dsh-plugin-token-report

实际使用截图

以下截图来自 2026-09-25 本机运行的 DSH Web 与真实会话日志，仅截取插件区域。数值是该机器当时的用量，不是模拟数据，也不代表性能基准。

用量概览与模型明细

点击输入框上方 TOKEN 用量 条里的「详情」，即可查看计费总量、未缓存输入、输出、缓存读、缓存命中率、调用数和会话数。趋势支持切换 Token 总量、调用数与命中率，明细支持模型、服务商、项目和会话分组，点击行可展开，超过 10 行可翻页。

自定义日期范围

除了今天、昨天、本周、最近 7 天、本月、近 30 天和今年，还可以通过双月日历选择开始与结束日期。开始与结束日期既可以点日历选，也可以直接敲进输入框（2026-09-21、2026/9/21、2026年9月21日 都认，失焦后统一成 2026-09-21）；格式不对、日期不存在或开始晚于结束时，标题右侧会说明原因，「应用范围」只在区间可用时才可点。范围按本地时区计算，包含起止两天，点击「应用范围」后更新统计；生效期间按钮上直接显示所选区间（如 09-12 – 10-06）。

第一次使用

1. 打开「详情」，选择需要查看的周期。首次建立索引可能需要十几秒，后续只增量读取变化的日志。
2. 切换趋势指标或明细分组查看用量来源。图表下方「查看图表数据」提供精确值。
3. 手动点击刷新即可读取最新数据；页面每 3 秒问一次「有没有新数」（没有就零成本）， 有新采集时按宿主缓存节奏（最多 30 秒）自动更新；切回前台标签页会立刻取一次。

仅查看本机统计不需要署名。未署名时，插件不采集上报事件，也不上报。 页面读取的是 DSH 已有的本机会话日志。

多套 DSH 并存（DSH Desktop / 命令行 / 第三方客户端）

一台机器上同时装着多套 DSH 时（命令行版 ~/.dsh、DSH Desktop 的 %APPDATA%\dsh-desktop\harness……）， 插件缺省把它们的会话日志一起统计。发现是结构驱动的 —— 候选目录里只有真的有 sessions 子目录 的才算一个根 —— 所以面板上的数字是多套 DSH 的并集，接入新的第三方客户端不需要改配置。

两套 DSH 的会话经常互为镜像（同一份日志被两边各记一份）。镜像按 event_id = : 去重、 只算一次，所以「并集小于各自相加」是正确结果，不是漏扫。启动日志与 token_usage_diagnostics 会逐一列出这次实际读到的根 —— 「我的数据到底读了哪几处」不会只给一个数字。

署名、连接配置与本地索引库都在同一个「数据目录」里，缺省 ~/.ai-token-report/，它与会话日志根无关， 所以多套 DSH 缺省就共用同一份身份与配置，Desktop 里不会再出现「尚未署名」，不需要任何配置：

/identity.json            ← 署名（token 就是 appKey）
/plugin-connection.json   ← 面板里填的服务端地址 / appKey / 间隔 / 位置 / 会话日志根
/usage.sqlite             ← 本地增量索引库（日志的派生物，可删可重建）
/outbox/                  ← 磁盘 outbox（崩溃不丢数据）

只有两种情况才需要动配置：想钉住统计范围（只看其中几处）用 dshHomes —— 面板里就能改（齿轮「配置」→「会话日志根」，保存即生效），也可以用部署配置 dshHomes 或环境变量 DSH_TOKEN_REPORT_DSH_HOMES 统一钉死； 想让某套 DSH 单独用一份身份 / 库用 dataDir（对应环境变量 DSH_TOKEN_REPORT_DATA_DIR， 只能在部署配置 / 环境变量里给 —— 换掉它等于连身份 / 库 / outbox 一起换，会让人「突然变成另一个人」）。

🚨 不要用日志根去达到「分开身份」的目的：dshHome / dshHomes 换掉的是日志来源， 那会让面板少算另一套 DSH 的会话，而实时上报照常工作 —— 这个错误不会以「完全没数据」的形式暴露。

别的 AI 客户端也算（缺省就是全算）

面板、token_usage 工具与上报都覆盖本机全部已注册来源：DSH、Codex、Claude Code、 Trae（国际版 trae / 国内版 trae-cn，两个发行版算两个来源）、WorkBuddy。 没有开关要打开 —— 本机装了哪个客户端，它的用量就进面板、也会进部门看板； 没装的那些自然不会出现（诊断里会逐项报出解析到的根）。

代价必须知情：第一次取数与第一轮历史补报要冷扫这些日志（本机实测 Codex 就有 1,500 个文件 / 2.8 GB，十几秒到几分钟），之后按文件字节数增量，只解析变化过的文件。 嫌慢就把那个客户端的日志目录挪走，或者用它自己的环境开关关掉 （例如 DSH_TOKEN_REPORT_CODEX=0）—— ⚠️ 这一项刻意不在面板里： 「我不想统计 Codex」是一件部署策略级的事，不该和「我的服务端地址」放在同一个表单里。

为什么不再做成「白名单」：少统计一个来源没有任何下游信号 —— 面板数字看着完全正常， 而它与「我在那台客户端上本来就没用量」长得一模一样。采集范围不是性能偏好，是一句会被读成结论的口径。

调整面板位置

面板默认出现在输入框上方。想让它出现在会话标题栏右上角、或两个位置都要， 有两种办法 —— 面板内改（推荐，立刻生效），或在 profile 里改部署配置。

办法一（0.6.0 起）：面板右上角齿轮「配置」→ 面板位置 → 验证并保存。 保存后面板就地换地方，不必刷新页面、更不必重启 DSH：

取值	效果
输入框上方（用量条）	只显示输入框上方的用量条（默认）
会话标题栏右上角（胶囊）	只显示标题栏右上角的胶囊；点开就是同一个详情面板
两处都显示	两处都显示 —— 与 0.2.0 的外观一致

这一项与下面「部署配置」写的是同一个东西，只是存在本机 （/plugin-connection.json，缺省即 ~/.ai-token-report/，见上方「多套 DSH 并存」），并且优先于部署配置。

办法二：在 profile 的 cordis.patch.yml 里给插件加一段 ui —— 适合「IT 统一规定全公司都用某个位置」：

- id: token-report
  config:
    ui:
      position: dock      # dock(默认，输入框上方) | header(右上角) | both(两处都要)

改完刷新页面即可生效。三种取值共用同一个详情面板，数字口径完全一致。 也可以不改 YAML，用环境变量 DSH_TOKEN_REPORT_UI_POSITION 临时覆盖。

写错的值不会让面板消失：只认上面三个值，其它一律回退 dock，并在 DSH 启动日志里告警。 面板内那一栏同样只提供这三个值，选不出非法值。

开启团队上报

在详情面板右上角点击齿轮「配置」，五个字段：

字段	说明
服务端地址	部门平台根地址（例如 https://portal.example.com，或本机自建的 http://127.0.0.1:8787）。上报地址由它推导（/api/v1/token-usage），不需要自己拼路径
appKey	管理员在平台「appKey 管理」页签发的那一串。已配置时留空 = 只改下面各项偏好，不会重新校验、也不重写身份文件
上报间隔	5 秒 / 10 秒（默认）/ 30 秒 / 1 分钟 / 5 分钟。这个数字直接决定部门服务端的请求密度，所以只给档位
面板位置	见上一节；保存后就地换地方
会话日志根	每行一个 DSH home；留空 = 自动发现。见上方「多套 DSH 并存」

点击「验证并保存」后，插件用这个 appKey 向对应服务端的 /api/v1/identity/verify 校验身份， 姓名与分组以服务端返回值为准（面板不再询问姓名 —— 它由 appKey 在服务端绑定的人决定）。

★ 保存后立即生效，不需要重启 DSH。 保存成功后页面会如实回报当前状态 （「已保存并开始上报 → 地址」或「上报仍未启用：原因」），并当场开始补报本机全部历史用量。 已保存的 appKey 不回显。

看「到底上报了什么」（上报调试）

配置页第二个页签 「上报调试」 是排查「部门看板上没有我的数」的地方。 它每 3 秒刷新一次，把下面这些一次说清：

• 在不在上报：状态 + 地址；没在跑时给原因（未署名 / 未配 appKey / 部署关闭了上报）。
• 发了多少：已采集、已投递（含重复与拒收）、内存队列、磁盘待投递（批数 / 条数 / 字节）、 请求数与失败数、最近成功时间。
• 最近上报：每次真实请求的请求体原文（点开可展开）+ 服务端回执 （接收 / 重复 / 拒收）与 HTTP 状态。请求体过大时只显示开头，并明确标注「已截断」。
• 历史补报进度：扫描文件数 / 服务端确认数 / 上次错误。
• 两个按钮：「立即上报一次」（真发）与「预览下一批内容」（只显示，不发送、不消耗队列）。

🚨 页面里看不到 appKey。 调试数据由宿主半的 GET /api/tokenReport.reports 提供， 而宿主只保留请求体、不保留请求头 —— appKey 走 Authorization: Bearer，天然不在这里。 不要为了「方便排查」把请求头加进去：那会把一个调试页变成凭证泄漏面。

身份与连接保存在数据目录下（缺省 ~/.ai-token-report/；DSH Desktop 与命令行版缺省就共用同一份、不需要任何配置，见上方「多套 DSH 并存」）。插件与本地 Web 共用身份文件。部署侧固定了身份时，页面会提示配置由管理员管理。

启用上报后，插件会在后台扫描上面那些会话日志根（缺省是本机全部 DSH home）以及本机全部已注册来源（Codex / Claude Code / Trae / WorkBuddy）下的全部历史会话，分批补报用量，直到服务器全部确认收到；不需要逐个打开旧会话。实时新用量同时上报，服务端按事件 ID 去重。断网或退出后，下次启动会继续；更换服务端地址或 appKey 后，会向新连接重新全量补报。

历史补报只发送 token 数值、模型和会话归属等统计字段，不发送对话正文。token_usage_diagnostics 会显示历史扫描进度、服务器确认数、重试错误和最近完成时间。对照本地与部门看板时，请选择相同时间范围并筛选 appKey 对应人员。

DSH 升级会保留旧格式日志作为备份；同一会话存在多个规范格式版本时，统计与补报都只读取最高版本，与 DSH 自身一致，避免事件重编号后重复计费。历史补报不会自动删除服务器上的旧数据；已由旧版本重复上报的记录需先对账、备份，再单独修复。

让 Agent 查询

可以在 DSH 会话里要求：

调用 token_usage，查看我今天的 token 用量，按模型分组。
调用 token_usage，查看最近 7 天的用量，按天显示趋势。
调用 token_usage_diagnostics，检查上报是否成功、是否有待发送数据。

工具注册需要宿主提供对应能力并启用 features.tools。查询工具只读本机日志，本身不产生上报。

1. 一份全局配置

团队铺开时，每个人机器上的差异应当只有「身份」一项。其余全部来自同一份下发配置：

# ④ 删掉插件产生的数据（state.json / usage.sqlite 是本地页与 CLI 的，按需保留）
Remove-Item "$env:USERPROFILE\.dsh\token-report\outbox" -Recurse -Force