OpenResearch 研究输出规范用 orx-reports 将实验结论沉淀为项目 Artifacts【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearchorx-reports是 OpenResearch 内置的 Agent 技能模块规定了研究报告、图表、CSV、PDF 等持久化输出应当如何写入与组织在项目的artifacts 目录中。本指南完整解析该模块的每一条规范并结合仓库源码说明 artifacts 目录的底层实现、会话移交时的 evidence-and-links 约定以及它与orx-evidence、orx-figures两个模块的分工。读完你就能在 OpenResearch 项目中按规范产出结构清晰、可复现、可被后续会话继续引用的研究交付物。orx-reports 的定位与使用时机模块的官方描述见 agent-skills/orx-reports/SKILL.md 与 src/local/agent_skills.rs 中的注册定义是Write and organize durable outputs in the artifacts directory. Use before creating or organizing artifacts, including reports, summaries, comparisons, figures, and exported data, or when a line of work concludes.即在创建或整理任何持久化输出之前以及一条研究线收尾时都应先加载orx-reports。它覆盖的产物类型包括报告reports、摘要summaries、对比comparisons、图表figures、导出的数据exported data以及 PDF 等其他输出。在orx的模块体系里它与orx-paperLaTeX 论文草稿、orx-evidence运行证据分工明确面向用户的研究报告与结果汇总归orx-reports管学术论文草稿归orx-paper管。artifacts 目录是什么文件系统即事实源orx-reports 的规范核心是直接把输出写进 artifacts 目录写好的文件立即成为项目 artifacts。这个目录不是虚构的概念而是用户机器上一个真实的普通文件夹。底层实现在 src/local/files.rs每个项目对应一个物理目录data dir/files/project slug/见files_dirsrc/local/files.rs兼容性迁移v0.1.48 之前的artifacts/根目录在不存在files/根时会原地迁移为files/两者并存时files/具有权威性见files_rootsrc/local/files.rs文件系统是唯一事实源没有注册表、没有上传步骤Dashboard 的 Artifacts 选项卡就是这个文件夹的浏览器src/local/files.rs文件可以放在根目录也可以放在任意用户自选的嵌套结构里文件名不设特殊处理。文件可以任意嵌套这正对应 orx-reports 的组织规范先查看现有 artifacts 目录并遵循其既有组织后续输出复用相关文件夹按研究主题或交付物分组而不是把文件堆在根目录。路径安全与浏览能力Artifacts 目录通过本机 API 对外提供浏览、读取、删除能力因此源码里对路径做了双重防护src/local/files.rsis_safe_rel_path做词法检查拒绝空路径、绝对路径、反斜杠以及任何含.././ 空段的路径resolve_contained做符号链接检查解析后必须仍落在 artifacts 目录内防止目录内的 symlink 指向外部如a - /elsewhere时经a/b越权对应测试覆盖了词法逃逸、symlink 文件逃逸、symlink 目录逃逸、内部 symlink 放行等场景src/local/files.rs目录列举上限为 2000 个节点MAX_ENTRIES超出即标记truncated避免失控目录拖垮 2Hz 的事件循环src/local/files.rs。服务端把 artifacts 目录的绝对路径注入 UI 与 Agent 会话project_json_with_artifacts_dir将artifactsDir写入项目 JSONsrc/commands/up.rs会话 playbook 则通过{artifacts}占位符注入见下文会话移交。目录组织规范主题分组拒绝空壳orx-reports 对目录组织的具体要求是按研究主题或交付物分组不要堆在 artifacts 根目录仅当确有帮助时才添加figures/、data/、models/等子文件夹绝不创建空脚手架——没有内容的目录结构是无意义的负担。模块给出的参考目录树如下原文完整继承artifacts-dir/ transformer-sweep/ transformer-sweep-report.md figures/ orx_figstyle.py patch-size.pdf patch-size.svg patch-size.py learning-rate.pdf learning-rate.svg learning-rate.py data/ sweep-results.csv仓库中的 demo 项目就是这一规范的活样例demo/nanochat/下的figures/4 张 SVG 图与reports/瓶颈诊断报告正是按主题分组、脚本与图同置的方式组织的。描述性文件名每个输出都应使用描述性文件名让读者仅凭文件名就能判断内容与用途。例如transformer-sweep-report.mdTransformer 扫描实验报告、patch-size.svgpatch 尺寸曲线、sweep-results.csv扫描结果数据。文件名是 artifacts 的第一层元数据也是后续会话定位产物、报告中相对链接能否成立的基础。可复现脚本与图同置临时文件隔离两条硬性规范可复现脚本必须与产物放一起图表的生成脚本patch-size.py紧挨其输出patch-size.pdf/patch-size.svg。图表脚本丢失 评审要求补一个 seed 时无法修正图就成了死资产。临时日志与草稿文件放在 artifacts 目录之外artifacts 目录只承载可交付的输出/tmp、会话 scratch 目录用于中间过程。这正对应orx-figures中的说法拉取日志、中间数据进/tmp没问题——图、以及生成图的脚本不是中间产物agent-skills/orx-figures/SKILL.md。已发布产物保持原位已经发布的输出已被用户引用、已进入报告或论文必须保留在现有路径。对更早的旧输出只有在被明确要求时才进行重组且重组时必须更新所有受影响的文档链接验证重组后的链接仍然可解析。这保证既有文档、聊天记录中的引用不会因一次顺手整理而 404。图表的门槛写图之前必读 orx-figuresorx-reports 明确声明写任何图之前必须读取orx-figures模块默认的 matplotlib 图不达报告标准。原因在 agent-skills/orx-figures/SKILL.md 中讲得很透论文中的图是一个论证而非数组截图默认 matplotlib 输出按屏幕尺寸绘制、在应放 caption 的位置放了标题、使用灰度下不可区分的色环、在需要矢量的地方做了栅格化。orx-figures的八条红线包括按最终印刷尺寸构图、矢量导出PDFSVG、每个数字都来自orx logs的运行结果、caption 即标题、展示不确定性并注明 seed 数、坐标轴带单位、色盲/灰度安全、全程统一无衬线字体agent-skills/orx-figures/SKILL.md。一个完整的流程示例是报告写到transformer-sweep/文件夹 → 图写到transformer-sweep/figures/→ 图脚本含 vendor 进来的orx_figstyle.py紧挨图放置保证本会话结束后图仍可复现。报告内使用相对链接报告文档内部引用图表时必须使用相对链接例如在transformer-sweep-report.md中写Patch size相对链接保证报告与其所在目录一起移动、一起归档时引用依然成立也符合产物可交付的定位。会话移交evidence-and-links 契约Agent 在会话chat handoff收尾时必须按会话 playbook 中的 evidence-and-links 契约链接每一个完成的输出并且使用完整嵌套路径例如file pathartifacts/transformer-sweep/figures/patch-size.svg /这条契约不是口头约定而是有源码测试保证的仓库对内置技能内容有断言测试要求orx-reports内容包含 evidence-and-links contractsrc/local/agent_skills.rs并且会话 playbook 的生成逻辑断言其中包含file pathartifacts/transformer-sweep/figures/patch-size.svg /形式的链接src/local/opencode.rs。从源码看会话 playbook 会把当前项目的 artifacts 绝对路径通过{artifacts}占位符注入给 Agentsrc/local/opencode.rs并确保目录存在src/local/opencode.rs。因此 Agent 在会话中看到的 artifacts 路径与用户在 UI 中看到的完全一致——链接能点开路径不出错。与 orx-evidence 联动先验证再报告orx-reports 的最后一条规范当报告中的主张claim源自运行结果时必须加载orx-evidence。二者的边界是——orx-reports 管怎么写、写在哪orx-evidence 管写的数字从哪来、是否可信。agent-skills/orx-evidence/SKILL.md 的核心要求运行日志是证据通道让 run 命令把所有判定所需内容打印到 stdout之后用orx logs读回。若结果不在日志里之后就无法查验读取方式orx logs runId默认读尾部通常正是想要的--head从头读--bytes 200000提高字节上限默认 64 KB最大 1 MB--range 4096:8192读精确字节窗口报告前必须验证日志是否标识了变体与生效配置、最终指标与紧凑摘要是否存在、长运行的轨迹是否可恢复、返回的字节窗口是否确实包含支撑输出——截断的输出不是证据缺失要组合--head/--bytes/--range直到读到相关部分。简言之任何运行结论在写进报告之前都要能从orx logs中直接读到依据。报告中每个数字都来自运行这也是 orx-reports 所引用图表规范的第 3 条红线Every number comes from a run见 agent-skills/orx-figures/SKILL.md。在会话中加载模块orx-reports与orx-evidence、orx-figures一样都是随orxCLI 捆绑的技能模块。Agent或开发者通过以下方式加载见 SKILL.md 的模块清单orx skill orx-reports # 查看本模块全文 orx skill orx-evidence # 报告涉及运行结果时配合使用 orx skill orx-figures # 写任何图之前必读orx skill无参数时打印总览与全部模块索引orx skill name打印对应模块全文。这些模块是懒加载资源按需读取。仓库中的完整实践样例demo/nanochat/是仓库内直接演示上述规范的研究产出样例报告demo/nanochat/reports/nanochat-bottleneck-diagnosis.md——按主题归档的诊断报告图表demo/nanochat/figures/下的 4 张 SVGnanochat-base-training-curves.svg、nanochat-sft-training-curves.svg、nanochat-training-throughput.svg、nanochat-core-evaluation.svg——矢量格式、按主题分组数据与清单demo/nanochat/evidence/README.md 展示了证据包的组织方式training-metrics.csv、evaluation-metrics.json、checkpoint 元数据、tokenizer、最终推理记录、run-manifest.json清单并明确记录了有意省略的多 GB 工作区内容权重、优化器状态、数据集等留在运行本地不进入 artifacts。这个样例演示了 orx-reports 的全部要点主题分组、描述性文件名、脚本/数据与产物同置、临时与大规模中间产物隔离、报告相对链接、以及证据可追溯。小结一次标准的研究输出流程综合orx-reports与配套模块一条研究线收尾时的标准流程是加载orx skill orx-reports检查现有 artifacts 目录的组织若报告中的数字来自运行加载orx skill orx-evidence用orx logs必要时组合--head/--bytes/--range确认每个主张都能从日志验证需要配图时加载orx skill orx-figures并按对应图类型曲线、scaling、对比、Pareto、矩阵、示意图阅读其 reference用orx_figstyle.py生成矢量图把报告、图PDFSVG、图脚本、导出数据按主题写入 artifacts 下的专用文件夹临时文件留在 artifacts 之外报告内部使用相对链接引用图表会话收尾时按 evidence-and-links 契约用完整嵌套路径file pathartifacts/topic/figures/name.svg /逐个链接已完成产物。【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考