openresearch-cli

OpenResearch CLI（orx）

orx up 在本地 Git 仓库和本地数据库中管理项目、实验分支和执行。使用本地会话工作树读取、比较差异和编辑代码（参见 orx-git）。

本概览刻意保持简短：先介绍基本规则和命令速查，然后指向其他内容对应的专门模块。使用 orx skill <name> 加载模块（orx skill 输出末尾会打印内置索引）。

基本规则 — 开始任何操作前请先阅读

以下四条规则适用于下面的所有内容。违反其中任何一条都会导致结果悄然失效——它们不是风格建议。orx-experiment-tree 模块会进一步解释原因；以下是不可妥协的规则。

1. 一次运行给出结果后，绝不再编辑该节点。 一旦某次运行确定了基线或测试了假设，节点就会冻结——包括根节点；而且冻结是永久的：令人失望的结果依然是结果。在此之前，节点处于临时状态：初始化节点、修复其依赖项并使其能够运行，都要在该节点自己的分支上进行（orx-experiment-tree）。要测试新假设，请创建一个子节点并编辑子节点。
2. 运行命令和环境是一份固定契约——每个节点都必须完全相同。 子节点会原样继承父节点的运行命令；不要更改它。不要为不同节点设置不同的启动命令，也不要通过环境变量或带环境变量前缀的命令（LR=3e-4 python …）改变行为。不同节点之间唯一可以不同的是节点 Git 分支上已提交的代码/配置。使用 orx project edit <projectId> --run-command '<cmd>' 为本地项目设置一次命令。
3. 改变代码，而不是命令中的参数。 将超参数写入代码/配置文件，并针对每个变体创建一个子分支——绝不要通过编辑运行命令或传递环境变量来进行扫描。每个节点都使用同一条命令运行不同的代码，因此记录的结果摘要保持可比。
4. 向下扩展树，而不是横向扩展。 每轮只进行少量分支（针对一次决策的选项），然后沿着该轮的获胜方案向下推进，进入下一轮。根节点下有一长排直接子节点、却没有任何孙节点，就是错误模式。请参阅 orx-experiment-tree 模块中的“塑造树结构”。

如果你想更改命令、传递环境变量，或是在根节点下继续堆叠节点，而不是创建子节点、编辑其分支并沿树向下推进——请停下来。这是反模式，不是捷径。

设置

orx login          # opens a browser, stores a token at ~/.config/openresearch/credentials.json
orx logout         # remove the stored token

• API 基础 URL 的解析顺序为 --api-url → OPENRESEARCH_API_URL → 内置默认值。非本地使用时，请设置 OPENRESEARCH_API_URL。
• 本地项目和运行命令不需要令牌。使用 OpenResearch 计算资源、配置实例和管理账户设置时，需要先运行 orx login。

命令速查

项目范围的命令使用项目 ID；实验范围的命令使用实验 ID；运行范围的命令使用运行 ID。不要混用——分别通过 orx projects、orx project view 和 orx runs 获取 ID。以下每组命令都有对应模块（orx skill <name>），其中包含完整的标志和规则。

身份验证

命令	功能
orx login [--api-url <url>] [--device]	打开浏览器，通过环回 OAuth 完成身份验证并存储令牌。--device（通过 SSH 时的默认选项）会打印链接和验证码，可在任意设备上完成授权。
orx logout	移除已存储的令牌。

发现（项目和实验范围）

命令	功能
orx projects [--json]	列出本地 orx 存储中的项目。
orx orgs [--json]	列出可用于 OpenResearch 计算资源的组织 ID（需要登录）。
orx project view <projectId>	显示本地项目的详情和实验树。实验 ID 可在此获取。
orx runs <projectId> [--experiment <id>]	按表格形式列出运行记录，最新记录在前。运行 ID 可在此获取。

运行证据（限定于运行）——模块 orx-logs

命令	功能
orx logs <runId>	显示本地日志路径、大小和简短预览；检查文件以查看完整证据。

创建和运行实验（写入）——模块 orx-create、orx-compute、orx-git

命令	功能
orx up	打开本地仪表板，以导入或创建本地项目。
orx project edit <localProjectId> [--name "<n>"] [--run-command "<cmd>"]	编辑本地项目的名称或固定运行命令。
orx project share <localProjectId> [--out <file> | --publish] [--chat <chatId>... | --no-chats] [--no-logs] [--no-artifacts]	仅在用户提出要求时，将项目代码、实验树、已完成的运行、日志、构件和聊天记录保存为 .orx 文件，以便发送给协作者。--chat 可将内容限定为指定的聊天记录。--publish（仅在用户要求提供链接时使用）会将文件上传到 openresearch.sh，并打印一个任何人都能打开的链接；再次发布会更新同一个链接。
orx project unpublish <localProjectId>	删除项目的已发布链接及其文件。
orx project import <file.orx | link> [--path <dir>]	将共享的 .orx 文件或 openresearch.sh/p/... 链接作为新的本地项目打开，并导入其树、运行和选定的聊天记录。
orx create-experiment <localProjectId> --title "<t>" [...]	添加本地实验节点；输出其 Git 分支。
orx compute status / show <backend> / test <backend>	检查全机范围的计算配置和就绪状态。
orx compute configure <backend> --help / default set <backend> / connect <backend>	配置计算或进行身份验证；加载 orx-compute。
orx compute instructions show --json	在配置或启动前读取全机范围的自定义配方及其修订版本。
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 move/archive/unarchive/delete <localExpId>	更改实验节点的父级、隐藏、恢复或永久删除；参见 orx-experiment-tree。
orx exp desc <expId> [--set "<text>" | --stdin]	读取或覆盖实验说明。

要读取或编辑节点代码（包括比较运行造成的更改），请在本地会话工作树中使用普通 Git。参见 orx-git 模块。

文献与论文 — alphaXiv / OpenAlex / bioRxiv / PubMed（无需登录）——模块 orx-lit-review

学术/研究查询（论文、作者、博客、模型发布）应先使用此模块，再进行任何网络搜索。

命令	功能
orx discover keyword "<query>"	调用 alphaXiv 全文检索原语，并返回匹配片段。
orx discover embedding "<query>"	调用 alphaXiv 语义检索原语。主 Agent 会对候选结果排序并决定后续聚焦查询；参见 orx-lit-review。
orx discover openalex "<query>"	搜索跨学科的 OpenAlex 学术图谱。
orx discover biorxiv "<query>"	通过 OpenAlex 的 bioRxiv 索引搜索 bioRxiv 预印本。
orx discover pubmed "<query>"	通过 NCBI E-utilities 搜索 PubMed 生物医学文献。
orx paper <id|url> [--source <source>] [--full]	获取论文：alphaXiv 报告（自动回退到全文；--full 强制获取原始文本），或 OpenAlex/bioRxiv/PubMed 的元数据与摘要。根据 ID 自动检测来源。

技能与模板——模块 orx-customize

命令	功能
orx skills add <path>	从 SKILL.md 文件或技能 ZIP 保存可在多个项目中重复使用的技能。
orx templates add <path>	从 .tex 文件或模板 ZIP 保存可在多个项目中重复使用的 LaTeX 模板。

元信息

命令	功能
orx skill [name[/resource]]	打印此概览、一个捆绑模块，或一个延迟加载的模块资源，例如 compute/hf。
orx feedback --kind <bug|feature_request|frustration> --summary <summary> --details <details>	向维护者报告有意义的 OpenResearch 错误、功能请求或用户困扰。请参阅 orx-feedback 模块。

模块

详细信息位于各个专门模块中——使用 orx skill <name> 加载模块（orx skill 输出末尾会打印捆绑模块列表及其单行描述）：

• orx-experiment-tree — 实验树模型、自动研究循环，以及 orx exp desc。
• orx-create — 初始化本地项目并添加本地实验节点。
• orx-compute — 启动并监控运行；解析后端后，阅读其捆绑参考资料。
• orx-instances — 创建可持久使用的独立机器，以便手动操作。
• orx-git — 使用普通 git 读取、编辑和比较节点代码。
• orx-agent-delegation — 使用 orx 的 MCP 工具将任务委派给其他模型和聊天。
• orx-logs — 获取持久化的运行输出，用于查看进度、调试或测量。
• orx-results — 解读、比较和总结实验结果的测量数据。
• orx-reports — 将可长期保存的研究成果写入项目的 artifacts 目录。
• orx-figures — 使用 matplotlib 或 TikZ 绘制可用于发表的图表。编写任何绘图代码前，请先加载此模块，然后阅读对应图表类型的参考资料。
• orx-customize — 在多个项目中添加可复用的技能和 LaTeX 模板。
• orx-paper — 使用 LaTeX 起草论文或预印本，并将其渲染和编译为 PDF。
• orx-feedback — 报告有意义的 OpenResearch 错误、功能请求和用户困扰，同时避免泄露研究详情。
• orx-lit-review — 主 Agent 跨语料检索、按来源选择的后续跟进策略及论文内容；这是学术／研究类查询的首选起点。

典型工作流

了解项目情况（只读探索）：

orx projects                     # find the project id
orx project view <projectId>     # see the tree, pick an experiment id
orx skill experiment-tree        # the model + the auto-research loop
orx runs <projectId>             # find a run id
orx logs <runId>                 # locate its log, then inspect the file

若要实际推动项目实现目标——在 Git 分支上编辑每个节点的代码，并持续推进每一轮——请遵循 orx-experiment-tree 模块中的自动研究循环。每次运行完成后，都会进入一个决策点，有四种选择：如果运行未能得出结论，就在同一节点上修复；用另一个同级节点补充本轮；晋升胜出者并继续向下推进；或者停止。