agent-notion

使用 agent-notion 自动化 Notion

agent-notion 是一个安装在 $PATH 上的 CLI 二进制文件。直接调用它（例如 agent-notion search query "Project Plan"）。

输出为 NDJSON——stdout 上每行一条 JSON 记录。列表命令会为每个项目打印一条记录；如果还有更多结果，则最后会附加一行 {"@pagination": {...}}（或 {"@meta": ...} / {"@total": n}）。传入 --format json|yaml 可改为输出单个美化后的 { "data": [ … ] } 封装对象；默认的 --format jsonl 为 NDJSON。

错误会以 { "error": "...", "fixable_by": "agent|human|retry", "hint": "..." } 的形式输出到 stderr，退出码为 1。不会打印令牌。

后端

支持两种 API 后端：官方 REST API（集成令牌、OAuth）和 v3 桌面会话 API（auth import-desktop/import-browser）。--backend auto（默认值）优先使用已存储的 v3 会话，否则使用官方凭据。使用 --backend official 或 --backend v3 可强制指定后端。以下命令需要 v3 会话：export、page backlinks、page history、activity log、page archive/unarchive、block move、comment inline 和所有 ai 命令。

快速开始（身份验证）

选项 A：OAuth（推荐，可完整访问官方 API）

agent-notion auth setup-oauth --client-id <id> --client-secret <secret>
agent-notion auth login                        # opens the browser for the OAuth flow
agent-notion auth status

选项 B：内部集成令牌

通过 stdin 传入令牌，避免机密出现在 argv、Shell 历史记录或任何 Agent 对话记录中：

printf '%s' "$NOTION_TOKEN" | agent-notion auth import   # token read from stdin
agent-notion auth status

在存储令牌之前，会先使用 API 对其进行验证；别名根据工作区名称生成（可使用 --alias 覆盖）。

切勿自行将令牌粘贴到 --token 中。 如果用户在聊天中粘贴了他们的 ntn_…/secret_… 集成令牌，不要将其放入 --token——机密会进入你的上下文窗口、对话记录以及任何下游遥测数据。应指导用户自行运行导入命令（如上所示，通过 stdin 传入，或在自己的终端中使用 --token），以确保机密不会进入大模型。对于交互式人工设置，优先使用 OAuth（选项 A）或桌面/浏览器会话（选项 C），这样原始令牌完全不会经过 Agent。

选项 C：桌面会话（用于 v3 功能）

agent-notion auth import-desktop                       # reads token_v2 from the Notion Desktop app
agent-notion auth import-browser chrome                # or from a browser cookie store

import-browser 支持：chrome、brave、edge、arc、chromium、firefox、zen、safari（使用 --profile <p> 选择配置文件）。

支持多个工作区：

agent-notion auth login --alias work
agent-notion auth workspace list
agent-notion auth workspace switch <alias>
agent-notion auth workspace remove <alias> --yes       # destructive: needs --yes
agent-notion auth logout --yes                          # default workspace; --all wipes everything

搜索

重要：Notion 搜索仅限标题。 它不会搜索页面内容、评论或属性值。若要搜索内容，请使用带属性筛选器的 database query <id>，或使用 block list <page-id> 并对输出进行 grep。

agent-notion search query "meeting notes"
agent-notion search query "Q1 Plan" --filter database
agent-notion search query "design doc" --filter page --limit 5

每条命中结果都是一条 NDJSON 记录 {id, type, title, url, parent?, last_edited_at?}；如果还有更多结果，末尾会出现一行 {"@pagination": {has_more, next_cursor}}（通过 --cursor 传回 next_cursor）。

数据库

agent-notion database list                                          # via the search API
agent-notion database get <database-id>                             # full metadata + property definitions
agent-notion database schema <database-id>                          # compact schema (types, options) for LLMs
agent-notion database query <database-id>                           # rows (one NDJSON record each)
agent-notion database query <id> --filter '{"property":"Status","status":{"equals":"Done"}}'
agent-notion database query <id> --sort '[{"property":"Name","direction":"ascending"}]'

构建筛选器之前，请使用 database schema 查看属性名称、类型以及有效的 select/status 选项。

结果顺序： 未指定 --sort 时，行会按视图自身的顺序返回（通常是手动排序），而不是按最新优先排序——新添加的行可能排在最后，因此 --limit 会悄然将其排除，让人误以为该行不存在。若要获取“最新的 N 条”，请始终按时间戳排序：--sort '[{"timestamp":"last_edited_time","direction":"descending"}]'。检查 {"@pagination": {has_more, next_cursor}} 末尾记录，以区分结果被截断和“没有更多行”。

即使页面的 parent.id（其数据库 ID）与用于打开数据库视图的 ID 不同，database get/query/schema 也接受该值——你可以获取某行的 parent，并直接查询其数据库。

页面

agent-notion page get <page-id>                                     # properties only
agent-notion page get <page-id> --content                           # properties + markdown content
agent-notion page get <page-id> --raw-content                       # properties + structured block objects
agent-notion page create --parent <id> --title "New Page"           # auto-detects database vs page parent
agent-notion page create --parent <db-id> --title "Task" --properties '{"Status":"In Progress","Priority":"High"}'
agent-notion page create --parent <id> --title "Notes" --icon "📝"
agent-notion page update <page-id> --title "Updated Title"          # at least one of --title/--properties/--icon
agent-notion page update <page-id> --properties '{"Status":"Done"}' --icon "✅"
agent-notion page trash <page-id> --yes                             # move to Trash (recoverable; destructive)
agent-notion page restore <page-id>                                 # restore from Trash
agent-notion page archive <page-id> --yes                           # real Archive (v3-only; destructive)
agent-notion page unarchive <page-id>                               # undo real Archive (v3-only)

归档和回收站是 Notion 中相互独立的状态。移至回收站会将 alive=false，所有后端均支持此操作；归档会让页面不出现在搜索结果中，但页面仍处于存活状态，且需要 v3 后端。页面可以处于其中一种、两种，或两种状态都不处于。

--content/--raw-content 会添加 block_count 和 content_truncated（当页面的块数超过 1000 时为 true）。--properties 中的属性值会自动转换：字符串会转换为选择值，数字会转换为数字属性，布尔值会转换为复选框，数组会转换为多选值；复杂类型请传入 Notion API 格式。

块（页面内容）

agent-notion block list <page-id>                                   # markdown (default): {page_id, content, block_count, has_more}
agent-notion block list <page-id> --raw                             # one NDJSON record per block {id, type, content, has_children}
agent-notion block append <page-id> --content "## New Section\n\nParagraph text"
agent-notion block append <page-id> --blocks '[{"type":"paragraph","paragraph":{"rich_text":[{"text":{"content":"Hello"}}]}}]'
agent-notion block update <block-id> --content "New text"           # replace a single block's text
agent-notion block delete <block-id> --yes                          # destructive: needs --yes
agent-notion block move <block-id> --after <other-block-id>         # reorder (v3)
agent-notion block move <block-id> --parent <callout-id>            # move into a container (v3)
agent-notion block replace <page-id> --content "# Fresh\n\nAll new" --yes   # delete all blocks, then append (destructive)

Markdown 转换支持标题、列表、待办事项、代码围栏、引用块、标注块、图片、分隔线和表格（渲染为 GitHub 风格的管道表格，首行为表头；--raw 的 table_row 记录会带有 cells 数组）。使用 block list --raw 获取用于 update/delete 的块 ID。block replace 会先删除所有现有块再追加内容，因此需要 --yes。

评论

agent-notion comment list <page-id>
agent-notion comment page <page-id> "This looks good!"
agent-notion comment inline <block-id> "Great point!" --text "target phrase"       # v3
agent-notion comment inline <block-id> "Second one" --text "the" --occurrence 2    # v3

comment list 会为每条评论输出一条 NDJSON 记录 {id, body, author: {id, name}, created_at}。comment page 返回 {id, discussion_id, body, created_at}；comment inline 会添加 anchor_text，且需要 v3 桌面会话。不支持讨论串（所有评论均为顶级评论）；API 无法编辑或删除评论。

v3 功能（需要 auth import-desktop）

导出

agent-notion export page <page-id>                             # export as a markdown zip
agent-notion export page <page-id> --format html --recursive   # export the page tree as HTML
agent-notion export workspace                                  # export the entire workspace
agent-notion export workspace --output my-backup.zip           # custom output path
agent-notion export poll <task-id> --output backup.zip         # resume a timed-out export

选项：--format markdown|html、--recursive（仅页面）、--output <path>、--wait <seconds>（页面默认 120，工作区/轮询默认 600）。导出为异步操作；CLI 会轮询直至完成或达到 --wait 超时，然后打印任务 ID，以便使用 export poll 继续操作。进度会写入 stderr。输出：{exported, format, pages_exported, recursive?}，其中 exported 是 zip 文件的绝对路径。

反向链接

agent-notion page backlinks <page-id>                          # pages linking to this page (v3)

每个源页面输出一条 NDJSON 记录 {block_id, page_id, page_title}（按页面去重），最后输出 {"@total": n}。

历史记录

agent-notion page history <page-id>                            # version snapshots (v3)
agent-notion page history <page-id> --limit 50

每个快照输出一条 NDJSON 记录 {id, version, last_version, timestamp, authors}，最后输出 {"@total": n}。

活动记录

agent-notion activity log                                      # workspace-wide activity (v3)
agent-notion activity log --page <page-id>                     # scoped to a page
agent-notion activity log --limit 50

每条活动输出一条 NDJSON 记录 {id, type, page_id, page_title, authors, edit_types, start_time, end_time}。

Notion AI（需要 auth import-desktop）

agent-notion ai model list                                         # active models (name, family, tier)
agent-notion ai model list --raw                                   # full model objects incl. codenames
agent-notion ai chat list [--limit 10]                             # recent threads
agent-notion ai chat get <thread-id>                               # thread messages
agent-notion ai chat send "Summarize my recent projects"           # new conversation
agent-notion ai chat send "Tell me more" --thread <id>             # continue a thread
agent-notion ai chat send "Explain this page" --page <page-id>     # with page context
agent-notion ai chat send "Summarize this" --page <page-id> --read-only  # ask/answer only, no edits
agent-notion ai chat send "Quick question" --stream                # stream response text to stderr
agent-notion ai chat send "Hello" --model "GPT-5.2"                # specific model
agent-notion ai chat mark-read <thread-id>

ai chat send 返回 {thread_id, response, title, model, tokens: {input, output, cached}}。模型解析优先级：--model 标志 > 配置项 ai.default_model > API 默认值；支持代号（例如 oatmeal-cookie）或显示名称。使用 --stream 时，响应文本会流式输出到 stderr，而 JSON 结果仍会输出到 stdout。

默认情况下，AI 拥有文档编辑工具（与 Notion 相同），因此提示词可以修改页面。传入 --read-only 可请求问答模式——它会要求 Notion 后端禁用这些工具（这是服务端请求，并非由客户端强制保证）。

用户

agent-notion user list                                              # one NDJSON record per user {id, name, type, email?, avatar_url?}
agent-notion user me                                                # bot identity {id, name, type, workspace_name}

type 为 person 或 bot；只有 person 用户才会包含 email。

截断

名为 description、body 和 content 的字段默认会截断为 200 个字符。配套的 {field}Length 字段（例如 descriptionLength）始终记录完整的码点数，因此 Agent 可以判断内容是否被截断。提高上限或展开字段：

agent-notion --full page get <page-id>                              # expand every truncatable field
agent-notion --expand description database get <id>                 # expand one field
agent-notion --expand description,content page get <id> --content   # expand several
agent-notion config set truncation.max_length 500                   # raise the default cap

--expand/--full 是全局标志（可放在命令前面或后面）。

全局标志

• --backend auto|official|v3 — 选择 API 后端（默认 auto）
• --format json|yaml|jsonl — json/yaml 会将输出封装在一个格式化的 {data: […]} 对象中；jsonl 是默认的 NDJSON 格式
• --expand <fields> / --full — 取消字段截断
• --color auto|always|never、--timeout <ms>、--debug、--version

ID

命令接受带连字符或不带连字符的 Notion UUID（URL 中不带连字符的 ID 会自动规范化）：

• a1b2c3d4-1111-2222-3333-444444444444
• a1b2c3d411112222333344444444444444

分页

列表命令会流式输出 NDJSON 记录；如果还有更多结果，则会在末尾输出 {"@pagination": {has_more, next_cursor}}。传入 --limit <n>（最大值为 100）和 --cursor <token> 可进行分页。在 --format json|yaml 模式下，记录和分页信息会合并到一个 {data: […], "@pagination": …} 封装中。

具有破坏性的命令（需要 --yes）

page trash、page archive、block delete、block replace、auth logout 和 auth workspace remove 会更改状态，未传入 --yes 时将拒绝运行；未传入时，这些命令会返回一条 fixable_by: human 错误，说明将会发生什么。page restore 和 page unarchive 不受此限制。

各命令的用法文档

每个命令组都有一个 usage 子命令，提供经过 LLM 优化的详细文档：

agent-notion usage                # top-level overview
agent-notion search usage
agent-notion database usage
agent-notion page usage
agent-notion block usage
agent-notion comment usage
agent-notion export usage
agent-notion activity usage
agent-notion ai usage
agent-notion user usage
agent-notion auth usage
agent-notion config usage

在执行操作前需要深入了解某个领域时，运行 agent-notion <group> usage。

配置

agent-notion config list                                            # every key with value + description
agent-notion config get <key>                                       # one setting {key, value, set}
agent-notion config set truncation.max_length 500                   # raise the truncation cap
agent-notion config set page_size 20                                # default results per list command (1-100)
agent-notion config set ai.default_model <codename>                 # default AI model
agent-notion config unset <key>                                     # reset one key to its default

配置项：page_size、max_depth、truncation.max_length、ai.default_model。设置会保存在 ~/.config/agent-notion/config.json 中。

参考文档

• references/commands.md：完整的命令映射及所有标志
• references/output.md：NDJSON 输出结构及字段详情