minimal-agent 0.10.0 → 0.12.0

package/src/tools/effectiveToolSet.js

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+import { filterToolsForRuntime } from '../runtime/agentRuntimeContext.js';
+const toolIds = new WeakMap();
+let nextToolId = 1;
+const effectiveSetCache = new Map();
+function identity(tool) {
+    let id = toolIds.get(tool);
+    if (id === undefined) {
+        id = nextToolId++;
+        toolIds.set(tool, id);
+    }
+    return id;
+}
+/**
+ * Resolve the host-visible tool catalog once for a run. The returned set is
+ * both what the model sees and the execution boundary; callers must not
+ * reconstruct capabilities from ALL_TOOLS later in the call chain.
+ */
+export function createEffectiveToolSet(input) {
+    const resolvedAvailability = new Map(input.availableTools.map((tool) => [
+        tool,
+        tool.resolveAvailability?.(input.runtime) ?? { available: true, signature: 'always' },
+    ]));
+    const availability = input.availableTools.map((tool) => {
+        const resolved = resolvedAvailability.get(tool);
+        return `${tool.name}:${resolved.available}:${resolved.signature}`;
+    });
+    const cacheKey = [
+        input.runtime.cwd,
+        input.runtime.surface,
+        input.runtime.profile,
+        input.runtime.memoryAccess,
+        input.runtime.browser?.supervised === true ? 'supervised-browser' : 'no-browser',
+        input.runtime.computer ? 'computer' : 'no-computer',
+        input.availableTools.map(identity).join(','),
+        availability.join(','),
+        input.allowedNames?.join(',') ?? '*',
+        input.requiredNames?.join(',') ?? '',
+    ].join('|');
+    const cached = effectiveSetCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const allowed = input.allowedNames === undefined
+        ? undefined
+        : new Set(input.allowedNames);
+    const requested = allowed === undefined
+        ? input.availableTools
+        : input.availableTools.filter((tool) => allowed.has(tool.name));
+    const tools = filterToolsForRuntime(requested, input.runtime, resolvedAvailability);
+    const names = new Set(tools.map((tool) => tool.name));
+    const requiredNames = new Set((input.requiredNames ?? []).filter((name) => names.has(name)));
+    const schemaIdentity = tools.map((tool) => ({
+        name: tool.name,
+        description: typeof tool.description === 'function'
+            ? tool.description()
+            : tool.description,
+        parameters: tool.parameters,
+    }));
+    const signature = createHash('sha256')
+        .update(JSON.stringify(schemaIdentity))
+        .digest('hex');
+    const result = Object.freeze({
+        tools: Object.freeze([...tools]),
+        names,
+        signature,
+        requiredNames,
+    });
+    effectiveSetCache.set(cacheKey, result);
+    if (effectiveSetCache.size > 128) {
+        effectiveSetCache.delete(effectiveSetCache.keys().next().value);
+    }
+    return result;
+}

package/src/tools/effectiveToolSet.ts

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import type { AgentRuntimeContext } from '../runtime/agentRuntimeContext.js';
+import type { Tool } from '../types.js';
+import { filterToolsForRuntime } from '../runtime/agentRuntimeContext.js';
+
+export interface EffectiveToolSet {
+  readonly tools: Tool[];
+  readonly names: ReadonlySet<string>;
+  readonly signature: string;
+  readonly requiredNames: ReadonlySet<string>;
+}
+
+const toolIds = new WeakMap<Tool, number>();
+let nextToolId = 1;
+const effectiveSetCache = new Map<string, EffectiveToolSet>();
+
+function identity(tool: Tool): number {
+  let id = toolIds.get(tool);
+  if (id === undefined) {
+    id = nextToolId++;
+    toolIds.set(tool, id);
+  }
+  return id;
+}
+
+/**
+ * Resolve the host-visible tool catalog once for a run. The returned set is
+ * both what the model sees and the execution boundary; callers must not
+ * reconstruct capabilities from ALL_TOOLS later in the call chain.
+ */
+export function createEffectiveToolSet(input: {
+  availableTools: readonly Tool[];
+  runtime: AgentRuntimeContext;
+  allowedNames?: readonly string[];
+  requiredNames?: readonly string[];
+}): EffectiveToolSet {
+  const resolvedAvailability = new Map(input.availableTools.map((tool) => [
+    tool,
+    tool.resolveAvailability?.(input.runtime) ?? { available: true, signature: 'always' },
+  ] as const));
+  const availability = input.availableTools.map((tool) => {
+    const resolved = resolvedAvailability.get(tool)!;
+    return `${tool.name}:${resolved.available}:${resolved.signature}`;
+  });
+  const cacheKey = [
+    input.runtime.cwd,
+    input.runtime.surface,
+    input.runtime.profile,
+    input.runtime.memoryAccess,
+    input.runtime.browser?.supervised === true ? 'supervised-browser' : 'no-browser',
+    input.runtime.computer ? 'computer' : 'no-computer',
+    input.availableTools.map(identity).join(','),
+    availability.join(','),
+    input.allowedNames?.join(',') ?? '*',
+    input.requiredNames?.join(',') ?? '',
+  ].join('|');
+  const cached = effectiveSetCache.get(cacheKey);
+  if (cached) return cached;
+  const allowed = input.allowedNames === undefined
+    ? undefined
+    : new Set(input.allowedNames);
+  const requested = allowed === undefined
+    ? input.availableTools
+    : input.availableTools.filter((tool) => allowed.has(tool.name));
+  const tools = filterToolsForRuntime(requested, input.runtime, resolvedAvailability);
+  const names = new Set(tools.map((tool) => tool.name));
+  const requiredNames = new Set(
+    (input.requiredNames ?? []).filter((name) => names.has(name)),
+  );
+  const schemaIdentity = tools.map((tool) => ({
+    name: tool.name,
+    description: typeof tool.description === 'function'
+      ? tool.description()
+      : tool.description,
+    parameters: tool.parameters,
+  }));
+  const signature = createHash('sha256')
+    .update(JSON.stringify(schemaIdentity))
+    .digest('hex');
+  const result = Object.freeze({
+    tools: Object.freeze([...tools]) as unknown as Tool[],
+    names,
+    signature,
+    requiredNames,
+  });
+  effectiveSetCache.set(cacheKey, result);
+  if (effectiveSetCache.size > 128) {
+    effectiveSetCache.delete(effectiveSetCache.keys().next().value!);
+  }
+  return result;
+}

package/src/tools/genimage/genimage.ts

@@ -0,0 +1,257 @@
+/**
+ * ============================================================
+ *  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 type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+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'),
+});
+type GenImageInput = z.infer<typeof inputSchema>;
+
+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(): string | null {
+  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: string): string {
+  return text.replace(TLS_WARNING_RE, '').trim();
+}
+
+function collectProgressSummary(stderr: string): string {
+  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: (line: string) => void,
+): (chunk: string) => void {
+  let buf = '';
+  return (chunk: string) => {
+    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: GenImageInput, signal?: AbortSignal, ctx?: ToolCallContext): Promise<ToolResult> {
+  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<ToolResult>((resolvePromise) => {
+    let child: ReturnType<typeof spawn>;
+    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 as Error).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: Tool<GenImageInput> = {
+  name: 'GenerateImage',
+  description,
+  inputSchema,
+  parameters,
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  call: (input, signal) => call(input, signal),
+  callWithContext: call,
+};

package/src/tools/genspeech/genspeech.ts

@@ -0,0 +1,83 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { z } from 'zod';
+
+import { configService } from '../../config/configService.js';
+import type { Tool, ToolResult } from '../../types.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'),
+});
+
+type SpeechInput = z.infer<typeof inputSchema>;
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+async function call(input: SpeechInput, signal?: AbortSignal): Promise<ToolResult> {
+  return callWith(input, signal, async () => configService.tool('textToSpeech'), fetch);
+}
+
+async function callWith(
+  input: SpeechInput,
+  signal: AbortSignal | undefined,
+  getConfig: () => ReturnType<typeof configService.tool<'textToSpeech'>>,
+  fetchImpl: FetchLike,
+): Promise<ToolResult> {
+  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) as {
+      data?: { audio?: string };
+      base_resp?: { status_code?: number; status_msg?: string };
+    } | 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: () => ReturnType<typeof configService.tool<'textToSpeech'>> = async () => configService.tool('textToSpeech'),
+  fetchImpl: FetchLike = fetch,
+): Tool<SpeechInput> {
+  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();