概览

llmtrim-stats-plugin

Live llmtrim savings dashboard inside the DeepSeek Harness (DSH) Web UI: a settings dashboard plus a rotating carousel stats strip under the composer.

README / ZH

插件文档

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

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

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

关键词 / 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 注入已打开的标签页。

手动挂载（备选）

git clone https://github.com/Zenjibad/llmtrim-stats-plugin.git（任意位置）。
在 ~/.dsh/profiles/web/package.json 的 dependencies 加 "llmtrim-stats-plugin": "link:<仓库路径>"，然后在 profile 目录 pnpm install。
重启 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

Requires DSH ≥ 0.1 with the web profile.

llmtrim-stats-plugin