Upsonic 应用科学家预置智能体 Evaluate 技能实战用机器可读 JSON 完成基准对比与实验裁决【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant导读Evaluate 是 Upsonic 预置的「应用科学家」Applied Scientist自主智能体实验流水线Phase 0 → Phase 5的收官阶段负责把 Phase 3 的基线指标与 Phase 4 的新方法指标汇总成一份机器可读的最终裁决报告result.json并同步更新实验登记表experiments.json、跨实验对比表comparison.json与分阶段日志log.json。读完本文你将掌握四类裁决BETTER / WORSE / INCONCLUSIVE / FAILED的判定逻辑、result.json的逐字段 schema 规范、三个配套 JSON 文件的更新协议以及仓库源码中ExperimentResult、ExperimentRecord、ExperimentRegistry对这份报告的读取与渲染机制可以直接在你的研究型 Agent 工作流中复刻这套诚实、可审计、可程序化消费的实验评价体系。一、Evaluate 技能在实验流水线中的位置为什么实验的产出是一份 JSON 裁决在展开 Evaluate 的细节之前先看它所在的上下文。应用科学家智能体的核心职责在 system_prompt.md 中被概括为一句话take what we have, take whats new, try the new thing, and tell us if its better把现有的拿走把新的拿来试试新东西然后告诉我们它是否更好。一次完整实验被拆成 6 个阶段每阶段对应一个技能目录SKILL.md阶段名称对应技能文档Phase 0Setup环境搭建experiment_management/SKILL.mdPhase 1Analyze Current分析基线analyze_current/SKILL.mdPhase 2Research研究新方法research/SKILL.mdPhase 3Benchmark定义对比框架benchmark/SKILL.mdPhase 4Implement实现并运行新方法implement/SKILL.mdPhase 5Evaluate对比、裁决、出报告evaluate/SKILL.mdEvaluate 就是最后一步盖棺定论的环节。它的 Purpose 在 evaluate/SKILL.md 中写得很明确Compare baseline and new implementation results. Produce the machine-readable final reportresult.json, updateexperiments.json, and append a row tocomparison.json.这里有一个贯穿全系统的设计哲学实验的产出不是代码而是一个决策。整条流水线中所有簿记文件progress.json、log.json、result.json、experiments.json、comparison.json全部是合法 JSON绝不使用 Markdown 报告。这样做的目的是让仪表盘、CLI 和 Jupyter notebook 都能直接轮询和渲染实验结果实现人机双读。二、输入参数Evaluate 需要什么Evaluate 技能接受两个输入参数见原文档 Input 表参数类型说明experiment_pathpath实验目录即experiments/{research_name}/research_namestring本次实验的名称必须逐字使用调用方给定的名字不得改名、不得加后缀、不得从论文标题重新推导research_name的逐字使用约束是全系统规则CRITICAL RULES 第 9 条实验文件夹名与所有 JSON 文件中的name字段都必须精确一致。在源码层agent.py 中的Experiment类保存了这份 name并通过ExperimentRecord/ExperimentRegistry以该名字为键去定位磁盘上的result.json、progress.json、log.json。另外要注意Evaluate 的所有输入都只来自磁盘上的既有文件——指标来自log.jsonPhase 3 的基线项 Phase 4 的新方法项实验目录在 Phase 0 已经创建完毕。因此 Evaluate 阶段不再需要接触原始 notebook 或数据这也符合系统NEVER modify original files的第一铁律。三、六步行动总览原文档将 Evaluate 拆为 6 个动作先建立全局视图收集全部指标从log.json读取 Phase 3 基线条目与 Phase 4 新方法条目。判定裁决得出BETTER/WORSE/INCONCLUSIVE/FAILED之一。写result.json按精确 schema 输出最终机器可读报告字段不得留空未知值用null。更新experiments.json将状态置为completed或failed补齐verdict、key_metric、baseline_model、new_method。更新comparison.json文件不存在则先创建{experiments: []}然后追加一行汇总记录。回写log.json追加 Phase 5 条目收尾整个实验。下面逐一展开。四、第一步与第二步收集指标、判定裁决收集指标Step 1的动作很直接log.json是贯穿 6 个阶段的唯一结构化日志Phase 3 的 Benchmark 条目里存有每个指标的baseline值与needs_computation标记参考 benchmark/SKILL.md 中的metrics[]结构Phase 4 的 Implement 条目里存有metrics字典与新方法实测值参考 implement/SKILL.md。Evaluate 只需要把这两处数据取出来配对无需重新运行任何 notebook。判定裁决Step 2是 Evaluate 的核心智力动作四类结论的语义如下verdict触发条件BETTER新方法在多数关键指标上优于基线WORSE新方法在多数关键指标上劣于基线INCONCLUSIVE结果混杂或差异落在噪声范围内FAILED实验无法产出可对比结果依赖安装失败、实现崩溃、数据不兼容注意两个要点多数majority意味着裁决不是看单一指标而是看指标集合的整体方向这要求 Phase 3 定义的对比指标足够全面分类任务建议 accuracy / precision / recall / F1 / AUC-ROC回归任务建议 MSE / RMSE / MAE / R²另外都建议计入训练时间training_time_seconds。FAILED不是白干一场系统提示词明确指出A failed experiment is more valuable than a fake success失败实验比伪造的成功更有价值。依赖失败、实现崩溃、数据不兼容都会走 FAILED 路径但依然要产出合法的result.json。五、第三步result.json完整 Schema 与字段规则result.json是实验的最终交付物也是是否应该切换到新方法这一问题的机器可读答案。原文档给出了精确 schema这里完整保留并逐字段注释{ name: {research_name}, verdict: BETTER, summary: 2-3 paragraphs explaining what the new method does, how it fundamentally differs from the baseline, and what trade-offs it makes., explanation: 2-3 sentences explaining WHY this verdict was reached. Reference specific metrics and their differences. Be concrete — mention numbers, not vague statements., comparison: { metrics: [ { name: accuracy, current: 0.853, new: 0.872, diff: 0.019, diff_display: 0.019, unit: null, higher_is_better: true, better: new }, { name: training_time_seconds, current: 2.0, new: 45.0, diff: 43.0, diff_display: 43.0, unit: seconds, higher_is_better: false, better: current } ] }, file_locations: { current_notebook: experiments/{research_name}/current.ipynb, current_data: experiments/{research_name}/current_data/, new_notebook: experiments/{research_name}/new.ipynb, research_source: experiments/{research_name}/research.pdf, experiment_log: experiments/{research_name}/log.json } }5.1 顶层字段规则name必须等于调用方给定的{research_name}与实验文件夹名一致。verdict只能是BETTER、WORSE、INCONCLUSIVE、FAILED四选一不允许其他取值。summary23 段纯文本说明新方法做什么、与基线在原理上有何不同、做了哪些取舍。明文规定不得使用 Markdown 标题只能写短段落。explanation23 句话说明为什么得到该裁决必须引用具体指标与具体差异数值mention numbers, not vague statements禁止空泛表述。永远输出合法 JSON任何字段都不得处于 undefined 状态未知值一律用null。这是全系统 CRITICAL RULES 第 8 条Every bookkeeping file is valid JSON的具体落实在实现上如果担心原子性可以先写临时文件再重命名。5.2comparison.metrics[]逐项规则这是报告中最容易被写错的部分原文档给出了严格的字段契约current/new必须是数字如果某一侧无法计算出该指标则用null例如基线 notebook 从未计算过训练时间。diff原始数值差定义为diff new - current不附加任何格式化。diff_display带符号的短字符串如0.019、-0.03用于人类可读的表格展示。betternew|current|tie|null四选一由diff与higher_is_better联合计算得出。当higher_is_bettertrue时diff 0意味着新方法更好反之亦然差异为 0 记tie无法判断记null。unit短单位字符串seconds、%等或null。higher_is_better布尔值指明该指标是越大越好还是越小越好——训练时间这类指标就是false所以上例中diff 43.0却判定better current。这里能看到该 schema 的精妙之处指标方向信息被显式建模后续任何渲染层表格、仪表盘都不需要猜某个指标是越大越好还是越小越好。在源码层agent.py 的ExperimentResult.table属性原样返回这组字典键为name、current、new、diff、diff_display、unit、higher_is_better、better并在_repr_html_中渲染成带 Metric / Current / New / Diff / Better 五列的 HTML 表格。5.3file_locations规则所有路径相对于 experiments 目录根即写为experiments/{research_name}/...形式不是绝对路径也不是只写文件名。research_source必须与 Phase 0 实际落地materialize的产物一致可能是research.pdf、research_source.{ext}如纯文本 idea 落盘为research_source.md也可能是克隆仓库对应的research_source/目录。Phase 0 的落地命名规范详见 experiment_management/SKILL.md 的 Pick a sensible local name 部分。六、第四步更新experiments.json实验登记表收尾experiments.json位于experiments/根目录是所有实验的总登记表。Evaluate 阶段对其做就地更新不是追加新条目条目在 Phase 0 已注册为in_progress需要完成四件事将status置为completed实验失败则置为failed填充verdict四选一填充key_metric其结构为对象{name: ..., baseline: num, new: num}填充baseline_model与new_method。完整的登记表条目格式来自 system_prompt.md如下{ experiments: [ { name: research_name, date: YYYY-MM-DD, status: completed | failed | in_progress, paper: paper title, baseline_model: e.g. XGBoost, new_method: e.g. TabPFN, verdict: BETTER | WORSE | INCONCLUSIVE | FAILED, key_metric: {name: accuracy, baseline: 0.85, new: 0.87}, path: experiments/research_name/ } ] }在源码层这个文件由ExperimentRegistryagent.py 中的ExperimentRegistry类读取__getitem__、get、items等接口每次访问都会重新解析磁盘文件保证后台运行期间状态永远新鲜。ExperimentRecord.status属性即映射这里的三态取值in_progress | completed | failed。七、第五步更新comparison.json跨实验对比表追加行comparison.json用于跨实验汇总方便日后在多个research_name之间横向比较。协议很简单若文件不存在先创建{experiments: []}追加一行{ name: {research_name}, date: YYYY-MM-DD, baseline: {baseline_model}, new_method: {new_method}, key_metric: {name: accuracy, baseline: 0.853, new: 0.872}, verdict: BETTER }注意该表每行是精简快照只保留key_metric单指标与最终verdict详细的多指标对比仍以每个实验目录下的result.json为准result.json的file_locations指向experiments/{research_name}/log.json可回溯全量过程。comparison.json的另一种等价格式来自 system_prompt.md也值得参考其中baseline/new_method直接填模型名如XGBoost/CatBoost。八、第六步回写log.jsonPhase 5 条目最后在log.json的phases数组中追加绝不覆盖先前条目一个 Phase 5 条目作为整个实验的终章记录{ name: Phase 5: Evaluate, completed_at: 2026-04-17T11:40:00Z, verdict: BETTER, key_change: accuracy 0.019 (new current), files_written: [result.json, experiments.json, comparison.json] }completed_at使用 UTC ISO-8601 时间戳key_change用一句话概括关键变化带具体数值files_written如实记录本次写出的文件清单保证如果没写进 log就等于没发生的可审计性。追加而不是覆盖的原则与前几个阶段一致参见 benchmark/SKILL.md 中 Do not overwrite earlier entries; append to thephasesarray 的同样要求。九、失败处理FAILED也是合法且重要的结论原文档强调不是每次实验都会成功失败也要诚实处理并产出合法 JSON。三类典型失败及对应处理方式如下失败类型处理方式依赖失败某包装不上experiments.json.status failedprogress.json.status FAILEDresult.json.verdict FAILED并在explanation中写清错误实现失败新方法训练中崩溃同上explanation中包含错误细节数据不兼容新方法无法处理该数据格式同上explanation中说明原因也就是说Evaluate 阶段的FAILED路径与成功路径走的是同一套文件协议——只是 verdict 取值与 status 不同。这保证了无论是失败还是成功下游消费者都能用同一套解析逻辑处理result.json。系统提示词的措辞是失败实验依然产出result.json因为它告诉我们这个方法对这个用例不适用这本身就是有价值的信息。十、源码印证从磁盘到渲染的完整链路Eval 阶段的产出不只是四个 JSON 文件仓库源码还提供了完整的读取与展示层值得对照学习。相关实现集中在 agent.py1213 行核心类如下10.1AppliedScientist与Experiment如何发起一次会走到 Phase 5 的实验AppliedScientist继承自PrebuiltAutonomousAgentBase将 agent 与template/目录下的技能模板绑定并通过new_experiment(...)暴露高层 API。返回的Experiment对象支持四种运行方式run()前台运行带终端美化输出底层走run_consolerun_async()异步运行无 TTY 格式化run_stream()同步流式迭代文本块或事件run_in_background()后台线程运行静默所有打印适合 Jupyter 单元格通过is_running/is_done/wait()/stop()控制生命周期。stop()使用框架的upsonic.run.cancel.cancel_run做协作式取消标记运行中的 run让 agent 在下一个流水线检查点自行中止而非强杀线程。10.2ExperimentResultresult.json的结构化视图ExperimentResult把result.json解析为四个调用方真正关心的属性与 Evaluate 的产出字段一一对应verdict——BETTER/WORSE/INCONCLUSIVE/FAILEDsummary—— 新方法的 23 段说明explanation—— 为什么得到该裁决table—— 对比指标列表即comparison.metrics。它还在 Jupyter 中提供_repr_html_渲染出实验名 带颜色的 verdict 徽章BETTER 绿 / WORSE 红 / INCONCLUSIVE 橙 / FAILED 灰 五列指标表 Why 摘要的卡片式 HTML 视图。也就是说Evaluate 写出的result.json可以直接在 notebook 里以漂亮的可视化形式呈现。10.3ExperimentRecord与ExperimentRegistry磁盘状态的只读视图ExperimentRecord由experiments.json中的条目 实验目录下的 JSON 文件共同支撑每个属性都重新从磁盘读取因此后台运行期间轮询永远拿到最新状态。它暴露status、verdict、key_metric、baseline_model、new_method、paper、date等登记表字段以及progress解析progress.json、log解析log.json、result解析result.json三个文件读取器。ExperimentRegistry是experiments.json的 dict-like 视图__getitem__/get/keys/items每次访问都重新加载文件Experiment.progress_bar属性会基于磁盘上的progress.json生成 Rich HTML 进度条含每个阶段的 ✓/●/○/✗ 图标与进度百分比last_logs(n)则渲染log.json末尾 n 条日志卡片——这两个 Jupyter 友好工具让用户在后台实验运行期间可以实时刷新查看 Phase 5 是否已经完成。另外_auto_inputs()辅助函数演示了输入处理哲学对用户传入的候选路径只做本地磁盘存在性检查Path(value).expanduser()后path.exists()URL、git 引用、arXiv 链接、纯文本 idea 等一律跳过留给 agent 在 Phase 0 用自己的技能去抓取——这与 experiment_management/SKILL.md 中不依赖固定前缀检测列表的原则完全一致。十一、端到端实战示例从发起实验到拿到裁决仓库提供了两个开箱即用的入口文件可以组合成一次完整演示。1. CLI 直跑example.shclaude \ --system-prompt-file ./system_prompt.md \ --dangerously-skip-permissions \ --effort medium \ New experiment. **Research paper:** example_1/tabpfn.pdf **Current notebook:** example_1/Baseline XGBoost Adult.ipynb **Current data:** downloaded in notebook (ucimlrepo, id2) Run the full experiment pipeline. Go from Phase 0 through Phase 5 without stopping. I want to see \result.md\ at the end telling me whether this new method is better than what we have. Start now.这里system_prompt.md即 应用科学家系统提示词它把实验协议6 条 CRITICAL RULES、5 项输入、6 阶段一次性注入 agentagent 在 Phase 5 会调用evaluate技能完成裁决与收尾。2. 模板消息first_message.md则展示了调用方应当提供的五个占位参数New experiment. **Experiment name:** {research_name} **Research source:** {research_source} **Current notebook:** {current_notebook} **Current data:** {current_data} **Experiments directory:** {experiments_directory}3. 通过 Python API 在 Jupyter 中运行使用AppliedScientist.new_experiment(name, research_source..., current_notebook..., current_data..., experiments_directory...)创建实验对象后调用experiment.run_in_background()返回控制权轮询experiment.progress_bar查看 Phase 05 进度实验完成后用experiment.result拿到ExperimentResult其verdict属性即为 Evaluate 阶段写入result.json的最终裁决或用scientist.experiments[name]读取登记表记录。一次完整实验结束后experiments/目录的最终形态如下结构来自 system_prompt.mdexperiments/ ├── experiments.json # Registry: every experiment ever run ├── comparison.json # Cross-experiment summary (JSON array) └── {research_name}/ ├── current.ipynb # COPY of the original notebook (never the original) ├── current_data/ # COPY of the original data (never the original) ├── current_requirements.txt ├── new.ipynb # New implementation ├── new_requirements.txt ├── research.pdf # Materialized research source ├── log.json # Phase-by-phase structured log ├── progress.json # Live progress snapshot └── result.json # The final machine-readable comparison report十二、Evaluate 实战检查清单最后把原文档与系统提示词中的硬性约束汇成一份可对照执行的清单指标必须成对Phase 3 定义的每个指标基线侧取log.jsonPhase 3 条目的baseline新方法侧取 Phase 4 条目的metrics某侧缺失用null不要编造。裁决依据多数关键指标整体方向决定BETTER/WORSE混杂或噪声内差异给INCONCLUSIVE无法对比给FAILED。verdict四选一不得出现其他取值。diff new - currentdiff_display带符号数值与展示字符串分工明确。better由diffhigher_is_better推导训练时间这类越小越好的指标方向不要搞反。summary/explanation纯文本无 Markdown 标题短段落explanation必须带具体数字。file_locations用相对 experiments 根的路径research_source与 Phase 0 落地产物严格一致。三个配套文件都要更新experiments.json改状态、comparison.json追加行先建默认结构、log.json追加 Phase 5 条目。所有文件合法 JSON不写半成品需要原子性时先写临时文件再 renameprogress.json的status保持大写枚举RUNNING/COMPLETED/FAILEDupdated_at始终刷新。失败同样出报告FAILED的result.json比伪造的成功更有价值。这套 Evaluate 协议的可贵之处在于它把新方法是否值得切换这个模糊的研究问题压缩成了四个可枚举的裁决、一份带符号差值与指标方向的机器可读报告、以及三份彼此可交叉引用的 JSON 簿记文件——让实验结论既诚实可审计又能被仪表盘与 notebook 直接消费。如果你想在自有研究流程中复刻这套体系直接以 evaluate/SKILL.md 为模板定义你的裁决契约再参照 agent.py 中的读取/渲染层即可无缝接入。【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Upsonic 应用科学家预置智能体 Evaluate 技能实战：用机器可读 JSON 完成基准对比与实验裁决
Upsonic 应用科学家预置智能体 Evaluate 技能实战用机器可读 JSON 完成基准对比与实验裁决【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant导读Evaluate 是 Upsonic 预置的「应用科学家」Applied Scientist自主智能体实验流水线Phase 0 → Phase 5的收官阶段负责把 Phase 3 的基线指标与 Phase 4 的新方法指标汇总成一份机器可读的最终裁决报告result.json并同步更新实验登记表experiments.json、跨实验对比表comparison.json与分阶段日志log.json。读完本文你将掌握四类裁决BETTER / WORSE / INCONCLUSIVE / FAILED的判定逻辑、result.json的逐字段 schema 规范、三个配套 JSON 文件的更新协议以及仓库源码中ExperimentResult、ExperimentRecord、ExperimentRegistry对这份报告的读取与渲染机制可以直接在你的研究型 Agent 工作流中复刻这套诚实、可审计、可程序化消费的实验评价体系。一、Evaluate 技能在实验流水线中的位置为什么实验的产出是一份 JSON 裁决在展开 Evaluate 的细节之前先看它所在的上下文。应用科学家智能体的核心职责在 system_prompt.md 中被概括为一句话take what we have, take whats new, try the new thing, and tell us if its better把现有的拿走把新的拿来试试新东西然后告诉我们它是否更好。一次完整实验被拆成 6 个阶段每阶段对应一个技能目录SKILL.md阶段名称对应技能文档Phase 0Setup环境搭建experiment_management/SKILL.mdPhase 1Analyze Current分析基线analyze_current/SKILL.mdPhase 2Research研究新方法research/SKILL.mdPhase 3Benchmark定义对比框架benchmark/SKILL.mdPhase 4Implement实现并运行新方法implement/SKILL.mdPhase 5Evaluate对比、裁决、出报告evaluate/SKILL.mdEvaluate 就是最后一步盖棺定论的环节。它的 Purpose 在 evaluate/SKILL.md 中写得很明确Compare baseline and new implementation results. Produce the machine-readable final reportresult.json, updateexperiments.json, and append a row tocomparison.json.这里有一个贯穿全系统的设计哲学实验的产出不是代码而是一个决策。整条流水线中所有簿记文件progress.json、log.json、result.json、experiments.json、comparison.json全部是合法 JSON绝不使用 Markdown 报告。这样做的目的是让仪表盘、CLI 和 Jupyter notebook 都能直接轮询和渲染实验结果实现人机双读。二、输入参数Evaluate 需要什么Evaluate 技能接受两个输入参数见原文档 Input 表参数类型说明experiment_pathpath实验目录即experiments/{research_name}/research_namestring本次实验的名称必须逐字使用调用方给定的名字不得改名、不得加后缀、不得从论文标题重新推导research_name的逐字使用约束是全系统规则CRITICAL RULES 第 9 条实验文件夹名与所有 JSON 文件中的name字段都必须精确一致。在源码层agent.py 中的Experiment类保存了这份 name并通过ExperimentRecord/ExperimentRegistry以该名字为键去定位磁盘上的result.json、progress.json、log.json。另外要注意Evaluate 的所有输入都只来自磁盘上的既有文件——指标来自log.jsonPhase 3 的基线项 Phase 4 的新方法项实验目录在 Phase 0 已经创建完毕。因此 Evaluate 阶段不再需要接触原始 notebook 或数据这也符合系统NEVER modify original files的第一铁律。三、六步行动总览原文档将 Evaluate 拆为 6 个动作先建立全局视图收集全部指标从log.json读取 Phase 3 基线条目与 Phase 4 新方法条目。判定裁决得出BETTER/WORSE/INCONCLUSIVE/FAILED之一。写result.json按精确 schema 输出最终机器可读报告字段不得留空未知值用null。更新experiments.json将状态置为completed或failed补齐verdict、key_metric、baseline_model、new_method。更新comparison.json文件不存在则先创建{experiments: []}然后追加一行汇总记录。回写log.json追加 Phase 5 条目收尾整个实验。下面逐一展开。四、第一步与第二步收集指标、判定裁决收集指标Step 1的动作很直接log.json是贯穿 6 个阶段的唯一结构化日志Phase 3 的 Benchmark 条目里存有每个指标的baseline值与needs_computation标记参考 benchmark/SKILL.md 中的metrics[]结构Phase 4 的 Implement 条目里存有metrics字典与新方法实测值参考 implement/SKILL.md。Evaluate 只需要把这两处数据取出来配对无需重新运行任何 notebook。判定裁决Step 2是 Evaluate 的核心智力动作四类结论的语义如下verdict触发条件BETTER新方法在多数关键指标上优于基线WORSE新方法在多数关键指标上劣于基线INCONCLUSIVE结果混杂或差异落在噪声范围内FAILED实验无法产出可对比结果依赖安装失败、实现崩溃、数据不兼容注意两个要点多数majority意味着裁决不是看单一指标而是看指标集合的整体方向这要求 Phase 3 定义的对比指标足够全面分类任务建议 accuracy / precision / recall / F1 / AUC-ROC回归任务建议 MSE / RMSE / MAE / R²另外都建议计入训练时间training_time_seconds。FAILED不是白干一场系统提示词明确指出A failed experiment is more valuable than a fake success失败实验比伪造的成功更有价值。依赖失败、实现崩溃、数据不兼容都会走 FAILED 路径但依然要产出合法的result.json。五、第三步result.json完整 Schema 与字段规则result.json是实验的最终交付物也是是否应该切换到新方法这一问题的机器可读答案。原文档给出了精确 schema这里完整保留并逐字段注释{ name: {research_name}, verdict: BETTER, summary: 2-3 paragraphs explaining what the new method does, how it fundamentally differs from the baseline, and what trade-offs it makes., explanation: 2-3 sentences explaining WHY this verdict was reached. Reference specific metrics and their differences. Be concrete — mention numbers, not vague statements., comparison: { metrics: [ { name: accuracy, current: 0.853, new: 0.872, diff: 0.019, diff_display: 0.019, unit: null, higher_is_better: true, better: new }, { name: training_time_seconds, current: 2.0, new: 45.0, diff: 43.0, diff_display: 43.0, unit: seconds, higher_is_better: false, better: current } ] }, file_locations: { current_notebook: experiments/{research_name}/current.ipynb, current_data: experiments/{research_name}/current_data/, new_notebook: experiments/{research_name}/new.ipynb, research_source: experiments/{research_name}/research.pdf, experiment_log: experiments/{research_name}/log.json } }5.1 顶层字段规则name必须等于调用方给定的{research_name}与实验文件夹名一致。verdict只能是BETTER、WORSE、INCONCLUSIVE、FAILED四选一不允许其他取值。summary23 段纯文本说明新方法做什么、与基线在原理上有何不同、做了哪些取舍。明文规定不得使用 Markdown 标题只能写短段落。explanation23 句话说明为什么得到该裁决必须引用具体指标与具体差异数值mention numbers, not vague statements禁止空泛表述。永远输出合法 JSON任何字段都不得处于 undefined 状态未知值一律用null。这是全系统 CRITICAL RULES 第 8 条Every bookkeeping file is valid JSON的具体落实在实现上如果担心原子性可以先写临时文件再重命名。5.2comparison.metrics[]逐项规则这是报告中最容易被写错的部分原文档给出了严格的字段契约current/new必须是数字如果某一侧无法计算出该指标则用null例如基线 notebook 从未计算过训练时间。diff原始数值差定义为diff new - current不附加任何格式化。diff_display带符号的短字符串如0.019、-0.03用于人类可读的表格展示。betternew|current|tie|null四选一由diff与higher_is_better联合计算得出。当higher_is_bettertrue时diff 0意味着新方法更好反之亦然差异为 0 记tie无法判断记null。unit短单位字符串seconds、%等或null。higher_is_better布尔值指明该指标是越大越好还是越小越好——训练时间这类指标就是false所以上例中diff 43.0却判定better current。这里能看到该 schema 的精妙之处指标方向信息被显式建模后续任何渲染层表格、仪表盘都不需要猜某个指标是越大越好还是越小越好。在源码层agent.py 的ExperimentResult.table属性原样返回这组字典键为name、current、new、diff、diff_display、unit、higher_is_better、better并在_repr_html_中渲染成带 Metric / Current / New / Diff / Better 五列的 HTML 表格。5.3file_locations规则所有路径相对于 experiments 目录根即写为experiments/{research_name}/...形式不是绝对路径也不是只写文件名。research_source必须与 Phase 0 实际落地materialize的产物一致可能是research.pdf、research_source.{ext}如纯文本 idea 落盘为research_source.md也可能是克隆仓库对应的research_source/目录。Phase 0 的落地命名规范详见 experiment_management/SKILL.md 的 Pick a sensible local name 部分。六、第四步更新experiments.json实验登记表收尾experiments.json位于experiments/根目录是所有实验的总登记表。Evaluate 阶段对其做就地更新不是追加新条目条目在 Phase 0 已注册为in_progress需要完成四件事将status置为completed实验失败则置为failed填充verdict四选一填充key_metric其结构为对象{name: ..., baseline: num, new: num}填充baseline_model与new_method。完整的登记表条目格式来自 system_prompt.md如下{ experiments: [ { name: research_name, date: YYYY-MM-DD, status: completed | failed | in_progress, paper: paper title, baseline_model: e.g. XGBoost, new_method: e.g. TabPFN, verdict: BETTER | WORSE | INCONCLUSIVE | FAILED, key_metric: {name: accuracy, baseline: 0.85, new: 0.87}, path: experiments/research_name/ } ] }在源码层这个文件由ExperimentRegistryagent.py 中的ExperimentRegistry类读取__getitem__、get、items等接口每次访问都会重新解析磁盘文件保证后台运行期间状态永远新鲜。ExperimentRecord.status属性即映射这里的三态取值in_progress | completed | failed。七、第五步更新comparison.json跨实验对比表追加行comparison.json用于跨实验汇总方便日后在多个research_name之间横向比较。协议很简单若文件不存在先创建{experiments: []}追加一行{ name: {research_name}, date: YYYY-MM-DD, baseline: {baseline_model}, new_method: {new_method}, key_metric: {name: accuracy, baseline: 0.853, new: 0.872}, verdict: BETTER }注意该表每行是精简快照只保留key_metric单指标与最终verdict详细的多指标对比仍以每个实验目录下的result.json为准result.json的file_locations指向experiments/{research_name}/log.json可回溯全量过程。comparison.json的另一种等价格式来自 system_prompt.md也值得参考其中baseline/new_method直接填模型名如XGBoost/CatBoost。八、第六步回写log.jsonPhase 5 条目最后在log.json的phases数组中追加绝不覆盖先前条目一个 Phase 5 条目作为整个实验的终章记录{ name: Phase 5: Evaluate, completed_at: 2026-04-17T11:40:00Z, verdict: BETTER, key_change: accuracy 0.019 (new current), files_written: [result.json, experiments.json, comparison.json] }completed_at使用 UTC ISO-8601 时间戳key_change用一句话概括关键变化带具体数值files_written如实记录本次写出的文件清单保证如果没写进 log就等于没发生的可审计性。追加而不是覆盖的原则与前几个阶段一致参见 benchmark/SKILL.md 中 Do not overwrite earlier entries; append to thephasesarray 的同样要求。九、失败处理FAILED也是合法且重要的结论原文档强调不是每次实验都会成功失败也要诚实处理并产出合法 JSON。三类典型失败及对应处理方式如下失败类型处理方式依赖失败某包装不上experiments.json.status failedprogress.json.status FAILEDresult.json.verdict FAILED并在explanation中写清错误实现失败新方法训练中崩溃同上explanation中包含错误细节数据不兼容新方法无法处理该数据格式同上explanation中说明原因也就是说Evaluate 阶段的FAILED路径与成功路径走的是同一套文件协议——只是 verdict 取值与 status 不同。这保证了无论是失败还是成功下游消费者都能用同一套解析逻辑处理result.json。系统提示词的措辞是失败实验依然产出result.json因为它告诉我们这个方法对这个用例不适用这本身就是有价值的信息。十、源码印证从磁盘到渲染的完整链路Eval 阶段的产出不只是四个 JSON 文件仓库源码还提供了完整的读取与展示层值得对照学习。相关实现集中在 agent.py1213 行核心类如下10.1AppliedScientist与Experiment如何发起一次会走到 Phase 5 的实验AppliedScientist继承自PrebuiltAutonomousAgentBase将 agent 与template/目录下的技能模板绑定并通过new_experiment(...)暴露高层 API。返回的Experiment对象支持四种运行方式run()前台运行带终端美化输出底层走run_consolerun_async()异步运行无 TTY 格式化run_stream()同步流式迭代文本块或事件run_in_background()后台线程运行静默所有打印适合 Jupyter 单元格通过is_running/is_done/wait()/stop()控制生命周期。stop()使用框架的upsonic.run.cancel.cancel_run做协作式取消标记运行中的 run让 agent 在下一个流水线检查点自行中止而非强杀线程。10.2ExperimentResultresult.json的结构化视图ExperimentResult把result.json解析为四个调用方真正关心的属性与 Evaluate 的产出字段一一对应verdict——BETTER/WORSE/INCONCLUSIVE/FAILEDsummary—— 新方法的 23 段说明explanation—— 为什么得到该裁决table—— 对比指标列表即comparison.metrics。它还在 Jupyter 中提供_repr_html_渲染出实验名 带颜色的 verdict 徽章BETTER 绿 / WORSE 红 / INCONCLUSIVE 橙 / FAILED 灰 五列指标表 Why 摘要的卡片式 HTML 视图。也就是说Evaluate 写出的result.json可以直接在 notebook 里以漂亮的可视化形式呈现。10.3ExperimentRecord与ExperimentRegistry磁盘状态的只读视图ExperimentRecord由experiments.json中的条目 实验目录下的 JSON 文件共同支撑每个属性都重新从磁盘读取因此后台运行期间轮询永远拿到最新状态。它暴露status、verdict、key_metric、baseline_model、new_method、paper、date等登记表字段以及progress解析progress.json、log解析log.json、result解析result.json三个文件读取器。ExperimentRegistry是experiments.json的 dict-like 视图__getitem__/get/keys/items每次访问都重新加载文件Experiment.progress_bar属性会基于磁盘上的progress.json生成 Rich HTML 进度条含每个阶段的 ✓/●/○/✗ 图标与进度百分比last_logs(n)则渲染log.json末尾 n 条日志卡片——这两个 Jupyter 友好工具让用户在后台实验运行期间可以实时刷新查看 Phase 5 是否已经完成。另外_auto_inputs()辅助函数演示了输入处理哲学对用户传入的候选路径只做本地磁盘存在性检查Path(value).expanduser()后path.exists()URL、git 引用、arXiv 链接、纯文本 idea 等一律跳过留给 agent 在 Phase 0 用自己的技能去抓取——这与 experiment_management/SKILL.md 中不依赖固定前缀检测列表的原则完全一致。十一、端到端实战示例从发起实验到拿到裁决仓库提供了两个开箱即用的入口文件可以组合成一次完整演示。1. CLI 直跑example.shclaude \ --system-prompt-file ./system_prompt.md \ --dangerously-skip-permissions \ --effort medium \ New experiment. **Research paper:** example_1/tabpfn.pdf **Current notebook:** example_1/Baseline XGBoost Adult.ipynb **Current data:** downloaded in notebook (ucimlrepo, id2) Run the full experiment pipeline. Go from Phase 0 through Phase 5 without stopping. I want to see \result.md\ at the end telling me whether this new method is better than what we have. Start now.这里system_prompt.md即 应用科学家系统提示词它把实验协议6 条 CRITICAL RULES、5 项输入、6 阶段一次性注入 agentagent 在 Phase 5 会调用evaluate技能完成裁决与收尾。2. 模板消息first_message.md则展示了调用方应当提供的五个占位参数New experiment. **Experiment name:** {research_name} **Research source:** {research_source} **Current notebook:** {current_notebook} **Current data:** {current_data} **Experiments directory:** {experiments_directory}3. 通过 Python API 在 Jupyter 中运行使用AppliedScientist.new_experiment(name, research_source..., current_notebook..., current_data..., experiments_directory...)创建实验对象后调用experiment.run_in_background()返回控制权轮询experiment.progress_bar查看 Phase 05 进度实验完成后用experiment.result拿到ExperimentResult其verdict属性即为 Evaluate 阶段写入result.json的最终裁决或用scientist.experiments[name]读取登记表记录。一次完整实验结束后experiments/目录的最终形态如下结构来自 system_prompt.mdexperiments/ ├── experiments.json # Registry: every experiment ever run ├── comparison.json # Cross-experiment summary (JSON array) └── {research_name}/ ├── current.ipynb # COPY of the original notebook (never the original) ├── current_data/ # COPY of the original data (never the original) ├── current_requirements.txt ├── new.ipynb # New implementation ├── new_requirements.txt ├── research.pdf # Materialized research source ├── log.json # Phase-by-phase structured log ├── progress.json # Live progress snapshot └── result.json # The final machine-readable comparison report十二、Evaluate 实战检查清单最后把原文档与系统提示词中的硬性约束汇成一份可对照执行的清单指标必须成对Phase 3 定义的每个指标基线侧取log.jsonPhase 3 条目的baseline新方法侧取 Phase 4 条目的metrics某侧缺失用null不要编造。裁决依据多数关键指标整体方向决定BETTER/WORSE混杂或噪声内差异给INCONCLUSIVE无法对比给FAILED。verdict四选一不得出现其他取值。diff new - currentdiff_display带符号数值与展示字符串分工明确。better由diffhigher_is_better推导训练时间这类越小越好的指标方向不要搞反。summary/explanation纯文本无 Markdown 标题短段落explanation必须带具体数字。file_locations用相对 experiments 根的路径research_source与 Phase 0 落地产物严格一致。三个配套文件都要更新experiments.json改状态、comparison.json追加行先建默认结构、log.json追加 Phase 5 条目。所有文件合法 JSON不写半成品需要原子性时先写临时文件再 renameprogress.json的status保持大写枚举RUNNING/COMPLETED/FAILEDupdated_at始终刷新。失败同样出报告FAILED的result.json比伪造的成功更有价值。这套 Evaluate 协议的可贵之处在于它把新方法是否值得切换这个模糊的研究问题压缩成了四个可枚举的裁决、一份带符号差值与指标方向的机器可读报告、以及三份彼此可交叉引用的 JSON 簿记文件——让实验结论既诚实可审计又能被仪表盘与 notebook 直接消费。如果你想在自有研究流程中复刻这套体系直接以 evaluate/SKILL.md 为模板定义你的裁决契约再参照 agent.py 中的读取/渲染层即可无缝接入。【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考