llmtrim 节省面板 Zenjibad/llmtrim-stats-plugin

llmtrim-stats-plugin · DSH 实时 llmtrim 压节省统计面板

在 DeepSeek Harness (DSH) Web UI 内实时展示 llmtrim 的压节省统计：设置页完整仪表盘 + 输入区轮播统计条。

English: README.md · LLM 索引: llms.txt · Agent 指南: AGENTS.md

dsh-plugin DeepSeek Harness license install

关键词 / Keywords: dsh-plugin · deepseek-harness-plugin · llmtrim · compression · tokens · savings · stats · dashboard · carousel

📑 目录

- ✨ 特性
- 🏗️ 工作原理
- 🚀 快速开始
- ⚙️ 配置
- ❓ 常见问题
- ⚠️ 安全须知
- 📦 项目结构
- 🙏 致谢

✨ 特性

| 特性 | 说明 |
| 📊 设置页仪表盘 | 设置 → llmtrim Stats：KPI 卡片（已支付 / 未压缩应付 / 今日节省 / 本周节省 + token 削减、请求数、按现价重估净节省）、守护进程健康徽章 + 版本号、按模型表格（模型 / 请求数 / 节省 % / USD） |
| 🎠 可配置轮播条 | 聊天输入框下方统计条：选择 轮播（每次切换一个统计）或 静态（同时显示所有勾选统计、不轮转）——自由挑选展示哪些统计，每 5 秒刷新 |
| 💵 四张金额卡片 | 已支付（money.paid_usd）、未压缩应付（money.would_have_usd）、今日节省（money.saved_today_usd）、本周节省（按本周（周一起）token 占比 × 累计 money.saved_usd 折算——llmtrim 不提供周度美元额） |
| 🔗 与官方 CLI 一致 | Host 通过 subprocess 服务运行 llmtrim status --json（与 llmtrim status 相同命令）——不解析账本文件，始终与 CLI 一致 |
| 🩺 守护进程健康一目了然 | 仪表盘显示绿/黄徽章（守护进程健康 / 已停止）与二进制版本号 |
| 🌗 主题自适应 | 全部颜色使用 --dsw-alias- 设计令牌，亮/暗色自动跟随 |
| ♨️ 重启常驻 | 真实 profile 打包插件：dsh plugin add 安装一次，每次 DSH 启动自动加载 —— 无需 cordis_define、无需每次重装 |

🏗️ 工作原理

llmtrim 拦截器（守护进程 :43117）──写入──> ~/.local/share/llmtrim/tracking.db │ Host 半区（DSH 进程内） ▼ └─ subprocess 服务：resolveExecutable('llmtrim') → spawn llmtrim status --json └─ 重塑 → { daemon, totals, money, cost, byModel } └─ settings 命名空间 llmtrim-stats { mode, staticStats }（轮播配置） └─ webServer 路由：GET /llmtrim-stats/api（快照含配置） PUT /llmtrim-stats/config（持久化轮播选择） │ Client 半区（浏览器） ▼ └─ 单一 5s 轮询 fetch(/llmtrim-stats/api) → 快照分发到两个席位 ├─ settings.section (id llmtrim-stats) → 完整仪表盘 + 轮播配置 └─ conversation.composer.dock (id llmtrim-carousel) → 轮播或静态条

- 纯拉取：不解析账本、无事件、无文件监听；llmtrim 缺失或 status --json 失败 → {ok:false,error}，UI 显示不可用，轮询自动恢复。
- 只读：插件从不写入 llmtrim 的目录或账本。
- 持久化：随包声明 dsh.bundle（cordis.patch.yml）+ dsh.client（exports["./client"] 打包产物），作为真实 profile 插件安装，DSH client-modules 每次启动都会扫描加载。

🚀 快速开始

标准安装：dsh plugin add（重启常驻）

从本仓库安装：

本地目录（在本仓库父目录执行）：
dsh plugin --profile web add ./llmtrim-stats-plugin

或直接从 GitHub（任意 DSH 机器）：
dsh plugin --profile web add github:Zenjibad/llmtrim-stats-plugin
或：
dsh plugin --profile web add git+https://github.com/Zenjibad/llmtrim-stats-plugin.git

dsh plugin add = 向 profile 做 pnpm add + dsh.profile.bundles 协调：识别到本包的 dsh.bundle 声明后，把 llmtrim-stats-plugin 追加进 bundle 栈。重启 DSH，然后硬刷新浏览器标签页（Ctrl+F5）。启动时 client-modules 扫描器解析 exports["./client"]，仪表盘与轮播条出现。无需 cordis_define，重启后依旧。

⚠️ 注意：安装（或更新）客户端插件后必须硬刷新页面（Ctrl+F5）——DSH 客户端 HMR 只会热替换已加载的 bundle，不会把新增*的 bundle 注入已打开的标签页。

手动挂载（备选）

1. git clone https://github.com/Zenjibad/llmtrim-stats-plugin.git（任意位置）。
2. 在 ~/.dsh/profiles/web/package.json 的 dependencies 加 "llmtrim-stats-plugin": "link:"，然后在 profile 目录 pnpm install。
3. 重启 DSH。

使用前提

- 本机已安装 llmtrim 且在 PATH 上（npm i -g @llmtrim/cli——插件通过 subprocess 服务解析；路径特殊时可用 LLMTRIM_BIN 覆盖）。
- 实时数字需要 llmtrim 守护进程在运行；未运行时插件照常工作（显示已停止/零值）。

⚙️ 配置

轮播条可在设置页配置（持久化到 llmtrim-stats settings 命名空间，通过 PUT /llmtrim-stats/config 写入）：

| 设置项 | 取值 | 效果 |
| 模式 | rotating（默认）/ static | 轮播：每 4 秒在所选统计中切换一个；静态：同时显示所有勾选统计、固定不轮转 |
| 统计项 | 9 个复选框（默认全选） | 轮播条显示哪些统计：今日节省、累计节省、已支付、未压缩应付、本周节省、token 削减、请求数、输入节省、往返节省 |

固定常量见源码：

| 可调项 | 位置 | 默认值 |
| HTTP 路由 | src/index.ts | GET /llmtrim-stats/api、PUT /llmtrim-stats/config |
| 可执行文件解析 | src/index.ts 中的 resolveLlmtrim | subprocess.resolveExecutable('llmtrim')，回退 LLMTRIM_BIN，再回退 npm win32-x64 路径 |
| 轮询间隔 | src/client/index.tsx 中的 POLL_MS | 5 秒 |
| 轮播节奏 | src/client/index.tsx 中的 CAROUSEL_MS | 4 秒 |
| 设置页席位 | src/client/index.tsx | settings.section id llmtrim-stats，顺序 80 |
| 轮播席位 | src/client/index.tsx | conversation.composer.dock id llmtrim-carousel，顺序 15 |

❓ 常见问题

Q: 仪表盘/轮播条不见了？
A: 先重启 DSH（如果 Host 半区尚未挂载），再硬刷新浏览器标签页（Ctrl+F5）。新增的客户端 bundle 只有整页刷新才会加载——HMR 不会把新 bundle 加进已打开的标签页。

Q: 显示「llmtrim stats 不可用」？
A: Host 无法运行 llmtrim status --json。请在 shell 里确认 llmtrim --version 可用；若不在 PATH 上，设置 LLMTRIM_BIN 为绝对 exe 路径后重启 DSH。

Q: 轮播条显示零 / 「守护进程已停止」？
A: 守护进程未运行（llmtrim start），或账本为空。启动守护进程后，下一次 5 秒轮询即会填充数字。

Q: 「代理账单节省」与「按现价重估净节省」为何不同？
A: 两者都直接来自 llmtrim status --json——money.saved_usd（按每次对话冻结费率）与 cost.net_saved_usd（按当前列表价重估）。它们是同一批流量的不同视角；llmtrim 官方 CLI 也展示同样的区别。

Q: 「本周节省」如何计算？
A: llmtrim 只按生命周期（money.saved_usd）与今日（money.saved_today_usd）报告金额；其 by_period 行只带 token 不带 USD（默认为 2026-08-19 形式的按日键）。因此插件按比例折算：本周（周一起）输入 token ÷ 累计输入 token × 累计节省。随账本增长而更新。

Q: 能不能让轮播条只显示一个统计、或停止轮播？
A: 可以——设置 → llmtrim Stats → Carousel：把模式设为 Static 并勾选你想要的统计，静态模式会同时显示所有勾选统计（固定不轮转），只勾选一个即固定显示单条。轮播模式则每次切换一个勾选统计。每次修改后会出现绿色「Saved ✓」提示；选择会持久化并跨重启保留。

Q: 如何彻底移除？
A: dsh plugin --profile web rm llmtrim-stats-plugin（或删除 profile 依赖与 bundle 条目）后重启 DSH。

⚠️ 安全须知

- 只读：插件只运行 llmtrim status --json，从不写入 llmtrim 的文件或账本。
- 同源路由：客户端仅轮询 DSH 同源的 /llmtrim-stats/api。
- 不接触凭据：插件不读取任何 API 密钥、token 或机密——只读取公开的节省快照。
- 小输出：status --json 的 stdout 上限 512 KB。

📦 项目结构

llmtrim-stats-plugin/
├── src/
│ ├── index.ts # host 半区：解析 llmtrim、spawn status --json、重塑、/llmtrim-stats/api 与 /llmtrim-stats/config 路由、settings 命名空间 │ └── client/index.tsx # client 包：5s 轮询、设置页仪表盘、可配置轮播统计条 ├── cordis.patch.yml # dsh.bundle patch（启动时插入插件行） ├── tsdown.config.ts # 打包 host（node ESM）+ client（CJS ModuleLoader） ├── package.json # name、exports["./client"]、dsh.client + dsh.bundle ├── lib/ # 构建产物（index.js、client.js） ├── AGENTS.md # AI agent 仓库指南 ├── llms.txt / llms-full.txt ├── README.md / README.zh.md └── LICENSE

🙏 致谢

- llmtrim — 压缩拦截器与 llmtrim status --json 数据源。
- DeepSeek Harness — DSH 插件/动态运行时、Slots、主题、webServer、client-modules。
- headroom-stats-plugin — 打包式 client 插件构建模式参考（tsdown host/client 拆分、cordis.patch.yml、dsh.client、设置页 + 轮播席位）。

📄 License

MIT

Repo

llmtrim-stats-plugin on GitHub

Requires DSH ≥ 0.1 with the web profile.