我的个人Pi插件组合：14 个扩展与 12 个 Skill 的取舍实录

前言

Pi（@earendil-works/pi-coding-agent）官方的定位写得很直白：极简的 Agent 外壳（minimal, extensible agent harness），”ships with powerful defaults but skips features”。它把扩展能力做成四类——Extension、Skill、Prompt Template、Theme——打包成 Pi Package，用 npm 或 git 分发。

直接后果是同一个 Pi 在不同人手里是两个东西：装与不装、装哪一个，差别比换模型还大。

我把自己这套跑了一年多的组合完整拆了一遍：14 个扩展包 + 12 个 Skill，共 26 个组件。不做种草，也不做劝退，每个组件只回答三件事，并附一张同类横向对比：

1. 它替代了什么；
2. 装它换来什么（优点）；
3. 装它付出什么代价（缺点）；

资料依据是各包的 README、pi.dev/packages 目录页、Pi 官方文档，以及我自己的日常使用体感；检索时间为 2026-10-28。配置里的模型名、服务商、密钥一类信息全部隐去，只保留组件名。

一、先分清 Pi 的两类扩展

Extension 和 Skill 的边界要先划清，否则”插件”这个词会一直含混下去。

维度	Extension（扩展包）	Skill（技能）
形态	TypeScript 代码，注册工具 / 命令 / 钩子	SKILL.md + 附属脚本与参考文件
上下文成本	注册的工具描述常驻 system prompt	只有名称与 description 常驻，正文按需加载
能力上限	能改工具集、拦命令、读写文件、起子进程	只能指导模型，不能赋予新权限
触发方式	自动生效，或 /命令	模型按 description 自选，或用户手动 /skill:xxx
风险面	第三方代码可直接执行	提示词层面，可被忽略

Pi 的 Skills 实现遵循 Agent Skills 规范（agentskills.io）：同一份 Skill 目录可以跨 Pi、Claude Code 等宿主复用，我的 ~/.agents/skills/ 就是两边共享的。

一个容易忽略的原生事实，来自 Pi 的 settings 文档：

Available built-in tools are read, bash, powershell, edit, write, grep, find, ls.
defaultTools 默认值：read、bash、edit、write

也就是说 grep、find、ls 默认不启用。很多人以为”装了搜索插件所以搜得快”，其实是内核压根没给模型开放检索工具，这一点直接决定了后面几个组件的取舍。

二、组合全景

分层按它作用在 Agent 循环的哪一环，不按功能目录：交互（问得对不对）→ 模型行为（想多深）→ 规划（做不做、怎么做）→ 记忆（长会话不失忆）→ 代码理解（找不找得到）→ 外部信息（能不能联网看图）→ 交付（产出是什么格式）。最底下那条是安全网，横穿所有层。

三、逐层点评

① 交互层：让分歧提前暴露

@juicesharp/rpiv-ask-user-question

给模型一个 ask_user_question 工具，最多 4 题、每题 2-4 选项，终端里弹出带 Tab 分栏的问卷。

• 优点：把”猜错方向再返工”变成”15 秒选一次”。选项可以带 preview 字段渲染 Markdown 对比框，ASCII 线框图、代码片段、配置方案并排看，这是纯文字提问做不到的；答不完会在 Submit 页点名提醒，还支持给单个答案加批注。
• 缺点：它改变模型行为的方式是”鼓励提问”，实测在指令模糊的任务上会被滥用——本来能合理默认的事也要弹窗打断一次。需要在 AGENTS.md 里补一条约束（我写的是”同一批问题一次问完，不许连续调用”），属于必须调教型组件。
• 同类：Pi 生态里这条赛道的包不少——pi-question-tool（单题+问卷两种形态）、edlsh/pi-ask-user（可搜索的单选长列表 + 分栏详情）、@qmahyar/pi-ask（单表单，最轻）、@arvoretech/pi-ask-user-question（同项目的 fork，额外支持把问题发到 Slack 按钮作答）。如果你需要”离开终端也能回答”，@arvoretech 那个 fork 才是目标件；纯终端场景 rpiv 的功能面最全。

@narumitw/pi-btw

/btw <问题> 立刻在侧线程开一个临时会话，主 Agent 继续干活，只有你显式带回的结果才进主上下文。

• 优点：解决长任务里最烦的一类中断——“顺手查一下这个东西”。侧线程能读主会话已持久化的分支作为背景，不用切换分支，主上下文不被污染。
• 缺点：结果默认不会自动回流，忘了带回来就等于白问；侧线程的模型与思考级别跟随全局设置，不能针对一个 trivia 单独降级省钱。
• 同类：QuangThai/pi-btw（多槽位并行侧问）、@pi-unipi/btw（用面板替代输入框，只读新会话）、LukasParke/pi-subagent（/btw 跑只读子代理，带预算与信号量）、tintinweb/pi-subagents / leninkhaidem/pi-crew（完整子代理编排）。只是想”顺嘴问一句”选 pi-btw；要并发跑多个子任务，应该直接上 subagent 类。

pi-jingle

按事件播放提示音：agent_start / agent_end / turn_end / session_shutdown 等。

• 优点：配置面极小，一个 sounds 对象搞定，支持音量；路径写法上 ~/sounds/x.mp3 会解析到 ~/.pi/sounds/，不需要写绝对路径。跑长任务时可以真正切走干别的。
• 缺点：纯本地音频播放，不处理”你是不是正在看终端”这个判断——Agent 每次收尾都响一次，在盯着屏幕看的时候反而成了噪音；Windows 下的播放实现也比 macOS/Linux 更容易出问题。
• 同类：pi-chime（只发终端 BEL，零依赖最克制）、ferologics/pi-notify / maxpetretta/pi-alert（原生桌面通知）、pi-notify-agent（可设阈值，超过 N 秒才提醒）、pi-focus-bell（tmux 感知，你正盯着那个 pane 就不响）。“只在我不在时才提醒”这个需求，pi-focus-bell 或 pi-notify-agent 明显更合理，pi-jingle 是”我就要听歌”的选择。

② 模型行为层：思考级别和任务路由

@tifan/pi-preferred-thinking

用 /preferred-thinking 给当前模型钉一个思考级别，写进 enabledModels，之后切换模型时自动应用。

• 优点：把 enabledModels 里手写的 provider/modelId:level 语法变成一次 TUI 选择。多模型轮换的人确实省反复设置：

{
  "enabledModels": [
    "providerA/model-x:xhigh",
    "providerB/model-y:high"
  ]
}

• 缺点：它本质是原生能力的一个写入助手。enabledModels 手工写死就能达到同样效果，不装也行；而且它要求 enabledModels 必须已存在，否则直接拒绝保存；旧版本的独立配置文件 pi-preferred-thinking.json 已经不再读取，老用户得迁移；另外它需要 Pi 0.84.2+。
• 同类：pi-effort（/effort 一条命令直设，还带 OpenAI/Codex fast mode 开关）、pi-thinking-levels（/thinking high 风格，最轻）、pi-adaptive-thinking（让 Agent 自己判断并调整 effort）、Kiri-Pi-ModelEffort（Claude 与 GPT 分别存预设）。想要”自动”选 pi-adaptive-thinking，想要”最小命令面”选 pi-effort，只有你确实在多个模型间高频轮换、且不想手写配置时，preferred-thinking 才有净收益。

deepseek-v4-flash-router（扩展 + Skill，我自建）

我针对 DeepSeek V4 Flash 做的任务路由：build 类先实现再验证，fix 类先看证据再最小修复，并且只对精确匹配的 provider/model 生效。

• 优点：这类小模型有明确的失效模式——无意义的环境探测、穷举扫描、机械重试同一条失败命令。用正则做任务分类 + 收敛提示，能实打实压住。因为同时是扩展，门控是自动的，不用每次手动喊。
• 缺点：维护成本高于收益。硬编码的模型标识一变（换服务商、加版本后缀）就静默失效；结论不可外推，Flash 的表现不能套到 Pro 上；作为 Skill 时它靠模型自觉，作为扩展时它是代码注入，两条路径的可靠性不一样。这类东西写第 2 个就开始心疼维护费。
• 同类：Pi 生态里最接近的是各家 skill pack，例如 pi-gauntlet（带门控的工作流 + 子代理 persona）、以及 @piex-dev/hashline 这种把编辑动作本身收紧的组件。更通用的解法是换一个会自己收敛的模型，或把规则写进 AGENTS.md——只有当某模型确实在特定任务上有可复现的系统性缺陷时，自建 router 才划算。

③ 规划层：动手之前先画路线

@burneikis/pi-plan

/plan <目标> 进入规划态：edit 直接禁用，write 只允许写计划文件，bash 中任何落盘、装包、改 git 的动作被拦。Agent 把方案写进 ~/.pi/agent/plans/<session-id>/plan-<时间戳>.md，然后弹菜单：Execute / Refine / Edit / Cancel。批准后开一个全新会话，以计划为首条消息，旧的规划上下文不进新会话。

• 优点：(a) 只读是代码层的强制，不靠模型自觉；(b) 计划落在磁盘上，可 diff、可复用、可跨重启；(c) 执行阶段用干净会话，不被探索过程的噪音挤占上下文。
• 缺点：README 自己也写明了，这套 gate 挡的是”误操作”，不是”故意越狱的模型”；多一次会话切换意味着上下文交接全靠那份 Markdown，计划写得含糊，执行就走样。
• 同类：@bacnh85/pi-plan（Ctrl+Alt+P 快捷键切换，并跨会话记住 plan-mode 专用模型和思考级别，把规划交给便宜模型这件事更彻底）、cfuentessalgado/pi-plan（/plan-resume 从已勾选的检查点续跑）、devkade/pi-plan（YOLO / plan 双模式 + /todos 进度）、@pandi-coding-agent/plan（Claude 式只读 + 显式批准）、@gamaraan/todos-tool（只做 todo 不做 plan）。在意成本分层就选 @bacnh85 那个，在意”审完再放”就选 @pandi，@burneikis 的差异化在”干净会话执行”。

wayfinder（Skill）

把一个超过单会话容量的大任务，在 issue tracker 上铺成一张 wayfinder:map 标签的地图，其下挂”决策工单”（要产出决定，不是产出代码），一张一张解决，直到路线清晰。

• 优点：“决策”而不是”任务切片”作为单位，这个抽象很反直觉但有效——它逼着把未定事项显式化。地图是索引不是存储，一个决策只活在它的工单里，地图只给摘要 + 链接，避免了复述漂移。它还强制”用名字指代工单”，不许甩一串 #42 #43，可读性确实好。
• 缺点：依赖 issue tracker。没提供 tracker 时它退到 local-markdown，跨人协作价值立刻减半；重量级明显，中小任务是纯负担；disable-model-invocation: true 意味着模型自己不会想到用它，得你记得 /wayfinder。
• 同类：grill-me（同一作者的另一个技能：不带方案地连环拷问，把前提里的水挤干，比 wayfinder 轻得多）、pi-t-plan（三层任务分级 + spec-driven 记忆）、pi-plan（单次会话内规划）。三者其实是一条谱系：grill-me（审问）→ wayfinder（铺地图）→ pi-plan（出计划并执行）。按任务体量选一个，不要同时指望它们协同。

grill-me（Skill）

同一个作者的另一个技能：对准一个方案或设计连环拷问，把藏在前提里的模糊处、未定处、想当然处全部挤出来。disable-model-invocation: true，只能你手动 /grill-me 拉起来。

• 优点：它是唯一一个不产出任何东西、只负责挑刺的技能，恰好补上 AI 辅助最缺的那一环——模型天然倾向于接受你给的前提并开始干活，grill-me 把「先别写，先想清楚」变成显式动作。成本比 wayfinder 低一个量级，不需要 issue tracker、不留任何持久产物，十分钟就能把一个烂方案问穿。放在 pi-plan 之前用，能显著减少「计划写得很完整、但前提错了」这类返工。
• 缺点：拷问的收敛性没有保证。它不给「问完了」的判据，深一层的追问可以无限继续，时间预算完全靠你手动叫停，容易从「想清楚」滑向「一直想」；产出是一段被问清楚的对话，没有落盘结构，谈完不接 pi-plan 或 wayfinder，成果很容易丢；拷问质量完全取决于模型，弱模型会退化成礼貌性复述你的话。另外它强制手动触发，模型自己永远想不起来用它。
• 同类：@burneikis/pi-plan 的 Refine 环节（写完计划后你描述修改，它重写，但它是先给方案再让你改，不是先问）、@pandi-coding-agent/plan（只读 + 显式批准）。真正的同类空缺：Pi 生态里没有一个「只质疑不产出」的扩展，因为这种能力本质上属于提示词层，只能靠 Skill 或自己写进 AGENTS.md，定位很难被取代，但也没法被量化验证。

④ 记忆与上下文层

pi-observational-memory

会话进行时持续记录”观察”和”反思”，压缩到来时不必现场重写历史；压缩后的记忆保留 id，可以精确回捞原始证据（我这次写作就靠 recall 找回过被压缩掉的原文）。

• 优点：把压缩从”事后有损摘要”变成”事前增量记录”，why a design decision was made、什么已经被否决过这类最容易丢的东西保得住。V3 的结构化记录 + recall 取证，比”只留摘要”更抗幻觉。
• 缺点：版本迁移是硬伤——V3 完全不读 V2 的设置和记忆格式，升级后必须开干净新会话，旧记忆直接放弃；另外它引入 3 个常驻工具（record_observations / record_reflections / drop_observations），短会话里纯属白交上下文税。
• 同类：pi-blackhole（确定性压缩 + 观察式记忆二合一，用算法结构摘要取代 LLM 摘要，压缩这一步零 token 成本，是”我嫌原生压缩贵”最直接的答案）、pi-observational-memory-extension（Mastra 风格两层模型，完全替换 /compact）、@sovorn/pi-observational-memory（带时间戳账本）。如果只装一个记忆组件，pi-blackhole 的信息量更值得看；pi-observational-memory 的优势是成熟度和可回捞的证据链。

pi-context-usage

/context 画一张点阵图显示上下文占用，/context details 展开 system prompt、活跃工具、逐条对话轮次。

• 优点：装了一堆扩展之后，“我到底付出了多少上下文”必须有地方能看见——否则上下文税完全是抽象概念。点阵图的直观程度远超一行数字。
• 缺点：估算方式写明是 字符数 / 4（Math.ceil(systemPrompt.length / 4)），对中文、代码、tokenizer 差异都会失准，只能看量级不能当账单；而且它多了一个 /release 发布工作流命令，对使用者是无关噪音。
• 同类：@taimoorchatha/pi-context-footer（把进度条直接放进 footer，每轮自动更新，不占命令）、chengzhi-c/pi-signal-footer（模型 / token / 缓存 / 成本 / MCP+LSP 状态一栏打尽）、aporcelli/pi-usage（配额与消耗统计）、ZaganJade/pi-context（分类拆解 + 跨模型交接）、algal/pi-context-inspect（纯诊断）。想要常驻可见选 footer 类（pi-signal-footer 最全，还带成本），想要偶尔深挖选 /context 这类命令式。

pi-rtk-optimizer

把 bash 命令透明改写成 rtk 等价形式，并对 bash / read / grep 输出做多阶段压缩（去 ANSI、测试结果聚合、构建错误提取、git 输出精简、lint 聚合、grep 按文件分组、智能截断、锚点安全压缩、硬截断）。

• 优点：对输出量大的工具链收益直接——RTK 上游宣称常见命令可压缩 60-90%。它的锚点安全设计（识别 hashline/anchored read 输出时保留完整编辑锚点）说明作者真的在用 Pi 改文件，不是纸上谈兵；rtk 二进制缺失时有 guard，命令原样执行。
• 缺点：多一个外部依赖，且行为不透明。命令被改写、输出被摘要，模型看到的世界和你终端里的不一样——调试时”为什么模型看不到那行报错”会真实发生，必须靠 black/white 名单和 /rtk stats 去查；Windows 侧还需要额外的 shell 修正。另外它与我自建 router 的”读完整错误信息”这条要求是隐性冲突的。
• 同类：上游 rtk-ai/rtk 本身就是 agent-agnostic 的 CLI proxy（Claude Code 用 PreToolUse hook 接）；Pi 侧还有 @piotr-oles/pi-reflag（只做 grep→rg 重写，无输出压缩）。不想引入二进制的轻量替代：调 Pi 原生截断 + 用 pi-fff 的分组返回，也能拿到大部分收益。

memmy-memory（Skill）

把记忆放在 Pi 之外：一个所有 Agent 共用的 Memmy 记忆库，通过 memmy-memory CLI 读写，输出 JSON，靠 --source pi 标注写入来源。

• 优点：跨宿主共享是它和上面那个记忆件最大的区别。pi-observational-memory 记的是「本次 Pi 会话的上下文」，而它记的是「我这个人在各个 Agent 里累积的事实」——同一条偏好、同一个未完成的 follow-up，不必在 Pi 和另一个终端 Agent 里各存一份。它同时给出了明确的记忆卫生规则：--source 标注、只存自包含的事实与决定、禁止存密钥和原始日志、把 <memmy_memory_context> 当历史、把 <current_user_request> 当权威当前任务；输出全部走 JSON 字段而不是靠肉眼读显示格式。服务不可用时要求「继续任务但不编造记忆」。
• 缺点：多一个外部依赖和一层一致性风险。需要 --url / --token / --config 任一配置，本机没起服务就整条静默失效；所有 Agent 共用一个数据库，意味着串味风险由你承担——一旦某个 Agent 写入了错误结论，其他 Agent 会把它当既有事实继承下来；--tags 要手工维护才有检索价值，标签一乱就退化成存了但取不出的死数据。
• 同类：和它同思路的是「外部记忆层」这一类（mem0、Letta 这类 Agent memory 服务，以及各类自建向量库检索件）；Pi 生态内部的对应物就是 pi-observational-memory / pi-blackhole（会话内记忆）与原生 compaction。选择很清楚：只在一个终端里干活，用 pi-observational-memory 就够；经常在多个 Agent / 宿主之间来回切，才需要它这种共享库——但两者都装时，建议把「会话内」和「跨会话」的分工写进 AGENTS.md，否则会出现同一条信息被写两次、取的时候互相矛盾。

⑤ 代码理解层

@ff-labs/pi-fff

用 Rust/SIMD 的 FFF 库替换内置 find 与 grep，提供 fffind / ffgrep / fff-multi-grep（Aho-Corasick 多模式），并接管 @ 文件补全。

• 优点：三条我每天都用得上——(1) frecency 排序，最近访问过的文件先出来，改一个模块时命中率高得离谱；(2) git-aware，未提交/已修改文件加权，重构时不会漏掉脏文件；(3) 不起子进程，mmap 缓存，后台预索引。fff-multi-grep 的多模式并查在跨文件定位时也很省轮次。
• 缺点：排序哲学与”我要穷举”冲突。它默认按 freq 排序并截断（limit 20/30），需要完整清单时会给你一种”找完了”的错觉，我在核对全局引用时就漏过一次——这种漏是隐性的，比慢更危险；原生 find/grep 被替换掉，出问题时得记着回去；另外它带来 3 个常驻工具描述。
• 同类：@tian.zuo/pi-find（老老实实 rg/fd 后端 + 有界输出）、@nklisch/pi-fff-compat（FFF 的速度 + Pi 原生语义：glob-only 查找、精确 regex/字面匹配、无模糊回退——就是冲着上面那个缺点写的）、yikZero/pi-fff-rg（保留 FFF 找文件、用 rg 做内容搜索的 fork）、tgrep-pi（微软 trigram 索引）、pi-prefer-rg（只提示模型优先用 rg，纯提示）。要穷举精确性选 pi-fff-compat 或 @tian.zuo/pi-find；日常定位选 pi-fff。

@vndv/pi-codegraph

把 CodeGraph 的 tree-sitter 索引暴露成 8 个原生工具（codegraph_search/node/files/callers/callees/impact/explore/status），不需要配 MCP。

• 优点：“谁调用这个函数””改这个符号影响哪些”用 grep 是问不出来的。一次 codegraph_explore 返回多个相关符号并按文件分组，替代好几轮 grep+read；纯扩展工具，无 MCP server 要维护。
• 缺点：索引是有状态的基础设施。要先 npm i -g @colbymchenry/codegraph 再 codegraph init -i；索引过期要 sync；格式版本不匹配会直接报错（store format version X vs Y）；我这种 WSL + Windows 双环境读写同一个工作区的情况，最容易出现 SQLite 锁、WAL 残留和跨环境读器混用，所以规则里明确禁止两边共用一个 .codegraph/。此外我钉死了 0.1.10 版本，因为新版工具名变化会打破我的 AGENTS.md 约定。
• 同类：pi-shazam（tree-sitter + LSP 共 7 个结构分析工具）、pi-serena-mcp（Serena 语义代码智能，走 MCP）、akaza21/pi-codeindex（定义/引用/callers/继承/AST 形状，纯本地）、alexykn/pi-cbm（把 codebase-memory-mcp 包成原生工具并自动索引）、R-Dson/pi-codebase（Node 进程内实现，不依赖 Go 二进制）。要类型精确度和跳转选 LSP 路线（pi-shazam / Serena）；要调用图和影响面选 CodeGraph；R-Dson 那种进程内实现是”不想装额外二进制”的折中。

⑥ 外部信息层：三个组件抢同一块活

这一层是我这套组合里唯一真正”冗余”的地方。

@bytetrue/pi-web-search

提供 web_search + web_fetch，默认零配置的 Exa MCP 免费通道，/web 里可选 provider、配 API key、SearXNG 自建实例和 HTTP 代理。

• 优点：provider 链 + 自动回退，第一个失败才试下一个；fetch 侧做了 redirect 重校验、SSRF 检查、强制纯文本、10 MiB 解码上限，大文本落临时文件后续再读，不硬塞进上下文。Bing 免密钥这条通道对国内无代理环境很实用，这是我留在主链上的原因。
• 缺点：README 明确要求移除任何已注册同名 web_search / web_fetch 的扩展——Pi 工具名必须唯一，这个包和 web-access、pi-web-access 之类的冲突需要自己处理；/web 的 API key 输入框默认是明文显示，录屏/共享终端时得改用环境变量。
• 同类：pi-web-access（OpenAI/Codex 搜索 + 零配置 Exa + Brave/Parallel/TinyFish 等，还带视频理解）、@counterposition/pi-web-search（4 后端 + markdown 输出）、@juicesharp/rpiv-web-tools（10 后端集中管理 key）、pi-search-hub / pi-search-multi（含 DuckDuckGo 免费无限、Marginalia 等长尾后端，带缓存与 fresh 模式）、pi-search-boost（多引擎融合 + 深度研究循环 + 并行子代理）、donsetch（单个 Rust 二进制搞定 fetch/search/crawl/screenshot，零 key）。要”零 key 立刻能用”看 pi-search-hub；要研究型多引擎看 pi-search-boost；只是偶尔查一下，当前这个的 Exa 免密钥 + Bing 足够。

web-access（Skill，一泽Eze，v2.5.4）

所有联网走一个入口：CDP 直连你日常已登录的浏览器，静态层（WebSearch/WebFetch/curl）→ Jina 转 Markdown → 需要登录态/动态渲染时直接上浏览器 /eval、/click、/screenshot；还带站点经验库 site-patterns/ 和本地书签/历史检索 find-url.mjs。

• 优点：解决”公开搜索永远搜不到”的那部分。抓取小红书、公众号这类静态层无效的内容，只有带登录态的真实浏览器可行；它把”先选路径 → 定义成功标准 → 每步用结果验证 → 判断是否已达标”写成纪律，比裸工具调用少走很多弯路；共享一个浏览器一个 Proxy、多子代理按 targetId 分后台 tab 的并发模型也很省资源。
• 缺点：授权摩擦和安全边界是最大代价。开 CDP 调试端口本身是较大权限，README 也承认部分站点检测严格存在账号风险；切换浏览器要重启 proxy 并重新授权；文档体量非常大（我的这份还加了 WSL/Windows 路径适配注记），Agent 每次都要吃掉这一整篇。
• 同类：pi-browser-harness（真实 Chrome + CDP：navigate/click/type/screenshot/extract）、pi-chrome-dev-tools（Playwright 懒启动 + 持久 profile + stealth patch）、pi-browser-actions（Playwright 有状态自动化 + markdown 提取）、pi-browser-use（基于 chrome-devtools-mcp，明确不用 Playwright）、以及下面的 pi-chrome。这个 Skill 和几个浏览器扩展不是互斥的：Skill 提供”怎么联网思考”的纪律与脚本，扩展提供稳定的工具面。但两者都装就必须给模型写清优先级，否则它会在两条路径间随机选。

pi-chrome

装一个你自己审过的 unpacked Chrome 扩展，通过 127.0.0.1:17318 回环桥接，让 Agent 在你已登录的 Chrome 里操作；每个会话要显式 /chrome authorize 才解锁工具。

• 优点：“attach 你的真实 profile”而不是”另起一个干净浏览器”。官方对比文档写得很清楚：Playwright/Puppeteer/Selenium 默认用一次性 profile，得靠 storageState 导出重放 cookie，而 OAuth/SSO 常把会话绑到 TLS 指纹和设备 ID 上，重放直接失效；并且 Playwright 指向你真实 user-data-dir 需要你先关掉日常 Chrome（profile 锁）。pi-chrome 因为就住在 profile 里，绕开整串问题。另外它的定位是 axis 1 的原语，不是 Agent loop——没有 LLM 循环，所以不会被塞进你不想要的意见；chrome_snapshot 返回稳定 uid 供后续动作引用；authorize 前 23 个工具不注入上下文，不白交税。
• 缺点：上手步骤最多（/chrome onboard → 开发者模式 → Load unpacked → /reload → /chrome authorize → /chrome doctor），而且每次会话要重新授权；扩展需要 tabs / scripting / debugger / webNavigation 大权限。安全上 README 自己说了”不同的安全边界，不是更安全”——它是扩展权限模型，不是隔离模型。威胁模型不接受大权限扩展的人，两个方案都不合适，该用沙箱 CI。
• 同类：选型按它自己的三分法就清楚了：CI 里做确定性 e2e 用 Playwright/Cypress；云端隔离 profile 集群用 Browserbase/Steel；要 Agent 用你日常登录态，pi-chrome 是这类里最工整的。

@zhushanwen/pi-vision

注册 analyze_image，把图片交给多模态模型分析，支持 fresh（独立会话）与 fork（继承父上下文），通过 spawn 独立 Pi 子进程实现。

• 优点：主会话模型可以完全不是多模态——文本模型也能”看懂”截图，图不进主上下文，token 花得明白；fork 模式让”分析这张报错截图”能接上前文语境；临时文件自动清理。
• 缺点：要额外维护一份 vision-models.json 模型配置，没配就直接不可用；起子进程有真实延迟；分析结果只有文字结论，丢失了原图的版面细节。
• 同类：pi-see（通用 vision proxy，任何模型可描述图片/截图/图示）、pi-vision-tool（describe_image，明确面向 Qwen VL 这类模型）、pi-inspect-image（inspect_image，走 OpenAI 兼容 API）、pi-multimodal-proxy（视频 / 音频 / YouTube 理解 + 成本路由的 vision + 会话图片回捞，功能面最广）、pi-vision-agents（图片转 pimage、视频转 pideo）。只要图片看一眼的选 pi-see/pi-vision-tool；要处理录屏、音频、并按成本把请求路由到便宜视觉模型，pi-multimodal-proxy 覆盖更全。

⑦ 交付产出层

docx（Anthropic 官方 Skill）

把 .docx 当作”装着 XML 的 ZIP”来处理，创建、读取、改 Word 文档，带目录、页码、页眉页脚等排版细节。

• 优点：官方维护，能力覆盖 XML 层。这是”从 .docx 提取内容进 Agent”和”输出可交付 .docx”两个方向的通道；我的实际用法是把单位给的 Word 周报模板喂进去生成初稿。
• 缺点：license 是 Proprietary（不是 MIT），商用分发要读它的 LICENSE.txt；单次任务链长——要跑脚本、要校验 zip 完整性，比 Markdown 出稿慢一个数量级；而且它只保证”合法可打开”，不保证符合你单位的排版规范。
• 同类：纯命令行路线 pandoc x.md -o x.docx --reference-doc=template.docx（模板驱动，一行命令，排版跟随参考文档）；代码路线 python-docx / docx.js（可控但从零写）；anthropics/skills 仓库里的 pdf/xlsx/pptx 是同族的官方件。只是格式转换，pandoc 更快更省；要精确控制段落、域、页眉，才需要这个 Skill。

ppt-master（社区 Skill）

源文档（PDF/DOCX/URL/Markdown）→ 多角色协作产出 SVG 页 → 导出 PPTX。

• 优点：把排版问题转成图形问题，SVG 是模型擅长稳定产出的介质；带 templates/workflows/references 分层，符合 Skill 的渐进披露；中文场景友好。
• 缺点：中间产物是 SVG 图形页，导出后的文字可编辑性和母版继承不如原生 pptx 结构；多角色协作意味着 token 与时延都不便宜。
• 同类：anthropics/skills 的官方 pptx（直接生成真 .pptx XML：slide + chart + 内嵌工作簿，可结构化校验）。有个对照实验记录值得看：官方 pptx Skill 相对裸模型少约 20% 输入 token，两组都可编辑、都没用图表截图交差，裸模型甚至用了更多形状（198 vs 149）。要”能直接改的正规 PPT”选官方 pptx；要”设计感强的图示化页面”选 ppt-master。

nature-writing / nature-polishing / nature-academic-search（社区 Skill，三件同族）

三者切的是写作流程的三个不同阶段，不是一份技能的三个版本。

nature-writing（v0.2.0）——从结果、要点、图表或中文草稿重建章节论证（摘要 / 引言 / 结果 / 讨论 / 结论 / 标题）。

• 优点：管的是论证骨架而不是句子，这是润色类工具碰不到的层次；支持从「只有要点笔记」的状态起手，对先有数据后组织文字的生信场景正好；带 agents/ 与 references/ 分层，不是一段裸 prompt。
• 缺点：重建意味着它会改你的论证顺序和结论表述，作者原意需要逐句对回去，否则容易把「观察到 A」写成「证明 A」这类越级断言；社区件无期刊侧验收背书。

nature-polishing（v5.0.2）——把已成稿句子润色 / 译成 Nature 倾向的英文，同时接 Academic Phrasebank 做短语级支撑。

• 优点：明确拆了两个层次（main strategy：篇章架构、已发表文章范式、章节逻辑、读者工作流、证据阀值、学术伦理；phrase-level：短语库），一次调用同时修结构和修句子；版本迭代到 5.x，说明作者自己一直在修。
• 缺点：倾向性很强，只锁 Nature/Nature Communications 的行文范式，投别的刊、中文学报、或基金文本都需要手工校正；和 nature-writing 同时对一份稿子用会产生风格拉扯。

nature-academic-search——多源文献检索（PubMed / CrossRef / arXiv）、引用核对、MeSH 检索策略、.nbib/.ris/.bib 互转与参考文献管理（BibTeX、相关文献、ID 互转），走 MCP 工具。

• 优点：这是三件里唯一带真实外部工具链的——它解决的是「检索与格式转换」而不是「文字」：MeSH 策略本身就是新手最容易出错的地方，而 .nbib/.ris/.bib 互转是纯体力活；需要跨源协同的多步文献工作（检索 → 核对 → 导出）确实超过单次 MCP 调用能做的范围。
• 缺点：带一个 mcp-server/ 目录和 install.sh，额外运行时依赖最重——要先配好 MCP 服务，而我当前这份配置里没有加载任何 MCP 客户端包，所以这个技能实际上处于「装了但不可用」状态，很容易让模型在不可用的工具上反复试探；联网检索质量受 PubMed/CrossRef 公共 API 的速率限制，批量核对引用时会被限流。

三者共同代价：同一族三个技能的 description 高度重叠，模型路由会歧义——你让它「润色一段」，它可能加载 nature-writing 的整篇重建流程，反而把段落改写了。建议只留一个当基线（我留的是 nature-polishing），另两个改成 /skill: 手动调用。

同类：最权威的参照是这些技能的事实上游 Academic Phrasebank（直接用它最可控但最费手）；英文润色另有通用路线（docx 同类的官方文档技能 + 自建 prompt）；文献检索的同类是单个 PubMed MCP / arXiv MCP，以及 Elicit、Consensus 这类闭源研究助手。只有当「多源检索 + 引用核对 + 格式转换」需要连着做完一串时，才需要这个编排型技能；只要其中一步，直接调对应 MCP 更便宜。

tdd / find-skills

• tdd（red-green-refactor，附 deep-modules.md / interface-design.md / mocking.md / tests.md）：优点是把”测试验行为不验实现”这个理念写成了可执行的判断标准，配套文档质量高，是典型的”技能承载方法论”用法；缺点是只有理念没有工具面——不会自动跑测试、不感知你项目里有没有 vitest/jest/pytest，弱模型会照着流程写出无意义测试。同类：pi-plan 类规划件（把测试计划显式化）、以及各家 spec-driven pack（如 pi-gauntlet）。方法论落地仍需项目侧的 hook 或 CI 兜底。
• find-skills（帮你发现并安装开放技能生态里的 Skill）：优点是降低生态发现成本，跨宿主共享一份目录（~/.agents/skills/ 在 Pi 和 Claude Code 都可见）；缺点是它把”装什么”这个决策交给搜索命中率，第三方 Skill 的提示词注入和质量完全无人审核——装之前得自己读 SKILL.md。同类：pi.dev/packages 官方目录页（带下载量和版本号）、awesome-pi.site（分类整理）、BubblePtr/awesome-pi。这个 Skill 适合”我知道有这东西但找不到”，不适合”我不知道该装什么”——后者更该先读官方目录。

安全网：pi-workspace-history

/checkpoint 打快照，/tree 是真正的时间机器，/undo、/redo 是它的快捷方式——核心目标是你跳到历史树的任意节点，聊天上下文和工作区文件状态一起回到那个节点的真实状态。

• 优点：这是我认为唯一值得无脑装的组件。Agent 改乱文件之后，原生 Pi 只给你聊天层面的导航，文件留在错误状态；/checkpoint 保护手工编辑这件事尤其实用。
• 缺点：需要额外的快照存储（磁盘占用随会话长度增长）；与 Pi 原生 /tree 的行为耦合，一旦上游导航语义变化就可能失配；这个包的目标宿主是 @mariozechner/pi-coding-agent，我用的发行包名是 @earendil-works/pi-coding-agent，这种包名分叉意味着兼容性得靠自己每次升级后手动验证——这也是我对所有非官方包的态度。
• 同类：@bacnh85/pi-checkpoint（纯 git ref 命名空间快照，每轮开始时记 HEAD/index/worktree，/undo 回滚）、pi-undo-redo（hybrid：git 仓库用 shadow git，非 git 也能用）、DavidEasden/pi-undo（内容寻址快照 + 持久化）、nicobailon/pi-rewind-hook（把 rewind 元数据作为隐藏条目写进会话本身，因此跨 fork/resume 存活）。如果你信 git，@bacnh85/pi-checkpoint 更透明可审计；pi-rewind-hook 的”元数据随会话存活”是另一个思路，跨会话恢复更稳。

四、组合层面：这套东西的真实代价

单看每个组件都”有点用”，组合起来才暴露四个问题。

1. 上下文税要有人结账。 26 个组件里，会往 system prompt 里塞常驻内容的（工具描述 + Skill 的 name/description）粗算超过 40 项。Pi 的 Skill 机制已经在做减法（只常驻 name + description，正文按需加载，官方文档明确”loads full instructions only when the task calls for them”），Armin Ronacher 对 Skills 与动态 MCP 的对比结论也是Skill 不需要服务端配合就能拿到更好的表现。但减法不等于免费——pi-chrome 用 authorize 门槛把 23 个工具挡在上下文外，正是对这件事的自觉。建议：装完立刻用 /context details 看一遍工具占比，超过 5% 就该砍。

2. 功能重叠必须显式裁决。 我这层的四处重叠：联网（pi-web-search 的静态搜索 vs web-access 的 CDP vs pi-chrome 的扩展桥）、图片（pi-vision vs pi-chrome 的 screenshot）、规划（pi-plan vs wayfinder vs grill-me）、记忆（pi-observational-memory 的会话内 vs memmy-memory 的跨宿主）。重叠本身不是错，没人裁决才是错——否则模型随机选一条路径，表现为”同样的活有时对有时不对”。我的裁决写在 AGENTS.md：静态搜索走 web_search；登录态和动态渲染才上 web-access/CDP；扩展只在我明确说”用我的 Chrome”时才 authorize。

3. 版本钉死与迁移成本。 三个真实痛点：pi-observational-memory V3 不读 V2 格式；pi-preferred-thinking 废弃了自己的 JSON 配置，改用原生 enabledModels；pi-codegraph 我把版本钉在 @0.1.10，因为新版工具名变化会打破既有约定。第三方包的能力可以只看一次，破坏性变更要一直盯着，这是我这一年付出最多的隐性成本。

4. 平台差异。 Windows + WSL 混用环境里，pi-rtk-optimizer 专门写了 Windows shell 修正，pi-jingle 的音频播放、pi-codegraph 的 SQLite 锁与 WAL 都更容易出问题。同一个 .codegraph/ / .pi/ 目录别让两个环境同时读写，构建产物也别跨环境共用。跨环境共用索引，是我踩过的最贵的一次。

五、按人群的安装建议

你的情况	建议装	可以先不装
只在终端里读代码、改小脚本	原生 read/bash/edit/write + pi-fff；想要检索先加 defaultTools: ["+grep","+find"]	其余全部
长会话 / 多日重构 / 大分支	pi-observational-memory（或 pi-blackhole）、pi-workspace-history、pi-context-usage	交付类 Skill、子代理
多个终端 Agent 之间来回切	memmy-memory（共享库）+ 一个会话内记忆件，并在 AGENTS.md 里分工	只在一个终端里干活时，共享库是多余的
需要联网查资料、读带登录态的页面	@bytetrue/pi-web-search 打底；确有需要再上 web-access 或 pi-chrome（二选一，别都常驻）	浏览器 + Skill 双份常驻
主模型不是多模态，但要处理截图 / 测序图	@zhushanwen/pi-vision（配好 vision 模型清单）或 pi-multimodal-proxy（还管视频音频）	直接切换主模型
生信 + 论文写作为主	nature-writing 或 nature-polishing 留一个当基线、nature-academic-search、docx、ppt-master	全套官方文档技能
在意 token 单价	pi-rtk-optimizer（接受其外部依赖）、pi-context-usage 做验证	多引擎 pi-search-boost、多角色 ppt-master（都是 token 大户）
只信 git	@bacnh85/pi-checkpoint、tgrep-pi / pi-shazam	pi-workspace-history、pi-observational-memory（非 git 场景多存一份状态）

六、配置骨架

复现这套组合只要把包名写进 packages（模型、密钥类字段一律不落仓库）：

// ~/.pi/agent/settings.json
{
  "compaction": { "enabled": true },
  "retry": { "enabled": true },
  "theme": "dark",
  "packages": [
    "npm:@ff-labs/pi-fff",
    "npm:pi-observational-memory",
    "npm:pi-context-usage",
    "npm:pi-workspace-history",
    "npm:@burneikis/pi-plan",
    "npm:@vndv/pi-codegraph@0.1.10",
    "npm:@zhushanwen/pi-vision",
    "npm:@bytetrue/pi-web-search",
    "npm:pi-chrome",
    "npm:pi-rtk-optimizer",
    "npm:@tifan/pi-preferred-thinking",
    "npm:@narumitw/pi-btw",
    "npm:@juicesharp/rpiv-ask-user-question",
    "npm:pi-jingle"
  ]
}

Skill 目录分两处：Pi 专属放 ~/.pi/agent/skills/，跨宿主共享放 ~/.agents/skills/（Pi 与 Claude Code 都能读到）。自建扩展放 ~/.pi/agent/extensions/<name>/index.ts。

pi install npm:<package>        # 安装
/reload                        # 重新加载，使新工具生效
pi -e npm:@burneikis/pi-plan   # 不安装，先试一次
/context details                # 看工具与上下文占比

结语

把 26 个组件逐个写完，最一致的体会不是”哪个插件最好”，而是三件事：

1. 先摸清内核给了什么。grep/find 默认没开这种事实，比任何推荐清单都更影响结果；
2. 每装一个都在借未来的上下文和未来的维护时间，装完立刻量一次，比事后 debug”它为什么走错路”便宜得多；
3. 重叠不可怕，没人裁决才可怕。把它写进 AGENTS.md，模型才有稳定的路径。

如果你只想要一句话的结论：pi-workspace-history + 一个记忆件 + pi-fff + 一个联网件，是我这套里唯一在每次会话都在挣饭吃的部分，其余都是场景件。

参考资料

• Pi 官方仓库与文档：github.com/badlogic/pi-mono、pi.dev/docs（Skills、Settings、Compaction、Packages）
• 包目录：pi.dev/packages、awesome-pi.site/extensions、BubblePtr/awesome-pi
• 各组件 README / CHANGELOG（本地安装副本与 npm 页面）
• pi-chrome 官方对比文档 docs/COMPARISON.md（浏览器自动化三轴模型）
• RTK 项目：github.com/rtk-ai/rtk 及其 Claude Code 集成文档
• Anthropic 官方技能仓库 github.com/anthropics/skills、Agent Skills 规范 agentskills.io
• Armin Ronacher, Skills vs Dynamic MCP Loadouts（2025-12-13）
• Anthropic, Equipping agents for the real world with Agent Skills