企业官网建设流程全解析

OpenResearch 运行证据链：用orx logs设计、校验与解读实验证据

【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearch

运行日志是 OpenResearch 实验的证据通道：一个 run 的终端输出在运行时被实时捕获、运行结束后持久化，之后通过orx logs按需回读。本指南讲解如何把“judge a run（判定一次运行的结果）”这件事做成工程化流程——在 launch 之前设计 stdout 应输出的指标与摘要，在 run 结束后用orx logs读回持久化结果，并在汇报任何由运行推导的结论之前完成一套可重复的证据校验。读完本文，你将掌握orx logs的四种读取模式与字节窗口语义、证据型 run 命令的撰写规范，以及一套“截断不等于不存在”的取证式排查方法，可直接套用到 nanochat 这类真实 demo 实验的复盘与汇报中。

一、为什么日志是证据：捕获与持久化机制

OpenResearch 把一个实验的判定依据收敛为一条原则：如果 run 的结果没有出现在它的日志里，事后就无法再检视。因此 run 命令必须把“判定结果所需的全部信息”打印到 stdout——最终指标、紧凑摘要、关键配置——日志被截断或丢失都不可接受。

从源码实现看，这一机制在本地平面（LocalPlane）中落为read_log：日志按 run 持久化到数据目录下的run-logs/<runId>.log文件，路径由 src/store.rs 中的log_path()计算，其中 run id 会被过滤为仅 ASCII 字母数字与-/_，防止异常数据逃逸出日志目录。读取时通过std::fs::metadata获取文件总字节数，再按请求模式在文件中定位窗口，见 src/plane/local_plane.rs。

字节窗口的三种定位模式

本地实现定义了三种窗口计算方式，对应orx logs的三种读取形态：

默认字节上限为 64 KB（常量LOCAL_DEFAULT_BYTES = 64 * 1024），这也是原文档默认值的来源。当文件不存在时返回missing_local标记，CLI 层打印[local file] no log captured yet for this run.（src/commands/logs.rs）。

stdout 与 stderr 的分流设计

日志正文写入stdout，而[source] bytes a–b of N状态行写入stderr（src/commands/logs.rs）。这是刻意的管道友好设计：状态行不会污染| grep或重定向。状态行由RunLog::footer()生成（src/plane.rs），当窗口上下被截断时会追加(more above)、(more below)提示。source字段表明日志来源，本地平面固定为"local file"。

run id 从哪里来

run id 由orx runs <projectId>列出。src/commands/runs.rs 以表格形式（ID / STATUS / EXPERIMENT / COMMIT / DURATION / UPDATED）按最新优先列出项目下所有 run，可用--experiment <expId>过滤到单个实验。注意runs命令不仅是 id 的来源，也是整个自动研究循环中的source of truth：每次orx exp wait唤醒后都要重新读取它并核对所有新终态的 run。

二、orx logs四种读取方式详解

核心命令的完整用法：

orx logs <runId> # tail（默认，通常是你想要的末尾） orx logs <runId> --head # 改为从头读取 orx logs <runId> --bytes 200000 # 提高字节上限（默认 64 KB，最大 1 MB） orx logs <runId> --range 4096:8192 # 精确字节窗口 [start, end)

参数定义见 src/main.rs：--head布尔开关，--bytes与--range均为字符串。--range必须满足end > start，否则 CLI 报错退出（src/commands/logs.rs）；--bytes必须是整数（src/commands/logs.rs）。

--head：读开头

从头读取。在本地实现中等价于窗口(0, min(max, total))，即最多取文件前 64 KB（可调）。适合查看 run 的启动阶段：环境准备、依赖安装、配置回显。示例：demo 的端到端日志 demo/nanochat/run-output.txt 开头即回显了command: bash runs/runcpu.sh && python -m scripts.chat_cli ...与“Tokenizer, base training, and base evaluation”的分段标记。

--bytes：提高字节上限

默认 64 KB 对单次读取可能不够（例如一个训练日志单行就 100+ 字节、动辄数千行）。--bytes 200000将窗口扩到 200 KB；最大 1 MB。注意上限用于定位窗口：tail模式下是“从末尾往前取 N 字节”，head模式下是“从开头往后取 N 字节”。

--range：精确字节窗口

--range 4096:8192精确读取第 4096 到 8191 字节。它是长程轨迹取证的关键工具：先 tail 拿到末尾摘要，发现需要核对中间某个 step 时，不必重新拉全文，直接按字节定位。窗口端点会clamp到[0, total]范围内，越界不报错。

状态行解读

每次读取，stderr 都会出现形如：

[local file] bytes 0–65536 of 131072 (more below)

含义：

• source：日志来源，本地为local file；
• bytes a–b of N：本次返回的字节区间与文件总大小；
• (more above)/(more below)：本次窗口上/下仍有未读内容（即truncated_before/truncated_after为真）。

这正是“截断提示”的可读形式——截断不是终点，而是继续读取的信号。

三、让 run 自己打印证据：run 命令设计规范

OpenResearch 要求 run 命令按以下规范组织 stdout，使日志成为“自含的证据包”：

1. 结尾打印最终指标 + 紧凑摘要块，而不是训练过程中零散输出。判定一个 run 时，你只读末尾几 KB 就能得到结论，不必扫描全程。
2. 回显实际使用的配置，让日志能标识出“变体”（variant）。多实验并行时，日志本身必须能自证它属于哪个配置，否则无法区分结果来源。
3. 长 run 定期打印单行指标，使其轨迹能通过字节窗口读取恢复。训练中间的过程值（loss、lr、tok/sec 等）是判断收敛、发散与归因的原料。

对照真实案例：nanochat demo 的证据型日志

仓库内的端到端 demo 恰好演示了这一规范的效果。demo/nanochat/run-output.txt 7355 行，结构如下：

• 开头：命令回显与环境准备（前 ~200 行）；
• 主体：step 0XXXX (xx.xx%) | loss: x.xxxxxx | lrm: x.xx | dt: xxxx.xxms | tok/sec: x,xxx | mfu: x.xx | epoch: 1 | total time: xx.xxm的单行周期指标（step 01499 结尾处见 demo/nanochat/run-output.txt）；
• 结尾：Minimum validation bpb: 0.7389等最终摘要，随后是 chat 确认与run completed successfully收尾（demo/nanochat/run-output.txt）。

对应的结构化解读结果落在 demo/nanochat/evidence/evaluation-metrics.json：baseEvaluation（trainBpb 1.152185 / validationBpb 1.119301）、core任务准确率、final（baseValidationBpb 1.165758 / sftValidationBpb 0.7389 / chatAnswer "Paris"）。demo/nanochat/evidence/final-inference.txt 则以人类可读形式记录了最终推理的命令、检查点、设备与回答。日志里的最终数字（0.7389、Paris）与持久化的证据文件完全对齐——这正是“最终指标 + 紧凑摘要”设计的落点。

触发点：什么时候加载 orx-evidence

根据技能的 frontmatter 描述，应在以下时机使用：

• 启动一个“其输出将被判定”的 run 之前——先设计好 stdout 证据再 launch；
• run 结束之后——用orx logs读回结果；
• 分析或汇报 run 结果之前——先完成证据校验，再下结论。

这与 agent-skills/orx-experiment-tree/SKILL.md 的自动研究循环衔接：步骤 4 明确要求“launch 前加载 orx-evidence，确保提交的代码输出足以判定该节点”；步骤 7 要求在每次完成时用orx logs <runId>真正读取结果，而不是从状态推断。

四、汇报前的校验清单：四步确认法

在接收或汇报任何由 run 推导的结论之前，禁止凭运行状态或记忆推断结果。必须逐项确认：

1. 日志标识了变体与有效配置——回显的配置与当前节点（branch/commit）对应；
2. 最终指标与紧凑摘要存在——末尾有完整的判定材料；
3. 长 run 的相关轨迹可恢复——周期性单行指标可被定位读取；
4. 返回的字节窗口确实包含支撑输出——你读到的内容覆盖了结论所依赖的那一段。

关键原则：截断不是“不存在”的证据

“Truncated output is not evidence of absence”（截断的输出不是不存在的证据）。当状态行显示(more above)或(more below)时，应继续用--head、--bytes或--range读取，直到相关部分被完整读到。反过来，一次只读 64 KB 就断言“日志里没有该指标”，同样属于证据误判。

失败 run 的取证路径

orx runs对 failed run 会额外打印reason:行。若失败信息未记录，会提示reason: — (no message recorded — see orx logs <runId>)（src/plane.rs）——明确把日志定位为失败归因的唯一途径。按 agent-skills/orx-compute/SKILL.md 的指引：provider 容量类失败通常可重试，而启动后的失败必须读取orx logs归因；一个 failed run 不构成新节点，应修复后重跑同一实验（见 orx-experiment-tree 的“repair, don't branch”）。

汇报格式：evidence-and-links 契约

校验通过后，按会话 playbook 的evidence-and-links 契约格式化聊天回复：每个由运行推导的结论都要链接到对应的证据文件（含完整嵌套路径），例如报告中的插图链接到figures/下可复现脚本旁的 SVG。这条契约由 agent-skills/orx-reports/SKILL.md 定义（其中明确“当报告包含由 run 结果推导的声明时，加载 orx-evidence”），并由测试在 src/local/agent_skills.rs 中强制校验：evidence 技能必须包含“Validate before reporting”与“Truncated output is not evidence of absence”，且与 reports 技能保持职责边界。

五、完整工作流：从设计证据到汇报

把前述要素串成一个可复用的闭环：

1. launch 前：加载 orx-evidence，检查 run 命令是否会打印最终指标、紧凑摘要与有效配置；长 run 确认有周期单行输出。需要时用orx project edit <projectId> --run-command '<cmd>'设定 run 命令（见 agent-skills/orx-create/SKILL.md）。
2. run 结束后：orx runs <projectId>拿到 run id 与状态；对 failed run 先读reason:，再决定是否需要取证。
3. 读证据：orx logs <runId>tail 读末尾摘要；摘要不足时按需--head、--bytes、--range补充，直到状态行不再提示截断、且目标字节窗口确实包含支撑输出。
4. 校验：核对四步确认法清单——变体标识、最终指标、轨迹可恢复、窗口覆盖。
5. 汇报：按 evidence-and-links 契约，把每个结论链接到持久化证据文件（参考 demo 的 demo/nanochat/evidence/evaluation-metrics.json 与 demo/nanochat/evidence/final-inference.txt 的组织方式）。

六、常见误区与边界

• 把 run 状态当结果：statusdone只说明进程退出码，不代表“答案正确”；结论必须来自日志内容。
• 把记忆当证据：多轮会话中容易凭印象汇报数字，任何 run 推导的声明都要回到日志与持久化证据核对。
• 一次 tail 就下结论：64 KB 默认窗口可能漏掉中部轨迹，(more above/below)提示出现时继续读。
• 截断视为缺失：截断只是窗口限制，不是内容不存在，用--head/--bytes/--range追读。
• stderr 状态行被忽略或误当正文：状态行进 stderr 是刻意的，| grep或重定向时它不会混入正文，但阅读完整输出时不要漏掉它传达的截断信息。
• --range写反：必须end > start，否则 CLI 直接报错退出。

边界方面需要说明：本文描述的字节语义、默认 64 KB 上限与 1 MB 上限、stderr 状态行格式，均以当前仓库的本地平面实现（src/plane/local_plane.rs）为准；不同 compute 后端（hf、modal、k8s、ssh、slurm、ray、openresearch、tinker）的日志来源字段与具体行为可能不同，但orx logs的 CLI 契约与证据校验原则一致。跨后端运行日志的读取均通过统一的LogRequest结构下发（src/plane.rs），保证了命令层的一致性。

【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearch