OpenResearch如何把Claude Code变成研究智能体？harness机制全解

OpenResearch如何把Claude Code变成研究智能体？harness机制全解

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

OpenResearch 是一个本地优先的研究智能体工作区，它的核心 trick 是一层harness 兼容层：通过统一的Harness抽象，把 Claude Code、Codex、OpenCode、Cursor 这些编码智能体（coding agent）改造成能读文献、提假设、跑实验、产出研究证据的研究智能体（research agent）。本文带你从源码角度拆解这套 harness 机制的完整设计。

为什么编码智能体"变不成"研究智能体？

编码智能体擅长写代码，但做研究还需要一套完整的工作流：创建实验基线 → 分支变体 → 并行跑实验 → 分析证据 → 决定下一步。直接让 Claude Code 裸跑，会出现乱改运行命令、用环境变量扫超参、把结论建立在不可复现的结果上等问题。

OpenResearch 的解法分两层：

1. harness 层：把各家智能体的 CLI 封装成统一接口，稳定地驱动它们完成一轮轮会话；
2. skill 层：把研究方法论文档"注入"智能体，让它遵守实验树的纪律。

harness 是什么：一个 trait + 一个注册表

整套机制的核心在 src/local/harness/mod.rs：一个Harnesstrait，四个智能体各一个实现文件：

所有消费方（会话调度、检测扫描、技能安装器）都只遍历同一个注册表 registry()：

新增一个 harness = 一个新文件里写一个impl Harness+ 注册表里加一行，其余代码零改动。

这就是"全解"里最值钱的设计：能力是可选的。每个 harness 最多提供三种能力，可以只实现其中一部分：

• detection（检测）：CLI 装没装、登没登录、账号和模型有哪些 → 驱动orx up界面里的智能体选择器；
• chat（驱动会话）：run_turn拉起 CLI、把各家原生事件流归一化成统一的 wire parts；
• skill install（技能安装）：往~/.claude/skills/orx等位置写入技能 shim，让智能体自动发现orx。

检测：先确认 Claude Code"可用"再开口

检测逻辑在 detect.rs，遵循"只读、尽力而为"原则——文件缺失或 JSON 解析失败只算"未检测到"，绝不报错。以 Claude 为例（claude.rs）：

1. claude --version探针：10 秒超时，从输出里解析出版本号（必须含数字才算真的版本行）；
2. claude auth status --json是登录状态的唯一事实来源，本地配置只贡献展示信息；
3. 认证状态归一为四档：Ready/NeedsLogin/Unknown/Unsupported，例如 OAuth 登录但 CLI 版本过旧（< 2.1.211）会降级为Unsupported，避免拉起一个会崩的子进程。

检测结果还会带上模型目录和每个模型支持的推理档位（detect.rs），供前端渲染模型选择器——选哪个模型、给多高的"思考力度"，都由检测到的真实能力决定，而不是硬编码。

一轮对话如何跑起来：run_turn 全链路

Claude Code 的适配是四种里最典型的（claude.rs 模块注释）：

• 每个会话一个常驻子进程：claude --print --input-format stream-json，stdin 保持打开，多轮对话复用同一个进程，省掉了每轮重新冷启动的开销；
• 事件流边界识别：每一轮从--replay-user-messages回显的那条用户消息开始，到result事件结束，中间的工具调用、文本全部归一化成 wire parts 推给前端；
• 配置变更或崩溃时自动--resume：权限模式、effort 档位变化，或进程挂了，就带着稳定session_id重新拉起，会话不断。

围绕这条链路还有三道"保命"设计：

权限模式与 Plan 门禁

各家智能体的权限词汇（"总是询问 / 自动接受 / 完全访问"……）被统一成一个内部枚举，再映射回各自的原生参数，定义见 options.rs。

Claude 的Plan 模式有个隐蔽的坑：headless 下--permission-mode plan会把任意Bash(orx …)当写操作拦截，而研究智能体恰恰要靠只读的orx runs、orx logs、git show来"看证据、做计划"。OpenResearch 的解法是一个PreToolUse钩子 orx plan-gate：只读命令放行，写操作保持拦截——规划可以随便看，动手必须等你批准。分类采用严格的白名单策略，未知命令一律视为"不读"。

灵魂一步：orx install-skills 注入研究方法

harness 解决了"怎么驱动"，skill 解决"怎么研究"。orx install-skills会把一个 SKILL.md shim 写入智能体的技能目录（如~/.claude/skills/orx/），shim 本身不含操作细节，只告诉智能体一句话：每个会话开始时先运行orx skill加载随 CLI 打包的最新操作手册。

真正的研究纪律写在 SKILL.md 的四条"铁律"里：

1. 节点一经实验回答就永久冻结——想试新想法，给节点分支一个子节点；
2. 运行命令和环境是固定契约——所有节点跑同一条命令；
3. 变代码，不变命令里的旋钮——超参写进代码/配置，按变体分支；
4. 树向下长，不横着铺——一轮内适度展开，然后沿着赢家往下走。

配套的模块化技能文档（如 orx-experiment-tree、orx-compute、orx-evidence）按orx skill <name>按需加载，覆盖实验树、多后端算力（Slurm / K8s / Ray / Modal / SSH）、证据分析等主题。

容易被忽略的细节

• 自动标题：新会话用一个廉价的"一次性子请求"（one_shot，无工具、30 秒超时）给会话起 6 词以内的短标题，并对模型爱加引号、尾句号的习惯做了防御性清洗（title.rs）；
• 引导（steering）：支持运行中向智能体插话的 harness 会在 UI 上开放"转向"输入，不支持的则排队到本轮结束（mod.rs）；
• 交互提示回流：Claude 的提问会让本轮结束、答案以--resume新消息续接；OpenCode 则在活协议上内联应答，两条路径统一收敛在resume_from_prompt接口后（mod.rs）。

上手三步

1. 从官方渠道安装 CLI（macOS / Linux 一条安装脚本即可），Windows 用 beta 包 + Git for Windows（见 docs/windows.md）；
2. 终端运行orx up，浏览器打开本地面板127.0.0.1:4791，harness 选择器会显示已检测到的 Claude Code 登录状态与模型；
3. 运行orx install-skills把研究技能注入你的编码智能体，之后在面板里给一个研究方向，智能体就会按实验树纪律自主迭代。

小结

OpenResearch 的 harness 机制本质上是把"驱动一个编码智能体"这件事抽象成检测、会话、技能三个正交能力，用注册表 + trait 让四个智能体平权接入；再叠加权限门禁、看门狗、重试与恢复快照这些工程化的"保险丝"，最后靠 skill 注入研究方法——于是 Claude Code 就从"帮你写代码"升级成了"帮你做研究"。想深入源码，建议从 src/local/harness/mod.rs 的模块注释读起，它几乎是整套机制的导读。

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