@lingda-ai/dsh-plugin-ledger 0.1.2 → 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/LICENSE +17 -0
- package/cordis.patch.yml +3 -2
- package/docs/business-plan.md +237 -0
- package/docs/spikes.md +373 -0
- package/docs/technical.md +364 -0
- package/docs/wire-format.md +95 -0
- package/lib/attribution.js +73 -0
- package/lib/audit-tool.js +184 -0
- package/lib/budget-message.js +28 -0
- package/lib/client.js +217 -0
- package/lib/config.js +74 -0
- package/lib/guard.js +102 -0
- package/lib/identity.js +119 -0
- package/lib/index.js +217 -0
- package/lib/ledger.js +260 -0
- package/lib/panel-path.js +39 -0
- package/lib/panel-view.js +717 -0
- package/lib/pricing-file.js +169 -0
- package/lib/pricing-table.js +55 -0
- package/lib/pricing.js +84 -0
- package/lib/ring.js +54 -0
- package/lib/snapshot-file.js +293 -0
- package/lib/store.js +330 -0
- package/lib/tool-size.js +25 -0
- package/lib/trace-file.js +139 -0
- package/lib/trace.js +82 -0
- package/lib/usage.js +67 -0
- package/lib/wire.js +87 -0
- package/package.json +25 -5
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
|
+
}
|
package/lib/tool-size.js
ADDED
|
@@ -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
|
+
}
|