用 CLI Agent 做系统化调试

你是我的 debug 搭子。我们要排查一个 bug，请严格按这五步走，每一步都不要跳：

【bug 描述】
- 现象：/orders/:id 详情页偶尔返回 500
- 频率：约 5% 请求
- 已知线索：日志里看到 NullPointerException

【你必须按顺序做的事】
1. **复现**：写一个 pytest 测试或 curl 命令，在本地稳定触发 500。
   - 如果 5 次跑都没触发，停下来跟我讨论可能漏了什么前置条件，不要跳到第 2 步。
   - 复现脚本要能让我直接 `python repro.py` 跑出来看到 500。

2. **隔离**：找到能触发 bug 的最小输入。
   - 砍掉所有跟 bug 无关的请求字段、数据库行、配置项。
   - 输出一个"最小复现集"：什么样的 order_id + 什么样的用户态 → 必然 500。

3. **root cause**：用 5 Whys 追问，至少问到第 3 层。
   - 不准把 stack trace 顶端那一行直接当 root cause。
   - 输出格式：
     Why 1: 为什么会 NPE？→ 因为 order.user 是 null
     Why 2: 为什么 order.user 是 null？→ 因为 join 查询少了一个外键
     Why 3: 为什么 join 少了？→ 因为上周改 ORM 时漏迁移了关联

4. **fix**：在 root cause 那一层修，不在症状层修。
   - 修之前先把"为什么这样修"写出来给我看。
   - 不允许加 try/catch 把异常吞掉当作 fix。

5. **回归**：把第 1 步那个复现测试加进项目测试套件里。
   - fix 之前这个测试必须红，fix 之后必须绿。
   - 给我看一次 `pytest path/to/test_xxx.py` 的红 + 绿两次输出。

如果你想跳步，请先停下来告诉我"我想跳第 X 步因为……"，由我决定。

# tests/regression/test_order_500.py
import pytest
from app import create_app

@pytest.mark.regression
@pytest.mark.bug("ISSUE-1234")
def test_order_500_repro():
    """
    复现 ISSUE-1234：订单详情页对 user=null 的 order 返回 500。
    fix 之前：这个测试预期失败（红）
    fix 之后：必须绿
    """
    app = create_app(env="test")
    client = app.test_client()

    # 最小复现集：构造一个 user_id 已被删除但 order 还在的场景
    order_id = seed_orphan_order(user_deleted=True)

    resp = client.get(f"/orders/{order_id}")

    # 期望应该是 404（订单的归属用户不存在），而不是 500
    assert resp.status_code == 404, (
        f"应当返回 404，实际拿到 {resp.status_code}，"
        f"说明 NPE 还没修干净"
    )

# 1. 让 Agent 写一个最小复现脚本，约定退出码：0=好，非 0=坏
#    脚本路径：scripts/repro.sh
cat > scripts/repro.sh <<'EOF'
#!/usr/bin/env bash
set -e
pytest tests/regression/test_order_500.py -q
# pytest 失败会以非 0 退出，刚好满足 git bisect 对"坏"的定义
EOF
chmod +x scripts/repro.sh

# 2. 启动 bisect，给一个已知 good 和已知 bad
git bisect start
git bisect bad HEAD
git bisect good v1.4.0

# 3. 让 git 自己二分跑脚本，直到锁定引入 bug 的提交
git bisect run scripts/repro.sh

# 4. 拿到那个 commit hash 之后，把它和 diff 喂给 Agent：
#    "下面是引入 bug 的提交 diff，请按 5 Whys 找 root cause"
git bisect reset

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '\nfile=\"$(jq -r .tool_input.file_path)\"\n# 只对 src/ 下的源码文件生效\nif [[ \"$file\" != src/* ]]; then exit 0; fi\n# 检查今天有没有新增/修改的回归测试\nif ! git status --porcelain tests/regression/ | grep -q .; then\n  echo \"REJECTED: 编辑 src/ 之前请先在 tests/regression/ 下写一个能复现 bug 的测试\" >&2\n  exit 2\nfi\nexit 0\n'"
          }
        ]
      }
    ]
  }
}