ppxans-harness 2.4.0

package/src/tools/advanced.js

@@ -0,0 +1,353 @@
+// src/tools/advanced.js - 进阶工具集 (搜索 / HTTP / 定时任务)
+// 全部零依赖: 用 Node 原生 fetch + timers
+import fs from "node:fs";
+import net from "node:net";
+import dns from "node:dns/promises";
+import path from "node:path";
+import { ensureDir, readJson, writeJson } from "../utils/store.js";
+
+// ---------- 网页搜索 (零依赖, 多引擎兜底: tavily/brave[有key] -> DDG) ----------
+// 有 TAVILY_API_KEY / BRAVE_API_KEY 时优先用官方 API, 否则回退加固后的 DDG 解析
+function _stripTags(h) { return String(h || "").replace(/<[^>]+>/g, "").replace(/&amp;/g, "&").replace(/&quot;/g, '"').replace(/&#x27;/g, "'").trim(); }
+function _decodeDDGUrl(u) {
+  // DDG 结果链接是 /duckduckgo.html?uddg=<encoded>&rut=...
+  const m = String(u || "").match(/[?&]uddg=([^&]+)/);
+  if (m) { try { return decodeURIComponent(m[1]); } catch {} }
+  return u;
+}
+
+async function searchWeb(query) {
+  const q = encodeURIComponent(query);
+
+  // 1. Tavily (官方 API, 需 TAVILY_API_KEY)
+  const tavilyKey = process.env.TAVILY_API_KEY;
+  if (tavilyKey) {
+    try {
+      const r = await fetch("https://api.tavily.com/search", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ api_key: tavilyKey, query, max_results: 5 }),
+        signal: AbortSignal.timeout(15000),
+      });
+      if (r.ok) {
+        const j = await r.json();
+        const results = (j.results || []).map(x => ({ title: x.title, url: x.url, snippet: x.content }));
+        if (results.length) return results;
+      }
+    } catch {}
+  }
+
+  // 2. Brave (官方 API, 需 BRAVE_API_KEY)
+  const braveKey = process.env.BRAVE_API_KEY;
+  if (braveKey) {
+    try {
+      const r = await fetch(`https://api.search.brave.com/res/v1/web/search?q=${q}&count=5`, {
+        headers: { "X-Subscription-Token": braveKey, "Accept": "application/json" },
+        signal: AbortSignal.timeout(15000),
+      });
+      if (r.ok) {
+        const j = await r.json();
+        const results = (j.web?.results || []).map(x => ({ title: x.title, url: x.url, snippet: x.description }));
+        if (results.length) return results;
+      }
+    } catch {}
+  }
+
+  // 3. DuckDuckGo HTML (免key兜底, 加固解析)
+  try {
+    const r = await fetch(`https://html.duckduckgo.com/html/?q=${q}`, {
+      headers: { "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" },
+      signal: AbortSignal.timeout(15000),
+    });
+    const html = await r.text();
+    const results = [];
+    // 每次抓一个 result 块: <a class="result__a" href="...">title<\/a> ... <a class="result__snippet"...>snippet<\/a>
+    const re = /<a[^>]*class="[^"]*result__a[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>[\s\S]*?<a[^>]*class="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/a>/g;
+    let m;
+    while ((m = re.exec(html)) && results.length < 5) {
+      const title = _stripTags(m[2]);
+      const snippet = _stripTags(m[3]);
+      if (title) results.push({ title, url: _decodeDDGUrl(m[1]), snippet });
+    }
+    if (results.length) return results;
+  } catch {}
+
+  // 4. DuckDuckGo lite (最终兜底)
+  try {
+    const r = await fetch(`https://lite.duckduckgo.com/lite/?q=${q}`, {
+      headers: { "User-Agent": "Mozilla/5.0" },
+      signal: AbortSignal.timeout(15000),
+    });
+    const html = await r.text();
+    const results = [];
+    const re = /<a[^>]+class="result-link"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/g;
+    let m;
+    while ((m = re.exec(html)) && results.length < 5) {
+      const title = _stripTags(m[2]);
+      if (title) results.push({ title, url: _decodeDDGUrl(m[1]), snippet: "" });
+    }
+    if (results.length) return results;
+  } catch {}
+
+  throw new Error("所有搜索源失败: 无结果");
+}
+
+// ---------- HTTP 请求 (含 SSRF 防护) ----------
+function isPrivateIP(ip) {
+  if (!ip) return false;
+  const parts = (ip.replace(/^::ffff:/, "")).split(".").map(Number);
+  if (parts.length !== 4) return false;
+  const [a, b] = parts;
+  if (a === 127) return true;
+  if (a === 10) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 0) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  return false;
+}
+
+async function assertPublicUrl(url) {
+  const u = new URL(url);
+  if (u.protocol !== "http:" && u.protocol !== "https:") throw new Error("仅允许 http/https");
+  const hostname = u.hostname.replace(/^\[|\]$/g, "");
+  if (net.isIP(hostname)) {
+    if (isPrivateIP(hostname)) throw new Error("SSRF 拒绝: 内网地址 " + hostname);
+    return;
+  }
+  const addrs = await dns.lookup(hostname, { all: true, verbatim: true });
+  for (const { address } of addrs) {
+    if (isPrivateIP(address)) throw new Error("SSRF 拒绝: " + hostname + " 解析到内网 " + address);
+  }
+}
+
+// 带 SSRF 校验的安全 fetch: 手动跟随重定向, 并对每一跳(含首发)都做 assertPublicUrl 校验。
+// fetch 默认 redirect:"follow" 会在每次跳转时重新解析 DNS —— 攻击者用一个公网 URL 302→内网
+// (如 http://127.0.0.1:x 或 http://169.254.169.254/)即可绕过单次 assertPublicUrl。
+// 这里改用 redirect:"manual" 逐跳校验后再继续, 堵住"302 到内网/云元数据"的绕过。
+async function _fetchWithSsrSafe(url, { method = "GET", headers = {}, body, signal, maxRedirects = 5 } = {}) {
+  let current = url;
+  for (let hop = 0; hop <= maxRedirects; hop++) {
+    await assertPublicUrl(current);
+    const resp = await fetch(current, {
+      method,
+      headers,
+      body: body !== undefined ? (typeof body === "string" ? body : JSON.stringify(body)) : undefined,
+      redirect: "manual",
+      signal,
+    });
+    if (resp.status >= 300 && resp.status < 400 && resp.headers.has("location")) {
+      const loc = resp.headers.get("location");
+      current = new URL(loc, current).toString(); // 相对 Location 基于 current 解析成绝对 URL
+      method = "GET"; // 重定向后不再携带 body, 并退回 GET (302/303 语义)
+      body = undefined;
+      continue;
+    }
+    return resp;
+  }
+  throw new Error("SSRF 拒绝: 重定向次数超过 " + maxRedirects);
+}
+
+async function httpRequest({ url, method = "GET", headers = {}, body = null, timeout = 15000 }) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeout);
+  try {
+    const resp = await _fetchWithSsrSafe(url, {
+      method,
+      headers: { "User-Agent": "PPX-Agent/0.2", ...headers },
+      body,
+      signal: ctrl.signal,
+    });
+    const text = await resp.text();
+    return { status: resp.status, ok: resp.ok, body: text.slice(0, 20000) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+
+// ---------- 网页正文提取 (fetch_page: 抓正文转纯文本, 配合 web_search 读网页) ----------
+function _htmlToText(html) {
+  const s0 = String(html || "");
+  // 去掉 script/style/nav/footer/header 噪音
+  let out = s0.replace(/<script[\s\S]*?<\/script>/gi, " ")
+              .replace(/<style[\s\S]*?<\/style>/gi, " ")
+              .replace(/<(script|style|nav|footer|header|iframe|form|button|svg)[^>]*>[\s\S]*?<\/\1>/gi, " ");
+  out = out.replace(/<br\s*\/?>|<\/p>|<\/div>|<\/li>|<\/h[1-6]>|<\/tr>/gi, "\n");
+  out = out.replace(/<[^>]+>/g, " ");                     // 去掉所有标签
+  out = out.replace(/&nbsp;/gi, " ").replace(/&amp;/gi, "&")
+           .replace(/&lt;/gi, "<").replace(/&gt;/gi, ">")
+           .replace(/&quot;/gi, '"').replace(/&#39;|&#x27;/gi, "'");
+  out = out.replace(/\s+/g, " ");                          // 压缩空白
+  return out.trim();
+}
+
+// ---------- 定时任务 ----------
+export class Scheduler {
+  constructor(dataDir) {
+    this.dir = path.join(dataDir, "scheduler");
+    ensureDir(this.dir);
+    this.file = path.join(this.dir, "jobs.json");
+    this.jobs = readJson(this.file, []);
+    this.timers = new Map();
+  }
+
+  add({ name, cron, action, type = "once" }) {
+    const job = {
+      id: "j_" + Math.random().toString(36).slice(2, 8),
+      name, cron, action, type, enabled: true, createdAt: new Date().toISOString(),
+    };
+    this.jobs.push(job);
+    writeJson(this.file, this.jobs);
+    this._schedule(job);
+    return job;
+  }
+
+  _schedule(job) {
+    if (this.timers.has(job.id)) clearTimeout(this.timers.get(job.id));
+    // 简化 cron: 支持 "HH:MM" (每日) 或 "after:Ns" (N秒后)
+    let delayMs = null;
+    if (typeof job.cron === "string" && job.cron.startsWith("after:")) {
+      delayMs = parseInt(job.cron.split(":")[1], 10) * 1000;
+    } else if (typeof job.cron === "string" && /^\d{2}:\d{2}$/.test(job.cron)) {
+      const [h, m] = job.cron.split(":").map(Number);
+      const now = new Date();
+      const target = new Date(now); target.setHours(h, m, 0, 0);
+      if (target <= now) target.setDate(target.getDate() + 1);
+      delayMs = target - now;
+    } else if (typeof job.cron === "number") {
+      delayMs = job.cron * 1000;
+    }
+    if (delayMs === null) return;
+    const timer = setTimeout(() => this._fire(job), delayMs);
+    this.timers.set(job.id, timer);
+  }
+
+  async _fire(job) {
+    if (job.type === "once") { this.remove(job.id); }
+    else { this._schedule(job); } // 每日任务重新排
+    try {
+      if (typeof job.action === "function") await job.action();
+    } catch (e) { console.error("定时任务失败:", e); }
+  }
+
+  remove(id) {
+    if (this.timers.has(id)) { clearTimeout(this.timers.get(id)); this.timers.delete(id); }
+    this.jobs = this.jobs.filter((j) => j.id !== id);
+    writeJson(this.file, this.jobs);
+  }
+
+  list() { return this.jobs.map(({ id, name, cron, enabled }) => ({ id, name, cron, enabled })); }
+
+  // 清理所有定时器 (进程关停时调用, 防 daily/repeating 任务把事件循环挂住不退出)
+  shutdown() {
+    for (const [id, t] of this.timers) { try { clearTimeout(t); } catch {} }
+    this.timers.clear();
+  }
+}
+
+// 注册进阶工具
+export function registerAdvancedTools(catalog, { dataDir, scheduler, onMemoryNote }) {
+  catalog.register({
+    name: "web_search",
+    description: "搜索互联网, 返回网页标题+链接+摘要。",
+    parameters: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
+    execute: async (args) => {
+      try {
+        const results = await searchWeb(args.query);
+        return results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.snippet || ""}`).join("\n");
+      } catch (e) {
+        return JSON.stringify({ error: `搜索失败: ${e.message}` });
+      }
+    },
+  });
+
+  catalog.register({
+    name: "http_request",
+    description: "发送 HTTP 请求 (GET/POST/PUT/DELETE), 返回状态码和响应体。",
+    parameters: {
+      type: "object",
+      properties: {
+        url: { type: "string" },
+        method: { type: "string", enum: ["GET", "POST", "PUT", "DELETE"] },
+        headers: { type: "object" },
+        body: { type: "string" },
+      },
+      required: ["url"],
+    },
+    execute: async (args) => {
+      try {
+        const r = await httpRequest(args);
+        return JSON.stringify({ status: r.status, ok: r.ok, body: r.body.slice(0, 5000) });
+      } catch (e) {
+        return JSON.stringify({ error: `HTTP 请求失败: ${e.message}` });
+      }
+    },
+  });
+
+  catalog.register({
+    name: "notify",
+    description: "主动向用户通道发送通知消息 (用于长任务或异步完成提醒)。",
+    parameters: { type: "object", properties: { message: { type: "string", description: "要发送的通知内容" } }, required: ["message"] },
+    execute: async (args, ctx) => {
+      const agent = ctx && ctx.agent;
+      if (agent && agent.notify) { agent.notify(args && args.message); return "notified"; }
+      return "no notify sink registered";
+    },
+  });
+
+  catalog.register({
+    name: "add_schedule",
+    description: "添加定时任务。cron 支持 'HH:MM'(每日) 或 'after:秒数'(N秒后执行一次)。",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        cron: { type: "string", description: "'HH:MM' 或 'after:60'" },
+      },
+      required: ["name", "cron"],
+    },
+    execute: async (args) => {
+      if (!scheduler) return JSON.stringify({ error: "调度器未初始化" });
+      const job = scheduler.add({ name: args.name, cron: args.cron, type: /^\d{2}:\d{2}$/.test(args.cron) ? "daily" : "once", action: () => onMemoryNote?.(`定时任务触发: ${args.name}`) });
+      return JSON.stringify({ ok: true, id: job.id, next: job.cron });
+    },
+  });
+
+  catalog.register({
+    name: "list_schedules",
+    description: "列出所有定时任务。",
+    parameters: { type: "object", properties: {} },
+    execute: async () => {
+      if (!scheduler) return "调度器未初始化";
+      return JSON.stringify(scheduler.list());
+    },
+  });
+
+
+  catalog.register({
+    name: "fetch_page",
+    description: "抓取一个网页的正文并转成纯文本 (截断到 20000 字符)。用于读文章/文档/新闻内容后回答问题。",
+    parameters: {
+      type: "object",
+      properties: { url: { type: "string", description: "要抓取的网页 URL" }, maxChars: { type: "number", description: "返回最大字符数, 默认 20000" } },
+      required: ["url"],
+    },
+    execute: async (args) => {
+      try {
+        const timeout = 15000;
+        const r = await httpRequest({ url: args.url, timeout });
+        if (!r.ok) return JSON.stringify({ error: "抓取失败 HTTP " + r.status });
+        const text = _htmlToText(r.body);
+        const max = Math.min(args.maxChars || 20000, 40000);
+        const truncated = text.length > max ? text.slice(0, max) + "\n...[已截断, 共 " + text.length + " 字符]" : text;
+        return JSON.stringify({ url: args.url, status: r.status, chars: text.length, content: truncated });
+      } catch (e) {
+        return JSON.stringify({ error: "fetch_page 失败: " + e.message });
+      }
+    },
+  });
+
+  return catalog;
+}

package/src/tools/builtin.js

@@ -0,0 +1,298 @@
+// src/tools/builtin.js - 内置工具集 (皮皮虾的手脚)
+// 文件/命令/时间/记忆查询 — 全部零依赖, 用 Node 原生
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { scrubPII } from "../utils/pii.js";
+import { LocalShellProvider } from "../seam/shell.js";
+import { checkCommand, DENY_HINT } from "./command-guard.js";
+
+const execFileP = promisify(execFile);
+
+// 默认 shell provider (未通过 seam 注入时的兜底, 供测试/独立工具目录使用)
+const defaultShell = new LocalShellProvider();
+
+// 图片 MIME 表 (read_image + 多模态注入共用)
+const IMAGE_MIME = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".bmp": "image/bmp" };
+
+// 读图片文件转 base64 data URL (供 read_image 工具与多模态 user 消息注入复用)
+export function imageFileToDataUrl(rootDir, p, { maxBytes = 8 * 1024 * 1024 } = {}) {
+  const fp = safePath(rootDir, p);
+  const mime = IMAGE_MIME[path.extname(fp).toLowerCase()];
+  if (!mime) throw new Error("不支持的文件类型: " + path.extname(fp));
+  if (!fs.existsSync(fp)) throw new Error("文件不存在: " + p);
+  const buf = fs.readFileSync(fp);
+  if (buf.length > maxBytes) throw new Error(`图片过大 (>${Math.round(maxBytes / 1024 / 1024)}MB)`);
+  return `data:${mime};base64,${buf.toString("base64")}`;
+}
+
+// ---- run_command 安全策略 (P0): 统一走命令守卫 (src/tools/command-guard.js) ----
+// 三层防线: 用户 deny(security.deny) -> 硬黑名单(allow_all 也拦) -> 常规高危 + 前缀白名单
+// 命令守卫的 isDeniedCommand/isAllowedCommand 兼容导出见 command-guard.js
+
+// 安全路径: 阻止逃出工作目录 (防路径穿越)
+// v1.0.9: 追加 realpath 校验 — 字符串前缀检查可被工作区内 symlink 指向外部绕过 (resolve 后仍在 root 内但实际文件在外部)
+export function safePath(root, p) {
+  const resolved = path.resolve(root, p);
+  if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+    throw new Error(`路径越界拒绝: ${p}`);
+  }
+  try {
+    const realRoot = fs.realpathSync(root);
+    let target = resolved;
+    if (fs.existsSync(target)) {
+      target = fs.realpathSync(target); // 存在: 直接解析真实路径
+    } else {
+      // 不存在: 用最近已存在父目录的真实路径 + 剩余部分 (新建文件场景)
+      let dir = path.dirname(target);
+      while (dir !== root && dir !== path.dirname(dir) && !fs.existsSync(dir)) dir = path.dirname(dir);
+      target = path.join(fs.realpathSync(fs.existsSync(dir) ? dir : root), path.relative(dir, resolved));
+    }
+    if (target !== realRoot && !target.startsWith(realRoot + path.sep)) {
+      throw new Error(`路径越界拒绝 (符号链接): ${p}`);
+    }
+  } catch (e) {
+    if (e && e.message && e.message.includes("路径越界拒绝")) throw e;
+    // root 不存在等边缘: 退回前缀检查 (已通过)
+  }
+  return resolved;
+}
+
+// ---- code_act (CodeAct 出口): 一次提交脚本批量操作, 压 N 轮工具往返 → 1 轮 ----
+// 安全: 默认关闭 (security.code_act), 开启后限 python/node 解释器 + 工作目录 + 超时 + PII + 黑名单扫描
+// 相比 run_command 的增量风险: 脚本体绕过命令串黑名单, 故独立开关 + 默认关闭
+// 沙箱加固 (进程级): 干净环境变量(剥离密钥/令牌) + node 内存上限 + 超时强杀进程树 + 输出上限
+//   真正隔离需外部 Docker/MicroVM (见 docs/CONFIG.md), 此处为无依赖下的最大进程级约束
+
+// 干净沙箱环境: 只保留运行必需变量, 剥离一切敏感密钥/令牌/凭证, 防脚本窃取宿主凭据
+const SANDBOX_ENV_KEEP = /^(PATH|PATHEXT|SYSTEMROOT|WINDIR|TEMP|TMP|USERPROFILE|HOMEDRIVE|HOMEPATH|COMSPEC|OS|PROCESSOR_ARCHITECTURE|PROCESSOR_IDENTIFIER|NUMBER_OF_PROCESSORS|LANG|LC_|PYTHONIOENCODING|PYTHONPATH)$/i;
+function sandboxEnv() {
+  const env = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (v && SANDBOX_ENV_KEEP.test(k)) env[k] = v;
+  }
+  return env;
+}
+
+const CODE_ACT_MEMORY_MB = 256;      // node 解释器内存上限
+const CODE_ACT_OUTPUT_MAX = 512 * 1024; // 输出上限 512KB
+
+export async function runCodeAct(rootDir, lang, code, timeoutMs) {
+  const isWin = process.platform === "win32";
+  const ext = lang === "node" ? "js" : "py";
+  const tmp = path.join(os.tmpdir(), `ppx_codeact_${Date.now()}_${Math.random().toString(36).slice(2, 6)}.${ext}`);
+  fs.writeFileSync(tmp, code, "utf8");
+  const interpreter = lang === "node" ? process.execPath : (isWin ? "python" : "python3");
+  // node 加内存上限; python 无等价零依赖参数 (可外接 Docker 时再限制)
+  const args = lang === "node" ? [`--max-old-space-size=${CODE_ACT_MEMORY_MB}`, tmp] : [tmp];
+  try {
+    const { stdout, stderr } = await execFileP(interpreter, args, {
+      cwd: rootDir,
+      timeout: timeoutMs || 30000,
+      maxBuffer: CODE_ACT_OUTPUT_MAX,
+      env: sandboxEnv(),
+      windowsHide: true,
+    });
+    const out = (stdout || "") + (stderr ? "\n[stderr] " + stderr : "");
+    return scrubPII(out).cleaned.slice(0, 20000) || "(无输出)";
+  } catch (e) {
+    // 超时/输出超限/内存超限的友好提示
+    if (e.killed || /timed out|ETIMEDOUT/i.test(e.message)) {
+      return JSON.stringify({ error: `code_act 执行超时 (${timeoutMs || 30000}ms), 已强制终止` });
+    }
+    return JSON.stringify({ error: e.message, code: e.code });
+  } finally {
+    try { fs.rmSync(tmp, { force: true }); } catch {}
+  }
+}
+
+// 注册全部内置工具
+export function registerBuiltinTools(catalog, { rootDir, facts, memory }) {
+  // 1. 读文件
+  catalog.register({
+    name: "read_file",
+    description: "读取文件内容。返回文件文本。",
+    parameters: {
+      type: "object",
+      properties: { path: { type: "string", description: "文件路径 (相对工作目录)" } },
+      required: ["path"],
+    },
+    execute: async (args) => {
+      const p = safePath(rootDir, args.path);
+      if (!fs.existsSync(p)) return JSON.stringify({ error: `文件不存在: ${args.path}` });
+      const content = fs.readFileSync(p, "utf8");
+      // v1.0.9: 输出 PII 脱敏 (与 run_command/code_act 一致, 文件可能含密钥/手机号)
+      return scrubPII(content).cleaned.slice(0, 20000);
+    },
+  });
+
+  // 2. 写文件
+  catalog.register({
+    name: "write_file",
+    description: "写入文件 (覆盖)。可用于创建/修改文件。",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "文件路径" },
+        content: { type: "string", description: "要写入的内容" },
+      },
+      required: ["path", "content"],
+    },
+    execute: async (args) => {
+      // v1.0.9: 写入内容上限 512KB (防撑爆磁盘); 路径是目录时给友好错误
+      const content = String(args.content ?? "");
+      if (content.length > 512 * 1024) return JSON.stringify({ error: `写入内容过大 (>512KB, 当前 ${content.length} 字符)` });
+      const p = safePath(rootDir, args.path);
+      if (fs.existsSync(p) && fs.statSync(p).isDirectory()) {
+        return JSON.stringify({ error: `目标是目录: ${args.path}` });
+      }
+      try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, content, "utf8");
+        return JSON.stringify({ ok: true, bytes: Buffer.byteLength(content) });
+      } catch (e) {
+        return JSON.stringify({ error: `写入失败: ${e.message}` });
+      }
+    },
+  });
+
+  // 3. 列目录
+  catalog.register({
+    name: "list_dir",
+    description: "列出目录内容 (文件名列表)。",
+    parameters: {
+      type: "object",
+      properties: { path: { type: "string", description: "目录路径, 默认工作目录" } },
+    },
+    execute: async (args) => {
+      const p = safePath(rootDir, args.path || ".");
+      if (!fs.existsSync(p) || !fs.statSync(p).isDirectory()) {
+        return JSON.stringify({ error: `目录不存在: ${args.path || "."}` });
+      }
+      const items = fs.readdirSync(p).map((f) => {
+        const fp = path.join(p, f);
+        const st = fs.statSync(fp);
+        return `${st.isDirectory() ? "[D]" : "[F]"} ${f}`;
+      });
+      return items.join("\n");
+    },
+  });
+
+  // 4. 执行命令 (安全: 限制在允许目录, 超时)
+  catalog.register({
+    name: "run_command",
+    description: "执行 shell 命令并返回输出。只能在工作目录内执行, 有超时。",
+    parameters: {
+      type: "object",
+      properties: { command: { type: "string", description: "要执行的命令" } },
+      required: ["command"],
+    },
+    execute: async (args, ctx) => {
+      const cmd = String(args.command || "").trim();
+      if (!cmd) return JSON.stringify({ error: "空命令" });
+      const opts = (ctx && ctx.agent && ctx.agent.config && ctx.agent.config.security) || {};
+      const guard = checkCommand(cmd, opts);
+      if (!guard.ok) {
+        return JSON.stringify({ error: guard.reason + DENY_HINT });
+      }
+      // 通过 shell seam 调用 (可替换 provider: 本地/沙箱/Docker), 换 provider 即换执行环境
+      const shell = (ctx?.agent?.ctx && ctx.agent.ctx.consume("shell")) || defaultShell;
+      const r = await shell.exec(cmd, { cwd: rootDir, timeoutMs: opts.command_timeout_ms || 30000 });
+      if (!r.ok) return JSON.stringify({ error: r.stderr, code: r.code });
+      const out = r.stdout + (r.stderr ? "\n[stderr] " + r.stderr : "");
+      return scrubPII(out).cleaned.slice(0, 20000) || "(无输出)";
+    },
+  });
+
+  // 4.5 code_act (CodeAct 出口): 脚本批量操作, 压 N 轮工具往返 → 1 轮
+  catalog.register({
+    name: "code_act",
+    description: "用 Python/Node 脚本一次性完成多个操作(读文件/处理数据/写结果), 用 print/console.log 输出结果。默认关闭, 需 security.code_act=true。",
+    parameters: {
+      type: "object",
+      properties: {
+        language: { type: "string", enum: ["python", "node"], description: "脚本语言" },
+        code: { type: "string", description: "脚本内容" },
+      },
+      required: ["language", "code"],
+    },
+    execute: async (args, ctx) => {
+      const sec = (ctx && ctx.agent && ctx.agent.config && ctx.agent.config.security) || {};
+      if (!sec.allow_all && !sec.code_act) {
+        return JSON.stringify({ error: "code_act 未开启: 在 security 设置 code_act=true (或 allow_all=true)" });
+      }
+      const lang = String(args.language || "").toLowerCase();
+      if (!["python", "node"].includes(lang)) return JSON.stringify({ error: "language 仅支持 python/node" });
+      const code = String(args.code || "");
+      if (!code) return JSON.stringify({ error: "空代码" });
+      // code_act 是脚本体: 只做 deny 检查 (硬黑名单 + 用户 deny + 常规高危), 不做前缀白名单 (脚本无"命令前缀")
+      const guard = checkCommand(code, { ...sec, allowAll: true });
+      if (!guard.ok) return JSON.stringify({ error: guard.reason + DENY_HINT });
+      return runCodeAct(rootDir, lang, code, sec.command_timeout_ms);
+    },
+  });
+
+  // 5. 当前时间
+  catalog.register({
+    name: "get_time",
+    description: "获取当前日期和时间。",
+    parameters: { type: "object", properties: {} },
+    execute: async () => new Date().toLocaleString("zh-CN", { timeZone: "Asia/Shanghai" }),
+  });
+
+  // 6. 记忆查询 (皮皮虾自己查记忆)
+  catalog.register({
+    name: "memory_search",
+    description: "搜索皮皮虾的记忆库, 返回相关事实。",
+    parameters: {
+      type: "object",
+      properties: { query: { type: "string", description: "要搜的内容" }, limit: { type: "number" } },
+      required: ["query"],
+    },
+    execute: async (args) => {
+      if (!facts) return JSON.stringify({ error: "记忆未初始化" });
+      const results = facts.query(args.query, { limit: args.limit || 5 });
+      return results.length
+        ? results.map((r) => `- [${r.score}] ${r.content}`).join("\n")
+        : "(无匹配记忆)";
+    },
+  });
+
+  // 7. 记住新事实
+  catalog.register({
+    name: "memory_add",
+    description: "把一条重要信息写进皮皮虾的长期记忆。",
+    parameters: {
+      type: "object",
+      properties: { content: { type: "string", description: "要记住的内容" } },
+      required: ["content"],
+    },
+    execute: async (args) => {
+      if (!facts) return JSON.stringify({ error: "记忆未初始化" });
+      const f = facts.add(args.content, { source: "agent-self" });
+      return JSON.stringify({ ok: true, id: f.id });
+    },
+  });
+
+  // 8. 读图片 (多模态): 返回 base64 data URL, 供多模态模型视觉理解
+  catalog.register({
+    name: "read_image",
+    description: "读取图片文件, 返回 base64 data URL 供多模态模型理解图片内容 (需配置支持视觉的模型, 如 gpt-4o/qwen-vl/glm-4v)。",
+    parameters: {
+      type: "object",
+      properties: { path: { type: "string", description: "图片文件路径 (相对工作目录)" } },
+      required: ["path"],
+    },
+    execute: async (args) => {
+      try {
+        return imageFileToDataUrl(rootDir, args.path);
+      } catch (e) {
+        return JSON.stringify({ error: e.message });
+      }
+    },
+  });
+
+  return catalog;
+}