agentworkshop 0.7.3 → 0.7.4

package/tui/components/monitor-pane.mjs

@@ -0,0 +1,39 @@
+// ============================================================
+// MonitorPane —— 右侧 agent 终端镜像面板(term 帧 → 行)。
+// 行来源:aw-tui 的终端 WS 接线把 term.* 帧写入 state.monitor。
+// ============================================================
+import { theme } from '../theme.mjs'
+import { wrapTextWithAnsi, truncateToWidth } from '@earendil-works/pi-tui'
+
+const TONE = {
+  dim: s => theme.faint(s),
+  info: s => theme.info(s),
+  warn: s => theme.warn(s),
+  error: s => theme.error(s),
+  accent: s => theme.accent(s),
+  monitor: s => s,
+}
+
+export class MonitorPane {
+  constructor(state, width = 44) {
+    this.state = state
+    this.width = width
+  }
+
+  render() {
+    const m = this.state.monitor
+    const w = Math.max(this.width - 2, 16)
+    const head = theme.info(`┌─ 监控 ${m.name ?? m.agentId?.slice(0, 8) ?? ''} ${m.streaming ? '· 流式中' : ''}`)
+    const lines = [head]
+    if (m.waiting) lines.push(theme.warn('omp 进程未启动,等待首个任务…'))
+    if (!m.agentId) lines.push(theme.faint('(未开启 —— /monitor <agent名|序号>)'))
+    for (const l of m.lines) {
+      const paint = TONE[l.tone] ?? (s => s)
+      lines.push(...wrapTextWithAnsi(paint(l.text), w))
+    }
+    if (m.streamText) {
+      lines.push(...wrapTextWithAnsi(theme.faint(m.streamText.slice(-600)), w))
+    }
+    return lines.slice(0, 200).map(l => truncateToWidth(l, w))
+  }
+}

package/tui/components/root.mjs

@@ -0,0 +1,53 @@
+// ============================================================
+// Root —— 组件树组装:双栏(会话流 | 监控面板) + HITL 卡 + 状态条 + 编辑器。
+// 双栏为手工列合成(pi-tui Container 只做纵向;列宽恒定防抖动)。
+// 列宽计算必须用 CJK 感知的 visibleWidth(中文占 2 列;stripAnsi().length 会低估)。
+// ============================================================
+import { visibleWidth, truncateToWidth } from '@earendil-works/pi-tui'
+import { theme } from '../theme.mjs'
+
+/**
+ * 双栏容器:左栏自适应,右栏固定宽;任一为空退化为单栏。
+ * left/right 需实现 render(width) → string[](Component duck-typing)。
+ */
+export class Columns {
+  constructor(left, right = null, rightWidth = 46) {
+    this.left = left
+    this.right = right
+    this.rightWidth = rightWidth
+  }
+
+  render(width) {
+    const gutter = 3
+    const leftWidth = this.right ? width - this.rightWidth - gutter : width
+    const leftLines = this.left.render(leftWidth).map(l => truncateToWidth(l, leftWidth))
+    if (!this.right || this.right.render === undefined) return leftLines
+    const rightLines = this.right.render(this.rightWidth).map(l => truncateToWidth(l, this.rightWidth - 1))
+    const height = Math.max(leftLines.length, rightLines.length)
+    const out = []
+    for (let i = 0; i < height; i++) {
+      const l = leftLines[i] ?? ''
+      const r = rightLines[i] ?? ''
+      const padL = ' '.repeat(Math.max(leftWidth - visibleWidth(l), 0))
+      out.push(`${l}${padL}${theme.faint(' │ ')}${r}`)
+    }
+    return out
+  }
+}
+
+/** 组装整棵组件树(aw-tui 调用;返回可挂到 TUI 的顶层组件) */
+export function buildTree({ state, chatLog, monitorPane, hitlCard, statusBar, editor }) {
+  const columns = new Columns(chatLog, monitorPane)
+  const stack = {
+    render(width) {
+      return [
+        ...columns.render(width),
+        ...hitlCard.render(width),
+        ...statusBar.render(width),
+      ]
+    },
+  }
+  void state
+  void editor
+  return { stack, editor }
+}

package/tui/components/status-bar.mjs

@@ -0,0 +1,29 @@
+// ============================================================
+// StatusBar —— 底部状态条:频道/成员忙碌/HITL 待办/连接态。
+// ============================================================
+import { theme } from '../theme.mjs'
+import { truncateToWidth } from '@earendil-works/pi-tui'
+
+const CONN_LABEL = { open: '实时', connecting: '连接中', closed: '离线' }
+
+export class StatusBar {
+  constructor(state) {
+    this.state = state
+  }
+
+  render(width) {
+    const s = this.state
+    const channel = s.channels.find(c => c.id === s.activeChannelId)
+    const members = s.agents.length
+    const busy = Object.values(s.agentStates).filter(a => a.state === 'busy').length
+    const parts = [
+      theme.accent(`▣ ${channel?.name ?? '未选择频道'}`),
+      members > 0 ? theme.faint(`成员 ${members}(忙 ${busy})`) : theme.faint('成员 0'),
+      s.hitl.length > 0 ? theme.warn(`⏸ HITL 待处理 ${s.hitl.length}(/hitl)`) : theme.faint('HITL 0'),
+      s.monitor.agentId ? theme.info(`监控:${s.monitor.waiting ? '等待进程' : s.monitor.name}`) : null,
+      s.connState === 'open' ? theme.faint(`● ${CONN_LABEL[s.connState]}`) : theme.warn(`● ${CONN_LABEL[s.connState] ?? s.connState}`),
+    ].filter(Boolean)
+    const line = parts.join(theme.faint(' · '))
+    return [truncateToWidth(line, Math.max(width, 20))]
+  }
+}

package/tui/lib/api.mjs

@@ -0,0 +1,82 @@
+// ============================================================
+// TUI REST 客户端 —— 统一信封 { code, message, data } 解包 + Bearer 注入。
+// 与 sdk/api.mjs 同语义(轻量自包含:TUI 不依赖构建产物,保持 .mjs 直跑)。
+// ============================================================
+
+/**
+ * 创建 API 客户端
+ * @param {object} opts
+ * @param {string} opts.baseUrl   形如 http://127.0.0.1:3000
+ * @param {string} opts.token     用户 token(ut-*)
+ */
+export function createApi({ baseUrl, token, timeoutMs = 15_000 }) {
+  const base = String(baseUrl ?? '').replace(/\/+$/, '')
+  // 动态 token:登录/运行中换凭据即时生效(避免实例化时闭包捕获 undefined)
+  let currentToken = token ?? ''
+
+  async function request(path, { method = 'GET', body, query } = {}) {
+    const url = new URL(base + path)
+    if (query) for (const [k, v] of Object.entries(query)) url.searchParams.set(k, String(v))
+    const ctrl = new AbortController()
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs)
+    try {
+      const res = await fetch(url, {
+        method,
+        headers: {
+          ...(currentToken ? { authorization: `Bearer ${currentToken}` } : {}),
+          ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+        signal: ctrl.signal,
+      })
+      const json = await res.json().catch(() => null)
+      if (!json || json.code === undefined) {
+        throw new Error(`HTTP ${res.status}(响应非标准信封)`)
+      }
+      if (json.code !== 0) {
+        const err = new Error(json.message ?? String(json.code))
+        err.code = json.code
+        throw err
+      }
+      return json.data
+    }
+    finally {
+      clearTimeout(timer)
+    }
+  }
+
+  return {
+    request,
+    /** 运行中更新凭据(登录后/换号) */
+    setToken(t) {
+      currentToken = t ?? ''
+    },
+
+    // ── 登录(无 token 引导;成功自动记住 token) ──
+    async login(email, password) {
+      const res = await request('/api/users/login', { method: 'POST', body: { email, password } })
+      currentToken = res.token
+      return res
+    },
+    get: (path, query) => request(path, { query }),
+    post: (path, body) => request(path, { method: 'POST', body }),
+
+    // ── channel/agent/task 管理面 ──
+    listChannels: () => request('/api/workshop/channels'),
+    createChannel: body => request('/api/workshop/channels', { method: 'POST', body }),
+    listAgents: channelId => request(`/api/workshop/channels/${channelId}/agents`),
+    addAgent: (channelId, body) => request(`/api/workshop/channels/${channelId}/agents`, { method: 'POST', body }),
+    listTemplates: () => request('/api/workshop/agents'),
+    listMessages: (channelId, limit = 50) => request(`/api/workshop/channels/${channelId}/messages`, { query: { limit } }),
+    sendMessage: (channelId, body) => request(`/api/workshop/channels/${channelId}/messages`, { method: 'POST', body }),
+    listTasks: channelId => request(`/api/workshop/channels/${channelId}/tasks`),
+    submitTask: (channelId, body) => request(`/api/workshop/channels/${channelId}/tasks`, { method: 'POST', body }),
+
+    // ── HITL 统一面(pending 响应为 { items: [...] },此处解包为数组) ──
+    hitlPending: async (channelId) => {
+      const data = await request('/api/workshop/hitl/pending', { query: channelId ? { channelId } : {} })
+      return data?.items ?? []
+    },
+    hitlRespond: body => request('/api/workshop/hitl/respond', { method: 'POST', body }),
+  }
+}

package/tui/lib/config.mjs

@@ -0,0 +1,58 @@
+// ============================================================
+// TUI 认证/连接配置 —— 落配置根 .AgentWorkShop/tui-auth.json(0600)。
+// 解析口径与服务端一致:cwd 向上找 config.yml → <repo>/.AgentWorkShop,
+// 找不到(全局安装任意 cwd)→ ~/.AgentWorkShop。
+// ============================================================
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve, dirname } from 'node:path'
+
+/** 向上查找文件(repo 模式判定) */
+function findUp(startDir, filename) {
+  let dir = resolve(startDir)
+  for (;;) {
+    const candidate = join(dir, filename)
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** 配置根(repo 内 cwd → <repo>/.AgentWorkShop;否则 ~/.AgentWorkShop) */
+export function configRoot(cwd = process.cwd()) {
+  const marker = findUp(cwd, 'config.yml')
+  if (marker) return join(dirname(marker), '.AgentWorkShop')
+  return join(homedir(), '.AgentWorkShop')
+}
+
+const authPath = cwd => join(configRoot(cwd), 'tui-auth.json')
+
+/** 读取已存凭据({ baseUrl, token, email? } 或 null) */
+export function loadAuth(cwd = process.cwd()) {
+  try {
+    const raw = JSON.parse(readFileSync(authPath(cwd), 'utf8'))
+    if (raw && typeof raw.token === 'string' && typeof raw.baseUrl === 'string') return raw
+  }
+  catch { /* 无凭据/损坏 → 重新登录 */ }
+  return null
+}
+
+/** 持久化凭据(0600;路径加入 .gitignore) */
+export function saveAuth(auth, cwd = process.cwd()) {
+  const file = authPath(cwd)
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, `${JSON.stringify(auth, null, 2)}\n`, 'utf8')
+  try {
+    chmodSync(file, 0o600)
+  }
+  catch { /* Windows FAT 卷 chmod 无效,忽略 */ }
+}
+
+/** 清除凭据(登出) */
+export function clearAuth(cwd = process.cwd()) {
+  try {
+    existsSync(authPath(cwd)) && (writeFileSync(authPath(cwd), '{}\n', 'utf8'), true)
+  }
+  catch { /* 尽力而为 */ }
+}

package/tui/lib/reducers.mjs

@@ -0,0 +1,218 @@
+// ============================================================
+// AEP 帧归约(纯函数式:输入 state+信封 → 原地更新 state 与 log 行)。
+// 与 WebUI 的 events.store 同一套语义:agent.delta 聚合进流式块,落定
+// agent.message 携带全文定稿(去重);hitl 增删幂等(kind+id)。
+// 可被 tsx/单测与 scripts/tui-smoke.mjs 无头驱动。
+// ============================================================
+import { pushLog } from './state.mjs'
+
+const STREAM_TAIL = 4000
+
+/** 从信封/消息提取展示名 */
+function agentNameOf(state, agentId, fallback = '') {
+  if (!agentId) return fallback
+  const a = state.agents.find(x => x.id === agentId)
+  return a?.name ?? fallback ?? agentId.slice(0, 8)
+}
+
+/** 消息 parts → 纯文本 */
+function partsText(message) {
+  const parts = message?.parts ?? []
+  return parts.map((p) => {
+    if (typeof p === 'string') return p
+    if (p && typeof p === 'object' && typeof p.text === 'string') return p.text
+    return ''
+  }).join('').trim()
+}
+
+/**
+ * 归约一帧 AEP 信封。返回 'handled' | 'ignored'(测试断言用)。
+ * 流式块键 = agentId+taskId(agent.message 到达即定稿替换全文)。
+ */
+export function reduceEnvelope(state, e) {
+  switch (e.type) {
+    case 'agent.status': {
+      const p = e.payload
+      state.agentStates[p.agentId] = {
+        state: p.state,
+        currentTaskId: p.currentTaskId ?? null,
+        queued: p.queued ?? 0,
+        completed: p.completed ?? 0,
+      }
+      return 'handled'
+    }
+    case 'agent.delta': {
+      const text = e.payload?.delta ?? ''
+      if (!text) return 'ignored'
+      const row = findStreamRow(state, e.agentId, e.taskId)
+      if (row) {
+        row.text = (row.text + text).slice(-STREAM_TAIL)
+      }
+      else {
+        pushLog(state, 'stream', text, { agentName: agentNameOf(state, e.agentId), agentId: e.agentId, taskId: e.taskId ?? null })
+      }
+      return 'handled'
+    }
+    case 'agent.message': {
+      const msg = e.payload ?? {}
+      const text = partsText(msg)
+      if (!text) return 'ignored'
+      const agentId = e.agentId ?? msg.metadata?.['x-aw-from-agent'] ?? ''
+      const name = agentNameOf(state, agentId, msg.metadata?.['x-aw-from-label'] ?? '')
+      const row = findStreamRow(state, agentId, e.taskId)
+      if (row) {
+        // 定稿:流式增量替换为全文,并升级为正式 agent 行(渲染带名高亮)
+        row.text = text
+        row.kind = 'agent'
+        row.agentName = name
+      }
+      else {
+        pushLog(state, 'agent', text, { agentName: name, agentId, taskId: e.taskId ?? null })
+      }
+      return 'handled'
+    }
+    case 'a2a.message': {
+      const msg = e.payload ?? {}
+      const meta = msg.metadata ?? {}
+      const fromLabel = meta['x-aw-from-label'] ?? ''
+      const fromAgent = meta['x-aw-from-agent'] ?? e.agentId ?? ''
+      const text = partsText(msg)
+      if (!text) return 'ignored'
+      const cross = meta['x-aw-cross-channel'] === 'true'
+      const prefix = cross ? '[跨频道] ' : ''
+      if (fromAgent) {
+        pushLog(state, 'agent', prefix + text, { agentName: agentNameOf(state, fromAgent, fromLabel), agentId: fromAgent, taskId: msg.taskId ?? null })
+      }
+      else {
+        // 人类消息(服务端盖章 from-label;本端发出的回显也走这里)
+        pushLog(state, 'user', prefix + text, { agentName: fromLabel || '用户' })
+      }
+      return 'handled'
+    }
+    case 'agent.status.message': {
+      const text = (e.payload?.text ?? '').trim()
+      if (text) pushLog(state, 'notice', text, { agentName: agentNameOf(state, e.agentId) })
+      return 'handled'
+    }
+    case 'task.status': {
+      const p = e.payload ?? {}
+      upsertTask(state, p)
+      const title = p.title ?? state.tasks.find(t2 => t2.taskId === p.taskId)?.title ?? ''
+      pushLog(state, 'task', `任务 ${p.taskId?.slice(0, 8)}${title ? `「${title}」` : ''} → ${p.state}${p.progress != null ? ` ${p.progress}%` : ''}`)
+      return 'handled'
+    }
+    case 'task.progress': {
+      const p = e.payload ?? {}
+      upsertTask(state, p)
+      return 'handled'
+    }
+    case 'a2a.artifact': {
+      const art = e.payload?.artifact
+      const name = art?.name ?? art?.kind ?? 'artifact'
+      pushLog(state, 'notice', `交付物:${name}`, { agentName: agentNameOf(state, e.agentId) })
+      return 'handled'
+    }
+    case 'error': {
+      pushLog(state, 'error', e.payload?.message ?? '未知错误', { agentName: agentNameOf(state, e.agentId) })
+      return 'handled'
+    }
+    case 'hitl.request': {
+      upsertHitl(state, e.payload)
+      const it = e.payload
+      pushLog(state, 'hitl', `⏸ 需要人工处理:${it.title}(${it.agentName})—— /hitl 查看并作答`)
+      return 'handled'
+    }
+    case 'hitl.resolved': {
+      const r = e.payload
+      state.hitl = state.hitl.filter(i => !(i.kind === r.kind && i.id === r.id))
+      if (state.hitlAnswering && state.hitlAnswering.kind === r.kind && state.hitlAnswering.id === r.id) state.hitlAnswering = null
+      pushLog(state, 'hitl-resolved', `✔ 待办已落定:${r.id}(outcome=${r.outcome}${r.by ? `, by ${r.by}` : ''})`)
+      return 'handled'
+    }
+    default:
+      return 'ignored'
+  }
+}
+
+function findStreamRow(state, agentId, taskId) {
+  for (let i = state.log.length - 1; i >= 0; i--) {
+    const row = state.log[i]
+    if (row.kind === 'stream' && row.agentId === agentId && (row.taskId ?? null) === (taskId ?? null)) return row
+  }
+  return null
+}
+
+function upsertTask(state, p) {
+  if (!p.taskId) return
+  const idx = state.tasks.findIndex(t => t.taskId === p.taskId)
+  if (idx >= 0) state.tasks[idx] = { ...state.tasks[idx], ...p }
+  else state.tasks.unshift(p)
+  state.tasks = state.tasks.slice(0, 100)
+}
+
+function upsertHitl(state, item) {
+  if (!item?.id) return
+  const idx = state.hitl.findIndex(i => i.kind === item.kind && i.id === item.id)
+  if (idx >= 0) state.hitl[idx] = item
+  else state.hitl.push(item)
+}
+
+// ===== 终端镜像帧 → monitor 行(纯部分;ws 接线在 aw-tui) =====
+
+/** term 帧 → monitor 行描述;返回 { lines:[{text,tone}], streamAppend?, streamEnd?, statePatch? } */
+export function reduceTermFrame(frame) {
+  const out = { lines: [], streamAppend: '', streamEnd: null, statePatch: null }
+  const type = frame?.type
+  switch (type) {
+    case 'agent_start':
+      out.lines.push({ text: '── 回合开始 ──', tone: 'dim' })
+      break
+    case 'agent_end':
+      out.lines.push({ text: '── 回合结束 ──', tone: 'dim' })
+      break
+    case 'message_end': {
+      const text = String(frame.text ?? '').trim()
+      if (text) out.lines.push({ text, tone: 'monitor' })
+      break
+    }
+    case 'tool_execution_start':
+      out.lines.push({ text: `🔧 ${frame.toolName ?? ''}${brief(frame.args, 80)}`, tone: 'info' })
+      break
+    case 'tool_execution_end':
+      out.lines.push({ text: `${frame.isError ? '✗' : '✔'} ${frame.toolName ?? ''}${brief(frame.result, 120)}`, tone: frame.isError ? 'error' : 'dim' })
+      break
+    case 'host_tool_call':
+      out.lines.push({ text: `🛠 host ${frame.toolName ?? ''}${brief(frame.args, 80)}`, tone: 'info' })
+      break
+    case 'extension_ui_request':
+      if (frame.method && frame.method !== 'cancel') {
+        out.lines.push({ text: `⏸ HITL ${frame.method}「${String(frame.title ?? '').slice(0, 60)}」(/hitl 作答)`, tone: 'warn' })
+      }
+      break
+    case '__human_input':
+      out.lines.push({ text: `⌨ ${String(frame.text ?? '').slice(0, 120)}`, tone: 'info' })
+      break
+    case '__terminal_notice':
+      out.lines.push({ text: String(frame.message ?? ''), tone: frame.level === 'error' ? 'error' : frame.level === 'warning' ? 'warn' : 'dim' })
+      break
+    default:
+      break
+  }
+  return out
+}
+
+function brief(value, max) {
+  if (value == null) return ''
+  let s = typeof value === 'string'
+    ? value
+    : (() => {
+        try {
+          return JSON.stringify(value) ?? ''
+        }
+        catch {
+          return String(value)
+        }
+      })()
+  s = s.replace(/\s+/g, ' ').trim()
+  return s ? ` ${s.slice(0, max)}${s.length > max ? '…' : ''}` : ''
+}

package/tui/lib/state.mjs

@@ -0,0 +1,80 @@
+// ============================================================
+// TuiState —— 全局共享状态(单一对象 + 订阅通知;组件渲染时读取)。
+// 纯数据,不含行为;帧归约逻辑在 reducers.mjs(可单测)。
+// ============================================================
+import { EventEmitter } from 'node:events'
+
+export const LOG_CAP = 400
+
+/** 日志行:{ id, kind, agentName?, text, at }
+ *  kind: system|user|agent|stream|task|hitl|hitl-resolved|error|monitor|notice */
+export function createState() {
+  const emitter = new EventEmitter()
+  emitter.setMaxListeners(20)
+
+  const state = {
+    baseUrl: '',
+    token: '',
+    userName: '',
+
+    connState: 'closed', // closed|connecting|open
+    channels: [],
+    activeChannelId: null,
+    agents: [], // channel 成员实例:{ id, name, role, harness, enabled }
+    agentStates: {}, // agentId → { state, currentTaskId, queued, completed }
+    tasks: [],
+
+    hitl: [], // AepHitlItem[]
+    /** 正在作答的条目(index → /hitl <n>;null = 常规输入) */
+    hitlAnswering: null,
+
+    monitor: {
+      agentId: null,
+      name: null,
+      connected: false,
+      waiting: false, // omp 未 spawn(NO_SESSION 重试等待)
+      streaming: false,
+      lines: [], // { text, tone: dim|info|warn|error|accent }
+      streamText: '', // message_update 聚合行(尾部)
+    },
+
+    /** 瞬时状态条消息(命令回执;几行内自然被后续输出顶走) */
+    statusMsg: '',
+    statusAt: 0,
+  }
+
+  return {
+    state,
+    /** 组件注册重渲染回调(requestRender) */
+    onChange(fn) {
+      emitter.on('change', fn)
+      return () => emitter.off('change', fn)
+    },
+    /** 归约器/命令改状态后调用 → 触发一帧渲染 */
+    notify() {
+      emitter.emit('change')
+    },
+  }
+}
+
+/** 追加日志行(封顶裁剪);返回该行 id */
+export function pushLog(state, kind, text, extra = {}) {
+  const row = {
+    id: `${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+    kind,
+    text,
+    agentName: extra.agentName ?? '',
+    agentId: extra.agentId ?? null,
+    taskId: extra.taskId ?? null,
+    at: new Date(),
+  }
+  state.log.push(row)
+  if (state.log.length > LOG_CAP) state.log.splice(0, state.log.length - LOG_CAP)
+  return row
+}
+
+/** TUI 挂载 log 数组(state.log 由宿主初始化;此处类型聚合,便于单测构造) */
+export function withLog(state) {
+  state.log ??= []
+  return state
+}

package/tui/lib/virtual-terminal.mjs

@@ -0,0 +1,48 @@
+// ============================================================
+// 虚拟终端(Terminal 接口最小实现)—— 无 TTY 环境驱动 TUI:
+// 捕获写入帧、注入按键流;scripts/tui-smoke.mjs 无头 e2e 用。
+// ============================================================
+import { stripAnsi } from '../theme.mjs'
+
+export class VirtualTerminal {
+  constructor(cols = 120, rows = 34) {
+    this.columns = cols
+    this.rows = rows
+    this.frames = []
+    this.inputHandler = null
+    this.kittyProtocolActive = false
+  }
+
+  start(onInput) {
+    this.inputHandler = onInput
+  }
+
+  stop() {}
+  async drainInput() {}
+  write(data) {
+    this.frames.push(data)
+  }
+
+  moveBy() {}
+  hideCursor() {}
+  showCursor() {}
+  clearLine() {}
+  clearFromCursor() {}
+  clearScreen() {}
+  setTitle() {}
+  setProgress() {}
+
+  /** 测试注入按键(模拟 raw-mode 字节流) */
+  emitInput(data) {
+    this.inputHandler?.(data)
+  }
+
+  output() {
+    return this.frames.join('')
+  }
+
+  /** 剥 ANSI 后的纯文本(断言用) */
+  text() {
+    return stripAnsi(this.output())
+  }
+}