ppxans-harness 2.4.0

package/src/evolve/playbook.js

@@ -0,0 +1,194 @@
+// src/evolve/playbook.js - 语境 Playbook 引擎 v1 (P1④)
+// 吸收 ACE (ICLR 2026, agentic-context-engineering) 的设计思想:
+//   - 语境即 Playbook: 系统提示词 = 静态基底 + 动态 bullets 注入
+//   - 增量 delta 合并 (ADD/UPDATE/REMOVE), 非 LLM 确定性应用, 防"整体重写→语境塌缩"
+//   - grow-and-refine: 语义去重 + harmful 裁剪
+//   - 门禁回滚: 任何进化必须过回归基准才 commit, 否则自动 rollback
+// 仅借鉴思想, 源码自研。核心合并/裁剪/门禁纯代码 (可测), LLM 提炼教训走可选 adapter (无 LLM 时跳过)。
+// 与 LearningService.refine (失败→经验库) 互补: refine 沉淀经验, playbook 反哺系统提示词 (零 token 成本时为空)。
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir, readText, writeText } from "../utils/store.js";
+
+// ---- 词法相似度 (grow-and-refine 用, 零依赖) ----
+// 英文/空格分隔 → 词级 Jaccard; 中文等 CJK 连续串 → 字符 bigram Dice (单 token 时退化)。
+// 这样"失败后查看审计链" 与 "失败后查看审计链重试" 也能算出高相似度。
+export function lexicalSimilarity(a, b) {
+  const ta = String(a || "");
+  const tb = String(b || "");
+  if (!ta || !tb) return 0;
+  const tokensA = tokenize(ta);
+  const tokensB = tokenize(tb);
+  return diceSet(tokensA, tokensB);
+}
+
+function tokenize(s) {
+  const words = s.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+  // 有词分隔: 用词级
+  if (words.length > 1) return words;
+  // 无分隔 (中文连续串): 用字符 bigram (含单字符兜底)
+  const chars = s.replace(/\s+/g, "").toLowerCase();
+  const bigrams = [];
+  for (let i = 0; i < chars.length - 1; i++) bigrams.push(chars.slice(i, i + 2));
+  if (bigrams.length) return bigrams;
+  return chars.split("");
+}
+
+function diceSet(A, B) {
+  const setA = new Set(A);
+  const setB = new Set(B);
+  if (!setA.size || !setB.size) return 0;
+  let inter = 0;
+  for (const w of setA) if (setB.has(w)) inter++;
+  return (2 * inter) / (setA.size + setB.size);
+}
+
+// ---- delta 操作 (确定性合并, 非 LLM) ----
+// ops: [{ op:'ADD', kind, content, evidence_ref? } | { op:'UPDATE', id, content, counters? } | { op:'REMOVE', id }]
+// 返回 { playbook, applied, rejected: [{op, reason}] }
+export function applyDelta(playbook, ops = [], { maxBullets = 200 } = {}) {
+  const pb = clonePlaybook(playbook);
+  const applied = [];
+  const rejected = [];
+  for (const op of ops) {
+    if (!op || !op.op) { rejected.push({ op, reason: "缺 op 字段" }); continue; }
+    if (op.op === "ADD") {
+      const content = String(op.content || "").trim();
+      if (!content) { rejected.push({ op, reason: "ADD 缺内容" }); continue; }
+      // 新增前查重: 与已有 bullet 词法相似 > 0.6 视为重复, 拒收 (grow-and-refine)
+      const dup = pb.bullets.find((b) => lexicalSimilarity(b.content, content) > 0.6);
+      if (dup) { rejected.push({ op, reason: "重复: " + dup.id }); continue; }
+      const id = op.id || ("b" + Date.now().toString(36) + Math.random().toString(36).slice(2, 5));
+      const kind = ["strategy", "pitfall", "domain"].includes(op.kind) ? op.kind : "strategy";
+      pb.bullets.push({ id, kind, content, counters: { helpful: 0, harmful: 0 }, evidence_ref: op.evidence_ref || null, createdAt: Date.now() });
+      applied.push({ op: "ADD", id });
+    } else if (op.op === "UPDATE") {
+      const b = pb.bullets.find((x) => x.id === op.id);
+      if (!b) { rejected.push({ op, reason: "UPDATE 未知 id: " + op.id }); continue; }
+      if (op.content && String(op.content).trim() !== b.content) {
+        b.content = String(op.content).trim();
+        b.updatedAt = Date.now();
+      }
+      if (op.evidence_ref) b.evidence_ref = op.evidence_ref;
+      if (op.counters) {
+        b.counters.helpful += Number(op.counters.helpful) || 0;
+        b.counters.harmful += Number(op.counters.harmful) || 0;
+      }
+      applied.push({ op: "UPDATE", id: op.id });
+    } else if (op.op === "REMOVE") {
+      const i = pb.bullets.findIndex((x) => x.id === op.id);
+      if (i < 0) { rejected.push({ op, reason: "REMOVE 未知 id: " + op.id }); continue; }
+      pb.bullets.splice(i, 1);
+      applied.push({ op: "REMOVE", id: op.id });
+    } else {
+      rejected.push({ op, reason: "未知 op: " + op.op });
+    }
+  }
+  // 容量保护: 超上限裁剪最弱 (harmful 最高) bullets —— 保留质量高 (harmful-净额小) 的在前
+  if (pb.bullets.length > maxBullets) {
+    pb.bullets.sort((a, b) => (a.counters.harmful - a.counters.helpful) - (b.counters.harmful - b.counters.helpful));
+    pb.bullets = pb.bullets.slice(0, maxBullets);
+  }
+  return { playbook: pb, applied, rejected };
+}
+
+// ---- grow-and-refine: 去重 + 裁剪 ----
+// harmful - helpful >= pruneAt 的 bullet 移除 (持续有害的策略自动淘汰)
+export function growAndRefine(playbook, { pruneAt = 3 } = {}) {
+  const pb = clonePlaybook(playbook);
+  const pruned = [];
+  const before = pb.bullets.length;
+  pb.bullets = pb.bullets.filter((b) => {
+    const net = b.counters.harmful - b.counters.helpful;
+    if (net >= pruneAt) { pruned.push({ id: b.id, net }); return false; }
+    return true;
+  });
+  return { playbook: pb, pruned, removed: before - pb.bullets.length };
+}
+
+// ---- 门禁: 进化必须过回归基准才 commit, 否则 rollback ----
+// gate(check: (playbook)=>boolean|Promise<boolean>) — 基准通过返回 true 才落盘
+export function createGate(regressionCheck, { onReject = null } = {}) {
+  return {
+    async commit(store, playbook, ops, meta = {}) {
+      const pass = typeof regressionCheck === "function" ? await regressionCheck(playbook) : true;
+      if (!pass) {
+        // 回滚: 不落盘, 保留原 playbook
+        onReject?.(playbook, meta);
+        return { committed: false, reason: "回归基准未通过", applied: [] };
+      }
+      store.save(playbook);
+      return { committed: true, applied: ops };
+    },
+  };
+}
+
+// ---- 渲染: bullets -> 注入串 (空时返回空串, 零 token 成本) ----
+export function renderBullets(playbook, { maxBullets = 30 } = {}) {
+  const bullets = (playbook?.bullets || []).slice(0, maxBullets);
+  if (!bullets.length) return "";
+  const lines = bullets.map((b, i) => `${i + 1}. [${b.kind}] ${b.content}`);
+  return `\n# 经验策略 (Playbook, 基于过往实践)\n${lines.join("\n")}\n`;
+}
+
+// ---- 存储 ----
+export class PlaybookStore {
+  constructor(dataDir) {
+    this.dir = path.join(dataDir, "evolve");
+    ensureDir(this.dir);
+    this.file = path.join(this.dir, "playbook.json");
+    this._playbook = this._load();
+  }
+
+  _load() {
+    try {
+      if (fs.existsSync(this.file)) {
+        const d = JSON.parse(fs.readFileSync(this.file, "utf8"));
+        if (d && Array.isArray(d.bullets)) return d;
+      }
+    } catch {}
+    return { base: "", bullets: [], version: 1 };
+  }
+
+  get playbook() { return this._playbook; }
+
+  setBase(text) {
+    this._playbook.base = String(text || "");
+    return this;
+  }
+
+  save(pb = this._playbook) {
+    this._playbook = pb;
+    writeText(this.file, JSON.stringify(pb, null, 2));
+    return pb;
+  }
+
+  // 便捷: 应用 delta + 门禁
+  async apply(ops, { gate = null, maxBullets } = {}) {
+    const { playbook: next, applied, rejected } = applyDelta(this._playbook, ops, { maxBullets });
+    if (gate) {
+      const r = await gate.commit(this, next, ops);
+      return { ...r, rejected };
+    }
+    this.save(next);
+    return { committed: true, applied, rejected };
+  }
+}
+
+function clonePlaybook(pb) {
+  return {
+    base: pb?.base || "",
+    version: pb?.version || 1,
+    bullets: (pb?.bullets || []).map((b) => ({
+      id: b.id,
+      kind: b.kind,
+      content: b.content,
+      counters: { helpful: b.counters?.helpful || 0, harmful: b.counters?.harmful || 0 },
+      evidence_ref: b.evidence_ref || null,
+      createdAt: b.createdAt,
+      updatedAt: b.updatedAt,
+    })),
+  };
+}
+
+export default PlaybookStore;

package/src/llm/client.js

@@ -0,0 +1,446 @@
+// src/llm/client.js - LLM 客户端
+// 后端两种模式:
+//   backend="openclaw" : 通过 `openclaw agent` CLI 驱动 OpenClaw 引擎 (底座=OpenClaw)
+//   backend="http"     : 直接 OpenAI 兼容 HTTP API (零依赖, 用 fetch)  [默认]
+import { spawn } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { info, warn } from "../utils/logger.js";
+import { estimateTokens, truncateByTokens } from "../utils/text.js";
+import { buildFencePrompt, proxyToolLoop, parseToolCalls } from "./fence.js";
+import { withRetry } from "./retry.js";
+
+const PPX_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+// DeepSeek Harness 已内嵌到 ppx-agent/.deps/deepseek-harness；仍可用 PPX_DSH_ROOT 覆盖。
+const DEFAULT_DSH_ROOT = process.env.PPX_DSH_ROOT || path.join(PPX_ROOT, ".deps", "deepseek-harness");
+const DEFAULT_MJS = process.env.PPX_OPENCLAW_MJS || "";
+
+// 纯函数: 校验 Node 版本是否满足 OpenClaw 引擎要求 (>=22.22.3 / >=24.15 / >=25.9, 且 23 与 24.0-24.14 不支持)
+export function nodeVersionOk(version) {
+  const v = String(version).split(".").map(Number);
+  const [maj, min, pat] = v;
+  return (maj === 22 && (min > 22 || (min === 22 && pat >= 3))) ||
+         (maj === 24 && min >= 15) ||
+         (maj === 25 && min >= 9) || maj > 25;
+}
+export class LLMClient {
+  constructor(provider) {
+    this.providerId = provider.id || "openclaw";
+    // 后端选择: 显式 backend=openclaw, 或 id=openclaw
+    this.backend = provider.backend === "openclaw" || provider.id === "openclaw" ? "openclaw"
+      : provider.backend === "deepseek" || provider.backend === "dsh" || provider.id === "dsh" ? "deepseek"
+      : "http";
+    this.baseUrl = (provider.base_url || "").replace(/\/$/, "");
+    this.apiKey = provider.api_key || process.env[provider.api_key_env] || "";
+    this.apiKeyEnvName = provider.api_key_env || ""; // 供缺失 key 报错时提示应设置的环境变量名
+    this.model = provider.model || provider.models?.chat || "gpt-4o-mini";
+    this.vision = !!provider.vision; // 是否支持多模态 (视觉) — 标记后才会注入图片到 user 消息
+    // 上下文窗口 (token): 供 agent 据此收紧会话历史预算, 防止本地小模型溢出。
+    // 可选字段, provider 未配置时用保守默认 8192 (绝不因未知窗口放大历史)。
+    this.context_window = Number(provider.context_window) || Number(provider.models?.context_window) || 8192;
+    this.timeoutMs = provider.timeout_ms || 120000;
+    this.retryMax = provider.retry_max ?? 3; // 单次调用内瞬态错误重试次数 (429/5xx/timeout)
+    // openclaw 后端专用
+    this.mjs = provider.mjs || DEFAULT_MJS;
+    this.sessionKey = provider.session_key || "ppx:main";
+    const dshRoot = process.env.PPX_DSH_ROOT || provider.dsh_root || DEFAULT_DSH_ROOT;
+    this.dshRoot = path.isAbsolute(dshRoot) ? dshRoot : path.resolve(PPX_ROOT, dshRoot);
+    this._tmpCounter = 0;
+    if (this.backend === "openclaw") info(`LLMClient[${this.providerId}] backend=openclaw mjs=${this.mjs} session=${this.sessionKey}`);
+  }
+
+  // ===== OpenClaw 后端异步版 (async spawn, 不阻塞事件循环) ====
+  async _openclawChatAsync(messages) {
+    this._openclawReadyOrThrow();
+    const lastUser = [...messages].reverse().find(m => m && (m.role === "user"));
+    const text = lastUser?.content || "";
+    const tmp = path.join(os.tmpdir(), `ppx_msg_${Date.now()}_${this._tmpCounter++}.txt`);
+    fs.writeFileSync(tmp, String(text), "utf8");
+    try {
+      const args = [
+        this.mjs, "agent",
+        "--session-key", this.sessionKey,
+        "--message-file", tmp,
+        "--json",
+        "--timeout", String(Math.floor(this.timeoutMs / 1000)),
+      ];
+      const stdout = await new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, args, { stdio: ["ignore", "pipe", "pipe"] });
+        let out = "", err = "";
+        child.stdout.on("data", d => out += d);
+        child.stderr.on("data", d => err += d);
+        child.on("error", reject);
+        child.on("close", code => {
+          if (code !== 0) reject(this._translateOpenclawError(new Error(`openclaw 退出 code=${code}: ${err.slice(-500)}`)));
+          else resolve(out);
+        });
+      });
+      const j = JSON.parse(stdout);
+      if (j.status && j.status !== "ok") throw new Error(`[皮皮虾] OpenClaw 执行状态异常 (status=${j.status})`);
+      const payloads = j?.result?.payloads || [];
+      const content = payloads.map(p => p?.text || "").filter(Boolean).join("\n");
+      if (!content) {
+        const alt = j?.result?.meta?.finalAssistantVisibleText;
+        if (alt) return { content: alt, usage: null };
+        throw new Error("OpenClaw 返回空内容 (runId=" + (j.runId ?? "?") + ")");
+      }
+      return { content, usage: null, meta: { engine: "openclaw", runId: j.runId } };
+    } finally {
+      try { fs.rmSync(tmp, { force: true }); } catch {}
+    }
+  }
+
+  // ===== DeepSeek Harness 后端 (dsh headless 一次性运行器) ====
+  // 两种形态:
+  //   built: dsh npm 包已安装 (dshRoot/lib/bin.js) — 零构建, 直接跑, 优先
+  //   src:   dsh 源码树 (dshRoot/apps/cli/src/bin.ts + node_modules/tsx) — 内嵌 .deps 形态
+  _dshResolveBin() {
+    const built = path.join(this.dshRoot, "lib", "bin.js");
+    if (fs.existsSync(built)) return { kind: "built", bin: built };
+    const src = path.join(this.dshRoot, "apps", "cli", "src", "bin.ts");
+    if (fs.existsSync(src)) return { kind: "src", bin: src };
+    return null;
+  }
+
+  _dshReadyOrThrow() {
+    const r = this._dshResolveBin();
+    if (!r) {
+      throw new Error("[皮皮虾] dsh 未就绪: " + this.dshRoot + " 下找不到 lib/bin.js (已安装 dsh npm 包) 或 apps/cli/src/bin.ts (dsh 源码)。\n请设置 PPX_DSH_ROOT 指向 dsh 安装目录，或 clone deepseek-harness 到 .deps/deepseek-harness 后运行 npm run dsh:install。");
+    }
+    if (r.kind === "src" && !fs.existsSync(path.join(this.dshRoot, "node_modules", "tsx"))) {
+      throw new Error("[皮皮虾] dsh 源码形态依赖未安装: " + this.dshRoot + "/node_modules/tsx 不存在。\n请先运行 npm run dsh:install（等价于 cd .deps/deepseek-harness && pnpm install），或将 PPX_DSH_ROOT 指向已安装的 dsh npm 包目录。");
+    }
+  }
+
+  // 驱动 `node <dsh bin> --profile headless "<task>"`,
+  // stdout = 最终助手文本, exit 0 = turn 完成, 1 = 出错(stderr 带错误)
+  async _dshChatAsync(messages) {
+    this._dshReadyOrThrow();
+    const lastUser = [...messages].reverse().find(m => m && m.role === "user");
+    const text = lastUser?.content || "";
+    const r = this._dshResolveBin();
+    const args = r.kind === "built"
+      ? [r.bin, "--profile", "headless", text]
+      : ["--import", "tsx/esm", "apps/cli/src/bin.ts", "--profile", "headless", text];
+    const stdout = await new Promise((resolve, reject) => {
+      const child = spawn(process.execPath, args, { cwd: this.dshRoot, stdio: ["ignore", "pipe", "pipe"] });
+      let out = "", err = "";
+      child.stdout.on("data", d => out += d);
+      child.stderr.on("data", d => err += d);
+      child.on("error", reject);
+      child.on("close", code => {
+        if (code !== 0) reject(new Error(`dsh 退出 code=${code}: ${err.slice(-500)}`));
+        else resolve(out);
+      });
+    });
+    const content = stdout.trim();
+    if (!content) throw new Error("dsh 返回空内容");
+    return { content, usage: null, meta: { engine: "deepseek-harness" } };
+  }
+
+  // 原生 chat (无工具)
+  // timeoutMs/retryMax: 可选覆盖 provider 默认 (辅助调用传短超时+禁重试快速失败, 见 AUX_TIMEOUT_MS)
+  async chat(messages, { temperature = 0.7, maxTokens = 2048, timeoutMs, retryMax } = {}) {
+    if (this.backend === "openclaw") {
+      const r = await this._openclawChatAsync(messages);
+      return { content: r.content, usage: r.usage };
+    }
+    if (this.backend === "deepseek") {
+      const r = await this._dshChatAsync(messages);
+      return { content: r.content, usage: r.usage };
+    }
+    const data = await this._request("/chat/completions", { model: this.model, messages, temperature, max_tokens: maxTokens }, { timeoutMs, retryMax });
+    const m1 = data?.choices?.[0]?.message;
+    let content = m1?.content;
+    // 本地推理模型兜底: thinking 吃满 token 时 content 为空, 用 reasoning_content 降级, 避免误判"断线/失败"并写入污染记忆
+    if (!content && m1?.reasoning_content) content = "[思考] " + m1.reasoning_content;
+    if (!content) throw new Error("LLM 返回空内容");
+    return { content, usage: data?.usage };
+  }
+
+  // API chat (支持工具调用), 返回完整 message (含 tool_calls)
+  async apiChat(messages, { tools = [], temperature = 0.7, maxTokens = 4096, toolRunner = null, timeoutMs, retryMax } = {}) {
+    if (this.backend === "openclaw") {
+      // OpenClaw 引擎是外部进程, 无法直接调用 PPX 内部工具。
+      // 若提供 toolRunner, 走围栏代理循环: 引擎以纯 LLM 输出工具意图, PPX 解析执行。
+      // 否则退化纯 LLM (引擎自带工具循环, 只回最终文本)。
+      if (toolRunner && tools.length) return this._proxyChat(messages, { tools, toolRunner, engine: "openclaw" });
+      const r = await this._openclawChatAsync(messages);
+      return { message: { role: "assistant", content: r.content, tool_calls: null }, usage: r.usage };
+    }
+    if (this.backend === "deepseek") {
+      if (toolRunner && tools.length) return this._proxyChat(messages, { tools, toolRunner, engine: "deepseek" });
+      const r = await this._dshChatAsync(messages);
+      return { message: { role: "assistant", content: r.content, tool_calls: null }, usage: r.usage };
+    }
+    const body = { model: this.model, messages, temperature, max_tokens: maxTokens };
+    if (tools.length) body.tools = tools;
+    const data = await this._request("/chat/completions", body, { timeoutMs, retryMax });
+    const message = data?.choices?.[0]?.message;
+    if (!message) throw new Error("LLM 返回空 message");
+    let toolCalls = message.tool_calls || null;
+    let content = message.content || null;
+    // 本地推理模型兜底: 无正文且无工具调用时, 用 reasoning_content 降级(避免误判断线/失败并写入污染记忆)
+    if (!content && !toolCalls?.length && message.reasoning_content) {
+      content = "[思考] " + message.reasoning_content;
+      toolCalls = null;
+    }
+    // 纯文本工具调用修复 (吸收 OpenClaw tool-call-repair):
+    // 部分模型(本地/DSML)返回文本工具意图而非原生 tool_calls, 从文本恢复
+    if (tools.length && (!toolCalls || !toolCalls.length) && typeof content === "string" && content) {
+      const parsed = parseToolCalls(content);
+      if (parsed.calls.length) {
+        toolCalls = parsed.calls.map((c) => ({
+          id: c.id,
+          type: "function",
+          function: { name: c.function.name, arguments: c.function.arguments },
+        }));
+        content = parsed.clean || null;
+      }
+    }
+    return {
+      message: {
+        role: message.role || "assistant",
+        content,
+        tool_calls: toolCalls,
+      },
+      usage: data?.usage,
+    };
+  }
+
+  // 围栏代理循环: 把工具清单注入, 引擎以纯 LLM 输出工具意图, PPX 执行 [P0#1]
+  // 围栏上下文 token 预算 (v0.6.6 优化: 替代固定 800/400 字符截断)
+  // 按 token 预算动态分配: persona 优先 40%, 历史按"最新优先 + 信息量"分配剩余 60%
+  static get FENCE_CTX_TOKEN_BUDGET() { return 2400; }
+  static get FENCE_PERSONA_RATIO() { return 0.4; }
+  static get FENCE_HIST_BUDGET() { return 2400 * 0.6; }
+  // 信息量启发: 含指令/数字/路径/结论的轮次更该保留
+  static _histPriority(m) {
+    const s = String(m?.content || "");
+    let p = 0;
+    if (/[查|算|写|建|改|创建|删除|修复|总结|分析|配置|执行|运行|启动|停止|提交|部署|安装|生成|编译|测试]/.test(s)) p += 2;
+    if (/[0-9]{2,}/.test(s)) p += 1;
+    if (/\.(js|py|md|json|txt|ts|go)\b|[:\\\/][A-Za-z]/.test(s)) p += 2;
+    if (/失败|错误|报错|异常|成功|完成|结果|结论|决定|方案/.test(s)) p += 2;
+    if (/^(你好|hi|hello|在吗|谢谢|好的|嗯|是的|对|收到|再见)/i.test(s.trim())) p -= 3;
+    return p;
+  }
+  async _proxyChat(messages, { tools, toolRunner, engine }) {
+    const fencePrompt = buildFencePrompt(tools);
+    // 保留 system/persona 设定 + 最近历史, 避免外部引擎只见"当前问题" [复审 P2]
+    const systemMsg = messages.find((m) => m && m.role === "system");
+    const nonSys = messages.filter((m) => m && m.role !== "system");
+    // person 预算: 固定 40%, 截断到预算内
+    const persona = systemMsg?.content
+      ? "角色设定:\n" + truncateByTokens(systemMsg.content, LLMClient.FENCE_CTX_TOKEN_BUDGET * LLMClient.FENCE_PERSONA_RATIO)
+      : null;
+    // 历史预算: 剩余 60% 按"最新优先 + 信息量"分配
+    const histBudget = LLMClient.FENCE_HIST_BUDGET;
+    let histLines = [], used = 0;
+    // 1) 最新 6 条按时间倒序, 优先保留(信息量高或最新)
+    const recent = nonSys.slice(-6);
+    for (let i = recent.length - 1; i >= 0; i--) {
+      const m = recent[i];
+      const line = (m.role === "user" ? "用户" : "助手") + ": " + String(m.content || "");
+      const t = estimateTokens(line);
+      if (used + t > histBudget) continue; // 超预算跳过(不截断硬塞)
+      histLines.push(line); used += t;
+    }
+    // 2) 若预算还有余量, 补更早的高信息量轮次
+    const older = nonSys.slice(0, Math.max(0, nonSys.length - 6));
+    for (let i = older.length - 1; i >= 0; i--) {
+      const m = older[i];
+      if (LLMClient._histPriority(m) < 2) continue; // 只补高信息量
+      const line = (m.role === "user" ? "用户" : "助手") + ": " + String(m.content || "");
+      const t = estimateTokens(line);
+      if (used + t > histBudget) break;
+      histLines.push(line); used += t;
+    }
+    histLines.reverse(); // 恢复时间正序
+    const ctx = [persona, histLines.length ? histLines.join("\n") : null].filter(Boolean).join("\n\n");
+    const combined = fencePrompt + "\n\n[上下文]\n" + ctx;
+    const finalText = await proxyToolLoop(
+      async (context) => {
+        // 每条消息: 围栏协议 + 任务 + 累积工具结果
+        const msg = context ? combined + "\n\n" + context : combined;
+        if (engine === "openclaw") {
+          const r = await this._openclawChatAsync([{ role: "user", content: msg }]);
+          return r.content;
+        }
+        const r = await this._dshChatAsync([{ role: "user", content: msg }]);
+        return r.content;
+      },
+      toolRunner,
+      { maxRounds: 8 }
+    );
+    return { message: { role: "assistant", content: finalText, tool_calls: null }, usage: null };
+  }
+
+  // 辅助 LLM 调用短超时 (毫秒): 压缩/提炼/扩展/经验 等非主对话调用, 快速失败降级, 避免 120s 卡死
+  // 使用场景: 模型未运行/网络不通时, 主对话靠 localIntent 或回退, 辅助调用不应阻塞主流程
+  static get AUX_TIMEOUT_MS() { return 10000; }
+
+  async _request(path, jsonBody, { timeoutMs, retryMax } = {}) {
+    if (!this.apiKey) throw new Error(`[皮皮虾] LLM 缺少 API key (env=${this.apiKeyEnvName || "?"})`);
+    const url = `${this.baseUrl}${path}`;
+    const ms = timeoutMs || this.timeoutMs;
+    // 辅助调用 (压缩/提炼/扩展等) 传 retryMax:0 禁重试: 短超时 + 不重试 = 快速失败降级, 不阻塞主流程
+    const maxRetries = retryMax === undefined ? this.retryMax : retryMax;
+    const doFetch = async () => {
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), ms);
+      try {
+        const resp = await fetch(url, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", "Authorization": `Bearer ${this.apiKey}` },
+          body: JSON.stringify(jsonBody),
+          signal: ctrl.signal,
+        });
+        if (!resp.ok) {
+          const text = await resp.text().catch(() => "");
+          const e = new Error(`LLM HTTP ${resp.status}: ${text.slice(0, 300)}`);
+          e.status = resp.status; // 结构化状态码, 供 retry.isTransientError 分类
+          throw e;
+        }
+        return await resp.json();
+      } finally {
+        clearTimeout(timer);
+      }
+    };
+    // 瞬态错误(429/5xx/timeout)单次调用内重试, 非瞬态(400/401/403)立即抛给上层 provider 回退
+    return withRetry(doFetch, { maxRetries });
+  }
+
+  // 是否支持逐字流式: 仅直连 HTTP API 后端 (openclaw/deepseek 为外部进程, 一次性返回) [复审 P2]
+  get supportsStream() { return this.backend !== "openclaw" && this.backend !== "deepseek"; }
+
+  // 是否支持原生 tool_calls: 仅 http 后端 (OpenAI 兼容 API)。
+  // openclaw 是完整 agent 运行时, 拒绝 PPX 的围栏协议(视为伪协议); dsh 走文本围栏。
+  // 工具类任务应优先路由到支持原生 tool_calls 的后端 (实测 LM Studio 原生 tool_calls 全链路通过)。
+  get supportsNativeToolCalls() { return this.backend === "http"; }
+
+  // openclaw 后端: 启动前校验 Node 版本, 不满足则抛中文引导错误 (而非原始报错)
+  _openclawReadyOrThrow() {
+    if (!nodeVersionOk(process.versions.node)) {
+      throw new Error("[皮皮虾] 当前 Node v" + process.versions.node + " 不满足 OpenClaw 引擎要求。\n请升级 Node 至 >=22.22.3 (推荐 26.x)；注意 Node 23 与 24.0-24.14 不支持。\n或改用 http 后端配置 API key 直连。");
+    }
+    if (!this.mjs || !fs.existsSync(this.mjs)) {
+      throw new Error("[皮皮虾] OpenClaw 引擎未就绪: mjs 路径不存在 (" + this.mjs + ")。\n请设置环境变量 PPX_OPENCLAW_MJS 指向 openclaw.mjs，或在 config/ppx.json 的 openclaw provider 里填 mjs 字段。");
+    }
+  }
+
+  // 翻译 openclaw CLI 的版本类报错为中文引导
+  _translateOpenclawError(e) {
+    const msg = String((e && e.message) || e);
+    if (/Node\.js >= \d+\.\d+\.\d+/.test(msg) || /engines|不满足引擎要求/.test(msg)) {
+      return new Error("[皮皮虾] OpenClaw 引擎要求更高的 Node 版本，请升级 Node 至 >=22.22.3 (推荐 26.x) 后重试。原始信息: " + msg.slice(0, 200));
+    }
+    return e;
+  }
+  // ===== Provider 健康探测 (Harness 化: 并发探测可用性, 支持快速失败) =====
+  // openclaw 后端: 校验本地 Node 版本是否满足引擎要求 (>=22.22.3 / >=24.15 / >=25.9)
+  // http 后端: 快速探测 /models (3s 超时), 不发完整请求
+  async health() {
+    if (this.backend === "openclaw") {
+      const okNode = nodeVersionOk(process.versions.node);
+      const okMjs = !!this.mjs && fs.existsSync(this.mjs);
+      const ok = okNode && okMjs;
+      if (!okNode) info("[health] openclaw 不可用: Node v" + process.versions.node + " 不满足引擎要求");
+      if (okNode && !okMjs) info("[health] openclaw 不可用: mjs 路径不存在 (" + this.mjs + ")，请设置 PPX_OPENCLAW_MJS");
+      return ok;
+    }
+    if (this.backend === "deepseek") {
+      const r = this._dshResolveBin();
+      if (!r) {
+        info("[health] deepseek 不可用: dsh 未就绪 " + this.dshRoot + " (缺 lib/bin.js 或 apps/cli/src/bin.ts)");
+        return false;
+      }
+      if (r.kind === "src" && !fs.existsSync(path.join(this.dshRoot, "node_modules", "tsx"))) {
+        info("[health] deepseek 不可用: dsh 源码形态依赖未安装 (请运行 npm run dsh:install 或设 PPX_DSH_ROOT)");
+        return false;
+      }
+      return nodeVersionOk(process.versions.node);
+    }
+    if (!this.apiKey) return false;
+    try {
+      const ctrl = new AbortController();
+      const t = setTimeout(() => ctrl.abort(), 3000);
+      const r = await fetch(this.baseUrl + "/models", {
+        headers: { "Authorization": "Bearer " + this.apiKey },
+        signal: ctrl.signal,
+      });
+      clearTimeout(t);
+      return r.ok;
+    } catch (e) {
+      warn("[health] " + this.providerId + " 探测失败:", e.message);
+      return false;
+    }
+  }
+
+
+  // 流式 chat: 逐块回调 (SSE), 返回累积文本
+  // onDelta(content) 每次增量, onDone(full) 结束
+  async streamChat(messages, { temperature = 0.7, maxTokens = 4096, onDelta, signal } = {}) {
+    if (this.backend === "openclaw") {
+      // OpenClaw CLI 非流式: 一次性返回全文 (先可用, 后续可切 SSE)
+      const r = await this._openclawChatAsync(messages);
+      if (onDelta) onDelta(r.content);
+      return r.content;
+    }
+    if (this.backend === "deepseek") {
+      // dsh headless 非流式: 一次性返回全文
+      const r = await this._dshChatAsync(messages);
+      if (onDelta) onDelta(r.content);
+      return r.content;
+    }
+    if (!this.apiKey) throw new Error(`[皮皮虾] LLM 缺少 API key`);
+    const url = `${this.baseUrl}/chat/completions`;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    const extSig = signal || null;
+    if (extSig) extSig.addEventListener("abort", () => ctrl.abort());
+    let full = "";
+    try {
+      const resp = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "Authorization": `Bearer ${this.apiKey}` },
+        body: JSON.stringify({ model: this.model, messages, temperature, max_tokens: maxTokens, stream: true }),
+        signal: ctrl.signal,
+      });
+      if (!resp.ok) {
+        const txt = await resp.text().catch(() => "");
+        throw new Error(`LLM HTTP ${resp.status}: ${txt.slice(0, 300)}`);
+      }
+      if (!resp.body) { throw new Error("响应无 body, 不支持流式"); }
+      const reader = resp.body.getReader();
+      const decoder = new TextDecoder();
+      let buf = "";
+      let streamDone = false; // 独立结束信号, 不污染 reader.read() 的 done
+      while (!streamDone) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        // 按行解析 SSE
+        let idx;
+        while (!streamDone && (idx = buf.indexOf("\n")) !== -1) {
+          const line = buf.slice(0, idx).trim().replace(/\r$/, "");
+          buf = buf.slice(idx + 1);
+          if (!line.startsWith("data:")) continue;
+          const data = line.slice(5).trim();
+          // 官方结束信号: 仅匹配空格式的 "data: [DONE]", 不做 buf 全文搜防误截
+          if (data === "[DONE]") { streamDone = true; break; }
+          try {
+            const j = JSON.parse(data);
+            const delta = j.choices?.[0]?.delta?.content;
+            if (delta) { full += delta; onDelta && onDelta(delta); }
+          } catch {}
+        }
+      }
+      return full;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}