agentworkshop 0.2.1

package/app/composables/workshop/useOpsLog.ts

@@ -0,0 +1,164 @@
+/**
+ * useOpsLog —— 运维日志(全操作统一记录)的前端单一消费口。
+ *
+ * 数据权威在 server:audit_log(SQLite)经 GET /api/workshop/ops-logs 按维度查询
+ * (产线/产品/Recipe/来源/分类/关键词/时间区间);POST 手动录入人工事件。
+ * 实时:WS ops.log 帧经 townBus 旁路 → recent 环形缓冲(实时事件轨只渲染摘要,
+ * 详情由 /logs 日志管理页查询),globalThis 单例防重复订阅。
+ */
+import { reactive } from 'vue'
+import { useTownBus } from './useTownBus'
+import { apiFetch } from './apiClient'
+import type { AepEnvelope, AepOpsLog } from '#shared/workshop-protocol'
+
+/** 实时事件轨容量(仅摘要;历史完整查询走 REST) */
+const RECENT_CAP = 40
+
+/** audit_log 行投影(REST 返回) */
+export interface OpsLogRow {
+  id: number
+  actor: string
+  actorName: string
+  actorKind: 'user' | 'agent' | 'system'
+  action: string
+  targetKind: string
+  targetId: string
+  detailJson: string
+  at: string
+  lineId: string
+  productId: string
+  recipeId: string
+  kind: string
+  summary: string
+}
+
+export interface OpsLogQuery {
+  lineId?: string
+  productId?: string
+  recipeId?: string
+  actorKind?: string
+  kind?: string
+  q?: string
+  from?: string
+  to?: string
+  limit?: number
+}
+
+const api = <T>(path: string, init?: RequestInit): Promise<T> =>
+  apiFetch<T>({ base: '/api/workshop/ops-logs', path, init })
+
+function ingestFrame(p: AepOpsLog): OpsLogRow {
+  return {
+    id: 0,
+    actor: p.actor,
+    actorName: p.actorName || p.actor,
+    actorKind: p.actorKind,
+    action: p.action,
+    targetKind: p.targetKind,
+    targetId: p.targetId,
+    detailJson: '',
+    at: p.at,
+    lineId: p.lineId,
+    productId: p.productId,
+    recipeId: p.recipeId,
+    kind: p.kind,
+    summary: p.summary,
+  }
+}
+
+const createStore = () => {
+  /** 实时事件轨(WS 直推;新→旧) */
+  const recent = reactive<OpsLogRow[]>([])
+  /** 查询结果(REST 快照;/logs 页与实时轨互不干扰) */
+  const results = reactive<OpsLogRow[]>([])
+  const loading = reactive({ list: false, posting: false })
+  const error = reactive({ list: '', post: '' })
+
+  /** 挂 WS 帧(townBus);幂等。返回退订函数。 */
+  function ensureLive(): () => void {
+    const g = globalThis as typeof globalThis & { __opsLogFed?: boolean }
+    if (g.__opsLogFed) return () => {}
+    g.__opsLogFed = true
+    void seedRecent()
+    return useTownBus().subscribe((e: AepEnvelope) => {
+      if (e.type === 'ops.log') {
+        const row = ingestFrame(e.payload as AepOpsLog)
+        if (!recent.some(r => r.at === row.at && r.actor === row.actor && r.action === row.action)) {
+          recent.unshift(row)
+          if (recent.length > RECENT_CAP) recent.splice(RECENT_CAP)
+        }
+      }
+    })
+  }
+
+  /** 首屏预填:最近 15 条历史摘要(实时轨不必从零等事件) */
+  async function seedRecent(): Promise<void> {
+    try {
+      const data = await api<{ logs: OpsLogRow[] }>('?limit=15')
+      for (const row of (data.logs ?? []).reverse()) {
+        if (!recent.some(r => r.at === row.at && r.actor === row.actor && r.action === row.action))
+          recent.unshift(row)
+      }
+    }
+    catch {
+      // 预取失败不阻塞实时轨(下一帧事件照常入列)
+    }
+  }
+
+  async function fetchLogs(query: OpsLogQuery = {}): Promise<void> {
+    loading.list = true
+    error.list = ''
+    try {
+      const qs = new URLSearchParams()
+      for (const [k, v] of Object.entries(query)) {
+        if (v != null && v !== '') qs.set(k, String(v))
+      }
+      const data = await api<{ logs: OpsLogRow[], count: number }>(`?${qs.toString()}`)
+      results.splice(0, results.length, ...(data.logs ?? []))
+    }
+    catch (err) {
+      error.list = err instanceof Error ? err.message : String(err)
+    }
+    finally {
+      loading.list = false
+    }
+  }
+
+  /** 人工手动记录事件(值班/处置/备注;与自动操作同一流水) */
+  async function postManual(input: { summary: string, lineId?: string, productId?: string, recipeId?: string, detail?: Record<string, unknown> }): Promise<void> {
+    loading.posting = true
+    error.post = ''
+    try {
+      await api('', { method: 'POST', body: JSON.stringify(input) })
+    }
+    catch (err) {
+      error.post = err instanceof Error ? err.message : String(err)
+      throw err
+    }
+    finally {
+      loading.posting = false
+    }
+  }
+
+  const store = reactive({
+    recent,
+    results,
+    loading,
+    error,
+    ensureLive,
+    fetchLogs,
+    postManual,
+  })
+  return store
+}
+
+type OpsLogStore = ReturnType<typeof createStore>
+
+const GLOBAL_KEY = '__opsLogStream'
+
+/** 单例(globalThis 挂载;跨组件/跨页面安全) */
+export function useOpsLog(): OpsLogStore {
+  const g = globalThis as typeof globalThis & Record<string, unknown>
+  if (!g[GLOBAL_KEY]) g[GLOBAL_KEY] = createStore()
+  return g[GLOBAL_KEY] as OpsLogStore
+}

package/app/composables/workshop/useSceneLayouts.ts

@@ -0,0 +1,166 @@
+/**
+ * useSceneLayouts —— 频道领地放置(3D 小镇布局注册表)。
+ *
+ * 职责:
+ *  - 拉取已放置频道清单(GET /api/workshop/scene/layouts);
+ *  - 放置/更新领地(PUT /:channelId):拖频道入场景、编辑边界后落库;
+ *  - 移除放置(DELETE /:channelId):把频道(及其 Agent)从场景撤出。
+ * 场景初始为空场地;未放置的频道只出现在频道坞,不进入 3D。
+ * 单例挂 globalThis,跨组件安全;store 为 reactive(驱动频道坞/选中面板重渲染)。
+ */
+import { reactive } from 'vue'
+
+export interface SceneLayoutView {
+  channelId: string
+  /** 领地中心(世界坐标) */
+  x: number
+  z: number
+  /** 边界半径(ellipse)/半宽(rect) */
+  radiusX: number
+  radiusZ: number
+  shape: 'ellipse' | 'rect'
+  rotationY: number
+  updatedAt: string
+}
+
+const GLOBAL_KEY = '__sceneLayouts'
+
+interface SceneLayoutStore {
+  layouts: Record<string, SceneLayoutView>
+  loaded: boolean
+  loading: boolean
+  error: string
+  /** 布局数据版本号(load 成功/save/remove 时自增;供组件监听后幂等收敛重建) */
+  rev: number
+  load(): Promise<void>
+  byChannel(channelId: string): SceneLayoutView | undefined
+  save(channelId: string, input: { x: number, z: number, radiusX: number, radiusZ: number, shape?: 'ellipse' | 'rect', rotationY?: number }): Promise<SceneLayoutView>
+  remove(channelId: string): Promise<void>
+}
+
+function headers(json = true): Record<string, string> {
+  const cookieToken = typeof document !== 'undefined'
+    ? (document.cookie.match(/(?:^|;\s*)token=([^;]+)/)?.[1] ?? '')
+    : ''
+  const h: Record<string, string> = {}
+  if (cookieToken) h.authorization = `Bearer ${decodeURIComponent(cookieToken)}`
+  if (json) h['content-type'] = 'application/json'
+  return h
+}
+
+function createStore(): SceneLayoutStore {
+  /** 在飞请求句柄:并发 load 等同一个真实请求(旧实现直接 return → 调用方拿空 layouts 去 hydrate,频道竞态消失) */
+  let inFlight: Promise<void> | null = null
+  const sleep = (ms: number): Promise<void> => new Promise(r => setTimeout(r, ms))
+
+  const store: SceneLayoutStore = reactive({
+    layouts: {},
+    loaded: false,
+    loading: false,
+    error: '',
+    rev: 0,
+
+    async load() {
+      if (!inFlight) {
+        inFlight = doLoad().finally(() => {
+          inFlight = null
+        })
+      }
+      return inFlight
+    },
+
+    byChannel(channelId) {
+      return store.layouts[channelId]
+    },
+
+    async save(channelId, input) {
+      // 乐观写入:本地即刻生效(WS snapshot 重建不会清掉刚放置的频道),随后持久化重试
+      store.layouts[channelId] = {
+        channelId,
+        x: input.x,
+        z: input.z,
+        radiusX: input.radiusX,
+        radiusZ: input.radiusZ,
+        shape: input.shape ?? 'ellipse',
+        rotationY: input.rotationY ?? 0,
+        updatedAt: new Date().toISOString(),
+      }
+      store.rev++
+      let lastErr: Error | null = null
+      for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+          const res = await fetch(`/api/workshop/scene/layouts/${channelId}`, {
+            method: 'PUT',
+            headers: headers(),
+            body: JSON.stringify(input),
+          })
+          const json = await res.json().catch(() => ({}))
+          if (!res.ok || !json?.data?.layout) throw new Error(json?.message ?? '保存频道布局失败')
+          store.layouts[channelId] = json.data.layout
+          // rev 不再自增:乐观写入已触发 hydrate,服务端回显仅对齐 updatedAt(同值),
+          // 二次 rev 会让整场 resetAll+GLB 重载执行两遍(一次保存双倍重建)
+          return json.data.layout
+        }
+        catch (err) {
+          lastErr = err instanceof Error ? err : new Error(String(err))
+          if (attempt < 2) await sleep(500 * (attempt + 1))
+        }
+      }
+      throw lastErr ?? new Error('保存频道布局失败')
+    },
+
+    async remove(channelId) {
+      const res = await fetch(`/api/workshop/scene/layouts/${channelId}`, {
+        method: 'DELETE',
+        headers: headers(),
+      })
+      const json = await res.json().catch(() => ({}))
+      if (!res.ok) throw new Error(json?.message ?? '移除频道放置失败')
+      const next = Object.fromEntries(Object.entries(store.layouts).filter(([k]) => k !== channelId))
+      store.layouts = next
+      store.rev++
+    },
+  })
+
+  /** 单次真实拉取(3 次退避重试;非 2xx 视为失败 —— 401/500 的空 layouts 曾让整场频道消失) */
+  async function doLoad(): Promise<void> {
+    store.loading = true
+    let lastErr = ''
+    try {
+      for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+          const res = await fetch('/api/workshop/scene/layouts', { headers: headers() })
+          if (!res.ok) throw new Error(`HTTP ${res.status}`)
+          const json = await res.json().catch(() => ({}))
+          const list: SceneLayoutView[] = json?.data?.layouts ?? []
+          const next: Record<string, SceneLayoutView> = {}
+          for (const l of list) next[l.channelId] = l
+          store.layouts = next
+          store.loaded = true
+          store.error = ''
+          store.rev++
+          return
+        }
+        catch (err) {
+          lastErr = err instanceof Error ? err.message : String(err)
+          if (attempt < 2) await sleep(400 * (attempt + 1))
+        }
+      }
+      store.loaded = false
+      store.error = lastErr
+    }
+    finally {
+      store.loading = false
+    }
+  }
+
+  return store
+}
+
+export function useSceneLayouts(): SceneLayoutStore {
+  const g = globalThis as unknown as Record<string, SceneLayoutStore | undefined>
+  if (!g[GLOBAL_KEY]) g[GLOBAL_KEY] = createStore()
+  const store = g[GLOBAL_KEY]!
+  void store.load()
+  return store
+}

package/app/composables/workshop/useTownBus.ts

@@ -0,0 +1,47 @@
+/**
+ * TownBus — Workshop AEP 事件旁路总线(单例)。
+ *
+ * 职责:把 `useWorkshopWs` ingest 的每一个 AEP 信封**旁路广播**给小镇场景(以及任何
+ * 需要与时间线同源实时事件流的消费方)。不改变既有 store 分发 —— 只在 ingest 尾部
+ * 追加 emit,幂等、可注释一行即完全回退。
+ *
+ * 核心契约:与 AepEnvelope 同构;subscribe 返回退订函数。单例挂 globalThis,
+ * 跨组件安全挂载/卸载(与 useWorkshopWs 的 session 单例同策略)。
+ */
+import type { AepEnvelope } from '#shared/workshop-protocol'
+
+export interface TownBus {
+  /** 广播一帧 AEP(useWorkshopWs ingest 尾部调用;订阅方异常不影响其它) */
+  emit(e: AepEnvelope): void
+  /** 订阅实时事件;返回退订函数(组件卸载时必须调用,防泄漏) */
+  subscribe(fn: (e: AepEnvelope) => void): () => void
+}
+
+/** 全局单例句柄键(避免多实例重复订阅) */
+const GLOBAL_KEY = '__townBus'
+
+function createBus(): TownBus {
+  const subs = new Set<(e: AepEnvelope) => void>()
+  return {
+    emit(e) {
+      for (const fn of subs) {
+        try {
+          fn(e)
+        }
+        catch {
+          /* 单个订阅方异常不阻断广播 */
+        }
+      }
+    },
+    subscribe(fn) {
+      subs.add(fn)
+      return () => subs.delete(fn)
+    },
+  }
+}
+
+export function useTownBus(): TownBus {
+  const g = globalThis as unknown as Record<string, TownBus | undefined>
+  if (!g[GLOBAL_KEY]) g[GLOBAL_KEY] = createBus()
+  return g[GLOBAL_KEY]!
+}

package/app/composables/workshop/useVisibleInterval.ts

@@ -0,0 +1,42 @@
+/**
+ * useVisibleInterval —— 主线程友好的可见性感知轮询。
+ *
+ * 资源分配契约:前台按 ms 节拍;标签页隐藏时降为 bgMs(null = 暂停,默认 3×);
+ * 回前台立即补一拍(数据秒级收敛,无需等下一个周期)。WS 长连不受影响
+ * (帧推送是常量成本,合批在 store 层完成),这里只调度「拉」的一半。
+ */
+export function useVisibleInterval(
+  fn: () => void,
+  ms: number,
+  opts: { bgMs?: number | null } = {},
+): void {
+  const bgMs = opts.bgMs === undefined ? ms * 3 : opts.bgMs
+  let timer: ReturnType<typeof setInterval> | null = null
+
+  function start(interval: number): void {
+    stop()
+    if (interval > 0) timer = setInterval(fn, interval)
+  }
+  function stop(): void {
+    if (timer) {
+      clearInterval(timer)
+      timer = null
+    }
+  }
+  function onVis(): void {
+    if (document.hidden) {
+      start(bgMs)
+    }
+    else {
+      start(ms)
+      fn()
+    }
+  }
+
+  start(document.hidden ? bgMs : ms)
+  document.addEventListener('visibilitychange', onVis)
+  onScopeDispose(() => {
+    stop()
+    document.removeEventListener('visibilitychange', onVis)
+  })
+}

package/app/composables/workshop/useWorkshopApi.ts

@@ -0,0 +1,224 @@
+/**
+ * Workshop API 类型化封装(P0 面:channels/agents/tasks/messages/memories/queue/runtime)。
+ * 统一走 $http(Bearer cookie 注入 + envelope 解包);错误由拦截器统一 toast。
+ */
+import type { AepSnapshot } from '#shared/workshop-protocol'
+
+export interface ChannelDto {
+  id: string
+  name: string
+  description?: string
+  /** channel 级作业场景 prompt(设置弹窗可编辑) */
+  scenarioPrompt?: string
+  leadAgentId: string | null
+  workspace?: string
+  enabled: number
+  /** 归属用户(null = 遗留公共) */
+  ownerUserId?: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+export interface AgentInfoDto {
+  id: string
+  channelId: string
+  name: string
+  harness: string
+  role: 'lead' | 'worker'
+  config: Record<string, unknown>
+  token?: string
+  /** 实例启停(1 启用 / 0 禁用) */
+  enabled?: number
+}
+
+export interface TaskDto {
+  id: string
+  channelId: string
+  parentId?: string
+  assigneeId: string
+  title: string
+  description?: string
+  state: string
+  progress: number
+  /** 派发路由理由(lead 留痕的审计决策) */
+  routeReason?: string
+  artifacts: Array<{ artifactId: string, name?: string, parts: Array<{ text?: string }> }>
+  createdAt: string
+  updatedAt: string
+}
+
+export interface MemoryRowDto {
+  id: string
+  channelId: string
+  agentId: string
+  kind: string
+  title: string
+  content: string
+  importance: number
+  accessCount: number
+  createdAt: string
+}
+
+export interface MemorySnippetDto {
+  id: string
+  kind: string
+  title: string
+  content: string
+  importance: number
+  createdAt: string
+  score: number
+  source: 'private' | 'shared'
+}
+
+export function useWorkshopApi() {
+  const http = useHttp()
+
+  return {
+    // channels
+    listChannels: () => http.get<{ data: ChannelDto[] }>('/workshop/channels'),
+    createChannel: (body: { name: string, description?: string, scenarioPrompt?: string, workspace?: string, leadAgent?: { name: string, harness: string, config?: Record<string, unknown> } }) =>
+      http.post<{ data: { channelId: string, leadAgentId?: string, workspace: string } }>('/workshop/channels', body),
+    deleteChannel: (id: string) => http.delete<{ data: unknown }>(`/workshop/channels/${id}`),
+    /** 修改 Channel 实例设置(场景 prompt / 工作目录热更新;成员运行时自动回收重装配) */
+    patchChannel: (id: string, body: { name?: string, description?: string, scenarioPrompt?: string, workspace?: string, enabled?: number }) =>
+      http.request<{ data: ChannelDto }>({ method: 'PATCH', url: `/workshop/channels/${id}`, data: body }),
+    // channel agents
+    listChannelAgents: (id: string) => http.get<{ data: AgentInfoDto[] }>(`/workshop/channels/${id}/agents`),
+    addChannelAgent: (id: string, body: { agentId?: string, name?: string, harness?: string, role?: 'lead' | 'worker', config?: Record<string, unknown> }) =>
+      http.post<{ data: AgentInfoDto }>(`/workshop/channels/${id}/agents`, body),
+    updateChannelAgent: (id: string, agentId: string, body: { name?: string, config?: Record<string, unknown>, enabled?: 0 | 1, reason?: string }) =>
+      http.request<{ data: { agentId: string, name: string } }>({ method: 'PATCH', url: `/workshop/channels/${id}/agents/${agentId}`, data: body }),
+    removeChannelAgent: (id: string, agentId: string) => http.delete<{ data: unknown }>(`/workshop/channels/${id}/agents/${agentId}`),
+    /** HITL:独立中断指定成员运行时(worker/lead 均可;lead 停止同时停调度,下次任务提交自动重激活) */
+    stopChannelAgent: (id: string, agentId: string) =>
+      http.post<{ data: { agentId: string, stopped: boolean } }>(`/workshop/channels/${id}/agents/${agentId}/stop`, {}),
+    // tasks
+    listTasks: (id: string) => http.get<{ data: TaskDto[] }>(`/workshop/channels/${id}/tasks`),
+    submitTask: (id: string, body: { title: string, description?: string, mode?: 'goal' | 'loop' | 'pipeline', modeConfig?: Record<string, unknown>, assigneeId?: string, fromLabel?: string, parts?: Array<{ text: string }> }) =>
+      http.post<{ data: TaskDto }>(`/workshop/channels/${id}/tasks`, body),
+    // messages(注入即时消息/队列消息;fromLabel = 人类发送者显示名)
+    injectMessage: (id: string, body: { toAgentId: string, text: string, priority?: 'immediate' | 'task', requireReply?: boolean, fromLabel?: string }) =>
+      http.post<{ data: unknown }>(`/workshop/channels/${id}/messages`, body),
+    // memories
+    listAgentMemories: (id: string, agentId: string) => http.get<{ data: MemoryRowDto[] }>(`/workshop/channels/${id}/agents/${agentId}/memories`),
+    searchMemories: (id: string, agentId: string, body: { query: string, scope?: 'auto' | 'private' | 'shared', limit?: number }) =>
+      http.post<{ data: MemorySnippetDto[] }>(`/workshop/channels/${id}/agents/${agentId}/memories/search`, body),
+    saveMemory: (id: string, agentId: string, body: { title: string, content: string, importance?: number, dedupKey?: string, scope?: 'private' | 'shared' }) =>
+      http.post<{ data: unknown }>(`/workshop/channels/${id}/agents/${agentId}/memories`, body),
+    listTeamMemories: (id: string) => http.get<{ data: MemoryRowDto[] }>(`/workshop/channels/${id}/memories`),
+    // queue / runtime
+    queueOverview: (id: string) => http.get<{ data: Array<{ agentId: string, name: string, state: string, currentTaskId: string | null, queuedCount: number, completedCount: number }> }>(`/workshop/channels/${id}/queue`),
+    runtimeStatus: () => http.get<{ data: { wiredAgents: string[], activeChannels: string[] } }>('/workshop/runtime'),
+    // tasks detail / lifecycle(P1 抽屉)
+    getTask: (taskId: string) => http.get<{ data: TaskDto }>(`/workshop/tasks/${taskId}`),
+    cancelTask: (taskId: string) => http.post<{ data: TaskDto }>(`/workshop/tasks/${taskId}/cancel`, {}),
+    /** HITL:重试 FAILED 任务(优先原 assignee,否则队列最短空闲 worker) */
+    retryTask: (taskId: string) => http.post<{ data: TaskDto }>(`/workshop/tasks/${taskId}/retry`, {}),
+    // agent 模板库(P1;v10 用户隔离:private 仅本人,public 全员可用,内置只读)
+    listTemplates: () => http.get<{ data: AgentTemplateDto[] }>('/workshop/agents'),
+    createTemplate: (body: { name: string, harness: string, config?: Record<string, unknown>, visibility?: 'private' | 'public' }) =>
+      http.post<{ data: AgentTemplateDto }>('/workshop/agents', body),
+    updateTemplate: (id: string, body: { name?: string, harness?: string, config?: Record<string, unknown>, enabled?: number, visibility?: 'private' | 'public' }) =>
+      http.request<{ data: AgentTemplateDto }>({ method: 'PATCH', url: `/workshop/agents/${id}`, data: body }),
+    deleteTemplate: (id: string) => http.delete<{ data: unknown }>(`/workshop/agents/${id}`),
+    // teams(P1 编组库;v10 可见性)
+    listTeams: () => http.get<{ data: TeamDto[] }>('/workshop/teams'),
+    createTeam: (body: { name: string, description?: string, visibility?: 'private' | 'public' }) => http.post<{ data: TeamDto }>('/workshop/teams', body),
+    updateTeam: (id: string, body: { name?: string, description?: string, visibility?: 'private' | 'public' }) =>
+      http.request<{ data: TeamDto }>({ method: 'PATCH', url: `/workshop/teams/${id}`, data: body }),
+    deleteTeam: (id: string) => http.delete<{ data: unknown }>(`/workshop/teams/${id}`),
+    addTeamMember: (id: string, body: { agentId: string, role?: 'lead' | 'worker' }) =>
+      http.post<{ data: TeamDto }>(`/workshop/teams/${id}/members`, body),
+    removeTeamMember: (id: string, templateId: string) => http.delete<{ data: TeamDto }>(`/workshop/teams/${id}/members/${templateId}`),
+    deployTeam: (teamId: string, channelId: string) => http.post<{ data: unknown }>(`/workshop/teams/${teamId}/deploy`, { channelId }),
+    // channel 模板库(v10:场景 + 工作目录 + 成员组合;实例化一键建 channel)
+    listChannelTemplates: () => http.get<{ data: ChannelTemplateDto[] }>('/workshop/channel-templates'),
+    createChannelTemplate: (body: { name: string, description?: string, scenarioPrompt?: string, workspace?: string, lead?: ChannelTemplateDto['lead'], members?: ChannelTemplateMemberDto[], visibility?: 'private' | 'public' }) =>
+      http.post<{ data: ChannelTemplateDto }>('/workshop/channel-templates', body),
+    captureChannelTemplate: (body: { channelId: string, name: string, description?: string, visibility?: 'private' | 'public' }) =>
+      http.post<{ data: ChannelTemplateDto }>('/workshop/channel-templates/from-channel', body),
+    updateChannelTemplate: (id: string, body: { name?: string, description?: string, scenarioPrompt?: string, workspace?: string, visibility?: 'private' | 'public' }) =>
+      http.request<{ data: ChannelTemplateDto }>({ method: 'PATCH', url: `/workshop/channel-templates/${id}`, data: body }),
+    deleteChannelTemplate: (id: string) => http.delete<{ data: unknown }>(`/workshop/channel-templates/${id}`),
+    instantiateChannelTemplate: (id: string, name?: string) =>
+      http.post<{ data: { channelId: string, workspace: string, agentCount: number, leadAgentId?: string } }>(`/workshop/channel-templates/${id}/instantiate`, { name }),
+    /** 从 Channel 模板实例化并挂载到 workspace(替代"挂载已有 Channel") */
+    mountChannelTemplate: (wsId: string, tplId: string, name?: string) =>
+      http.post<{ data: { channelId: string, workspace: string, agentCount: number, leadAgentId?: string } }>(`/workshop/workspaces/${wsId}/channel-templates/${tplId}`, { name }),
+    // channel 成员的 harness 终端会话(rpc-ui 镜像;lanes 控制面板数据源)
+    listChannelTerminals: (id: string) => http.get<{ data: TerminalSessionDto[] }>(`/workshop/channels/${id}/terminals`),
+  }
+}
+
+/** harness 终端会话视图(GET /workshop/channels/:id/terminals) */
+export interface TerminalSessionDto {
+  pid: number
+  agentId: string | null
+  channelId: string | null
+  name: string | null
+  role: 'lead' | 'worker' | null
+  harness: string
+  alive: boolean
+  running: boolean
+  streaming: boolean
+  startedAt: number
+}
+
+/** Agent 模板详情(全局;instances = 已克隆实例去向;v10 用户隔离字段) */
+export interface AgentTemplateDto {
+  id: string
+  name: string
+  harness: string
+  config: Record<string, unknown>
+  enabled: number
+  /** 可见性:'private' 仅本人 | 'public' 全员可读可用 */
+  visibility: 'private' | 'public'
+  /** 内置模板(公开只读,任何人不可修改删除) */
+  isBuiltin: boolean
+  /** 归属用户(null = 内置) */
+  ownerUserId: string | null
+  /** 归属用户名(列表接口附注;'system' = 内置) */
+  ownerName?: string | null
+  instances: Array<{ id: string, channelId: string, role: 'lead' | 'worker', token: string }>
+  createdAt: string
+  updatedAt: string
+}
+
+/** AgentTeam 详情(v10 用户隔离字段) */
+export interface TeamDto {
+  id: string
+  name: string
+  description?: string
+  visibility: 'private' | 'public'
+  isBuiltin: boolean
+  ownerUserId: string | null
+  ownerName?: string | null
+  members: Array<{ templateId: string, name: string, harness: string, role: 'lead' | 'worker', addedAt: string }>
+  createdAt: string
+  updatedAt: string
+}
+
+/** Channel 模板成员条目(引用 Agent 模板或内联定义) */
+export type ChannelTemplateMemberDto
+  = | { templateId: string, role: 'lead' | 'worker' }
+    | { inline: { name: string, harness: string, config?: Record<string, unknown> }, role: 'lead' | 'worker' }
+
+/** Channel 模板详情(场景 + 工作目录 + 成员组合;v10) */
+export interface ChannelTemplateDto {
+  id: string
+  name: string
+  description: string
+  scenarioPrompt: string
+  workspace: string
+  lead: { name: string, harness: string, config?: Record<string, unknown> } | null
+  members: ChannelTemplateMemberDto[]
+  visibility: 'private' | 'public'
+  isBuiltin: boolean
+  ownerUserId: string | null
+  ownerName?: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+/** AepSnapshot 的轻量 REST 对齐(WS 未连时兜底刷新;实际从 WS channel.snapshot 取) */
+export type { AepSnapshot }