ppxans-harness 2.6.0 → 3.2.1

package/src/tools/git.js

@@ -0,0 +1,151 @@
+// src/tools/git.js - Git 集成工具 (结构化 + 护栏)
+// 对齐主流 Agent 实践 (aider 自动提交 / Claude Code / OpenHands / Cline):
+// 版本控制是编码 Agent 的标配一等工具, 但必须有硬护栏 —
+//   ① 只读工具 (status/diff/log) 幂等无副作用;
+//   ② git_commit 仅限 add+commit, 禁止 push / reset / rebase / clean / force (无此工具即无此能力);
+//   ③ 全部走 execFile 参数数组, 不经 shell, 命令注入不可能;
+//   ④ 输出截断到 toolResultBudget 级别, 防 diff 巨型化撑爆上下文。
+// 2026-10-01 新增 (GitHub 主流 Agent 对标轮)。
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const OUT_CAP = 4000;
+const MSG_CAP = 500;
+
+function findRepoRoot(rootDir) {
+  let dir = path.resolve(rootDir);
+  for (let i = 0; i < 32; i++) {
+    if (fs.existsSync(path.join(dir, ".git"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+function git(rootDir, args, timeoutMs = 15000) {
+  const repo = findRepoRoot(rootDir);
+  if (!repo) throw new Error("不在 git 仓库内 (未找到 .git)");
+  return execFileSync("git", args, {
+    cwd: repo,
+    timeout: timeoutMs,
+    maxBuffer: 8 * 1024 * 1024,
+    encoding: "utf8",
+  });
+}
+
+function cap(s) {
+  return String(s || "").length > OUT_CAP
+    ? String(s).slice(0, OUT_CAP) + `\n…[已截断, 共 ${String(s).length} 字符]`
+    : String(s || "");
+}
+
+export function registerGitTools(catalog, { rootDir } = {}) {
+  // 1. git_status — 分支 + 变更清单 (结构化)
+  catalog.register({
+    name: "git_status",
+    description: "查看 git 仓库状态: 当前分支与变更文件清单 (结构化 JSON)。提交前先看这里。",
+    parameters: { type: "object", properties: {}, required: [] },
+    category: "vcs",
+    power: "user",
+    idempotent: true,
+    execute: async () => {
+      try {
+        const branch = git(rootDir, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+        const porcelain = git(rootDir, ["status", "--porcelain", "-b"]);
+        const lines = porcelain.split("\n").filter(Boolean);
+        const changes = lines.filter((l) => !l.startsWith("##"));
+        return JSON.stringify({
+          branch,
+          clean: changes.length === 0,
+          entries: changes.map((l) => ({ x: l.slice(0, 2).trim(), file: l.slice(3).trim() })),
+        });
+      } catch (e) {
+        return JSON.stringify({ error: (e.message || "").slice(0, 200) });
+      }
+    },
+  });
+
+  // 2. git_diff — 查看改动内容
+  catalog.register({
+    name: "git_diff",
+    description: "查看未提交改动 (git diff)。staged=true 只看已暂存区; path 可限定单个文件。",
+    parameters: {
+      type: "object",
+      properties: { staged: { type: "boolean" }, path: { type: "string" } },
+      required: [],
+    },
+    category: "vcs",
+    power: "user",
+    idempotent: true,
+    execute: async (args) => {
+      try {
+        const a = ["diff", "--no-color"];
+        if (args.staged) a.push("--staged");
+        if (args.path) a.push("--", args.path);
+        return cap(git(rootDir, a));
+      } catch (e) {
+        return "[git 错误] " + (e.message || "").slice(0, 200);
+      }
+    },
+  });
+
+  // 3. git_log — 最近提交历史
+  catalog.register({
+    name: "git_log",
+    description: "查看最近提交历史 (默认 10 条, 上限 50)。",
+    parameters: { type: "object", properties: { n: { type: "number" } }, required: [] },
+    category: "vcs",
+    power: "user",
+    idempotent: true,
+    execute: async (args) => {
+      const n = Math.min(Math.max(Number(args.n) || 10, 1), 50);
+      try {
+        const raw = git(rootDir, ["log", `-${n}`, "--pretty=format:%h|%an|%ad|%s", "--date=short"]);
+        return JSON.stringify({
+          commits: raw.split("\n").filter(Boolean).map((l) => {
+            const [hash, author, date, ...rest] = l.split("|");
+            return { hash, author, date, subject: rest.join("|") };
+          }),
+        });
+      } catch {
+        return JSON.stringify({ commits: [] }); // 空仓库 (尚无任何提交)
+      }
+    },
+  });
+
+  // 4. git_commit — 受限提交 (唯一写操作; 无 push/reset/rebase 能力)
+  catalog.register({
+    name: "git_commit",
+    description: "提交当前改动 (仅 add+commit)。add_all=true 时先暂存全部改动。禁止也不支持 push/reset 等危险操作。",
+    parameters: {
+      type: "object",
+      properties: {
+        message: { type: "string", description: "提交信息 (≤500 字符)" },
+        add_all: { type: "boolean", description: "先暂存全部改动 (git add -A)" },
+      },
+      required: ["message"],
+    },
+    category: "vcs",
+    power: "agent",
+    execute: async (args) => {
+      const message = String(args.message || "").trim();
+      if (!message) return "[工具错误] git_commit: 需要 message";
+      if (message.length > MSG_CAP) return `[工具错误] git_commit: message 超过 ${MSG_CAP} 字符`;
+      const staged = args.add_all === true;
+      if (staged) git(rootDir, ["add", "-A"]);
+      // 无暂存改动时 commit 会失败, 先探测给出可读错误
+      const nothing = git(rootDir, ["status", "--porcelain"]).split("\n").filter(Boolean).length === 0
+        && git(rootDir, ["diff", "--staged", "--quiet"]).length === 0;
+      if (nothing && !staged) return JSON.stringify({ ok: false, error: "没有可提交的改动 (工作区干净且暂存区为空)" });
+      try {
+        const out = git(rootDir, ["commit", "-m", message]);
+        const hash = (out.match(/\[[^\]]+ ([0-9a-f]+)\]/) || [])[1] || "";
+        return JSON.stringify({ ok: true, hash, message });
+      } catch (e) {
+        return JSON.stringify({ ok: false, error: (e.message || "").slice(0, 300) });
+      }
+    },
+  });
+}

package/src/tools/governance.js

@@ -3,6 +3,10 @@
 //        + audit_verify, 以及 ppx-memory/ppx-selfheal 暴露的 persona_build/persona_read/selfheal_run。
 // 改写: ppx-v2 原版用 cordis 的 defineTool + @deepseek-ai/schemastery (z.object) 声明,
 //       这里改写为 ppx-agent 原生的 ToolCatalog.register 风格, 剥离全部外部依赖。
+//
+// 2026-09-18 重构: 原先是一个 250 行的单一注册函数 (10 个工具挤在一起)。
+//   现按文件头注自身的分组拆成三个具名函数, 找某个工具时可直接跳到对应组;
+//   对外的 registerGovernanceTools 签名与返回值完全不变。
 import fs from "node:fs";
 import path from "node:path";
 import { safePath } from "./builtin.js";
@@ -10,8 +14,19 @@ import { ensureDir, nowISO } from "../utils/store.js";
 
 // 记忆治理 + 审计 + 运维工具注册
 // deps: { rootDir, facts, audit, personaStore, healer, experience, dataDir }
-export function registerGovernanceTools(catalog, { rootDir, facts, audit, personaStore, healer, experience, dataDir } = {}) {
+export function registerGovernanceTools(catalog, deps = {}) {
+  registerMemoryGovernanceTools(catalog, deps);
+  registerAuditTools(catalog, deps);
+  registerOpsTools(catalog, deps);
+  return catalog;
+}
+
+// ---- 组 1: 记忆治理 (forget / restore / list_deleted / export / import / clear_layer) ----
+// 设计原则: 默认软删可回滚, 物理删除必须显式 hard=true —— 治理动作不可逆是最大的风险面。
+function registerMemoryGovernanceTools(catalog, { rootDir, facts, dataDir } = {}) {
   const exportsDir = path.join(rootDir || dataDir || ".", "exports");
+  // 记忆服务未装配时的统一降级响应 (6 个 memory_* 工具共用, 改文案只动这一处)
+  const noFacts = () => JSON.stringify({ error: "记忆未初始化" });
 
   // 1. 遗忘 (软删, 可回滚) —— ppx-agent 原版只有不可逆硬删, 这是最大的治理缺口
   catalog.register({
@@ -21,17 +36,21 @@ export function registerGovernanceTools(catalog, { rootDir, facts, audit, person
       type: "object",
       properties: {
         id_or_content: { type: "string", description: "记忆 id 或内容 (按内容精确匹配, 去记忆动词前缀后比对)" },
+        id: { type: "string", description: "记忆 id (与 id_or_content 二选一, 与 memory_restore 参数名对齐)" },
         reason: { type: "string", description: "遗忘原因 (记入审计, 便于后续复核)" },
       },
-      required: ["id_or_content"],
+      required: [],
     },
     category: "memory",
     power: "user",
     idempotent: true,
     execute: async (args) => {
-      if (!facts) return JSON.stringify({ error: "记忆未初始化" });
-      const f = facts.forget(args.id_or_content, { reason: args.reason || null });
-      if (!f) return JSON.stringify({ error: "未找到匹配记忆", target: args.id_or_content });
+      if (!facts) return noFacts();
+      // 2026-10-03 统一: 兼容接受 id (与 memory_restore 同名), 消除两个工具参数命名不一致
+      const target = args.id_or_content || args.id;
+      if (!target) return JSON.stringify({ error: "缺少必填参数 id 或 id_or_content" });
+      const f = facts.forget(target, { reason: args.reason || null });
+      if (!f) return JSON.stringify({ error: "未找到匹配记忆", target });
       return JSON.stringify({ ok: true, id: f.id, content: f.content, status: f.status, note: "已软删, 可用 memory_restore 回滚" });
     },
   });
@@ -42,16 +61,21 @@ export function registerGovernanceTools(catalog, { rootDir, facts, audit, person
     description: "恢复一条被遗忘 (软删) 的记忆。",
     parameters: {
       type: "object",
-      properties: { id: { type: "string", description: "记忆 id" } },
-      required: ["id"],
+    properties: {
+      id: { type: "string", description: "记忆 id" },
+      id_or_content: { type: "string", description: "记忆 id 或内容 (与 id 二选一, 兼容 memory_forget 参数名)" },
+    },
+    required: [],
     },
     category: "memory",
     power: "user",
     idempotent: true,
     execute: async (args) => {
-      if (!facts) return JSON.stringify({ error: "记忆未初始化" });
-      const f = facts.restore(args.id);
-      if (!f) return JSON.stringify({ error: "未找到该记忆", id: args.id });
+      if (!facts) return noFacts();
+      // 2026-10-03 统一: 兼容接受 id_or_content (与 memory_forget 同名)
+      const target = args.id || args.id_or_content;
+      const f = facts.restore(target);
+      if (!f) return JSON.stringify({ error: "未找到该记忆", id: target });
       return JSON.stringify({ ok: true, id: f.id, content: f.content, status: f.status });
     },
   });
@@ -69,7 +93,7 @@ export function registerGovernanceTools(catalog, { rootDir, facts, audit, person
     power: "user",
     idempotent: true,
     execute: async (args) => {
-      if (!facts) return JSON.stringify({ error: "记忆未初始化" });
+      if (!facts) return noFacts();
       const list = facts.deletedList().slice(0, args.limit || 20);
       if (!list.length) return "(无已遗忘的记忆)";
       return list.map((f) => `- ${f.id} | ${f.deletedAt || "?"} | ${f.deleteReason || "无原因"} | ${f.content}`).join("\n");
@@ -92,7 +116,7 @@ export function registerGovernanceTools(catalog, { rootDir, facts, audit, person
     power: "user",
     idempotent: true,
     execute: async (args) => {
-      if (!facts) return JSON.stringify({ error: "记忆未初始化" });
+      if (!facts) return noFacts();
       const dump = facts.exportAll({ includeDeleted: args.include_deleted !== false });
       let out;
       if (args.file) {
@@ -123,7 +147,7 @@ export function registerGovernanceTools(catalog, { rootDir, facts, audit, person
     power: "user",
     idempotent: false,
     execute: async (args) => {
-      if (!facts) return JSON.stringify({ error: "记忆未初始化" });
+      if (!facts) return noFacts();
       const fp = safePath(rootDir || ".", args.file);
       if (!fs.existsSync(fp)) return JSON.stringify({ error: "文件不存在", file: args.file });
       let payload;
@@ -149,13 +173,15 @@ export function registerGovernanceTools(catalog, { rootDir, facts, audit, person
     power: "user",
     idempotent: false,
     execute: async (args) => {
-      if (!facts) return JSON.stringify({ error: "记忆未初始化" });
+      if (!facts) return noFacts();
       const r = facts.clearLayer(Number(args.layer), { hard: args.hard === true });
       return JSON.stringify({ ok: true, ...r, note: r.hard ? "已物理删除" : "已软删, 可用 memory_restore 逐条回滚" });
     },
   });
+}
 
-  // 7. 审计链校验 (吸收自 ppx-v2 audit.js: SHA-256 哈希链防篡改验证)
+// ---- 组 2: 审计链校验 (吸收自 ppx-v2 audit.js: SHA-256 哈希链防篡改验证) ----
+function registerAuditTools(catalog, { audit } = {}) {
   catalog.register({
     name: "audit_verify",
     description: "校验工具调用审计日志的 SHA-256 哈希链完整性, 定位首个被篡改/截断的位置。quarantine=true 时隔离损坏段并重建空链。",
@@ -187,8 +213,11 @@ export function registerGovernanceTools(catalog, { rootDir, facts, audit, person
       return JSON.stringify(out);
     },
   });
+}
 
-  // 8. 画像重建 (ppx-v2 ppx-memory 的 persona_build, 这里薄包装 l3 PersonaStore)
+// ---- 组 3: 运维 (画像重建/读取 + 自愈体检) ----
+function registerOpsTools(catalog, { personaStore, healer, experience, facts } = {}) {
+  // 7. 画像重建 (ppx-v2 ppx-memory 的 persona_build, 这里薄包装 l3 PersonaStore)
   catalog.register({
     name: "persona_build",
     description: "从当前记忆与经验重新提炼用户画像 / agent 人格, 写入 L3 层。",
@@ -217,7 +246,7 @@ export function registerGovernanceTools(catalog, { rootDir, facts, audit, person
     },
   });
 
-  // 9. 画像读取
+  // 8. 画像读取
   catalog.register({
     name: "persona_read",
     description: "读取 L3 层沉淀的用户画像 / agent 人格全文。",
@@ -237,7 +266,7 @@ export function registerGovernanceTools(catalog, { rootDir, facts, audit, person
     },
   });
 
-  // 10. 自愈体检 (ppx-v2 selfheal_run, 薄包装 Healer)
+  // 9. 自愈体检 (ppx-v2 selfheal_run, 薄包装 Healer)
   catalog.register({
     name: "selfheal_run",
     description: "手动跑一次自愈体检: 补建缺失目录、修复损坏 JSON、清理崩溃残留与过期备份。",
@@ -255,6 +284,4 @@ export function registerGovernanceTools(catalog, { rootDir, facts, audit, person
       return JSON.stringify({ ok: true, healedAt: nowISO(), health });
     },
   });
-
-  return catalog;
 }

package/src/tools/index.js

@@ -1,11 +1,16 @@
-// src/tools/index.js - 工具系统统一出口
-export { ToolCatalog, TOOL_ERROR_PREFIX } from "./catalog.js";
-export { normalizeMeta, runWithPolicy, toDescriptor } from "./seam.js";
-export { registerBuiltinTools } from "./builtin.js";
-export { registerAdvancedTools, Scheduler } from "./advanced.js";
-export { registerMethodTools } from "./methods.js";
-export { registerSelfmodTools } from "./selfmod.js";
-export { registerCustomTools } from "./custom.js";
-export { registerDocumentTools } from "./document.js";
-// 记忆治理 + 审计 + 运维 (吸收自 ppx-v2)
-export { registerGovernanceTools } from "./governance.js";
+// src/tools/index.js - 工具系统统一出口
+export { ToolCatalog, TOOL_ERROR_PREFIX } from "./catalog.js";
+export { normalizeMeta, runWithPolicy, toDescriptor } from "./seam.js";
+export { registerBuiltinTools } from "./builtin.js";
+export { registerAdvancedTools, Scheduler } from "./advanced.js";
+export { registerMethodTools } from "./methods.js";
+export { registerSelfmodTools } from "./selfmod.js";
+export { registerCustomTools } from "./custom.js";
+export { registerDocumentTools } from "./document.js";
+// 记忆治理 + 审计 + 运维 (吸收自 ppx-v2)
+export { registerGovernanceTools } from "./governance.js";
+export { registerGitTools } from "./git.js";
+export { registerVoiceTools, resolveVoice, resolveLocalAsr, voiceStatus } from "./voice.js";
+// v3.1: 内置 JS 沙箱执行器 (CodeAct) + 语音活动检测 (VAD)
+export { registerSandboxTools, runInSandbox } from "./sandbox.js";
+export { registerVadTools, energyVad, parseWavPcm16 } from "./vad.js";