agentworkshop 0.2.1

package/scripts/test-workspace-api.ts

@@ -0,0 +1,329 @@
+/**
+ * Workspace + 后端 API 集成测试
+ *
+ * 测试矩阵:
+ *  A. workspace 创建与注入:创建 channel → 默认 workspace 目录生成 → agent cwd 注入验证
+ *  B. 自定义 workspace:显式指定 workspace → 目录创建 → omp 子进程在该目录执行(read 工具可见)
+ *  C. channel 管理 API:getChannel/getChannelWorkspace/updateChannelWorkspace
+ *  D. 消息 API:sendImmediateMessage 优先级路由验证
+ *
+ * 运行: npx tsx scripts/test-workspace-api.ts
+ */
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { openWorkshopDb } from '../server/services/workshop/db/database'
+import { createChannelRepo } from '../server/services/workshop/db/channel.repo'
+import { createAgentRepo } from '../server/services/workshop/db/agent.repo'
+import { createChannelAgentRepo } from '../server/services/workshop/db/channel-agent.repo'
+import { createTaskRepo } from '../server/services/workshop/db/task.repo'
+import { createMemoryRepo } from '../server/services/workshop/db/memory.repo'
+import { createChannelEventRepo } from '../server/services/workshop/db/channel-event.repo'
+import { createTeamRepo } from '../server/services/workshop/db/team.repo'
+import { createTeamMemberRepo } from '../server/services/workshop/db/team-member.repo'
+import { createMessageRepo } from '../server/services/workshop/db/message.repo'
+import { createSubscriptionRepo } from '../server/services/workshop/db/subscription.repo'
+import { createAgentChannelManager } from '../server/services/workshop/runtime/manager'
+import type { AgentChannelManager } from '../server/services/workshop/runtime/manager'
+import { createAgentImpl } from '../server/services/workshop/agents/factory'
+import { OmpRpcAgentImpl } from '../server/services/workshop/agents/omp-agent'
+
+let failures = 0
+let testCount = 0
+function check(name: string, ok: boolean, detail = ''): void {
+  testCount += 1
+  console.log(`  ${ok ? '✅' : '❌'} ${name}${detail ? ` — ${detail}` : ''}`)
+  if (!ok) failures += 1
+}
+
+const sleep = (ms: number) => new Promise<void>(r => setTimeout(r, ms))
+
+async function waitUntil(cond: () => boolean | Promise<boolean>, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    if (await cond()) return true
+    await sleep(100)
+  }
+  return false
+}
+
+interface SetupResult {
+  manager: AgentChannelManager
+  db: ReturnType<typeof openWorkshopDb>
+  repos: ReturnType<typeof buildRepos>
+}
+
+function buildRepos(db: ReturnType<typeof openWorkshopDb>) {
+  return {
+    channels: createChannelRepo(db),
+    agents: createAgentRepo(db),
+    channelAgents: createChannelAgentRepo(db),
+    messages: createMessageRepo(db),
+    subscriptions: createSubscriptionRepo(db),
+    tasks: createTaskRepo(db),
+    memories: createMemoryRepo(db),
+
+    channelEvents: createChannelEventRepo(db),
+
+    teams: createTeamRepo(db),
+
+    teamMembers: createTeamMemberRepo(db),
+  }
+}
+
+function setup(): SetupResult {
+  const db = openWorkshopDb(':memory:')
+  const repos = buildRepos(db)
+  const manager = createAgentChannelManager({ repos, implFactory: createAgentImpl, db })
+  return { manager, db, repos }
+}
+
+function attachScheduler(manager: AgentChannelManager, channelId: string, tickMs = 200): void {
+  manager.ensureChannelActive(channelId, { tickMs, stallMs: 60_000 })
+}
+
+async function disposeAll(manager: AgentChannelManager): Promise<void> {
+  await manager.shutdown()
+}
+
+// ===== 测试 A: 默认 workspace 生成与 cwd 注入 =====
+async function testDefaultWorkspace(): Promise<void> {
+  console.log('\n━━━ 测试 A: 默认 workspace 生成与 cwd 注入 ━━━')
+
+  const { manager, db } = setup()
+  const tmpRoot = resolve(process.cwd(), 'data', 'workspaces')
+  let channelId = ''
+
+  try {
+    const ch = await manager.createChannel({
+      name: 'workspace 测试',
+      leadAgent: { name: 'lead', harness: 'mock', config: {} },
+    })
+    channelId = ch.channelId
+
+    // 1. workspace 默认生成在 data/workspaces/<channelId>
+    check('createChannel 返回 workspace', ch.workspace.length > 0, ch.workspace)
+    check('默认 workspace 路径在 data/workspaces 下', ch.workspace.startsWith(tmpRoot), ch.workspace)
+    check('workspace 目录已创建', existsSync(ch.workspace))
+
+    // 2. agent cwd 注入验证:创建 worker → 内部 implFactory 收到的 config.cwd = workspace
+    let capturedCwd = ''
+    const probeFactory = (agent: Parameters<typeof createAgentImpl>[0]) => {
+      capturedCwd = (agent.config as { cwd?: string }).cwd ?? ''
+      return createAgentImpl(agent)
+    }
+    // 重建 manager 使用探测工厂
+    const db2 = openWorkshopDb(':memory:')
+    const repos2 = buildRepos(db2)
+    const manager2 = createAgentChannelManager({ repos: repos2, implFactory: probeFactory, db: db2 })
+    const ch2 = await manager2.createChannel({
+      name: 'cwd 探测',
+      leadAgent: { name: 'lead', harness: 'mock', config: { delayMs: 20 } },
+    })
+    await manager2.addAgentToChannel({ channelId: ch2.channelId, agentId: (await manager2.createAgent({ name: 'w', harness: 'mock', config: { delayMs: 20 } })).id, role: 'worker' })
+    // 懒加载:显式激活触发 lead 装配
+    manager2.ensureChannelActive(ch2.channelId, { tickMs: 20 })
+    check('lead 装配时注入 cwd', capturedCwd === ch2.workspace, `cwd=${capturedCwd}`)
+    // 提交任务触发 worker dispatch 装配
+    await manager2.submitChannelTask({ channelId: ch2.channelId, title: 't' })
+    await sleep(300)
+    check('worker 装配时注入 cwd', capturedCwd === ch2.workspace, `cwd=${capturedCwd}`)
+
+    // 3. getChannel 返回 workspace
+    const detail = await manager.getChannel(channelId)
+    check('getChannel 返回 workspace', detail.workspace === ch.workspace)
+    check('getChannel 返回 agents', detail.agents.length === 1)
+
+    await disposeAll(manager2)
+    db2.close()
+  }
+  finally {
+    await disposeAll(manager)
+    db.close()
+    // 清理测试生成的 workspace 目录
+    if (channelId) {
+      const dir = resolve(tmpRoot, channelId)
+      if (existsSync(dir)) rmSync(dir, { recursive: true, force: true })
+    }
+  }
+}
+
+// ===== 测试 B: 自定义 workspace + omp 真实 cwd 约束 =====
+async function testCustomWorkspaceOmp(): Promise<void> {
+  console.log('\n━━━ 测试 B: 自定义 workspace + omp 真实 cwd 约束 ━━━')
+
+  const { manager, db } = setup()
+  // 自定义 workspace:temp 目录
+  const customDir = resolve(process.cwd(), '.tmp-test-ws')
+  mkdirSync(customDir, { recursive: true })
+  // 在自定义目录写一个标记文件,omp 用 read 应该能读到
+  writeFileSync(resolve(customDir, 'MARKER.txt'), 'workspace-marker-content-12345', 'utf8')
+
+  try {
+    const ch = await manager.createChannel({
+      name: 'omp cwd 测试',
+      workspace: customDir,
+      leadAgent: { name: 'lead', harness: 'omp', config: {} },
+    })
+    check('自定义 workspace 生效', ch.workspace === customDir, ch.workspace)
+
+    const wTpl = await manager.createAgent({ name: 'w', harness: 'omp', config: {} })
+    await manager.addAgentToChannel({ channelId: ch.channelId, agentId: wTpl.id, role: 'worker' })
+    attachScheduler(manager, ch.channelId, 500)
+
+    // 提交任务:要求 worker 读取 MARKER.txt(只有 cwd 正确才能读到)
+    const engine = (manager as unknown as {
+      getTaskEngine(): {
+        get(id: string): { state: string, artifacts: Array<{ parts: Array<{ text?: string }> }> } | undefined
+        list(channelId: string): Array<{ parentId: string | null, state: string }>
+      }
+    }).getTaskEngine()
+
+    const task = await manager.submitChannelTask({
+      channelId: ch.channelId,
+      title: '读取 MARKER.txt 内容',
+      description: '读取当前工作目录下的 MARKER.txt 文件,报告其完整内容,然后完成任务。',
+    })
+
+    await waitUntil(() => {
+      const t = engine.get(task.id)
+      return t?.state === 'COMPLETED' || t?.state === 'CANCELED' || t?.state === 'FAILED'
+    }, 240_000)
+
+    const final = engine.get(task.id)
+    check('omp 任务完成', final?.state === 'COMPLETED', `state=${final?.state}`)
+
+    // 验证 worker 产物包含标记内容(证明 omp 在 customDir 下执行)
+    const children = engine.list(ch.channelId).filter(t => t.parentId === task.id)
+    const allText = [...(final?.artifacts ?? []), ...children.flatMap(c => (c as { artifacts?: Array<{ parts: Array<{ text?: string }> }> }).artifacts ?? [])]
+      .flatMap(a => a.parts)
+      .map(p => p.text ?? '')
+      .join(' ')
+    check('omp 读取到 MARKER.txt 内容(cwd 约束生效)', allText.includes('workspace-marker-content-12345'), `内容片段: ${allText.slice(0, 80)}…`)
+  }
+  finally {
+    await disposeAll(manager)
+    db.close()
+    rmSync(customDir, { recursive: true, force: true })
+  }
+}
+
+// ===== 测试 C: workspace 更新 API =====
+async function testWorkspaceUpdate(): Promise<void> {
+  console.log('\n━━━ 测试 C: workspace 更新 ━━━')
+
+  const { manager, db } = setup()
+  try {
+    const ch = await manager.createChannel({ name: 'update 测试' })
+    const dir1 = resolve(process.cwd(), '.tmp-ws-a')
+    const dir2 = resolve(process.cwd(), '.tmp-ws-b')
+
+    const updated = await manager.updateChannelWorkspace(ch.channelId, dir1)
+    check('workspace 更新生效', updated.workspace === dir1)
+    check('更新后目录存在', existsSync(dir1))
+
+    const updated2 = await manager.updateChannelWorkspace(ch.channelId, dir2)
+    check('workspace 二次更新', updated2.workspace === dir2)
+    check('二次更新目录存在', existsSync(dir2))
+
+    // 404 场景
+    let threw = false
+    try {
+      await manager.updateChannelWorkspace('nonexistent', dir1)
+    }
+    catch {
+      threw = true
+    }
+    check('不存在的 channel 更新抛 404', threw)
+  }
+  finally {
+    await disposeAll(manager)
+    db.close()
+    rmSync(resolve(process.cwd(), '.tmp-ws-a'), { recursive: true, force: true })
+    rmSync(resolve(process.cwd(), '.tmp-ws-b'), { recursive: true, force: true })
+  }
+}
+
+// ===== 测试 D: 消息 API 优先级路由 =====
+async function testMessagePriorityRouting(): Promise<void> {
+  console.log('\n━━━ 测试 D: 消息 API 优先级路由 ━━━')
+
+  const { manager, db, repos } = setup()
+  try {
+    const ch = await manager.createChannel({
+      name: '消息路由测试',
+      leadAgent: { name: 'lead', harness: 'mock', config: { delayMs: 100 } },
+    })
+    const w1 = await manager.addAgentToChannel({ channelId: ch.channelId, agentId: (await manager.createAgent({ name: 'w1', harness: 'mock', config: { delayMs: 100 } })).id, role: 'worker' })
+    attachScheduler(manager, ch.channelId)
+
+    // immediate 消息:metadata 带 immediate
+    const imm = await manager.sendImmediateMessage({
+      channelId: ch.channelId,
+      fromAgentId: '',
+      toAgentId: w1.id,
+      parts: [{ text: '实时消息' }],
+    })
+    check('immediate 消息带 priority metadata', imm.metadata?.['x-aw-msg-priority'] === 'immediate')
+
+    // task 消息(经 sendA2A)
+    const lead = (await manager.listChannelAgents(ch.channelId)).find(a => a.role === 'lead')!
+    const tsk = await manager.sendA2A(ch.channelId, lead.id, {
+      toAgentId: w1.id,
+      parts: [{ text: '队列消息' }],
+      metadata: { 'x-aw-msg-priority': 'task' },
+    })
+    check('task 消息带 priority metadata', tsk.metadata?.['x-aw-msg-priority'] === 'task')
+
+    // 等消息被消费
+    await sleep(300)
+    const recent = repos.messages.listRecentByChannel(ch.channelId, 10)
+    const w1Msgs = recent.filter(m => m.toAgentId === w1.id && m.partsJson.includes('消息'))
+    check('消息已投递到 w1', w1Msgs.length >= 2, `消息数=${w1Msgs.length}`)
+  }
+  finally {
+    await disposeAll(manager)
+    db.close()
+  }
+}
+
+// ===== 测试 E: OmpRpcAgentImpl cwd 直传验证 =====
+async function testOmpImplCwdDirect(): Promise<void> {
+  console.log('\n━━━ 测试 E: OmpRpcAgentImpl cwd 配置直传 ━━━')
+
+  const customDir = resolve(process.cwd(), '.tmp-impl-cwd')
+  mkdirSync(customDir, { recursive: true })
+  writeFileSync(resolve(customDir, 'IMPL.txt'), 'impl-cwd-marker', 'utf8')
+
+  try {
+    // 直接构造 impl,验证 config.cwd 传入 OmpRpcClient
+    const impl = new OmpRpcAgentImpl({ cwd: customDir, name: 'test', role: 'worker' })
+    const config = (impl as unknown as { config: { cwd?: string } }).config
+    check('OmpRpcAgentImpl 接受 cwd 配置', config.cwd === customDir, config.cwd)
+  }
+  finally {
+    rmSync(customDir, { recursive: true, force: true })
+  }
+}
+
+// ===== main =====
+async function main(): Promise<void> {
+  console.log('╔════════════════════════════════════════════════════════════╗')
+  console.log('║  Workspace + API 集成测试                                   ║')
+  console.log('╚════════════════════════════════════════════════════════════╝')
+
+  await testDefaultWorkspace()
+  await testWorkspaceUpdate()
+  await testMessagePriorityRouting()
+  await testOmpImplCwdDirect()
+  await testCustomWorkspaceOmp() // 真实 omp,最慢放最后
+
+  console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
+  console.log(`  ${failures === 0 ? `🎉 全部通过(${testCount} 项检查)` : `❌ ${failures}/${testCount} 项失败`}`)
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
+  process.exit(failures === 0 ? 0 : 1)
+}
+
+main().catch((e) => {
+  console.error('测试异常:', e)
+  process.exit(1)
+})

package/scripts/test-ws-aep.mjs

@@ -0,0 +1,187 @@
+/**
+ * AEP v1 协议级测试(对运行中的 dev server):
+ * ① 信封:{v,type,seq,at,channelId,payload} 全字段;snapshot 含 agents/tasks/queue/messages
+ * ② 事件直推:提交任务 → task.status/task.progress/a2a.artifact/a2a.message/agent.status 无轮询延迟到达
+ * ③ seq 单调递增且连续
+ * ④ 断线续传:断开期间发生事件 → sub{lastSeq} 重放缺失段(无快照帧、seq 连续)
+ * ⑤ 缓冲窗外/游标缺失 → channel.snapshot 全量对齐兜底
+ * ⑥ 多 channel 单连接:sub/unsub 复用一条 WS
+ * ⑦ ping/pong 心跳;非法上行 → error
+ * 运行: node scripts/test-ws-aep.mjs(需 server 已启动,AW_E2E_BASE 可覆盖)
+ */
+const BASE = process.env.AW_E2E_BASE ?? 'http://localhost:3000'
+const WS_BASE = BASE.replace(/^http/, 'ws')
+
+let failures = 0
+function 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))
+// 用户级隔离:注册测试用户;管理面 API 全程携带用户 token
+const __user = await fetch(BASE + '/api/workshop/users/register', {
+  method: 'POST', headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ name: 'e2e-' + Math.random().toString(36).slice(2, 10) }),
+}).then(r => r.json()).catch(() => null)
+const __userToken = __user?.data?.token
+if (!__userToken) {
+  console.error('用户注册失败')
+  process.exit(1)
+}
+
+async function api(method, path, arg) {
+  // 调用侧统一 { body: {...} } 包装;无 body 的 GET 直传 path 后无第三参
+  const body = arg && typeof arg === 'object' && 'body' in arg ? arg.body : arg
+  const res = await fetch(`${BASE}/api/workshop${path}`, {
+    method,
+    headers: {
+      authorization: `Bearer ${__userToken}`,
+      ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  })
+  const json = await res.json().catch(() => null)
+  return { status: res.status, code: json?.code, data: json?.data }
+}
+
+/** WS 收集器:url 省省时连裸端点(纯上行 sub 模式) */
+function openWs(url = `${WS_BASE}/api/workshop/ws`) {
+  const frames = []
+  const ws = new WebSocket(url)
+  const opened = new Promise((resolve, reject) => {
+    ws.onopen = () => resolve(true)
+    ws.onerror = e => reject(new Error(`ws error: ${e?.message ?? e}`))
+  })
+  ws.onmessage = ev => frames.push(JSON.parse(ev.data))
+  return { ws, frames, opened }
+}
+
+const seqsOf = frames => frames.map(f => f.seq).filter(n => Number.isFinite(n))
+const isMonotonic = seqs => seqs.every((s, i) => i === 0 || s > seqs[i - 1])
+
+async function main() {
+  // ── 前置:channel + lead + 2 worker(mock);首次请求撞上 Nitro 构建窗口时重试 ──
+  let ch = null
+  for (let i = 0; i < 5 && !ch?.data?.channelId; i++) {
+    ch = await api('POST', '/channels', { body: { name: `aep-${Date.now()}` } })
+    if (!ch?.data?.channelId) {
+      console.log(`[debug] 第 ${i + 1} 次失败: ${JSON.stringify(ch).slice(0, 200)}`)
+      await sleep(1000)
+    }
+  }
+  if (!ch?.data?.channelId) throw new Error(`channel 创建失败: ${JSON.stringify(ch).slice(0, 200)}`)
+  const channelId = ch.data.channelId
+  const mk = (name, role) => api('POST', `/channels/${channelId}/agents`, { body: { name, harness: 'mock', role } })
+  await mk('aep-lead', 'lead')
+  await mk('aep-w1', 'worker')
+  await mk('aep-w2', 'worker')
+
+  console.log('=== ① 信封与快照 ===')
+  const c1 = openWs(`${WS_BASE}/api/workshop/ws?channelId=${channelId}&token=${encodeURIComponent(__userToken)}`)
+  await c1.opened
+  const snap = await (async () => {
+    const deadline = Date.now() + 5000
+    while (Date.now() < deadline) {
+      const f = c1.frames.find(f => f.type === 'channel.snapshot')
+      if (f) return f
+      await sleep(50)
+    }
+    return null
+  })()
+  check('连接即收 channel.snapshot', !!snap)
+  check('信封字段完整(v/type/seq/at/channelId/payload)', snap?.v === 1 && !!snap.type && typeof snap.seq === 'number' && !!snap.at && snap.channelId === channelId && !!snap.payload)
+  check('快照含 agents(3)/queue(3)/tasks/messages', snap?.payload.agents?.length === 3 && snap?.payload.queue?.length === 3 && Array.isArray(snap?.payload.tasks) && Array.isArray(snap?.payload.messages))
+
+  console.log('\n=== ② 事件直推(无轮询)===')
+  const t1 = await api('POST', `/channels/${channelId}/tasks`, { body: { title: 'AEP 直推验证', description: 'mock 执行' } })
+  check('任务提交 200', t1.status === 200)
+  const sawComplete = await (async () => {
+    const deadline = Date.now() + 20_000
+    while (Date.now() < deadline) {
+      const done = c1.frames.some(f => f.type === 'task.status' && f.payload?.taskId === t1.data.id && f.payload?.state === 'COMPLETED')
+      if (done) return true
+      await sleep(100)
+    }
+    return false
+  })()
+  const types = [...new Set(c1.frames.map(f => f.type))]
+  check('任务全生命周期事件直推至 COMPLETED', sawComplete)
+  check('事件类型覆盖(status/progress/artifact/message)', ['task.status', 'task.progress'].every(t => types.includes(t)), types.join(','))
+  const a2a = c1.frames.filter(f => f.type === 'a2a.message')
+  check('a2a.message 投递事件(route 汇流:lead assign)', a2a.length >= 1, `n=${a2a.length}`)
+
+  console.log('\n=== ③ seq 单调 ===')
+  const seqs = seqsOf(c1.frames.filter(f => f.type !== 'pong'))
+  check('seq 严格单调递增', isMonotonic(seqs), `last=${seqs.at(-1)}`)
+
+  console.log('\n=== ④ 断线续传(lastSeq 重放)===')
+  const lastSeq = seqs.at(-1) ?? 0
+  c1.ws.close()
+  await sleep(300)
+  // 断开期间提交第二个任务(事件进入服务端缓冲)
+  const t2 = await api('POST', `/channels/${channelId}/tasks`, { body: { title: '断线期间任务', description: '重放验证' } })
+  const t2done = await (async () => {
+    const deadline = Date.now() + 20_000
+    while (Date.now() < deadline) {
+      const r = await api('GET', `/channels/${channelId}/tasks`)
+      const t = r.data?.find(x => x.id === t2.data?.id)
+      if (t?.state === 'COMPLETED') return true
+      await sleep(200)
+    }
+    return false
+  })()
+  check('断线期间任务完成(事件入缓冲)', t2done)
+  const c2 = openWs()
+  await c2.opened
+  c2.ws.send(JSON.stringify({ type: 'sub', channelId, lastSeq, token: __userToken }))
+  await sleep(500)
+  const replay = c2.frames.filter(f => f.type !== 'pong' && f.type !== 'channel.snapshot')
+  const replaySeqs = seqsOf(replay)
+  check('重放帧 seq 从 lastSeq+1 连续', replaySeqs.length > 0 && replaySeqs[0] === lastSeq + 1 && replaySeqs.every((s, i) => i === 0 || s === replaySeqs[i - 1] + 1),
+    `first=${replaySeqs[0]} last=${replaySeqs.at(-1)} (lastSeq=${lastSeq})`)
+  check('重放含断线期间任务事件', replay.some(f => f.type === 'task.status' && f.payload?.taskId === t2.data?.id))
+  check('无快照帧(重放路径不走全量)', !c2.frames.some(f => f.type === 'channel.snapshot'))
+
+  console.log('\n=== ⑤ 全量对齐兜底(lastSeq 缺失) ===')
+  const c3 = openWs()
+  await c3.opened
+  c3.ws.send(JSON.stringify({ type: 'sub', channelId, token: __userToken })) // 无 lastSeq → snapshot
+  await sleep(500)
+  check('无 lastSeq → channel.snapshot 对齐', c3.frames.some(f => f.type === 'channel.snapshot'))
+
+  console.log('\n=== ⑥ 多 channel 单连接(sub/unsub) ===')
+  const ch2 = await api('POST', '/channels', { body: { name: `aep2-${Date.now()}` } })
+  c3.ws.send(JSON.stringify({ type: 'sub', channelId: ch2.data.channelId, token: __userToken }))
+  await sleep(300)
+  await api('POST', `/channels/${ch2.data.channelId}/agents`, { body: { name: 'solo-lead', harness: 'mock', role: 'lead' } })
+  await api('POST', `/channels/${ch2.data.channelId}/tasks`, { body: { title: '第二通道任务' } })
+  await sleep(1500)
+  check('同一连接收到第二 channel 事件', c3.frames.some(f => f.channelId === ch2.data.channelId && f.type !== 'channel.snapshot'))
+  c3.ws.send(JSON.stringify({ type: 'unsub', channelId: ch2.data.channelId }))
+  await sleep(200)
+  const beforeUnsub = c3.frames.filter(f => f.channelId === ch2.data.channelId).length
+  await sleep(800)
+  check('unsub 后不再收到该 channel 事件', c3.frames.filter(f => f.channelId === ch2.data.channelId).length === beforeUnsub)
+
+  console.log('\n=== ⑦ 心跳与非法上行 ===')
+  c3.ws.send(JSON.stringify({ type: 'ping' }))
+  await sleep(300)
+  check('ping → pong', c3.frames.some(f => f.type === 'pong'))
+  c3.ws.send(JSON.stringify({ type: 'nonsense' }))
+  await sleep(300)
+  check('非法上行 → error UNSUPPORTED_UPLINK', c3.frames.some(f => f.type === 'error' && f.payload?.code === 'UNSUPPORTED_UPLINK'))
+  c3.ws.close()
+  c2.ws.close()
+
+  // ── 清理 ──
+  await api('DELETE', `/channels/${channelId}`)
+  await api('DELETE', `/channels/${ch2.data.channelId}`)
+  console.log(`\n${failures === 0 ? 'ALL PASS' : `${failures} FAILED`}`)
+  process.exit(failures === 0 ? 0 : 1)
+}
+
+main().catch((e) => {
+  console.error('AEP 测试异常:', e)
+  process.exit(1)
+})

package/scripts/test-ws-protocol.ts

@@ -0,0 +1,134 @@
+/**
+ * WS 协议解析验证 — 通过真实 WebSocket 连接验证 CMDParser 在消息边界的行为
+ *
+ * 验证矩阵:
+ *  A. 上行规范指令: session.join / player.pos / agent.pos / input.move → 服务端消费(无 error 回传)
+ *  B. 上行不规范指令: 坏JSON / 缺payload / 未知指令 / 越界枚举 → 服务端回传 error 指令(BAD_MESSAGE/UNKNOWN_COMMAND/INVALID_PAYLOAD)
+ *  C. 服务行规范下行: 自动 session.ready / agent.state 均可被前端 CMDParser 解析
+ *
+ * 仅验证"线上解析"层(前后端消息边界);"前端渲染"由浏览器截图单独验证。
+ * 使用 Node 内置全局 WebSocket(Node 22+),无需第三方依赖。
+ */
+/** 业务 WS 鉴权:先注册临时用户拿 token(?token= 查询参数) */
+async function bootstrapToken(): Promise<string> {
+  const base = (process.env.WS_URL ?? 'ws://localhost:3000').replace(/^ws/, 'http').replace(/\/api\/game\/ws$/, '')
+  const r = await fetch(`${base}/api/users/register`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ name: `wsp-${Date.now().toString(36)}`, email: `wsp-${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 as string
+}
+const USER_TOKEN = await bootstrapToken()
+const WS_URL = `${process.env.WS_URL ?? 'ws://localhost:3000/api/game/ws'}?token=${encodeURIComponent(USER_TOKEN)}`
+let pass = 0
+let fail = 0
+function check(name: string, ok: boolean, detail = ''): void {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (ok) pass += 1
+  else fail += 1
+}
+
+interface WireMsg { type: string, payload: Record<string, unknown> }
+
+type WsLike = InstanceType<typeof WebSocket>
+
+function connect(): Promise<WsLike> {
+  const { promise, resolve, reject } = Promise.withResolvers<WsLike>()
+  const ws = new WebSocket(WS_URL)
+  ws.addEventListener('open', () => resolve(ws as WsLike))
+  ws.addEventListener('error', () => reject(new Error('ws connect failed')))
+  return promise
+}
+
+/** 收集指定时间窗内的下行消息 */
+function collect(ws: WsLike, ms: number): Promise<WireMsg[]> {
+  const msgs: WireMsg[] = []
+  const { promise, resolve } = Promise.withResolvers<WireMsg[]>()
+  const handler = (ev: MessageEvent) => {
+    try {
+      msgs.push(JSON.parse(ev.data as string))
+    }
+    catch {
+      msgs.push({ type: '__unparseable__', payload: {} })
+    }
+  }
+  ws.addEventListener('message', handler)
+  setTimeout(() => {
+    ws.removeEventListener('message', handler)
+    resolve(msgs)
+  }, ms)
+  return promise
+}
+
+/** 发送上行并等待回传(收集 200ms) */
+function sendAndCollect(ws: WsLike, raw: string): Promise<WireMsg[]> {
+  const p = collect(ws, 200)
+  ws.send(raw)
+  return p
+}
+
+async function main(): Promise<void> {
+  console.log(`\n=== WS 协议解析验证 (${WS_URL}) ===`)
+  const ws = await connect()
+  console.log('connected\n')
+
+  // 连接后服务端自动下发 session.ready + agent.state,验证"规范下行可被解析"
+  const initial = await collect(ws, 500)
+  const types = initial.map(m => m.type)
+  check('连接收到 session.ready', types.includes('session.ready'), JSON.stringify(types))
+  check('连接收到 agent.state', types.includes('agent.state'))
+  check('session.ready 有 agentName + spawn', (() => {
+    const m = initial.find(x => x.type === 'session.ready')
+    return !!m && typeof m.payload.agentName === 'string' && !!m.payload.spawn
+  })())
+
+  // ---------------- A. 上行规范指令(应被消费,无 error) ----------------
+  console.log('\n--- A. 上行规范指令(应无 error 回传) ---')
+
+  const a1 = await sendAndCollect(ws, JSON.stringify({ type: 'player.pos', payload: { x: 700, y: 650, tileX: 21, tileY: 20 } }))
+  check('player.pos 规范 → 无 error', a1.every(m => m.type !== 'error'), JSON.stringify(a1.map(m => m.type)))
+
+  const a2 = await sendAndCollect(ws, JSON.stringify({ type: 'agent.pos', payload: { x: 720, y: 656 } }))
+  check('agent.pos 规范 → 无 error', a2.every(m => m.type !== 'error'))
+
+  const a3 = await sendAndCollect(ws, JSON.stringify({ type: 'input.move', payload: { dx: 1, dy: 0 } }))
+  check('input.move 规范(dx=1) → 无 error', a3.every(m => m.type !== 'error'))
+
+  const a4 = await sendAndCollect(ws, JSON.stringify({ type: 'input.move', payload: { dx: -1, dy: 0 } }))
+  check('input.move 规范(dx=-1) → 无 error', a4.every(m => m.type !== 'error'))
+
+  // ---------------- B. 上行不规范指令(应回传对应 error) ----------------
+  console.log('\n--- B. 上行不规范指令(应回传 error) ---')
+
+  const b1 = await sendAndCollect(ws, '{not valid json')
+  check('坏JSON → error(BAD_MESSAGE)', b1.some(m => m.type === 'error' && m.payload.code === 'BAD_MESSAGE'), JSON.stringify(b1))
+
+  const b2 = await sendAndCollect(ws, JSON.stringify({ type: 'input.move', payload_dx: 1 }))
+  check('缺payload → error(BAD_MESSAGE)', b2.some(m => m.type === 'error' && m.payload.code === 'BAD_MESSAGE'))
+
+  const b3 = await sendAndCollect(ws, JSON.stringify({ type: 'totally.unknown', payload: {} }))
+  check('未知指令 → error(UNKNOWN_COMMAND)', b3.some(m => m.type === 'error' && m.payload.code === 'UNKNOWN_COMMAND'))
+
+  const b4 = await sendAndCollect(ws, JSON.stringify({ type: 'input.move', payload: { dx: 5, dy: 0 } }))
+  check('dx=5越界枚举 → error(INVALID_PAYLOAD)', b4.some(m => m.type === 'error' && m.payload.code === 'INVALID_PAYLOAD'), JSON.stringify(b4))
+
+  const b5 = await sendAndCollect(ws, JSON.stringify({ type: 'player.pos', payload: { x: 1, y: 2 } }))
+  check('player.pos 缺tileX/tileY → error(INVALID_PAYLOAD)', b5.some(m => m.type === 'error' && m.payload.code === 'INVALID_PAYLOAD'))
+
+  const b6 = await sendAndCollect(ws, JSON.stringify({ type: 'input.move', payload: { dx: 'left', dy: 0 } }))
+  check('dx=字符串类型错误 → error(INVALID_PAYLOAD)', b6.some(m => m.type === 'error' && m.payload.code === 'INVALID_PAYLOAD'))
+
+  const b7 = await sendAndCollect(ws, JSON.stringify({ type: 'session.join', payload: { agentId: 'x', extra: 1 } }))
+  check('额外字段(闭合schema) → error(INVALID_PAYLOAD)', b7.some(m => m.type === 'error' && m.payload.code === 'INVALID_PAYLOAD'))
+
+  ws.close()
+  console.log(`\n=== ${fail === 0 ? 'ALL PASS' : `${fail} FAILED`} (${pass}/${pass + fail}) ===`)
+  process.exit(fail === 0 ? 0 : 1)
+}
+
+main().catch((e) => {
+  console.error('WS 验证失败:', e)
+  process.exit(1)
+})