mocode-ai 0.4.0 → 0.4.2

package/dist/session/compact.js

@@ -5,7 +5,8 @@ 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';
-/** 跨模块共享的上下文状态:agent 写 lastUsage,compact 写 lastEstimate,repl 的 /context 读。 */
+/** 跨模块共享的上下文状态:agent 写 lastUsage,compact 写 lastEstimate,repl 的 /context 读。
+ *  scheduler.ts 写最近一次调度日志(可选,repl 可读不到时 no-op)。 */
 export const contextState = {
     lastEstimate: 0,
 };
@@ -268,15 +269,83 @@ export async function compactHistory(history, opts) {
         summarized: false,
         estimateBefore,
         estimateAfter: estimateBefore,
-        reason: 'noop',
+        reason: 'noop-noold-noop',
+        protectedRatio: history.length > 0 ? kept.length / history.length : 0,
+        oldGroupCount: oldGroups.length,
     };
     if (oldGroups.length === 0) {
         // 没有旧区可压缩
+        const protectedRatio = history.length > 0 ? kept.length / history.length : 0;
+        if (opts.force && history.length > 2) {
+            // 真·强制压:把降 keepBudget 当 old group 强行创建一组可压区
+            // 取最早的 user/assistant/tool 当 old,后一段当 kept
+            const mid = Math.max(1, Math.floor(history.length / 2));
+            const older = history.slice(1, mid);
+            const keptAfter = history.slice(mid);
+            // 走仅微压缩(LLM 可能不可用,不强行 summarize)
+            let microcompactDone2 = false;
+            for (const m of older) {
+                const c = m.content;
+                if (typeof c === 'string' && c.length > MAX_OLD_TOOL_STUB) {
+                    m.content = truncateMid(c, MAX_OLD_TOOL_STUB);
+                    microcompactDone2 = true;
+                }
+                const as = m;
+                if (as.role === 'assistant') {
+                    if (typeof as.content === 'string' && as.content.length > MAX_OLD_TOOL_STUB) {
+                        as.content = truncateMid(as.content, MAX_OLD_TOOL_STUB);
+                        microcompactDone2 = true;
+                    }
+                    if (Array.isArray(as.tool_calls)) {
+                        for (const tc of as.tool_calls) {
+                            const args = tc?.function?.arguments;
+                            if (typeof args !== 'string' || args.length <= MAX_OLD_TOOL_STUB)
+                                continue;
+                            const stubbed = stubToolCallArguments(args);
+                            if (stubbed !== args) {
+                                tc.function.arguments = stubbed;
+                                microcompactDone2 = true;
+                            }
+                        }
+                    }
+                }
+            }
+            const summaryMsg = {
+                role: 'system',
+                content: older.length > 0
+                    ? `# 会话摘要(force)\n被跳过的早期对话 ${older.length} 条已微压缩(token 数减少)。`
+                    : `# 会话摘要(force)\n无内容。`,
+            };
+            const rebuilt = [history[0], summaryMsg, ...keptAfter];
+            history.length = 0;
+            history.push(...rebuilt);
+            pruneAfterCompaction(history);
+            const estimateAfter = estimateMessagesTokens(history) + schemaTokens;
+            contextState.lastEstimate = estimateAfter;
+            contextState.lastUsage = undefined;
+            layout.contentWrite(`  ${ui.brightMagenta}●${ui.reset} ${ui.cyan}强制压缩(focus on early history)${ui.reset}  ${ui.dim}${estimateBefore} → ${estimateAfter} tokens${ui.reset}\n`);
+            return {
+                compacted: true,
+                summarized: false,
+                estimateBefore,
+                estimateAfter,
+                reason: microcompactDone2 ? 'microcompact' : 'summarize',
+                protectedRatio,
+                oldGroupCount: 0,
+            };
+        }
+        // 细分 noop 类型,供 repl 文案
+        const isEmpty = history.length <= 1; // 只有 system 提示
+        if (isEmpty) {
+            // 整段 history 太短,没有可压内容
+            return { ...noop, reason: 'noop-empty', protectedRatio };
+        }
+        // history 有内容但全在保护区(系统 + 当前轮)
         if (estimateBefore >= opts.threshold * opts.window) {
-            layout.contentWrite(`  ${ui.yellow}●${ui.reset} ${ui.yellow}上下文已超阈但无可压缩项,建议 /clear 或缩短输入。${ui.reset}\n`);
-            return { ...noop, reason: 'too-large' };
+            layout.contentWrite(`  ${ui.yellow}●${ui.reset} ${ui.yellow}上下文已超阈但无可压缩项(全在保护区),建议 /clear 或缩短输入。${ui.reset}\n`);
+            return { ...noop, reason: 'noop-shrunk-too-large', protectedRatio };
         }
-        return noop;
+        return { ...noop, reason: 'noop-protected', protectedRatio };
     }
     // 第一层:微压缩——旧区原地截短(保 tool_call_id,无 LLM 调用)
     // 覆盖三类大字段,均只裁模型/工具产物,不动 user 原话与 system(摘要):
@@ -365,24 +434,63 @@ export async function compactHistory(history, opts) {
             estimateBefore,
             estimateAfter,
             reason: 'microcompact',
+            protectedRatio: history.length > 0 ? kept.length / history.length : 0,
+            oldGroupCount: oldGroups.length,
         };
     }
-    return noop;
+    // 摘要失败 + 无超大单条可微压 = 真 noop
+    return {
+        ...noop,
+        reason: 'noop-ml-only',
+        protectedRatio: history.length > 0 ? kept.length / history.length : 0,
+        oldGroupCount: oldGroups.length,
+    };
 }
 /**
  * 自动压缩门槛:agent 每步调 chat() 前调用。
  * 用全量启发式估算(始终可用、安全侧、无 stale-usage 问题);超阈则压缩。
+ *
+ * 升级到 Budget Scheduler:可传 `report: BudgetReport`。传了就**按 ROI 调度**:
+ *   - 只有当 `report.layers.history.overBudget` 或 `report.totalOver` 时才压;
+ *   - 冷工具超(Cold Tool ROI 最低)→ 不压 history,留给调度器的 cold tools 路径处理。
+ * 这样 cold tools 路径(L1 中截 / L2 relevance / L3 age stub)能先动,history
+ * 摘要(最贵)只在 cold tools 解不开时才触发。
+ *
+ * 不传 report 时退化为原行为:仅看总占用是否超 `compactThreshold * window`——
+ * 兼容老调用方(子 agent / 测试直接调时),零行为变化。
+ *
+ * manual 选项(repl /compact 用):true 时旁路 autoCompact 开关与 ROI 阈,
+ * 强制走 compactHistory(manual/force 参数透传)。返 CompactResult 给 caller 文案展示。
+ * 默认 manual=false 自动路径完全不变。
  */
-export async function maybeCompact(history) {
+export async function maybeCompact(history, report, manualOpts) {
     const schemaTokens = estimateToolSchemaTokens();
     const est = estimateMessagesTokens(history) + schemaTokens;
     contextState.lastEstimate = est;
-    if (!config.autoCompact)
-        return;
-    if (est < config.compactThreshold * config.contextWindowTokens)
-        return;
-    await compactHistory(history, {
+    const isManual = manualOpts?.manual === true;
+    // 手动路径:旁路 autoCompact / report / 总阈三重门
+    if (!isManual) {
+        if (!config.autoCompact)
+            return;
+        if (report) {
+            // 调度模式:只压 history 层超或兜底总超
+            const needsCompact = report.layers.history.overBudget || report.totalOver;
+            if (!needsCompact)
+                return;
+        }
+        else {
+            // 老路径:总占用超阈才压
+            if (est < config.compactThreshold * config.contextWindowTokens)
+                return;
+        }
+    }
+    const r = await compactHistory(history, {
         window: config.contextWindowTokens,
         threshold: config.compactThreshold,
+        focus: manualOpts?.focus,
+        manual: isManual,
+        force: manualOpts?.force,
     });
+    if (isManual)
+        return r;
 }

package/dist/session/index.js

@@ -5,5 +5,10 @@
  * 依赖方向:session → {llm(摘要复用 chat), config, ui};llm 不反向依赖 session。
  */
 export { compactHistory, maybeCompact, capToolResultForHistory, truncateMid, contextState, } from './compact.js';
+// ── Context Budget Scheduler 接缝 ────────────────────────────────────────
+// agent/core.ts 步前调 runScheduler(history, step):评估五区预算 → 按 ROI 调度
+// shrink_cold_tools / cap_hot_tools / compact_history。开关关闭时退化为 maybeCompact。
+// repl /compact 命令调 manualCompact(history, focus?):与自动路径完全一致,focus 透传摘要 prompt。
+export { runScheduler, manualCompact, createBudgetScheduler, } from './scheduler.js';
 export { dropContextFromHistory, formatDropResult, } from './drop.js';
 export { newSessionId, saveSession, loadSession, listSessions, sessionDir, } from './persist.js';

package/dist/session/scheduler.js

@@ -0,0 +1,172 @@
+// Context Budget Scheduler(执行层):把 scheduleActions() 产生的动作落到既有闸上。
+//
+// 关系图:
+//
+//   agent/core.ts (步前)              repl /compact 命令(手动)
+//     ↓ runScheduler(history, step)    ↓ manualCompact(history, focus?)
+//   session/scheduler.ts(本文件)
+//     ├─ evaluateBudget(history, window, step) → BudgetReport
+//     │     ↓
+//     ├─ scheduleActions(report) → ScheduleAction[]
+//     │     ↓
+//     └─ 执行 actions:
+//          - warn:                  仅写日志
+//          - shrink_cold_tools L1:  由 push-time cap.ts(MAX_HISTORY_RESULT)自动处理;此处 no-op
+//          - shrink_cold_tools L2:  由 pruner.observePush(relevance.ts)自动处理;此处 no-op
+//          - shrink_cold_tools L3:  由 lifecycle.pushTool(lifecycle.ts)自动处理;此处 no-op
+//          - cap_hot_tools:         Hot 区只 cap,实际仍由 push-time cap 走;此处 no-op + 记日志
+//          - compact_history:       调 maybeCompact(history, report)── report 路由到 ROI 调度
+//
+// 设计意图:
+//   - **L1/L2/L3 不重复实现**——push-time 已经自动跑过这三级。再在调度器做一遍是 Double-Action
+//     且破坏「调度器永不抛错 + 幂等」契约。调度器只负责"决策时点",push-time 闸负责"执行"。
+//   - **hotBoundary** 仍由调度器算出来供 lifecycle 内部用(将来可演进成「仅 Cold 区跑 age stub」)——
+//     现版本先全面暴露给 report,暂不传参给 lifecycle。
+//   - **actionLog**:每次执行的决策落进 contextState.schedulerLog,供 /context 命令与调试用。
+//   - **manualCompact**:手动入口(用户敲 /compact),与 runScheduler 共享决策路径;唯一差别是
+//     即使 history 不超预算也强制产 compact_history(focus 透传)。对齐用户拍板的方案 A。
+//
+// 开关:
+//   - config.contextBudget !== false(默认 true):agent 调 runScheduler
+//   - 关时 agent 仍走原 maybeCompact(history)无 report 路径,零行为变化
+//   - 手动 /compact 走 manualCompact;关时退化直接调 compactHistory(history, { focus })
+import { evaluateBudget, scheduleActions, formatReport, } from '../context/budget.js';
+import { config } from '../config/index.js';
+import { maybeCompact, contextState } from './compact.js';
+import * as layout from '../ui/layout.js';
+import { ui } from '../ui/theme.js';
+/** 创建 runAgentCore 闭包持有的 scheduler(每次 agent 启动一个新实例)。
+ *  observePush 当前只是占位:真正 L1/L2/L3 已由 cap / pruner / lifecycle 在 push 时跑;
+ *  保留接口为后续「调度器注入 hotBoundary 给 lifecycle」演进留接缝。 */
+export function createBudgetScheduler() {
+    const obs = {
+        lastRunLog: null,
+        observePush(_history, _idx) {
+            // 占位:push-time 三闸(cap / pruner / lifecycle)已自动跑;此接缝供将来演进。
+        },
+        async runStep(history, step) {
+            const report = evaluateBudget(history, config.contextWindowTokens, step);
+            const actions = scheduleActions(report);
+            let compactHistoryCalled = false;
+            for (const a of actions) {
+                if (a.kind === 'warn') {
+                    // system 超:写一行提示(配置漂移应由用户处理,不是调度器压)
+                    layout.contentWrite(`  ${ui.yellow}●${ui.reset} ${ui.yellow}调度器警告:${a.layer} ${a.reason}${ui.reset}\n`);
+                }
+                else if (a.kind === 'compact_history') {
+                    // 路由到 maybeCompact(history, report)——按 ROI 调度(只有 history 超 / totalOver 才真压)
+                    await maybeCompact(history, report);
+                    compactHistoryCalled = true;
+                }
+                // shrink_cold_tools L1/L2/L3 与 cap_hot_tools:已由 push-time 闸在每次 push 自动跑
+                // (cap = MAX_HISTORY_RESULT;pruner = same-path 新旧替换;lifecycle = age stub)。
+                // 调度器不重复,只把决策记录下来供调试。
+            }
+            const log = {
+                step,
+                report,
+                actions,
+                compactHistoryCalled,
+                ts: Date.now(),
+            };
+            obs.lastRunLog = log;
+            // 暴露给 /context 共享读(repl / context 命令)
+            contextState.schedulerLog = log;
+        },
+    };
+    return obs;
+}
+/** 便捷:agent/core.ts 不需要每次 createBudgetScheduler,直接 runScheduler(history, step)。 */
+export async function runScheduler(history, step) {
+    const s = createBudgetScheduler();
+    await s.runStep(history, step);
+}
+/** 手动 /compact 入口(repl):与自动路径完全一致——五区 ROI 调度,但 history 摘要强制执行。
+ *  即便 layers.history.overBudget=false 或 totalOver=false,manual 仍产 compact_history action
+ *  把 focus 透传给 LLM 摘要 prompt。其它 ROI 决策(cold tools / cap hot / warn)按 scheduleActions 走。
+ *
+ *  关系:runScheduler 是「自动触发」,manualCompact 是「用户显式触发」,二者共享 scheduleActions。
+ *
+ *  force=true:即便 oldGroups 空(history 全在保护区)也强行把早期消息降级压一次。
+ *  适合"history 太长,自动阈值从未触发,但用户想强制压"的场景。
+ *
+ *  退化:config.contextBudget === false 时直接调 compactHistory(history, { focus }),与改造前等价。
+ *  返回 SchedulerRunLog + compactDetail 字段,供 repl 文案展示"为什么没压"。 */
+export async function manualCompact(history, focus, opts) {
+    if (config.contextBudget === false) {
+        // 退化:不经调度器,直压 history(等价于改造前,但带 manual/force 透传)
+        const r = await import('./compact.js').then(({ compactHistory }) => compactHistory(history, {
+            window: config.contextWindowTokens,
+            threshold: config.compactThreshold,
+            focus,
+            manual: true,
+            force: opts?.force,
+        }));
+        return {
+            step: -1,
+            report: evaluateBudget(history, config.contextWindowTokens, -1),
+            actions: [{ kind: 'compact_history', focus }],
+            compactHistoryCalled: true,
+            ts: Date.now(),
+            compactDetail: {
+                reason: r.reason,
+                estimateBefore: r.estimateBefore,
+                estimateAfter: r.estimateAfter,
+                protectedRatio: r.protectedRatio,
+                oldGroupCount: r.oldGroupCount,
+                focus,
+            },
+        };
+    }
+    const report = evaluateBudget(history, config.contextWindowTokens, -1);
+    let actions = scheduleActions(report);
+    // 用户显式说「要压」:即使 report 不含 history 触发,仍追加 compact_history
+    const hasCompact = actions.some(a => a.kind === 'compact_history');
+    if (!hasCompact) {
+        actions = [...actions, { kind: 'compact_history', focus }];
+    }
+    else if (focus) {
+        // 已有 compact_history(action 由 scheduleActions 产,无 focus)— 注入 focus
+        actions = actions.map(a => a.kind === 'compact_history' ? { ...a, focus } : a);
+    }
+    const s = createBudgetScheduler();
+    // 直接驱动 runStep 的执行逻辑(action list 我们已自己生成)
+    let compactHistoryCalled = false;
+    let compactDetail;
+    for (const a of actions) {
+        if (a.kind === 'warn') {
+            // 复用现有 contentWrite 路径(经 scheduler.runStep);这里略,只记录到 log
+        }
+        else if (a.kind === 'compact_history') {
+            const r = await maybeCompact(history, report, {
+                manual: true,
+                force: opts?.force,
+                focus: a.focus,
+            });
+            compactHistoryCalled = true;
+            if (r) {
+                compactDetail = {
+                    reason: r.reason,
+                    estimateBefore: r.estimateBefore,
+                    estimateAfter: r.estimateAfter,
+                    protectedRatio: r.protectedRatio,
+                    oldGroupCount: r.oldGroupCount,
+                    focus: a.focus,
+                };
+            }
+        }
+    }
+    const log = {
+        step: -1,
+        report,
+        actions,
+        compactHistoryCalled,
+        ts: Date.now(),
+        compactDetail,
+    };
+    s.lastRunLog = log;
+    contextState.schedulerLog = log;
+    return log;
+}
+// ── 调试导出:用于 scripts/check-budget.ts 把报告打到 stdout 调试 ────────
+export { evaluateBudget, scheduleActions, formatReport };

package/dist/tools/builtins/ask-human.js

@@ -1,5 +1,80 @@
 import { promptIntervention } from '../../ui/intervention.js';
 import { sendState } from '../../pet/bridge.js';
+/** 将单个选项元素安全地转为可读字符串。
+ *  LLM 有时会传对象(如 {name/label/title:"xxx", desc/description:"yyy"})而不是纯字符串,
+ *  直接 String(obj) 会变成 "[object Object]"——这里智能提取可读字段。 */
+function optionToString(o) {
+    if (o === null || o === undefined)
+        return '';
+    if (typeof o === 'string')
+        return o;
+    if (typeof o === 'number' || typeof o === 'boolean')
+        return String(o);
+    if (typeof o === 'object') {
+        const obj = o;
+        // 优先取常见的标签字段
+        const labelKeys = ['label', 'name', 'title', 'text', 'option', 'choice', 'value', 'key'];
+        for (const k of labelKeys) {
+            const v = obj[k];
+            if (typeof v === 'string' && v.trim())
+                return v;
+        }
+        // 其次尝试 "label + description" 组合
+        const label = obj.label ?? obj.name ?? obj.title;
+        const desc = obj.description ?? obj.desc ?? obj.detail;
+        if (typeof label === 'string' && typeof desc === 'string') {
+            return `${label}: ${desc}`;
+        }
+        // 兜底:JSON 序列化(去掉大括号让它看起来不像代码)
+        try {
+            const s = JSON.stringify(obj);
+            // 如果是简单对象尝试美化
+            return s;
+        }
+        catch {
+            return String(o);
+        }
+    }
+    return String(o);
+}
+/** 公开以便 check-ask-human-options.ts 单元测试。 */
+export function coerceOptions(raw) {
+    // 路径 1:本身就是数组,map 成字符串。
+    if (Array.isArray(raw)) {
+        // 子路径 1a:LLM 把真数组包成字符串塞在单元素里(本次 bug 现场)
+        if (raw.length === 1 && typeof raw[0] === 'string') {
+            const t = raw[0].trim();
+            if (t.startsWith('[') && t.endsWith(']')) {
+                try {
+                    const parsed = JSON.parse(t);
+                    if (Array.isArray(parsed))
+                        return parsed.map(optionToString);
+                }
+                catch {
+                    // 不是合法 JSON 数组,降级原值
+                }
+            }
+        }
+        return raw.map(optionToString);
+    }
+    // 路径 2:LLM 直接把整个数组 stringify 成单字符串塞 options 字段(JSON.parse 出来是字符串)
+    // 例如 GLM 系经常这么做,arg h['options']='["A","B"]' → args.options='["A","B"]'
+    // 这里解开成真数组再转。
+    if (typeof raw === 'string') {
+        const t = raw.trim();
+        if (t.startsWith('[') && t.endsWith(']')) {
+            try {
+                const parsed = JSON.parse(t);
+                if (Array.isArray(parsed))
+                    return parsed.map(optionToString);
+            }
+            catch {
+                // 不是合法 JSON,保留为单元素数组(对应 input 模式)
+            }
+        }
+    }
+    return [];
+}
 // ---------- ask_human ----------
 export const askHumanTool = {
     name: 'ask_human',
@@ -30,9 +105,10 @@ export const askHumanTool = {
     },
     async execute(args) {
         const question = String(args.question ?? '');
-        const options = Array.isArray(args.options)
-            ? args.options.map((o) => String(o))
-            : [];
+        // 容错:部分 LLM(尤其 GLM 系)把数组/对象 stringify 后塞进来,这里识别「长得很像 JSON
+        // 数组的单字符串元素」并解开,避免菜单只剩一行 [object Object]、逼用户手动输入。
+        // 任何一步失败 / 解出非数组:降级 input,与原代码语义一致。
+        const options = coerceOptions(args.options);
         const context = args.context ? String(args.context) : undefined;
         // 桌宠:面板弹出期间广播 waiting_human(红灯闪烁,提示需要人工介入);拿到响应后 sendState 会被
         // 下一个 hook 事件(如 onToolDone→tool_call)覆盖,这里不用手动切回——与其它工具状态转移逻辑一致。

package/dist/tools/builtins/grep.js

@@ -5,19 +5,26 @@ import { getSandboxRoot, isInsideRoot, jailResolve } from '../../sandbox/index.j
 // ---------- grep ----------
 export const grepTool = {
     name: 'grep',
-    description: 'Search file contents by regex, returning file:line: matched lines. Recursively searches cwd excluding node_modules/.git. Optional glob restricts file types.' +
-        ' For architecture/call chains, prefer codegraph.',
+    description: 'Search file contents by regex (recursive, excludes node_modules/.git).\n' +
+        'Output: per-file header "<path>: N matches, lines [l1, l2, ...]" + first N matching lines.\n' +
+        'Use the line-number list to call read_file(offset=X, limit=Y) for each region — ' +
+        'do NOT read entire files after grepping. Prefer codegraph for call chains.',
     parameters: {
         type: 'object',
         properties: {
             pattern: { type: 'string', description: 'Regular expression' },
             glob: { type: 'string', description: 'Optional, restrict to a file glob, e.g. *.ts' },
+            max_per_file: {
+                type: 'integer',
+                description: 'Max body lines per file (default 15, cap 50). Line-number list is always full.',
+            },
         },
         required: ['pattern'],
     },
     async execute(args) {
         const pattern = String(args.pattern);
         const g = String(args.glob ?? '**/*');
+        const maxPerFile = Math.min(Math.max(Number(args.max_per_file ?? 15), 1), 50);
         let re;
         try {
             re = new RegExp(pattern);
@@ -34,11 +41,10 @@ export const grepTool = {
             followSymbolicLinks: false, // 不跟随软链目录,防经软链扫到牢外文件
             throwErrorOnBrokenSymbolicLink: false,
         })).filter((f) => isInsideRoot(f)); // 后置兜底:仅留牢内
-        const results = [];
+        const hits = [];
         let scanned = 0;
-        for (const f of files) {
-            if (results.length >= MAX_RESULTS)
-                break;
+        let truncated = false;
+        outer: for (const f of files) {
             let content;
             try {
                 // jailResolve:realpath 化,防「牢内文件软链→牢外」的内容泄露;越界/不可读均 catch 跳过
@@ -49,19 +55,50 @@ export const grepTool = {
             }
             scanned++;
             const lines = content.split(/\r?\n/);
+            const lineNos = [];
             for (let i = 0; i < lines.length; i++) {
-                if (re.test(lines[i])) {
-                    results.push(`${f}:${i + 1}: ${lines[i].trim()}`);
-                    if (results.length >= MAX_RESULTS)
-                        break;
+                if (re.test(lines[i]))
+                    lineNos.push(i + 1);
+            }
+            if (lineNos.length === 0)
+                continue;
+            // 全局配额:行号列表总是计入,body 行数也计入(行号 + body 两条共用 MAX_RESULTS)
+            const totalCost = lineNos.length + Math.min(lineNos.length, maxPerFile);
+            if (hits.length >= MAX_RESULTS || totalCost > MAX_RESULTS * 4) {
+                // 文件过多 / 配额爆:仅追加该文件行号列表,不再展开 body
+                if (hits.length < MAX_RESULTS) {
+                    hits.push({ path: f, lineNos, bodies: [] });
                 }
+                truncated = true;
+                continue;
             }
+            const bodies = lineNos.slice(0, maxPerFile).map((n) => {
+                const trimmed = lines[n - 1].trim();
+                return `  L${n}: ${trimmed}`;
+            });
+            hits.push({ path: f, lineNos, bodies });
         }
-        if (results.length === 0)
+        if (hits.length === 0)
             return `无匹配(扫描了 ${scanned} 个文件)`;
-        let out = results.join('\n');
-        if (results.length >= MAX_RESULTS)
-            out += `\n...(结果达到 ${MAX_RESULTS} 条上限)`;
-        return out;
+        const out = [];
+        let totalShown = 0;
+        for (const h of hits) {
+            const header = `${h.path}: ${h.lineNos.length} 处匹配,行号 [${h.lineNos.join(', ')}]`;
+            out.push(header);
+            if (h.bodies.length > 0) {
+                out.push(...h.bodies);
+            }
+            else {
+                out.push(`  (body 已折叠,见上方行号列表 → read_file 精读)`);
+            }
+            totalShown += h.lineNos.length + h.bodies.length;
+            if (totalShown >= MAX_RESULTS) {
+                out.push(`...(结果达到 ${MAX_RESULTS} 条上限)`);
+                break;
+            }
+        }
+        if (truncated)
+            out.push(`...(仍有更多匹配文件未展示,缩小 glob 或收窄正则)`);
+        return out.join('\n');
     },
 };

package/dist/tools/builtins/index.js

@@ -21,7 +21,26 @@ import { todolistTool } from './todolist.js';
 /**
  * 所有内置工具,按注册顺序排列。
  * 加新工具:在本目录新建 `xxx.ts` 导出一个 Tool,再在下面数组里加一行。无需改 agent / llm。
+ *
+ * 记忆子系统总开关(MEMORY_ENABLED !== 'true'):5 个 memory_* 工具整体不进 builtinTools,
+ * 进而不进 LLM 的工具表(模型根本看不到、也不会想着去调)。运行时通过 /memory_switch 切;
+ * 切换对当前会话的 tool list 不重算(取的是模块初始化时的快照),所以需要重启 REPL 才生效
+ * —— 这是有意为之,避免切开关瞬间把已发出请求的工具列表打乱。
+ *
+ * 注:这里直接读 env(MEMORY_ENABLED)而不是调 config.isMemoryEnabled(),因为本模块可能在
+ * config 单例尚未初始化时被其它模块拉起(import 链路:tools/registry → builtinTools,
+ * config 单例字段 getter 在 getPlanDisabledTools 等调用链路上 lazy 求值)。
  */
+const _memoryEnabledAtBoot = process.env.MEMORY_ENABLED === 'true';
+const _memoryTools = _memoryEnabledAtBoot
+    ? [
+        memorySaveTool,
+        memorySearchTool,
+        memoryListTool,
+        memoryUpdateTool,
+        memoryForgetTool,
+    ]
+    : [];
 export const builtinTools = [
     readFileTool,
     writeFileTool,
@@ -36,11 +55,7 @@ export const builtinTools = [
     askHumanTool,
     switchModeTool, // plan↔auto 自切(两模式都可见,不进 PLAN_DISABLED_TOOLS;副作用控制工具→串行分支)
     dropContextTool, // 运行中剔除无关 tool 结果(上下文管理,无副作用;两模式都可见,串行分支)
-    memorySaveTool,
-    memorySearchTool,
-    memoryListTool,
-    memoryUpdateTool,
-    memoryForgetTool,
+    ..._memoryTools,
     taskTool, // 派生子 agent(独立 history + 可受限工具集);plan 模式禁用(见 PLAN_DISABLED_TOOLS)
     todolistTool, // 工作记事本(plan 文件:复杂任务 checklist,落盘抗压缩);plan 模式可用(便于「先 plan 再 auto」时落地执行清单)
 ];

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

@@ -1,24 +1,34 @@
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { MAX_FILE_LINES } from '../constants.js';
+/** 默认单次 read_file 拉取的行数。刻意压低,逼 LLM 分块读大文件,
+ * 配合 description 中的 PAGINATION IS MANDATORY 引导。
+ * 300 行 ≈ 一个屏幕的源码量,够定位一段逻辑而不至于吃光上下文。 */
+const DEFAULT_READ_LIMIT = 300;
 // ---------- read_file ----------
 export const readFileTool = {
     name: 'read_file',
-    description: 'Read file content with line numbers. Read before editing. offset (1-based, default 1), limit (default 2000).' +
-        ' For architecture/call chains, prefer codegraph over reading files one at a time.',
+    description: 'Read file content with line numbers. Read before editing.\n' +
+        'For files >500 lines: grep first to locate regions, then call read_file multiple times ' +
+        'with offset+limit (e.g. offset=350, limit=120). Do NOT read an entire large file in one call.\n' +
+        'Prefer codegraph over reading files one at a time for architecture/call-chain questions.',
     parameters: {
         type: 'object',
         properties: {
             path: { type: 'string', description: 'File path, relative to the working directory' },
-            offset: { type: 'integer', description: 'Start line (1-based), default 1' },
-            limit: { type: 'integer', description: 'Max number of lines to read, default 2000' },
+            offset: { type: 'integer', description: 'Start line, 1-based (default 1).' },
+            limit: {
+                type: 'integer',
+                description: 'Max lines to read (default 300, hard cap 2000). Keep ranges ~80-200.',
+            },
         },
         required: ['path'],
     },
     async execute(args) {
         const path = String(args.path);
         const offset = Number(args.offset ?? 1);
-        const limit = Number(args.limit ?? MAX_FILE_LINES);
+        // 无论 LLM 传多大,单次硬钳到 MAX_FILE_LINES,杜绝「绕过分页引导一把全拿」。
+        const limit = Math.min(Number(args.limit ?? DEFAULT_READ_LIMIT), MAX_FILE_LINES);
         const data = await readFile(resolve(path), 'utf8');
         const lines = data.split(/\r?\n/);
         const start = Math.max(0, offset - 1);