ppxans-harness 2.4.0 → 3.2.0

package/skills/ppx-memory/scripts/session.js

@@ -0,0 +1,398 @@
+// src/memory/session.js - 会话事件日志 (吸收 dsh "会话即唯一事实源")
+// 新架构: 不可变 append-only 事件日志, 每条 = {seq, ts, type, data}
+//  - 模型可见历史 = deriveMessages() 从日志投影 (无可变状态, 仅从日志重建)
+//  - replay() 回放完整事件流 | fork() 从边界派生新会话
+//  - 兼容旧 get/set/has/delete 接口 (agent 无需全量改动)
+// 吸收自 DeepSeek Harness: "model-visible means logged" (能进模型的必须能从日志重建)
+//
+// v1.1.x 第九轮 review P2: default 主会话按天分片 (default-YYYY-MM-DD.jsonl),
+// 单文件不再无限增长。设计要点:
+//  - 仅 key === "default" 走按天分片; 非 default 会话保持单文件 (不扩散改动面)
+//  - 命名: default-YYYY-MM-DD.jsonl (取事件 ts 所在本地自然日, 与 eventsByDay/logicalDay 一致)
+//  - 兼容旧文件: 若历史遗留 default.jsonl, 读取时纳入合并, 不丢历史
+//  - seq 跨天连续递增: 同一 default 会话所有分片共用一个 seq 序列, 不从 1 重头数
+//    (否则 compaction 的 upToSeq / fork / replay 会错乱)
+//  - 所有读取路径把多天分片合并成按 seq(ts) 升序的单一事件流
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir, logicalDay } from "./store.js";
+
+// 事件类型集 (对齐 dsh 事件域: user/assistant/tool/system)
+export const EVENTS = {
+  USER: "user/message",
+  ASSISTANT: "assistant/message",
+  SYSTEM: "system",
+  TOOL_CALL: "tool/call",
+  TOOL_RESULT: "tool/result",
+  COMPACTION: "compaction/summary",
+};
+
+// default 会话按天分片: default-YYYY-MM-DD.jsonl
+const DEFAULT_SHARD_RE = /^default-\d{4}-\d{2}-\d{2}\.jsonl$/;
+
+export class SessionStore {
+  constructor(dataDir) {
+    this.dir = path.join(dataDir, "sessions");
+    ensureDir(this.dir);
+    this._logs = new Map();    // key -> event[] (不可变, append-only)
+    this._nextSeq = new Map(); // key -> 下一个 seq
+    this._flushedSeq = new Map(); // key -> 已落盘的最大 seq (增量追加用)
+    this._loadAll();
+    // --- 派生缓存 (v1.1.1 性能优化) ---
+    // eventsByDay / deriveCompacted 在每一轮/每一工具轮都被调用, 旧实现每次全量扫描 O(T)。
+    // 事件日志是 append-only 不可变, 一个 key 的 events 数组只增不改（set/rename/fork 会换新数组）。
+    //   · deriveCompacted: 以"数组引用标识"做增量缓存——数组没换就只把尾部新事件追加进 msgs, 命中 O(Δ)；
+    //     数组被替换(重命名/重建)则重算。compaction 事件追加时检测到也整体重算（它会重投影历史）。
+    //   · eventsByDay: 版本门控的全库按天缓存, 版本变化时整库重扫一次（每轮兜底, 仍远优于每次 O(T)）。
+    this._version = 0;                  // 全局版本: 任何 write 递增
+    this._dayCache = new Map();         // day -> 该天结果 (当期 version)
+    this._dayCacheAt = 0;               // 生成该缓存时的 _version
+    // deriveCompacted 增量缓存: key -> { arrRef, msgs, lastCompSeq }
+    this._compactedCache = new Map();
+  }
+
+  _bump() { this._version += 1; }
+
+  _safe(key) { return String(key || "default").replace(/[^\w.-]/g, "_"); }
+  // 旧单文件路径 (仅非 default 会话使用)
+  _file(key) { return path.join(this.dir, this._safe(key) + ".jsonl"); }
+
+  _log(key) {
+    const k = this._safe(key);
+    if (!this._logs.has(k)) { this._logs.set(k, []); this._nextSeq.set(k, 0); }
+    return this._logs.get(k);
+  }
+
+  // 判断文件名是否为 default 的日分片
+  _isShard(fname) { return DEFAULT_SHARD_RE.test(fname); }
+  // default 分片文件路径 (day 形如 YYYY-MM-DD)
+  _shardFile(day) { return path.join(this.dir, `default-${day}.jsonl`); }
+  // 事件 ts 归属的本地自然日 (复用 utils/store.logicalDay, 与 eventsByDay 一致, 避免时区错位;
+  // 2026-09-18 重构: 原先这里手写了一份与 logicalDay 相同的实现, 双份易漂移)
+  _dayOf(ts) {
+    return logicalDay(new Date(ts));
+  }
+  // 列出 default 相关的所有文件 (旧单文件 + 各日分片)
+  _defaultFiles() {
+    let files = [];
+    try {
+      files = fs.readdirSync(this.dir)
+        .filter((f) => f.endsWith(".jsonl") && (f === "default.jsonl" || this._isShard(f)));
+    } catch {}
+    return files.map((f) => path.join(this.dir, f));
+  }
+  _removeDefaultFiles() {
+    for (const f of this._defaultFiles()) { try { fs.rmSync(f, { force: true }); } catch {} }
+  }
+
+  // 读取单个 jsonl 文件的事件序列
+  _readEventsFromFile(file) {
+    const events = [];
+    try {
+      for (const l of fs.readFileSync(file, "utf8").split("\n").filter(Boolean)) {
+        try { const e = JSON.parse(l); if (e && e.seq && e.type && e.data) events.push(e); } catch {}
+      }
+    } catch {}
+    return events;
+  }
+
+  _loadAll() {
+    let files = [];
+    try { files = fs.readdirSync(this.dir).filter((f) => f.endsWith(".jsonl")); } catch { return; }
+    for (const f of files) {
+      // default 的旧单文件 + 日分片 → 归并到同一个 key="default"
+      if (f === "default.jsonl" || this._isShard(f)) {
+        const events = this._readEventsFromFile(path.join(this.dir, f));
+        if (events.length) {
+          const k = "default";
+          const cur = this._logs.get(k) || [];
+          this._logs.set(k, cur.concat(events));
+        }
+        continue;
+      }
+      const k = f.replace(/\.jsonl$/, "");
+      const events = this._readEventsFromFile(path.join(this.dir, f));
+      if (events.length) {
+        events.sort((a, b) => a.seq - b.seq);
+        this._logs.set(k, events);
+        this._nextSeq.set(k, events[events.length - 1].seq);
+        this._flushedSeq.set(k, events[events.length - 1].seq);
+      }
+    }
+    // default: 跨文件合并后按 seq(ts 兜底) 升序 + 统一 next/flushed seq (跨天连续递增)
+    if (this._logs.has("default")) {
+      const evs = this._logs.get("default");
+      evs.sort((a, b) => a.seq - b.seq || a.ts - b.ts);
+      this._nextSeq.set("default", evs[evs.length - 1].seq);
+      this._flushedSeq.set("default", evs[evs.length - 1].seq);
+    }
+  }
+
+  // 追加事件 (唯一写入路径, append-only, 永不重写/裁剪日志文件)
+  // ts 可选: 测试/回溯时可注入固定时间戳; 缺省用 Date.now() (向后兼容)
+  // 追加事件 (唯一写入路径, append-only, 永不重写/裁剪日志文件)
+  // ts 可选: 测试/回溯时可注入固定时间戳; 缺省用 Date.now() (向后兼容)
+  // opts.skipFlush: true 时延后落盘 (调用方需随后显式 flush(key) 或下次 append), 用于一次性批量写入
+  append(key, type, data, ts, { skipFlush = false } = {}) {
+    const k = this._safe(key);
+    const seq = (this._nextSeq.get(k) || 0) + 1;
+    const ev = { seq, ts: Number.isFinite(ts) ? ts : Date.now(), type, data };
+    this._log(k).push(ev);
+    this._nextSeq.set(k, seq);
+    if (!skipFlush) this._flush(k);
+    this._bump(); // 使派生缓存失效
+    return ev;
+  }
+
+  // 显式落盘: 把 skipFlush 延后的待写事件写入磁盘 (供批量写入后调用)
+  flush(key) { this._flush(this._safe(key)); }
+
+  // 从日志投影模型可见历史 (user/assistant), 无可变状态
+  deriveMessages(key) {
+    return this._log(this._safe(key))
+      .filter((e) => e.type === EVENTS.USER || e.type === EVENTS.ASSISTANT)
+      .map((e) => ({ role: e.type === EVENTS.USER ? "user" : "assistant", content: e.data?.content }));
+  }
+
+  // 投影「压缩后」的模型可见历史: 最后一条 compaction 事件之前 (seq <= upToSeq) 的消息被摘要替换
+  // 吸收 OpenClaw compaction: 摘要作为单一 surface node 替换被压缩区间, 日志本身不可变
+  // v1.1.1: 增量缓存——数组引用没变时只 O(Δ) 追加尾部消息; 数组被替换或追加 compaction 时整体重算。
+  deriveCompacted(key) {
+    const k = this._safe(key);
+    const evs = this._log(k);
+    const cached = this._compactedCache.get(k);
+    // 数组引用未变 (append-only 稳定), 且无新 compaction: 只把尾部新 user/assistant 追加进 msgs
+    if (cached && cached.arrRef === evs) {
+      if (cached.consumed === evs.length) return cached.msgs; // 无新增, 直接命中
+      // 检查新增区间是否含 compaction (compaction 会重投影历史, 需整体重算)
+      for (let i = cached.consumed; i < evs.length; i++) {
+        if (evs[i].type === EVENTS.COMPACTION) return this._deriveCompactedFrom(evs, k);
+      }
+      // 只有 user/assistant 追加: 把可见的尾部消息追加进 msgs
+      for (let i = cached.consumed; i < evs.length; i++) {
+        const e = evs[i];
+        if (e.type === EVENTS.USER || e.type === EVENTS.ASSISTANT) {
+          cached.msgs.push({ role: e.type === EVENTS.USER ? "user" : "assistant", content: e.data?.content });
+        }
+      }
+      cached.consumed = evs.length;
+      return cached.msgs;
+    }
+    // 无缓存 / 数组被替换 (set/rename/fork/delete): 整体重算
+    return this._deriveCompactedFrom(evs, k);
+  }
+
+  _deriveCompactedFrom(evs, k) {
+    let lastComp = null;
+    for (const e of evs) if (e.type === EVENTS.COMPACTION) lastComp = e;
+    const upToSeq = lastComp?.data?.upToSeq || 0;
+    const msgs = [];
+    let consumed = 0;
+    if (lastComp?.data?.summary) {
+      msgs.push({ role: "system", content: String(lastComp.data.summary) });
+    }
+    for (const e of evs) {
+      consumed++;
+      if (e.seq <= upToSeq) continue;
+      if (e.type === EVENTS.USER || e.type === EVENTS.ASSISTANT) {
+        msgs.push({ role: e.type === EVENTS.USER ? "user" : "assistant", content: e.data?.content });
+      }
+    }
+    this._compactedCache.set(k, { arrRef: evs, msgs, consumed, lastCompSeq: lastComp?.seq || 0 });
+    return msgs;
+  }
+
+  // 完整事件流 (回放/审计/轨迹)
+  replay(key) { return [...this._log(this._safe(key))]; }
+
+  // L0 只读代理 / 按天审计: 遍历所有会话, 派生某天的对话事件 (消除 l0/*.jsonl 重复)
+  // v1.1.1: 全库按天缓存, 版本未变则零成本; 保持"本地自然日"语义 (与 _dayOf/logicalDay 一致, 避免时区错位)
+  eventsByDay(day) {
+    const dayStr = String(day).slice(0, 10);
+    const dayMs = new Date(dayStr + "T00:00:00").getTime();
+    if (Number.isNaN(dayMs)) return [];
+    // 缓存: 版本未变时按 day 命中 (append 后 _bump 使整个缓存失效, 下轮重扫一次)
+    if (this._dayCacheAt === this._version && this._dayCache.size) {
+      const hit = this._dayCache.get(dayStr);
+      if (hit) return hit;
+    }
+    // 全库扫描一次, 按"事件 ts 的本地自然日"聚合缓存所有天 → 之后所有 eventsByDay 调用都命中
+    const byDay = new Map();
+    for (const [key, events] of this._logs) {
+      for (const e of events) {
+        if (e.type !== EVENTS.USER && e.type !== EVENTS.ASSISTANT) continue;
+        const d = this._dayOf(e.ts);
+        let arr = byDay.get(d);
+        if (!arr) { arr = []; byDay.set(d, arr); }
+        arr.push({ sessionKey: key, role: e.type === EVENTS.USER ? "user" : "assistant", content: e.data?.content, timestamp: e.ts });
+      }
+    }
+    this._dayCache = byDay;
+    this._dayCacheAt = this._version;
+    // 2026-09-18 修复: 每一天的缓存数组都必须在入缓存前排好时间序 ——
+    //   原实现只对当次请求的 day 排序, 其余天命中缓存时返回的是事件追加顺序 (乱序)
+    for (const arr of byDay.values()) arr.sort((a, b) => a.timestamp - b.timestamp);
+    const out = byDay.get(dayStr) || [];
+    return out;
+  }
+
+  // 返回某自然日的对话事件(带 seq/type/data), 供 memory-ticker 按 seq 去重滚动归档
+  // (防止 _compileDaily_Rolling 每次把今日全文再次追加, 造成 longterm 内容重复累积)
+  replayDay(day) {
+    const dayStr = String(day).slice(0, 10);
+    const out = [];
+    for (const [, events] of this._logs) {
+      for (const e of events) {
+        if (e.type !== EVENTS.USER && e.type !== EVENTS.ASSISTANT) continue;
+        if (this._dayOf(e.ts) !== dayStr) continue;
+        out.push(e);
+      }
+    }
+    out.sort((a, b) => a.seq - b.seq);
+    return out;
+  }
+
+  // fork: 从 boundarySeq 及更早派生新会话 (吸收 dsh fork 语义, 保留不可变源)
+  fork(fromKey, boundarySeq, toKey) {
+    const keep = this._log(this._safe(fromKey)).filter((e) => e.seq <= boundarySeq);
+    const k = this._safe(toKey);
+    // 目标为 default 时先清掉旧分片, 再按边界重建 (避免 keep 追加到已有同 seq 行造成重复)
+    if (k === "default") this._removeDefaultFiles();
+    this._logs.set(k, [...keep]);
+    this._nextSeq.set(k, keep.length ? keep[keep.length - 1].seq : 0);
+    this._flushedSeq.delete(k);
+    this._flush(k);
+    this._bump();
+    return keep;
+  }
+
+  // count: 事件条数
+  count(key) { return this._log(this._safe(key)).length; }
+
+  // 列出所有会话: {key, count, lastTs, title} (title 取首条 user 消息前 20 字)
+  // 供 Web UI 多会话管理 (P1#6)
+  list() {
+    const out = [];
+    for (const [key, events] of this._logs) {
+      if (!events.length) continue;
+      const firstUser = events.find((e) => e.type === EVENTS.USER);
+      const title = firstUser?.data?.content ? String(firstUser.data.content).slice(0, 20) : key;
+      out.push({
+        key,
+        count: events.length,
+        lastTs: events[events.length - 1].ts,
+        title,
+      });
+    }
+    out.sort((a, b) => (b.lastTs || 0) - (a.lastTs || 0));
+    return out;
+  }
+
+  // ---- 兼容旧接口 (agent/CLI 仍可用) ----
+  get(key) { return this.deriveMessages(key); }
+  set(key, history) {
+    const k = this._safe(key);
+    // default 为分片存储: 清掉内存前先删旧分片, 保证重建后磁盘与内存一致 (无残留旧文件)
+    if (k === "default") this._removeDefaultFiles();
+    this._logs.delete(k); this._nextSeq.set(k, 0); this._flushedSeq.delete(k);
+    for (const m of (history || [])) this.append(k, m.role === "user" ? EVENTS.USER : EVENTS.ASSISTANT, { content: m.content });
+    return history;
+  }
+  has(key) { return this._logs.has(this._safe(key)); }
+  // 重命名会话: 复制事件到新 key 并删除旧 key (保留 seq 顺序) [P1#6]
+  rename(fromKey, toKey) {
+    const f = this._safe(fromKey), t = this._safe(toKey);
+    if (f === t) return false;
+    if (!this._logs.has(f)) return false;
+    if (this._logs.has(t)) return false; // 目标已存在, 拒绝覆盖防数据丢失 [复审 P1]
+    const events = this._logs.get(f);
+    this._logs.set(t, [...events]);
+    const lastSeq = events.length ? events[events.length - 1].seq : 0;
+    this._nextSeq.set(t, lastSeq);
+    this._flushedSeq.delete(t);
+    this._flush(t);
+    this.delete(f);
+    this._bump();
+    return true;
+  }
+  delete(key) {
+    const k = this._safe(key);
+    this._logs.delete(k); this._nextSeq.delete(k); this._flushedSeq.delete(k);
+    try {
+      if (k === "default") {
+        // 删除 default 所有分片 (旧单文件 + 各日 shard)
+        this._removeDefaultFiles();
+      } else {
+        fs.rmSync(this._file(k), { force: true });
+      }
+    } catch {}
+    this._bump();
+  }
+
+  // 清理过期会话: 删除超过 maxAgeDays 天未活跃的非 default 会话文件
+  // 返回删除的会话 key 列表。default 主会话始终保留 (防误删主对话历史)
+  // 分片说明: default 的各日分片在 _logs 中只对应一个 key="default", 不会被误当独立会话删除
+  pruneOld({ maxAgeDays = 30, keep = [] } = {}) {
+    const now = Date.now();
+    const cutoff = now - maxAgeDays * 86400000;
+    const keepSet = new Set([...keep, "default"].map((k) => this._safe(k)));
+    const removed = [];
+    for (const [key, events] of this._logs) {
+      if (keepSet.has(key)) continue;
+      const lastTs = events.length ? events[events.length - 1].ts : 0;
+      if (!lastTs || lastTs < cutoff) {
+        this.delete(key);
+        removed.push(key);
+      }
+    }
+    return removed;
+  }
+
+  // 增量落盘: 只追加 flushedSeq 之后的新事件 (P1#5, 消除大会话全量重写)
+  // default 按天落盘: 只把当天分片写到对应 default-YYYY-MM-DD.jsonl, 非当前天文件不再改写
+  _flush(key) {
+    const k = this._safe(key);
+    const evs = this._logs.get(k) || [];
+    if (!evs.length) return;
+    const flushed = this._flushedSeq.get(k) || 0;
+    const pending = evs.filter((e) => e.seq > flushed);
+    if (!pending.length) return;
+    try {
+      if (k === "default") this._flushDaily(pending);
+      else this._flushLegacy(k, pending, flushed);
+      this._flushedSeq.set(k, evs[evs.length - 1].seq);
+    } catch (e) {
+      // v1.0.9: 落盘失败不再静默 (磁盘满/权限丢失消息不可见), 至少留日志
+      try { console.warn(`[session] 会话 ${k} 落盘失败: ${e.message}`); } catch {}
+    }
+  }
+
+  // 非 default 会话: 原单文件增量写 (首次全量覆盖重建, 之后追加)
+  _flushLegacy(k, pending, flushed) {
+    const line = pending.map((e) => JSON.stringify(e)).join("\n") + "\n";
+    if (flushed === 0) {
+      fs.writeFileSync(this._file(k), line, "utf8");
+    } else {
+      fs.appendFileSync(this._file(k), line, "utf8");
+    }
+  }
+
+  // default 会话: 按事件 ts 归属的天分片增量写
+  //  - 按天分组: 每个文件只追加自己那天的行
+  //  - 当天文件已有则追加, 首次创建则写入新文件
+  _flushDaily(pending) {
+    const byDay = new Map();
+    for (const e of pending) {
+      const d = this._dayOf(e.ts);
+      let g = byDay.get(d);
+      if (!g) { g = []; byDay.set(d, g); }
+      g.push(e);
+    }
+    for (const [d, group] of byDay) {
+      const file = this._shardFile(d);
+      const line = group.map((e) => JSON.stringify(e)).join("\n") + "\n";
+      if (fs.existsSync(file)) fs.appendFileSync(file, line, "utf8");
+      else fs.writeFileSync(file, line, "utf8"); // 新的一天文件首次写入
+    }
+  }
+}

package/skills/ppx-memory/scripts/similarity.js

@@ -0,0 +1,43 @@
+// src/utils/similarity.js - 中文文本相似度的公共基元 (唯一实现, 2026-09-18 重构收敛)
+// 背景: "字符级 bigram + 交集" 的相似度思路在 fact-store / experience / eviction 三处各写一份,
+//       集合运算 (交集大小 / Jaccard / overlap) 完全重复。这里只收敛「集合级运算 + 字符 bigram 分词」,
+//       各模块保留自己的分词策略与阈值 (fact-store 用 scope 感知的 _bigramSet, 语义不同, 不强行合并)。
+// 零依赖, 纯函数。
+
+// 字符级 bigram: 去空白 + 按码点取相邻两字符 (对中文简繁/词序变化有容错)
+// 与 experience/_bigrams、eviction/_bigramSet 原实现一致 (Array.from 按码点切分, astral 字符不劈半)
+export function charBigrams(s) {
+  const chars = Array.from(String(s ?? "").replace(/\s+/g, ""));
+  const out = new Set();
+  for (let i = 0; i < chars.length - 1; i++) out.add(chars[i] + chars[i + 1]);
+  return out;
+}
+
+// 集合交集大小
+export function intersectSize(A, B) {
+  let inter = 0;
+  for (const x of A) if (B.has(x)) inter++;
+  return inter;
+}
+
+// Jaccard 系数: 交集 / 并集 (0~1)
+export function setJaccard(A, B) {
+  if (!A.size || !B.size) return 0;
+  const union = A.size + B.size - intersectSize(A, B);
+  return union ? intersectSize(A, B) / union : 0;
+}
+
+// overlap 系数: 交集 / 较短集合 (0~1) —— 对"共享核心词但词序/措辞大变"比 Jaccard 更敏感
+export function setOverlap(A, B) {
+  if (!A.size || !B.size) return 0;
+  return intersectSize(A, B) / Math.min(A.size, B.size);
+}
+
+// 文本级便捷封装 (字符 bigram)
+export function overlapCoefficient(a, b) {
+  return setOverlap(charBigrams(a), charBigrams(b));
+}
+
+export function jaccardCoefficient(a, b) {
+  return setJaccard(charBigrams(a), charBigrams(b));
+}

package/skills/ppx-memory/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/ppx-memory/scripts/wal.js

@@ -0,0 +1,38 @@
+// src/utils/wal.js - 追加式变更日志 (Write-Ahead Log) 轻量实现
+// 用途: 记忆数据的高频增量落盘。每次变更 append 一行事件到 <file>.wal (单行 JSON, 原子追加),
+//       达到阈值或显式 flush 时全量 compact 到主文件 + 清空 WAL。
+// 崩溃安全: 主文件 = 最后一次 flush 快照, WAL = 快照后的增量; 启动时重放 WAL 恢复。
+// 重放幂等: 事件按 id upsert/remove, 重复应用无害 (flush 后崩溃最多重放已落盘变更)。
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir } from "./store.js";
+
+export function walFileOf(file) {
+  return file + ".wal";
+}
+
+// 追加一条事件 (JSON 行)。appendFileSync 单行追加在正常写入下原子; 失败抛错由调用方降级 (内存态仍正确, 下次 flush 补齐)。
+export function appendWal(walFile, evt) {
+  ensureDir(path.dirname(walFile));
+  fs.appendFileSync(walFile, JSON.stringify(evt) + "\n", "utf8");
+}
+
+// 读 WAL: 逐行解析; 尾部半行 (崩溃中断写入) 静默丢弃; 返回事件数组
+export function readWal(walFile) {
+  if (!fs.existsSync(walFile)) return [];
+  let raw;
+  try { raw = fs.readFileSync(walFile, "utf8"); } catch { return []; }
+  if (!raw) return [];
+  const events = [];
+  for (const line of raw.split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    try { events.push(JSON.parse(t)); } catch { break; } // 半行丢弃, 后面的已不可信
+  }
+  return events;
+}
+
+// 清空 WAL (compact 成功后调用; 与 append 同一锁内执行, 防丢事件)
+export function truncateWal(walFile) {
+  try { fs.rmSync(walFile, { force: true }); } catch {}
+}

package/skills/ppx-selfheal/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: ppx-selfheal
+description: 皮皮虾自愈引擎的使用与判读：启动体检、损坏数据修复、崩溃恢复、残留清理。出现数据异常、启动失败、疑似崩溃退出时使用。
+---
+
+# 皮皮虾自愈引擎 (ppx-selfheal)
+
+## 流程
+
+1. **跑体检**：`selfheal_run` 触发启动检查（补建缺失目录、修复损坏 JSON、清理残留）。
+2. **读结果**：关注 `integrity.json` 的 `clean` 字段 —— 上次 `clean === false` 说明上回是崩溃退出，本轮会做残留清理。
+3. **损坏隔离而非删除**：损坏的 `facts.json` 会被改名 `.corrupt-<ts>` 保留，修复后确认无用再手工清理。
+4. **阈值门禁**：发布前用 `npm run selfheal` 跑基准，`PPX_MIN_SELFHEAL` 可设通过阈值（默认 7/7）。
+5. **判读自诊断**：`self_diagnose` 聚合审计链与失败案例库，输出"症状 → 根因 → 处方"。
+
+## 反合理化
+
+- "重启一下就好了"——先看 integrity.json 弄清是崩溃还是正常退出，否则同一故障会反复。
+- "损坏文件直接删"——自愈的语义是隔离保留，绕过它等于放弃取证能力。
+- "自愈通过就万事大吉"——自愈保证的是数据可用，不代表业务逻辑正确。
+
+## 验证
+
+必须提供：① 自愈基准分数（`npm run selfheal`）；② 真实数据目录（非 `root/data`）已被体检的证据；③ 有损坏时的隔离文件名。