earthsdk3-skill

EarthSDK3 AI 开发工具套件 — 安装即用。自动识别 开发场景（SDK 源码 / 业务项目）、IDE 与 包管理器，注入对应的 rules、skills、intents。

版本 1.0.8 — 多 IDE 目录/格式审计（Trae CN→.trae、Qoder .md、CodeBuddy 文件夹、Reasonix）；含 1.0.7 ES 继承、规则格式、uniformMap。决策层 + 8 领域 Skill + JSON Catalog + lint/doctor/sync-manifest。

文档：使用手册 · 迁移 · 脚手架路线图 · knowledge/package-setup.md · knowledge/prompt-guide.md（sync 后）

快速开始

新项目（推荐）

# 交互式：框架 / 引擎 / IDE / 安装 / sync 一步向导
npx earthsdk3-skill create

# 非交互示例：Vite+Vue3 + Cesium
npx earthsdk3-skill create --yes --dir=./my-earth-app --engines=cesium --ide=cursor

生成最小可运行工程（含 whenViewerReady 时序、earthsdk3-skill sync、项目 README）。详见下方 create 与 knowledge/package-setup.md。

已有项目

# 一步 sync AI 配置
npx earthsdk3-skill sync

# 或仅合并依赖 + sync（目录须已有 package.json）
npx earthsdk3-skill create --yes --framework=existing --dir=. --engines=cesium

sync 会：自动注入 "prepare": "earthsdk3-skill sync"、注入 rules/skills/intents、同步知识库、维护 .gitignore。此后每次 npm/pnpm install 自动触发 sync。

IDE 与团队： 本地 .earthsdk3-skill.json 记录锁定 IDE（不提交 Git）。无该文件时 prepare 自动检测本机主 IDE 并写入；队友 clone 后只需 pnpm install。换编辑器：sync --ide=vscode。详见下方 IDE 锁定与团队协作。

外部项目完整 5 步见 knowledge/package-setup.md；总览见 docs/USER_GUIDE.md（sync 后：.agents/earthsdk3/knowledge/user-guide.md）。

CLI

# ── 脚手架（v1.0.4+）──
npx earthsdk3-skill create                    # 交互式（TTY）
npx earthsdk3-skill create --yes              # 非交互
npx earthsdk3-skill create --help             # 完整选项

# ── 同步与诊断 ──
# 自动检测场景 + IDE
npx earthsdk3-skill sync

# 仅更新 rules/assets，跳过 skills（CI 或快速刷新知识库）
npx earthsdk3-skill sync --skip-skills

# 指定注入目录
npx earthsdk3-skill sync --root=../..

# 指定场景
npx earthsdk3-skill sync --context=project-dev

# 指定注入的 IDE（逗号分隔）
npx earthsdk3-skill sync --ide=cursor,claude,reasonix

# 强制注入所有支持的 IDE 配置
npx earthsdk3-skill sync --force

# npx skills 失败时退出（默认 fallback 复制）
npx earthsdk3-skill sync --strict

# 诊断
npx earthsdk3-skill doctor
npx earthsdk3-skill doctor --json

# 代码禁止模式扫描
npx earthsdk3-skill lint
npx earthsdk3-skill lint src/

# 校验 manifest
npx earthsdk3-skill validate

# 清理
npx earthsdk3-skill clean

create 选项摘要

| 选项 | 说明 | |------|------| | --template=vue + --lang=ts\|js | create-vite 风格（默认 vue + ts） | | --framework=vite-vue3-ts | Vite + Vue3 + TS（别名 vue-ts） | | --framework=vite-vue3-js | Vite + Vue3 + JS（别名 vue） | | --framework=vite-vanilla-ts | Vite + TS 无 Vue（别名 vanilla-ts） | | --framework=vite-vanilla-js | Vite + JS 无 Vue（别名 vanilla） | | --framework=existing | 已有项目：合并依赖 + prepare + sync | | --assets / --no-assets | Cesium 是否安装 earthsdk3-assets（默认安装） | | --dir=./my-app | 输出目录（existing 默认 .） | | --engines=cesium,ol | 引擎包（cesium | ol | ue） | | --primary-engine=ol | 多引擎时主视口 createXxxViewer | | --ide=cursor,copilot | sync 时注入的 IDE（写入本地锁定配置） | | --git | 创建后 git init | | --skip-install / --skip-sync | 跳过安装或 sync | | --skip-skills | sync 时仅 rules/workflows，不装 skills |

脚手架生成单一主视口 + 默认影像底图 + flyTo，不含引擎切换 UI；切换见 workflows/switch-engine.md。

Monorepo / 子包安装

在 demos/app1 等子目录安装时，CLI 会自动向上解析 git 仓库根目录，将配置注入到工作区根。

npx earthsdk3-skill sync --root=../..
# 或
EARTHSDK3_AI_ROOT=/path/to/workspace npx earthsdk3-skill sync

Windsurf 路径与格式

| 推荐 | 说明 | |------|------| | .windsurf/rules/earthsdk3-*.md | Wave 8+ 标准；frontmatter 含 trigger: always_on 等 | | .windsurfrules/earthsdk3-*.md | 旧版扁平目录，仍兼容检测 |

迁移见 docs/MIGRATION.md。勿再使用 .mdc 写入 Windsurf / Trae / Qoder（1.0.8 起已按各 IDE 官方路径修正）。

IDE 锁定与团队协作

.earthsdk3-skill.json（仅本机）

create / sync --ide= 会在项目根写入本地配置（勿提交 Git，脚手架与 sync 已维护 .gitignore）：

{
  "ides": ["cursor"],
  "context": "project-dev"
}

| 情况 | 行为 | |------|------| | 有本地配置 | prepare 只同步 ides 列表中的 IDE，不扫描本机其它编辑器 | | 无本地配置 | 自动检测本机主 IDE（进程优先）→ 写入配置 → 同步 | | 多人多 IDE | 每人 pnpm install 各自生成配置；互不影响 | | ides 多个 | 支持，如 ["cursor","vscode"] 同时维护两套目录 | | 换 IDE | npx earthsdk3-skill sync --ide=vscode 覆盖本地配置 | | 检测不准 | 环境变量 EARTHSDK3_IDE=trae 或手动 --ide= |

检测优先级（自动锁定时）： EARTHSDK3_IDE → 本机运行进程（Cursor / Code / Trae…）→ 项目目录推断；多命中时按内置优先级取一个。

别名： github→copilot，code/vs code→vscode，traecn→trae-cn。

# 单人本机 Cursor ↔ VS Code 切换
npx earthsdk3-skill sync --ide=vscode

# 本机同时维护 Cursor + Copilot（可选）
npx earthsdk3-skill sync --ide=cursor,vscode

各 IDE 资产路径（sync 后）

| IDE | Rules | 规则格式 | Skills | 知识库 | |-----|-------|----------|--------|--------| | Cursor | .cursor/rules/、.agents/rules/ | earthsdk3-*.mdc（alwaysApply） | .agents/skills/earthsdk3-* | .agents/earthsdk3/ | | VS Code + Copilot | .github/copilot-instructions.md | 合并单文件 Markdown | .agents/skills/ | .agents/earthsdk3/ | | Trae / Trae CN | .trae/rules/ | earthsdk3-*.md | 同目录 skills/ | .agents/earthsdk3/ | | Claude Code | .claude/rules/ | earthsdk3-*.md | .claude/skills/ | .agents/earthsdk3/ | | Windsurf | .windsurf/rules/ | earthsdk3-*.md（trigger:） | .windsurf/skills/ | .agents/earthsdk3/ | | CodeBuddy | .codebuddy/rules/{name}/RULE.mdc | RULE.mdc（alwaysApply） | .codebuddy/skills/ | .agents/earthsdk3/ | | Qoder | .qoder/rules/ | earthsdk3-*.md | .qoder/skills/ | .agents/earthsdk3/ | | Reasonix | —（无官方 rules 目录） | 使用 REASONIX.md + .agents/earthsdk3/ | .agents/skills/ | .agents/earthsdk3/ |

sync 会按上表为锁定 IDE 写入对应扩展名与 frontmatter（源规则在包内 rules/、intents/，由 src/rule-format.ts 转换）。重新 sync 会清理误注入的旧格式（如 Trae 下的 .mdc）。

Copilot 需在 VS Code 设置中启用 "chat.useAgentSkills": true，并使用 Agent 模式。详见 使用手册（sync 后 knowledge/user-guide.md）。

常见问题（FAQ）

| 问题 | 处理 | |------|------| | sync 后 AI 不按 EarthSDK 规范回答 | 运行 doctor 确认 Profile / rules 存在；Copilot 开 Agent Skills | | npx skills 安装失败 | 默认 fallback 复制仍可用；或 sync --skip-skills 仅更新知识库 | | doctor 提示 manifest 过期 | 升级套件后重新 npx earthsdk3-skill sync | | 子包 sync 到了错误目录 | sync --root=../.. 或 EARTHSDK3_AI_ROOT | | 队友装依赖却同步成我的 IDE | 勿提交 .earthsdk3-skill.json；队友删本地该文件后 pnpm install | | 从 Cursor 换 VS Code | sync --ide=vscode（或 sync --ide=cursor,vscode 两套并存） | | 自动检测 IDE 不对 | EARTHSDK3_IDE=cursor 或 sync --ide=cursor | | 不想 install 时自动 sync | 从 package.json 移除 prepare 中的 earthsdk3-skill sync（见 package-setup） | | 移除套件 | npx earthsdk3-skill clean + 卸载 devDependency（见 package-setup） | | Monorepo 改 demo 却走了 sdk-dev | sync --context=project-dev | | Windsurf 规则不生效 | 确认 .windsurf/rules/earthsdk3-*.md 含 trigger:；重新 sync --ide=windsurf（勿用 .mdc） | | Trae / Claude 规则不加载 | 确认为 .md 非 .mdc；sync --ide=trae 或 --ide=claude |

更多排错 → docs/USER_GUIDE.md · sync 后 workflows/debug-troubleshoot.md

包内结构

earthsdk3-skill/
├─ profiles/          # 场景配置（sdk-dev / project-dev）
├─ rules/             # 常驻规则（含决策层 alwaysApply）
├─ intents/           # 意图路由
├─ docs/              # 发布计划、验收、迁移
├─ workflows/         # 多步骤工作流（20条）
├─ skills/            # 领域技能（8个）
├─ knowledge/         # API 参考 + JSON Catalog
├─ specs/             # 对象索引
├─ examples/          # 正反例
├─ validators/        # 生成后校验
├─ templates/         # create 脚手架模板（vite-vue3-ts / vite-vanilla-ts）
├─ src/               # detect、sync、scaffold、CLI、generator

架构：决策层

用户需求 → task-routing → intent → workflow-selection → skill-selection
  → SKILL.md → JSON catalog → 生成代码 → decision-check 校验

场景 Profile

| Profile | 场景 | Skills | |---------|------|--------| | sdk-dev | SDK 源码开发 | dev, debug, object, events, camera, analysis, tiles | | project-dev | 业务项目 | consume-api, debug, object, events, camera, analysis, tiles |

JSON Catalog

| Catalog | 生成 | |---------|------| | workflow-catalog.generated.json | pnpm generate:catalog | | example-catalog.generated.json | pnpm generate:catalog | | api-catalog.generated.json | pnpm generate:catalog-full（需 monorepo） |

注入流程

npx earthsdk3-skill sync
  ├─ ① 解析 IDE：--ide= > .earthsdk3-skill.json > 自动检测主 IDE
  ├─ ② installProfileSkills（--skip-skills 可跳过）
  ├─ ③ 按锁定 IDE 注入 rules + intents（各 IDE 对应 .md / .mdc / 合并 Copilot）
  └─ ④ assets 统一到 .agents/earthsdk3/ + sync-manifest.json + .gitignore

维护者发布

pnpm run build && pnpm run validate && pnpm run test   # prepublishOnly 同等
pnpm run generate:catalog
pnpm run push          # npm latest

License

MIT