Hermes + Chrome + OpenCode：我用 AI Agent 修 bug 的工作流

最近在维护一个 Web 项目时，摸索出了一套用 AI Agent 定位问题、修复代码、复核验证的工作流。踩了不少坑，但也确实解决了不少用传统方式很难定位的问题。记录一下这套流程，顺便对比一下跟纯用 OpenCode 的差异。

工作流概览

整套流程分三步：

  1. 问题定位：用 Hermes Agent + Playwright（Chrome 无头浏览器）结合项目源码，精准定位问题根因
  2. 代码修复：把定位到的问题交给 OpenCode 修复
  3. 复核验证：用 Hermes Agent 再次通过浏览器验证修复效果

每一步都有不少细节，用实际案例说明。

案例一：卡片显示不全

问题

项目有一个 Canvas 功能，用户可以创建工具卡片。某次创建了一个卡片后，页面显示「共 1 个工具」，但实际看不到任何卡片。

定位过程

直接用 OpenCode 描述这个问题：「卡片创建成功但不显示」，它会怎么处理？

它会猜测：可能是模板问题、可能是数据问题、可能是 CSS 问题……然后开始一通修改。但问题在于，它不知道问题出在哪里。

用这套工作流就不一样了：

  1. 浏览器先看：用 Playwright 打开页面，提取 DOM 结构，发现页面确实有 canvas_list 数据，但卡片没有被渲染
  2. 源码对照：让 Hermes Agent 读取模板文件，发现模板是按 categories 循环渲染的
  3. 精准定位：创建卡片时用的 category 是 tech，但模板只接受 tool、game、visual 等预定义值。tech 不在列表里，所以被跳过了

问题根因：API 没有校验 category 合法性，模板渲染时又静默忽略了无效值。

修复

定位清楚后，交给 OpenCode：「把 category 改成 tool，然后通过 admin 重新发布」。修复过程变得很简单。

复核

用 Hermes Agent 再次打开页面，确认卡片正常显示。

案例二：iframe 嵌入空白

问题

Canvas 有一个预览功能，用 iframe 嵌入原始 HTML。预览页面加载后，iframe 区域是空白的。

定位过程

这个问题如果只告诉 OpenCode「iframe 空白」，它会怎么猜？

  • 可能是 iframe src 错误？
  • 可能是跨域问题？
  • 可能是 CSS 隐藏了？

但实际上，问题出在 HTTP 响应头：

  1. 浏览器抓包：用 Playwright 查看控制台，发现报错：Refused to display in a frame because it set 'X-Frame-Options' to 'deny'
  2. 源码追踪：找到 shared/security_headers.py，发现所有服务都设置了 frame-ancestors 'none'
  3. 精确定位：Canvas 的 /raw/{slug} 路由继承了这个安全策略，导致 iframe 被浏览器阻止

问题根因：全局安全策略与 Canvas 自身的 iframe 嵌入需求冲突。

修复

交给 OpenCode：「在 /raw/{slug} 路由中覆盖安全头，设置 X-Frame-Options: SAMEORIGIN 和 frame-ancestors 'self'」。

注意：不是修改全局的 shared/security_headers.py，而是只在这个路由里覆盖。OpenCode 如果没有明确的上下文，可能会改错地方。

案例三：编辑后卡片消失

问题

通过管理后台编辑一个已发布的 Canvas 后，它从首页消失了。

定位过程

  1. 浏览器验证：用 Playwright 登录管理后台，编辑一个 Canvas，然后回到首页——确实看不到了
  2. 源码分析：让 Hermes Agent 读取 admin 路由代码，发现编辑表单提交后，后端总是设置 draft=True
  3. 确认根因：admin 编辑功能没有保留原有的 draft 状态，编辑后自动回到草稿状态

修复

这个问题其实不需要改代码，只需要调整操作流程：编辑后手动点击「发布」按钮重新发布。

但如果只告诉 OpenCode「编辑后卡片消失」，它可能会去改代码逻辑，而不是告诉你这是操作流程的问题。

这套流程 vs 纯用 OpenCode

纯 OpenCode 的方式

用户描述问题 → OpenCode 猜测原因 → 尝试修改 → 失败 → 再猜 → 再试……

优点： - 简单直接，不需要额外工具 - 适合问题明确、根因清晰的情况

缺点： - 信息不对称：OpenCode 不知道页面实际长什么样，只能靠你描述 - 猜测成本高：一个「iframe 空白」可能有十几种原因，每次猜测都是一次代码修改 - 容易改错地方：没有源码对照，OpenCode 可能改了不该改的文件 - 复核困难：改完后还是需要人去验证

Hermes + Chrome + OpenCode 的方式

Hermes 浏览器定位 → 源码对照 → 精确描述问题 → OpenCode 修复 → Hermes 复核

优点： - 定位准确：浏览器能看到实际页面状态、控制台报错、DOM 结构 - 源码对照：能把页面表现和代码逻辑关联起来 - 修复精确：给 OpenCode 的指令是「改哪个文件的哪一行」，而不是「帮我修这个问题」 - 可复核：修复后自动验证

缺点： - 需要配置 Playwright 和浏览器环境 - 定位阶段耗时较长（但总体更快） - 需要 Agent 有文件系统和终端访问权限

什么时候用哪种

  • 纯 OpenCode：问题明确、改动范围小、不需要看页面状态。比如「把按钮颜色改成蓝色」
  • 这套工作流：问题模糊、涉及多文件、需要看实际渲染效果、有交互行为。比如「页面显示异常」「功能不工作」

实际收益

用这套流程处理了十几个问题后，几个感受：

  1. 定位时间缩短：以前需要人肉排查半小时的问题，现在 5 分钟内能找到根因
  2. 修复准确率提高：OpenCode 接到的指令更精确，改错地方的概率大幅下降
  3. 复核成本降低：不用每次改完都手动去页面点一遍

最大的收益是减少了「猜测-试错」的循环。以前用 OpenCode，经常是「改了 A，发现 B 也坏了，改 B，发现 C 也坏了」。现在是先定位清楚再改，一次到位。

配置要点

如果你想搭建类似的工作流，几个关键配置：

  1. Playwright 浏览器：需要安装 Chromium，服务器上推荐用 headless 模式
  2. Agent 权限：需要文件系统读取权限（看源码）和终端执行权限（运行浏览器）
  3. 项目结构：Agent 需要知道项目根目录，方便在页面表现和源码之间切换
  4. 调试信息：浏览器控制台日志、网络请求、DOM 结构，这些都是定位问题的关键信息

总结

AI 辅助开发不只是「让 AI 写代码」。真正提高效率的是让 AI 帮你定位问题和验证修复。

纯用 OpenCode 这类编码 Agent，本质上还是「人告诉 AI 问题在哪，AI 去改」。而这套工作流是「AI 自己找问题，AI 自己改，AI 自己验证」。人的角色从「问题描述者」变成了「决策者」——只需要在关键节点做判断，不用事无巨细地描述问题。

当然，简单的改动用 OpenCode 就够了，复杂的架构问题还是需要人来主导。但对于日常的 bug 修复，这套流程省了不少来回。