ppxans-harness 2.6.0 → 3.2.0

package/src/session/rollout.js

@@ -0,0 +1,54 @@
+// src/session/rollout.js - JSONL rollout 持久化 (对齐 codex rollout + fork/rewind)
+// item 约定: { seq, type, payload }
+//  - append: 追加一行 JSON, 目录不存在先建
+//  - fork:   从源会话复制 seq<=uptoSeq 的 items 到新会话文件
+//  - rewind: 删除 seq>uptoSeq 的行, 先写 .tmp 再 rename (Windows 安全: 避免读半截)
+import fs from "node:fs";
+import path from "node:path";
+
+export const Rollout = {
+  // 会话 rollout 文件路径 (sessionId 做安全化, 防路径穿越)
+  _file(dir, sessionId) {
+    const safe = String(sessionId).replace(/[^\w.-]/g, "_");
+    return path.join(dir, `${safe}.rollout.jsonl`);
+  },
+
+  // 追加一行 JSON ({ts, ...item})
+  append(dir, sessionId, item) {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const line = JSON.stringify({ ts: Date.now(), ...item }) + "\n";
+    fs.appendFileSync(this._file(dir, sessionId), line, "utf8");
+  },
+
+  // 读取全部 items (按文件顺序)
+  load(dir, sessionId) {
+    const file = this._file(dir, sessionId);
+    const out = [];
+    try {
+      for (const l of fs.readFileSync(file, "utf8").split("\n").filter(Boolean)) {
+        try { out.push(JSON.parse(l)); } catch { /* 跳过损坏行 */ }
+      }
+    } catch { /* 文件不存在视为空 */ }
+    return out;
+  },
+
+  // 从 fromSessionId 复制 seq<=uptoSeq 的 items 到 newSessionId 文件 (覆盖写, 目标为新会话)
+  fork(dir, fromSessionId, newSessionId, uptoSeq) {
+    const items = this.load(dir, fromSessionId).filter((it) => it.seq <= uptoSeq);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const content = items.map((it) => JSON.stringify(it)).join("\n") + (items.length ? "\n" : "");
+    fs.writeFileSync(this._file(dir, newSessionId), content, "utf8");
+    return items;
+  },
+
+  // 回退: 删除 seq>uptoSeq 的行 (先写 .tmp 再 rename)
+  rewind(dir, sessionId, uptoSeq) {
+    const items = this.load(dir, sessionId).filter((it) => it.seq <= uptoSeq);
+    const file = this._file(dir, sessionId);
+    const tmp = file + ".tmp";
+    const content = items.map((it) => JSON.stringify(it)).join("\n") + (items.length ? "\n" : "");
+    fs.writeFileSync(tmp, content, "utf8");
+    fs.renameSync(tmp, file);
+    return items;
+  },
+};

package/src/session/turn.js

@@ -0,0 +1,137 @@
+// src/session/turn.js - Session→Task→Turn 状态机 (对齐 codex taskTurn/turn 模型)
+// Session 持有有序 tasks; Task 持有有序 turns + queuedUserInputs;
+// turn 完成后若仍有排队输入则自动续开新 turn (对齐 codex appendTurn/completeTurn 语义)。
+import { randomUUID } from "node:crypto";
+
+// 新建一个 turn 对象 (status: open/closed/aborted)
+function createTurn(task, seq) {
+  return {
+    id: `turn_${randomUUID()}`,
+    seq,
+    status: "open",
+    startedAt: Date.now(),
+    closedAt: null,
+    items: [], // ResponseItem 数组
+  };
+}
+
+// 新建一个 task 对象, 方法通过 this 绑定 (便于反序列化复用同一份方法)
+function newTask(session, id) {
+  return {
+    id: id || `task_${randomUUID()}`,
+    sessionId: session.id,
+    turns: [],
+    status: "running", // running | complete | aborted
+    queuedUserInputs: [],
+    currentTurn: null,
+
+    // 追加一个用户输入:
+    //  - 当前 turn 进行中 -> 先排队 (用户追打)
+    //  - 无进行中 turn  -> 开新 turn 承接
+    appendTurn(userInput) {
+      if (this.currentTurn && this.currentTurn.status === "open") {
+        this.queuedUserInputs.push(userInput);
+        return this.currentTurn;
+      }
+      const turn = createTurn(this, this.turns.length + 1);
+      this.turns.push(turn);
+      this.currentTurn = turn;
+      turn.items.push(userInput);
+      session.turnCount += 1;
+      return turn;
+    },
+
+    // 结束当前 turn:
+    //  - 当前 turn 标 closed
+    //  - 若仍有排队输入, 自动开新 turn 承接第一个 (其余留待下次 completeTurn)
+    completeTurn() {
+      if (this.currentTurn) {
+        this.currentTurn.status = "closed";
+        this.currentTurn.closedAt = Date.now();
+      }
+      if (this.queuedUserInputs.length > 0) {
+        const next = this.queuedUserInputs.shift();
+        this.appendTurn(next);
+      }
+      return this.currentTurn;
+    },
+
+    // 中止: 当前 turn 标 aborted, task 标 aborted
+    abort() {
+      if (this.currentTurn) {
+        this.currentTurn.status = "aborted";
+        this.currentTurn.closedAt = Date.now();
+      }
+      this.status = "aborted";
+      session.status = "aborted";
+      return this;
+    },
+  };
+}
+
+// 创建会话
+export function createSession({ id } = {}) {
+  const sessionId = id || `sess_${randomUUID()}`;
+  const session = {
+    id: sessionId,
+    tasks: [],
+    turnCount: 0,
+    status: "active", // active | aborted
+    createTask(input = {}) {
+      const task = newTask(this, input.id);
+      this.tasks.push(task);
+      return task;
+    },
+    currentTask() {
+      return this.tasks.length ? this.tasks[this.tasks.length - 1] : null;
+    },
+  };
+  return session;
+}
+
+// 序列化会话为 JSON 字符串 (仅数据, 方法在反序列化时重建)
+export function serializeSession(session) {
+  return JSON.stringify({
+    id: session.id,
+    turnCount: session.turnCount,
+    status: session.status,
+    tasks: session.tasks.map((t) => ({
+      id: t.id,
+      sessionId: t.sessionId,
+      status: t.status,
+      queuedUserInputs: t.queuedUserInputs,
+      turns: t.turns.map((tn) => ({
+        id: tn.id,
+        seq: tn.seq,
+        status: tn.status,
+        startedAt: tn.startedAt,
+        closedAt: tn.closedAt,
+        items: tn.items,
+      })),
+    })),
+  });
+}
+
+// 从 JSON 反序列化 (重建方法 + 当前 turn 指针)
+export function deserializeSession(json) {
+  const data = typeof json === "string" ? JSON.parse(json) : json;
+  const session = createSession({ id: data.id });
+  session.turnCount = data.turnCount ?? 0;
+  session.status = data.status ?? "active";
+  session.tasks = (data.tasks || []).map((t) => {
+    const task = newTask(session, t.id);
+    task.status = t.status ?? "running";
+    task.queuedUserInputs = t.queuedUserInputs || [];
+    task.turns = (t.turns || []).map((tn) => ({
+      id: tn.id,
+      seq: tn.seq,
+      status: tn.status,
+      startedAt: tn.startedAt,
+      closedAt: tn.closedAt ?? null,
+      items: tn.items || [],
+    }));
+    task.currentTurn = task.turns.length ? task.turns[task.turns.length - 1] : null;
+    return task;
+  });
+  return session;
+}

package/src/skills/lint.js

@@ -0,0 +1,72 @@
+// src/skills/lint.js - Skill 质量门槛 (零 LLM, 可接 CI)
+// 依据《Skill 蓝皮书 2026》: 元数据与描述质量是 skill 分发的第一瓶颈。
+//   error = 阻断 (结构/元数据缺失, 不可分发)
+//   warning = 建议 (描述过泛/缺反合理化段, 影响模型能否正确选中)
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter, stripFrontmatter, parseSections } from "./loader.js";
+
+export const MIN_DESC_LEN = 8;
+export const MIN_BODY_LEN = 40;
+const NAME_RE = /^[a-zA-Z0-9-]+$/;
+
+function lintOne(dir, id) {
+  const errors = [];
+  const warnings = [];
+  const file = path.join(dir, id, "SKILL.md");
+  if (!fs.existsSync(file)) {
+    errors.push({ id: "no-skill-md", msg: "缺少 SKILL.md" });
+    return { name: id, ok: false, errors, warnings };
+  }
+  let raw = "";
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch (e) {
+    errors.push({ id: "unreadable", msg: "SKILL.md 读取失败: " + String(e?.message || e) });
+    return { name: id, ok: false, errors, warnings };
+  }
+  const fm = parseFrontmatter(raw);
+  const body = stripFrontmatter(raw).trim();
+
+  if (!fm.name) errors.push({ id: "missing-name", msg: "frontmatter 缺 name" });
+  else if (fm.name !== id) errors.push({ id: "name-mismatch", msg: `name (${fm.name}) 与目录名 (${id}) 不一致` });
+  if (fm.name && !NAME_RE.test(fm.name)) errors.push({ id: "bad-name", msg: "name 仅允许字母/数字/横线" });
+
+  if (!fm.description) errors.push({ id: "missing-description", msg: "frontmatter 缺 description (模型选中的唯一依据)" });
+  else if (String(fm.description).trim().length < MIN_DESC_LEN) {
+    warnings.push({ id: "short-description", msg: `description 过短 (< ${MIN_DESC_LEN} 字), 模型难以判断适用场景` });
+  }
+
+  if (!body) errors.push({ id: "empty-body", msg: "正文为空" });
+  else if (body.length < MIN_BODY_LEN) {
+    warnings.push({ id: "short-body", msg: `正文过短 (< ${MIN_BODY_LEN} 字), 建议补流程/检查点` });
+  }
+
+  const secs = parseSections(body);
+  if (!secs["流程"]) errors.push({ id: "no-process", msg: '缺 "## 流程" 段' });
+  if (!secs["验证"]) errors.push({ id: "no-verify", msg: '缺 "## 验证" 段 (完成后必须提供的证据)' });
+  if (!secs["反合理化"]) warnings.push({ id: "no-antirationale", msg: '缺 "## 反合理化" 段 (常见偷懒借口 + 反驳)' });
+
+  return { name: id, ok: errors.length === 0, errors, warnings };
+}
+
+export function lintSkillDir(dir) {
+  if (!fs.existsSync(dir)) return { results: [], pass: 0, warn: 0, fail: 0, error: `技能目录不存在: ${dir}` };
+  let ids = [];
+  try {
+    ids = fs
+      .readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .filter((n) => !n.startsWith("."))
+      .sort();
+  } catch (e) {
+    return { results: [], pass: 0, warn: 0, fail: 0, error: `技能目录不可读: ${String(e?.message || e)}` };
+  }
+
+  const results = ids.map((id) => lintOne(dir, id));
+  const pass = results.filter((r) => r.ok && !r.warnings.length).length;
+  const warn = results.filter((r) => r.ok && r.warnings.length).length;
+  const fail = results.filter((r) => !r.ok).length;
+  return { results, pass, warn, fail, error: null };
+}

package/src/skills/loader.js

@@ -1,150 +1,231 @@
-// src/skills/loader.js - Skill Catalog + Loader
-// 参考 deepseek-harness 的 skill package(catalog + loader): 可枚举、可发现、可加载的技能注册表
-// 扫描 <skillsDir>/*/SKILL.md, 解析 frontmatter(name/description), 提供 list/get/loadAll
-import fs from "node:fs";
-import path from "node:path";
-
-// 解析 SKILL.md 顶部的 --- frontmatter ---
-// 支持简单 `key: value` 和 YAML 折叠块（`>` / `|`），保证多行 description 可被解析。
-export function parseFrontmatter(md) {
-  const m = md.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!m) return {};
-  const meta = {};
-  const lines = m[1].split(/\r?\n/);
-  let key = null;
-  let block = null;
-  let blockLines = [];
-  const flush = () => {
-    if (key && block) {
-      meta[key] = block === ">"
-        ? blockLines.join(" ").replace(/\s+/g, " ").trim()
-        : blockLines.join("\n").trim();
-    }
-    key = null;
-    block = null;
-    blockLines = [];
-  };
-  for (const line of lines) {
-    const mm = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
-    if (mm) {
-      flush();
-      key = mm[1];
-      const val = mm[2].trim();
-      if (val === ">" || val === "|") {
-        block = val;
-      } else {
-        meta[key] = val;
-        key = null;
-      }
-    } else if (block && key) {
-      blockLines.push(line.trim());
-    }
-  }
-  flush();
-  return meta;
-}
-
-// 解析 SKILL.md 正文章节: "## 标题" -> 内容
-// 供按需加载 (渐进式披露): agent 可只读「反合理化」「验证」等特定段, 不用整篇读入
-export function parseSections(md) {
-  const sections = {};
-  const lines = String(md || "").split(/\r?\n/);
-  let cur = null;
-  for (const line of lines) {
-    const m = line.match(/^##\s+(.+)$/);
-    if (m) { cur = m[1].trim(); sections[cur] = ""; continue; }
-    if (cur) sections[cur] += line + "\n";
-  }
-  for (const k of Object.keys(sections)) sections[k] = sections[k].trim();
-  return sections;
-}
-
-export class SkillLoader {
-  constructor(skillsDir) {
-    this.dir = skillsDir;
-    // 技能使用追踪 (source: Hermes "skill self-improves during use")
-    this.usageFile = path.join(skillsDir, ".usage.json");
-    this._usage = this._readUsage();
-  }
-
-  _scan() {
-    if (!fs.existsSync(this.dir)) return {};
-    const out = {};
-    for (const entry of fs.readdirSync(this.dir, { withFileTypes: true })) {
-      if (!entry.isDirectory()) continue;
-      const skillMd = path.join(this.dir, entry.name, "SKILL.md");
-      if (!fs.existsSync(skillMd)) continue;
-      const raw = fs.readFileSync(skillMd, "utf8");
-      const meta = parseFrontmatter(raw);
-      out[entry.name] = {
-        id: entry.name,
-        name: meta.name || entry.name,
-        description: meta.description || "",
-        dir: path.join(this.dir, entry.name),
-        path: skillMd,
-      };
-    }
-    return out;
-  }
-
-  // 可枚举: 全部技能
-  list() {
-    return Object.values(this._scan());
-  }
-
-  // 可发现: 按 id 查
-  get(id) {
-    return this._scan()[id] || null;
-  }
-
-  has(id) {
-    return !!this._scan()[id];
-  }
-
-  // 读取某个技能的完整 SKILL.md 内容
-  read(id) {
-    const s = this.get(id);
-    if (!s) return null;
-    return fs.readFileSync(s.path, "utf8");
-  }
-
-  // 按需读取某个技能的指定章节 (渐进式披露: 只读「反合理化」「验证」等段, 省 token)
-  readSection(id, section) {
-    const raw = this.read(id);
-    if (raw === null) return null;
-    const sections = parseSections(raw);
-    return sections[section] ?? null;
-  }
-
-  _readUsage() {
-    try { if (fs.existsSync(this.usageFile)) { const d = JSON.parse(fs.readFileSync(this.usageFile, "utf8")); if (d && typeof d === "object") return d; } } catch {}
-    return {};
-  }
-
-  _saveUsage() {
-    try { fs.writeFileSync(this.usageFile, JSON.stringify(this._usage, null, 2), "utf8"); } catch {}
-  }
-
-  // 记录一次技能使用 (load_skill 时调用)
-  trackUse(id) {
-    this._usage = this._readUsage();
-    const u = this._usage[id] || { uses: 0, lastUsed: null };
-    u.uses = (u.uses || 0) + 1;
-    u.lastUsed = new Date().toISOString();
-    this._usage[id] = u;
-    this._saveUsage();
-    return u;
-  }
-
-  // 某技能使用统计
-  useOf(id) { const u = this._readUsage()[id]; return u ? { uses: u.uses || 0, lastUsed: u.lastUsed || null } : { uses: 0, lastUsed: null }; }
-
-  // 全部技能使用统计
-  usageAll() { return this._readUsage(); }
-
-  // 重置某技能使用计数 (用中自进化升级完成后调用, 防连跑)
-  resetUse(id) {
-    this._usage = this._readUsage();
-    if (this._usage[id]) { this._usage[id].uses = 0; this._usage[id].lastUpgraded = new Date().toISOString(); this._saveUsage(); }
-  }
-}
+// src/skills/loader.js - 方法技能加载器 (SKILL.md 目录式)
+// 来源: Superpowers / addyosmani-agent-skills 模式 —— 技能=目录 + SKILL.md(frontmatter + ## 章节)
+// 设计要点:
+//  1) 签名缓存 (mtime+size): 内容修改/目录增删后 list()/get() 必须反映变化 (蓝皮书: 发现是生态瓶颈)
+//  2) readSection 按需读章节: 只把命中的章节喂给 LLM, 省 token
+//  3) 使用追踪 trackUse/useOf/usageAll: 用中自进化 (Hermes) 的前提是知道谁在用、谁闲置
+import fs from "node:fs";
+import path from "node:path";
+
+// ---- frontmatter / 章节解析 (零依赖) ----
+
+// 解析 `---\nkey: value\n---` 头。无头返回 {}。
+export function parseFrontmatter(md) {
+  const text = String(md || "").replace(/^\uFEFF/, "");
+  const m = text.match(/^\s*---\s*\r?\n([\s\S]*?)\r?\n\s*---\s*(?:\r?\n|$)/);
+  if (!m) return {};
+  const out = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const i = line.indexOf(":");
+    if (i <= 0) continue;
+    const k = line.slice(0, i).trim();
+    let v = line.slice(i + 1).trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+      v = v.slice(1, -1);
+    }
+    if (k) out[k] = v;
+  }
+  return out;
+}
+
+// 去掉 frontmatter 后的正文
+export function stripFrontmatter(md) {
+  const text = String(md || "").replace(/^\uFEFF/, "");
+  const m = text.match(/^\s*---\s*\r?\n[\s\S]*?\r?\n\s*---\s*(?:\r?\n|$)/);
+  return m ? text.slice(m[0].length) : text;
+}
+
+// 解析二级标题章节: `## 流程` → { "流程": "正文(不含标题行)" }
+export function parseSections(md) {
+  const body = stripFrontmatter(md);
+  const out = {};
+  const lines = body.split(/\r?\n/);
+  let cur = null;
+  let buf = [];
+  const flush = () => {
+    if (cur === null) return;
+    out[cur] = buf.join("\n").trim();
+  };
+  for (const line of lines) {
+    const h = line.match(/^##\s+(.+?)\s*$/);
+    const h1 = line.match(/^#\s+(.+?)\s*$/);
+    if (h) {
+      flush();
+      cur = h[1].trim();
+      buf = [];
+    } else if (h1) {
+      // 一级标题不作为章节, 但结束当前章节
+      flush();
+      cur = null;
+      buf = [];
+    } else if (cur !== null) {
+      buf.push(line);
+    }
+  }
+  flush();
+  return out;
+}
+
+const USAGE_FILE = ".usage.json";
+
+function readJsonSafe(file, fallback) {
+  try {
+    if (!fs.existsSync(file)) return fallback;
+    const raw = fs.readFileSync(file, "utf8");
+    if (!raw.trim()) return fallback;
+    const v = JSON.parse(raw);
+    return v && typeof v === "object" ? v : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+export class SkillLoader {
+  constructor(dir) {
+    this.dir = dir;
+    this._cache = new Map(); // id -> { sig, meta }
+  }
+
+  // 单技能签名: SKILL.md 的 mtime+size (变更即失效缓存)
+  _sigOf(file) {
+    try {
+      const st = fs.statSync(file);
+      return `${st.mtimeMs}:${st.size}`;
+    } catch {
+      return null;
+    }
+  }
+
+  _skillDirs() {
+    try {
+      return fs
+        .readdirSync(this.dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .filter((n) => !n.startsWith(".") && n !== "node_modules");
+    } catch {
+      return [];
+    }
+  }
+
+  _load(id) {
+    const file = path.join(this.dir, id, "SKILL.md");
+    const sig = this._sigOf(file);
+    if (sig === null) {
+      this._cache.delete(id);
+      return null;
+    }
+    const hit = this._cache.get(id);
+    if (hit && hit.sig === sig) return hit.meta;
+    let raw = "";
+    try {
+      raw = fs.readFileSync(file, "utf8");
+    } catch {
+      this._cache.delete(id);
+      return null;
+    }
+    const fm = parseFrontmatter(raw);
+    const meta = {
+      id,
+      name: String(fm.name || id),
+      description: String(fm.description || ""),
+      frontmatter: fm,
+      body: stripFrontmatter(raw),
+      file,
+    };
+    this._cache.set(id, { sig, meta });
+    return meta;
+  }
+
+  // 列出全部技能 (id/name/description), 目录增删与内容修改都会反映
+  list() {
+    const ids = this._skillDirs().sort();
+    const keep = new Set(ids);
+    for (const k of [...this._cache.keys()]) if (!keep.has(k)) this._cache.delete(k);
+    const out = [];
+    for (const id of ids) {
+      const m = this._load(id);
+      if (m) out.push({ id: m.id, name: m.name, description: m.description });
+    }
+    return out;
+  }
+
+  has(id) {
+    return this._load(String(id || "")) !== null;
+  }
+
+  get(id) {
+    const m = this._load(String(id || ""));
+    if (!m) return null;
+    return { id: m.id, name: m.name, description: m.description, frontmatter: m.frontmatter };
+  }
+
+  // SKILL.md 正文 (去 frontmatter)。未知技能返回 null。
+  read(id) {
+    const m = this._load(String(id || ""));
+    return m ? m.body : null;
+  }
+
+  // 按需读章节。章节不存在或技能不存在返回 null。
+  readSection(id, section) {
+    const body = this.read(id);
+    if (body === null) return null;
+    const s = parseSections(body);
+    const v = s[String(section || "")];
+    return v === undefined ? null : v;
+  }
+
+  // ---- 使用追踪 (落盘, 跨实例可读回) ----
+  _usageFile() {
+    return path.join(this.dir, USAGE_FILE);
+  }
+
+  _readUsage() {
+    return readJsonSafe(this._usageFile(), {});
+  }
+
+  _writeUsage(u) {
+    try {
+      fs.mkdirSync(this.dir, { recursive: true });
+      fs.writeFileSync(this._usageFile(), JSON.stringify(u, null, 2), "utf8");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  trackUse(id) {
+    const key = String(id || "");
+    if (!key) return { uses: 0, lastUsed: null };
+    const u = this._readUsage();
+    const cur = u[key] && typeof u[key] === "object" ? u[key] : { uses: 0, lastUsed: null };
+    const next = { uses: Number(cur.uses || 0) + 1, lastUsed: new Date().toISOString() };
+    u[key] = next;
+    this._writeUsage(u);
+    return next;
+  }
+
+  useOf(id) {
+    const u = this._readUsage();
+    const cur = u[String(id || "")];
+    if (!cur || typeof cur !== "object") return { uses: 0, lastUsed: null };
+    return { uses: Number(cur.uses || 0), lastUsed: cur.lastUsed || null };
+  }
+
+  usageAll() {
+    const u = this._readUsage();
+    const out = {};
+    for (const [k, v] of Object.entries(u)) {
+      if (!v || typeof v !== "object") continue;
+      out[k] = { uses: Number(v.uses || 0), lastUsed: v.lastUsed || null };
+    }
+    return out;
+  }
+
+  resetUse(id) {
+    const key = String(id || "");
+    const u = this._readUsage();
+    delete u[key];
+    return this._writeUsage(u);
+  }
+}