mocode-ai 0.4.8 → 0.4.10

package/dist/ui/content.js

@@ -136,6 +136,60 @@ export function lineAt(abs) {
     const all = snapshot();
     return abs >= 0 && abs < all.length ? all[abs] : null;
 }
+/**
+ * 找「绝对行索引 < absStart 的最近一条用户消息」的文本(用于滚动回看时的「我刚发的
+ * 请求」sticky banner)。算法:从 absStart - 1 往上扫,识别「用户气泡行」(由 repl
+ * formatUserMessage 写入,剥 SGR 后首字符 = ❯);再从此行往下吞连续的同类行
+ * 收集多行消息,join('\n')。
+ *
+ * 检测 user-bubble 行靠「剥 SGR 后以 ❯ 开头」而非 userBg SGR 前缀:rowStartSgr 继承自
+ * 上一行末(可能残留 dim/cyan),且 bubble 起手有 userBg 包裹,直接 startsWith(userBg)
+ * 在残留 rowStartSgr 场景会漏判。剥光所有 SGR 后 → 首字符稳定为 ❯ (repl.PROMPT)。
+ *
+ * 返回的文本已经剥离 ANSI + 提示符,可直接给 banner 渲染(再做截断 / 折叠)。
+ * absStart ≤ 0 返 null(没东西在视口上方)。
+ */
+export function lastUserMessageBefore(absStart) {
+    if (absStart <= 0)
+        return null;
+    const all = snapshot();
+    const SGR = /\x1B\[[0-9;]*m/g;
+    const isUserBubbleRow = (row) => {
+        // 剥光 SGR 后首字符 = ❯(repl.PROMPT 首字)→ 是 user bubble;
+        // agent 行首字符可能是 ● / ╭ / │ / 数字 / 字母,绝不会撞 ❯。
+        const visible = row.replace(SGR, '');
+        return visible.startsWith('❯');
+    };
+    // 1) 从 absStart - 1 往上扫,找第一条 user bubble 行(最近的 user-bubble 的最后一行)
+    let bubbleEnd = -1;
+    for (let i = Math.min(absStart, all.length) - 1; i >= 0; i--) {
+        if (isUserBubbleRow(all[i])) {
+            bubbleEnd = i;
+            break;
+        }
+    }
+    if (bubbleEnd < 0)
+        return null;
+    // 2) 往上找气泡起点(连续 user-bubble 行块 = 同一条 user 消息)
+    let bubbleStart = bubbleEnd;
+    while (bubbleStart - 1 >= 0 && isUserBubbleRow(all[bubbleStart - 1])) {
+        bubbleStart--;
+    }
+    // 3) 收文本:按显示字符剥 SGR + 续行/末填充空格 + 首行 prompt
+    //    首行剥前导 '❯ ' 序列 → banner 自己再加回 [banner_prompt] + <text>;
+    //    一次剥光所有重复的 ❯(防止用户手敲 prompt / 多重回显 → 出现 '❯ ❯ ...' 双提示符)。
+    const joinedText = all
+        .slice(bubbleStart, bubbleEnd + 1)
+        .map((raw, idx) => {
+        let stripped = raw.replace(SGR, '');
+        if (idx === 0)
+            stripped = stripped.replace(/^(?:❯\s*)+/, ''); // 剥光所有前导 ❯(含每个后面的可选空格)
+        return stripped.trimEnd();
+    })
+        .join('\n')
+        .replace(/\n+$/, '');
+    return joinedText || null;
+}
 /**
  * 在绝对行索引 after(0-based,已 commit)之后插入 N 条自洽行。
  * 用于「折叠摘要行下展开明细」——把详情行在已写入摘要行后面塞入缓冲,
@@ -143,8 +197,8 @@ export function lineAt(abs) {
  *
  * 行须自洽(每行带行末 \x1B[0m),不经 feedChar/feedSgr,直接入 rows。
  * after < 0 视为在所有已 commit 行之前插入;after ≥ 已 commit 行数则追加到末尾。
- * 不动 segMark——此函数用于非 md 路径(BatchRenderer 展开/折叠);
- * md 段切回 layout.contentWriteMd 时 setLines 仍按 segMark 截断。
+ * 若 segMark 活跃且插入点在 segMark.rowIdx 之前,则 segMark.rowIdx 跟着平移(否则
+ * 流式 md 段活跃期间展开/折叠 batch 后,下一个 md chunk 的 setLines 截断到错误位置)。
  *
  * 后置条件:插入后 hasCurrent=false(新空行不由本函数建立);调用方须自行决定续写位
  * (BatchRenderer 在插入后调 layout.contentWrite 续写,新 \n 自然在详情块后建新行)。
@@ -162,6 +216,11 @@ export function insertAfter(after, lines) {
     // after 是绝对行索引;若超过 committed(例如快照时 hasCurrent=true),钳到末尾
     const target = after < 0 ? 0 : Math.min(after + 1, committed);
     rows.splice(target, 0, ...lines);
+    // 流式 md 段活跃期间:插入点在段起点之前 → segMark.rowIdx 平移,
+    // 否则下一个 md chunk 的 setLines 截断到旧位置,展开行被砍掉。
+    if (segMark && target <= segMark.rowIdx) {
+        segMark.rowIdx += lines.length;
+    }
     if (rows.length > MAX_ROWS + 512)
         rows.splice(0, rows.length - MAX_ROWS);
 }
@@ -185,5 +244,11 @@ export function deleteFrom(startIdx, n) {
     if (startIdx >= committed)
         return;
     const end = Math.min(startIdx + n, committed);
-    rows.splice(startIdx, end - startIdx);
+    const actual = end - startIdx;
+    rows.splice(startIdx, actual);
+    // 流式 md 段活跃期间:删除区间全部在段起点之前 → segMark.rowIdx 回退,
+    // 否则下一个 md chunk 的 setLines 截断到旧位置,段内容错位。
+    if (segMark && startIdx + actual <= segMark.rowIdx) {
+        segMark.rowIdx -= actual;
+    }
 }

package/dist/ui/diff.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 文件改动 diff 渲染(仿 Claude Code):
+ *   Update(path) / Create(path) + Added N lines, removed M lines
+ *   正文带文件行号 + `-` 红 / `+` 绿 gutter + 代码经 cli-highlight 语法高亮。
+ *
+ * 纯渲染叶子模块——不依赖 config / 业务;颜色经 theme 非 TTY 退化为空串,
+ * 输出供 layout.contentWrite 写入(区域滚动 / 底栏保护 / 续写位跟踪均由其内置)。
+ * 高亮逐行做(每行自成 SGR 闭区间,末尾补 reset 防跨行泄漏);多行构造(块注释 / 模板串)的内部行可能不上色,可接受。
+ */
+/** 行级 diff 单元:ctx 不变 / add 新增 / del 删除。 */
+export type DiffOp = 'ctx' | 'add' | 'del';
+export interface DiffLine {
+    op: DiffOp;
+    text: string;
+}
+/**
+ * 行级 LCS diff。返回 op 序列(ctx/add/del)。
+ * 任一边超 MAX_FULL_DIFF_LINES 返回 null(降级,由调用方走「省略 diff」分支)。
+ */
+export declare function lineDiff(oldS: string, newS: string): DiffLine[] | null;
+/**
+ * 渲染文件改动块(供 layout.contentWrite 写入)。
+ *  - kind:'edit' 头行用 Update;kind:'write' 用 Update(覆盖)/ Create(oldStr===null 新建)。
+ *  - oldStr===null 表示新建:正文只显 + 行,行号从 1。
+ *  - startLine:diff 首行对应的文件行号(edit_file 由调用方定位 old_string 起始行;write_file 传 1)。
+ *  - diff 过大(超 MAX_FULL_DIFF_LINES)时仅显头行 + 「file too large, diff omitted」。
+ */
+export declare function renderFileChange(opts: {
+    path: string;
+    kind: 'edit' | 'write';
+    oldStr: string | null;
+    newStr: string;
+    startLine?: number;
+}): string;

package/dist/ui/diff.js

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

package/dist/ui/intervention.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 介入面板:agent 执行中遇到需要用户决策的岔路时,弹问题 + 选项让用户选择(ask_human 工具调用)。
+ * 仿 Claude Code 的 ask / AskUserQuestion:用户可挑预设选项,也可选"自定义输入"自由作答。
+ *
+ * 渲染复用 promptTurnPicker 的模式(layout.paintInput:菜单向上展开进内容区底、提示/输入放底栏),
+ * 不碰固定边框、不用 DECSC/DECRC、逐行 \x1B[2K 擦除(符合 TUI 不变量)。
+ *
+ * 两个冲突由本函数自行处理(因 ask_human 在 executeTool 内被调,此时 agent 处 RUNNING 态):
+ *  1. spinner 在转(agent 在 await executeTool 前调了 spinner.start('执行 ask_human'),onFrame 每 80ms
+ *     paintLiveAtCursor 画帧会覆盖面板)→ 进入前 Spinner.pauseCurrent() 停转。
+ *  2. repl 的 onRunningKey 在整个 runAgent 期间已挂载(↑/↓ 当滚动、Ctrl+C 当中断、可打印键当 typeahead
+ *     回显)→ 快照并摘掉现有 keypress 监听、挂自己的 onKey,退出 finally 按原序恢复。
+ * 滚轮:面板内滚轮只滚动查看 agent 输出内容(↑↓ 才选菜单),与 onRunningKey 一致;菜单经 scrollBy 末尾
+ * repaint()→paintInput(lastView) 重画,不被 viewport 滚动覆盖。进入时 resetScroll 回尾,退出时若滚过再回尾。
+ * 退出时 paintInput(dim,menu:null) 擦菜单 + 复位 lastMenuRows,再 resetScroll(面板内滚过)/repaintViewport
+ * 从缓冲重画内容区(恢复被菜单覆盖的 ● ask_human 行);顺序不可反——反了 stale lastMenuRows 会擦掉已恢复的内容。
+ *
+ * 非 TTY(管道/CI):不弹面板,choice 自动选第一项、input 返回 seed/空,打一行 stderr 日志,不阻塞。
+ */
+export type InterventionType = 'choice' | 'input';
+/** choice 单个选项:label 是选项本身(选中后回传的值),detail 是选它意味着什么/取舍(可选,渲染时与 label 同行、用全角括号()包裹)。 */
+export interface ChoiceOption {
+    label: string;
+    detail?: string;
+}
+export interface InterventionRequest {
+    type: InterventionType;
+    /** 问题/标题,显示在面板顶部。 */
+    title: string;
+    /** choice 的选项列表(2~6 个);为空则降级 input。纯字符串 = 无说明,等价 {label}。 */
+    options?: Array<string | ChoiceOption>;
+    /** 背景说明,显示在标题下(可多行)。 */
+    detail?: string;
+    /** input 模式预填文本。 */
+    seed?: string;
+    /** choice 末尾是否追加「其他(自定义输入)」项。默认 true;只有调用方确实想关掉才传 false。 */
+    allowCustom?: boolean;
+}
+export interface InterventionResult {
+    /** selected=选中某选项;submitted=提交自定义文本;cancelled=用户取消(Esc/Ctrl+C)。 */
+    action: 'selected' | 'submitted' | 'cancelled';
+    /** selected=选项文本;submitted=输入文本;cancelled 时无。 */
+    value?: string;
+}
+/** 弹出介入面板,阻塞直到用户完成选择。 */
+export declare function promptIntervention(req: InterventionRequest): Promise<InterventionResult>;

package/dist/ui/layout.d.ts

@@ -0,0 +1,225 @@
+/**
+ * 全屏 TUI 布局(参考 Claude Code):alt screen + 单滚动区域(内容区)+ 区域外固定底栏(状态行 + 输入框)。
+ *
+ * 只依赖最成熟、Windows(WT / conhost)最稳的 ANSI 子集:
+ *  - alt screen        \x1B[?1049h / \x1B[?1049l
+ *  - DECSTBM 滚动区域  \x1B[<top>;<bottom>r   (区域内写满自动在区域内滚动,区域外底栏不被顶)
+ *  - 逐行擦除          \x1B[2K / \x1B[K        (菜单 / 清屏,绝不用 ED \x1B[J 做边界擦除)
+ *  - CUP 绝对定位      \x1B[<row>;<col>H
+ * 不用原点模式(\x1B[?6h)、不依赖 ED 边界、不用 DECSC/DECRC、不用 IL/DL/SU/SD——这些在 conhost 上不可靠。
+ *
+ * 续写位(contentRow / contentCol)由 contentWrite 按字符宽度 + 折行模拟跟踪;CUP 到它即可随时回到内容续写位,
+ * 故底栏刷新(状态行 / spinner)无需保存/恢复光标——CUP 回续写位即可。
+ *
+ * 关键洞察:RUNNING 态也支持 typeahead 输入与滚动回看。INPUT 态光标常驻输入框;RUNNING 态光标在续写位,
+ * 运行中打的字经 paintRunningInputEcho 作 dim 回显(占位行换成已打文本,光标仍留续写位,不与流式争用);
+ * 运行中可滚动回看——contentWrite 在 scrollOffset>0 时只喂缓冲不物理写(否则新流式覆盖 viewport 历史行),
+ * 回尾(scrollOffset===0)才 cup 续写位写出。两态切换不重设区域(底栏高度恒 = 2),仅多行输入换行撑高时才 setRegion。
+ *
+ * 非 TTY:全部空操作,contentWrite 退化为 stdout.write,与改造前内联行为一致。
+ */
+export interface Geo {
+    rows: number;
+    cols: number;
+    footerH: number;
+    contentTop: number;
+    contentBottom: number;
+}
+export interface StatusBarData {
+    model: string;
+    contextBar: string;
+    cwd: string;
+    status: string;
+    spinnerFrame?: string;
+    modeTag?: string;
+    /** 活跃 plan 短摘要(无 plan=undefined,空串=有 plan 但 chip 不显)。repl 透传 getActivePlanSummary()。 */
+    planSummary?: string;
+    /** 本轮最后一条 token 用量(modeTag chip 右边显示)。后端不开 include_usage 时 undefined。
+     *  cachedTokens 可选 —— 后端未报或老 ChatUsage 字面量不带此字段时 UI 不会显示缓存标记。 */
+    lastTurnUsage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cachedTokens?: number;
+    };
+}
+export interface InputView {
+    prompt: string;
+    lines: string[];
+    cursorLine: number;
+    cursorCol: number;
+    menu: {
+        lines: string[];
+    } | null;
+    dim?: boolean;
+    placeholder?: string;
+}
+export declare function getGeo(fh?: number): Geo;
+/** (重)设滚动区域 [1, rows-footerH];设完 \x1B[H 归位(conhost 设 DECSTBM 时光标留旧位置行为未定义)。 */
+export declare function setRegion(fh: number): Geo;
+export declare function contentMode(): void;
+/** 运行态用户是否在打字(近期有按键)——是则暂停流式物理写(contentWrite/drawStatusBar/paintLiveAtCursor 跳过物理写),光标留输入框,IME 候选窗稳定不跟流式跑。 */
+export declare function isStreamingPaused(): boolean;
+/**
+ * 运行态用户打字时调(repl onRunningKey 每次按键):标记活跃 + 重置 flush 定时器。
+ * 活跃期间流式只喂缓冲不物理写(光标不入内容区);用户停手 USER_ACTIVE_PAUSE_MS 后 flush:
+ * repaintViewport 重画缓冲内容 + drawStatusBar 刷状态行 + 光标归输入框。
+ * 解决 IME 候选窗跟流式输出跑:流式写必须 cup 到 contentRow,IME 逐光标跟踪→气泡跟跑;打字时暂停写则光标不动。
+ */
+export declare function setUserActive(): void;
+/**
+ * 内容区正文写:CUP 到续写位 + 写出 + 按字符宽度/折行更新续写位 + 同步入 content 缓冲(供滚动回看)。
+ * 滚动区域内写满自动在区域内滚动,底栏在区域外不被顶。非 TTY / 未激活:直接 stdout.write(内联退化)。
+ *
+ * 逐字符分类(按码点取字符,SGR 序列整段识别):SGR 码 → 0 宽跟踪 + content.feedSgr;其他 CSI/OSC → 跳过
+ * (callers 理论上不传);\n / 折行 / tab 换行 → 行推进 + content.breakRow;可见字符 → charWidth 跟踪 +
+ * content.feedChar。SGR 在终端 0 宽,故续写位只按可见字符推进(与终端实际光标一致)。
+ */
+export declare function contentWrite(s: string): void;
+/**
+ * markdown 正文写(替代 contentWrite 用于 agent onText):累积 chunk 到 mdBuf,每 chunk 把整段
+ * mdBuf 经 renderMarkdown 渲成自洽 ANSI 行,replace 缓冲段(content.setLines 截旧 + 写新),
+ * repaintViewport 重画(仅尾 offset=0 且未暂停)。流式安全:未闭合 fence 照常 emit 进行中代码块;
+ * renderMarkdown 内部 memo by text 使重复渲染命中缓存。非 TTY / 未激活:直接 stdout.write(与
+ * contentWrite 一致,管道流式可见)。
+ *
+ * 续写位 = 段末下一行(段占 lines.length 行从 segmentStartRow 起);超可视区则滚动留 contentBottom。
+ * 物理重画用 repaintViewport(全内容区,原子一次 write 无闪烁)— md 段是缓冲尾,viewport 显尾即显段。
+ * 滚动回看(scrollOffset>0)只更新缓冲不物理写(回尾时显);打字中照常物理写——单次 write 结尾 cup 回输入框,IME 锚定不动。
+ */
+export declare function contentWriteMd(s: string): void;
+/**
+ * 把一段完整(非流式)assistant 文本一次性渲染成 markdown 写入(供 renderHistory 回显
+ * /resume / /rollback 复显上下文):渲染一次 → join('\n') → 经 contentWrite 增量写
+ * (无段 erase / 无 repaintViewport,无闪烁)。与流式 contentWriteMd 的区别:不累积 chunk、
+ * 不走段替换——一次性把渲染结果当普通带色文本喂入(渲染行各自 ≤ cols、自洽带色,contentWrite
+ * 的 SGR/折行状态机原样接纳)。非 TTY:退化为 stdout.write 原文(同 contentWrite)。
+ */
+export declare function contentWriteMdOnce(s: string): void;
+/** 清空内容区(保留底栏):全屏清 + 重设区域 + 续写位归 (1,1) + 清缓冲 + 回尾。底栏由调用方随后重画。 */
+export declare function clearContent(): void;
+/**
+ * 撤销(rewind)内容区末尾 n 物理行 —— 供 "刚 echoInput 写下用户气泡、用户撤回"
+ * 把气泡从可视区与 buffer 一起拿掉。content.rewind 弹出 buffer 末 n 行;layout 这边
+ * 同步上溯 contentRow(contentTop 钳位,防下溢)、scrollOffset 钳到新 totalRows、
+ * 最后 repaintViewport 重画可视区(running 态回 runningCaretPos,input 态回续写位)。
+ *
+ * 与 clearContent 不同:只擦最近一段、保留更早内容与 buffer;光标归内容区底,
+ * 不是 (1,1)。常发生在 RUNNING 态的 pending 窗口内 recall —— recall 后调用方
+ * 通常再 enterInputMode 切回 INPUT 视觉,光标由后续 paintInput 重画。
+ */
+export declare function rewindContent(rowsToRewind: number): void;
+/**
+ * 在绝对行索引 after 后插入自洽行(详情展开用)。
+ * 滚动回看冻结:scrollOffset>0 时 offset += delta 把窗口冻在原绝对行,
+ * 与 contentWrite/contentWriteMd 同模式。插入后 repaintViewport 重画 viewport。
+ *
+ * 续写位(contentRow):若原写头在插入点之后,前移 lines.length,保持相对位置;
+ * 若原写头 ≤ after,不变(新行在写头之后)。非 TTY 直接调 content.insertAfter。
+ */
+export declare function contentInsertAfter(after: number, lines: string[]): void;
+/**
+ * 从绝对行索引 startIdx 起删 n 行(折叠回退用)。
+ * 滚动回看冻结同 insertAfter:offset -= delta,钳 ≥ 0。续写位若在删区后前移 delta。
+ */
+export declare function contentDeleteFrom(startIdx: number, n: number): void;
+/** 当前内容物理行总数(含当前未提交行)。供 batch 渲染器在 endBatch 时定位摘要行索引。 */
+export declare function totalRows(): number;
+/** 清空内容区时通知 batch 渲染器重置(摘要行映射与展开态)。 */
+export declare function notifyContentReset(): void;
+/** 是否处于滚动回看态(offset>0,内容区显历史)。prompt 据此在非滚动键时回尾。 */
+export declare function isScrolled(): boolean;
+/**
+ * 重画内容区 viewport:按 scrollOffset 取缓冲尾窗,逐行 cup+clearline+rowtext 映射到屏 1..contentBottom。
+ * offset=0 即尾窗(== 实时屏,resize / 回尾时用)。清行含 contentBottom——顺带擦 WT 边距漏影(状态行重复)。
+ * 有活跃选区(鼠标拖拽中)时,对选中范围套反白——纯视觉,不影响缓冲内容。
+ */
+export declare function repaintViewport(): void;
+/** 滚动 delta 行(正=往新、负=往旧);钳 [0, max(0, total-contentBottom)];变则重画 + 刷底栏(显指示、光标回输入框)。 */
+export declare function scrollBy(delta: number): void;
+/** 清活跃选区(不复制),若原有选区则重画去掉反白。供 ESC / 点击别处 / 退出滚动态等场景调。 */
+export declare function clearSelection(): void;
+/**
+ * 注册"点击输入框粘贴"回调:当前持有文本输入的模块(prompt.ts 的 promptWithSlashMenu / repl 运行态
+ * typeahead)在挂键盘监听时调,退出时传 null 注销。点击输入行(未拖动)时 layout 读剪贴板后回调此函数,
+ * 由回调方完成插入(各输入状态的行/光标结构不同,layout 不掺和文本编辑逻辑,只管"贴入"这个动作触发)。
+ */
+export declare function setPasteHandler(fn: ((text: string) => void) | null): void;
+/** 注册"点击输入框 → 改光标"回调:prompt.ts 等文本所有者挂此回调后,
+ *  鼠标左键落输入行算出的新 (line, col) 会在 prompt 下次 redraw 前喂入此回调
+ *  (prompt 用它写自己的 cl / cc,真正改 source of truth)。
+ *  传 null 注销(在 cleanup / 退出输入态时调,防下个 prompt 实例被旧回调污染)。 */
+export declare function setCursorChangeHandler(fn: ((line: number, col: number) => void) | null): void;
+/** picker / 介入面板期间禁用鼠标选区与拖拽(避免 viewport 重画覆盖菜单);滚轮仍可用。面板退出后恢复。 */
+export declare function setMouseEnabled(v: boolean): void;
+/** 回尾(offset=0);仅当原本滚动过才重画(避免每轮 enterRunningMode 闪烁)。 */
+export declare function resetScroll(): void;
+/** 发消息轮首短时锁住滚动:吸收 stdin 残留滚轮事件(发消息前后的滚轮惯性 / OS 缓冲延迟到达),
+ *  防 resetScroll 回尾后被 onRunningKey 接到的残留事件重新滚上去——致 agent 输出进缓冲、显示在历史区。
+ *  锁只挡 scrollBy(滚轮 / PgUp-PgDn);不影响 contentWrite 写屏(offset=0 时照常物理写,agent 输出从底部开始)。
+ *  默认 SCROLL_LOCK_MS 后自动解锁;enterInputMode(轮末)也清锁。用户轮中后段仍可上滑(满足"输出时能看历史")。 */
+export declare function lockScrollToBottom(ms?: number): void;
+/** 解锁(轮末 enterInputMode / 测试用)。 */
+export declare function unlockScroll(): void;
+/** 轮首滚动锁是否生效(测试用)。 */
+export declare function isScrollLocked(): boolean;
+/** 画状态行(plan 行 + spinner 行 + model 行,三行)。RUNNING 态 spinner 频繁调。
+ *  行号(footerH=6):
+ *    plan 行     = contentBottom+1  (活跃 plan 时显 chip;无则空)
+ *    spinner 行  = contentBottom+2  (◆ 空闲 / ⠹ 思考中… / etc)
+ *    上线        = contentBottom+3  (画在 paintInput)
+ *    输入行      = contentBottom+4
+ *    下线        = contentBottom+5
+ *    model 行    = rows              (屏底:auto + ctx + cwd) */
+export declare function drawStatusBar(status?: StatusBarData): void;
+/** 更新易变状态(状态文字 + spinner 帧)并重画状态行。spinner / agent 用。 */
+export declare function setStatus(status: string, frame?: string): void;
+/**
+ * 在续写位画一行瞬时活动文本(spinner 帧):不进缓冲、不推进续写位,逐行 clearLine 重画。
+ * 仅 TTY + offset=0(实时尾)+ 非打字暂停态时物理写屏;滚动态跳过(由状态行 spinner 兜底,且避免覆盖 viewport 历史行)。
+ * 配合 clearLiveAtCursor 在 spinner 停时清掉,随后 contentWrite 的结果即写在该行(spinner 不入历史缓冲)。
+ *
+ * 记 frameRow/frameCol = 实际画帧位置;clearLiveAtCursor 清"这行"而非当前续写位,防续写位漂移时清错行。
+ * 续写位漂移时(运行期间被某次 contentWrite 推进,罕见但 557e678 后可能)先清旧 frameRow 再画新位,避免旧帧残留。
+ * 打字暂停态(isStreamingPaused)spinner 不画帧——恢复 557e678 前的 spinner 隐形行为(只关 spinner,不动 contentWrite)。
+ */
+export declare function paintLiveAtCursor(text: string): void;
+/** 清掉 paintLiveAtCursor 画过的那行瞬时活动文本。清"实际画过的位置"(frameRow),非当前续写位。
+ *  不加 isStreamingPaused 守卫——stop 时必须无条件清(只写一次、结尾 cup 回输入框,不扰 IME);否则打字中 stop 会跳过清帧、制造泄漏。
+ *  滚动态(scrollOffset≠0)也必须清残留帧——否则旧 spinner 帧卡在历史视图某行(「思考中在消息堆里」根因)。 */
+export declare function clearLiveAtCursor(): void;
+/** 更新状态行基线(模型 / context / cwd / 模式标识 / 活跃 plan chip / 本轮 token chip)。repl 在轮次边界与切模式时调。 */
+export declare function setStatusBase(b: {
+    model: string;
+    contextBar: string;
+    cwd: string;
+    modeTag?: string;
+    planSummary?: string;
+    lastTurnUsage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}): void;
+/**
+ * 画输入区:擦旧菜单 → (必要时)setRegion → 画状态行 + 输入行 + 向上菜单,光标留输入框(dim 时回续写位)。
+ * prompt.ts 每次按键调;enterInputMode / enterRunningMode 也调(空 / dim)。
+ */
+export declare function paintInput(view: InputView): void;
+/**
+ * 运行态 typeahead 回显:定向写输入行(底栏输入框),把 dim 占位换成已打字文本 + 反白块状光标(无打字时光标在起点)。
+ * 只 cup 输入行 + clearLine + dim 文本 + 归位——不调 setRegion(运行中禁多行,避免 DECSTBM 抖动)、
+ * 不重画状态行/contentBottom、不用 ED。同步 lastView 为 dim 视图(text 与 placeholder 拆开存),使 scrollBy/resize
+ * 的 repaint 仍显当前回显 + 光标。真光标归续写位(滚动回看时归内容区底)——不入输入框,假光标已画在行内。
+ */
+export declare function paintRunningInputEcho(text: string, placeholder: string): void;
+/** 重画当前视图(resize / 内部用)。 */
+export declare function repaint(): void;
+/** 进入输入态:画空输入框 + 状态行,光标入输入框。 */
+export declare function enterInputMode(status?: string): void;
+/** 进入运行态:底栏输入行改 dim 占位,光标回续写位。footerH 恒 6(虚拟空+spinner行+上线+输入+下线+model行)。新轮回尾(确保新内容可见)。 */
+export declare function enterRunningMode(status: string, placeholder: string): void;
+export declare function enterAltScreen(): void;
+/** 复原:复位 margins + 显光标 + 退 alt + 还原 raw。幂等。 */
+export declare function exitAltScreen(): void;
+export declare function isActive(): boolean;

package/dist/ui/layout.js

@@ -34,6 +34,8 @@ let runningFrame = -1;
 let userActiveUntil = 0; // 打字活跃截止时刻(Date.now()+PAUSE);0=未活跃
 let flushTimer = null; // 用户停手后 flush 缓冲内容(repaintViewport)
 const USER_ACTIVE_PAUSE_MS = 1500;
+/** Sticky banner 的 ❯ 前缀(同 repl 的 PROMPT;常量统一视觉)。 */
+const BANNER_PROMPT = '❯ ';
 let lastView = null;
 let lastMenuStartRow = 0; // 上次菜单起始屏行(供擦除)
 let lastMenuRows = 0;
@@ -443,6 +445,11 @@ export function contentInsertAfter(after, lines) {
     const delta = content.totalRows() - totalBefore;
     if (delta === 0)
         return;
+    // 流式 md 段活跃期间:插入点在段起点之前 → segmentStartRow 平移,
+    // 否则 contentWriteMd 的续写位算错,展开行被下一个 setLines 砍掉。
+    if (mdActive && after + 1 < segmentStartRow) {
+        segmentStartRow += delta;
+    }
     // 续写位:原写头绝对行 = viewport 起点 + (contentRow-1) [offset=0];偏移后才一致
     if (scrollOffset === 0 && contentRow > after + 1) {
         contentRow = Math.min(contentRow + delta, g.contentBottom);
@@ -469,6 +476,11 @@ export function contentDeleteFrom(startIdx, n) {
     const delta = totalBefore - content.totalRows();
     if (delta === 0)
         return;
+    // 流式 md 段活跃期间:删除区间全部在段起点之前 → segmentStartRow 回退,
+    // 否则 contentWriteMd 的续写位算错,段内容错位。
+    if (mdActive && startIdx + delta <= segmentStartRow) {
+        segmentStartRow = Math.max(1, segmentStartRow - delta);
+    }
     if (scrollOffset === 0 && contentRow > startIdx + 1) {
         contentRow = Math.max(1, contentRow - delta);
     }
@@ -562,6 +574,12 @@ function highlightRange(line, colStart, colEnd) {
  * 重画内容区 viewport:按 scrollOffset 取缓冲尾窗,逐行 cup+clearline+rowtext 映射到屏 1..contentBottom。
  * offset=0 即尾窗(== 实时屏,resize / 回尾时用)。清行含 contentBottom——顺带擦 WT 边距漏影(状态行重复)。
  * 有活跃选区(鼠标拖拽中)时,对选中范围套反白——纯视觉,不影响缓冲内容。
+ *
+ * **滚动回看 sticky banner(输入框上方固定标题的姊妹需求)**:
+ * 仅在 scrollOffset > 0 时,在 viewport 第 1 行顶部叠一行横幅,显示「当前 viewport 顶上
+ * 那条用户消息」的预览。用户上滑翻历史时,横幅内容随滚动到的 user→agent 对应关系变化;
+ * 滑到底(offset===0)自动消失(实时屏可见,无需 banner)。满宽 padding + 底色对比反色
+ * 提示「↑ 这是上方滚走的内容」,不与内容区行内 SGR 冲突。
  */
 export function repaintViewport() {
     if (!active)
@@ -570,11 +588,27 @@ export function repaintViewport() {
     const h = g.contentBottom;
     const slice = content.sliceFromEnd(scrollOffset, h);
     const sel = normalizeSelection();
-    const absStart = sel ? viewportAbsStart() : 0;
+    // viewportAbsStart() 无选区时也用:sticky banner 必须按真实窗口头算,不能降级 0(否则 banner 永不出现)。
+    const absStart = viewportAbsStart();
+    // sticky banner:仅 scrollOffset>0 时显示;offset=0 即实时屏,user 气泡本来就在视口内,无需 banner。
+    const bannerText = scrollOffset > 0
+        ? content.lastUserMessageBefore(absStart)
+        : null;
+    const BANNER_ROW = 1; // 横幅占 viewport 第 1 行(会把原第 1 行内容遮住 —— 1 行换"我在看啥"的可读性,可接受)
     let p = '';
     for (let r = 1; r <= h; r++) {
         let line = slice[r - 1] ?? '';
-        if (sel) {
+        if (bannerText && r === BANNER_ROW) {
+            // banner 行:满宽 userBg + ❯ + 单行截断(多行 ⏎ 折叠)+ userBg 补到底 + 底线分隔短横
+            const cols = g.cols;
+            const oneLine = bannerText.replace(/\s*\n\s*/g, ' ⏎ ');
+            const promptW = displayWidth(BANNER_PROMPT);
+            const avail = Math.max(1, cols - promptW);
+            const truncated = truncateDisplayHead(oneLine, avail);
+            const padCount = Math.max(0, cols - promptW - displayWidth(truncated));
+            line = `${ui.userBg}${BANNER_PROMPT}${truncated}${' '.repeat(padCount)}${ui.reset}`;
+        }
+        else if (sel) {
             const absLine = absStart + r - 1;
             if (absLine >= sel.startLine && absLine <= sel.endLine) {
                 const lineW = ansiDisplayWidth(line);
@@ -1133,28 +1167,50 @@ function composeSpinnerLine(status, cols) {
 function composeModelLine(status, cols) {
     const ctx = status.contextBar; // 已带色
     const ctxW = ansiDisplayWidth(ctx);
-    // 左段:模式标识 + 本轮 token chip。token chip 仅展示总量,用 mid 灰,不抢主色。
+    // 左段:模式标识 + 切换提示(灰)+ 本轮 token chip。token chip 仅展示总量,用 mid 灰,不抢主色。
     const modeTag = status.modeTag ?? '';
     const modeColor = modeTag === 'plan' ? ui.yellow : ui.brightCyan;
     const modePart = modeTag ? `${modeColor}${modeTag}${ui.reset}` : '';
     const modeW = modeTag ? displayWidth(modeTag) : 0;
+    // 切换提示:告诉用户怎么切模式。灰(dim)降优先级,不与 modeTag 抢色;只在有 modeTag 时出现。
+    const HINT = 'Shift+Tab 切换模式';
+    const hintW = modeTag ? displayWidth(HINT) : 0;
+    const hintPart = modeTag ? `${ui.dim}${HINT}${ui.reset}` : '';
     const tokChip = formatTurnTokenChip(status.lastTurnUsage);
     const tokW = displayWidth(stripAnsi(tokChip));
-    // 合并左段:chip 前留 2 空格分隔,无 modeTag 也允许仅显示 chip(兜底边角)。
-    const sep = modePart && tokChip ? '  ' : '';
-    const leftStr = `${modePart}${sep}${tokChip}`;
-    const leftW = modeW + (modePart && tokChip ? sep.length : 0) + tokW;
+    // 合并左段:段间留 2 空格分隔。极窄时 hint 与 chip 都可能藏掉。
+    // 优先级:modeTag(必) > chip(提示累计 token,有信息量)> hint(纯说明性,窄时最先省)。
+    const sepMH = modePart && (hintPart || tokChip) ? '  ' : '';
+    const sepHT = (hintPart && tokChip) ? '  ' : '';
+    const leftStr = `${modePart}${sepMH}${hintPart}${sepHT}${tokChip}`;
+    const leftW = modeW
+        + (modePart && (hintPart || tokChip) ? sepMH.length : 0)
+        + hintW
+        + ((hintPart && tokChip) ? sepHT.length : 0)
+        + tokW;
     // 右段:ctx + sep + cwd,右端对齐。cwd 按预算截断,极窄(<6)隐藏。
-    // 任一 chip 极宽时收紧 cwd(toolbar 列挤压场景),先从 cwd 砍、再隐藏 cwd、再隐藏 token chip。
+    // 任一 chip 极宽时收紧 cwd(toolbar 列挤压场景),先从 cwd 砍、再隐藏 cwd、再按 hint→chip 顺序省。
     const minGap = 2;
     let cwdBudget = cols - leftW - minGap - ctxW - STATUS_SEP_W - 1;
     let cwd = cwdBudget >= 6 ? truncateDisplay(status.cwd, cwdBudget) : '';
     let cwdW = displayWidth(cwd);
     let rightStr = `${ctx}${STATUS_SEP}${ui.dim}${cwd}${ui.reset}`;
     let rightW = ctxW + STATUS_SEP_W + cwdW;
-    // 极窄(<24 列含 ctx):藏 token chip
-    if (modePart && tokChip && rightW + minGap + leftW > cols) {
-        return twoColumn(modePart, modeW, rightStr, rightW, cols);
+    // 极窄:逐步降级——先藏 hint,再藏 token chip,只剩 modeTag 与右段挤。
+    // 这样 80 列宽终端下 hint 和 chip 都能稳住,只 <50 列才退化到只剩 modeTag。
+    if (leftW + minGap + rightW > cols) {
+        // 优先藏 hint(纯说明,信息密度最低):仅留 modePart + sep + tokChip
+        if (modePart && tokChip && hintPart) {
+            const leftStr2 = `${modePart}${sepMH}${tokChip}`;
+            const leftW2 = modeW + sepMH.length + tokW;
+            if (leftW2 + minGap + rightW <= cols) {
+                return twoColumn(leftStr2, leftW2, rightStr, rightW, cols);
+            }
+        }
+        // 再藏 token chip:仅留 modePart
+        if (modePart && tokChip) {
+            return twoColumn(modePart, modeW, rightStr, rightW, cols);
+        }
     }
     return twoColumn(leftStr, leftW, rightStr, rightW, cols);
 }