minimal-agent 0.9.0 → 0.10.0

package/src/tools/download/download.js

@@ -0,0 +1,144 @@
+/**
+ * ============================================================
+ *  src/tools/download/download.ts —— Download 工具（URL → 文件）
+ * ------------------------------------------------------------
+ *  通用基础能力：把一个 URL 的字节流下载落盘。填补 WebFetch（HTML→markdown，
+ *  读文本用）与 Bash（curl/Invoke-WebRequest，跨平台脆）之间的空白——纯 YAML
+ *  工作流要「把图片/资产存盘」时用它（如 illustrate 配图工作流逐图下载候选）。
+ *
+ *  输入：
+ *    url       必填，http(s) 资源地址
+ *    path      必填，落盘路径（相对 getWorkingDir 锚定；绝对路径原样）
+ *    headers   可选，自定义请求头（如 Referer/User-Agent，绕部分防盗链）
+ *    timeout   可选，毫秒，默认 60000（无新字节判死由 fetch/AbortSignal 控）
+ *    max_bytes 可选，体积上限（默认 25MB；超限不写、报错，防失控）
+ *
+ *  输出：成功 = { ok, content: "DOWNLOADED: <bytes> → <path> (<content-type>)" }；
+ *        失败 = { ok:false, error } —— 不抛异常，error 喂回 LLM（同全项目工具约定）。
+ *
+ *  可测：fetch 经 deps 注入（不连真网）；落盘走真实 fs（测试用 tmp 目录）。
+ * ============================================================
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { z } from 'zod';
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+// ---------------- 1. Zod 输入 schema ----------------
+const inputSchema = z.object({
+    url: z.string().url().describe('http(s) resource URL to download'),
+    path: z
+        .string()
+        .describe('Destination file path (relative paths anchor to the working dir)'),
+    headers: z
+        .record(z.string())
+        .optional()
+        .describe('Optional request headers (e.g. Referer/User-Agent to bypass hotlink guards)'),
+    timeout: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Timeout in milliseconds (default: 60000)'),
+    max_bytes: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Max size in bytes; over this the download is rejected (default: 25MB)'),
+});
+const parameters = toToolParameters(inputSchema);
+const description = `Download a URL to a local file (raw bytes).
+
+When to use Download vs WebFetch:
+- WebFetch: read a web page as markdown text (for the model to consume).
+- Download: save the raw bytes of a resource (image / pdf / asset) to disk.
+
+Input parameters:
+  - url (required): http(s) URL.
+  - path (required): destination file path (relative paths anchor to the working dir; parent dirs are created).
+  - headers (optional): request headers (e.g. Referer/User-Agent to bypass hotlink protection).
+  - timeout (optional): milliseconds (default 60000).
+  - max_bytes (optional): reject downloads larger than this (default 25MB).
+
+Notes:
+  - Returns an error (not an exception) on HTTP failure / timeout / oversize.
+  - Overwrites an existing file at path.`;
+const defaultDeps = {
+    fetchImpl: globalThis.fetch,
+};
+// ---------------- 3. call() ----------------
+async function call(input, signal, deps = defaultDeps) {
+    const { url, path } = input;
+    const timeout = input.timeout ?? DEFAULT_TIMEOUT_MS;
+    const maxBytes = input.max_bytes ?? DEFAULT_MAX_BYTES;
+    const abs = isAbsolute(path) ? path : resolve(join(getWorkingDir(), path));
+    // 合并外部 signal 与超时
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeout);
+    if (signal) {
+        if (signal.aborted)
+            ctrl.abort();
+        else
+            signal.addEventListener('abort', () => ctrl.abort(), { once: true });
+    }
+    try {
+        let res;
+        try {
+            res = await deps.fetchImpl(url, { headers: input.headers, signal: ctrl.signal });
+        }
+        catch (e) {
+            const msg = ctrl.signal.aborted
+                ? `下载超时（${timeout}ms）或被中断`
+                : e instanceof Error
+                    ? e.message
+                    : String(e);
+            return { ok: false, error: `[Download] 请求失败：${msg}（${url}）` };
+        }
+        if (!res.ok) {
+            return {
+                ok: false,
+                error: `[Download] HTTP ${res.status} ${res.statusText}（${url}）`,
+            };
+        }
+        // content-length 预检（有则提前拒绝超大文件，省下载）
+        const declared = Number(res.headers.get('content-length') ?? '');
+        if (Number.isFinite(declared) && declared > maxBytes) {
+            return {
+                ok: false,
+                error: `[Download] 体积 ${declared} 字节超过上限 ${maxBytes}（${url}）`,
+            };
+        }
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.byteLength > maxBytes) {
+            return {
+                ok: false,
+                error: `[Download] 下载 ${buf.byteLength} 字节超过上限 ${maxBytes}（${url}）`,
+            };
+        }
+        await mkdir(dirname(abs), { recursive: true });
+        await writeFile(abs, buf);
+        const ctype = res.headers.get('content-type') ?? 'unknown';
+        return {
+            ok: true,
+            content: `DOWNLOADED: ${buf.byteLength} 字节 → ${abs}（${ctype}）`,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ---------------- 4. 导出 ----------------
+export const downloadTool = {
+    name: 'Download',
+    description,
+    inputSchema,
+    parameters,
+    isReadOnly: false,
+    isConcurrencySafe: true,
+    call,
+};
+// 供单测：直接调 call 注入 deps。
+export const _downloadCall = call;

package/src/tools/edit/edit.js

@@ -276,5 +276,6 @@ export const editTool = {
     isReadOnly: false,
     isConcurrencySafe: false,
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+    interruptBehavior: () => 'block',
     call,
 };

package/src/tools/edit/multi-edit.js

@@ -175,5 +175,6 @@ export const multiEditTool = {
     isReadOnly: false,
     isConcurrencySafe: false,
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+    interruptBehavior: () => 'block',
     call,
 };

package/src/tools/genimage/genimage.js

@@ -0,0 +1,242 @@
+/**
+ * ============================================================
+ *  src/tools/genimage/genimage.ts —— GenerateImage 工具
+ * ------------------------------------------------------------
+ *  专用「图像生成」工具：按 img_plan.json 批量生成 PPT 配图（文生图 / 图生图）。
+ *
+ *  为什么要专用工具、而不是用 Bash 跑脚本（用户拍板·Claude Code 同款）：
+ *  ─────────────────────────────────────────────────────────
+ *  图像生成是**专用的长时操作**（单张 Seedream ~50s，一批 5 张 ~250s）。
+ *  通用 Bash 工具默认超时 120s、硬上限 600s（src/tools/bash/bash.ts），
+ *  用它跑生图必然把整批**在中途 SIGKILL**（实测两次都杀在第 3 张）。
+ *  Bash 该是「最后兜底」，专用长操作应封装专用工具——本工具**无 120s 帽**，
+ *  仅凭 `ctx.signal`（Ctrl+C/ESC）中断，配合脚本自身的「总时长自限 + 降级」，
+ *  让生图永不被误杀、AI 配图失败也优雅退化、绝不阻断工作流。
+ *
+ *  薄封装：HTTP 双协议 / 重试 / 降级写占位逻辑仍住 `skills/ai-image`
+ *  （generate_from_plan.mjs + generate.mjs），本工具只负责「无帽地把它跑完、
+ *  收口成 ToolResult」，不重写生图逻辑（守减法 + 三层解耦）。
+ * ============================================================
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { z } from 'zod';
+import { trustedToolEnv } from '../../config/configService.js';
+import { getResourceSearchPaths } from '../../utils/resourcePaths.js';
+import { killTree } from '../shared/killTree.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+// ---------------- 1. Zod 输入 schema ----------------
+const inputSchema = z.object({
+    plan: z
+        .string()
+        .optional()
+        .describe('img_plan.json 路径（每条 {file,mode,prompt,...}）；默认 ./build/img_plan.json'),
+    assets: z
+        .string()
+        .optional()
+        .describe('图片输出目录（客户原图也在这）；默认 <plan 同级>/assets 或 ./build/assets'),
+    size: z.string().optional().describe('生成尺寸档（透传 generate.mjs，默认 1K）'),
+    timeout_ms: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('单张生成超时（毫秒，透传 generate_from_plan 的 --timeout-ms，默认 600000=10min）'),
+    wall_budget_ms: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        // 成本不计、最大努力生图：预算放宽到 60min，防尾部图撞预算被误降级。
+        .describe('整批总时长预算（毫秒）；超了把剩余图全部走降级占位、主动收尾。默认 3600000=60min'),
+    retry_degraded_report: z
+        .string()
+        .optional()
+        .describe('只重试某次 image_generation_report.json 里的 degraded 条目'),
+    concurrency: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('批内并发生成张数（透传 generate_from_plan 的 --concurrency，默认 1=顺序）'),
+    max_rounds: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('重试轮数；配合 retry_degraded_report 使用时默认 3'),
+});
+const parameters = toToolParameters(inputSchema);
+const description = `按 img_plan.json 批量生成 PPT 配图（文生图 / 图生图），专为长时图像生成设计。
+- 无 120s 超时帽（区别于 Bash），仅响应 Ctrl+C/ESC 中断；适合一批多张图（每张可达分钟级）。
+- 内建优雅退化：单张失败（敏感内容/超时/网络/空输出）会写降级占位资产（图生图退回原图、文生图写渐变背景），**绝不让 deck 坏图、绝不阻断工作流**。
+- 输入 plan（默认 ./build/img_plan.json）+ assets（默认同级 assets）。空 plan / 无 plan 直接跳过。`;
+/** 在 skills 搜索路径里定位 ai-image 的生图编排脚本。 */
+function locateScript() {
+    for (const base of getResourceSearchPaths('skills', import.meta.url)) {
+        const p = join(base, 'ai-image', 'scripts', 'generate_from_plan.mjs');
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+const TLS_WARNING_RE = /Warning: Setting the NODE_TLS_REJECT_UNAUTHORIZED environment variable to '0'[\s\S]*?\(Use `node --trace-warnings \.\.\.`[\s\S]*?\)\n?/g;
+function stripKnownNoise(text) {
+    return text.replace(TLS_WARNING_RE, '').trim();
+}
+function collectProgressSummary(stderr) {
+    const lines = stripKnownNoise(stderr)
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('[ai-image-plan]'));
+    if (lines.length === 0)
+        return '';
+    const uniqueTail = [...new Set(lines)].slice(-6);
+    return uniqueTail.join('\n');
+}
+/**
+ * 步内实时进度：把子进程 stderr 流按行切分（chunk 可能把一行切成两半，必须缓冲），
+ * 只把 `[ai-image-plan] …` 进度行交给 onLine。导出供单测直接喂「切断的 chunk 流」。
+ * 治「31 张生图 ~13 分钟 TUI 全程静默被误判死机」（2026-07-02 事故）——
+ * generate_from_plan.mjs 本就逐张打进度到 stderr，此前只在结束后汇总，运行中无人消费。
+ */
+export function createProgressLineFeed(onLine) {
+    let buf = '';
+    return (chunk) => {
+        buf += chunk;
+        let idx = buf.indexOf('\n');
+        while (idx >= 0) {
+            const line = buf.slice(0, idx).trim();
+            buf = buf.slice(idx + 1);
+            if (line.startsWith('[ai-image-plan]'))
+                onLine(line);
+            idx = buf.indexOf('\n');
+        }
+    };
+}
+// killTree（中断杀整棵进程树）已升为共享 util —— 见 ../shared/killTree.js
+// （两次规则：genimage + bash 长命令都需要，2026-07-02 生图事故的同类问题在 Bash 复现）。
+// ---------------- call() ----------------
+async function call(input, signal, ctx) {
+    const planPath = resolve(input.plan ?? './build/img_plan.json');
+    const assetsDir = resolve(input.assets ?? join(dirname(planPath), 'assets'));
+    if (!existsSync(planPath)) {
+        return { ok: true, content: `PLAN_EMPTY: ${planPath} 不存在，跳过生图。` };
+    }
+    const script = locateScript();
+    if (!script) {
+        // 找不到脚本也不抛、不 halt——工作流靠 deck 已写的 enhanced/原图引用降级（onError:continue）。
+        return {
+            ok: false,
+            error: 'GenerateImage: 未找到 skills/ai-image/scripts/generate_from_plan.mjs（已跳过，不阻断）。',
+        };
+    }
+    const cmd = [
+        script,
+        '--plan',
+        planPath,
+        '--assets',
+        assetsDir,
+        '--timeout-ms',
+        String(input.timeout_ms ?? 600_000),
+        '--wall-budget-ms',
+        // 成本不计、最大努力生图：默认 60min（原 25min 偏紧，尾部图常撞预算被降级）。
+        String(input.wall_budget_ms ?? 3_600_000),
+        '--size',
+        input.size ?? '1K',
+    ];
+    if (input.retry_degraded_report) {
+        cmd.push('--retry-degraded-report', resolve(input.retry_degraded_report));
+    }
+    if (input.max_rounds) {
+        cmd.push('--max-rounds', String(input.max_rounds));
+    }
+    if (input.concurrency) {
+        cmd.push('--concurrency', String(input.concurrency));
+    }
+    const trustedEnv = await trustedToolEnv('imageGeneration');
+    return await new Promise((resolvePromise) => {
+        let child;
+        try {
+            // 用 `node` 跑 .mjs（与既有 Bash 步一致；绿色版同样依赖 node 在 PATH）。
+            // POSIX 下 detached 自成进程组，中断时 kill(-pid) 才能掀到孙进程（见 killTree）；
+            // win32 走 taskkill /T，不需要（也不该）detached。
+            child = spawn('node', cmd, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: { ...trustedEnv, MINIMAL_AGENT_CAPTURED_STDIO: '1' },
+                detached: process.platform !== 'win32',
+            });
+        }
+        catch (e) {
+            resolvePromise({ ok: false, error: `GenerateImage 启动失败：${e.message}（不阻断）` });
+            return;
+        }
+        let out = '';
+        let errOut = '';
+        // taskkill /F 杀掉的子进程在 win32 上 close 时 signal=null、exit code 非 0，
+        // 单看 sig 判不出「被用户中断」——用本地 flag 记账，close 时据此正确报「被中断」。
+        let killedByAbort = false;
+        const onAbort = () => {
+            killedByAbort = true;
+            killTree(child);
+        };
+        if (signal) {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener('abort', onAbort, { once: true });
+        }
+        // 步内实时进度通过调用级上下文上报，精确关联到当前 toolCallId。
+        const feedProgress = createProgressLineFeed((line) => ctx?.reportProgress?.(line));
+        child.stdout?.on('data', (d) => {
+            out += d.toString();
+        });
+        child.stderr?.on('data', (d) => {
+            const text = d.toString();
+            errOut += text;
+            feedProgress(text);
+        });
+        child.on('error', (e) => {
+            if (signal)
+                signal.removeEventListener('abort', onAbort);
+            resolvePromise({ ok: false, error: `GenerateImage 子进程错误：${e.message}（不阻断）` });
+        });
+        child.on('close', (code, sig) => {
+            if (signal)
+                signal.removeEventListener('abort', onAbort);
+            // 末行结局：脚本降级时仍 exit 0（IMAGE_PLAN_OK/DEGRADED）；exit≠0 仅结构/安全 bug。
+            const tail = (out + '\n' + errOut)
+                .split('\n')
+                .filter((l) => /IMAGE_PLAN_(OK|DEGRADED|FAILED|EMPTY|ERROR)/.test(l))
+                .join('\n')
+                .trim();
+            const progress = collectProgressSummary(errOut);
+            const summaryParts = [
+                tail || `生图结束（exit ${code ?? 'null'}${sig ? ` ${sig}` : ''}）`,
+                progress ? `进度摘要：\n${progress}` : '',
+            ].filter(Boolean);
+            const summary = summaryParts.join('\n');
+            if (killedByAbort || sig === 'SIGTERM') {
+                resolvePromise({ ok: false, error: `GenerateImage 被中断（${sig ?? `exit ${code ?? '?'}`}）。${summary}` });
+            }
+            else if ((code ?? 1) === 0) {
+                resolvePromise({ ok: true, content: summary });
+            }
+            else {
+                // 结构/安全校验失败（计划 bug）——报错但不抛；工作流 onError:continue 兜底。
+                resolvePromise({ ok: false, error: summary });
+            }
+        });
+    });
+}
+export const genImageTool = {
+    name: 'GenerateImage',
+    description,
+    inputSchema,
+    parameters,
+    isReadOnly: false,
+    isConcurrencySafe: false,
+    call: (input, signal) => call(input, signal),
+    callWithContext: call,
+};

package/src/tools/genspeech/genspeech.js

@@ -0,0 +1,67 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { z } from 'zod';
+import { configService } from '../../config/configService.js';
+import { resolveToolPath } from '../shared/fileUtils.js';
+import { filePathField } from '../shared/schemas.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+const inputSchema = z.object({
+    text: z.string().min(1).max(10_000).describe('要合成的文本'),
+    output: filePathField('写入').describe('工作目录内的 MP3 输出路径'),
+    voice: z.string().optional().describe('MiniMax voice_id，默认 female-shaonv'),
+    speed: z.number().min(0.5).max(2).optional().describe('语速，0.5 到 2.0，默认 1'),
+});
+async function call(input, signal) {
+    return callWith(input, signal, async () => configService.tool('textToSpeech'), fetch);
+}
+async function callWith(input, signal, getConfig, fetchImpl) {
+    const config = await getConfig();
+    if (!config)
+        return { ok: false, error: '尚未配置 MiniMax 语音。请在 KakadeAI 设置 → 工具中配置。' };
+    const output = resolveToolPath(input.output);
+    if (!output.ok)
+        return output;
+    try {
+        const url = new URL('/v1/t2a_v2', 'https://api.minimax.chat');
+        url.searchParams.set('GroupId', config.groupId);
+        const response = await fetchImpl(url, {
+            method: 'POST',
+            signal,
+            headers: { Authorization: `Bearer ${config.apiKey}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                model: 'speech-01',
+                text: input.text,
+                voice_setting: { voice_id: input.voice ?? 'female-shaonv', speed: input.speed ?? 1 },
+                audio_setting: { format: 'mp3' },
+            }),
+        });
+        const payload = await response.json().catch(() => null);
+        const hex = payload?.data?.audio?.replace(/\s+/g, '');
+        if (!response.ok || !hex || !/^[0-9a-f]+$/i.test(hex) || hex.length % 2 !== 0) {
+            const detail = payload?.base_resp?.status_msg || `HTTP ${response.status}`;
+            return { ok: false, error: `MiniMax 语音生成失败：${detail}` };
+        }
+        const audio = Buffer.from(hex, 'hex');
+        if (audio.length < 128)
+            return { ok: false, error: 'MiniMax 返回的音频数据为空或不完整' };
+        await mkdir(dirname(output.resolvedPath), { recursive: true });
+        await writeFile(output.resolvedPath, audio, { mode: 0o600 });
+        return { ok: true, content: `saved: ${input.output} (provider=minimax, size=${audio.length})` };
+    }
+    catch (error) {
+        if (signal?.aborted)
+            return { ok: false, error: '语音生成已取消' };
+        return { ok: false, error: `MiniMax 语音生成失败：${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+export function createGenerateSpeechTool(getConfig = async () => configService.tool('textToSpeech'), fetchImpl = fetch) {
+    return {
+        name: 'GenerateSpeech',
+        description: '使用已配置的 MiniMax TTS 安全生成 MP3。凭据由受控工具读取，不会暴露给 Bash、日志或模型。',
+        inputSchema,
+        parameters: toToolParameters(inputSchema),
+        isReadOnly: false,
+        call: (input, signal) => callWith(input, signal, getConfig, fetchImpl),
+    };
+}
+export const generateSpeechTool = createGenerateSpeechTool();

package/src/tools/glob/glob.js

@@ -93,5 +93,6 @@ export const globTool = {
     isReadOnly: true,
     isConcurrencySafe: true,
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+    interruptBehavior: () => 'cancel',
     call,
 };

package/src/tools/grep/grep.js

@@ -18,6 +18,7 @@ import { spawn } from 'node:child_process';
 import { resolve } from 'node:path';
 import { z } from 'zod';
 import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import { sanitizeCredentialEnv } from '../../config/configService.js';
 import { resolveRgPath } from './rgPath.js';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
@@ -123,6 +124,7 @@ async function call(input, signal) {
         await new Promise((resolveP, rejectP) => {
             const child = spawn(rgPath, args, {
                 cwd: getWorkingDir(),
+                env: sanitizeCredentialEnv(),
                 signal,
                 windowsHide: true,
             });
@@ -181,5 +183,6 @@ export const grepTool = {
     isReadOnly: true,
     isConcurrencySafe: true,
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+    interruptBehavior: () => 'cancel',
     call,
 };

package/src/tools/grep/rgPath.js

@@ -26,6 +26,7 @@
 import { spawn } from 'node:child_process';
 import { chmodSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { sanitizeCredentialEnv } from '../../config/configService.js';
 import { execSiblingDir } from '../../utils/greenRoot.js';
 import { findPackageRoot } from '../../utils/packageRoot.js';
 let cached;
@@ -125,6 +126,7 @@ function trySpawn(cmd) {
         try {
             const child = spawn(cmd, ['--version'], {
                 stdio: ['ignore', 'pipe', 'ignore'],
+                env: sanitizeCredentialEnv(),
                 windowsHide: true,
             });
             let stdout = '';

package/src/tools/index.js

@@ -12,10 +12,18 @@
  *  这层是"防线"：模型给的参数永远不可信，必须 Zod 校验后才进 call()。
  * ============================================================
  */
+import { advisorTool } from './advisor/advisor.js';
+// ⚠️ agent.ts 与本模块构成环（tools/index → agent → loop → tools/index）：
+// agent.ts 顶层不求值本模块/loop 的任何导出、loop.ts 的工具 token 估算已懒化，
+// 环在运行时是安全的（详见 agent.ts 文件头「循环依赖纪律」）。
+import { agentTool } from './agent/agent.js';
 import { askUserQuestionTool } from './ask/ask.js';
 import { bashTool } from './bash/bash.js';
+import { downloadTool } from './download/download.js';
 import { editTool } from './edit/edit.js';
 import { multiEditTool } from './edit/multi-edit.js';
+import { genImageTool } from './genimage/genimage.js';
+import { generateSpeechTool } from './genspeech/genspeech.js';
 import { globTool } from './glob/glob.js';
 import { grepTool } from './grep/grep.js';
 import { readTool } from './read/read.js';
@@ -34,8 +42,14 @@ export const ALL_TOOLS = [
     webSearchTool,
     webfetchTool,
     webbrowserTool,
+    downloadTool,
+    genImageTool,
+    generateSpeechTool,
     bashTool,
     askUserQuestionTool,
+    advisorTool,
+    // 追加在末尾：主循环 tools schema 的原有前缀字节不动（提示词缓存友好）
+    agentTool,
 ];
 /** 按名字查表 */
 export function getToolByName(name) {
@@ -47,11 +61,12 @@ export function getToolByName(name) {
  * @param name        工具名（来自 LLM 的 tool_call.function.name）
  * @param rawArguments LLM 给的参数 —— 注意这是 JSON 字符串，不是对象
  * @param signal      支持中断
+ * @param ctx         可选环境态透传（如 Advisor 需要的当前 history），绝大多数工具忽略
  *
  * 返回 ToolResult：失败时不抛异常，把 error 写在结果里（便于把"工具失败"
  * 当成普通 tool_result 喂回 LLM，让模型自己重试或换思路）。
  */
-export async function executeTool(name, rawArguments, signal) {
+export async function executeTool(name, rawArguments, signal, ctx) {
     // 1. 找工具
     const tool = getToolByName(name);
     if (!tool) {
@@ -81,7 +96,10 @@ export async function executeTool(name, rawArguments, signal) {
         };
     }
     // 4. 调用 call()，捕获意外异常
+    //
     try {
+        if (tool.callWithContext)
+            return await tool.callWithContext(checked.data, signal, ctx ?? {});
         return await tool.call(checked.data, signal);
     }
     catch (e) {
@@ -92,5 +110,10 @@ export async function executeTool(name, rawArguments, signal) {
     }
 }
 // 导出每个工具，方便测试单独 import
-export { readTool, editTool, writeTool, globTool, grepTool, webSearchTool, webfetchTool, webbrowserTool, bashTool, askUserQuestionTool };
+export { readTool, editTool, writeTool, globTool, grepTool, webSearchTool, webfetchTool, webbrowserTool, downloadTool, bashTool, askUserQuestionTool };
 export { multiEditTool } from './edit/multi-edit.js';
+export { genImageTool } from './genimage/genimage.js';
+export { advisorTool } from './advisor/advisor.js';
+export { agentTool } from './agent/agent.js';
+export { createGenerateSpeechTool, generateSpeechTool } from './genspeech/genspeech.js';
+export { createWebSearchTool } from './websearch/websearch.js';

package/src/tools/read/read.js

@@ -212,5 +212,6 @@ export const readTool = {
     isReadOnly: true,
     isConcurrencySafe: true,
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+    interruptBehavior: () => 'cancel',
     call,
 };

package/src/tools/shared/killTree.js

@@ -0,0 +1,52 @@
+/**
+ * ============================================================
+ *  src/tools/shared/killTree.ts —— 中断/超时时杀「整棵进程树」
+ * ------------------------------------------------------------
+ *  win32 的 `child.kill('SIGTERM')` 只 TerminateProcess **直接子进程**：在飞的孙进程
+ *  （shell 里的实际命令 / 逐张 spawn 的生图子进程 / bun test·构建·服务 …）会变孤儿继续
+ *  跑，还占着 stdout 管道让 'close' 永不触发 —— 表现为「点了停止、agent 停了、活儿还在
+ *  后台跑」的"中断看起来没生效"（2026-07-02 生图事故；同类问题后来在 Bash 长命令复现）。
+ *
+ *   - win32：`taskkill /pid <pid> /T /F` 杀整棵树；taskkill 自身失败再兜底 kill 直接子进程。
+ *   - POSIX：调用方须 `spawn({ detached: true })` 让子进程自成进程组，这里 `kill(-pid)` 掀整组；
+ *     失败兜底同上。
+ *
+ *  两个消费者（genimage / bash）都需要，按「两次规则」升为共享 util。
+ * ============================================================
+ */
+import { spawn } from 'node:child_process';
+export function killTree(child) {
+    const pid = child.pid;
+    const fallback = () => {
+        try {
+            child.kill('SIGTERM');
+        }
+        catch {
+            /* ignore */
+        }
+    };
+    if (!pid) {
+        fallback();
+        return;
+    }
+    if (process.platform === 'win32') {
+        try {
+            const killer = spawn('taskkill', ['/pid', String(pid), '/T', '/F'], {
+                stdio: 'ignore',
+                windowsHide: true,
+            });
+            killer.on('error', fallback);
+        }
+        catch {
+            fallback();
+        }
+    }
+    else {
+        try {
+            process.kill(-pid, 'SIGTERM');
+        }
+        catch {
+            fallback();
+        }
+    }
+}