让修复缺陷的智能体交出验证证据

把修 Bug 交给 AI，难点在于如何让它按规矩办事，并交出能验收的结果。Sharkly 团队给修复 Agent Sherlock 设计了一套固定流程：先诊断，再审批，再修改，最后拿真实运行证据接受复核。

作者给出的内部数据是：最近 15 天，Sherlock 完成了全部 Sharkly 任务的 13%；最近分配给它的 100 个任务里，90 个成功完成。这套经验值得看，但成功率的统计口径、任务难度，以及流程究竟靠什么强制执行，仍有需要追问的地方。

一次滚动条修复，为什么需要两次人工确认

案例是一个具体的 UI 缺陷：Clear Build Cache 对话框里的临时目录列表太长，超出可用空间，却无法滚动。

Oliver 在内部 Slack 报告问题，Emma 让 Sharkly Task Assistant 整理成任务，再分配给 Sherlock。Agent 花了 14 分钟复现问题、追踪实现并定位原因，接着列出三个需要人决定的实现选项。

Emma 选择推荐方案，并用下面的消息授权开发：

1A 2A 3A [START DEVELOPMENT]

关键是末尾的 [START DEVELOPMENT]。前面的选项表达方案选择，后面的精确令牌才允许 Agent 修改产品代码。普通的「继续」「看起来不错」不算授权。

又过了 37 分钟，Sherlock 报告实现和验证完成，并提交修复截图供检查。

Emma 检查结果后，发送第二个令牌：

[SUBMIT FOR TESTING]

这一行授权最终提交、推送、目标分支操作和任务状态更新。案例中，代码随后合入开发分支，任务进入自动化测试流程。

两个节点承担不同责任：第一次判断方案是否值得实施，第二次判断完成的改动是否可以进入团队交付流程。中间的读代码、运行命令、实现和验证，由 Agent 自主完成。

这也限定了案例的结论：它证明了一次修复如何走完流程，没有证明同样的审批成本适合所有 Bug。

可靠性如何落到文件和状态转换上

Sherlock 使用共享开发 Computer，运行在 oh-my-pi Runtime 上，模型是 GPT 6 Astra。Sharkly 管理任务、对话、执行记录和审批；Computer 提供仓库、依赖、浏览器及其他工具。

作者把 Agent 和 Runtime 分开：Agent 保存身份、指令、Skills 和操作规则，Runtime 则是实际执行工作的编码工具。Claude Code、Codex 等工具可以承担这个执行角色。

更关键的是，Sherlock 被定义为一个十阶段状态机。大白话理解，就是每一步都有入口条件、允许的动作和交付物，不能因为「已经知道怎么改」就跳到下一步。

初始化时，它先核对任务信息、工作区和基线分支。紧急任务可能基于 main，高优先级任务可能基于 staging，其他任务通常跟随仓库默认集成分支。这是他们团队的分支策略，不宜直接照搬。

随后是诊断与方案阶段：

• diagnosis.md 保存复现过程、根因和证据，期间禁止修改产品代码。
• idea.md 保存解决方案、需要保持的行为和待确认选项；涉及用户文案时，要先读术语与本地化规则。
• 收到开发授权后，才进行实现探索，产出 findings.md 和 plan.md；偏离计划的内容写入 plan-delta.md。

实现完成后，还有独立审视、修补、真实验证、等待测试审批和提交测试等阶段。审查结果放入 review-report.md，最终交付与验证信息写入 ship-summary.md。

聊天里说「完成了」，不能代替阶段交付物。

流程状态持久化在 state.json 中。每次有效转换要记录前后阶段、转换原因、关联文件和哈希；涉及审批时，还要记录令牌及获批方案的准确版本。会话中断后，新的运行从磁盘恢复状态，不靠聊天记录猜进度。

如果 state.json 丢失、损坏或自相矛盾，要求是停止并报告，不能补猜审批、手动跳关。

这套流程还规定了信息优先级：Agent 指令与明确的人类决策，其次是 AGENTS.md、文档和分支策略，再到任务及获批方案，最后是源码和运行证据。作者强调，仓库事实要优先于模型的通用记忆；文档、代码和运行行为冲突时，必须把冲突摆出来。

另外，主指令之外还有七个阶段专用 Skills。进入阶段前要完整阅读并记录，产物也必须体现执行要求。原文没有列出这七个 Skills 的具体内容，因此它提供的是组织方法，还不是一份能直接复用的完整配置。

测试通过之后，还要证明什么

Sherlock 写完代码，先同步权威基线分支，再做 clean-room review。这里指暂时放下实现时的假设，尝试以独立审查者的视角检查改动，包括根因是否解决、调用点是否遗漏、测试是否覆盖风险，以及是否混入无关修改。

它仍然是同一个 Agent。这个步骤提供了重新审视的机会，但不能直接等同于独立人员或另一模型的审查。

发现阻塞问题后，Agent 修补、重新同步基线，再审查。最多循环六次，第六次后仍有阻塞问题就停止，交给人处理，避免无限自修。

验证也分两层：先运行仓库声明的测试套件，再检查实际改变的行为。UI 改动需要真实界面证据；后端改动需要 API 响应、日志、查询或命令输出。

命令以状态码零退出，只能证明这条命令成功结束。

对于滚动问题，测试通过还不够，审核者需要看到长列表确实可以滚动。作者进一步要求，截图必须直接出现在对话里，不能只给一个需要手动寻找的文件路径。证据应该出现在做决定的位置。

提交前的测试包还包括实现摘要、代码 diff、自动决策、测试结果、预览链接，以及视觉或运行证据。每次回复则附带任务、阶段、待审批令牌、审查次数和产物路径，让人能看清当前进度。

我的判断

我认可它把人工注意力集中到两个信息充分的节点。早期版本有七个人工审批关卡，后来缩减为两个。对于边界明确的小任务，这比每跑几个命令就停下来确认，更有机会减少监督负担。

单 Agent 的选择也有道理。诊断、实现和验证紧密依赖同一份仓库上下文，拆成多个 Agent 会增加信息交接。作者建议先用单 Agent 加强 Skills，只有职责能清楚拆分时才引入 Crews。

但原文没有给出单 Agent 与多 Agent 的成本、耗时或质量对照。团队虽然用相同真实任务测试过 Claude Code、Codex CLI、OpenCode 和 oh-my-pi，却也没有公开对比结果。选择 oh-my-pi 的理由是指令与工具控制、会话重放恢复，以及共享 Computer 上的轻量并发。这是针对他们工作负载的经验判断。

90/100 的成功率同样需要保留统计边界：成功如何定义、后续有没有回归、失败任务有什么特征，原文都没交代。15 天内完成全部任务的 13%，也不等于节省了 13% 的工程工时。

还有两处实现问题需要问清。第一，状态机和权限边界究竟由外部工具强制限制，还是主要依靠模型遵守指令？原文没有充分说明。持久化文件能帮助恢复，却不自动构成权限隔离。

第二，作者一处说推送需要 [SUBMIT FOR TESTING]，另一处又说提交前会推送专用远程审查分支。审查分支是否存在单独授权例外，文中没有解释。团队落地前必须消除这个歧义。

能拿来做什么

• 给日常 AI 修复任务增加明确的诊断产物，先要求记录复现条件、根因和证据，再讨论实现。前端溢出、交互异常这类问题尤其适合这样处理。
• 把方案审批与交付审批分开，并让审批关联具体版本。方案发生变化后，应能看出原授权覆盖哪些改动。
• 为前端和 Node 改动分别定义验收证据：前端提供真实界面截图或浏览器操作结果，Node 提供对应 API、日志或实际执行结果，测试报告作为其中一部分。
• 先从范围小、验收明确的任务试运行单 Agent 流程，记录失败原因和人工介入成本，再判断是否需要增加 Skills 或拆分职责。