agentworkshop 0.2.1

package/scripts/test-task-invariants.mjs

@@ -0,0 +1,169 @@
+// -*- coding: utf-8 -*-
+// 任务管理不变量 E2E(node scripts/test-task-invariants.mjs)
+//
+// 实证三条核心不变量(单 worker 串行 + 事件流精确重建):
+//  I1 单 WORKING:任意时刻同一 agent 至多 1 个 WORKING 任务(事件区间重叠检测)
+//  I2 FIFO:ASSIGNED 任务按创建顺序依次进入 WORKING
+//  I3 状态链:每个任务完整走 ASSIGNED → WORKING → COMPLETED,无跳步、无回退
+//  I4 前端同步:agent.status 的 currentTaskId 与唯一 WORKING 任务始终一致(busy 期间)
+import { env } from 'node:process'
+
+const BASE = env.AW_BASE ?? 'http://127.0.0.1:3002'
+const TOKEN = env.AW_TOKEN ?? 'ut-636e563104b844b591de8aadf6071aea'
+
+let failures = 0
+const check = (name, ok, detail = '') => {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (!ok) failures += 1
+}
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+async function api(method, path, body) {
+  const res = await fetch(BASE + path, {
+    method,
+    headers: { 'authorization': `Bearer ${TOKEN}`, 'content-type': 'application/json' },
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  const d = await res.json().catch(() => ({}))
+  if (d?.code !== undefined && d.code !== 0 && d.code !== 'ok') {
+    throw new Error(`${method} ${path} -> ${JSON.stringify(d).slice(0, 200)}`)
+  }
+  return d?.data ?? d
+}
+
+async function main() {
+  const stamp = Date.now().toString(36)
+  const created = await api('POST', '/api/workshop/channels', {
+    name: `invariant-e2e-${stamp}`,
+    description: '任务不变量 E2E(自动清理)',
+    leadAgent: { name: 'inv-lead', harness: 'mock', config: { delayMs: 60 } },
+  })
+  const cid = created.channelId
+  try {
+    const w = await api('POST', `/api/workshop/channels/${cid}/agents`, { name: 'inv-worker', harness: 'mock', config: { delayMs: 260 } })
+    const wid = w.id
+    console.log(`channel=${cid.slice(0, 8)} worker=${wid.slice(0, 8)}`)
+
+    // ===== 顺序提交 6 个任务(确定性 FIFO 创建序) =====
+    const N = 6
+    const tasks = []
+    for (let i = 1; i <= N; i++) {
+      const t = await api('POST', `/api/workshop/channels/${cid}/tasks`, {
+        title: `INV-${String(i).padStart(2, '0')}`,
+        description: `不变量验证任务 ${i}`,
+        assigneeId: wid,
+        parts: [{ text: `INV-${i}` }],
+      })
+      tasks.push(t)
+    }
+    console.log(`已顺序提交 ${N} 个任务(单 worker,delayMs=260 → 每任务约 1s,全程 ~7s)`)
+
+    // ===== 全程轮询采样:任意时刻 WORKING 数(REST 快照) =====
+    const samples = []
+    const t0 = Date.now()
+    while (Date.now() - t0 < 40_000) {
+      const list = await api('GET', `/api/workshop/channels/${cid}/tasks`).catch(() => null)
+      if (list) {
+        const working = list.filter(t => t.state === 'WORKING')
+        samples.push({ at: Date.now(), workingCount: working.length, workingIds: working.map(t => t.id) })
+        if (list.every(t => ['COMPLETED', 'FAILED', 'CANCELED'].includes(t.state)) && list.length >= N) break
+      }
+      await sleep(200)
+    }
+    const maxWorking = Math.max(0, ...samples.map(s => s.workingCount))
+    check(`I1 单 WORKING(全程采样 ${samples.length} 次,峰值 ${maxWorking})`, maxWorking <= 1)
+    const executed = samples.filter(s => s.workingCount === 1).length
+    check('I1b 执行期间确实处于 WORKING 态(采样非全 0)', executed > 0, `${executed} 次采样有 1 个 WORKING`)
+
+    // ===== 事件流精确重建:状态路径 + WORKING 区间重叠 + currentTaskId 一致性 =====
+    const evs = (await api('GET', `/api/workshop/channels/${cid}/events?limit=500`)).items ?? []
+    const seq = evs.map(e => e.seq)
+    check('事件流 seq 严格递增', seq.every((s, i) => i === 0 || s > seq[i - 1]))
+    const taskEvs = evs
+      .filter(e => e.type === 'task.status')
+      .map(e => ({ seq: e.seq, taskId: e.payload?.taskId, state: e.payload?.state, assigneeId: e.payload?.assigneeId }))
+      .filter(x => tasks.some(t => t.id === x.taskId))
+    const agentEvs = evs
+      .filter(e => e.type === 'agent.status' && e.agentId === wid)
+      .map(e => ({ seq: e.seq, state: e.payload?.state, currentTaskId: e.payload?.currentTaskId ?? null }))
+
+    // I3:每任务状态路径 = [ASSIGNED, WORKING, COMPLETED](容许 SUBMITTED 首帧)
+    const pathOf = new Map()
+    for (const x of taskEvs) {
+      const arr = pathOf.get(x.taskId) ?? []
+      if (arr[arr.length - 1] !== x.state) arr.push(x.state)
+      pathOf.set(x.taskId, arr)
+    }
+    const expectOrder = tasks.map(t => t.id)
+    let pathsOk = true
+    const workingStartSeq = new Map()
+    const workingEndSeq = new Map()
+    for (const t of tasks) {
+      const path = pathOf.get(t.id) ?? []
+      const core = path.filter(s => s !== 'SUBMITTED')
+      if (core.join(',') !== 'ASSIGNED,WORKING,COMPLETED') {
+        pathsOk = false
+        console.log(`   任务 ${t.title} 路径异常: ${path.join(' → ')}`)
+      }
+      const wSeq = taskEvs.find(x => x.taskId === t.id && x.state === 'WORKING')?.seq
+      const cSeq = taskEvs.find(x => x.taskId === t.id && x.state === 'COMPLETED')?.seq
+      if (wSeq) workingStartSeq.set(t.id, wSeq)
+      if (cSeq) workingEndSeq.set(t.id, cSeq)
+    }
+    check(`I3 每任务状态链 ASSIGNED→WORKING→COMPLETED(${N}/${pathOf.size} 有事件)`, pathsOk && pathOf.size === N)
+
+    // I2:WORKING 开始的 seq 顺序 === 创建顺序
+    const startOrder = expectOrder
+      .filter(id => workingStartSeq.has(id))
+      .sort((a, b) => workingStartSeq.get(a) - workingStartSeq.get(b))
+    check('I2 FIFO:进入 WORKING 的顺序 === 任务创建顺序', startOrder.join(',') === expectOrder.join(','),
+      startOrder.map(id => tasks.find(t => t.id === id)?.title).join(' → '))
+
+    // I1(事件级):WORKING 区间互不重叠
+    let overlap = false
+    const intervals = expectOrder
+      .filter(id => workingStartSeq.has(id) && workingEndSeq.has(id))
+      .map(id => [workingStartSeq.get(id), workingEndSeq.get(id), id])
+    for (let i = 1; i < intervals.length; i++) {
+      const cur = intervals[i]
+      const prev = intervals[i - 1]
+      if (cur && prev && cur[0] <= prev[1]) overlap = true
+      if (overlap) break
+    }
+    check('I1(事件级)WORKING 区间零重叠', !overlap, `${intervals.length} 个区间`)
+
+    // I4:busy 期间 currentTaskId === 当前唯一 WORKING 任务
+    // 重建每 seq 时刻的 working 任务(区间内)并与最近 agent.status 对齐
+    const workingAt = s => intervals.find(([a, b]) => s >= a && s <= b)?.[2] ?? null
+    let mismatch = 0
+    let checked = 0
+    for (const a of agentEvs) {
+      if (a.state !== 'busy') continue
+      const cur = workingAt(a.seq)
+      checked += 1
+      if (cur && a.currentTaskId && a.currentTaskId !== cur) mismatch += 1
+    }
+    check('I4 busy 期间 currentTaskId 与唯一 WORKING 任务一致', mismatch === 0, `检查 ${checked} 帧,失配 ${mismatch}`)
+
+    // 终态收口
+    const final = await api('GET', `/api/workshop/channels/${cid}/tasks`)
+    check('全部任务 COMPLETED', final.filter(t => tasks.some(x => x.id === t.id)).every(t => t.state === 'COMPLETED'),
+      `${final.filter(t => t.state === 'COMPLETED').length}/${N}`)
+  }
+  finally {
+    try {
+      await api('DELETE', `/api/workshop/channels/${cid}`)
+      console.log(`\n(测试 channel ${cid.slice(0, 8)} 已删除)`)
+    }
+    catch (err) {
+      console.log(`\n(清理失败:${err.message})`)
+    }
+  }
+  console.log(`\n${failures === 0 ? 'ALL PASS' : `${failures} FAILURE(S)`}`)
+  process.exit(failures === 0 ? 0 : 1)
+}
+
+main().catch((err) => {
+  console.error('E2E 异常:', err.message)
+  process.exit(1)
+})

package/scripts/test-terminal-e2e.mjs

@@ -0,0 +1,264 @@
+/**
+ * 终端功能全栈 e2e(两阶段,针对 .output 生产构建;AW_BASE 指向目标服务)。
+ *
+ * Phase A — mock 环境(功能集成回归):
+ *  A1. mock channel(lead+worker)任务生命周期跑通至 COMPLETED
+ *  A2. GET /channels/:id/terminals → 空数组(mock 无 omp 进程,无终端镜像)
+ *  A3. WS 以 mock agent 的 agentId 连接 → NO_SESSION 优雅拒绝
+ *  A4. /api/system/monitor:mock agent process=null(in-proc),无 omp 进程行
+ *
+ * Phase B — omp 环境(简单任务全链路,rpc-ui HITL):
+ *  B1. WS 鉴权负例(无 token → USER_UNAUTHORIZED;不存在 pid → NO_SESSION)
+ *  B2. omp lead channel + 任务 → 进程 spawn;monitor 进程行 terminal:true
+ *  B3. terminals 端点返回该成员会话(agentId 寻址数据源)
+ *  B4. WS agentId 连接:term.init(meta 归属)+ 帧流回放(会话事件)
+ *  B5. 空闲注入(follow_up)→ __human_input 广播 + omp 受理
+ *  B6. 诱导 ask → extension_ui_request 实时帧 → ui_response 应答 →
+ *      ask 工具收到 "User selected"(tool_execution_end 可见)
+ *  B7. 应答后任务完成(COMPLETED)
+ *  B8. 清理:终止进程 + 删除 channel
+ *
+ * 运行:node scripts/test-terminal-e2e.mjs(默认 http://127.0.0.1:3101;需 omp CLI)
+ */
+const BASE = process.env.AW_BASE ?? 'http://127.0.0.1:3101'
+const WS_BASE = BASE.replace(/^http/, 'ws')
+
+let failures = 0
+let passed = 0
+function check(name, ok, detail = '') {
+  const tag = ok ? 'PASS' : 'FAIL'
+  console.log(`  ${tag}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (ok) passed += 1
+  else failures += 1
+}
+function section(title) {
+  console.log(`\n━━━ ${title} ━━━`)
+}
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+async function waitUntil(name, cond, timeoutMs = 240_000, intervalMs = 500) {
+  const deadline = Date.now() + timeoutMs
+  let last = null
+  while (Date.now() < deadline) {
+    try {
+      last = await cond()
+      if (last) return last
+    }
+    catch (e) { last = e }
+    await sleep(intervalMs)
+  }
+  throw new Error(`waitUntil timeout: ${name} (last=${String(last).slice(0, 160)})`)
+}
+
+/** 终端 WS 客户端:收集消息;frames() 聚合全部帧;send() 上行 */
+function openTerminalWs(query) {
+  const messages = []
+  const ws = new WebSocket(`${WS_BASE}/api/system/monitor/terminal/ws?${query}`)
+  ws.addEventListener('message', (ev) => {
+    try {
+      messages.push(JSON.parse(ev.data))
+    }
+    catch { /* ignore */ }
+  })
+  const waitClose = () => new Promise((resolve) => {
+    if (ws.readyState === WebSocket.CLOSED) return resolve(true)
+    ws.addEventListener('close', () => resolve(true))
+    setTimeout(() => resolve(false), 8000)
+  })
+  return {
+    ws,
+    messages,
+    waitClose,
+    frames: () => messages.filter(m => m.type === 'term.frames').flatMap(m => m.frames),
+    send: obj => ws.send(JSON.stringify(obj)),
+  }
+}
+
+const api = async (method, path, { body, token } = {}) => {
+  const headers = { 'content-type': 'application/json' }
+  if (token) headers.authorization = `Bearer ${token}`
+  const res = await fetch(`${BASE}${path}`, { method, headers, body: body !== undefined ? JSON.stringify(body) : undefined })
+  return { status: res.status, ...(await res.json().catch(() => ({}))) }
+}
+
+async function registerUser(label) {
+  const user = await api('POST', '/api/users/register', {
+    body: { email: `${label}-${Date.now().toString(36)}@test.local`, password: 'Passw0rd!123', name: label },
+  })
+  const token = user.data?.token
+  if (!token) throw new Error(`用户注册失败: ${JSON.stringify(user).slice(0, 160)}`)
+  return token
+}
+
+async function createChannel(token, name, leadHarness) {
+  const ch = await api('POST', '/api/workshop/channels', {
+    body: { name, description: 'terminal e2e', leadAgent: { name: `${name}-lead`, harness: leadHarness } },
+    token,
+  })
+  if (ch.code !== 0 || !ch.data?.channelId) throw new Error(`channel 创建失败: ${JSON.stringify(ch).slice(0, 160)}`)
+  return { channelId: ch.data.channelId, leadAgentId: ch.data.leadAgentId }
+}
+
+async function taskState(token, channelId, taskId) {
+  const tasks = await api('GET', `/api/workshop/channels/${channelId}/tasks`, { token })
+  return (tasks.data ?? []).find(t => t.id === taskId)?.state ?? null
+}
+
+// ═══════════════════ Phase A:mock 环境 ═══════════════════
+
+async function phaseMock() {
+  section('Phase A — mock 环境(功能集成回归)')
+  const token = await registerUser('term-e2e-mock')
+  check('A0 用户注册 + token', true)
+
+  // A1:mock channel 任务生命周期
+  const { channelId, leadAgentId } = await createChannel(token, `mock-e2e-${Date.now().toString(36)}`, 'mock')
+  check('A1 创建 mock lead channel', true, `channel=${channelId.slice(0, 8)}`)
+  const w = await api('POST', `/api/workshop/channels/${channelId}/agents`, { body: { name: 'mock-worker', harness: 'mock', role: 'worker' }, token })
+  check('A1 添加 mock worker', w.code === 0)
+  const workerId = w.data?.id ?? null
+
+  const task = await api('POST', `/api/workshop/channels/${channelId}/tasks`, {
+    body: { title: 'mock-lifecycle', description: 'mock 任务生命周期验证' },
+    token,
+  })
+  const taskId = task.data?.id
+  const finalState = await waitUntil('mock 任务终态', () => taskState(token, channelId, taskId).then(s => (s === 'COMPLETED' || s === 'FAILED' ? s : null)), 120_000)
+  check('A1 mock 任务生命周期跑通', finalState === 'COMPLETED', `state=${finalState}`)
+
+  // A2:terminals 端点 → 空数组
+  const terms = await api('GET', `/api/workshop/channels/${channelId}/terminals`, { token })
+  check('A2 GET /channels/:id/terminals 形状(数组)', terms.code === 0 && Array.isArray(terms.data))
+  check('A2 mock channel 无终端会话(omp 专属)', (terms.data ?? []).length === 0, `count=${terms.data?.length}`)
+
+  // A3:WS 以 mock agent 的 agentId 连接 → NO_SESSION
+  {
+    const t = openTerminalWs(`agentId=${leadAgentId}&channelId=${channelId}&token=${token}`)
+    const closed = await t.waitClose()
+    check('A3 WS mock agentId → NO_SESSION 优雅拒绝', closed && t.messages.some(m => m.type === 'term.error' && m.code === 'NO_SESSION'), `msgs=${t.messages.map(m => m.type).join(',')}`)
+  }
+
+  // A4:monitor 快照,mock agent in-proc
+  const mon = await api('GET', '/api/system/monitor', { token })
+  const mockAgent = (mon.data?.agents ?? []).find(a => a.agentId === leadAgentId)
+  check('A4 monitor:mock agent 无子进程(in-proc)', mockAgent?.process === null || mockAgent?.process === undefined)
+  const ompProcs = (mon.data?.processes ?? []).filter(p => p.harness === 'omp')
+  check('A4 monitor:当前无 omp 进程行', ompProcs.length === 0, `omp=${ompProcs.length}`)
+
+  // 清理
+  await api('DELETE', `/api/workshop/channels/${channelId}`, { token })
+  void workerId
+}
+
+// ═══════════════════ Phase B:omp 环境 ═══════════════════
+
+async function phaseOmp() {
+  section('Phase B — omp 环境(简单任务全链路 + rpc-ui HITL)')
+  const token = await registerUser('term-e2e-omp')
+
+  // B1:WS 鉴权负例
+  {
+    const t = openTerminalWs('pid=999999')
+    const closed = await t.waitClose()
+    check('B1 无 token → USER_UNAUTHORIZED', closed && t.messages.some(m => m.type === 'term.error' && m.code === 'USER_UNAUTHORIZED'))
+  }
+  {
+    const t = openTerminalWs(`pid=999999&token=${token}`)
+    const closed = await t.waitClose()
+    check('B1 有效 token + 不存在 pid → NO_SESSION', closed && t.messages.some(m => m.type === 'term.error' && m.code === 'NO_SESSION'))
+  }
+  {
+    const t = openTerminalWs(`token=${token}`)
+    const closed = await t.waitClose()
+    check('B1 缺 pid/agentId → BAD_PID', closed && t.messages.some(m => m.type === 'term.error' && m.code === 'BAD_PID'))
+  }
+
+  // B2:omp channel + 任务 → spawn
+  const { channelId, leadAgentId } = await createChannel(token, `omp-e2e-${Date.now().toString(36)}`, 'omp')
+  check('B2 创建 omp lead channel', true, `channel=${channelId.slice(0, 8)}`)
+  const task = await api('POST', `/api/workshop/channels/${channelId}/tasks`, {
+    body: { title: 'hitl-e2e', description: 'Wait for further instructions from the human operator via the terminal.' },
+    token,
+  })
+  const taskId = task.data?.id
+  check('B2 提交任务(触发 supervise → omp spawn)', task.code === 0, `task=${taskId.slice(0, 8)}`)
+
+  const proc = await waitUntil('omp 进程 spawn(terminal:true)', async () => {
+    const snap = await api('GET', '/api/system/monitor', { token })
+    return (snap.data?.processes ?? []).find(p => p.harness === 'omp' && p.alive && p.terminal && p.agentId === leadAgentId) ?? null
+  })
+  check('B2 monitor:omp 进程存活且 terminal:true', true, `pid=${proc.pid} name=${proc.name}`)
+
+  // B3:terminals 端点
+  const terms = await api('GET', `/api/workshop/channels/${channelId}/terminals`, { token })
+  const mine = (terms.data ?? []).find(t => t.agentId === leadAgentId)
+  check('B3 terminals 端点返回该成员会话', !!mine && mine.pid === proc.pid && mine.alive === true, `pid=${mine?.pid} running=${mine?.running}`)
+
+  // B4:WS agentId 连接
+  const t = openTerminalWs(`agentId=${leadAgentId}&channelId=${channelId}&token=${token}`)
+  await waitUntil('term.init', () => t.messages.some(m => m.type === 'term.init'))
+  const init = t.messages.find(m => m.type === 'term.init')
+  check('B4 term.init(agentId 解析,meta 归属 lead)', init?.meta?.pid === proc.pid && init.meta.agentId === leadAgentId && init.meta.role === 'lead', `pid=${init?.meta?.pid}`)
+  await waitUntil('帧流到达', () => t.frames().length > 0)
+  const frameTypes = new Set(t.frames().map(f => String(f.frame.type)))
+  check('B4 帧流回放含会话事件', frameTypes.has('agent_start') || frameTypes.has('message_start') || frameTypes.has('message_update'), `types=${[...frameTypes].slice(0, 8).join(',')}`)
+
+  // B5:ping/pong
+  t.send({ type: 'ping' })
+  await waitUntil('pong', () => t.messages.some(m => m.type === 'pong'), 10_000)
+  check('B5 ping → pong', true)
+
+  // B6:等 lead 空闲 → 注入 ask 指令(follow_up)
+  await waitUntil('lead 空闲', () => {
+    const state = t.messages.findLast(m => m.type === 'term.state')
+    return state ? state.running === false : init?.running === false
+  }, 240_000).catch(() => console.log('  (等待空闲超时,仍尝试注入)'))
+
+  t.send({ type: 'input', text: 'Use the ask tool NOW to ask me: Proceed? with options yes and no. After I answer, call complete_task with the deliverable set to my answer.' })
+  const humanEcho = await waitUntil('__human_input 广播', () => t.frames().some(f => f.frame.type === '__human_input'), 30_000).catch(() => null)
+  check('B6 注入 → __human_input 帧广播', humanEcho !== null)
+  const accepted = await waitUntil('注入受理', () => {
+    return t.frames().some(f => f.frame.type === 'response' && (f.frame.command === 'follow_up' || f.frame.command === 'steer') && f.frame.success === true)
+  }, 60_000).catch(() => null)
+  check('B6 omp 受理注入(steer/follow_up response)', accepted !== null)
+
+  // B7:extension_ui_request 实时帧 → 应答 → ask 收到答案
+  const dialog = await waitUntil('extension_ui_request 实时帧', () => {
+    const f = t.frames().findLast(f => f.frame.type === 'extension_ui_request' && ['select', 'confirm', 'input', 'editor'].includes(String(f.frame.method)))
+    return f ?? null
+  }, 240_000)
+  const dlg = dialog.frame
+  check('B7 ask 对话框实时到达(extension_ui_request)', dlg.method === 'select' && String(dlg.title).includes('Proceed'), `method=${dlg.method} options=${JSON.stringify(dlg.options).slice(0, 80)}`)
+
+  t.send({ type: 'ui_response', id: String(dlg.id), value: 'yes' })
+  const askResult = await waitUntil('ask 工具收到答案', () => {
+    return t.frames().some(f => f.frame.type === 'tool_execution_end' && String(f.frame.toolName) === 'ask' && String(f.frame.result).includes('yes')) ?? null
+  }, 120_000)
+  check('B7 ui_response 应答 → ask 工具收到 "yes"', askResult !== null)
+
+  // B8:任务完成
+  const finalState = await waitUntil('任务终态', () => taskState(token, channelId, taskId).then(s => (s === 'COMPLETED' || s === 'FAILED' ? s : null)), 240_000)
+  check('B8 HITL 应答后任务完成', finalState === 'COMPLETED', `state=${finalState}`)
+
+  // 断开
+  t.ws.close()
+
+  // 清理:终止进程 + 删除 channel
+  const stop = await api('POST', '/api/system/monitor/terminate', { body: { channelId, agentId: leadAgentId }, token })
+  check('B9 终止 lead 进程(runtime 卸载)', stop.code === 0)
+  const del = await api('DELETE', `/api/workshop/channels/${channelId}`, { token })
+  check('B9 删除 channel', del.code === 0)
+}
+
+async function main() {
+  console.log(`目标: ${BASE}(生产构建 .output)\n`)
+  await phaseMock()
+  await phaseOmp()
+  console.log(`\n★ 结果: ${passed} passed, ${failures} failed`)
+  process.exit(failures === 0 ? 0 : 1)
+}
+
+main().catch((err) => {
+  console.error('e2e 异常:', err.message)
+  process.exit(1)
+})

package/scripts/test-town-3d.mjs

@@ -0,0 +1,121 @@
+/**
+ * 小镇·3D(Three.js)走查与断言 —— 默认渲染器为 3D。
+ * 断言:
+ *  - 默认进入 ?view=town 时是 3D 渲染器(__town.scene 是 Three 场景,有 getMinimapState);
+ *  - 渲染出 ≥1 领地 + 角色(getDebugState().blocks/agents);
+ *  - drop 一个模型到角色 → 换装(modelRef/textureKey 变化);
+ * 截图供人工走查。
+ * 依赖:dev server(127.0.0.1:3000)+ Edge + puppeteer-core。
+ */
+import puppeteer from 'puppeteer-core'
+import fs from 'node:fs'
+
+const SHELL = `${process.env.USERPROFILE}\\.cache\\puppeteer\\chrome-headless-shell\\win64-131.0.6778.204\\chrome-headless-shell-win64\\chrome-headless-shell.exe`
+const BASE = 'http://127.0.0.1:3000'
+const OUT = 'gui-test-screenshots/wuwa-3d'
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+const api = async (m, ep, { body, token } = {}) => {
+  const h = { 'content-type': 'application/json' }
+  if (token) h.authorization = `Bearer ${token}`
+  const r = await fetch(`${BASE}${ep}`, { method: m, headers: h, body: body ? JSON.stringify(body) : undefined })
+  return r.json()
+}
+
+async function main() {
+  fs.mkdirSync(OUT, { recursive: true })
+  const email = `t3d-${Date.now().toString(36)}@test.local`
+  const reg = await api('POST', '/api/users/register', { body: { name: `t3d-${Date.now().toString(36)}`, email, password: 'Passw0rd!123' } })
+  if (!reg.data) {
+    console.error('REG FAIL')
+    process.exit(2)
+  }
+  const { token } = reg.data
+  // 3 频道(各 lead+worker) → 3D 环形布点
+  const mkCh = async (name) => {
+    const ch = await api('POST', '/api/workshop/channels', { body: { name, scenarioPrompt: 't', leadAgent: { name: `${name}-lead`, harness: 'mock' } }, token })
+    await api('POST', `/api/workshop/channels/${ch.data.channelId}/agents`, { body: { name: `${name}-w`, harness: 'mock', role: 'worker' }, token })
+    return ch.data.channelId
+  }
+  const cids = []
+  for (const n of ['海港', '苔原', '工坊']) cids.push(await mkCh(n))
+  const ws = await api('POST', '/api/workshop/workspaces', { body: { name: 't3d-ws' }, token })
+  for (const c of cids) await api('POST', `/api/workshop/workspaces/${ws.data.id}/channels/${c}`, { token })
+
+  const browser = await puppeteer.launch({ executablePath: SHELL, headless: 'new', args: ['--no-sandbox'], defaultViewport: { width: 1400, height: 900 } })
+  const page = await browser.newPage()
+  page.on('pageerror', (e) => {
+    console.log('  [pageerror]', e.message.slice(0, 200))
+  })
+  await page.goto(`${BASE}/workshop`, { waitUntil: 'domcontentloaded' })
+  await sleep(2500)
+  const si = (s, v) => page.$eval(s, (el, val) => {
+    const pr = el.tagName === 'TEXTAREA' ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype
+    Object.getOwnPropertyDescriptor(pr, 'value').set.call(el, val)
+    el.dispatchEvent(new Event('input', { bubbles: true }))
+  }, v)
+  await si('input[type=email]', email)
+  await si('input[type=password]', 'Passw0rd!123')
+  await sleep(200)
+  for (const bt of await page.$$('button')) {
+    if (((await bt.evaluate(el => el.textContent)) || '').trim().replace(/\s/g, '') === '登录') {
+      await bt.click()
+      break
+    }
+  }
+  await sleep(4500)
+  await page.goto(`${BASE}/workshop/w/${ws.data.id}?view=town`, { waitUntil: 'domcontentloaded' })
+  await sleep(6000)
+
+  // 断言:是 3D 渲染器 + 有 blocks/agents(偶尔 401 抽风 → 重试一次)
+  let state = { ok: false }
+  for (let i = 0; i < 3; i++) {
+    state = await page.evaluate(() => {
+      const s = window.__town?.scene
+      if (!s) return { ok: false }
+      return { ok: true, is3D: typeof s.getMinimapState === 'function' && 'screenToWorld' in s, blocks: s.getDebugState?.().blocks, agents: s.getDebugState?.().agents?.length }
+    })
+    if (state.ok) break
+    await sleep(2000)
+    await page.goto(`${BASE}/workshop/w/${ws.data.id}?view=town`, { waitUntil: 'domcontentloaded' })
+    await sleep(4000)
+  }
+  console.log('state:', JSON.stringify(state))
+  const is3D = state.is3D === true
+  console.log(`3D 渲染器: ${is3D ? 'PASS' : 'CHECK'} | blocks=${state.blocks} agents=${state.agents}`)
+
+  await page.screenshot({ path: `${OUT}/01-3d-town.png` })
+
+  // 放大到 某 worker,展示 3D 角色近景
+  if (is3D) {
+    await page.evaluate(() => {
+      const s = window.__town.scene
+      const mm = s.getMinimapState()
+      const a = mm.agents.find(x => x.busy === false) || mm.agents[0]
+      if (a && s.focusTo) s.focusTo(a.x * mm.world.w, a.y * mm.world.h)
+      s.dolly = 1.9
+    })
+    await sleep(1200)
+    await page.screenshot({ path: `${OUT}/02-3d-closeup.png` })
+  }
+
+  // 若 3D 正常,断言 drop 换装
+  if (is3D) {
+    const worker = await page.evaluate(() => window.__town.scene.getDebugState().agents.find(a => a.role === 'worker' && a.channelId))
+    const before = worker?.textureKey
+    await page.evaluate(w => window.__town.scene.dropModelOnWorld(w.x, w.y, 'knight'), worker)
+    await sleep(1500)
+    const after = await page.evaluate(id => window.__town.scene.getDebugState().agents.find(a => a.agentId === id)?.textureKey, worker.agentId)
+    console.log(`换装: ${before} → ${after} | ${after === 'knight' && after !== before ? 'PASS' : 'CHECK'}`)
+    await page.screenshot({ path: `${OUT}/02-3d-rebind.png` })
+  }
+
+  const ok = is3D && state.blocks >= 1 && state.agents >= 1
+  console.log(ok ? '\n==> 3D OK' : '\n==> 3D NOT READY')
+  await browser.close()
+  process.exit(ok ? 0 : 1)
+}
+main()
+  .catch((e) => {
+    console.error(e)
+    process.exit(2)
+  })