agentworkshop 0.2.1

package/scripts/test-channel-routing.ts

@@ -0,0 +1,301 @@
+/**
+ * ChannelRuntime 路由测试(node + tsx 直跑,无浏览器)。
+ *
+ * 覆盖:
+ *  1. 点对点直投(x-aw-target-agent)
+ *  2. 跨 channel 目标忽略
+ *  3. 任务消息直投 assignee(x-aw-task-kind)
+ *  4. 广播只达订阅者
+ *  5. 无订阅者时广播无投递
+ *  6. 订阅后广播可达
+ *
+ * 使用真实 ChannelRuntime + 真实 Mailbox(:memory:) + 3 个 fake AgentRuntime(仅 getState/enqueue 记录)。
+ */
+import { randomUUID } from 'node:crypto'
+import type { DatabaseSync } from 'node:sqlite'
+import { openWorkshopDb } from '../server/services/workshop/db/database'
+import { createMessageRepo } from '../server/services/workshop/db/message.repo'
+import type { MessageRepo } from '../server/services/workshop/db/message.repo'
+import { createSubscriptionRepo } from '../server/services/workshop/db/subscription.repo'
+import { createChannelAgentRepo } from '../server/services/workshop/db/channel-agent.repo'
+import { Mailbox } from '../server/services/workshop/runtime/mailbox'
+import { ChannelRuntime } from '../server/services/workshop/runtime/channel-runtime'
+import type { AgentRuntimeLike, TaskEngine } from '../server/services/workshop/runtime/agent-runtime'
+import type { A2AMessage } from '../server/services/workshop/types/a2a'
+import type { AgentStatusView, AgentTaskQueueView } from '../server/services/workshop/types/task'
+
+let failures = 0
+function check(name: string, ok: boolean, detail = ''): void {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (!ok) {
+    failures += 1
+  }
+}
+
+/** 落库一个 channel(messages.channel_id / agents.channel_id 外键依赖) */
+function seedChannel(db: DatabaseSync, id: string): void {
+  const now = new Date().toISOString()
+  db.prepare(
+    `INSERT INTO channels (id, name, description, lead_agent_id, enabled, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)`,
+  ).run(id, id, '', null, 1, now, now)
+}
+
+/** 落库一个 Agent 实例(subscriptions.agent_id 外键依赖 channel_agents.id) */
+function seedAgent(db: DatabaseSync, id: string, channelId: string, role: 'lead' | 'worker'): void {
+  const now = new Date().toISOString()
+  db.prepare(
+    `INSERT INTO channel_agents (id, channel_id, template_id, name, harness, config_json, role, token, enabled, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(id, channelId, null, id, 'mock', '{}', role, randomUUID(), 1, now, now)
+}
+
+function mkTask(channelId: string, assigneeId: string, title: string): WorkspaceTask {
+  return {
+    id: randomUUID(),
+    channelId,
+    assigneeId,
+    creatorId: '',
+    title,
+    state: 'ASSIGNED',
+    progress: 0,
+    retryCount: 0,
+    artifacts: [],
+    history: [],
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  }
+}
+
+/** fake AgentRuntime:仅记录 enqueue,并透过真实 Mailbox 落库 */
+class FakeAgentRuntime implements AgentRuntimeLike {
+  readonly agentId: string
+  readonly role: 'lead' | 'worker'
+  readonly channelId: string
+  received: A2AMessage[] = []
+  readonly mailbox: Mailbox
+
+  constructor(agentId: string, role: 'lead' | 'worker', channelId: string, messages: MessageRepo) {
+    this.agentId = agentId
+    this.role = role
+    this.channelId = channelId
+    this.mailbox = new Mailbox(messages, channelId, agentId, () => {})
+  }
+
+  enqueue(message: A2AMessage): void {
+    this.received.push(message)
+    this.mailbox.enqueue(message)
+  }
+
+  getState(): 'idle' | 'busy' | 'stopped' {
+    return 'idle'
+  }
+
+  wakeMailbox(): void {}
+
+  injectSteer(message: A2AMessage): void {
+    this.enqueue(message)
+  }
+
+  getStatus(): AgentStatusView {
+    return {
+      agentId: this.agentId,
+      channelId: this.channelId,
+      role: this.role,
+      name: this.agentId,
+      state: 'idle',
+      currentTaskId: null,
+      queuedCount: 0,
+      completedCount: 0,
+    }
+  }
+
+  getQueueView(): AgentTaskQueueView {
+    return { agentId: this.agentId, channelId: this.channelId, queued: [], completed: [] }
+  }
+
+  async stop(): Promise<void> {}
+
+  emitExternal(): void {}
+}
+
+function main(): void {
+  const db = openWorkshopDb(':memory:')
+  seedChannel(db, 'ch1')
+  seedAgent(db, 'agentA', 'ch1', 'lead')
+  seedAgent(db, 'agentB', 'ch1', 'worker')
+  seedAgent(db, 'agentC', 'ch1', 'worker')
+  const messages = createMessageRepo(db)
+  const subscriptions = createSubscriptionRepo(db)
+
+  // fake TaskEngine:route 仅调用 get
+  const tasks = new Map<string, WorkspaceTask>()
+  const engine = {
+    get: (taskId: string) => tasks.get(taskId),
+    create: () => {
+      throw new Error('未使用')
+    },
+    dispatch: () => {
+      throw new Error('未使用')
+    },
+    transition: () => {
+      throw new Error('未使用')
+    },
+    applyEvent: () => {},
+    list: () => [] as WorkspaceTask[],
+    complete: () => {
+      throw new Error('未使用')
+    },
+    reassign: () => {
+      throw new Error('未使用')
+    },
+    cancel: () => {
+      throw new Error('未使用')
+    },
+    onChildCompleted: () => {},
+    queueViewOf: () => ({ queued: [], completed: [] }),
+  } as TaskEngine
+
+  const channelId = 'ch1'
+  const cr = new ChannelRuntime(channelId, { taskEngine: engine, subscriptionRepo: subscriptions, channelAgents: createChannelAgentRepo(db) })
+  const a = new FakeAgentRuntime('agentA', 'lead', channelId, messages)
+  const b = new FakeAgentRuntime('agentB', 'worker', channelId, messages)
+  const c = new FakeAgentRuntime('agentC', 'worker', channelId, messages)
+  cr.addAgent(a)
+  cr.addAgent(b)
+  cr.addAgent(c)
+
+  function routeMsg(metadata: Record<string, unknown>): A2AMessage {
+    const msg: A2AMessage = { messageId: randomUUID(), contextId: channelId, role: 'ROLE_USER', parts: [], metadata }
+    cr.route(msg)
+    return msg
+  }
+
+  function clearReceived(): void {
+    a.received = []
+    b.received = []
+    c.received = []
+  }
+
+  console.log('\n--- 基础 ---')
+  check('getAgents 返回 3 个 agent', cr.getAgents().length === 3)
+  check('lead getter 返回 lead agent', cr.lead?.agentId === 'agentA')
+
+  console.log('\n--- 1. 点对点直投 ---')
+  clearReceived()
+  const p2p = routeMsg({ 'x-aw-target-agent': 'agentB', 'x-aw-from-agent': 'agentA' })
+  check('点对点直投:目标收到', b.received.includes(p2p))
+  check('点对点直投:非目标未收到', !a.received.includes(p2p) && !c.received.includes(p2p))
+
+  console.log('\n--- 2. 跨 channel 目标忽略 ---')
+  clearReceived()
+  routeMsg({ 'x-aw-target-agent': 'agentX', 'x-aw-from-agent': 'agentA' })
+  check('跨 channel 目标忽略:无投递', a.received.length === 0 && b.received.length === 0 && c.received.length === 0)
+
+  console.log('\n--- 3. 任务消息直投 assignee ---')
+  const task = mkTask(channelId, 'agentC', '任务C')
+  tasks.set(task.id, task)
+  clearReceived()
+  const assignMsg = routeMsg({ 'x-aw-task-kind': 'assign', 'x-aw-task-id': task.id })
+  check('任务消息直投 assignee', c.received.includes(assignMsg))
+  console.log('\n--- 4. 广播只达订阅者 ---')
+  subscriptions.add(channelId, 'agentA', 'agentB') // A 订阅 B
+  clearReceived()
+  const bcastB = routeMsg({ 'x-aw-from-agent': 'agentB' })
+  check('广播只达订阅者:A 收到', a.received.includes(bcastB))
+  check('广播只达订阅者:B/C 未收到', !b.received.includes(bcastB) && !c.received.includes(bcastB))
+
+  console.log('\n--- 5. 无订阅者时广播无投递 ---')
+  clearReceived()
+  routeMsg({ 'x-aw-from-agent': 'agentC' }) // C 无订阅者
+  console.log('\n--- 6. 订阅后广播可达 ---')
+  subscriptions.add(channelId, 'agentA', 'agentC') // A 订阅 C
+  clearReceived()
+  const bcastC = routeMsg({ 'x-aw-from-agent': 'agentC' })
+  check('订阅后广播可达:A 收到 C 的广播', a.received.includes(bcastC))
+  check('订阅后广播:C 自身未收到', !c.received.includes(bcastC))
+
+  console.log('\n--- 7. 垃圾拦截(无发送人/伪造发送人/无效任务) ---')
+  clearReceived()
+  const noSender = routeMsg({ 'x-aw-target-agent': 'agentB' })
+  check('无发送人消息被拦截', !b.received.includes(noSender))
+  const fakeSender = routeMsg({ 'x-aw-target-agent': 'agentB', 'x-aw-from-agent': 'agentZ' })
+  check('伪造发送人(非成员)消息被拦截', !b.received.includes(fakeSender))
+  routeMsg({ 'x-aw-task-kind': 'assign', 'x-aw-task-id': 'task-not-exist' })
+  check('无效任务消息被拦截', a.received.length === 0 && b.received.length === 0 && c.received.length === 0)
+  const humanMsg = routeMsg({ 'x-aw-target-agent': 'agentB', 'x-aw-from-label': 'tester' })
+  check('人类消息(from-label)放行', b.received.includes(humanMsg))
+
+  console.log('\n--- 真实 Mailbox 持久化 ---')
+  void b.mailbox.peek(10).then(async (peeked) => {
+    const persisted = peeked.find(m => m.metadata?.['x-aw-target-agent'] === 'agentB')
+    check('点对点直投:Mailbox 落库 pending', persisted !== undefined, `peeked ${peeked.length} 条`)
+
+    // ===== 恰好一次认领(steer 注入 / poll_messages 读即取 / 消费循环 dequeue 三方竞争) =====
+    console.log('\n--- 恰好一次认领(原子 claim) ---')
+    // 清空 B 信箱残留(FIFO 顺序干扰):全部认领并消费
+    for (const old of await b.mailbox.peek(50)) {
+      if (b.mailbox.claim(old.messageId)) b.mailbox.markConsumed(old.messageId)
+    }
+    const raceMsg: A2AMessage = {
+      messageId: randomUUID(),
+      contextId: channelId,
+      role: 'ROLE_AGENT',
+      parts: [{ text: 'race' }],
+      metadata: { 'x-aw-target-agent': 'agentB', 'x-aw-from-agent': 'agentA', 'x-aw-msg-priority': 'immediate' },
+    }
+    b.mailbox.enqueue(raceMsg)
+    // 三个竞争方依次认领:只有第一个成功(唯一所有权 → 消息绝不双投)
+    const steerGot = b.mailbox.claim(raceMsg.messageId)
+    const pollGot = b.mailbox.claim(raceMsg.messageId)
+    const dqGot = b.mailbox.claim(raceMsg.messageId)
+    check('首竞争者(steer)认领成功', steerGot === true)
+    check('后到竞争者(poll/dequeue)认领失败', pollGot === false && dqGot === false)
+    // 认领期间消息对 peek 不可见(poll_messages 不会重复取走)
+    const visible = await b.mailbox.peek(10)
+    check('认领期间 peek 不可见', !visible.some(x => x.messageId === raceMsg.messageId))
+    // steer 放弃(deferred)→ requeue 释放回 pending → dequeue 接管
+    check('requeue 释放认领', b.mailbox.requeue(raceMsg.messageId) === true)
+    const taken = await Promise.race([
+      b.mailbox.dequeue(),
+      new Promise<A2AMessage | null>(r => setTimeout(() => r(null), 1000)),
+    ])
+    check('释放后 dequeue 取到消息', taken?.messageId === raceMsg.messageId)
+    // 终态:markConsumed 后 claim 不复活消息
+    b.mailbox.markConsumed(raceMsg.messageId)
+    check('consumed 后 claim 不复活', b.mailbox.claim(raceMsg.messageId) === false)
+
+    // ===== 同毫秒突发 FIFO(rowid 决胜回归) =====
+    // 紧密循环同步入队:大概率全部落在同一毫秒内 → dequeue 顺序必须 === 入队顺序
+    console.log('\n--- 同毫秒突发 FIFO(rowid 决胜) ---')
+    const burst: A2AMessage[] = []
+    for (let i = 0; i < 30; i++) {
+      const m: A2AMessage = {
+        messageId: randomUUID(),
+        contextId: channelId,
+        role: 'ROLE_AGENT',
+        parts: [{ text: `burst-${i}` }],
+        metadata: { 'x-aw-target-agent': 'agentB', 'x-aw-from-agent': 'agentA' },
+      }
+      b.mailbox.enqueue(m)
+      burst.push(m)
+    }
+    const textOf = (m: A2AMessage): string =>
+      (m.parts[0] && 'text' in m.parts[0] ? m.parts[0].text : '') as string
+    const takenOrder: string[] = []
+    for (let i = 0; i < burst.length; i++) {
+      const got = await Promise.race([
+        b.mailbox.dequeue(),
+        new Promise<A2AMessage | null>(r => setTimeout(() => r(null), 1000)),
+      ])
+      if (!got) break
+      takenOrder.push(textOf(got))
+    }
+    const expectOrder = burst.map(textOf)
+    check('30 条同毫秒突发按入队顺序逐条出队(FIFO)', takenOrder.join(',') === expectOrder.join(','),
+      `${takenOrder.length} 条`)
+
+    console.log(`\n${failures === 0 ? 'ALL PASS' : `${failures} FAILURE(S)`}`)
+    process.exit(failures === 0 ? 0 : 1)
+  })
+}
+
+main()

package/scripts/test-cmd-render.mjs

@@ -0,0 +1,218 @@
+/**
+ * 下行指令渲染验证 — puppeteer-core 驱动 Edge + HTTP 注入 execDownlink
+ *
+ * 验证矩阵:
+ *  1. 规范下行指令 → 前端正确渲染(HUD 文本/动画状态/对话框):
+ *     - agent.say    → Agent 头顶气泡(截图可见)
+ *     - dialog.open  → [data-hud="dialog"] 可见 + agentName/lines 正确
+ *     - dialog.close → 对话框消失
+ *     - agent.state  → [data-hud="agent-mode"] 文本变化(待机→游荡→靠近→对话→等待)
+ *     - agent.face   → 精灵朝向(截图可见)
+ *     - agent.move   → 精灵位移(__game 场景坐标变化)
+ *  2. 不规范下行指令 → execDownlink 拒绝(FORBIDDEN/INVALID_PAYLOAD/UNKNOWN_COMMAND),
+ *     前端无变化(对话框未异常打开、HUD 模式不跳变)
+ *
+ * 注入路径: POST /api/game/cmd { type, payload } → session.execDownlink → emit → WS → 前端
+ *           即真实 Agent sendmsg 入口,全链路真实。
+ */
+import puppeteer from 'puppeteer-core'
+import { mkdirSync } from 'node:fs'
+
+const BASE = 'http://localhost:3000'
+const EDGE = 'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe'
+const SHOT_DIR = '.game-verify'
+
+let pass = 0
+let fail = 0
+function check(name, ok, detail = '') {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (ok) pass += 1
+  else fail += 1
+}
+/** POST /api/game/cmd 注入下行指令,返回归一化结果 { ok, applied?, code?, message? }
+ * defineApiHandler 成功时包成 { code:0, data:{applied,...} },失败时为 { code:ErrCode, message } */
+async function injectCmd(page, type, payload) {
+  const res = await page.evaluate(async ({ type, payload, token }) => {
+    const r = await fetch('/api/game/cmd', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
+      body: JSON.stringify({ type, payload }),
+    })
+    return r.json()
+  }, { type, payload, token: USER_TOKEN })
+  if (res.code === 0) {
+    return { ok: true, applied: res.data?.applied === true, type: res.data?.type }
+  }
+  return { ok: false, code: res.code, message: res.message }
+}
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+/** 业务 API 鉴权:注册临时用户拿 token(game/cmd|brain 需用户 token) */
+const USER_TOKEN = await (async () => {
+  const r = await fetch(`${BASE}/api/users/register`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ name: `cmd-${Date.now().toString(36)}`, email: `cmd-${Date.now().toString(36)}@test.local`, password: 'Passw0rd!123' }),
+  }).then(x => x.json())
+  if (r.code !== 0) throw new Error(`注册失败: ${r.message}`)
+  return r.data.token
+})()
+
+/** 读 Agent 模式 HUD 文本 */
+async function agentMode(page) {
+  return page.$eval('[data-hud="agent-mode"]', el => el.textContent.trim())
+}
+
+/** 对话框是否可见 */
+async function dialogVisible(page) {
+  // 用 evaluate 而非 page.$:避免 Transition leave 动画期残留 ElementHandle 的竞态
+  return page.evaluate(() => document.querySelector('[data-hud="dialog"]') !== null)
+}
+
+/** Agent 精灵像素坐标(经调试钩子) */
+async function agentPx(page) {
+  return page.evaluate(() => {
+    const s = window.__game.scene
+    return { x: Math.round(s.agent.x), y: Math.round(s.agent.y), flipX: s.agent.flipX }
+  })
+}
+
+async function waitPageReady(page) {
+  await page.goto(`${BASE}/game`, { waitUntil: 'domcontentloaded', timeout: 30000 })
+  await page.waitForSelector('canvas', { timeout: 20000 })
+  await page.waitForFunction(() => !document.querySelector('[data-hud="loading"]'), { timeout: 25000 })
+  await sleep(1500) // 等 session.ready + agent 放置
+}
+
+async function main() {
+  mkdirSync(SHOT_DIR, { recursive: true })
+  const browser = await puppeteer.launch({
+    executablePath: EDGE,
+    headless: 'new',
+    args: ['--no-sandbox', '--disable-gpu', '--window-size=1400,900'],
+    defaultViewport: { width: 1400, height: 900 },
+  })
+  const page = await browser.newPage()
+  page.on('pageerror', e => console.log('  [pageerror]', e.message.slice(0, 200)))
+
+  console.log('\n=== 下行指令渲染验证 ===')
+  await waitPageReady(page)
+  // 暂停自主 brain:让下行指令渲染验证不受模拟 Agent 自发对话/移动干扰
+  await page.evaluate(async (token) => {
+    await fetch('/api/game/brain?pause=true', { method: 'POST', headers: { authorization: `Bearer ${token}` } })
+  }, USER_TOKEN)
+  await sleep(300)
+  await page.screenshot({ path: `${SHOT_DIR}/cmd-01-baseline.png` })
+
+  // ---------------- 1. 规范下行指令渲染 ----------------
+  console.log('\n--- 1. 规范下行指令 → 渲染 ---')
+
+  // agent.say: 气泡(截图 + applied)
+  const say = await injectCmd(page, 'agent.say', { text: '协议测试气泡', ttlMs: 3000 })
+  check('agent.say 注入 applied=true', say.applied === true, JSON.stringify(say))
+  await sleep(500)
+  await page.screenshot({ path: `${SHOT_DIR}/cmd-02-say-bubble.png` })
+
+  // dialog.open: 先确保对话框关闭(轮询稳定基线),排除模拟 Agent 残留对话
+  await injectCmd(page, 'dialog.close', {})
+  let beforeDlg = true
+  for (let i = 0; i < 20 && beforeDlg; i++) {
+    await sleep(150)
+    beforeDlg = await dialogVisible(page)
+  }
+  const dlg = await injectCmd(page, 'dialog.open', { agentName: 'cmd-injector', lines: ['第一句台词', '第二句台词'] })
+  check('dialog.open 注入 applied=true', dlg.applied === true, JSON.stringify(dlg))
+  // 轮询等待对话框出现(WS 下行 + Vue 过渡)
+  let opened = false
+  for (let i = 0; i < 20 && !opened; i++) {
+    await sleep(150)
+    opened = await dialogVisible(page)
+  }
+  check('dialog.open → 对话框出现', opened === true && beforeDlg === false, `before=${beforeDlg} after=${opened}`)
+  const dlgAgentName = await page.$eval('[data-hud="dialog"] .text-xs.font-bold', el => el.textContent.trim())
+  check('dialog.open → agentName 正确', dlgAgentName === 'cmd-injector', `got="${dlgAgentName}"`)
+  await page.screenshot({ path: `${SHOT_DIR}/cmd-03-dialog-open.png` })
+
+  // dialog.close: 轮询等待消失
+  const close = await injectCmd(page, 'dialog.close', {})
+  check('dialog.close 注入 applied=true', close.applied === true)
+  let closed = true
+  for (let i = 0; i < 20 && closed; i++) {
+    await sleep(150)
+    closed = await dialogVisible(page)
+  }
+  check('dialog.close → 对话框消失', closed === false)
+  await page.screenshot({ path: `${SHOT_DIR}/cmd-04-dialog-close.png` })
+
+  // agent.state: HUD 模式文本变化(取一个稳定值)
+  const stateBefore = await agentMode(page)
+  const state = await injectCmd(page, 'agent.state', { mode: 'wait', speed: 100 })
+  check('agent.state 注入 applied=true', state.applied === true, JSON.stringify(state))
+  await sleep(400)
+  const stateAfter = await agentMode(page)
+  check('agent.state → HUD 模式变化为"等待"', stateAfter.includes('等待'), `${stateBefore} → ${stateAfter}`)
+  await page.screenshot({ path: `${SHOT_DIR}/cmd-05-agent-state.png` })
+
+  // agent.face: 朝向(截图 + flipX)
+  const faceBefore = await agentPx(page)
+  await injectCmd(page, 'agent.face', { dir: 'left' })
+  await sleep(300)
+  const faceAfter = await agentPx(page)
+  check('agent.face → flipX 变为 true', faceAfter.flipX === true, `flipX: ${faceBefore.flipX}→${faceAfter.flipX}`)
+  await page.screenshot({ path: `${SHOT_DIR}/cmd-06-agent-face.png` })
+
+  // agent.move: 精灵位移
+  const moveBefore = await agentPx(page)
+  await injectCmd(page, 'agent.move', { dir: 'right', durationMs: 800 })
+  await sleep(900)
+  const moveAfter = await agentPx(page)
+  const moved = Math.abs(moveAfter.x - moveBefore.x) > 5
+  check('agent.move → 精灵 X 位移', moved, `x: ${moveBefore.x}→${moveAfter.x}`)
+  await page.screenshot({ path: `${SHOT_DIR}/cmd-07-agent-move.png` })
+
+  // ---------------- 2. 不规范下行指令 → 拒绝,前端无变化 ----------------
+  console.log('\n--- 2. 不规范下行指令 → 拒绝(execDownlink 守卫) ---')
+
+  // 先确保对话框关闭(轮询稳定基线)
+  await injectCmd(page, 'dialog.close', {})
+  let dlgClosedBefore = true
+  for (let i = 0; i < 20 && dlgClosedBefore; i++) {
+    await sleep(150)
+    dlgClosedBefore = await dialogVisible(page)
+  }
+
+  // 非 agentCallable 指令: session.ready
+  const forbid = await injectCmd(page, 'session.ready', { agentName: 'x', spawn: { x: 0, y: 0 } })
+  check('session.ready → FORBIDDEN', forbid.code === 'FORBIDDEN', JSON.stringify(forbid))
+
+  // 未知指令
+  const unknown = await injectCmd(page, 'totally.unknown', {})
+  check('未知指令 → UNKNOWN_COMMAND', unknown.code === 'UNKNOWN_COMMAND' || unknown.code === 'BAD_MESSAGE', JSON.stringify(unknown))
+
+  // 无效 payload: agent.move dir 非法
+  const invalidMove = await injectCmd(page, 'agent.move', { dir: 'sideways', durationMs: 100 })
+  check('agent.move 非法 dir → INVALID_PAYLOAD', invalidMove.code === 'INVALID_PAYLOAD', JSON.stringify(invalidMove))
+
+  // 无效 payload: dialog.open 缺 lines
+  const invalidDlg = await injectCmd(page, 'dialog.open', { agentName: 'x' })
+  check('dialog.open 缺 lines → INVALID_PAYLOAD', invalidDlg.code === 'INVALID_PAYLOAD', JSON.stringify(invalidDlg))
+
+  // 闭合 schema: agent.say 多余字段
+  const extra = await injectCmd(page, 'agent.say', { text: 'x', ttlMs: 100, rogue: 1 })
+  check('agent.say 多余字段 → INVALID_PAYLOAD', extra.code === 'INVALID_PAYLOAD', JSON.stringify(extra))
+
+  // 确认前端无异常变化:对话框仍关闭
+  const dlgClosedAfter = await dialogVisible(page)
+  check('不规范指令 → 前端对话框未异常打开', dlgClosedBefore === false && dlgClosedAfter === false)
+
+  await page.screenshot({ path: `${SHOT_DIR}/cmd-08-after-rejects.png` })
+  await browser.close()
+
+  console.log(`\n=== ${fail === 0 ? 'ALL PASS' : `${fail} FAILED`} (${pass}/${pass + fail}) ===`)
+  process.exit(fail === 0 ? 0 : 1)
+}
+
+main().catch((e) => {
+  console.error('RENDER VERIFY CRASH:', e)
+  process.exit(2)
+})

package/scripts/test-collab-e2e.mjs

@@ -0,0 +1,136 @@
+/**
+ * AgentTeam 协作守卫专项 e2e(mock):
+ *  - 防重复派发:同父同标题子任务在途 → 409 DUPLICATE_DISPATCH
+ *  - 规范化匹配:大小写/空白变体同样被拦
+ *  - 已完成且有交付 → 409 并附既有成果预览(lead 直接引用,不重做)
+ *  - 不同标题 → 正常派发
+ *  - 指纹节流下 mock 三模式回归(goal 快速一例)
+ * 运行:node scripts/test-collab-e2e.mjs(默认 http://127.0.0.1:3101)
+ */
+const BASE = process.env.AW_BASE ?? 'http://127.0.0.1:3101'
+
+let failures = 0
+let passed = 0
+const check = (name, ok, detail = '') => {
+  console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (ok) passed += 1
+  else failures += 1
+}
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+async function waitUntil(name, cond, timeoutMs = 60_000, intervalMs = 300) {
+  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)})`)
+}
+
+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 main() {
+  console.log(`目标: ${BASE}\n`)
+  const user = await api('POST', '/api/workshop/users/register', { body: { name: `collab-${Date.now().toString(36)}` } })
+  const token = user.data?.token
+  if (!token) throw new Error('注册失败')
+
+  // mock channel(lead + worker)
+  const ch = await api('POST', '/api/workshop/channels', {
+    body: { name: `collab-${Date.now().toString(36)}`, leadAgent: { name: 'lead', harness: 'mock' } },
+    token,
+  })
+  const channelId = ch.data.channelId
+  const leadId = ch.data.leadAgentId
+  const w = await api('POST', `/api/workshop/channels/${channelId}/agents`, { body: { name: 'worker', harness: 'mock', role: 'worker' }, token })
+  const workerId = w.data.id
+  const members = await api('GET', `/api/workshop/channels/${channelId}/agents`, { token })
+  const leadToken = (members.data ?? []).find(m => m.id === leadId)?.token
+  check('channel + lead/worker 就绪', !!leadToken && !!workerId)
+
+  // 父任务
+  const parent = await api('POST', `/api/workshop/channels/${channelId}/tasks`, {
+    body: { title: 'collab-guard-parent', description: '守卫专项父任务' },
+    token,
+  })
+  const parentId = parent.data.id
+  check('父任务提交', !!parentId)
+
+  // ① 首次派发成功
+  const d1 = await api('POST', `/api/workshop/tasks/${parentId}/dispatch`, {
+    body: { assigneeId: workerId, title: 'dup-test', description: '首次派发' },
+    token: leadToken,
+  })
+  check('① 首次派发成功', d1.code === 0, `code=${d1.code}`)
+
+  // ② 同标题重复派发(在途)→ 409
+  const d2 = await api('POST', `/api/workshop/tasks/${parentId}/dispatch`, {
+    body: { assigneeId: workerId, title: 'dup-test', description: '重复!' },
+    token: leadToken,
+  })
+  check('② 在途同标题重复派发被拒', d2.code === 'DUPLICATE_DISPATCH' || d2.status === 409, `code=${d2.code}`)
+  check('② 拒绝信息指明在途状态', String(d2.message ?? '').includes('已在执行中'))
+
+  // ③ 规范化变体(大小写+空白)同样被拦
+  const d3 = await api('POST', `/api/workshop/tasks/${parentId}/dispatch`, {
+    body: { assigneeId: workerId, title: '  DUP-Test  ', description: '变体' },
+    token: leadToken,
+  })
+  check('③ 大小写/空白变体被拦(规范化匹配)', d3.code === 'DUPLICATE_DISPATCH' || d3.status === 409)
+
+  // ④ 不同标题 → 正常
+  const d4 = await api('POST', `/api/workshop/tasks/${parentId}/dispatch`, {
+    body: { assigneeId: workerId, title: 'other-work', description: '不同工作' },
+    token: leadToken,
+  })
+  check('④ 不同标题正常派发', d4.code === 0)
+
+  // ⑤ 等 dup-test 完成(mock)→ 同标题再派发 → 409 且含交付预览
+  await waitUntil('dup-test 完成', async () => {
+    const tasks = await api('GET', `/api/workshop/channels/${channelId}/tasks`, { token })
+    const t = (tasks.data ?? []).find(x => x.title === 'dup-test')
+    return t?.state === 'COMPLETED' ? t : null
+  })
+  const d5 = await api('POST', `/api/workshop/tasks/${parentId}/dispatch`, {
+    body: { assigneeId: workerId, title: 'dup-test', description: '完成后重派' },
+    token: leadToken,
+  })
+  check('⑤ 已完成同标题重派被拒', d5.code === 'DUPLICATE_DISPATCH' || d5.status === 409)
+  check('⑤ 拒绝信息附既有成果提示', String(d5.message ?? '').includes('已完成并交付'))
+
+  // ⑥ 指纹节流下 goal 模式回归(快速)
+  const goal = await api('POST', `/api/workshop/channels/${channelId}/tasks`, {
+    body: {
+      title: 'goal-regress',
+      description: '[mode:goal][criteria:mock 完成] 指纹节流下的 goal 回归',
+    },
+    token,
+  })
+  const goalId = goal.data.id
+  const goalFinal = await waitUntil('goal 任务终态', async () => {
+    const tasks = await api('GET', `/api/workshop/channels/${channelId}/tasks`, { token })
+    const t = (tasks.data ?? []).find(x => x.id === goalId)
+    return ['COMPLETED', 'FAILED', 'CANCELED'].includes(t?.state ?? '') ? t.state : null
+  }, 90_000)
+  check('⑥ 指纹节流下 goal 模式正常完成', goalFinal === 'COMPLETED', `state=${goalFinal}`)
+
+  // 清理
+  await api('DELETE', `/api/workshop/channels/${channelId}`, { token })
+  console.log(`\n★ 结果: ${passed} passed, ${failures} failed`)
+  process.exit(failures === 0 ? 0 : 1)
+}
+
+main().catch((err) => {
+  console.error('e2e 异常:', err.message)
+  process.exit(1)
+})