mocode-ai 0.1.4 → 0.1.6

package/dist/sandbox/jail.js

@@ -0,0 +1,75 @@
+// 路径牢笼原语:把任意输入路径解析到沙箱根之内,拒绝越界(../、绝对路径外圈、符号链接出圈)。
+// 核心:resolve(root, input) → realpath(解软链)→ 前缀校验。
+// 新文件(目标不存在)走「最近存在祖先 realpath 再拼回剩余分量」,同样挡住「祖先是出圈软链」。
+import { realpathSync, existsSync } from 'node:fs';
+import { resolve, relative, isAbsolute, dirname, basename, join } from 'node:path';
+import { getSandboxRoot } from './root.js';
+const isWin = process.platform === 'win32';
+/** 当前沙箱根(绝对),未初始化回退 process.cwd()。 */
+function root() {
+    return resolve(getSandboxRoot() ?? process.cwd());
+}
+/**
+ * abs 是否在沙箱根内(含 == 根)。win32 下两边 toLowerCase 再比(node 的 path.relative 不做
+ * 大小写无关比较,盘符大小写差异会误判出圈)。**不做 realpath**——用于 glob/grep 结果后置过滤;
+ * 越界软链的拦挡靠 jailResolve 的 realpath。
+ */
+export function isInsideRoot(abs) {
+    const r = root();
+    // resolve 相对 r(sandbox root):glob/grep 结果相对 sandbox root,需对齐;
+    // 传绝对路径时 resolve(r, abs) 返 abs 不变,兼容 jailResolve 的 realpath 结果。
+    const a = isWin ? resolve(r, abs).toLowerCase() : resolve(r, abs);
+    const rr = isWin ? r.toLowerCase() : r;
+    const rel = relative(rr, a);
+    return !rel.startsWith('..') && !isAbsolute(rel);
+}
+/**
+ * 把输入路径解析为沙箱根内的绝对路径;越界(../、绝对外圈、符号链接出圈)抛错。
+ * 供 enforceSandbox 重写 args.path(读/写/改)、readDiffContext 预读旧内容用。
+ * 同步:realpathSync 仅做 fs 元数据查询(微秒级),与既有 readFileSync/existsSync 用法一致。
+ */
+export function jailResolve(input) {
+    const r = root();
+    let abs = resolve(r, input);
+    try {
+        abs = realpathSync(abs);
+    }
+    catch {
+        // 目标或中间段不存在(写新文件 / 路径中间段未建):realpath 最近存在祖先,拼回剩余分量。
+        let dir = dirname(abs);
+        const rest = [basename(abs)];
+        while (!existsSync(dir)) {
+            const parent = dirname(dir);
+            if (parent === dir)
+                break; // 已到 FS 根(C:\ 或 /),无法再上
+            rest.unshift(basename(dir));
+            dir = parent;
+        }
+        try {
+            abs = join(realpathSync(dir), ...rest);
+        }
+        catch {
+            // 连祖先都 realpath 失败(不该发生,除非 root 本身不可达):用 resolve 值,交由包含校验兜底
+            abs = resolve(r, input);
+        }
+    }
+    if (!isInsideRoot(abs)) {
+        throw new Error(`路径越界,已被沙箱拒绝: ${input}`);
+    }
+    return abs;
+}
+/**
+ * glob pattern 校验:拒绝对路径(平台相关的 isAbsolute)与含 `..` 段的 pattern。
+ * 返 null = 通过;返 string = 拒绝原因。形如 *.ts 的正常 pattern 放行。
+ */
+export function jailGlobPattern(pattern) {
+    const p = String(pattern ?? '').trim();
+    if (!p)
+        return '空 pattern';
+    if (isAbsolute(p))
+        return `不得为绝对路径: ${pattern}`;
+    const segs = p.split(/[\\/]/);
+    if (segs.includes('..'))
+        return `不得含 .. 段: ${pattern}`;
+    return null;
+}

package/dist/sandbox/policy.js

@@ -0,0 +1,58 @@
+// 沙箱策略分类集 + 集中执行 enforceSandbox。单一事实源,仿 tools/constants.ts 的
+// PLAN_DISABLED_TOOLS / READ_TOOL_NAMES 风格。
+import { jailResolve, jailGlobPattern } from './jail.js';
+/**
+ * 豁免 cwd 牢笼的工具:
+ *  - memory_*:操作 ~/.mocode 与 <cwd>/.mocode(CLAUDE.md 明确不进回滚、在外圈),本就该在外圈
+ *  - use_skill:读 ~/.claude/skills、~/.mocode/skills、<cwd>/.mocode/skills,部分在外圈
+ *  - web_*:跨网络,非文件路径
+ *  - ask_human / switch_mode:无文件路径
+ *  - codegraph:只读 cwd 下 .codegraph/ 索引(只读、不写盘)
+ *  - task:派生子 agent,继承全局 root(子 agent 同进程天然共享 getSandboxRoot)
+ */
+export const SANDBOX_EXEMPT_TOOLS = new Set([
+    'memory_save', 'memory_update', 'memory_forget', 'memory_search', 'memory_list',
+    'use_skill',
+    'web_search', 'web_fetch',
+    'ask_human', 'switch_mode',
+    'codegraph',
+    'task',
+]);
+/**
+ * 路径类工具:enforceSandbox 集中把 args.path 重写为牢内绝对路径(默认安全;工具内
+ * resolve(absolutePath) 原样返回)。**新加带 path 参数的工具须列入此集**,否则不会被牢笼挡。
+ */
+export const SANDBOX_PATH_TOOLS = new Set(['read_file', 'write_file', 'edit_file']);
+/**
+ * 工具执行前的沙箱校验。返 string = 拒绝(直接喂 LLM,不执行);返 null = 放行(可能已重写 args.path)。
+ * **不抛**——契约对齐「调度器永不抛错、永远返回字符串」(tools/registry.ts executeTool)。
+ * run_command 不在此处理(cwd / env / denylist 在其站点)。
+ */
+export function enforceSandbox(name, args) {
+    if (SANDBOX_EXEMPT_TOOLS.has(name))
+        return null;
+    if (SANDBOX_PATH_TOOLS.has(name)) {
+        const p = args.path;
+        if (typeof p === 'string' && p) {
+            try {
+                args.path = jailResolve(p);
+            }
+            catch (e) {
+                const why = e instanceof Error ? e.message : String(e);
+                return `错误:路径越界,已被沙箱拒绝: ${p} (${why})`;
+            }
+        }
+        return null;
+    }
+    if (name === 'glob') {
+        const pat = String(args.pattern ?? '');
+        const err = jailGlobPattern(pat);
+        return err ? `错误:glob ${err}` : null;
+    }
+    if (name === 'grep') {
+        const pat = String(args.glob ?? '**/*');
+        const err = jailGlobPattern(pat);
+        return err ? `错误:grep glob ${err}` : null;
+    }
+    return null;
+}

package/dist/sandbox/root.js

@@ -0,0 +1,19 @@
+// 共享叶子:沙箱根目录(文件操作边界)。零依赖、不反向引用业务、不落盘。
+// 依赖方向无环:tools/registry → sandbox、tools/builtins/* → sandbox、agent/core → sandbox、repl → sandbox
+// —— 全是「业务 → 叶子」,同 src/agent/mode.ts。
+//
+// 设计:sandboxRoot 是纯边界记录(默认 = process.cwd(),不 chdir),避免与 config.sessionDir 等
+// 模块加载期计算的值产生错位(若 chdir 会令那些值变陈旧)。子 agent 同进程天然继承全局 root
+// (未来 agents/ 做 worktree 隔离时再改为沿 opts 透传,照 signal 同形链路,7 处改动)。
+let currentRoot = null;
+/** 当前沙箱根(绝对路径)。未初始化返 null,调用方 ?? process.cwd() 兜底(防御)。 */
+export function getSandboxRoot() {
+    return currentRoot;
+}
+/** 设置沙箱根。repl startRepl 启动时调一次(默认 process.cwd();--sandbox-root / SANDBOX_ROOT 可覆盖)。
+ *  返回之前的值,供未来 save/restore(子 agent worktree 隔离)用。 */
+export function setSandboxRoot(root) {
+    const prev = currentRoot;
+    currentRoot = root;
+    return prev;
+}

package/dist/session/compact.js

@@ -147,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',

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

@@ -3,26 +3,26 @@ import { promptIntervention } from '../../ui/intervention.js';
 export const askHumanTool = {
     name: 'ask_human',
     description: [
-        '当你在执行任务中遇到需要人类做决策的岔路时调用此工具,在终端弹出问题面板让用户选择。',
-        '适用:多种实现方案需要用户拍板、不确定用户意图需要澄清、需要用户提供额外信息才能继续。',
-        '调用后阻塞等待用户响应;用户可挑预设选项,也可选"自定义输入"自由作答,结果作为工具返回值返回。',
-        '不要在任务明确、可自行决定时频繁调用——会打断用户。options 省略或为空时改为自由文本输入。',
+        '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: '要问用户的问题,简明扼要(显示为面板标题)',
+                description: 'The question to ask the user; keep it concise (shown as the panel title)',
             },
             options: {
                 type: 'array',
                 items: { type: 'string' },
-                description: '供用户选择的选项(2~6 个)。可省略——省略或为空时改为自由文本输入',
+                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: '问题的背景说明(可选,帮助用户理解为何需要他决策;显示在标题下,可多行)',
+                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'],

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

@@ -1,24 +1,29 @@
 import fg from 'fast-glob';
 import { IGNORE } from '../constants.js';
+import { getSandboxRoot, isInsideRoot } from '../../sandbox/index.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'],
     },
     async execute(args) {
         const pattern = String(args.pattern);
-        const files = await fg(pattern, {
-            cwd: process.cwd(),
+        const cwd = getSandboxRoot() ?? process.cwd();
+        const files = (await fg(pattern, {
+            cwd,
             onlyFiles: true,
             dot: true,
             ignore: IGNORE,
-        });
+            followSymbolicLinks: false, // 不跟随软链目录,防经软链列出牢外文件
+            throwErrorOnBrokenSymbolicLink: false,
+        })).filter((f) => isInsideRoot(f)); // 后置兜底:仅留牢内
         if (files.length === 0)
             return '无匹配文件';
         const shown = files.slice(0, 200);

package/dist/tools/builtins/grep.js

@@ -1,16 +1,17 @@
 import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
 import fg from 'fast-glob';
 import { MAX_RESULTS, IGNORE } from '../constants.js';
+import { getSandboxRoot, isInsideRoot, jailResolve } from '../../sandbox/index.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'],
     },
@@ -24,12 +25,15 @@ export const grepTool = {
         catch (e) {
             return `错误:非法正则 ${pattern}: ${e instanceof Error ? e.message : String(e)}`;
         }
-        const files = await fg(g, {
-            cwd: process.cwd(),
+        const cwd = getSandboxRoot() ?? process.cwd();
+        const files = (await fg(g, {
+            cwd,
             onlyFiles: true,
             dot: true,
             ignore: IGNORE,
-        });
+            followSymbolicLinks: false, // 不跟随软链目录,防经软链扫到牢外文件
+            throwErrorOnBrokenSymbolicLink: false,
+        })).filter((f) => isInsideRoot(f)); // 后置兜底:仅留牢内
         const results = [];
         let scanned = 0;
         for (const f of files) {
@@ -37,10 +41,11 @@ export const grepTool = {
                 break;
             let content;
             try {
-                content = await readFile(resolve(f), 'utf8');
+                // jailResolve:realpath 化,防「牢内文件软链→牢外」的内容泄露;越界/不可读均 catch 跳过
+                content = await readFile(jailResolve(f), 'utf8');
             }
             catch {
-                continue; // 跳过无法读的文件(二进制/权限)
+                continue; // 跳过无法读的文件(二进制/权限/沙箱越界)
             }
             scanned++;
             const lines = content.split(/\r?\n/);

package/dist/tools/builtins/index.js

@@ -8,14 +8,17 @@ 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,
@@ -24,13 +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

@@ -3,7 +3,7 @@ import { forgetEntry } from '../../memory/store.js';
 // 遗忘:默认归档(archived,从索引/默认搜索隐藏,可复活);mode=delete 硬删。pinned 拒删。
 export const memoryForgetTool = {
     name: 'memory_forget',
-    description: '遗忘一条记忆:默认归档(archived,从索引/默认搜索隐藏,可经 memory_update 复活);mode=delete 硬删。pinned 条目拒删(先 memory_update pinned=false 解钉)。',
+    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: {
@@ -11,7 +11,7 @@ export const memoryForgetTool = {
             mode: {
                 type: 'string',
                 enum: ['archive', 'delete'],
-                description: '默认 archive',
+                description: 'Default archive',
             },
         },
         required: ['id'],

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

@@ -3,7 +3,7 @@ import { listEntries } from '../../memory/store.js';
 // 列索引(id/name/summary,无正文、不 bump recall)。用于浏览有哪些、拿 id 再 memory_search 取正文。
 export const memoryListTool = {
     name: 'memory_list',
-    description: '列出记忆索引(id/name/summary,不含正文)。默认列 active。拿 id 再 memory_search 取正文。',
+    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: {
@@ -14,7 +14,7 @@ export const memoryListTool = {
             status: {
                 type: 'string',
                 enum: ['active', 'superseded', 'archived', 'any'],
-                description: '默认 active',
+                description: 'Default active',
             },
         },
     },

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

@@ -4,23 +4,23 @@ import { saveEntry } from '../../memory/store.js';
 // 撞库(name→id 已存在)拒绝,引导用 memory_update。
 export const memorySaveTool = {
     name: 'memory_save',
-    description: '保存一条长期记忆(跨会话)。只存非显然、长期有用的事实/决策/坑。启动时标题进索引,详情按需 memory_search 取。',
+    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: '简短唯一标题(转成 id,撞库会拒绝)' },
-            summary: { type: 'string', description: '一句话摘要(进索引,尽量短)' },
-            body: { type: 'string', description: '完整内容(细节/上下文/证据)' },
+            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: '分类,默认 fact',
+                description: 'Category, default fact',
             },
-            pinned: { type: 'boolean', description: '钉住(豁免自动遗忘衰减),默认 false' },
+            pinned: { type: 'boolean', description: 'Pin (exempt from auto-forgetting decay), default false' },
             scope: {
                 type: 'string',
                 enum: ['project', 'global'],
-                description: '存到项目级(<cwd>/.mocode/)还是全局(~/.mocode/),默认 project',
+                description: 'Store at project level (<cwd>/.mocode/) or global (~/.mocode/), default project',
             },
         },
         required: ['name', 'summary', 'body'],

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

@@ -4,11 +4,11 @@ import { searchEntries } from '../../memory/store.js';
 // 结果走 capToolResultForHistory 的放宽上限(同 use_skill,保正文完整)。
 export const memorySearchTool = {
     name: 'memory_search',
-    description: '按关键词搜索记忆正文(多词子串匹配,按相关度排),返回匹配条目全文。命中记一次召回(影响遗忘衰减)。',
+    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: '关键词(id 或 name 里的词效果最好)' },
+            query: { type: 'string', description: 'Keywords (words in id or name work best)' },
             type: {
                 type: 'string',
                 enum: ['decision', 'fact', 'pitfall', 'reference', 'feedback'],
@@ -16,9 +16,9 @@ export const memorySearchTool = {
             status: {
                 type: 'string',
                 enum: ['active', 'superseded', 'archived', 'any'],
-                description: '默认 active(只搜活的)',
+                description: 'Default active (only search live entries)',
             },
-            limit: { type: 'integer', description: '返回条数,默认 5,上限 20' },
+            limit: { type: 'integer', description: 'Number of entries to return, default 5, max 20' },
         },
         required: ['query'],
     },

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

@@ -3,16 +3,16 @@ import { updateEntry } from '../../memory/store.js';
 // 原地改一条记忆(id 不变)。反思的弱意义:干活时发现事实变了/过时即纠正。
 export const memoryUpdateTool = {
     name: 'memory_update',
-    description: '更新一条记忆(id 不变)。用于事实变了/纠正过时/补 summary 或 body/切换 pinned。id 从 memory_list 或 memory_search 拿。',
+    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: '新摘要(只传要改的字段)' },
-            body: { type: 'string', description: '新正文(只传要改的字段)' },
-            name: { type: 'string', description: '新标题(id 不随 name 变)' },
-            pinned: { type: 'boolean', description: '切换钉住状态(true 钉住豁免衰减 / false 解钉)' },
-            reason: { type: 'string', description: '更新理由(记入 lastUpdateReason,便于追溯)' },
+            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'],
     },

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'],
     },