如何迁移 pi-extensions 弃用包：deprecated 扩展升级指南

如果你在使用 Pi Coding Agent 扩展仓库 pi-extensions，会发现部分扩展已被移入 deprecated/ 目录并停止维护。这篇 pi-extensions 弃用包迁移指南会带你快速搞清楚：哪些扩展该替换、换成什么、怎么安全切换，以及 7 个无替代方案的弃用包如何直接卸载，避免踩"新旧扩展同时加载"的坑。

deprecated 目录是什么？

在 pi-extensions 这个 monorepo 中，deprecated/下的包仅作为源码参考保留，已被排除在活跃工作区的检查、测试、发布和维护之外（详见 README.md 末尾的 "Deprecated packages" 小节）。

简单说：装了这些包不会报错，但你得不到任何功能更新和安全修复。每个包的 README 顶部都有WARNING警告块，说明替代方案和卸载命令。

弃用包迁移速查表

这是本次升级最常用的一页速查表，先判断你的扩展属于哪一类：

所有卸载命令格式统一：

pi uninstall npm:@narumitw/<包名>

如果是项目级安装，加上--local参数。

pi-workflow 迁移：拆分为 pi-plan-mode 和 pi-goal

pi-workflow是弃用包中功能最重的一个，它把 Plan（规划）和 Goal（自主执行）合并成了单一包，现在拆成了两个独立维护的包：pi-plan-mode 和 pi-goal。

行为映射：哪些功能有替代，哪些没有

六步安全切换流程

完整步骤见 deprecated/pi-workflow/README.md 的 "Safe switch-over" 小节：

1. 先完成或停止正在进行的合并式工作；
2. 导出需要保留的 Plan，对不再需要恢复的 Goal 状态执行/goal clear；
3. 退出 Pi，避免旧命令处理器、定时器残留在内存中；
4. 卸载合并包：pi uninstall npm:@narumitw/pi-workflow；
5. 按需安装pi install npm:@narumitw/pi-plan-mode和pi install npm:@narumitw/pi-goal；
6. 启动新会话，确认/plan和/goal都显示预期的未激活状态。

⚠️ 千万不要把pi-workflow归档包与pi-plan-mode或pi-goal同时加载——它们故意复用相同的命令、工具和事件通道名，同时加载会产生重复处理器和竞争的状态归属。

配置文件如何拆分

旧版使用单一文件~/.pi/agent/pi-workflow.json，新版分别读取同目录下的pi-plan-mode.json和pi-goal.json。迁移规则是按嵌套对象拷贝，不要整体复制：

• 只把plan对象拷贝到pi-plan-mode.json的顶层；
• 只把goal对象中受支持的字段拷贝到pi-goal.json的顶层；
• 顶层的workflow对象（planHandoff字段）和goal.experimental.goals（有序队列）不要拷贝，因为它们在新版中没有对应物；
• 在新文件被接受前保留旧文件备份。

新版包也提供了替代方案：若确实需要"Plan 交给 Goal 执行"的持久交接，可以手动执行/plan export PLAN.md导出计划文件，再/goal implement and verify the approved plan in PLAN.md启动 Goal——这是刻意设计的手动流程，不提供原子激活或回滚。

浏览器与爬虫扩展迁移：改用 Pi 原生 MCP

pi-chrome-devtools（浏览器自动化）和pi-firecrawl（网页抓取/搜索）的迁移思路一致：卸载扩展，改用 Pi 原生 MCP 支持接入上游官方 MCP 服务器。详细步骤分别在 deprecated/pi-chrome-devtools/README.md 和 deprecated/pi-firecrawl/README.md 的 "Migration to native MCP" 小节。

通用流程：

1. 完成进行中的操作并退出 Pi（让扩展释放托管的浏览器和临时配置）；
2. 执行pi uninstall卸载扩展（项目级安装加--local）；
3. 把官方 MCP 服务器条目合并进用户级~/.pi/agent/mcp.json，保留已有服务器配置；
4. 运行pi mcp list验证连接，新开会话后用/mcp查看状态。

两个值得注意的差异：

• 工具名变了：MCP 工具会加命名空间前缀，例如firecrawl_scrape变为mcp__firecrawl__firecrawl_scrape，之前保存的工具白名单、Plan mode 选择需要同步更新；
• 旧配置文件不会被自动转换：pi-chrome-devtools.json、pi-firecrawl.json等文件保留原样作为备份，没有任何自动迁移或删除，新设置需要在 MCP 服务器配置中显式重建。

pi-codex-accounts 迁移到 pi-accounts

账号切换场景最简单：旧版只管 Codex 订阅账号，新版 pi-accounts 覆盖所有内置/login提供商（OpenAI、Anthropic、GitHub Copilot、Kimi、OpenRouter、Radius、xAI 等）。

pi uninstall npm:@narumitw/pi-codex-accounts pi install npm:@narumitw/pi-accounts

pi-accounts会自动导入旧版pi-codex-accounts.json中的数据，同时保留源文件以便回滚。同样注意：两个包不要同时加载，因为它们可能同时刷新同一份轮换的 Codex 凭据。

无替代方案的弃用包：直接卸载

以下 7 个扩展弃用时没有提供替代品，处理方式是卸载后按自身工作流调整：

另有pi-retry：当前 Pi 版本已内置 provider 重试、Codex WebSocket 续期和可配置的空闲超时（retry与httpIdleTimeoutMs设置），直接卸载即可。卸载后其 90 秒停滞看门狗也一并移除，见 deprecated/pi-retry/README.md。

pi-google-genai的替代是grounding-with-google-genaiagent 技能，注意顺序：该技能依赖环境中的GEMINI_API_KEY（或可发现的.env文件），不读取旧的pi-google-genai.json，所以要先配置好技能再卸载扩展，见 deprecated/pi-google-genai/README.md。

迁移避坑清单

• 🔁 改完扩展后重启 Pi 或执行/reload，手动改的配置文件才会生效；
• 🚫 不要同时加载归档包与其替代包（pi-workflow+ Plan/Goal、pi-codex-accounts+pi-accounts都是同类冲突）；
• 📄 旧设置文件一律先留作备份，没有自动转换机制；
• ✅ 迁移后验证：MCP 方案跑pi mcp list；Plan/Goal 方案确认/plan与/goal初始状态正常；
• 📦 归档包源码仍在deprecated/下，需要理解历史行为时可以本地构建检查（npm run build后再pi -e .），但不要在新会话中安装。

按上面的速查表对号入座，多数用户一次pi uninstall+pi install就能完成升级；只有pi-workflow用户需要额外处理配置文件拆分。迁移完成前建议保留一份~/.pi/agent/目录备份，出问题时随时可以回滚。