pi-simple-status-footer0.2.0

pi-simple-status-footer

English | 简体中文

一个适用于 Pi coding agent 的轻量自定义页脚扩展。替换内置页脚，集中显示模型、Token、缓存、费用、上下文和 Git 改动，并支持自定义颜色与图标。

第一行显示模型、供应商、思考等级、当前目录、Git、上下文百分比与自动压缩标记。第二行显示 Last 最近一次请求及 Total 会话累计的 Token、缓存、命中率和费用。扩展状态显示在后续行。终端宽度不足时，各区域内部自动换行；单项内容过长时会截断显示。

安装与管理

从 npm 安装：

pi install npm:pi-simple-status-footer

更新到最新版本：

pi update npm:pi-simple-status-footer

移除扩展：

pi remove npm:pi-simple-status-footer

安装或更新后，重启 Pi，或者在 Pi 中执行 /reload。

从本地目录安装迁移到 npm

先移除原来的本地安装来源，再安装 npm 包，避免同时加载两份扩展。将下面的路径替换为你的实际项目目录：

pi remove /path/to/pi-simple-status-footer
pi install npm:pi-simple-status-footer

开发时也可以直接安装本地目录：

pi install /path/to/pi-simple-status-footer

换电脑时如何恢复

在新电脑上重新执行 npm 安装命令即可，无需复制源码目录。自定义配置保存在 ~/.pi/agent/simple-status-footer.json，独立于 npm 包；需要保留配色、图标等设置时，将这个文件一并迁移。

显示指标

指标	含义
模型	机器人图标后显示模型 ID，括号中显示提供方
思考等级	大脑图标后显示当前思考等级，如 medium、high
工作目录	文件夹图标后显示当前目录；设置了会话名时会一并显示
Git 状态	分支名后显示 + 暂存文件数、~ 未暂存文件数、? 未跟踪文件数
会话输入/输出 Token	整个会话累计的不含缓存读写的输入 Token 和输出 Token；输出已包含提供方计入的思考 Token
会话总 Token	整个会话累计的 Token 总量（输入 + 输出 + 缓存读取 + 缓存写入）
会话缓存读写	整个会话累计的缓存读取和写入 Token
平均缓存命中率	整个会话按 Token 加权的缓存命中率
最近一次请求	历史图标后显示最近一次助手请求的输入/输出/总 Token 和缓存读写 Token；Token 均显示完整整数，不做 k/M 缩写
单次缓存命中率	最近一次助手请求的缓存读取 Token 占该次提示词 Token 的比例
费用	累加 Pi 记录的模型费用，例如 $ 1.234，不等同于供应商账单；提供方价格缺失时无法反映实际费用，适用时附带 (sub) 订阅标记
上下文	显示 已用/总量 百分比 (auto)，用量使用 k/M 缩写；未知时显示 ?，开启自动压缩时附带 (auto)
扩展状态	显示其他扩展发布的状态文字，例如 MCP 连接状态
工具数	在 MCP 状态右侧显示当前 Pi 激活、声明给模型的工具数量
插件数	在 MCP 状态右侧显示已配置的插件包数量；一个包可能提供多个扩展模块

工具数与插件数跟随非空的 mcp 状态显示，没有这条状态时不会单独显示这两个计数。

单次缓存命中率和平均缓存命中率是两个独立指标：

单次命中率 = 单次 cacheRead / (单次 input + 单次 cacheRead + 单次 cacheWrite) × 100%
平均命中率 = 总 cacheRead / (总 input + 总 cacheRead + 总 cacheWrite) × 100%

会话累计值来自会话文件中记录的 usage：助手消息、工具结果摘要、压缩/分支摘要以及缓存预热等 usage 条目，包含同一文件中已回退的分支。总 Token 按输入、输出、缓存读取、缓存写入四项相加，不再叠加思考 Token。插件无法补出上游未记录的用量。

会话文件是追加式的，上下文压缩只会追加摘要条目，不会删除历史记录，因此累计 Token 不会因压缩而变小。上下文百分比由 Pi 提供，包含估算；压缩后可能先显示 ?，待后续响应后恢复计算。最近一次请求指最后写入会话文件的助手消息，不包含正在流式生成的响应，也不等于一轮多次工具调用的合计。

单次命中率在会话已有缓存活动且本次完全未命中时显示 0.0%；没有任何缓存记录或提示词数量为零时省略。窄屏会将最近一次请求按指标拆分换行，各段重复历史图标以区分累计值。Git 计数是文件数，不是改动行数；同一文件可以同时计入暂存和未暂存。缓存、费用和 Git 等指标会根据当前可用数据按需显示。

自定义主题

配置文件位置

用户配置文件默认位于：

~/.pi/agent/simple-status-footer.json

如果设置了 PI_CODING_AGENT_DIR，扩展会从该目录读取 simple-status-footer.json。

默认配色位于包内的 footer-theme.default.json。用户配置中填写的字段会覆盖对应默认值，没有填写的字段继续使用默认值。建议修改用户配置文件，避免升级扩展时丢失自己的设置。

最小配色示例

新建配置文件，或在已有配置中修改对应字段：

{
  "model": "#ff79c6",
  "provider": "#8be9fd",
  "tokens": "#f1fa8c",
  "cachePercent": "#50fa7b"
}

这个示例将模型名设为粉色、提供方设为青色、输入/输出 Token 设为黄色、缓存命中率设为绿色，其他项沿用默认配色。修改后，在 Pi 中执行 /reload 生效。

需要完整配置时，可参考 footer-theme.example.json。示例还包含可选的 background 背景色；不需要背景时，省略该字段即可。

颜色字段对应关系

每个指标的颜色同时作用于它的图标和文字。

字段	修改的指标或内容
model	模型 ID；未选择模型时显示的 no-model
provider	括号内的提供方名称
thinking	当前思考等级
path	工作目录和会话名称
git	工作区干净时的 Git 分支和改动计数
gitDirty	存在文件改动时的 Git 分支和改动计数
tokens	最近一次请求的历史图标
tokenInput / tokenOutput / tokenTotal	分别设置输入、输出、总 Token 的颜色，与旧 tokens 配色独立
cacheRead / cacheWrite	分别设置缓存读取、写入的颜色，与旧 cache 配色独立
lastLabel / totalLabel	分别设置 Last、Total 标签高亮颜色
cache	保留的旧主题字段；缓存指标请使用独立颜色字段
cachePercent	平均缓存命中率和单次缓存命中率
cost	费用及订阅标记
context	上下文使用率不超过 70%，或者使用量未知时的显示
contextWarn	上下文使用率大于 70%、不超过 90% 时的显示
contextError	上下文使用率大于 90% 时的显示
sessionTime	MCP 状态旁的工具数和插件数
separator	指标之间的分隔符 │
background	页脚和扩展状态行的可选背景色

前景色支持三种格式：

格式	示例	说明
Pi 主题颜色名	"accent"、"success"、"warning"、"error"、"muted"	跟随 Pi 当前主题
十六进制颜色	"#8be9fd"、"#0af"	支持三位或六位 RGB 颜色
ANSI 颜色索引	81、141	使用 0–255 的整数，不加引号

background 同样支持十六进制颜色和 ANSI 索引。使用 Pi 背景颜色名时，可选 selectedBg、searchMatchBg、userMessageBg、customMessageBg、toolPendingBg、toolSuccessBg、toolErrorBg。

缩进和刷新间隔

字段	作用	范围及默认值
paddingLeft	页脚和扩展状态行的左侧缩进	0–8 个字符单元，默认 2
refreshMs	Git 状态轮询间隔	1000–60000 毫秒，默认 5000

refreshMs 控制 Git 状态轮询间隔。

{
  "paddingLeft": 1,
  "refreshMs": 10000
}

图标设置

默认使用 Nerd Font 图标。终端字体不包含这些字形时，可以使用简化图标模式：

{
  "icons": "ascii"
}

恢复默认 Nerd Font 图标：

{
  "icons": "nerd"
}

也可以使用对象只覆盖个别图标。mode 决定基础图标集，没有指定 mode 时默认使用 nerd；某个图标设置为 "" 时，仅隐藏图标，保留指标数值。

{
  "icons": {
    "mode": "nerd",
    "cacheHit": "✓",
    "gitBranch": ""
  }
}

图标字段对应关系

icons 内的字段	对应指标	默认 Nerd Font 图标
model	模型	nf-md-robot_outline
thinking	思考等级	nf-md-brain
path	工作目录	nf-md-folder_outline
context	上下文	nf-md-chart_donut
tokenInput	输入 Token	nf-md-arrow_up_bold
tokenOutput	输出 Token	nf-md-arrow_down_bold
tokenTotal	总 Token	nf-md-sigma
cacheRead	缓存读取	nf-md-database_arrow_down
cacheWrite	缓存写入	nf-md-database_arrow_up
cacheHit	缓存命中率	nf-md-database_check
lastRequest	最近一次请求	nf-md-history
toolCount	工具数量	nf-md-tools
pluginCount	插件包数量	nf-md-package_variant_closed
gitBranch	Git 分支	nf-fa-code_branch

完整默认字形及其 JSON 写法可参考 footer-theme.example.json。

配置生效与恢复默认

修改用户配置文件后，在 Pi 中执行：

/reload

需要创建一份默认配置或恢复默认时，执行：

/status-theme-reset
/reload

/status-theme-reset 会用默认配置覆盖当前用户配置文件。只想恢复某一项时，删除配置中的对应字段，再执行 /reload 即可。

开发

开发依赖固定使用 Pi 1.4.0。运行测试需要支持 --experimental-strip-types 参数的 Node.js 版本。

git clone https://github.com/lonnnnnng/pi-simple-status-footer.git
cd pi-simple-status-footer
npm ci
npm run typecheck
npm test
npm pack --dry-run

许可证

使用 MIT 许可证，详见 LICENSE。