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

title, created, version, status, changelog

title	created	version	status	changelog
End-to-End Flow — 端到端任务流程设计	2026-06-22	v1.0	draft	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）：

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 后续跟进。