@fufuf-c/dsh-token

dsh plugin --profile web add @fufuf-c/dsh-token

dsh-token


DSH 本地 Token 用量统计插件——以 Token 为第一视角:不只回答"花了多少钱、用了多少量",还回答 Token 从哪来、缓存省了多少、哪些会话在烧 Token。数据全部来自本地会话日志,零上传、无在线依赖。仪表盘为 Apple 风格四 Tab 界面,开箱即用。

亮点

• 四段 Token 构成:未命中 / 缓存命中 / 缓存写入 / 输出,并给出缓存省下的钱;
• 成本诚实:无内置价且无自定义价的模型成本计 0,但 kpi.totals 显式报出

unpricedTokens / unpricedModelCount,界面与导出都标注"未计入" ——

估算成本是"已定价部分的成本 + 未定价 token 数",不是完整账单;

• 全局筛选:时间(今天/3天/7天/30天/自定义)+ 模型 + 会话 + 工作目录,URL 可分享;
• 会话下钻:四联统计、逐模型构成、逐请求明细、上下文增长曲线、🔥 异常激增标记、?session= 深链;
• 成本与预算:单价表(内置 DeepSeek 官方价目,高峰/空闲分档,时段可改)、月度预算

环形进度 + 月底外推 + 80%/100% 阈值、按模型/按会话归因;

• 图表:多模型叠加趋势(图例可逐个关)、日/周/月粒度、24 桶小时直方图、活跃度月历热力图;
• 快路径聚合:无 session/wd 筛选时查询读 day/month 聚合索引,复杂度 O(天数);

带这两个筛选时整会话跳过(它们是会话级前缀判定)。两条路径输出等价由单测锁定;

• 落盘分片:store.json 只存元数据,逐会话记录在 shards/;分片自带模型表,

局部重写不会让整数下标错位;单会话损坏只影响它自己;

• 增量扫描:未变化会话按 revision 跳过;扫描周期无变化时跳过重建与落盘;

retention.days 修剪超龄记录,默认 0 = 永久保留;

• 刷新可配:refresh.pageSec(页面重取,默认 60s)、scanSec(后台重扫,默认 300s)、

onOpen(进入界面先扫一次,默认开);填 0 关闭;

• store 损坏不静默清零:形态体检不合格就改名 store.json.corrupt-<时间戳> 留证再从日志重建;
• 跨 DSH 版本自适应:sessionPersistence 两代 API 按能力探测适配,不绑宿主版本号;
• 失败会话隔离:被宿主确定性拒绝的老日志在冷却窗口内跳过,瞬时错误始终重试。

性能与实现取舍的逐条论证见 scripts/invariants.mjs(95 条编号不变量,

每条写明"锁什么、为什么、被哪个测试锁住")。

界面

六个视图,截图取自一份全虚构的示例库(18 个会话 / 474 次请求,由

scripts/screenshot-harness.mjs 用固定种子生成),不含任何真实使用记录。点图看原图。

图片挂在 Release 资产上而不是用仓库相对路径:README 同时是 npm 页,相对路径在

npmjs.com 上会裂图,而 raw.githubusercontent.com 在部分网络环境下不可达。商店侧

以仓库里的 screenshots.json 为准,与这里无关。

<br>今天 · 四段构成与小时分布 · <br>活动 · 趋势 / 逐模型 / 粒度切换

<br>会话 · 排序 / 搜索 / 激增标记 · <br>会话详情 · 指标 / 构成 / 增长曲线

<br>逐请求时间线 · 明细表 · <br>设置 · 预算 / 单价 / 高峰时段

架构

web/index.html       **拼接产物**(交付物)仪表盘单页 · Apple 风格(默认页;四 Tab:iOS 大标题 / 玻璃材质 /
                     活动圆环 hero / 屏幕使用时间式图表;纯原生 JS + Canvas,单文件无外部资源)
lib/client.js        宿主直供的浏览器模块(`exports["./client"]`,手写、不经打包器):
                      四个入口 —— 侧边栏「Token 统计」= 全局面板(应用内整屏仪表盘,
                      注册在 sidebar.panellist + main,本体是 iframe 嵌 /dsh-token),
                      会话内「本会话用量」= 原生 React 单会话面板(不是 iframe),
                      设置页「Token 统计」= 插件信息面板。
                      只 require 平台种子模块 react(宿主模块表提供,非 npm 依赖)
lib/core.mjs         数据层核心(**纯数据**:store 进、结果出,不碰文件也不认识 Cordis 服务):
                      折叠、聚合、筛选、导出、价格、异常检测、
                      会话标题提取(session/title → 首条用户消息回退)、
                      day/month 聚合快路径(O(天数) 查询)+ 惰性重建、store 形态体检
                      (聚合运行时状态挂 store 的**非枚举**字段 `__agg`,单一入口 `aggState(store)`,不落盘)
lib/session-source.mjs 会话日志读取与扫描层(唯一需要 sessionPersistence 服务的一层):
                      sessionPersistence 新旧两代 API 适配、增量水位线、
                      确定性失败会话隔离 + retention 修剪
                      (依赖方向:index → session-source → core;core 不认识前两者)
lib/design-tokens.mjs 设计 token **单一来源**:两处界面的调色板/语义色/文本色/阴影
                      由 scripts/build-tokens.mjs 注入 web/src/style.css 与 lib/client.js
                      (**注入源文件**,再由 build-web 带进产物),LOCAL 里显式登记"有意不一致"的项
                      **仅构建期使用**:不在 package.json 的 files 里,运行时无任何 import
                      (由 V63b 守卫 —— 运行时 import 它会让用户侧 MODULE_NOT_FOUND)
scripts/invariants.mjs **不变量登记表**:112 条防退化守卫的"锁什么 / 为什么 / 被哪个测试锁定"
                      (V1–V73e),机器可读。test/invariants.test.mjs **双向强制**:
                      登记了没测试 → 失败;有 V 编号测试没登记 → 失败;缺号必须在 GAPS 里解释
scripts/web-parts.mjs 网页源文件的拼接清单(按序排列的文件名)
scripts/build-web.mjs 把 web/src/** 拼成 web/index.html;--check 逐字节校验(漂移即失败)
web/src/**          仪表盘源文件(HTML 外壳 + style.css + app/*.js 共 20 份)
web/index.html      **拼接产物**(交付物):仪表盘单页 · Apple 风格
lib/index.js         Host 插件外壳:扫描(sessionPersistence)、/dsh-token 路由、
                      /token-stats 命令、5 分钟增量扫描(无变化不落盘)、
                      页面缓存(按 mtime+size+外观偏好失效)+ gzip、发送时注入外观偏好、
                      POST 同源校验 + 1MB body 上限、
                      store 形态体检与损坏留证、启动自检;
                      **store 载入与分片读取为异步**(0.9.4,并发 8),
                      查询入口有空库兜底(载入完成前不返回 500)
test/                node:test 断言(397 项):数据层、价格/时段、扫描与隔离、客户端注册、
                      页面渲染、宿主语义(时区口径/未定价/惰性重建/store 体检)、
                      界面回归(配色按模型名稳定/占比口径/单桶趋势/监听幂等/自定义范围)、
                      设计 token 一致性与引用闭合、宿主适配不回退
                      (面板必须"接"宿主字体族/正文字号/底色,不允许抄成固定值)、
                      画布绘制(2D 调用序列录制:渐变档位/路径闭合/坐标有限/同输入可复现)、
                      **结构化转义**(tpl/raw 语义 + 恶意输入实测 + 源码级裸拼接守卫)、
                      **异步载入与分片重建的等价性**(与同步路径逐字段相同)、
                      **不变量登记表强制**(登记 ↔ 测试双向一致)
scripts/build.mjs    发布前完整性校验(文件、dsh 字段、各模块可解析、内联脚本语法)
scripts/build-tokens.mjs 设计 token 注入器(`--check` 用于 CI/测试,漂移即失败)
scripts/e2e-smoke.mjs 真实 http 栈端到端冒烟(零依赖,临时 DSH_HOME;含外观偏好注入与
                      「偏好进页面缓存键」:只改设置、不动页面文件,注入值也必须立刻换新)
scripts/verify-

…(truncated)