pi-extension

我使用 pi 时写的一些扩展插件（extensions），公开分享。

插件列表

文件	功能
extensions/commits.ts	/commits — 用列表查看当前分支提交历史，选中后 git show --stat 查看详情
extensions/checkpoint.ts	/checkpoint — 自动生成提交信息并提交当前 git 改动（绝不 push）
extensions/token-speed.ts	显示上一条回答的 token 生成速度（tok/s），通过 pi-footer 的 widget 展示；/speed 查看详细统计
extensions/steer-or-interrupt.ts	Opt+Enter：没有进行中的 tool 时立刻中断当前回答并发送；有挂起的 tool 时走内置 steering
extensions/auto-hide-thinking.ts	Herdr 下联动显示/隐藏 thinking 与完整工具块：生成中可见，整轮结束后收起；Ctrl+T 恢复两者，Ctrl+O 仍只控制工具展开。只在 Herdr pane 生效
extensions/scroll-to-last-prompt.ts	每轮回复结束后，自动把「我上一条消息」的第一行顶到屏幕顶部，方便从头顺序读本轮回复；生成中手动上翻过则不打扰，下次发送消息自动恢复跟随。只在 fullscreen TUI 生效
extensions/herdr-session-title.ts	把 pi 会话名作为 pane token（pi_session）报给 Herdr，供侧边栏 Agent 行显示；session_start / session_info_changed 时同步，/name 改名立刻跟着变。只在 Herdr pane 生效
extensions/reload-all/	/reload-all 把 Herdr 里所有空闲的 pi 窗口重载一遍；/restart-all 把它们重启一遍（换进程、各自回到自己的对话）。两者都跳过忙碌 / 输入框里有草稿的窗口
extensions/restart.ts	/restart — 重启本窗口（换进程，回到同一个对话）。/reload 只换扩展代码、不换进程，清不掉内存里被污染的状态时用它。只在 Herdr pane 生效
extensions/codex-usage/	/status 查看 ChatGPT Codex 的 5 小时 / 周额度，底部状态栏常驻摘要；复用 pi 管理的 openai-codex OAuth
extensions/model-filter.ts	隐藏内置 provider 里用不到的历史模型（默认过滤 openai-codex 的 gpt-5.3~5.5），在 /model 与 --list-models 生效
extensions/pi-footer.json	pi 底部状态栏（footer）配置：布局、图标、widget 等
extensions/pi-context-view.json	「Context View」颜色主题配置（各消息类型的颜色）

配套：Herdr 侧边栏显示 pi 会话名

herdr-session-title.ts 只是把名字上报成 pane token，还要在 ~/.config/herdr/config.toml 里把它排进侧边栏 Agent 行（保持两行，不换行，超宽由 Herdr 截断）：

[ui.sidebar.agents]
rows = [["state_icon", "machine", "workspace", "tab"], ["agent", "$pi_session"]]

没有名字的会话（token 被清空）第 2 行只显示 pi，不会留空行也不会多出第三行。

Skills

文件	功能
skills/read-terminal/	按需读取 Herdr 里另一个命名终端 pane 的屏幕 / scrollback。只在 Herdr 环境下生效，纯读取，不会向对方 pane 写入

安装

方式一：pi 包安装（推荐）

整个仓库已发布为 pi 包，一条命令装全部扩展和 skill：

pi install npm:@zionzionzion/pi-extensions

• 装的内容：extensions/ 下全部扩展 + skills/read-terminal
• 更新：pi update npm:@zionzionzion/pi-extensions（或 pi update --extensions 一并更新所有包）
• 卸载：pi remove npm:@zionzionzion/pi-extensions
• 只想启用其中部分：pi config 里按需开关，或在 settings.json 里用 package 过滤（见 pi 文档的 Package Filtering）

⚠️ 如果之前手动复制过扩展到 ~/.pi/agent/extensions/，装包前先删掉对应副本，否则会双加载。pi-context-view.json / pi-footer.json 是配置文件不是扩展，不随包分发，留在原处即可。

方式二：手动软链（按需挑选）

开发机上用软链，不要 cp：cp 出来的是拷贝，之后改仓库不生效、两边静默漂移；ln -s 的是同一个文件 —— 仓库即唯一真源。

git clone https://github.com/zion-zion-zion/pi-extension.git
cd pi-extension

ln -s "$PWD/extensions/commits.ts"  ~/.pi/agent/extensions/commits.ts    # 单文件扩展
ln -s "$PWD/extensions/codex-usage" ~/.pi/agent/extensions/codex-usage   # 目录型扩展
ln -s "$PWD/skills/read-terminal"   ~/.agents/skills/read-terminal       # skill

装完重启 pi，或在 pi 内 /reload。完整清单（哪些故意不装、哪些不属于本仓库）与漂移检查都在脚本里：

node scripts/link.mjs          # 检查：软链正确 / 拷贝 / 漂移 / 缺失
node scripts/link.mjs --fix    # 把「拷贝一致 / 缺失」收敛成软链；漂移项只报告

改完仓库里的代码要确认两边一致时，也跑上面第一条。给 agent 的完整规矩见 AGENTS.md。

放置路径：全局 ~/.pi/agent/extensions/，项目级 .pi/extensions/（需先信任项目）。快速测试可用 pi -e ./xxx.ts。Skill 路径：全局 ~/.agents/skills/ 或 ~/.pi/agent/skills/。

安全提示：扩展和 skill 都以你的完整权限运行，只从可信来源安装。

发布

npm 包由 GitHub Actions 自动发布：只要 package.json 的 version 变化并 push 到 main，CI 就会跑测试 → npm publish → 自动打 v* tag；版本号没变的 push 只跑测试，不会发版。

npm version patch   # 或 minor / major
git push            # 之后全自动，无需手动 npm publish

CI 定义见 .github/workflows/publish.yml。

依赖

.ts 扩展会 import pi 的官方包，pi 自带，无需额外安装：

• @earendil-works/pi-coding-agent
• @earendil-works/pi-tui
• @earendil-works/pi-ai

说明

• 目录里没有 herdr-agent-state.ts：该文件由 herdr 自动生成并管理，重装集成会被覆盖，不适合公开分发。
• auto-hide-thinking.ts 只在 Herdr 的 TUI pane 里生效：拿本 pane 自己的 hideThinkingBlock 当基准（settings.json 被所有 pane 共享，只能当兑底，不能用来判定“已经是目标值”），不一致时用 herdr pane send-keys 注入 Ctrl+T；thinking 隐藏时，Bash、Read、Edit 等工具块整体不渲染。Ctrl+T 会同时恢复 thinking 和工具块，Ctrl+O 仍只切换工具块内部的预览/完整输出。非 Herdr / print / RPC 模式直接空操作。
• restart.ts（/restart）与 reload-all/（/reload-all、/restart-all）互不依赖，可以单独安装、单独升级。/restart 靠一个几行的 /bin/sh 分离助手在自己的 pi 退出后再把窗口拉起来（pi --session <原会话文件>），助手日志在 ~/.pi/agent/restart.log；/restart-all 只重启「空闲 + 输入框为空 + Herdr 记着会话」的其他窗口，每个窗口任一步失败就跳过它，绝不往别人输入框里灌文本。
• /restart 在「让新东西生效」这件事上覆盖 /reload（换进程后扩展 / skills / prompts / themes / keybindings / context 文件全部重读，并且额外重读 models.json、环境变量，用上升级后的 pi 本体，清掉原型/闭包里的脏状态——包括那些 session_start 时快照下来、/reload 刷不掉的参数）。代价是几秒黑屏，且会丢展开的工具块 / 滚动位置这类内存态。选型：
  • 只改了扩展代码、想快速看效果 → /reload / /reload-all（亚秒级、不闪屏）
  • 改了 models.json / 环境变量、升级了 pi、或怀疑内存里有脏状态 → /restart / /restart-all
  • 拿不准 → /restart：除了慢几秒，它不会有「半新半旧」这种不确定性
  • 一个真实的能力差：/restart-all 会跳过「Herdr 还没记录会话」的窗口（刚开、没发过消息的），那种窗口只有 /reload-all 能覆盖
• 这些插件来自我的个人配置，仅供参考，按需裁剪。
• scroll-to-last-prompt.ts 只在 tuiMode: "fullscreen" 下生效。它给 UserMessageComponent 渲染后的首行打标记来精确命中「我上一条消息」，而不是扫 pi 内置的 OSC 133;A——助手那条没有工具调用的纯文本消息也会带同样的前缀，只扫标记会定位成回复开头。滚动会让 ScrollView 退出「跟随最新」，所以下一次发送消息时（alt+enter 排队的消息除外）自动恢复跟随。