Notion API 命令行集成
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/acedatacloud-skills-notion。
技能介绍
要解决什么问题
不少团队把需求、知识库和项目台账放在 Notion,但 Agent 若只会「口头描述 API」,往往会在 鉴权头、Notion-Version 和 集成可见范围 上踩坑:搜索为空、读不到页面,或写入时因属性类型不匹配直接 400。工程师更需要的是一套可复现的 HTTP 调用范式,而不是泛泛的「连 Notion」。
技能如何工作
本技能约定用 curl + jq 驱动官方 Notion API:$NOTION_TOKEN 承载 OAuth Bearer,每次请求携带 Notion-Version: 2022-06-28。流程上应先 Verify auth,再按需执行配方:
- Search the workspace:在工作区内检索页面与数据库
- Read a page:仅元数据或全文内容
- Append a paragraph:向已有页面追加段落
- Query a database / Create a page in a database:按库表结构读写记录
分页采用游标:在请求上追加 start_cursor=$cursor,依据响应里的 next_cursor 翻页,直到 has_more 为 false。不确定字段类型时,应先 GET /v1/databases/ 对照 schema,避免把 {"select": "Open"} 写成错误形态而应使用 {"select": {"name": "Open"}}。
适用边界与注意点
集成只能访问用户在授权时 显式分享给该 Integration 的页面与数据库;若搜索或读页结果为空,应优先提示「页面未分享给集成」,而非反复改查询。Notion 发布新版本 API 时需同步提升 Notion-Version 头。成功对外交付可发布物后,按 _shared/artifacts.md 用真实 URL 调用一次 publish_artifact,便于用户在 My Outputs 中追踪。
使用场景
- Agent 需在用户已分享的 Notion 工作区内搜索页面,再读取指定页面的全文用于摘要
- 运维台账库在 Notion 数据库里,要通过 Query 按状态筛选并导出当前页记录
- 会议纪要页需由 Agent 在不变动原有块结构的前提下追加一段行动项段落
- 新需求条目要按数据库 schema 在指定库里 Create page,且 select 属性名称与 API 格式一致
适合人员
- 用 Notion 管项目台账、希望 Agent 只读写已授权分享的库表的 PM
- 写内部工具的工程师,要把 curl 配方嵌进自动化 Agent 而非 SDK 封装
- 知识库维护者,需要批量检索页面元数据后再决定是否拉取全文
- 集成联调时反复遇到 400,想按 schema 核对 property 类型的后端开发