【Pi】基础扩展简单推荐

昨天看到佬友写的帖子 【π】关于pi的完善之路，package生态的折腾之路 感觉真心不错，刚睡醒，心血来潮也来分享一下自己近期折腾 pi 扩展的经验。

先给误入此帖 (bushi) 的佬介绍下， Pi 是一个轻量实现的 harness, 跟 claude code / codex / opencode 这些工具比起来绝对是简易甚至可以称得上是毛坯房了，很多功能作者都刻意避开，这也让它的 system prompt token 开销很小。

虽然 Pi 这类 agent 可应用的领域不止 coding，但我目前主要还是用于 coding。本贴推荐的都是一些基础插件，coding 场景还是都能用得上的，做其他任务也有一定意义。

Pi 现在是有 7 个内置工具，其中 read, write, edit, bash 这四个是默认启用的，而 grep (后端为 rg), find (后端为 fd), ls 这三个默认是隐藏的，可以通过 pi 的 cli 选项 --tools <list> 启用。

Pi 的插件系统是 package，优点是很灵活，像 extension, theme, skills 等都可以做成 package，且一个 package 里可以包含任意种类和数量的 extention/skill/theme。 站里不少佬友的帖子里有详细说明，这里不再赘述。

先放个 pi package 的官网

个人理念就是无论使用什么 agent，先装一些通用的基础插件，之后再根据具体需求增加插件并根据项目选择性开启。尽量避免一上来就装一大堆重型插件，尤其是那种大而全的包办类型插件质量往往不高 (我说插件好用多装有没有懂的)。功能复杂往往导致架构和实现复杂，维护困难，就全用 AI 改。不会真有人喜欢纯 vibe 写的石山吧。其实很多时候根据不同的项目需求自己写 skills/插件/工作流效果更好，没必要什么级别的项目都非要用重型框架和重型扩展。另外对于 pi 的 packages 也是，并不是下载量越高就越好用，得根据自己实际需求来选。

有点扯远了，回到正题。下面开始安利一些个人觉得实用好用的插件。

权限管理

Pi 默认是不带任何权限管理以及沙盒的。 这使得 Pi 的整体使用很丝滑（rm -rf / 也很丝滑，嗯）。所以在非容器内跑 Pi，加一个权限管理还是安心不少。

这里推荐 gotgenes 的 pi-permission-system，比较喜欢它的扁平化配置。

配置位于 ~/.pi/agent/extensions/pi-permission-system/config.json

这里我目前的策略是：

1. 拒绝访问项目和用户目录的敏感路径。


2. 允许访问当前工作目录，访问外部目录时询问用户，但排除.pi 自身的目录，不然读个全局 skill 疯狂弹窗。


3. bash 执行敏感操作时询问，至于为什么不是拒绝，我测试过即使设置为拒绝， LLM 有时候也会疯狂想办法钻漏洞绕过，比如写 js 脚本删。所以我选择 ask 并由用户来判断。这里就可以体现沙盒的好处了，官网 packages 也能搜到沙盒类的权限管理扩展，佬们可以自行安装测试，或者自己从头 vibe 一个。

我正在使用的示例配置如下，我主要目的是为了防止删库，bash 部分包含了 POSIX/Unix 和 Powershell 命令，佬们根据自己的需求改。

{

  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-packages/refs/heads/main/packages/pi-permission-system/schemas/permissions.schema.json",

  "debugLog": false,

  "permissionReviewLog": false,

  "yoloMode": false,



  "permission": {

    "*": "allow",



    "grep": "deny",

    "find": "deny",



    "external_directory": {

      "*": "ask",



      "~/.pi/agent/sessions/*": "allow",

    },



    "path": {

      "*.env": "deny",

      "*.env.*": "deny",

      "~/.ssh/*": "deny",

      "$HOME/.ssh/*": "deny"

    },



    "bash": {

      "Remove-Item *": "ask",

      "remove-item *": "ask",

      "rm *": "ask",

      "del *": "ask",

      "erase *": "ask",

      "rd *": "ask",

      "rmdir *": "ask",

      "ri *": "ask",

      "mv *": "ask",



      "cmd /c del *": "ask",

      "cmd /c erase *": "ask",

      "cmd /c rd *": "ask",

      "cmd /c rmdir *": "ask",

      "cmd.exe /c del *": "ask",

      "cmd.exe /c erase *": "ask",

      "cmd.exe /c rd *": "ask",

      "cmd.exe /c rmdir *": "ask",



      "powershell *Remove-Item*": "ask",

      "powershell.exe *Remove-Item*": "ask",

      "pwsh *Remove-Item*": "ask",

      "pwsh.exe *Remove-Item*": "ask",



      "git clean *": "ask",

      "git reset --hard *": "ask",

      "git checkout -- *": "ask",

      "git restore *": "ask",



      "Clear-Content *": "ask",

      "Set-Content *": "ask",

      "Out-File *": "ask",

      "Move-Item *": "ask",

      "Rename-Item *": "ask"

    }

  }

}

这里有个反直觉的地方，pi-permission-system 会从 Pi 的全部已注册工具里重新生成 active tools，而 grep,find,ls 原本就在 Pi 内置工具全集里只是没激活。而扩展配置里默认权限的 fallback 是 ask，而只要设置为 ask 全部默认工具会被暴露。所以只有在配置里显式写 “grep”: “deny”, “find”: “deny” 才会把它们从 active tools 里过滤掉。 嗯，有点离谱。我这里还是保留了 ls，也算是高频使用的工具了，而内置的grep 和 find 被之后要介绍的 pi-fff 替代了。

Subagent 子代理

这里推荐 gotgenes 的 pi-subagents，和上面的权限管理是同一个作者（虽然这两个项目好像都是这位从其他 repo fork 二开的）。这个子代理的特点就是与上面的权限管理有联动，子代理触发权限规则，询问弹窗也会转发到主界面。目测实现比较轻量，应该是对标 cc 或者 opencode 的子代理做的，用起来挺丝滑。自带有三个子 agent 角色: general-purpose 用于通用复杂任务，Explore 用于快速仓库探索(只读), 还有一个 Plan 用于架构规划(只读)。支持自定义新 agent 角色。具体配置方法不赘述。

下载量最高的 pi-subagents 也不错，个人感觉更偏向预定 agent 角色 + 预定工作流，有点 omo-slim 内味，也可以手动配置不同 agent 的角色和模型。我个人一般用不太到这种复杂工作流，感觉平时偶尔用一下直接跟ai说自然语言也就调用子agent了，反复用的就写个 skills 规定一个带子agent的工作流，然后配合上面 gotgenes 的 pi-subagents 效果也大差不差。

上下文漂移缓解

目前在用 pi-observational-memory ，比较轻量，功能也比较有限，不像 magic-context 那样支持跨 session 记忆和其他复杂特性。

原理差不多就是后台起个子进程跑 observer 和 reflector 将精简后的对话记录和用户提过的重要要求固化到 pi 的 session 记录里。配合更加激进的触发 pi 内置的 compact，可以保证LLM一直工作在召回率较高的区间 (具体可参考 ContextArena )，同时不容易丢失一些重要信息。

扩展支持手动配置触发 observer, reflector 和 compact 的 token 数。至于如何配置，去看作者给的示例配置就好了，很简单，而且写在 pi 的 settings.json 里就 ok。

后悔药

undo / rewind 类

pi-rewind · Packages · Pi 这个插件比较接近 cc 上 /rewind(undo) 的效果，不过几个月没更新了。而且它是通过 git checkpoint 实现的，强制要求项目已经初始化 git。我平常用 jj 比较多，虽然 jj 默认就是 colocated 模式，但还是不太喜欢混用 git 命令。默认无需额外配置。

pi-workspace-history · Packages · Pi 相比上面的我更推荐这个。它用的是 shadow git，所以不需要项目初始化 git。它默认也无需额外配置。要注意是的他注册的 /undo 命令是撤销上一次的整个对话以及文件更改。也支持 /redo。如果想实现类似 cc 的 /rewind 效果，得用 pi 自带的 /tree 命令，切换节点的时候就会自动触发 pi-workspace-history 的文件恢复了。

消息撤回类

pi-wtf · Packages · Pi 在你输入内容有 typo 或者没输完却不小心回车之后。输入 /fuck (十分甚至九分的文明) 就可以强制停止当前工作并通过 pi 的 tree 撤回，并且回填之前用户的输入内容。

不过要注意的是，/fuck 只会撤回对话状态，不会更改本地文件。

测试的时候发现的一个有意思的点是，这个插件会通过切换 tree 来达成撤回的效果，所以跟上面的 pi-workspace-history 一起装会达成一套奇妙 combo： /fuck 通过 tree 撤销当前正在进行的会话时，即使文件已经做了更改，也会同时触发 pi-workspace-history 撤销文件更改。

查询增强

推荐 pi-fff, 会向 pi 注册两个工具 fffind 和 ffgrep，索引之后查询速度极快，还可以显示 git 状态，算是 fd 和 rg 的上位替代了。

有些扩展可能会激活 pi 内置的 grep, find , ls 这三个默认隐藏的命令，导致工具列表里既有 grep 和 find，也有 fffind 和 ffgrep，这时候一些笨比模型就喜欢优先用 grep 和 find 了（我不说是谁，因为其实 gpt 有时候也这样）。

如果不幸遇到的话，目前有一个暂时的解决办法：使用 pi --exclude-tools find,grep， --exclude-tools 这个参数也是最近版本才更新的 (具体见 Release v0.77.0 更新日志) ，也有用户在 Issue #5084 提到了可以把 exclude 写到配置文件里，不过 issue 被自动关掉了，不知道后面有没有可能再打开。

还需要注意的一点就是这个扩展为了增强 pi 自带的 @ 选文件功能，覆盖了 editor（就是pi的输入框hh），所以会和一些同样修改了输入框部分的一些扩展冲突，具体谁覆盖谁就看扩展的加载顺序了（当然也有可能直接报错）。

显示美化

推荐 pi-tool-display

效果差不多是这样：

可以让 Pi 的 toolcall block 变得比较简洁， edit diff 记录更美观 (还可以根据终端宽度自动切换 split/unified，整挺好)，详细配置可以在 pi 内 /tool-display 触发一个友好的 TUI 弹窗调整配置。

需要注意的是它会覆盖注册 pi 的内置工具，有可能会跟其他调整了 pi 内置工具的扩展打架。

I use Pi btw

这个功能用的比较少，目前比较推荐 @narumitw/pi-btw，体验比较类似 cc 的 btw，支持 TUI markdown 渲染，割裂感不会很重，甚至可以说风格与原版挺契合。不会污染主线程。要说缺点就是不能连续对话，不同的 btw 对话之间没有共享上下文。btw 里模型能看到工具，但模型会明确拒绝执行，有可能是通过提示词限制了。

下载量最高的是 @juicesharp/rpiv-btw，特点是支持多 btw 上下文共享，并且当前 session 只要不结束就会一直保留上下文，可以通过 TUI 手动清除 btw 的上下文历史记录。缺点是不支持 markdown 渲染。README 明确指出已经禁用了工具的，但模型还是能读到工具列表，而且调用的时候会卡住，而且好像把工具调用日志都干出来了，这点感觉不是很好。

pi-btw 是 btw 类当前下载量第二，它可以在主线程 TUI 上覆盖一个 TUI 窗口进行对话，并且支持连续对话，但似乎不支持 markdown 渲染。能调用工具，但工具数量变少了，应该是故意限制了。不过在 Powershell 上有时候渲染还是有点问题，而且在我第一次尝试时，只是问个问题让它读个文件就给我整个 Pi 进程干崩了。

结语

Man! what can i say, Pi out!

就写到这吧，在 Joplin 里全文手打无 AI 帮忙整理润色还是太累了，写了一半撤销后面发现丢了点内容，但具体丢了哪些我已经没啥印象了，气笑了。之后要是还能想起来就再更新（乐）。我目前使用场景主要是让agent以本地文档为开发依赖，所以暂时并没有配搜索的扩展/mcp/skills。欢迎佬友们补充更多实用扩展，实测好用的我会更新到帖子中 。