@gong-ym/ai-spec-auto 0.2.11 → 0.2.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.qoder/README.md +114 -114
- package/LICENSE +21 -21
- package/README.md +433 -433
- package/bin/cli.js +294 -300
- package/bin/install-workflow.js +2983 -2983
- package/package.json +72 -73
package/README.md
CHANGED
|
@@ -1,433 +1,433 @@
|
|
|
1
|
-
# ai-spec-auto
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/@engineered/ai-spec-auto)
|
|
4
|
-
[](LICENSE)
|
|
5
|
-
[ |
|
|
29
|
-
| **分支评审** | 技术风险+业务风险双维度分析,可视化 HTML 报告 |
|
|
30
|
-
| **多 IDE 支持** | Qoder、Cursor、Claude Code、OpenCode、Trae、Codex |
|
|
31
|
-
| **渐进式接入** | L1/L2/L3 三层策略,老项目零侵入接入 |
|
|
32
|
-
|
|
33
|
-
## 🚀 快速开始
|
|
34
|
-
|
|
35
|
-
### 1. 安装
|
|
36
|
-
|
|
37
|
-
```bash
|
|
38
|
-
# 推荐:单次指定公共 registry
|
|
39
|
-
npx --yes --registry https://registry.npmjs.org/ @engineered/ai-spec-auto@latest init . --profile vue -y
|
|
40
|
-
|
|
41
|
-
# 或已配置 ~/.npmrc 后
|
|
42
|
-
npx @engineered/ai-spec-auto@latest init .
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
**支持的 Profile**:
|
|
46
|
-
- `vue` - Vue 3 + TypeScript + Vite
|
|
47
|
-
- `react` - React + TypeScript + Vite
|
|
48
|
-
- `nestjs` - NestJS 后端框架
|
|
49
|
-
- `springboot` - Spring Boot 后端框架
|
|
50
|
-
- `node-tooling` - Node.js CLI/工具库
|
|
51
|
-
|
|
52
|
-
### 2. 项目初始化(老项目必做)
|
|
53
|
-
|
|
54
|
-
```text
|
|
55
|
-
在 IDE 中输入: 初始化项目规范
|
|
56
|
-
|
|
57
|
-
AI 会自动:
|
|
58
|
-
✅ 扫描项目技术栈
|
|
59
|
-
✅ 生成 01-项目概述.md
|
|
60
|
-
✅ 生成 03-项目结构.md
|
|
61
|
-
✅ 生成 context/PROJECT.md
|
|
62
|
-
✅ 归纳既有约定和能力规则
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
> 💡 **老项目接入必须先运行 project-init**,让 AI 了解项目现状再开始开发!
|
|
66
|
-
|
|
67
|
-
### 3. 开始需求开发
|
|
68
|
-
|
|
69
|
-
```text
|
|
70
|
-
/spec-start 创建订单列表页面,支持分页、筛选、状态切换
|
|
71
|
-
|
|
72
|
-
AI 自动执行:
|
|
73
|
-
1. 需求分析 → proposal.md / spec.md / tasks.md
|
|
74
|
-
2. 逐条执行任务 → Superpowers 四道关卡
|
|
75
|
-
3. 代码审查 → checklist.md
|
|
76
|
-
4. 归档交付 → .ai-spec/changes/
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
### 4. 分支代码评审(合并前必做)
|
|
80
|
-
|
|
81
|
-
```text
|
|
82
|
-
/branch-review # 仅技术风险
|
|
83
|
-
/branch-review docs/prd-order-module.md # 技术+业务风险
|
|
84
|
-
|
|
85
|
-
生成可视化 HTML 报告:
|
|
86
|
-
✅ 代码差异对比(并排/统一模式)
|
|
87
|
-
✅ 技术风险识别(性能/安全/错误处理)
|
|
88
|
-
✅ 业务风险分析(功能缺失/流程错误/需求覆盖度)
|
|
89
|
-
✅ 交互式报告(搜索/过滤/评论/导出)
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
## 📦 安装后会得到什么
|
|
93
|
-
|
|
94
|
-
```
|
|
95
|
-
your-project/
|
|
96
|
-
├── .agents/ # 规范源
|
|
97
|
-
│ ├── rules/ # 项目规则(01-项目概述/03-项目结构/能力规则)
|
|
98
|
-
│ ├── skills/ # 执行技能(execute-task/branch-code-reviewer等)
|
|
99
|
-
│ ├── commands/ # 命令模板源文件
|
|
100
|
-
│ └── registry/ # Profile 注册表
|
|
101
|
-
├── .ai-spec/ # 运行态数据
|
|
102
|
-
│ ├── manifest.json # 安装清单
|
|
103
|
-
│ └── changes/ # 需求交付产物
|
|
104
|
-
├── .qoder/ # Qoder IDE 适配
|
|
105
|
-
├── .cursor/ # Cursor IDE 适配
|
|
106
|
-
├── .claude/ # Claude Code IDE 适配
|
|
107
|
-
├── openspec/ # OpenSpec 流程模板
|
|
108
|
-
└── [你的业务代码] # 完全不受影响!
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
## 🎮 核心命令
|
|
112
|
-
|
|
113
|
-
### IDE 命令(在 Qoder/Cursor/Claude 中使用)
|
|
114
|
-
|
|
115
|
-
| 命令 | 用途 | 阶段 |
|
|
116
|
-
|------|------|------|
|
|
117
|
-
| `/project-init` | 初始化项目规范 | 接入时 |
|
|
118
|
-
| `/spec-start` | 启动需求交付 | 新需求 |
|
|
119
|
-
| `/spec-update` | 增量更新需求 | 需求变更 |
|
|
120
|
-
| `/spec-continue` | 继续当前 run | 恢复开发 |
|
|
121
|
-
| `/spec-status` | 查看当前状态 | 任意时 |
|
|
122
|
-
| `/spec-stop` | 暂停当前 run | 暂停 |
|
|
123
|
-
| `/branch-review` | 分支代码评审 | 合并前 |
|
|
124
|
-
|
|
125
|
-
### CLI 命令
|
|
126
|
-
|
|
127
|
-
```bash
|
|
128
|
-
# 安装
|
|
129
|
-
npx @engineered/ai-spec-auto@latest init .
|
|
130
|
-
|
|
131
|
-
# 更新
|
|
132
|
-
npx @engineered/ai-spec-auto@latest update .
|
|
133
|
-
|
|
134
|
-
# 检查
|
|
135
|
-
npx @engineered/ai-spec-auto@latest check .
|
|
136
|
-
|
|
137
|
-
# 卸载
|
|
138
|
-
npx @engineered/ai-spec-auto@latest uninstall .
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
## 🏗️ 工作流程
|
|
142
|
-
|
|
143
|
-
### 完整交付流程
|
|
144
|
-
|
|
145
|
-
```
|
|
146
|
-
用户需求
|
|
147
|
-
↓
|
|
148
|
-
/spec-start 触发 OpenSpec 流程
|
|
149
|
-
↓
|
|
150
|
-
[OpenSpec 需求治理]
|
|
151
|
-
├─ task-orchestrator 分析需求,确定流程
|
|
152
|
-
├─ requirement-analyst 产出 proposal/spec/tasks
|
|
153
|
-
└─ 生成 .ai-spec/changes/[id]/tasks.md
|
|
154
|
-
↓
|
|
155
|
-
[Superpowers 代码实现]
|
|
156
|
-
├─ 逐条执行 tasks.md
|
|
157
|
-
├─ 每条任务走四道关卡:
|
|
158
|
-
│ 1. 头脑风暴 (思考边界和风险)
|
|
159
|
-
│ 2. TDD 编码 (RED→GREEN→REFACTOR)
|
|
160
|
-
│ 3. 双重审查 (设计对齐+质量门禁)
|
|
161
|
-
│ 4. 审计汇报 (结构化输出)
|
|
162
|
-
└─ 更新 tasks.md 状态
|
|
163
|
-
↓
|
|
164
|
-
code-guardian 验收
|
|
165
|
-
├─ checklist.md (验收清单)
|
|
166
|
-
└─ iterations.md (迭代记录)
|
|
167
|
-
↓
|
|
168
|
-
/spec-status → 交付完成 ✅
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
### 小需求轻量流程
|
|
172
|
-
|
|
173
|
-
| 场景 | 推荐入口 | 流程 |
|
|
174
|
-
|------|---------|------|
|
|
175
|
-
| 新功能/跨模块改动 | `/spec-start` | prd-to-delivery (完整) |
|
|
176
|
-
| 当前 run 内小修正 | `/spec-update` | patch / scope-delta |
|
|
177
|
-
| 归档前发现不对 | 自然语言 | archive-fix |
|
|
178
|
-
| 已归档内容补丁 | 自然语言 | followup-patch |
|
|
179
|
-
| 低风险单点修复 | 自然语言 | bugfix-to-verification |
|
|
180
|
-
|
|
181
|
-
**判断原则**:
|
|
182
|
-
- 涉及 API/路由/全局状态/权限/支付 → 升级回完整流程
|
|
183
|
-
- 要求留痕/归档/评审 → 走完整 OpenSpec
|
|
184
|
-
|
|
185
|
-
## 📚 使用场景
|
|
186
|
-
|
|
187
|
-
### 场景 1: 老项目接入
|
|
188
|
-
|
|
189
|
-
```bash
|
|
190
|
-
# 1. 安装
|
|
191
|
-
npx @engineered/ai-spec-auto@latest init .
|
|
192
|
-
|
|
193
|
-
# 2. 初始化(自动梳理项目)
|
|
194
|
-
用户: 初始化项目规范
|
|
195
|
-
|
|
196
|
-
# 3. 验证生成内容
|
|
197
|
-
cat .agents/rules/01-项目概述.md
|
|
198
|
-
cat .agents/rules/03-项目结构.md
|
|
199
|
-
|
|
200
|
-
# 4. 开始开发
|
|
201
|
-
/spec-start 新功能...
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
### 场景 2: 新功能开发
|
|
205
|
-
|
|
206
|
-
```text
|
|
207
|
-
/spec-start 创建用户管理模块
|
|
208
|
-
|
|
209
|
-
AI 产出:
|
|
210
|
-
✅ proposal.md - 业务目标、工程目标、复用策略
|
|
211
|
-
✅ spec.md - 可测试的场景和验收标准
|
|
212
|
-
✅ tasks.md - 可执行的任务清单
|
|
213
|
-
|
|
214
|
-
逐条执行任务:
|
|
215
|
-
✅ Superpowers 四道关卡保证质量
|
|
216
|
-
✅ 审计报告可追溯
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
### 场景 3: 合并前评审
|
|
220
|
-
|
|
221
|
-
```text
|
|
222
|
-
/branch-review docs/prd-user-module.md
|
|
223
|
-
|
|
224
|
-
生成 HTML 报告:
|
|
225
|
-
✅ 技术风险: 12个 (🔴2 🟡5 🔵4 ⚪1)
|
|
226
|
-
✅ 业务风险: 5个 (🔴2 🟡3)
|
|
227
|
-
✅ 需求覆盖度: 85%
|
|
228
|
-
✅ 整体通过率: 78%
|
|
229
|
-
|
|
230
|
-
修复风险后重新评审验证
|
|
231
|
-
```
|
|
232
|
-
|
|
233
|
-
## 🔧 高级用法
|
|
234
|
-
|
|
235
|
-
### Monorepo 支持
|
|
236
|
-
|
|
237
|
-
```bash
|
|
238
|
-
# 安装到子包
|
|
239
|
-
npx @engineered/ai-spec-auto@latest init . --package packages/web
|
|
240
|
-
|
|
241
|
-
# 在仓库根安装
|
|
242
|
-
npx @engineered/ai-spec-auto@latest init . --workspace-root
|
|
243
|
-
```
|
|
244
|
-
|
|
245
|
-
### 自定义规则
|
|
246
|
-
|
|
247
|
-
```bash
|
|
248
|
-
# 启用可定制规则全集
|
|
249
|
-
npx @engineered/ai-spec-auto@latest init . --custom-rules
|
|
250
|
-
|
|
251
|
-
# 使用标准规则集
|
|
252
|
-
npx @engineered/ai-spec-auto@latest init . --standard-rules
|
|
253
|
-
```
|
|
254
|
-
|
|
255
|
-
### 多技术栈项目
|
|
256
|
-
|
|
257
|
-
```bash
|
|
258
|
-
# 一次安装多个技术栈
|
|
259
|
-
npx @engineered/ai-spec-auto@latest init . --profiles vue,nestjs
|
|
260
|
-
```
|
|
261
|
-
|
|
262
|
-
### 选择性更新
|
|
263
|
-
|
|
264
|
-
```bash
|
|
265
|
-
# 只更新规则与命令
|
|
266
|
-
npx @engineered/ai-spec-auto@latest update . --skip-skills --skip-configs --skip-openspec
|
|
267
|
-
|
|
268
|
-
# 强制覆盖本地规则
|
|
269
|
-
npx @engineered/ai-spec-auto@latest update . --force-update-rules
|
|
270
|
-
```
|
|
271
|
-
|
|
272
|
-
## 🌐 支持的 IDE
|
|
273
|
-
|
|
274
|
-
| IDE | 规则链接 | 技能链接 | 命令模板 | MCP 配置 |
|
|
275
|
-
|-----|---------|---------|---------|---------|
|
|
276
|
-
| **Qoder** | ✅ | ✅ | ✅ | ✅ |
|
|
277
|
-
| **Cursor** | ✅ | ✅ | ✅ | ✅ |
|
|
278
|
-
| **Claude Code** | ✅ | ✅ | ✅ | ❌ |
|
|
279
|
-
| **OpenCode** | ✅ | ✅ | ✅ | ❌ |
|
|
280
|
-
| **Trae** | ✅ | ✅ | ✅ | ❌ |
|
|
281
|
-
| **Codex** | ✅ | ✅ | ✅ | ❌ |
|
|
282
|
-
|
|
283
|
-
> 💡 **命令模板统一管理**: 所有 IDE 的命令模板都存放在 `.agents/commands/common/`,安装时自动映射到各 IDE 的 `commands/` 目录。
|
|
284
|
-
|
|
285
|
-
## 📖 详细文档
|
|
286
|
-
|
|
287
|
-
### 快速入门
|
|
288
|
-
|
|
289
|
-
- [5 分钟快速上手](docs/quick-start.md)
|
|
290
|
-
- [安装指南](docs/install-guide.md)
|
|
291
|
-
- [老项目接入指南](docs/legacy-project-onboarding-guide.md) 🆕
|
|
292
|
-
- [分支代码评审使用指南](docs/branch-code-reviewer-guide.md) 🆕
|
|
293
|
-
|
|
294
|
-
### 核心机制
|
|
295
|
-
|
|
296
|
-
- [Superpowers 与 OpenSpec 协同机制](docs/superpowers-and-openspec-guide.md) 🆕
|
|
297
|
-
- [IDE 命令模板映射机制](docs/ide-command-mapping-guide.md) 🆕
|
|
298
|
-
- [OpenSpec / 协议流说明](docs/openspec-guide.md)
|
|
299
|
-
- [小需求与补丁修正指南](docs/four/小需求与补丁修正指南.md)
|
|
300
|
-
|
|
301
|
-
### 架构与治理
|
|
302
|
-
|
|
303
|
-
- [第四阶段文档入口](docs/four/README.md)
|
|
304
|
-
- [架构设计与治理说明](docs/four/架构设计与治理说明.md)
|
|
305
|
-
- [项目介绍与运行机制说明](docs/four/项目介绍与运行机制说明.md)
|
|
306
|
-
- [开发最佳实践指南](docs/four/开发最佳实践指南.md)
|
|
307
|
-
|
|
308
|
-
### 其他
|
|
309
|
-
|
|
310
|
-
- [文档索引](docs/README.md)
|
|
311
|
-
- [培训大纲](docs/training-outline.md)
|
|
312
|
-
- [需求示例:从发起到归档](docs/four/需求示例-从发起到归档.md)
|
|
313
|
-
|
|
314
|
-
## ⚙️ 配置说明
|
|
315
|
-
|
|
316
|
-
### npm Registry 配置
|
|
317
|
-
|
|
318
|
-
如果本机默认使用内网 npm registry,需要配置 `@engineered` 作用域走公共 npm:
|
|
319
|
-
|
|
320
|
-
```ini
|
|
321
|
-
# ~/.npmrc
|
|
322
|
-
@engineered:registry=https://registry.npmjs.org/
|
|
323
|
-
```
|
|
324
|
-
|
|
325
|
-
### 匿名使用统计(可选)
|
|
326
|
-
|
|
327
|
-
默认关闭上报。如需开启:
|
|
328
|
-
|
|
329
|
-
```json
|
|
330
|
-
// ~/.ai-spec-auto/config.json
|
|
331
|
-
{
|
|
332
|
-
"visualUrl": "http://your-visual-server:3000",
|
|
333
|
-
"disabled": false
|
|
334
|
-
}
|
|
335
|
-
```
|
|
336
|
-
|
|
337
|
-
关闭统计:
|
|
338
|
-
|
|
339
|
-
```bash
|
|
340
|
-
export AI_SPEC_TELEMETRY_DISABLED=1
|
|
341
|
-
```
|
|
342
|
-
|
|
343
|
-
详见下方[匿名使用统计](#-匿名使用统计)章节。
|
|
344
|
-
|
|
345
|
-
## 🔮 后续规划
|
|
346
|
-
|
|
347
|
-
### 短期
|
|
348
|
-
- 继续跑稳 `prd-to-delivery` 主链和 `bugfix-to-verification` 轻量链
|
|
349
|
-
- 降低 `init / sync / manifest` 的接入摩擦
|
|
350
|
-
- 让普通开发者先用起来,不被底层协议细节拦在门外
|
|
351
|
-
|
|
352
|
-
### 中期
|
|
353
|
-
- Hub 负责资产管理与场景组合
|
|
354
|
-
- Manifest 成为能力组合的稳定描述
|
|
355
|
-
- 补齐 `git worktree` 支持,支撑多需求并行开发
|
|
356
|
-
- CLI 和 IDE 入口承担更轻量的状态提示与切换
|
|
357
|
-
|
|
358
|
-
### 中长期
|
|
359
|
-
- 补齐 OpenClaw 对接,形成远程入口与团队协同控制面
|
|
360
|
-
- CI/CD 校验纳入统一治理链
|
|
361
|
-
- 从本地开发到持续交付的一体化约束
|
|
362
|
-
|
|
363
|
-
## 🤝 贡献指南
|
|
364
|
-
|
|
365
|
-
欢迎提交 Issue 和 Pull Request!
|
|
366
|
-
|
|
367
|
-
- 报告问题: https://github.com/
|
|
368
|
-
- 提交 PR: https://github.com/
|
|
369
|
-
|
|
370
|
-
## 📄 许可证
|
|
371
|
-
|
|
372
|
-
[MIT License](LICENSE)
|
|
373
|
-
|
|
374
|
-
---
|
|
375
|
-
|
|
376
|
-
## 📊 匿名使用统计
|
|
377
|
-
|
|
378
|
-
<details>
|
|
379
|
-
<summary>点击展开详细说明</summary>
|
|
380
|
-
|
|
381
|
-
`bin/telemetry/` 是一个**隔离的切面模块**,用于向私有部署的 [`engineered-spec-visual`](https://github.com/
|
|
382
|
-
|
|
383
|
-
### 默认行为
|
|
384
|
-
|
|
385
|
-
仓库内置默认配置**关闭上报**(`disabled: true`)。需要统计时自行配置 Visual 地址并设置 `disabled: false`。
|
|
386
|
-
|
|
387
|
-
### 关闭统计
|
|
388
|
-
|
|
389
|
-
```bash
|
|
390
|
-
# 临时(当前会话)
|
|
391
|
-
export AI_SPEC_TELEMETRY_DISABLED=1
|
|
392
|
-
|
|
393
|
-
# 永久(写入配置)
|
|
394
|
-
mkdir -p ~/.ai-spec-auto
|
|
395
|
-
echo '{"disabled": true}' > ~/.ai-spec-auto/config.json
|
|
396
|
-
```
|
|
397
|
-
|
|
398
|
-
### 配置字段
|
|
399
|
-
|
|
400
|
-
| 字段 | 环境变量 | 配置 Key | 说明 |
|
|
401
|
-
|------|---------|----------|------|
|
|
402
|
-
| Visual 地址 | `AI_SPEC_VISUAL_URL` | `visualUrl` | 空值则不发送 |
|
|
403
|
-
| 总开关 | `AI_SPEC_TELEMETRY_DISABLED=1` | `disabled: true` | 任一源为真即关闭 |
|
|
404
|
-
| 鉴权密钥 | `AI_SPEC_TELEMETRY_SECRET` | `secret` | 与服务端一致 |
|
|
405
|
-
| 调试输出 | `AI_SPEC_TELEMETRY_DEBUG=1` | — | 排查问题时用 |
|
|
406
|
-
|
|
407
|
-
### 隐私保证
|
|
408
|
-
|
|
409
|
-
- **唯一标识**: 来自 `node-machine-id`,缺失时用 SHA256 兜底
|
|
410
|
-
- **项目路径**: 以 SHA256 哈希形式上报,不包含源码/绝对路径
|
|
411
|
-
- **健康探测**: 上报前 HEAD 请求(500ms 超时),失败自动跳过
|
|
412
|
-
- **删除即失效**: 模块移除不影响 CLI 正常工作
|
|
413
|
-
|
|
414
|
-
</details>
|
|
415
|
-
|
|
416
|
-
## 📝 兼容说明
|
|
417
|
-
|
|
418
|
-
以下能力继续保留:
|
|
419
|
-
|
|
420
|
-
- ✅ `install.sh` / `install.ps1` 脚本入口
|
|
421
|
-
- ✅ `--level L1/L2/L3` 渐进式接入参数
|
|
422
|
-
- ✅ `--custom-rules` 自定义规则
|
|
423
|
-
- ✅ 细粒度 `update` 选择性更新
|
|
424
|
-
- ✅ Monorepo 目标选择
|
|
425
|
-
- ✅ `configs/` 增量补齐
|
|
426
|
-
|
|
427
|
-
**重点收口**:
|
|
428
|
-
- 安装实现统一到 Node 核心
|
|
429
|
-
- Bash/PowerShell 只保留薄壳入口
|
|
430
|
-
- README 收成产品入口页
|
|
431
|
-
- Registry 说明集中统一
|
|
432
|
-
|
|
433
|
-
协议主链、专家链和运行时状态机没有因为入口收口而改变。
|
|
1
|
+
# ai-spec-auto
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@engineered/ai-spec-auto)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](https://github.com/gong-chick/engineered-spec)
|
|
6
|
+
|
|
7
|
+
> **它不是单个 AI 工具的替代品,而是一套把需求、实现、检查、归档串成团队开发链路的项目级交付底座。**
|
|
8
|
+
|
|
9
|
+
`ai-spec-auto` 是一套面向前端项目的 **AI 规范驱动开发底座**。它把项目规则、专家资产、IDE 命令入口、OpenSpec 交付产物和 `.ai-spec` 运行状态放进同一个项目里,让 AI 开发不再只停留在对话里,而是能够按统一约束执行、留痕、归档和复用。
|
|
10
|
+
|
|
11
|
+
## ✨ 核心特性
|
|
12
|
+
|
|
13
|
+
### 🎯 解决的问题
|
|
14
|
+
|
|
15
|
+
团队引入 AI 后最常见的痛点:
|
|
16
|
+
|
|
17
|
+
- ❌ 需求没收敛,AI 就开始改代码,返工成本高
|
|
18
|
+
- ❌ 规范散落在文档和口头经验里,难以稳定复用
|
|
19
|
+
- ❌ 过程只在聊天记录,缺少可追溯的交付产物
|
|
20
|
+
- ❌ 新功能和简单修复混用同一流程,效率和治理难平衡
|
|
21
|
+
|
|
22
|
+
### ✅ 提供的能力
|
|
23
|
+
|
|
24
|
+
| 能力 | 说明 |
|
|
25
|
+
|------|------|
|
|
26
|
+
| **需求治理** | OpenSpec 协议,从需求到任务的标准化流程 |
|
|
27
|
+
| **规范驱动** | 项目规则、编码规范、目录约定自动加载 |
|
|
28
|
+
| **质量控制** | Superpowers 四道关卡(头脑风暴→TDD→审查→审计) |
|
|
29
|
+
| **分支评审** | 技术风险+业务风险双维度分析,可视化 HTML 报告 |
|
|
30
|
+
| **多 IDE 支持** | Qoder、Cursor、Claude Code、OpenCode、Trae、Codex |
|
|
31
|
+
| **渐进式接入** | L1/L2/L3 三层策略,老项目零侵入接入 |
|
|
32
|
+
|
|
33
|
+
## 🚀 快速开始
|
|
34
|
+
|
|
35
|
+
### 1. 安装
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
# 推荐:单次指定公共 registry
|
|
39
|
+
npx --yes --registry https://registry.npmjs.org/ @engineered/ai-spec-auto@latest init . --profile vue -y
|
|
40
|
+
|
|
41
|
+
# 或已配置 ~/.npmrc 后
|
|
42
|
+
npx @engineered/ai-spec-auto@latest init .
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
**支持的 Profile**:
|
|
46
|
+
- `vue` - Vue 3 + TypeScript + Vite
|
|
47
|
+
- `react` - React + TypeScript + Vite
|
|
48
|
+
- `nestjs` - NestJS 后端框架
|
|
49
|
+
- `springboot` - Spring Boot 后端框架
|
|
50
|
+
- `node-tooling` - Node.js CLI/工具库
|
|
51
|
+
|
|
52
|
+
### 2. 项目初始化(老项目必做)
|
|
53
|
+
|
|
54
|
+
```text
|
|
55
|
+
在 IDE 中输入: 初始化项目规范
|
|
56
|
+
|
|
57
|
+
AI 会自动:
|
|
58
|
+
✅ 扫描项目技术栈
|
|
59
|
+
✅ 生成 01-项目概述.md
|
|
60
|
+
✅ 生成 03-项目结构.md
|
|
61
|
+
✅ 生成 context/PROJECT.md
|
|
62
|
+
✅ 归纳既有约定和能力规则
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
> 💡 **老项目接入必须先运行 project-init**,让 AI 了解项目现状再开始开发!
|
|
66
|
+
|
|
67
|
+
### 3. 开始需求开发
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
/spec-start 创建订单列表页面,支持分页、筛选、状态切换
|
|
71
|
+
|
|
72
|
+
AI 自动执行:
|
|
73
|
+
1. 需求分析 → proposal.md / spec.md / tasks.md
|
|
74
|
+
2. 逐条执行任务 → Superpowers 四道关卡
|
|
75
|
+
3. 代码审查 → checklist.md
|
|
76
|
+
4. 归档交付 → .ai-spec/changes/
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### 4. 分支代码评审(合并前必做)
|
|
80
|
+
|
|
81
|
+
```text
|
|
82
|
+
/branch-review # 仅技术风险
|
|
83
|
+
/branch-review docs/prd-order-module.md # 技术+业务风险
|
|
84
|
+
|
|
85
|
+
生成可视化 HTML 报告:
|
|
86
|
+
✅ 代码差异对比(并排/统一模式)
|
|
87
|
+
✅ 技术风险识别(性能/安全/错误处理)
|
|
88
|
+
✅ 业务风险分析(功能缺失/流程错误/需求覆盖度)
|
|
89
|
+
✅ 交互式报告(搜索/过滤/评论/导出)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## 📦 安装后会得到什么
|
|
93
|
+
|
|
94
|
+
```
|
|
95
|
+
your-project/
|
|
96
|
+
├── .agents/ # 规范源
|
|
97
|
+
│ ├── rules/ # 项目规则(01-项目概述/03-项目结构/能力规则)
|
|
98
|
+
│ ├── skills/ # 执行技能(execute-task/branch-code-reviewer等)
|
|
99
|
+
│ ├── commands/ # 命令模板源文件
|
|
100
|
+
│ └── registry/ # Profile 注册表
|
|
101
|
+
├── .ai-spec/ # 运行态数据
|
|
102
|
+
│ ├── manifest.json # 安装清单
|
|
103
|
+
│ └── changes/ # 需求交付产物
|
|
104
|
+
├── .qoder/ # Qoder IDE 适配
|
|
105
|
+
├── .cursor/ # Cursor IDE 适配
|
|
106
|
+
├── .claude/ # Claude Code IDE 适配
|
|
107
|
+
├── openspec/ # OpenSpec 流程模板
|
|
108
|
+
└── [你的业务代码] # 完全不受影响!
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## 🎮 核心命令
|
|
112
|
+
|
|
113
|
+
### IDE 命令(在 Qoder/Cursor/Claude 中使用)
|
|
114
|
+
|
|
115
|
+
| 命令 | 用途 | 阶段 |
|
|
116
|
+
|------|------|------|
|
|
117
|
+
| `/project-init` | 初始化项目规范 | 接入时 |
|
|
118
|
+
| `/spec-start` | 启动需求交付 | 新需求 |
|
|
119
|
+
| `/spec-update` | 增量更新需求 | 需求变更 |
|
|
120
|
+
| `/spec-continue` | 继续当前 run | 恢复开发 |
|
|
121
|
+
| `/spec-status` | 查看当前状态 | 任意时 |
|
|
122
|
+
| `/spec-stop` | 暂停当前 run | 暂停 |
|
|
123
|
+
| `/branch-review` | 分支代码评审 | 合并前 |
|
|
124
|
+
|
|
125
|
+
### CLI 命令
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
# 安装
|
|
129
|
+
npx @engineered/ai-spec-auto@latest init .
|
|
130
|
+
|
|
131
|
+
# 更新
|
|
132
|
+
npx @engineered/ai-spec-auto@latest update .
|
|
133
|
+
|
|
134
|
+
# 检查
|
|
135
|
+
npx @engineered/ai-spec-auto@latest check .
|
|
136
|
+
|
|
137
|
+
# 卸载
|
|
138
|
+
npx @engineered/ai-spec-auto@latest uninstall .
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## 🏗️ 工作流程
|
|
142
|
+
|
|
143
|
+
### 完整交付流程
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
用户需求
|
|
147
|
+
↓
|
|
148
|
+
/spec-start 触发 OpenSpec 流程
|
|
149
|
+
↓
|
|
150
|
+
[OpenSpec 需求治理]
|
|
151
|
+
├─ task-orchestrator 分析需求,确定流程
|
|
152
|
+
├─ requirement-analyst 产出 proposal/spec/tasks
|
|
153
|
+
└─ 生成 .ai-spec/changes/[id]/tasks.md
|
|
154
|
+
↓
|
|
155
|
+
[Superpowers 代码实现]
|
|
156
|
+
├─ 逐条执行 tasks.md
|
|
157
|
+
├─ 每条任务走四道关卡:
|
|
158
|
+
│ 1. 头脑风暴 (思考边界和风险)
|
|
159
|
+
│ 2. TDD 编码 (RED→GREEN→REFACTOR)
|
|
160
|
+
│ 3. 双重审查 (设计对齐+质量门禁)
|
|
161
|
+
│ 4. 审计汇报 (结构化输出)
|
|
162
|
+
└─ 更新 tasks.md 状态
|
|
163
|
+
↓
|
|
164
|
+
code-guardian 验收
|
|
165
|
+
├─ checklist.md (验收清单)
|
|
166
|
+
└─ iterations.md (迭代记录)
|
|
167
|
+
↓
|
|
168
|
+
/spec-status → 交付完成 ✅
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### 小需求轻量流程
|
|
172
|
+
|
|
173
|
+
| 场景 | 推荐入口 | 流程 |
|
|
174
|
+
|------|---------|------|
|
|
175
|
+
| 新功能/跨模块改动 | `/spec-start` | prd-to-delivery (完整) |
|
|
176
|
+
| 当前 run 内小修正 | `/spec-update` | patch / scope-delta |
|
|
177
|
+
| 归档前发现不对 | 自然语言 | archive-fix |
|
|
178
|
+
| 已归档内容补丁 | 自然语言 | followup-patch |
|
|
179
|
+
| 低风险单点修复 | 自然语言 | bugfix-to-verification |
|
|
180
|
+
|
|
181
|
+
**判断原则**:
|
|
182
|
+
- 涉及 API/路由/全局状态/权限/支付 → 升级回完整流程
|
|
183
|
+
- 要求留痕/归档/评审 → 走完整 OpenSpec
|
|
184
|
+
|
|
185
|
+
## 📚 使用场景
|
|
186
|
+
|
|
187
|
+
### 场景 1: 老项目接入
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
# 1. 安装
|
|
191
|
+
npx @engineered/ai-spec-auto@latest init .
|
|
192
|
+
|
|
193
|
+
# 2. 初始化(自动梳理项目)
|
|
194
|
+
用户: 初始化项目规范
|
|
195
|
+
|
|
196
|
+
# 3. 验证生成内容
|
|
197
|
+
cat .agents/rules/01-项目概述.md
|
|
198
|
+
cat .agents/rules/03-项目结构.md
|
|
199
|
+
|
|
200
|
+
# 4. 开始开发
|
|
201
|
+
/spec-start 新功能...
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
### 场景 2: 新功能开发
|
|
205
|
+
|
|
206
|
+
```text
|
|
207
|
+
/spec-start 创建用户管理模块
|
|
208
|
+
|
|
209
|
+
AI 产出:
|
|
210
|
+
✅ proposal.md - 业务目标、工程目标、复用策略
|
|
211
|
+
✅ spec.md - 可测试的场景和验收标准
|
|
212
|
+
✅ tasks.md - 可执行的任务清单
|
|
213
|
+
|
|
214
|
+
逐条执行任务:
|
|
215
|
+
✅ Superpowers 四道关卡保证质量
|
|
216
|
+
✅ 审计报告可追溯
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
### 场景 3: 合并前评审
|
|
220
|
+
|
|
221
|
+
```text
|
|
222
|
+
/branch-review docs/prd-user-module.md
|
|
223
|
+
|
|
224
|
+
生成 HTML 报告:
|
|
225
|
+
✅ 技术风险: 12个 (🔴2 🟡5 🔵4 ⚪1)
|
|
226
|
+
✅ 业务风险: 5个 (🔴2 🟡3)
|
|
227
|
+
✅ 需求覆盖度: 85%
|
|
228
|
+
✅ 整体通过率: 78%
|
|
229
|
+
|
|
230
|
+
修复风险后重新评审验证
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
## 🔧 高级用法
|
|
234
|
+
|
|
235
|
+
### Monorepo 支持
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
# 安装到子包
|
|
239
|
+
npx @engineered/ai-spec-auto@latest init . --package packages/web
|
|
240
|
+
|
|
241
|
+
# 在仓库根安装
|
|
242
|
+
npx @engineered/ai-spec-auto@latest init . --workspace-root
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
### 自定义规则
|
|
246
|
+
|
|
247
|
+
```bash
|
|
248
|
+
# 启用可定制规则全集
|
|
249
|
+
npx @engineered/ai-spec-auto@latest init . --custom-rules
|
|
250
|
+
|
|
251
|
+
# 使用标准规则集
|
|
252
|
+
npx @engineered/ai-spec-auto@latest init . --standard-rules
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
### 多技术栈项目
|
|
256
|
+
|
|
257
|
+
```bash
|
|
258
|
+
# 一次安装多个技术栈
|
|
259
|
+
npx @engineered/ai-spec-auto@latest init . --profiles vue,nestjs
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
### 选择性更新
|
|
263
|
+
|
|
264
|
+
```bash
|
|
265
|
+
# 只更新规则与命令
|
|
266
|
+
npx @engineered/ai-spec-auto@latest update . --skip-skills --skip-configs --skip-openspec
|
|
267
|
+
|
|
268
|
+
# 强制覆盖本地规则
|
|
269
|
+
npx @engineered/ai-spec-auto@latest update . --force-update-rules
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
## 🌐 支持的 IDE
|
|
273
|
+
|
|
274
|
+
| IDE | 规则链接 | 技能链接 | 命令模板 | MCP 配置 |
|
|
275
|
+
|-----|---------|---------|---------|---------|
|
|
276
|
+
| **Qoder** | ✅ | ✅ | ✅ | ✅ |
|
|
277
|
+
| **Cursor** | ✅ | ✅ | ✅ | ✅ |
|
|
278
|
+
| **Claude Code** | ✅ | ✅ | ✅ | ❌ |
|
|
279
|
+
| **OpenCode** | ✅ | ✅ | ✅ | ❌ |
|
|
280
|
+
| **Trae** | ✅ | ✅ | ✅ | ❌ |
|
|
281
|
+
| **Codex** | ✅ | ✅ | ✅ | ❌ |
|
|
282
|
+
|
|
283
|
+
> 💡 **命令模板统一管理**: 所有 IDE 的命令模板都存放在 `.agents/commands/common/`,安装时自动映射到各 IDE 的 `commands/` 目录。
|
|
284
|
+
|
|
285
|
+
## 📖 详细文档
|
|
286
|
+
|
|
287
|
+
### 快速入门
|
|
288
|
+
|
|
289
|
+
- [5 分钟快速上手](docs/quick-start.md)
|
|
290
|
+
- [安装指南](docs/install-guide.md)
|
|
291
|
+
- [老项目接入指南](docs/legacy-project-onboarding-guide.md) 🆕
|
|
292
|
+
- [分支代码评审使用指南](docs/branch-code-reviewer-guide.md) 🆕
|
|
293
|
+
|
|
294
|
+
### 核心机制
|
|
295
|
+
|
|
296
|
+
- [Superpowers 与 OpenSpec 协同机制](docs/superpowers-and-openspec-guide.md) 🆕
|
|
297
|
+
- [IDE 命令模板映射机制](docs/ide-command-mapping-guide.md) 🆕
|
|
298
|
+
- [OpenSpec / 协议流说明](docs/openspec-guide.md)
|
|
299
|
+
- [小需求与补丁修正指南](docs/four/小需求与补丁修正指南.md)
|
|
300
|
+
|
|
301
|
+
### 架构与治理
|
|
302
|
+
|
|
303
|
+
- [第四阶段文档入口](docs/four/README.md)
|
|
304
|
+
- [架构设计与治理说明](docs/four/架构设计与治理说明.md)
|
|
305
|
+
- [项目介绍与运行机制说明](docs/four/项目介绍与运行机制说明.md)
|
|
306
|
+
- [开发最佳实践指南](docs/four/开发最佳实践指南.md)
|
|
307
|
+
|
|
308
|
+
### 其他
|
|
309
|
+
|
|
310
|
+
- [文档索引](docs/README.md)
|
|
311
|
+
- [培训大纲](docs/training-outline.md)
|
|
312
|
+
- [需求示例:从发起到归档](docs/four/需求示例-从发起到归档.md)
|
|
313
|
+
|
|
314
|
+
## ⚙️ 配置说明
|
|
315
|
+
|
|
316
|
+
### npm Registry 配置
|
|
317
|
+
|
|
318
|
+
如果本机默认使用内网 npm registry,需要配置 `@engineered` 作用域走公共 npm:
|
|
319
|
+
|
|
320
|
+
```ini
|
|
321
|
+
# ~/.npmrc
|
|
322
|
+
@engineered:registry=https://registry.npmjs.org/
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
### 匿名使用统计(可选)
|
|
326
|
+
|
|
327
|
+
默认关闭上报。如需开启:
|
|
328
|
+
|
|
329
|
+
```json
|
|
330
|
+
// ~/.ai-spec-auto/config.json
|
|
331
|
+
{
|
|
332
|
+
"visualUrl": "http://your-visual-server:3000",
|
|
333
|
+
"disabled": false
|
|
334
|
+
}
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
关闭统计:
|
|
338
|
+
|
|
339
|
+
```bash
|
|
340
|
+
export AI_SPEC_TELEMETRY_DISABLED=1
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
详见下方[匿名使用统计](#-匿名使用统计)章节。
|
|
344
|
+
|
|
345
|
+
## 🔮 后续规划
|
|
346
|
+
|
|
347
|
+
### 短期
|
|
348
|
+
- 继续跑稳 `prd-to-delivery` 主链和 `bugfix-to-verification` 轻量链
|
|
349
|
+
- 降低 `init / sync / manifest` 的接入摩擦
|
|
350
|
+
- 让普通开发者先用起来,不被底层协议细节拦在门外
|
|
351
|
+
|
|
352
|
+
### 中期
|
|
353
|
+
- Hub 负责资产管理与场景组合
|
|
354
|
+
- Manifest 成为能力组合的稳定描述
|
|
355
|
+
- 补齐 `git worktree` 支持,支撑多需求并行开发
|
|
356
|
+
- CLI 和 IDE 入口承担更轻量的状态提示与切换
|
|
357
|
+
|
|
358
|
+
### 中长期
|
|
359
|
+
- 补齐 OpenClaw 对接,形成远程入口与团队协同控制面
|
|
360
|
+
- CI/CD 校验纳入统一治理链
|
|
361
|
+
- 从本地开发到持续交付的一体化约束
|
|
362
|
+
|
|
363
|
+
## 🤝 贡献指南
|
|
364
|
+
|
|
365
|
+
欢迎提交 Issue 和 Pull Request!
|
|
366
|
+
|
|
367
|
+
- 报告问题: https://github.com/gong-chick/engineered-spec/issues
|
|
368
|
+
- 提交 PR: https://github.com/gong-chick/engineered-spec/pulls
|
|
369
|
+
|
|
370
|
+
## 📄 许可证
|
|
371
|
+
|
|
372
|
+
[MIT License](LICENSE)
|
|
373
|
+
|
|
374
|
+
---
|
|
375
|
+
|
|
376
|
+
## 📊 匿名使用统计
|
|
377
|
+
|
|
378
|
+
<details>
|
|
379
|
+
<summary>点击展开详细说明</summary>
|
|
380
|
+
|
|
381
|
+
`bin/telemetry/` 是一个**隔离的切面模块**,用于向私有部署的 [`engineered-spec-visual`](https://github.com/gong-chick/engineered-spec-visual) 上报 CLI 安装与使用情况。
|
|
382
|
+
|
|
383
|
+
### 默认行为
|
|
384
|
+
|
|
385
|
+
仓库内置默认配置**关闭上报**(`disabled: true`)。需要统计时自行配置 Visual 地址并设置 `disabled: false`。
|
|
386
|
+
|
|
387
|
+
### 关闭统计
|
|
388
|
+
|
|
389
|
+
```bash
|
|
390
|
+
# 临时(当前会话)
|
|
391
|
+
export AI_SPEC_TELEMETRY_DISABLED=1
|
|
392
|
+
|
|
393
|
+
# 永久(写入配置)
|
|
394
|
+
mkdir -p ~/.ai-spec-auto
|
|
395
|
+
echo '{"disabled": true}' > ~/.ai-spec-auto/config.json
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
### 配置字段
|
|
399
|
+
|
|
400
|
+
| 字段 | 环境变量 | 配置 Key | 说明 |
|
|
401
|
+
|------|---------|----------|------|
|
|
402
|
+
| Visual 地址 | `AI_SPEC_VISUAL_URL` | `visualUrl` | 空值则不发送 |
|
|
403
|
+
| 总开关 | `AI_SPEC_TELEMETRY_DISABLED=1` | `disabled: true` | 任一源为真即关闭 |
|
|
404
|
+
| 鉴权密钥 | `AI_SPEC_TELEMETRY_SECRET` | `secret` | 与服务端一致 |
|
|
405
|
+
| 调试输出 | `AI_SPEC_TELEMETRY_DEBUG=1` | — | 排查问题时用 |
|
|
406
|
+
|
|
407
|
+
### 隐私保证
|
|
408
|
+
|
|
409
|
+
- **唯一标识**: 来自 `node-machine-id`,缺失时用 SHA256 兜底
|
|
410
|
+
- **项目路径**: 以 SHA256 哈希形式上报,不包含源码/绝对路径
|
|
411
|
+
- **健康探测**: 上报前 HEAD 请求(500ms 超时),失败自动跳过
|
|
412
|
+
- **删除即失效**: 模块移除不影响 CLI 正常工作
|
|
413
|
+
|
|
414
|
+
</details>
|
|
415
|
+
|
|
416
|
+
## 📝 兼容说明
|
|
417
|
+
|
|
418
|
+
以下能力继续保留:
|
|
419
|
+
|
|
420
|
+
- ✅ `install.sh` / `install.ps1` 脚本入口
|
|
421
|
+
- ✅ `--level L1/L2/L3` 渐进式接入参数
|
|
422
|
+
- ✅ `--custom-rules` 自定义规则
|
|
423
|
+
- ✅ 细粒度 `update` 选择性更新
|
|
424
|
+
- ✅ Monorepo 目标选择
|
|
425
|
+
- ✅ `configs/` 增量补齐
|
|
426
|
+
|
|
427
|
+
**重点收口**:
|
|
428
|
+
- 安装实现统一到 Node 核心
|
|
429
|
+
- Bash/PowerShell 只保留薄壳入口
|
|
430
|
+
- README 收成产品入口页
|
|
431
|
+
- Registry 说明集中统一
|
|
432
|
+
|
|
433
|
+
协议主链、专家链和运行时状态机没有因为入口收口而改变。
|