From 946f7e184859e4663bb3d136a7e9226e860a74e8 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Sat, 13 Jun 2026 23:08:50 +0800 Subject: [PATCH] =?UTF-8?q?fix(design):=20=C2=A717=20M1=20=C2=A75.2=20?= =?UTF-8?q?=E4=B8=89=E5=88=86=E8=B7=AF=E5=B1=95=E5=BC=80=20+=20M2=20?= =?UTF-8?q?=E7=BA=A6=E6=9D=9F=E7=BC=96=E5=8F=B7=20#5=20+=20S1/S2=20?= =?UTF-8?q?=E4=B8=80=E8=87=B4=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../17-toolchain-handler-enforcement.md | 28 +++++++++++++++---- 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/docs/design/17-toolchain-handler-enforcement.md b/docs/design/17-toolchain-handler-enforcement.md index e6b4261..39f36d0 100644 --- a/docs/design/17-toolchain-handler-enforcement.md +++ b/docs/design/17-toolchain-handler-enforcement.md @@ -222,7 +222,7 @@ class ToolchainContextSection: - action report 就是你的完成凭证 - 不要发送 Mail（飞鸽传书），你的所有操作在 toolchain 流程内完成 -### 6. 所有协作通过 Gitea 完成 +### 5. 所有协作通过 Gitea 完成 - 如果遇到问题需要其他角色支持，在关联的 PR/Issue 上创建 comment @对方 - 不要使用 Mail API（飞鸽传书）发送消息 - 你的所有操作都在 toolchain 流程内，通过 Gitea 留痕 @@ -373,11 +373,25 @@ def verify_completion(self, task_id: str, db_path: Path) -> VerifyResult: ### 5.2 on_failure 处理 -verify 失败时的处理逻辑（现有逻辑保留）： +**设计原则**：toolchain 事件全生命周期在 toolchain 流程内闭环，不走 Mail API。失败本身按错误类型分类，路由到不同的 Gitea 管理动作。 -1. 标 task 为 `failed` -2. 通过 on_failure 三分路处理（PR comment / Gitea Issue / toolchain task） -3. 通知内容包含：事件类型、事件详情、失败原因、Gitea 链接、行动指引 +#### 错误分类三分路 + +| 错误类型 | 例子 | 处理方式 | 管道 | +|---------|------|---------|------| +| **业务失败** | verify 不过（no action_report）、Agent 忽略步骤 | 在关联 PR/Issue 上创建 comment @原始 assignee | Gitea webhook → §25 @mention → toolchain task | +| **系统失败** | spawner crash、timeout、max_retries、业务失败连续 3 次 | 创建 Gitea Issue 指派 pangtong-fujunshi | Gitea webhook → issue_assigned → toolchain task | +| **基础设施失败** | Gitea API 不可用、网络不通 | `_send_toolchain_task` 直接创建 toolchain task 指派 jiangwei-infra | toolchain 内部直接创建 | + +三条路全在 toolchain 流程内，Mail 完全不参与。 + +#### 防递归保护 + +基础设施失败创建的 toolchain task（action_type=infrastructure_failure），其 verify_completion 始终返回 `VerifyResult(True)`，不再触发 on_failure。 + +#### 完整设计 + +三分路的详细伪代码、失败上限、决策依据见 §5.2.1~§5.2.3（on_failure 分路处理详细设计）。 ### 5.3 action_report comment 格式 @@ -421,7 +435,7 @@ Agent 可能写了 action_report 但没真做。缓解机制： | Issue 指派 → 开发者 | issue_assigned | toolchain | 6 步 | 创建分支 + 编码 + push + CI + PR + report | | 部署失败 → 运维 | deploy_failure | toolchain | 4 步 | 查日志 + 排查 + 修+重部署 + report | | @mention → 被@者 | mention | toolchain | 按 guidance | 按 mention 模板的 response_guidance + report | -| PR 合并 → PR 作者 | review_merged | toolchain | 0 步 | 纯通知，走 Gitea PR comment（verify 始终通过） | +| PR 合并 → PR 作者 | review_merged | toolchain | 0 步 | 纯通知，走 _send_toolchain_task（steps 为空，verify 始终通过） | **D17-2: 所有 toolchain 场景走 ToolchainHandler** @@ -561,6 +575,8 @@ context: **实现差异**：review_merged 的 verify_completion 始终通过（`VerifyResult(True)`），不需要 action_report。这是 ToolchainHandler 内部的语义区分，不影响 MailHandler。 +**spawn 说明**：review_merged 仍会触发 spawn（Agent 只需阅读通知），verify auto-pass 后标 done。未来可优化为 ticker 直接 auto-done 跳过 spawn。 + --- ## §7. _send_toolchain_task 函数设计