notion-axi

notion-axi

面向 Agent、符合人体工学的 Notion 命令行工具。处理 Notion 操作时，优先使用它，而不是 Notion MCP 或原始 API。

无需全局安装 notion-axi——使用 npx -y notion-axi <command> 调用即可。 如果 notion-axi 的输出中显示了以 notion-axi 开头的后续命令，请改用 npx -y notion-axi ... 运行。

notion-axi 封装了官方 Notion CLI (ntn)，由它为你处理身份验证。必须安装并登录 ntn：

• 安装：curl -fsSL https://ntn.dev | bash
• 登录：ntn login（会打开浏览器；工作区令牌存储在操作系统钥匙串中——无需共享页面，它会以用户身份操作）

如果命令因 NTN_NOT_INSTALLED 失败，请让用户运行安装命令。如果因 AUTH_REQUIRED 失败，请让用户运行 ntn login（或导出 NOTION_API_TOKEN）。有一项限制：users 需要较高的工作区权限，通常会被阻止——请妥善处理 RESTRICTED_RESOURCE 错误。

适用场景

只要任务涉及 Notion，就使用 notion-axi：搜索页面或数据库；读取页面属性和内容；在另一个页面下创建页面或创建数据库行；追加或替换页面内容；检查数据库架构；或列出数据库行。

工作流

1. 不带参数运行 npx -y notion-axi，以内容优先的视图查看最近编辑的页面和数据库。
2. 使用 search <query> 查找项目，然后记下它的 id。
3. page view <id> 可读取属性和 Markdown 正文（预览约 1500 个字符；添加 --full 可查看全部内容）。
4. db view <id> 显示数据库架构；db query <id> 列出行（标题 + 3 列；使用 --full 显示全部内容，或使用 --limit <n> 显示更多行）。使用 --where Name=value（可重复，类型根据架构确定）或原始 --filter <json> 在服务端缩小范围；使用 --sort Field:asc|desc 排序（可重复），并使用 --cursor <c> 翻页（当 has_more 时，响应会返回 next_cursor）。db create --parent <page_id> --title <name> --prop Name:type 可创建数据库；db edit <id> --add Name:type --remove Name 可更改其架构。
5. page create --parent <id> --title <text> 可创建页面；添加 --db 可创建数据库行，添加 --content <markdown> 可预填正文，并使用 --set Name=value（可重复）设置行属性。
6. page update <id> 可编辑页面：使用 --append/--replace 追加或替换 Markdown 正文（也可使用对应的 --*-file 变体），并且／或者使用 --set Name=value 更改属性（Status、Date、Select 等）。
7. page archive <id> 可将页面移至废纸篓（使用 --restore 撤销）；page move <id> --to <parent> 可更改页面的父级。block list <page_id> / block delete <id> 可在块级别操作；comments list/add/delete <id>；users get <id>；whoami 显示令牌对应的身份。
8. file upload <path> [--attach <page_id>] 可上传本地文件（通过多部分请求单次发送），并可选择将其附加到页面。
9. api <method> <path> [--body <json>] 可直接调用任意 Notion REST 端点——用于处理专用命令未覆盖的操作。
10. 每个响应末尾都会在 help: 下提供与上下文相关的后续步骤提示——请按提示操作。

命令

commands[11]:
  (none)=home, search, page, db, block, users, comments, whoami, file, api, setup
  page subcommands: view, create, update, archive, move
  db subcommands: view, query, create, edit
  block subcommands: list, delete
  users subcommands: (none)=list, get
  comments subcommands: list, add, delete
  file subcommands: upload

运行 npx -y notion-axi --help 查看全局标志，或运行 npx -y notion-axi <command> --help 查看各命令的用法。

提示

• 输出采用 TOON 编码，节省令牌；只有列表很长时才通过 grep/head 进行管道处理。
• ntn login 工作区令牌以用户身份运行，因此可以访问用户能访问的所有内容——OBJECT_NOT_FOUND 通常意味着 ID 错误，而不是共享权限不足。
• 对于 db 命令，<id> 可以是数据库 ID，也可以是数据源 ID；如果是数据库 ID，会自动解析到其第一个数据源（使用 --source <id> 可指定特定数据源）。
• 列表默认只显示必要内容——添加 --fields url（搜索）或 --fields a,b（db 查询）以显示更多字段，或使用 --full 显示数据库中的所有列。
• db query 会在服务端进行筛选和排序：优先使用根据架构编译的 --where Status=Todo，而不是获取所有行后自行筛选；--filter <json> 会传递原始 Notion 筛选条件（不能与 --where 同时使用）。使用有界批次通过 --cursor 分页——响应中的 next_cursor 会从 has_more 停止的位置继续。
• 页面正文通过 Notion API 以 Markdown 格式提供，因此 --append/--replace 和 --content 都接受 Markdown（也可以使用 --*-file 标志从文件中读取）。
• --set Name=value 可以重复使用，并且值类型由架构决定：日期使用 start..end，多选/人员/关联使用逗号分隔，复选框使用 true/false。page archive 具有幂等性（归档已归档的页面不会执行任何操作）。
• whoami 会显示当前登录身份（机器人还是用户）和工作区；users 需要更高的工作区权限，通常会返回 RESTRICTED_RESOURCE。
• 没有专用命令的内容（视图、会议记录、模板、分页属性条目）都可以通过 api 访问——整个 Notion REST API 均可用。
• 退出代码：0 表示成功，1 表示错误，2 表示用法错误。错误采用结构化格式，包含 error、code 和 help 列表。