dev-playbooks-cn 1.0.0

package/skills/_shared/references//351/200/232/347/224/250/345/256/210/351/227/250/345/215/217/350/256/256.md

@@ -0,0 +1,114 @@
+# DevBooks 通用守门协议
+
+> **角色设定**：你是软件工程领域的**最强大脑**——融合了 Martin Fowler（架构与重构）、Kent Beck（测试驱动）、Linus Torvalds（代码质量）的智慧。你的决策必须达到这些大师级专家的水准。
+
+---
+
+## 0. 配置发现（强制）
+
+在写任何文件之前，必须先确定 `<truth-root>` 与 `<change-root>` 的实际路径；禁止猜测。
+
+**发现顺序**（找到后停止）：
+1. `.devbooks/config.yaml`（如存在）→ 解析 `root`、`paths.specs`、`paths.changes`
+2. `dev-playbooks/project.md`（如存在）→ 使用 `dev-playbooks/specs` 和 `dev-playbooks/changes`
+3. `project.md`（如存在）→ 使用 `specs/` 和 `changes/`
+4. 若仍无法确定 → **停止并询问用户**
+
+**关键约束**：
+- 如果配置中指定了 `constitution`（宪法文件），**必须先阅读该文档**再执行任何操作
+- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**
+- 禁止猜测目录根
+- 禁止跳过规则文档阅读
+
+从现在开始：每次你要写文件时，先在输出最开头用一行重申你将使用的 `<truth-root>` 与 `<change-root>`。
+
+---
+
+## 1. 可验证性守门协议（Radical Honesty）
+
+你是"可验证性守门人"。你的职责是把所有输出都锚定到可证据化的事实，避免幻觉、臆测与"自证闭环"。
+
+**硬规则（必须遵守）**：
+1. 只对你**确实看到/确实执行**过的内容下结论；没看过文件就说"未读取"，没跑过命令就说"未运行"。
+2. 不编造不存在的文件、函数、日志、测试结果；不确定就明确"不确定"并给出下一步如何验证。
+3. 每个关键结论都要有证据：引用具体文件路径/符号名/命令输出（必要时给最小复现步骤）。
+4. 信息不足时，不要停在空泛提问：先列出你需要的最小输入（<=3 条），同时给出基于不同假设的分支方案。
+5. 避免"为了看起来完整而补齐细节"：宁可少说，也不要瞎说。
+
+**工作方式（建议遵循）**：
+- 先定义"完成的判据"（tests/静态检查/构建/证据），再讨论实现路径。
+- 对跨文件/跨模块/跨契约的改动，先做影响分析与一致性检查，再写代码。
+- 当你发现设计/规格/计划/测试之间不一致：停止推进，先指出冲突点与建议的真理源优先级。
+- 若文档元信息中的 `last_verified` 超过 `freshness_check`，先补"文档验真任务"并完成验证/更新，再进入实现。
+- 若存在 `<truth-root>/_meta/glossary.md`，必须遵守统一术语；禁止自创同义词。
+
+---
+
+## 2. 结构质量守门协议
+
+1. **识别**：若需求/规范以"代理指标"驱动（行数/文件数/目录切分/命名格式等硬性限制），先评估对系统质量的影响（高内聚低耦合、可测试性、可演进性）。
+
+2. **诊断信号**：若出现任一信号，必须提出异议与风险：
+   - 同一业务流程被切散到多个文件/模块，理解成本显著上升
+   - 边界被扭曲以满足指标（层次/依赖方向被迫改变）
+   - 为达标引入大量粘合代码/重复代码/不稳定的跨文件调用
+   - 测试边界被破坏或显著变难
+
+3. **替代**：优先建议以复杂度、耦合度、依赖方向、变更频率、测试质量作为质量闸门，而非代理指标。
+
+4. **决策**：在获得明确授权前，不执行"纯为达标的改动"；将其记录为需决策问题并建议写入 proposal/design。
+
+---
+
+## 3. 完整性守门协议（零容忍）
+
+**核心原则：你写的每一个字都必须是完整的、可验证的、自包含的。**
+
+**禁止行为（触发任一即为违规）**：
+
+1. **禁止省略号偷懒**：禁止写 `...`、`（略）`、`（以下省略）`、`等 N 个` 来代替完整内容。
+   - 违规示例：`- 文件1.ts\n- 文件2.ts\n- ... 等 15 个文件`
+   - 正确做法：列出全部 15 个文件，一个不漏。
+
+2. **禁止引用不存在的文件**：禁止写 `详见 xxx.md`、`完整清单见 yyy.md` 除非该文件已经存在或你在同一次输出中创建它。
+   - 违规示例：`（完整清单见 evidence/high-complexity.md）` ← 但该文件不存在
+   - 正确做法：要么内联写完整清单，要么先创建 `evidence/high-complexity.md` 再引用。
+
+3. **禁止占位符承诺**：禁止写 `[待补充]`、`[TODO: 添加详情]`、`后续会补充` 等占位符。
+   - 违规示例：`## 影响范围\n[待分析后补充]`
+   - 正确做法：信息不足就明确说 "需要以下输入才能完成：..."，不要留空洞的占位符。
+
+4. **禁止虚假数量声明**：禁止声称 `共 N 个` 但实际列出数量 ≠ N。
+   - 违规示例：`共涉及 8 个模块：` 然后只列出 3 个
+   - 正确做法：先数清楚，再声明数量，且必须完整列出。
+
+**执行规则**：
+- 每次生成清单/列表/文件集合时，先在心中数一遍数量，确保声明数量 = 实际列出数量。
+- 每次引用外部文件时，先确认该文件存在或在同一输出中创建。
+- 若内容确实太长（>100 项），可以分批输出，但第一批必须明确说 "第 1/N 批，共 X 项"，且后续必须主动输出剩余批次。
+- 若用户中断分批输出，下次继续时必须从断点继续，不得跳过。
+
+**自检清单（每次输出前默念）**：
+- [ ] 我写的每个数字（"N 个文件"）都数过了吗？
+- [ ] 我引用的每个文件路径都存在或在本次创建了吗？
+- [ ] 我的列表是完整的，没有用省略号代替吗？
+- [ ] 如果内容分批，我说明了总批次和当前进度吗？
+
+**违反完整性守门协议 = 输出无效，必须重做。**
+
+---
+
+## 4. 输出格式约束
+
+当你在产出文档/方案时：
+- 用 Markdown，结构清晰，避免长段散文。
+- 对每个可执行建议，给出对应的验证方法（命令/测试/检查清单）。
+
+**可读性检查（可选但高 ROI）**：
+- 在提交代码前做一轮"只看可读性/惯用法"的检查，不讨论业务逻辑。
+- 对照仓库中 3 个同类文件的写法（命名/结构/错误处理/注释风格），避免引入"方言"。
+- Linter 只是底线，风格不一致仍需修正。
+
+---
+
+从现在开始，你在后续所有输出中默认启用上述规则。

package/skills/_template/config-discovery-template.md

@@ -0,0 +1,126 @@
+# Skills 配置发现标准模板
+
+> 此模板定义了所有 `devbooks-*` Skills 在执行前必须遵循的配置发现流程。
+
+---
+
+## 前置：配置发现（协议无关）
+
+执行任何操作前，**必须**按以下顺序查找配置（找到后停止）：
+
+### 查找顺序
+
+1. `.devbooks/config.yaml`（如存在）→ 解析其中的映射
+2. `dev-playbooks/project.md`（如存在）→ 使用 DevBooks 默认映射
+3. `project.md`（如存在）→ 使用 template 默认映射
+4. 若仍无法确定 → **停止并询问用户**
+
+### 默认映射表
+
+| 协议 | truth_root | change_root | agents_doc |
+|------|------------|-------------|------------|
+| devbooks | `dev-playbooks/specs/` | `dev-playbooks/changes/` | `dev-playbooks/project.md` |
+| template | `specs/` | `changes/` | `project.md` |
+
+### 从配置中获取
+
+- `truth_root`：真理目录根（当前系统规格的最终版本）
+- `change_root`：变更目录根（每次变更的所有产物）
+- `agents_doc`：规则文档位置（AI 必须先阅读）
+- `project_profile`：项目画像位置（可选，用于快速上下文）
+
+### 关键约束
+
+1. **如果 `agents_doc` 存在，必须先阅读该文档再执行任何操作**
+2. 禁止猜测目录根
+3. 禁止跳过规则文档阅读
+4. 禁止在未确定配置的情况下执行
+
+### 推荐方式
+
+运行配置发现脚本：
+
+```bash
+DEVBOOKS_SCRIPTS="${CODEX_HOME:-$HOME/.codex}/skills/devbooks-delivery-workflow/scripts"
+# 或
+DEVBOOKS_SCRIPTS="${CLAUDE_CODE_HOME:-$HOME/.claude-code}/skills/devbooks-delivery-workflow/scripts"
+
+source <("$DEVBOOKS_SCRIPTS/../config-discovery.sh")
+# 现在可以使用 $truth_root, $change_root, $agents_doc 等变量
+```
+
+---
+
+## 如何在 SKILL.md 中使用此模板
+
+在每个 SKILL.md 文件的开头，添加以下内容：
+
+```markdown
+## 前置：配置发现（协议无关）
+
+- `<truth-root>`：当前真理目录根
+- `<change-root>`：变更包目录根
+
+执行前**必须**按以下顺序查找配置（找到后停止）：
+1. `.devbooks/config.yaml`（如存在）
+2. `dev-playbooks/project.md`（如存在）
+3. `project.md`（如存在）
+4. 若仍无法确定 → **停止并询问用户**
+
+**关键约束**：如果配置中指定了 `agents_doc`（规则文档），必须先阅读该文档再执行任何操作。
+```
+
+---
+
+## 示例：更新后的 SKILL.md
+
+### 更新前（硬编码）
+
+```markdown
+## 前置：目录根（协议无关）
+
+- `<truth-root>`：当前真理目录根（默认建议 `specs/`；DevBooks 项目为 `dev-playbooks/specs/`）
+- `<change-root>`：变更包目录根（默认建议 `changes/`；DevBooks 项目为 `dev-playbooks/changes/`）
+
+执行前必须先尝试读取 `dev-playbooks/project.md`（如存在）以确定 `<truth-root>/<change-root>`；禁止猜测目录根。若仍无法确定，再询问用户确认。
+```
+
+### 更新后（协议发现）
+
+```markdown
+## 前置：配置发现（协议无关）
+
+- `<truth-root>`：当前真理目录根
+- `<change-root>`：变更包目录根
+
+执行前**必须**按以下顺序查找配置（找到后停止）：
+1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
+2. `dev-playbooks/project.md`（如存在）→ DevBooks 协议，使用默认映射
+3. `project.md`（如存在）→ template 协议，使用默认映射
+4. 若仍无法确定 → **停止并询问用户**
+
+**关键约束**：
+- 如果配置中指定了 `agents_doc`，必须先阅读该文档再执行任何操作
+- 禁止猜测目录根
+- 禁止跳过规则文档阅读
+```
+
+---
+
+## 批量更新脚本（参考）
+
+```bash
+#!/bin/bash
+# 批量更新所有 Skills 的 SKILL.md
+
+OLD_PATTERN='执行前必须先尝试读取 `dev-playbooks/project.md`'
+NEW_TEXT='执行前**必须**按以下顺序查找配置'
+
+for skill_dir in skills/devbooks-*/; do
+    skill_md="$skill_dir/SKILL.md"
+    if [ -f "$skill_md" ] && grep -q "$OLD_PATTERN" "$skill_md"; then
+        echo "Updating: $skill_md"
+        # 实际更新需要更复杂的 sed 命令
+    fi
+done
+```

package/skills/devbooks-brownfield-bootstrap/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: devbooks-brownfield-bootstrap
+description: devbooks-brownfield-bootstrap：存量项目初始化：在当前真理目录为空时生成项目画像、术语表、基线规格与最小验证锚点，避免"边补 specs 边改行为"。用户说"存量初始化/基线 specs/项目画像/建立 glossary/把老项目接入上下文协议"等时使用。
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - mcp__ckb__getStatus
+  - mcp__ckb__getArchitecture
+  - mcp__ckb__getHotspots
+  - mcp__ckb__listKeyConcepts
+  - mcp__ckb__getModuleOverview
+---
+
+# DevBooks：存量项目初始化（Brownfield Bootstrap）
+
+## 前置：配置发现（协议无关）
+
+- `<truth-root>`：当前真理目录根
+- `<change-root>`：变更包目录根
+
+执行前**必须**按以下顺序查找配置（找到后停止）：
+1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
+2. `dev-playbooks/project.md`（如存在）→ DevBooks 2.0 协议，使用默认映射
+4. `project.md`（如存在）→ template 协议，使用默认映射
+5. 若仍无法确定 → **停止并询问用户**
+
+**关键约束**：
+- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
+- 禁止猜测目录根
+- 禁止跳过规则文档阅读
+
+## COD 模型生成（Code Overview & Dependencies）
+
+在初始化时自动生成项目的"代码地图"（需要 CKB MCP Server 可用，否则跳过）：
+
+### 自动生成产物
+
+| 产物 | 路径 | 数据来源 |
+|------|------|----------|
+| 模块依赖图 | `<truth-root>/architecture/module-graph.md` | `mcp__ckb__getArchitecture` |
+| 技术债热点 | `<truth-root>/architecture/hotspots.md` | `mcp__ckb__getHotspots` |
+| 领域概念 | `<truth-root>/_meta/key-concepts.md` | `mcp__ckb__listKeyConcepts` |
+| 项目画像 | `<truth-root>/_meta/project-profile.md` | 综合分析 |
+
+### 热点计算公式
+
+```
+热点分数 = 变更频率 × 圈复杂度
+```
+
+- **高热点**（分数 > 阈值）：频繁修改 + 高复杂度 = Bug 密集区
+- **休眠债务**（高复杂度 + 低频率）：暂时安全但需关注
+- **活跃健康**（高频率 + 低复杂度）：正常维护区域
+
+### 边界识别
+
+自动区分：
+- **用户代码**：`src/`、`lib/`、`app/` 等（可修改）
+- **库代码**：`node_modules/`、`vendor/`、`.venv/` 等（不可变接口）
+- **生成代码**：`dist/`、`build/`、`*.generated.*` 等（禁止手动修改）
+
+### 执行流程
+
+1) **检查图索引**：调用 `mcp__ckb__getStatus`
+   - 若 SCIP 可用 → 使用图基分析
+   - 若不可用 → 提示生成索引或使用 Git 历史分析
+
+2) **生成 COD 产物**：
+   ```bash
+   # 获取模块架构
+   mcp__ckb__getArchitecture(depth=2, includeExternalDeps=false)
+
+   # 获取热点（近 30 天）
+   mcp__ckb__getHotspots(limit=20)
+
+   # 获取领域概念
+   mcp__ckb__listKeyConcepts(limit=12)
+   ```
+
+3) **生成项目画像**：整合以上数据 + 传统分析
+
+## 参考骨架与模板
+
+- 工作流：`references/存量项目初始化.md`
+- 代码导航策略：`references/代码导航策略.md`
+- **项目画像模板（三层架构）**：`templates/project-profile-template.md`
+- 一次性提示词：`references/存量项目初始化提示词.md`
+- 模板（按需）：`references/术语表模板.md`
+
+---
+
+## 上下文感知
+
+本 Skill 在执行前自动检测上下文，选择合适的初始化范围。
+
+检测规则参考：`skills/_shared/context-detection-template.md`
+
+### 检测流程
+
+1. 检测 `<truth-root>/` 是否为空或基本为空
+2. 检测 CKB 索引是否可用
+3. 检测项目规模和语言栈
+
+### 本 Skill 支持的模式
+
+| 模式 | 触发条件 | 行为 |
+|------|----------|------|
+| **完整初始化** | truth-root 为空 | 生成所有基础产物 |
+| **增量初始化** | truth-root 部分存在 | 只补充缺失产物 |
+| **增强模式** | CKB 索引可用 | 使用图分析生成更精确的画像 |
+| **基础模式** | CKB 索引不可用 | 使用传统分析方法 |
+
+### 检测输出示例
+
+```
+检测结果：
+- truth-root：为空
+- CKB 索引：可用
+- 项目规模：中型（~50K LOC）
+- 运行模式：完整初始化 + 增强模式
+```
+
+---
+
+## MCP 增强
+
+本 Skill 支持 MCP 运行时增强，自动检测并启用高级功能。
+
+MCP 增强规则参考：`skills/_shared/mcp-enhancement-template.md`
+
+### 依赖的 MCP 服务
+
+| 服务 | 用途 | 超时 |
+|------|------|------|
+| `mcp__ckb__getStatus` | 检测 CKB 索引可用性 | 2s |
+| `mcp__ckb__getArchitecture` | 获取模块依赖图 | 2s |
+| `mcp__ckb__getHotspots` | 获取技术债热点 | 2s |
+| `mcp__ckb__listKeyConcepts` | 获取领域概念 | 2s |
+| `mcp__ckb__getModuleOverview` | 获取模块概览 | 2s |
+
+### 检测流程
+
+1. 调用 `mcp__ckb__getStatus`（2s 超时）
+2. 若 CKB 可用 → 使用图基分析生成 COD 产物
+3. 若超时或失败 → 降级到传统分析（Git 历史 + 文件统计）
+
+### 增强模式 vs 基础模式
+
+| 功能 | 增强模式 | 基础模式 |
+|------|----------|----------|
+| 模块依赖图 | CKB getArchitecture | 目录结构推断 |
+| 技术债热点 | CKB getHotspots | Git log 统计 |
+| 领域概念 | CKB listKeyConcepts | 命名分析 |
+| 边界识别 | 精确模块边界 | 目录约定 |
+
+### 降级提示
+
+当 MCP 不可用时，输出以下提示：
+
+```
+⚠️ CKB 不可用，使用传统分析方法生成项目画像。
+如需更精确的架构分析，请运行 /devbooks:index 生成索引。
+```

package/skills/devbooks-brownfield-bootstrap/references//344/273/243/347/240/201/345/257/274/350/210/252/347/255/226/347/225/245.md

@@ -0,0 +1,203 @@
+# 代码导航策略（四步法）
+
+借鉴 VS Code 的 `copilot-instructions.md`，本文档定义了在存量项目中快速定位代码的标准流程。
+
+---
+
+## 核心原则
+
+> **先理解，后修改**：在修改任何代码之前，必须先理解现有代码的结构和意图。
+
+---
+
+## 四步定位法
+
+### 第一步：语义搜索（Semantic Search）
+
+**目的**：基于意图快速缩小范围
+
+**方法**：
+```bash
+# 使用模糊搜索工具
+rg -i "user.*auth" --type ts
+rg -i "login|signin|authenticate" --type ts
+
+# 或使用 IDE 的语义搜索
+# VS Code: Cmd+Shift+F → 输入关键词
+```
+
+**技巧**：
+- 使用业务术语而非技术术语
+- 尝试同义词（login/signin/authenticate）
+- 搜索注释和文档字符串
+
+### 第二步：精确搜索（Exact Grep）
+
+**目的**：找到具体的函数/类/变量定义
+
+**方法**：
+```bash
+# 搜索函数定义
+rg "function\s+createUser" --type ts
+rg "const\s+createUser\s*=" --type ts
+
+# 搜索类定义
+rg "class\s+UserService" --type ts
+
+# 搜索接口定义
+rg "interface\s+User\b" --type ts
+
+# 搜索导出
+rg "export\s+(default\s+)?(function|class|const|interface)\s+\w*User" --type ts
+```
+
+**技巧**：
+- 使用 `\b` 确保单词边界
+- 搜索导出以找到公共 API
+- 结合文件路径过滤：`rg "pattern" src/user/`
+
+### 第三步：追踪导入（Trace Imports）
+
+**目的**：理解依赖关系和调用链
+
+**方法**：
+```bash
+# 找到谁引用了这个模块
+rg "from ['\"].*userService['\"]" --type ts
+rg "import.*UserService" --type ts
+
+# 找到这个模块引用了谁
+rg "^import" src/services/userService.ts
+
+# 使用 IDE 的"查找引用"功能
+# VS Code: 右键 → Find All References (Shift+F12)
+```
+
+**技巧**：
+- 从入口点开始追踪（main.ts, index.ts）
+- 注意相对导入 vs 绝对导入
+- 检查 re-export（index.ts 中的 `export * from`）
+
+### 第四步：查看测试（Review Tests）
+
+**目的**：理解预期行为和边界条件
+
+**方法**：
+```bash
+# 找到相关测试文件
+rg -l "UserService" tests/ src/**/test/
+
+# 查看测试用例描述
+rg "describe\(|it\(|test\(" tests/user.service.test.ts
+
+# 查看 mock 和 fixture
+rg "mock|stub|fixture" tests/user.service.test.ts
+```
+
+**技巧**：
+- 测试是最好的文档
+- 查看 `beforeEach` 了解初始化
+- 查看 `expect` 了解预期行为
+- 边界条件测试揭示隐藏约束
+
+---
+
+## 定位策略选择
+
+| 场景 | 推荐策略 | 原因 |
+|------|----------|------|
+| 不知道功能在哪 | 语义搜索 → 精确搜索 | 从宽到窄 |
+| 知道函数名 | 精确搜索 → 追踪导入 | 直接定位 |
+| 理解调用关系 | 追踪导入 → 查看测试 | 上下文理解 |
+| 理解预期行为 | 查看测试 | 测试即文档 |
+| 修改前验证影响 | 追踪导入 | 影响分析 |
+
+---
+
+## 项目结构识别
+
+### 常见目录结构模式
+
+**分层架构**：
+```
+src/
+├── controllers/   # 入口层
+├── services/      # 业务逻辑层
+├── repositories/  # 数据访问层
+├── models/        # 数据模型
+└── utils/         # 工具函数
+```
+
+**特性切片架构**：
+```
+src/
+├── user/
+│   ├── user.controller.ts
+│   ├── user.service.ts
+│   └── user.repository.ts
+├── order/
+│   ├── order.controller.ts
+│   └── ...
+```
+
+**VS Code 架构**：
+```
+src/vs/
+├── base/          # 基础工具
+├── platform/      # 平台服务
+├── editor/        # 编辑器
+└── workbench/     # 工作台
+    ├── browser/   # UI
+    ├── services/  # 服务
+    └── contrib/   # 贡献模块
+```
+
+### 快速识别入口点
+
+```bash
+# 查找 main 文件
+rg -l "main|bootstrap|app" --type ts -g "*.ts" | head -10
+
+# 查找路由定义
+rg "app\.(get|post|put|delete)|router\." --type ts
+
+# 查找服务注册
+rg "register|provide|bind" --type ts | head -20
+```
+
+---
+
+## 工具推荐
+
+### 命令行工具
+
+| 工具 | 用途 | 安装 |
+|------|------|------|
+| `rg` (ripgrep) | 快速文本搜索 | `brew install ripgrep` |
+| `fd` | 快速文件查找 | `brew install fd` |
+| `tree` | 目录结构可视化 | `brew install tree` |
+| `bat` | 语法高亮查看 | `brew install bat` |
+
+### IDE 功能
+
+| 功能 | VS Code 快捷键 | 用途 |
+|------|----------------|------|
+| 全局搜索 | Cmd+Shift+F | 语义搜索 |
+| 转到定义 | F12 | 精确定位 |
+| 查找引用 | Shift+F12 | 追踪导入 |
+| 符号搜索 | Cmd+T | 快速跳转 |
+| 文件搜索 | Cmd+P | 快速打开 |
+
+---
+
+## 检查清单
+
+在开始修改代码前，确认已完成：
+
+- [ ] 使用语义搜索找到相关区域
+- [ ] 使用精确搜索定位具体定义
+- [ ] 追踪导入理解依赖关系
+- [ ] 查看测试理解预期行为
+- [ ] 识别项目结构模式
+- [ ] 确认入口点和调用链
+- [ ] 评估修改影响范围