minimal-agent 0.1.9 → 0.3.0

package/src/tools/grep/grep.js

@@ -0,0 +1,185 @@
+/**
+ * ============================================================
+ *  src/tools/grep.ts —— Grep 工具（基于 ripgrep 的内容搜索）
+ * ------------------------------------------------------------
+ *  对应 kakadeai 主仓库的 GrepTool。
+ *  实现策略：spawn 系统 `rg` 命令。
+ *  没装 ripgrep 时给"教学型"错误：
+ *    - macOS: brew install ripgrep
+ *    - Windows: scoop install ripgrep
+ *    - Ubuntu: sudo apt install ripgrep
+ *
+ *  为何不用纯 Node 实现？
+ *    递归遍历 + 正则 + glob 排除 + 字符编码处理 = 几百行；
+ *    最小化原则下复用 rg 子进程更划算。
+ * ============================================================
+ */
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import { resolveRgPath } from './rgPath.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+// ---------------- 1. Zod 输入 schema ----------------
+const inputSchema = z.object({
+    pattern: z.string().min(1).describe('正则表达式（ripgrep 兼容语法）'),
+    path: z
+        .string()
+        .optional()
+        .describe('搜索的根目录或文件（默认当前工作目录）'),
+    glob: z
+        .string()
+        .optional()
+        .describe('文件名 glob 过滤，如 "*.ts"'),
+    type: z
+        .string()
+        .optional()
+        .describe('rg 的文件类型快捷名，如 "py"、"rust"、"js"'),
+    output_mode: z
+        .enum(['content', 'files_with_matches', 'count'])
+        .optional()
+        .describe('输出模式：content=匹配行；files_with_matches=只列文件；count=每文件计数'),
+    '-i': z.boolean().optional().describe('忽略大小写'),
+    '-n': z.boolean().optional().describe('显示行号（仅 content 模式）'),
+    '-A': z.number().int().min(0).optional().describe('匹配后展示几行上下文'),
+    '-B': z.number().int().min(0).optional().describe('匹配前展示几行上下文'),
+    '-C': z.number().int().min(0).optional().describe('匹配前后各展示几行（覆盖 -A/-B）'),
+    head_limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('输出最多保留前 N 行（防止结果过大）'),
+});
+// ---------------- 2. JSON Schema（由 Zod 自动派生） ----------------
+const parameters = toToolParameters(inputSchema);
+// ---------------- 3. Description（搬自 kakadeai/tools/GrepTool/prompt.ts） ----------------
+const description = `A powerful search tool built on ripgrep.
+
+Usage:
+- ALWAYS use Grep for content search tasks. Do NOT invoke \`grep\` or \`rg\` directly via Bash.
+- Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
+- Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
+- Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts
+- Pattern syntax: Uses ripgrep (not classic grep)`;
+// ---------------- 4. call() ----------------
+async function call(input, signal) {
+    const args = [];
+    // 输出模式（默认 files_with_matches）
+    const mode = input.output_mode ?? 'files_with_matches';
+    if (mode === 'files_with_matches')
+        args.push('-l');
+    else if (mode === 'count')
+        args.push('--count-matches');
+    // mode === 'content' 是 rg 默认行为，不加 flag
+    if (input['-i'])
+        args.push('-i');
+    if (mode === 'content' && input['-n'])
+        args.push('-n');
+    // 上下文行数：-C 优先，否则各加 -A/-B
+    if (typeof input['-C'] === 'number') {
+        args.push('-C', String(input['-C']));
+    }
+    else {
+        if (typeof input['-A'] === 'number')
+            args.push('-A', String(input['-A']));
+        if (typeof input['-B'] === 'number')
+            args.push('-B', String(input['-B']));
+    }
+    if (input.glob)
+        args.push('--glob', input.glob);
+    if (input.type)
+        args.push('--type', input.type);
+    // 安全：限制单文件输出大小（防止超大行）
+    args.push('--max-columns', '500');
+    args.push('--max-columns-preview');
+    // 按修改时间降序排列（新文件/新匹配在前，与 Glob 的旧在前形成互补锁定模板）
+    args.push('--sort', 'modified');
+    // pattern 必须用 -e 显式标记，否则以 - 开头的 pattern 会被当成 flag
+    args.push('-e', input.pattern);
+    // 搜索路径
+    args.push(input.path ? resolve(input.path) : '.');
+    // ---- 找 rg ----
+    // 优先级：MINIMAL_AGENT_RIPGREP_PATH → 系统 PATH → Claude Code 自带的 rg
+    const rgPath = await resolveRgPath();
+    if (!rgPath) {
+        return {
+            ok: false,
+            error: '找不到 ripgrep（rg）。可以三选一：\n' +
+                '  ① 装 Claude Code（自带 rg）：npm i -g @anthropic-ai/claude-code\n' +
+                '  ② 系统装 ripgrep：\n' +
+                '     macOS:   brew install ripgrep\n' +
+                '     Windows: scoop install ripgrep\n' +
+                '     Ubuntu:  sudo apt install ripgrep\n' +
+                '  ③ 在 .env 设置 MINIMAL_AGENT_RIPGREP_PATH=/绝对/路径/到/rg',
+        };
+    }
+    // ---- spawn rg ----
+    let stdout = '';
+    let stderr = '';
+    let exitCode = null;
+    try {
+        await new Promise((resolveP, rejectP) => {
+            const child = spawn(rgPath, args, {
+                cwd: getWorkingDir(),
+                signal,
+                windowsHide: true,
+            });
+            child.stdout.setEncoding('utf8');
+            child.stderr.setEncoding('utf8');
+            child.stdout.on('data', (chunk) => (stdout += chunk));
+            child.stderr.on('data', (chunk) => (stderr += chunk));
+            child.on('error', (e) => rejectP(e));
+            child.on('close', (code) => {
+                exitCode = code;
+                resolveP();
+            });
+        });
+    }
+    catch (e) {
+        const err = e;
+        return { ok: false, error: `执行 rg 失败（${rgPath}）：${err.message}` };
+    }
+    // rg 的退出码语义：
+    //   0 = 找到匹配
+    //   1 = 没找到匹配（不算错）
+    //   2 = 真正的错误
+    if (exitCode === 1) {
+        return { ok: true, content: `(no matches for pattern: ${input.pattern})` };
+    }
+    if (exitCode !== 0) {
+        return {
+            ok: false,
+            error: `rg 退出码 ${exitCode}：${stderr.slice(0, 500) || '(无 stderr)'}`,
+        };
+    }
+    // ---- head_limit + 大小兜底 ----
+    let content = stdout;
+    if (input.head_limit && input.head_limit > 0) {
+        const lines = content.split('\n');
+        if (lines.length > input.head_limit) {
+            content =
+                lines.slice(0, input.head_limit).join('\n') +
+                    `\n... (已截断到 ${input.head_limit} 行 / 共 ${lines.length} 行，保留最新匹配)`;
+        }
+    }
+    // 超长截断：保留头部（最新结果），丢弃尾部（旧结果）
+    if (content.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
+        content =
+            content.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) +
+                `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断尾部旧结果)`;
+    }
+    return { ok: true, content };
+}
+// ---------------- 5. 导出 ----------------
+export const grepTool = {
+    name: 'Grep',
+    description,
+    inputSchema,
+    parameters,
+    isReadOnly: true,
+    isConcurrencySafe: true,
+    maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+    call,
+};

package/src/tools/grep/rgPath.js

@@ -0,0 +1,173 @@
+/**
+ * ============================================================
+ *  src/tools/rgPath.ts —— 解析 ripgrep 可执行文件路径
+ * ------------------------------------------------------------
+ *  策略（按优先级）：
+ *    ① MINIMAL_AGENT_RIPGREP_PATH 环境变量（手动指定，调试时最高优先）
+ *    ② 项目自带的 vendored rg —— vendor/ripgrep/<arch>-<platform>/rg(.exe)
+ *       这是默认路径！开箱即用，不依赖系统装没装。
+ *    ③ 系统 PATH 上的 rg (用户自己装的 brew/scoop/apt 版本)
+ *    ④ Claude Code 全局 npm 包自带的 rg（兜底）
+ *
+ *  借鉴：kakadeai/utils/ripgrep.ts 的 getRipgrepConfig，但砍掉了：
+ *    - 嵌入式 Bun 模式（我们不用 bun build 打包）
+ *    - 单线程 EAGAIN 重试（最小化版用不到）
+ *
+ *  vendor/ripgrep 6 个平台二进制（arm64/x64 × win32/darwin/linux）从
+ *  Claude Code 自带的同一份原料复制而来，许可证 MIT/Unlicense，可自由分发。
+ *  macOS 上首次跑可能需要 codesign（见 codesignIfNeeded 注释）。
+ *
+ *  用法：
+ *    const rg = await resolveRgPath();
+ *    if (!rg) → 返回友好错误
+ *    spawn(rg, args)
+ * ============================================================
+ */
+import { spawn } from 'node:child_process';
+import { chmodSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { findPackageRoot } from '../../utils/packageRoot.js';
+let cached;
+/**
+ * 解析一次 rg 路径，结果缓存（同一进程内复用）。
+ * 返回 null 表示找不到。
+ */
+export async function resolveRgPath() {
+    if (cached !== undefined)
+        return cached;
+    cached = await detect();
+    return cached;
+}
+/** 仅供测试重置缓存 */
+export function _resetRgCache() {
+    cached = undefined;
+}
+async function detect() {
+    // ① 显式 env 覆盖
+    const fromEnv = process.env.MINIMAL_AGENT_RIPGREP_PATH;
+    if (fromEnv && existsSync(fromEnv))
+        return fromEnv;
+    // ② 项目自带的 vendored rg（默认路径！开箱即用）
+    const vendored = vendoredRgPath();
+    if (vendored && existsSync(vendored)) {
+        ensureExecutable(vendored);
+        return vendored;
+    }
+    // ③ PATH 上的 rg —— 直接试 spawn rg --version
+    if (await trySpawn('rg'))
+        return 'rg';
+    // ④ Claude Code 全局 npm 包自带的 rg
+    for (const candidate of claudeCodeCandidates()) {
+        if (existsSync(candidate)) {
+            ensureExecutable(candidate);
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * 项目内 vendor 路径：vendor/ripgrep/<arch>-<platform>/rg(.exe)
+ * 路径以本文件为锚点向上找，不依赖 cwd（用户在任何目录跑 minimal-agent 都行）。
+ */
+function vendoredRgPath() {
+    try {
+        const projectRoot = findPackageRoot(import.meta.url);
+        return resolve(projectRoot, 'vendor', 'ripgrep', subdir(), exeName());
+    }
+    catch {
+        return null;
+    }
+}
+function subdir() {
+    return `${process.arch}-${process.platform}`;
+}
+function exeName() {
+    return process.platform === 'win32' ? 'rg.exe' : 'rg';
+}
+/**
+ * Unix 上 git/tarball/cp 偶尔会丢可执行位。Windows 不需要。
+ * 失败也忽略（最坏情况下后面 spawn 会报权限错，给出明确信号）。
+ */
+function ensureExecutable(path) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        chmodSync(path, 0o755);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * 试着 spawn 一下，看 --version 能不能跑通。
+ * 注意：直接传 'rg'（不是绝对路径）让 OS 解析 PATH，
+ * 在 Windows 上配合 NoDefaultCurrentDirectoryInExePath 防 PATH 劫持。
+ */
+function trySpawn(cmd) {
+    return new Promise((resolveP) => {
+        let settled = false;
+        const done = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            resolveP(ok);
+        };
+        try {
+            const child = spawn(cmd, ['--version'], {
+                stdio: ['ignore', 'pipe', 'ignore'],
+                windowsHide: true,
+            });
+            let stdout = '';
+            child.stdout.setEncoding('utf8');
+            child.stdout.on('data', (c) => (stdout += c));
+            child.on('error', () => done(false));
+            child.on('close', (code) => done(code === 0 && stdout.startsWith('ripgrep ')));
+            // 兜底超时：5 秒
+            setTimeout(() => {
+                try {
+                    child.kill();
+                }
+                catch { }
+                done(false);
+            }, 5_000);
+        }
+        catch {
+            done(false);
+        }
+    });
+}
+/**
+ * 枚举 Claude Code 自带 rg 在常见安装路径下的位置。
+ * 不存在的路径不会被实际访问 —— 调用方用 existsSync 过滤。
+ */
+function claudeCodeCandidates() {
+    const arch = process.arch; // 'x64' | 'arm64' | ...
+    const platform = process.platform; // 'win32' | 'darwin' | 'linux' | ...
+    const subdir = `${arch}-${platform}`;
+    const exe = platform === 'win32' ? 'rg.exe' : 'rg';
+    // 各种 npm global 安装路径
+    const npmRoots = [];
+    if (platform === 'win32') {
+        // npm 默认 prefix: %APPDATA%/npm
+        if (process.env.APPDATA) {
+            npmRoots.push(resolve(process.env.APPDATA, 'npm', 'node_modules'));
+        }
+        // 也试试 user profile/AppData/Roaming（Bash on Windows 偶尔 APPDATA 没设）
+        if (process.env.USERPROFILE) {
+            npmRoots.push(resolve(process.env.USERPROFILE, 'AppData', 'Roaming', 'npm', 'node_modules'));
+        }
+    }
+    else {
+        // Unix：常见的 npm global prefix
+        const home = process.env.HOME ?? '';
+        if (home) {
+            npmRoots.push(resolve(home, '.npm-global', 'lib', 'node_modules'));
+            npmRoots.push(resolve(home, '.npm', 'lib', 'node_modules'));
+            npmRoots.push(resolve(home, 'node_modules'));
+        }
+        npmRoots.push('/usr/local/lib/node_modules');
+        npmRoots.push('/usr/lib/node_modules');
+        npmRoots.push('/opt/homebrew/lib/node_modules');
+    }
+    return npmRoots.map((root) => resolve(root, '@anthropic-ai', 'claude-code', 'vendor', 'ripgrep', subdir, exe));
+}

package/src/tools/index.js

@@ -0,0 +1,94 @@
+/**
+ * ============================================================
+ *  src/tools/index.ts —— 工具注册表 + 执行入口
+ * ------------------------------------------------------------
+ *  这里做两件事：
+ *    1. 把所有工具集中起来导出一个 ALL_TOOLS 数组（loop.ts 会用）
+ *    2. 实现 executeTool(name, rawArgs)：
+ *         a. 按 name 查表
+ *         b. 用 Zod safeParse 校验 arguments（LLM 给的是 JSON 字符串！）
+ *         c. 调用 tool.call()，统一包装错误
+ *
+ *  这层是"防线"：模型给的参数永远不可信，必须 Zod 校验后才进 call()。
+ * ============================================================
+ */
+import { bashTool } from './bash/bash.js';
+import { editTool } from './edit/edit.js';
+import { multiEditTool } from './edit/multi-edit.js';
+import { globTool } from './glob/glob.js';
+import { grepTool } from './grep/grep.js';
+import { readTool } from './read/read.js';
+import { webfetchTool } from './webfetch/webfetch.js';
+import { webbrowserTool } from './webbrowser/webbrowser.js';
+import { webSearchTool } from './websearch/websearch.js';
+import { writeTool } from './write/write.js';
+/** 所有内置工具（顺序 = 给 LLM 呈现的顺序，不影响代码执行，但会影响模型的优先级直觉） */
+export const ALL_TOOLS = [
+    readTool,
+    editTool,
+    multiEditTool,
+    writeTool,
+    globTool,
+    grepTool,
+    webSearchTool,
+    webfetchTool,
+    webbrowserTool,
+    bashTool,
+];
+/** 按名字查表 */
+export function getToolByName(name) {
+    return ALL_TOOLS.find((t) => t.name === name);
+}
+/**
+ * 执行一次工具调用。
+ *
+ * @param name        工具名（来自 LLM 的 tool_call.function.name）
+ * @param rawArguments LLM 给的参数 —— 注意这是 JSON 字符串，不是对象
+ * @param signal      支持中断
+ *
+ * 返回 ToolResult：失败时不抛异常，把 error 写在结果里（便于把"工具失败"
+ * 当成普通 tool_result 喂回 LLM，让模型自己重试或换思路）。
+ */
+export async function executeTool(name, rawArguments, signal) {
+    // 1. 找工具
+    const tool = getToolByName(name);
+    if (!tool) {
+        const available = ALL_TOOLS.map((t) => t.name).join(', ');
+        return { ok: false, error: `未知工具 "${name}"。可用工具：${available}` };
+    }
+    // 2. 解析 JSON
+    let parsedJson;
+    try {
+        parsedJson = rawArguments.length === 0 ? {} : JSON.parse(rawArguments);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: `工具参数不是合法 JSON：${e.message}\n收到的字符串：${rawArguments.slice(0, 200)}`,
+        };
+    }
+    // 3. Zod 校验
+    const checked = tool.inputSchema.safeParse(parsedJson);
+    if (!checked.success) {
+        const issues = checked.error.issues
+            .map((i) => `  - ${i.path.join('.') || '<root>'}: ${i.message}`)
+            .join('\n');
+        return {
+            ok: false,
+            error: `参数校验失败（请检查参数名/类型）：\n${issues}`,
+        };
+    }
+    // 4. 调用 call()，捕获意外异常
+    try {
+        return await tool.call(checked.data, signal);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: `工具执行抛出异常：${e.message}`,
+        };
+    }
+}
+// 导出每个工具，方便测试单独 import
+export { readTool, editTool, writeTool, globTool, grepTool, webSearchTool, webfetchTool, webbrowserTool, bashTool };
+export { multiEditTool } from './edit/multi-edit.js';

package/src/tools/read/read.js

@@ -0,0 +1,209 @@
+/**
+ * ============================================================
+ *  src/tools/read.ts —— Read 工具（读文件）
+ * ------------------------------------------------------------
+ *  对应 kakadeai 主仓库的 FileReadTool。
+ *  prompt 文本和 Zod schema 与 kakadeai 一致，让"模型可见接口"完全对齐；
+ *  call() 实现用最简单的 fs/promises，剥离了 UI/权限/PDF/Notebook/图片支持。
+ *
+ *  输入：
+ *    file_path  必填，绝对路径（建议）或相对项目根
+ *    offset     可选，1-indexed 起始行号
+ *    limit      可选，最大读多少行（默认 2000）
+ *
+ *  输出：
+ *    带行号前缀的文本（格式："${line}\t${content}"），与 Read 工具的 prompt 约定一致
+ * ============================================================
+ */
+import { createReadStream } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { z } from 'zod';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS, MAX_FILE_SIZE_BYTES, MAX_LINES_TO_READ } from '../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { hasBinaryExtension, isBlockedDevicePath, resolveToolPath } from '../shared/fileUtils.js';
+import { filePathField } from '../shared/schemas.js';
+import { recordRead } from '../shared/fileState.js';
+// ---------------- 1. Zod 输入 schema ----------------
+const inputSchema = z.object({
+    file_path: filePathField('读取'),
+    offset: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('起始行号（1-indexed）；不填则从文件开头读'),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe(`最多读多少行；不填则用默认值 ${MAX_LINES_TO_READ}`),
+});
+// ---------------- 2. JSON Schema（给 LLM 看） ----------------
+//
+// 与上面的 Zod schema 保持一致；改动时两边都要改。
+// ---------------- 2. JSON Schema（由 Zod 自动派生） ----------------
+const parameters = toToolParameters(inputSchema);
+// ---------------- 3. Description（给 LLM 看的工具说明） ----------------
+//
+// 这段文本直接搬自 kakadeai/tools/FileReadTool/prompt.ts 的 DESCRIPTION，
+// 只是去掉了和 PDF/Notebook/图片相关的能力描述（最小版不支持）。
+const description = `Reads a file from the local filesystem. You can access any file directly by using this tool.
+Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- The file_path parameter is preferably an absolute path. Relative paths are accepted and will be resolved against the agent's working directory (locked at startup via \`-d <dir>\` or process cwd).
+- By default, it reads up to ${MAX_LINES_TO_READ} lines starting from the beginning of the file
+- You can optionally specify a line offset and limit (especially handy for long files)
+- Results are returned using cat -n format, with line numbers starting at 1
+- This tool can only read text files, not directories. To read a directory, use the Glob tool.
+- If you read a file that exists but has empty contents you will receive a warning in place of file contents.
+- 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;
+async function call(input) {
+    const offset = input.offset ?? 1;
+    const limit = input.limit ?? MAX_LINES_TO_READ;
+    // 4a. 路径规范化 + 安全校验（替换原来的手动 resolve + validatePath）
+    const pathResult = resolveToolPath(input.file_path);
+    if (!pathResult.ok)
+        return pathResult;
+    const filePath = pathResult.resolvedPath;
+    // 4b. 设备文件双重拦截（虽然 validateAndResolvePath 已包含，但双重保险）
+    if (isBlockedDevicePath(filePath)) {
+        return { ok: false, error: `不允许读取设备文件：${filePath}。该路径可能产生无限输出或阻塞进程。` };
+    }
+    // 4b'. 二进制扩展名黑名单：在 stat 之前快速短路，避免把 .png/.exe/.pdf 等塞回 LLM
+    if (hasBinaryExtension(filePath)) {
+        return {
+            ok: false,
+            error: `不支持读取二进制文件：${filePath}（扩展名命中二进制黑名单）。若该文件实际为文本，可改后缀或用 Bash cat 旁路。`,
+        };
+    }
+    // 4c. 文件存在性 / 大小检查
+    let st;
+    try {
+        st = await stat(filePath);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: `读取失败：${filePath} 不存在或无法访问（${e.message}）`,
+        };
+    }
+    if (!st.isFile()) {
+        return { ok: false, error: `${filePath} 不是文件（可能是目录）。要列目录用 Glob 工具。` };
+    }
+    if (st.size > MAX_FILE_SIZE_BYTES) {
+        return {
+            ok: false,
+            error: `文件过大（${st.size} 字节 > ${MAX_FILE_SIZE_BYTES}）。请用 offset/limit 分段读。`,
+        };
+    }
+    // 4d. 根据文件大小选择读取策略
+    let numbered;
+    let totalLines;
+    if (st.size <= STREAM_THRESHOLD) {
+        // 小文件：原有 readFile 路径
+        const result = await readSmallFile(filePath, offset, limit);
+        numbered = result.numbered;
+        totalLines = result.totalLines;
+        if (result.isEmpty) {
+            recordRead(filePath);
+            return { ok: true, content: '<file is empty>' };
+        }
+    }
+    else {
+        // 大文件（>1MB 且 <= MAX_FILE_SIZE_BYTES）：流式读取
+        const result = await readLargeFileStream(filePath, offset, limit);
+        numbered = result.numbered;
+        totalLines = result.totalLines;
+    }
+    // 4e. 空文件处理
+    if (totalLines === 0 || !numbered) {
+        recordRead(filePath);
+        return { ok: true, content: '<file is empty>' };
+    }
+    // 4f. 大小兜底 + 自动分段提示
+    let content = numbered;
+    if (content.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
+        content =
+            content.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) +
+                `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
+    }
+    const startIdx = Math.max(0, offset - 1);
+    const endIdx = Math.min(totalLines, startIdx + limit);
+    if (endIdx < totalLines) {
+        const nextOffset = endIdx + 1;
+        const returnedLines = content.split('\n').filter(l => l.trim()).length;
+        content += `\n\n... (本次返回 ${returnedLines} 行 / 文件共 ${totalLines} 行；用 offset=${nextOffset} 继续读)`;
+    }
+    if (st.size > 100 * 1024 && offset === 1) {
+        content += `\n\n⚠️ 注意：这是一个大文件（${(st.size / 1024).toFixed(1)} KB）。建议用 offset/limit 分段读取，例如先读关键部分（imports、exports、函数签名）。`;
+    }
+    recordRead(filePath);
+    return { ok: true, content };
+}
+async function readSmallFile(filePath, offset, limit) {
+    const raw = await readFile(filePath, 'utf8');
+    if (raw.length === 0) {
+        return { numbered: '', totalLines: 0, isEmpty: true };
+    }
+    const allLines = raw.split('\n');
+    const totalLines = allLines.length;
+    const startIdx = Math.max(0, offset - 1);
+    const endIdx = Math.min(totalLines, startIdx + limit);
+    const slice = allLines.slice(startIdx, endIdx);
+    const numbered = slice
+        .map((line, i) => `${(startIdx + i + 1).toString()}\t${line}`)
+        .join('\n');
+    return { numbered, totalLines, isEmpty: false };
+}
+async function readLargeFileStream(filePath, offset, limit) {
+    return new Promise((resolvePromise, reject) => {
+        const lines = [];
+        let currentLine = 0;
+        const startIdx = Math.max(0, offset - 1);
+        const endLine = startIdx + limit;
+        const input = createReadStream(filePath, { encoding: 'utf8' });
+        const rl = createInterface({
+            input,
+            crlfDelay: Infinity,
+        });
+        input.on('error', (err) => {
+            reject(err);
+        });
+        rl.on('line', (line) => {
+            currentLine++;
+            if (currentLine > endLine) {
+                rl.close();
+                rl.removeAllListeners();
+                return;
+            }
+            if (currentLine >= offset) {
+                lines.push(`${currentLine}\t${line}`);
+            }
+        });
+        rl.on('close', () => {
+            resolvePromise({
+                numbered: lines.join('\n'),
+                totalLines: currentLine,
+            });
+        });
+        rl.on('error', (err) => {
+            reject(err);
+        });
+    });
+}
+// ---------------- 5. 导出工具对象 ----------------
+export const readTool = {
+    name: 'Read',
+    description,
+    inputSchema,
+    parameters,
+    isReadOnly: true,
+    isConcurrencySafe: true,
+    maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+    call,
+};