Pi 基础扩展简单推荐
本文分享一套实用的 Pi 基础扩展选择与配置经验：权限管理（pi-permission-system）、子代理（pi-subagents）、上下文漂移缓解、后悔药（undo/rewind）、查询增强与显示美化，覆盖 Coding 场景的主要需求。
前言
昨天看到佬友写的帖子【π 关于 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 里可以包含任意种类和数量的 Extension/Skill/Theme。
先放个 Pi Package 的官网：pi.dev
个人理念就是无论使用什么 Agent，先装一些通用的基础插件，之后再根据具体需求增加插件并根据项目选择性开启。尽量避免一上来就装一大堆重型插件，尤其是那种大而全的包办类型插件质量往往不高。功能复杂往往导致架构和实现复杂，维护困难，就全用 AI 改。其实很多时候根据不同的项目需求自己写 Skills/插件/工作流效果更好，没必要什么级别的项目都非要用重型框架和重型扩展。另外对于 Pi 的 Packages 也是，并不是下载量越高就越好用，得根据自己实际需求来选。
权限管理
Pi 默认是不带任何权限管理以及沙盒的。这使得 Pi 的整体使用很丝滑（rm -rf / 也很丝滑，嗯）。所以在非容器内跑 Pi，加一个权限管理还是安心不少。
这里推荐 gotgenes 的 pi-permission-system，比较喜欢它的扁平化配置。
配置位于 ~/.pi/agent/extensions/pi-permission-system/config.json。
我目前的策略是：
- 拒绝访问项目和用户目录的敏感路径。
- 允许访问当前工作目录，访问外部目录时询问用户，但排除
.pi自身的目录，不然读个全局 skill 疯狂弹窗。 - Bash 执行敏感操作时询问——至于为什么不是拒绝，我测试过即使设置为拒绝，LLM 有时候也会疯狂想办法钻漏洞绕过，比如写 JS 脚本删。所以我选择 ask 并由用户来判断。
我正在使用的示例配置如下：
{
"$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",
"*\\users\\*\\.pi\\agent\\skills\\*": "allow",
"*\\users\\*\\.pi\\agent\\npm\\*": "allow",
"*\\users\\*\\.pi\\agent\\sessions\\*": "allow",
"*\\users\\*\\.pi\\agent\\repos\\*": "allow",
"*\\node_modules\\@earendil-works\\*": "allow",
"*\\node_modules\\@earendil-works": "allow",
"*\\dev\\null\\*": "allow",
"*\\dev\\null*": "allow",
"*\\dev\\null\\": "allow",
"*\\dev\\null": "allow"
},
"path": {
"*.env": "deny",
"*.env.*": "deny",
"~/.ssh/*": "deny",
"$HOME/.ssh/*": "deny",
"*\\users\\*\\.pi\\agent\\auth.json": "deny",
"*\\users\\*\\.pi\\agent\\models.json": "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 一直工作在召回率较高的区间，同时不容易丢失一些重要信息。
扩展支持手动配置触发 observer、reflector 和 compact 的 token 数。配置写在 Pi 的 settings.json 里即可。
后悔药
Undo / Rewind 类
pi-rewind — 这个插件比较接近 CC 上 /rewind（undo）的效果，不过几个月没更新了。它是通过 Git checkpoint 实现的，强制要求项目已经初始化 Git。默认无需额外配置。
pi-workspace-history — 相比上面的我更推荐这个。它用的是 shadow git，所以不需要项目初始化 Git。它注册的 /undo 命令是撤销上一次的整个对话以及文件更改，也支持 /redo。如果想实现类似 CC 的 /rewind 效果，得用 Pi 自带的 /tree 命令，切换节点的时候就会自动触发 pi-workspace-history 的文件恢复了。
消息撤回类
pi-wtf — 在你输入内容有 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 了。
如果不幸遇到的话，目前有一个暂时的解决办法：使用 pi --exclude-tools find,grep。--exclude-tools 这个参数也是最近版本才更新的（见 Release v0.77.0 更新日志），也有用户在 Issue #5084 提到了可以把 exclude 写到配置文件里，不过 issue 被自动关掉了。
还需要注意的一点就是这个扩展为了增强 Pi 自带的 @ 选文件功能，覆盖了 editor（Pi 的输入框），所以会和一些同样修改了输入框部分的一些扩展冲突，具体谁覆盖谁就看扩展的加载顺序了（当然也有可能直接报错）。
显示美化
推荐 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 进程干崩了。
验证与自查
- 安装扩展后重启 Pi，
/reload重载扩展，确认新命令（如/undo、/plan、/btw、/tool-display）出现在命令列表中 - 权限系统：在项目中让 Agent 执行
rm或读取.env，应触发询问/拒绝（取决于配置） - 子代理：给 Agent 一个复杂任务，观察它能否派发子代理并在主界面收到权限询问弹窗
- 查询增强：在会话里让模型使用
ffgrep/fffind，确认工具可用且速度明显快于内置grep/find
结语
Man! What can I say, Pi out!
就写到这吧，在 Joplin 里全文手打无 AI 帮忙整理润色还是太累了，写了一半撤销后面发现丢了点内容，但具体丢了哪些我已经没啥印象了，气笑了。之后要是还能想起来就再更新（乐）。我目前使用场景主要是让 Agent 以本地文档为开发依赖，所以暂时并没有配搜索的扩展/MCP/Skills。欢迎佬友们补充更多实用扩展，实测好用的我会更新到帖子中。