排查 Pi 时，先确定问题发生在哪一层：进程是否正确启动、模型请求是否成功、工具是否执行、最终结果是否满足任务。把这些层次分开，能避免用“Agent 没反应”概括不同原因。
四层观察法
| 层次 | 要确认的事实 | 常见证据 |
|---|---|---|
| 启动与加载 | 版本、工作目录、项目是否受信任、配置和资源是否加载 | 启动界面、pi --version、pi list、当前目录 |
| 模型与提供商 | 当前模型身份、认证、网络、额度和提供商响应 | 模型选择结果、错误类型、提供商日志或状态 |
| 工具执行 | 工具是否被调用，命令在哪个目录运行，返回码和输出是什么 | 工具调用记录、命令、路径、退出码、标准错误 |
| 结果验收 | 文件和外部状态是否真的改变，测试是否通过 | diff、文件内容、测试输出、目标系统读取结果 |
应该从出现异常的最早层开始检查。后续层成功不能反向证明前一层完全正确，例如工具返回零退出码也不能证明改动符合需求。
常见现象与判断
模型能看到，但调用失败
模型出现在列表中，只能说明模型目录或配置可见。实际调用还依赖认证信息、网络、提供商服务和账户额度。应记录模型标识与提供商，再读取原始错误，区分未认证、限流、连接失败和服务端错误。认证入口和提供商差异见官方 Providers 文档。
交互模式可用，脚本或 CI 不可用
首先比较工作目录、环境变量、项目受信任状态和加载参数。交互终端中已确认的项目资源，不代表非交互环境会得到相同授权；全局与项目设置也可能不同。然后确认脚本使用的是 print、JSON 还是 RPC 模式，以及调用方是否正确读取结构化输出。官方使用说明列出了不同运行模式。
扩展或技能没有出现
依次检查资源路径或 Package 声明、项目是否受信任、筛选规则是否启用目标资源、当前进程是否已重载，以及启动时是否报告加载错误。资源已安装不代表已加载，已加载也不代表模型会在当前任务中调用它。
工具执行失败
保留完整工具名称、参数、工作目录、相关路径、退出码和错误输出。重点检查相对路径的基准、文件权限、命令是否存在、超时限制和输出是否被截断。不要只根据模型对错误的概括判断原因，应回到工具返回的原始事实。
模型说“已完成”，但结果不符合要求
把完成声明当作待验证结论。读取改动后的文件或目标系统状态，检查 diff，运行与任务相关的测试，并逐条对照验收条件。如果任务涉及部署、发布或外部服务，还应区分“本地修改完成”“构建成功”“已部署”和“线上验证通过”。
重试、超时与确定性错误
Pi 的 Agent 级重试用于处理部分暂时性失败，默认重试次数和退避策略可在设置中配置；提供商或请求层也可能有独立重试机制。具体字段见官方设置文档。
重试适合限流、暂时断线或服务端短暂异常，不会自动修复错误路径、无效参数、权限不足或测试断言失败。超时表示操作在规定时间内没有完成，也不等于远端操作一定没有生效。涉及外部写入时，重试前应先查询实际状态，避免重复创建或重复执行。
最小复现步骤
遇到难以解释的问题，可以缩小到以下流程：
- 记录 Pi 版本、操作系统、当前目录、模型和提供商；
- 暂时只保留复现所需的最少配置与资源；
- 新建会话，用一条明确输入触发问题；
- 保存原始命令、工具参数、错误输出和时间；
- 在相同目录重复一次，判断是否稳定复现；
- 只改变一个变量，例如模型、Package 版本或运行模式；
- 恢复必要扩展，确认问题是否重新出现。
临时关闭资源只能用于定位，不能替代最终环境中的验收。若问题只在某个项目发生，应同时保留该项目的信任状态和 .pi/settings.json 相关片段，但不要暴露密钥。
提交问题时保留什么
一份可诊断的问题报告至少应包含：Pi 版本、模型和提供商、运行模式、工作目录类型、已加载资源的来源、最小输入、预期结果、实际结果及原始错误。敏感令牌、私有文件内容和个人路径可脱敏，但不应删除决定行为的配置事实。
扩展拥有完整系统权限，因此异常也可能来自第三方代码。若加载来源不明或行为涉及意外的文件、命令或网络操作，应立即停止任务并检查来源；边界说明见官方安全文档。