[moz] docs(§22): 端到端任务流程设计 v1.0

把 §21 散落在各章节的设计点串成一条完整链路：
- Phase 0-8 覆盖从 parent Issue 创建到关闭
- 每个 Phase 标注 4 维度（触发/daemon/prompt/agent）
- prompt 模板对照表（设计 vs 实际）
- 差距分析：Phase 1 discussion broadcast 是核心断裂点（P0）

Closes #119

docs/design/22-end-to-end-flow.md

@@ -0,0 +1,260 @@
+---
+title: "End-to-End Flow — 端到端任务流程设计"
+created: 2026-06-22
+version: v1.0
+status: draft
+changelog: v1.0 初版
+---
+
+# End-to-End Flow — 端到端任务流程设计
+
+> 本文档描述一个任务从发起到结束的**完整系统行为链路**。
+> §21 各章节按功能点分章，本文档把它们串成一条端到端流程。
+> 每个 Phase 标注：触发源、daemon 函数、prompt 来源、agent 行为、留痕位置。
+
+---
+
+## §22.1 流程总览
+
+```
+Phase 0: 庞统创建 parent Issue（无 assignee, 有 type/* label）
+    ↓ webhook: issues/opened
+Phase 1: Discussion 广播（所有空闲 agent）
+    ↓ agent 在 Gitea Issue comment 讨论 → 创建 sub Issue（assign 自己）
+Phase 2: sub Issue assigned → executor 分派
+    ↓ webhook: issues/assigned
+Phase 3: 编码 + PR 创建
+    ↓ webhook: pull_request/opened → CI 自动触发
+Phase 4: CI 检查
+    ↓ CI 通过 → 等 Review / CI 失败 → agent 修复 → 重跑
+Phase 5: Review（司马懿）
+    ↓ APPROVED → 通知 agent 合并 / REQUEST_CHANGES → agent 修改 → 回 Phase 3
+Phase 6: Merge + sub Issue 自动关闭
+    ↓ webhook: pull_request/closed(merged)
+Phase 7: Round Review（庞统三问）
+    ↓ GOAL_ACHIEVED → 关闭 parent / 需要新轮 → 创建新 sub → 回 Phase 2
+Phase 8: parent Issue 关闭
+    ↓ webhook: issues/closed
+```
+
+**核心设计原则**：
+
+1. **协作面是 Gitea**（Issue/PR comment），不是黑板 DB
+2. **每个 Phase 有明确的前置条件和产出**，前一步未完成则后续不触发
+3. **daemon 通过 webhook 感知状态变化**，不依赖 ticker 轮询（ticker 只负责 broadcast 和 review 检测）
+4. **agent 在 Gitea 留痕**（Issue comment、PR、Review），黑板 DB 只存 daemon 内部状态
+
+---
+
+## §22.2 阶段详解
+
+### Phase 0: parent Issue 创建
+
+| 维度 | 内容 |
+|------|------|
+| **触发** | 庞统（或用户）在 Gitea 创建 parent Issue |
+| **条件** | 无 assignee + 有 `type/*` label |
+| **daemon 函数** | `_handle_issues`（`toolchain_routes.py`），opened 分支 |
+| **daemon 行为** | 检测无 assignee + 有 type/* label → 创建 toolchain task（`assignee=None`, `action_type=issue_discussion`）写入 `_toolchain` DB |
+| **agent 行为** | 无（此阶段不 spawn agent） |
+| **产出** | `_toolchain` DB 中一条 pending task |
+
+**webhook 流转**：
+
+```
+Gitea: Issue created (no assignee, label type/feat)
+  → webhook: issues/opened
+  → daemon: _handle_issues → action="opened"
+  → 非部署失败 + 无 assignee + 有 type/* label
+  → _send_toolchain_task(to_agent=None, action_type="issue_discussion")
+```
+
+---
+
+### Phase 1: Discussion 广播
+
+| 维度 | 内容 |
+|------|------|
+| **触发** | ticker 30s 扫到 Phase 0 创建的 pending task |
+| **daemon 函数** | `ticker._dispatch_pending` → `dispatcher.decide` → `_broadcast_claim` |
+| **daemon 行为** | assignee=None → router 返回 mode=delegate → ticker 归入 broadcast_tasks → 广播给所有空闲 agent |
+| **prompt 来源（设计期望）** | `discussion prompt`（§13.2）：你是谁 + 你必须做什么（4 维度）+ Gitea API + Boids 行为准则 |
+| **agent 行为（设计期望）** | 每个 agent 在 **Gitea Issue** comment（角色名开头，4 维度回应）；需要参与的 agent 创建 sub Issue（Gitea API，assign 自己）；在 parent Issue comment 注册 sub |
+| **产出** | parent Issue 上有所有 agent 的讨论 comment；Gitea 上有若干 sub Issue |
+
+**discussion prompt 核心（§13.2）**：
+
+```
+你被 spawn 来参与 Gitea Issue 讨论。
+
+## 讨论主题
+{parent Issue body 全文}
+
+## 你是谁
+你是 {agent_id}（{display_name}），角色是 {role}，能力是 {capabilities}
+
+## 你必须做什么（每个 agent 必须 comment）
+1.【定位】这个需求和你有什么关系？
+2.【建议】你对实现方案有什么建议？
+3.【认领】如果你需要参与，创建 sub Issue 并在 parent comment 注册：
+   POST /repos/{repo}/issues
+   title: "[moz][sub][parent #{N}] 任务名"
+   body: "Parent: #{N}\nDepends: #M\n## 任务\n..."
+   assignees: ["{你的 agent_id}"]
+4.【风险】如果发现风险或不合理假设，直接提出
+
+## Comment 格式
+[角色名] 你的观点
+
+## API（Gitea）
+- 读 Issue: GET /repos/{repo}/issues/{N}
+- 写 comment: POST /repos/{repo}/issues/{N}/comments
+- 创建 sub Issue: POST /repos/{repo}/issues
+```
+
+**Phase 1 的结束条件**：
+
+- 所有被广播的 agent 都已 comment（或 NO_REPLY）
+- 至少有一个 agent 创建了 sub Issue
+- 如果没有任何 agent 创建 sub Issue → ticker 升级庞统（3 轮无 taker 机制）
+
+---
+
+### Phase 2: sub Issue assigned → executor 分派
+
+| 维度 | 内容 |
+|------|------|
+| **触发** | agent 在 Phase 1 创建 sub Issue 时 assign 自己 → Gitea 发 `issues/assigned` webhook |
+| **daemon 函数** | `_handle_issues`（`toolchain_routes.py`），assigned 分支 |
+| **daemon 行为** | 解析 type/* label → 确定 business_type → 从 `toolchain-templates.yaml` 获取 steps → 创建 toolchain task（`action_type=issue_assigned`）→ ticker dispatch |
+| **prompt 来源** | `ToolchainHandler.build_prompt`（通过 PromptComposer 拼装 sections） |
+| **agent 行为** | 建分支 `{type}/{sub_issue_number}-{brief}` → 编码 → 写测试 → 创建 PR（body 含 `Closes #N` + `Parent #M`） |
+| **产出** | Gitea 上有 PR + 分支有代码 |
+
+**steps 来源（`config/toolchain-templates.yaml`）**：
+
+```yaml
+issue_assigned:
+  feat:
+    steps:
+      - "理解需求（Issue body）"
+      - "git checkout -b feat/{issue_number}-{brief}"
+      - "编码 + 写 UT"
+      - "文档同步检查"
+      - "git push + 创建 PR（body 含 Closes #{issue_number}）"
+      - "等 Review"
+```
+
+---
+
+### Phase 3: PR 创建 + CI 触发
+
+| 维度 | 内容 |
+|------|------|
+| **触发** | agent 创建 PR → webhook `pull_request/opened` → CI 自动触发 |
+| **daemon 函数（PR opened）** | `_handle_pull_request` → 创建 `review_request` task → 通知司马懿 |
+| **daemon 函数（CI）** | CI 结果通过 Gitea comment 反馈 → `_handle_issue_comment` CI 路径 |
+| **CI 通过** | 等待 Review（Phase 5） |
+| **CI 失败** | 创建 `ci_failure` task → 通知 agent 修复 |
+| **agent prompt（CI 失败时）** | `ToolchainHandler.build_prompt`，action_type=ci_failure，steps 含 CI 日志查看 + 根因判断 + 修复 |
+| **产出** | CI 通过的 PR |
+
+---
+
+### Phase 4: Review（司马懿）
+
+| 维度 | 内容 |
+|------|------|
+| **触发** | `review_request` task 被 ticker dispatch 给司马懿 |
+| **daemon 函数** | ticker spawn 司马懿 → 司马懿通过 Review API 提交 verdict → webhook `pull_request_review` → `_handle_pull_request_review` |
+| **prompt 来源** | `ToolchainHandler.build_prompt`，action_type=review_request |
+| **Review APPROVED** | 创建 `review_result_approved` task → 通知 agent 合并 |
+| **Review REQUEST_CHANGES** | 创建 `review_result_request_changes` task → 通知 agent 修改 → agent push 同分支 → CI 重跑 → 回 Phase 3 |
+| **产出** | Gitea Review 记录 |
+
+---
+
+### Phase 5: Merge + sub Issue 关闭
+
+| 维度 | 内容 |
+|------|------|
+| **触发** | agent merge PR |
+| **daemon 函数** | Gitea 自动关闭 sub Issue（PR body 含 `Closes #N`）→ webhook `pull_request/closed(merged)` → `_handle_pull_request` closed 分支 |
+| **daemon 行为** | 创建 `review_merged` task → 通知 agent（纯通知）；ToolchainHandler verify: auto-pass |
+| **产出** | sub Issue closed + 分支自动删除 |
+
+---
+
+### Phase 6: Round Review（庞统三问）
+
+| 维度 | 内容 |
+|------|------|
+| **触发** | daemon 检测 parent Issue 下所有 sub Issue 终态（done/closed） |
+| **daemon 函数** | `ticker._check_round_complete` 扫描 parent/sub 映射 → 所有 sub 终态 → spawn 庞统 |
+| **prompt 来源** | `ticker._build_review_prompt`（三问框架） |
+| **agent 行为** | 庞统通过 Gitea API 读 parent Issue body + 所有 sub Issue comments/outputs → 三问评估 |
+| **GOAL_ACHIEVED** | 庞统关闭 parent Issue → Phase 7 |
+| **需要新轮** | 庞统创建新 sub Issues → 回 Phase 2 |
+| **产出** | parent Issue closed 或新一轮 sub Issues |
+
+**三问框架**：
+
+```
+1. Goal 还清晰吗？（是否有 goal drift）
+2. 成果物覆盖 goal 了吗？（逐条检查验收标准 + docs/design 同步确认）
+3. 下一轮需要做什么？（创建新 sub / 标记完成 / 调整方向）
+```
+
+---
+
+### Phase 7: parent Issue 关闭
+
+| 维度 | 内容 |
+|------|------|
+| **触发** | 庞统关闭 parent Issue |
+| **daemon 函数** | webhook `issues/closed` → `_handle_issues` closed 分支 |
+| **daemon 行为** | 创建 `issue_closed` task → 通知（纯通知，auto-pass） |
+| **产出** | parent Issue closed，全流程结束 |
+
+---
+
+## §22.3 Prompt 模板对照表
+
+| Phase | prompt 用途 | 设计指定的模板来源 | 当前实际来源 | 一致？ |
+|-------|-----------|----------------|------------|-------|
+| 1 Discussion | 广播讨论 | discussion prompt（§13.2，Gitea API） | claim prompt（`_build_claim_prompt`，黑板 API） | ❌ |
+| 2 Executor | 编码执行 | `ToolchainHandler.build_prompt` + YAML steps | 同设计 | ✅ |
+| 3 CI 失败 | 修复 CI | `ToolchainHandler.build_prompt` ci_failure | 同设计 | ✅ |
+| 4 Review | 审查 PR | `ToolchainHandler.build_prompt` review_request | 同设计 | ✅ |
+| 5 Merge | 合并通知 | `ToolchainHandler.build_prompt` review_merged | 同设计 | ✅ |
+| 6 Round Review | 庞统三问 | `ticker._build_review_prompt` | 同设计 | ✅ |
+| 7 Issue closed | 关闭通知 | `ToolchainHandler.build_prompt` issue_closed | 同设计 | ✅ |
+
+**唯一偏差在 Phase 1**：discussion 设计了完整的 prompt（§13.2），但 ticker 从未调用它。
+
+---
+
+## §22.4 当前实现差距
+
+| Phase | 实现状态 | 差距描述 |
+|-------|---------|---------|
+| 0 parent Issue 创建 | ✅ 已实现 | PR #113 `_handle_issues` opened 分支，无 assignee + type/* label → toolchain task |
+| 1 Discussion 广播 | ❌ **未实现** | ticker broadcast 只有 `_build_claim_prompt`（黑板 API，认领模式），没有 discussion broadcast（Gitea API，讨论模式）。`_build_discussion_prompt` 存在于 spawner 中但 ticker 从未调用。agent 收到的是"认领并执行"而不是"讨论后创建 sub" |
+| 2 sub Issue → executor | ⚠️ 部分 | assigned 路径 + YAML steps 已实现（PR #107），但因为 Phase 1 断裂，agent 不会创建 sub Issue，走不到此阶段 |
+| 3 PR + CI | ✅ 已实现 | toolchain handler 正常处理 PR opened + CI 失败 |
+| 4 Review | ✅ 已实现 | Review 请求 + Review 结果通知正常 |
+| 5 Merge + sub 关闭 | ⚠️ 部分 | merge 通知正常。但 agent 创建的 PR body 不含 `Closes #N`（因为走的是 claim prompt 不是 executor prompt，prompt 中没有 Closes #N 约束） |
+| 6 Round Review | ❌ 未适配 | `_check_round_complete` 扫黑板 `parent_task` 字段，不扫 Gitea parent/sub Issue 映射。没有 sub Issue 就检测不到 |
+| 7 parent Issue 关闭 | ✅ 已实现 | PR #113 issue_closed auto-pass |
+
+---
+
+## §22.5 差距优先级排序
+
+| 优先级 | 差距 | 影响范围 | 修复建议 |
+|--------|------|---------|---------|
+| **P0** | Phase 1 discussion broadcast | **核心断裂**。整个 Gitea Issue 流程退化成黑板 claim 模式 | ticker `_broadcast_claim` 中判断 `action_type=issue_discussion` → 调用 discussion prompt（Gitea API 版本）而非 claim prompt |
+| **P1** | Phase 5 PR body Closes #N | sub Issue 不自动关闭 | Phase 2 executor prompt 中已有 Closes #N 约束（YAML steps），Phase 1 修好后自然解决 |
+| **P2** | Phase 6 Round Review Gitea 适配 | 无法触发庞统三问 | `_check_round_complete` 改为扫 Gitea parent/sub Issue 映射（通过 `task_state.parent_issue` 字段，§20 设计） |
+
+**关键结论**：P0 是唯一阻断点。修好 Phase 1 discussion broadcast 后，Phase 2-5 自然走通（已实现），Phase 6-7 后续跟进。