agentworkshop 0.7.39 → 0.7.41

package/scripts/_dbg-param-real-scenario.mjs

@@ -0,0 +1,153 @@
+/**
+ * 真实场景测试:用户/Agent 只管工艺参数(设温度多少度),PLC 细节由标准转换模式封装。
+ *
+ *  前置:隔离 AW 实例(E2E_ROOT,首注册即 admin)+ 运行中的 plc-node-simulator(E2E_SIM_API)。
+ *  ①配置阶段(集成工程师,一次性):取模拟器「对接导出」→ 以标准转换模式(float32)一键建工艺参数映射
+ *  ②运行阶段(用户视角):参数列表(无寄存器细节)→ 设 温度185/210 → 模拟器 API 确认真实收到 →
+ *    参数读回一致 → 越基准限界 400 → 模拟器侧手动改值 → 用户参数读到新值(读方向同样自动换算)
+ *  ③收尾:模拟器信号值复原 + 产线 purge。
+ * 运行: node scripts/_dbg-param-real-scenario.mjs
+ */
+const ROOT = process.env.E2E_ROOT ?? 'http://127.0.0.1:3399'
+const SIM_API = process.env.E2E_SIM_API ?? 'http://127.0.0.1:4010'
+let failed = 0
+const check = (name, ok, detail = '') => { console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`); if (!ok) failed++ }
+const sleep = (ms) => new Promise(r => setTimeout(r, ms))
+const j = async (base, u, m = 'GET', b, h = {}) => {
+  const r = await fetch(base + u, { method: m, headers: { 'content-type': 'application/json', ...h }, body: b ? JSON.stringify(b) : undefined }).then(x => x.json())
+  if (r.error) return { ...r, _status: r.statusCode }
+  return r
+}
+
+// ---- 认证:AW_E2E_TOKEN > token 缓存文件(首注册即 admin,复跑复用) > 现场注册 ----
+let token = process.env.AW_E2E_TOKEN
+const tokenFile = process.env.AW_SCENE_TOKEN_FILE ?? '.tmp-scene-home/admin-token.txt'
+if (!token) {
+  try {
+    token = (await import('node:fs')).readFileSync(tokenFile, 'utf8').trim() || null
+  }
+  catch { /* 无缓存 */ }
+  if (token) check('复用已缓存管理员 token', true)
+}
+if (!token) {
+  const reg = await j(ROOT, '/api/workshop/users/register', 'POST', { name: `scene-admin-${Date.now().toString(36)}` })
+  token = reg.data?.token
+  check('注册管理员(隔离实例,首注册即 admin)', !!token)
+  if (token) {
+    try {
+      ;(await import('node:fs')).mkdirSync(tokenFile.replace(/[/\\][^/\\]+$/, ''), { recursive: true })
+      ;(await import('node:fs')).writeFileSync(tokenFile, token)
+    }
+    catch { /* 缓存失败不影响本次 */ }
+  }
+}
+const H = { authorization: `Bearer ${token}` }
+const api = (u, m = 'GET', b) => j(ROOT, u, m, b, H)
+const sim = (u, m = 'GET', b) => j(SIM_API, u, m, b)
+
+try {
+  // ---- ① 配置阶段(一次性;模拟器导出 → 标准转换模式建映射) ----
+  console.log('\n--- ① 配置阶段:模拟器对接导出 → 标准转换模式一键建工艺参数映射 ---')
+  const nodes = await sim('/api/nodes')
+  const dev = (nodes.data ?? []).find(n => n.protocol === 'modbus-tcp')
+  check('发现 plc-node-simulator Modbus TCP 设备', !!dev?.id, `${dev?.id}(${dev?.name})`)
+  const exp = await sim(`/api/nodes/${dev.id}/export`)
+  const items = exp.data?.items ?? []
+  check('导出对接配置(寄存器/数据类型/字节序由模拟器给出)', items.length >= 2, items.map(i => `${i.signal}@${i.driverConfig.register}`).join(', '))
+
+  const line = (await api('/api/workshop/dcw/lines', 'POST', { name: '1号挤出线(参数映射)' })).data?.line
+  check('创建产线', !!line?.id)
+
+  // 两个工艺参数:加热区1/加热区2 温度,float32 直写标准模式,基准限界 160~190(收窄于模板量程 150~200)
+  const mkParam = async (item, key, name) => {
+    const cfg = item.driverConfig
+    const r = await api('/api/workshop/dcw/params', 'POST', {
+      key, name, templateRef: 'dcw-temp-sp', lineId: line.id,
+      min: 160, max: 190,
+      access: {
+        host: cfg.host, port: cfg.port, unitId: cfg.unitId, register: cfg.register,
+        conversion: { mode: 'float32', byteOrder: cfg.byteOrder },
+      },
+    })
+    return r.data?.param
+  }
+  const p1 = await mkParam(items[0], 'zone1_temp', '加热区1温度设定')
+  const p2 = await mkParam(items[1], 'zone2_temp', '加热区2温度设定')
+  check('工艺参数「zone1_temp」建映射成功(自动建执行节点)', !!p1?.id && !!p1.nodeId, `${p1?.id} → ${p1?.nodeId}`)
+  check('转换模式已留存(float32)', p1?.conversion?.mode === 'float32')
+  check('映射视图不含寄存器/数据类型(用户不可见)', !JSON.stringify(p1).includes('register') && !JSON.stringify(p1).includes('dataType'))
+
+  // ---- ② 运行阶段(用户只碰 key + 工程值) ----
+  console.log('\n--- ② 运行阶段:用户设定工艺参数 → 模拟器真实接收 → 参数读回 ---')
+  const list = await api('/api/workshop/dcw/params?lineId=' + line.id)
+  check('用户参数列表(2 条工艺参数)', (list.data?.params ?? []).length === 2, list.data?.params?.map(p => `${p.key}=${p.value}${p.unit}`).join(', '))
+
+  const simValueOf = async (signalName) => {
+    const ns = await sim('/api/nodes')
+    const sg = (ns.data ?? []).find(n => n.id === dev.id)?.signals?.find(s => s.name === signalName || s.id === signalName)
+    return sg?.value
+  }
+  const userSet = async (param, value) => {
+    const w = await api(`/api/workshop/dcw/params/${param.id}/write`, 'POST', { value })
+    return { ok: w.data?.outcome?.ok, msg: w.data?.outcome?.message ?? w.message }
+  }
+  const userRead = async (param) => {
+    const r = await api(`/api/workshop/dcw/params/${param.id}/read`, 'POST', {})
+    return { value: r.data?.read?.value, ok: r.data?.read?.ok, msg: r.data?.read?.message }
+  }
+  // 模拟器 SP 可能带一阶收敛,轮询直至到位
+  const waitSimValue = async (signalName, target, timeoutMs = 8000) => {
+    const t0 = Date.now()
+    for (;;) {
+      const v = await simValueOf(signalName)
+      if (v != null && Math.abs(v - target) <= 0.6) return v
+      if (Date.now() - t0 > timeoutMs) return v
+      await sleep(400)
+    }
+  }
+
+  console.log('  · 用户设定 加热区1温度 = 185℃')
+  const w1 = await userSet(p1, 185)
+  check('用户写入 185℃ 成功(含 PLC 回读确认)', w1.ok === true, w1.msg)
+  const sv1 = await waitSimValue(items[0].signal, 185)
+  check('PLC 模拟器真实收到:zone1 SP = 185', sv1 != null && Math.abs(sv1 - 185) <= 0.6, `sim.value=${sv1}`)
+  const r1 = await userRead(p1)
+  check('用户按参数读回 = 185℃(工程量纲)', r1.ok && Math.abs((r1.value ?? 0) - 185) <= 0.6, `value=${r1.value}`)
+
+  console.log('  · 用户设定 加热区2温度 = 175℃')
+  const w2 = await userSet(p2, 175)
+  check('用户写入 175℃ 成功', w2.ok === true, w2.msg)
+  const sv2 = await waitSimValue(items[1].signal, 175)
+  check('PLC 模拟器真实收到:zone2 SP = 175', sv2 != null && Math.abs(sv2 - 175) <= 0.6, `sim.value=${sv2}`)
+
+  console.log('  · 用户越界尝试 195℃...基准限界上限是 190(节点量程 150~200 之内)')
+  const w3 = await api(`/api/workshop/dcw/params/${p2.id}/write`, 'POST', { value: 195 })
+  check('越基准限界 → 400 点名参数层(用户不可越界)', (w3._status === 400 || w3.code === 'VALIDATION_ERROR') && String(w3.message).includes('基准限界'), String(w3.message).slice(0, 80))
+
+  console.log('  · 现场侧把 zone1 就地改到 172℃(模拟读方向)')
+  // 模拟器 manual 接口按信号 id 寻址(导出的 signal 字段是中文名,先换 id)
+  const simSignals = (await sim('/api/nodes')).data?.find(n => n.id === dev.id)?.signals ?? []
+  const signalIdOf = (name) => simSignals.find(s => s.name === name || s.id === name)?.id
+  await sim(`/api/nodes/${dev.id}/signals/${signalIdOf(items[0].signal)}/manual`, 'POST', { value: 172 })
+  await sleep(600)
+  const r2 = await userRead(p1)
+  check('用户参数读到现场实际值 172℃(接收方向同样自动换算)', r2.ok && Math.abs((r2.value ?? 0) - 172) <= 0.6, `value=${r2.value}`)
+
+  // ---- ③ 收尾 ----
+  console.log('\n--- ③ 收尾:模拟器复原 + 产线清理 ---')
+  for (const item of items.slice(0, 2)) {
+    await sim(`/api/nodes/${dev.id}/signals/${signalIdOf(item.signal)}/manual`, 'POST', { value: 200 })
+  }
+  const back1 = await waitSimValue(items[0].signal, 200, 5000)
+  check('模拟器信号值复原(200)', back1 != null && Math.abs(back1 - 200) <= 0.6, `sim.value=${back1}`)
+  await api(`/api/workshop/dcw/lines/${line.id}?purge=1`, 'DELETE')
+  const after = await api('/api/workshop/dcw/params')
+  check('产线 purge 后工艺参数映射清零', !(after.data?.params ?? []).some(p => [p1.id, p2.id].includes(p.id)))
+}
+catch (err) {
+  failed += 1
+  console.error('场景异常中断:', err)
+}
+
+console.log(`\n${failed === 0 ? '✅ 真实场景全部通过' : `❌ ${failed} 项失败`}`)
+process.exit(failed === 0 ? 0 : 1)

package/scripts/_loop-biax-campaign.mjs

@@ -0,0 +1,124 @@
+/**
+ * 双拉任务确定性 campaign —— R11 Major-1 的实验落地:
+ * 固定模拟器状态(plantReset warm)+ 固定 commit + 固定配方,连续执行 N=30 次
+ * AgentTeam 双拉闭环任务,记录每次入带结果,给出入带率的 Wilson 95% CI。
+ * 预注册判据:入带 = |最终厚度 − 25.0| ≤ 0.7 µm;每次写后等待 ≥12s 运输滞后。
+ * 运行: AW_BASE=http://127.0.0.1:3005 NO_PROXY=127.0.0.1,localhost node scripts/_loop-biax-campaign.mjs [N]
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
+import { join, resolve, dirname } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+const N = Number(process.argv[2] ?? 30)
+const BASE = process.env.AW_BASE ?? 'http://127.0.0.1:3005'
+const OUT = join(REPO, 'bench', 'results', 'biax-campaign')
+const SIM = process.env.E2E_SIM_API ?? 'http://127.0.0.1:4010'
+const fetchRetry = async (url, opts = {}, tries = 8) => {
+  let lastErr
+  for (let i = 1; i <= tries; i++) {
+    try { return await fetch(url, { ...opts, signal: AbortSignal.timeout(20000) }) }
+    catch (e) { lastErr = e; await new Promise(r => setTimeout(r, Math.min(500 * 2 ** (i - 1), 6000))) }
+  }
+  throw lastErr
+}
+
+mkdirSync(OUT, { recursive: true })
+
+const BS = String.fromCharCode(92)
+const sleep = (ms) => new Promise(r => setTimeout(r, ms))
+
+const login = await (await fetch(BASE + '/api/users/login', {
+  method: 'POST', headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ email: 'admin@awshop.local', password: 'admin123' }),
+})).json()
+const H = { authorization: `Bearer ${login.data.token}`, 'content-type': 'application/json' }
+const api = {
+  call: async (method, u, b) => (await fetch(BASE + u, { method, headers: H, body: b ? JSON.stringify(b) : undefined })).json(),
+}
+
+const { ensureSimulator, simUp, simNodes, simExport, plantReset } = await import(pathToFileURL(join(REPO, 'bench', 'lib', 'sim.mjs')).href)
+const { provisionBiaxLine, runBiaxMission, ensureBiaxLine } = await import(pathToFileURL(join(REPO, 'bench', 'lib', 'biax.mjs')).href)
+const { makeApi } = await import(pathToFileURL(join(REPO, 'bench', 'lib', 'util.mjs')).href)
+
+if (!(await simUp())) {
+  console.error('模拟器不可达:请先启动 plc-node-simulator (:4010)')
+  process.exit(1)
+}
+await ensureSimulator().catch(() => {})
+
+const sfx = 'camp' + Date.now().toString(36).slice(-4)
+// 平台夹具:channel + mock lead/worker(任务板剧本)+ opencode 绑定执行体
+const ch = await api.call('POST', '/api/workshop/channels', { name: `biax-campaign-${sfx}`, leadAgent: { name: `clead-${sfx}`, harness: 'mock', config: { delayMs: 40 } } })
+const channelId = ch.data?.channelId ?? ch.data?.channel?.id ?? ch.data?.id
+const worker = await api.call('POST', '/api/workshop/agents', { name: `cworker-${sfx}`, harness: 'mock', config: { delayMs: 60 } })
+await api.call('POST', `/api/workshop/channels/${channelId}/agents`, { agentId: worker.data?.id, role: 'worker' })
+const agent = await api.call('POST', '/api/workshop/agents', { name: `cexec-${sfx}`, harness: 'opencode', config: {} })
+const joinResp = await api.call('POST', `/api/workshop/channels/${channelId}/agents`, { agentId: agent.data?.id, role: 'worker' })
+const instId = joinResp.data?.id ?? joinResp.data?.agentId
+if (!instId) { console.error('执行体创建失败'); process.exit(1) }
+
+const runs = []
+const stateFile = join(OUT, 'campaign-state.json')
+const save = () => writeFileSync(stateFile, JSON.stringify({ sfx, startedAt: new Date().toISOString(), runs }, null, 1))
+
+console.log(`campaign start: N=${N} base=${BASE} sim=:4010`)
+for (let k = 1; k <= N; k++) {
+  const t0 = Date.now()
+  // ① 固定模拟器状态(确定性根修:零随机漂移 + warm 标称)
+  await plantReset({ warm: true, disturbances: { heaterDecay: 1, feedDriftPerMin: 0 } })
+  await sleep(1500)
+  // ②.5 SP 归一化:崩塌任务会把 SP 写到量程外(实测 pump-sp=0 残留),起跑前统一设回
+  // 量程内 35% 位(确定性起点;任务只写铸速/快辊/轨宽三旋钮,其余 SP 仅作配方合法值)
+  {
+    const nodes = (await simNodes()).filter(n => n.id.startsWith('biax-'))
+    for (const dev of nodes) {
+      for (const sig of dev.signals ?? []) {
+        if (!/SP/i.test(sig.id) && !/SP/i.test(sig.name ?? '')) continue
+        const lo = sig.min ?? 0, hi = sig.max ?? 100
+        const v = Number(sig.value)
+        if (!Number.isFinite(v) || v < lo + 0.05 * (hi - lo)) {
+          const target = +(lo + 0.35 * (hi - lo)).toFixed(sig.decimals ?? 1)
+          await fetchRetry(SIM + '/api/nodes/' + dev.id + '/signals/' + encodeURIComponent(sig.id) + '/manual', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ value: target }) }).catch(() => {})
+        }
+      }
+    }
+    await sleep(1200)
+  }
+
+  // ② 每轮独立布线(探测补建幂等;节点随 purge 回收)
+  const ensured = await ensureBiaxLine()
+  if (!ensured?.verified) throw new Error('ensureBiaxLine 失败')
+  const provisioned = await provisionBiaxLine(api, { sfx: sfx + k })
+  const line = provisioned
+  // ③ 绑定执行体到三个执行节点的 DCW
+  for (const nodeId of Object.values(line.dcw)) {
+    await api.call('POST', '/api/workshop/agent-tools/bindings', { agentId: instId, nodeId, kind: 'dcw', mode: 'auto' })
+  }
+  await sleep(2000)
+  // ④ 任务(含治理写与判定)
+  const mission = await runBiaxMission(api, { instId, line, simDevices: (await simNodes()).filter(n => n.id.startsWith('biax')), sfx: sfx + k, maxRounds: 6 })
+  if (k === 1 || !mission.attained) console.log('DIAG provErrors:', JSON.stringify(provisioned.errors ?? []), '| dcw:', Object.keys(line.dcw ?? {}).length, '| daq:', Object.keys(line.daq ?? {}).length, '| ids:', JSON.stringify(line.ids ?? {}))
+  const run = {
+    k, attained: mission.attained, thickness: mission.thickness,
+    writes: mission.writes, knobs: mission.distinctNodes.size, wallS: Math.round((Date.now() - t0) / 1000),
+  }
+  runs.push(run)
+  save()
+  console.log(`[${k}/${N}] attained=${run.attained} h=${run.thickness?.toFixed(2)}µm writes=${run.writes} wall=${run.wallS}s`)
+  // ⑤ 收尾:停线防批次泄漏
+  await api.call('POST', `/api/workshop/dcw/lines/${line.ids.line}/stop`, {}).catch(() => {})
+  await api.call('DELETE', `/api/workshop/dcw/lines/${line.ids.line}?purge=1`, {}).catch(() => {})
+  await sleep(2000)
+}
+
+const ok = runs.filter(r => r.attained).length
+const n = runs.length
+const p = ok / n
+const z = 1.96
+const ci = n ? [p - z * Math.sqrt((p * (1 - p)) / n), p + z * Math.sqrt((p * (1 - p)) / n)] : [0, 0]
+const summary = { n, ok, rate: +p.toFixed(3), wilson95: ci.map(c => +c.toFixed(3)), runs }
+writeFileSync(join(OUT, 'campaign-summary.json'), JSON.stringify(summary, null, 1))
+console.log(`\n结果: ${ok}/${n} 入带,rate=${(p * 100).toFixed(1)}%,Wilson95=[${ci[0].toFixed(3)},${ci[1].toFixed(3)}]`)
+console.log(`产物: ${OUT}`)

package/scripts/api-live-e2e.mjs

@@ -19,6 +19,24 @@
 const BASE = process.env.AW_BASE ?? 'http://127.0.0.1:3001'
 const WS_BASE = BASE.replace(/^http/, 'ws')
 
+// 网络层瞬断（本机代理 churn 间歇占满回环临时端口 → fetch failed/EADDRINUSE）
+// 用退避重试吸收；HTTP 语义错误不重试。与 bench/lib 侧瞬断策略一致。
+const rawFetch = globalThis.fetch.bind(globalThis)
+globalThis.fetch = async (input, init = {}) => {
+  let lastErr
+  for (let attempt = 1; attempt <= 8; attempt++) {
+    try {
+      return await rawFetch(input, { ...init, signal: init.signal ?? AbortSignal.timeout(30_000) })
+    }
+    catch (err) {
+      lastErr = err
+      if (init.signal?.aborted) throw err
+      if (attempt < 8) await new Promise(r => setTimeout(r, Math.min(800 * 2 ** (attempt - 1), 8000)))
+    }
+  }
+  throw lastErr
+}
+
 let failures = 0
 let passed = 0
 let step = 0
@@ -109,20 +127,34 @@ async function main() {
   const ch0 = await api('GET', '/api/workshop/channels')
   check('GET /channels 恢复 channel 列表', ch0.code === 0 && Array.isArray(ch0.data), `count=${ch0.data?.length}`)
   const persisted = (ch0.data ?? []).filter(c => c.leadAgentId)
-  check('恢复的 channel 带 lead 实例', persisted.length >= 1, `with-lead=${persisted.length}`)
+  // 该子检查依赖「上一轮遗留的 channel-with-lead」。首次运行/上轮已清理时按项目
+  // 失败语义诚实 skip(bench/PIPELINE.md:环境不具备宁可 skip 并写明原因,绝不伪造通过),
+  // 不计入 fail,也不得因缺前置数据而崩溃。
+  const hasPersisted = persisted.length >= 1
+  if (hasPersisted) {
+    check('恢复的 channel 带 lead 实例', true, `with-lead=${persisted.length}`)
+  }
+  else {
+    console.log('  SKIP  恢复的 channel 带 lead 实例 — 实例无历史 channel-with-lead(首次运行或上轮已清理);跨重启持久化由独立重启演练覆盖')
+  }
 
   const rt0 = await api('GET', '/api/workshop/runtime')
   check('GET /runtime 形状(懒加载状态)', rt0.code === 0 && Array.isArray(rt0.data?.wiredAgents) && Array.isArray(rt0.data?.activeChannels), `wired=${rt0.data?.wiredAgents?.length} active=${rt0.data?.activeChannels?.length}`)
   const rt0Wired = rt0.data?.wiredAgents?.length ?? 0
 
   // 详情请求触发 ensureChannelActive(懒加载恢复)
-  const probeId = persisted[0].id
-  const probe = await api('GET', `/api/workshop/channels/${probeId}`)
-  check('GET /channels/:id 详情(含成员)', probe.code === 0 && Array.isArray(probe.data?.agents) && probe.data.agents.length > 0, `agents=${probe.data?.agents?.length}`)
-  const rt1 = await api('GET', '/api/workshop/runtime')
-  check('详情请求后 lead 运行时装配(懒加载)', rt1.code === 0 && (rt1.data?.wiredAgents?.length ?? 0) >= rt0Wired, `wired=${rt1.data?.wiredAgents?.length} active=${rt1.data?.activeChannels?.length}`)
-  const persistedTasks = await api('GET', `/api/workshop/channels/${probeId}/tasks`)
-  check('GET /channels/:id/tasks 恢复历史任务', persistedTasks.code === 0, `tasks=${persistedTasks.data?.length}`)
+  const probeId = hasPersisted ? persisted[0].id : null
+  if (probeId) {
+    const probe = await api('GET', `/api/workshop/channels/${probeId}`)
+    check('GET /channels/:id 详情(含成员)', probe.code === 0 && Array.isArray(probe.data?.agents) && probe.data.agents.length > 0, `agents=${probe.data?.agents?.length}`)
+    const rt1 = await api('GET', '/api/workshop/runtime')
+    check('详情请求后 lead 运行时装配(懒加载)', rt1.code === 0 && (rt1.data?.wiredAgents?.length ?? 0) >= rt0Wired, `wired=${rt1.data?.wiredAgents?.length} active=${rt1.data?.activeChannels?.length}`)
+    const persistedTasks = await api('GET', `/api/workshop/channels/${probeId}/tasks`)
+    check('GET /channels/:id/tasks 恢复历史任务', persistedTasks.code === 0, `tasks=${persistedTasks.data?.length}`)
+  }
+  else {
+    console.log('  SKIP  详情/懒加载装配/历史任务 — 无持久化 channel 可探')
+  }
 
   // ═══════════ 2. AGENT 模板 CRUD ═══════════
   section('AGENT 模板 CRUD(全局定义)')

package/scripts/capture-walkthrough.mjs

@@ -0,0 +1,232 @@
+/**
+ * Canonical walkthrough-figure capture. High-DPI (3x), element/row-accurate crops
+ * of the four operational stages on a live AgentWorkShop instance.
+ *
+ * The shared production instance carries Chinese-named test data, so the four
+ * screenshots are taken against the small ENGLISH fixture created by
+ * scripts/seed-walkthrough-fixture.mjs (line "Cast-film line A", English DAQ
+ * nodes, an English agent team). The UI is forced to the `en` locale (persisted
+ * in localStorage under `aw.locale`, applied by app/plugins/locale-restore.client.ts)
+ * before any capture, so every UI string is English.
+ *
+ * Geometry discipline: every crop is ≤470 CSS px wide (12 px UI text must print
+ * ≥ ~6.4 pt at the ~88 mm panel width of the 181 mm figure), except panel 2 whose
+ * four table columns cannot fit narrower.
+ *
+ * Usage:
+ *   NO_PROXY='127.0.0.1,localhost' node scripts/seed-walkthrough-fixture.mjs
+ *   NO_PROXY='127.0.0.1,localhost' AW_BASE=http://127.0.0.1:3005 node scripts/capture-walkthrough.mjs
+ */
+import puppeteer from 'puppeteer-core'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const BASE = process.env.AW_BASE ?? 'http://127.0.0.1:3005'
+const OUT = process.env.AW_OUT ?? 'paper/tii/figures/walkthrough'
+fs.mkdirSync(OUT, { recursive: true })
+
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+const tok = async (e, p) => {
+  const r = await (await fetch(`${BASE}/api/users/login`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ email: e, password: p }) })).json()
+  if (!r.data?.token) throw new Error(`login failed: ${e} (${JSON.stringify(r).slice(0, 120)})`)
+  return r.data.token
+}
+const ADMIN = await tok('admin@awshop.local', 'admin123')
+
+const jget = async (u) => {
+  const r = await (await fetch(`${BASE}${u}`, { headers: { Authorization: `Bearer ${ADMIN}` } })).json()
+  return r.data
+}
+
+// ── fixture discovery (fail loudly rather than silently capturing Chinese) ──
+const LINES = (await jget('/api/workshop/dcw/lines')).lines
+const LINE = LINES.find(l => l.name === 'Cast-film line A')
+if (!LINE) throw new Error('English fixture line "Cast-film line A" missing — run scripts/seed-walkthrough-fixture.mjs first')
+const DAQ = await jget('/api/workshop/daq')
+const modbusNode = DAQ.nodes.find(n => n.lineId === LINE.id && n.driver === 'modbus-tcp')
+if (!modbusNode) throw new Error('fixture Modbus-TCP node missing on Cast-film line A')
+// panel 4 uses the real judged optimization records already on the ledger of this node
+const RECORD_LINE = 'ln-af002514'
+const RECORD_NODE = 'dw-322b1978'
+console.log(`fixture line=${LINE.id}  modbus=${modbusNode.id} (${modbusNode.name})  records=${RECORD_NODE}`)
+
+const browser = await puppeteer.launch({
+  executablePath: process.env.AW_CHROME ?? 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+  headless: 'new',
+  args: ['--no-sandbox', '--disable-gpu', '--proxy-server=direct://', '--proxy-bypass-list=*'],
+})
+const page = await browser.newPage()
+const errs = []
+page.on('pageerror', e => errs.push(String(e).slice(0, 120)))
+await page.setViewport({ width: 1680, height: 1600, deviceScaleFactor: 3 })
+
+const auth = async (t) => { const c = await page.target().createCDPSession(); await c.send('Network.clearBrowserCookies'); await page.setCookie({ name: 'token', value: t, domain: '127.0.0.1', path: '/' }) }
+const goto = async (u, w = 10000) => { await page.goto(`${BASE}${u}`, { waitUntil: 'domcontentloaded', timeout: 90_000 }); await sleep(w) }
+
+// content-visibility:auto sections report estimated rects until rendered; force real
+// layout so element-accurate clips do not drift. Also kill CSS transitions/animations
+// so a mid-transition frame (e.g. the hold-interval cell double-painting its value)
+// can never be captured.
+const settle = async () => {
+  await page.evaluate(() => {
+    let st = document.getElementById('aw-capture-calm')
+    if (!st) {
+      st = document.createElement('style')
+      st.id = 'aw-capture-calm'
+      st.textContent = '*,*::before,*::after{transition:none!important;transition-duration:0s!important;animation:none!important;animation-duration:0s!important;animation-delay:0s!important}'
+      document.head.appendChild(st)
+    }
+    for (const e of document.querySelectorAll('*')) {
+      const cs = getComputedStyle(e)
+      if (cs.contentVisibility && cs.contentVisibility !== 'visible') e.style.contentVisibility = 'visible'
+    }
+    window.scrollTo(0, document.body.scrollHeight)
+  })
+  await sleep(700)
+  await page.evaluate(() => window.scrollTo(0, 0))
+  await sleep(300)
+}
+
+// Grow the viewport to the full document height BEFORE measuring, so that the
+// screenshot's captureBeyondViewport expansion cannot re-layout the page and
+// shift elements between measurement and capture.
+const expand = async () => {
+  const h = await page.evaluate(() => document.documentElement.scrollHeight)
+  await page.setViewport({ width: 1680, height: Math.min(Math.ceil(h) + 40, 14000), deviceScaleFactor: 3 })
+  await sleep(1200)
+  await settle()
+}
+
+const repaint = async () => {
+  await page.evaluate(() => new Promise(res => {
+    window.scrollTo(0, 0)
+    requestAnimationFrame(() => requestAnimationFrame(res))
+  }))
+  await sleep(120)
+}
+
+// Capture only once the pixels stop changing: two consecutive identical captures are
+// required (guards against mid-transition / late-commit frames like double-struck text).
+const shot = async (n, x, y, w, h, tries = 5) => {
+  const clip = { x, y, width: w, height: h }
+  let prev = null
+  let stable = false
+  for (let i = 0; i < tries; i++) {
+    await repaint()
+    const buf = Buffer.from(await page.screenshot({ encoding: 'binary', clip, captureBeyondViewport: true }))
+    if (prev && Buffer.compare(prev, buf) === 0) { prev = buf; stable = true; break }
+    prev = buf
+    await sleep(1000)
+  }
+  fs.writeFileSync(path.join(OUT, n), prev)
+  console.log(`  ✓ ${n}  ${Math.round(w)}x${Math.round(h)} css @3x  ${stable ? 'stable' : 'NOT STABLE (last frame written)'}`)
+}
+
+// ── force English UI before any capture ──────────────────────────────────
+await auth(ADMIN)
+await goto('/daq', 4000)
+await page.evaluate(() => localStorage.setItem('aw.locale', 'en'))
+await page.reload({ waitUntil: 'domcontentloaded' })
+await sleep(6000)
+const heads = await page.evaluate(() => [...document.querySelectorAll('.nodes-table thead th')].map(t => t.textContent.trim()))
+if (!heads.some(h => /Sampling/i.test(h))) throw new Error(`locale not English (headers: ${JSON.stringify(heads)})`)
+console.log(`locale  : en (headers: ${heads.join(' | ')})`)
+
+// ══ ① provision & connect — /daq nodes filtered to the English line ══════
+console.log('\n== ① /daq ==')
+await page.evaluate((ln) => {
+  for (const s of document.querySelectorAll('select')) {
+    if ([...s.options].some(o => o.value === ln)) { s.value = ln; s.dispatchEvent(new Event('change', { bubbles: true })); break }
+  }
+}, LINE.id)
+await sleep(3500)
+await settle()
+await expand()
+
+const G = await page.evaluate(() => {
+  const tbl = document.querySelector('.nodes-table')
+  const rect = tbl.getBoundingClientRect()
+  const ths = [...tbl.querySelectorAll('thead th')].map(t => ({ x: Math.round(t.getBoundingClientRect().x - rect.x), text: t.textContent.trim() }))
+  const rows = [...tbl.querySelectorAll('tbody tr')].map((tr) => {
+    const q = tr.getBoundingClientRect()
+    const tds = tr.querySelectorAll('td')
+    return { y: Math.round(q.y + window.scrollY), h: q.height, name: (tr.querySelector('b')?.textContent || '').trim(), driver: (tds[6]?.textContent || '').trim() }
+  })
+  return { x: rect.x, ths, rows }
+})
+console.log('  rows:', G.rows.map(r => `${r.name}[${r.driver}]`).join(', '))
+if (!G.rows.some(r => r.driver.includes('modbus'))) throw new Error('no Modbus-TCP row visible on filtered line')
+// columns: 4 Sampling · 5 WS Publish · 6 Driver · 7 Line (indices are locale-stable).
+// Keep the crop ≤470 css px: 12 px UI text must print ≥ ~6.4 pt at the 88 mm panel width.
+const mbIdx = G.rows.findIndex(r => r.driver.includes('modbus'))
+const mkIdx = mbIdx > 0 ? mbIdx - 1 : 0
+const x0 = G.x + G.ths[4].x
+const x1 = G.x + G.ths[8].x
+const yS = G.rows[mkIdx].y
+const yE = G.rows[mbIdx].y + G.rows[mbIdx].h
+console.log(`  pair: ${G.rows[mkIdx].name}[${G.rows[mkIdx].driver}] + ${G.rows[mbIdx].name}[${G.rows[mbIdx].driver}]`)
+await shot('p1-driver.png', x0 - 2, yS, Math.min(x1 - x0 + 4, 470), yE - yS)
+
+// ══ ② bind node → line / device — /dcw/{English line} ═══════════════════
+console.log('\n== ② /dcw/' + LINE.id + ' ==')
+await goto(`/dcw/${LINE.id}`, 9000)
+await settle()
+await expand()
+const D = await page.evaluate(() => {
+  const t = document.querySelector('.aw-tile.table-card table')
+  const rect = t.getBoundingClientRect()
+  const ths = [...t.querySelectorAll('thead th')].map(x => ({ x: Math.round(x.getBoundingClientRect().x - rect.x), text: x.textContent.trim() }))
+  return { x: rect.x, y: rect.y + window.scrollY, h: rect.height, ths }
+})
+console.log('  cols:', D.ths.map(c => c.text).join(' | '))
+// columns: 5 Setpoint · 6 Process Range · 7 Hold Interval · 8 Bound Device
+const c0 = D.x + D.ths[5].x
+const c1 = D.x + D.ths[9].x
+await shot('p2-binding.png', c0 - 6, D.y, (c1 - c0) + 12, D.h)
+
+// ══ ④ governed closed loop — ledger optimization records (real, judged) ══
+console.log('\n== ④ /dcw/' + RECORD_LINE + ' ledger ==')
+await goto(`/dcw/${RECORD_LINE}`, 9000)
+await page.evaluate((nid) => {
+  const s = document.querySelector('.ledger-card select.inp')
+  if (!s) return
+  s.value = nid
+  s.dispatchEvent(new Event('change', { bubbles: true }))
+}, RECORD_NODE)
+await sleep(3500)
+await settle()
+await expand()
+const L = await page.evaluate(() => {
+  const card = document.querySelector('.ledger-card')
+  const col = [...card.querySelectorAll('.ledger-col')].find(c => c.querySelector('li.ledger-rec')) || [...card.querySelectorAll('.ledger-col')].pop()
+  const recs = [...col.querySelectorAll('li.ledger-rec')]
+  const r = col.getBoundingClientRect()
+  const last = recs[recs.length - 1].getBoundingClientRect()
+  return { x: r.x, y: r.y + window.scrollY, w: r.width, h: last.bottom - r.top, texts: recs.map(li => li.textContent.replace(/\s+/g, ' ').trim()) }
+})
+console.log('  records:', JSON.stringify(L.texts))
+// tight: header + the real records, without the empty box below them
+await shot('p4-records.png', L.x - 5, L.y - 5, Math.min(L.w + 14, 470), L.h + 14)
+
+// ══ ③ compose & deploy the agent team — /workshop/teams ═════════════════
+// Desktop viewport: one card in the multi-column grid (~343 px wide), which keeps the
+// crop ≤470 css px so member text prints ≥ ~6 pt at the 88 mm panel width.
+console.log('\n== ③ /workshop/teams ==')
+await page.setViewport({ width: 1680, height: 1600, deviceScaleFactor: 3 })
+await goto('/workshop/teams', 9000)
+await settle()
+await expand()
+const cards = await page.evaluate(() => [...document.querySelectorAll('.grid .card')].map(e => {
+  const r = e.getBoundingClientRect()
+  const members = e.querySelectorAll('.member')
+  const last = members[members.length - 1]?.getBoundingClientRect()
+  return { x: Math.round(r.x), y: Math.round(r.y + window.scrollY), w: Math.round(r.width), h: Math.round(r.height), memberH: last ? Math.round(last.bottom - r.top) : Math.round(r.height), t: e.textContent.replace(/\s+/g, ' ').slice(0, 40) }
+}))
+console.log('  cards:', JSON.stringify(cards))
+const tgt = cards.find(c => c.t.includes('Cast-film control team'))
+if (!tgt) throw new Error('English team card not found on /workshop/teams')
+// crop head + member rows only (excludes the Add-Member button) to keep the figure compact
+await shot('p3-team.png', tgt.x - 5, tgt.y - 5, Math.min(tgt.w + 10, 470), tgt.memberH + 8)
+
+console.log('\npageerrors:', errs.length ? errs.join(' | ') : 'none')
+await browser.close()

package/scripts/render-walkthrough-figure.mjs

@@ -0,0 +1,46 @@
+/**
+ * Render the walkthrough figure HTML to (a) an exact-size PDF via headless Chrome
+ * --print-to-pdf and (b) a high-resolution PNG for inspection/archival.
+ *
+ * Usage: node scripts/render-walkthrough-figure.mjs
+ */
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import puppeteer from 'puppeteer-core'
+
+const CHROME = process.env.AW_CHROME ?? 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
+const DIR = path.resolve('paper/tii/figures/walkthrough')
+const SRC = path.join(DIR, 'fig-walkthrough.html')
+if (!fs.existsSync(SRC)) throw new Error('missing ' + SRC)
+
+// ── (a) exact-size PDF ────────────────────────────────────────────────────
+const pdfUrl = 'file:///' + SRC.replace(/\\/g, '/')
+const outPdf = path.resolve('paper/tii/figures/pdf/fig-walkthrough.pdf')
+fs.mkdirSync(path.dirname(outPdf), { recursive: true })
+execFileSync(CHROME, [
+  '--headless=new', '--disable-gpu', '--no-pdf-header-footer',
+  `--print-to-pdf=${outPdf}`, pdfUrl,
+], { stdio: 'ignore' })
+const info = execFileSync('pdfinfo', [outPdf], { encoding: 'utf8' })
+console.log('PDF  :', outPdf)
+console.log('     ', info.split('\n').filter(l => /Page size|Pages/.test(l)).join(' | ').trim())
+
+// ── (b) high-resolution PNG (overall + per-panel) ─────────────────────────
+const browser = await puppeteer.launch({ executablePath: CHROME, headless: 'new', args: ['--no-sandbox', '--disable-gpu', '--allow-file-access-from-files'] })
+const page = await browser.newPage()
+// 181 mm wide at 96 dpi/css == 684 css px; height is a minimum — fullPage grows to content
+await page.setViewport({ width: 684, height: 200, deviceScaleFactor: 8 })
+await page.goto(pdfUrl, { waitUntil: 'networkidle0' })
+await page.evaluate(() => document.fonts?.ready)
+await new Promise(r => setTimeout(r, 500))
+await page.screenshot({ path: path.join(DIR, 'fig-walkthrough.png'), fullPage: true })
+const png = fs.statSync(path.join(DIR, 'fig-walkthrough.png'))
+console.log('PNG  :', path.join(DIR, 'fig-walkthrough.png'), `${(png.size / 1024).toFixed(0)} KB`)
+
+// medium-res variant for quick review
+await page.setViewport({ width: 684, height: 200, deviceScaleFactor: 2 })
+await page.screenshot({ path: path.join(DIR, '_preview.png'), fullPage: true })
+console.log('PREV :', path.join(DIR, '_preview.png'))
+
+await browser.close()