Reef Infra：用显式请求驱动AI优化器的harness变更

为什么追踪数据不足以驱动所有变更

在自动化AI优化系统中，一个常见的假设是：系统通过观察使用过程中的失败痕迹（usage traces）来发现问题，再据此调整。这种模式在应对重复性故障时非常有效——追踪数据会清晰暴露同一类错误反复出现的模式。

但这里存在一个结构性盲点。追踪数据只能反映已经发生的行为，它无法包含某个人刚刚决定采纳的新需求。当团队约定了一套全新的输出模式（output schema），如果还要等待用户在旧模式下累积足够多的失败，才让系统"察觉"到需要改变，这显然是一种荒谬的沟通方式。需求本身是一个有意图的决定，而非一次次故障的自然产物。

这正是 Reef Infra 试图解决的问题：它为自定义 harness 方法提供了两种模式——手动（manual）与混合（hybrid），让"主动请求"成为触发变更的第一类输入。

**使用追踪（usage traces）**是指系统在运行过程中自动记录的输入输出日志、错误信息与执行路径，是当前主流LLM优化框架（如DSPy、TextGrad等）的核心反馈来源。这类数据天然适合发现"已有行为的缺陷"——例如某类查询的答案格式一直不稳定、某个推理步骤频繁出错——因为这些问题会随着时间积累形成统计显著的信号。然而追踪数据的有效性完全依赖于"问题已经发生过"这一前提。在产品迭代速度较快的场景下，团队往往需要在新需求落地的当天就完成系统调整，而不是等待旧行为积累足够多的失败样本。这种时序上的错位——需求在前、数据在后——是纯追踪驱动架构的根本局限，而非工程实现层面可以修补的细节。

手动模式与混合模式的分工

Reef Infra 的设计核心在于区分两种性质不同的输入来源。

手动模式：纯粹的意图输入

在手动模式下，proposer（提议器）接收到的是一个排队中的请求（queued request），以及一个空的样本列表。换句话说，这个变更完全由意图驱动，不依赖任何近期的执行上下文。当你有一个明确的、新达成共识的需求时，手动请求可以直接发起这次改变，而无需任何失败案例作为前提。

混合模式：意图与观察的结合

混合模式则更进一步。它会从下一个自动批次（automatic batch）中附带一部分样本，让请求在抵达时带有近期的执行上下文。这意味着提议器既能看到"有人想要什么改变"，又能参考"系统最近实际在怎么运行"。这种设计让自定义方法同时拥有两个职责不同的输入：观察到的行为与改变它的有意图请求。

两种模式的价值在于，它们把"新需求"从报告流（report stream）中解耦出来。你不再需要让每一个新需求都伪装成一连串失败案例，才能被系统接收。

显式契约：requests 关键字参数

Reef Infra 在工程实现上设置了一条明确的契约（explicit contract）：自定义方法必须声明一个 requests 关键字参数。

这里有一个容易被忽视但设计精妙的细节——一个通用的 **kwargs 是不够的。如果你试图用 **kwargs 来笼统接收参数，recipe 会在启动时直接拒绝该配置。

**Fail-fast（快速失败）**是软件工程中一种防御性设计原则，主张系统在检测到配置或接口错误时应立即终止并报错，而不是带着潜在问题继续运行。与之相对的"静默失败"会让错误在系统深处潜伏，最终以难以复现的运行时异常暴露，排查成本极高。在可组合的优化流水线中，各组件之间的接口契约尤为重要——一个上游组件悄悄丢弃了某个字段，可能要等到下游组件执行数十步之后才会引发可见错误。强制要求显式声明 `requests` 参数，而非接受宽泛的 `**kwargs`，正是将接口合规性检查前移到启动阶段，把"配置错误"与"运行时错误"严格区分开来。这对于团队协作中多人接入自定义优化器的场景尤其有价值，能有效防止因参数命名约定不一致导致的隐性错误。
# 不被接受：
def my_method(**kwargs):
    ...

# 被接受：
def my_method(requests=None, samples=None):
    ...

从开发体验角度看，这是一种"有用的早期失败"（a useful failure to get early）。当你在接入自己的优化器时，系统在启动阶段就明确告诉你契约不符，而不是让问题潜伏到运行时才以难以排查的方式爆发。这种 fail-fast 的设计，在构建可组合的优化流程时能显著降低调试成本。

评估与发布策略仍然掌舵

值得澄清的一点是：手动请求能够发起变更，但并不意味着它能绕过系统的治理机制。原有的评估（evaluation）与发布（publication）策略仍然决定着这些被提议的编辑最终会发生什么。

这是一个重要的权力边界设计。请求只是打开了变更的入口，赋予了自定义方法一个主动的起点；但变更是否真正生效，依旧要经过既定的评估流程把关。这样既保证了需求能够及时、直接地进入系统，又不会让主观意图凌空于质量控制之上。

在自动化AI优化系统中，评估（evaluation）与发布（publication）策略通常构成变更生效的最终关卡。评估策略负责对提议的编辑进行质量度量——常见手段包括在保留集（held-out set）上运行基准测试、与当前版本做A/B对比、或通过人工标注进行偏好判断；发布策略则决定何种条件下评估通过的变更会被写入生产配置，例如"必须在所有核心指标上不低于基线"或"需经过人工审批"。将请求入口与发布门控分离，是一种典型的"关注点分离"设计：请求层只负责表达意图，治理层只负责质量把控，两者互不越权。这种架构使得团队可以独立调整各自的策略——例如在实验阶段放宽发布门控以加快迭代，而无需修改请求接入逻辑。

对AI工程实践的启示

Reef Infra 这套机制背后的理念，对更广泛的AI系统工程有参考意义。

当前许多自动化优化、自我改进（self-improvement）系统过度依赖反馈数据驱动，默认"一切变更都应来自观测"。但现实中，产品决策、协议升级、schema 变更往往是先于数据的主动选择。一个成熟的系统架构，应该同时为"数据驱动的修正"和"意图驱动的变更"提供清晰的通道，而不是把所有需求强行塞进同一条报告流里。

通过将请求作为显式的第一类输入，并辅以严格的接口契约与不可绕过的评估策略，Reef Infra 展示了一种更务实的平衡：既尊重人的主动意图，又不放弃系统的质量保障。对于正在搭建自定义优化器或 harness 的工程团队来说，这是一个值得借鉴的设计模式。