dsh-token-usage-ledger 0.0.36 → 0.0.44

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -3,6 +3,106 @@
3
3
  版本号约定:`v0.0.<序号>`(纯 SemVer,**不带日期后缀**;历史条目里的 `-yyyyMMdd` 是旧格式,保留原样不会重复发布)。
4
4
  `package.json` 的 `version` 写 SemVer 合法形式(`0.0.36`,不带 `v` 前缀)。任何变更只递增最后一位数字。
5
5
 
6
+ ## v0.0.44 — 2026-11-21 06:11
7
+
8
+ **按反馈回退 Agent 图表并继续去噪:断轴说明移入弹窗且通用化;效率卡片名称去掉“中位”;Agent 三图恢复原环形/饼图;雷达去掉下箭头并拉开左右标签;断轴图不再显示截断说明。**
9
+
10
+ - **工具耗时**:删除图下“pwsh 超出刻度……”常驻文字;断轴/截断规则改为通用说明,仅在“步骤与工具”的 `i` 弹窗中描述,不绑定某一工具名。
11
+ - **使用效率卡片**:小模块名称改回“首 token 用时 / 输出速度”,不再带“中位”;卡片脚注补 `中位 …` 与 `平均 …` 两行。
12
+ - **Agent 与时段**:恢复原来的三张图(费用环形图、轮次饼图、高峰/空闲环形图),不再使用树图;不再改动该模块原有图表形式。
13
+ - **路由雷达**:去掉首 token 用时后的下箭头;扩大左右留白并调整左右标签锚点,`调用` / `输出速度` 不再与图形重叠。
14
+ - **验证**:单测 **306/306**;隔离 UI **94/94**;`typecheck` 双 0。
15
+
16
+ ## v0.0.43 — 2026-11-21 05:44
17
+
18
+
19
+ **继续收敛看板:缓存字段改独立药丸;工具耗时改断轴横条;删除最贵轮次并把 Agent 费用占比改成树图;效率卡片脚注改两行;去掉雷达/悬停等多余说明;工作区说明移入弹窗;输出速度主值改中位并补 P90。**
20
+
21
+ - **缓存命中率**:命中 / 未命中 / 输出 / 当前范围改为四个独立药丸,与响应性能的 KPI 字段一致;不再用一整行背景框。
22
+ - **工具耗时**:对数横条改为**断轴横条**。最大值(pwsh)用断轴截断并标 `//`,其余工具按线性刻度;既保留 pwsh 的突出程度,也能看清小工具及名称。
23
+ - **最贵轮次**:删除该模块;Agent 费用占比由环形图改为**费用树图**,面积=费用、标签=Agent 名称,避免只有日期和 `#轮次` 无法定位的问题。
24
+ - **使用效率卡片**:关键数字下的补充字段改为最多两行,去掉 `·` 串联与多余字段;输出速度主值改为中位,补充平均与 90% 分位,不再叫“加权均值”。
25
+ - **响应性能**:路由雷达下的“各轴按当前路由归一化 · 悬停圆点看原始值”说明删除;`TTFT/TPS` 在 UI 和说明弹窗中统一改为**首 token 用时 / 输出速度**,不再用英文简称。
26
+ - **悬停说明**:删除 `悬停看调用/失败/平均耗时`、`悬停查看明细`、`悬停其它扇形…` 等所有页面级悬停提示,悬停展示本身保留。
27
+ - **按工作区**:合并/展开说明移入右上角 `i` 弹窗,表格上方不再常驻文字。
28
+ - **验证**:单测 **306/306**;隔离 UI **94/94**;`typecheck` 双 0。
29
+
30
+ ## v0.0.42 — 2026-11-21 04:46
31
+
32
+
33
+ **看板收尾:Token/费用柱图加纵轴虚线;费用弹窗改为空闲在上并说明 DeepSeek 时段规则;导出等到真正写入后再报成功;缓存统计移到顶部独立框;输出速度改为按路由分位图并排除 1000+ 异常样本;工具耗时改对数横条;步骤/工具调用相邻整行;Agent 移到费用下方。**
34
+
35
+ - **Token 消耗 / 费用消耗**:两根柱状图都按纵轴刻度画水平虚线,便于对照柱高;Token 堆叠图与费用柱图共用同一虚线样式。
36
+ - **费用说明弹窗**:价格表改为**空闲在上、高峰在下**;新增说明“高峰/空闲统一按 DeepSeek 官方北京时间规则判定,与接入方无关”;官网链接明确为 **DeepSeek 官方定价页(不是本插件官网)**;补充非 DeepSeek 模型未覆盖时按 DeepSeek 兜底价估算、实际以服务商账单为准。
37
+ - **导出**:有 File System Access API 时先弹原生保存框,写入完成后才提示“已保存”;浏览器不支持/拒绝时回退为普通下载,只提示“已开始下载,请确认文件”,不再提前说“已导出”。
38
+ - **缓存命中率**:命中/未命中/输出/当前范围移到趋势图上方的独立框;底部文字和纵轴缩放说明移入 `i` 弹窗。
39
+ - **输出速度**:从直方图改为**按路由的分位区间图**(箱体 25–75 分位、中线中位、细线 10–90 分位);排除单 chunk/非流式导致的 >1000 tok/s 不可信样本;弹窗解释 TPS 是解码速度,不等于端到端响应速度。
40
+ - **工具耗时**:树图改为**对数刻度横条排行**(前 10 + 其他),所有工具名称可读;仪表与排行并排。
41
+ - **步骤与工具**:每轮步骤数、每轮工具调用数改为相邻的整行图;Agent 与时段移到费用消耗下方、缓存命中率上方。
42
+ - **验证**:单测 **306/306**;隔离 UI **95/95**(新增导出两条路径、柱图虚线、缓存信息、Agent 顺序等断言);`typecheck` 双 0。
43
+
44
+ ## v0.0.41 — 2026-11-21 03:48
45
+
46
+
47
+ **按真实账本数据修正分档与布局:把被 `80+ / 32+ / 21+` 吞掉的长尾拆开,性能/工具图改整行,雷达可悬停看原始值,统一子模块边框与间距,修正仪表配色和 24 小时/星期热力的横轴对齐。**
48
+
49
+ - **分档**:TPS 改为 `<50 / 50–100 / 100–150 / 150–200 / 200–250 / 250–300 / 300–400 / 400–500 / 500–1000 / 1000+`;每轮步骤改为 `1 / 2 / 3 / 4–5 / 6–10 / 11–20 / 21–40 / 41–80 / 81–160 / 161+`;每轮工具调用改为 `0 / 1–5 / 6–15 / 16–30 / 31–60 / 61–120 / 121–240 / 241+`。依据是当前真实账本分布,避免单档占 50%–98%。
50
+ - **响应性能**:TTFT/TPS 双轴、速度分布、路由雷达各占整行;`TTFT = Time To First Token`、`TPS = Tokens Per Second` 写进说明;速度图补横纵轴说明;雷达圆点可悬停查看该路由的原始调用/TTFT/TPS/输出/用时,并加一行“各轴归一化”的短说明。
51
+ - **步骤与工具**:每轮步骤数、工具耗时树图各占整行;树图只单列耗时前 6 个工具,其余合并为「其他 N 个」,并增加名称+数值图例,解决小方块看不到名字;每轮工具调用数改为棒棒糖图,8 个分档完整展示。
52
+ - **仪表**:半圆仪表的模型部分现在是蓝色弧(此前只画了工具橙色弧,与图例不符)。
53
+ - **布局**:所有子模块统一加浅色背景框、圆角和 18–20px 间距;使用效率去掉每个小图下方的统计文字,改为面板顶部一行 KPI;24 小时柱图与星期×小时热力按 37px 行标签偏移对齐。
54
+ - **验证**:单测 **306/306**;隔离 UI **91/91**(新增雷达悬停、24h/热力对齐、子模块边框等断言);`typecheck` 双 0。
55
+
56
+ ## v0.0.40 — 2026-11-21 02:30
57
+
58
+
59
+ **重做新增统计面板的展示:不再用表格/列表堆文字,改为双轴面积、雷达、树图、径向柱、棒棒糖、半圆仪表等图;说明收进 `i` 弹窗。**
60
+
61
+ - **响应性能**:TTFT/TPS 从两张折线图合并为一条共享时间轴的**双轴面积图**;速度分布改为**棒棒糖图**;按路由表改为**归一化雷达图**(TTFT↓ / TPS / 输出 / 调用),路由不再堆成表格。
62
+ - **步骤与工具**:每轮步骤数改为**棒棒糖图**;每轮工具调用数改为**径向柱图**;工具排行表改为**耗时树图**(面积 = 工具耗时,颜色越深失败率越高);模型/工具用时改为**半圆仪表**。
63
+ - **最贵轮次**:表格改为**费用树图**(面积 = 该轮费用,颜色区分模型),悬停看 Token/耗时/步骤/TTFT/速度。
64
+ - **少文字**:新增面板只保留一行紧凑 KPI 药丸和短标题;覆盖口径、调用级 vs 整轮口径、图表编码说明全部移入 `i` 弹窗,不再有面板内长段落。
65
+ - **图表实现**:全部手写 SVG/HTML(无新依赖),新增 `src/client/advanced.tsx`;旧模块(累计卡片、热力日历、Token/费用柱、缓存、效率、24 小时、Agent)保持原样。
66
+ - **测试**:单测 **306/306**;隔离 UI **88/88**(更新新面板断言为双轴/雷达/棒棒糖/树图/径向/仪表,截图重新生成);`typecheck` 双 0。
67
+
68
+ ## v0.0.39 — 2026-11-21 02:02
69
+
70
+ **审查后修复:补全后的导出/恢复不再丢字段;补全预览数量与真实可补量一致;步骤/工具口径、覆盖率文案与资源上限加固。**
71
+
72
+ - **P0 备份恢复**:`createBackup()` 按 `(sessionId, turn)` 做 **newest-wins** 去重,`recordCount` 为唯一轮次数;`selectNewRecords()` 对备份内部重复 key 也保留最后一条。实测补全后的账本导出从 866 行恢复为 829 条唯一记录,恢复到空账本时 37 条 v2 补全字段完整保留(修复前会全部回退成 v1)。
73
+ - **P1 补全预览**:`turnsEnrichable` 只在 `mergeRecordExtras()` 真正返回升级行时自增;对已补全账本再次预览显示 0 条,而不是「可补全 37 条」。
74
+ - **P2 统计口径**:步骤/工具计数改为**整轮口径**,不再随模型/接入方筛选拆成部分步骤;TTFT/TPS/模型用时仍按匹配调用。`stepsPerTurn` 明确为「有采样轮次平均」,卡片与面板显示采样轮次/覆盖率。
75
+ - **P2 资源上限**:工具名/调用配对/重试码设置硬上限(199 个具名工具 + `(其它)`、2000 个待配对调用、20 个失败码),避免异常工具循环在对话回调里无界占用内存;超出仍保留计数,不影响 token/费用。
76
+ - **P3 加固**:首 token 的 `time0+dt` 累加做有限性检查,溢出返回未知;`highlights` 改为 Top-8 增量维护,不再为每个选中轮次建对象;summary 中的会话身份改为 8 位 FNV-1a 指纹(不再暴露完整 `sessionId`);路由/工具表超过 12 项时显示「共 N 项,显示前 12 项」。
77
+ - **展示**:性能/工具面板在完全没有新版数据时不再渲染空图表;「模型/工具用时」标注为累计值;TPS 趋势标题注明 `tok/s`;新增面板说明调用级指标与整轮活动指标的区别。
78
+ - **测试**:单测 **306/306**(新增备份恢复、补全预览幂等、模型筛选活动口径、Top-8/会话指纹、工具上限、首 token 溢出、recompute 保留 v2);隔离 UI 回归(新增面板断言保持全绿);`typecheck` 双 0。
79
+
80
+ ## v0.0.38 — 2026-11-21 01:26
81
+
82
+ **新增 dsh 0.2.2 已提供的逐调用性能与工具活动采集:TTFT、输出速度、step/模型/工具用时、工具成功率与重试;账本升到 v2(旧行仍可读),看板增加响应性能、步骤与工具、星期×小时热力、最贵轮次四个模块,并支持从历史会话日志补全旧记录的新字段。**
83
+
84
+ - **账本 schema v2(只增可选字段)**:`attempts[]` 新增 `step/startedAt/firstTokenAt/ttftMs/decodeMs/durationMs/tokensPerSecond/settledBy/interrupted/reportedCacheRead/Write/Reasoning`;record 新增 `tools[]/retries/retryCodes/interrupted`。`RECORD_SCHEMA_VERSION → 2`,`READABLE_RECORD_VERSIONS = [1,2]`;v1 reader 永久保留,旧行读成新形状时新字段缺省(未知,不伪造 0)。v2 reader 对新增字段做清洗:坏时间/坏数组只丢字段,不丢整行。
85
+ - **采集口径与官方一致**:从 `assistant/message` / `assistant/attempt` 的紧凑 stream 还原首个输出 token 时间(`text-delta` / `reasoning-delta` / `tool-call-delta`,压缩 run 用 `time0 + dt[]`);TTFT 从 step 开始算、输出速度 = 输出 token / 解码时长;模型用时 = step 开始到最终回复完成;工具用时 = `tool/call → tool/result`。工具只保存名称/次数/耗时/失败状态,不保存参数、结果或失败正文;重试只保存稳定 `failure.code`。
86
+ - **不增加对话路径 I/O**:所有新解析仍在 `session/event` 回调内做纯算术,落盘仍走原 `setImmediate` 队列;stream 不留存。旧日志只有 usage chunk 时时间字段自然缺省。
87
+ - **历史补全(只增不改)**:补录扫描到已存在的 v1 记录时,用同一份会话日志重放出的 `step/时间/工具/重试` 字段升级该记录(attempt 按 `(at, total, provider, model)` 对齐);token、费用、币种、会话/工作区身份、起止时间一律不动,重跑幂等。日志不存在/格式不认识则保持原样。API/CLI 报告新增 `turnsEnrichable/turnsEnriched/turnsEnrichSkipped`,CLI 增加 `--no-enrich`。
88
+ - **看板新增**:使用效率卡片从 5 张增至 8 张(首 token 中位、输出速度、步骤与工具);「响应性能」面板(TTFT/TPS 趋势、速度分布、按路由性能表);「步骤与工具」面板(每轮步骤/工具分布、模型 vs 工具耗时环形图、工具排行);「24 小时活跃」增加星期×小时 7×24 热力图;「最贵轮次」Top 8 表;旧记录无采样时显示 `—`/空状态与覆盖率说明,不出现 0/NaN。
89
+ - **测试**:单测 **297/297**(新增 collector 首 token/工具/重试、schema v2、聚合 performance/weekHours/highlights、bucketDaily perf、merge 幂等与不改费用);隔离 UI **88/88**(新增 4 个面板断言 + 2 张趋势图/2 张分布图/热力/最贵轮次;截图新增 `panel-performance.png`、`panel-tools.png`、`panel-highlights.png`);`typecheck` 双 0;含真实 0.2.2 会话日志的补录 dry-run 实测(5 个日志:18 条可补全、0 条误改)。
90
+ - **兼容/体积**:旧 Host 的 summary 没有新 `analytics` 字段时新 Client 不渲染新模块;旧插件读 v2 行会明确报 `unsupported-version`(不损坏数据)。按本机 829 轮/37,444 attempts/11.1 MB 估算,账本约增加 4–6 MB。
91
+ - **文档**:README、`design/CORE-LOGIC.md`、维护手册与本设计 `docs/plan/014-20261121-性能与工具数据采集设计与实施.md` 同步。
92
+
93
+ ## v0.0.37 — 2026-11-13 18:17
94
+
95
+ **README 新增「效果预览」:两张真实界面截图,让 npm 页面和 dsh 插件详情页可以直接看到看板效果。**
96
+
97
+ - **截图**:`docs/token-usage-image01.png`(看板上半部分:累计卡片、使用效率、固定 365 天日历热力图、Token / 费用趋势)与 `docs/token-usage-image02.png`(缓存命中率趋势、调用与轮次效率、24 小时活跃、Agent 与时段)。
98
+ - **图片 URL 用绝对地址**:npm 页面不会按包内相对路径解析图片(没有 public 仓库可映射),因此 README 使用 jsDelivr 的 npm 文件 CDN:`https://cdn.jsdelivr.net/npm/dsh-token-usage-ledger@0.0.37/docs/...`。dsh 0.2.x 的插件详情页同样把 http(s) 图片按外链渲染,所以两处都能显示。
99
+ - **图片随包发布**:`package.json` 的 `files` 增加两张 PNG,`npm pack` 后由 jsDelivr 从 npm tarball 读取;不把 `docs/` 里的维护文档打进包。
100
+ - **布局**:两张图按上下顺序放在正文简介之后、功能列表之前,每张下面一行斜体说明,分别对应看板上半部分和下半部分;截图用深色主题,文字注明浅色主题同样适配。
101
+ - **发布顺序**:必须先 `npm publish` 0.0.37,jsDelivr 上 `@0.0.37` 的图片 URL 才存在;在此之前本地/旧版页面打开会看到破图。发布后可用 `Invoke-WebRequest -Method Head` 逐个核对两个 URL 返回 200。
102
+ - **验证**:`typecheck` 双 0、单测 **280/280**、`npm pack --dry-run` 文件清单包含两张 PNG 且不含 `src/`、`tests/`、`scripts/`、`docs/*.md`、sourcemap、`.tsbuildinfo`。
103
+ - **说明**:截图只包含 token 数量、费用、模型/接入方与时间分布,不含提示词、会话内容或工作区路径;产品代码与账本 schema 不变。
104
+ - **已发布(2026-11-13 19:00,北京时间)**:`dsh-token-usage-ledger@0.0.37` 发布成功,`dist-tags.latest = 0.0.37`;两个 jsDelivr 图片 URL 实测返回 **200**(`image/png`,368,416 / 181,051 字节),npm 页面已显示「效果预览」两张图。正式环境仍在 `0.0.36`(本版无产品代码变化,无需强制升级)。
105
+
6
106
  ## v0.0.36 — 2026-11-13 03:17
7
107
 
8
108
  **面向 npm 公共发布:包名改为 `dsh-token-usage-ledger`,README 拆成用户版(npm 页面 / 插件详情页)与维护手册,版本号改为纯 SemVer;产品行为不变。**
@@ -16,6 +116,8 @@
16
116
  - **维护脚本同步**:`verify-ui.mjs` 的模块 id 改为从 `package.json` 读取;`setup_test_env.py` 的组合层断言、`install/uninstall/deploy_production.py` 的默认包名与旧包名迁移提示同步更新(检测到旧包名时会明确要求先卸载,不会在 profile 里留下两行相同 id)。
17
117
  - **测试**:单测 **280/280**、`typecheck` 双 0;`npm pack --dry-run` 文件清单与 `npm publish --dry-run` 通过;隔离实例从打包产物安装并通过 UI 断言(见维护手册 §9)。
18
118
  - **安装/发布**:离线包 `npm run build && npm run pack:install` → `dist/dsh-token-usage-ledger-0.0.36.zip`;npm 公共发布步骤见 `docs/002-20261113-npm发布手册.md`(需要维护者本人输入 2FA 验证码)。
119
+ - **已发布(2026-11-13 03:24,北京时间)**:`dsh-token-usage-ledger@0.0.36` 发布成功,`dist-tags.latest = 0.0.36`;首次发布产生的 `0.0.0-stage` 占位版本已按规范单独 deprecate(`latest` 未受影响)。
120
+ - **正式环境已切换(2026-11-13 03:32)**:完全退出应用 → 卸载旧包名 → 从 npm 安装 `dsh-token-usage-ledger@^0.0.36` → 重启;`runtime.json` 的 `pluginVersion` 为 `0.0.36`,`dataDir` 仍是 `~/.dsh/token-usage`,账本保留并继续追加(切换前 10,037,896 字节 → 切换后 10,039,380 字节)。旧包名在 `node_modules` 里还留有一个**符号链接**(不在 dependencies / `dsh.profile.bundles` / lock 中,不影响加载),按需用 `cmd /c rmdir "<路径>"` 摘掉即可。
19
121
  - **升级注意**:正式环境若还装着旧包名 `dsh-plugin-token-usage`,必须**先完全退出应用 → 卸载旧包 → 安装新包 → 重启**;新旧包名不能同时存在(同一个插件会有两行相同的 `token-usage` id)。账本不受影响。
20
122
 
21
123
  ## v0.0.35-20261112 — 2026-11-12 21:42
package/README.md CHANGED
@@ -5,7 +5,17 @@
5
5
 
6
6
  **给 DeepSeek Harness(dsh)用的 Token 用量账本与统计看板。**
7
7
 
8
- 它会在每一轮对话结束后,自动把这一轮消耗的 token 与折算费用记到本地账本里,并在 dsh 侧栏提供一个看板:累计用量、日历热力图、Token / 费用趋势、按模型与按工作区的明细。安装后不需要任何操作,聊过的每一轮都会自动记账。
8
+ 它会在每一轮对话结束后,自动把这一轮消耗的 token 与折算费用记到本地账本里,并在 dsh 侧栏提供一个看板:累计用量、日历热力图、Token / 费用趋势、响应速度(首 token / 输出速度)、步骤与工具活动、按模型与按工作区的明细。安装后不需要任何操作,聊过的每一轮都会自动记账。
9
+
10
+ ## 效果预览
11
+
12
+ ![看板总览:累计卡片、日历热力图与 Token / 费用趋势](https://cdn.jsdelivr.net/npm/dsh-token-usage-ledger@0.0.37/docs/token-usage-image01.png)
13
+
14
+ *看板上半部分:累计 Token / 费用 / 轮次、缓存命中率、固定 365 天的日历热力图,以及 Token 与费用趋势。顶部可切换工作区、接入方、模型、粒度和日期范围。*
15
+
16
+ ![缓存命中率、调用与轮次效率、24 小时活跃、Agent 与时段](https://cdn.jsdelivr.net/npm/dsh-token-usage-ledger@0.0.37/docs/token-usage-image02.png)
17
+
18
+ *继续向下:Agent 与时段(费用占比 / 轮次 / 高峰空闲)、缓存命中率趋势、调用与轮次效率、24 小时活跃时段。截图使用深色主题,浅色主题同样适配。*
9
19
 
10
20
  ---
11
21
 
@@ -20,7 +30,10 @@
20
30
  - **明细表**:「按模型」会区分同一模型的不同接入方;「按工作区」按当前显示名合并同名工作区,可展开查看每条原始路径,并可「只看此路径」。
21
31
  - **费用说明**:看板头部的 `i` 按钮会说明费用公式、峰谷时段、价格来源与估算口径。
22
32
  - **更多统计**:轮次效率、调用次数 / 耗时分布、24 小时活跃时段、Agent 模式的费用与轮次、高峰 / 空闲费用占比。
23
- - **备份与补录**:一键导出完整账本 JSON;导入只追加缺失记录(按「会话 + 轮次」去重);「补录」可扫描本机会话日志,把安装插件之前或停用期间漏记的轮次补进账本。
33
+ - **响应性能**:首 token 用时与输出速度(tok/s)的双轴面积趋势、按路由的输出速度分位图(25–75 分位 / 中位 / 10–90 分位)、按路由的归一化雷达图;累计模型/工具用时。输出速度主值取中位,卡片补充中位与平均;1000+ tok/s 的单 chunk/非流式异常样本会被排除。
34
+ - **步骤与工具**:每轮步骤数 / 每轮工具调用数用相邻的棒棒糖图(按真实数据扩充分档)、工具耗时用断轴横条排行(最大值明显高于其余工具时截断标记,其余工具线性展示,前 10 + 其他)、模型/工具用时占比用半圆仪表。只记录工具名和计数,不保存参数或结果。
35
+ - **活跃节律**:在 24 小时柱状图之外,增加「星期 × 小时」7×24 热力图,方便看出固定时段的使用习惯。
36
+ - **备份与补录**:一键导出完整账本 JSON(按「会话 + 轮次」只保留最新一条,补全后的 v2 字段不会在恢复时丢失);导入只追加缺失记录;「补录」可扫描本机会话日志,把安装插件之前或停用期间漏记的轮次补进账本,并为旧记录补全首 token / 工具等新字段(只增不改,token 与费用不动)。
24
37
  - **不影响对话**:只读取会话事件;采集或渲染出错只会在插件内部提示,不会影响对话,也不会影响 dsh 其它功能。
25
38
 
26
39
  ---
@@ -84,8 +97,10 @@ dsh plugin --profile <profile> add dsh-token-usage-ledger
84
97
  | 按模型 | 模型 + 接入方、token、轮次、费用;同一模型经不同接入方时分行显示 |
85
98
  | 按工作区 | 工作区、轮次、token、费用;同名工作区合并,可展开原始路径 |
86
99
  | 调用与轮次效率 | 每轮调用次数、耗时、中位数、90% 分位、会话数等 |
87
- | 24 小时活跃时段 | 一天中各小时的活跃分布 |
88
- | Agent 与时段 | 各 Agent 模式的费用 / 轮次,以及高峰 / 空闲费用占比 |
100
+ | 响应性能 | 双轴面积趋势、路由速度分位图、路由雷达图 |
101
+ | 步骤与工具 | 步骤/工具调用棒棒糖图、工具耗时断轴横条、用时仪表 |
102
+ | 24 小时活跃时段 | 一天中各小时的活跃分布,以及「星期 × 小时」热力图 |
103
+ | Agent 与时段 | Agent 费用环形图、轮次饼图、高峰 / 空闲调用 |
89
104
 
90
105
  看板头部会显示当前插件版本。各模块右上角的 `i` 是口径说明。
91
106
 
@@ -99,7 +114,7 @@ dsh plugin --profile <profile> add dsh-token-usage-ledger
99
114
 
100
115
  ### 备份、导入与历史补录
101
116
 
102
- - **导出**:下载完整账本 JSON 备份。备份包含会话 ID、工作区路径等明细,请妥善保管。
117
+ - **导出**:保存完整账本 JSON 备份。支持原生保存框时,写入完成后才提示“已保存”;不支持时提示“已开始下载,请在浏览器下载位置确认”。每个「会话 + 轮次」只写最新一条,补全后的 v2 字段会保留;备份包含会话 ID、工作区路径等明细,请妥善保管。
103
118
  - **导入**:先显示待导入记录数,确认后只追加缺失记录;同一「会话 + 轮次」会跳过,重复导入不会重复计数。
104
119
  - **补录**:两阶段(扫描预览 → 确认补录)。用于补装插件之前的历史,以及停用期间漏记但日志仍可还原的轮次;重复执行是安全的。
105
120
 
@@ -109,7 +124,7 @@ dsh plugin --profile <profile> add dsh-token-usage-ledger
109
124
 
110
125
  - 账本默认位于 `<dsh home>/token-usage/records.jsonl`,通常是 `~/.dsh/token-usage/records.jsonl`(Windows:`%USERPROFILE%\.dsh\token-usage\records.jsonl`)。一行一条 JSON,只追加。
111
126
  - 看板通过 dsh 自带的 Web 服务读取一个本机端点(默认 `/dsh-token-usage`)。该端点受 dsh 的浏览器信任围栏保护:没有有效页面会话返回 401,主机校验不通过返回 403;响应不包含 CORS 头。
112
- - 插件**不会**保存提示词、消息内容、附件或任何凭据;只记录 token 数量、模型 / 接入方、工作区路径、时间与金额。工作区**绝对路径**会出现在看板数据中(用于筛选与显示),这是有意的取舍。
127
+ - 插件**不会**保存提示词、消息内容、附件或任何凭据;只记录 token 数量、模型 / 接入方、工作区路径、时间、金额,以及从 dsh 会话事件中可得到的**首 token 时间、输出速度、步骤/工具耗时、工具名称与调用/失败次数、重试错误码**。工具参数、工具结果、失败正文和消息正文都不会写入账本。工作区**绝对路径**会出现在看板数据中(用于筛选与显示),这是有意的取舍。
113
128
  - 插件不向任何外部服务器发送数据,也不会在运行时联网核对价格。
114
129
  - 卸载插件**不会删除账本**;重新安装后继续使用同一份数据。
115
130
 
@@ -118,7 +133,7 @@ dsh plugin --profile <profile> add dsh-token-usage-ledger
118
133
  ## 费用是怎么算的
119
134
 
120
135
  - 按 DeepSeek 官方公开价目估算(价目 id `deepseek-2026-09-10`,2026-09-13 核对,单位:每百万 token)。
121
- - **峰谷时段**:周一至周五 09:00–12:00、14:00–18:00(北京时间)为高峰;其余时间(含周末)按高峰价的 50% 计算。判定按每次请求的结算时刻,与运行机器的时区无关。
136
+ - **峰谷时段**:统一按 DeepSeek 官方的北京时间规则:周一至周五 09:00–12:00、14:00–18:00 为高峰;其余时间(含周末)按高峰价的 50% 计算。所有接入方都套用同一时段倍率;判定按每次请求的结算时刻,与运行机器的时区无关。价格表来自 DeepSeek 官方定价页,不是本插件官网;非 DeepSeek 模型未配置覆盖时按兜底价估算,实际以服务商账单为准。
122
137
  - 缓存写入按「未命中输入」计价;推理 token 不单独计价(它是输出的一部分)。
123
138
  - 默认人民币(CNY)。费用在记账时冻结:之后改价目或改币种,都不会改写历史记录。
124
139
  - **这是估算,不是账单**:不包含账户级折扣、赠送额度等;请以 DeepSeek 官方账单为准。
@@ -178,7 +193,7 @@ dsh plugin --profile <profile> add dsh-token-usage-ledger
178
193
 
179
194
  装完同样需要完全重启 dsh。
180
195
 
181
- 升级只替换插件代码,不会动账本。
196
+ 升级只替换插件代码,不会动账本。从 v0.0.37 升到 v0.0.38+ 后,账本会用 schema v2 追加新行;旧行仍按 v1 读取。**若之后降级到 v0.0.37 或更早版本,v0.0.38+ 写入的行会被旧版本视为「版本过新」而不计入**(不会损坏数据);降级前请先导出备份。v0.0.39 进一步修复了补全后导出/恢复的去重问题:每个「会话 + 轮次」只备份最新一条,恢复不会退回旧 v1 行。升级后可用看板「补录」把旧记录的首 token / 工具字段补全。
182
197
 
183
198
  ---
184
199
 
@@ -212,6 +227,7 @@ dsh plugin --profile <profile> add dsh-token-usage-ledger
212
227
  ## 已知限制
213
228
 
214
229
  - 只统计**安装并启动之后**发生的轮次;安装前的历史需要用「补录」按钮从会话日志补出来。
230
+ - 首 token / 输出速度 / 工具活动等字段从 **v0.0.38** 起采集(v0.0.39 修正了补全后导出/恢复与采样口径);旧账本记录本身仍可读,但只有会话日志还能重放时才能通过「补录」补全这些字段,补不出来的会显示为「—」而不是 0。
215
231
  - 费用是根据公开价目表与上报用量计算的**估算值**,不是官方账单。
216
232
  - 同名工作区按显示名合并;需要精确区分时,展开原始路径或使用「只看此路径」。
217
233
  - 同一模型经不同接入方接入时分行显示,不会自动合并。
@@ -223,7 +239,7 @@ dsh plugin --profile <profile> add dsh-token-usage-ledger
223
239
 
224
240
  ## English
225
241
 
226
- **dsh-token-usage-ledger** records the token usage and estimated cost of every turn in DeepSeek Harness (dsh) into a local, append-only ledger, and adds a dashboard to the sidebar: summary cards, a 365-day calendar heatmap, token/cost charts, per-model and per-workspace tables, and export / import / backfill actions.
242
+ **dsh-token-usage-ledger** records the token usage and estimated cost of every turn in DeepSeek Harness (dsh) into a local, append-only ledger, and adds a dashboard to the sidebar: summary cards, a 365-day calendar heatmap, token/cost charts, response performance (first-token latency / output speed), step and tool activity, a weekday × hour heatmap, per-model and per-workspace tables, and export / import / backfill actions.
227
243
 
228
244
  - **Requirements**: dsh `0.2.2-rc.2` or newer (0.2.x; desktop app or `dsh web`). The plugin is rejected at install time on older versions.
229
245
  - **Install**: open dsh → **Plugins → Add plugin** → enter `dsh-token-usage-ledger` → choose the **official npm registry** → install → fully quit and reopen dsh.
Binary file
Binary file