前言¶
在 DSH 里让 agent 修前端 bug 时，常见做法是口述复现步骤，或手写 Playwright 脚本。前者容易漏掉「正确应该是什么」，后者往往和真实用户操作脱节，修完后也难以证明跑的是当前工作区里的补丁。BugGPS 是 DeepSeek Harness 的工作流类插件：你在浏览器里把问题操作一遍并标出预期，插件把它锁成会失败的检查；agent 改代码后，由 BugGPS 自己启动应用、按原条件重放，只有全部检查通过才给出 VERIFIED。
这是什么¶
BugGPS（仓库名 dsh-bug-gps）由维护者 lijiaqi-AI-Product-Manager 发布，分类为工作流。一句话定位：录下问题，按原预期复核修复（Record the bug. Verify the fix against the original expectation.）。当前为预发布状态，尚未发布到 npm；README 记载的安装与流程在 DSH 0.2.1-rc.5 / Windows 11 上已用本地 checkout 或 npm pack 包实测。
社区目录页：https://www.skillhub.cn/plugins/lijiaqi-AI-Product-Manager/dsh-bug-gps
源码与文档：https://github.com/lijiaqi-AI-Product-Manager/dsh-bug-gps
DSH 生态理念是「一切皆插件」；SkillHub 等目录为社区站点，与 DeepSeek / 幻方无官方从属关系。
核心流程与工具¶
下面介绍插件在 DSH 会话里暴露的主线，对应 README 中的四步。
1. 录制（buggps_record）¶
浏览器打开后，你操作一遍，在工具栏上标注：
- 预期：文本、输入值、应可见、应消失、不应报错。若先标「不应报错」再标正向预期，两者都会保留。
- 检查点（可选）：「此刻页面应为 …」。修复前后都必须成立，防止修复绕过录制情境；缩减步骤时也不会删掉。
- 关键步骤（可选）：缩减时永远保留。
密码、验证码、卡号等敏感字段不会写入录制，只存引用；重放时从环境变量 BUGGPS_SECRET_<名字> 读取。
2. 锁定（buggps_lock）¶
BugGPS 用配置里的 serve 命令自己启动应用，在当前代码上重放 3 次；3 次都以同一种方式失败才锁定。锁定用例带内容哈希并写保护，同时尝试缩短步骤（只靠重放，不调用模型）。
3. 修复¶
由 DSH agent 用常规工具改代码，插件不替代这一环。
4. 验证（buggps_verify）¶
BugGPS 再次从工作区启动应用，重放完整录制 3 次。每次在最后一步之后须持续满足全部检查（默认观察 1000 ms，见 observeMs）。
录制范围包括点击、输入、选择、勾选、回车、Escape，以及确实打开了菜单的悬停；不记录拖拽和全局键盘输入。每次启动应用后会先完整重放一次作预热（宽松超时、结果丢弃），便于 Vite 等按需编译；因此录制里的操作不应改动服务端持久数据，目前面向状态在浏览器内、每次可重置的应用。
配置：buggps.config.json¶
在仓库根目录放置配置，示例：
{
"serve": {
"command": ["npm", "run", "dev", "--", "--port", "5199", "--strictPort"],
"url": "http://127.0.0.1:5199/"
},
"observeMs": 1000
}
serve 是 BugGPS 自行执行的命令，只接受 localhost。端口应与你平时开发用的不同：录制时你的 dev server 照常跑；锁定和验证时 BugGPS 用自有端口。端口被占用时报 ENV_BLOCKED，不会误用其它服务器的结果。锁定时 serve 会写入用例并参与哈希，之后改配置文件不影响已锁定用例。
判定结果¶
验证与锁定阶段会返回明确判定，便于 agent 和人判断是否真修好了。要点如下：
| 判定 | 含义（摘要） |
|---|---|
VERIFIED |
从当前工作区启动应用，完整录制 3 次均满足检查；补丁为锁定基线到当前代码的差异 |
PASSED_UNBOUND |
检查通过，但非 BugGPS 启动的服务器，无法证明运行的是这份补丁 |
NEEDS_REVIEW |
检查通过但证据偏弱，需人工看 review_reasons |
STILL_FAILING |
仍是原失败 |
DIFFERENT_FAILURE |
症状变化或检查点不再成立 |
NO_CODE_CHANGE |
锁定后代码无变化 |
CASE_TAMPERED |
锁定用例被改动 |
STALE |
验证过程中文件变化 |
TEST_INVALID |
录制无法重放 |
ENV_BLOCKED |
浏览器、端口、dev server 或 secret 等环境问题 |
FLAKY |
多次重放结果不一致 |
VERIFIED 只覆盖录制场景，不证明其它 bug 不存在。禁用控件类修法、negative-only、模糊定位等会落入 NEEDS_REVIEW，不会自动当作完全修好。
环境要求¶
- DeepSeek Harness：
>=0.2.1-0 <0.3.0（README 实测 0.2.1-rc.5） - PATH 上有 pnpm ≥10（
dsh plugin会调用 pnpm） - 已安装 Microsoft Edge 或 Google Chrome（插件不下载浏览器）
- Node ≥20，git；目标项目为 git 仓库
依赖侧：playwright-core 1.64.1；peer 为 @deepseek-ai/dsh-tools 同版本区间。许可证 MIT。
安装与启用¶
插件尚未上 npm，安装方式为本地路径（README 已实测）：
dsh plugin --profile <你的 profile> add <path-to-dsh-bug-gps>
确认是否加载：
dsh --profile <你的 profile> --dump-config
输出中应出现 # == dsh-bug-gps。--profile 为必填。Windows 上若 DSH_HOME 路径过深可能报 ENAMETOOLONG。
安装前请自行阅读仓库源码与 MIT 许可证。插件以当前 DSH 进程权限运行，会启动浏览器、执行 serve 命令并读写项目下的 .buggps/；对 .buggps/ 的写操作在 agent 工具层会被拦截，但 shell 侧只能尽力防护，防线还包括用例内容哈希。
典型用法：内置示例¶
先做一分钟试用，生成带植入 bug 的示例商店（独立 git 仓库，已含 buggps.config.json）：
node bin/buggps.js demo ../buggps-demo
按终端提示启动 npm run dev，再在 DSH 里让 agent 借助 BugGPS 修 bug。环境自检：
node bin/buggps.js doctor --repo ../buggps-demo
会检查 Node、git、Edge/Chrome、pnpm、dsh、serve 配置与端口。
适用场景与注意¶
更适合：React + Vite、Chromium 系浏览器、前端状态可重置、用 DOM 断言描述预期的 bug 修复闭环；希望 agent 的「修好了」有浏览器重放证据，而不是仅凭描述或弱断言。
需要留意：
- 快照基于 git，含未跟踪文件，不含
.gitignore忽略项（如node_modules、.env）；依赖或本地配置变化不算在补丁里。 - 实测范围 README 写明为上述技术栈；其它环境未验收。
- 「把按钮禁用」等修法需人工确认；删掉功能消除报错、换服务器、推迟报错等反例在仓库
test/counterexamples.test.js中有覆盖。
结尾¶
BugGPS 把「用户真实操作 + 明确预期」变成可锁定、可重放的检查，并在验证阶段由插件自启应用给出 VERIFIED 或具体失败原因，适合纳入 DSH 前端 bug 工作流。详情与演示 GIF 见 GitHub README；社区条目见 SkillHub 目录页。
- 目录：https://www.skillhub.cn/plugins/lijiaqi-AI-Product-Manager/dsh-bug-gps
- 仓库：https://github.com/lijiaqi-AI-Product-Manager/dsh-bug-gps
