---
title: 附录 C 常见问题与排查清单
description: "针对 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 和审批符合预期。

- 固定基准任务的质量、成本和耗时没有明显退化。