agentworkshop 0.7.44 → 0.7.47

package/app/composables/workshop/useTaskBoardMenu.ts

@@ -0,0 +1,60 @@
+/**
+ * useTaskBoardMenu —— 状态胶囊菜单(动作 + 详情):fixed 定位并按视口收敛。
+ *
+ * 动作清单按当前任务态派生(cancel 收未终结态 / retry 收 FAILED / detail 恒有),
+ * 与拖拽落列共用同一个动作面 applyMove —— 两条路径的状态语义必须一致。
+ */
+import { computed, ref } from 'vue'
+import type { TaskView } from '@/app/stores/workshop/entities'
+
+export interface TaskBoardMenuAction {
+  key: 'cancel' | 'retry' | 'detail'
+  label: string
+  danger?: boolean
+}
+
+export function useTaskBoardMenu(options: {
+  applyMove: (taskId: string, action: 'cancel' | 'retry') => Promise<void>
+  openTask: (taskId: string) => void
+}) {
+  const { t } = useI18n()
+
+  const { applyMove, openTask } = options
+
+  /** 状态胶囊菜单(动作 + 详情);fixed 定位并按视口收敛 */
+  const menu = ref<{ task: TaskView, x: number, y: number } | null>(null)
+  const openMenu = (ev: MouseEvent, task: TaskView) => {
+    const x = Math.min(ev.clientX, Math.max(window.innerWidth - 156, 8))
+    const y = Math.min(ev.clientY, Math.max(window.innerHeight - 160, 8))
+    menu.value = { task, x, y }
+  }
+  const closeMenu = () => {
+    menu.value = null
+  }
+  const menuActions = computed<TaskBoardMenuAction[]>(() => {
+    const task = menu.value?.task
+    if (!task) return []
+    const acts: TaskBoardMenuAction[] = []
+    if (['SUBMITTED', 'ASSIGNED', 'WORKING', 'WAITING', 'FAILED'].includes(task.state)) {
+      acts.push({ key: 'cancel', label: t('taskBoardView.k1bs0t9b016'), danger: true })
+    }
+    if (task.state === 'FAILED') {
+      acts.push({ key: 'retry', label: t('taskBoardView.k1lclwk6017') })
+    }
+    acts.push({ key: 'detail', label: t('taskBoardView.k1dx9ysj018') })
+    return acts
+  })
+  const onMenuAction = async (key: 'cancel' | 'retry' | 'detail') => {
+    const t = menu.value?.task
+    closeMenu()
+    if (!t) return
+    if (key === 'detail') {
+      openTask(t.id)
+    }
+    else {
+      await applyMove(t.id, key)
+    }
+  }
+
+  return { menu, openMenu, closeMenu, menuActions, onMenuAction }
+}

package/app/composables/workshop/useTaskBoardTasks.ts

@@ -0,0 +1,74 @@
+/**
+ * useTaskBoardTasks —— 任务板的实体读取与动作面(每个 TaskBoardView 实例一份,非模块级单例):
+ *  - tasks/synced 取自 entities store(channelId 作用域);快照未到达时 synced=false,
+ *    空态据此显示「同步中」而不是误判「没有任务」;
+ *  - optimistic:taskId → 预期 state 的乐观覆盖层(REST 进行中;WS 事件确认后由实体覆盖);
+ *  - applyMove:cancel/retry 的唯一出口(拖拽落列与状态胶囊菜单共用同一动作面):
+ *    先乐观预移,REST 失败回滚并弹错,完成后短暂清理乐观层交给 WS/实体收敛。
+ */
+import { computed, ref, type Ref } from 'vue'
+import { message } from 'ant-design-vue'
+import { apiErrorMessage } from '@/app/utils/api-error'
+import { useEntitiesStore, type TaskView } from '@/app/stores/workshop/entities'
+import { useWorkshopApi } from '@/app/composables/workshop/useWorkshopApi'
+
+export function useTaskBoardTasks(channelId: Ref<string>) {
+  const { t } = useI18n()
+
+  const entities = useEntitiesStore()
+  const api = useWorkshopApi()
+
+  const tasks = computed(() => entities.tasks[channelId.value] ?? [])
+  /** 实体快照是否已到达(未到时空态显示同步中,不误判"没有任务") */
+  const synced = computed(() => entities.channels[channelId.value] !== undefined
+    || entities.tasks[channelId.value] !== undefined)
+
+  /** 乐观覆盖:taskId → 预期 state(REST 进行中;WS 确认后由实体覆盖) */
+  const optimistic = ref(new Map<string, string>())
+  const mergedTasks = computed<TaskView[]>(() =>
+    tasks.value.map(t => (optimistic.value.has(t.id) ? { ...t, state: optimistic.value.get(t.id)! } : t)),
+  )
+
+  const taskById = (id: string): TaskView | undefined => mergedTasks.value.find(t => t.id === id)
+
+  // ===== 动作面(拖拽与胶囊菜单共用) =====
+  const acting = ref(new Set<string>())
+  const applyMove = async (taskId: string, action: 'cancel' | 'retry'): Promise<void> => {
+    if (acting.value.has(taskId)) return
+    const task = taskById(taskId)
+    if (!task) return
+    acting.value.add(taskId)
+    const prev = task.state
+    // 乐观预移:cancel → CANCELED;retry → ASSIGNED
+    const next = action === 'cancel' ? 'CANCELED' : 'ASSIGNED'
+    const opt = new Map(optimistic.value)
+    opt.set(taskId, next)
+    optimistic.value = opt
+    try {
+      await (action === 'cancel' ? api.cancelTask(taskId) : api.retryTask(taskId))
+      // cancel 可能级联多个后代;命令响应只有 root,所以立即刷新整条 Channel 的事实源，
+      // 再等待 WS 事件收敛，避免 UI 留下仍显示 WORKING 的孤儿 child。
+      entities.refreshTasks(channelId.value)
+      message.success(action === 'cancel' ? t('taskBoardView.k189y4q013') : t('taskBoardView.kv1l1j3014'))
+    }
+    catch (e) {
+      // 回滚乐观预移,弹错(WS 事件为准)
+      const revert = new Map(optimistic.value)
+      revert.set(taskId, prev)
+      optimistic.value = revert
+      const err = e as { data?: { message?: string }, message?: string }
+      message.error(apiErrorMessage(err, t('taskBoardView.k1e7zwuc015')))
+    }
+    finally {
+      acting.value.delete(taskId)
+      // REST 完成后短暂清理乐观层,交给 WS/实体收敛
+      setTimeout(() => {
+        const clean = new Map(optimistic.value)
+        clean.delete(taskId)
+        optimistic.value = clean
+      }, 4000)
+    }
+  }
+
+  return { synced, mergedTasks, taskById, applyMove }
+}

package/app/composables/workshop/useTerminalRenderer.ts

@@ -0,0 +1,308 @@
+/**
+ * useTerminalRenderer —— 结构化 RPC 帧 → ANSI TUI 渲染层(自 OmpTerminalPanel 结构拆分)。
+ *
+ * 只做"帧/文本 → xterm 写入":流式增量缓冲、底部输入行重绘、视图重置与清屏。
+ * xterm 实例不在此创建/销毁,经 getTerm 访问器借用;已渲染 seq 游标与命令历史
+ * 归 session 组合式,经访问器/回调协作 —— 拆分只搬运代码,渲染时序逐字不变。
+ */
+import type { Ref } from 'vue'
+import type { Terminal } from '@xterm/xterm'
+import { nowLocalIso } from '~/composables/workshop/useLocalTime'
+import type {
+  TermFrame,
+  TerminalHitlDialog,
+} from '#shared/terminal-protocol'
+
+/** 渲染层协作口(实例/游标/历史由 session 组合式持有) */
+export interface TerminalRendererDeps {
+  /** xterm 实例访问器(未装配或已销毁时为 null) */
+  getTerm: () => Terminal | null
+  /** 待应答 HITL 对话框(extension_ui_request cancel 分支置空) */
+  hitl: Ref<TerminalHitlDialog | null>
+  /** 已渲染 seq(重连全量重放去重)访问器 */
+  getLastSeq: () => number
+  setLastSeq: (seq: number) => void
+  /** 清空命令历史(历史属于会话,随视图一并重置) */
+  clearHistory: () => void
+}
+
+export function useTerminalRenderer(deps: TerminalRendererDeps) {
+  const { getTerm, hitl, getLastSeq, setLastSeq, clearHistory } = deps
+  const { t } = useI18n()
+
+  // ANSI 快捷片段
+  const C = {
+    reset: '\x1b[0m',
+    dim: '\x1b[2m',
+    bold: '\x1b[1m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+    dimItalicMagenta: '\x1b[2;3;35m',
+  }
+
+  /** 流式行未收尾标志:光标停在流式行中间 —— 下一个块/回合收尾前先补换行 */
+  let streamLineOpen = false
+
+  /** 最近一次人类输入(follow_up 路径 omp 回显 user 消息 → 去重) */
+  let lastHumanInput = ''
+  /** 当前回合 assistant 流式是否已输出过换行收尾标记 */
+  let assistantStreamActive = false
+  /** 流式增量缓冲(text/thinking delta 按批 flush,防与输入行交错) */
+  const streamBuf: string[] = []
+  /**
+   * 正文差额账本:contentIndex → 已渲染长度。部分 provider 的 text 块不走
+   * text_delta(只有换行),全文在 text_end.content 落定 —— 差额补发防止终端缺正文。
+   */
+  const textSent = new Map<number, number>()
+
+  /** 底部输入行已键入内容(按键/历史处理在 session 组合式,此处共用读写) */
+  let inputLine = ''
+
+  /**
+   * 冲刷流式增量:直接续写在光标后。
+   * 不补换行、不清行、不碰底部输入行 —— 流式批次之间是同一段正文,
+   * 旧实现按"块语义"逐批强制换行 + 重绘 prompt,导致实时消费出现逐批断行
+   * (历史重放一次冲刷故正常)。
+   */
+  function flushStream(): void {
+    if (streamBuf.length === 0) return
+    const text = streamBuf.join('')
+    streamBuf.length = 0
+    getTerm()?.write(text)
+    if (!/\r?\n$/.test(text)) streamLineOpen = true
+  }
+
+  /** 收尾流式行:仅在光标停在流式行中时补一个换行 */
+  function closeStreamLine(): void {
+    if (!streamLineOpen) return
+    streamLineOpen = false
+    getTerm()?.write('\r\n')
+  }
+
+  /** 写入完整块(独立行):冲刷流式增量并收尾流式行 → 清输入行 → 写块 → 重绘输入行 */
+  function writeBlock(text: string): void {
+    const term = getTerm()
+    if (!term) return
+    flushStream()
+    closeStreamLine()
+    term.write('\r\x1b[K')
+    term.write(text.endsWith('\r\n') || text.endsWith('\n') ? text : `${text}\r\n`)
+    renderInputRow()
+  }
+
+  /** 重绘底部输入行(prompt + 已键入内容);流式行未收尾时跳过(回合收尾后统一补绘) */
+  function renderInputRow(): void {
+    const term = getTerm()
+    if (!term) return
+    if (streamLineOpen || streamBuf.length > 0) return
+    term.write(`\r\x1b[K${C.dim}❯${C.reset} ${C.cyan}${inputLine}${C.reset}`)
+  }
+
+  /**
+   * 清空视图(切换目标 / 重开抽屉):丢弃上一会话的全部渲染状态与 xterm 缓冲。
+   * 不清空会把前一个 Agent 的历史输出叠进本 Agent 的终端,重开抽屉还会整环
+   * 重放造成重复 —— 每个 Agent 的终端必须只渲染自己的信息。
+   */
+  function resetView(): void {
+    streamBuf.length = 0
+    streamLineOpen = false
+    assistantStreamActive = false
+    textSent.clear()
+    lastHumanInput = ''
+    inputLine = ''
+    // 命令历史随视图一并清空:历史属于会话,跨 Agent/重开共享会串上下文
+    clearHistory()
+    getTerm()?.reset()
+    renderInputRow()
+  }
+
+  const ts = (): string => {
+    const d = new Date()
+    return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}:${String(d.getSeconds()).padStart(2, '0')}`
+  }
+
+  /** 单行/短文本裁剪(空白折叠) */
+  function oneLine(text: string, max = 160): string {
+    const flat = text.replace(/\s+/g, ' ').trim()
+    return flat.length > max ? `${flat.slice(0, max)}…` : flat
+  }
+
+  // ===== 帧渲染器:结构化 RPC 帧 → ANSI TUI =====
+
+  function renderFrame(f: TermFrame): void {
+    if (f.seq <= getLastSeq()) return
+    setLastSeq(f.seq)
+    const frame = f.frame
+    const type = frame.type as string
+
+    switch (type) {
+      case '__terminal_notice': {
+        const level = String(frame.level ?? 'info')
+        const color = level === 'error' ? C.red : level === 'warning' ? C.yellow : C.dim
+        writeBlock(`${C.dim}[${ts()}]${C.reset} ${color}⚡ ${String(frame.message ?? '')}${C.reset}`)
+        return
+      }
+      case '__human_input': {
+        lastHumanInput = String(frame.text ?? '')
+        writeBlock(`${C.bold}${C.cyan}❯ ${lastHumanInput}${C.reset}`)
+        return
+      }
+      case 'ready':
+        writeBlock(`${C.green}● omp ready${C.reset} ${C.dim}protocol v${String(frame.protocolVersion ?? '?')} · mode rpc-ui${C.reset}`)
+        return
+      case 'agent_start':
+        assistantStreamActive = false
+        textSent.clear()
+        writeBlock(`${C.dim}── agent turn started ──${C.reset}`)
+        return
+      case 'agent_end':
+        writeBlock(`${C.dim}── agent turn ended(${String(frame.messageCount ?? '?')} messages)──${C.reset}`)
+        return
+      case 'message_start': {
+        const role = String(frame.role ?? '')
+        if (role === 'user') {
+          const text = String(frame.text ?? '')
+          // follow_up 的 user 回显与人类输入同文 → 已渲染,跳过;平台注入的任务 prompt 正常回显
+          if (text === lastHumanInput) return
+          writeBlock(`${C.bold}${C.cyan}❯ ${text.replace(/\n/g, '\r\n')}${C.reset}`)
+        }
+        return
+      }
+      case 'message_update': {
+        const ev = frame.assistantMessageEvent as { type?: string, delta?: string, content?: string, contentIndex?: number } | undefined
+        if (!ev) return
+        // 流式增量先入缓冲,按批(flushStream)统一走 writeBlock:
+        // 直接 term.write 会落在底部输入行上,与输入行互相覆盖
+        if (ev.type === 'text_delta' && ev.delta) {
+          assistantStreamActive = true
+          const ci = typeof ev.contentIndex === 'number' ? ev.contentIndex : 0
+          textSent.set(ci, (textSent.get(ci) ?? 0) + ev.delta.length)
+          streamBuf.push(ev.delta.replace(/\n/g, '\r\n'))
+        }
+        else if (ev.type === 'text_end' && typeof ev.content === 'string' && ev.content.length > 0) {
+          // 落定差额兜底:provider 未流式 text 块时全文在 text_end,补发未渲染部分
+          const ci = typeof ev.contentIndex === 'number' ? ev.contentIndex : 0
+          const sent = textSent.get(ci) ?? 0
+          if (ev.content.length > sent) {
+            assistantStreamActive = true
+            textSent.set(ci, ev.content.length)
+            streamBuf.push(ev.content.slice(sent).replace(/\n/g, '\r\n'))
+          }
+        }
+        else if (ev.type === 'thinking_delta' && ev.delta) {
+          assistantStreamActive = true
+          streamBuf.push(`${C.dimItalicMagenta}${ev.delta.replace(/\n/g, '\r\n')}${C.reset}`)
+        }
+        return
+      }
+      case 'message_end': {
+        const role = String(frame.role ?? '')
+        if (role === 'assistant' && assistantStreamActive) {
+          // 回合收尾:冲刷剩余增量 → 流式行补换行 → 恢复底部输入行
+          assistantStreamActive = false
+          flushStream()
+          closeStreamLine()
+          renderInputRow()
+        }
+        return
+      }
+      case 'tool_execution_start':
+        writeBlock(`  ${C.yellow}⚙ ${String(frame.toolName ?? 'tool')}${C.reset}${C.dim}(${oneLine(String(frame.args ?? ''), 120)})${C.reset}`)
+        return
+      case 'tool_execution_update':
+        writeBlock(`  ${C.dim}↳ … ${oneLine(String(frame.update ?? ''), 100)}${C.reset}`)
+        return
+      case 'tool_execution_end': {
+        const err = frame.isError === true
+        const mark = err ? `${C.red}✗${C.reset}` : `${C.green}✓${C.reset}`
+        const preview = oneLine(String(frame.result ?? ''), 180)
+        writeBlock(`  ${mark} ${C.dim}${preview}${C.reset}`)
+        return
+      }
+      case 'host_tool_call':
+        writeBlock(`  ${C.magenta}⇄ host:${String(frame.toolName ?? '?')}${C.reset}${C.dim}(${oneLine(String(frame.args ?? ''), 100)})${C.reset}`)
+        return
+      case 'extension_ui_request': {
+        const method = String(frame.method ?? '')
+        if (method === 'cancel') {
+          writeBlock(t('ompTerminalPanel.k14jk3nu001', { p0: C.dim, p1: String(frame.targetId ?? ''), p2: C.reset }))
+          // omp 主动撤销(回合中止等)→ 关闭交互面板
+          if (hitl.value && hitl.value.id === String(frame.targetId ?? '')) hitl.value = null
+          return
+        }
+        if (method === 'notify') {
+          writeBlock(`  ${C.blue}ℹ ${String(frame.message ?? '')}${C.reset}`)
+          return
+        }
+        if (method === 'select' || method === 'confirm' || method === 'input' || method === 'editor') {
+          const title = String(frame.title ?? '')
+          writeBlock(`${C.bold}${C.magenta}⚠ HITL · ${method}: ${title}${C.reset}`)
+          if (Array.isArray(frame.options)) {
+            for (const opt of frame.options) {
+              writeBlock(`  ${C.magenta}○${C.reset} ${String(opt)}`)
+            }
+          }
+          // 弹出交互面板(实时帧驱动;term.init 的 hitl 仅覆盖重连时已在等待的对话框)
+          hitl.value = {
+            id: String(frame.id ?? ''),
+            method,
+            title,
+            options: Array.isArray(frame.options) ? frame.options.map(String) : undefined,
+            message: typeof frame.message === 'string' ? frame.message : undefined,
+            placeholder: typeof frame.placeholder === 'string' ? frame.placeholder : undefined,
+            prefill: typeof frame.prefill === 'string' ? frame.prefill : undefined,
+            at: nowLocalIso(),
+          }
+        }
+        // 其余 UI 方法(setStatus/setWidget/…)静默
+        return
+      }
+      case 'command_output':
+        writeBlock(`${C.dim}${String(frame.text ?? '').replace(/\n/g, '\r\n')}${C.reset}`)
+        return
+      case 'response': {
+        const command = String(frame.command ?? '')
+        // 只回显人工控制命令的受理结果,其余(get_state 等)为噪音
+        if (command === 'steer' || command === 'follow_up' || command === 'abort' || command === 'prompt') {
+          const ok = frame.success !== false
+          writeBlock(`  ${C.dim}· ${command} ${ok ? 'accepted' : `failed: ${String(frame.error ?? '')}`}${C.reset}`)
+        }
+        return
+      }
+      default:
+        // available_commands_update / session_info_update / config_update / 未知帧:静默
+        return
+    }
+  }
+
+  /** 清屏(仅清 xterm 缓冲与流式残行;seq 游标不动,重放去重仍有效) */
+  function doClear(): void {
+    streamBuf.length = 0
+    streamLineOpen = false
+    getTerm()?.clear()
+    renderInputRow()
+  }
+
+  return {
+    C,
+    flushStream,
+    closeStreamLine,
+    writeBlock,
+    renderInputRow,
+    resetView,
+    renderFrame,
+    doClear,
+    oneLine,
+    /** 底部输入行读写口(按键处理/粘贴在 session 组合式) */
+    get inputLine(): string {
+      return inputLine
+    },
+    set inputLine(v: string) {
+      inputLine = v
+    },
+  }
+}

package/app/composables/workshop/useTranscriptEnterStage.ts

@@ -0,0 +1,48 @@
+/**
+ * 时间线新块进场编排(open-tag motion charter 移植)。
+ *
+ * 只有实时新到的尾部块做进场动画(60ms stagger,600ms burst 窗口,上限 8 条);
+ * 整体重建(过滤切换/聚焦/历史回填——一次出现大量新 id)与组件首载直接显示,
+ * 不动画不延迟。映射:blockId → 进场延迟 ms;-1 = 不动画。
+ *
+ * 从 TranscriptTimeline 拆出时逻辑逐行未动:唯一的改动是私有类型 `Stage`
+ * 更名并导出为 `TranscriptEnterStage`(子组件要向 workshop-event-block 传同一结构)。
+ */
+import { ref, watch } from 'vue'
+import type { Ref } from 'vue'
+import type { EventBlock } from '@/app/composables/workshop/useEventBlocks'
+
+export interface TranscriptEnterStage {
+  enter: boolean
+  delay: number
+}
+
+export function useTranscriptEnterStage(blocks: Ref<EventBlock[]>) {
+  const staged = ref(new Map<string, TranscriptEnterStage>())
+  let burstAt = 0
+  let burstN = 0
+  const mountedAt = Date.now()
+  watch(blocks, (list, prev) => {
+    const prevIds = new Set((prev ?? []).map(b => b.id))
+    const fresh = list.filter(b => !prevIds.has(b.id))
+    const map = new Map<string, TranscriptEnterStage>()
+    const wholesale = fresh.length === 0
+      || fresh.length > Math.max(8, Math.ceil(list.length * 0.4))
+      || Date.now() - mountedAt < 1500
+    if (!wholesale) {
+      const now = Date.now()
+      if (now - burstAt > 600) {
+        burstAt = now
+        burstN = 0
+      }
+    }
+    for (const b of list) {
+      const isFresh = !prevIds.has(b.id)
+      const delay = isFresh && !wholesale ? Math.min(burstN++, 7) * 60 : -1
+      map.set(b.id, { enter: delay >= 0, delay: Math.max(0, delay) })
+    }
+    staged.value = map
+  }, { immediate: true })
+
+  return { staged }
+}

package/app/composables/workshop/useTranscriptHistory.ts

@@ -0,0 +1,52 @@
+/**
+ * 时间线「加载更早」翻页(beforeSeq 游标;顶部按钮驱动)。
+ *
+ * 头部插入必须还原视口:历史帧插到列首会把内容整体下推,若不做补偿,
+ * 浏览器保持 scrollTop 不变 → 视口里的块"跳"走。这里记住插入前的
+ * (scrollTop, scrollHeight),nextTick 后按 scrollHeight 增量还原 scrollTop,
+ * 视口锚定在同一批块上(不吸底跳变)。拉取失败保持按钮可重试,不打断时间线。
+ *
+ * 从 TranscriptTimeline 拆出时逻辑逐行未动;滚动容器由容器组件经参数传入
+ * (锚定用,未挂载时为 null)。
+ */
+import { computed, nextTick, ref, toValue } from 'vue'
+import type { MaybeRefOrGetter, Ref } from 'vue'
+import { useEventsStore } from '@/app/stores/workshop/events'
+
+export function useTranscriptHistory(
+  channelId: MaybeRefOrGetter<string>,
+  /** 滚动容器(视口锚定用) */
+  scroller: Ref<HTMLElement | null>,
+) {
+  const events = useEventsStore()
+
+  // ===== 向上翻页历史 =====
+  const loadingEarlier = ref(false)
+  const earlierExhausted = ref(false)
+  /** 已加载事件数 vs 持久化总量 → 是否可能还有更早(粗判,点击时由 loadEarlier 探底) */
+  const loadedCount = computed(() => events.ring(toValue(channelId)).items.length)
+  const maybeMore = computed(() => !earlierExhausted.value && loadedCount.value > 0)
+  const loadEarlier = async (): Promise<void> => {
+    if (loadingEarlier.value || earlierExhausted.value) return
+    loadingEarlier.value = true
+    // 记住滚动位置:头部插入后保持视口锚定(不吸底跳变)
+    const el = scroller.value
+    const anchor = el ? { top: el.scrollTop, height: el.scrollHeight } : null
+    try {
+      const hasMore = await events.loadEarlier(toValue(channelId))
+      if (!hasMore) earlierExhausted.value = true
+      if (el && anchor) {
+        await nextTick()
+        el.scrollTop = el.scrollHeight - anchor.height + anchor.top
+      }
+    }
+    catch {
+      /* 历史拉取失败:保持按钮可重试,不打断时间线 */
+    }
+    finally {
+      loadingEarlier.value = false
+    }
+  }
+
+  return { loadingEarlier, earlierExhausted, loadedCount, maybeMore, loadEarlier }
+}

package/app/composables/workshop/useTranscriptScroll.ts

@@ -0,0 +1,113 @@
+/**
+ * 时间线滚动容器编排:吸底跟随 + 回底动画 + 内容高度增长补滚。
+ *
+ * 三条补滚路径(缺一条都会让长输出"卡"在中途):
+ *  ① 块数变化(新块上屏)
+ *  ② 频道 lastSeq 增长(合并帧不推块数时)
+ *  ③ 同一流块 delta 打字机让块变高(块数与 seq 都不变 → ResizeObserver 兜底)
+ *
+ * `stickBottom` 由滚动位置决定(离底 120px 内算贴底):用户离底后新内容不再强制跟随,
+ * 由「跳回最新」按钮显式回底。ResizeObserver 以结构化类型声明:绕开 vue-tsc 双 lib.dom
+ * 下 Element 类型不兼容问题。
+ *
+ * 从 TranscriptTimeline 拆出时逻辑逐行未动;`scroller` / `columnEl` 仍是模板 ref
+ * (容器模板用 ref="scroller" / ref="columnEl" 绑定),副作用注册与清理成对留在本文件内。
+ */
+import { nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+
+/** 结构化滚动容器(绕开 vue-tsc 双 lib.dom 的 Element 类型不兼容) */
+type ScrollBox = { scrollTop: number, scrollHeight: number, clientHeight: number }
+
+/** 补滚触发源:两个都是 getter(watch 按值变化触发) */
+export interface TranscriptScrollSources {
+  /** 已呈现块数(变化 → 补一次滚底) */
+  blockCount: () => number
+  /** 频道最新 seq(增长 → 补一次滚底) */
+  lastSeq: () => number
+}
+
+export function useTranscriptScroll(sources: TranscriptScrollSources) {
+  const scroller = ref<HTMLElement | null>(null)
+  const stickBottom = ref(true)
+  const scrollingDown = ref(false)
+  /** 内容列(高度增长的观测目标;模板 ref) */
+  const columnEl = ref<HTMLElement | null>(null)
+  let contentObserver: { disconnect(): void } | null = null
+
+  const onScroll = (): void => {
+    const el = scroller.value
+    if (!el) return
+    stickBottom.value = el.scrollHeight - el.scrollTop - el.clientHeight < 120
+  }
+
+  // ===== 回底动画(open-tag jump-bottom:800ms ease-out,动画期抑制按钮闪烁) =====
+  const animateScroll = (el: ScrollBox, ms: number): Promise<void> =>
+    new Promise((resolve) => {
+      if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+        el.scrollTop = el.scrollHeight
+        resolve()
+        return
+      }
+      const from = el.scrollTop
+      const delta = el.scrollHeight - el.clientHeight - from
+      const t0 = performance.now()
+      const step = (t: number): void => {
+        const k = Math.min(1, (t - t0) / ms)
+        const eased = 1 - (1 - k) ** 3 // ease-out cubic
+        el.scrollTop = from + delta * eased
+        if (k < 1) requestAnimationFrame(step)
+        else resolve()
+      }
+      requestAnimationFrame(step)
+    })
+
+  /** 跳回最新:滚底并恢复吸底(用户离开底部后新内容不再自动跟随) */
+  const jumpToLatest = async (): Promise<void> => {
+    stickBottom.value = true
+    const el = scroller.value
+    if (!el) return
+    scrollingDown.value = true
+    try {
+      await animateScroll(el, 800)
+    }
+    finally {
+      scrollingDown.value = false
+    }
+  }
+
+  /** 吸底:新块出现 / seq 增长 / 块内容尺寸变化(可能高增)后滚到底 */
+  const scrollToBottom = async (): Promise<void> => {
+    if (!stickBottom.value) return
+    await nextTick()
+    const el = scroller.value
+    if (el) el.scrollTop = el.scrollHeight
+  }
+  watch(sources.blockCount, () => {
+    void scrollToBottom()
+  })
+  watch(sources.lastSeq, () => {
+    void scrollToBottom()
+  })
+
+  // 内容高度增长吸底:同一流块 delta 打字机让块变高(块数与 seq 不变或合并帧不推 seq),
+  // ResizeObserver 观测内容列高度变化补一次滚底 —— 长输出不再"卡"在中途。
+  // (观察器以结构化类型声明:绕开 vue-tsc 双 lib.dom 下 Element 类型不兼容问题)
+  onMounted(() => {
+    const el = scroller.value
+    const column = columnEl.value
+    if (!el || !column || typeof ResizeObserver === 'undefined') return
+    const Observer = ResizeObserver as unknown as
+      new (cb: () => void) => { observe(target: unknown): void, disconnect(): void }
+    const observer = new Observer(() => {
+      if (stickBottom.value) el.scrollTop = el.scrollHeight
+    })
+    observer.observe(column)
+    contentObserver = observer
+  })
+  onBeforeUnmount(() => {
+    contentObserver?.disconnect()
+    contentObserver = null
+  })
+
+  return { scroller, columnEl, stickBottom, scrollingDown, onScroll, jumpToLatest }
+}