debug · git:20261026.8d01e18 · 2026-10-26 · sha256 04ee79001633e494
debug git:20261026.8d01e18A
Immutable. This exact content never changes and is served at /api/v1/blob/04ee79001633e494.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_wra7xbehp4tgbgnj/04ee79001633e4943547dbf222bd693086221294c7078506e0907b37fd0aab73.json
Then /plugin install debug@markdownregistry-wra7xbehp4tgbgnj in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: debug
description: 系统调试循环(无 slash · skill-only)— 复现→假设→隔离→验证→记录;禁止无复现盲改。说「修 bug」「测挂了」「不知道为啥挂」时用。
---
# debug
**用这个**:测挂 / 异常行为 / 要找根因再改。**不是那个**:已知实现任务继续做 → **`/run`**;范围不清要重排 → **`/plan`**;上线走查 → **`/delivery`**。
衔接 `rules/execution/bugfix.mdc`。结论须含 **file:line** 与可复现步骤。
## 铁律
**无根因调查,不提修复。** 禁止无复现、无假设的盲改;symptomatic patch 视为失败。
## 系统循环(按序)
| 步 | 动作 | 完成标准 |
|----|------|----------|
| **1 复现** | 固定步骤 / 最小用例;读完整报错与栈 | 能稳定触发,或明确「不可复现→先采证」 |
| **2 假设** | 1~3 条可证伪原因(含「近期变更 / 环境」) | 写下假设,勿边猜边改 |
| **3 隔离** | 见下节;缩小到单层/单文件 | 证据指向失败边界 |
| **4 验证** | 最小 diff + `task-verify` / 项目 test | 绿且回归不过度 |
| **5 记录** | 用户可见 → CHANGELOG `### Fixed`;流程缺口 → `/learn` | 可审计 |
跨组件(API↔DB、CI↔脚本)时:先在边界打诊断日志,**定位断裂层**再深入,勿多处同时猜改。
## 隔离法
1. 最小复现或补失败测试
2. 注释/禁用可疑块(备份或 stash 思路)
3. 跑 `task-verify` / 项目 test 对比前后
4. 二分缩小范围
## 模式聚类
- 同类报错一批修(同根因别打补丁)
- 区分环境 vs 代码(config、版本、路径)
### 路径型资源 · 健康三角验证
**用这个**:Unix socket · PID 文件 · 锁文件 · 命名管道路径。**不是那个**:纯 HTTP `/health` 返回 200 即收工。
| 视角 | 检查什么 |
|------|----------|
| **客户端路径** | `test -S path` / `stat` — 文件系统上是否存在 |
| **系统层** | `ss -xl` / `lsof` — 内核是否仍有 listener |
| **进程内** | 应用 `/health` 或内存 handle — 是否自认 healthy |
**关键**:三者可**不一致**(路径已删而 fd 仍 listen → 客户端 `ENOENT` 但 `/health` 仍绿)。修复须同时校验路径可达 + 失效 stale 缓存(见下节),勿只信单一绿灯。
### Stale 单例 / 连接缓存
连接类全局缓存(模块级 singleton client · `globalThis` 句柄 · env 里旧 URL)在 **硬失败**(`ENOENT` · `ECONNREFUSED`)后须 **invalidate 并重试**,禁止无限复用 stale 句柄。优先读**指针文件/权威配置** over 进程启动时注入的旧 env。
### Dev 反代 · 多传输路径
Vite/webpack dev proxy 调试时须枚举 **所有** 出站路径:主线程 `fetch` shim · **XHR** · **Web Worker** · WebSocket。Worker 内请求**不经过** HTML 注入的 fetch 补丁是高频根因。
| 纪律 | 说明 |
|------|------|
| **具体优先** | 专用 rewrite(如 `/api/uploads` · `/api/ws`)须排在泛 `/api` **之前** |
| **同源壳** | iframe/子应用路径与主站 API 分流要分别验证 |
## Agent 内省调试(Agent 失败 / 越修越乱)
**用这个**:Agent 会话内工具失败、结论自相矛盾、多轮「修了又坏」。**不是那个**:纯应用代码 bug → 上节系统循环;范围重排 → **`/plan`**。
吸收自 SkillsMP `agent-introspection-debugging`(协议 only)。
| 症状 | 常见根因 | 先做什么 |
|------|----------|----------|
| 工具反复报错 | 工具误用、参数/schema 错、无权限 | 读**完整**工具输出;对照 `GetMcpTools` schema;单步重试 |
| 答案与仓库事实不符 | **上下文污染**(旧假设、截断 diff、错文件) | 重新 `Read`/`Grep` 采证;勿沿用未验证结论 |
| 绿测后又挂 / 补丁叠补丁 | **隐式修复环**(symptomatic + 未记录假设) | 停止扩 diff;回到 **1 复现**;列出已改文件与仍失败断言 |
| 同命令第 3 次仍失败 | 环境/路径/沙箱与假设不符 | 打印 `cwd`、实际命令、exit code;对照 `bugfix` Escalation |
**内省循环**(嵌在系统循环内,不跳过复现):
1. **捕获** — 失败工具调用、用户纠正原话、相关 `file:line`
2. **诊断** — 1~3 条可证伪假设(含「我是否读错文件/漏看 stderr」)
3. **受限恢复** — 最小回滚或单点验证;**禁止**同时改多模块「碰运气」
4. **内省报告**(给用户 3~5 行)— 根因 · 证据 · 已验证修复 · 若仍不确定标 `Decision needed`
流程缺口或重复 Agent 失误 → 提议 **`/learn`** §ERRORS;勿自动改 `.cursor/` 母版。
## Escalation(与 run)
- **`/run` 失败自修 ≤2 轮** → 仍失败:plan 标 `⚠️` → **`/plan`**
- 线上 hotfix:小 diff + CHANGELOG `### Fixed`;仍须先复现/采证
- 同症状 ≥2 已发布 patch → **禁止**第三个 symptomatic hotfix;走 `bugfix` §Follow-up / `SPIKE-*`
## 网络与抓取(任务中 · 非仅 debug)
**用这个**:选工具、处理失败。**不是那个**:UI 走查清单 → **delivery** §10;可回归 E2E → **test**。
| 场景 | 优先 | 失败时 |
|------|------|--------|
| 有明确 URL · 静态页 | `WebFetch` | 说明原因(403/CAPTCHA/空白);不静默假装成功 |
| 无 URL · 需搜索 | `WebSearch` | 说明无结果或需用户补充关键词 |
| JS 渲染 / 登录 / 交互 | **delivery** §10 或已装浏览器自动化 CLI | 须用户授权登录与敏感操作 |
动态页勿仅用 `WebFetch` 猜内容;网络类结论写进 debug 记录或提议 **learn** §ERRORS。
## 浏览器 E2E 调试(吸收自 anthropics/skills/webapp-testing)
**用这个**:本地 dev server + Playwright 脚本复现 UI 问题。**路由**:写测/起服 → **test** §E2E;上线走查 → **delivery** §10。
| 症状 | 先查 |
|------|------|
| 元素找不到 | 是否 **networkidle 前** 就查 DOM?→ 先 `wait_for_load_state('networkidle')` |
| 间歇失败 | server 未就绪 → **test** `with_server.py` |
| JS 报错 | **test** `examples/console_logging.py` 抓 console |
| selector 不稳 | 侦察:screenshot + `locator().all()`,再改 selector |
脚本路径:`.cursor/skills/test/scripts/` · 先 `--help` 黑盒调用。