跳转到内容

状态栏与 statusline

Pi 输入框下方的 bar / 状态栏,在官方文档和 API 中叫 footer(页脚)。它承担了 Claude Code statusline 的常见用途:随时查看目录、Git 分支、用量、费用和上下文。用途相近,但配置方式不能照搬。

这页按 Pi 1.5.0 的内置页脚实现核对。只想得到截图里的效果,默认就有,不需要安装状态栏插件。想追根到文件层面,看会话文件解剖;想自己统计这些数字,看高效读取会话数据。

按截图读懂每一项

Pi 默认页脚:目录 ~/codex/pi-book、分支 main,以及 ↑1.9k ↓26k R4.6M W111k CH99.6% $7.298 41.1%/272k (auto)

为方便手机阅读,截图中的文字也列在下面;长行可左右滑动:

~/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(缓存命中率)。这些字母都和文件读写次数无关。

页脚分为三个口径:↑1.9k、↓26k、R4.6M、W111k 和 $7.298 累计整个会话;CH99.6% 只看最近助手响应;41.1%/272k 只表示当前窗口占用,auto 表示自动压缩。
在原始记录之外,按会话累计、最近响应和当前窗口分组理解。打开 SVG ↗

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(目录未单列)
Pi 1.5.0 内置目录价格,美元每百万 token:GPT-6 Astra 输入 10、输出 50、缓存读 1、缓存写 12.5;DeepSeek V4 Pro 分别为 1.32、3.96、0.044、0。前三项倍率约为 7.58、12.63、22.73;缓存写目录零值不代表新输入免费。
原始单价表保留在上方;条形图仅辅助比较,每组独立缩放。打开 SVG ↗

同样 100 万 token,GPT 的普通输入约为 DeepSeek 的 7.58 倍、输出约 12.63 倍、缓存读取约 22.73 倍。所以即使 CH 很高,换模型后的美元消耗仍可能差很多;单价倍率也不等于整场会话的费用倍率。

来源是已安装的 @earendil-works/pi-ai@1.5.0 中 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 CodePi
查看目录、模型、用量配置 statusline,可选择需要的字段内置 footer 默认显示
自定义入口/statusline,或 settings.json 的 statusLine.commandTypeScript 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:

book-status.ts
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 内置命令。

book-footer.ts
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 的完整会话统计,不能直接拿来对账。

配置后怎样验证

  1. 启动 Pi,确认目录与 Git 分支符合当前项目。
  2. 输入 /thinking,确认实际生效档位;需要默认 max 时按默认 max 教程操作。
  3. 发送一个小任务,观察统计更新和扩展状态变化;用 /session 查看详细统计。
  4. 缩窄终端,确认页脚不会换行撑坏布局;模型名被截断时用 /model、/thinking 查看。
  5. 执行 /reload,确认没有重复状态或监听;自定义页脚再次切换后能恢复默认布局。

核对来源