diff --git a/docs/design/22-end-to-end-flow.md b/docs/design/22-end-to-end-flow.md index ca33f0d..0b949a4 100644 --- a/docs/design/22-end-to-end-flow.md +++ b/docs/design/22-end-to-end-flow.md @@ -1,9 +1,12 @@ --- title: "End-to-End Flow — 端到端任务流程设计" created: 2026-06-22 -version: v1.2 +version: v1.5 status: draft -changelog: v1.2 §22.3/§22.4 更新 Phase 1 为 ✅ 已实现(PR #124) +changelog: v1.5 采纳司马懿 S1-S4+P1-P3:判断逻辑补 infrastructure 分支、flow/discuss deprecated、定向讨论 fallback、task_state.status 完整生命周期、parent_status 查表不硬编码 + v1.4 §22.6/§22.8 设计补足:基础设施排除、定向讨论简化为单spawn自主模式、迁移策略、TC数据源/round_count分流通透 + v1.3 §22.6 重构为「所有 TC 流程第一步走 Discuss」+ §22.8 TC Round Review Gitea 适配设计 + v1.2 §22.3/§22.4 更新 Phase 1 为 ✅ 已实现(PR #124) v1.1 补充轻量路径设计(§22.6)、数据流澄清(§22.7)、修正设计原则3、统一Phase编号、Phase 1标注 v1.0 初版 --- @@ -264,35 +267,96 @@ issue_assigned: ## §22.6 轻量路径设计(Direct Assignment) -> 不是所有任务都需要 Discussion 广播。需求明确、单一执行者的任务应跳过 Phase 0/1 直接进入 Phase 2。 +> **核心原则:所有 TC 流程第一步都走 Discuss(基础设施和 flow/direct 除外)。** +> Discussion 不是可选项,而是 TC 流程的必经阶段——确保方案对齐、风险暴露后再进入 exec。 +> 区别只在于「谁参与讨论」。 ### 路径决策矩阵 -| 条件 | 路径 | 流程 | -|------|------|------| -| Issue 无 assignee + type/* label | **Discussion 路径**(默认) | Phase 0 → 1 → 2 → … | -| Issue 有 assignee | **Direct 路径** | → Phase 2(跳过 Phase 0/1) | -| Issue 有 `flow/direct` label | **强制 Direct** | → Phase 2(即使无 assignee,daemon 自动 assign) | -| Issue 有 `flow/discuss` label | **强制 Discussion** | Phase 0 → 1 → 2 → …(即使有 assignee) | +| 条件 | 讨论范围 | 流程 | +|------|---------|------| +| Issue 无 assignee + type/* label | **广播所有空闲 agent** | Phase 0 → 1(广播讨论)→ 2 → … | +| Issue 有 assignee(非 infrastructure) | **assignee 自主定向讨论** | assignee 写方案 → @司马懿 review → 创建 sub Issue 进 exec | +| Issue 有 `type/infrastructure` label | **跳过讨论** | → executor(运维排障,无需方案审查) | +| Issue 有 `flow/direct` label | **跳过讨论** | → Phase 2(极小改动逃生舱) | + +**设计原则**: +1. 基础设施 Issue(`type/infrastructure`)→ 直接到 executor(运维排障任务,不需要写方案+审查) +2. `flow/direct` label → 直接到 executor(明确不需要讨论的小改动) +3. 有 assignee(非 infrastructure)→ assignee 自主走「方案→review→exec」流程,daemon 不编排 +4. 没有 assignee → 广播所有 agent 讨论,有 agent 认领后创建 sub Issue + +> **v1.4 补充**:v1.3 原设计将 infrastructure 也纳入 Discuss,但基础设施排障任务(Gitea 挂了、磁盘满等)不需要写实现方案和司马懿审查,应排除。 ### 判断逻辑 ``` parent Issue 创建 - ├─ 有 flow/discuss label?→ Discussion 路径(Phase 0 → 1) - ├─ 有 flow/direct label?→ Direct 路径(daemon 自动 assign → Phase 2) - ├─ 有 assignee?→ Direct 路径(→ Phase 2) - └─ 无 assignee(默认)→ Discussion 路径(Phase 0 → 1) + ├─ 有 flow/direct label?→ Direct 路径(→ Phase 2,跳过讨论) + ├─ 有 type/infrastructure label?→ Direct 路径(→ executor,运维排障) + ├─ 有 assignee(非 infrastructure)?→ 定向 Discussion(assignee 自主模式) + └─ 无 assignee(默认)→ 广播 Discussion(所有空闲 agent) ``` -优先级:`flow/*` label > assignee > 默认行为。 +### 定向讨论流程(有 assignee,非 infrastructure) + +> **v1.4 修正**:v1.3 原设计「ticker 同时 spawn assignee + 司马懿」过于复杂,需要 daemon 协调两个 agent 生命周期。 +> v1.4 简化为**单 spawn 自主模式**——daemon 只创建 discussion task 给 assignee,assignee 在一个 session 内自主完成全部流程。 + +``` +Issue assigned webhook + → daemon 创建 issue_discussion task(assignee=该 agent,context_data 带 issue/repo) + → ticker dispatch:有 assignee → 确定性路由 spawn assignee 单人 + → discussion prompt 引导 assignee: + 1. 读 Issue 全文,在 Gitea Issue comment 写实现方案(技术选型、实现路径、影响范围) + 2. @simayi-challenger 请求方案审查(利用现有 @mention 机制自动创建 review task) + 3. 等司马懿 review 结果(通过 @mention 回传) + 4. review 通过 → 创建 sub Issue(assign 自己)→ 进入 exec + 5. review 驳回 → 修改方案重新提交(重新 comment + @司马懿) +``` + +**为什么不双 spawn**: +1. assignee 写方案时间不确定,双 spawn 后司马懿可能干等 +2. 两阶段串行更简单,assignee 完成后 @mention 自动触发司马懿 +3. 和广播讨论一致——daemon 只创建初始 task,后续靠 agent 自主 + @mention + +**与广播讨论的区别**: +- 广播讨论:assignee=None → ticker 归入 broadcast_tasks → 广播所有空闲 agent +- 定向讨论:assignee=该 agent → ticker 归入 deterministic_tasks → 确定性路由 spawn 单人 + +### 定向讨论 fallback(assignee 无响应) + +> **v1.4 补充(司马懿 S4)**:广播讨论有「3 轮无 taker → 升级庞统」机制,定向讨论也需要 fallback。 + +单 spawn assignee 后,如果 assignee NO_REPLY 或 session 超时: + +``` +ticker 定期 check(复用现有 broadcast _broadcast_tracker 机制) + → discussion task 仍 pending/working 且超过 3 轮 check 未终态 + → 升级庞统(escalated 状态) + → 庞统判断:重新分配 / 转为广播讨论 / 直接关闭 +``` + +复用现有 `_broadcast_tracker` 的 `round_number >= 3 → escalated` 逻辑,不引入新机制。 + +### 广播讨论流程(无 assignee) + +``` +Issue opened webhook + → daemon 创建 issue_discussion task(assignee=None) + → ticker broadcast:广播所有空闲 agent + → discussion prompt 引导每个 agent: + 1. 在 Gitea Issue comment 回应(定位/建议/认领/风险) + 2. 需要参与的 agent 创建 sub Issue assign 自己 +``` ### 适用场景 | 路径 | 适用场景 | 示例 | |------|---------|------| -| Discussion | 需求不明确、需要多角色讨论、跨模块协作 | 新功能设计、架构变更、涉及 3+ agent 的任务 | -| Direct | 需求明确、单一执行者、小范围改动 | Bug 修复、文档更新、配置调整、单人任务 | +| 广播讨论 | 需求不明确、跨模块协作、涉及 3+ agent、无人认领 | 新功能设计、架构变更 | +| 定向讨论 | 需求明确但需要方案确认 | 有明确 assignee 的 Issue | +| Direct | 改 typo、改配置值等极小改动 | `flow/direct` label | ### Discussion 路径中的降级 @@ -304,26 +368,42 @@ Discussion 进行中,如果所有 agent 都认为任务足够简单只涉及 庞统判断后创建 sub Issue 直接 assign → 该 agent 跳过讨论直接进入 Phase 2。 -### Direct 路径跳过的 Phase +### 迁移策略 -| Phase | 是否跳过 | 原因 | -|-------|---------|------| -| Phase 0(parent Issue 讨论 task) | ✅ 跳过 | 不创建 discussion task | -| Phase 1(Discussion 广播) | ✅ 跳过 | 不广播,不打扰其他 agent | -| Phase 2(assigned → executor) | ❌ 直接进入 | 起点 | +> **v1.4 补充**:v1.3 未说明现有 `issue_assigned` 路径如何处理。 -### 对现有代码的影响 +**保留 `issue_assigned` 给 infrastructure / flow-direct,新增定向讨论路径**: -当前 `_handle_issues` 已有两个分支: +| 条件 | 旧路径(v1.2) | 新路径(v1.4) | 变化 | +|------|----------------|----------------|------| +| 有 assignee + 非 infrastructure | issue_assigned → executor | issue_discussion → discussion(定向) | **改** | +| 有 assignee + `type/infrastructure` | issue_assigned → executor | issue_assigned → executor(不变) | 无 | +| 有 `flow/direct` label | issue_assigned → executor | issue_assigned → executor(不变) | 无 | +| 无 assignee + type/* label | issue_discussion → broadcast | issue_discussion → broadcast(不变) | 无 | -- `opened`(无 assignee + type/* label)→ discussion task ← Discussion 路径 ✅ -- `assigned`(有 assignee)→ executor task ← Direct 路径 ✅ +`_ACTION_HINTS` / YAML steps / `ToolchainContextSection` 中的 `issue_assigned` 相关逻辑**保留**(infrastructure/flow-direct 还用),新增 `issue_review_discussion` action_type。 -**轻量路径已全部实现**。包括: +> **`flow/discuss` label deprecated**:v1.2 曾设计 `flow/discuss` label(强制 Discussion 即使有 assignee),v1.4 废弃。所有有 assignee 的 Issue(非 infrastructure)默认走定向讨论,无需显式 label。Gitea 上 `flow/discuss` label(id=101)保留但不影响路由。 -1. ✅ `flow/direct` 和 `flow/discuss` label 已创建(Gitea label id=100, 101) -2. ✅ `toolchain_routes.py` `_handle_issues` opened 分支识别 `flow/direct` → executor task -3. ✅ Discussion prompt 中包含降级机制引导(§22.6) +### 实现方案 + +**toolchain_routes.py**: +- `opened` 分支(无 assignee)→ discussion task(assignee=None)— 现有逻辑 ✅ +- `assigned` 分支改造: + - `is_infrastructure=True` → executor task(现有逻辑保留 ✅) + - `has_flow_direct=True` → executor task(现有逻辑保留 ✅) + - **其他** → discussion task(assignee=该 agent,context_data 带 issue/repo)— **需要改动** + +**ticker.py**: +- 定向讨论 task 有 assignee → `_dispatch_pending` 确定性路由直接 spawn assignee 单人 +- 广播讨论 task 无 assignee → `_broadcast_claim` 广播所有空闲 agent(现有逻辑 ✅) +- `_broadcast_claim` 中的 action_type 判断逻辑保留(discussion task 走 `_build_discussion_prompt`) + +**讨论 prompt 差异化**: +- 定向讨论 prompt 额外指引:你是 assignee,需要写方案并主动 @司马懿 review +- 广播讨论 prompt 保持现有模板(4 维度回应 + 自主认领) + +**不影响**:mail / task 流程(它们不走 toolchain_routes.py) --- @@ -360,29 +440,11 @@ ticker: _check_round_complete → 全部终态 → spawn 庞统 review ``` -### 前置条件 +### 前置条件(已全部实现 ✅) -1. **task_state 表创建**:§20 设计了 DDL 但未实现。需要先建表: - - ```sql - CREATE TABLE task_state ( - issue_number INTEGER PRIMARY KEY, - repo TEXT, - parent_issue INTEGER, - status TEXT DEFAULT 'pending', - action_type TEXT, - retry_count INTEGER DEFAULT 0, - dispatch_count INTEGER DEFAULT 0, - round_count INTEGER DEFAULT 0, - created_at TEXT, - updated_at TEXT - ); - CREATE INDEX idx_task_state_parent ON task_state(parent_issue); - ``` - -2. **parent_issue 解析**:daemon 在 `_handle_issues` 中解析标题 `[parent #{N}]` 模式,写入 `task_state.parent_issue`(§21 §14b L920 已有此设计)。 - -3. **_check_round_complete 改造**:从扫 `tasks.parent_task`(黑板)改为扫 `task_state.parent_issue`(toolchain DB)(§21 §16.2 L1148 已有此设计)。 +1. **task_state 表创建**:已在 PR #125 中实现(`_init_task_state_table`,CREATE IF NOT EXISTS)。 +2. **parent_issue 解析**:已实现(`_ensure_task_state`,`_handle_issues` assigned 分支解析 `[parent #N]`)。 +3. **_check_round_complete 双源扫描**:已实现(`task_state.parent_issue` + `tasks.parent_task`)。 ### 混合期处理 @@ -405,3 +467,245 @@ task_state 表创建前,`_check_round_complete` 仍扫 `tasks.parent_task`。 | 5 | toolchain DB: task(review_merged) | Gitea webhook (PR closed/merged) | — | — | | 6 | task_state: round_count++ | task_state: parent_issue + sub status | Gitea parent Issue body + sub Issue comments | Gitea Issue comment(三问结论)+ 关闭/创建 Issue | | 7 | toolchain DB: task(issue_closed) | Gitea webhook (issues/closed) | — | — | + +--- + +## §22.8 TC Round Review Gitea 适配 + +> **设计原则:三个流程已通过 Handler 架构分离(§14)。TC Round Review 的改造通过 ToolchainHandler 分流,不影响黑板流程。** + +### 问题(v1.4 修正:不只是 prompt 不同,数据查询链路也不同) + +`_check_round_complete` 中调用 `bb.get_subtasks_summary(parent_id)` / `bb.get_aggregate_outputs()` / `bb.get_round_comments()` 全部查黑板 DB。但 TC 的子任务信息在 `task_state` 表 + Gitea Issue/PR,**根本不在黑板 tasks/outputs/comments 表**。 + +因此 handler 分流不只是 prompt 层面,需要贯穿**数据查询 → prompt 构建 → round_count 递增**三个环节。 + +### TC 数据源 vs 黑板数据源对照 + +| 环节 | 黑板路径 | TC 路径 | +|------|---------|---------| +| 子任务状态 | `bb.get_subtasks_summary()` → tasks 表 | 新增 `get_tc_subtask_summary()` → task_state 表 | +| 成果物 | `bb.get_aggregate_outputs()` → outputs 表 | 庞统自己读 Gitea API(PR/commit) | +| 讨论历史 | `bb.get_round_comments()` → comments 表 | 庞统自己读 Gitea Issue comments | +| round_count | `bb.increment_round_count()` → tasks.round_count | `UPDATE task_state SET round_count+1` | +| parent status | tasks.status | task_state.status(需补充更新逻辑) | + +### task_state.status 更新机制 + +> **v1.4 补充(司马懿 S3)**:当前 `_ensure_task_state` 只做 `INSERT OR IGNORE`,status 初始为 `pending`,后续没有任何代码更新。需补充。 + +**状态生命周期**: + +| 状态 | 触发来源 | 更新位置 | +|------|---------|----------| +| `pending` | `_ensure_task_state` 初始插入 | `toolchain_routes.py` assigned 分支 | +| `done` | Gitea Issue closed webhook | `toolchain_routes.py` closed 分支 | +| `failed` | executor task 验证失败且未重试 | `toolchain_handler.py` `post_complete` → `_update_task_state_status()` | + +**关键路径说明**: + +1. **sub Issue 创建** → `_ensure_task_state` 写入 `status='pending'` +2. **sub Issue 对应的 executor task 完成** → ToolchainHandler 通过 @mention 指引 agent 创建 PR(含 `Closes #N`)→ PR 合并时 Gitea 自动关闭 Issue → webhook `issues/closed` → 更新 `status='done'` +3. **executor task 失败** → `ToolchainHandler.post_complete()` 中检测 verify 失败且 retry_count 达上限 → 调用 `_update_task_state_status(issue_number, 'failed')` + +**`post_complete` 何时触发**:spawner 完成 session 后(agent exit),ticker 在下个 tick 检测到 session 终态 → 调用 `handler.post_complete(task_id, agent_id, outcome, db_path)`。此时 handler 可以: +- 检查 verify 结果 +- 如果 failed 且不可 retry → 查 task_state 找到对应 issue_number → 更新 status='failed' + +**新增方法**: + +```python +# toolchain_handler.py +def _update_task_state_status(self, issue_number: int, status: str): + """更新 task_state.status(executor 失败时调用)""" + tc_db = _toolchain_db_path() + conn = get_connection(tc_db) + try: + conn.execute( + "UPDATE task_state SET status=?, updated_at=datetime('now') " + "WHERE issue_number=?", + (status, issue_number) + ) + conn.commit() + finally: + conn.close() +``` + +**toolchain_routes.py closed 分支补充**: + +```python +elif action == "closed": + # 更新 task_state status='done' + tc_db = _toolchain_db_path() + conn = get_connection(tc_db) + try: + conn.execute( + "UPDATE task_state SET status='done', updated_at=datetime('now') " + "WHERE issue_number=?", + (issue_number,) + ) + conn.commit() + finally: + conn.close() + # ... 现有通知逻辑 +``` + +> **注意**:`get_tc_subtask_summary` 中的 `all_terminal` 只依赖 `done` 和 `failed` 两种终态。`pending`/`working` 计入 `other`,确保未完成的 sub 不会误触发 round review。 + +### 分流方案(全链路) + +``` +_check_round_complete: + handler = TaskTypeRegistry.get_by_project(project_id) + is_tc = handler and handler.virtual_project == "_toolchain" + + # 1. 数据查询分流 + if is_tc and parent_id in task_state_parents: + summary = get_tc_subtask_summary(tc_db, int(parent_id)) + # 不查 outputs/comments — 庞统 spawn 后自己读 Gitea API + else: + summary = bb.get_subtasks_summary(parent_id) + outputs = bb.get_aggregate_outputs(parent_id) + comments = bb.get_round_comments(parent_id) + + # 2. prompt 构建分流 + if is_tc: + review_prompt = handler.build_round_review_prompt(parent_id, summary, ...) + else: + review_prompt = self._build_review_prompt(parent_task, summary, outputs, comments, ...) + + # 3. round_count 递增分流 + if spawned: + if is_tc: + UPDATE task_state SET round_count = round_count + 1 WHERE issue_number = ? + else: + bb.increment_round_count(parent_id) +``` + +### BaseTaskHandler 接口扩展 + +在 `BaseTaskHandler`(`task_type_registry.py`)中新增默认方法: + +```python +def build_round_review_prompt(self, parent_id: str, summary: dict, + outputs: list, comments: list, + round_num: int, **kwargs) -> str: + """构建 Round Review prompt。默认 raise NotImplementedError。""" + raise NotImplementedError( + f"{self.task_type} handler does not support round review") +``` + +普通 task 和 mail 不调用此方法(走 ticker 原有 `_build_review_prompt`),只有 ToolchainHandler override。 + +### ToolchainHandler.build_round_review_prompt + +TC 版本的 Round Review prompt。核心区别: + +| 维度 | 黑板版(原) | Gitea 版(新) | +|------|-----------|-------------| +| Goal 来源 | `parent_task.description`(黑板 DB) | parent Issue body(庞统自己读 Gitea API) | +| 成果物 | `bb.get_aggregate_outputs()`(黑板 DB) | PR / commit(庞统自己读 Gitea API) | +| 讨论历史 | `bb.get_round_comments()`(黑板 DB) | Issue comments(庞统自己读 Gitea API) | +| 创建新 sub | `POST localhost:8083/api/.../tasks`(黑板 API) | `POST Gitea /repos/.../issues`(Gitea API) | +| 关闭 parent | 更新黑板 status | `PATCH Gitea /repos/.../issues/{N}` | + +**prompt 设计**:只给 Issue 编号和 repo,让庞统 spawn 后自己调 Gitea API 读详情。daemon 不做 Gitea API 调用。 + +``` +## 庞统 TC Round Review(第 {round_num} 轮) + +### Parent Issue +- Repo: {repo} +- Issue: #{parent_issue_number} + +### 本轮 Sub Issue 状态 +- 完成: {done} +- 失败: {failed} +- 总计: {total} + +### 你必须做什么 + +1. 读 parent Issue: GET /repos/{repo}/issues/{parent_issue_number} +2. 读所有 sub Issue 的 comments 和 PR +3. 三问评估: + - Goal 还清晰吗? + - 成果物覆盖 goal 了吗?(逐条检查 + docs/design 同步) + - 下一轮需要做什么? +4. 决策: + - GOAL_ACHIEVED → 关闭 parent Issue + - 需要新轮 → 创建新 sub Issues + +### Gitea API +- 读 Issue: GET /repos/{repo}/issues/{N} +- 读 comments: GET /repos/{repo}/issues/{N}/comments +- 创建 sub Issue: POST /repos/{repo}/issues +- 关闭 Issue: PATCH /repos/{repo}/issues/{N} (state=closed) +``` + +### 不影响黑板流程的保证 + +1. **Handler 分流**:`_check_round_complete` 通过 `TaskTypeRegistry.get_by_project(project_id)` 判断。普通项目(无 handler)走 `_build_review_prompt`(黑板版本不变) +2. **数据隔离**:TC review 读 `task_state` 表 + Gitea API;黑板 review 读 `tasks` 表 + `outputs` / `comments` 表 +3. **prompt 隔离**:TC prompt 只含 Gitea API 指引;黑板 prompt 只含黑板 API 指引 +4. **Handler 分流模式已在 `_dispatch_reviews` 中验证可行**:L1379 `if handler: return []` 用 Handler 分流跳过 handler 项目的 PR Review 流程,TC Round Review 采用相同模式 + +### 实现方案 + +| 文件 | 改动 | +|------|------| +| `task_type_registry.py` | `BaseTaskHandler` 加 `build_round_review_prompt` 默认方法(raise NotImplementedError) | +| `toolchain_handler.py` | `ToolchainHandler` override `build_round_review_prompt` → 返回 Gitea API 版 prompt;新增 `get_tc_subtask_summary()` 静态方法 | +| `ticker.py` | `_check_round_complete` 全链路分流:数据查询 + prompt 构建 + round_count 递增 | +| `toolchain_routes.py` | `_handle_issues` closed 分支:更新 `task_state.status = 'done'` | + +### get_tc_subtask_summary 方法设计 + +```python +def get_tc_subtask_summary(tc_db: Path, parent_issue: int) -> Optional[dict]: + """TC 路径:从 task_state 表查子任务状态摘要""" + conn = get_connection(tc_db) + try: + parent_row = conn.execute( + "SELECT round_count, status FROM task_state WHERE issue_number = ?", + (parent_issue,) + ).fetchone() + if not parent_row: + return None + + rows = conn.execute( + "SELECT status, COUNT(*) as cnt FROM task_state " + "WHERE parent_issue = ? GROUP BY status", + (parent_issue,) + ).fetchall() + if not rows: + return None + + summary = { + "parent_id": str(parent_issue), + "parent_status": parent_row["status"], # 从 task_state 读取实际状态 + "round_count": parent_row["round_count"], + "total": 0, "done": 0, "failed": 0, "cancelled": 0, "other": 0, + } + for row in rows: + summary["total"] += row["cnt"] + if row["status"] in ("done", "failed", "cancelled"): + summary[row["status"]] += row["cnt"] + else: + summary["other"] += row["cnt"] + summary["all_terminal"] = summary["other"] == 0 and summary["total"] > 0 + return summary + finally: + conn.close() +``` + +### TaskState round_count 同步 + +TC 路径的 `round_count` 存在 `task_state` 表中。`_check_round_complete` 需要在 spawn review 成功后递增: + +```python +if handler and handler.virtual_project == "_toolchain": + # TC 路径:递增 task_state.round_count + conn.execute("UPDATE task_state SET round_count = round_count + 1 WHERE issue_number = ?", ...) +else: + # 黑板路径:原有 bb.increment_round_count(parent_id) +```