用途
notion-master 是一个共享资源库，供 Notion 集成相关技能引用，用于消除重复内容。它本身不是面向用户的技能，用户不应直接加载它，而应调用具体的 Notion 技能（如 notion-connect、query-notion-db、import-skill-to-nexus、export-skill-to-notion）。
主要能力
该资源库通过 DRY 原则，将原本在 3 个 Notion 技能中重复的 950 行内容（设置向导、API 文档、错误表各重复 3 次）抽取到 notion-master/references/ 和 notion-master/scripts/ 中，使 SKILL.md 文件从 950 行减少到 370 行，上下文占用减少约 60%。
参考文档（references/）
- setup-guide.md：完整设置向导，包括获取 Notion API 密钥、查找数据库 ID、配置 .env 和 user-config.yaml、获取用户 Notion ID。
- api-reference.md：Notion API 模式，包括数据库查询 API、文件上传 API（三步流程）、文件下载 API（三步流程）、常用 curl 示例。
- error-handling.md：故障排除，包括常见错误与解决方案、API 错误码、配置问题、网络与超时处理。
- database-schema.md：Beam Nexus Skills 数据库，包括属性类型与描述、可用 Teams 和 Integrations、字段映射表、示例条目。
- filter-syntax.md：查询过滤语法，包括按属性类型的操作符、常用过滤模式、排序选项。
- property-types.md：属性类型参考，包括 20 多种属性类型、读写格式、验证规则。
- block-types.md：块类型参考，包括 50 多种块类型、块模式与示例、富文本格式。
脚本（scripts/）
配置与设置：
- check_notion_config.py：预检验证，支持 --json 参数，退出码 0=已配置、1=部分配置、2=未配置。建议在任何 Notion 操作前首先运行。
- setup_notion.py：交互式设置向导，无参数，引导完成 API 密钥设置、测试连接、保存到 .env、获取用户 Notion ID、自动运行数据库发现。
- discover_databases.py：数据库发现（POST /search），支持 --refresh、--json、--detailed，保存到 01-memory/integrations/notion-databases.yaml。
数据库查询：
- search_skill_database.py：统一数据库查询（POST /databases/{id}/query），支持通用模式和 Skills DB 预设模式，参数包括 --db、--skills、--team、--integration、--name、--owner、--filter、--sort、--sort-dir、--limit、--json。过滤语法示例：--filter "Status = Active"、--filter "Name contains project"、--filter "Priority > 5"、--filter "Tags is_empty" 等。
页面操作：
- create_page.py：在数据库中创建页面（POST /pages），支持 --db、--properties、--interactive、--json。
- manage_page.py：页面管理（GET/PATCH /pages/{id}），子命令 get、update、delete。
数据库管理：
- manage_database.py：数据库操作（POST/PATCH /databases），子命令 create、update。
块操作：
- manage_blocks.py：块操作（GET/PATCH/DELETE /blocks/{id}），子命令 get、children、append、update、delete。
用户管理：
- manage_users.py：用户操作（GET /users），子命令 list、get、me。
评论操作：
- manage_comments.py：评论操作（GET/POST /comments），子命令 list、create、get。需要集成设置中的“Insert comments”能力。
技能导入导出：
- download_skill.py：从 Notion 下载技能，参数包括 page_ids、--output-dir、--no-backup、--json。
- upload_skill.py：上传技能到 Notion，参数包括 SKILL_PATH、--team、--integration、--dry-run、--as-new、--skip-validation、--json。
工具模块：
- rate_limiter.py：速率限制处理模块（非 CLI），提供 with_retry 装饰器、RateLimiter 类、make_request_with_retry 函数，支持指数退避、抖动、遵循 Retry-After 头、自动重试 429/5xx。
使用方式
用户应直接调用具体的 Notion 技能，而不是加载 notion-master。各技能按需引用共享资源（渐进式披露）。例如，用户说“query my Projects database”时：AI 加载 notion-connect 技能，该技能提示先运行 check_notion_config.py，然后运行 search_skill_database.py --db "Projects"，如遇错误则加载 error-handling.md。
当 Notion 技能因缺少配置而失败时，AI 应运行 check_notion_config.py --json，解析 ai_action 字段（proceed_with_operation、proceed_with_warning、prompt_for_api_key、create_env_file、run_setup_wizard），并据此帮助用户修复问题。
适用场景
适用于需要与 Notion 工作区集成的技能开发与使用，包括查询数据库、创建和管理页面、管理块、用户、评论，以及在 Notion 与本地 Nexus 之间导入导出技能。
限制
notion-master 不是用户直接调用的技能，不应直接加载。其功能依赖 Notion API 密钥和数据库 ID 的正确配置。评论操作需要集成设置中的“Insert comments”能力。速率限制为 3 请求/秒。
版本：2.6，创建于 2025-12-10，更新于 2025-12-11，状态：生产就绪。