安装与启动
`pi --version` 失败，或者系统找不到命令。
- 确认安装路径本身已经完整执行成功。
- 检查 shell profile 与 PATH 初始化是否正确。
- 确认是否有旧版 `pi` 抢占了当前二进制。
控制
故障排查故障排查
Maozhua故障排查恢复路径试用版
Provider 配置
第一次提问在可用会话建立前就失败。
- 确认当前 shell 已导出一个受支持 provider 的 key。
- 优先先配置一个 provider，不要一开始混合多套配置。
- 先用“总结仓库结构”这种简单问题重试，再进入更深工作流。
迁移问题
旧版 TypeScript `pi` 安装导致混淆或冲突。
- 优先走文档中的 migrate 或 keep-existing 路径，而不是手动覆盖。
- 确认 PATH 中实际优先命中的 `pi` 二进制是哪一个。
- 如果没有实际验证，不要轻易承诺无缝回滚。
RPC 与扩展
自动化、IDE 或扩展行为与预期不一致。
- 把更深的 RPC 路径视为试验能力，而不是稳定 contract parity。
- 首批使用优先限制在已验证命令与官方/内部扩展上。
- 升级前先记录准确命令、环境信息和复现步骤。