agentworkshop 0.2.1

package/server/api/workshop/dcw/recipes/[id]/mark-good.post.ts

@@ -0,0 +1,21 @@
+/**
+ * POST /api/workshop/dcw/recipes/:id/mark-good —— 标记已知良好批次(基准恢复目标)。
+ * body: { runId: string }
+ */
+import { getRouterParam, readBody } from 'h3'
+import { requireRole } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { AppError, ErrorCodes } from '@/server/utils/errors'
+import { getDcwRecipeRepo } from '@/server/services/workshop/dcw/dcw-recipe.repo'
+import { audit } from '@/server/services/workshop/ops/ops'
+
+export default defineApiHandler(async (event) => {
+  const user = requireRole(event)
+  const id = getRouterParam(event, 'id') ?? ''
+  const body = await readBody<{ runId?: string }>(event) ?? {}
+  if (!body.runId)
+    throw new AppError(400, ErrorCodes.VALIDATION_ERROR, 'runId 必填')
+  const updated = getDcwRecipeRepo().markGood(id, String(body.runId))
+  audit({ actor: user.id, actorName: user.name, actorKind: 'user', action: 'recipe.mark-good', targetKind: 'recipe', targetId: id, detail: { runId: body.runId } })
+  return { recipe: updated }
+})

package/server/api/workshop/dcw/recipes/[id]/rollback-good.post.ts

@@ -0,0 +1,19 @@
+/**
+ * POST /api/workshop/dcw/recipes/:id/rollback-good —— 基准恢复:重新下发 lastGood 批次冻结参数集。
+ */
+import { getRouterParam } from 'h3'
+import { requireRole } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { bindDcwBroadcast } from '@/server/services/workshop/dcw/dcw-controller'
+import { broadcastSceneEvent } from '@/server/services/workshop/scene-events'
+import { getRecipeRollBackManager } from '@/server/services/workshop/dcw/recipe-rollback-manager'
+import { audit } from '@/server/services/workshop/ops/ops'
+
+export default defineApiHandler(async (event) => {
+  const user = requireRole(event)
+  bindDcwBroadcast(broadcastSceneEvent)
+  const id = getRouterParam(event, 'id') ?? ''
+  const outcomes = await getRecipeRollBackManager().rollbackRecipeGood(id, user.id)
+  audit({ actor: user.id, actorName: user.name, actorKind: 'user', action: 'recipe.rollback-good', targetKind: 'recipe', targetId: id, detail: { outcomes } })
+  return { outcomes }
+})

package/server/api/workshop/dcw/recipes/[id].delete.ts

@@ -0,0 +1,14 @@
+/**
+ * DELETE /api/workshop/dcw/recipes/:id —— 删除配方。
+ */
+import { getRouterParam } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDcwRecipeRepo } from '@/server/services/workshop/dcw/dcw-recipe.repo'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const id = getRouterParam(event, 'id') ?? ''
+  getDcwRecipeRepo().remove(id)
+  return { deleted: true }
+})

package/server/api/workshop/dcw/recipes/[id].patch.ts

@@ -0,0 +1,16 @@
+/**
+ * PATCH /api/workshop/dcw/recipes/:id —— 编辑配方。
+ */
+import { getRouterParam, readBody } from 'h3'
+import type { RecipeInput } from '#shared/dcw-protocol'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDcwRecipeRepo } from '@/server/services/workshop/dcw/dcw-recipe.repo'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const id = getRouterParam(event, 'id') ?? ''
+  const body = await readBody<Partial<RecipeInput>>(event) ?? {}
+  const recipe = getDcwRecipeRepo().update(id, body)
+  return { recipe }
+})

package/server/api/workshop/dcw/recipes/index.get.ts

@@ -0,0 +1,12 @@
+/**
+ * GET /api/workshop/dcw/recipes —— 配方 + 批次列表。
+ */
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDcwRecipeRepo } from '@/server/services/workshop/dcw/dcw-recipe.repo'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const repo = getDcwRecipeRepo()
+  return { recipes: repo.list(), runs: repo.listRuns() }
+})

package/server/api/workshop/dcw/recipes/index.post.ts

@@ -0,0 +1,15 @@
+/**
+ * POST /api/workshop/dcw/recipes —— 创建配方(body: { name, description?, params? })。
+ */
+import { readBody } from 'h3'
+import type { RecipeInput } from '#shared/dcw-protocol'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDcwRecipeRepo } from '@/server/services/workshop/dcw/dcw-recipe.repo'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const body = await readBody<RecipeInput>(event) ?? { name: '' }
+  const recipe = getDcwRecipeRepo().create(body)
+  return { recipe }
+})

package/server/api/workshop/dcw/runs/[id]/close.post.ts

@@ -0,0 +1,15 @@
+/**
+ * POST /api/workshop/dcw/runs/:id/close —— 关闭批次(结束数据隔离窗口)。
+ */
+import { getRouterParam } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { bindDcwBroadcast, getDcwController } from '@/server/services/workshop/dcw/dcw-controller'
+import { broadcastSceneEvent } from '@/server/services/workshop/scene-events'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  bindDcwBroadcast(broadcastSceneEvent)
+  const id = getRouterParam(event, 'id') ?? ''
+  return { run: getDcwController().closeRun(id) }
+})

package/server/api/workshop/dcw/runs/[id]/data.get.ts

@@ -0,0 +1,15 @@
+/**
+ * GET /api/workshop/dcw/runs/:id/data —— 批次数据视图(数采汇总 + 写历史,窗口隔离)。
+ */
+import { getRouterParam } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { bindDcwBroadcast, getDcwController } from '@/server/services/workshop/dcw/dcw-controller'
+import { broadcastSceneEvent } from '@/server/services/workshop/scene-events'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  bindDcwBroadcast(broadcastSceneEvent)
+  const id = getRouterParam(event, 'id') ?? ''
+  return await getDcwController().runData(id)
+})

package/server/api/workshop/dcw/runs/[id]/rollback.post.ts

@@ -0,0 +1,20 @@
+/**
+ * POST /api/workshop/dcw/runs/:id/rollback —— 批次级回退(撤销这次实验)。
+ * 恢复该 run 涉及节点在 run.startedAt 之前的值(账本最近批次前稳定锚)。
+ */
+import { getRouterParam } from 'h3'
+import { requireRole } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { bindDcwBroadcast } from '@/server/services/workshop/dcw/dcw-controller'
+import { broadcastSceneEvent } from '@/server/services/workshop/scene-events'
+import { getRecipeRollBackManager } from '@/server/services/workshop/dcw/recipe-rollback-manager'
+import { audit } from '@/server/services/workshop/ops/ops'
+
+export default defineApiHandler(async (event) => {
+  const user = requireRole(event)
+  bindDcwBroadcast(broadcastSceneEvent)
+  const id = getRouterParam(event, 'id') ?? ''
+  const outcomes = await getRecipeRollBackManager().rollbackRun(id, user.id)
+  audit({ actor: user.id, actorName: user.name, actorKind: 'user', action: 'dcw.run.rollback', targetKind: 'recipe-run', targetId: id, detail: { outcomes } })
+  return { outcomes }
+})

package/server/api/workshop/dcw/runs/index.get.ts

@@ -0,0 +1,11 @@
+/**
+ * GET /api/workshop/dcw/runs —— 生产批次列表。
+ */
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDcwRecipeRepo } from '@/server/services/workshop/dcw/dcw-recipe.repo'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  return { runs: getDcwRecipeRepo().listRuns() }
+})

package/server/api/workshop/dcw/templates/[key].delete.ts

@@ -0,0 +1,14 @@
+/**
+ * DELETE /api/workshop/dcw/templates/:key —— 删除自定义控制模板(内置拒绝)。
+ */
+import { getRouterParam } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDcwTemplateRegistry } from '@/server/services/workshop/dcw/dcw-templates'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const key = getRouterParam(event, 'key') ?? ''
+  const removed = getDcwTemplateRegistry().remove(key)
+  return { removed: removed.key }
+})

package/server/api/workshop/dcw/templates/[key].patch.ts

@@ -0,0 +1,16 @@
+/**
+ * PATCH /api/workshop/dcw/templates/:key —— 编辑自定义控制模板(内置拒绝)。
+ */
+import { getRouterParam, readBody } from 'h3'
+import type { DcwTemplateInput } from '#shared/dcw-protocol'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDcwTemplateRegistry } from '@/server/services/workshop/dcw/dcw-templates'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const key = getRouterParam(event, 'key') ?? ''
+  const body = (await readBody(event) ?? {}) as Partial<DcwTemplateInput>
+  const template = getDcwTemplateRegistry().update(key, body)
+  return { template }
+})

package/server/api/workshop/dcw/templates/index.post.ts

@@ -0,0 +1,15 @@
+/**
+ * POST /api/workshop/dcw/templates —— 新建自定义控制模板。
+ */
+import { readBody } from 'h3'
+import type { DcwTemplateInput } from '#shared/dcw-protocol'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDcwTemplateRegistry } from '@/server/services/workshop/dcw/dcw-templates'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const body = (await readBody(event) ?? {}) as DcwTemplateInput
+  const template = getDcwTemplateRegistry().create(body)
+  return { template }
+})

package/server/api/workshop/dcw/test-driver.post.ts

@@ -0,0 +1,16 @@
+/**
+ * POST /api/workshop/dcw/test-driver —— 连接测试(body: { driver, driverConfig })。
+ */
+import { readBody } from 'h3'
+import type { DcwDriverKind } from '#shared/dcw-protocol'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { bindDcwBroadcast, getDcwController } from '@/server/services/workshop/dcw/dcw-controller'
+import { broadcastSceneEvent } from '@/server/services/workshop/scene-events'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  bindDcwBroadcast(broadcastSceneEvent)
+  const body = await readBody<{ driver?: DcwDriverKind, driverConfig?: Record<string, unknown> }>(event) ?? {}
+  return { test: await getDcwController().testDriver(body.driver ?? 'mock', body.driverConfig ?? {}) }
+})

package/server/api/workshop/device-twins/[id]/control.post.ts

@@ -0,0 +1,21 @@
+/**
+ * POST /api/workshop/device-twins/:id/control —— 下发设备指令(模拟域)。
+ * - Bearer 用户 token;body: { command, args? }
+ * - 等价于 MCP device.control 的用户面入口
+ * - 返回 { twin }
+ */
+import { getRouterParam, readBody } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDeviceTwinRepo } from '@/server/services/workshop/assets/device-twin.repo'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const id = getRouterParam(event, 'id')!
+  const body = await readBody<{ command?: string, args?: Record<string, unknown> }>(event)
+  if (!body?.command) throw new AppError(400, 'BAD_REQUEST', 'command 必填')
+  const twin = getDeviceTwinRepo().applyControl(id, body.command, body.args ?? {})
+  if (!twin) throw new AppError(404, 'NOT_FOUND', `设备不存在: ${id}`)
+  return { twin }
+})

package/server/api/workshop/device-twins/[id]/telemetry.post.ts

@@ -0,0 +1,21 @@
+/**
+ * POST /api/workshop/device-twins/:id/telemetry —— 数字孪生数据采集(采集器/Agent 推送)。
+ * - Bearer 用户 token;body: { telemetry: Record<string, number|string|boolean> }
+ * - 也可由外部采集器接入(真实设备 OPC-UA/MQTT 采集器把数据推到这里)
+ * - 返回 { twin, derived: { state } }
+ */
+import { getRouterParam, readBody } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDeviceTwinRepo } from '@/server/services/workshop/assets/device-twin.repo'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const id = getRouterParam(event, 'id')!
+  const body = await readBody<{ telemetry?: Record<string, unknown> }>(event)
+  if (!body?.telemetry || typeof body.telemetry !== 'object') throw new AppError(400, 'BAD_REQUEST', 'telemetry 必填(object)')
+  const twin = getDeviceTwinRepo().applyTelemetry(id, body.telemetry as Record<string, number | string | boolean>)
+  if (!twin) throw new AppError(404, 'NOT_FOUND', `设备不存在: ${id}`)
+  return { twin, derived: { state: twin.state } }
+})

package/server/api/workshop/device-twins/[id].delete.ts

@@ -0,0 +1,25 @@
+/**
+ * DELETE /api/workshop/device-twins/:id —— 删除数字孪生设备。
+ * 删除前广播 device.deleted(其他小镇客户端即时移除场景节点)。
+ */
+import { getRouterParam } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDeviceTwinRepo } from '@/server/services/workshop/assets/device-twin.repo'
+import { getDaqController } from '@/server/services/workshop/daq/daq-controller'
+import { getDcwController } from '@/server/services/workshop/dcw/dcw-controller'
+import { broadcastSceneEvent } from '@/server/services/workshop/scene-events'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const id = getRouterParam(event, 'id')!
+  const twin = getDeviceTwinRepo().findById(id)
+  const ok = getDeviceTwinRepo().remove(id)
+  if (!ok) throw new AppError(404, 'NOT_FOUND', `设备不存在: ${id}`)
+  // 级联解绑其 DAQ 采集节点与 DCW 控制节点 + 广播节点变更
+  getDaqController().unbindDevice(id)
+  getDcwController().unbindDevice(id)
+  broadcastSceneEvent('device.deleted', { id, name: twin?.name ?? '' })
+  return { deleted: true }
+})

package/server/api/workshop/device-twins/[id].patch.ts

@@ -0,0 +1,29 @@
+/**
+ * PATCH /api/workshop/device-twins/:id —— 更新数字孪生设备(含 3D 场景落点 transform)。
+ * - Bearer 用户 token;body: { name?, modelRef?, posX?, posZ?, rotationY?, scale? }
+ * - 落点坐标/朝向/缩放由 3D 小镇编辑模式拖拽/滑杆结束防抖写入;
+ * - 更新后广播 device.updated(全部已连 peer,其他小镇客户端即时同步场景节点)。
+ */
+import { getRouterParam, readBody } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDeviceTwinRepo, deviceScenePayload } from '@/server/services/workshop/assets/device-twin.repo'
+import { broadcastSceneEvent } from '@/server/api/workshop/ws'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const id = getRouterParam(event, 'id')!
+  const body = await readBody<{ name?: string, modelRef?: string, posX?: number, posZ?: number, rotationY?: number, scale?: number }>(event)
+  const twin = getDeviceTwinRepo().update(id, {
+    name: typeof body?.name === 'string' && body.name.trim() ? body.name.trim() : undefined,
+    modelRef: typeof body?.modelRef === 'string' ? body.modelRef.trim() : undefined,
+    posX: typeof body?.posX === 'number' && Number.isFinite(body.posX) ? Math.round(body.posX * 10) / 10 : undefined,
+    posZ: typeof body?.posZ === 'number' && Number.isFinite(body.posZ) ? Math.round(body.posZ * 10) / 10 : undefined,
+    rotationY: typeof body?.rotationY === 'number' && Number.isFinite(body.rotationY) ? Math.round(body.rotationY * 10) / 10 : undefined,
+    scale: typeof body?.scale === 'number' && Number.isFinite(body.scale) && body.scale > 0 ? Math.round(body.scale * 100) / 100 : undefined,
+  })
+  if (!twin) throw new AppError(404, 'NOT_FOUND', `设备不存在: ${id}`)
+  broadcastSceneEvent('device.updated', deviceScenePayload(twin))
+  return { twin }
+})

package/server/api/workshop/device-twins/index.get.ts

@@ -0,0 +1,16 @@
+/**
+ * GET /api/workshop/device-twins —— 数字孪生设备列表。
+ * - Bearer 用户 token;?workspaceId= 可选作用域
+ * - 返回 { twins: DeviceTwin[] }
+ */
+import { getQuery } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDeviceTwinRepo } from '@/server/services/workshop/assets/device-twin.repo'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const q = getQuery(event)
+  const workspaceId = typeof q.workspaceId === 'string' ? q.workspaceId : ''
+  return { twins: getDeviceTwinRepo().listAll(workspaceId) }
+})

package/server/api/workshop/device-twins/index.post.ts

@@ -0,0 +1,32 @@
+/**
+ * POST /api/workshop/device-twins —— 创建数字孪生设备。
+ * - Bearer 用户 token;body: { name, modelRef?, workspaceId?, kind?, controls?, telemetry?, posX?, posZ?, rotationY?, scale? }
+ * - 创建后广播 device.created(3D 小镇拖入场景即建,其他客户端即时同步)。
+ * - 返回 { twin }
+ */
+import { readBody } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDeviceTwinRepo, deviceScenePayload, type DeviceTwin } from '@/server/services/workshop/assets/device-twin.repo'
+import { broadcastSceneEvent } from '@/server/api/workshop/ws'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const body = await readBody<{ name?: string, modelRef?: string, workspaceId?: string, kind?: string, controls?: string[], telemetry?: Record<string, unknown>, posX?: number, posZ?: number, rotationY?: number, scale?: number }>(event)
+  if (!body?.name?.trim()) throw new AppError(400, 'BAD_REQUEST', 'name 必填')
+  const twin = getDeviceTwinRepo().create({
+    name: body.name.trim(),
+    modelRef: body.modelRef ?? '',
+    workspaceId: body.workspaceId ?? '',
+    kind: (body.kind === 'environment' || body.kind === 'asset' || body.kind === 'daq' ? body.kind : 'device') as DeviceTwin['kind'],
+    controls: body.controls ?? [],
+    telemetry: (body.telemetry ?? {}) as Record<string, number | string | boolean>,
+    posX: typeof body.posX === 'number' && Number.isFinite(body.posX) ? Math.round(body.posX * 10) / 10 : undefined,
+    posZ: typeof body.posZ === 'number' && Number.isFinite(body.posZ) ? Math.round(body.posZ * 10) / 10 : undefined,
+    rotationY: typeof body.rotationY === 'number' && Number.isFinite(body.rotationY) ? Math.round(body.rotationY * 10) / 10 : undefined,
+    scale: typeof body.scale === 'number' && Number.isFinite(body.scale) && body.scale > 0 ? Math.round(body.scale * 100) / 100 : undefined,
+  })
+  broadcastSceneEvent('device.created', deviceScenePayload(twin))
+  return { twin }
+})

package/server/api/workshop/fs/dirs.get.ts

@@ -0,0 +1,40 @@
+/**
+ * GET /api/workshop/fs/dirs -- FileSelector 数据源:列出服务器上某目录的子目录。
+ * - Bearer 用户 token(本地 harness 工具面;仅返回目录名,不读文件内容)
+ * - path 缺省 = 项目根 process.cwd();非法/不存在 -> 400
+ * - 返回 { cwd, parent, dirs: [{ name, path, hasChildren }] }(仅目录,排序:目录名 ASC)
+ */
+import { readdirSync } from 'node:fs'
+import { resolve, dirname, isAbsolute, join } from 'node:path'
+import { getQuery } from 'h3'
+import { resolveUser } from '../caller'
+import { AppError } from '../../../utils/errors'
+import { defineApiHandler } from '../../../utils/response'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const q = getQuery(event)
+  const raw = typeof q.path === 'string' ? q.path.trim() : ''
+  const cwd = raw ? resolve(raw) : process.cwd()
+  let entries: import('node:fs').Dirent[]
+  try {
+    entries = readdirSync(cwd, { withFileTypes: true })
+  }
+  catch (err) {
+    throw new AppError(400, 'FS_READ_FAILED', `目录不可读: ${cwd}(${err instanceof Error ? err.message : String(err)})`)
+  }
+  const dirs = entries
+    .filter(e => e.isDirectory() && !e.name.startsWith('.'))
+    .map((e) => {
+      const full = join(cwd, e.name)
+      let hasChildren = false
+      try {
+        hasChildren = readdirSync(full, { withFileTypes: true }).some(x => x.isDirectory())
+      }
+      catch { /* 无权限视为叶子 */ }
+      return { name: e.name, path: full, hasChildren }
+    })
+    .sort((a, b) => a.name.localeCompare(b.name))
+  const parent = dirname(cwd) !== cwd ? dirname(cwd) : null
+  return { cwd, parent, isAbsoluteRoot: !isAbsolute(cwd), dirs }
+})

package/server/api/workshop/mailbox/all.get.ts

@@ -0,0 +1,19 @@
+/**
+ * GET /api/workshop/mailbox/all —— (仅 lead)Channel 邮件全览:REST 作业面,与 MCP workshop.mail.list 同语义。
+ * 返回全部 agent 间消息(含已消费/任务投递),按时间倒序;可选 agentId 过滤参与方。
+ * - 需要 Bearer token(caller 由 token 决定);非 lead 调用 → 403 SCOPE_VIOLATION(manager 校验)
+ */
+import { defineApiHandler } from '../../../utils/response'
+import { getWorkshopManager } from '../../../plugins/workshop'
+import { resolveCaller } from '../caller'
+
+export default defineApiHandler(async (event) => {
+  const caller = resolveCaller(event)
+  const url = new URL(event.path, 'http://localhost')
+  const limit = Number.parseInt(url.searchParams.get('limit') ?? '200', 10)
+  const agentId = url.searchParams.get('agentId') ?? undefined
+  return getWorkshopManager().listChannelMail(caller.channelId, caller.id, {
+    limit: Number.isFinite(limit) && limit > 0 ? limit : 200,
+    agentId,
+  })
+})

package/server/api/workshop/mailbox.get.ts

@@ -0,0 +1,14 @@
+/**
+ * GET /api/workshop/mailbox —— 拉取 caller 自己的未消费消息(REST 作业面,与 MCP workshop.a2a.poll 同语义)。
+ * - 需要 Bearer token;返回 mailbox 中 pending 消息(不改状态,消费由 AgentRuntime 循环完成)
+ */
+import { defineApiHandler } from '../../utils/response'
+import { getWorkshopManager } from '../../plugins/workshop'
+import { resolveCaller } from './caller'
+
+export default defineApiHandler(async (event) => {
+  const caller = resolveCaller(event)
+  const url = new URL(event.path, 'http://localhost')
+  const limit = Number.parseInt(url.searchParams.get('limit') ?? '50', 10)
+  return getWorkshopManager().pollMailbox(caller.channelId, caller.id, Number.isFinite(limit) && limit > 0 ? limit : 50)
+})

package/server/api/workshop/memories/maintenance.post.ts

@@ -0,0 +1,15 @@
+/**
+ * POST /api/workshop/memories/maintenance —— 手动触发记忆衰减清理(lead)。
+ * - 需要 Bearer token;仅 lead 可触发(403 SCOPE_VIOLATION)
+ * - 与定时器同一策略函数,返回 { deletedExpired, evicted, cleanedVec }
+ */
+import { AppError } from '../../../utils/errors'
+import { defineApiHandler } from '../../../utils/response'
+import { getWorkshopManager } from '../../../plugins/workshop'
+import { resolveCaller } from '../caller'
+
+export default defineApiHandler(async (event) => {
+  const caller = resolveCaller(event)
+  if (caller.role !== 'lead') throw new AppError(403, 'SCOPE_VIOLATION', '仅 lead 可触发记忆维护')
+  return getWorkshopManager().runMemoryMaintenanceNow()
+})

package/server/api/workshop/ops-logs/index.get.ts

@@ -0,0 +1,30 @@
+/**
+ * GET /api/workshop/ops-logs —— 运维日志查询(全操作统一记录)。
+ * 维度隔离:lineId / productId / recipeId + 来源 actorKind + 分类 kind + 关键词 q + 时间区间。
+ * 返回 { logs: [...], count }。行结构 = audit_log 投影(id/actor/actorKind/kind/summary/detailJson…)。
+ */
+import { getQuery } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { getOps } from '../../../services/workshop/ops/ops'
+import { AppError } from '../../../utils/errors'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const repo = getOps()?.audit
+  if (!repo)
+    throw new AppError(503, 'UNAVAILABLE', '运维日志仓储未就绪')
+  const q = getQuery(event) as Record<string, string | undefined>
+  const logs = repo.query({
+    lineId: q.lineId || undefined,
+    productId: q.productId || undefined,
+    recipeId: q.recipeId || undefined,
+    actorKind: q.actorKind || undefined,
+    kind: q.kind || undefined,
+    q: q.q || undefined,
+    from: q.from || undefined,
+    to: q.to || undefined,
+    limit: Math.min(500, Number(q.limit ?? 200) || 200),
+  })
+  return { logs, count: logs.length }
+})

package/server/api/workshop/ops-logs/index.post.ts

@@ -0,0 +1,39 @@
+/**
+ * POST /api/workshop/ops-logs —— 人工手动记录事件(运维数字化:值班记录/现场处置/备注)。
+ * body: { summary(必填), lineId?, productId?, recipeId?, detail? }
+ * 入 audit_log(kind='manual')+ 广播 ops.log 实时帧,与自动操作同一流水可联合查询。
+ */
+import { readBody } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { AppError, ErrorCodes } from '../../../utils/errors'
+import { recordOps } from '../../../services/workshop/ops/ops'
+
+export default defineApiHandler(async (event) => {
+  const user = resolveUser(event)
+  const body = await readBody<{
+    summary?: string
+    lineId?: string
+    productId?: string
+    recipeId?: string
+    detail?: Record<string, unknown>
+  }>(event) ?? {}
+  const summary = String(body.summary ?? '').trim()
+  if (!summary)
+    throw new AppError(400, ErrorCodes.VALIDATION_ERROR, '手动记录内容(summary)不能为空')
+  recordOps({
+    actor: user.id,
+    actorName: user.name,
+    actorKind: 'user',
+    action: 'ops.manual',
+    kind: 'manual',
+    targetKind: 'manual-log',
+    targetId: '',
+    summary,
+    lineId: body.lineId ?? '',
+    productId: body.productId ?? '',
+    recipeId: body.recipeId ?? '',
+    detail: { manual: true, ...(body.detail ?? {}) },
+  })
+  return { ok: true }
+})

package/server/api/workshop/runtime.get.ts

@@ -0,0 +1,11 @@
+/**
+ * GET /api/workshop/runtime —— 运行时装配状态(已装配 agent / 活跃 channel 数)。
+ * 前端调试懒加载与内存回收用。
+ */
+import { defineApiHandler } from '../../utils/response'
+import { resolveUser } from './caller'
+import { getWorkshopManager } from '../../plugins/workshop'
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  return getWorkshopManager().runtimeStatus()
+})

package/server/api/workshop/scene/layouts/[channelId].delete.ts

@@ -0,0 +1,23 @@
+/**
+ * DELETE /api/workshop/scene/layouts/:channelId —— 取消频道领地放置(从 3D 小镇移除)。
+ * - Bearer 用户 token;校验 channel 属主;广播 scene.layout.removed(客户端移除领地+其 Agent)。
+ */
+import { getRouterParam } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { defineApiHandler } from '@/server/utils/response'
+import { getWorkshopManager } from '@/server/plugins/workshop'
+import { getSceneLayoutRepo } from '@/server/services/workshop/scene/scene-layout.repo'
+import { publishSceneLayoutEvent } from '@/server/api/workshop/ws'
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'channelId')!
+  const manager = getWorkshopManager()
+  const user = resolveUser(event)
+  const channel = manager.getChannelForUser(channelId, user.id)
+  manager.requireWritable(channel.ownerUserId, user, 'channel')
+  const ok = getSceneLayoutRepo().remove(channelId)
+  if (!ok) throw new AppError(404, 'NOT_FOUND', `频道未放置: ${channelId}`)
+  publishSceneLayoutEvent(manager, channelId, 'scene.layout.removed', { channelId })
+  return { deleted: true }
+})

package/server/api/workshop/scene/layouts/[channelId].put.ts

@@ -0,0 +1,31 @@
+/**
+ * PUT /api/workshop/scene/layouts/:channelId —— 放置/更新频道领地(3D 小镇)。
+ * - Bearer 用户 token;body: { x, z, radiusX, radiusZ, shape?, rotationY? }
+ * - 校验 channel 属主;变更经该频道频道流广播 scene.layout.saved(其他小镇客户端即时同步)。
+ */
+import { getRouterParam, readBody } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { getWorkshopManager } from '@/server/plugins/workshop'
+import { getSceneLayoutRepo } from '@/server/services/workshop/scene/scene-layout.repo'
+import { publishSceneLayoutEvent } from '@/server/api/workshop/ws'
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'channelId')!
+  const body = await readBody<{ x?: number, z?: number, radiusX?: number, radiusZ?: number, shape?: string, rotationY?: number }>(event)
+  const manager = getWorkshopManager()
+  const user = resolveUser(event)
+  const channel = manager.getChannelForUser(channelId, user.id)
+  manager.requireWritable(channel.ownerUserId, user, 'channel')
+
+  const layout = getSceneLayoutRepo().upsert(channelId, {
+    x: typeof body?.x === 'number' && Number.isFinite(body.x) ? body.x : 0,
+    z: typeof body?.z === 'number' && Number.isFinite(body.z) ? body.z : 0,
+    radiusX: typeof body?.radiusX === 'number' && Number.isFinite(body.radiusX) ? body.radiusX : 180,
+    radiusZ: typeof body?.radiusZ === 'number' && Number.isFinite(body.radiusZ) ? body.radiusZ : 120,
+    shape: body?.shape === 'rect' ? 'rect' : 'ellipse',
+    rotationY: typeof body?.rotationY === 'number' && Number.isFinite(body.rotationY) ? body.rotationY : 0,
+  })
+  publishSceneLayoutEvent(manager, channelId, 'scene.layout.saved', layout)
+  return { layout }
+})