ppxans-harness 2.4.0

package/src/agent/prompts.js

@@ -0,0 +1,107 @@
+// src/agent/prompts.js - Agent 提示词/上下文构建 (从 index.js 拆分, mixin 挂回 prototype)
+// 重构 (2026-09-15): 提示词组装 (技能清单/核心价值/DSML/画像/多模态) 从 PPXAgent 类中抽出,
+// 方法以 mixin 方式挂回 prototype, 实例行为与调用方完全不变。
+
+import { buildDsmlPrompt } from "../llm/dsml.js";
+import { valuesPrompt } from "../ans/values.js";
+import { context as rewardContext } from "../ans/reward.js";
+import { imageFileToDataUrl } from "../tools/builtin.js";
+
+// 多模态: 提取 user 消息中的图片路径并同步读图, 注入 OpenAI 视觉格式的 content 数组。
+// 仅当当前 LLM 是 http 后端且 provider 标记 vision=true 时生效 (openclaw/dsh 走文本围栏不传图)。
+// 返回 string (无图/不支持) 或 [{type:text}, {type:image_url}...]
+export function visionUserContent(llm, root, userMsg) {
+  const text = String(userMsg);
+  if (!llm || llm.backend !== "http" || !llm.vision) return text;
+  const paths = [];
+  for (const m of text.matchAll(/[^\s"'`，。；;：:,，()（）]+\.(?:png|jpe?g|gif|webp|bmp)/gi)) {
+    paths.push(m[0]);
+  }
+  if (!paths.length) return text;
+  const content = [{ type: "text", text }];
+  for (const p of [...new Set(paths)].slice(0, 4)) {
+    try {
+      const dataUrl = imageFileToDataUrl(root, p);
+      content.push({ type: "image_url", image_url: { url: dataUrl } });
+    } catch { /* 读图失败静默跳过, 保留纯文本 */ }
+  }
+  return content.length > 1 ? content : text;
+}
+
+export const promptMethods = {
+  // 组装记忆上下文
+  // 差异化视角 (_perspective): 多 agent 场景下由委派方注入子 agent 的专属视角,
+  // 对抗同质失败 (Anthropic: 同模型+同上下文 → 一个错全错), 生命周期由调用方控制
+  // 方法技能清单注入: 让 LLM 知道有哪些方法论技能可用, 面对任务时主动 load_skill
+  // (Superpowers 吸收: 技能不自动生效, 需要触发才读取全文, 省 token)
+  _skillsPrompt() {
+    try {
+      if (!this.skills) return "";
+      const list = this.skills.list().filter((s) => s && s.description);
+      if (!list.length) return "";
+      return "【可用技能】面对对应任务时用 load_skill 读取全文再执行:\n"
+        + list.map((s) => `- ${s.id}: ${s.description}`).join("\n");
+    } catch { return ""; }
+  },
+
+  _context(userMsg) {
+    const base = this.persona.systemPrompt(this.userName) + "\n\n" + this.memory.context(userMsg) + "\n\n" + this.experience.context() + this._l3Context();
+    // 核心价值 (ANS 价值对齐): 注入最前, 独立于 prompt, 不可被后续指令违背
+    const values = this._valuesPrompt();
+    // 引用规则 + 额外 system 内容均可配置 (agent.citation_rule / agent.system_extra)
+    const citation = this.config.agent?.citation_rule || "";
+    const extra = this.config.agent?.system_extra || "";
+    const perspective = this._perspective ? `【任务视角】${this._perspective}` : "";
+    const active = this.scenes.activeContext(userMsg || "");
+    const baseCtx = active ? base + "\n\n" + active : base;
+    const skills = this._skillsPrompt();
+    // DSML 原生文本模型 opt-in (provider.dsml=true): 注入工具协议, 让模型能稳定输出 DSML 结构做工具调用
+    const dsml = this._dsmlPrompt();
+    const rewardCtx = rewardContext(this); // ⑦ 低可靠性工具提醒 (Reward 闭环注入)
+    return [values, baseCtx, skills, citation, perspective, extra, dsml, rewardCtx].filter(Boolean).join("\n\n");
+  },
+
+  // DSML 工具调用协议注入 (v1.1.1 接线): 修复 buildDsmlPrompt 过去从未注入的缺口。
+  // 仅当激活的 http provider 显式 dsml=true 且工具启用时注入; 默认所有 provider 不注入(零回归)。
+  _dsmlPrompt() {
+    try {
+      if (!(this.llm && this.llm.dsml === true)) return "";
+      if (!this.toolsEnabled || !this.tools) return "";
+      const tools = this.tools.toOpenAI();
+      return buildDsmlPrompt(tools);
+    } catch { return ""; }
+  },
+
+  // 核心价值文本 (委托 ans/values 模块): 数组 → 固定格式注入 (无值时不注入, 向后兼容)
+  _valuesPrompt() {
+    return valuesPrompt(this.config.agent?.values);
+  },
+
+  // L3 画像注入: 已生成的用户画像 + agent 自我画像 (未生成返回 "")
+  _l3Context() {
+    try {
+      const parts = [];
+      const u = this.personaStore.userPersona();
+      const a = this.personaStore.agentPersona();
+      if (u) parts.push(u);
+      if (a) parts.push(a);
+      return parts.length ? "\n\n" + parts.join("\n\n") : "";
+    } catch { return ""; }
+  },
+
+  // L3 画像刷新: 跨天触发 (实现已迁 memory-service, 此处分发; 日期标记在 service 内部)
+  _maybeRefreshPersona() {
+    return this.memorySvc.refreshPersona();
+  },
+
+  // 找视觉 provider: 当前 LLM 若是 vision 直接用, 否则从 allProviders 找第一个 vision
+  _visionLLM() {
+    if (this.llm && this.llm.vision) return this.llm;
+    return (this.allProviders || []).find((p) => p.vision) || null;
+  },
+
+  // 多模态 user 消息内容: 有图且存在 vision provider 时返回 content 数组, 否则纯文本
+  _userContent(userMsg) {
+    return visionUserContent(this._visionLLM(), this.root, userMsg);
+  }
+};

package/src/aml-server.js

@@ -0,0 +1,151 @@
+// src/aml-server.js - AML (Agent Memory Leaderboard) 适配服务
+// 提供 Add + Search 契约, 映射进 FactStore (BM25 + bigram 检索, scope 隔离)
+// 端点:
+//   POST /v1/memories/add    同步存储 (消息完整落盘且可检索后才返回), 回显 request_id
+//   POST /v1/memories/search query + scope + top_k 检索
+//   GET  /health
+// 鉴权: PPX_AML_AUTH = token|bearer|x-api-key|none (默认 none)
+//       PPX_AML_AUTH_VALUE = 对应密钥
+// 启动: node src/aml-server.js   (监听 PPX_AML_PORT, 默认 8900)
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { FactStore } from "./memory/fact-store.js";
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const PORT = Number(process.env.PPX_AML_PORT || 8900);
+const DATA = process.env.PPX_AML_DATA || path.join(ROOT, "data", "aml");
+const AUTH_SCHEME = (process.env.PPX_AML_AUTH || "none").toLowerCase();
+const AUTH_VALUE = process.env.PPX_AML_AUTH_VALUE || "";
+const MAX_BODY = 1024 * 1024; // 1MB 请求体上限, 防滥用
+const RATE_PER_MIN = 60;      // 每 IP 每分钟最大请求数 (令牌桶, 对齐 http.js)
+const RATE_WINDOW_MS = 60_000;
+
+const store = new FactStore(DATA, {});
+const _buckets = new Map(); // ip -> {tokens, last}
+
+// 简单令牌桶限流: 每 IP 60 req/min (对齐 channels/http.js) [P1#10]
+function rateLimit(req, res) {
+  const ip = req.socket?.remoteAddress || "unknown";
+  const now = Date.now();
+  let b = _buckets.get(ip);
+  if (!b) {
+    b = { tokens: RATE_PER_MIN, last: now };
+    _buckets.set(ip, b);
+  }
+  const refill = Math.floor((now - b.last) / RATE_WINDOW_MS);
+  if (refill > 0) {
+    b.tokens = Math.min(RATE_PER_MIN, b.tokens + refill * RATE_PER_MIN);
+    b.last = now;
+  }
+  if (b.tokens <= 0) {
+    res.writeHead(429, { "Content-Type": "application/json", "Retry-After": "60" });
+    res.end(JSON.stringify({ error: "rate limited" }));
+    return false;
+  }
+  b.tokens -= 1;
+  return true;
+}
+
+function authOk(req) {
+  if (AUTH_SCHEME === "none") return true;
+  if (AUTH_SCHEME === "token") return req.headers.authorization === "Token " + AUTH_VALUE;
+  if (AUTH_SCHEME === "bearer") return req.headers.authorization === "Bearer " + AUTH_VALUE;
+  if (AUTH_SCHEME === "x-api-key") return req.headers["x-api-key"] === AUTH_VALUE;
+  return false;
+}
+
+// 读取请求体, 带大小上限 (超限/非法 JSON 返回 null)
+function readBody(req, maxBytes = MAX_BODY) {
+  return new Promise((resolve) => {
+    let d = "";
+    let tooBig = false;
+    req.on("data", (c) => {
+      if (tooBig) return; // 已超限, 丢弃后续数据但不断连 (让 handler 回 413)
+      d += c;
+      if (Buffer.byteLength(d) > maxBytes) { tooBig = true; d = ""; }
+    });
+    req.on("end", () => {
+      if (tooBig) return resolve(null); // handler 据此回 413
+      try { resolve(JSON.parse(d)); } catch { resolve(null); }
+    });
+    req.on("error", () => resolve(null));
+  });
+}
+
+function send(res, code, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(code, { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) });
+  res.end(body);
+}
+
+// Add: messages[] -> 每条存为带 scope + 结构化元数据(role/seq/timestamp) 的 fact
+// 保留 role/顺序/时间, 支撑 AML 多跳/时间/关系维度
+// 同步语义 = 全部落盘且可检索后才返回
+async function handleAdd(req, res) {
+  const body = await readBody(req);
+  if (!body) return send(res, 413, { error: "request body too large or invalid" });
+  if (!body || !Array.isArray(body.messages)) return send(res, 422, { error: "messages[] required" });
+  const { request_id, messages, scope, conversation_id, async_mode } = body;
+  if (scope == null) return send(res, 422, { error: "scope required" });
+  let stored = 0;
+  messages.forEach((m, i) => {
+    const content = String(m?.content || "").trim();
+    if (!content) return;
+    const meta = {
+      seq: i, // 保留对话内顺序
+    };
+    if (m.role != null) meta.role = String(m.role); // 保留 speaker
+    if (m.timestamp != null) meta.timestamp = m.timestamp; // 保留原始时间戳
+    if (conversation_id != null) meta.conversation_id = String(conversation_id);
+    store.add(content, { type: "message", source: "aml", dedupe: false, scope: String(scope), meta });
+    stored += 1;
+  });
+  // request_id 原样回显; 同步模式已完成存储
+  return send(res, 200, {
+    request_id: request_id ?? null,
+    status: "ok",
+    stored,
+    scope: String(scope),
+    conversation_id: conversation_id ?? null,
+    async_mode: async_mode || false,
+  });
+}
+
+async function handleSearch(req, res) {
+  const body = await readBody(req);
+  if (!body) return send(res, 413, { error: "request body too large or invalid" });
+  const query = String(body?.query || "").trim();
+  const scope = body?.scope ?? null;
+  const top_k = Math.min(Number(body?.top_k || 10), 100);
+  if (!query) return send(res, 422, { error: "query required" });
+  const hits = store.query(query, { limit: top_k || 10, scope: scope == null ? null : String(scope) });
+  return send(res, 200, {
+    query,
+    scope: scope ?? null,
+    count: hits.length,
+    results: hits.map((h) => ({ id: h.id, content: h.content, score: Math.round(h.effectiveScore * 100) / 100 })),
+  });
+}
+
+export function createAmlServer() {
+  return http.createServer(async (req, res) => {
+    const url = new URL(req.url, "http://x");
+    if (!authOk(req)) return send(res, 401, { error: "unauthorized" });
+    if (!rateLimit(req, res)) return;
+    const pathname = url.pathname;
+    if (req.method === "POST" && pathname === "/v1/memories/add") return handleAdd(req, res);
+    if (req.method === "POST" && pathname === "/v1/memories/search") return handleSearch(req, res);
+    if (req.method === "GET" && pathname === "/health") return send(res, 200, { status: "ok" });
+    return send(res, 404, { error: "not found" });
+  });
+}
+
+// CLI 入口: 直接运行本文件时启动服务器
+if (import.meta.url === `file:///${process.argv[1]?.replace(/\\\\/g, "/")}`) {
+  const server = createAmlServer();
+  server.listen(PORT, () => {
+    console.log(`[aml-server] listening on :${PORT} | auth=${AUTH_SCHEME} | data=${DATA}`);
+    console.log(`  POST /v1/memories/add    POST /v1/memories/search    GET /health`);
+  });
+}

package/src/ans/eviction.js

@@ -0,0 +1,144 @@
+// src/ans/eviction.js - 排泄系 (⑤ 遗忘-归档) 自治治理 (ANS)
+//
+// 职责 (RC1 §1 ⑤): 记忆压缩、冷热层、历史会话归档、冗余识别、过期治理、遗忘与删除候选生成。
+//   边界仅限跨会话长期记忆 (L1 FactStore + 会话日志); 功能性缓存/日志不归它管。
+//
+// 本期聚焦三大可落地的自治能力:
+//   1. 冗余识别 - 利用 FactStore.findSimilar 检测高度重复记忆, 标记为"冗余候选"(合并/降权/删除候选)
+//   2. 冷热分层 - 按 低访问天数×低衰减分 识别"冷记忆", 归档为只读, 不占热上下文
+//   3. 归档扫描 - 产出结构化治理报告 (preview 不直接改), 挂 Scheduler 每日自动跑
+//
+// 删除策略 (务实): findSimilar 检测到的高相似对 → 保留高保真(importance/hits 更高)那条, 低的那条标"冗余候选"。
+//   默认只"报告 + 标记", 硬删除交给 FactStore 既有 _prune (超 maxFacts 时)。本模块产出治理信号, 不越权改数据。
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir } from "../utils/store.js";
+import { info } from "../utils/logger.js";
+
+// 冗余判定阈值 (bigram overlap 相似度, 0~1; 中文同义变体通常 >0.6)
+const SIM_THRESHOLD = 0.6;
+// 中文 bigram 集: 连续两个字符为一组 (字符级 bigram, 对中文简繁/词序变化有容错)
+function _bigramSet(s) {
+  const set = new Set();
+  const t = String(s || "").replace(/\s+/g, "");
+  for (let i = 0; i < t.length - 1; i++) set.add(t.slice(i, i + 2));
+  return set;
+}
+// bigram overlap: 交集 / 较短集合 (0~1) — 对「共享核心词但措辞宽松」更敏感
+function _overlap(a, b) {
+  const A = _bigramSet(a), B = _bigramSet(b);
+  if (!A.size || !B.size) return 0;
+  let inter = 0;
+  for (const x of A) if (B.has(x)) inter++;
+  return inter / Math.min(A.size, B.size);
+}
+// 冷记忆判定: 连续 N 天未被访问 + 分数低于分位 → 冷
+const COLD_DAYS = 14;
+// 治理报告保留条数
+const REPORT_LIMIT = 50;
+
+function _file(agent) { return path.join(agent.dataDir, "memory", "eviction.json"); }
+
+// 读取治理状态 (缺失/损坏 → 空)
+export function loadState(agent) {
+  try {
+    const f = _file(agent);
+    if (fs.existsSync(f)) {
+      const s = JSON.parse(fs.readFileSync(f, "utf8"));
+      return (s && typeof s === "object") ? s : {};
+    }
+  } catch {}
+  return {};
+}
+
+export function saveState(agent, state) {
+  try {
+    const f = _file(agent);
+    ensureDir(path.dirname(f));
+    fs.writeFileSync(f, JSON.stringify(state, null, 2), "utf8");
+  } catch {}
+}
+
+// 幂等记录一次扫描结果 (去重: 同 id 已存在则更新, 不无限追加)
+function _recordRun(agent, run) {
+  const st = loadState(agent);
+  st.lastRun = run;
+  saveState(agent, st);
+}
+
+// 扫描一次 L1 记忆: 返回 { redundant, cold, total, scanned } 治理报告 (只读, 不改数据)
+export function scan(agent) {
+  const facts = agent.facts;
+  if (!facts || typeof facts.list !== "function" || !facts.findSimilar) {
+    return { total: 0, redundant: [], cold: [], lastRunAt: Date.now() };
+  }
+  let all = [];
+  try { all = facts.list() || []; } catch { return { total: 0, redundant: [], cold: [], error: "list-failed" }; }
+  if (!all.length) return { total: 0, redundant: [], cold: [], lastRunAt: Date.now() };
+
+  const now = Date.now();
+  const DAY = 86400000;
+
+  // 1) 冗余识别: 两两 findSimilar 检测高相似对, 标低保真那条为冗余候选
+  const redundant = [];
+  const visited = new Set();
+  // 两两比较 (自实现 overlap): findSimilar 对自身返回1.0无法用, 逐对算 bigram 相似度
+  for (let i = 0; i < all.length; i++) {
+    const f = all[i];
+    if (visited.has(f.id)) continue;
+    let best = null, bestSim = 0;
+    for (let j = 0; j < all.length; j++) {
+      const g = all[j];
+      if (g.id === f.id || visited.has(g.id)) continue;
+      try {
+        const sim = _overlap(f.content, g.content);
+        if (sim > bestSim) { bestSim = sim; best = g; }
+      } catch {}
+    }
+    if (best && bestSim >= SIM_THRESHOLD) {
+      const aKeep = (f.importance || 0) + (f.hits || 0);
+      const bKeep = (best.importance || 0) + (best.hits || 0);
+      const loser = aKeep >= bKeep ? best : f;
+      const winner = aKeep >= bKeep ? f : best;
+      redundant.push({
+        id: loser.id,
+        content: String(loser.content || "").slice(0, 120),
+        keepId: winner.id,
+        keep: String(winner.content || "").slice(0, 120),
+        importance: loser.importance || 0,
+        hits: loser.hits || 0,
+        sim: Math.round(bestSim * 100) / 100,
+      });
+      visited.add(loser.id);
+      visited.add(f.id);
+    } else {
+      visited.add(f.id);
+    }
+  }
+
+  // 2) 冷热分层: N 天未访问 → 冷 (归档候选, 不参与热上下文)
+  const cold = all
+    .filter((f) => {
+      const last = f.lastAccess ? new Date(f.lastAccess).getTime() : (f.created ? new Date(f.created).getTime() : now);
+      return (now - last) > COLD_DAYS * DAY;
+    })
+    .map((f) => ({ id: f.id, content: String(f.content || "").slice(0, 120), lastAccess: f.lastAccess, importance: f.importance || 0, hits: f.hits || 0 }))
+    .slice(0, REPORT_LIMIT);
+
+  const run = {
+    total: all.length,
+    redundant: redundant.slice(0, REPORT_LIMIT),
+    redundantCount: redundant.length,
+    coldCount: cold.length,
+    cold: cold.slice(0, REPORT_LIMIT),
+    lastRunAt: Date.now(),
+  };
+  _recordRun(agent, run);
+  info(`[eviction] 扫描 ${all.length} 条: 冗余 ${redundant.length}, 冷记忆 ${cold.length}`);
+  return run;
+}
+
+// 人类可读状态 (可观测)
+export function status(agent) {
+  return loadState(agent);
+}

package/src/ans/guard.js

@@ -0,0 +1,120 @@
+// src/ans/guard.js - 免疫系 (⑧安全治理) 全局闸门 (ANS)
+// 在 P0 总线 intercept() 之上搭全局免疫: 任何经总线命令通道的动作执行前先过闸门。
+// 能力 (务实, 不硬造):
+//   1. 全局审计 - 所有放行/拒绝的命令记入 Auditor 账本 (可离线核实)
+//   2. 危险 verb 阻断 - 白名单制: 未显式放行的"危险操作"(删除/清空/覆盖写) 默认拒绝
+//   3. 单次审批授权 - 对越出白名单的关键操作可单次放行 (双模式授权)
+// 说明: 总线 command 通道 (P0 建) + 免疫闸门 (本模块) 形成"执行前统一安全校验"。
+//   现有工具走 catalog/seam (已有局部 runWithPolicy 权限)；本闸门覆盖"走总线命令"的敏感动作 (记忆写/删除等未来接线)。
+// P0 (2026-09-15): 新增 installGuardOnCatalog —— 把同一闸门状态挂到 ToolCatalog 策略链,
+//   解决 MERGE-REPORT 遗留 P2 (guard 空转: 工具走 catalog 不走总线)。危险判定作用于工具名。
+import { hasPII } from "../utils/pii.js";
+
+// 危险 verb 前缀: 命中且未显式白名单放行 → 需单次审批或拒绝
+const DANGEROUS_RE = /^(delete|remove|clear|wipe|drop|purge|truncate|overwrite)/i;
+// 默认记审计账本的最大条目
+const AUDIT_LIMIT = 200;
+
+// 危险判定: verb 命中危险前缀且未白名单放行
+export function isDangerous(verb, allowList = []) {
+  return DANGEROUS_RE.test(verb) && !allowList.includes(verb);
+}
+
+// 安装免疫闸门: 挂到 agent.bus.intercept(), 返回可观测状态
+// opts.intercept: 是否实际拦截 (true=默认审计+危险阻断; false=仅审计不阻断, 用于灰度)
+export function installGuard(agent, opts = {}) {
+  if (!agent.bus || typeof agent.bus.intercept !== "function") {
+    return { enabled: false, reason: "no-bus" };
+  }
+  const { intercept = true, allowList = [], ledgerLimit = AUDIT_LIMIT } = opts;
+  const state = {
+    enabled: true,
+    intercept,
+    allowList: [...allowList],
+    checks: 0,
+    blocked: 0,
+    allowed: 0,
+    audited: [],
+    lastVerdict: null,
+  };
+
+  const record = (verdict, cmd, note) => {
+    state.checks++;
+    if (verdict === "block") state.blocked++;
+    else if (verdict === "allow" || verdict === "approve") state.allowed++;
+    state.audited.push({ verdict, verb: cmd.verb, id: cmd.id, ts: Date.now(), note, payloadHasPII: hasPII(JSON.stringify(cmd.payload || {})) });
+    if (state.audited.length > ledgerLimit) state.audited = state.audited.slice(-ledgerLimit);
+    // 写 Auditor 账本 (若装了)
+    try {
+      if (agent.auditor && typeof agent.auditor.record === "function") {
+        agent.auditor.record("guard", { verdict, verb: cmd.verb, note });
+      }
+    } catch {}
+    state.lastVerdict = { verdict, verb: cmd.verb, note };
+  };
+
+  // 卸载钩子
+  const off = agent.bus.intercept(async (cmd, next) => {
+    const verb = String(cmd.verb || "");
+    const dangerous = DANGEROUS_RE.test(verb);
+    const allowed = state.allowList.includes(verb);
+    if (!dangerous || allowed) {
+      record("allow", cmd, dangerous ? "dangerous-whitelisted" : "normal");
+    } else if (intercept) {
+      record("block", cmd, "dangerous-not-whitelisted");
+      throw new Error("免疫闸门: 危险命令未授信而阻断: " + verb);
+    } else {
+      record("allow", cmd, "dangerous-observed-not-blocked");
+    }
+    await next();
+  });
+
+  // 单次审批授权: 放行一次危险 verb (一次用完自动失效)
+  const approveOnce = (verb) => { state.allowList.push(verb); return () => removeAllow(verb); };
+  const removeAllow = (verb) => { const i = state.allowList.indexOf(verb); if (i >= 0) state.allowList.splice(i, 1); };
+  const status = () => ({ enabled: state.enabled, intercept: state.intercept, checks: state.checks, blocked: state.blocked, allowed: state.allowed, allowList: [...state.allowList], recent: state.audited.slice(-10) });
+
+  return { off, approveOnce, status, _state: state };
+}
+
+// ---- P0: 免疫闸门接入工具执行收口 (ToolCatalog 策略链) ----
+// 与 installGuard (总线版) 共享同一 state: allowList / 计数 / 审计记录全部复用,
+// 所以 agent.approveGuard("delete/x") 一次授权同时作用于总线命令和工具调用。
+// catalog.addPolicySubscriber 已保证: 策略订阅者异常不拖垮工具 (fail-open + 日志)。
+export function installGuardOnCatalog(catalog, guardHandle) {
+  if (!catalog || typeof catalog.addPolicySubscriber !== "function") {
+    return { enabled: false, reason: "no-catalog" };
+  }
+  const state = guardHandle?._state;
+  if (!state) return { enabled: false, reason: "no-guard-state" };
+  const off = catalog.addPolicySubscriber(async (name, args, ctx) => {
+    const verb = String(name || "");
+    const dangerous = DANGEROUS_RE.test(verb);
+    const allowed = state.allowList.includes(verb);
+    if (!dangerous || allowed) {
+      state.checks++;
+      state.allowed++;
+      state.audited.push({ verdict: "allow", verb, ts: Date.now(), note: dangerous ? "dangerous-whitelisted" : "normal", payloadHasPII: hasPII(JSON.stringify(args || {})) });
+      if (state.audited.length > AUDIT_LIMIT) state.audited = state.audited.slice(-AUDIT_LIMIT);
+      return null; // 弃权 = allow (放行)
+    }
+    state.checks++;
+    state.blocked++;
+    state.audited.push({ verdict: "block", verb, ts: Date.now(), note: "dangerous-not-whitelisted", payloadHasPII: hasPII(JSON.stringify(args || {})) });
+    if (state.audited.length > AUDIT_LIMIT) state.audited = state.audited.slice(-AUDIT_LIMIT);
+    if (typeof guardHandle.status === "function") {
+      try {
+        // 同步状态到 guard 的 lastVerdict (可观测)
+        const st = guardHandle._state;
+        st.lastVerdict = { verdict: "block", verb, note: "dangerous-not-whitelisted" };
+      } catch {}
+    }
+    return { decision: "deny", reason: "免疫闸门: 危险工具未授信: " + verb, priority: 100 };
+  }, { name: "immune-guard", priority: 100 });
+  return { enabled: true, off };
+}
+
+// 可观测摘要 (读已安装实例)
+export function guardStatus(agent) {
+  return agent.__guard ? agent.__guard.status() : { enabled: false };
+}

package/src/ans/lifecycle.js

@@ -0,0 +1,93 @@
+// src/ans/lifecycle.js - 生命周期状态机 (ANS)
+// 独立可更换模块: agent 只持有 Lifecycle 实例, 需要自定义阶段逻辑时替换此模块即可
+// 阶段: born → growing(首次对话) → mature(10 次对话); evolving(进化)/ reproducing(繁衍) 为累计计数
+// v1.0.7 持久化: 传入 file 时状态落盘 JSON, 跨进程/重启不归零 (P1)
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir } from "../utils/store.js";
+import { info } from "../utils/logger.js";
+
+const MATURE_CHATS = 10;   // 对话达到该次数 → mature
+const LOG_LIMIT = 50;      // 阶段日志上限 (环形)
+
+export class Lifecycle {
+  constructor({ file = null } = {}) {
+    this.file = file || null;
+    this.stage = "born";
+    this.bornAt = Date.now();
+    this.chats = 0;
+    this.evolved = 0;
+    this.reproduced = 0;
+    this.log = [];
+    this._load();
+  }
+
+  // 从磁盘恢复状态 (跨进程/重启), 文件缺失或损坏时静默用初始值
+  _load() {
+    if (!this.file) return;
+    try {
+      if (fs.existsSync(this.file)) {
+        const s = JSON.parse(fs.readFileSync(this.file, "utf8"));
+        if (s && typeof s.stage === "string" && s.stage) {
+          this.stage = s.stage;
+          this.bornAt = s.bornAt || Date.now();
+          this.chats = Number(s.chats) || 0;
+          this.evolved = Number(s.evolved) || 0;
+          this.reproduced = Number(s.reproduced) || 0;
+          this.log = Array.isArray(s.log) ? s.log.slice(-LOG_LIMIT) : [];
+        }
+      }
+    } catch { /* 损坏文件静默忽略, 用初始状态 */ }
+  }
+
+  _save() {
+    if (!this.file) return;
+    try {
+      ensureDir(path.dirname(this.file));
+      fs.writeFileSync(this.file, JSON.stringify({
+        stage: this.stage,
+        bornAt: this.bornAt,
+        chats: this.chats,
+        evolved: this.evolved,
+        reproduced: this.reproduced,
+        log: this.log.slice(-LOG_LIMIT),
+      }, null, 2), "utf8");
+    } catch {}
+  }
+
+  // 每次对话推进: born → growing → mature (计数由调用方保证每次对话调一次)
+  tick() {
+    this.chats += 1;
+    if (this.stage === "born") this.to("growing", "首次对话");
+    else if (this.stage === "growing" && this.chats >= MATURE_CHATS) this.to("mature", `完成 ${this.chats} 次对话`);
+    this._save();
+  }
+
+  // 阶段转换 (含日志), 供进化/繁衍等外部事件调用
+  to(stage, note) {
+    this.stage = stage;
+    this.log.push({ stage, note, ts: Date.now() });
+    if (this.log.length > LOG_LIMIT) this.log.shift();
+    info(`[lifecycle] ${stage}: ${note}`);
+    this._save();
+  }
+
+  // 进化计数 (refine/分享经验), 内部落盘
+  evolve(n = 1) { this.evolved += n; this._save(); }
+
+  // 繁衍计数 (spawn_agent), 内部落盘
+  reproduce(n = 1) { this.reproduced += n; this._save(); }
+
+  // 人类可读摘要 (可观测)
+  status() {
+    return {
+      stage: this.stage,
+      bornAt: new Date(this.bornAt).toISOString(),
+      ageMs: Date.now() - this.bornAt,
+      chats: this.chats,
+      evolved: this.evolved,
+      reproduced: this.reproduced,
+      recent: this.log.slice(-5),
+    };
+  }
+}