用量教练与回执 marksimZ/dsh-usage-kit

dsh-usage-kit

一个 DeepSeek Harness 插件，包含两个小巧、互相独立的组件，都围绕一次对话正在消耗什么：

1. 上下文教练 —— 输入框上方一行提示，只在有事可做时出现：上下文快满了、预计下一次请求可能触发压缩，或者缓存命中率太低导致重复输入变贵。点一下就能运行 /compact。
2. 回合回执 —— 每个完成的回合下方一行安静的文字： 8 步 · 955.0k tok · 缓存 97% · ¥0.32 · 2m14s，可展开查看四个计费 token 桶、路由到的模型，以及峰时/闲时时段。

两个组件打包在同一行插件里，但由各自独立的 effect 注册，所以关掉其中一个不影响另一个（widgets.coach: false / widgets.receipt: false）；想删掉某个组件，只需从 src/client.js 里移除对应的注册块。

为什么是这两个

DSH 已经在输入框里内置了 14px 的上下文圆环，上方还有 todo/goal 停靠区。这套工具不重复它们：

- 圆环只显示数字；教练补上动作（无事可做时保持隐藏，不会变成第二个仪表）；
- 内置的回合用量面板只有 token，而且藏在点击之后；回执是一行内联文字，带金额和耗时，价格取自 DeepSeek 官方价目表。

界面

composer area
┌─────────────────────────────────────────────────────────────┐
│ 上下文已用 83% · 历史消息约 42.0k 可压缩 [压缩] │ ← coach (only when triggered) ├─────────────────────────────────────────────────────────────┤ │ … input card … │ └─────────────────────────────────────────────────────────────┘

transcript, under a completed turn
✓ 3 files changed · 2 commands 8 步 · 955.0k tok · 缓存 97% · ¥0.32 · 2m14s ▾ ← receipt 未缓存输入 30.0k 缓存读取 900.0k 输出 25.0k 模型 deepseek-flash 时段 峰时价

环境要求

- 一个组合了 webServer 和 sessionProjections 的 DSH 客户端（Desktop 客户端和 dsh web 都满足）。教练只需要内置的会话投影；回执需要 Host 那一半来折叠每回合用量。
- Node 20+ 仅用于测试/安装脚本；插件本身没有构建步骤。

安装

git clone https://github.com/marksimZ/dsh-usage-kit.git dsh-usage-kit

一次性运行：

dsh web --patch /absolute/path/to/dsh-usage-kit/cordis.patch.yml

永久安装到某个配置档的补丁层（该配置档存在时安装器选 desktop，否则选 web）：

node scripts/install.mjs # writes $DSH_HOME/profiles/<profile>/cordis.patch.yml
node scripts/install.mjs --dry-run

验证运行中的 GUI 是否已加载：

node scripts/verify-deployed.mjs --url http://127.0.0.1:<GUI 端口>

Host 那一半是新增的插件行，所以会在下次客户端启动时加载；浏览器那一半会重新加载普通刷新页面即可。现有 dsh-balance-guard 不受影响。

配置

每个键都可选，默认值写在 cordis.patch.yml 里。

| 键 | 默认值 | 含义 |
| widgets.coach | true | 注册上下文教练行 |
| widgets.receipt | true | 注册回合回执行 |
| coach.occupancyWarn | 0.8 | 触发压缩建议的占用率 |
| coach.projectedWarn | 0.9 | 触发压缩建议的下一请求预测占用率 |
| coach.cacheHitFloor | 0.8 | 缓存命中率低于此值时，显示「重复输入」提示 |
| coach.minPromptTokens | 20000 | 提示词 token 数达到此下限才值得显示该提示 |
| cnyPerUsd | 7.2 | 回执金额的显示换算汇率 |
| holidays | [] | 全天按低谷计费的 UTC 日期（中国法定节假日） |
| turnsKept | 300 | 每个会话为回执保留的已完成回合数 |

价格写在 src/pricing.js 里（美元 / 1M token，deepseek-flash 和 deepseek-v4-pro 各有高峰与低谷两行），由 scripts/pricing-spec.mjs 锁定。高峰时段为周一至周五 UTC 01:00–04:00 和 06:00–10:00，holidays 除外。

架构

Host half (src/index.ts)
ctx.on('session/event')
request/context → the routed model for the turn
turn/start → open a turn (steps, running usage total)
assistant/message → add its billed usage sample (retries add another)
turn/end → price the turn and publish a receipt
src/pricing.js → price catalog, peak calendar, billing math (pure)
└─ GET /dsh-usage-kit/receipts?session=<id> → { byTurn, bySeq } receipts
└─ globalThis.__DSH_USAGE_KIT_CONFIG__ → widget switches for the browser half

Browser half (src/client.js)
conversation.input.dock → context coach (reads contextPressure / contextBreakdown / tokenUsage)
conversation.chat.turnTail → turn receipt (fetches the session's receipts, cached 10s)

为什么还需要 Host half？ 浏览器里的 tokenUsage 投影是累计值，推不出每回合的用量。所以 Host 从服务商上报的 assistant/message.usage 样本里逐回合汇总，算出价格再发布。教练不需要 Host 数据，完全跑在现成的投影上。

为什么用两个查找键？ 对话记录条目拿到的是收尾 node 的 seq，不是 turn/end 事件的 seq，只按 seq 建索引会漏。所以回执同时按回合号（主键）和结束 seq（兜底）发布，浏览器再从收到的 TurnLocation 里稳妥地解析出回合 id。

为什么选 conversation.chat.turnTail 和 conversation.input.dock？ 这两个文档座位本来就接收 useProjection 和输入/聊天钩子；注册新的 id 会在现成条目旁边加一条，而不是替换它们（replaceRisk: none）。

测试

npm test # pricing spec + client spec + bundle smoke + theme tokens + visual tokens
npm run test:host # folds three turns on a mock context and drives the real receipts route
npm run verify # read-only probe of a running GUI

| 脚本 | 固定住什么 |
| scripts/pricing-spec.mjs | 官方价格表、高峰/低谷日历、计费算法、用量增量 |
| scripts/client-spec.mjs | 教练建议规则（占用 / 预估 / 缓存）、对话轮次身份、回执摘要与详情、格式化器、注入开关 |
| scripts/client-smoke.mjs | 打包契约、单一样式表、两个席位注册、按控件开关 |
| scripts/host-smoke.mjs | 从助手样本累计用量（重试会累加）、从请求/上下文取模型、byTurn/bySeq 键、成本、注入、路由边界 |
| scripts/theme-tokens.mjs | 每个 var(--dsw-*) 都由随包发布的主题声明 |
| scripts/visual-tokens.mjs | 不用原始颜色，圆角/字号只取自主题刻度，不用无限动画 |
| scripts/verify-deployed.mjs | 运行中的 GUI 能提供打包产物和回执路由 |

限制

- 回执从插件加载时开始。 Host 那一半挂载之前完成的轮次没有折叠回执，所以它们的尾行干脆不渲染（不做任何猜测）。
- 教练只给建议，不自动执行。 它从不自行压缩；按钮运行随包发布的 /compact 命令，拒绝时以行内文本呈现。
- 金额是按标价估算，不是账单：用的是目录价和轮次结束时的时段，不是服务商的延迟结算。
- 一行，两个控件。 删除控件要改源码（移除它的注册块）或改配置开关；按设计没有按控件安装的行。

许可证

MIT —— 见 LICENSE。