pi-hud-classic-footer

English | 简体中文

基于 Hiyori97/pi-hud-footer (MIT License)

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

它把模型、上下文、词元、缓存、费用、工具调用和运行状态集中显示在 TUI 底部。每行显示哪些内容、按什么顺序排列，都可以用 classicLayout 自定义；光标支持 bar / block 两种样式，默认是稳恒不闪烁的竖条光标。

功能亮点

• 显示当前模型、思考等级、项目名和 git 分支
• 显示上下文使用进度、可选会话树/当前分支的累计词元用量、输出速率、缓存读写和缓存命中率
• 支持累计或最近一次请求的缓存命中率
• 显示 running / ready 状态、会话耗时、费用估算和每轮用时（ready 状态附带本轮用时）
• 费用支持 USD / CNY 显示，美元兑人民币汇率默认 6.8 且可自定义
• 显示工具调用统计，并保持 footer 高度稳定
• 支持 classicLayout 自定义 footer 布局：逐行自由排列显示项（见下文「布局」）
• 可显示上一条用户提问（lastQuestion），并用 Ctrl+Shift+I 快捷键快速查看
• 支持中文/英文界面，默认根据系统语言自动选择
• 支持全局和项目级 JSONC/JSON 配置（支持注释）
• 支持 bar / block 光标样式，通过 DECSCUSR 提供稳恒竖条光标体验

截图

安装

推荐从 npm 安装：

pi install npm:pi-hud-classic-footer

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

pi install git:github.com/0717wuwang/pi-hud-classic-footer

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

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

命令与快捷键

命令	说明
/hud-footer	切换当前会话的 HUD footer 开/关。
/hud-footer-reload	重新读取配置并刷新 HUD footer。

快捷键	说明
Ctrl+Shift+I	弹出上一条用户提问（仅当存在上一条提问时生效）。

配置

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

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

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

配置项

配置项	说明
enabled	是否启用 HUD footer。
language	界面语言：auto / zh / en。
cursorStyle	光标样式：bar（稳恒竖条）/ block（默认方块），默认 bar。仅在 TUI 模式生效。
modelDisplay	模型名显示模式：short（缩写）/ long（展示名）/ full（完整 ID），默认 short。
projectNameDepth	项目路径保留层级，范围 -1..10，默认 3；-1 显示完整路径。
classicLayout	footer 布局配置：每行一个数组，元素为显示键名。未配置时使用内置默认布局（见下文「布局」）。
cacheRateMode	缓存命中率：累计值 total / 最近一次请求 latest，默认 total。
currency	费用显示货币：USD / CNY，默认 USD。
exchangeRate	美元兑人民币汇率，默认 6.8（即 1 USD = 6.8 CNY）。
barWidth	上下文进度条宽度，范围 6..40，默认 18。
maxTools	工具统计最多显示数量，范围 1..20，默认 7。
usageScope	累计词元和费用范围：当前分支 branch / 完整会话树 session，默认 branch。

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

/hud-footer-reload

或：

/reload

布局（classicLayout）

classicLayout 控制 footer 每一行显示的内容。每行是一个数组，元素按顺序显示、用 | 分隔；没有任何可见内容的行不渲染。未配置时使用内置默认布局：

[
	["project", "git"],
	["model", "context", "state"],
	["tokens", "tokenBreakdown", "tokenRate", "cacheRate", "elapsed", "cost"],
	["toolsLine"]
]

示例：把模型和项目放在同一行，并追加上一条提问：

{
	"classicLayout": [
		["model", "project", "git"],
		["context", "state"],
		["tokens", "tokenBreakdown", "tokenRate", "cacheRate", "elapsed", "cost"],
		["toolsLine"],
		["lastQuestion"]
	]
}

可用的显示键：

键	内容
model	模型（含思考等级与供应商）。
project	项目路径（层级由 projectNameDepth 控制）。
git	git 分支。
context	上下文进度：进度条 + 百分比 + 词元占用。
tokens	词元总数。
tokenBreakdown	输入 / 输出 / 缓存读写的细分。
tokenRate	主 agent 当前流式输出速率。
cacheRate	缓存命中率。
elapsed	会话耗时。
cost	费用估算。
state	running / ready 状态（ready 时附带本轮用时）。
turnDuration	本身不占列；出现在任意行中即启用「每轮用时」展示：运行中在工作消息显示本轮用时，结束时通知「本轮用时 X」。
toolsLine	工具调用统计行。
lastQuestion	上一条用户提问（按宽度截断）。

无效的键会被跳过（console.warn 警告，不报错）。

指标说明

词元指标使用以下图标：

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

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

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

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

cacheRateMode 可选择当前分支最近一次 assistant 请求（latest）或当前分支累计值（total）。缓存命中率计算方式：

cacheRead / (input + cacheRead + cacheWrite)

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

光标样式

cursorStyle 通过 DECSCUSR 设置终端硬件光标，仅在 TUI 模式生效，会话结束时恢复默认：

值	说明
bar	稳恒竖条（默认），不闪烁。
block	恢复终端默认方块光标。

开发 / 临时运行

不安装，临时加载：

pi -e ./pi-hud-classic-footer

在仓库目录内：

pi -e .

修改后在 pi 中执行：

/reload

发布给其他人

详见：docs/PUBLISH.md / English

安全说明

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

许可证

MIT