thincoder 0.7.7 → 0.8.0

package/src/tui/index.mjs

@@ -0,0 +1,330 @@
+/**
+ * tui.mjs — 裸 ANSI 终端 UI
+ * 零依赖：raw mode 键盘输入、ANSI 转义渲染、自研宽字符换行。
+ * 布局：header / 对话区 (可滚动）/ todo 面板 (有任务时）/ 输入框 / 状态栏。
+ *
+ * 大型逻辑块已拆到独立模块：
+ *   agent-turn.mjs    — agent 循环 + 回调构建
+ *   key-handler.mjs   — 键盘事件分发
+ *   startup.mjs       — 启动画面 + 会话恢复 + 后台索引
+ *   interaction.mjs   — 权限审批 + 问答
+ *   pickers.mjs       — 通用列表选择器 + 模型选择器
+ *   wizard.mjs        — 首次配置向导
+ *   slash-commands.mjs — 斜杠命令分发
+ *   config-helpers.mjs — persistRaw / syncProviderField / maskKey
+ *   clipboard.mjs     — 剪贴板图片粘贴
+ *   distill-cmd.mjs   — /distill 命令
+ */
+
+import { emitKeypressEvents } from "node:readline"
+import { PassThrough } from "node:stream"
+import { saveSession, archiveCurrent, listSlots } from "../session.mjs"
+import { closeAllMcp } from "../mcp.mjs"
+import { estimateTokens } from "../context.mjs"
+import { ansi, C } from "./ansi.mjs"
+import { renderFrame, countConvLines } from "./render-frame.mjs"
+import { computeLayout } from "./layout.mjs"
+import { SLASH_COMMANDS, createSlashCommands } from "./slash-commands.mjs"
+import { createWizard } from "./wizard.mjs"
+import { createPickers } from "./pickers.mjs"
+import { runDistill as runDistillImpl } from "./distill-cmd.mjs"
+import { createInteraction } from "./interaction.mjs"
+import { pasteClipboardImage as pasteClipboardImageImpl } from "./clipboard.mjs"
+import { runAgentTurn } from "./agent-turn.mjs"
+import { createKeyHandler } from "./key-handler.mjs"
+import { showStartup, backgroundIndex } from "./startup.mjs"
+import { createConfigHelpers } from "./config-helpers.mjs"
+
+/**
+ * 启动 TUI，接管终端直到退出。
+ * agent: createAgent 的返回值
+ * opts: { projectDir?, team?, author? } —— /distill 写入 project/team 层时用
+ */
+export async function startTUI(agent, opts = {}) {
+  if (!process.stdin.isTTY) {
+    throw new Error("TUI requires a TTY; use 'thincoder chat' for non-interactive use")
+  }
+
+  const distillOpts = opts
+
+  const state = {
+    lines: [], // 对话区行：{ text, color }
+    streaming: "", // current流式缓冲
+    input: [], // 输入缓冲区 (码点数组）
+    cursor: 0,
+    history: [],
+    historyIndex: -1,
+    scroll: 0, // 从底部向上的滚动行数
+    processing: false,
+    controller: null, // AbortController for current agent run
+    permission: null, // { name, args, resolve }
+    permissionPreview: [], // 权限审批的内容预览行 (渲染在输入框上方，不分隔）
+    question: null, // { text, options, resolve } — agent 的 question 工具回调
+    picker: null, // 模型选择器 { entries, lines, index, scroll, selectedLine }
+    wizard: null, // 首次Config向导 { step, index, scroll, selectedLine, fields, error, lines }
+    tasks: agent.tasks ?? [], // task 工具的任务列表 (状态栏显示进度）；会话恢复时直接带上，全完成自动收起
+    tokens: { prompt: 0, completion: 0, cacheHit: 0, cacheMiss: 0 }, // 累计 token 用量 (状态栏显示）
+    ctxCache: { len: -1, tokens: 0 }, // 上下文占用估算缓存 (estimateTokens 是 O(n)，history 变长才重算）
+    reasoning: "", // 思考流缓冲 (暗色展示）
+    completion: null, // Tab 补全状态 { candidates, index }
+    toolStreams: {}, // 各工具的实时输出 (按工具名隔离，并行工具互不串扰）
+    subTasks: {}, // 子 agent 面板：{ roleName: { role, text, done } }，每 role 一行，完成后标记 done 停留片刻
+    currentTool: null, // 正在执行的工具名 (状态栏显示）
+    processingStarted: 0, // 本轮处理开始时间 (状态栏计时）
+    status: "Ready",
+    queue: [], // 处理中排队的待执行消息：[{ text }]，处理完自动取下一条
+  }
+
+  // 恢复的会话如果所有任务completed，自动收起 todo 面板 (对齐运行时行为）
+  if (state.tasks.length > 0 && state.tasks.every((t) => t.status === "done")) {
+    state.tasks = []
+  }
+
+  // 输入流先过一道滤网：鼠标序列 (滚轮）在这里拦截处理，剥净后才交给 keypress 解析，
+  // 防止序列残片 (如 "64;72;42M"）漏进输入框
+  const keyStream = new PassThrough()
+  let mousePending = "" // 跨 chunk 的不完整鼠标序列尾部
+  let lastRenderedScroll = 0
+  emitKeypressEvents(keyStream)
+  process.stdin.setRawMode(true)
+  process.stdout.write(ansi.altBuffer + ansi.hideCursor + ansi.mouseOn)
+
+  process.stdin.on("data", (chunk) => {
+    let text = mousePending + chunk.toString("utf8")
+    mousePending = ""
+
+    // 滚轮：\x1b[<64;…M 上滚，\x1b[<65;…M 下滚 (每次 3 行）
+    for (const m of text.matchAll(/\x1b\[<(\d+);\d+;\d+([Mm])/g)) {
+      if (Number(m[1]) === 64) {
+        state.scroll += 3
+      } else if (Number(m[1]) === 65) {
+        state.scroll = Math.max(0, state.scroll - 3)
+      }
+    }
+
+    // 剥掉完整鼠标序列；不完整的尾部留到下一块数据再拼
+    text = text.replace(/\x1b\[<\d+;\d+;\d+[Mm]/g, "")
+    const tail = text.match(/\x1b\[<[\d;]*$/)
+    if (tail) {
+      mousePending = tail[0]
+      text = text.slice(0, -tail[0].length)
+    }
+
+    if (state.scroll !== lastRenderedScroll) {
+      lastRenderedScroll = state.scroll
+      render()
+    }
+    if (text) keyStream.write(text)
+  })
+
+  let cleanedUp = false
+  const cleanup = () => {
+    if (cleanedUp) return
+    cleanedUp = true
+    // 退出前保存会话 (同步写）；先归档current到槽位，再落新——不丢
+    try {
+      archiveCurrent(agent.cwd)
+      saveSession(agent, state.lines)
+    } catch {
+      // 存失败不耽误退出
+    }
+    // Off MCP stdio 子进程，不留孤儿
+    try {
+      closeAllMcp(agent)
+    } catch {
+      // 关不掉就算了，进程马上退出
+    }
+    process.stdin.setRawMode(false)
+    process.stdout.write(ansi.mouseOff + ansi.mainBuffer + ansi.showCursor + ansi.reset)
+  }
+  process.on("exit", cleanup)
+
+  const pushLine = (text, color) => {
+    state.lines.push({ text, color })
+    if (state.lines.length > 5000) state.lines.splice(0, 1000) // 防none限增长
+    render()
+  }
+
+  /** 消息块标签：空行 + 标签行。用户/助手消息之间留出呼吸空间 */
+  const pushLabel = (text, color) => {
+    if (state.lines.length > 0) state.lines.push({ text: "", color: C.dim })
+    state.lines.push({ text, color })
+    render()
+  }
+
+  // 每轮对话只打一次助手标签 (首个 token 或首个工具调用时）
+  let assistantLabeled = false
+  const ensureAssistantLabel = () => {
+    if (!assistantLabeled) {
+      assistantLabeled = true
+      pushLabel(`❯ ThinCoder:`, ansi.bold + C.assistant)
+    }
+  }
+
+  // ---------------------------------------------------------- 渲染
+
+  // 帧去重 + 流式限流：内容没变的帧不重写 (防闪屏）；token 洪流合并到 ~25fps
+  let lastFrame = ""
+  let renderTimer = null
+
+  function scheduleRender() {
+    if (renderTimer) return
+    renderTimer = setTimeout(() => {
+      renderTimer = null
+      render()
+    }, 40)
+  }
+
+  function render() {
+    // 副作用：scroll 归位 + ctxCache 更新 + overlay scroll 归位
+    // (renderFrame 是纯函数，副作用集中在此)
+    const dims = { cols: process.stdout.columns || 80, rows: process.stdout.rows || 24 }
+    const layout = computeLayout(state, dims)
+    // clamp conversation scroll
+    const convLines = countConvLines(state, dims.cols)
+    const maxScroll = Math.max(0, convLines - layout.panels.conversation.h)
+    state.scroll = Math.min(state.scroll, maxScroll)
+    // clamp overlay scroll
+    const overlay = state.picker ?? state.wizard
+    if (overlay && layout.panels.picker) {
+      const winH = layout.panels.picker.h - 1
+      if (overlay.selectedLine < overlay.scroll) overlay.scroll = overlay.selectedLine
+      if (overlay.selectedLine >= overlay.scroll + winH) overlay.scroll = overlay.selectedLine - winH + 1
+    }
+    // update ctxCache
+    if (state.ctxCache.len !== agent.history.length) {
+      state.ctxCache = { len: agent.history.length, tokens: estimateTokens(agent.history) }
+    }
+
+    const { frame, cursorRow, cursorCol } = renderFrame(state, agent, {
+      ...dims,
+      slashCommands: SLASH_COMMANDS,
+    })
+    if (frame !== lastFrame) {
+      lastFrame = frame
+      process.stdout.write(frame)
+    }
+    // 光标：输入态定位到输入框内；权限确认/菜单态时隐藏
+    if (state.permission || state.question || state.picker || state.wizard?.step === "provider") {
+      process.stdout.write(ansi.hideCursor)
+    } else {
+      process.stdout.write(`${"\x1b"}[${cursorRow};${cursorCol}H${ansi.showCursor}`)
+    }
+  }
+
+  process.stdout.on("resize", render)
+
+  // ---------------------------------------------------------- 提交
+
+  async function submit() {
+    const text = state.input.join("").trim()
+    if (!text) return
+    state.input = []
+    state.cursor = 0
+    state.history.push(text)
+    state.historyIndex = -1
+    state.scroll = 0
+
+    // 斜杠Commands：本地处理，不进入 agent
+    if (text.startsWith("/")) {
+      if (state.processing) {
+        // 处理中：只读命令（切换/查看/帮助）直接执行，有副作用的（清屏/新建/重建索引/提取）排队
+        const cmd0 = text.split(/\s+/)[0]
+        const ALIASES = { "/h": "/help", "/x": "/exit", "/m": "/model", "/p": "/plan", "/t": "/think", "/c": "/clear", "/n": "/new" }
+        const resolved0 = ALIASES[cmd0] ?? cmd0
+        const safeDuringProcessing = new Set(["/help", "/exit", "/model", "/think", "/config", "/skills", "/mcp", "/goal", "/session"])
+        if (safeDuringProcessing.has(resolved0)) {
+          await handleSlash(text)
+        } else {
+          state.queue.push({ text })
+          render()
+        }
+        return
+      }
+      await handleSlash(text)
+      return
+    }
+
+    // 处理中：入队等待，不立即执行
+    if (state.processing) {
+      state.queue.push({ text })
+      pushLabel(`❯ You: (queued #${state.queue.length})`, ansi.bold + C.user)
+      pushLine(text, C.dim)
+      render()
+      return
+    }
+
+    await turn(text)
+  }
+
+  // 交互原语：权限审批 + 问答输入，实现在 interaction.mjs
+  const { askPermission, askQuestion } = createInteraction({
+    agent, state, pushLine, pushLabel, render, summarize,
+  })
+
+  // 剪贴板图片粘贴：实现在 clipboard.mjs
+  const pasteClipboardImage = () => pasteClipboardImageImpl({ agent, state, pushLine, render })
+
+  // agent 循环：实现在 agent-turn.mjs
+  const turnCtx = {
+    agent, state, pushLine, pushLabel, render, scheduleRender, ensureAssistantLabel,
+    askPermission, askQuestion, handleSlash: null, summarize,
+    get assistantLabeled() { return assistantLabeled },
+    set assistantLabeled(v) { assistantLabeled = v },
+  }
+  const turn = (text) => runAgentTurn(turnCtx, text)
+
+  // ---------------------------------------------------------- 斜杠Commands
+
+  // 配置辅助：实现在 config-helpers.mjs
+  const { persistRaw, syncProviderField, maskKey } = createConfigHelpers(agent)
+
+  // 模型选择器 + 通用 picker：实现在 pickers.mjs
+  const { openPicker, closePicker, renderPickerLines, openModelPicker, setProviderKey } = createPickers({
+    agent, state, render, ansi, C, pushLine, pushLabel, persistRaw, askQuestion, maskKey,
+  })
+
+  // 初始 Config 向导：实现在 wizard.mjs，通过 ctx 传入闭包依赖
+  const { startWizard, renderWizard, wizardChooseProvider, wizardSubmitText, cancelWizard, wizardProviderItems } = createWizard({
+    agent, state, pushLine, pushLabel, render, persistRaw,
+    openModelPicker: () => openModelPicker(),
+  })
+
+  // /distill: impl in distill-cmd.mjs, ctx-passed
+  const runDistill = () => runDistillImpl({ agent, state, pushLine, render, askPermission, distillOpts })
+
+  // 斜杠命令分发、Tab 补全：实现在 slash-commands.mjs，通过 ctx 传入闭包依赖
+  const { handleSlash, completions, handleTab } = createSlashCommands({
+    agent, state, distillOpts,
+    pushLine, pushLabel, render,
+    openPicker, askQuestion, askPermission,
+    persistRaw, syncProviderField, maskKey,
+    openModelPicker: () => openModelPicker(),
+    setProviderKey,
+    runDistill,
+    exit: () => { cleanup(); setTimeout(() => process.exit(0), 100) },
+  })
+  // handleSlash 被 turnCtx 引用（循环依赖：submit → turn → handleSlash），在此回填
+  turnCtx.handleSlash = handleSlash
+
+  // ---------------------------------------------------------- 键盘 / 鼠标
+
+  // keypress 挂在过滤后的 keyStream 上：鼠标序列已在上游滤网中处理并剥除
+  const onKeypress = createKeyHandler({
+    agent, state, render, closePicker, renderPickerLines,
+    handleSlash, handleTab, submit, pasteClipboardImage,
+    wizardChooseProvider, wizardSubmitText, cancelWizard, wizardProviderItems,
+    renderWizard, pushLine, cleanup,
+  })
+  keyStream.on("keypress", onKeypress)
+
+  // ---------------------------------------------------------- 启动画面 + 后台索引
+
+  showStartup({ agent, state, opts, pushLine, pushLabel, render, startWizard })
+  backgroundIndex({ agent, state, render })
+}
+
+function summarize(obj) {
+  const s = JSON.stringify(obj)
+  return s.length > 80 ? s.slice(0, 80) + "…" : s
+}

package/src/tui/interaction.mjs

@@ -0,0 +1,79 @@
+import { ansi, C } from "./ansi.mjs"
+
+/** 交互原语：权限审批 + 问答输入。
+ *  从 index.mjs 抽出，通过 createInteraction(ctx) 接收闭包依赖。
+ *  ctx: { agent, state, pushLine, pushLabel, render, summarize } */
+export function createInteraction(ctx) {
+  const { agent, state, pushLine, pushLabel, render, summarize } = ctx
+
+  /** 权限请求的关键信息 (按工具定制），返回行数组。name 可能带子 agent 前缀 ("coder/bash"），取基名匹配 */
+  function formatPermission(name, args) {
+    const cap = (s, n = 1000) => (s.length > n ? `${s.slice(0, n)}…(${s.length} chars total)` : s)
+    const base = name.includes("/") ? name.split("/").pop() : name
+    if (base === "bash") return cap(args.command ?? "").split("\n")
+    if (base === "write") {
+      // 批准写文件必须看得到要写什么：路径 + 内容预览
+      return [`${args.path} (write ${(args.content ?? "").length} chars)`, ...cap(args.content ?? "", 1000).split("\n")]
+    }
+    if (base === "edit") {
+      // 简易 diff：- 旧内容 / + 新内容
+      return [
+        `${args.path}`,
+        ...cap(args.old_string ?? "", 500).split("\n").map((l) => `- ${l}`),
+        "  ↓",
+        ...cap(args.new_string ?? "", 500).split("\n").map((l) => `+ ${l}`),
+      ]
+    }
+    if (base === "apply_patch") {
+      // 补丁本身就是可读的 diff，直接预览
+      return cap(args.patch ?? "", 1500).split("\n")
+    }
+    if (base === "delete") return [`${args.path}${args.force ? " (force: also delete tracked files)" : ""}`]
+    if (base === "subagent") return cap(args.task ?? "", 500).split("\n")
+    if (base === "memory_put") return [`[${args.type ?? ""}] ${args.title ?? ""}`, ...cap(args.content ?? "", 500).split("\n")]
+    return [cap(summarize(args), 300)]
+  }
+
+  function askPermission(name, args) {
+    // auto 模式：完全授权，不再询问
+    if (agent.autoApprove) {
+      pushLine(`  [auto] ${name} ${summarize(args)}`, C.warn)
+      return Promise.resolve(true)
+    }
+    // 预览内容存到 permissionPreview，渲染在输入框上方紧挨"Allow?"提示
+    state.permissionPreview = formatPermission(name, args)
+    return new Promise((resolve) => {
+      state.permission = { name, args, resolve }
+      state.status = `Waiting: ${name}`
+      render()
+    })
+  }
+
+  function askQuestion(text, options = []) {
+    // 一次只能问一个：question 是只读工具走并行通道，同批第二个直接驳回，
+    // 否则后到的会覆盖 state.question，先到的 Promise 永远悬挂 (agent 死等）
+    if (state.question) {
+      return Promise.resolve("(error: another question is pending; ask one at a time and wait for the answer)")
+    }
+    if (!options.length) {
+      // 自由文本：打开输入态让用户打字，Enter 提交
+      pushLabel(`❯ Question`, ansi.bold + C.tool)
+      for (const line of text.split("\n")) pushLine(`  ${line}`, C.text)
+      return new Promise((resolve) => {
+        state.question = { text, options: [], resolve }
+        state.status = "Waiting for answer..."
+        render()
+      })
+    }
+    // 选项模式：输入框内显示列表，方向键选，Enter 确认
+    pushLabel(`❯ Question`, ansi.bold + C.tool)
+    for (const line of text.split("\n")) pushLine(`  ${line}`, C.text)
+    return new Promise((resolve) => {
+      state.question = { text, options, selected: 0, resolve }
+      state.status = "Waiting for choice..."
+      render()
+    })
+  }
+
+  return { askPermission, askQuestion, formatPermission }
+}

package/src/tui/key-handler.mjs

@@ -0,0 +1,267 @@
+import { ansi, C } from "./ansi.mjs"
+
+/** 键盘事件分发：权限确认 / 问答 / picker / wizard / 编辑 / 翻页 / 历史 / 粘贴。
+ *  从 index.mjs 抽出。
+ *  ctx: { agent, state, render, renderPickerLines, closePicker,
+ *         handleSlash, handleTab, submit, pasteClipboardImage,
+ *         wizardChooseProvider, wizardSubmitText, cancelWizard, wizardProviderItems,
+ *         renderWizard, pushLine, cleanup } */
+export function createKeyHandler(ctx) {
+  const { agent, state, render, closePicker, renderPickerLines, handleSlash, handleTab, submit, pasteClipboardImage, wizardChooseProvider, wizardSubmitText, cancelWizard, wizardProviderItems, renderWizard, pushLine, cleanup } = ctx
+
+  return function onKeypress(str, key = {}) {
+    // 权限确认态：y 批准 / n 拒绝 / a 批准并On AUTO (后续不再询问）
+    if (state.permission) {
+      const answer = (str || "").toLowerCase()
+      const isContinue = state.permission.name === "continue"
+      const validKeys = isContinue ? ["y", "n"] : ["y", "n", "a"]
+      if (validKeys.includes(answer) || key.name === "escape") {
+        const { resolve, name } = state.permission
+        state.permission = null
+        state.permissionPreview = []
+        state.status = "Processing..."
+        if (answer === "a" && !isContinue) {
+          agent.autoApprove = true
+          agent._pendingReminders = agent._pendingReminders ?? []
+          agent._pendingReminders.push("[System reminder: AUTO mode is now ON. All tool calls are automatically approved. Use /auto to disable.]")
+          pushLine(`  [auto] AUTO ON: tool calls no longer prompt for approval (/auto to disable)`, C.warn)
+        }
+        const approved = answer === "y" || (answer === "a" && !isContinue)
+        // 决定落痕：对话区留下批准/拒绝记录 (continue 询问有自己的输出，不重复记）
+        if (!isContinue) {
+          pushLine(`  [${approved ? "approved" : "denied"}] ${name}`, approved ? C.dim : C.error)
+        }
+        resolve(approved)
+        render()
+      }
+      return
+    }
+
+    // question 工具回调：自由文本 / 选项选择
+    if (state.question) {
+      const q = state.question
+      if (q.options.length > 0) {
+        // 选项模式：↑↓ 选择，Enter 确认，Esc 取消
+        if (key.name === "escape") {
+          q.resolve("(cancelled)")
+          state.question = null
+          state.status = "Processing..."
+          render()
+        } else if (key.name === "up") {
+          q.selected = Math.max(0, (q.selected ?? 0) - 1)
+          render()
+        } else if (key.name === "down") {
+          q.selected = Math.min(q.options.length - 1, (q.selected ?? 0) + 1)
+          render()
+        } else if (key.name === "return") {
+          const answer = q.options[q.selected ?? 0]
+          q.resolve(answer)
+          state.question = null
+          state.status = "Processing..."
+          pushLine(`  → ${answer}`, C.tool)
+          render()
+        }
+      } else {
+        // 自由文本：键入答案，Enter 提交，Esc 取消
+        if (key.name === "escape") {
+          q.resolve("(cancelled)")
+          state.question = null
+          state.status = "Processing..."
+          render()
+        } else if (key.name === "return") {
+          const answer = (q.answer ?? "").trim()
+          q.resolve(answer || "(empty answer)")
+          state.question = null
+          state.status = "Processing..."
+          pushLine(`  → ${answer || "(empty)"}`, C.tool)
+          render()
+        } else if (key.name === "backspace") {
+          q.answer = (q.answer ?? "").slice(0, -1)
+          render()
+        } else if (str && !key.ctrl && !key.meta) {
+          q.answer = (q.answer ?? "") + str
+          render()
+        }
+      }
+      return
+    }
+
+    if (key.ctrl && key.name === "c") {
+      if (state.processing && state.controller) {
+        state.controller.abort()
+        pushLine("[Aborting…]", C.warn)
+        render()
+        return
+      }
+      cleanup()
+      setTimeout(() => process.exit(0), 100)
+    }
+
+    // 通用列表选择器：↑↓ 移动，Enter 确认，Esc 取消
+    if (state.picker) {
+      const items = state.picker?.entries.filter((e) => e.type === "item") ?? []
+      if (key.name === "escape") {
+        closePicker()
+      } else if (key.name === "up" && items.length) {
+        state.picker.index = (state.picker.index - 1 + items.length) % items.length
+        renderPickerLines()
+      } else if (key.name === "down" && items.length) {
+        state.picker.index = (state.picker.index + 1) % items.length
+        renderPickerLines()
+      } else if (key.name === "return" && items.length) {
+        const selected = items[state.picker.index]
+        const handler = state.picker.onSelect
+        state.picker = null // 先关 picker，避免 onSelect 内部 render 时 picker 还在
+        // onSelect 是 async（如删 provider 要写文件），用 catch 兜住错误不被吞
+        Promise.resolve(handler?.(selected)).catch((err) => {
+          pushLine(`[error] ${err.message}`, C.error)
+        }).finally(() => render())
+      }
+      return
+    }
+
+    // 初始Config向导：菜单步 ↑↓/Enter/Esc；文本步 Enter 提交、Esc 取消，编辑键落到正常输入
+    if (state.wizard) {
+      const w = state.wizard
+      if (key.name === "escape") {
+        cancelWizard()
+        return
+      }
+      if (w.step === "provider") {
+        const items = wizardProviderItems()
+        if (key.name === "up" && items.length) {
+          w.index = (w.index - 1 + items.length) % items.length
+          renderWizard()
+        } else if (key.name === "down" && items.length) {
+          w.index = (w.index + 1) % items.length
+          renderWizard()
+        } else if (key.name === "return" && items.length) {
+          wizardChooseProvider(items[w.index])
+        }
+        return
+      }
+      if (key.name === "return") {
+        wizardSubmitText()
+        return
+      }
+      // 文本步骤屏蔽翻页/历史，其余编辑键放行到下面的普通输入逻辑
+      if (key.name === "up" || key.name === "down" || key.name === "pageup" || key.name === "pagedown") return
+    }
+
+    // 翻页
+    if (key.name === "pageup") {
+      state.scroll += Math.max(1, (process.stdout.rows || 24) - 8)
+      render()
+      return
+    }
+    if (key.name === "pagedown") {
+      state.scroll = Math.max(0, state.scroll - Math.max(1, (process.stdout.rows || 24) - 8))
+      render()
+      return
+    }
+
+    if (state.processing) {
+      // 处理中允许输入（排队），但屏蔽方向键历史和 Tab 补全
+      if (key.name === "tab" || key.name === "up" || key.name === "down") return
+      // Ctrl+D：删除队列中最后一条
+      if (key.ctrl && key.name === "d") {
+        if (state.queue.length > 0) {
+          state.queue.pop()
+          render()
+        }
+        return
+      }
+      // 其余可打印字符正常进入输入框
+    }
+
+    // Tab：斜杠Commands补全 (循环候选）；其余输入忽略 (\t 会顶破输入框，永不直接插入）
+    if (key.name === "tab") {
+      handleTab()
+      return
+    }
+
+    // 输入历史
+    if (key.name === "up") {
+      if (state.history.length) {
+        state.historyIndex = state.historyIndex === -1 ? state.history.length - 1 : Math.max(0, state.historyIndex - 1)
+        state.input = [...state.history[state.historyIndex]]
+        state.cursor = state.input.length
+        render()
+      }
+      return
+    }
+    if (key.name === "down") {
+      if (state.historyIndex !== -1) {
+        state.historyIndex++
+        if (state.historyIndex >= state.history.length) {
+          state.historyIndex = -1
+          state.input = []
+        } else {
+          state.input = [...state.history[state.historyIndex]]
+        }
+        state.cursor = state.input.length
+        render()
+      }
+      return
+    }
+
+    // 光标移动
+    if (key.name === "left") {
+      state.cursor = Math.max(0, state.cursor - 1)
+      render()
+      return
+    }
+    if (key.name === "right") {
+      state.cursor = Math.min(state.input.length, state.cursor + 1)
+      render()
+      return
+    }
+    if (key.name === "home") {
+      state.cursor = 0
+      render()
+      return
+    }
+    if (key.name === "end") {
+      state.cursor = state.input.length
+      render()
+      return
+    }
+
+    // 编辑
+    if (key.name === "backspace") {
+      if (state.cursor > 0) {
+        state.input.splice(state.cursor - 1, 1)
+        state.cursor--
+        render()
+      }
+      return
+    }
+    if (key.name === "delete") {
+      if (state.cursor < state.input.length) {
+        state.input.splice(state.cursor, 1)
+        render()
+      }
+      return
+    }
+    if (key.name === "return") {
+      submit().catch((e) => pushLine(`[error] ${e.message}`, C.error))
+      return
+    }
+
+    // Ctrl+V (Unix) / Alt+V (Windows)：粘贴剪贴板图片 → 存临时文件 → 输入框插入 read_image
+    const isPasteImage = (key.name === "v" && (key.ctrl || key.meta)) || (key.name === "v" && key.alt)
+    if (isPasteImage) {
+      pasteClipboardImage(agent).catch((e) => pushLine(`[error] ${e.message}`, C.error))
+      return
+    }
+
+    // 可打印字符 / 粘贴 (str 可能一次多个字符）；Tab 一律转成两个空格 (\t 显示宽度不定，会顶破输入框）
+    // \r\n 在 Windows raw mode 下可能漏进来冲乱页面
+    if (str && !key.ctrl && !key.meta) {
+      const chars = [...str.replace(/[\r\n]+/g, "").replace(/\t/g, "  ")]
+      state.input.splice(state.cursor, 0, ...chars)
+      state.cursor += chars.length
+      render()
+    }
+  }
+}