agentworkshop 0.2.1

package/scripts/test-protocol.ts

@@ -0,0 +1,156 @@
+/**
+ * CMDParser 协议解析测试 + MCP 接缝验证(node + tsx 直跑,无浏览器)
+ *
+ * 覆盖:
+ *  1. 协议同步(assertProtocolSync):JSON 注册表 ↔ wire 类型键集合一致,example 自洽
+ *  2. CMDParser.parseUplink:合法/空/坏JSON/缺字段/未知指令/无效枚举/越界值
+ *  3. CMDParser.parseDownlink:合法 + 闭合结构(拒绝额外字段)
+ *  4. toMcpTools:agentCallable=true 的 downlink 即工具集,description 非空
+ *  5. GameSession.execDownlink:Agent 可调用指令注入成功,会话生命周期指令被 FORBIDDEN 拦截
+ */
+import {
+  assertProtocolSync,
+  CMDParser,
+  PROTOCOL,
+  toMcpTools,
+} from '../shared/game-protocol'
+import { gameSession } from '../server/services/game/session'
+import type { ServerToClient } from '../server/types/game'
+
+let failures = 0
+function check(name: string, ok: boolean, detail = ''): void {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (!ok) {
+    failures += 1
+  }
+}
+
+/** 假 WS peer:捕获下行指令(结构兼容 h3 peer) */
+class FakePeer {
+  sent: ServerToClient[] = []
+
+  send(data: string | Uint8Array): void {
+    this.sent.push(JSON.parse(typeof data === 'string' ? data : new TextDecoder().decode(data)))
+  }
+
+  close(): void {}
+}
+
+function testProtocolSync(): void {
+  console.log('\n--- 1. 协议同步 ---')
+  const report = assertProtocolSync()
+  check('downlink 键集合无漂移', report.unsyncedDownlink.length === 0, JSON.stringify(report.downlink))
+  check('uplink 键集合无漂移', report.unsyncedUplink.length === 0, JSON.stringify(report.uplink))
+  check('所有 example 自洽', report.badExamples.length === 0)
+  check('agentCallable 指令存在', report.downlink.some(k => PROTOCOL.downlink[k]?.agentCallable))
+}
+
+function testParseUplink(): void {
+  console.log('\n--- 2. CMDParser.parseUplink ---')
+
+  // 合法
+  const ok = CMDParser.parseUplink('{"type":"input.move","payload":{"dx":1,"dy":0}}')
+  check('合法 input.move 解析成功', ok.ok && ok.value.type === 'input.move')
+
+  // 空字符串
+  const empty = CMDParser.parseUplink('')
+  check('空字符串 → BAD_MESSAGE', !empty.ok && empty.error.code === 'BAD_MESSAGE')
+
+  // 坏 JSON
+  const bad = CMDParser.parseUplink('{not json')
+  check('坏 JSON → BAD_MESSAGE', !bad.ok && bad.error.code === 'BAD_MESSAGE')
+
+  // 缺 payload
+  const noPayload = CMDParser.parseUplink('{"type":"input.move","payload_dx":1}')
+  check('缺 payload → BAD_MESSAGE', !noPayload.ok && noPayload.error.code === 'BAD_MESSAGE')
+
+  // 未知指令
+  const unknown = CMDParser.parseUplink('{"type":"foo.bar","payload":{}}')
+  check('未知指令 → UNKNOWN_COMMAND', !unknown.ok && unknown.error.code === 'UNKNOWN_COMMAND')
+
+  // 无效枚举
+  const badEnum = CMDParser.parseUplink('{"type":"input.move","payload":{"dx":2,"dy":0}}')
+  check('dx=2 越界枚举 → INVALID_PAYLOAD', !badEnum.ok && badEnum.error.code === 'INVALID_PAYLOAD',
+    badEnum.ok ? '' : badEnum.error.path)
+
+  // 缺必填
+  const missing = CMDParser.parseUplink('{"type":"player.pos","payload":{"x":1,"y":2}}')
+  check('缺 tileX/tileY → INVALID_PAYLOAD', !missing.ok && missing.error.code === 'INVALID_PAYLOAD')
+}
+
+function testParseDownlink(): void {
+  console.log('\n--- 3. CMDParser.parseDownlink ---')
+
+  const ok = CMDParser.parseDownlink('{"type":"agent.say","payload":{"text":"hi","ttlMs":1000}}')
+  check('合法 agent.say 解析成功', ok.ok && ok.value.type === 'agent.say')
+
+  // 闭合结构:拒绝额外字段
+  const extra = CMDParser.parseDownlink('{"type":"agent.face","payload":{"dir":"down","extra":1}}')
+  check('额外字段被拒绝(闭合 schema)', !extra.ok && extra.error.code === 'INVALID_PAYLOAD')
+
+  // 对象类型指令:缺必填
+  const missing = CMDParser.parseDownlink('{"type":"session.ready","payload":{"agentName":"x"}}')
+  check('session.ready 缺 spawn → INVALID_PAYLOAD', !missing.ok && missing.error.code === 'INVALID_PAYLOAD')
+}
+
+function testMcpTools(): void {
+  console.log('\n--- 4. MCP 工具词表 ---')
+  const tools = toMcpTools()
+  const names = tools.map(t => t.name)
+  check('工具数 > 0', tools.length > 0, names.join(','))
+
+  const allCallable = names.every(n => PROTOCOL.downlink[n]?.agentCallable === true)
+  check('全部工具对应 agentCallable=true', allCallable)
+
+  const allDescribed = tools.every(t => t.description.length > 0 && t.inputSchema.type === 'object')
+  check('每个工具有 description + object inputSchema', allDescribed)
+
+  // 关键 Agent 工具应在册
+  check('agent.move 在工具集', names.includes('agent.move'))
+  check('agent.say 在工具集', names.includes('agent.say'))
+  check('dialog.open 在工具集', names.includes('dialog.open'))
+
+  // 非工具:会话生命周期 + 协议内部指令不应可调用
+  check('session.ready 不在工具集', !names.includes('session.ready'))
+  check('dialog.advance 不在工具集', !names.includes('dialog.advance'))
+  check('error 不在工具集', !names.includes('error'))
+}
+
+async function testExecDownlink(): Promise<void> {
+  console.log('\n--- 5. GameSession.execDownlink(MCP 接缝) ---')
+  const peer = new FakePeer()
+  gameSession.connect(peer)
+  // connect 后首两条为 session.ready / agent.state,execDownlink 的新指令在其后追加
+  const baseline = peer.sent.length
+
+  // Agent 可调用指令:注入成功 + 下行广播
+  const res = gameSession.execDownlink('agent.say', { text: '来自 Agent', ttlMs: 1500 })
+  check('execDownlink agent.say 成功', res.ok)
+  check('agent.say 下发到 peer', peer.sent.length === baseline + 1
+  && peer.sent[peer.sent.length - 1]!.type === 'agent.say', `sent=${peer.sent.length}`)
+
+  // 非 agentCallable 指令:FORBIDDEN
+  const forbidden = gameSession.execDownlink('session.ready', { agentName: 'x', spawn: { x: 0, y: 0 } })
+  check('session.ready 被 FORBIDDEN 拦截', !forbidden.ok && forbidden.error.code === 'FORBIDDEN')
+
+  // 无效 payload:校验失败
+  const invalid = gameSession.execDownlink('agent.move', { dir: 'sideways', durationMs: 100 })
+  check('agent.move 非法 dir → 校验失败', !invalid.ok && invalid.error.code === 'INVALID_PAYLOAD')
+  gameSession.stop()
+}
+
+async function main(): Promise<void> {
+  testProtocolSync()
+  testParseUplink()
+  testParseDownlink()
+  testMcpTools()
+  await testExecDownlink()
+
+  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-real-scenario.mjs

@@ -0,0 +1,290 @@
+/**
+ * 真实场景端到端实测:『产品 v2.5 发布准备团队』(omp + glm-5-turbo):
+ *  - 场景:双 worker 协作 —— 撰写员产出发布说明草稿 → 检查员核对并给 GO/NO-GO
+ *  - API 断言:场景/角色 prompt 注入、双 worker 参与作业、防重复、goal 结语、
+ *              中文+要点交付、邮件协作留痕、supervise 节流
+ *  - UI 监控(puppeteer):实时观测时间线块累积(单调不减)、类型分发(task/artifact/
+ *              message 等分块渲染)、无重复渲染、交付块可展开、header 航迹存在
+ * 运行:node scripts/test-real-scenario.mjs
+ */
+import puppeteer from 'puppeteer-core'
+import { mkdirSync } from 'node:fs'
+
+const BASE = process.env.AW_BASE ?? 'http://127.0.0.1:3101'
+const PROVIDER = 'zhipu-coding-plan'
+const MODEL = 'glm-5-turbo'
+const EDGE = process.env.EDGE_PATH ?? 'C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe'
+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(() => ({}))) }
+}
+
+const SCENARIO = [
+  '本团队为「Acme 产品 v2.5」发布做准备。所有 Agent 必须遵守:',
+  '1. 所有交付使用中文,结构化要点(- 开头),不超过 120 字',
+  '2. 每份最终交付的最后一行必须是指定标记 [READY] 或 [BLOCKED]',
+  '3. 结论必须明确,不含糊;不编造数据,引用上游产出时保留其标记',
+].join('\n')
+
+async function main() {
+  mkdirSync('data/shots', { recursive: true })
+
+  // ═══ 1. 组队(API) ═══
+  const email = `release-e2e-${Date.now().toString(36)}@test.local`
+  const reg = await api('POST', '/api/users/register', { body: { name: `release-e2e-${Date.now().toString(36)}`, email, password: 'Passw0rd!123' } })
+  const token = reg.data?.token ?? reg.token
+  if (!token) throw new Error('注册失败')
+
+  const ch = await api('POST', '/api/workshop/channels', {
+    body: {
+      name: 'v2.5-release-team',
+      scenarioPrompt: SCENARIO,
+      leadAgent: { name: 'release-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 w1 = await api('POST', `/api/workshop/channels/${channelId}/agents`, {
+    body: {
+      name: 'draft-writer',
+      harness: 'omp',
+      role: 'worker',
+      config: {
+        provider: PROVIDER,
+        model: MODEL,
+        systemPromptPrefix: 'You are a senior release-note writer. You ALWAYS write deliverables as Chinese markdown bullet points (- item), concise and factual. Your final line is a status marker like [READY].',
+      },
+    },
+    token,
+  })
+  const w2 = await api('POST', `/api/workshop/channels/${channelId}/agents`, {
+    body: {
+      name: 'release-checker',
+      harness: 'omp',
+      role: 'worker',
+      config: {
+        provider: PROVIDER,
+        model: MODEL,
+        systemPromptPrefix: 'You are a release readiness checker. You verify upstream deliverables and always end with an explicit GO or NO-GO verdict line in Chinese, followed by the status marker [READY] or [BLOCKED].',
+      },
+    },
+    token,
+  })
+  if (w1.code !== 0 || w2.code !== 0) throw new Error('worker 创建失败')
+  check('团队就绪(omp lead + 撰写员 + 检查员)', true, `channel=${channelId.slice(0, 8)}`)
+
+  const ws = await api('POST', '/api/workshop/workspaces', { body: { name: 'release-ws' }, token })
+  await api('POST', `/api/workshop/workspaces/${ws.data.id}/channels/${channelId}`, { token })
+
+  const tasksOf = async () => (await api('GET', `/api/workshop/channels/${channelId}/tasks`, { token })).data ?? []
+  const eventsOf = async () => (await api('GET', `/api/workshop/channels/${channelId}/events?limit=800`, { token })).data?.items ?? []
+
+  // ═══ 2. 提交 GOAL 任务并打开前端监控 ═══
+  const task = await api('POST', `/api/workshop/channels/${channelId}/tasks`, {
+    body: {
+      title: 'v2.5-release-readiness',
+      description: '[mode:goal][criteria:最终交付包含中文发布说明要点与明确的 GO 或 NO-GO 结论] 先让撰写员 draft-writer 产出 v2.5 发布说明草稿(3-5 个要点,末行 [READY]);再让检查员 release-checker 核对草稿,给出 GO/NO-GO 结论(末行 [READY] 或 [BLOCKED])。你汇总两者的产出为最终交付。',
+    },
+    token,
+  })
+  const parentId = task.data?.id
+  if (!parentId) throw new Error('任务提交失败')
+  console.log('  任务已提交,打开前端监控…')
+
+  // ── puppeteer 前端实时监控 ──
+  const browser = await puppeteer.launch({
+    executablePath: EDGE,
+    headless: 'new',
+    args: ['--no-sandbox', '--disable-gpu', '--window-size=1500,900'],
+    defaultViewport: { width: 1500, height: 900 },
+  })
+  const page = await browser.newPage()
+  page.on('pageerror', e => console.log('  [pageerror]', e.message.slice(0, 160)))
+
+  await page.goto(`${BASE}/workshop`, { waitUntil: 'domcontentloaded' })
+  await sleep(1800)
+  // 登录门 → 表单登录(点击进入控制台后等 SPA 导航完成再校验 URL)
+  let inConsole = false
+  for (let attempt = 0; attempt < 2 && !inConsole; attempt++) {
+    for (const b of await page.$$('button')) {
+      const txt = (await b.evaluate(el => el.textContent) || '').trim()
+      if (txt.includes('进入控制台')) {
+        await b.click()
+        await sleep(2500)
+        inConsole = page.url().includes('/workshop/w/')
+        break
+      }
+    }
+    if (inConsole) break
+    const emailInput = await page.$('input[type="email"]')
+    if (!emailInput) break
+    await emailInput.type(email, { delay: 8 })
+    const pwd = await page.$('input[type="password"]')
+    await pwd.type('Passw0rd!123', { delay: 8 })
+    for (const b of await page.$$('button')) {
+      const txt = (await b.evaluate(el => el.textContent) || '').trim()
+      if (txt.replace(/\s/g, '') === '登录') {
+        await b.click()
+        break
+      }
+    }
+    await sleep(2200)
+  }
+  check('前端登录并进入控制台', inConsole, page.url().slice(-40))
+  await sleep(2500)
+
+  // header 航迹(新功能)存在
+  const trailNodes = await page.$$eval('.trail-node', els => els.length).catch(() => 0)
+  check('header 航迹导航渲染', trailNodes >= 1, `nodes=${trailNodes}`)
+
+  // 监控循环:块数单调不减 + 类型采样
+  const samples = []
+  const kinds = new Set()
+  let monotonic = true
+  const deadline = Date.now() + 720_000
+  let finalState = ''
+  while (Date.now() < deadline) {
+    const snap = await page.evaluate(() => ({
+      blocks: document.querySelectorAll('.event-block').length,
+      kinds: [...document.querySelectorAll('.event-block .kind')].map(e => e.textContent.trim()),
+    })).catch(() => null)
+    if (snap) {
+      if (samples.length && snap.blocks < samples[samples.length - 1].blocks) monotonic = false
+      samples.push({ t: Date.now(), blocks: snap.blocks })
+      snap.kinds.forEach(k => kinds.add(k))
+    }
+    const st = (await tasksOf().catch(() => [])).find(t => t.id === parentId)?.state ?? ''
+    if (['COMPLETED', 'FAILED', 'CANCELED'].includes(st)) {
+      finalState = st
+      break
+    }
+    await sleep(4000)
+  }
+  // 宽限:子任务全完成、父任务最终汇总轮进行中的常见尾延(模型延迟波动)
+  if (!finalState) {
+    for (let i = 0; i < 12; i++) {
+      const st = (await tasksOf().catch(() => [])).find(t => t.id === parentId)?.state ?? ''
+      if (['COMPLETED', 'FAILED', 'CANCELED'].includes(st)) {
+        finalState = st
+        break
+      }
+      await sleep(5000)
+    }
+  }
+  const blockSamples = samples.map(s => s.blocks)
+  check('时间线实时块渲染(有块且持续更新)', samples.length > 0 && Math.max(...blockSamples, 0) >= 8, `peak=${Math.max(...blockSamples, 0)}, 采样${samples.length}次`)
+  check('块数单调不减(无重复消费/重置)', monotonic, `${blockSamples.slice(0, 8).join('→')}…`)
+  check('类型化分发渲染(task/artifact 等各自成块)', kinds.has('task') && kinds.has('artifact'), [...kinds].join(','))
+  check('成员/生命周期事件入轨', kinds.has('team') || kinds.has('state') || kinds.has('event'), '')
+
+  if (samples.length > 2) await page.screenshot({ path: 'data/shots/real-scenario-live.png' })
+
+  // ═══ 3. API 侧协作逻辑断言 ═══
+  check('goal 父任务完成', finalState === 'COMPLETED', `state=${finalState}`)
+
+  const tasks = await tasksOf()
+  const children = tasks.filter(t => t.parentId === parentId)
+  check('子任务派发(≥2,两名 worker 均参与)', children.length >= 2 && new Set(children.map(c => c.assigneeId)).size >= 2, `children=${children.length}, assignees=${new Set(children.map(c => c.assigneeId)).size}`)
+
+  const active = children.filter(c => ['ASSIGNED', 'WORKING', 'WAITING'].includes(c.state))
+  const titles = children.map(c => c.title.replace(/\s+/g, ' ').trim().toLowerCase())
+  const dupCount = titles.filter((t, i) => titles.indexOf(t) !== i).length
+  // 同标题重派仅在"前次完成且无交付"时被守卫放行(有交付会 409 拒绝,由 test-collab-e2e 专项证明);
+  // 此处断言终态无在途 + 记录重派数供观察
+  check('无并发在途重复(终态在途为 0)', active.length === 0, `active=${active.length}, 同标题重派=${dupCount}(设计允许:前次无交付)`)
+
+  const doneChildren = children.filter(c => c.state === 'COMPLETED' && (c.artifacts?.length ?? 0) > 0)
+  check('worker 子任务完成且带交付', doneChildren.length >= 2, `done=${doneChildren.length}`)
+
+  const parent = tasks.find(t => t.id === parentId)
+  const parentText = JSON.stringify(parent?.artifacts ?? '')
+  check('父任务含 goal 结语交付(GO/NO-GO 判定)', (parent?.artifacts?.length ?? 0) > 0 && /GO/i.test(parentText), parentText.slice(0, 100))
+
+  // 场景遵守抽查:worker 交付含中文
+  const cjk = s => /[\u4e00-\u9fff]/.test(s)
+  const childText = JSON.stringify(doneChildren.map(c => c.artifacts))
+  check('交付使用中文(场景规范 1)', cjk(childText), '')
+
+  // 邮件协作留痕:agent 间通信事件(agent.message / agent.status.message / a2a.message)
+  const evs = await eventsOf()
+  const members = (await api('GET', `/api/workshop/channels/${channelId}/agents`, { token })).data ?? []
+  const leadId = (members.find(m => m.role === 'lead') ?? {}).id ?? ch.data.leadAgentId
+  const mailEvents = evs.filter(e => ['agent.message', 'agent.status.message', 'a2a.message'].includes(e.type)).length
+  check('邮件流含协作记录(团队知情)', mailEvents >= 4, `mail events=${mailEvents}`)
+
+  // supervise 回合信号:lead 的 status.message(派发指令 + supervise 摘要);
+  // 健康节奏 ≈ 8-10 条/分钟(每子任务状态迁移触发一轮);指纹节流防的是无变化忙轮转
+  // (那会是数百条)。界限 60 = 健康值的 2 倍余量,仍能捕获失控场景。
+  const leadSuperviseMsgs = evs.filter(e => e.type === 'agent.status.message' && e.agentId === leadId).length
+  const byAgent = evs
+    .filter(e => e.type === 'agent.message' || e.type === 'agent.status.message')
+    .reduce((acc, e) => {
+      const k = e.agentId?.slice(0, 8) ?? 'system'
+      acc[k] = (acc[k] ?? 0) + 1
+      return acc
+    }, {})
+  check('supervise 轮数受节流控制(lead 状态摘要)', leadSuperviseMsgs < 60, `lead supervise=${leadSuperviseMsgs}, 消息分布=${JSON.stringify(byAgent)}, 总事件=${evs.length}`)
+
+  // ═══ 4. 前端最终渲染断言 ═══
+  await sleep(2500)
+  const finalBlocks = await page.$$eval('.event-block', els => els.length).catch(() => 0)
+  const artifactCards = await page.$$eval('.event-block', els =>
+    els.filter(e => e.querySelector('.kind')?.textContent.trim() === 'artifact').length,
+  ).catch(() => 0)
+  const errorBlocks = await page.$$eval('.event-block', els =>
+    els.filter(e => e.querySelector('.kind')?.textContent.trim() === 'error').length,
+  ).catch(() => -1)
+  check('终态块渲染(数量稳定)', finalBlocks >= artifactCards && finalBlocks > 0, `blocks=${finalBlocks}, artifacts=${artifactCards}`)
+  check('交付块(artifact)渲染', artifactCards >= 2, `=${artifactCards}`)
+  check('无 error 块', errorBlocks === 0, `=${errorBlocks}`)
+  await page.screenshot({ path: 'data/shots/real-scenario-final.png' })
+  await browser.close()
+
+  // ═══ 5. 失败诊断转储(任务状态时间线 + Agent 消息节选) ═══
+  if (failures > 0) {
+    console.log('\n━━━ 失败诊断(channel 保留待查)━━━')
+    console.log(`channelId: ${channelId}`)
+    const all = await tasksOf()
+    for (const t of all) {
+      console.log(`  [task] ${t.id.slice(0, 8)} parent=${t.parentId?.slice(0, 8) ?? '-'} state=${t.state} progress=${t.progress}% title=${t.title}`)
+    }
+    for (const e of evs.filter(e => e.type === 'task.status').slice(-16)) {
+      const p = e.payload ?? {}
+      console.log(`  [status] seq=${e.seq} ${e.at.slice(11, 19)} ${p.state} task=${p.taskId ?? e.taskId ?? '-'}`)
+    }
+    for (const e of evs.filter(e => e.type === 'agent.message').slice(-8)) {
+      const p = e.payload ?? {}
+      const text = String(p.parts ?? p.text ?? '').slice(0, 150)
+      console.log(`  [msg] seq=${e.seq} agent=${e.agentId?.slice(0, 8)} ${text}`)
+    }
+  }
+  else {
+    // 清理
+    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(() => {})
+    }
+    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-route-reason.mjs

@@ -0,0 +1,111 @@
+/**
+ * 路由决策留痕 + 能力画像数据基础(koda 后端设计借鉴)确定性测试:
+ *  - lead 经 agents 端点创建(响应含实例 token)→ MCP tools/call 携带 Bearer
+ *  - workshop.task.dispatch 带 route_reason → 落库 → 任务列表返回
+ *  - task.status 事件载荷携带 routeReason/createdAt(前端"事件即实体" + 能力画像数据基础)
+ * 运行:node scripts/test-route-reason.mjs
+ */
+const BASE = process.env.AW_BASE ?? 'http://127.0.0.1:3101'
+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(() => ({}))) }
+}
+
+const mcp = async (sid, id, method, params, agentToken) => {
+  const headers = { 'content-type': 'application/json', 'accept': 'application/json, text/event-stream' }
+  if (sid) headers['mcp-session-id'] = sid
+  if (agentToken) headers.authorization = `Bearer ${agentToken}`
+  const res = await fetch(`${BASE}/api/mcp/workshop`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+  })
+  return { sid: res.headers.get('mcp-session-id'), text: await res.text() }
+}
+
+async function main() {
+  const REASON = 'specialty: mock worker; queue empty; deterministic test'
+
+  // ── 组队(mock;lead 经 agents 端点创建拿 token)──
+  const user = await api('POST', '/api/workshop/users/register', { body: { name: `route-${Date.now().toString(36)}` } })
+  const token = user.data?.token
+  const ch = await api('POST', '/api/workshop/channels', { body: { name: 'route-reason-check' }, token })
+  if (ch.code !== 0) throw new Error('channel 创建失败')
+  const channelId = ch.data.channelId
+  const lead = await api('POST', `/api/workshop/channels/${channelId}/agents`, {
+    body: { name: 'lead', harness: 'mock', role: 'lead' },
+    token,
+  })
+  const worker = await api('POST', `/api/workshop/channels/${channelId}/agents`, {
+    body: { name: 'worker', harness: 'mock', role: 'worker' },
+    token,
+  })
+  const leadToken = lead.data?.token
+  const workerId = worker.data?.id
+  check('lead 实例 token 下发(MCP caller)', Boolean(leadToken) && Boolean(workerId))
+
+  // ── 父任务 + MCP dispatch 带 route_reason ──
+  const task = await api('POST', `/api/workshop/channels/${channelId}/tasks`, {
+    body: { title: 'route-parent', description: 'mock parent for route reason check' },
+    token,
+  })
+  const parentId = task.data?.id
+  check('父任务提交', Boolean(parentId), parentId?.slice(0, 8))
+
+  const init = await mcp(null, 1, 'initialize', {
+    protocolVersion: '2025-03-26',
+    capabilities: {},
+    clientInfo: { name: 'route-e2e', version: '1.0.0' },
+  }, leadToken)
+  const sid = init.sid
+  check('MCP 会话建立(agent caller)', Boolean(sid))
+
+  const call = await mcp(sid, 2, 'tools/call', {
+    name: 'workshop.task.dispatch',
+    arguments: {
+      parentTaskId: parentId,
+      assigneeId: workerId,
+      title: 'routed-child',
+      description: 'child with auditable routing decision',
+      routeReason: REASON,
+    },
+  }, leadToken)
+  const okCall = !/"isError":\s*true/.test(call.text) && !call.text.includes('SCOPE_VIOLATION')
+  check('MCP dispatch(route_reason)执行', okCall, okCall ? '' : call.text.slice(0, 140))
+  if (sid) await fetch(`${BASE}/api/mcp/workshop?sessionId=${sid}`, { method: 'DELETE' }).catch(() => {})
+
+  // ── 断言:任务行带 routeReason + 画像数据基础 ──
+  await sleep(1200)
+  const tasks = (await api('GET', `/api/workshop/channels/${channelId}/tasks`, { token })).data ?? []
+  const child = tasks.find(t => t.title === 'routed-child')
+  check('任务列表返回 routeReason', child?.routeReason === REASON, child?.routeReason ?? '(missing)')
+  check('DTO 含 createdAt/updatedAt(能力画像数据基础)', Boolean(child?.createdAt) && Boolean(child?.updatedAt), '')
+
+  // ── 断言:task.status 事件载荷携带 routeReason/createdAt ──
+  const evs = (await api('GET', `/api/workshop/channels/${channelId}/events?limit=200`, { token })).data?.items ?? []
+  const evReason = evs.find(e => e.type === 'task.status' && (e.payload ?? {}).routeReason !== undefined)
+  const evCreated = evs.find(e => e.type === 'task.status' && (e.payload ?? {}).createdAt !== undefined)
+  check('task.status 事件携带 routeReason(事件即实体)', Boolean(evReason))
+  check('task.status 事件携带 createdAt', Boolean(evCreated))
+
+  // 清理
+  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)
+})