ppxans-harness 2.6.0 → 3.2.1

package/skills/ppx-selfheal/scripts/cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// skills/ppx-selfheal/scripts/cli.js - 皮皮虾自愈引擎「独立运行版」CLI
+// 不依赖主项目 src/, 对数据目录做体检与修复 (与主项目共享 integrity.json 语义)
+//
+// 用法:
+//   node cli.js check    启动体检 (补建缺失目录 + 修复损坏 JSON)
+//   node cli.js crash    检查上次是否崩溃退出 (integrity.clean === false)
+//   node cli.js status   查看完整性状态
+//   node cli.js prune    清理过期备份 (损坏备份/备份目录/.bak, 各保留 2 份)
+//   node cli.js heal     完整自愈 (体检 + 崩溃恢复 + 残留清理)
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Healer } from "./healer.js";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+// 技能位于 <root>/skills/ppx-selfheal/scripts/ → ROOT 为三级之上
+const ROOT = process.env.PPX_ROOT || path.resolve(HERE, "..", "..", "..");
+const DATA = process.env.PPX_DATA_DIR || path.join(ROOT, "data");
+
+const out = (o) => console.log(typeof o === "string" ? o : JSON.stringify(o, null, 2));
+const healer = new Healer(ROOT, DATA);
+
+const cmd = process.argv[2] || "check";
+
+switch (cmd) {
+  case "check": {
+    const fixes = healer.runStartupChecks();
+    if (!fixes.length) out("体检通过: 无需修复 ✓");
+    else {
+      out(`完成 ${fixes.length} 项修复:`);
+      for (const f of fixes) out("  - " + (typeof f === "string" ? f : JSON.stringify(f)));
+    }
+    break;
+  }
+
+  case "crash": {
+    const crashed = healer.checkCrash();
+    out(crashed ? "⚠ 上次为崩溃退出 (integrity.clean === false), 建议跑 heal" : "上次为正常退出 ✓");
+    process.exit(crashed ? 1 : 0);
+  }
+
+  case "status": {
+    const f = path.join(DATA, "integrity.json");
+    if (!fs.existsSync(f)) {
+      out("(尚无 integrity.json, 未做过体检)");
+      break;
+    }
+    out(JSON.parse(fs.readFileSync(f, "utf8")));
+    break;
+  }
+
+  case "prune": {
+    healer.cleanupCorruptBackups(2);
+    healer.cleanupStaleBackupDirs(2);
+    healer.cleanupStaleBakFiles(2);
+    out("已清理过期备份 (各保留最近 2 份) ✓");
+    break;
+  }
+
+  case "heal": {
+    const fixes = healer.runStartupChecks();
+    const crashed = healer.checkCrash();
+    if (crashed) healer._cleanupTmp?.();
+    healer.cleanupCorruptBackups(2);
+    healer.cleanupStaleBackupDirs(2);
+    healer.cleanupStaleBakFiles(2);
+    out(`自愈完成: ${fixes.length} 项修复${crashed ? " + 崩溃残留清理" : ""} ✓`);
+    for (const f of fixes) out("  - " + (typeof f === "string" ? f : JSON.stringify(f)));
+    break;
+  }
+
+  default:
+    out(`皮皮虾自愈引擎 · 独立 CLI
+项目根: ${ROOT}
+数据目录: ${DATA}
+
+用法: check | crash | status | prune | heal`);
+    process.exit(1);
+}

package/skills/ppx-selfheal/scripts/healer.js

@@ -0,0 +1,184 @@
+// src/selfheal/healer.js - 自愈引擎
+// 1. 启动检查: 修复缺失目录/损坏JSON/权限
+// 2. 崩溃恢复: 检测上次异常退出, 清理残留
+// 3. 数据一致性: 校验记忆文件
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir, readJson } from "./store.js";
+import { info, warn } from "./logger.js";
+
+export class Healer {
+  // dataDir 可选: 显式传入真实数据目录 (PPX_DATA_DIR 可能指向非默认位置)。
+  // v1.0.8 修复 (P1-2): 原实现把 dataDir 硬编码为 path.join(rootDir, "data"),
+  //   而调用方 builtin.js 传进来的是 root 而非数据目录 —— 一旦 PPX_DATA_DIR 改到别处,
+  //   自愈就会在错误的目录里创建 memory/experience/logs、写 integrity.json、清理 .tmp,
+  //   形成"数据目录 / 自愈目录"分叉: 真实数据目录永不被体检, 空目录反而被反复重建。
+  //   默认值保留 rootDir/data, 让既有 15 处 `new Healer(root)` 调用点行为不变 (向后兼容)。
+  constructor(rootDir, dataDir = null) {
+    this.root = rootDir;
+    this.dataDir = dataDir || path.join(rootDir, "data");
+    this.integrity = path.join(this.dataDir, "integrity.json");
+  }
+
+  // 启动体检: 返回修复清单
+  runStartupChecks() {
+    const fixes = [];
+    ensureDir(this.dataDir);
+    for (const sub of ["memory", "memory/daily", "experience", "sessions", "logs"]) {
+      const d = path.join(this.dataDir, sub);
+      if (!fs.existsSync(d)) { fs.mkdirSync(d, { recursive: true }); fixes.push(`created dir: ${sub}`); }
+    }
+    // 校验关键 JSON 可解析
+    const facts = path.join(this.dataDir, "memory", "facts.json");
+    if (fs.existsSync(facts)) {
+      const parsed = readJson(facts, null);
+      if (parsed === null) {
+        // 损坏: 备份后重建
+        const bak = facts + ".corrupt-" + Date.now();
+        fs.renameSync(facts, bak);
+        fs.writeFileSync(facts, "[]", "utf8");
+        fixes.push(`facts.json corrupt -> backed up to ${path.basename(bak)}, reset`);
+      }
+    }
+    return fixes;
+  }
+
+  // 崩溃恢复: 检查上次是否干净退出
+  checkCrash() {
+    const state = readJson(this.integrity, { clean: true, pid: null });
+    const result = { crashed: false, detail: null };
+    if (state.clean === false) {
+      result.crashed = true;
+      result.detail = `上次进程 (pid=${state.pid}) 未干净退出, 可能残留临时文件`;
+      this._cleanupTmp();
+    }
+    return result;
+  }
+
+  _cleanupTmp() {
+    const walk = (dir) => {
+      if (!fs.existsSync(dir)) return;
+      for (const f of fs.readdirSync(dir)) {
+        const p = path.join(dir, f);
+        let st;
+        try { st = fs.statSync(p); } catch { continue; } // 并发删除竞态容错
+        if (st.isDirectory()) walk(p);
+        else if (f.endsWith(".tmp")) { try { fs.unlinkSync(p); } catch {} info(`cleaned tmp: ${f}`); }
+      }
+    };
+walk(this.dataDir);
+  }
+
+  markDirty() {
+    ensureDir(this.dataDir);
+    fs.writeFileSync(this.integrity, JSON.stringify({ clean: false, pid: process.pid, ts: Date.now() }), "utf8");
+  }
+
+  markClean() {
+    ensureDir(this.dataDir);
+    fs.writeFileSync(this.integrity, JSON.stringify({ clean: true, pid: process.pid, ts: Date.now() }), "utf8");
+  }
+
+  // ---- 备份清理 (2026-09-18 重构: 原先三个方法各抄一份「收集→按 mtime 排序→保留最近 N→删其余」) ----
+
+  // 通用清理器: collect() 给出候选 [{p, mtime}] → 按 mtime 新→旧排序 → 保留最近 keep 个, 其余逐个 remove
+  // 单个删除失败只告警不中断 (与原来逐方法 try/catch 语义一致)。
+  _pruneByMtime({ keep, collect, remove, logLabel, warnLabel }) {
+    const all = collect();
+    all.sort((a, b) => b.mtime - a.mtime);
+    const removed = [];
+    for (const item of all.slice(keep)) {
+      try { remove(item.p); removed.push(path.basename(item.p)); }
+      catch (e) { warn(`清理${warnLabel}失败: ${item.p}: ${e.message}`); }
+    }
+    if (removed.length) info(`selfheal: 清理旧${logLabel} ${removed.length} 个: ${removed.join(", ")}`);
+    return removed;
+  }
+
+  // 递归收集 dataDir 下满足 pred(fileName) 的文件 (带 mtime)
+  _collectFilesBy(pred) {
+    const found = [];
+    const walk = (d) => {
+      if (!fs.existsSync(d)) return;
+      for (const f of fs.readdirSync(d)) {
+        const p = path.join(d, f);
+        let st;
+        try { st = fs.statSync(p); } catch { continue; }
+        if (st.isDirectory()) walk(p);
+        else if (pred(f)) found.push({ p, mtime: st.mtimeMs });
+      }
+    };
+    walk(this.dataDir);
+    return found;
+  }
+
+  // 清理历史 corrupt 备份: 保留最近 N 个, 更早自动删除 (默认保留 2)
+  cleanupCorruptBackups(keep = 2) {
+    return this._pruneByMtime({
+      keep,
+      collect: () => this._collectFilesBy((f) => f.includes(".corrupt-")),
+      remove: (p) => fs.unlinkSync(p),
+      logLabel: "corrupt 备份",
+      warnLabel: "损坏备份",
+    });
+  }
+
+  // 清理历史手动备份目录 (memory-backup-*): 保留最近 N 个, 更早自动删除 (默认保留 2)
+  // 手动全量备份目录不在 corrupt 备份机制内, 若无清理会持续累积磁盘占用
+  cleanupStaleBackupDirs(keep = 2) {
+    return this._pruneByMtime({
+      keep,
+      collect: () => {
+        if (!fs.existsSync(this.dataDir)) return [];
+        const dirs = [];
+        for (const f of fs.readdirSync(this.dataDir)) {
+          if (!f.startsWith("memory-backup-")) continue;
+          const p = path.join(this.dataDir, f);
+          let st;
+          try { st = fs.statSync(p); } catch { continue; }
+          if (st.isDirectory()) dirs.push({ p, mtime: st.mtimeMs });
+        }
+        return dirs;
+      },
+      remove: (p) => fs.rmSync(p, { recursive: true, force: true }),
+      logLabel: "手动备份目录",
+      warnLabel: "过期备份目录",
+    });
+  }
+
+  // 清理历史 .bak-* 文件 (去重/迁移等一次性工具留下的手动备份): 保留最近 N 个, 更早自动删除 (默认保留 2)
+  // 覆盖 facts.json.bak-* / lessons.json.bak-* 等, 防手动备份文件在 data/ 内无限累积
+  cleanupStaleBakFiles(keep = 2) {
+    return this._pruneByMtime({
+      keep,
+      collect: () => this._collectFilesBy((f) => f.includes(".bak-") && !f.endsWith(".lock")),
+      remove: (p) => fs.unlinkSync(p),
+      logLabel: ".bak-* 备份文件",
+      warnLabel: "过期备份文件",
+    });
+  }
+  
+  // 完整自愈入口
+  // 2026-09-17 体检修复: 原实现把"崩溃残留已清理, 状态置回 clean"打在"修复 N 项"与
+  //   "检测到崩溃残留 -> ..."之前, 日志里表现为「先说痊愈、再说发现崩溃」的因果颠倒,
+  //   使用者会怀疑自愈到底有没有生效。现按"先报问题 → 再报处置 → 最后报结果"的顺序输出。
+  heal() {
+    // 1) 先判定上次是否崩溃 (必须在 runStartupChecks 之前判定, 否则重建的目录会掩盖证据)
+    const crash = this.checkCrash();
+    if (crash.crashed) warn(`selfheal: 检测到崩溃残留 -> ${crash.detail}`);
+    // 2) 启动体检 + 备份清理
+    const fixes = this.runStartupChecks();
+    // 清理历史 corrupt 备份 (保留最近 2 个, 更早自动删除) — 之前漏调用导致 corrupt 持续累积
+    const cleanedCorrupt = this.cleanupCorruptBackups(2);
+    // 清理历史手动备份目录 (保留最近 2 个)
+    const cleanedBackupDirs = this.cleanupStaleBackupDirs(2);
+    // 清理历史 .bak-* 文件 (保留最近 2 个)
+    const cleanedBakFiles = this.cleanupStaleBakFiles(2);
+    // 3) 处置回执: 崩溃残留清理后主动翻回 clean —— 自愈闭环, 清了毒就要"宣布痊愈",
+    //    否则下次启动还误报崩溃
+    if (crash.crashed) { this.markClean(); info("selfheal: 崩溃残留已清理, 状态置回 clean"); }
+    if (fixes.length) info(`selfheal: 修复 ${fixes.length} 项: ${fixes.join("; ")}`);
+    else info("selfheal: 无异常");
+    return { fixes, crashed: crash.crashed, crashDetail: crash.detail, cleanedCorrupt, cleanedBackupDirs, cleanedBakFiles };
+  }
+}

package/skills/ppx-selfheal/scripts/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/skills/ppx-selfheal/scripts/store.js

@@ -0,0 +1,116 @@
+// src/utils/store.js - 零依赖文件存储 (JSON + 原子写)
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function atomicWrite(file, data) {
+  ensureDir(path.dirname(file));
+  const tmp = file + "." + crypto.randomBytes(4).toString("hex") + ".tmp";
+  fs.writeFileSync(tmp, data, "utf8");
+  // v1.0.8: rename 覆盖已存在文件在 Windows 并发下可能 EPERM/EEXIST (短窗口), 重试 3 次;
+  // 不再降级为非原子直接写 (并发双写可交错损坏文件), 重试仍失败则抛错由调用方处理
+  for (let attempt = 0; ; attempt++) {
+    try {
+      fs.renameSync(tmp, file);
+      return;
+    } catch (e) {
+      if (attempt >= 2) {
+        try { fs.unlinkSync(tmp); } catch {}
+        throw new Error(`原子写失败: ${file} (${e.message})`);
+      }
+      const end = Date.now() + 30;
+      while (Date.now() < end) {} // 短延迟后重试
+    }
+  }
+}
+
+export function readJson(file, fallback = null) {
+  try {
+    if (!fs.existsSync(file)) return fallback;
+    let raw = fs.readFileSync(file, "utf8");
+    if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1); // 去 BOM
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+
+export function writeJson(file, obj) {
+  atomicWrite(file, JSON.stringify(obj, null, 2));
+}
+
+// 简单跨进程文件锁 (零依赖, 同步): 原子创建 .lock 文件, 临界区内执行 fn, finally 释放
+// 用于跨 agent 共享文件的"读-改-写"临界区 (防并发覆盖, 如共享经验库)
+// 锁是同步 busy-wait (低频写场景可接受); 超时视为陈旧锁 (崩溃残留) 强取
+export function withFileLock(file, fn, { timeoutMs = 3000, pollMs = 20 } = {}) {
+  const lock = file + ".lock";
+  const acquire = () => {
+    try {
+      const fd = fs.openSync(lock, "wx"); // 'wx': 已存在则抛错 (原子)
+      try { fs.writeSync(fd, String(process.pid)); } catch {}
+      fs.closeSync(fd);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const start = Date.now();
+  while (!acquire()) {
+    if (Date.now() - start > timeoutMs) {
+      try { fs.rmSync(lock, { force: true }); } catch {} // 陈旧锁强取
+      if (!acquire()) throw new Error("文件锁获取超时: " + lock);
+      break;
+    }
+    const end = Date.now() + pollMs;
+    while (Date.now() < end) {} // 同步短暂等待
+  }
+  try {
+    return fn();
+  } finally {
+    try { fs.rmSync(lock, { force: true }); } catch {}
+  }
+}
+
+export function readText(file, fallback = "") {
+  try {
+    if (!fs.existsSync(file)) return fallback;
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return fallback;
+  }
+}
+
+export function writeText(file, text) {
+  atomicWrite(file, text);
+}
+
+export function appendLine(file, line) {
+  ensureDir(path.dirname(file));
+  fs.appendFileSync(file, line + "\n", "utf8");
+}
+
+export function nowISO() {
+  return new Date().toISOString();
+}
+
+export function logicalDay(d = new Date()) {
+  // 逻辑日 (本地时区): 今日/归档/按天检索统一用本地年月日
+  // 与 eventsByDay() 的本地解析保持一致, 避免 8 小时时区偏移导致按天检索错位
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+
+// 按逻辑日切分 JSONL 的日志目录 (工具轨迹 utils/trace.js 与事件流 core/trace.js 共用)。
+// 两个写入器必须落在同一目录, 用同一函数取路径可避免字面量各写一份后悄悄漂移。
+export function logsDir(dataDir, sub = "traces") {
+  const dir = path.join(dataDir, "logs", sub);
+  ensureDir(dir);
+  return dir;
+}

package/skills/prompt-depth-kit/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: prompt-depth-kit
+description: 回答表达深度提示词方案库。同一问题输出不同深度的三套方案（主动边界探索 / 情境化优先级 / 极简优雅），按场景选型。需要提升回答质量与信息密度时使用。
+---
+
+# 回答表达深度提示词方案库（Prompt Depth Kit）
+
+面对"回答太浅/太啰嗦/不切重点"三类问题时，按目标选一套方案注入提示词。
+
+## 流程
+
+1. **判型**：先分清问题出在哪 —— 信息不足（浅）、重点不明（散）、还是话太多（冗）。
+2. **选方案**（三选一，不要叠加）：
+   - **方案一 · 主动边界探索型（The Proactive Explorer）** —— 治"浅"。要求先摊开问题边界：已知什么、未知什么、哪些假设没验证，再给结论。适合技术选型、方案评审。
+   - **方案二 · 情境化优先级型（The Contextual Prioritizer）** —— 治"散"。要求先排序：在**当前这个具体情境**下，哪一条最要紧、哪一条可以暂时不管。适合多问题并发、资源有限时的决策。
+   - **方案三 · 极简优雅型（The Elegant Minimalist）** —— 治"冗"。要求砍掉一切铺垫与复述，只留结论与依据。适合结论已明确、只需要传达的场合。
+3. **落地**：把选中方案的措辞写进 system prompt 或任务描述，**一次只加一套**——三套同时塞进去会互相打架，模型只会变得更啰嗦。
+4. **校验**：对比注入前后同一问题的输出长度与信息密度，确认真的变好了。
+
+## 反合理化
+
+- "三套都写上，模型自己会选"——模型不会选，只会把三种要求揉成一锅。
+- "先随便选一个试试"——选错方案比不选更糟，会放大原来的毛病。
+- "回答越长越显得认真"——冗长是认知负担，不是深度。
+
+## 验证
+
+必须给出：① 判定属于哪一类问题；② 选中的方案及理由；③ 注入前后的对比样本（同一问题的两次输出）。

package/skills/session-naming/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: session-naming
+description: 会话自动命名模板。把首轮对话压缩成 4-12 字的可辨识标题，避免会话列表全是"新对话"。需要给会话/任务起名、批量整理标题时使用。
+---
+
+# 会话命名模板（Session Naming Kit）
+
+## 流程
+
+1. **取信号**：只看首轮对话里"用户想干什么"这件事——不要用问候语、不要用助手回复的开场白。
+2. **压到 4–12 字**：中文按字算，英文按词算。超出就砍修饰语，保动作与对象。
+3. **去泛词**：`帮我` / `请` / `一下` / `关于` / `问题` 一律删掉——它们不提供区分度。
+4. **保专名**：项目名、文件名、技术栈、版本号属于高价值信号，优先保留。
+5. **同名去重**：与已有会话标题重复时，追加可区分后缀（日期 / 序号 / 具体对象）。
+
+## Few-shot 示例
+
+| 首轮对话（节选） | 坏命名 | 好命名 |
+|---|---|---|
+| "你好，帮我看看这个 PPXANS-Harness 项目为什么跑不起来" | 新对话 | PPX 内核启动失败排查 |
+| "我想优化一下记忆检索的排序算法" | 讨论 | L1 记忆 BM25 排序优化 |
+| "把这个 md 拆成按主题的小文件" | 文件处理 | 提示词合集按主题拆分 |
+| "现在几点了" | 时间查询 | —（寒暄/单轮，不起名） |
+| "继续" | 继续 | —（无信息量，沿用上轮标题） |
+
+> 判据：**如果这个标题不能让你在两周后一眼认出是哪次对话，就重写。**
+
+## 反合理化
+
+- "用第一句话原文当标题"——原文包含问候与口语，区分度低。
+- "给寒暄也起个名"——"你好"起的任何名字都是噪音。
+- "标题越长越准确"——列表里只显示十几个字，长的会被截断，等于没写。
+
+## 验证
+
+必须给出：① 生成标题；② 字数与去词记录；③ 与已有会话标题的重名检查结果。

package/skills/verify/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: verify
+description: 交付前证据核验：任何"做完了"的结论都必须附可复现证据。改代码、修缺陷、跑任务收尾时使用。
+---
+
+# verify — 完成前核验
+
+## 流程
+
+1. **列出断言**：把"已完成"拆成可判定的原子断言（例：内核能启动 / 测试 0 失败 / 接口返回 200）。
+2. **为每条断言指定证据命令**：必须是别人能照抄复现的命令，不是"我看过了"。
+3. **真跑**：执行命令，原样记录输出（含失败）。
+4. **对账**：断言 → 证据 → 通过/不通过。任何一条没证据，就标"未验证"。
+5. **失败即停**：不通过就修，修完重跑全套，不挑着跑。
+
+## 反合理化
+
+- "应该没问题"——"应该"不是证据。
+- "这个改动很小"——小改动照样要跑回归。
+- "本地测过了"——本地过了但没跑全量，等于没测。
+- "日志里没报错"——没报错 ≠ 跑通了，可能是分支没进。
+
+## 验证
+
+收尾必须提供：① 断言清单；② 每条对应的命令与原始输出；③ 明确的通过/不通过结论。禁止只报"已完成"。