agentworkshop 0.2.1

package/scripts/test-a2a-relay.mjs

@@ -0,0 +1,222 @@
+/**
+ * A2A 通信中继实测(omp + glm-5-turbo):出题 → 解答 → 判定 三段链路。
+ *  - 团队:lead + worker1(quiz-master 出题者) + worker2(solver 解题者)
+ *  - 链路:worker1 经 send_message_to_agent 出题给 worker2(require_reply+immediate)
+ *         → worker2 解答回复(in_reply_to 关联) → worker1 核对判定并回复
+ *         → lead 经 read_channel_mail 全览通信后总结完成
+ *  - 断言:
+ *    R1 roster 注入(worker1 回合 prompt 含 Team Roster + 同伴名 + 专长)
+ *    R2 题目消息 w1→w2(priority=immediate / require_reply)
+ *    R3 答案消息 w2→w1 且 in_reply_to 精确关联题目消息 id(A2A 寻址正确)
+ *    R4 判定消息 w1→w2(含 正确/错误 结论)
+ *    R5 链路消息均已消费(无滞留 pending)
+ *    R6 goal 父任务 COMPLETED 且结语交付提及链路
+ * 运行:node scripts/test-a2a-relay.mjs
+ */
+const BASE = process.env.AW_BASE ?? 'http://127.0.0.1:3101'
+const PROVIDER = 'zhipu-coding-plan'
+const MODEL = 'glm-5-turbo'
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+let passed = 0, failures = 0
+const check = (name, ok, detail = '') => {
+  console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (ok) passed += 1
+  else failures += 1
+}
+
+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 waitUntil(name, cond, timeoutMs, intervalMs = 4000) {
+  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, 140)})`)
+}
+
+async function main() {
+  // ═══ 1. 组队 ═══
+  const user = await api('POST', '/api/workshop/users/register', { body: { name: `a2a-relay-${Date.now().toString(36)}` } })
+  const token = user.data?.token
+  if (!token) throw new Error('注册失败')
+
+  const ch = await api('POST', '/api/workshop/channels', {
+    body: {
+      name: 'quiz-relay',
+      leadAgent: { name: 'relay-lead', harness: 'omp', config: { provider: PROVIDER, model: MODEL } },
+    },
+    token,
+  })
+  if (ch.code !== 0) throw new Error('channel 创建失败: ' + JSON.stringify(ch).slice(0, 140))
+  const channelId = ch.data.channelId
+  const leadId = ch.data.leadAgentId
+
+  const w1 = await api('POST', `/api/workshop/channels/${channelId}/agents`, {
+    body: {
+      name: 'quiz-master',
+      harness: 'omp',
+      role: 'worker',
+      config: {
+        provider: PROVIDER,
+        model: MODEL,
+        systemPromptPrefix: 'You are a math quiz master. You create exactly one arithmetic quiz question (two-digit multiplication) and later verify the answer, stating explicitly 正确 or 错误 with the correct value.',
+      },
+    },
+    token,
+  })
+  const w2 = await api('POST', `/api/workshop/channels/${channelId}/agents`, {
+    body: {
+      name: 'solver',
+      harness: 'omp',
+      role: 'worker',
+      config: {
+        provider: PROVIDER,
+        model: MODEL,
+        systemPromptPrefix: 'You are a precise solver. You compute arithmetic answers step by step and always reply with the final numeric result clearly.',
+      },
+    },
+    token,
+  })
+  if (w1.code !== 0 || w2.code !== 0) throw new Error('worker 创建失败')
+  const w1Id = w1.data.id
+  const w2Id = w2.data.id
+  check('团队就绪(lead + quiz-master + solver)', true, `channel=${channelId.slice(0, 8)}`)
+
+  // ═══ 2. 提交 GOAL 中继任务 ═══
+  const task = await api('POST', `/api/workshop/channels/${channelId}/tasks`, {
+    body: {
+      title: 'quiz-relay-check',
+      description: [
+        '[mode:goal][criteria:三段通信链(题目→解答→判定)全部经 send_message_to_agent 完成,lead 总结全链后交付]',
+        '作业流程(严格按序,全部用 send_message_to_agent 完成,不要用任务派发代替通信):',
+        '1. 把工作派发给 quiz-master(worker)。',
+        '2. quiz-master 出一道两位数乘法题,用 send_message_to_agent 发给 solver(to_agent_id=solver的id, require_reply=true, priority=immediate)。',
+        '3. solver 计算后用 send_message_to_agent 把答案回复 quiz-master(in_reply_to=题目消息id)。',
+        '4. quiz-master 核对答案,用 send_message_to_agent 把判定(正确 或 错误+正确值)回复 solver,然后完成任务(交付=题目、答案、判定)。',
+        '5. lead 用 read_channel_mail 查看三段通信记录,确认链路完整,以总结(题目/答案/判定/链路)交付完成本任务。',
+      ].join('\n'),
+    },
+    token,
+  })
+  const parentId = task.data?.id
+  if (!parentId) throw new Error('任务提交失败')
+
+  const tasksOf = async () => (await api('GET', `/api/workshop/channels/${channelId}/tasks`, { token })).data ?? []
+  const mailsOf = async () => {
+    const res = await api('GET', `/api/workshop/channels/${channelId}/messages?limit=400`, { token })
+    return (res.data ?? []).map(m => ({
+      id: m.id,
+      from: m.fromAgentId,
+      to: m.toAgentId,
+      state: m.state,
+      text: (m.parts ?? []).map(p => p.text ?? '').join(' '),
+      meta: m.metadata ?? {},
+    }))
+  }
+
+  // ═══ 3. roster 注入观测(worker1 回合 prompt 帧含 Team Roster) ═══
+  const termFrames = async () => {
+    const t = await api('GET', `/api/workshop/channels/${channelId}/terminals`, { token })
+    const has = (t.data ?? []).some(x => x.agentId === w1Id)
+    if (!has) return null
+    return new Promise((resolve) => {
+      const frames = []
+      const ws = new WebSocket(`ws://127.0.0.1:3101/api/system/monitor/terminal/ws?agentId=${w1Id}&channelId=${channelId}&token=${token}`)
+      ws.onmessage = (ev) => {
+        const m = JSON.parse(ev.data)
+        if (m.type === 'term.frames') frames.push(...m.frames)
+      }
+      ws.onopen = () => setTimeout(() => {
+        ws.close()
+        resolve(frames)
+      }, 1500)
+      ws.onerror = () => resolve(null)
+    })
+  }
+  try {
+    const promptText = await waitUntil('worker1 roster prompt 帧', async () => {
+      const frames = await termFrames()
+      if (!frames) return null
+      const hit = frames.find(f => f.frame.type === 'message_start' && f.frame.role === 'user'
+        && String(f.frame.text ?? '').includes('Team Roster'))
+      return hit ? String(hit.frame.text) : null
+    }, 300_000, 8000)
+    check('R1a roster 注入(worker1 prompt 含 Team Roster)', promptText.includes('Team Roster'))
+    check('R1b 名册含同伴与专长', promptText.includes('solver') && promptText.includes('quiz-master') && promptText.includes('擅长'), promptText.slice(promptText.indexOf('Team Roster'), promptText.indexOf('Team Roster') + 120).replace(/\n/g, ' '))
+    check('R1c 名册标注自己', promptText.includes('← 你'), '')
+  }
+  catch (e) {
+    check('R1 roster 注入观测', false, String(e).slice(0, 90))
+  }
+
+  // ═══ 4. 等父任务终态 ═══
+  const finalState = await waitUntil('父任务终态', async () => {
+    const t = (await tasksOf()).find(x => x.id === parentId)
+    return ['COMPLETED', 'FAILED', 'CANCELED'].includes(t?.state ?? '') ? t.state : null
+  }, 600_000, 5000)
+  check('R6a goal 父任务完成', finalState === 'COMPLETED', `state=${finalState}`)
+
+  // ═══ 5. 邮件链路断言 ═══
+  const mails = await mailsOf()
+  const mailsOfResult = mails
+  const peer = mails.filter(m => m.from && m.to && m.meta['x-aw-task-kind'] === undefined)
+  const q = peer.filter(m => m.from === w1Id && m.to === w2Id && !m.meta['x-aw-in-reply-to'])
+  const a = peer.filter(m => m.from === w2Id && m.to === w1Id)
+  const v = peer.filter(m => m.from === w1Id && m.to === w2Id && m.meta['x-aw-in-reply-to'])
+
+  check('R2 题目消息 w1→w2', q.length >= 1, `count=${q.length}`)
+  check('R2b 题目要求回复且实时', q.length >= 1 && q.some(m => m.meta['x-aw-require-reply'] === 'true' && m.meta['x-aw-msg-priority'] === 'immediate'), '')
+
+  check('R3a 答案消息 w2→w1', a.length >= 1, `count=${a.length}`)
+  const qIds = new Set(q.map(m => m.id))
+  const linked = a.filter(m => qIds.has(String(m.meta['x-aw-in-reply-to'])))
+  check('R3b in_reply_to 精确关联题目消息', linked.length >= 1, `linked=${linked.length}/${a.length}`)
+
+  check('R4 判定消息 w1→w2(带关联)', v.length >= 1, `count=${v.length}`)
+  const allRelay = [...q, ...a, ...v]
+  const chainText = allRelay.map(m => m.text).join(' ')
+  check('R4b 判定含 正确/错误 结论', /正确|错误|correct|wrong/i.test(chainText), '')
+
+  const stuck = allRelay.filter(m => m.state === 'pending')
+  check('R5 链路消息全部消费(无滞留)', stuck.length === 0, `pending=${stuck.length}/${allRelay.length}`)
+
+  const parent = (await tasksOf()).find(t => t.id === parentId)
+  const parentText = JSON.stringify(parent?.artifacts ?? '')
+  check('R6b 结语交付提及链路/判定', (parent?.artifacts?.length ?? 0) > 0 && /正确|错误|题目|判定|链|quiz/i.test(parentText), parentText.slice(0, 110))
+
+  // lead 通信观察断言:直接调 read_channel_mail,或经信箱收到 w1 的链路汇报
+  // (两种都是"lead 能看到通信记录"的有效形态;结语引用链路已由 R6b 保证)
+  const evs = (await api('GET', `/api/workshop/channels/${channelId}/events?limit=800`, { token })).data?.items ?? []
+  const leadRead = evs.some(e => e.agentId === leadId && /read_channel_mail/.test(JSON.stringify(e.payload ?? {})))
+  const leadGotReport = mailsOfResult.filter(m => m.to === leadId && m.from === w1Id && /正确|判定|链|完成/.test(m.text)).length > 0
+  check('R7 lead 可见通信记录(read_channel_mail 或 收到链路汇报)', leadRead || leadGotReport, `tool=${leadRead}, report=${leadGotReport}`)
+
+  // 清理
+  const members = await api('GET', `/api/workshop/channels/${channelId}/agents`, { token })
+  for (const m of members.data ?? []) {
+    await api('POST', '/api/system/monitor/terminate', { body: { channelId, agentId: m.id }, token }).catch(() => {})
+  }
+  if (failures === 0) {
+    await api('DELETE', `/api/workshop/channels/${channelId}`, { token }).catch(() => {})
+  }
+
+  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-a2a-types.ts

@@ -0,0 +1,296 @@
+/**
+ * A2A 类型 + Agent 接口层测试(node + tsx 直跑,无浏览器)。
+ *
+ * 覆盖:
+ *  1. Part 四变体(text/data/url/raw)构造与判别
+ *  2. A2AMessage 往返 JSON 序列化(messageId/contextId/parts/metadata 保真)
+ *  3. WorkspaceTask 默认值与 JSON 序列化
+ *  4. AgentEvent 五变体(kind 判别 + 各字段类型收窄)
+ *  5. SupervisionDecision 五变体判别
+ *  6. AgentInterface 结构验证(mock 对象 run 返回 AsyncIterable 可迭代)
+ */
+import type { Part, A2AMessage, A2AArtifact } from '../server/services/workshop/types/a2a'
+import type { TaskState, WorkspaceTask } from '../server/services/workshop/types/task'
+import type {
+  AgentEvent,
+  AgentInfo,
+  AgentInterface,
+  AgentRunContext,
+  AgentRunRequest,
+  AgentWorkspace,
+  SupervisionDecision,
+  SupervisionSnapshot,
+} from '../server/services/workshop/agents/agent-interface'
+
+let failures = 0
+function check(name: string, ok: boolean, detail = ''): void {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (!ok) {
+    failures += 1
+  }
+}
+
+/** 判别 Part 变体,返回其判别键(用于类型收窄验证) */
+function partKind(part: Part): 'text' | 'data' | 'url' | 'raw' {
+  if ('text' in part) return 'text'
+  if ('data' in part) return 'data'
+  if ('url' in part) return 'url'
+  return 'raw'
+}
+
+function testPart(): void {
+  console.log('\n--- 1. Part 四变体 ---')
+
+  const text: Part = { text: 'hello', mediaType: 'text/plain', metadata: { k: 'v' } }
+  const data: Part = { data: { n: 1 }, mediaType: 'application/json' }
+  const url: Part = { url: 'https://example.com/a.png', mediaType: 'image/png', filename: 'a.png' }
+  const raw: Part = { raw: 'base64==', mediaType: 'application/octet-stream', filename: 'b.bin' }
+
+  check('text 变体判别', partKind(text) === 'text')
+  check('text 变体字段收窄(string)', typeof text.text === 'string')
+  check('text 变体 mediaType', text.mediaType === 'text/plain')
+  check('text 变体 metadata', text.metadata?.k === 'v')
+
+  check('data 变体判别', partKind(data) === 'data')
+  check('data 变体字段收窄(unknown 承载任意值)', (data.data as { n: number }).n === 1)
+  check('data 变体 mediaType', data.mediaType === 'application/json')
+
+  check('url 变体判别', partKind(url) === 'url')
+  check('url 变体字段收窄(string + filename)', typeof url.url === 'string' && url.filename === 'a.png')
+
+  check('raw 变体判别', partKind(raw) === 'raw')
+  check('raw 变体字段收窄(string + filename)', typeof raw.raw === 'string' && raw.filename === 'b.bin')
+}
+
+function testA2AMessage(): void {
+  console.log('\n--- 2. A2AMessage 往返 JSON 序列化 ---')
+
+  const msg: A2AMessage = {
+    messageId: 'm-1',
+    contextId: 'ch-1',
+    taskId: 't-1',
+    role: 'ROLE_AGENT',
+    parts: [
+      { text: 'hi' },
+      { data: { x: 42 }, mediaType: 'application/json' },
+      { url: 'https://x/y', filename: 'y' },
+      { raw: 'AAAA', mediaType: 'application/octet-stream' },
+    ],
+    metadata: { 'x-aw-task-kind': 'assign', 'x-aw-task-id': 't-1' },
+    extensions: ['ext-a'],
+    referenceTaskIds: ['t-0'],
+  }
+
+  const roundtrip: A2AMessage = JSON.parse(JSON.stringify(msg))
+  check('messageId 保真', roundtrip.messageId === 'm-1')
+  check('contextId 保真', roundtrip.contextId === 'ch-1')
+  check('taskId 保真', roundtrip.taskId === 't-1')
+  check('role 保真', roundtrip.role === 'ROLE_AGENT')
+  check('parts 长度保真', roundtrip.parts.length === 4)
+  check('parts 内容保真(text)', (roundtrip.parts[0] as { text: string }).text === 'hi')
+  check('parts 内容保真(data)', (roundtrip.parts[1] as { data: unknown }).data !== undefined)
+  check('metadata 保真', roundtrip.metadata?.['x-aw-task-kind'] === 'assign')
+  check('extensions 保真', roundtrip.extensions?.[0] === 'ext-a')
+  check('referenceTaskIds 保真', roundtrip.referenceTaskIds?.[0] === 't-0')
+}
+
+function testWorkspaceTask(): void {
+  console.log('\n--- 3. WorkspaceTask 默认值与 JSON 序列化 ---')
+
+  const artifact: A2AArtifact = { artifactId: 'art-1', name: '报告', parts: [{ text: '成果' }] }
+  const history: A2AMessage = { messageId: 'm-h', contextId: 'ch-1', role: 'ROLE_USER', parts: [{ text: '开始' }] }
+
+  const task: WorkspaceTask = {
+    id: 'task-1',
+    channelId: 'ch-1',
+    assigneeId: 'agent-a',
+    creatorId: 'lead-1',
+    title: '写周报',
+    state: 'WORKING',
+    progress: 0,
+    retryCount: 0,
+    artifacts: [artifact],
+    history: [history],
+    createdAt: '2026-08-13T00:00:00.000Z',
+    updatedAt: '2026-08-13T00:00:00.000Z',
+  }
+
+  // 可选字段(parentId/description)缺省为 undefined
+  check('parentId 缺省为 undefined', task.parentId === undefined)
+  check('description 缺省为 undefined', task.description === undefined)
+
+  const roundtrip: WorkspaceTask = JSON.parse(JSON.stringify(task))
+  check('id 保真', roundtrip.id === 'task-1')
+  check('channelId 保真', roundtrip.channelId === 'ch-1')
+  check('state 保真', roundtrip.state === 'WORKING')
+  check('progress 保真', roundtrip.progress === 0)
+  check('retryCount 保真', roundtrip.retryCount === 0)
+  check('artifacts 保真', roundtrip.artifacts.length === 1 && roundtrip.artifacts[0].artifactId === 'art-1')
+  check('history 保真', roundtrip.history.length === 1 && roundtrip.history[0].messageId === 'm-h')
+  check('createdAt 保真', roundtrip.createdAt === '2026-08-13T00:00:00.000Z')
+
+  // 终态枚举:TaskState 各取值均可赋值
+  const states: TaskState[] = ['SUBMITTED', 'ASSIGNED', 'WORKING', 'WAITING', 'COMPLETED', 'FAILED', 'CANCELED']
+  check('TaskState 七个枚举值', states.length === 7 && states.includes('COMPLETED') && states.includes('CANCELED'))
+}
+
+function testAgentEvent(): void {
+  console.log('\n--- 4. AgentEvent 五变体 ---')
+
+  const statusEvt: AgentEvent = { kind: 'status', status: { state: 'working', timestamp: '2026-08-13T00:00:00.000Z' } }
+  const msgEvt: AgentEvent = { kind: 'message', message: { messageId: 'm-1', contextId: 'ch-1', role: 'ROLE_AGENT', parts: [{ text: 'hi' }] } }
+  const artEvt: AgentEvent = { kind: 'artifact', artifact: { artifactId: 'art-1', parts: [{ text: 'x' }] }, append: true, lastChunk: false, totalChunks: 3 }
+  const errEvt: AgentEvent = { kind: 'error', error: { code: 'X', message: 'boom' } }
+  const doneEvt: AgentEvent = { kind: 'done', final: { taskId: 't-1' } }
+
+  check('status 变体判别', statusEvt.kind === 'status')
+  check('status 变体字段收窄(state/timestamp)', typeof statusEvt.status.state === 'string' && typeof statusEvt.status.timestamp === 'string')
+
+  check('message 变体判别', msgEvt.kind === 'message')
+  check('message 变体字段收窄(A2AMessage)', msgEvt.message.messageId === 'm-1')
+
+  check('artifact 变体判别', artEvt.kind === 'artifact')
+  check('artifact 变体字段收窄(artifact + 分块)', artEvt.artifact.artifactId === 'art-1' && artEvt.append === true && artEvt.lastChunk === false && artEvt.totalChunks === 3)
+
+  check('error 变体判别', errEvt.kind === 'error')
+  check('error 变体字段收窄(A2AError)', errEvt.error.code === 'X' && errEvt.error.message === 'boom')
+
+  check('done 变体判别', doneEvt.kind === 'done')
+  check('done 变体字段收窄(final.taskId)', doneEvt.final?.taskId === 't-1')
+
+  // 泛化类型收窄:switch 后可安全访问各字段
+  const events: AgentEvent[] = [statusEvt, msgEvt, artEvt, errEvt, doneEvt]
+  let narrowed = true
+  for (const ev of events) {
+    switch (ev.kind) {
+      case 'status':
+        narrowed = narrowed && ev.status.state !== undefined
+        break
+      case 'message':
+        narrowed = narrowed && ev.message.messageId !== undefined
+        break
+      case 'artifact':
+        narrowed = narrowed && ev.artifact.artifactId !== undefined
+        break
+      case 'error':
+        narrowed = narrowed && ev.error.code !== undefined
+        break
+      case 'done':
+        narrowed = narrowed && ev.final !== undefined
+        break
+      default:
+        narrowed = false
+    }
+  }
+  check('五变体 switch 全收窄无遗漏', narrowed)
+}
+
+function testSupervisionDecision(): void {
+  console.log('\n--- 5. SupervisionDecision 五变体判别 ---')
+
+  const decisions: SupervisionDecision[] = [
+    { kind: 'dispatch', parentTaskId: 'p-1', assigneeId: 'w-1', title: '子任务', description: 'd', parts: [{ text: 'x' }] },
+    { kind: 'reassign', taskId: 't-1', toAgentId: 'w-2' },
+    { kind: 'cancel', taskId: 't-2' },
+    { kind: 'complete', taskId: 't-3', artifacts: [{ artifactId: 'a-1', parts: [{ text: 'r' }] }] },
+    { kind: 'notify', toAgentId: 'w-3', parts: [{ text: '通知' }] },
+  ]
+
+  check('dispatch 判别', decisions[0].kind === 'dispatch')
+  check('dispatch 字段(assigneeId/title/parts)', decisions[0].kind === 'dispatch' && decisions[0].assigneeId === 'w-1' && decisions[0].title === '子任务' && decisions[0].parts?.length === 1)
+
+  check('reassign 判别', decisions[1].kind === 'reassign')
+  check('reassign 字段(taskId/toAgentId)', decisions[1].kind === 'reassign' && decisions[1].taskId === 't-1' && decisions[1].toAgentId === 'w-2')
+
+  check('cancel 判别', decisions[2].kind === 'cancel')
+  check('cancel 字段(taskId)', decisions[2].kind === 'cancel' && decisions[2].taskId === 't-2')
+
+  check('complete 判别', decisions[3].kind === 'complete')
+  check('complete 字段(taskId/artifacts)', decisions[3].kind === 'complete' && decisions[3].taskId === 't-3' && decisions[3].artifacts?.length === 1)
+
+  check('notify 判别', decisions[4].kind === 'notify')
+  check('notify 字段(toAgentId/parts)', decisions[4].kind === 'notify' && decisions[4].toAgentId === 'w-3' && decisions[4].parts.length === 1)
+}
+
+async function testAgentInterface(): Promise<void> {
+  console.log('\n--- 6. AgentInterface 结构验证 ---')
+
+  const mockImpl: AgentInterface = {
+    async* run(request: AgentRunRequest, _ctx: AgentRunContext): AsyncIterable<AgentEvent> {
+      yield { kind: 'status', status: { state: 'running', timestamp: new Date().toISOString() } }
+      yield { kind: 'message', message: request.message }
+      yield { kind: 'done', final: { taskId: request.taskId } }
+    },
+    async supervise(snapshot: SupervisionSnapshot, _ctx: AgentRunContext): Promise<SupervisionDecision[]> {
+      return snapshot.tasks.length === 0 ? [] : [{ kind: 'cancel', taskId: snapshot.tasks[0].id }]
+    },
+  }
+
+  const agent: AgentInfo = { id: 'agent-a', channelId: 'ch-1', name: 'A', harness: 'mock', role: 'worker', config: {} }
+  const workspace: AgentWorkspace = {
+    listAgents: async () => [agent],
+    dispatchTask: async () => { throw new Error('not implemented') },
+    listTasks: async () => [],
+    getTask: async () => { throw new Error('not implemented') },
+    reportTask: async () => { throw new Error('not implemented') },
+    completeTask: async () => { throw new Error('not implemented') },
+    cancelTask: async () => { throw new Error('not implemented') },
+    myQueue: async () => ({ agentId: 'agent-a', channelId: 'ch-1', queued: [], completed: [] }),
+    queueOverview: async () => [],
+    updateTask: async () => { throw new Error('not implemented') },
+    reassignTask: async () => { throw new Error('not implemented') },
+    sendMessage: async () => { throw new Error('not implemented') },
+    pollMailbox: async () => [],
+    listMail: async () => [],
+    subscribe: async () => {},
+    recallMemory: async () => [],
+    saveMemory: async () => { throw new Error('not implemented') },
+  }
+  const ctx: AgentRunContext = { agentId: 'agent-a', channelId: 'ch-1', role: 'worker', workspace, signal: new AbortController().signal }
+
+  const req: AgentRunRequest = {
+    message: { messageId: 'm-1', contextId: 'ch-1', role: 'ROLE_USER', parts: [{ text: 'hi' }] },
+    contextId: 'ch-1',
+    fromAgentId: null,
+    toAgentId: 'agent-a',
+  }
+
+  check('run 返回 AsyncIterable 且可迭代', typeof mockImpl.run(req, ctx)[Symbol.asyncIterator] === 'function')
+
+  // 实际迭代收集事件
+  const collected: AgentEvent[] = []
+  for await (const ev of mockImpl.run(req, ctx)) {
+    collected.push(ev)
+  }
+  check('迭代产出 3 个事件', collected.length === 3)
+  check('事件顺序(status→message→done)', collected[0].kind === 'status' && collected[1].kind === 'message' && collected[2].kind === 'done')
+
+  // supervise 可选实现
+  check('supervise 可调用返回决策', mockImpl.supervise !== undefined)
+  const decisions = await mockImpl.supervise!(
+    { tick: 1, now: Date.now(), tasks: [], members: [], pendingChildren: {} },
+    ctx,
+  )
+  check('supervise 空快照返回空数组', Array.isArray(decisions) && decisions.length === 0)
+
+  // init/dispose 为可选方法
+  check('init 可选(未实现为 undefined)', mockImpl.init === undefined)
+  check('dispose 可选(未实现为 undefined)', mockImpl.dispose === undefined)
+}
+
+async function main(): Promise<void> {
+  testPart()
+  testA2AMessage()
+  testWorkspaceTask()
+  testAgentEvent()
+  testSupervisionDecision()
+  await testAgentInterface()
+
+  console.log(`\n${failures === 0 ? 'ALL PASS' : `${failures} FAILED`}`)
+  process.exit(failures === 0 ? 0 : 1)
+}
+
+main().catch((e) => {
+  console.error(e)
+  process.exit(1)
+})

package/scripts/test-agent-brain.ts

@@ -0,0 +1,135 @@
+/**
+ * ScriptBrain 模拟 Agent — 纯逻辑单测(node + tsx 直跑,无浏览器依赖)
+ *
+ * 验证状态机迁移与动作输出:
+ *  1. 初始 tick → 进入 wander + move 动作
+ *  2. 玩家进入 6 tiles → approach + 朝玩家方向移动
+ *  3. 玩家贴脸(≤3 tiles)→ talk + dialog 发起 + face
+ *  4. dialog.closed 事件 → wait,冷却后恢复 wander
+ *  5. 地图边缘 → 不朝边界外走
+ *  6. 对话中 → 不产出 move
+ */
+import { ScriptBrain } from '../server/services/game/agent'
+import type { AgentContext, Dir } from '../server/types/game'
+
+let failures = 0
+function check(name: string, ok: boolean, detail = '') {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (!ok)
+    failures += 1
+}
+
+const AGENT_START = { x: 720, y: 656 }
+const rngSeq = (() => {
+  let i = 0
+  const seq = [0.9, 0.1, 0.5, 0.7, 0.3, 0.6, 0.2, 0.8, 0.4, 0.95]
+  return () => seq[i++ % seq.length]
+})()
+
+function mkCtx(over: Partial<AgentContext> = {}): AgentContext {
+  return {
+    tick: 1,
+    now: 1000,
+    agent: { ...AGENT_START, dir: 'down', mode: 'idle' },
+    player: { x: 0, y: 0, lastSeenAt: null, distance: Infinity },
+    rng: rngSeq,
+    ...over,
+  }
+}
+
+// 1. 初始:进入 wander 并产出 move
+{
+  const brain = new ScriptBrain()
+  const acts = brain.think(mkCtx())
+  const state = acts.find(a => a.kind === 'state')
+  const move = acts.find(a => a.kind === 'move')
+  check('初始 tick 进入 wander', state?.kind === 'state' && state.mode === 'wander')
+  check('初始 tick 产出移动动作', move?.kind === 'move' && (move as { durationMs: number }).durationMs > 0,
+    `dir=${(move as { dir: Dir }).dir} dur=${(move as { durationMs: number }).durationMs}ms`)
+}
+
+// 2. 玩家 5 tiles:approach + 朝玩家方向
+{
+  const brain = new ScriptBrain()
+  brain.think(mkCtx()) // 进入 wander
+  const ctx = mkCtx({
+    now: 2000,
+    player: { x: AGENT_START.x + 160, y: AGENT_START.y, lastSeenAt: 1999, distance: 160 },
+  })
+  const acts = brain.think(ctx)
+  const state = acts.find(a => a.kind === 'state')
+  const move = acts.find(a => a.kind === 'move')
+  check('玩家 5 tiles → approach', state?.kind === 'state' && state.mode === 'approach')
+  check('approach 朝玩家方向(right)', move?.kind === 'move' && (move as { dir: Dir }).dir === 'right')
+}
+
+// 3. 玩家贴脸:talk + dialog
+{
+  const brain = new ScriptBrain()
+  brain.think(mkCtx())
+  const ctx = mkCtx({
+    now: 3000,
+    player: { x: AGENT_START.x + 64, y: AGENT_START.y, lastSeenAt: 2999, distance: 64 },
+  })
+  const acts = brain.think(ctx)
+  const dialog = acts.find(a => a.kind === 'dialog')
+  const move = acts.find(a => a.kind === 'move')
+  check('贴脸发起对话', dialog?.kind === 'dialog' && (dialog as { lines: string[] }).lines.length >= 1)
+  check('对话中不产出移动', move === undefined)
+  // 继续 tick:仍 talk,无新 dialog
+  const acts2 = brain.think(mkCtx({ now: 3100, player: { x: AGENT_START.x + 64, y: AGENT_START.y, lastSeenAt: 3099, distance: 64 } }))
+  check('对话期间不重复发起', !acts2.some(a => a.kind === 'dialog'))
+}
+
+// 4. 对话关闭 → wait → 冷却后 wander
+{
+  const brain = new ScriptBrain()
+  brain.think(mkCtx())
+  brain.think(mkCtx({ now: 3000, player: { x: AGENT_START.x + 64, y: AGENT_START.y, lastSeenAt: 2999, distance: 64 } }))
+  brain.onEvent?.({ kind: 'dialog.closed' })
+  const during = brain.think(mkCtx({ now: 3500, player: { x: AGENT_START.x + 64, y: AGENT_START.y, lastSeenAt: 3499, distance: 64 } }))
+  check('dialog.closed → 无动作(wait 冷却)', during.length === 0 || !during.some(a => a.kind === 'move'))
+  const after = brain.think(mkCtx({ now: 9000, player: { x: AGENT_START.x + 64, y: AGENT_START.y, lastSeenAt: 8999, distance: 64 } }))
+  const state = after.find(a => a.kind === 'state')
+  check('冷却后恢复 wander', state?.kind === 'state' && state.mode === 'wander')
+}
+
+// 5. 地图边缘:不向界外走
+{
+  const brain = new ScriptBrain()
+  const ctx = mkCtx({
+    now: 5000,
+    agent: { x: 40, y: 656, dir: 'down', mode: 'wander' }, // 左边缘 40px(<2 tiles=64)
+  })
+  // 固定 rng 序列首个 0.9 → 可能选 left;边缘保护应避免向界外
+  for (let i = 0; i < 20; i++) {
+    const acts = brain.think(ctx)
+    const move = acts.find(a => a.kind === 'move')
+    if (move?.kind === 'move' && move.dir === 'left') {
+      check('地图边缘不向左走', false, `tick ${i} 仍向左`)
+      break
+    }
+    if (i === 19)
+      check('地图边缘不向左走', true)
+  }
+}
+
+// 6. 玩家远离(>11 tiles) → 放弃追逐回 wander
+{
+  const brain = new ScriptBrain()
+  brain.think(mkCtx()) // wander
+  brain.think(mkCtx({
+    now: 2000,
+    player: { x: AGENT_START.x + 160, y: AGENT_START.y, lastSeenAt: 1999, distance: 160 },
+  })) // approach
+  const far = mkCtx({
+    now: 3000,
+    player: { x: AGENT_START.x + 400, y: AGENT_START.y + 400, lastSeenAt: 2999, distance: 566 },
+  })
+  const acts = brain.think(far)
+  const state = acts.find(a => a.kind === 'state')
+  check('玩家远离 → 回 wander', state?.kind === 'state' && state.mode === 'wander')
+}
+
+console.log(`\n===== ${6 - failures}/6 passed =====`)
+process.exit(failures ? 1 : 0)