mocode-ai 0.4.4 → 0.4.6

package/dist/ui/batch.js

@@ -0,0 +1,235 @@
+/**
+ * 工具调用批量折叠渲染(仿 Claude Code):
+ *   agent 一轮返回 N 个 tool_calls 时,不逐个打印 `● name ↳ result`,
+ *   改输出一行摘要 `● Ran N tools · read 3, grep 1, glob 1`;
+ *   鼠标点击该摘要行 → 展开完整明细(● 头 + ↳ preview / diff 块),再点折回。
+ *
+ * 设计要点:
+ *  - 实时执行 + renderHistory 回放共用本渲染器;
+ *  - 仅 buffer 写一行,详情行展开时才插入(mid-buffer insert via layout.contentInsertAfter);
+ *  - 默认折叠;展开/折叠不影响历史回放的 history 结构(history 仍存完整 tool_calls+tool 消息)。
+ *
+ * 状态全模块级(单实例)——一次 REPL 内所有 batch 共享,清内容区 / 退 alt 屏时统一重置。
+ */
+import { ui } from './theme.js';
+const batches = new Map();
+/** 绝对行索引 → 所属 batch id(仅记录 summary 行;用于鼠标点击反查)。
+ *  buffer 行数变化时本表可能漂移——但只在 insertAfter/deleteFrom 后由本模块同步更新,
+ *  并保持 buffer 当前状态对应。 */
+const absLineToBatchId = new Map();
+/** 已展开的 batch id;默认空(全折叠);layout.mouse release 点击摘要行时切。
+ *  含 mutation 的 batch 不在此 set——它们走 forceExpanded 永远展开,与 toggle 隔离。 */
+const expandedBatches = new Set();
+/** mutation 工具名集合(写盘操作);与 src/agent/core.ts 的 isMutationTool 同步,本模块独立持有
+ *  避免 ui → agent 反向依赖。 */
+const MUTATION_TOOLS = new Set(['write_file', 'edit_file']);
+function isMutationTool(name) {
+    return MUTATION_TOOLS.has(name);
+}
+/** 通知 buffer 整体清空(clearContent / exitAltScreen / 新一轮 turn)——本模块状态同步归零。 */
+export function reset() {
+    batches.clear();
+    absLineToBatchId.clear();
+    expandedBatches.clear();
+}
+/** 新建一个 batch(在 agent 拿到第一条 onToolHeader 时调)。返回 id。 */
+export function beginBatch() {
+    const id = `b${++_idCounter}`;
+    batches.set(id, { id, summaryAbsIdx: -1, entries: [], forceExpanded: false });
+    return id;
+}
+/** 记一条工具调用(在 onToolHeader 时调,与 setEntryResult 配对;entries 顺序 = agent 调用顺序)。 */
+export function recordCall(id, name, callSummary) {
+    const b = batches.get(id);
+    if (!b)
+        return;
+    b.entries.push({ name, callSummary, resultSummary: '', diffBlock: null });
+}
+/** 记一条工具结果(diff 块或单行 preview);agent 在 onToolResult 时调,匹配最后一条未填的 entry。 */
+export function recordResult(id, name, resultSummary, diffBlock) {
+    const b = batches.get(id);
+    if (!b || b.entries.length === 0)
+        return;
+    // 反向找最后一条同名的 entry 填结果;同名工具一批多次调用时正向遍历更安全——用 lastIndexOf 同名回退
+    for (let i = b.entries.length - 1; i >= 0; i--) {
+        if (b.entries[i].name === name && !b.entries[i].resultSummary) {
+            b.entries[i].resultSummary = resultSummary;
+            b.entries[i].diffBlock = diffBlock;
+            return;
+        }
+    }
+    // 兜底:无匹配则填最后一条
+    const last = b.entries[b.entries.length - 1];
+    if (!last.resultSummary) {
+        last.resultSummary = resultSummary;
+        last.diffBlock = diffBlock;
+    }
+}
+// ── 摘要行文本生成 ──
+/** 把 entry 列表压缩成一行摘要(Claude Code 风格)。 */
+function buildSummaryLine(entries) {
+    if (entries.length === 0) {
+        return `  ${ui.brightMagenta}●${ui.reset} ${ui.dim}No tools${ui.reset}`;
+    }
+    if (entries.length === 1) {
+        const e = entries[0];
+        return `  ${ui.brightMagenta}●${ui.reset} ${ui.cyan}${e.name}${ui.reset}  ${ui.dim}${e.callSummary}${ui.reset}`;
+    }
+    // N>1:同类合并 "read_file 3, glob 1, grep 1"
+    const counts = new Map();
+    for (const e of entries)
+        counts.set(e.name, (counts.get(e.name) ?? 0) + 1);
+    const parts = [];
+    for (const [n, c] of counts)
+        parts.push(`${n} ${c}`);
+    return `  ${ui.brightMagenta}●${ui.reset} ${ui.dim}Ran ${entries.length} tools · ${parts.join(', ')}${ui.reset}`;
+}
+// ── 展开/折叠 ──
+/** 把 batch 的详情行展开成自洽行数组(供 layout.contentInsertAfter 走 mid-buffer 插入)。
+ *  每行末尾必须以 \x1B[0m 收尾(SGR 自洽模型),行内允许含 SGR(行末 reset 不影响行内样式),
+ *  但**绝不**带 \n——rows[] 是行数组,不是流输出。 */
+function buildExpandedLines(entries, indent = '    ') {
+    const lines = [];
+    for (const e of entries) {
+        lines.push(`${indent}${ui.brightMagenta}●${ui.reset} ${ui.cyan}${e.name}${ui.reset}  ${ui.dim}${e.callSummary}${ui.reset}\x1B[0m`);
+        if (e.diffBlock) {
+            // diff 块多行文本(由 renderFileChange 渲染);按 \n 拆成物理行,
+            // 每行单独入 rows[]。行末 reset 由本函数统一追加(若原行已带 reset,终端合并即可)。
+            const block = e.diffBlock.endsWith('\n') ? e.diffBlock : e.diffBlock + '\n';
+            for (const line of block.split('\n')) {
+                if (line === '' && lines.length > 0 && lines[lines.length - 1] === '')
+                    continue; // 折叠连续空行
+                if (line === '' && lines.length > 0)
+                    continue; // 跳过首尾空行(diff 头/尾换行)
+                lines.push(line.endsWith('\x1B[0m') ? line : line + '\x1B[0m');
+            }
+        }
+        else if (e.resultSummary) {
+            lines.push(`${indent}${ui.gray}↳ ${e.resultSummary}${ui.reset}\x1B[0m`);
+        }
+    }
+    return lines;
+}
+/** 在 batch 收尾时(onToolBatchEnd):写摘要行 + 登记 summaryAbsIdx;若已展开(回放场景)立即插详情。 */
+export function endBatch(id, layout) {
+    const b = batches.get(id);
+    if (!b || b.summaryAbsIdx >= 0)
+        return; // 幂等
+    // 含 mutation(write_file/edit_file)时强制展开——写盘操作必须让用户看到 diff
+    b.forceExpanded = b.entries.some((e) => isMutationTool(e.name));
+    // 单条 mutation 调用:摘要行("● edit_file path")与展开详情头逐字重复,跳过摘要行、只写详情
+    // (N>1 时摘要行是聚合信息 "Ran N tools · ...",与详情不重复,两者照常都写)。
+    if (b.forceExpanded && b.entries.length === 1) {
+        // 无摘要行可当父行,详情头改用顶层 2 空格缩进(与 buildSummaryLine/diff head 对齐,而非嵌套的 4 空格)
+        const lines = buildExpandedLines(b.entries, '  ');
+        layout.contentWrite(lines.join('\n') + '\n');
+        b.summaryAbsIdx = Math.max(0, layout.totalRows() - 1 - lines.length);
+        absLineToBatchId.set(b.summaryAbsIdx, b.id);
+        expandedBatches.add(b.id); // 已展开;防止 toggleBatch 再次 expand() 造成重复插入
+        return;
+    }
+    const summary = buildSummaryLine(b.entries);
+    // 写摘要行(以 \n 收尾;contentWrite 会 breakRow 让其成为完整物理行)
+    layout.contentWrite(summary + '\n');
+    // 摘要行绝对索引 = totalRows - 2(hasCurrent 那行是新空行)
+    b.summaryAbsIdx = Math.max(0, layout.totalRows() - 2);
+    absLineToBatchId.set(b.summaryAbsIdx, b.id);
+    // forceExpanded 时立刻展开(让 diff 在收尾后立即可见,无需点击)
+    if (b.forceExpanded) {
+        expand(b, layout);
+    }
+}
+/** 绝对行索引 → 命中 batch id(用于鼠标 release 反查);非摘要行返 null。 */
+export function findBatchByAbsLine(absLine) {
+    return absLineToBatchId.get(absLine) ?? null;
+}
+/** 当前 batch 是否已展开。 */
+export function isExpanded(id) {
+    return expandedBatches.has(id);
+}
+/**
+ * 切换 batch 展开/折叠;无变化时 no-op。
+ * 折叠:从 buffer 删详情行(mid-buffer delete);
+ * 展开:把详情行插入摘要行下方(mid-buffer insert)。
+ * 同步更新 absLineToBatchId 中所有受影响的索引:
+ *   - 删除/插入点之后的 batch 摘要行索引相应平移。
+ * 含 mutation(write_file/edit_file)的 batch 强制展开——不允许折叠(写盘操作必须始终可见)。
+ */
+export function toggleBatch(id, layout) {
+    const b = batches.get(id);
+    if (!b)
+        return;
+    if (b.forceExpanded) {
+        // 写盘操作的 batch 强制展开,toggle 拒绝折叠(用户能看到完整 diff 即用)
+        if (!expandedBatches.has(id))
+            expand(b, layout);
+        return;
+    }
+    if (expandedBatches.has(id)) {
+        collapse(b, layout);
+    }
+    else {
+        expand(b, layout);
+    }
+}
+function expand(b, layout) {
+    const lines = buildExpandedLines(b.entries);
+    layout.contentInsertAfter(b.summaryAbsIdx, lines);
+    expandedBatches.add(b.id);
+}
+function collapse(b, layout) {
+    const lines = buildExpandedLines(b.entries);
+    layout.contentDeleteFrom(b.summaryAbsIdx + 1, lines.length);
+    expandedBatches.delete(b.id);
+}
+/**
+ * 当 buffer 中段插/删 N 行后,所有受影响 batch 的 summaryAbsIdx 需平移。
+ * 由 layout.contentInsertAfter / contentDeleteFrom 在每次变动后调一次,
+ * 参数 afterIdx 是被插入/删除点的绝对索引(插入点之前索引不变;之后索引 += delta)。
+ */
+export function shiftBatchesAfter(absIdx, delta) {
+    if (delta === 0)
+        return;
+    // 重建 absLineToBatchId:删除所有 <= absIdx 的项,把 > absIdx 的项按 delta 平移
+    const next = new Map();
+    for (const [idx, id] of absLineToBatchId) {
+        if (idx <= absIdx) {
+            next.set(idx, id);
+        }
+        else {
+            const newIdx = idx + delta;
+            if (newIdx >= 0)
+                next.set(newIdx, id);
+        }
+    }
+    absLineToBatchId.clear();
+    for (const [k, v] of next)
+        absLineToBatchId.set(k, v);
+    // 同步每个 batch 的 summaryAbsIdx
+    for (const b of batches.values()) {
+        if (b.summaryAbsIdx > absIdx)
+            b.summaryAbsIdx = Math.max(0, b.summaryAbsIdx + delta);
+    }
+}
+// ── history 回放支持 ──
+/** 把已构造好的 BatchEntry[] 直接落成摘要行(用于 renderHistory 回放;不记录 id 也不需可切换)。
+ *  含 mutation(write_file/edit_file)时整批展开——与实时 endBatch 行为一致。 */
+export function writeSummaryOnly(entries, layout) {
+    const hasMutation = entries.some((e) => isMutationTool(e.name));
+    // 单条 mutation:同 endBatch,摘要行与展开详情头重复,跳过摘要行只写详情
+    if (hasMutation && entries.length === 1) {
+        const lines = buildExpandedLines(entries, '  ');
+        layout.contentWrite(lines.join('\n') + '\n');
+        return;
+    }
+    layout.contentWrite(buildSummaryLine(entries) + '\n');
+    if (hasMutation) {
+        // 回放时同步展开:重新调 expand 路径需要 BatchRecord,此处直接拼 line 插入
+        const summaryIdx = Math.max(0, layout.totalRows() - 2);
+        const lines = buildExpandedLines(entries);
+        layout.contentInsertAfter(summaryIdx, lines);
+        // 不入 batches/absLineToBatchId/expandedBatches——回放行不支持点击 toggle(设计取舍:
+        // 简化模型;若需要支持回放也可展开/折叠,可在 alt-screen 启动时建一张临时映射)
+    }
+}
+let _idCounter = 0;

package/dist/ui/content.js

@@ -136,3 +136,54 @@ export function lineAt(abs) {
     const all = snapshot();
     return abs >= 0 && abs < all.length ? all[abs] : null;
 }
+/**
+ * 在绝对行索引 after(0-based,已 commit)之后插入 N 条自洽行。
+ * 用于「折叠摘要行下展开明细」——把详情行在已写入摘要行后面塞入缓冲,
+ * 不重写尾部已有内容;且不影响更早的 buffer 行(hasCurrent 先 commit 再 splice)。
+ *
+ * 行须自洽(每行带行末 \x1B[0m),不经 feedChar/feedSgr,直接入 rows。
+ * after < 0 视为在所有已 commit 行之前插入;after ≥ 已 commit 行数则追加到末尾。
+ * 不动 segMark——此函数用于非 md 路径(BatchRenderer 展开/折叠);
+ * md 段切回 layout.contentWriteMd 时 setLines 仍按 segMark 截断。
+ *
+ * 后置条件:插入后 hasCurrent=false(新空行不由本函数建立);调用方须自行决定续写位
+ * (BatchRenderer 在插入后调 layout.contentWrite 续写,新 \n 自然在详情块后建新行)。
+ */
+export function insertAfter(after, lines) {
+    if (lines.length === 0)
+        return;
+    if (hasCurrent) {
+        rows.push(rowStartSgr + curRaw + '\x1B[0m');
+        curRaw = '';
+        rowStartSgr = curSgr;
+        hasCurrent = false;
+    }
+    const committed = rows.length;
+    // after 是绝对行索引;若超过 committed(例如快照时 hasCurrent=true),钳到末尾
+    const target = after < 0 ? 0 : Math.min(after + 1, committed);
+    rows.splice(target, 0, ...lines);
+    if (rows.length > MAX_ROWS + 512)
+        rows.splice(0, rows.length - MAX_ROWS);
+}
+/**
+ * 从绝对行索引 startIdx(0-based,已 commit)起删 n 行。
+ * 用于「已展开明细折回摘要」——把详情行从中段裁掉,保留摘要行和后续内容。
+ * startIdx 越界或 n <= 0 直接 no-op。hasCurrent 时先 commit(同 insertAfter)。
+ *
+ * 后置条件:删除后 hasCurrent=false。后续 layout.contentWrite 自然续写。
+ */
+export function deleteFrom(startIdx, n) {
+    if (n <= 0)
+        return;
+    if (hasCurrent) {
+        rows.push(rowStartSgr + curRaw + '\x1B[0m');
+        curRaw = '';
+        rowStartSgr = curSgr;
+        hasCurrent = false;
+    }
+    const committed = rows.length;
+    if (startIdx >= committed)
+        return;
+    const end = Math.min(startIdx + n, committed);
+    rows.splice(startIdx, end - startIdx);
+}

package/dist/ui/diff.js

@@ -191,11 +191,14 @@ function compactCtx(ops) {
     }
     return items;
 }
-function gutterOf(op) {
+function gutterOf(op, restoreBg = '') {
+    // restoreBg:add/del 行在 pushBody 处已铺底色,gutter 的 `${ui.reset}` 会清掉底色,所以
+    // reset 后必须重发 bg SGR,让该行后续字符继续带底色(否则 gutter 后一小段会变无色)。
+    const rb = restoreBg;
     if (op === 'del')
-        return `${ui.red}-${ui.reset}`;
+        return `${ui.red}-${ui.reset}${rb}`;
     if (op === 'add')
-        return `${ui.green}+${ui.reset}`;
+        return `${ui.green}+${ui.reset}${rb}`;
     return `${ui.dim} ${ui.reset}`;
 }
 function lineWord(n) {
@@ -261,7 +264,41 @@ function renderBody(head, counts, items, padW, startLine, lang) {
     let overflow = 0;
     const pushBody = (num, op, text) => {
         const numStr = String(num).padStart(padW);
-        lines.push(`${BODY_INDENT}${ui.gray}${numStr}${ui.reset} ${gutterOf(op)} ${codeText(text, lang)}`);
+        // 行级底色:add/del 整行包裹主题底色(addBg/delBg),行末由 codeText 内置 reset 闭合 →
+        // bg 不污染下一行。ctx 行不加底色(避免整个 diff 块被背景化,符合 GitHub / VSCode 视觉)。
+        // 注意 gutterOf 与 numStr 的 `${ui.reset}` 会清除之前累加的 bg,所以要紧跟一个 bg 恢复 SGR
+        // 才能让该行后续字符(代码区)继续带底色。
+        //   同时,代码区由 cli-highlight 渲染,内部会反复 ${fg}tok${reset}tok${fg}tok${reset}…
+        //   每个 reset 都会清掉外层 bg → 后面的 token 变无色。所以要在每个 reset 后重发 bg SGR
+        //   (行末那枚 reset 是收尾的,后面紧跟换行而非字符,不需补 bg)。用行末 reset 之外的 reset
+        //   计数 = 内部重发点。
+        const bg = op === 'add' ? ui.addBg : op === 'del' ? ui.delBg : '';
+        if (bg === '') {
+            lines.push(`${BODY_INDENT}${ui.gray}${numStr}${ui.reset} ${gutterOf(op)} ${codeText(text, lang)}`);
+            return;
+        }
+        const raw = `${bg}${BODY_INDENT}${ui.gray}${numStr}${ui.reset}${bg} ${gutterOf(op, bg)} ${codeText(text, lang)}${ui.reset}`;
+        // 在每个非行末的 ${ui.reset} 后重发 bg。行末 reset 紧跟行尾或换行,无需补。
+        // 简单做法:把除最后一个 reset 外的所有 reset 后都补 bg——但要注意 cli-highlight
+        // 输出的代码区段内部还有"省略号截断"${ui.dim}…${ui.reset},它的 reset 也需补 bg。
+        // 用 split 走一遍:找出所有 reset 位置(除最后那个),在其后插入 bg。
+        const resetStr = ui.reset;
+        const lastResetIdx = raw.lastIndexOf(resetStr);
+        if (lastResetIdx < 0) {
+            lines.push(raw);
+            return;
+        }
+        // 把 raw 切成 [prefix + 末 reset] + (中间所有 reset 替换为 reset+bg)
+        const prefix = raw.slice(0, lastResetIdx);
+        const tail = raw.slice(lastResetIdx);
+        // 头部所有 reset 之后插 bg(注:用 split 重建)
+        const parts = prefix.split(resetStr);
+        // parts[i] 是第 i 段,紧跟一段 reset(最后一段后无 reset,故少一个元素)
+        let rebuilt = parts[0];
+        for (let i = 1; i < parts.length; i++) {
+            rebuilt += resetStr + bg + parts[i];
+        }
+        lines.push(rebuilt + tail);
     };
     for (const it of items) {
         if (shown >= MAX_BODY_LINES) {

package/dist/ui/intervention.js

@@ -1,7 +1,7 @@
 import readline from 'node:readline';
 import { stdin, stderr } from 'node:process';
 import { ui } from './theme.js';
-import { displayWidth, truncateDisplay } from './render.js';
+import { displayWidth, truncateDisplay, wrapByDisplayWidth } from './render.js';
 import * as layout from './layout.js';
 import * as mouse from './mouse.js';
 import { Spinner } from './spinner.js';
@@ -15,12 +15,16 @@ export async function promptIntervention(req) {
         const kind = req.type === 'choice' ? '自动选默认项' : '自动返回空输入';
         stderr.write(`[介入] ${req.title}(非交互环境,${kind})\n`);
         if (req.type === 'choice') {
-            return { action: 'selected', value: req.options?.[0] ?? '' };
+            const first = req.options?.[0];
+            const value = typeof first === 'string' ? first : first?.label ?? '';
+            return { action: 'selected', value };
         }
         return { action: 'submitted', value: req.seed ?? '' };
     }
     const options = req.type === 'choice' && Array.isArray(req.options)
-        ? req.options.map((o) => String(o)).filter((s) => s.length > 0)
+        ? req.options
+            .map((o) => typeof o === 'string' ? { label: o } : { label: String(o.label ?? ''), detail: o.detail })
+            .filter((o) => o.label.length > 0)
         : [];
     // choice 但选项被滤空 → 降级 input(对齐设计文档 §8:ask_human 选项为空数组→input)。
     const startMode = req.type === 'choice' && options.length > 0 ? 'choice' : 'input';
@@ -36,14 +40,23 @@ export async function promptIntervention(req) {
     let resolve;
     // 挂自己监听前快照的现有 keypress 监听(运行态即 onRunningKey),退出时按原序恢复。
     let savedListeners = [];
-    /** choice 菜单行:标题(bold)+ detail(dim,行数上限保选项可见)+ 空行 + 选项(▸ 选中/dim)。 */
+    /** choice 菜单行:标题(bold)+ 背景 detail(dim,行数上限保选项可见)+ 空行 + 选项(▸ label,有 detail 的项用全角括号()拼到 label 同行)。 */
     function menuLinesChoice() {
         const g = layout.getGeo();
         const cols = g.cols;
-        const items = [...options, CUSTOM_LABEL];
+        const allowCustom = req.allowCustom !== false;
+        const items = allowCustom ? [...options, { label: CUSTOM_LABEL }] : [...options];
         const optionCount = items.length;
-        // detail 上限:title(1)+detail(D)+空行(1)+options(O) ≤ contentBottom → D ≤ contentBottom-2-O
-        const detailCap = Math.max(0, g.contentBottom - 2 - optionCount);
+        // 每项占行数 = label + （detail）整体 wrap 到可用宽度后的实际行数(超长换行,不再省略)。
+        // 短 label 仍只占 1 行;长 detail 自然占用多行,菜单总高度随之动态增长。
+        const rowsFor = (o) => {
+            const prefixWidth = 2 + (optionCount <= 9 ? 3 : 4); // 保守:覆盖 1. 与 10. 两种前缀
+            const text = o.label + (o.detail ? `（${o.detail}）` : '');
+            return Math.max(1, wrapByDisplayWidth(text, Math.max(1, cols - prefixWidth)).length);
+        };
+        const totalOptionRows = items.reduce((n, o) => n + rowsFor(o), 0);
+        // detail 上限:title(1)+detail(D)+空行(1)+options(totalOptionRows) ≤ contentBottom
+        const detailCap = Math.max(0, g.contentBottom - 2 - totalOptionRows);
         const lines = [];
         lines.push(`${ui.bold}${truncateDisplay(req.title, cols)}${ui.reset}`);
         if (req.detail) {
@@ -56,21 +69,47 @@ export async function promptIntervention(req) {
                 lines.push(`${ui.dim}…${ui.reset}`);
         }
         lines.push(''); // 分隔空行
-        // 选项开窗:超屏高时以 selected 为中心取窗,保选中项可见。
+        // 选项开窗:超屏高时以 selected 为中心收选中项可见。
         const maxOptRows = Math.max(1, g.contentBottom - lines.length);
         let start = 0;
-        if (optionCount > maxOptRows) {
-            start = Math.max(0, Math.min(selected - Math.floor(maxOptRows / 2), optionCount - maxOptRows));
+        {
+            let acc = 0;
+            let s = 0;
+            for (let i = 0; i <= selected && i < optionCount; i++)
+                acc += rowsFor(items[i]);
+            while (acc > maxOptRows && s < selected) {
+                acc -= rowsFor(items[s]);
+                s++;
+            }
+            start = s;
         }
-        const count = Math.min(maxOptRows, optionCount);
-        for (let i = 0; i < count; i++) {
-            const idx = start + i;
+        let used = 0;
+        let idx = start;
+        while (idx < optionCount) {
+            const o = items[idx];
+            const rows = rowsFor(o);
+            if (used + rows > maxOptRows && idx > start)
+                break;
             // 选中项:▸ 与正文均 cyan+bold(去 dim),未选中项保持 dim——选中行整体高亮。
             const isSel = idx === selected;
             const color = isSel ? `${ui.cyan}${ui.bold}` : ui.dim;
             const marker = isSel ? `${ui.cyan}${ui.bold}▸${ui.reset}` : ' ';
-            const body = truncateDisplay(items[idx], cols - 2);
-            lines.push(`${marker} ${color}${body}${ui.reset}`);
+            // 数字前缀:只标真实选项(1-9,与 onKeyChoice 的数字直选对应);"自定义"项不占号。
+            const numStr = idx < options.length ? `${idx + 1}. ` : '';
+            const prefixWidth = 2 + numStr.length; // marker(1)+空格(1)+numStr
+            // 有 detail 的项:把说明拼到 label 后面、用全角括号()包裹;按可用宽度 wrap 多行(超长换行不再省略)。
+            // 第 1 行画 marker+numStr,后续行只画占位空白(prefixWidth)使 label 视觉上悬挂缩进、保持对齐。
+            // 颜色随 label 走(选中 cyan+bold、未选 dim),保持多行视觉整体性。
+            const detailSuffix = o.detail ? `（${o.detail}）` : '';
+            const fullText = o.label + detailSuffix;
+            const wrapped = wrapByDisplayWidth(fullText, Math.max(1, cols - prefixWidth));
+            const pad = ' '.repeat(prefixWidth);
+            for (let li = 0; li < wrapped.length; li++) {
+                const prefix = li === 0 ? `${marker} ${numStr}` : pad;
+                lines.push(`${prefix}${color}${wrapped[li]}${ui.reset}`);
+            }
+            used += rows;
+            idx++;
         }
         return lines;
     }
@@ -102,7 +141,6 @@ export async function promptIntervention(req) {
                 cursorLine: 0,
                 cursorCol: displayWidth(hint),
                 menu: { lines: menuLinesChoice() },
-                caret: false, // 纯导航(非文本输入):不画输入框块状光标,聚焦由选项 ▸ 标记
             });
         }
         else {
@@ -182,7 +220,8 @@ export async function promptIntervention(req) {
         }
     }
     function onKeyChoice(key) {
-        const itemCount = options.length + 1; // +自定义项
+        const allowCustom = req.allowCustom !== false;
+        const itemCount = allowCustom ? options.length + 1 : options.length;
         switch (key.name) {
             case 'up':
                 selected = (selected - 1 + itemCount) % itemCount;
@@ -194,7 +233,7 @@ export async function promptIntervention(req) {
                 return;
             case 'return':
             case 'enter':
-                if (selected === options.length) {
+                if (allowCustom && selected === options.length) {
                     // 自定义项 → 切 input 子态(空文本起)
                     mode = 'input';
                     cameFromChoice = true;
@@ -203,7 +242,7 @@ export async function promptIntervention(req) {
                     redraw();
                 }
                 else {
-                    finish({ action: 'selected', value: options[selected] });
+                    finish({ action: 'selected', value: options[selected]?.label });
                 }
                 return;
         }
@@ -212,7 +251,7 @@ export async function promptIntervention(req) {
         if (s >= '1' && s <= '9') {
             const n = Number(s) - 1;
             if (n < options.length) {
-                finish({ action: 'selected', value: options[n] });
+                finish({ action: 'selected', value: options[n].label });
             }
         }
     }