dev-playbooks-cn 1.7.4 → 2.1.0

package/README.md

@@ -31,6 +31,39 @@ AI 编码助手很强大，但往往**不可预测**：
 
 ---
 
+## ✨ v2.0.0 新特性：人类友好的文档模板
+
+**核心理念**：AI 时代，人类需要简洁的信息来做决策，而不是阅读 AI 生成的上千行文档。
+
+### 结论先行（30秒快速理解）
+
+每个文档（proposal、design、tasks、verification）顶部都有简短摘要：
+- ✅ **会导致什么**：用大白话列出变化
+- ❌ **不会导致什么**：明确说明不变的事情
+- 📝 **一句话总结**：让非技术人员也能理解
+
+### 需求对齐（挖掘隐藏需求）
+
+在 proposal 阶段，通过问题引导用户思考：
+- 👤 **你是谁？**：快速上手者 / 平台构建者 / 快速验证者
+- 🎯 **你要什么？**：显性需求 + 隐藏需求
+- 💡 **多视角推荐**：基于不同角色给出不同方案
+
+### 默认批准机制（减少决策疲劳）
+
+- ⏰ **用户不说话 = 同意**：超时后自动批准
+- 🎛️ **可配置超时**：proposal 48h / design 24h / tasks 24h / verification 12h
+- 🔒 **保留控制权**：用户可以随时拒绝或自定义
+
+### 项目级文档（知识沉淀）
+
+- 📋 **用户画像**（project-profile.md）：记录角色、需求、约束、偏好
+- 📝 **决策日志**（decision-log.md）：记录所有重要决策，方便回溯
+
+**详见**：`docs/v2.0.0-修改总结.md`
+
+---
+
 ## 工作原理
 
 **核心约束**：Test Owner 与 Coder **必须在独立对话**中工作。这是硬性约束，不是建议。Coder 不能修改 `tests/**`，完成由测试/构建验证，而非 AI 自评。

package/bin/devbooks.js

@@ -380,6 +380,195 @@ async function performNpmUpdate() {
   });
 }
 
+/**
+ * 显示版本变更摘要
+ * @param {string} fromVersion - 当前版本
+ * @param {string} toVersion - 目标版本
+ */
+async function displayVersionChangelog(fromVersion, toVersion) {
+  try {
+    // 尝试从 npm 获取 CHANGELOG
+    const { execSync } = await import('child_process');
+    const changelogUrl = `https://raw.githubusercontent.com/Darkbluelr/dev-playbooks-cn/master/CHANGELOG.md`;
+
+    // 使用 curl 获取 CHANGELOG（如果可用）
+    let changelog = '';
+    try {
+      changelog = execSync(`curl -s -m 5 "${changelogUrl}"`, {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+    } catch {
+      // 如果获取失败，显示简化信息
+      console.log(chalk.cyan('📋 版本变更摘要'));
+      console.log(chalk.gray('─'.repeat(60)));
+      console.log(chalk.yellow('⚠ 无法获取详细变更日志，请访问：'));
+      console.log(chalk.blue(`   https://github.com/Darkbluelr/dev-playbooks-cn/releases/tag/v${toVersion}`));
+      return;
+    }
+
+    // 解析 CHANGELOG，提取相关版本的变更
+    const changes = parseChangelog(changelog, fromVersion, toVersion);
+
+    if (changes.length === 0) {
+      console.log(chalk.cyan('📋 版本变更摘要'));
+      console.log(chalk.gray('─'.repeat(60)));
+      console.log(chalk.yellow('⚠ 未找到详细变更信息，请访问：'));
+      console.log(chalk.blue(`   https://github.com/Darkbluelr/dev-playbooks-cn/releases/tag/v${toVersion}`));
+      return;
+    }
+
+    // 显示变更摘要
+    console.log(chalk.cyan('📋 版本变更摘要'));
+    console.log(chalk.gray('─'.repeat(60)));
+
+    for (const change of changes) {
+      console.log();
+      console.log(chalk.bold.green(`## ${change.version}`));
+      if (change.date) {
+        console.log(chalk.gray(`   发布日期: ${change.date}`));
+      }
+      console.log();
+
+      // 显示主要变更（限制显示前10条）
+      const highlights = change.content.split('\n')
+        .filter(line => line.trim().length > 0)
+        .slice(0, 10);
+
+      for (const line of highlights) {
+        if (line.startsWith('###')) {
+          console.log(chalk.bold.yellow(line));
+        } else if (line.startsWith('####')) {
+          console.log(chalk.bold(line));
+        } else if (line.startsWith('- ✅') || line.startsWith('- ✓')) {
+          console.log(chalk.green(line));
+        } else if (line.startsWith('- ⚠️') || line.startsWith('- ❌')) {
+          console.log(chalk.yellow(line));
+        } else if (line.startsWith('- ')) {
+          console.log(chalk.white(line));
+        } else {
+          console.log(chalk.gray(line));
+        }
+      }
+
+      if (change.content.split('\n').length > 10) {
+        console.log(chalk.gray('   ... (更多变更请查看完整日志)'));
+      }
+    }
+
+    console.log();
+    console.log(chalk.gray('─'.repeat(60)));
+    console.log(chalk.blue('📖 完整变更日志: ') + chalk.underline(`https://github.com/Darkbluelr/dev-playbooks-cn/blob/master/CHANGELOG.md`));
+
+  } catch (error) {
+    // 静默失败，不影响更新流程
+    console.log(chalk.gray('提示: 无法显示变更摘要'));
+  }
+}
+
+/**
+ * 解析 CHANGELOG 内容，提取指定版本范围的变更
+ * @param {string} changelog - CHANGELOG 内容
+ * @param {string} fromVersion - 起始版本
+ * @param {string} toVersion - 目标版本
+ * @returns {Array} - 变更列表
+ */
+function parseChangelog(changelog, fromVersion, toVersion) {
+  const changes = [];
+  const lines = changelog.split('\n');
+
+  let currentVersion = null;
+  let currentDate = null;
+  let currentContent = [];
+  let inVersionBlock = false;
+  let shouldCapture = false;
+
+  // 解析版本号（移除 'v' 前缀）
+  const from = fromVersion.replace(/^v/, '');
+  const to = toVersion.replace(/^v/, '');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // 匹配版本标题：## [2.0.0] - 2026-01-19
+    const versionMatch = line.match(/^##\s+\[?(\d+\.\d+\.\d+)\]?\s*(?:-\s*(\d{4}-\d{2}-\d{2}))?/);
+
+    if (versionMatch) {
+      // 保存上一个版本的内容
+      if (inVersionBlock && shouldCapture && currentVersion) {
+        changes.push({
+          version: currentVersion,
+          date: currentDate,
+          content: currentContent.join('\n').trim()
+        });
+      }
+
+      // 开始新版本
+      currentVersion = versionMatch[1];
+      currentDate = versionMatch[2] || null;
+      currentContent = [];
+      inVersionBlock = true;
+
+      // 判断是否应该捕获这个版本
+      // 捕获从 fromVersion 到 toVersion 之间的所有版本
+      const versionNum = currentVersion.split('.').map(Number);
+      const fromNum = from.split('.').map(Number);
+      const toNum = to.split('.').map(Number);
+
+      const isAfterFrom = compareVersions(versionNum, fromNum) > 0;
+      const isBeforeOrEqualTo = compareVersions(versionNum, toNum) <= 0;
+
+      shouldCapture = isAfterFrom && isBeforeOrEqualTo;
+
+      continue;
+    }
+
+    // 如果遇到下一个版本标题或分隔线，结束当前版本
+    if (line.startsWith('---') && inVersionBlock) {
+      if (shouldCapture && currentVersion) {
+        changes.push({
+          version: currentVersion,
+          date: currentDate,
+          content: currentContent.join('\n').trim()
+        });
+      }
+      inVersionBlock = false;
+      shouldCapture = false;
+      continue;
+    }
+
+    // 收集内容
+    if (inVersionBlock && shouldCapture) {
+      currentContent.push(line);
+    }
+  }
+
+  // 保存最后一个版本
+  if (inVersionBlock && shouldCapture && currentVersion) {
+    changes.push({
+      version: currentVersion,
+      date: currentDate,
+      content: currentContent.join('\n').trim()
+    });
+  }
+
+  return changes;
+}
+
+/**
+ * 比较两个版本号
+ * @param {number[]} v1 - 版本1 [major, minor, patch]
+ * @param {number[]} v2 - 版本2 [major, minor, patch]
+ * @returns {number} - 1 if v1 > v2, -1 if v1 < v2, 0 if equal
+ */
+function compareVersions(v1, v2) {
+  for (let i = 0; i < 3; i++) {
+    if (v1[i] > v2[i]) return 1;
+    if (v1[i] < v2[i]) return -1;
+  }
+  return 0;
+}
+
 // ============================================================================
 // 自动更新 .gitignore 和 .npmignore
 // ============================================================================
@@ -1373,6 +1562,12 @@ async function updateCommand(projectDir) {
 
   if (hasUpdate) {
     spinner.info(`发现新版本: ${currentVersion} → ${latestVersion}`);
+
+    // 显示版本变更摘要
+    console.log();
+    await displayVersionChangelog(currentVersion, latestVersion);
+    console.log();
+
     const shouldUpdate = await confirm({
       message: `是否更新 ${CLI_COMMAND} 到 ${latestVersion}?`,
       default: true

package/package.json

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

package/skills/_shared/references//346/211/271/345/207/206/351/205/215/347/275/256/350/257/264/346/230/216.md

@@ -0,0 +1,285 @@
+# 批准配置说明
+
+> 本文档说明如何配置批准机制，包括默认批准、超时时间等。
+
+## 配置文件位置
+
+```
+.devbooks/config.yaml
+```
+
+## 配置示例
+
+```yaml
+# 批准配置
+approval:
+  # 默认批准策略
+  # - auto_approve: 超时后自动批准（默认）
+  # - require_explicit: 必须明确批准
+  # - disabled: 禁用批准机制
+  default_strategy: auto_approve
+
+  # 超时时间（小时）
+  timeout:
+    proposal: 48      # Proposal 需要 48 小时
+    design: 24        # Design 需要 24 小时
+    tasks: 24         # Tasks 需要 24 小时
+    verification: 12  # Verification 需要 12 小时
+
+  # 是否需要明确批准
+  require_explicit:
+    proposal: true    # Proposal 必须明确批准
+    design: false     # Design 可以自动批准
+    tasks: false      # Tasks 可以自动批准
+    verification: false  # Verification 可以自动批准
+
+  # 批准方式
+  approval_methods:
+    - cli           # 命令行批准
+    - chat          # 聊天批准
+    - auto          # 自动批准
+
+  # 通知方式
+  notification:
+    - terminal      # 终端通知
+    # - desktop     # 桌面通知（可选）
+    # - email       # 邮件通知（可选）
+```
+
+## 配置说明
+
+### 1. 默认批准策略
+
+| 策略 | 说明 | 适用场景 |
+|------|------|----------|
+| `auto_approve` | 超时后自动批准 | 大部分情况（推荐） |
+| `require_explicit` | 必须明确批准 | 高风险项目 |
+| `disabled` | 禁用批准机制 | 完全信任 AI |
+
+### 2. 超时时间
+
+- **Proposal**：48 小时（需要更多时间思考）
+- **Design**：24 小时（技术细节）
+- **Tasks**：24 小时（任务拆分）
+- **Verification**：12 小时（验收结果）
+
+**建议**：
+- 个人项目：可以缩短超时时间（如 12/6/6/3 小时）
+- 团队项目：保持默认超时时间
+- 高风险项目：延长超时时间（如 72/48/48/24 小时）
+
+### 3. 是否需要明确批准
+
+- **true**：必须明确批准，不会自动批准
+- **false**：超时后自动批准
+
+**建议**：
+- Proposal 设置为 true（重要决策）
+- 其他阶段设置为 false（减少负担）
+
+### 4. 批准方式
+
+#### CLI 批准
+
+```bash
+# 批准
+devbooks approve <change-id> --stage proposal
+
+# 拒绝
+devbooks reject <change-id> --stage proposal --reason "理由"
+
+# 修改
+devbooks revise <change-id> --stage proposal
+```
+
+#### 聊天批准
+
+直接在聊天中说：
+- "同意" / "批准" / "approve"
+- "不同意" / "拒绝" / "reject"
+- "我想修改 XXX"
+
+#### 自动批准
+
+超时后自动批准（根据配置）
+
+### 5. 通知方式
+
+- **terminal**：终端通知（默认）
+- **desktop**：桌面通知（需要额外配置）
+- **email**：邮件通知（需要额外配置）
+
+## 批准流程
+
+### 1. 创建阶段
+
+AI 创建文档后，会在文档末尾添加批准区块：
+
+```markdown
+## ✅ 批准流程
+
+**当前状态**：
+- 📝 状态：待批准
+- ⏰ 创建时间：2026-01-19 10:00
+- ⏰ 超时时间：2026-01-20 10:00（24 小时后）
+
+**如果你同意**：
+- [ ] ✅ 批准，开始下一阶段
+
+**如果你不同意**：
+- [ ] ❌ 拒绝，说明理由
+
+**默认选择**：✅ 批准（24 小时后自动批准）
+```
+
+### 2. 通知阶段
+
+系统会通过配置的通知方式提醒用户：
+
+```
+⏰ 提醒：Proposal 待批准
+- 变更：20260119-1000-add-feature-x
+- 阶段：Proposal
+- 超时时间：2026-01-20 10:00（还剩 23 小时）
+- 操作：devbooks approve 20260119-1000-add-feature-x --stage proposal
+```
+
+### 3. 批准阶段
+
+用户可以通过以下方式批准：
+
+- **CLI**：`devbooks approve <change-id> --stage proposal`
+- **聊天**：直接说"同意"
+- **自动**：什么都不做，等待超时
+
+### 4. 超时阶段
+
+如果超时且配置为 `auto_approve`，系统会自动批准：
+
+```
+✅ 自动批准：Proposal
+- 变更：20260119-1000-add-feature-x
+- 阶段：Proposal
+- 原因：超时自动批准（24 小时）
+```
+
+### 5. 记录阶段
+
+所有批准操作都会记录在批准历史中：
+
+```markdown
+## 批准历史
+
+| 时间 | 阶段 | 操作 | 操作者 | 理由 |
+|------|------|------|--------|------|
+| 2026-01-19 10:00 | Proposal | 创建 | AI | - |
+| 2026-01-20 10:00 | Proposal | 自动批准 | 系统 | 24 小时超时 |
+```
+
+## 常见问题
+
+### Q1: 如何禁用自动批准？
+
+修改配置文件：
+
+```yaml
+approval:
+  default_strategy: require_explicit
+  require_explicit:
+    proposal: true
+    design: true
+    tasks: true
+    verification: true
+```
+
+### Q2: 如何缩短超时时间？
+
+修改配置文件：
+
+```yaml
+approval:
+  timeout:
+    proposal: 12
+    design: 6
+    tasks: 6
+    verification: 3
+```
+
+### Q3: 如何查看待批准的变更？
+
+```bash
+devbooks status
+```
+
+输出：
+
+```
+待批准的变更：
+- 20260119-1000-add-feature-x (Proposal, 还剩 23 小时)
+- 20260119-1100-fix-bug-y (Design, 还剩 5 小时)
+```
+
+### Q4: 如何批量批准？
+
+```bash
+devbooks approve --all
+```
+
+### Q5: 如何撤销批准？
+
+```bash
+devbooks revoke <change-id> --stage proposal
+```
+
+## 最佳实践
+
+### 1. 个人项目
+
+```yaml
+approval:
+  default_strategy: auto_approve
+  timeout:
+    proposal: 12
+    design: 6
+    tasks: 6
+    verification: 3
+  require_explicit:
+    proposal: false
+    design: false
+    tasks: false
+    verification: false
+```
+
+### 2. 团队项目
+
+```yaml
+approval:
+  default_strategy: auto_approve
+  timeout:
+    proposal: 48
+    design: 24
+    tasks: 24
+    verification: 12
+  require_explicit:
+    proposal: true
+    design: false
+    tasks: false
+    verification: false
+```
+
+### 3. 高风险项目
+
+```yaml
+approval:
+  default_strategy: require_explicit
+  timeout:
+    proposal: 72
+    design: 48
+    tasks: 48
+    verification: 24
+  require_explicit:
+    proposal: true
+    design: true
+    tasks: true
+    verification: true
+```

package/skills/_shared/references//346/226/207/346/241/243/346/250/241/346/235/277-decision-log.md

@@ -0,0 +1,137 @@
+# Decision Log 文档模板
+
+> 本模板定义了 decision-log.md 的标准结构，用于记录所有重要决策，方便回溯和学习。
+
+## 文件位置
+
+```
+<truth-root>/specs/_meta/decision-log.md
+```
+
+## 标准结构
+
+```markdown
+# 决策日志：<项目名称>
+
+> **目的**：记录所有重要决策，方便回溯和学习
+
+## 决策 #001：[决策标题]
+
+**决策时间**：YYYY-MM-DD
+**决策阶段**：Proposal / Design / Tasks / Verification
+**决策者**：用户 / AI 推荐 / 默认
+
+**背景**：
+[为什么需要做这个决策]
+
+**选项**：
+- 选项 A：[描述]
+  - 优势：[优势]
+  - 劣势：[劣势]
+  - 适合：[适合什么场景]
+
+- 选项 B：[描述]
+  - 优势：[优势]
+  - 劣势：[劣势]
+  - 适合：[适合什么场景]
+
+**决策**：
+选择选项 [X]
+
+**理由**：
+- [理由 1]
+- [理由 2]
+- [理由 3]
+
+**影响**：
+- ✅ [正面影响]
+- ⚠️ [负面影响]
+- ⚠️ [风险]
+
+**后续演变**：
+- YYYY-MM-DD：[演变记录]
+
+---
+
+## 决策 #002：[决策标题]
+
+...
+
+---
+
+## 决策模板
+
+**决策 #XXX：[决策标题]**
+
+**决策时间**：YYYY-MM-DD
+**决策阶段**：Proposal / Design / Tasks / Verification
+**决策者**：用户 / AI 推荐 / 默认
+
+**背景**：
+[为什么需要做这个决策]
+
+**选项**：
+- 选项 A：[描述]
+- 选项 B：[描述]
+- 选项 C：[描述]
+
+**决策**：
+选择选项 X
+
+**理由**：
+- [理由 1]
+- [理由 2]
+- [理由 3]
+
+**影响**：
+- ✅ [正面影响]
+- ⚠️ [负面影响]
+- ⚠️ [风险]
+
+**后续演变**：
+- YYYY-MM-DD：[演变记录]
+```
+
+## 使用指南
+
+### 1. 谁来写 Decision Log？
+
+- **proposal-author**：记录 Proposal 阶段的决策
+- **design-doc**：记录 Design 阶段的决策
+- **implementation-plan**：记录 Tasks 阶段的决策
+- **archiver**：归档时整理决策日志
+
+### 2. 谁来读 Decision Log？
+
+| Skill | 读取目的 |
+|-------|----------|
+| proposal-author | 了解历史决策，避免重复讨论 |
+| design-doc | 了解技术选型的历史原因 |
+| impact-analysis | 评估决策的长期影响 |
+| archiver | 整理决策日志，建立知识库 |
+
+### 3. 决策日志的作用
+
+- **知识沉淀**：记录决策的背景、理由和影响
+- **避免重复**：避免重复讨论相同的问题
+- **学习改进**：回顾决策的后续演变，学习经验教训
+- **团队协作**：让新成员快速了解项目的决策历史
+
+### 4. 决策日志的更新频率
+
+- **实时更新**：每次做出重要决策时立即记录
+- **定期回顾**：每月回顾一次，更新"后续演变"部分
+- **归档整理**：每次归档时整理决策日志，删除过时的决策
+
+### 5. 什么样的决策需要记录？
+
+**需要记录的决策**：
+- 技术选型（选择 A 而不是 B）
+- 架构设计（选择方案 A 而不是方案 B）
+- 重要的权衡（牺牲 X 换取 Y）
+- 边界条件（明确不做什么）
+
+**不需要记录的决策**：
+- 显而易见的决策（如使用 Git 做版本控制）
+- 临时性的决策（如变量命名）
+- 可逆的决策（如代码格式）