minimal-agent 0.5.4 → 0.5.6

package/src/loop.js

@@ -15,18 +15,23 @@
  *    a. 自动压缩检查（防止 context 撑爆）
  *    b. 调 LLM，把流式响应组装成完整的 assistant message
  *    c. 如果 assistant 不调工具 → 结束，return
- *    d. 否则按顺序执行每个工具调用，把 tool 消息追加到历史
+ *    d. 否则并行执行所有工具调用（OpenAI 协议要求 tool 消息按 tool_calls 顺序回填）
  *    e. 进入下一轮（让模型看到 tool_result 后继续推理）
  *
  *  失控保护：maxTurns（默认 50）。
  *  中断支持：AbortSignal 透传到 chat() 和 tool.call()。
+ *
+ *  "工作过程显示"事件：
+ *    - stage_change：thinking / streaming / tool_executing / compacting
+ *    - reasoning：思维链流式增量（仅字符串型 field）
  * ============================================================
  */
+import crypto from 'node:crypto';
 import { autoCompactIfNeeded } from './context/compact.js';
 import { microCompact, incrementTurn, expireOldEntries } from './context/microCompactLite.js';
 import { isPromptTooLongError, reactiveCompactIfApplicable, } from './context/reactiveCompact.js';
-import { chat } from './llm/client.js';
-import { ALL_TOOLS, executeTool } from './tools/index.js';
+import { chat as defaultChat } from './llm/client.js';
+import { ALL_TOOLS, executeTool as defaultExecuteTool } from './tools/index.js';
 /**
  * 执行一次"用户输入 → 模型回答完成"的完整流程。
  *
@@ -35,8 +40,20 @@ import { ALL_TOOLS, executeTool } from './tools/index.js';
 export async function* runQuery(userInput, options) {
     const { provider, history, signal, sessionState } = options;
     const maxTurns = options.maxTurns ?? 50;
-    // 1. 用户消息入栈
-    history.push({ role: 'user', content: userInput });
+    // DI fallback：测试可传 stub，生产走真实模块单例
+    const chatFn = options.chat ?? defaultChat;
+    const executeToolFn = options.executeTool ?? defaultExecuteTool;
+    // 1. 用户消息入栈（v2：填 timestamp，让 MessageList 的 turn 边界横线
+    //    能拿到首条 user 的真实时间，否则 fallback Date.now() 会丢失"提交时刻"语义）
+    history.push({
+        role: 'user',
+        content: userInput,
+        timestamp: Date.now(),
+        id: crypto.randomUUID(),
+    });
+    // 立即通知 UI：用户消息已入栈，触发 bump 让 <Static> 马上把它 commit 进 scrollback，
+    // 不必等整轮 assistant 落定（保证用户输入第一时间置顶，符合 T-A-O-R 展示顺序）。
+    yield { type: 'user_message_committed' };
     // 反应式压缩自救：本 runQuery 只允许触发一次，避免压缩失败导致死循环。
     // 配合 reactiveCompact.ts 的 attempted（session 级）双层防爆。
     let reactiveAttempted = false;
@@ -50,6 +67,8 @@ export async function* runQuery(userInput, options) {
             history.push({
                 role: 'user',
                 content: '(用户按下了 ESC/Ctrl+C 中断了任务)',
+                timestamp: Date.now(),
+                id: crypto.randomUUID(),
             });
             yield { type: 'error', error: '已被用户中断' };
             return;
@@ -59,10 +78,13 @@ export async function* runQuery(userInput, options) {
             const compact = await autoCompactIfNeeded(history, provider);
             if (compact.compacted) {
                 yield { type: 'compact_start' };
+                yield { type: 'stage_change', stage: 'compacting' };
                 // in-place 替换 history（保持调用方持有的引用有效）
                 history.length = 0;
                 history.push(...compact.messages);
                 yield { type: 'compact_done', before: compact.before, after: compact.after };
+                // 压缩完会回到 LLM 调用，stage 退回 thinking
+                yield { type: 'stage_change', stage: 'thinking' };
             }
         }
         catch (e) {
@@ -83,14 +105,22 @@ export async function* runQuery(userInput, options) {
         let reasoningContent = '';
         let reasoningString = '';
         const reasoningDetails = [];
+        /** 首个 text_delta 时切到 streaming，再来不重复 yield */
+        let stageStreamingYielded = false;
+        // 进入 LLM 流前：等首 token / reasoning，本质是 thinking
+        yield { type: 'stage_change', stage: 'thinking' };
         try {
-            for await (const ev of chat({
+            for await (const ev of chatFn({
                 provider,
                 messages: history,
                 tools: ALL_TOOLS,
                 signal,
             })) {
                 if (ev.type === 'text_delta') {
+                    if (!stageStreamingYielded) {
+                        stageStreamingYielded = true;
+                        yield { type: 'stage_change', stage: 'streaming' };
+                    }
                     assistantText += ev.delta;
                     yield { type: 'text', delta: ev.delta };
                 }
@@ -100,16 +130,16 @@ export async function* runQuery(userInput, options) {
                 else if (ev.type === 'reasoning_delta') {
                     if (ev.field === 'reasoning_content' && ev.delta) {
                         reasoningContent += ev.delta;
+                        yield { type: 'reasoning', delta: ev.delta };
                     }
                     else if (ev.field === 'reasoning' && ev.delta) {
                         reasoningString += ev.delta;
+                        yield { type: 'reasoning', delta: ev.delta };
                     }
                     else if (ev.field === 'reasoning_details' && ev.items) {
+                        // reasoning_details 是结构化数组，没有 delta 字符串，跳过 yield
                         reasoningDetails.push(...ev.items);
                     }
-                    if (ev.delta) {
-                        yield { type: 'reasoning_delta', field: ev.field, delta: ev.delta };
-                    }
                 }
                 // ev.type === 'done' 时无需处理：循环自然结束
             }
@@ -120,6 +150,8 @@ export async function* runQuery(userInput, options) {
                 history.push({
                     role: 'user',
                     content: '(用户按下了 ESC/Ctrl+C 中断了任务)',
+                    timestamp: Date.now(),
+                    id: crypto.randomUUID(),
                 });
                 yield { type: 'interrupted' };
                 return;
@@ -130,6 +162,7 @@ export async function* runQuery(userInput, options) {
             if (isPromptTooLongError(e) && !reactiveAttempted) {
                 reactiveAttempted = true;
                 yield { type: 'compact_start' };
+                yield { type: 'stage_change', stage: 'compacting' };
                 const result = await reactiveCompactIfApplicable(history, provider, e, sessionState?.reactive);
                 if (result.recovered) {
                     history.length = 0;
@@ -139,6 +172,8 @@ export async function* runQuery(userInput, options) {
                         before: result.before ?? 0,
                         after: result.after ?? 0,
                     };
+                    // 压缩完回到 LLM 调用
+                    yield { type: 'stage_change', stage: 'thinking' };
                     turn--; // 不消耗 turn 配额，本轮重新走
                     continue;
                 }
@@ -154,6 +189,8 @@ export async function* runQuery(userInput, options) {
             ...(reasoningContent ? { reasoning_content: reasoningContent } : {}),
             ...(reasoningString ? { reasoning: reasoningString } : {}),
             ...(reasoningDetails.length > 0 ? { reasoning_details: reasoningDetails } : {}),
+            timestamp: Date.now(),
+            id: crypto.randomUUID(),
         };
         history.push(assistantMsg);
         yield { type: 'assistant_message', message: assistantMsg };
@@ -162,41 +199,116 @@ export async function* runQuery(userInput, options) {
             yield { type: 'turn_done' };
             return;
         }
-        // 5. 顺序执行每个工具
-        for (const tc of toolCallsByIndex) {
-            if (signal?.aborted) {
-                // 中断标记帮助模型理解上下文：为什么输出被截断，用户可以重新输入
+        // 5. 并行执行所有工具
+        //
+        // 设计：用 Promise.allSettled 启动 N 个 worker，配合一个简易事件队列
+        // （queue + signalNew）把多个 worker 的 tool_start / tool_end 事件按
+        // 真实完成顺序交错 yield 给 UI；但 history 里的 tool 消息严格按
+        // toolCallsByIndex 索引顺序 push（OpenAI 协议要求 tool 消息和上一条
+        // assistant 的 tool_calls 一一对应）。
+        yield { type: 'stage_change', stage: 'tool_executing' };
+        const queue = [];
+        let signalNew = null;
+        const enqueue = (ev) => {
+            queue.push(ev);
+            signalNew?.();
+            signalNew = null;
+        };
+        const workers = toolCallsByIndex.map(async (tc) => {
+            enqueue({
+                type: 'tool_start',
+                toolCallId: tc.id,
+                toolName: tc.function.name,
+                argsPreview: previewArgs(tc.function.arguments),
+                argsFriendly: friendlyToolDescription(tc.function.name, tc.function.arguments),
+            });
+            try {
+                const result = await executeToolFn(tc.function.name, tc.function.arguments, signal);
+                enqueue({
+                    type: 'tool_end',
+                    toolCallId: tc.id,
+                    toolName: tc.function.name,
+                    ok: result.ok,
+                    content: result.ok ? result.content : `Error: ${result.error}`,
+                });
+                return { tc, result };
+            }
+            catch (e) {
+                if (e.name === 'AbortError') {
+                    enqueue({
+                        type: 'tool_end',
+                        toolCallId: tc.id,
+                        toolName: tc.function.name,
+                        ok: false,
+                        content: '(已中断)',
+                    });
+                    return { tc, result: { ok: false, error: 'aborted' } };
+                }
+                const msg = e.message;
+                enqueue({
+                    type: 'tool_end',
+                    toolCallId: tc.id,
+                    toolName: tc.function.name,
+                    ok: false,
+                    content: msg,
+                });
+                return { tc, result: { ok: false, error: msg } };
+            }
+        });
+        const allDone = Promise.allSettled(workers);
+        let finished = false;
+        allDone.then(() => {
+            finished = true;
+            signalNew?.();
+            signalNew = null;
+        });
+        while (!finished || queue.length > 0) {
+            while (queue.length > 0)
+                yield queue.shift();
+            if (finished)
+                break;
+            await new Promise((r) => {
+                signalNew = r;
+            });
+        }
+        // 严格按 toolCallsByIndex 顺序 push tool 消息进 history（OpenAI 协议要求）
+        const settled = await allDone;
+        let anyAborted = false;
+        for (let i = 0; i < toolCallsByIndex.length; i++) {
+            const tc = toolCallsByIndex[i];
+            const r = settled[i];
+            if (r.status === 'rejected') {
+                // 理论上 worker 已经 catch 了所有异常，这里只是防御
+                const errMsg = r.reason?.message ?? 'unknown';
                 history.push({
-                    role: 'user',
-                    content: '(用户按下了 ESC/Ctrl+C 中断了任务)',
+                    role: 'tool',
+                    tool_call_id: tc.id,
+                    content: `Error: ${errMsg}`,
+                    timestamp: Date.now(),
+                    id: crypto.randomUUID(),
                 });
-                yield { type: 'error', error: '已被用户中断' };
-                return;
+                continue;
             }
-            const argsPreview = previewArgs(tc.function.arguments);
-            yield {
-                type: 'tool_start',
-                toolName: tc.function.name,
-                toolCallId: tc.id,
-                argsPreview,
-            };
-            const result = await executeTool(tc.function.name, tc.function.arguments, signal);
-            // 工具结果：失败保留错误信息，成功经微压缩后保留
+            const { result } = r.value;
+            if (!result.ok && result.error === 'aborted')
+                anyAborted = true;
             const rawContent = result.ok ? result.content : `Error: ${result.error}`;
-            const content = microCompact(tc.function.name, rawContent, sessionState?.microCompact);
-            // 工具结果作为 tool 消息回填
+            // 微压缩仅对成功结果走（失败结果通常很短，不需要压缩）
+            const content = result.ok
+                ? microCompact(tc.function.name, rawContent, sessionState?.microCompact)
+                : rawContent;
             history.push({
                 role: 'tool',
                 content,
                 tool_call_id: tc.id,
+                timestamp: Date.now(),
+                id: crypto.randomUUID(),
             });
-            yield {
-                type: 'tool_end',
-                toolName: tc.function.name,
-                toolCallId: tc.id,
-                ok: result.ok,
-                content,
-            };
+        }
+        if (anyAborted || signal?.aborted) {
+            // 任一工具抛 AbortError 时，外层 yield interrupted 并 return
+            yield { type: 'interrupted' };
+            return;
         }
         // 6. 继续 while 让模型看到 tool_result 后继续推理
     }
@@ -231,3 +343,47 @@ function previewArgs(rawJson) {
         return oneLine;
     return oneLine.slice(0, 60) + '...';
 }
+/**
+ * 把工具名 + raw arguments JSON 转换成人话描述。
+ * UI 优先用这个显示在 spinner 行（如 "Reading src/foo.ts"）。
+ * 已知工具走 switch；未知工具或 JSON parse 失败 fallback 到 `${toolName}(...)`。
+ */
+function friendlyToolDescription(toolName, rawArgsJson) {
+    let args = {};
+    try {
+        args = JSON.parse(rawArgsJson) ?? {};
+    }
+    catch {
+        return `${toolName}(...)`;
+    }
+    const truncate = (s, n) => {
+        if (typeof s !== 'string')
+            return '';
+        return s.length > n ? s.slice(0, n) + '…' : s;
+    };
+    switch (toolName) {
+        case 'Read': return `Reading ${truncate(args.file_path, 60)}`;
+        case 'Edit': return `Editing ${truncate(args.file_path, 60)}`;
+        case 'Write': return `Writing ${truncate(args.file_path, 60)}`;
+        case 'Bash': return `Running \`${truncate(args.command, 40)}\``;
+        case 'Grep': {
+            const p = truncate(args.pattern, 30);
+            const g = typeof args.glob === 'string' && args.glob.length > 0 ? ` in ${truncate(args.glob, 25)}` : '';
+            return `Searching \`${p}\`${g}`;
+        }
+        case 'Glob': return `Globbing \`${truncate(args.pattern, 50)}\``;
+        case 'WebFetch':
+        case 'WebBrowser': {
+            try {
+                return `Fetching ${new URL(String(args.url)).host}`;
+            }
+            catch {
+                return `Fetching ...`;
+            }
+        }
+        case 'WebSearch': return `Searching \`${truncate(args.query, 50)}\``;
+        default: return `${toolName}(...)`;
+    }
+}
+// 导出供测试用（friendlyToolDescription 是 module-private 纯函数）
+export { friendlyToolDescription };

package/src/prompts/system.js

@@ -34,17 +34,6 @@ export async function getSystemPrompt(cwd, tools) {
 
 # 思维与立场（核心：像专家一样独立思考）
 - **你是工程协作者，不是奉承者**。不无条件夸赞、不为附和而附和、不同意时直说。不用"很好的问题"、"你说得对"、"完全同意"这类前缀——直接答内容。
-- **先判断用户意图再行动**——这是最重要的第一步，区分以下三种情况：
-  - ✅ **明确执行（直接动手，不要犹豫）**：用户表述包含明确的行动指令。
-    动词特征：「修改/改/调整/修复/优化/更新/替换/删/移除/写/创建/实现/做/生成/新建/开发/执行/跑/运行/提交/部署/安装」
-    确认性指令也算：「对就这么改」「是的按这个方案实现」「好的麻烦改一下」
-  - ❌ **纯讨论（绝对不能动文件，只回答）**：用户只是提问、咨询、探讨、评估。
-    特征：问号结尾、「是不是/怎么样/为什么/好不好/能否/你觉得」、纯观点表达「我觉得...」「这里好像有...」
-    即使你发现明显问题，也只能给文字建议，**禁止调用 Edit/Write/MultiEdit/Bash 写操作等任何修改类工具**
-  - ❓ **模糊场景（仅一次确认，不要啰嗦）**：介于两者之间无法判断时。
-    例：「这个接口响应太慢了」「这个正则好像有问题」
-    只问一句：「你是需要我实际修改/修复，还是只是讨论这个问题？」—— 用户说改就立刻改，说讨论就停
-- **兜底原则**：宁可多问一次也不要擅自修改；但只要用户明确说要改，必须立刻执行，不要二次确认。
 - **基于证据，不基于揣测用户想听什么**。没读过的代码先 Read，没验证过的行为先验证，不凭印象答。回答前先问自己：这个判断有具体证据吗，还是我在猜？
 - **不知道就说不知道**。明确边界："这个版本号我不确定"、"这个 API 我没看过文档"、"这部分行为我没验证过"。胡编一个看起来对的答案，代价远高于承认不知道。
 - **明示 confidence 分层**。结论按确定度分层表达——"已 verify / 高度确信"、"基于代码合理推测"、"未验证猜测"——让用户基于你的不确定程度决策，不要把推测说成事实。
@@ -52,6 +41,7 @@ export async function getSystemPrompt(cwd, tools) {
 - **给根因不给表面答案**。bug 报告先定位 root cause 再给 fix，不要先给个让症状消失的 workaround 蒙混过去。修复要能解释"为什么这样改就对了"。
 - **任何方案都有代价**。主动说 trade-off（性能 vs 可读、激进 vs 保守、本期 vs 长期），让用户基于全貌决策，不要只夸方案的优点。
 - **被指出错误时直接承认 + 修正**。不解释、不防御、不找借口。承认 → 给出修正 → 避免下次。错误是 update prior 的信号，不是要消化的尴尬。
+- **读过就别反复读，验证过就别反复验**。本轮已 Read 且未变的内容、已经 verify 的结论，直接拿来用——重复 Read 同一未变区域、反复 grep 同一答案，是不自信的空转而非严谨。真严谨是"一次读对、读透"，不是"读很多次"；读完就基于已读内容推进。
 
 # 工作环境
 - 当前工作目录: ${cwd}
@@ -73,6 +63,7 @@ ${toolList}
 - 修改既有文件之前，必须用 Read 工具读取相关代码的最新内容。
   "我记得"、"我之前看过"、"应该差不多"都不算读过——必须在本轮任务中实际调用 Read。
   尤其当你要参考某个文件的写法来实现类似功能时，必须先重读该文件的关键部分（函数实现、判断逻辑、数据流），理解清楚后再动手。
+  反过来：**本轮已 Read 过、且你没用 Edit/Write 改动过的区域，不要重复 Read**——直接基于已读内容操作。如果你重复读取同一未变区域，结果头部会出现"已读过该区域"的提示，看到就停止重读、立刻用已有内容推进（重复读既费轮次又是死循环前兆）。
 - Edit / MultiEdit 拦截 fallback：如果你忘了先 Read 就直接调 Edit/MultiEdit，错误响应里会**自动附带当前文件前 200 行 / 32KB 以内的 snippet**（带行号）。这种情况下**直接基于 snippet 重新构造 old_string 再发一次 Edit 即可，不要再额外调 Read**。只有当 snippet 显示"未注入内容"（文件过大或二进制）时才需要显式 Read。Write 不附带 snippet——整文件覆盖语义下必须先显式 Read，避免基于片段重写导致截断范围外内容丢失。
 - Edit 工具的 old_string 必须在文件中唯一；不唯一时请扩大上下文或显式 replace_all=true。
 - 同一文件需要修改多处（3 处及以上）时优先用 MultiEdit：所有 edit 按顺序在内存中应用，**全部成功才落盘**；任一失败磁盘不动，避免中间状态污染。单点修改继续用 Edit。
@@ -138,16 +129,25 @@ ${skillHint}
 - 如果用户的请求不清晰，先用一句话澄清再动手。
 - 任务完成后用一两句话总结改了什么，不要长篇大论。
 
+# 修改 vs 讨论（动手边界，重要）
+先判断用户要的是"动手改"还是"聊一聊"，再决定要不要写盘——默认克制、被要求才行动：
+- **默认是讨论/分析/给方案**：除非判定用户要你改，否则只回答、只给建议，**不调用 Edit/Write/MultiEdit、不跑会改状态或破坏性的 Bash**。未经允许的修改和"不读就改"一样是越界。
+- **只读工具不受此限**：Read/Grep/Glob/WebSearch/WebFetch 任何时候都能直接用——读代码、查资料是"理解"不是"动手"，讨论也要先把事实读准。
+- **命中修改意图就果断改，别反问试探**：祈使式动词（改/加/删/修/修复/重构/实现/优化/重命名/迁移/接上/补全…）、明确的"直接改/帮我写/动手/落地"、或一个可执行的 bug 修复请求——都是放行信号，直接干。别再用"要不要我帮你改"来回打转，那是讨好型的犹豫。
+- **纯讨论意图就别擅自改**：以"为什么/是不是/能不能/看看/评估下/解释下/你怎么看/可行吗/有没有问题"为主、没有修改祈使的，给分析和建议即可，不要顺手把代码改了。
+- **只有"讨论还是修改"真拿不准时**，才用一句话澄清（"你是想我直接改，还是先讨论方案？"）再停；能从措辞判断的就别问。
+
 # 中断支持
 - 用户可以随时按 ESC 或 Ctrl+C 中断你的工作。
 - 中断后等待用户输入新任务，不要自行继续执行被中断的操作。
 - 如果用户输入了新任务，直接响应新任务，不必提及之前被中断的操作。
 
-# 任务识别
-- 用户开始新任务时（"帮我做 X"、"这次做 YYY"），不要继续之前未完成的旧任务
-- 用户说"继续"、"接着做"、"再加一个"时，保持当前任务上下文
-- 用户说"重新开始"、"不算了，做 X"时，立即放下旧任务
-- 意图模糊时，先用一句话澄清："你是继续刚才的，还是开始新的？"`;
+# 任务边界与上下文关联（每轮开工前自检）
+用户不会一问一会话，历史里常混着已结束的旧任务。每轮开工前先答三个问题，再决定怎么用上下文：
+1. **这是新任务还是上一任务的延续？**——"继续/接着做/再加一个/还有"=延续，保持当前任务上下文；"帮我做 X/这次做 Y/另外"=多半是新任务；"重新开始/不算了，做 X"=立即放下旧任务。
+2. **历史里哪些和当前问题相关？**——只把与当前问题直接相关的消息、文件、工具结果当活动上下文；无关的旧任务细节当背景，**不要拿旧任务的结论/文件/方案硬套当前问题**（典型翻车：上个任务在改 A，这次问的是 B，却惯性去翻 A）。
+3. **判不准边界就先确认**：一句话澄清"你是继续刚才的 X，还是开始新的？"，别默默假设。
+- 当前用户消息 + 紧邻的最近几条消息，权重永远高于更早历史；越早、越不相关的内容参考价值越低。`;
 }
 /**
  * 生成完整系统提示词：getSystemPrompt + 项目级 minimal-agent.md 指令。

package/src/tools/read/read.js

@@ -62,6 +62,8 @@ Usage:
 - This tool cannot read binary files. Files whose extensions are on the binary blocklist (images: .png/.jpg/.gif/.webp/..., documents: .pdf/.docx/.xlsx/..., executables: .exe/.dll/.so/..., archives: .zip/.tar/.gz/..., and others) will be rejected with a clear error. If the file is actually text despite the extension (e.g., a misnamed log), rename it or use Bash \`cat\` to read it directly — do not retry Read with the same path.`;
 // ---------------- 4. call() —— 真正干活 ----------------
 const STREAM_THRESHOLD = 1024 * 1024;
+/** "同区重读空转"提示：同一区间 + 文件未变 + 第二次起，前置到结果头部（仅提示，不拦截）。 */
+const REREAD_HINT = '⚠️ 你本轮已经读过该文件的这一区间，且文件未发生变化——请直接基于上次读到的内容操作，不要重复读取空转。如果你其实在找别的内容，改用不同的 offset/limit，或用 Grep 精确定位。\n\n';
 async function call(input) {
     const offset = input.offset ?? 1;
     const limit = input.limit ?? MAX_LINES_TO_READ;
@@ -145,7 +147,9 @@ async function call(input) {
     if (st.size > 100 * 1024 && offset === 1) {
         content += `\n\n⚠️ 注意：这是一个大文件（${(st.size / 1024).toFixed(1)} KB）。建议用 offset/limit 分段读取，例如先读关键部分（imports、exports、函数签名）。`;
     }
-    recordRead(filePath, { truncated });
+    const readCount = recordRead(filePath, { truncated, offset, limit });
+    if (readCount >= 2)
+        content = REREAD_HINT + content;
     return { ok: true, content };
 }
 async function readSmallFile(filePath, offset, limit) {

package/src/tools/shared/fileState.js

@@ -12,21 +12,44 @@
  *    3. 当前 mtime > 记录的 mtime → 报错"文件被外部修改"
  *
  *  /new 调用 clearContext 时连带调 clearFileState() 防残留。
+ *
+ *  v2 增量（防"读后空转"）：recordRead 额外记录最近一次读取的 (offset, limit)
+ *  与"同区连续重读次数"，并返回该次数。Read 工具据此在"同一区间 + 文件未变 +
+ *  第二次起"时给模型一行"别重复读、直接用已读内容"的提示（仅提示，不拦截）。
+ *  文件一旦被 Edit/Write 或外部改动（mtime 漂移），重读即合法、计数归 1。
  * ============================================================
  */
 import { existsSync, statSync } from 'node:fs';
 const fileState = new Map();
+/**
+ * 记录一次 Read，返回本次是"同区重读"的第几次（首次=1）。
+ *
+ * "同区重读" = 文件 mtime 未漂移（内容没变） + 这次 (offset,limit) 与上次完全相同。
+ * 调用方（Read 工具）据返回值 >= 2 判定模型在空转、给提示。
+ * 文件被 Edit/Write 或外部改动（mtime 漂移）即视为合法重读，计数归 1、不提示。
+ */
 export function recordRead(absPath, opts) {
     try {
         const st = statSync(absPath);
+        const prev = fileState.get(absPath);
+        const sameRegionUnchanged = prev !== undefined &&
+            st.mtimeMs <= prev.timestamp &&
+            prev.offset === opts?.offset &&
+            prev.limit === opts?.limit;
+        const reads = sameRegionUnchanged ? (prev.reads ?? 1) + 1 : 1;
         fileState.set(absPath, {
             timestamp: st.mtimeMs,
             size: st.size,
             truncated: opts?.truncated ?? false,
+            offset: opts?.offset,
+            limit: opts?.limit,
+            reads,
         });
+        return reads;
     }
     catch {
         // 文件不存在或无权访问 —— 不记录，让 Read 自己处理错误
+        return 1;
     }
 }
 /** 查询上次 Read 是否被截断。供 Edit/MultiEdit 给出更精准 error hint、Write 做 hard guard 用。 */