notion

Notion 操作

使用此技能通过 Notion API 读取 Notion 内容，并在获得明确确认后写入内容：包括页面、数据库查询、搜索和页面属性更新。这是用于 Notion 平台的工具技能。构建 Notion 集成、编写复杂的块组合或基于 Notion API 构建应用属于应用开发；此技能负责日常的 Agent 工作流：找到正确的页面、从数据库中获取答案，以及执行已确认的编辑。

操作约定

1. 任何修改前先进行只读查找。 可自由检索页面、查询数据库和搜索。随附的 notion-cli 脚本只读，不会写入任何内容。
2. 执行操作前确认目标、范围和回滚方式。 创建页面或更新属性会修改团队成员共同阅读的工作区。两者都需要明确的人工指令，并通过 notion-cli 使用 --dry-run 预览，再用 --yes 确认。属性更新会覆盖现有值——确认前说明当前值和替换后的值。
3. 遵守读取范围限制。 Notion 使用 page_size 和 has_more 进行分页；只翻页到任务所需的范围。notion-cli --limit 会限制每次搜索和查询的结果数量。
4. 提供有限的依据。 引用简短的页面标题、属性值和 ID；切勿在聊天中粘贴完整页面、令牌或原始 API 载荷。
5. 了解 API 版本。 Notion-Version 标头固定了 API 契约；当前可用的读取方式可能会随版本升级而变化。notion-cli 默认发送 2022-06-28，并遵循 NOTION_VERSION。

notion-cli 脚本

scripts/notion-cli 是一个面向 Agent、仅使用标准库的 Notion API 命令行工具。它涵盖所有相关操作：页面、数据库（查询）、搜索和更新。

notion/scripts/notion-cli --help                           # no token or network needed
notion/scripts/notion-cli --json pages get --page-id <page>
# Read only properties you plan to change; absent names are marked explicitly
notion/scripts/notion-cli --json pages get --page-id <page> --property Status --property Reviewer
notion/scripts/notion-cli --json --limit 10 databases query --database-id <db>
notion/scripts/notion-cli --json search query --query "on-call runbook"
notion/scripts/notion-cli pages update --page-id <page> --properties props.json --dry-run
notion/scripts/notion-cli pages update --page-id <page> --properties props.json --yes
notion/scripts/notion-cli pages create --parent-database <db> --title "New row" --yes

退出代码：0 表示成功，1 表示 API 错误或检查失败，2 表示用法错误。创建和更新操作均受保护：未指定 --dry-run 或 --yes 时，脚本会以退出代码 1 拒绝操作，且绝不会调用 API。读取结果受 --limit 限制（默认值为 20，最大值为 100）。

操作流程

1. 定位内容：使用 search query 按文本查找页面和数据库，或直接使用已知 ID。
2. 在范围内读取：使用 pages get 读取单个页面，使用 databases query 读取数据库中的行（可选使用 JSON --filter），并始终通过 --limit 限制结果数量。
3. 梳理答案：将问题对应到依据（页面标题和属性、数据库行、带有 has_more 状态的搜索结果）。
4. 确认后操作：仅在收到人工修改指令后执行；先用 --dry-run 预览，再用 --yes 确认。
5. 验证：重新读取页面（pages get），确认属性值已更新。

页面、数据库和搜索

• 页面（GET /pages/{id}）：页面包含 ID、标题（从 title 或 Name 属性提取）、URL、时间戳和带类型的属性摘要。JSON 输出包含每个属性的类型、值和完整性；可重复使用 --property NAME 选择属性，并将请求但不存在的属性标记为 present: false。人类可读的输出会将不完整的属性标记为 <incomplete: reason>。长文本还会包含截断标记和原始字符数，避免被误认为是已验证的完整值。
• 数据库（POST /databases/{id}/query）：将查询结果作为页面返回，并通过 page_size 限制数量；也可选择使用结构化的 --filter JSON 文件（例如 {"property": "Status", "select": {"equals": "Done"}}）。has_more 会告知你是否有更多行被数量上限隐藏。
• 搜索（POST /search）：按文本在集成可访问的工作区中查找页面和数据库；结果数量受 --limit 限制。
• 更新（PATCH /pages/{id}）：属性更新会覆盖现有值（select、status、checkbox、rich text 等）。使用 --dry-run 预览确切的属性载荷，再用 --yes 确认；之后通过 pages get 再次读取并验证。

集成访问模型

• Notion 集成使用 bot 风格的令牌（secret_...）进行身份验证，并且只能查看明确共享给集成的页面和数据库。工作区中存在但未共享的页面会返回 404/object_not_found——这是访问模型导致的结果，并不代表页面不存在。
• Notion-Version 请求头用于选择 API 契约。CLI 默认使用 2022-06-28；如果工作区或应用固定使用其他版本，请设置 NOTION_VERSION。
• 令牌是工作区范围的凭据。请将其存储在环境中（NOTION_TOKEN），切勿放入代码、聊天内容或提交中。如果集成令牌泄露，请在 Notion 集成设置中将其撤销。

参考资料索引

加载时机	参考资料
来源、版本说明、刷新流程	references/00-source-index.md
API 端点、分页、属性类型、筛选条件和错误处理	references/01-api-operations.md

附带内容

• scripts/notion-cli：功能范围受限、仅使用标准库的 CLI（获取/创建/更新页面、查询数据库、搜索；--json；--limit；通过 --dry-run/--yes 限制修改操作）。
• tests/test_notion_cli.py：针对 Notion API 存根的 21 个确定性测试，包括类型化属性读取、明确的缺失/截断状态、分页失败、修改操作门控以及只读契约。
• references/：带日期的来源索引和 API 操作参考资料。
• evals/evals.json：用于评估 Agent 运行输出质量的 6 个案例。

验证边界

声明	最低证据要求
页面存在且标题正确	notion-cli pages get --page-id ... --json 返回标题和 ID
数据库查询已回答问题	notion-cli databases query --json 返回有界行，并包含 has_more 状态
搜索找到了内容	notion-cli search query --json 返回匹配的页面/数据库及其 ID 和标题
更新已生效	notion-cli pages update --yes 以状态码 0 退出，且后续执行 pages get --property NAME 会显示每个已更改属性的类型化值；请将其与请求的值进行比较
修改操作可以安全执行	notion-cli ... --dry-run 会打印即将发送的确切负载

严格限制

• 未经人工指示、--dry-run 预览和 --yes 确认，绝不创建或更新页面——所有有权限访问页面的人都能看到 Notion 编辑内容。
• 如果页面可能只是未共享给集成，绝不声称页面不存在；请先核实访问模型。
• 绝不读取超过 --limit 的页面；绝不将完整页面、令牌或原始负载输出到聊天中。
• 此技能用于操作 Notion API，不用于构建 Notion 集成（应用开发），也不涵盖其他知识库产品。

不适用场景

• 构建 Notion 集成或应用（OAuth 流程、自定义区块、公共 API 产品、超出属性更新范围的区块树组合）——这属于应用开发；服务设计请参阅 backend-engineering。
• 其他知识库和文档工具（Confluence、Google Docs、Wiki）——它们各自有专用工具；此技能仅涵盖 Notion。
• 工作区管理（用户管理、工作区设置、集成审批）——请使用 Notion 管理控制台。