mocode-ai 0.1.4 → 0.1.5

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

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

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

@@ -1,18 +1,18 @@
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { MAX_OUTPUT } from '../constants.js';
 // ---------- run_command ----------
 export const runCommandTool = {
     name: 'run_command',
-    description: '执行 shell 命令,返回合并的 stdout+stderr。默认超时 120 秒。用于跑测试、构建、git 等。',
+    description: 'Execute a shell command, returning combined stdout+stderr. Default timeout 120s. Use for running tests, builds, git, etc.',
     parameters: {
         type: 'object',
         properties: {
-            command: { type: 'string', description: '要执行的命令(单行)' },
-            timeout: { type: 'integer', description: '超时毫秒,默认120000' },
+            command: { type: 'string', description: 'Command to execute (single line)' },
+            timeout: { type: 'integer', description: 'Timeout in milliseconds, default 120000' },
         },
         required: ['command'],
     },
-    async execute(args) {
+    async execute(args, ctx) {
         const command = String(args.command);
         const timeout = Number(args.timeout ?? 120000);
         return new Promise((done) => {
@@ -20,11 +20,37 @@ export const runCommandTool = {
             const child = spawn(isWin ? 'cmd.exe' : 'bash', isWin ? ['/c', command] : ['-c', command], { cwd: process.cwd() });
             let out = '';
             let finished = false;
+            let timer;
+            // 杀整棵进程树。child.kill() 在 Windows 只杀 cmd.exe、npm 等子进程会孤儿继续跑(占锁、污染下一步),
+            // 故 Win 用 taskkill /T /F 树杀;Unix child.kill('SIGTERM')(bash -c 通常转发给前台子进程,best-effort)。
+            const killTree = () => {
+                try {
+                    if (isWin) {
+                        if (child.pid != null) {
+                            spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], {
+                                stdio: 'ignore',
+                            });
+                        }
+                    }
+                    else {
+                        child.kill('SIGTERM');
+                    }
+                }
+                catch {
+                    // 进程已退出 / kill 失败:忽略(close 事件会兜底 finish)
+                }
+            };
+            // abort(用户 Ctrl+C,经 executeTool ctx.signal 透传)→ 杀子进程树 + 返[已中断]
+            const onAbort = () => {
+                killTree();
+                finish(`[已中断]\n${out.trim()}`);
+            };
             const finish = (s) => {
                 if (finished)
                     return;
                 finished = true;
                 clearTimeout(timer);
+                ctx?.signal?.removeEventListener('abort', onAbort);
                 done(s);
             };
             const onChunk = (chunk) => {
@@ -40,10 +66,17 @@ export const runCommandTool = {
                     r += '\n...(输出已截断)';
                 finish(`[退出码 ${code}]\n${r || '(无输出)'}`);
             });
-            const timer = setTimeout(() => {
-                child.kill();
+            timer = setTimeout(() => {
+                killTree();
                 finish(`[超时,已终止]\n${out.trim()}`);
             }, timeout);
+            // 外部 abort signal:已 aborted 即时杀(防御;agent 循环顶检查通常会先拦),否则挂监听
+            if (ctx?.signal) {
+                if (ctx.signal.aborted)
+                    onAbort();
+                else
+                    ctx.signal.addEventListener('abort', onAbort, { once: true });
+            }
         });
     },
 };

package/dist/tools/builtins/switch-mode.js

@@ -0,0 +1,46 @@
+import { setAgentMode, getAgentMode } from '../../agent/mode.js';
+// ---------- switch_mode ----------
+export const switchModeTool = {
+    name: 'switch_mode',
+    description: [
+        'Switch the agent mode between "plan" (read-only investigation + planning) and "auto" (full tool execution).',
+        'In plan mode, write_file / edit_file / run_command / memory_save / memory_update / memory_forget are disabled; in auto mode, all tools are available.',
+        'Use this to autonomously transition from planning to execution WITHIN THE SAME TURN: investigate in plan mode, produce a plan, then call switch_mode("auto") and continue implementing it in the same turn — ONLY when the user has explicitly asked you to "plan first then execute" / "先 plan 再 auto" / autonomous execution.',
+        'Do NOT switch to auto if the user entered plan mode manually (via /plan or Shift+Tab) for a safety review — in that case present the plan and STOP; the user will approve via a prompt and execution happens in a follow-up turn.',
+        'Switching to plan from auto is rarely needed; do it only if you realize you should investigate before changing anything.',
+    ].join(' '),
+    parameters: {
+        type: 'object',
+        properties: {
+            mode: {
+                type: 'string',
+                enum: ['auto', 'plan'],
+                description: 'Target mode: "plan" (read-only) or "auto" (full tools)',
+            },
+        },
+        required: ['mode'],
+    },
+    async execute(args) {
+        const target = String(args.mode);
+        if (target !== 'auto' && target !== 'plan') {
+            return `错误:mode 必须是 "auto" 或 "plan",收到 "${target}"`;
+        }
+        const prev = getAgentMode();
+        if (prev === target) {
+            return `已在 ${target} 模式,无需切换。`;
+        }
+        setAgentMode(target); // 触发 listener:repl 重写 history[0] 系统提示 + 刷状态行 modeTag
+        if (target === 'auto') {
+            return [
+                `已从 plan 切换到 auto 模式。`,
+                `写盘 / 命令 / 记忆写入工具(write_file / edit_file / run_command / memory_save / memory_update / memory_forget)现已恢复可用。`,
+                `请按你刚才产出的计划继续执行(同一轮内,无需重述计划)。`,
+            ].join('\n');
+        }
+        return [
+            `已从 auto 切换到 plan 模式(只读探查)。`,
+            `写盘 / 命令 / 记忆写入工具已禁用;只用 read_file / glob / grep / codegraph / web_search / web_fetch / use_skill / ask_human / memory_search / memory_list 探查。`,
+            `产出计划后 STOP 等用户审批,或(若用户要求自主执行)再调 switch_mode("auto") 续跑。`,
+        ].join('\n');
+    },
+};

package/dist/tools/builtins/task.js

@@ -0,0 +1,62 @@
+import { spawnAgent } from '../../agent/spawn.js';
+import { MAX_OUTPUT } from '../constants.js';
+// ---------- task ----------
+// 派生子 agent 执行独立子任务。子 agent 有独立 history(不污染主对话),
+// 可受限工具子集 + 低步数上限,最终摘要回灌主 history 供主 agent 继续。
+//
+// 适用:并行探查多个文件 / 分而治之的复杂任务 / 隔离上下文避免子任务工具噪声撑爆主窗口。
+// 子 agent 中间过程不写主屏,只返回最终摘要;主 agent 据摘要决定下一步。
+export const taskTool = {
+    name: 'task',
+    description: [
+        'Spawn a sub-agent to handle an isolated sub-task with its own conversation history (independent of the main thread). The sub-agent runs to completion and returns a concise summary.',
+        'Use when: a task can be decomposed into independent sub-tasks, you want to explore multiple files/areas without polluting the main history, or a sub-task involves many tool calls that would bloat the main context window.',
+        'The sub-agent has its own history; only its final summary is returned to you as the tool result. It cannot recursively spawn further sub-agents (no "task" tool available to it).',
+        'Optionally restrict the sub-agent to a subset of tools (e.g. read-only tools for pure investigation) via the "tools" parameter.',
+    ].join(''),
+    parameters: {
+        type: 'object',
+        properties: {
+            prompt: {
+                type: 'string',
+                description: 'The sub-task instruction for the sub-agent. Be specific about what to investigate/implement and what to report back.',
+            },
+            tools: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Optional whitelist of tool names the sub-agent is allowed to use (e.g. ["read_file","glob","grep","codegraph"] for read-only investigation). Omit to allow all tools.',
+            },
+            maxSteps: {
+                type: 'number',
+                description: 'Optional step limit for the sub-agent (default 50). Lower if the sub-task should be quick.',
+            },
+        },
+        required: ['prompt'],
+    },
+    async execute(args, ctx) {
+        const prompt = String(args.prompt ?? '');
+        if (!prompt)
+            return '错误:缺少 prompt(子任务指令)。';
+        const tools = Array.isArray(args.tools)
+            ? args.tools.map((t) => String(t))
+            : undefined;
+        const maxSteps = typeof args.maxSteps === 'number' && args.maxSteps > 0
+            ? Math.floor(args.maxSteps)
+            : undefined;
+        // 透传主 agent 的 abort signal:主 Ctrl+C 树杀子 agent(chat abort + 工具 abort)。
+        const result = await spawnAgent({ prompt, tools, maxSteps, signal: ctx?.signal });
+        if (!result.completed) {
+            return '子 agent 被中断,未完成。';
+        }
+        if (!result.summary) {
+            return '子 agent 完成但未返回文本摘要(可能只调了工具或达到步数上限)。';
+        }
+        // 摘要可能很长,截到 MAX_OUTPUT 保主 history 不爆。
+        const summary = result.summary;
+        if (summary.length > MAX_OUTPUT) {
+            return (summary.slice(0, MAX_OUTPUT) +
+                `\n\n…(子 agent 摘要已截断 ${summary.length - MAX_OUTPUT} 字符)`);
+        }
+        return summary;
+    },
+};

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

@@ -4,13 +4,13 @@ import { getSkillBody } from '../../skills/index.js';
 // 系统提示里已列出可用 skill 的 name + description(何时用),模型据此决定调用。
 export const useSkillTool = {
     name: 'use_skill',
-    description: '加载并返回某个 skill 的完整 SKILL.md 指令(传 name)。何时用见系统提示的 skill 列表。',
+    description: 'Load and return the full SKILL.md instructions for a given skill (pass name). See the skill list in the system prompt for when to use each.',
     parameters: {
         type: 'object',
         properties: {
             name: {
                 type: 'string',
-                description: '要加载的 skill 名(见系统提示里的 skill 列表,或 /skills 命令)',
+                description: 'Name of the skill to load (see the skill list in the system prompt, or the /skills command)',
             },
         },
         required: ['name'],

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

@@ -4,15 +4,15 @@ const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML,
 // ---------- web_fetch ----------
 export const webFetchTool = {
     name: 'web_fetch',
-    description: '抓取指定 URL 的网页内容并清洗成纯文本(去 HTML 标签/脚本/样式,保留正文)。用于读取搜索结果里的某个链接、或用户给出的具体 URL。',
+    description: 'Fetch the web page at a given URL and clean it into plain text (strips HTML tags/scripts/styles, keeps the body). Use to read a link from search results, or a specific URL given by the user.',
     parameters: {
         type: 'object',
         properties: {
-            url: { type: 'string', description: '要抓取的完整 URL,须 http/https' },
+            url: { type: 'string', description: 'Full URL to fetch; must be http/https' },
         },
         required: ['url'],
     },
-    async execute(args) {
+    async execute(args, ctx) {
         const rawUrl = String(args.url ?? '').trim();
         if (!rawUrl)
             return '错误:url 不能为空。';
@@ -28,6 +28,15 @@ export const webFetchTool = {
         }
         const ctrl = new AbortController();
         const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+        // 外部 abort signal(用户 Ctrl+C,经 executeTool ctx.signal 透传)→ 合并到 ctrl,fetch 即时取消(不等 30s 超时)
+        const onExternalAbort = () => ctrl.abort();
+        const externalSignal = ctx?.signal;
+        if (externalSignal) {
+            if (externalSignal.aborted)
+                ctrl.abort();
+            else
+                externalSignal.addEventListener('abort', onExternalAbort, { once: true });
+        }
         try {
             const resp = await fetch(url.href, {
                 method: 'GET',
@@ -56,6 +65,8 @@ export const webFetchTool = {
         }
         catch (e) {
             if (ctrl.signal.aborted) {
+                if (externalSignal?.aborted)
+                    return `错误:已中断: ${url.href}`;
                 return `错误:抓取超时(${FETCH_TIMEOUT_MS}ms): ${url.href}`;
             }
             const msg = e instanceof Error ? e.message : String(e);
@@ -63,6 +74,8 @@ export const webFetchTool = {
         }
         finally {
             clearTimeout(timer);
+            if (externalSignal)
+                externalSignal.removeEventListener('abort', onExternalAbort);
         }
     },
 };

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

@@ -6,20 +6,20 @@ const MAX_CONTENT_CHARS = 800;
 // ---------- web_search ----------
 export const webSearchTool = {
     name: 'web_search',
-    description: '联网搜索(AnySearch)。返回每条结果的标题/URL/摘要/正文。可选 tag 切换子域(见 tag 参数)。',
+    description: 'Search the web (AnySearch). Returns title/url/snippet/body for each result. Optional tag to switch sub-domain capability (see tag param).',
     parameters: {
         type: 'object',
         properties: {
-            query: { type: 'string', description: '搜索查询词' },
-            max_results: { type: 'integer', description: '返回条数,1-20,默认 10' },
+            query: { type: 'string', description: 'Search query' },
+            max_results: { type: 'integer', description: 'Number of results, 1-20, default 10' },
             tag: {
                 type: 'string',
-                description: '子域能力标签,如 general.general / code.doc / code.snippet;不传走通用搜索',
+                description: 'Sub-domain capability tag, e.g. general.general / code.doc / code.snippet; omit for general search',
             },
-            language: { type: 'string', description: '偏好语言,如 zh-CN / en,默认 zh-CN' },
+            language: { type: 'string', description: 'Preferred language, e.g. zh-CN / en, default zh-CN' },
             params: {
                 type: 'object',
-                description: '特定 tag 的扩展参数,如 code.doc 的 {"library":"golang"};通用搜索不需要',
+                description: 'Extended params for a specific tag, e.g. {"library":"golang"} for code.doc; not needed for general search',
             },
         },
         required: ['query'],