OpenResearch CLIorx完全指南用四条铁律驱动本地研究代理的实验树【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearchOpenResearch 是一个把编码代理变成研究代理的本地优先工作区而orxCLI 是驱动整个工作区的统一入口项目与实验分支的创建、算力的调度与监督、日志与证据的检视、实验树的生长管理全部收敛到这一条命令上。本文以仓库根目录的 SKILL.md 为骨架结合src/main.rs、src/commands/下的子命令实现与agent-skills/中的模块技能文档完整讲解orx的命令体系、四条不可违背的核心规则、典型工作流与底层实现细节让读者既能照抄命令跑通流程也能理解每条规则背后的设计动机。一、orx是什么一条命令管理整个本地研究闭环orxOpenResearch CLI是一个 Rust 实现的命令行工具负责拥有本地 Git 仓库中的项目project、实验分支experiment branch与执行execution并将状态持久化到本地 SQLite 数据库。它把本地仪表盘、运行调度、证据检视、文献检索与技能分发整合成一套树状子命令。从源码看CLI 入口 src/main.rs 使用clap的 derive 语法声明了完整的命令树Login、Logout、Projects、Orgs、Project、Agent、Runs、Logs、CreateExperiment、Compute、Instance、SshKey、Exp、Skill、Skills、Templates、InstallSkills、Discover、Paper、Version、Update、Delete、Serve、Supervise、Up、Telemetry等统一由一个异步tokio::main分发每个子命令路由到commands::name下的模块函数src/main.rs。orx up会在http://127.0.0.1:4791打开本地仪表盘用于导入或创建本地项目本地会话的 worktree 则用于以普通 Git 方式读取、diff 和编辑代码对应orx-git模块。安装方式与更宏观的项目定位可参考 README.mdcurl -LsSf https://openresearch.sh/install.sh | sh orx up根目录的SKILL.md刻意保持简短它承载四条铁律与一份命令速查表其余细节全部下沉到聚焦的模块文档中。加载某个模块使用orx skill name无参orx skill会在末尾打印全部内置模块及一行说明。从实现上印证这一设计的是 src/commands/skill.rs根目录的SKILL.md通过include_str!(../../SKILL.md)直接编译进二进制模块则统一放在仓库 agent-skills/ 目录下agent-skills/name/SKILL.md同样以include_str!内嵌src/local/agent_skills.rs既能在 GitHub 上直接阅读、又随二进制分发、还能原样安装进代理会话。二、四条铁律先读再做违反任何一条都会静默污染结果SKILL.md明确强调这四条规则不是风格偏好违反任何一条都会静默地使实验结果失效。它们也是orx-experiment-tree模块agent-skills/orx-experiment-tree/SKILL.md的理论前提。铁律一一个节点一旦被 run 回答过就永远不可再编辑节点node从 run 建立基线或检验假设的那一刻起被冻结frozen冻结是永久性的——包括根节点在内。一个令人失望的结果仍然是结果。在冻结之前节点处于临时provisional状态播种、修复依赖、让它跑起来都发生在它自己的分支上。想尝试新想法就分支出一个子节点去编辑。铁律二run 命令与环境是一份固定契约——每个节点必须完全一致子节点逐字继承父节点的 run 命令不允许给不同节点设置不同的启动命令也不允许通过环境变量或 env 前缀命令如LR3e-4 python …改变行为。节点之间唯一允许不同的是节点 Git 分支上已提交的代码/配置。项目的命令只需设置一次orx project edit projectId --run-command cmd从参数定义看--run-command的语义是设置项目默认运行命令新实验自动继承传空串可清除src/main.rs。铁律三变代码不要变命令里的旋钮超参数编码在代码/配置文件中每个变体分支出一个子节点——绝不通过改 run 命令或传环境变量来扫描超参。每个节点用相同命令跑不同代码因此它们记录的摘要结果保持可比性。铁律四树向下生长不要横向铺开在一轮round内部可以适度扇出一次决策的多个选项然后落到该轮的赢家上进入下一轮。根节点下挂一长排直接子节点、却没有孙节点的平扇是最典型的失败形态。SKILL.md给了一句直白的自我提醒无论何时想改命令、传环境变量、或往根节点上再堆一个节点——停下来。那是反模式不是捷径。三、Setup登录、登出与 API 地址解析orx login # 打开浏览器将 token 存储在 ~/.config/openresearch/credentials.json orx logout # 移除已存储的 tokenAPI 基础地址的解析顺序为--api-url→ 环境变量OPENRESEARCH_API_URL→ 内置默认值。非本地使用请设置OPENRESEARCH_API_URL。本地项目与 run 命令不需要 tokenOpenResearch 托管算力、实例供应与账户设置则需要先orx login。LoginArgs在源码中的定义印证了--api-url的存在覆盖 API 基础地址或设置 OPENRESEARCH_API_URLsrc/main.rs。四、命令速查全表SKILL.md强调作用域规则项目级命令接收 project id实验级命令接收 experiment idrun 级命令接收 run id三者不可混用。id 分别来自orx projects、orx project view、orx runs。下面按组完整呈现速查表并补充源码与模块文档中的参数细节。4.1 认证Auth命令作用orx login [--api-url url]打开浏览器执行 loopback OAuth存储 token。orx logout移除已存储的 token。4.2 发现与定位Discover项目级与实验级命令作用orx projects [--json]列出本地orxstore 中的项目。orx orgs [--json]列出可用于 OpenResearch 算力的组织 id需登录。orx project view projectId展示本地项目详情与实验树。experiment id 从这里获取。orx runs projectId [--experiment id]以表格列出 run最新在前。run id 从这里获取。orx project view在实验树中会标注每个节点的 id、标题、分支根节点标记为[root]agent-skills/orx-experiment-tree/SKILL.md。--experiment过滤器由RunsArgs.experiment承载src/main.rs。4.3 Run 证据run 级——模块orx-evidence命令作用orx logs runId [--head] [--bytes n] [--range s:e]读取 run 的终端日志。日志读取的实现细节值得展开run 的终端输出在运行期间被实时捕获、结束后持久化。默认尾部读取结尾通常最有用--head从头读--bytes提高字节上限默认 64 KB最大 1 MB--range s:e读取精确字节窗口[start, end)。日志正文输出到stdout一条[source] bytes a–b of N状态行输出到stderr用于提示截断位置agent-skills/orx-evidence/SKILL.md。源码 src/commands/logs.rs 展示了实现--head切换head/tail模式--range按:拆分并校验end start非法时以非零退出并提示错误随后通过resolve_run定位 run构造LogRequest { mode, max_bytes, start_byte, end_byte }交给 plane 层读取。4.4 创建与运行实验写操作——模块orx-create、orx-compute、orx-git命令作用orx up打开本地仪表盘导入或创建本地项目。orx project edit localProjectId [--name n] [--run-command cmd]编辑本地项目的名称或固定 run 命令。orx create-experiment localProjectId --title t [...]新增本地实验节点打印其 Git 分支。orx compute [--gpu id] [--count n] [--provider name]/orx compute --cpu浏览 GPU/CPU 算力目录。orx instance create orgId (--gpu id … \| --cpu flavor …)在组织内拉起独立实例见orx-instances。orx exp status/run/cancel/wait/wake localExpId检视、运行、取消、等待或注册本地实验节点的唤醒。orx exp desc expId [--set text \| --stdin]读取或覆写实验描述。orx agent spawn task [--title t] [--stdin] [--no-wake]向辅助会话委派独立任务见orx-agent-delegation。创建项目的流程agent-skills/orx-create/SKILL.mdgit clone https://github.com/owner/repo # 已有实现优先而非空白仓库 orx up # 仪表盘中导入该 checkout或新建项目 orx project edit localProjectId --run-command command # 启动实验前先设好命令新增实验节点# 空项目中的第一个节点基线根 orx create-experiment localProjectId --title Baseline # 从既有实验分支出的子节点 orx create-experiment localProjectId --title Larger batch \ --parent localExperimentId \ --description Increase batch size and compare throughput and loss. # 项目已有根时显式再建一个根 orx create-experiment localProjectId --title Alternative baseline --baseline要点第一个无父节点即基线之后的无父节点默认挂到最老根下除非--baseline显式要求另建根子节点从父节点 Git 分支分出并继承 run 命令改动应落在代码/配置上--description应写明该节点要做的具体改动与要度量的指标启动前必须提交节点分支——run 使用的是该本地提交的不可变归档。启动与监控算力agent-skills/orx-compute/SKILL.mdorx exp status expId # 分支、父节点、run 命令、最近 run 与提交 orx compute # 浏览所有供应商的 GPU 报价 orx compute --gpu H100_SXM --count 1 # 按 GPU 型号过滤 orx compute --cpu # 浏览纯 CPU 报价 orx exp run expId # 在配置的默认后端上启动 orx exp cancel expId # 取消在途 run通用启动契约所有实验算力一律通过orx exp run启动绝不直接调用供应商 CLI、调度器、裸 SSH 或训练命令本身worktree 只用于编辑与编排直跑任务不受跟踪、可能运行非记录提交的代码run 命令保持固定提交后再启动每个后端都运行记录提交的不可变快照未提交文件一律排除且任何后端都不需要 GitHub pushorx exp run会排队并立即返回之后配合orx runs/orx logs/orx exp wait/orx exp wake使用--force允许在同一实验上刻意并发运行否则该节点已有在途 run 时会被拒绝。4.5 文献与论文无需登录——模块orx-lit-review官方建议在任何学术/研究类查询论文、作者、博客、模型发布的网络搜索之前优先使用命令作用orx discover keyword query调用 alphaXiv 全文检索原语返回带匹配片段的结果。orx discover embedding query调用 alphaXiv 语义检索原语。主代理负责对候选排序并决定聚焦的追问见orx-lit-review。orx discover openalex query检索跨学科 OpenAlex 学术图谱。orx discover biorxiv query通过 OpenAlex 的 bioRxiv 索引检索 bioRxiv 预印本。orx paper id\|url [--source ...] [--full]抓取论文alphaXiv 报告自动回退全文--full强制原始文本或 OpenAlex/bioRxiv 的元数据摘要。来源从 id 自动检测。源码中这些检索原语对应Command::Discover与Command::Papersrc/main.rs模块文档见 agent-skills/orx-lit-review/SKILL.md。4.6 技能与模板——模块orx-customize命令作用orx skills add path从SKILL.md文件或技能 ZIP 保存可复用技能跨项目生效。orx templates add path从.tex文件或模板 ZIP 保存可复用 LaTeX 模板跨项目生效。4.7 元命令Meta命令作用orx skill [name[/resource]]打印本总览、某个内置模块、或某个懒加载模块资源如compute/hf。五、模块体系细节在哪里、如何加载orx把细节下沉到聚焦模块orx skill name加载无参orx skill末尾打印完整清单与一行说明。各模块在仓库中对应agent-skills/name/SKILL.mdorx-experiment-tree—— 实验树模型、自动研究循环与orx exp descagent-skills/orx-experiment-tree/SKILL.md。orx-create—— 初始化本地项目、新增本地实验节点agent-skills/orx-create/SKILL.md。orx-compute—— 启动与监控 run解析后端后阅读其捆绑参考文档agent-skills/orx-compute/SKILL.md后端参考见agent-skills/orx-compute/references/下的hf.md、k8s.md、local.md、modal.md、openresearch.md、ray.md、slurm.md、ssh.md、tinker.md。orx-instances—— 为手工工作创建持久独立机器agent-skills/orx-instances/SKILL.md。orx-git—— 用普通 git 读取、编辑、diff 节点代码agent-skills/orx-git/SKILL.md。orx-agent-delegation—— 安全地把独立工作委派给辅助会话agent-skills/orx-agent-delegation/SKILL.md。orx-evidence—— 通过 run 日志捕获与检视实验结果agent-skills/orx-evidence/SKILL.md。orx-reports—— 将持久研究产出写入项目 artifacts 目录agent-skills/orx-reports/SKILL.md。orx-figures—— 用 matplotlib 或 TikZ 产出出版级图表在写任何绘图代码之前加载再读对应图表类型的参考agent-skills/orx-figures/SKILL.md。orx-customize—— 跨项目添加可复用技能与 LaTeX 模板agent-skills/orx-customize/SKILL.md。orx-paper—— 以可渲染、可编译为 PDF 的 LaTeX 起草论文/预印本agent-skills/orx-paper/SKILL.md。orx-lit-review—— 主代理跨语料检索、按来源选择的追问策略与论文内容学术/研究类查询的推荐起点agent-skills/orx-lit-review/SKILL.md。从实现角度这些模块由 src/local/agent_skills.rs 统一管理AgentSkill结构体承载 name、description、完整SKILL.md内容与可选懒加载资源SkillSet区分Local安装进orx up会话 worktree每轮新鲜生成供会话代理自动发现与Full含项目引导orx install-skills --full写入代理全局技能目录。模块名统一加orx-前缀使技能列表中一目了然。orx skill命令解析name或name/resource路径未知技能会报错并列出可用清单src/commands/skill.rs。每个SKILL.md只有一份权威正文本地会话与完整集共用同一模块体避免漂移。六、典型工作流从定位到驱动项目只读定位在项目中辨明方向orx projects # 找到 project id orx project view projectId # 查看实验树挑选 experiment id orx skill experiment-tree # 加载模型与自动研究循环 orx runs projectId # 找到 run id orx logs runId # 读取其输出实际驱动项目朝目标前进在节点 Git 分支上改代码、保持轮次前进时遵循orx-experiment-tree的自动研究循环每个完成的 run 都是一个决策点有四种动作——repairrun 未回答任何问题时修复同一节点、refill结果平庸启动下一个排队子节点补位、promote明确胜出该节点成为下一轮的父节点并下潜、stop目标达成或分支耗尽。6.1 树的正确形状堆叠灌木而非平扇或面条orx-experiment-tree模块明确指出最常见的驱动失误是树的形状错误存在两种相反的错误形态正确形态介于其间FLAT FAN (错误) NOODLE (错误) STACKED BUSHES (正确) root root root ├ a ├ b ├ c ... ├ n └ a └ lr-head ┐ 第 1 轮 └ b ├ lr 2e-5 │ 少量并列选项 └ c └ lr 3e-5 ┘ 的小扇 └ d ... └ winner ── arch-head ┐ 第 2 轮 ├ arch-A │ 落到第 1 轮 └ arch-B ┘ 赢家之上平扇flat fan整个扫描挂在根下每个结果都对着起点度量胜果从不累积树毫无进展。面条noodle为深而深的单子链每一步并没有真正建立在上一层之上。堆叠灌木stacked bushes正确一轮内部小扇出一次决策的选项然后落到该轮赢家进入下一轮。产生正确形状的唯一规则在把 X 设为 Y 的子节点之前说清楚 Y 建立了什么、X 在此基础上构建什么。说得出来Y 是 LR 赢家X 保留该 LR 只改架构→ 真深度X 是 Y 的子节点下潜说不出来X 与 Y 是同时尝试的并列选项如 lr 2e-5 vs lr 3e-5→ 它们是同簇兄弟扇出而非串链。即宽度 一次决策的开放选项3 路 LR 扫描就该是公共头下的三个兄弟深度 已解决的决策的堆叠每保留一个赢家下潜一层。每轮用orx project view projectId重读树并检查形状。6.2 自动研究循环的落地命令轮次示例一轮一个决策、选项从基线扇出下一轮落到赢家# 第 1 轮 —— 一个决策LR选项从基线扇出 orx create-experiment projectId --parent baseId --title LR 2e-5 \ --description Set the LR in config.yaml to 2e-5; change nothing else. orx create-experiment projectId --parent baseId --title LR 3e-5 \ --description Set the LR in config.yaml to 3e-5; change nothing else. # 第 2 轮 —— LR 3e-5 胜出 → 下一决策架构落在它上面 orx create-experiment projectId --parent lr3e5WinnerId --title Wider MLP \ --description On top of the LR-3e-5 winner, widen the MLP hidden dim 1024→2048 in model.py.子节点自动继承父节点 run 命令——不需要设置也绝不给兄弟节点不同命令或环境变量铁律二。orx create-experiment会打印子分支名orx/slug在 worktree 中git checkout orx/child-slug # …只编辑该想法涉及的文件… git commit -am cosine LR warmup不要碰 run 命令。启动前加载orx-evidence确保提交的代码输出足够的 run 证据。随后orx exp run childId --backend b启动本轮就绪的子节点省略--backend时用已配置的默认目标远程后端可并行跑兄弟节点--backend local共享本机 CPU、RAM、GPU。6.3 每完成一个就驱动的循环orx exp wait --project研究推进的关键是逐完成驱动而非等全批跑完——任何一个 run 结束就应拿回控制权分析它、补位或停止# 启动 run 后循环直到项目耗尽 loop: orx exp wait --project projectId # 睡眠第一个完成时返回 orx runs projectId # 真相来源重读全部 run 状态 # 对每个尚未处理、现已终态的 run # - 读其结果第 7 步并决策补位提升停止 # - 启动下一个排队子节点补上腾出的槽位第 5 步 # 若 exp wait 打印 drained: no runs in flight → 批次结束跳出循环三条稳健性要求exp wait --project是睡到变化的信号不是真相来源。它只报告这一次调用期间观察到的完成你分析上一条 run 时完成的 run到下次调用时已处于终态、不会被报告。因此每次醒来都要重读orx runs projectId对照已处理集合对每一个新终态 run 采取行动——这正是唯一应该循环查看orx runs的时机作为每次醒来的对账而非替代exp wait的紧轮询。每拍重新发起exp wait一次完成 → 一次返回 → 你决策 → 再调用。别指望单次exp wait阻塞到全部结束。以 drained 终止无在途 run 时exp wait --project立即返回并打印drained: no runs in flight——或orx runs全部终态且无更多子节点可启动——即退出条件不要一直调用到超时。源码层面的对应orx exp wait的--interval默认 5 秒、--timeout默认 1800 秒超时以非零退出、表示尚未变化而非run 失败。expId模式是电平触发轮询该实验最近 run 直到终态--project模式是边沿触发快照项目全部 run第一个 run完成即返回——这正是槽位刚腾出的信号run 启动与 queued→running 转换被有意忽略二者传参互斥src/commands/exp.rs。失败的 run 会带reason:行供应商容量类失败通常可重试启动后失败则必须读orx logs runId。改为休眠若想结束本轮、在该 run 成功或失败后再恢复用orx exp wake expId。唤醒是opt-in的只在done或failed时触发且排在排队用户消息之后wait 与 wake 对一个 run 只用其一。源码显示orx exp wake仅在本地orx up代理会话内可用通过register_run_wakeup为 run 注册会话唤醒并区分 Scheduled / AlreadyPending / AlreadyDelivered 三种注册结果src/commands/exp.rs。6.4 决策点四动作与停止条件每个完成都应在循环内实际读取结果orx logs runId而不是由状态推断用orx-git的 diff 手段看完成节点到底改了什么。四种动作Repair—— run 未回答任何问题修该节点分支并重新启动同一节点。Refill—— 结果平庸或不确定启动下一个排队子节点让轮次继续。Promote—— 明确胜出该节点成为下一轮的父节点下一批子节点从它而非基线分支胜果前移、新想法堆叠其上跳过它正是产生平扇树的元凶。Stop—— 目标达成或分支已穷尽。目标达成、或连续约 3 次失败/回退后停止停止时把树写成带描述性名字的项目 artifact见orx-reports。运行或改动过实验的轮次收尾时应给出简短实验摘要每个相关节点一行写明测了什么、状态与要点结果。6.5 实验备注orx exp desc每个实验节点携带自由格式 markdowndescription——与create-experiment --description设的是同一字段用作笔记、假设或滚动摘要它是整文档字段写入即整体覆写orx exp desc expId # 打印到 stdout空 → 提示写到 stderr orx exp desc expId --set tried lr3e-4, diverged at step 4k # 短注覆盖 cat notes.md | orx exp desc expId --stdin # 从 stdin 覆盖长 markdown读文本打到stdout便于管道/重定向为空时提示打到stderr、stdout 保持为空。写--set行内与--stdin整个 stdin二选一同时传是错误写入替换整个描述要追加需先读、再改、再写回。expId来自orx create-experiment输出或orx project view projectId是实验 id不是 run 或 project id。七、证据与 Git让结论可检验、可追溯证据通道是 run 日志orx-evidence模块让 run 命令把评判结果所需的一切打到 stdout——结尾打印最终指标与紧凑摘要块、回显实际生效的配置让日志识别变体、长 run 周期性打印单行指标便于按字节窗口读轨迹。报告前验证四件事日志标识了变体与有效配置最终指标与摘要存在长 run 轨迹可恢复返回的字节窗口确实包含支撑输出。截断不是证据缺失——用--head、--bytes、--range读到相关部分为止。Git 记录每一次实验orx-git模块每个节点有本地orx/slug分支由orx create-experiment从父节点创建。会话 worktree 默认 detached 在基线上编辑前先检出实验分支、只做该实验的改动并提交运行器从记录提交构建不可变源码归档因此已提交即足够跑任何后端未提交文件从不进 run——启动前确认git status --short为空并用git show --stat --oneline HEAD检视记录提交。比较子父节点只用本地引用git diff parent-branch...orx/child-slug git log --oneline parent-branch..orx/child-slug一个 run 回答过某实验后其分支与历史即不可变绝不 merge 或 rebase 它要吸收他人工作就创建子节点、把 merge 提交放在子节点分支上。实验历史记录的是实际运行的精确代码。八、补充算力选型与规模建议orx-compute给出了务实的选型原则先决定 GPU 还是 CPUAPI 驱动的评估与数据准备通常 CPU 更划算选能装下模型与最小 batch 的最小规格遇到真实的 OOM 或慢到绝望再升级而不是一开始就用最大加速卡只有真正长 run 才提高超时。所有后端共享同一契约不可变快照、固定命令、先提交后启动、统一经orx exp run调度——这正是四条铁律在算力层的落地。结语orx的设计哲学是少而严命令面窄、规则硬、模块深。四条铁律把实验可复现从口头承诺变成机制约束——冻结节点、固定命令契约、代码承载变体、树向下生长——而orx skill name的模块体系把全部细节按主题分发到agent-skills/下可直接阅读的文档。对想驱动 OpenResearch 做自动研究的代理或开发者而言记住一句总纲即可命令固定变体进代码结果留在日志树永远向下长。深入细节时随时orx skill name取用对应模块。【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考