mocode-ai 1.6.1 → 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/config/index.js

@@ -322,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] : []),
@@ -331,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 构建
@@ -398,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.

package/dist/repl/commands/system.js

@@ -17,40 +17,60 @@ import { buildSlashCommands, slashHelpLines, HELP_GROUPS } from '../commands.js'
 import { startRunningListener, stopRunningListener } from '../running-input.js';
 import { checkVersion, fetchLatestVersion, getCurrentVersion, runUpgradeForeground } from '../../commands/upgrade.js';
 import { unhandled, next, exit, forward } from './types.js';
+import fs from 'node:fs';
+import path from 'node:path';
 /**
- * /init 指令:发给 agent 扫描项目并生成 AGENTS.md。已存在则让 agent 读后更新(不丢失事实)。写完供 memory 子系统下轮加载。
+ * /init 指令:发给 agent 扫描项目并生成 AGENTS.md。整体重写(非增量追加),预算分配制:
+ * 总长 ≤4000 字且 ≤ 旧文件字数(代码侧动态注入具体数字),装不下的高价值事实进
+ * .mocode/agents-draft.md 草稿而非硬塞,消除「删事实 vs 守预算」两难。写完供 memory 子系统下轮加载。
  *
- * 函数化(非 const):.codegraph/ 索引是否存在的探测放在调用瞬间,没索引时不提 codegraph,
+ * 函数化(非 const):.codegraph/ 索引与旧文件字数的探测放在调用瞬间,没索引时不提 codegraph,
  * 避免 LLM 调出失败。/init 是冷启动动作,IO 开销可忽略。
  */
 function buildInitPrompt() {
     const cg = hasCodegraphIndex()
         ? '- 若有 .codegraph/:用 use_skill 加载 codegraph skill 后用 run_command 调 codegraph explore "<架构或入口符号>" 一次拿相关源码+调用路径,别逐文件读！！！\n'
         : '';
+    // 动态注入旧文件字数:具体数字的遵循率远高于抽象原则(「≤4000」);首次生成时无旧文件则只约束绝对上限。
+    let oldSizeNote = '';
+    try {
+        const old = fs.readFileSync(path.join(process.cwd(), 'AGENTS.md'), 'utf8');
+        if (old.trim())
+            oldSizeNote = `旧 AGENTS.md 为 ${old.length} 字(新文件净字数必须 ≤ ${Math.min(4000, old.length)}:既守 4000 上限也守零和,超出即继续删低价值条目直到达标)。`;
+    }
+    catch {
+        // 无旧文件:首次生成,只受 4000 字绝对上限约束。
+    }
     return `分析当前项目(process.cwd()),生成 AGENTS.md 项目记忆文件,供 mocode 后续会话自动加载——目标是让后续会话无需重新摸索就能上手。
 
 先探查(尽量少调用拿全貌):
 ${cg}- read_file package.json(或 Cargo.toml/pyproject.toml/go.mod 等):scripts、依赖、入口、模块类型。
 - glob 顶层目录;read_file 入口文件 + 各子系统 index.ts/README。
-- 若 AGENTS.md 已存在:read_file 读它,在其基础上更新(补缺、修正过时),不丢已有准确事实。
+- 若 AGENTS.md 已存在:read_file 读它。**整体重写,不是增量追加**——不要把旧文当底稿做增量,从下面的预算出发重新分配每一条;以当前代码为准,过时/弱事实直接删,准确且仍高价值的可沿用。
+- 若 .mocode/agents-draft.md 存在:read_file 读它,把草稿里的稳定事实合入对应章节,完成后用 write_file 覆盖为空(或删除该文件)。
 
 AGENTS.md 按以下结构写(每节简短,只写稳定、非显然的事实):
 ## 项目
 一两句:是什么、技术栈、运行环境。
 ## 命令
-install / dev / build / test / typecheck / lint 等——从 package.json scripts 提炼,写原样命令行(如 \`npm run typecheck\`);没有的注明"无测试"/"无 lint"。
+install / dev / build / test / typecheck / lint 等——从 package.json scripts 提炼,写原样命令行(如 \`npm run build\`);没有的注明"无测试"/"无 lint"。
 ## 目录结构
-顶层各目录与子系统职责,一句话/个;不逐文件列。
+顶层各目录与子系统职责,一句话/个;不逐文件列。此节系统提示不会常驻注入(按需 read_file),够用即可。
 ## 约定
 从代码与现有文档提炼的硬约定:模块系统(ESM?)、命名、错误处理、工具/函数契约、易踩坑点。只写非显然、会让人踩坑的;不写"保持简洁"这种正确废话。
 ## 扩展点
-加工具/命令/provider/模块的接缝(改哪个文件、加在哪)。
+加工具/命令/provider/模块的接缝(改哪个文件、加在哪)。此节同样不常驻注入,保持简短。
+
+预算(硬上限,按字分配,参考):
+- 总长 ≤ 4000 字${oldSizeNote ? `,且 ${oldSizeNote}` : '(首次生成)'}。参考分配:项目 ≤200、命令 ≤650、目录结构 ≤400、约定 ≤2000、扩展点 ≤400。
+- **预算装不下但确有高价值的事实不丢**:write_file(append=true) 追加到 \`.mocode/agents-draft.md\`(一行一条,注明所属章节),下次 /init 再评估合入。禁止为了塞进预算牺牲准确性,也禁止超预算硬塞。
 
 硬要求:
 - 从实际代码提炼,引用具体文件名/命令/符号;不编造、不泛泛。
-- 总长 ≤ 3000 字;只写后续会话有用的稳定事实,不写易变项(当前 bug、临时文件、未决 TODO)。
-- 用 write_file 写入项目根 AGENTS.md。
-- 写完简述:写了哪几节 + 从代码里发现的 2-3 条非显然关键约定(供用户校验)。`;
+- 只写后续会话有用的稳定事实,不写易变项(当前 bug、临时文件、未决 TODO)。
+- 写入前 run_command \`wc -m AGENTS.md\` 不可用(文件还没写);改用你草稿的字数估算,并按 ${oldSizeNote ? '上述净删目标' : '4000 字上限'}自查,超了先删再写。
+- 用 write_file 写入项目根 AGENTS.md;**写完立即 read_file AGENTS.md 复查实际字数**,超限则编辑收窄后重写,直到达标。
+- 最终简述必须含对账三件套(供用户验收,缺一不可):①新旧字数对比(旧 X → 新 Y,无旧文件写"首建 Y");②删掉的条目清单(标题级);③新增的条目清单(标题级)+ 从代码里发现的 2-3 条非显然关键约定。`;
 }
 export const systemCommands = [
     (ctx) => {

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

@@ -111,10 +111,9 @@ export const askHumanTool = {
     name: 'ask_human',
     description: [
         'Ask the user a question and wait for their response.',
-        ' CHOICES: pass 2-4 concrete options via `options`, each as { label, description? }.',
+        ' CHOICES: pass 2-4 concrete options via `options`, each as { label, description? }; every non-empty option requires a non-empty `label`.',
         ' FREE-TEXT: pass `options: []` when the answer cannot be reduced to choices (e.g. "paste the error message").',
-        ' Every non-empty option requires a non-empty `label`; never emit [{}], omit label, or omit `options`.',
-        ' DO NOT call when the task is clear and you can pick a sensible default.',
+        ' DO NOT call when the task is clear and a sensible default exists.',
     ].join(' '),
     parameters: {
         type: 'object',

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

@@ -13,23 +13,15 @@ function conflict(path, details) {
 }
 export const editFileTool = {
     name: 'edit_file',
-    description: `Replace content in a file transactionally. Supports two modes:
+    description: `Replace content in a file transactionally. Two modes:
 
-**String replacement mode (default):** Provide old_string that occurs exactly once in the file. The old_string must be copied verbatim from a fresh read_file output — do NOT reconstruct from memory, summaries, or grep output, as these lose whitespace/indentation details. Common failure modes: trailing whitespace, tabs vs spaces, indentation changes, line-ending mismatches (CRLF vs LF).
+**String replacement (default):** old_string must occur EXACTLY once, copied verbatim from a fresh read_file output — never reconstruct from memory, summaries, or grep output (whitespace/indentation/line-ending details are lost there).
 
-**Line-range mode:** Provide line_start and line_end (1-based, inclusive) instead of old_string. Use this when the exact text is hard to reproduce or when replacing a large block.
+**Line-range:** line_start/line_end (1-based, inclusive) instead of old_string — for large blocks, repeated patterns, or hard-to-reproduce text.
 
-expected_hash is required (sha256 from read_file artifact header) and must match the current file hash. If the file changed after your read, the edit is rejected. Recovery: call read_file again on the same path and copy both the new hash and exact text.
+expected_hash (sha256 from read_file artifact header) is required and must match the current file; changed-since-read edits are rejected — re-read and retry with the new hash.
 
-**When to use which mode:**
-- String replacement: small, unique text fragments (function signatures, config keys, error messages)
-- Line-range: large blocks, repeated patterns, or when whitespace precision is critical
-
-**Anti-patterns (will fail):**
-- old_string reconstructed from memory or a summary
-- old_string copied from a previous tool call that may be stale
-- old_string that appears multiple times (add more context to make it unique)
-- expected_hash from a different file or an old read_file call`,
+Anti-patterns (will fail): old_string from memory/summary/stale call; multiple occurrences (add context to disambiguate); hash from another file or old read.`,
     risk: 'confirm',
     parameters: {
         type: 'object',

package/dist/tools/builtins/glob.js

@@ -4,8 +4,8 @@ import { getSandboxRoot, isInsideRoot } from '../../sandbox/index.js';
 // ---------- glob ----------
 export const globTool = {
     name: 'glob',
-    description: 'Find files matching a glob pattern (e.g. **/*.ts). Auto-excludes node_modules/.git.' +
-        ' For architecture or call chains, prefer loading the `codegraph` skill (use_skill).',
+    description: 'Find files matching a glob pattern (e.g. **/*.ts). Auto-excludes node_modules/.git. ' +
+        'For architecture or call chains, prefer the codegraph skill.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/grep.js

@@ -60,13 +60,9 @@ export const grepTool = {
     name: 'grep',
     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. Context lines use an `L<n>-` prefix and blocks are separated by `  --`.\n' +
-        'Still use read_file(offset=X, limit=Y) when you need a whole region or exact text for an edit — ' +
-        'do NOT read entire files after grepping, and do NOT reconstruct an edit_file old_string from grep output ' +
-        '(long lines are clipped).\n' +
-        '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).',
+        '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: {

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

@@ -36,18 +36,11 @@ function failure(code, message) {
 export const readFileTool = {
     name: 'read_file',
     description: 'Read a file: text with line numbers, images as visual model input.\n' +
-        'Text — read before editing. 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' +
-        'Images — PNG/JPEG/GIF/WebP are detected by MAGIC BYTES (the extension does not matter) and attached as ' +
-        'visual model input; pass detail=low|high to control resolution, and oversized PNGs are downscaled automatically.\n' +
-        'Other binary files are REJECTED with an explanation instead of being dumped as garbled text. ' +
-        'If you truly need their content, use run_command with a proper tool (e.g. `file`, `strings`, a disassembler).\n' +
-        'For architecture or call-chain questions, prefer loading the `codegraph` skill (use_skill) over reading files one at a time.',
+        '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: {

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

@@ -164,15 +164,9 @@ function commandOutcome(result) {
 // ---------- run_command ----------
 export const runCommandTool = {
     name: 'run_command',
-    description: 'Run a FOREGROUND shell command, merging stdout+stderr. Default timeout 120s, hard cap 10min. ' +
-        'For tests, builds, git, etc. Pass shell=cmd|powershell|bash to choose the interpreter — the platform ' +
-        'default (and any MOCODE_SHELL override) is stated in the system prompt. Non-interactive cmd cannot run `timeout /t` — ' +
-        'pass shell=powershell (`Start-Sleep`) or shell=bash (`sleep`) when a wait is needed.\n' +
-        'Anything that must keep running after this call returns — dev server, inference/model service, watcher, ' +
-        'log tail — belongs to dev_server instead: it survives across tool calls and gives you an id for ' +
-        'incremental log reads and process-tree kill. Do NOT detach with `start /b`, `nohup`, `&` or similar here: ' +
-        'you lose both the logs and the handle.\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',

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

@@ -77,8 +77,7 @@ async function attemptFetch(target, via, signal) {
 // ---------- 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' },

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

@@ -28,10 +28,8 @@ function invalid(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.\n' +
-        'To ADD to an existing file (logs, growing docs, staged generation of a long file), pass append=true instead of re-sending the whole content: only the new text goes in `content`. ' +
-        'append needs NO expected_hash and NO prior read_file (concurrency is handled by the file lock); it creates the file when missing, and it appends bytes VERBATIM — ' +
-        'if the file does not end with a newline, start your content with "\\n" or the last line will merge with yours.',
+    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',

package/dist/tools/policy.js

@@ -237,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mocode-ai",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "终端编码 agent:LLM + tool-call 循环 + 流式输出(含思考)+ 25 个工具,接任意 OpenAI 兼容后端。",
   "type": "module",
   "bin": {