agentworkshop 0.2.1

package/server/api/system/monitor/terminal/ws.ts

@@ -0,0 +1,177 @@
+/**
+ * WebSocket 端点: /api/system/monitor/terminal/ws?pid=<pid>&token=<userToken>
+ *
+ * harness 终端通道(协议权威 #shared/terminal-protocol):
+ *  - 下行:term.init(会话元信息+状态) → term.frames(重放缓冲 + 实时帧微批)
+ *          / term.state(回合·流式状态) / term.notice / term.error / pong
+ *  - 上行:ping / input(steer·follow_up 注入 omp 会话)/ abort(中止回合)/
+ *          ui_response(HITL 对话框应答 → extension_ui_response)
+ *
+ * 鉴权:用户 token(?token= 查询参数,与管理 API 同口径)——终端可向
+ * 真实 agent 会话注入输入(HITL),必须认证。
+ */
+import { defineWebSocketHandler } from 'h3'
+import { resolveUserByToken } from '../../../../services/user.service'
+import {
+  abortTerminal,
+  findLiveTerminalPidByAgent,
+  respondTerminalUi,
+  sendTerminalInput,
+  subscribeTerminal,
+  terminalSessionSnapshot,
+} from '../../../../services/workshop/agents/harness-terminal'
+import type { TerminalClientMessage, TerminalServerMessage } from '../../../../../shared/terminal-protocol'
+
+/** 最小 peer 接口(h3 2.x 未 re-export crossws 类型,duck typing;与 workshop ws.ts 同风格) */
+interface WsPeer {
+  send(data: string | Uint8Array): void
+  close(code?: number, reason?: string): void
+}
+
+function resolveQueryParam(peer: WsPeer, name: string): string | undefined {
+  const req = (peer as unknown as { request?: Request }).request
+  if (!req) return undefined
+  return new URL(req.url).searchParams.get(name) ?? undefined
+}
+
+function send(peer: WsPeer, msg: TerminalServerMessage): void {
+  try {
+    peer.send(JSON.stringify(msg))
+  }
+  catch { /* 死连接 */ }
+}
+
+function fail(peer: WsPeer, code: string, message: string, wsCode = 4400): void {
+  send(peer, { type: 'term.error', code, message })
+  peer.close(wsCode, message)
+}
+
+export default defineWebSocketHandler({
+  open(peer) {
+    const ws = peer as unknown as WsPeer
+
+    // 鉴权:?token= 用户 token(管理面同口径)
+    const token = resolveQueryParam(ws, 'token')
+    if (!token || !resolveUserByToken(token)) {
+      fail(ws, 'USER_UNAUTHORIZED', '需要有效用户 token(?token= 查询参数)', 4401)
+      return
+    }
+
+    // 寻址:优先 pid;否则 agentId(+可选 channelId)解析当前存活进程
+    // (omp lazy spawn:进程随首个任务启动;agent 寻址下前端断线重连/进程
+    // 重启后自动落到新会话)
+    const pidRaw = Number.parseInt(resolveQueryParam(ws, 'pid') ?? '', 10)
+    const agentId = resolveQueryParam(ws, 'agentId')
+    let pid: number
+    if (Number.isInteger(pidRaw) && pidRaw > 0) {
+      pid = pidRaw
+    }
+    else if (agentId) {
+      const resolved = findLiveTerminalPidByAgent(resolveQueryParam(ws, 'channelId') ?? '', agentId)
+      if (!resolved) {
+        fail(ws, 'NO_SESSION', `agent ${agentId.slice(0, 8)} 的 omp 进程尚未启动(等待首个任务触发 spawn)`, 4404)
+        return
+      }
+      pid = resolved
+    }
+    else {
+      fail(ws, 'BAD_PID', '缺少有效 pid 或 agentId 查询参数', 4400)
+      return
+    }
+
+    const snap = terminalSessionSnapshot(pid)
+    if (!snap) {
+      fail(ws, 'NO_SESSION', `PID ${pid} 无终端镜像会话(进程未启动或非 omp harness)`, 4404)
+      return
+    }
+
+    send(ws, {
+      type: 'term.init',
+      meta: snap.meta,
+      alive: snap.alive,
+      streaming: snap.streaming,
+      running: snap.running,
+      lastSeq: snap.lastSeq,
+      hitl: snap.hitl,
+    })
+    // 重放缓冲(全量;环形缓冲上限内,前端按 seq 渲染)
+    if (snap.replay.length > 0) {
+      send(ws, { type: 'term.frames', frames: snap.replay })
+    }
+
+    const unsub = subscribeTerminal(pid, msg => send(ws, msg))
+    if (!unsub) {
+      fail(ws, 'NO_SESSION', `PID ${pid} 终端会话已消失`, 4404)
+      return
+    }
+    const holder = peer as unknown as { __unsub?: () => void, __termPid?: number }
+    holder.__unsub = unsub
+    holder.__termPid = pid
+  },
+
+  message(peer, message) {
+    const ws = peer as unknown as WsPeer
+    const raw = message.text()
+    if (!raw) return
+    let parsed: TerminalClientMessage
+    try {
+      parsed = JSON.parse(raw) as TerminalClientMessage
+    }
+    catch {
+      send(ws, { type: 'term.error', code: 'BAD_MESSAGE', message: '无法解析的上行消息(需 JSON)' })
+      return
+    }
+
+    // open 时解析并缓存的 pid(pid 直连或 agentId 解析结果)
+    const pid = (peer as unknown as { __termPid?: number }).__termPid
+    if (!Number.isInteger(pid)) return
+    const targetPid = pid as number
+
+    switch (parsed.type) {
+      case 'ping':
+        send(ws, { type: 'pong' })
+        return
+      case 'input': {
+        const text = parsed.text?.trim()
+        if (!text) return
+        sendTerminalInput(targetPid, text).catch((err: unknown) => {
+          send(ws, { type: 'term.error', code: 'INPUT_FAILED', message: err instanceof Error ? err.message : String(err) })
+        })
+        return
+      }
+      case 'abort': {
+        abortTerminal(targetPid).catch((err: unknown) => {
+          send(ws, { type: 'term.error', code: 'ABORT_FAILED', message: err instanceof Error ? err.message : String(err) })
+        })
+        return
+      }
+      case 'ui_response': {
+        if (!parsed.id) return
+        try {
+          respondTerminalUi(targetPid, {
+            id: parsed.id,
+            value: typeof parsed.value === 'string' ? parsed.value : undefined,
+            confirmed: typeof parsed.confirmed === 'boolean' ? parsed.confirmed : undefined,
+            cancelled: parsed.cancelled === true,
+          })
+        }
+        catch (err) {
+          send(ws, { type: 'term.error', code: 'UI_RESPONSE_FAILED', message: err instanceof Error ? err.message : String(err) })
+        }
+        return
+      }
+      default:
+        send(ws, { type: 'term.error', code: 'UNKNOWN_COMMAND', message: `未知上行消息类型: ${(parsed as { type?: string }).type}` })
+    }
+  },
+
+  close(peer) {
+    (peer as unknown as { __unsub?: () => void }).__unsub?.()
+  },
+
+  error(peer, error) {
+    console.error('[terminal-ws] connection error:', error)
+    const holder = peer as unknown as { __unsub?: () => void }
+    holder.__unsub?.()
+  },
+})

package/server/api/system/monitor/terminate.post.ts

@@ -0,0 +1,36 @@
+/**
+ * POST /api/system/monitor/terminate —— 终止 harness 进程(防资源浪费;用户级隔离)。
+ *  - { channelId, agentId }:终止对应 runtime 的进程;channel 须为本人或 admin。
+ *  - { pid }:按 PID 终止;绑定 channel 的进程须本人/admin,未绑定孤儿进程仅 admin。
+ * 需要用户 token(管理面)。
+ */
+import { readBody } from 'h3'
+import { AppError } from '../../../utils/errors'
+import { defineApiHandler } from '../../../utils/response'
+import { getWorkshopManager } from '../../../plugins/workshop'
+import { resolveUser } from '../../workshop/caller'
+import { listHarnessProcesses } from '../../../services/workshop/agents/harness-process'
+
+export default defineApiHandler(async (event) => {
+  const user = resolveUser(event)
+  const body = await readBody<{ channelId?: string, agentId?: string, pid?: number }>(event)
+  const manager = getWorkshopManager()
+  if (body?.agentId && body?.channelId) {
+    const ch = manager.getChannelForUser(body.channelId, user.id)
+    manager.requireWritable(ch.ownerUserId, user, 'channel')
+    return manager.terminateRuntimeProcess(body.channelId, body.agentId)
+  }
+  if (typeof body?.pid === 'number' && Number.isInteger(body.pid) && body.pid > 0) {
+    // 进程归属判定:绑定的 channel 须本人/admin;未绑定(孤儿)仅 admin 可杀
+    const entry = listHarnessProcesses().find(p => p.pid === body.pid)
+    if (entry?.channelId) {
+      const ch = manager.getChannelForUser(entry.channelId, user.id)
+      manager.requireWritable(ch.ownerUserId, user, 'channel')
+    }
+    else if (user.role !== 'admin') {
+      throw new AppError(403, 'ADMIN_REQUIRED', '孤儿进程终止需要管理员权限')
+    }
+    return manager.killHarnessProcessByPid(body.pid)
+  }
+  throw new AppError(400, 'BAD_REQUEST', '需要 { channelId, agentId } 或 { pid }')
+})

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

@@ -0,0 +1,13 @@
+/**
+ * GET /api/system/monitor —— 运行时资源监控快照(用户级隔离)。
+ * 普通用户:仅本人 channel 的 runtime/agent/进程(孤儿与无主资源不可见);
+ * admin:全量视图,附 ownerUserId/ownerName(创建者)标注。需要用户 token(管理面)。
+ */
+import { defineApiHandler } from '../../utils/response'
+import { resolveUser } from '../workshop/caller'
+import { getWorkshopManager } from '../../plugins/workshop'
+
+export default defineApiHandler(async (event) => {
+  const user = resolveUser(event)
+  return getWorkshopManager().monitorRuntimeForUser(user)
+})

package/server/api/system/settings/events.get.ts

@@ -0,0 +1,28 @@
+/**
+ * GET /api/system/settings/events —— 设置变更 SSE 事件流。
+ * 客户端用 fetch + ReadableStream（带 Authorization 头）订阅；
+ * 服务端任何写入（UI / CLI / 文件监听）都会 push { type, changed, restartRequired, effective }。
+ * 连接前先鉴权（无效 token 直接 401，不开流）。
+ */
+import { createEventStream } from 'h3'
+import { resolveUser } from '../../workshop/caller'
+import { getSystemConfigService, type ConfigEventPayload } from '../../../services/system-config'
+
+export default defineEventHandler(async (event) => {
+  resolveUser(event) // 开流前鉴权：无 token → 401
+  const service = getSystemConfigService()
+  const stream = createEventStream(event)
+
+  let listener: ((payload: ConfigEventPayload) => void) | undefined
+  listener = (payload) => {
+    void stream.push(JSON.stringify(payload))
+  }
+  const unsubscribe = service.subscribe(listener)
+
+  stream.onClosed(async () => {
+    unsubscribe()
+    await stream.close()
+  })
+
+  return stream.send()
+})

package/server/api/system/settings/index.get.ts

@@ -0,0 +1,14 @@
+/**
+ * GET /api/system/settings —— 运行时设置全量快照。
+ * 返回描述符 + 有效值 + 各键来源(config.yml/runtime/env) + 覆盖文件路径。
+ * 前端「系统设置 → 运行配置」表单据此渲染;CLI `aw status` 也走同源概念。
+ * 鉴权:任何已登录用户可读(config.get 同语义)。
+ */
+import { defineApiHandler } from '../../../utils/response'
+import { resolveUser } from '../../workshop/caller'
+import { getSystemConfigService } from '../../../services/system-config'
+
+export default defineApiHandler((event) => {
+  resolveUser(event)
+  return getSystemConfigService().snapshot()
+})

package/server/api/system/settings/index.patch.ts

@@ -0,0 +1,22 @@
+/**
+ * PATCH /api/system/settings —— 写入运行时设置（持久化 + 热重载）。
+ * body: { "override": { "<key>": value | null } }
+ *   value 非 null → 校验后写入 data/runtime-settings.json 并立即应用(live 键实时生效)
+ *   value 为 null → 清除该键覆盖(回落 config.yml)
+ * 返回 { changed, restartRequired, effective, sources, overrides }。
+ * 鉴权:仅 admin（系统级设置变更属高危管理面）。
+ */
+import { readBody } from 'h3'
+import { defineApiHandler } from '../../../utils/response'
+import { requireRole } from '../../workshop/caller'
+import { getSystemConfigService } from '../../../services/system-config'
+
+export default defineApiHandler(async (event) => {
+  requireRole(event, ['admin'])
+  const body = (await readBody(event)) ?? {}
+  const overrides = body.override ?? body.overrides ?? body
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    return { ok: false, message: '请求体应为 { "override": { key: value } }' }
+  }
+  return { ok: true, ...getSystemConfigService().patch(overrides as Record<string, unknown>) }
+})

package/server/api/system/settings/reset.post.ts

@@ -0,0 +1,12 @@
+/**
+ * POST /api/system/settings/reset —— 清空全部运行时覆盖（回落 config.yml/base + env）。
+ * 鉴权:仅 admin。
+ */
+import { defineApiHandler } from '../../../utils/response'
+import { requireRole } from '../../workshop/caller'
+import { getSystemConfigService } from '../../../services/system-config'
+
+export default defineApiHandler((event) => {
+  requireRole(event, ['admin'])
+  return { ok: true, ...getSystemConfigService().reset() }
+})

package/server/api/users/[id].delete.ts

@@ -0,0 +1,11 @@
+import { getRouterParam } from 'h3'
+import { userService } from '../../services/user.service'
+import { defineApiHandler } from '../../utils/response'
+import { requireAdmin } from '../workshop/caller'
+
+/** DELETE /api/users/:id —— 删除用户(仅 admin) */
+export default defineApiHandler((event) => {
+  requireAdmin(event)
+  const id = getRouterParam(event, 'id') ?? ''
+  return userService.remove(id)
+})

package/server/api/users/[id].get.ts

@@ -0,0 +1,11 @@
+import { getRouterParam } from 'h3'
+import { userService } from '../../services/user.service'
+import { defineApiHandler } from '../../utils/response'
+import { requireAdmin } from '../workshop/caller'
+
+/** GET /api/users/:id —— 用户详情(仅 admin) */
+export default defineApiHandler((event) => {
+  requireAdmin(event)
+  const id = getRouterParam(event, 'id') ?? ''
+  return userService.getById(id)
+})

package/server/api/users/[id].put.ts

@@ -0,0 +1,14 @@
+import { getRouterParam, readValidatedBody } from 'h3'
+import { userUpdateSchema, type UserUpdate } from '../../schemas/user.schema'
+import { userService } from '../../services/user.service'
+import { defineApiHandler } from '../../utils/response'
+import { zValidator } from '../../utils/validate'
+import { requireAdmin } from '../workshop/caller'
+
+/** PUT /api/users/:id —— 更新用户（部分字段） */
+export default defineApiHandler(async (event) => {
+  requireAdmin(event)
+  const id = getRouterParam(event, 'id') ?? ''
+  const body = await readValidatedBody(event, zValidator(userUpdateSchema)) as UserUpdate
+  return userService.update(id, body)
+})

package/server/api/users/index.get.ts

@@ -0,0 +1,13 @@
+import { getValidatedQuery } from 'h3'
+import { userListQuerySchema, type UserListQueryInput } from '../../schemas/user.schema'
+import { userService } from '../../services/user.service'
+import { defineApiHandler } from '../../utils/response'
+import { zValidator } from '../../utils/validate'
+import { requireAdmin } from '../workshop/caller'
+
+/** GET /api/users —— 分页查询用户（pageSize 缺省时由 config.yml 驱动；仅 admin） */
+export default defineApiHandler(async (event) => {
+  requireAdmin(event)
+  const query = await getValidatedQuery(event, zValidator(userListQuerySchema)) as UserListQueryInput
+  return userService.list(query)
+})

package/server/api/users/index.post.ts

@@ -0,0 +1,13 @@
+import { readValidatedBody } from 'h3'
+import { userCreateSchema, type UserCreate } from '../../schemas/user.schema'
+import { userService } from '../../services/user.service'
+import { defineApiHandler } from '../../utils/response'
+import { zValidator } from '../../utils/validate'
+import { requireAdmin } from '../workshop/caller'
+
+/** POST /api/users —— 创建用户 */
+export default defineApiHandler(async (event) => {
+  requireAdmin(event)
+  const body = await readValidatedBody(event, zValidator(userCreateSchema)) as UserCreate
+  return userService.create(body)
+})

package/server/api/users/login.post.ts

@@ -0,0 +1,11 @@
+import { readValidatedBody } from 'h3'
+import { userLoginSchema, type UserLogin } from '../../schemas/user.schema'
+import { userService } from '../../services/user.service'
+import { defineApiHandler } from '../../utils/response'
+import { zValidator } from '../../utils/validate'
+
+/** POST /api/users/login —— 公开登录（email + password），签发新会话 token */
+export default defineApiHandler(async (event) => {
+  const body = await readValidatedBody(event, zValidator(userLoginSchema)) as UserLogin
+  return userService.login(body)
+})

package/server/api/users/logout.post.ts

@@ -0,0 +1,9 @@
+import { extractBearerToken } from '../../utils/auth'
+import { userService } from '../../services/user.service'
+import { defineApiHandler } from '../../utils/response'
+
+/** POST /api/users/logout —— 吊销当前使用的 token（仅该 token 失效） */
+export default defineApiHandler((event) => {
+  const token = extractBearerToken(event)
+  return userService.logout(token)
+})

package/server/api/users/me.get.ts

@@ -0,0 +1,9 @@
+import { extractBearerToken } from '../../utils/auth'
+import { userService } from '../../services/user.service'
+import { defineApiHandler } from '../../utils/response'
+
+/** GET /api/users/me —— 当前用户信息（Bearer token） */
+export default defineApiHandler((event) => {
+  const token = extractBearerToken(event)
+  return userService.me(token)
+})

package/server/api/users/register.post.ts

@@ -0,0 +1,11 @@
+import { readValidatedBody } from 'h3'
+import { userRegisterSchema, type UserRegister } from '../../schemas/user.schema'
+import { userService } from '../../services/user.service'
+import { defineApiHandler } from '../../utils/response'
+import { zValidator } from '../../utils/validate'
+
+/** POST /api/users/register —— 公开注册（name + email + password），签发首个 token */
+export default defineApiHandler(async (event) => {
+  const body = await readValidatedBody(event, zValidator(userRegisterSchema)) as UserRegister
+  return userService.register(body)
+})

package/server/api/users/tokens/[id]/token.get.ts

@@ -0,0 +1,11 @@
+import { getRouterParam } from 'h3'
+import { extractBearerToken } from '../../../../utils/auth'
+import { userService } from '../../../../services/user.service'
+import { defineApiHandler } from '../../../../utils/response'
+
+/** GET /api/users/tokens/:id/token —— 查看当前用户某 token 的存档明文（随时可查，配合前端掩码/眼睛切换） */
+export default defineApiHandler((event) => {
+  const token = extractBearerToken(event)
+  const id = getRouterParam(event, 'id') ?? ''
+  return { token: userService.revealToken(userService.me(token).id, id) }
+})

package/server/api/users/tokens/[id].delete.ts

@@ -0,0 +1,11 @@
+import { getRouterParam } from 'h3'
+import { extractBearerToken } from '../../../utils/auth'
+import { userService } from '../../../services/user.service'
+import { defineApiHandler } from '../../../utils/response'
+
+/** DELETE /api/users/tokens/:id —— 吊销当前用户某 token */
+export default defineApiHandler((event) => {
+  const token = extractBearerToken(event)
+  const id = getRouterParam(event, 'id') ?? ''
+  return userService.revokeToken(userService.me(token).id, id)
+})

package/server/api/users/tokens/[id].patch.ts

@@ -0,0 +1,14 @@
+import { getRouterParam, readValidatedBody } from 'h3'
+import { userTokenUpdateSchema, type UserTokenUpdate } from '../../../schemas/user.schema'
+import { extractBearerToken } from '../../../utils/auth'
+import { userService } from '../../../services/user.service'
+import { defineApiHandler } from '../../../utils/response'
+import { zValidator } from '../../../utils/validate'
+
+/** PATCH /api/users/tokens/:id —— 更新当前用户某 token 的标签 */
+export default defineApiHandler(async (event) => {
+  const token = extractBearerToken(event)
+  const id = getRouterParam(event, 'id') ?? ''
+  const body = await readValidatedBody(event, zValidator(userTokenUpdateSchema)) as UserTokenUpdate
+  return userService.updateToken(userService.me(token).id, id, body.label)
+})

package/server/api/users/tokens/index.get.ts

@@ -0,0 +1,9 @@
+import { extractBearerToken } from '../../../utils/auth'
+import { userService } from '../../../services/user.service'
+import { defineApiHandler } from '../../../utils/response'
+
+/** GET /api/users/tokens —— 当前用户 token 列表（仅元数据，不含明文） */
+export default defineApiHandler((event) => {
+  const token = extractBearerToken(event)
+  return userService.listTokens(userService.me(token).id)
+})

package/server/api/users/tokens/index.post.ts

@@ -0,0 +1,13 @@
+import { readValidatedBody } from 'h3'
+import { userTokenCreateSchema, type UserTokenCreate } from '../../../schemas/user.schema'
+import { extractBearerToken } from '../../../utils/auth'
+import { userService } from '../../../services/user.service'
+import { defineApiHandler } from '../../../utils/response'
+import { zValidator } from '../../../utils/validate'
+
+/** POST /api/users/tokens —— 为当前用户创建新 token（明文仅此一次返回） */
+export default defineApiHandler(async (event) => {
+  const token = extractBearerToken(event)
+  const body = await readValidatedBody(event, zValidator(userTokenCreateSchema)) as UserTokenCreate
+  return userService.createToken(userService.me(token).id, body.label)
+})

package/server/api/workshop/[...path].ts

@@ -0,0 +1,13 @@
+/**
+ * /api/workshop/** 未匹配路由的兜底 404 信封。
+ * - 显式路由优先;只有没有任何路由命中的路径才会落到这里
+ * - 输出与 defineApiHandler 同形的 {code:'NOT_FOUND', message, data:null},
+ *   前端 apiFetch/调用方不必对 h3 原生 "Page not found" 做特殊分支
+ */
+import type { H3Event } from 'h3'
+import { AppError } from '../../utils/errors'
+import { defineApiHandler } from '../../utils/response'
+
+export default defineApiHandler((event: H3Event) => {
+  throw new AppError(404, 'NOT_FOUND', `接口不存在: ${event.path}`)
+})

package/server/api/workshop/a2a/[agentId]/card/index.get.ts

@@ -0,0 +1,75 @@
+/**
+ * GET /api/workshop/a2a/:agentId.card —— A2A AgentCard(设计文档 §6.3,规范 §7)。
+ * 由 AgentConfig 动态生成:camelCase 字段,supportedInterfaces.protocolBinding='JSONRPC',
+ * capabilities.streaming=true,skills 由 config.skills 声明(缺省 [])。
+ * 按 A2A 规范直接返回 card 文档(不走 ApiEnvelope 信封);Agent 不存在 → 404。
+ */
+import { defineEventHandler, getRouterParam, setResponseStatus } from 'h3'
+import { getWorkshopManager } from '../../../../../plugins/workshop'
+import type { AgentChannelManager, ManagerDeps } from '../../../../../services/workshop/runtime/manager'
+import type { AgentInfo } from '../../../../../services/workshop/agents/agent-interface'
+import { parseJson } from '../../../../../services/workshop/db/database'
+
+/** A2A AgentCard(1.0 子集,与 rpc agent/getCard 同一结构) */
+export interface AgentCard {
+  name: string
+  description: string
+  supportedInterfaces: {
+    url: string
+    protocolBinding: 'JSONRPC'
+    protocolVersion: '1.0'
+  }[]
+  capabilities: { streaming: boolean, pushNotifications: boolean }
+  defaultInputModes: string[]
+  defaultOutputModes: string[]
+  skills: unknown[]
+}
+
+/** 按实例 id 查找 Channel 实例(公开 API 无 findAgent;经 deps.repos 只读查询) */
+export function findAgent(manager: AgentChannelManager, agentId: string): AgentInfo | undefined {
+  const repos = (manager as unknown as { deps: ManagerDeps }).deps.repos
+  const m = repos.channelAgents.findById(agentId)
+  if (!m) return undefined
+  return {
+    id: m.id,
+    channelId: m.channelId,
+    name: m.name,
+    harness: m.harness,
+    role: m.role as 'lead' | 'worker',
+    config: parseJson<Record<string, unknown>>(m.configJson, {}),
+    token: m.token,
+  }
+}
+
+/** 生成 AgentCard(由 AgentConfig 动态生成;description/skills 可经 config 声明) */
+export function buildAgentCard(agent: AgentInfo): AgentCard {
+  const config = agent.config ?? {}
+  return {
+    name: agent.name,
+    description:
+      typeof config.description === 'string'
+        ? config.description
+        : `AgentWorkShop ${agent.role} Agent(${agent.harness})`,
+    supportedInterfaces: [
+      {
+        url: `/api/workshop/a2a/${agent.id}/rpc`,
+        protocolBinding: 'JSONRPC',
+        protocolVersion: '1.0',
+      },
+    ],
+    capabilities: { streaming: true, pushNotifications: false },
+    defaultInputModes: ['text/plain'],
+    defaultOutputModes: ['text/plain'],
+    skills: Array.isArray(config.skills) ? config.skills : [],
+  }
+}
+
+export default defineEventHandler((event) => {
+  const agentId = getRouterParam(event, 'agentId')!
+  const agent = findAgent(getWorkshopManager(), agentId)
+  if (!agent) {
+    setResponseStatus(event, 404)
+    return { error: { code: 'NOT_FOUND', message: `Agent 不存在: ${agentId}` } }
+  }
+  return buildAgentCard(agent)
+})