dev-playbooks-cn 2.2.0 → 2.3.0

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 (41) hide show
  1. package/CHANGELOG.md +251 -0
  2. package/README.md +1 -0
  3. package/bin/devbooks.js +42 -4
  4. package/package.json +2 -1
  5. package/scripts/benchmark-scan.sh +67 -0
  6. package/scripts/detect-fancy-words.sh +7 -0
  7. package/skills/_shared/references/AI/350/241/214/344/270/272/350/247/204/350/214/203.md +20 -1
  8. package/skills/_shared/references//344/270/223/345/256/266/345/210/227/350/241/250.md +21 -0
  9. package/skills/_shared/references//345/256/214/345/244/207/346/200/247/346/200/235/347/273/264/346/241/206/346/236/266.md +89 -0
  10. package/skills/devbooks-archiver/SKILL.md +16 -5
  11. package/skills/devbooks-brownfield-bootstrap/SKILL.md +4 -38
  12. package/skills/devbooks-coder/SKILL.md +1 -1
  13. package/skills/devbooks-convergence-audit/SKILL.md +1 -0
  14. package/skills/devbooks-delivery-workflow/SKILL.md +3 -14
  15. package/skills/devbooks-delivery-workflow/scripts/change-check.sh +8 -0
  16. package/skills/devbooks-delivery-workflow/scripts/guardrail-check.sh +39 -10
  17. package/skills/devbooks-design-backport/SKILL.md +2 -4
  18. package/skills/devbooks-design-doc/SKILL.md +5 -3
  19. package/skills/devbooks-docs-consistency/SKILL.md +155 -0
  20. package/skills/devbooks-docs-consistency/references/completeness-dimensions.yaml +25 -0
  21. package/skills/devbooks-docs-consistency/references/doc-classification.yaml +11 -0
  22. package/skills/devbooks-docs-consistency/references/docs-rules-schema.yaml +11 -0
  23. package/skills/devbooks-docs-consistency/scripts/alias.sh +5 -0
  24. package/skills/devbooks-docs-consistency/scripts/completeness-checker.sh +153 -0
  25. package/skills/devbooks-docs-consistency/scripts/doc-classifier.sh +121 -0
  26. package/skills/devbooks-docs-consistency/scripts/git-adapter.sh +32 -0
  27. package/skills/devbooks-docs-consistency/scripts/rules-engine.sh +255 -0
  28. package/skills/devbooks-docs-consistency/scripts/scanner.sh +93 -0
  29. package/skills/devbooks-docs-consistency/scripts/style-checker.sh +123 -0
  30. package/skills/devbooks-entropy-monitor/SKILL.md +3 -35
  31. package/skills/devbooks-impact-analysis/SKILL.md +3 -38
  32. package/skills/devbooks-implementation-plan/SKILL.md +2 -4
  33. package/skills/devbooks-proposal-author/SKILL.md +7 -3
  34. package/skills/devbooks-proposal-challenger/SKILL.md +2 -4
  35. package/skills/devbooks-proposal-judge/SKILL.md +2 -4
  36. package/skills/devbooks-reviewer/SKILL.md +3 -36
  37. package/skills/devbooks-router/SKILL.md +5 -35
  38. package/skills/devbooks-spec-contract/SKILL.md +3 -34
  39. package/skills/devbooks-test-owner/SKILL.md +2 -3
  40. package/skills/devbooks-test-reviewer/SKILL.md +2 -3
  41. package/skills/devbooks-docs-sync/SKILL.md +0 -338
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: devbooks-impact-analysis
3
3
  description: devbooks-impact-analysis:跨模块/跨文件/对外契约变更前做影响分析,产出可直接写入 proposal.md 的 Impact 部分(Scope/Impacts/Risks/Minimal Diff/Open Questions)。用户说"做影响分析/改动面控制/引用查找/受影响模块/兼容性风险"等时使用。
4
+ recommended_experts: ["System Architect"]
4
5
  allowed-tools:
5
6
  - Glob
6
7
  - Grep
@@ -129,42 +130,6 @@ AI:[使用 Grep/CKB 分析引用]
129
130
 
130
131
  ---
131
132
 
132
- ## MCP 增强
133
-
134
- 本 Skill 支持 MCP 运行时增强,自动检测并启用高级功能。
135
-
136
- MCP 增强规则参考:`skills/_shared/MCP增强模板.md`
137
-
138
- ### 依赖的 MCP 服务
139
-
140
- | 服务 | 用途 | 超时 |
141
- |------|------|------|
142
- | `mcp__ckb__analyzeImpact` | 符号级影响分析 | 2s |
143
- | `mcp__ckb__findReferences` | 精确引用查找 | 2s |
144
- | `mcp__ckb__getCallGraph` | 调用图分析 | 2s |
145
- | `mcp__ckb__getStatus` | 检测 CKB 索引可用性 | 2s |
146
-
147
- ### 检测流程
148
-
149
- 1. 调用 `mcp__ckb__getStatus`(2s 超时)
150
- 2. 若 CKB 可用 → 使用 `analyzeImpact` 和 `findReferences` 进行精确分析
151
- 3. 若超时或失败 → 降级到基础模式(Grep 文本搜索)
152
-
153
- ### 增强模式 vs 基础模式
154
-
155
- | 功能 | 增强模式 | 基础模式 |
156
- |------|----------|----------|
157
- | 引用查找 | 符号级精确匹配 | 文本 Grep 搜索 |
158
- | 影响范围 | 调用图传递分析 | 直接引用统计 |
159
- | 风险评估 | 基于调用深度量化 | 基于文件数量估算 |
160
- | 跨模块分析 | 自动识别模块边界 | 需手动指定范围 |
161
-
162
- ### 降级提示
163
-
164
- 当 MCP 不可用时,输出以下提示:
165
-
166
- ```
167
- ⚠️ CKB 不可用,使用 Grep 文本搜索进行影响分析。
168
- 分析结果可能不够精确,建议手动生成 SCIP 索引后重新分析。
169
- ```
133
+ ## MCP 说明
170
134
 
135
+ 本 Skill 不依赖 MCP 服务,无需运行时检测。
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: devbooks-implementation-plan
3
3
  description: devbooks-implementation-plan:从设计文档推导编码计划(tasks.md),输出可跟踪的主线计划/临时计划/断点区,并绑定验收锚点。用户说"写编码计划/Implementation Plan/tasks.md/任务拆解/并行拆分/里程碑/验收锚点"等时使用。
4
+ recommended_experts: ["System Architect", "Product Manager"]
4
5
  allowed-tools:
5
6
  - Glob
6
7
  - Grep
@@ -153,9 +154,6 @@ implementation-plan → test-owner (会话A) → coder (会话B)
153
154
 
154
155
  ---
155
156
 
156
- ## MCP 增强
157
+ ## MCP 说明
157
158
 
158
159
  本 Skill 不依赖 MCP 服务,无需运行时检测。
159
-
160
- MCP 增强规则参考:`skills/_shared/MCP增强模板.md`
161
-
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: devbooks-proposal-author
3
3
  description: devbooks-proposal-author:撰写变更提案 proposal.md(Why/What/Impact + Debate Packet),作为后续 Design/Spec/Plan 的入口。对设计性决策会呈现选项给用户选择。用户说"写提案/proposal/为什么要改/影响范围/坏味道重构提案"等时使用。
4
+ recommended_experts: ["Product Manager", "System Architect"]
4
5
  allowed-tools:
5
6
  - Glob
6
7
  - Grep
@@ -175,9 +176,12 @@ proposal-author → [impact-analysis] → design-doc → [spec-contract] → imp
175
176
 
176
177
  ---
177
178
 
178
- ## MCP 增强
179
+ ## Challenger 审视
179
180
 
180
- Skill 不依赖 MCP 服务,无需运行时检测。
181
+ 在完成提案草案后,执行 Challenger 审视,重点检查遗漏的约束与不确定性,并参考完备性方法论。
182
+
183
+ - 方法论参考:[完备性思维框架](../_shared/references/完备性思维框架.md)
181
184
 
182
- MCP 增强规则参考:`skills/_shared/MCP增强模板.md`
185
+ ## MCP 说明
183
186
 
187
+ 本 Skill 不依赖 MCP 服务,无需运行时检测。
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: devbooks-proposal-challenger
3
3
  description: devbooks-proposal-challenger:对 proposal.md 发起质疑(Challenger)+ 查漏补缺,指出风险/遗漏/不一致并给结论,发现缺失的验收标准和未覆盖场景。用户说"质疑提案/挑刺/风险评估/提案对辩 challenger/查漏补缺"等时使用。
4
+ recommended_experts: ["Product Manager", "System Architect"]
4
5
  allowed-tools:
5
6
  - Glob
6
7
  - Grep
@@ -78,9 +79,6 @@ allowed-tools:
78
79
 
79
80
  ---
80
81
 
81
- ## MCP 增强
82
+ ## MCP 说明
82
83
 
83
84
  本 Skill 不依赖 MCP 服务,无需运行时检测。
84
-
85
- MCP 增强规则参考:`skills/_shared/MCP增强模板.md`
86
-
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: devbooks-proposal-judge
3
3
  description: devbooks-proposal-judge:对 proposal 阶段进行裁决(Judge),输出 Approved/Revise/Rejected 并写回 proposal.md 的 Decision Log。用户说"裁决提案/提案评审/Approved Revise Rejected/decision log"等时使用。
4
+ recommended_experts: ["Product Manager", "System Architect"]
4
5
  allowed-tools:
5
6
  - Glob
6
7
  - Grep
@@ -70,9 +71,6 @@ allowed-tools:
70
71
 
71
72
  ---
72
73
 
73
- ## MCP 增强
74
+ ## MCP 说明
74
75
 
75
76
  本 Skill 不依赖 MCP 服务,无需运行时检测。
76
-
77
- MCP 增强规则参考:`skills/_shared/MCP增强模板.md`
78
-
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: devbooks-reviewer
3
3
  description: devbooks-reviewer:以 Reviewer 角色做可读性/一致性/依赖健康/坏味道审查,只输出审查意见与可执行建议,不讨论业务正确性。用户说"帮我做代码评审/review 可维护性/坏味道/依赖风险/一致性建议",或在 DevBooks apply 阶段以 reviewer 执行时使用。
4
+ recommended_experts: ["System Architect", "Security Expert"]
4
5
  allowed-tools:
5
6
  - Glob
6
7
  - Grep
@@ -206,40 +207,6 @@ Review 通过后,Reviewer 必须执行:
206
207
 
207
208
  ---
208
209
 
209
- ## MCP 增强
210
-
211
- 本 Skill 支持 MCP 运行时增强,自动检测并启用高级功能。
212
-
213
- MCP 增强规则参考:`skills/_shared/MCP增强模板.md`
214
-
215
- ### 依赖的 MCP 服务
216
-
217
- | 服务 | 用途 | 超时 |
218
- |------|------|------|
219
- | `mcp__ckb__getHotspots` | 检测热点文件,优先审查 | 2s |
220
- | `mcp__ckb__getStatus` | 检测 CKB 索引可用性 | 2s |
221
-
222
- ### 检测流程
223
-
224
- 1. 调用 `mcp__ckb__getStatus`(2s 超时)
225
- 2. 若 CKB 可用 → 调用 `mcp__ckb__getHotspots` 获取热点文件
226
- 3. 对热点文件进行优先审查
227
- 4. 若超时或失败 → 降级到基础模式
228
-
229
- ### 增强模式 vs 基础模式
230
-
231
- | 功能 | 增强模式 | 基础模式 |
232
- |------|----------|----------|
233
- | 热点优先审查 | 自动识别高风险文件 | 按变更顺序审查 |
234
- | 依赖方向检查 | 基于模块图分析 | 基于文件路径推断 |
235
- | 循环依赖检测 | CKB 精确检测 | Grep 启发式检测 |
236
-
237
- ### 降级提示
238
-
239
- 当 MCP 不可用时,输出以下提示:
240
-
241
- ```
242
- ⚠️ CKB 不可用,无法进行热点优先审查。
243
- 按变更文件顺序进行审查。
244
- ```
210
+ ## MCP 说明
245
211
 
212
+ 本 Skill 不依赖 MCP 服务,无需运行时检测。
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: devbooks-router
3
3
  description: devbooks-router:DevBooks 工作流入口引导:帮助用户确定从哪个 skill 开始,检测项目当前状态,给出最短闭环路径。用户说"下一步怎么做/从哪开始/按 devbooks 跑闭环/项目状态"等时使用。注意:skill 完成后的路由由各 skill 自己负责,无需调用 router。
4
+ recommended_experts: ["System Architect", "Product Manager"]
4
5
  allowed-tools:
5
6
  - Glob
6
7
  - Grep
@@ -236,7 +237,7 @@ LSC(大规模同质化修改)建议:
236
237
  触发信号:用户说"更新文档/同步文档/README 更新/API 文档"等。
237
238
 
238
239
  默认路由:
239
- - `devbooks-docs-sync`(维护用户文档与代码一致性)
240
+ - `devbooks-docs-consistency`(维护用户文档与代码一致性)
240
241
  - 增量模式:在变更包上下文中,只更新本次 change 相关的文档
241
242
  - 全局模式:带 --global 参数,扫描全部文档并生成差异报告
242
243
 
@@ -253,7 +254,7 @@ LSC(大规模同质化修改)建议:
253
254
  默认路由:
254
255
  - 若本次产生了 spec delta:`devbooks-archiver`(先修剪 `<truth-root>/**` 再归档合并)
255
256
  - 若需要回写设计决策:`devbooks-design-backport`(按需)
256
- - 若影响用户文档:`devbooks-docs-sync`(确保文档与代码一致)
257
+ - 若影响用户文档:`devbooks-docs-consistency`(确保文档与代码一致)
257
258
 
258
259
  归档前的确定性检查(推荐):
259
260
  - `change-check.sh <change-id> --mode strict ...`(要求:proposal 已 Approved、tasks 全勾选、trace matrix 无 TODO、结构守门决策已填写)
@@ -340,37 +341,6 @@ DevBooks 使用 `devbooks-proposal-author skill`、`devbooks-test-owner/coder sk
340
341
 
341
342
  ---
342
343
 
343
- ## MCP 增强
344
+ ## MCP 说明
344
345
 
345
- 本 Skill 支持 MCP 运行时增强,自动检测并启用高级功能。
346
-
347
- MCP 增强规则参考:`skills/_shared/MCP增强模板.md`
348
-
349
- ### 依赖的 MCP 服务
350
-
351
- | 服务 | 用途 | 超时 |
352
- |------|------|------|
353
- | `mcp__ckb__getStatus` | 检测 CKB 索引可用性 | 2s |
354
-
355
- ### 检测流程
356
-
357
- 1. 调用 `mcp__ckb__getStatus`(2s 超时)
358
- 2. 若 CKB 可用 → 在路由建议中标注"图基能力已激活"
359
- 3. 若超时或失败 → 在路由建议中标注"图基能力降级",建议手动生成 SCIP 索引
360
-
361
- ### 增强模式 vs 基础模式
362
-
363
- | 功能 | 增强模式 | 基础模式 |
364
- |------|----------|----------|
365
- | 影响分析推荐 | 使用 CKB 精确分析 | 使用 Grep 文本搜索 |
366
- | 代码导航 | 符号级跳转可用 | 文件级搜索 |
367
- | 热点检测 | CKB 实时分析 | 不可用 |
368
-
369
- ### 降级提示
370
-
371
- 当 MCP 不可用时,输出以下提示:
372
-
373
- ```
374
- ⚠️ CKB 索引未激活,图基能力(影响分析、调用图等)将降级。
375
- 建议手动生成 SCIP 索引以启用完整功能。
376
- ```
346
+ 本 Skill 不依赖 MCP 服务,无需运行时检测。
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: devbooks-spec-contract
3
3
  description: devbooks-spec-contract:定义对外行为规格与契约(Requirements/Scenarios/API/Schema/兼容策略/迁移),并建议或生成 contract tests。合并了原 spec-delta 和 contract-data 的功能。用户说"写规格/spec/契约/OpenAPI/Schema/兼容策略/contract tests"等时使用。
4
+ recommended_experts: ["System Architect", "Product Manager"]
4
5
  allowed-tools:
5
6
  - Glob
6
7
  - Grep
@@ -188,38 +189,6 @@ spec-contract → implementation-plan → test-owner → coder
188
189
 
189
190
  ---
190
191
 
191
- ## MCP 增强
192
+ ## MCP 说明
192
193
 
193
- 本 Skill 支持 MCP 运行时增强,自动检测并启用高级功能。
194
-
195
- MCP 增强规则参考:`skills/_shared/MCP增强模板.md`
196
-
197
- ### 依赖的 MCP 服务
198
-
199
- | 服务 | 用途 | 超时 |
200
- |------|------|------|
201
- | `mcp__ckb__findReferences` | 检测契约引用范围 | 2s |
202
- | `mcp__ckb__getStatus` | 检测 CKB 索引可用性 | 2s |
203
-
204
- ### 检测流程
205
-
206
- 1. 调用 `mcp__ckb__getStatus`(2s 超时)
207
- 2. 若 CKB 可用 → 使用 `findReferences` 检测契约符号的引用范围
208
- 3. 若超时或失败 → 降级到 Grep 文本搜索
209
-
210
- ### 增强模式 vs 基础模式
211
-
212
- | 功能 | 增强模式 | 基础模式 |
213
- |------|----------|----------|
214
- | 引用检测 | 符号级精确匹配 | Grep 文本搜索 |
215
- | 契约影响范围 | 调用图分析 | 直接引用统计 |
216
- | 兼容性风险 | 自动评估 | 手动判断 |
217
-
218
- ### 降级提示
219
-
220
- 当 MCP 不可用时,输出以下提示:
221
-
222
- ```
223
- ⚠️ CKB 不可用,使用 Grep 文本搜索检测契约引用。
224
- 结果可能不够精确,建议手动生成 SCIP 索引。
225
- ```
194
+ 本 Skill 不依赖 MCP 服务,无需运行时检测。
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: devbooks-test-owner
3
3
  description: devbooks-test-owner:以 Test Owner 角色把设计/规格转成可执行验收测试与追溯文档(verification.md),强调与实现(Coder)独立对话、先跑出 Red 基线。用户说"写测试/验收测试/追溯矩阵/verification.md/Red-Green/contract tests/fitness tests",或在 DevBooks apply 阶段以 test owner 执行时使用。
4
+ recommended_experts: ["Test Engineer"]
4
5
  allowed-tools:
5
6
  - Glob
6
7
  - Grep
@@ -279,8 +280,6 @@ proposal → design → [TEST-OWNER] → [CODER] → [TEST-OWNER] → code-revie
279
280
 
280
281
  ---
281
282
 
282
- ## MCP 增强
283
+ ## MCP 说明
283
284
 
284
285
  本 Skill 不依赖 MCP 服务,无需运行时检测。
285
-
286
- MCP 增强规则参考:`~/.claude/skills/_shared/MCP增强模板.md`
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: devbooks-test-reviewer
3
3
  description: devbooks-test-reviewer:以 Test Reviewer 角色评审 tests/ 测试质量(覆盖、边界、可读性、可维护性),只输出评审意见,不修改代码。用户说“测试评审/评审测试质量/覆盖率/边界条件”等时使用。
4
+ recommended_experts: ["Test Engineer"]
4
5
  allowed-tools:
5
6
  - Glob
6
7
  - Grep
@@ -244,12 +245,10 @@ allowed-tools:
244
245
 
245
246
  ---
246
247
 
247
- ## MCP 增强
248
+ ## MCP 说明
248
249
 
249
250
  本 Skill 不依赖 MCP 服务,无需运行时检测。
250
251
 
251
- MCP 增强规则参考:`skills/_shared/MCP增强模板.md`
252
-
253
252
  ---
254
253
 
255
254
  *此 Skill 文档遵循 devbooks-* 规范。*
@@ -1,338 +0,0 @@
1
- ---
2
- name: devbooks-docs-sync
3
- description: devbooks-docs-sync:维护项目文档(README、API 文档等面向用户的文档)与代码的一致性。支持增量模式(针对 change)和全局模式(一致性检查)。用户说"更新文档/同步文档/文档对齐/README 更新/API 文档更新"等时使用。
4
- allowed-tools:
5
- - Glob
6
- - Grep
7
- - Read
8
- - Edit
9
- - Write
10
- - Bash
11
- ---
12
-
13
- # DevBooks:文档同步(Docs Sync)
14
-
15
- ## 前置:配置发现(协议无关)
16
-
17
- 执行前**必须**按以下顺序查找配置(找到后停止):
18
- 1. `.devbooks/config.yaml`(如存在)→ 解析并使用其中的映射
19
- 2. `dev-playbooks/project.md`(如存在)→ Dev-Playbooks 协议,使用默认映射
20
- 3. `project.md`(如存在)→ template 协议,使用默认映射
21
- 4. 若仍无法确定 → **停止并询问用户**
22
-
23
- ---
24
-
25
- ## 角色定义
26
-
27
- **docs-sync** 是 DevBooks Apply 阶段的文档维护角色,负责确保面向用户的文档与代码保持一致。
28
-
29
- ### 文档分类
30
-
31
- | 文档类型 | 目标受众 | 是否由本 Skill 维护 | 示例 |
32
- |----------|----------|:-------------------:|------|
33
- | **用户文档** | 最终用户 | ✅ | README.md, docs/*.md, API.md |
34
- | **开发者规范** | AI/开发者 | ❌(由其他 skill 维护) | dev-playbooks/, AGENTS.md |
35
- | **代码注释** | 开发者 | ❌(由 coder 维护) | JSDoc, 行内注释 |
36
-
37
- ### 与其他角色的区别
38
-
39
- | 维度 | docs-sync | coder | reviewer |
40
- |------|:---------:|:-----:|:--------:|
41
- | 维护用户文档 | ✅ | ❌ | ❌ |
42
- | 修改代码 | ❌ | ✅ | ❌ |
43
- | 修改测试 | ❌ | ❌ | ❌ |
44
- | 审查代码质量 | ❌ | ❌ | ✅ |
45
-
46
- ---
47
-
48
- ## 关键约束
49
-
50
- ### CON-DOCS-001:只维护用户文档
51
- - **允许修改**:README.md、docs/、API.md、CHANGELOG.md、配置说明等
52
- - **禁止修改**:dev-playbooks/、AGENTS.md、CLAUDE.md、src/、tests/
53
-
54
- ### CON-DOCS-002:不引入新功能
55
- - 只同步现有功能的文档描述
56
- - 不添加代码中不存在的功能说明
57
- - 如发现功能缺失,应提出建议而非自行添加
58
-
59
- ### CON-DOCS-003:保持风格一致
60
- - 遵循项目现有的文档风格
61
- - 使用 `<truth-root>/_meta/glossary.md` 中的统一术语
62
- - 保持中英文一致性(如项目有多语言文档)
63
-
64
- ---
65
-
66
- ## 运行模式
67
-
68
- ### 模式一:增量模式(Change-Scoped)
69
-
70
- **触发条件**:在变更包上下文中运行
71
-
72
- **行为**:
73
- 1. 分析本次 change 影响的公共 API/功能/配置
74
- 2. 定位相关的用户文档
75
- 3. 更新受影响的文档部分
76
- 4. 输出变更摘要
77
-
78
- **执行流程**:
79
- ```
80
- 1. 读取 <change-root>/<change-id>/design.md 了解变更内容
81
- 2. 识别影响范围:
82
- - 新增/修改的公共 API
83
- - 配置项变更
84
- - 用户可见行为变更
85
- 3. 定位需要更新的文档:
86
- - README.md 中的功能说明
87
- - API.md 中的接口文档
88
- - docs/ 中的使用指南
89
- 4. 执行更新并记录
90
- ```
91
-
92
- ### 模式二:全局模式(Global Sync)
93
-
94
- **触发条件**:用户显式请求全局同步(如 `devbooks-docs-sync --global`)
95
-
96
- **行为**:
97
- 1. 扫描项目所有公共 API 和功能
98
- 2. 比对文档覆盖情况
99
- 3. 生成差异报告
100
- 4. 询问用户确认后执行修复
101
-
102
- **执行流程**:
103
- ```
104
- 1. 扫描代码中的公共接口(导出函数、类、配置)
105
- 2. 扫描用户文档中的功能描述
106
- 3. 生成对比矩阵:
107
- - 代码有文档无:需要补充
108
- - 代码无文档有:过时文档
109
- - 代码文档不一致:需要同步
110
- 4. 输出差异报告
111
- 5. 用户确认后执行修复
112
- ```
113
-
114
- ---
115
-
116
- ## 检查清单
117
-
118
- ### 文档覆盖检查
119
-
120
- - [ ] README.md 中的功能列表是否与实际功能一致
121
- - [ ] API 文档是否覆盖所有公共接口
122
- - [ ] 配置说明是否与实际配置项一致
123
- - [ ] 示例代码是否能正常运行
124
-
125
- ### 一致性检查
126
-
127
- - [ ] 文档中的术语是否与 glossary.md 一致
128
- - [ ] 版本号是否与 package.json 一致
129
- - [ ] 命令行示例是否与实际 CLI 一致
130
- - [ ] 链接是否有效(无死链)
131
-
132
- ### 完整性检查
133
-
134
- - [ ] 安装指南是否完整
135
- - [ ] 快速开始是否可用
136
- - [ ] 常见问题是否更新
137
- - [ ] CHANGELOG 是否记录了重要变更
138
-
139
- ---
140
-
141
- ## 输出格式
142
-
143
- ### 增量模式输出
144
-
145
- ```markdown
146
- # Docs Sync Report: <change-id>
147
-
148
- ## 影响分析
149
-
150
- | 变更类型 | 影响项 | 相关文档 |
151
- |----------|--------|----------|
152
- | 新增 API | `createWidget()` | README.md, API.md |
153
- | 修改配置 | `timeout` 参数 | docs/config.md |
154
- | 移除功能 | `legacyMode` | README.md |
155
-
156
- ## 更新摘要
157
-
158
- ### README.md
159
- - [x] 更新功能列表,添加 `createWidget` 描述
160
- - [x] 移除 `legacyMode` 相关说明
161
-
162
- ### API.md
163
- - [x] 添加 `createWidget()` 接口文档
164
-
165
- ## 结论
166
-
167
- ✅ **SYNCED** - 文档已同步完成
168
- ```
169
-
170
- ### 全局模式输出
171
-
172
- ```markdown
173
- # Global Docs Sync Report
174
-
175
- ## 覆盖率统计
176
-
177
- | 类型 | 代码数量 | 文档数量 | 覆盖率 |
178
- |------|----------|----------|--------|
179
- | 公共函数 | 25 | 22 | 88% |
180
- | 配置项 | 10 | 10 | 100% |
181
- | CLI 命令 | 5 | 4 | 80% |
182
-
183
- ## 差异清单
184
-
185
- ### 缺失文档(代码有文档无)
186
- 1. `parseConfig()` - src/config.ts:42
187
- 2. `validateInput()` - src/utils.ts:15
188
-
189
- ### 过时文档(代码无文档有)
190
- 1. `oldFunction()` - 已在 v2.0 移除
191
-
192
- ### 不一致项
193
- 1. `timeout` 参数:代码默认值 30s,文档写 60s
194
-
195
- ## 建议操作
196
-
197
- 1. 为 `parseConfig()` 添加文档
198
- 2. 移除 `oldFunction()` 的文档
199
- 3. 修正 `timeout` 的默认值说明
200
-
201
- 是否执行以上修复?[Y/n]
202
- ```
203
-
204
- ---
205
-
206
- ## 与工作流的集成
207
-
208
- ### 在 Delivery Workflow 中的位置
209
-
210
- ```
211
- Design → Plan → Test → Implement → Review → [Docs Sync] → Archive
212
- ```
213
-
214
- ### 触发时机
215
-
216
- | 阶段 | 触发条件 | 模式 |
217
- |------|----------|------|
218
- | 实现完成后 | change 影响公共 API | 增量模式 |
219
- | 归档前 | 用户请求 | 增量模式 |
220
- | 独立运行 | 用户显式请求 | 全局模式 |
221
-
222
- ### 是否每个 change 都要执行?
223
-
224
- **不是**。只有满足以下条件的 change 才需要执行:
225
-
226
- - 新增/修改/删除公共 API
227
- - 变更用户可见行为
228
- - 修改配置项
229
- - 变更 CLI 命令
230
-
231
- **以下情况不需要执行**:
232
-
233
- - 纯重构(不影响公共接口)
234
- - Bug 修复(不改变行为)
235
- - 内部实现优化
236
- - 测试代码变更
237
-
238
- ---
239
-
240
- ## 如何确保不遗漏
241
-
242
- ### 1. 在 design.md 中标记
243
-
244
- 在 design.md 中添加 `[Docs-Required]` 标记:
245
-
246
- ```markdown
247
- ## 变更说明
248
-
249
- 本次变更添加了新的 `createWidget()` API。[Docs-Required]
250
- ```
251
-
252
- ### 2. 在 tasks.md 中包含文档任务
253
-
254
- ```markdown
255
- ## 任务列表
256
-
257
- - [ ] 实现 createWidget API
258
- - [ ] 添加单元测试
259
- - [ ] [Docs] 更新 API.md
260
- - [ ] [Docs] 更新 README.md
261
- ```
262
-
263
- ### 3. 在 review 阶段检查
264
-
265
- code-review 时检查是否有未完成的文档任务。
266
-
267
- ---
268
-
269
- ## 上下文感知
270
-
271
- 本 Skill 在执行前自动检测上下文,选择合适的运行模式。
272
-
273
- ### 检测流程
274
-
275
- 1. 检测是否在变更包上下文中
276
- 2. 检测是否有 `--global` 参数
277
- 3. 检测变更包是否影响公共 API
278
-
279
- ### 本 Skill 支持的模式
280
-
281
- | 模式 | 触发条件 | 行为 |
282
- |------|----------|------|
283
- | **增量模式** | 在变更包上下文中 | 只更新本次 change 相关的文档 |
284
- | **全局模式** | 带 --global 参数 | 扫描全部文档并生成差异报告 |
285
- | **检查模式** | 带 --check 参数 | 只检查不修改,输出报告 |
286
-
287
- ### 检测输出示例
288
-
289
- ```
290
- 检测结果:
291
- - 变更包上下文:存在 (CHG-2024-001)
292
- - 影响公共 API:是 (2 个新增, 1 个修改)
293
- - 运行模式:增量模式
294
- ```
295
-
296
- ---
297
-
298
- ## MCP 增强
299
-
300
- 本 Skill 可选使用 MCP 服务增强功能。
301
-
302
- ### 依赖的 MCP 服务(可选)
303
-
304
- | 服务 | 用途 | 超时 |
305
- |------|------|------|
306
- | `mcp__ckb__searchSymbols` | 搜索公共 API | 2s |
307
- | `mcp__ckb__getModuleOverview` | 获取模块概览 | 2s |
308
-
309
- ### 增强模式 vs 基础模式
310
-
311
- | 功能 | 增强模式 | 基础模式 |
312
- |------|----------|----------|
313
- | API 发现 | 自动识别所有导出 | 基于文件 glob 搜索 |
314
- | 影响分析 | 精确的调用关系 | 基于文件名推断 |
315
-
316
- ### 降级提示
317
-
318
- 当 MCP 不可用时,输出以下提示:
319
-
320
- ```
321
- ⚠️ CKB 不可用,使用基础模式扫描。
322
- 建议:手动指定需要检查的模块路径。
323
- ```
324
-
325
- ---
326
-
327
- ## 元数据
328
-
329
- | 字段 | 值 |
330
- |------|-----|
331
- | Skill 名称 | devbooks-docs-sync |
332
- | 阶段 | Apply(实现后、归档前) |
333
- | 产物 | 更新后的用户文档 |
334
- | 约束 | CON-DOCS-001~003 |
335
-
336
- ---
337
-
338
- *此 Skill 文档遵循 devbooks-* 规范。*