@lingda-ai/dsh-plugin-ledger 0.1.7 → 0.1.8

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/docs/technical.md CHANGED
@@ -261,7 +261,7 @@ token 只是 `measures` 里的一种单位。计划中的第二个来源(Trae
261
261
 
262
262
  | 手段 | 覆盖 | 产出 |
263
263
  |---|---|---|
264
- | `node --test test/*.test.mjs` | 206 例断言 | 计价、归因、预算回滞、幂等、身份、卸载残留、面板 SSR、客户端产物形态 |
264
+ | `node --test test/*.test.mjs` | 225 例断言 | 计价、归因、预算回滞、幂等、身份、卸载残留、面板 SSR、客户端产物形态 |
265
265
  | `node scripts/build-client.mjs` | 产物形态 | 从源码重建 `lib/client.js`(零 import/export 的 loader 包) |
266
266
  | `scripts/bench.mjs --gate` | 热路径 + 内存 | 上表数字 |
267
267
  | `scripts/smoke-registry.mjs` | 插件装配契约 | 假 ctx 下工具注册/提供不抛 |
@@ -270,6 +270,9 @@ token 只是 `measures` 里的一种单位。计划中的第二个来源(Trae
270
270
  | `scripts/render-panel.mjs` | 视觉(单状态) | 真实 `renderPayload()` 输出,三列宽度 |
271
271
  | `scripts/render-states.mjs` | 视觉(状态矩阵) | 7 个状态并排:常规/空态/费率未知/费率被拒/展开/预算/300px |
272
272
  | `test/client-lifecycle.test.mjs` | 客户端生命周期 | 登记可逆、重复 apply、无 slots 降级、登记抛错不冒泡 |
273
+ | `test/snapshot-roundtrip.test.mjs` | 写盘→读回全链路 | 20 条明细(400+ 行)分页读回、truncated 落盘、二级降级不超 maxBytes |
274
+ | `test/guard-downgrade.test.mjs` | 预算降级矩阵 | provider/model/maxTokens 覆盖、阈值、未知成本不判、next 抛错冒泡 |
275
+ | `test/client-artifact-render.test.mjs` | 产物渲染 | 用 `lib/client.js` + 真 React 渲染有数据态与组件首帧(抓出过重名常量导致的 SyntaxError) |
273
276
 
274
277
  **SKIP 不等于通过**:冒烟脚本找不到 DSH 运行时用退出码 2 表示 SKIP,`prepublish.sh` 第 6 步把 SKIP 判 FAIL。
275
278
  这条是为了避免"换台机器 CI 照样全绿,但契约一条没验"。
@@ -383,6 +386,22 @@ ctx.get('slots') // 可选服务:不受 inject 约
383
386
  默认姿态是"退化成一个没有面板的插件",而不是"把宿主带走";同时新增反证测试:
384
387
  把 `inject` 去掉,`apply` 必须抛 `without inject`——这条测试的存在意义就是让这个错在单测里炸。
385
388
 
389
+ **12.7 三条跨模块契约,从来没被同一条测试同时握住两端。**
390
+
391
+ 一次针对性审计(自动化测试视角)挖出三个**当前代码的真实故障**,都不是理论风险:
392
+
393
+ | 故障 | 为什么单测全绿 |
394
+ |---|---|
395
+ | 面板读回:Host 写的是多行 JSON,`workspaceFiles.read` 是**按行分页**的(一页最多 400 行),而浏览器半只读一页还要求 `eof`。一份 20 条明细的快照有 461~587 行 → 任何稍成熟的会话打开面板都是「读取失败」 | Host 侧测 payload 对象(没写盘),浏览器侧测 mock 远程(没真文件),谁都没测真实尺寸 |
396
+ | `truncated` 不落盘:它只是 `buildPanelPayload` 的返回值,payload 里没有这个字段,面板的"明细已截断"提示是死代码 | 单测断言的是返回值 `r.truncated`,正好把落盘那一步遮住 |
397
+ | `assistant/attempt` 污染预算:该事件无 usage,记成 `unknown(no-usage)` 后 `guard.spentOf` 见到 `unknownEntries > 0` 就整条放弃预算,降级静默失效 | 全套用例里根本没构造过 attempt 事件 |
398
+
399
+ 修法都不是加判断,而是**把两端放进同一条测试**:`snapshot-roundtrip.test.mjs` 用真 store + 真 publisher + 真文件 + 按行分页的假 remote;
400
+ `client-artifact-render.test.mjs` 用发布产物 + 真 React 渲染(它当场抓出一个重名常量导致的 SyntaxError——
401
+ 四个模块打包进同一作用域,`REFRESH_MS` 重复声明,源码测试全绿、产物必然崩)。
402
+
403
+ 一句话:**可以骗过单测的,永远是"我以为另一端是这样的"。**
404
+
386
405
  ### 工程侧的一条硬约束
387
406
 
388
407
  `dsh plugin --profile <p> add file:<path>` 是 pnpm 的 `file:` 依赖:**文件硬链接、目录复制**。
package/lib/client.js CHANGED
@@ -101,6 +101,13 @@ window.__ModuleLoader__.load({
101
101
 
102
102
  /** 上下文规模用 k 缩写:42.0k 比 42,000 更适合一眼扫 */
103
103
  /** 四档都齐才给总数:缺一档就当不知道,不把缺失当 0 加进去(否则会造出一个假数) */
104
+ /** 实付 + 省下 = "如果没有缓存本来要花的钱",也就是节省比例的分母。 */
105
+ function grossAmountOf(view) {
106
+ const saved = view?.totals?.saved?.amount
107
+ const spent = view?.totals?.cost?.amount
108
+ return typeof saved === 'number' && typeof spent === 'number' ? saved + spent : null
109
+ }
110
+
104
111
  function tokensTotal(tokens) {
105
112
  if (!tokens || typeof tokens !== 'object') return null
106
113
  const parts = [tokens.input, tokens.output, tokens.cacheRead, tokens.cacheWrite]
@@ -134,6 +141,9 @@ window.__ModuleLoader__.load({
134
141
  /** "谁花的"折叠前先显示几条:6 条是 300px 宽度下不做滚动还看得完的上限 */
135
142
  const SOURCE_HEAD = 6
136
143
 
144
+ /** 面板自动刷新间隔:Host 落盘节流 3s,这里 5s,够快又不空转。 */
145
+ const REFRESH_MS = 5000
146
+
137
147
  // 老快照(没有 pricing 字段)的兜底文案。新快照一律由 pricingNoteOf 生成,
138
148
  // 因为"内置还是自定义、哪天的价、有没有被忽略的模型"只能从数据里读,不能写死。
139
149
  const PRICING_NOTE = '按内置官方价估算 · 2026-11-19'
@@ -231,7 +241,7 @@ window.__ModuleLoader__.load({
231
241
 
232
242
  const INK = '#1f2733'
233
243
  const INK2 = '#5a6472'
234
- const INK3 = '#6f7a89'
244
+ const INK3 = '#64707f'
235
245
 
236
246
  /**
237
247
  * 时间一律按**本地时区**显示。
@@ -318,19 +328,28 @@ window.__ModuleLoader__.load({
318
328
  const [view, setView] = React.useState(undefined)
319
329
  const [busy, setBusy] = React.useState(false)
320
330
  const [expanded, setExpanded] = React.useState(false)
331
+ // 请求序号:切会话时旧请求可能后到,不能让它把新会话的读数覆盖掉
332
+ const seq = React.useRef(0)
321
333
 
322
334
  const refresh = React.useCallback(async () => {
323
335
  if (sessionId === null) return
336
+ const mine = (seq.current += 1)
324
337
  setBusy(true)
325
338
  try {
326
- setView(await fetchView(sessionId))
339
+ const next = await fetchView(sessionId)
340
+ if (mine === seq.current) setView(next)
327
341
  } finally {
328
- setBusy(false)
342
+ if (mine === seq.current) setBusy(false)
329
343
  }
330
344
  }, [sessionId])
331
345
 
332
346
  React.useEffect(() => {
347
+ // 切会话先清空:宁可闪一帧"正在读取",也不能让 B 会话标题下挂着 A 会话的金额
348
+ setView(undefined)
333
349
  void refresh()
350
+ // 成本是持续读数,不是一张照片:挂载后自动刷新(Host 侧 3 秒落盘节流)
351
+ const timer = setInterval(() => { void refresh() }, REFRESH_MS)
352
+ return () => clearInterval(timer)
334
353
  }, [refresh])
335
354
 
336
355
  const head = h(
@@ -426,7 +445,9 @@ window.__ModuleLoader__.load({
426
445
  const unattributed = list.find((item) => item?.plugin === 'unattributed')
427
446
  const lost = typeof unattributed?.entries === 'number' && unattributed.entries > 0 ? unattributed.entries : null
428
447
  if (lost === null) return `${entries} 次调用`
429
- if (lost === entries) return `${entries} 次调用 · 来源未配置`
448
+ // 全部落在 unattributed 时不能写"来源未配置":那个桶里既有"本会话没调用工具"(no-signal),
449
+ // 也有"调了工具但没登记 owner"(no-origin)。写"配置"会把纯聊天会话指去改配置。
450
+ if (lost === entries) return `${entries} 次调用 · 归因无信号`
430
451
  return `${entries} 次调用 · ${lost} 次未归因`
431
452
  }
432
453
 
@@ -581,16 +602,22 @@ window.__ModuleLoader__.load({
581
602
  : h(
582
603
  'div',
583
604
  { style: { marginTop: 4, fontSize: 11, lineHeight: 1.6, color: GOOD, fontVariantNumeric: 'tabular-nums' } },
584
- `缓存命中已省 ${formatAmount(view.totals.saved.amount, view.totals.saved.currency)}${
605
+ `缓存已省 ${formatAmount(view.totals.saved.amount, view.totals.saved.currency)}${
585
606
  typeof view.totals.savedShare === 'number'
586
- ? ` · 少花 ${formatShare(view.totals.savedShare)}`
607
+ ? ` · 如未命中需 ${formatAmount(grossAmountOf(view), view.totals.saved.currency)}(少花 ${formatShare(view.totals.savedShare)})`
587
608
  : ''
588
609
  }`,
589
610
  ),
590
611
  ),
591
612
  // 预算条:只有配置了 limit 才画,未计价时不假装花了 0
592
- view.budget !== null && view.budget !== undefined
613
+ view.budget === null || view.budget === undefined
593
614
  ? h(
615
+ 'div',
616
+ { style: { padding: '0 14px 8px', fontSize: 11, color: INK3 } },
617
+ // 静默消失会被读成"这个面板没有这个功能";说清是配置项,用户才知道怎么开
618
+ '未设预算 · 配 budget.limit 后这里显示"还能问几次"',
619
+ )
620
+ : h(
594
621
  'div',
595
622
  { style: { padding: '0 14px 10px' } },
596
623
  h(
@@ -616,8 +643,7 @@ window.__ModuleLoader__.load({
616
643
  },
617
644
  }),
618
645
  ),
619
- )
620
- : null,
646
+ ),
621
647
  // token 四档
622
648
  h(
623
649
  'div',
@@ -635,8 +661,18 @@ window.__ModuleLoader__.load({
635
661
  formatAmount(parts?.cacheRead, cost.currency),
636
662
  `${formatTokens(tokens.cacheRead)} tok${hitRateOf(totals.cacheHitRate)}`,
637
663
  ),
638
- rowOf(React, '缓存写', formatAmount(parts?.cacheWrite, cost.currency), `${formatTokens(tokens.cacheWrite)} tok`),
639
- rowOf(React, '输出', formatAmount(parts?.output, cost.currency), `${formatTokens(tokens.output)} tok · 含 reasoning`),
664
+ // 缓存写:DeepSeek 没有独立写价,这一档恒为 0。占一行"0 tok ¥0.0000"只是噪音,
665
+ // 但真的产生了写 token 时必须画出来(其它 provider 会有)
666
+ (tokens.cacheWrite ?? 0) > 0 || (parts?.cacheWrite ?? 0) > 0
667
+ ? rowOf(React, '缓存写', formatAmount(parts?.cacheWrite, cost.currency), `${formatTokens(tokens.cacheWrite)} tok`)
668
+ : null,
669
+ rowOf(
670
+ React,
671
+ '输出',
672
+ formatAmount(parts?.output, cost.currency),
673
+ // "含 reasoning" 在 reasoning=0 时是假陈述
674
+ `${formatTokens(tokens.output)} tok${(tokens.reasoning ?? 0) > 0 ? ' · 含 reasoning' : ''}`,
675
+ ),
640
676
  ),
641
677
  ),
642
678
  // 来源
@@ -720,10 +756,15 @@ window.__ModuleLoader__.load({
720
756
  : h(
721
757
  'span',
722
758
  { style: { fontSize: 11, color: INK3, fontVariantNumeric: 'tabular-nums', whiteSpace: 'nowrap' } },
723
- `最贵一步 ${formatAmount(peak.amount, cost.currency)}`,
759
+ // 只说"最贵"会让人去优化那一步;补上定位与占比才知道值不值得优化
760
+ `最贵 ${typeof peak.turn === 'number' ? `T${peak.turn}·S${peak.step ?? '—'} ` : ''}${formatAmount(peak.amount, cost.currency)}${
761
+ moneyKnown && cost.amount > 0
762
+ ? ` · 占 ${formatShare(peak.amount / cost.amount)}`
763
+ : ''
764
+ }`,
724
765
  ),
725
766
  ),
726
- recent.slice(0, 5).map((item, index) =>
767
+ recent.slice(0, 5).map((item, index, all) =>
727
768
  h(
728
769
  'div',
729
770
  { key: `r-${index}`, style: { padding: '4px 0' } },
@@ -752,12 +793,30 @@ window.__ModuleLoader__.load({
752
793
  // 第二行的优先级 = "为什么这一步贵":压缩收益 > 本次 token 量 > 工具体量 > 路由 > 归属。
753
794
  // 380px 下这一行必定会被省略号截断,所以要让它从右边开始丢信息,
754
795
  // 而不是从左边(左边留住的是解释,右边留住的是标识)。
755
- ...detailPartsOf(React, item, cost),
796
+ ...detailPartsOf(React, item, cost, {
797
+ // 同一段的模型名大多相同,重复 N 遍等于把"为什么贵"的信息挤出去
798
+ hideRoute: index > 0 && routeTextOf(item) === routeTextOf(all[index - 1]),
799
+ }),
756
800
  ),
757
801
  ),
758
802
  ),
759
803
  )
760
804
  : null,
805
+ // 结论行:② 问的是"为什么贵",一张等高的小额明细表回答不了。
806
+ // 只在"命中这一档确实占大头"时给一句人话,其余情况闭嘴(不为了凑结论而编结论)。
807
+ (() => {
808
+ if (!moneyKnown || typeof parts?.cacheRead !== 'number' || cost.amount <= 0) return null
809
+ const share = parts.cacheRead / cost.amount
810
+ const calls = totals.entries ?? 0
811
+ if (share < 0.5 || calls < 3) return null
812
+ const totalTok = tokens ? (tokens.input ?? 0) + (tokens.cacheRead ?? 0) + (tokens.output ?? 0) : null
813
+ return h(
814
+ 'div',
815
+ { style: { padding: '0 14px 10px', fontSize: 11, lineHeight: 1.65, color: INK2 } },
816
+ `钱主要花在重复送出的上下文:命中一档 ${formatAmount(parts.cacheRead, cost.currency)}(占 ${formatShare(share)})`,
817
+ totalTok === null ? '' : `,${calls} 次调用共送出 ${formatTokensCompact(totalTok)} tok`,
818
+ )
819
+ })(),
761
820
  // 会话对比:只给其他会话,自己已经在顶部
762
821
  others.length > 0
763
822
  ? h(
@@ -785,19 +844,14 @@ window.__ModuleLoader__.load({
785
844
  ),
786
845
  )
787
846
  : null,
788
- // 页脚
789
- h(
790
- 'div',
791
- { style: { padding: '6px 14px 12px', fontSize: 11, color: INK3 } },
792
- `快照 ${formatLocalTime(view.generatedAt)}`,
793
- ),
847
+ // 页脚:快照时间 + 费率来源合成一行,省 20px 且不会出现"两个日期像两个时间戳"
794
848
  h(
795
849
  'div',
796
850
  {
797
- // 费率脚注:自定义生效用正文色、无效用警示色,绝不与"内置价"混成一色
798
- style: { padding: '0 14px 12px', fontSize: 11, color: note.warn ? WARN : INK3 },
851
+ // 费率无效时整行转警示色:这是"金额不可信"的信号,不能和普通脚注同色
852
+ style: { padding: '6px 14px 12px', fontSize: 11, lineHeight: 1.65, color: note.warn ? WARN : INK3 },
799
853
  },
800
- note.text,
854
+ `快照 ${formatLocalTime(view.generatedAt)} · ${note.text}`,
801
855
  ),
802
856
  )
803
857
  }
@@ -811,7 +865,7 @@ window.__ModuleLoader__.load({
811
865
  * @param {object} item - compactEntry 产出的一条明细
812
866
  * @param {object} cost - totals.cost(取币种与可读性标记)
813
867
  */
814
- function detailPartsOf(React, item, cost) {
868
+ function detailPartsOf(React, item, cost, options = {}) {
815
869
  const h = React.createElement
816
870
  const parts = []
817
871
  if (item.contextBeforeTokens !== null && item.contextBeforeTokens !== undefined) {
@@ -827,7 +881,7 @@ window.__ModuleLoader__.load({
827
881
  parts.push(h('span', { style: { color: item.contextChars >= 10_000 ? WARN : INK3 } }, `工具结果 ${formatChars(item.contextChars)}`))
828
882
  }
829
883
  const route = routeTextOf(item)
830
- if (route !== '') parts.push(route)
884
+ if (route && options.hideRoute !== true) parts.push(route)
831
885
  if (item.plugin !== null && item.plugin !== undefined) parts.push(sourceLabel(item.plugin))
832
886
  return parts.flatMap((part, index) => (index === 0 ? [part] : [' · ', part]))
833
887
  }
@@ -901,6 +955,14 @@ window.__ModuleLoader__.load({
901
955
  /** tab 类型判别串,`openTab('ledger.cost', …)` 用的就是它。 */
902
956
  const LEDGER_KIND = 'ledger.cost'
903
957
 
958
+ /** 读回快照时的分页参数:一次最多 400 行(宿主 maxLines 的常见上限),最多翻 20 页。 */
959
+ const PAGE_LINES = 400
960
+ const MAX_PAGES = 20
961
+ /** 文本总量的硬上限:超过就不是快照了(Host 侧 maxBytes 是 256KB) */
962
+ const MAX_CHARS = 1_500_000
963
+ // 注意:自动刷新间隔 REFRESH_MS 定义在 panel-view.js(组件住在那里)。
964
+ // 打包时四个模块共用同一个作用域,重名会直接 SyntaxError —— 这是产物测试抓出来的。
965
+
904
966
  /**
905
967
  * 硬依赖:没有右栏 tab 服务,这个插件什么都不用做。
906
968
  *
@@ -997,16 +1059,33 @@ window.__ModuleLoader__.load({
997
1059
  const bytes = stat.value?.bytes
998
1060
  if (typeof bytes === 'number' && bytes > 1024 * 1024) return { error: '快照文件过大,已跳过' }
999
1061
 
1000
- let page
1001
- try {
1002
- page = await files.read(sessionId, absolutePath, { offset: 0, limit: 400 }, opts.signal)
1003
- } catch (error) {
1004
- return { error: stringifyError(error) }
1062
+ // 宿主的 workspaceFiles.read 是**按行分页**的(offset=首页行号,limit=最大行数,
1063
+ // 且 limit 不得超过宿主配置的 maxLines)。一份 20 条明细的快照实测 461~587 行,
1064
+ // 而这里原来只读一页 400 行并要求 eof —— 结果是任何稍成熟点的会话打开面板都显示
1065
+ // "读取失败:快照过长"。必须翻页读完,而不是把页宽当文件长度。
1066
+ let text = ''
1067
+ let offset = 1
1068
+ let eof = false
1069
+ for (let page = 0; page < MAX_PAGES && !eof; page += 1) {
1070
+ let result
1071
+ try {
1072
+ result = await files.read(sessionId, absolutePath, { offset, limit: PAGE_LINES }, opts.signal)
1073
+ } catch (error) {
1074
+ return { error: stringifyError(error) }
1075
+ }
1076
+ if (!result?.ok) return { error: '读取快照失败' }
1077
+ const chunk = result.value?.text
1078
+ if (typeof chunk !== 'string') return { error: '快照内容为空' }
1079
+ // 分页边界可能落在换行上也可能不落:拼之前补一个换行,避免两页粘成一行坏 JSON
1080
+ if (text.length > 0 && !text.endsWith('\n')) text += '\n'
1081
+ text += chunk
1082
+ if (text.length > MAX_CHARS) return { error: '快照文件过大,已跳过' }
1083
+ eof = result.value?.eof !== false
1084
+ const lines = typeof result.value?.lines === 'number' ? result.value.lines : 0
1085
+ if (lines <= 0) break
1086
+ offset += lines
1005
1087
  }
1006
- if (!page?.ok) return { error: '读取快照失败' }
1007
- const text = page.value?.text
1008
- if (typeof text !== 'string') return { error: '快照内容为空' }
1009
- if (page.value?.eof === false) return { error: '快照过长,未能一次读完' }
1088
+ if (!eof) return { error: '快照过长,分页读取未完成' }
1010
1089
 
1011
1090
  try {
1012
1091
  const parsed = JSON.parse(text)
@@ -1153,6 +1232,8 @@ window.__ModuleLoader__.load({
1153
1232
  // 硬依赖必须跟着产物一起导出:cordis 靠它判断"什么时候允许 apply",
1154
1233
  // 漏了就会在 apply 里抛 cannot get property "..." without inject,把宿主启动带崩。
1155
1234
  exports.inject = inject;
1235
+ // 纯函数面:只给测试与诊断用(renderPayload 等),不参与宿主运行
1236
+ exports.__internal = __internal;
1156
1237
  return module.exports;
1157
1238
  },
1158
1239
  });
package/lib/client.src.js CHANGED
@@ -43,6 +43,14 @@ const LEDGER_ID = '@lingda-ai/ledger'
43
43
  /** tab 类型判别串,`openTab('ledger.cost', …)` 用的就是它。 */
44
44
  const LEDGER_KIND = 'ledger.cost'
45
45
 
46
+ /** 读回快照时的分页参数:一次最多 400 行(宿主 maxLines 的常见上限),最多翻 20 页。 */
47
+ const PAGE_LINES = 400
48
+ const MAX_PAGES = 20
49
+ /** 文本总量的硬上限:超过就不是快照了(Host 侧 maxBytes 是 256KB) */
50
+ const MAX_CHARS = 1_500_000
51
+ // 注意:自动刷新间隔 REFRESH_MS 定义在 panel-view.js(组件住在那里)。
52
+ // 打包时四个模块共用同一个作用域,重名会直接 SyntaxError —— 这是产物测试抓出来的。
53
+
46
54
  /**
47
55
  * 硬依赖:没有右栏 tab 服务,这个插件什么都不用做。
48
56
  *
@@ -153,16 +161,33 @@ export function createFetchView(ctx) {
153
161
  const bytes = stat.value?.bytes
154
162
  if (typeof bytes === 'number' && bytes > 1024 * 1024) return { error: '快照文件过大,已跳过' }
155
163
 
156
- let page
157
- try {
158
- page = await files.read(sessionId, absolutePath, { offset: 0, limit: 400 }, opts.signal)
159
- } catch (error) {
160
- return { error: stringifyError(error) }
164
+ // 宿主的 workspaceFiles.read 是**按行分页**的(offset=首页行号,limit=最大行数,
165
+ // 且 limit 不得超过宿主配置的 maxLines)。一份 20 条明细的快照实测 461~587 行,
166
+ // 而这里原来只读一页 400 行并要求 eof —— 结果是任何稍成熟点的会话打开面板都显示
167
+ // "读取失败:快照过长"。必须翻页读完,而不是把页宽当文件长度。
168
+ let text = ''
169
+ let offset = 1
170
+ let eof = false
171
+ for (let page = 0; page < MAX_PAGES && !eof; page += 1) {
172
+ let result
173
+ try {
174
+ result = await files.read(sessionId, absolutePath, { offset, limit: PAGE_LINES }, opts.signal)
175
+ } catch (error) {
176
+ return { error: stringifyError(error) }
177
+ }
178
+ if (!result?.ok) return { error: '读取快照失败' }
179
+ const chunk = result.value?.text
180
+ if (typeof chunk !== 'string') return { error: '快照内容为空' }
181
+ // 分页边界可能落在换行上也可能不落:拼之前补一个换行,避免两页粘成一行坏 JSON
182
+ if (text.length > 0 && !text.endsWith('\n')) text += '\n'
183
+ text += chunk
184
+ if (text.length > MAX_CHARS) return { error: '快照文件过大,已跳过' }
185
+ eof = result.value?.eof !== false
186
+ const lines = typeof result.value?.lines === 'number' ? result.value.lines : 0
187
+ if (lines <= 0) break
188
+ offset += lines
161
189
  }
162
- if (!page?.ok) return { error: '读取快照失败' }
163
- const text = page.value?.text
164
- if (typeof text !== 'string') return { error: '快照内容为空' }
165
- if (page.value?.eof === false) return { error: '快照过长,未能一次读完' }
190
+ if (!eof) return { error: '快照过长,分页读取未完成' }
166
191
 
167
192
  try {
168
193
  const parsed = JSON.parse(text)
package/lib/guard.js CHANGED
@@ -68,7 +68,14 @@ export function createBudgetGuard({ store, config, deliver }) {
68
68
 
69
69
  /** agent/request waterfall:只做降级,不做事实注入 */
70
70
  async function onRequest(payload, next) {
71
- const config0 = await next()
71
+ // next() 自己也可能抛(上游适配器失败)。它必须在 try 里:否则一次上游异常会
72
+ // 从这个 waterfall 直接冒泡出去,而这里的职责只是"要不要改路由",不是"替上游报错"。
73
+ let config0
74
+ try {
75
+ config0 = await next()
76
+ } catch (error) {
77
+ throw error // 上游失败仍然要冒泡(那不是我们能降级的事),只是不进下面的降级逻辑
78
+ }
72
79
  try {
73
80
  if (!downgrade || !budgetEnabled(config)) return config0
74
81
  if (!downgrade.provider && !downgrade.model) return config0
package/lib/index.js CHANGED
@@ -24,6 +24,7 @@ import { createBudgetGuard } from './guard.js'
24
24
  import { createLedgerQueryTool } from './audit-tool.js'
25
25
  import { makeBudgetMessage } from './budget-message.js'
26
26
  import { createSnapshotPublisher } from './snapshot-file.js'
27
+ import { PANEL_DIR } from './panel-path.js'
27
28
  import { createTraceSink } from './trace-file.js'
28
29
 
29
30
  export const name = 'ledger'
@@ -119,6 +120,16 @@ export function apply(ctx, rawConfig) {
119
120
 
120
121
  // 右侧栏面板的数据通道:Host 落快照 JSON,浏览器半用 workspace 文件 remote 读回。
121
122
  // 默认关闭(config.panel.enabled),打开才有写盘副作用。
123
+ // 客户端的读路径固定是 <session cwd>/.dsh/ledger/<safe>.json(panel-path.js 两侧共用)。
124
+ // 自定义 panel.dir 会让 Host 写到别处、面板读空——这不是"配置不生效",是"看不到",
125
+ // 必须显性说出来,否则用户会以为是插件坏了。
126
+ if (config.panel?.enabled === true && (config.panel.dir ?? PANEL_DIR) !== PANEL_DIR) {
127
+ console.warn(
128
+ `[ledger] panel.dir=${JSON.stringify(config.panel.dir)} 与浏览器侧的固定读路径 ${PANEL_DIR} 不一致,`
129
+ + '面板将读不到快照。面板开启时请保持默认目录。',
130
+ )
131
+ }
132
+
122
133
  const publisher =
123
134
  config.panel?.enabled === true
124
135
  ? createSnapshotPublisher({
@@ -201,10 +212,20 @@ export function apply(ctx, rawConfig) {
201
212
  pricing: pricingMeta,
202
213
  config,
203
214
  }
204
- // 仓库既有插件统一用 ctx.provide 暴露服务(见 lingzhi-core / lingzhi-workbench)
205
- ctx.provide('ledger', api)
215
+ // 仓库既有插件统一用 ctx.provide 暴露服务(见 lingzhi-core / lingzhi-workbench)。
216
+ // 但同一个 ctx 被重复装配时(HMR、禁用后重新启用)provide 会抛 "service already exists",
217
+ // 而它在 apply 里抛=宿主启动失败。服务已经在了就复用,插件其余部分照常工作。
218
+ try {
219
+ ctx.provide('ledger', api)
220
+ } catch (error) {
221
+ console.warn('[ledger] 服务 ledger 已存在,复用既有实例(重复装配):', error?.message ?? error)
222
+ }
206
223
 
224
+ let disposed = false
207
225
  const cleanup = () => {
226
+ // 幂等:宿主可能既跑 effect 清理又触发 dispose 事件,重复释放会二次 flush/close
227
+ if (disposed) return
228
+ disposed = true
208
229
  publisher?.dispose()
209
230
  traceSink?.dispose()
210
231
  }
package/lib/ledger.js CHANGED
@@ -44,6 +44,8 @@ const COMPACTION_PREFIX = 'compaction/'
44
44
  export function createLedger({ store, pricing, attribution, trace, onEntry, cwdOf, identity, now = () => Date.now() }) {
45
45
  let failures = 0
46
46
  let handled = 0
47
+ /** 无 usage 的模型事件数(assistant/attempt 之类)。它们是"尝试",不是计费调用。 */
48
+ let skipped = 0
47
49
 
48
50
  /**
49
51
  * 唯一入账出口。`onEntry` 是给 Budget Guard 的正式钩子,
@@ -91,6 +93,15 @@ export function createLedger({ store, pricing, attribution, trace, onEntry, cwdO
91
93
  const step = event.step ?? 0
92
94
 
93
95
  const usage = normalizeUsage(event.usage ?? event.message?.usage)
96
+ // 没有 usage 的模型事件(assistant/attempt)不是计费调用,**不能入账**:
97
+ // - 它会变成一条 unknown(no-usage),而 guard 见到 unknownEntries > 0 就整条放弃预算,
98
+ // 于是"预算降级"静默失效,面板还会误报"合计偏低"(实测注入 0 条预算事实);
99
+ // - 它也没有任何金额可记,记了只会在明细里多一行"未知"噪音。
100
+ // 计数留在 stats.skipped 里,仍然可观测。
101
+ if (usage === null) {
102
+ skipped += 1
103
+ return
104
+ }
94
105
  const route = routeOf(event)
95
106
  const cost = pricing.costOf(usage, route)
96
107
 
@@ -255,6 +266,6 @@ export function createLedger({ store, pricing, attribution, trace, onEntry, cwdO
255
266
  pendingCompaction.delete(sessionId)
256
267
  identityBySession.delete(sessionId)
257
268
  },
258
- stats: () => ({ handled, failures }),
269
+ stats: () => ({ handled, failures, skipped }),
259
270
  }
260
271
  }
package/lib/panel-view.js CHANGED
@@ -18,7 +18,14 @@ function routeTextOf(item) {
18
18
 
19
19
  /** 上下文规模用 k 缩写:42.0k 比 42,000 更适合一眼扫 */
20
20
  /** 四档都齐才给总数:缺一档就当不知道,不把缺失当 0 加进去(否则会造出一个假数) */
21
- export function tokensTotal(tokens) {
21
+ export /** 实付 + 省下 = "如果没有缓存本来要花的钱",也就是节省比例的分母。 */
22
+ function grossAmountOf(view) {
23
+ const saved = view?.totals?.saved?.amount
24
+ const spent = view?.totals?.cost?.amount
25
+ return typeof saved === 'number' && typeof spent === 'number' ? saved + spent : null
26
+ }
27
+
28
+ function tokensTotal(tokens) {
22
29
  if (!tokens || typeof tokens !== 'object') return null
23
30
  const parts = [tokens.input, tokens.output, tokens.cacheRead, tokens.cacheWrite]
24
31
  if (!parts.every((v) => Number.isFinite(v))) return null
@@ -51,6 +58,9 @@ const GOOD = '#2f7d64'
51
58
  /** "谁花的"折叠前先显示几条:6 条是 300px 宽度下不做滚动还看得完的上限 */
52
59
  const SOURCE_HEAD = 6
53
60
 
61
+ /** 面板自动刷新间隔:Host 落盘节流 3s,这里 5s,够快又不空转。 */
62
+ const REFRESH_MS = 5000
63
+
54
64
  // 老快照(没有 pricing 字段)的兜底文案。新快照一律由 pricingNoteOf 生成,
55
65
  // 因为"内置还是自定义、哪天的价、有没有被忽略的模型"只能从数据里读,不能写死。
56
66
  const PRICING_NOTE = '按内置官方价估算 · 2026-11-19'
@@ -148,7 +158,7 @@ function pricingBanner(React, note) {
148
158
 
149
159
  const INK = '#1f2733'
150
160
  const INK2 = '#5a6472'
151
- const INK3 = '#6f7a89'
161
+ const INK3 = '#64707f'
152
162
 
153
163
  /**
154
164
  * 时间一律按**本地时区**显示。
@@ -235,19 +245,28 @@ function makeLedgerBody(React, fetchView) {
235
245
  const [view, setView] = React.useState(undefined)
236
246
  const [busy, setBusy] = React.useState(false)
237
247
  const [expanded, setExpanded] = React.useState(false)
248
+ // 请求序号:切会话时旧请求可能后到,不能让它把新会话的读数覆盖掉
249
+ const seq = React.useRef(0)
238
250
 
239
251
  const refresh = React.useCallback(async () => {
240
252
  if (sessionId === null) return
253
+ const mine = (seq.current += 1)
241
254
  setBusy(true)
242
255
  try {
243
- setView(await fetchView(sessionId))
256
+ const next = await fetchView(sessionId)
257
+ if (mine === seq.current) setView(next)
244
258
  } finally {
245
- setBusy(false)
259
+ if (mine === seq.current) setBusy(false)
246
260
  }
247
261
  }, [sessionId])
248
262
 
249
263
  React.useEffect(() => {
264
+ // 切会话先清空:宁可闪一帧"正在读取",也不能让 B 会话标题下挂着 A 会话的金额
265
+ setView(undefined)
250
266
  void refresh()
267
+ // 成本是持续读数,不是一张照片:挂载后自动刷新(Host 侧 3 秒落盘节流)
268
+ const timer = setInterval(() => { void refresh() }, REFRESH_MS)
269
+ return () => clearInterval(timer)
251
270
  }, [refresh])
252
271
 
253
272
  const head = h(
@@ -343,7 +362,9 @@ function summaryOf(totals, list) {
343
362
  const unattributed = list.find((item) => item?.plugin === 'unattributed')
344
363
  const lost = typeof unattributed?.entries === 'number' && unattributed.entries > 0 ? unattributed.entries : null
345
364
  if (lost === null) return `${entries} 次调用`
346
- if (lost === entries) return `${entries} 次调用 · 来源未配置`
365
+ // 全部落在 unattributed 时不能写"来源未配置":那个桶里既有"本会话没调用工具"(no-signal),
366
+ // 也有"调了工具但没登记 owner"(no-origin)。写"配置"会把纯聊天会话指去改配置。
367
+ if (lost === entries) return `${entries} 次调用 · 归因无信号`
347
368
  return `${entries} 次调用 · ${lost} 次未归因`
348
369
  }
349
370
 
@@ -498,16 +519,22 @@ function renderPayload(React, view, sessionId, head, options = {}) {
498
519
  : h(
499
520
  'div',
500
521
  { style: { marginTop: 4, fontSize: 11, lineHeight: 1.6, color: GOOD, fontVariantNumeric: 'tabular-nums' } },
501
- `缓存命中已省 ${formatAmount(view.totals.saved.amount, view.totals.saved.currency)}${
522
+ `缓存已省 ${formatAmount(view.totals.saved.amount, view.totals.saved.currency)}${
502
523
  typeof view.totals.savedShare === 'number'
503
- ? ` · 少花 ${formatShare(view.totals.savedShare)}`
524
+ ? ` · 如未命中需 ${formatAmount(grossAmountOf(view), view.totals.saved.currency)}(少花 ${formatShare(view.totals.savedShare)})`
504
525
  : ''
505
526
  }`,
506
527
  ),
507
528
  ),
508
529
  // 预算条:只有配置了 limit 才画,未计价时不假装花了 0
509
- view.budget !== null && view.budget !== undefined
530
+ view.budget === null || view.budget === undefined
510
531
  ? h(
532
+ 'div',
533
+ { style: { padding: '0 14px 8px', fontSize: 11, color: INK3 } },
534
+ // 静默消失会被读成"这个面板没有这个功能";说清是配置项,用户才知道怎么开
535
+ '未设预算 · 配 budget.limit 后这里显示"还能问几次"',
536
+ )
537
+ : h(
511
538
  'div',
512
539
  { style: { padding: '0 14px 10px' } },
513
540
  h(
@@ -533,8 +560,7 @@ function renderPayload(React, view, sessionId, head, options = {}) {
533
560
  },
534
561
  }),
535
562
  ),
536
- )
537
- : null,
563
+ ),
538
564
  // token 四档
539
565
  h(
540
566
  'div',
@@ -552,8 +578,18 @@ function renderPayload(React, view, sessionId, head, options = {}) {
552
578
  formatAmount(parts?.cacheRead, cost.currency),
553
579
  `${formatTokens(tokens.cacheRead)} tok${hitRateOf(totals.cacheHitRate)}`,
554
580
  ),
555
- rowOf(React, '缓存写', formatAmount(parts?.cacheWrite, cost.currency), `${formatTokens(tokens.cacheWrite)} tok`),
556
- rowOf(React, '输出', formatAmount(parts?.output, cost.currency), `${formatTokens(tokens.output)} tok · 含 reasoning`),
581
+ // 缓存写:DeepSeek 没有独立写价,这一档恒为 0。占一行"0 tok ¥0.0000"只是噪音,
582
+ // 但真的产生了写 token 时必须画出来(其它 provider 会有)
583
+ (tokens.cacheWrite ?? 0) > 0 || (parts?.cacheWrite ?? 0) > 0
584
+ ? rowOf(React, '缓存写', formatAmount(parts?.cacheWrite, cost.currency), `${formatTokens(tokens.cacheWrite)} tok`)
585
+ : null,
586
+ rowOf(
587
+ React,
588
+ '输出',
589
+ formatAmount(parts?.output, cost.currency),
590
+ // "含 reasoning" 在 reasoning=0 时是假陈述
591
+ `${formatTokens(tokens.output)} tok${(tokens.reasoning ?? 0) > 0 ? ' · 含 reasoning' : ''}`,
592
+ ),
557
593
  ),
558
594
  ),
559
595
  // 来源
@@ -637,10 +673,15 @@ function renderPayload(React, view, sessionId, head, options = {}) {
637
673
  : h(
638
674
  'span',
639
675
  { style: { fontSize: 11, color: INK3, fontVariantNumeric: 'tabular-nums', whiteSpace: 'nowrap' } },
640
- `最贵一步 ${formatAmount(peak.amount, cost.currency)}`,
676
+ // 只说"最贵"会让人去优化那一步;补上定位与占比才知道值不值得优化
677
+ `最贵 ${typeof peak.turn === 'number' ? `T${peak.turn}·S${peak.step ?? '—'} ` : ''}${formatAmount(peak.amount, cost.currency)}${
678
+ moneyKnown && cost.amount > 0
679
+ ? ` · 占 ${formatShare(peak.amount / cost.amount)}`
680
+ : ''
681
+ }`,
641
682
  ),
642
683
  ),
643
- recent.slice(0, 5).map((item, index) =>
684
+ recent.slice(0, 5).map((item, index, all) =>
644
685
  h(
645
686
  'div',
646
687
  { key: `r-${index}`, style: { padding: '4px 0' } },
@@ -669,12 +710,30 @@ function renderPayload(React, view, sessionId, head, options = {}) {
669
710
  // 第二行的优先级 = "为什么这一步贵":压缩收益 > 本次 token 量 > 工具体量 > 路由 > 归属。
670
711
  // 380px 下这一行必定会被省略号截断,所以要让它从右边开始丢信息,
671
712
  // 而不是从左边(左边留住的是解释,右边留住的是标识)。
672
- ...detailPartsOf(React, item, cost),
713
+ ...detailPartsOf(React, item, cost, {
714
+ // 同一段的模型名大多相同,重复 N 遍等于把"为什么贵"的信息挤出去
715
+ hideRoute: index > 0 && routeTextOf(item) === routeTextOf(all[index - 1]),
716
+ }),
673
717
  ),
674
718
  ),
675
719
  ),
676
720
  )
677
721
  : null,
722
+ // 结论行:② 问的是"为什么贵",一张等高的小额明细表回答不了。
723
+ // 只在"命中这一档确实占大头"时给一句人话,其余情况闭嘴(不为了凑结论而编结论)。
724
+ (() => {
725
+ if (!moneyKnown || typeof parts?.cacheRead !== 'number' || cost.amount <= 0) return null
726
+ const share = parts.cacheRead / cost.amount
727
+ const calls = totals.entries ?? 0
728
+ if (share < 0.5 || calls < 3) return null
729
+ const totalTok = tokens ? (tokens.input ?? 0) + (tokens.cacheRead ?? 0) + (tokens.output ?? 0) : null
730
+ return h(
731
+ 'div',
732
+ { style: { padding: '0 14px 10px', fontSize: 11, lineHeight: 1.65, color: INK2 } },
733
+ `钱主要花在重复送出的上下文:命中一档 ${formatAmount(parts.cacheRead, cost.currency)}(占 ${formatShare(share)})`,
734
+ totalTok === null ? '' : `,${calls} 次调用共送出 ${formatTokensCompact(totalTok)} tok`,
735
+ )
736
+ })(),
678
737
  // 会话对比:只给其他会话,自己已经在顶部
679
738
  others.length > 0
680
739
  ? h(
@@ -702,19 +761,14 @@ function renderPayload(React, view, sessionId, head, options = {}) {
702
761
  ),
703
762
  )
704
763
  : null,
705
- // 页脚
706
- h(
707
- 'div',
708
- { style: { padding: '6px 14px 12px', fontSize: 11, color: INK3 } },
709
- `快照 ${formatLocalTime(view.generatedAt)}`,
710
- ),
764
+ // 页脚:快照时间 + 费率来源合成一行,省 20px 且不会出现"两个日期像两个时间戳"
711
765
  h(
712
766
  'div',
713
767
  {
714
- // 费率脚注:自定义生效用正文色、无效用警示色,绝不与"内置价"混成一色
715
- style: { padding: '0 14px 12px', fontSize: 11, color: note.warn ? WARN : INK3 },
768
+ // 费率无效时整行转警示色:这是"金额不可信"的信号,不能和普通脚注同色
769
+ style: { padding: '6px 14px 12px', fontSize: 11, lineHeight: 1.65, color: note.warn ? WARN : INK3 },
716
770
  },
717
- note.text,
771
+ `快照 ${formatLocalTime(view.generatedAt)} · ${note.text}`,
718
772
  ),
719
773
  )
720
774
  }
@@ -728,7 +782,7 @@ function renderPayload(React, view, sessionId, head, options = {}) {
728
782
  * @param {object} item - compactEntry 产出的一条明细
729
783
  * @param {object} cost - totals.cost(取币种与可读性标记)
730
784
  */
731
- function detailPartsOf(React, item, cost) {
785
+ function detailPartsOf(React, item, cost, options = {}) {
732
786
  const h = React.createElement
733
787
  const parts = []
734
788
  if (item.contextBeforeTokens !== null && item.contextBeforeTokens !== undefined) {
@@ -744,7 +798,7 @@ function detailPartsOf(React, item, cost) {
744
798
  parts.push(h('span', { style: { color: item.contextChars >= 10_000 ? WARN : INK3 } }, `工具结果 ${formatChars(item.contextChars)}`))
745
799
  }
746
800
  const route = routeTextOf(item)
747
- if (route !== '') parts.push(route)
801
+ if (route && options.hideRoute !== true) parts.push(route)
748
802
  if (item.plugin !== null && item.plugin !== undefined) parts.push(sourceLabel(item.plugin))
749
803
  return parts.flatMap((part, index) => (index === 0 ? [part] : [' · ', part]))
750
804
  }
@@ -57,10 +57,24 @@ export function buildPanelPayload(snapshot, sources, { maxBytes = 262144, budget
57
57
  // 费率来源:面板必须能说出"这些钱是按哪套价算的"。
58
58
  // null 表示未传(老调用方),面板退化成只显示内置基准日。
59
59
  pricing: pricing ?? null,
60
+ // 这个标志必须落在 payload 里:它同时是"给用户看的提示"和"给诊断用的计数"。
61
+ // 只把它当返回值,面板那一侧永远读到 undefined(历史上就是这样丢的)。
62
+ truncated: false,
60
63
  }
61
64
  const full = { ...base, sources: sources?.sources ?? [], sourceCount: sources?.sourceCount ?? null }
62
- const bytes = Buffer.byteLength(JSON.stringify(full))
63
- return bytes <= maxBytes ? { payload: full, truncated: false } : { payload: base, truncated: true }
65
+ if (Buffer.byteLength(JSON.stringify(full)) <= maxBytes) return { payload: full, truncated: false }
66
+
67
+ // 一级降级:去掉 sources,保留最近明细
68
+ const slim = { ...base, truncated: true }
69
+ if (Buffer.byteLength(JSON.stringify(slim)) <= maxBytes) return { payload: slim, truncated: true }
70
+
71
+ // 二级降级:连明细也保不住时,只留合计与 Top 来源。
72
+ // 没有这一步,maxBytes 就只是个愿望——实测 20 条明细的 base 仍有 9.8KB。
73
+ const minimal = { ...base, recent: [], peak: null, overview: null, truncated: true }
74
+ if (Buffer.byteLength(JSON.stringify(minimal)) <= maxBytes) return { payload: minimal, truncated: true }
75
+
76
+ // 连合计都超限(maxBytes 配得极小):仍然写,但标明截断,别让"写失败"变成静默
77
+ return { payload: { ...minimal, totals: null }, truncated: true }
64
78
  }
65
79
 
66
80
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lingda-ai/dsh-plugin-ledger",
3
- "version": "0.1.7",
3
+ "version": "0.1.8",
4
4
  "description": "DSH 插件搜索入口:运行时账本(成本/用量观测)。自包含单包,不依赖其他 npm 包,便于从镜像源安装。",
5
5
  "license": "Apache-2.0",
6
6
  "keywords": [