name: 故障排除 description: “包含CI的错误和故障的诊断与修复指南。当用户提到某些东西坏了、错误、不起作用、CI失败、构建错误、测试失败或管道问题时使用。不要用于：成功构建、新功能实现或评审。” description-en: “包含CI的错误和故障的诊断与修复指南。当用户提到某些东西坏了、错误、不起作用、CI失败、构建错误、测试失败或管道问题时使用。不要用于：成功构建、新功能实现或评审。” description-ja: “动かない？エラー？CIが赤い？诊断と修复をガイド。困ったときの駆け込み寺。当用户提到某些东西坏了、错误、不起作用、CI失败、CIが落ちた、构建错误、测试失败或管道问题时使用。不要用于：成功构建、新功能实现或评审。” allowed-tools: [“Read”, “Grep”, “Bash”] context: fork argument-hint: “[build|test|runtime]”
故障排除技能
问题发生时的诊断与解决指导技能。 帮助VibeCoder无需技术知识即可解决问题。
触发短语
此技能在以下短语时自动启动：
- “动かない”“出现错误”“坏了”
- “不顺利”“失败了”
- “为什么？”“原因是什么？”
- “it’s broken”, “doesn’t work”, “error”, “why?”
概要
当问题发生时，VibeCoder无需理解技术细节。 此技能自动诊断并提供解决方案。
诊断流程
Step 1: 症状确认
🔍 发生了什么？
请简单告诉我：
- “屏幕全白”
- “按钮不动”
- “数据未保存”
Step 2: 自动诊断
# 环境检查
node -v
npm -v
git status -sb
# 错误日志确认
npm run build 2>&1 | tail -20
npm test 2>&1 | tail -20
# 依赖关系检查
npm ls --depth=0
Step 3: 问题类别特定
| 类别 | 症状 | 自动应对 |
|---|---|---|
| 依赖关系 | Cannot find module |
npm install |
| 类型错误 | Type error |
error-recovery agent |
| 构建错误 | Build failed |
error-recovery agent |
| 运行时 | 屏幕未显示 | 日志分析 |
| 环境设置 | 连接错误 | 环境变量确认 |
| CI/CD | CI 失败、管道失败 | dispatch到ci技能 |
CI/CD 问题: 检测到CI故障・测试失败・管道问题时，将处理委派给
ci技能（skills/ci/）。ci技能使用ci-cd-fixer代理进行自动诊断和修正。
问题别对应
“按钮不动 / 表单未提交 / UI崩溃”
UI的不便，在屏幕上再现并观察→修正→再验证是最短的。
- 优先使用agent-browser（安装:
npm install -g agent-browser）# 打开页面并获取快照 agent-browser open https://example.com/target-page agent-browser snapshot -i -c # 元素引用点击・输入 agent-browser click @e1 agent-browser fill @e2 "test"- 在目标URL再现 → 基于快照/控制台缩小原因
- 确认源代码（UI/状态管理/API/验证）并进行修正
- 用相同步骤确认不再现
- 参考:
docs/OPTIONAL_PLUGINS.md
- 当agent-browser不可用时的回退
- MCP浏览器工具（chrome-devtools, playwright）
- 再现步骤（URL/步骤/期望值/实际）
- 屏幕截图/视频
- 控制台日志/网络日志
“屏幕全白”
🔍 诊断中...
可能的原因:
1. 构建错误
2. JavaScript错误
3. 路由问题
🔧 自动检查:
- 检查构建日志... ✅ 无错误
- 检查控制台错误... ❌ 发现错误
💡 解决方案:
说“修复”。将尝试自动修正。
“npm install失败”
🔍 诊断中...
错误: `ERESOLVE unable to resolve dependency tree`
🔧 解决方案:
1. 清除缓存
2. 重新安装node_modules
可以执行吗？（是/否）
“Git异常”
🔍 诊断中...
检测: 发生合并冲突
🔧 解决方案:
1. 显示冲突位置
2. 提议解决方法
说“解决”将尝试自动合并。
VibeCoder向响应模式
模式1: 自动修正可能
⚠️ 检测到问题
**问题**: 找不到模块
**原因**: 依赖关系未安装
🔧 **自动修正**
→ 执行`npm install`中...
✅ 修正完成！请再试一次。
模式2: 需要确认
⚠️ 检测到问题
**问题**: 需要更改配置文件
**影响**: 可能影响操作
🤔 **请确认**:
可以更改设置吗？
→ 说“更改”执行
→ 说“说明”确认详细
模式3: 升级
⚠️ 检测到复杂问题
**问题**: {{问题概述}}
**尝试的修正**: 3次失败
🆘 **推荐咨询Cursor (PM)**
请向Cursor共享以下:
- 错误内容: {{摘要}}
- 尝试的对应: {{列表}}
- 估计原因: {{分析}}
说“创建报告书”生成共享用报告。
常见问题自动响应
| 问题 | 自动响应 |
|---|---|
| “为什么出现错误？” | 分析错误日志并说明原因 |
| “怎么修复？” | 提示具体解决步骤 |
| “之前能用” | 用git log确认最近更改 |
| “同一错误多次” | 分析模式并提议根本对策 |
诊断命令
快速诊断
“诊断”
→ 全面健康检查
→ 有问题则报告
→ 无则“无问题”
详细诊断
“详细诊断”
→ 依赖关系检查
→ 构建测试
→ 测试执行
→ 环境变量确认
→ 输出详细报告
Claude Code 固有诊断（CC 2.1.49+）
复杂会话问题使用/debug命令有效。
| 症状 | 推荐 |
|---|---|
| “会话异常” | /debug进行会话诊断 |
| “MCP不动” | /debug确认MCP状态 |
| “多次尝试仍不行” | /debug输出详细日志 |
| “上下文奇怪” | /debug获取上下文信息 |
| “认证错误” | claude auth status确认认证状态 (CC 2.1.41+) |
认证诊断（CC 2.1.41+）
CC 2.1.41 添加了claude auth子命令:
claude auth status # 确认认证状态
claude auth login # 重新登录
claude auth logout # 登出
对API密钥问题或认证过期的诊断有用。
VibeCoder 向
🔍 需要更详细诊断时
当说“更详细诊断”时:
→ 推荐使用`/debug`命令
/debug命令诊断以下:
- 会话状态
- MCP服务器连接
- 插件设置
- 内存使用情况
- 错误日志详细
💡 使用方法:
在聊天栏输入`/debug`
故障排除联动流程
troubleshoot技能诊断
↓
自动检查一般问题
↓
┌─────────────────────────────────────────┐
│ 解决了吗？ │
├─────────────────────────────────────────┤
│ YES → 修正完成 │
│ NO → 可能复杂问题 │
└─────────────────────────────────────────┘
↓
推荐/debug命令
↓
会话・MCP・设置详细诊断
↓
基于诊断结果提示解决方案
/debug尤其有效的案例
| 案例 | 理由 |
|---|---|
| 3次修正仍不解决 | 可能环境设置问题 |
| MCP工具无响应 | 需要MCP服务器连接诊断 |
| 会话重启后操作不良 | 需要会话状态确认 |
| 其他项目能运行 | 项目固有设置问题 |
预防性建议
为防止问题，推荐以下:
- 定期
npm run build: 早期发现问题 - 频繁提交: 问题发生时易恢复
- 更新Plans.md: 可追踪变更历史
注意事项
- 自动修正最多尝试3次
- 3次失败则升级
- 破坏性操作必先确认
- 修正记录记入session-log.md
🔧 LSP功能活用
问题解决时活用LSP（Language Server Protocol）准确特定原因。
LSP Diagnostics问题检测
🔍 执行LSP诊断...
📊 诊断结果:
| 文件 | 行 | 消息 |
|---------|-----|-----------|
| src/api/user.ts | 23 | 'userId' 可能未定义 |
| src/components/Form.tsx | 45 | 不能将类型'string'分配给类型'number' |
→ 检测到2个问题
→ 上述可能为“不动”原因
Go-to-definition原因追踪
🔍 原因追踪
错误: Cannot read property 'name' of undefined
追踪:
1. src/pages/user.tsx:34 - 引用user.name
2. src/hooks/useUser.ts:12 - 返回user ← Go-to-definition
3. src/api/user.ts:8 - API响应可能为null
→ 原因为API错误时处理不足
VibeCoder 向使用方法
| 症状 | LSP活用 |
|---|---|
| “不动” | Diagnostics特定错误位置 |
| “哪里奇怪？” | Go-to-definition追踪原因 |
| “什么时候坏？” | Find-references确认变更影响 |