dev-playbooks-cn 1.1.0 → 1.2.2

package/bin/devbooks.js

@@ -305,6 +305,160 @@ function getCliVersion() {
   }
 }
 
+// ============================================================================
+// 自动更新 .gitignore 和 .npmignore
+// ============================================================================
+
+const IGNORE_MARKERS = {
+  start: '# DevBooks managed - DO NOT EDIT',
+  end: '# End DevBooks managed'
+};
+
+/**
+ * 获取需要添加到 .gitignore 的条目
+ * @param {string[]} toolIds - 选择的 AI 工具 ID
+ * @returns {string[]} - 需要忽略的条目
+ */
+function getGitIgnoreEntries(toolIds) {
+  const entries = [
+    '# DevBooks 本地配置（包含用户偏好，不应提交）',
+    '.devbooks/'
+  ];
+
+  // 根据选择的工具添加对应的 AI 工具目录
+  for (const toolId of toolIds) {
+    const tool = AI_TOOLS.find(t => t.id === toolId);
+    if (!tool) continue;
+
+    // 添加 slash 命令目录
+    if (tool.slashDir) {
+      const topDir = tool.slashDir.split('/')[0];
+      if (!entries.includes(topDir + '/')) {
+        entries.push(`${topDir}/`);
+      }
+    }
+
+    // 添加 rules 目录
+    if (tool.rulesDir) {
+      const topDir = tool.rulesDir.split('/')[0];
+      if (!entries.includes(topDir + '/')) {
+        entries.push(`${topDir}/`);
+      }
+    }
+
+    // 添加 agents 目录（如 .github/instructions 等）
+    if (tool.instructionsDir) {
+      const topDir = tool.instructionsDir.split('/')[0];
+      if (topDir !== '.github') { // .github 目录通常需要保留
+        if (!entries.includes(topDir + '/')) {
+          entries.push(`${topDir}/`);
+        }
+      }
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * 获取需要添加到 .npmignore 的条目
+ * @returns {string[]} - 需要忽略的条目
+ */
+function getNpmIgnoreEntries() {
+  return [
+    '# DevBooks 开发文档（运行时不需要）',
+    'dev-playbooks/',
+    '.devbooks/',
+    '',
+    '# AI 工具配置目录',
+    '.claude/',
+    '.cursor/',
+    '.windsurf/',
+    '.gemini/',
+    '.agent/',
+    '.opencode/',
+    '.continue/',
+    '.qoder/',
+    '.github/instructions/',
+    '.github/copilot-instructions.md',
+    '',
+    '# DevBooks 指令文件',
+    'CLAUDE.md',
+    'AGENTS.md',
+    'GEMINI.md'
+  ];
+}
+
+/**
+ * 更新 ignore 文件，保留用户自定义内容
+ * @param {string} filePath - ignore 文件路径
+ * @param {string[]} entries - 需要添加的条目
+ * @returns {object} - { updated: boolean, action: 'created' | 'updated' | 'unchanged' }
+ */
+function updateIgnoreFile(filePath, entries) {
+  const managedBlock = [
+    IGNORE_MARKERS.start,
+    ...entries,
+    IGNORE_MARKERS.end
+  ].join('\n');
+
+  if (!fs.existsSync(filePath)) {
+    // 文件不存在，创建新文件
+    fs.writeFileSync(filePath, managedBlock + '\n');
+    return { updated: true, action: 'created' };
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const startIdx = content.indexOf(IGNORE_MARKERS.start);
+  const endIdx = content.indexOf(IGNORE_MARKERS.end);
+
+  if (startIdx !== -1 && endIdx !== -1 && startIdx < endIdx) {
+    // 已有托管块，更新它
+    const before = content.slice(0, startIdx);
+    const after = content.slice(endIdx + IGNORE_MARKERS.end.length);
+    const newContent = before + managedBlock + after;
+
+    if (newContent !== content) {
+      fs.writeFileSync(filePath, newContent);
+      return { updated: true, action: 'updated' };
+    }
+    return { updated: false, action: 'unchanged' };
+  }
+
+  // 没有托管块，追加到文件末尾
+  const newContent = content.trimEnd() + '\n\n' + managedBlock + '\n';
+  fs.writeFileSync(filePath, newContent);
+  return { updated: true, action: 'updated' };
+}
+
+/**
+ * 设置项目的 ignore 文件
+ * @param {string[]} toolIds - 选择的 AI 工具 ID
+ * @param {string} projectDir - 项目目录
+ * @returns {object[]} - 结果数组
+ */
+function setupIgnoreFiles(toolIds, projectDir) {
+  const results = [];
+
+  // 更新 .gitignore
+  const gitIgnorePath = path.join(projectDir, '.gitignore');
+  const gitIgnoreEntries = getGitIgnoreEntries(toolIds);
+  const gitResult = updateIgnoreFile(gitIgnorePath, gitIgnoreEntries);
+  if (gitResult.updated) {
+    results.push({ file: '.gitignore', action: gitResult.action });
+  }
+
+  // 更新 .npmignore
+  const npmIgnorePath = path.join(projectDir, '.npmignore');
+  const npmIgnoreEntries = getNpmIgnoreEntries();
+  const npmResult = updateIgnoreFile(npmIgnorePath, npmIgnoreEntries);
+  if (npmResult.updated) {
+    results.push({ file: '.npmignore', action: npmResult.action });
+  }
+
+  return results;
+}
+
 function showVersion() {
   console.log(`${CLI_COMMAND} v${getCliVersion()}`);
 }
@@ -458,6 +612,52 @@ function installSkills(toolIds, update = false) {
   return results;
 }
 
+// ============================================================================
+// 安装 Claude Code 自定义子代理（解决内置子代理无法访问 Skills 的问题）
+// ============================================================================
+
+function installClaudeAgents(toolIds, projectDir, update = false) {
+  const results = [];
+
+  // 只有 Claude Code 需要安装自定义子代理
+  if (!toolIds.includes('claude')) return results;
+
+  const agentsSrcDir = path.join(__dirname, '..', 'templates', 'claude-agents');
+  const agentsDestDir = path.join(projectDir, '.claude', 'agents');
+
+  if (!fs.existsSync(agentsSrcDir)) return results;
+
+  const agentFiles = fs.readdirSync(agentsSrcDir)
+    .filter(name => name.endsWith('.md'));
+
+  if (agentFiles.length === 0) return results;
+
+  fs.mkdirSync(agentsDestDir, { recursive: true });
+
+  let installedCount = 0;
+  for (const agentFile of agentFiles) {
+    const srcPath = path.join(agentsSrcDir, agentFile);
+    const destPath = path.join(agentsDestDir, agentFile);
+
+    if (fs.existsSync(destPath) && !update) continue;
+
+    fs.copyFileSync(srcPath, destPath);
+    installedCount++;
+  }
+
+  if (installedCount > 0) {
+    results.push({
+      tool: 'Claude Code',
+      type: 'agents',
+      count: installedCount,
+      total: agentFiles.length,
+      path: agentsDestDir
+    });
+  }
+
+  return results;
+}
+
 // ============================================================================
 // 安装 Rules（Cursor, Windsurf, Gemini, Antigravity, OpenCode, Continue）
 // ============================================================================
@@ -853,6 +1053,14 @@ async function initCommand(projectDir, options) {
         console.log(chalk.gray(`  └ ${result.tool}: ${result.note}`));
       }
     }
+
+    // 安装 Claude Code 自定义子代理（解决内置子代理无法访问 Skills 的问题）
+    const agentsResults = installClaudeAgents(fullSupportTools, projectDir);
+    for (const result of agentsResults) {
+      if (result.count > 0) {
+        console.log(chalk.gray(`  └ ${result.tool}: ${result.count} 个自定义子代理 → ${result.path}`));
+      }
+    }
   }
 
   // 安装 Rules（Rules 类似系统的工具）
@@ -880,6 +1088,18 @@ async function initCommand(projectDir, options) {
     console.log(chalk.gray(`  └ ${result.tool}: ${path.relative(projectDir, result.path)}`));
   }
 
+  // 设置 ignore 文件
+  const ignoreSpinner = ora('配置 ignore 文件...').start();
+  const ignoreResults = setupIgnoreFiles(selectedTools, projectDir);
+  if (ignoreResults.length > 0) {
+    ignoreSpinner.succeed('ignore 文件已配置');
+    for (const result of ignoreResults) {
+      console.log(chalk.gray(`  └ ${result.file}: ${result.action === 'created' ? '已创建' : '已更新'}`));
+    }
+  } else {
+    ignoreSpinner.succeed('ignore 文件无需更新');
+  }
+
   // 完成
   console.log();
   console.log(chalk.green('══════════════════════════════════════'));
@@ -946,6 +1166,14 @@ async function updateCommand(projectDir) {
     }
   }
 
+  // 更新 Claude Code 自定义子代理（项目目录）
+  const agentsResults = installClaudeAgents(configuredTools, projectDir, true);
+  for (const result of agentsResults) {
+    if (result.count > 0) {
+      console.log(chalk.green('✓') + ` ${result.tool}: 更新了 ${result.count} 个自定义子代理`);
+    }
+  }
+
   // 更新 Rules（项目目录）
   const rulesTools = configuredTools.filter(id => {
     const tool = AI_TOOLS.find(t => t.id === id);

package/package.json

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

package/skills/_shared/references//345/201/217/347/246/273/346/243/200/346/265/213/344/270/216/350/267/257/347/224/261/345/215/217/350/256/256.md

@@ -0,0 +1,199 @@
+# 偏离检测与路由协议
+
+> 本协议定义了 skill 执行过程中的偏离检测、记录和路由机制。
+> 所有 Apply 阶段的 skill（coder、test-owner、reviewer）必须遵循本协议。
+
+## 核心问题
+
+在长任务（如 coder）执行过程中，可能出现：
+1. 计划外的功能修改或新增
+2. 发现设计文档的约束需要调整
+3. 上下文超出引发 compact，导致偏离信息丢失
+
+**解决方案**：实时落盘 + 完成时检测 + 结构化路由
+
+---
+
+## 完成状态分类（MECE）
+
+每个 skill 结束时，必须识别并声明当前状态：
+
+| 状态码 | 状态 | 含义 | 下一步 |
+|:------:|------|------|--------|
+| ✅ | COMPLETED | 正常完成，无偏离 | 进入下一个 skill |
+| ⚠️ | COMPLETED_WITH_DEVIATION | 完成但有偏离/新增 | 先 design-backport，再下一步 |
+| 🔄 | HANDOFF | 需要其他角色处理 | 退回指定 skill |
+| ❌ | BLOCKED | 阻塞，需要外部输入 | 记录断点，等待 |
+| 💥 | FAILED | 失败，闸门未通过 | 修复后重试 |
+
+### 状态判定规则
+
+```
+如果 deviation-log.md 有未回写的记录
+  → COMPLETED_WITH_DEVIATION
+
+如果 tasks.md 有未完成项
+  → BLOCKED 或 FAILED（取决于原因）
+
+如果发现需要修改 tests/（对于 coder）
+  → HANDOFF to test-owner
+
+如果所有任务完成且无偏离
+  → COMPLETED
+```
+
+---
+
+## 偏离日志协议（Deviation Log Protocol）
+
+### 文件位置
+
+```
+<change-root>/<change-id>/deviation-log.md
+```
+
+### 文件格式
+
+```markdown
+# 偏离日志 (Deviation Log)
+
+> 此文件记录实现过程中发现的所有偏离、新增和临时决策。
+> **重要**：Compact 后此文件仍然存在，确保信息不丢失。
+
+## 待回写记录
+
+| 时间 | 类型 | 描述 | 涉及文件 | 已回写 |
+|------|------|------|----------|:------:|
+| YYYY-MM-DD HH:mm | NEW_FEATURE | 添加了 X 功能 | src/x.ts | ❌ |
+| YYYY-MM-DD HH:mm | CONSTRAINT_CHANGE | 超时改为 60s | config.ts | ❌ |
+| YYYY-MM-DD HH:mm | DESIGN_GAP | 发现未覆盖的边界情况 | - | ❌ |
+
+## 已回写记录
+
+（design-backport 完成后移动到此处）
+
+| 时间 | 类型 | 描述 | 回写到 |
+|------|------|------|--------|
+```
+
+### 偏离类型定义
+
+| 类型 | 代码 | 描述 | 示例 |
+|------|------|------|------|
+| 新增功能 | NEW_FEATURE | 添加了设计中没有的功能 | 新增 warmup() 方法 |
+| 约束变更 | CONSTRAINT_CHANGE | 修改了设计中的约束/配置 | 超时从 30s 改为 60s |
+| 设计缺口 | DESIGN_GAP | 发现设计未覆盖的场景 | 并发情况未考虑 |
+| 接口变更 | API_CHANGE | 公共接口与设计不一致 | 参数增加了 options |
+| 依赖变更 | DEPENDENCY_CHANGE | 引入了计划外的依赖 | 新增 lodash |
+
+---
+
+## 实时落盘协议
+
+### 何时写入 deviation-log.md
+
+**必须立即写入**的情况：
+
+1. **添加了新文件/函数**，且不在 tasks.md 中
+2. **修改了配置/约束**，且与 design.md 不一致
+3. **发现边界情况**，design.md 未覆盖
+4. **临时决策**，需要事后确认
+
+### 如何写入
+
+```markdown
+## 示例：发现需要新增功能
+
+在 deviation-log.md 中追加一行：
+
+| 2024-01-15 10:30 | NEW_FEATURE | 添加缓存预热功能，提升首次访问性能 | src/cache.ts | ❌ |
+```
+
+### Compact 保护
+
+deviation-log.md 是**持久化文件**，不受 compact 影响。即使对话上下文被压缩：
+- 文件内容仍然存在
+- 下一个 skill 可以读取并处理
+
+---
+
+## 下一步路由规则
+
+### 通用路由表
+
+| 当前 Skill | 完成状态 | 下一步 |
+|------------|----------|--------|
+| 任意 | COMPLETED_WITH_DEVIATION | `devbooks-design-backport` |
+| coder | COMPLETED | `devbooks-code-review` |
+| coder | HANDOFF (测试问题) | `devbooks-test-owner` |
+| test-owner | COMPLETED | `devbooks-coder` |
+| test-owner | HANDOFF (设计问题) | `devbooks-design-backport` |
+| code-review | COMPLETED (有 spec delta) | `devbooks-spec-gardener` |
+| code-review | COMPLETED (无 spec delta) | 归档完成 |
+| 任意 | BLOCKED | 记录断点，等待用户 |
+| 任意 | FAILED | 修复后重试当前 skill |
+
+### 路由输出模板
+
+完成 skill 后，必须输出以下格式：
+
+```markdown
+## 完成状态
+
+**状态**：[COMPLETED / COMPLETED_WITH_DEVIATION / HANDOFF / BLOCKED / FAILED]
+
+**偏离记录**：[有 N 条 / 无]
+
+## 下一步
+
+**推荐**：`devbooks-xxx skill`
+
+**原因**：[具体原因]
+
+**调用方式**：
+运行 devbooks-xxx skill 处理变更 <change-id>
+```
+
+---
+
+## 与 design-backport 的交互
+
+### 触发条件
+
+当 deviation-log.md 中有**未回写记录**（已回写=❌）时，必须先执行 design-backport。
+
+### 回写完成标记
+
+design-backport 完成后：
+1. 将记录从"待回写"移动到"已回写"
+2. 更新"已回写"列为 ✅
+3. 记录回写到的具体位置
+
+---
+
+## 检测脚本（可选）
+
+```bash
+# 检查是否有未回写的偏离
+check_deviation() {
+  local change_dir="$1"
+  local log_file="${change_dir}/deviation-log.md"
+
+  if [[ ! -f "$log_file" ]]; then
+    echo "NO_DEVIATION"
+    return 0
+  fi
+
+  if grep -q "| ❌" "$log_file"; then
+    echo "HAS_PENDING_DEVIATION"
+    return 1
+  fi
+
+  echo "ALL_BACKPORTED"
+  return 0
+}
+```
+
+---
+
+*此协议是 DevBooks Apply 阶段的核心协议，所有实现类 skill 必须遵循。*

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

@@ -1,18 +1,13 @@
 ---
 name: devbooks-brownfield-bootstrap
 description: devbooks-brownfield-bootstrap：存量项目初始化：在当前真理目录为空时生成项目画像、术语表、基线规格与最小验证锚点，避免"边补 specs 边改行为"。用户说"存量初始化/基线 specs/项目画像/建立 glossary/把老项目接入上下文协议"等时使用。
-tools:
+allowed-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）

package/skills/devbooks-code-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: devbooks-code-review
 description: devbooks-code-review：以 Reviewer 角色做可读性/一致性/依赖健康/坏味道审查，只输出审查意见与可执行建议，不讨论业务正确性。用户说"帮我做代码评审/review 可维护性/坏味道/依赖风险/一致性建议"，或在 DevBooks apply 阶段以 reviewer 执行时使用。
-tools:
+allowed-tools:
   - Glob
   - Grep
   - Read

package/skills/devbooks-coder/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: devbooks-coder
 description: devbooks-coder：以 Coder 角色严格按 tasks.md 实现功能并跑闸门，禁止修改 tests/，以测试/静态检查为唯一完成判据。用户说"按计划实现/修复测试失败/让闸门全绿/实现任务项/不改测试"，或在 DevBooks apply 阶段以 coder 执行时使用。
-tools:
+allowed-tools:
   - Glob
   - Grep
   - Read
@@ -245,45 +245,104 @@ fi
 
 ---
 
-## 下一步推荐
+## 偏离检测与落盘协议
 
-**参考**：`skills/_shared/workflow-next-steps.md`
+**参考**：`skills/_shared/references/偏离检测与路由协议.md`
 
-完成 coder（所有任务完成，闸门变绿）后，下一步是：
+### 实时落盘要求
 
-| 条件 | 下一个 Skill | 原因 |
-|------|--------------|------|
-| 所有任务已完成 | `devbooks-code-review` | 评审可读性/一致性 |
-| 需要修改测试 | 交回 `devbooks-test-owner` | Coder 不能修改测试 |
+在实现过程中，**必须立即**将以下情况写入 `deviation-log.md`：
+
+| 情况 | 类型 | 示例 |
+|------|------|------|
+| 添加了 tasks.md 中没有的功能 | NEW_FEATURE | 新增 warmup() 方法 |
+| 修改了 design.md 中的约束 | CONSTRAINT_CHANGE | 超时改为 60s |
+| 发现设计未覆盖的边界情况 | DESIGN_GAP | 并发场景 |
+| 公共接口与设计不一致 | API_CHANGE | 参数增加 |
+
+### deviation-log.md 格式
+
+```markdown
+# 偏离日志
+
+## 待回写记录
+
+| 时间 | 类型 | 描述 | 涉及文件 | 已回写 |
+|------|------|------|----------|:------:|
+| 2024-01-15 10:30 | NEW_FEATURE | 添加缓存预热功能 | src/cache.ts | ❌ |
+```
+
+### Compact 保护
+
+**重要**：deviation-log.md 是持久化文件，不受 compact 影响。即使对话被压缩，偏离信息仍然保留。
+
+---
+
+## 完成状态与下一步路由
+
+### 完成状态分类（MECE）
+
+| 状态码 | 状态 | 判定条件 | 下一步 |
+|:------:|------|----------|--------|
+| ✅ | COMPLETED | 所有任务完成，无偏离 | `devbooks-code-review` |
+| ⚠️ | COMPLETED_WITH_DEVIATION | 任务完成，deviation-log 有未回写记录 | `devbooks-design-backport` |
+| 🔄 | HANDOFF | 发现测试问题需要修改 | `devbooks-test-owner` |
+| ❌ | BLOCKED | 需要外部输入/决策 | 记录断点，等待用户 |
+| 💥 | FAILED | 闸门未通过 | 修复后重试 |
+
+### 状态判定流程
 
-**关键**：
-- Coder **不能修改** `tests/**`
-- 如发现测试问题，交回 Test Owner（单独会话）
-- 工作流顺序是：
 ```
-coder → code-review → spec-gardener (如有 spec deltas) → 归档
+1. 检查 deviation-log.md 是否有 "| ❌" 记录
+   → 有：COMPLETED_WITH_DEVIATION
+
+2. 检查是否需要修改 tests/
+   → 是：HANDOFF to test-owner
+
+3. 检查 tasks.md 是否全部完成
+   → 否：BLOCKED 或 FAILED
+
+4. 以上都通过
+   → COMPLETED
 ```
 
-### 输出模板
+### 路由输出模板（必须使用）
 
-完成 coder（所有闸门变绿）后，输出：
+完成 coder 后，**必须**输出以下格式：
 
 ```markdown
-## 推荐的下一步
+## 完成状态
+
+**状态**：✅ COMPLETED / ⚠️ COMPLETED_WITH_DEVIATION / 🔄 HANDOFF / ❌ BLOCKED / 💥 FAILED
+
+**任务进度**：X/Y 已完成
 
-**下一步：`devbooks-code-review`**
+**偏离记录**：有 N 条待回写 / 无
 
-原因：所有任务已完成，闸门已变绿。下一步是代码评审，检查可读性、一致性和可维护性。
+## 下一步
+
+**推荐**：`devbooks-xxx skill`
+
+**原因**：[具体原因]
 
 ### 如何调用
-```
-运行 devbooks-code-review skill 处理变更 <change-id>
+运行 devbooks-xxx skill 处理变更 <change-id>
 ```
 
-### 评审后
-- 如有 spec deltas：`devbooks-spec-gardener` 合并到真理
-- 如无 spec deltas：归档完成
-```
+### 具体路由规则
+
+| 我的状态 | 下一步 | 原因 |
+|----------|--------|------|
+| COMPLETED | `devbooks-code-review` | 评审可读性/一致性 |
+| COMPLETED_WITH_DEVIATION | `devbooks-design-backport` | 先回写设计，再评审 |
+| HANDOFF (测试问题) | `devbooks-test-owner` | Coder 不能修改测试 |
+| BLOCKED | 等待用户 | 记录断点区 |
+| FAILED | 修复后重试 | 分析失败原因 |
+
+**关键约束**：
+- Coder **永远不能修改** `tests/**`
+- 如发现测试问题，必须 HANDOFF 给 Test Owner（单独会话）
+- 如有偏离，必须先 design-backport 再继续
 
 ---
 

package/skills/devbooks-delivery-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: devbooks-delivery-workflow
 description: devbooks-delivery-workflow：把一次变更跑成可追溯闭环（Design→Plan→Trace→Verify→Implement→Archive），明确 DoD、追溯矩阵与角色隔离（Test Owner 与 Coder 分离）。用户说"跑一遍闭环/交付验收/追溯矩阵/DoD/关账归档/验收工作流"等时使用。
-tools:
+allowed-tools:
   - Glob
   - Grep
   - Read

package/skills/devbooks-design-backport/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: devbooks-design-backport
 description: devbooks-design-backport：把实现过程中发现的新约束/冲突/缺口回写到 design.md（保持设计为黄金真理），并标注决策与影响。用户说"回写设计/补充设计文档/Design Backport/设计与实现不一致/需要澄清约束"等时使用。
-tools:
+allowed-tools:
   - Glob
   - Grep
   - Read

package/skills/devbooks-design-doc/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: devbooks-design-doc
 description: devbooks-design-doc：产出变更包的设计文档（design.md），只写 What/Constraints 与 AC-xxx，不写实现步骤。用户说"写设计文档/Design Doc/架构设计/约束/验收标准/AC/C4 Delta"等时使用。
-tools:
+allowed-tools:
   - Glob
   - Grep
   - Read