PiDeck 启动提示找不到 pi？新手最常踩的5个坑与完整排障清单-育师

【免费下载链接】PiDeck

PiDeck 是一个开源的桌面工作台，用于在本地项目目录中统一管理 PI | DSH Agent 会话，并支持导入 Codex、Claude 本地会话以便统一浏览和恢复。支持多项目工作区、会话历史、Git 集成、内置终端、模型配置和插件管理，基于 Electron 构建。

项目地址：https://gitcode.com/gh_mirrors/pide/PiDeck

点击查看免费下载

PiDeck 是一个基于 Electron 的开源桌面工作台，用于在本地项目目录中统一管理 PI / DSH Agent 会话，并支持导入 Codex、Claude 本地会话。启动 PiDeck 后如果弹出「未检测到 Pi CLI」，先别慌——这不一定代表你没装 pi。本文带你快速定位 PiDeck 找不到 pi 的 5 个常见原因，并给出一份可直接照做的完整排障清单。

PiDeck 和 pi 是什么关系？为什么启动时要检测 pi

一句话：PiDeck 是 pi 的桌面外壳，不是 pi 本身。Agent 的对话、工具调用、会话读写、模型调用全部由本机pi进程原生完成，PiDeck 只负责窗口管理、会话浏览、Git 面板、终端和设置这些框架层能力，两者通过 stdio JSON-RPC 通信。

所以每次启动，PiDeck 的主进程都会先定位到你机器上的 pi 可执行文件，找不到就会在「检测环境」里提示：

未检测到 Pi CLI——桌面端通过系统 PATH 和常见包管理器路径自动查找 pi 命令。

PiDeck 检测 pi 的方式（按来源优先级）：

目录表扫描：官方安装器落点（~/.pi/agent/bin）、各包管理器全局目录（npm / nvm / pnpm / bun / yarn / mise / volta）、PiDeck 自己的便携副本目录；
自定义路径：你在设置里添加过的customPiPath与备选池piCustomPaths；
PATH 目录：GUI 进程继承到的 PATH；
登录 shell 反查：作为兜底，交互式执行一次where pi/which pi。

理解这套机制，下面 5 个坑就都好解释了。

坑一：终端里 pi 正常，PiDeck 却「未检测到」

这是新手踩得最多的一个坑。典型现场：

终端里pi --version正常输出版本号；
点 PiDeck 的「检测环境」，却提示「未检测到 Pi CLI」，错误详情写着pi: 不是内部或外部命令，也不是可运行的程序或批处理文件。

原因：官方安装脚本（curl -fsSL https://pi.dev/install.sh | sh）只把 PATH 写进当前 shell 的配置文件（bash 写~/.bashrc，否则写~/.profile），只有交互式终端会加载它。而 PiDeck 从桌面会话启动，继承的是桌面 PATH，里面没有~/.pi/agent/bin——于是"终端看得见、GUI 看不见"。这个成因链在项目文档里有完整复盘：docs/pi-install-detection.md。

两种解法（任选其一）：

从终端再找一次：在「未检测到 Pi CLI」对话框点「从终端再找一次」，PiDeck 会启动一次交互式登录 shell 反查 pi 路径，成功后点「重新检测」即可；
手动指定路径：在终端执行where pi（Windows）或which -a pi（Linux / macOS），把输出的绝对路径粘贴到设置 → 开发设置 → Pi 命令来源 → 自定义 pi 路径。粘贴后会自动归一化并校验，校验通过立即切换为"当前使用"。

坑二：装了两份 pi，PiDeck 用的是"错的那份"

如果机器上同时存在官方安装器装的~/.pi/agent/bin/pi和 npm 全局装的 pi（nvm 目录下），PiDeck 只会选中第一个命中的候选——不一定是你终端用的那份。后果不只是"显示错了"：终端pi update升级的是 managed 安装，PiDeck 的「更新 Pi」升级的可能是 npm 那份，两边版本会漂移。

怎么查、怎么切：打开设置 → 开发设置 → Pi CLI区块。「Pi 命令来源」列表会列出所有发现的安装，每行带版本、路径、来源标签（managed官方安装 /package-manager包管理器全局 /portablePiDeck 便携副本 /custom自定义 /pathPATH 发现）和状态徽章（当前使用 / 终端默认 / 较新 / 较旧）。点一行 = 切换为当前使用，PiDeck 会把它写进settings.customPiPath作为唯一生效指针，无需手动改系统环境。

💡 判断依据：路径里出现.nvm/、.bun/、pi-runtime/pi-global这类目录，说明来自不同安装通道，务必在列表里确认"当前使用"是不是你终端里那份。

坑三：压根没装 pi，先补 Node → npm → pi 三步

如果终端里pi --version本身就报错，那是真的没装。PiDeck 的检测面板会给出Node → npm → pi三步引导，一步步做完即可：

步骤	说明	PiDeck 能帮你做的事
1. Node.js	pi 是 Node CLI，先要有 Node	一键下载安装便携 Node（约 30 MB，装进 PiDeck 数据目录，不需要管理员权限，不影响系统环境）
2. npm	npm 随 Node 一起安装	检测到系统 Node 后自动完成检测
3. pi	安装 Pi CLI	用 npm 安装到 PiDeck 数据目录（不需要提权），网络慢可勾选「使用国内镜像源」

两个防呆设计值得知道：

引导安装只装进 PiDeck 自己的数据目录（<userData>/pi-runtime/），不写系统环境——所以装完后终端里直接敲pi可能仍找不到，这是设计如此；
如果你本机其实已经装过 pi（只是检测没扫到），点击安装时主进程会拦住并显示「本机已经装好 Pi，已跳过安装（不会再多装一份）」，并列出已有路径——不会再误装第二份。

坑四：检测有短缓存，装完不点「重新检测」会"装上了也看不到"

PiDeck 对检测做了多层缓存以提速：安装列表约 10 秒进程内缓存，登录 shell 反查有约 60 秒负缓存，WSL 探测也有负缓存 TTL（详见 PiLocator.ts 的注释）。这意味着：

刚装完 pi、刚改完 PATH，立即点「重新检测」仍可能读到旧结果；
此时点对话框里的「重置检测标记」，PiDeck 会清掉标记并在重启后强制重新检测；
引导流程全部完成（pi 步骤变绿 ✓）后，直接点「完成，重启应用」最稳妥，让新环境对所有会话生效。

另外，如果你的 pi 装在WSL 发行版内：宿主扫描目录里的 pi 不代表你在用的那份，需要在「Pi 来源」里选择WSL — 使用 WSL 发行版中的 Pi并指定发行版与用户名，再点重新检测。

坑五：pi 版本太旧，部分能力会被拦截

"找到 pi"≠"pi 够新"。不同能力有各自的最低版本门槛（项目文档 docs/pi-install-detection.md 有完整依据）：

能力	pi 最低版本
`pi update --self`自更新	0.70.3
RPC 直接执行 bash	0.14.0
bash 流式输出事件	0.82.0

版本低于门槛时，PiDeck 不会替你猜命令另装一份，而是提示"用原安装方式手动升级后重新检测"。先看「Pi CLI」状态行的版本号再决定下一步，能少走很多弯路。

完整排障清单：照着做一遍

遇到「未检测到 Pi CLI」，按顺序过一遍：

终端执行pi --version，确认 pi 本身可用；
在「检测环境」对话框展开「检测错误详情」，把报错原文抄下来（spawn pi ENOENT、不是可运行的程序等，都能直接判断原因）；
终端pi正常但 PiDeck 看不到 → 点「从终端再找一次」，或在设置 → 开发设置 → Pi 命令来源里手动粘贴路径；
装了两份 pi → 在「Pi 命令来源」列表里点选你要用的那份，确认"当前使用"徽章位置；
刚装完 / 刚改过环境 → 点「重新检测」；仍不行点「重置检测标记」后重启应用；
pi 装在 WSL → 「Pi 来源」选 WSL 并填对发行版与用户名；
版本号低于能力门槛 → 用原安装方式升级 pi 后重新检测；
都试过仍失败 → 设置页导出日志，把检测错误详情、pi 版本与路径一起反馈（「反馈」面板的示例文案就是为你这种场景准备的："点击检测环境后提示未检测到 Pi，但命令行里pi --version正常"）。