ppxans-harness 2.4.0 → 3.2.0

package/src/services/diagnose.js

@@ -0,0 +1,180 @@
+// src/services/diagnose.js - Agent 自诊断 (2026-10-03, "按症状下药"表自动化)
+// 数据源全部为本地白盒: 审计哈希链 (工具调用 ok/error/ms) + 失败案例库 + 使用统计 + 任务基线。
+// 输出: 症状 → 根因 → 增强动作 (对齐强化框架的按症状下药表), 零 LLM 参与, 确定性可复现。
+import fs from "node:fs";
+import path from "node:path";
+import { auditFile } from "../audit/audit-chain.js";
+import { summarizeCauses } from "./triage.js";
+import { debug } from "../utils/logger.js";
+
+function readJson(p, fallback) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return fallback; }
+}
+
+// 读审计链最近 maxLines 条, 聚合出工具级信号
+function readAuditSignals(dataDir, maxLines = 5000) {
+  const file = auditFile(dataDir);
+  let lines = [];
+  try { lines = fs.readFileSync(file, "utf8").trim().split("\n").filter(Boolean); } catch { return null; }
+  lines = lines.slice(-maxLines);
+  const calls = [];
+  for (const line of lines) {
+    try { calls.push(JSON.parse(line)); } catch (e) { debug(`[services/diagnose] 已忽略异常: ${e && e.message ? e.message : e}`); }
+  }
+  if (!calls.length) return null;
+  const byTool = new Map(); // tool -> {calls, fails, errors:{}}
+  let paramErrors = 0, policyBlocks = 0, timeouts = 0;
+  for (const c of calls) {
+    const t = byTool.get(c.tool) || { calls: 0, fails: 0 };
+    t.calls++;
+    if (!c.ok) {
+      t.fails++;
+      const err = String(c.error || "");
+      if (err.includes("参数错误")) paramErrors++;
+      else if (err.includes("策略拦截") || err.includes("权限") || err.includes("审批")) policyBlocks++;
+      else if (/超时|timeout/i.test(err)) timeouts++;
+    }
+    byTool.set(c.tool, t);
+  }
+  return { file, total: calls.length, byTool, paramErrors, policyBlocks, timeouts };
+}
+
+export function diagnoseAgent({ dataDir, rootDir = null, usageStats = null, health = null, topPerFinding = 3 } = {}) {
+  const findings = [];
+  const signals = {};
+
+  // 1. 审计链信号
+  const audit = readAuditSignals(dataDir);
+  signals.audit = audit ? { total: audit.total, paramErrors: audit.paramErrors, policyBlocks: audit.policyBlocks, timeouts: audit.timeouts } : null;
+  if (audit) {
+    // 症状: 工具调用错 (参数类)
+    if (audit.paramErrors > 0) {
+      findings.push({
+        severity: "info",
+        symptom: `参数校验器拦截了 ${audit.paramErrors} 次错误参数 (未浪费 LLM 轮次)`,
+        rootCause: "模型传参不规范 / 工具 schema 描述不够清晰",
+        action: "参数校验已生效; 若同一工具反复被拦, 优先完善该工具的参数描述与示例",
+      });
+    }
+    // 症状: 权限拦截频繁
+    if (audit.policyBlocks >= 3) {
+      findings.push({
+        severity: "medium",
+        symptom: `权限/策略拦截 ${audit.policyBlocks} 次`,
+        rootCause: "权限配置与当前任务错配 (最小权限不等于处处设卡)",
+        action: "用 PERMISSION_PRESETS 切换沙箱档位, 或对确需的高频工具 addRule allow (opencode 规则链)",
+      });
+    }
+    // 症状: 单工具失败率异常
+    for (const [tool, t] of audit.byTool) {
+      if (t.calls >= 5 && t.fails / t.calls > 0.3) {
+        findings.push({
+          severity: "high",
+          symptom: `工具 ${tool} 失败率 ${(100 * t.fails / t.calls).toFixed(0)}% (${t.fails}/${t.calls})`,
+          rootCause: "工具 schema 不清晰 / 实现缺陷 / 上游依赖不稳",
+          action: `优先修复 ${tool}: 补参数描述与示例 + 失败重试 (idempotent) + 结果验证器`,
+        });
+      }
+    }
+    // 症状: 超时
+    if (audit.timeouts >= 2) {
+      findings.push({
+        severity: "medium",
+        symptom: `工具超时 ${audit.timeouts} 次`,
+        rootCause: "上游依赖不稳 / timeoutMs 配置过紧",
+        action: "对幂等工具启用重试; 检查 timeoutMs 与上游可用性",
+      });
+    }
+  }
+
+  // 2. 失败案例库
+  const episodes = readJson(path.join(dataDir, "memory", "failures", "episodes.json"), []);
+  signals.failureEpisodes = episodes.length;
+  if (episodes.length >= 3) {
+    findings.push({
+      severity: "medium",
+      symptom: `失败案例库 ${episodes.length} 条 (近端: ${episodes.slice(0, topPerFinding).map((e) => e.tool).join(", ")})`,
+      rootCause: "同类失败反复出现 = 系统性短板, 非偶发",
+      action: "对高频失败做归因分类 (知识/工具/规划/验证/记忆), 逐类补齐; 每次修复后跑回归",
+    });
+  }
+
+  // 2b. 记忆管线健康度 (2026-10-03 接线: MemoryHealthMonitor 曾被装配却零消费)
+  if (health) {
+    signals.memoryHealth = {
+      overall: health.overall,
+      worstRecentFails: health.worstRecentFails,
+      totalFail: health.totalFail,
+    };
+    if (health.overall && health.overall !== "healthy") {
+      const badSteps = (health.steps || [])
+        .filter((s) => s.recentFails > 0)
+        .map((s) => `${s.name}(${s.recentFails}次: ${String(s.lastError || "?").slice(0, 60)})`);
+      findings.push({
+        severity: health.overall === "unhealthy" ? "high" : "medium",
+        symptom: `记忆管线 ${health.overall} — 窗口内最差单步失败 ${health.worstRecentFails} 次, 累计 ${health.totalFail} 次`,
+        rootCause: badSteps.length ? badSteps.join("; ") : "上游模型或存储不稳",
+        action: health.overall === "unhealthy"
+          ? "已强制降级为「只写不压」(跳过 compact/extract); 先排查 LLM provider 可用性与磁盘写入权限"
+          : "观察是否持续恶化; 可用 model_routing.aux 把辅助任务切到更稳/更便宜的模型",
+      });
+    }
+  }
+
+  // 3. 使用统计 (成本症状)
+  const usage = usageStats || readJson(path.join(dataDir, "usage-stats.json"), null);
+  signals.usage = usage;
+  if (usage && usage.calls >= 5) {
+    const costPerCall = Math.round(usage.tokens / usage.calls);
+    if (costPerCall > 15000) {
+      findings.push({
+        severity: "medium",
+        symptom: `单次调用平均 ${costPerCall} tok (共 ${usage.calls} 次)`,
+        rootCause: "全用大模型 / 上下文冗余",
+        action: "启用 model_routing.aux 分层路由 (辅助任务走便宜模型) + 检查上下文压缩是否生效",
+      });
+    }
+  }
+
+  // 4. 任务基线 (规划症状): 只读显式提供的 rootDir, 不回落 cwd (避免跨仓库污染诊断)
+  let baseline = readJson(path.join(dataDir, "baseline.json"), null);
+  if (!baseline && rootDir) baseline = readJson(path.join(rootDir, "bench", "baseline.json"), null);
+  if (baseline && Array.isArray(baseline.results)) {
+    const fails = baseline.results.filter((r) => !r.pass);
+    signals.baseline = { coverage: `${baseline.results.length} 任务`, failures: fails.length };
+    if (fails.length) {
+      // 失败归因 (2026-10-03 接线): 基线里若带 triage 记录, 直接给确定性根因与处方;
+      // 没有才回落到"需人工判定" —— 这正是框架第 1 条要消灭的那句话。
+      const triages = fails.map((f) => f.triage).filter(Boolean);
+      const causes = triages.length ? summarizeCauses(triages) : null;
+      findings.push({
+        severity: "high",
+        symptom: `任务基线有 ${fails.length} 项未通过: ${fails.slice(0, topPerFinding).map((f) => f.id).join(", ")}`,
+        rootCause: causes
+          ? `失败归因: ${Object.entries(causes.byCause).sort((a, b) => b[1] - a[1]).map(([c, n]) => `${c}×${n}`).join(", ")}`
+          : "未归因 (重跑 taskbench 可自动归因)",
+        action: causes?.dominantAction || "任务分解 + 验证器 + 重规划; 先人工复跑确认是真实失败还是环境误伤",
+        evidence: triages.flatMap((t) => t.evidence || []).slice(0, 4),
+      });
+    }
+  }
+
+  if (!findings.length) {
+    findings.push({ severity: "ok", symptom: "未检出系统性短板", rootCause: "各信号均在阈值内", action: "保持既有节奏: 跑基准 → 找短板 → 优化 → 对比" });
+  }
+
+  // 报告渲染
+  const L = ["═══ 皮皮虾自诊断报告 ═══", ""];
+  L.push(`审计信号: ${signals.audit ? `${signals.audit.total} 次工具调用 (参数错 ${signals.audit.paramErrors} / 策略拦 ${signals.audit.policyBlocks} / 超时 ${signals.audit.timeouts})` : "(无审计数据)"}`);
+  L.push(`失败案例: ${signals.failureEpisodes} 条 | 使用: ${signals.usage ? `${signals.usage.calls} 次 / ${signals.usage.tokens} tok` : "(无数据)"}`);
+  L.push(`记忆管线: ${signals.memoryHealth ? `${signals.memoryHealth.overall} (最差步失败 ${signals.memoryHealth.worstRecentFails} 次 / 累计 ${signals.memoryHealth.totalFail})` : "(未接入)"}`);
+  L.push(`任务基线: ${signals.baseline ? `${signals.baseline.coverage}, ${signals.baseline.failures} 项未通过` : "(未建立)"}`);
+  L.push("");
+  for (const f of findings) {
+    L.push(`[${f.severity.toUpperCase()}] ${f.symptom}`);
+    L.push(`  根因: ${f.rootCause}`);
+    L.push(`  动作: ${f.action}`);
+    L.push("");
+  }
+  return { report: L.join("\n").trim(), findings, signals };
+}

package/src/services/learning-service.js

@@ -28,6 +28,8 @@ export class LearningService {
     this.tracer = deps.tracer;           // 结构化事件流
     this.toolNames = deps.toolNames;     // () => string[], 工具名清单 (verifyLesson 接地)
     this.runTool = deps.runTool;         // (name, args) => Promise<string>, create_skill 调用
+    // 2026-10-03 接线: 语境 Playbook —— refine 成功的教训同步沉淀为 playbook bullet (反哺 system prompt)
+    this.playbook = deps.playbook || null;
     if (!(this.auditor instanceof Auditor)) {
       // 兼容: 外部可能传普通对象 (测试/轻量装配), 不强求 Auditor 实例
     }
@@ -63,6 +65,13 @@ export class LearningService {
       (p) => {
         this.experience.learn({ task: "自动提炼", lesson: p.lesson, tags: ["auto-refine"] });
         if (this.lifecycle) this.lifecycle.evolve(); // 生命周期: 进化计数 (落盘)
+        // 2026-10-03 接线: 教训 → playbook bullet (grow-and-refine 去重内置; 空库首次 ADD)
+        if (this.playbook) {
+          try {
+            this.playbook.apply([{ op: "ADD", kind: "lesson", content: p.lesson, evidence_ref: "learning/refine" }]);
+            this.tracer?.event("evolve/playbook", { op: "ADD", lesson: p.lesson.slice(0, 120) });
+          } catch (e) { /* playbook 沉淀失败不影响经验库主链路 */ }
+        }
       }
     );
     if (!g.committed) {

package/src/services/memory-health.js

@@ -7,11 +7,17 @@
 export const HEALTH = { HEALTHY: "healthy", DEGRADED: "degraded", UNHEALTHY: "unhealthy" };
 
 export class MemoryHealthMonitor {
-  constructor({ degradeAfter = 3, windowMs = 5 * 60 * 1000 } = {}) {
+  constructor({ degradeAfter = 3, unhealthyAfter = null, windowMs = 5 * 60 * 1000 } = {}) {
     this.degradeAfter = degradeAfter;   // 连续失败多少次进入 degraded
+    // 修复 (2026-09-17): unhealthy 原先不可达 (status() 三元两分支都返回 HEALTHY)。
+    // 现按窗口内失败数分为两档: >= degradeAfter → degraded, >= unhealthyAfter → unhealthy。
+    // 默认取 degradeAfter 的两倍, 保持"降级先发生、重度降级随后"的渐进语义。
+    this.unhealthyAfter = Number(unhealthyAfter) || degradeAfter * 2;
     this.windowMs = windowMs;           // 统计窗口 (默认 5 分钟)
     this.steps = new Map();             // stepName -> { ok, fail, lastError, lastAt, fails: [] }
     this.degraded = false;              // 降级开关 (只写不压)
+    this.unhealthy = false;             // 重度降级 (持续失败)
+    this._worst = 0;                    // 窗口内最差单步失败数 (可观测)
   }
 
   _step(name) {
@@ -40,7 +46,7 @@ export class MemoryHealthMonitor {
     return s;
   }
 
-  // 连续失败 -> degraded (滑动窗口内失败数 >= degradeAfter)
+  // 连续失败 -> degraded / unhealthy (滑动窗口内失败数分档)
   _recompute() {
     const now = Date.now();
     let worst = 0;
@@ -48,7 +54,9 @@ export class MemoryHealthMonitor {
       const recent = s.fails.filter((t) => now - t < this.windowMs).length;
       if (recent > worst) worst = recent;
     }
+    this._worst = worst;
     this.degraded = worst >= this.degradeAfter;
+    this.unhealthy = worst >= this.unhealthyAfter;
     return this.degraded;
   }
 
@@ -78,17 +86,37 @@ export class MemoryHealthMonitor {
       recentFails: s.fails.filter((t) => now - t < this.windowMs).length,
     }));
     const totalFail = stepList.reduce((a, s) => a + s.fail, 0);
-    const overall = this.degraded
-      ? HEALTH.DEGRADED
-      : (totalFail === 0 ? HEALTH.HEALTHY : HEALTH.HEALTHY);
-    return { overall, degraded: this.degraded, steps: stepList, updatedAt: now };
+    // 三态可达 (修复 2026-09-17): unhealthy > degraded > healthy
+    const overall = this.unhealthy
+      ? HEALTH.UNHEALTHY
+      : (this.degraded ? HEALTH.DEGRADED : HEALTH.HEALTHY);
+    return {
+      overall,
+      degraded: this.degraded,
+      unhealthy: this.unhealthy,
+      worstRecentFails: this._worst,
+      thresholds: { degradeAfter: this.degradeAfter, unhealthyAfter: this.unhealthyAfter, windowMs: this.windowMs },
+      totalFail,
+      steps: stepList,
+      updatedAt: now,
+    };
   }
 
   // 降级建议 (供 memory ticker / agent 消费)
   advice() {
     if (!this.degraded) return { action: "normal" };
+    if (this.unhealthy) {
+      return {
+        action: "degrade",
+        severe: true,
+        reason: `记忆管线持续失败 (窗口内 ${this._worst} 次, 已达重度阈值 ${this.unhealthyAfter}), 强制降级为只写不压`,
+        // 只写不压: 跳过 LLM 压缩/提炼, 仅保留原始会话写入
+        skip: ["compact", "extract"],
+      };
+    }
     return {
       action: "degrade",
+      severe: false,
       reason: "记忆管线连续失败, 建议降级为只写不压",
       // 只写不压: 跳过 LLM 压缩/提炼, 仅保留原始会话写入
       skip: ["compact", "extract"],

package/src/services/memory-service.js

@@ -23,11 +23,22 @@ export class MemoryService {
     this.experience = deps.experience;   // 经验库
     this.lifecycle = deps.lifecycle;     // ANS 生命周期 (进化计数)
     this.tracer = deps.tracer;           // 结构化事件流
+    // 记忆管线健康监控 (2026-10-03 接线): MemoryHealthMonitor 由 evolvePlugin 装配,
+    // 但此前**零消费** —— 没人 record() 也没人读 advice(), 于是 status() 永远是 healthy,
+    // 降级逻辑形同虚设。现由本服务在每步管线记录成败, 并在降级时真的跳过 LLM 压缩/提炼。
+    this.health = deps.health || null;
     this._personaBuilt = null;           // L3 画像上次生成日期 (跨天刷新标记, 原 agent 字段)
   }
 
   _llm() { return this.getLlm ? this.getLlm() : null; }
 
+  // 管线步骤门禁: 健康度降级时跳过对应 LLM 步骤 (只写不压 → 防上下文污染 + 省调用)
+  _skipStep(step) {
+    if (!this.health || typeof this.health.advice !== "function") return false;
+    const adv = this.health.advice();
+    return !!(adv && Array.isArray(adv.skip) && adv.skip.includes(step));
+  }
+
   // 辅助 LLM 调用前置健康探测: 模型不可用 (本地服务未运行/远端不可达) 时快速跳过
   async _auxLlmReady() {
     const llm = this._llm();
@@ -40,6 +51,10 @@ export class MemoryService {
   async extractMemory(user, assistant, existing = []) {
     const llm = this._llm();
     if (!llm) return [];
+    if (this._skipStep("extract")) {
+      this.tracer?.event("memory/extract", { count: 0, reason: "health_degraded" });
+      return [];
+    }
     if (!(await this._auxLlmReady())) return []; // 模型不可用时跳过提炼 (退回启发式)
     // 噪声治理: 显式跳过寒暄/无信息量/关于系统本身的元讨论
     const sys = "你是记忆提炼器。从对话中提取值得长期记忆的关键事实、用户偏好、待办事项。只输出 JSON 数组, 每项是{content: 一句完整中文记忆}。没有值得记的返回 []。不要解释, 只输出 JSON。\n跳过以下内容: 1) 寒暄/问候/客套话; 2) 无信息量的闲聊; 3) 对助手/系统本身的元讨论与建议 (如任务描述方式、提示词建议等); 4) 已被现有记忆覆盖的内容。";
@@ -49,10 +64,18 @@ export class MemoryService {
       userMsg += "\n\n【已有记忆】以下记忆已存在, 若你提炼的内容与其中任意一条含义相同或被其覆盖, 则不要输出该条 (避免重复):\n"
         + existing.map((f, i) => `${i + 1}. ${f.content}`).join("\n");
     }
-    const r = await llm.chat([
-      { role: "system", content: sys },
-      { role: "user", content: userMsg },
-    ], { timeoutMs: AUX_LLM_TIMEOUT_MS, retryMax: 0 });
+    let r;
+    try {
+      r = await llm.chat([
+        { role: "system", content: sys },
+        { role: "user", content: userMsg },
+      ], { timeoutMs: AUX_LLM_TIMEOUT_MS, retryMax: 0 });
+      this.health?.record("extract", { ok: true });
+    } catch (e) {
+      // 管线步骤成败必须记账 —— 没有这个信号, MemoryHealthMonitor 永远停在 healthy
+      this.health?.record("extract", { ok: false, error: e?.message || String(e) });
+      throw e; // 保持原语义: 由调用方决定是否降级
+    }
     const text = String(r.content || "").trim();
     // 容忍模型把 JSON 包在 markdown 代码块里
     const cleaned = text.replace(/```(?:json|JSON)?\s*/g, "").replace(/```/g, "").trim();
@@ -71,11 +94,19 @@ export class MemoryService {
   async summarizeMemory(raw) {
     const llm = this._llm();
     if (!llm) throw new Error("无 LLM");
+    if (this._skipStep("compact")) throw new Error("记忆管线降级中, 跳过压缩 (只写不压)");
     if (!(await this._auxLlmReady())) throw new Error("LLM 不可用, 跳过辅助摘要");
-    const r = await llm.chat([
-      { role: "system", content: "你是记忆压缩器。把下面这段对话记录压缩成一段简洁的中文摘要(≤200字), 保留关键事实、用户偏好、进展和待办。不要客套, 直接输出摘要。" },
-      { role: "user", content: String(raw).slice(0, 4000) },
-    ], { timeoutMs: AUX_LLM_TIMEOUT_MS, retryMax: 0 });
+    let r;
+    try {
+      r = await llm.chat([
+        { role: "system", content: "你是记忆压缩器。把下面这段对话记录压缩成一段简洁的中文摘要(≤200字), 保留关键事实、用户偏好、进展和待办。不要客套, 直接输出摘要。" },
+        { role: "user", content: String(raw).slice(0, 4000) },
+      ], { timeoutMs: AUX_LLM_TIMEOUT_MS, retryMax: 0 });
+      this.health?.record("compact", { ok: true });
+    } catch (e) {
+      this.health?.record("compact", { ok: false, error: e?.message || String(e) });
+      throw e;
+    }
     this.tracer?.event("memory/summarize", { chars: String(raw).length, ok: true });
     return r.content;
   }
@@ -101,7 +132,9 @@ export class MemoryService {
     // 有 embedder 时走 dense 语义检索 (与 BM25 RRF 融合), 否则 LLM 扩展 + RRF
     let hits;
     if (this.facts.embedder) {
-      hits = this.facts.querySemantic(q, { limit, scope });
+      // 2026-09-18 修复: querySemantic 是 async, 原漏 await 导致 hits 是 Promise,
+      //   tracer 恒记 hits:0 (可观测数据失真), 后续读 hits 也会踩坑
+      hits = await this.facts.querySemantic(q, { limit, scope });
     } else {
       const variants = [q];
       const llm = this._llm();

package/src/services/triage.js

@@ -0,0 +1,138 @@
+// src/services/triage.js - 失败归因 (Agent 增强框架第 1 条的最后一环: "对失败归因")
+// 框架原文: "对失败归因: 是知识不够、工具不会用、规划错、验证缺失, 还是记忆没复用"
+// 本模块把这件事从"人工看日志"变成"从轨迹确定性判定", 零 LLM, 可复现, 可测。
+//
+// 输入: 一次任务的执行轨迹 (最终回复 + 工具调用序列 + 耗时 + 判分结果)
+// 输出: { cause, confidence, evidence[], action } —— action 直接对应"按症状下药"表的处方
+
+export const CAUSE = {
+  /** 卡在 LLM 侧: 单次调用悬挂, 任务时限先到 */
+  LLM_STALL: "llm_stall",
+  /** 卡在规划侧: 重复调用同一工具/参数, 循环不收敛 */
+  LOOP: "loop",
+  /** 跑满时限但轨迹不足以判定 */
+  TIMEOUT_UNKNOWN: "timeout_unknown",
+  /** 工具不会用: 参数错/未知工具/被禁用/权限拦截 */
+  TOOL_USE: "tool_use",
+  /** 规划错: 一直在试但没收敛 (轮次逼近上限且无错误) */
+  PLANNING: "planning",
+  /** 验证缺失: 工具都成功了、有产出, 但结果不对 —— 没做自检 */
+  VERIFICATION: "verification",
+  /** 知识不够: 几乎没查就作答 */
+  KNOWLEDGE: "knowledge",
+  UNKNOWN: "unknown",
+};
+
+// 每类根的处方 (对齐框架"按症状下药"表)
+const PRESCRIPTION = {
+  [CAUSE.LLM_STALL]: "单次 LLM 超时 (provider.timeout_ms) 必须小于任务级时限; 并给工具循环加「心跳超时」",
+  [CAUSE.LOOP]: "任务分解 + 验证器 + 重规划; 检查探索熔断阈值是否过松",
+  [CAUSE.TIMEOUT_UNKNOWN]: "补全轨迹采集后重跑定位 (当前轨迹不足以归因)",
+  [CAUSE.TOOL_USE]: "结构化输出 + 参数校验 + 失败重试 + 沙箱; 优先修该工具的 schema 与示例",
+  [CAUSE.PLANNING]: "任务分解 + 验证器 + 重规划 (轮次逼近上限仍未收敛)",
+  [CAUSE.VERIFICATION]: "生成 → 验证 → 修正: 给这类任务配确定性校验器, 让 agent 自查后再作答",
+  [CAUSE.KNOWLEDGE]: "RAG + 引用核验 + 工具查询 (先查再答, 不要凭记忆作答)",
+  [CAUSE.UNKNOWN]: "采集更多轨迹样本后重判",
+};
+
+// 工具调用签名 (同工具同参数视为重复)
+function sig(c) {
+  try {
+    return `${c.tool}::${JSON.stringify(c.args || {}).slice(0, 120)}`;
+  } catch {
+    return String(c.tool);
+  }
+}
+
+/**
+ * 从轨迹归因一次失败
+ * @param {object} o
+ * @param {string} o.reply        最终回复
+ * @param {Array}  o.toolCalls    工具调用序列 [{tool,args,ok,error,durationMs}]
+ * @param {number} o.ms           总耗时
+ * @param {number} o.budgetMs     任务时限 (默认 90000)
+ * @param {number} o.maxRounds    工具循环轮次上限
+ * @param {string} o.detail       判分说明
+ * @returns {{cause:string, confidence:number, evidence:string[], action:string}}
+ */
+export function triageFailure({ reply = "", toolCalls = [], ms = 0, budgetMs = 90000, maxRounds = 8, detail = "" } = {}) {
+  const calls = Array.isArray(toolCalls) ? toolCalls : [];
+  const evidence = [];
+  const fail = (cause, confidence) => ({ cause, confidence, evidence, action: PRESCRIPTION[cause] });
+
+  const failedCalls = calls.filter((c) => c && c.ok === false);
+  const calledTools = new Set(calls.map((c) => c && c.tool).filter(Boolean));
+
+  // ---- 1. 超时族: 跑满时限才被砍 ----
+  const timedOut = ms >= budgetMs * 0.98 || /超时|timeout/i.test(String(reply || ""));
+  if (timedOut) {
+    evidence.push(`耗时 ${ms}ms 已达任务时限 ${budgetMs}ms`);
+    // 1a. 重复签名 → 规划不收敛
+    const counts = new Map();
+    for (const c of calls) {
+      const k = sig(c);
+      counts.set(k, (counts.get(k) || 0) + 1);
+    }
+    const worst = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+    if (worst && worst[1] >= 3) {
+      evidence.push(`同一调用重复 ${worst[1]} 次: ${worst[0]}`);
+      return fail(CAUSE.LOOP, 0.85);
+    }
+    // 1b. 工具调用很少 → 时间花在 LLM 侧
+    if (calls.length <= 2) {
+      evidence.push(`整个任务只发生 ${calls.length} 次工具调用, 时间几乎全在 LLM 往返`);
+      return fail(CAUSE.LLM_STALL, 0.7);
+    }
+    evidence.push(`工具调用 ${calls.length} 次, 无重复签名, 但仍未收敛`);
+    return fail(CAUSE.TIMEOUT_UNKNOWN, 0.4);
+  }
+
+  // ---- 2. 工具不会用: 有工具返回错误 ----
+  if (failedCalls.length) {
+    const kinds = new Map();
+    for (const c of failedCalls) {
+      const e = String(c.error || "");
+      const k = /参数错误|应为|必填/.test(e) ? "参数校验被拦"
+        : /未知工具|已禁用/.test(e) ? "工具不可用"
+        : /策略拦截|权限|审批/.test(e) ? "权限/策略拦截"
+        : /超时/.test(e) ? "工具超时"
+        : "执行报错";
+      kinds.set(k, (kinds.get(k) || 0) + 1);
+    }
+    for (const [k, n] of kinds) evidence.push(`${k} × ${n} (涉及工具: ${[...new Set(failedCalls.map((c) => c.tool))].slice(0, 3).join(", ")})`);
+    return fail(CAUSE.TOOL_USE, 0.9);
+  }
+
+  // ---- 3. 规划错: 轮次逼近上限仍未收敛 ----
+  if (maxRounds > 0 && calls.length >= Math.max(3, Math.floor(maxRounds * 0.75))) {
+    evidence.push(`工具调用 ${calls.length} 次, 逼近轮次上限 ${maxRounds}, 无错误但未收敛`);
+    return fail(CAUSE.PLANNING, 0.7);
+  }
+
+  // ---- 4. 验证缺失: 该查的都查了、没错、有产出, 但结果不对 ----
+  if (calls.length >= 1) {
+    evidence.push(`工具调用 ${calls.length} 次且全部成功, 但判分失败 (${detail || "结果不符"})`);
+    evidence.push(`涉及工具: ${[...calledTools].join(", ")}`);
+    return fail(CAUSE.VERIFICATION, 0.75);
+  }
+
+  // ---- 5. 知识不够: 几乎没查就作答 ----
+  evidence.push(`工具调用 ${calls.length} 次 —— 基本没查就作答, 判分失败 (${detail || "结果不符"})`);
+  return fail(CAUSE.KNOWLEDGE, 0.8);
+}
+
+// 汇总一批归因结果 → 按根因分布 (供 self_diagnose / 报告展示)
+export function summarizeCauses(triages = []) {
+  const byCause = {};
+  for (const t of triages) {
+    if (!t || !t.cause) continue;
+    byCause[t.cause] = (byCause[t.cause] || 0) + 1;
+  }
+  const top = Object.entries(byCause).sort((a, b) => b[1] - a[1])[0];
+  return {
+    total: triages.filter((t) => t && t.cause).length,
+    byCause,
+    dominant: top ? top[0] : null,
+    dominantAction: top ? PRESCRIPTION[top[0]] : null,
+  };
+}

package/src/session/parts.js

@@ -0,0 +1,76 @@
+// src/session/parts.js - 结构化消息部件 (opencode 风格)
+// 每个部件: { id, type, ...字段, ts }; id 用 crypto.randomUUID()
+//  - part.*        部件工厂
+//  - parts.*       含工厂 + fromResponseItems + estimateTokens
+import { randomUUID } from "node:crypto";
+
+function _base(type, extra) {
+  return { id: randomUUID(), type, ts: Date.now(), ...extra };
+}
+
+// 部件工厂
+export const part = {
+  text(text) {
+    return _base("text", { text });
+  },
+  file({ path: p, content }) {
+    return _base("file", { path: p, content });
+  },
+  image({ url }) {
+    return _base("image", { url });
+  },
+  agent({ name, color }) {
+    return _base("agent", { name, color });
+  },
+  reasoning(text) {
+    return _base("reasoning", { text });
+  },
+  tool({ call, output }) {
+    return _base("tool", { call, output });
+  },
+};
+
+// 把 ResponseItem 数组映射为部件数组 (对齐 codex ResponseItem 形态)
+export function fromResponseItems(items = []) {
+  const out = [];
+  for (const it of items) {
+    if (!it || !it.type) continue;
+    switch (it.type) {
+      case "message":
+        out.push(part.text(it.content ?? ""));
+        break;
+      case "reasoning":
+        out.push(part.reasoning(it.text ?? ""));
+        break;
+      case "function_call":
+        out.push(part.tool({ call: { name: it.name, arguments: it.arguments }, output: null }));
+        break;
+      case "function_call_output":
+        out.push(part.tool({ call: null, output: it.output }));
+        break;
+      default:
+        // 未知类型: 兜底为文本部件, 不丢信息
+        out.push(part.text(JSON.stringify(it)));
+    }
+  }
+  return out;
+}
+
+// 粗估 token 数: 中文每字约 1.6 字符/token, 其它非空白字符约 3.5 字符/token, 分段累加后向上取整
+export function estimateTokens(text) {
+  if (!text) return 0;
+  const s = String(text);
+  let cn = 0, other = 0;
+  for (const ch of s) {
+    if (/[㐀-䶿一-鿿]/.test(ch)) cn++;          // CJK 基本区 + 扩展A
+    else if (!/\s/.test(ch)) other++;
+  }
+  return Math.ceil(cn / 1.6 + other / 3.5);
+}
+
+// 对外命名空间: 含全部工厂 + 转换/估算能力
+export const parts = {
+  ...part,
+  fromResponseItems,
+  estimateTokens,
+};

package/src/session/projection.js

@@ -0,0 +1,73 @@
+// src/session/projection.js - Turn 投影层 (v3.1 首片集成, 2026-10-03)
+//
+// 定位: src/session/turn.js 的 Session→Task→Turn 状态机作为**投影层**接入主链路,
+//       SessionStore (data/sessions/*.jsonl) 仍是会话内容的唯一事实源。
+//       本层只记录「每轮对话的生命周期状态」(open/closed/aborted), 不参与消息路由,
+//       对 chat/chatStream 是纯可观测增量 —— 后续 v3.1 排队输入 (queuedUserInputs)
+//       承接、rollout 持久化都在这层之上演进, 不必再动主链路。
+//
+// 事件: agent.bus 发 chat/turn/begin、chat/turn/end (status: closed|aborted);
+//       protocolBus.eq 有 SQ/EQ 总线时同步推 TASK_TURN_* 结构化事件。
+import { createSession } from "./turn.js";
+
+export class TurnProjection {
+  constructor() {
+    this.sessions = new Map(); // sessionKey -> session 状态机实例 (内存投影, 轻量)
+    this.enabled = true;       // config.agent.turn_projection === false 时整体旁路
+  }
+
+  _get(sessionKey) {
+    let s = this.sessions.get(sessionKey);
+    if (!s) {
+      s = createSession({ id: sessionKey });
+      this.sessions.set(sessionKey, s);
+    }
+    return s;
+  }
+
+  // 开始一轮: 开新 turn 承接用户输入
+  begin(sessionKey, userMsg) {
+    if (!this.enabled) return null;
+    try {
+      const s = this._get(sessionKey);
+      const task = s.currentTask() || s.createTask();
+      const turn = task.appendTurn(String(userMsg ?? ""));
+      return { sessionId: s.id, turnId: turn.id, seq: turn.seq };
+    } catch { return null; } // 投影层永不影响主链路
+  }
+
+  // 正常结束一轮 (排队输入存在时状态机自动开下一个 turn, 本层暂不消费)
+  complete(sessionKey) {
+    if (!this.enabled) return null;
+    try {
+      const s = this.sessions.get(sessionKey);
+      const task = s && s.currentTask();
+      const turn = task && task.completeTurn();
+      return turn ? { turnId: turn.id, status: turn.status, queued: task.queuedUserInputs.length } : null;
+    } catch { return null; }
+  }
+
+  // 中止一轮 (中断/异常)
+  abort(sessionKey) {
+    if (!this.enabled) return null;
+    try {
+      const s = this.sessions.get(sessionKey);
+      const task = s && s.currentTask();
+      return task ? { turnId: task.currentTurn?.id, status: "aborted" } : null;
+    } catch { return null; }
+  }
+
+  // 诊断视图: 指定会话的 turn 概要
+  status(sessionKey) {
+    const s = this.sessions.get(sessionKey);
+    if (!s) return null;
+    const task = s.currentTask();
+    return {
+      sessionId: s.id,
+      turnCount: s.turnCount,
+      taskStatus: task ? task.status : null,
+      queuedInputs: task ? task.queuedUserInputs.length : 0,
+      turns: (task ? task.turns : []).slice(-10).map((t) => ({ id: t.id, seq: t.seq, status: t.status })),
+    };
+  }
+}