agentworkshop 0.7.34 → 0.7.37

package/scripts/test-daq-frame-race.mjs

@@ -17,19 +17,24 @@
  * 服务器未起时自动降级为仅 A 部分。
  */
 
-const BASE = process.argv[2] ?? process.env.AW_BASE ?? "http://127.0.0.1:3021"
+const BASE = process.argv[2] ?? process.env.AW_BASE ?? 'http://127.0.0.1:3021'
 let pass = 0
 let fail = 0
-const ok = (cond, label, detail = "") => {
-  if (cond) { pass++; console.log("  [PASS] " + label + (detail ? " -- " + detail : "")) }
-  else { fail++; console.log("  [FAIL] " + label + (detail ? " -- " + detail : "")) }
+const ok = (cond, label, detail = '') => {
+  if (cond) {
+    pass++
+    console.log('  [PASS] ' + label + (detail ? ' -- ' + detail : ''))
+    return
+  }
+  fail++
+  console.log('  [FAIL] ' + label + (detail ? ' -- ' + detail : ''))
 }
-const section = t => console.log("\n=== " + t + " ===")
+const section = t => console.log('\n=== ' + t + ' ===')
 
 // ---------------------------------------------------------
 // A. 函数级:复刻 daq-controller.ts 的映射逻辑
 // ---------------------------------------------------------
-section("A. 函数级:内存读穿透映射与 TSDB 形态一致性")
+section('A. 函数级:内存读穿透映射与 TSDB 形态一致性')
 
 /** 复刻 DaqController.pointsFromMeta(与 tsdb adapter 同规则) */
 function pointsFromMeta(meta) {
@@ -46,7 +51,7 @@ function framesFromBuffer(frameBuffer, id, tsMs) {
     out.push({
       at: r.tsMs,
       kind: r.kind,
-      points: r.kind === "vector" ? pointsFromMeta(r.meta) : undefined,
+      points: r.kind === 'vector' ? pointsFromMeta(r.meta) : undefined,
       metrics: r.metrics,
       meta: r.meta,
       deviceBindingId: r.deviceBindingId ?? null,
@@ -64,7 +69,7 @@ function queryFramesMapping(row) {
   return {
     at: row.tsMs,
     kind: row.kind,
-    points: row.kind === "vector" ? pointsFromMeta(row.meta) : undefined,
+    points: row.kind === 'vector' ? pointsFromMeta(row.meta) : undefined,
     metrics: row.metrics,
     meta: row.meta,
     deviceBindingId: row.device_binding_id ?? null,
@@ -80,10 +85,29 @@ function legacyFrameContent(tsdbRows, id, tsMs) {
   const rows = tsdbRows.filter(r => r.nodeId === id && r.tsMs >= tsMs - 1 && r.tsMs <= tsMs + 1)
     .map(queryFramesMapping)
   const row = rows.find(r => r.at === tsMs)
-  if (!row || row.kind !== "image") return { status: 404 }
+  if (!row || row.kind !== 'image') return { status: 404 }
   const key = row.meta.objectKey
   if (!key) return { status: 404 }
-  return { status: 200, key, mime: typeof row.meta.mime === "string" ? row.meta.mime : "image/png" }
+  return { status: 200, key, mime: typeof row.meta.mime === 'string' ? row.meta.mime : 'image/png' }
+}
+
+/**
+ * 读 PNG IHDR 的像素宽度(非 PNG / 太短 / chunk 不合法 → null)。
+ * PNG:8 字节签名 + [4B 长度][4B "IHDR"][4B 宽度][4B 高度]...
+ */
+function pngWidth(buf) {
+  if (!buf || buf.length < 24) return null
+  const sig = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+  for (let i = 0; i < 8; i++) if (buf[i] !== sig[i]) return null
+  if (String.fromCharCode(buf[12], buf[13], buf[14], buf[15]) !== 'IHDR') return null
+  return ((buf[16] << 24) | (buf[17] << 16) | (buf[18] << 8) | buf[19]) >>> 0
+}
+
+/** 两份字节是否完全相同 */
+function sameBytes(a, b) {
+  if (!a || !b || a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false
+  return true
 }
 
 /** 复刻「修复后」语义:先 buffer,未命中再 TSDB */
@@ -93,23 +117,23 @@ function fixedFrameContent(frameBuffer, tsdbRows, id, tsMs, thumb) {
     rows.push(...tsdbRows.filter(r => r.nodeId === id && r.tsMs >= tsMs - 1 && r.tsMs <= tsMs + 1).map(queryFramesMapping))
   }
   const row = rows.find(r => r.at === tsMs)
-  if (!row || row.kind !== "image") return { status: 404 }
+  if (!row || row.kind !== 'image') return { status: 404 }
   const key = thumb ? row.meta.thumbKey : row.meta.objectKey
   if (!key) return { status: 404 }
-  return { status: 200, key, mime: typeof row.meta.mime === "string" ? row.meta.mime : "image/png" }
+  return { status: 200, key, mime: typeof row.meta.mime === 'string' ? row.meta.mime : 'image/png' }
 }
 
 const TS = 1760000000000
-const NODE = "dn-race01"
+const NODE = 'dn-race01'
 const imageRow = {
-  nodeId: NODE, tsMs: TS, kind: "image", templateKey: "ccd-image", deviceBindingId: null,
+  nodeId: NODE, tsMs: TS, kind: 'image', templateKey: 'ccd-image', deviceBindingId: null,
   lineId: null, productId: null, recipeId: null, runId: null, points: 0,
-  meta: { objectKey: "daq/" + NODE + "/" + TS + ".png", thumbKey: "daq/" + NODE + "/" + TS + ".thumb.png", mime: "image/png", width: 640, height: 480 },
+  meta: { objectKey: 'daq/' + NODE + '/' + TS + '.png', thumbKey: 'daq/' + NODE + '/' + TS + '.thumb.png', mime: 'image/png', width: 640, height: 480 },
   metrics: { brightness: 128.5 },
   device_binding_id: null, line_id: null, product_id: null, recipe_id: null, run_id: null,
 }
 const vectorRow = {
-  nodeId: NODE, tsMs: TS, kind: "vector", templateKey: "plug-matrix-profile", deviceBindingId: null,
+  nodeId: NODE, tsMs: TS, kind: 'vector', templateKey: 'plug-matrix-profile', deviceBindingId: null,
   lineId: null, productId: null, recipeId: null, runId: null, points: 3,
   meta: { points: [1.5, 2.5, 3.5] }, metrics: { avg: 2.5 },
   device_binding_id: null, line_id: null, product_id: null, recipe_id: null, run_id: null,
@@ -117,47 +141,50 @@ const vectorRow = {
 const EMPTY_TSDB = []
 
 // A1 竞态复现:修复前 404
-ok(legacyFrameContent(EMPTY_TSDB, NODE, TS).status === 404, "竞态复现:未刷盘时[仅查 TSDB]返回 404")
+ok(legacyFrameContent(EMPTY_TSDB, NODE, TS).status === 404, '竞态复现:未刷盘时[仅查 TSDB]返回 404')
 
 // A2 修复后立刻可取
 const fixed = fixedFrameContent([imageRow], EMPTY_TSDB, NODE, TS, false)
-ok(fixed.status === 200, "修复生效:同刻[先查 buffer]返回 200", "status=" + fixed.status)
-ok(fixed.key === imageRow.meta.objectKey, "主图取 meta.objectKey", String(fixed.key))
-ok(fixed.mime === "image/png", "mime 透传自 meta.mime", String(fixed.mime))
-ok(fixedFrameContent([imageRow], EMPTY_TSDB, NODE, TS, true).key === imageRow.meta.thumbKey, "缩略图取 meta.thumbKey")
+ok(fixed.status === 200, '修复生效:同刻[先查 buffer]返回 200', 'status=' + fixed.status)
+ok(fixed.key === imageRow.meta.objectKey, '主图取 meta.objectKey', String(fixed.key))
+ok(fixed.mime === 'image/png', 'mime 透传自 meta.mime', String(fixed.mime))
+ok(fixedFrameContent([imageRow], EMPTY_TSDB, NODE, TS, true).key === imageRow.meta.thumbKey, '缩略图取 meta.thumbKey')
 
 // A3 形态一致性:buffer 路径 === TSDB 路径
 const fromBuffer = framesFromBuffer([imageRow], NODE, TS)[0]
 const fromTsdb = queryFramesMapping(imageRow)
 const keys = o => JSON.stringify(Object.keys(o).sort())
-ok(keys(fromBuffer) === keys(fromTsdb), "image:buffer 记录键集 === TSDB 记录键集", keys(fromBuffer))
-ok(JSON.stringify(fromBuffer) === JSON.stringify(fromTsdb), "image:buffer 记录值与 TSDB 逐一相等")
-ok(fromBuffer.points === undefined, "image:points 为 undefined(与 TSDB 一致)")
-ok(fromBuffer.meta === imageRow.meta, "image:meta 原样透传(objectKey/thumbKey/mime/width/height)")
+ok(keys(fromBuffer) === keys(fromTsdb), 'image:buffer 记录键集 === TSDB 记录键集', keys(fromBuffer))
+ok(JSON.stringify(fromBuffer) === JSON.stringify(fromTsdb), 'image:buffer 记录值与 TSDB 逐一相等')
+ok(fromBuffer.points === undefined, 'image:points 为 undefined(与 TSDB 一致)')
+ok(fromBuffer.meta === imageRow.meta, 'image:meta 原样透传(objectKey/thumbKey/mime/width/height)')
 
 const vecBuf = framesFromBuffer([vectorRow], NODE, TS)[0]
 const vecTsdb = queryFramesMapping(vectorRow)
-ok(JSON.stringify(vecBuf) === JSON.stringify(vecTsdb), "vector:buffer 记录与 TSDB 逐一相等(含 meta.points 还原)")
-ok(Array.isArray(vecBuf.points) && vecBuf.points.length === 3, "vector:points 从 meta.points 还原", JSON.stringify(vecBuf.points))
+ok(JSON.stringify(vecBuf) === JSON.stringify(vecTsdb), 'vector:buffer 记录与 TSDB 逐一相等(含 meta.points 还原)')
+ok(Array.isArray(vecBuf.points) && vecBuf.points.length === 3, 'vector:points 从 meta.points 还原', JSON.stringify(vecBuf.points))
 
 // A4 pointsFromMeta 防御规则
-ok(pointsFromMeta({ points: [] }) === undefined, "空点列 -> undefined")
-ok(pointsFromMeta({ points: "x" }) === undefined, "非数组 -> undefined")
-ok(pointsFromMeta({ points: [1, "a"] }) === undefined, "非数值成员 -> undefined")
-ok(pointsFromMeta({ points: new Array(4097).fill(1) }) === undefined, "超 4096 越界 -> undefined")
-ok(JSON.stringify(pointsFromMeta({ points: ["1", 2] })) === "[1,2]", "数值字符串归一为 number")
+ok(pointsFromMeta({ points: [] }) === undefined, '空点列 -> undefined')
+ok(pointsFromMeta({ points: 'x' }) === undefined, '非数组 -> undefined')
+ok(pointsFromMeta({ points: [1, 'a'] }) === undefined, '非数值成员 -> undefined')
+ok(pointsFromMeta({ points: new Array(4097).fill(1) }) === undefined, '超 4096 越界 -> undefined')
+ok(JSON.stringify(pointsFromMeta({ points: ['1', 2] })) === '[1,2]', '数值字符串归一为 number')
 
 // A5 命中不查 TSDB
 let tsdbCalls = 0
-const spy = () => { tsdbCalls++; return [] }
+const spy = () => {
+  tsdbCalls++
+  return []
+}
 if (framesFromBuffer([imageRow], NODE, TS).length === 0) spy()
-ok(tsdbCalls === 0, "buffer 命中时不触发 TSDB 查询")
+ok(tsdbCalls === 0, 'buffer 命中时不触发 TSDB 查询')
 if (framesFromBuffer([imageRow], NODE, TS + 1).length === 0) spy()
-ok(tsdbCalls === 1, "buffer 未命中时回退 TSDB 查询")
+ok(tsdbCalls === 1, 'buffer 未命中时回退 TSDB 查询')
 
 // A6 刷盘后无回归
-ok(fixedFrameContent([], [imageRow], NODE, TS, false).status === 200, "刷盘后(buffer 空)仍由 TSDB 路径返回 200")
-ok(fixedFrameContent([], [], NODE, TS, false).status === 404, "真正不存在的帧仍 404(未放水)")
+ok(fixedFrameContent([], [imageRow], NODE, TS, false).status === 200, '刷盘后(buffer 空)仍由 TSDB 路径返回 200')
+ok(fixedFrameContent([], [], NODE, TS, false).status === 404, '真正不存在的帧仍 404(未放水)')
 
 // A7 frames() 列表合并语义
 function mergeFrames(tsdbRows, frameBuffer, id, opts) {
@@ -172,139 +199,160 @@ function mergeFrames(tsdbRows, frameBuffer, id, opts) {
   return [...rows, ...pending].slice(0, Math.min(Math.max(opts.limit ?? 100, 1), 1000))
 }
 const merged = mergeFrames([], [imageRow, vectorRow], NODE, { limit: 10 })
-ok(merged.length === 2, "frames():未刷盘帧补入列表", "n=" + merged.length)
-ok(merged[0].at >= merged[1].at, "frames():按 at 降序")
-ok(mergeFrames([], [imageRow], NODE, { limit: 10, kind: "vector" }).length === 0, "frames():kind 过滤生效")
-ok(mergeFrames([], [imageRow, vectorRow], NODE, { limit: 10 }).length === 2, "frames():无重复(按 at 去重)")
+ok(merged.length === 2, 'frames():未刷盘帧补入列表', 'n=' + merged.length)
+ok(merged[0].at >= merged[1].at, 'frames():按 at 降序')
+ok(mergeFrames([], [imageRow], NODE, { limit: 10, kind: 'vector' }).length === 0, 'frames():kind 过滤生效')
+ok(mergeFrames([], [imageRow, vectorRow], NODE, { limit: 10 }).length === 2, 'frames():无重复(按 at 去重)')
 
 // ---------------------------------------------------------
 // B. 端到端
 // ---------------------------------------------------------
-section("B. 端到端:运行中的服务器")
+section('B. 端到端:运行中的服务器')
 
 // BASE 可能指向不可用端口;依次探测候选基址,取第一个能提供 DAQ API 的
-const candidates = [BASE, "http://127.0.0.1:3021", "http://127.0.0.1:3001"].filter((v, i, a) => a.indexOf(v) === i)
+const candidates = [BASE, 'http://127.0.0.1:3021', 'http://127.0.0.1:3001'].filter((v, i, a) => a.indexOf(v) === i)
 let API = null
 for (const c of candidates) {
   try {
-    const res = await fetch(c + "/api/workshop/daq/infra", { signal: AbortSignal.timeout(4000) })
+    const res = await fetch(c + '/api/workshop/daq/infra', { signal: AbortSignal.timeout(4000) })
     // 401 = 服务在,只是要鉴权;同样算可用
-    if (res.status < 500) { API = c; break }
-  } catch { /* 试下一个 */ }
+    if (res.status < 500) {
+      API = c
+      break
+    }
+  }
+  catch { /* 试下一个 */ }
 }
 const online = API != null
-if (online && API !== BASE) console.log("  " + BASE + " 不可用 -> 回退到 " + API)
+if (online && API !== BASE) console.log('  ' + BASE + ' 不可用 -> 回退到 ' + API)
 
 const api = async (path, opts = {}) => {
-  const res = await fetch(API + path, { ...opts, headers: { "content-type": "application/json", ...(opts.headers ?? {}) } })
-  const ct = res.headers.get("content-type") ?? ""
-  const body = ct.includes("application/json") ? await res.json().catch(() => null) : Buffer.from(await res.arrayBuffer())
+  const res = await fetch(API + path, { ...opts, headers: { 'content-type': 'application/json', ...(opts.headers ?? {}) } })
+  const ct = res.headers.get('content-type') ?? ''
+  const body = ct.includes('application/json') ? await res.json().catch(() => null) : Buffer.from(await res.arrayBuffer())
   return { status: res.status, ct, body }
 }
 
 if (!online) {
-  console.log("  [SKIP] 候选基址 " + candidates.join(", ") + " 均不可用 -> 跳过端到端;A 部分已函数级证明修复逻辑。")
-  console.log("\n结果:" + pass + " 通过 / " + fail + " 失败(E2E 跳过)")
+  console.log('  [SKIP] 候选基址 ' + candidates.join(', ') + ' 均不可用 -> 跳过端到端;A 部分已函数级证明修复逻辑。')
+  console.log('\n结果:' + pass + ' 通过 / ' + fail + ' 失败(E2E 跳过)')
   process.exit(fail === 0 ? 0 : 1)
 }
-console.log("  服务器在线:" + API)
+console.log('  服务器在线:' + API)
 
 // B1 鉴权:admin 全量可见(普通用户受产线 grant 过滤,节点列表为空)
-const ADMIN_EMAIL = process.env.AW_ADMIN_EMAIL ?? "admin@awshop.local"
-const ADMIN_PASS = process.env.AW_ADMIN_PASS ?? "admin123"
-const login = await api("/api/users/login", {
-  method: "POST",
+const ADMIN_EMAIL = process.env.AW_ADMIN_EMAIL ?? 'admin@awshop.local'
+const ADMIN_PASS = process.env.AW_ADMIN_PASS ?? 'admin123'
+const login = await api('/api/users/login', {
+  method: 'POST',
   body: JSON.stringify({ email: ADMIN_EMAIL, password: ADMIN_PASS }),
 })
 const token = login.body?.data?.token
-ok(!!token, "登录取得 token", token ? ADMIN_EMAIL + " role=" + login.body?.data?.user?.role : "status=" + login.status)
-if (!token) { console.log("\n结果:" + pass + " 通过 / " + fail + " 失败(无法鉴权,E2E 中止)"); process.exit(1) }
-const auth = { authorization: "Bearer " + token }
+ok(!!token, '登录取得 token', token ? ADMIN_EMAIL + ' role=' + login.body?.data?.user?.role : 'status=' + login.status)
+if (!token) {
+  console.log('\n结果:' + pass + ' 通过 / ' + fail + ' 失败(无法鉴权,E2E 中止)')
+  process.exit(1)
+}
+const auth = { authorization: 'Bearer ' + token }
 
 // B2 找 live image 节点(节点视图暴露 templateRef,非 templateKey)
-const idx = await api("/api/workshop/daq", { headers: auth })
+const idx = await api('/api/workshop/daq', { headers: auth })
 const d = idx.body?.data ?? {}
 const nodes = d.nodes ?? []
 const kindOf = {}
 for (const t of d.templates ?? []) kindOf[t.key] = t.signalKind
-const refOf = n => String(n.templateRef ?? "").replace(/^daq-/, "")
-const imgNodes = nodes.filter(n => kindOf[refOf(n)] === "image")
-console.log("  节点总数=" + nodes.length + "  image 节点=" + imgNodes.length
-  + "  framesStored=" + (d.controller?.framesStored ?? "?"))
+const refOf = n => String(n.templateRef ?? '').replace(/^daq-/, '')
+const imgNodes = nodes.filter(n => kindOf[refOf(n)] === 'image')
+console.log('  节点总数=' + nodes.length + '  image 节点=' + imgNodes.length
+  + '  framesStored=' + (d.controller?.framesStored ?? '?'))
 
 if (imgNodes.length === 0) {
-  console.log("  [SKIP] 服务器上无 image 类型节点 -> E2E 未执行(需先建 ccd-image 节点并开线)")
-  console.log("\n结果:" + pass + " 通过 / " + fail + " 失败(E2E 部分跳过)")
+  console.log('  [SKIP] 服务器上无 image 类型节点 -> E2E 未执行(需先建 ccd-image 节点并开线)')
+  console.log('\n结果:' + pass + ' 通过 / ' + fail + ' 失败(E2E 部分跳过)')
   process.exit(fail === 0 ? 0 : 1)
 }
 
 // B3 挑一个在采(enabled 且非 offline)的 image 节点
-const target = imgNodes.find(n => n.enabled && n.state !== "offline") ?? imgNodes.find(n => n.enabled) ?? imgNodes[0]
-console.log("  目标节点:" + target.id + " tpl=" + refOf(target) + " line=" + (target.lineId ?? "-")
-  + " enabled=" + target.enabled + " state=" + target.state)
+const target = imgNodes.find(n => n.enabled && n.state !== 'offline') ?? imgNodes.find(n => n.enabled) ?? imgNodes[0]
+console.log('  目标节点:' + target.id + ' tpl=' + refOf(target) + ' line=' + (target.lineId ?? '-')
+  + ' enabled=' + target.enabled + ' state=' + target.state)
 
 // B4 关键断言:捕捉「帧列表刚出现的新帧」并立刻回查 content。
 //     帧列表自身也走读穿透(修复覆盖),所以新帧一经出现即证明它在 buffer 或 TSDB 中;
 //     真正要证的是 content 端点对这种「极新鲜」的帧不再 404。
-console.log("\n  --- 轮询最新帧并立刻回查 content(关键断言) ---")
+console.log('\n  --- 轮询最新帧并立刻回查 content(关键断言) ---')
 
 const seen = new Set()
 let hit = null
 const probeLog = []
 const deadline = Date.now() + 90000
 while (Date.now() < deadline && !hit) {
-  const fr = await api("/api/workshop/daq/" + target.id + "/frames?limit=10", { headers: auth })
+  const fr = await api('/api/workshop/daq/' + target.id + '/frames?limit=10', { headers: auth })
   const list = fr.body?.data?.frames ?? []
   for (const f of list) {
     if (seen.has(f.at)) continue
     seen.add(f.at)
-    if (f.kind !== "image") continue
+    if (f.kind !== 'image') continue
     // 立刻回查(不等待,模拟前端收到 WS daq.frame 后的即时回查)
     const t0 = Date.now()
-    const c = await api("/api/workshop/daq/" + target.id + "/frames/content?ts=" + f.at, { headers: auth })
+    const c = await api('/api/workshop/daq/' + target.id + '/frames/content?ts=' + f.at, { headers: auth })
     const dt = Date.now() - t0
-    probeLog.push("ts=" + f.at + "->" + c.status)
-    if (c.status === 200) { hit = { frame: f, content: c, dt }; break }
+    probeLog.push('ts=' + f.at + '->' + c.status)
+    if (c.status === 200) {
+      hit = { frame: f, content: c, dt }
+      break
+    }
   }
   if (!hit) await new Promise(r => setTimeout(r, 250))
 }
 
-if (probeLog.length) console.log("  探测 " + probeLog.length + " 个新帧:" + probeLog.slice(0, 8).join(" | ") + (probeLog.length > 8 ? " ..." : ""))
+if (probeLog.length) console.log('  探测 ' + probeLog.length + ' 个新帧:' + probeLog.slice(0, 8).join(' | ') + (probeLog.length > 8 ? ' ...' : ''))
 
-ok(!!hit, "捕捉到新 ingest 的 image 帧并可立即取 content",
-  hit ? "ts=" + hit.frame.at + " 回查耗时=" + hit.dt + "ms" : "轮询 " + seen.size + " 帧均未成功")
+ok(!!hit, '捕捉到新 ingest 的 image 帧并可立即取 content',
+  hit ? 'ts=' + hit.frame.at + ' 回查耗时=' + hit.dt + 'ms' : '轮询 ' + seen.size + ' 帧均未成功')
 
 if (hit) {
   const c = hit.content
   const buf = c.body
-  ok(c.status === 200, "刚 ingest 的帧 content 立即可取(200)", "status=" + c.status)
-  ok(Buffer.isBuffer(buf) && buf.length > 0, "content 返回非空二进制", "bytes=" + (buf?.length ?? 0))
+  ok(c.status === 200, '刚 ingest 的帧 content 立即可取(200)', 'status=' + c.status)
+  ok(Buffer.isBuffer(buf) && buf.length > 0, 'content 返回非空二进制', 'bytes=' + (buf?.length ?? 0))
   const isPng = buf && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47
   const isJpg = buf && buf[0] === 0xff && buf[1] === 0xd8
-  ok(isPng || isJpg, "content 是合法 PNG/JPEG 魔数", isPng ? "PNG" : isJpg ? "JPEG" : "ct=" + c.ct)
-  ok(String(c.ct).startsWith("image/"), "content-type 为 image/*", c.ct)
+  ok(isPng || isJpg, 'content 是合法 PNG/JPEG 魔数', isPng ? 'PNG' : isJpg ? 'JPEG' : 'ct=' + c.ct)
+  ok(String(c.ct).startsWith('image/'), 'content-type 为 image/*', c.ct)
 
   // 主图 vs 缩略图应是不同字节(缩略图按模板 sink 缩到 256 宽)
-  const hasThumb = hit.frame.meta && typeof hit.frame.meta.thumbKey === "string"
+  const hasThumb = hit.frame.meta && typeof hit.frame.meta.thumbKey === 'string'
   if (hasThumb) {
-    const t = await api("/api/workshop/daq/" + target.id + "/frames/content?ts=" + hit.frame.at + "&thumb=1", { headers: auth })
-    ok(t.status === 200 && t.body?.length > 0, "缩略图 content 可取", "status=" + t.status + " bytes=" + (t.body?.length ?? 0))
-    ok(t.body?.length < buf.length, "缩略图小于主图(证明走 thumbKey 分支)",
-      (t.body?.length ?? 0) + " < " + buf.length)
+    const t = await api('/api/workshop/daq/' + target.id + '/frames/content?ts=' + hit.frame.at + '&thumb=1', { headers: auth })
+    ok(t.status === 200 && t.body?.length > 0, '缩略图 content 可取', 'status=' + t.status + ' bytes=' + (t.body?.length ?? 0))
+    // 断言用**像素宽度**而不是字节大小:合成帧的主图往往是低熵图案(平坦/渐变),
+    // 其 PNG 可能比"降采样后反而引入高频"的缩略图更小 —— 按字节比大小会假阳性。
+    // 直接读 IHDR 宽高才是"确实走了 thumbKey 分支"的硬证据。
+    const mainW = pngWidth(buf)
+    const thumbW = pngWidth(t.body)
+    if (mainW != null && thumbW != null) {
+      ok(thumbW < mainW, '缩略图像素宽度小于主图(证明走 thumbKey 分支)',
+        'thumb ' + thumbW + 'px < main ' + mainW + 'px')
+    }
+    else {
+      ok(!sameBytes(buf, t.body), '缩略图与主图字节不同(非 PNG 无法比尺寸)',
+        'main=' + (buf?.length ?? 0) + 'B thumb=' + (t.body?.length ?? 0) + 'B')
+    }
   }
-  else { console.log("  [INFO] 该帧无 thumbKey -> 跳过缩略图断言") }
+  else { console.log('  [INFO] 该帧无 thumbKey -> 跳过缩略图断言') }
 
   // 未放水:不存在的 ts 仍 404
-  const miss = await api("/api/workshop/daq/" + target.id + "/frames/content?ts=1", { headers: auth })
-  ok(miss.status === 404, "不存在的帧仍返回 404(未放水)", "status=" + miss.status)
+  const miss = await api('/api/workshop/daq/' + target.id + '/frames/content?ts=1', { headers: auth })
+  ok(miss.status === 404, '不存在的帧仍返回 404(未放水)', 'status=' + miss.status)
 
   // 刷盘后仍可取(TSDB 路径无回归):等待 > 500ms 防抖窗 + 写库时间
-  console.log("  等待 1500ms(越过 500ms 刷盘窗)后复测同一 ts ...")
+  console.log('  等待 1500ms(越过 500ms 刷盘窗)后复测同一 ts ...')
   await new Promise(r => setTimeout(r, 1500))
-  const again = await api("/api/workshop/daq/" + target.id + "/frames/content?ts=" + hit.frame.at, { headers: auth })
-  ok(again.status === 200 && again.body?.length === buf.length, "刷盘后同一帧仍可取且字节一致(TSDB 路径无回归)",
-    "status=" + again.status + " bytes=" + (again.body?.length ?? 0))
+  const again = await api('/api/workshop/daq/' + target.id + '/frames/content?ts=' + hit.frame.at, { headers: auth })
+  ok(again.status === 200 && again.body?.length === buf.length, '刷盘后同一帧仍可取且字节一致(TSDB 路径无回归)',
+    'status=' + again.status + ' bytes=' + (again.body?.length ?? 0))
 }
 
-console.log("\n结果:" + pass + " 通过 / " + fail + " 失败")
+console.log('\n结果:' + pass + ' 通过 / ' + fail + ' 失败')
 process.exit(fail === 0 ? 0 : 1)

package/scripts/test-events-index.mjs

@@ -0,0 +1,176 @@
+/**
+ * 回归测试 —— 事件 ring 增量索引与增量时间线的**语义等价性**。
+ *
+ * 背景(为什么要测):events store 的两条热路径从"每帧全量过滤"改成了增量,
+ * 增量实现的危险在于**悄悄与全量语义分叉**(少一条、多一条、淘汰后残留),
+ * 而这类 bug 只在长会话里出现,人工测不出来。所以这里做**属性对照测试**:
+ * 用同一串随机操作(ingest / 淘汰 / 历史合并 / 过滤切换 / 聚焦切换)同时喂给
+ * 「真实 store」与「朴素全量参照实现」,逐拍比对结果必须完全一致。
+ *
+ * 运行:node scripts/test-events-index.mjs
+ */
+import { register } from 'node:module'
+import { createPinia, setActivePinia } from 'pinia'
+
+register(new URL('./_audit/ts-resolve-hook.mjs', import.meta.url).href)
+
+const { useEventsStore, matchesTimeline, FILTER_TYPES } = await import('../app/stores/workshop/events.ts')
+
+let pass = 0
+const fails = []
+const check = (name, ok, detail = '') => {
+  if (ok) {
+    pass++
+    console.log(`  ✔ ${name}${detail ? ` — ${detail}` : ''}`)
+    return
+  }
+  fails.push(name)
+  console.log(`  ✘ ${name}${detail ? ` — ${detail}` : ''}`)
+}
+
+const RING_CAP = 5000
+
+// ---------- 朴素参照实现 ----------
+// 关键:谓词**复用产品导出的 matchesTimeline**。本测试要证明的是"增量维护状态
+// (byAgent 桶 / upToIdx / headSeq / 淘汰同步)与全量重算等价",不是重新推导过滤语义。
+// 自己再抄一份谓词只会引入假阳性(第一版就两次栽在这上面:key 档位的 tier 判定、
+// 以及 key 档位提前返回而不受 focus 影响)。
+const refFilter = (items, filter, focus) =>
+  items.filter(e => matchesTimeline(e, filter, FILTER_TYPES[filter], focus))
+
+const refByAgent = (items, agentId) => items.filter(e => e.agentId === agentId)
+
+// ---------- 随机操作序列 ----------
+let seed = 0x2F6E2B1
+const rnd = () => {
+  seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0
+  return seed / 0x100000000
+}
+const pick = arr => arr[Math.floor(rnd() * arr.length)]
+
+const AGENTS = ['a1', 'a2', 'a3', 'a4', 'a5']
+const TYPES = ['agent.message', 'agent.delta', 'agent.status.message', 'a2a.message', 'task.status', 'task.progress', 'a2a.artifact', 'error', 'agent.member']
+
+function mkEnvelope(seq) {
+  const type = pick(TYPES)
+  const agentId = type === 'error' ? undefined : pick(AGENTS)
+  // 覆盖各档位:task.status 的终态/等待态、require-reply 的 attention、普通过程帧
+  const status = type === 'task.status' ? pick(['WORKING', 'COMPLETED', 'FAILED', 'WAITING']) : undefined
+  return {
+    seq,
+    channelId: 'ch1',
+    type,
+    agentId,
+    taskId: type.startsWith('task.') ? `t${Math.floor(rnd() * 3)}` : undefined,
+    at: new Date(1700000000000 + seq * 10).toISOString(),
+    payload: type === 'agent.delta'
+      ? { delta: `d${seq}` }
+      : (status ? { state: status } : (rnd() < 0.2 ? { metadata: { 'x-aw-require-reply': 'true' } } : {})),
+  }
+}
+
+const FILTERS = ['all', 'messages', 'tasks', 'team', 'errors', 'key']
+
+async function main() {
+  setActivePinia(createPinia())
+  const store = useEventsStore()
+  const CH = 'ch1'
+
+  // 初始快照(建立 ring)
+  store.ingest({ seq: 0, channelId: CH, type: 'channel.snapshot', payload: {} })
+
+  let seq = 0
+  let mismatches = 0
+  const STEPS = 6000
+  // 4000 步之后超过 RING_CAP 会开始淘汰 —— 专门覆盖"淘汰后索引残留"这一最易错的分支
+  const historyScript = []
+  for (let i = 0; i < 6; i++) {
+    const extra = []
+    for (let k = 0; k < 40; k++) extra.push(mkEnvelope(seq + 1 + k))
+    historyScript.push({ atStep: Math.floor(STEPS * (i + 1) / 7), items: extra })
+  }
+
+  for (let step = 0; step < STEPS; step++) {
+    // 1) 推进 seq 并 ingest 一帧
+    seq += 1
+    const e = mkEnvelope(seq)
+    store.ingest(e)
+
+    // 2) 偶发:切换过滤 / 聚焦
+    if (step % 250 === 0) store.setFilter(CH, pick(FILTERS))
+    if (step % 317 === 0) store.setFocusAgent(CH, rnd() < 0.6 ? pick(AGENTS) : null)
+
+    // 3) 偶发:历史批量合并(走 reindex 全量重建路径)
+    const script = historyScript.find(s => s.atStep === step)
+    if (script) {
+      for (const item of script.items) store.ingest(item)
+      seq += script.items.length
+    }
+
+    // 4) 对照:ring items 本身
+    const ring = store.rings[CH]
+    if (!ring) {
+      mismatches++
+      console.log(`  ! step ${step}: ring 丢失`)
+      break
+    }
+
+    // 5) 对照:每个 agent 的子序列(索引)必须与全量过滤一致
+    for (const a of AGENTS) {
+      const got = store.agentEvents(CH, a)
+      const want = refByAgent(ring.items, a)
+      if (got.length !== want.length || got.some((x, i) => x !== want[i])) {
+        mismatches++
+        console.log(`  ! step ${step} agent=${a} 索引漂移:got=${got.length} want=${want.length}`)
+        break
+      }
+    }
+    if (mismatches) break
+
+    // 6) 对照:时间线(增量)必须与全量过滤一致
+    const filter = store.filters[CH] ?? 'all'
+    const focus = store.focusAgents[CH] ?? null
+    const gotTl = store.timeline(CH)
+    const wantTl = refFilter(ring.items, filter, focus)
+    if (gotTl.length !== wantTl.length || gotTl.some((x, i) => x !== wantTl[i])) {
+      mismatches++
+      console.log(`  ! step ${step} timeline(${filter},focus=${focus}) 漂移:got=${gotTl.length} want=${wantTl.length}`)
+      break
+    }
+  }
+
+  check(`${STEPS} 步随机操作后 ring 未丢失`, Boolean(store.rings[CH]))
+  check('agent 子序列索引与全量过滤逐拍一致', mismatches === 0, `mismatches=${mismatches}`)
+  check('增量时间线与全量过滤逐拍一致', mismatches === 0, `mismatches=${mismatches}`)
+  check('ring 已触发淘汰(覆盖淘汰分支)', store.rings[CH].items.length <= RING_CAP,
+    `items=${store.rings[CH].items.length} cap=${RING_CAP}`)
+  // 关键:总 seq 必须超过 cap,否则整段测试根本没走到"满环 + 头部淘汰"这条最易错的分支
+  check('总 seq 已越过 ring 容量(确认走过淘汰路径)', seq > RING_CAP, `seq=${seq} cap=${RING_CAP}`)
+
+  // 索引无悬挂引用:所有桶内元素必须仍在 items 中(否则是内存泄漏 + 查询命中幽灵条目)
+  const inRing = new Set(store.rings[CH].items)
+  let dangling = 0
+  for (const a of AGENTS) for (const e of store.agentEvents(CH, a)) if (!inRing.has(e)) dangling++
+  check('索引无悬挂引用(不持有已淘汰条目)', dangling === 0, `dangling=${dangling}`)
+
+  // 索引覆盖率:所有带 agentId 的 items 都能在其桶里找到
+  let uncovered = 0
+  for (const e of store.rings[CH].items) {
+    if (!e.agentId) continue
+    if (!store.agentEvents(CH, e.agentId).includes(e)) uncovered++
+  }
+  check('索引覆盖完整(每条带 agentId 的事件都在桶内)', uncovered === 0, `uncovered=${uncovered}`)
+
+  // 快照重建必须清空索引
+  store.ingest({ seq: seq + 100, channelId: CH, type: 'channel.snapshot', payload: {} })
+  const emptyOk = AGENTS.every(a => store.agentEvents(CH, a).length === 0) && store.timeline(CH).length === 0
+  check('channel.snapshot 重建后索引与时间线均为空', emptyOk)
+
+  console.log(`\n结果:${pass} 通过 / ${fails.length} 失败`)
+  process.exit(fails.length === 0 ? 0 : 1)
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})