ppxans-harness 2.4.0

package/src/tools/methods.js

@@ -0,0 +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;
+}

package/src/tools/ocr.js

@@ -0,0 +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");
+}

package/src/tools/seam.js

@@ -0,0 +1,125 @@
+// src/tools/seam.js - 能力缝(Capability Seam)辅助层
+// 参考 deepseek-harness 的 Capability Seam 三分法:
+//   Service Definition(声明/元数据) / Service Provider(execute 实现) / Consumer(runWithPolicy 统一策略入口)
+// 零依赖, 纯 Node 原生。保留皮皮虾原有错误语义, 追加超时门禁/禁用门禁/追踪回调。
+
+export const TOOL_ERROR_PREFIX = "[工具错误]";
+
+// power 权限级: user < agent < super
+export const POWER_LEVEL = { user: 0, agent: 1, super: 2 };
+
+// ---- Definition 层: 元数据归一化 + 校验 ----
+export function normalizeMeta(def = {}) {
+  if (!def || typeof def.name !== "string" || !def.name) {
+    throw new Error("能力缝 Definition 失败: 需 name");
+  }
+  return {
+    name: def.name,
+    description: def.description || "",
+    parameters: def.parameters || { type: "object", properties: {}, required: [] },
+    // 能力缝新增元数据
+    category: def.category || "misc",        // 能力域: file/net/system/memory/selfmod/...
+    power: def.power || "user",              // 权限级: user/agent(0栓塞)
+    timeoutMs: Number(def.timeoutMs) || 0,   // 0 = 不限时
+    idempotent: !!def.idempotent,            // 是否可安全重试
+    enabled: def.enabled !== false,          // 默认启用
+    execute: def.execute,
+    // 工具钩子链 (吸收 OpenClaw before/after 钩子):
+    //  before(args, ctx) -> undefined 继续 | 字符串短路 | throw 拒绝
+    //  after(args, result, ctx) -> 后处理(结果审计/清理), 错误不阻塞
+    before: typeof def.before === "function" ? def.before : null,
+    after: typeof def.after === "function" ? def.after : null,
+  };
+}
+
+// ---- Consumer 层: 统一策略执行 ----
+// 统一处理: 禁用门禁 / 实现缺失 / 超时门禁 / 标准错误语义 / 追踪回调
+export async function runWithPolicy(meta, args, ctx = {}) {
+  if (meta.enabled === false) {
+    return `${TOOL_ERROR_PREFIX} ${meta.name}: 能力已禁用`;
+  }
+  // power 权限门禁: 仅当 ctx.power 明确提供时生效(向后兼容, 无 ctx.power 默认放行)
+  if (ctx && ctx.power) {
+    const need = POWER_LEVEL[meta.power] ?? 0;
+    const have = POWER_LEVEL[ctx.power] ?? 0;
+    if (have < need) {
+      return `${TOOL_ERROR_PREFIX} ${meta.name}: 权限不足(需要 ${meta.power}, 当前 ${ctx.power})`;
+    }
+  }
+  const fn = meta.execute;
+  if (typeof fn !== "function") {
+    return `${TOOL_ERROR_PREFIX} ${meta.name}: 无实现(Provider 缺失)`;
+  }
+  // before 钩子: 返回非 undefined 则短路(不执行), throw 则拒绝
+  if (meta.before) {
+    try {
+      const shortCircuit = await meta.before(args, ctx);
+      if (shortCircuit !== undefined && shortCircuit !== null) {
+        return typeof shortCircuit === "string" ? shortCircuit : JSON.stringify(shortCircuit);
+      }
+    } catch (e) {
+      return `${TOOL_ERROR_PREFIX} ${meta.name}: before 钩子拒绝: ${e.message}`;
+    }
+  }
+  let timer = null;
+  let timedOut = false;
+  const ctrl = new AbortController();
+  // 超时预算: 工具级声明优先 (meta.timeoutMs > 0), 否则全局默认 (ctx.timeoutMs, agent 从 config.agent.tool_timeout_ms 传入)
+  // v1.6.0 (第四刀): 无声明工具不再永不超时 — 有保守全局默认兑底, 避免单个慢工具卡死整个对话
+  const effectiveTimeout = meta.timeoutMs > 0 ? meta.timeoutMs : (Number(ctx.timeoutMs) || 0);
+  if (effectiveTimeout > 0) {
+    timer = setTimeout(() => { timedOut = true; ctrl.abort(); }, effectiveTimeout);
+  }
+  try {
+    // v1.6.0 (第四刀): 双层超时兜底 —
+    //   1) signal 传给 execute: 配合的工具提前终止释放资源 (资源超时)
+    //   2) Promise.race 强制超时返回: 不响应 signal 的工具也不至于永远挂住对话 (语义超时兜底)
+    // 这是文档指出的灰色地带: 光靠 abort 信号, 不配合的工具会无限期挂着。
+    const run = () => (fn.length >= 2 ? fn(args, { ...ctx, signal: ctrl.signal }) : fn(args));
+    let result;
+    if (effectiveTimeout > 0) {
+      let raceTimer = null;
+      const timeoutGuard = new Promise((_, reject) => {
+        raceTimer = setTimeout(() => reject(Object.assign(new Error("timeout"), { timedOut: true })), effectiveTimeout);
+      });
+      const pRun = Promise.resolve().then(run);
+      // 哨兵: 超时赢时工具方后到的 reject 忽略, 防 unhandledRejection 崩进程
+      pRun.catch(() => {});
+      try {
+        result = await Promise.race([pRun, timeoutGuard]);
+      } catch (e) {
+        if (e && e.timedOut) timedOut = true;
+        throw e;
+      } finally {
+        if (raceTimer) clearTimeout(raceTimer);
+      }
+    } else {
+      result = await run();
+    }
+    if (timedOut) return `${TOOL_ERROR_PREFIX} ${meta.name}: 超时`;
+    if (meta.after) {
+      try { await meta.after(args, result, ctx); } catch { /* after 钩子错误不阻塞 */ }
+    }
+    if (typeof ctx.onResult === "function") ctx.onResult(meta.name, "ok", null);
+    return typeof result === "string" ? result : JSON.stringify(result);
+  } catch (e) {
+    if (typeof ctx.onResult === "function") ctx.onResult(meta.name, "error", e.message);
+    return `${TOOL_ERROR_PREFIX} ${meta.name}: ${timedOut ? "超时" : e.message}`;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+// 供 selfmod 工具 / 追踪用的纯净元数据(不含 execute 实现)
+export function toDescriptor(meta) {
+  return {
+    name: meta.name,
+    description: meta.description,
+    parameters: meta.parameters,
+    category: meta.category,
+    power: meta.power,
+    timeoutMs: meta.timeoutMs,
+    idempotent: meta.idempotent,
+    enabled: meta.enabled,
+  };
+}

package/src/tools/selfmod.js

@@ -0,0 +1,176 @@
+// 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;
+}

package/src/utils/logger.js

@@ -0,0 +1,17 @@
+// src/utils/logger.js - 分级日志
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+
+let minLevel = LEVELS.info;
+
+export function setLevel(lv) {
+  if (lv in LEVELS) minLevel = LEVELS[lv];
+}
+
+function ts() {
+  return new Date().toISOString();
+}
+
+export function debug(...a) { if (minLevel <= LEVELS.debug) console.log(`[${ts()}] [debug]`, ...a); }
+export function info(...a)  { if (minLevel <= LEVELS.info)  console.log(`[${ts()}] [info]`, ...a); }
+export function warn(...a)  { if (minLevel <= LEVELS.warn)  console.log(`[${ts()}] [warn]`, ...a); }
+export function error(...a) { if (minLevel <= LEVELS.error) console.error(`[${ts()}] [error]`, ...a); }

package/src/utils/pii.js

@@ -0,0 +1,42 @@
+// src/utils/pii.js - PII / 凭证检测与脱敏 (架构参考 openhanako pii-guard)
+const HARD_PATTERNS = [
+  { name: "api_key", regex: /\b(sk-[a-zA-Z0-9]{20,}|AKIA[A-Z0-9]{16}|gsk_[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]{20,}|xoxb-[a-zA-Z0-9-]+)\b/g },
+  // v1.0.8: 放宽 inline_secret 值域 (含 :/# 等) + 8 位起, 短密钥不漏检 (原 16+ 位且不含 :#)
+  // P0 (2026-09-15): key 后允许可选闭合引号 —— 原版只匹配 key=value / key: value,
+  //   JSON 序列化形式 "key":"value" (key 后先有闭合引号) 完全漏检, 已修。
+  { name: "inline_secret", regex: /\b(api[_-]?key|secret[_-]?key|access[_-]?token|auth[_-]?token|password|bearer)["']?\s*[:=]\s*["']?([a-zA-Z0-9_/+=\-.:#]{8,})["']?/gi },
+  { name: "private_key", regex: /-----BEGIN\s+(RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/g },
+  { name: "credit_card", regex: /\b(?:\d{4}[- ]?){3}\d{4}\b/g },
+  { name: "id_card", regex: /\b\d{6}(?:19|20)\d{2}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])\d{3}[\dXx]\b/g },
+  { name: "ssn", regex: /\b\d{3}-\d{2}-\d{4}\b/g },
+  // v1.0.8: 邮箱 + 中国大陆手机号 (11 位, 1[3-9] 开头)
+  { name: "email", regex: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g },
+  { name: "phone", regex: /\b1[3-9]\d{9}\b/g },
+  // v1.6.0-dev: URL query 里的敏感参数值 (token/key/secret/sign 等) — 最常见的凭证泄漏渠道, 此前未覆盖
+  // 仅匹配参数名白名单, 避免误伤合法 URL 参数; 保留参数名, 只替换值
+  { name: "url_secret", regex: /([?&](?:token|key|secret|api[_-]?key|access[_-]?token|auth|sign|sig|password)=)[^&#\s"']*/gi, redact: (m, pre) => pre + "[REDACTED]" },
+];
+
+export function scrubPII(text) {
+  if (!text) return { cleaned: text, detected: [] };
+  const detected = [];
+  let cleaned = text;
+  for (const { name, regex, redact } of HARD_PATTERNS) {
+    regex.lastIndex = 0;
+    if (regex.test(cleaned)) {
+      detected.push(name);
+      regex.lastIndex = 0;
+      cleaned = cleaned.replace(regex, redact ? redact : "[REDACTED]");
+    }
+  }
+  return { cleaned, detected };
+}
+
+export function hasPII(text) {
+  if (!text) return false;
+  for (const { regex } of HARD_PATTERNS) {
+    regex.lastIndex = 0;
+    if (regex.test(text)) return true;
+  }
+  return false;
+}