diff --git a/docs/design/13-toolchain-and-dev-workflow.md b/docs/design/13-toolchain-and-dev-workflow.md index acd8e06..a3881d3 100644 --- a/docs/design/13-toolchain-and-dev-workflow.md +++ b/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 模板(流程强约束固化)