dev-playbooks-cn 1.0.9 → 1.0.11

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/README.md CHANGED
@@ -7,6 +7,8 @@
7
7
  [![npm](https://img.shields.io/npm/v/dev-playbooks-cn)](https://www.npmjs.com/package/dev-playbooks-cn)
8
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
9
9
 
10
+ ![DevBooks 工作流](docs/workflow-diagram.svg)
11
+
10
12
  ---
11
13
 
12
14
  ## 为什么选择 DevBooks?
@@ -46,29 +48,6 @@ AI 编码助手很强大,但往往**不可预测**:
46
48
 
47
49
  ## 工作原理
48
50
 
49
- ```
50
- DevBooks 工作流
51
-
52
- PROPOSAL 阶段 APPLY 阶段 ARCHIVE 阶段
53
- (禁止编码) (角色隔离强制) (质量闸门)
54
-
55
- ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
56
- │ /devbooks: │ │ 对话 A │ │ /devbooks: │
57
- │ proposal │ │ ┌───────────┐ │ │ gardener │
58
- │ impact │────────────│ │Test Owner │ │────────────│ delivery │
59
- │ design │ │ │(先跑 Red) │ │ │ │
60
- │ spec │ │ └───────────┘ │ │ 质量闸门: │
61
- │ plan │ │ │ │ ✓ Green 证据 │
62
- └─────────────────┘ │ 对话 B │ │ ✓ 任务完成 │
63
- │ │ ┌───────────┐ │ │ ✓ 角色边界 │
64
- ▼ │ │ Coder │ │ │ ✓ 无失败 │
65
- ┌─────────────────┐ │ │(禁改测试!)│ │ └─────────────────┘
66
- │ 三角对辩 │ │ └───────────┘ │
67
- │ Author/Challenger│ └─────────────────┘
68
- │ /Judge │
69
- └─────────────────┘
70
- ```
71
-
72
51
  **核心约束**:Test Owner 与 Coder **必须在独立对话**中工作。这是硬性约束,不是建议。Coder 不能修改 `tests/**`,完成由测试/构建验证,而非 AI 自评。
73
52
 
74
53
  ---
@@ -77,19 +56,18 @@ AI 编码助手很强大,但往往**不可预测**:
77
56
 
78
57
  ### 支持的 AI 工具
79
58
 
80
- | 工具 | Slash 命令 | 自然语言 | 配置文件 |
81
- |------|-----------|----------|----------|
82
- | **Claude Code** | `/devbooks:*` | 支持 | `CLAUDE.md` |
83
- | **Codex CLI** | `/devbooks:*` | 支持 | `AGENTS.md` |
84
- | **Cursor** | - | 支持 | `.cursorrules` |
85
- | **Windsurf** | - | 支持 | `.windsurfrules` |
86
- | **Continue.dev** | - | 支持 | `.continuerules` |
87
- | **GitHub Copilot** | - | 支持 | `.github/copilot-instructions.md` |
88
- | **Gemini Code Assist** | - | 支持 | - |
89
- | **Aider** | - | 支持 | `.aider.conf.yml` |
90
- | **Cline** | - | 支持 | `.clinerules` |
59
+ | 工具 | 支持级别 | 配置文件 |
60
+ |------|----------|----------|
61
+ | **Claude Code** | 完整 Skills | `CLAUDE.md` |
62
+ | **Codex CLI** | 完整 Skills | `AGENTS.md` |
63
+ | **Qoder** | 完整 Skills | `AGENTS.md` |
64
+ | **Cursor** | Rules 系统 | `.cursor/rules/` |
65
+ | **Windsurf** | Rules 系统 | `.windsurf/rules/` |
66
+ | **Gemini CLI** | Rules 系统 | `GEMINI.md` |
67
+ | **Continue** | Rules 系统 | `.continue/rules/` |
68
+ | **GitHub Copilot** | 自定义指令 | `.github/copilot-instructions.md` |
91
69
 
92
- > **提示**:对于不支持 Slash 命令的工具,使用自然语言指令,例如:"运行 DevBooks proposal skill..."
70
+ > **提示**:使用自然语言调用 Skills,例如:"运行 devbooks-proposal-author skill..."
93
71
 
94
72
  ### 安装与初始化
95
73
 
@@ -119,7 +97,7 @@ npx dev-playbooks-cn@latest init
119
97
 
120
98
  初始化后:
121
99
  - Claude Code:`~/.claude/skills/devbooks-*`
122
- - Codex CLI:`$CODEX_HOME/skills/devbooks-*`(默认 `~/.codex/skills/devbooks-*`)
100
+ - Codex CLI:`~/.codex/skills/devbooks-*`
123
101
 
124
102
  ### 快速集成
125
103
 
@@ -130,7 +108,7 @@ DevBooks 使用两个目录根:
130
108
  | `<truth-root>` | 当前规格(只读真理) | `dev-playbooks/specs/` |
131
109
  | `<change-root>` | 变更包(工作区) | `dev-playbooks/changes/` |
132
110
 
133
- 详见 `docs/DevBooks集成模板(协议无关).md` 或使用 `docs/DevBooks安装提示词.md` 让 AI 自动配置。
111
+ 详见 `docs/DevBooks配置指南.md`。
134
112
 
135
113
  ---
136
114
 
@@ -138,20 +116,20 @@ DevBooks 使用两个目录根:
138
116
 
139
117
  ### 使用 Router(推荐)
140
118
 
119
+ 告诉 AI 你的需求,让 Router 分析并输出执行计划:
120
+
141
121
  ```
142
- /devbooks:router <你的需求>
122
+ 请运行 devbooks-router skill,分析需求:<你的需求>
143
123
  ```
144
124
 
145
- Router 分析需求并输出执行计划,告诉你下一步用哪个命令。
146
-
147
- ### 直达命令
125
+ ### Skills 直达
148
126
 
149
127
  熟悉流程后,直接调用 Skill:
150
128
 
151
129
  **1. Proposal 阶段(禁止编码)**
152
130
 
153
131
  ```
154
- /devbooks:proposal 添加 OAuth2 用户认证
132
+ 请运行 devbooks-proposal-author skill,创建提案:添加 OAuth2 用户认证
155
133
  ```
156
134
 
157
135
  产物:`proposal.md`(必需)、`design.md`、`tasks.md`
@@ -162,10 +140,10 @@ Router 分析需求并输出执行计划,告诉你下一步用哪个命令。
162
140
 
163
141
  ```
164
142
  # 对话 A - Test Owner
165
- /devbooks:test add-oauth2
143
+ 请运行 devbooks-test-owner skill,变更 ID:add-oauth2
166
144
 
167
145
  # 对话 B - Coder
168
- /devbooks:code add-oauth2
146
+ 请运行 devbooks-coder skill,变更 ID:add-oauth2
169
147
  ```
170
148
 
171
149
  - Test Owner:写 `verification.md` + 测试,先跑 **Red**
@@ -174,64 +152,64 @@ Router 分析需求并输出执行计划,告诉你下一步用哪个命令。
174
152
  **3. Review 阶段**
175
153
 
176
154
  ```
177
- /devbooks:review add-oauth2
155
+ 请运行 devbooks-code-review skill,变更 ID:add-oauth2
178
156
  ```
179
157
 
180
158
  **4. Archive 阶段**
181
159
 
182
160
  ```
183
- /devbooks:gardener add-oauth2
161
+ 请运行 devbooks-spec-gardener skill,变更 ID:add-oauth2
184
162
  ```
185
163
 
186
164
  ---
187
165
 
188
- ## 命令参考
166
+ ## Skills 参考
189
167
 
190
168
  ### Proposal 阶段
191
169
 
192
- | 命令 | Skill | 说明 |
193
- |------|-------|------|
194
- | `/devbooks:router` | devbooks-router | 智能路由到合适的 Skill |
195
- | `/devbooks:proposal` | devbooks-proposal-author | 创建变更提案 |
196
- | `/devbooks:impact` | devbooks-impact-analysis | 跨模块影响分析 |
197
- | `/devbooks:challenger` | devbooks-proposal-challenger | 质疑和挑战提案 |
198
- | `/devbooks:judge` | devbooks-proposal-judge | 裁决提案 |
199
- | `/devbooks:debate` | devbooks-proposal-debate-workflow | 三角对辩(Author/Challenger/Judge) |
200
- | `/devbooks:design` | devbooks-design-doc | 创建设计文档 |
201
- | `/devbooks:spec` | devbooks-spec-contract | 定义规格与契约 |
202
- | `/devbooks:c4` | devbooks-c4-map | 生成 C4 架构地图 |
203
- | `/devbooks:plan` | devbooks-implementation-plan | 创建实现计划 |
170
+ | Skill | 说明 |
171
+ |-------|------|
172
+ | `devbooks-router` | 智能路由到合适的 Skill |
173
+ | `devbooks-proposal-author` | 创建变更提案 |
174
+ | `devbooks-impact-analysis` | 跨模块影响分析 |
175
+ | `devbooks-proposal-challenger` | 质疑和挑战提案 |
176
+ | `devbooks-proposal-judge` | 裁决提案 |
177
+ | `devbooks-proposal-debate-workflow` | 三角对辩(Author/Challenger/Judge) |
178
+ | `devbooks-design-doc` | 创建设计文档 |
179
+ | `devbooks-spec-contract` | 定义规格与契约 |
180
+ | `devbooks-c4-map` | 生成 C4 架构地图 |
181
+ | `devbooks-implementation-plan` | 创建实现计划 |
204
182
 
205
183
  ### Apply 阶段
206
184
 
207
- | 命令 | Skill | 说明 |
208
- |------|-------|------|
209
- | `/devbooks:test` | devbooks-test-owner | Test Owner 角色(必须独立对话) |
210
- | `/devbooks:code` | devbooks-coder | Coder 角色(必须独立对话) |
211
- | `/devbooks:backport` | devbooks-design-backport | 回写发现到设计文档 |
185
+ | Skill | 说明 |
186
+ |-------|------|
187
+ | `devbooks-test-owner` | Test Owner 角色(必须独立对话) |
188
+ | `devbooks-coder` | Coder 角色(必须独立对话) |
189
+ | `devbooks-design-backport` | 回写发现到设计文档 |
212
190
 
213
191
  ### Review 阶段
214
192
 
215
- | 命令 | Skill | 说明 |
216
- |------|-------|------|
217
- | `/devbooks:review` | devbooks-code-review | 代码评审(可读性/一致性) |
218
- | `/devbooks:test-review` | devbooks-test-reviewer | 测试质量与覆盖率评审 |
193
+ | Skill | 说明 |
194
+ |-------|------|
195
+ | `devbooks-code-review` | 代码评审(可读性/一致性) |
196
+ | `devbooks-test-reviewer` | 测试质量与覆盖率评审 |
219
197
 
220
198
  ### Archive 阶段
221
199
 
222
- | 命令 | Skill | 说明 |
223
- |------|-------|------|
224
- | `/devbooks:gardener` | devbooks-spec-gardener | 规格维护与去重 |
225
- | `/devbooks:delivery` | devbooks-delivery-workflow | 完整交付闭环 |
200
+ | Skill | 说明 |
201
+ |-------|------|
202
+ | `devbooks-spec-gardener` | 规格维护与去重 |
203
+ | `devbooks-delivery-workflow` | 完整交付闭环 |
226
204
 
227
205
  ### 独立技能
228
206
 
229
- | 命令 | Skill | 说明 |
230
- |------|-------|------|
231
- | `/devbooks:entropy` | devbooks-entropy-monitor | 系统熵度量 |
232
- | `/devbooks:federation` | devbooks-federation | 跨仓库联邦分析 |
233
- | `/devbooks:bootstrap` | devbooks-brownfield-bootstrap | 存量项目初始化 |
234
- | `/devbooks:index` | devbooks-index-bootstrap | 生成 SCIP 索引 |
207
+ | Skill | 说明 |
208
+ |-------|------|
209
+ | `devbooks-entropy-monitor` | 系统熵度量 |
210
+ | `devbooks-federation` | 跨仓库联邦分析 |
211
+ | `devbooks-brownfield-bootstrap` | 存量项目初始化 |
212
+ | `devbooks-index-bootstrap` | 生成 SCIP 索引 |
235
213
 
236
214
  ---
237
215
 
@@ -317,7 +295,7 @@ DevBooks 提供质量闸门拦截"伪完成":
317
295
  | P0 跳过审批 | strict | P0 任务跳过必须有审批记录 |
318
296
  | 角色边界检查 | apply --role | Coder 不能改 tests/,Test Owner 不能改 src/ |
319
297
 
320
- 核心脚本(位于 `skills/devbooks-delivery-workflow/scripts/`):
298
+ 核心脚本(位于 `~/.claude/skills/devbooks-delivery-workflow/scripts/`):
321
299
  - `change-check.sh --mode proposal|apply|archive|strict`
322
300
  - `handoff-check.sh` - 角色交接验证
323
301
  - `audit-scope.sh` - 全量审计扫描
@@ -337,7 +315,7 @@ DevBooks 提供质量闸门拦截"伪完成":
337
315
 
338
316
  原型模式防止实验代码污染主源码树。
339
317
 
340
- 脚本位于 `skills/devbooks-delivery-workflow/scripts/`。
318
+ 脚本位于 `~/.claude/skills/devbooks-delivery-workflow/scripts/`。
341
319
 
342
320
  </details>
343
321
 
@@ -353,22 +331,17 @@ DevBooks 跟踪四维系统熵:
353
331
  | 测试熵 | 测试覆盖率和质量衰减 |
354
332
  | 依赖熵 | 外部依赖健康度 |
355
333
 
356
- `/devbooks:entropy` 生成报告,识别重构机会。
334
+ `devbooks-entropy-monitor` 生成报告,识别重构机会。
357
335
 
358
- 脚本(位于 `skills/devbooks-entropy-monitor/scripts/`):`entropy-measure.sh`、`entropy-report.sh`
336
+ 脚本(位于 `~/.claude/skills/devbooks-entropy-monitor/scripts/`):`entropy-measure.sh`、`entropy-report.sh`
359
337
 
360
338
  </details>
361
339
 
362
340
  <details>
363
341
  <summary><strong>存量项目初始化</strong></summary>
364
342
 
365
- 当 `<truth-root>` 为空时:
343
+ 当 `<truth-root>` 为空时,使用 `devbooks-brownfield-bootstrap` 生成:
366
344
 
367
- ```
368
- /devbooks:bootstrap
369
- ```
370
-
371
- 生成:
372
345
  - 项目画像和术语表
373
346
  - 从现有代码生成基线规格
374
347
  - 最小验证锚点
@@ -380,24 +353,18 @@ DevBooks 跟踪四维系统熵:
380
353
  <details>
381
354
  <summary><strong>跨仓库联邦</strong></summary>
382
355
 
383
- 多仓库分析:
384
-
385
- ```
386
- /devbooks:federation
387
- ```
388
-
389
- 分析跨仓库边界的契约和依赖,支持协调变更。
356
+ 多仓库分析用 `devbooks-federation`,分析跨仓库边界的契约和依赖,支持协调变更。
390
357
 
391
358
  </details>
392
359
 
393
360
  <details>
394
361
  <summary><strong>MCP 自动检测</strong></summary>
395
362
 
396
- DevBooks Skills 支持 MCP(Model Context Protocol)优雅降级:在没有 MCP/CKB 的环境也能跑完整工作流;一旦检测到 CKB(Code Knowledge Base)可用,就自动启用图基能力,把“范围/引用/调用链”分析做得更准。
363
+ DevBooks Skills 支持 MCP(Model Context Protocol)优雅降级:在没有 MCP/CKB 的环境也能跑完整工作流;一旦检测到 CKB(Code Knowledge Base)可用,就自动启用图基能力,把"范围/引用/调用链"分析做得更准。
397
364
 
398
365
  ### 它有什么用?
399
366
 
400
- - **影响分析更精确**:从“文件级猜测”升级到“符号级引用 + 调用图”,降低漏改风险
367
+ - **影响分析更精确**:从"文件级猜测"升级到"符号级引用 + 调用图",降低漏改风险
401
368
  - **审查更有重点**:自动拉取热点文件,优先关注高风险区域(技术债/高变动)
402
369
  - **大仓库更省心**:减少手动 Grep 的噪音与反复确认
403
370
 
@@ -405,27 +372,23 @@ DevBooks Skills 支持 MCP(Model Context Protocol)优雅降级:在没有 M
405
372
 
406
373
  | MCP 状态 | 行为 |
407
374
  |----------|------|
408
- | CKB 可用 | 增强模式:符号级影响分析/引用查找/调用图/热点(`mcp__ckb__analyzeImpact`、`mcp__ckb__findReferences`、`mcp__ckb__getCallGraph`、`mcp__ckb__getHotspots`) |
375
+ | CKB 可用 | 增强模式:符号级影响分析/引用查找/调用图/热点 |
409
376
  | CKB 不可用 | 基础模式:Grep + Glob 文本搜索(功能完整,精度降低) |
410
377
 
411
378
  ### 自动检测
412
379
 
413
- - 需要 MCP 的 Skills 会先调用 `mcp__ckb__getStatus` 探测可用性(2s 超时)
380
+ - 需要 MCP 的 Skills 会先探测可用性(2s 超时)
414
381
  - 超时/失败 → 静默降级到基础模式,不阻塞执行
415
- - 无需手动选择“基础/增强”模式
382
+ - 无需手动选择"基础/增强"模式
416
383
 
417
- 如需启用增强能力:按 `docs/推荐MCP.md` 配置 CKB,并运行 `/devbooks:index` 生成 `index.scip`。
384
+ 如需启用增强能力:按 `docs/推荐MCP.md` 配置 CKB,并运行 `devbooks-index-bootstrap` 生成 `index.scip`。
418
385
 
419
386
  </details>
420
387
 
421
388
  <details>
422
389
  <summary><strong>提案对辩工作流</strong></summary>
423
390
 
424
- 严格提案审查用三角对辩:
425
-
426
- ```
427
- /devbooks:debate
428
- ```
391
+ 严格提案审查用三角对辩 `devbooks-proposal-debate-workflow`:
429
392
 
430
393
  三个角色:
431
394
  1. **Author**:创建并捍卫提案
@@ -438,26 +401,103 @@ DevBooks Skills 支持 MCP(Model Context Protocol)优雅降级:在没有 M
438
401
 
439
402
  ---
440
403
 
441
- ## 仓库结构
404
+ ## 从其他框架迁移
405
+
406
+ DevBooks 提供迁移脚本帮助从其他规格驱动开发工具迁移。
407
+
408
+ ### 从 OpenSpec 迁移
409
+
410
+ 如果你当前使用 [OpenSpec](https://github.com/Fission-AI/OpenSpec),有 `openspec/` 目录:
411
+
412
+ ```bash
413
+ # 使用 CLI(推荐)
414
+ dev-playbooks-cn migrate --from openspec
415
+
416
+ # 先预览变更
417
+ dev-playbooks-cn migrate --from openspec --dry-run
418
+
419
+ # 迁移后保留原目录
420
+ dev-playbooks-cn migrate --from openspec --keep-old
421
+ ```
422
+
423
+ **迁移内容:**
424
+ - `openspec/specs/` → `dev-playbooks/specs/`
425
+ - `openspec/changes/` → `dev-playbooks/changes/`
426
+ - `openspec/project.md` → `dev-playbooks/project.md`
427
+ - 所有路径引用自动更新
428
+
429
+ ### 从 GitHub spec-kit 迁移
430
+
431
+ 如果你使用 [GitHub spec-kit](https://github.com/github/spec-kit),有 `specs/` 和 `memory/` 目录:
432
+
433
+ ```bash
434
+ # 使用 CLI(推荐)
435
+ dev-playbooks-cn migrate --from speckit
436
+
437
+ # 先预览变更
438
+ dev-playbooks-cn migrate --from speckit --dry-run
439
+
440
+ # 迁移后保留原目录
441
+ dev-playbooks-cn migrate --from speckit --keep-old
442
+ ```
443
+
444
+ **映射规则:**
445
+
446
+ | Spec-Kit | DevBooks |
447
+ |----------|----------|
448
+ | `memory/constitution.md` | `dev-playbooks/specs/_meta/constitution.md` |
449
+ | `specs/[feature]/spec.md` | `changes/[feature]/design.md` |
450
+ | `specs/[feature]/plan.md` | `changes/[feature]/proposal.md` |
451
+ | `specs/[feature]/tasks.md` | `changes/[feature]/tasks.md` |
452
+ | `specs/[feature]/quickstart.md` | `changes/[feature]/verification.md` |
453
+ | `specs/[feature]/contracts/` | `changes/[feature]/specs/` |
454
+
455
+ ### 迁移功能
456
+
457
+ 两个迁移脚本都支持:
458
+
459
+ - **幂等执行**:可安全多次运行
460
+ - **断点续传**:中断后可从断点恢复
461
+ - **试运行模式**:预览变更再执行
462
+ - **自动备份**:原文件备份到 `.devbooks/backup/`
463
+ - **引用更新**:文档中的路径引用自动更新
464
+
465
+ ### 迁移后步骤
466
+
467
+ 迁移后:
468
+
469
+ 1. 运行 `dev-playbooks-cn init` 设置 DevBooks Skills
470
+ 2. 检查 `dev-playbooks/` 中的迁移文件
471
+ 3. 更新 `verification.md` 文件的 AC 映射
472
+ 4. 如需基线规格,运行 `devbooks-brownfield-bootstrap`
473
+
474
+ ---
475
+
476
+ ## 目录结构
442
477
 
443
478
  ```
444
- skills/ # devbooks-* Skills 源码(部分 Skill 自带 scripts/)
445
- templates/ # 项目初始化模板(`dev-playbooks-cn init` 使用)
446
- templates/dev-playbooks/ # DevBooks 协议目录模板(初始化后写入项目为 `dev-playbooks/`)
447
- scripts/ # 安装与辅助脚本
448
- docs/ # 支持文档
449
- bin/ # CLI 入口
479
+ dev-playbooks/
480
+ ├── README.md # 本文档
481
+ ├── constitution.md # 项目宪法(GIP 原则)
482
+ ├── project.md # 项目上下文(技术栈/约定)
483
+ ├── specs/ # 当前规格(只读真理)
484
+ │ ├── _meta/ # 元数据(术语表、项目画像)
485
+ │ └── architecture/ # 架构规格(fitness-rules)
486
+ ├── changes/ # 变更包(工作区)
487
+ ├── scripts/ # 辅助脚本
488
+ └── docs/ # 文档
489
+ ├── workflow-diagram.svg # 工作流程图
490
+ ├── 推荐MCP.md # MCP 配置建议
491
+ └── DevBooks配置指南.md # 配置指南
450
492
  ```
451
493
 
452
494
  ---
453
495
 
454
496
  ## 文档
455
497
 
456
- - [Slash 命令使用指南](docs/Slash 命令使用指南.md)
457
- - [Skills 使用说明](skills/Skills使用说明.md)
498
+ - [工作流程图](docs/workflow-diagram.svg)
458
499
  - [MCP 配置建议](docs/推荐MCP.md)
459
- - [集成模板(协议无关)](docs/DevBooks集成模板(协议无关).md)
460
- - [安装提示词](docs/DevBooks安装提示词.md)
500
+ - [配置指南](docs/DevBooks配置指南.md)
461
501
 
462
502
  ---
463
503
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dev-playbooks-cn",
3
- "version": "1.0.9",
3
+ "version": "1.0.11",
4
4
  "description": "AI-driven spec-based development workflow",
5
5
  "keywords": [
6
6
  "devbooks",
@@ -7,6 +7,8 @@
7
7
  [![npm](https://img.shields.io/npm/v/dev-playbooks-cn)](https://www.npmjs.com/package/dev-playbooks-cn)
8
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../LICENSE)
9
9
 
10
+ ![DevBooks 工作流](docs/workflow-diagram.svg)
11
+
10
12
  ---
11
13
 
12
14
  ## 为什么选择 DevBooks?
@@ -46,8 +48,6 @@ AI 编码助手很强大,但往往**不可预测**:
46
48
 
47
49
  ## 工作原理
48
50
 
49
- ![DevBooks 工作流](docs/workflow-diagram.svg)
50
-
51
51
  **核心约束**:Test Owner 与 Coder **必须在独立对话**中工作。这是硬性约束,不是建议。Coder 不能修改 `tests/**`,完成由测试/构建验证,而非 AI 自评。
52
52
 
53
53
  ---