Kimi Code 用量看板

只读扫描 ~/.kimi-code/sessions 下各会话的 wire.jsonl，在本地起一个 Web 看板：token 用量卡片、趋势图、按模型的费用估算，以及套餐配额（官方接口实时查询）。除保存单价表外不写入任何数据。

启动

python server.py [端口]   # 默认 8787

然后浏览器打开 http://127.0.0.1:8787。无第三方依赖，Python 3.7+ 即可。

桌面模式（托盘常驻）

依赖装在项目内 .venv（已装好；重装：.venv\Scripts\python -m pip install pywebview pystray pillow）。

• 双击 start.bat，或运行 .venv\Scripts\python desktop.py
• 单实例运行：已有看板在跑时重复启动会自动退出（不会出现多个窗口）；要换新版本请先在托盘右键「退出」再启动
• 弹出窗口是 420×560 无边框小部件（实时用量桌面 Board 设计）：输入/输出/总 Tokens 与请求次数统计卡（较前一时段涨跌幅 + 迷你走势线）、用量趋势面积图（1小时/6小时/24小时/今天切换，叠加缓存命中率虚线）、模型使用 Top 3、费用估算与缓存命中率（卡内含「单价设置」「完整看板」入口）、周配额与 5 小时窗口双进度条；拖动头部移动窗口，− 最小化为 260×44 横条、× 收到托盘；不占任务栏按钮（Alt+Tab 也不出现，托盘左键管理显隐），横条与展开态全程置顶，贴屏幕右/下边缘时切换尺寸自动保持贴边不收出屏外
• 配额告警：周额度 ≥50% 时 mini 横条与展开态配额卡出现黄色呼吸灯边框，≥90% 时切换为红色（仅桌面面板，完整看板无此效果）；点击横条或配额卡，确认后取消该级别告警显示（用量回落到阈值以下后重新允许）
• 完整看板多一个「会话明细」视图：按会话聚合调用次数 / tokens / 费用，点击行展开模型拆分；随当前时间范围联动
• 托盘图标数字 = 周配额已用百分比；悬停显示 周 / 5 小时用量与近 5 分钟 token 速率
• 左键弹出 / 收起面板；关闭窗口 = 最小化到托盘；右键菜单：显示 / 隐藏、刷新、完整看板、退出
• 开机自启：面板「设置」弹窗勾选即写入注册表 HKCU Software\Microsoft\Windows\CurrentVersion\Run（仅 Windows）

Token 速率 与 TPS

• 卡片「Token 速率」与托盘悬停显示的是滑动窗口吞吐（tokens/分钟）：近 5 分钟均值，附输出速率与近 1 小时峰值。
• TPS / 延迟（完整看板）：
  • 「TPS 吞吐」= 近 5 分钟总 tokens ÷ 300（tokens/秒）；「请求速率」= 近 5 分钟调用数 ÷ 300（次/秒）——均为滑动窗口聚合。
  • 「TPS 输出(实测)」= 输出 tokens ÷ step.end 解码耗时（llmServerDecodeMs），wire 实测字段，非估算。
  • 「首字延迟」= llmFirstTokenLatencyMs 的均值 / P50 / P95。
  • 「异常回合率」= step.end 中非 tool_use / end_turn 结束的占比（失败/限流/中断）。

接口

• GET /api/usage?start=&end=&bucket=&tzoff= — 用量卡片 + 趋势分桶 + 按模型费用估算
• GET /api/export?start=&end=&fmt=csv|json — 导出所选范围数据：CSV 逐 turn 明细（UTF-8 BOM，Excel 兼容）/ JSON 完整聚合包（含逐条记录与费用）
• GET /api/sessions?start=&end= — 会话明细（按会话聚合：调用 / tokens / 费用 / 模型拆分）
• GET /api/plan — 套餐配额（周配额 / 时间窗口 / Extra 余额），官方接口实时查询，60 秒缓存；附带配额告警 alerts（50% / 90%）
• GET /api/pricing / POST /api/pricing — 读取 / 保存单价表（pricing.json）
• GET /api/config — 当前数据目录、凭据/会话数据存在状态、开机自启状态
• POST /api/config — 保存自定义数据目录（{"dataDir": "路径"}，null 恢复默认）与开机自启（{"autoStart": true|false}）到本地 config.json / 注册表
• GET /api/update — Kimi Code CLI 更新检测（本地版本 vs GitHub Releases 最新版，2 小时缓存；仅走 GitHub 官方版本线）

数据目录识别

凭据（credentials/kimi-code.json）与会话数据（sessions/**/wire.jsonl）默认随 kimi CLI 存放在 ~/.kimi-code。看板按以下顺序自动识别数据根目录：

1. 环境变量 KIMI_CODE_HOME（kimi CLI 官方支持，可迁移整个数据目录）
2. 项目内本地配置 config.json 的 dataDir（在「设置数据目录」弹窗中手动指定）
3. 默认 ~/.kimi-code

未找到登录凭据时，看板 / 桌面面板会显示引导提示，并可通过「设置数据目录」手动指定位置。config.json 只保存在本机（已加入 .gitignore），不会随仓库分发。

更新检测

看板会检测 Kimi Code CLI 是否有新版本（本地 kimi --version vs GitHub MoonshotAI/kimi-code Releases 最新版，结果缓存 2 小时；仅使用 GitHub 官方版本线——npm 上的 kimi-code 是另一条已停更的版本线，混用会误导，故不做兜底）。发现新版本时，看板与桌面面板会弹窗提示（同一版本只提示一次），可跳转查看更新说明；升级仍由 kimi upgrade 手动执行。

深色模式

完整看板与桌面面板头部均有主题开关（☀ 浅色 / ☾ 深色 / ◐ 跟随系统，三态循环），选择存于浏览器 localStorage（两端同源自动同步）；默认跟随系统（prefers-color-scheme），趋势图配色同步切换。托盘图标为深色实底、深浅任务栏均可辨；桌面 mini 横条空间有限不设开关，展开后切换即可。

测试

后端单元测试（标准库 unittest，无第三方依赖）：python -m unittest discover -s tests -v。覆盖 wire 解析与模型归因、step 级统计、聚合与告警阈值、路径脱敏、导出接口、HTTP 路由与路径穿越防护。GitHub Actions CI（.github/workflows/ci.yml）在 push / PR 时于 Python 3.8 / 3.10 / 3.12 上运行。

安全说明

• 认证信息与会话数据始终存放在 ~/.kimi-code（或 KIMI_CODE_HOME 指定目录），不在项目目录内，不会随 git push 或打包分发泄露。
• 本仓库不读取、不写入、不上传任何凭据内容；/api/plan 仅使用内存中的 token 查询官方配额接口，错误信息中的本机路径会被脱敏为 ~。
• .gitignore 已排除 logs/、.venv/、__pycache__/、config.json 等，上传前无需额外处理。
• 打包发给他人时：只打包源码（server.py、desktop.py、start.bat、web/、pricing.json、README.md）即可，.venv/、logs/ 不要打包。

pricing.json

每 1M tokens 单价（人民币 ¥）：

• input — 缓存未命中输入
• cacheRead — 缓存命中读取
• output — 输出
• "*" — 未列出模型的兜底价

完整看板「费用估算」面板与桌面面板「费用估算」卡的 ⚙ 按钮均可打开「单价设置」弹窗，改完保存即生效，也可直接编辑该文件。

目录结构

server.py      后端：扫描、聚合、HTTP 服务（无第三方依赖）
desktop.py     桌面模式：托盘常驻 + 原生窗口（依赖在 .venv）
start.bat      双击启动桌面模式（无控制台窗口）
web/           前端：index.html / app.js / style.css（完整看板）+ panel.html / panel.js / panel.css（桌面紧凑面板）+ vendor/
tests/         后端单元测试（unittest）
.github/       GitHub Actions CI
pricing.json   单价表
logs/          运行日志（board.log 自动轮转 + 脱敏）
.venv/         桌面模式依赖的隔离 Python 环境