面向科研 Agent 的 Harness 实验条件固定与复现

面向科研 Agent 的 Harness 实验条件固定与复现：从「复现玄学」到「100% 可验证」

一、引言 (Introduction)

1.1 钩子：所有科研人都踩过的「复现坑」

你是否有过这样的经历：花了3个月调出来的Agent实验，跑出了比SOTA高5个点的准确率，写论文的时候把环境、参数、步骤写了满满3页附录，结果审稿人复现的时候，要么依赖装不上，要么跑出来的结果比你低10个点，直接给你打了个「拒稿，实验不可复现」？
你是否试过下载了顶会论文的开源代码，按照README跑了10遍，结果没有一次能复现论文里的结果，最后怀疑是自己的机器有问题，甚至怀疑作者的数据是编的？
2023年斯坦福大学的一项调研显示：大模型Agent相关的科研论文中，仅有27%的实验可以被第三方成功复现，剩下的73%要么环境依赖冲突，要么参数存在隐式默认值，要么大模型API静默更新导致交互结果完全不同，甚至有12%的论文连作者自己都复现不出投稿时的结果。
这就是当前科研Agent领域最严峻的「复现危机」：当实验的变量从传统机器学习的「数据集+模型参数」变成Agent的「环境依赖+模型版本+工具调用时序+随机种子+外部API响应+操作系统调度」时，传统的实验记录方式已经完全无法满足科研可复现性的要求。

1.2 问题背景：为什么科研Agent的复现格外难？

科研Agent和传统的机器学习模型有本质的区别：传统模型是「输入-输出」的静态函数，只要固定数据集和参数，结果就可以复现；而Agent是「多轮交互+动态决策+外部工具调用」的闭环系统，任何一个环节的微小变化，都会被放大成最终结果的巨大差异。
我们统计了科研Agent实验中最常见的不可复现来源：

1.3 文章目标：你能从这篇文章学到什么？

读完本文，你将：

1. 理解科研Agent实验可复现性的核心要求，以及传统工具的局限性；
2. 掌握Harness框架的核心设计思路，从0到1搭建一套属于自己的可复现实验体系；
3. 拿到开箱即用的开源Harness代码，直接应用到你的科研项目中；
4. 避开90%的科研Agent复现坑，学会从实验设计阶段就考虑可复现性。
   本文会从基础概念讲起，配合完整的架构图、代码、实战案例，即使你是第一次接触Agent实验管控，也能快速上手。

二、基础知识/背景铺垫 (Foundational Concepts)

2.1 核心概念定义

在正式讲解Harness之前，我们先统一几个核心概念的定义：

2.1.1 科研Agent

指用于科学研究的智能体系统，通常具备以下能力：

• 大模型驱动的自然语言理解与决策能力；
• 多轮交互能力（和用户、工具、环境交互）；
• 工具调用能力（调用搜索引擎、代码解释器、科学计算库等）；
• 任务闭环能力（自主完成数学推理、代码编写、科学实验等复杂任务）。
  科研Agent的核心评价指标是任务成功率、推理准确率、工具调用正确率等，这些指标的稳定性直接决定了科研结论的可靠性。

2.1.2 实验可复现性

计算机领域的实验可复现性分为三个层级：

1. 可重复（Repeatable）：同一个团队、同一个环境、同一个人跑，结果一致；
2. 可复现（Reproducible）：不同团队、不同环境、不同的人跑，结果一致；
3. 可复用（Reusable）：实验的代码、数据、环境可以直接被其他研究人员用于新的实验。
   本文我们讨论的是最高要求的「可复现」，也是科研论文必须满足的基本要求。

2.1.3 实验Harness

Harness直译为「线束、支架」，在软件工程领域指的是包裹目标系统的控制框架，可以固定目标系统的输入、环境、执行流程，采集输出结果。
面向科研Agent的Harness，就是专门包裹Agent实验的控制框架，核心能力是：

• 全链路固定实验条件；
• 隔离实验环境；
• 自动采集全量实验数据；
• 生成可验证的实验快照。

2.2 传统实验管控工具的局限性

很多人会问：我已经在用Docker、MLflow、Weights&Biases这些工具了，为什么还需要专门的Agent Harness？我们做了一个全面的对比：

三、核心内容/实战演练：从零搭建科研Agent Harness

这是本文的核心部分，我们会带着你从零开始搭建一套完整的科研Agent Harness，每一步都有代码和架构图支撑。

3.1 需求分析：Harness需要固定哪些实验条件？

要实现100%的复现度，我们需要把Agent实验的所有变量全部固定，没有任何隐式的可变因素。我们把变量分为5层，从下到上依次是：

1. 环境层：操作系统版本、系统依赖、Python版本、Python依赖包版本、环境变量；
2. 模型层：大模型权重/API版本、模型参数（temperature、top_p、max_tokens等）、分词器版本；
3. 交互层：工具调用的请求/响应、外部API的请求/响应、数据集内容、用户输入；
4. 控制层：全局随机种子、Agent的执行逻辑、决策流程、多轮交互的时序；
5. 度量层：指标计算逻辑、评判标准、结果统计方法。
   Harness的核心就是把这5层的所有变量全部固化，任何一层的变化都会生成不同的实验指纹，只要指纹相同，实验结果就一定相同。

3.1.1 实验唯一指纹的数学模型

我们用SHA256哈希算法生成实验的唯一指纹，公式如下：
F = S H A 256 ( H e n v ∥ H m o d e l ∥ H i n t e r a c t ∥ H c o n t r o l ∥ H m e t r i c ) F = SHA256(H_{env} \parallel H_{model} \parallel H_{interact} \parallel H_{control} \parallel H_{metric})F=SHA256(Henv​∥Hmodel​∥Hinteract​∥Hcontrol​∥Hmetric​)
其中：

• H e n v H_{env}Henv​是环境层所有变量的哈希值；
• H m o d e l H_{model}Hmodel​是模型层所有变量的哈希值；
• H i n t e r a c t H_{interact}Hinteract​是交互层所有变量的哈希值；
• H c o n t r o l H_{control}Hcontrol​是控制层所有变量的哈希值；
• H m e t r i c H_{metric}Hmetric​是度量层所有变量的哈希值；
• ∥ \parallel∥表示字符串拼接。
  只要两个实验的指纹F FF相同，我们就可以认为它们的实验条件完全一致，结果应该完全相同。

3.1.2 复现度的计算模型

我们用复现度R RR来衡量复现实验和原始实验的一致性，公式如下：
R = ∑ i = 1 N I ( ∣ M i r − M i o ∣ < ϵ i ) N R = \frac{\sum_{i=1}^{N} I(|M_i^r - M_i^o| < \epsilon_i)}{N}R=N∑i=1N​I(∣Mir​−Mio​∣<ϵi​)​
其中：

• N NN是实验的度量指标总数；
• M i r M_i^rMir​是复现实验的第i ii个指标值；
• M i o M_i^oMio​是原始实验的第i ii个指标值；
• ϵ i \epsilon_iϵi​是第i ii个指标允许的误差阈值（比如准确率的阈值可以设为0.1%）；
• I II是指示函数，满足条件返回1，否则返回0。
  当R = 1 R=1R=1时，说明实验完全复现成功。

3.2 架构设计：Harness的分层架构

我们设计的Harness采用分层架构，每一层负责固定对应的变量，各层之间解耦，方便扩展。架构图如下：