技能介绍

要解决的问题

很多团队把项目文档、产品路线图、Bug 跟踪表都放在 Notion 里，但这些内容被锁在 Notion 的编辑器里。自动化脚本想读某个数据库的最新记录、按状态筛选任务，或者在 CI 流程里把构建结果写回 Notion 时，往往要在内部 API、第三方集成和 Webhook 之间反复权衡。这个技能的目标是把「操作 Notion 工作区」变成 Agent 可以直接调用的一组明确能力，让大模型能像调用函数一样查询和修改工作区内容。

核心能力与工作方式

这个技能的能力底座是 Notion 官方 SDK（@notionhq/client），它把 Notion HTTP API 封装成 JavaScript 客户端。技能本身做两件事：一是为 Agent 提供调用 Notion API endpoint 的通道；二是按 SDK 的使用约定，把常见操作整理成技能可执行的步骤。

典型的工作流大致是：

初始化客户端：通过 Client 构造函数传入认证信息，SDK 会处理请求签名和版本头。
读写页面：用 pages.retrieve 与 pages.update 获取或修改页面属性，包括标题和 properties 等结构化字段。
查询数据库：通过 databases.query 按过滤器检索记录，再对结果做聚合或批量更新。
错误处理：SDK 暴露 APIErrorCode，调用方可以针对限流、权限不足等错误码做重试或降级。
日志控制：通过 LogLevel 调整 SDK 的日志输出级别，方便在 Agent 运行环境里排查问题。

适用边界与注意点

能力上限取决于 Notion API：技能没有额外封装 Notion 本身不支持的操作，级联删除、跨工作区查询等行为仍受平台限制。
认证与权限：调用方需要自备 Notion integration token，并为相关页面或数据库授予访问权限，否则会收到鉴权类错误。
内容相对上游文档较薄：技能文件的大部分说明直接提取自 Notion SDK 官方 README，本质是对 SDK 能力的重新组织，而不是一套独立的新实现。
Agent 上下文成本：Notion 返回的对象 JSON 可能较大，接入 Agent 时通常需要裁剪字段，避免把整棵页面树塞进上下文。