附录 C 常见问题与排查清单

针对 AI 工具使用中常见的各类问题，提供系统化的排查步骤、解决方案与快速恢复清单，帮助快速定位并解决问题，同时给出恢复建议。

先排输入，再排目录与 Git，再排环境、规则、权限和外部连接，最后才考虑换模型。

问题	常见原因	优先排查
总是跑偏	目标模糊、旧上下文、规则冲突	重开会话；从 Brief / Spec 开始；列已加载规则
代码看起来对但跑不通	没执行真实命令、环境变量、依赖或端口错误	运行最小路径；记录命令、cwd、版本和完整错误
重复同一错误	经验只留在聊天	新增最小规则、测试或 Hook；明确 Owner
规则没有生效	启动目录不对、文件名/层级/override 冲突	让 Agent 列出指令来源；检查 AGENTS.md 层级，并确认 CLAUDE.md 只含 `@AGENTS.md`
Skill 不触发	description 模糊、位置不对、名字冲突	检查路径、重启、显式调用、缩短并明确描述
MCP / 插件失败	认证、scope、网络、租户、工具 schema	先最小只读调用；检查账号、权限和工具清单
Worktree 启动失败	未跟踪文件、env、依赖、端口、数据库缺失	建立初始化脚本；参数化环境；使用独立数据
Cloud 与本地结果不同	环境镜像、依赖、网络或 secret 漂移	记录版本、锁文件、环境配置；在本地复现后再合并
Browser / Computer Use 误操作	身份、页面、提示注入、权限不清	限定身份、profile 与 Kimi session；敏感动作前停下；回读实际结果
定时任务静默失败	凭据过期、触发、worktree、通知或配额	运行手动测试；检查历史、日志、失败通知和清理
多人冲突多	共享目录、任务边界和合并人不清	worktree、接口契约、可写范围、主集成人
成本失控	长上下文、反复全量读取、过多并行、没有停止条件	按任务选模型；压缩输入；里程碑预算；限制并发

C.1 通用排查顺序

1. 输入：目标、范围、验收、禁止事项是否清楚？

2. 位置：当前目录、仓库、分支、worktree、主文件夹是否正确？

3. 上下文：加载了哪些规则、Spec、Skill 和历史？是否冲突？

4. 环境：运行时、依赖、环境变量、端口、网络、账号是否正确？

5. 权限：沙箱、审批、writable roots、MCP scope 是否足够且不过度？

6. 验证：真实命令、日志、截图、数据是否证明结果？

7. 版本：客户端/CLI/插件是否变化？查看 --help、/help 与 release notes。

8. 最后才调整模型、reasoning、提示或拆分策略。

C.2 版本更新前回归清单

CLI 启动、登录、--version、--help 正常。
AGENTS.md 层级与 override 加载正确；CLAUDE.md 只引用 @AGENTS.md。
核心 Skill 能显式和隐式触发，输出不变形。
Hook / 权限 / 沙箱不被更新重置。
MCP / 插件最小只读调用正常，写操作仍需审批。
Worktree / Cloud / Routine / Scheduled Task 可创建、运行、清理。
浏览器与 Computer Use 的平台能力、profile 和审批符合预期。
固定基准任务的质量、成本和耗时没有明显退化。