前言¶
在 DeepSeek Harness（DSH）里跑智能体，模型调用会分散在普通对话、重试、上下文压缩和不同 provider 路由之间。provider 控制台能看到账单，但很难对照「哪次会话、哪条路由、压缩占了多少」；本地会话 projection 里也可能混着旧版无法按日归因的用量。若要在本机做预算预警、趋势对比或单会话轨迹审计，通常得自己写统计脚本，且很难与 DSH Web 设置页集成。
dsh-token-usage 是社区维护者 LeemanCheung 发布的 DSH 插件，在 Web profile 下被动观察 Host 侧事件，持久记录四类 Token bucket，并提供仪表盘、预算、公开费率估算、聚合导出，以及按需触发的 AI 用量分析与会话轨迹报告。插件当前在 GitHub 有 12 stars，SkillHub 分类为「记忆」。
这是什么¶
一句话定位：面向 DeepSeek Harness 的本地优先 Token 可观测性、预算与轨迹审计插件。
它解决的核心问题是：在不拦截模型请求的前提下，把未缓存输入、输出、缓存读取、缓存写入四类 bucket 记账到可恢复的会话 projection，并在 设置 → Token 用量 页面集中展示趋势、预算、效率指标与会话级下钻。USD 数字按内置静态公开费率估算，不冒充 provider 账单；AI 分析与轨迹报告须用户显式启动，且只发送有界聚合 DTO 或白名单轨迹元数据。
许可证为 MIT。完整说明见 GitHub 仓库 与 SkillHub 目录页。SkillHub 是独立社区目录，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
精确记账与多维聚合¶
Host 侧观察普通模型请求、重试和压缩事件，构建可恢复的会话统计 projection。reasoningTokens 已包含在输出中，不重复计算。流式 usage 先记为临时值，同一 attempt 内最终消息会覆盖它；重试与上下文压缩独立计数。可按 provider / model、会话与 UTC 日期聚合；旧用量无法归因时单独披露，不破坏总量守恒。
统计口径（摘自 README）：
| 指标 | 计算方式 |
|---|---|
| 输入 Token | uncachedInputTokens + cacheReadTokens + cacheWriteTokens |
| 总 Token | 输入 Token + outputTokens |
| 缓存读取占输入 | cacheReadTokens / 输入 Token（Token 结构比例，非请求级缓存命中率） |
| 压缩 Token | 所有 compaction/summary provider usage 的四个 bucket 之和 |
| 每次模型尝试 Token | (总 Token - 压缩 Token) / assistantRequests；重试算独立尝试 |
概览、趋势与活跃度¶
仪表盘提供八项概览指标：总量、输入、输出、缓存结构、公开费用、缓存读取避免费用、费率覆盖和有用量会话数。最近 30 周 UTC 日热力图支持四类 bucket 悬停与按日会话下钻。周期趋势可切换 7 / 30 / 90 日窗口，查看总量、环比、活跃天数与峰值日。
运行率、预算预测与异常检测仅在逐日 bucket 完整可靠时启用，避免旧版合成日期造成低估。运行率取最近 7 个完整 UTC 日（不含今天）的日均，乘以 30 得到滚动预测；异常检测将昨天与此前 28 日内至少 5 个活跃基线日的中位数 / MAD 比较，异常日可下钻会话贡献。
预算与 Agent 效率¶
滚动 30 日 Token 预算写入本机 DSH settings（token-usage.rolling30DayBudget）。预算开启且逐日覆盖完整时，界面显示消耗比例、按当前运行率的 30 日预测及可能超额提示；填 0 或清空可关闭。插件只展示证据，不会阻止模型调用。
Agent 效率区展示模型尝试数、每次尝试 Token、每 100 次尝试压缩数、压缩 Token 占比、缓存读取占输入、Top 1 / Top 3 路由集中度及未归因比例。
公开价格估算¶
成本按内置静态公开费率（USD / 1M Token）计算，当前 README 列出的匹配范围包括 OpenAI 侧 gpt-5、gpt-5-mini、gpt-5-nano、gpt-4.1 系列及 gpt-4o 等标签。界面标明费率基准日、Token / 路由覆盖与未覆盖项；未覆盖路由显示 —。
AI Token 用量分析（按需、opt-in）¶
用户从仪表盘选择目录预选的默认 / 首个路由，或改选任一当前可列出的已接入 provider / model，点击生成后才会调用模型。报告覆盖总量、压缩、缓存、路由贡献、可靠日趋势、峰值、波动与 Token 优化建议；按 Markdown 渲染并可导出。生成过程显示准备 / 生成 / 整理阶段；provider usage 到达前标注估算值，到达后切换精确值。模型目录可手动刷新；单个 provider 枚举失败不影响其他路由。聚合 AI 用量报告不会持久化。
会话轨迹分析¶
可从设置页会话列表或对话页标题操作区启动同一 Host 流程，支持 live 与冷会话。分析调用节点、重试、压缩、工具可靠性、速率、生命周期和 Token 对账，并含合规控制审计（审批请求与决定配对统计）。报告强制区分观测证据、风险假设与不可用证据。轨迹报告在当前浏览器 localStorage（键名 dsh-token-usage.trajectory-history.v1）中最多保存 24 条，界面按当前会话过滤并可删除。
聚合导出¶
可导出不含会话正文和标题的 JSON v2、每日 CSV 与模型 CSV。CSV 单元格防公式注入；JSON 与模型 CSV 带公开费率覆盖和已覆盖路由估算。
设计边界¶
- 被动账本：不拦截请求，不改写路由。
- 按需 AI：提示词、回复、标题、路径、工具参数和原始 provider / model 不会进入模型证据。
- 估算非账单：USD 与审批统计均不替代 provider 账单、策略执行或认证审计。
- 隐私：持久 projection 只保存统计数据；私有 RPC 仅允许 loopback 页面。
安装与启用¶
插件需要挂载完整 Client 服务的 DSH Web profile，依赖 DSH 0.1.0-rc.6 系列的 session、LLM、settings、projection 和 Web UI 服务。CLI 或非 Web profile 不提供仪表盘。
官方安装命令如下。安装后重启当前 dsh web 进程并刷新 http://127.0.0.1:3080，再打开 设置 → Token 用量。
dsh plugin --profile web add github:LeemanCheung/dsh-token-usage
本地源码开发时，可在插件目录上一级执行：
dsh plugin --profile web add ./dsh-token-usage
卸载命令：
dsh plugin --profile web remove dsh-token-usage
卸载后重启 dsh web 并刷新页面。卸载是移除插件挂载，不是数据重置；若要减少本地残留，可先删除轨迹历史报告、将预算清零，再按 DSH 自身 session / cache 策略处理 projection 数据。
典型用法¶
查看全局用量与趋势¶
- 完成安装并重启
dsh web。 - 打开 设置 → Token 用量。
- 在概览卡片查看总量、输入 / 输出、缓存结构与公开 USD 估算。
- 在 30 周热力图上悬停查看四类 bucket，点击方格下钻当天会话。
- 切换 7 / 30 / 90 日周期趋势，对照环比与峰值日。
设置预算并观察运行率¶
在 30 日预算区填入 Token 上限（写入 token-usage.rolling30DayBudget）。当全部纳入统计的会话都有真实逐日 bucket 时，界面会显示滚动消耗比例、按当前运行率的 30 日预测及超额提示。覆盖不完整时会标明相关指标不可用。
生成 AI 用量优化报告¶
- 在 AI Token 用量分析 区确认或刷新模型目录。
- 选择要用于分析的已接入 provider / model（默认使用目录预选路由）。
- 点击生成，等待准备 / 生成 / 整理阶段完成。
- 阅读 Markdown 报告，必要时导出。
选择的路由只在用户点击生成后调用；目录失败可重试，不会静默改用默认模型。
单会话轨迹分析¶
- 在会话记录表第一列点击轨迹分析，或从对话页标题操作区进入同一流程。
- 查看四组确定性摘要：调用节点、重试、压缩、工具与 Token 对账等。
- 导出报告或在浏览器本地历史中按会话过滤、删除旧报告（最多 24 条）。
导出聚合数据¶
在聚合导出入口选择 JSON v2、每日 CSV 或模型 CSV。导出内容不含会话标题与正文，适合外部分析或存档；注意 JSON / 模型 CSV 中的费用仍为公开费率估算。
适用场景与注意¶
适合谁
- 在 DSH Web 中长期跑智能体，需要本机 Token 结构、路由集中度与压缩开销的可视化。
- 需要滚动预算与异常日提示，但接受「仅展示证据、不拦截调用」的设计。
- 要对单会话做轨迹与审批事件审计，且愿意按需触发 AI 分析、接受白名单元数据边界。
使用前注意
- 插件以当前
dsh进程权限运行；安装前应阅读源码与 MIT 许可证，确认符合本机安全与合规要求。 - 仅 Web profile 可用；无 Web UI 的环境无法使用仪表盘。
- 旧版 projection 缺少逐日数据时，历史总量仍保留，但运行率 / 异常等口径会排除不完整日期。
- 公开费率表覆盖有限，未匹配路由的费用显示为
—；勿将界面数字当作 provider 账单。 - AI 用量分析与轨迹分析会向所选模型发送聚合或白名单数据；虽不含会话正文，仍属 opt-in 操作。
结尾¶
dsh-token-usage 把 DSH 本地的 Token 事件收成可恢复的 projection，并在 Web 设置页提供仪表盘、预算、导出与两类按需分析报告。若你已在 Web profile 下使用 DSH，且需要可下钻的用量账本而非事后查账单，可按上文命令安装并在 设置 → Token 用量 启用。
