# 本地用量工作台 / Local usage workbench

版本：0.5.0。兼容目标与原插件一致：DeepSeek Harness 0.1.2-rc.1；自动验证固定上游提交 `a66e4702047846cdaa10c66c9d3df3951f5ea70d`。安装方法沿用仓库 README，工作台入口是设置中的「用量工作台 / Usage workbench」。原有「Token 用量」页面及原会话用量投影保留。

## 从体检到优化

先选一个会话，点击「读取并体检」。这是本地事件元数据检查，不会调用模型，也不会发送提示词或工具正文。收据按未缓存输入、输出、缓存读取、缓存写入四个互斥桶展示总量，并分解普通请求、重试和压缩用量。对账差异、工具错误、未配对工具事件、未结束生命周期、待审批事件和重试/压缩占比均有规则版本与证据。没有规则命中不等于业务结果正确。

快照固定生成时刻与 revision；运行中的会话需重新读取。单次最多检查 200,000 个事件，时间线每页 200 个节点，最多缓存 8 个快照，10 分钟未使用过期。翻页使用同一 revision，不把不同时间的页面拼接成一个收据。活跃时长按回合区间并集计算，避免并行执行重复累计。

JSON 收据默认隐藏会话、路由和节点标识；费用中的价卡与节点标识也被移除。JSON 的节点明细只包含当前页面，总量覆盖完整快照，导出中明确记录范围。Markdown 收据只包含数值摘要。原文、工具参数、工具输出、请求正文不会进入收据。

## 版本化价卡：估算不是账单

价卡按 **精确 provider + model + 币种 + 生效区间** 匹配。`effectiveFrom` 包含边界，`effectiveTo` 不包含边界。相同路由和币种的生效区间不允许重叠。未来生效价卡不会提前应用，USD 与 CNY 分别显示且绝不直接相加；不做隐式汇率换算。

四类单价单位是每百万 Token。空白或 `null` 表示未知，`0` 表示明确免费。缺少价卡、缺少某类单价、缺少请求级上下文证据等情况必须显示不可用、部分覆盖或区间，而不是完整零费用。价格明细记录价卡 ID、核对时间及估算模式，官方账单仍是结算依据。

页面支持新增、编辑、删除和 JSON 导入/导出。高级 JSON 支持：

- `periods`：提供方时区内的星期、起止分钟和费率，星期从 0（周日）至 6；时段不可重叠，跨午夜分成两条。
- `tiers`：按单次请求输入量的阶梯费率，阈值不得重复。没有请求级上下文证据的汇总用量不套用阶梯。
- `cacheWriteVariants`：short/long 缓存写入类别；缺少类别证据时对应写入价格未知。

同一价卡叠加分时与上下文阶梯仍被明确拒绝，不猜测优先级。这是计价规则边界，不代表支持任意提供方合同。数值、时区、URL、数组大小和载荷体积均有校验。编辑参考价卡后来源会标记为用户定义。

DeepSeek 模板只提供路由结构，不预填可能已经变化的价格。请先核对提供方官方价目表、实际端点、路由标签和生效时间，再填写。模板的创建时间不意味着插件联网核验过价格；插件不会自动拉取外部价目表。

「历史参考」使用调用事件时间选择价格版本。事件时间不能证明提供方实际计费时点，分时费率证据不足时展示范围。「当前费率重估」把历史 Token 数量按当前费率重算，用于比较，不声称它是历史实付费用。

## 辅助分析账本

原页面发起的 AI 用量分析、AI 轨迹分析会进入独立辅助账本；工作台本地体检不进入账本，也不会生成模型费用。仅记录本版本启用后的调用，不能倒推出旧版本未记录的数据。

账本记录调用类别、时间、状态、路由摘要及提供方上报的 Token 用量，不保存原始路由标签、提示词或响应正文。流式累计用量更新替换同一次调用的先前累计值，避免重复加总。没有用量上报时显示未知；失败或取消后已经收到的用量保留为暂定数据，不伪装成完整账单。Host 重启时将遗留 running 记录改为 interrupted 并持久保存首次恢复时刻；保存失败时读取报告不可用，避免把内存状态误报为持久记录。

最多保留 512 条，淘汰数量明确展示，因此它不是无限保留的审计档案。可以导出或显式勾选确认后清空；有分析运行时拒绝清空。清空辅助账本不修改原会话账本。存储失败会提示不可用，不阻断用户本来的分析任务，也不静默覆盖损坏的历史配置。

共同窗口合计按清空时刻和已淘汰调用的最晚开始时刻判断历史缺口；早于所选窗口的损失不会永久使后续窗口不完整。旧版本只记录淘汰数量、没有时间时，以本次启动作为保守上界并保存，因此不会猜测旧窗口完整；完整位于该上界之后的新窗口可以恢复完整覆盖。

稳定请求标识的哈希预约在 30 天后到期，容量上限为 2048 条；启动、读取工作台和保存配置时都会清理到期预约，同时移除仍保留账本中的过期请求标识副本，用量及审计时间不删除。清理不依赖下一次模型分析；Host 未运行或没有任何后续操作时，在下次启动或操作时完成清理。此有界去重不能提供无限期 exactly-once 保证。

## 变化归因与项目预算

变化归因支持 7 / 30 / 90 个完整 UTC 日：排除今天，区间右端不包含。桶、路由、会话贡献项是可加总的算术差额，不推断业务因果。日期不可靠的会话单独列为排除用量；缺少可靠路由分解时保留未归属残差。页面展示绝对变化最大的 100 个会话，CSV 包含全部贡献项并防止电子表格公式注入。

一个会话只有一个主项目，可以有多个筛选标签，标签不会重复加总用量。删除项目会解除其会话归属，但不删除会话。未分组会话始终保留。浏览筛选影响变化报告和周报，不会缩小项目预算的实际核算范围。

Token 和金额预算使用包含今天的滚动 30 个 UTC 日，因此与完整周期变化对比不同。Token 预算 0 表示关闭，金额预算空白表示关闭；80% 起预警，达到预算显示超出。金额预算按当前费率重估。只有日期与定价完整才能显示预算内；已知费用下界本身已超预算时可以保守提示超出。全局与各项目支持分别设置 USD/CNY 金额预算。

预算是只读提示，不停止、取消或延迟任务，不自动修改模型、配置或排程。

## 优化实验室与情景试算

实验保存不可变统计快照：实验名、基线/候选组、配对任务编号、任务类别、输入规模、运行条件、配置版本标签、Token、活跃时长、重试次数和可用参考费用。人工验收必须明确选择通过、失败或未验收；回合结束不等于业务验收通过。请只填写标签，不在标签中粘贴敏感正文。

配对要求任务编号、类别、规模和条件一致，且每对基线/候选各一次。统计提供样本数、均值、中位数、样本标准差、配对差值和验收率。每个通过任务费用包含同组失败尝试；零通过、未验收或价格覆盖不完整时不可用。小样本不能证明显著性，所有对比标明探索性质，不输出虚假的模型排行榜或因果结论。

价卡变更才更新 priceRevision 并使当前收据费用失效；只保存项目或实验不再清空费用。既有实验中的费用快照不会被新价卡改写。

情景试算在不修改真实账本的前提下，将指定比例未缓存输入迁移为缓存读取，Token 总量守恒；缓存命中只是明确的假设。可选择另一张价卡和执行时刻，查看提供方时区的下次费率切换及本地时间。相同 Token 换费率不等于换模型后的真实消耗预测；不调用模型或自动执行错峰任务。

## 周报与同页面只读联动

SVG 与 JSON 周报只包含窗口日期、可比覆盖标志、活跃会话数、Token、差额、缓存读取比例，不含会话名称、项目名、路径、路由或正文。下载使用当前浏览筛选。

跨插件只读摘要默认关闭。开启后，同一页面可以监听 `dsh-token-usage:summary`，或发送 `dsh-token-usage:summary-request` 请求最新摘要。每次请求重新确认 Host 配置，限制并发并节流。服务端不可用时不会授权共享。摘要范围为全部可观测会话，不因当前页面筛选而变化。

```js
window.addEventListener('dsh-token-usage:summary', event => {
  console.log(event.detail); // 数值白名单，不是会话正文
});
window.dispatchEvent(new Event('dsh-token-usage:summary-request'));
```

没有新增 HTTP 服务，没有 `postMessage` 跨窗口入口，没有命令执行入口。关闭后停止发出新摘要；已经被同页面代码接收的数据不能追回。页面卸载清理事件监听器和未完成请求。

## 数据保存与升级

配置和辅助账本保存在 Host 的 `token-usage-workbench` settings 中，采用带 schema 标记的有界结构。所有写入串行执行，配置保存带 revision 前置条件；多窗口冲突会报错并要求刷新，不使用 last-write-wins 覆盖他人的修改。非法或损坏配置不会被自动清空。

本地工作台 RPC 复用插件的本机连接检查，网络远程页面不会得到该接口的访问权限。不上传遥测，不采集 API key，不为读取配置建立外部网络连接。用户手动下载的本地文件仍应按组织的数据分类制度保管。

## 可重复验证

先按 README/现有 CI 方式链接固定 DSH 工作区，再运行：

```sh
npm run typecheck
npm test
bash scripts/run-workbench-e2e.sh
npm run build
```

浏览器脚本使用固定 Chromium 工具版本，真实挂载工作台 React 组件，通过真实 Host 工作台 RPC 读写文件系统上的测试配置；DSH 事件和模型传输使用合成 fixture，不产生付费模型调用。覆盖体检、费率、收据脱敏、项目预算、配置重载、变化导出、情景、人工验收实验、辅助账本、周报共享、冲突保护及中文移动端。证据输出到 `test-results/workbench`，包括日志、JSON 结果和截图。

这验证的是固定版本接口与合成输入下的端到端链路，不等同于在用户生产环境调用真实提供方并核对其账单。生产安装仍使用原插件包；测试 HTTP fixture、浏览器工具和候选构建脚本不包含在发布包中。


## 0.5.0 的补齐与迁移

原 workbench-v1 状态会校验并迁移为 workbench-v2；不丢弃既有项目、实验或辅助账本。不修改原会话 projection。纯聚合函数已移至 `src/client/selectors/usage.ts`，原页面保留兼容导出。

每条诊断现在包含 `scope`、中英文 `suggestedAction` 和可用的节点页引用。新增时间/路由覆盖规则；预算压力与覆盖缺口按当前快照生成时刻、完整项目/全局范围计算，导出和页面使用相同诊断集合。节点图以当前视图最大 Token 归一化，节点视图仅当前页，桶/调用类别/路由视图覆盖完整快照；不同分类不相加。点击节点可以查看四类 bucket 与最终性。

合计面板使用包含今天的 7/30/90 个 UTC 日，分别显示会话、辅助分析和两者已观测合计。日期缺失、辅助记账开始较晚、未知/暂定用量、历史淘汰/清空都会披露；辅助记录按调用开始日归属，不虚构跨日 Token 分布。占比的分母是已观测合计，不是提供方账户账单。

价卡维护采用人工核对来源、有效期与费率后的保存/导入流程，导入须勾选确认。每次变更保存完整价格簿和稳定摘要；回滚先预览差异并确认，再追加新修订。最多保留 16 份且历史约 1.5 MB，先达到限制先淘汰并累计数量，可导出长期保存。历史收据 RPC 可传 `priceRevision` 重现尚保留的价格簿；保存的实验费用不会回写。不会把模板的创建时间说成在线价格核验。

AI 请求沿用浏览器生成的 progressId 作为稳定请求 ID。Host 在调用模型前持久化哈希预约，同 ID 重放/重连会被拒绝，不再次调用模型或入账；改变输入复用 ID 也拒绝。只保存 ID 和输入的哈希，不保存原始输入。最多 2048 个哈希、30 天，账本仍保留相同请求时也可阻止重复；超限数量披露。清空辅助账本保留这些有界去重哈希。无法持久预约的新格式请求会在调用前失败，以免重复费用。旧客户端不传 ID 时仍走原有单次调用内累计去重，不能承诺跨请求幂等。显式重新分析会生成新 ID。

实验新增请求次数、重试 Token、重试占比、活跃时长、工具计数及完整任务条件表。旧实验缺少分母时显示不可用，不补零。同一快照不能当成独立两次试验；不同快照也不是统计独立或因果证明。人工验收标签可后补，原使用量与事件 revision 不变。费用可比性按币种和价格簿指纹判断，缺少依据时不宣称改善。

跨时段试算提供基线/候选开始时刻、最长七天持续时间、缓存迁移比例和计费时点假设。默认未知计费时点，逐桶取整个覆盖区间的上下界，跨费率版本、工作日/周末和 DST 都纳入；费率缺口导致不可用/部分覆盖。选择开始或结束计费只是一项明确假设，不代替提供方计费证据。不会假设 Token 均匀发出或修改真实排程。

参考费用变化拆解使用两个完整周期末的 UTC 参考费率，依次替换路由用量、输入缓存结构、参考费率，三项差额与可定价子集的变化守恒。新路由的当前结构作为其起始结构；顺序影响归因。缺失费率和上下文证据时不输出全量金额结论，不能称为历史实付变化。

优化成果周报仅汇总候选生成日期在活动窗口内、条件配对、不同快照、完整数据且双方人工验收通过的实验；重复快照和无验收样本不纳入。展示 Token/重试减少量与排除数，负数如实表示增加，零合格样本不生成优化结论。活动周报仍有独立 v1 格式。`dsh-token-usage:summary-v2` 及对应 `summary-v2-request` 是新增事件，返回优化数字、预算状态和现有采样器的已确认输出速度；旧 summary 事件不改变形状。所有字段都是显式白名单，不含项目名、实验名、路由或正文。读取采样的时刻不是逐 Token 解码时间。

离线收据需显式点击保存，保存当前页元数据到本浏览器，最多 8 页/1 MB，淘汰数量可见；有清空确认。断开 Host 或会话索引不可用时仍能读取缓存。缓存不会更新，只能看已保存页，不能离线加载其他页或重新计算价格。损坏或禁用的 localStorage 明确报错，不自动清空。

固定 `a66e470…` 的 CI 继续是阻断型门槛。另有 **Advisory DSH compatibility** 通道，默认检查经记录的较新上游提交，也可手动选择 ref；运行记录包含实际 DSH SHA 和逐步结果。该通道不自动扩充插件的正式兼容声明，失败需要按真实日志判断。