ppxans-harness 2.4.0 → 3.2.0

package/src/tools/methods.js

@@ -1,178 +1,178 @@
-// src/tools/methods.js - 方法型 Skill (借鉴 7 大神级 Skill)
-// 零依赖: 全部通过 LLM 多阶段调用实现, 不引入外部包
-// 1. humanize       <- Humanizer-zh   : 去 AI 味
-// 2. write_article  <- writing-agent  : 分阶段写作
-// 3. clarify        <- Superpowers    : 需求澄清 (信息不足先问)
-
-// 内部: 用 agent 的 LLM 做一次无工具对话
-async function llmChat(agent, system, user) {
-  if (!agent || !agent.llm) throw new Error("未配置 LLM provider, 方法型 Skill 不可用");
-  const r = await agent.llm.chat([
-    { role: "system", content: system },
-    { role: "user", content: user },
-  ]);
-  return r.content;
-}
-
-function textOf(v, fallback) {
-  return String(v ?? fallback).trim();
-}
-
-export function registerMethodTools(catalog) {
-  // ---------- 1. humanize: 去 AI 味 (Humanizer-zh) ----------
-  catalog.register({
-    name: "humanize",
-    description: "去除文本的 AI 模板腔。检查宣传腔、过度排比、模糊归因、连接词过多、句式重复、空话套话, 返回改写的自然版本。适合公众号稿、汇报、产品介绍。",
-    parameters: {
-      type: "object",
-      properties: {
-        text: { type: "string", description: "要检查改写的文本" },
-        mode: { type: "string", enum: ["check", "rewrite"], description: "check=只列问题, rewrite=直接改写(默认)" },
-      },
-      required: ["text"],
-    },
-    execute: async (args, ctx) => {
-      const text = textOf(args.text, "");
-      if (!text) return "[工具错误] humanize: 缺少 text";
-      const mode = args.mode === "check" ? "check" : "rewrite";
-      const system = "你是文本去AI味专家。检查并消除这些痕迹: ①宣传腔/夸大空话 ②过度排比(句式重复堆叠) ③模糊归因(Experts say/行业报告称 无出处) ④连接词过多(首先/其次/总之/因此 连用) ⑤破折号狂魔 ⑥空洞收尾(未来可期/前景光明) ⑦奉承腔(Great question!/说得太对了)。输出自然、有真人质感的中文。不解释, 直接给结果。";
-      const user = mode === "rewrite"
-        ? `请改写下面文本, 保留原意但去掉所有AI腔:\n\n${text}`
-        : `请逐项检查下面文本的AI痕迹, 用列表列出问题(每项: 位置+问题+修改建议):\n\n${text}`;
-      try {
-        const out = await llmChat(ctx.agent, system, user);
-        return out || "(无输出)";
-      } catch (e) {
-        return `[工具错误] humanize: ${e.message}`;
-      }
-    },
-  });
-
-  // ---------- 2. write_article: 分阶段写作 (writing-agent) ----------
-  catalog.register({
-    name: "write_article",
-    description: "分阶段写长文: 选题→结构→初稿→审稿→修改→导出。适合公众号文章、产品介绍、课程内容、需要反复修改的长文。",
-    parameters: {
-      type: "object",
-      properties: {
-        topic: { type: "string", description: "主题" },
-        audience: { type: "string", description: "读者是谁 (可选)" },
-        length: { type: "string", description: "字数要求 (可选)" },
-        tone: { type: "string", description: "语气风格 (可选)" },
-      },
-      required: ["topic"],
-    },
-    execute: async (args, ctx) => {
-      const topic = textOf(args.topic, "");
-      if (!topic) return "[工具错误] write_article: 缺少 topic";
-      const audience = textOf(args.audience, "undefined");
-      const length = textOf(args.length, "undefined");
-      const tone = textOf(args.tone, "undefined");
-      const system = "你是资深内容创作总编。写长文必须走完整流程, 先规划再动笔, 每步都交代清楚再进下一步。";
-      const user = `写一篇关于「${topic}」的文章。\n读者: ${audience}\n字数: ${length}\n语气: ${tone}\n\n请按流程输出:\n【1.选题确认】一句话说清本文核心观点和读者收益\n【2.结构】列出大纲(标题+各段要点)\n【3.初稿】按结构写出完整正文\n【4.审稿】列出初稿的问题(事实/逻辑/语气)\n【5.修改稿】根据审稿优化后的最终版本\n【6.导出】给出可用标题(3个备选)+文章定稿`;
-      try {
-        const out = await llmChat(ctx.agent, system, user);
-        return out || "(无输出)";
-      } catch (e) {
-        return `[工具错误] write_article: ${e.message}`;
-      }
-    },
-  });
-
-  // ---------- 3. clarify: 需求澄清 (Superpowers) ----------
-  catalog.register({
-    name: "clarify",
-    description: "需求澄清: 面对模糊任务先问清需求再动手, 避免返工。传入任务描述, 返回需要澄清的问题清单; 若信息足够则直接给出执行方案。适合改代码/做项目前使用。",
-    parameters: {
-      type: "object",
-      properties: {
-        task: { type: "string", description: "任务描述" },
-        context: { type: "string", description: "已知背景/已了解的信息 (可选)" },
-      },
-      required: ["task"],
-    },
-    execute: async (args, ctx) => {
-      const task = textOf(args.task, "");
-      if (!task) return "[工具错误] clarify: 缺少 task";
-      const context = textOf(args.context, "无额外背景");
-      const system = "你是需求澄清专家。面对模糊任务, 先判断信息是否足够执行。若不足, 列出必须澄清的关键问题(≤5个, 只问真正影响执行的问题, 不啰嗦); 若已足够, 给出简明执行方案(步骤+风险+受影响的文件/模块)。不编造, 不确定就列问题。";
-      const user = `任务: ${task}\n已知背景: ${context}\n\n请判断信息是否足够, 不足则问关键问题, 足够则给执行方案。`;
-      try {
-        const out = await llmChat(ctx.agent, system, user);
-        return out || "(无输出)";
-      } catch (e) {
-        return `[工具错误] clarify: ${e.message}`;
-      }
-    },
-  });
-
-  // ---------- 场景系统: 类似灵魂文件的场景设定 ----------
-  catalog.register({
-    name: "scene_create",
-    description: "创建/更新一个场景(人设)。每个场景定义智能体在这个情境下能帮用户干什么, 类似灵魂文件。可手动设定名称/介绍/能力。",
-    parameters: {
-      type: "object",
-      properties: {
-        name: { type: "string", description: "场景名称, 如: A股交易助手" },
-        description: { type: "string", description: "场景介绍, 说明这个场景是干嘛的" },
-        canHelp: { type: "string", description: "这个场景能帮用户干什么(能力清单)" },
-        keywords: { type: "array", items: { type: "string" }, description: "触发关键词(可选)" },
-      },
-      required: ["name", "description", "canHelp"],
-    },
-    execute: async (args, ctx) => {
-      if (!ctx.agent) return "[工具错误] scene_create: 缺少 agent 上下文";
-      const s = ctx.agent.scenes.create({
-        name: args.name, description: args.description, canHelp: args.canHelp, keywords: args.keywords,
-      });
-      return JSON.stringify({ ok: true, id: s.id, name: s.name, mode: "manual" });
-    },
-  });
-
-  catalog.register({
-    name: "scene_list",
-    description: "列出所有场景及其介绍/能力。",
-    parameters: { type: "object", properties: {} },
-    execute: async (args, ctx) => {
-      if (!ctx.agent) return "[工具错误] scene_list: 缺少 agent 上下文";
-      const list = ctx.agent.scenes.listWithDesc();
-      return list.length ? list.map((s) => `- [${s.mode}] ${s.name}: ${s.description} | 能帮: ${s.canHelp} | ${s.facts}条记忆`).join("\n") : "(暂无场景)";
-    },
-  });
-
-  catalog.register({
-    name: "scene_describe",
-    description: "用 LLM 从历史对话提炼场景介绍和能力。给定场景名, 自动总结该场景的用途和能帮用户干什么。",
-    parameters: {
-      type: "object",
-      properties: { name: { type: "string", description: "要提炼的场景名" } },
-      required: ["name"],
-    },
-    execute: async (args, ctx) => {
-      const name = textOf(args.name, "");
-      if (!name) return "[工具错误] scene_describe: 缺少 name";
-      if (!ctx.agent) return "[工具错误] scene_describe: 缺少 agent";
-      // 找场景
-      const scene = ctx.agent.scenes.scenes.find((i) => i.name === name || i.name.includes(name));
-      if (!scene) return `[工具错误] scene_describe: 未找到场景 ${name}`;
-      const facts = (scene.facts || []).map((f) => f.content).slice(-10).join("\n");
-      const system = "你是场景分析器。根据场景的历史对话, 提炼出: ①场景简介(一句话) ②这个场景能帮用户干什么(能力清单, 3-5项)。直接给结果, 格式: 简介:xxx\\n能力: - xxx\\n - xxx";
-      const user = `场景: ${scene.name}\\n历史对话:\\n${facts || "(无)"}`;
-      try {
-        const out = await llmChat(ctx.agent, system, user);
-        // v1.0.9: LLM 输出未含"能力"段时保留旧值 (原 split("能力")[0] 会拿整段污染 description)
-        if (out.includes("能力")) {
-          scene.description = out.split("能力")[0].replace("简介:", "").trim().slice(0, 300) || scene.description;
-          scene.canHelp = out.split("能力")[1]?.slice(0, 300) || scene.canHelp;
-        }
-        scene.mode = "manual";
-        ctx.agent.scenes._save();
-        return out || "(无输出)";
-      } catch (e) {
-        return `[工具错误] scene_describe: ${e.message}`;
-      }
-    },
-  });
-
-  return catalog;
-}
+// src/tools/methods.js - 方法型 Skill (借鉴 7 大神级 Skill)
+// 零依赖: 全部通过 LLM 多阶段调用实现, 不引入外部包
+// 1. humanize       <- Humanizer-zh   : 去 AI 味
+// 2. write_article  <- writing-agent  : 分阶段写作
+// 3. clarify        <- Superpowers    : 需求澄清 (信息不足先问)
+
+// 内部: 用 agent 的 LLM 做一次无工具对话
+async function llmChat(agent, system, user) {
+  if (!agent || !agent.llm) throw new Error("未配置 LLM provider, 方法型 Skill 不可用");
+  const r = await agent.llm.chat([
+    { role: "system", content: system },
+    { role: "user", content: user },
+  ]);
+  return r.content;
+}
+
+function textOf(v, fallback) {
+  return String(v ?? fallback).trim();
+}
+
+export function registerMethodTools(catalog) {
+  // ---------- 1. humanize: 去 AI 味 (Humanizer-zh) ----------
+  catalog.register({
+    name: "humanize",
+    description: "去除文本的 AI 模板腔。检查宣传腔、过度排比、模糊归因、连接词过多、句式重复、空话套话, 返回改写的自然版本。适合公众号稿、汇报、产品介绍。",
+    parameters: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "要检查改写的文本" },
+        mode: { type: "string", enum: ["check", "rewrite"], description: "check=只列问题, rewrite=直接改写(默认)" },
+      },
+      required: ["text"],
+    },
+    execute: async (args, ctx) => {
+      const text = textOf(args.text, "");
+      if (!text) return "[工具错误] humanize: 缺少 text";
+      const mode = args.mode === "check" ? "check" : "rewrite";
+      const system = "你是文本去AI味专家。检查并消除这些痕迹: ①宣传腔/夸大空话 ②过度排比(句式重复堆叠) ③模糊归因(Experts say/行业报告称 无出处) ④连接词过多(首先/其次/总之/因此 连用) ⑤破折号狂魔 ⑥空洞收尾(未来可期/前景光明) ⑦奉承腔(Great question!/说得太对了)。输出自然、有真人质感的中文。不解释, 直接给结果。";
+      const user = mode === "rewrite"
+        ? `请改写下面文本, 保留原意但去掉所有AI腔:\n\n${text}`
+        : `请逐项检查下面文本的AI痕迹, 用列表列出问题(每项: 位置+问题+修改建议):\n\n${text}`;
+      try {
+        const out = await llmChat(ctx.agent, system, user);
+        return out || "(无输出)";
+      } catch (e) {
+        return `[工具错误] humanize: ${e.message}`;
+      }
+    },
+  });
+
+  // ---------- 2. write_article: 分阶段写作 (writing-agent) ----------
+  catalog.register({
+    name: "write_article",
+    description: "分阶段写长文: 选题→结构→初稿→审稿→修改→导出。适合公众号文章、产品介绍、课程内容、需要反复修改的长文。",
+    parameters: {
+      type: "object",
+      properties: {
+        topic: { type: "string", description: "主题" },
+        audience: { type: "string", description: "读者是谁 (可选)" },
+        length: { type: "string", description: "字数要求 (可选)" },
+        tone: { type: "string", description: "语气风格 (可选)" },
+      },
+      required: ["topic"],
+    },
+    execute: async (args, ctx) => {
+      const topic = textOf(args.topic, "");
+      if (!topic) return "[工具错误] write_article: 缺少 topic";
+      const audience = textOf(args.audience, "undefined");
+      const length = textOf(args.length, "undefined");
+      const tone = textOf(args.tone, "undefined");
+      const system = "你是资深内容创作总编。写长文必须走完整流程, 先规划再动笔, 每步都交代清楚再进下一步。";
+      const user = `写一篇关于「${topic}」的文章。\n读者: ${audience}\n字数: ${length}\n语气: ${tone}\n\n请按流程输出:\n【1.选题确认】一句话说清本文核心观点和读者收益\n【2.结构】列出大纲(标题+各段要点)\n【3.初稿】按结构写出完整正文\n【4.审稿】列出初稿的问题(事实/逻辑/语气)\n【5.修改稿】根据审稿优化后的最终版本\n【6.导出】给出可用标题(3个备选)+文章定稿`;
+      try {
+        const out = await llmChat(ctx.agent, system, user);
+        return out || "(无输出)";
+      } catch (e) {
+        return `[工具错误] write_article: ${e.message}`;
+      }
+    },
+  });
+
+  // ---------- 3. clarify: 需求澄清 (Superpowers) ----------
+  catalog.register({
+    name: "clarify",
+    description: "需求澄清: 面对模糊任务先问清需求再动手, 避免返工。传入任务描述, 返回需要澄清的问题清单; 若信息足够则直接给出执行方案。适合改代码/做项目前使用。",
+    parameters: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "任务描述" },
+        context: { type: "string", description: "已知背景/已了解的信息 (可选)" },
+      },
+      required: ["task"],
+    },
+    execute: async (args, ctx) => {
+      const task = textOf(args.task, "");
+      if (!task) return "[工具错误] clarify: 缺少 task";
+      const context = textOf(args.context, "无额外背景");
+      const system = "你是需求澄清专家。面对模糊任务, 先判断信息是否足够执行。若不足, 列出必须澄清的关键问题(≤5个, 只问真正影响执行的问题, 不啰嗦); 若已足够, 给出简明执行方案(步骤+风险+受影响的文件/模块)。不编造, 不确定就列问题。";
+      const user = `任务: ${task}\n已知背景: ${context}\n\n请判断信息是否足够, 不足则问关键问题, 足够则给执行方案。`;
+      try {
+        const out = await llmChat(ctx.agent, system, user);
+        return out || "(无输出)";
+      } catch (e) {
+        return `[工具错误] clarify: ${e.message}`;
+      }
+    },
+  });
+
+  // ---------- 场景系统: 类似灵魂文件的场景设定 ----------
+  catalog.register({
+    name: "scene_create",
+    description: "创建/更新一个场景(人设)。每个场景定义智能体在这个情境下能帮用户干什么, 类似灵魂文件。可手动设定名称/介绍/能力。",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "场景名称, 如: A股交易助手" },
+        description: { type: "string", description: "场景介绍, 说明这个场景是干嘛的" },
+        canHelp: { type: "string", description: "这个场景能帮用户干什么(能力清单)" },
+        keywords: { type: "array", items: { type: "string" }, description: "触发关键词(可选)" },
+      },
+      required: ["name", "description", "canHelp"],
+    },
+    execute: async (args, ctx) => {
+      if (!ctx.agent) return "[工具错误] scene_create: 缺少 agent 上下文";
+      const s = ctx.agent.scenes.create({
+        name: args.name, description: args.description, canHelp: args.canHelp, keywords: args.keywords,
+      });
+      return JSON.stringify({ ok: true, id: s.id, name: s.name, mode: "manual" });
+    },
+  });
+
+  catalog.register({
+    name: "scene_list",
+    description: "列出所有场景及其介绍/能力。",
+    parameters: { type: "object", properties: {} },
+    execute: async (args, ctx) => {
+      if (!ctx.agent) return "[工具错误] scene_list: 缺少 agent 上下文";
+      const list = ctx.agent.scenes.listWithDesc();
+      return list.length ? list.map((s) => `- [${s.mode}] ${s.name}: ${s.description} | 能帮: ${s.canHelp} | ${s.facts}条记忆`).join("\n") : "(暂无场景)";
+    },
+  });
+
+  catalog.register({
+    name: "scene_describe",
+    description: "用 LLM 从历史对话提炼场景介绍和能力。给定场景名, 自动总结该场景的用途和能帮用户干什么。",
+    parameters: {
+      type: "object",
+      properties: { name: { type: "string", description: "要提炼的场景名" } },
+      required: ["name"],
+    },
+    execute: async (args, ctx) => {
+      const name = textOf(args.name, "");
+      if (!name) return "[工具错误] scene_describe: 缺少 name";
+      if (!ctx.agent) return "[工具错误] scene_describe: 缺少 agent";
+      // 找场景
+      const scene = ctx.agent.scenes.scenes.find((i) => i.name === name || i.name.includes(name));
+      if (!scene) return `[工具错误] scene_describe: 未找到场景 ${name}`;
+      const facts = (scene.facts || []).map((f) => f.content).slice(-10).join("\n");
+      const system = "你是场景分析器。根据场景的历史对话, 提炼出: ①场景简介(一句话) ②这个场景能帮用户干什么(能力清单, 3-5项)。直接给结果, 格式: 简介:xxx\\n能力: - xxx\\n - xxx";
+      const user = `场景: ${scene.name}\\n历史对话:\\n${facts || "(无)"}`;
+      try {
+        const out = await llmChat(ctx.agent, system, user);
+        // v1.0.9: LLM 输出未含"能力"段时保留旧值 (原 split("能力")[0] 会拿整段污染 description)
+        if (out.includes("能力")) {
+          scene.description = out.split("能力")[0].replace("简介:", "").trim().slice(0, 300) || scene.description;
+          scene.canHelp = out.split("能力")[1]?.slice(0, 300) || scene.canHelp;
+        }
+        scene.mode = "manual";
+        ctx.agent.scenes._save();
+        return out || "(无输出)";
+      } catch (e) {
+        return `[工具错误] scene_describe: ${e.message}`;
+      }
+    },
+  });
+
+  return catalog;
+}

package/src/tools/ocr.js

@@ -1,59 +1,59 @@
-// src/tools/ocr.js - OCR 光学字符识别 (零依赖, 可插拔)
-// 主通道: 本地 tesseract 二进制 (零 key 零网络, 需系统安装)
-// 回退: 百度 OCR 云 API (需 BAIDU_OCR_API_KEY / BAIDU_OCR_SECRET_KEY)
-// 用于: 扫描件 PDF / 图片里的文字识别 (read_image 读图后无法理解文字时)
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import fs from "node:fs";
-
-const execFileP = promisify(execFile);
-
-// 检测 tesseract 是否可用 (注入 _exec 便于测试)
-export async function tesseractAvailable(bin = "tesseract", _exec = execFileP) {
-  try {
-    await _exec(bin, ["--version"], { timeout: 5000, windowsHide: true });
-    return true;
-  } catch { return false; }
-}
-
-// tesseract 识别图片 → 文字 (stdout 直接输出识别结果)
-export async function ocrWithTesseract(filePath, { bin = "tesseract", lang = "chi_sim", timeoutMs = 30000, _exec = execFileP } = {}) {
-  const { stdout, stderr } = await _exec(bin, [filePath, "stdout", "-l", lang], {
-    timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024, windowsHide: true,
-  });
-  const text = String(stdout || "").trim();
-  if (!text && stderr) throw new Error("tesseract 未识别出文字: " + String(stderr).slice(0, 200));
-  return text;
-}
-
-// 百度 OCR: 取 access_token → 通用文字识别
-async function ocrWithBaidu(filePath, { apiKey, secretKey }) {
-  const tok = await fetch(
-    `https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=${encodeURIComponent(apiKey)}&client_secret=${encodeURIComponent(secretKey)}`,
-    { method: "POST", signal: AbortSignal.timeout(15000) },
-  ).then((r) => r.json());
-  if (!tok.access_token) throw new Error("百度 OCR token 获取失败: " + (tok.error_description || tok.error || "未知"));
-  const img = fs.readFileSync(filePath).toString("base64");
-  const body = new URLSearchParams({ image: img, language_type: "CHN_ENG" });
-  const r = await fetch(`https://aip.baidubce.com/rest/2.0/ocr/v1/general_basic?access_token=${tok.access_token}`, {
-    method: "POST",
-    headers: { "Content-Type": "application/x-www-form-urlencoded" },
-    body,
-    signal: AbortSignal.timeout(20000),
-  });
-  const j = await r.json();
-  if (j.error_code) throw new Error("百度 OCR 失败: " + (j.error_msg || j.error_code));
-  return (j.words_result || []).map((w) => w.words).join("\n");
-}
-
-// OCR 主入口: tesseract 优先, 云 OCR 回退, 都不可用抛中文引导
-export async function ocrImage(filePath, { tesseract = "tesseract", lang = "chi_sim", cloud = null, _exec = execFileP } = {}) {
-  if (!fs.existsSync(filePath)) throw new Error("文件不存在: " + filePath);
-  if (await tesseractAvailable(tesseract, _exec)) {
-    return ocrWithTesseract(filePath, { bin: tesseract, lang, _exec });
-  }
-  if (cloud && cloud.apiKey && cloud.secretKey) {
-    return ocrWithBaidu(filePath, { apiKey: cloud.apiKey, secretKey: cloud.secretKey });
-  }
-  throw new Error("OCR 不可用: 请安装 tesseract (含中文语言包) 或配置 config.ocr 的云 OCR key");
-}
+// src/tools/ocr.js - OCR 光学字符识别 (零依赖, 可插拔)
+// 主通道: 本地 tesseract 二进制 (零 key 零网络, 需系统安装)
+// 回退: 百度 OCR 云 API (需 BAIDU_OCR_API_KEY / BAIDU_OCR_SECRET_KEY)
+// 用于: 扫描件 PDF / 图片里的文字识别 (read_image 读图后无法理解文字时)
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import fs from "node:fs";
+
+const execFileP = promisify(execFile);
+
+// 检测 tesseract 是否可用 (注入 _exec 便于测试)
+export async function tesseractAvailable(bin = "tesseract", _exec = execFileP) {
+  try {
+    await _exec(bin, ["--version"], { timeout: 5000, windowsHide: true });
+    return true;
+  } catch { return false; }
+}
+
+// tesseract 识别图片 → 文字 (stdout 直接输出识别结果)
+export async function ocrWithTesseract(filePath, { bin = "tesseract", lang = "chi_sim", timeoutMs = 30000, _exec = execFileP } = {}) {
+  const { stdout, stderr } = await _exec(bin, [filePath, "stdout", "-l", lang], {
+    timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024, windowsHide: true,
+  });
+  const text = String(stdout || "").trim();
+  if (!text && stderr) throw new Error("tesseract 未识别出文字: " + String(stderr).slice(0, 200));
+  return text;
+}
+
+// 百度 OCR: 取 access_token → 通用文字识别
+async function ocrWithBaidu(filePath, { apiKey, secretKey }) {
+  const tok = await fetch(
+    `https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=${encodeURIComponent(apiKey)}&client_secret=${encodeURIComponent(secretKey)}`,
+    { method: "POST", signal: AbortSignal.timeout(15000) },
+  ).then((r) => r.json());
+  if (!tok.access_token) throw new Error("百度 OCR token 获取失败: " + (tok.error_description || tok.error || "未知"));
+  const img = fs.readFileSync(filePath).toString("base64");
+  const body = new URLSearchParams({ image: img, language_type: "CHN_ENG" });
+  const r = await fetch(`https://aip.baidubce.com/rest/2.0/ocr/v1/general_basic?access_token=${tok.access_token}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body,
+    signal: AbortSignal.timeout(20000),
+  });
+  const j = await r.json();
+  if (j.error_code) throw new Error("百度 OCR 失败: " + (j.error_msg || j.error_code));
+  return (j.words_result || []).map((w) => w.words).join("\n");
+}
+
+// OCR 主入口: tesseract 优先, 云 OCR 回退, 都不可用抛中文引导
+export async function ocrImage(filePath, { tesseract = "tesseract", lang = "chi_sim", cloud = null, _exec = execFileP } = {}) {
+  if (!fs.existsSync(filePath)) throw new Error("文件不存在: " + filePath);
+  if (await tesseractAvailable(tesseract, _exec)) {
+    return ocrWithTesseract(filePath, { bin: tesseract, lang, _exec });
+  }
+  if (cloud && cloud.apiKey && cloud.secretKey) {
+    return ocrWithBaidu(filePath, { apiKey: cloud.apiKey, secretKey: cloud.secretKey });
+  }
+  throw new Error("OCR 不可用: 请安装 tesseract (含中文语言包) 或配置 config.ocr 的云 OCR key");
+}

package/src/tools/sandbox-worker.js

@@ -0,0 +1,40 @@
+// src/tools/sandbox-worker.js - 沙箱工作线程 (配合 sandbox.js)
+// worker 隔离 = 第一层边界 (独立线程, 可强杀); node:vm 新上下文 = 第二层 (裁剪全局)。
+// 沙箱内**没有** require/import/process/fetch/fs —— 纯计算用途。
+import { parentPort, workerData } from "node:worker_threads";
+import vm from "node:vm";
+
+const logs = [];
+const fmt = (v) => {
+  if (typeof v === "string") return v;
+  try { return JSON.stringify(v) ?? String(v); } catch { return String(v); }
+};
+const push = (level) => (...args) => logs.push(`[${level}] ` + args.map(fmt).join(" "));
+
+const sandboxConsole = { log: push("log"), info: push("info"), warn: push("warn"), error: push("error") };
+
+// 裁剪过的全局: 纯计算可用, 无 IO / 网络 / 时器 / 模块加载
+const sandbox = {
+  console: sandboxConsole,
+  Math, JSON, Date, RegExp, Error, TypeError, RangeError, SyntaxError,
+  Array, Object, String, Number, Boolean, Symbol, BigInt, Map, Set, WeakMap, WeakSet,
+  Promise, isNaN, isFinite, parseInt, parseFloat, encodeURIComponent, decodeURIComponent,
+  structuredClone, NaN, Infinity, undefined,
+};
+sandbox.globalThis = sandbox;
+
+const timeoutMs = Math.min(Number(workerData?.timeoutMs) || 3000, 10000);
+try {
+  const result = vm.runInNewContext(String(workerData?.code || ""), sandbox, {
+    timeout: timeoutMs,          // 同步代码超时 (vm 层)
+    displayErrors: true,
+  });
+  let out;
+  if (typeof result === "bigint") out = String(result);
+  else if (typeof result === "function" || (typeof result === "object" && result !== null)) {
+    try { out = JSON.parse(JSON.stringify(result)); } catch { out = String(result); }
+  } else out = result;
+  parentPort.postMessage({ ok: true, result: out, logs });
+} catch (e) {
+  parentPort.postMessage({ ok: false, error: `${e.name}: ${e.message}`, logs });
+}

package/src/tools/sandbox.js

@@ -0,0 +1,92 @@
+// src/tools/sandbox.js - 内置 JS 沙箱执行器 (零依赖)
+//
+// 用途: 让 agent 能安全地跑一段 JS 做计算/数据变换/格式转换 (CodeAct 能力落地):
+//   - 不用 shell 也不落盘, 单轮纯计算, 结果回灌工具循环。
+//   - 双层隔离: worker_threads 独立线程 (超时强杀, 死循环也不挂主进程)
+//     + node:vm 裁剪全局上下文 (无 require/process/fetch/fs, 纯计算)。
+//   - 这不是安全边界意义上的"防恶意"沙箱 (Node 无原生强隔离), 面向的是"防失误":
+//     防死循环、防误写文件、防意外网络请求。对不受信代码仍应走 run_command + 沙箱策略审批链。
+import path from "node:path";
+import { Worker } from "node:worker_threads";
+import { TOOL_ERROR_PREFIX } from "./seam.js";
+import { debug } from "../utils/logger.js";
+
+const WORKER_URL = new URL("./sandbox-worker.js", import.meta.url);
+
+function err(name, msg) {
+  return `${TOOL_ERROR_PREFIX} ${name}: ${msg}`;
+}
+
+// 跑一段代码: { ok, result, logs, durationMs } 或 { ok:false, error, logs }
+export function runInSandbox(code, { timeoutMs = 3000 } = {}) {
+  return new Promise((resolve) => {
+    const t0 = Date.now();
+    const cap = Math.min(Number(timeoutMs) || 3000, 10000);
+    let worker;
+    try {
+      worker = new Worker(WORKER_URL, { workerData: { code: String(code || ""), timeoutMs: cap } });
+    } catch (e) {
+      return resolve({ ok: false, error: `worker 启动失败: ${e.message}`, logs: [], durationMs: 0 });
+    }
+    const timer = setTimeout(() => {
+      worker.terminate().catch((e) => debug(`[sandbox] terminate 异常: ${e.message}`));
+      // terminate 后 message 不会再来, 立即裁决; 哨兵标志防双 resolve
+      settled = true;
+      resolve({ ok: false, error: `执行超时 (${cap}ms), 线程已强杀`, logs: [], durationMs: Date.now() - t0 });
+    }, cap + 500); // vm 层超时通常先触发; 这层兜底异步死循环
+    let settled = false;
+    worker.on("message", (msg) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ ...msg, durationMs: Date.now() - t0 });
+    });
+    worker.on("error", (e) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ ok: false, error: `worker 异常: ${e.message}`, logs: [], durationMs: Date.now() - t0 });
+    });
+    worker.on("exit", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ ok: false, error: `worker 提前退出 (code=${code})`, logs: [], durationMs: Date.now() - t0 });
+    });
+  });
+}
+
+export function registerSandboxTools(catalog, { rootDir = process.cwd() } = {}) {
+  void rootDir;
+  catalog.register({
+    name: "code_run",
+    description: "在内置 JS 沙箱里执行一段 JavaScript 并返回结果 (纯计算: 数学/字符串/数组变换/JSON 处理)。沙箱无网络/文件/进程访问, 限时 10s。适合精确计算、数据转换、格式化 —— 比手算可靠, 比 shell 干净。",
+    parameters: {
+      type: "object",
+      properties: {
+        code: { type: "string", description: "JS 代码 (表达式或语句)。最后一条表达式的值或显式变量为返回值; 用 console.log 输出中间信息" },
+        timeout_ms: { type: "number", description: "超时毫秒 (默认 3000, 上限 10000)" },
+      },
+      required: ["code"],
+    },
+    category: "compute",
+    power: "user",
+    idempotent: true,
+    capability: { readOnly: true, riskLevel: "low", sideEffect: "none" },
+    execute: async (args) => {
+      const code = String(args.code || "").trim();
+      if (!code) return err("code_run", "code 不能为空");
+      const r = await runInSandbox(code, { timeoutMs: Number(args.timeout_ms) || 3000 });
+      if (!r.ok) {
+        return err("code_run", `${r.error}${r.logs?.length ? ` | 输出: ${r.logs.join(" / ").slice(0, 500)}` : ""}`);
+      }
+      return JSON.stringify({
+        ok: true,
+        result: r.result,
+        logs: (r.logs || []).slice(0, 50),
+        durationMs: r.durationMs,
+      });
+    },
+  });
+  return catalog;
+}