name: troubleshoot description: “指导问题发生时的诊断和解决。当用户提到 动かない, エラーが出た, 壊れた, うまくいかない, broken, doesn’t work, error 时使用。不要加载用于：正常构建，新功能实现，代码审查。” allowed-tools: [“Read”, “Grep”, “Bash”] context: fork metadata: skillport: category: worker tags: [troubleshoot, debug, error, diagnosis] alwaysApply: false
故障排除技能
问题发生时的诊断与解决指南。 帮助 VibeCoder 无需技术知识即可解决问题。
触发短语
此技能会在以下短语时自动启动：
- 「动かない」「エラーが出た」「壊れた」
- 「うまくいかない」「失敗した」
- 「なぜ？」「原因は？」
- “it’s broken”, “doesn’t work”, “error”, “why?”
概述
当问题发生时，VibeCoder 无需理解技术细节。 此技能会自动诊断并提供解决方案。
诊断流程
步骤 1：确认症状
🔍 发生了什么？
请简单告诉我：
- 「屏幕一片空白」
- 「按钮不工作」
- 「数据无法保存」
步骤 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
步骤 3：确定问题类别
| 类别 | 症状 | 自动响应 |
|---|---|---|
| 依赖关系 | Cannot find module |
npm install |
| 类型错误 | Type error |
error-recovery agent |
| 构建错误 | Build failed |
error-recovery agent |
| 运行时 | 屏幕不显示 | 日志分析 |
| 环境设置 | 连接错误 | 环境变量确认 |
按问题分类的应对
「按钮不工作 / 表单无法提交 / UI 崩溃」
UI 故障，在屏幕上重现并观察→修复→重新验证是最快的方法。
- 如果已安装 dev-browser，则优先使用
- 在目标 URL 重现 → 根据 DOM/控制台/网络信息缩小原因范围
- 检查源代码（UI/状态管理/API/验证）并进行修复
- 确认相同步骤不再重现
- 参考：
docs/OPTIONAL_PLUGINS.md
- 无法使用 dev-browser 时的备用方案
- 重现步骤（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 确认最近的更改 |
| 「同样的错误反复出现」 | 分析模式并提出根本性对策 |
诊断命令
快速诊断
「诊断」
→ 全面的健康检查
→ 有问题则报告
→ 没有则「无问题」
详细诊断
「详细诊断」
→ 依赖关系检查
→ 构建测试
→ 测试执行
→ 环境变量确认
→ 输出详细报告
预防性建议
为防止问题发生，建议以下事项：
- 定期执行
npm run build：及早发现问题 - 频繁提交：发生问题时易于回退
- 更新 Plans.md：可追踪变更历史
注意事项
- 自动修复最多尝试 3 次
- 3 次失败后上报升级
- 破坏性操作务必先确认
- 修复历史记录在 session-log.md 中
🔧 活用 LSP 功能
在解决问题时，活用 LSP（Language Server Protocol）来准确确定原因。
通过 LSP Diagnostics 检测问题
🔍 正在执行 LSP 诊断...
📊 诊断结果：
| 文件 | 行 | 消息 |
|---------|-----|-----------|
| src/api/user.ts | 23 | 'userId' 可能为 undefined |
| 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 确认变更影响 |