Agent Troubleshoot Skill

agent-troubleshoot-skill

  

**一个会不断成长的故障排查知识库技能 | A constantly-growing troubleshooting knowledge-base skill for AI coding agents**

**概述：把踩过的坑都记下来，遇到问题让AI先翻笔记本，再动手修。** **Overview: Every pitfall you've hit gets written down. When AI sees a problem, it checks the notebook first, then fixes it.**

**适用范围：** 适用于Codex、Claude Code、OpenCode 等常用的Agent 工具。 Works with any agent that supports the Agent Skills spec (Codex, Claude Code, OpenCode, etc.).

[中文](#简介中文) | [English](#overview-english)

---

简介（中文）

**原理：** 基于确认过的排查经验持续积累，遇到历史同类故障时能快速识别并复用解决方案，显著缩短修复时间。

它的作用体现在三层：

层次	作用	说明
即时匹配	减少重复排查	遇到报错时自动检索知识库中相似的历史案例，直接给出解决方案和预防措施
统一入口	覆盖主流平台	一个技能覆盖Codex、Claude、Gemini、ZCode、Foundry、OpenCode等平台，不用针对每个平台单独找方案
持续积累	越用越强	每确认一个新案例，知识库就更扎实，形成正向循环

**🔒 隐私与质量保障**

• 你的敏感信息不会被收录：API密钥、令牌、端口、本机路径等，入库前都会自动删掉或替换掉
• 错误方案不会被收录：只有你确认问题真正解决后，案例才会写入知识库

核心功能：

1. 故障诊断：根据错误症状（错误码、框架名、关键词）匹配历史案例，输出带置信度的解决方案
2. 智能学习：问题解决后由用户确认，新案例归档到知识库（Jaccard语义去重、多解法合并）
3. 避坑指南：记录试过但没用的方法，帮你少走弯路（wrongSolutions字段）
4. 两级分类：「共同问题」是任何框架都可能遇到的（如401认证失败、429限流）；「独有问题」是只在某个框架自身工具链里才存在的故障

预置 8 个平台共 30 个案例：

类别	示例
共同问题	401鉴权失败、429限流、上下文溢出、网络超时、模型不存在
Antigravity 独有	浏览器控制失败（Chrome/扩展）、工件与任务列表同步失败
Claude 独有	artifact渲染崩溃、shell命令找不到、权限拒绝
Codex 独有	模型上下文协议（MCP）服务器缺失、单模型上游慢导致超时、切换模型失败
Foundry 独有（微软Azure AI平台）	azd 部署失败、trace导出失败、missing agent.yaml
Gemini 独有	思考预算耗尽、图片上传失败、日配额用尽
OpenCode 独有	自定义provider配置不生效、崩溃后会话恢复失败
Reasonix 独有	推理链断裂（深度超限）、工具循环调用
ZCode 独有	技能不触发、hook失效、MCP断连、插件缺失

安装：

适用于任何支持技能机制的Agent（Codex / Claude Code / OpenCode 等）。**复制下面这一行发送给您的AI即可：**

帮我安装agent-troubleshoot技能，项目地址：https://github.com/XCZ-Huazhou/agent-troubleshoot-skill ，下载放入我的技能目录并完成本机配置。

---

**⚠️ 安装后初始化***