ppxans-harness 2.4.0

package/src/config/settings.js

@@ -0,0 +1,182 @@
+// src/config/settings.js - 通用设置读写 (HTTP API 后端)
+// 覆盖 config/ppx.json 顶层字段: user / channels.http / security / agent 预设 (values/system_extra/citation_rule/mode)
+// 设计 (与 providers.js 对齐):
+//   - 唯一事实源 = config/ppx.json
+//   - 写盘: 备份原文件 → 原子写 (.tmp + rename) → 防配置丢失
+//   - 读取: 深度合并默认值 (loadConfig), 保证前端总能拿到完整结构
+//   - 热重载: 写盘后由调用方调 agent.reload() 重建内存
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig, DEFAULT_CONFIG } from "./index.js";
+import { withFileLock } from "../utils/store.js";
+import { warn } from "../utils/logger.js";
+
+function getConfigPath(root) {
+  return path.join(root, "config", "ppx.json");
+}
+
+// 读取当前 config (磁盘原文), 缺文件返回空
+export function readConfigRaw(root) {
+  const p = getConfigPath(root);
+  if (!fs.existsSync(p)) return {};
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch (e) { warn("config/ppx.json 读取失败:", e.message); return {}; }
+}
+
+// 写盘: 先备份 (保留最近 3 个), 再原子写 (tmp + rename)
+function writeConfigAtomic(root, cfg) {
+  const p = getConfigPath(root);
+  if (fs.existsSync(p)) {
+    const bak = p + ".bak-" + new Date().toISOString().replace(/[:.]/g, "-");
+    try { fs.copyFileSync(p, bak); } catch (e) { warn("备份失败:", e.message); }
+    try {
+      const dir = path.dirname(p);
+      const base = path.basename(p);
+      const baks = fs.readdirSync(dir)
+        .filter((f) => f.startsWith(base + ".bak-"))
+        .map((f) => ({ f, t: fs.statSync(path.join(dir, f)).mtimeMs }));
+      baks.sort((a, b) => b.t - a.t);
+      for (const old of baks.slice(3)) {
+        try { fs.unlinkSync(path.join(dir, old.f)); } catch {}
+      }
+    } catch {}
+  }
+  const tmp = p + ".tmp";
+  fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2), "utf8");
+  fs.renameSync(tmp, p);
+}
+
+// 通用设置字段白名单 (GET 返回 + PUT 可改的顶层键)
+// 每个键对应 config 里的一个可编辑分区, 值里的字段再细分
+export const SETTINGS_FIELDS = {
+  user: ["name"],
+  http: ["port", "auth_token"],
+  security: ["allow_all", "command_timeout_ms", "code_act"],
+  agent: ["name", "mode", "citation_rule", "system_extra", "values"],
+  mcp: ["servers", "auto_connect"],
+  tools: ["disabled"],
+};
+
+// MCP 服务器字段白名单 (防注入任意字段)
+export const MCP_SERVER_KEYS = ["command", "args", "env", "prefix", "url", "headers", "timeout", "name"];
+
+// 安全视图: 抹掉敏感明文 (auth_token / api_key / mcp headers), 只暴露 set 标志
+function sanitizeSettings(cfg) {
+  const out = {
+    user: { name: cfg.user?.name || "兄弟" },
+    http: {
+      port: cfg.channels?.http?.port ?? 8899,
+      auth_token_set: !!(cfg.channels?.http?.auth_token),
+    },
+    security: {
+      allow_all: !!cfg.security?.allow_all,
+      command_timeout_ms: cfg.security?.command_timeout_ms ?? 30000,
+      code_act: !!cfg.security?.code_act,
+    },
+    agent: {
+      name: cfg.agent?.name || "皮皮虾",
+      mode: cfg.agent?.mode || "react",
+      citation_rule: cfg.agent?.citation_rule ?? "",
+      system_extra: cfg.agent?.system_extra ?? "",
+      values: Array.isArray(cfg.agent?.values) ? cfg.agent.values : (DEFAULT_CONFIG.agent?.values || []),
+    },
+    mcp: {
+      auto_connect: !!cfg.mcp?.auto_connect,
+      servers: Array.isArray(cfg.mcp?.servers) ? cfg.mcp.servers.map((s) => sanitizeMcpServer(s)) : [],
+    },
+    tools: {
+      disabled: Array.isArray(cfg.tools?.disabled) ? cfg.tools.disabled : [],
+    },
+  };
+  return out;
+}
+
+// MCP 服务器安全视图: 只暴露白名单字段, headers 抹掉明文只回 set 标志
+function sanitizeMcpServer(s) {
+  if (!s || typeof s !== "object") return {};
+  const out = {};
+  for (const k of MCP_SERVER_KEYS) {
+    if (k === "headers") {
+      if (s.headers && typeof s.headers === "object") out.headers_set = true;
+      continue;
+    }
+    if (k === "env") {
+      if (s.env && typeof s.env === "object") out.env_set = Object.keys(s.env).length > 0;
+      continue;
+    }
+    if (s[k] !== undefined) out[k] = s[k];
+  }
+  if (!out.name) out.name = s.command || s.url || "";
+  return out;
+}
+
+// GET /api/settings: 返回可编辑设置的安全视图
+export function getSettings(root) {
+  // 用 loadConfig 深合并默认值, 保证缺字段也有结构; 但 write 需基于磁盘原文避免覆盖默认
+  const merged = loadConfig(root);
+  return sanitizeSettings(merged);
+}
+
+// PUT /api/settings: 只更新白名单字段, 返回更新后的安全视图
+// patch = { user?, http?, security?, agent?, mcp?, tools? }
+// v1.0.8: patch 顶层/分区字段都按 SETTINGS_FIELDS 白名单过滤 (防注入任意字段); 写盘在文件锁内读-改-写 (防并发丢更新)
+export function updateSettings(root, patch) {
+  if (!patch || typeof patch !== "object") throw new Error("patch 必须是对象");
+  const p = getConfigPath(root);
+  return withFileLock(p, () => {
+    const cfg = readConfigRaw(root); // 锁内重读: 拿最新磁盘状态再改
+    // 只取白名单字段 (SETTINGS_FIELDS 定义每个分区可改的键)
+    const pick = (obj, keys) => {
+      const out = {};
+      for (const k of keys) if (obj && typeof obj === "object" && obj[k] !== undefined) out[k] = obj[k];
+      return out;
+    };
+    cfg.user = { ...(cfg.user || {}), ...pick(patch.user, SETTINGS_FIELDS.user) };
+    cfg.channels = cfg.channels || {};
+    cfg.channels.http = { ...(cfg.channels.http || {}), ...pick(patch.http, SETTINGS_FIELDS.http) };
+    cfg.security = { ...(cfg.security || {}), ...pick(patch.security, SETTINGS_FIELDS.security) };
+    cfg.agent = { ...(cfg.agent || {}), ...pick(patch.agent, SETTINGS_FIELDS.agent) };
+    cfg.mcp = { ...(cfg.mcp || {}), ...pick(patch.mcp, SETTINGS_FIELDS.mcp) };
+    cfg.tools = { ...(cfg.tools || {}), ...pick(patch.tools, SETTINGS_FIELDS.tools) };
+
+    // 校验
+    const port = cfg.channels.http.port;
+    if (port != null && (!Number.isInteger(port) || port < 1 || port > 65535)) throw new Error("HTTP 端口必须是 1-65535 的整数");
+    const timeout = cfg.security.command_timeout_ms;
+    if (timeout != null && (!Number.isFinite(timeout) || timeout < 1000)) throw new Error("命令超时至少 1000ms");
+    if (cfg.agent.values != null && !Array.isArray(cfg.agent.values)) throw new Error("核心价值必须是字符串数组");
+    if (cfg.agent.values && cfg.agent.values.some((v) => typeof v !== "string")) throw new Error("核心价值必须是字符串数组");
+    if (cfg.agent.mode != null && !/^[a-z-]{2,30}$/.test(String(cfg.agent.mode))) throw new Error("编排模式只含小写字母/横线");
+    // mcp.servers: 必须是对象数组, 每项至少 command 或 url, 只保留白名单字段
+    if (cfg.mcp.servers != null && !Array.isArray(cfg.mcp.servers)) throw new Error("MCP servers 必须是数组");
+    if (Array.isArray(cfg.mcp.servers)) {
+      const clean = [];
+      for (const s of cfg.mcp.servers) {
+        if (!s || typeof s !== "object") continue;
+        if (!s.command && !s.url) throw new Error("MCP 服务器至少需要 command(stdio) 或 url(http)");
+        const norm = {};
+        for (const k of MCP_SERVER_KEYS) if (s[k] !== undefined) norm[k] = s[k];
+        clean.push(norm);
+      }
+      cfg.mcp.servers = clean;
+    }
+    // tools.disabled: 必须是字符串数组
+    if (cfg.tools.disabled != null) {
+      if (!Array.isArray(cfg.tools.disabled)) throw new Error("tools.disabled 必须是字符串数组");
+      if (cfg.tools.disabled.some((t) => typeof t !== "string")) throw new Error("tools.disabled 必须是字符串数组");
+    }
+
+    writeConfigAtomic(root, cfg);
+    return sanitizeSettings(cfg);
+  });
+}
+
+// 应用 tools.disabled: 返回需要禁用的工具名列表 (供启动时/热重载时禁用)
+export function disabledTools(root) {
+  const { tools } = getSettings(root);
+  return Array.isArray(tools?.disabled) ? tools.disabled : [];
+}
+
+// 可编辑字段元数据 (供前端渲染表单, 免前端硬编码结构)
+export function settingsSchema() {
+  return SETTINGS_FIELDS;
+}

package/src/core/policy.js

@@ -0,0 +1,272 @@
+// src/core/policy.js - 工具循环执行策略 (纯逻辑, 不依赖 agent 实例)
+// 重构第一刀 (2026-09-14): 从 src/agent/index.js PPXAgent._llmWithTools 抽离。
+// 抽走: 探索熔断 / 重复命令检测 / 溢出降档 / 错误重试 / 轮次上限 / 工具结果裁剪。
+// 原则: 策略与执行分离 — agent 只负责"调 LLM、跑工具、传消息",
+//       循环何时停、降档、重试、注入方向盘, 全由本模块决策。
+//       依赖全部注入 (llm/tools/runTool/shrinkMessages/...), 无 agent 引用, 可独立测试。
+import { TOOL_ERROR_PREFIX } from "../tools/index.js";
+import { warn } from "../utils/logger.js";
+
+// ---- 阈值默认值 (config.agent.* 可覆盖) ----
+export const DEFAULT_MAX_TOOL_ROUNDS = 8;
+export const DEFAULT_TOOL_RESULT_BUDGET = 4000; // L4 toolResultBudget: 工具结果超过此长度裁剪, 防撑爆上下文
+export const DEFAULT_MAX_TOOL_ERROR_RETRY = 2;
+export const DEFAULT_OVERFLOW_SHRINK_MAX = 2;
+
+// P0③ harness 融断: 探索连击 / 重复命令 阈值 (config.agent.explore_break_limit / repeat_flag_limit 可调)
+export const DEFAULT_EXPLORE_BREAK = 3;   // 连续 3 轮只有只读/查询无产出 -> 融断
+export const DEFAULT_REPEAT_FLAG = 2;     // 同一工具+args 命中 2 次 -> 警告重复
+
+// 探索类工具集 (read-only/发现; 不算"产出或修改")
+export const EXPLORE_TOOLS = new Set([
+  "read_file", "list_dir", "web_search", "fetch_page", "memory_search", "read_document",
+  "get_time", "read_image", "ocr_image", "list_schedules", "list_capabilities", "replay_session",
+]);
+
+// 判断是否为「上下文溢出」错误 (常见信号: 消息含 context/length/token/window, 或 HTTP 400/413)
+// 注意: AbortError(用户取消/内部超时中止) 一律不算溢出, 沿用 retry.js 不重试约定。
+export function isOverflowError(e) {
+  if (!e) return false;
+  if (e.name === "AbortError" || e.code === "ABORT_ERR") return false;
+  const status = (typeof e.status === "number" ? e.status : e.statusCode) ?? null;
+  if (status === 413) return true; // 请求体过大 (content too large)
+  if (status !== null && status !== 400 && (status >= 500 || status < 400)) return false; // 服务端/非 4xx 非溢出
+  const msg = String(e?.message || e || "");
+  // 仅在消息出现上下文/长度/token 相关措辞时判为溢出, 普适 HTTP 400 不误判
+  if (status === 400) {
+    return /context|token|length|window/i.test(msg);
+  }
+  return /context\s*(size)?\s*exceeded|maximum\s*context\s*length|too\s*many\s*tokens|context\s*window|token\s*(limit|budget)|exceeds?\s*(the\s*)?(model|context|token)|insufficient\s*context/i.test(msg);
+}
+
+// LLM 调用失败的兜底提示: 附排查指引, 避免裸抛错误对用户不友好
+export function LLM_FAILED_HINT(message) {
+  return `[皮皮虾] LLM 调用失败: ${message}
+排查指引: 1) 检查 config/ppx.json 的 providers 是否配置了可用的 API key (export XXX_API_KEY=...); 2) 本地模型 (lmstudio) 是否在运行; 3) 启动 ppx-serve 看日志确认模型加载。`;
+}
+
+// L4 toolResultBudget: 裁剪超长工具结果, 保留头尾关键信息 (默认 4000, config.agent.tool_result_budget 可调)
+export function trimToolResult(r, budget = DEFAULT_TOOL_RESULT_BUDGET) {
+  const s = String(r || "");
+  if (s.length <= budget) return s;
+  const head = s.slice(0, budget * 0.7);
+  const tail = s.slice(-budget * 0.3);
+  return head + `\n...[结果已裁剪: 共 ${s.length} 字符, 保留头尾 ${budget}]...\n` + tail;
+}
+
+// 工具结果 → OpenAI 消息 content: 图片 data URL 转 image_url 块 (多模态), 否则文本裁剪
+export function toToolContent(result, budget = DEFAULT_TOOL_RESULT_BUDGET) {
+  const s = String(result || "");
+  if (/^data:image\/[a-z0-9.+-]+;base64,/i.test(s)) {
+    return [{ type: "image_url", image_url: { url: s } }];
+  }
+  return trimToolResult(s, budget);
+}
+
+// ---- 超时检测与重试 (v1.6.0 第四刀: 首个功能增量, 非等价重构) ----
+// 语义: 工具层 (seam.js runWithPolicy) 已用 AbortController 真中断底层执行 (资源超时),
+//       这里负责策略层: 超时结果识别 + 幂等工具重试一次 + tool.timeout 事件采集。
+// 边界 (最小版本): 不搞退避/熔断/自适应预算 — 留到有真实超时数据后 (第五刀) 再设计。
+// 返回: { result, elapsedMs, timedOut, retried }
+export function isTimeoutResult(r) {
+  return typeof r === "string" && r.startsWith(TOOL_ERROR_PREFIX) && r.includes("超时");
+}
+
+export async function callWithTimeoutRetry({
+  name, args, runTool,
+  isIdempotent = true,       // 幂等工具才自动重试 (避免非幂等工具副作用二次执行)
+  budgetMs = null,           // 工具超时预算 (toolTimeoutOf 注入, 事件采集用)
+  onEvent = null,
+}) {
+  const ev = (type, payload) => { if (onEvent) { try { onEvent(type, payload); } catch {} } };
+  const t0 = Date.now();
+  let result = await runTool(name, args);
+  let elapsedMs = Date.now() - t0;
+  if (!isTimeoutResult(result)) return { result, elapsedMs, timedOut: false, retried: false };
+  // 超时: 非幂等不重试 (副作用安全边界), 直接返回结构化错误
+  if (!isIdempotent) {
+    ev("tool/timeout", { tool: name, elapsedMs, budgetMs, retried: false, skippedRetry: true });
+    return { result, elapsedMs, timedOut: true, retried: false };
+  }
+  // 幂等: 重试一次
+  ev("tool/timeout", { tool: name, elapsedMs, budgetMs, retried: false });
+  const t1 = Date.now();
+  result = await runTool(name, args);
+  elapsedMs = Date.now() - t1;
+  if (isTimeoutResult(result)) {
+    ev("tool/timeout", { tool: name, elapsedMs, budgetMs, retried: true, gaveUp: true });
+    return { result, elapsedMs, timedOut: true, retried: true };
+  }
+  return { result, elapsedMs, timedOut: false, retried: true };
+}
+
+// ---- 工具循环策略状态机 ----
+// 每轮工具循环的决策都收敛到这里: 阈值从 config 读, 状态在实例内, 判定是纯方法。
+// 换策略 = 换这个类, 不动 agent 主循环。
+export class ToolLoopPolicy {
+  constructor(cfg = {}) {
+    const c = cfg || {};
+    this.maxRounds = Number(c.max_tool_rounds) || DEFAULT_MAX_TOOL_ROUNDS;
+    this.resultBudget = Number(c.tool_result_budget) || DEFAULT_TOOL_RESULT_BUDGET;
+    this.maxErrorRetry = Number(c.max_tool_error_retry) || DEFAULT_MAX_TOOL_ERROR_RETRY;
+    this.exploreBreak = Number(c.explore_break_limit) || DEFAULT_EXPLORE_BREAK;
+    this.repeatFlag = Number(c.repeat_flag_limit) || DEFAULT_REPEAT_FLAG;
+    this.overflowShrinkMax = DEFAULT_OVERFLOW_SHRINK_MAX;
+    // 运行时状态 (每轮循环实例持有, 重启归零)
+    this.errorRetries = 0;
+    this.exploreStreak = 0;
+    this.seenSig = new Map();
+    this.overflowShrinks = 0;
+  }
+
+  // 溢出判定: 是否该降档裁剪后重试 (未超降档次数上限 && 确实是溢出错误)
+  shouldShrinkOverflow(e) {
+    return this.overflowShrinks < this.overflowShrinkMax && isOverflowError(e);
+  }
+
+  // 溢出降档: 计数 +1, 返回更紧的历史预算 (逐档缩紧, 下限 200)
+  nextOverflowCap(histTokenCap) {
+    this.overflowShrinks++;
+    return Math.max(200, Math.floor(histTokenCap / (this.overflowShrinks + 1)));
+  }
+
+  // 记录本轮工具调用, 返回需要注入模型的方向盘消息 (无则 null)
+  // 两种熔断: 连续探索无产出 / 重复执行相同工具+参数
+  recordTurn(toolCalls) {
+    const called = (toolCalls || []).filter((tc) => tc.type === "function" && tc.function);
+    if (!called.length) return null;
+    let allExplore = true;
+    for (const tc of called) {
+      if (!EXPLORE_TOOLS.has(tc.function?.name || "")) { allExplore = false; break; }
+    }
+    let repeatHit = false;
+    for (const tc of called) {
+      let a = {};
+      try { a = JSON.parse(tc.function.arguments || "{}"); } catch {}
+      const sig = (tc.function?.name || "") + "::" + JSON.stringify(a).slice(0, 120);
+      this.seenSig.set(sig, (this.seenSig.get(sig) || 0) + 1);
+      if (this.seenSig.get(sig) >= this.repeatFlag) repeatHit = true;
+    }
+    if (allExplore) this.exploreStreak++; else this.exploreStreak = 0;
+    if (repeatHit) { this.exploreStreak = 0; this.seenSig.clear(); }
+    if (allExplore && this.exploreStreak >= this.exploreBreak) {
+      this.exploreStreak = 0; this.seenSig.clear();
+      return "检测到连续探索循环: 连续 " + this.exploreBreak + " 轮只有只读/查询工具, 未产生任何产出或修改。请停止继续探测, 基于已获得的信息直接给出结论或交付物; 若确实缺少关键信息, 明确说明并结束本轮, 不要空转。";
+    }
+    if (repeatHit) {
+      return "检测到重复执行相同工具与参数。请不要再重复该调用, 换一条不同路径推进, 或直接基于现有信息产出结论。";
+    }
+    return null;
+  }
+
+  // 工具错误: 是否该把错误喂回模型修正重试 (未超重试上限)
+  shouldRetryErrors(errors) {
+    if (!errors || !errors.length) return false;
+    if (this.errorRetries >= this.maxErrorRetry) return false;
+    this.errorRetries++;
+    return true;
+  }
+}
+
+// ---- 工具循环主驱动 (原 PPXAgent._llmWithTools) ----
+// 依赖全部注入, 不持有 agent 引用:
+//   seedMessages     初始消息数组 (system + history + user)
+//   llm              LLM 客户端 (apiChat)
+//   tools            OpenAI 格式工具声明数组 ([] = 禁用工具)
+//   config           完整配置 (读 config.agent.* 阈值)
+//   isInterrupted    () => boolean, 中断信号
+//   onStep           (ev) => void, 推理轮次事件
+//   runTool          (name, args) => Promise<string>, 工具执行 (trace/事件由调用方负责)
+//   shrinkMessages   (messages, budget) => messages, 溢出降档裁剪 (agent 上下文管理职责)
+//   histTokenCap     () => number, 当前历史 token 预算上限
+//   onEvent          (type, payload) => void, 可选策略事件回调 (工具失败路径: 溢出降档/熔断/错误重试/超时), 供 trace 埋点
+//   isIdempotentTool (name) => boolean, 工具是否幂等可安全重试 (默认全 true)
+//   toolTimeoutOf    (name) => number|null, 工具超时预算 (事件采集用, 默认 null)
+export async function runToolLoop({
+  seedMessages,
+  llm,
+  tools,
+  config = {},
+  isInterrupted = () => false,
+  onStep = null,
+  onEvent = null,
+  isIdempotentTool = () => true,
+  toolTimeoutOf = () => null,
+  runTool,
+  shrinkMessages,
+  histTokenCap = () => 8192,
+}) {
+  const policy = new ToolLoopPolicy(config.agent || config);
+  let messages = [...seedMessages];
+  const ev = (type, payload) => { if (onEvent) { try { onEvent(type, payload); } catch {} } };
+
+  for (let round = 0; round < policy.maxRounds; round++) {
+    if (isInterrupted()) return "[皮皮虾] 任务已被中断 (operator cancelled).";
+    if (onStep) { try { onStep({ type: "step", round, maxRounds: policy.maxRounds, ts: Date.now() }); } catch {} }
+
+    let resp;
+    try {
+      resp = await llm.apiChat(messages, {
+        tools,
+        toolRunner: async (name, args) => runTool(name, args),
+      });
+    } catch (e) {
+      // 上下文溢出: 降档裁剪历史后重发 (不影响其它错误路径 — 非溢出照常抛出,
+      // 交由上层 _llmWithFallback 切换 provider / 调用方处理)
+      if (policy.shouldShrinkOverflow(e)) {
+        const cap = policy.nextOverflowCap(histTokenCap());
+        ev("tool/overflow", { round, shrink: policy.overflowShrinks, max: policy.overflowShrinkMax });
+        warn(`上下文溢出, 降档裁剪后重试 (${policy.overflowShrinks}/${policy.overflowShrinkMax}): ${String(e?.message || e).slice(0, 120)}`);
+        messages = shrinkMessages(messages, cap);
+        continue;
+      }
+      throw e;
+    }
+
+    const msg = resp.message;
+    messages.push(msg);
+
+    const toolCalls = msg.tool_calls;
+    if (!toolCalls || toolCalls.length === 0) {
+      return msg.content || "[皮皮虾] (无回复)";
+    }
+
+    // 工具错误重试: 若本轮有工具失败, 汇总错误喂回模型修正后重试 (最多 maxErrorRetry 次)
+    const errors = [];
+    for (const tc of toolCalls) {
+      if (tc.type === "function" && tc.function) {
+        let args = {};
+        try { args = JSON.parse(tc.function.arguments || "{}"); } catch {}
+        // v1.6.0 第四刀: 超时检测 + 幂等重试一次 (tool/timeout 事件采集 P50/P95/P99 数据基础)
+        const { result } = await callWithTimeoutRetry({
+          name: tc.function.name,
+          args,
+          runTool,
+          isIdempotent: isIdempotentTool(tc.function.name),
+          budgetMs: toolTimeoutOf(tc.function.name),
+          onEvent,
+        });
+        messages.push({ role: "tool", tool_call_id: tc.id, content: toToolContent(result, policy.resultBudget) });
+        if (result.startsWith(TOOL_ERROR_PREFIX)) errors.push(result);
+      }
+    }
+    if (policy.shouldRetryErrors(errors)) {
+      ev("tool/error_retry", { round, errors: errors.length, retries: policy.errorRetries, max: policy.maxErrorRetry });
+      messages.push({
+        role: "user",
+        content: "以下工具调用失败, 请修正参数或改用其他方式后重试:\n" + errors.join("\n"),
+      });
+      continue;
+    }
+
+    // P0③ harness 融断: 探索循环 / 重复命令 (无产出的自转) → 注入方向盘给模型
+    const steer = policy.recordTurn(toolCalls);
+    if (steer) {
+      if (steer.includes("连续探索循环")) ev("tool/explore_break", { round });
+      else ev("tool/repeat_warn", { round });
+      messages.push({ role: "user", content: steer });
+      continue;
+    }
+  }
+  return "[皮皮虾] 工具调用轮次过多, 已停止。";
+}

package/src/core/trace.js

@@ -0,0 +1,89 @@
+// src/core/trace.js - 结构化事件流 (重构第三刀, 2026-09-14)
+// 目的: 给关键路径 (记忆升降级/工具失败/Agent spawn/自愈触发) 提供 traceId 贯穿的事件流,
+//       作为后续「记忆+学习服务化」重构的行为等价验证基础设施。
+// 设计:
+//   - AsyncLocalStorage (node:async_hooks 原生, 零依赖) 贯穿 traceId: 一次 chat/chatStream
+//     入口生成 traceId, 所有深层异步调用 (记忆提炼/压缩/检索/自愈/spawn) 自动继承, 无需手动传参。
+//   - EventTracer 写 data/logs/traces/events-YYYY-MM-DD.jsonl (与工具轨迹 traces/ 同目录, 独立文件),
+//     每条事件带 traceId/sessionId/seq/ts/type/payload, payload 落盘前 PII 脱敏。
+//   - span() 包装子操作自动记录耗时, 失败自动带 error。
+// 与 src/utils/trace.js (工具调用专用轨迹) 互补: 工具轨迹保留原结构不动, 事件流只做横切补充。
+import { AsyncLocalStorage } from "node:async_hooks";
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir, logicalDay } from "../utils/store.js";
+import { scrubPII } from "../utils/pii.js";
+
+const als = new AsyncLocalStorage();
+const MAX_PAYLOAD = 2000; // 单条事件载荷上限, 防爆文件
+
+export function genTraceId() {
+  return "t_" + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+}
+
+// 入口包装: 生成新 traceId, 所有异步子调用自动继承
+// meta 可带 { sessionKey, channel, userMsg } 等上下文, 存于 ALS store
+export function runWithTrace(fn, meta = {}) {
+  const store = { traceId: genTraceId(), ...meta, t0: Date.now() };
+  return als.run(store, fn);
+}
+
+// 任意深层调用取当前 traceId (无入口上下文时返回 null, 事件照记不丢)
+export function currentTrace() {
+  return als.getStore() || null;
+}
+
+// 当前 trace 是否存在 (测试用)
+export function hasTrace() {
+  return !!als.getStore();
+}
+
+// ---- 事件流写入器 (agent 构造时实例化一个, 全局复用) ----
+export class EventTracer {
+  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, `events-${day}.jsonl`); }
+
+  // 记录一条结构化事件。payload 对象落盘前序列化 + PII 脱敏。
+  // 自动附加: ts/sessionId/traceId(ALS 继承)/seq/type/durationMs(可选)
+  event(type, payload = {}, opts = {}) {
+    const store = als.getStore();
+    this.count += 1;
+    let safe = {};
+    try { safe = JSON.parse(scrubPII(JSON.stringify(payload ?? {})).cleaned); } catch { safe = { _raw: "(unserializable)" }; }
+    const entry = {
+      ts: new Date().toISOString(),
+      sessionId: this.sessionId,
+      traceId: store?.traceId || null,
+      seq: this.count,
+      type,
+      ...safe,
+    };
+    if (opts.durationMs != null) entry.durationMs = Math.round(opts.durationMs);
+    if (opts.error != null) entry.error = String(opts.error).slice(0, 500);
+    const line = JSON.stringify(entry);
+    try {
+      fs.appendFileSync(this._file(), (line.length > MAX_PAYLOAD * 4 ? line.slice(0, MAX_PAYLOAD * 4) + "…" : line) + "\n", "utf8");
+    } catch (e) { /* 事件写入失败不影响主流程 (可观测性降级不阻塞 agent) */ }
+    return entry;
+  }
+
+  // 包装子操作: 自动记录 type 事件 + 耗时, fn 抛错时事件带 error 并重抛
+  // 用法: await tracer.span("memory/extract", async () => {...})
+  async span(type, fn, payload = {}) {
+    const t0 = Date.now();
+    try {
+      const r = await fn();
+      this.event(type, { ...payload, ok: true }, { durationMs: Date.now() - t0 });
+      return r;
+    } catch (e) {
+      this.event(type, { ...payload, ok: false }, { durationMs: Date.now() - t0, error: e?.message || String(e) });
+      throw e;
+    }
+  }
+}