Notion 协作与知识库平台 Skill
Notion API 最容易卡住人的一步不是鉴权本身，而是"token 合法但没把页面共享给集成"——这时返回的是看起来像 ID 抄错的 404 object_not_found，而不是权限错误的 403。另一个训练记忆最容易过时的地方是 2025-09-03 的破坏性变更：database 和 data source 拆成了两个对象，database_id 和 data_source_id 不能互换，几乎所有读写数据行的操作现在都要用后者。
ntn_/secret_ 前缀）+ 必须在 UI 里把页面共享给集成Agent 工具更新 2026-09-21安装
选你用的 Agent，复制命令。
npx -y skills add fxp/skillify --skill notion --agent claude-code --yes装到项目的 .claude/skills/；加 -g 装到全局。装完需要你手动执行 /reload-plugins，这一步 Agent 代劳不了。
npx -y skills add fxp/skillify --skill notion --agent codex --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill notion --agent cursor --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill notion --agent opencode --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill notion --agent gemini-cli --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill notion --agent github-copilot --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill notion --agent trae --yes装到项目的 .trae/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill notion --agent windsurf --yes装到项目的 .windsurf/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill notion --agent qwen-code --yes把 --agent 换成你用的 Agent 标识，可以一次写多个。skills CLI 1.5.25 共支持 79 个，例如 qwen-code、kimi-code-cli、trae-cn、qoder、lingma、cline、roo。
或者让 Agent 自己装
读 https://github.com/fxp/skillify/blob/main/skills/notion/prompt.md 并照它执行装对了的标志：references/ 下有 6 份文档。
装好后，可以这样问你的 Agent
这份 Skill 覆盖的典型任务。点一下复制。
6 类能力
每类能力对应一份 reference，Agent 按任务只打开需要的那份。
鉴权与共享
三种鉴权方式怎么选、必须共享页面给集成的坑、connection capabilities
数据库与数据源
database/data source 双层模型、发现流程、查询过滤排序、relation 读写不对称
页面与区块
页面 CRUD、属性值按类型分叉、区块树读写、Enhanced Markdown 便捷层
富文本
富文本对象数组格式、annotations 样式、mention 三种类型、大小限制
Search
按标题搜索已共享内容、2025-09-03 起结果变成 data_source、索引延迟的例外规则
错误与限流
Notion-Version 版本机制、错误码表（401 vs 404 的区别）、Free 工作区区块上限、限流、SDK
当前事实
整理自官方文档（抓取于 2026-09-21），还没有用真实凭证验证。
| 项 | 值 |
|---|---|
| Base URL | https://api.notion.com/v1/，每个请求必须带 Notion-Version 头，缺失直接 400 |
| 鉴权 | Authorization: Bearer <TOKEN>，新 token 前缀 ntn_，旧的 secret_ 同样有效 |
| 必须共享 | Internal/Public connection 必须在 Notion UI 里手动 Add connections，PAT 例外，直接继承创建者权限 |
| database vs data source | 2025-09-03 起两者是不同对象，创建页面/查询/relation 现在都要用 data_source_id，不是 database_id |
| 富文本 | 标题、rich_text 属性、多数区块文字都是对象数组，不是字符串，写入需构造完整 annotations |
| 限流 | 普通计划 180 次/分钟，Business/Enterprise 600 次/分钟（单连接维度），429 读 Retry-After |
照通用经验写容易错的 6 件事
来自官方文档，还没有用真实凭证验证。
- "token 有效"和"集成能看到这个页面"是两回事，而且失败模式是 404 不是 403。Internal/Public connection 必须在 UI 里对每个顶层页面/数据库手动 Add connections；PAT 是例外，直接继承创建者本人权限，不需要这步。遇到"ID 明明是对的却 404"，第一反应应该是检查共享状态。
- 2025-09-03 起 database 和 data source 是两个不同对象，ID 不能互换。一个 database 下可以挂多个 data source，几乎所有"读写数据库行"的操作（parent、查询、relation）现在都要用
data_source_id，先GET /v1/databases/{id}拿到data_sources[]再往下走。 - 页面属性(properties)和内容(content)是两套完全独立的数据和 API。改标题走
PATCH /v1/pages/{id}的properties，改正文走区块级 API 或 markdown 便捷层，"更新页面文本"从来不是一次简单的字段写入。 - 富文本从来不是字符串，是对象数组。标题、
rich_text属性值、大多数区块文字都要传完整的{text: {content}, annotations}数组，"title": "string" 这种简化写法从未被 API 接受过。 Notion-Version缺失会硬报 400，但传旧版本不会提醒你。省略这个头直接报错（相对友好），但传了一个过旧但合法的版本号会静默沿用旧版的字段形状，不会主动提示有新版本可升级——升级要主动做。- Free 工作区有 1000 个区块的生命周期硬上限，触发后是 403 不是 429。这不是限流，重试没用，必须升级付费计划；触及上限后有 3 天宽限期，之后所有会创建新区块的写操作失败，但读/删除仍可用；PAT 和面向所有工作区开放的 public connection 不受此限制。