agentworkshop 0.2.1

package/server/api/workshop/scene/layouts.get.ts

@@ -0,0 +1,13 @@
+/**
+ * GET /api/workshop/scene/layouts —— 频道领地放置清单(3D 小镇布局持久化)。
+ * - Bearer 用户 token;返回 { layouts: SceneLayout[] }
+ * - 前端按自己频道 id 过滤;empty = 场景尚未放置任何频道(初始场地)。
+ */
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { getSceneLayoutRepo } from '@/server/services/workshop/scene/scene-layout.repo'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  return { layouts: getSceneLayoutRepo().listAll() }
+})

package/server/api/workshop/tasks/[id]/cancel/index.post.ts

@@ -0,0 +1,34 @@
+/**
+ * POST /api/workshop/tasks/:id/cancel —— 取消任务(用户手动回收卡死任务)(设计文档 §6.2)。
+ * 用户/系统无 caller 身份时,以任务所在 channel 的 lead 身份取消(lead 可取消 channel 内任意任务);
+ * 已处终态的任务取消 → 400 INVALID_TRANSITION(manager 状态机校验)。
+ * - 任务不存在 → 404 NOT_FOUND
+ * - channel 无 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 { 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 taskId = getRouterParam(event, 'id')!
+  const manager = getWorkshopManager()
+  const task = taskEngineOf(manager).get(taskId)
+  if (!task) throw new AppError(404, 'NOT_FOUND', `任务不存在: ${taskId}`)
+  // 用户 owner 守卫:取消 = 写操作
+  const user = resolveUser(event)
+  const ch = manager.getChannelForUser(task.channelId, user.id)
+  manager.requireOwned(ch.ownerUserId, user.id, 'channel')
+  // 系统身份:任务所在 channel 的 lead
+  const agents = await manager.listChannelAgents(task.channelId)
+  const lead = agents.find(a => a.role === 'lead')
+  if (!lead) throw new AppError(400, 'NO_LEAD_AGENT', `channel ${task.channelId} 无 lead,无法以系统身份取消`)
+  return manager.cancelTask(lead.channelId, lead.id, { taskId })
+})

package/server/api/workshop/tasks/[id]/complete.post.ts

@@ -0,0 +1,32 @@
+/**
+ * POST /api/workshop/tasks/:id/complete —— assignee 完成任务并交付成果(REST 作业面,与 MCP workshop.task.complete 同语义)。
+ * - 需要 Bearer token;仅任务 assignee 可完成(manager 校验);完成后自动触发父任务汇总(若为子任务)
+ * - 任务需处于 WORKING 状态(ASSIGNED 未接取时完成 → 400 INVALID_TRANSITION)
+ */
+import { z } from 'zod'
+import { getRouterParam, readValidatedBody } from 'h3'
+import { zValidator } from '../../../../utils/validate'
+import { defineApiHandler } from '../../../../utils/response'
+import { getWorkshopManager } from '../../../../plugins/workshop'
+import { resolveCaller } from '../../caller'
+import type { A2AArtifact } from '../../../../services/workshop/types/a2a'
+
+/** 运行时校验与契约一致;zod 推断形状与契约存在无害差异,as 收窄 */
+const artifactSchema = z.object({
+  artifactId: z.string(),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  parts: z.array(z.unknown()),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}) as z.ZodType<A2AArtifact>
+
+const completeSchema = z.object({
+  artifacts: z.array(artifactSchema).optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const taskId = getRouterParam(event, 'id')!
+  const caller = resolveCaller(event)
+  const body = await readValidatedBody(event, zValidator(completeSchema))
+  return getWorkshopManager().completeTask(caller.channelId, caller.id, { taskId, artifacts: body.artifacts })
+})

package/server/api/workshop/tasks/[id]/dispatch.post.ts

@@ -0,0 +1,30 @@
+/**
+ * POST /api/workshop/tasks/:id/dispatch —— lead 分解并指派子任务(REST 作业面,与 MCP workshop.task.dispatch 同语义)。
+ * - 需要 Bearer token;仅 lead 可派发(manager 校验);父任务转 WAITING
+ */
+import { z } from 'zod'
+import { getRouterParam, readValidatedBody } from 'h3'
+import { zValidator } from '../../../../utils/validate'
+import { defineApiHandler } from '../../../../utils/response'
+import { getWorkshopManager } from '../../../../plugins/workshop'
+import { resolveCaller } from '../../caller'
+
+const dispatchSchema = z.object({
+  assigneeId: z.string().min(1, 'assigneeId 必填'),
+  title: z.string().min(1, 'title 必填'),
+  description: z.string().optional(),
+  parts: z.array(z.unknown()).optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const parentTaskId = getRouterParam(event, 'id')!
+  const caller = resolveCaller(event)
+  const body = await readValidatedBody(event, zValidator(dispatchSchema))
+  return getWorkshopManager().dispatchTask(caller.channelId, caller.id, {
+    parentTaskId,
+    assigneeId: body.assigneeId,
+    title: body.title,
+    description: body.description,
+    parts: body.parts as never,
+  })
+})

package/server/api/workshop/tasks/[id]/report.post.ts

@@ -0,0 +1,38 @@
+/**
+ * POST /api/workshop/tasks/:id/report —— assignee 上报任务进度/成果(REST 作业面,与 MCP workshop.task.report 同语义)。
+ * - 需要 Bearer token;仅任务 assignee 可上报(manager 校验)
+ */
+import { z } from 'zod'
+import { getRouterParam, readValidatedBody } from 'h3'
+import { zValidator } from '../../../../utils/validate'
+import { defineApiHandler } from '../../../../utils/response'
+import { getWorkshopManager } from '../../../../plugins/workshop'
+import { resolveCaller } from '../../caller'
+import type { A2AArtifact } from '../../../../services/workshop/types/a2a'
+
+/** 运行时校验与契约一致;zod 推断形状与契约存在无害差异,as 收窄 */
+const artifactSchema = z.object({
+  artifactId: z.string(),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  parts: z.array(z.unknown()),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}) as z.ZodType<A2AArtifact>
+
+const reportSchema = z.object({
+  progress: z.number().min(0).max(100).optional(),
+  artifact: artifactSchema.optional(),
+  message: z.string().optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const taskId = getRouterParam(event, 'id')!
+  const caller = resolveCaller(event)
+  const body = await readValidatedBody(event, zValidator(reportSchema))
+  return getWorkshopManager().reportTask(caller.channelId, caller.id, {
+    taskId,
+    progress: body.progress,
+    artifact: body.artifact,
+    message: body.message,
+  })
+})

package/server/api/workshop/tasks/[id]/retry.post.ts

@@ -0,0 +1,33 @@
+/**
+ * POST /api/workshop/tasks/:id/retry —— HITL 重试 FAILED 任务(lead/worker 任务均可)。
+ * 用户/系统无 caller 身份时,以任务所在 channel 的 lead 身份调用 manager.retryTask:
+ * 优先原 assignee,否则选队列最短空闲 worker,重新投递执行。
+ * - 任务不存在 → 404;任务非 FAILED → 400 INVALID_STATE
+ * - channel 无 lead → 400 NO_LEAD_AGENT;无可用 worker → 400 NO_WORKER
+ */
+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 type { AgentChannelManager } from '@/server/services/workshop/runtime/manager'
+import type { TaskEngine } from '@/server/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 taskId = getRouterParam(event, 'id')!
+  const manager = getWorkshopManager()
+  const task = taskEngineOf(manager).get(taskId)
+  if (!task) throw new AppError(404, 'NOT_FOUND', `任务不存在: ${taskId}`)
+  const user = resolveUser(event)
+  const ch = manager.getChannelForUser(task.channelId, user.id)
+  manager.requireOwned(ch.ownerUserId, user.id, 'channel')
+  const agents = await manager.listChannelAgents(task.channelId)
+  const lead = agents.find(a => a.role === 'lead')
+  if (!lead) throw new AppError(400, 'NO_LEAD_AGENT', `channel ${task.channelId} 无 lead,无法以系统身份重试`)
+  return manager.retryTask(lead.channelId, lead.id, taskId)
+})

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

@@ -0,0 +1,32 @@
+/**
+ * GET /api/workshop/tasks/:id —— 任务详情(含成果 artifacts/history)。
+ * - 无 token:管理面路径(用户手动查看)
+ * - 带 Bearer token:Agent 路径,经 manager.getTask 做同 channel 作用域校验(跨 channel → 403)
+ */
+import { getRouterParam } from 'h3'
+import { resolveCallerOrNull, resolveUser } from '../caller'
+import { AppError } from '../../../utils/errors'
+import { defineApiHandler } from '../../../utils/response'
+import { getWorkshopManager } from '../../../plugins/workshop'
+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 taskId = getRouterParam(event, 'id')!
+  const manager = getWorkshopManager()
+  const caller = resolveCallerOrNull(event)
+  if (caller) {
+    // Agent 路径:作用域校验(同 channel 可见,跨 channel 抛 SCOPE_VIOLATION)
+    return manager.getTask(caller.channelId, caller.id, taskId)
+  }
+  // 用户路径:channel 读取守卫(本人/遗留公共)
+  const user = resolveUser(event)
+  manager.getChannelForUser(taskEngineOf(manager).get(taskId)?.channelId ?? '', user.id)
+  const task = taskEngineOf(manager).get(taskId)
+  if (!task) throw new AppError(404, 'NOT_FOUND', `任务不存在: ${taskId}`)
+  return task
+})

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

@@ -0,0 +1,13 @@
+/**
+ * GET /api/workshop/tasks —— caller 所在 channel 的任务列表(带进度)。
+ * - 需要 Bearer token;作用域强制 caller 的 channel(跨 channel 不可见)
+ * - 与 /api/workshop/channels/:id/tasks(管理面,按 channelId)互补
+ */
+import { defineApiHandler } from '../../utils/response'
+import { getWorkshopManager } from '../../plugins/workshop'
+import { resolveCaller } from './caller'
+
+export default defineApiHandler(async (event) => {
+  const caller = resolveCaller(event)
+  return getWorkshopManager().listTasks(caller.channelId, caller.id)
+})

package/server/api/workshop/teams/[id]/deploy.post.ts

@@ -0,0 +1,40 @@
+/**
+ * POST /api/workshop/teams/:id/deploy —— 把 AgentTeam 批量部署到 channel。
+ * - body.channelId 必填;对每个成员模板克隆出独立身份 id 的新实例(同 addAgentToChannel)
+ * - team 无成员 → 400 TEAM_EMPTY
+ * - channel 已有 lead 且 team 成员含 lead → 409 LEAD_EXISTS(先前克隆的实例保留,调用方可删后重试)
+ * - 部署含 lead 的 team 后自动启动该 channel 的 SchedulerLoop(与单独放置 lead 同路径)
+ */
+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, ensureLeadSchedulerLoop } from '../../../../plugins/workshop'
+
+const deploySchema = z.object({
+  channelId: z.string().min(1, 'channelId 必填'),
+})
+
+export default defineApiHandler(async (event) => {
+  const teamId = getRouterParam(event, 'id')!
+  const user = resolveUser(event)
+  const body = await readValidatedBody(event, zValidator(deploySchema))
+  const manager = getWorkshopManager()
+  const team = manager.getTeam(teamId)
+  if (!team) throw new AppError(404, 'NOT_FOUND', `AgentTeam 不存在: ${teamId}`)
+  // 部署 = 克隆成员模板到本人 channel(不修改编组本身):
+  // 内置/公开编组允许任何人使用;私有编组仅属主/admin 可用
+  manager.requireTemplateReadable(team, user, 'AgentTeam')
+  // 成员模板同样需操作者可读(公开 team 含私有成员时非属主/admin 拒绝)
+  for (const m of team.members) {
+    const tpl = manager.getAgent(m.templateId)
+    if (tpl) manager.requireTemplateReadable(tpl, user, '成员 Agent 模板')
+  }
+  const ch = manager.getChannelForUser(body.channelId, user.id)
+  manager.requireWritable(ch.ownerUserId, user, 'channel')
+  // 部署后:若 channel 尚无调度循环(新 lead 就位)→ 启动
+  const result = await manager.deployTeamToChannel({ teamId, channelId: body.channelId })
+  ensureLeadSchedulerLoop(manager, body.channelId)
+  return result
+})

package/server/api/workshop/teams/[id]/members/[agentId].delete.ts

@@ -0,0 +1,19 @@
+/**
+ * DELETE /api/workshop/teams/:id/members/:agentId —— 从 AgentTeam 移除 Agent 模板。
+ * - 仅删编组关系;不动模板本身与其已部署实例
+ */
+import { getRouterParam } from 'h3'
+import { resolveUser } from '../../../caller'
+import { defineApiHandler } from '../../../../../utils/response'
+import { getWorkshopManager } from '../../../../../plugins/workshop'
+
+export default defineApiHandler(async (event) => {
+  const teamId = getRouterParam(event, 'id')!
+  const agentId = getRouterParam(event, 'agentId')!
+  const manager = getWorkshopManager()
+  const user = resolveUser(event)
+  const team = manager.getTeam(teamId)
+  if (!team) throw new AppError(404, 'NOT_FOUND', `AgentTeam 不存在: ${teamId}`)
+  manager.requireWritable(team.ownerUserId, user, 'AgentTeam')
+  return manager.removeTemplateFromTeam(teamId, agentId)
+})

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

@@ -0,0 +1,19 @@
+/**
+ * GET /api/workshop/teams/:id/members —— team 成员模板列表(快照含模板当前 name/harness)。
+ * 可见性:属主 / public(含内置)/ admin;他人 private → 403。(修复:原无守卫)
+ */
+import { getRouterParam } from 'h3'
+import { defineApiHandler } from '../../../../../utils/response'
+import { AppError } from '../../../../../utils/errors'
+import { resolveUser } from '../../../caller'
+import { getWorkshopManager } from '../../../../../plugins/workshop'
+
+export default defineApiHandler(async (event) => {
+  const teamId = getRouterParam(event, 'id')!
+  const manager = getWorkshopManager()
+  const team = manager.getTeam(teamId)
+  if (!team) throw new AppError(404, 'NOT_FOUND', `AgentTeam 不存在: ${teamId}`)
+  const user = resolveUser(event)
+  manager.requireTemplateReadable(team, user, 'AgentTeam')
+  return team.members
+})

package/server/api/workshop/teams/[id]/members/index.post.ts

@@ -0,0 +1,32 @@
+/**
+ * POST /api/workshop/teams/:id/members —— 把 Agent 模板加入 AgentTeam。
+ * - agentId 必填(全局 Agent 模板 id)
+ * - role 缺省 worker;team 内至多一个 lead(已有 → 409 LEAD_EXISTS)
+ * - 重复加入 → 409 ALREADY_MEMBER
+ */
+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 addMemberSchema = z.object({
+  agentId: z.string().min(1, 'agentId 必填'),
+  role: z.enum(['lead', 'worker']).optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const teamId = getRouterParam(event, 'id')!
+  const user = resolveUser(event)
+  const body = await readValidatedBody(event, zValidator(addMemberSchema))
+  const manager = getWorkshopManager()
+  const team = manager.getTeam(teamId)
+  if (!team) throw new AppError(404, 'NOT_FOUND', `AgentTeam 不存在: ${teamId}`)
+  manager.requireWritable(team.ownerUserId, user, 'AgentTeam')
+  return manager.addTemplateToTeam({
+    teamId,
+    templateId: body.agentId,
+    role: body.role,
+  })
+})

package/server/api/workshop/teams/[id].delete.ts

@@ -0,0 +1,20 @@
+/**
+ * DELETE /api/workshop/teams/:id —— 删除 AgentTeam(仅删编组关系;不动成员模板与已部署实例)。
+ * 权限:属主或 admin;内置编组任何人不可删除。
+ */
+import { getRouterParam } from 'h3'
+import { resolveUser } from '../caller'
+import { defineApiHandler } from '../../../utils/response'
+import { AppError } from '../../../utils/errors'
+import { getWorkshopManager } from '../../../plugins/workshop'
+
+export default defineApiHandler(async (event) => {
+  const teamId = getRouterParam(event, 'id')!
+  const manager = getWorkshopManager()
+  const user = resolveUser(event)
+  const team = manager.getTeam(teamId)
+  if (!team) throw new AppError(404, 'NOT_FOUND', `AgentTeam 不存在: ${teamId}`)
+  manager.requireWritable(team.ownerUserId, user, 'AgentTeam')
+  await manager.removeTeam(teamId)
+  return { removed: true, teamId }
+})

package/server/api/workshop/teams/[id].get.ts

@@ -0,0 +1,19 @@
+/**
+ * GET /api/workshop/teams/:id —— AgentTeam 详情(含成员模板快照)。
+ * 可见性:属主 / public(含内置)/ admin;他人 private → 403。(修复:原无守卫)
+ */
+import { getRouterParam } from 'h3'
+import { defineApiHandler } from '../../../utils/response'
+import { AppError } from '../../../utils/errors'
+import { resolveUser } from '../caller'
+import { getWorkshopManager } from '../../../plugins/workshop'
+
+export default defineApiHandler(async (event) => {
+  const teamId = getRouterParam(event, 'id')!
+  const manager = getWorkshopManager()
+  const team = manager.getTeam(teamId)
+  if (!team) throw new AppError(404, 'NOT_FOUND', `AgentTeam 不存在: ${teamId}`)
+  const user = resolveUser(event)
+  manager.requireTemplateReadable(team, user, 'AgentTeam')
+  return team
+})

package/server/api/workshop/teams/[id].patch.ts

@@ -0,0 +1,32 @@
+/**
+ * PATCH /api/workshop/teams/:id —— 更新 AgentTeam(name/description/visibility)。
+ * 权限:属主或 admin;内置编组任何人不可修改。(修复:原无认证与归属校验)
+ */
+import { z } from 'zod'
+import { getRouterParam, readValidatedBody } from 'h3'
+import { zValidator } from '../../../utils/validate'
+import { defineApiHandler } from '../../../utils/response'
+import { AppError } from '../../../utils/errors'
+import { resolveUser } from '../caller'
+import { getWorkshopManager } from '../../../plugins/workshop'
+
+const patchTeamSchema = z.object({
+  name: z.string().min(1).optional(),
+  description: z.string().optional(),
+  visibility: z.enum(['private', 'public']).optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const teamId = getRouterParam(event, 'id')!
+  const user = resolveUser(event)
+  const body = await readValidatedBody(event, zValidator(patchTeamSchema))
+  const manager = getWorkshopManager()
+  const team = manager.getTeam(teamId)
+  if (!team) throw new AppError(404, 'NOT_FOUND', `AgentTeam 不存在: ${teamId}`)
+  manager.requireWritable(team.ownerUserId, user, 'AgentTeam')
+  return manager.updateTeam(teamId, {
+    name: body.name,
+    description: body.description,
+    visibility: body.visibility,
+  })
+})

package/server/api/workshop/teams/index.get.ts

@@ -0,0 +1,13 @@
+/**
+ * GET /api/workshop/teams —— 可见性感知的 AgentTeam 列表。
+ * 普通用户:本人(任意可见性)+ 全部 public(含内置);admin:全量(附创建者名)。
+ */
+import { defineApiHandler } from '../../../utils/response'
+import { resolveUser, withOwnerNames } from '../caller'
+import { getWorkshopManager } from '../../../plugins/workshop'
+
+export default defineApiHandler(async (event) => {
+  const user = resolveUser(event)
+  const teams = await getWorkshopManager().listTeamsVisibleTo(user)
+  return withOwnerNames(teams)
+})

package/server/api/workshop/teams/index.post.ts

@@ -0,0 +1,27 @@
+/**
+ * POST /api/workshop/teams —— 创建 AgentTeam(Agent 模板编组容器)。
+ * visibility 缺省 private;public = 全员可读可用,仅属主/admin 可改删。
+ */
+import { z } from 'zod'
+import { resolveUser } from '../caller'
+import { readValidatedBody } from 'h3'
+import { zValidator } from '../../../utils/validate'
+import { defineApiHandler } from '../../../utils/response'
+import { getWorkshopManager } from '../../../plugins/workshop'
+
+const createTeamSchema = z.object({
+  name: z.string().min(1, 'name 必填'),
+  description: z.string().optional(),
+  visibility: z.enum(['private', 'public']).optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const user = resolveUser(event)
+  const body = await readValidatedBody(event, zValidator(createTeamSchema))
+  return getWorkshopManager().createTeam({
+    name: body.name,
+    description: body.description,
+    visibility: body.visibility,
+    ownerUserId: user.id,
+  })
+})

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

@@ -0,0 +1,23 @@
+/**
+ * GET /api/workshop/users/me —— 当前用户信息(Bearer 用户 token)。
+ * 附带资源统计(owned channels/templates/teams/workspaces)。
+ */
+import { defineApiHandler } from '../../../utils/response'
+import { getWorkshopManager } from '../../../plugins/workshop'
+import { resolveUser } from '../caller'
+
+export default defineApiHandler(async (event) => {
+  const manager = getWorkshopManager()
+  const user = resolveUser(event)
+  const channels = manager.listChannelsForUser(user.id)
+  return {
+    id: user.id,
+    name: user.name,
+    createdAt: user.createdAt,
+    stats: {
+      ownedChannels: channels.filter(c => c.ownerUserId === user.id).length,
+      legacyChannels: channels.filter(c => c.ownerUserId === null).length,
+      workspaces: manager.listWorkspaces(user.id).length,
+    },
+  }
+})

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

@@ -0,0 +1,33 @@
+/**
+ * POST /api/workshop/users/register —— 注册用户（name 唯一），经全局用户系统签发。
+ * 兼容旧契约：仅传 name 时自动补全局账号（email 由 name 派生、随机密码），
+ * 返回 { id, name, token }——token 仅此一次完整返回，请妥善保存。
+ * 全局用户系统承载身份，workshop 本地不再维护独立用户表。
+ */
+import { z } from 'zod'
+import { randomBytes } from 'node:crypto'
+import { readValidatedBody } from 'h3'
+import { zValidator } from '../../../utils/validate'
+import { defineApiHandler } from '../../../utils/response'
+import { userService } from '../../../services/user.service'
+
+const schema = z.object({
+  name: z.string().trim().min(1, 'name 必填').max(64, 'name 过长'),
+})
+
+export default defineApiHandler(async (event) => {
+  const body = await readValidatedBody(event, zValidator(schema))
+  const name = body.name.trim()
+  const email = `${name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}-${Date.now()}@workshop.local`
+  const result = userService.register({ name, email, password: randomLegacyPassword() })
+  return { id: result.user.id, name: result.user.name, token: result.token }
+})
+
+/** 20 位随机口令（老版仅 name 注册的账号密码不对外；后续可经管理面重置） */
+function randomLegacyPassword(): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
+  const bytes = randomBytes(20)
+  let out = ''
+  for (const b of bytes) out += chars[b % chars.length]
+  return out
+}

package/server/api/workshop/workspaces/[id]/channel-templates/[tplId].post.ts

@@ -0,0 +1,31 @@
+/**
+ * POST /api/workshop/workspaces/:id/channel-templates/:tplId —— 从 Channel 模板实例化并挂载到 workspace。
+ * 一步完成:实例化(属主 = 操作者)+ mount;替代原「挂载已有 Channel」入口。
+ */
+import { z } from 'zod'
+import { getRouterParam, readValidatedBody } from 'h3'
+import { zValidator } from '../../../../../utils/validate'
+import { defineApiHandler } from '../../../../../utils/response'
+import { resolveUser } from '../../../caller'
+import { getWorkshopManager, ensureLeadSchedulerLoop } from '../../../../../plugins/workshop'
+
+const mountSchema = z.object({
+  name: z.string().min(1).optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const workspaceId = getRouterParam(event, 'id')!
+  const templateId = getRouterParam(event, 'tplId')!
+  const user = resolveUser(event)
+  const body = await readValidatedBody(event, zValidator(mountSchema))
+  const manager = getWorkshopManager()
+  const result = await manager.instantiateChannelTemplate(templateId, user, body.name)
+  manager.mountChannelToWorkspace(user.id, workspaceId, result.channelId)
+  if (result.leadAgentId) {
+    ensureLeadSchedulerLoop(manager, result.channelId)
+  }
+  // 常驻事件录制器(与 channels.post 同口径):确保无人 WS 订阅前事件也已持久化
+  const { ensureStream } = await import('../../../ws')
+  ensureStream(manager, result.channelId)
+  return result
+})

package/server/api/workshop/workspaces/[id]/channels/[channelId].delete.ts

@@ -0,0 +1,15 @@
+/**
+ * DELETE /api/workshop/workspaces/:id/channels/:channelId —— 移出 channel。
+ */
+import { getRouterParam } from 'h3'
+import { defineApiHandler } from '../../../../../utils/response'
+import { getWorkshopManager } from '../../../../../plugins/workshop'
+import { resolveUser } from '../../../caller'
+
+export default defineApiHandler(async (event) => {
+  const user = resolveUser(event)
+  const workspaceId = getRouterParam(event, 'id')!
+  const channelId = getRouterParam(event, 'channelId')!
+  getWorkshopManager().unmountChannelFromWorkspace(user.id, workspaceId, channelId)
+  return { ok: true, workspaceId, channelId }
+})

package/server/api/workshop/workspaces/[id]/channels/[channelId].post.ts

@@ -0,0 +1,15 @@
+/**
+ * POST /api/workshop/workspaces/:id/channels/:channelId —— 挂载 channel(须为本人的 channel)。
+ */
+import { getRouterParam } from 'h3'
+import { defineApiHandler } from '../../../../../utils/response'
+import { getWorkshopManager } from '../../../../../plugins/workshop'
+import { resolveUser } from '../../../caller'
+
+export default defineApiHandler(async (event) => {
+  const user = resolveUser(event)
+  const workspaceId = getRouterParam(event, 'id')!
+  const channelId = getRouterParam(event, 'channelId')!
+  getWorkshopManager().mountChannelToWorkspace(user.id, workspaceId, channelId)
+  return { ok: true, workspaceId, channelId }
+})

package/server/api/workshop/workspaces/[id]/index.delete.ts

@@ -0,0 +1,14 @@
+/**
+ * DELETE /api/workshop/workspaces/:id —— 删除 workspace(仅 owner)。
+ */
+import { getRouterParam } from 'h3'
+import { defineApiHandler } from '../../../../utils/response'
+import { getWorkshopManager } from '../../../../plugins/workshop'
+import { resolveUser } from '../../caller'
+
+export default defineApiHandler(async (event) => {
+  const user = resolveUser(event)
+  const workspaceId = getRouterParam(event, 'id')!
+  getWorkshopManager().deleteWorkspace(user.id, workspaceId)
+  return { ok: true, workspaceId }
+})

package/server/api/workshop/workspaces/index.get.ts

@@ -0,0 +1,11 @@
+/**
+ * GET /api/workshop/workspaces —— 当前用户的 workspace 列表(含挂载 channel;Bearer 用户 token)。
+ */
+import { defineApiHandler } from '../../../utils/response'
+import { getWorkshopManager } from '../../../plugins/workshop'
+import { resolveUser } from '../caller'
+
+export default defineApiHandler(async (event) => {
+  const user = resolveUser(event)
+  return getWorkshopManager().listWorkspaces(user.id)
+})

package/server/api/workshop/workspaces/index.post.ts

@@ -0,0 +1,17 @@
+/**
+ * POST /api/workshop/workspaces —— 创建 workspace(归属当前用户)。
+ */
+import { z } from 'zod'
+import { readValidatedBody } from 'h3'
+import { zValidator } from '../../../utils/validate'
+import { defineApiHandler } from '../../../utils/response'
+import { getWorkshopManager } from '../../../plugins/workshop'
+import { resolveUser } from '../caller'
+
+const schema = z.object({ name: z.string().min(1, 'name 必填').max(64) })
+
+export default defineApiHandler(async (event) => {
+  const user = resolveUser(event)
+  const body = await readValidatedBody(event, zValidator(schema))
+  return getWorkshopManager().createWorkspace(user.id, body.name)
+})