From 280435119e5a5c76b8b2621132ac66ddbbd43020 Mon Sep 17 00:00:00 2001
From: cfdaily <cfdaily@gitee.com>
Date: Sat, 20 Jun 2026 21:28:46 +0800
Subject: [PATCH] =?UTF-8?q?[moz]=20docs(=C2=A721):=20=E6=96=B0=E5=A2=9E=20?=
 =?UTF-8?q?=C2=A714b=20=E5=88=86=E6=94=AF=E4=B8=8E=20PR=20=E7=94=9F?=
 =?UTF-8?q?=E5=91=BD=E5=91=A8=E6=9C=9F=E7=AE=A1=E7=90=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

§14b.1 Sub Issue 完整生命周期（9 步：创建→分支→编码→PR→CI→Review→修改→Merge→清理）
§14b.2 Parent Issue 完整生命周期（5 步：创建→讨论→执行→Round Review→关闭）
§14b.3 核心规则（分支:Issue=1:1, 分支:PR=1:1, Closes #N, Parent #M）
§14b.4 多分支并行场景
§14b.5 PR body 标准模板
---
 docs/design/21-unified-toolchain-design.md | 132 +++++++++++++++++++++
 1 file changed, 132 insertions(+)

diff --git a/docs/design/21-unified-toolchain-design.md b/docs/design/21-unified-toolchain-design.md
index 2671ada..9efc934 100644
--- a/docs/design/21-unified-toolchain-design.md
+++ b/docs/design/21-unified-toolchain-design.md
@@ -797,6 +797,138 @@ daemon 监听 Issue 创建 webhook → 解析标题中的 `[parent #N]` → 记
 
 ---
 
+## §14b. 分支与 PR 生命周期管理
+
+> 解决分支、PR、Issue 之间的割裂问题，统一定义完整生命周期。
+
+### 14b.1 Sub Issue 的分支/PR 生命周期
+
+```
+① 创建 Sub Issue
+  Agent 在 discussion 阶段创建 sub Issue（assign 自己）
+  → 分支：还不存在
+  → daemon task_state: status=pending, parent_issue=N
+
+② 分支创建（executor 阶段）
+  Agent 收到 executor prompt → git checkout -b {type}/{sub_issue_number}-{brief}
+  → 分支名从 sub Issue number 派生，一一对应
+  → daemon task_state: status=working（通过 dispatch 触发）
+
+③ 编码
+  Agent 在分支上编码 → commit → push
+  → 分支远程存在，Gitea 可见
+
+④ PR 创建
+  Agent 创建 PR（head: {type}/{sub_issue_number}-{brief} → base: main）
+  PR body 必须包含：
+    - `Closes #{sub_issue_number}`（让 Gitea merge 时自动关 sub Issue）
+    - `Parent: #{parent_issue_number}`（关联到 parent）
+    - 改动说明（改了什么、为什么）
+  → webhook: pull_request/opened → daemon task_state: status=review
+
+⑤ CI
+  PR 创建 → CI 自动触发（lint + test + frontend）
+  → 通过：等 Review
+  → 失败：toolchain handler 创建 ci_failure task → agent 修复 → push 到同分支 → CI 重跑
+
+⑥ Review
+  司马懿收到 Review 请求 → 读 PR diff → 提交 Review（Review API）
+  → APPROVED：通知 agent 合并
+  → REQUEST_CHANGES：通知 agent 修改
+
+⑦ 修改（如果有）
+  Agent 在同分支上修改 → commit → push
+  → PR 自动更新（不新建 PR）
+  → CI 重跑 → 司马懿重新 Review
+  → 循环回到 ⑥
+
+⑧ Merge
+  Agent 或 Reviewer merge PR
+  → Gitea 自动关闭 sub Issue（因为 PR body 有 Closes #N）
+  → webhook: pull_request/closed(merged=true)
+  → daemon 终态信号：task_state status=done
+
+⑨ 分支清理
+  Gitea 配置自动删除已合并分支（推荐）
+  Issue 保持 closed 状态（完整历史保留）
+```
+
+### 14b.2 Parent Issue 的生命周期
+
+```
+① 创建（庞统）
+  庞统创建 parent Issue（无 assignee）
+  → 触发 discussion 广播
+  → parent Issue 不创建分支（parent 是讨论和编排层）
+
+② Discussion
+  Agents 讨论、创建 sub Issues、在 parent comment 注册
+
+③ 执行
+  所有 sub Issues 走 §14b.1 生命周期
+
+④ Round Review
+  所有 sub Issues 终态 → 庞统三问
+  → GOAL_ACHIEVED → 庞统关闭 parent Issue
+  → 需要新轮 → 庞统创建新 sub Issues → 回到 ③
+
+⑤ 关闭
+  庞统关闭 parent Issue
+  → webhook: issues/closed → daemon 终态
+```
+
+### 14b.3 核心规则
+
+| 规则 | 定义 | 原因 |
+|------|------|------|
+| 分支 : sub Issue = 1:1 | 每个 sub Issue 一个分支 | 分支名从 Issue number 派生 |
+| 分支 : PR = 1:1 | 每个分支一个 PR | Review 驳回不新建 PR，push 到同分支更新 |
+| sub Issue : PR = 1:1 | 一个 sub Issue 一个 PR | 简单场景。复杂 sub 按需拆多个 sub Issue |
+| PR body 必须含 Closes #N | N = sub Issue 编号 | merge 后自动关 Issue |
+| PR body 必须含 Parent #M | M = parent Issue 编号 | 关联到 parent，方便追溯 |
+| parent Issue 不创建分支 | parent 是讨论编排层 | 代码产出在 sub Issue 的分支 |
+| discussion 不碰 git | 只读 Issue + comment + 创建 sub | 避免讨论阶段产生无意义 commit |
+| 分支名格式 | {type}/{sub_issue_number}-{brief} | 按 Issue 类型：fix/feat/impl/docs/refactor/test |
+| merge 后自动删分支 | Gitea 配置 | 避免分支堆积 |
+
+### 14b.4 多分支并行场景
+
+一个 parent Issue 下多个 sub Issue 同时执行：
+
+```
+parent Issue #100（双均线策略）
+  ├── sub #101 策略编码 → 分支 feat/101-dual-ma → PR #104
+  │   └── CI 跑 + Review → merge → Closes #101
+  ├── sub #102 风控规则 → 分支 feat/102-risk-control → PR #105
+  │   └── CI 跑 + Review → merge → Closes #102
+  └── sub #103 策略测试 → 分支 test/103-strategy-test → PR #106
+      └── CI 跑 + Review → merge → Closes #103
+
+所有 sub 终态 → 庞统 round review → parent Issue #100 关闭
+```
+
+每个 sub Issue 的分支、PR、CI、Review 独立流转，互不干扰。
+
+### 14b.5 PR body 模板
+
+```markdown
+Closes #{sub_issue_number}
+Parent: #{parent_issue_number}
+
+## 改动说明
+<改了什么、为什么>
+
+## 验证
+- [ ] CI 通过（lint + test）
+- [ ] 本地测试通过（如有）
+
+## 改动文件
+- `src/xxx.py`: <改了什么>
+- `tests/test_xxx.py`: <新增什么测试>
+```
+
+---
+
 ## §15. @mention 通知迁移
 
 ### 15.1 当前实现