agentworkshop 0.2.1

package/server/api/workshop/channels/[id]/agents/[agentId]/range.patch.ts

@@ -0,0 +1,54 @@
+/**
+ * PATCH /api/workshop/channels/:id/agents/:agentId/range —— 管理员布局:保存 Agent 独立活动范围。
+ * - Bearer 用户 token;body: { range?: { x, z, radiusX, radiusZ, shape?, rotationY? } | null }
+ * - 写入 config.range(config 合并,不覆盖 modelRef/homeX 等既有字段);range 缺省/null → 清除(回退频道边界);
+ * - 经既有 updateChannelAgent 持久化并 AEP agent.member(op=updated) 回流前端(town 重建即按新范围落位)。
+ */
+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 { getWorkshopManager } from '@/server/plugins/workshop'
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const agentId = getRouterParam(event, 'agentId')!
+  const body = await readBody<{ range?: unknown }>(event)
+  const manager = getWorkshopManager()
+  const user = resolveUser(event)
+  const channel = manager.getChannelForUser(channelId, user.id)
+  manager.requireWritable(channel.ownerUserId, user, 'channel')
+  const members = await manager.listChannelAgents(channelId)
+  const agent = members.find(a => a.id === agentId)
+  if (!agent) throw new AppError(404, 'NOT_FOUND', `成员不存在: ${agentId}`)
+
+  // 合并写入,保留 modelRef/homeX 等既有 config;range 缺省/null/非法 → 清除对应活动范围
+  const config = { ...(agent.config ?? {}) }
+  const raw = body?.range
+  if (raw && typeof raw === 'object') {
+    const r = raw as Record<string, unknown>
+    const num = (v: unknown): number | undefined => (typeof v === 'number' && Number.isFinite(v) ? v : undefined)
+    const x = num(r.x)
+    const z = num(r.z)
+    const radiusX = num(r.radiusX)
+    const radiusZ = num(r.radiusZ)
+    if (x !== undefined && z !== undefined && radiusX !== undefined && radiusZ !== undefined) {
+      config.range = {
+        x: Math.round(x * 10) / 10,
+        z: Math.round(z * 10) / 10,
+        radiusX: Math.max(30, Math.round(radiusX * 10) / 10),
+        radiusZ: Math.max(30, Math.round(radiusZ * 10) / 10),
+        shape: r.shape === 'rect' ? 'rect' : 'ellipse',
+        rotationY: Math.round((num(r.rotationY) ?? 0) * 10) / 10,
+      }
+    }
+    else {
+      delete config.range
+    }
+  }
+  else {
+    delete config.range
+  }
+  await manager.updateChannelAgent(agentId, { config }, { channelId, by: 'user', reason: 'range' })
+  return { agentId, name: agent.name, config }
+})

package/server/api/workshop/channels/[id]/agents/[agentId]/stop.post.ts

@@ -0,0 +1,25 @@
+/**
+ * POST /api/workshop/channels/:id/agents/:agentId/stop —— HITL 独立中断指定成员运行时。
+ * worker/lead 均可;lead 停止同时停调度循环,下次任务提交自动重激活。
+ * 成员行保留(interrupt 语义),运行时强制 stop + detach;变更经 AEP agent.member 广播。
+ * - channel/成员不存在 → 404;非属主 → 403
+ */
+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'
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const agentId = getRouterParam(event, 'agentId')!
+  const manager = getWorkshopManager()
+  const user = resolveUser(event)
+  const channel = manager.getChannelForUser(channelId, user.id)
+  manager.requireWritable(channel.ownerUserId, user, 'channel')
+  const members = await manager.listChannelAgents(channelId)
+  if (!members.some(a => a.id === agentId)) {
+    throw new AppError(404, 'NOT_FOUND', `成员不存在: ${agentId}`)
+  }
+  return manager.stopAgentRuntime(channelId, agentId, 'user')
+})

package/server/api/workshop/channels/[id]/agents/[agentId].delete.ts

@@ -0,0 +1,23 @@
+/**
+ * DELETE /api/workshop/channels/:id/agents/:agentId —— 从 channel 移除成员(仅删关系,不删 Agent 定义)。
+ * - channel/成员不存在 → 404 NOT_FOUND
+ */
+import { getRouterParam } from 'h3'
+
+import { resolveUser } from '../../../caller'
+import { AppError } from '../../../../../utils/errors'
+import { defineApiHandler } from '../../../../../utils/response'
+import { getWorkshopManager } from '../../../../../plugins/workshop'
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const agentId = getRouterParam(event, 'agentId')!
+  const manager = getWorkshopManager()
+  const user = resolveUser(event)
+  const channel = manager.getChannelForUser(channelId, user.id)
+  manager.requireWritable(channel.ownerUserId, user, 'channel')
+  const members = await manager.listChannelAgents(channelId)
+  if (!members.some(a => a.id === agentId)) throw new AppError(404, 'NOT_FOUND', `成员不存在: ${agentId}`)
+  await manager.removeAgentFromChannel(channelId, agentId)
+  return { ok: true }
+})

package/server/api/workshop/channels/[id]/agents/[agentId].patch.ts

@@ -0,0 +1,28 @@
+/**
+ * PATCH /api/workshop/channels/:id/agents/:agentId —— 更新 channel 成员实例(name/config/enabled)。
+ * 变更后运行时卸载,下次任务按新配置重载;成功经 AEP agent.member(op=updated) 事件广播。
+ * - channel/成员不存在 → 404 NOT_FOUND;非属主 → 403
+ */
+import { getRouterParam, readBody } from 'h3'
+import { resolveUser } from '../../../caller'
+import { AppError } from '../../../../../utils/errors'
+import { defineApiHandler } from '../../../../../utils/response'
+import { getWorkshopManager } from '../../../../../plugins/workshop'
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const agentId = getRouterParam(event, 'agentId')!
+  const body = await readBody<{ name?: string, config?: Record<string, unknown>, enabled?: number, reason?: string }>(event)
+  const manager = getWorkshopManager()
+  const user = resolveUser(event)
+  const channel = manager.getChannelForUser(channelId, user.id)
+  manager.requireWritable(channel.ownerUserId, user, 'channel')
+  const members = await manager.listChannelAgents(channelId)
+  if (!members.some(a => a.id === agentId)) throw new AppError(404, 'NOT_FOUND', `成员不存在: ${agentId}`)
+  const patch: { name?: string, config?: Record<string, unknown>, enabled?: number } = {}
+  if (typeof body?.name === 'string' && body.name.trim()) patch.name = body.name.trim()
+  if (body?.config && typeof body.config === 'object') patch.config = body.config
+  if (body?.enabled === 0 || body?.enabled === 1) patch.enabled = body.enabled
+  const agent = await manager.updateChannelAgent(agentId, patch, { channelId, by: 'user', reason: body?.reason })
+  return { agentId: agent.id, name: agent.name, harness: agent.harness, role: agent.role }
+})

package/server/api/workshop/channels/[id]/agents/index.get.ts

@@ -0,0 +1,27 @@
+/**
+ * GET /api/workshop/channels/:id/agents —— channel 成员列表。
+ * 双轨鉴权:用户 token(owner/遗留公共可见)或 agent token(本 channel 成员)。
+ * - channel 不存在 → 404 NOT_FOUND
+ */
+import { getRouterParam } from 'h3'
+import { resolveUser, resolveCallerOrNull } from '../../../caller'
+import { defineApiHandler } from '../../../../../utils/response'
+import { AppError } from '../../../../../utils/errors'
+import { getWorkshopManager } from '../../../../../plugins/workshop'
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const manager = getWorkshopManager()
+  // 双轨:优先按用户 token;无用户 token 时接受本 channel 成员的 agent token
+  try {
+    const user = resolveUser(event)
+    manager.getChannelForUser(channelId, user.id)
+  }
+  catch (err) {
+    const caller = resolveCallerOrNull(event)
+    if (!caller || caller.channelId !== channelId) throw err
+  }
+  const channel = (await manager.listChannels()).find(c => c.id === channelId)
+  if (!channel) throw new AppError(404, 'NOT_FOUND', `channel 不存在: ${channelId}`)
+  return manager.listChannelAgents(channelId)
+})

package/server/api/workshop/channels/[id]/agents/index.post.ts

@@ -0,0 +1,61 @@
+/**
+ * POST /api/workshop/channels/:id/agents —— 在 channel 内放置 Agent 实例。
+ * - 提供 agentId:把该 Agent 模板克隆为独立身份 id 的新实例
+ * - 否则:一步创建 Agent 模板并克隆进 channel
+ * - role=lead 且已有 lead → 409 LEAD_EXISTS
+ */
+import { z } from 'zod'
+
+import { resolveUser } from '../../../caller'
+import { getRouterParam, readValidatedBody } from 'h3'
+import { zValidator } from '../../../../../utils/validate'
+import { defineApiHandler } from '../../../../../utils/response'
+import { AppError } from '../../../../../utils/errors'
+import { getWorkshopManager, ensureLeadSchedulerLoop } from '../../../../../plugins/workshop'
+
+const createAgentSchema = z.object({
+  agentId: z.string().min(1).optional(),
+  name: z.string().min(1).optional(),
+  harness: z.string().min(1).optional(),
+  role: z.enum(['lead', 'worker']).default('worker'),
+  config: z.record(z.string(), z.unknown()).optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const user = resolveUser(event)
+  const body = await readValidatedBody(event, zValidator(createAgentSchema))
+  const manager = getWorkshopManager()
+  const channel = (await manager.listChannels()).find(c => c.id === channelId)
+  if (!channel) throw new AppError(404, 'NOT_FOUND', `channel 不存在: ${channelId}`)
+
+  const ch = manager.getChannelForUser(channelId, user.id)
+  manager.requireWritable(ch.ownerUserId, user, 'channel')
+  const role = body.role ?? 'worker'
+  // 克隆模板时校验模板可读(属主/public 含内置/admin;他人 private → 403)
+  if (body.agentId) {
+    const tpl = manager.getAgent(body.agentId)
+    if (!tpl) throw new AppError(404, 'NOT_FOUND', `Agent 模板不存在: ${body.agentId}`)
+    manager.requireTemplateReadable(tpl, user, 'Agent 模板')
+  }
+  const agent = body.agentId
+    ? await manager.addAgentToChannel({
+        channelId,
+        agentId: body.agentId,
+        role,
+        // 克隆模板时允许覆盖 config(如注入/覆盖 systemPromptPrefix 场景提示词)
+        configOverride: body.config && Object.keys(body.config).length > 0 ? body.config : undefined,
+      })
+    : await (async () => {
+        if (!body.name || !body.harness) {
+          throw new AppError(400, 'BAD_REQUEST', '需提供 name+harness(新建模板)或 agentId(克隆已有模板)')
+        }
+        const tpl = await manager.createAgent({ name: body.name, harness: body.harness, config: body.config, ownerUserId: user.id })
+        return manager.addAgentToChannel({ channelId, agentId: tpl.id, role })
+      })()
+
+  if (role === 'lead') {
+    ensureLeadSchedulerLoop(manager, channelId)
+  }
+  return agent
+})

package/server/api/workshop/channels/[id]/events.get.ts

@@ -0,0 +1,55 @@
+/**
+ * GET /api/workshop/channels/:id/events —— AEP 事件持久化历史(server 驱动)。
+ * - Bearer 用户 token;channel 须为本人(或遗留公共只读)
+ * - 查询:limit(默认 200,上限 1000)/ beforeSeq(向上翻页)
+ *   / agentId(仅该 agent 的事件,lane 按需加载)
+ *   / excludeTypes(逗号分隔,剔除过程帧如 agent.delta —— 历史回放由落定帧携带全文)
+ * - 返回 AEP 信封同构帧(与 WS 增量无缝衔接;正序);total 与过滤条件同口径
+ */
+import { getRouterParam, getQuery } from 'h3'
+import { z } from 'zod'
+import { zValidator } from '../../../../utils/validate'
+import { defineApiHandler } from '../../../../utils/response'
+import { getWorkshopManager } from '../../../../plugins/workshop'
+import { resolveUser } from '../../caller'
+import type { ChannelEventRepo } from '../../../../services/workshop/db/channel-event.repo'
+
+const querySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(1000).default(200),
+  beforeSeq: z.coerce.number().int().min(0).optional(),
+  agentId: z.string().min(1).optional(),
+  excludeTypes: z.string().min(1).optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const user = resolveUser(event)
+  const manager = getWorkshopManager()
+  manager.getChannelForUser(channelId, user.id)
+  const q = await zValidator(querySchema)(getQuery(event))
+  const repo: ChannelEventRepo = (manager as unknown as { deps: { repos: { channelEvents: ChannelEventRepo } } }).deps.repos.channelEvents
+  const opts = {
+    agentId: q.agentId,
+    excludeTypes: q.excludeTypes?.split(',').map(s => s.trim()).filter(Boolean),
+  }
+  const before = q.beforeSeq
+  const limit = q.limit ?? 200
+  const items = before !== undefined && before > 0
+    ? repo.listBefore(channelId, before, limit, opts)
+    : repo.listRecent(channelId, limit, opts)
+  return {
+    channelId,
+    total: repo.count(channelId, opts),
+    maxSeq: repo.maxSeq(channelId),
+    items: items.map((e: { seq: number, type: string, at: string, agentId: string | null, taskId: string | null, payload: unknown }) => ({
+      v: 1,
+      type: e.type,
+      seq: e.seq,
+      at: e.at,
+      channelId,
+      ...(e.agentId ? { agentId: e.agentId } : {}),
+      ...(e.taskId ? { taskId: e.taskId } : {}),
+      payload: e.payload,
+    })),
+  }
+})

package/server/api/workshop/channels/[id]/index.get.ts

@@ -0,0 +1,18 @@
+/**
+ * GET /api/workshop/channels/:id —— channel 详情(含 workspace 与成员列表)。
+ * - channel 不存在 → 404 NOT_FOUND
+ */
+import { getRouterParam } from 'h3'
+import { resolveUser } from '../../caller'
+import { defineApiHandler } from '../../../../utils/response'
+import { getWorkshopManager, ensureLeadSchedulerLoop } from '../../../../plugins/workshop'
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const user = resolveUser(event)
+  const manager = getWorkshopManager()
+  manager.getChannelForUser(channelId, user.id) // 读取守卫(404/越权)
+  const channel = await manager.getChannel(channelId)
+  // 兜底:详情请求时确保 lead 的调度循环已装配(如启动恢复遗漏)
+  ensureLeadSchedulerLoop(manager, channelId)
+  return channel
+})

package/server/api/workshop/channels/[id]/index.patch.ts

@@ -0,0 +1,30 @@
+/**
+ * PATCH /api/workshop/channels/:id —— 更新 channel(name/description/workspace/enabled)。
+ * - channel 不存在 → 404 NOT_FOUND
+ * - workspace 变更确保目录存在并卸载已装配成员(cwd 重载)
+ * - enabled=0 停调度器并卸载全部成员
+ */
+import { z } from 'zod'
+import { resolveUser } from '../../caller'
+import { getRouterParam, readValidatedBody } from 'h3'
+import { zValidator } from '../../../../utils/validate'
+import { defineApiHandler } from '../../../../utils/response'
+import { getWorkshopManager } from '../../../../plugins/workshop'
+
+const patchChannelSchema = z.object({
+  name: z.string().min(1).optional(),
+  description: z.string().optional(),
+  scenarioPrompt: z.string().optional(),
+  workspace: z.string().min(1).optional(),
+  enabled: z.number().int().min(0).max(1).optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const user = resolveUser(event)
+  const body = await readValidatedBody(event, zValidator(patchChannelSchema))
+  const manager = getWorkshopManager()
+  const channel = manager.getChannelForUser(channelId, user.id)
+  manager.requireWritable(channel.ownerUserId, user, 'channel')
+  return manager.updateChannel(channelId, body)
+})

package/server/api/workshop/channels/[id]/memories/[memoryId].delete.ts

@@ -0,0 +1,29 @@
+/**
+ * DELETE /api/workshop/channels/:id/memories/:memoryId —— 删团队共享记忆(仅 lead)。
+ * - 需要 Bearer token;caller 须为本 channel 成员(跨 channel → 403 SCOPE_VIOLATION)
+ * - 仅 lead 可删(manager 校验);memoryId 不属于本 channel 团队行 → 404
+ */
+import { getRouterParam } from 'h3'
+import { AppError } from '../../../../../utils/errors'
+import { defineApiHandler } from '../../../../../utils/response'
+import { getWorkshopManager } from '../../../../../plugins/workshop'
+import { resolveAgentOrUser } from '../../../caller'
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const memoryId = getRouterParam(event, 'memoryId')!
+  // 双域鉴权:Agent 成员 token(作业面)或用户 token(控制台 owner)
+  const who = resolveAgentOrUser(event)
+  const manager = getWorkshopManager()
+  let byOwner = false
+  if (who.kind === 'agent') {
+    if (who.caller.channelId !== channelId) throw new AppError(403, 'SCOPE_VIOLATION', '仅本 channel 成员可删团队记忆')
+  }
+  else {
+    const ch = manager.getChannelForUser(channelId, who.user.id)
+    manager.requireOwned(ch.ownerUserId, who.user.id, 'channel')
+    byOwner = true
+  }
+  await manager.deleteTeamMemory(channelId, who.kind === 'agent' && !byOwner ? who.caller.id : '__team__', memoryId, { byOwner })
+  return { deleted: true, memoryId }
+})

package/server/api/workshop/channels/[id]/memories/index.get.ts

@@ -0,0 +1,28 @@
+/**
+ * GET /api/workshop/channels/:id/memories —— 团队共享记忆列表(channel 级)。
+ * - 需要 Bearer token;caller 须为本 channel 成员(跨 channel → 403 SCOPE_VIOLATION)
+ * - 任意本 channel 成员可读(全员 recall 同口径);channel 不存在 → 404(manager 校验)
+ */
+import { getRouterParam } from 'h3'
+import { AppError } from '../../../../../utils/errors'
+import { defineApiHandler } from '../../../../../utils/response'
+import { getWorkshopManager } from '../../../../../plugins/workshop'
+import { resolveAgentOrUser } from '../../../caller'
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  // 双域鉴权:Agent 成员 token(作业面)或用户 token(控制台 owner)
+  const who = resolveAgentOrUser(event)
+  const manager = getWorkshopManager()
+  let byOwner = false
+  if (who.kind === 'agent') {
+    if (who.caller.channelId !== channelId) throw new AppError(403, 'SCOPE_VIOLATION', '仅本 channel 成员可读团队记忆')
+  }
+  else {
+    const ch = manager.getChannelForUser(channelId, who.user.id)
+    manager.requireOwned(ch.ownerUserId, who.user.id, 'channel')
+    byOwner = true
+  }
+  void byOwner
+  return manager.listTeamMemories(channelId)
+})

package/server/api/workshop/channels/[id]/memories/index.post.ts

@@ -0,0 +1,42 @@
+/**
+ * POST /api/workshop/channels/:id/memories —— 写/更新团队共享记忆(lead 策展)。
+ * - 需要 Bearer token;caller 须为本 channel 成员(跨 channel → 403 SCOPE_VIOLATION)
+ * - 仅 lead 可写(manager 校验 → 403 SCOPE_VIOLATION);稳定 dedupKey 幂等刷新
+ */
+import { z } from 'zod'
+import { getRouterParam, readValidatedBody } from 'h3'
+import { zValidator } from '../../../../../utils/validate'
+import { AppError } from '../../../../../utils/errors'
+import { defineApiHandler } from '../../../../../utils/response'
+import { getWorkshopManager } from '../../../../../plugins/workshop'
+import { resolveAgentOrUser } from '../../../caller'
+
+const teamMemorySchema = z.object({
+  title: z.string().min(1, 'title 必填'),
+  content: z.string().min(1, 'content 必填'),
+  importance: z.number().min(0).max(1).optional(),
+  dedupKey: z.string().optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  // 双域鉴权:Agent 成员 token(作业面)或用户 token(控制台 owner)
+  const who = resolveAgentOrUser(event)
+  const manager = getWorkshopManager()
+  let byOwner = false
+  if (who.kind === 'agent') {
+    if (who.caller.channelId !== channelId) throw new AppError(403, 'SCOPE_VIOLATION', '仅本 channel 成员可写团队记忆')
+  }
+  else {
+    const ch = manager.getChannelForUser(channelId, who.user.id)
+    manager.requireOwned(ch.ownerUserId, who.user.id, 'channel')
+    byOwner = true
+  }
+  const body = await readValidatedBody(event, zValidator(teamMemorySchema))
+  return manager.addTeamMemory(channelId, who.kind === 'agent' && !byOwner ? who.caller.id : '__team__', {
+    title: body.title,
+    content: body.content,
+    importance: body.importance,
+    dedupKey: body.dedupKey,
+  }, { byOwner })
+})

package/server/api/workshop/channels/[id]/messages/index.get.ts

@@ -0,0 +1,56 @@
+/**
+ * GET /api/workshop/channels/:id/messages —— channel 消息历史(倒序,limit 默认 50)。
+ * - channel 不存在 → 404 NOT_FOUND
+ */
+import { z } from 'zod'
+import { resolveUser } from '../../../caller'
+import { getRouterParam, getQuery } from 'h3'
+import { zValidator } from '../../../../../utils/validate'
+import { defineApiHandler } from '../../../../../utils/response'
+import { AppError } from '../../../../../utils/errors'
+import { getWorkshopManager } from '../../../../../plugins/workshop'
+const querySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(500).default(50),
+})
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const query = await zValidator(querySchema)(getQuery(event))
+  const manager = getWorkshopManager()
+  const user = resolveUser(event)
+  manager.getChannelForUser(channelId, user.id)
+  const channel = (await manager.listChannels()).find(c => c.id === channelId)
+  if (!channel) throw new AppError(404, 'NOT_FOUND', `channel 不存在: ${channelId}`)
+
+  // 经 manager 内部 repos 拉取消息历史(倒序 → 正序返回)
+  const internal = manager as unknown as {
+    deps: { repos: { messages: { listRecentByChannel(channelId: string, limit: number): Array<{
+      id: string
+      channelId: string
+      taskId: string | null
+      fromAgentId: string | null
+      toAgentId: string | null
+      role: string
+      partsJson: string
+      metadataJson: string
+      state: string
+      createdAt: string
+      consumedAt: string | null
+    }> } } }
+  }
+  const rows = internal.deps.repos.messages.listRecentByChannel(channelId, query.limit ?? 50)
+  // 倒序返回最新在前(前端按需反转)
+  return rows.map(row => ({
+    id: row.id,
+    channelId: row.channelId,
+    taskId: row.taskId,
+    fromAgentId: row.fromAgentId,
+    toAgentId: row.toAgentId,
+    role: row.role,
+    parts: JSON.parse(row.partsJson),
+    metadata: JSON.parse(row.metadataJson),
+    state: row.state,
+    createdAt: row.createdAt,
+    consumedAt: row.consumedAt,
+  }))
+})

package/server/api/workshop/channels/[id]/messages/index.post.ts

@@ -0,0 +1,75 @@
+/**
+ * POST /api/workshop/channels/:id/messages —— 发送消息到 channel 内 agent。
+ * 两种优先级:
+ *  - immediate:目标 agent 忙碌时实时注入运行中的 omp 会话(steer)
+ *  - task(默认):进入目标 agent 的 mailbox 队列,等当前任务结束消费
+ * - 可带 fromAgentId(模拟某个 agent 发送);缺省为系统消息
+ */
+import { z } from 'zod'
+
+import { resolveUser } from '../../../caller'
+import { getRouterParam, readValidatedBody } from 'h3'
+import { zValidator } from '../../../../../utils/validate'
+import { defineApiHandler } from '../../../../../utils/response'
+
+import { getWorkshopManager } from '../../../../../plugins/workshop'
+
+const sendMessageSchema = z.object({
+  toAgentId: z.string().min(1, 'toAgentId 必填'),
+  text: z.string().min(1, 'text 必填'),
+  fromAgentId: z.string().optional(),
+  /** 人类发送者显示名(时间线 a2a.message 的发送者归属 → x-aw-from-label) */
+  fromLabel: z.string().max(120).optional(),
+  priority: z.enum(['immediate', 'task']).default('task'),
+  /** 触发器:要求接收方回执(执行结果 + 所需内容,in_reply_to 关联) */
+  requireReply: z.boolean().optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const user = resolveUser(event)
+  const body = await readValidatedBody(event, zValidator(sendMessageSchema))
+  const manager = getWorkshopManager()
+  const channel = manager.getChannelForUser(channelId, user.id)
+  manager.requireOwned(channel.ownerUserId, user.id, 'channel')
+
+  // 目标寻址(容错:精确实例 id / 模板 id / 名字 / 唯一名字前缀)
+  const target = manager.resolveChannelMember(channelId, body.toAgentId)
+  // 发送方身份校验:显式 fromAgentId 必须可解析到本 channel 成员 ——
+  // 伪造/已移除成员不再静默降级为人类消息(调用方意图是 agent 身份,降级会造成归属欺骗)
+  let fromAgentId = body.fromAgentId
+  if (fromAgentId) {
+    fromAgentId = manager.resolveChannelMember(channelId, fromAgentId).id
+  }
+
+  if (body.priority === 'immediate') {
+    return manager.sendImmediateMessage({
+      channelId,
+      fromAgentId: fromAgentId,
+      toAgentId: target.id,
+      parts: [{ text: body.text }],
+      requireReply: body.requireReply,
+      // 无主消息拦截 + 发送人语义:人类消息缺省发送人=登录用户名(时间线"用户章")
+      fromLabel: body.fromLabel ?? user.name,
+    })
+  }
+  // task 优先级:经 fromAgentId 身份走 sendA2A;无 fromAgentId 时用 immediate 通道(空闲即入队)
+  if (fromAgentId) {
+    return manager.sendA2A(channelId, fromAgentId, {
+      toAgentId: target.id,
+      parts: [{ text: body.text }],
+      metadata: {
+        'x-aw-msg-priority': 'task',
+        ...(body.requireReply ? { 'x-aw-require-reply': 'true' } : {}),
+      },
+    })
+  }
+  return manager.sendImmediateMessage({
+    channelId,
+    fromAgentId: '',
+    toAgentId: target.id,
+    parts: [{ text: body.text }],
+    requireReply: body.requireReply,
+    fromLabel: body.fromLabel ?? user.name,
+  })
+})

package/server/api/workshop/channels/[id]/queue.get.ts

@@ -0,0 +1,25 @@
+/**
+ * GET /api/workshop/channels/:id/queue —— Channel 队列总览(实时状态追踪)。
+ * 返回全员 status(idle/busy/stopped + 当前任务)+ 各自任务队列长度(待执行/已完成)。
+ * lead 统一调度与最优调配的观察面;channel 不存在 → 404,无 lead → 400 NO_LEAD_AGENT。
+ */
+import { getRouterParam } from 'h3'
+import { resolveUser } from '../../caller'
+import { AppError } from '../../../../utils/errors'
+import { defineApiHandler } from '../../../../utils/response'
+import { getWorkshopManager } from '../../../../plugins/workshop'
+import type { AgentStatusView } from '../../../../services/workshop/types/task'
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const manager = getWorkshopManager()
+  const user = resolveUser(event)
+  manager.getChannelForUser(channelId, user.id)
+  const channel = (await manager.listChannels()).find(c => c.id === channelId)
+  if (!channel) throw new AppError(404, 'NOT_FOUND', `channel 不存在: ${channelId}`)
+  if (!channel.leadAgentId) throw new AppError(400, 'NO_LEAD_AGENT', `channel ${channelId} 无 lead`)
+  // 外部观察视角:以 lead 成员身份查询(queueOverview 校验调用方为本 channel 成员)
+  const overview: AgentStatusView[]
+    = await manager.queueOverview(channelId, channel.leadAgentId)
+  return overview
+})

package/server/api/workshop/channels/[id]/tasks/index.get.ts

@@ -0,0 +1,24 @@
+/**
+ * GET /api/workshop/channels/:id/tasks —— 任务列表(含进度)(设计文档 §6.2)。
+ * manager 未公开 channel 级任务查询,经内部 TaskEngine 只读获取(与运行时同一实例)。
+ * channel 不存在 → 404 NOT_FOUND。
+ */
+import { getRouterParam } from 'h3'
+import { resolveUser } from '../../../caller'
+import { defineApiHandler } from '../../../../../utils/response'
+import { getWorkshopManager } from '../../../../../plugins/workshop'
+import type { AgentChannelManager } from '../../../../../services/workshop/runtime/manager'
+import type { TaskEngine } from '../../../../../services/workshop/runtime/agent-runtime'
+
+/** manager 未公开 TaskEngine 访问;经内部方法只读获取(类型收窄) */
+function taskEngineOf(manager: AgentChannelManager): TaskEngine {
+  return (manager as unknown as { getTaskEngine(): TaskEngine }).getTaskEngine()
+}
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const manager = getWorkshopManager()
+  const user = resolveUser(event)
+  manager.getChannelForUser(channelId, user.id)
+  return taskEngineOf(manager).list(channelId)
+})