agentworkshop 0.7.3 → 0.7.4

package/tui/aw-tui.mjs

@@ -0,0 +1,356 @@
+// ============================================================
+// AgentWorkShop TUI 入口 —— 终端工作台(与 AgentTeam 交互作业)。
+//
+//   node tui/aw-tui.mjs [--url http://127.0.0.1:3000] [--token ut-*]
+//                       [--channel <名>] [--headless]
+//   (或 `aw tui …` / `pnpm tui`)
+//
+// 装配:认证(配置根 tui-auth.json / 交互登录)→ AEP 事件流(频道 sub)+
+// 命令系统(/help)+ 监控面板(终端 WS)+ HITL 统一作答(/hitl)。
+// --headless:VirtualTerminal 驱动(无 TTY;scripts/tui-smoke.mjs 用)。
+// ============================================================
+import { TuiMainScreen, Editor, CombinedAutocompleteProvider, ProcessTerminal } from '@earendil-works/pi-tui'
+import { theme } from './theme.mjs'
+import { loadAuth, saveAuth, configRoot } from './lib/config.mjs'
+import { createApi } from './lib/api.mjs'
+import { connectAep, connectTerm } from './lib/ws.mjs'
+import { createState, pushLog, withLog } from './lib/state.mjs'
+import { reduceEnvelope, reduceTermFrame } from './lib/reducers.mjs'
+import { dispatchCommand, slashCommandCompletions } from './commands/index.mjs'
+import { ChatLog } from './components/chat-log.mjs'
+import { StatusBar } from './components/status-bar.mjs'
+import { MonitorPane } from './components/monitor-pane.mjs'
+import { HitlCard } from './components/hitl-card.mjs'
+import { buildTree } from './components/root.mjs'
+import { VirtualTerminal } from './lib/virtual-terminal.mjs'
+
+function parseArgs(argv) {
+  const opts = { headless: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--headless') opts.headless = true
+    else if (a === '--url') opts.url = argv[++i]
+    else if (a === '--token') opts.token = argv[++i]
+    else if (a === '--channel') opts.channel = argv[++i]
+  }
+  return opts
+}
+
+/** 认证:已存凭据 → --token → 环境变量 → 交互登录 */
+async function ensureAuth(opts) {
+  const saved = loadAuth()
+  const baseUrl = opts.url ?? process.env.AW_TUI_URL ?? saved?.baseUrl ?? 'http://127.0.0.1:3000'
+  if (opts.token) return { baseUrl, token: opts.token }
+  if (saved?.token && saved.baseUrl === baseUrl) return { baseUrl, token: saved.token }
+
+  const email = process.env.AW_TUI_EMAIL
+  const password = process.env.AW_TUI_PASSWORD
+  if (email && password) {
+    const api = createApi({ baseUrl })
+    const res = await api.login(email, password)
+    const auth = { baseUrl, token: res.token, email }
+    saveAuth(auth)
+    return auth
+  }
+  if (opts.headless) throw new Error('无凭据:headless 模式请传 --token 或设 AW_TUI_EMAIL/AW_TUI_PASSWORD')
+
+  const rl = (await import('node:readline/promises')).createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    console.log(`AgentWorkShop TUI 首次使用(凭据落 ${configRoot()}/tui-auth.json)`)
+    const mail = await rl.question('邮箱: ')
+    const pass = await rl.question('密码: ')
+    const api = createApi({ baseUrl })
+    const res = await api.login(mail.trim(), pass)
+    const auth = { baseUrl, token: res.token, email: mail.trim() }
+    saveAuth(auth)
+    console.log('✔ 登录成功,凭据已保存')
+    return auth
+  }
+  finally {
+    rl.close()
+  }
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv)
+  const auth = await ensureAuth(opts)
+
+  const store = createState()
+  const state = withLog(store.state)
+  state.baseUrl = auth.baseUrl
+  state.token = auth.token
+  const api = createApi(auth)
+
+  // ── 终端 + 组件树 ──
+  const terminal = opts.headless ? new VirtualTerminal() : new ProcessTerminal()
+  if (opts.headless) (globalThis).__tuiSmokeTerminal = terminal // 无头 e2e 注入句柄
+  const tui = new TuiMainScreen(terminal)
+  const chatLog = new ChatLog(state)
+  const monitorPane = new MonitorPane(state)
+  const hitlCard = new HitlCard(state)
+  const statusBar = new StatusBar(state)
+  const editor = new Editor(tui, theme.editor)
+  const { stack } = buildTree({ state, chatLog, monitorPane, hitlCard, statusBar, editor })
+
+  const push = (kind, text) => {
+    pushLog(state, kind, text)
+    store.notify()
+  }
+  const echo = (kind, text) => push(kind === 'warn' ? 'hitl' : kind, text)
+
+  // ── 装配动作(命令系统/提交路由的副作用入口) ──
+  let termConn = null
+  const actions = {
+    async switchChannel(channelId) {
+      if (state.activeChannelId && state.activeChannelId !== channelId) aep.unsubscribe(state.activeChannelId)
+      state.activeChannelId = channelId
+      aep.subscribe(channelId, seqCursor.get(channelId))
+      await actions.refreshAgents()
+      // 时间线回填:最近 20 条(人类/Agent 消息)
+      try {
+        const msgs = await api.listMessages(channelId, 20)
+        for (const m of msgs) {
+          const text = (m.parts ?? []).map(p => p?.text ?? '').join('').trim()
+          if (!text) continue
+          if (m.role === 'USER' || m.fromAgentId == null) push('user', text)
+          else push('agent', text)
+        }
+      }
+      catch { /* 回填失败不阻塞 */ }
+      const ch = state.channels.find(c => c.id === channelId)
+      push('system', `已切换到频道「${ch?.name ?? channelId.slice(0, 8)}」—— 普通文本发送任务,/help 查看命令。`)
+      store.notify()
+    },
+    async refreshAgents() {
+      if (!state.activeChannelId) return
+      const list = await api.listAgents(state.activeChannelId)
+      state.agents = list.map(a => ({ id: a.id, name: a.name, role: a.role, harness: a.harness, enabled: a.enabled }))
+      store.notify()
+    },
+    openMonitor(agent) {
+      termConn?.close()
+      termConn = null
+      state.monitor = { agentId: agent.id, name: agent.name, connected: false, waiting: false, streaming: false, lines: [], streamText: '' }
+      const mon = state.monitor
+      const addLine = (text, tone = 'dim') => {
+        mon.lines.push({ text, tone })
+        if (mon.lines.length > 120) mon.lines.splice(0, mon.lines.length - 120)
+      }
+      const applyFrame = (frame) => {
+        if (frame.type === 'message_update') {
+          const ev = frame.assistantMessageEvent
+          const delta = typeof ev?.delta === 'string' ? ev.delta : typeof frame.text === 'string' ? frame.text : ''
+          if (delta) mon.streamText = (mon.streamText + delta).slice(-2000)
+          mon.streaming = true
+          return
+        }
+        if (frame.type === 'message_end' || frame.type === 'turn_end') mon.streaming = false
+        const { lines } = reduceTermFrameSafe(frame)
+        for (const l of lines) addLine(l.text, l.tone)
+      }
+      termConn = connectTerm({
+        baseUrl: state.baseUrl,
+        token: state.token,
+        agentId: agent.id,
+        channelId: state.activeChannelId,
+        onMessage(msg) {
+          if (msg.type === 'term.init') {
+            mon.connected = true
+            mon.waiting = false
+            addLine(`── 已接入 ${msg.meta?.name ?? agent.name} pid ${msg.meta?.pid ?? '?'}(重放 ${msg.lastSeq ?? 0} 帧)──`, 'accent')
+            if (msg.hitl) {
+              upsertHitlLocal(state, { kind: 'omp-dialog', id: msg.hitl.id, channelId: state.activeChannelId, agentId: agent.id, agentName: agent.name, method: msg.hitl.method, title: msg.hitl.title, options: msg.hitl.options, message: msg.hitl.message })
+              addLine(`⏸ 待答对话框:${msg.hitl.title}(/hitl 作答)`, 'warn')
+            }
+            // 重放尾部 40 帧给上下文
+            for (const f of (msg.replay ?? []).slice(-40)) applyFrame(f.frame)
+          }
+          else if (msg.type === 'term.frames') {
+            for (const f of msg.frames ?? []) applyFrame(f.frame)
+          }
+          else if (msg.type === 'term.state') {
+            mon.streaming = msg.streaming
+          }
+          else if (msg.type === 'term.notice') {
+            addLine(msg.message, msg.level === 'error' ? 'error' : 'dim')
+          }
+          store.notify()
+        },
+        onClose(code) {
+          if (mon.agentId !== agent.id) return
+          mon.connected = false
+          if (code === 4404) {
+            mon.waiting = true
+            addLine('omp 进程未启动(随首个任务 spawn),等待接入…', 'warn')
+          }
+          store.notify()
+        },
+      })
+      push('system', `监控已开启:${agent.name}(右侧面板;/monitor off 关闭)`)
+    },
+    closeMonitor() {
+      termConn?.close()
+      termConn = null
+      state.monitor = { agentId: null, name: null, connected: false, waiting: false, streaming: false, lines: [], streamText: '' }
+      store.notify()
+    },
+    async submitHitlAnswer(text) {
+      const item = state.hitlAnswering
+      if (!item) return false
+      const body = { kind: item.kind, id: item.id }
+      if (item.kind === 'omp-dialog') {
+        if (item.method === 'confirm') {
+          const norm = text.trim().toLowerCase()
+          if (!['y', 'n', 'yes', 'no'].includes(norm)) {
+            push('error', 'confirm 对话框请输入 y(批准)或 n(拒绝)')
+            return true
+          }
+          body.confirmed = norm.startsWith('y')
+        }
+        else if (item.method === 'select') {
+          const idx = Number.parseInt(text.trim(), 10)
+          if (!Number.isInteger(idx) || idx < 1 || idx > (item.options?.length ?? 0)) {
+            push('error', `select 请输入 1-${item.options?.length ?? 0} 的序号`)
+            return true
+          }
+          body.value = item.options[idx - 1]
+        }
+        else {
+          body.value = text
+        }
+      }
+      else {
+        // dcw-approval:confirm 语义(y=批准/n=拒绝)+ 备注
+        const norm = text.trim().toLowerCase()
+        body.confirmed = norm.startsWith('y')
+        if (norm.length > 1) body.comment = text
+      }
+      try {
+        await api.hitlRespond(body)
+        push('system', `✔ 应答已提交(${item.title})`)
+        state.hitl = state.hitl.filter(i => !(i.kind === item.kind && i.id === item.id))
+        state.hitlAnswering = null
+      }
+      catch (err) {
+        push('error', `应答失败:${err.message}`)
+        if (String(err.code) === 'ALREADY_RESOLVED') state.hitlAnswering = null
+      }
+      store.notify()
+      return true
+    },
+    quit() {
+      aep.close()
+      termConn?.close()
+      tui.stop()
+      process.exit(0)
+    },
+  }
+  const ctx = { state, store, api, echo, push, actions }
+
+  // ── 编辑器提交路由:HITL 作答 → 命令 → 普通文本发任务 ──
+  editor.onSubmit = async (text) => {
+    const trimmed = text.trim()
+    editor.setText('')
+    editor.addToHistory?.(text)
+    if (!trimmed) return
+    if (state.hitlAnswering) {
+      await actions.submitHitlAnswer(trimmed)
+      return
+    }
+    if (trimmed.startsWith('/')) {
+      await dispatchCommand(ctx, trimmed)
+      store.notify()
+      return
+    }
+    if (!state.activeChannelId) {
+      push('error', '未选择频道:先 /channels + /channel use <名|序号>')
+      return
+    }
+    // messages 端点要求 toAgentId:普通文本缺省路由 lead
+    const ch = state.channels.find(c => c.id === state.activeChannelId)
+    const leadId = ch?.leadAgentId ?? state.agents.find(a => a.role === 'lead')?.id
+    if (!leadId) {
+      push('error', '当前频道没有 lead:用 /channel new --lead <名> 重建,或 /send <成员> 指定收件人。')
+      return
+    }
+    try {
+      await api.sendMessage(state.activeChannelId, { toAgentId: leadId, text: trimmed, priority: 'task', fromLabel: state.userName || '用户' })
+    }
+    catch (err) {
+      push('error', `发送失败:${err.message}`)
+    }
+    store.notify()
+  }
+
+  // ── AEP 事件流 ──
+  const seqCursor = new Map()
+  const aep = connectAep({
+    baseUrl: state.baseUrl,
+    token: state.token,
+    onEvent(e) {
+      if (e.channelId && typeof e.seq === 'number') {
+        aep.cursor(e.channelId, e.seq)
+        seqCursor.set(e.channelId, e.seq)
+      }
+      reduceEnvelope(state, e)
+      store.notify()
+    },
+    onState(s) {
+      state.connState = s
+      store.notify()
+    },
+  })
+
+  store.onChange(() => tui.requestRender())
+
+  // ── 组装视图 ──
+  tui.addChild({ render: width => [...stack.render(width), '', ...editor.render(width)] })
+  editor.setAutocompleteProvider?.(new CombinedAutocompleteProvider(slashCommandCompletions(), process.cwd()))
+  tui.setFocus(editor)
+
+  push('system', `AgentWorkShop TUI 已就绪 ${state.baseUrl}`)
+  push('system', '普通文本 = 发任务到当前频道;/help 命令列表;/hitl 处理待办。')
+
+  // ── 启动:频道自动选择 → 订阅 ──
+  try {
+    const channels = await api.listChannels()
+    state.channels = channels
+    // 空字符串 --channel 视为未指定('' 非 nullish,?? 不会走右侧)
+    const target = (opts.channel ? channels.find(c => c.name === opts.channel || c.id === opts.channel) : undefined)
+      ?? channels[0]
+    if (target) await actions.switchChannel(target.id)
+    else push('warn', '尚无频道:/channel new <名称> 创建一个。')
+    const me = await api.get('/api/workshop/users/me').catch(() => null)
+    state.userName = me?.user?.name ?? me?.name ?? '用户'
+  }
+  catch (err) {
+    push('error', `初始化失败:${err.message}`)
+  }
+
+  tui.start()
+  return tui
+}
+
+function upsertHitlLocal(state, item) {
+  const i = state.hitl.findIndex(x => x.kind === item.kind && x.id === item.id)
+  if (i >= 0) state.hitl[i] = item
+  else state.hitl.push(item)
+}
+
+/** reduceTermFrame 的防御包装(未知帧形状不炸渲染) */
+function reduceTermFrameSafe(frame) {
+  try {
+    return reduceTermFrame(frame)
+  }
+  catch {
+    return { lines: [] }
+  }
+}
+
+// 直接运行入口(aw tui / pnpm tui 均落到这里)
+if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replaceAll('\\', '/').split('/').pop())) {
+  main().catch((err) => {
+    console.error('[tui] 启动失败:', err.message)
+    process.exit(1)
+  })
+}

package/tui/commands/index.mjs

@@ -0,0 +1,250 @@
+// ============================================================
+// TUI 命令系统 —— SlashCommand 集中注册 + 解析(仿 openclaw tui/commands.ts)。
+// handler(ctx, args):ctx = { state, notify, api, ws, actions, echo }。
+// actions 由 aw-tui 注入(switchChannel/openMonitor/submitHitl 等带副作用的装配)。
+// ============================================================
+
+/** 解析 '/cmd arg1 arg2 --flag val --bool' → { name, args, flags } */
+export function parseCommand(input) {
+  const text = String(input ?? '').trim()
+  if (!text.startsWith('/')) return null
+  const tokens = text.slice(1).split(/\s+/).filter(Boolean)
+  const name = tokens.shift() ?? ''
+  const args = []
+  const flags = {}
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i]
+    if (tok.startsWith('--')) {
+      const key = tok.slice(2)
+      const next = tokens[i + 1]
+      if (next !== undefined && !next.startsWith('--')) {
+        flags[key] = next
+        i++
+      }
+      else flags[key] = true
+    }
+    else args.push(tok)
+  }
+  return { name, args, flags, rest: args.join(' ') }
+}
+
+export const commands = [
+  {
+    name: 'help',
+    description: '命令列表',
+    handler(ctx) {
+      const rows = commands.map(c => `  /${c.name}${c.usage ? ` ${c.usage}` : ''}  — ${c.description}`)
+      ctx.echo('system', `可用命令:\n${rows.join('\n')}\n普通文本 = 发送任务到当前频道(lead);以 Agent 身份发信走 /send。`)
+    },
+  },
+  {
+    name: 'channels',
+    description: '列出我的频道',
+    async handler(ctx) {
+      const list = await ctx.api.listChannels()
+      ctx.state.channels = list
+      ctx.echo('system', `频道 ${list.length} 个:`)
+      for (const [i, c] of list.entries()) {
+        ctx.echo('system', `  ${i + 1}. ${c.name}${c.id === ctx.state.activeChannelId ? ' ◀ 当前' : ''}(id ${c.id.slice(0, 8)})`)
+      }
+    },
+  },
+  {
+    name: 'channel',
+    usage: 'new <name> [--desc …] [--lead <名>] | use <名|序号> | add <模板|名> [--role lead] [--harness omp] [--config JSON]',
+    description: '创建/切换频道、向频道放置 Agent',
+    async handler(ctx, args, flags) {
+      const sub = args.shift()
+      if (sub === 'new') {
+        const name = args.shift()
+        if (!name) return ctx.echo('error', '用法:/channel new <name> [--desc …] [--lead <名>]')
+        const desc = args.join(' ')
+        const body = { name, description: desc }
+        if (flags.lead) body.leadAgent = { name: String(flags.lead), harness: String(flags.harness ?? 'omp') }
+        // 响应为 { channelId, leadAgentId }(manager.createChannel 收敛)
+        const result = await ctx.api.createChannel(body)
+        ctx.state.channels.push({ id: result.channelId, name, description: desc, leadAgentId: result.leadAgentId ?? null })
+        ctx.echo('system', `✔ 频道已创建:${name}(id ${result.channelId.slice(0, 8)})`)
+        await ctx.actions.switchChannel(result.channelId)
+      }
+      else if (sub === 'use') {
+        const key = args.shift()
+        if (!key) return ctx.echo('error', '用法:/channel use <名|序号>(/channels 查看列表)')
+        const ch = resolveChannel(ctx.state, key)
+        if (!ch) return ctx.echo('error', `频道不存在:${key}`)
+        await ctx.actions.switchChannel(ch.id)
+      }
+      else if (sub === 'add') {
+        const name = args.shift()
+        if (!name) return ctx.echo('error', '用法:/channel add <模板名|名称> [--role lead|worker] [--harness omp] [--config JSON]')
+        const role = flags.role === 'lead' ? 'lead' : 'worker'
+        const harness = String(flags.harness ?? 'omp')
+        let body
+        const templates = await ctx.api.listTemplates().catch(() => [])
+        const tpl = templates.find(t => t.name === name)
+        if (tpl) {
+          body = { agentId: tpl.id, role, configOverride: parseConfigFlag(flags.config) }
+        }
+        else {
+          body = { name, harness, role, config: parseConfigFlag(flags.config) }
+          ctx.echo('system', `未找到模板「${name}」,按内联定义创建(harness=${harness})。`)
+        }
+        const inst = await ctx.api.addAgent(ctx.state.activeChannelId, body)
+        await ctx.actions.refreshAgents()
+        ctx.echo('system', `✔ Agent 已放入频道:${inst?.name ?? name}(${role})`)
+      }
+      else {
+        ctx.echo('error', '用法:/channel new|use|add …(/help)')
+      }
+    },
+  },
+  {
+    name: 'agents',
+    description: '当前频道成员与实时状态',
+    async handler(ctx) {
+      await ctx.actions.refreshAgents()
+      const rows = ctx.state.agents.map((a, i) => {
+        const st = ctx.state.agentStates[a.id]
+        const state = st?.state ?? 'idle'
+        const queued = st?.queued ?? 0
+        return `  ${i + 1}. ${a.name}${a.role === 'lead' ? '(lead)' : ''} ${state === 'busy' ? '● busy' : state === 'stopped' ? '○ stopped' : '○ idle'}${queued ? ` 队列${queued}` : ''} [${a.id.slice(0, 8)}]`
+      })
+      ctx.echo('system', `成员 ${rows.length}:\n${rows.join('\n') || '  (空 —— /channel add <名>)'}`)
+    },
+  },
+  {
+    name: 'send',
+    usage: '<agent名|序号> <文本…>',
+    description: '向指定 Agent 直发消息(忙碌时 steer 注入当前回合)',
+    async handler(ctx, args) {
+      const key = args.shift()
+      const text = args.join(' ')
+      if (!key || !text) return ctx.echo('error', '用法:/send <agent名|序号> <文本…>')
+      const agent = resolveAgent(ctx.state, key)
+      if (!agent) return ctx.echo('error', `成员不存在:${key}(/agents 查看)`)
+      await ctx.api.sendMessage(ctx.state.activeChannelId, { toAgentId: agent.id, text, priority: 'immediate', requireReply: true, fromLabel: ctx.state.userName || '用户' })
+      ctx.echo('system', `✔ 已直发 ${agent.name}`)
+    },
+  },
+  {
+    name: 'task',
+    usage: '<标题…> [--mode goal|loop|pipeline] [--assignee <agent>]',
+    description: '提交正式任务(缺省路由 lead,状态经 /tasks 跟踪)',
+    async handler(ctx, args, flags) {
+      const title = args.join(' ')
+      if (!title) return ctx.echo('error', '用法:/task <标题…> [--mode goal|loop|pipeline] [--assignee <agent>]')
+      const body = { title, mode: flags.mode ?? 'goal' }
+      if (flags.assignee) {
+        const a = resolveAgent(ctx.state, String(flags.assignee))
+        if (!a) return ctx.echo('error', `assignee 不存在:${flags.assignee}`)
+        body.assigneeId = a.id
+      }
+      const task = await ctx.api.submitTask(ctx.state.activeChannelId, body)
+      ctx.echo('system', `✔ 任务已提交:${task?.id?.slice(0, 8) ?? ''}「${title}」`)
+    },
+  },
+  {
+    name: 'tasks',
+    description: '任务列表与状态',
+    async handler(ctx) {
+      const list = await ctx.api.listTasks(ctx.state.activeChannelId)
+      ctx.state.tasks = list
+      const rows = list.slice(0, 20).map((t, i) => `  ${i + 1}. [${t.state}] ${t.title ?? t.taskId?.slice(0, 8)}${t.progress ? ` ${t.progress}%` : ''}`)
+      ctx.echo('system', `任务 ${list.length}:\n${rows.join('\n') || '  (无)'}`)
+    },
+  },
+  {
+    name: 'monitor',
+    usage: '<agent名|序号|off>',
+    description: '开/关右侧终端镜像面板(实时查看该 Agent 执行过程)',
+    async handler(ctx, args) {
+      const key = args.shift()
+      if (!key || key === 'off') {
+        ctx.actions.closeMonitor()
+        ctx.echo('system', '监控面板已关闭')
+        return
+      }
+      await ctx.actions.refreshAgents()
+      const agent = resolveAgent(ctx.state, key)
+      if (!agent) return ctx.echo('error', `成员不存在:${key}(/agents 查看)`)
+      ctx.actions.openMonitor(agent)
+    },
+  },
+  {
+    name: 'hitl',
+    usage: '[序号|off]',
+    description: '列出待人工处理事项;带序号进入作答;off 放弃作答',
+    async handler(ctx, args) {
+      const key = args.shift()
+      if (key === 'off') {
+        ctx.state.hitlAnswering = null
+        ctx.echo('system', '已放弃当前作答(对话框仍在待办中,可 /hitl 重进)')
+        return
+      }
+      if (key === undefined) {
+        const list = ctx.state.hitl.length > 0 ? ctx.state.hitl : await ctx.api.hitlPending(ctx.state.activeChannelId)
+        ctx.state.hitl = list
+        if (list.length === 0) return ctx.echo('system', '当前没有待人工处理的事项。')
+        const rows = list.map((it, i) => `  ${i + 1}. [${it.kind}] ${it.title} —— ${it.agentName}${it.expiresAt ? `(park 截止 ${it.expiresAt.slice(11, 19)})` : ''}`)
+        ctx.echo('warn', `待人工处理 ${list.length} 项:\n${rows.join('\n')}\n/hitl <序号> 进入作答。`)
+        return
+      }
+      const idx = Number.parseInt(key, 10) - 1
+      const item = ctx.state.hitl[idx]
+      if (!item) return ctx.echo('error', `序号无效:${key}(/hitl 查看列表)`)
+      ctx.state.hitlAnswering = item
+      ctx.echo('warn', `进入作答:${item.title} —— 完成输入回车提交,/hitl off 放弃。`)
+    },
+  },
+  {
+    name: 'quit',
+    description: '退出 TUI',
+    handler(ctx) {
+      ctx.actions.quit()
+    },
+  },
+]
+
+function resolveChannel(state, key) {
+  const byIdx = state.channels[Number.parseInt(key, 10) - 1]
+  return state.channels.find(c => c.name === key || c.id === key) ?? (Number.isInteger(Number.parseInt(key, 10)) ? byIdx : undefined)
+}
+
+function resolveAgent(state, key) {
+  const byIdx = state.agents[Number.parseInt(key, 10) - 1]
+  return state.agents.find(a => a.name === key || a.id === key) ?? (Number.isInteger(Number.parseInt(key, 10)) ? byIdx : undefined)
+}
+
+function parseConfigFlag(raw) {
+  if (!raw || raw === true) return undefined
+  try {
+    return JSON.parse(String(raw))
+  }
+  catch {
+    throw new Error(`--config 不是合法 JSON:${raw}`)
+  }
+}
+
+/** 命令分发(编辑器 onSubmit 入口;返回 true = 已作为命令消费) */
+export async function dispatchCommand(ctx, input) {
+  const parsed = parseCommand(input)
+  if (!parsed) return false
+  const cmd = commands.find(c => c.name === parsed.name)
+  if (!cmd) {
+    ctx.echo('error', `未知命令:/${parsed.name}(/help 查看命令列表)`)
+    return true
+  }
+  try {
+    await cmd.handler(ctx, parsed.args, parsed.flags)
+  }
+  catch (err) {
+    ctx.echo('error', `/${cmd.name} 失败:${err.message}`)
+  }
+  return true
+}
+
+/** pi-tui CombinedAutocompleteProvider 的命令表(斜杠补全;name 不带 '/'——
+ *  provider 把 '/' 当触发符自带,带了会在应用补全时拼出 '//cmd') */
+export function slashCommandCompletions() {
+  return commands.map(c => ({ name: c.name, description: c.description }))
+}

package/tui/components/chat-log.mjs

@@ -0,0 +1,42 @@
+// ============================================================
+// ChatLog 组件 —— 会话时间线(AEP 归约后的 log 行渲染)。
+// 每次 render 全量输出(有界 400 行),增量绘制由 TuiMainScreen 差分完成。
+// 输出经 truncateToWidth 兜底(CJK 宽字符行宽;pi-tui 对超宽行直接 crash)。
+// ============================================================
+import { theme } from '../theme.mjs'
+import { wrapTextWithAnsi, truncateToWidth } from '@earendil-works/pi-tui'
+
+const TONE_OF = {
+  'system': s => theme.faint(s),
+  'user': s => `${theme.info('◆ 你')} ${s}`,
+  'agent': s => `${theme.accent('◆ Agent')} ${s}`,
+  'stream': s => theme.faint(s),
+  'task': s => theme.info(s),
+  'hitl': s => theme.warn(s),
+  'hitl-resolved': s => theme.accent(s),
+  'error': s => theme.error(`✗ ${s}`),
+  'notice': s => theme.faint(`· ${s}`),
+  'monitor': s => s,
+}
+
+export class ChatLog {
+  constructor(state) {
+    this.state = state
+  }
+
+  render(width) {
+    const w = Math.max(width, 20)
+    const lines = []
+    for (const row of this.state.log) {
+      const paint = TONE_OF[row.kind] ?? (s => s)
+      const prefix = row.kind === 'agent' && row.agentName ? `${theme.faint(`[${row.agentName}]`)} ` : ''
+      const wrapped = wrapTextWithAnsi(paint(`${prefix}${row.text}`), w)
+      lines.push(...wrapped)
+    }
+    if (this.state.statusMsg && Date.now() - this.state.statusAt < 15_000) {
+      lines.push('')
+      lines.push(theme.faint(this.state.statusMsg))
+    }
+    return lines.map(l => truncateToWidth(l, w))
+  }
+}

package/tui/components/hitl-card.mjs

@@ -0,0 +1,36 @@
+// ============================================================
+// HitlCard —— 作答模式卡片(state.hitlAnswering 非空时渲染于输入框上方)。
+// 作答约定:confirm → y/n;select → 选项序号;input/editor → 自由文本;
+// /hitl off 放弃作答(等价 Esc)。提交经 POST /api/workshop/hitl/respond。
+// ============================================================
+import { theme } from '../theme.mjs'
+import { wrapTextWithAnsi, truncateToWidth } from '@earendil-works/pi-tui'
+
+const HINT = {
+  confirm: '输入 y 批准 / n 拒绝',
+  select: '输入选项序号(如 1)',
+  input: '输入回答文本',
+  editor: '输入回答文本',
+}
+
+export class HitlCard {
+  constructor(state) {
+    this.state = state
+  }
+
+  render(width) {
+    const item = this.state.hitlAnswering
+    if (!item) return []
+    const w = Math.max(width - 4, 20)
+    const lines = []
+    lines.push(theme.warn(`⏸ HITL 作答 · ${item.agentName} · ${item.kind === 'omp-dialog' ? 'omp 对话框' : '下发审批'}`))
+    lines.push(truncateToWidth(theme.bold(String(item.title ?? '')), w))
+    if (item.detail) lines.push(...wrapTextWithAnsi(theme.faint(item.detail), w))
+    if (item.message) lines.push(...wrapTextWithAnsi(String(item.message), w))
+    if (item.method === 'select' && Array.isArray(item.options)) {
+      item.options.forEach((opt, i) => lines.push(`  ${theme.accent(`${i + 1}.`)} ${opt}`))
+    }
+    lines.push(theme.faint(`${HINT[item.method] ?? '输入回答'} · /hitl off 放弃`))
+    return lines.map(l => truncateToWidth(l, Math.max(width, 20)))
+  }
+}