Pi Agent 可以便携吗？可以，但真正的便携不只是把一个启动程序复制到 U 盘。要让它换电脑、换盘符甚至重装系统后仍能继续工作，Node.js、Git、配置、Skills、插件、会话和项目都要尽量收进同一个目录。
这篇文章记录我在 Windows 上实际使用的一套 Pi Agent 便携环境。目标很明确：配置跟着目录走，项目跟着目录走，换电脑后尽量少重装、少配置。
一、什么才算“真正便携”
普通安装通常会把文件分散到用户目录、npm 全局目录、系统 PATH 和各种缓存位置。复制主程序后，Skills、插件、登录状态或 SSH 配置往往并没有一起带走。
我的便携目录集中保存以下内容：
- Pi Agent 与 Node.js/npm；
- PortableGit、Bash 和 OpenSSH；
- Pi 设置、模型配置、插件与 Skills；
- 会话记录和项目文件；
- Git 配置及必要的 SSH 配置；
- 启动、检查和权限修复脚本。
示例根目录：
D:\APP\Pi Agent\
这只是示例路径，放在其他盘符也可以。关键是启动脚本应根据自身位置计算根目录，而不是把所有路径永久写死。
二、推荐的目录结构
Pi Agent\
├─ data\
│ ├─ skills\ # Agent Skills
│ ├─ home\ # 便携 HOME、SSH 等
│ ├─ sessions\ # 会话数据
│ └─ settings.json # Pi 配置
├─ npm\ # 便携 npm 与相关工具
├─ npm-cache\ # npm 缓存
├─ project\ # 项目目录
├─ tools\
│ └─ PortableGit\ # Git、Bash、OpenSSH
├─ pi.cmd
├─ 启动 Pi PowerShell.vbs
├─ 检查便携环境.cmd
└─ 修复便携SSH权限.cmd
日常项目、截图、导出文件和脚本也应放进各自的项目目录，不要散落在工作区根目录。
三、日常启动方式
我给环境准备了几个固定入口：
- 启动 Pi PowerShell.vbs：日常启动入口；
- 注册 Pi 到当前电脑.vbs：让普通终端可以直接输入
pi； - 检查便携环境.cmd：检查 Pi、Node.js、Git、Bash、SSH 和路径；
- 修复便携SSH权限.cmd：换电脑后修复私钥权限。
启动脚本主要做三件事：
- 把
HOME指向便携目录； - 优先使用目录内的 Node.js、Git、Bash 和 OpenSSH；
- 进入项目目录后启动 Pi。
这样可以减少配置写入 Windows 用户目录，也能在盘符变化后重新计算内部路径。
四、Package、Extension 和 Skill 的区别
这是便携环境中最容易混淆的部分。
Pi Package / Extension
Package 或 Extension 通常包含可执行代码，为 Pi 增加新工具、命令或界面能力。查看已安装包可以使用：
& "D:\APP\Pi Agent\pi.cmd" list
安装时建议通过 Pi 自己的包机制：
& "D:\APP\Pi Agent\pi.cmd" install "npm:插件包名"
不要随意使用系统级 npm install -g，否则依赖可能被装到便携目录之外。
Agent Skill
Skill 更像一套专门的任务说明和工作流程，核心入口通常是 SKILL.md。在这套便携环境中，Skill 放在：
D:\APP\Pi Agent\data\skills\<skill-name>\SKILL.md
pi.cmd list 主要显示 Package/Extension，因此普通 Skill 即使安装成功，也不一定出现在这个列表里。验证 Skill 最直接的方法，是检查目录和 SKILL.md 是否存在，然后重启 Pi 观察能否被识别。
五、迁移到新电脑
迁移时不要只复制几个启动文件，必须复制完整的 Pi Agent 文件夹。
- 退出正在运行的 Pi 和相关开发服务；
- 完整复制整个便携目录；
- 在新电脑上放到 NTFS 分区；
- 运行 SSH 权限修复脚本；
- 运行环境检查脚本；
- 启动 Pi，检查 Skills、插件和项目；
- 必要时重新登录模型或第三方服务。
如果使用 U 盘传输，建议 U 盘只作为搬运介质，最终仍将目录复制到新电脑的 NTFS 分区。exFAT/FAT 对 SSH 私钥权限和部分开发工具并不友好。
六、迁移后重点检查什么
PI_CODING_AGENT_DIR是否指向当前便携目录；- Node.js、npm、Git 和 Bash 是否来自便携目录；
- Skills 和插件能否正常识别；
- 项目文件和历史会话是否完整；
- SSH 私钥权限是否被 Windows 重置；
- 浏览器、模型和第三方平台是否需要重新登录；
- 原来的绝对路径是否仍指向旧盘符。
建议每次迁移后先运行检查脚本，再开始正式工作。这样比等到某个命令报错后再逐项排查更省时间。
七、常见问题
1. Skill 已复制，但 Pi 没有识别
确认目录层级正确，必须能找到：
data\skills\技能名称\SKILL.md
然后完全退出并重新启动 Pi。
2. 插件安装后，换电脑就丢失
通常是插件或 npm 依赖安装到了系统用户目录。应检查安装命令、npm 前缀和便携启动脚本设置的环境变量。
3. SSH 提示私钥权限过宽
这是 Windows 复制文件后常见的问题。需要重新限制私钥 ACL，只允许当前用户读取。不要为了省事关闭 SSH 的权限检查。
4. 换盘符后无法启动
检查脚本中是否存在写死的绝对路径。启动器应根据自身目录动态计算根路径，并更新内部配置。
八、安全提醒
完整便携目录可能包含高度敏感的信息，包括：
- SSH 私钥；
- API Key 与访问令牌；
- 浏览器 Cookie 或登录状态；
- 模型账户信息；
- 项目中的
.env文件； - 服务器地址和内部配置。
不要把完整便携目录上传到公开网盘或公开 Git 仓库。分享教程时只展示经过脱敏的目录、命令和示例配置。
九、总结
真正好用的便携环境，不是“复制后勉强能启动”，而是路径、依赖、配置、Skills、插件和项目都具备明确的归属。只要坚持完整目录迁移、动态路径、安装位置可控和迁移后检查，Pi Agent 就可以成为一套能长期携带和持续维护的 Windows 工作环境。
说明：本文是个人环境搭建与实际迁移记录，不代表 Pi Agent 官方安装文档。工具版本和目录约定可能随更新变化，实际操作前请同时查看当前版本帮助。