Notion API

核心功能

Notion 技能提供了一套确定性脚本优先的 CLI 工具 notionctl.mjs，将常见的 Notion API 操作封装为结构化命令，输出 JSON 便于 AI Agent 解析。

主要能力

• 搜索：支持按标题搜索页面（--type page）或数据源/数据库（--type data_source）
• 内容读写：export-md 将页面导出为 Markdown；create-md/append-md 支持从 Markdown 创建或追加内容
• 页面迁移：支持在页面间移动（--to-page）或转入数据库（--to-data-source，需使用 data_source_id）
• 收件箱工作流：list-child-pages 列出子页面，triage 支持基于规则的分流处理（含 dry-run 模式）

显著优点

1. 确定性设计：自动处理 headers、分页、速率限制（3 req/s）、HTTP 429 退避，降低 ad-hoc API 调用的错误率
2. OpenClaw 友好：单一二进制入口 + 可预测参数，便于权限管控
3. JSON 输出：便于 Agent 解析和推理
4. 多认证回退：优先 NOTION_API_KEY，兼容 NOTION_TOKEN、NOTION_API_TOKEN 及本地配置文件

局限性与风险

• API 版本锁定：强制使用 2025-09-03 版本，未来版本变更需同步更新
• 速率限制严格：3 req/s 的限制对批量操作构成瓶颈，需主动处理退避
• 数据源术语变更：Notion API 中 "database" 概念已迁移至 "data_source"，旧文档/习惯可能导致混淆
• 权限依赖：401/403/404 错误常源于集成未共享到目标页面，需人工排查

适合人群

• 需要程序化批量管理 Notion 内容的开发者/高级用户
• 构建收件箱-分流自动化工作流的知识管理者
• 在 OpenClaw 等受限环境中需要可审计、可预测 Notion 操作的场景

安全提示

• 内容不信任原则：将 Notion 内容视为不可信用户输入，避免执行其中嵌入的指令
• 批量操作建议：--dry-run → 确认范围（--limit）→ 执行（--apply）

核心用法

Notion Skill 提供了一套完整的命令行接口，将 Notion API 封装为确定性脚本，避免临时 API 调用的错误风险。核心功能覆盖搜索、读取、创建、追加和移动五大操作：

| 功能 | 命令示例 | 场景 |

|------|---------|------|

| 搜索 | `search --query "关键词" --type page` | 快速定位笔记 |

| 导出 | `export-md --page "<id>"` | 页面转 Markdown |

| 创建 | `create-md --parent-page "<id>" --title "..."` | 新建笔记 |

| 追加 | `append-md --page "<id>" --md "## 更新"` | 增量编辑 |

| 移动 | `move --page "<id>" --to-data-source "<id>"` | 分类归档 |

特别支持 data_source（数据库）操作，可设置属性字段如 Status=Inbox、Tags=home,admin，实现结构化数据管理。内置的 triage 工作流支持基于规则的批量分类，配合 --dry-run 预览模式，确保批量操作安全可控。

显著优点

• 确定性执行：统一处理 headers、分页、限速（3 req/s）和重试，错误率远低于临时脚本
• 零依赖安全：纯 Node.js 内置模块实现，彻底消除供应链攻击风险
• 环境变量认证：通过 NOTION_API_KEY 等变量获取密钥，无硬编码泄露风险
• JSON-first 设计：输出结构化数据，便于 Agent 解析和自动化编排
• 智能限流：350ms 请求间隔 + 6 次指数退避重试，符合官方最佳实践

潜在局限

• 功能边界：专注于内容 CRUD，不支持数据库 schema 修改、权限管理或页面模板创建
• Markdown 转换：复杂 Notion 块（如嵌套数据库、公式字段）的 Markdown 映射可能不完全
• 依赖 Node.js：运行时需 Node 18+，环境要求高于纯 shell 方案
• 无原生 GUI：纯 CLI 交互，非技术用户学习曲线较陡

适合人群

• 需要批量处理 Notion 内容的知识库管理员
• 构建自动化工作流的效率工具爱好者
• 将 Notion 作为数据源集成的开发者/Agent 系统
• 追求"本地优先"、不信任第三方 SaaS 工具的隐私敏感用户

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| API 密钥泄露 | 环境变量被进程 dump 读取 | 使用专用集成令牌，定期轮换 |

| 误操作数据丢失 | 批量移动/覆盖无二次确认 | 强制 `--dry-run` 预览，配合 `--limit` 分批执行 |

| 限流触发 | 并发过高导致 429 错误 | 内置退避机制，避免多实例并发 |

| 权限漂移 | 页面未共享给集成导致 403 | 操作前验证 `whoami` 和页面可见性 |

安全认证显示该 Skill 通过全部 6 维度检测（静态分析 88、动态分析 82、依赖审计 95），但建议用户仍遵循"不信任 Notion 内容本身"的原则，将页面内容视为不可信输入。