出海助手-Notion

> 本技能改造自开源技能 notion（来源：openclaw/openclaw，openclaw 开源技能生态）。已完整保留原始运行文件（scripts/references/assets 与 LICENSE），并新增中文出海使用说明。原始英文说明见文末「English (Original)」与同目录 SKILL.original.md。

功能说明 / Functional Overview

用官方 ntn CLI 操作 Notion 工作区（页面、数据库 / 数据源、文件、Workers）。以 Markdown 为中心，也支持直接调 Notion REST API。

适用场景 / Use Cases

• 读取 / 创建 / 更新 / 归档 Notion 页面
• 查询数据库（按筛选、排序取数据）
• 上传文件、管理自动化 Workers

使用方法 / How to Use

• 安装与登录：npm install -g ntn → ntn login（脚本 / 无头用 NOTION_API_TOKEN + NOTION_API_VERSION=2026-03-11）
• 页面：ntn pages get <page-id>、ntn pages create --parent page:<id> --content '# 标题...'、ntn pages update <page-id> --content '# 更新'
• 数据源：ntn datasources resolve <db-id>、ntn datasources query <ds-id> --filter '{...}'
• 原始 API：ntn api v1/users/me、ntn api v1/search query=roadmap
• 无 ntn 时可用 curl 调 https://api.notion.com/v1/... 兜底

示例 / Examples

• ntn pages create --parent page:<id> --content '# 周报'
• ntn datasources query <ds-id> --filter '{"property":"Done","checkbox":{"equals":true}}'

限制说明 / Limitations

• 最新 API 版本 2026-03-11；归档用 in_trash 而非 archived。
• Workers 可能需要 Business/Enterprise 套餐且工作区已启用。
• 凭证（token）请通过环境变量注入，不要硬编码进脚本。

English (Original) / 英文原文（完整保留）

> The section below is the original skill definition, preserved verbatim for traceability and full functionality.

Notion

Prefer official ntn CLI. Use curl only when ntn is unavailable or a raw request is clearer.

Setup

npm install -g ntn
ntn --version
ntn login

Script/headless auth:

export NOTION_API_TOKEN=secret_or_ntn_token
export NOTION_API_VERSION=2026-03-11

ntn api sets Authorization and Notion-Version automatically. It uses CLI login by default, or NOTION_API_TOKEN when set.

Inspect

ntn doctor
ntn api ls
ntn api ls --json
ntn api v1/comments --help
ntn api v1/comments --spec -X POST
ntn api v1/comments --docs -X POST

Pages

Markdown-first helpers:

ntn pages get <page-id>
ntn pages get <page-id> --json
ntn pages create --parent page:<page-id> --content '# Title\n\nBody'
ntn pages create --parent data-source:<data-source-id> < page.md
ntn pages update <page-id> --content '# Updated'
ntn pages update <page-id> < page.md
ntn pages trash <page-id> --yes

Notes:

• pages get prints Markdown with page properties as frontmatter.
• Content input: --content, stdin, or editor in a TTY.
• Parent refs: page:<id>, database:<id>, data-source:<id>.
• For properties/templates/full Pages API, use ntn api v1/pages.

Data sources

ntn datasources resolve <database-id>
ntn datasources resolve <database-id> --json
ntn datasources query <data-source-id>
ntn datasources query <data-source-id> --limit 50 --json
ntn datasources query <data-source-id> --sort 'Date desc'
ntn datasources query <data-source-id> --filter '{"property":"Done","checkbox":{"equals":true}}'

Use resolve when you have a database ID. Query needs a data source ID.

Raw API

ntn api v1/users/me
ntn api v1/search query=roadmap page_size:=10
ntn api v1/pages 'parent[data_source_id]='"$DS_ID" 'properties[Name][title][0][text][content]=New item'
ntn api "v1/pages/$PAGE_ID" -X PATCH in_trash:=true
ntn api "v1/blocks/$PAGE_ID/children" -X PATCH \
  'children[0][type]=paragraph' \
  'children[0][paragraph][rich_text][0][text][content]=Hello'

Input syntax:

• path=value: string body field.
• path:=json: typed JSON body field.
• name==value: query parameter.
• Header:Value: request header.
• --data '<json>' or stdin JSON for larger bodies.
• Only one body source per request.

Files

ntn files create < image.png
ntn files create --filename photo.png --content-type image/png < /tmp/photo
ntn files create --external-url https://example.com/photo.png
ntn files get <upload-id>
ntn files list

Workers

ntn workers new
ntn workers deploy
ntn workers list --json
ntn workers runs list --json
ntn workers runs logs <run-id>

Workers may require Business/Enterprise plan and workspace enablement.

Curl fallback

curl -sS "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json"

Version notes

• Current latest API version: 2026-03-11.
• Use in_trash, not archived.
• Append block positioning uses position, not flat after.
• transcription block renamed to meeting_notes.
• Databases can contain multiple data sources; page parents generally use data_source_id.