96 lines
3.9 KiB
Markdown
96 lines
3.9 KiB
Markdown
|
# 系统化调试方法论
|
|||
|
|
|
|||
|
|
`调试` `AI Agent` `开发规范` `最佳实践`
|
|||
|
|
|
|||
|
|
# 🔍 调试方法论
|
|||
|
|
|
|||
|
|
[](https://clawhub.com)
|
|||
|
|
[](LICENSE)
|
|||
|
|
[](https://github.com/openclaw/openclaw)
|
|||
|
|
|
|||
|
|
**系统化调试方法论** — 适用于 AI Agent 和开发者的通用调试规范。
|
|||
|
|
|
|||
|
|
> 从真实生产事故中提炼，结合 Nicole Tietz、Brendan Gregg、Julia Evans 等业界顶级工程师的方法论。
|
|||
|
|
|
|||
|
|
## 为什么需要这个？
|
|||
|
|
|
|||
|
|
AI Agent 在调试时容易陷入以下陷阱：
|
|||
|
|
- 🚨 **醉汉反模式** — 随机改代码直到问题消失
|
|||
|
|
- 🚨 **路灯反模式** — 只在熟悉的地方找，而不是问题真正在的地方
|
|||
|
|
- 🚨 **补丁链** — 每次报新错就修那个错，越改越乱
|
|||
|
|
- 🚨 **忽略用户** — 用户说"改了X就坏了"，却继续自己猜
|
|||
|
|
|
|||
|
|
这套方法论提供了一个**强制性的调试流程**，避免这些常见错误。
|
|||
|
|
|
|||
|
|
## 核心流程
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
阶段 1：停下来 → 动手前先搞清现状（进程、环境、启动命令）
|
|||
|
|
阶段 2：想清楚 → 形成一个假设（优先查自己改了什么）
|
|||
|
|
阶段 3：去验证 → 一次改一个，验证后再继续
|
|||
|
|
阶段 4：检测问题 → 改了2次没好？全部回退，重新来
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 快速决策树
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
出现报错
|
|||
|
|
├─ 刚才在改代码？ → 查看变更 diff → 有嫌疑就回退
|
|||
|
|
├─ 服务起不来？ → 检查启动命令 + 环境变量
|
|||
|
|
├─ 修完又报新错？ → 停下！（补丁链！）→ 全部回退 → 重回阶段1
|
|||
|
|
├─ 用户反馈回归？ → 对比用户最后确认正常前后的变更
|
|||
|
|
└─ 偶发问题？ → 查日志 + 外部依赖 + 时序关系
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 作为 OpenClaw Skill 使用
|
|||
|
|
|
|||
|
|
将 `SKILL.md` 放入你的 skills 目录：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
mkdir -p ~/.agents/skills/debug-methodology
|
|||
|
|
cp SKILL.md ~/.agents/skills/debug-methodology/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
重启 OpenClaw 后，所有 session 遇到调试场景会自动加载这套方法论。
|
|||
|
|
|
|||
|
|
## 完整规范
|
|||
|
|
|
|||
|
|
详见 [SKILL.md](SKILL.md) — 包含：
|
|||
|
|
|
|||
|
|
- **4阶段调试流程**（停下来 → 建立假设 → 验证 → 补丁链检测）
|
|||
|
|
- **4大反模式警告**（醉汉 / 路灯 / 货物崇拜 / 忽略用户）
|
|||
|
|
- **环境检查清单**（运行时 / 依赖 / 配置 / 进程管理器 / 日志 / 备份）
|
|||
|
|
- **部署安全流程**（拉取 → 备份 → 修改 → 测试 → 部署 → 验证）
|
|||
|
|
- **快速决策树**
|
|||
|
|
|
|||
|
|
## 起源
|
|||
|
|
|
|||
|
|
这套方法论源自一次真实的生产事故：
|
|||
|
|
|
|||
|
|
修复一个简单的超时问题（2步就能搞定），却因为重启服务时没用虚拟环境，走了10步弯路。事后复盘发现，如果一开始跑一句 `ps -p <PID> -o command=` 就能避免所有问题。
|
|||
|
|
|
|||
|
|
由此总结出这套通用调试规范，并结合业界最佳实践形成了完整的方法论。
|
|||
|
|
|
|||
|
|
## 安装
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
clawhub install debug-methodology
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Wiki
|
|||
|
|
|
|||
|
|
更详细的案例分析和扩展内容请查看 [Wiki](../../wiki)。
|
|||
|
|
|
|||
|
|
## 🔗 AI 开发质量工具套件
|
|||
|
|
|
|||
|
|
| 技能 | 用途 | 安装命令 |
|
|||
|
|
|------|------|---------|
|
|||
|
|
| [bug-audit](https://github.com/abczsl520/bug-audit-skill) | 动态缺陷扫描，覆盖 200+ 常见陷阱 | `clawhub install bug-audit` |
|
|||
|
|
| [codex-review](https://github.com/abczsl520/codex-review) | 三层代码审查，含对抗性测试 | `clawhub install codex-review` |
|
|||
|
|
| **debug-methodology**（本仓库） | 根因调试，防止补丁链蔓延 | `clawhub install debug-methodology` |
|
|||
|
|
| [nodejs-project-arch](https://github.com/abczsl520/nodejs-project-arch) | AI 友好架构，节省 70–93% token | `clawhub install nodejs-project-arch` |
|
|||
|
|
| [game-quality-gates](https://github.com/abczsl520/game-quality-gates) | 12 项通用游戏开发质量检查 | `clawhub install game-quality-gates` |
|
|||
|
|
|
|||
|
|
## 许可证
|
|||
|
|
|
|||
|
|
MIT
|