dsh-token-usage

面向 DeepSeek Harness 的本地优先 Token 可观测性、预算与轨迹审计插件。
持久统计四类 provider Token bucket，提供趋势、预算、公开费率估算、聚合导出，并通过模型目录当前选中的已接入路由按需生成用量和会话轨迹报告。

功能全景 · 功能截图 · 安装 · AI 用量分析 · 轨迹分析 · 已知限制

截图采集自当前 DSH 界面；采集前已将用量、日期、路由与报告内容替换为明确标注的示例数据，不对应真实会话、模型配置或账单。

🗺️ 功能全景

该插件如何工作，以及不做什么

• 被动账本，不拦截请求：Host 侧观察普通模型请求、重试和压缩事件，构建可恢复的会话统计 projection；预算、异常和建议只展示证据，不会阻止模型调用或改写路由。
• 按需 AI，不是后台画像：聚合用量分析和单会话轨迹报告都必须由用户显式启动；前者只发送有界聚合 DTO，后者只发送白名单事件元数据。提示词、回复、标题、路径、工具参数和原始 provider/model 不会进入模型证据。
• 估算不等于账单或合规结论：USD 数字只按本地静态公开费率计算，报告中的审批统计也只陈述观测到的事件与证据缺口；两者都不替代 provider 账单、策略执行或认证审计。

🖼️ 功能截图

趋势、效率、运行率与预算

AI 用量分析入口与模型热点

选择的路由只在用户点击生成后调用；目录失败可重试，也不会静默改用默认模型。

会话轨迹报告与浏览器本地历史

轨迹截图使用示例会话指标，展示限制在视口内的滚动预览、完成态摘要、Markdown 表格与导出；继续向下滚动可查看浏览器本地历史，不对应真实会话内容。

🚀 安装

dsh plugin --profile web add github:LeemanCheung/dsh-token-usage

安装后重启当前 dsh web 进程并刷新 http://127.0.0.1:3080，再打开 设置 → Token 用量。

dsh plugin --profile web add ./dsh-token-usage

兼容性、存储与卸载

• 需要挂载完整 Client 服务的 DSH Web profile，并依赖 DSH 0.1.0-rc.6 系列的 session、LLM、settings、projection 和 Web UI 服务；CLI 或非 Web profile 不提供仪表盘。
• 数据分为三层：Host 的会话 projection 聚合统计、DSH settings 中的滚动 30 日预算（token-usage.rolling30DayBudget），以及当前浏览器 localStorage 中最多 24 条的轨迹报告（dsh-token-usage.trajectory-history.v1）。聚合 AI 用量报告不会持久化。
• 卸载是移除插件挂载，并不是数据重置流程。若要减少本地残留，请先在轨迹历史中删除报告、将预算清零，再按 DSH 自身的 session/cache 保留策略处理 projection 数据。

dsh plugin --profile web remove dsh-token-usage

卸载后重启 dsh web 并刷新页面；已有会话历史仍存在，但仪表盘和自定义分析入口需要重新安装此插件才能显示。

📊 仪表盘内容

• 概览卡片：总 Token、输入 Token、输出 Token、缓存读取占输入、有用量会话数，以及已覆盖路由的公开 USD 估算、缓存读取避免费用和 Token 费率覆盖率。
• Token 活跃度与下钻：最近 30 周按 UTC 日汇总的热力图；悬停方格查看四类 bucket，点击查看当天总量和贡献会话。旧版内置 projection 缺少逐日数据时，仍会以会话最后活动日保留历史总量，但该日期会从运行率/异常口径排除。
• 周期趋势：切换 7/30/90 日窗口，查看当前周期总量、环比、活跃天数与峰值日。
• 用量信号：仅在全部纳入统计的会话都有真实逐日 bucket 时，按最近 7 个完整 UTC 日计算日均和预计 30 日运行率；昨天的完整日会与此前 28 日至少 5 个活跃日的中位数/MAD 稳健基线比较，异常日可直接下钻会话。覆盖不完整时会明确显示不可用，而不是低估。
• 30 日预算：预算写入本机 DSH settings；逐日覆盖完整时显示滚动消耗比例、当前运行率的 30 日预测和可能的预测超额，填 0 或清空可关闭。
• Agent 效率与归因：显示模型尝试数、每次尝试 Token、每 100 次尝试压缩数、精确压缩 Token 占比、缓存读取占输入、Top 1/Top 3 路由集中度及未归因比例。
• 价格统计：显示已覆盖路由的估算 USD 成本、缓存读取避免费用、按 Token 计算的费率覆盖率，以及每条模型路由的估算成本；未覆盖路由明确显示 —。
• AI Token 用量分析：使用目录自动预选的默认/首个模型，或改选另一个已接入模型，按需生成总量、精确压缩开销、输入/输出/缓存、路由集中度、可靠日趋势、峰值、波动和 Token 优化建议报告。报告按 Markdown 结构渲染并可导出；生成中显示准备/生成/整理阶段、等待时间，以及估算或 provider 上报的精确输出 Token。模型目录可手动刷新；某个提供方暂时无法列出模型时，其他可用模型不受影响。
• 模型用量：按 provider / model 汇总普通模型尝试、上下文压缩次数、总量、输入与输出；可按总 Token、已覆盖的估算费用、每次记录调用 Token 或缓存读取占输入排序。
• 聚合导出：导出不含会话标题和正文的 JSON v2（含压缩 bucket、公开费率覆盖和路由估算）、每日 CSV 或模型 CSV；模型 CSV 含已覆盖路由的费用/缓存避免费用，CSV 单元格防公式注入。
• 会话记录：轨迹分析操作位于表格第一列；可搜索会话标题、会话 ID 或模型路由，初始最多显示 50 条并可渐进展开，也可直接打开会话。

统计口径

同一请求步骤若先后出现流式 usage 与最终消息 usage，最终值会替换该步骤的临时值，避免重复记账；发生 llm/retry 后，每个重试尝试仍会被独立统计。每条 compaction/summary 都计为一次压缩；provider 未附 usage 时只增加次数，不虚构 Token。带 surfaceOp: replace 的消息只改写可见会话表面，不代表新的模型或工具执行，因此不会重复计数。

📈 运行率、异常与 Agent 效率

• 运行率：仅在逐日覆盖完整时，使用真实逐日 bucket，并取最近 7 个完整 UTC 日（不包含尚未结束的今天）计算日均，再乘以 30 得到滚动 30 日预测；它是 Token 运行率，不是账单预测。
• 预算预测：仅在已开启 Token 预算时比较预测值和预算。当前已超额与“按当前运行率将超额”会分别提示，不会自动阻止模型调用。
• 异常检测：将昨天这个完整 UTC 日与此前 28 日内的活跃完整日比较。至少需要 5 个活跃基线日；使用活跃日中位数和 MAD，MAD 为 0 时采用 3×中位数阈值。异常提示会显示绝对超量和倍数，并可下钻现有的按日会话贡献。
• 效率/集中度：Top 1/Top 3 是全部 Token 的路由份额；未归因用量会单独披露。每次模型尝试 Token 从可归因总量扣除精确压缩 Token 后计算，重试属于独立尝试。
• 会话工作流：会话名称可直接打开当前仍在列表内的会话；若会话在点击前消失，保持设置页面并显示失败原因。初始列表只渲染 50 行，聚合统计仍覆盖全部会话。

💵 公开价格统计

成本是静态公开费率估算，不是 provider 账单。内置表以 USD / 1M Token 计价，当前按精确 provider: 'openai' 与 model 标签匹配：gpt-5、gpt-5-mini、gpt-5-nano、gpt-4.1、gpt-4.1-mini、gpt-4.1-nano、gpt-4o 和 gpt-4o-mini（及列出的 API 版本别名）。费率依据 OpenAI 官方 API Pricing，表内最近基准日为 2025-08-07，不会联网实时刷新；标签匹配不能验证实际端点、转售关系、合同或账单。

估算 USD = 未缓存输入 × inputRate
         + 输出 × outputRate
         + 缓存读取 × cacheReadRate
         + 缓存写入 × cacheWriteRate
         ÷ 1,000,000

• 仅当 provider 和 model 标签均精确匹配内置表时才计价，不借用相似模型价格；匹配结果仍可能对应代理或自定义端点，因此必须结合实际账单核验。
• 费率覆盖率按已匹配路由的四类 Token / 全部四类 Token 计算；未覆盖 Token 不进入估算总额，页面会同时显示覆盖 Token 和有用量路由数，部分覆盖不会四舍五入为 100%。它不是实际消费金额覆盖率，不能据此外推未知价格。
• 缓存读取避免费用仅对已匹配路由计算：cacheReadTokens × max(inputRate - cacheReadRate, 0) / 1M；它比较同一静态公开表中的未缓存输入价，不是账单返还。
• OpenAI 路由没有单独公开的 cache-write 费率时，cache-write 按普通输入费率估算；每条路由的悬停说明会显示所用四项费率与基准日。
• 历史聚合会按当前内置静态表重估，不按事件发生日的历史价格还原；因此暂不提供 USD 预算。
• 价格计算、页面展示和 JSON v2/模型 CSV 只在本地浏览器中使用已持久化的聚合 bucket；价格匹配、覆盖率、估算 USD 和缓存读取避免费用都不会作为外部分析模型的证据，也不会新增会话正文、提示词或响应数据的收集。

🤖 AI Token 用量分析

在仪表盘的 AI Token 用量分析 卡片中，目录会自动预选默认路由或首个可用路由；可直接使用，也可改选另一个当前已接入且可列出的 provider/model，再点击 生成用量分析。可使用 刷新模型目录 重新读取实时路由；当前选择也用于下面的设置页会话轨迹分析，但每次分析仍需单独触发。目录仅负责选择和展示，真正生成时仍由 Host LLM adapter 校验路由。查看界面截图。

报告固定覆盖：

聚合数据、隐私与费用

• 用量分析只发送总 Token bucket、精确压缩 Token bucket、报告内 route-N 别名、对话/压缩次数和可靠的 UTC 每日 bucket；本地价格匹配、覆盖率、估算 USD、缓存读取避免费用和路由成本均不发送。原始 provider/model、会话 ID、标题、提示词、回复、工具参数或其他会话正文同样不会发送。
• 模型证据最多保留 Token 最大的 48 条路由记录与最新 366 条日期记录；总量仍来自完整仪表盘聚合。
• 报告和辅助调用用量仅驻留当前页面内存，刷新后消失，不进入会话日志或 projection cache；用户可显式下载 Markdown 报告。导出文件名只包含报告类型和 UTC 生成时间，不使用会话标题、会话 ID 或模型返回内容。模型 Markdown 通过 DSH 安全渲染器展示，远程图片语法在页面和导出文件中都会退化为普通链接，原始 HTML 会转义为文本，避免自动发起外部资源请求。
• 用户选择的 provider/model 会实际产生一次辅助模型调用；生成中显示阶段、等待时间、流块、字符数和明确标注的估算输出 Token，收到 provider usage 后改为精确值；完成报告继续显示调用 provider/model、辅助调用总 Token 与模型输出 Token。用量分析最多生成 2,600 Token。
• 目录只显示已接入且当前可列出模型的路由。单个提供方的目录失败不会隐藏其他可用路由，页面会披露受影响的提供方但不暴露适配器错误细节；调用失败时不会悄悄改用默认模型。
• 目录用于用户选择和展示；实际调用以 Host LLM adapter 的 prepareCall 为准，因此目录刷新与调用之间消失的路由会得到适配器的明确失败，而不是先被过期目录拒绝。

🧠 会话 Token 轨迹分析

可在设置页 会话记录 第一列点击 分析轨迹，也可在对话页会话标题操作区点击 会话 Token 轨迹分析。两个入口调用同一 Host 分析流程：读取 live 会话完整事件日志，或通过 sessionPersistence.inspect() 读取冷会话；浏览器分页不会影响结果。分析器先做确定性 fold，再使用当前入口选中的已接入 provider/model 生成报告；设置页沿用仪表盘选择，对话页拥有独立选择器，两者都会自动预选默认或首个可用路由。查看完成态与历史截图。

确定性证据

读取旧版 v1/v2 轨迹报告时，已有的审批请求数与拒绝数仍会展示；只有 v3 新增的闭环、分类结果和审计缺口字段标为不可用，不会用零冒充确定性证据。

当前 provider 只提供未缓存输入、缓存读取、缓存写入和输出四类实际值。系统指令、用户输入、历史、检索、工具结果和子代理结果的细分归因标为不可用；插件不会读取正文进行估算，也不会把估算值伪装成实际值。

模型报告结构

完成态先展示四组本地确定性摘要，再渲染模型 Markdown。模型被要求固定覆盖九个部分：资源摘要、调用链与用量节点、Token 对账与构成、合规控制与审计边界、重试与失败、速率与上下文效率、工具与压缩成效、异常模式，以及 3–7 条 P0/P1/P2 分级建议。重要结论必须引用事件 seq、span ID 或确定性指标；截断数据必须标为不可用，不能从缺失正文推断身份、意图、策略违规、质量或成本。

输入、隐私与费用

• 分析由用户显式触发。报告不写入会话日志或 projection cache；成功结果的完整分析对象会进入当前浏览器 localStorage，包含 sessionId、所选分析 provider/model、确定性 metrics/spans 和模型报告，但不含会话标题或正文。每个浏览器配置跨全部会话全局最多保留 24 条，序列化总量不超过 3,000,000 字符，超限时淘汰最旧记录；若单份报告本身已超限，它仍可在当前界面查看和导出，但不会持久化。历史界面再按当前会话过滤，重新打开只读取本地报告、不重复调用模型；可删除并可导出不含会话标题/ID 的 Markdown。损坏时间戳或无效 schema 会被忽略，损坏 JSON 会清理后恢复；浏览器禁用或耗尽本地存储时会明确提示，当前报告仍可查看和导出。
• 发送给模型的事件只允许：内置事件类别与序号、相对时间、turn/step、报告内 route-N 别名、符合受限标识符规则的工具名称、审批结果、重试序号/上限/等待、通用成功或错误状态、表面改写标记以及 Token bucket；未知扩展事件会省略。
• 提示词、回复、system prompt、会话标题/ID、原始 provider/model、工具参数/结果/meta、审批原因与 ID、故障代码与错误消息，以及路径和 URL 字段、邮箱、姓名、个人字段和组织字段不会进入模型证据；这是 allowlist 省略，不依赖正则脱敏。允许的工具名称是独立的受限标识符，可能包含 /，不能将其误解为“任何看似路径的工具名都被移除”。
• 完整模型证据最多 96,000 字符；完整节点表留在本地，模型只接收最大节点、最多 16 个高消耗重试节点和有界首尾时间线，超限时插入截断标记。模型最多生成 3,000 Token。
• 生成中显示准备/生成/整理阶段、等待时间、流块、字符数和输出 Token 进度；usage 到达前的 Token 数明确标注为估算，provider usage 到达后使用精确值，完成态同时显示辅助调用总 Token 与模型输出 Token。关闭对话页分析弹窗会中止仍在运行的请求，避免后台继续生成；辅助调用用量不会计入持久化用量 projection。
• 报告使用 DSH Markdown 组件安全渲染，把远程图片语法降级为普通链接并将原始 HTML 转义为文本；四个紧凑摘要面板分别汇总生命周期、工具可靠性、合规控制和资源效率。对话页预览采用中等宽度与视口内高度上限，长报告在正文区域滚动，底部关闭操作保持可达。
• 私有 RPC 只允许本机 loopback Web 页面调用；分析必须使用当前选择器中的目录路由（自动预选或用户改选），不会在生成阶段隐藏地回退到另一模型。目录枚举与生成调用都绑定当前 LLM service 生命周期，服务移除或替换时会立即停止等待。Client 会在渲染前验证 provider 总量、节点归因、signed delta、状态和最大节点引用的一致性。

🧭 数据流

flowchart LR
  A[DSH session log] --> B[Token usage projection]
  B --> C[Session projection cache]
  C --> D[Settings · Token 用量]
  D --> E[概览、趋势、预算与导出]
  D --> F[30 周热力图与会话下钻]
  D -->|显式触发| G[确定性用量节点与对账]
  G --> H[白名单元数据 DTO]
  D -->|显式触发| J[聚合用量 DTO]
  H --> K[当前选择器中的已接入模型]
  J --> K
  K --> I[安全渲染的 Markdown 报告]
  I -->|显式操作| L[Markdown 导出]
  I -->|仅轨迹报告| M[浏览器本地历史]

• Host 侧监听普通模型请求、重试和上下文压缩事件，构建会话级持久 projection。
• 历史会话在后台按顺序预热；冷会话在恢复期间重新附着时，会重新写入最新 live checkpoint，避免回退缓存水位。
• Web 侧将所有会话 projection 聚合为仪表盘数据。较旧的内置 projection 会显示为“未归因用量”，以保持总量守恒。
• 两类 AI 分析都走 loopback 私有 RPC，并只接受用户从已接入模型目录中选择的路由：用量分析只传聚合 DTO；轨迹分析由 Host 读取权威事件日志、构造内容无关的实际用量节点和有界白名单 DTO。Web 通过短轮询读取请求级进度，只接收标量进度、JSON 指标和 Markdown 报告；分析结束后 Host 立即移除进度记录。

🔎 设计参考与取舍

本插件吸收了主流 Agent 可观测性产品对 Token、成本、缓存和聚合趋势的做法，例如 LangSmith cost tracking、OpenAI Agents SDK usage、Langfuse token/cost tracking 和 Phoenix LLM metrics。预算和异常部分参考 FinOps Budgeting、Anomaly Management 与 MAD 的稳健统计定义。

取舍是有意的：Host projection 只持久化聚合 bucket、日期、计数和路由归因；聚合 AI 报告只在当前页面内存中，用户显式生成的轨迹报告才进入当前浏览器 localStorage。插件不保存请求正文、逐请求正文日志、日期×模型交叉明细或人员/组织归因。现有投影没有日期×模型维度，因此异常日只支持会话贡献下钻，不声称模型级日归因。

🔄 更新与热加载

🔧 排障

🛠️ 开发

本项目当前以 GitHub 源码插件形式分发，不发布到 npm。源码与 DSH checkout 并排放置，tsdown.config.ts 复用 DSH 的官方 Client bundle preset。

开发命令依赖 DSH workspace 提供的 TypeScript、Vitest 和 tsdown；该私有源码包本身没有声明这些 devDependencies。若脱离 DSH workspace 开发，需要自行安装兼容版本后再运行：

npm test
npm run typecheck
npm run build

构建产物为 lib/index.js 与 lib/client.js，已提交到仓库，确保可直接通过 GitHub 安装。

测试与费率维护边界

自动化覆盖 projection、聚合、分析/RPC、报告安全、浏览器历史和组件行为，但不是完整的 DSH Web E2E。真实 profile 的安装激活、HMR、Slot/RPC/Schema 版本互操作、英文文案/CSS/reduced-motion 视觉，以及历史预热的全部 fail-soft 分支仍需要人工或浏览器 E2E 验证。费率测试覆盖代表性条目而非完整公开价格目录；修改 src/pricing.ts 的任一行时，应逐项复核公开来源、更新基准日/README，并在发布前完成真实 Web profile 验证。

⚠️ 已知限制

• 历史预热依赖 DSH session projection cache。预热完成前，仅有内置 projection 的旧会话会被显示为“未归因用量”；刷新后可读取新的模型明细。
• 单个损坏或不可读取的历史会话只会记录警告，不会阻止插件启动。
• 热力图按持久事件的 UTC 日期统计；旧版内置 projection 缺少逐日数据时，会暂按会话最后活动日归档。
• 运行率和异常检测会排除上述旧版合成日期，只使用真实逐日 bucket；覆盖缺失或仅部分可靠时都会显示不可用，而不是以不完整数据给出偏低结果。异常检测需要昨天有记录且此前 28 日至少 5 个活跃日，不足基线时不报告“正常”。预测和异常不会做模型级逐日归因。
• 轨迹报告是模型辅助的资源效率解释，不是策略执行器或合规证明；确定性节点、provider bucket 和对账结果优先于模型推断。
• provider 当前不提供系统、用户、历史、检索、工具和子代理输入的独立 Token bucket，因此这些细分不会估算；超长元数据轨迹的中段会明确标为不可用。
• 插件不建设人员、团队、部门、组织、成本中心或行为画像维度；AI 用量报告刷新后消失，轨迹报告只保存在当前浏览器配置中、跨全部会话全局最多 24 条，不跨浏览器同步，也暂不生成历史趋势对比。
• 分析调用的 Token 在生成进度和完成报告中显示，不计入持久化仪表盘。provider usage 到达前的输出 Token 是基于字符的近似值，不可用于账单。
• AI 用量分析只可选择当前能由已接入 provider 列出的模型；每日趋势证据最多传递最新 366 天。内置 USD 费率表不是实时账单或汇率服务，仅按文档列出的 OpenAI 路由标签本地匹配；模型建议不接收价格证据，也不替代账单、延迟或质量观测。

📄 License

MIT © LeemanCheung