故障排查

排查 Pi 时不要同时改模型、凭据、配置和 Extension。先建立一个最小可工作的基线，再逐层恢复项目能力。

排查基线 Pi 0.83.0 源码 c13ffe1877c32026-07-30

五分钟诊断顺序

按顺序运行：

node --version
pi --version
pi --list-models
pi --no-session --no-approve --no-tools \
  --no-context-files --no-extensions --no-skills \
  --no-prompt-templates --system-prompt "" \
  --append-system-prompt "" -p "只回复 OK"

这四步分别验证：

1. Node.js 是否满足 >=22.19.0。
2. CLI 是否正确安装并进入 PATH。
3. 凭据与模型目录是否至少有一个可用组合。
4. 不加载用户与项目上下文、扩展、技能或模板，也不向模型暴露工具时，模型链路是否正常；Pi 内置系统提示仍然存在。

如果第 4 步通过，问题通常在资源加载、工具或终端交互层，不要继续重装 Pi。注意：--no-approve 本身不会禁用上下文文件和用户级资源，--no-context-files 也不会屏蔽用户级 SYSTEM.md 与 APPEND_SYSTEM.md，所以最小基线需要上面的完整参数组合。

症状速查

症状	最可能原因	先检查
pi: command not found	npm 全局 bin 不在 PATH	npm prefix -g、重开终端
启动时报 Node 版本错误	Node.js 太旧	node --version
/model 没有可用模型	凭据缺失或目录未刷新	/login、pi --list-models
登录成功后仍认证失败	启动进程没有读到凭据，或 OAuth 需刷新	同一 shell 重试 /login
项目 Skill/Extension 不出现	项目未受信任或未重载	/trust、重启、/reload
非交互任务忽略项目配置	Print/JSON/RPC 不弹信任提示	显式 --approve
/reload 后 Extension 行为重复	初始化不是幂等，后台资源未关闭	session_shutdown
工具能看到却无法执行	schema、权限、路径或运行模式错误	工具错误结果与启动目录
上下文很快满	大输出、重复文件或长会话	/session、/compact
Windows shell 工具失败	没有可用 Bash	Git Bash / WSL 与官方 Windows 指南
图片、颜色或快捷键异常	终端能力或键位冲突	/hotkeys、终端设置

安装与版本

Node.js 版本太旧

Pi 0.83.0 要求：

Node.js >= 22.19.0

确认当前 shell 使用的版本：

node --version
which node

Windows PowerShell：

node --version
Get-Command node

安装新版本后，完全关闭并重新打开终端，避免版本管理器仍保留旧环境。

pi 不在 PATH

先检查全局安装：

npm list -g --depth=0 @earendil-works/pi-coding-agent
npm prefix -g

重新安装：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

不要同时用 npm、pnpm、Bun 和 curl installer 安装多个全局副本。which pi 或 Get-Command pi 应只指向你准备使用的那个版本。

版本升级后 Extension 报类型或导出错误

先看：

pi --version
pi --help

再对照 Pi changelog。常见破坏性变化包括：

• coding-agent SDK 从旧 AuthStorage / ModelRegistry 选项迁移到异步 ModelRuntime。
• TypeBox 升级后删除旧 API。
• Extension 事件或工具结果结构收紧。

固定依赖版本，先在临时分支升级并运行 Extension 的失败路径。

认证与模型

没有可用模型

按顺序检查：

pi --list-models
pi update --models

然后进入交互模式：

/login
/model

不要从网上复制一个模型 ID 直接猜。pi --list-models 和 /model 才是当前安装、凭据和供应商目录的事实来源。

环境变量明明设置了，Pi 却看不到

确认变量和 Pi 在同一个进程环境中：

test -n "$ANTHROPIC_API_KEY" && echo "set" || echo "missing"
pi --list-models anthropic

只检查是否存在，不要打印真实值。图形化 IDE、终端 multiplexer、容器和 CI runner 可能不会继承你刚修改的 shell 配置。

SSH 或无头环境无法完成登录

Pi 0.83.0 的部分供应商支持设备码、粘贴回调地址或授权码。按照 /login 当时显示的流程操作，不要假设所有供应商都使用同一种 OAuth 回调。

如果自动打开浏览器失败，把提示中的授权链接复制到另一台有浏览器的设备。详细流程以 Providers 为准。

调试外部客户端凭据

Pi 0.83.0 增加了：

pi auth print-api-key --provider <provider> --model <model>
pi auth print-bearer-token --provider <provider> --model <model>

这些命令会把真实凭据写到 stdout，只适合受控的进程间集成。不要粘贴到终端日志、聊天、Issue、CI 输出或文档。一般排错优先使用 /login 和 pi --list-models，不需要打印秘密。

项目信任与资源加载

项目设置、Skill 或 Extension 没加载

交互模式中：

/trust

保存信任后重启 Pi。/trust 写入未来会话的决策，不会自动重新启动当前会话。

之后执行：

/reload

检查启动头部是否列出了目标资源，以及是否存在加载诊断。

项目信任控制 .pi/settings.json、.pi 资源、项目 .agents/skills 和项目 Package。它不限制 Pi 对文件或 shell 的系统权限。

Print、JSON 或 RPC 模式行为与交互模式不同

非交互模式不显示项目信任提示。选择一种明确策略：

# 已审查并需要项目资源
pi -p --approve "运行项目定义的检查"

# 不需要项目资源
pi -p --no-approve "只概览公开文件"

不要依赖之前某次交互提示的记忆。自动化脚本应在命令中表达边界。

AGENTS.md 在未信任项目中仍然生效

这是预期行为。AGENTS.md 和 CLAUDE.md 属于上下文文件，默认会加载，不受项目信任开关保护。

需要完全忽略上下文文件时使用：

pi --no-context-files

不可信仓库中的文档、注释、构建输出和上下文文件都可能包含提示注入。真正的安全边界仍然是容器、VM 或策略沙箱。

Skill 与 Extension

Skill 没有被发现

检查：

• SKILL.md 是否在目录中。
• frontmatter 是否有非空 name 和 description。
• name 是否只含小写字母、数字和连字符。
• 是否发生同名冲突。
• 项目是否受信任并执行过 /reload。

显式测试可以绕开自动发现：

pi --skill ./path/to/skill

完整步骤见做出第一个 Pi Skill。

Extension 加载失败

用显式路径隔离问题：

pi -e ./path/to/extension.ts

先移除第三方依赖和复杂初始化，缩减到只注册一个命令。如果最小 Extension 能加载，再逐项恢复：

1. npm 依赖。
2. 文件和网络访问。
3. 事件处理器。
4. 自定义工具。
5. 后台资源。

/reload 后重复通知、重复监听或进程不退出，通常说明初始化或清理不是幂等的。完整生命周期见做出第一个 Pi Extension。

会话、上下文与工具

上下文快满了

先执行：

/session

查看消息、token 和成本，再选择：

• 用 /compact 总结旧上下文。
• 用 /tree 回到更早节点。
• 用 /fork 或 /clone 分离新方向。
• 开新会话，把稳定结论写进文件而不是长期留在聊天里。

大段 shell 输出、生成文件和重复读取最容易消耗上下文。!!command 会执行命令但不把输出加入模型上下文。

工具输出被截断

这是保护上下文的预期行为。改用更窄的命令：

rg -n "target" src/
git diff --stat
git diff -- path/to/file

不要为了得到完整日志而无限提高输出上限。先筛选，再读取相关片段。

Agent 停止后仍有排队消息

在交互模式中：

• Enter 发送 steering。
• Alt+Enter 发送 follow-up。
• Escape 中止并把排队消息恢复到编辑器。
• Alt+Up 取回队列中的消息。

如果行为不符合预期，打开 /settings 检查 steeringMode 和 followUpMode。

网络与离线

完全禁用启动时网络操作：

PI_OFFLINE=1 pi

它会关闭版本检查、Package 更新检查、安装/更新遥测和模型目录网络刷新。离线模式不提供本地尚未缓存的模型或凭据。

只关闭版本检查：

PI_SKIP_VERSION_CHECK=1 pi

只关闭安装/更新遥测：

PI_TELEMETRY=0 pi

这三个开关作用不同。不要用 PI_TELEMETRY=0 期待完全离线。

终端与平台

Windows shell 命令失败

Pi 的 shell 工具需要 Bash。常见选择：

• Git for Windows 提供的 Git Bash。
• WSL 中完整运行 Pi。

查看 Pi Windows 官方指南，确认路径、引号和终端快捷键。

Alt+Enter、粘贴或图片显示异常

• 运行 /hotkeys 查看 Pi 当前键位。
• Windows Terminal 的 Alt+Enter 默认可能切换全屏，需要重新映射。
• Windows 粘贴图片常用 Alt+V。
• 图片显示能力取决于终端支持的图形协议。

终端差异见 Terminal setup。

提交问题前收集最小证据

不要上传会话或整个配置目录。先准备：

Pi 版本：
Node.js 版本：
操作系统与终端：
启动命令（移除密钥）：
最小复现步骤：
实际结果：
预期结果：
是否在 --no-session --no-approve --no-tools 下复现：

分享日志前删除：

• API Key、Bearer Token 和 OAuth 回调。
• 用户目录、私有仓库名和内部域名。
• prompt 与工具输出中的业务数据。
• 会话导出中的源代码或图片。

仍无法定位时，查看Pi 官方文档、现有 Issues，或按仓库要求提供最小复现。