@lingda-ai/dsh-plugin-ledger 0.1.13 → 0.1.14

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/lib/config.js CHANGED
@@ -61,6 +61,7 @@ export const DEFAULT_CONFIG = Object.freeze({
61
61
  dir: '.dsh/ledger', // 相对 process.cwd();也可给绝对路径
62
62
  intervalMs: 3000, // 同一会话两次落盘的最小间隔
63
63
  maxBytes: 262144, // 超过则只写 totals + topSources
64
+ windowHours: 24, // 快照里附带"最近 N 小时"的增量(0 = 不带)
64
65
  },
65
66
  })
66
67
 
package/lib/index.js CHANGED
@@ -137,6 +137,8 @@ export function apply(ctx, rawConfig) {
137
137
  dir: config.panel.dir,
138
138
  intervalMs: config.panel.intervalMs,
139
139
  maxBytes: config.panel.maxBytes,
140
+ // 窗口增量的小时数(默认 24):塔台报告用它回答"这一段花了多少"
141
+ windowHours: config.panel.windowHours,
140
142
  rootOf: (sessionId) => sessionRoots.get(sessionId) ?? process.cwd(),
141
143
  // 预算读数:面板画进度条用,口径来自配置,不由前端推算
142
144
  budget: { limit: config.budget?.limit ?? null, currency: config.pricing?.currency ?? 'CNY' },
@@ -69,6 +69,9 @@ export function buildPanelPayload(snapshot, sources, { maxBytes = 262144, budget
69
69
  // 费率来源:面板必须能说出"这些钱是按哪套价算的"。
70
70
  // null 表示未传(老调用方),面板退化成只显示内置基准日。
71
71
  pricing: pricing ?? null,
72
+ // 窗口增量:预算/报告要回答"最近 N 小时花了多少",累计值答不了这个问题。
73
+ // null = 本次没有请求窗口(老调用方),消费方据此隐藏该口径,而不是当成 0。
74
+ window: snapshot?.window ?? null,
72
75
  // 这个标志必须落在 payload 里:它同时是"给用户看的提示"和"给诊断用的计数"。
73
76
  // 只把它当返回值,面板那一侧永远读到 undefined(历史上就是这样丢的)。
74
77
  truncated: false,
@@ -230,6 +233,8 @@ export function createSnapshotPublisher(options) {
230
233
  const intervalMs = Math.max(0, Number(options.intervalMs ?? 0))
231
234
  const maxBytes = Math.max(1024, Number(options.maxBytes ?? 262144))
232
235
  const budget = options.budget ?? null // {limit, currency} 由调用方给(配置侧)
236
+ // 窗口口径的小时数:由配置给(默认 24),随快照一起下发,消费方不需要猜
237
+ const windowHours = Number(options.windowHours) > 0 ? Number(options.windowHours) : 24
233
238
  const overview = typeof options.overview === 'function' ? options.overview : null
234
239
  const now = options.now ?? Date.now
235
240
 
@@ -245,7 +250,7 @@ export function createSnapshotPublisher(options) {
245
250
  function publishNow(sessionId) {
246
251
  if (typeof sessionId !== 'string' || sessionId.length === 0) return false
247
252
  try {
248
- const snapshot = options.snapshot(sessionId)
253
+ const snapshot = options.snapshot(sessionId, { windowHours })
249
254
  if (snapshot === null || snapshot === undefined) return false // 该会话已淘汰
250
255
  const sources = typeof options.sources === 'function' ? options.sources(sessionId) : null
251
256
  const ov = overview === null ? null : overview()
package/lib/store.js CHANGED
@@ -226,20 +226,78 @@ export class LedgerStore {
226
226
  }
227
227
  }
228
228
 
229
- snapshot(sessionId, { lastN = 20 } = {}) {
229
+ snapshot(sessionId, { lastN = 20, windowHours = null } = {}) {
230
230
  const bucket = this.#sessions.get(sessionId)
231
231
  if (!bucket) return null
232
232
  const top = [...bucket.bySource.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3)
233
+ const window = typeof windowHours === 'number' && windowHours > 0 ? this.windowTotals(sessionId, { hours: windowHours }) : null
233
234
  return Object.freeze({
234
235
  sessionId,
235
236
  totals: this.totals(sessionId),
236
237
  topSources: top.map(([plugin, amount]) => ({ plugin, amount })),
237
238
  recent: bucket.entries.last(lastN),
238
239
  trace: bucket.trace ? bucket.trace.last(lastN) : null,
240
+ // 窗口增量:给"最近 N 小时花了多少"这个问题一个**有口径**的答案。
241
+ // null = 调用方没要(老调用方),不冒充 0。
242
+ window,
239
243
  generatedAt: Date.now(),
240
244
  })
241
245
  }
242
246
 
247
+ /**
248
+ * 窗口内增量:只读环上条目,按 `at >= since` 聚合。
249
+ *
250
+ * 为什么在环上重算而不是维护增量累加器:
251
+ * 环容量有界(capacity 条),快照落盘本身被 intervalMs 节流(默认 3s),
252
+ * 一次遍历的代价远低于"多一套增量状态与它的过期逻辑"。
253
+ *
254
+ * `covered` 是诚实性字段:
255
+ * - true = 环里最老的条目早于窗口起点,窗口内的条目都在,数字完整;
256
+ * - false = 环已被写过一轮,窗口起点之前的条目被淘汰,**窗口可能不完整**。
257
+ * 消费方(例如塔台的报告)据此决定要不要标注"口径偏小"。
258
+ *
259
+ * @param {string} sessionId
260
+ * @param {{ hours?: number, now?: number }} [opts]
261
+ */
262
+ windowTotals(sessionId, { hours = 24, now = Date.now() } = {}) {
263
+ const bucket = this.#sessions.get(sessionId)
264
+ if (!bucket) return null
265
+ const spanHours = Math.max(1, Number(hours) || 24)
266
+ const since = now - spanHours * 3_600_000
267
+ const all = bucket.entries.toArray()
268
+ let cost = 0
269
+ let saved = 0
270
+ let entries = 0
271
+ let known = 0
272
+ let unknown = 0
273
+ let currency = null
274
+ for (const item of all) {
275
+ const at = typeof item?.at === 'number' ? item.at : 0
276
+ if (at > 0 && at < since) continue
277
+ entries += 1
278
+ if (item?.cost?.kind === 'known') {
279
+ cost += item.cost.amount
280
+ known += 1
281
+ currency = item.cost.currency ?? currency
282
+ } else {
283
+ unknown += 1
284
+ }
285
+ if (typeof item?.savedAmount === 'number' && Number.isFinite(item.savedAmount)) saved += item.savedAmount
286
+ }
287
+ const oldestAt = all.length > 0 && typeof all[0]?.at === 'number' ? all[0].at : null
288
+ return Object.freeze({
289
+ hours: spanHours,
290
+ since,
291
+ cost: Math.round(cost * 1e6) / 1e6,
292
+ saved: Math.round(saved * 1e6) / 1e6,
293
+ entries,
294
+ knownEntries: known,
295
+ unknownEntries: unknown,
296
+ currency: currency ?? bucket.currency ?? null,
297
+ covered: oldestAt !== null && oldestAt <= since,
298
+ })
299
+ }
300
+
243
301
  /**
244
302
  * 全部来源(不截断到 Top3)。
245
303
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lingda-ai/dsh-plugin-ledger",
3
- "version": "0.1.13",
3
+ "version": "0.1.14",
4
4
  "description": "DSH 插件搜索入口:运行时账本(成本/用量观测)。自包含单包,不依赖其他 npm 包,便于从镜像源安装。",
5
5
  "license": "Apache-2.0",
6
6
  "keywords": [