npm - dev-playbooks-cn - Versions diffs - 2.3.2 → 2.4.0 - Mend

dev-playbooks-cn 2.3.2 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -1,8 +1,6 @@
 # DevBooks
-**面向 Claude Code / Codex CLI 的代理式 AI 开发工作流**
-> 把大型变更变成可控、可追溯、可验证的闭环：Skills + 质量闸门 + 角色隔离。
+**AI 编程的质量闸门：让 AI 助手从"不可预测"变成"可验证"**
 [![npm](https://img.shields.io/npm/v/dev-playbooks-cn)](https://www.npmjs.com/package/dev-playbooks-cn)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -11,104 +9,74 @@
 ---
-## 为什么选择 DevBooks？
+## 30 秒电梯演讲
-AI 编码助手很强大，但往往**不可预测**：
+AI 编程助手很强大，但有个致命问题：**你无法确定它是真的完成了，还是只是看起来完成了。**
-| 痛点 | 后果 |
-|------|------|
-| **AI 自评"已完成"** | 实际测试不过、边界条件遗漏 |
-| **同一对话写测试又写代码** | 测试沦为"通过性测试"，而非验证规格 |
-| **无验证闸门** | 伪完成悄悄进入生产环境 |
-| **只支持 0→1 项目** | 存量代码库无从下手 |
-| **命令太少** | 复杂变更不只是"spec/apply/archive" |
+DevBooks 通过三个核心机制解决这个问题：
-**DevBooks 的解决方案**：
-- **基于证据的完成**：完成由测试/构建/证据定义，而非 AI 自我评估
-- **强制角色隔离**：Test Owner 与 Coder 必须在独立对话中工作
-- **多重质量闸门**：Green 证据检查、任务完成率、角色边界检查
-- **18 个 Skills**：覆盖提案、设计、评审、熵度量等完整工作流
+1. **角色隔离** - Test Owner 与 Coder 必须在独立对话中工作，测试不会沦为"通过性测试"
+2. **证据驱动** - 完成由测试通过 + 构建成功定义，而非 AI 自评
+3. **质量闸门** - 多重检查确保每个变更都是真正可交付的
----
+**结果**：从"边修边破"变成"稳定推进"。
-## ✨ v2.0.0 新特性：人类友好的文档模板
-**核心理念**：AI 时代，人类需要简洁的信息来做决策，而不是阅读 AI 生成的上千行文档。
+---
-### 结论先行（30秒快速理解）
+## 最佳实践：一键跑完整闭环
-每个文档（proposal、design、tasks、verification）顶部都有简短摘要：
-- ✅ **会导致什么**：用大白话列出变化
-- ❌ **不会导致什么**：明确说明不变的事情
-- 📝 **一句话总结**：让非技术人员也能理解
+不知道怎么用？直接运行：
-### 需求对齐（挖掘隐藏需求）
+```bash
+/devbooks-delivery-workflow
+```
-在 proposal 阶段，通过问题引导用户思考：
-- 👤 **你是谁？**：快速上手者 / 平台构建者 / 快速验证者
-- 🎯 **你要什么？**：显性需求 + 隐藏需求
-- 💡 **多视角推荐**：基于不同角色给出不同方案
+这个 skill 会自动编排完整的开发闭环：Proposal → Design → Spec → Plan → Test → Implement → Review → Archive
-### 默认批准机制（减少决策疲劳）
+**适用场景**：新功能开发、重大重构、不熟悉 DevBooks 工作流
-- ⏰ **用户不说话 = 同意**：超时后自动批准
-- 🎛️ **可配置超时**：proposal 48h / design 24h / tasks 24h / verification 12h
-- 🔒 **保留控制权**：用户可以随时拒绝或自定义
+---
-### 项目级文档（知识沉淀）
+## 我们解决的核心问题
-- 📋 **用户画像**（project-profile.md）：记录角色、需求、约束、偏好
-- 📝 **决策日志**（decision-log.md）：记录所有重要决策，方便回溯
+### 问题 1：逻辑幻觉与事实捏造
-**详见**：`docs/v2.0.0-修改总结.md`
+**痛点**：AI 在缺乏知识时倾向于自信地编造代码或库，而非承认无知。
----
+**DevBooks 方案**：
+- 规格驱动开发：所有代码必须追溯到 AC-xxx（验收标准）
+- Contract Tests：验证对外契约，防止 API 幻觉
-## 工作原理
+### 问题 2：非收敛性调试
-**核心约束**：Test Owner 与 Coder **必须在独立对话**中工作。这是硬性约束，不是建议。Coder 不能修改 `tests/**`，完成由测试/构建验证，而非 AI 自评。
+**痛点**：修复一个 Bug 引入两个新 Bug，陷入"打地鼠"循环。
----
+**DevBooks 方案**：
+- 角色隔离：Test Owner 先跑出 Red 基线，Coder 不能修改测试
+- 收敛性审计：`devbooks-convergence-audit` 评估变更包是否有效推进
-## 快速开始
+### 问题 3：局部最优与全局短视
-**不知道怎么用？** 查看 [使用指南](docs/使用指南.md) 或直接运行：
+**痛点**：AI 倾向于生成"能跑通"的独立代码块，缺乏对整体架构的考量。
-```bash
-/devbooks-delivery-workflow
-```
+**DevBooks 方案**：
+- 设计先行：Design Doc 定义 What/Constraints，不写 How
+- 架构约束：Fitness Rules 验证架构规则
+- 影响分析：变更前评估跨模块影响
-这个 skill 会自动编排完整的开发闭环，从提案到归档。
+### 问题 4：验证疲劳
-### 文档
+**痛点**：AI 生成速度极快，人类审查代码的警觉性随时间呈指数下降。
-- [使用指南](docs/使用指南.md) - 最佳实践和推荐工作流程
-- [Skill 详解](docs/Skill详解.md) - 19 个 Skills 的特色和功能
-- [配置指南](dev-playbooks/docs/DevBooks配置指南.md) - 配置说明
-- [推荐 MCP](dev-playbooks/docs/推荐MCP.md) - MCP 服务器推荐
+**DevBooks 方案**：
+- 自动化质量闸门：Green 证据检查、任务完成率、角色边界检查
+- 强制评审：Reviewer 只审查可维护性，业务正确性由测试保证
 ---
-### 支持的 AI 工具
-| 工具 | 支持级别 | 配置文件 |
-|------|----------|----------|
-| **Claude Code** | 完整 Skills | `CLAUDE.md` |
-| **Codex CLI** | 完整 Skills | `AGENTS.md` |
-| **Qoder** | 完整 Skills | `AGENTS.md` |
-| **OpenCode** | 完整 Skills | `AGENTS.md` |
-| **Every Code** | 完整 Skills | `AGENTS.md` |
-| **Cursor** | Rules 系统 | `.cursor/rules/` |
-| **Windsurf** | Rules 系统 | `.windsurf/rules/` |
-| **Gemini CLI** | Rules 系统 | `GEMINI.md` |
-| **Continue** | Rules 系统 | `.continue/rules/` |
-| **GitHub Copilot** | 自定义指令 | `.github/copilot-instructions.md` |
-> **提示**：使用自然语言调用 Skills，例如："运行 devbooks-proposal-author skill..."
-### 安装与初始化
+## 快速开始
-**npm 安装（推荐）：**
+### 安装
 ```bash
 # 全局安装
@@ -118,454 +86,155 @@ npm install -g dev-playbooks-cn
 dev-playbooks-cn init
 ```
-**一次性使用：**
-```bash
-npx dev-playbooks-cn@latest init
-```
-**从源码安装（贡献者）：**
-```bash
-./scripts/install-skills.sh
-```
-### 安装落点
-初始化时可选择 Skills 安装位置：
-| 安装范围 | 说明 | 路径示例 |
-|----------|------|----------|
-| **项目级**（默认） | 仅当前项目可用 | `.claude/skills/devbooks-*` |
-| **全局** | 所有项目共享 | `~/.claude/skills/devbooks-*` |
-```bash
-# 交互式选择
-dev-playbooks-cn init
-# 非交互式指定
-dev-playbooks-cn init --tools claude --scope project  # 项目级
-dev-playbooks-cn init --tools claude --scope global   # 全局
-```
 ### 更新
-使用 `update` 命令同时更新 CLI 和项目中的 Skills：
 ```bash
 dev-playbooks-cn update
 ```
-更新命令会：
-1. **检查 CLI 新版本**：自动检测 npm 上是否有新版本，交互式询问是否更新
-2. **更新项目文件**：更新 Skills、规则文件、指令文件等
-> **提示**：不再需要手动运行 `npm install -g dev-playbooks-cn`，`update` 命令会自动处理。
+### 支持的 AI 工具
-### 快速集成
+| 工具 | 支持级别 |
+|------|----------|
+| Claude Code | 完整 Skills |
+| Codex CLI | 完整 Skills |
+| Qoder | 完整 Skills |
+| OpenCode | 完整 Skills |
+| Every Code | 完整 Skills |
+| Cursor | Rules 系统 |
+| Windsurf | Rules 系统 |
+| Gemini CLI | Rules 系统 |
-DevBooks 使用两个目录根：
+---
-| 目录 | 用途 | 默认值 |
-|------|------|--------|
-| `<truth-root>` | 当前规格（只读真理） | `dev-playbooks/specs/` |
-| `<change-root>` | 变更包（工作区） | `dev-playbooks/changes/` |
+## 文档
-详见 `docs/DevBooks配置指南.md`。
+- [使用指南](docs/使用指南.md) - 完整工作流程和最佳实践
+- [Skill 详解](docs/Skill详解.md) - 18 个 Skills 的特色和功能
+- [配置指南](dev-playbooks/docs/DevBooks配置指南.md) - 配置说明
+- [推荐 MCP](dev-playbooks/docs/推荐MCP.md) - MCP 服务器推荐
 ---
-## 日常变更工作流
-### 使用 Router（推荐）
+## 核心理念
-告诉 AI 你的需求，让 Router 分析并输出执行计划：
+### 1. 角色隔离（Role Isolation）
-```
-请运行 devbooks-router skill，分析需求：<你的需求>
-```
+Test Owner 与 Coder **必须在独立对话**中工作。这不是建议，是硬性约束。
-### Skills 直达
+**为什么？**
+- 同一对话中写测试又写代码 → 测试沦为"通过性测试"
+- 独立对话 → 测试真正验证规格
-熟悉流程后，直接调用 Skill：
+### 2. 规格驱动（Spec-Driven）
-**1. Proposal 阶段（禁止编码）**
+所有代码必须追溯到 AC-xxx（验收标准）。
 ```
-请运行 devbooks-proposal-author skill，创建提案：添加 OAuth2 用户认证
+需求 → Proposal → Design (AC-001, AC-002) → Spec → Tasks → Tests → Code
 ```
-产物：`proposal.md`（必需）、`design.md`、`tasks.md`
+### 3. 证据优先（Evidence-First）
-**2. Apply 阶段（强制角色隔离）**
+完成由证据定义，而非 AI 声明。
-必须开 **2 个独立对话**：
+必需的证据：
+- 测试通过（Green 证据）
+- 构建成功
+- 静态检查通过
+- 任务完成率 100%
-```
-# 对话 A - Test Owner
-请运行 devbooks-test-owner skill，变更 ID：add-oauth2
-# 对话 B - Coder
-请运行 devbooks-coder skill，变更 ID：add-oauth2
-```
-- Test Owner：写 `verification.md` + 测试，先跑 **Red**
-- Coder：按 `tasks.md` 实现，让闸门 **Green**（禁止改测试）
-**3. Review 阶段**
-```
-请运行 devbooks-reviewer skill，变更 ID：add-oauth2
-```
+---
-**4. Archive 阶段**
+## 工作流程
 ```
-请运行 devbooks-archiver skill，变更 ID：add-oauth2
+1. Proposal（提案）- 分析需求，评估影响
+   ↓
+2. Design（设计）- 定义 What/Constraints + AC-xxx
+   ↓
+3. Spec（规格）- 定义对外行为契约
+   ↓
+4. Plan（计划）- 制定实现计划和任务拆解
+   ↓
+5. Test（测试）- 编写验收测试（独立对话）
+   ↓
+6. Implement（实现）- 实现功能（独立对话）
+   ↓
+7. Review（评审）- 代码评审
+   ↓
+8. Archive（归档）- 归档变更包
 ```
 ---
-## Skills 参考
-### Proposal 阶段
-| Skill | 说明 |
-|-------|------|
-| `devbooks-router` | 智能路由到合适的 Skill |
-| `devbooks-proposal-author` | 创建变更提案 |
-| `devbooks-impact-analysis` | 跨模块影响分析 |
-| `devbooks-proposal-challenger` | 质疑和挑战提案 |
-| `devbooks-proposal-judge` | 裁决提案 |
-| `devbooks-design-doc` | 创建设计文档 |
-| `devbooks-spec-contract` | 定义规格与契约 |
-| `devbooks-implementation-plan` | 创建实现计划 |
-### Apply 阶段
-| Skill | 说明 |
-|-------|------|
-| `devbooks-test-owner` | Test Owner 角色（必须独立对话） |
-| `devbooks-coder` | Coder 角色（必须独立对话） |
-| `devbooks-design-backport` | 回写发现到设计文档 |
-### Review 阶段
-| Skill | 说明 |
-|-------|------|
-| `devbooks-reviewer` | 代码评审（可读性/一致性） |
-| `devbooks-test-reviewer` | 测试质量与覆盖率评审 |
-| `devbooks-docs-consistency` | 文档一致性检查（原 devbooks-docs-sync） |
-### Archive 阶段
-| Skill | 说明 |
-|-------|------|
-| `devbooks-archiver` | 规格维护与去重 |
-### 独立技能
-| Skill | 说明 |
-|-------|------|
-| `devbooks-entropy-monitor` | 系统熵度量 |
-| `devbooks-brownfield-bootstrap` | 存量项目初始化 |
-| `devbooks-convergence-audit` | 收敛性审计（反迷惑设计） |
-### 编排层（支持子 Agent 的工具专用）
-| Skill | 说明 |
-|-------|------|
-| `devbooks-delivery-workflow` | 完整闭环编排器，自动编排 Proposal→Design→Spec→Plan→Test→Code→Review→Archive 全流程 |
-> **注意**：`devbooks-delivery-workflow` 是编排层 Skill，专为支持子 Agent 的 AI 编程工具（如 Claude Code with Task tool）设计。它会调用子 Agent 执行各阶段 Skill，完成完整的变更闭环。
----
-## DevBooks 对比
-### vs. OpenSpec
-[OpenSpec](https://github.com/Fission-AI/OpenSpec) 是轻量级规格驱动框架，用三个核心命令（proposal/apply/archive）对齐人与 AI。
-**OpenSpec 的局限**：
-- 缺乏角色隔离，AI 可能自我验证"已完成"
-- 无质量闸门，伪完成难以拦截
-- 只有 3 个命令，复杂变更覆盖不足
-**DevBooks 解决方案**：
-- **强制角色隔离**：Test Owner 与 Coder 必须独立对话，杜绝自我验证
-- **5+ 质量闸门**：Green 证据检查、任务完成率、角色边界检查
-- **18 个 Skills**：覆盖提案→实现→归档完整闭环
-### vs. spec-kit
-[GitHub spec-kit](https://github.com/github/spec-kit) 提供规格驱动开发工具包，有 constitution 文件和结构化规划。
-**spec-kit 的局限**：
-- 偏向 0→1 绿地项目，存量项目支持有限
-- 无强制角色隔离，测试与实现可能混淆
-- 依赖人工检查，缺乏运行时验证
-**DevBooks 解决方案**：
-- **存量优先**：`devbooks-brownfield-bootstrap` 自动生成基线规格
-- **强制角色隔离**：测试编写与实现物理分离
-- **运行时闸门**：自动验证，不依赖人工检查
-### vs. Kiro.dev
-[Kiro](https://kiro.dev/) 是 AWS 的代理式 IDE，用三阶段工作流（需求、设计、任务）。
-**Kiro 的局限**：
-- 规格与实现产物分开存储，追溯困难
-- 无强制角色隔离
-- 依赖特定 IDE 环境
-**DevBooks 解决方案**：
-- **变更包**：proposal/design/spec/plan/verification/evidence 集中存储，完整追溯
-- **强制角色隔离**：Test Owner 与 Coder 硬边界
-- **工具无关**：支持 Claude Code、Codex CLI、Cursor 等多种工具
-### vs. 无规格
-没有规格时，AI 从模糊提示生成代码，导致不可预测的输出、范围蔓延和"幻觉式完成"。
-**DevBooks 带来：**
-- 实现前商定规格，范围清晰可控
-- 质量闸门验证真实完成
-- 角色隔离防止自我验证
-- 每个变更的完整证据链
----
-## 核心原则
-| 原则 | 说明 |
-|------|------|
-| **协议优先** | 真理/变更/归档写进项目，不只存在聊天记录里 |
-| **锚点优先** | 完成由测试、静态分析、构建和证据定义 |
-| **角色隔离** | Test Owner 与 Coder 必须在独立对话中工作 |
-| **真理源分离** | `<truth-root>` 是只读真理；`<change-root>` 是临时工作区 |
-| **结构闸门** | 优先关注复杂度/耦合/测试质量，而非代理指标 |
+## 18 个 Skills
+| Skill | 阶段 | 作用 |
+|-------|------|------|
+| devbooks-router | 入口 | 工作流引导 |
+| devbooks-proposal-author | Proposal | 撰写提案 |
+| devbooks-proposal-challenger | Proposal | 质疑提案 |
+| devbooks-proposal-judge | Proposal | 裁决提案 |
+| devbooks-design-doc | Design | 编写设计文档 |
+| devbooks-spec-contract | Spec | 定义规格契约 |
+| devbooks-implementation-plan | Plan | 制定实现计划 |
+| devbooks-test-owner | Test | 编写验收测试 |
+| devbooks-test-reviewer | Review | 测试评审 |
+| devbooks-coder | Implement | 实现功能 |
+| devbooks-reviewer | Review | 代码评审 |
+| devbooks-archiver | Archive | 归档变更包 |
+| devbooks-docs-consistency | Quality | 文档一致性检查 |
+| devbooks-impact-analysis | Quality | 影响分析 |
+| devbooks-convergence-audit | Quality | 收敛性审计 |
+| devbooks-entropy-monitor | Quality | 熵度量监控 |
+| devbooks-brownfield-bootstrap | Init | 存量项目初始化 |
+| devbooks-delivery-workflow | Full | 完整闭环编排 |
+详见 [Skill 详解](docs/Skill详解.md)
 ---
-## 高级功能
-<details>
-<summary><strong>质量闸门</strong></summary>
-DevBooks 提供质量闸门拦截"伪完成"：
-| 闸门 | 触发模式 | 检查内容 |
-|------|----------|----------|
-| Green 证据检查 | archive, strict | `evidence/green-final/` 存在且非空 |
-| 任务完成检查 | strict | tasks.md 中所有任务完成或 SKIP-APPROVED |
-| 测试失败拦截 | archive, strict | Green 证据中无失败模式 |
-| P0 跳过审批 | strict | P0 任务跳过必须有审批记录 |
-| 角色边界检查 | apply --role | Coder 不能改 tests/，Test Owner 不能改 src/ |
-核心脚本（位于 `~/.claude/skills/devbooks-delivery-workflow/scripts/`）：
-- `change-check.sh --mode proposal|apply|archive|strict`
-- `handoff-check.sh` - 角色交接验证
-- `audit-scope.sh` - 全量审计扫描
-- `progress-dashboard.sh` - 进度可视化
-</details>
-<details>
-<summary><strong>原型模式</strong></summary>
-技术方案不确定时：
-1. 创建原型：`change-scaffold.sh <change-id> --prototype`
-2. Test Owner 用 `--prototype`：表征测试（无需 Red 基线）
-3. Coder 用 `--prototype`：输出到 `prototype/src/`（隔离主 src）
-4. 提升或丢弃：`prototype-promote.sh <change-id>`
-原型模式防止实验代码污染主源码树。
-脚本位于 `~/.claude/skills/devbooks-delivery-workflow/scripts/`。
-</details>
-<details>
-<summary><strong>熵度量监控</strong></summary>
-DevBooks 跟踪四维系统熵：
-| 指标 | 测量内容 |
-|------|----------|
-| 结构熵 | 模块复杂度和耦合 |
-| 变更熵 | 变动和波动模式 |
-| 测试熵 | 测试覆盖率和质量衰减 |
-| 依赖熵 | 外部依赖健康度 |
-用 `devbooks-entropy-monitor` 生成报告，识别重构机会。
-脚本（位于 `~/.claude/skills/devbooks-entropy-monitor/scripts/`）：`entropy-measure.sh`、`entropy-report.sh`
-</details>
-<details>
-<summary><strong>存量项目初始化</strong></summary>
-当 `<truth-root>` 为空时，使用 `devbooks-brownfield-bootstrap` 生成：
-- 项目画像和术语表
-- 从现有代码生成基线规格
-- 最小验证锚点
-- 模块依赖图
-- 技术债热点
-</details>
-<details>
-<summary><strong>MCP 自动检测</strong></summary>
-DevBooks Skills 支持 MCP（Model Context Protocol）优雅降级：在没有 MCP/CKB 的环境也能跑完整工作流；一旦检测到 CKB（Code Knowledge Base）可用，就自动启用图基能力，把"范围/引用/调用链"分析做得更准。
-### 它有什么用？
-- **影响分析更精确**：从"文件级猜测"升级到"符号级引用 + 调用图"，降低漏改风险
-- **审查更有重点**：自动拉取热点文件，优先关注高风险区域（技术债/高变动）
-- **大仓库更省心**：减少手动 Grep 的噪音与反复确认
-### MCP 状态与行为
-| MCP 状态 | 行为 |
-|----------|------|
-| CKB 可用 | 增强模式：符号级影响分析/引用查找/调用图/热点 |
-| CKB 不可用 | 基础模式：Grep + Glob 文本搜索（功能完整，精度降低） |
-### 自动检测
-- 需要 MCP 的 Skills 会先探测可用性（2s 超时）
-- 超时/失败 → 静默降级到基础模式，不阻塞执行
-- 无需手动选择"基础/增强"模式
-如需启用增强能力：按 `docs/推荐MCP.md` 配置 CKB，并手动生成 `index.scip`。
-</details>
-<details>
-<summary><strong>提案审查流程</strong></summary>
-严格提案审查使用独立对话的 Challenger 和 Judge：
+## 为什么选择 DevBooks？
-三个角色（必须独立对话）：
-1. **Author**：创建并捍卫提案（使用 `devbooks-proposal-author`）
-2. **Challenger**：质疑假设、发现缺口、识别风险（使用 `devbooks-proposal-challenger`）
-3. **Judge**：做最终决定、记录理由（使用 `devbooks-proposal-judge`）
+### 对比传统 AI 编程
-**重要**：三个角色必须在**独立对话**中工作，以避免角色混淆和自我验证。
+| 传统 AI 编程 | DevBooks |
+|-------------|----------|
+| AI 自评"已完成" | 测试通过 + 构建成功 |
+| 同一对话写测试又写代码 | 角色隔离，独立对话 |
+| 无验证闸门 | 多重质量闸门 |
+| 边修边破 | 稳定推进 |
+| 只支持 0→1 项目 | 支持存量项目 |
-决定结果：`Approved`、`Revise`、`Rejected`
+### 适用场景
-</details>
+- 新功能开发
+- 重大重构
+- Bug 修复
+- 存量项目接入
+- 需要高质量保证的项目
 ---
-## 从其他框架迁移
-DevBooks 提供迁移脚本帮助从其他规格驱动开发工具迁移。
-### 从 OpenSpec 迁移
-如果你当前使用 [OpenSpec](https://github.com/Fission-AI/OpenSpec)，有 `openspec/` 目录：
-```bash
-# 使用 CLI（推荐）
-dev-playbooks-cn migrate --from openspec
-# 先预览变更
-dev-playbooks-cn migrate --from openspec --dry-run
-# 迁移后保留原目录
-dev-playbooks-cn migrate --from openspec --keep-old
-```
+## 贡献
-**迁移内容：**
-- `openspec/specs/` → `dev-playbooks/specs/`
-- `openspec/changes/` → `dev-playbooks/changes/`
-- `openspec/project.md` → `dev-playbooks/project.md`
-- 所有路径引用自动更新
-### 从 GitHub spec-kit 迁移
-如果你使用 [GitHub spec-kit](https://github.com/github/spec-kit)，有 `specs/` 和 `memory/` 目录：
-```bash
-# 使用 CLI（推荐）
-dev-playbooks-cn migrate --from speckit
-# 先预览变更
-dev-playbooks-cn migrate --from speckit --dry-run
-# 迁移后保留原目录
-dev-playbooks-cn migrate --from speckit --keep-old
-```
-**映射规则：**
-| Spec-Kit | DevBooks |
-|----------|----------|
-| `memory/constitution.md` | `dev-playbooks/specs/_meta/constitution.md` |
-| `specs/[feature]/spec.md` | `changes/[feature]/design.md` |
-| `specs/[feature]/plan.md` | `changes/[feature]/proposal.md` |
-| `specs/[feature]/tasks.md` | `changes/[feature]/tasks.md` |
-| `specs/[feature]/quickstart.md` | `changes/[feature]/verification.md` |
-| `specs/[feature]/contracts/` | `changes/[feature]/specs/` |
-### 迁移功能
-两个迁移脚本都支持：
-- **幂等执行**：可安全多次运行
-- **断点续传**：中断后可从断点恢复
-- **试运行模式**：预览变更再执行
-- **自动备份**：原文件备份到 `.devbooks/backup/`
-- **引用更新**：文档中的路径引用自动更新
-### 迁移后步骤
-迁移后：
-1. 运行 `dev-playbooks-cn init` 设置 DevBooks Skills
-2. 检查 `dev-playbooks/` 中的迁移文件
-3. 更新 `verification.md` 文件的 AC 映射
-4. 如需基线规格，运行 `devbooks-brownfield-bootstrap`
+欢迎贡献！请查看 [贡献指南](CONTRIBUTING.md)。
 ---
-## 目录结构
+## 许可证
-```
-dev-playbooks/
-├── README.md              # 本文档
-├── constitution.md        # 项目宪法（GIP 原则）
-├── project.md             # 项目上下文（技术栈/约定）
-├── specs/                 # 当前规格（只读真理）
-│   ├── _meta/             # 元数据（术语表、项目画像）
-│   └── architecture/      # 架构规格（fitness-rules）
-├── changes/               # 变更包（工作区）
-├── scripts/               # 辅助脚本
-└── docs/                  # 文档
-    ├── workflow-diagram.svg   # 工作流程图
-    ├── 推荐MCP.md             # MCP 配置建议
-    └── DevBooks配置指南.md    # 配置指南
-```
+MIT License - 详见 [LICENSE](LICENSE)
 ---
-## 文档
+## 联系方式
-- [工作流程图](docs/workflow-diagram.svg)
-- [MCP 配置建议](docs/推荐MCP.md)
-- [配置指南](docs/DevBooks配置指南.md)
+- GitHub: https://github.com/Darkbluelr/dev-playbooks-cn
+- npm: https://www.npmjs.com/package/dev-playbooks-cn
+- Issues: https://github.com/Darkbluelr/dev-playbooks-cn/issues
 ---
-## License
-MIT
+**记住**：DevBooks 不是工具，而是一套工作流程。遵循约束，质量自然提升。

package/package.json CHANGED Viewed

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

package/skills/devbooks-archiver/SKILL.md CHANGED Viewed

@@ -65,12 +65,14 @@ proposal → design → test-owner(P1) → coder → test-owner(P2) → code-rev
 | 阶段 | 职责 | 说明 |
 |------|------|------|
-| 1 | 自动回写检测与处理 | 检测 deviation-log.md，自动回写设计文档 |
+| 1 | 设计回写（Design Backport） | 检测实现过程中的新约束/冲突/缺口，回写到 design.md |
 | 2 | 规格合并 | 将 specs/contracts 合并到 truth-root |
 | 3 | 架构合并 | 将 design.md 的 Architecture Impact 合并到 c4.md |
 | 4 | 文档同步检查 | 检查 design.md 的 Documentation Impact 是否已处理 |
 | 5 | 变更包归档移动 | 将变更包移动到 `<change-root>/archive/` |
+**注意**：Archiver 现在承担了原 `devbooks-design-backport` skill 的职责，作为归档闭环的一部分自动执行。
 ---
 ## 前置：配置发现（协议无关）

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

@@ -1,105 +0,0 @@
----
-name: devbooks-design-backport
-description: devbooks-design-backport：把实现过程中发现的新约束/冲突/缺口回写到 design.md（保持设计为黄金真理），并标注决策与影响。用户说"回写设计/补充设计文档/Design Backport/设计与实现不一致/需要澄清约束"等时使用。
-recommended_experts: ["System Architect"]
-allowed-tools:
-  - Glob
-  - Grep
-  - Read
-  - Write
-  - Edit
----
-# DevBooks：回写设计文档（Design Backport）
-## 工作流位置感知（Workflow Position Awareness）
-> **核心原则**：Design Backport 现在**主要由 Archiver 在归档阶段自动调用**，用户通常不需要手动调用。
-### 我在整体工作流中的位置
-```
-proposal → design → test-owner → coder → test-owner(验证) → code-review → [Archive/Archiver]
-                                    ↓                                              ↓
-                             记录偏离到 deviation-log.md               自动调用 design-backport
-```
-### 设计决策：自动回写
-**旧流程**（需手动判断）：
-```
-coder 有偏离 → 用户手动调用 design-backport → 再归档
-```
-**新流程**（自动处理）：
-```
-coder 有偏离 → 归档时 archiver 自动检测并回写 → 归档
-```
-### 何时仍需手动调用
-| 场景 | 是否需要手动调用 |
-|------|------------------|
-| 正常流程（偏离记录在 deviation-log.md） | ❌ 归档时自动处理 |
-| 需要立即回写（不等归档） | ✅ 手动调用 |
-| 设计与实现严重冲突需要决策 | ✅ 手动调用并讨论 |
----
-## 前置：配置发现（协议无关）
-- `<truth-root>`：当前真理目录根
-- `<change-root>`：变更包目录根
-执行前**必须**按以下顺序查找配置（找到后停止）：
-1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
-2. `dev-playbooks/project.md`（如存在）→ Dev-Playbooks 协议，使用默认映射
-3. `project.md`（如存在）→ template 协议，使用默认映射
-4. 若仍无法确定 → **停止并询问用户**
-**关键约束**：
-- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
-- 禁止猜测目录根
-- 禁止跳过规则文档阅读
-## 执行方式
-1) 先阅读并遵守：`~/.claude/skills/_shared/references/AI行为规范.md`（可验证性 + 结构质量守门）。
-2) 严格按完整提示词执行：`references/回写设计文档提示词.md`。
----
-## 上下文感知
-本 Skill 在执行前自动检测上下文，识别需要回写的内容。
-检测规则参考：`skills/_shared/上下文检测模板.md`
-### 检测流程
-1. 检测 `design.md` 是否存在
-2. 检测实现过程中是否有新发现（冲突/约束/缺口）
-3. 对比设计与实现的差异
-### 本 Skill 支持的模式
-| 模式 | 触发条件 | 行为 |
-|------|----------|------|
-| **冲突回写** | 发现设计与实现冲突 | 记录冲突点和解决方案 |
-| **约束回写** | 发现新的实现约束 | 补充约束条件到设计 |
-| **缺口回写** | 发现设计未覆盖的场景 | 补充遗漏的设计决策 |
-### 检测输出示例
-```
-检测结果：
-- design.md：存在
-- 发现内容：2 个新约束，1 个设计冲突
-- 运行模式：约束回写 + 冲突回写
-```
----
-## MCP 说明
-本 Skill 不依赖 MCP 服务，无需运行时检测。

package/skills/devbooks-design-backport/references//345/233/236/345/206/231/350/256/276/350/256/241/346/226/207/346/241/243/346/217/220/347/244/272/350/257/215.md DELETED Viewed

@@ -1,196 +0,0 @@
-# 回写设计文档提示词
-> **角色设定**：你是设计演进领域的**最强大脑**——融合了 Michael Nygard（架构决策记录）、Martin Fowler（演进式设计）、Kent Beck（渐进式改进）的智慧。你的设计同步必须达到这些大师级专家的水准。
-最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
-# 提示词：当编码计划超出设计文档范围时，回写设计文档（Design Backport）
-> 使用场景：你发现“编码计划（tasks/plan）”中出现了“设计文档（design/spec）”未包含的新约束/新概念/新验收口径，导致“计划驱动实现”与“设计驱动验收”出现漂移。
-产物落点（目录约定，协议无关）：
-- 设计文档通常位于：`<change-root>/<change-id>/design.md`
-- 编码计划通常位于：`<change-root>/<change-id>/tasks.md`
-- 规格 delta 通常位于：`<change-root>/<change-id>/specs/<capability>/spec.md`
-- 当前真理源位于：`<truth-root>/`（不要试图回写/篡改历史归档来“统一口径”；用新的变更包更新当前真理）
-> 目标：把“应该成为设计的一部分”的内容回写进设计文档，降低后续测试、实现、验收的分歧。
----
-## 可回写到设计文档的内容（What can be backported）
-只有当计划内容满足以下任一条件时，才适合回写到设计文档（属于 **Design-level**）：
-1. **对外语义或用户可感知行为**
-- 新增/修改关键用户流程（例如显式状态机、异步会话、可取消/可超时）
-- 对外契约（API 输入输出形状、错误语义、必填字段、兼容窗口）
-2. **系统级不可变约束（Invariants / Red Lines）**
-- 成本/资源上限（例如禁止 N² LLM 调用、`max_llm_calls` 硬上限、预算触发降级）
-- 可靠性/安全红线（例如多租户隔离默认开启、外部不可信边界、注入默认隔离）
-3. **核心数据契约与演进策略（Contracts & Evolution）**
-- `schema_version`、事件信封必需字段、幂等键原则、兼容策略（DLQ/迁移/回放）
-- “什么必须能回放/可审计/可追溯”的最低标准
-4. **跨阶段治理策略（Cross-cutting Concerns）**
-- 观测指标、SLO/KPI、告警与运营策略
-- 生命周期/保留策略（Valid/Quarantine/Garbage 的策略与目的）
-- 灰度/回滚路径与功能开关（Feature Flags）
-5. **关键取舍与决策（Decisions）**
-- 选择 A 而非 B 的原因、替代方案、风险、降级策略
-- 新增/修改“非目标（Non-goals）”或“开放问题（Open Questions）”
----
-## 不应回写到设计文档的内容（What must NOT be backported）
-以下内容属于 **Implementation-level**，不应直接写入设计文档（除非你要把它升级为正式设计决策）：
-- 具体文件路径、类名/函数名、表名/字段名的实现细节（除非它是稳定的架构边界且必须对齐）
-- PR 切分建议、任务执行顺序、脚本/命令的临时实现步骤
-- 过细的算法伪代码（可回写“输入/输出/不变量/复杂度上限/降级策略”，避免把代码写进设计）
-- 仅为某次实现方便的技巧性约束（没有长期价值或不可被验证）
----
-## 冲突处理规则（Plan vs Design）
-- **设计文档优先（Design is the Golden Truth）**：若编码计划与设计冲突，不要直接用计划覆盖设计。
-- 允许两种处理方式：
-1) **提案式回写**：把计划内容作为 “Proposed Design Change（提案）” 写入设计文档，并明确需要决策/确认；
-2) **降级/延期**：将计划条目标记为 `DEFERRED/UNSCOPED`，直到设计明确后再进入实施。
-- 回写时必须显式标注：这是“新增设计决策/补充约束”，并说明原因与影响范围。
----
-## 输出要求（你要产出的东西）
-1. **对比清单**：列出“计划超出设计”的候选条目（按 Plan ID 分组），并给出分类：`Design-level / Implementation-level / Out-of-scope`。
-2. **设计回写补丁**：将所有 `Design-level` 内容以最小改动写回设计文档，放到最合适的章节（例如：非目标/设计原则/风险与降级/契约/里程碑/关键决策汇总）。
-3. **追溯更新**：对每条回写的设计内容，明确其验收方式（A/B/C）与验收锚点，并要求同步更新：
-   - 追溯矩阵（优先更新本次变更的 `<change-root>/<change-id>/verification.md`；如需对外公开再同步到 `docs/`）
-   - 非机器验收清单（优先更新 `<change-root>/<change-id>/verification.md` 中的 `MANUAL-*` 条目；如需对外公开再同步到 `docs/`）
-   - 如需新增/更新自动化锚点：列出对应的测试/静态检查建议（tests/命令/marker）
----
-## 可直接复制使用的提示词（Prompt）
-```text
-你是“设计文档编辑器（Design Doc Editor）”。你的目标是把编码计划中超出设计文档范围、但属于设计层的内容，回写到设计文档中，使其成为可追溯、可验收的设计约束。
-输入：
-- 设计文档：`<change-root>/<change-id>/design.md`（或你提供的等价路径）
-- 编码计划：`<change-root>/<change-id>/tasks.md`（或你提供的等价路径）
-任务：
-1) 通读编码计划，找出所有“设计文档没有覆盖或表述不足”的条目（按 MP/章节聚类）。
-2) 对每条候选内容做分类：
-- Design-level（应回写到设计）：影响对外语义/用户流程/系统红线/数据契约/演进策略/运维治理/关键决策
-- Implementation-level（不回写）：实现细节、文件路径、PR 切分、执行顺序、伪代码细节
-- Out-of-scope（不回写且应延期）：不在本次范围或属于未来阶段但未被设计确认
-3) 仅对 Design-level 内容，回写到设计文档：
-- 放到最合适的现有章节；必要时新增小节，但不要重构整篇文档
-- 以“设计约束/决策”的口吻描述，避免实现细节
-- 如与原设计冲突：不要直接改写原结论；新增“Proposed Design Change/开放问题”并说明原因、影响、需要决策点
-- 更新设计文档头部的“更新时间”（如存在）
-4) 输出：
-- A) 候选清单与分类结果（按 Plan ID）
-- B) 对设计文档的最小补丁（只包含新增/修改的段落）
-- C) 追溯与锚点更新清单（按优先级排序）：
-  - 需要新增/更新哪些 tests/静态检查（A 类锚点）
-  - 需要新增/更新哪些人工/混合验收条目（B/C 类锚点，优先落到 `<change-root>/<change-id>/verification.md`）
-  - 需要如何更新追溯矩阵（优先落到 `<change-root>/<change-id>/verification.md`）
-限制：
-- 不要把文件路径、类名/函数名、DB 表名等实现细节写进设计文档（除非它是稳定架构边界且必须暴露）
-- 不要把大段伪代码写进设计文档；可以写不变量、复杂度上限、降级策略
-- 语言保持与设计文档一致（中文为主，必要时英文术语括号解释）
-```