mocode-ai 0.1.0

package/dist/ui/prompt.js

@@ -0,0 +1,414 @@
+import readline from 'node:readline';
+import { stdin, stdout } from 'node:process';
+import { ui } from './theme.js';
+import { displayWidth, padEndDisplay, truncateDisplay } from './render.js';
+import * as layout from './layout.js';
+/** 非 TTY / 未进 alt screen 时退化为普通 readline 行输入(无菜单、单行)。 */
+function questionFallback(prompt) {
+    return new Promise((res, rej) => {
+        const rl = readline.createInterface({ input: stdin, output: stdout });
+        rl.question(prompt, (answer) => {
+            rl.close();
+            res(answer);
+        });
+        rl.on('error', (e) => {
+            rl.close();
+            rej(e);
+        });
+    });
+}
+/**
+ * 读多行输入;TUI 下经 layout.paintInput 把输入框画在固定底栏、斜杠菜单向上展开进内容区底。
+ * 换行:Ctrl+J / Alt+Enter / Shift+Enter(终端区分时)/ 粘贴的 LF。Enter 提交。返回行数组;null=空缓冲 Ctrl+D。
+ * 非 TTY 退化为 readline.question(单行,返回 [answer])。raw 模式下 Ctrl+C 先恢复终端再 reject('SIGINT')。
+ *
+ * 渲染全归 layout(prompt 只持有编辑状态:lines / 光标 / 菜单),prompt 不直接发 ANSI 区域控制,
+ * 避免 readline 光标错位与区域越界——颜色仅用在菜单行字符串里(由 layout 原样贴入)。
+ */
+export async function promptWithSlashMenu(opts) {
+    if (!layout.isActive()) {
+        const a = await questionFallback(opts.prompt);
+        return [a];
+    }
+    const emitter = stdin;
+    const promptW = displayWidth(opts.prompt);
+    // initialLines(运行中 typeahead 预填):用调用方给的行初始化,光标置末行末尾。
+    let lines = opts.initialLines && opts.initialLines.length > 0
+        ? [...opts.initialLines]
+        : [''];
+    let cl = lines.length - 1; // 光标行(0-based)= 末行
+    let cc = lines[cl].length; // 光标在该行的字符索引 = 末行末尾
+    let menuOpen = false;
+    let selected = 0;
+    let filtered = [];
+    let resolved = false;
+    let resolve;
+    let reject;
+    /** 菜单行(预渲染,带色)——向上展开进内容区底,由 layout 贴入。 */
+    function menuLines() {
+        if (!menuOpen || filtered.length === 0)
+            return [];
+        const cols = layout.getGeo().cols;
+        const maxName = Math.max(...filtered.map((c) => displayWidth(c.name)));
+        return filtered.map((c, i) => {
+            const marker = i === selected ? `${ui.cyan}▸${ui.reset}` : ' ';
+            const name = padEndDisplay(c.name, maxName);
+            const descW = cols - maxName - 5; // marker + 空格 + 2 间距
+            const desc = descW > 0 ? truncateDisplay(c.desc, descW) : '';
+            return `${marker} ${ui.dim}${name}${ui.reset}  ${ui.dim}${desc}${ui.reset}`;
+        });
+    }
+    /** 当前光标在该行的显示列(供 layout 定位光标)。 */
+    function cursorCol() {
+        return displayWidth(lines[cl].slice(0, cc));
+    }
+    function computeFiltered() {
+        if (cl === 0 && lines[0].startsWith('/')) {
+            filtered = opts.commands.filter((c) => c.name.startsWith(lines[0]));
+            menuOpen = filtered.length > 0;
+            if (selected >= filtered.length)
+                selected = 0;
+        }
+        else {
+            filtered = [];
+            menuOpen = false;
+        }
+    }
+    function redraw() {
+        layout.paintInput({
+            prompt: opts.prompt,
+            lines,
+            cursorLine: cl,
+            cursorCol: cursorCol(),
+            menu: menuLines().length ? { lines: menuLines() } : null,
+        });
+    }
+    function cleanup() {
+        try {
+            stdin.setRawMode(false);
+        }
+        catch {
+            // 忽略
+        }
+        emitter.removeListener('keypress', onKey);
+        stdin.pause();
+    }
+    function finish(value) {
+        if (resolved)
+            return;
+        resolved = true;
+        cleanup();
+        resolve(value);
+    }
+    /** 提交:菜单打开时先补全选中项到第 0 行。 */
+    function submit() {
+        if (menuOpen && filtered[selected]) {
+            lines = [filtered[selected].name];
+            cl = 0;
+            cc = lines[0].length;
+        }
+        finish(lines);
+    }
+    /** 插换行:在光标处断行。 */
+    function insertNewline() {
+        const after = lines[cl].slice(cc);
+        lines[cl] = lines[cl].slice(0, cc);
+        lines.splice(cl + 1, 0, after);
+        cl++;
+        cc = 0;
+        computeFiltered();
+        redraw();
+    }
+    function onKey(_str, key) {
+        if (resolved || !key)
+            return;
+        // 滚动回看键(优先;不触发回尾):PgUp/PgDn 翻页,Ctrl+↑↓ 与 plain ↑/↓ 单行。
+        // plain ↑/↓ 仅在单行输入且菜单关闭时作滚动(多行编辑留给光标移动,菜单打开留给选项);
+        // 兼鼠标滚轮——WT alt 屏(经 \x1B[?1007h)滚轮转发 ↑/↓。
+        const plainArrowScroll = (key.name === 'up' || key.name === 'down') &&
+            !key.ctrl &&
+            !key.meta &&
+            !key.shift &&
+            lines.length <= 1 &&
+            !(menuOpen && filtered.length > 0);
+        if (key.name === 'pageup' ||
+            key.name === 'pagedown' ||
+            (key.ctrl && (key.name === 'up' || key.name === 'down')) ||
+            plainArrowScroll) {
+            const pageH = layout.getGeo().contentBottom;
+            if (key.name === 'pageup')
+                layout.scrollBy(pageH);
+            else if (key.name === 'pagedown')
+                layout.scrollBy(-pageH);
+            else if (key.name === 'up')
+                layout.scrollBy(1);
+            else
+                layout.scrollBy(-1);
+            return;
+        }
+        // 其他键:若处于滚动回看,先回尾再处理(打字即回底)
+        if (layout.isScrolled())
+            layout.resetScroll();
+        // raw 模式下 Ctrl+C 不触发 SIGINT,作为按键到达:先恢复终端再 reject
+        if (key.ctrl && key.name === 'c') {
+            cleanup();
+            reject(new Error('SIGINT'));
+            return;
+        }
+        if (key.ctrl && key.name === 'd') {
+            if (lines.every((l) => l === '') && cl === 0 && cc === 0)
+                finish(null);
+            return;
+        }
+        if (key.ctrl && key.name === 'a') {
+            cc = 0;
+            redraw();
+            return;
+        }
+        if (key.ctrl && key.name === 'e') {
+            cc = lines[cl].length;
+            redraw();
+            return;
+        }
+        const isReturn = key.name === 'return' || key.name === 'enter';
+        // 换行:Ctrl+J / Alt+Enter(meta)/ Shift+Enter(终端区分时)/ 粘贴的 LF
+        const wantNewline = (key.ctrl && key.name === 'j') ||
+            (key.meta && isReturn) ||
+            (key.shift && isReturn) ||
+            (key.sequence === '\n' && !key.ctrl);
+        // 换行(Ctrl+J / Alt+Enter / Shift+Enter / 粘贴 LF)
+        if (wantNewline) {
+            insertNewline();
+            return;
+        }
+        // 提交(plain Enter)
+        if (isReturn && !key.shift && !key.meta && !key.ctrl) {
+            submit();
+            return;
+        }
+        switch (key.name) {
+            case 'backspace':
+                if (cc > 0) {
+                    lines[cl] = lines[cl].slice(0, cc - 1) + lines[cl].slice(cc);
+                    cc--;
+                    computeFiltered();
+                    redraw();
+                }
+                else if (cl > 0) {
+                    // 行首退格:并入上一行
+                    const cur = lines[cl];
+                    cc = lines[cl - 1].length;
+                    lines[cl - 1] = lines[cl - 1] + cur;
+                    lines.splice(cl, 1);
+                    cl--;
+                    computeFiltered();
+                    redraw();
+                }
+                return;
+            case 'up':
+                if (menuOpen && filtered.length) {
+                    selected = (selected - 1 + filtered.length) % filtered.length;
+                    redraw();
+                }
+                else if (cl > 0) {
+                    cl--;
+                    cc = Math.min(cc, lines[cl].length);
+                    redraw();
+                }
+                return;
+            case 'down':
+                if (menuOpen && filtered.length) {
+                    selected = (selected + 1) % filtered.length;
+                    redraw();
+                }
+                else if (cl < lines.length - 1) {
+                    cl++;
+                    cc = Math.min(cc, lines[cl].length);
+                    redraw();
+                }
+                return;
+            case 'tab':
+                if (menuOpen && filtered[selected]) {
+                    lines[0] = filtered[selected].name;
+                    cl = 0;
+                    cc = lines[0].length;
+                    computeFiltered();
+                    redraw();
+                }
+                return;
+            case 'escape':
+                menuOpen = false;
+                filtered = [];
+                redraw();
+                return;
+            case 'left':
+                if (cc > 0) {
+                    cc--;
+                    redraw();
+                }
+                else if (cl > 0) {
+                    cl--;
+                    cc = lines[cl].length;
+                    redraw();
+                }
+                return;
+            case 'right':
+                if (cc < lines[cl].length) {
+                    cc++;
+                    redraw();
+                }
+                else if (cl < lines.length - 1) {
+                    cl++;
+                    cc = 0;
+                    redraw();
+                }
+                return;
+            case 'home':
+                cc = 0;
+                redraw();
+                return;
+            case 'end':
+                cc = lines[cl].length;
+                redraw();
+                return;
+        }
+        // 可打印字符(>= 空格,非 ctrl/meta)
+        const s = key.sequence ?? '';
+        if (s && s >= ' ' && !key.ctrl && !key.meta) {
+            lines[cl] = lines[cl].slice(0, cc) + s + lines[cl].slice(cc);
+            cc += s.length;
+            computeFiltered();
+            redraw();
+        }
+    }
+    return new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+        readline.emitKeypressEvents(stdin);
+        let rawOk = true;
+        try {
+            stdin.setRawMode(true);
+        }
+        catch {
+            rawOk = false;
+        }
+        if (!rawOk) {
+            // isTTY 但 setRawMode 失败(罕见):退化为 readline
+            questionFallback(opts.prompt).then((a) => res([a]), (e) => rej(e));
+            return;
+        }
+        stdin.resume();
+        emitter.on('keypress', onKey);
+        computeFiltered();
+        redraw();
+    });
+}
+/**
+ * 轮次选择菜单(供 /rollback 菜单化选择):↑/↓ 导航、Enter 选中、Esc/Ctrl+D 取消。
+ * 把 items 画成向上展开的菜单(经 layout.paintInput,与斜杠菜单同套渲染),输入框行作操作提示。
+ * 返回选中的 0-based 下标;null=取消 / 非 TTY / 空列表。纯导航(不收文本输入)。
+ * 长列表(超屏高)自动开窗保光标可见;默认聚焦末项(最新轮次,靠近输入框)。
+ */
+export async function promptTurnPicker(items) {
+    if (!layout.isActive() || items.length === 0)
+        return null;
+    const emitter = stdin;
+    const hint = '↑↓ 选择 · Enter 回滚到该轮 · Esc 取消';
+    let selected = items.length - 1; // 默认聚焦最新(末项,菜单底、靠近输入框)
+    let resolved = false;
+    let resolve;
+    let reject;
+    /** 菜单行(带开窗):超屏高时以 selected 为中心取窗,保光标可见;末项在底(靠近输入框)。 */
+    function menuLines() {
+        const g = layout.getGeo();
+        const maxRows = Math.max(1, g.contentBottom);
+        let start = 0;
+        if (items.length > maxRows) {
+            start = Math.max(0, Math.min(selected - Math.floor(maxRows / 2), items.length - maxRows));
+        }
+        const count = Math.min(maxRows, items.length);
+        const cols = g.cols;
+        return Array.from({ length: count }, (_, i) => {
+            const idx = start + i;
+            const marker = idx === selected ? `${ui.cyan}▸${ui.reset}` : ' ';
+            const num = `${ui.dim}${idx + 1}${ui.reset}`;
+            const text = truncateDisplay(items[idx].firstLine, cols - 6);
+            return `${marker} ${num} ${ui.dim}${text}${ui.reset}`;
+        });
+    }
+    function redraw() {
+        layout.paintInput({
+            prompt: '❯ ',
+            lines: [hint],
+            cursorLine: 0,
+            cursorCol: displayWidth(hint),
+            menu: { lines: menuLines() },
+        });
+    }
+    function cleanup() {
+        try {
+            stdin.setRawMode(false);
+        }
+        catch {
+            // 忽略
+        }
+        emitter.removeListener('keypress', onKey);
+        stdin.pause();
+    }
+    function finish(value) {
+        if (resolved)
+            return;
+        resolved = true;
+        cleanup();
+        resolve(value);
+    }
+    function onKey(_str, key) {
+        if (resolved || !key)
+            return;
+        if (key.ctrl && key.name === 'c') {
+            cleanup();
+            reject(new Error('SIGINT'));
+            return;
+        }
+        if (key.ctrl && key.name === 'd') {
+            finish(null);
+            return;
+        }
+        switch (key.name) {
+            case 'up':
+                selected = (selected - 1 + items.length) % items.length;
+                redraw();
+                return;
+            case 'down':
+                selected = (selected + 1) % items.length;
+                redraw();
+                return;
+            case 'return':
+            case 'enter':
+                finish(selected);
+                return;
+            case 'escape':
+                finish(null);
+                return;
+        }
+    }
+    return new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+        readline.emitKeypressEvents(stdin);
+        let rawOk = true;
+        try {
+            stdin.setRawMode(true);
+        }
+        catch {
+            rawOk = false;
+        }
+        if (!rawOk) {
+            res(null);
+            return;
+        }
+        stdin.resume();
+        emitter.on('keypress', onKey);
+        redraw();
+    });
+}

package/dist/ui/render.js

@@ -0,0 +1,204 @@
+import { stdout } from 'node:process';
+import { ui } from './theme.js';
+/**
+ * 清空整屏 + 滚动缓冲(向上滚动可见的历史输出),光标归位。
+ * 进入会话时调用,让终端只剩当前 agent 对话。非 TTY 时空操作。
+ */
+export function clearScreen() {
+    if (!ui.isTTY)
+        return;
+    // [2J 清整屏 · [3J 清滚动缓冲 · [H 光标回到左上
+    stdout.write('\x1B[2J\x1B[3J\x1B[H');
+}
+// ── 显示宽度:CJK / 全角算 2,控制符 / 组合符算 0;用于横幅边框对齐 ──
+export function charWidth(cp) {
+    if (cp < 0x20 || (cp >= 0x7f && cp < 0xa0))
+        return 0; // 控制符
+    if (cp >= 0x300 && cp <= 0x36f)
+        return 0; // 组合附加符号
+    if (cp >= 0x1ab0 && cp <= 0x1aff)
+        return 0;
+    if (cp >= 0x1dc0 && cp <= 0x1dff)
+        return 0;
+    if (cp >= 0x20d0 && cp <= 0x20ff)
+        return 0;
+    if (cp >= 0x200b && cp <= 0x200f)
+        return 0; // 零宽 / ZWJ
+    if (cp >= 0xfe00 && cp <= 0xfe0f)
+        return 0; // 变体选择符
+    if (cp >= 0x1100 && cp <= 0x115f)
+        return 2;
+    if (cp >= 0x2e80 && cp <= 0x303e)
+        return 2;
+    if (cp >= 0x3041 && cp <= 0x33ff)
+        return 2;
+    if (cp >= 0x3400 && cp <= 0x4dbf)
+        return 2;
+    if (cp >= 0x4e00 && cp <= 0xa4cf)
+        return 2; // CJK 统一表意
+    if (cp >= 0xac00 && cp <= 0xd7a3)
+        return 2; // 韩文音节
+    if (cp >= 0xf900 && cp <= 0xfaff)
+        return 2;
+    if (cp >= 0xfe30 && cp <= 0xfe6f)
+        return 2;
+    if (cp >= 0xff00 && cp <= 0xff60)
+        return 2; // 全角
+    if (cp >= 0xffe0 && cp <= 0xffe6)
+        return 2;
+    if (cp >= 0x1f300 && cp <= 0x1faff)
+        return 2; // 表情
+    if (cp >= 0x20000 && cp <= 0x2fffd)
+        return 2; // CJK 扩展 B-F
+    return 1;
+}
+export function displayWidth(str) {
+    let w = 0;
+    for (const ch of str)
+        w += charWidth(ch.codePointAt(0) ?? 0);
+    return w;
+}
+/** 去除 SGR 颜色转义(\x1B[…m),用于度量带色串的真实可见宽度。 */
+export function stripAnsi(s) {
+    return s.replace(/\x1b\[[0-9;]*m/g, '');
+}
+/** 带色串的可见显示宽度(先去 ANSI 再按 displayWidth 度量)。 */
+export function ansiDisplayWidth(s) {
+    return displayWidth(stripAnsi(s));
+}
+/** 按显示宽度右补空格。 */
+export function padEndDisplay(str, width) {
+    const w = displayWidth(str);
+    return w >= width ? str : str + ' '.repeat(width - w);
+}
+/** 按显示宽度截断,超出加 …。 */
+export function truncateDisplay(str, width) {
+    if (displayWidth(str) <= width)
+        return str;
+    let w = 0;
+    let out = '';
+    for (const ch of str) {
+        const cw = charWidth(ch.codePointAt(0) ?? 0);
+        if (w + cw + 1 > width)
+            break; // +1 留给末尾的 …
+        out += ch;
+        w += cw;
+    }
+    return out + '…';
+}
+/**
+ * 按显示宽度把文本软折行为多行(供输入框软换行):每行可见宽度 ≤ width。
+ * 宽字符(CJK / emoji = 2)在剩余宽度放不下时整字折到下行(留尾部空格,与终端自动折行一致),
+ * 而非劈开半个字。零宽字符(组合符等)不计宽度、附在当前行。空串返回 [''](占一行)。
+ * 输入文本应全为可见字符(无控制码 / SGR)。
+ */
+export function wrapByDisplayWidth(text, width) {
+    const w = Math.max(1, width);
+    const out = [];
+    let cur = '';
+    let curW = 0;
+    for (const ch of text) {
+        const cw = charWidth(ch.codePointAt(0) ?? 0);
+        if (cw <= 0) {
+            cur += ch; // 零宽:不计宽度
+            continue;
+        }
+        if (curW + cw > w) {
+            out.push(cur);
+            cur = ch;
+            curW = cw;
+        }
+        else {
+            cur += ch;
+            curW += cw;
+        }
+    }
+    out.push(cur);
+    return out;
+}
+const BOX_W = 76; // 内容区显示宽度(容下完整工具列表 + 命令提示)
+const MARGIN = '  '; // 盒外左缩进
+function boxBorder(left, mid, right) {
+    return `${ui.gray}${left}${mid.repeat(BOX_W + 2)}${right}${ui.reset}`;
+}
+function boxLine(content) {
+    const inner = padEndDisplay(truncateDisplay(content, BOX_W), BOX_W);
+    return `${ui.gray}│${ui.reset} ${inner} ${ui.gray}│${ui.reset}`;
+}
+function boxEmpty() {
+    return `${ui.gray}│${ui.reset} ${' '.repeat(BOX_W)} ${ui.gray}│${ui.reset}`;
+}
+function labelRow(label, value) {
+    return boxLine(`${ui.dim}${padEndDisplay(label, 6)}${ui.reset}${value}`);
+}
+/** 横幅纯文本(带 ANSI 颜色,不写出)——供 TUI 经 contentWrite 写入内容区以跟踪续写位。 */
+export function bannerString(info) {
+    const rows = [
+        boxBorder('╭', '─', '╮'),
+        boxLine(`${ui.bold}${ui.brightCyan}◆  mocode${ui.reset}  ${ui.dim}终端编码 agent${ui.reset}`),
+        boxEmpty(),
+        labelRow('模型', info.model),
+        labelRow('后端', info.baseURL),
+        labelRow('目录', info.cwd),
+        labelRow('工具', info.tools),
+        boxEmpty(),
+        boxLine(`${ui.dim}/exit 退出 · /clear 清空 · /compact 压缩 · /context 用量 · /resume 续接${ui.reset}`),
+        boxBorder('╰', '─', '╯'),
+    ];
+    return (rows.map((r) => MARGIN + r).join('\n') +
+        '\n\n' +
+        `${MARGIN}${ui.dim}直接描述任务,agent 会自动读写文件与执行命令。${ui.reset}\n`);
+}
+/** 启动横幅:带边框的信息盒 + 一行提示。纯渲染,不依赖 config / 业务。 */
+export function printBanner(info) {
+    stdout.write(bannerString(info));
+}
+// ── 工具调用 / 结果 摘要 ──
+function tryParse(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** 把工具调用的 JSON 参数提炼成人可读的一行(路径 / 模式 / 命令)。 */
+export function summarizeToolCall(name, argsRaw) {
+    const args = tryParse(argsRaw);
+    if (!args)
+        return truncateDisplay(argsRaw, 80);
+    const s = (k) => typeof args[k] === 'string' ? args[k] : '';
+    switch (name) {
+        case 'read_file':
+        case 'write_file':
+        case 'edit_file':
+            return s('path') || truncateDisplay(argsRaw, 80);
+        case 'run_command':
+            return truncateDisplay(s('command') || argsRaw, 100);
+        case 'glob':
+            return s('pattern') || argsRaw;
+        case 'grep': {
+            const p = s('pattern');
+            const path = s('path');
+            return path ? `${p}  ·  ${path}` : p || argsRaw;
+        }
+        default:
+            return truncateDisplay(argsRaw, 80);
+    }
+}
+/** 工具结果的人可读一行预览(行数 / 匹配数 / 首行);喂回 LLM 的全文不变。 */
+export function summarizeToolResult(name, output) {
+    const nonEmpty = output.split('\n').filter((l) => l.trim().length > 0);
+    switch (name) {
+        case 'read_file':
+            return nonEmpty.length ? `${nonEmpty.length} 行` : '(空文件)';
+        case 'glob':
+            return nonEmpty.length ? `${nonEmpty.length} 个文件` : '(无匹配)';
+        case 'grep':
+            return nonEmpty.length ? `${nonEmpty.length} 处匹配` : '(无匹配)';
+        case 'run_command':
+            return truncateDisplay(nonEmpty[0] ?? '', 100) || '(无输出)';
+        default:
+            return truncateDisplay(nonEmpty[0] ?? '', 100);
+    }
+}

package/dist/ui/spinner.js

@@ -0,0 +1,63 @@
+import { stdout } from 'node:process';
+import { ui } from './theme.js';
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+/**
+ * 等待动画:在 await 长操作(chat / 工具执行 / 压缩)时旋转,避免「卡死」错觉。
+ *
+ * 两种渲染模式:
+ *  - onFrame 回调(TUI 态):帧经回调刷状态行(layout.drawStatusBar),内容区保持静止、底栏转圈;
+ *    不在内容行用 \r\x1B[K 原地刷(那会擦内容、与滚动区域冲突)。
+ *  - 无回调(非 TTY / 旧路径):\r\x1B[K 原地刷 braille 帧;非 TTY 退化为启动时打印一行静态提示。
+ *
+ * stop() 仅在确实旋转过(有 timer)时清场,避免对从未 start 的实例误清状态行。
+ */
+export class Spinner {
+    onFrame;
+    timer = null;
+    frame = 0;
+    msg = '';
+    constructor(onFrame) {
+        this.onFrame = onFrame;
+    }
+    start(msg) {
+        this.stop();
+        this.msg = msg;
+        if (!ui.isTTY) {
+            stdout.write(`${ui.dim}${msg}…${ui.reset}\n`);
+            return;
+        }
+        if (this.onFrame) {
+            const cb = this.onFrame;
+            this.frame = 0;
+            cb(msg, FRAMES[0]); // 立即首帧,状态行即刻反映
+            this.timer = setInterval(() => {
+                this.frame = (this.frame + 1) % FRAMES.length;
+                cb(msg, FRAMES[this.frame]);
+            }, 80);
+            this.timer.unref();
+            return;
+        }
+        this.frame = 0;
+        this.timer = setInterval(() => {
+            this.render();
+            this.frame = (this.frame + 1) % FRAMES.length;
+        }, 80);
+        this.timer.unref();
+    }
+    render() {
+        const f = FRAMES[this.frame];
+        stdout.write(`\r${ui.brightMagenta}${f}${ui.reset} ${ui.dim}${this.msg}${ui.reset}\x1B[K`);
+    }
+    stop() {
+        if (!this.timer)
+            return; // 未旋转:不清场(避免误清状态行)
+        clearInterval(this.timer);
+        this.timer = null;
+        if (this.onFrame) {
+            this.onFrame(this.msg, null); // 状态行去帧,保留状态文字
+        }
+        else if (ui.isTTY) {
+            stdout.write('\r\x1B[K');
+        }
+    }
+}

package/dist/ui/theme.js

@@ -0,0 +1,21 @@
+import { stdout } from 'node:process';
+/**
+ * 终端 UI 主题:TTY 感知的 ANSI 颜色。
+ * 非 TTY(管道 / 重定向)时颜色退化为空串,避免把转义码原样打到日志里。
+ */
+const isTTY = Boolean(stdout.isTTY);
+const wrap = (code) => (isTTY ? code : '');
+export const ui = {
+    isTTY,
+    reset: wrap('\x1B[0m'),
+    bold: wrap('\x1B[1m'),
+    dim: wrap('\x1B[2m'),
+    red: wrap('\x1B[31m'),
+    green: wrap('\x1B[32m'),
+    yellow: wrap('\x1B[33m'),
+    cyan: wrap('\x1B[36m'),
+    gray: wrap('\x1B[90m'),
+    magenta: wrap('\x1B[35m'),
+    brightCyan: wrap('\x1B[96m'),
+    brightMagenta: wrap('\x1B[95m'),
+};