dev-playbooks-cn 1.7.3 → 2.0.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/package.json

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

package/skills/Skill/345/274/200/345/217/221/346/214/207/345/215/227.md

@@ -39,7 +39,7 @@
 - [ ] 多次运行不产生累积副作用
 - [ ] 提供"dry-run"模式预览变更
 
-### 1.3 强制验证前置原则（借鉴 VS Code）
+### 1.3 强制验证前置原则
 
 **核心要求**：生成/修改类 Skill 在输出文件后，**必须运行验证**，验证失败时禁止进入下一步。
 
@@ -99,7 +99,7 @@ echo "ok: verification passed"
 - **写入工作区**：Skill 的写入目标是 `<change-root>/<change-id>/`
 - **归档即合并**：归档操作将工作区内容合并回真理源
 
-### 1.6 资源清理原则（借鉴 VS Code）
+### 1.6 资源清理原则
 
 **要求**：无论成功失败，必须清理临时资源。
 

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 做版本控制）
+- 临时性的决策（如变量命名）
+- 可逆的决策（如代码格式）

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

@@ -0,0 +1,202 @@
+# Design 文档模板
+
+> 本模板定义了 design.md 的标准结构，确保设计清晰、可实现、可验证。
+
+## 文件位置
+
+```
+<change-root>/<change-id>/design.md
+```
+
+## 标准结构
+
+```markdown
+# <变更标题> - 设计文档
+
+## 🎯 结论先行（30秒阅读）
+
+**本设计会导致**：
+- ✅ [会发生什么变化 1]
+- ✅ [会发生什么变化 2]
+- ✅ [会发生什么变化 3]
+
+**本设计不会导致**：
+- ❌ [不会发生什么 1]
+- ❌ [不会发生什么 2]
+
+**与 Proposal 的差异**：
+- 📝 Proposal 说"[Proposal 的内容]"
+- 🎨 Design 说"[Design 的具体实现方式]"
+
+---
+
+## 🤔 需求对齐检查（2分钟阅读）
+
+> 目的：确认设计符合你的需求
+
+### 快速检查
+
+**Proposal 阶段你选择了**：
+- 角色：[角色名称]
+- 方案：[方案名称]
+
+**Design 阶段的变化**：
+- ⚠️ [发现的新问题或约束]
+- ✅ [建议的调整]
+- ⚠️ 代价：[说明代价]
+
+**需要你确认**：
+- [ ] ✅ 同意调整（[理由]）
+- [ ] ❌ 不同意，继续原方案（[理由]）
+- [ ] 🤔 我需要更多信息
+
+**默认选择**：✅ 同意调整（24小时后自动批准）
+
+---
+
+## ✅ 批准流程（1分钟）
+
+**当前状态**：
+- 📝 状态：待批准
+- ⏰ 创建时间：[时间]
+- ⏰ 超时时间：[时间]（24小时后）
+
+**如果你同意**：
+- [ ] ✅ 批准设计，开始实现
+
+**如果你不同意**：
+- [ ] ❌ 拒绝设计，说明理由：[理由]
+
+**默认选择**：✅ 批准设计（24小时后自动批准）
+
+---
+
+## 📋 详细设计（AI阅读）
+
+### What（做什么）
+
+#### 目标
+
+[描述设计的目标]
+
+#### 范围
+
+[说明设计的范围]
+
+---
+
+### Constraints（约束条件）
+
+#### 技术约束
+
+| 约束 | 说明 | 影响 |
+|------|------|------|
+| [约束1] | [说明] | [影响] |
+
+#### 业务约束
+
+| 约束 | 说明 | 影响 |
+|------|------|------|
+| [约束1] | [说明] | [影响] |
+
+---
+
+### Architecture（架构设计）
+
+#### 组件图
+
+```
+[使用 Mermaid 或文本描述组件关系]
+```
+
+#### 数据流
+
+```
+[描述数据流向]
+```
+
+#### 接口设计
+
+| 接口 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| [接口1] | [输入] | [输出] | [说明] |
+
+---
+
+### Acceptance Criteria（验收标准）
+
+#### AC-001: [验收标准标题]
+
+**描述**：[一句话描述]
+
+**验收条件**：
+- [ ] [条件1]
+- [ ] [条件2]
+
+**测试方式**：[说明如何测试]
+
+---
+
+### Documentation Impact（文档影响）
+
+#### 需要更新的文档
+
+| 文档 | 更新原因 | 优先级 |
+|------|----------|--------|
+| [文档1] | [原因] | P0 |
+
+#### 无需更新的文档
+
+- [ ] 本次变更为内部重构，不影响用户可见功能
+- [ ] 本次变更仅修复 bug，不引入新功
+
+---
+
+### Architecture Impact（架构影响）
+
+#### 新增依赖
+
+| 依赖 | 版本 | 用途 | 风险 |
+|------|------|------|------|
+| [依赖1] | [版本] | [用途] | [风险] |
+
+#### 修改的模块
+
+| 模块 | 修改类型 | 影响范围 |
+|------|----------|----------|
+| [模块1] | [新增/修改/删除] | [影响范围] |
+
+---
+
+## 批准历史
+
+| 时间 | 阶段 | 操作 | 操作者 | 理由 |
+|------|------|------|--------|------|
+| [时间] | Design | 创建 | AI | - |
+| [时间] | Design | 批准 | 用户 | [理由] |
+```
+
+## 使用指南
+
+### 1. 结论先行的作用
+
+- **30秒快速理解**：让用户立即知道设计的核心内容
+- **与 Proposal 对比**：明确说明设计与提案的差异
+- **降低认知负担**：用大白话，不用专业术语
+
+### 2. 需求对齐检查的作用
+
+- **轻量级对齐**：只在发现新问题或约束时才需要用户确认
+- **快速决策**：大部分情况下用户只需要确认"同意"或"不同意"
+- **保留控制权**：用户可以随时拒绝调整
+
+### 3. 详细设计的作用
+
+- **AI阅读**：提供完整的技术细节供AI参考
+- **人类可跳过**：人类只需要读"结论先行"和"需求对齐检查"部分
+
+### 4. 验收标准的作用
+
+- **可测试**：每个验收标准都应该是可测试的
+- **可追溯**：验收标准应该与 Proposal 的目标对应
+- **可验证**：验收标准应该明确说明如何验证