前言¶
「代码报错了怎么查」「这个 bug 到底在哪一层」「改了两轮还是不对，问题出在哪」，是日常开发里最常见、也最容易陷入循环的问题。多数时候不是没有排查能力，而是没有一条固定的路径：先做什么、再做什么、什么时候该回退假设，全凭临场发挥。
Debug Pro 就是用来补这条路径的。它把调试拆成七个固定步骤，再附上多种语言的调试命令，交给 Agent 去执行，避免临时拼凑。
这是什么¶
Debug Pro 是一个基于通用 SKILL.md 格式的 Agent Skill，来自 ClawHub 生态，坐标 @clawhub_cmanfre7/debug-pro，发布者 cmanfre7，当前版本 1.0.0，许可证 MIT-0。
它解决的问题是：让 Agent 在面对一个软件缺陷时，有一套系统性的识别、验证、修复流程，而不是直接猜一个原因就动手改。资料页给出的定位是「提供七步调试协议及语言特定命令，系统化地识别、验证并修复跨多环境的软件缺陷」。
分类属于 dev-programming。资料显示 requires_api_key=false，即使用不需要额外 API key。
核心能力¶
按官方 SKILL.md，这个 Skill 提供四块内容。
1、七步调试协议：从复现到回归测试的固定顺序。
2、语言特定的调试命令：覆盖 JavaScript/TypeScript、Python、Swift、CSS/Layout、网络层，外加 Git Bisect 流程。
3、常见错误模式对照表：把错误信息、可能原因、修复方式列成表。
4、快速诊断命令：端口占用、进程状态、文件监听、磁盘与系统资源。
七步协议原文如下，这是整个 Skill 的骨架。
- Reproduce — 让故障稳定复现，记录准确的步骤、输入和环境。
- Isolate — 缩小范围。注释代码、二分查找、用
git bisect查最近的提交。 - Hypothesize — 形成一个具体的、可被验证的根因假设。
- Instrument — 加有针对性的日志、断点或断言。
- Verify — 确认根因。如果假设是错的，回到第 3 步。
- Fix — 应用最小的正确修复，不要在调试时顺手重构。
- Regression Test — 写一个能抓住这个 bug 的测试，并验证它通过。
第 5 步的「假设错了就回到第 3 步」是关键，它把调试从线性流程变成了可回退的循环。
安装与启用¶
安装走 ClawHub 的 CLI，命令如下。
openclaw skills install @clawhub_cmanfre7/debug-pro
这是上游仓库 https://clawhub.ai/cmanfre7/debug-pro 页面给出的安装方式。SkillHub 页面同时也提供了 npx skills 的入口。
安装完成后，在 Agent 中以 Skill 形式启用即可。这个 Skill 不需要配置 API key，也不需要额外的环境变量。
关于其他编辑器或 CLI，资料里没有分别给出安装差异，这里不做推测。
典型用法¶
场景一：顺着七步协议排查一个偶发崩溃¶
先把现象稳定下来，这一步不做任何修改。
# 记录触发条件：完整的复现步骤、输入数据、运行时环境
然后二分缩小范围，用 git bisect 定位是哪次提交引入的。
git bisect start
git bisect bad # 当前提交是坏的
git bisect good abc1234 # 已知的好提交
# Git 自动切到中间提交，测试它，然后：
git bisect good # 或 git bisect bad
# 反复执行，直到定位到根因提交
git bisect reset
定位到提交之后，加日志或断点验证假设。以 Python 为例：
python -m pdb script.py
breakpoint() # Python 3.7+
确认根因后做最小修复，最后补一个回归测试。
场景二：前端布局错位¶
CSS 层的排查，Skill 给的是直接在页面上打轮廓和高亮的办法。
/* 给所有元素描边 */
* { outline: 1px solid red !important; }
/* 高亮某个具体元素 */
.debug { background: rgba(255,0,0,0.1) !important; }
场景三：接口请求失败¶
先确认是网络层还是服务层的问题。
# HTTP 调试
curl -v https://api.example.com/endpoint
curl -w "@curl-format.txt" -o /dev/null -s https://example.com
# DNS
dig example.com
nslookup example.com
# 端口占用
lsof -i :3000
netstat -tlnp
场景四：环境层面的快速诊断¶
当现象和代码看起来都对不上时，先确认环境。
lsof -i :PORT # 这个端口被谁占了
ps aux | grep PROCESS # 这个进程在干什么
fswatch -r ./src # 监听文件变化
df -h # 磁盘空间
top -l 1 | head -10 # 系统资源占用
常见错误模式对照¶
SKILL.md 里附了一张错误信息到修复方式的表，适合快速比对。
| 错误 | 可能原因 | 修复方式 |
|---|---|---|
| Cannot read property of undefined | 缺少 null 检查或数据结构不对 | 用可选链 ?. 或校验数据 |
| ENOENT | 文件或目录不存在 | 检查路径、创建目录、用 existsSync |
| CORS error | 后端缺少 CORS 头 | 加带正确 origin 的 CORS 中间件 |
| Module not found | 依赖缺失或导入路径错 | npm install，检查 tsconfig paths |
| Hydration mismatch (React) | 服务端/客户端渲染不一致 | 保证渲染一致，客户端逻辑放 useEffect |
| Segmentation fault | 内存越界、空指针 | 检查数组边界与指针有效性 |
| Connection refused | 服务没在预期端口上跑 | 确认服务状态，核对端口和 host |
| Permission denied | 文件或网络权限问题 | 检查 chmod、防火墙、sudo |
这张表的价值在于，它把「读错误信息」这一步标准化了，Agent 可以先查表再决定深入哪一层。
适用场景与注意¶
适合的场景：缺陷现象明确、可以复现的问题；跨语言、跨环境需要统一排查口径的场景；想让 Agent 按固定流程而不是凭感觉改代码的场景。
需要注意的几点。
1、协议的第一步是稳定复现。如果现象本身就是偶发且无法复现的，七步流程走不起来，这时先补日志和监控，而不是直接套用。
2、第 6 步强调「最小修复，不要顺手重构」。这个约束需要在使用中反复确认，因为 Agent 容易在调试过程中顺手改一堆东西。
3、第 7 步要求写回归测试。如果项目本身没有测试基础设施，这一步会落空，需要先补上测试环境。
4、语言特定命令覆盖 JavaScript/TypeScript、Python、Swift、CSS/Layout 和网络层。如果项目用的是其他语言或框架，需要自行补充对应命令。
5、这是一个方法论型 Skill，不带运行时依赖，也没有 API key 要求，适合直接嵌入现有的 Agent 工作流。
结尾¶
Debug Pro 的价值不在于提供了多少条命令，而在于把调试这件事变成了一条有明确步骤、可以回退、可以验证的流程。对于经常让 Agent 帮忙查 bug 的人来说，它把「先复现、再隔离、再假设、再验证」这套纪律固化了下来。
官方地址：https://www.skillhub.cn/skills/clawhub_cmanfre7/debug-pro，上游仓库：https://clawhub.ai/cmanfre7/debug-pro。
说明：安装命令、七步协议、语言命令、错误对照表均来自上游仓库页面，版本号与许可证同上。
