trae-embedded-spec-builder

嵌入式 SPEC 文档构建器 — 项目级架构基线层

Version: 2.0.0 License: MIT Engines: Node.js >= 20.19.0

这是什么

@wangwubei/embedded-spec-builder 是一个针对嵌入式软件项目的 NPM CLI 工具，提供 4 个独立 AI Skill 一键安装到 30+ AI IDE：

| 子 Skill | 职责 | 触发时机 | |---------|------|---------| | embedded-spec-generator | 生成项目级 SPEC 文档（11+1 步） | 项目启动期 | | embedded-pattern-advisor | 31 种嵌入式设计模式咨询 + 6 种统一骨架 | 任何阶段 | | embedded-code-refactor | 七维诊断 + 协作链分析 | 已有代码改进 | | embedded-test-case-generator | 生成测试用例（6 维度 + 32 类故障注入 + 13 项自检） | SPEC 完成后 |

快速开始（v2.0 NPM 方式）

安装

npm install -g @wangwubei/embedded-spec-builder

初始化

cd your-embedded-project
esb init

交互式选择要安装到哪些 IDE，然后一键完成。

非交互式

# 只安装 Trae
esb init --ide trae

# 安装多个 IDE
esb init --ide trae,claude,cursor

# 强制覆盖
esb init --force

CLI 命令

esb init [path]

初始化项目并安装 skills 到选定的 IDE。

esb init                    # 当前目录交互式
esb init ./my-project       # 指定目录
esb init --ide trae         # 仅 Trae
esb init --ide all          # 所有可用 IDE
esb init --force            # 强制覆盖
esb init --skip-openspec    # 跳过 openspec 目录初始化

esb update

重新生成所有已安装 IDE 的 SKILL.md（适用于升级 esb 后同步）。

esb update           # 仅更新版本旧的
esb update --force   # 强制全部更新

esb sync

监听归档目录，自动启动 CDP 反向传播。

esb sync           # 持续监听模式
esb sync --once    # 一次性扫描

esb list

列出所有 IDE 中已安装的 skills。

esb list           # 表格输出
esb list --json    # JSON 输出（机器可读）

esb validate

校验 skills 的 SKILL.md frontmatter 完整性。

esb validate           # 默认
esb validate --strict  # 严格模式

esb claude-md

生成 CLAUDE.md 文件。

esb claude-md           # 生成
esb claude-md --force   # 覆盖

esb openspec-init

初始化 openspec 目录结构。

esb openspec-init           # 初始化
esb openspec-init --force   # 强制

支持的 30+ AI IDE

完全适配（含 Slash Command）：

• Claude Code — .claude/skills/ + .claude/commands/esb/
• Cursor — .cursor/skills/ + .cursor/commands/esb-*
• Codex — .codex/skills/ + ~/.codex/prompts/ (全局)
• Gemini CLI — .gemini/skills/ + .gemini/commands/esb/*.toml
• Windsurf — .windsurf/skills/ + .windsurf/workflows/
• GitHub Copilot — .github/skills/ + .github/prompts/
• Cline — .clinerules/skills/ + .clinerules/workflows/
• Roo Code — .roo/skills/ + .roo/commands/
• Qwen Code — .qwen/skills/ + .qwen/commands/esb/*.toml
• Amazon Q — .amazonq/skills/ + .amazonq/prompts/

Skill-only 模式：

• Trae — .trae/skills/
• Kimi — .kimi/skills/

仅注册（待 adapter 完善）： ForgeCode / Continue / Vibe / Aider / Tabnine / Cody / JetBrains AI / Zed / Void / Pearl / Augment / Sweep / OpenDevin / Devin / Bolt / Lovable / V0 / KiloCode

项目结构

@wangwubei/embedded-spec-builder/
├── README.md                         ← 你正在读
├── INSTALL.md                        ← 详细安装指南
├── USAGE.md                          ← 完整使用手册
├── package.json                      ← NPM 元数据
├── tsconfig.json                     ← TypeScript 配置
├── LICENSE                           ← MIT 许可证
│
├── docs/
│   └── 嵌入式SPEC文档构建器_Skill设计方案_V8.md
│
├── src/                              ← TypeScript 源码
│   ├── cli/index.ts                  ← CLI 主入口
│   ├── commands/                     ← 8 个 CLI 命令
│   └── core/
│       ├── config.ts                 ← AI_TOOLS 注册表（30 个 IDE）
│       ├── available-tools.ts        ← IDE 检测
│       ├── init.ts                   ← InitCommand
│       ├── legacy-cleanup.ts
│       ├── shared/
│       │   ├── skill-generation.ts
│       │   └── tool-detection.ts
│       ├── templates/
│       │   └── skill-templates.ts
│       ├── command-generation/       ← Adapter 模式
│       │   ├── types.ts
│       │   ├── registry.ts
│       │   ├── generator.ts
│       │   ├── index.ts
│       │   └── adapters/             ← 12 个 IDE adapter
│       ├── cdp/                      ← CDP 反向传播
│       │   ├── state-manager.ts
│       │   ├── openspec-watcher.ts
│       │   ├── impact-analyzer.ts
│       │   ├── propagator.ts
│       │   └── auth-gates.ts
│       └── integration/              ← CLAUDE.md / openspec 目录集成
│           ├── openspec-init.ts
│           ├── spec-extractor.ts
│           ├── claude-md-generator.ts
│           └── claude-md-template.ts
│
├── skills/                           ← 4 个 skill 内容
│   ├── embedded-spec-generator/
│   ├── embedded-pattern-advisor/
│   ├── embedded-code-refactor/
│   └── embedded-test-case-generator/
│
└── scripts/                          ← v1.0 脚本（兼容保留）
    ├── install-trae.ps1
    ├── install-trae.sh
    └── uninstall.ps1

核心方法论（V8）

八大设计哲学

① 功能 = 模块协作链
② 穷举行为路径，而非输入数据
③ 时空确定性是嵌入式架构的基石
④ 未审批不实现，绝对铁律无例外
⑤ 强制 > 建议，铁律 > 流程
⑥ 文档是活的资产，变更必须双向传播
⑦ SPEC 驱动测试，测试反哺 SPEC
⑧ 项目级架构基线由本工具维护

v2.0 数据规模

4 个独立子 skill
30+ AI IDE 支持
12 个完整 adapter
8 个 CLI 命令
42+ 个 TypeScript 模块（源码）
45+ 个 skill 内容文件
21 万字符方法论
38 条强制规则
8 大设计哲学
4 道 CDP 授权门
5 个 CDP 触发场景
32 类故障注入
13 项测试自检
6 维度 × N 对象测试矩阵
31 种嵌入式设计模式
6 种统一骨架

路线图

v1.0 (MVP) 已完成

• 4 个子 skill 完整内容
• Trae 单 IDE 安装脚本

v2.0 (当前) 已完成

• NPM 包 @wangwubei/embedded-spec-builder
• CLI 命令 esb（8 个子命令）
• 30+ AI IDE 注册（12 个完整 adapter）
• CDP 反向传播完整实现（4 道授权门）
• openspec 目录自动初始化
• CLAUDE.md 自动生成与同步

v3.0 (规划中)

• 完善剩余 18 个 IDE adapter
• Web UI 界面
• 多语言支持（英文版 SKILL.md）
• 团队协作模式
• 更多行业模板（医疗、汽车 ISO 26262）

开发

从源码构建

git clone <repo-url>
cd trae-embedded-spec-builder
npm install
npm run build

本地链接测试

npm link
cd /path/to/test-project
esb init

运行测试

npm test

License

MIT

反馈

请通过 issue 或 PR 反馈问题与建议。

Last updated: 2026-06-18