捉虫专家 - 多Agent协作调试系统

English Documentation | 中文文档

基于 Harness Engineering 范式的多 Agent 调试技能，通过专业分工 + 协作机制，覆盖前端/后端/数据库/网络/系统全栈调试场景。 兼容 WorkBuddy 和 OpenClaw 双平台 | Compatible with both WorkBuddy and OpenClaw

---

⚠️ 免责声明 | Disclaimer

中文:

• 本技能仅供开发调试使用,请勿在生产环境中直接执行修复
• 使用者需自行审查所有生成的修复脚本并承担使用风险
• 作者不对任何直接或间接损失承担责任
• 详见 MIT License

English:

• This skill is for development debugging only, do not execute fixes directly in production
• Users must review all generated fix scripts and assume all risks
• The author is not liable for any direct or indirect damages
• See MIT License for details

---

🎯 特性

• 多Agent协作: 6个专业领域Agent协作诊断
• Harness Engineering: 四大护栏保障质量
• 持续演化: 错误驱动学习,不断改进
• 完整流程: 从问题接收→诊断→审查→执行→验证

📋 架构

Debug Orchestrator (编排者)
    ├─ Frontend Debugger   → 前端调试专家
    ├─ Backend Debugger    → 后端调试专家
    ├─ Database Debugger   → 数据库调试专家
    ├─ Network Debugger    → 网络调试专家
    ├─ System Debugger     → 系统调试专家
    └─ Code Reviewer       → 代码审查者

🚀 快速开始

1. 触发方式

使用以下关键词触发调试:

调试 / debug / 排查 / 诊断 / 报错 / error / 异常 / exception / 修复

2. 基本使用

示例1: 前端错误

用户: "React报错: Cannot read property 'map' of undefined"

Agent:
1. [分流] → 加载 Frontend Debugger
2. [诊断] → state未初始化导致异步数据未加载完成
3. [方案] → 添加loading状态和默认值
4. [审查] → Code Reviewer评估方案
5. [确认] → 等待用户确认后执行

示例2: 数据库性能

用户: "MySQL查询很慢,日志显示: Query execution time: 15s"

Agent:
1. [分流] → 加载 Database Debugger
2. [诊断] → 缺少索引或查询未优化
3. [方案] → 添加索引建议 + 查询优化
4. [审查] → Code Reviewer评估影响
5. [确认] → 用户确认后生成执行脚本

3. 使用规范

✅ 提供完整信息

错误信息: [完整错误堆栈]
环境: [操作系统/语言版本/数据库版本]
复现步骤: [如何重现问题]
相关代码: [问题代码片段]

❌ 避免模糊描述

"程序报错了" (❌ 信息不足)
"代码不工作" (❌ 需要具体错误信息)

📚 目录结构

debug-swat/
├─ SKILL.md                    # 编排者入口 (<3.5k词)
├─ agents/                     # 专家模块
│   ├─ frontend-debugger.md    # 前端调试专家
│   ├─ backend-debugger.md     # 后端调试专家
│   ├─ database-debugger.md    # 数据库调试专家
│   ├─ network-debugger.md     # 网络调试专家
│   ├─ system-debugger.md      # 系统调试专家
│   └─ code-reviewer.md        # 代码审查者
├─ references/                 # 参考文档
│   ├─ error_catalog.md        # 错误目录 (持续更新)
│   ├─ diagnosis_templates.md  # 诊断报告模板
│   └─ best_practices.md       # 各领域最佳实践
├─ scripts/                    # 工具脚本
│   └─ harness_validate.py     # Harness合规性验证
├─ examples/                   # 使用示例
└─ README.md                   # 本文件

🔧 核心机制

1. 分流逻辑

Agent根据问题类型自动加载对应专家:

前端错误 → Frontend Debugger
后端错误 → Backend Debugger
数据库问题 → Database Debugger
网络问题 → Network Debugger
系统问题 → System Debugger
跨领域问题 → 多专家会诊

2. 验证门机制

诊断报告 → 验证门1 (根因分析?)
    ↓ 通过
修复方案 → 验证门2 (审查通过?)
    ↓ 通过
执行修复 → 验证门3 (修复成功?)
    ↓ 通过
更新错误目录

3. Generator-Evaluator模式

Debugger (Generator) → 生成诊断方案
    ↓
Code Reviewer (Evaluator) → 审查方案质量
    ↓
未通过 → 返回重新生成 (最多2轮)
    ↓
通过 → 等待用户确认

4. 错误驱动演化

每次错误解决后:

1. 追加到 error_catalog.md
2. 提取预防规则
3. 写入 SKILL.md 约束块
4. 定期审查,精简过时规则

🛡️ 安全机制

硬性规则

ID	规则	来源
R1	禁止直接执行修复,必须先诊断后行动	安全基线
R2	危险操作必须人工确认	安全基线
R3	连续3次诊断失败必须升级人工	Harness原则
R4	不执行未经验证的修复脚本	安全基线
R5	生产环境修改需要双确认	安全基线

边界-自主权分离

人类决策区:

• 是否执行修复方案
• 是否修改生产环境
• 是否回滚变更

Agent自主区:

• 选择调用哪个专家
• 诊断分析方法
• 生成修复方案选项

📖 详细文档

• 主SKILL.md - 编排者入口,完整工作流程
• 错误目录 - 常见错误及解决方案
• 诊断模板 - 标准化诊断报告
• 最佳实践 - 各领域最佳实践

🔍 验证工具

验证Skill是否符合Harness Engineering规范:

cd scripts
python harness_validate.py ../..

输出示例:

🔍 开始Harness合规性验证...

✅ 目录存在: agents/
✅ 目录存在: references/
✅ 文件存在: SKILL.md
✅ SKILL.md词数: 2847 (符合<3500要求)
✅ 包含章节: 概述
✅ 包含章节: 核心原则
...

📊 验证结果汇总
✅ 通过: 25
❌ 失败: 0
⚠️  警告: 3

总体评分: 89.3/100
等级评定: B (良好)

🎓 学习路径

初级用户

1. 阅读 README.md 了解基本概念
2. 查看 examples/ 目录中的示例
3. 尝试使用调试功能

高级用户

1. 阅读 SKILL.md 理解工作流程
2. 研究 agents/ 目录了解各专家能力
3. 参考 references/ 学习最佳实践

贡献者

1. 阅读 Harness Engineering 理论基础
2. 理解四大护栏设计
3. 运行 harness_validate.py 验证修改
4. 更新 error_catalog.md 记录新错误

🤝 贡献指南

1. 添加新错误案例

编辑 references/error_catalog.md:

### [错误类型] - [日期]

**触发条件**: [场景描述]

**错误信息**:
\`\`\`
[完整错误]
\`\`\`

**根因分析** (5 Whys):
1. Why: ...
2. Why: ...
...

**修复方案**:
\`\`\`[语言]
[修复代码]
\`\`\`

**预防规则**: [约束建议]

2. 更新专家知识

编辑对应的 agents/*.md 文件,添加新的:

• 错误类型
• 调试工具
• 常见问题模式
• 最佳实践

3. 优化约束系统

当硬约束超过15条时:

1. 审查是否有矛盾规则
2. 合并语义相似的规则
3. 移除模型能力已覆盖的旧规则
4. 移动到 references/deprecated_constraints.md

📊 版本历史

v1.0.0 (2026-04-03) - 首个正式版本 🎉

🎯 亮点:

• 基于 Harness Engineering 范式的多Agent协作调试系统
• 6大专业专家协作诊断,覆盖全栈调试场景
• Generator-Evaluator 质量保障机制
• Harness 合规评分 100/100 (A级优秀)

✨ 新增功能:

• ✅ 多Agent协作系统 (6个专业领域专家)
• ✅ Harness Engineering 四大护栏
• ✅ 智能分流机制 + 验证门机制
• ✅ 5条硬性安全规则
• ✅ 错误驱动持续学习
• ✅ Harness合规性验证工具
• ✅ 完整文档体系 (SKILL.md + 6个专家模块 + 3个参考文档)
• ✅ 10个常见错误案例库
• ✅ 3个详细使用示例

📚 文档:

• SKILL.md - 编排者入口 (578词)
• agents/ - 6个专家模块
• references/ - 错误目录/诊断模板/最佳实践
• examples/ - 3个使用示例
• CHANGELOG.md - 版本更新日志
• RELEASE_NOTES.md - GitHub Release 说明

🐛 修复: 无(首个版本)

⚡ 优化:

• 初始设计即遵循 Harness Engineering 最佳实践
• 约束数量控制在 5 条,避免过载
• 错误目录预置 10 个常见案例

🔒 安全性:

• 所有危险操作均需人工确认
• 生产环境修改需要双确认机制
• 不执行未经验证的修复脚本

📊 验证结果:

✅ 通过: 39
❌ 失败: 0
⚠️  警告: 0
总体评分: 100.0/100
等级评定: A (优秀)

🙏 致谢: Mitchell Hashimoto (Harness Engineering) / OpenAI Codex / Anthropic Claude Code / Martin Fowler

---

维护日志

2026-04-03 v1.0.0 发布

• 初始版本发布
• 6个专家模块完整实现
• 四大护栏机制到位
• 验证门 + Generator-Evaluator 模式
• 错误目录初始化 10 个案例
• 通过 Harness 合规性验证 (100/100 A级)

2026-04-03 项目优化

• 添加 description 字段,修复技能面板描述显示
• 重命名技能为"捉虫专家"
• 创建 CHANGELOG.md 和 RELEASE_NOTES.md

---

📄 许可证

MIT License

---

🙏 致谢

基于以下理论和方法论构建:

• Mitchell Hashimoto - Harness Engineering原文
• OpenAI Codex - 10条实践
• Anthropic Claude Code - Generator-Evaluator模式
• Martin Fowler - 三支柱框架

---

捉虫专家: 专业协作,精准诊断。

问题反馈: 如遇到问题或有改进建议,请更新 error_catalog.md 或联系维护者。