dev-playbooks-cn 4.0.1 → 4.0.3

package/README.md

@@ -3,83 +3,165 @@
 [![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)
 
-## v4.0 新特性
+**让 AI 写代码从"说完成就完成"变成"有证据才算完成"。**
 
-- **完成合同（Completion Contract）**：把用户意图编译为机读合同，锁定"义务→检查→证据"链条，防止 AI 偷偷降低交付标准
-- **7 道闸门（G0-G6）**：从输入就绪到归档裁决，全链路可裁判检查点，任何一道失败都会阻断
-- **上游 SSOT 支持**：自动索引项目已有的需求文档，提取可裁判约束；没有需求文档时自动创建最小 SSOT 包
-- **Knife 切片协议**：大需求强制切片，每片有复杂度预算，超预算必须再切
-- **Void 研究协议**：高熵问题先研究再决策，产出可追溯的决策记录（ADR）
-- **证据新鲜度校验**：证据文件必须比被覆盖的交付物更新，防止用旧证据糊弄
-- **弱连接义务**：文档、配置、发布说明等"代码外契约"也被编译为可裁判义务
+DevBooks 是一套面向 AI 的工程协议，通过上游真理源（SSOT）、可执行闸门、证据闭环，把 AI 编程从"对话式猜测"升级为"可审计的工程交付"。
 
 ---
 
-## 你用 AI 写代码时，是不是经常遇到这些问题？
+## 核心理念
 
-**"说改好了，结果没改好"**
-AI 说"已修复"，你问它确定吗，它说"确定"。上线后炸了。回头看，它写的测试恰好能通过它自己的 Bug。
+软件工程的本质是**在不可靠的组件之上构建可靠的系统**。传统工程用 RAID 对抗不可靠的硬盘，用 TCP 重传对抗不可靠的网络，用 Code Review 对抗不可靠的人类程序员。AI 工程同样需要用**闸门与证据闭环**约束不可靠的 LLM 输出。
 
-**"改着改着就忘了之前说的"**
-对话开头你说"不要改 X 模块"，三十轮对话后它把 X 模块改了。你提醒它，它道歉，然后下一轮又改了。
+DevBooks 不是提示词优化，而是工程约束。
 
-**"需求大了就乱套"**
-小功能还行，稍微复杂一点就开始胡说八道。改了 A 忘了 B，修了 B 又破坏了 C。
+---
+
+## 上游真理源（SSOT）：全开发周期的单一权威
 
-**"不知道它到底做没做完"**
-它说"完成了"，但你不敢信。你让它再检查一遍，它说"检查过了，没问题"。你还是不敢信。
+DevBooks 的核心是**上游真理源（Single Source of Truth）**——所有关键知识落盘并版本化，跨对话、跨变更稳定。
+
+```
+你的需求文档（如果有）
+    ↓ 提取约束，建立索引
+specs/（术语、边界、决策、场景）← 跨变更稳定的"项目记忆"
+    ↓ 派生变更包
+changes/<id>/（提案、设计、任务、证据）
+    ↓ 归档回写
+specs/（更新真理）
+```
 
-**"每次都要从头教"**
-上次对话里建立的约定，这次对话全忘了。项目的术语、边界、约束，每次都要重新解释。
+**SSOT 解决的问题：**
 
-**"改完不知道改了什么"**
-它改了一堆文件，你问它改了什么，它给你一个摘要。但这个摘要对不对？你不知道。
+| 问题 | 根因 | SSOT 如何解决 |
+|-----|------|--------------|
+| 每次都要从头教 | 对话是临时的，知识没有持久化 | 术语、边界、约束写在文件里，不依赖对话记忆 |
+| 改着改着就忘了之前说的 | 上下文窗口有限，早期信息被挤出去 | 真理工件持久化，强制注入关键约束 |
+| 不知道改了什么 | 没有可审计的变更记录 | 每次变更有完整记录——提案、设计、任务、证据 |
 
 ---
 
-## 这些不是 AI 不够聪明，是结构性问题
+## 账本与索引：持续追踪完成情况
+
+DevBooks 通过**完成合同（Completion Contract）**和**需求索引（Requirements Index）**持续追踪交付状态。
 
-提示词写得再好也没用。这是 LLM 的工作方式决定的：
+### 完成合同：把"我要什么"编译成机器可检查的清单
 
-| 问题 | 根本原因 |
-|-----|---------|
-| 说改好了没改好 | 自己写测试验证自己的代码，当然能过 |
-| 改着改着就忘了 | 上下文窗口有限，早期信息被挤出去 |
-| 需求大了就乱 | 复杂度超过单次对话能处理的极限 |
-| 不知道做没做完 | 没有客观证据，只有它的口头声明 |
-| 每次从头教 | 对话是临时的，知识没有持久化 |
-| 不知道改了什么 | 没有可审计的变更记录 |
+```yaml
+obligations:
+  - id: O-001
+    describes: "用户可以通过邮箱登录"
+    severity: must
+checks:
+  - id: C-001
+    type: test
+    covers: [O-001]
+    artifacts: ["evidence/gates/login-test.log"]
+```
+
+不是"大概做完了"，而是"这 5 条义务都有证据"。
+
+### 需求索引：把上游文档变成可追溯的义务清单
+
+```yaml
+set_id: ARCH-P3
+source_ref: "truth://specs/architecture/design.md"
+requirements:
+  - id: R-001
+    severity: must
+    statement: "所有 API 必须支持版本化"
+  - id: R-002
+    severity: should
+    statement: "响应时间 < 200ms"
+```
+
+当变更包宣称"已完成上游任务"时，系统可以裁判这个宣称——不是口头确认，而是机器校验。
 
 ---
 
-## DevBooks：用工程约束解决这些问题
+## Knife 切片协议：把大需求变成可执行队列
+
+大需求直接交给 AI 会怎样？改了 A 忘了 B，修了 B 又破坏了 C。
+
+Knife 协议通过**复杂度预算**和**拓扑排序**，把 Epic 切成可独立验证的原子变更包队列。
+
+### 切片算法
+
+```
+Score = w₁·Files + w₂·Modules + w₃·RiskFlags + w₄·HotspotWeight
+```
+
+| 信号 | 权重 | 说明 |
+|-----|------|-----|
+| files_touched | 1.0 | 每个文件计 1 分 |
+| modules_touched | 5.0 | 跨模块风险高 |
+| risk_flags | 10.0 | 每个风险旗标计 10 分 |
+| hotspot_weight | 2.0 | 高 churn 区域加权 |
+
+**超预算必须再切**——禁止"硬做"。
+
+### 切片不变量
+
+1. **MECE 覆盖**：所有切片的验收点并集等于 Epic 的完整验收点集合，且不重叠
+2. **可独立 Green**：每个切片至少一个确定性验证锚点，不允许"中间态不可编译"
+3. **拓扑可排序**：依赖图必须无环，执行顺序必须为拓扑序
+4. **预算熔断**：超预算必须递归切分，或回流补信息
+
+### 并行执行调度
+
+当 Knife Plan 包含多个 Slice 时，可以生成并行执行清单：
 
 ```bash
-npm install -g dev-playbooks-cn
-dev-playbooks-cn init
-dev-playbooks-cn delivery
+knife-parallel-schedule.sh <epic-id> --format md --out parallel-schedule.md
 ```
 
-| 问题 | DevBooks 怎么解决 |
-|-----|------------------|
-| 自己验证自己 | **角色隔离**：写测试的 Agent 和写代码的 Agent 必须分开，互相看不到对方的思路 |
-| 上下文遗忘 | **真理落盘**：术语、边界、约束写在文件里，不依赖对话记忆 |
-| 需求太大 | **切片预算**：大需求必须切成小块，每块有复杂度上限，超了就再切 |
-| 口头完成 | **证据定义完成**：测试日志、构建输出必须真的存在于磁盘上 |
-| 每次从头教 | **SSOT（单一真理源）**：项目知识持久化在 specs/，跨对话、跨变更稳定 |
-| 不知道改了什么 | **变更包**：每次变更有完整记录——提案、设计、任务、证据 |
+输出内容：
+- **最大并行度**：可同时启动的最大 Agent 数量
+- **分层执行清单**：Layer 0（无依赖）→ Layer 1 → Layer N
+- **关键路径**：串行依赖深度
+- **启动命令模板**：每个 Slice 的 Agent 启动命令
+
+由于当前 AI 编程工具不支持二级子代理调用，Epic 拆分后需要人类协调多个独立 Agent 并行完成。
+
+---
+
+## 7 道闸门：全链路可裁判检查点
+
+| 闸门 | 检查什么 | 失败后果 |
+|-----|---------|---------|
+| G0 | 输入就绪了吗？基线工件齐全吗？ | 回流到 Bootstrap |
+| G1 | 该有的文件都有吗？结构正确吗？ | 阻断 |
+| G2 | 任务都完成了吗？绿证据存在吗？ | 阻断 |
+| G3 | 切片正确吗？锚点齐全吗？（大需求） | 回流到 Knife |
+| G4 | 文档同步了吗？扩展包完整吗？ | 阻断 |
+| G5 | 风险覆盖了吗？回滚策略有吗？（高风险） | 阻断 |
+| G6 | 证据完整吗？合同满足吗？可以归档吗？ | 阻断 |
+
+任何一道失败，流程阻断。不是警告，是阻断。
 
 ---
 
-## 它是怎么工作的
+## 角色隔离：防止 AI 自己验证自己
+
+| 角色 | 职责 | 硬约束 |
+|-----|------|-------|
+| Test Owner | 从设计推导验收测试 | 禁止看实现代码 |
+| Coder | 按任务实现功能 | 禁止修改 tests/ |
+| Reviewer | 审查可读性与一致性 | 不改测试不改设计 |
+
+Test Owner 和 Coder 必须在**不同上下文**执行——不是"不同人"，而是"不同对话/不同实例"。两者之间只能通过**落盘工件**交接。
+
+---
 
-你只需要记住一个命令：
+## 快速开始
 
 ```bash
+npm install -g dev-playbooks-cn
+dev-playbooks-cn init
 dev-playbooks-cn delivery
 ```
 
-系统会问你几个问题，然后生成一份 `RUNBOOK.md`——这是你这次任务的操作手册。照着做就行。
+你只需要记住一个命令：`delivery`。系统会问你几个问题，然后生成一份 `RUNBOOK.md`——这是你这次任务的操作手册。照着做就行。
 
 ```
 你的需求
@@ -99,66 +181,41 @@ Delivery（判断类型、生成 RUNBOOK）
 
 ---
 
-## 核心机制
-
-**真理源（SSOT）**
-
-```
-你的需求文档（如果有）
-    ↓ 提取约束
-specs/（术语、边界、决策）← 跨变更稳定的"项目记忆"
-    ↓
-changes/<id>/（本次变更的提案、设计、任务、证据）
-    ↓ 归档
-specs/（更新真理）
-```
-
-如果你没有需求文档，DevBooks 会帮你创建一个最小的。这反而是好事——逼你把模糊的想法写清楚。
-
-**完成合同**
-
-把"我要什么"编译成机器可检查的清单：
-- 5 条义务
-- 每条有对应的检查项
-- 每条有对应的证据文件
-
-不是"大概做完了"，而是"这 5 条都有证据"。
-
-**7 道闸门（G0-G6）**
-
-| 闸门 | 检查什么 |
-|-----|---------|
-| G0 | 输入就绪了吗？需求清楚吗？ |
-| G1 | 该有的文件都有吗？ |
-| G2 | 任务都完成了吗？ |
-| G3 | 切片正确吗？（大需求） |
-| G4 | 文档同步了吗？ |
-| G5 | 风险覆盖了吗？（高风险变更） |
-| G6 | 证据完整吗？可以归档吗？ |
-
-任何一道失败，流程阻断。不是警告，是阻断。
-
----
-
 ## 目录结构
 
 ```
 project/
-├── .devbooks/config.yaml     # 配置
+├── .devbooks/config.yaml        # 配置入口
 └── dev-playbooks/
-    ├── constitution.md       # 硬约束（不可绕过的规则）
-    ├── specs/                # 真理源（跨变更稳定）
-    └── changes/              # 变更包（每次变更一个目录）
+    ├── constitution.md          # 硬约束（不可绕过的规则）
+    ├── specs/                   # 真理源（SSOT）
+    │   ├── _meta/
+    │   │   ├── glossary.md      # 统一语言
+    │   │   ├── boundaries.md    # 模块边界
+    │   │   ├── capabilities.yaml # 能力注册表
+    │   │   └── epics/           # Knife 切片计划
+    │   └── ...
+    └── changes/                 # 变更包
         └── <change-id>/
-            ├── proposal.md   # 为什么做、做什么
-            ├── design.md     # 怎么做、验收标准
-            ├── tasks.md      # 拆成可执行的步骤
-            ├── verification.md # 怎么证明做对了
-            └── evidence/     # 测试日志、构建输出
+            ├── proposal.md      # 为什么做、做什么
+            ├── design.md        # 怎么做、验收标准
+            ├── tasks.md         # 拆成可执行的步骤
+            ├── completion.contract.yaml  # 完成合同
+            ├── verification.md  # 怎么证明做对了
+            └── evidence/        # 测试日志、构建输出
 ```
 
 ---
 
+## 适用场景
+
+- **存量项目接入**：自动索引现有文档，提取可裁判约束，建立最小 SSOT 包
+- **新项目启动**：引导补齐术语、边界、场景、决策，建立基线
+- **日常变更**：最小充分闭环，可复现验证锚点 + 证据归档
+- **大型重构**：Knife 切片 + 迁移范式（Expand-Contract / Strangler Fig / Branch by Abstraction）
+
+---
+
 ## 下一步
 
 - [快速开始](docs/使用指南.md)

package/package.json

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

package/skills/Skills/344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -115,6 +115,30 @@ Skills 引用的共享资源（如 `_shared/references/`）位于 skills 全局
   最后给出下一步最短闭环路由 + 升级条件。
   ```
 
+### 并行执行调度（多 Agent 并行）
+
+当 Knife Plan 包含多个 Slice 时，可以生成并行执行清单，让人类协调多个独立 Agent 并行完成：
+
+```bash
+# 生成并行调度清单
+knife-parallel-schedule.sh <epic-id> --format md --out parallel-schedule.md
+```
+
+**输出内容**：
+1. **最大并行度**：可同时启动的最大 Agent 数量
+2. **分层执行清单**：Layer 0（无依赖）→ Layer 1（依赖 Layer 0）→ ...
+3. **关键路径**：串行依赖深度
+4. **启动命令模板**：每个 Slice 的 Agent 启动命令
+5. **溯源信息**：Epic ID、Plan ID、Plan Revision
+
+**使用场景**：
+由于当前 AI 编程工具不支持二级子代理调用，Epic 拆分后需要人类协调多个独立 Agent 并行完成：
+1. 运行 `knife-parallel-schedule.sh` 生成清单
+2. 根据清单的 Layer 0 启动多个独立 Agent
+3. 等待 Layer 0 全部完成后，启动 Layer 1
+4. 重复直到所有 Layer 完成
+5. 运行 `requirements-ledger-derive.sh` 更新账本
+
 ---
 
 ## `devbooks-proposal-author`（Proposal Author）

package/skills/devbooks-delivery-workflow/scripts/knife-parallel-schedule.sh

@@ -0,0 +1,458 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# =============================================================================
+# knife-parallel-schedule.sh
+# =============================================================================
+# 从 Knife Plan 生成并行执行调度清单
+#
+# 功能：
+#   1. 解析 Knife Plan 的 slices[] 依赖图
+#   2. 计算最大并行度（DAG 宽度）
+#   3. 生成分层执行清单（Layer 0, 1, 2, ...）
+#   4. 识别关键路径
+#   5. 输出人类可读的并行执行指南
+#
+# 用途：
+#   Epic 拆分后，用户可以根据此清单开启多个独立 Agent 并行完成变更包
+# =============================================================================
+
+usage() {
+  cat <<'EOF' >&2
+usage: knife-parallel-schedule.sh <epic-id> [options]
+
+从 Knife Plan 生成并行执行调度清单。
+
+Options:
+  --project-root <dir>    项目根目录 (default: pwd)
+  --truth-root <dir>      真理根目录 (default: specs)
+  --out <path>            输出文件路径 (default: stdout)
+  --format <md|json>      输出格式 (default: md)
+  -h, --help              显示帮助
+
+输出内容：
+  - 最大并行度
+  - 分层执行清单（哪些 Slice 可以同时开始）
+  - 关键路径
+  - 每个 Slice 的启动命令模板
+  - 溯源信息
+
+Exit codes:
+  0 - 成功
+  1 - Knife Plan 不存在或解析失败
+  2 - 用法错误
+EOF
+}
+
+errorf() {
+  printf 'ERROR: %s\n' "$*" >&2
+}
+
+infof() {
+  printf 'INFO: %s\n' "$*" >&2
+}
+
+# =============================================================================
+# 参数解析
+# =============================================================================
+
+if [[ $# -eq 0 ]]; then
+  usage
+  exit 2
+fi
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+epic_id="$1"
+shift
+
+project_root="${DEVBOOKS_PROJECT_ROOT:-$(pwd)}"
+truth_root="${DEVBOOKS_TRUTH_ROOT:-specs}"
+out_path=""
+format="md"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --project-root)
+      project_root="${2:-}"
+      shift 2
+      ;;
+    --truth-root)
+      truth_root="${2:-}"
+      shift 2
+      ;;
+    --out)
+      out_path="${2:-}"
+      shift 2
+      ;;
+    --format)
+      format="${2:-}"
+      shift 2
+      ;;
+    *)
+      errorf "unknown option: $1"
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+if [[ -z "$epic_id" || "$epic_id" == "-"* ]]; then
+  errorf "invalid epic-id: '$epic_id'"
+  exit 2
+fi
+
+case "$format" in
+  md|json) ;;
+  *)
+    errorf "invalid --format: $format (must be md or json)"
+    exit 2
+    ;;
+esac
+
+project_root="${project_root%/}"
+truth_root="${truth_root%/}"
+
+if [[ "$truth_root" = /* ]]; then
+  truth_dir="$truth_root"
+else
+  truth_dir="${project_root}/${truth_root}"
+fi
+
+# =============================================================================
+# 查找 Knife Plan
+# =============================================================================
+
+knife_plan_dir="${truth_dir}/_meta/epics/${epic_id}"
+knife_plan_file=""
+
+if [[ -f "${knife_plan_dir}/knife-plan.yaml" ]]; then
+  knife_plan_file="${knife_plan_dir}/knife-plan.yaml"
+elif [[ -f "${knife_plan_dir}/knife-plan.json" ]]; then
+  knife_plan_file="${knife_plan_dir}/knife-plan.json"
+else
+  errorf "Knife Plan not found at: ${knife_plan_dir}/knife-plan.(yaml|json)"
+  exit 1
+fi
+
+infof "Found Knife Plan: $knife_plan_file"
+
+# =============================================================================
+# 解析 Knife Plan（使用 yq 或 jq）
+# =============================================================================
+
+# 检查工具可用性
+if command -v yq &>/dev/null; then
+  YAML_TOOL="yq"
+elif command -v python3 &>/dev/null; then
+  YAML_TOOL="python"
+else
+  errorf "需要 yq 或 python3 来解析 YAML"
+  exit 1
+fi
+
+# 提取 slices 数据
+extract_slices() {
+  local file="$1"
+
+  if [[ "$file" == *.json ]]; then
+    jq -r '.slices // []' "$file"
+  elif [[ "$YAML_TOOL" == "yq" ]]; then
+    yq -o=json '.slices // []' "$file"
+  else
+    python3 -c "
+import yaml
+import json
+import sys
+
+with open('$file', 'r') as f:
+    data = yaml.safe_load(f)
+    slices = data.get('slices', [])
+    print(json.dumps(slices))
+"
+  fi
+}
+
+# 提取元数据
+extract_metadata() {
+  local file="$1"
+
+  if [[ "$file" == *.json ]]; then
+    jq -r '{epic_id, plan_id, plan_revision, risk_level, change_type, ac_ids}' "$file"
+  elif [[ "$YAML_TOOL" == "yq" ]]; then
+    yq -o=json '{epic_id: .epic_id, plan_id: .plan_id, plan_revision: .plan_revision, risk_level: .risk_level, change_type: .change_type, ac_ids: .ac_ids}' "$file"
+  else
+    python3 -c "
+import yaml
+import json
+import sys
+
+with open('$file', 'r') as f:
+    data = yaml.safe_load(f)
+    meta = {
+        'epic_id': data.get('epic_id'),
+        'plan_id': data.get('plan_id'),
+        'plan_revision': data.get('plan_revision'),
+        'risk_level': data.get('risk_level'),
+        'change_type': data.get('change_type'),
+        'ac_ids': data.get('ac_ids', [])
+    }
+    print(json.dumps(meta))
+"
+  fi
+}
+
+slices_json=$(extract_slices "$knife_plan_file")
+metadata_json=$(extract_metadata "$knife_plan_file")
+
+# 验证 slices 不为空
+slice_count=$(echo "$slices_json" | jq 'length')
+if [[ "$slice_count" -eq 0 ]]; then
+  errorf "Knife Plan 中没有定义 slices"
+  exit 1
+fi
+
+infof "Found $slice_count slices"
+
+# =============================================================================
+# 拓扑排序与分层计算
+# =============================================================================
+
+# 使用 jq 进行拓扑排序和分层计算
+schedule_json=$(echo "$slices_json" | jq '
+# 构建 slice_id -> index 映射
+. as $slices |
+reduce range(length) as $i ({}; . + {($slices[$i].slice_id): $i}) as $id_to_idx |
+
+# 计算每个节点的入度
+reduce .[] as $slice (
+  (reduce .[] as $s ({}; . + {($s.slice_id): 0}));
+  reduce ($slice.depends_on // [])[] as $dep (.; .[$slice.slice_id] = (.[$slice.slice_id] // 0) + 1)
+) as $in_degree |
+
+# Kahn 算法进行拓扑排序并分层
+{
+  layers: [],
+  remaining: [.[] | .slice_id],
+  in_degree: $in_degree,
+  slices: $slices
+} |
+until((.remaining | length) == 0;
+  # 找出当前入度为 0 的节点
+  .remaining as $rem |
+  .in_degree as $deg |
+  [$rem[] | select($deg[.] == 0)] as $current_layer |
+
+  if ($current_layer | length) == 0 then
+    # 有环，无法继续
+    .remaining = []
+  else
+    # 更新入度
+    reduce ($slices[] | select([.slice_id] | inside($current_layer) | not)) as $s (
+      .in_degree;
+      reduce ($s.depends_on // [])[] as $dep (
+        .;
+        if ($current_layer | index($dep)) then
+          .[$s.slice_id] = (.[$s.slice_id] - 1)
+        else . end
+      )
+    ) as $new_deg |
+
+    .layers += [$current_layer] |
+    .remaining = [.remaining[] | select(. as $id | $current_layer | index($id) | not)] |
+    .in_degree = $new_deg
+  end
+) |
+
+# 计算关键路径（最长路径）
+.layers as $layers |
+($layers | length) as $depth |
+
+# 构建 slice 详情
+{
+  max_parallelism: ($layers | map(length) | max),
+  total_layers: ($layers | length),
+  layers: [range($layers | length) as $i | {
+    layer: $i,
+    can_start_immediately: ($i == 0),
+    depends_on_layer: (if $i > 0 then $i - 1 else null end),
+    slices: $layers[$i]
+  }],
+  critical_path_length: ($layers | length),
+  slices_detail: [.slices[] | {
+    slice_id: .slice_id,
+    change_id: .change_id,
+    ac_subset: .ac_subset,
+    depends_on: (.depends_on // []),
+    budgets: .budgets,
+    verification_anchors: .verification_anchors
+  }]
+}
+')
+
+# =============================================================================
+# 输出生成
+# =============================================================================
+
+generate_markdown() {
+  local meta="$1"
+  local schedule="$2"
+  local knife_file="$3"
+
+  local epic_id plan_id plan_revision risk_level change_type
+  epic_id=$(echo "$meta" | jq -r '.epic_id // "N/A"')
+  plan_id=$(echo "$meta" | jq -r '.plan_id // "N/A"')
+  plan_revision=$(echo "$meta" | jq -r '.plan_revision // "N/A"')
+  risk_level=$(echo "$meta" | jq -r '.risk_level // "N/A"')
+  change_type=$(echo "$meta" | jq -r '.change_type // "N/A"')
+
+  local max_parallelism total_layers
+  max_parallelism=$(echo "$schedule" | jq -r '.max_parallelism')
+  total_layers=$(echo "$schedule" | jq -r '.total_layers')
+
+  cat <<EOF
+# 并行执行调度清单
+
+> 由 \`knife-parallel-schedule.sh\` 自动生成
+> 生成时间: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+## 溯源信息
+
+| 字段 | 值 |
+|------|-----|
+| Epic ID | \`$epic_id\` |
+| Plan ID | \`$plan_id\` |
+| Plan Revision | \`$plan_revision\` |
+| Risk Level | \`$risk_level\` |
+| Change Type | \`$change_type\` |
+| Knife Plan 路径 | \`$knife_file\` |
+
+## 并行度摘要
+
+- **最大并行度**: $max_parallelism（可同时启动的最大 Agent 数量）
+- **总层数**: $total_layers（串行依赖深度）
+- **关键路径长度**: $total_layers 层
+
+## 执行层级
+
+EOF
+
+  # 输出每一层
+  echo "$schedule" | jq -r '.layers[] | "### Layer \(.layer)\(if .can_start_immediately then " (可立即开始)" else " (依赖 Layer \(.depends_on_layer))" end)\n\n| Slice ID | Change ID |\n|----------|-----------|" + (.slices | map("\n| `\(.)` | - |") | join(""))'
+
+  cat <<EOF
+
+## Slice 详情
+
+EOF
+
+  # 输出每个 slice 的详情
+  echo "$schedule" | jq -r '.slices_detail[] | "### \(.slice_id)\n\n- **Change ID**: `\(.change_id // "待分配")`\n- **依赖**: \(if (.depends_on | length) == 0 then "无（可独立执行）" else (.depends_on | map("`\(.)`") | join(", ")) end)\n- **AC 子集**: \(.ac_subset | map("`\(.)`") | join(", "))\n- **Token 预算**: \(.budgets.tokens // "未指定")\n- **验证锚点**: \(if (.verification_anchors | length) == 0 then "无" else (.verification_anchors | map("`\(.)`") | join(", ")) end)\n"'
+
+  cat <<EOF
+
+## 启动命令模板
+
+每个 Slice 对应一个独立的变更包，可以在独立的 Agent 会话中执行：
+
+\`\`\`bash
+# Layer 0 的 Slice 可以立即并行启动
+EOF
+
+  echo "$schedule" | jq -r '.layers[0].slices[] as $sid | .slices_detail[] | select(.slice_id == $sid) | "# Agent for \(.slice_id)\ndevbooks apply --change-id \(.change_id // "<待分配>") --epic-id '"$epic_id"' --slice-id \(.slice_id)"'
+
+  cat <<EOF
+\`\`\`
+
+## 执行建议
+
+1. **并行启动**: 同一 Layer 内的所有 Slice 可以同时启动独立的 Agent
+2. **依赖等待**: 下一 Layer 的 Slice 必须等待上一 Layer 全部完成
+3. **溯源验证**: 每个变更包完成后，使用 \`devbooks archive\` 归档并回写账本
+4. **进度追踪**: 使用 \`progress-dashboard.sh\` 查看整体进度
+
+## 完成后回写
+
+所有 Slice 完成后，执行以下命令更新账本：
+
+\`\`\`bash
+# 派生需求账本
+requirements-ledger-derive.sh --project-root .
+
+# 验证 Epic 完整性
+epic-alignment-check.sh $epic_id --mode strict
+\`\`\`
+
+---
+
+*此清单由 DevBooks Knife Parallel Schedule 生成*
+*参考: dev-playbooks/specs/knife/spec.md*
+EOF
+}
+
+generate_json() {
+  local meta="$1"
+  local schedule="$2"
+  local knife_file="$3"
+
+  jq -n \
+    --argjson meta "$meta" \
+    --argjson schedule "$schedule" \
+    --arg knife_file "$knife_file" \
+    --arg generated_at "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
+    '{
+      schema_version: "1.0.0",
+      generated_at: $generated_at,
+      source: {
+        knife_plan_path: $knife_file,
+        epic_id: $meta.epic_id,
+        plan_id: $meta.plan_id,
+        plan_revision: $meta.plan_revision,
+        risk_level: $meta.risk_level,
+        change_type: $meta.change_type
+      },
+      summary: {
+        max_parallelism: $schedule.max_parallelism,
+        total_layers: $schedule.total_layers,
+        critical_path_length: $schedule.critical_path_length,
+        total_slices: ($schedule.slices_detail | length)
+      },
+      layers: $schedule.layers,
+      slices: $schedule.slices_detail
+    }'
+}
+
+# =============================================================================
+# 输出
+# =============================================================================
+
+output=""
+if [[ "$format" == "md" ]]; then
+  output=$(generate_markdown "$metadata_json" "$schedule_json" "$knife_plan_file")
+else
+  output=$(generate_json "$metadata_json" "$schedule_json" "$knife_plan_file")
+fi
+
+if [[ -n "$out_path" ]]; then
+  if [[ "$out_path" = /* ]]; then
+    out_file="$out_path"
+  else
+    out_file="${project_root}/${out_path}"
+  fi
+  mkdir -p "$(dirname "$out_file")"
+  echo "$output" > "$out_file"
+  infof "Output written to: $out_file"
+else
+  echo "$output"
+fi
+
+infof "Parallel schedule generated successfully"
+infof "Max parallelism: $(echo "$schedule_json" | jq -r '.max_parallelism')"
+infof "Total layers: $(echo "$schedule_json" | jq -r '.total_layers')"

package/skills/devbooks-knife/SKILL.md

@@ -67,7 +67,41 @@ allowed-tools:
 4. 落盘 Knife Plan 到规定路径，并在内容中显式绑定 `epic_id` / `slice_id`。
 5. 输出下一步路由建议：进入 `devbooks-delivery-workflow`（或先进入 Proposal/Design/Spec/Plan），并给出升级条件。
 
+## 并行执行调度
+
+当 Knife Plan 包含多个 Slice 时，可以使用 `knife-parallel-schedule.sh` 生成并行执行清单：
+
+```bash
+# 生成 Markdown 格式的并行调度清单
+knife-parallel-schedule.sh <epic-id> --format md --out parallel-schedule.md
+
+# 生成 JSON 格式（供程序消费）
+knife-parallel-schedule.sh <epic-id> --format json --out parallel-schedule.json
+```
+
+### 输出内容
+
+1. **最大并行度**：可同时启动的最大 Agent 数量
+2. **分层执行清单**：
+   - Layer 0：无依赖，可立即启动
+   - Layer 1：依赖 Layer 0 完成
+   - Layer N：依赖 Layer N-1 完成
+3. **关键路径**：串行依赖深度
+4. **启动命令模板**：每个 Slice 的 Agent 启动命令
+5. **溯源信息**：Epic ID、Plan ID、Plan Revision
+
+### 使用场景
+
+由于当前 AI 编程工具不支持二级子代理调用，Epic 拆分后需要人类协调多个独立 Agent 并行完成：
+
+1. 运行 `knife-parallel-schedule.sh` 生成清单
+2. 根据清单的 Layer 0 启动多个独立 Agent
+3. 等待 Layer 0 全部完成后，启动 Layer 1
+4. 重复直到所有 Layer 完成
+5. 运行 `requirements-ledger-derive.sh` 更新账本
+
 ## 参考
 
 - `dev-playbooks/specs/knife/spec.md`（Knife 的规范与闸门接线要求）
 - `dev-playbooks/specs/_meta/epics/README.md`（Epic 工件目录约束）
+- `skills/devbooks-delivery-workflow/scripts/knife-parallel-schedule.sh`（并行调度脚本）