harness 如何运作，逐点讲清

DAG 执行器是 harness 的故障边界原语。工作内容编译为一组原子 leaf 构成的有向无环图，executor 强制执行严格生命周期：每个单元要么全部成功断言后置条件，要么丢弃如从未运行。可靠性是图形结构与这一二元契约的函数，而非 leaf 内部运行的模型决定。

失败模式

缺少这一原子契约时，基于易错模型或服务的多步骤管线会遭受部分状态损坏。中途失败的 leaf 可能留下半写好的输出，下游 leaf 不知情地消费这些输出，无声地叠加错误。当多个 leaf 共享依赖却无明确的完成/未完成信号时，竞态条件出现，系统无法回答“此输入是否稳定”。重试逻辑变得模糊：若 leaf 部分变更了状态，重新执行可能导致效果重复应用或传播过时数据。conductor 无法区分干净失败与从未正确启动的 leaf，每次失败要么强行全图重跑代价高昂，要么手动梳理副作用。harness 将歧义泄露到每一次重试、跳过或路由重定向决策中，可靠性崩溃为每个 leaf 的防御性检查纠缠体。

工作原理

executor 为每个 leaf 强制执行严格的状态生命周期：

• pending – 尚未评估就绪性。
• ready – 所有上游依赖处于 done 或 skipped 状态；leaf 可被 dispatch。
• running – leaf 正在其上分配模型或工具上执行。
• done – 执行完成且 leaf 成功断言其后置条件。
• failed – 执行完成但后置条件断言失败（或发生异常）。
• paused / skipped – 外部控制状态（例如人工暂停或 conductor 指示跳过）。

一个 leaf 从 pending 转换到 ready 仅当每个上游 leaf 都达到终止状态（done 或 skipped）。没有部分就绪，没有尽力推测。这个拓扑门确保没有 leaf 会在不完整或未验证的输入上运行。

当 leaf 完成其负载后，executor 运行 leaf 的后置条件检查——一组必须成立的不变式（例如输出格式有效、必要字段存在）。若断言通过，leaf 转为 done；若失败，leaf 立即被丢弃：其状态转为 failed，其输出从 DAG 上下文中擦除，下游 leaf 永远不会看到它。失败限制在 leaf 边界内。conductor 随后可以决定重试该 leaf（以可能不同参数重新实例化）、跳过它（标记为 skipped 以便依赖项适应）或重新路由工作流——全都毫无歧义，因为没有部分状态逃出 leaf。

DAG executor 从不解释 leaf 逻辑。它只强制执行生命周期、依赖拓扑和后置条件门。它保证每个达到 done 的 leaf 都完全验证过，每个失败 leaf 在图内不留可见痕迹。

权衡与边界

• 后置条件成本。 每个 leaf 必须定义并执行其自身不变式。廉价后置条件（类型检查、schema 验证）开销低，但重量级检查（例如重新评估模型输出）可能成为瓶颈。executor 不提供优化——leaf 作者负担该成本。
• 无部分结果或流式输出。 二元契约禁止增量输出。失败 leaf 产生的任何部分工作都会丢失；leaf 是全有或全无的单元。需要渐进交付的工作负载必须拆分为更小的 leaf 或使用其他原语。
• 副作用不会自动回滚。 “丢弃如从未运行”使 leaf 对下游消费者不可见，但任何预先提交的外部副作用（API 调用、写入）仍存在。契约依赖 leaf 作者设计幂等的 leaf、将不可逆效果延迟到后置条件成功之后，或通过外部管理补偿。
• 仅限有向无环。 DAG 严格无环。循环工作流必须在 executor 外部处理，通常由 conductor 每次迭代重新规划新图。
• 退化路径。 若后置条件过弱（总是通过），executor 退化为简单调度器，未验证输出传播，消除可靠性保证。若后置条件过严，健康输出被拒绝，导致过多假阴性失败。调整后置条件严格度是持续运维事项。
• 粒度是设计选择，而非运行时调整。 粗粒度 leaf 在失败时丢弃大量工作；细粒度 leaf 增加图开销与调度复杂度。executor 无论如何都将每个 leaf 视为原子。

何时值得使用

DAG executor 在以下场景中发挥价值：任何多步骤工作流中，单一失败不能损坏整个管线。

• 带验证的模型链： Leaf A 生成输出；leaf B 用后置条件验证它。若验证失败，仅 A 被重试，下游步骤不受污染。
• 昂贵的混合模型管线： 廉价快速模型运行一个 leaf；后置条件 leaf 检查一致性。失败可触发仅该 leaf 在更强模型上重跑，节省成本。
• 带依赖的并行扇出： 就绪规则确保下游 leaf 只看到来自所有上游 leaf 的稳定、验证过的输入，消除竞态条件。
• 审计与调试： 每个 leaf 记录二元成功或失败及其后置条件结果，提供干净、原子追踪的执行历史。
• 高可靠性工作流： 财务计算、合规检查或配置生成，其中半执行步骤会破坏下游状态。

一个 leaf 要么完成，要么从未发生过——图保证这一点。

比较并交换（CAS）状态是一个每叶子（per‑leaf）的原子状态机——pending → claimed → completed——保证在任何并发度下恰好有一个工作者可以认领并完成给定叶子。它建立在一个核心思想上：只有 compare‑and‑swap 指令成功的工作者才能转移状态；其他工作者看到不匹配，转而处理其他任务。结果是得到一个无锁框架（lock‑free harness），将并行叶子执行从竞态条件转变为确定性认领。

失败模式

没有 CAS，DAG 中每个就绪的叶子都会成为潜在的静默错误点。两个或更多工作者检查同一个叶子，都看到 pending，然后都决定执行。它们重复工作——浪费计算资源——然后都写入完成标记。下游依赖项收到两次本应只有一次的转换，破坏了它们的不变量。如果叶子产生副作用（文件写入、API 调用、数据库插入），这些操作会触发两次。基于单一完成语义的图依赖解析，会静默地变成无意义的混乱。脆弱性随并发度放大：更多工作者提高了碰撞概率，一个未保护的叶子就足以破坏整个计划。全局互斥锁可以阻止这种情况，但代价是所有叶子转换串行化，吞吐量归零。没有 CAS，可靠的并行执行是不可能的——框架变成一场彩票，而非一条流水线。

工作原理

每个叶子携带一个可原子访问的状态字。框架定义了恰好三种合法状态和两个受保护的转换：

• 认领（Claiming）：工作者读取叶子状态（预期 pending），并尝试原子 compare‑and‑swap 为 claimed。只有一个工作者的 CAS 成功；失败者看到不匹配——要么 claimed（其他工作者已获胜），要么 completed（已完成）。失败工作者不阻塞。它从分发队列中选取另一个叶子，或者只有在状态保持 pending 时（一个很快会解决的边缘情况）才重试同一个叶子。
• 完成（Completing）：执行完叶子任务后，获胜的工作者执行第二次 CAS，从 claimed 转换为 completed。这防止了重复完成：如果某个错误或过时的恢复尝试再次完成同一个叶子，CAS 会失败，因为状态已经是 completed。只有第一次成功完成才有效。
• 失败处理：如果工作者在认领 CAS 之后、完成 CAS 之前崩溃，叶子状态停留在 claimed。CAS 本身无法超时或回滚该状态——它是一个纯粹的原子原语。恢复被委托给分发层，该层监控叶子状态并应用超时/重试策略（例如，在可配置的截止时间后将叶子重置为 pending）。这种分离使框架快速且最小化，同时由更高层组件处理活性。

CAS 原语始终开启，对模型不可见，由框架在每个状态转换上强制执行。不存在全局锁；工作者从不相互等待。

权衡与边界

CAS 是单状态原语。它不协调多叶子事务——它不能原子性地同时认领叶子 A 和叶子 B，也不能回滚已完成的叶子。这些责任属于 conductor（计划级编排）和 dispatch（拓扑排序、恢复）。

崩溃后卡在 claimed 状态的叶子需要外部超时；没有它，进度将停滞。分发层的重试策略必须根据工作负载调整，以平衡误报重置与长时间停顿。CAS 也不提供副作用幂等性：如果叶子写入外部数据库，然后工作者在完成 CAS 之前崩溃，框架可以在超时后重试叶子，但无法撤销该数据库写入。安全性保证是状态转换的完整性，而非外部补偿。

在极端竞争下——许多工作者争夺同一个叶子——CAS 失败会浪费少量 CPU 周期用于重试。实际中，分发层将工作分布到许多就绪叶子上，使竞争可忽略。一次成功 CAS 的成本是单个硬件原子指令（几个周期），远小于叶子内部的模型推理或 I/O。如果工作负载完全由微秒级任务组成，该开销可能变得可测量，但这对 agent 平台而言是不典型的用法。

CAS 不防止叶子产生错误结果（模型幻觉、错误的工具调用）。验证（verifier）——路线图上的一个独立组件——处理输出正确性。

何时发挥价值

任何时候多个工作者并发执行叶子时，CAS 都体现价值。对于任何吞吐量敏感的 Xihe 部署，这是默认设置。它在以下情况下尤为突出：

• 叶子代价高昂（数秒的模型推理或 I/O），重复执行会浪费时间和外部配额。
• 叶子产生副作用且不能触发两次——例如，速率受限的 API 调用、数据库插入、文件写入。
• 工作者是异构或不可靠的（模型延迟变化不定，可能崩溃）。CAS 确保状态转换诚实，即使工作者来来去去。
• DAG 包含数十到数千个叶子，且分发层同时馈送许多就绪叶子；全局锁会成为串行化瓶颈。

在这些场景中，CAS 将并行性从正确性隐患转变为安全、可预测的流水线。如果系统使用单一工作者运行，CAS 增加微不足道的开销且永远不会竞争；一旦并发度提高，它就静默地防止了开发者从不需要考虑的破坏。

CAS 将并发叶子执行从竞态条件转变为可预测的流水线：一个工作者，一次认领，一次完成。

Harness 将共享上下文——系统提示与任务框架——物化一次，并锁定为字节稳定的提示前缀。DAG 中的每个叶子都通过 provider 的提示缓存机制继承该前缀，从而消除冗余的 token 重算。其核心思想是：并行执行不应倍增共享上下文的成本；通过缓存该上下文，并发宽度仅受 provider 速率限制约束，而非 token 预算。

失败模式

若没有冻结前缀，宽 DAG 中的每个叶子都会独立传输并处理相同的系统提示与任务框架。这种冗余不仅是浪费——更会破坏性地叠加。每个叶子为前缀支付全额 token 生成成本，将 256 路扇出变成同一上下文的 256 倍 token 乘法。延迟膨胀，因为 provider 需反复为前缀计算 KV 缓存，耗尽自身资源并扼制吞吐量。并发在 token 预算与速率限制余量的重压下崩溃：本应快速的并行叶子执行变成序列化、成本爆炸的行军。

该故障是静默的——无报错、无崩溃。开发者可能用少量叶子测试，从未发现问题，直到 DAG 拓宽时撞墙。脆弱性在于并发与提示大小互相耦合；消除这一耦合是设计的核心任务。

工作原理

Harness 在任意叶子被派发前，将共享上下文物化一次，并锁定为确定性的不可变字节序列。后续叶子不再重新组装这一前缀；它们通过 provider 的提示缓存机制引用它。Provider 存储前缀的 KV 状态，并为每个提交相同字节精确前缀的叶子提供该状态，完全跳过重算。

• 每个叶子的请求由缓存前缀（或对其的引用）加上叶子特有后缀组成。Provider 将前缀 token 视为缓存命中，按约 生成价格的 10% 计费。
• 重算降为零；每个叶子仅剩轻量级缓存查找。
• 结构共享使得宽并发变得可负担：在该方案下，DeepSeek 工作负载通常可在单个缓存前缀上实现 ~256 路扇出；MiMo 可扩展至 ~8 路。
• 冻结前缀是一条 红线。任何编辑——哪怕一个 token 的改动——都会使所有下游叶子的缓存失效，迫使每个叶子对前缀的 KV 状态进行完全重算。因此，Harness 将前缀修改视为破坏模式的操作，仅允许在 conductor 显式重新规划的步骤中进行。

该设计 将并发宽度与提示大小成本解耦。并行性现在受限于 provider 的每秒请求数或每分钟 token 数限制，而非共享上下文的大小。

权衡与边界

冻结前缀强加了严格的刚性：DAG 中所有叶子的共享上下文必须完全相同。不存在混合“部分动态”机制——系统提示或任务框架中任何逐叶子的变化都将要求不同的前缀，从而破坏缓存收益。这些叶子特有需求必须放在后缀中，而后缀无法从缓存获益。

最大的代价是 红线惩罚。在运行中更改前缀会迫使后续每个叶子完全重算，导致 token 使用量和延迟飙升。这仅在重新规划很少发生时才可接受——conductor 的重新规划步骤被明确门控，以有意吸收这一代价，而非由叶子意外触发。

该机制依赖于 provider 支持提示缓存。若 provider 不提供缓存或在缓存命中时仍按全额 token 收费，则 token 节省作用消失，仅剩下结构上的简化。对于非常小的 DAG（少量叶子）或琐碎的共享上下文，管理冻结前缀的开销可能超过收益。

缓存命中经济学依赖于前缀在短时间窗口内被密集复用——这正是 Harness 保证的模式。然而，Harness 无法控制 provider 的缓存驱逐策略；它仅确保前缀字节稳定并统一传输。退化路径是每个叶子完全重算，Harness 将其视为昂贵的缓存未命中，但不会尝试重试或补偿。

何时发挥价值

每当大量静态共享上下文供给多个并发叶子时，冻结前缀就会带来收益。

• 宽扇出 DAG，例如代码生成，其中单个规范派生出数百个独立函数实现。每个叶子继承相同的架构约束；前缀只支付一次，并行几乎免费。
• 多智能体评估，其中相同的评分标准与系统提示被并行应用于数十个响应。
• 批量提取或分类，具有固定的 schema 描述和格式化规则；每个叶子仅输入记录不同。
• 成本敏感部署，其中 token 预算紧张，约 10% 的缓存命中定价将原本不可承受的扇出变成可控开销。
• 延迟敏感的实时智能体，跳过 KV 预填为每个叶子节省数百毫秒。

该机制对于单叶子任务或共享上下文微不足道的 DAG（例如单行系统提示）而言过于笨重。它恰恰在以下场景中证明其价值：并行性因 token 成本而受限——且共享上下文足够大，使得节省决定性的。

冻结前缀将并发从 token 成本转变为速率限制游戏：为共享上下文支付一次，且仅一次。

Best-of-N 嫁接是一种针对高风险叶子节点的驾驭策略：conductor 并行启动 N 个独立尝试，它们共享相同的冻结前缀。可配置的裁判组根据成本、质量和延迟对每个尝试打分；仅将得分最高的尝试嫁接到主树上，其余丢弃。其核心思想在于冻结前缀意味着你为并发付费，而不是 N 倍的 token——成本仅适用于分叉的后缀部分。

失败模式

没有 Best-of-N，每个叶子就是单次模型调用。对于棘手的算法、设计决策或模糊的规格说明，那一次尝试本质上就是抛硬币。如果模型第一个样本是次优的——脆弱的实现、错误的设计选择、误解——错误会悄无声息地向下游传播。后续叶子建立在有缺陷的产物上，加剧损害。发现为时已晚，迫使进行昂贵的重新规划，回滚整棵或子树。即使是串行重试也是浪费：每次再次支付前缀的全部 token 成本，并且没有机制系统地比较候选者。计划的质量崩溃到其最弱叶子的可靠性，开发者只能把整棵树押注在单个猜测上。

工作方式

• 冻结前缀。 所有 N 次尝试共享直到该叶子的相同上下文——相同的对话历史、相同的中间结果、相同的指令。分歧仅从叶子输入开始，因此 token 开销有界：你大致支付公共前缀一次加上 N 次后缀 token。并发取代了 token 乘法。
• 并行执行。 conductor 标记该叶子为 Best-of-N 并同时启动 N 次独立调用。每次尝试在其自己的模型调用中运行，无共享可变状态。延迟是最慢尝试的挂钟时间，而非总和。
• 裁判组。 每叶子评分函数评估每个完成的尝试沿三个轴——成本（消耗的 token）、质量（正确性、风格、约束遵守）和延迟——每个具有可配置权重（例如质量 0.7，成本 0.2，延迟 0.1）。裁判组可以是规则、schema 验证器或模型调用。只有得分最高的尝试被嫁接到树中；丢弃的 N‑1 次尝试是临时的，对下游不可见。
• 质量门控。 如果每个尝试都低于最低质量阈值，则该叶子整体失败。不会有“最不差”的结果传播。conductor 必须重新规划或升级失败，防止无声退化。

权衡与边界

代价是什么。 并发开销是主要代价：N 次并行调用消耗速率限制余量、工作线程槽和内存。当一个计划中许多叶子同时使用 Best-of-N 时，系统可能饱和并使其他分支饥饿。延迟由最大尝试持续时间加上裁判评估界定，而不是平均值。丢弃的后缀浪费 token——如果后缀相对于前缀较长，token 节省减少。最后，裁判组本身增加延迟，并且如果它是模型调用，则额外增加 token 成本。

不适用的情况。 产生昂贵外部副作用的叶子——数据库写入、邮件发送、支付 API 调用——绝不能使用 Best-of-N。每次尝试都会触发其副作用，并且失败尝试没有事务性回滚。状态依赖的裁判逻辑也会破坏该模式：如果裁判的分数取决于可变的外部状态（例如每次尝试递增的计数器，或尝试完成的顺序），比较变得无效。裁判必须是尝试输出和叶子输入的纯函数。同样，输出无法独立评分的叶子（例如没有评分标准的主观创意文案）是糟糕的候选者；自动裁判会带来虚假的可靠性感。

退化路径。 如果所有尝试都未通过质量门控，则叶子干净地失败——这比一个无声的腐化输出要好。实践中，开发者可以在资源紧张时调低 N（较小的 N 仍然多样化风险），或在解空间特别大时增加 N。顶部尝试之间的分数差距作为信号：如果尝试得分相似，则额外的并发收益甚微；如果它们急剧分化，则嫁接正在起作用。

何时值得使用

• 棘手的算法或重构，解空间宽广。 存在多个可行的实现；其中一个可能处理边缘情况不佳。Best-of-N 并发测试这个空间并选出最干净、最便宜的结果。
• 存在几种合理方法的设计决策。 在事件驱动 vs 轮询架构，或工厂 vs 策略模式之间选择。每种尝试为不同方法辩护，裁判选出最佳权衡。
• 模糊的规格说明，单次通过如同抛硬币。 当提示词留有解释空间时，N 次尝试采样解释空间；裁判选择最连贯或最保守的匹配。
• 任何出了错后期发现代价高昂的叶子。 核心业务逻辑、数据模型 schema、安全边界——一个错误会级联到几十个下游节点。嫁接的并发成本是对更大返工的保险费用。

Best-of-N 嫁接以并发成本换取可靠性：冻结前缀保持 token 成本低廉，且只有胜者存活。

Hashline 是 harness 层的一个验证步骤，用于消除廉价 executor 模型的行偏移错误。其工作机制是：在编辑前后，对每个受影响的代码行及其上下文进行哈希，然后比对。如果目标行的内容在修改后的文件中唯一存在于其他地方，则自动纠正偏移；否则直接拒绝补丁。无需修改提示，不涉及模型，延迟可忽略不计。核心思想：用行自身的内容作为位置锚点，而非模型脆弱的行号猜测。

失败模式

一个廉价 executor 模型（为速度和成本刻意选择而来）常常将编辑位置偏移一行。本应修改第 42 行的指令，最终落在了第 41 或第 43 行。产生的 diff 看起来仍然合理——代码修改语法正确，文件能编译，静态检查通过。错误是不可见的。经过多轮迭代，这些逐行偏移错误会悄无声息地累积：保护条件漂移到错误分支，注释上移一行，函数调用进入不同作用域。代码仍可构建，测试或许仍能通过，但逻辑结构已经腐烂。只有当下游 bug 迫使人们跨轮次历史进行昂贵的溯源追踪时，问题才会暴露。调试那样的混乱局面，其成本远超使用廉价模型节省的计算量。根本原因在于，弱模型将行号当作文本坐标而非语义锚点——它们对 token 级别的空间推理是模糊的，每一次编辑都是一场关于位置精度的赌博。没有机械性的护栏，harness 只能相信模型报告的行号，而这种信任是脆弱的。

工作机制

Hashline 在补丁提交管道中插入一个基于内容的检查，完全在模型调用之外运行：

• 派发前，harness 对编辑应该接触的每一行以及可配置数量的周边上下文行进行哈希。这捕获了每行内容的精确内容（包括空白），并存储行号到哈希的映射。
• executor 返回补丁后，harness 将补丁应用到文件的本地拷贝，并重新哈希相同的逻辑行（按原始位置）。
• 如果每个哈希都匹配，则编辑位置正确，补丁进入提交阶段。
• 如果发生哈希不匹配，harness 会扫描邻域（通常为整个文件），寻找内容哈希与目标行编辑前哈希一致的行。如果恰好存在这样一个行，则自动纠正偏移——编辑被应用到该行。如果零个或多个行共享该哈希，则直接拒绝补丁。
• 模型从未感知到这一步。没有提示修改，没有重训练，没有额外推理。检查在微秒内完成，比模型调用本身快数个数量级。

这一机制将位置精度与模型质量解耦。executor 只需为目标行产生正确的内容；harness 确保该内容落到文件中的正确行。可靠性在模型之外被工程化。

权衡与边界

Hashline 是一个位置护栏，而不是语义护栏。它验证的是编辑落在哪里，而不是编辑本身逻辑上是否正确。一个完美对齐但引入了 bug 的补丁仍然会通过。它补充而非替代其他验证阶段。

哈希唯一性要求。 自动纠正依赖于目标行在文件中具有唯一的内容哈希。如果该行为空、只包含空白，或者与相邻行重复（例如连续的 }) 行），harness 无法区分，会回退到拒绝。这是故意设计的：安全拒绝优于静默误用。实践中，具有独特标识符或注释的非平凡代码行很少发生碰撞，因此自动纠正大部分时间都在工作。对于重复性高的文件（自动生成的头文件、表格数据），拒绝率可能上升。

架构成本。 harness 必须维护一个编辑前的文件快照，以便在应用补丁后重新哈希——这是较小的内存开销，通常已存在于 conductor 的状态管理中。哈希每次编辑增加几微秒，相对于模型推理可忽略不计。

退化路径。 随着重复内容增加，拒绝变得更频繁。每次拒绝都需要重试（conductor 重新派发编辑，可能给更强的模型），但防止了静默损坏。用户可以调整上下文窗口大小；更宽的窗口可以提高唯一性，但也增加了合法编辑到某行上下文时触发虚假不匹配的几率，因此这是一个刻意的权衡。

适用范围。 Hashline 作用于单文件、基于行的编辑。它不适用于全文件重写（“受影响行”失去意义）或跨文件移动。插入和删除被隐式处理：搜索比较的是内容而非绝对位置，因此将目标行下推的插入不会破坏检查。

适用场景

当选择廉价 executor 模型是为了速度或成本而非位置精度时，Hashline 便物有所值。具体场景：

• 迭代、多轮编辑循环——conductor 在一个会话中执行数十个小补丁。没有 Hashline，至少发生一次逐行偏移错误的概率接近确定；有了它，每个补丁都被固定在内容上，而非脆弱的行号。
• 廉价 executor 农场——团队使用小型、快速模型（如 Llama 8B、Gemma、Claude Haiku）进行批量叶子编辑。这些模型成本效益高，但空间推理能力众所周知地弱。Hashline 让它们能够完成原本不可信任的、精确到行的外科手术式工作。
• CI/CD 修复机器人或自动化重构——任何补丁必须正确落地且无需人工检查的流水线。拒绝会立即暴露出失败，而不是将其隐藏在后来才出问题的损坏文件中。
• 混合层级系统——昂贵的 conductor 模型（如 Opus、GPT-4o）配合廉价 executor。如果 executor 放错行，规划者的昂贵推理就白白浪费了；Hashline 将两者解耦，保留了廉价工人的经济优势。

当 executor 模型已经具有近乎完美的位置精度（在短上下文上的顶级模型）或编辑只是重新生成整个文件时，Hashline 用处较小。但其开销如此之小，以至于通常默认保持开启——即使是强模型在极长文件中偶尔也会数错行。

永远不要相信模型数行——让内容哈希作为锚点。

语言服务器集成通过语言服务器协议（LSP）向 executor 提供实时的、结构化的代码库视图。它将“猜测程序”的问题转化为“查询程序”的问题，将智能体的推理从概率文本补全转移到由驱动人类编辑器的同一工具链所提供的锚定符号表。

失效模式

没有 LSP 集成时，executor 基于原始文本操作。每一个符号引用、导入路径、方法签名都必须从周围 token 推断。模型可以生成看起来合理的代码——正确的缩进、熟悉的命名——却悄然破坏不变量。它可能重命名一个函数但遗漏其他文件中的调用点，生成对不存在方法的调用，或者导入从未安装过的模块。这就是“幻觉路径”失效模式：模型自信地构建了一个在代码库中毫无事实依据的现实，而由于文本看起来连贯，智能体内部没有警报。

浪费叠加。executor 可能将整个文件倾入上下文，希望模型能发现相关部分，从而在无关的函数体上烧掉令牌和注意力预算。它可能发出多轮澄清（“parseConfig 的返回类型是什么？”），而这些本可以瞬间回答。最糟糕的是无声的破坏——通过视觉审查但破坏构建或引入微妙语义不匹配的编辑。每一次这样的编辑都需要手动调试，违背自动化的初衷，且脆弱性随着模型参考的文件数量组合级数增长。

工作原理

executor 充当轻量级 LSP 客户端。它不是将文件作为自由文本请求，而是发送定向的、只读的查询，并接收结构化回复：

• textDocument/documentSymbol 返回文件的符号树——名称、种类（函数、类、变量）以及位置范围。
• textDocument/references 枚举整个项目中某符号的所有使用点。
• textDocument/definition 将符号解析到其精确声明位置，包括文件、行和列。

每个查询返回的是 AST 级别的元数据，而不是原始文本。executor 完全基于这些响应构建其内部符号表。模型只能请求 LSP 报告的内容；它无法伪造不存在的定义或调用点。编辑变得锚定：在模型写出一个 token 之前，重命名一个符号就会揭示所有受影响的位置；添加一个函数调用时，目标签名会与实际代码图进行校验。executor 只读取 LSP 指向的文件和行范围——从来不指望通过加载整个文件来对齐上下文——从而大幅减少令牌消耗。

此集成在 LSP 端是只读的，且按语言区分。它从不发送如 textDocument/rename 这类变更操作；仅当相关文件类型有语言服务器运行时才激活。如果没有可用的服务器，executor 回退到基于文本的启发式方法——可靠性较低，但可用。当服务器存在时，结构化查询总是优先。

权衡与边界

语言服务器集成有诚实的边缘。每种语言需要一个运行的 LSP，在服务器索引项目时增加启动延迟。对于短生命周期的单文件任务，开销可能超过收益。回退到文本启发式方法噪音更大、精度更低，因此没有 LSP 的环境（某些动态语言、自定义 DSL）以较低的可靠性运行。

集成严格静态。它提供结构元数据——符号名、类型、引用——但不提供运行时类型、动态分发或元编程模式。一个编译通过但运行时抛异常的方法不会被捕获。模型仍需读取函数体和注释以理解语义；LSP 锚定的是推理的结构，而非其含义。

LSP 服务器本身有差异：有些落后于语言版本，有些省略某些符号种类，有些在大规模索引时崩溃。harness 必须优雅地处理这些情况——超时、重试、降级——绝不让计划无限阻塞。

何时物有所值

每当智能体需要导航包含多个模块的代码库，或生成要求结构精度的编辑时，LSP 集成就能发挥价值。具体触发条件：

• 跨文件重构：重命名一个出现在数十个文件中的符号。引用查询提供受影响位置的明确列表，防止无声遗漏。
• 类型感知代码生成：添加一个必须匹配另一文件签名的函数调用。定义查询揭示精确的参数类型和返回类型，消除猜测。
• 导入管理：documentSymbol 列出模块的导出项，因此智能体无需手动扫描文件即可选择正确的导入路径。
• 提交前验证编辑：后续的引用查询可以验证变更后是否残留悬挂引用。

对于具有简单模式的单文件任务（例如为已知签名生成单元测试），启动成本可能不值得。但只要智能体需要问“这个名称的定义是什么？”或“谁使用了这个变量？”，LSP 就能瞬间、确定地给出答案。

LSP 是静态程序结构的单一事实源——harness 从模型外部工程出可靠性。

MCP 路由器是 Xihe harness 内部的单一入口点，所有模型‑上下文‑协议（Model‑Context‑Protocol）工具调用必须经过此处。它贯彻一个核心思想：将可用工具的目录与其 schema 及结果分离。Agent 看到的是轻量级菜单与紧凑指针；schema 与大型载荷按需获取或存储，从不预加载或倾倒入上下文。

故障模式

没有集中式路由器时，每个 agent 必须在每一轮提示中预加载完整的 MCP 工具 schema——这是一个随着工具目录增长而膨胀的固定成本。单个 schema 可能重达数百 token，十几个工具每轮就浪费 4–8K token 在未使用的元数据上，挤压任务指令与推理空间。这就是无声上下文毒化：不崩溃，只表现为提示词被无关结构填满后响应质量逐步退化。

第二个故障是输出倾泻。当工具返回大型载荷——文件内容、搜索结果、数据库行——它直接落入上下文窗口。上下文单调膨胀，引发延迟激增（模型必须重新消化整个膨胀的历史）、token 溢出和成本失控。由于每个 agent 自主管理工具调用，没有中心点来修剪、计量或审计发生了什么。添加工具让提示更重；执行工具让上下文更大。结果是脆弱的、规模负相关的集成：更强的能力意味着更差的性能，而且往往直到系统崩溃才能察觉。

工作原理

路由器位于 harness 侧，从不在 agent 侧。它通过三个元工具强制统一接口，用可控的按需存取替代原始的 schema 注入。

• 驻留菜单。 启动时，harness 构建一个轻量级工具名称列表及一行描述。这个菜单每个工具只消耗几个 token，作为唯一的静态引用常驻在 agent 上下文中。没有 schema，没有参数——足够让 agent 发现可用工具。
• 按需 schema 加载。 当 agent 决定调用某个工具时，它首先调用 describe(tool_name)。路由器只在此刻才获取该工具的完整 JSON schema，并且只获取这一个。除非 agent 显式请求，schema 永远不会出现在提示词中，因此每轮工具开销比预加载全部工具降低约 70%。
• 三个元工具。 所有 MCP 交互通过 search（按能力发现工具）、describe（获取工具 schema）和 call（带参数执行）进行。路由器从不暴露原始工具注入；agent 无法绕过此接口。Harness 会拦截并拒绝任何直接的 MCP 流量。
• 输出沙箱。 当工具返回大型结果时，路由器将完整载荷存储到外部，并返回一个紧凑指针——标识符加字节大小——替代原始输出。Agent 只看到指针，将大部分内容排除在上下文窗口之外。对于过大结果，这能节省约 98% 的上下文空间。
• 审计边界。 每一次 search、describe 和 call 都在路由器边界记录：agent ID、工具名称、输入大小、输出大小、延迟。Harness 维护单一结构化的审计流，用于计费、调试和治理。Conductor 和 dispatch 对输出体积完全无感；它们调度产生指针而非文档的叶子任务。

开发者体验简单：通过配置映射将 MCP 服务器注册到路由器。添加或移除工具时无需更改 agent 代码。路由器的菜单在 harness 初始化时自动更新。

权衡与边界

按需 schema 加载在第一次使用某个工具时会增加一次额外的 describe 往返。对于重复调用同一小工具集的 agent，此开销相比 LLM 推理时间很小，但并非零。极低延迟管线（每轮 <200 ms）可能感受到成本；其他所有情况下，token 节省都超过它。

路由器是单点故障。如果路由器进程宕机，没有 agent 能调用任何 MCP 工具。Harness 本身就已是关键组件，因此通常可以接受，但高可靠性部署应规划备用或优雅降级路径——例如回退到无沙箱的静态菜单。

输出沙箱依赖外部存储（内存、文件或对象存储）。如果该存储不可用，路由器无法返回有效指针。必须显式制定回退策略：要么让工具调用失败，要么允许内联输出并附带警告。约 98% 的节省仅适用于大型输出；结果本就低于沙箱阈值时直通传递，不产生节省。

路由器不强制工具认证或授权——那是 MCP 服务器的职责。它也不对工具排序或决定调用哪个工具；那是 agent 推理循环的决策。最后，路由器不能替代整体上下文窗口管理。重复调用同一工具且保留旧指针仍会导致上下文增长，因此 conductor 仍需要应用摘要或驱逐策略。

何时发挥价值

MCP 路由器一旦 agent 使用超过三个 MCP 工具，或任何工具经常返回数百 token 以上输出时，就能收回成本。它在以下场景不可或缺：

• 多个 agent 共享一个不断增长的工具集（代码库搜索、文件 I/O、API 客户端），预加载所有 schema 会消耗 5–15% 的上下文窗口。
• 工具产生可变且常为大型的结果——文件内容、数据库转储、搜索结果——单个过载载荷可能毒化整轮交互。
• Token 预算紧张，无论是出于成本约束还是小模型上下文窗口的限制。
• 每次工具调用都必须接受合规、成本分配或回放调试的审计。
• 多个 agent 使用同一组 MCP 服务器；路由器提供单一的计量、沙箱化接口，并防止跨 agent 上下文污染。

相反，一个只有两个工具、输出小于 500 字节且无审计需求的原型只会看到额外开销。路由器的价值在规模下显现——恰恰在朴素 MCP 模式开始失效之时。

MCP 路由器将 MCP 从每轮固定开销转变为按次计费——在 harness 网关处计量、沙箱化、可审计。

没有上下文模式时，每一个确定性子任务都迫使LLM摄入原始数据，在概率环境中执行算术、模式匹配或逻辑操作。这种做法的失败具体体现为三点。第一，令牌浪费和上下文膨胀：原始文件消耗了本应用于规划的预算，导致conductor随着上下文窗口被噪声填满而忘记早前的步骤。第二，静默数据幻觉：模型以高置信度错误计数、捏造数字或错位对齐列，而无验证性追踪，错误便不可见地传播到下游推理中。第三，不可重现的输出与审计性丢失：自然语言推理是不透明的；评审者无法重放计算以找出错误，而一个幻觉摘要看上去和真实摘要一样可信。框架将确定性工作交给了最不合适的组件，使得每项此类任务都成为可靠性地雷，在不触发崩溃的情况下毒化agent的输出。

工作机制

框架检查conductor生成的计划，并分类那些其结果仅依赖于已知数据上的确定性计算的叶子任务（如计数匹配、差异比较、列聚合、结构化输出格式化）。当查询足够明确时，框架将任务路由至沙箱化的executor——此决策可以是每个任务单独设置，也可以是全局设置，并且由dispatch层强制执行，dispatch层是确定性代码，而非LLM。

• 脚本生成。agent编写一段短小、自包含的脚本，包含显式输入路径、内联注释、类型注解和断言。这些元素构成了推理过程中的痕迹：代码本身就是思考。
• 沙箱执行。脚本在隔离环境中运行（无网络、只读文件系统、资源限制）。只有标准输出和退出码可以跨越边界。沙箱拒绝副作用并强制执行超时。
• 结果压缩。框架捕获标准输出（通常是一个单一值、JSON或表格），并将其作为压缩后的事实转发给conductor。非零退出码或超时则变成显式、结构化的失败信号——绝不会是一个猜测性的摘要。
• 完整审计追踪。脚本源代码、调用时间戳、退出码和输出都被记录在外部。任何开发者都可以在之后重放该确切计算，从而将推理从不透明的散文转化为可重现的制品。
• 歧义时回退。当任务需要细微的语义判断、主观评估，或者agent的脚本不可恢复地失败时，框架会静默降级为标准上下文读取。降级对conductor透明，但记录在日志中，以额外的令牌开销换取正确性。

权衡与边界

上下文模式带来了真实的成本。延迟：沙箱启动和脚本生成对于琐碎查询（如“统计一行单词数”）可能显得不成比例。令牌开销：生成正确代码会消耗输出令牌——这是用前期的令牌支出来换取后期的正确性和可审计性。agent能力：小型或非编码模型可能生成有问题的脚本，被迫回退而浪费时间。安全性是强制性的：沙箱必须禁止写入、网络访问和无限循环；配置错误会将代码执行变成危险向量。不适合细微判断：该模式完全不能处理诸如语气分析或风格评判等开放型任务。如果强行使用，脚本只会返回空洞的机械答案（例如，因为只检查了字符串相等而返回“0处差异”）。红线是：当上下文模式激活时，原始文件内容绝不能进入上下文；框架必须拦截并剥离任何意外数据。降级路径显式失败：如果脚本出错，框架不会盲目重试，而是升级到标准读取，增加延迟但避免静默损坏。正确分类歧义仍然是一门工程艺术，而非解决了的算法——过于激进的分配会产生脆弱的失败，而过于保守的分配则浪费令牌。

适用场景

上下文模式在每一个针对结构化或半结构化数据的具体、可验证的问题中都值得使用。具体例子：在代码库中统计模式出现次数（PR评审）、比较两个配置文件或API响应的差异、将CSV格式化为嵌套JSON结构、聚合多个日志文件中的指标，或从值超过阈值的行中提取第三列。在多步DAG中，当中间计数、总和或约束检查必须在下一步骤之前精确完成时，它同样大放异彩——例如，计划重构的conductor首先需要已废弃API调用的精确计数。在审计关键的环境中，脚本是一个可重复的复现器，输出是一条单一的确定性行。这种模式消除了“幻觉数字”这类错误类别，这类错误在评审中看似合理，却会侵蚀对整个系统的信任。

上下文是用于压缩的预算，而不是扩展的对象——编写工具，而非文档；让代码承载精确性，把最擅长的事情留给模型。

该框架（harness）将智能体工作分解为三个硬边界层——Conductor、Dispatch、Executor——每一层都与具体模型解耦。其核心思想是：可靠性是控制流的一种工程属性，而非精心提示的副产品。通过强制将规划、路由和执行分离为不同角色，框架消除了使模型驱动管线脆弱的纠缠。

The failure mode

没有这三层分离，智能体循环就会坍缩为单体，同一个模型决定做什么、何时做以及如何恢复。这种耦合滋生了一系列失败：

• 共享状态上的竞态条件。 提示中看似独立的两个子任务可能在没有协调的情况下更新同一个可变上下文（文件句柄、进度计数器）。没有比较并交换（CAS）门控，它们会交织并损坏彼此的数据，产生看起来合理但逻辑不一致的输出。
• 静默损坏。 一个leaf返回了错误但格式正确的结果。没有独立层验证它；错误向下游传播，开发者看到的是看似正确的最终答案。损伤不可见。
• 浪费推理。 单一模型为一次leaf级别的失败重新规划整个任务，燃烧token和延迟重新推理已经正确的工作。或者，系统因缺乏明确的重新规划词汇而无限重试同一提示。
• 模型锁定。 每一步都在同一个模型上运行，因为没有路由层。廉价的快速模型无法用于常规leaf，而重推理模型只负责规划——成本和品质被锁在一起。
• 脆弱的恢复。 当模型本身既规划又执行时，失败与意图变更无法区分。系统要么盲目重试，要么彻底放弃。

所有这些失败都是编排层面的失败，而非模型质量的问题。该框架通过为每个职责分配一个独立的、确定性的所有者来解决这些问题。

How it works

该框架以铁一般的边界强制执行三个角色：

• Conductor 接收用户意图并返回一个由原子leaves组成的有向无环图（DAG）。每个leaf定义一个工作单元——一个提示模板、一个模型绑定（Opus、Codex、GLM）和一个失败阈值。Conductor是推理密集型且可热替换；你可以更换规划模型而不触及框架的其他部分。它从不接触执行，从不读取模型输出，从不消费原始token。其产品只有DAG。
• Dispatch 是确定性的框架代码，不带模型参与循环。它轮询DAG中依赖已满足的leaves，按拓扑分层，在有限并发下扇出。每个leaf被路由到其预绑定的模型。状态转换——就绪、飞行中、完成、失败——通过比较并交换（CAS）进行门控，以防止双重分发或竞态。Dispatch从不规划、从不验证输出、从不调用模型。其职责严格限于排序和路由。
• Executor 在其分配的模型上原子运行单个leaf。它接收leaf定义和来自其依赖的预计算输入，调用模型，并返回结构化输出或失败信号。它完全不可见DAG、之前的leaves或整体计划。它是廉价的、无状态的，并且可大规模并行。Executor不验证——它们只返回二元通过/失败。

关键循环：当一个executor发出失败信号时，dispatch将该leaf标记为失败，停止该分支的DAG，并将控制权返回给conductor。然后conductor重新规划——重新划分子DAG、更换模型或完全中止意图。失败绝不会静默通过dispatch门控；它总是重新进入推理层。

Trade-offs & boundaries

分离并非免费：

• DAG构建开销。 每个任务，即使是琐碎的，至少需要一次conductor调用来生成初始计划。对于单步操作，这会增加延迟和成本而无益处。
• 重新规划延迟。 失败的leaf必须冒泡到conductor，被重新推理，并产生新的子DAG才能恢复执行。对于失败率低的工作流，间接层可能过于繁重。
• 粒度负担。 开发者必须将意图分解为真正原子的leaves。过于粗糙的leaf浪费重新规划周期；过于细碎的leaf膨胀DAG并增加dispatch开销。没有自动的合适尺寸。
• 验证者补上“看似合理”的缺口。 一片 leaf 可能返回看似合理但错误的结果，executor 自己的 pass/fail 信号抓不到。验证者——一个 model-agnostic 的跨模型怀疑者，默认关闭——在 DAG 跑完后审查结果；发现真问题时 conductor 静默升级到更强模型并重规划。opt-in：不配置它，返回的结果即算成功。
• 确定性的局限。 Dispatch的CAS门控保证每个leaf恰好运行一次，但并发分发的时序是非确定性的。如果leaves修改共享外部资源，顺序仍可能导致竞态——该框架不提供外部状态的事务安全性。
• Conductor退化。 如果conductor本身反复失败（错误指定DAG、遇到速率限制），系统退化到硬错误。没有优雅的部分输出；要么计划完成，要么不完成。

红线是绝对的，违反它们将使可靠性保证失效：Dispatch从不规划，Executor从不验证，Conductor从不消费原始模型输出。如果Conductor曾经接触leaf输出，它将重新引入该框架旨在消除的静默损坏路径。

When it earns its place

这种架构在以下场景中物有所值：

• 工作流跨越多个模型，具有不同的成本/延迟特征——例如，一个推理密集型规划器、一个用于批量操作的快速执行器，以及一个用于代码生成的专家模型。每个leaf预绑定到正确的模型。
• 独立子任务可以并行运行（例如，为同一个函数生成测试、文档和桩代码）。有限并发防止资源饱和，同时充分利用并行性。
• 高正确性要求不可妥协——金融、法律或安全关键任务，静默传播错误是不可接受的。重新规划循环确保每个失败都在推理层面被诊断。
• 你需要可审计的可追溯性——每个leaf的输入、输出和失败历史被记录，DAG为调试提供完整的溯源记录。
• 你预期模型不稳定，并希望拥有一个容错系统，其中重试或模型切换发生在计划层面，而不是在不透明的提示循环中。

规划者规划，路由者路由，执行者行动——失败回归推理层面，绝非模型在环重试。

Web 栈是一个 harness 级别的资源，通过将整个检索管道——查询、故障切换、内容提取和大小沙箱——放在模型之外，把互联网变成研究级信号。其核心前提：Web 检索中每个脆弱环节都在 harness 中工程化实现，而非通过提示塞给 LLM。conductor 发出搜索意图，栈自主返回干净、有界的文本摘录；模型从不解析 HTML、处理 API 密钥或推理缺失的供应商问题。

失败模式

没有 Web 栈，任何需要在线信息的 agent 都会陷入无声失败模式。单一供应商依赖意味着一个过期或耗尽的 API 密钥就会停止所有检索，而且往往没有明确信号——模型收到空字符串或错误页面，继续在噪声上推理。手动 URL 策划或基于提示的搜索迫使 conductor 猜测链接或依赖模型解析混乱的 HTML，导致上下文被导航和广告膨胀。超大页面随即撑爆上下文窗口：一篇包含大量模板代码的文章可能在出现任何事实之前就消耗数千 token，触发静默截断或用无关内容淹没信号。由于检索被视为模型内部问题，脆弱性会叠加——恢复逻辑、重试提示和幻觉回退都浪费推理预算并污染下游结论。harness 缺失，因此可靠性依赖于脆弱且无声失效的工具调用链。

工作原理

Web 栈作为单个 harness 级别资源运作，由 conductor 用搜索意图调用。无需手工喂 URL，无需恢复提示。它封装了三个自主机制：

• Provider rotation – 自动轮换搜索后端池（Bing、SerpAPI、自托管端点）。当供应商 API 密钥缺失或耗尽时，该后端被静默跳过。只有在池中所有供应商都不可达时，栈才返回结构化的“无结果”信封。降级是优雅的：缺失的密钥从不破坏检索，conductor 永远看不到故障切换。
• Content extraction – 每个抓取的页面通过类 Trafilatura 的提取器缩减为文本信号，丢弃导航、广告、模板代码和格式。输出是干净的段落和标题块，剥离到语义核心。如果提取的文本超过可配置的大小阈值，MCP 输出轴会自动对其进行沙箱处理。下游 agent 接收修剪后的摘录或压缩引用——永远不会是可能溢出上下文或引入噪声的原始 DOM。
• Model‑agnostic reliability – 搜索调度、供应商故障切换、提取和沙箱都在模型循环之外发生。harness 掌握机制，因此模型始终专注于决策。检索是确定性的：conductor 发送意图，栈返回带有来源元数据的结构化文本片段。

权衡与边界

Web 栈的设计经过深思熟虑，其边缘是诚实的。

• 延迟开销 – 轮换供应商和抓取完整页面每次查询都会增加网络时间。栈用绝对速度换取有保证的结构化信号；它不适合亚秒级交互循环。
• 内容提取有损 – 类 Trafilatura 的提取器在静态、结构良好的 HTML 上效果最佳。它丢弃图像、布局和交互元素，且无法执行 JavaScript。动态内容（单页应用、懒加载文本）可能极小或缺失。需要视觉证据或原始页面布局的工作流将得不到有用结果。
• 沙箱是粗粒度工具 – 超大内容被截断而非智能摘要。低阈值可能丢失细微差别；高阈值仍可能给上下文窗口带来压力。可配置的大小限制需要针对所用模型进行调优。
• 结果质量取决于供应商相关性 – 栈按原样返回搜索供应商的顶部结果。它不重新排名、不过滤垃圾信息、也不补偿低质量索引。返回噪声结果的降级供应商会把噪声送入提取，而无信号质量检查。
• 网络和密钥依赖 – 池中必须存在至少一个有效供应商密钥。如果所有密钥耗尽或配置错误，则返回结构化的“无结果”信封，conductor 必须显式处理该情况（例如，回退到本地知识或将该分支标记为未解决）。栈不会无限重试，也不会在空信封之外发出警报。
• 无交互或流式页面 – 栈每个结果抓取一个静态 URL。它无法跟踪分页链、处理表单提交或维护已验证会话。它是单次、文本优先的提取器，而非通用 Web 浏览器。

红线：栈永不暴露原始 HTML、永不解释 JavaScript、永不绕过大小沙箱。conductor 不能在单次请求基础上覆盖沙箱或要求特定供应商。

何时物有所值

Web 栈在以下场景中回报巨大：研究广度大、上下文预算紧张，且 conductor 必须基于实时、未策划的来源来制定计划，同时避免脆弱的逐个 agent 集成。

• 研究密集型计划 – 需要从多个站点验证事实或跨域收集文档的 conductor 可以将搜索意图作为 DAG 步骤发出；栈处理并行检索、故障切换和修剪，使 token 消耗可预测。
• 长时间运行的自主 agent – 在运行数小时的循环中，单个超大页面的代价呈指数增长。强制性沙箱能防止上下文窗口随时间累积爆炸。
• 多步骤综合或报告 – 干净的提取文本可直接输入摘要 executor 或 verifier，无需预处理。无需手动 URL 白名单或提示工程化的恢复逻辑。
• 拥有多个搜索供应商的环境 – 通过池化 Bing、SerpAPI 和自托管端点来避免供应商锁定的团队获得韧性：一个密钥过期不成问题，检索持续进行直到所有供应商耗尽。
• 之前需要手工策划 URL 的场景 – 如果工作流需要人类预选页面或脆弱的脚本去爬取，Web 栈用单个意图调用替代之，让 conductor 留在其规划车道上。

harness 拥有检索，这样模型就永远不必协商速率限制或解析 <div>。