@haaaiawd/loom 1.3.1 → 2.0.0

package/cli/src/version.js

@@ -1,134 +0,0 @@
-// version — LOOM 版本管理
-// 提供 list / current / new / use / diff 五个原子操作。
-// CLI 只做数据操作，演进决策（Minor/Major）由 Agent + 用户对话完成。
-
-import { existsSync, readdirSync, readFileSync, writeFileSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { createVersionStructure } from './init.js';
-
-/**
- * 列出所有版本目录。
- * @param {string} loomRoot — .loom 目录路径
- * @returns {{ versions: string[], current: string|null }}
- */
-export function listVersions(loomRoot) {
-  if (!existsSync(loomRoot)) {
-    throw new Error(`找不到 .loom 目录: ${loomRoot}`);
-  }
-  const versions = readdirSync(loomRoot)
-    .filter((d) => /^v\d+$/.test(d) && statSync(join(loomRoot, d)).isDirectory())
-    .sort((a, b) => parseInt(a.slice(1)) - parseInt(b.slice(1)));
-  const current = readCurrentPointer(loomRoot);
-  return { versions, current };
-}
-
-/**
- * 读取当前版本指针。
- * 优先读 .loom/current 文件；不存在则回退到自动探测最新版本。
- * @param {string} loomRoot — .loom 目录路径
- * @returns {string|null} 版本号如 'v1'，或 null（无版本）
- */
-export function readCurrentPointer(loomRoot) {
-  const pointerPath = join(loomRoot, 'current');
-  if (existsSync(pointerPath)) {
-    const v = readFileSync(pointerPath, 'utf-8').trim();
-    if (/^v\d+$/.test(v) && existsSync(join(loomRoot, v))) return v;
-  }
-  // 回退：自动探测最新版本
-  if (!existsSync(loomRoot)) return null;
-  const versions = readdirSync(loomRoot)
-    .filter((d) => /^v\d+$/.test(d) && statSync(join(loomRoot, d)).isDirectory())
-    .sort((a, b) => parseInt(b.slice(1)) - parseInt(a.slice(1)));
-  return versions[0] ?? null;
-}
-
-/**
- * 创建新版本 v{N+1}，自动切换为当前版本。
- * 不复制旧版本内容——空目录 + 模板强制 Agent 重新思考。
- * @param {string} projectDir — 项目根目录
- * @returns {{ version: string, created: string[], skipped: string[] }}
- */
-export function newVersion(projectDir) {
-  const loomRoot = join(projectDir, '.loom');
-  const { versions } = listVersions(loomRoot);
-  const parentVersion = readCurrentPointer(loomRoot);
-  const nextNum = versions.length === 0
-    ? 1
-    : parseInt(versions[versions.length - 1].slice(1)) + 1;
-  const nextV = `v${nextNum}`;
-  const result = createVersionStructure(projectDir, nextV, parentVersion);
-  // 自动切换为当前版本
-  writeFileSync(join(loomRoot, 'current'), nextV, 'utf-8');
-  result.created.push('.loom/current');
-  return { version: nextV, created: result.created, skipped: result.skipped };
-}
-
-/**
- * 切换当前版本指针。
- * @param {string} loomRoot — .loom 目录路径
- * @param {string} version — 目标版本号如 'v1'
- */
-export function useVersion(loomRoot, version) {
-  const v = version.startsWith('v') ? version : `v${version}`;
-  if (!existsSync(join(loomRoot, v))) {
-    throw new Error(`版本不存在: ${v}`);
-  }
-  writeFileSync(join(loomRoot, 'current'), v, 'utf-8');
-  return v;
-}
-
-/**
- * 对比两个版本的文件差异。
- * 只对比文件存在性和大小，不做内容 diff（内容 diff 用 Git）。
- * @param {string} loomRoot — .loom 目录路径
- * @param {string} v1 — 版本 A
- * @param {string} v2 — 版本 B
- * @returns {{ only_in_a: string[], only_in_b: string[], different_size: string[], same: string[] }}
- */
-export function diffVersions(loomRoot, v1, v2) {
-  const a = v1.startsWith('v') ? v1 : `v${v1}`;
-  const b = v2.startsWith('v') ? v2 : `v${v2}`;
-  const dirA = join(loomRoot, a);
-  const dirB = join(loomRoot, b);
-  if (!existsSync(dirA)) throw new Error(`版本不存在: ${a}`);
-  if (!existsSync(dirB)) throw new Error(`版本不存在: ${b}`);
-
-  const filesA = listFilesRelative(dirA);
-  const filesB = listFilesRelative(dirB);
-  const setA = new Set(filesA);
-  const setB = new Set(filesB);
-
-  const onlyInA = filesA.filter((f) => !setB.has(f));
-  const onlyInB = filesB.filter((f) => !setA.has(f));
-  const common = filesA.filter((f) => setB.has(f));
-  const differentSize = common.filter((f) => {
-    const sa = statSync(join(dirA, f)).size;
-    const sb = statSync(join(dirB, f)).size;
-    return sa !== sb;
-  });
-  const same = common.filter((f) => {
-    const sa = statSync(join(dirA, f)).size;
-    const sb = statSync(join(dirB, f)).size;
-    return sa === sb;
-  });
-
-  return { only_in_a: onlyInA, only_in_b: onlyInB, different_size: differentSize, same };
-}
-
-/**
- * 递归列出目录下所有文件的相对路径。
- */
-function listFilesRelative(dir, base = '') {
-  const result = [];
-  if (!existsSync(dir)) return result;
-  for (const entry of readdirSync(dir)) {
-    const full = join(dir, entry);
-    const rel = base ? join(base, entry) : entry;
-    if (statSync(full).isDirectory()) {
-      result.push(...listFilesRelative(full, rel));
-    } else {
-      result.push(rel);
-    }
-  }
-  return result.sort();
-}

package/dimensions/AUTHORSHIP.md

@@ -1,45 +0,0 @@
-# Authorship — Identity Compiler 与 Atelier Method
-
-本维度只在 `quality_strategy=atelier` 时加载。目标不是扮演某位大师，而是迫使本次创作
-形成可反驳的命题、明确的选择与可观察的作品差异。
-
-## Identity Compiler
-
-先读取当前 Intent、Doctrine anchors、Capability Graph / Brief、quality contract、
-creative scope、真实媒介约束与参考机制，再形成 Authorial Stance：
-
-1. `creative_thesis`：作品要让用户以什么不同方式理解或感受问题。
-2. `gaze`：这次优先看见什么。
-3. `tension`：哪两个价值必须同时成立。
-4. `signature_bet`：主张、实现机制与主要代价。
-5. `refusals`：拒绝哪些安全但平庸的默认解。
-6. `medium_grammar`：构图、节奏、动效、材质、语言或声音如何承载命题。
-7. `surprise_budget`：允许陌生到什么程度，哪些边界不可牺牲。
-8. `anti_fixation`：至少一个主动打破首个构想的约束。
-9. `verification_lens`：不看阐述时，怎样从作品与用户行为判断命题成立。
-
-如果这些内容不会改变任何构图、交互、资产、语言或验证动作，Stance 无效。
-
-## Atelier
-
-1. 在修改前冻结真实基线。
-2. 定义至少两个会改变用户体验机制的差异轴。
-3. 独立产生媒介原型；换色、换皮、同义改写不算不同候选。
-4. 每个候选先过 Reliability Floor，再进入质量比较。
-5. 交换顺序或隐藏来源进行比较；没有候选胜过基线时保留基线。
-6. 完整实现胜出机制，观察真实宿主并修正。
-
-唯一记录位于 `.loom/vN/09_ATELIER/<intent-id>.json`。每个候选必须绑定
-`stance_revision`；Stance 改变后，旧候选要重新资格检查或归档。
-
-## Correction Triage
-
-- 当前命题、机制、媒介语法或候选选择失效：写 `corrections[]`，递增
-  `stance_revision`。
-- 新用户结果、约束、能力缺口、风险或项目证据：提交带 provenance 的 Capability Graph
-  proposal，由 Architect 裁决。
-- Intent、契约或 Doctrine 错误：按 LOOM reflow 回到对应上层。
-- 多个任务经 Quality Proof 重复验证的方法：作为 learning candidate，人工晋升为 Skill；
-  只有跨 Intent 的长期创作判断才考虑 Creative Lineage。
-
-Author 不能修改 Graph、Intent 或验收标准，也不能裁决自己的 proposal。

package/dimensions/PART_DECOMPOSITION.md

@@ -1,42 +0,0 @@
-# Responsibility and Intent Slicing
-
-> 这是 Architect 的按需方法，不是 Weaver 的必填清单，也不是 CLI 通过条件。
-
-## 何时使用
-
-只有在以下情况使用拆分：
-
-- 一个目标跨越多个独立系统责任。
-- 不同部分可以单独验证或具有明确依赖。
-- 一次实现会产生过大风险、上下文或回滚成本。
-
-如果拆分不会改善边界、验证或交付顺序，就保持一个 Intent。
-
-## 三种不能混淆的结构
-
-1. **Doctrine 领域**：会反复影响未来决策的长期判断，由 Weaver 负责。
-2. **系统责任**：模块、数据、接口与依赖边界，由 Architect 负责。
-3. **Intent 切片**：能够独立保护和验证的用户结果，由 Architect 负责。
-
-不要从技术目录直接推导 Intent，也不要让 Doctrine 文档变成模块清单。
-
-## 最小拆分法
-
-对候选切片逐一询问：
-
-- 它保护的用户结果能否独立描述。
-- 它是否有独立的完成契约。
-- 它失败时能否独立回流或回滚。
-- 它与其他切片的依赖是否单向且必要。
-- 合并后是否更简单，且不会模糊验证。
-
-只有前三项明确、依赖可解释时才创建独立 Intent。
-
-## 输出
-
-拆分结果只进入：
-
-- `02_ARCHITECTURE.md` 的系统责任与依赖说明。
-- `04_INTENT_MAP.json` 的 Intent DAG。
-
-它不进入 Project Doctrine，也不以“数量足够多”作为质量信号。

package/dimensions/SEARCH_METHODOLOGY.md

@@ -1,101 +0,0 @@
-# Decision-Relevant Research
-
-研究的目的不是展示看过多少资料，而是减少一个真实决定中的错误与平庸。
-
-## 触发条件
-
-满足任一条件才外部研究：
-
-- 当前事实不足以支持高影响或不可逆决定。
-- 任务需要专门领域知识、质量判断或安全边界。
-- 已有方案“合格但普通”，需要寻找不同机制。
-- 证据互相冲突，需要确定适用条件。
-
-低风险、可逆、项目内已有充分事实的决定可以直接实验。
-
-## 搜索回路
-
-```text
-Decision Question
-→ Project Grounding
-→ Targeted Search
-→ Extract Mechanism
-→ Translate to Project Consequence
-→ Test or Record
-```
-
-### 1. Decision Question
-
-把未知写成会改变行动的问题，例如：
-
-- 哪一种交互机制能让首次使用者更快建立正确心智模型？
-- 该库在当前数据规模下的失败边界是什么？
-- 什么信号能区分视觉新鲜感与长期可用性？
-
-“了解行业最佳实践”不是问题。
-
-### 2. Project Grounding
-
-先读真实仓库、用户反馈、现有产物、约束和历史决策。外部资料不能替代项目事实。
-
-### 3. Targeted Search
-
-选择与主张匹配的来源：
-
-- 协议、行为、接口 → 官方规范与实现文档。
-- 风险、效果、因果 → 原始研究、测量或真实案例。
-- 品味与作品质量 → 代表作品、设计批评、成熟实践者的可验证方法。
-- 当前工具能力 → 当前官方文档和真实运行结果。
-
-来源数量不设下限或配额。一个直接原始证据可以足够；多个间接来源也可能仍不够。
-
-### 4. Extract Mechanism
-
-不要只抄结论或名字，提取：
-
-- 在什么条件下成立。
-- 通过什么机制产生结果。
-- 可能在哪些条件下失败。
-- 它能否迁移到当前项目。
-
-### 5. Translate
-
-每条保留证据都要落成项目后果：
-
-```text
-Evidence → Mechanism → Project Decision → Verification Signal
-```
-
-无法改变决定、候选或验证方式的资料不进入正式上下文。
-
-### 6. Stop
-
-满足以下任一条件停止：
-
-- 新证据不再改变候选排序或边界。
-- 一个低成本实验比继续阅读更有信息量。
-- 已有证据足够支持可逆决定。
-- 不确定性只能由用户授权或真实反馈消除。
-
-## Evidence Map
-
-长期判断写入 Doctrine 的 Evidence Map；任务级专业资料进入临时 Expertise Pack；实现后的比较结果进入
-Quality Proof。三者不要互相复制成第二真相源。
-
-最低记录：
-
-- 来源或项目事实。
-- 为什么与当前问题相关。
-- 提取的机制或边界。
-- 它改变了什么决定。
-- 可追溯位置。
-
-## 失败模式
-
-- 固定凑来源数量。
-- 用权威名字代替适用性。
-- 先搜索后定义问题。
-- 把“大家都这样做”当证据。
-- 搜到熟悉答案就停止。
-- 把任务级技巧永久写入 Doctrine。
-- 只有结论，没有基线、反例或验证信号。

package/dimensions/examples/AGENT_SYSTEM/README.md

@@ -1,219 +0,0 @@
-# 参考案例：Agent 系统
-
-> 这份文件提供搜索起点和好实践样本。Weaver 只在相关 Doctrine 问题中使用，
-> 拆解出的部分和这里不同时，以 Weaver 的拆解为准。
-
----
-
-## Agent 系统通常拆解出的实现部分
-
-### 1. 系统架构
-**职责**：编排 vs 控制、进程边界、IPC 机制、状态管理、多 Agent 协调
-
-**该做什么**：
-- **编排而非控制**——设计可信赖的编排协议，把精力放在"哪些能力可以委托、边界在哪、失控时如何收回"这三个问题上，不要试图控制每一行执行
-- **区分 LLM 层和确定性层**——LLM 推理和可测试执行要分离（2389-research 的四层架构：reasoning / orchestration / tool bus / deterministic adapters）
-- **编排模式显式选择**：
-  - Sequential（流水线）：agent 链，前一个的输出是后一个的输入
-  - Concurrent（并行）：多 agent 同时处理同一任务，结果聚合（Fan-out/Fan-in）
-  - Handoff（交接）：triage agent 路由到 specialist，specialist 接管后续交互
-  - Agents-as-tools（工具化）：manager agent 调用 specialist 作为工具，自己保留最终回答权
-- **状态管理显式化**——agent 状态必须可序列化，非序列化状态破坏恢复能力
-- **IPC 机制要考虑进程边界**——子 agent 可能是独立进程，通信协议要显式（不是共享内存）
-
-**不该做什么**：
-- 不要让单个 agent 拿所有工具——工具过载导致选择质量下降（Microsoft Azure 架构指南）
-- 不要让 LLM 层直接做副作用——副作用必须在确定性层，带幂等键
-- 不要用共享可变状态做 agent 间通信——破坏可恢复性
-- 不要假设 agent 不会崩——长任务必须有 checkpoint
-
-**参考实践**：
-- **Azure Architecture Center — AI Agent Orchestration Patterns** — Sequential / Concurrent / Handoff / Agents-as-tools 四种编排模式 + 选择指南。https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns
-- **OpenAI Agents SDK — Multi-Agent Orchestration** — Handoff vs Agents-as-tools 的选择标准、代码编排 vs LLM 编排。https://openai.github.io/openai-agents-python/multi_agent/
-- **Microsoft Multi-Agent Reference Architecture** — Orchestrator + Registry + Classifier + MCP Server 的完整参考架构。https://microsoft.github.io/multi-agent-reference-architecture/docs/reference-architecture/Reference-Architecture.html
-- **2389-research/building-multiagent-systems** — 四层架构 + 七种协调模式 + 生命周期管理（cascading stop / orphan detection / heartbeat）。https://github.com/2389-research/building-multiagent-systems
-- **"Control Plane as a Tool" (arXiv 2505.06817)** — 把控制平面暴露为单个工具接口，封装工具路由逻辑，解决规模化时的工具编排问题。https://arxiv.org/html/2505.06817
-
-**搜索起点**：
-- "agent orchestration architecture patterns"
-- "multi-agent coordination protocol"
-- "LLM agent system design four layer architecture"
-- "agent state machine workflow"
-
----
-
-### 2. 工具调用哲学
-**职责**：委托边界、失控收回、工具描述怎么写、工具选择策略、按需加载
-
-**该做什么**：
-- **工具描述是给 LLM 看的契约**——schema 要清晰、类型要显式、副作用要声明
-- **按需加载工具定义**——不要把所有工具定义一次性塞进 context（MCP 的 code-execution 模式：agent 探索 filesystem 发现工具，按需加载，token 从 150K 降到 2K，节省 98.7%）
-- **人类在环作为安全网**——MCP 规范要求：工具调用 SHOULD 有人类在环，能拒绝调用（modelcontextprotocol.io §Tools）
-- **工具权限分级**——读操作自动批准，写操作需确认，不可逆操作需显式批准
-- **工具结果要过滤**——不要把原始 tool output 直接塞回 context，在执行环境里过滤后再返回模型
-
-**不该做什么**：
-- 不要给 agent 没有边界的工具——"能做什么"和"被允许做什么"是两件事
-- 不要让工具描述模糊——"处理文件"不行，"读取文件内容，参数：path，返回：string"才行
-- 不要把敏感工具和普通工具混在一起不加标记
-- 不要假设 LLM 会正确选择工具——工具越多选择质量越下降，要有工具数量上限或分域
-
-**参考实践**：
-- **MCP Specification — Tools** — JSON Schema 定义工具、`tools/list` 发现、`tools/call` 调用、人类在环要求。https://modelcontextprotocol.io/specification/2024-11-05/server/tools
-- **Anthropic — "Code execution with MCP"** — 把 MCP server 暴露为 code API 而非直接 tool call，agent 按需加载工具定义，token 节省 98.7%。https://www.anthropic.com/engineering/code-execution-with-mcp
-- **MCP Architecture Overview** — Tools / Resources / Prompts 三种 primitive，`*/list` 发现 + `*/get` 检索 + `tools/call` 执行。https://modelcontextprotocol.io/docs/learn/architecture
-- **2389-research — Schema-first tools** — typed contract 让 sub-agent 发现和验证工具 + permission inheritance + locking + rate limiting。https://github.com/2389-research/building-multiagent-systems
-
-**搜索起点**：
-- "MCP Model Context Protocol tool calling"
-- "agent tool description writing best practices"
-- "tool selection strategy LLM overload"
-- "agent tool permission boundary"
-
----
-
-### 3. 上下文管理
-**职责**：上下文窗口管理、压缩策略、记忆持久化、信息保留优先级、预算感知
-
-**该做什么**：
-- **主动压缩 vs 被动保留**——agent 应该自主决定何时压缩，别等 context 满了才压缩（Focus Agent：模仿黏菌的探索-retract 策略，主动把关键学习固化到 Knowledge block，剪枝原始历史）
-- **压缩什么、保留什么要显式**——文件路径、API 参数、关键决策不能丢；中间错误、冗余输出可以压缩
-- **预算感知**——agent 要知道剩余 context headroom，据此决定压缩力度（ContextBudget：把压缩建模为预算约束的序列决策）
-- **语义无损压缩 > 截断**——SimpleMem 三阶段：语义结构化压缩 → 在线语义合成 → 意图感知检索规划，F1 提升 26.4%，token 降 30 倍
-- **区分短期 / 工作记忆 / 长期记忆**——不同记忆不同生命周期、不同检索策略
-
-**不该做什么**：
-- 不要被动保留全部历史——context bloat 导致成本爆炸、延迟增加、推理质量下降（"lost in the middle"）
-- 不要用固定规则压缩——"保留最近 N 轮"不够，信息相关性随任务进展动态变化（Acon：压缩指南优化，自然语言空间精炼 compressor prompt）
-- 不要压缩后丢失关键细节——一个文件路径丢了整个 workflow 就崩了（Acon 论文指出）
-- 不要把记忆和持久化执行混为一谈——session memory 不是 durable execution（Zylos Research）
-
-**参考实践**：
-- **Focus Agent (arXiv 2601.07190)** — agent-centric 主动压缩，模仿黏菌策略，6 次自主压缩/任务，token 节省 22.7%，精度不降。https://arxiv.org/html/2601.07190v1
-- **SimpleMem (arXiv 2601.02553)** — 语义无损压缩三阶段，F1 +26.4%，token -30x。https://arxiv.org/pdf/2601.02553
-- **ContextBudget (arXiv 2604.01664)** — 预算感知上下文管理，把压缩建模为预算约束序列决策。https://arxiv.org/pdf/2604.01664
-- **Acon (arXiv 2510.00615)** — Agent Context Optimization，自然语言空间优化压缩指南，model-agnostic。https://arxiv.org/html/2510.00615v3
-- **SUPO (ACL 2026)** — summarization-augmented policy optimization，RL 训练时同时优化工具使用和摘要策略。https://aclanthology.org/2026.acl-long.966/
-
-**搜索起点**：
-- "LLM context window management compression"
-- "agent memory architecture short term long term"
-- "context bloat agent performance degradation"
-- "what to keep what to compress agent context"
-
----
-
-### 4. 提示词工程
-**职责**：角色激活、约束注入、系统提示词结构、上下文组装、角色边界
-
-**该做什么**：
-- **Role-Task-Constraints 三层结构**——系统提示词按这个顺序：Role（做什么类型的工作）→ Task（具体做什么）→ Constraints（不管什么任务都成立的不变式 + 禁忌）。缺任何一层都会 under-specify
-- **硬约束放最前和最后**——注意力在开头和结尾最强（attention anchoring），安全约束埋在第七段等于没有
-- **稳定 vs 可变分离**——稳定部分（role / 硬约束 / 行为风格）短而紧，可变部分（参考资料 / 示例 / 上下文）动态注入
-- **禁忌配正面替代**——LLM 对否定指令系统性表现更差（Truong et al. 2023，降 20-40 分），"不要编辑 vendor/" 要配 "vendor/ 的修改走 PR review 流程"
-- **约束作为可组合规则集**——核心 prompt 不变，约束按部署上下文动态注入（constraint injection pattern：scope + priority + content，运行时 resolver 合并）
-- **输出契约显式**——格式、长度、schema、要省略什么，都写清楚。被代码消费的输出要求 JSON against schema
-
-**不该做什么**：
-- 不要写长 preamble 再放关键指令——注意力衰减，关键约束掉进 attention shadow
-- 不要用 "be careful" 这种模糊约束——写成 concrete checkable rules："never run a statement that writes; refuse and explain"
-- 不要把 role 和 task 混在一起——role 定义"我是谁"，task 定义"现在做什么"
-- 不要假设 LLM 能从 context 推断 role 边界——role 边界要显式声明，否则 prompt injection 能越权
-
-**参考实践**：
-- **buecking/incontext — Role-Task-Constraints** — 系统提示词三层结构 + 禁忌配正面替代 + negation 性能下降证据。https://github.com/buecking/incontext/blob/main/docs/patterns/role-task-constraints.md
-- **contextpatterns.com — System Prompt Engineering** — Pyramid pattern（关键内容放最前）+ attention anchoring + 稳定/可变分离。https://contextpatterns.com/guides/system-prompt-engineering/
-- **llmbestpractices — System Prompt Design Patterns** — 命名块结构（role/capabilities/constraints/output/examples）+ 约束作为 explicit rules + 输出契约。https://llmbestpractices.com/prompt-engineering/system-prompt-design-patterns
-- **context-engineering-handbook — Constraint Injection** — 约束作为可组合规则集，运行时按部署上下文动态注入。https://github.com/ypollak2/context-engineering-handbook/blob/main/patterns/construction/constraint-injection.md
-- **LessWrong — "A Theory of Prompt Injection"** — role 边界失败机制 + role probes（CoTness / Userness）。https://www.lesswrong.com/posts/d8xDGzCEYE639qqEv/
-
-**搜索起点**：
-- "system prompt design patterns role task constraints"
-- "prompt engineering constraint injection dynamic"
-- "LLM negation performance drop negated instructions"
-- "prompt injection role boundary"
-
----
-
-### 5. 验证哲学
-**职责**：怎么信、怎么验、自动化 vs 人类、验证维度设计、信任校准
-
-**该做什么**：
-- **验证嵌入执行循环，别做事后评估**——TrustBench：在 agent formulates action 之后、execution 之前做信任验证（pre-execution gate），事后打分来不及阻止错误
-- **信任分级 + capability gate**——skill manifest 带显式 verification level，HITL 只对 unverified 触发，verified 的自动放行（否则 HITL 退化为 rubber-stamping）
-- **双信号信任评分**——agent stated confidence（经 calibration curve 映射）+ 无 ground-truth 可计算的 metrics 子集，sub-200ms 出结果
-- **多维验证**——不只看功能正确性：correctness / informativeness / consistency（TrustBench）；reliability / grounding / attribution / policy-alignment（AEMA 统一框架）
-- **HITL 模式选择**：
-  - Workflow approval（durable，多步骤，可等数天）——用于合规/安全/高质量审查
-  - MCP elicitation（结构化用户输入）——用于工具执行中需要额外信息
-- **不可逆操作必须人类确认**——payments / deletions / external communications（Cloudflare HITL patterns）
-
-**不该做什么**：
-- 不要用 ROUGE 等 ground-truth overlap 指标评估 agent 推理质量——agentic task 没有确定性 reference（TrustBench 指出）
-- 不要让 HITL 对每个调用都触发——operationally untenable，degrades into rubber-stamping
-- 不要只做事后评估——reactive assessment 无法阻止执行中的错误
-- 不要混淆 capability 和 trustworthiness——能力强的不一定可靠
-
-**参考实践**：
-- **TrustBench (arXiv 2603.09157)** — 实时信任验证，pre-execution gate，双信号 sub-200ms 评分，dual-mode（benchmark + toolkit）。https://arxiv.org/abs/2603.09157v1
-- **Skills as Verifiable Artifacts (arXiv 2605.00424)** — trust schema + verification level + capability gate + biconditional correctness criterion。https://arxiv.org/html/2605.00424v1
-- **AEMA (arXiv 2601.11903)** — 多 agent 可验证评估框架，process-aware + auditable + human oversight。https://arxiv.org/pdf/2601.11903
-- **Unified Evaluation & Governance Framework** — ARS/RGC/ACR/PAAS 四指标 + 多层验证 + 治理审计层，hallucination -88%。https://doi.org/10.36227/techrxiv.176799772.28164151/v1
-- **Cloudflare Agents — Human-in-the-loop patterns** — Workflow approval vs MCP elicitation + timeout + audit trail。https://developers.cloudflare.com/agents/concepts/human-in-the-loop/
-
-**搜索起点**：
-- "AI agent verification trust benchmark"
-- "human-in-the-loop pattern agent approval"
-- "pre-execution verification agent safety"
-- "multi-dimensional agent evaluation"
-
----
-
-### 6. 失败与恢复
-**职责**：崩溃恢复、状态一致性、回滚策略、降级方案、幂等性、熔断
-
-**该做什么**：
-- **每个副作用操作当事务边界**——record intent before execution → execute with idempotency wrapper → record durable receipt after success（Zylos Research）
-- **checkpoint + idempotent step 是恢复的基础**——checkpoint 让你从最后完成点恢复，idempotent 让你重试不产生重复副作用（AWS Well-Architected Agentic AI Lens）
-- **两种恢复方案选一种**：
-  - Deterministic replay（Temporal/Inngest 模式）：state = inputs + side-effect log，重放时跳过已 log 的副作用
-  - Checkpoint snapshot（LangGraph Cloud 模式）：周期性序列化 plan / working memory / partial outputs / pending tool calls
-- **idempotency key 传给每个副作用目标**——没有 idempotency key 的工具不能安全 resume（crash-between-effect-and-log 会产生重复）
-- **circuit breaker 防级联失败**——外部 API 连续失败 N 次后临时停止调用，避免浪费 latency 和 token（MightyBot）
-- **checkpoint 有 TTL + 显式清理**——不完成的 workflow 最终 aged out，完成的立即回收空间
-- **恢复后验证副作用是否真的完成了**——不要假设，查 idempotency key、查 API 状态
-
-**不该做什么**：
-- 不要假设 agent 不会崩——长任务一定会崩，问题是什么时候
-- 不要用 session memory 当 durable execution——chat history 不能证明哪个 shell 命令跑了、哪封邮件发了（Zylos Research）
-- 不要把恢复范围设得太大——"整个 pipeline 从头跑"浪费 token 和时间，scope 到最小可能单元
-- 不要在 interrupt 边界前放 mutating 操作——LangGraph 的 interrupt 后 code 可能重跑，approval boundary 要放对位置
-- 不要忽略 drifted external state——恢复后外部状态可能变了，要验证
-
-**参考实践**：
-- **Agent Resumption Pattern** — deterministic replay vs checkpoint snapshot + idempotency key。https://github.com/agentpatternscatalog/patterns/blob/main/patterns/agent-resumption.md
-- **AWS Well-Architected Agentic AI Lens — AGENTREL03-BP03** — checkpoint + idempotent step + TTL lifecycle。https://docs.aws.amazon.com/wellarchitected/latest/agentic-ai-lens/agentrel03-bp03.html
-- **MightyBot — Fault-Tolerant AI Agent Pipelines** — idempotency / checkpoint / state machine / circuit breaker / dead letter queue。https://mightybot.ai/blog/fault-tolerant-ai-agent-pipelines/
-- **Zylos Research — Durable Execution for AI Agent Runtimes** — execution journal + idempotent tool boundaries + versioned prompts + durable human approvals + recovery tests。https://zylos.ai/research/2026-04-24-durable-execution-agent-runtimes/
-- **LangGraph Persistence** — checkpointer 每 superstep 存 graph state，支持 memory / fault recovery / time travel / HITL。https://github.com/langchain-ai/langgraph
-
-**搜索起点**：
-- "agent failure recovery checkpoint pattern"
-- "durable execution AI agent runtime"
-- "idempotent agent operations side effect"
-- "circuit breaker pattern agent pipeline"
-
----
-
-## 搜索时的关键提醒
-
-1. Agent 系统是实践驱动领域——知识在工程博客、开源项目、会议演讲里，传统学术论文里反而少。不过 arXiv 上 2025-2026 年的 agent 专项论文开始多了，值得关注
-2. 看真实系统的架构文档——LangChain / AutoGPT / CrewAI / OpenAI Agents SDK / Microsoft Multi-Agent Reference Architecture 的 README 和 design docs
-3. 关注失败案例——Agent 系统的哲学往往从"它怎么失败了"中提炼。issue tracker 和 postmortem 是金矿
-4. 区分 hype 和 practice——很多 Agent 框架的博客是营销文案，看代码和 issue tracker 才是真实状态
-5. 2025-2026 年的关键趋势：
-   - MCP 成为工具调用标准
-   - 主动上下文压缩取代被动保留
-   - pre-execution 验证取代事后评估
-   - durable execution + idempotency 成为生产级 agent 的硬要求
-   - constraint injection 取代静态 system prompt