9. 高频故障排查速查表
整合全教程实战过程中的高频故障场景，按「技能包使用 + 脚本部署 + 基础工具」分类整理，新手可直接对照排查，快速解决实操卡点，无需反复调试；表格中所有解决方案均经过实战验证，可直接落地。
| 故障场景 | 问题现象 | 核心排查方向 | 解决方案 |
|---|---|---|---|
| 技能加载失败（Claude/Codex 通用） | 技能包无法识别、加载报错、提示文件缺失 | 文件夹命名违规、SKILL.md 大小写错误 / 更名、路径含中文 / 特殊字符、技能包目录结构缺失 | 1. 统一用 kebab-case 短横线命名文件夹，禁用大写 / 空格 / 下划线；2. 还原 SKILL.md 文件名（严格区分大小写，不可更名）；3. 将技能包移至纯英文路径，删除特殊字符；4. 补全技能包核心目录结构（如 scripts/references） |
| 技能执行无响应 / 中断 | 触发指令后无输出、执行到一半卡住、终端提示 “执行失败” | 脚本依赖未安装、脚本无执行权限、token 超限、SKILL.md 指令模糊无约束 | 1. 补装对应依赖（如 pylint/vercel-cli）；2. 给 Shell/Python 脚本赋予执行权限（chmod +x 脚本名）；3. 精简 SKILL.md 指令，拆分长任务减少 token 消耗；4. 明确指令约束，避免模糊表述 |
| 技能输出结果不规范 / 偏差大 | 代码不合规、报告缺失字段、格式混乱、未按需求执行 | SKILL.md 指令不清晰、无输出格式约束、未绑定参考规范文档、上下文干扰 | 1. 细化 SKILL.md 执行步骤，明确输出格式要求；2. 补充规范附件并在指令中明确调用；3. 清空历史对话，减少上下文干扰；4. 在指令中添加 “禁用行为”，限定 AI 执行边界 |
| 脚本 / 部署类报错 | Python 校验失败、Vercel 部署超时、Git 提交报错、Docker 部署失败 | 密钥配置错误、端口占用、工具版本不兼容、网络权限限制、路径错误 | 1. 核对 config.json 中的密钥 / 账号信息，确保准确无误；2. 关闭占用端口的进程，更换未被占用的端口；3. 固定工具 / 依赖版本，避免兼容冲突；4. 企业内网开启合规网络代理，解决部署网络问题；5. 检查脚本中的文件路径，改为绝对路径避免错误 |
| 基础工具类故障 | API 调用失败、Copilot 无补全提示、Cursor 本地模式无响应 | 网络环境异常、API Key 失效 / 无额度、工具未登录 / 订阅过期、硬件资源不足 | 1. 配置合规网络环境，确保云端工具可正常访问；2. 核对 API Key 有效性，泄露后立即重置，补充账号额度；3. 重新登录工具账号，检查订阅状态（学生重新完成教育版认证）；4. 关闭无关进程，为本地工具分配足够的 CPU / 显存资源 |