name: 故障排除 description: “针对包括CI在内的错误和失败的诊断和修复指南。当用户提到某物损坏、错误、它不工作、CI失败、构建错误、测试失败或管道问题时使用。不要用于：成功构建、新功能实现或评审。” description-en: “Diagnosis and repair guide for errors and failures including CI. Use when user mentions something broken, errors, it doesn’t work, CI failures, build errors, test failures, or pipeline issues. Do NOT load for: successful builds, new feature implementation, or reviews.” description-ja: “动かない？エラー？CIが赤い？诊断と修复をガイド。困ったときの駆け込み寺。Use when user mentions something broken, errors, it doesn’t work, CI failures, CIが落ちた, build errors, test failures, or pipeline issues. Do NOT load for: successful builds, new feature implementation, or reviews.” 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 失败、管道失败	ci 技能に dispatch

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' 可能有 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 确认变更影响

详细: docs/LSP_INTEGRATION.md