用途
share-skill 用于把本地技能（位于 03-skills/ 目录）导出并推送到公司的 Notion 技能数据库（Beam Nexus Skills database）。它负责校验 SKILL.md 格式、读取元数据（含版本）、自动上传技能全部文件、映射字段到 Notion 属性、在推送前强制要求用户确认、从 user-config.yaml 设置 Owner、推断合适的 Team（必要时创建新 Team），并创建带文件附件的数据库条目。通常在 create-skill 之后使用，用于把新技能分享给公司。
主要能力
- 校验 SKILL.md 格式：检查 YAML frontmatter 是否存在、必填字段（name、description）是否齐全、description 是否包含触发短语（含 "when"）、版本格式是否合法（语义化版本，如 1.0、1.0.0）。
- 读取 SKILL.md 提取元数据：name、description、version（默认 1.0），以及 Purpose 段落。
- 自动打包技能文件：生成 JSON bundle（{skill-name}.skill.json），包含 SKILL.md（必需）、scripts/、references/、assets/ 等文件夹，文件内容以 base64 编码保存。
- 通过 Notion File Upload API 上传文件并创建数据库条目（带附件）。
- 重复检测：若技能名已存在，提示 Owner、Version、URL，并阻止覆盖。
- 版本跟踪：版本记录在 SKILL.md frontmatter、JSON bundle 和 Notion 数据库三处。
- 支持 --dry-run 预览、--as-new 上传改进版本、--skip-validation 跳过校验（不推荐）、--integration 指定集成。
使用方式
前置检查（每次导出前必须运行）：
python ../../notion-master/scripts/check_notion_config.py
若未配置，可运行安装向导：
python ../../notion-master/scripts/setup_notion.py
或参考 ../../notion-master/references/setup-guide.md。
预览（不实际上传）：
python ../../notion-master/scripts/upload_skill.py 03-skills/{skill-name} --team General --dry-run
正式上传：
python ../../notion-master/scripts/upload_skill.py 03-skills/{skill-name} --team General
带集成：
python ../../notion-master/scripts/upload_skill.py 03-skills/my-skill --team General --integration "Beam AI,Linear"
上传为改进版本（新名称）：
python ../../notion-master/scripts/upload_skill.py 03-skills/my-skill --team General --as-new "my-skill-enhanced"
跳过校验（不推荐）：
python ../../notion-master/scripts/upload_skill.py 03-skills/my-skill --team General --skip-validation
工作流：读取本地技能 → 准备技能 bundle → 推断 Team 并收集信息 → 推送前预览（强制）→ 创建带文件的 Notion 条目 → 确认成功。
适用场景
- 在 create-skill 之后，把新创建的技能分享给公司。
- 将本地技能导出到 Notion 技能数据库，供团队发现和使用。
- 上传技能的改进版本（使用 --as-new 创建新条目）。
- 用户提到 "share skill"、"export skill"、"push to notion"、"add skill to database" 等触发短语时。
限制与规则
- 推送前必须获得用户确认，绝不自动推送。
- 必须设置 Owner（使用 user-config.yaml 中的 notion_user_id）。
- 必须上传技能文件（使用 Notion File Upload API）。
- 必须推断合适的 Team，不要默认 Solutions；General 用于公司通用工具，Solutions 用于面向客户/实施，Engineering 用于开发工具；必要时可创建新 Team。
- 必须先检查重复项，不能覆盖他人的技能。
- 禁止从 Notion 删除技能，删除必须在 Notion UI 手动完成。
- 改进版本使用 --as-new，不要覆盖，而是创建新条目。
- 禁止批量推送，一次只能推送一个。
- 禁止覆盖已有技能，必须先删除。
- 禁止删除任何技能。
配置
来自 .env：
- NOTION_API_KEY - Notion 集成令牌
- NOTION_SKILLS_DB_ID - 数据库 ID：2bc2cadf-bbbc-80be-af8a-d45dfc8dfa2e
来自 user-config.yaml：
- notion_user_id - 用于 Owner 字段的 Notion 用户 ID
- notion_user_name - 显示名称
可用 Team（可创建新 Team）：General、Solutions、Engineering、Sales。
可用集成：Beam AI、Linear、Notion。
字段映射
本地（SKILL.md）到 Notion 属性：
- name: in YAML → Skill Name（title，必需）
- description: in YAML → Description（rich_text，必需）
- version: in YAML → Version（rich_text，必需，默认 1.0）
- Purpose 段落 → Purpose（rich_text，可选，从 ## Purpose 提取）
- AI 推断 + 用户确认 → Team（select，必需，不存在则创建）
- AI 从内容推断 → Integration（multi_select，可选）
- user-config.yaml → Owner（people，必需，notion_user_id）
- 今天日期 → Created（date，必需，自动设置）
- JSON bundle → Skill（files，必需，通过 File Upload API 自动上传）
版本跟踪
版本格式：MAJOR.MINOR 或 MAJOR.MINOR.PATCH。合法示例：1.0、1.1、2.0、1.0.0。非法示例：v1.0（无 "v" 前缀）、1（需要 MAJOR.MINOR）、latest（必须为数字）、1.0.0.0（段数过多）。
何时递增：
- Bug 修复、拼写错误 → 递增 MINOR（1.0 → 1.1）
- 小幅改进 → 递增 MINOR（1.1 → 1.2）
- 新增功能 → 递增 MINOR（1.2 → 1.3）
- 破坏性变更 → 递增 MAJOR（1.x → 2.0）
- 完全重写 → 递增 MAJOR（2.x → 3.0）
版本记录在 3 处：SKILL.md frontmatter（version: 字段，真实来源）、JSON bundle（"version": "1.0"）、Notion 数据库（Version 列）。
错误处理
常见错误与解决方案：
- 401 Unauthorized：API 密钥无效，检查 .env 中的 NOTION_API_KEY。
- 400 Bad Request：属性格式无效，检查字段映射。
- Skill already exists：Notion 中重复，使用 --as-new 或在 Notion 中删除。
- Missing notion_user_id：不在 user-config.yaml 中，提示添加。
- Missing SKILL.md：技能路径无效，验证路径。
- Validation failed：SKILL.md 格式无效，修复问题或使用 --skip-validation。
详细故障排除见 ../../notion-master/references/error-handling.md。
附加参考
- ../../notion-master/references/setup-guide.md - 初始设置
- ../../notion-master/references/api-reference.md - 文件上传 API
- ../../notion-master/references/database-schema.md - 完整 schema
- ../../notion-master/references/error-handling.md - 故障排除