Skip to main content

Pi 用满两个月后的配置：20+ 扩展与 Skill 实战清单

Pi 默认只有 4 个工具、~370 token 系统提示词，所有「能用感」都是扩展堆出来的。一个用户两个月实战后沉淀的配置，验证了「极简核心 + 行为外置」这条路怎么走。

  1. 起点：Pi 默认 4 工具（read/write/edit/bash），~370 token 系统提示词。
  2. 两条扩展线：Extension 改 Agent 自身（行为层），Skill 装领域知识（说明书层）。
  3. 必备扩展：bash-guard / file-changes / ask-user-question / web-search / web-fetch / subagents / video-extract。
  4. 领域 Skill：pdf-reader / stop-low / orchestrator / reddit。
  5. Sub-agent 极简：只 3 个角色 scout / researcher / worker，写代码用得很少。
  6. file-changes 是杀手锏：每个 write/edit 调用都记 diff，支持一键回滚。
  7. bash-guard 是第一道护栏：rm -rf、git push -f 这类命令弹窗确认。
  8. 终极原则：让 Pi 自己构建扩展，别手写代码。

极简起点：4 工具 + 370 token​

Pi 出厂时只有 4 个工具（read / write / edit / bash）、~370 token 系统提示词、零权限保护、零 MCP、零 sub-agent、零 plan mode。这套极简默认让 Pi 上手就跑得起来，也意味着所有「用得顺手」的能力都靠扩展装回来。

Eero Alvar 用 Pi 满两个月后，把配置整理成了一份清单：13 个 Extension + 4 个 Skill，外加 sub-agent、provider、slash command 等若干配置。把这份清单当案例看，可以反推「极简 + 行为外置」这条路在实战里到底长什么样。

两条扩展线：Extension vs Skill​

Pi 的扩展机制分两层，职责完全不同（参见 Pi 的 Extension 是什么？）：

  • Extension —— TypeScript 模块，订阅 30+ 生命周期事件，能注册工具 / 命令 / provider / UI 渲染 / 快捷键。改的是 Agent 自身的运行方式。
  • Skill —— Markdown 说明书，按需加载。告诉 Agent 怎么完成专业任务。

13 个 Extension 是「不装没法用」的硬需求；4 个 Skill 是「装上更好用」的领域知识。两层比例倒过来想，说明 Pi 的设计底线是「连安全护栏都不内置」——必须自己装 bash-guard 才能放心跑。

清单里大部分 extension 是 Eero 个人 config（视频结尾他说「I'll probably make these like Github repos later」），目前没单独建仓。下面贴的 GitHub 链接优先指向 oh-my-pi 主仓里功能最接近的内置实现（如 bash-interceptor、file-recorder、read-pdf），其余指向主仓 README。

必备扩展：按用途拆解​

下面按「没装之前会卡住什么」的角度，把 7 个核心扩展过一遍。

bash-guard：第一道护栏​

Pi 默认没有任何权限拦截——rm -rf、git push -f、覆盖关键路径都会直接执行。bash-guard 是清单里第一个被实现的扩展，监听 tool_call 事件，匹配到破坏性命令就弹确认框。

Pi 默认没有任何权限拦截

删文件、执行高危命令、push 到 main，都不会拦。bash-guard 必须第一个装。

实现起来很简单——订阅 bash 工具调用，正则匹配危险模式，命中就 ctx.ui.confirm：

pi.on("tool_call", async (event, ctx) => {
  if (event.toolName === "bash") {
    const cmd = event.input.command ?? "";
    if (/\brm\s+-rf\b|\bgit\s+push\s+(-f|--force)\b/.test(cmd)) {
      const ok = await ctx.ui.confirm("危险命令", `允许执行吗？\n${cmd}`);
      if (!ok) return { block: true };
    }
  }
});

file-changes：每步 diff 都记录​

清单里被点名「最喜欢」的扩展——监听 write 和 edit 的 tool_result，把每次文件改动按时间序列存起来。终端里实时显示 line-by-line diff，每一处字符串替换、每一处新增都能看到 delta。

杀手锏是支持回滚：edit 和 write 的工具输出里包含「exact line edits」，意味着只要记录了改动序列，就能精确 undo。Pi 在做非编码任务（写作、整理资料、调 API）时尤其需要这个——git 不一定能覆盖所有场景。

file-changes 的设计取舍

只跟踪 write 和 edit 工具产生的改动，不跟踪 bash 里跑的脚本。如果 agent 用 sed 改了文件，bash-guard + file-changes 都看不见。这是有意的设计——保持工具语义清晰，代码版本管理让 git 兜底。

ask-user-question：AI 在工具调用里追问​

普通 Agent 缺信息时，会在回复里列一串问句，让用户写一段回答。ask-user-question 把它改成工具调用——AI 用 multiple choice + custom answer 的形式发起追问，用户点选完继续工作。

优势：

  • 上下文不被打断——AI 不需要停下当前回合来组织问句
  • 结构化选项——多个备选让用户秒选，不用敲完整回答
  • 避免遗忘——强制 AI 在「继续干活」前补齐信息缺口

这是 Pi 整个配置里最高频的工具之一。

web-search & web-fetch：基础联网​

web-search 基于 Google Custom Search API，工具 schema 里直接支持 Google 修饰符（"exact phrase"、-exclude）。一次可以批多个 query。web-fetch 单独存在是因为——搜索引擎只返回 URL，不返回正文，需要单独一个工具把页面解析成 markdown。

subagents：3 个角色的极简配置​

Pi 默认没有 sub-agent，需要自己装。Eero 的配置是最简版：

角色职责用途
scout探索目录 / 代码库理解项目结构
researcher联网搜资料web 研究
worker写代码几乎不用

之所以 3 个就够，核心思路是「sub-agent 的价值是隔离上下文」。让 scout 去翻目录、researcher 去查资料，主 agent 的窗口就不会被中间产物填满——这两个角色是真正高频的。worker 角色存在是因为「sub-agent 完整链路要有」这个洁癖，实际很少触发，因为 Pi 自己直接调 edit 写代码比 fork 出一个 worker 再等结果更快。

agent 定义就是 markdown 文件，列出工具清单和模型描述。要加新角色只需要再写一个 md 文件。

video-extract：让 Pi 看视频​

给 Pi 加「看视频」的能力，分两种姿势：

  • 指定时间戳——「从 1:23 到 1:45 截帧分析」
  • 完整 Gemini 视频分析——直接把视频丢给多模态模型

实测演示里，给一段没有提示的「猜电影」短视频，video-extract 在 Opus 4.7 下能精准识别出处。适合做视频脚本、YouTube 内容研究、视频编辑 agent 的工具集。

4 个领域 Skill​

pdf-reader：手术刀读 PDF​

PDF 不能直接喂进上下文——数学符号、图片、表格混在一起，模型会被噪声淹没。pdf-reader 的思路是先看 PDF 顶层结构（meta 信息），按需展开：

  • 抽纯文本
  • 渲染特定页面为图
  • 提取特定图片分析

Skill 文件里写了「什么时候用哪个工具」的判断流程——比如「数学公式多的论文先渲染页图，文字为主的扫描件先抽 OCR」。

stop-low：从 claude-code skills 仓库搬来​

直译是「停低点」，作用是让 AI 写作少一点 AI 腔——去掉「总的来说」「值得注意的是」「深入探讨」这类套话。Eero 承认这个 Skill 是从社区仓库直接拷的，「thought this was good, seem to have worked」——不一定最优，但确实有用。

orchestrator：sub-agent 调度说明​

跟 subagent Extension 配合使用，告诉主 agent「什么场景该 fork 哪个角色」。Pi 本身已经知道怎么调工具，但「什么时候值得 fork、什么时候直接干」需要 Skill 显式描述。

reddit：Reddit 浏览能力​

为「YouTube 选题 agent」专门加的 Skill——能搜帖子、读评论、抓热帖。明确不该放在全局（只有内容选题场景需要），但因为还没重构到 agent 局部目录，目前还留在全局。

三条配置哲学​

Eero 的配置清单可以浓缩成三条经验：

极简默认 + 行为外置 = 长期可演进

Pi 两个月配置演进下来，13 个 Extension + 4 个 Skill 看似很多，但每一项都是被真实场景倒逼出来的——bash-guard 拦过一次 rm -rf 之后就不能不装，file-changes 救回过一次错误改动之后就成为默认。要点：

  1. 不要一开始就把所有扩展装齐。Pi 出厂就能跑，先用一周看哪里卡，卡哪里装哪里。Eero 自己说「这配置是两个月试出来的，不是设计出来的」。
  2. 自己做而不是直接用社区版。subagent 扩展他参考了别人实现，但最终写了极简版——「社区版塞了太多文件，会污染主 agent 的上下文」。fork 一份按需精简，比抄一份大而全更划算。
  3. 终极原则：让 Pi 自己构建扩展。Pi 能读自己的扩展文档，能自己写代码改 Extension，改完 /reload 热加载。要加新能力时，用自然语言告诉 Pi 它要什么，它自己写、自己测、自己改——这条原则把 Agent 从「工具使用者」升级成「工具制造者」。

写在最后​

Eero 自己总结这套配置的两点取舍：

  • 大多数 Skill / Extension 是按需积累——能用 default 跑就先跑，缺什么补什么
  • 核心极简 = 透明度 = 可控性——Pi 把所有能力开放成扩展点，用户能看清每一条行为是怎么来的

极简 Agent 路线不是「功能少所以差」，是「功能少所以清晰」。配置自由度高，意味着每一步加法都要想清楚代价。这条路在企业落地里被反复验证（见 PI Coding Agent 为什么是企业级 Agent 落地的优选底座？），在个人使用里同样成立——配置不是一次性写完，是和工具一起演化。

References​

视频​

  1. 两个月了，我的 Pi Coding Agent 配置长这样 —— Eero Alvar（63号炼金工坊 翻译转载）, 哔哩哔哩, 2026-05-31

源码（oh-my-pi 主仓里最接近的内置实现）​

  1. oh-my-pi 主仓 —— can1357, GitHub, 截至 2026-08
  2. bash-interceptor.ts（bash-guard 等价实现） —— can1357, GitHub, 2026-08
  3. auto-generated-guard.ts（bash 自动生成拦截规则） —— can1357, GitHub, 2026-08
  4. file-recorder.ts（file-changes 等价实现） —— can1357, GitHub, 2026-08
  5. ask.ts（ask-user-question 等价实现） —— can1357, GitHub, 2026-08
  6. web/（web-search + Kagi/exa 搜索） —— can1357, GitHub, 2026-08
  7. fetch.ts（web-fetch 等价实现） —— can1357, GitHub, 2026-08
  8. task/（subagent 调度） —— can1357, GitHub, 2026-08
  9. browser/（video-extract / 浏览器交互） —— can1357, GitHub, 2026-08
  10. memory-backend/（persistent-memory 后端） —— can1357, GitHub, 2026-08
  11. read-pdf.ts（pdf-reader 等价实现） —— can1357, GitHub, 2026-08

站内扩展阅读​

  1. Pi 的 Extension 是什么？TypeScript 扩展点 + 30+ 生命周期事件 —— Kimi Gao, 本站
  2. PI Coding Agent 为什么是企业级 Agent 落地的优选底座？ —— Kimi Gao, 本站
Last updated on by Kimi Gao