dsh-bug-gps

dsh plugin --profile web add dsh-bug-gps

BugGPS · dsh-bug-gps

简体中文 · [English](docs/i18n/README.en.md) · [日本語](docs/i18n/README.ja.md) · [한국어](docs/i18n/README.ko.md) · [Deutsch](docs/i18n/README.de.md) · [Français](docs/i18n/README.fr.md) · [Español](docs/i18n/README.es.md) · [Português (Brasil)](docs/i18n/README.pt-BR.md)

录下问题，按原预期复核修复。

Record the bug. Verify the fix against the original expectation.

DeepSeek Harness（DSH）插件。你在浏览器里把 bug 操作一遍，标出“正确应该是什么”；BugGPS 把它锁成一个会失败的检查，修复后由 BugGPS 自己启动应用、按原条件重放，只有全部检查都通过才给出 VERIFIED。

_{演示由脚本操作仓库自带的植入 bug 示例，并应用预置的错误和正确修改。页面与工具结果来自实际运行，采用关键帧剪辑；片长不代表任务耗时。结果卡片为演示排版，光标与字幕叠加。查看 [本次场景与运行摘要](docs/media/demo-run.json)；真实 DSH 集成另见测试说明。重新生成：npm run demo:gif（需要 ffmpeg）。也有 [MP4 版本](docs/media/buggps-demo.mp4)。}

以下命令安装固定 Git 源码；npm 路径适用于已经公开发布的版本。发布状态见发布清单。兼容范围为 DSH 0.2.1-rc.5 的 headless / web，已记录的环境为 Windows。

dsh plugin --profile web add 'git+https://github.com/lijiaqi-AI-Product-Manager/dsh-bug-gps.git#c48aa094b6b32731d517fb0026cceccdae60e117'
dsh --profile web --dump-config

这里以 web 为例；无界面实例将两处 Profile 改为 headless。确认配置层后重启对应实例，在目标 Git 项目中调用 buggps_status；桌面入口需独立验收。完整步骤及 npm 路径见 [安装与移除](docs/installation.md)。

[历史运行依据](docs/verification/1.0.0/README.md)记录固定案例、账号流程和分发路径，每份记录绑定自己的源码与范围。最新验收进展见发布清单。

试用内置示例

从源码试用时，使用下面的固定源码准备依赖。运行记录、支持范围与实际发布状态见 发布清单：

git clone https://github.com/lijiaqi-AI-Product-Manager/dsh-bug-gps.git
cd dsh-bug-gps
git checkout --detach c48aa094b6b32731d517fb0026cceccdae60e117
npm ci

node bin/buggps.js demo ../buggps-demo

它会生成一个带植入 bug 的小商店（独立 git 仓库，已配置 buggps.config.json），并打印下一步：启动 npm run dev，然后在 DSH 里让 agent 用 BugGPS 修 bug。

node bin/buggps.js doctor --repo ../buggps-demo

检查 Node、git、系统 Edge/Chrome、pnpm、dsh、serve 配置和端口。

流程

录制工具栏默认简体中文，可切换英语、日语、韩语、德语、法语、西班牙语和巴西葡萄牙语。输入值、应消失、不应报错、检查点和关键步骤在「更多检查」中。选取页面元素时面板自动收起，确认或取消后恢复；Esc 可以取消选取。已设置的预期、检查点与关键步骤持续显示，语言、位置和收起状态跨页保留。

结束前会确认已发送的记录。有问题时，警告面板聚焦原因和两种处理选项；窄屏分行显示状态与语言控件，键盘焦点进入处理按钮，返回后恢复录制控件。缺少正向预期、操作无法定位、输入不受支持或确认超时都会显示原因；保留未完成记录不会得到修复已验证的结论。可查看 [中文界面](docs/media/toolbar/zh-CN.png) 与 [英文界面](docs/media/toolbar/en.png)。截图由脚本操作内置植入问题示例，展示录制与预期设置，没有执行修复验证；从源码重新生成：npm run demo:toolbar。

1. 录制（buggps_record）：浏览器打开，你操作一遍，在工具栏上标出：

• 预期：文本 / 输入值 / 应可见 / 应消失 / 不应报错。先标“不应报错”再标一个正向预期时，两个都会保留。
• 检查点（可选）：“此刻页面应为 …”。修复前后都必须成立，防止修复绕过你录下的情境；缩减步骤时也不会删掉它。
• 关键步骤（可选）：缩减时永远保留。
• 识别为密码、验证码、卡号或 token 的输入字段和文本域只保存引用；重放时从环境变量 BUGGPS_SECRET_<名字> 读取。同名字段使用独立引用，再次填写同一字段时复用原引用。
• 每份草稿使用独立标识保存，中文名称作为显示信息保留。重新锁定场景时使用新的 case id，已有用例不会被覆盖。
• 保存初始窗口尺寸、语言、时区和像素比例。录制期间的窗口尺寸变化作为关键步骤保留，用于重放响应式布局问题。

2. 锁定（buggps_lock）：BugGPS 用 serve 命令自己启动应用，在当前代码上默认重放 3 次，全部以同一种方式失败才锁定。锁定的用例有内容哈希，并且写保护。同时尝试缩短步骤，只靠重放，不调用模型。

3. 修复：DSH 的 agent 用常规工具改代码。

4. 验证（buggps_verify）：BugGPS 再次从工作区启动应用，默认重放你的完整录制 3 次。最后一步后先检查所有条件，再在观察窗口内按 50 ms 目标间隔重复检查（默认观察 1000 ms）；任一采样失败就不通过。运行记录保留实际采样次数和最大间隔。该检查不覆盖采样间隙及观察窗口以外的状态变化。

可复核的外部案例

ChartDB 的 DBML 导入曾将 GIN 索引显示为默认 B-tree。DSH 0.2.1-rc.5 在未提供参考补丁或修复历史的应用副本中修改一个源文件：候选通过 3/3，新启动的原代码再次匹配失败 3/3；12 个既有 DBML 导入测试文件共 99 项，前后均通过。会话耗时 206.5 秒，包含锁定、读取、修改和验证，环境准备及应用回归另计。

查看 [实际账户流程记录](bench/results/account-project-chartdb-dbml-index-2026-11-03.json)、[输入、补丁与复核命令](bench/repairs/chartdb-dbml-index/README.md)和 [输入校验修复后的补丁重放](bench/results/repair-replay-case-input-2026-11-03.json)。后一次重放耗时 497,334 ms，使用已安装依赖且没有模型调用；原代码、无关改动、候选及新启动的原代码控制均执行 3 次。两类运行分别记录，不把固定补丁重放当作新的独立修复。这一案例已用于改进实现，不能估算真实用户成功率。

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 会写进用例并参与哈希计算，之后修改配置文件不会影响已锁定的用例。
• CLI 与插件工具使用相同的配置校验。observeMs 在建立场景时覆盖输入草稿中的观察窗口；插件显式传入的 observe_ms 优先。锁定后验证使用保存的条件，不重新套用当前项目配置。

结构化草稿可以直接锁定。当前录制使用 buggps.capture/v2，锁定前会核对所有选取的文本、输入值与可见性是否匹配录制时的原始状态；版本与这些状态一同参与内容指纹。缺少当前采集依据的旧录制必须重新录制，旧锁在检查器升级后需重新确认和锁定，不能自动继承修复结论。

字符串检查默认严格相等；结构化草稿需要验证动态文件名时，可在锁定前明确声明 comparison: "startsWith" 与固定前缀。录制草稿保留精确比较，避免用前缀掩盖原始状态变化。count 检查使用一个明确的集合选择器和整数 equals，例如检查收藏入口数量。这些条件均参与用例指纹，不由修复过程自动放宽。

判定

判定 · 含义

VERIFIED · 候选版本的完整录制在全部配置次数中满足所有检查（默认 3 次），独立基线对照也重新出现锁定的原失败；补丁是锁定基线到候选代码的差异

PASSED_UNBOUND · 检查通过了，但服务器不是 BugGPS 启动的，证明不了它运行的是这份补丁。没有 serve 时最多只能得到这个

NEEDS_REVIEW · 检查通过了，但证据弱于“修好了”，需要人判断。原因见 review_reasons：<br>disabled-control：录制的操作打到了被禁用的控件<br>negative-only：仅检查不报错、目标消失或零匹配，仍缺少正向结果<br>locator-drift：动作、检查点或预期改用了其他定位候选，或旧记录缺少定位依据；需要重新确认场景<br>evaluator-changed：检查器版本与原失败记录不同，需在原代码上重新建立失败依据，另存新用例，保留旧记录<br>baseline-not-reproduced：独立基线对照未能重新出现锁定的原失败

STILL_FAILING · 还是原来那个失败

DIFFERENT_FAILURE · 症状变了但预期仍未满足，或者录制的检查点不再成立

NO_CODE_CHANGE · 锁定后代码未变；修复任务继续修改和复验，仅验证的任务报告未变

CASE_TAMPERED · 锁定的用例被改动过，不给判定

STALE · 验证过程中文件发生了变化

TEST_INVALID · 案例定义、定位器或录制无法执行；不作为应用故障

ENV_BLOCKED · 环境问题，不是代码问题：浏览器、端口、dev server 或未提供的 secret

FLAKY · 多次重放结果不一致

BUDGET_EXHAUSTED · 预算已耗尽，证据尚未齐备

ABORTED · 任务已取消，不给出修复成功结论

VERIFIED 只覆盖录制的那个场景。 它不证明其它 bug 不存在。

buggps_status 按完成时间显示最近的有效运行。历史结果只有在代码、用例、锁定清单与检查器仍匹配时才标记为当前适用；not_current_reasons 说明不匹配的原因。NO_CODE_CHANGE 保留“代码未变”的判定，不表示修复成功。

工具文本预览最多 12,000 字符，优先显示判定、证据引用和下一步。看到 output_preview: abbreviated 时，按引用读取完整草稿、用例、运行记录或补丁。完整结构化结果和验收数据保持原样，不从省略的预览重建测试或采用补丁。

环境要求

• DeepSeek Harness 0.2.1-rc.5。当前兼容声明仅覆盖这个已验收版本；扩大范围前会补充兼容记录
• PATH 上有 pnpm ≥10：dsh plugin 会调用 pnpm
• 已安装 **Micros

…(truncated)