agentworkshop 0.2.1

package/app/stores/workshop/entities.ts

@@ -0,0 +1,350 @@
+/**
+ * 实体归一化:channel/agent/task 快照 + AEP 增量 upsert(幂等)。
+ * REST 命令后的状态以 WS 事件回流为准(REST 返回值不直接写状态,避免双源)。
+ */
+import { defineStore } from 'pinia'
+import { useUserStore } from './user'
+import type { AepEnvelope, AepSnapshot } from '#shared/workshop-protocol'
+
+export interface AgentView {
+  agentId: string
+  name: string
+  role: 'lead' | 'worker'
+  harness: string
+  /** 实例启停(1 启用 / 0 禁用;缺省视为启用) */
+  enabled?: number
+  state: 'idle' | 'busy' | 'stopped'
+  /** 场景配置(含 systemPromptPrefix 等;由 WS 快照下发) */
+  config?: Record<string, unknown>
+  currentTaskId?: string | null
+  /** 执行中任务标题(lead 观察 worker 在干什么) */
+  currentTaskTitle?: string | null
+  /** 执行中任务进度 0-100(空闲/未上报为 null) */
+  currentTaskProgress?: number | null
+  /** 用户给该角色绑定的自定义模型(assetId;缺省用内置员工模型) */
+  modelRef?: string | null
+  queued?: number
+  completed?: number
+}
+
+export interface TaskView {
+  id: string
+  parentId?: string
+  title: string
+  state: string
+  progress: number
+  assigneeId: string
+  artifacts: number
+  /** 派发路由理由(lead 审计决策) */
+  routeReason?: string
+  createdAt?: string
+  updatedAt?: string
+}
+
+export const useEntitiesStore = defineStore('workshop.entities', {
+  state: () => ({
+    channels: {} as Record<string, AepSnapshot['channel'] & { loadedAt: number }>,
+    agents: {} as Record<string, AgentView[]>,
+    tasks: {} as Record<string, TaskView[]>,
+    /** refreshTasks 进行中标志(节流) */
+    refreshing: {} as Record<string, boolean>,
+    /** refreshAgents 进行中标志(节流) */
+    refreshingAgents: {} as Record<string, boolean>,
+  }),
+  getters: {
+    agentById(state) {
+      return (channelId: string, agentId: string): AgentView | undefined =>
+        state.agents[channelId]?.find(a => a.agentId === agentId)
+    },
+    /** agent 名字解析(事件渲染用):已知成员取名字,否则 id 前 8 位 */
+    agentName(state) {
+      return (channelId: string, agentId?: string | null): string => {
+        if (!agentId) return 'system'
+        const a = state.agents[channelId]?.find(x => x.agentId === agentId)
+        return a?.name ?? agentId.slice(0, 8)
+      }
+    },
+    /** 任务标题解析(事件渲染用):已知任务取标题,否则 id 前 8 位 */
+    taskTitle(state) {
+      return (channelId: string, taskId?: string | null): string => {
+        if (!taskId) return ''
+        const t = state.tasks[channelId]?.find(x => x.id === taskId)
+        return t?.title ?? taskId.slice(0, 8)
+      }
+    },
+    rootTasks(state) {
+      return (channelId: string): TaskView[] =>
+        (state.tasks[channelId] ?? []).filter(t => !t.parentId)
+    },
+    taskById(state) {
+      return (channelId: string, taskId: string): TaskView | undefined =>
+        state.tasks[channelId]?.find(t => t.id === taskId)
+    },
+    busyCount(state) {
+      return (channelId: string): number =>
+        (state.agents[channelId] ?? []).filter(a => a.state === 'busy').length
+    },
+  },
+  actions: {
+    applySnapshot(payload: AepSnapshot): void {
+      const { channelId } = payload
+      this.channels[channelId] = { ...payload.channel, loadedAt: Date.now() }
+      // 快照 agents 携带 config(server buildSnapshot);换装元数据 modelRef 从 config 派生,
+      // 保证「再次进入直接加载用户选择的模型」——与 agent.member 事件路径同一语义。
+      this.agents[channelId] = payload.agents.map(a => ({
+        ...a,
+        modelRef: (a as { config?: Record<string, unknown> }).config?.modelRef as string | undefined
+          ?? (a as { modelRef?: string | null }).modelRef
+          ?? null,
+      }))
+      this.tasks[channelId] = payload.tasks.map(t => this.toTaskView(t))
+    }, applyEvent(e: AepEnvelope): void {
+      const cid = e.channelId
+      switch (e.type) {
+        case 'agent.status': {
+          const list = this.agents[cid] ?? []
+          // 协议字段 queued/completed 为准;兼容旧帧(queuedCount/completedCount),避免 undefined 覆写实体
+          const raw = e.payload as {
+            agentId: string
+            state: AgentView['state']
+            currentTaskId?: string | null
+            currentTaskTitle?: string | null
+            currentTaskProgress?: number | null
+            queued?: number
+            completed?: number
+            queuedCount?: number
+            completedCount?: number
+          }
+          const p = {
+            agentId: raw.agentId,
+            state: raw.state,
+            currentTaskId: raw.currentTaskId ?? null,
+            currentTaskTitle: raw.currentTaskTitle ?? null,
+            currentTaskProgress: raw.currentTaskProgress ?? null,
+            queued: raw.queued ?? raw.queuedCount ?? 0,
+            completed: raw.completed ?? raw.completedCount ?? 0,
+          }
+          const idx = list.findIndex(a => a.agentId === p.agentId)
+          if (idx >= 0) {
+            list[idx] = { ...list[idx]!, ...p }
+          }
+          else {
+            // 新 agent 只能从事件构建(无快照)→ 补默认名/角色/harness;显式构造避免 spread 覆盖
+            const fresh: AgentView = {
+              agentId: p.agentId,
+              state: p.state,
+              currentTaskId: p.currentTaskId ?? null,
+              queued: p.queued,
+              completed: p.completed,
+              name: p.agentId.slice(0, 8),
+              role: 'worker',
+              harness: '-',
+            }
+            list.push(fresh)
+            // 事件缺名字/角色等元信息 → 节流 REST 对齐补全(与任务同策略)
+            this.refreshAgents(cid)
+          }
+          this.agents[cid] = [...list]
+          break
+        }
+        case 'agent.member': {
+          // 团队成员增/改/删(lead 执行中自主管理或用户 REST):实体列表实时增删改
+          const p = e.payload as {
+            op: 'added' | 'updated' | 'removed'
+            agentId: string
+            name: string
+            role: 'lead' | 'worker'
+            harness: string
+            enabled?: number
+            config?: Record<string, unknown>
+            by: string
+            reason?: string
+          }
+          const list = this.agents[cid] ?? []
+          const idx = list.findIndex(a => a.agentId === p.agentId)
+          if (p.op === 'added') {
+            if (idx < 0) {
+              list.push({
+                agentId: p.agentId,
+                name: p.name,
+                role: p.role,
+                harness: p.harness,
+                enabled: p.enabled,
+                config: p.config,
+                modelRef: (p.config as { modelRef?: string } | undefined)?.modelRef ?? null,
+                state: 'idle',
+                currentTaskId: null,
+                queued: 0,
+                completed: 0,
+              })
+            }
+          }
+          else if (p.op === 'updated') {
+            if (idx >= 0) {
+              const prev = list[idx]!
+              const nextConfig = p.config ?? prev.config
+              list[idx] = {
+                ...prev,
+                name: p.name ?? prev.name,
+                role: p.role ?? prev.role,
+                harness: p.harness ?? prev.harness,
+                enabled: p.enabled ?? prev.enabled,
+                config: nextConfig,
+                modelRef: (nextConfig as { modelRef?: string } | undefined)?.modelRef ?? prev.modelRef ?? null,
+              }
+            }
+          }
+          else if (p.op === 'removed') {
+            if (idx >= 0) list.splice(idx, 1)
+          }
+          this.agents[cid] = [...list]
+          break
+        }
+        case 'task.status': {
+          // 事件正文携带标题/父级/进度/交付数(ws.ts 随任务行直推)→ 事件即实体,任务无需 REST 即可全量渲染
+          const p = e.payload as {
+            taskId: string
+            state: string
+            assigneeId?: string
+            title?: string
+            parentId?: string
+            progress?: number
+            routeReason?: string
+            createdAt?: string
+            artifacts?: number
+          }
+          const list = this.tasks[cid] ?? []
+          const idx = list.findIndex(t => t.id === p.taskId)
+          if (idx >= 0) {
+            const prev = list[idx]!
+            list[idx] = {
+              ...prev,
+              state: p.state,
+              assigneeId: p.assigneeId ?? prev.assigneeId,
+              title: p.title ?? prev.title,
+              parentId: p.parentId ?? prev.parentId,
+              progress: Math.max(prev.progress, p.progress ?? 0),
+              routeReason: p.routeReason ?? prev.routeReason,
+              createdAt: p.createdAt ?? prev.createdAt,
+              artifacts: Math.max(prev.artifacts, p.artifacts ?? 0),
+            }
+          }
+          else {
+            const fresh: TaskView = {
+              id: p.taskId,
+              title: p.title ?? p.taskId.slice(0, 8),
+              state: p.state,
+              progress: p.progress ?? 0,
+              assigneeId: p.assigneeId ?? '',
+              artifacts: p.artifacts ?? 0,
+            }
+            if (p.parentId) fresh.parentId = p.parentId
+            if (p.routeReason) fresh.routeReason = p.routeReason
+            if (p.createdAt) fresh.createdAt = p.createdAt
+            list.push(fresh)
+            // 旧服务端帧不含正文(title 缺失)→ 兜底节流 REST 补全(新帧已自足,此路径不再触发)
+            if (p.title === undefined) this.refreshTasks(cid)
+          }
+          this.tasks[cid] = [...list]
+          break
+        }
+        case 'task.progress': {
+          const p = e.payload as { taskId: string, progress: number }
+          const list = this.tasks[cid] ?? []
+          const idx = list.findIndex(t => t.id === p.taskId)
+          const prev = idx >= 0 ? list[idx] : undefined
+          if (prev) list[idx] = { ...prev, progress: p.progress }
+          this.tasks[cid] = [...list]
+          break
+        }
+        case 'a2a.artifact': {
+          const p = e.payload as { taskId?: string }
+          if (!p.taskId) break
+          const list = this.tasks[cid] ?? []
+          const idx = list.findIndex(t => t.id === p.taskId)
+          const prev = idx >= 0 ? list[idx] : undefined
+          if (prev) list[idx] = { ...prev, artifacts: prev.artifacts + 1 }
+          this.tasks[cid] = [...list]
+          break
+        }
+      }
+    },
+    toTaskView(t: AepSnapshot['tasks'][number]): TaskView {
+      return {
+        id: t.id,
+        parentId: t.parentId,
+        title: t.title,
+        state: t.state,
+        progress: t.progress,
+        assigneeId: t.assigneeId,
+        artifacts: t.artifacts.length,
+        updatedAt: t.updatedAt,
+      }
+    },
+    /** WS 断连后的 REST 兜底刷新(命令后立即对齐用) */
+    refreshChannel(channelId: string, snapshot: AepSnapshot): void {
+      this.applySnapshot(snapshot)
+    },
+    /**
+     * 节流 REST 成员对齐:事件流里冒出的未知 agent 缺 name/role/harness 元信息,
+     * 拉一次成员列表 upsert(以 REST 为准;事件流继续增量更新 state)。
+     */
+    refreshAgents(channelId: string): void {
+      if (this.refreshingAgents[channelId]) return
+      this.refreshingAgents[channelId] = true
+      $fetch<{ data?: Array<{ id: string, name: string, role: 'lead' | 'worker', harness: string, config?: Record<string, unknown> }> }>(
+        `/api/workshop/channels/${channelId}/agents`,
+        { headers: { authorization: `Bearer ${useUserStore().token}` } },
+      )
+        .then((res) => {
+          const fresh = res.data ?? []
+          const merged = [...(this.agents[channelId] ?? [])]
+          for (const m of fresh) {
+            const idx = merged.findIndex(a => a.agentId === m.id)
+            if (idx >= 0) merged[idx] = { ...merged[idx]!, name: m.name, role: m.role, harness: m.harness, config: m.config }
+            else merged.push({ agentId: m.id, name: m.name, role: m.role, harness: m.harness, config: m.config, state: 'idle', currentTaskId: null, queued: 0, completed: 0 })
+          }
+          this.agents[channelId] = merged
+        })
+        .catch(() => {})
+        .finally(() => {
+          this.refreshingAgents[channelId] = false
+        })
+    },
+    /**
+     * 节流 REST 任务对齐:订阅后新建任务从事件构建时缺标题/父子关系,
+     * 拉一次任务列表 upsert(以 REST 为准;事件流继续增量更新)。
+     */
+    refreshTasks(channelId: string): void {
+      if (this.refreshing[channelId]) return
+      this.refreshing[channelId] = true
+      $fetch<{ data?: AepSnapshot['tasks'] }>(`/api/workshop/channels/${channelId}/tasks`, {
+        headers: { authorization: `Bearer ${useUserStore().token}` },
+      })
+        .then((res) => {
+          const fresh = res.data ?? []
+          const current = this.tasks[channelId] ?? []
+          const byId = new Map(current.map(t => [t.id, t]))
+          // upsert 合并(不整表替换):REST 为准补全已知任务;WS 已知但 REST 尚未
+          // 返回的极新任务保留(防丢失);重叠任务 progress 取两侧较大(state/title 以 REST 为准,
+          // 避免旧事件帧状态黏附——REST 与 WS 同源于 DB,REST 至少不旧于已消费事件)
+          const freshIds = new Set(fresh.map(t => t.id))
+          const merged = fresh.map((t) => {
+            const prev = byId.get(t.id)
+            const next = this.toTaskView(t)
+            return prev && prev.progress > next.progress
+              ? { ...next, progress: prev.progress }
+              : next
+          })
+          for (const t of current) {
+            if (!freshIds.has(t.id)) merged.push(t)
+          }
+          this.tasks[channelId] = merged
+        })
+        .catch(() => {})
+        .finally(() => {
+          this.refreshing[channelId] = false
+        })
+    },
+  },
+})

package/app/stores/workshop/events.ts

@@ -0,0 +1,292 @@
+/**
+ * AEP 事件缓冲:per-channel 环形(ring 5000,与服务端 RING_CAP 同量级)+
+ * lastSeq 游标 + 派生 selectors。全部渲染组件从本 store 派生,不直接持有事件。
+ */
+import { defineStore } from 'pinia'
+import { useUserStore } from './user'
+import { envelopeTier } from '@/app/composables/workshop/useEventBlocks'
+import type { AepEnvelope } from '#shared/workshop-protocol'
+
+const RING_CAP = 5000
+
+/**
+ * 历史回放剔除的过程帧:agent.delta 的打字机增量在历史里由落定 agent.message
+ * 携带全文(终帧必落库),逐帧重放既浪费窗口又会把单 agent 的流式帧灌满
+ * 全局 200 帧限额 —— 其他 agent 的消息一条都进不来(lane 空 <-> 时间线缺消息)。
+ */
+const HISTORY_EXCLUDE_TYPES = ['agent.delta']
+
+export type EventFilter = 'all' | 'messages' | 'tasks' | 'team' | 'errors' | 'key'
+
+/** 过滤器 → 允许的事件类型集合(key = 档位过滤:只看注意级+终局级,open-tag deliveryTier) */
+const FILTER_TYPES: Record<EventFilter, string[] | null> = {
+  all: null,
+  messages: ['agent.message', 'agent.delta', 'agent.status.message', 'a2a.message'],
+  tasks: ['task.status', 'task.progress', 'a2a.artifact'],
+  team: ['agent.member', 'task.status'],
+  errors: ['error'],
+  key: null,
+}
+
+/** 时间线过滤纯函数(记忆化缓存的真实计算体) */
+function computeTimeline(
+  items: AepEnvelope[],
+  filter: EventFilter,
+  allow: string[] | null,
+  focus: string | null,
+): AepEnvelope[] {
+  return items.filter((e) => {
+    if (e.type === 'channel.snapshot') return false
+    // key 过滤:只看注意级 + 终局级(open-tag deliveryTier —— agent 噪声让路)
+    if (filter === 'key') {
+      const t = envelopeTier(e)
+      return t === 'attention' || t === 'terminal'
+    }
+    if (allow && !allow.includes(e.type)) return false
+    if (focus && e.type !== 'task.status' && e.type !== 'task.progress') {
+      if (e.agentId === focus) return true
+      // 消息归属发送方,但发给聚焦 Agent 的消息(a2a.message target)仍属其流
+      if (e.type === 'a2a.message') {
+        const target = (e.payload as { metadata?: { 'x-aw-target-agent'?: string } }).metadata?.['x-aw-target-agent']
+        return target === focus
+      }
+      return false
+    }
+    return true
+  })
+}
+
+/** per-channel 时间线记忆化(key 含 lastSeq/条数/过滤态;原 getter 每访问全量过滤 5000 帧) */
+const timelineCache = new Map<string, { key: string, result: AepEnvelope[] }>()
+
+interface ChannelRing {
+  lastSeq: number
+  items: AepEnvelope[]
+  /**
+   * 已消费过的全部 seq(含被 delta 合并吃掉的中间 seq)——loadHistory 的
+   * 去重依据:按 item.seq 精确匹配会漏掉合并帧,导致同段 delta 重复插入。
+   */
+  consumed: Set<number>
+}
+
+const EMPTY_RING = (): ChannelRing => ({ lastSeq: 0, items: [], consumed: new Set() })
+
+/** 历史接口响应壳(全局/lane 同构) */
+interface EventsHistoryRes {
+  code: number | string
+  data?: { items: AepEnvelope[], total?: number }
+}
+
+/**
+ * 历史帧合并(共享水路):seq ≤ ceiling 窗口校验(增量路径由 ingest 处理)+
+ * consumed 去重(含被合并吃掉的帧)→ 排序归位 + 容量裁剪。返回净新增数。
+ */
+function mergeHistory(ring: ChannelRing, items: AepEnvelope[], ceiling: number): number {
+  let added = 0
+  for (const e of items) {
+    if (typeof e.seq !== 'number' || e.seq > ceiling) continue
+    if (ring.consumed.has(e.seq)) continue
+    ring.items.push(e)
+    ring.consumed.add(e.seq)
+    added += 1
+  }
+  if (added > 0) {
+    ring.items.sort((a, b) => a.seq - b.seq)
+    if (ring.items.length > RING_CAP) ring.items.splice(0, ring.items.length - RING_CAP)
+  }
+  return added
+}
+
+export const useEventsStore = defineStore('workshop.events', {
+  state: () => ({
+    rings: {} as Record<string, ChannelRing>,
+    filters: {} as Record<string, EventFilter>,
+    /** 时间线聚焦的 agent(只看该 agent 的流;null = 全部) */
+    focusAgents: {} as Record<string, string | null>,
+    /** lane 历史已回填的 agent(channelId → agentId 集合;防视图切换重复拉取) */
+    laneLoaded: {} as Record<string, Set<string>>,
+  }),
+  getters: {
+    ring(state) {
+      return (channelId: string): ChannelRing =>
+        state.rings[channelId] ?? EMPTY_RING()
+    },
+    /** 应用过滤 + agent 聚焦后的时间线(虚拟滚动/自动吸底消费;per-channel 记忆化) */
+    timeline(state) {
+      return (channelId: string): AepEnvelope[] => {
+        const ring = state.rings[channelId]
+        if (!ring) return []
+        const filter = state.filters[channelId] ?? 'all'
+        const focus = state.focusAgents[channelId] ?? null
+        const memoKey = `${filter}:${focus ?? ''}:${ring.lastSeq}:${ring.items.length}`
+        const hit = timelineCache.get(channelId)
+        if (hit && hit.key === memoKey) return hit.result
+        const result = computeTimeline(ring.items, filter, FILTER_TYPES[filter], focus)
+        timelineCache.set(channelId, { key: memoKey, result })
+        return result
+      }
+    },
+    lastSeq(state) {
+      return (channelId: string): number => state.rings[channelId]?.lastSeq ?? 0
+    },
+  },
+  actions: {
+    /** 消费一帧 AEP(连接回调入口):快照重建 ring,增量追加并推进游标 */
+    ingest(e: AepEnvelope): void {
+      if (!e.channelId) return
+      const ring = this.rings[e.channelId] ?? EMPTY_RING()
+      if (e.type === 'channel.snapshot') {
+        // 全量对齐:清空 ring,游标对齐快照 seq
+        this.rings[e.channelId] = { lastSeq: e.seq, items: [], consumed: new Set([e.seq]) }
+        return
+      }
+      if (typeof e.seq === 'number' && e.seq > ring.lastSeq) {
+        ring.consumed.add(e.seq)
+        // delta 聚合:同 agent(+同任务)连续增量合并进前一条;跨任务增量绝不粘连
+        if (e.type === 'agent.delta') {
+          const last = ring.items[ring.items.length - 1]
+          const sameOrigin = last
+            && last.type === 'agent.delta'
+            && last.agentId === e.agentId
+            && (last.taskId ?? null) === (e.taskId ?? null)
+          if (sameOrigin && last) {
+            const prev = (last.payload as { delta: string }).delta
+            ;(last.payload as { delta: string }).delta = prev + (e.payload as { delta: string }).delta
+            ring.lastSeq = e.seq
+            this.rings[e.channelId] = ring
+            return
+          }
+        }
+        ring.items.push(e)
+        if (ring.items.length > RING_CAP) ring.items.splice(0, ring.items.length - RING_CAP)
+        ring.lastSeq = e.seq
+        // 防泄漏:超限后从现存 items 重建(合并掉的旧 seq 允许短暂失忆——远早于 ring 窗口)
+        if (ring.consumed.size > 20_000) ring.consumed = new Set(ring.items.map(i => i.seq))
+        this.rings[e.channelId] = ring
+      }
+    },
+    setFilter(channelId: string, filter: EventFilter): void {
+      this.filters[channelId] = filter
+    },
+    /**
+     * 持久化历史拉取(server 驱动):刷新后从 DB 拉最近事件并填充 ring。
+     * 与 WS 增量无缝衔接:仅接受 seq ≤ 当前游标的帧;已消费过的 seq
+     * (含被 delta 合并吃掉的中间 seq,经 consumed 集合识别)绝不重复插入。
+     * 剔除 agent.delta 过程帧:落定 agent.message 携带全文,历史窗口
+     * 不被单 agent 的打字机帧淹没(其他 agent 的消息才能进窗口)。
+     */
+    async loadHistory(channelId: string, limit = 200): Promise<void> {
+      if (typeof window === 'undefined') return
+      const ring = this.rings[channelId] ?? EMPTY_RING()
+      try {
+        const res = await $fetch<EventsHistoryRes>(
+          `/api/workshop/channels/${channelId}/events`,
+          { params: { limit, excludeTypes: HISTORY_EXCLUDE_TYPES.join(',') }, headers: { authorization: `Bearer ${useUserStore().token}` } },
+        )
+        if (res.code !== 0 || !res.data?.items?.length) return
+        mergeHistory(ring, res.data.items, ring.lastSeq)
+        this.rings[channelId] = ring
+      }
+      catch { /* 历史拉取失败不阻塞实时流 */ }
+    },
+    /**
+     * 向上翻页加载更早历史(beforeSeq 游标;时间线"加载更早"按钮驱动)。
+     * 仅接受 seq < 当前 ring 最小 seq 的帧,插入头部;consumed 去重防御。
+     * 返回 false 表示已无更早历史(按钮隐藏)。
+     */
+    async loadEarlier(channelId: string, limit = 200): Promise<boolean> {
+      if (typeof window === 'undefined') return false
+      const ring = this.rings[channelId]
+      if (!ring) return false
+      const minSeq = ring.items.length > 0 ? (ring.items[0]?.seq ?? 0) : ring.lastSeq
+      if (minSeq <= 1) return false
+      try {
+        const res = await $fetch<EventsHistoryRes>(
+          `/api/workshop/channels/${channelId}/events`,
+          { params: { limit, beforeSeq: Math.max(1, minSeq - 1), excludeTypes: HISTORY_EXCLUDE_TYPES.join(',') }, headers: { authorization: `Bearer ${useUserStore().token}` } },
+        )
+        if (res.code !== 0 || !res.data?.items?.length) return false
+        const added = mergeHistory(ring, res.data.items, ring.lastSeq)
+        if (added > 0) this.rings[channelId] = ring
+        // 返回是否可能还有更早(拉满一页视为有;由下次点击自然探底)
+        return added > 0 && res.data.items.length >= limit
+      }
+      catch {
+        return false
+      }
+    },
+    /**
+     * lane 历史按需回填:按 agent 维度拉取该成员的全部事件(剔除 delta 过程帧),
+     * 合并进 channel ring —— lanes 谓词按 agentId 过滤,时间线同样受益。
+     * laneLoaded 守卫保证每订阅生命周期内每 agent 只回填一次(视图切换不重复拉取;
+     * clear 随 ring 一并重置);拉取失败移除守卫,下次挂载可重试。
+     * 快照竞态防御:ring 未建立(lastSeq=0,channel.snapshot 未到)时先有界等待 ——
+     * 过早合并会被快照全量重建整环覆盖,等价于白拉。
+     */
+    async loadLaneHistory(channelId: string, agentId: string, limit = 200): Promise<void> {
+      if (typeof window === 'undefined') return
+      if (this.laneLoaded[channelId]?.has(agentId)) return
+      ;(this.laneLoaded[channelId] ??= new Set()).add(agentId)
+      for (let i = 0; i < 20 && this.lastSeq(channelId) === 0; i++) {
+        await new Promise(resolve => setTimeout(resolve, 150))
+      }
+      if (this.lastSeq(channelId) === 0) {
+        // 快照迟迟未到(WS 未连/权限拒绝):放弃本次,守卫移除待重试
+        this.laneLoaded[channelId]?.delete(agentId)
+        return
+      }
+      const ring = this.rings[channelId]!
+      try {
+        const res = await $fetch<EventsHistoryRes>(
+          `/api/workshop/channels/${channelId}/events`,
+          { params: { limit, agentId, excludeTypes: HISTORY_EXCLUDE_TYPES.join(',') }, headers: { authorization: `Bearer ${useUserStore().token}` } },
+        )
+        if (res.code === 0 && res.data?.items?.length) {
+          mergeHistory(ring, res.data.items, ring.lastSeq)
+          this.rings[channelId] = ring
+        }
+      }
+      catch {
+        this.laneLoaded[channelId]?.delete(agentId)
+      }
+    },
+    /**
+     * lane 向上翻页:该 agent 在 ring 内的最小 seq 为游标,拉更早一段。
+     * 返回 false 表示该 agent 已无更早历史(lane"加载更早"按钮隐藏)。
+     */
+    async loadLaneEarlier(channelId: string, agentId: string, limit = 200): Promise<boolean> {
+      if (typeof window === 'undefined') return false
+      const ring = this.rings[channelId]
+      if (!ring) return false
+      let minSeq = 0
+      for (const e of ring.items) {
+        if (e.agentId === agentId) {
+          minSeq = e.seq
+          break
+        }
+      }
+      if (minSeq <= 1) return false
+      try {
+        const res = await $fetch<EventsHistoryRes>(
+          `/api/workshop/channels/${channelId}/events`,
+          { params: { limit, agentId, beforeSeq: minSeq - 1, excludeTypes: HISTORY_EXCLUDE_TYPES.join(',') }, headers: { authorization: `Bearer ${useUserStore().token}` } },
+        )
+        if (res.code !== 0 || !res.data?.items?.length) return false
+        const added = mergeHistory(ring, res.data.items, ring.lastSeq)
+        if (added > 0) this.rings[channelId] = ring
+        return added > 0 && res.data.items.length >= limit
+      }
+      catch {
+        return false
+      }
+    },
+
+    setFocusAgent(channelId: string, agentId: string | null): void {
+      this.focusAgents[channelId] = agentId
+    },
+    clear(channelId: string): void {
+      Reflect.deleteProperty(this.rings, channelId)
+      Reflect.deleteProperty(this.laneLoaded, channelId)
+    },
+  },
+})