把常见试用故障整理成可执行的恢复路径。
把常见失败点压缩成可执行恢复路径先看主路径失败，再看集成边界与历史迁移。
控制
故障排查Doctor
pi doctormacOS
Troubleshooting
4当前公开发布线
安装与启动
`pi --version` 失败，或安装后命令不可见。
- 确认安装脚本完整执行成功。
- 检查 shell profile 与 PATH 初始化是否正确。
- 确认没有旧版 `pi` 抢占当前二进制。
Provider 与环境检查
第一次调用在会话建立前就失败，或 provider 不可用。
- 先配置一个受支持 provider 的 key。
- 运行 `pi doctor`、`pi --list-providers` 与 `pi --list-models`。
- 先用仓库摘要这种简单请求验证主路径。
JSON / RPC / SDK 接入
结构化输出、RPC 客户端或嵌入接入表现与预期不一致。
- 先验证 `pi --mode json` 与 `pi --mode rpc` 的最小调用。
- 把当前阶段视为可用入口，而不是所有语义都已锁定的最终 contract。
- 记录准确命令、输入、环境和复现步骤后再升级处理。
历史环境迁移与桌面包装
旧版 `pi` 安装、桌面 app、PATH 或并存策略导致混淆。
- 优先走文档中的 migrate 或 keep-existing 路径，而不是手动覆盖。
- 确认 PATH 中实际优先命中的 `pi` 二进制是哪一个。
- 桌面包装问题优先在 macOS 上按构建脚本与 app/pkg 产物核验。