前言¶
在 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
