@muzi3/pi-ui

Pi 扩展：把页脚换成双行上下文仪表盘，在编辑器边框上常驻显示模型名与耗时，并给折叠的 thinking 标签加 spinner 动画，主题跟着当前主题走。

替代 pi-catppuccin-tui 的自实现版本，修掉了原实现的两处问题：指示器颜色和多处 token 写死了 Macchiato 的十六进制色（换主题后错色），以及自定义 footer 整体替换内置 footer 后、其他扩展的 setStatus 状态 （如 @muzi3/comate-quota 的额度）变得不可见。

能力

footer 布局

Comate  ████░░░░░░░░░░  25% / ¥50.00  ~/muzi/pi-packages/packages/pi-ui    main
Context ██░░░░░░░░░░░░  1.7% / 272k  ↑74.7k ↓3.8k $0.009

色：标签 muted｜进度条 按占用率 绿/黄/红｜占比 跟条同色｜/ 窗口、/ ¥ 与未知占位 dim｜ ↑ mdLink 蓝、↓ syntaxNumber 桃、$ syntaxOperator 青｜工作目录 dim｜分支 accent（图标与分支名同色）

• 第 1 行：其他扩展通过 setStatus 设置的文本（如 @muzi3/comate-quota 的额度条）+ 工作目录 + git 分支。 工作目录取 ctx.cwd，$HOME 前缀缩成 ~（不在 HOME 下就保留绝对路径）；宽度不够时从中间 丢段、保住末段（~/muzi/…/packages/pi-ui，项目名在末尾，左截断会先砍掉最该看的字）， 连末段都放不下就整段丢掉，不显示成只有省略号的 ~/…。 分支前是 Nerd Font 的 git 图标 U+E0A0（nf-pl-branch，与 starship 默认提示符同一字形， 分支前是 Nerd Font 的 git 图标 U+E0A0（nf-pl-branch，与 starship 默认提示符同一字形， accent 色），需要 Nerd Font 字体，否则显示为豆腐块；分支名同色 accent（图标与名字 合成一整块，在行尾立成一个锚点）
• 第 2 行：上下文进度条（14 格）+ 百分比 / 窗口 + 累计用量（↑in ↓out $cost）。 进度条配色按占用率分级：<70% 绿（success）、70~90% 黄（warning）、>90% 红（error）； 刚压缩完占用未知时显示为暗色 ?
• 分色规则：语义色（绿/黄/红）只用于占用率档位，其余按“角色”取色，避免整行一片灰或一片绿。 标签 muted；占比跟进度条同色，/ 窗口 降为 dim；用量三块各一色（见上）。 mdLink/syntaxNumber/syntaxOperator 是按“颜色”选的 token：pi 的 ThemeColor 是闭合的 56 个语义 token，没有给 footer 留名字。Mocha 的 teal 因此取不到——26 色里只有它和 rosewater/flamingo/pink/base/crust 没有任何 token 指向，改主题里这些 token 的映射等于改这里的观感
• 第 1、2 行的标签列固定 8 列（Comate / Context ，含标签后的分隔空格），两条进度条因此左对齐。 Context 由本包补齐；扩展状态行是别的包产出的文本，要自己把标签补齐到 8 列、标签色用 muted （参考 @muzi3/comate-quota）——这是跨包视觉契约
• 行尾的工作目录、分支与累计用量是次要信息，放不下就整段丢弃（不截断）： 第 1 行先缩路径、再丢分支、最后才丢路径；进度条与百分比不参与降级
• footer 高度不超过 2 行：没装扩展就没有额度条，不在 git 仓库就没有分支， 取不到 cwd 就没有工作目录
• 内核 footer 右侧的“模型名 • 思考等级”两项都不要：模型名在编辑器边框上常驻，思考等级由边框 颜色区分（每个等级一个 thinking* token，主题里已拉开层次）
• 累计用量口径与内置 footer 一致：assistant、带 usage 的 toolResult、branch_summary/compaction 求和

编辑器边框标题

╭─ claude-sonnet-4-5 ⏱ 12s ───────────────────────────────╮  空闲
╭─ ⠼ claude-sonnet-4-5 ⏱ 12s ─────────────────────────────╮  流式（模型名上有高光带扫过）
│ ❯                                                        │
╰──────────────────────────────────────────────────────────╯

• 用自定义编辑器（PiUiBorderEditor extends CustomEditor）接管编辑器上边框。pi 自带的 WorkingStatusIndicator 只在流式期间挂在边框上（turn_start 挂、turn_end 清），空闲即消失， 承载不了“常驻”；所以子类覆写 setWorkingStatusIndicator，忽略 pi 的挂/清，恒挂自己的标题。 边框拼接、截断、↑ N more 滚动提示全部沿用 CustomEditor.renderTopBorder，没有重写排版
• 输入被滚动时不用取舍：↑ N more 会与标题并列出现在同一行边框上 （── ⠼ model ⏱ 12s ──── ↑ 5 more ────），这是继承来的行为，不是额外实现
• 指示器：流式为 ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ @80ms，帧序列与间隔都对齐 pi 自带 Loader（@earendil-works/pi-tui 的 DEFAULT_FRAMES / DEFAULT_INTERVAL_MS），颜色跟内置 working 指示器一样用 accent 单色。 用盲文而不是 ▘▝▗▖/◰◳◲◱ 这类整格块：后者在等宽字体下几乎占满整格，在边框上比正文还抢眼； 盲文墨水轻、不挑字体。10 帧在 visibleWidth 下都是 1 列，边框标题不抖。 早先试过 4 帧矩形（⠁⠈⠠⠄ 绕四角 + dim→muted→accent→borderAccent 明暗递进）：帧数翻到 10 帧后 逐帧换色会变成“亮度在扫”，反而不像 spinner，所以回到单色。 不转的时候完全不显示——空闲、或关掉 indicator 时都不留静止帧（静止的帧反而 更难看出在不在生成）；代价只是模型名左右移 1 列，在以 ─ 为主的边框上几乎看不出来
• 配色：模型名空闲时直接取编辑器当前的 borderColor（this.borderColor），边框是什么色它 就是什么色。pi 会按 thinking level 换这个函数（getThinkingBorderColor：off overlay0、low blue、 medium sapphire、high mauve……），bash 模式另有 getBashModeBorderColor，所以写死任何 token 都会在切换后与边框脱色（例如 medium 下边框是青色而模型名还是灰的）。 流式时模型名换成扫光帧，配色改由 shimmer.ts 的三档负责（dim/muted/accent+bold）， 此时不再跟随 borderColor；⏱ 耗时 始终为 dim
• 耗时口径与旧版 footer 一致，只是位置变了：流式为已进行秒数（随 spinner 帧重绘跳秒）， 空闲为上一轮总耗时；宽度不足时先丢掉 ⏱ 耗时，再逐字截断模型名
• 退出/关闭 working 会换回内置编辑器，还原 pi 默认：仅流式期间在边框显示模型名
• 需要 pi >= 0.85（CustomEditor 的 embedWorkingStatus 与 setWorkingStatusIndicator 从该版本才有）； 本包不依赖 @earendil-works/pi-coding-agent 的本地副本，运行时由 pi 的扩展加载器别名到自身
• 圆角与 ❯：覆写 renderTopBorder / renderBottomBorder / render，四角换成 ╭╮╰╯、左右补 │； 圆角只在 visibleWidth(line) === width 时替换，宁可没圆角也不要把宿主截断过的行改坏
• ❯ 靠预留左内边距实现（用户内边距之外再加 3 列槽位），不接管宿主的文本编辑；输入被滚动时 不画 ❯（否则图标会漂到半截文字前面），极窄宽度放不下槽位时也不画。颜色取 this.borderColor， 所以跟边框、跟 thinking level 同步
• 模型名在流式时换成扫光帧（shimmer.ts：dim → muted → accent+bold 三档，高光带 3 列宽， 帧数 = 字符数 + 2），40ms 一帧；盲文仍是 80ms 一帧，两套相位独立，转速不变。空闲回落为纯边框色

模型名覆盖（跨扩展）

边框标题默认显示当前会话模型，其他扩展可以在自己占用会话期间临时把它换掉：

pi.events.emit("pi-ui:model-override", "glm-4.6"); // 覆盖
pi.events.emit("pi-ui:model-override", undefined); // 恢复会话模型

通道是软约定：没扩展发布时什么都不发生，空串与 undefined 都表示恢复， session_start/session_shutdown 会清空残留值。@muzi3/compaction-custom-model 靠它在压缩期间显示压缩所用模型。

宽度不足时的降级顺序

自定义 footer 会整体接管内置 footer，内置第三行（扩展状态）随之消失，所以扩展状态置于页脚最前。 两行各自独立降级，每行都保住它最有信息量的部分：

1. 第 1 行：完整（额度条 + 工作目录 + 分支）→ 路径中段省略 → 丢分支 → 丢工作目录 → 额度条截断加省略号
2. 第 2 行：完整（进度条 + 计数 + 累计用量）→ 丢累计用量 → 丢 Context 标签 → 丢百分比/窗口 → 只剩进度条；进度条不接受被截断

thinking spinner 动画

折叠 thinking 块的标签（hideThinkingBlock 或 Ctrl+T 收起时显示的那行）前面盲文 spinner 照转，文字上有高光带扫过：

⠋ Thinking...   ← 流式中：盲文 @80ms + 文字上 40ms 扫光（复用边框指示器的帧）
✓ Thinking...   ← 结束后回落的静态帧（accent 色对勾，同 pi 选择器标记当前项的那个）

帧表不在这里另写一份，直接复用 indicator.ts 的 buildSpinnerFrames 与 shimmer.ts 的 shimmerFrames：两处观感要一致，两份列表迟早漂移。节奏分两套——盲文沿用 SPINNER_INTERVAL_MS （80ms，与边框 spinner 同速），扫光用 SHIMMER_TICK_MS（40ms，与边框标题同速）。

• pi 只提供静态的 setHiddenThinkingLabel，动画靠定时器反复改写标签实现。每次改写都会重绘 整条 transcript，所以定时器只在 assistant 消息流式期间开表（message_start 开、 message_end 停，agent_settled 兜住用户中断）；流式期间 pi 本来就在逐 token 重绘，这点 额外开销看不出来，空闲时零成本
• 一轮里可能有多条 assistant 消息、中间夹着工具调用，动画跟消息粒度走而不是跟轮次走： 工具执行期间标签保持静态，不会被误看成还在思考
• 宿主那个 setter 是全局广播（一个标签打给所有行实例），而每行拿自己的 lastMessage 重绘， 所以不做拦截的话，前面已完成的思考块会跟着新一轮一起转回进行态。thinking-rows.ts 在标签落到 实例前拦一道：只有 lastMessage 就是当前流式那条消息（同一个对象引用）的行拿动画帧，其余行 换成静止标签。行的身份必须用对象引用——AssistantMessage 上没有 timestamp 之类的字段 （pi-ai/dist/types.d.ts 里就只有 role/content/api/provider/model/usage/stopReason 等）， 按字段比对在真实场景里恒不成立，补丁会静默退化成什么都不做。没有活动消息时补丁透传， 宿主的内部结构一旦变了也不会抛异常
• 配色：盲文沿用 accent（同边框指示器），扫光三档 dim → muted → accent+bold，空闲回落 静态 thinkingText。两段都自带完整着色：pi 把整串包进 fg("thinkingText", label)，内层 fg 的 reset 会让后面的行内文本不再跟随 thinkingText，颜色塌成终端默认色
• 帧宽一致（盲文各占 1 列），标签不会左右抖；静止帧用 ✓（U+2713）而不是 ✔️， 后者带 emoji 变体选择符、多数终端占 2 列，结束瞬间会把标签推右一格。帧是每帧现取主题色 （换主题后立刻跟上），不像边框 spinner 那样需要按主题名重建缓存
• 只在 thinking 块折叠时可见；Ctrl+T 展开思考原文时这个标签不显示，动画照旧开着（不额外 探测 pi 内部的 hideThinkingBlock，它没有对外读接口）

关闭 thinking 会调 setHiddenThinkingLabel(undefined) 还原 pi 默认的 Thinking...。

命令

/pi-ui                                        # 查看四块能力的开关状态
/pi-ui footer|indicator|working|thinking on|off  # 单独开关

关闭 footer 会恢复 pi 内置 footer；关闭 working 会换回内置编辑器（流式期间才显示模型名）；关闭 indicator 会让 spinner 不再显示；关闭 thinking 会把折叠 thinking 标签还原成 pi 默认文案。 开关只在本次会话内有效，不写盘。

主题

themes/pi-ui-catppuccin.json（主题名 pi-ui-catppuccin）在 Catppuccin Mocha 基础上只改层次关系， 色板本身不变：

色板与配色思路来自 Catppuccin（MIT）与 pi 主题 catppuccin-tui-mocha（MIT）。

安装

pi install npm:@muzi3/pi-ui

从 pi-catppuccin-tui 迁移时，先装本包、把 ~/.pi/agent/settings.json 的 theme 改成 pi-ui-catppuccin， 再卸载前者。两个包都会调用 setFooter，后加载者生效，顺序不确定；先卸载可避免页脚互相覆盖。

敏感信息

本包不含个人信息、内部工具名与任何凭证。发布前扫描见仓库根 .pi/RULES.md。