dev-playbooks-cn 1.0.6 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks-cn",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "AI-driven spec-based development workflow",
   "keywords": [
     "devbooks",

package/templates/dev-playbooks/README.md

@@ -130,7 +130,7 @@ DevBooks 使用两个目录根：
 | `<truth-root>` | 当前规格（只读真理） | `dev-playbooks/specs/` |
 | `<change-root>` | 变更包（工作区） | `dev-playbooks/changes/` |
 
-详见 `../docs/DevBooks集成模板（协议无关）.md` 或使用 `../docs/DevBooks安装提示词.md` 让 AI 自动配置。
+详见 `docs/DevBooks集成模板（协议无关）.md` 或使用 `docs/DevBooks安装提示词.md` 让 AI 自动配置。
 
 ---
 
@@ -414,7 +414,7 @@ DevBooks Skills 支持 MCP（Model Context Protocol）优雅降级：在没有 M
 - 超时/失败 → 静默降级到基础模式，不阻塞执行
 - 无需手动选择"基础/增强"模式
 
-如需启用增强能力：按 `../docs/推荐MCP.md` 配置 CKB，并运行 `/devbooks:index` 生成 `index.scip`。
+如需启用增强能力：按 `docs/推荐MCP.md` 配置 CKB，并运行 `/devbooks:index` 生成 `index.scip`。
 
 </details>
 
@@ -511,26 +511,33 @@ dev-playbooks-cn migrate --from speckit --keep-old
 
 ---
 
-## 仓库结构
+## 目录结构
 
 ```
-skills/                    # devbooks-* Skills 源码（部分 Skill 自带 scripts/）
-templates/                 # 项目初始化模板（`dev-playbooks-cn init` 使用）
-templates/dev-playbooks/   # DevBooks 协议目录模板（初始化后写入项目为 `dev-playbooks/`）
-scripts/                   # 安装与辅助脚本
-docs/                      # 支持文档
-bin/                       # CLI 入口
+dev-playbooks/
+├── README.md              # 本文档
+├── constitution.md        # 项目宪法（GIP 原则）
+├── project.md             # 项目上下文（技术栈/约定）
+├── specs/                 # 当前规格（只读真理）
+│   ├── _meta/             # 元数据（术语表、项目画像）
+│   └── architecture/      # 架构规格（fitness-rules）
+├── changes/               # 变更包（工作区）
+├── scripts/               # 辅助脚本
+└── docs/                  # 文档
+    ├── Slash 命令使用指南.md
+    ├── 推荐MCP.md
+    ├── DevBooks集成模板（协议无关）.md
+    └── DevBooks安装提示词.md
 ```
 
 ---
 
 ## 文档
 
-- [Slash 命令使用指南](../docs/Slash 命令使用指南.md)
-- [Skills 使用说明](../skills/Skills使用说明.md)
-- [MCP 配置建议](../docs/推荐MCP.md)
-- [集成模板（协议无关）](../docs/DevBooks集成模板（协议无关）.md)
-- [安装提示词](../docs/DevBooks安装提示词.md)
+- [Slash 命令使用指南](docs/Slash%20命令使用指南.md)
+- [MCP 配置建议](docs/推荐MCP.md)
+- [集成模板（协议无关）](docs/DevBooks集成模板（协议无关）.md)
+- [安装提示词](docs/DevBooks安装提示词.md)
 
 ---
 

package/templates/dev-playbooks/docs/DevBooks/345/256/211/350/243/205/346/217/220/347/244/272/350/257/215.md

@@ -0,0 +1,42 @@
+```text
+你是“DevBooks 上下文协议适配器安装员（DevBooks Context Protocol Adapter Installer）”。你的目标是在目标项目中，把 DevBooks 的协议无关约定（<truth-root>/<change-root> + 角色隔离 + DoD + Skills 索引）集成到该项目的上下文协议里。
+
+前置条件（先检查，缺失则停止并说明原因）：
+- 系统依赖已安装（必需：jq、ripgrep；推荐：scc、radon）
+  检查命令：command -v jq rg scc radon
+  若缺失，运行：<devbooks-root>/scripts/install-dependencies.sh
+- 你能定位该项目的“标牌文件（signpost file）”（由上下文协议决定，常见：CLAUDE.md / AGENTS.md / PROJECT.md / <protocol>/project.md）。
+
+硬约束（必须遵守）：
+1) 本次安装只允许改“上下文/文档标牌”，不得修改业务代码、tests、也不得引入新依赖。
+2) 若目标项目已有“上下文协议托管区块（managed block）”，自定义内容必须放在托管区块之外，避免被后续自动更新覆盖。
+3) 安装必须明确写出两个目录根：
+   - <truth-root>：当前真理目录根
+   - <change-root>：变更包目录根
+
+任务（按顺序执行）：
+0) 检查系统依赖：
+   - 运行：command -v jq rg scc radon
+   - 若缺失必需依赖（jq、rg），提示用户先运行：./scripts/install-dependencies.sh
+   - 若缺失推荐依赖（scc、radon），说明这是可选项，用于启用“复杂度加权热点”等能力
+1) 识别上下文协议类型（至少两条分支）：
+   - 若检测到 DevBooks（存在 dev-playbooks/project.md）：使用 DevBooks 默认值（<truth-root>=dev-playbooks/specs，<change-root>=dev-playbooks/changes）
+   - 否则：使用 `docs/DevBooks集成模板（协议无关）.md` 进行集成
+2) 为该项目确定目录根：
+   - 若项目已有 specs/changes 等目录约定：直接沿用作为 <truth-root>/<change-root>
+   - 若项目没有定义：推荐在仓库根目录使用 `specs/` 与 `changes/`
+3) 将模板内容合入标牌文件（以追加方式合并）：
+   - 写入：<truth-root>/<change-root>、变更包结构约定、角色隔离、DoD、devbooks-* Skills 索引
+4) 验证（必须输出检查结果）：
+   - 产物落点是否一致（proposal/design/tasks/verification/specs/evidence）
+   - 是否包含 Test Owner/Coder 隔离与“Coder 禁止修改 tests”
+   - 是否包含 DoD（MECE）
+   - 是否包含 devbooks-* Skills 索引
+
+完成后输出：
+- 系统依赖检查结果（哪些已安装、哪些缺失）
+- 你修改了哪些文件（列表）
+- 该项目最终的 <truth-root>/<change-root> 值
+- 下一步最短路径示例（用自然语言点 2-3 个关键 skills）
+```
+

package/templates/dev-playbooks/docs/DevBooks/351/233/206/346/210/220/346/250/241/346/235/277/357/274/210/345/215/217/350/256/256/346/227/240/345/205/263/357/274/211.md

@@ -0,0 +1,120 @@
+# DevBooks 集成模板（协议无关）
+
+> 目标：把 DevBooks 的**角色隔离**、**DoD（完成定义）**、**目录约定**、以及 `devbooks-*` Skills 索引，写入目标项目的“项目标牌文件（signpost file）”里（无需依赖 DevBooks 本体）。
+
+---
+
+## DevBooks 上下文（协议无关约定）
+
+将以下信息添加到你的“项目标牌文件”（由项目上下文协议决定，常见候选：`CLAUDE.md`、`AGENTS.md`、`PROJECT.md` 等）：
+
+- 目录根（Directory Roots）：
+  - `<truth-root>`：当前真理目录根（默认建议：`specs/`）
+  - `<change-root>`：变更包目录根（默认建议：`changes/`）
+
+- 单次变更包文件落点（目录约定）：
+  - `(<change-root>/<change-id>/proposal.md)`：提案
+  - `(<change-root>/<change-id>/design.md)`：设计文档
+  - `(<change-root>/<change-id>/tasks.md)`：编码计划
+  - `(<change-root>/<change-id>/verification.md)`：验证与追溯（含追溯矩阵、MANUAL-* 清单、证据要求）
+  - `(<change-root>/<change-id>/specs/**)`：本次变更的规格增量
+  - `(<change-root>/<change-id>/evidence/**)`：证据（按需）
+
+- 当前真理目录建议结构（非强制，但建议保持一致）：
+  - `(<truth-root>/_meta/project-profile.md)`：项目画像/约束/闸门/格式约定
+  - `(<truth-root>/_meta/glossary.md)`：统一语言术语表
+  - `(<truth-root>/architecture/c4.md)`：C4 架构地图（当前真理）
+  - `(<truth-root>/engineering/pitfalls.md)`：高 ROI 坑库（可选）
+
+---
+
+## 角色隔离（强制）
+
+- Test Owner 与 Coder 必须在**独立对话/独立实例**中工作；允许并行，但不允许共享上下文造成“自证式测试”。
+- Coder **禁止修改** `tests/**`；如需调整测试，必须交回 Test Owner 决策与修改。
+
+---
+
+## DoD（完成定义，MECE）
+
+每次变更至少要声明覆盖哪些闸门；未覆盖项必须写明原因与补救计划（建议写入 `(<change-root>/<change-id>/verification.md)`）：
+
+- 行为：unit/integration/e2e（按项目类型选择最小集合）
+- 契约：OpenAPI/Proto/Schema/事件信封 + contract tests
+- 结构：分层/依赖方向/无环（fitness tests）
+- 静态/安全：lint/typecheck/build + SAST/secret scan
+- 证据（按需）：截图/录屏/报告（UI、性能、安全排查）
+
+---
+
+## DevBooks Skills 索引（协议无关）
+
+建议把下面的索引放入项目标牌文件，用来指导“什么时候用哪个 Skill”。
+
+### 按角色
+
+- Router：`devbooks-router` → 不确定下一步/阶段时做路由与产物落点建议（支持 Prototype 模式）
+- Proposal Author：`devbooks-proposal-author` → `(<change-root>/<change-id>/proposal.md)`
+- Proposal Challenger：`devbooks-proposal-challenger` → 质疑报告（可选写入变更包）
+- Proposal Judge：`devbooks-proposal-judge` → 裁决回写到 `proposal.md`
+- Impact Analyst：`devbooks-impact-analysis` → 影响分析（建议写回 proposal 的 Impact 部分）
+- Design Owner：`devbooks-design-doc` → `(<change-root>/<change-id>/design.md)`
+- Spec & Contract Owner：`devbooks-spec-contract` → `(<change-root>/<change-id>/specs/**)` + 契约计划
+- Planner：`devbooks-implementation-plan` → `(<change-root>/<change-id>/tasks.md)`
+- Test Owner：`devbooks-test-owner` → `(<change-root>/<change-id>/verification.md)` + `tests/**`
+- Coder：`devbooks-coder` → 按 `tasks.md` 实现（禁止改 tests）
+- Reviewer：`devbooks-code-review` → 评审意见（不改代码）
+- Spec Gardener：`devbooks-spec-gardener` → 归档前修剪 `(<truth-root>/**)`
+- C4 Map Maintainer：`devbooks-c4-map` → `(<truth-root>/architecture/c4.md)`
+- Design Backport：`devbooks-design-backport` → 回写设计缺口/冲突
+
+### 按工作流
+
+- Proposal Debate：`devbooks-proposal-debate-workflow` → Author/Challenger/Judge 三角对辩
+- Delivery Workflow：`devbooks-delivery-workflow` → 变更闭环 + 确定性脚本（scaffold/check/evidence）
+- Brownfield Bootstrap：`devbooks-brownfield-bootstrap` → 存量项目初始化（`<truth-root>` 为空时）
+
+### 按度量
+
+- Entropy Monitor：`devbooks-entropy-monitor` → 系统熵度量（结构/变更/测试/依赖熵）+ 重构预警
+
+### 按索引
+
+- Index Bootstrap：`devbooks-index-bootstrap` → 生成 SCIP 索引，启用图基分析
+- Federation：`devbooks-federation` → 跨仓库联邦分析与契约同步
+
+---
+
+## CI/CD 集成（可选）
+
+把 `templates/ci/` 里的模板复制到目标项目的 `.github/workflows/`：
+
+- `devbooks-guardrail.yml`：在 PR 上做复杂度/热点/分层违规/环依赖检查
+- `devbooks-cod-update.yml`：push 后自动更新 COD 模型（模块图/热点/概念）
+
+---
+
+## 跨仓库联邦（可选）
+
+多仓库项目可配置 `.devbooks/federation.yaml` 定义上下游依赖：
+
+```bash
+cp skills/devbooks-federation/templates/federation.yaml .devbooks/federation.yaml
+```
+
+详见 `skills/devbooks-federation/SKILL.md`
+
+---
+
+## 自动 Skill 路由规则（无感集成）
+
+> 这些规则让 AI 可以根据用户意图自动选择 Skills，不需要用户显式点名。
+
+### 意图识别与自动路由
+
+| 用户意图模式 | 自动选择 Skills |
+|-------------|------------------|
+| “修 bug”、“定位问题”、“为什么报错” | `devbooks-impact-analysis` → `devbooks-coder` |
+| “重构”、“优化代码”、“消除重复” | `devbooks-code-review` → `devbooks-coder` |
+| “新功能”、“增加 XX”、“实现 XX” | `devbooks-router` → 输出闭环路线 |
+| “写测试”、“补测试” | `devbooks-test-owner` |