@lingda-ai/dsh-plugin-ledger 0.1.3 → 0.1.4

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/store.js ADDED
@@ -0,0 +1,330 @@
1
+ /**
2
+ * 会话级账本存储。
3
+ *
4
+ * 性能与内存:
5
+ * - 每个会话固定两块环(账本条目 + 行为流水),容量预先固定,不随会话变长增长;
6
+ * - 会话数受 maxSessions 约束,Map 的插入顺序直接当 LRU 用,淘汰 O(1);
7
+ * - 聚合值是增量维护的,快照不做全量重算。
8
+ *
9
+ * 诚实性:
10
+ * - 已知金额与未知条目分开累计。unknown 不是 0,不能被平均掉。
11
+ */
12
+ import { RingBuffer } from './ring.js'
13
+ import { sumUsage } from './usage.js'
14
+
15
+ /**
16
+ * 一条条目的成本记到哪个来源桶。
17
+ *
18
+ * 三种无 primary 的情形必须分开,否则面板会把"拆不开"和"没信号"混成一个数:
19
+ * - `shared:unknown`:确实有多个已知 owner 共同贡献上下文,但无法拆到单个(多贡献者)
20
+ * - `unattributed` :完全没有归因信号(no-signal / no-origin 且无 owner)
21
+ * - `system:compaction`:压缩产生的调用,不属于任何插件
22
+ * @param {object} entry
23
+ * @returns {string}
24
+ */
25
+ export function sourceKeyOf(entry) {
26
+ const attribution = entry?.attribution
27
+ if (attribution?.system === 'compaction') return 'system:compaction'
28
+ if (typeof attribution?.primary?.plugin === 'string' && attribution.primary.plugin.length > 0) {
29
+ return attribution.primary.plugin
30
+ }
31
+ const owners = (attribution?.sharedContext ?? []).filter(
32
+ (item) => item?.note === 'shared-context-cost' && typeof item.plugin === 'string',
33
+ )
34
+ return owners.length > 0 ? 'shared:unknown' : 'unattributed'
35
+ }
36
+
37
+ export class LedgerStore {
38
+ #sessions = new Map()
39
+ #capacity
40
+ #traceCapacity
41
+ #traceEnabled
42
+ #maxSessions
43
+
44
+ /** @type {null | ((sessionId: string, record: object) => void)} */
45
+ #onTrace = null
46
+
47
+ constructor({ capacity, traceCapacity, traceEnabled, maxSessions, onTrace = null }) {
48
+ this.#capacity = capacity
49
+ this.#traceCapacity = traceCapacity
50
+ this.#traceEnabled = traceEnabled
51
+ this.#onTrace = typeof onTrace === 'function' ? onTrace : null
52
+ this.#maxSessions = maxSessions
53
+ }
54
+
55
+ #bucket(sessionId) {
56
+ let bucket = this.#sessions.get(sessionId)
57
+ if (bucket) {
58
+ // LRU touch:重新插入到队尾
59
+ this.#sessions.delete(sessionId)
60
+ this.#sessions.set(sessionId, bucket)
61
+ return bucket
62
+ }
63
+ if (this.#sessions.size >= this.#maxSessions) {
64
+ const oldest = this.#sessions.keys().next().value
65
+ if (oldest !== undefined) this.#sessions.delete(oldest)
66
+ }
67
+ bucket = {
68
+ entries: new RingBuffer(this.#capacity),
69
+ trace: this.#traceEnabled ? new RingBuffer(this.#traceCapacity) : null,
70
+ tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, missing: 0 },
71
+ bySource: new Map(), // 归因来源 → 已知金额
72
+ bySourceCount: new Map(), // 归因来源 → 条目数(来源数很少,有界)
73
+ unknownCostEntries: 0,
74
+ knownCostEntries: 0,
75
+ // 缓存命中省下的钱(能严格算出来的那一个;压缩节省只给 token,不折钱)
76
+ savedAmount: 0,
77
+ savedEntries: 0,
78
+ costAmount: 0,
79
+ // 四档金额累计:只在已知费率的条目上累加,unknown 不计入
80
+ costParts: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
81
+ currency: null,
82
+ lastStep: null,
83
+ lastAt: 0,
84
+ stepTools: new Map(), // "turn:step" → Set(toolName)
85
+ stepResultChars: new Map(), // "turn:step" → number(该步工具结果文本总字符数)
86
+ }
87
+ this.#sessions.set(sessionId, bucket)
88
+ return bucket
89
+ }
90
+
91
+ recordEntry(sessionId, entry) {
92
+ const bucket = this.#bucket(sessionId)
93
+ bucket.entries.push(entry)
94
+ bucket.lastStep = { turn: entry.turn, step: entry.step }
95
+ if (typeof entry.at === 'number') bucket.lastAt = entry.at
96
+
97
+ const usage = entry.usage
98
+ if (usage) {
99
+ bucket.tokens.input += usage.inputTokens ?? 0
100
+ bucket.tokens.output += usage.outputTokens ?? 0
101
+ bucket.tokens.cacheRead += usage.cacheReadTokens
102
+ bucket.tokens.cacheWrite += usage.cacheWriteTokens
103
+ bucket.tokens.reasoning += usage.reasoningTokens
104
+ if (!usage.complete) bucket.tokens.missing += 1
105
+ }
106
+
107
+ if (entry.cost?.kind === 'known') {
108
+ bucket.costAmount += entry.cost.amount
109
+ bucket.knownCostEntries += 1
110
+ bucket.currency = entry.cost.currency
111
+ const parts = entry.cost.parts
112
+ if (parts) {
113
+ bucket.costParts.input += parts.input ?? 0
114
+ bucket.costParts.output += parts.output ?? 0
115
+ bucket.costParts.cacheRead += parts.cacheRead ?? 0
116
+ bucket.costParts.cacheWrite += parts.cacheWrite ?? 0
117
+ }
118
+ const source = sourceKeyOf(entry)
119
+ bucket.bySource.set(source, (bucket.bySource.get(source) ?? 0) + entry.cost.amount)
120
+ bucket.bySourceCount.set(source, (bucket.bySourceCount.get(source) ?? 0) + 1)
121
+ } else {
122
+ bucket.unknownCostEntries += 1
123
+ }
124
+
125
+ // 与成本分开累加:费率未知的条目算不出节省,就和算不出成本一样处理,不冒充 0
126
+ if (typeof entry.savedAmount === 'number' && Number.isFinite(entry.savedAmount)) {
127
+ bucket.savedAmount += entry.savedAmount
128
+ bucket.savedEntries += 1
129
+ }
130
+
131
+ return bucket
132
+ }
133
+
134
+ recordTrace(sessionId, record) {
135
+ if (!this.#traceEnabled) return
136
+ const bucket = this.#bucket(sessionId)
137
+ bucket.trace?.push(record)
138
+ // 落盘钩子必须是同步且廉价的(只入队);IO 由 sink 自己合并
139
+ if (typeof this.#onTrace === 'function') this.#onTrace(sessionId, record)
140
+ }
141
+
142
+ noteToolCall(sessionId, turn, step, name) {
143
+ const bucket = this.#bucket(sessionId)
144
+ const key = `${turn}:${step}`
145
+ const set = bucket.stepTools.get(key) ?? new Set()
146
+ set.add(name)
147
+ bucket.stepTools.set(key, set)
148
+ // 只保留最近 8 个步骤的工具集合,防止长会话无限增长
149
+ if (bucket.stepTools.size > 8) {
150
+ const first = bucket.stepTools.keys().next().value
151
+ bucket.stepTools.delete(first)
152
+ }
153
+ }
154
+
155
+ /**
156
+ * 记一次工具结果的体积。同一步可以调多次工具,累加。
157
+ * 只保留最近 8 步——与 stepTools 同一窗口,避免两条索引不同步。
158
+ */
159
+ noteToolResult(sessionId, turn, step, chars) {
160
+ if (!Number.isFinite(chars) || chars <= 0) return
161
+ const bucket = this.#bucket(sessionId)
162
+ const key = `${turn}:${step}`
163
+ bucket.stepResultChars.set(key, (bucket.stepResultChars.get(key) ?? 0) + chars)
164
+ if (bucket.stepResultChars.size > 8) {
165
+ const first = bucket.stepResultChars.keys().next().value
166
+ bucket.stepResultChars.delete(first)
167
+ }
168
+ }
169
+
170
+ /**
171
+ * 最近一条模型调用的"上下文规模" = 未命中输入 + 缓存命中输入。
172
+ * 压缩前用它当前值,压缩后用下一步的值,差额才是"压缩省下的上下文"。
173
+ */
174
+ lastModelContextTokens(sessionId) {
175
+ const bucket = this.#sessions.get(sessionId)
176
+ if (!bucket) return null
177
+ const entries = bucket.entries.last(20) ?? []
178
+ for (let i = entries.length - 1; i >= 0; i -= 1) {
179
+ const entry = entries[i]
180
+ if (entry?.kind !== 'model' || entry.usage === null) continue
181
+ return (entry.usage.inputTokens ?? 0) + (entry.usage.cacheReadTokens ?? 0)
182
+ }
183
+ return null
184
+ }
185
+
186
+ /** 该步工具结果文本总字符数;没有记录就是 0(不是未知,确实没结果) */
187
+ resultCharsForStep(sessionId, turn, step) {
188
+ const bucket = this.#sessions.get(sessionId)
189
+ return bucket?.stepResultChars.get(`${turn}:${step}`) ?? 0
190
+ }
191
+
192
+ toolsForStep(sessionId, turn, step) {
193
+ const bucket = this.#sessions.get(sessionId)
194
+ return [...(bucket?.stepTools.get(`${turn}:${step}`) ?? [])]
195
+ }
196
+
197
+ totals(sessionId) {
198
+ // 只读视图:不 touch LRU。否则面板每 30s 轮询就把所有会话续命,淘汰策略会失效。
199
+ const bucket = this.#sessions.get(sessionId)
200
+ if (!bucket) {
201
+ return {
202
+ cost: { amount: null, currency: null, knownEntries: 0, unknownEntries: 0, parts: null },
203
+ saved: { amount: null, currency: null, entries: 0 },
204
+ tokens: null,
205
+ entries: 0,
206
+ }
207
+ }
208
+ return {
209
+ cost: {
210
+ // 没有任何已知条目时 amount 就是 null —— 不发布假数字
211
+ amount: bucket.knownCostEntries > 0 ? bucket.costAmount : null,
212
+ currency: bucket.currency,
213
+ knownEntries: bucket.knownCostEntries,
214
+ unknownEntries: bucket.unknownCostEntries,
215
+ // 四档金额:一条已知条目都没有时给 null(面板显示"未计价")
216
+ parts: bucket.knownCostEntries > 0 ? { ...bucket.costParts } : null,
217
+ },
218
+ // 缓存节省:没有可算的条目时 amount 为 null,面板据此不显示这一行
219
+ saved: {
220
+ amount: bucket.savedEntries > 0 ? bucket.savedAmount : null,
221
+ currency: bucket.savedEntries > 0 ? bucket.currency : null,
222
+ entries: bucket.savedEntries,
223
+ },
224
+ tokens: { ...bucket.tokens },
225
+ entries: bucket.entries.size,
226
+ }
227
+ }
228
+
229
+ snapshot(sessionId, { lastN = 20 } = {}) {
230
+ const bucket = this.#sessions.get(sessionId)
231
+ if (!bucket) return null
232
+ const top = [...bucket.bySource.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3)
233
+ return Object.freeze({
234
+ sessionId,
235
+ totals: this.totals(sessionId),
236
+ topSources: top.map(([plugin, amount]) => ({ plugin, amount })),
237
+ recent: bucket.entries.last(lastN),
238
+ trace: bucket.trace ? bucket.trace.last(lastN) : null,
239
+ generatedAt: Date.now(),
240
+ })
241
+ }
242
+
243
+ /**
244
+ * 全部来源(不截断到 Top3)。
245
+ *
246
+ * 只读聚合,纯前端无法伪造:unknown 条目不进入金额排序,但单独计数返回,
247
+ * 让调用方自己决定"未知要不要参与排名",而不是由 store 悄悄补 0。
248
+ *
249
+ * @param {string} sessionId
250
+ * @param {{ limit?: number, sort?: 'amount'|'entries'|'name' }} [opts]
251
+ */
252
+ sources(sessionId, { limit = 20, sort = 'amount' } = {}) {
253
+ const bucket = this.#sessions.get(sessionId)
254
+ if (!bucket) return null
255
+ const all = [...bucket.bySource.entries()].map(([plugin, amount]) => ({
256
+ plugin,
257
+ amount,
258
+ entries: bucket.bySourceCount.get(plugin) ?? 0,
259
+ }))
260
+ const cmp = {
261
+ amount: (a, b) => b.amount - a.amount || a.plugin.localeCompare(b.plugin),
262
+ entries: (a, b) => b.entries - a.entries || a.plugin.localeCompare(b.plugin),
263
+ name: (a, b) => a.plugin.localeCompare(b.plugin),
264
+ }[sort] ?? ((a, b) => b.amount - a.amount)
265
+ all.sort(cmp)
266
+ const total = this.totals(sessionId)
267
+ const shown = all.slice(0, Math.max(1, limit))
268
+ return Object.freeze({
269
+ sessionId,
270
+ sort,
271
+ total: total.cost.amount,
272
+ unknownEntries: total.cost.unknownEntries,
273
+ knownEntries: total.cost.knownEntries,
274
+ sourceCount: all.length,
275
+ truncated: shown.length < all.length,
276
+ sources: shown.map((s) => Object.freeze({
277
+ ...s,
278
+ share: total.cost.amount ? s.amount / total.cost.amount : null,
279
+ })),
280
+ generatedAt: Date.now(),
281
+ })
282
+ }
283
+
284
+ /**
285
+ * 跨会话概览:按 LRU 顺序(最近使用在前)返回各会话的汇总。
286
+ *
287
+ * 只遍历会话表,不遍历条目,成本 O(maxSessions);maxSessions 有硬上限 64。
288
+ */
289
+ overview({ limit = 64 } = {}) {
290
+ const ids = [...this.#sessions.keys()].reverse()
291
+ const shown = ids.slice(0, Math.max(1, limit))
292
+ const sessions = shown.map((id) => {
293
+ const b = this.#sessions.get(id)
294
+ return Object.freeze({
295
+ sessionId: id,
296
+ cost: Object.freeze({
297
+ amount: b.knownCostEntries > 0 ? b.costAmount : null,
298
+ currency: b.currency,
299
+ knownEntries: b.knownCostEntries,
300
+ unknownEntries: b.unknownCostEntries,
301
+ }),
302
+ tokens: Object.freeze({ ...b.tokens }),
303
+ entries: b.entries.size,
304
+ lastAt: b.lastAt || null,
305
+ })
306
+ })
307
+ return Object.freeze({
308
+ generatedAt: Date.now(),
309
+ sessionCount: this.#sessions.size,
310
+ truncated: shown.length < this.#sessions.size,
311
+ sessions,
312
+ })
313
+ }
314
+
315
+ traceTail(sessionId, n) {
316
+ return this.#sessions.get(sessionId)?.trace?.last(n) ?? []
317
+ }
318
+
319
+ entriesOf(sessionId) {
320
+ return this.#sessions.get(sessionId)?.entries.toArray() ?? []
321
+ }
322
+
323
+ drop(sessionId) {
324
+ this.#sessions.delete(sessionId)
325
+ }
326
+
327
+ get sessionCount() {
328
+ return this.#sessions.size
329
+ }
330
+ }
@@ -0,0 +1,25 @@
1
+ /**
2
+ * 工具结果的"体积":只数字符,不估 token。
3
+ *
4
+ * 为什么不估 token:不同 provider 的 tokenizer 不同,用 1 token ≈ 4 字符这种
5
+ * 经验系数去报"约 xx token",就是把不确定的东西伪装成确定。面板要显示的是
6
+ * "这次工具结果有多大",字符数本身就是事实。
7
+ *
8
+ * 只数 text:图片、文件引用等非文本块不占"文本上下文",数进去反而误导。
9
+ */
10
+ export function toolResultChars(message) {
11
+ const blocks = message?.content
12
+ if (!Array.isArray(blocks)) return 0
13
+ let chars = 0
14
+ for (const block of blocks) {
15
+ if (block !== null && typeof block === 'object' && typeof block.text === 'string') chars += block.text.length
16
+ }
17
+ return chars
18
+ }
19
+
20
+ /** 给面板用的紧凑写法:18,442 → 18.4k(超过 1 万才缩写,小数字不做无意义转换) */
21
+ export function formatChars(chars) {
22
+ if (typeof chars !== 'number' || !Number.isFinite(chars) || chars < 0) return null
23
+ if (chars < 10_000) return `${chars.toLocaleString('en-US')} 字符`
24
+ return `${(chars / 1000).toFixed(1)}k 字符`
25
+ }
@@ -0,0 +1,139 @@
1
+ /**
2
+ * 行为流水落盘(JSONL)。
3
+ *
4
+ * 为什么必须缓冲:`recordTrace` 在 `session/event` 热路径上,同步 append 会直接
5
+ * 拖慢 post-commit 广播(性能门禁测的就是这条路径)。所以这里只入队,
6
+ * 由定时器合并成一次 `appendFileSync`。
7
+ *
8
+ * 边界:
9
+ * - 每会话一个文件 `<root>/.dsh/ledger/<safe>.trace.jsonl`;
10
+ * - 队列有上限,满了就丢最旧的并计数(宁可丢流水,不拖慢宿主);
11
+ * - 单文件超过 maxBytes 后停止追加,只写一次"截断"提示行;
12
+ * - 所有异常吞掉并计数,绝不向调用方抛。
13
+ */
14
+ import { appendFileSync, mkdirSync, statSync } from 'node:fs'
15
+ import { join, isAbsolute, resolve } from 'node:path'
16
+ import { PANEL_DIR, safeFileName } from './panel-path.js'
17
+
18
+ /** 流水文件的后缀,与快照文件区分。 */
19
+ export const TRACE_SUFFIX = '.trace.jsonl'
20
+
21
+ /**
22
+ * @param {object} options
23
+ * @param {string} [options.dir] - 相对会话工作区根
24
+ * @param {string} [options.rootOf]
25
+ * @param {number} [options.maxBytes] - 单文件上限
26
+ * @param {number} [options.intervalMs] - 合并写盘间隔
27
+ * @param {number} [options.maxQueued] - 每会话队列上限
28
+ * @param {() => number} [options.now]
29
+ */
30
+ export function createTraceSink(options) {
31
+ const relativeDir = options.dir ?? PANEL_DIR
32
+ const fixedDir = isAbsolute(relativeDir) ? relativeDir : null
33
+ const rootOf = typeof options.rootOf === 'function' ? options.rootOf : () => process.cwd()
34
+ const dirOf = (sessionId) => (fixedDir !== null ? fixedDir : resolve(rootOf(sessionId), relativeDir))
35
+ const maxBytes = Math.max(64 * 1024, Number(options.maxBytes ?? 4 * 1024 * 1024))
36
+ const intervalMs = Math.max(50, Number(options.intervalMs ?? 500))
37
+ const maxQueued = Math.max(2, Number(options.maxQueued ?? 1000))
38
+ const now = options.now ?? Date.now
39
+
40
+ /** sessionId → string[](已序列化好的行) */
41
+ const queues = new Map()
42
+ const sealed = new Set() // 超过 maxBytes 的会话,后续直接丢
43
+ const stats = { lines: 0, dropped: 0, errors: 0, sealed: 0 }
44
+
45
+ function filePathOf(sessionId) {
46
+ return join(dirOf(sessionId), `${safeFileName(sessionId)}${TRACE_SUFFIX}`)
47
+ }
48
+
49
+ /** 热路径:只做一次 Map 取 + push,不做任何 IO。 */
50
+ function append(sessionId, record) {
51
+ if (typeof sessionId !== 'string' || sessionId.length === 0) return false
52
+ if (sealed.has(sessionId)) {
53
+ stats.dropped += 1
54
+ return false
55
+ }
56
+ let line
57
+ try {
58
+ line = JSON.stringify(record)
59
+ } catch {
60
+ stats.errors += 1
61
+ return false
62
+ }
63
+ let queue = queues.get(sessionId)
64
+ if (queue === undefined) {
65
+ queue = []
66
+ queues.set(sessionId, queue)
67
+ }
68
+ if (queue.length >= maxQueued) {
69
+ queue.shift() // 丢最旧:保留最近的行为,避免无限占内存
70
+ stats.dropped += 1
71
+ }
72
+ queue.push(line)
73
+ return true
74
+ }
75
+
76
+ /** 把队列写成文件;由定时器或 dispose 调用。 */
77
+ function flush() {
78
+ for (const [sessionId, queue] of queues) {
79
+ if (queue.length === 0) continue
80
+ const path = filePathOf(sessionId)
81
+ try {
82
+ mkdirSync(dirOf(sessionId), { recursive: true })
83
+ let size = 0
84
+ try {
85
+ size = statSync(path).size
86
+ } catch {
87
+ size = 0 // 文件还不存在
88
+ }
89
+ let body = ''
90
+ let written = 0
91
+ for (const line of queue) {
92
+ if (size + body.length + line.length + 1 > maxBytes) break
93
+ body += `${line}\n`
94
+ written += 1
95
+ }
96
+ if (body.length > 0) appendFileSync(path, body, 'utf8')
97
+ if (written < queue.length) {
98
+ // 到上限了:写一条自解释的收尾行,然后封口
99
+ if (!sealed.has(sessionId)) {
100
+ appendFileSync(path, `${JSON.stringify({ truncated: true, at: now(), dropped: queue.length - written })}\n`, 'utf8')
101
+ sealed.add(sessionId)
102
+ stats.sealed += 1
103
+ }
104
+ stats.dropped += queue.length - written
105
+ }
106
+ queue.length = 0
107
+ stats.lines += written
108
+ } catch {
109
+ stats.errors += 1
110
+ queue.length = 0
111
+ }
112
+ }
113
+ }
114
+
115
+ let timer = null
116
+ if (intervalMs > 0) {
117
+ timer = setInterval(flush, intervalMs)
118
+ // 别为了写流水把进程拖住
119
+ if (typeof timer.unref === 'function') timer.unref()
120
+ }
121
+
122
+ function dispose() {
123
+ if (timer !== null) {
124
+ clearInterval(timer)
125
+ timer = null
126
+ }
127
+ flush()
128
+ queues.clear()
129
+ sealed.clear()
130
+ }
131
+
132
+ /** 会话结束:丢掉它的队列与封口标记,避免按会话索引无界增长 */
133
+ function remove(sessionId) {
134
+ queues.delete(sessionId)
135
+ sealed.delete(sessionId)
136
+ }
137
+
138
+ return { append, flush, dispose, stats, filePathOf, dirOf, remove }
139
+ }
package/lib/trace.js ADDED
@@ -0,0 +1,82 @@
1
+ /**
2
+ * 行为流水。
3
+ *
4
+ * 三个硬约束:
5
+ * 1. 字段从第一版就按 OTel GenAI 语义(gen_ai.*)组织,避免阶段二重构数据模型;
6
+ * 2. 脱敏是默认行为,不是可选开关;
7
+ * 3. 记录失败绝不影响主流程(session/event 是 post-commit 广播,抛错会污染日志)。
8
+ *
9
+ * 另外三个字段是**不可逆的投资**(见 wire.js):
10
+ * - `eventId`:幂等键,双端重复上报的唯一防线;
11
+ * - `measures`:中性计量(token 只是其中一种单位,订阅制工具没有 token);
12
+ * - `actor` / `project` / `deviceId`:身份线索,没采到的历史永远补不回来。
13
+ */
14
+
15
+ import { eventIdOf, measuresOf, WIRE_VERSION } from './wire.js'
16
+
17
+ const SECRET_PATTERNS = [
18
+ /\bsk-[A-Za-z0-9_-]{8,}\b/g,
19
+ /\bBearer\s+[A-Za-z0-9._-]{8,}\b/gi,
20
+ /\b(api[_-]?key|token|secret|password)\s*[:=]\s*[^\s,;]{6,}/gi,
21
+ ]
22
+
23
+ /** 绝对路径会把用户目录结构泄进审计日志 */
24
+ const ABS_PATH = /(?:^|[\s"'(])((?:[A-Za-z]:)?(?:[\\/](?:[^\\/\s"']+)){2,})/g
25
+
26
+ export function redactText(value, maxLength = 200) {
27
+ if (typeof value !== 'string') return ''
28
+ let text = value
29
+ for (const pattern of SECRET_PATTERNS) text = text.replace(pattern, '[redacted]')
30
+ text = text.replace(ABS_PATH, ' [path]')
31
+ text = text.replace(/\s+/g, ' ').trim()
32
+ return text.length > maxLength ? `${text.slice(0, maxLength)}…` : text
33
+ }
34
+
35
+ /**
36
+ * @param {{enabled:boolean, capacity:number, maxTextLength:number}} config
37
+ */
38
+ export function createTrace(config) {
39
+ const maxLength = config?.maxTextLength ?? 200
40
+
41
+ /**
42
+ * @param {object} input
43
+ * @returns {object|null} 关闭时返回 null,由调用方跳过写入
44
+ */
45
+ function project(input) {
46
+ if (!config?.enabled) return null
47
+ const {
48
+ sessionId, turn, step, eventType, pluginSource, cost, summary, at, identity,
49
+ } = input
50
+
51
+ // 身份线索随行落盘:它是唯一"事后补不回来"的维度,宁可先记下
52
+ const actor = identity?.actor ?? null
53
+ const project = identity?.project ?? null
54
+ const deviceId = identity?.deviceId ?? null
55
+
56
+ return Object.freeze({
57
+ timestamp: new Date(at ?? Date.now()).toISOString(),
58
+ sessionId,
59
+ turn,
60
+ step,
61
+ 'gen_ai.operation.name': eventType,
62
+ 'gen_ai.agent.name': pluginSource ?? 'unattributed',
63
+ 'gen_ai.usage.input_tokens': input.usage?.inputTokens ?? null,
64
+ 'gen_ai.usage.output_tokens': input.usage?.outputTokens ?? null,
65
+ 'gen_ai.usage.cache_read_tokens': input.usage?.cacheReadTokens ?? null,
66
+ 'gen_ai.usage.cache_write_tokens': input.usage?.cacheWriteTokens ?? null,
67
+ // 不可逆字段:三件一次写齐,后面上报和团队聚合都靠它们
68
+ wireVersion: WIRE_VERSION,
69
+ eventId: eventIdOf({ sessionId, turn, step, operation: eventType }),
70
+ measures: measuresOf(input.usage),
71
+ deviceId,
72
+ actor,
73
+ project,
74
+ cost: cost?.kind === 'known' ? { amount: cost.amount, currency: cost.currency } : null,
75
+ costUnknownReason: cost?.kind === 'unknown' ? cost.reason : null,
76
+ summary: redactText(summary ?? '', maxLength),
77
+ })
78
+ }
79
+
80
+ // enabled 暴露给采集层:关闭时连 project 的参数对象都不构造(热路径零分配)
81
+ return { project, enabled: Boolean(config?.enabled), redactText: (v) => redactText(v, maxLength) }
82
+ }
package/lib/usage.js ADDED
@@ -0,0 +1,67 @@
1
+ /**
2
+ * TokenUsage 归一化。
3
+ *
4
+ * 源码事实(@deepseek-ai/dsh-llm TokenUsage):
5
+ * - 计数是 **disjoint**(互不重叠):`inputTokens` 只含未缓存输入,
6
+ * 缓存输入单列为 `cacheReadTokens` / `cacheWriteTokens`。
7
+ * - `totalTokens` 是可选的;缺了就缺了,**不做加法冒充**。
8
+ *
9
+ * 因此 billableInput = input + cacheRead + cacheWrite 是派生量,
10
+ * 必须显式标注 derived,避免下游误当成上游上报值。
11
+ */
12
+
13
+ const isNum = (v) => typeof v === 'number' && Number.isFinite(v)
14
+
15
+ /**
16
+ * @param {unknown} raw assistant/message 携带的 usage
17
+ * @returns {{
18
+ * inputTokens: number|null, outputTokens: number|null,
19
+ * cacheReadTokens: number, cacheWriteTokens: number,
20
+ * reasoningTokens: number, totalTokens: number|null,
21
+ * billableInput: number|null, complete: boolean
22
+ * }|null}
23
+ */
24
+ export function normalizeUsage(raw) {
25
+ if (!raw || typeof raw !== 'object') return null
26
+
27
+ const input = isNum(raw.inputTokens) ? raw.inputTokens : null
28
+ const output = isNum(raw.outputTokens) ? raw.outputTokens : null
29
+ const cacheRead = isNum(raw.cacheReadTokens) ? raw.cacheReadTokens : 0
30
+ const cacheWrite = isNum(raw.cacheWriteTokens) ? raw.cacheWriteTokens : 0
31
+ const reasoning = isNum(raw.reasoningTokens) ? raw.reasoningTokens : 0
32
+ const total = isNum(raw.totalTokens) ? raw.totalTokens : null
33
+
34
+ // 完全没有计数信号时视为"没有 usage",而不是"用量为 0"
35
+ if (input === null && output === null && cacheRead === 0 && cacheWrite === 0 && total === null) {
36
+ return null
37
+ }
38
+
39
+ return {
40
+ inputTokens: input,
41
+ outputTokens: output,
42
+ cacheReadTokens: cacheRead,
43
+ cacheWriteTokens: cacheWrite,
44
+ reasoningTokens: reasoning,
45
+ totalTokens: total,
46
+ // 派生量:仅在 input 可得时才有意义
47
+ billableInput: input === null ? null : input + cacheRead + cacheWrite,
48
+ // 计费必须同时拿到输入与输出;缺任何一个都不可计费
49
+ complete: input !== null && output !== null,
50
+ }
51
+ }
52
+
53
+ /** 汇总多个 usage(用于会话级 token 总数)。缺失字段不参与求和,避免被 0 稀释。 */
54
+ export function sumUsage(list) {
55
+ const acc = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0, reported: 0, missing: 0 }
56
+ for (const u of list) {
57
+ if (!u) continue
58
+ acc.inputTokens += u.inputTokens ?? 0
59
+ acc.outputTokens += u.outputTokens ?? 0
60
+ acc.cacheReadTokens += u.cacheReadTokens ?? 0
61
+ acc.cacheWriteTokens += u.cacheWriteTokens ?? 0
62
+ acc.reasoningTokens += u.reasoningTokens ?? 0
63
+ if (u.complete) acc.reported += 1
64
+ else acc.missing += 1
65
+ }
66
+ return acc
67
+ }