ppxans-harness 2.4.0

package/src/utils/store.js

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

package/src/utils/text.js

@@ -0,0 +1,16 @@
+// src/utils/text.js - 零依赖文本工具 (token 估算等, 供 agent/llm 等共用)
+// 单一实现, 避免 agent 与 llm 各自维护一份 token 估算导致口径漂移。
+
+// 估算 token 数: 中文字符约 1 字 ≈ 0.6 token, 1 token ≈ 4 字符; 统一按字符数 /1.6 估。
+export function estimateTokens(s) {
+  return Math.ceil(String(s || "").length / 1.6);
+}
+
+// 按 token 预算截断字符串: 保留头部信息 (供 persona/角色设定等需保留 key 信息的场景),
+// 超预算时在尾部标注截断来源与总量。与 estimateTokens 同口径 (字符/1.6)。
+export function truncateByTokens(s, budget) {
+  const str = String(s || "");
+  const maxLen = Math.floor(budget * 1.6);
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen) + `\n...[persona 已按预算截断, 共 ${str.length} 字符]...`;
+}

package/src/utils/trace.js

@@ -0,0 +1,153 @@
+// src/utils/trace.js - 结构化可观测轨迹 (Harness 第四层)
+// 记录每次工具调用的完整轨迹: 工具/参数/结果摘要/耗时/成败
+// 写 JSONL 到 data/logs/traces/YYYY-MM-DD.jsonl, 供事后复盘"哪一步坏了"
+// v1.0.8: args/result 落盘前 PII 脱敏 (凭证不写日志); read(day) 支持按指定日期读取
+// P0 (2026-09-15): 事件源不变量 (model-visible = logged) ——
+//   turn/step 边界事件落同一 JSONL + verifyReplay() 重放校验 (配对完整性/顺序性)。
+//   对齐 dsh "会话日志是模型可见内容的唯一事实源" 思想, 用皮皮虾自有结构增量实现。
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir, logicalDay } from "./store.js";
+import { scrubPII } from "./pii.js";
+
+const MAX_TRACE_BODY = 2000;   // 单条结果保留上限, 防爆文件
+
+// 事件类型常量 (turn/step 边界)
+export const EVT = {
+  TURN_START: "turn/start",
+  TURN_END: "turn/end",
+  STEP_START: "step/start",
+  STEP_END: "step/end",
+  TOOL: "tool/call",
+};
+
+export class Traces {
+  constructor(dataDir) {
+    this.dir = path.join(dataDir, "logs", "traces");
+    ensureDir(this.dir);
+    this.sessionId = "s_" + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+    this.count = 0;
+  }
+
+  _file(day = logicalDay()) { return path.join(this.dir, `${day}.jsonl`); }
+
+  // 记录一次工具调用轨迹
+  record({ tool, args, result, ok, durationMs, error }) {
+    const entry = this._entry({ evt: EVT.TOOL, tool, args, result, ok, durationMs, error });
+    fs.appendFileSync(this._file(), JSON.stringify(entry) + "\n", "utf8");
+    return entry;
+  }
+
+  // ---- P0: turn/step 边界事件 (事件源事实) ----
+  recordTurnStart({ sessionId, reason } = {}) {
+    return this._append({ evt: EVT.TURN_START, tsIso: new Date().toISOString(), reason: reason || "user", sessionId: sessionId || this.sessionId });
+  }
+  recordTurnEnd({ ok = true, rounds = 0, reason } = {}) {
+    return this._append({ evt: EVT.TURN_END, ok: !!ok, rounds, reason: reason || null });
+  }
+  recordStepStart({ round = 0, context } = {}) {
+    // context 快照 = 该 step 模型看到的上下文投影摘要 (验证 model-visible = logged)
+    const safe = context ? scrubPII(JSON.stringify(context)).cleaned : null;
+    return this._append({ evt: EVT.STEP_START, round, context: safe ? this._truncate(safe) : null });
+  }
+  recordStepEnd({ round = 0, ok = true, tool = null, error } = {}) {
+    return this._append({ evt: EVT.STEP_END, round, ok: !!ok, tool: tool || null, error: error || null });
+  }
+
+  _append(extra) {
+    this.count += 1;
+    const entry = { ...this._base(), ...extra };
+    fs.appendFileSync(this._file(), JSON.stringify(entry) + "\n", "utf8");
+    return entry;
+  }
+
+  _base() {
+    return { ts: new Date().toISOString(), sessionId: this.sessionId, seq: this.count };
+  }
+
+  _entry({ evt, tool, args, result, ok, durationMs, error }) {
+    const safeArgs = scrubPII(JSON.stringify(args ?? {})).cleaned;
+    const safeResult = scrubPII(String(result ?? "")).cleaned;
+    return {
+      ...this._base(),
+      evt: evt || EVT.TOOL,
+      tool,
+      args: this._truncate(safeArgs),
+      result: this._truncate(safeResult),
+      ok: !!ok,
+      durationMs: Math.round(durationMs || 0),
+      error: error || null,
+    };
+  }
+
+  _truncate(s) {
+    const str = String(s ?? "");
+    return str.length > MAX_TRACE_BODY ? str.slice(0, MAX_TRACE_BODY) + "…" : str;
+  }
+
+  // ---- P0: 事件源不变量断言 (model-visible = logged) ----
+  // 重放校验: 1) 每行可解析  2) turn/step 配对完整 (start 必有 end, 嵌套合法)  3) step round 递增无重复
+  // 返回 { ok, total, errors: [] }。任何不变量破坏 → ok=false + 具体错误行, 供自愈/测试定位。
+  verifyReplay(day = logicalDay()) {
+    const lines = this.readRaw(day);
+    const errors = [];
+    const turnStack = [];
+    const stepRounds = new Set();
+    let total = 0;
+    for (let i = 0; i < lines.length; i++) {
+      let e;
+      try { e = JSON.parse(lines[i]); } catch (err) { errors.push({ line: i + 1, kind: "parse", detail: err.message }); continue; }
+      total++;
+      if (!e || !e.evt) { errors.push({ line: i + 1, kind: "no-evt" }); continue; }
+      if (e.evt === EVT.TURN_START) turnStack.push(i);
+      else if (e.evt === EVT.TURN_END) {
+        if (!turnStack.length) errors.push({ line: i + 1, kind: "turn-end-orphan" });
+        else turnStack.pop();
+      } else if (e.evt === EVT.STEP_START) {
+        const r = Number(e.round);
+        if (stepRounds.has(r)) errors.push({ line: i + 1, kind: "step-round-duplicate", detail: `round=${r}` });
+        stepRounds.add(r);
+      }
+    }
+    if (turnStack.length) errors.push({ kind: "turn-unclosed", detail: `剩余 ${turnStack.length} 个未闭合 turn` });
+    return { ok: errors.length === 0, total, errors };
+  }
+
+  // 读原始行 (verifyReplay 用, 不跳过坏行)
+  readRaw(day = logicalDay()) {
+    const file = this._file(day);
+    if (!fs.existsSync(file)) return [];
+    return fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+  }
+
+  // 读取某天轨迹 (最近 N 条); day 缺省 = 今天
+  read(day, limit = 100) {
+    const file = this._file(day);
+    if (!fs.existsSync(file)) return [];
+    return fs.readFileSync(file, "utf8").split("\n").filter(Boolean).slice(-limit)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  }
+
+  // 统计: 失败率/平均耗时/慢工具
+  stats(day) {
+    const all = this.read(day, 10000);
+    if (!all.length) return { count: 0, failed: 0, failRate: "0%", slowTools: [] };
+    const failed = all.filter((t) => !t.ok);
+    const byTool = {};
+    for (const t of all) {
+      (byTool[t.tool] = byTool[t.tool] || { calls: 0, fails: 0, totalMs: 0 });
+      byTool[t.tool].calls++;
+      if (!t.ok) byTool[t.tool].fails++;
+      byTool[t.tool].totalMs += t.durationMs;
+    }
+    const slow = Object.entries(byTool)
+      .map(([tool, v]) => ({ tool, ...v, avgMs: Math.round(v.totalMs / v.calls) }))
+      .sort((a, b) => b.avgMs - a.avgMs).slice(0, 5);
+    return {
+      count: all.length,
+      failed: failed.length,
+      failRate: all.length ? (failed.length / all.length * 100).toFixed(1) + "%" : "0%",
+      slowTools: slow,
+    };
+  }
+}

package/src/utils/winutf8.js

@@ -0,0 +1,15 @@
+// src/utils/winutf8.js - Windows 控制台 UTF-8 引导：强制 chcp 65001 + stdout/stderr 用 utf8
+// 根治 PowerShell/GBK 控制台把 Node UTF-8 输出解成乱码（鐨尰铏?/鑳藉姏... 那种）
+import { execSync } from "node:child_process";
+
+export function ensureUTF8Console() {
+  if (process.platform !== "win32") return;
+  try {
+    // 改当前控制台活动代码页为 UTF-8（仅当是真实终端时；stdout 非 TTY 时跳过，避免写日志管道报错）
+    if (process.stdout?.isTTY) {
+      execSync("chcp 65001", { stdio: "ignore", windowsHide: true });
+    }
+  } catch { /* 非交互/无控制台，忽略 */ }
+  try { process.stdout.setDefaultEncoding?.("utf8"); } catch {}
+  try { process.stderr.setDefaultEncoding?.("utf8"); } catch {}
+}