agentworkshop 0.2.1

package/server/api/workshop/caller.ts

@@ -0,0 +1,141 @@
+/**
+ * REST 作业面共享认证 — Bearer token → caller Agent。
+ * 与 MCP 工具同一语义(manager.findByToken):Agent 经 REST 调用时,
+ * 所有查询/通信按 caller 的 channelId 作用域过滤(跨 channel 一律 SCOPE_VIOLATION)。
+ * v10:用户面透传 role,提供 admin 守卫与模板归属名注入(权限系统)。
+ */
+import { getRequestHeader } from 'h3'
+import type { H3Event } from 'h3'
+import { AppError } from '../../utils/errors'
+import { getWorkshopManager } from '../../plugins/workshop'
+import { resolveUserByToken } from '../../services/user.service'
+import { userRepository } from '../../repositories/user.repository'
+import type { AgentInfo } from '../../services/workshop/agents/agent-interface'
+
+/** 从 Authorization: Bearer <token> 解析 caller;缺失/无效 → 401 */
+export function resolveCaller(event: H3Event): AgentInfo {
+  const auth = getRequestHeader(event, 'authorization')
+  const token = auth?.match(/^Bearer\s+(.+)$/i)?.[1]?.trim()
+  const caller = token ? getWorkshopManager().findByToken(token) : undefined
+  if (!caller) {
+    throw new AppError(401, 'UNAUTHORIZED', '需要有效的 Agent token(Authorization: Bearer <token>)')
+  }
+  return caller
+}
+
+/** 可选 caller:有有效 token 则返回,否则 undefined(管理面路径用) */
+export function resolveCallerOrNull(event: H3Event): AgentInfo | null {
+  try {
+    return resolveCaller(event)
+  }
+  catch {
+    return null
+  }
+}
+
+/**
+ * 双域鉴权主体:Agent 实例 token(本 channel 成员语义)或用户 token(owner 语义)。
+ * 记忆观察/策展等"agent 作业面 + 人类控制台"共用端点的统一入口:
+ * 用户路径的 channel 可见性/所有权由调用方经 getChannelForUser/requireOwned 校验。
+ */
+export type ResolvedPrincipal
+  = | { kind: 'agent', caller: AgentInfo }
+    | { kind: 'user', user: ResolvedUser }
+
+export function resolveAgentOrUser(event: H3Event): ResolvedPrincipal {
+  const auth = getRequestHeader(event, 'authorization')
+  const token = auth?.match(/^Bearer\s+(.+)$/i)?.[1]?.trim()
+  if (!token) throw new AppError(401, 'UNAUTHORIZED', '需要 Agent token 或用户 token(Authorization: Bearer)')
+  const agent = getWorkshopManager().findByToken(token)
+  if (agent) return { kind: 'agent', caller: agent }
+  const user = resolveUserByToken(token)
+  if (user) return { kind: 'user', user }
+  throw new AppError(401, 'UNAUTHORIZED', 'token 无效(Agent 实例 token 或用户 token)')
+}
+
+/** 用户面认证解析结果（全局用户档案子集,供所有权/统计/权限消费） */
+export interface ResolvedUser {
+  id: string
+  name: string
+  /** 全局角色:'admin' | 'editor' | 'user'(权限系统;admin 拥有最高管理权限) */
+  role: string
+  createdAt: string
+}
+
+/**
+ * 用户面认证 — Bearer <用户 token> → 全局用户（data/users.sqlite 的 user_tokens）。
+ * 管理面(channels/agents/teams/tasks/messages/workspaces)强制用户身份:
+ * Agent 实例 token 与用户 token 分属两个域,互不通用。
+ * 每用户多 token 均有效;token 经 /api/users/register|/login|/tokens 签发。
+ */
+export function resolveUser(event: H3Event): ResolvedUser {
+  const auth = getRequestHeader(event, 'authorization')
+  const token = auth?.match(/^Bearer\s+(.+)$/i)?.[1]?.trim()
+  const user = token ? resolveUserByToken(token) : null
+  if (!user) {
+    throw new AppError(401, 'USER_UNAUTHORIZED', '需要有效的用户 token(Authorization: Bearer <用户token>;经 /api/users/register 或 /api/users/login 获取)')
+  }
+  return { id: user.id, name: user.name, role: user.role, createdAt: user.createdAt }
+}
+
+/** admin 守卫:非 admin → 403(用户管理/越权管理面) */
+export function requireAdmin(event: H3Event): ResolvedUser {
+  const user = resolveUser(event)
+  if (user.role !== 'admin') {
+    throw new AppError(403, 'ADMIN_REQUIRED', '该操作需要管理员权限')
+  }
+  return user
+}
+
+/** 角色 守卫(R3):高危控制面操作(配方应用/网关启停/节点删除)仅 admin/editor 可执行 */
+export function requireRole(event: H3Event, roles: string[] = ['admin', 'editor']): ResolvedUser {
+  const user = resolveUser(event)
+  if (!roles.includes(user.role)) {
+    throw new AppError(403, 'FORBIDDEN_ROLE', `该操作需要 ${roles.join('/')} 权限(当前角色 ${user.role})`)
+  }
+  return user
+}
+
+/** admin 判定(仅角色检查,不做认证;认证由 resolveUser 先行) */
+export function isAdmin(user: { role: string }): boolean {
+  return user.role === 'admin'
+}
+
+/** 模板/资源列表归属名注入:ownerUserId → ownerName(内置 NULL → 'system');就地补齐供前端呈现创建者 */
+export function withOwnerNames<T extends { ownerUserId: string | null, isBuiltin?: boolean }>(items: T[]): Array<T & { ownerName: string | null }> {
+  const cache = new Map<string, string | null>()
+  const resolveOne = (id: string): string | null => {
+    if (!cache.has(id)) {
+      cache.set(id, resolveUserNameById(id))
+    }
+    return cache.get(id) ?? null
+  }
+  return items.map((item) => {
+    const ownerName = item.ownerUserId === null
+      ? 'system'
+      : resolveOne(item.ownerUserId)
+    return { ...item, ownerName }
+  })
+}
+
+/** 按用户 id 解析用户名(60s 轻量缓存;users.sqlite 查询,解析失败回 null) */
+const nameCache = new Map<string, { name: string | null, at: number }>()
+function resolveUserNameById(userId: string): string | null {
+  const hit = nameCache.get(userId)
+  if (hit && Date.now() - hit.at < 60_000) return hit.name
+  let name: string | null
+  try {
+    name = userRepository.findById(userId)?.name ?? null
+  }
+  catch {
+    name = null
+  }
+  nameCache.set(userId, { name, at: Date.now() })
+  return name
+}
+
+/** 从事件提取用户 token(WS sub 等非 header 场景共用) */
+export function extractUserToken(event: H3Event): string | null {
+  const auth = getRequestHeader(event, 'authorization')
+  return auth?.match(/^Bearer\s+(.+)$/i)?.[1]?.trim() ?? null
+}

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

@@ -0,0 +1,31 @@
+/**
+ * POST /api/workshop/channel-templates/:id/instantiate —— 实例化 Channel 模板 → 新建 channel(属主 = 操作者)。
+ * 可见性:属主 / public(含内置)/ admin 可实例化;他人 private → 403。
+ * body.name 可选(缺省用模板名)。
+ */
+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 instantiateSchema = z.object({
+  name: z.string().min(1).optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const templateId = getRouterParam(event, 'id')!
+  const user = resolveUser(event)
+  const body = await readValidatedBody(event, zValidator(instantiateSchema))
+  const manager = getWorkshopManager()
+  const result = await manager.instantiateChannelTemplate(templateId, user, body.name)
+  // 模板含 lead 时直接启动调度循环(可提交任务)
+  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/channel-templates/[id].delete.ts

@@ -0,0 +1,20 @@
+/**
+ * DELETE /api/workshop/channel-templates/:id —— 删除 Channel 模板(不影响已实例化的 channel)。
+ * 权限:属主或 admin;内置模板任何人不可删除。
+ */
+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 templateId = getRouterParam(event, 'id')!
+  const manager = getWorkshopManager()
+  const user = resolveUser(event)
+  const tpl = manager.getChannelTemplate(templateId)
+  if (!tpl) throw new AppError(404, 'NOT_FOUND', `Channel 模板不存在: ${templateId}`)
+  manager.requireWritable(tpl.ownerUserId, user, 'Channel 模板')
+  manager.removeChannelTemplate(templateId)
+  return { removed: true, templateId }
+})

package/server/api/workshop/channel-templates/[id].get.ts

@@ -0,0 +1,19 @@
+/**
+ * GET /api/workshop/channel-templates/:id —— Channel 模板详情。
+ * 可见性:属主 / public(含内置)/ admin;他人 private → 403。
+ */
+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 templateId = getRouterParam(event, 'id')!
+  const manager = getWorkshopManager()
+  const tpl = manager.getChannelTemplate(templateId)
+  if (!tpl) throw new AppError(404, 'NOT_FOUND', `Channel 模板不存在: ${templateId}`)
+  const user = resolveUser(event)
+  manager.requireTemplateReadable(tpl, user, 'Channel 模板')
+  return tpl
+})

package/server/api/workshop/channel-templates/[id].patch.ts

@@ -0,0 +1,48 @@
+/**
+ * PATCH /api/workshop/channel-templates/:id —— 更新 Channel 模板。
+ * 权限:属主或 admin;内置模板任何人不可修改(TEMPLATE_BUILTIN)。
+ */
+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 memberSchema = z.union([
+  z.object({ templateId: z.string().min(1), role: z.enum(['lead', 'worker']) }),
+  z.object({
+    inline: z.object({
+      name: z.string().min(1),
+      harness: z.string().min(1),
+      config: z.record(z.string(), z.unknown()).optional(),
+    }),
+    role: z.enum(['lead', 'worker']),
+  }),
+])
+
+const patchSchema = z.object({
+  name: z.string().min(1).optional(),
+  description: z.string().optional(),
+  scenarioPrompt: z.string().optional(),
+  workspace: z.string().optional(),
+  lead: z.object({
+    name: z.string().min(1),
+    harness: z.string().min(1),
+    config: z.record(z.string(), z.unknown()).optional(),
+  }).nullable().optional(),
+  members: z.array(memberSchema).optional(),
+  visibility: z.enum(['private', 'public']).optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const templateId = getRouterParam(event, 'id')!
+  const user = resolveUser(event)
+  const body = await readValidatedBody(event, zValidator(patchSchema))
+  const manager = getWorkshopManager()
+  const tpl = manager.getChannelTemplate(templateId)
+  if (!tpl) throw new AppError(404, 'NOT_FOUND', `Channel 模板不存在: ${templateId}`)
+  manager.requireWritable(tpl.ownerUserId, user, 'Channel 模板')
+  return manager.updateChannelTemplate(templateId, body)
+})

package/server/api/workshop/channel-templates/from-channel.post.ts

@@ -0,0 +1,31 @@
+/**
+ * POST /api/workshop/channel-templates/from-channel —— 从当前 Channel 实例捕获为模板。
+ * 捕获:场景 prompt + 工作目录 + lead(内联快照)+ 成员(有模板引用则引用,否则内联快照)。
+ * 权限:channel 属主或 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 captureSchema = z.object({
+  channelId: z.string().min(1, 'channelId 必填'),
+  name: z.string().min(1, '模板名必填'),
+  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(captureSchema))
+  const manager = getWorkshopManager()
+  const channel = manager.getChannelForUser(body.channelId, user.id)
+  manager.requireWritable(channel.ownerUserId, user, 'channel')
+  return manager.createChannelTemplateFromChannel(body.channelId, {
+    name: body.name,
+    description: body.description,
+    visibility: body.visibility,
+  }, user.id)
+})

package/server/api/workshop/channel-templates/index.get.ts

@@ -0,0 +1,13 @@
+/**
+ * GET /api/workshop/channel-templates —— 可见性感知的 Channel 模板列表。
+ * 普通用户:本人(任意可见性)+ 全部 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 templates = getWorkshopManager().listChannelTemplatesVisibleTo(user)
+  return withOwnerNames(templates)
+})

package/server/api/workshop/channel-templates/index.post.ts

@@ -0,0 +1,61 @@
+/**
+ * POST /api/workshop/channel-templates —— 创建 Channel 模板(场景 + 工作目录 + 成员组合)。
+ * 成员引用的 Agent 模板须操作者可读(属主/public/内置);visibility 缺省 private。
+ */
+import { z } from 'zod'
+import { resolveUser } from '../caller'
+import { readValidatedBody } from 'h3'
+import { zValidator } from '../../../utils/validate'
+import { defineApiHandler } from '../../../utils/response'
+import { AppError } from '../../../utils/errors'
+import { getWorkshopManager } from '../../../plugins/workshop'
+
+const memberSchema = z.union([
+  z.object({ templateId: z.string().min(1), role: z.enum(['lead', 'worker']) }),
+  z.object({
+    inline: z.object({
+      name: z.string().min(1),
+      harness: z.string().min(1),
+      config: z.record(z.string(), z.unknown()).optional(),
+    }),
+    role: z.enum(['lead', 'worker']),
+  }),
+])
+
+const createSchema = z.object({
+  name: z.string().min(1, 'name 必填'),
+  description: z.string().optional(),
+  scenarioPrompt: z.string().optional(),
+  workspace: z.string().optional(),
+  lead: z.object({
+    name: z.string().min(1),
+    harness: z.string().min(1),
+    config: z.record(z.string(), z.unknown()).optional(),
+  }).nullable().optional(),
+  members: z.array(memberSchema).optional(),
+  visibility: z.enum(['private', 'public']).optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const user = resolveUser(event)
+  const body = await readValidatedBody(event, zValidator(createSchema))
+  const manager = getWorkshopManager()
+  // 成员模板引用校验:引用的 Agent 模板须操作者可读
+  for (const m of body.members ?? []) {
+    if ('templateId' in m) {
+      const tpl = manager.getAgent(m.templateId)
+      if (!tpl) throw new AppError(404, 'NOT_FOUND', `Agent 模板不存在: ${m.templateId}`)
+      manager.requireTemplateReadable(tpl, user, 'Agent 模板')
+    }
+  }
+  return manager.createChannelTemplate({
+    name: body.name,
+    description: body.description,
+    scenarioPrompt: body.scenarioPrompt,
+    workspace: body.workspace,
+    lead: body.lead ?? null,
+    members: body.members ?? [],
+    visibility: body.visibility,
+    ownerUserId: user.id,
+  })
+})

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

@@ -0,0 +1,19 @@
+/**
+ * POST /api/workshop/channels/:id/activate —— 显式激活 channel(装配 lead + 调度循环)。
+ * 懒加载设计下通常在任务提交时自动激活;此端点供前端主动预热/恢复。
+ */
+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 manager = getWorkshopManager()
+  const user = resolveUser(event)
+  const channel = manager.getChannelForUser(channelId, user.id)
+  manager.requireWritable(channel.ownerUserId, user, 'channel')
+  ensureLeadSchedulerLoop(manager, channelId)
+  return manager.runtimeStatus()
+})

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

@@ -0,0 +1,30 @@
+/**
+ * DELETE /api/workshop/channels/:id/agents/:agentId/memories/:memoryId —— 删 Agent 私有记忆(本人或 lead)。
+ * - 需要 Bearer token;caller 须为本 channel 成员(跨 channel → 403 SCOPE_VIOLATION)
+ * - 仅本人或 lead 可删(manager 校验);memoryId 不属于该 agent 的本 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 agentId = getRouterParam(event, 'agentId')!
+  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 成员可删 Agent 记忆')
+  }
+  else {
+    const ch = manager.getChannelForUser(channelId, who.user.id)
+    manager.requireOwned(ch.ownerUserId, who.user.id, 'channel')
+    byOwner = true
+  }
+  manager.deleteAgentMemory(channelId, who.kind === 'agent' && !byOwner ? who.caller.id : agentId, agentId, memoryId, { byOwner })
+  return { deleted: true, memoryId }
+})

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

@@ -0,0 +1,29 @@
+/**
+ * GET /api/workshop/channels/:id/agents/:agentId/memories —— Agent 记忆只读观察面。
+ * - 需要 Bearer token 且 caller 为本 channel 成员;否则 401(与 mailbox.get.ts 同语义)
+ * - 返回该实例最近记忆(listByAgent);实例不存在 → 404(由 manager.listMemories 抛出)
+ */
+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 agentId = getRouterParam(event, 'agentId')!
+  // 双域鉴权: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 成员可观察 Agent 记忆')
+  }
+  else {
+    const ch = manager.getChannelForUser(channelId, who.user.id)
+    manager.requireOwned(ch.ownerUserId, who.user.id, 'channel')
+    byOwner = true
+  }
+  void byOwner
+  return manager.listMemories(channelId, agentId)
+})

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

@@ -0,0 +1,48 @@
+/**
+ * POST /api/workshop/channels/:id/agents/:agentId/memories —— 写/更新 Agent 记忆(agent 本人或 lead 策展)。
+ * - 需要 Bearer token;caller 须为本 channel 成员(跨 channel → 403 SCOPE_VIOLATION)
+ * - 仅本人或 lead 可写私有域(manager 校验 → 403 SCOPE_VIOLATION);稳定 dedupKey 幂等刷新
+ * - scope='shared'(可选):落 Channel 公共记忆域(agent:<caller>:<key> 命名空间,全员可检索)
+ */
+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 agentMemorySchema = 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(),
+  scope: z.enum(['private', 'shared']).optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const agentId = getRouterParam(event, 'agentId')!
+  // 双域鉴权: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 成员可策展 Agent 记忆')
+  }
+  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(agentMemorySchema))
+  // owner 策展:curator 身份取目标成员(命名空间一致;byOwner 已旁路成员校验)
+  manager.addAgentMemory(channelId, who.kind === 'agent' && !byOwner ? who.caller.id : agentId, agentId, {
+    title: body.title,
+    content: body.content,
+    importance: body.importance,
+    dedupKey: body.dedupKey,
+    scope: body.scope,
+  }, { byOwner })
+  return { ok: true, agentId, scope: body.scope ?? 'private' }
+})

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

@@ -0,0 +1,43 @@
+/**
+ * POST /api/workshop/channels/:id/agents/:agentId/memories/search —— 记忆混合检索(客户端观察面)。
+ * - 与 agent 运行时 search_memory 工具同源算法(FTS+向量融合,0.5×相关性+0.3×时近性+0.2×重要性排序)
+ * - 需要 Bearer token;caller 须为本 channel 成员(跨 channel → 403 SCOPE_VIOLATION)
+ * - scope: auto=目标 agent 私有域+Channel 公共域(默认) / private / shared
+ * - 返回结构化片段(content 未切分原文;source 标注 private/shared)
+ */
+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 searchSchema = z.object({
+  query: z.string().min(1, 'query 必填'),
+  scope: z.enum(['auto', 'private', 'shared']).optional(),
+  limit: z.number().int().min(1).max(20).optional(),
+})
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const agentId = getRouterParam(event, 'agentId')!
+  // 双域鉴权: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(searchSchema))
+  return manager.searchAgentMemories(channelId, who.kind === 'agent' && !byOwner ? who.caller.id : agentId, agentId, {
+    query: body.query,
+    scope: body.scope,
+    limit: body.limit,
+  }, { byOwner })
+})

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

@@ -0,0 +1,39 @@
+/**
+ * PATCH /api/workshop/channels/:id/agents/:agentId/model —— 绑定角色模型(换装)。
+ * - Bearer 用户 token;body: { modelRef }(assetId;'' 清除)
+ * - 更新 agent 的 config.modelRef(经 manager.updateChannelAgent 持久化)+ 注册表 appliedTo 反向索引
+ * - 返回 { agentId, modelRef }
+ */
+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'
+import { getCharacterAssetRepo } from '@/server/services/workshop/assets/character-asset.repo'
+
+export default defineApiHandler(async (event) => {
+  const channelId = getRouterParam(event, 'id')!
+  const agentId = getRouterParam(event, 'agentId')!
+  const body = await readBody<{ modelRef?: string | null }>(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 modelRef = typeof body?.modelRef === 'string' ? body.modelRef.trim() : ''
+  // 与既有 config 合并(保留 homeX/homeZ 等布局字段),经既有 updateChannelAgent 持久化,
+  // 随后 AEP agent.member 回流前端
+  const current = (members.find(a => a.id === agentId)?.config ?? {}) as Record<string, unknown>
+  await manager.updateChannelAgent(agentId, { config: { ...current, modelRef } }, { channelId, by: 'user', reason: 'bind-model' })
+
+  // 更新注册表反向索引:新模型 bind;旧模型 unbind(重算所有绑定该 agent 的模型)
+  const repo = getCharacterAssetRepo()
+  if (modelRef) repo.bind(modelRef, agentId)
+  for (const a of repo.listAll()) {
+    if (a.id !== modelRef && a.appliedTo.includes(agentId)) repo.unbind(a.id, agentId)
+  }
+
+  return { agentId, modelRef }
+})

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

@@ -0,0 +1,33 @@
+/**
+ * PATCH /api/workshop/channels/:id/agents/:agentId/position —— 管理员布局:保存 Agent 落点。
+ * - Bearer 用户 token;body: { x, z }(3D 小镇世界坐标;缺省清除)
+ * - 与既有 config 合并(homeX/homeZ),不覆盖 modelRef 等既有字段;
+ * - 经既有 updateChannelAgent 持久化并 AEP agent.member(op=updated) 回流前端(town 重建即按新 home 落位)。
+ */
+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<{ x?: number, z?: number }>(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 等既有 config;x/z 缺省/非有限 → 清除对应 home
+  const config = { ...(agent.config ?? {}) }
+  if (typeof body?.x === 'number' && Number.isFinite(body.x)) config.homeX = Math.round(body.x * 10) / 10
+  else delete config.homeX
+  if (typeof body?.z === 'number' && Number.isFinite(body.z)) config.homeZ = Math.round(body.z * 10) / 10
+  else delete config.homeZ
+  await manager.updateChannelAgent(agentId, { config }, { channelId, by: 'user', reason: 'position' })
+  return { agentId, name: agent.name, config }
+})