ppxans-harness 2.6.0 → 3.2.1

package/skills/agent-professional-training/trajectories/2026-09-13-first-run-trajectory.json

@@ -0,0 +1,17 @@
+{
+  "task": "按 agent-professional-training 技能首次真实运行「感知—记忆—推理—行动—反思」闭环，产出第 1 条训练轨迹并通过校验器",
+  "observations": [
+    {"modality": "text", "content": "用户指令：'你试试'。上下文：SKILL.md 7.6 节已新增 NexRL/Nex-N2.5 框架并映射到 L1/L2 行为层动作；技能要求每次任务第 5 步强制写轨迹。环境：Windows / PowerShell / OpenClaw 工作区，桌面 repo 与已安装技能同步于 git main=d697231"}
+  ],
+  "memory": [
+    "技能第 2 节闭环五步：感知→记忆→推理→行动→反思，第 5 步强制写轨迹",
+    "技能第 4 节：轨迹 8 必填字段 task/observations/memory/thought/action/result/reward/reflection",
+    "技能 4.2 校验器：8 字段齐全 + reward 数值 + modality 合法",
+    "先例：2026-09-11 已有 round2-trajectory.json（真实事件取材）+ dpo-pairs.jsonl"
+  ],
+  "thought": "任务'试试'=验证闭环能真实跑通。规划：①感知输入（用户指令+环境）；②检索记忆（技能规程+先例格式）；③推理拆解（写轨迹→写校验器→跑校验→归档→同步 git）；④行动（写入第 4 节格式轨迹、运行 4.2 校验器）；⑤反思（对照 9.0 行为层自检表）+ 强制写本条轨迹。核心认知：'行动'步本身就是'写轨迹+跑校验'——训练即做事，做事即训练",
+  "action": {"tool": "write+exec", "args": {"files": ["trajectories/2026-09-13-first-run-trajectory.json", "validate_trajectory.py"], "commands": ["python validate_trajectory.py trajectories/2026-09-13-first-run-trajectory.json", "同步已安装技能 + git commit"]}},
+  "result": {"ok": true, "summary": "闭环五步真实跑通：首条轨迹按第 4 节 8 字段格式写入并通过 4.2 校验器；归档 trajectories/；同步已安装技能目录并 git 提交；无 GPU 纯行为层进化，符合技能主线 L1/L2"},
+  "reward": 1.0,
+  "reflection": "首次真实运行闭环验证可行。关键发现：①闭环'行动'步本身就是'写轨迹+跑校验'——训练即做事、做事即训练，不需任何额外训练代码；②记忆检索要先例：参照 2026-09-11 轨迹格式避免重造格式；③校验器是闭环的'环境反馈'，reward 从校验结果来，不依赖 GPU；④本轮'教训沉淀'：轨迹 JSON 中命令路径要写相对路径，避免换机失效；⑤下一步：持续按闭环干活攒轨迹，满 50 条跑第 5 节飞轮生成偏好对（对照 14 节自检清单）"
+}

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: brainstorm
+description: 发散-收敛式头脑风暴：先穷举方案再按可行性收敛。需求模糊、方案未定、要做技术选型时使用。
+---
+
+# brainstorm — 发散与收敛
+
+## 流程
+
+1. **复述问题**：用一句话写下真实目标与成功标准。目标写不清就先问，别急着给方案。
+2. **发散（不评判）**：列出 ≥6 个方案，含"看起来不靠谱的"。此阶段禁止自我审查。
+3. **归类**：把方案归到 2–4 个方向（如：最小改动 / 一步到位 / 换个思路 / 不做）。
+4. **收敛**：每个方向选 1 个代表方案，按「代价 / 收益 / 可逆性」三列打分。
+5. **推荐 1 个 + 备选 1 个**，说明为什么淘汰其余。
+
+## 反合理化
+
+- "只有一个方案"——那就是还没发散完，回去重来。
+- "细节以后再想"——不可逆决策不允许以后再想。
+- "先做起来看看"——先做起来的前提是能回滚。
+
+## 验证
+
+完成后必须给出：① 至少 6 条候选；② 打分表；③ 明确推荐项 + 淘汰理由。

package/skills/cupid-lover-comms/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: cupid-lover-comms
+description: 可自定义角色沟通素材库（Role-based Chatting Kit）。按关系阶段组织话术与话题引子，含好话术/坏话术对照。需要设计拟人角色的对话风格、陪伴型文案时使用。
+---
+
+# 丘比特 · 可自定义角色沟通素材库（Role-based Chatting Kit）
+
+为拟人化角色（陪伴、客服人格、虚拟伴侣）提供分阶段的沟通素材，避免"上来就掏心窝子"这类失真人设。
+
+## 流程
+
+1. **定关系阶段**：先确定当前处于哪个阶段——初识 / 熟悉 / 亲近 / 稳定。阶段决定可用的亲密度和话题深度。
+2. **套漏斗（The Funnel）**：话题只能逐级下探，不可跳级。初识谈事实与兴趣，熟悉谈观点与经历，亲近才谈情绪与脆弱。
+3. **选话术**：同一意图准备"好话术 / 坏话术"两版对照——好话术给具体动作与承接，坏话术是套话与自我中心。
+4. **补话题引子**：从话题库里按阶段取 3–5 个开放性问题，避免只能回答"是/否"的封闭问题。
+5. **检查人设一致性**：把生成的回复与角色设定对齐——用词、语气、关注点是否像同一个人说的。
+
+## 好话术 vs 坏话术（对照表）
+
+| 场景 | 坏话术 | 好话术 |
+|---|---|---|
+| 对方说累了 | "那你早点休息" | "今天是什么事最耗神？说出来我陪你顺一遍" |
+| 对方分享好消息 | "恭喜恭喜！" | "这个你准备了挺久吧，最得意的是哪一步？" |
+| 对方情绪低落 | "别想太多了" | "先不急着解决，你想让我听着，还是想一起想办法？" |
+| 自己想表达关心 | "我一直都在" | "你上次提的那件事，后来怎么样了？" |
+
+> 判据：**坏话术结束对话，好话术开启下一步。**
+
+## 反合理化
+
+- "话说得越热络越像真人"——热络不等于亲密，越级热络是典型的人设崩塌。
+- "套话最安全"——套话没有信息量，对方接不下去，对话就死了。
+- "一句万能回复走天下"——同一个回复跨越所有阶段，等于没有阶段设计。
+
+## 验证
+
+必须给出：① 当前关系阶段判定；② 该阶段允许的话题深度；③ 好/坏话术对照至少 3 组；④ 人设一致性检查结果。

package/skills/debug/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: debug
+description: 面向根因的排障流程：先稳定复现再二分定位，禁止猜测式改代码。出现报错、行为异常、测试失败时使用。
+---
+
+# debug — 根因排障
+
+## 流程
+
+1. **读完整报错**：全文读，包括栈与 code（`ERR_*`），别只看第一行。
+2. **稳定复现**：写出最小复现命令。不能复现就先想办法复现，别改代码。
+3. **二分定位**：把链路切成两半，确认问题在哪半，重复到最小单元。
+4. **根因陈述**：用一句话说清"为什么"，并指出它在哪一行。
+5. **先写回归**：修之前先加一个能失败的测试，再改到它通过。
+6. **验证修复**：跑全量回归，确认没有连带破坏。
+
+## 反合理化
+
+- "先改改看"——猜测式修改会把真正的根因埋得更深。
+- "这个报错以前见过"——相似报错≠同一根因。
+- "加了 try/catch 就不报错了"——那是掩盖，不是修复。
+- "改完好了就行"——没写回归，下次还会犯。
+
+## 验证
+
+必须提供：① 最小复现命令与原始报错；② 定位到的 `文件:行号` 根因；③ 新增的回归测试；④ 全量回归结果。

package/skills/plan/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: plan
+description: 把模糊目标拆成可执行、可验证的步骤序列，标出依赖与风险。多步骤任务动手前使用。
+---
+
+# plan — 计划拆解
+
+## 流程
+
+1. **定终局**：写下"做完时什么样"（可观察的终态），不是"要做什么"。
+2. **倒推步骤**：从终态往回拆，每步输出必须是下一步的输入。
+3. **标注**：每步标 ① 依赖 ② 可回滚性 ③ 预计触碰的文件/系统。
+4. **找关键路径**：哪一步最可能卡住？先做它（风险前置）。
+5. **设检查点**：在不可逆动作之前插一个"停下来确认"。
+6. **产出**：有序步骤表 + 关键路径 + 检查点位置。
+
+## 反合理化
+
+- "边做边想"——不可逆的部分不允许边做边想。
+- "先全部做完再测"——每步都应可独立验证。
+- "步骤越多越专业"——超过 7 步就该分层。
+
+## 验证
+
+完成后必须给出：① 步骤表（含依赖与可回滚性）；② 关键路径；③ 每个不可逆动作前的检查点。

package/skills/ponytail/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: ponytail
+description: 最小改动原则：能改一行不改十行，能不加依赖就不加。任何重构、优化、修缺陷动手前使用。
+---
+
+# ponytail — 最小改动
+
+## 流程
+
+1. **先量体**：改之前统计当前现状（文件数、行数、测试数），改完再量一次，用差值证明改动范围。
+2. **找最小切口**：同样的效果，优先选"改动行数最少"的方案；能局部修就不整体重写。
+3. **零依赖优先**：能用手写 20 行解决，就不引入一个包（本项目的底线是运行时零依赖）。
+4. **不动无关代码**：顺手格式化、顺手改名、顺手删注释，都算越界 —— 除非它就在你改的这行上。
+5. **可回滚**：动不可逆的东西（删数据、改接口）前先备份或留隔离区。
+
+## 反合理化
+
+- "顺手重构一下"——顺手重构是最常见的"改出三个新 bug"来源。
+- "加个库更省事"——省的是你的时间，赔的是别人的部署。
+- "反正要改，一次改干净"——大爆炸式改动没法二分定位问题。
+- "这代码太丑了我看不下去"——丑但能跑，和跑不起来之间差一个 PR。
+
+## 验证
+
+必须提供：① 改动前后的量体数据（行数/文件数）；② 本次改动的 diff 范围说明；③ 明确列出"我刻意没改的东西"。

package/skills/ppx-memory/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ppx-memory
+description: 皮皮虾记忆引擎（ppx-memory）的读写规程与独立 CLI 用法：五层记忆结构、什么时候记、记到哪层、怎么检索与安全遗忘。涉及长期记忆、用户偏好、跨会话召回时使用。
+---
+
+# 皮皮虾记忆引擎 (ppx-memory)
+
+五层结构（L0 对话 → L1 原子事实 → L2 场景 → L3 画像 → L4 程序性记忆），自带高斯衰减、软删回滚、版本链与 WAL 增量落盘。
+
+本技能附带 `scripts/cli.js`，是一个**不依赖主项目**的独立可运行版本，可直接对记忆库做增删查。
+
+## 流程
+
+### 1. 判断该不该记
+
+只记**跨会话仍然成立**的信息：偏好、约定、稳定事实。
+不记：寒暄、提问、一次性的中间结果。（引擎已做句式过滤，但边界情况要自己判——脏记忆会喂回上下文污染判断。）
+
+### 2. 写入（选层）
+
+| 内容类型 | 目标层 | 工具 |
+|---|---|---|
+| 用户偏好 / 稳定事实 | L1 | `memory_add` |
+| 可复用的方法 / 流程 | L4（衰减仅 L1 的 1/4） | `memory_add`（layer=4）或 `create_skill` |
+| 场景知识 | L2 | 由 `afterTurn` 自动聚类归档 |
+
+内容必须**自包含**——脱离当前上下文也能读懂，否则三个月后检索出来也不知道在说什么。
+
+### 3. 检索
+
+- `memory_search` 走"粗召回（倒排索引）→ 精排（BM25 × 时间新鲜度 + 命中权重 + 重要性）"，门槛 1 分。
+- 需要更宽上下文时，同时取 L2 场景与 L3 画像（`persona_read`）。
+- 疑问句/多义词可用 `queryMulti` 的查询扩展（RRF 融合多路结果）。
+
+### 4. 遗忘（可回滚）
+
+```
+memory_forget        → 软删（状态置 deleted，检索立即不可见，数据保留）
+memory_restore       → 回滚（恢复即视为一次访问，避免刚恢复就被衰减清空）
+memory_list_deleted  → 复核已遗忘条目（含原因与时间）
+memory_clear_layer   → 按层清理（默认软删，hard=true 才物理删除）
+```
+
+**分不清该不该删时一律先软删。**
+
+### 5. 迁移
+
+`memory_export` / `memory_import` 用于换机或备份。导入前确认 `mode`：`merge`（按内容去重）还是 `replace`（整体替换，**会覆盖现有库**）。
+
+### 6. 独立 CLI 用法（不依赖主项目）
+
+```bash
+# 写入一条原子记忆（自动 PII 脱敏）
+node skills/ppx-memory/scripts/cli.js add "用户偏好深色主题"
+
+# 检索
+node skills/ppx-memory/scripts/cli.js search "主题偏好"
+
+# 组装完整上下文（今日 + 长期摘要 + 高分事实）
+node skills/ppx-memory/scripts/cli.js context
+
+# 读取最近会话
+node skills/ppx-memory/scripts/cli.js session --limit 50
+
+# 软删 / 回滚
+node skills/ppx-memory/scripts/cli.js forget <id>
+node skills/ppx-memory/scripts/cli.js restore <id>
+```
+
+数据目录默认 `<root>/data`，可用环境变量 `PPX_DATA_DIR` 覆盖。
+
+### 7. 集成到 OpenClaw 的时机
+
+满足以下任一条时，把本技能的 `scripts/` 目录挂到目标 harness：
+- 目标 harness 没有持久记忆，但需要跨会话召回用户偏好；
+- 需要与主项目的记忆库**共享同一份数据**（同一 `PPX_DATA_DIR`）；
+- 只想用记忆能力、不想引入整个 Agent 内核。
+
+> 注意：独立版与主项目 `src/memory/` 共享数据格式。**同一数据目录不要被两个进程同时写入**（主项目有文件锁，独立 CLI 也有，但跨进程仍建议串行使用）。
+
+## 反合理化
+
+- "先记下来再说"——记忆越用越脏，且会喂回上下文。
+- "记了删不掉"——软删可回滚，别因为怕删就不敢记。
+- "把用户原话整段存进去"——提问和寒暄不该入库。
+- "L4 和 L1 一样处理"——技能应该长期留存，衰减率不同正是为此。
+- "直接改 facts.json 更快"——绕过锁会损坏 WAL 一致性，务必走工具或 CLI。
+
+## 验证
+
+完成后必须确认：① 写入内容脱离上下文仍可读；② 软删→恢复可逆；③ 检索能命中刚写入的条目；④ 若用 CLI，跑完 `cli.js context` 能看到新条目。

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

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// skills/ppx-memory/scripts/cli.js - 皮皮虾记忆引擎「独立运行版」CLI
+// 不依赖主项目 src/, 直接对记忆库做增删查 (与主项目共享同一数据格式, 可用 PPX_DATA_DIR 共用)
+//
+// 用法:
+//   node cli.js add "内容" [--layer 1] [--importance 12] [--scope proj] [--type fact]
+//   node cli.js search "查询" [--limit 5]
+//   node cli.js context ["当前消息"]
+//   node cli.js session [--limit 50]
+//   node cli.js forget <id|内容> [--reason 原因]
+//   node cli.js restore <id>
+//   node cli.js deleted
+//   node cli.js stats
+//   node cli.js export [--no-deleted]
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { FactStore } from "./fact-store.js";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+// 默认数据目录: 技能位于 <root>/skills/ppx-memory/scripts/, 回退三级到 <root>/data
+const DATA = process.env.PPX_DATA_DIR || path.resolve(HERE, "..", "..", "..", "data");
+
+const out = (o) => console.log(typeof o === "string" ? o : JSON.stringify(o, null, 2));
+const facts = new FactStore(DATA);
+
+// 极简参数解析: 位置参数 + --key value
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) flags[key] = true;
+      else {
+        flags[key] = next;
+        i++;
+      }
+    } else positional.push(a);
+  }
+  return { positional, flags };
+}
+
+function addMemory(content, fl = {}) {
+  const f = facts.add(content, {
+    layer: fl.layer ? Number(fl.layer) : undefined,
+    importance: fl.importance ? Number(fl.importance) : undefined,
+    type: fl.type || undefined,
+    scope: fl.scope || null,
+  });
+  if (!f) {
+    out("未写入 (内容为空, 或被归一化去重命中已有条目)");
+    return;
+  }
+  out({ ok: true, id: f.id, layer: f.layer, score: Math.round(f.score * 100) / 100, content: f.content });
+}
+
+function printFacts(list) {
+  if (!list.length) {
+    out("(无匹配)");
+    return;
+  }
+  for (const f of list) {
+    const s = typeof f.score === "number" ? Math.round(f.score * 100) / 100 : "-";
+    out(`[L${f.layer ?? 1}] (${s}) ${f.id}  ${f.content}`);
+  }
+}
+
+// 读取最近会话 (直接读 jsonl, 不依赖 SessionStore API)
+function readSession(limit = 50) {
+  const dir = path.join(DATA, "sessions");
+  if (!fs.existsSync(dir)) return [];
+  const files = fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".jsonl"))
+    .map((f) => ({ f, m: fs.statSync(path.join(dir, f)).mtimeMs }))
+    .sort((a, b) => b.m - a.m);
+  const lines = [];
+  for (const { f } of files) {
+    for (const line of fs.readFileSync(path.join(dir, f), "utf8").split("\n")) {
+      if (line.trim()) lines.push(line);
+      if (lines.length > limit * 4) break;
+    }
+    if (lines.length > limit * 4) break;
+  }
+  return lines.slice(-limit).map((l) => {
+    try {
+      const o = JSON.parse(l);
+      const d = o.data || {};
+      return { ts: o.ts, type: o.type, text: d.user || d.assistant || d.text || "" };
+    } catch {
+      return { raw: l };
+    }
+  });
+}
+
+const { positional, flags } = parseArgs(process.argv.slice(2));
+const [cmd, ...rest] = positional;
+
+switch (cmd) {
+  case "add":
+    addMemory(rest.join(" "), flags);
+    break;
+
+  case "search":
+  case "q": {
+    const q = rest.join(" ");
+    if (!q) {
+      out("需要查询关键词");
+      process.exit(1);
+    }
+    const limit = flags.limit ? Number(flags.limit) : 5;
+    const hits = facts.query(q, { limit });
+    hits.forEach((h) => facts.hit(h.id)); // 命中加分 (与主项目一致)
+    printFacts(hits);
+    break;
+  }
+
+  case "context": {
+    // 组装: 高分事实 + 长期摘要 (today/longterm 由 MemoryTicker 维护, 此处轻量回退)
+    const q = rest.join(" ");
+    printFacts(facts.query(q, { limit: 8 }));
+    const lt = path.join(DATA, "memory", "longterm.md");
+    if (fs.existsSync(lt)) {
+      out("\n--- longterm ---");
+      out(fs.readFileSync(lt, "utf8").trim().slice(0, 2000));
+    }
+    break;
+  }
+
+  case "session": {
+    const limit = flags.limit ? Number(flags.limit) : 50;
+    const rows = readSession(limit);
+    if (!rows.length) out("(无会话记录)");
+    for (const r of rows) out(`${r.type || "?"}  ${String(r.text || r.raw || "").slice(0, 160)}`);
+    break;
+  }
+
+  case "forget": {
+    const target = rest.join(" ");
+    if (!target) {
+      out("需要 id 或内容片段");
+      process.exit(1);
+    }
+    const r = facts.forget(target, { reason: flags.reason || null });
+    out(r ? { ok: true, forgotten: r.id || target } : "未找到可遗忘的条目");
+    break;
+  }
+
+  case "restore": {
+    const id = rest.join(" ");
+    const r = facts.restore(id);
+    out(r ? { ok: true, restored: r.id || id } : "未找到该 id (或未被软删)");
+    break;
+  }
+
+  case "deleted": {
+    const all = facts.exportAll({ includeDeleted: true });
+    const list = (Array.isArray(all) ? all : all.facts || []).filter((f) => f.status === "deleted");
+    if (!list.length) out("(无已遗忘条目)");
+    for (const f of list) out(`${f.id}  ${f.content}  ← ${f.deletedReason || "无原因"}`);
+    break;
+  }
+
+  case "stats":
+    out(facts.stats());
+    break;
+
+  case "export": {
+    const all = facts.exportAll({ includeDeleted: flags["no-deleted"] !== true });
+    process.stdout.write(JSON.stringify(all, null, 2));
+    break;
+  }
+
+  default:
+    out(`皮皮虾记忆引擎 · 独立 CLI
+数据目录: ${DATA}
+
+用法:
+  add <内容> [--layer 1] [--importance 12] [--scope xxx]   写入一条记忆
+  search <关键词> [--limit 5]                              检索 (命中自动加分)
+  context [当前消息]                                       组装上下文 (高分事实 + 长期摘要)
+  session [--limit 50]                                     读取最近会话
+  forget <id|内容> [--reason 原因]                         软删 (可恢复)
+  restore <id>                                             回滚软删
+  deleted                                                  列出已遗忘条目
+  stats                                                    记忆库统计
+  export [--no-deleted]                                    导出 JSON`);
+    process.exit(cmd ? 1 : 0);
+}

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

@@ -0,0 +1,133 @@
+// src/memory/experience.js - 经验库 (自学习)
+// 从每次任务结果中提炼经验, 供后续任务参考 (参考 openhanako experience)
+// 跨 agent 共享: 支持全局经验目录 (globalDataDir), 写入用文件锁防并发覆盖
+// v1.0.7: 同义经验相似合并 (bigram overlap, 词序/措辞变体命中合并而非新增)
+import path from "node:path";
+import { ensureDir, readJson, writeJson, nowISO, withFileLock } from "./store.js";
+import { overlapCoefficient } from "./similarity.js";
+
+// 同义合并阈值: 经验 lesson 的 bigram overlap 达到此值视为同一条
+// 用真实生产变体校准: 同义改写 0.50-0.55, 相关但不同 0.29, 不相关 0.0 → 0.5 能抓同义不误伤
+const SIM_THRESHOLD = 0.5;
+
+// overlap 系数 (交集 / 较短者): 对词序变化容忍, 实现收敛到 utils/similarity
+// (与 FactStore._overlap 同思路, 但分词/阈值各自独立)
+export const lessonOverlap = overlapCoefficient;
+
+// 模板句判定: 去掉数字后完全相同 (如 "A 经验教训 0" vs "A 经验教训 1")
+// 这类"仅编号不同"的条目是不同内容, 不参与同义合并 (防误伤)
+function _isTemplateLike(a, b) {
+  return String(a).replace(/\d+/g, "#") === String(b).replace(/\d+/g, "#");
+}
+
+export class Experience {
+  constructor(dataDir) {
+    this.dir = path.join(dataDir, "experience");
+    ensureDir(this.dir);
+    this.file = path.join(this.dir, "lessons.json");
+    this.lessons = readJson(this.file, []);
+  }
+
+  learn({ task, outcome, lesson, tags = [] }) {
+    const entry = {
+      id: "e_" + Math.random().toString(36).slice(2, 10),
+      task: String(task || "").slice(0, 300),
+      outcome: String(outcome || "").slice(0, 300),
+      lesson: String(lesson || "").slice(0, 500),
+      tags,
+      ts: nowISO(),
+      uses: 0,
+    };
+    if (!entry.lesson || entry.lesson.length < 5) return null;
+    // 内容去重: 同一 lesson 已存在则命中加分 (uses+1) 而非新增, 防高频学习路径写放大
+    // 归一化: 去首尾空白 + 折叠连续空白 (与 FactStore._norm 同策略)
+    const normKey = String(lesson).trim().replace(/\s+/g, " ");
+    // 锁内读-改-写: 防止多 agent 共享经验库时并发覆盖
+    return withFileLock(this.file, () => {
+      this.lessons = readJson(this.file, []);
+      const existing = this.lessons.find((l) => String(l.lesson || "").trim().replace(/\s+/g, " ") === normKey);
+      if (existing) {
+        existing.uses += 1;
+        existing.ts = nowISO(); // 刷新时间, 让近期命中经验排到 context 前面
+        writeJson(this.file, this.lessons);
+        return existing;
+      }
+      // 同义合并 (v1.0.7): 措辞/词序不同的变体 (逃过精确去重) 语义相似时合并, 防同义经验堆积
+      // 排除"仅编号不同"的模板句 (如 A 经验教训 0/1 → 视为不同条目)
+      const similar = this.lessons.find((l) => {
+        const la = String(l.lesson || "");
+        if (_isTemplateLike(la, entry.lesson)) return false;
+        return lessonOverlap(la, entry.lesson) >= SIM_THRESHOLD;
+      });
+      if (similar) {
+        similar.uses += 1;
+        similar.ts = nowISO();
+        writeJson(this.file, this.lessons);
+        return similar;
+      }
+      this.lessons.push(entry);
+      this._prune();
+      writeJson(this.file, this.lessons);
+      return entry;
+    });
+  }
+
+  recall(taskDesc) {
+    const q = String(taskDesc || "").toLowerCase();
+    const scored = this.lessons
+      .map((l) => {
+        let s = 0;
+        const hay = (l.lesson + " " + l.task + " " + l.tags.join(" ")).toLowerCase();
+        if (q && hay.includes(q)) s += 10;
+        if (l.uses > 0) s += Math.min(l.uses, 5);
+        return { ...l, score: s };
+      })
+      .filter((l) => l.score > 0)
+      .sort((a, b) => b.score - a.score);
+    return scored.slice(0, 5);
+  }
+
+  use(id) {
+    withFileLock(this.file, () => {
+      this.lessons = readJson(this.file, []);
+      const l = this.lessons.find((x) => x.id === id);
+      if (l) { l.uses += 1; writeJson(this.file, this.lessons); }
+    });
+  }
+
+  // 经验清单 (公开读 API): 默认按命中次数降序, 同次数按时间新→旧
+  // 供 fork 快照 / 外部观测使用 (调用方无需触碰 this.lessons 内部数组)
+  list({ limit = 0, sort = "uses" } = {}) {
+    const all = [...this.lessons];
+    if (sort === "uses") {
+      all.sort((a, b) => (b.uses || 0) - (a.uses || 0) || new Date(b.ts || 0) - new Date(a.ts || 0));
+    } else if (sort === "ts") {
+      all.sort((a, b) => new Date(b.ts || 0) - new Date(a.ts || 0));
+    }
+    const n = Number(limit) || 0;
+    return n > 0 ? all.slice(0, n) : all;
+  }
+
+  // 条目数 (可观测)
+  count() {
+    return this.lessons.length;
+  }
+
+  _prune() {
+    // 最多保留 200 条
+    if (this.lessons.length > 200) {
+      this.lessons.sort((a, b) => b.uses - a.uses);
+      this.lessons = this.lessons.slice(0, 200);
+    }
+  }
+
+  context() {
+    // 优先命中次数 (高频教训浮上来, 让反复发生的硬拒绝/跨会话坑真正影响行为),
+    // 同次数按时间新→旧 (近期教训仍可见)。蒸馏接缝: B3 auto-self-review 教训 uses 随复发上涨,
+    // 从而在上下文里越来越突出, 形成「经验→长期准则」的浮升链路。
+    const picked = [...this.lessons]
+      .sort((a, b) => (b.uses || 0) - (a.uses || 0) || new Date(b.ts || 0) - new Date(a.ts || 0))
+      .slice(0, 5);
+    return picked.map((l) => `- 经验: ${l.lesson}`).join("\n") || "(暂无经验)";
+  }
+}