earthsdk3-skill

EarthSDK3 AI 开发工具套件。自动识别开发场景（SDK 源码 / 业务项目），同步知识库、skills、reference，并提供 doctor / clean / lint 等维护能力。

项目脚手架已拆分为独立包 create-earthsdk，本包不再提供 create 命令，也不再按 IDE 注入规则文件。

安装

已有项目：

pnpm add -D earthsdk3-skill
npx earthsdk3-skill sync

sync 会注入 prepare: earthsdk3-skill sync，之后每次 install 自动同步。新项目请使用 create-earthsdk 生成，它已经写好该配置。

命令

| 命令 | 作用 | | --- | --- | | npx earthsdk3-skill sync | 识别 sdk-dev / project-dev，同步 .agents/earthsdk3，通过 npx skills 安装 skills，写 manifest | | npx earthsdk3-skill doctor | 体检：profile、知识库、manifest 版本、skills 状态 | | npx earthsdk3-skill clean | 清理 managed 的 .agents/earthsdk3 与 earthsdk3 skills | | npx earthsdk3-skill lint [path] | 扫描 EarthSDK 反模式 | | npx earthsdk3-skill validate | 校验 manifest 与资产引用 |

常用选项：

npx earthsdk3-skill sync --context=project-dev   # 强制业务项目
npx earthsdk3-skill sync --context=sdk-dev       # 强制 SDK 源码开发
npx earthsdk3-skill sync --skip-skills           # 只同步知识库，不装 skills
npx earthsdk3-skill sync --root=path             # 指定注入根目录

工作方式

sync
  ├─ detectContext() → sdk-dev / project-dev
  ├─ 按 profile 过滤内容
  ├─ 写 .agents/earthsdk3/  knowledge / workflows / validators / reference / rules
  ├─ npx skills add <skill> --copy -y            # skills 统一安装
  ├─ 写 sync-manifest.json
  └─ 维护 .gitignore（.agents/earthsdk3、skills-lock.json）

• 知识资产统一放在 .agents/earthsdk3/，不再按 Cursor / Trae / Claude 等 IDE 复制多份规则。
• skills 由 npx skills 安装到 .agents/skills/；失败时 fallback 复制到同一目录。
• 规则以 .agents/earthsdk3/rules/ 的 Markdown 提供，由 SKILL.md 引用。
• Copilot 用户需在 VS Code 开启 chat.useAgentSkills 并使用 Agent 模式。

开发场景

| Profile | 场景 | | --- | --- | | project-dev | 业务项目、demos、外部应用 | | sdk-dev | EarthSDK 官方 Monorepo 根与 earthsdk/earthsdk3* 源码包 |

与 create-earthsdk 的关系

• create-earthsdk 负责生成项目、写依赖、注入 prepare: earthsdk3-skill sync。
• 本包负责 AI 配置、知识库、skills、体检与清理。
• 生成项目后直接执行 pnpm install，prepare 会自动完成 sync。

目录结构

earthsdk3-skill/
├─ profiles/          # sdk-dev / project-dev
├─ rules/             # 规则源
├─ intents/           # 意图路由
├─ skills/            # 领域技能（8 个）
├─ knowledge/         # API 速查、对象属性、catalog
├─ reference/         # 完整对象 API 参考
├─ workflows/         # 多步骤工作流
├─ validators/        # 生成后校验
├─ examples/          # 示例
├─ specs/             # 对象索引
└─ src/               # sync / doctor / clean / lint / validate

常见问题

• doctor 提示 manifest 过期：重新执行 sync。
• skills 未安装：执行 sync；npx skills 失败会自动 fallback。
• 想卸载：npx earthsdk3-skill clean，再移除 devDependency。