pi-hud-footer

English | 简体中文

一个给 pi coding agent 使用的 Claude HUD 风格自定义 footer/statusline 插件。

它把模型、上下文、词元、缓存、费用、工具调用和运行状态集中显示在 TUI 底部。默认使用 classic 经典 footer 样式；也可以切换到 border 输入框边框样式，把稳定信息嵌入输入框边框，只把会动态增长的工具统计保留在 footer 中。

功能亮点

• 显示当前模型、思考等级、项目名和 git 分支
• 显示上下文使用进度、可选会话树/当前分支的累计词元用量、输出速率、缓存读写和缓存命中率
• 支持累计或最近一次请求的缓存命中率
• 显示 running / ready 状态、会话耗时和费用估算；每轮用时通知可选开启
• 费用支持 USD / CNY 显示，美元兑人民币汇率默认 6.8 且可自定义
• 显示工具调用统计，并保持 footer 高度稳定
• 显示其他扩展通过 ctx.ui.setStatus 设置的状态文本
• 支持两套 HUD 样式：classic 经典 footer 样式和 border 输入框边框样式
• 支持中文/英文界面，默认根据系统语言自动选择
• 支持全局和项目级 JSON 配置

主题 / 样式

样式	别名	适合场景	说明
classic	1	默认主题	将 HUD 信息集中显示在输入框下方，保留经典三行 footer 体验。
border	2	边框布局	将模型、耗时、费用、上下文、词元和状态嵌入输入框上下边框；工具统计保留在 footer 行，布局更稳定。

在 TUI 中切换并保存样式：

/hud-footer-theme

命令会写入配置文件：如果当前受信任项目已存在 .pi/hud-footer.json，则保存到项目配置；否则保存到全局配置 ~/.pi/agent/hud-footer.json。也可以手动设置：

{
  "style": "classic"
}

classic / 1：经典 footer 样式

border / 2：输入框边框样式

安装

推荐从 npm 安装：

pi install npm:pi-hud-footer

也可以从 GitHub 安装，不需要指定版本号：

pi install git:github.com/liao666brant/pi-hud-footer

本地开发或调试时，可以从本地路径安装：

pi install /path/to/pi-hud-footer

命令

命令	说明
/hud-footer	切换当前会话的 HUD footer 开/关。
/hud-footer-reload	重新读取配置并刷新 HUD footer。
/hud-footer-theme	打开 TUI 选择器，切换并保存 HUD 样式。
/hud-footer-language	打开 TUI 选择器，切换并保存界面语言。
/hud-footer-currency	打开 TUI 选择器，切换并保存费用显示货币（汇率仍在配置文件中设置）。

配置

完整配置说明见：docs/CONFIG.md / English

示例配置：examples/hud-footer.json / 带注释版：examples/hud-footer.jsonc

配置层级	路径	说明
全局配置	~/.pi/agent/hud-footer.json	对所有会话生效。
项目配置	.pi/hud-footer.json	仅在项目受信任时读取，并覆盖全局配置。

配置项

配置项	说明
enabled	是否启用 HUD footer。
language	界面语言：auto / zh / en。
style	HUD 样式：classic / border。
display	控件显示规则，支持全局和按样式覆盖。
cacheRateMode	缓存命中率：累计值 total / 最近一次请求 latest，默认 total。
currency	费用显示货币：USD / CNY，默认 USD；也可用 /hud-footer-currency 切换。
exchangeRate	美元兑人民币汇率，默认 6.8（即 1 USD = 6.8 CNY）。
barWidth	上下文进度条宽度。
maxTools	工具统计最多显示数量。
usageScope	累计词元和费用范围：当前分支 branch / 完整会话树 session，默认 branch。

display 支持 all、classic、border 分组，可配置：toolsLine、modelName、thinkingLevel、projectName、gitBranch、context、tokens、tokenBreakdown、tokenRate、cacheRate、elapsed、cost、state、turnDuration。

turnDuration 默认关闭，避免与其他插件提供的每轮耗时通知重复；需要时将其设置为 true。

修改配置后，在 pi 中执行：

/hud-footer-reload

或：

/reload

指标说明

词元指标使用以下图标：

图标	含义
↑	输入词元
↓	输出词元
R	缓存读取词元
W	缓存写入词元
⚡	缓存命中率

R / W 在对应数值为 0 时会分别隐藏。

usageScope 决定 ↑/↓/R/W 与费用是累计完整会话树还是当前分支；session 会计入 assistant、带 usage 的 toolResult、usage 记录（如缓存预热）、compaction 和 branch summary。上下文进度和工具统计仍分别使用当前有效上下文与当前分支。

tokenRate 显示主 agent 当前流式输出速率，按最近 0.5～2 秒输出词元增量计算。

cacheRateMode 可选择最近一次 assistant 请求（latest）或累计值（total）；latest 取当前统计范围内最后一条 assistant 请求，total 取当前统计范围的累计值。缓存命中率计算方式：

cacheRead / (input + cacheRead + cacheWrite)

即：缓存命中的输入词元 / 输入侧总词元。

开发 / 临时运行

不安装，临时加载：

pi -e ./pi-hud-footer

在仓库目录内：

pi -e .

修改后在 pi 中执行：

/reload

发布给其他人

详见：docs/PUBLISH.md / English

安全说明

pi 扩展会以你的系统权限运行。本扩展只读取 pi 扩展 API 暴露的会话元数据，以及 pi footer API 暴露的 git 分支信息；不访问网络。

许可证

MIT