auto-sync: 2026-06-06 11:07:17

docs/design/13-toolchain-and-dev-workflow.md

@@ -1200,16 +1200,57 @@ async def handle_gitea_webhook(event: dict, x_gitea_event: str = Header(...), x_
 - 简单事件（CI失败通知、Review通知、任务指派）直接发 Mail
 - 复杂事件（部署失败、架构级 Review 问题）spawn 庞统
 
-### §15.4 超时检测与失败处置
+### §15.4 回复驱动与超时处置
 
-**检测机制**：daemon ticker 中新增一个定时扫描任务（每小时跑一次）
+> daemon ticker 中新增两个定时扫描任务，**回复驱动是主路径，超时检测是兜底**。
+
+**主路径：回复驱动（Agent 回复 Mail 后，daemon 根据结果触发下一步）**
+
+```python
+# daemon ticker 每小时跑一次
+async def process_flow():
+    # 路径1：扫描新回复，驱动下一步（主路径）
+    await check_replies()
+    # 路径2：扫描超时未回复，兜底处置
+    await check_stale_flows()
+
+async def check_replies():
+    """扫描 Mail 回复，根据结果触发下一步"""
+    # 查所有有新回复的 Mail（回复在上一轮扫描之后）
+    replied_mails = queries.find_recently_replied(since=last_scan)
+    
+    for mail in replied_mails:
+        reply = get_reply(mail.id)
+        
+        if is_success_reply(reply):
+            # 成功 → 记录闭环，不触发动作
+            # 原因：Gitea 自动化（Actions + Webhook）会自动推动下一步
+            # 例：张飞回复"已创建PR" → Gitea Webhook 自动通知司马懿 Review
+            # 例：张飞回复"已merge" → Gitea Actions 自动触发 deploy
+            log.info(f"Mail {mail.id} 已成功闭环: {reply.text[:100]}")
+        
+        elif is_failure_reply(reply):
+            # 失败 → 创建 Issue 走正式流程
+            await create_issue(
+                title=f"执行失败: {mail.title}",
+                labels=["bug"],
+                body=f"原指令: {mail.text}\n\n失败原因: {reply.text}"
+            )
+            # 通知庞统
+            await send_mail(to="pangtong-fujunshi",
+                          title=f"执行失败已创建 Issue: {mail.title}", ...)
+        
+        elif is_help_reply(reply):
+            # 需协助 → spawn 庞统协调
+            await spawn_agent("pangtong-fujunshi",
+                f"Agent {reply.from} 执行 '{mail.title}' 遇到困难，请求协助。详情: {reply.text}")
+```
+
+**兜底路径：超时检测（Agent 没回复时的处置）**
 
 ```python
-# 在 daemon ticker 中
 async def check_stale_flows():
     """扫描超时未回复的 Mail，按个性化 deadline 判断"""
-    # 1. 查所有 type=request 且无 in_reply_to 回复的 Mail
-    #    每个 Mail 创建时在 metadata 中记录 deadline（基于 Mail 模板的时限）
     pending_mails = queries.find_pending_requests()
     
     for mail in pending_mails:
@@ -1232,7 +1273,7 @@ async def check_stale_flows():
                             f"流程卡住: Mail {mail.id} '{mail.title}' 超时 {hours_overdue:.0f} 小时未回复。请介入协调。")
         
         else:
-            # 严重：创建 Issue + 通知主公
+            # 严重：创建 Issue + 通知庞统
             await create_issue(title=f"流程严重超时: {mail.title}", labels=["blocked", "priority:high"])
             await send_mail(to="pangtong-fujunshi", 
                           title=f"严重超时: {mail.title}，已创建 Issue", ...)
@@ -1247,6 +1288,7 @@ async def check_stale_flows():
 **断点续传**：
 - 每个环节的状态都在 Gitea 上（PR 状态、CI 结果、Review 状态）
 - Mail 线程提供完整的可追溯记录
+- 回复驱动确保正常流程自动推进，超时检测确保异常被捕获
 - 流程卡住时，庞统可以根据 Mail 线程 + Gitea 状态快速定位断点并继续
 
 ### §15.5 Mail 模板（流程强约束固化）