Pi Coding Agent 扩展生态指南 — 从安装到实战

上次分享了怎么给 pi coding agent 配自定义 provider，这次聊聊它的扩展生态——一个被低估但非常强大的特性。

免责声明：本文涉及的 API Key 等敏感信息均已脱敏处理。实际使用请自行替换。

为什么需要扩展

Pi 的设计哲学是”最小核心 + 可插拔”——它本身只有最基本的 read/write/edit/bash 工具，但通过扩展机制，你可以给它加上任意能力：子代理、规划模式、持久记忆、权限保护、LSP 诊断……几乎 Claude Code 有的功能，Pi 都能通过扩展补上。

而且扩展是用 TypeScript 写的，本质上就是一个 npm 包。你甚至可以问 Pi 自己写一个扩展。

安装扩展

Pi 的扩展通过 pi install 命令安装：

1	pi install npm:@org/package-name

安装后需要在 Pi 交互界面中执行 /reload 让扩展生效。不改配置文件，不重启终端，非常干净。

查看已安装的扩展：

pi list

我装的扩展清单

🎯 Goal 模式 — 长期目标追踪

两个目标管理扩展，二选一即可：

# 方案 A：基础版
pi install npm:pi-agent-goal

# 方案 B：增强版（推荐，带 setup 访谈）
pi install npm:@qhn/pi-goal

@qhn/pi-goal 会在设置目标前先进行一个”访谈”——和用户对齐 outcome、完成标准、决策风格、ask-before 边界——然后再开始自主工作。体验上更接近 Claude Code 的 plan 模式。

注意两个扩展都注册了 /goal 命令，不要同时装。

🔒 权限保护 — 防误操作

1	pi install npm:@gotgenes/pi-permission-system

这个扩展给 Pi 加了一层权限门控。当模型要执行删除、覆盖等危险操作时，会先请求确认。适合在需要保护的代码库中使用，防止 AI 不小心把不该删的文件删了。

📋 Todo 浮动层

1	pi install npm:@juicesharp/rpiv-todo

在 Pi 界面中增加一个 todo 列表浮动层，由模型自己维护。多步任务时特别有用——模型可以看到还剩哪些步骤没做，不会跑偏。

📝 任务规划

1	pi install npm:@mjasnikovs/pi-task

确定性任务规划 + 规范编排。适合需要严格按步骤执行的场景，Pi 会先生成计划、再逐步执行、最后验证结果。支持将任务分解为可追踪的子任务。

🧠 持久记忆

1	pi install npm:@remnic/plugin-pi

让 Pi 拥有跨会话记忆能力。之前聊过的上下文、做过的工作会被记住，下次开启新会话时不需要重新交代背景。

🔧 其他推荐扩展

# 子代理
pi install npm:pi-subagents                # 并行/链式任务委派

# 联网能力
pi install npm:pi-web-access               # 联网搜索、GitHub 克隆、PDF/YouTube 提取

# 代码智能
pi install npm:pi-lens                     # LSP 实时代码反馈（lint、type-check）
pi install npm:@ff-labs/pi-fff             # 模糊文件/内容搜索
pi install npm:pi-simplify                 # 自动审查并简化新改代码

# 上下文管理
pi install npm:context-mode                # MCP 插件，压缩 context 省 98%

# 导航
pi install npm:@ayulab/pi-rewind           # 检查点导航
pi install npm:@quintinshaw/pi-dynamic-workflows  # Claude Code 式动态工作流

完整的配置结构

装完扩展后，~/.pi/agent/ 目录结构大概是这样的：

~/.pi/agent/
├── auth.json           # API Key 存储
├── models.json         # 自定义模型提供商
├── settings.json       # 全局设置
├── sessions/           # 会话记录
├── npm/                # 扩展包安装目录
│   └── node_modules/
│       ├── @qhn/pi-goal/
│       ├── @gotgenes/pi-permission-system/
│       ├── @juicesharp/rpiv-todo/
│       ├── @mjasnikovs/pi-task/
│       └── @remnic/plugin-pi/
└── trust.json          # 项目信任记录

自定义模型提供商配置

我用的 krill 示例（~/.pi/agent/models.json）：

{
  "providers": {
    "krill": {
      "name": "Krill API",
      "baseUrl": "https://api.krill-ai.com/codex/v1",
      "api": "openai-completions",
      "apiKey": "$KRILL_API_KEY",
      "models": [
        { "id": "deepseek-v4-flash", "contextWindow": 128000, "maxTokens": 16384, "reasoning": true },
        { "id": "gpt-5.5", "contextWindow": 256000, "maxTokens": 32768 },
        { "id": "gpt-5.6-sol", "contextWindow": 256000, "maxTokens": 32768, "reasoning": true },
        { "id": "gpt-5.6-terra", "contextWindow": 256000, "maxTokens": 32768 },
        { "id": "gpt-5.6-luna", "contextWindow": 256000, "maxTokens": 32768 },
        { "id": "kimi-k2.7-code", "contextWindow": 128000, "maxTokens": 16384, "reasoning": true },
        { "id": "gemini-3.1-pro-preview", "contextWindow": 1048576, "maxTokens": 32768 }
      ]
    }
  }
}

API Key 通过环境变量 KRILL_API_KEY 注入，或写到 auth.json：

{
  "krill": {
    "type": "api_key",
    "key": "your-api-key-here"
  }
}

tmux + Pi 后台工作流

Pi 配合 tmux 可以长时间在后台运行，适合做大任务：

# 启动
tmux new-session -d -s pi-session -c ~/project
tmux send-keys -t pi-session "pi --model krill/gpt-5.6-sol" Enter

# 发任务
tmux send-keys -t pi-session "你的任务描述" Enter

# 查看进度
tmux capture-pane -t pi-session -p -S -30 | tail -20

# 附着查看
tmux attach -t pi-session

建议在 ~/.tmux.conf 中加上 set -g extended-keys on，否则 Pi 的某些快捷键在 tmux 中会报 warning。

小技巧

扩展不要一次装太多 — 每个扩展都会增加 context 开销。先装最需要的，不够再加
两个 goal 扩展冲突 — 不要同时装 pi-agent-goal 和 @qhn/pi-goal，它们都注册了 /goal 命令。二选一
models.json 热重载 — 编辑完不需要重启 Pi，/model 或 --model 时会自动重新加载
API Key 别写死在 JSON 里 — 用 $ENV_VAR 引用环境变量，安全且方便切换
多模型切换 — Pi 支持 Ctrl+L 快速切换模型，可以按任务类型切换（重任务用 Sol，轻量用 Luna）

资源

可以在 pi.dev/packages 查看完整扩展目录
也可以在 npm 搜索 keywords:pi-package 发现更多扩展
我的完整 Skill 配置文件：下载 pi-coding-agent-skill.md（Hermes Agent skill 格式，可放在 ~/.hermes/skills/ 下使用）

小结

Pi 的扩展生态远比我想象的成熟。从 goal 模式到子代理，从权限保护到持久记忆，大部分我想要的 Claude Code 功能都能通过扩展补上，而且安装过程极其简单——一行命令 + /reload 搞定。

如果你也在用 AI 编码助手，不妨试试 Pi + 扩展的组合，说不定会有惊喜。

为什么需要扩展
安装扩展
我装的扩展清单
完整的配置结构
自定义模型提供商配置
tmux + Pi 后台工作流
小技巧
资源
小结