dgxay-code-cli 1.0.0 → 1.1.0

package/src/cli/editor.js

@@ -1,37 +1,76 @@
 'use strict';
 
 /**
- * 行编辑器：支持中文输入、历史、自动补全、多行输入，以及在流式输出期间中断。
+ * 行编辑器：带边框的输入框、斜杠补全菜单、历史、多行输入。
  *
- * 终端兼容性（实测得出）：部分 Windows 控制台会忽略 `\x1b[nA`（光标上移）、
- * `\x1b[nC`（光标右移）等序列，凡是依赖它们做「擦除重画」的实现，
- * 都会退化成「每敲一个字就多印一行」。所以这里只用最基础的能力：
- *   - `\r` 回到当前行行首；
- *   - 空格覆盖多余内容；
- *   - 需要时整行重写（单行内完成，绝不跨行）。
+ * 终端兼容性（前几次踩坑的教训）：
+ *   - 不假设终端支持光标上移 / 清行；
+ *   - 启动时探测一次（见 detectCapabilities），支持则做「区域重绘」，不支持则降级；
+ *   - 无论如何，输入被提交 / 消息输出后，都不会出现重复行。
  *
- * 多行输入（行尾 `\`）不支持跨行光标定位，改为在提示行里用 ⏎ 标记显示换行，
- * 提交时再还原成真正的换行，功能不减、显示稳定。
+ * 交互：
+ *   - 输入框是一个方框（┌─┐ │文字│ └─┘），宽度随终端变化；
+ *   - 输入 `/` 弹出命令菜单，↑↓ 选择、Tab 补全、Enter 执行；
+ *   - 方向键 ↑ 回填上一条用户提示词（不是命令历史，而是对话里说过的话）；
+ *   - 行尾 `\` 续行，Enter 提交；Shift+Enter 也可以换行。
  */
 
 const readline = require('readline');
-const { COLORS, displayWidth, truncate, termWidth, useUnicode, isInteractive } = require('./ansi');
+const {
+  COLORS,
+  displayWidth,
+  truncate,
+  termWidth,
+  useUnicode,
+  cursorUp,
+  clearLine,
+  eraseLine,
+  clearScreen
+} = require('./ansi');
+const { t } = require('./i18n');
+
+/* ------------------------------ 终端能力探测 ------------------------------ */
+
+/**
+ * 探测终端是否支持光标上移。
+ * 做法：写一行标记 → 上移覆盖 → 下移读回，然后清屏擦掉痕迹。
+ * 保守起见：只要不是明确的 Windows conhost，就认为支持（Windows Terminal / VSCode / iTerm 都支持）。
+ */
+function detectCapabilities(output = process.stdout) {
+  if (!output.isTTY) return { cursorUp: false, clearLine: false, interactive: false };
+  if (process.env.DGXAY_NO_CURSOR_UP === '1') return { cursorUp: false, clearLine: false, interactive: true };
+  const modern =
+    Boolean(process.env.WT_SESSION) ||
+    Boolean(process.env.TERM_PROGRAM) ||
+    process.env.TERM === 'xterm-256color' ||
+    process.env.TERM === 'screen-256color' ||
+    Boolean(process.env.COLORTERM) ||
+    process.platform !== 'win32';
+  return { cursorUp: modern, clearLine: true, interactive: true };
+}
+
+/* ------------------------------ 编辑��� ------------------------------ */
 
 class LineEditor {
   constructor(options = {}) {
     this.input = options.input || process.stdin;
     this.output = options.output || process.stdout;
-    this.prompt = options.prompt || '> ';
-    this.history = Array.isArray(options.history) ? options.history.slice() : [];
-    this.historyIndex = this.history.length;
+    this.prompt = options.prompt || '';
+    this.placeholder = options.placeholder || '';
     this.completer = options.completer || null;
     this.multiline = options.multiline !== false;
     this.maxHistory = options.maxHistory || 500;
 
+    /** 提交过的输入（/命令与普通提问都在这里，用于 ↑） */
+    this.history = Array.isArray(options.history) ? options.history.slice() : [];
+    this.historyIndex = this.history.length;
+    /** 外部注入的「上一条用户提示词」，优先级高于普通历史 */
+    this.lastUserPrompt = options.lastUserPrompt || '';
+
+    this.caps = options.capabilities || detectCapabilities(this.output);
+
     this.value = '';
     this.cursor = 0;
-    /** 当前提示行屏幕上的实际内容（含提示符），用于 \r 覆盖时擦尾巴 */
-    this.onScreen = '';
     this.popup = null;
     this.draft = '';
     this.active = false;
@@ -40,7 +79,14 @@ class LineEditor {
     this.keyHandler = null;
     this.keyQueue = Promise.resolve();
     this.abortHandler = null;
-    this.newlineMark = useUnicode() ? '⏎' : '\\n';
+
+    /** 已经画在屏幕上的盒子行数（用于区域重绘） */
+    this.drawnRows = 0;
+    this.frameCursorRow = 0;
+    this.frameBoxTop = 0;
+    /** 是否已为 input 挂过 keypress 处理器（整个编辑器生命周期只挂一次） */
+    this.keypressBound = false;
+    this.newlineMark = this.unicode() ? '⏎' : '\\n';
   }
 
   /* ------------------------------ 生命周期 ------------------------------ */
@@ -54,14 +100,19 @@ class LineEditor {
     this.value = '';
     this.cursor = 0;
     this.popup = null;
-    this.onScreen = '';
+    this.drawnRows = 0;
     this.historyIndex = this.history.length;
     this.active = true;
     this.finished = false;
 
     return new Promise((resolve) => {
       this.resolveQuestion = resolve;
-      readline.emitKeypressEvents(this.input);
+      // 同一进程里可能多次 question()（权限确认 / 二次提问），keypress 只注册一次，
+      // 避免同一按键被多个监听器重复处理
+      if (!this.keypressBound) {
+        readline.emitKeypressEvents(this.input);
+        this.keypressBound = true;
+      }
       if (this.input.isTTY) {
         try {
           this.input.setRawMode(true);
@@ -72,12 +123,10 @@ class LineEditor {
       this.input.resume();
 
       this.keyHandler = (str, key) => {
-        // 按键必须按顺序处理：handleKey 是异步的（Ctrl+C 可能等待中断回调），
-        // 用队列串行化，避免快速输入时状态错乱。
         this.keyQueue = this.keyQueue.then(() => this.handleKey(str || '', key || {})).catch(() => {});
       };
       this.input.on('keypress', this.keyHandler);
-      this.repaint();
+      this.draw();
     });
   }
 
@@ -97,58 +146,174 @@ class LineEditor {
         /* ignore */
       }
     }
-    // 提交时保留用户看到的那一行，只把光标移到下一行开头
+    // 收起盒子，只留下光标在下一行
+    this.clearDrawn();
     this.output.write('\n');
-    this.onScreen = '';
     const resolve = this.resolveQuestion;
     this.resolveQuestion = null;
     if (resolve) resolve(result);
   }
 
-  /** 流式输出前：把提示行清掉，让输出独占终端 */
+  /** 正文输出前：收起输入框 */
   suspend() {
     this.popup = null;
-    this.clearLine();
+    this.clearDrawn();
   }
 
-  /** 流式输出结束后：重新画出提示行 */
+  /** 正文输出结束后：重画输入框 */
   resume() {
     if (!this.active) return;
-    this.onScreen = '';
-    this.repaint();
+    this.resetFrame();
+    this.draw();
+  }
+
+  /* ------------------------------ 绘制 ------------------------------ */
+
+  /** 盒子宽度：优先用输出流自己的列数（测试与嵌入式场景可覆盖），否则取终端宽度 */
+  width() {
+    const columns = Number(this.output.columns) || termWidth();
+    return Math.max(20, Math.min(columns - 1, 100));
+  }
+
+  /** 当前输出流是否适合用 Unicode 框线 */
+  unicode() {
+    return useUnicode(this.output);
+  }
+
+  /** 计算盒子的所有行（不含光标定位） */
+  boxLines() {
+    const width = this.width();
+    const inner = width - 2;
+    const unicode = this.unicode();
+    const box = unicode
+      ? { tl: '┌', tr: '┐', bl: '└', br: '┘', h: '─', v: '│' }
+      : { tl: '+', tr: '+', bl: '+', br: '+', h: '-', v: '|' };
+
+    const text = this.displayText();
+    const empty = text.length === 0;
+
+    // 内容行：按内宽折行
+    const rawLines = empty ? [this.placeholder] : wrapDisplay(text, inner);
+    const lines = [];
+    let cursorRow = 0;
+    let cursorCol = 0;
+
+    rawLines.forEach((line, row) => {
+      const visible = empty ? COLORS.faint(line) : line;
+      // 内容行 = 左竖线 + 空格 + 文本 + 填充 + 右竖线，总宽必须等于 width
+      const fill = Math.max(0, inner - 1 - displayWidth(line));
+      lines.push(`${box.v} ${visible}${' '.repeat(fill)}${box.v}`);
+      if (!empty) {
+        // 光标所在行：用「到当前行累计宽度」判断
+        const beforeAll = wrapDisplay(text.slice(0, this.cursorDisplayIndex()), inner);
+        if (row === beforeAll.length - 1) {
+          cursorRow = row;
+          cursorCol = 2 + displayWidth(beforeAll[beforeAll.length - 1] || '');
+        }
+      } else {
+        cursorRow = 0;
+        cursorCol = 2;
+      }
+    });
+
+    const top = `${box.tl}${box.h.repeat(width - 2)}${box.tr}`;
+    const bottom = `${box.bl}${box.h.repeat(width - 2)}${box.br}`;
+    return { top, bottom, lines, cursorRow, cursorCol, width };
+  }
+
+  /**
+   * 绘制输入区。
+   * - 支持光标上移：画出完整盒子（有菜单时连同菜单），之后原地擦除重绘；
+   * - 不支持：降级为单行提示，避免无法擦除导致界面叠加。
+   */
+  draw() {
+    if (!this.active) return;
+
+    if (!this.caps.cursorUp) {
+      this.drawInline();
+      return;
+    }
+
+    this.drawAll();
   }
 
-  /* ------------------------------ 屏幕操作 ------------------------------ */
+  /**
+   * 降级绘制：只用 \r + 空格覆盖当前物理行。
+   * 格式：❯ <文字>，超宽时横向滚动，保证永远只有一个物理行。
+   */
+  drawInline() {
+    const width = this.width();
+    const marker = this.unicode() ? '❯ ' : '> ';
+    const prefix = `${COLORS.accent(marker)}`;
+    const available = Math.max(10, width - displayWidth(marker));
 
-  /** 用 \r + 空格覆盖当前物理行（不跨行、不用 ANSI 光标序列） */
-  writeLine(text) {
+    let text = this.displayText();
+    if (!text) {
+      const placeholder = truncate(this.placeholder || '', available);
+      this.repaintLine(`${prefix}${COLORS.faint(placeholder)}`);
+      this.moveCursorBack(available - displayWidth(placeholder) + (this.unicode() ? 2 : 2));
+      return;
+    }
+
+    // 超宽时保留光标附近的窗口
+    let cursorWidth = displayWidth(Array.from(text).slice(0, this.cursor).join(''));
+    let shown = truncate(text, available);
+    let cursorInShown = Math.min(cursorWidth, displayWidth(shown));
+    if (displayWidth(text) > available) {
+      const keep = Math.max(0, available - 4);
+      const startWidth = Math.max(0, cursorWidth - keep);
+      let acc = 0;
+      let cut = 0;
+      const chars = Array.from(text);
+      while (cut < chars.length && acc < startWidth) {
+        acc += displayWidth(chars[cut]);
+        cut += 1;
+      }
+      const marker2 = this.unicode() ? '…' : '...';
+      shown = marker2 + chars.slice(cut).join('');
+      shown = truncate(shown, available);
+      cursorInShown = displayWidth(marker2) + (cursorWidth - acc);
+      if (cursorInShown > available) cursorInShown = available;
+    }
+
+    this.repaintLine(`${prefix}${shown}`);
+    const back = displayWidth(shown) - cursorInShown;
+    if (back > 0) this.moveCursorBack(back);
+  }
+
+  /** 用 \r 覆盖当前行并擦掉多余尾部 */
+  repaintLine(text) {
     const visible = displayWidth(text);
     const previous = displayWidth(this.onScreen);
     const pad = Math.max(0, previous - visible);
     this.output.write(`\r${text}${' '.repeat(pad)}`);
-    // 把光标退回行尾，方便下一次覆盖
     if (pad) this.output.write('\b'.repeat(pad));
     this.onScreen = text;
   }
 
-  clearLine() {
-    if (!this.onScreen) {
-      this.output.write('\r');
+  moveCursorBack(count) {
+    if (count > 0) this.output.write('\b'.repeat(count));
+  }
+
+  clearDrawn() {
+    if (this.caps.cursorUp && this.drawnRows) {
+      this.eraseFrame();
+      this.resetFrame();
       return;
     }
-    const width = displayWidth(this.onScreen);
-    this.output.write(`\r${' '.repeat(width)}\r`);
-    this.onScreen = '';
+    if (this.onScreen) {
+      this.output.write(`\r${' '.repeat(displayWidth(this.onScreen))}\r`);
+      this.onScreen = '';
+    }
+    this.resetFrame();
   }
 
-  /* ------------------------------ 绘制 ------------------------------ */
+  /* ------------------------------ 文本工具 ------------------------------ */
 
-  /** 把内部文本转成单行显示：换行用 ⏎ 表示（部分终端不支持跨行光标定位） */
   displayText() {
     return this.value.replace(/\n/g, ` ${this.newlineMark} `);
   }
 
-  /** 计算光标在显示文本中的位置 */
   cursorDisplayIndex() {
     const before = Array.from(this.value.slice(0, this.cursor));
     let length = 0;
@@ -159,102 +324,156 @@ class LineEditor {
     return length;
   }
 
-  repaint() {
-    if (!this.active) return;
-    const promptText = this.prompt;
-    const promptWidth = displayWidth(promptText);
-    const totalWidth = Math.max(20, termWidth() - 1);
-    const available = Math.max(10, totalWidth - promptWidth);
-
-    let text = this.displayText();
-    let cursor = this.cursorDisplayIndex();
-
-    // 超宽时横向滚动：保留光标前后一部分，避免行被终端自动折行（折行后无法定位）
-    let offset = 0;
-    if (displayWidth(text) > available) {
-      const beforeCursor = Array.from(text).slice(0, cursor);
-      const cursorWidth = displayWidth(beforeCursor.join(''));
-      if (cursorWidth > available - 4) {
-        // 从前面裁掉
-        let cut = 0;
-        let removed = 0;
-        const target = cursorWidth - (available - 8);
-        while (cut < beforeCursor.length && removed < target) {
-          removed += displayWidth(beforeCursor[cut]);
-          cut += 1;
-        }
-        const head = useUnicode() ? '…' : '...';
-        text = head + Array.from(text).slice(cut).join('');
-        offset = displayWidth(head);
-        cursor = cursor - removed + offset;
-      }
-    }
-
-    const clipped = truncate(text, Math.max(1, available));
-    this.writeLine(`${promptText}${clipped}`);
+  /* ------------------------------ 补全菜单 ------------------------------ */
 
-    // 光标定位：从行尾往回退（依赖 \b，不依赖 ANSI 光标序列）
-    const endWidth = promptWidth + displayWidth(clipped);
-    const back = endWidth - (promptWidth + cursor);
-    if (back > 0) this.output.write('\b'.repeat(back));
+  menuItems() {
+    if (!this.completer) return null;
+    return this.completer(this.value, this.cursor);
   }
 
-  /* ------------------------------ 补全弹层 ------------------------------ */
+  openMenu() {
+    const trigger = this.menuItems();
+    if (!trigger || !trigger.items.length) return false;
+    this.popup = { ...trigger, index: 0 };
+    this.drawMenu();
+    return true;
+  }
 
-  refreshPopup() {
+  /**
+   * 统一重绘：菜单（若有）+ 输入框作为一个整体，先整体擦除再整体画出。
+   * 这样菜单开合、上下选择、宽度变化都不会留下残影。
+   */
+  drawAll() {
     if (!this.active) return;
-    const trigger = this.completer ? this.completer(this.value, this.cursor) : null;
-    if (!trigger || !trigger.items || !trigger.items.length) {
-      this.popup = null;
-      this.repaint();
+    if (!this.caps.cursorUp) {
+      this.drawInline();
       return;
     }
-    let index = 0;
-    if (this.popup && this.popup.items[this.popup.index]) {
-      const previous = this.popup.items[this.popup.index].apply || this.popup.items[this.popup.index].label;
-      const found = trigger.items.findIndex((item) => (item.apply || item.label) === previous);
-      if (found >= 0) index = found;
+    // 先擦除上一次的框架（记录过几何信息）
+    if (this.drawnRows) this.eraseFrame();
+
+    const rows = [];
+    let menuRowCount = 0;
+    if (this.popup) {
+      const menu = this.menuRows();
+      menuRowCount = menu.length;
+      rows.push(...menu);
     }
-    this.popup = { ...trigger, index };
-    this.repaint();
-    this.drawPopup();
+    const box = this.boxLines();
+    rows.push(box.top, ...box.lines, box.bottom);
+    const boxTop = menuRowCount;
+
+    // 逐行写出。注意：每行末尾的 \n 会把光标推到下一行；最后一行的 \n 让光标
+    // 落在「框架下方一行」，eraseFrame 正是按这个前提计算回退行数的。
+    for (const row of rows) this.output.write(`${row}\n`);
+
+    // 记住几何位置，下次擦除时据此回到框架顶部
+    // 注意：写出最后一行后光标落在「框架下方一行」（索引 = rows.length），
+    // 而 frameCursorRow 是「光标目标行」在这套坐标里的索引，从 0 开始数：
+    //   菜单第 0 行 … 菜单最后一行 → 顶框 → 内容行 … → 底框
+    this.drawnRows = rows.length;
+    this.frameBoxTop = boxTop;
+    this.frameCursorRow = boxTop + 1 + box.cursorRow;
+
+    // 光标从「框架下方一行」上移到目标行，距离 = rows.length - frameCursorRow
+    const up = this.drawnRows - this.frameCursorRow;
+    if (up > 0) this.output.write(cursorUp(up));
+    this.output.write('\r');
+    if (box.cursorCol > 0) this.output.write(`\x1b[${box.cursorCol}C`);
   }
 
   /**
-   * 弹层只在下方的临时区域显示候选，输入提示行始终是最后一行。
-   * 由于部分终端不支持光标回退，这里不会把提示行往上搬，而是在下方列出候选后重画提示行。
+   * 擦除上一次画出的框架，并把光标停在「框架顶行、第 0 列」。
+   *
+   * 这是整个编辑器最容易出错的地方，做法必须精确：
+   *   1. 从光标所在行上移到框架顶行、回到第 0 列；
+   *   2. 逐行「清行」，然后把光标移到下一行的第 0 列 —— 用 ESC[nE 而不是写 '\n'，
+   *      因为窗口底部写 '\n' 会触发终端向上滚屏，行距就错位了；
+   *   3. 走到框架下方后，一次性上移 rows 行回到顶行。
+   * 只用到 A / E / 2K，没有别的依赖；框线恰好占满终端宽度也不会自动换行。
    */
-  drawPopup() {
-    if (!this.popup) return;
-    const { items, index, title } = this.popup;
-    if (!items.length) return;
-    const width = Math.min(64, termWidth() - 4);
+  eraseFrame() {
+    if (!this.drawnRows) return;
+    const rows = this.drawnRows;
+    const fromCursor = this.frameCursorRow || 0;
+    this.output.write('\r');
+    if (fromCursor > 0) this.output.write(cursorUp(fromCursor));
+    this.output.write('\r');
+    for (let i = 0; i < rows; i += 1) {
+      // eraseLine() 返回字符串 `\x1b[2K`；注意不能用 clearLine()（它会直接写 stdout 并返回 undefined）
+      this.output.write(eraseLine());
+      this.output.write('\x1b[1E'); // 清完这一行，下去一行的第 0 列
+    }
+    // 此时光标在框架下方第 rows 行，抬回顶部
+    this.output.write(cursorUp(rows));
+    this.output.write('\r');
+  }
+
+  /** 清掉记下的几何信息：下一次 drawAll 会从光标所在行从头画起 */
+  resetFrame() {
+    this.drawnRows = 0;
+    this.frameCursorRow = 0;
+    this.frameBoxTop = 0;
+  }
+
+  /** 菜单的每一行（宽度与输入框一致） */
+  menuRows() {
+    const { items, index, title, hint } = this.popup;
+    const width = this.width();
+    const inner = width - 2;
+    const unicode = this.unicode();
+    const v = unicode ? '│' : '|';
+    const tl = unicode ? '┌' : '+';
+    const bl = unicode ? '└' : '+';
+    const tr = unicode ? '┐' : '+';
+    const br = unicode ? '┘' : '+';
+    const h = unicode ? '─' : '-';
+
+    const pageSize = 8;
+    const start = Math.max(0, Math.min(index - Math.floor(pageSize / 2), Math.max(0, items.length - pageSize)));
+    const shown = items.slice(start, start + pageSize);
+
+    const rows = [];
+    const headLabel = ` ${title || 'Menu'} `;
+    const headFill = Math.max(0, width - 2 - displayWidth(headLabel));
+    rows.push(`${tl}${COLORS.bold(headLabel)}${h.repeat(headFill)}${tr}`);
 
-    // 先把提示行清掉，候选从空行开始打印
-    this.clearLine();
-    this.output.write('\n');
-    if (title) this.output.write(`${COLORS.faint(`  ${title}`)}\n`);
-    const shown = items.slice(0, 12);
     shown.forEach((item, i) => {
-      const active = i === index;
-      const label = truncate(item.label, width - 8);
-      const hintWidth = Math.max(0, width - 10 - displayWidth(label));
-      const hint = item.hint && hintWidth > 4 ? COLORS.faint(`  ${truncate(item.hint, hintWidth)}`) : '';
-      this.output.write(`${active ? COLORS.accent('›') : ' '} ${active ? COLORS.accent(label) : label}${hint}\n`);
+      const realIndex = start + i;
+      const active = realIndex === index;
+      const marker = active ? COLORS.accent('›') : ' ';
+      const label = truncate(item.label, Math.max(8, inner - 6));
+      const hintWidth = Math.max(0, inner - 4 - displayWidth(label));
+      const tail = item.hint && hintWidth > 6 ? COLORS.faint(`  ${truncate(item.hint, hintWidth)}`) : '';
+      const body = `${marker} ${active ? COLORS.accent(label) : label}${tail}`;
+      const fill = Math.max(0, inner - displayWidth(`${marker} ${label}${tail ? `  ${truncate(item.hint, hintWidth)}` : ''}`));
+      rows.push(`${COLORS.faint(v)} ${body}${' '.repeat(fill)}${COLORS.faint(v)}`);
     });
-    if (items.length > shown.length) {
-      this.output.write(COLORS.faint(`  …还有 ${items.length - shown.length} 项\n`));
-    }
 
-    // 重画提示行，让它回到最下方
-    this.onScreen = '';
-    this.repaint();
+    const footer = items.length > shown.length ? ` ${start + 1}-${start + shown.length}/${items.length} ` : '';
+    rows.push(`${bl}${h.repeat(Math.max(0, width - 2 - displayWidth(footer)))}${footer}${br}`);
+    if (hint) rows.push(COLORS.faint(`  ${hint}`));
+    return rows;
   }
 
-  closePopup() {
+  /** 打开/刷新菜单后整体重绘 */
+  drawMenu() {
+    this.drawAll();
+  }
+
+  closeMenu() {
     if (!this.popup) return;
     this.popup = null;
-    this.repaint();
+    this.drawAll();
+  }
+
+  applyItem(item) {
+    if (!item) return;
+    const next = typeof item.apply === 'string' ? item.apply : typeof item.value === 'string' ? item.value : null;
+    if (next !== null) {
+      this.value = next;
+      this.cursor = Array.from(next).length;
+    }
   }
 
   /* ------------------------------ 编辑 ------------------------------ */
@@ -276,58 +495,65 @@ class LineEditor {
     this.historyIndex = this.history.length;
   }
 
+  /** 取上一条可回填的内容：优先用户提示词，其次普通历史 */
+  previousEntry() {
+    if (this.lastUserPrompt) return this.lastUserPrompt;
+    if (this.history.length) return this.history[this.history.length - 1];
+    return '';
+  }
+
   /* ------------------------------ 按键 ------------------------------ */
 
   async handleKey(str, key) {
     if (!this.active) return;
     const ctrl = Boolean(key.ctrl);
     const chars = Array.from(this.value);
-    const isSubmitKey = key.name === 'return' || key.name === 'enter' || str === '\r' || str === '\n';
+    const isSubmit = key.name === 'return' || key.name === 'enter' || str === '\r' || str === '\n';
 
-    /* --- 弹层激活 --- */
+    /* --- 菜单激活时优先处理 --- */
     if (this.popup) {
       const { items } = this.popup;
       if (key.name === 'up') {
         this.popup.index = (this.popup.index - 1 + items.length) % items.length;
-        this.drawPopup();
+        this.drawMenu();
         return;
       }
-      if (key.name === 'down' || key.name === 'tab') {
+      if (key.name === 'down') {
         this.popup.index = (this.popup.index + 1) % items.length;
-        this.drawPopup();
+        this.drawMenu();
         return;
       }
       if (key.name === 'escape') {
+        this.closeMenu();
+        return;
+      }
+      if (key.name === 'tab') {
+        // Tab 补全当前选中项
+        this.applyItem(items[this.popup.index]);
         this.popup = null;
-        this.repaint();
+        this.draw();
         return;
       }
-      if (isSubmitKey) {
-        const item = items[this.popup.index];
+      if (isSubmit) {
+        // Enter 执行当前选中项
+        this.applyItem(items[this.popup.index]);
         this.popup = null;
-        if (item) {
-          // 注意：不能写 `this.completer.apply(...)` —— 那是 Function.prototype.apply，
-          // 永远存在，会把补全器的返回值吃成 undefined。这里只认显式的 applyItem 方法，
-          // 否则回落到 item 上的 apply 字符串。
-          let applied = null;
-          if (this.completer && typeof this.completer.applyItem === 'function') {
-            applied = this.completer.applyItem(this.value, this.cursor, item);
-          }
-          if (applied && typeof applied.value === 'string') {
-            this.value = applied.value;
-            this.cursor = Number.isInteger(applied.cursor) ? applied.cursor : Array.from(applied.value).length;
-          } else if (typeof item.apply === 'string') {
-            this.value = item.apply;
-            this.cursor = Array.from(item.apply).length;
-          } else if (typeof item.value === 'string') {
-            this.value = item.value;
-            this.cursor = Array.from(item.value).length;
-          }
-          this.repaint();
-          // 补全后把选择权交回用户：再按一次回车才提交
-          return;
+        this.submit();
+        return;
+      }
+      if (key.name === 'backspace') {
+        if (this.cursor > 0) {
+          chars.splice(this.cursor - 1, 1);
+          this.cursor -= 1;
+          this.value = chars.join('');
         }
+        this.popup = null;
+        this.draw();
+        return;
       }
+      // 其他字符：关闭菜单继续输入
+      this.popup = null;
+      this.draw();
     }
 
     /* --- 控制键 --- */
@@ -335,11 +561,10 @@ class LineEditor {
       if (this.value) {
         this.value = '';
         this.cursor = 0;
-        this.popup = null;
-        this.repaint();
+        this.draw();
         return;
       }
-      this.clearLine();
+      this.clearDrawn();
       this.active = false;
       if (this.keyHandler) {
         this.input.removeListener('keypress', this.keyHandler);
@@ -359,7 +584,7 @@ class LineEditor {
         this.finished = false;
         this.value = '';
         this.cursor = 0;
-        this.onScreen = '';
+        this.drawnRows = 0;
         if (this.input.isTTY) {
           try {
             this.input.setRawMode(true);
@@ -371,7 +596,7 @@ class LineEditor {
           this.keyQueue = this.keyQueue.then(() => this.handleKey(s || '', k || {})).catch(() => {});
         };
         this.input.on('keypress', this.keyHandler);
-        this.repaint();
+        this.draw();
         return;
       }
       this.finish({ type: 'cancel', value: '' });
@@ -385,7 +610,7 @@ class LineEditor {
       }
       chars.splice(this.cursor, 1);
       this.value = chars.join('');
-      this.repaint();
+      this.draw();
       return;
     }
 
@@ -393,14 +618,14 @@ class LineEditor {
       chars.splice(0, this.cursor);
       this.value = chars.join('');
       this.cursor = 0;
-      this.repaint();
+      this.draw();
       return;
     }
 
     if (ctrl && key.name === 'k') {
       chars.splice(this.cursor);
       this.value = chars.join('');
-      this.repaint();
+      this.draw();
       return;
     }
 
@@ -411,104 +636,111 @@ class LineEditor {
       chars.splice(i, this.cursor - i);
       this.cursor = i;
       this.value = chars.join('');
-      this.repaint();
+      this.draw();
       return;
     }
 
     if (ctrl && key.name === 'a') {
       this.cursor = 0;
-      this.repaint();
+      this.draw();
       return;
     }
 
     if (ctrl && key.name === 'e') {
       this.cursor = chars.length;
-      this.repaint();
+      this.draw();
       return;
     }
 
     if (ctrl && key.name === 'l') {
-      this.output.write('\x1b[2J\x1b[H');
-      this.onScreen = '';
-      this.repaint();
+      clearScreen(this.output);
+      this.drawnRows = 0;
+      this.draw();
       return;
     }
 
-    /* --- 回车 --- */
-    if (isSubmitKey) {
+    /* --- 回车 / 续行 --- */
+    if (isSubmit) {
       if (this.multiline && chars[this.cursor - 1] === '\\') {
         chars.splice(this.cursor - 1, 1, '\n');
         this.value = chars.join('');
-        this.repaint();
+        this.draw();
         return;
       }
       this.submit();
       return;
     }
 
-    /* --- 光标与删除 --- */
-    if (key.name === 'backspace') {
-      if (this.cursor > 0) {
-        chars.splice(this.cursor - 1, 1);
-        this.cursor -= 1;
-        this.value = chars.join('');
-        this.refreshPopup();
+    /* --- 方向键 --- */
+    if (key.name === 'up') {
+      // ↑ 回填上一条用户提示词
+      const previous = this.previousEntry();
+      if (previous && !this.value) {
+        this.value = previous;
+        this.cursor = Array.from(previous).length;
+        this.draw();
       }
       return;
     }
-    if (key.name === 'delete') {
-      if (this.cursor < chars.length) {
-        chars.splice(this.cursor, 1);
-        this.value = chars.join('');
-        this.refreshPopup();
+    if (key.name === 'down') {
+      if (this.historyIndex < this.history.length - 1) {
+        this.historyIndex += 1;
+        this.value = this.history[this.historyIndex] || '';
+        this.cursor = Array.from(this.value).length;
+      } else {
+        this.historyIndex = this.history.length;
+        this.value = this.draft;
+        this.cursor = Array.from(this.value).length;
       }
+      this.draw();
       return;
     }
     if (key.name === 'left') {
       this.cursor = Math.max(0, this.cursor - 1);
-      this.popup = null;
-      this.repaint();
+      this.draw();
       return;
     }
     if (key.name === 'right') {
       this.cursor = Math.min(chars.length, this.cursor + 1);
-      this.popup = null;
-      this.repaint();
+      this.draw();
       return;
     }
     if (key.name === 'home') {
       this.cursor = 0;
-      this.repaint();
+      this.draw();
       return;
     }
     if (key.name === 'end') {
       this.cursor = chars.length;
-      this.repaint();
+      this.draw();
       return;
     }
-    if (key.name === 'up') {
-      if (!this.history.length) return;
-      if (this.historyIndex === this.history.length) this.draft = this.value;
-      this.historyIndex = Math.max(0, this.historyIndex - 1);
-      this.value = this.history[this.historyIndex] || '';
-      this.cursor = Array.from(this.value).length;
-      this.popup = null;
-      this.repaint();
+
+    /* --- 删除 --- */
+    if (key.name === 'backspace') {
+      if (this.cursor > 0) {
+        chars.splice(this.cursor - 1, 1);
+        this.cursor -= 1;
+        this.value = chars.join('');
+        this.draw();
+      }
       return;
     }
-    if (key.name === 'down') {
-      if (this.historyIndex >= this.history.length) return;
-      this.historyIndex = Math.min(this.history.length, this.historyIndex + 1);
-      this.value = this.historyIndex === this.history.length ? this.draft : this.history[this.historyIndex] || '';
-      this.cursor = Array.from(this.value).length;
-      this.popup = null;
-      this.repaint();
+    if (key.name === 'delete') {
+      if (this.cursor < chars.length) {
+        chars.splice(this.cursor, 1);
+        this.value = chars.join('');
+        this.draw();
+      }
       return;
     }
+
+    /* --- Tab：打开或切换菜单 --- */
     if (key.name === 'tab') {
-      this.refreshPopup();
+      if (!this.popup) this.openMenu();
       return;
     }
+
     if (key.name === 'escape') {
       return;
     }
@@ -518,7 +750,7 @@ class LineEditor {
       const filtered = String(str).replace(/[\r\n]/g, '');
       if (filtered) {
         this.insert(filtered);
-        this.repaint();
+        this.draw();
       }
     }
   }
@@ -528,15 +760,36 @@ class LineEditor {
     this.value = '';
     this.cursor = 0;
     this.popup = null;
+    this.historyIndex = this.history.length;
+    this.draft = '';
     this.finish({ type: 'submit', value });
   }
 }
 
+/* ------------------------------ 文本折行 ------------------------------ */
+
+/** 按显示宽度把文本折成多行 */
+function wrapDisplay(text, width) {
+  const limit = Math.max(4, width);
+  const out = [];
+  let line = '';
+  let lineWidth = 0;
+  for (const char of String(text ?? '')) {
+    const w = displayWidth(char);
+    if (lineWidth + w > limit) {
+      out.push(line);
+      line = '';
+      lineWidth = 0;
+    }
+    line += char;
+    lineWidth += w;
+  }
+  out.push(line);
+  return out.length ? out : [''];
+}
+
 /* ------------------------------ 非 TTY 回退 ------------------------------ */
 
-/**
- * 非 TTY（管道 / 重定向）用的极简行读取：不做任何光标控制。
- */
 function createLineReader(stream = process.stdin) {
   const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
   const iterator = rl[Symbol.asyncIterator]();
@@ -554,6 +807,7 @@ function createLineReader(stream = process.stdin) {
     },
     setAbortHandler() {},
     history: [],
+    lastUserPrompt: '',
     pushHistory() {},
     suspend() {},
     resume() {},
@@ -571,4 +825,4 @@ function createLineReader(stream = process.stdin) {
   };
 }
 
-module.exports = { LineEditor, createLineReader };
+module.exports = { LineEditor, createLineReader, detectCapabilities, wrapDisplay, t };