状态栏与 statusline
Pi 输入框下方的 bar / 状态栏,在官方文档和 API 中叫 footer(页脚)。它承担了 Claude Code statusline 的常见用途:随时查看目录、Git 分支、用量、费用和上下文。用途相近,但配置方式不能照搬。
这页按 Pi 1.5.0 的内置页脚实现核对。只想得到截图里的效果,默认就有,不需要安装状态栏插件。想追根到文件层面,看会话文件解剖;想自己统计这些数字,看高效读取会话数据。
按截图读懂每一项

为方便手机阅读,截图中的文字也列在下面;长行可左右滑动:
~/codex/pi-book (main)↑1.9k ↓26k R4.6M W111k CH99.6% $7.298 41.1%/272k (auto)| 片段 | 含义 | 不要误读为 |
|---|---|---|
~/codex/pi-book | 会话的工作目录;~ 表示用户主目录 | 当前正在修改的单个文件 |
(main) | 当前 Git 分支;非 Git 目录可能没有 | Pi 的会话分支名 |
↑1.9k | 会话累计的 input token,约 1,900;缓存读取和写入另列 | 当前上下文总长度 |
↓26k | 会话累计的 output token,约 26,000 | 终端显示的字符数 |
R4.6M | 会话累计的缓存读取 token,约 460 万;R = cache read | 文件读取次数,或一次装入了 460 万上下文 |
W111k | 会话累计的缓存写入 token,约 111,000;W = cache write | 写文件次数或磁盘写入量 |
CH99.6% | 最近一条助手响应的提示缓存命中率 | 整个会话的平均命中率 |
$7.298 | 会话累计费用,美元,显示到小数点后 3 位 | 当前请求价格、订阅余额或最终账单 |
41.1%/272k | 当前上下文占用约 41.1%,用于计算的模型窗口约 272,000 token | 已经完成了 41.1% 的任务 |
(auto) | 自动压缩已开启 | 自动选模型、自动思考档位或 max 模式 |
记法:R = cache Read(读缓存),W = cache Write(写缓存),CH = Cache Hit(缓存命中率)。这些字母都和文件读写次数无关。
k 表示千,M 表示百万。显示值分档取整:小于 1k 原样显示,1k–10k 保留一位小数,10k–1M 取整为 k,1M–10M 保留一位小数 M,10M 以上取整为 M。输入、输出、缓存和费用累计自会话记录,包含已记录的工具用量、压缩、分支摘要及缓存预热用量,不是只统计当前压缩后的上下文。R 很大而上下文占用较小是正常的:多轮请求可能反复读取同一份提示缓存。
缓存命中率的计算使用最近一条助手消息的用量:
CH = cacheRead / (input + cacheRead + cacheWrite) × 100%不能用旁边累计的 ↑1.9k、R4.6M、W111k 反算出 CH99.6%。供应商是否报告缓存用量也会影响显示;没有用量的项目可能不显示。
费用可能由模型价格估算,也可能使用供应商报告的总价,不能替代服务商账单。订阅认证还可能显示 (sub),它不代表额外扣费或剩余额度。
W 不是免费的:它按模型的 cache write 单价计费。以本机 gpt-6-astra 为例,cache write 是 $12.5/M,比普通输入 $10/M 还贵 25%,一次写入 20 万 token 就接近 2.5 美元。看到 W 很大时,成本和命中率要一起看。这些累计值的来源见会话文件解剖。
GPT 与 DeepSeek 的价格差异
下面保留 Pi 1.5.0 内置模型目录的价格快照,单位均为 美元 / 百万 token,不是把截图里的累计费用拆成两个模型的账单:
| 模型 | 普通输入 ↑ | 输出 ↓ | 缓存读取 R | 缓存写入 W |
|---|---|---|---|---|
openai/gpt-6-astra | $10 | $50 | $1 | $12.5 |
deepseek/deepseek-v4-pro | $1.32 | $3.96 | $0.044 | $0(目录未单列) |
同样 100 万 token,GPT 的普通输入约为 DeepSeek 的 7.58 倍、输出约 12.63 倍、缓存读取约 22.73 倍。所以即使 CH 很高,换模型后的美元消耗仍可能差很多;单价倍率也不等于整场会话的费用倍率。
来源是已安装的 @earendil-works/[email protected] 中 dist/providers/data/openai.json 与 deepseek.json 的 cost 字段,校对日期为 2026-11-06;对应上游 Pi 1.5.0 的 AI 包。这是基础价格:GPT 目录还为输入超过 272,000 token 的请求列了更高档位。DeepSeek 的 cacheWrite: 0 只表示该目录没有单列缓存写入费用,不能据此断言未命中的输入免费。供应商、网关、自定义模型设置及后续目录更新都可能改变计价,实际对账仍看服务商。
右侧的模型名、思考档位和上方横线
终端足够宽时,第二行右侧还会显示模型 ID、思考级别(例如 • max),有空间且存在多个供应商时也会显示 provider。虚拟模型还可能显示最近一次路由到的物理模型。窄终端会省略或截断右侧,这张截图不能证明当前模型或思考级别。
截图上方的彩色横线属于编辑器边框,不是用量进度条;其颜色受思考级别和主题影响。用 /thinking 确认当前档位,设置方法见让新会话默认使用 max。不要仅凭边框颜色判断 max。
上下文占用什么时候需要处理
- 超过 70% 使用主题的
warning色,超过 90% 使用error色;不一定在所有主题里都是黄色、红色。 - 颜色阈值不是自动压缩的触发阈值。自动压缩还取决于预留 token 等设置。
- 压缩后可能暂时显示
?/272k,等下一次模型响应提供用量后更新,不要当成 0%。 - 需要手动整理上下文时用
/compact;换了任务则考虑/new。具体取舍见何时压缩上下文。
从 Claude Code statusline 迁移
| 需求 | Claude Code | Pi |
|---|---|---|
| 查看目录、模型、用量 | 配置 statusline,可选择需要的字段 | 内置 footer 默认显示 |
| 自定义入口 | /statusline,或 settings.json 的 statusLine.command | TypeScript Extension 的 ctx.ui API |
| 数据如何交给自定义代码 | 命令从 stdin 收到 JSON,将显示文本写到 stdout | 扩展读取 ctx、会话和 footer 数据,交给 TUI 渲染 |
| 只加一小段状态 | 让脚本多输出一段 | ctx.ui.setStatus(key, text),保留默认页脚 |
| 自己安排整个底部布局 | 修改脚本输出 | ctx.ui.setFooter(factory),替换整个默认页脚 |
Pi 没有与 Claude Code 同义的内置 /statusline 命令,也不要把 statusLine.command 直接写入 Pi 设置。若第三方扩展注册了同名命令,那是扩展自己的能力。
配置一:保留默认页脚,只改外观和基本信息
这是最省维护的方案。
| 想调整什么 | 操作 |
|---|---|
| 换配色 | /settings → Theme,选择 system、light、dark 或自己的主题 |
| 跟随终端配色 | 选择默认的 system;修改终端主题会影响 Pi 的颜色 |
| 在目录后显示会话名 | /name 为会话命名 |
| 看完整用量与会话信息 | /session |
| 确认或修改思考档位 | /thinking;保存默认值时在选择器里按 Ctrl+S |
| 自动压缩标记 | 由 compaction.enabled 控制;建议保留开启 |
如果通过文件配置,将需要的字段合并到 ~/.pi/agent/settings.json,不要整份覆盖原文件:
{ "$schema": "https://pi.dev/schemas/settings.schema.json", "theme": "system", "compaction": { "enabled": true }}用户级路径以默认 agent 目录为例;改变 PI_CODING_AGENT_DIR 时使用相应目录。已信任项目的 .pi/settings.json 可以覆盖同名设置。手动修改后,在下一次启动检查效果;当前会话直接通过 /settings 操作更直观。
想进一步调色,从官方完整主题复制一份到 ~/.pi/agent/themes/my-theme.json,将 name 改为 my-theme,再在 /settings 中选择:
dim:默认页脚目录、普通统计和模型文本使用的颜色。warning、error:高上下文占用的提示色。thinkingOff到thinkingMax:编辑器边框的思考档位色,不是页脚的字段配置。
主题需要完整的必填颜色,只有以上几个字段的 JSON 不是完整主题。文件名与 name 保持一致;当前用户主题可热更新,其他来源的主题修改后用 /reload。详见 Pi Themes。
配置二:增加状态,不丢失内置统计
想显示“就绪 / 工作中 / 已停止”,优先用 setStatus(),不要重写 token 与费用统计。
创建 ~/.pi/agent/extensions/book-status.ts,保存以下代码,然后在 Pi 空闲时执行 /reload:
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
export default function (pi: ExtensionAPI) { pi.on("session_start", (_event, ctx) => { if (!ctx.hasUI) return; ctx.ui.setStatus("book-status", "● 就绪"); });
pi.on("agent_start", (_event, ctx) => { if (!ctx.hasUI) return; ctx.ui.setStatus("book-status", "● 工作中"); });
pi.on("agent_settled", (event, ctx) => { if (!ctx.hasUI) return; ctx.ui.setStatus("book-status", event.aborted ? "○ 已停止" : "✓ 本轮结束"); });
pi.on("session_shutdown", (_event, ctx) => { if (!ctx.hasUI) return; ctx.ui.setStatus("book-status", undefined); });}这里使用 agent_settled 而不是 agent_end:后者之后可能还有自动重试、自动压缩或排队消息。“本轮结束”只表示运行结束,不保证任务或测试成功。
默认页脚会在下方增加一行扩展状态;相同 key 会更新原状态,不会不断新增行。撤销时删除这个扩展文件并 /reload。项目专用扩展也可放在 .pi/extensions/,但只有项目信任后才加载。
扩展在 Pi 进程内以当前用户权限运行,只加载可信代码。这个示例只更新 UI,不调用模型、不执行 shell,也不改变工具权限。
配置三:完整替换页脚
只有确实要换字段与布局时才用 setFooter()。下面的简化示例显示目录、分支、模型、思考档位与上下文,刻意不显示累计 token、费用和其他扩展状态;需要这些信息时保留默认 footer 更稳妥。
保存为 ~/.pi/agent/extensions/book-footer.ts,/reload 后输入 /book-footer 切换自定义页脚,再输入一次恢复。/book-footer 是此示例注册的命令,不是 Pi 内置命令。
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";import { truncateToWidth } from "@earendil-works/pi-tui";
export default function (pi: ExtensionAPI) { let enabled = false;
pi.registerCommand("book-footer", { description: "切换简化页脚", handler: async (_args, ctx) => { if (ctx.mode !== "tui") { ctx.ui.notify("自定义页脚需要交互式终端模式", "warning"); return; } if (enabled) { ctx.ui.setFooter(undefined); enabled = false; return; }
ctx.ui.setFooter((tui, theme, footerData) => { const unsubscribe = footerData.onBranchChange(() => tui.requestRender()); return { dispose: unsubscribe, invalidate() {}, render(width: number): string[] { const branch = footerData.getGitBranch(); const location = `${ctx.cwd}${branch ? ` (${branch})` : ""}`; const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "未选择模型"; const percent = ctx.getContextUsage()?.percent; const context = percent == null ? "待更新" : `${percent.toFixed(1)}%`; const details = `${model} · ${ctx.thinkingLevel} · 上下文 ${context}`; return [ truncateToWidth(theme.fg("dim", location), width), truncateToWidth(theme.fg("accent", details), width), ]; }, }; }); enabled = true; }, });}几个边界不要省略:
setFooter(undefined)恢复默认页脚;替换或移除组件时,Pi 调用其dispose(),这里用来取消 Git 分支监听。- 用
truncateToWidth()按终端列宽截断,不能用字符串.length处理中文、emoji 和 ANSI 颜色。 - 未知上下文显示“待更新”,而不是伪造
0%。 - 这是 TUI 组件;RPC 的
ctx.hasUI也可能为true,所以完整页脚使用ctx.mode === "tui"判断。 - 不要在
render()中执行 Git 命令、网络请求或文件扫描。它会频繁调用,慢操作会拖累输入和滚动。 - 多个扩展同时替换页脚会互相覆盖。出现统计消失时,先检查是否有扩展调用
setFooter()。
更多做法见第一个 Extension和上游的 custom-footer.ts。上游示例只聚合当前分支的助手消息用量,不等于内置 footer 的完整会话统计,不能直接拿来对账。
配置后怎样验证
- 启动 Pi,确认目录与 Git 分支符合当前项目。
- 输入
/thinking,确认实际生效档位;需要默认max时按默认 max 教程操作。 - 发送一个小任务,观察统计更新和扩展状态变化;用
/session查看详细统计。 - 缩窄终端,确认页脚不会换行撑坏布局;模型名被截断时用
/model、/thinking查看。 - 执行
/reload,确认没有重复状态或监听;自定义页脚再次切换后能恢复默认布局。
核对来源
- Pi 1.5.0 默认 footer 实现:字段、累计范围、CH 公式、阈值和截断。
- Pi Settings、Themes:设置项与主题。
- Pi Extensions、Terminal UI:状态、完整页脚及组件生命周期。
- Claude Code statusline:
statusLine.command与 stdin/stdout 数据流。