二分定位调试 PangYiMing/dsh-bisect-debug

dsh-bisect-debug

DeepSeek Harness 插件 · 二分定位 / DSH plugin for bisecting bugs

"bug 在当前代码里，但不知道具体在哪"——用二分法把搜索范围每轮砍一半，快速锁定到具体函数/边界/commit。

"Bugs live somewhere in this code, but where?" — halve the search space every round with bisection, down to the exact function, boundary, or commit.

三种二分法 Three modes

| 模式 | 切什么 | 适用场景 | 需要什么 |
| ① 代码二分 | 注释/disable 一半代码 | "bug 在当前代码里，缩小到具体函数/组件" | 当前代码 + 可复现的 bug |
| ② 边界二分 | curl/log 沿数据流逐层验证 | "不知道是前端还是后端的锅" | 数据流节点图（≥3 层） |
| ③ commit 二分 | git bisect 切提交历史 | "之前还好好的，不知道哪次改坏的" | git 历史 + 好/坏 commit |

先判断用哪种：有明确好/坏时间点 → ③；跨层问题不确定哪层 → ②；确定在当前代码里 → ①（最常用）。

① 代码二分（注释/disable，最常用）

范围里有 N 个候选（函数/组件/中间件/import） → 注释掉后半 N/2 个 → bug 消失 → 根因在被注释的后半里，继续二分后半 → bug 还在 → 根因在前半里，继续二分前半 → 反复直到缩小到具体函数/具体行

标记法（方便恢复，不丢原代码）：

// [bisect-disabled]
//

注意：有依赖关系的模块不能乱注释（会引入新报错）；注释后验证的是"bug 还在不在"而不是"有没有新报错"；每轮只注释一半。

② 边界二分（curl/log 沿数据流）

任何 bug 都是"数据在某个环节不再正确"。沿数据流逐跳验证，找到数据正确到达的最后一站：

上游 ──→ 节点A ──→ 节点B ──→ 节点C ──→ 下游（用户看到的现象）

从中间节点验证——midpoint 正确则 bug 在下游，错误则 bug 在上游。不同架构的验证方式：

| 架构 | 验证方式 |
| HTTP 前后端 | curl 直连后端 API，绕过前端 |
| 微服务链 | 逐服务 curl 或查日志 |
| 数据库 | DB 客户端直接查 |
| 浏览器渲染 | DevTools Network + Console |
| 函数调用链 | 调用方/被调用方各加 log |

真实案例：点击授权报 405 → 3 个 curl（MCP 登录 200 ✅ / 网关 POST 405 / 下游 API 422 ✅）→ 结论：网关 nginx 拦截 POST。全程 3 个 curl，0 行代码改动。

先用边界二分定层，再在该层内用代码二分定函数。

③ commit 二分（git bisect run）

把"好/坏判定"固化成退出码脚本（exit 0=好，exit 1=坏，exit 125=跳过），交给 git bisect run 全自动收敛：

1. 确认好/坏 commit（good 从 tag/log 推断，不问用户）
git merge-base --is-ancestor # 校验 good 在 bad 祖先链上

2. 写判定脚本 .temp/bisect-judge.sh
npm run build >/dev/null 2>&1 || exit 125
code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 30 "http://localhost:8080/")
[ "$code" = "200" ] && exit 0 || exit 1

3. 全自动跑
git bisect start
git bisect bad
git bisect good
git bisect run bash .temp/bisect-judge.sh

4. 收尾（必做）
git bisect reset

注意：base 过期要校验（upstream 合入新文件会误导二分）；启动前工作区必须干净；git bisect reset 必做。

执行纪律 Discipline

1. 连续改了 ≥2 处还没解决 → 停下，回到二分（最强反偷懒规则）。
2. 每轮只切一半，测完再切下一半——禁止一次改多处再测。
3. 现象优先，代码最后——先用 curl/log/ping 确认现象和边界，不要一上来就读代码。
4. bug 不可复现时调整策略：总是复现 → 直接二分；间歇复现 → 加诊断日志等下一次；只发生一次 → 最大日志注入 + 部署监控。
5. 不好结果也有参考价值——宁可跑完次优解留数据，不中途停下等拍板。

跳过二分的情况 When to skip

从现象到根因 ≤ 2 步，不进二分：编译器已指出文件+行号 / 用户明确说了根因 / 改一行就能验证 / 已知版本依赖问题。

安装 Install

发布到 npm 后
dsh plugin --profile demo add dsh-bisect-debug

或从 GitHub 安装
dsh plugin --profile demo add github:PangYiMing/dsh-bisect-debug

许可证 License

MIT