mocode-ai 1.6.0 → 1.6.2

package/dist/tools/builtins/screenshot.js

@@ -1,12 +1,9 @@
-import { mkdir, readFile } from 'node:fs/promises';
-import { basename, dirname, extname } from 'node:path';
-import { loadImageAttachment, MAX_INLINE_BYTES_DEFAULT } from '../../attachments/image.js';
+import { mkdir } from 'node:fs/promises';
+import { dirname, extname } from 'node:path';
+import { loadImageAttachmentWithDownscale, MAX_INLINE_BYTES_DEFAULT } from '../../attachments/image.js';
 import { jailResolve } from '../../sandbox/index.js';
 // 平台捕获逻辑已抽到 runtime/screen-capture.ts(computer 工具闭环共用),本文件只做薄封装。
 import { captureDesktop } from '../../runtime/screen-capture.js';
-import { decodePng, downscale, encodePng } from '../../runtime/screen-pipeline.js';
-/** 原图超过内联上限时降级缩放的长边(对齐主流视觉模型的原生分辨率)。 */
-const FALLBACK_MAX_EDGE = 1568;
 export const screenshotTool = {
     name: 'screenshot',
     description: 'Capture the desktop and inspect it as visual model input. Use this to diagnose visible UI state, dialogs, rendering problems, or applications that cannot be understood from source files alone. The user must approve each capture because screenshots may contain sensitive information.',
@@ -68,50 +65,29 @@ export const screenshotTool = {
                 output: `Unable to capture screenshot: ${capture.detail}`,
             };
         }
-        const loaded = await loadImageAttachment(outputPath, {
+        // 共享 helper:超内联上限时自动把 PNG 降采样到 DOWNSCALE_MAX_EDGE 再回灌,不让工具失败。
+        // 高分屏(尤其 DPI aware 后抓到物理分辨率)的 PNG 常超 4 MiB;原图仍留在磁盘上。
+        const loaded = await loadImageAttachmentWithDownscale(outputPath, {
             maxBytes: MAX_INLINE_BYTES_DEFAULT,
         });
         const detail = args.detail === 'low' || args.detail === 'auto' ? args.detail : 'high';
-        // 高分屏(尤其 DPI aware 后抓到物理分辨率)的 PNG 可能超过内联上限:
-        // 原图仍留在磁盘上,回灌改用缩放版本,不让工具因此失败。
         if (!loaded.ok) {
-            try {
-                const png = decodePng(await readFile(outputPath));
-                const { img } = downscale(png, FALLBACK_MAX_EDGE);
-                const buf = encodePng(img);
-                return {
-                    status: 'success',
-                    code: 'OK',
-                    retryable: false,
-                    output: `Captured ${target} display to ${requestedPath} (${png.width}×${png.height}); ` +
-                        `it exceeded the inline limit, so the attached copy was resized to ${img.width}×${img.height}.`,
-                    modelAttachments: [
-                        {
-                            type: 'image',
-                            name: basename(outputPath),
-                            mime: 'image/png',
-                            dataUrl: `data:image/png;base64,${buf.toString('base64')}`,
-                            detail,
-                        },
-                    ],
-                };
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                return {
-                    status: 'error',
-                    code: 'EXECUTION_ERROR',
-                    retryable: false,
-                    output: `Screenshot saved to ${requestedPath}, but it could not be attached: ${loaded.reason}${message ? ` (resize fallback failed: ${message})` : ''}`,
-                };
-            }
+            return {
+                status: 'error',
+                code: 'EXECUTION_ERROR',
+                retryable: false,
+                output: `Screenshot saved to ${requestedPath}, but it could not be attached: ${loaded.reason}`,
+            };
         }
-        const { att } = loaded;
+        const { att, downscaledFrom } = loaded;
+        const resizedNote = downscaledFrom
+            ? ` (${downscaledFrom.width}×${downscaledFrom.height}; exceeded the inline limit, so the attached copy was resized)`
+            : '';
         return {
             status: 'success',
             code: 'OK',
             retryable: false,
-            output: `Captured ${target} display to ${requestedPath} (${att.bytes} bytes). Visual content is attached to the next model request.`,
+            output: `Captured ${target} display to ${requestedPath} (${att.bytes} bytes)${resizedNote}. Visual content is attached to the next model request.`,
             modelAttachments: [
                 {
                     type: 'image',

package/dist/tools/builtins/use-skill.js

@@ -13,9 +13,9 @@ import { activateSkill } from '../../skills/activation.js';
 const MAX_SKILL_FILE = 200_000;
 export const useSkillTool = {
     name: 'use_skill',
-    description: 'Load the full SKILL.md instructions for a given skill. See the skill list in the system prompt for when to use each. ' +
+    description: 'Load the full SKILL.md instructions for a given skill (see the skill list in the system prompt for when to use each). ' +
         'Supports args (renders $ARGUMENTS / $1.. / ${SKILL_DIR}) and file (reads a bundled reference file). ' +
-        'For skills marked [fork], this returns a guide to call run_skill instead of loading the body inline.',
+        'Skills marked [fork] return a guide to call run_skill instead of loading the body inline.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/web-fetch.js

@@ -1,11 +1,83 @@
 import { MAX_OUTPUT } from '../constants.js';
 const FETCH_TIMEOUT_MS = 30000;
 const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36';
+/**
+ * 浏览器拟真头集合。
+ *
+ * 只带 UA 挡不住主流反爬:Cloudflare/DataDome 类盾检查 Sec-Fetch-* / Accept-Language 的
+ * 组合一致性(真浏览器必带,裸 fetch 必缺)。缺头是 roman.pt / nader.substack.com 403
+ * 而 flaviocopes(无盾)成功的直接原因。补全成本为零,收益是把一批「看起来像脚本」的
+ * 请求拉回「看起来像浏览器」。
+ */
+function browserHeaders() {
+    return {
+        'User-Agent': UA,
+        Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8',
+        'Accept-Language': 'en-US,en;q=0.9,zh-CN;q=0.8',
+        // sec-ch-ua 是 Chrome 的 client hints:与 UA 里的 Chrome/120 对齐,不一致反而更可疑。
+        'sec-ch-ua': '"Not_A Brand";v="8", "Chromium";v="120", "Google Chrome";v="120"',
+        'sec-ch-ua-mobile': '?0',
+        'sec-ch-ua-platform': '"Windows"',
+        'Sec-Fetch-Dest': 'document',
+        'Sec-Fetch-Mode': 'navigate',
+        'Sec-Fetch-Site': 'none',
+        'Sec-Fetch-User': '?1',
+        'Upgrade-Insecure-Requests': '1',
+        // 同源直访不带 Referer;跨域跳转场景由调用方语义决定,这里保持「直接导航」画像。
+        'Cache-Control': 'no-cache',
+    };
+}
+/**
+ * 纯文本代理回退(opt-in,默认关)。
+ *
+ * MOCODE_WEB_FETCH_PROXY 设为前缀型代理(如 `https://r.jina.ai/`),直连失败且疑似被盾拦截时
+ * 改走 `${PROXY}${原 URL}`。为什么默认关:把目标 URL 交给第三方是隐私/信任决策,必须由用户
+ * 显式打开,agent 不能替用户把浏览足迹外包出去。
+ */
+function proxyPrefix() {
+    const raw = (process.env.MOCODE_WEB_FETCH_PROXY ?? '').trim();
+    if (!raw)
+        return null;
+    try {
+        const parsed = new URL(raw);
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+            return null;
+        return parsed.href.endsWith('/') ? parsed.href : `${parsed.href}/`;
+    }
+    catch {
+        return null;
+    }
+}
+/** 疑似反爬拦截:这些状态码重试直连基本无望,值得走代理(若配置)。 */
+function isBlockedStatus(status) {
+    return status === 403 || status === 405 || status === 406 || status === 429 || status === 451 || status === 503;
+}
+async function attemptFetch(target, via, signal) {
+    try {
+        const resp = await fetch(target, { method: 'GET', headers: browserHeaders(), signal });
+        const contentType = resp.headers.get('content-type') ?? '';
+        const text = await resp.text();
+        return { ok: resp.ok, status: resp.status, statusText: resp.statusText, contentType, text, via };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return {
+            ok: false,
+            status: 0,
+            statusText: '',
+            contentType: '',
+            text: '',
+            via,
+            error: msg,
+            timedOut: signal.aborted,
+            networkError: !signal.aborted,
+        };
+    }
+}
 // ---------- web_fetch ----------
 export const webFetchTool = {
     name: 'web_fetch',
-    description: 'Fetch a URL and clean HTML to body text. Use to read a link from search results or a URL given by the user.',
-    parameters: {
+    description: 'Fetch a URL and clean HTML to body text. Use to read a link from search results or a URL given by the user.', parameters: {
         type: 'object',
         properties: {
             url: { type: 'string', description: 'Full URL to fetch; must be http/https' },
@@ -38,35 +110,9 @@ export const webFetchTool = {
                 externalSignal.addEventListener('abort', onExternalAbort, { once: true });
         }
         try {
-            const resp = await fetch(url.href, {
-                method: 'GET',
-                headers: {
-                    'User-Agent': UA,
-                    Accept: 'text/html,application/xhtml+xml,text/plain,application/json,*/*',
-                },
-                signal: ctrl.signal,
-            });
-            const contentType = resp.headers.get('content-type') ?? '';
-            const text = await resp.text();
-            if (!resp.ok) {
-                return {
-                    status: 'error',
-                    code: 'HTTP_ERROR',
-                    retryable: resp.status === 408 || resp.status === 429 || resp.status >= 500,
-                    output: `错误:抓取失败 HTTP ${resp.status} ${resp.statusText}\n${text.slice(0, 500)}`,
-                };
-            }
-            const isHtml = /html/i.test(contentType) || /^\s*<!doctype html/i.test(text) || /<html[\s>]/i.test(text.slice(0, 1000));
-            const body = isHtml ? htmlToText(text) : text;
-            const ct = contentType.split(';')[0].trim();
-            const prefix = `${url.href} (HTTP ${resp.status}${ct ? ', ' + ct : ''})\n\n`;
-            let out = prefix + body;
-            if (out.length > MAX_OUTPUT) {
-                out = out.slice(0, MAX_OUTPUT) + `\n...(已截断,原文 ${body.length} 字符)`;
-            }
-            return out;
-        }
-        catch (e) {
+            const attempt = await attemptFetch(url.href, 'direct', ctrl.signal);
+            // abort 优先判定:用户 Ctrl+C 是终态,绝不能被当成「直连失败」去走代理或重试。
+            // (放在直连结果之后、任何分支之前 —— 代理路径与 HTTP 错误路径都必须先过这道闸。)
             if (ctrl.signal.aborted) {
                 if (externalSignal?.aborted) {
                     return { status: 'aborted', code: 'ABORTED', retryable: false, output: `错误:已中断: ${url.href}` };
@@ -78,12 +124,48 @@ export const webFetchTool = {
                     output: `错误:抓取超时(${FETCH_TIMEOUT_MS}ms): ${url.href}`,
                 };
             }
-            const msg = e instanceof Error ? e.message : String(e);
+            if (attempt.ok)
+                return renderBody(attempt, url);
+            // 直连被盾拦(403/429/503…)且用户配置了代理 → 走代理再试一次;代理失败回落原始失败,
+            // 报「直连 + 代理」两段原因,让模型知道两条路都试过。
+            if (isBlockedStatus(attempt.status)) {
+                const prefix = proxyPrefix();
+                if (prefix) {
+                    const proxied = await attemptFetch(`${prefix}${url.href}`, 'proxy', ctrl.signal);
+                    // 代理期间的 abort 同样按终态处理,不降级成「代理失败」。
+                    if (ctrl.signal.aborted && !proxied.ok) {
+                        return externalSignal?.aborted
+                            ? { status: 'aborted', code: 'ABORTED', retryable: false, output: `错误:已中断: ${url.href}` }
+                            : {
+                                status: 'error',
+                                code: 'TIMEOUT',
+                                retryable: true,
+                                output: `错误:抓取超时(${FETCH_TIMEOUT_MS}ms): ${url.href}`,
+                            };
+                    }
+                    if (proxied.ok)
+                        return renderBody(proxied, url);
+                    return blockedFailure(attempt, proxied, url);
+                }
+            }
+            if (attempt.networkError) {
+                return {
+                    status: 'error',
+                    code: 'NETWORK_ERROR',
+                    retryable: true,
+                    output: `错误:抓取失败: ${attempt.error ?? 'network error'}`,
+                };
+            }
+            // HTTP 错误:429/5xx/408 标 retryable,registry 对幂等工具自动退避重试。
+            const retryable = attempt.status === 408 || attempt.status === 429 || attempt.status >= 500;
+            const hint = isBlockedStatus(attempt.status)
+                ? '\n(疑似反爬拦截;可设 MOCODE_WEB_FETCH_PROXY=<前缀代理> 开启纯文本代理回退)'
+                : '';
             return {
                 status: 'error',
-                code: 'NETWORK_ERROR',
-                retryable: true,
-                output: `错误:抓取失败: ${msg}`,
+                code: 'HTTP_ERROR',
+                retryable,
+                output: `错误:抓取失败 HTTP ${attempt.status} ${attempt.statusText}\n${attempt.text.slice(0, 500)}${hint}`,
             };
         }
         finally {
@@ -93,6 +175,37 @@ export const webFetchTool = {
         }
     },
 };
+/** 成功响应 → 清洗正文 + 截断(直连与代理共用)。 */
+function renderBody(attempt, url) {
+    const isHtml = /html/i.test(attempt.contentType) ||
+        /^\s*<!doctype html/i.test(attempt.text) ||
+        /<html[\s>]/i.test(attempt.text.slice(0, 1000));
+    const body = isHtml ? htmlToText(attempt.text) : attempt.text;
+    const ct = attempt.contentType.split(';')[0].trim();
+    const via = attempt.via === 'proxy' ? ', via proxy' : '';
+    const prefix = `${url.href} (HTTP ${attempt.status}${ct ? ', ' + ct : ''}${via})\n\n`;
+    let out = prefix + body;
+    if (out.length > MAX_OUTPUT) {
+        out = out.slice(0, MAX_OUTPUT) + `\n...(已截断,原文 ${body.length} 字符)`;
+    }
+    return out;
+}
+/** 直连被拦 + 代理也失败:两段原因都报,不掩盖代理尝试。 */
+function blockedFailure(direct, proxied, url) {
+    const proxyDetail = proxied.networkError
+        ? `代理网络错误: ${proxied.error ?? 'unknown'}`
+        : proxied.timedOut
+            ? '代理超时'
+            : `代理返回 HTTP ${proxied.status}`;
+    return {
+        status: 'error',
+        code: 'HTTP_ERROR',
+        retryable: direct.status === 429 || direct.status >= 500,
+        output: `错误:抓取失败(直连与代理均被拒): ${url.href}\n` +
+            `直连: HTTP ${direct.status} ${direct.statusText}\n${proxyDetail}\n` +
+            `直连响应片段: ${direct.text.slice(0, 300)}`,
+    };
+}
 /**
  * 轻量 HTML→纯文本:优先取 <main>/<article> 正文区,再去 nav/header/footer/aside/form
  * 等非正文块与脚本样式,块级/列表标签转换行,去剩余标签,解码实体,压缩空白。

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

@@ -6,8 +6,7 @@ const MAX_CONTENT_CHARS = 800;
 // ---------- web_search ----------
 export const webSearchTool = {
     name: 'web_search',
-    description: 'Search the web (AnySearch). Returns title/url/snippet/body per result. Optional tag for sub-domain capability.',
-    parameters: {
+    description: 'Search the web (AnySearch). Returns title/url/snippet/body per result. Optional tag for sub-domain capability.', parameters: {
         type: 'object',
         properties: {
             query: { type: 'string', description: 'Search query' },

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

@@ -1,4 +1,12 @@
-import { commitChangeSet, createChangeSet, normalizeContentHash, summarizeChangeSet, } from '../../changeset/index.js';
+import { readFile, stat } from 'node:fs/promises';
+import { commitChangeSet, contentHash, createChangeSet, normalizeContentHash, summarizeChangeSet, } from '../../changeset/index.js';
+import { jailResolve } from '../../sandbox/index.js';
+import { isProbablyBinary } from '../../attachments/image.js';
+/** append 需要把整个文件读进内存再全量重写(ChangeSet 的 backup + 原子 rename 语义决定),
+ *  故与 read_file 同款 32 MiB 闸门:超过就指路 shell 重定向,不把进程内存顶死。 */
+const MAX_APPEND_TARGET_BYTES = 32 * 1024 * 1024;
+/** 二进制嗅探只需文件头,与 read_file 同口径(16KB)。 */
+const SNIFF_BYTES = 16 * 1024;
 function conflict(path, details) {
     return {
         status: 'error',
@@ -9,18 +17,35 @@ function conflict(path, details) {
         output: `CHANGE_CONFLICT: ${path} was not changed. ${details} Do not retry these arguments. Call read_file on this exact path, then use the returned hash; use expected_hash=null only if read_file reports that the path is missing.`,
     };
 }
+function invalid(path, message) {
+    return {
+        status: 'error',
+        code: 'INVALID_ARGUMENTS',
+        retryable: false,
+        changedFiles: [],
+        output: `错误:${path}: ${message}`,
+    };
+}
 export const writeFileTool = {
     name: 'write_file',
-    description: 'Create or replace one file transactionally. expected_hash may be omitted (or null) only for create-only writes to a path that must not exist; overwriting requires the hash from a fresh read_file artifact header.',
+    description: 'Create or replace one file transactionally. expected_hash may be omitted (or null) only for create-only writes to a path that must not exist; overwriting requires the hash from a fresh read_file.\n' +
+        'To ADD to an existing file, pass append=true — only the new text goes in `content`; NO expected_hash and NO prior read_file needed (lock-protected; creates the file when missing). Appends VERBATIM: if the file does not end with a newline, start your content with "\\n" or the last line will merge with yours.',
     risk: 'confirm',
     parameters: {
         type: 'object',
         properties: {
             path: { type: 'string', description: 'File path' },
-            content: { type: 'string', description: 'Full file content' },
+            content: {
+                type: 'string',
+                description: 'File content. With append=false (default): the FULL new content. With append=true: only the text to add at the end.',
+            },
             expected_hash: {
                 type: ['string', 'null'],
-                description: 'Optional sha256 hash from read_file. Omit or pass null only when the path must not exist.',
+                description: 'Optional sha256 hash from read_file. Omit or pass null when the path must not exist, or when append=true (append reads the current content itself and is lock-protected).',
+            },
+            append: {
+                type: 'boolean',
+                description: 'Append `content` to the end of the file instead of replacing it (default false). Creates the file if missing. Text files only; binary targets are rejected.',
             },
         },
         required: ['path', 'content'],
@@ -28,6 +53,7 @@ export const writeFileTool = {
     async execute(args, ctx) {
         const file = String(args.path);
         const content = String(args.content);
+        const append = args.append === true;
         let expectedHash = null;
         // Missing and explicit null are both safe create-only requests. They never
         // overwrite: ChangeSet compares expectedHash=null against the current path.
@@ -36,13 +62,80 @@ export const writeFileTool = {
             if (!expectedHash)
                 return conflict(file, 'expected_hash 必须是 null 或 sha256:<64 hex>。');
         }
-        const operation = expectedHash === null ? 'create' : 'update';
+        let operation = expectedHash === null ? 'create' : 'update';
+        let replacement = content;
+        if (append) {
+            // append 的实现策略:工具层读现状 + 拼接 + 以 update 提交,**完全复用** ChangeSet 事务机器 ——
+            // 于是 rollback/diff/changeSet 追踪、原子 temp+rename 写回全部照旧,不新增第二套事务语义。
+            //
+            // 并发安全:读取发生在锁外(write_file 声明 delegatesResourceLocks,锁由 commitChangeSet 持有),
+            // 所以「读到」与「提交」之间存在窗口。这个窗口由 expectedHash 兜底 —— 下面把读到的内容 hash
+            // 填进 expectedHash,dryRun 会拿它与提交瞬间的真实内容比对:期间有人改过就报 CHANGE_CONFLICT
+            // (fail-loud,让模型重读重试),**绝不静默覆盖别人的追加**。这是 append 不需要模型先 read_file
+            // 的原因:hash 由工具自己算,正确性由冲突检测保证,而非靠模型复述。
+            let absolute;
+            try {
+                absolute = jailResolve(file);
+            }
+            catch (error) {
+                return invalid(file, error instanceof Error ? error.message : String(error));
+            }
+            let before = null;
+            try {
+                // 先 stat 再 read:体积闸门必须在字节进内存**之前**生效,否则一个 200MB 的日志
+                // 已经分配了 200MB 才被拒绝,闸门形同虚设(read_file 同款顺序)。
+                const info = await stat(absolute);
+                if (info.isDirectory()) {
+                    return invalid(file, '是目录,不能追加内容。');
+                }
+                if (!info.isFile()) {
+                    return invalid(file, '不是普通文件(设备/套接字/特殊文件),无法追加。');
+                }
+                if (info.size > MAX_APPEND_TARGET_BYTES) {
+                    return invalid(file, `有 ${(info.size / 1024 / 1024).toFixed(1)} MB,超过 append 的 32.0 MB 上限` +
+                        '(追加需整文件载入内存以走事务化写回)。超大日志请用 run_command 的 shell 重定向: `... >> <path>`。');
+                }
+                before = await readFile(absolute);
+            }
+            catch (error) {
+                const e = error;
+                // ENOENT = 文件还不存在:append 语义等同 shell `>>`,直接创建。其余错误如实上报。
+                if (e?.code !== 'ENOENT') {
+                    return {
+                        status: 'error',
+                        code: 'EXECUTION_ERROR',
+                        retryable: false,
+                        changedFiles: [],
+                        output: `错误:读取 ${file} 以便追加失败: ${e?.message ?? String(error)}`,
+                    };
+                }
+            }
+            if (before !== null) {
+                // 二进制拒绝是 append 特有的风险:全量覆盖时坏数据只影响这一次写入,
+                // 而 append 会把「解码坏掉的旧内容」永久写回原文件,等于静默损毁数据。
+                if (isProbablyBinary(before.subarray(0, SNIFF_BYTES))) {
+                    return invalid(file, '是二进制文件,不能按文本追加(utf8 往返会损毁原有字节)。如需追加二进制请用 run_command。');
+                }
+                // 模型显式给了 hash 就用它校验(不匹配交给 dryRun 报 conflict);没给则用实际 hash ——
+                // append 是日志/分段生成的高频操作,强制「先 read_file 拿 hash」纯属负担,
+                // 正确性由提交前的 hash 比对保证(fail-loud),而非靠模型复述。
+                if (expectedHash === null)
+                    expectedHash = contentHash(before);
+                operation = 'update';
+                // 原样拼接,不自动补换行:尊重 shell `>>` 语义,不擅自改数据。
+                // 缺换行的黏行风险在 description 里显式告知模型(让它在 content 开头带 \n)。
+                replacement = before.toString('utf8') + content;
+            }
+            else {
+                operation = expectedHash === null ? 'create' : 'update';
+            }
+        }
         const result = await commitChangeSet(createChangeSet([
             {
                 path: file,
                 operation,
                 expectedHash,
-                replacement: content,
+                replacement,
             },
         ]), ctx?.signal);
         if (result.status === 'conflict') {
@@ -59,6 +152,8 @@ export const writeFileTool = {
             };
         }
         const summary = summarizeChangeSet(result.changeSet);
+        const verb = append ? '已追加到' : '已事务化写入';
+        const sizeNote = append ? `${content.length} 字符追加, 全文 ${replacement.length} 字符` : `${content.length} 字符`;
         return {
             status: 'success',
             code: 'OK',
@@ -67,7 +162,7 @@ export const writeFileTool = {
             changeSet: summary,
             output: result.changedFiles.length === 0
                 ? `文件 ${file} 内容未变化 (ChangeSet ${summary.id})。`
-                : `已事务化写入 ${file} (${content.length} 字符, ChangeSet ${summary.id}, sha256=${summary.changes[0]?.afterHash})。`,
+                : `${verb} ${file} (${sizeNote}, ChangeSet ${summary.id}, sha256=${summary.changes[0]?.afterHash})。`,
         };
     },
 };

package/dist/tools/constants.js

@@ -5,6 +5,13 @@ import { getActiveSkill } from '../skills/activation.js';
 export const MAX_FILE_LINES = 2000;
 export const MAX_OUTPUT = 20000;
 export const MAX_RESULTS = 100;
+/**
+ * read_file 命中图片分支时 output 的前缀。
+ *
+ * 放在 constants(叶子模块)而不是 builtins/read-file.ts:ui/render.ts 要用它把摘要
+ * 从「N 行」改成「图片已附加」,而 render.ts → builtins → registry 会绕出模块循环。
+ */
+export const IMAGE_READ_MARKER = '[image]';
 /** 进 history 的单条工具结果上限(字符)。push-time 第一层裁剪,保 head + 标记 + tail。 */
 export const MAX_HISTORY_RESULT = 8000;
 /** use_skill 结果(SKILL.md 正文)的放宽上限:指令须完整,中截会破坏语义。 */

package/dist/tools/policy.js

@@ -1,4 +1,4 @@
-import { ADD_TOOL_GROUPS_TOOL_NAME, COMMON_TOOL_NAMES, DEFAULT_ROUTE_GROUPS, TOOL_ROUTE_GROUP_NAMES, TOOL_ROUTE_GROUPS, getToolRouteGroupNames, isToolRouteGroupName, } from '../config/profiles.js';
+import { ADD_TOOL_GROUPS_TOOL_NAME, COMMON_TOOL_NAMES, DEFAULT_ROUTE_GROUPS, TOOL_ROUTE_GROUP_NAMES, TOOL_ROUTE_GROUPS, expandRouteImplications, getToolRouteGroupNames, isToolRouteGroupName, } from '../config/profiles.js';
 import { PLAN_DISABLED_TOOLS } from './constants.js';
 import { tools } from './registry.js';
 const clampConfidence = (value) => (Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0);
@@ -106,9 +106,10 @@ export class ToolPolicyController {
         this.confidence = clampConfidence(init.confidence ?? 0);
         const available = new Set(getAvailableToolRouteGroups(this.catalog, this.gateAllows));
         // 常驻簇无条件激活:路由漏判/失败都不会让主 Agent 起手就没有写文件或跑命令的能力。
+        // 蕴含簇(browser-debug → background-exec)在此一并展开,弱模型只选浏览器时也拿得到起服务的能力。
         const requested = process.env.MOCODE_TOOL_POLICY === 'full'
             ? available
-            : new Set([...DEFAULT_ROUTE_GROUPS, ...(init.groups ?? [])]);
+            : expandRouteImplications([...DEFAULT_ROUTE_GROUPS, ...(init.groups ?? [])]);
         for (const group of requested) {
             if (available.has(group))
                 this.selected.add(group);
@@ -176,38 +177,56 @@ export class ToolPolicyController {
     expand(rawGroups, reason) {
         const rejected = [];
         const added = [];
+        const implied = [];
         if (this.expansionCount >= this.maxExpansions) {
             return {
                 added,
+                implied,
                 rejected: ['expansion limit reached'],
                 snapshot: this.snapshot(false),
             };
         }
         const available = new Set(getAvailableToolRouteGroups(this.catalog, this.gateAllows));
+        /** 尝试激活一个簇;返回是否真的由本次调用新增。 */
+        const activate = (value) => {
+            if (!available.has(value))
+                return false;
+            if (this.selected.has(value))
+                return false;
+            this.selected.add(value);
+            return true;
+        };
         for (const value of rawGroups) {
             if (!isToolRouteGroupName(value)) {
                 rejected.push(`${String(value)}: unknown group`);
+                continue;
             }
-            else if (!available.has(value)) {
+            if (!available.has(value)) {
                 rejected.push(`${value}: capability disabled or unavailable`);
             }
             else if (this.selected.has(value)) {
                 rejected.push(`${value}: already active`);
             }
             else {
-                this.selected.add(value);
+                activate(value);
                 added.push(value);
+                // 蕴含簇静默带上:被 gate 否决或已激活都属正常,不进 rejected(不是模型的错)。
+                for (const impliedGroup of expandRouteImplications([value])) {
+                    if (impliedGroup !== value && activate(impliedGroup))
+                        implied.push(impliedGroup);
+                }
             }
         }
         if (added.length > 0) {
             this.expansionCount++;
             this.version++;
-            this.reason = reason.trim() || `Main agent added ${added.join(', ')}.`;
+            const gained = [...added, ...implied];
+            this.reason = reason.trim() || `Main agent added ${gained.join(', ')}.`;
             this.confidence = Math.max(this.confidence, 0.8);
             this.autoCache = null;
             this.planCache = null;
         }
-        return { added, rejected, snapshot: this.snapshot(false) };
+        return { added, implied, rejected, snapshot: this.snapshot(false) };
     }
     /** 注入请求尾部，不改写稳定 system prefix。 */
     reminder(planMode = false) {
@@ -218,7 +237,7 @@ export class ToolPolicyController {
             '## Tool route (current turn)',
             `Policy ${snapshot.id} v${snapshot.version}; active groups: ${active}.`,
             `Router reason: ${snapshot.reason}`,
-            'Use only the tools currently exposed. If a required capability is missing, call add_tool_groups alone; dependent calls must wait until the next step.',
+            'Use only the exposed tools. Missing capability? Call add_tool_groups alone; dependent calls wait for the next step.',
         ];
         if (remaining.length)
             lines.push(`Groups still available: ${remaining.join(', ')}.`);

package/dist/tools/router.js

@@ -1,7 +1,7 @@
 import { chat } from '../llm/index.js';
 import { COMMON_TOOL_NAMES, DEFAULT_ROUTE_GROUPS, TOOL_ROUTE_GROUPS, isToolRouteGroupName, } from '../config/profiles.js';
 import { getRoutableToolRouteGroups, toolRouteCatalog } from './policy.js';
-import { getRouterMode, getJevRouterConfig, isJevRouterConfigured } from '../config/index.js';
+import { getRouterMode, getJevRouterConfig, isJevRouterConfigured, isToolRoutingEnabled } from '../config/index.js';
 import { askJev } from './jev-client.js';
 const ROUTER_TOOL_NAME = 'select_tool_groups';
 const MAX_ROUTER_INPUT_CHARS = 12_000;
@@ -89,6 +89,8 @@ function parseDecision(raw, available, previousGroups, startedAt) {
  *   - `jev`:TypeSafe systemone,每组独立出 0~1 概率,按阈值出簇(阈值可调是选它的核心理由)。
  * 两条路径失败都沿用上一 turn 的簇;主 Agent 仍可通过 add_tool_groups 自救,
  * 但绝不因路由失败直接暴露 full 工具集。
+ * 总开关(/router off,MOCODE_ROUTER_ENABLED=false):跳过路由调用,只保留常驻簇
+ * (controller 无条件激活的 DEFAULT_ROUTE_GROUPS)+ 通用工具,不再选任何额外簇。
  */
 export async function routeToolGroups(request) {
     const startedAt = Date.now();
@@ -97,6 +99,18 @@ export async function routeToolGroups(request) {
     const availableGroups = getRoutableToolRouteGroups(request.tools, request.gateAllows);
     const available = new Set(availableGroups);
     const previousGroups = (request.previousGroups ?? []).filter((group) => available.has(group));
+    // 总开关关闭:不发任何路由请求。groups 置空 → controller 只保留常驻簇 + 通用工具,
+    // 缺的能力模型仍可 add_tool_groups 自救。fallback 标记让 metadata 能区分「真路由」与「开关直通」。
+    if (!isToolRoutingEnabled()) {
+        return {
+            groups: [],
+            inheritPrevious: false,
+            confidence: 0,
+            reason: 'Tool pre-routing is disabled (/router off); common tools plus default groups only.',
+            latencyMs: Date.now() - startedAt,
+            fallback: true,
+        };
+    }
     if (availableGroups.length === 0) {
         return fallbackDecision(startedAt, [], `No routable tool groups are currently available; using common tools plus always-on ${DEFAULT_ROUTE_GROUPS.join(', ')}.`);
     }
@@ -191,9 +205,10 @@ ${request.tools ? toolRouteCatalog(availableGroups, request.tools) : toolRouteCa
 
 Routing rules:
 - You MUST call ${ROUTER_TOOL_NAME} exactly once and emit no prose.
-- File edits and command execution are always available; do NOT select them. If common tools plus the always-on groups suffice (most coding, testing, and debugging tasks), return an empty groups array.
+- File edits and foreground command execution are always available; do NOT select them. If common tools plus the always-on groups suffice (most coding, testing, and debugging tasks), return an empty groups array.
 - Select multiple groups when the task genuinely combines capabilities.
-- Web UI DOM/console/network/page sessions or local web servers need browser-debug.
+- background-exec is for any process that must keep running after the tool call returns: dev servers, inference/model services, watchers, log tails, or a command you will poll later. Foreground run_command blocks and is killed at its timeout, so it cannot host them.
+- Web UI DOM/console/network/page sessions need browser-debug; a local web server alone only needs background-exec.
 - Merely observing system dialogs or non-browser windows needs desktop-observe.
 - computer-control requires explicit real GUI clicking, typing, scrolling, or desktop application operation; never infer it from the word "browser" alone.
 - memory-write requires explicit intent to remember, update, forget, or link cross-session knowledge.
@@ -205,7 +220,8 @@ Routing rules:
 Examples (text form; always answer with the ${ROUTER_TOOL_NAME} call):
 - Task "这个仓库用什么测试框架?该怎么加一个新测试?" → groups: [], inheritPrevious: false, reason: "Pure question; common read/search tools suffice."
 - Task "修好 auth.ts 里过期的 token 校验并跑一遍相关测试" → groups: [], inheritPrevious: false, reason: "File edits and test runs are always-on groups, never selected."
-- Task "本地页面白屏了,帮我看看控制台报错" → groups: [browser-debug], inheritPrevious: false, reason: "Needs DOM/console inspection of a local web page."
+- Task "把 8765 端口的推理服务起起来,然后拿它的 /predict 试几个样本" → groups: [background-exec], inheritPrevious: false, reason: "A long-running service must stay alive across calls so it can be polled and stopped later."
+- Task "本地页面白屏了,帮我看看控制台报错" → groups: [background-exec, browser-debug], inheritPrevious: false, reason: "Needs the dev server running plus DOM/console inspection of a local web page."
 - Task "记住这条约定:提交前必须跑 lint" → groups: [memory-write], inheritPrevious: false, reason: "Explicit intent to persist cross-session knowledge."`;
     const user = [
         `Current mode: ${request.planMode ? 'PLAN (route final task needs; execution will still be read-only)' : 'AUTO'}`,