OpenResearch 拆解：把 Claude Code 变成科研 agent 的本地优先工作区

技术拆解：解析 AI 技术框架——说明、分析、技术评估、价值判断、落地使用。作者：永亮

---

2026 年 9 月 18 日，alphaXiv/OpenResearch 在 GitHub 上有 4,941 个 star（截至 9 月 18 日）、305 个 fork、42 个 open issues，MIT 协议，仓库创建于 2026 年 6 月 7 日——两个多月拿到近五千星，README 上挂了 Trending 第一的徽章（trendshift）。它做的事一句话说清：不新造一个科研 agent，而是把你已经在用的 Claude Code、Codex、OpenCode、Cursor 改造成科研 agent，给它们一套本地优先的工作区——文献综述、假设、实验、研究报告都是带版本的工件。这篇文章按六件事拆：是什么、怎么装、源码层三件套、冷静看、值不值、结论。

一、这是什么

OpenResearch 的自我定位写在 README 第一行：「The local-first workspace for research agents and autoresearch」，第二行更直白——「Turn your coding agents into research agents」。注意这个动词：turn，改造，不是 replace。它承认一个现实：科研 agent 需要的推理和工具调用能力，编码 agent 已经有了，缺的是科研这件事特有的结构——实验要可复现、假设要有血缘、证据要留在上下文里、成果要能被审阅。通用编码 agent 直接上手做研究，最常见的死法不是答错问题，而是把不同方向的改动搅在一个目录里、把一次跑通的结果当成可以引用的结论。OpenResearch 要补的就是这层结构。

技术栈本身就是这个定位的注脚。全仓 515 个文件，Rust 占 3.63MB（115 个 .rs 文件），扛本地运行时和 harness 管理层；TypeScript 1.38MB（89 个 .tsx 加 47 个 .ts）撑起 254 个文件的 ui/ 仪表盘；JavaScript 204KB 多在构建脚本，Python 只有 49KB、40 个文件，分布在 demo 和脚本侧。顶层目录 ui/、src/、demo/、agent-skills/（29 个文件）、macos/、docs/——一个「本地进程 + 浏览器界面 + 技能包 + 原生应用壳」的结构，桌面端也没落下。

README 把能力压成一张六行表格：并行探索（每个研究方向一个独立 agent 会话，配隔离的 git worktree）；可复现实验（git 原生的实验树，每次 run 是不可变归档）；证据在上下文；agent 自选（每个会话换 harness、换模型）；算力自选（本地、自有集群、托管）；本地所有权。这六条不是功能清单，是设计宣言——每一条都在回答通用编码 agent 做科研时的一个具体失灵。注意第六条「本地所有权」被单独列出来：工件和数据留在你自己的 git 仓库里，这在这个品类里是立场，不是功能。

二、怎么装怎么用

安装一条命令：

curl -LsSf https://openresearch.sh/install.sh | sh

装完 orx up，本地仪表盘起在 http://127.0.0.1:4791，之后的操作基本在浏览器里完成：开会话、看实验树、翻证据。命令行工具是 orx。平台覆盖 macOS 11 以上、Linux 一键、Windows beta（需要 Git for Windows）——beta 的标注照实写，稳定性自行评估，而且它强依赖 git，Windows 上先确认 Git for Windows 就位。模型侧可以接 LM Studio、oMLX、Ollama 或任何自定义 OpenAI 兼容端点，也可以直接用各家云 API；接本地模型意味着不联网也能跑完整流程，这条对数据敏感的研究是硬需求。

用法分两层。手动层：你在仪表盘里开多个会话，每个会话对应一个研究方向，各自跑各自的 agent，各写各的代码，你在树状视图里看哪个方向长出了结果。自动层叫 Autoresearch：给一个想法，agent 自己走完「提想法→改代码→跑实验→看证据→决定下一步」这一圈，多个 agent 并行推进，实验树保证每一步的血缘可查。

运行面有一个值得单独记的开关：orx up --remote user@host。同一份 committed 代码快照，可以跑在本地、SSH 远程机、Slurm 集群、K8s、Ray、HuggingFace Jobs、Modal、Tinker 或托管环境里——浏览器和数据留在你的笔记本上，计算扔到远程 GPU。对算力不固定在本地的人，这个开关决定了它是不是一个玩具：科研实验的算力大头在训练，笔记本只配看结果。

三、硬核拆解：源码层三件套

这是全文重头。README 说「local-first」「隔离」「可复现」，这些话每个工具都会讲。拆开源码看，三件事被落实得非常具体：实验树与 worktree 隔离、playbook 注入机制、agent-skills 模块化。行号都指得到。

3.1 实验树与 worktree 隔离

科研 agent 最大的隐患是串味：两个方向的 agent 在同一个目录里改代码，互相覆盖，最后谁也说不清哪个结果来自哪份代码。OpenResearch 的答案在 src/local/git.rs 的 ensure_session_worktree——每个会话启动时保证有自己的 git worktree，源码注释把原则写得很白：「one opencode serve child per chat session, cwd=私有 worktree」。一个会话一个 agent 子进程，工作目录是私有 worktree，文件系统层面就把两个方向隔开了，agent 之间不需要任何自觉。

worktree 之上是实验树。每一次实验 run 对应树上的一次 commit，不可变归档——run 结束后那份代码、那份配置、那份输入不会再变，后来的对比都是在和历史快照对话而不是和一团活代码。这条设计的价值在写论文那一刻兑现：每个数字都能指回一棵可重放的树，审稿人要复现，把树 checkout 出来重跑即可。git 在这里不是版本控制的附加品，是实验数据结构本身——这是「git 原生」三个字真正的分量。

3.2 playbook 注入：给每个 agent 换脑子

改造编码 agent 的第一道关卡是系统提示词。OpenResearch 没有要求用户去各家工具的配置文件里手写科研指令，而是内置一份 SYSTEM_PROMPT.md——一份科研 playbook，orx up 时经各家 agent 的原生通道注入每个会话。三条通道在源码里各有落点：Claude Code 走命令行参数，src/local/claude.rs:481 调用时带上 --append-system-prompt-file；Codex 走 developerInstructions 字段；OpenCode 走 config 的 instructions 列表。同一份 playbook，三家 harness，各自用自家认的口子喂进去——这是「turn your coding agents」在工程上的真实含义：不劫持、不补丁，用原生机制，agent 以为自己只是在正常开工。

playbook 本身不是静态文本。playbook_md() 在 src/local/opencode.rs:179，渲染时替换一批 {token} 占位符：项目事实、当前状态、算力默认值、工件路径。也就是说，同一个 Claude Code 会话在 OpenResearch 里启动时，拿到的是一份知道自己在哪个项目、工件放哪、默认往哪跑计算的科研角色卡，而不是一份通用的「你是一个有帮助的助手」。上下文工程从会话第一秒就开始了，省掉了用户每次手动交代背景的那几百字。

3.3 agent-skills：12 个模块的科研技能包

第二道关卡是技能。光会聊天不够，科研有自己的工序：怎么做文献综述、怎么归档实验、怎么出图表、怎么写报告。agent-skills/ 目录下按工序分了 12 个模块：orx-agent-delegation（agent 之间怎么委托任务）、orx-compute（算力调度）、orx-create、orx-customize、orx-evidence（证据管理）、orx-experiment-tree（实验树操作）、orx-figures（图表生成）、orx-git、orx-instances（运行实例管理）、orx-lit-review（文献综述）、orx-paper（论文写作）、orx-reports（报告生成）。每个模块一份 SKILL.md，开头是四条 cardinal rules——先把科研工作的红线立住，再谈怎么干活。会话内通过 orx skill <name> 按需加载，用哪个取哪个，不一股脑塞进上下文。

这三件套合起来的图景是：worktree 隔离保证物理上不串，playbook 注入保证每个会话从第一秒就按科研的规矩来，12 个技能模块保证 agent 知道文献综述和实验归档分别该怎么做。harness 管理层在 src/local/harness/ 下，claude.rs、codex.rs、cursor.rs、opencode.rs、opencode_v2.rs、detect.rs 六个文件，统一由 AgentHost（基于 axum 的本地服务）管理——多 agent 并行不是多个进程杂乱无章地跑着，是一个本地宿主在统一调度，detect 负责辨认机器上装了哪些可用 harness。Rust 写这层是合理选择：宿主进程要长时间活着、同时管多个子进程，内存安全和并发模型都用得上。

四、冷静看

先把口径说清。4,941 star 是两个多月的成绩，README 挂了 Trending 第一的徽章，属事实陈述；但 star 增速和工具是否堪用是两回事。两个月大的项目，42 个 open issues 摆在那，515 个文件里的接口和命令都还在动，今天写的接入方式明天可能改——MIT 协议倒是把最坏情况兜住了，就算项目停更，手上的版本也能继续用。

第二，「本地优先」是优点也是边界。工件、证据、代码全在本地 git 里，所有权清晰、离线能跑、接本地模型时数据不出机——这些对处理未公开数据、未发表结果的人是硬需求，投稿前的活本来就不该上云。但反过来，它目前没有一个中央化的共享层：团队协作、结果发布、跨机同步，都要靠你自己用 git 的既有机制拼，工具本身不替你做。习惯 GitHub 式协作的人，会在这里感到缺了一块。

第三，Autoresearch 的自主性要按宣传读。README 的描述是「提想法→改代码→跑实验→看证据→定下一步」，方向可信，但每一圈的质量取决于你接的模型和你给的算力，agent 选错方向的代价是烧掉一整棵实验树的算力。把它当自动化的研究助理用可以，当能独立产出结论的研究员用，现在不行。

第四，Windows 还是 beta。主力开发机是 Mac 或 Linux 的人无感，Windows 用户先想清楚 git 环境和 beta 状态能不能接受。

五、值不值

按人群分。在做 ML、系统或任何要跑实验的方向研究、已经在用 Claude Code 或 OpenCode 的人，这是最顺的接入路径：不迁移工具、不换习惯，orx up 之后你原来的 agent 就多了科研的骨骼——实验树、worktree 隔离、playbook、技能包全是现成的，学习成本几乎为零。需要本地跑模型的人（数据敏感、预算敏感），LM Studio、oMLX、Ollama 直连，算力自主权是完整的。算力在远程的人，orx up --remote 一条命令把计算放出去，本地留浏览器和工件，这个形态比在笔记本上硬跑健康得多。

暂缓的情形也清楚：不做实验性研究、只需要读论文写笔记的人，12 个技能模块大半用不上，杀鸡用牛刀，一个顺手的笔记流程就够了；团队协作需求重、需要中心化结果管理的人，本地优先的架构和你的需求方向相反；期待「agent 自动给我一篇论文」的人，Autoresearch 是流程辅助不是代写，预期错了会失望。另外 MIT 协议、本地运行，这两个条件让试错成本很低——装一下，拿一个小的复现任务走一遍流程，合不合手半天就知道，这是这类工具最划算的开箱方式。

结论

OpenResearch 回答了一个被回避很久的问题：科研 agent 一定要新造吗？它的答案是不——Claude Code、Codex、OpenCode、Cursor 的推理和工具能力已经够用，缺的是科研的结构，而结构可以用工程补上。源码里这个判断被落实得很具体：ensure_session_worktree 让每个会话有私有 worktree，一份 SYSTEM_PROMPT.md 经 --append-system-prompt-file（claude.rs:481）、developerInstructions、config instructions 三条原生通道注入各家会话，playbook_md() 在渲染时填入项目事实与算力默认值，12 个 agent-skills 模块经 orx skill 按需加载，harness 层由 AgentHost 统一调度。实验树长在 git 上，每个 run 是不可变归档，可复现性从承诺变成数据结构。对正在用编码 agent 做研究的人，这是目前最完整的「改造而非重造」方案；对研究 agent 工程的人，它示范了怎么把「本地优先」从口号落到行号。

参考来源

• alphaXiv/OpenResearch README（GitHub；定位、安装、六大能力表、Autoresearch、运行面）
• OpenResearch 源码（本地 clone）：src/local/git.rs（ensure_session_worktree）、src/local/claude.rs:481（—append-system-prompt-file）、src/local/opencode.rs:179（playbook_md）、src/local/harness/（claude.rs / codex.rs / cursor.rs / opencode.rs / opencode_v2.rs / detect.rs）、agent-skills/（12 个 SKILL.md）
• 仓库数据：4,941★、fork 305、issues 42、MIT、创建于 2026-06-07（截至 2026-09-18）