pi-signal-footer

中文 | English

为 Pi Coding Agent 提供的可读状态栏：模型、token、缓存、成本、上下文条、流式速率与 MCP/LSP 状态。

下方示例按 160 列终端排版。颜色跟随宿主主题，终端变窄时自动重排。

外观

classic（默认）

C:/Users/dev/agent-demo · fix-context-bar  │  opencode-go › ◎ deepseek-v4-flash-0731 │ ✦ max │ ⎇ main                      ⎔ 12% [━━──────────────────] 36k/300k
↓ 220 ↑ 5.4k │ ↻ 51k (96.92%) ✎ 1.4k │ $0.087 │ ◷ 2m · 1轮 · 45 tok/s                                                                               ⇄ MCP 工具 2

vivid（/footer theme）

📁 C:/Users/dev/agent-demo · fix-context-bar  │  opencode-go › 🐳 deepseek-v4-flash-0731 │ 🧠 max │ 🔀 main               📊 12% [━━──────────────────] 36k/300k
📥 220 📤 5.4k │ 🔄 51k (96.92%) 📝 1.4k │ 💰 0.087 │ ⏳ 2m · 💬 1轮 · 🚀 45 tok/s                                                                 🔌 MCP 工具 2

LSP 按需显示：没有活动或失败状态时隐藏。

需要 Pi Coding Agent >=0.84.4。更旧的宿主保留原生状态栏。

每一行在返回前按终端宽度截断。

某帧渲染抛错时回退到上一帧，并按当前宽度重新截断。

图例固定 5 行，最宽 77 列，80 列终端不折行。

安装

pi install npm:pi-signal-footer

配置

设置写在 Pi 代理目录（通常 ~/.pi/agent/）下的 pi-signal-footer.json。缺失或无效时回退以下默认值。

{
  "enabled": true,
  "locale": "auto",
  "theme": "classic",
  "showProject": true,
  "showSessionName": true,
  "showDuration": true,
  "showTurns": true,
  "showSpeed": true,
  "showBranch": true,
  "showCacheRatio": true
}

只有会改设置的命令才重写这个文件。

classic 是灰色骨架上的白色读数，成本为琥珀色（见上方第一个示例）。vivid 用 emoji 图标与柔和语法色（见上方第二个示例）。两种外观共用同一套排版：灰只留给骨架，报警色只留给上下文阈值与故障，成本除外。

命令

/signal-footer 与短别名 /footer 功能完全一致。

单项：path、session、time、turns、speed、branch、cache。

off 与 on 跨会话持久。关闭时清理 stream、速率与压缩临时状态并隐藏图例。

图例是会话级 UI，与 enabled 解耦。只有 /footer off、/footer hide 和会话结束会清掉它。

读数口径

• ≈ 是近似值。流式速率与 ↑ 的 ≈+N 后缀按可见正文、思考与工具调用参数估算。

• 固定密度：正文/思考 ≈4 字符/token、工具参数 JSON ≈2、CJK/韩文 ≈1。

• 变化的正 provider output 校准读数，此后只估新增可见内容。结束时有效正 output 变为 +N，直到同一消息落盘。

• 消息被其他扩展替换，或条目数组被 fork 缩短时，在途读数结束。

• 实时速率用同一观测跨度上的 token 差与时间差。

• 读数只在 chunk 到达时更新，渲染不改变它。连续窗口排除长停顿；停顿保持最后一次读数，恢复初期可能短暂沿用。

• 稀疏 chunk 无成熟窗口时使用请求内观测平均。结束后定格为 output ÷ 首次观测输出至结束的时间，未观测到输出时回退请求开始时间。

• token、缓存、成本与轮数累计当前会话文件的全部条目，/fork 只计复制过来的路径。

• 轮数 = 用户消息数，包含 steering 插话。

• ◷ 是估算的 agent 工作时长。启用时在 agent_start 与 session_before_compact 写一个不进入 LLM 上下文的 custom 工作起点，排除此前空闲。

• 起点标记使实时、落盘、重载保持一致。等人输入以及切模型、改思考等级、命名、标签前的空档不计；单段封顶 15 分钟。

• 旧历史没有起点标记时仍按条目 gap 推导，不能还原所有空闲边界。aborted 按条目落盘时间减消息开始时间回退，最多扣本段已计入量；error 不回退。

• 失败或取消的压缩没有落盘结果时，不保留新增完成工作。

• ↻ 是缓存读 token 累计。括号是最近一次带可用输入维度的已落盘 assistant 请求，不是当前流式请求。

• 括号内比例为 cacheRead / (input + cacheRead + cacheWrite)，保留两位小数。输入维度全零或未上报时沿用上轮已知值（可能滞后，绝不伪造 0.00%）；有输入但无缓存读的请求显示 0.00%。

• 上下文来自宿主当前分支的 getContextUsage()，可能混合已上报用量与新增消息估算。未知保持未知。

• 宿主把窗口报成 0 或 NaN 时回退到模型的 contextWindow；两者都缺失才显示 ?。

• 成本累加记录的 usage.cost.total，不代表账单核验。上下文阈值色按显示的整数：≥50% 警告，≥75% 错误。

MCP / LSP 状态

状态栏读取公开扩展状态与 MCP 工具清单，不探测私有连接状态。已识别的 LSP 失败排在最前，接着是 MCP 明确故障或部分连接，最后是按 key 稳定排列的正常/未知状态；未知文案保留原有颜色。

MCP 零连接可能是懒连接尚未激活，不代表故障。LSP 服务器名最多列 3 个，其余折成 +N，状态区不会被撑长，也不会在行尾截出半截名字。

状态区示例：MCP 有明确待处理状态时，比例与 ✗N 标记为红色；LSP 失败也为红色。

• LSP：只呈现已发布的活动或失败状态，支持完整格式（LSP Active: … / LSP Failed: …）与紧凑格式（LSP ✓ / LSP ✗）。失败优先显示；LSP Inactive 或没有发布状态时隐藏。
• 不显示 LSP 本身不能判断服务好坏。若已发布的活动或失败状态仍不可见，可加宽终端排除截断。
• MCP 健康：优先采用已发布的已连/启用状态。原生契约 MCP native C/E failed F 显示为 MCP C/E；明确需要处理的服务器（失败、断开或待认证）用红色 ✗F 标记。
• 健康连接 classic 用 text、vivid 用 success；部分连接用警告色；没有明确故障的零连接压得更暗。
• 原生健康后可附 · 工具 N（已发现的 mcp__ 工具数）。也支持紧凑比例状态；识别到 MCP 0/0 时隐藏，且不回退库存。
• 裸 N/M connected 只在其 status key 指向 MCP 时才读作比例；挂在其他 key 下的连接池仍是普通状态。
• Pi 不发布已连/启用状态，因此内置 MCP 只显示工具数。扩展发布受支持的状态时才显示比例。
• MCP 库存：没有可识别健康状态时，MCP 工具 N 显示公开 getAllTools() 中名称以 mcp__ 开头的工具。MCP 工具随服务器连接才进入该列表，会话头几秒读数会增长。
• 标签用 muted，数字取输入色：classic 是 text，vivid 是青色。库存不是连接健康计数。
• 状态栏启用时每秒检查一次公开 API 的本地内存库存。某次检查读到的状态与此前任意一次读取不同就请求重绘；组件销毁即停止。
• 不探测服务器、不联网。API 缺失或不可用时不会伪造零值。

原生健康依赖宿主发布受支持的状态。服务器配置和工具发现本身不能证明连接健康。

本包只读取状态，不修改宿主、不创建连接。插件已加载且宿主公开库存 API 兼容时，没有健康发布源也能更新库存，但不保证任意未来宿主版本兼容。

配置中的服务在工具发现前可能没有状态项。用宿主的 /mcp 命令查服务器详情，可加宽终端排除截断。

开发验证

本机微基准不是完整 Desktop 性能测量。bench:reality 不指定目录就不扫描；估算/用量比值只作描述，不代表独立 tokenizer 精度或地面真值。

许可证

MIT