mocode-ai 1.6.0 → 1.6.2

package/dist/tools/builtins/grep.js

@@ -1,19 +1,68 @@
 import { readFile } from 'node:fs/promises';
 import fg from 'fast-glob';
-import { MAX_RESULTS, IGNORE } from '../constants.js';
-// 二进制文件探测:头部 4KB 含 C0 控制字符(NUL/BEL 等)即视为二进制,跳过。
-// 否则 grep 扫到 SQLite/压缩文件等会产出「单行数 KB + 控制字符」的匹配行,
-// 这类行进 TUI 展开后被终端 auto-wrap,物理行与缓冲行失配导致整屏错乱。
-const BINARY_PROBE_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
+import { IGNORE, MAX_RESULTS } from '../constants.js';
+import { isProbablyBinary } from '../../attachments/image.js';
+// 二进制文件探测统一走 attachments/image.ts 的 isProbablyBinary(与 read_file 同源同口径,
+// 避免两处正则漂移):头部含 C0 控制字符即跳过。否则 grep 扫到 SQLite/压缩文件等会产出
+// 「单行数 KB + 控制字符」的匹配行,这类行进 TUI 展开后被终端 auto-wrap,物理行与缓冲行
+// 失配导致整屏错乱。
 import { getSandboxRoot, isInsideRoot, jailResolve } from '../../sandbox/index.js';
+/** 单文件读取上限:超过即跳过(压缩产物 / 生成物 / 数据 dump)。
+ *  逐文件全量 readFile 进内存是 grep 的固有成本,不设上限时一个 200MB 的 bundle
+ *  就能把整轮 grep 拖死并撑爆内存。跳过的文件数会在结果尾部报出来,不静默吞。 */
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+/** 单条 body 行渲染上限(字符):minified JS / 单行 JSON 截断加 …,
+ *  既防 TUI auto-wrap 错乱,也防一行吃掉整个 MAX_RESULTS 预算。 */
+const MAX_BODY_LINE_CHARS = 400;
+/** context 参数上限:邻居行是 ×(1+2C) 放大,给到 10 已远超「看清一段逻辑」的需要。 */
+const MAX_CONTEXT_LINES = 10;
+/** 超长行截断(保留头部:grep 的价值在行首标识与缩进)。 */
+function clipLine(line) {
+    if (line.length <= MAX_BODY_LINE_CHARS)
+        return line;
+    return `${line.slice(0, MAX_BODY_LINE_CHARS)}…(+${line.length - MAX_BODY_LINE_CHARS} 字符)`;
+}
+/**
+ * 把命中行号 + context 半径渲染成 body 行。
+ *
+ * 输出格式契约(context/encoders/search.ts 依赖前两个前缀做 Cold 折叠):
+ *   `  L<n>: <原文>`   命中行(冒号)
+ *   `  L<n>- <原文>`   上下文行(连字符,对齐 ripgrep 的 `:` / `-`)
+ *   `  --`             不相邻分块之间的分隔(对齐 ripgrep)
+ * 原文**不 trim**:缩进是代码结构信息,trim 掉后模型看不出嵌套层级,只能再发一次
+ * read_file 去确认——那正是 context 参数要消灭的往返。
+ */
+function renderBodies(lines, lineNos, maxPerFile, context) {
+    const shown = lineNos.slice(0, maxPerFile);
+    if (shown.length === 0)
+        return [];
+    const matched = new Set(shown);
+    // 命中行 ± context 的并集,排序后按连续块渲染。
+    const wanted = new Set();
+    for (const n of shown) {
+        for (let i = n - context; i <= n + context; i++) {
+            if (i >= 1 && i <= lines.length)
+                wanted.add(i);
+        }
+    }
+    const out = [];
+    let previous = 0;
+    for (const n of [...wanted].sort((a, b) => a - b)) {
+        if (previous !== 0 && n !== previous + 1)
+            out.push('  --');
+        previous = n;
+        out.push(`  L${n}${matched.has(n) ? ':' : '-'} ${clipLine(lines[n - 1])}`);
+    }
+    return out;
+}
 // ---------- grep ----------
 export const grepTool = {
     name: 'grep',
-    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. Independent read_file/grep/glob calls may be ' +
-        'issued in the same response and run concurrently. For call chains across many files, prefer loading the `codegraph` skill (use_skill).',
+    description: 'Search file contents by regex (recursive, excludes node_modules/.git/dist).\n' +
+        'Output: per-file header "<path>: N matches, lines [l1, l2, ...]" + matched lines with ORIGINAL INDENTATION kept.\n' +
+        'Pass context=2..5 to get neighbouring lines inline (like ripgrep -C) — use it INSTEAD of following every hit with a read_file round-trip.\n' +
+        'Still use read_file(offset=X, limit=Y) for a whole region or exact edit text — never reconstruct an edit_file old_string from grep output (long lines are clipped). ' +
+        'For call chains across many files, prefer the codegraph skill.',
     parameters: {
         type: 'object',
         properties: {
@@ -21,7 +70,12 @@ export const grepTool = {
             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.',
+                description: 'Max MATCHED lines rendered per file (default 15, cap 50); their context lines are extra. Line-number list is always full.',
+            },
+            context: {
+                type: 'integer',
+                description: 'Neighbouring lines to include around each match, like ripgrep -C (default 0, max 10). ' +
+                    'Output grows ~x(1+2*context) and counts against the same result budget, so keep it small.',
             },
         },
         required: ['pattern'],
@@ -30,6 +84,8 @@ export const grepTool = {
         const pattern = String(args.pattern);
         const g = String(args.glob ?? '**/*');
         const maxPerFile = Math.min(Math.max(Number(args.max_per_file ?? 15), 1), 50);
+        const contextRaw = Number(args.context ?? 0);
+        const context = Number.isFinite(contextRaw) ? Math.min(Math.max(Math.trunc(contextRaw), 0), MAX_CONTEXT_LINES) : 0;
         let re;
         try {
             re = new RegExp(pattern);
@@ -38,18 +94,27 @@ export const grepTool = {
             return `错误:非法正则 ${pattern}: ${e instanceof Error ? e.message : String(e)}`;
         }
         const cwd = getSandboxRoot() ?? process.cwd();
-        const files = (await fg(g, {
+        // stats:true 让 fast-glob 顺手带回 size,免为体积闸门再付一次 stat 系统调用。
+        const entries = (await fg(g, {
             cwd,
             onlyFiles: true,
             dot: true,
             ignore: IGNORE,
+            stats: true,
             followSymbolicLinks: false, // 不跟随软链目录,防经软链扫到牢外文件
             throwErrorOnBrokenSymbolicLink: false,
-        })).filter((f) => isInsideRoot(f)); // 后置兜底:仅留牢内
+        })).filter((entry) => isInsideRoot(entry.path)); // 后置兜底:仅留牢内
         const hits = [];
         let scanned = 0;
+        let skippedTooLarge = 0;
         let truncated = false;
-        for (const f of files) {
+        for (const entry of entries) {
+            const f = entry.path;
+            // 体积闸门:压缩产物 / 数据 dump 读进来只会撑爆内存并产出无意义超长行。
+            if (entry.stats && entry.stats.size > MAX_FILE_BYTES) {
+                skippedTooLarge++;
+                continue;
+            }
             let content;
             try {
                 // jailResolve:realpath 化,防「牢内文件软链→牢外」的内容泄露;越界/不可读均 catch 跳过
@@ -61,7 +126,7 @@ export const grepTool = {
             scanned++;
             // 二进制文件(如 .codegraph/codegraph.db 这类 SQLite)跳过:其「行」是数 KB 的
             // 序列化记录 + 控制字符,匹配行对 LLM 无意义,还会污染 TUI 展开渲染。
-            if (BINARY_PROBE_RE.test(content.slice(0, 4096)))
+            if (isProbablyBinary(content))
                 continue;
             const lines = content.split(/\r?\n/);
             const lineNos = [];
@@ -71,8 +136,10 @@ export const grepTool = {
             }
             if (lineNos.length === 0)
                 continue;
-            // 全局配额:行号列表总是计入,body 行数也计入(行号 + body 两条共用 MAX_RESULTS)
-            const totalCost = lineNos.length + Math.min(lineNos.length, maxPerFile);
+            // 全局配额:行号列表总是计入,body 成本按「命中行数 ×(1+2×context)」计入 ——
+            // context 是乘法放大,不按实际渲染量计就会让带 ±5 邻居的 grep 静默撑爆预算。
+            const bodyCost = Math.min(lineNos.length, maxPerFile) * (1 + 2 * context);
+            const totalCost = lineNos.length + bodyCost;
             if (hits.length >= MAX_RESULTS || totalCost > MAX_RESULTS * 4) {
                 // 文件过多 / 配额爆:仅追加该文件行号列表,不再展开 body
                 if (hits.length < MAX_RESULTS) {
@@ -81,19 +148,17 @@ export const grepTool = {
                 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 });
+            hits.push({ path: f, lineNos, bodies: renderBodies(lines, lineNos, maxPerFile, context) });
         }
+        const skippedNote = skippedTooLarge
+            ? `,跳过 ${skippedTooLarge} 个超过 ${MAX_FILE_BYTES / 1024 / 1024}MiB 的文件`
+            : '';
         if (hits.length === 0)
-            return `无匹配(扫描了 ${scanned} 个文件)`;
+            return `无匹配(扫描了 ${scanned} 个文件${skippedNote})`;
         const out = [];
         let totalShown = 0;
         for (const h of hits) {
-            const header = `${h.path}: ${h.lineNos.length} 处匹配,行号 [${h.lineNos.join(', ')}]`;
-            out.push(header);
+            out.push(`${h.path}: ${h.lineNos.length} 处匹配,行号 [${h.lineNos.join(', ')}]`);
             if (h.bodies.length > 0) {
                 out.push(...h.bodies);
             }
@@ -102,12 +167,14 @@ export const grepTool = {
             }
             totalShown += h.lineNos.length + h.bodies.length;
             if (totalShown >= MAX_RESULTS) {
-                out.push(`...(结果达到 ${MAX_RESULTS} 条上限)`);
+                out.push(`...(结果达到 ${MAX_RESULTS} 条上限${context > 0 ? ',context 行同样计入;要更全就减小 context 或收窄 glob' : ''})`);
                 break;
             }
         }
         if (truncated)
             out.push(`...(仍有更多匹配文件未展示,缩小 glob 或收窄正则)`);
+        if (skippedTooLarge)
+            out.push(`...(跳过 ${skippedTooLarge} 个超过 ${MAX_FILE_BYTES / 1024 / 1024}MiB 的文件)`);
         return out.join('\n');
     },
 };

package/dist/tools/builtins/index.js

@@ -1,6 +1,5 @@
 import { installBuiltinTools } from '../registry.js';
 import { readFileTool } from './read-file.js';
-import { viewImageTool } from './view-image.js';
 import { screenshotTool } from './screenshot.js';
 import { writeFileTool } from './write-file.js';
 import { editFileTool } from './edit-file.js';
@@ -35,9 +34,9 @@ import { computerTool } from './computer.js';
 const pathResource = (args) => typeof args.path === 'string' && args.path ? [`file:${args.path}`] : ['workspace'];
 const workspaceResource = () => ['workspace'];
 const memoryResource = () => ['memory-store'];
-const CAPABILITIES = {
+/** 导出供审计测试:能力声明是单一事实源,测试直接断言这张表(而非重新枚举一遍工具名)。 */
+export const CAPABILITIES = {
     read_file: { effect: 'read', concurrency: 'parallel', resources: pathResource },
-    view_image: { effect: 'read', concurrency: 'parallel', resources: pathResource },
     screenshot: { effect: 'process', concurrency: 'serial', resources: workspaceResource, supportsAbort: true },
     write_file: {
         effect: 'write',
@@ -52,8 +51,10 @@ const CAPABILITIES = {
     browser: { effect: 'process', concurrency: 'serial', resources: workspaceResource },
     glob: { effect: 'read', concurrency: 'parallel', resources: workspaceResource },
     grep: { effect: 'read', concurrency: 'parallel', resources: workspaceResource },
-    web_search: { effect: 'network', concurrency: 'parallel', supportsAbort: true },
-    web_fetch: { effect: 'network', concurrency: 'parallel', supportsAbort: true },
+    // 网络只读查询:无副作用,可安全重复执行 → idempotent 让 runtime 对瞬时失败(429/5xx/超时/
+    // 网络抖动)自动退避重试,省掉模型「再发一轮 tool call 自救」的往返。写/进程类工具绝不置此位。
+    web_search: { effect: 'network', concurrency: 'parallel', supportsAbort: true, idempotent: true },
+    web_fetch: { effect: 'network', concurrency: 'parallel', supportsAbort: true, idempotent: true },
     use_skill: { effect: 'read', concurrency: 'serial' },
     run_skill: { effect: 'process', concurrency: 'serial', delegatesResourceLocks: true, supportsAbort: true },
     ask_human: { effect: 'read', concurrency: 'serial' },
@@ -87,7 +88,6 @@ const CAPABILITIES = {
 };
 const rawBuiltinTools = [
     readFileTool,
-    viewImageTool,
     screenshotTool,
     writeFileTool,
     editFileTool,

package/dist/tools/builtins/note-append.js

@@ -36,14 +36,10 @@ function normalizeSection(raw) {
 }
 export const noteAppendTool = {
     name: 'note_append',
-    description: 'Append a decision-grade note (a finding, decision, open question, or risk) to the session notepad ' +
-        '(`.mocode/sessions/<id>/notes.md`) so it survives context compaction and stays resident in the prompt. ' +
-        'Use this for NON-OBVIOUS, lasting-value discoveries — subtle constraints, decisions with downstream impact, ' +
-        'open questions that block a choice, or risks that affect later steps. Do NOT use it for routine progress ' +
-        '(that is the plan via `plan_update`) or for stable cross-session facts (that is `memory_save`). ' +
-        'Notes you write here persist across compaction within this session and are re-injected into the prompt ' +
-        'automatically, so the agent keeps remembering what it found/decided. Call it the moment you make the ' +
-        'discovery or decision — do not batch to the end.',
+    description: 'Append ONE decision-grade note (finding / decision / open question / risk) to the session notepad (notes.md); it survives compaction and is re-injected into the prompt automatically. ' +
+        'Only NON-OBVIOUS, lasting-value discoveries: subtle constraints, decisions with downstream impact, open questions blocking a choice, risks affecting later steps. ' +
+        'NOT routine progress (that is plan_update) and NOT stable cross-session facts (that is memory_save). ' +
+        'Call the moment you make the discovery or decision — do not batch to the end. One item per call.',
     risk: 'safe',
     parameters: {
         type: 'object',

package/dist/tools/builtins/plan-update.js

@@ -18,12 +18,7 @@ function normalizeStatus(raw) {
 }
 export const planUpdateTool = {
     name: 'plan_update',
-    description: 'Record and update the session execution plan (the `## Plan:` block in `.mocode/sessions/<id>/notes.md`). ' +
-        'Use for any task with 3+ steps or context-loss risk. This REPLACES the whole plan each call, so always pass the full steps array. ' +
-        'Rules: at most one step may be in_progress; mark a step completed as soon as its work is done — do not batch updates to end of turn. ' +
-        'Give every step a short `title` (≤20 chars, e.g. "编写测试" / "修 status bar") that shows in the status bar, ' +
-        'plus a `content` that is self-contained enough to survive context compaction: name the target file/symbol, the change, and how to verify. ' +
-        'When every step is completed the plan auto-settles to `## Done:`. Creates notes.md if missing. Safe to call in PLAN mode (writes only the session notepad, never project files).',
+    description: 'Record and update the session execution plan (the `## Plan:` block in notes.md). Use for any task with 3+ steps or context-loss risk. REPLACES the whole plan each call — always pass the full steps array. At most one step in_progress; mark a step completed as soon as its work is done, not batched to end of turn. Each step: short `title` (≤20 chars, shown in the status bar) + `content` self-contained enough to survive compaction (target file/symbol, change, verification). All steps completed → auto-settles to `## Done:`. Creates notes.md if missing. Safe in PLAN mode (writes only the session notepad).',
     risk: 'safe',
     parameters: {
         type: 'object',

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

@@ -1,31 +1,59 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { contentHash } from '../../changeset/index.js';
-import { MAX_FILE_LINES } from '../constants.js';
+import { IMAGE_READ_MARKER, MAX_FILE_LINES } from '../constants.js';
+import { MAX_INLINE_BYTES_DEFAULT, isProbablyBinary, loadImageAttachmentWithDownscale, sniffImageMime, } from '../../attachments/image.js';
 /** 默认单次 read_file 拉取的行数。刻意压低,逼 LLM 分块读大文件,
  * 配合 description 中的 PAGINATION IS MANDATORY 引导。
  * 300 行 ≈ 一个屏幕的源码量,够定位一段逻辑而不至于吃光上下文。 */
 const DEFAULT_READ_LIMIT = 300;
+/** 魔数嗅探只需文件头:16KB 足够覆盖 WebP(12 字节)/PNG(8)/GIF(6)/JPEG(SOF 位置不定)
+ *  与二进制探测的 4KB 控制字符窗口。 */
+const SNIFF_BYTES = 16 * 1024;
+/** 再导出单一事实源(tools/constants.ts):ui/render.ts 与测试都按此判定图片分支摘要。 */
+export { IMAGE_READ_MARKER };
+/**
+ * 单文件体积上限(32 MiB)。
+ *
+ * 行号分页的实现是「整文件载入内存再按行切片」,所以体积直接等于内存占用:一个 2GB 的
+ * 数据 dump / 压缩包能把进程顶死,而模型其实只需要其中一段。上限取得足够高,只拦真正
+ * 病态的输入;拦下时明确指路(grep 定位 + run_command 按段取),不给模型留猜谜空间。
+ */
+const MAX_FILE_BYTES = 32 * 1024 * 1024;
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+/** 结构化失败:status=error 让上层不当成「成功读取」;output 以 `错误:` 开头对齐既有约定
+ *  (context/utils.isToolResultSuccess 靠该前缀判定,artifacts/relevance 据此排除失败结果)。 */
+function failure(code, message) {
+    return { status: 'error', code, retryable: false, output: `错误:${message}` };
+}
 // ---------- read_file ----------
 export const readFileTool = {
     name: 'read_file',
-    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' +
-        'When you need several regions of the SAME file, issue those read_file calls together in one ' +
-        'response (they run concurrently) instead of paging through it one page after another — ' +
-        'avoid sequential offset+=limit walks of the same file.\n' +
-        'For files ≤500 lines you may read the whole file in one call. Independent region reads ' +
-        'may be issued in the same response — they run concurrently, saving a round-trip each.\n' +
-        'For architecture or call-chain questions, prefer loading the `codegraph` skill (use_skill) over reading files one at a time.',
+    description: 'Read a file: text with line numbers, images as visual model input.\n' +
+        'Text — read before editing. Files >500 lines: grep first, then read_file with offset+limit (e.g. offset=350, limit=120); never read a whole large file in one call. ' +
+        'Need several regions of the SAME file? Issue those read_file calls together in one response (they run concurrently) instead of sequential offset+=limit walks. ' +
+        'Images — PNG/JPEG/GIF/WebP detected by MAGIC BYTES (extension ignored), attached as visual input; detail=low|high controls resolution, oversized PNGs downscale automatically. ' +
+        'Other binaries are REJECTED with an explanation — use run_command with a proper tool (`file`, `strings`, disassembler) if you need their content. ' +
+        'Architecture/call-chain questions: prefer the codegraph skill over reading files one at a time.',
     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).' },
+            offset: { type: 'integer', description: 'Start line, 1-based (default 1). Text files only; ignored for images.' },
             limit: {
                 type: 'integer',
-                description: 'Max lines to read (default 300, hard cap 2000). Keep ranges modest (e.g. 80-300); for files ≤500 lines you may read the whole file in one call.',
+                description: 'Max lines to read (default 300, hard cap 2000). Keep ranges modest (e.g. 80-300); for files ≤500 lines you may read the whole file in one call. Text only; ignored for images.',
+            },
+            detail: {
+                type: 'string',
+                enum: ['auto', 'low', 'high'],
+                description: 'Vision detail level when the path is an image (default: auto). Ignored for text.',
             },
         },
         required: ['path'],
@@ -35,7 +63,55 @@ export const readFileTool = {
         const offset = Number(args.offset ?? 1);
         // 无论 LLM 传多大,单次硬钳到 MAX_FILE_LINES,杜绝「绕过分页引导一把全拿」。
         const limit = Math.min(Number(args.limit ?? DEFAULT_READ_LIMIT), MAX_FILE_LINES);
-        const data = await readFile(resolve(path), 'utf8');
+        // enforceSandbox 已把 args.path 重写为牢内绝对路径(sandbox/policy.ts SANDBOX_PATH_TOOLS),
+        // resolve 对绝对路径原样返回。
+        const absolute = resolve(path);
+        // ── 1. stat:目录 / 不存在 / 超大文件在这里分流,不把字节读进来再说 ────────
+        let info;
+        try {
+            info = await stat(absolute);
+        }
+        catch (error) {
+            const e = error;
+            if (e?.code === 'ENOENT')
+                return failure('EXECUTION_ERROR', `文件不存在: ${path}`);
+            return failure('EXECUTION_ERROR', `无法访问文件 ${path}: ${e?.message ?? String(error)}`);
+        }
+        if (info.isDirectory()) {
+            return failure('INVALID_ARGUMENTS', `${path} 是目录,不是文件。用 glob(pattern="${path}/**") 列目录内容,或用 grep 在目录下搜内容。`);
+        }
+        if (!info.isFile()) {
+            return failure('INVALID_ARGUMENTS', `${path} 不是普通文件(设备/套接字/特殊文件),无法读取。`);
+        }
+        if (info.size > MAX_FILE_BYTES) {
+            return failure('INVALID_ARGUMENTS', `${path} 有 ${formatBytes(info.size)},超过 read_file 的 ${formatBytes(MAX_FILE_BYTES)} 上限` +
+                '(行号分页需整文件载入内存)。先用 grep 定位行号,再用 run_command 配合系统工具按段取。');
+        }
+        let buffer;
+        try {
+            buffer = await readFile(absolute);
+        }
+        catch (error) {
+            const e = error;
+            return failure(e?.code === 'EACCES' || e?.code === 'EPERM' ? 'SANDBOX_DENIED' : 'EXECUTION_ERROR', `读取 ${path} 失败: ${e?.message ?? String(error)}`);
+        }
+        // ── 2. 魔数嗅探:图片走视觉通道,其余二进制明确拒绝 ──────────────────────
+        // 为什么必须嗅探而不看扩展名:扩展名会说谎(截图缓存 / 构建产物常无扩展名或错扩展名),
+        // 而把二进制当 UTF-8 解码的代价是实测一张 42KB PNG 产出 17862 个 U+FFFD(占 45%),
+        // 经 history 上限中截后仍有数千字符纯乱码进上下文 —— 既烧 token 又误导模型。
+        const head = buffer.subarray(0, SNIFF_BYTES);
+        const sniffed = sniffImageMime(head);
+        if (sniffed)
+            return await readAsImage(path, sniffed, args.detail, info.size);
+        if (isProbablyBinary(head)) {
+            return failure('INVALID_ARGUMENTS', `${path} 是二进制文件(头部含控制字符),不能按文本读取 —— 强行解码只会得到乱码。` +
+                '若它其实是图片,支持的格式为 png/jpg/jpeg/gif/webp;否则用 run_command 配合专用工具' +
+                '(如 file / strings / 反汇编器)查看。');
+        }
+        // ── 3. 文本:沿用既有 artifact header + 行号分页 ────────────────────────
+        // hash 仍取「UTF-8 解码后字符串」的摘要(与改动前逐字节一致):会话里已持久化的
+        // expected_hash 与 context/artifacts 的 parseReadHash 都依赖这个口径,不能顺手换。
+        const data = buffer.toString('utf8');
         const artifactHeader = `[artifact source=read_file path=${path} hash=${contentHash(data)}]`;
         const lines = data.split(/\r?\n/);
         const start = Math.max(0, offset - 1);
@@ -44,9 +120,50 @@ export const readFileTool = {
             .slice(start, end)
             .map((l, i) => `${String(start + i + 1).padStart(6, ' ')}\t${l}`)
             .join('\n');
-        if (end < lines.length) {
-            return artifactHeader + '\n' + body + `\n\n... (${lines.length - end} 行未显示,共 ${lines.length} 行)`;
-        }
-        return artifactHeader + '\n' + (body || '(空文件)');
+        // 空文件(0 字节)显式报「(空文件)」:''.split 得到 [''],行号分页会渲染成 `     1\t`,
+        // 让模型误以为读到了带一行空白的文件。data.length===0 才是真·空的判据。
+        if (data.length === 0)
+            return { status: 'success', code: 'OK', retryable: false, output: `${artifactHeader}\n(空文件)` };
+        const output = end < lines.length
+            ? `${artifactHeader}\n${body}\n\n... (${lines.length - end} 行未显示,共 ${lines.length} 行)`
+            : `${artifactHeader}\n${body}`;
+        return { status: 'success', code: 'OK', retryable: false, output };
     },
 };
+/**
+ * 图片分支:走视觉通道(modelAttachments),文本 output 只留一句可读摘要。
+ *
+ * 复用 attachments/image.ts 的加载 + 超限 PNG 降采样逻辑,与 screenshot 同口径
+ * (4 MiB 内联上限、detail 语义、越界拒绝)。offset/limit 对图片无意义,显式说明而非静默忽略。
+ */
+async function readAsImage(path, mime, detailArg, bytes) {
+    const loaded = await loadImageAttachmentWithDownscale(path, {
+        maxBytes: MAX_INLINE_BYTES_DEFAULT,
+        sniffedMime: mime,
+    });
+    if (!loaded.ok) {
+        return failure(loaded.reason.startsWith('outside sandbox') ? 'SANDBOX_DENIED' : 'EXECUTION_ERROR', `无法把图片 ${path} 作为视觉输入加载: ${loaded.reason}`);
+    }
+    const detail = detailArg === 'low' || detailArg === 'high' ? detailArg : 'auto';
+    const { att, downscaledFrom } = loaded;
+    const resizedNote = downscaledFrom
+        ? ` Original ${downscaledFrom.width}×${downscaledFrom.height} exceeded the inline limit; the attached copy was downscaled.`
+        : '';
+    return {
+        status: 'success',
+        code: 'OK',
+        retryable: false,
+        output: `${IMAGE_READ_MARKER} Detected an image by magic bytes (${mime}, ${formatBytes(bytes)} on disk) and attached it ` +
+            `as visual model input.${resizedNote} Attached ${att.bytes} bytes. ` +
+            'offset/limit do not apply to images; pass detail=low to save tokens on the next one.',
+        modelAttachments: [
+            {
+                type: 'image',
+                name: att.name,
+                mime: att.mime,
+                dataUrl: att.dataUrl,
+                detail,
+            },
+        ],
+    };
+}

package/dist/tools/builtins/run-command.js

@@ -2,8 +2,28 @@ import { spawn, spawnSync } from 'node:child_process';
 import { MAX_OUTPUT } from '../constants.js';
 import { getSandboxRoot, filterEnv, isCommandDenied, jailResolve } from '../../sandbox/index.js';
 import { t } from '../../i18n/index.js';
+import { shellParamDescription, defaultShellKind, parseShellKind, shellSpawnSpec, } from '../../runtime/shell.js';
 const OUTPUT_HEAD_LIMIT = Math.floor(MAX_OUTPUT * 0.4);
 const OUTPUT_TAIL_LIMIT = MAX_OUTPUT - OUTPUT_HEAD_LIMIT;
+/**
+ * 前台命令的超时窗口钳制。
+ *
+ * 下界 1s:防模型传 0/负数把 timer 变成「立即超时」,命令还没 spawn 就被判 timed_out。
+ * 上界 10min:run_command 声明 concurrency:'serial' + resources:['workspace']
+ * (builtins/index.ts:54),执行期间持有全局 workspace 锁 —— 一条超时 1 小时的命令会把
+ * 所有其它工具调用(含子 agent)一起挂死,且 TUI 只能等或 Ctrl+C。需要长驻的进程走
+ * dev_server(跨调用存活 + 日志增量读 + 树杀),不是把前台超时拉长。
+ */
+export const MIN_COMMAND_TIMEOUT_MS = 1_000;
+export const MAX_COMMAND_TIMEOUT_MS = 600_000;
+export const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
+/** 把模型给的 timeout 钳进 [MIN, MAX];非有限数(NaN/Infinity/非法字符串)回落默认值。 */
+export function clampCommandTimeout(raw) {
+    const value = Number(raw);
+    if (!Number.isFinite(value))
+        return DEFAULT_COMMAND_TIMEOUT_MS;
+    return Math.min(Math.max(Math.trunc(value), MIN_COMMAND_TIMEOUT_MS), MAX_COMMAND_TIMEOUT_MS);
+}
 /** 有界采集：短输出逐字保留；超限后保留 head+tail，避免构建/测试错误只出现在尾部时被丢弃。 */
 class BoundedCommandOutput {
     head = '';
@@ -26,8 +46,10 @@ class BoundedCommandOutput {
     }
 }
 /** Execute a command with the same sandbox, output cap and cancellation semantics as run_command. */
-export async function runCommandRaw(command, timeout = 120000, signal, cwd) {
+export async function runCommandRaw(command, timeout = DEFAULT_COMMAND_TIMEOUT_MS, signal, cwd, shell) {
     const startedAt = Date.now();
+    // 内部调用方(skill 注入等)也走同一钳制:防止任何路径把前台命令挂成无限期持锁。
+    const effectiveTimeout = clampCommandTimeout(timeout);
     const deny = isCommandDenied(command);
     if (deny) {
         return { status: 'denied', exitCode: null, output: `错误:${deny}`, durationMs: 0 };
@@ -44,12 +66,13 @@ export async function runCommandRaw(command, timeout = 120000, signal, cwd) {
     }
     return new Promise((done) => {
         const isWin = process.platform === 'win32';
-        const child = spawn(isWin ? 'cmd.exe' : 'bash', isWin ? ['/d', '/s', '/c', command] : ['-c', command], {
+        const spec = shellSpawnSpec(shell ?? defaultShellKind(), command);
+        const child = spawn(spec.file, spec.args, {
             cwd: executionCwd,
             env: filterEnv(process.env),
-            // Without this, Node re-quotes cmd.exe arguments and `node -e "..."` can become
-            // a string literal that exits 0, causing false-positive validation on Windows.
-            windowsVerbatimArguments: isWin,
+            // cmd.exe 需要 verbatim:否则 Node 重新引号化参数,`node -e "..."` 会退化成
+            // 字符串字面量并 exit 0,造成 Windows 上的假阳性验证。其它 shell 必须关。
+            windowsVerbatimArguments: spec.windowsVerbatimArguments,
         });
         const output = new BoundedCommandOutput();
         let finished = false;
@@ -86,7 +109,7 @@ export async function runCommandRaw(command, timeout = 120000, signal, cwd) {
         const timer = setTimeout(() => {
             killTree();
             finish({ status: 'timed_out', exitCode: null, output: output.render().trim() });
-        }, timeout);
+        }, effectiveTimeout);
         child.stdout.on('data', onChunk);
         child.stderr.on('data', onChunk);
         child.on('error', (error) => {
@@ -141,20 +164,46 @@ function commandOutcome(result) {
 // ---------- run_command ----------
 export const runCommandTool = {
     name: 'run_command',
-    description: 'Run a shell command, merging stdout+stderr. Default timeout 120s. For tests, builds, git, etc.\n' +
-        "Multiple independent run_command calls may be issued in one response to save model round-trips; they execute serially, so do not depend one on another's output within the same message.",
+    description: 'Run a FOREGROUND shell command, merging stdout+stderr. Default timeout 120s, hard cap 10min; pass shell=cmd|powershell|bash to pick the interpreter (platform default and MOCODE_SHELL override are stated in the system prompt). Non-interactive cmd cannot run `timeout /t` — use shell=powershell (`Start-Sleep`) or shell=bash (`sleep`) for waits.\n' +
+        'Anything that must keep running after this call returns — dev server, model service, watcher, log tail — belongs to dev_server (survives across calls; gives an id for incremental logs and process-tree kill). Do NOT detach via `start /b`, `nohup`, `&`: you lose both the logs and the handle.\n' +
+        'Multiple independent calls may be issued in one response (they run serially, in order); do not depend one on another\'s output within the same message.',
     risk: 'dangerous',
     parameters: {
         type: 'object',
         properties: {
             command: { type: 'string', description: 'Command to execute (single line)' },
-            timeout: { type: 'integer', description: 'Timeout in milliseconds, default 120000' },
+            timeout: {
+                type: 'integer',
+                description: `Timeout in milliseconds (default ${DEFAULT_COMMAND_TIMEOUT_MS}, clamped to ${MIN_COMMAND_TIMEOUT_MS}..${MAX_COMMAND_TIMEOUT_MS}). Raise it only for genuinely slow foreground work; use dev_server for long-running processes.`,
+            },
+            shell: { type: 'string', enum: ['cmd', 'powershell', 'bash'], description: shellParamDescription() },
         },
         required: ['command'],
     },
     async execute(args, ctx) {
         const command = String(args.command);
-        const timeout = Number(args.timeout ?? 120000);
-        return commandOutcome(await runCommandRaw(command, timeout, ctx?.signal));
+        const timeout = clampCommandTimeout(args.timeout);
+        // shell 非法值不静默忽略:明确报错,否则模型以为在 powershell 里跑却落到 cmd,
+        // 语法错误难以归因。合法值大小写/别名由 parseShellKind 归一。
+        let shell;
+        if (args.shell !== undefined) {
+            const parsed = parseShellKind(args.shell);
+            if (!parsed) {
+                return {
+                    status: 'error',
+                    code: 'INVALID_ARGUMENTS',
+                    retryable: false,
+                    output: `错误:无效的 shell "${String(args.shell)}"。可选值:cmd / powershell / bash。`,
+                };
+            }
+            shell = parsed;
+        }
+        const result = await runCommandRaw(command, timeout, ctx?.signal, undefined, shell);
+        const outcome = commandOutcome(result);
+        // 钳制要显式告知:模型传了 30min 却按 10min 判超时,不说清它会以为是环境抽风而盲目重试。
+        if (args.timeout !== undefined && Number(args.timeout) !== timeout && result.status === 'timed_out') {
+            outcome.output = `${outcome.output}\n(请求的 timeout=${Number(args.timeout)}ms 已钳制到 ${timeout}ms;需要长驻进程请改用 dev_server)`;
+        }
+        return outcome;
     },
 };