Kimi Code CLI 的自定义底部状态栏（HUD）——零依赖 Node.js 脚本，在终端 TUI 底部显示模型与思考强度、Git 分支、生成速度（TPS / TTFT）、压缩计时、缓存命中率、Kimi 托管订阅额度，以及受支持第三方 provider 的余额或会话成本估算。渲染受宿主的 300ms 截止时间约束，HUD 自身再以 220ms 的内部每帧预算自律（边界见工作原理）；所有错误静默降级，即使单帧超时也由宿主兜底回退，不会卡住 TUI。
要求 Node.js ≥ 18（用到全局 fetch），无 npm 依赖；运行时、操作系统与宿主的支持范围见下方支持环境。
在 Kimi Code TUI 中运行：
/plugins install https://github.com/FinbackYu/kimi-code-hud
- 安装后重启或开新会话生效：
SessionStarthook 会把tui.toml的[status_line]指向插件托管副本，并在每次会话启动时自动修复； - 开关：
/plugins面板选中按Space，或/plugins disable kimi-code-hud//plugins enable kimi-code-hud； - 如果你已在
[status_line]配置了自己的命令，hook 不会覆盖它； - 更新：重跑一遍安装命令即原地更新，约 1 秒自动生效。
| 层级 | 范围 | 验证程度 |
|---|---|---|
| 推荐运行时 | 处于上游维护窗口内的 Node.js LTS（撰写本文时为 22 / 24） | 日常开发与发布验证以此为准 |
| 尽力兼容运行时 | 满足最低要求 Node.js ≥ 18 的所有版本（最低要求不变） | 已结束上游官方维护（EOL）的版本（如 18 / 20）不做主动测试；相关问题按尽力兼容处理 |
| 操作系统 | macOS / Linux / Windows | macOS 是维护者的主要开发与动态验证环境；Linux 由 CI 自动化测试覆盖（实际矩阵以 .github/workflows/test.yml 为准）；Windows 为尽力兼容——Git 探针已按 Windows 约定做可信可执行解析（含 PATHEXT，见 KI-7），2026-09-18 已在 Windows 11 + Windows Terminal 真实环境完成 HUD 动态验证（真实 PTY 下全屏模式的逐帧渲染、行 1 刷新、行 2 归属、额度刷新与冷启动耗时，当时用的是 2.0.0 与上线前的 KIMI_CODE_TUI_FULL_SCREEN=1 开关，当前入口是 tui.toml 的 tui_mode = "fullscreen"，证据见 KI-8）；窗口 resize、/reload-tui 热重载与失败回退仍未实测 |
| Kimi Code 宿主 | 源码与合成 fixture 基线 2.2.0；真实 TUI 验收待完成 | 逐版本契约审计与固定的上游提交见 CAPABILITIES.md |
CI 矩阵的增删是测试覆盖的变化，不构成支持契约的扩张或收缩；支持范围以本节为准。跨操作系统的交互式宿主矩阵（真实 TUI、终端模拟器、插件生命周期）已补齐 Windows 一行（Windows 11 + Windows Terminal，见 KI-8），macOS Terminal 与 Linux PTY 组合仍在补齐。
HUD 自有设置保存在 ~/.kimi-code-hud/config.json（JSON；容忍未知键，文件缺失或损坏时整体回退默认值）。同名设置的环境变量优先于配置文件。
| 键 | 取值 | 默认 | 说明 |
|---|---|---|---|
layout |
"normal" / "compact" |
normal |
布局档位；可见宽度超过 200 字符时自动 normal→compact 降级 |
permissionNames |
"official" / "short" |
official |
权限徽标措辞。official 跟随宿主 0.40+ 官方称呼（[Always Ask] / [Ask When Needed] / [Never Ask]）；short 保留旧短徽标（[manual] / [yolo] / [auto]）。非法值回落默认 |
disabled |
true |
（缺省即启用） | 禁用旗标；一般无需手改 |
{ "layout": "normal", "permissionNames": "official" }| 变量 | 取值 | 说明 |
|---|---|---|
KIMI_HUD_LAYOUT |
normal / compact |
布局覆盖，优先于配置文件 |
KIMI_HUD_PERMISSION_NAMES |
official / short |
权限徽标措辞覆盖，优先于配置文件 |
KIMI_HUD_THEME |
dark / light / auto |
手动固定配色主题；缺省跟随 tui.toml 顶层的 theme |
NO_COLOR / KIMI_HUD_NO_COLOR |
设置即生效 | 禁用全部 ANSI 颜色 |
KIMI_HUD_HOME |
目录路径 | 覆盖 HUD 自有配置与缓存根（默认 ~/.kimi-code-hud） |
KIMI_CODE_HOME |
目录路径 | 覆盖 Kimi Code 数据根（默认 ~/.kimi-code，本文出现的 ~/.kimi-code 均指未设置时的默认路径） |
KIMI_HUD_THEME 为 auto（或未设置且宿主无 theme）时经 COLORFGBG 判定深浅、回退 dark——状态行无法在 300ms 热路径上执行宿主的 OSC 11 查询；自定义主题名回退 dark。light 下徽标（模型名、[plan]、[Ask When Needed]、[swarm]、[tower]、[Never Ask]）加粗显示，琥珀/青色比宿主默认更亮（#D97706/#14B8A6），额度柱体从刺眼的 ANSI 红改为柔和真彩色（#B91C1C/#D97706/#0E7A38）；dark 模式不变，柱体 ANSI 色由终端按自身主题重映射。
- 默认（official 措辞）：
[Always Ask]（manual 档，褪色蓝 dark#54658A/ light#7D92B8——比默认前景安静，常驻以保持行首对齐）、[Ask When Needed]（yolo 档，琥珀黄，对齐宿主）、[Never Ask]（auto 档，亮红，便于与琥珀区分）； short措辞下为[manual]/[yolo]/[auto]，配色规则不变。
调试时临时退回内置状态栏：/plugins disable kimi-code-hud，恢复用 /plugins enable kimi-code-hud。
卸载：/plugins remove kimi-code-hud，托管副本下次运行时自动清除 tui.toml 条目。改完后 /reload-tui 或新会话生效（宿主会缓存最后一帧自定义状态栏）。
每段的精确口径（样本接纳规则、wire 推导路径、失败关闭边界、持久化文件）见 CAPABILITIES.md。要点：
- 速度样本只接纳流式 ≥250ms、≤1000 t/s 的
step.end，取最近 10 分钟内最多 5 个的中位数；预热与窗口过期以暗灰显示，模型切换重新预热； - 模型/thinking 优先取 wire（
profile.bind、会话内切换的config.update与每次请求的llm.request），只有 wire 记录会让 effort 以默认色显示；wire 未到达的懒启动阶段解析全局config.toml，config 来源（含显式[thinking].effort键）一律灰显——顶档 effort 宿主不落盘会使 config 无声过期，HUD 无法判断 config 是否仍代表当前选择；解析结果按会话快照~/.kimi-code-hud/sessions/thinking-<sessionId>.json固定并记录 config 依据，依据变化即重解析，wire 确认过的会话不受其他会话/effort改写全局配置的影响。懒启动阶段 max 档只能显示模型默认值或旧值（KI-5）； - goal / swarm / tower 状态从主 agent wire 的
goal.*/swarm_mode.*/tower_mode.*事件折叠；后台任务徽章从task.started/task.terminated与tasks/<taskId>.json旁车双源合并（取较新记录），只计running（被标lost后仍有新写入的续跑子代理除外，上游 issue MoonshotAI/kimi-code#3350）； - 配额仅对可归因到
managed:kimi-code的模型显示与刷新；provider 余额/成本在币种未知、自建代理、未知模型或混合 provider ledger 时失败关闭； - 会话成本本地计算，价格表以 2026-08-09 官方定价核对，不含服务端工具费等修正所以始终带
≈；DeepSeek 缓存命中字段在宿主补齐映射前按未命中价保守估算，数值可能偏高； - 用量分级着色 <60% 绿 / <85% 黄 / ≥85% 红；可见宽度超过 200 字符自动 normal→compact 降级。
宿主每秒通过 stdin 传一个 JSON 快照（读取上限 1 MiB、150ms 超时），命令 stdout 的第一行接管 footer line 1（line 2 固定由宿主绘制，插件无法接管）。300ms 是宿主截止时间（host deadline）：它约束包括 Node 进程启动在内的整个子进程生命周期，超时后进程树由宿主终止。HUD 自身在此之下把每帧工作限制在 220ms 的内部预算内（从脚本逻辑入口计时，不含 Node 启动），给宿主的调度与兜底留出余量。预算是协作式的：HUD 在步骤之间检查剩余时间、提前收手，但已在进行中的同步 I/O 无法被中途打断——单次慢读取最坏会越过内部预算，由宿主 300ms 截止兜底。失败/超时/空输出时宿主渲染内置行或重播上一帧，所以超时后旧帧可能继续显示一段时间（见 KI-4）——脚本对所有错误静默降级、绝不打印日志（唯一的非零退出是"已禁用/已移除插件的托管副本"自我清除 tui.toml 条目，插件开关由此实现）。
数据来自四路：stdin 快照与跨进程缓存的 Git 探针（cwd 只存 SHA-256，TTL 15s）；会话 wire.jsonl 增量解析（main + 全部 subagent，无正文，cursor 与计数持久化在 ~/.kimi-code-hud/sessions/，旧版根目录文件在会话恢复时自动迁移；超过 30 天未活跃的会话状态与进程被杀残留的 *.tmp-* 临时文件由 SessionStart hook 每日清理一次）；官方 /usages 配额接口（60s 缓存 + 后台刷新，双区域按 oauth host 判定）；provider 官方余额接口与本地定价的成本估算（按 provider + key 指纹隔离缓存）。
- 能力清单：Kimi Code 2.2.0 第一行 slots 的覆盖情况、数据来源，以及已经可读但尚未展示的 Cache/token/goal/task/Git 等信息；
- 已知问题：Git、终端宽度、失败帧与全屏动态验证缺口及验收条件。
- Kimi access token 仅从
~/.kimi-code/credentials/本地读取（CLI 自己负责续期，本工具只读不写），仅用于官方api.kimi.com/api.kimi.ai配额接口；DeepSeek API Key 仅在 provider 名与基址均为官方api.deepseek.com时读取，请求固定的官方余额接口； - 两类凭证都不写入日志、缓存或输出；provider usage 缓存只保存 API Key 的单向 SHA-256 指纹和规范化余额；
- 所有动态显示文本在 HUD 加 ANSI 样式前剥离 OSC、CSI 及 C0/DEL/C1 控制字符；HUD 自身颜色序列不经过该清洗器；
- Session Cost 完全在本地计算，不额外发送 API Key；持久化 ledger 只有模型别名与四类 Token 计数，无会话正文。
状态栏没变化？ 确认 /reload-tui 或重启过；确认 echo '{}' | node ~/.kimi-code/plugins/managed/kimi-code-hud/bin/kimi-hud.mjs 有输出。
没有 TPS？ 只有一种状态会完全看不到 TPS：当前会话连一个有效 step.end 样本都还没有（全新会话的首个 step 进行中，期间先单独显示 TTFT）。预热期（不足 3 个样本）、窗口过期与刚切换模型都以暗灰显示临时读数或最后一次中位数，攒够 3 个有效样本后转为正常亮度；任务刚落定时是例外——最后一次中位数与 gen/compacted 计时会在落定后的 1 分钟宽限内保持正常亮度，之后才转为暗灰。若连 TTFT 也没有，说明当前会话还没有完成过 step.end。
没有 Cache？ 会话还没有任何完整 step.end 用量时整段省略；首个有效用量计入后出现，此后常亮不再消失。升级后旧状态会从 wire 尾巴（最多 1 MiB）一次性重建累计计数。
没有配额段？ 先确认当前模型不是第三方 provider（/provider 接入的模型本就不显示配额，接口只覆盖托管订阅），并且其模型配置能明确解析到 managed:kimi-code；provider 未知时按安全边界失败关闭。managed 模型下，缓存首次生成前整段省略。0.43.1 的新响应使用 usages 中的比例字段；HUD 按返回内容显示 5h、7d 和 Monthly，月度同时有总量与 code 时显示 kimi/code 拆分。升级会使旧配额缓存失效，首次成功刷新后恢复。可手动 node ~/.kimi-code/plugins/managed/kimi-code-hud/bin/kimi-hud.mjs --refresh-quota 后重试。
没有 DeepSeek 余额或 Session Cost？ 必须正在使用 provider 名为 deepseek 的支持模型，且其 type = "openai"、base_url 是官方 https://api.deepseek.com（可带 /v1）。余额还要求有效凭证：api_key，或 Kimi Code 2.0.1+ 的 api_key_env 指向的非空环境变量（二者互斥；HUD 每次解析按变量名现读，密钥值不落盘、不进日志；变量未设置或为空时余额按安全设计隐藏，不回退到其他凭证）；首次后台刷新完成前不显示占位（成本必须先从余额响应确认币种）。完整用量 ledger 就绪后，即使余额不可用也可按已知币种单独显示 Session Cost。可静默运行 node ~/.kimi-code/plugins/managed/kimi-code-hud/bin/kimi-hud.mjs --refresh-provider-usage deepseek 后检查 ~/.kimi-code-hud/provider-usage/。兼容代理会按安全设计拒绝余额请求和成本估算。
没有 DeepSeek / OpenAI / Anthropic Session Cost？ 当前模型必须使用对应官方直连服务，且模型 ID 位于内置价格表。所有日志追平前不显示不完整数字；同一会话只要存在其他 provider 或无法解析模型的非零用量，整项隐藏。该值是本次会话的本地估算，不是 API 余额，也与 ChatGPT / Claude 订阅额度无关。
Context 段去哪了？ 插件不再自绘 Context 段，直接看宿主第二行的 context: N% (tokens/max)（该行永远由宿主绘制，插件无法接管）。
npm test # node --test基于 MIT 协议发布。© 2026 FinbackYu