agentworkshop 0.2.1

package/scripts/verify-page-smoke.mjs

@@ -0,0 +1,87 @@
+/**
+ * 页面冒烟:无头浏览器打开 AgentWorkShop 首页 / 小镇(3D),截图留档。
+ * 运行: node scripts/verify-page-smoke.mjs   (env: AW_PAGE_TOKEN 可选自动登录 token)
+ */
+import puppeteer from 'puppeteer-core'
+import { mkdirSync } from 'node:fs'
+
+const BASE = process.env.AW_PAGE_BASE ?? 'http://127.0.0.1:3000'
+const TOKEN = process.env.AW_PAGE_TOKEN ?? ''
+const OUT = 'docs/audit/screenshots'
+mkdirSync(OUT, { recursive: true })
+
+const browser = await puppeteer.launch({
+  executablePath: process.env.AW_BROWSER ?? 'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+  headless: 'new',
+  args: ['--no-sandbox', '--disable-gpu', '--window-size=1560,1040'],
+})
+const page = await browser.newPage()
+await page.setViewport({ width: 1560, height: 1040 })
+
+let ok = false, err = ''
+try {
+  await page.goto(BASE, { waitUntil: 'networkidle2', timeout: 45000 })
+  await page.screenshot({ path: `${OUT}/home.png` })
+  console.log('home ok, title=' + await page.title())
+
+  if (TOKEN) {
+    // 会话 = 'token' cookie + session-restore 插件恢复登录态
+    await page.setCookie({ name: 'token', value: TOKEN, domain: '127.0.0.1', path: '/' })
+    await page.goto(`${BASE}/town`, { waitUntil: 'domcontentloaded', timeout: 60000 })
+    // 轮询等待场景就绪(WS/快照/布局异步;避免 networkidle2 被长连接卡死)
+    for (let i = 0; i < 30; i++) {
+      const ready = await page.evaluate(() => !!window.__town?.scene)
+      if (ready) break
+      await new Promise(r => setTimeout(r, 1000))
+    }
+    await new Promise(r => setTimeout(r, 5000))
+    const state = await page.evaluate(() => ({
+      logged: !!window.__town?.scene,
+      title: document.title,
+      hasEmpty: !!document.querySelector('[data-hud="town-empty"]'),
+    }))
+    console.log('town state:', JSON.stringify(state))
+    await page.screenshot({ path: `${OUT}/town-3d.png` })
+
+    // 选中第一个 Agent → 触发员工会话台(大字号会话窗)
+    const agentSel = await page.evaluate(() => {
+      const s = window.__town?.scene
+      if (!s) return null
+      const agent = s.agents?.values?.().next?.().value
+      if (!agent) return null
+      s.setSelected?.({ kind: 'agent', id: agent.agentId })
+      return { id: agent.agentId, name: agent.name }
+    })
+    console.log('agent selected:', JSON.stringify(agentSel))
+
+    // 注入实时对话(演示头顶大字号气泡 + 员工会话台实时消费)
+    const demoCh = await fetch(`${BASE}/api/workshop/channels`, { headers: { authorization: `Bearer ${TOKEN}` } }).then(r => r.json())
+    const targetCh = (demoCh.data ?? [])[0]
+    if (targetCh?.id) {
+      const agents = await fetch(`${BASE}/api/workshop/channels/${targetCh.id}/agents`, { headers: { authorization: `Bearer ${TOKEN}` } }).then(r => r.json())
+      const lead = (agents.data ?? []).find(a => a.role === 'lead')
+      const workers = (agents.data ?? []).filter(a => a.role === 'worker')
+      for (let i = 0; i < 3; i++) {
+        const to = workers[i % workers.length]
+        if (lead?.token && to?.id) {
+          await fetch(`${BASE}/api/workshop/a2a/send`, {
+            method: 'POST',
+            headers: { 'authorization': `Bearer ${lead.token}`, 'content-type': 'application/json' },
+            body: JSON.stringify({ toAgentId: to.id, parts: [{ text: `第 ${i + 1} 批巡检数据已收到:泵组 ${i + 1} 号运行正常,继续跟进。` }] }),
+          }).catch(() => {})
+        }
+      }
+    }
+    await new Promise(r => setTimeout(r, 2600))
+    await page.screenshot({ path: `${OUT}/town-agent-chat.png` })
+  }
+  else {
+    await page.goto(`${BASE}/workshop`, { waitUntil: 'networkidle2', timeout: 30000 })
+    await page.screenshot({ path: `${OUT}/workshop.png` })
+  }
+  ok = true
+}
+catch (e) { err = String(e) }
+await browser.close()
+console.log(ok ? 'SMOKE OK' : `SMOKE FAIL: ${err}`)
+process.exit(ok ? 0 : 1)

package/scripts/verify-ws-events.mjs

@@ -0,0 +1,123 @@
+/**
+ * AEP 事件流实时验证(真实 WebSocket + REST)——验证「发给前端渲染的 event」端到端:
+ *  - 连接 /api/workshop/ws(带用户 token)→ sub 指定 channel
+ *  - 首帧应是 channel.snapshot(agents/tasks/queue/messages 实体基线)
+ *  - REST 提交任务 → 依次收到 agent.status / task.status / task.progress / a2a.artifact / a2a.message
+ *  - 信封完整性:v/type/seq/at/channelId/payload;seq 单调递增
+ * 运行:node scripts/verify-ws-events.mjs [--base http://127.0.0.1:3000]
+ */
+const BASE = (process.argv.find(a => a.startsWith('--base='))?.slice(7) ?? 'http://127.0.0.1:3000')
+const API = BASE + '/api/workshop'
+const WS = BASE.replace(/^http/, 'ws') + '/api/workshop/ws'
+
+let pass = 0, fail = 0
+const check = (name, ok, detail = '') => {
+  console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  ok ? pass++ : fail++
+}
+
+async function api(method, path, { token, body } = {}) {
+  const headers = { 'content-type': 'application/json' }
+  if (token) headers.authorization = `Bearer ${token}`
+  const res = await fetch(`${API}${path}`, { method, headers, body: body ? JSON.stringify(body) : undefined })
+  return { status: res.status, json: await res.json().catch(() => null) }
+}
+
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+async function waitTaskTerminal(taskId, token, timeoutMs = 20_000) {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    const { json } = await api('GET', `/tasks/${taskId}`, { token })
+    if (['COMPLETED', 'FAILED', 'CANCELED'].includes(json?.data?.state ?? '')) return json?.data
+    await sleep(250)
+  }
+  return null
+}
+
+let __token = null
+let __channel = null
+
+async function main() {
+  console.log('━━━ AEP 事件流实时验证(真实 WS)→', WS, '━━━')
+  const user = await api('POST', '/users/register', { body: { name: 'ws-events-' + Math.random().toString(36).slice(2, 9) } })
+  const token = user.json?.data?.token
+  __token = token
+  check('用户注册/拿 token', !!token)
+
+  const ch = await api('POST', '/channels', { token, body: { name: 'ws-events-check' } })
+  const CH = ch.json?.data?.channelId
+  __channel = CH
+  check('channel 创建', !!CH)
+  await api('POST', `/channels/${CH}/agents`, { token, body: { name: 'ws-lead', harness: 'mock', role: 'lead' } })
+  const worker = await api('POST', `/channels/${CH}/agents`, { token, body: { name: 'ws-worker', harness: 'mock', role: 'worker' } })
+  const WORKER = worker.json?.data?.id
+  check('lead/worker 实例创建', !!WORKER)
+
+  // 连接 WS + sub
+  const ws = new WebSocket(WS)
+  const frames = []
+  const seen = new Set()
+  let snapshot = null
+  ws.onmessage = (ev) => {
+    const e = JSON.parse(ev.data)
+    frames.push(e)
+    if (e.type === 'channel.snapshot' && e.channelId === CH) snapshot = e
+    seen.add(e.type)
+  }
+  await new Promise((resolve, reject) => {
+    ws.onopen = resolve
+    ws.onerror = reject
+  })
+  ws.send(JSON.stringify({ type: 'sub', channelId: CH, token }))
+  await sleep(800)
+
+  check('sub 后收到 channel.snapshot', !!snapshot)
+  check('snapshot 含 channel 元信息', !!snapshot?.payload?.channel && snapshot.payload.channel.id === CH)
+  check('snapshot agents 含 lead/worker', (snapshot?.payload?.agents ?? []).some(a => a.role === 'lead') && (snapshot?.payload?.agents ?? []).some(a => a.role === 'worker'))
+  check('snapshot 信封合法(v/seq/at/channelId)', snapshot?.v === 1 && typeof snapshot.seq === 'number' && typeof snapshot.at === 'string')
+
+  // 提交任务 → 事件流
+  const task = await api('POST', `/channels/${CH}/tasks`, { token, body: { title: 'ws-event-task', description: '触发事件流' } })
+  const TASK = task.json?.data?.id
+  check('任务提交', !!TASK)
+
+  const final = await waitTaskTerminal(TASK, token)
+  check('任务 COMPLETED', final?.state === 'COMPLETED', final?.state ?? '')
+  await sleep(800) // 等尾部事件
+
+  ws.send(JSON.stringify({ type: 'unsub', channelId: CH }))
+  ws.close()
+
+  const channelFrames = frames.filter(f => f.channelId === CH)
+  check('收到 agent.status', channelFrames.some(f => f.type === 'agent.status'), `n=${channelFrames.filter(f => f.type === 'agent.status').length}`)
+  check('收到 task.status', channelFrames.some(f => f.type === 'task.status'))
+  check('收到 task.progress', channelFrames.some(f => f.type === 'task.progress'))
+  const artifacts = channelFrames.filter(f => f.type === 'a2a.artifact')
+  check('收到 a2a.artifact', artifacts.length > 0, `n=${artifacts.length}`)
+  const taskStatus = channelFrames.find(f => f.type === 'task.status')
+  check('task.status 载荷含 state/taskId', !!taskStatus?.payload?.state && !!taskStatus?.payload?.taskId)
+  check('task.status 载荷含 assigneeId(事件即实体)', typeof taskStatus?.payload?.assigneeId === 'string')
+  // seq 单调性:同一 channel 内 seq 严格递增
+  let monotonic = true
+  let prev = -1
+  for (const f of channelFrames) {
+    if (f.seq <= prev) {
+      monotonic = false
+      break
+    }
+    prev = f.seq
+  }
+  check('channel 内 seq 单调递增', monotonic, `frames=${channelFrames.length}`)
+  check('含超额投递的 a2a.message', channelFrames.some(f => f.type === 'a2a.message'))
+
+  console.log(`\n  [事件样本] ${channelFrames.slice(0, 4).map(f => `${f.seq}:${f.type}(state=${f.payload?.state ?? '-'})`).join('  ')}`)
+  console.log(`\n━━━ 结果: PASS=${pass} FAIL=${fail} ━━━`)
+  process.exit(fail === 0 ? 0 : 1)
+}
+
+try {
+  await main()
+}
+finally {
+  if (__channel && __token) await api('DELETE', `/channels/${__channel}`, { token: __token }).catch(() => {})
+}

package/scripts/ws-test.mjs

@@ -0,0 +1,176 @@
+// -*- coding: utf-8 -*-
+// WS 实时链路实测(需 Node ≥ 22,原生 WebSocket;node scripts/ws-test.mjs)。
+//
+// 针对运行中的 dev/prod 服务验证 AEP v1 协议全链路:
+//  1. 鉴权:无 token 订阅被拒(USER_UNAUTHORIZED);有效 token 通过。
+//  2. 快照对齐:无游标 sub → channel.snapshot(实体基线)。
+//  3. ping/pong。
+//  4. 实时推送:REST 注入人类消息 → WS 收到 a2a.message 帧;验证:
+//     - 信封 agentId 归属(人类消息不归属收件 Agent —— 修复回归测试)
+//     - seq 单调递增。
+//  5. 断线续传:携带 lastSeq 重订 → 重放缺失段(seq > lastSeq,不重复、不跳号)。
+//  6. 落库对账:WS 收到的帧在 REST /events 中按同序存在(DB 事实源)。
+import { env } from 'node:process'
+
+const BASE = env.AW_BASE ?? 'http://127.0.0.1:3002'
+const TOKEN = env.AW_TOKEN ?? 'ut-636e563104b844b591de8aadf6071aea'
+const CID = env.AW_CID ?? '4b4d742d-2e27-4f2d-a2c9-c1ce9ceb0411'
+const WS_BASE = BASE.replace(/^http/, 'ws')
+
+let failures = 0
+const check = (name, ok, detail = '') => {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (!ok) failures += 1
+}
+
+async function api(method, path, body) {
+  const res = await fetch(BASE + path, {
+    method,
+    headers: { 'authorization': `Bearer ${TOKEN}`, 'content-type': 'application/json' },
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  const d = await res.json()
+  if (d && typeof d === 'object' && 'code' in d && d.code !== 0 && d.code !== 'ok') {
+    throw new Error(`${path} -> ${JSON.stringify(d).slice(0, 200)}`)
+  }
+  return d?.data ?? d
+}
+
+/** 打开一条 WS 并等待 open */
+function openWs(query) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(`${WS_BASE}/api/workshop/ws${query}`)
+    ws.addEventListener('open', () => resolve(ws), { once: true })
+    ws.addEventListener('error', () => reject(new Error('ws connect failed')), { once: true })
+  })
+}
+
+/** 收帧直到谓词命中(超时抛错);返回命中帧与期间全部帧 */
+function waitFrame(ws, pred, timeoutMs = 8000) {
+  return new Promise((resolve, reject) => {
+    const seen = []
+    const timer = setTimeout(() => {
+      cleanup()
+      reject(new Error(`等帧超时(${timeoutMs}ms);已收 ${seen.length} 帧`))
+    }, timeoutMs)
+    const onMsg = (ev) => {
+      let e
+      try {
+        e = JSON.parse(ev.data)
+      }
+      catch { return }
+      seen.push(e)
+      if (pred(e, seen)) {
+        cleanup()
+        resolve({ frame: e, seen })
+      }
+    }
+    const cleanup = () => {
+      clearTimeout(timer)
+      ws.removeEventListener('message', onMsg)
+    }
+    ws.addEventListener('message', onMsg)
+  })
+}
+
+const send = (ws, obj) => ws.send(JSON.stringify(obj))
+
+async function main() {
+  // ---- 0. 前置:channel 存在 ----
+  const events0 = await api('GET', `/api/workshop/channels/${CID}/events?limit=1`)
+  const maxSeq0 = events0.maxSeq ?? 0
+  console.log(`基线 maxSeq=${maxSeq0}`)
+
+  // ---- 1. 鉴权 ----
+  {
+    const ws = await openWs('')
+    send(ws, { type: 'sub', channelId: CID }) // 无 token 字段
+    const { frame } = await waitFrame(ws, e => e.type === 'error' && e.payload?.code === 'USER_UNAUTHORIZED')
+    check('无 token sub 被拒(USER_UNAUTHORIZED)', frame.payload.code === 'USER_UNAUTHORIZED')
+    ws.close()
+  }
+
+  // ---- 2/3. 快照 + ping/pong ----
+  const ws = await openWs(`?token=${encodeURIComponent(TOKEN)}`)
+  send(ws, { type: 'sub', channelId: CID, token: TOKEN })
+  {
+    const { frame } = await waitFrame(ws, e => e.type === 'channel.snapshot')
+    const p = frame.payload ?? {}
+    check('无游标 sub → channel.snapshot', Array.isArray(p.agents) && Array.isArray(p.tasks))
+    check('快照含 agents 基线', (p.agents ?? []).length > 0, `agents=${(p.agents ?? []).length}`)
+  }
+  {
+    send(ws, { type: 'ping' })
+    const { frame } = await waitFrame(ws, e => e.type === 'pong')
+    check('ping → pong', frame.type === 'pong')
+  }
+
+  // ---- 4. 实时推送 + 人类消息归属 ----
+  let lastSeq = 0
+  {
+    const before = await api('GET', `/api/workshop/channels/${CID}/events?limit=1`)
+    lastSeq = before.maxSeq ?? 0
+    const stamp = Date.now().toString(36)
+    // 先挂帧监听再注入:帧在 POST 处理中即推送,后挂会错过
+    const waitP = waitFrame(ws, e =>
+      e.type === 'a2a.message'
+      && Number(e.seq ?? 0) > lastSeq
+      && JSON.stringify(e.payload?.parts ?? []).includes(stamp), 15000)
+    await api('POST', `/api/workshop/channels/${CID}/messages`, {
+      toAgentId: 'b0de4cfa-42eb-4c64-90d1-c571bdd069f6',
+      text: `[ws-test] 人类实时消息 ${stamp}`,
+      priority: 'immediate',
+      requireReply: false,
+    })
+    const { frame } = await waitP
+    check('REST 注入 → WS 实时收到 a2a.message', true, `seq=${frame.seq}`)
+    check('人类消息信封 agentId 为空(归属修复)', frame.agentId === undefined || frame.agentId === null,
+      `agentId=${String(frame.agentId)}`)
+    check('帧 seq 单调 > 基线', frame.seq > lastSeq, `${lastSeq} → ${frame.seq}`)
+    lastSeq = frame.seq
+  }
+
+  // ---- 5. 断线续传:重连 + lastSeq 重放 ----
+  {
+    ws.close()
+    // 关闭后再注入一条(模拟断线窗口内的事件)
+    const stamp2 = Date.now().toString(36)
+    await api('POST', `/api/workshop/channels/${CID}/messages`, {
+      toAgentId: 'b0de4cfa-42eb-4c64-90d1-c571bdd069f6',
+      text: `[ws-test] 断线窗口消息 ${stamp2}`,
+      priority: 'task',
+    })
+    const ws2 = await openWs(`?token=${encodeURIComponent(TOKEN)}`)
+    const waitP2 = waitFrame(ws2, e =>
+      e.type === 'a2a.message' && JSON.stringify(e.payload?.parts ?? []).includes(stamp2), 15000)
+    send(ws2, { type: 'sub', channelId: CID, token: TOKEN, lastSeq })
+    const { seen } = await waitP2
+    const replay = seen.filter(e => typeof e.seq === 'number' && e.seq > lastSeq)
+    check('重连 lastSeq → 重放缺失段', replay.length > 0, `重放 ${replay.length} 帧`)
+    const seqs = replay.map(e => e.seq)
+    const monotonic = seqs.every((s, i) => i === 0 || s > seqs[i - 1])
+    check('重放段 seq 严格递增(不重复不跳号)', monotonic, seqs.slice(0, 8).join(','))
+    const noSnapshot = !seen.some(e => e.type === 'channel.snapshot')
+    check('游标在缓冲窗内 → 不下发全量快照', noSnapshot)
+    const last = seqs[seqs.length - 1] ?? lastSeq
+    ws2.close()
+
+    // ---- 6. 落库对账:WS 重放帧与 REST /events 同序 ----
+    const hist = await api('GET', `/api/workshop/channels/${CID}/events?limit=200`)
+    const items = hist.items ?? []
+    const bySeq = new Map(items.map(e => [e.seq, e]))
+    const replayInDb = replay.every(e => bySeq.has(e.seq))
+    check('重放帧全部落库(顺序事实源)', replayInDb)
+    const dbMax = Math.max(...items.map(e => e.seq), 0)
+    check('DB maxSeq ≥ WS 最后重放 seq', dbMax >= last, `db=${dbMax} ws=${last}`)
+  }
+
+  ws.close()
+  console.log(`\n${failures === 0 ? 'ALL PASS' : `${failures} FAILURE(S)`}`)
+  process.exit(failures === 0 ? 0 : 1)
+}
+
+main().catch((err) => {
+  console.error('WS 测试异常:', err.message)
+  process.exit(1)
+})

package/scripts/ws-test.py

@@ -0,0 +1,4 @@
+
+import websocket
+def ok(): print("test_OK")
+ok()

package/server/api/health.get.ts

@@ -0,0 +1,32 @@
+/**
+ * GET /api/health —— 存活探测(公开,无需认证;供运维/脚本探活)。
+ * 返回版本 + 进程 uptime + workshop manager 装配概要。
+ * 存活语义:进程可响应即 200;manager 未就绪(启动早期)降级标记 workshop='not_ready',
+ * 不抛错——就绪探针可按该字段判断,而探活端点本身不被组件状态拖垮。
+ */
+import { useServerConfig } from '../utils/config'
+import { defineApiHandler } from '../utils/response'
+import { getWorkshopManager } from '../plugins/workshop'
+
+export default defineApiHandler(async () => {
+  const cfg = useServerConfig()
+  let workshop: 'ready' | 'not_ready' = 'ready'
+  let summary: { wiredAgents: number, activeChannels: number } | null = null
+  try {
+    const status = getWorkshopManager().runtimeStatus()
+    summary = { wiredAgents: status.wiredAgents.length, activeChannels: status.activeChannels.length }
+  }
+  catch {
+    workshop = 'not_ready'
+  }
+  return {
+    status: 'ok',
+    app: cfg.app.name,
+    version: cfg.app.version,
+    mode: cfg.app.mode,
+    uptimeMs: Math.round(process.uptime() * 1000),
+    timestamp: new Date().toISOString(),
+    workshop,
+    ...summary,
+  }
+})

package/server/api/mcp/workshop.ts

@@ -0,0 +1,78 @@
+/**
+ * MCP Streamable HTTP 端点 — /api/mcp/workshop
+ *
+ * 平台对 Agent harness 的自主作业面(设计文档 §6.1):Agent(MCP client)经本端点
+ * 调用 16 个 workshop 工具(channel/agent/task/a2a 管理),与 REST API 双驱动同一 Manager。
+ *
+ * 实现: WebStandardStreamableHTTPServerTransport(stateful 模式,会话复用):
+ *  - POST initialize(无 sessionId)→ 创建 transport + McpServer,响应头带回 Mcp-Session-Id
+ *  - 后续 POST(带 sessionId)→ 复用 transport(会话内状态保留)
+ *  - GET(带 sessionId)→ SSE 流(server → client 消息)
+ *  - DELETE(带 sessionId)→ 关闭会话并从注册表移除
+ * 传输层认证: 工具级 Bearer token(workshop-server 的 requireCaller 解析)。
+ *
+ * 兼容性: 手动构造 web Request + 直接返回 web Response——同时兼容 Nitro 内置 h3 1.x
+ * 与项目根 h3 2.x(两者 Request/Response 转换助手名不一致,web 标准对象两版均可返回)。
+ */
+import { randomUUID } from 'node:crypto'
+import { defineEventHandler, getRequestURL, getRequestHeaders, readRawBody } from 'h3'
+import type { H3Event } from 'h3'
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js'
+import { createWorkshopMcpServer } from '../../mcp/workshop-server'
+import { getWorkshopManager } from '../../plugins/workshop'
+
+/** 会话注册表:sessionId → transport(stateful 会话状态保留) */
+const sessions = new Map<string, WebStandardStreamableHTTPServerTransport>()
+
+/** h3 event → web Request(跨 h3 1.x/2.x 兼容:不用版本互异的转换助手) */
+async function toFetchRequest(event: H3Event): Promise<Request> {
+  const hasBody = event.method !== 'GET' && event.method !== 'DELETE'
+  const body = hasBody ? await readRawBody(event) : undefined
+  return new Request(getRequestURL(event), {
+    method: event.method,
+    headers: new Headers(getRequestHeaders(event) as Record<string, string>),
+    body,
+  })
+}
+
+function sessionIdOf(event: H3Event): string | null {
+  const url = new URL(event.path, 'http://localhost')
+  const sid = url.searchParams.get('sessionId') ?? getRequestHeaders(event)['mcp-session-id']
+  return typeof sid === 'string' && sid.length > 0 ? sid : null
+}
+
+export default defineEventHandler(async (event) => {
+  const request = await toFetchRequest(event)
+  const sessionId = sessionIdOf(event)
+
+  // DELETE:关闭会话
+  if (event.method === 'DELETE' && sessionId) {
+    const transport = sessions.get(sessionId)
+    if (transport) {
+      try {
+        await transport.handleRequest(request)
+      }
+      finally {
+        sessions.delete(sessionId)
+      }
+      return new Response(null, { status: 204 })
+    }
+    return new Response(null, { status: 404 })
+  }
+
+  // 复用已有会话
+  let transport = sessionId ? sessions.get(sessionId) : undefined
+
+  // 新会话:预生成 sessionId,transport 在 initialize 时把它写入响应头
+  if (!transport) {
+    const newSessionId = randomUUID()
+    transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: () => newSessionId,
+    })
+    const server = createWorkshopMcpServer(getWorkshopManager())
+    await server.connect(transport)
+    sessions.set(newSessionId, transport)
+  }
+
+  return transport.handleRequest(request)
+})

package/server/api/metrics.ts

@@ -0,0 +1,75 @@
+/**
+ * GET /api/metrics —— 运维指标端点(R4,production-readiness-plan)。
+ *
+ * text/plain 简易指标格式(键值行,Prometheus 可用 textfile/自定义采集器接入)。
+ * 无鉴权:仅暴露聚合计数与时间戳,不含业务数据;内网部署语义。
+ * 只读 globalThis 单例(不主动实例化),服务未装配时输出 0 —— 首次抓取即合法。
+ */
+import { defineEventHandler, setResponseHeader } from 'h3'
+import { getOps } from '../services/workshop/ops/ops'
+
+interface MetricLine { name: string, help: string, value: number | string }
+
+function fmt(lines: MetricLine[]): string {
+  return lines.map(l => `# HELP ${l.name} ${l.help}\n# TYPE ${l.name} gauge\n${l.name} ${l.value}`).join('\n') + '\n'
+}
+
+export default defineEventHandler(async (event) => {
+  const g = globalThis as typeof globalThis & {
+    __daqController?: { controllerState(): Record<string, number | boolean>, running?: boolean }
+    __daqQueue?: { lost?: number }
+    __daqQueueBackend?: string
+    __toolApprovals?: { listPending(agentId?: string): unknown[] }
+    __wsDbFlushFails?: number
+    __awBackupLastAt?: string
+  }
+
+  const lines: MetricLine[] = []
+
+  // ---- DAQ 数据链路(未运行/未装配时 controllerState 仍可读,计数为 0) ----
+  const ctrl = g.__daqController
+  if (ctrl) {
+    const s = ctrl.controllerState()
+    const num = (v: unknown): number => (typeof v === 'number' ? v : 0)
+    lines.push(
+      { name: 'awshop_daq_running', help: 'DAQ controller running(1=运行中)', value: s.running ? 1 : 0 },
+      { name: 'awshop_daq_nodes_total', help: 'DAQ nodes registered', value: num(s.nodesTotal) },
+      { name: 'awshop_daq_nodes_online', help: 'DAQ nodes enabled', value: num(s.nodesOnline) },
+      { name: 'awshop_daq_produced_total', help: 'Samples produced by runtimes', value: num(s.produced) },
+      { name: 'awshop_daq_consumed_total', help: 'Samples consumed from queue', value: num(s.consumed) },
+      { name: 'awshop_daq_dropped_total', help: 'Samples dropped(queue lost + late frames)', value: num(s.dropped) },
+      { name: 'awshop_daq_samples_stored_total', help: 'Samples persisted to tsdb', value: num(s.samplesStored) },
+      { name: 'awshop_daq_tsdb_dropped_total', help: 'Samples dropped by tsdb writer', value: num(s.tsdbDropped) },
+      { name: 'awshop_daq_alarms_raised_total', help: 'Alarms raised(edge-trigger, idempotent)', value: num(s.alarmsRaised) },
+    )
+  }
+  else {
+    lines.push(
+      { name: 'awshop_daq_running', help: 'DAQ controller running(1=运行中)', value: 0 },
+      { name: 'awshop_daq_produced_total', help: 'Samples produced by runtimes', value: 0 },
+      { name: 'awshop_daq_samples_stored_total', help: 'Samples persisted to tsdb', value: 0 },
+      { name: 'awshop_daq_alarms_raised_total', help: 'Alarms raised(edge-trigger, idempotent)', value: 0 },
+    )
+  }
+  lines.push(
+    { name: 'awshop_daq_queue_lost_total', help: 'Frames lost at queue adapter(mqtt断连/inproc拥塞)', value: g.__daqQueue?.lost ?? 0 },
+    { name: 'awshop_daq_queue_backend_info', help: 'Queue backend(inproc=0 / mqtt=1)', value: (g.__daqQueueBackend ?? 'inproc') === 'mqtt' ? 1 : 0 },
+  )
+
+  // ---- WS 实时通道(落库失败静默重试,只能靠计数观测) ----
+  lines.push({ name: 'awshop_ws_db_flush_fails_total', help: 'Channel event batch DB-insert failures', value: g.__wsDbFlushFails ?? 0 })
+
+  // ---- HITL:工具审批 + 高危操作复核待办 ----
+  const toolPending = g.__toolApprovals?.listPending().length ?? 0
+  const opsPending = getOps()?.approvalRequests.listPending().length ?? 0
+  lines.push(
+    { name: 'awshop_tool_approvals_pending', help: 'Pending agent tool approvals(HITL)', value: toolPending },
+    { name: 'awshop_operation_approvals_pending', help: 'Pending dangerous-operation approval requests(maker-checker)', value: opsPending },
+  )
+
+  // ---- 备份(S6) ----
+  lines.push({ name: 'awshop_backup_last_success_timestamp', help: 'Last successful backup ISO time(0=从未)', value: g.__awBackupLastAt ?? 0 })
+
+  setResponseHeader(event, 'content-type', 'text/plain; charset=utf-8')
+  return fmt(lines)
+})

package/server/api/system/config.get.ts

@@ -0,0 +1,12 @@
+/**
+ * GET /api/system/config —— 服务端配置视图(业务信息:端口/分页等)。
+ * 需用户 token(业务面统一鉴权;与前端 useSiteConfig() 同源于 config.yml,用于验证前后端配置一致性)。
+ */
+import { defineApiHandler } from '../../utils/response'
+import { useServerConfig } from '../../utils/config'
+import { resolveUser } from '../workshop/caller'
+
+export default defineApiHandler((event) => {
+  resolveUser(event)
+  return useServerConfig()
+})