agentworkshop 0.2.1

package/app/composables/useCodeCopy.ts

@@ -0,0 +1,30 @@
+/**
+ * 代码块复制(事件委托单例):mdLite 渲染的 `.code-copy` 按钮点击 →
+ * 复制同块 <pre><code> 文本 → 按钮瞬时"已复制"反馈。
+ * document 级监听,时间线/lanes/抽屉内任意代码块通用,重复调用幂等。
+ */
+let installed = false
+
+export function useCodeCopy(): void {
+  if (installed || typeof document === 'undefined') return
+  installed = true
+  document.addEventListener('click', (ev) => {
+    const btn = (ev.target as HTMLElement | null)?.closest?.('.code-copy')
+    if (!(btn instanceof HTMLElement)) return
+    const block = btn.closest('.code-block')
+    const code = block?.querySelector('pre code')?.textContent ?? ''
+    const done = (): void => {
+      const prev = btn.textContent
+      btn.textContent = '已复制'
+      setTimeout(() => {
+        btn.textContent = prev ?? '复制'
+      }, 1400)
+    }
+    if (navigator.clipboard?.writeText) {
+      navigator.clipboard.writeText(code).then(done, done)
+    }
+    else {
+      done()
+    }
+  })
+}

package/app/composables/useHttp.ts

@@ -0,0 +1,8 @@
+/**
+ * HTTP 组合式入口，封装 nuxtApp.$http 的类型化访问。
+ * 用法：const { get, post } = useHttp()
+ */
+export function useHttp() {
+  const { $http } = useNuxtApp()
+  return $http
+}

package/app/composables/useRouteMeta.ts

@@ -0,0 +1,50 @@
+/**
+ * 路径 → 航迹元数据(标题/图标):
+ *  - 静态路由按菜单表;i18n 响应式派生,语言切换即时生效
+ *  - 动态路由 /workshop/w/:id 用 workspace 名称(异步加载后 reactive 刷新)
+ */
+import { useWorkspacesStore } from '@/app/stores/workshop/workspaces'
+
+export interface RouteMeta {
+  title: string
+  icon: string
+}
+
+export function useRouteMeta() {
+  const { t } = useI18n()
+  const workspaces = useWorkspacesStore()
+
+  /** 静态路由表:标题存 i18n key(metaFor 求值时才 t(),语言切换即时生效) */
+  const staticMap: Record<string, { key: string, icon: string }> = {
+    '/': { key: 'menu.dashboard', icon: 'i-tabler-layout-dashboard' },
+    '/workshop': { key: 'menu.workshop', icon: 'i-tabler-box' },
+
+    '/workshop/agents': { key: 'meta.agents', icon: 'i-tabler-users' },
+
+    '/workshop/teams': { key: 'meta.teams', icon: 'i-tabler-users-group' },
+
+    '/workshop/channel-templates': { key: 'meta.ctpl', icon: 'i-tabler-layout-grid-add' },
+    '/town': { key: 'menu.town', icon: 'i-tabler-map-2' },
+    '/tokens': { key: 'menu.tokens', icon: 'i-tabler-key' },
+    '/users': { key: 'menu.users', icon: 'i-tabler-users-group' },
+    '/monitor': { key: 'menu.monitor', icon: 'i-tabler-cpu' },
+    '/settings': { key: 'menu.settings', icon: 'i-tabler-settings' },
+  }
+
+  const metaFor = (path: string): RouteMeta => {
+    const direct = staticMap[path]
+    if (direct) return { title: t(direct.key), icon: direct.icon }
+
+    // 动态:/workshop/w/<id> → workspace 名称(未加载时用短 id 占位)
+    const wsMatch = path.match(/^\/workshop\/w\/([^/]+)$/)
+    if (wsMatch) {
+      const id = wsMatch[1]!
+      const name = workspaces.workspaces.find(w => w.id === id)?.name
+      return { title: name ?? `${t('header.workspace')} ${id.slice(0, 6)}`, icon: 'i-tabler-console' }
+    }
+
+    return { title: path.split('/').filter(Boolean).pop() ?? '·', icon: 'i-tabler-point' }
+  }
+
+  return { metaFor }
+}

package/app/composables/useSiteConfig.ts

@@ -0,0 +1,21 @@
+/**
+ * 统一读取运行时配置（来自 config.yml -> runtimeConfig.public）
+ * 全应用通过 useSiteConfig() 消费，避免散落 useRuntimeConfig()。
+ */
+export function useSiteConfig() {
+  const c = useRuntimeConfig().public
+  return {
+    name: c.appName as string,
+    title: c.appTitle as string,
+    version: c.version as string,
+    description: c.description as string,
+    mode: c.mode as string,
+    apiBase: c.apiBase as string,
+    apiTimeout: c.apiTimeout as number,
+    primaryColor: c.primaryColor as string,
+    themeMode: c.themeMode as 'light' | 'dark',
+    serverHost: c.serverHost as string,
+    devPort: c.devPort as number,
+    prodPort: c.prodPort as number,
+  }
+}

package/app/composables/workshop/apiClient.ts

@@ -0,0 +1,95 @@
+/**
+ * 统一 API 客户端 —— 全部手写 fetch 的单一收口。
+ * - 信封解析:{code, message, data};code !== 0 或非 2xx 一律抛 ApiError
+ * - ApiError 保留业务码与 HTTP 状态(调用方可分支),message 为后端可读文案
+ * - 网络层失败(TypeError/断网)→ ApiError('NETWORK'),不再裸奔 "Failed to fetch"
+ * - 幂等 GET 可选自动重试(5xx/网络错误;400ms 起退避);写操作永不重试
+ */
+
+export class ApiError extends Error {
+  readonly code: string | number
+  readonly status: number
+
+  constructor(code: string | number, status: number, message: string) {
+    super(message)
+    this.name = 'ApiError'
+    this.code = code
+    this.status = status
+  }
+}
+
+/** 鉴权头(cookie token → Bearer;与既有会话契约同源) */
+function authHeaders(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
+}
+
+const sleep = (ms: number) => new Promise(r => setTimeout(r, ms))
+
+function isIdempotent(init?: RequestInit): boolean {
+  const method = (init?.method ?? 'GET').toUpperCase()
+  return method === 'GET' || method === 'HEAD'
+}
+
+/** 单次请求:信封解析 + 错误归一化(所有失败路径都抛 ApiError) */
+async function attemptOnce<T>(base: string, path: string, init?: RequestInit): Promise<T> {
+  let res: Response
+  try {
+    res = await fetch(base + path, { ...init, headers: { ...authHeaders(!!init?.body), ...init?.headers } })
+  }
+  catch {
+    throw new ApiError('NETWORK', 0, '无法连接服务器，请检查网络或服务状态')
+  }
+  let json: { code?: string | number, message?: string, data?: T } | null = null
+  try {
+    json = await res.json()
+  }
+  catch {
+    // 非 JSON 响应(代理/网关 HTML 错误页等)——按状态码归一化
+  }
+  if (!res.ok) {
+    throw new ApiError(
+      json?.code ?? `HTTP_${res.status}`,
+      res.status,
+      json?.message || `请求失败(HTTP ${res.status})`,
+    )
+  }
+  if (json?.code !== 0) {
+    throw new ApiError(json?.code ?? 'REQUEST_ERROR', res.status, json?.message || '请求失败')
+  }
+  return json.data as T
+}
+
+/**
+ * 统一请求入口。
+ * @param opts.base   API 前缀(如 '/api/workshop/daq')
+ * @param opts.path   路径后缀(如 '/:id/bind')
+ * @param opts.init   fetch RequestInit(body 由调用方 JSON.stringify)
+ * @param opts.retries 幂等请求额外重试次数(仅 5xx/网络错误;默认 0)
+ */
+export async function apiFetch<T>(opts: { base: string, path?: string, init?: RequestInit, retries?: number }): Promise<T> {
+  const { base, path = '', init, retries = 0 } = opts
+  const idempotent = isIdempotent(init)
+  const attempts = idempotent ? retries + 1 : 1
+  let lastError: ApiError | undefined
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      return await attemptOnce<T>(base, path, init)
+    }
+    catch (err) {
+      const apiErr = err instanceof ApiError
+        ? err
+        : new ApiError('INTERNAL_ERROR', 0, err instanceof Error ? err.message : String(err))
+      const retryable = idempotent && (apiErr.code === 'NETWORK' || apiErr.status >= 500)
+      lastError = apiErr
+      if (!retryable || attempt === attempts - 1) throw apiErr
+      await sleep(400 * (attempt + 1))
+    }
+  }
+  throw lastError ?? new ApiError('INTERNAL_ERROR', 0, '请求失败')
+}

package/app/composables/workshop/useCharacterAssets.ts

@@ -0,0 +1,292 @@
+/**
+ * useCharacterAssets —— 角色模型库(前端注册表 + REST 拉取/上传/绑定)。
+ *
+ * 职责:
+ *  - 拉取服务端资产清单(GET /api/workshop/assets/character)并 merge 内置约定模型;
+ *  - 上传新模型(POST /api/workshop/assets/character,multipart);
+ *  - 删除模型(引删保护 DELETE):仍被绑定 → 提示 used>0;
+ *  - 绑定模型到某 Agent(PATCH /api/workshop/channels/:cid/agents/:agentId/model)。
+ * 单例挂 globalThis,跨组件安全;store 为 reactive(异步加载完成后驱动组件重渲染)。
+ */
+import { reactive } from 'vue'
+
+export interface CharacterModel {
+  id: string
+  name: string
+  file: string
+  frames: number
+  frameWidth: number
+  frameHeight: number
+  /** 模型类型:sheet(精灵表) / glb(3D 角色) / dev(3D 设备/数字孪生实体) */
+  kind: 'sheet' | 'glb' | 'dev'
+  builtin: boolean
+  /** 是否被任一 agent 绑定(引删保护用) */
+  applied: boolean
+  hint?: string
+  /** 设备模型相对高度系数(1 = 基准;薄膜产线设备按设计稿比例错落) */
+  hFactor?: number
+}
+
+interface ApiAsset {
+  id: string
+  workspaceId: string
+  name: string
+  file: string
+  kind: string
+  sheet?: { frameWidth?: number, frameHeight?: number, frames?: number }
+  appliedTo?: string[]
+  author: string
+}
+
+const GLOBAL_KEY = '__characterAssets'
+
+interface CharacterAssetStore {
+  models: CharacterModel[]
+  loaded: boolean
+  loading: boolean
+  error: string
+  load(): Promise<void>
+  byId(id: string): CharacterModel | undefined
+  upload(file: File, opts: { name?: string, workspaceId?: string, frameWidth?: number, frameHeight?: number, frames?: number, kind?: string }): Promise<CharacterModel>
+  remove(id: string): Promise<{ used: number }>
+  /** 上传设备/实体 3D 模型(.glb/.gltf...)到 devices 目录(模型库即时可见) */
+  uploadDevice(file: File, name?: string): Promise<CharacterModel>
+  /** 删除设备模型文件(id = dev-folder-<base> 或 base) */
+  removeDevice(id: string): Promise<void>
+  bind(channelId: string, agentId: string, modelRef: string): Promise<void>
+}
+
+function fromApi(a: ApiAsset): CharacterModel {
+  return {
+    id: a.id,
+    name: a.name,
+    file: a.file,
+    frames: a.sheet?.frames ?? 4,
+    frameWidth: a.sheet?.frameWidth ?? 48,
+    frameHeight: a.sheet?.frameHeight ?? 88,
+    kind: a.kind === 'glb' ? 'glb' : a.kind === 'dev' ? 'dev' : 'sheet',
+    builtin: a.author === 'system',
+    applied: (a.appliedTo?.length ?? 0) > 0,
+  }
+}
+
+function createStore(): CharacterAssetStore {
+  const models: CharacterModel[] = []
+  // 内置约定模型(与 server 全局库同源;空白兜底,主以 REST 为准)
+  const builtins: CharacterModel[] = [
+    { id: 'knight', name: '灰羽骑士', file: '/assets/game/character/knight.png', frames: 4, frameWidth: 48, frameHeight: 88, kind: 'sheet', builtin: true, applied: false },
+    { id: 'mage', name: '紫晶法师', file: '/assets/game/character/mage.png', frames: 4, frameWidth: 48, frameHeight: 88, kind: 'sheet', builtin: true, applied: false },
+    { id: 'bot', name: '青枢机械', file: '/assets/game/character/bot.png', frames: 4, frameWidth: 48, frameHeight: 88, kind: 'sheet', builtin: true, applied: false },
+    { id: 'hero-3d', name: '标准员工模型', file: '/assets/game/character/hero-3d.glb', frames: 1, frameWidth: 0, frameHeight: 0, kind: 'glb', builtin: true, applied: false, hint: '默认员工 3D 模型' },
+    { id: 'device-3d', name: '工业泵设备', file: '/assets/game/character/device-3d.glb', frames: 1, frameWidth: 0, frameHeight: 0, kind: 'dev', builtin: true, applied: false, hint: '数字孪生实体模型(拖入场景生成设备)' },
+  ]
+
+  // 设备固定目录自动识别:把 public/assets/game/devices/ 下的所有 .glb 注册为 kind=dev 设备。
+  // 用户把设备/实体模型丢进该目录即自动出现在模型库,无需改代码。
+  // 主来源:服务端扫描 API(GET /api/workshop/assets/devices,运行期即时可见);
+  // 此处 Vite import.meta.glob 仅为服务端不可用时的本地兜底。
+  // 注意:Vite 的 import.meta.glob 参数必须是「直接字符串字面量」(不能是变量),且需用绝对根
+  // 路径 /public/... 才能命中 public/ 资产;返回 "/public/assets/game/devices/<name>.glb",
+  // 运行时实际服务路径去 "/public" 前缀 → /assets/game/devices/<name>.glb。
+  const deviceFallbacks: CharacterModel[] = []
+  try {
+    const deviceModules = import.meta.glob<string>('/public/assets/game/devices/*.glb', { eager: true, query: '?url', import: 'default' })
+    for (const [key, url] of Object.entries(deviceModules)) {
+      const base = key.split('/').pop() ?? ''
+      const id = 'dev-folder-' + base.replace(/\.glb$/i, '')
+      const servedFile = url.replace(/^\/public\//, '/')
+      deviceFallbacks.push({
+        id,
+        name: base.replace(/\.glb$/i, '').replace(/[-_]/g, ' '),
+        file: servedFile,
+        frames: 1,
+        frameWidth: 0,
+        frameHeight: 0,
+        kind: 'dev',
+        builtin: true,
+        applied: false,
+        hint: '设备实体(拖入场景生成数字孪生)',
+      })
+    }
+  }
+  catch {
+    // glob 不识别该相对路径时静默;不影响其余模型。
+  }
+  const headers = (json = true): Record<string, string> => {
+    // token 存在 cookie 'token'(user store 写入);读不到则从 user store 兜底
+    const cookieToken = typeof document !== 'undefined'
+      ? (document.cookie.match(/(?:^|;\s*)token=([^;]+)/)?.[1] ?? '')
+      : ''
+    const h: Record<string, string> = {}
+    const t = cookieToken || ''
+    if (t) h.authorization = `Bearer ${decodeURIComponent(t)}`
+    if (json) h['content-type'] = 'application/json'
+    return h
+  }
+
+  const store: CharacterAssetStore = reactive({
+    models,
+    loaded: false,
+    loading: false,
+    error: '',
+    async load() {
+      if (store.loading || store.loaded) return
+      store.loading = true
+      try {
+        // 角色资产(上传/全局库)+ 设备/角色 3D 模型资源扫描(真实目录,运行期即时)并行拉取
+        const [charRes, scanRes] = await Promise.allSettled([
+          fetch('/api/workshop/assets/character', { headers: headers() }),
+          fetch('/api/workshop/assets/devices', { headers: headers() }),
+        ])
+        const charJson = charRes.status === 'fulfilled' ? await charRes.value.json().catch(() => ({})) : {}
+        const scanJson = scanRes.status === 'fulfilled' ? await scanRes.value.json().catch(() => ({})) : {}
+        const apiAssets: ApiAsset[] = charJson?.data?.assets ?? []
+        // 服务端扫描的设备模型(运行期新增立即可见;失败则静默,由本地兜底补)
+        const scannedDevices: CharacterModel[] = (scanJson?.data?.devices ?? []).map((d: { id: string, name: string, file: string, defaultScale?: number }) => ({
+          id: d.id,
+          name: d.name,
+          file: d.file,
+          frames: 1,
+          frameWidth: 0,
+          frameHeight: 0,
+          kind: 'dev' as const,
+          builtin: true,
+          applied: false,
+          hint: '设备实体(拖入场景生成数字孪生)',
+          hFactor: typeof d.defaultScale === 'number' && d.defaultScale > 0 ? d.defaultScale : 1,
+        }))
+        // 服务端扫描的角色 3D 模型(character 目录 .glb;供 Channel 成员换装,不进侧边模型库;
+        // 过滤掉与内置 hero-3d/device-3d 同文件的重复项,成员下拉只保留语义唯一的选项)
+        const builtinFiles = new Set(builtins.map(b => b.file))
+        const scannedCharacters: CharacterModel[] = (scanJson?.data?.characters ?? [])
+          .filter((d: { file: string }) => !builtinFiles.has(d.file))
+          .map((d: { id: string, name: string, file: string }) => ({
+            id: d.id,
+            name: d.name,
+            file: d.file,
+            frames: 1,
+            frameWidth: 0,
+            frameHeight: 0,
+            kind: 'glb' as const,
+            builtin: true,
+            applied: false,
+            hint: '角色 3D 模型(在频道成员管理中设置)',
+          }))
+        // REST 为准;内置约定补足(若有同名则用 API 版);扫描设备优先于本地 glob 兜底
+        const merged: CharacterModel[] = []
+        const seen = new Set<string>()
+        for (const a of apiAssets) {
+          merged.push(fromApi(a))
+          seen.add(a.id)
+        }
+        for (const d of scannedDevices) {
+          if (seen.has(d.id)) continue
+          merged.push(d)
+          seen.add(d.id)
+        }
+        for (const c of scannedCharacters) {
+          if (seen.has(c.id)) continue
+          merged.push(c)
+          seen.add(c.id)
+        }
+        for (const b of builtins) {
+          if (!seen.has(b.id)) merged.push(b)
+        }
+        for (const d of deviceFallbacks) {
+          if (!seen.has(d.id)) merged.push(d)
+        }
+        // 变更经 reactive 代理,驱动 AssetLibrary 等组件重渲染
+        store.models.splice(0, store.models.length, ...merged)
+        store.loaded = true
+        store.error = ''
+      }
+      catch (err) {
+        store.loaded = false
+        store.error = err instanceof Error ? err.message : String(err)
+      }
+      finally {
+        store.loading = false
+      }
+    },
+    byId(id) {
+      return models.find(m => m.id === id)
+    },
+    async upload(file, opts) {
+      const fd = new FormData()
+      fd.append('file', file)
+      fd.append('name', opts.name ?? file.name.replace(/\.[^.]+$/, ''))
+      fd.append('workspaceId', opts.workspaceId ?? '')
+      fd.append('kind', opts.kind ?? 'sheet')
+      fd.append('frameWidth', String(opts.frameWidth ?? 48))
+      fd.append('frameHeight', String(opts.frameHeight ?? 88))
+      fd.append('frames', String(opts.frames ?? 4))
+      const res = await fetch('/api/workshop/assets/character', { method: 'POST', headers: headers(false), body: fd })
+      const json = await res.json().catch(() => ({}))
+      if (!res.ok || !json?.data?.asset) {
+        throw new Error(json?.message ?? '上传失败')
+      }
+      // 从服务端同步最新清单(含新模型 + appliedTo)
+      store.loaded = false
+      await store.load()
+      return fromApi(json.data.asset)
+    },
+    async remove(id) {
+      const res = await fetch(`/api/workshop/assets/character/${id}`, { method: 'DELETE', headers: headers() })
+      const json = await res.json().catch(() => ({}))
+      if (!res.ok) throw new Error(json?.message ?? '删除失败')
+      // 重新拉取(仅当真正删除时 appliedTo 才会变)
+      store.loaded = false
+      await store.load()
+      return { used: json?.data?.used ?? 0 }
+    },
+    async uploadDevice(file, name) {
+      const fd = new FormData()
+      fd.append('file', file)
+      if (name) fd.append('name', name)
+      const res = await fetch('/api/workshop/assets/devices', { method: 'POST', headers: headers(false), body: fd })
+      const json = await res.json().catch(() => ({}))
+      if (!res.ok || !json?.data?.asset) throw new Error(json?.message ?? '设备模型上传失败')
+      store.loaded = false
+      await store.load()
+      const a = json.data.asset
+      return {
+        id: a.id,
+        name: a.name,
+        file: a.file,
+        frames: 1,
+        frameWidth: 0,
+        frameHeight: 0,
+        kind: 'dev' as const,
+        builtin: false,
+        applied: false,
+        hint: '设备实体(拖入场景生成数字孪生)',
+      }
+    },
+    async removeDevice(id) {
+      const key = id.replace(/^dev-folder-/, '')
+      const res = await fetch(`/api/workshop/assets/devices/${encodeURIComponent(key)}`, { method: 'DELETE', headers: headers() })
+      const json = await res.json().catch(() => ({}))
+      if (!res.ok) throw new Error(json?.message ?? '设备模型删除失败')
+      store.loaded = false
+      await store.load()
+    },
+    async bind(channelId, agentId, modelRef) {
+      const res = await fetch(`/api/workshop/channels/${channelId}/agents/${agentId}/model`, {
+        method: 'PATCH',
+        headers: headers(),
+        body: JSON.stringify({ modelRef }),
+      })
+      const json = await res.json().catch(() => ({}))
+      if (!res.ok) throw new Error(json?.message ?? '绑定失败')
+    },
+  })
+  return store
+}
+
+export function useCharacterAssets(): CharacterAssetStore {
+  const g = globalThis as unknown as Record<string, CharacterAssetStore | undefined>
+  if (!g[GLOBAL_KEY]) g[GLOBAL_KEY] = createStore()
+  const store = g[GLOBAL_KEY]!
+  void store.load()
+  return store
+}

package/app/composables/workshop/useClusteredBlocks.ts

@@ -0,0 +1,150 @@
+/**
+ * 流式块消费:events store 与 BlockClusterer 的绑定层。
+ *
+ * 消费模型(对旧版的修改):
+ *  - 旧版 TranscriptTimeline 每次响应式触发都对整条时间线执行 aggregateEvents 重建;
+ *    这里是增量消费:新帧只推入聚类器,块对象身份稳定 → Vue 组件按 key 复用无满屏闪动
+ *  - cid / filter / focus / predicate 变化 → 聚类器全量 reset + 一次重建(过滤语义必须重算)
+ *  - 块数组同一 identity,在 v-for 中直接使用
+ *  - raw 模式(lanes 用):源 = ring 原始 items + 调用方 predicate,绕过 timeline 的
+ *    filter/focus —— 时间线聚焦某 agent 时(Inspector 设置 focusAgents),非聚焦 lane
+ *    不能跟着清空;lanes 的重置仅由 cid / predicate / resetKey 驱动
+ *
+ * 呈现节流(Agent-UI 聚合消费,修复"空白块 + 断断续续渲染"):
+ *  - 帧到达即入聚类器(状态零延迟,去重/折回基于全量数据),但呈现(发布到 v-for)
+ *    按聚合窗合批:过程帧(delta/工具/进度)160ms 合并为一次呈现 —— 新块"攒够了"再上屏,
+ *    不再 1-2 个字符地闪现断续
+ *  - 终局/外显帧(落定消息/交付/错误/任务迁移/点对点消息/成员变更/生命周期)即时呈现
+ *  - 尾部流块未落定且累计文本不足 8 字符时本拍暂缓(攒出实质内容再上屏);落定必然呈现
+ *  - 块内增量文本仍实时(块对象 reactive,既有流块内的打字机增量不经发布通道直传渲染端)
+ *    —— 合批只作用于"新块出现"的粒度,不牺牲流式可见性
+ */
+import { computed, onScopeDispose, shallowRef, watch } from 'vue'
+import type { MaybeRefOrGetter } from 'vue'
+import type { AepEnvelope } from '#shared/workshop-protocol'
+import { useEventsStore } from '../../stores/workshop/events'
+import { BlockClusterer, buildStreamText, type EventBlock } from './useEventBlocks'
+
+/** 聚合窗:过程帧突发合并为一次呈现(ms) */
+const FLUSH_MS = 160
+/** 尾部流块最小可见文本(字符):不足则暂缓一拍,避免 1-2 字符的"准空白"块闪现 */
+const MIN_STREAM_PREVIEW = 8
+/** 即时呈现的终局/外显帧:结果类与状态翻转类内容不合批 */
+const IMMEDIATE_TYPES = new Set([
+  'agent.message',
+  'a2a.artifact',
+  'error',
+  'task.status',
+  'a2a.message',
+  'agent.member',
+  'agent.status',
+])
+
+export function useClusteredBlocks(
+  channelId: MaybeRefOrGetter<string | null | undefined>,
+  opts: {
+    /**
+     * 事件谓词(直接传函数本体)。注意不能用 toValue 解包:Vue 的 toValue 对函数
+     * 会直接调用,谓词会被无参执行而崩溃;谓词上下文变化由 resetKey 驱动重建。
+     */
+    predicate?: ((e: AepEnvelope) => boolean) | null | undefined
+    /** 外部谓词捕获的上下文(如 agentId)变化 → 全量重建 */
+    resetKey?: MaybeRefOrGetter<unknown>
+    /** raw 源:绕过 timeline 的 filter/focus(lanes 场景),用 ring items + predicate */
+    raw?: boolean
+  } = {},
+) {
+  const events = useEventsStore()
+  const clusterer = new BlockClusterer()
+  const blocks = shallowRef<EventBlock[]>(clusterer.blocks)
+
+  const cid = computed(() => toValue(channelId) ?? '')
+  const filterVal = computed(() => events.filters[cid.value] ?? 'all')
+  const focusVal = computed(() => events.focusAgents[cid.value] ?? null)
+  const resetKeyVal = computed(() => toValue(opts.resetKey))
+  const predRaw = computed(() => opts.predicate ?? null)
+
+  const list = computed(() => {
+    if (opts.raw) return cid.value ? events.ring(cid.value).items : []
+    return cid.value ? events.timeline(cid.value) : []
+  })
+  const source = computed(() => {
+    // resetKey(外部捕获上下文)列入依赖:变化时 source 重算,配合下方重置重建
+    void resetKeyVal.value
+    return predRaw.value ? list.value.filter(predRaw.value) : list.value
+  })
+
+  // ===== 呈现节流(聚合消费) =====
+  let flushTimer: ReturnType<typeof setTimeout> | null = null
+  /** reset 重建挂起:过滤/频道切换后的重算必须立即全量呈现(不能等聚合窗) */
+  let rebuildPending = false
+
+  /**
+   * 呈现过滤(空壳块全量防线):
+   *  ① 无文本流块(纯空白 delta 累计 / 中断回合)任何位置都不上屏——壳都不给
+   *  ② 尾部活动流块且累计文本不足阈值 → 本拍暂缓(攒出实质内容再上屏);
+   *     仅限 tail(仍可能增长);被后续块顶离尾部的短流块是已成内容,照常显示
+   */
+  const presentable = (list: EventBlock[]): EventBlock[] => {
+    if (list.length === 0) return list
+    const lastIdx = list.length - 1
+    return list.filter((b, i) => {
+      if (b.kind !== 'stream') return true
+      const text = buildStreamText(b).trim()
+      if (!text && !b.overrideText) return false
+      if (i === lastIdx && !b.settled && text.length < MIN_STREAM_PREVIEW) return false
+      return true
+    })
+  }
+
+  const publish = (): void => {
+    if (flushTimer != null) {
+      clearTimeout(flushTimer)
+      flushTimer = null
+    }
+    blocks.value = presentable(clusterer.blocks)
+  }
+
+  /** 终局帧/重建 → 即时呈现;过程帧(delta/status.message/tool/progress)→ 聚合窗合批 */
+  const schedulePublish = (immediate: boolean): void => {
+    if (immediate || rebuildPending) {
+      rebuildPending = false
+      publish()
+      return
+    }
+    if (flushTimer != null) return
+    flushTimer = setTimeout(publish, FLUSH_MS)
+  }
+  onScopeDispose(() => {
+    if (flushTimer != null) clearTimeout(flushTimer)
+  })
+
+  if (opts.raw) {
+    // raw 模式:filter/focus 不影响源,重置仅由 cid / predicate / 上下文驱动
+    watch([cid, predRaw, resetKeyVal], () => {
+      clusterer.reset()
+      rebuildPending = true
+    }, { immediate: true })
+  }
+  else {
+    // 过滤/聚焦/predicate/上下文变化 → 全量重建(先注册先执行,重置先于同步)
+    watch([cid, filterVal, focusVal, predRaw, resetKeyVal], () => {
+      clusterer.reset()
+      rebuildPending = true
+    }, { immediate: true })
+  }
+
+  watch(source, (l) => {
+    // 尾帧类别决定呈现 urgency:终局/外显帧即时,过程帧合批
+    const tail = l[l.length - 1]
+    const immediate = tail != null && IMMEDIATE_TYPES.has(tail.type)
+    clusterer.sync(l)
+    schedulePublish(immediate)
+  }, { immediate: true })
+
+  const totalEvents = computed(() => source.value.length)
+
+  return { blocks, totalEvents, clusterer }
+}
+
+export type { EventBlock }

package/app/composables/workshop/useComposerBus.ts

@@ -0,0 +1,16 @@
+/**
+ * Composer 指令总线:块工具条「引用到输入框」→ Composer 消费。
+ * 模块级单例 ref(跨组件树;时间线块与 Composer 无父子关系)。
+ */
+import { ref } from 'vue'
+
+const quoteText = ref<string | null>(null)
+
+export function useComposerBus() {
+  /** 请求把文本以引用形式带入 Composer */
+  const quote = (text: string): void => {
+    quoteText.value = text
+  }
+
+  return { quoteText, quote }
+}