mocode-ai 1.6.0 → 1.6.2

package/dist/agent/model-turn.js

@@ -101,18 +101,17 @@ export async function runModelTurn(input) {
         const ephemeralReminder = [
             runPolicy.reminder,
             !opts.suppressOpeningAnalysis && step === 0
-                ? '## Opening analysis\nBegin your FIRST response of this turn with a brief analysis of the request and your planned approach (1-3 sentences, no filler), THEN start tool calls. This opening is the only place where pre-tool prose is expected; after it, work quietly with no narration between tool calls.'
+                ? '## Opening analysis\nStart your first response of this turn with a brief analysis of the request and approach (1-3 sentences, no filler), then start tool calls. This is the only expected pre-tool prose; afterwards work quietly, no narration between calls.'
                 : '',
             historyRebuilt
-                ? '## Post-compaction recovery\n' +
-                    'Context was compacted before this request. Recover before doing anything else, in this order:\n' +
-                    '1. Read the session summary at the top of the history: `## Completed` is already done — do not redo or re-verify it. `## In Progress` / `## Next Steps` tell you exactly where work stopped and what is next.\n' +
-                    '2. Read `## Session state` below (refreshed every step from notes.md / gui-actions.log): the active plan is authoritative — `[x]` steps are finished, resume from the first `[ ]`. A `## Compaction Snapshot` section there is the progress checkpoint written at this compaction. A `## GUI actions` section lists every GUI action already performed with its observed result: do not repeat an action that appears there, unless the latest screenshot contradicts it (then the screenshot wins — treat that line as attempted but unverified).\n' +
+                ? '## Post-compaction recovery\nContext was compacted before this request. Recover first, in this order:\n' +
+                    '1. Read the session summary at the top of the history: `## Completed` is done — do not redo or re-verify it; `## In Progress` / `## Next Steps` say where work stopped and what is next.\n' +
+                    '2. Read `## Session state` below (refreshed from notes.md / gui-actions.log): the active plan is authoritative — `[x]` steps are done, resume from the first `[ ]`. `## Compaction Snapshot` is the checkpoint written at this compaction. `## GUI actions` lists every GUI action already performed with its result: do not repeat one that appears there, unless the latest screenshot contradicts it (the screenshot wins — treat that line as attempted but unverified).\n' +
                     (sessionStateText
                         ? ''
-                        : '(No active plan or snapshot was found in notes.md — reconstruct what is done purely from the summary and treat its `## Completed` as ground truth.)\n') +
-                    '3. Before any file edit, read_file the target fresh to get the current content hash — never edit from memory of pre-compaction content.\n' +
-                    '4. Before re-running a search/read you think you already did, check the summary and notes first: only repeat it if the result is genuinely missing or the target has changed.'
+                        : '(No active plan or snapshot in notes.md — reconstruct progress from the summary; treat its `## Completed` as ground truth.)\n') +
+                    '3. Before any file edit, read_file the target fresh for its current hash — never edit from pre-compaction memory.\n' +
+                    '4. Before re-running a search/read you think you already did, check the summary and notes first; repeat only if the result is genuinely missing or the target changed.'
                 : '',
             sessionStateText,
         ]

package/dist/agent/run-coordinator.js

@@ -429,6 +429,9 @@ export async function runAgentCoreLegacy(opts, historyManager, stages) {
                                                 succeeded
                                                     ? `Tool policy expanded to v${expansion.snapshot.version}; added groups: ${expansion.added.join(', ')}.`
                                                     : `Tool policy was not expanded (still v${expansion.snapshot.version}).`,
+                                                expansion.implied.length > 0
+                                                    ? `Implied groups also activated: ${expansion.implied.join(', ')}.`
+                                                    : '',
                                                 expansion.rejected.length > 0 ? `Rejected: ${expansion.rejected.join('; ')}.` : '',
                                                 succeeded ? 'The added tool schemas become available on the next model step.' : '',
                                             ]
@@ -448,6 +451,7 @@ export async function runAgentCoreLegacy(opts, historyManager, stages) {
                                                 toVersion: expansion.snapshot.version,
                                                 requestedGroups: parsed.groups.map(String),
                                                 addedGroups: expansion.added,
+                                                impliedGroups: expansion.implied,
                                                 rejected: expansion.rejected,
                                                 reason: parsed.reason,
                                                 status: outcome.status,

package/dist/agent/stages/tool-dispatcher.js

@@ -138,6 +138,7 @@ class LegacyCompatibleToolDispatcher {
                         succeeded
                             ? `Tool policy expanded to v${expansion.snapshot.version}; added groups: ${expansion.added.join(', ')}.`
                             : `Tool policy was not expanded (still v${expansion.snapshot.version}).`,
+                        expansion.implied.length > 0 ? `Implied groups also activated: ${expansion.implied.join(', ')}.` : '',
                         expansion.rejected.length > 0 ? `Rejected: ${expansion.rejected.join('; ')}.` : '',
                         succeeded ? 'The added tool schemas become available on the next model step.' : '',
                     ]

package/dist/agent/tool-turn.js

@@ -8,7 +8,7 @@ const PLAN_NAG_TEXT = '[mocode] Reminder: you have an active plan in notes.md bu
  * 「工具回灌的屏幕帧」与「用户粘贴的图」——两边各写一份字符串会让识别规则悄悄失效。
  * 新增附件产出点**必须**复用这一个前言。
  */
-export const ATTACHMENT_PREAMBLE = 'The view_image tool loaded the following visual input: ';
+export const ATTACHMENT_PREAMBLE = 'The read_file tool loaded the following visual input: ';
 /** Owns tool-turn history publication, transaction settlement, plan nag, attachments and checkpoint ordering. */
 export async function runToolTurn(input) {
     const { opts, ctx, historyManager, result, stream, step, maxSteps, planState, turnLifecycle, cancellationLifecycle, terminationPolicy, rebuildHistoryIndexes, dispatch, } = input;

package/dist/attachments/image.js

@@ -2,6 +2,7 @@ import { readFile, stat } from 'node:fs/promises';
 import { basename, extname } from 'node:path';
 import { createHash } from 'node:crypto';
 import { jailResolve } from '../sandbox/jail.js';
+import { decodePng, downscale, encodePng } from '../runtime/screen-pipeline.js';
 export const MAX_INLINE_BYTES_DEFAULT = 4 * 1024 * 1024;
 const MIME_BY_EXT = {
     '.png': 'image/png',
@@ -13,6 +14,40 @@ const MIME_BY_EXT = {
 export function detectMime(p) {
     return MIME_BY_EXT[extname(p).toLowerCase()] ?? null;
 }
+/**
+ * 按**魔数**判定图片类型(不看扩展名)。
+ *
+ * 为什么必须有这条:扩展名会说谎——`data.bin` 可能是 PNG,`notes.png` 也可能是文本。
+ * read_file 要靠它决定「走文本行号分页」还是「走视觉通道」,判错的代价是把二进制
+ * 当 UTF-8 解码(实测一张 42KB PNG 解码出 17862 个 U+FFFD,占 45%)灌进 history。
+ */
+export function sniffImageMime(buf) {
+    if (buf.length >= 8 && buf[0] === 0x89 && buf.toString('ascii', 1, 8) === 'PNG\r\n\x1a\n')
+        return 'image/png';
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff)
+        return 'image/jpeg';
+    if (buf.length >= 6 && buf.toString('ascii', 0, 6) === 'GIF87a')
+        return 'image/gif';
+    if (buf.length >= 6 && buf.toString('ascii', 0, 6) === 'GIF89a')
+        return 'image/gif';
+    // WebP: RIFF....WEBP
+    if (buf.length >= 12 && buf.toString('ascii', 0, 4) === 'RIFF' && buf.toString('ascii', 8, 12) === 'WEBP') {
+        return 'image/webp';
+    }
+    return null;
+}
+/**
+ * 二进制嗅探:头部 4KB 含 C0 控制字符(NUL/BEL/ESC 等,放行 \t\n\r)即视为二进制。
+ *
+ * 与 grep 的 BINARY_PROBE_RE 同源同口径(集中在此,避免两处正则漂移):SQLite、压缩包、
+ * 可执行文件、minified 数据 dump 都会命中。用途是让 read_file 明确拒绝并指路,
+ * 而不是把乱码塞进上下文——那既烧 token 又让模型基于垃圾内容做判断。
+ */
+export const BINARY_PROBE_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
+export function isProbablyBinary(head) {
+    const sample = typeof head === 'string' ? head : head.toString('latin1');
+    return BINARY_PROBE_RE.test(sample.slice(0, 4096));
+}
 function formatBytes(n) {
     if (n < 1024)
         return `${n} B`;
@@ -23,11 +58,93 @@ function formatBytes(n) {
 export function renderChip(att) {
     return `📷 ${att.name} (${formatBytes(att.bytes)})`;
 }
+/** 降采样兜底的长边上界:对齐主流视觉模型的原生分辨率(Claude 1568 / OpenAI 高分块同级)。 */
+export const DOWNSCALE_MAX_EDGE = 1568;
+/**
+ * 读图 + 超限自动降采样兜底。
+ *
+ * 为什么要兜底:4 MiB 内联上限对高 DPI 截图偏紧(一张 4K Retina PNG 轻松 5-8 MiB)。
+ * 直接拒绝会逼模型去找压缩工具/改用户文件,而**服务端缩一下就能成功**。
+ * screenshot 早有这条路径(screenshot.ts 的 FALLBACK_MAX_EDGE 分支),这里抽成共享 helper,
+ * 让 read_file 图片通道(原 view_image,已并入)同样受益。
+ *
+ * 能力边界(诚实声明):`runtime/screen-pipeline.ts` 的 PNG 解码是手写的、只支持
+ * **8-bit RGB/RGBA PNG**(项目刻意零原生图像依赖)。所以兜底只覆盖 PNG;
+ * JPEG/WebP/GIF 超限仍然拒绝,reason 会写明这一点。
+ */
+export async function loadImageAttachmentWithDownscale(input, opts) {
+    const loaded = await loadImageAttachment(input, opts);
+    if (loaded.ok)
+        return loaded;
+    // 只有「体积超限」这一种失败值得兜底:路径为空/扩展名不支持/沙箱越界/不是普通文件
+    // 都是真错误,缩图解决不了,原样透出让调用方给出准确提示。
+    if (!loaded.reason.startsWith('too large'))
+        return loaded;
+    const mime = detectMime(input) ?? opts.sniffedMime ?? null;
+    if (mime !== 'image/png') {
+        return {
+            ok: false,
+            reason: `${loaded.reason} — 自动降采样仅支持 PNG(零原生图像依赖);${extname(input)} 请先转成 PNG 或自行压缩后重试`,
+        };
+    }
+    let abs;
+    try {
+        abs = jailResolve(input.trim());
+    }
+    catch (e) {
+        return { ok: false, reason: `outside sandbox: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    try {
+        const png = decodePng(await readFile(abs));
+        const { img } = downscale(png, DOWNSCALE_MAX_EDGE);
+        const buf = encodePng(img);
+        if (buf.length > opts.maxBytes) {
+            return {
+                ok: false,
+                reason: `${loaded.reason} — 降采样到 ${img.width}×${img.height} 后仍有 ${formatBytes(buf.length)},超过 ${formatBytes(opts.maxBytes)}`,
+            };
+        }
+        let st;
+        try {
+            st = await stat(abs);
+        }
+        catch {
+            st = null;
+        }
+        const id = createHash('sha1')
+            .update(abs)
+            .update('\0downscaled')
+            .update(String(img.width))
+            .update('\0')
+            .update(String(img.height))
+            .update('\0')
+            .update(String(st?.mtimeMs ?? 0))
+            .digest('hex');
+        return {
+            ok: true,
+            downscaledFrom: { width: png.width, height: png.height },
+            att: {
+                id,
+                path: abs,
+                name: basename(abs),
+                bytes: buf.length,
+                mime: 'image/png',
+                dataUrl: `data:image/png;base64,${buf.toString('base64')}`,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, reason: `${loaded.reason}(降采样兜底失败: ${message})` };
+    }
+}
 export async function loadImageAttachment(input, opts) {
     const trimmed = input.trim();
     if (!trimmed)
         return { ok: false, reason: '路径为空' };
-    const mime = detectMime(trimmed);
+    // 扩展名优先(便宜、无需读文件);不认识时用调用方给的魔数嗅探结果兜底 ——
+    // read_file 读到的图片常常没有正确扩展名(截图缓存 / 构建产物 / 无扩展名 blob)。
+    const mime = detectMime(trimmed) ?? opts.sniffedMime ?? null;
     if (!mime) {
         return { ok: false, reason: `unsupported: ${extname(trimmed) || '(无扩展名)'} — 仅支持 png/jpg/jpeg/gif/webp` };
     }
@@ -52,7 +169,7 @@ export async function loadImageAttachment(input, opts) {
     if (st.size > opts.maxBytes) {
         return {
             ok: false,
-            reason: `too large: ${formatBytes(st.size)} (max ${formatBytes(opts.maxBytes)}) — TODO: URL upload not yet supported`,
+            reason: `too large: ${formatBytes(st.size)} (max ${formatBytes(opts.maxBytes)})`,
         };
     }
     const buf = await readFile(abs);

package/dist/config/index.js

@@ -12,6 +12,9 @@ import { detectLanguage, setLanguage, t } from '../i18n/index.js';
 import { isProfileName, profileHasGroup } from './profiles.js';
 // 端点常量归协议实现方(jev-client.ts,纯叶子无 import,不引入环);此处只引用不重定义。
 import { DEFAULT_JEV_BASE_URL } from '../tools/jev-client.js';
+// shell.ts 是纯叶子(只 import node 内置):PLATFORM_NOTE 的措辞必须跟 run_command/dev_server
+// 实际 spawn 的默认 shell 一致,单一事实源,防「文案说 cmd、实际跑 bash」漂移。
+import { defaultShellKind } from '../runtime/shell.js';
 /**
  * 按优先级加载配置文件并回填 process.env:
  *   候选(后者覆盖前者,优先级升序):<cwd>/.env(兼容旧用法,最低)→ ~/.mocode/config(全局)→ <cwd>/.mocode/config(项目级覆盖,最高)。
@@ -95,9 +98,17 @@ export function isModelConfigured() {
     return !!config.baseURL && !!config.apiKey;
 }
 const PLATFORM_NOTE = (() => {
+    const shell = defaultShellKind();
+    if (process.platform === 'win32' && shell === 'cmd') {
+        return `- This is Windows: \`run_command\`/\`dev_server\` default to \`cmd.exe /c\` — use cmd syntax and \`%VAR%\`; Unix builtins and command substitution are unavailable.
+- Non-interactive cmd cannot run \`timeout /t\` (it errors out); pass \`shell: "powershell"\` with \`Start-Sleep\`, or \`shell: "bash"\` with \`sleep\`, when a wait is needed.
+- Prefer read_file/glob/grep for file discovery and reading. When a POSIX shell fits better, pass \`shell: "bash"\` (Git Bash, auto-detected) or \`shell: "powershell"\`; never mix syntaxes within one command.`;
+    }
     if (process.platform === 'win32') {
-        return `- This is Windows: \`run_command\` uses \`cmd.exe /c\` — use cmd syntax and \`%VAR%\`; Unix builtins and command substitution are unavailable.
-- Prefer read_file/glob/grep for file discovery and reading. When shell is necessary, use forward-slash paths or invoke PowerShell explicitly.`;
+        // MOCODE_SHELL 翻转了默认:措辞必须跟着变,否则模型按文案写 cmd 语法却落进 bash。
+        return `- This is Windows: \`run_command\`/\`dev_server\` default to ${shell} (MOCODE_SHELL override) — use ${shell === 'bash' ? 'POSIX syntax ($VAR, &&, forward-slash paths)' : 'PowerShell syntax ($VAR, Start-Sleep)'}.
+- cmd-only syntax (\`%VAR%\`, \`start /b\`, \`dir\`) needs an explicit \`shell: "cmd"\`; do not mix syntaxes within one command.
+- Prefer read_file/glob/grep for file discovery and reading; reach for the shell only when a dedicated tool does not fit.`;
     }
     if (process.platform === 'darwin') {
         return `- This is macOS: \`run_command\` uses bash with BSD utilities. Prefer read_file/glob/grep; account for BSD/GNU differences when shell commands are necessary.`;
@@ -311,7 +322,7 @@ export function buildSessionStateReminder(sessionId = getCurrentSessionId()) {
     const sources = [notes || plan ? 'notes.md' : '', guiActions ? 'gui-actions.log' : ''].filter(Boolean).join(' + ');
     const parts = [
         `## Session state (current, from ${sources})`,
-        'This block mirrors the live session state and is refreshed every step; treat it as authoritative, and ignore any older copy earlier in this conversation.',
+        'Mirrors live session state, refreshed every step; authoritative — ignore older copies earlier in this conversation.',
         ...(plan ? [plan] : []),
         ...(notes ? [notes] : []),
         ...(guiActions ? [guiActions] : []),
@@ -320,23 +331,69 @@ export function buildSessionStateReminder(sessionId = getCurrentSessionId()) {
 }
 /** AGENTS.md 自动导入正文上限:system 位于 history[0] 且 compactHistory 不压缩 system,超长需截断防占窗口(见 memory/README.md)。 */
 const MAX_AGENTS_IMPORT_CHARS = 20000;
+/**
+ * 不常驻注入的章节(压成指针行,read_file 按需取全文):
+ * - 目录结构 / Directory structure / Project layout —— 架构探索任务用 codegraph/探查工具现查更准;
+ * - 扩展点 / Extension points —— 只在「加新工具/命令/模块」类任务才需要,恰好是 skill 的定义。
+ * 常驻价值密度最高的「项目/命令/约定」(市场实证 arXiv 2511.12884:build/run 62.3%、conventions 主流)全文保留。
+ * 章节标题大小写不敏感,兼容英文写法的 AGENTS.md。
+ */
+const AGENTS_INJECTION_INDEX_SECTIONS = [
+    '目录结构',
+    '扩展点',
+    'directory structure',
+    'project layout',
+    'extension points',
+];
+/**
+ * AGENTS.md 按章节过滤注入:命中 {@link AGENTS_INJECTION_INDEX_SECTIONS} 的 H2 章节整段压缩成一行指针,
+ * 其余章节(preamble、## 项目、## 命令、## 约定及未知章节)逐字保留。
+ * H1 及更深层级不动;空文件/无章节文件原样返回。导出供单测直接断言。
+ */
+export function filterAgentsSectionsForInjection(content) {
+    const lines = content.split('\n');
+    const out = [];
+    let inIndexedSection = false;
+    for (const line of lines) {
+        const h2 = /^##\s+(.*)$/.exec(line);
+        if (h2) {
+            const title = h2[1].trim().toLowerCase();
+            // 前缀匹配容忍「目录结构(monorepo)」「Directory Structure — monorepo」等后缀写法;
+            // 仅当后缀紧邻(空格/括号/冒号/破折号)时命中,避免误伤「约定与目录结构习惯」这类反向词序。
+            inIndexedSection = AGENTS_INJECTION_INDEX_SECTIONS.some((s) => title === s || new RegExp(`^${s}[\\s(:\\u2014\\uff08\\(]`).test(title));
+            if (inIndexedSection) {
+                out.push(`- ${h2[1].trim()}: (not injected — read_file AGENTS.md on demand)`);
+                continue;
+            }
+        }
+        if (!inIndexedSection)
+            out.push(line);
+    }
+    return out.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
 /**
  * 工作区根 AGENTS.md 自动导入段:与 memory 开关完全无关——
  * 只要 <cwd>/AGENTS.md 存在就把正文直接拼进 prompt(超 {@link MAX_AGENTS_IMPORT_CHARS} 截断+末尾提示),
  * 不再只指路让模型按需 read_file。读失败静默跳过(返空串)。
+ *
+ * 瘦身(方案A):目录结构/扩展点两章节不常驻,压成指针行——模型真做架构/扩展任务时
+ * 一次 read_file 取全文(渐进披露,与 Skills 清单同构);截断上限作用于过滤后的正文。
  */
 function buildAgentsImportSection() {
     try {
         const projectAgents = path.join(process.cwd(), 'AGENTS.md');
         if (!fs.existsSync(projectAgents))
             return '';
-        const content = fs.readFileSync(projectAgents, 'utf8').trim();
-        if (!content)
+        const raw = fs.readFileSync(projectAgents, 'utf8').trim();
+        if (!raw)
             return '';
-        const body = content.length > MAX_AGENTS_IMPORT_CHARS
-            ? `${content.slice(0, MAX_AGENTS_IMPORT_CHARS)}\n…[AGENTS.md truncated: first ${MAX_AGENTS_IMPORT_CHARS} characters injected]`
-            : content;
-        return `\n## Project memory (AGENTS.md, auto-imported)\n${body}\n- AGENTS.md may be stale: current code and the user request override stale memory.`;
+        const filtered = filterAgentsSectionsForInjection(raw);
+        const body = filtered.length > MAX_AGENTS_IMPORT_CHARS
+            ? `${filtered.slice(0, MAX_AGENTS_IMPORT_CHARS)}\n…[AGENTS.md truncated: first ${MAX_AGENTS_IMPORT_CHARS} characters injected]`
+            : filtered;
+        return (`\n## Project memory (AGENTS.md, auto-imported)\n${body}\n` +
+            '- AGENTS.md may be stale: current code and the user request override stale memory.\n' +
+            '- Discovered a stable, non-obvious project fact worth persisting? write_file(append=true) one line to `.mocode/agents-draft.md`; the user merges drafts into AGENTS.md via /init.');
     }
     catch {
         return ''; // 读失败静默跳过:不让导入破坏 prompt 构建
@@ -387,14 +444,14 @@ export function buildBasePrompt(sessionId = getCurrentSessionId()) {
     // 回复语言不写入提示词:模型按用户当轮提问语言自动识别(Voice 段的
     // "Match the user's style and language" 已覆盖),/language 只切换终端 UI 文案。
     const staticBody = `## Identity
-You are mocode, a terminal coding agent.
+You are mocode, a terminal coding agent created by Wan Engineer.
 
 ## Core behavior
 Complete programming tasks through an "analyze → call tool → observe result → decide next step" loop until solved.
 
 ## Modes
-- AUTO is the default: investigate and complete the task with the tools currently exposed.
-- PLAN is read-only research and design; do not make changes until the user approves and switches back to AUTO.
+- AUTO (default): complete tasks with the tools currently exposed.
+- PLAN: read-only design; no changes until the user approves and switches back.
 
 ## Workflow
 - Understand: use existing conversation and tool evidence before gathering more.
@@ -412,12 +469,12 @@ ${buildWorkDisciplineSection(inferModelFamily(config.model))}
 ## Tool policy
 - Silent Execution: invoke tools directly without preamble. Output visible text ONLY for the final answer and critical mid-task findings. Strictly no step-by-step narration (no "let me…", "让我先…", "now checking…" between calls).
 - Go directly to a known path or symbol; use discovery tools only when the location is unknown.
-- Edit against a FRESH read: before any edit_file/write_file, call read_file on the exact path and copy both its latest hash and the exact target text. Never reconstruct old_string from a grep/summary/diff — those lose whitespace and indentation and cause edit failures.
+- Edit against a FRESH read: before any edit_file or a replacing write_file, call read_file on the exact path and copy both its latest hash and the exact target text. Never reconstruct old_string from a grep/summary/diff — those lose whitespace and indentation and cause edit failures. (write_file with append=true is the exception: it reads and hashes the file itself, so no prior read_file and no expected_hash are needed.)
 - A read_file hash from before a compaction, session resume, edit conflict, or external change is STALE and will be rejected — re-read rather than reuse an old hash.
 - Emit multiple independent tool calls in ONE assistant message so they run concurrently — e.g. several read_file regions, a grep plus a glob, or several web_fetch calls. One lookup per message wastes a full model round-trip each time. Place parallel-safe calls consecutively; keep any call that depends on their results (e.g. an edit) for the next message.
 - Never batch a read with an edit that depends on it; do not repeat overlapping reads or unchanged failed calls.
 - On failure, inspect the full error, change the approach, and retry only with a reason. Drop stale tool output when it no longer supports the task.
-- For generated content over roughly 200 lines or 5K tokens, use small staged writes rather than one oversized tool argument.
+- For generated content over roughly 200 lines or 5K tokens, write it in stages: first write_file the initial chunk, then extend it with write_file(append=true, content=<next chunk>) — each call stays small and the file grows transactionally. Appends are VERBATIM: if the file does not already end with a newline, begin your chunk with "\\n" so lines do not merge.
 
 ## Environment
 ${PLATFORM_NOTE}
@@ -803,6 +860,19 @@ export function getRouterMode() {
 export function updateRouterMode(mode) {
     process.env.MOCODE_ROUTER_MODE = mode;
 }
+/**
+ * 工具预路由总开关。关闭 = 每个 turn 跳过路由调用,只保留常驻簇
+ * (controller 无条件激活的 DEFAULT_ROUTE_GROUPS)+ 通用工具,不选任何额外簇;默认开启。
+ * 与 RouterMode 同一理由直接读写 process.env:支持 /router on|off 即时切换,
+ * routeToolGroups 在每 turn 调用点实时读,改后下一真实用户 turn 生效。
+ */
+export function isToolRoutingEnabled() {
+    return process.env.MOCODE_ROUTER_ENABLED !== 'false';
+}
+/** /router 的写入口;持久化由调用方写 MOCODE_ROUTER_ENABLED(见 config/file.ts)。 */
+export function updateToolRoutingEnabled(enabled) {
+    process.env.MOCODE_ROUTER_ENABLED = enabled ? 'true' : 'false';
+}
 function readNumberEnv(name, fallback) {
     const raw = process.env[name];
     if (raw === undefined || raw.trim() === '')

package/dist/config/profiles.js

@@ -5,25 +5,28 @@
  */
 /**
  * 工具簇 → 工具名。新增工具时归到对应簇;一个工具只属一个簇。
- * view_image 放 core-read,保证所有模式都能读取已有本地图片;工具产生的即时视觉结果通过
- * modelAttachments 直接回灌,不依赖 view_image。screenshot 留 frontend(抓整个桌面,隐私敏感,
- * 主要服务前端联调)。
+ * 图片读取由 read_file 的魔数嗅探分支覆盖(原 view_image 已并入):文本/图片分流,
+ * 工具产生的即时视觉结果通过 modelAttachments 直接回灌。screenshot 留 frontend(抓整个
+ * 桌面,隐私敏感,主要服务前端联调)。
+ * dev_server 归 core-write 而非 frontend:它是「后台进程管理」能力(与 run_command 同级),
+ * 不是浏览器工具,不该受 MOCODE_FRONTEND_TOOLS_ENABLED 否决。与自动路由的 background-exec
+ * 组(无 gateEnv)语义对齐。
  */
 export const TOOL_GROUPS = {
-    'core-read': ['read_file', 'view_image', 'glob', 'grep'],
-    'core-write': ['write_file', 'edit_file', 'run_command'],
+    'core-read': ['read_file', 'glob', 'grep'],
+    'core-write': ['write_file', 'edit_file', 'run_command', 'dev_server'],
     'agent-meta': ['plan_update', 'note_append', 'ask_human', 'use_skill', 'run_skill'],
     web: ['web_search', 'web_fetch'],
-    frontend: ['browser', 'dev_server', 'screenshot'],
+    frontend: ['browser', 'screenshot'],
     computer: ['computer'],
     memory: ['memory_save', 'memory_search', 'memory_list', 'memory_update', 'memory_forget', 'memory_graph'],
     subagent: ['sub-agent'],
 };
 // ── LLM 自动工具路由 ──────────────────────────────────────────────────────
-/** 主 Agent 每一步都可见的低风险、高复用工具。 */
+/** 主 Agent 每一步都可见的低风险、高复用工具。
+ *  图片读取并入 read_file(魔数嗅探分流,原 view_image 已移除)。 */
 export const COMMON_TOOL_NAMES = [
     'read_file',
-    'view_image',
     'glob',
     'grep',
     'web_search',
@@ -52,9 +55,18 @@ export const TOOL_ROUTE_GROUPS = {
         tools: ['run_command'],
         description: 'Run tests, builds, linters, Git, package managers, logs, diagnostics, and foreground commands.',
     },
+    // dev_server 从 browser-debug 拆出:它的能力是「跨工具调用存活的后台进程 + 日志 + 树杀」,
+    // 服务对象远不止前端联调(推理服务、watcher、log tail、任意长驻命令)。留在 browser-debug 时
+    // 受 MOCODE_FRONTEND_TOOLS_ENABLED 否决、且组描述只提 DOM/console,路由 LLM 对「起个服务」
+    // 类任务几乎不会选它 —— 模型于是退回 run_command 前台阻塞(120s 超时)或 start /b 脱离启动,
+    // 之后既拿不到日志也没法优雅 kill。故独立成组且**无 gateEnv**:与 shell-debug 同级、永远可路由。
+    'background-exec': {
+        tools: ['dev_server'],
+        description: 'Run any long-running background process that must outlive a single tool call — dev servers, inference/model services, watchers, log tails, message queues. Provides process id, incremental log reads, readiness wait, and process-tree termination.',
+    },
     'browser-debug': {
-        tools: ['browser', 'dev_server'],
-        description: 'Start local development servers and debug web UIs through DOM, console, network, and page sessions.',
+        tools: ['browser'],
+        description: 'Debug web UIs through DOM, console, network, and page sessions in a real browser.',
         gateEnv: 'MOCODE_FRONTEND_TOOLS_ENABLED',
     },
     'desktop-observe': {
@@ -89,6 +101,26 @@ export const TOOL_ROUTE_GROUPS = {
     },
 };
 export const TOOL_ROUTE_GROUP_NAMES = Object.keys(TOOL_ROUTE_GROUPS);
+/**
+ * 簇蕴含关系:选中 key 簇时自动带上 value 里的簇(仍受各自 gateEnv 否决)。
+ *
+ * 存在的理由是「能力半截」比「能力多余」更贵:browser-debug 只给浏览器,而被调试的页面
+ * 得先有人把它跑起来。弱模型只选 browser-debug 时,它要么白付一个 step 去 add_tool_groups
+ * 扩容 background-exec,要么退回 run_command 前台起服务(120s 超时被杀 / 拿不到日志)。
+ * 蕴含在 policy 层解析,router 的 Examples 仍要求显式列出两者(让强模型学会正确归因)。
+ */
+export const TOOL_ROUTE_IMPLICATIONS = {
+    'browser-debug': ['background-exec'],
+};
+/** 展开蕴含:传入簇集合 → 并上其蕴含簇。纯函数、幂等(蕴含不再递归展开第二层)。 */
+export function expandRouteImplications(groups) {
+    const out = new Set(groups);
+    for (const group of [...out]) {
+        for (const implied of TOOL_ROUTE_IMPLICATIONS[group] ?? [])
+            out.add(implied);
+    }
+    return out;
+}
 /**
  * 常驻工具簇:每个 turn 无条件激活,不经过 LLM 路由(路由只需在「可用簇 − 常驻簇」里挑)。
  * 入选标准:高频(coding agent 多数 turn 都要)+ 低暴露成本(工具少、schema 短)+ 漏判代价高

package/dist/context/encoders/search.js

@@ -1,6 +1,9 @@
 const LEGACY_GREP_RE = /^(.*?):(\d+):(.*)$/;
 const STRUCTURED_HEADER_RE = /^(.*): (\d+) 处匹配,行号 \[([0-9,\s]+)\]$/;
-const STRUCTURED_BODY_RE = /^\s{2}L\d+:/;
+/** body 行:命中 `  L12:` / 上下文 `  L11-`(grep.ts renderBodies 的两种前缀)。 */
+const STRUCTURED_BODY_RE = /^\s{2}L\d+[:-]/;
+/** 不相邻分块分隔符 `  --`(对齐 ripgrep)。Cold 折叠时与 body 一并丢弃。 */
+const STRUCTURED_SEPARATOR_RE = /^\s{2}--$/;
 const STRUCTURED_FOLDED_RE = /^\s{2}\(body 已折叠/;
 function isAgedCold(input) {
     return input.phase === 'sweep' && input.isCold === true && (input.age ?? 0) >= 2;
@@ -18,7 +21,8 @@ function collapseStructuredGrep(output) {
             out.push(line);
             continue;
         }
-        if (inFile && (STRUCTURED_BODY_RE.test(line) || STRUCTURED_FOLDED_RE.test(line))) {
+        if (inFile &&
+            (STRUCTURED_BODY_RE.test(line) || STRUCTURED_SEPARATOR_RE.test(line) || STRUCTURED_FOLDED_RE.test(line))) {
             continue;
         }
         inFile = false;

package/dist/context/vision-window.js

@@ -30,7 +30,7 @@ const RECOVERY_HINT = ' Call computer{screenshot} if you need the current screen
  *    computer-zoom.png —— 每次动作回灌的屏幕帧,会被反复收发,是二次增长的来源。
  *  - ❌ `browser`:`src/tools/builtins/browser.ts:235` 的附件名是 `${sessionId}.png`,**没有稳定前缀**,
  *    按文档 §2.2 的约定移出白名单(收益小一档但不会误剪)。
- *  - ❌ `screenshot` / `view_image` / 用户粘贴图:读的是"文档图"或用户意图的直接载体,剪掉是净损失。
+ *  - ❌ `screenshot` / `read_file`(文档图)/ 用户粘贴图:读的是"文档图"或用户意图的直接载体,剪掉是净损失。
  *
  * 新增屏幕帧产出点必须沿用 `computer-` 前缀才会自动进窗口;若前缀不同,请在白名单里显式登记
  * 并同步更新 design-notes/vision-window.md。
@@ -90,7 +90,7 @@ function frameNames(message) {
  *  1. `role === 'user'` 且 content 是数组;
  *  2. 数组里至少有 1 个 `image_url` part;
  *  3. 前言以工具附件前言开头(从而排除用户粘贴图),且**所有**帧名命中白名单
- *     (混进 view_image / screenshot / 用户图时不整条淘汰 —— 那些剪掉是净损失)。
+ *     (混进 read_file 文档图 / screenshot / 用户图时不整条淘汰 —— 那些剪掉是净损失)。
  *
  * 已剪过的消息不再含 image_url part → 规则 2 自然失效 → 幂等。
  * **不靠自定义字段打标**:消息对象会被 OpenAI SDK 原样发出,严格兼容后端可能 400。