ppxans-harness 2.4.0 → 3.2.0

package/src/tools/selfmod.js

@@ -1,176 +1,196 @@
-// src/tools/selfmod.js - Self-modification 工具
-// 参考 deepseek-harness 的 self-modification: agent 能检查/挂载/卸载自己的运行时能力
-// 这里落地为"能力级自修改": 枚举能力(工具+技能) / 启用 / 禁用 / 加载技能, 不破坏零依赖内核
-import { SkillLoader } from "../skills/loader.js";
-import fs from "node:fs";
-import path from "node:path";
-
-function capErr(name, msg) {
-  return `[工具错误] ${name}: ${msg}`;
-}
-
-export function registerSelfmodTools(catalog, { skillsDir }) {
-  const loader = new SkillLoader(skillsDir);
-
-  // 1. 枚举全部能力: 工具 + 技能
-  catalog.register({
-    name: "list_capabilities",
-    description: "枚举当前所有可用的工具能力(category/power/enabled) 和已安装技能。用于 agent 了解自己能干啥。",
-    parameters: { type: "object", properties: { kind: { type: "string", enum: ["tool", "skill", "all"], description: "all=工具+技能(默认)" } }, required: [] },
-    category: "selfmod",
-    power: "agent",
-    idempotent: true,
-    execute: async (args) => {
-      const kind = args && args.kind ? args.kind : "all";
-      const lines = [];
-      if (kind === "all" || kind === "tool") {
-        lines.push("— 工具 —");
-        for (const t of catalog.listDetailed()) {
-          lines.push(`[${t.enabled ? "ON" : "OFF"}] ${t.name} (${t.category}/${t.power})${t.timeoutMs ? ` 超时${t.timeoutMs}ms` : ""}`);
-        }
-      }
-      if (kind === "all" || kind === "skill") {
-        lines.push("— 技能 —");
-        for (const s of loader.list()) {
-          lines.push(`${s.id}: ${s.name} — ${s.description}`);
-        }
-      }
-      return lines.join("\n");
-    },
-  });
-
-  // 2. 启用能力
-  catalog.register({
-    name: "enable_capability",
-    description: "启用一个已注册但被禁用的工具能力。name 为工具名。",
-    parameters: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
-    category: "selfmod",
-    power: "agent",
-    execute: async (args) => {
-      if (!catalog.enable(args.name)) return capErr("enable_capability", `未知工具: ${args.name}`);
-      return `已启用: ${args.name}`;
-    },
-  });
-
-  // 3. 禁用能力
-  catalog.register({
-    name: "disable_capability",
-    description: "禁用工具能力(不卸载, 可随时启用)。name 为工具名。禁用后该工具不再出现在 LLM schema 且调用被拒。",
-    parameters: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
-    category: "selfmod",
-    power: "agent",
-    execute: async (args) => {
-      if (!catalog.disable(args.name)) return capErr("disable_capability", `未知工具: ${args.name}`);
-      return `已禁用: ${args.name}`;
-    },
-  });
-
-  // 4. 加载技能
-  catalog.register({
-    name: "load_skill",
-    description: "读取一个已安装技能的 SKILL.md 全文, 供 agent 按需加载使用。id 为技能名。",
-    parameters: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
-    category: "selfmod",
-    power: "user",
-    idempotent: true,
-    execute: async (args) => {
-      const content = loader.read(args.id);
-      if (content === null) return capErr("load_skill", `未知技能: ${args.id}`);
-      
-      if (loader && typeof loader.trackUse === "function") { try { loader.trackUse(args.id); } catch {} }
-      return `# ${args.id}\n\n${content}`;
-    },
-  });
-
-  // 5. 创建新技能 (L5 auto-skill: 复杂任务后沉淀为可复用 Skill)
-  catalog.register({
-    name: "create_skill",
-    description: "把一次成功的方法/流程沉淀为可复用的 Agent Skill。name=技能名(字母数字横线), description=一句话说明, content=SKILL.md 正文。正文推荐含三个段落(参考 addyosmani/agent-skills): ①「## 流程」逐步工作流+检查点 ②「## 反合理化」常见偷懒借口+反驳 ③「## 验证」完成后必须提供的证据。写进 skills/ 目录后自动被 loader 发现。",
-    parameters: {
-      type: "object",
-      properties: {
-        name: { type: "string", description: "技能名, 仅字母/数字/横线" },
-        description: { type: "string", description: "技能一句话说明" },
-        content: { type: "string", description: "SKILL.md 正文 (建议含: 流程/反合理化/验证 三段)" },
-      },
-      required: ["name", "description", "content"],
-    },
-    category: "selfmod",
-    power: "agent",
-    execute: async (args) => {
-      const name = String(args.name || "").trim();
-      if (!/^[a-zA-Z0-9-]+$/.test(name)) return "[工具错误] create_skill: 技能名仅允许字母/数字/横线: " + name;
-      const desc = String(args.description || "").trim();
-      const content = String(args.content || "").trim();
-      if (!desc || !content) return "[工具错误] create_skill: 需 description + content";
-      // v1.0.8: 长度上限, 防写超大文件/垃圾内容
-      if (desc.length > 300) return "[工具错误] create_skill: description 超长 (最大 300 字符)";
-      if (content.length > 50000) return "[工具错误] create_skill: content 超长 (最大 50000 字符)";
-      const dir = path.join(skillsDir, name);
-      fs.mkdirSync(dir, { recursive: true });
-      const frontmatter = "---" + "\n" + "name: " + name + "\n" + "description: " + desc + "\n" + "---" + "\n" + "\n";
-      fs.writeFileSync(path.join(dir, "SKILL.md"), frontmatter + content, "utf8");
-      return "已创建技能: " + name + " (skills/" + name + "/SKILL.md)";
-    },
-  });
-
-  // 6b. 自我进化: 从失败轨迹自动提炼经验 (refine 的上半场, 补齐「失败→经验」闭环)
-  catalog.register({
-    name: "refine",
-    description: "从最近的失败工具调用轨迹自动提炼一条可复用经验教训 (自我进化闭环)。失败轨迹足够(≥2条)时, 用 LLM 提炼成一句话经验存进经验库, 后续任务自动注入上下文。",
-    parameters: { type: "object", properties: { limit: { type: "number", description: "回看轨迹条数, 默认 20" } }, required: [] },
-    category: "selfmod",
-    power: "agent",
-    execute: async (args, ctx) => {
-      const agent = ctx && ctx.agent;
-      if (!agent || typeof agent.refine !== "function") return capErr("refine", "无 agent 上下文");
-      const r = await agent.refine({ limit: Number(args && args.limit) || 20 });
-      return JSON.stringify(r);
-    },
-  });
-
-  // 7. 自我进化: 从成功轨迹自动提炼可复用 Skill (refine 的下半场)
-  catalog.register({
-    name: "refine_skill",
-    description: "从最近成功的工具调用轨迹自动提炼一个可复用 Skill (自我进化闭环)。成功轨迹足够且高频工具重复出现时, 用 LLM 提炼成 skills/<name>/SKILL.md。",
-    parameters: { type: "object", properties: { limit: { type: "number", description: "回看轨迹条数, 默认 50" } }, required: [] },
-    category: "selfmod",
-    power: "agent",
-    execute: async (args, ctx) => {
-      const agent = ctx && ctx.agent;
-      if (!agent || typeof agent.refineSkill !== "function") return capErr("refine_skill", "无 agent 上下文");
-      const r = await agent.refineSkill({ limit: Number(args && args.limit) || 50 });
-      return JSON.stringify(r);
-    },
-  });
-
-  // 6. Session Replay: 从原始日志恢复会话历史 (跨天/崩溃续跑)
-  catalog.register({
-    name: "replay_session",
-    description: "从原始对话日志恢复某会话的历史(跨天/崩溃后续跑)。sessionKey=会话名(默认default), days=回溯天数(默认7), limit=返回条数(默认40)。",
-    parameters: {
-      type: "object",
-      properties: {
-        sessionKey: { type: "string", description: "会话名, 默认 default" },
-        days: { type: "number", description: "回溯天数, 默认 7" },
-        limit: { type: "number", description: "返回条数, 默认 40" },
-      },
-      required: [],
-    },
-    category: "selfmod",
-    power: "user",
-    idempotent: true,
-    execute: async (args, ctx) => {
-      const agent = ctx && ctx.agent;
-      if (!agent || !agent.l0) return capErr("replay_session", "无 l0 记录器");
-      const msgs = agent.replaySession((args && args.sessionKey) || "default", {
-        days: Number(args && args.days) || 7,
-        limit: Number(args && args.limit) || 40,
-      });
-      if (!msgs.length) return "(该会话无历史记录)";
-      return msgs.map(m => `${m.role}: ${m.content}`).join("\n");
-    },
-  });
-
-  return catalog;
-}
+// src/tools/selfmod.js - Self-modification 工具
+// 参考 deepseek-harness 的 self-modification: agent 能检查/挂载/卸载自己的运行时能力
+// 这里落地为"能力级自修改": 枚举能力(工具+技能) / 启用 / 禁用 / 加载技能, 不破坏零依赖内核
+import { SkillLoader } from "../skills/loader.js";
+import { scoreSkills } from "../skills/search.js";
+import fs from "node:fs";
+import path from "node:path";
+import { debug } from "../utils/logger.js";
+
+function capErr(name, msg) {
+  return `[工具错误] ${name}: ${msg}`;
+}
+
+export function registerSelfmodTools(catalog, { skillsDir }) {
+  const loader = new SkillLoader(skillsDir);
+
+  // 1. 枚举全部能力: 工具 + 技能
+  catalog.register({
+    name: "list_capabilities",
+    description: "枚举当前所有可用的工具能力(category/power/enabled) 和已安装技能。用于 agent 了解自己能干啥。",
+    parameters: { type: "object", properties: { kind: { type: "string", enum: ["tool", "skill", "all"], description: "all=工具+技能(默认)" } }, required: [] },
+    category: "selfmod",
+    power: "agent",
+    idempotent: true,
+    execute: async (args) => {
+      const kind = args && args.kind ? args.kind : "all";
+      const lines = [];
+      if (kind === "all" || kind === "tool") {
+        lines.push("— 工具 —");
+        for (const t of catalog.listDetailed()) {
+          lines.push(`[${t.enabled ? "ON" : "OFF"}] ${t.name} (${t.category}/${t.power})${t.timeoutMs ? ` 超时${t.timeoutMs}ms` : ""}`);
+        }
+      }
+      if (kind === "all" || kind === "skill") {
+        lines.push("— 技能 —");
+        for (const s of loader.list()) {
+          lines.push(`${s.id}: ${s.name} — ${s.description}`);
+        }
+      }
+      return lines.join("\n");
+    },
+  });
+
+  // 2. 启用能力 (+ 按需披露: 让该工具的 schema 进入下一轮 LLM 请求)
+  catalog.register({
+    name: "enable_capability",
+    description: "启用并加载一个工具能力 (name 为工具名)。用于加载未默认携带的工具 —— 它们的功能已在【按需工具】清单里列出, 但完整参数说明需要先启用才能调用。",
+    parameters: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
+    category: "selfmod",
+    power: "agent",
+    execute: async (args) => {
+      if (!catalog.enable(args.name)) return capErr("enable_capability", `未知工具: ${args.name}`);
+      catalog.expose(args.name); // 披露给 LLM: 下一轮请求即可见其参数 schema
+      return `已启用: ${args.name}`;
+    },
+  });
+
+  // 3. 禁用能力
+  catalog.register({
+    name: "disable_capability",
+    description: "禁用工具能力(不卸载, 可随时启用)。name 为工具名。禁用后该工具不再出现在 LLM schema 且调用被拒。",
+    parameters: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
+    category: "selfmod",
+    power: "agent",
+    execute: async (args) => {
+      if (!catalog.disable(args.name)) return capErr("disable_capability", `未知工具: ${args.name}`);
+      return `已禁用: ${args.name}`;
+    },
+  });
+
+  // 4. 加载技能
+  catalog.register({
+    name: "load_skill",
+    description: "读取一个已安装技能的 SKILL.md 全文, 供 agent 按需加载使用。id 为技能名。",
+    parameters: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+    category: "selfmod",
+    power: "user",
+    idempotent: true,
+    execute: async (args) => {
+      const content = loader.read(args.id);
+      if (content === null) return capErr("load_skill", `未知技能: ${args.id}`);
+      
+      if (loader && typeof loader.trackUse === "function") { try { loader.trackUse(args.id); } catch (e) { debug(`[tools/selfmod] 已忽略异常: ${e && e.message ? e.message : e}`); } }
+      return `# ${args.id}\n\n${content}`;
+    },
+  });
+
+  // 4.5 技能检索 (蓝皮书 2026: 发现机制是技能生态的瓶颈 — 给 agent 一个检索入口)
+  catalog.register({
+    name: "skill_search",
+    description: "按关键词检索已安装技能, 对 name/description 打分排序返回。面对任务不确定用哪个技能时先用它发现, 再用 load_skill 读取全文。",
+    parameters: { type: "object", properties: { query: { type: "string", description: "关键词 (中英文均可)" } }, required: ["query"] },
+    category: "selfmod",
+    power: "user",
+    idempotent: true,
+    execute: async (args) => {
+      const q = String(args.query || "").trim();
+      if (!q) return capErr("skill_search", "需要 query 关键词");
+      if (!loader) return capErr("skill_search", "技能目录未装配");
+      const results = scoreSkills(loader, q).slice(0, 8);
+      return JSON.stringify({ query: q, count: results.length, results });
+    },
+  });
+
+  // 5. 创建新技能 (L5 auto-skill: 复杂任务后沉淀为可复用 Skill)
+  catalog.register({
+    name: "create_skill",
+    description: "把一次成功的方法/流程沉淀为可复用的 Agent Skill。name=技能名(字母数字横线), description=一句话说明, content=SKILL.md 正文。正文推荐含三个段落(参考 addyosmani/agent-skills): ①「## 流程」逐步工作流+检查点 ②「## 反合理化」常见偷懒借口+反驳 ③「## 验证」完成后必须提供的证据。写进 skills/ 目录后自动被 loader 发现。",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "技能名, 仅字母/数字/横线" },
+        description: { type: "string", description: "技能一句话说明" },
+        content: { type: "string", description: "SKILL.md 正文 (建议含: 流程/反合理化/验证 三段)" },
+      },
+      required: ["name", "description", "content"],
+    },
+    category: "selfmod",
+    power: "agent",
+    execute: async (args) => {
+      const name = String(args.name || "").trim();
+      if (!/^[a-zA-Z0-9-]+$/.test(name)) return "[工具错误] create_skill: 技能名仅允许字母/数字/横线: " + name;
+      const desc = String(args.description || "").trim();
+      const content = String(args.content || "").trim();
+      if (!desc || !content) return "[工具错误] create_skill: 需 description + content";
+      // v1.0.8: 长度上限, 防写超大文件/垃圾内容
+      if (desc.length > 300) return "[工具错误] create_skill: description 超长 (最大 300 字符)";
+      if (content.length > 50000) return "[工具错误] create_skill: content 超长 (最大 50000 字符)";
+      const dir = path.join(skillsDir, name);
+      fs.mkdirSync(dir, { recursive: true });
+      const frontmatter = "---" + "\n" + "name: " + name + "\n" + "description: " + desc + "\n" + "---" + "\n" + "\n";
+      fs.writeFileSync(path.join(dir, "SKILL.md"), frontmatter + content, "utf8");
+      return "已创建技能: " + name + " (skills/" + name + "/SKILL.md)";
+    },
+  });
+
+  // 6b. 自我进化: 从失败轨迹自动提炼经验 (refine 的上半场, 补齐「失败→经验」闭环)
+  catalog.register({
+    name: "refine",
+    description: "从最近的失败工具调用轨迹自动提炼一条可复用经验教训 (自我进化闭环)。失败轨迹足够(≥2条)时, 用 LLM 提炼成一句话经验存进经验库, 后续任务自动注入上下文。",
+    parameters: { type: "object", properties: { limit: { type: "number", description: "回看轨迹条数, 默认 20" } }, required: [] },
+    category: "selfmod",
+    power: "agent",
+    execute: async (args, ctx) => {
+      const agent = ctx && ctx.agent;
+      if (!agent || typeof agent.refine !== "function") return capErr("refine", "无 agent 上下文");
+      const r = await agent.refine({ limit: Number(args && args.limit) || 20 });
+      return JSON.stringify(r);
+    },
+  });
+
+  // 7. 自我进化: 从成功轨迹自动提炼可复用 Skill (refine 的下半场)
+  catalog.register({
+    name: "refine_skill",
+    description: "从最近成功的工具调用轨迹自动提炼一个可复用 Skill (自我进化闭环)。成功轨迹足够且高频工具重复出现时, 用 LLM 提炼成 skills/<name>/SKILL.md。",
+    parameters: { type: "object", properties: { limit: { type: "number", description: "回看轨迹条数, 默认 50" } }, required: [] },
+    category: "selfmod",
+    power: "agent",
+    execute: async (args, ctx) => {
+      const agent = ctx && ctx.agent;
+      if (!agent || typeof agent.refineSkill !== "function") return capErr("refine_skill", "无 agent 上下文");
+      const r = await agent.refineSkill({ limit: Number(args && args.limit) || 50 });
+      return JSON.stringify(r);
+    },
+  });
+
+  // 6. Session Replay: 从原始日志恢复会话历史 (跨天/崩溃续跑)
+  catalog.register({
+    name: "replay_session",
+    description: "从原始对话日志恢复某会话的历史(跨天/崩溃后续跑)。sessionKey=会话名(默认default), days=回溯天数(默认7), limit=返回条数(默认40)。",
+    parameters: {
+      type: "object",
+      properties: {
+        sessionKey: { type: "string", description: "会话名, 默认 default" },
+        days: { type: "number", description: "回溯天数, 默认 7" },
+        limit: { type: "number", description: "返回条数, 默认 40" },
+      },
+      required: [],
+    },
+    category: "selfmod",
+    power: "user",
+    idempotent: true,
+    execute: async (args, ctx) => {
+      const agent = ctx && ctx.agent;
+      if (!agent || !agent.l0) return capErr("replay_session", "无 l0 记录器");
+      const msgs = agent.replaySession((args && args.sessionKey) || "default", {
+        days: Number(args && args.days) || 7,
+        limit: Number(args && args.limit) || 40,
+      });
+      if (!msgs.length) return "(该会话无历史记录)";
+      return msgs.map(m => `${m.role}: ${m.content}`).join("\n");
+    },
+  });
+
+  return catalog;
+}

package/src/tools/v3.js

@@ -0,0 +1,225 @@
+// src/tools/v3.js - v3.0 新工具注册 (codex 对齐)
+// repo_map(aider) / apply_patch(aider SR 编辑块+快照) / review_code(OCR 分级) / goal_board(OMH)
+// 零运行时依赖; 全部走 ToolCatalog 标准注册 (权限引擎/钩子链自动织入)。
+import fs from "node:fs";
+import path from "node:path";
+import { renderRepoMap } from "../repomap/index.js";
+import { parseEditBlocks, applyAll, formatRetryFeedback } from "../edit/editblock.js";
+import { Snapshot } from "../edit/snapshot.js";
+import { runReview } from "../review/index.js";
+import { safePath } from "./builtin.js";
+import { generateWiki, checkStaleness } from "../wiki/index.js";
+import { debug } from "../utils/logger.js";
+
+export function registerV3Tools(catalog, { rootDir, agent = null }) {
+  // 0. repo_wiki — 代码库 Wiki (2026-10-02 吸收 ZCode repo-wiki): 架构文档 + file:line 绑定 + 敏感排除
+  catalog.register({
+    name: "repo_wiki",
+    // 陈旧时自动刷新写入 docs/WIKI.md → 有工作区副作用, 不能声明 readOnly (诚实声明, ZCode 教训)
+    capability: { riskLevel: "low", sideEffect: "workspace" },
+    description: "生成代码库 Wiki 架构文档: 按目录列出核心定义 (签名+file:line) + 模块依赖 mermaid 图; 敏感文件 (token/secret/credential/password 等) 自动排除。可选写入 docs/WIKI.md。",
+    parameters: {
+      type: "object",
+      properties: {
+        save: { type: "boolean", description: "是否写入 docs/WIKI.md (默认 false 只返回文本)" },
+      },
+    },
+    execute: async (args) => {
+      const out = path.join(rootDir, "docs", "WIKI.md");
+      // ZCode 语义: 源码变化后 wiki 陈旧, 自动重生成而非返回过期内容
+      const staleness = checkStaleness(out, rootDir);
+      const w = generateWiki(rootDir, {});
+      const summary = `文件 ${w.stats.files} · 定义 ${w.stats.defs} · 依赖边 ${w.stats.edges} · 敏感排除 ${w.sensitiveSkipped}`;
+      if (args.save || staleness.stale) {
+        fs.mkdirSync(path.dirname(out), { recursive: true });
+        fs.writeFileSync(out, w.text + "\n", "utf8");
+        return `Wiki 已刷新写入 docs/WIKI.md (此前状态: ${staleness.reason}; ${summary})\n\n${w.text}`;
+      }
+      return `Wiki 概况 (${summary}; 上次生成于 docs/WIKI.md, ${staleness.reason}):\n\n${w.text}`;
+    },
+  });
+  // 0b. usage_stats — 会话级使用统计 (2026-10-02 吸收 ZCode 使用统计: 模型消耗/调用次数)
+  catalog.register({
+    name: "usage_stats",
+    capability: { readOnly: true, riskLevel: "low", sideEffect: "none" },
+    description: "查看本会话 LLM 使用统计: 调用次数 / token 消耗 / 按模型分解。",
+    parameters: { type: "object", properties: {} },
+    execute: async () => {
+      const s = agent?.usageStats;
+      if (!s) return JSON.stringify({ calls: 0, tokens: 0, byModel: {} });
+      return JSON.stringify({ calls: s.calls, tokens: s.tokens, byModel: s.byModel });
+    },
+  });
+  // 0c. self_diagnose — 自诊断 (2026-10-03, "按症状下药"表自动化: 症状→根因→增强动作)
+  catalog.register({
+    name: "self_diagnose",
+    capability: { readOnly: true, riskLevel: "low", sideEffect: "none" },
+    description: "Agent 自诊断: 从审计链/失败案例库/使用统计/任务基线聚合信号, 按症状输出根因与增强动作 (零 LLM, 确定性)。",
+    parameters: { type: "object", properties: {} },
+    execute: async () => {
+      const { diagnoseAgent } = await import("../services/diagnose.js");
+      const d = diagnoseAgent({
+        dataDir: agent?.dataDir || path.join(rootDir, "data"),
+        rootDir,
+        usageStats: agent?.usageStats,
+        // 记忆管线健康度 (2026-10-03 接线): MemoryHealthMonitor 曾装配却零消费, 现作为诊断信号源
+        health: agent?.memoryHealth && typeof agent.memoryHealth.status === "function" ? agent.memoryHealth.status() : null,
+      });
+      return d.report;
+    },
+  });
+  // 1. repo_map — 仓库地图 (PageRank 标识符排序, token 预算内渲染)
+  catalog.register({
+    name: "repo_map",
+    description: "生成仓库地图: 按重要性(PageRank)列出代码标识符与结构骨架, 用于快速理解代码库。省 token, 优先于全量读目录。",
+    parameters: {
+      type: "object",
+      properties: {
+        root: { type: "string", description: "仓库根目录 (相对工作目录, 默认 .)" },
+        token_budget: { type: "number", description: "渲染 token 预算 (默认 1024)" },
+      },
+      required: [],
+    },
+    execute: async (args) => {
+      // 2026-09-18 修复 (P2): repo_map 原先对 args.root 无路径防护,
+      //   绝对路径/.. 穿越可枚举工作区外任意目录的结构与标识符 (信息泄露面)。
+      //   现与 write_file/apply_patch 同一安全不变量: safePath 前缀 + realpath 双校验。
+      try {
+        safePath(rootDir, args.root || ".");
+      } catch (e) {
+        return JSON.stringify({ error: `路径被拒绝: ${e.message}` });
+      }
+      const root = path.resolve(rootDir, args.root || ".");
+      if (!fs.existsSync(root)) return JSON.stringify({ error: `目录不存在: ${args.root}` });
+      try {
+        const map = renderRepoMap(root, { tokenBudget: Number(args.token_budget) || 1024 });
+        return JSON.stringify({ stats: map.stats, text: map.text });
+      } catch (e) {
+        return JSON.stringify({ error: e.message });
+      }
+    },
+  });
+
+  // 2. apply_patch — SR 编辑块应用 (aider 语义: SEARCH/REPLACE + 快照回滚)
+  catalog.register({
+    name: "apply_patch",
+    description: "按 SEARCH/REPLACE 编辑块修改文件。输入含 <<<<<<< SEARCH / ======= / >>>>>>> REPLACE 的编辑文本, 支持多文件多块。比整体重写更省 token、更精准。",
+    parameters: {
+      type: "object",
+      properties: {
+        content: { type: "string", description: "含一个或多个 SEARCH/REPLACE 块的编辑文本" },
+      },
+      required: ["content"],
+    },
+    execute: async (args) => {
+      const blocks = parseEditBlocks(String(args.content || ""));
+      if (!blocks.length) return JSON.stringify({ error: "未找到任何 SEARCH/REPLACE 块" });
+      // 路径防护 (2026-09-18 修复 P1): 原实现直接 path.resolve(rootDir, b.path) 后写盘,
+      //   SEARCH/REPLACE 块携带绝对路径 (D:\...) 或 ..\..\ 穿越路径时可写工作区外任意文件,
+      //   且目标路径藏在 content 字符串里, permissions 的 findEscape 也看不见。
+      //   现统一走 safePath (前缀 + realpath 双重校验), 与 write_file 同一安全不变量。
+      try {
+        for (const b of blocks) safePath(rootDir, b.path);
+      } catch (e) {
+        return JSON.stringify({ error: `路径被拒绝: ${e.message}` });
+      }
+      // 快照所有目标文件 (回滚保险)
+      const snapPaths = [...new Set(blocks.map((b) => path.resolve(rootDir, b.path)))];
+      const snap = Snapshot.begin(snapPaths);
+      const byFile = new Map();
+      for (const b of blocks) {
+        const key = path.resolve(rootDir, b.path);
+        if (!byFile.has(key)) byFile.set(key, { file: b.path, blocks: [] });
+        byFile.get(key).blocks.push(b);
+      }
+      const results = [];
+      for (const { file, blocks: fblocks } of byFile.values()) {
+        const abs = path.resolve(rootDir, file);
+        if (!fs.existsSync(abs)) {
+          // 只支持新建: 全部块 search 为空
+          const allNew = fblocks.every((b) => !b.search.trim());
+          if (!allNew) { results.push({ file, ok: false, error: "not-found: 文件不存在且存在非新建块" }); continue; }
+          const content = fblocks.map((b) => b.replace).join("\n");
+          fs.mkdirSync(path.dirname(abs), { recursive: true });
+          fs.writeFileSync(abs, content, "utf8");
+          results.push({ file, ok: true, created: true });
+          continue;
+        }
+        let content = fs.readFileSync(abs, "utf8");
+        const r = applyAll(content, fblocks, { fuzzy: true });
+        if (!r.ok) {
+          results.push({ file, ok: false, error: r.error, feedback: formatRetryFeedback(r.results) });
+          continue;
+        }
+        fs.writeFileSync(abs, r.content, "utf8");
+        results.push({ file, ok: true, blocks: fblocks.length });
+      }
+      const failed = results.filter((r) => !r.ok);
+      // 任一失败 → 整体回滚 (aider: 原子性优先), 回灌反馈交给 LLM 修复
+      if (failed.length) {
+        try { Snapshot.rollback(snap); } catch (e) { debug(`[tools/v3] 已忽略异常: ${e && e.message ? e.message : e}`); }
+        return JSON.stringify({ ok: false, rolled_back: true, results, retry_hint: "请根据 feedback 修正 SEARCH 块后重试" });
+      }
+      return JSON.stringify({ ok: true, files: results.length, blocks: blocks.length, results });
+    },
+  });
+
+  // 3. review_code — 分级代码审查 (OCR 五阶段: plan→group→review→relocate→filter)
+  catalog.register({
+    name: "review_code",
+    description: "对指定文件(或最近变更)执行分级审查, 输出 P0/P1/P2 问题清单 (密钥泄漏/调试残留/空 catch 等)。结果同步到 Web UI 审查面板。",
+    parameters: {
+      type: "object",
+      properties: {
+        files: { type: "array", items: { type: "string" }, description: "待审查文件路径列表 (相对工作目录)" },
+        diff: { type: "string", description: "可选: 直接传 diff 文本" },
+      },
+      required: [],
+    },
+    execute: async (args) => {
+      let { files = [], diff = null } = args || {};
+      if (!files.length && !diff) {
+        // 兜底: 用 traces 里最近的写操作文件
+        const recent = (agent?.traces?.read?.("write_file", 10) || []);
+        files = recent.map((t) => t.args?.path).filter(Boolean);
+      }
+      const out = runReview({ files, diff });
+      // 报告存到 agent, Web UI /api/review/latest 直接读
+      if (agent) agent._lastReview = { issues: out.issues, report: out.report, ts: Date.now() };
+      return JSON.stringify({ ok: true, total: out.issues.length, issues: out.issues, report: out.report });
+    },
+  });
+
+  // 4. goal_board — 目标看板 (OMH goal board: 增删改查 + 只读渲染)
+  catalog.register({
+    name: "goal_board",
+    description: "目标看板: 记录/更新长期目标的优先级与状态 (pending/in_progress/blocked/done)。用户在 Web UI 看板实时可见。",
+    parameters: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["add", "update", "list"], description: "add=新增 update=更新状态 list=列出" },
+        id: { type: "string", description: "目标 id (update 时必填)" },
+        title: { type: "string", description: "目标标题 (add 时必填)" },
+        priority: { type: "string", enum: ["p0", "p1", "p2"], description: "优先级 (add 可选)" },
+        status: { type: "string", enum: ["pending", "in_progress", "blocked", "done"], description: "新状态 (update 时必填)" },
+      },
+      required: ["action"],
+    },
+    execute: async (args) => {
+      const board = agent?.goalBoard;
+      if (!board) return JSON.stringify({ error: "目标看板未装配" });
+      const a = args.action;
+      if (a === "add") {
+        if (!args.title) return JSON.stringify({ error: "add 需要 title" });
+        const g = board.addGoal({ title: args.title, priority: args.priority || "p2" });
+        return JSON.stringify({ ok: true, goal: g });
+      }
+      if (a === "update") {
+        if (!args.id || !args.status) return JSON.stringify({ error: "update 需要 id + status" });
+        const ok = board.updateStatus(args.id, args.status);
+        return JSON.stringify({ ok });
+      }
+      return JSON.stringify({ ok: true, goals: board.list(), text: board.render() });
+    },
+  });
+}