--- name: "notion-toolkit-free" description: "通过 Notion API 创建和管理页面、数据库与块,支持搜索、查询与内容更新。Use when 需要数据库操作、SQL查询、数据存储管理时使用。不适用于数据库架构设计决策。适用于独立开发者、企业团队和自动化工作流场景。支持中文交互，无需复杂配置即开即用。输出结果可直接使用，减少二次加工成本。提供结构化输出和错误处理机制。" license: Proprietary allowed-tools: read exec compatibility: "Requires LLM with tool-use capability" metadata: displayName: "Notion 工具包基础版" version: "1.0.0" summary: "通过 Notion API 创建和管理页面、数据库与块,支持搜索、查询与内容更新" tags: - "Notion" - "API" - "页面管理" - "数据库" source: "SkillHub" converted_at: "2026-07-22T17:58:36" tools: - exec - read --- # Notion 工具包基础版 ## 概述 本工具是 **知识管理** 领域的 **FREE 版本** AI Skill,专为个人用户与轻量级场景设计。通过自然语言指令驱动 AI Agent 执行任务,提供核心功能与简洁易用的操作体验。 FREE 版本与 PRO 版本完全兼容,可在需要时升级至 PRO 版本获取高级功能、批量操作与团队协同能力。 ### 版本定位 | 维度 | FREE 版本 | PRO 版本 | |:-----|:----------|:---------| | 目标用户 | 个人用户 | 企业团队 | | 功能范围 | 核心功能 | 全部功能 | | 批量操作 | 不支持 | 支持 | | 团队协作 | 不支持 | 支持 | | 技术支持 | 社区支持 | 优先响应 | | 数据分析 | 基础统计 | 高级分析 | ## 核心能力 FREE 版本提供以下能力: ### 搜索页面和数据源(数据库) 搜索页面和数据源(数据库) **输出**: 返回搜索页面和数据源(数据库)的执行结果,包含操作状态和输出数据。 - 执行此能力时使用`input_params`参数,支持创建/查询/导出操作 ### 获取页面内容与块结构 获取页面内容与块结构 **输出**: 返回获取页面内容与块结构的执行结果,包含操作状态和输出数据。 - 执行此能力时使用`input_params`参数,支持创建/查询/导出操作 ### 在数据源中创建页面并设置属性 在数据源中创建页面并设置属性 **输出**: 返回在数据源中创建页面并设置属性的执行结果,包含操作状态和输出数据。 - 执行此能力时使用`input_params`参数,支持创建/查询/导出操作 ### 查询数据源并过滤排序 查询数据源并过滤排序 **输出**: 返回查询数据源并过滤排序的执行结果,包含操作状态和输出数据。 - 执行此能力时使用`input_params`参数,支持创建/查询/导出操作 ### 更新页面属性与添加块 更新页面属性与添加块 **输出**: 返回更新页面属性与添加块的执行结果,包含操作状态和输出数据。 - 执行此能力时使用`input_params`参数,支持创建/查询/导出操作 ### 功能详情 本版本提供 5 项核心能力,覆盖 知识管理 的常见使用场景。如需批量操作、团队协作、数据分析等高级功能,可升级至 PRO 版本。 **FREE 版本核心功能清单:** - 搜索页面和数据源(数据库) - 获取页面内容与块结构 - 在数据源中创建页面并设置属性 - 查询数据源并过滤排序 - 更新页面属性与添加块 **PRO 版本扩展功能预览:** - 批量页面创建与属性映射 - 数据库模板管理与自动应用 - 多数据源同步与跨工作区复制 - 工作流自动化:状态变更触发操作 - 与外部系统集成的数据管道 - Notion 版本管理与变更追踪 **输出**: 返回功能详情的执行结果,包含操作状态和输出数据。 **技术参数**：使用`input_params`和`output_format`参数控制执行行为,支持`json`/`text`/`csv`输出格式。 **能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：API、创建和管理页面、数据库与块、支持搜索、查询与内容更新、知识管理领域的专、辅助工具、提供核心基础功能等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。 ## 使用场景 ### 场景 1: 搜索工作区内容 按关键词搜索页面和数据库 ```bash curl -X POST "https://api.notion.com/v1/search" -H "Authorization: Bearer $NOTION_KEY" -H "Notion-Version: 2025-09-03" -d '{"query": "project"}' ``` ### 场景 2: 在数据库中创建页面 创建新条目并设置属性 ```bash notion.com/v1/pages" -H "Authorization: Bearer $NOTION_KEY" -H "Notion-Version: 2025-09-03" -d '{"parent":{"database_id":"未指定"},"properties":{"Name":{"title":[{"text":{"content":"New Item"}}]}}}' ``` ## 不适用场景 以下场景Notion 工具包基础版不适合处理： - 实时流数据处理 - 小规模数据手动分析 - 非结构化文本情感分析 ## 触发条件 需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于非本工具能力范围的需求。 ## 快速开始 ### 1. 环境准备 确保已安装并配置好 AI Agent 环境(Claude Code / Cursor / Codex / Gemini CLI 等),本 Skill 通过 SKILL.md 指令驱动 Agent 执行任务。 **系统要求:** - 操作系统: Windows / macOS / Linux - Agent 平台: 支持 SKILL.md 格式的任意 AI Agent - 运行时: Python 3.8+ 或 Node.js 18+(视具体操作需求) ### 2. 配置参数 ```bash mkdir -p ~/.config/notion echo "ntn_your_key_here" > ~/.config/notion/api_key # Notion-Version: 2025-09-03 # 需要将目标页面/数据库连接到你的 integration ``` ### 3. 验证配置 配置完成后,可通过以下方式验证是否正常工作: ```bash # 验证环境变量是否设置 echo "配置检查:" env | grep -E "API|KEY|TOKEN|SECRET" | sed "s/=.*/=***/" # Linux/macOS # 或 PowerShell # Get-ChildItem Env: | Where-Object {$_.Name -match "API|KEY|TOKEN"} | Format-Table ``` ### 4. 开始使用 在 AI Agent 对话中描述你的需求,Agent 会根据本 Skill 的指令自动执行对应操作。 ```text 请帮我搜索工作区内容 ``` Agent 将自动: 1. 解析你的自然语言指令 2. 调用相应的工具或 API 3. 执行操作并返回结果 4. 返回执行结果供你确认 # ## 示例 ### 基础配置 ```bash mkdir -p ~/.config/notion config/notion/api_key # Notion-Version: 2025-09-03 # 需要将目标页面/数据库连接到你的 integration ``` ### 可选配置 ```json { "edition": "free", "auto_retry": false, "max_concurrent": 1, "log_level": "info", "cache_enabled": true, "timeout": 30 } ``` **FREE 配置项说明:** | 配置项 | 类型 | 默认值 | 说明 | |:-------|:-----|:-------|:-----| | auto_retry | bool | false | 失败后自动重试 | | max_concurrent | int | 1 | 最大并发数(FREE 限制为1) | | log_level | string | info | 日志级别 | | cache_enabled | bool | true | 启用结果缓存 | | timeout | int | 30 | 操作超时时间(秒) | ## 优选实践 1. **API 版本统一使用 2025-09-03** 2. **页面/数据库 ID 使用完整 UUID** 3. **速率限制约 3 请求/秒,批量操作需控制频率** 4. **创建页面前确认父级 database_id 正确** ### 个人使用建议 - 从简单任务开始熟悉工具行为,逐步扩展到复杂场景 - 定期备份配置文件与数据,防止意外丢失 - 遇到问题先查阅常见问题章节,再寻求社区帮助 - 保持配置简洁,只启用必要的功能选项 - 定期更新工具版本以获取最新功能与修复 - 记录常用操作命令,提高日常使用效率 ## 常见问题 ### Q: 数据库和数据源有什么区别? A: 2025-09-03 版本中数据库称为数据源,查询使用 /data_sources/ 端点。 ### Q: 如何获取 API Key? A: 在 notion.so/my-integrations 创建集成,复制以 ntn_ 开头的密钥。 ### Q: 如何升级到 PRO 版本? A: 升级到 PRO 版本非常简单: 1. 获取 PRO 版本授权 2. 安装 PRO 版本 Skill 3. 原有配置自动迁移,无需额外操作 4. 即可使用批量操作、团队协作等高级功能 ### 已知限制 A: FREE 版本主要限制: - 不支持批量操作(每次只能处理一个任务) - 不支持团队协作(仅限个人使用) - 不支持高级数据分析 - 技术支持依赖社区 如需这些功能,建议升级至 PRO 版本。 ### Q: FREE 版本的数据安全吗? A: FREE 版本所有数据本地存储,不上传云端,确保隐私安全。建议定期备份配置文件与数据目录。 ## 依赖说明 ### 运行环境 - **Agent 平台**: 支持 SKILL.md 的任意 AI Agent(Claude Code / Cursor / Codex / Gemini CLI 等) - **操作系统**: Windows / macOS / Linux - **运行时**: Python 3.8+ 或 Node.js 18+(视具体操作需求) - **网络**: 部分功能需要网络连接访问外部 API ### 依赖详情 | 依赖项 | 类型 | 是否必需 | 获取方式 | |:-------|:-----|:---------|:---------| | LLM API | API | 必需 | 由 Agent 内置 LLM 提供 | | curl | CLI 工具 | 推荐 | 系统自带或包管理器安装 | | jq | JSON 处理 | 推荐 | apt install jq / brew install jq | | Python 3.8+ | 运行时 | 视需求 | python.org 下载 | | Node.js 18+ | 运行时 | 视需求 | nodejs.org 下载 | ### API Key 配置 FREE 版本支持单一 API Key 配置,满足个人使用需求: - **环境变量**:通过环境变量配置 API Key - **配置文件**:支持配置文件方式存储 API Key - **安全提醒**:切勿将 API Key 硬编码到脚本或提交到版本控制系统 ### 可用性分类 - **分类**: MD+execute(纯 Markdown 指令,部分功能需要 exec 命令行执行能力) - **说明**: 基于 Markdown 的 AI Skill,通过自然语言指令驱动 Agent 执行任务 - **FREE 特性**: 支持单次执行、基础配置与社区支持 - **安全等级**: 基础,数据本地存储,建议定期备份 - **SLA**: 社区支持,尽力响应 --- **版本信息** | 项目 | 值 | |:-----|:---| | 版本号 | 1.0.0 | | 版本类型 | FREE | | 许可证 | MIT | | 兼容性 | 可升级至 PRO 版本 | ## 错误处理 | 错误场景 | 原因 | 处理方式 | |---------|------|---------| | 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 | | 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 | | 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 | ## 安全注意事项 | 风险类型 | 防范措施 | |----------|---------| | API密钥泄露 | 通过环境变量配置，禁止硬编码到代码或配置文件中 | | 命令执行风险 | 仅执行白名单命令，避免拼接用户输入到命令行参数中 | | 网络通信安全 | 使用HTTPS协议，验证SSL证书有效性 | | 敏感数据暴露 | 输出结果中不包含密钥、令牌等敏感信息 | 使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。