dev-playbooks-cn 1.0.4 → 1.0.6

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.
Files changed (4) hide show
  1. package/package.json +1 -1
  2. package/skills/devbooks-brownfield-bootstrap/SKILL.md +70 -6
  3. package/skills/devbooks-brownfield-bootstrap/references//345/255/230/351/207/217/351/241/271/347/233/256/345/210/235/345/247/213/345/214/226/346/217/220/347/244/272/350/257/215.md +89 -20
  4. package/templates/dev-playbooks/README.md +270 -270
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dev-playbooks-cn",
3
- "version": "1.0.4",
3
+ "version": "1.0.6",
4
4
  "description": "AI-driven spec-based development workflow",
5
5
  "keywords": [
6
6
  "devbooks",
package/skills/devbooks-brownfield-bootstrap/SKILL.md CHANGED
@@ -21,18 +21,75 @@ tools:
21
21
 
22
22
  - `<truth-root>`：当前真理目录根
23
23
  - `<change-root>`：变更包目录根
24
+ - `<devbooks-root>`：DevBooks 管理目录（通常是 `dev-playbooks/`）
24
25
 
25
26
  执行前**必须**按以下顺序查找配置（找到后停止）：
26
27
  1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
27
28
  2. `dev-playbooks/project.md`（如存在）→ DevBooks 2.0 协议，使用默认映射
28
29
  4. `project.md`（如存在）→ template 协议，使用默认映射
29
- 5. 若仍无法确定 → **停止并询问用户**
30
+ 5. 若仍无法确定 → **创建 DevBooks 目录结构并初始化基础配置**
30
31
 
31
32
  **关键约束**：
32
33
  - 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
33
34
  - 禁止猜测目录根
34
35
  - 禁止跳过规则文档阅读
35
36
 
37
+ ---
38
+
39
+ ## 核心职责
40
+
41
+ 存量项目初始化包含以下职责：
42
+
43
+ ### 1. 基础配置文件初始化（新增）
44
+
45
+ 在 `<devbooks-root>/`（通常是 `dev-playbooks/`）下检查并创建：
46
+
47
+ | 文件 | 用途 | 创建条件 |
48
+ |------|------|----------|
49
+ | `constitution.md` | 项目宪法（GIP 原则） | 文件不存在时 |
50
+ | `project.md` | 项目上下文（技术栈/约定） | 文件不存在时 |
51
+
52
+ **创建方式**：
53
+ - **不是简单复制模板**，而是根据代码分析结果定制内容
54
+ - `constitution.md`：基于默认 GIP 原则，可根据项目特性调整
55
+ - `project.md`：根据代码分析结果填充：
56
+ - 技术栈（语言/框架/数据库）
57
+ - 开发约定（代码风格/测试策略/Git 工作流）
58
+ - 领域上下文（核心概念/角色定义）
59
+ - 目录根映射
60
+
61
+ ### 2. 项目画像与元数据
62
+
63
+ 在 `<truth-root>/_meta/` 下生成：
64
+
65
+ | 产物 | 路径 | 说明 |
66
+ |------|------|------|
67
+ | 项目画像 | `_meta/project-profile.md` | 三层架构的详细技术画像 |
68
+ | 术语表 | `_meta/glossary.md` | 统一语言表（可选但推荐） |
69
+ | 领域概念 | `_meta/key-concepts.md` | CKB 提取的概念（增强模式） |
70
+
71
+ ### 3. 架构分析产物
72
+
73
+ 在 `<truth-root>/architecture/` 下生成：
74
+
75
+ | 产物 | 路径 | 数据来源 |
76
+ |------|------|----------|
77
+ | 模块依赖图 | `architecture/module-graph.md` | `mcp__ckb__getArchitecture` |
78
+ | 技术债热点 | `architecture/hotspots.md` | `mcp__ckb__getHotspots` |
79
+
80
+ ### 4. 基线变更包
81
+
82
+ 在 `<change-root>/<baseline-id>/` 下生成：
83
+
84
+ | 产物 | 说明 |
85
+ |------|------|
86
+ | `proposal.md` | 基线范围、In/Out、风险 |
87
+ | `design.md` | 现状盘点（capability inventory） |
88
+ | `specs/<cap>/spec.md` | 基线 spec deltas（ADDED 为主） |
89
+ | `verification.md` | 最小验证锚点计划 |
90
+
91
+ ---
92
+
36
93
  ## COD 模型生成（Code Overview & Dependencies）
37
94
 
38
95
  在初始化时自动生成项目的"代码地图"（需要 CKB MCP Server 可用，否则跳过）：
@@ -101,15 +158,19 @@ tools:
101
158
 
102
159
  ### 检测流程
103
160
 
104
- 1. 检测 `<truth-root>/` 是否为空或基本为空
105
- 2. 检测 CKB 索引是否可用
106
- 3. 检测项目规模和语言栈
161
+ 1. 检测 `<devbooks-root>/constitution.md` 是否存在
162
+ 2. 检测 `<devbooks-root>/project.md` 是否存在
163
+ 3. 检测 `<truth-root>/` 是否为空或基本为空
164
+ 4. 检测 CKB 索引是否可用
165
+ 5. 检测项目规模和语言栈
107
166
 
108
167
  ### 本 Skill 支持的模式
109
168
 
110
169
  | 模式 | 触发条件 | 行为 |
111
170
  |------|----------|------|
112
- | **完整初始化** | truth-root 为空 | 生成所有基础产物 |
171
+ | **全新初始化** | devbooks-root 不存在或为空 | 创建完整目录结构 + constitution + project + 画像 |
172
+ | **补充配置** | constitution/project 缺失 | 只补充缺失的配置文件 |
173
+ | **完整初始化** | truth-root 为空 | 生成所有基础产物（画像/基线/验证） |
113
174
  | **增量初始化** | truth-root 部分存在 | 只补充缺失产物 |
114
175
  | **增强模式** | CKB 索引可用 | 使用图分析生成更精确的画像 |
115
176
  | **基础模式** | CKB 索引不可用 | 使用传统分析方法 |
@@ -118,10 +179,13 @@ tools:
118
179
 
119
180
  ```
120
181
  检测结果：
182
+ - devbooks-root：存在
183
+ - constitution.md：不存在 → 将创建
184
+ - project.md：不存在 → 将创建
121
185
  - truth-root：为空
122
186
  - CKB 索引：可用
123
187
  - 项目规模：中型（~50K LOC）
124
- - 运行模式：完整初始化 + 增强模式
188
+ - 运行模式：补充配置 + 完整初始化 + 增强模式
125
189
  ```
126
190
 
127
191
  ---
package/skills/devbooks-brownfield-bootstrap/references//345/255/230/351/207/217/351/241/271/347/233/256/345/210/235/345/247/213/345/214/226/346/217/220/347/244/272/350/257/215.md CHANGED
@@ -6,18 +6,20 @@
6
6
  - 在执行本提示词前，先阅读 `_shared/references/通用守门协议.md` 并遵循其中所有协议。
7
7
 
8
8
  目录根（强制）：
9
- - 在写任何文件前，必须先确定 `<truth-root>` 与 `<change-root>` 的实际路径；禁止猜测。
10
- - 若存在 `dev-playbooks/project.md`（或目录 `dev-playbooks/`）：视为 DevBooks 项目，默认：
9
+ - 在写任何文件前，必须先确定 `<devbooks-root>`、`<truth-root>` 与 `<change-root>` 的实际路径；禁止猜测。
10
+ - 若存在 `dev-playbooks/` 目录：视为 DevBooks 项目，默认：
11
+ - `<devbooks-root>` = `dev-playbooks/`
11
12
  - `<truth-root>` = `dev-playbooks/specs`
12
13
  - `<change-root>` = `dev-playbooks/changes`
13
- - 必须先阅读 `dev-playbooks/project.md`（如存在）并遵循其中说明。
14
- - 否则：必须先询问用户确认 `<truth-root>` 与 `<change-root>`；用户未确认不得落盘。
14
+ - 如存在 `dev-playbooks/project.md`：必须先阅读并遵循其中说明。
15
+ - 否则：必须先询问用户确认目录根；用户未确认不得落盘。
15
16
 
16
- 你是“存量项目初始化负责人（Brownfield Bootstrapper）”。你的任务是在**存量项目**中，当 `<truth-root>/` 为空或缺失时，一次性补齐：
17
- 1) 项目画像与约定（技术栈/命令/边界/闸门/契约入口）
18
- 2) 现状规格基线（baseline specs，以 ADDED 为主）
17
+ 你是"存量项目初始化负责人（Brownfield Bootstrapper）"。你的任务是在**存量项目**中，当 `<truth-root>/` 为空或缺失时，一次性补齐：
18
+ 1) **基础配置文件**（constitution.md、project.md）
19
+ 2) 项目画像与约定（技术栈/命令/边界/闸门/契约入口）
20
+ 3) 现状规格基线（baseline specs，以 ADDED 为主）
19
21
 
20
- 最终效果：后续任何变更都能像“项目从一开始就按规格化流程开发”一样，有稳定真理源、稳定落点与可验证锚点。
22
+ 最终效果：后续任何变更都能像"项目从一开始就按规格化流程开发"一样，有稳定真理源、稳定落点与可验证锚点。
21
23
 
22
24
  输入材料（由我提供）：
23
25
  - 代码库（只读分析，允许运行只读命令）
@@ -26,6 +28,9 @@
26
28
  - 我指定的基线范围（对外契约优先/关键链路优先/模块边界优先）
27
29
 
28
30
  产物目标（目录约定，协议无关）：
31
+ - **基础配置文件**（如缺失则创建）：
32
+ - `<devbooks-root>/constitution.md`：项目宪法（GIP 原则）
33
+ - `<devbooks-root>/project.md`：项目上下文（技术栈/约定/领域）
29
34
  - 项目画像（当前真理的一部分）：
30
35
  - `<truth-root>/_meta/project-profile.md`
31
36
  - 统一语言表（可选但推荐）：
@@ -33,21 +38,83 @@
33
38
  - 变更包：`<change-root>/<baseline-id>/`
34
39
  - `proposal.md`：基线范围、为什么先做基线、In/Out、风险与未知
35
40
  - `design.md`（可选但推荐）：现状盘点（capability inventory）与边界/依赖方向
36
- - `<truth-root>/<capability>/spec.md`：基线 spec deltas（只用 ADDED Requirements）
41
+ - `specs/<capability>/spec.md`：基线 spec deltas（只用 ADDED Requirements）
37
42
  - `verification.md`：最小验证锚点计划 + 追溯矩阵 + MANUAL-*
38
- - 当前真理源：`<truth-root>/`（本阶段先不直接写入；由后续“归档/合并”动作把基线变更合并进去）
43
+ - 当前真理源：`<truth-root>/`（本阶段先不直接写入；由后续"归档/合并"动作把基线变更合并进去）
39
44
 
40
45
  硬约束（必须遵守）：
41
46
  1) **只写现状，不做重构**：本次初始化不引入行为变化建议，不输出实现计划。
42
47
  2) **基线 delta 以 ADDED 为主**：当 `<truth-root>/` 为空时，优先只写 ADDED，避免 MODIFIED/RENAMED/REMOVED（这些通常要求已有当前真理）。
43
48
  3) **delta 格式必须匹配项目所用协议的校验器**：
44
- - 先在仓库里查找“delta 标题/场景标题”的既有模板或约定（例如搜索 `ADDED Requirements`/`新增需求`/`Scenario:`/`场景：`）
49
+ - 先在仓库里查找"delta 标题/场景标题"的既有模板或约定（例如搜索 `ADDED Requirements`/`新增需求`/`Scenario:`/`场景：`）
45
50
  - 若仍不确定：不要臆测；在 `<truth-root>/_meta/project-profile.md` 标注 `TBD` 并给出验证动作（例如运行协议的 validate 命令）
46
51
  4) **证据优先**：任何不确定的地方必须标注 `TBD`，并在 `verification.md` 写清验证动作；禁止臆测补齐。
47
52
  5) **MECE 聚类**：capability 控制在 3–8 个；每个 capability 的 Requirements 控制在 3–15 条（先薄后厚）。
48
53
  6) **每条 Requirement 至少 1 个 Scenario**，并尽量在 Scenario 末尾补一行 Evidence（指向代码入口/测试/命令/日志关键字）。
49
54
  7) **遗留安全网优先**：若后续计划涉及重构/迁移，`verification.md` 中优先加入 Snapshot/Golden Master 测试策略。
50
55
 
56
+ ---
57
+
58
+ ## `constitution.md` 创建要求
59
+
60
+ 当 `<devbooks-root>/constitution.md` 不存在时，必须创建。
61
+
62
+ **内容要求**：
63
+ 1) 包含 Part Zero（强制指令）
64
+ 2) 包含 GIP-01 到 GIP-04（角色隔离/测试不可篡改/设计优先/真理源唯一）
65
+ 3) 包含逃生舱口（紧急修复/原型验证/人工裁决）
66
+ 4) 可根据项目特性新增项目特有的 GIP（如 GIP-05），但不得删除核心 GIP
67
+
68
+ **推荐结构**：
69
+ ```markdown
70
+ # 项目宪法 (Project Constitution)
71
+
72
+ ## Part Zero: 强制指令
73
+ ## 全局不可违背原则 (Global Inviolable Principles)
74
+ ### GIP-01: 角色隔离原则
75
+ ### GIP-02: 测试不可篡改原则
76
+ ### GIP-03: 设计优先原则
77
+ ### GIP-04: 真理源唯一原则
78
+ ### GIP-05: [项目特有原则，可选]
79
+ ## 逃生舱口 (Escape Hatches)
80
+ ## 宪法变更流程
81
+ ```
82
+
83
+ ---
84
+
85
+ ## `project.md` 创建要求
86
+
87
+ 当 `<devbooks-root>/project.md` 不存在时，必须创建。
88
+
89
+ **内容要求**（根据代码分析结果填充）：
90
+ 1) 目的：项目的核心目标
91
+ 2) 技术栈：从 package.json/go.mod/pom.xml/requirements.txt 等推断
92
+ 3) 项目约定：代码风格/架构模式/测试策略/Git 工作流
93
+ 4) 领域上下文：核心概念/角色定义
94
+ 5) 重要约束：角色隔离等
95
+ 6) 目录根映射：truth-root/change-root 的路径
96
+
97
+ **推荐结构**：
98
+ ```markdown
99
+ # 项目上下文 (Project Context)
100
+
101
+ ## 目的
102
+ ## 技术栈
103
+ ## 项目约定
104
+ ### 代码风格
105
+ ### 架构模式
106
+ ### 测试策略
107
+ ### Git 工作流
108
+ ## 领域上下文
109
+ ### 核心概念
110
+ ### 角色定义
111
+ ## 重要约束
112
+ ## 外部依赖
113
+ ## 目录根映射
114
+ ```
115
+
116
+ ---
117
+
51
118
  `<truth-root>/_meta/project-profile.md` 写作要求（必须遵守）：
52
119
  1) 只写你能从仓库证据推导出的结论；不确定必须标注 `TBD` 并给出验证动作（命令/文件路径/下一步）。
53
120
  2) 不改业务代码、不改 tests、不引入依赖；你只产出文档。
@@ -99,17 +166,19 @@
99
166
 
100
167
  输出要求（按顺序）：
101
168
  1) 先输出你将创建/更新的文件路径清单（只列路径）
102
- 2) 输出 `<truth-root>/_meta/project-profile.md` 内容（Markdown）
103
- 2.1) 若能从仓库识别稳定术语：输出 `<truth-root>/_meta/glossary.md` 草案
104
- 3) 输出 `proposal.md` 内容（Markdown）
105
- 4) 输出 `design.md` 内容（若你认为必要；否则输出“不需要”的理由）
106
- 5) 对每个 capability 输出 `<change-root>/<baseline-id>/specs/<capability>/spec.md` 的 delta 内容（优先只包含 ADDED Requirements）
107
- 6) 输出 `verification.md` 草案（至少包含：主线计划区、追溯矩阵、MANUAL-*）
108
- 7) 最后给出一个“合并建议”：如何把本基线变更合并进 `<truth-root>/`（如果你知道项目使用的协议命令，可以顺带给出命令；不知道就给出人工合并步骤）
169
+ 2) 若 `<devbooks-root>/constitution.md` 不存在：输出其内容（Markdown）
170
+ 3) 若 `<devbooks-root>/project.md` 不存在：输出其内容（Markdown），根据代码分析结果填充
171
+ 4) 输出 `<truth-root>/_meta/project-profile.md` 内容（Markdown）
172
+ 4.1) 若能从仓库识别稳定术语：输出 `<truth-root>/_meta/glossary.md` 草案
173
+ 5) 输出 `proposal.md` 内容（Markdown）
174
+ 6) 输出 `design.md` 内容（若你认为必要；否则输出"不需要"的理由）
175
+ 7) 对每个 capability 输出 `<change-root>/<baseline-id>/specs/<capability>/spec.md` 的 delta 内容（优先只包含 ADDED Requirements）
176
+ 8) 输出 `verification.md` 草案（至少包含：主线计划区、追溯矩阵、MANUAL-*）
177
+ 9) 最后给出一个"合并建议"：如何把本基线变更合并进 `<truth-root>/`（如果你知道项目使用的协议命令，可以顺带给出命令；不知道就给出人工合并步骤）
109
178
 
110
179
  现在开始执行，不要输出额外解释。
111
180
 
112
181
  注意事项：
113
- - 本文档中的 `<truth-root>` 与 `<change-root>` 是**占位符**，实际取值必须来自项目的上下文协议/指路牌。
114
- - DevBooks 项目默认取值：`dev-playbooks/specs` 与 `dev-playbooks/changes`。
182
+ - 本文档中的 `<devbooks-root>`、`<truth-root>` 与 `<change-root>` 是**占位符**，实际取值必须来自项目的上下文协议/指路牌。
183
+ - DevBooks 项目默认取值：`dev-playbooks/`、`dev-playbooks/specs` 与 `dev-playbooks/changes`。
115
184
  - 只有在用户明确确认时才允许使用默认 `specs/` 与 `changes/`。
package/templates/dev-playbooks/README.md CHANGED
@@ -1,183 +1,183 @@
1
1
  # DevBooks
2
2
 
3
- **An agentic AI development workflow for Claude Code / Codex CLI**
3
+ **面向 Claude Code / Codex CLI 的代理式 AI 开发工作流**
4
4
 
5
- > Turn large changes into a controlled, traceable, verifiable loop: Skills + quality gates + role isolation.
5
+ > 把大型变更变成可控、可追溯、可验证的闭环：Skills + 质量闸门 + 角色隔离。
6
6
 
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
10
  ---
11
11
 
12
- ## Why DevBooks?
12
+ ## 为什么选择 DevBooks？
13
13
 
14
- AI coding assistants are powerful, but often **unpredictable**:
14
+ AI 编码助手很强大，但往往**不可预测**：
15
15
 
16
- | Pain point | Outcome |
16
+ | 痛点 | 后果 |
17
17
  |------|------|
18
- | **AI self-declares "done"** | Tests fail, edge cases are missed |
19
- | **Writing tests and code in the same chat** | Tests turn into “pass tests” instead of spec verification |
20
- | **No verification gates** | False completion silently ships |
21
- | **Only works for greenfield (0→1)** | Brownfield repos have no on-ramp |
22
- | **Too few commands** | Complex changes are not just "spec/apply/archive" |
23
-
24
- **DevBooks provides**:
25
- - **Evidence-based done**: completion is defined by tests/build/evidence, not AI self-evaluation
26
- - **Enforced role isolation**: Test Owner and Coder must work in separate conversations
27
- - **Multiple quality gates**: green evidence checks, task completion, role boundary checks
28
- - **21 Skills**: proposal, design, debate, review, entropy metrics, federation, and more
18
+ | **AI 自评"已完成"** | 实际测试不过、边界条件遗漏 |
19
+ | **同一对话写测试又写代码** | 测试沦为"通过性测试"，而非验证规格 |
20
+ | **无验证闸门** | 伪完成悄悄进入生产环境 |
21
+ | **只支持 0→1 项目** | 存量代码库无从下手 |
22
+ | **命令太少** | 复杂变更不只是"spec/apply/archive" |
23
+
24
+ **DevBooks 的解决方案**：
25
+ - **基于证据的完成**：完成由测试/构建/证据定义，而非 AI 自我评估
26
+ - **强制角色隔离**：Test Owner 与 Coder 必须在独立对话中工作
27
+ - **多重质量闸门**：Green 证据检查、任务完成率、角色边界检查
28
+ - **21 个 Skills**：覆盖提案、设计、对辩、评审、熵度量、联邦分析等
29
29
 
30
30
  ---
31
31
 
32
- ## DevBooks At a Glance (Comparison)
32
+ ## DevBooks 对比一览
33
33
 
34
- | Dimension | DevBooks | OpenSpec | spec-kit | No spec |
34
+ | 维度 | DevBooks | OpenSpec | spec-kit | 无规格 |
35
35
  |------|----------|----------|----------|--------|
36
- | Spec-driven workflow | Yes | Yes | Yes | No |
37
- | Artifact traceability | Change package (proposal/design/spec/tasks/verification/evidence) | Mostly folder/file organization | Docs + tasks orchestration | None |
38
- | Role & responsibility boundaries | **Enforced** (Test Owner / Coder) | Convention-based (not enforced) | Convention-based (not enforced) | None |
39
- | Definition of Done (DoD) | **Evidence + gates** (tests/build/audit) | Manual definition/checks | Manual definition/checks | Often subjective |
40
- | Code quality assurance | Gates + metrics (entropy/hotspots) + review roles | External tools / manual review | External tools / manual review | Unstable |
41
- | Impact analysis | CKB graph capability (falls back to grep) | Text search / manual reasoning | Text search / manual reasoning | Easy to miss |
42
- | Brownfield onboarding | Baseline specs/glossary/minimal verification anchors | Manual | Limited | - |
43
- | Automation coverage | 21 Skills (proposal→implementation→archive loop) | 3 core commands | Toolkit (greenfield-leaning) | - |
36
+ | 规格驱动工作流 | 是 | 是 | 是 | 否 |
37
+ | 变更产物的可追溯性 | 变更包集中存档（proposal/design/spec/tasks/verification/evidence） | 主要以变更目录/文件组织为主 | 以文档+任务编排为主 | 无 |
38
+ | 角色与职责边界 | **强制隔离**（Test Owner / Coder） | 约定为主（不强制） | 约定为主（不强制） | 无 |
39
+ | 完成判据（DoD） | **证据驱动 + 闸门**（测试/构建/审计） | 人工定义/人工检查 | 人工定义/人工检查 | 常依赖主观判断 |
40
+ | 代码质量保障 | 守门 + 指标（熵度量/热点）+ Review 角色 | 依赖外部工具/人工 review | 依赖外部工具/人工 review | 不稳定 |
41
+ | 影响面分析 | CKB 图基能力（可降级 Grep） | 文本搜索/人工推导 | 文本搜索/人工推导 | 容易漏改 |
42
+ | 存量项目起步 | 自动生成基线规格/术语表/最小验证锚点 | 手动补齐 | 有限 | - |
43
+ | 自动化覆盖面 | 21 个 Skills（提案→实现→归档闭环） | 3 个核心命令 | 工具包（偏 0→1） | - |
44
44
 
45
45
  ---
46
46
 
47
- ## How It Works
47
+ ## 工作原理
48
48
 
49
49
  ```
50
- DevBooks Workflow
51
-
52
- PROPOSAL stage APPLY stage ARCHIVE stage
53
- (no coding) (role isolation enforced) (quality gates)
54
-
55
- ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
56
- │ /devbooks: │ │ Chat A │ │ /devbooks: │
57
- │ proposal │ │ ┌───────────┐ │ │ gardener │
58
- │ impact │────────────│ │Test Owner │ │──────────────│ delivery │
59
- │ design │ │ │(Red first)│ │ │ │
60
- │ spec │ │ └───────────┘ │ │ Gates: │
61
- │ plan │ │ │ │ ✓ Green evidence│
62
- └─────────────────┘ │ Chat B │ │ ✓ Tasks done │
63
- │ │ ┌───────────┐ │ │ ✓ Role boundary│
64
- ▼ │ │ Coder │ │ │ ✓ No failures │
65
- ┌─────────────────┐ │ │(no tests!)│ │ └─────────────────┘
66
- │ Triangle debate │ │ └───────────┘ │
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
67
  │ Author/Challenger│ └─────────────────┘
68
68
  │ /Judge │
69
69
  └─────────────────┘
70
70
  ```
71
71
 
72
- **Hard constraint**: Test Owner and Coder **must work in separate conversations**. This is not a suggestion. Coder cannot modify `tests/**`. “Done” is defined by tests/build verification, not AI self-evaluation.
72
+ **核心约束**：Test Owner 与 Coder **必须在独立对话**中工作。这是硬性约束，不是建议。Coder 不能修改 `tests/**`，完成由测试/构建验证，而非 AI 自评。
73
73
 
74
74
  ---
75
75
 
76
- ## Quick Start
76
+ ## 快速开始
77
77
 
78
- ### Supported AI tools
78
+ ### 支持的 AI 工具
79
79
 
80
- | Tool | Support Level | Slash Commands | Config File |
81
- |------|---------------|----------------|-------------|
82
- | **Claude Code** | Full Skills | `/devbooks:*` | `CLAUDE.md` |
83
- | **Codex CLI** | Full Skills | `/devbooks:*` | `AGENTS.md` |
84
- | **Qoder** | Full Skills | `/devbooks:*` | `AGENTS.md` |
85
- | **Cursor** | Rules | - | `.cursor/rules/` |
86
- | **Windsurf** | Rules | - | `.windsurf/rules/` |
87
- | **Gemini CLI** | Rules | - | `GEMINI.md` |
88
- | **Continue** | Rules | - | `.continue/rules/` |
89
- | **GitHub Copilot** | Instructions | - | `.github/copilot-instructions.md` |
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` |
90
91
 
91
- > **Tip**: For tools without Slash command support, use natural language, e.g., "Run DevBooks proposal skill..."
92
+ > **提示**：对于不支持 Slash 命令的工具，使用自然语言指令，例如："运行 DevBooks proposal skill..."
92
93
 
93
- ### Install & init
94
+ ### 安装与初始化
94
95
 
95
- **Install via npm (recommended):**
96
+ **npm 安装（推荐）：**
96
97
 
97
98
  ```bash
98
- # global install
99
+ # 全局安装
99
100
  npm install -g dev-playbooks-cn
100
101
 
101
- # init inside your project
102
+ # 在项目中初始化
102
103
  dev-playbooks-cn init
103
104
  ```
104
105
 
105
- **One-off usage:**
106
+ **一次性使用：**
106
107
 
107
108
  ```bash
108
109
  npx dev-playbooks-cn@latest init
109
110
  ```
110
111
 
111
- **From source (contributors):**
112
+ **从源码安装（贡献者）：**
112
113
 
113
114
  ```bash
114
- ../scripts/install-skills.sh
115
+ ./scripts/install-skills.sh
115
116
  ```
116
117
 
117
- ### Install targets
118
+ ### 安装落点
118
119
 
119
- After initialization:
120
- - Claude Code: `~/.claude/skills/devbooks-*`
121
- - Codex CLI: `~/.codex/skills/devbooks-*`
122
- - Qoder: `~/.qoder/` (manual setup required)
120
+ 初始化后：
121
+ - Claude Code：`~/.claude/skills/devbooks-*`
122
+ - Codex CLI：`$CODEX_HOME/skills/devbooks-*`（默认 `~/.codex/skills/devbooks-*`）
123
123
 
124
- ### Quick integration
124
+ ### 快速集成
125
125
 
126
- DevBooks uses two directory roots:
126
+ DevBooks 使用两个目录根：
127
127
 
128
- | Directory | Purpose | Default |
128
+ | 目录 | 用途 | 默认值 |
129
129
  |------|------|--------|
130
- | `<truth-root>` | Current specs (read-only truth) | `dev-playbooks/specs/` |
131
- | `<change-root>` | Change packages (workspace) | `dev-playbooks/changes/` |
130
+ | `<truth-root>` | 当前规格（只读真理） | `dev-playbooks/specs/` |
131
+ | `<change-root>` | 变更包（工作区） | `dev-playbooks/changes/` |
132
132
 
133
- See `../docs/DevBooks集成模板（协议无关）.md` (currently in Chinese), or use `../docs/DevBooks安装提示词.md` to let your assistant configure it automatically.
133
+ 详见 `../docs/DevBooks集成模板（协议无关）.md` 或使用 `../docs/DevBooks安装提示词.md` 让 AI 自动配置。
134
134
 
135
135
  ---
136
136
 
137
- ## Day-to-Day Change Workflow
137
+ ## 日常变更工作流
138
138
 
139
- ### Use Router (recommended)
139
+ ### 使用 Router（推荐）
140
140
 
141
141
  ```
142
- /devbooks:router <your request>
142
+ /devbooks:router <你的需求>
143
143
  ```
144
144
 
145
- Router analyzes your request and outputs an execution plan (which command to run next).
145
+ Router 分析需求并输出执行计划，告诉你下一步用哪个命令。
146
146
 
147
- ### Direct commands
147
+ ### 直达命令
148
148
 
149
- Once you know the flow, call the Skills directly:
149
+ 熟悉流程后，直接调用 Skill：
150
150
 
151
- **1) Proposal stage (no coding)**
151
+ **1. Proposal 阶段（禁止编码）**
152
152
 
153
153
  ```
154
- /devbooks:proposal Add OAuth2 user authentication
154
+ /devbooks:proposal 添加 OAuth2 用户认证
155
155
  ```
156
156
 
157
- Artifacts: `proposal.md` (required), `design.md`, `tasks.md`
157
+ 产物：`proposal.md`（必需）、`design.md`、`tasks.md`
158
158
 
159
- **2) Apply stage (role isolation enforced)**
159
+ **2. Apply 阶段（强制角色隔离）**
160
160
 
161
- You must use **two separate conversations**:
161
+ 必须开 **2 个独立对话**：
162
162
 
163
163
  ```
164
- # Chat A - Test Owner
164
+ # 对话 A - Test Owner
165
165
  /devbooks:test add-oauth2
166
166
 
167
- # Chat B - Coder
167
+ # 对话 B - Coder
168
168
  /devbooks:code add-oauth2
169
169
  ```
170
170
 
171
- - Test Owner: writes `verification.md` + tests, runs **Red** first
172
- - Coder: implements per `tasks.md`, makes gates **Green** (cannot modify tests)
171
+ - Test Owner：写 `verification.md` + 测试，先跑 **Red**
172
+ - Coder：按 `tasks.md` 实现，让闸门 **Green**（禁止改测试）
173
173
 
174
- **3) Review stage**
174
+ **3. Review 阶段**
175
175
 
176
176
  ```
177
177
  /devbooks:review add-oauth2
178
178
  ```
179
179
 
180
- **4) Archive stage**
180
+ **4. Archive 阶段**
181
181
 
182
182
  ```
183
183
  /devbooks:gardener add-oauth2
@@ -185,301 +185,301 @@ You must use **two separate conversations**:
185
185
 
186
186
  ---
187
187
 
188
- ## Command Reference
188
+ ## 命令参考
189
189
 
190
- ### Proposal stage
190
+ ### Proposal 阶段
191
191
 
192
- | Command | Skill | Description |
192
+ | 命令 | Skill | 说明 |
193
193
  |------|-------|------|
194
- | `/devbooks:router` | devbooks-router | Route to the right Skill |
195
- | `/devbooks:proposal` | devbooks-proposal-author | Create a change proposal |
196
- | `/devbooks:impact` | devbooks-impact-analysis | Cross-module impact analysis |
197
- | `/devbooks:challenger` | devbooks-proposal-challenger | Challenge a proposal |
198
- | `/devbooks:judge` | devbooks-proposal-judge | Adjudicate a proposal |
199
- | `/devbooks:debate` | devbooks-proposal-debate-workflow | Triangle debate (Author/Challenger/Judge) |
200
- | `/devbooks:design` | devbooks-design-doc | Create a design doc |
201
- | `/devbooks:spec` | devbooks-spec-contract | Define specs & contracts |
202
- | `/devbooks:c4` | devbooks-c4-map | Generate a C4 map |
203
- | `/devbooks:plan` | devbooks-implementation-plan | Create an implementation plan |
204
-
205
- ### Apply stage
206
-
207
- | Command | Skill | Description |
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 | 创建实现计划 |
204
+
205
+ ### Apply 阶段
206
+
207
+ | 命令 | Skill | 说明 |
208
208
  |------|-------|------|
209
- | `/devbooks:test` | devbooks-test-owner | Test Owner role (separate chat required) |
210
- | `/devbooks:code` | devbooks-coder | Coder role (separate chat required) |
211
- | `/devbooks:backport` | devbooks-design-backport | Backport discoveries to design |
209
+ | `/devbooks:test` | devbooks-test-owner | Test Owner 角色（必须独立对话） |
210
+ | `/devbooks:code` | devbooks-coder | Coder 角色（必须独立对话） |
211
+ | `/devbooks:backport` | devbooks-design-backport | 回写发现到设计文档 |
212
212
 
213
- ### Review stage
213
+ ### Review 阶段
214
214
 
215
- | Command | Skill | Description |
215
+ | 命令 | Skill | 说明 |
216
216
  |------|-------|------|
217
- | `/devbooks:review` | devbooks-code-review | Code review (readability/consistency) |
218
- | `/devbooks:test-review` | devbooks-test-reviewer | Test quality & coverage review |
217
+ | `/devbooks:review` | devbooks-code-review | 代码评审（可读性/一致性） |
218
+ | `/devbooks:test-review` | devbooks-test-reviewer | 测试质量与覆盖率评审 |
219
219
 
220
- ### Archive stage
220
+ ### Archive 阶段
221
221
 
222
- | Command | Skill | Description |
222
+ | 命令 | Skill | 说明 |
223
223
  |------|-------|------|
224
- | `/devbooks:gardener` | devbooks-spec-gardener | Maintain/dedupe specs |
225
- | `/devbooks:delivery` | devbooks-delivery-workflow | End-to-end delivery workflow |
224
+ | `/devbooks:gardener` | devbooks-spec-gardener | 规格维护与去重 |
225
+ | `/devbooks:delivery` | devbooks-delivery-workflow | 完整交付闭环 |
226
226
 
227
- ### Standalone Skills
227
+ ### 独立技能
228
228
 
229
- | Command | Skill | Description |
229
+ | 命令 | Skill | 说明 |
230
230
  |------|-------|------|
231
- | `/devbooks:entropy` | devbooks-entropy-monitor | System entropy metrics |
232
- | `/devbooks:federation` | devbooks-federation | Cross-repo federation analysis |
233
- | `/devbooks:bootstrap` | devbooks-brownfield-bootstrap | Brownfield project bootstrap |
234
- | `/devbooks:index` | devbooks-index-bootstrap | Generate a SCIP index |
231
+ | `/devbooks:entropy` | devbooks-entropy-monitor | 系统熵度量 |
232
+ | `/devbooks:federation` | devbooks-federation | 跨仓库联邦分析 |
233
+ | `/devbooks:bootstrap` | devbooks-brownfield-bootstrap | 存量项目初始化 |
234
+ | `/devbooks:index` | devbooks-index-bootstrap | 生成 SCIP 索引 |
235
235
 
236
236
  ---
237
237
 
238
- ## DevBooks Comparisons
238
+ ## DevBooks 对比
239
239
 
240
240
  ### vs. OpenSpec
241
241
 
242
- [OpenSpec](https://github.com/Fission-AI/OpenSpec) is a lightweight spec-driven framework with three core commands (proposal/apply/archive), organizing changes by feature folders.
242
+ [OpenSpec](https://github.com/Fission-AI/OpenSpec) 是轻量级规格驱动框架，用三个核心命令（proposal/apply/archive）对齐人与 AI，按功能文件夹分组变更。
243
243
 
244
- **What DevBooks adds:**
245
- - **Role isolation**: hard boundary between Test Owner and Coder (separate chats)
246
- - **Quality gates**: 5+ verification gates to block false completion
247
- - **21 Skills**: proposal, debate, review, entropy metrics, federation, etc.
248
- - **Evidence-based done**: tests/build define “done”, not self-evaluation
244
+ **DevBooks 新增：**
245
+ - **角色隔离**：Test Owner 与 Coder 硬边界（必须独立对话）
246
+ - **质量闸门**：5+ 验证闸门拦截伪完成
247
+ - **21 个 Skills**：覆盖提案、对辩、评审、熵度量、联邦分析
248
+ - **基于证据的完成**：测试/构建定义"完成"，而非 AI 自评
249
249
 
250
- **Choose OpenSpec**: you want a lightweight spec workflow.
250
+ **选择 OpenSpec**：简单规格驱动变更，需要轻量工作流。
251
251
 
252
- **Choose DevBooks**: you need role separation and verification gates for larger changes.
252
+ **选择 DevBooks**：大型变更、需要角色分离和质量验证。
253
253
 
254
254
  ### vs. spec-kit
255
255
 
256
- [GitHub spec-kit](https://github.com/github/spec-kit) is a spec-driven toolkit with a constitution file, multi-step refinement, and structured planning.
256
+ [GitHub spec-kit](https://github.com/github/spec-kit) 提供规格驱动开发工具包，有 constitution 文件、多步骤细化和结构化规划。
257
257
 
258
- **What DevBooks adds:**
259
- - **Brownfield-first**: generates baseline specs for existing repos
260
- - **Role isolation**: test authoring and implementation are separated
261
- - **Quality gates**: runtime verification, not just workflow guidance
262
- - **Prototype mode**: safe experiments without polluting main `src/`
258
+ **DevBooks 新增：**
259
+ - **存量优先**：自动为现有代码库生成基线规格
260
+ - **角色隔离**：测试编写与实现强制分离
261
+ - **质量闸门**：运行时验证，不只是工作流引导
262
+ - **原型模式**：安全实验不污染主 src/
263
263
 
264
- **Choose spec-kit**: greenfield projects with supported AI tools.
264
+ **选择 spec-kit**：0→1 绿地项目，使用支持的 AI 工具。
265
265
 
266
- **Choose DevBooks**: brownfield repos or when you want enforced gates.
266
+ **选择 DevBooks**：存量项目或需要强制质量闸门。
267
267
 
268
268
  ### vs. Kiro.dev
269
269
 
270
- [Kiro](https://kiro.dev/) is an AWS agentic IDE with a three-phase workflow (EARS requirements, design, tasks), but stores specs separately from implementation artifacts.
270
+ [Kiro](https://kiro.dev/) 是 AWS 的代理式 IDE，用三阶段工作流（EARS 格式需求、设计、任务），但规格与实现产物分开存储。
271
271
 
272
- **DevBooks differences:**
273
- - **Change package**: proposal/design/spec/plan/verification/evidence in one place for lifecycle traceability
274
- - **Role isolation**: Test Owner and Coder are separated
275
- - **Quality gates**: verified through gates, not just task completion
272
+ **DevBooks 差异：**
273
+ - **变更包**：每个变更包含 proposal/design/spec/plan/verification/evidence，整个生命周期可在一个位置追溯
274
+ - **角色隔离**：Test Owner 与 Coder 强制分离
275
+ - **质量闸门**：通过闸门验证，不只是任务完成
276
276
 
277
- **Choose Kiro**: you want an IDE experience and AWS ecosystem integration.
277
+ **选择 Kiro**：想要集成 IDE 体验和 AWS 生态。
278
278
 
279
- **Choose DevBooks**: you want change packages to bundle artifacts and enforce role boundaries.
279
+ **选择 DevBooks**：想要变更包捆绑所有产物并强制角色边界。
280
280
 
281
- ### vs. no spec
281
+ ### vs. 无规格
282
282
 
283
- Without specs, the assistant generates code from vague prompts, leading to unpredictable output, scope creep, and “hallucinated completion”.
283
+ 没有规格时，AI 从模糊提示生成代码，导致不可预测的输出、范围蔓延和"幻觉式完成"。
284
284
 
285
- **DevBooks brings:**
286
- - Specs agreed before implementation
287
- - Quality gates that verify real completion
288
- - Role isolation to prevent self-verification
289
- - Evidence chain per change
285
+ **DevBooks 带来：**
286
+ - 实现前商定规格
287
+ - 验证真实完成的质量闸门
288
+ - 防止自我验证的角色隔离
289
+ - 每个变更的证据链
290
290
 
291
291
  ---
292
292
 
293
- ## Core Principles
293
+ ## 核心原则
294
294
 
295
- | Principle | Meaning |
295
+ | 原则 | 说明 |
296
296
  |------|------|
297
- | **Protocol first** | truth/change/archive live in the repo, not only in chat logs |
298
- | **Anchor first** | done is defined by tests/static checks/build/evidence |
299
- | **Role isolation** | Test Owner and Coder must work in separate conversations |
300
- | **Truth root separation** | `<truth-root>` is read-only truth; `<change-root>` is the workspace |
301
- | **Structural gates** | prioritize complexity/coupling/test quality, not proxy metrics |
297
+ | **协议优先** | 真理/变更/归档写进项目，不只存在聊天记录里 |
298
+ | **锚点优先** | 完成由测试、静态分析、构建和证据定义 |
299
+ | **角色隔离** | Test Owner 与 Coder 必须在独立对话中工作 |
300
+ | **真理源分离** | `<truth-root>` 是只读真理；`<change-root>` 是临时工作区 |
301
+ | **结构闸门** | 优先关注复杂度/耦合/测试质量，而非代理指标 |
302
302
 
303
303
  ---
304
304
 
305
- ## Advanced Features
305
+ ## 高级功能
306
306
 
307
307
  <details>
308
- <summary><strong>Quality gates</strong></summary>
308
+ <summary><strong>质量闸门</strong></summary>
309
309
 
310
- DevBooks uses quality gates to block “false done”:
310
+ DevBooks 提供质量闸门拦截"伪完成"：
311
311
 
312
- | Gate | Trigger mode | What it checks |
312
+ | 闸门 | 触发模式 | 检查内容 |
313
313
  |------|----------|----------|
314
- | Green evidence | archive, strict | `evidence/green-final/` exists and is non-empty |
315
- | Task completion | strict | all tasks are done or SKIP-APPROVED |
316
- | Test failure block | archive, strict | no failures in green evidence |
317
- | P0 skip approval | strict | P0 skips require an approval record |
318
- | Role boundary | apply --role | Coder cannot modify tests/, Test Owner cannot modify src/ |
314
+ | Green 证据检查 | archive, strict | `evidence/green-final/` 存在且非空 |
315
+ | 任务完成检查 | strict | tasks.md 中所有任务完成或 SKIP-APPROVED |
316
+ | 测试失败拦截 | archive, strict | Green 证据中无失败模式 |
317
+ | P0 跳过审批 | strict | P0 任务跳过必须有审批记录 |
318
+ | 角色边界检查 | apply --role | Coder 不能改 tests/，Test Owner 不能改 src/ |
319
319
 
320
- Core scripts (in `../skills/devbooks-delivery-workflow/scripts/`):
320
+ 核心脚本（位于 `~/.claude/skills/devbooks-delivery-workflow/scripts/`）：
321
321
  - `change-check.sh --mode proposal|apply|archive|strict`
322
- - `handoff-check.sh` - handoff boundary checks
323
- - `audit-scope.sh` - full audit scan
324
- - `progress-dashboard.sh` - progress visualization
322
+ - `handoff-check.sh` - 角色交接验证
323
+ - `audit-scope.sh` - 全量审计扫描
324
+ - `progress-dashboard.sh` - 进度可视化
325
325
 
326
326
  </details>
327
327
 
328
328
  <details>
329
- <summary><strong>Prototype mode</strong></summary>
329
+ <summary><strong>原型模式</strong></summary>
330
330
 
331
- When the technical approach is uncertain:
331
+ 技术方案不确定时：
332
332
 
333
- 1. Create a prototype: `change-scaffold.sh <change-id> --prototype`
334
- 2. Test Owner with `--prototype`: characterization tests (no Red baseline required)
335
- 3. Coder with `--prototype`: output to `prototype/src/` (isolates main src)
336
- 4. Promote or discard: `prototype-promote.sh <change-id>`
333
+ 1. 创建原型：`change-scaffold.sh <change-id> --prototype`
334
+ 2. Test Owner 用 `--prototype`：表征测试（无需 Red 基线）
335
+ 3. Coder 用 `--prototype`：输出到 `prototype/src/`（隔离主 src）
336
+ 4. 提升或丢弃：`prototype-promote.sh <change-id>`
337
337
 
338
- Prototype mode prevents experimental code from polluting the main tree.
338
+ 原型模式防止实验代码污染主源码树。
339
339
 
340
- Scripts live in `../skills/devbooks-delivery-workflow/scripts/`.
340
+ 脚本位于 `~/.claude/skills/devbooks-delivery-workflow/scripts/`。
341
341
 
342
342
  </details>
343
343
 
344
344
  <details>
345
- <summary><strong>Entropy monitoring</strong></summary>
345
+ <summary><strong>熵度量监控</strong></summary>
346
346
 
347
- DevBooks tracks four dimensions of system entropy:
347
+ DevBooks 跟踪四维系统熵：
348
348
 
349
- | Metric | What it measures |
349
+ | 指标 | 测量内容 |
350
350
  |------|----------|
351
- | Structural entropy | module complexity and coupling |
352
- | Change entropy | change patterns and volatility |
353
- | Test entropy | coverage/quality decay over time |
354
- | Dependency entropy | external dependency health |
351
+ | 结构熵 | 模块复杂度和耦合 |
352
+ | 变更熵 | 变动和波动模式 |
353
+ | 测试熵 | 测试覆盖率和质量衰减 |
354
+ | 依赖熵 | 外部依赖健康度 |
355
355
 
356
- Use `/devbooks:entropy` to generate reports and identify refactor opportunities.
356
+ 用 `/devbooks:entropy` 生成报告，识别重构机会。
357
357
 
358
- Scripts (in `../skills/devbooks-entropy-monitor/scripts/`): `entropy-measure.sh`, `entropy-report.sh`
358
+ 脚本（位于 `~/.claude/skills/devbooks-entropy-monitor/scripts/`）：`entropy-measure.sh`、`entropy-report.sh`
359
359
 
360
360
  </details>
361
361
 
362
362
  <details>
363
- <summary><strong>Brownfield project bootstrap</strong></summary>
363
+ <summary><strong>存量项目初始化</strong></summary>
364
364
 
365
- When `<truth-root>` is empty:
365
+ 当 `<truth-root>` 为空时：
366
366
 
367
367
  ```
368
368
  /devbooks:bootstrap
369
369
  ```
370
370
 
371
- Generates:
372
- - project profile and glossary
373
- - baseline specs from existing code
374
- - minimal verification anchors
375
- - module dependency map
376
- - technical debt hotspots
371
+ 生成：
372
+ - 项目画像和术语表
373
+ - 从现有代码生成基线规格
374
+ - 最小验证锚点
375
+ - 模块依赖图
376
+ - 技术债热点
377
377
 
378
378
  </details>
379
379
 
380
380
  <details>
381
- <summary><strong>Cross-repo federation</strong></summary>
381
+ <summary><strong>跨仓库联邦</strong></summary>
382
382
 
383
- For multi-repo analysis:
383
+ 多仓库分析：
384
384
 
385
385
  ```
386
386
  /devbooks:federation
387
387
  ```
388
388
 
389
- Analyzes cross-repo contracts and dependencies to support coordinated changes.
389
+ 分析跨仓库边界的契约和依赖，支持协调变更。
390
390
 
391
391
  </details>
392
392
 
393
393
  <details>
394
- <summary><strong>MCP auto-detection</strong></summary>
394
+ <summary><strong>MCP 自动检测</strong></summary>
395
395
 
396
- DevBooks Skills support graceful MCP (Model Context Protocol) degradation: you can run the full workflow without MCP/CKB; when CKB (Code Knowledge Base) is detected, DevBooks automatically enables graph-based capabilities for more accurate “scope/reference/call chain” analysis.
396
+ DevBooks Skills 支持 MCP（Model Context Protocol）优雅降级：在没有 MCP/CKB 的环境也能跑完整工作流；一旦检测到 CKB（Code Knowledge Base）可用，就自动启用图基能力，把"范围/引用/调用链"分析做得更准。
397
397
 
398
- ### What is it for?
398
+ ### 它有什么用？
399
399
 
400
- - **More accurate impact analysis**: upgrades from “file-level guesses” to “symbol references + call graphs”
401
- - **More focused reviews**: automatically pulls hotspots and prioritizes high-risk areas (tech debt/high churn)
402
- - **Less manual grep**: reduces noise and repeated confirmation in large repos
400
+ - **影响分析更精确**：从"文件级猜测"升级到"符号级引用 + 调用图"，降低漏改风险
401
+ - **审查更有重点**：自动拉取热点文件，优先关注高风险区域（技术债/高变动）
402
+ - **大仓库更省心**：减少手动 Grep 的噪音与反复确认
403
403
 
404
- ### MCP status and behavior
404
+ ### MCP 状态与行为
405
405
 
406
- | MCP status | Behavior |
406
+ | MCP 状态 | 行为 |
407
407
  |----------|------|
408
- | CKB available | Enhanced mode: symbol-level impact/references/call graph/hotspots (`mcp__ckb__analyzeImpact`, `mcp__ckb__findReferences`, `mcp__ckb__getCallGraph`, `mcp__ckb__getHotspots`) |
409
- | CKB unavailable | Basic mode: Grep + Glob text search (full functionality, lower precision) |
408
+ | CKB 可用 | 增强模式：符号级影响分析/引用查找/调用图/热点（`mcp__ckb__analyzeImpact`、`mcp__ckb__findReferences`、`mcp__ckb__getCallGraph`、`mcp__ckb__getHotspots`） |
409
+ | CKB 不可用 | 基础模式：Grep + Glob 文本搜索（功能完整，精度降低） |
410
410
 
411
- ### Auto detection
411
+ ### 自动检测
412
412
 
413
- - Skills that depend on MCP call `mcp__ckb__getStatus` first (2s timeout)
414
- - Timeout/failure → silently falls back to basic mode (non-blocking)
415
- - No manual “basic/enhanced” switch required
413
+ - 需要 MCP 的 Skills 会先调用 `mcp__ckb__getStatus` 探测可用性（2s 超时）
414
+ - 超时/失败 → 静默降级到基础模式，不阻塞执行
415
+ - 无需手动选择"基础/增强"模式
416
416
 
417
- To enable enhanced mode: configure CKB per `../docs/推荐MCP.md` and run `/devbooks:index` to generate `index.scip`.
417
+ 如需启用增强能力：按 `../docs/推荐MCP.md` 配置 CKB，并运行 `/devbooks:index` 生成 `index.scip`。
418
418
 
419
419
  </details>
420
420
 
421
421
  <details>
422
- <summary><strong>Proposal debate workflow</strong></summary>
422
+ <summary><strong>提案对辩工作流</strong></summary>
423
423
 
424
- For strict proposal review, run the triangle debate:
424
+ 严格提案审查用三角对辩：
425
425
 
426
426
  ```
427
427
  /devbooks:debate
428
428
  ```
429
429
 
430
- Three roles:
431
- 1. **Author**: creates and defends the proposal
432
- 2. **Challenger**: challenges assumptions, finds gaps, identifies risks
433
- 3. **Judge**: makes the final decision and records rationale
430
+ 三个角色：
431
+ 1. **Author**：创建并捍卫提案
432
+ 2. **Challenger**：质疑假设、发现缺口、识别风险
433
+ 3. **Judge**：做最终决定、记录理由
434
434
 
435
- Decision: `Approved`, `Revise`, `Rejected`
435
+ 决定结果：`Approved`、`Revise`、`Rejected`
436
436
 
437
437
  </details>
438
438
 
439
439
  ---
440
440
 
441
- ## Migration from Other Frameworks
441
+ ## 从其他框架迁移
442
442
 
443
- DevBooks provides migration scripts to help you transition from other spec-driven development tools.
443
+ DevBooks 提供迁移脚本帮助从其他规格驱动开发工具迁移。
444
444
 
445
- ### Migrate from OpenSpec
445
+ ### 从 OpenSpec 迁移
446
446
 
447
- If you're currently using [OpenSpec](https://github.com/Fission-AI/OpenSpec) with an `openspec/` directory:
447
+ 如果你当前使用 [OpenSpec](https://github.com/Fission-AI/OpenSpec)，有 `openspec/` 目录：
448
448
 
449
449
  ```bash
450
- # Using CLI (recommended)
450
+ # 使用 CLI（推荐）
451
451
  dev-playbooks-cn migrate --from openspec
452
452
 
453
- # Preview changes first
453
+ # 先预览变更
454
454
  dev-playbooks-cn migrate --from openspec --dry-run
455
455
 
456
- # Keep original directory after migration
456
+ # 迁移后保留原目录
457
457
  dev-playbooks-cn migrate --from openspec --keep-old
458
458
  ```
459
459
 
460
- **What gets migrated:**
460
+ **迁移内容：**
461
461
  - `openspec/specs/` → `dev-playbooks/specs/`
462
462
  - `openspec/changes/` → `dev-playbooks/changes/`
463
463
  - `openspec/project.md` → `dev-playbooks/project.md`
464
- - All path references are automatically updated
465
- - AI tool command directories are cleaned up (`.claude/commands/openspec/`, etc.)
464
+ - 所有路径引用自动更新
465
+ - AI 工具命令目录自动清理（`.claude/commands/openspec/` 等）
466
466
 
467
- ### Migrate from GitHub spec-kit
467
+ ### 从 GitHub spec-kit 迁移
468
468
 
469
- If you're using [GitHub spec-kit](https://github.com/github/spec-kit) with `specs/` and `memory/` directories:
469
+ 如果你使用 [GitHub spec-kit](https://github.com/github/spec-kit)，有 `specs/` 和 `memory/` 目录：
470
470
 
471
471
  ```bash
472
- # Using CLI (recommended)
472
+ # 使用 CLI（推荐）
473
473
  dev-playbooks-cn migrate --from speckit
474
474
 
475
- # Preview changes first
475
+ # 先预览变更
476
476
  dev-playbooks-cn migrate --from speckit --dry-run
477
477
 
478
- # Keep original directories after migration
478
+ # 迁移后保留原目录
479
479
  dev-playbooks-cn migrate --from speckit --keep-old
480
480
  ```
481
481
 
482
- **Mapping rules:**
482
+ **映射规则：**
483
483
 
484
484
  | Spec-Kit | DevBooks |
485
485
  |----------|----------|
@@ -490,47 +490,47 @@ dev-playbooks-cn migrate --from speckit --keep-old
490
490
  | `specs/[feature]/quickstart.md` | `changes/[feature]/verification.md` |
491
491
  | `specs/[feature]/contracts/` | `changes/[feature]/specs/` |
492
492
 
493
- ### Migration Features
493
+ ### 迁移功能
494
494
 
495
- Both migration scripts support:
495
+ 两个迁移脚本都支持：
496
496
 
497
- - **Idempotent execution**: Safe to run multiple times
498
- - **Checkpoints**: Resume from where you left off if interrupted
499
- - **Dry-run mode**: Preview changes before applying
500
- - **Automatic backup**: Original files are backed up to `.devbooks/backup/`
501
- - **Reference updates**: Path references in documents are automatically updated
497
+ - **幂等执行**：可安全多次运行
498
+ - **断点续传**：中断后可从断点恢复
499
+ - **试运行模式**：预览变更再执行
500
+ - **自动备份**：原文件备份到 `.devbooks/backup/`
501
+ - **引用更新**：文档中的路径引用自动更新
502
502
 
503
- ### Post-Migration Steps
503
+ ### 迁移后步骤
504
504
 
505
- After migration:
505
+ 迁移后：
506
506
 
507
- 1. Run `dev-playbooks-cn init` to set up DevBooks Skills
508
- 2. Review migrated files in `dev-playbooks/`
509
- 3. Update `verification.md` files with proper AC mappings
510
- 4. Run `/devbooks:bootstrap` if you need baseline specs
507
+ 1. 运行 `dev-playbooks-cn init` 设置 DevBooks Skills
508
+ 2. 检查 `dev-playbooks/` 中的迁移文件
509
+ 3. 更新 `verification.md` 文件的 AC 映射
510
+ 4. 如需基线规格，运行 `/devbooks:bootstrap`
511
511
 
512
512
  ---
513
513
 
514
- ## Repository Structure
514
+ ## 仓库结构
515
515
 
516
516
  ```
517
- skills/ # devbooks-* Skill sources (some ship scripts/)
518
- templates/ # project init templates (used by `dev-playbooks-cn init`)
519
- templates/dev-playbooks/ # DevBooks protocol directory template (copied into your project as `dev-playbooks/`)
520
- scripts/ # install & helper scripts
521
- docs/ # documentation
522
- bin/ # CLI entry
517
+ skills/ # devbooks-* Skills 源码（部分 Skill 自带 scripts/）
518
+ templates/ # 项目初始化模板（`dev-playbooks-cn init` 使用）
519
+ templates/dev-playbooks/ # DevBooks 协议目录模板（初始化后写入项目为 `dev-playbooks/`）
520
+ scripts/ # 安装与辅助脚本
521
+ docs/ # 支持文档
522
+ bin/ # CLI 入口
523
523
  ```
524
524
 
525
525
  ---
526
526
 
527
- ## Documentation
527
+ ## 文档
528
528
 
529
- - [Slash command guide](../docs/Slash 命令使用指南.md)
530
- - [Skills guide](../skills/Skills使用说明.md)
531
- - [MCP configuration recommendations](../docs/推荐MCP.md)
532
- - [Integration template (protocol-agnostic)](../docs/DevBooks集成模板（协议无关）.md)
533
- - [Installation prompt](../docs/DevBooks安装提示词.md)
529
+ - [Slash 命令使用指南](../docs/Slash 命令使用指南.md)
530
+ - [Skills 使用说明](../skills/Skills使用说明.md)
531
+ - [MCP 配置建议](../docs/推荐MCP.md)
532
+ - [集成模板（协议无关）](../docs/DevBooks集成模板（协议无关）.md)
533
+ - [安装提示词](../docs/DevBooks安装提示词.md)
534
534
 
535
535
  ---
536
536