# 环节④：问题修复

> 什么时候读这个文件：之前生成的 skill 运行失败（刚安装后的验证失败，或日常运行报错）。

## 原则：本地修，不打服务端

修复在本地做，免费、不消耗生成额度。只有本地多次修不好才走"重新生成"（消耗额度），且要用户同意。

## 修复流程

1. **看现场**：读 skill 输出目录的 `res.json`（error 字段）和 stderr。skill 的调用契约：`node skill.mjs <input.json>`，产出 `res.json` + `data.md`
2. **先排除环境问题**（这类不用改代码）：
   - `webclaw3 doctor` 不通过 → 按 advice 处理通道问题
   - 登录态过期（页面跳登录/内容拿不到）→ 请用户在 Chrome 登录目标站点后直接重跑
   - 站点临时错误（5xx、偶发超时）→ 稍后重跑一次再下结论
3. **改代码**：环境没问题就是 skill 与页面对不上了（改版、选择器失效、新增弹窗）。用浏览器打开目标页面 inspect 真实 DOM，对着改 `skill.mjs`——按 SKILL.md 探索方法定位，不要凭想象猜选择器
4. **重跑验证**：用**和失败时不同的参数**跑一次，通过才算修好（同参数通过可能只是过拟合）

## 什么时候放弃本地修

同一个问题尝试 3 次没有实质进展，停下来，告诉用户：

- 失败的具体原因（页面大改版 / 功能下线 / 反爬升级等）
- 建议走重新生成（消耗一次生成额度），是否继续由用户决定

## 重新生成：失败原因进新 primer

用户同意后走 `references/brief.md` 流程重新提炼。关键差别：**把这次的失败原因追加进新 primer.md 的「必避陷阱」**，例如：

```markdown
## 必避陷阱
- 上一版 skill 失效原因：列表页从静态 DOM 改为接口渲染，原提取路径已不可用；
  本地实测新页面结构为 ...（写实测发现，没有就写失效现象）
```

"上一个 skill 死在哪"是服务端重新探索时最有价值的制导信息，不要省略。
