mocode-ai 0.1.3 → 0.1.5

package/dist/session/compact.js

@@ -1,6 +1,6 @@
 import { chat, estimateMessagesTokens, estimateToolSchemaTokens, estimateTokens, } from '../llm/index.js';
 import { config } from '../config/index.js';
-import { MAX_HISTORY_RESULT, MAX_OLD_TOOL_STUB, MAX_SKILL_RESULT } from '../tools/constants.js';
+import { MAX_HISTORY_RESULT, MAX_MEMORY_RESULT, MAX_OLD_TOOL_STUB, MAX_SKILL_RESULT } from '../tools/constants.js';
 import { ui } from '../ui/theme.js';
 import { Spinner } from '../ui/spinner.js';
 import * as layout from '../ui/layout.js';
@@ -40,6 +40,17 @@ export function capToolResultForHistory(name, output) {
             return marker.slice(0, MAX_SKILL_RESULT);
         return output.slice(0, remain) + marker;
     }
+    if (name === 'memory_search') {
+        // 召回的记忆正文是高价值事实/指令,中截会劈断语义;同 use_skill 走尾截(保头部、弃尾部)。
+        if (output.length <= MAX_MEMORY_RESULT)
+            return output;
+        const removed = output.length - MAX_MEMORY_RESULT;
+        const marker = `…[记忆结果过长,已截断尾部 ${removed} 字符]…`;
+        const remain = MAX_MEMORY_RESULT - marker.length;
+        if (remain <= 0)
+            return marker.slice(0, MAX_MEMORY_RESULT);
+        return output.slice(0, remain) + marker;
+    }
     if (output.length <= MAX_HISTORY_RESULT)
         return output;
     return truncateMid(output, MAX_HISTORY_RESULT);
@@ -136,7 +147,7 @@ async function defaultSummarize(older, focus) {
     }
     const sysMsg = {
         role: 'system',
-        content: '你是会话摘要器。只输出摘要正文,不超过 300 字,保留:用户核心请求、已读写/改动的文件及关键变更、执行过的关键命令及结果要点、已做决策、当前任务进度与下一步、未决问题。不要复述全部细节。',
+        content: 'You are a session summarizer. Output only the summary body, max 300 words, preserving: the user\'s core request; files read/written/modified and key changes; key commands run and their result highlights; decisions made; current task progress and next step; open questions. Do not recap every detail.',
     };
     const userMsg = {
         role: 'user',
@@ -194,7 +205,12 @@ export async function compactHistory(history, opts) {
         }
         return noop;
     }
-    // 第一层:微压缩——旧区 tool 结果原地截短(保 tool_call_id,无 LLM 调用)
+    // 第一层:微压缩——旧区原地截短(保 tool_call_id,无 LLM 调用)
+    // 覆盖三类大字段,均只裁模型/工具产物,不动 user 原话与 system(摘要):
+    //   ① tool 结果 content;
+    //   ② 旧 assistant 的 tool_calls.arguments —— 保 JSON 合法:整体超长才进,
+    //     逐字段值裁中截后重新 stringify(不裸中截会劈断 JSON、严格后端 400);parse 失败跳过;
+    //   ③ 旧 assistant 正文 content(模型长解释,回看价值低)。
     let microcompactDone = false;
     for (const g of oldGroups) {
         for (const t of g.tools) {
@@ -204,6 +220,38 @@ export async function compactHistory(history, opts) {
                 microcompactDone = true;
             }
         }
+        const as = g.assistant;
+        if (as && as.role === 'assistant') {
+            // ③ 旧正文 content
+            if (typeof as.content === 'string' && as.content.length > MAX_OLD_TOOL_STUB) {
+                as.content = truncateMid(as.content, MAX_OLD_TOOL_STUB);
+                microcompactDone = true;
+            }
+            // ② tool_calls 参数:整体超长才进,逐字段裁值,保 JSON 合法
+            if (Array.isArray(as.tool_calls)) {
+                for (const tc of as.tool_calls) {
+                    const args = tc?.function?.arguments;
+                    if (typeof args !== 'string' || args.length <= MAX_OLD_TOOL_STUB)
+                        continue;
+                    try {
+                        const parsed = JSON.parse(args);
+                        if (parsed && typeof parsed === 'object') {
+                            for (const k of Object.keys(parsed)) {
+                                const v = parsed[k];
+                                if (typeof v === 'string' && v.length > MAX_OLD_TOOL_STUB) {
+                                    parsed[k] = truncateMid(v, MAX_OLD_TOOL_STUB);
+                                }
+                            }
+                            tc.function.arguments = JSON.stringify(parsed);
+                            microcompactDone = true;
+                        }
+                    }
+                    catch {
+                        // arguments 非合法 JSON(模型偶发):不裁,沿用「调度器永不抛错」
+                    }
+                }
+            }
+        }
     }
     // 第二层:摘要——把旧区(微压缩后)压成一条 system 摘要
     const older = flattenGroups(oldGroups);

package/dist/skills/index.js

@@ -39,8 +39,8 @@ export function buildSkillsSection() {
     return [
         '',
         '',
-        '## Skills(按需加载)',
-        '以下 skill 可用。只在任务相关时调用 use_skill 工具(传 skill 的 name)加载其完整指令,据此行动;不要无脑批量加载。',
+        '## Skills (load on demand)',
+        'The following skills are available. Call the use_skill tool (passing the skill name) only when relevant to the current task, to load its full instructions and act on them; do not load them all blindly.',
         ...lines,
     ].join('\n');
 }

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

@@ -0,0 +1,50 @@
+import { promptIntervention } from '../../ui/intervention.js';
+// ---------- ask_human ----------
+export const askHumanTool = {
+    name: 'ask_human',
+    description: [
+        'Call this tool when you hit a decision point during a task that requires human input — it pops up a question panel in the terminal for the user to choose.',
+        'Use when: multiple implementation approaches need a user decision, user intent is unclear and needs clarification, or extra info is needed to proceed.',
+        'Blocks until the user responds; the user can pick a preset option or choose "custom input" to answer freely; the result is returned as the tool result.',
+        'Do not call frequently when the task is clear and you can decide yourself — it interrupts the user. When options is omitted or empty, it becomes free-text input instead.',
+    ].join(''),
+    parameters: {
+        type: 'object',
+        properties: {
+            question: {
+                type: 'string',
+                description: 'The question to ask the user; keep it concise (shown as the panel title)',
+            },
+            options: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Options for the user to choose from (2~6). May be omitted — when omitted or empty, it becomes free-text input instead',
+            },
+            context: {
+                type: 'string',
+                description: 'Background explanation for the question (optional; helps the user understand why their decision is needed; shown under the title, may be multiline)',
+            },
+        },
+        required: ['question'],
+    },
+    async execute(args) {
+        const question = String(args.question ?? '');
+        const options = Array.isArray(args.options)
+            ? args.options.map((o) => String(o))
+            : [];
+        const context = args.context ? String(args.context) : undefined;
+        const result = await promptIntervention({
+            type: options.length > 0 ? 'choice' : 'input',
+            title: question,
+            options: options.length > 0 ? options : undefined,
+            detail: context,
+        });
+        if (result.action === 'cancelled') {
+            return '用户取消了选择。请考虑是否有不依赖用户输入的替代方案,或换个角度重新提问。';
+        }
+        if (result.action === 'submitted') {
+            return `用户回答:${result.value ?? ''}`;
+        }
+        return `用户选择:${result.value ?? ''}`;
+    },
+};

package/dist/tools/builtins/codegraph.js

@@ -0,0 +1,113 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { MAX_OUTPUT } from '../constants.js';
+// ---------- codegraph ----------
+// 已建代码索引(.codegraph/)的仓库里,理解/定位代码、查调用链、看改动影响面时
+// 的首选工具。比逐文件 read_file/grep 拼凑更准更省。
+// 检查 .codegraph/ 是否存在:不存在则提示建索引,不盲目调 CLI(避免报错噪音)。
+/** 同步判断当前 cwd 是否已建 codegraph 索引。 */
+function hasCodegraphIndex() {
+    return existsSync(path.join(process.cwd(), '.codegraph'));
+}
+/** 跑 codegraph CLI 子进程,返回合并 stdout+stderr(带退出码),超时 60s。 */
+function runCodegraph(args) {
+    return new Promise((done) => {
+        const isWin = process.platform === 'win32';
+        // win32 必须走 cmd.exe /c:Node 自 CVE-2024-27980 修复后,shell:false 直接 spawn
+        // .cmd/.bat 会抛 EINVAL;cmd.exe 是真二进制,直接 spawn 安全(与 run_command 同约定)。
+        const child = isWin
+            ? spawn('cmd.exe', ['/c', 'codegraph', ...args], { cwd: process.cwd() })
+            : spawn('codegraph', args, { cwd: process.cwd() });
+        let out = '';
+        let finished = false;
+        const finish = (s) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            done(s);
+        };
+        const onChunk = (chunk) => {
+            if (out.length < MAX_OUTPUT)
+                out += chunk.toString('utf8');
+        };
+        child.stdout.on('data', onChunk);
+        child.stderr.on('data', onChunk);
+        child.on('error', (e) => finish(`codegraph 执行失败(可能未安装或不在 PATH): ${e.message}\n` +
+            '安装: npm i -g @colbymchenry/codegraph'));
+        child.on('close', (code) => {
+            let r = out.trim();
+            if (out.length >= MAX_OUTPUT)
+                r += '\n...(输出已截断)';
+            finish(`[退出码 ${code}]\n${r || '(无输出)'}`);
+        });
+        const timer = setTimeout(() => {
+            child.kill();
+            finish(`[超时,已终止]\n${out.trim()}`);
+        }, 60000);
+    });
+}
+export const codegraphTool = {
+    name: 'codegraph',
+    description: 'Preferred tool for understanding/locating code, tracing call chains, and assessing the impact of changes in repos with a code index (.codegraph/).' +
+        ' Returns relevant symbol source + call paths in one shot — more accurate and economical than piecing together via read_file/grep.' +
+        ' Returns a hint when .codegraph/ is absent (build it first with `codegraph init`).',
+    parameters: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['explore', 'node'],
+                description: "explore=fetch relevant source + call paths by question/symbol (use when understanding a feature/architecture);" +
+                    "node=look up a single symbol's source + callers/callees, or read a file + dependencies (use when locating a specific symbol)",
+            },
+            query: {
+                type: 'string',
+                description: 'explore: the question or symbol name to investigate (e.g. "runAgent" or "how history is compacted").' +
+                    'node: symbol name (e.g. runAgent) or file path (used with file mode)',
+            },
+            file: {
+                type: 'string',
+                description: 'node only: treat query as a file path to read (file mode), or disambiguate to a specific file',
+            },
+            offset: {
+                type: 'integer',
+                description: 'node file mode only: start line (1-based)',
+            },
+            limit: {
+                type: 'integer',
+                description: 'node file mode only: max number of lines',
+            },
+        },
+        required: ['action', 'query'],
+    },
+    async execute(args) {
+        if (!hasCodegraphIndex()) {
+            return ('当前目录无 .codegraph/ 索引。codegraph 工具不可用。\n' +
+                '建索引:运行 `codegraph init`(需要 codegraph CLI:`npm i -g @colbymchenry/codegraph`)。\n' +
+                '在此之前,可改用 read_file / grep / glob 探索代码。');
+        }
+        const action = String(args.action);
+        const query = String(args.query);
+        const cliArgs = [];
+        if (action === 'explore') {
+            // explore 接 <query...> 多 token,拆分后逐个 push
+            cliArgs.push('explore', ...query.split(/\s+/).filter(Boolean));
+        }
+        else if (action === 'node') {
+            cliArgs.push('node', query);
+            const file = args.file ? String(args.file) : '';
+            if (file)
+                cliArgs.push('--file', file);
+            if (args.offset !== undefined)
+                cliArgs.push('--offset', String(args.offset));
+            if (args.limit !== undefined)
+                cliArgs.push('--limit', String(args.limit));
+        }
+        else {
+            return `错误:未知 action "${action}",可选 explore 或 node。`;
+        }
+        return runCodegraph(cliArgs);
+    },
+};

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

@@ -3,13 +3,13 @@ import { resolve } from 'node:path';
 // ---------- edit_file ----------
 export const editFileTool = {
     name: 'edit_file',
-    description: '对文件做精确字符串替换。old_string 必须在文件中唯一出现且完全匹配(含缩进/换行)。新建文件请用 write_file。',
+    description: 'Make a precise string replacement in a file. old_string must occur exactly once in the file and match exactly (including indentation/newlines). Use write_file for new files.',
     parameters: {
         type: 'object',
         properties: {
             path: { type: 'string' },
-            old_string: { type: 'string', description: '要被替换的原文,须精确匹配' },
-            new_string: { type: 'string', description: '替换后的新文本' },
+            old_string: { type: 'string', description: 'The original text to be replaced; must match exactly' },
+            new_string: { type: 'string', description: 'The new text to replace it with' },
         },
         required: ['path', 'old_string', 'new_string'],
     },

package/dist/tools/builtins/glob.js

@@ -3,11 +3,12 @@ import { IGNORE } from '../constants.js';
 // ---------- glob ----------
 export const globTool = {
     name: 'glob',
-    description: '按 glob 模式查找文件路径(如 **/*.ts)。返回匹配列表(自动排除 node_modules / .git)。',
+    description: 'Find file paths matching a glob pattern (e.g. **/*.ts). Returns a list of matches (auto-excludes node_modules / .git).' +
+        ' Note: when understanding code architecture/call chains, if a .codegraph/ index exists, prefer the codegraph tool over piecing together via glob one file at a time.',
     parameters: {
         type: 'object',
         properties: {
-            pattern: { type: 'string', description: 'glob 模式,如 **/*.ts 或 src/**/*.json' },
+            pattern: { type: 'string', description: 'Glob pattern, e.g. **/*.ts or src/**/*.json' },
         },
         required: ['pattern'],
     },

package/dist/tools/builtins/grep.js

@@ -5,12 +5,13 @@ import { MAX_RESULTS, IGNORE } from '../constants.js';
 // ---------- grep ----------
 export const grepTool = {
     name: 'grep',
-    description: '在文件内容里按正则搜索,返回 file:line: 匹配行。默认递归搜索当前目录(排除 node_modules/.git)。可选 glob 限定文件类型。',
+    description: 'Search file contents by regex, returning file:line: matched lines. Recursively searches the current directory by default (excluding node_modules/.git). Optional glob to restrict file types.' +
+        ' Note: when understanding code architecture/call chains, if a .codegraph/ index exists, prefer the codegraph tool over piecing together via grep one file at a time.',
     parameters: {
         type: 'object',
         properties: {
-            pattern: { type: 'string', description: '正则表达式' },
-            glob: { type: 'string', description: '可选,限定文件 glob,如 *.ts' },
+            pattern: { type: 'string', description: 'Regular expression' },
+            glob: { type: 'string', description: 'Optional, restrict to a file glob, e.g. *.ts' },
         },
         required: ['pattern'],
     },

package/dist/tools/builtins/index.js

@@ -7,9 +7,18 @@ import { grepTool } from './grep.js';
 import { webSearchTool } from './web-search.js';
 import { webFetchTool } from './web-fetch.js';
 import { useSkillTool } from './use-skill.js';
+import { askHumanTool } from './ask-human.js';
+import { codegraphTool } from './codegraph.js';
+import { switchModeTool } from './switch-mode.js';
+import { memorySaveTool } from './memory-save.js';
+import { memorySearchTool } from './memory-search.js';
+import { memoryListTool } from './memory-list.js';
+import { memoryUpdateTool } from './memory-update.js';
+import { memoryForgetTool } from './memory-forget.js';
+import { taskTool } from './task.js';
 /**
  * 所有内置工具,按注册顺序排列。
- * 加新工具:在本目录新建 `xxx.ts` 导出一个 Tool,再在下面数组里加一行。
+ * 加新工具:在本目录新建 `xxx.ts` 导出一个 Tool,再在下面数组里加一行。无需改 agent / llm。
  */
 export const builtinTools = [
     readFileTool,
@@ -18,7 +27,16 @@ export const builtinTools = [
     runCommandTool,
     globTool,
     grepTool,
+    codegraphTool,
     webSearchTool,
     webFetchTool,
     useSkillTool,
+    askHumanTool,
+    switchModeTool, // plan↔auto 自切(两模式都可见,不进 PLAN_DISABLED_TOOLS;副作用控制工具→串行分支)
+    memorySaveTool,
+    memorySearchTool,
+    memoryListTool,
+    memoryUpdateTool,
+    memoryForgetTool,
+    taskTool, // 派生子 agent(独立 history + 可受限工具集);plan 模式禁用(见 PLAN_DISABLED_TOOLS)
 ];

package/dist/tools/builtins/memory-forget.js

@@ -0,0 +1,32 @@
+import { forgetEntry } from '../../memory/store.js';
+// ---------- memory_forget ----------
+// 遗忘:默认归档(archived,从索引/默认搜索隐藏,可复活);mode=delete 硬删。pinned 拒删。
+export const memoryForgetTool = {
+    name: 'memory_forget',
+    description: 'Forget a memory entry: by default archives (archived, hidden from index and default search, can be revived via memory_update); mode=delete hard-deletes. Pinned entries cannot be deleted (first memory_update pinned=false to unpin).',
+    parameters: {
+        type: 'object',
+        properties: {
+            id: { type: 'string' },
+            mode: {
+                type: 'string',
+                enum: ['archive', 'delete'],
+                description: 'Default archive',
+            },
+        },
+        required: ['id'],
+    },
+    async execute(args) {
+        const id = String(args.id ?? '').trim();
+        if (!id)
+            return '错误:缺少 id。';
+        const mode = args.mode === 'delete' ? 'delete' : 'archive';
+        const r = forgetEntry(id, mode);
+        if (r.ok)
+            return `已${mode === 'delete' ? '硬删' : '归档'}记忆 [${id}]。`;
+        if ('notFound' in r)
+            return `错误:找不到记忆 id="${id}"。`;
+        // pinned
+        return `错误:[${id}] 已钉住,拒绝遗忘。先 memory_update(id="${id}", pinned=false) 解钉。`;
+    },
+};

package/dist/tools/builtins/memory-list.js

@@ -0,0 +1,34 @@
+import { listEntries } from '../../memory/store.js';
+// ---------- memory_list ----------
+// 列索引(id/name/summary,无正文、不 bump recall)。用于浏览有哪些、拿 id 再 memory_search 取正文。
+export const memoryListTool = {
+    name: 'memory_list',
+    description: 'List the memory index (id/name/summary, no body). Defaults to active. Get an id, then use memory_search to retrieve the full body.',
+    parameters: {
+        type: 'object',
+        properties: {
+            type: {
+                type: 'string',
+                enum: ['decision', 'fact', 'pitfall', 'reference', 'feedback'],
+            },
+            status: {
+                type: 'string',
+                enum: ['active', 'superseded', 'archived', 'any'],
+                description: 'Default active',
+            },
+        },
+    },
+    async execute(args) {
+        const items = listEntries({
+            type: typeof args.type === 'string' ? args.type : undefined,
+            status: typeof args.status === 'string'
+                ? args.status
+                : undefined,
+        });
+        if (items.length === 0)
+            return '(无记忆条目)';
+        return items
+            .map((i) => `- ${i.id}: ${i.name} — ${i.summary} (${i.type}, ${i.status})`)
+            .join('\n');
+    },
+};

package/dist/tools/builtins/memory-save.js

@@ -0,0 +1,51 @@
+import { saveEntry } from '../../memory/store.js';
+// ---------- memory_save ----------
+// 存一条长期记忆(跨会话)。启动只把标题/摘要注入索引(几百 token);详情按需 memory_search 取。
+// 撞库(name→id 已存在)拒绝,引导用 memory_update。
+export const memorySaveTool = {
+    name: 'memory_save',
+    description: 'Save a long-term memory entry (cross-session). Store only non-obvious, long-term-useful facts/decisions/pitfalls. The title goes into the startup index; retrieve full body on demand via memory_search.',
+    parameters: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Short unique title (converted to id; rejected if it collides with an existing one)' },
+            summary: { type: 'string', description: 'One-line summary (goes into the index; keep it short)' },
+            body: { type: 'string', description: 'Full content (details/context/evidence)' },
+            type: {
+                type: 'string',
+                enum: ['decision', 'fact', 'pitfall', 'reference', 'feedback'],
+                description: 'Category, default fact',
+            },
+            pinned: { type: 'boolean', description: 'Pin (exempt from auto-forgetting decay), default false' },
+            scope: {
+                type: 'string',
+                enum: ['project', 'global'],
+                description: 'Store at project level (<cwd>/.mocode/) or global (~/.mocode/), default project',
+            },
+        },
+        required: ['name', 'summary', 'body'],
+    },
+    async execute(args) {
+        const name = String(args.name ?? '').trim();
+        const summary = String(args.summary ?? '').trim();
+        const body = String(args.body ?? '').trim();
+        if (!name)
+            return '错误:缺少 name。';
+        if (!summary)
+            return '错误:缺少 summary。';
+        if (!body)
+            return '错误:缺少 body。';
+        const type = typeof args.type === 'string' ? args.type : undefined;
+        const r = saveEntry({
+            name,
+            summary,
+            body,
+            type,
+            pinned: args.pinned === true,
+            scope: args.scope === 'global' ? 'global' : 'project',
+        });
+        if (r.ok)
+            return `已保存记忆 [${r.id}] "${name}"(下次启动进索引)。`;
+        return `已存在同名记忆 [${r.exists}]。改用 memory_update(id="${r.exists}", …) 更新,或换一个 name。`;
+    },
+};

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

@@ -0,0 +1,42 @@
+import { searchEntries } from '../../memory/store.js';
+// ---------- memory_search ----------
+// 关键词搜记忆正文(多词子串匹配,name 权重最高)。命中即 bump recallCount(遗忘衰减依据)。
+// 结果走 capToolResultForHistory 的放宽上限(同 use_skill,保正文完整)。
+export const memorySearchTool = {
+    name: 'memory_search',
+    description: 'Search memory entries by keyword (multi-word substring match, ranked by relevance), returning full body of matching entries. A hit bumps recall count (affects forgetting decay).',
+    parameters: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'Keywords (words in id or name work best)' },
+            type: {
+                type: 'string',
+                enum: ['decision', 'fact', 'pitfall', 'reference', 'feedback'],
+            },
+            status: {
+                type: 'string',
+                enum: ['active', 'superseded', 'archived', 'any'],
+                description: 'Default active (only search live entries)',
+            },
+            limit: { type: 'integer', description: 'Number of entries to return, default 5, max 20' },
+        },
+        required: ['query'],
+    },
+    async execute(args) {
+        const query = String(args.query ?? '').trim();
+        if (!query)
+            return '错误:缺少 query。';
+        const r = searchEntries(query, {
+            type: typeof args.type === 'string' ? args.type : undefined,
+            status: typeof args.status === 'string'
+                ? args.status
+                : undefined,
+            limit: typeof args.limit === 'number' ? args.limit : undefined,
+        });
+        if (r.length === 0)
+            return `(无匹配记忆:query="${query}")`;
+        return r
+            .map((e) => `# [${e.id}] ${e.name} (${e.type}, recalled ${e.recallCount})\nsummary: ${e.summary}\n\n${e.body}`)
+            .join('\n\n---\n\n');
+    },
+};

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

@@ -0,0 +1,41 @@
+import { updateEntry } from '../../memory/store.js';
+// ---------- memory_update ----------
+// 原地改一条记忆(id 不变)。反思的弱意义:干活时发现事实变了/过时即纠正。
+export const memoryUpdateTool = {
+    name: 'memory_update',
+    description: 'Update a memory entry in place (id unchanged). Use when facts changed / correcting outdated info / updating summary or body / toggling pinned. Get id from memory_list or memory_search.',
+    parameters: {
+        type: 'object',
+        properties: {
+            id: { type: 'string' },
+            summary: { type: 'string', description: 'New summary (only pass fields to change)' },
+            body: { type: 'string', description: 'New body (only pass fields to change)' },
+            name: { type: 'string', description: 'New title (id does not change with name)' },
+            pinned: { type: 'boolean', description: 'Toggle pin status (true pins and exempts decay / false unpins)' },
+            reason: { type: 'string', description: 'Update reason (recorded in lastUpdateReason for traceability)' },
+        },
+        required: ['id'],
+    },
+    async execute(args) {
+        const id = String(args.id ?? '').trim();
+        if (!id)
+            return '错误:缺少 id。';
+        const patch = {};
+        if (typeof args.summary === 'string')
+            patch.summary = args.summary;
+        if (typeof args.body === 'string')
+            patch.body = args.body;
+        if (typeof args.name === 'string')
+            patch.name = args.name;
+        if (typeof args.reason === 'string')
+            patch.reason = args.reason;
+        if (typeof args.pinned === 'boolean')
+            patch.pinned = args.pinned;
+        if (Object.keys(patch).length === 0)
+            return '错误:至少传一个要改的字段(summary/body/name/pinned/reason)。';
+        const r = updateEntry(id, patch);
+        if (r.ok)
+            return `已更新记忆 [${id}]。`;
+        return `错误:找不到记忆 id="${id}"。用 memory_list 查可用 id。`;
+    },
+};

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

@@ -4,13 +4,14 @@ import { MAX_FILE_LINES } from '../constants.js';
 // ---------- read_file ----------
 export const readFileTool = {
     name: 'read_file',
-    description: '读取文件内容,返回带行号的文本。改代码前先读。可选 offset(起始行,1-based,默认1)和 limit(行数,默认2000)。',
+    description: 'Read file content, returning text with line numbers. Read before editing code. Optional offset (start line, 1-based, default 1) and limit (number of lines, default 2000).' +
+        ' Note: when understanding code architecture/call chains, if a .codegraph/ index exists, prefer the codegraph tool over piecing together via read_file one file at a time.',
     parameters: {
         type: 'object',
         properties: {
-            path: { type: 'string', description: '文件路径,相对工作目录' },
-            offset: { type: 'integer', description: '起始行号(1-based),默认1' },
-            limit: { type: 'integer', description: '最大读取行数,默认2000' },
+            path: { type: 'string', description: 'File path, relative to the working directory' },
+            offset: { type: 'integer', description: 'Start line (1-based), default 1' },
+            limit: { type: 'integer', description: 'Max number of lines to read, default 2000' },
         },
         required: ['path'],
     },