mocode-ai 1.6.4 → 1.6.5

package/dist/session/usage-stats.js

@@ -0,0 +1,90 @@
+/** 从 ChatUsage 构造记录;usage 缺失返 null。 */
+export function toUsageRecord(step, phase, usage, estimatedTotal) {
+    if (!usage)
+        return null;
+    return {
+        step,
+        phase,
+        inputTokens: usage.promptTokens,
+        outputTokens: usage.completionTokens,
+        cachedTokens: usage.cachedTokens,
+        reasoningTokens: usage.reasoningTokens,
+        ...(usage.cacheCreationTokens ? { cacheCreationTokens: usage.cacheCreationTokens } : {}),
+        ...(estimatedTotal != null ? { estimatedTotal } : {}),
+    };
+}
+function emptyTotals() {
+    return { input: 0, output: 0, cached: 0, reasoning: 0, cacheCreation: 0, calls: 0 };
+}
+function add(totals, r) {
+    totals.input += r.inputTokens;
+    totals.output += r.outputTokens;
+    totals.cached += r.cachedTokens;
+    totals.reasoning += r.reasoningTokens;
+    totals.cacheCreation += r.cacheCreationTokens ?? 0;
+    totals.calls++;
+}
+function hitRate(t) {
+    if (t.calls === 0)
+        return null;
+    // 后端从未上报过 cached → 无法计算,不是 0%。
+    if (t.cached === 0)
+        return null;
+    return t.cached / Math.max(t.input, 1);
+}
+export function summarizeUsage(records) {
+    const main = emptyTotals();
+    const compact = emptyTotals();
+    let cacheReported = false;
+    let estimateRatioSum = 0;
+    let estimateSamples = 0;
+    for (const r of records) {
+        add(r.phase === 'compact' ? compact : main, r);
+        if (r.cachedTokens > 0)
+            cacheReported = true;
+        if (r.estimatedTotal && r.estimatedTotal > 0) {
+            estimateRatioSum += r.inputTokens / r.estimatedTotal;
+            estimateSamples++;
+        }
+    }
+    const total = emptyTotals();
+    for (const r of records)
+        add(total, r);
+    // 全部记录里从未出现 cached 字段 → 所有命中率都 n/a;
+    // 有过 cached(即使某 phase 为 0)则该 phase 按真实 0 计算。
+    const rate = (t) => {
+        if (!cacheReported || t.calls === 0)
+            return null;
+        return t.cached / Math.max(t.input, 1);
+    };
+    return {
+        records: records.length,
+        compactCalls: compact.calls,
+        main,
+        compact,
+        total,
+        cacheHitRate: hitRate(total),
+        mainCacheHitRate: rate(main),
+        compactCacheHitRate: rate(compact),
+        reasoningShare: total.output > 0 ? total.reasoning / total.output : 0,
+        estimateRatio: estimateSamples > 0 ? estimateRatioSum / estimateSamples : null,
+    };
+}
+function pct(n) {
+    return n == null ? 'n/a' : `${(n * 100).toFixed(1)}%`;
+}
+function fmtTotals(t) {
+    return `${t.calls} calls · in ${t.input} · out ${t.output} · cached ${t.cached} · reasoning ${t.reasoning}`;
+}
+/** 拍平成人类可读(/stats 命令输出)。 */
+export function formatUsageSummary(s) {
+    const lines = [];
+    lines.push(`Token usage — ${s.records} record(s), ${s.compactCalls} compact call(s)`);
+    lines.push(`  Cache hit rate: total ${pct(s.cacheHitRate)} · main ${pct(s.mainCacheHitRate)} · compact ${pct(s.compactCacheHitRate)}`);
+    lines.push(`  Main      ${fmtTotals(s.main)}`);
+    if (s.compact.calls > 0)
+        lines.push(`  Compact   ${fmtTotals(s.compact)}`);
+    lines.push(`  Total     in ${s.total.input} · out ${s.total.output} · reasoning share ${(s.reasoningShare * 100).toFixed(1)}%` +
+        (s.estimateRatio != null ? ` · measured/estimate ${s.estimateRatio.toFixed(2)}` : ''));
+    return lines.join('\n');
+}

package/dist/skills/activation.js

@@ -20,6 +20,8 @@ export function activateSkill(skill) {
     active = {
         name: skill.name,
         disallowed: disallowed.size > 0 ? disallowed : null,
+        // 后者带 effort 则覆盖;没带则继承前一 skill 的设置。
+        effort: skill.effort ?? active?.effort,
     };
 }
 /** 用户新轮开始时清激活态。 */

package/dist/skills/builtin-skills.js

@@ -40,6 +40,111 @@ run_command({ command: "codegraph node <symbol-or-path>" })
 
 CLI dump 一般是 \`path/to/file.ts:line:col  symbol\` 形式,与 grep 一样可被 read_file 消费。
 `;
+const BRAINSTORM_BODY = `# Brainstorming(需求澄清)
+
+开工前的需求澄清流程:当需求可能被理解错、或信息不足以决定交付物时,先用对话把需求问清楚,再动手。
+
+## 何时进入
+
+- 用户的需求存在两种以上实质不同的理解,会导致不同交付物;
+- 缺少关键信息(目标、范围、约束、输入输出、验收标准),且靠仓库证据无法补全;
+- 改动涉及不可逆操作 / 公共 API / 多个会实质改变产品行为的方案;
+- 用户只给了粗略想法(如「帮我做个 X」),期望先讨论。
+
+## 何时不要进入
+
+- 任务清晰且存在合理默认做法 → 直接干,在最终回复中披露假设;
+- 只是命名或实现细节 → 遵循仓库惯例自主决定;
+- 用户已明确表示「直接做 / 别问我」。
+
+## 流程
+
+1. **最小探查**:只读取提出好问题所必需的代码和上下文(有 .codegraph/ 时优先 codegraph skill),不要在澄清阶段做大范围调研。
+2. **复述理解**:用一两句向用户复述你对需求的理解,并点出关键分歧或未知点。
+3. **一次只问一个问题**:每轮 \`ask_human\` 只问当前最关键的一个问题,自由文本优先(\`options: []\`);仅当答案能收敛为少量明确选项时才给 2-4 个选项。不要一次甩多个问题。
+4. **据回答继续**:必要时追问下一个最关键的问题;回答引出新歧义时先澄清新歧义。不要重复问已回答的内容。
+5. **收敛确认**:需求清晰后,用一次 \`ask_human\` 分节呈现方案——目标 / 范围 / 做法与受影响文件 / 不做什么 / 验证方式,选项固定为「确认,开始做」「再调整」「取消」。
+6. **转入执行**:用户确认后再开始改动。
+
+## 边界
+
+- 澄清阶段的 \`ask_human\` 不计入「执行阶段每轮最多 2 次」的预算,但仍要克制:每个问题都必须实质推进理解。用户表现出不耐烦或说「你决定」时,采用最安全的可逆默认做法并说明。
+- 用户取消:停止,不要按自己的猜测继续。
+- 问题与方案用用户的语言表述。
+- 澄清期间保持只读:不改文件、不跑有副作用的命令。
+`;
+const DEBUGGING_BODY = `# Systematic Debugging(系统化调试)
+
+遇到 bug、测试失败或报错时,用「先理解再修」的流程,禁止靠猜测随机改动。
+
+## 核心原则
+
+- 没有找到根因之前,不要改代码。症状不是原因。
+- 一次只改一处;改完无法解释为什么有效,就不算修好。
+- 不要用「删掉重试 / 换个写法试试 / 加个 await 碰碰运气」这类无假设的尝试。
+
+## 流程
+
+1. **复现**:先稳定复现问题。复现不了,先弄清楚触发条件(输入、环境、顺序),必要时向用户索取复现步骤或报错全文。
+2. **收集证据**:读完整报错和堆栈,定位到具体文件/行;用日志或最小用例确认数据在**哪一步**开始出错。有 .codegraph/ 时用它追调用链。
+3. **形成根因假设**:用一句话说明「为什么当前行为会必然产生这个症状」,并指出能证伪它的检查点。
+4. **验证假设**:先做最小检查确认假设成立,再动手。如果证据与假设矛盾,回到第 2 步,不要硬修。
+5. **最小修复**:只改根因,不动无关代码;避免为绕过症状而加补丁、吞异常、放宽校验。
+6. **验证修复**:复现用例通过;补一个能覆盖该 bug 的回归测试(成本合理时);检查同类路径是否也受影响。
+7. **复盘**:说明根因、改动、验证方式;仍有不确定就如实说。
+
+## 反模式
+
+- 报错还没看完就开始改;
+- 同一处反复改了 3 次仍失败却不换思路;
+- 修复让错误「消失」但说不清机制(往往只是被掩盖);
+- 顺手重构与 bug 无关的代码。
+`;
+const CODE_REVIEW_BODY = `# Code Review(自审 diff)
+
+提交/收尾前,对**自己本次的改动**做一遍审查。改动越多越要做;几行的机械改动可快速过。
+
+## 流程
+
+1. **拿到完整 diff**:只审本次相关改动(\`git diff\` / 未提交改动),不要凭记忆。
+2. **意图对齐**:每处改动是否都服务于任务?有没有夹带无关重构、调试残留(console.log、注释掉的代码、临时文件)?
+3. **正确性**:逻辑分支是否完整;边界(空值、空数组、并发/重复调用、错误路径);条件取反、off-by-one;异步是否有未 await 或未处理的 rejection。
+4. **错误处理**:失败时是否给出有用信息而非静默吞掉;资源(文件句柄、锁、子进程)是否正确释放。
+5. **兼容与契约**:公共 API、类型、配置键、默认值是否保持兼容;是否违背仓库既有约定(如纯 ESM 的 .js 扩展名、工具契约)。
+6. **安全与副作用**:是否引入不可逆操作、权限绕过、注入面;写入/执行是否走了既有护栏。
+7. **完整性**:文档、调用方、测试是否需要同步;用户要求的场景是否都覆盖。
+8. **修复后复审**:发现问题就改,改完重新看那部分 diff,确认没有引入新问题。
+
+## 输出
+
+如实质问题:直接修复,最终回复中列出发现并修复了什么。
+如无问题:简要说明审过哪些点。不要为了凑数报无关紧要的风格问题——格式交给 Prettier。
+`;
+const VERIFICATION_BODY = `# Verification Before Completion(完成前证据验证)
+
+宣布任务「完成」之前,必须用实际运行的证据确认改动真的生效。禁止把「代码看起来对 / 应该能跑」当作完成。
+
+## 硬性规则
+
+1. **先验证,再宣称完成**:任何「已修复 / 已完成 / 能用了」的结论,前面必须有一次实际执行及其真实输出。
+2. **验证必须对得上声称**:改了行为就跑能体现该行为的场景;修了 bug 就用能复现该 bug 的输入确认;不能用「编译通过」代替「功能正确」。
+3. **看完整结果**:确认退出码、断言/测试通过数、关键输出行;有 warning 或失败项要逐条判断,不能只看最后一行没报错。
+4. **验证不了就如实说**:环境缺失、需要用户凭据/设备、或验证成本明显不合理时,说明已验证到哪一步、什么没验证、用户可以怎么验证。不要假称已验证。
+
+## 怎么选验证(按成本,够小即可)
+
+- 优先最小相关检查:拥有该改动的包的 typecheck / 一个针对性测试 / 直接运行受影响入口;
+- 不要为了「保险」默认跑全量 test/build;
+- UI/交互类改动:能自动化就自动化(浏览器工具/webapp 测试),否则明确告知未做可视化验证;
+- 纯文档、注释等零行为改动:可不跑验证。
+
+## 反模式
+
+- 「理论上没问题」「逻辑上应该可以」——没有运行证据就不算完成;
+- 测试其实失败/被跳过,却报告成功;
+- 跑了一个与改动无关的检查,用它冒充验证;
+- 改完代码不重新运行,沿用改动前的旧结果。
+`;
 /** 单一事实源:加新内置 skill 在此数组加一条。 */
 export const builtinSkills = [
     {
@@ -56,6 +161,54 @@ export const builtinSkills = [
         origin: 'builtin',
         warnings: [],
     },
+    {
+        name: 'brainstorming',
+        description: '需求澄清(开工前对话):当用户需求可能被误解、信息不足、存在多种实质不同方案,或只给了粗略想法时,' +
+            '先用「一次一个问题」的对话澄清需求,分节呈现方案并获得确认,再开始写代码。任务清晰时不要使用。',
+        body: BRAINSTORM_BODY,
+        dir: 'builtin',
+        skillMdPath: 'builtin',
+        context: 'inline',
+        modelInvocable: true,
+        origin: 'builtin',
+        warnings: [],
+    },
+    {
+        name: 'systematic-debugging',
+        description: '系统化调试:遇到 bug、测试失败或报错时,先稳定复现并定位根因(读完堆栈、用证据验证假设),再做最小修复并回归验证。' +
+            '禁止没找到根因就靠猜测反复改代码。',
+        body: DEBUGGING_BODY,
+        dir: 'builtin',
+        skillMdPath: 'builtin',
+        context: 'inline',
+        modelInvocable: true,
+        origin: 'builtin',
+        warnings: [],
+    },
+    {
+        name: 'code-review',
+        description: '收尾前自审本次 diff:意图对齐、正确性与边界、错误处理、API/约定兼容性、安全副作用、文档与测试完整性,' +
+            '发现问题直接修复后复审。改动较多或涉及核心逻辑时使用;纯机械小改可快速过。',
+        body: CODE_REVIEW_BODY,
+        dir: 'builtin',
+        skillMdPath: 'builtin',
+        context: 'inline',
+        modelInvocable: true,
+        origin: 'builtin',
+        warnings: [],
+    },
+    {
+        name: 'verification-before-completion',
+        description: '完成前证据验证:宣布「已修复/已完成」前必须实际运行过相关检查并看到真实输出(退出码、测试通过数、关键输出),' +
+            '验证内容要对得上声称;无法验证时如实说明。适用于一切有行为改动的收尾,纯文档改动除外。',
+        body: VERIFICATION_BODY,
+        dir: 'builtin',
+        skillMdPath: 'builtin',
+        context: 'inline',
+        modelInvocable: true,
+        origin: 'builtin',
+        warnings: [],
+    },
 ];
 /** 内置 skill 名字集,供 discoverSkills 跳过/覆盖时使用。 */
 export const builtinSkillNames = new Set(builtinSkills.map((s) => s.name));

package/dist/skills/discover.js

@@ -8,6 +8,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { parseReasoningEffort } from '../llm/reasoning.js';
 import { builtinSkillNames } from './builtin-skills.js';
 /** 把开头的 ~/ 或 ~ 展开为 home 目录(Windows 与 POSIX 通用)。 */
 function expandHome(p) {
@@ -94,7 +95,7 @@ function resolveContext(meta) {
  *  该字段不再产生任何效果,按"已忽略"提示作者,避免其误以为仍有限权语义。 */
 function collectWarnings(meta) {
     const warnings = [];
-    for (const k of ['hooks', 'model', 'effort', 'paths', 'agent']) {
+    for (const k of ['hooks', 'model', 'paths', 'agent']) {
         if (k in meta)
             warnings.push(`字段 "${k}" 当前不支持,已忽略`);
     }
@@ -238,6 +239,7 @@ export function discoverSkills() {
                     disallowedTools: asArray(meta, 'disallowed-tools'),
                     modelInvocable: !truthy(meta, 'disable-model-invocation'),
                     maxSteps: num(meta, 'max-steps'),
+                    effort: parseReasoningEffort(scalar(meta, 'effort')),
                     argumentHint: scalar(meta, 'argument-hint')?.trim() || undefined,
                     whenToUse: scalar(meta, 'when_to_use')?.trim() || undefined,
                     origin,

package/dist/skills/runner.js

@@ -13,6 +13,7 @@ import { isSkillTrusted, ensureSkillTrust } from './trust.js';
 import { mapSkillTools } from './toolmap.js';
 import { spawnAgent } from '../agent/spawn.js';
 import { runCommandRaw } from '../tools/builtins/run-command.js';
+import { runWithEffortScope } from '../llm/reasoning.js';
 const MAX_INJECTIONS = 4;
 const MAX_INJECTION_OUTPUT = 4096;
 const INJECT_TIMEOUT = 10_000;
@@ -168,7 +169,7 @@ export async function runSkill(a, ctx) {
         // 仅记到正文前导,模型可感知哪些 allowed-tools 被忽略(不阻断执行)。
         body = `> 注意:以下 allowed-tools 无法映射到 mocode 工具,已忽略: ${unknown.join(', ')}\n\n` + body;
     }
-    const res = await spawnAgent({
+    const execute = () => spawnAgent({
         prompt: SKILL_PROTOCOL_HEADER + '\n\n' + body,
         tools: tools ?? undefined,
         maxSteps: skill.maxSteps,
@@ -180,5 +181,7 @@ export async function runSkill(a, ctx) {
         parentAllowedToolNames: ctx?.allowedToolNames,
         delegation: ctx?.delegation,
     });
+    // skill frontmatter effort 覆盖会话级(ALS 沿子 agent 异步树继承)。
+    const res = skill.effort ? await runWithEffortScope(skill.effort, execute) : await execute();
     return toOutcome(res);
 }

package/dist/tools/builtins/index.js

@@ -23,6 +23,7 @@ import { memoryForgetTool } from './memory-forget.js';
 import { memoryGraphTool } from './memory-graph.js';
 import { subAgentTool } from './task.js';
 import { computerTool } from './computer.js';
+import { sessionSearchTool } from './session-search.js';
 /**
  * 所有内置工具,按注册顺序排列。
  * 加新工具:在本目录新建 `xxx.ts` 导出一个 Tool,再在下面数组里加一行。无需改 agent / llm。
@@ -70,6 +71,8 @@ export const CAPABILITIES = {
     memory_forget: { effect: 'write', concurrency: 'serial', resources: memoryResource },
     // memory_graph:search/neighbors/stats 只读、add 写,统一按写处理走串行(调用不频繁,简化)。
     memory_graph: { effect: 'write', concurrency: 'serial', resources: memoryResource },
+    // session_search 只读归档索引,纯本地无副作用;串行(每次重建 BM25 索引,避免并发交错)。
+    session_search: { effect: 'read', concurrency: 'serial' },
     // computer 桌面操控:桌面状态全局唯一,任何两个 computer 调用都不允许并发;
     // effect=process(不写工作区文件,不触发 rollback/diff 追踪),supportsAbort 中断长 wait/拖拽。
     computer: { effect: 'process', concurrency: 'serial', resources: () => ['desktop'], supportsAbort: true },
@@ -111,6 +114,7 @@ const rawBuiltinTools = [
     memoryGraphTool,
     subAgentTool,
     computerTool,
+    sessionSearchTool,
 ];
 /** 所有内置工具均携带显式能力；新增工具遗漏声明时 registry 会保守串行。 */
 export const builtinTools = rawBuiltinTools.map((tool) => ({

package/dist/tools/builtins/read-file.js

@@ -3,6 +3,7 @@ import { resolve } from 'node:path';
 import { contentHash } from '../../changeset/index.js';
 import { IMAGE_READ_MARKER, MAX_FILE_LINES } from '../constants.js';
 import { MAX_INLINE_BYTES_DEFAULT, isProbablyBinary, loadImageAttachmentWithDownscale, sniffImageMime, } from '../../attachments/image.js';
+import { config } from '../../config/index.js';
 /** 默认单次 read_file 拉取的行数。刻意压低,逼 LLM 分块读大文件,
  * 配合 description 中的 PAGINATION IS MANDATORY 引导。
  * 300 行 ≈ 一个屏幕的源码量,够定位一段逻辑而不至于吃光上下文。 */
@@ -56,7 +57,7 @@ export const readFileTool = {
         },
         required: ['path'],
     },
-    async execute(args) {
+    async execute(args, toolCtx) {
         const path = String(args.path);
         const offset = Number(args.offset ?? 1);
         // 无论 LLM 传多大,单次硬钳到 MAX_FILE_LINES,杜绝「绕过分页引导一把全拿」。
@@ -122,9 +123,26 @@ export const readFileTool = {
         // 让模型误以为读到了带一行空白的文件。data.length===0 才是真·空的判据。
         if (data.length === 0)
             return { status: 'success', code: 'OK', retryable: false, output: `${artifactHeader}\n(空文件)` };
+        // P2 重复读短路:同区间 + hash 未变 + 内容仍在 context → 短指针。
+        const reqStart = start + 1;
+        const reqEnd = end;
+        const dedup = toolCtx?.readDedup;
+        if (config.readDedup && dedup) {
+            const hit = dedup.findUnchanged(path, reqStart, reqEnd, contentHash(data));
+            if (hit) {
+                return {
+                    status: 'success',
+                    code: 'OK',
+                    retryable: false,
+                    output: `${artifactHeader}\n[unchanged since step ${hit.step}, hash=${hit.hash}] ` +
+                        '该区间内容已在上方上下文中,未重复返回;若已被压缩或确需重读,请忽略本提示再读一次。',
+                };
+            }
+        }
         const output = end < lines.length
             ? `${artifactHeader}\n${body}\n\n... (${lines.length - end} 行未显示,共 ${lines.length} 行)`
             : `${artifactHeader}\n${body}`;
+        dedup?.record(path, reqStart, reqEnd, contentHash(data));
         return { status: 'success', code: 'OK', retryable: false, output };
     },
 };

package/dist/tools/builtins/session-search.js

@@ -0,0 +1,33 @@
+import { config } from '../../config/index.js';
+import { searchArchiveIndex } from '../../session/retention.js';
+// ---------- session_search ----------
+// episodic 层入口:跨会话搜索已归档会话(首条用户消息 + 摘要,BM25)。
+// 已 purge(正文已删)的会话同样可命中——meta+摘要永久保留。需要整段恢复时,
+// 未 purge 的会话仍可用 --resume <id> 从 archive 取回(见 retention loadArchivedSession)。
+export const sessionSearchTool = {
+    name: 'session_search',
+    description: 'Search archived past sessions in this workspace by keyword (BM25 over the first user message and the session summary). Returns session id, date, and summary. Use to recall what was decided or done in earlier conversations.',
+    parameters: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'Keywords describing the past session' },
+            limit: { type: 'integer', description: 'Number of sessions to return, default 10' },
+        },
+        required: ['query'],
+    },
+    async execute(args) {
+        const query = String(args.query ?? '').trim();
+        if (!query)
+            return '错误:缺少 query。';
+        const limit = typeof args.limit === 'number' ? args.limit : 10;
+        const hits = searchArchiveIndex(config.sessionDir, query, limit);
+        if (hits.length === 0)
+            return `(无匹配的归档会话:query="${query}")`;
+        return hits
+            .map((h) => {
+            const status = h.purgedAt ? ' [正文已清除,仅摘要]' : '';
+            return `# ${h.id} · ${h.createdAt}${status}\n${h.summary || h.firstUser}`;
+        })
+            .join('\n\n---\n\n');
+    },
+};

package/dist/tools/builtins/task.js

@@ -81,6 +81,8 @@ export const subAgentTool = {
             retryable: false,
             output,
             usage: result.usage,
+            // P4 闸3:只归属本子 agent 树真实改动;tool-runtime 允许工具自报覆盖整轮快照。
+            changedFiles: result.changedFiles ?? [],
         };
         return outcome;
     },

package/dist/tools/constants.js

@@ -18,6 +18,14 @@ export const MAX_HISTORY_RESULT = 8000;
 export const MAX_SKILL_RESULT = 64000;
 /** 微压缩时旧工具结果截到的存根长度(字符)。 */
 export const MAX_OLD_TOOL_STUB = 600;
+// ── 磁盘侧治理(见 session/store.ts)──────────────────────────────────────
+/** trace.jsonl 单文件大小上限(字节):超过即把整份 gzip 轮转为 trace.N.jsonl.gz 并清空。
+ *  trace 是纯诊断数据,可激进轮转;512KB 约含千余条事件。 */
+export const MAX_TRACE_BYTES = 512 * 1024;
+/** 保留的历史 trace 轮转份数(trace.1 .. trace.N),更老的硬删。 */
+export const MAX_TRACE_ROTATIONS = 3;
+/** rollback snapshots 压缩前滚动窗口:无论是否 compact,仅保留最近 N 个 user turn 的快照。 */
+export const MAX_SNAPSHOT_TURNS = 50;
 // ── 上下文压缩摘要(见 session/compact.ts defaultSummarize)────────────────
 /** 摘要输入单条消息封顶:逐条封顶保证每轮对话都有代表,替代整段中截(会切掉中间整轮)。
  *  转录总量超 SUMMARY_TRANSCRIPT_WINDOW_RATIO 时,这些封顶会被等比缩小重拼。 */

package/dist/tools/read-dedup.js

@@ -0,0 +1,62 @@
+const MAX_RANGES_PER_PATH = 5;
+const MAX_PATHS = 200;
+export class ReadDedup {
+    /** Map 保序:超容量时删最老(第一个)key。 */
+    entries = new Map();
+    currentStep = 0;
+    /** model-turn 每步调用:钉住 step(指针消息里展示 "since step K")。 */
+    beginStep(step) {
+        this.currentStep = step;
+    }
+    /** trim 变更 history 内容后调用:所有存活条目失活(其内容可能已不在 context)。 */
+    markContextChanged() {
+        for (const list of this.entries.values())
+            for (const e of list)
+                e.hot = false;
+    }
+    touch(path) {
+        let list = this.entries.get(path);
+        if (list) {
+            // LRU:命中路径挪到末尾。
+            this.entries.delete(path);
+        }
+        else {
+            list = [];
+            if (this.entries.size >= MAX_PATHS) {
+                const oldest = this.entries.keys().next().value;
+                if (oldest !== undefined)
+                    this.entries.delete(oldest);
+            }
+        }
+        this.entries.set(path, list);
+        return list;
+    }
+    /** 记录一次实际返回的读取(全量返回之后调用)。 */
+    record(path, startLine, endLine, hash) {
+        const list = this.touch(path);
+        list.push({ startLine, endLine, hash, step: this.currentStep, hot: true });
+        while (list.length > MAX_RANGES_PER_PATH)
+            list.shift();
+    }
+    /**
+     * 查询重复读命中:存在 hot 条目,其行区间覆盖请求区间、hash 相同。
+     * 无命中返 null(调用方照常全量返回)。
+     */
+    findUnchanged(path, startLine, endLine, hash) {
+        const list = this.entries.get(path);
+        if (!list)
+            return null;
+        // 从新到旧找。
+        for (let i = list.length - 1; i >= 0; i--) {
+            const e = list[i];
+            if (e.hot && e.hash === hash && e.startLine <= startLine && e.endLine >= endLine) {
+                return { step: e.step, hash };
+            }
+        }
+        return null;
+    }
+}
+/** 每用户 turn 一个 scope。 */
+export function createReadDedup() {
+    return new ReadDedup();
+}

package/dist/tools/tool-runtime.js

@@ -292,6 +292,7 @@ export class ToolRuntime {
                         callId: opts?.callId,
                         allowedToolNames: opts?.allowedToolNames,
                         delegation: opts?.delegation,
+                        readDedup: opts?.readDedup,
                     });
                 }
                 finally {