@sligqoer/dsh-usage-stats 0.1.2 → 0.2.1

package/lib/lm-fingerprint-engine.js

@@ -0,0 +1,166 @@
+/** Upstream releases are immutable. A running quote always keeps its version. */
+import { Worker } from 'node:worker_threads'
+import { readFile, writeFile, mkdir, rename, rm } from 'node:fs/promises'
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve, join, relative, isAbsolute, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { randomUUID } from 'node:crypto'
+import { hash, publishedRelease, buildRelease, closeDownloadTransport } from './lm-fingerprint-source.js'
+
+const bundled = [new URL('../third_party/lm-fingerprint/', import.meta.url), new URL('./third_party/lm-fingerprint/', import.meta.url)]
+  .map(url => fileURLToPath(url)).find(path => existsSync(join(path, 'UPSTREAM.json')))
+export async function verifyEngine(directory) {
+  const manifest = JSON.parse(await readFile(join(directory, 'UPSTREAM.json'), 'utf8'))
+  if (manifest.schema !== 1 || manifest.name !== 'lmfpd' || !/^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/.test(manifest.version || '') ||
+      !/^[a-f0-9]{40}$/.test(manifest.revision || '') || !manifest.files || Object.keys(manifest.files).length > 40) throw new Error('指纹引擎清单无效。')
+  const required = ['LICENSE', 'data/unified_bank.json', 'data/shared_detector.bin',
+    ...['challenge-browser', 'fingerprint-core', 'shared-detector', 'detector-codec'].map(name => 'core/' + name + '.mjs')]
+  if (required.some(name => !manifest.files[name])) throw new Error('指纹引擎文件缺失。')
+  for (const [name, digest] of Object.entries(manifest.files)) {
+    if (!/^(?:LICENSE|data\/(?:unified_bank\.json|shared_detector\.bin)|core\/[a-z0-9-]+\.mjs)$/.test(name) ||
+        !/^[a-f0-9]{64}$/.test(digest) || hash(await readFile(join(directory, name))) !== digest) throw new Error('指纹引擎文件校验失败。')
+  }
+  return manifest
+}
+export function openEngine(directory, manifest, options = {}) {
+  const worker = new Worker(new URL('./lm-fingerprint-worker.js', import.meta.url), {
+    workerData: { directory }, resourceLimits: { maxOldGenerationSizeMb: 256 }, execArgv: []
+  })
+  const pending = new Map()
+  let sequence = 0, closed = false, metadata
+  let resolveReady, rejectReady
+  const ready = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject })
+  const timeoutMs = options.timeoutMs || 30_000
+  const startup = setTimeout(() => fail(new Error('指纹引擎启动超时。')), timeoutMs)
+  const dispose = () => { if (!closed) { closed = true; clearTimeout(startup); rejectReady(new Error('指纹引擎已停止。')); void worker.terminate(); for (const p of pending.values()) p.reject(new Error('指纹引擎已停止。')); pending.clear() } }
+  function fail(error) { clearTimeout(startup); rejectReady(error); dispose() }
+  worker.on('message', message => {
+    if (message.ready) { clearTimeout(startup); metadata = message; resolveReady(message); return }
+    const item = pending.get(message.id)
+    if (!item) return
+    pending.delete(message.id)
+    message.error ? item.reject(new Error(message.error)) : item.resolve(message.result)
+  })
+  worker.on('error', error => fail(new Error('指纹引擎无法启动，请检查宿主运行环境。', { cause: error })))
+  worker.on('exit', () => { if (!closed) fail(new Error('指纹引擎意外退出。')) })
+  return {
+    manifest, directory, ready, dispose,
+    get models() { return metadata?.models || [] },
+    async call(operation, value, signal) {
+      await ready
+      if (closed || signal?.aborted) throw new Error('指纹检测已停止。')
+      return new Promise((resolve, reject) => {
+        const id = ++sequence
+        const finish = handler => result => { clearTimeout(timer); signal?.removeEventListener('abort', abort); pending.delete(id); handler(result) }
+        const abort = () => pending.get(id)?.reject(new Error('指纹检测已取消。'))
+        const timer = setTimeout(() => { pending.get(id)?.reject(new Error('指纹引擎计算超时。')); dispose() }, timeoutMs)
+        pending.set(id, { resolve: finish(resolve), reject: finish(reject) })
+        signal?.addEventListener('abort', abort, { once: true })
+        worker.postMessage({ id, operation, value })
+      })
+    }
+  }
+}
+export function createFingerprintEngine(options = {}) {
+  const cache = options.path && resolve(options.path), fallback = options.bundledPath || bundled
+  let active = fallback, activeManifest, warning = '', checkedAt = 0, checking, initialized, disposed = false, autoTimer
+  const lifecycle = new AbortController()
+  const sessions = new Set()
+  try { activeManifest = JSON.parse(readFileSync(join(fallback, 'UPSTREAM.json'), 'utf8')) } catch { warning = '内置指纹引擎不可用，请重新安装插件。' }
+  function status() { return { name: 'lmfpd', version: activeManifest?.version || '', revision: activeManifest?.revision || '',
+    builtAt: activeManifest?.builtAt || '', modelCount: activeManifest?.modelCount || 0, source: active === fallback ? 'bundled' : 'updated',
+    checkedAt, updating: !!checking, warning, autoUpdate: !!cache } }
+  function cacheDirectory(version) {
+    if (!cache || !/^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/.test(version || '') || version.length > 64) throw new Error('指纹引擎缓存路径无效。')
+    const target = resolve(cache, 'versions', version), rel = relative(cache, target)
+    if (rel.startsWith('..') || isAbsolute(rel)) throw new Error('指纹引擎缓存路径无效。')
+    return target
+  }
+  async function init() {
+    if (!initialized) initialized = (async () => {
+      if (cache) {
+        try {
+          const pointer = JSON.parse(await readFile(join(cache, 'current.json'), 'utf8'))
+          const directory = cacheDirectory(pointer.version), manifest = await verifyEngine(directory)
+          if (pointer.manifestHash !== hash(await readFile(join(directory, 'UPSTREAM.json')))) throw new Error('缓存清单不一致。')
+          active = directory; activeManifest = manifest; checkedAt = Number(pointer.checkedAt) || 0
+        } catch (error) { if (error.code !== 'ENOENT') warning = '缓存引擎校验失败，已保留内置版本。' }
+        try {
+          const check = JSON.parse(await readFile(join(cache, 'check.json'), 'utf8'))
+          if (Number.isFinite(check.checkedAt)) checkedAt = Math.min(Date.now(), Math.max(0, check.checkedAt))
+          if (!warning && typeof check.warning === 'string' && check.warning === '上游更新暂不可用，继续使用已验证的指纹引擎。') warning = check.warning
+        } catch {}
+      }
+      activeManifest = await verifyEngine(active)
+    })()
+    await initialized
+    if (disposed) throw new Error('指纹引擎已停止。')
+  }
+  async function update(force = false) {
+    await init()
+    if (!cache || disposed) return status()
+    if (checking) return checking
+    if (!force && Date.now() - checkedAt < (options.checkIntervalMs ?? 86_400_000)) return status()
+    checking = (async () => {
+      let staging, trial
+      try {
+        checkedAt = Date.now()
+        const release = await publishedRelease({ fetch: options.fetch, signal: AbortSignal.any([lifecycle.signal, AbortSignal.timeout(15_000)]) })
+        if (release.version === activeManifest.version || Number(release.version.split('.').pop()) < Number(activeManifest.version.split('.').pop())) { warning = ''; return }
+        staging = join(cache, '.stage-' + randomUUID())
+        const manifest = await buildRelease(release, staging, { fetch: options.fetch, signal: AbortSignal.any([lifecycle.signal, AbortSignal.timeout(60_000)]) })
+        trial = openEngine(staging, manifest, options); await trial.ready
+        trial.dispose(); trial = null
+        if (disposed) throw new Error('指纹引擎已停止。')
+        const destination = cacheDirectory(manifest.version)
+        if (existsSync(destination)) {
+          const existing = await verifyEngine(destination)
+          if (existing.revision !== manifest.revision || existing.integrity !== manifest.integrity ||
+            JSON.stringify(Object.entries(existing.files).sort()) !== JSON.stringify(Object.entries(manifest.files).sort())) throw new Error('同版本缓存内容不同。')
+        } else { await mkdir(dirname(destination), { recursive: true }); await rename(staging, destination) }
+        const pointer = { version: manifest.version, checkedAt, manifestHash: hash(await readFile(join(destination, 'UPSTREAM.json'))) }
+        await mkdir(cache, { recursive: true })
+        const temporary = join(cache, 'current-' + randomUUID() + '.tmp')
+        await writePointer(temporary, pointer)
+        await rename(temporary, join(cache, 'current.json'))
+        active = destination; activeManifest = manifest; warning = ''
+      } catch { warning = '上游更新暂不可用，继续使用已验证的指纹引擎。' }
+      finally {
+        trial?.dispose()
+        const rel = staging && relative(cache, resolve(staging))
+        if (rel && !rel.startsWith('..') && !isAbsolute(rel)) await rm(staging, { recursive: true, force: true }).catch(() => {})
+        if (!disposed) {
+          const temporary = join(cache, 'check-' + randomUUID() + '.tmp')
+          try { await mkdir(cache, { recursive: true }); await writePointer(temporary, { checkedAt, warning }); await rename(temporary, join(cache, 'check.json')) }
+          catch { await rm(temporary, { force: true }).catch(() => {}) }
+        }
+      }
+    })().finally(() => { checking = null })
+    await checking
+    return status()
+  }
+  async function writePointer(path, value) { await writeFile(path, JSON.stringify(value) + '\n') }
+  return {
+    status, update,
+    async acquire() {
+      await init()
+      const manifest = await verifyEngine(active), engine = openEngine(active, manifest, options)
+      sessions.add(engine)
+      const close = engine.dispose
+      engine.dispose = () => { sessions.delete(engine); close() }
+      try { await engine.ready } catch (error) { engine.dispose(); throw error }
+      return engine
+    },
+    async catalog() {
+      const engine = await this.acquire()
+      try {
+        if (cache && !autoTimer) { autoTimer = setInterval(() => { void update().catch(() => {}) }, 3_600_000); autoTimer.unref?.() }
+        void update().catch(() => {})
+        // Let the background check enter its downloading state for the UI.
+        await new Promise(resolve => setImmediate(resolve))
+        return { ...status(), version: engine.manifest.version, builtAt: engine.manifest.builtAt, modelCount: engine.models.length, models: engine.models }
+      } finally { engine.dispose() }
+    },
+    dispose() { disposed = true; lifecycle.abort(); clearInterval(autoTimer); for (const session of sessions) session.dispose(); void closeDownloadTransport() }
+  }
+}

package/lib/lm-fingerprint-source.js

@@ -0,0 +1,134 @@
+/** Fetch one published upstream revision. Never runs npm scripts or the CLI. */
+import { createHash } from 'node:crypto'
+import { gunzipSync } from 'node:zlib'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join, posix } from 'node:path'
+import { EnvHttpProxyAgent, fetch as undiciFetch } from 'undici'
+
+export const REGISTRY = 'https://registry.npmjs.org/lmfpd/latest'
+export const SOURCE_ROOT = 'https://raw.githubusercontent.com/Ikaleio/lm-detector/'
+const roots = ['challenge-browser.js', 'fingerprint-core.js', 'shared-detector.ts', 'detector-codec.ts']
+let downloadAgent
+function defaultFetch(url, init) {
+  if (process.env.HTTPS_PROXY || process.env.HTTP_PROXY || process.env.https_proxy || process.env.http_proxy) {
+    downloadAgent ||= new EnvHttpProxyAgent()
+    return undiciFetch(url, { ...init, dispatcher: downloadAgent })
+  }
+  return globalThis.fetch(url, init)
+}
+export async function closeDownloadTransport() { const agent = downloadAgent; downloadAgent = undefined; await agent?.destroy() }
+export const hash = value => createHash('sha256').update(value).digest('hex')
+export function validateRelease(value) {
+  const version = value?.version, revision = value?.gitHead
+  if (value?.name !== 'lmfpd' || !/^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/.test(version || '') || version.length > 64 ||
+      !/^[a-f0-9]{40}$/.test(revision || '') || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(value?.dist?.integrity || '')) {
+    throw new Error('上游版本信息无效。')
+  }
+  const expected = 'https://registry.npmjs.org/lmfpd/-/lmfpd-' + version + '.tgz'
+  if (value.dist.tarball !== expected) throw new Error('上游发布包地址不受支持。')
+  return { version, revision, tarball: expected, integrity: value.dist.integrity }
+}
+export async function readRemote(url, { fetch: request = defaultFetch, signal, limit = 1_048_576 } = {}) {
+  const response = await request(url, { signal: signal || AbortSignal.timeout(30_000), redirect: 'error' })
+  if (!response.ok) throw new Error('上游文件下载失败（HTTP ' + response.status + '）。')
+  if (Number(response.headers.get('content-length')) > limit) throw new Error('上游文件超过大小限制。')
+  const reader = response.body.getReader(), chunks = []
+  let size = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      size += value.length
+      if (size > limit) throw new Error('上游文件超过大小限制。')
+      chunks.push(Buffer.from(value))
+    }
+  } finally { await reader.cancel().catch(() => {}) }
+  return Buffer.concat(chunks)
+}
+export async function publishedRelease(options = {}) {
+  return validateRelease(JSON.parse((await readRemote(REGISTRY, options)).toString('utf8')))
+}
+/** Select literal members from a bounded archive; never extract archive paths. */
+export function releaseFiles(compressed, integrity) {
+  if ('sha512-' + createHash('sha512').update(compressed).digest('base64') !== integrity) throw new Error('上游发布包完整性校验失败。')
+  const tar = gunzipSync(compressed, { maxOutputLength: 96 * 1024 * 1024 })
+  const wanted = new Set(['package/package.json', 'package/LICENSE', 'package/data/unified_bank.json', 'package/data/shared_detector.bin'])
+  const files = new Map()
+  for (let offset = 0; offset + 512 <= tar.length;) {
+    const header = tar.subarray(offset, offset + 512)
+    if (header.every(v => v === 0)) break
+    const field = (a, b) => header.subarray(a, b).toString('utf8').split('\0')[0]
+    const size = Number.parseInt(field(124, 136).trim(), 8)
+    const checksum = Number.parseInt(field(148, 156).trim(), 8)
+    const actual = header.reduce((sum, v, i) => sum + (i >= 148 && i < 156 ? 32 : v), 0)
+    if (!Number.isSafeInteger(size) || size < 0 || offset + 512 + size > tar.length || actual !== checksum) throw new Error('上游发布包归档无效。')
+    const prefix = field(345, 500), name = (prefix ? prefix + '/' : '') + field(0, 100)
+    if (wanted.has(name)) {
+      if (![0, 48].includes(header[156]) || files.has(name.slice(8))) throw new Error('上游发布包含无效文件。')
+      files.set(name.slice(8), Buffer.from(tar.subarray(offset + 512, offset + 512 + size)))
+    }
+    offset += 512 + Math.ceil(size / 512) * 512
+  }
+  if (files.size !== wanted.size) throw new Error('上游发布包缺少检测文件，请更新插件适配。')
+  return files
+}
+export async function buildRelease(release, directory, options = {}) {
+  // Types are removed without rewriting the upstream numerical algorithm.
+  const ts = (await import('typescript')).default
+  const files = releaseFiles(await readRemote(release.tarball, { ...options, limit: 24 * 1024 * 1024 }), release.integrity)
+  const pkg = JSON.parse(files.get('package.json').toString('utf8'))
+  if (pkg.name !== 'lmfpd' || pkg.version !== release.version || pkg.gitHead !== release.revision) throw new Error('上游代码与发布版本不一致。')
+  const bank = JSON.parse(files.get('data/unified_bank.json').toString('utf8'))
+  if (!Array.isArray(bank.models) || !bank.models.length || bank.models.length > 1000) throw new Error('上游参考库无效。')
+  const modules = new Map(), sourceHashes = {}
+  async function moduleFor(name) {
+    if (!/^[a-z0-9-]+\.(?:ts|js)$/.test(name)) throw new Error('上游模块路径不受支持。')
+    if (modules.has(name)) return
+    if (modules.size >= 32) throw new Error('上游模块数量超过限制。')
+    modules.set(name, null)
+    const raw = await readRemote(SOURCE_ROOT + release.revision + '/shared/' + name, options)
+    sourceHashes[name] = hash(raw)
+    const compiled = ts.transpileModule(raw.toString('utf8'), {
+      fileName: name, compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext }
+    }).outputText
+    const parsed = ts.createSourceFile(name, compiled, ts.ScriptTarget.ES2022, true, ts.ScriptKind.JS)
+    const replacements = [], dependencies = []
+    for (const statement of parsed.statements) {
+      if (!ts.isImportDeclaration(statement) && !ts.isExportDeclaration(statement)) continue
+      const specifier = statement.moduleSpecifier
+      if (!specifier) continue
+      const path = specifier.text
+      if (typeof path !== 'string' || !/^\.\/[a-z0-9-]+(?:\.(?:js|ts))?$/.test(path)) throw new Error('上游模块依赖不受支持，请更新插件适配。')
+      const child = path.slice(2).includes('.') ? path.slice(2) : path.slice(2) + '.ts'
+      dependencies.push(child)
+      replacements.push({ start: specifier.getStart(parsed), end: specifier.getEnd(), value: JSON.stringify('./' + child.replace(/\.(ts|js)$/, '.mjs')) })
+    }
+    let dynamic = false
+    function visit(node) { if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) dynamic = true; ts.forEachChild(node, visit) }
+    visit(parsed)
+    if (dynamic) throw new Error('上游动态模块依赖不受支持，请更新插件适配。')
+    let code = compiled
+    for (const change of replacements.sort((a, b) => b.start - a.start)) code = code.slice(0, change.start) + change.value + code.slice(change.end)
+    modules.set(name, code)
+    await Promise.all(dependencies.map(moduleFor))
+  }
+  await Promise.all(roots.map(moduleFor))
+  const outputs = new Map([
+    ['LICENSE', files.get('LICENSE')],
+    ['data/unified_bank.json', files.get('data/unified_bank.json')],
+    ['data/shared_detector.bin', files.get('data/shared_detector.bin')],
+    ...[...modules].map(([name, code]) => ['core/' + name.replace(/\.(ts|js)$/, '.mjs'), Buffer.from(code)])
+  ])
+  const manifest = { schema: 1, name: 'lmfpd', version: release.version, revision: release.revision, integrity: release.integrity,
+    builtAt: bank.built_at, modelCount: bank.models.length, source: 'https://github.com/Ikaleio/lm-detector/tree/' + release.revision,
+    upstream: { url: 'https://github.com/Ikaleio/lm-detector', commit: release.revision },
+    compiler: 'TypeScript 5.9.3; type erasure and relative module extensions only', sourceHashes: Object.fromEntries(Object.entries(sourceHashes).sort()),
+    files: Object.fromEntries([...outputs].sort(([a], [b]) => a.localeCompare(b)).map(([name, bytes]) => [name, hash(bytes)])) }
+  for (const [name, bytes] of outputs) {
+    const parts = posix.dirname(name)
+    await mkdir(join(directory, parts), { recursive: true })
+    await writeFile(join(directory, name), bytes)
+  }
+  await writeFile(join(directory, 'UPSTREAM.json'), JSON.stringify(manifest, null, 2) + '\n')
+  return manifest
+}

package/lib/lm-fingerprint-worker.js

@@ -0,0 +1,31 @@
+/** The worker loads upstream code and data together; no network or credentials. */
+import { parentPort, workerData } from 'node:worker_threads'
+import { readFile } from 'node:fs/promises'
+import { pathToFileURL } from 'node:url'
+import { join } from 'node:path'
+
+const root = workerData.directory
+const [challenge, fingerprint, scorer, codec] = await Promise.all(
+  ['challenge-browser', 'fingerprint-core', 'shared-detector', 'detector-codec'].map(name => import(pathToFileURL(join(root, 'core', name + '.mjs')).href)))
+const bank = JSON.parse(await readFile(join(root, 'data', 'unified_bank.json'), 'utf8'))
+const detector = codec.decodeDetector(await readFile(join(root, 'data', 'shared_detector.bin')))
+if (!scorer.supportsSharedDetector(bank, detector)) throw new Error('参考库与检测器不匹配。')
+const models = bank.models.map(m => ({ id: m.id, name: m.display_name, family: m.family }))
+// Exercise the numerical interface before activating an update. No model calls.
+const fixture = Array.from({ length: 300 }, (_, i) => (i * 17) % 355 + 1).join(',')
+const check = scorer.analyzeSharedOutputs(Array.from({ length: 3 }, () => ({ text: fixture, expected_count: 300 })), bank, detector)
+if (!check.results?.length || check.results.some(r => !Number.isFinite(r.score)) ||
+    check.probability !== null && (!Number.isFinite(check.probability) || check.probability < 0 || check.probability > 1)) throw new Error('上游检测接口不兼容。')
+const challenges = challenge.generateChallenges(3)
+if (challenges.length !== 3 || challenges.some(c => typeof c.prompt !== 'string' || !Number.isInteger(c.expected_count) || c.expected_count < 80 || c.expected_count > 500)) throw new Error('上游挑战接口不兼容。')
+parentPort.postMessage({ ready: true, models, builtAt: bank.built_at })
+parentPort.on('message', ({ id, operation, value }) => {
+  try {
+    let result
+    if (operation === 'challenges') result = challenge.generateChallenges(value)
+    else if (operation === 'parse') result = fingerprint.parseNumbers(value)
+    else if (operation === 'score') result = scorer.analyzeSharedOutputs(value, bank, detector, { allowPartial: true })
+    else throw new Error('Unsupported engine operation')
+    parentPort.postMessage({ id, result })
+  } catch { parentPort.postMessage({ id, error: '指纹评分失败，请检查引擎版本或有效样本。' }) }
+})

package/lib/model-detection-history.js

@@ -0,0 +1,86 @@
+/** Reported detection usage and recent fingerprints. No prompts, answers or credentials. */
+import { readFileSync } from 'node:fs'
+import { mkdir, writeFile, rename } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { modelSelection, safeUsage, summarizeModelDetection, normalizeFingerprintIdentity } from './model-detection.js'
+
+const clean = v => typeof v === 'string' ? v.replace(/[\u0000-\u001f\u007f]/g, '').slice(0, 256) : ''
+const number = v => Number.isFinite(v) && v >= 0 ? v : 0
+const timing = v => Number.isFinite(v) && v >= 0 ? v : null
+const states = ['running', 'complete', 'failed', 'cancelled', 'budget-exhausted', 'interrupted']
+const outcomes = ['scored', 'unparseable', 'unavailable', 'timeout', 'incomplete', 'cancelled']
+const fields = (value, keys) => Object.fromEntries(keys.filter(k => Number.isFinite(value?.[k]) && value[k] >= 0).map(k => [k, value[k]]))
+function result(raw, job) {
+  const selection = modelSelection(raw.selection) || (job.testSelection || job.selection)
+  return { time: number(raw.time) || job.finishedAt || job.startedAt, selection,
+    phase: 'fingerprint', outcome: outcomes.includes(raw.outcome) ? raw.outcome : 'unavailable', stop: clean(raw.stop),
+    usage: safeUsage(raw.usage), usageReported: raw.usageReported === true,
+    valid: number(raw.valid), expected: number(raw.expected), ttftMs: timing(raw.ttftMs), decodeMs: timing(raw.decodeMs) }
+}
+function jobSnapshot(raw) {
+  const selection = modelSelection(raw?.selection)
+  if (!selection || !clean(raw.id) || !states.includes(raw.status)) return null
+  const job = { id: clean(raw.id), sessionId: clean(raw.sessionId), selection, testSelection: modelSelection(raw.testSelection),
+    status: raw.status, phase: clean(raw.phase), startedAt: number(raw.startedAt), finishedAt: number(raw.finishedAt),
+    plan: fields(raw.plan, ['requests', 'samples', 'maxTokens', 'maxOutputTokens', 'estimatedInputTokens', 'budgetTokens', 'timeoutMs']),
+    usage: safeUsage(raw.usage), usageReported: raw.usageReported === true, usageIncomplete: raw.usageIncomplete === true, usageSaved: true,
+    message: clean(raw.message), channel: { tps: timing(raw.channel?.tps), ttftMs: timing(raw.channel?.ttftMs) } }
+  job.plan.numbers = (Array.isArray(raw.plan?.numbers) ? raw.plan.numbers : []).slice(0, 3).map(number)
+  if (raw.engine) job.engine = { name: 'lmfpd', version: clean(raw.engine.version), revision: clean(raw.engine.revision), builtAt: clean(raw.engine.builtAt), modelCount: number(raw.engine.modelCount) }
+  job.identity = normalizeFingerprintIdentity(raw.identity)
+  job.results = (Array.isArray(raw.results) ? raw.results : []).map(r => result(r, job))
+  job.progress = job.results.length
+  job.conclusion = summarizeModelDetection(job)
+  return job
+}
+export function createModelDetectionHistory(path) {
+  const usage = new Map(), jobs = new Map()
+  let queue = Promise.resolve(), warning = ''
+  try {
+    const document = JSON.parse(readFileSync(path, 'utf8'))
+    if (document.version !== 1 || !Array.isArray(document.usage) || !Array.isArray(document.jobs)) throw new Error('invalid')
+    for (const raw of document.usage) {
+      const job = { selection: modelSelection(raw.selection), startedAt: number(raw.startedAt), finishedAt: number(raw.finishedAt) }
+      if (!clean(raw.id) || !job.selection || !Array.isArray(raw.results)) throw new Error('invalid')
+      usage.set(clean(raw.id), { id: clean(raw.id), ...job, results: raw.results.map(r => result(r, job)) })
+    }
+    for (const raw of document.jobs.slice(-10)) {
+      const job = jobSnapshot(raw)
+      if (!job) continue
+      if (job.status === 'running') {
+        job.status = 'interrupted'; job.finishedAt = Date.now(); job.message = ''
+        job.identity = null
+        job.conclusion = summarizeModelDetection(job)
+      }
+      jobs.set(job.id, job)
+    }
+  } catch (error) { if (error.code !== 'ENOENT') warning = '检测记录无法读取，请检查本地记录后重新加载插件。' }
+  return {
+    warning: () => warning,
+    flush: () => queue.catch(() => {}),
+    latest(sessionId) { return [...jobs.values()].reverse().find(j => !sessionId || j.sessionId === sessionId) || null },
+    get(id) { return jobs.get(id) || null },
+    usage() { return [...usage.values()].flatMap(j => j.results) },
+    // Stable sample IDs let the statistics plugin replace repeated snapshots without double counting.
+    usageRecords() { return [...usage.values()].flatMap(j => j.results.map((row, index) => ({ ...row, id: `${j.id}:${index}` }))) },
+    async record(raw) {
+      if (warning) throw new Error(warning)
+      const job = jobSnapshot(raw)
+      if (!job) throw new Error('invalid fingerprint record')
+      const prior = usage.get(job.id)
+      // A late poll or repeated save must never shrink or duplicate spend.
+      if (prior && job.results.length < prior.results.length) return
+      usage.set(job.id, { id: job.id, selection: job.selection, startedAt: job.startedAt, finishedAt: job.finishedAt, results: job.results })
+      jobs.set(job.id, job)
+      while (jobs.size > 10) jobs.delete(jobs.keys().next().value)
+      const document = JSON.stringify({ version: 1, usage: [...usage.values()], jobs: [...jobs.values()] })
+      const next = queue.catch(() => {}).then(async () => {
+        await mkdir(dirname(path), { recursive: true })
+        await writeFile(path + '.tmp', document, { mode: 0o600 })
+        await rename(path + '.tmp', path)
+      })
+      queue = next
+      await next
+    },
+  }
+}