agentworkshop 0.7.27 → 0.7.34

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

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+/**
+ * scripts/test-daq-frame-race.mjs —— DAQ 帧「先广播后落库」竞态验证。
+ *
+ * 竞态:ingestFrame() 把帧 push 进内存 frameBuffer 后立刻广播 WS daq.frame,
+ * 而 frameBuffer 是 500ms 防抖异步刷盘 —— 前端收到帧马上回查
+ * /api/workshop/daq/:id/frames/content?ts=<tsMs> 会在落库前拿到 404。
+ *
+ * 修复:frameContent/frames 查询侧「内存读穿透」—— 先按 (nodeId, tsMs) 查
+ * frameBuffer,未命中再查 TSDB;返回结构与 TSDB 查询路径逐字段一致。
+ *
+ * A. 函数级:复刻 framesFromBuffer 映射,证明竞态存在 + 修复后一致
+ * B. 端到端:对运行中服务器注册用户 → 找/建 image 节点 → 采一帧 →
+ *    在 WS 广播后立刻(远早于 500ms 刷盘)回查 content,断言 200 + PNG/JPEG。
+ *
+ * 用法:node scripts/test-daq-frame-race.mjs [base]   默认 http://127.0.0.1:3021
+ * 服务器未起时自动降级为仅 A 部分。
+ */
+
+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 section = t => console.log("\n=== " + t + " ===")
+
+// ---------------------------------------------------------
+// A. 函数级:复刻 daq-controller.ts 的映射逻辑
+// ---------------------------------------------------------
+section("A. 函数级:内存读穿透映射与 TSDB 形态一致性")
+
+/** 复刻 DaqController.pointsFromMeta(与 tsdb adapter 同规则) */
+function pointsFromMeta(meta) {
+  const p = meta.points
+  if (!Array.isArray(p) || p.length === 0 || p.length > 4096) return undefined
+  return p.every(x => Number.isFinite(Number(x))) ? p.map(Number) : undefined
+}
+
+/** 复刻 DaqController.framesFromBuffer(帧 buffer 行 -> DaqFrameRecord) */
+function framesFromBuffer(frameBuffer, id, tsMs) {
+  const out = []
+  for (const r of frameBuffer) {
+    if (r.nodeId !== id || r.tsMs !== tsMs) continue
+    out.push({
+      at: r.tsMs,
+      kind: r.kind,
+      points: r.kind === "vector" ? pointsFromMeta(r.meta) : undefined,
+      metrics: r.metrics,
+      meta: r.meta,
+      deviceBindingId: r.deviceBindingId ?? null,
+      lineId: r.lineId ?? null,
+      productId: r.productId ?? null,
+      recipeId: r.recipeId ?? null,
+      runId: r.runId ?? null,
+    })
+  }
+  return out
+}
+
+/** 复刻 sqlite/timescale adapter 的 queryFrames 映射(落库后的同一行) */
+function queryFramesMapping(row) {
+  return {
+    at: row.tsMs,
+    kind: row.kind,
+    points: row.kind === "vector" ? pointsFromMeta(row.meta) : undefined,
+    metrics: row.metrics,
+    meta: row.meta,
+    deviceBindingId: row.device_binding_id ?? null,
+    lineId: row.line_id ?? null,
+    productId: row.product_id ?? null,
+    recipeId: row.recipe_id ?? null,
+    runId: row.run_id ?? null,
+  }
+}
+
+/** 复刻「修复前」语义:只查 TSDB(buffer 未刷盘 => [] => 404) */
+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 }
+  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" }
+}
+
+/** 复刻「修复后」语义:先 buffer,未命中再 TSDB */
+function fixedFrameContent(frameBuffer, tsdbRows, id, tsMs, thumb) {
+  const rows = framesFromBuffer(frameBuffer, id, tsMs)
+  if (rows.length === 0) {
+    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 }
+  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" }
+}
+
+const TS = 1760000000000
+const NODE = "dn-race01"
+const imageRow = {
+  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 },
+  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,
+  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,
+}
+const EMPTY_TSDB = []
+
+// A1 竞态复现:修复前 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")
+
+// 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)")
+
+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))
+
+// 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")
+
+// A5 命中不查 TSDB
+let tsdbCalls = 0
+const spy = () => { tsdbCalls++; return [] }
+if (framesFromBuffer([imageRow], NODE, TS).length === 0) spy()
+ok(tsdbCalls === 0, "buffer 命中时不触发 TSDB 查询")
+if (framesFromBuffer([imageRow], NODE, TS + 1).length === 0) spy()
+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(未放水)")
+
+// A7 frames() 列表合并语义
+function mergeFrames(tsdbRows, frameBuffer, id, opts) {
+  const rows = tsdbRows.map(queryFramesMapping)
+  const seen = new Set(rows.map(r => r.at))
+  const pending = frameBuffer.filter(r => r.nodeId === id
+    && (opts.kind == null || r.kind === opts.kind)
+    && r.tsMs >= (opts.fromMs ?? 0) && r.tsMs <= (opts.toMs ?? Date.now()))
+    .filter(r => !seen.has(r.tsMs))
+    .sort((a, b) => b.tsMs - a.tsMs)
+    .map(r => framesFromBuffer([r], id, r.tsMs)[0])
+  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 去重)")
+
+// ---------------------------------------------------------
+// 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)
+let API = null
+for (const c of candidates) {
+  try {
+    const res = await fetch(c + "/api/workshop/daq/infra", { signal: AbortSignal.timeout(4000) })
+    // 401 = 服务在,只是要鉴权;同样算可用
+    if (res.status < 500) { API = c; break }
+  } catch { /* 试下一个 */ }
+}
+const online = API != null
+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())
+  return { status: res.status, ct, body }
+}
+
+if (!online) {
+  console.log("  [SKIP] 候选基址 " + candidates.join(", ") + " 均不可用 -> 跳过端到端;A 部分已函数级证明修复逻辑。")
+  console.log("\n结果:" + pass + " 通过 / " + fail + " 失败(E2E 跳过)")
+  process.exit(fail === 0 ? 0 : 1)
+}
+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",
+  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 }
+
+// B2 找 live image 节点(节点视图暴露 templateRef,非 templateKey)
+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 ?? "?"))
+
+if (imgNodes.length === 0) {
+  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)
+
+// B4 关键断言:捕捉「帧列表刚出现的新帧」并立刻回查 content。
+//     帧列表自身也走读穿透(修复覆盖),所以新帧一经出现即证明它在 buffer 或 TSDB 中;
+//     真正要证的是 content 端点对这种「极新鲜」的帧不再 404。
+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 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
+    // 立刻回查(不等待,模拟前端收到 WS daq.frame 后的即时回查)
+    const t0 = Date.now()
+    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 }
+  }
+  if (!hit) await new Promise(r => setTimeout(r, 250))
+}
+
+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 + " 帧均未成功")
+
+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))
+  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)
+
+  // 主图 vs 缩略图应是不同字节(缩略图按模板 sink 缩到 256 宽)
+  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)
+  }
+  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)
+
+  // 刷盘后仍可取(TSDB 路径无回归):等待 > 500ms 防抖窗 + 写库时间
+  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))
+}
+
+console.log("\n结果:" + pass + " 通过 / " + fail + " 失败")
+process.exit(fail === 0 ? 0 : 1)

package/scripts/test-data-root.mjs

@@ -0,0 +1,208 @@
+/**
+ * 回归测试 —— 单一数据根(.AgentWorkShop/data)与「最新者胜」迁移
+ *
+ * 覆盖:
+ *   1. 静态断言:全部 JSON 仓库不再自建 cwd 相对路径(process.cwd().endsWith('server')
+ *      / 'server', 'data'),且统一 import ensureDataDir;
+ *   2. 解析器:注入 cwd/env 后数据目录落在 <cwd>/.AgentWorkShop/data,与 process.cwd() 无关;
+ *   3. 迁移:旧位置严格更新时覆盖配置根,目标更新或同时刻时保持不动(不再永久分叉);
+ *   4. 收尾:清理临时目录。
+ *
+ * 运行: node scripts/test-data-root.mjs
+ */
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, utimesSync, writeFileSync, readdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { dataDirFor, resolveRunMode, ensureDataDir } from '../shared/config/home.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+
+let pass = 0, fail = 0
+// 与 scripts/test-lru.mjs / test-rollback-index.mjs 同款 PASS/FAIL 行式断言
+// (分支体保持单语句以过 @stylistic/max-statements-per-line)
+const check = (n, ok, d = '') => {
+  if (ok) return console.log('  PASS  ' + n) ?? pass++
+  return console.log('  FAIL  ' + n + (d ? '  — ' + d : '')) ?? fail++
+}
+
+/** 静态断言必须覆盖的 9 个 JSON 仓库(相对检出根) */
+const TARGETS = [
+  'server/services/workshop/daq/daq-node.repo.ts',
+  'server/services/workshop/dcw/dcw-node.repo.ts',
+  'server/services/workshop/dcw/dcw-line.repo.ts',
+  'server/services/workshop/dcw/dcw-product.repo.ts',
+  'server/services/workshop/dcw/dcw-recipe.repo.ts',
+  'server/services/workshop/dcw/dcw-templates.ts',
+  'server/services/workshop/dcw/recipe-rollback.repo.ts',
+  'server/services/workshop/dcw/line-run.ts',
+  'server/services/workshop/scene/scene-layout.repo.ts',
+]
+
+// 临时工作区(全部测试产物都在其下,结束时整体删除;绝不触碰真实 server/data 与 .AgentWorkShop/data)
+const TMP = mkdtempSync(join(tmpdir(), 'aw-data-root-'))
+// 隔离:注入独立 AW_HOME,绝不落到真实 ~/.AgentWorkShop
+const runEnv = { ...process.env, AW_HOME: join(TMP, 'fake-home') }
+
+/** 造一个「项目工作区」:含 .AgentWorkShop 目录即被识别为项目运行时根 */
+function makeWorkspace(name) {
+  const ws = join(TMP, name)
+  mkdirSync(join(ws, '.AgentWorkShop'), { recursive: true })
+  return ws
+}
+
+/** 写文件并显式设定 mtime(避免依赖文件系统时间戳精度) */
+function writeWithMtime(file, content, mtimeMs) {
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, content, 'utf8')
+  const secs = mtimeMs / 1000
+  utimesSync(file, secs, secs)
+}
+
+const mtimeOf = f => statSync(f).mtimeMs
+const read = f => readFileSync(f, 'utf8')
+
+// 触发点原文(用模板串包裹,避免内层单引号影响引号风格规则)
+const BAD_PATH_LITERAL = `'server', 'data'`
+const BAD_CWD_GUARD = `process.cwd().endsWith('server')`
+
+console.log('\n━━━ 1. 静态断言:9 个仓库不再自建 cwd 相对路径 ━━━')
+for (const rel of TARGETS) {
+  const abs = join(REPO, rel)
+  let src
+  try {
+    src = readFileSync(abs, 'utf8')
+  }
+  catch (err) {
+    check(`${rel} 可读取`, false, String(err.message))
+    continue
+  }
+  check(`${rel} 不含 'server', 'data'`, !src.includes(BAD_PATH_LITERAL))
+  check(`${rel} 不含 process.cwd().endsWith('server')`, !src.includes(BAD_CWD_GUARD))
+  check(`${rel} import 了 ensureDataDir`, /import\s*\{[^}]*\bensureDataDir\b[^}]*\}\s*from\s*'[^']*shared\/config\/home\.mjs'/.test(src))
+}
+
+// 反向兜底:整个 server/ 目录再扫一遍,防止遗漏同类写法(本用例的文件列表本身也可能漏)
+const strayFiles = []
+const walk = (dir) => {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const abs = join(dir, e.name)
+    if (e.isDirectory()) walk(abs)
+    else if (/\.(ts|mjs)$/.test(e.name)) {
+      const text = read(join(dir, e.name))
+      if (text.includes(BAD_PATH_LITERAL) || text.includes(BAD_CWD_GUARD)) strayFiles.push(relative(REPO, abs))
+    }
+  }
+}
+try {
+  walk(join(REPO, 'server'))
+  check('server/ 全目录无同类 cwd 相对数据路径', strayFiles.length === 0, strayFiles.join(', '))
+}
+catch (err) {
+  check('server/ 全目录扫描完成', false, String(err.message))
+}
+
+console.log('\n━━━ 2. 解析器:数据根 = <cwd>/.AgentWorkShop/data ━━━')
+const wsA = makeWorkspace('proj-a')
+{
+  const rm = resolveRunMode({ cwd: wsA, env: runEnv })
+  const expected = join(wsA, '.AgentWorkShop', 'data')
+  check('mode = repo', rm.mode === 'repo', 'mode=' + rm.mode)
+  check('configRoot = <cwd>/.AgentWorkShop', resolve(rm.configRoot) === resolve(wsA, '.AgentWorkShop'), rm.configRoot)
+  check('dataDir = <cwd>/.AgentWorkShop/data', resolve(rm.dataDir) === resolve(expected), rm.dataDir)
+
+  const dir = dataDirFor(wsA, runEnv)
+  check('dataDirFor(cwd) 同上', resolve(dir) === resolve(expected), dir)
+  check('dataDirFor 只解析不建目录', !existsSync(dir))
+
+  // 与 process.cwd() 无关:同一个 cwd 参数在任意进程工作目录下结果一致
+  const before = process.cwd()
+  const returned = ensureDataDir(wsA, runEnv)
+  check('ensureDataDir 返回数据根', resolve(returned) === resolve(expected), returned)
+  check('ensureDataDir 建好目录', existsSync(dir) && statSync(dir).isDirectory())
+  check('调用后 process.cwd() 未被改变', process.cwd() === before, process.cwd())
+  check('两个不同 cwd 各自独立', resolve(dataDirFor(wsA, runEnv)) !== resolve(dataDirFor(makeWorkspace('proj-b'), runEnv)))
+  check('结果不落在检出仓库内', !resolve(dir).startsWith(resolve(REPO)), dir)
+
+  // 注入 env 优先:AW_DATA_DIR 覆盖解析(启动器注入路径的契约)
+  const forced = join(TMP, 'forced-data')
+  check('AW_DATA_DIR 优先', resolve(dataDirFor(wsA, { ...runEnv, AW_DATA_DIR: forced })) === resolve(forced))
+}
+
+console.log('\n━━━ 3. 迁移:最新者胜(不再永久分叉) ━━━')
+{
+  const ws = makeWorkspace('migrate')
+  const legacy = join(ws, 'server', 'data')
+  const dest = join(ws, '.AgentWorkShop', 'data')
+  const xSrc = join(legacy, 'x.json')
+  const xDst = join(dest, 'x.json')
+  const now = Date.now()
+
+  // 3a. 目标缺失 → 必须复制(原行为保留)
+  mkdirSync(dest, { recursive: true })
+  writeWithMtime(xSrc, '{"v":"legacy-only"}', now - 30000)
+  ensureDataDir(ws, runEnv)
+  check('a) 目标缺失时复制', existsSync(xDst) && read(xDst) === '{"v":"legacy-only"}', xDst)
+
+  // 3b. 旧位置严格更新 → 覆盖配置根(收敛的关键)
+  writeWithMtime(xDst, '{"v":"configroot-old"}', now - 20000)
+  writeWithMtime(xSrc, '{"v":"legacy-new"}', now - 10000)
+  const srcMs = mtimeOf(xSrc), dstMs = mtimeOf(xDst)
+  check('b) 前置:mtime 严格有序(旧位置更新)', srcMs > dstMs, `src=${srcMs} dst=${dstMs}`)
+  ensureDataDir(ws, runEnv)
+  check('b) 旧位置更新时覆盖为目标', read(xDst) === '{"v":"legacy-new"}', read(xDst))
+  check('b) 旧文件不被删除', existsSync(xSrc))
+
+  // 3c. 反向:配置根更新 → 保留配置根内容(不得回退)
+  writeWithMtime(xSrc, '{"v":"legacy-stale"}', now - 20000)
+  writeWithMtime(xDst, '{"v":"configroot-new"}', now - 5000)
+  const srcMs2 = mtimeOf(xSrc), dstMs2 = mtimeOf(xDst)
+  check('c) 前置:mtime 严格有序(目标更新)', dstMs2 > srcMs2, `src=${srcMs2} dst=${dstMs2}`)
+  ensureDataDir(ws, runEnv)
+  check('c) 目标更新时保留目标内容', read(xDst) === '{"v":"configroot-new"}', read(xDst))
+
+  // 3d. 同时刻 → 不复制
+  const same = now - 1000
+  writeWithMtime(xSrc, '{"v":"legacy-tie"}', same)
+  writeWithMtime(xDst, '{"v":"configroot-tie"}', same)
+  check('d) 前置:mtime 相等', mtimeOf(xSrc) === mtimeOf(xDst), `${mtimeOf(xSrc)} vs ${mtimeOf(xDst)}`)
+  ensureDataDir(ws, runEnv)
+  check('d) 同时刻不覆盖', read(xDst) === '{"v":"configroot-tie"}', read(xDst))
+
+  // 3e. 保留既有守卫:非运行时文件不迁移
+  writeWithMtime(join(legacy, 'noise.log'), 'log', now)
+  writeWithMtime(join(legacy, 'script.mjs'), 'x', now)
+  // 与 .json 同名的目录:必须按「非文件」跳过(statSync(src).isFile() 守卫)
+  mkdirSync(join(legacy, 'sub.json'), { recursive: true })
+  ensureDataDir(ws, runEnv)
+  check('e) 非运行时扩展名不迁移', !existsSync(join(dest, 'noise.log')) && !existsSync(join(dest, 'script.mjs')))
+  check('e) 目录不被当作文件复制', !existsSync(join(dest, 'sub.json')) && statSync(join(legacy, 'sub.json')).isDirectory())
+  check('e) 单文件失败不阻断其余(其它文件仍迁入)', existsSync(xDst))
+
+  // 3f. 保留既有守卫:AW_MODE=home 跳过整个迁移
+  const wsHome = makeWorkspace('migrate-home')
+  const homeLegacy = join(wsHome, 'server', 'data')
+  writeWithMtime(join(homeLegacy, 'y.json'), '{"v":"home-mode"}', now)
+  ensureDataDir(wsHome, { ...runEnv, AW_MODE: 'home', AW_HOME: join(TMP, 'home-mode-root') })
+  check('f) AW_MODE=home 时跳过迁移', !existsSync(join(wsHome, '.AgentWorkShop', 'data', 'y.json')))
+
+  // 3g. 幂等:重复调用不再变化
+  const beforeIdem = read(xDst)
+  ensureDataDir(ws, runEnv)
+  ensureDataDir(ws, runEnv)
+  check('g) 幂等(重复调用结果稳定)', read(xDst) === beforeIdem, read(xDst))
+}
+
+console.log(`\n━━━ 结果:${pass} passed, ${fail} failed ━━━\n`)
+
+// 清理临时目录(含上面所有工作区)
+try {
+  rmSync(TMP, { recursive: true, force: true })
+  console.log('  临时目录已清理: ' + TMP)
+}
+catch (err) {
+  console.log('  临时目录清理失败(可手动删除): ' + TMP + ' — ' + String(err.message))
+}
+
+process.exit(fail === 0 ? 0 : 1)