mocode-ai 0.5.3 → 0.5.5

package/dist/agent/core.js

@@ -5,7 +5,7 @@
 // 与 index.ts 的关系:index.ts 的 runAgent = runAgentCore + TUI hooks 薄封装(行为不变)。
 // spawn.ts 的 spawnAgent = runAgentCore + 静默 hooks(子 agent)。
 import { readFileSync } from 'node:fs';
-import { chat, planChatTools, } from '../llm/index.js';
+import { chat, estimateMessagesTokens, estimateToolSchemaTokens, planChatTools, } from '../llm/index.js';
 import { executeTool, tools } from '../tools/registry.js';
 import { checkPermission } from '../permissions/index.js';
 import { getPlanDisabledTools } from '../tools/constants.js';
@@ -262,6 +262,16 @@ export async function runAgentCore(opts) {
             }
             contextState.lastUsage = result.usage; // 供 /context 与状态行显示实测 token
             addUsage(result.usage); // 本轮累计:onDone 摘要行 + AgentRunResult.usage 透传
+            // 校正系数:API 实测 prompt_tokens / 估算 token。
+            // 每次 chat 响应后刷新,让下次 evaluateBudget 用更接近真实的 actual。
+            // 钳位 [0.5, 2.0]:防单次异常值(极短回复 / 空 history)导致系数跳变。
+            if (result.usage?.promptTokens && result.usage.promptTokens > 100) {
+                const estimated = estimateMessagesTokens(history) + estimateToolSchemaTokens();
+                if (estimated > 100) {
+                    const raw = result.usage.promptTokens / estimated;
+                    contextState.correction = Math.max(0.5, Math.min(2.0, raw));
+                }
+            }
             hooks.onChatDone?.(); // 主 agent:spinner.stop()
             // lastUsage 已更新:触发状态行 context 用量条重算+重画,运行中不再冻结在轮首。
             onContextUpdate?.();
@@ -280,8 +290,9 @@ export async function runAgentCore(opts) {
                         function: { name: tc.name, arguments: tc.arguments },
                     })),
                 });
-                // 工具分组执行(保 tool_calls 原顺序):连续的只读工具(READ_TOOL_NAMES)成组并发——一次性启动全部
-                // executeTool(调用即开始 I/O),再按原顺序逐个 await + 渲染(● 头与 ↳ 结果紧邻,修并行时"全 ● 后全 ↳"分离)。
+                // 工具分组执行(保 tool_calls 原顺序):连续的只读工具(READ_TOOL_NAMES)成组并发——先一次性
+                // 渲染全部 header，让摘要在任何同步工具真正执行前立即可见；随后启动全部 executeTool，
+                // 再按原顺序逐个 await + 回灌结果。
                 // mutation(write_file/edit_file)及 run_command/use_skill 各为单步串行屏障——mutation 串行保
                 // recordMutation 调用序 = 回滚快照序(executeTool 内写前记 before 快照,同文件多次写需按序)。
                 // 渲染与 history 回灌一律按原顺序;并发只影响执行时序,tool_call_id 仍按序配对。
@@ -290,25 +301,28 @@ export async function runAgentCore(opts) {
                 let i = 0;
                 while (i < calls.length) {
                     if (READ_TOOL_NAMES.has(calls[i].name)) {
-                        // 收集连续只读组(≥1),并发执行:先一次性启动所有(executeTool 调用即开始 I/O),
-                        // 再按原顺序逐个 await + 渲染——● 头与 ↳ 结果紧邻、顺序 = tool_calls 序(修"全 ● 后全 ↳"分离 bug)。
+                        // 收集连续只读组(≥1),并发执行:先渲染所有 header，再一次性启动所有
+                        // (executeTool 调用即开始 I/O)，最后按原顺序逐个 await + 回灌。
+                        // 必须先 header 后 execute：todolist/grep 等同步快速工具会在 executeTool 返回 Promise 前
+                        // 已经完成；若先 started.map，用户只能在工具完成后才看到摘要与其前面的换行。
                         // 异步工具(web_fetch 等)并发跑、总耗时 ≈ 最慢一个;同步工具(glob/grep)map 时已顺序跑完,await 即返。
                         let j = i;
                         while (j < calls.length && READ_TOOL_NAMES.has(calls[j].name))
                             j++;
                         const batch = calls.slice(i, j);
+                        for (const tc of batch)
+                            hooks.onToolHeader?.(tc);
+                        hooks.onToolStart?.(batch[0].name);
                         const started = batch.map((tc) => executeTool(tc.name, tc.arguments, signal, { skipRollback, dropContext }));
                         for (let k = 0; k < batch.length; k++) {
                             const tc = batch[k];
-                            hooks.onToolHeader?.(tc);
-                            hooks.onToolStart?.(tc.name);
                             const output = await started[k];
-                            hooks.onToolDone?.();
                             hooks.onToolResult?.(tc, output, null, null, 1); // 只读工具无 diff
                             // Thrashing:history 里附 hint(UI 已用干净 output 渲染,避免屏幕噪声)
                             const hint = recordAndHint(tc.name, tc.arguments);
                             pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler);
                         }
+                        hooks.onToolDone?.();
                         i = j;
                     }
                     else if (calls[i].name === 'task') {

package/dist/agent/index.js

@@ -25,9 +25,14 @@ function firstLineOf(ui) {
  *  重构后改为累积到 BatchRenderer,onToolBatchEnd 时统一打摘要行;
  *  展开/折叠由 BatchRenderer + 鼠标 release 决定,本函数不再直接写屏。 */
 function writeToolHeader(tc) {
+    // 改文件工具是 batch 屏障：先收尾之前的普通工具，确保 mutation 永远独占一批。
+    if (isMutationTool(tc.name))
+        flushToolBatch();
     if (!currentBatchId)
         currentBatchId = batch.beginBatch();
     batch.recordCall(currentBatchId, tc.name, summarizeToolCall(tc.name, tc.arguments));
+    // 第一条工具开始时立即落摘要；后续调用加入同一 batch，并原地刷新计数。
+    batch.showLiveBatch(currentBatchId, layout);
 }
 /** 渲染工具结果:mutation 成功走 diff 块(行号 + 语法高亮,仿 Claude Code);其余走一行 preview。
  *  同 writeToolHeader,改为累积到 BatchRenderer(只缓存字符串,不写屏)。 */
@@ -48,6 +53,21 @@ function writeToolResult(tc, output, parsed, preWriteOld, editStartLine) {
     }
     const preview = diff ? '' : summarizeToolResult(tc.name, output);
     batch.recordResult(currentBatchId, tc.name, preview, diff, output);
+    // mutation 结果（成功 diff 或错误输出）立即可见，并阻止后续普通工具并入这一批。
+    if (isMutationTool(tc.name))
+        flushToolBatch(true);
+}
+/** 将跨 LLM 工具轮次累计的调用写入内容区；正文开始或整个 turn 收尾时才切批。 */
+function flushToolBatch(expandSingleEntry = false) {
+    if (!currentBatchId)
+        return;
+    const id = currentBatchId;
+    currentBatchId = null;
+    batch.endBatch(id, layout);
+    if (expandSingleEntry)
+        batch.expandSingleEntryFully(id, layout);
+    // 摘要本身已有行尾；再补一行，保持工具与后续正文/状态摘要之间的原有间距。
+    layout.contentWrite('\n');
 }
 /**
  * agent 核心循环(主 agent,TUI 渲染版):
@@ -79,19 +99,43 @@ onContextUpdate) {
     // lastChar 镜像:core 跟踪流式末字符决定补换行,但 TUI hooks 需读它决定 layout.contentWrite('\n')。
     // core 的 onTextEnd hook 只在 lastChar !== '\n' 时才调,调后置 '\n';镜像与此同步。
     let lastChar = '';
+    // 正文 -> 工具的边界由 core.onTextEnd 与本层 onToolCall 分两段完成。
+    // markdown 段末已经是完整物理行，因此再写 1 个 \n 就代表 1 条空白行；
+    // 不能按普通字符串的“两个换行才有一个空行”来计算。
+    let textBoundaryNewlines = 0;
+    let hasPendingTextBoundary = false;
     const hooks = {
         onText: (s) => {
-            spinner.stop(); // 任何正文 token 都停 spinner(首 token 停「思考中」;onToolCall 重启后若又来文本则停「生成中」)。未旋转时 stop 为 no-op。
-            layout.contentWriteMd(s); // 正文走 markdown 渲染(代码块高亮 / 标题 / 列表 / 行内 …),见 ui/markdown.ts
+            // 纯空白 chunk 在视觉上不是正文：既不切 batch，也不写入 markdown 缓冲。
+            // 部分兼容后端会在连续工具轮次间流出 " " / "\n"，若据此切批会漏掉首个工具。
+            if (currentBatchId && s.trim().length === 0)
+                return;
+            const followsToolBatch = currentBatchId !== null;
+            // batch 收尾已经统一留了一条空白行。部分后端会把下一段正文以 \n / \n\n
+            // 开头发来；去掉这些“边界换行”，避免与 UI 分隔叠成两条空白行。
+            const visible = followsToolBatch ? s.replace(/^(?:[ \t]*\r?\n)+/, '') : s;
             if (s)
-                lastChar = s[s.length - 1];
+                flushToolBatch();
+            spinner.stop(); // 任何正文 token 都停 spinner(首 token 停「思考中」;onToolCall 重启后若又来文本则停「生成中」)。未旋转时 stop 为 no-op。
+            layout.contentWriteMd(visible); // 正文走 markdown 渲染(代码块高亮 / 标题 / 列表 / 行内 …),见 ui/markdown.ts
+            if (visible) {
+                lastChar = visible[visible.length - 1];
+                if (visible.trim().length > 0) {
+                    hasPendingTextBoundary = true;
+                    textBoundaryNewlines = 0;
+                }
+            }
         },
         onToolCall: (name) => {
             // 文本/思考已流完,模型转而生成 tool_call 参数(可能很长,如 write_file 整篇内容):
             // 补换行(让随后的 ● 行与 diff 不黏在正文末尾)+ 启「生成中」内联 spinner,内容区不再干等。
-            if (lastChar && lastChar !== '\n') {
-                layout.contentWrite('\n');
+            if (hasPendingTextBoundary) {
+                if (textBoundaryNewlines < 1) {
+                    layout.contentWrite('\n');
+                }
                 lastChar = '\n';
+                textBoundaryNewlines = 1;
+                hasPendingTextBoundary = false;
             }
             if (name)
                 spinner.start(`生成 ${name}`);
@@ -102,6 +146,8 @@ onContextUpdate) {
             if (lastChar && lastChar !== '\n') {
                 layout.contentWrite('\n');
                 lastChar = '\n';
+                if (hasPendingTextBoundary)
+                    textBoundaryNewlines = 1;
             }
         },
         onToolHeader: (tc) => writeToolHeader(tc),
@@ -109,27 +155,31 @@ onContextUpdate) {
         onToolDone: () => spinner.stop(),
         onToolResult: (tc, output, parsed, preWriteOld, editStartLine) => writeToolResult(tc, output, parsed, preWriteOld, editStartLine),
         onToolBatchEnd: () => {
-            // 收尾:把累积的 batch 渲染成单行摘要(批内 N 个 tool 调用共用一行,
-            // 鼠标点击该行可展开完整明细——见 ui/batch.ts)。无 batch(模型未调工具)则补空行保持间距。
-            if (currentBatchId) {
-                const id = currentBatchId;
-                currentBatchId = null;
-                batch.endBatch(id, layout);
-            }
-            layout.contentWrite('\n');
+            // 一次工具轮次结束不再切 UI batch；下一轮若仍无正文，继续复用 currentBatchId。
+        },
+        onNoReply: () => {
+            flushToolBatch();
+            layout.contentWrite(`${ui.dim}(无回复)${ui.reset}\n`);
+        },
+        onMaxSteps: () => {
+            flushToolBatch();
+            layout.contentWrite(`  ${ui.yellow}●${ui.reset} ${ui.yellow}达到最大步数(${config.maxSteps}),本轮停止。${ui.reset}\n`);
         },
-        onNoReply: () => layout.contentWrite(`${ui.dim}(无回复)${ui.reset}\n`),
-        onMaxSteps: () => layout.contentWrite(`  ${ui.yellow}●${ui.reset} ${ui.yellow}达到最大步数(${config.maxSteps}),本轮停止。${ui.reset}\n`),
         onAbort: () => {
             spinner.stop();
             if (lastChar && lastChar !== '\n')
                 layout.contentWrite('\n');
+            flushToolBatch();
             layout.contentWrite(`${ui.dim}(已中断)${ui.reset}\n`);
-            currentBatchId = null; // 丢弃未收尾 batch
         },
         onDone: (elapsedMs, usage) => {
+            flushToolBatch();
             const tok = formatTurnTokens(usage);
             layout.contentWrite(`  ${ui.dim}✻ Worked for ${fmtElapsed(elapsedMs)}${tok}${ui.reset}\n`);
+            // 内容区触底时，DECSTBM 增量滚屏可能只推进物理终端，未把 Worked 前已在
+            // buffer 中的空行完整画出来；用户滚动/点击触发 repaint 后才“突然”出现。
+            // 轮次收尾立即按 buffer 原子重画，使未满屏与触底滚屏的布局一致。
+            layout.repaintViewport();
         },
     };
     // 桌宠状态广播:与 TUI hooks 并列注入,互不干扰(petHooks 只调 bridge.sendState,不写屏;

package/dist/context/budget.js

@@ -25,6 +25,7 @@
 // 开关(MOCODE_BUDGET_SCHEDULER):默认 true。false 时 agent/core.ts 走老路径
 //      (直接 maybeCompact),完全跳过本模块,零行为变化。
 import { estimateMessagesTokens, estimateTokens } from '../llm/index.js';
+import { toText } from './utils.js';
 /** 五区分账(占比对齐 CONTEXT_WINDOW)。顺序固定,便于遍历。 */
 export const BUDGET_LAYERS = [
     'system',
@@ -52,19 +53,6 @@ export const HOT_TURN_WINDOW = 4;
  * Cold 区内:age ≥ TOOL_OLD_AGE 的非观察类工具结果可被调度器就地 stub。
  * 默认 2 = 跨过 2 个消费者 push 仍未被消费,等同 lifecycle 的 DEFAULT_AGE_THRESHOLD。 */
 export const TOOL_OLD_AGE = 2;
-/** 把每条 token 拍平成字符串(只估 token,不深解析工具调用)。 */
-function toText(content) {
-    if (content == null)
-        return '';
-    if (typeof content === 'string')
-        return content;
-    try {
-        return JSON.stringify(content);
-    }
-    catch {
-        return String(content);
-    }
-}
 function msgTokens(m) {
     const c = m.content;
     const tcs = m.tool_calls;
@@ -75,14 +63,6 @@ function msgTokens(m) {
     // 与 llm.estimateTokens 同公式(CJK 1/字,ASCII 1/4字);保证调度器评估与系统估算口径一致。
     return 4 + estimateTokens(extra);
 }
-/** 从 history 末尾向前找最后一个 user 消息的索引;无 user 返 -1。 */
-export function lastUserIndex(history) {
-    for (let i = history.length - 1; i >= 1; i--) {
-        if (history[i].role === 'user')
-            return i;
-    }
-    return -1;
-}
 /** 从 idx 处向前数第 N 个 user turn 的边界 index(含该 user 之后的内容)。
  * 用于把 history 切成 Hot 区(tail 一段,endExclusive=history.length)与 Cold 区(0..endExclusive)。
  * 若 N 个 user 不足,Hot 区 = history.length(全保护);Cold 区空,无压缩目标。 */
@@ -98,16 +78,19 @@ export function userTurnBoundary(history, window) {
     return 1; // 没攒够 N 个 user 之前的全归 Cold(history[0] system 不动)
 }
 /** 评估当前 history 的五区预算(纯函数,改不动 history)。
- * 传入 step 是当前所在 step 编号(agent 循环 step 变量),用于日志/调试。 */
-export function evaluateBudget(history, window, step = 0) {
+ * 传入 step 是当前所在 step 编号(agent 循环 step 变量),用于日志/调试。
+ * correction:API 实测 / 估算的校正系数(默认 1);>1 表示粗估偏低,乘以系数后 actual 更接近真实值。 */
+export function evaluateBudget(history, window, step = 0, correction = 1) {
     const layers = {};
     for (const k of BUDGET_LAYERS) {
         const budget = Math.floor(BUDGET_RATIO[k] * window);
         layers[k] = { actual: 0, budget, overBudget: false, overRatio: 0 };
     }
+    // 校正后的 token 数:raw * correction,最小 1(raw > 0 时)。
+    const adj = (raw) => (raw > 0 ? Math.max(1, Math.round(raw * correction)) : 0);
     const sysMsg = history[0];
     if (sysMsg)
-        layers.system.actual = msgTokens(sysMsg);
+        layers.system.actual = adj(msgTokens(sysMsg));
     // Summary 检测:role:'system' 且不是 history[0] 的,视为摘要(compact.ts 摘要插 index 1)。
     // 简单启发:若 history[1]?.role === 'system' 且 content 含「# 会话摘要」特征串,计入 summary。
     // 命中时循环跳过 i=1;不命中时当作普通 message(罕见,落到下方 user/assistant 分支)。
@@ -115,7 +98,7 @@ export function evaluateBudget(history, window, step = 0) {
     if (history.length > 1 && history[1].role === 'system') {
         const c1 = toText(history[1].content);
         if (c1.startsWith('# 会话摘要') || c1.includes('会话摘要')) {
-            layers.summary.actual = msgTokens(history[1]);
+            layers.summary.actual = adj(msgTokens(history[1]));
             summaryHit = true;
         }
     }
@@ -127,7 +110,7 @@ export function evaluateBudget(history, window, step = 0) {
         if (i === 1 && summaryHit)
             continue; // summary 已单独算过
         if (m.role === 'tool') {
-            const t = msgTokens(m);
+            const t = adj(msgTokens(m));
             if (i >= hotStart)
                 layers.toolRecent.actual += t;
             else
@@ -135,7 +118,7 @@ export function evaluateBudget(history, window, step = 0) {
         }
         else if (m.role !== 'system') {
             // user / assistant 全部计入 history(对话轨迹)
-            layers.history.actual += msgTokens(m);
+            layers.history.actual += adj(msgTokens(m));
         }
         // 其它 system(几乎不存在)跳过
     }
@@ -152,7 +135,8 @@ export function evaluateBudget(history, window, step = 0) {
     // 按 overRatio 降序
     triggers.sort((a, b) => layers[b].overRatio - layers[a].overRatio);
     const total = BUDGET_LAYERS.reduce((s, k) => s + (k === 'reserve' ? 0 : layers[k].actual), 0);
-    const totalOver = total >= 0.85 * window;
+    // 安全裕量:用 0.82 而非 0.85,预留 3% 给 correction 波动与新消息增量。
+    const totalOver = total >= 0.82 * window;
     return {
         step,
         total,
@@ -161,19 +145,24 @@ export function evaluateBudget(history, window, step = 0) {
         triggers,
         totalOver,
         hotBoundary: hotStart,
+        correction,
     };
 }
-/** 根据 BudgetReport 生成调度动作(从轻到重,直至总占用回落到 0.85 以下)。
+/** 根据 BudgetReport 生成调度动作(从轻到重,直至总占用回落到阈值以下)。
  * 规则:
  *   - system 超 → warn(不压,配置问题不是内容问题)
  *   - toolOld 超 → 先 L1(中截超大)→ L2(same-path 已有 relevance)→ L3(age stub,新增)
  *   - toolRecent 超 → cap(只降低单条上限,不 stub)
  *   - history 超 或 totalOver → compact_history(调 maybeCompact / compactHistory)
- *   - summary 超 → 不动(摘要本身就压缩产物,删它等于丢历史,只能放任或扩 Recent 预算) */
+ *   - summary 超 → 不动(摘要本身就压缩产物,删它等于丢历史,只能放任或扩 Recent 预算)
+ *
+ * 安全裕量:headroom 按 0.80 * window - total * 1.05 计算(预留 5% 应对 correction 误差
+ * 与新消息增量),避免估算偏差导致被 API 硬截断。 */
 export function scheduleActions(report) {
     const actions = [];
     const { layers, totalOver, total } = report;
-    const headroom = 0.85 * report.window - total;
+    // 收紧:0.80 阈值(原 0.85)+ total * 1.05 放大(估算不确定性缓冲)
+    const headroom = 0.80 * report.window - total * 1.05;
     // system 超 → warn,不是 schedule 目标
     if (layers.system.overBudget) {
         actions.push({
@@ -196,8 +185,8 @@ export function scheduleActions(report) {
     if (layers.toolRecent.overBudget && layers.toolRecent.overRatio > 0.15) {
         actions.push({ kind: 'cap_hot_tools', aggressive: layers.toolRecent.overRatio > 0.5 });
     }
-    // History / total 超 → 摘要(最贵);headroom < -2K 真正触发,让 cold tools 先动
-    if ((layers.history.overBudget || totalOver) && headroom < -2000) {
+    // History / total 超 → 摘要(最贵);headroom < -1500 真正触发(原 -2000,裕量收紧后同步调低),让 cold tools 先动
+    if ((layers.history.overBudget || totalOver) && headroom < -1500) {
         actions.push({ kind: 'compact_history' });
     }
     // 排序(同 kind 已在上面排好):warn → cold L1→L2→L3 → cap_hot → compact_history

package/dist/context/index.js

@@ -10,4 +10,4 @@ export { optimizeToolResult } from './pipeline.js';
 export { classify, knownToolKinds } from './classifier.js';
 export { registerEncoder, registerAll, getEncoder, registeredKinds, } from './registry.js';
 // ── Context Budget Scheduler ───────────────────────────────────────────────
-export { evaluateBudget, scheduleActions, formatReport, quickEstimate, userTurnBoundary, lastUserIndex, BUDGET_LAYERS, BUDGET_RATIO, HOT_TURN_WINDOW, TOOL_OLD_AGE, } from './budget.js';
+export { evaluateBudget, scheduleActions, formatReport, quickEstimate, userTurnBoundary, BUDGET_LAYERS, BUDGET_RATIO, HOT_TURN_WINDOW, TOOL_OLD_AGE, } from './budget.js';

package/dist/context/lifecycle.js

@@ -26,6 +26,7 @@
 //   - mutation 分支额外调 pushMutation 通知(也走 observeMutation 同语义)。
 //
 // 开关:`config.contextLifecycle`(默认 true;MOCODE_LIFECYCLE=false 回退)。
+import { extractPath, lastUserIndex, toText, toolNameOf } from './utils.js';
 /** 观察类工具(永远只到 REFERENCED,不参与自动 STUB)。 */
 const OBSERVER_TOOLS = new Set([
     'grep',
@@ -45,61 +46,6 @@ const STUB_PREFIX_NO_CONSUMER = '⌦[无消费者:观察结果已无引用价值
  *  ≥ 这个值且仍为 LIVE 且非观察类 → 视为 OBSOLETE → STUB。
  *  默认 2:等价于「跨过两个消费者 push 仍无人引用」= 跨过整轮最末尾的工具调用。 */
 const DEFAULT_AGE_THRESHOLD = 2;
-/** 复用 drop.ts 的取 path 思路,但本层要支持更多字段名(read_file/edit_file/write_file 都有 path;
- *  edit_file 还可能有 file_path,但这里只看 path,保持单一)。 */
-function extractPath(argsRaw) {
-    if (!argsRaw)
-        return null;
-    let parsed;
-    try {
-        parsed = JSON.parse(argsRaw);
-    }
-    catch {
-        return null;
-    }
-    if (!parsed || typeof parsed !== 'object')
-        return null;
-    const p = parsed.path;
-    return typeof p === 'string' && p ? p : null;
-}
-/** 从 tool 消息往前找匹配的 assistant.tool_calls 拿 tool 名。找不到返 null(保守跳过)。 */
-function toolNameOf(history, idx) {
-    const tcId = history[idx].tool_call_id;
-    if (!tcId)
-        return null;
-    for (let j = idx - 1; j >= 1; j--) {
-        const m = history[j];
-        if (m.role !== 'assistant')
-            continue;
-        const tcs = m.tool_calls;
-        if (!tcs)
-            continue;
-        const hit = tcs.find((tc) => tc?.id === tcId);
-        if (hit)
-            return hit.function?.name ?? null;
-    }
-    return null;
-}
-/** 找最后一个 user 消息索引;无 user 返 -1。 */
-function lastUserIndex(history) {
-    for (let i = history.length - 1; i >= 1; i--) {
-        if (history[i].role === 'user')
-            return i;
-    }
-    return -1;
-}
-function toText(content) {
-    if (content == null)
-        return '';
-    if (typeof content === 'string')
-        return content;
-    try {
-        return JSON.stringify(content);
-    }
-    catch {
-        return String(content);
-    }
-}
 /** 从 tool 结果的 content 中提取「生产者命中过的 path 列表」。
  *  - read_file:没有 path 列表(本身就是单 path 消费者,无需再追生产者)。
  *  - grep:content 是 `file:line: ...` 行,提取每行的 file 段(只保留绝对路径形态或与 pattern 匹配的)。

package/dist/context/relevance.js

@@ -22,71 +22,10 @@
 //   - TUI 渲染(hooks.onToolResult)用原始 output,与本层解耦——屏上看全量,LLM 看裁剪后版。
 //
 // 零行为变化兜底:开关 `config.contextRelprune` 关闭时,pipeline 路径完全不调本模块。
+import { extractPath, lastUserIndex, toText, toolNameOf } from './utils.js';
 /** stub 标记前缀(供幂等判定)。drop_context 用的是「⌦[已剔除:与当前任务无关]」,
  *  本层用「⌦[已过时:同 path 已有新 read / 已被 mutation 覆写]」,区分两类剔除来源。 */
 const STUB_PREFIX = '⌦[已过时:同 path 已有新 read / 已被 mutation 覆写]';
-/** 解析工具 arguments(只关心 path);非法返 null。 */
-function extractPath(argsRaw) {
-    if (!argsRaw)
-        return null;
-    let parsed;
-    try {
-        parsed = JSON.parse(argsRaw);
-    }
-    catch {
-        return null;
-    }
-    if (!parsed || typeof parsed !== 'object')
-        return null;
-    const p = parsed.path;
-    if (typeof p !== 'string' || !p)
-        return null;
-    return p;
-}
-/** 从 history 末尾向前找最后一个 user 消息的索引;无 user 返 -1。
- *  复用 drop.ts 的思路:user 及其之后的 tool 结果视为当前轮保护区。
- *  在本层里,read_file tool 消息若落在 user 之后,本轮还在用,不能 stub。
- *  注:history[0] 是 system,user 不会落在 0;若 user 就在末尾(即 0 user 之后),
- *  protectedFrom=0 时整段历史都不可 stub(实际不会发生:pushToolResult 必在 user 之后)。 */
-function lastUserIndex(history) {
-    for (let i = history.length - 1; i >= 1; i--) {
-        if (history[i].role === 'user')
-            return i;
-    }
-    return -1;
-}
-/** 取 tool 消息对应的工具名(从紧邻的前导 assistant.tool_calls 按 tool_call_id 配对找)。
- *  返回 null 表示找不到(孤儿 tool,极少见),本层保守不动。 */
-function toolNameOf(history, idx) {
-    const tcId = history[idx].tool_call_id;
-    if (!tcId)
-        return null;
-    for (let j = idx - 1; j >= 1; j--) {
-        const m = history[j];
-        if (m.role !== 'assistant')
-            continue;
-        const tcs = m.tool_calls;
-        if (!tcs)
-            continue;
-        const hit = tcs.find((tc) => tc?.id === tcId);
-        if (hit)
-            return hit.function?.name ?? null;
-    }
-    return null;
-}
-/** 把 content 拍平成字符串(对齐 drop.ts)。 */
-function toText(content) {
-    if (content == null)
-        return '';
-    if (typeof content === 'string')
-        return content;
-    try {
-        return JSON.stringify(content);
-    }
-    catch {
-        return String(content);
-    }
-}
 /**
  * 维护「path → 该 path 所有 read_file tool 消息的 history index」映射。
  *  - observePush:把刚 push 的 read_file tool 消息登记,并把同 path 的"更早" read 全部 stub。

package/dist/context/utils.js

@@ -0,0 +1,68 @@
+// 跨上下文模块共享的小工具函数。
+//
+// 目的:消除 `relevance.ts` / `lifecycle.ts` / `budget.ts` / `compact.ts` / `session/drop.ts`
+//      之间的 copy-paste。这些函数逻辑完全一致,统一维护于此,避免行为漂移。
+//
+// 不变量:
+//  - 永不抛错(对齐「调度器永不抛错」契约)。
+//  - 仅依赖 `ChatMessage` 的最小形状,不反向 import agent / session / tools。
+/** 把消息 content 拍平成字符串(OpenAI 可能 string / null / 多模态数组)。
+ *  用于估算 token、内容匹配、stub 拼接等场景。 */
+export function toText(content) {
+    if (content == null)
+        return '';
+    if (typeof content === 'string')
+        return content;
+    try {
+        return JSON.stringify(content);
+    }
+    catch {
+        return String(content);
+    }
+}
+/** 从 history 末尾向前找最后一个 user 消息的索引;无 user 返 -1。
+ *  用于划定「当前轮保护区」——该 user 及其之后的消息(agent 本轮还在用)不动。
+ *  注:history[0] 是 system,故下界为 1。 */
+export function lastUserIndex(history) {
+    for (let i = history.length - 1; i >= 1; i--) {
+        if (history[i].role === 'user')
+            return i;
+    }
+    return -1;
+}
+/** 取 tool 消息对应的工具名(从紧邻的前导 assistant.tool_calls 按 tool_call_id 配对找)。
+ *  返回 null 表示找不到(孤儿 tool 消息,极少见),调用方保守跳过。 */
+export function toolNameOf(history, idx) {
+    const tcId = history[idx].tool_call_id;
+    if (!tcId)
+        return null;
+    for (let j = idx - 1; j >= 1; j--) {
+        const m = history[j];
+        if (m.role !== 'assistant')
+            continue;
+        const tcs = m.tool_calls;
+        if (!tcs)
+            continue;
+        const hit = tcs.find((tc) => tc?.id === tcId);
+        if (hit)
+            return hit.function?.name ?? null;
+    }
+    return null;
+}
+/** 解析工具 arguments JSON,只取 `path` 字段;非法 / 无 path 返 null。
+ *  用于 read_file / edit_file / write_file 等以 path 为关键字的工具,供跨消息关联使用。 */
+export function extractPath(argsRaw) {
+    if (!argsRaw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(argsRaw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const p = parsed.path;
+    return typeof p === 'string' && p ? p : null;
+}

package/dist/repl/index.js

@@ -455,14 +455,15 @@ function textOf(c) {
  * 回放默认全折叠;用户可鼠标点击摘要行展开(由 BatchRenderer 接管,见 ui/batch.ts)。
  */
 export function renderHistory(history) {
-    const idToName = new Map();
-    // 当前累积的 batch(assistant.tool_calls + 后续 tool 消息);一旦遇到非 tool 消息即收尾出摘要
-    let pendingBatch = [];
+    const idToEntry = new Map();
+    // 普通工具可跨 assistant 步聚合；mutation 各自占一个 group，并切断前后普通工具。
+    let pendingBatches = [];
+    let normalBatch = null;
     const flushBatch = () => {
-        if (pendingBatch.length === 0)
-            return;
-        batch.writeSummaryOnly(pendingBatch, layout);
-        pendingBatch = [];
+        for (const entries of pendingBatches)
+            batch.writeSummaryOnly(entries, layout);
+        pendingBatches = [];
+        normalBatch = null;
     };
     for (let idx = 0; idx < history.length; idx++) {
         const m = history[idx];
@@ -505,14 +506,25 @@ export function renderHistory(history) {
                 for (const tc of tcs) {
                     const name = tc?.function?.name ?? '';
                     const args = tc?.function?.arguments ?? '';
-                    if (tc?.id && name)
-                        idToName.set(tc.id, name);
-                    pendingBatch.push({
+                    const entry = {
                         name,
                         callSummary: summarizeToolCall(name, args),
                         resultSummary: '',
                         diffBlock: null,
-                    });
+                    };
+                    if (batch.isMutationToolName(name)) {
+                        normalBatch = null;
+                        pendingBatches.push([entry]);
+                    }
+                    else {
+                        if (!normalBatch) {
+                            normalBatch = [];
+                            pendingBatches.push(normalBatch);
+                        }
+                        normalBatch.push(entry);
+                    }
+                    if (tc?.id)
+                        idToEntry.set(tc.id, entry);
                 }
                 continue; // 跳过后续 tool 消息处理循环(由下一分支填 result)
             }
@@ -522,18 +534,10 @@ export function renderHistory(history) {
         }
         if (m.role === 'tool') {
             const id = m.tool_call_id ?? '';
-            const name = idToName.get(id) ?? '';
+            const target = idToEntry.get(id);
+            const name = target?.name ?? '';
             const output = textOf(m.content);
             const preview = summarizeToolResult(name, output);
-            // 匹配 pendingBatch 中尚未填 result 的同名 entry;同名前缀 tool 较罕见(并行工具同 id 不同名)
-            let target;
-            for (let i = pendingBatch.length - 1; i >= 0; i--) {
-                const e = pendingBatch[i];
-                if (e.name === name && !e.resultSummary) {
-                    target = e;
-                    break;
-                }
-            }
             if (target) {
                 target.resultSummary = preview;
                 target.fullOutput = output;
@@ -853,6 +857,7 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
         if (!loadSnapshots(loaded.id))
             rebuildFromHistory(history);
         contextState.lastUsage = undefined;
+        contextState.correction = 1;
         lastTurnUsage = undefined; // 续接:旧会话的 token 累计已无意义,清空等下轮覆写
         layout.clearContent();
         renderHistory(history);
@@ -985,6 +990,7 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             currentSessionId = undefined; // 下轮起新会话文件
             turnCount = 0; // 反思 cadence 重新计数
             contextState.lastUsage = undefined;
+            contextState.correction = 1;
             lastTurnUsage = undefined; // 清空旧轮的 token 累计
             pendingAttachments = []; // 一并清空待发图片
             layout.clearContent();

package/dist/rollback/index.js

@@ -2,24 +2,12 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from
 import path from 'node:path';
 import { config } from '../config/index.js';
 import { truncateDisplay } from '../ui/render.js';
+import { toText } from '../context/utils.js';
 let turnIdCounter = 0;
 let currentTurnId = 0;
 let turns = [];
 let snapshots = [];
 const MUTATION_TOOLS = new Set(['write_file', 'edit_file']);
-/** 把任意 content 拍平成字符串(OpenAI 可能是 string / 多模态数组)。 */
-function toText(content) {
-    if (content == null)
-        return '';
-    if (typeof content === 'string')
-        return content;
-    try {
-        return JSON.stringify(content);
-    }
-    catch {
-        return String(content);
-    }
-}
 /** 规整成 cwd 相对路径(快照存相对,跨 /resume 同项目可识别;resolve 已归一 ./ 和 ..)。 */
 function toRel(p) {
     try {

package/dist/session/compact.js

@@ -5,10 +5,14 @@ import { ui } from '../ui/theme.js';
 import { Spinner } from '../ui/spinner.js';
 import * as layout from '../ui/layout.js';
 import { pruneAfterCompaction } from '../rollback/index.js';
+import { toText } from '../context/utils.js';
 /** 跨模块共享的上下文状态:agent 写 lastUsage,compact 写 lastEstimate,repl 的 /context 读。
- *  scheduler.ts 写最近一次调度日志(可选,repl 可读不到时 no-op)。 */
+ *  scheduler.ts 写最近一次调度日志(可选,repl 可读不到时 no-op)。
+ *  correction:API 实测 token / 估算 token 的校正系数(1.0 = 无偏差;>1 = 低估;<1 = 高估)。
+ *  由 agent/core.ts 在每次 chat 响应后更新;compact/repl 在 usage 失效时同步重置。 */
 export const contextState = {
     lastEstimate: 0,
+    correction: 1,
 };
 /** 中截:text 太长时保 head + 标记 + tail,总长 ≤ max。 */
 export function truncateMid(text, max) {
@@ -97,19 +101,7 @@ export function capToolResultForHistory(name, output) {
         return output;
     return truncateMid(output, MAX_HISTORY_RESULT);
 }
-// ── 内部:消息内容拍平 / group 划分 ──────────────────────────────────────
-function toText(content) {
-    if (content == null)
-        return '';
-    if (typeof content === 'string')
-        return content;
-    try {
-        return JSON.stringify(content);
-    }
-    catch {
-        return String(content);
-    }
-}
+// ── 内部:group 划分(toText 已移至 context/utils.ts 统一维护) ────────────
 /**
  * 把多模态 content 拍平成纯文本(供摘要 transcript 用):text parts 拼接;image_url parts
  * 替换为 `[图片已剥离: <mime>]` stub,避免 base64 进摘要 prompt(LLM 看到也无意义,反而撑爆 token)。
@@ -323,6 +315,7 @@ export async function compactHistory(history, opts) {
             const estimateAfter = estimateMessagesTokens(history) + schemaTokens;
             contextState.lastEstimate = estimateAfter;
             contextState.lastUsage = undefined;
+            contextState.correction = 1;
             layout.contentWrite(`  ${ui.bold}${ui.accent}●${ui.reset} ${ui.accent}强制压缩(focus on early history)${ui.reset}  ${ui.dim}${estimateBefore} → ${estimateAfter} tokens${ui.reset}\n`);
             return {
                 compacted: true,
@@ -409,6 +402,7 @@ export async function compactHistory(history, opts) {
         const estimateAfter = estimateMessagesTokens(history) + schemaTokens;
         contextState.lastEstimate = estimateAfter;
         contextState.lastUsage = undefined; // 压缩后旧 usage 失效,/context 改用估算
+        contextState.correction = 1;
         layout.contentWrite(`  ${ui.bold}${ui.accent}●${ui.reset} ${ui.accent}压缩上下文${ui.reset}  ${ui.dim}${estimateBefore} → ${estimateAfter} tokens${ui.reset}\n`);
         // 抖动保护:压缩后仍超阈 → 提示 /clear,不死循环
         if (estimateAfter >= opts.threshold * opts.window) {
@@ -426,6 +420,7 @@ export async function compactHistory(history, opts) {
     const estimateAfter = estimateMessagesTokens(history) + schemaTokens;
     contextState.lastEstimate = estimateAfter;
     contextState.lastUsage = undefined; // 结构虽未变,但 token 数已变,旧 usage 失效
+    contextState.correction = 1;
     if (microcompactDone) {
         layout.contentWrite(`  ${ui.bold}${ui.accent}●${ui.reset} ${ui.accent}微压缩旧工具结果${ui.reset}  ${ui.dim}${estimateBefore} → ${estimateAfter} tokens${ui.reset}\n`);
         return {

package/dist/session/drop.js

@@ -11,49 +11,7 @@
 //  - 原地修改 history(同 compact:length=0;push 重建,repl 持有同一引用)。
 //  - 永不抛错(对齐「调度器永不抛错」契约);无匹配 / 无可剔除 → 返 dropped=0。
 import { messageTokens, estimateTokens, } from '../llm/index.js';
-/** 把消息 content 拍平成字符串(OpenAI 可能 string / null / 多模态数组)。 */
-function toText(content) {
-    if (content == null)
-        return '';
-    if (typeof content === 'string')
-        return content;
-    try {
-        return JSON.stringify(content);
-    }
-    catch {
-        return String(content);
-    }
-}
-/**
- * 从 history 末尾向前找最后一个 user 消息的索引;无 user 返 -1。
- * 用于划定"当前轮保护区"——该 user 及其之后的消息一律不剔除。
- */
-function lastUserIndex(history) {
-    for (let i = history.length - 1; i >= 1; i--) {
-        if (history[i].role === 'user')
-            return i;
-    }
-    return -1;
-}
-/** 取 tool 消息对应的工具名(从紧邻的前导 assistant.tool_calls 按 tool_call_id 配对找)。 */
-function toolNameOf(history, idx) {
-    const tcId = history[idx].tool_call_id;
-    if (!tcId)
-        return null;
-    for (let j = idx - 1; j >= 1; j--) {
-        const m = history[j];
-        if (m.role !== 'assistant')
-            continue;
-        const tcs = m
-            .tool_calls;
-        if (!tcs)
-            continue;
-        const hit = tcs.find((tc) => tc?.id === tcId);
-        if (hit)
-            return hit.function?.name ?? null;
-    }
-    return null;
-}
+import { lastUserIndex, toText, toolNameOf } from '../context/utils.js';
 /**
  * 剔除历史里命中的旧 tool 结果(原地修改 history)。
  *

package/dist/session/scheduler.js

@@ -45,7 +45,7 @@ export function createBudgetScheduler() {
             // 占位:push-time 三闸(cap / pruner / lifecycle)已自动跑;此接缝供将来演进。
         },
         async runStep(history, step) {
-            const report = evaluateBudget(history, config.contextWindowTokens, step);
+            const report = evaluateBudget(history, config.contextWindowTokens, step, contextState.correction);
             const actions = scheduleActions(report);
             let compactHistoryCalled = false;
             for (const a of actions) {
@@ -104,7 +104,7 @@ export async function manualCompact(history, focus, opts) {
         }));
         return {
             step: -1,
-            report: evaluateBudget(history, config.contextWindowTokens, -1),
+            report: evaluateBudget(history, config.contextWindowTokens, -1, contextState.correction),
             actions: [{ kind: 'compact_history', focus }],
             compactHistoryCalled: true,
             ts: Date.now(),
@@ -118,7 +118,7 @@ export async function manualCompact(history, focus, opts) {
             },
         };
     }
-    const report = evaluateBudget(history, config.contextWindowTokens, -1);
+    const report = evaluateBudget(history, config.contextWindowTokens, -1, contextState.correction);
     let actions = scheduleActions(report);
     // 用户显式说「要压」:即使 report 不含 history 触发,仍追加 compact_history
     const hasCompact = actions.some(a => a.kind === 'compact_history');

package/dist/ui/batch.js

@@ -17,27 +17,26 @@ const batches = new Map();
  *  buffer 行数变化时本表可能漂移——但只在 insertAfter/deleteFrom 后由本模块同步更新,
  *  并保持 buffer 当前状态对应。 */
 const absLineToBatchId = new Map();
-/** 已展开的 batch id;默认空(全折叠);layout.mouse release 点击摘要行时切。
- *  含 mutation 的 batch 不在此 set——它们走 forceExpanded 永远展开,与 toggle 隔离。 */
+/** 第一层展开后，工具概要行的绝对索引 → 对应 entry。 */
+const absLineToEntry = new Map();
+/** 已展开第一层工具列表的 batch id。 */
 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);
-}
 /** 展开时完整输出的最大行数;超出截断,避免巨型输出撑爆 viewport。 */
 const MAX_EXPAND_LINES = 200;
+export function isMutationToolName(name) {
+    return name === 'write_file' || name === 'edit_file';
+}
 /** 通知 buffer 整体清空(clearContent / exitAltScreen / 新一轮 turn)——本模块状态同步归零。 */
 export function reset() {
     batches.clear();
     absLineToBatchId.clear();
+    absLineToEntry.clear();
     expandedBatches.clear();
 }
 /** 新建一个 batch(在 agent 拿到第一条 onToolHeader 时调)。返回 id。 */
 export function beginBatch() {
     const id = `b${++_idCounter}`;
-    batches.set(id, { id, summaryAbsIdx: -1, entries: [], forceExpanded: false });
+    batches.set(id, { id, summaryAbsIdx: -1, entries: [], expandedEntries: new Set() });
     return id;
 }
 /** 记一条工具调用(在 onToolHeader 时调,与 setEntryResult 配对;entries 顺序 = agent 调用顺序)。 */
@@ -78,7 +77,9 @@ function buildSummaryLine(entries) {
     }
     if (entries.length === 1) {
         const e = entries[0];
-        return `  ${ui.bold}${ui.accent}●${ui.reset} ${ui.accent}${e.name}${ui.reset}  ${ui.dim}${e.callSummary}${ui.reset}`;
+        // 实时摘要必须稳定保持单行；完整参数放在第一层工具概要中，避免长 JSON 自动折行后
+        // 原地刷新只能覆盖最后一条物理行、残留旧摘要前半段。
+        return `  ${ui.bold}${ui.accent}●${ui.reset} ${ui.dim}Ran 1 tool · ${e.name} 1${ui.reset}`;
     }
     // N>1:同类合并 "read_file 3, glob 1, grep 1"
     const counts = new Map();
@@ -93,56 +94,53 @@ function buildSummaryLine(entries) {
 /** 把 batch 的详情行展开成自洽行数组(供 layout.contentInsertAfter 走 mid-buffer 插入)。
  *  每行末尾必须以 \x1B[0m 收尾(SGR 自洽模型),行内允许含 SGR(行末 reset 不影响行内样式),
  *  但**绝不**带 \n——rows[] 是行数组,不是流输出。 */
-function buildExpandedLines(entries, indent = '    ') {
+function buildEntryDetailLines(e, indent = '      ') {
     const lines = [];
-    for (const e of entries) {
-        lines.push(`${indent}${ui.bold}${ui.accent}●${ui.reset} ${ui.accent}${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');
-            }
+    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.fullOutput) {
-            // 完整工具输出(纯文本):按行展开,每行缩进 + dim 样式;长输出截断到 MAX_EXPAND_LINES 行
-            const rawLines = e.fullOutput.split('\n');
-            const truncated = rawLines.length > MAX_EXPAND_LINES;
-            const displayLines = truncated ? rawLines.slice(0, MAX_EXPAND_LINES) : rawLines;
-            for (const line of displayLines) {
-                lines.push(`${indent}${ui.gray}${line}${ui.reset}\x1B[0m`);
-            }
-            if (truncated) {
-                lines.push(`${indent}${ui.dim}… (${rawLines.length - MAX_EXPAND_LINES} more lines)${ui.reset}\x1B[0m`);
-            }
+    }
+    else if (e.fullOutput) {
+        // 完整工具输出(纯文本):按行展开,每行缩进 + dim 样式;长输出截断到 MAX_EXPAND_LINES 行
+        const rawLines = e.fullOutput.split('\n');
+        const truncated = rawLines.length > MAX_EXPAND_LINES;
+        const displayLines = truncated ? rawLines.slice(0, MAX_EXPAND_LINES) : rawLines;
+        for (const line of displayLines) {
+            lines.push(`${indent}${ui.gray}${line}${ui.reset}\x1B[0m`);
         }
-        else if (e.resultSummary) {
-            lines.push(`${indent}${ui.gray}↳ ${e.resultSummary}${ui.reset}\x1B[0m`);
+        if (truncated) {
+            lines.push(`${indent}${ui.dim}… (${rawLines.length - MAX_EXPAND_LINES} more lines)${ui.reset}\x1B[0m`);
         }
     }
+    else if (e.resultSummary) {
+        lines.push(`${indent}${ui.gray}↳ ${e.resultSummary}${ui.reset}\x1B[0m`);
+    }
     return lines;
 }
+/** 第一层只展示有哪些调用及其简短结果，不展开完整输出。 */
+function buildExpandedLines(entries, indent = '    ') {
+    return entries.map((e) => {
+        const result = e.resultSummary ? `  ${ui.gray}↳ ${e.resultSummary}${ui.reset}` : '';
+        return `${indent}${ui.bold}${ui.accent}●${ui.reset} ${ui.accent}${e.name}${ui.reset}  ${ui.dim}${e.callSummary}${ui.reset}${result}\x1B[0m`;
+    });
+}
 /** 在 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);
+    if (!b)
+        return;
+    if (b.summaryAbsIdx >= 0) {
+        layout.contentReplaceLine?.(b.summaryAbsIdx, buildSummaryLine(b.entries));
+        // 执行阶段只展示实时摘要；到 endBatch 才开放点击，避免未完成 batch 的第一层列表失步。
         absLineToBatchId.set(b.summaryAbsIdx, b.id);
-        expandedBatches.add(b.id); // 已展开;防止 toggleBatch 再次 expand() 造成重复插入
         return;
     }
     const summary = buildSummaryLine(b.entries);
@@ -151,9 +149,25 @@ export function endBatch(id, layout) {
     // 摘要行绝对索引 = 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);
+}
+/**
+ * 工具执行中立即显示/刷新摘要，但暂不登记点击命中；endBatch 收尾后才开放两层展开。
+ */
+export function showLiveBatch(id, layout) {
+    const b = batches.get(id);
+    if (!b)
+        return;
+    const summary = buildSummaryLine(b.entries);
+    if (b.summaryAbsIdx < 0) {
+        layout.contentWrite(summary + '\n');
+        b.summaryAbsIdx = Math.max(0, layout.totalRows() - 2);
+        // 首条摘要通过增量 contentWrite 落屏时，markdown→普通内容的边界可能只更新了
+        // buffer/续写位；直到第二个 header 的 contentReplaceLine 或后续正文重绘才完全可见。
+        // 立即按 buffer 原子重画，确保慢工具执行期间摘要前的空行已经显示。
+        layout.repaintViewport?.();
+    }
+    else {
+        layout.contentReplaceLine(b.summaryAbsIdx, summary);
     }
 }
 /** 绝对行索引 → 命中 batch id(用于鼠标 release 反查);非摘要行返 null。 */
@@ -170,18 +184,11 @@ export function isExpanded(id) {
  * 展开:把详情行插入摘要行下方(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);
     }
@@ -193,11 +200,63 @@ function expand(b, layout) {
     const lines = buildExpandedLines(b.entries);
     layout.contentInsertAfter(b.summaryAbsIdx, lines);
     expandedBatches.add(b.id);
+    for (let i = 0; i < b.entries.length; i++) {
+        absLineToEntry.set(b.summaryAbsIdx + 1 + i, { batchId: b.id, entryIndex: i });
+    }
+}
+/** mutation 独占 batch 收尾后立即展示其调用概要和 diff。 */
+export function expandSingleEntryFully(id, layout) {
+    const b = batches.get(id);
+    if (!b || b.entries.length !== 1 || expandedBatches.has(id))
+        return;
+    const lines = [
+        ...buildExpandedLines(b.entries),
+        ...buildEntryDetailLines(b.entries[0]),
+    ];
+    layout.contentInsertAfter(b.summaryAbsIdx, lines);
+    expandedBatches.add(id);
+    b.expandedEntries.add(0);
+    absLineToEntry.set(b.summaryAbsIdx + 1, { batchId: id, entryIndex: 0 });
 }
 function collapse(b, layout) {
-    const lines = buildExpandedLines(b.entries);
-    layout.contentDeleteFrom(b.summaryAbsIdx + 1, lines.length);
+    let lineCount = b.entries.length;
+    for (const i of b.expandedEntries)
+        lineCount += buildEntryDetailLines(b.entries[i]).length;
+    layout.contentDeleteFrom(b.summaryAbsIdx + 1, lineCount);
     expandedBatches.delete(b.id);
+    b.expandedEntries.clear();
+    for (const [idx, target] of absLineToEntry) {
+        if (target.batchId === b.id)
+            absLineToEntry.delete(idx);
+    }
+}
+/** 绝对行索引 → 第一层中的具体工具调用。 */
+export function findEntryByAbsLine(absLine) {
+    return absLineToEntry.get(absLine) ?? null;
+}
+/** 第二层：只展开/折叠某一个工具的完整输出。 */
+export function toggleEntry(batchId, entryIndex, layout) {
+    const b = batches.get(batchId);
+    if (!b || !expandedBatches.has(batchId))
+        return;
+    let headerIdx = -1;
+    for (const [idx, target] of absLineToEntry) {
+        if (target.batchId === batchId && target.entryIndex === entryIndex)
+            headerIdx = idx;
+    }
+    if (headerIdx < 0)
+        return;
+    const details = buildEntryDetailLines(b.entries[entryIndex]);
+    if (details.length === 0)
+        return;
+    if (b.expandedEntries.has(entryIndex)) {
+        layout.contentDeleteFrom(headerIdx + 1, details.length);
+        b.expandedEntries.delete(entryIndex);
+    }
+    else {
+        layout.contentInsertAfter(headerIdx, details);
+        b.expandedEntries.add(entryIndex);
+    }
 }
 /**
  * 当 buffer 中段插/删 N 行后,所有受影响 batch 的 summaryAbsIdx 需平移。
@@ -222,6 +281,21 @@ export function shiftBatchesAfter(absIdx, delta) {
     absLineToBatchId.clear();
     for (const [k, v] of next)
         absLineToBatchId.set(k, v);
+    const nextEntries = new Map();
+    // expand() 先插入整组概要行、再登记其命中位置；layout 随后的异步 shift 通知不应把
+    // 这批“刚插入”的概要行再次平移。插入单个工具详情时 absIdx 不是 summary，仍正常平移。
+    const insertedOverviewBatch = delta > 0
+        ? [...batches.values()].find((b) => b.summaryAbsIdx === absIdx && expandedBatches.has(b.id))?.id
+        : undefined;
+    for (const [idx, target] of absLineToEntry) {
+        const isNewOverviewLine = target.batchId === insertedOverviewBatch;
+        const newIdx = idx > absIdx && !isNewOverviewLine ? idx + delta : idx;
+        if (newIdx >= 0)
+            nextEntries.set(newIdx, target);
+    }
+    absLineToEntry.clear();
+    for (const [k, v] of nextEntries)
+        absLineToEntry.set(k, v);
     // 同步每个 batch 的 summaryAbsIdx
     for (const b of batches.values()) {
         if (b.summaryAbsIdx > absIdx)
@@ -232,21 +306,14 @@ export function shiftBatchesAfter(absIdx, delta) {
 /** 把已构造好的 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');
+    const id = beginBatch();
+    const b = batches.get(id);
+    if (!b)
         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 启动时建一张临时映射)
+    b.entries = entries;
+    endBatch(id, layout);
+    if (entries.length === 1 && isMutationToolName(entries[0].name)) {
+        expandSingleEntryFully(id, layout);
     }
 }
 let _idCounter = 0;

package/dist/ui/content.js

@@ -141,6 +141,12 @@ export function lineAt(abs) {
     const all = snapshot();
     return abs >= 0 && abs < all.length ? all[abs] : null;
 }
+/** 等长替换一条已提交物理行，供运行中的工具 batch 原地刷新摘要。 */
+export function replaceLine(abs, line) {
+    if (abs < 0 || abs >= rows.length)
+        return;
+    rows[abs] = line.endsWith('\x1B[0m') ? line : line + '\x1B[0m';
+}
 /**
  * 找「绝对行索引 < absStart 的最近一条用户消息」的文本(用于滚动回看时的「我刚发的
  * 请求」sticky banner)。算法:从 absStart - 1 往上扫,识别「用户气泡行」(由 repl

package/dist/ui/layout.js

@@ -1,5 +1,5 @@
 import { stdin, stdout } from 'node:process';
-import { charWidth, displayWidth, truncateDisplay, truncateDisplayHead, ansiDisplayWidth, wrapByDisplayWidth, fmtElapsed, stripAnsi, sliceByDisplayCol, } from './render.js';
+import { charWidth, displayWidth, truncateDisplay, truncateDisplayHead, truncateAnsi, ansiDisplayWidth, wrapByDisplayWidth, fmtElapsed, stripAnsi, sliceByDisplayCol, } from './render.js';
 import { ui } from './theme.js';
 import * as content from './content.js';
 import * as mouse from './mouse.js';
@@ -578,6 +578,16 @@ export function contentDeleteFrom(startIdx, n) {
 export function totalRows() {
     return content.totalRows();
 }
+/** 原地刷新一条内容行（行数不变），用于运行中的工具 batch 更新计数。 */
+export function contentReplaceLine(absIdx, line) {
+    if (!active)
+        return;
+    // 原地更新的 batch 摘要可能随追加工具而变长。缓冲区仍把它当作一行，但若直接
+    // 交给终端超过 cols，终端会自动折行，造成视觉上多出空行且续写位与缓冲失步。
+    // 在写回缓冲前按 ANSI 可见宽度截断，确保“一条逻辑行 = 一条物理行”。
+    content.replaceLine(absIdx, truncateAnsi(line, getGeo().cols));
+    repaintViewport();
+}
 /** 清空内容区时通知 batch 渲染器重置(摘要行映射与展开态)。 */
 export function notifyContentReset() {
     // 动态 import 避免循环;模块级 reset() 只清映射,不动 batch 内部数据(id 与 entries 仍可重用)
@@ -1135,14 +1145,25 @@ function handleMouseEvent(e) {
         void (async () => {
             try {
                 const m = await import('./batch.js');
+                const entry = m.findEntryByAbsLine(absClick);
+                if (entry) {
+                    // 先清选区再改 buffer：contentInsert/Delete 内会立即 repaintViewport；若此时仍保留
+                    // 旧绝对行选区，会短暂画出一帧错位高亮，随后二次重画，视觉上就是抖动。
+                    selection = null;
+                    m.toggleEntry(entry.batchId, entry.entryIndex, {
+                        contentInsertAfter: (after, lines) => contentInsertAfter(after, lines),
+                        contentDeleteFrom: (start, n) => contentDeleteFrom(start, n),
+                    });
+                    repaint();
+                    return;
+                }
                 const id = m.findBatchByAbsLine(absClick);
                 if (id) {
+                    selection = null;
                     m.toggleBatch(id, {
                         contentInsertAfter: (after, lines) => contentInsertAfter(after, lines),
                         contentDeleteFrom: (start, n) => contentDeleteFrom(start, n),
                     });
-                    selection = null;
-                    repaintViewport();
                     repaint();
                     return;
                 }

package/dist/ui/markdown.js

@@ -574,6 +574,11 @@ function renderMarkdownImpl(text, cols) {
     flushPara();
     if (inFence)
         flushCode(); // EOF 仍 inFence:流式中未闭合 fence → 照常 emit 进行中代码块
+    // 独立 markdown 段的外部间距由 agent/batch 边界统一管理。流式后端可能把
+    // "\n\n" 与首段正文拆成不同 chunk；仅清洗首个正文 chunk 不够，因为 mdBuf
+    // 累积重渲染时这些换行仍会变成段首空行。这里最终兜底，正文段永不自带前导空行。
+    while (out.length > 0 && out[0] === '')
+        out.shift();
     // 末尾不留空行:agent onText 后接 onToolCall 的 contentWrite('\n') 会补 1 空行分隔正文与 ● 行;
     // 若 md 末尾自带空行(段落/代码块后)则叠成 2 空行。裁掉末尾连续空行,让 onToolCall / 轮末
     // contentWrite('\n') 恰好补 1 行(与改造前 raw 文本行为一致)。块间空行(flushPara/flushCode 中段

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mocode-ai",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "终端编码 agent:LLM + tool-call 循环 + 流式输出(含思考)+ 16 个工具,接任意 OpenAI 兼容后端。",
   "type": "module",
   "bin": {