3441 字
17 分钟
让 Agent 自己修 bug:狄仁杰的状态机、阶段产物与两道人工门

原文:AI-native 实践:HiFox 团队如何让 Agent 自动修 bug

来源:HiFox 团队,2026-11-04

HiFox 的人一般不怎么修 bug,大部分直接交给 Agent。他们有一个专门修 bug 和做小需求的 Agent,叫「狄仁杰」,能描述和讨论问题、进代码仓库查找实现、在运行环境里执行测试;涉及界面变化时还会打开浏览器验证操作并保留截图。

过去 15 天里,HiFox 团队完成的所有任务中有 13% 是狄仁杰做的;分配给它的最近 100 个需求,90% 顺利完成。它跑在团队的共享开发机上,用 oh-my-pi Runtime 和 glm-5.3 模型,每天接几十个 bug 和小需求。

一个实际案例:同事发现「清理构建缓存」弹窗里的临时目录列表无法滚动,把问题发到内部吐槽飞书群,另一位同事 @HiFox 任务助手让 Agent 建任务。狄仁杰接手后跑了 14 分 1 秒,定位到原因,提出三个需要确认的决策。用户回「1A 2A 3A 【进入开发】」之后,它工作 37 分钟完成开发和验证,交付代码 PR、预览链接、修复后的截图。人看材料确认修好了,回「提测」,代码合入开发分支,进入自动化测试。

整个过程人只在两个节点做判断,其余时间不用跟 Agent 反复对话确认细节。

十个阶段#

狄仁杰的流程从前到后十步,其中第 4 步和第 9 步是停下来等人给令牌的等待阶段。

阶段做什么
1. 初始化检查任务编号、标题、描述和标签,确认自己在 HiFox 的任务工作区,再按优先级确定基线分支:紧急任务可能用 main,高优先级可能用 staging,其余通常跟随仓库默认集成分支
2. 诊断只复现问题、收集证据、找根因。即使修法已经很明显也不能改代码,结果必须写进 diagnosis.md
3. 起草方案说明准备改什么、哪些行为保持不变、还有哪些问题要用户选。涉及用户可见文案要先读仓库里的术语表和本地化规则,准备多个候选说法;用户反馈后继续精化 idea.md
4. 等待【进入开发】第一个等待阶段。已经知道怎么修,但没有改产品代码的权限。只有这个令牌有效,「继续」「可以」「按这个做」都不行
5. 实现探索与实现读相关文件、查调用关系、确认现有测试和仓库惯例,生成 findings.md 与 plan.md,再按批准的想法改代码。计划外的变化记在 plan-delta.md
6. 净室评审同步权威基线后进入评审。所谓净室,是暂时放下实现者的思路,用评审者的标准重新检查改动:根因是否真的解决、调用方是否全部迁移、测试是否覆盖风险、代码里有没有残留的旧路径
7. 修补评审发现阻断问题就修,修完重新同步基线再做一次净室评审。这个循环最多六次,六次后仍有阻断就停掉自动流程,转人工
8. 验证跑仓库声明的测试,并按改动性质检查真实页面、接口、日志或命令行为。测试命令退出成功只说明检查通过了一部分;界面改动要真实界面证据,后端改动要留下与运行行为相符的记录
9. 等待【提测】整理提测包,进入第二个等待阶段。用户审阅改动、证据和自动决策后发【提测】,这个令牌授权创建最终提交、推送代码、执行目标分支操作,并把任务更新到待测试状态
10. 执行提测合并代码到开发分支,任务状态改成「待测试」,等测试 Agent 接手

六次修补上限是为了防止 Agent 在自己写、自己审、自己修的循环里一直跑下去。

指令是一套状态机#

狄仁杰的指令读起来像一份可以自动执行的开发规程,本质是一套工程化的「单 Agent 缺陷修复状态机」。Agent 大部分时间独立工作,但决定不了两件事:什么时候开始改代码,什么时候把代码提交到目标分支。

指令由八部分组成:

部分规定
角色与边界只处理当前分配的 HiFox 任务,不允许自己找别的任务、创建替代任务或调用其他 Agent,禁止跨阶段工作
权威顺序信息冲突时,Agent 指令和人工决策优先,其次是仓库里的 AgentS.md、文档和分支政策,最后才是任务描述、批准后的方案、代码和运行证据。模型记得某个框架通常怎么配,不能证明这个仓库也该这么配;仓库声明了测试命令和分支规则,就得照着执行。文档、代码和运行行为互相矛盾时,要把冲突暴露出来,不能挑最方便的解释继续
持久化状态机初始化之后,state.json 是判断当前阶段的唯一依据,每次行动前都要读取校验,同一时间只能有一个活动阶段。文件里除了阶段,还存任务信息、等待的人工确认、已批准的决策、阶段产物和验证状态。每次合法的阶段变化都写历史,包括原阶段、新阶段、迁移原因、相关文件及哈希;需要人工许可时,还要存令牌和当时被批准的方案版本。会话中断后,新的运行不会靠聊天记忆猜上次做到哪,而是重新读状态文件和产物;文件缺失、损坏或内容矛盾时,Agent 停止并报告状态错误,不能手工把阶段改到后面,也不能根据聊天内容补造一条丢失的批准记录
人工门两道门控制两类高影响操作。【进入开发】管产品代码写入,【提测】管提交、推送和任务状态修改。风险被切成两段:改代码一段,把改动送到远端并影响团队流程一段。两道门之间 Agent 可以干大量活,但越不过这两条边界
阶段产物每个阶段有对应文件。诊断出 diagnosis.md,方案用 idea.md,实现前出 plan.md,评审结果写 review-report.md,全部通过后交付信息写 ship-summary.md。缺文件就不能宣称这个阶段完成,聊天里写一句「诊断完成」没有效力
阶段专属 Skill主指令管流程、权限和迁移条件,具体阶段的做法交给七个 Skill:lattice-diagnose、lattice-idea、lattice-explore、lattice-implement、lattice-review、lattice-verify、lattice-deliver。进入新阶段前必须完整读取对应 Skill,并把读取记录写进状态历史;产物也要符合 Skill 规定的格式,光记录「已读取」不够
验证与提测提测前把工作分支推到专用的远端评审分支,给 Compare 链接,人可以看实际代码差异和验证材料
回复格式回复必须包含实际完成的工作、当前阶段和下一步人工动作,末尾强制带状态页脚,写清任务、阶段、等待令牌、评审次数和产物路径

净室评审和证据链#

这套流程里最较真的两处是净室评审和验证。

净室评审要求评审者暂时忘掉实现者的思路,按评审标准重新看:根因是不是真的解决了,调用方是不是都迁移了,测试是不是覆盖了风险,代码里有没有留下旧路径。发现阻断就回到修补阶段,重新同步基线后再评审一次。

验证阶段对证据的要求更高。测试命令跑通只能证明测试通过,证明不了功能在真实环境里可用。用户能看到的功能要在实际页面或应用里检查,后端改动要留接口、日志、查询结果或运行命令的证据。提测前还要推一个远端评审分支出来,让人能看真实 diff。

为什么没走多 Agent#

HiFox 的「小队」功能本身就能做多 Agent 协作,他们讨论过用多个 Agent 完成整个开发过程,最后还是选了单 Agent 状态机。原因是修 bug 这个场景用当前的模型能力,单 Agent 已经够用,多 Agent 更耗时也更贵。多 Agent 小队更适合有多个明确专业分工、步骤之间耦合度低的事务。文章也引了 Anthropic 的建议:尽量用带 Skill 的单 Agent,而不是拆成多个子 Agent。

Runtime 选型用同一批真实任务试了 Claude Code、Codex CLI、OpenCode 和 oh-my-pi,最后选 oh-my-pi。理由有四个:

  • 指令完全可控。状态机的前提是行为可预期,Runtime 不能夹带隐藏提示词,也不能好心自动重试、自动继续、压缩上下文,这些对人类用户贴心,对状态机是干扰。oh-my-pi 的系统提示、工具集和执行循环都能被完全接管,出了问题能归因。
  • 工作过程可回放。偶尔结果不对、要深挖原因时,可以导出 ACP session 完整回放:哪一步在反复试探、哪条指令没被遵守、上下文在哪里膨胀。狄仁杰流程上的不少优化点就是从回放里发现的。
  • 会话可持久化和恢复。一个任务动辄几十分钟,中间会中断重启,oh-my-pi 支持断点恢复。这跟 state.json 的设计正好咬合:状态在文件里,上下文在会话里,两边都接得上。
  • 轻量、可并发、开源可修。共享开发机上每天几十个任务并行,几十个实例同时跑没有压力,也没有按席位付费的成本,出了问题可以直接读源码打补丁。

文章也标了边界:这些工具都在快速迭代,结论只针对「无人值守跑状态机」这一个场景;如果目标是给人做交互式编程助手,选择可能完全不同。

迭代出来的四条经验#

这套流程不是一次设计出来的,是踩坑之后做减法做出来的。

  • 用已经验证可靠的 Skill。Agent 的稳定下限由工具决定,未经验证的指令每次执行路径都可能不一样,出了问题也难归因。新写的 Skill 必须先在低风险任务上跑通才能进正式流程。
  • 人工门尽量少。早期版本设了 7 道门,Agent 走几步就停下来等人,人被反复打断。后来减到 2 道,只留风险最高的【进入开发】和【提测】。门少了反而更容易守住:人在信息完整的少数节点做判断,比在过程里频繁点头可靠。
  • 自然语言不解锁,必须用明确指令。自然语言的含义会随上下文漂移,Agent 可能把一句客套话当成批准。把授权收敛成无歧义的令牌,事后还能在状态历史里核对是谁、在哪个方案版本上给的授权。
  • 必须有截图,而且贴进会话。涉及界面的改动,截图是硬性要求,并且要直接贴进对话,不能给个文件路径让人自己去找。人做提测决策的依据应该出现在决策发生的地方,要点开好几层目录才能看到的证据等于没有证据。

和「折叠子 Agent」那篇对读#

我这次一起读的 Anthropic 那篇讲的是把子 Agent 收回主循环,用 Skill 和工具做渐进披露,减少 lossy handoff 和延迟。狄仁杰是另一种方向的极端:主循环本身被约束成状态机,阶段、权限、迁移条件全部写死在指令和 state.json 里,模型只负责每个阶段内部的判断和执行。

我的判断是这两种做法解决的不是同一个问题。Anthropic 在优化「一个 Agent 能不能处理更多种类的事」,所以要把结构做轻,把判断交还模型;狄仁杰在优化「一类高风险任务能不能稳定、可核对地重复执行」,所以要把结构做重,把判断锁进流程。前者适合任务边界模糊、需要探索的场景,后者适合步骤固定、错误代价高、必须留证据的场景。修 bug 恰好落在后者:根因分析要探索,但改代码、提测、合分支这些动作不能由模型临场决定。

代价这部分是我的判断:状态机和阶段产物要维护,指令和 Skill 要持续验证,任务类型一变流程就得跟着改。文章里那句「修 bug 只是起点」后面还有半句,同样的纪律正在复制到需求开发、测试和发布;能不能复制成功,取决于那些环节的步骤是否也足够稳定。

参考#

相关阅读#

让 Agent 自己修 bug:狄仁杰的状态机、阶段产物与两道人工门
https://blog.xqcherry.top/posts/ai/agent-bugfix-state-machine/
作者
xqcherry
发布于
2026-11-09
许可协议
CC BY-NC-SA 4.0