OpenResearch（orx）仓库开发指南深度解读：架构分层、开发规范与 CI/发布门禁实战

发布时间：2026/9/19 22:31:17
OpenResearch（orx）仓库开发指南深度解读：架构分层、开发规范与 CI/发布门禁实战
人工智能AI Agent深度研究自主智能体Agent 编排【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址https://gitcode.com/GitHub_Trending/op/OpenResearch点击查看免费下载本文围绕仓库根目录的 AGENTS.mdRepository Guide仓库开发指南展开。该文件同时是 CLAUDE.md 的唯一内容来源——CLAUDE.md全文仅一行AGENTS.md即“请以 AGENTS.md 为准”因此它是本项目面向开发 Agent 与人类贡献者的核心元文档。读完本文你将掌握orxCLI 与openresearch.sh服务之间的职责边界、Rust 后端与 UI 前端的目录约定、基于 dev-slot 的本地开发隔离机制以及从 PR 到发布的全链路 CI 门禁设计并了解每一处规则背后对应的源码实现。一、先看元文档结构CLAUDE.md 与 AGENTS.md 的关系在 OpenResearch 仓库中CLAUDE.md 并没有重复堆砌规则而是采用 Claude Code 生态中常见的“指针文件”写法AGENTS.md指令表示“将 AGENTS.md 的内容并入本文件”。这意味着对 Claude Code 而言加载CLAUDE.md等价于加载根目录的 AGENTS.md对 OpenCode、Codex、Cursor 等其他 Agent仓库根目录的AGENTS.md是通用入口对贡献者而言维护者只需维护一份“Repository Guide”避免多份指南漂移。因此本文的技术主体实际是 AGENTS.md 这份仓库开发指南下面逐节拆解其内容并给出仓库内的源码佐证。二、仓库定位openresearch-cli 与 openresearch.sh 的双层架构AGENTS.md 开篇即界定了仓库的“是什么”openresearch-cliorx命令行工具的开源 Rust 实现。它拥有本地 CLI、仪表盘dashboard与 API、SQLite 存储、编码 Agent 集成、实验编排experiment orchestration以及各类执行后端execution backends。openresearch.sh配套的托管服务。它拥有官网与文档、账号与组织organizations、沙箱供给sandbox provisioning以及托管算力目录managed-compute catalogs。两者的数据边界非常清晰研究项目projects、实验experiments、运行runs、日志logs与工件artifacts全部保留在orx本地只有账号、组织、沙箱、托管算力这类“服务自有能力”才归属openresearch.sh。这一点与 README.md 中 “Local by default” 的承诺一致创建项目或启动运行不会发布你的代码。从 Cargo.toml 可以看到 CLI 的工程身份name openresearch-cli版本0.2.3edition 2021可执行文件名为orx[[bin]] name orx入口 src/main.rs。依赖选型也服务于“本地优先 静态链接”的目标rusqlite使用bundled特性编译 SQLite、reqwest关闭默认native-tls改用rustls注释明确写道“避免 OpenSSL 依赖让静态 musl Linux 构建干净链接”。AGENTS.md 还给出了跨仓库协作的边界规则修改认证、组织、沙箱或托管算力 API 时需查看对应的openresearch.sh实现并保持两端兼容除非明确纳入范围否则不要编辑配套仓库。三、目录布局与开发规范AGENTS.md 用四条规则概括日常开发约束全部可以在仓库中逐一验证3.1 代码分区src/ 与 ui/src/Rust 代码位于src/仪表盘位于ui/src/。保持本地专属行为留在本地仅对openresearch.sh自有能力使用生产 API 客户端。这与实际目录完全吻合src/下是按职责划分的 Rust 模块例如 src/commandsup、exp、runs、project等子命令、src/local本地后端与 Agent harness、src/jobsHugging Face、Kubernetes、Slurm、Ray、Modal、SSH 等执行后端ui/下则是基于 TanStack Router 的前端ui/src/routes、ui/src/components 等。“生产 API 客户端仅用于服务自有能力”与 README 中“本地 SQLite 存储 本地优先”的定位互为印证。3.2 本地开发必须走 dev-slot 隔离通过scripts/dev-slot.mjs运行本地应用实例使开发数据、端口与进程彼此隔离。这是一条硬性工程纪律本地调试不得直接复用生产数据目录而是让每个实例占用独立的 slot。dev-slot 的实现细节见 scripts/dev-slot.mjsslot 池FIRST_SLOT 1到LAST_SLOT 9scripts/dev-slot.mjs即最多 9 个并发开发槽位端口分配后端端口为4900 slotUI 端口为5200 slotscripts/dev-slot.mjs因此 slot 1 对应后端 4901 / UI 5201数据隔离通过环境变量注入独立路径——ORX_DATA_DIR、ORX_CACHE_DIR、XDG_CONFIG_HOME、CARGO_TARGET_DIRscripts/dev-slot.mjs所有数据落在~/.local/share/openresearch-dev/slot-N下两种数据库模式start --db empty以全新空库启动start --db copy则先用sqlite3 .backup对本地正式库做 WAL 安全的快照再复制 run-logsscripts/dev-slot.mjs便于带着真实数据复现问题生命周期管理start/status/stop/cleanup四种子命令配合flock/lockf咨询锁、进程组监督supervisor与端口归属校验确保一个 slot 的进程不会误杀另一个 slot。启动一个开发实例的典型命令对应 scripts/dev-slot.mjs 的用法说明node scripts/dev-slot.mjs start --db empty --open # 全新空库并打开浏览器 node scripts/dev-slot.mjs start --db copy # 复制本地正式库的快照 node scripts/dev-slot.mjs status # 查看当前工作区 slot 状态 node scripts/dev-slot.mjs stop # 停止受管的后端与 UI 进程 node scripts/dev-slot.mjs cleanup # 移除 launch 注册项与数据目录该脚本自带单元测试 scripts/dev-slot.test.mjs并会在 CI 中执行见下文第五节。3.3 ui/dist 提交并嵌入发布构建ui/dist是已提交产物并嵌入发布构建。UI 改动后运行pnpm build并提交重新生成的资源。也就是说前端改动不是“只改源码”而是要重新构建、把ui/dist的产物一起提交。这正是 Rust 侧通过rust-embed将 SPA 静态资源编译进二进制的依据Cargo.toml 中rust-embed 8的依赖注释orx up仪表盘用axum做路由/SSE、rust-embed嵌入 SPA。3.4 Tailwind 主题规范优先使用规范的 Tailwind 工具类flex flex-col h-full min-h-0与项目主题别名bg-background、text-subtext、border-border。仅当不存在项目工具类时才使用任意值arbitrary values并保留依赖选择器或运行时行为的语义标记类。主题别名的实际定义位于 ui/src/base.css 等样式文件如--base、--highlight、--border等 CSS 变量前端组件中大量使用bg-background/text-subtext/border-border这类语义化类名。仓库还提供样式规范检查脚本 ui/scripts/check-styles.mjs并在 CI 中作为一道门禁运行。四、CI 与发布门禁AGENTS.md 的“上线红线”AGENTS.md 的第三节是整份指南最硬核的部分它定义了仓库的持续集成与发布纪律。我们逐条对照实际工作流文件。4.1 main 分支保护要求GitHub 对main的保护必须要求来自 GitHub Actions 的fmt, clippy, test与version sanity两项检查通过包括管理员不要求 merge queue也不要求分支保持最新。这些设置在 GitHub 侧管理不由本文件管理。这两项检查对应的正是 .github/workflows/ci.yml 中的两个 jobCI 检查对应 job主要职责fmt, clippy, testcheck前端 i18n/样式/单测、cargo fmt --all --check、cargo clippy --all-targets -- -D warnings、cargo build --locked、cargo test --locked并校验源码构建的 telemetry build channel 必须是developmentversion sanityversion-guard校验Cargo.toml版本只能前进、不能复用已发布 tag、版本升级必须携带重新生成的Cargo.lock4.2 PR 必须测试“GitHub 模拟合并”PR CI 必须测试 GitHub 的模拟合并refs/pull/number/merge——这正是actions/checkout在pull_request事件下的默认行为而不是只检出 PR 头部。每次运行测试各自的合并候选main后续变更不会自动重跑已打开的 PR。这条规则保证了 CI 验证的是“合并后的代码”而非 PR 分支本身避免“PR 上绿、合上就红”的经典陷阱。4.3 发布复用同一套 CICI 也运行在main上。发布会对被打包的提交调用同一 CI 工作流发布要求该运行成功。在 .github/workflows/release.yml 中可以看到custom-cijob 以workflow_call方式复用 .github/workflows/ci.ymluses: ./.github/workflows/ci.ymlrelease.yml并且最终的host发布 job 的if条件强制要求custom-ci结果必须为success或skippedrelease.yml。也就是说CI 不绿发布不进行。4.4 保持 ./ci 在 cargo-dist 的 global-artifacts-jobs 中重新生成发布工作流时保持./ci位于 cargo-dist 的global-artifacts-jobs中。这条“防回归”规则可以直接在 dist-workspace.toml 中验证# Verify packaged binaries and source CI before publishing. global-artifacts-jobs [./verify-build-channel, ./telemetry-contract, ./ci]即发布流水线在打包全局产物前必须依次通过./verify-build-channel——验证被打包二进制的构建通道对应 .github/workflows/verify-build-channel.yml./telemetry-contract——以ORX_OFFICIAL_RELEASE_BUILD1运行telemetry::tests::production_contract_is_accepted忽略测试确保生产遥测契约可被接受见 .github/workflows/telemetry-contract.yml./ci——即上文的完整 CI。4.5 构建通道的源码级机制build.rsverify-build-channel与“源码构建不得启用生产遥测”的约束底层由 build.rs 实现。核心逻辑是只有当ORX_OFFICIAL_RELEASE_BUILD1且处于 GitHub Actions且仓库为alphaXiv/OpenResearch时构建通道才是production否则一律是development任何越权设置都会直接panicbuild.rs。该通道值通过cargo:rustc-envORX_BUILD_CHANNEL注入编译环境供 src/telemetry.rs 的build_channel()读取并作为遥测上下文的buildChannel字段上报。五、CI 流水线全景ci.yml 的三个 job为了把第四节的规则落到实处这里完整梳理 .github/workflows/ci.yml 的三个 job5.1 checkfmt, clippy, test——平台无关的完整套件ubuntu-latest上依次执行.github/workflows/ci.yml本地化目录校验node ui/scripts/check-i18n.mjs样式 token 校验node ui/scripts/check-styles.mjsdev-slot 助手测试node --test scripts/dev-slot.test.mjsUI 依赖安装与消息编译pnpm install --frozen-lockfile后执行paraglide-js compileUI 类型检查与单测pnpm typecheck、node --test --experimental-strip-types ui/tests/*.test.mjsRust 质量门禁cargo fmt --all --check、cargo clippy --all-targets -- -D warnings、cargo build --locked构建通道校验断言target/debug/orx与target/release/orx的--build-channel均为development源码构建不可携带生产遥测Rust 测试cargo test --locked。5.2 windowswindows build, test——仅平台差异项windows-latest上只跑与平台相关的部分clippy、cargo build --locked、cargo test --locked并在非plan即真正发布时额外构建--release并上传orx.exe工件.github/workflows/ci.yml。注释说明得很直白debug 版orx.exe太慢会拉低测试者对仪表盘的观感因此交付物始终是 release 构建。5.3 version-guardversion sanity——版本升级的唯一合法入口该 job 仅在 PR 上运行.github/workflows/ci.yml校验三件事新版本号必须严格大于基线版本semver-aware 排序新版本号对应的v版本tag 不能已发布版本升级必须伴随重新生成的 Cargo.lock否则发布构建--locked会失败。它把关的其实是“合并即发布”的风险本仓库采用“合入一个 bump 版本的 PR 即触发发布”的模型因此在main之前的这道守卫至关重要。六、发布流水线从版本 bump 到 macOS DMGAGENTS.md 提到 CI 与发布强绑定配套工作流把这条链路完整落地6.1 版本 bump 触发发布release-on-bump.yml.github/workflows/release-on-bump.yml 监听main的 push若本次 push 恰好改变了 Cargo.toml 的版本且该版本尚未发布就向 release.yml 派发tagv版本。设计上刻意不推 tag而是走workflow_dispatch因为默认GITHUB_TOKEN引发的 tag push 不会触发其他工作流GitHub 的反递归规则而workflow_dispatch是文档化的例外。同时用 PATRELEASE_DISPATCH_TOKEN派发让 Release 运行的完成事件能级联触发 macOS 应用的自动附加。6.2 cargo-dist 驱动的发布release.yml.github/workflows/release.yml 由 cargo-dist 自动生成并定制执行plan → build-local-artifacts → build-global-artifacts → custom-* 门禁 → host → announce的完整流程最终创建 GitHub Release 并附带各平台安装器。其中custom-ci、custom-telemetry-contract、custom-verify-build-channel三个门禁全部通过host才会发布。6.3 目标平台矩阵dist-workspace.toml 声明了打包矩阵aarch64-apple-darwin、x86_64-apple-darwin、aarch64-unknown-linux-musl、x86_64-unknown-linux-musl、x86_64-pc-windows-msvc安装器为shell与powershell并启用dispatch-releases true发布由 workflow_dispatch 驱动tag 在 Release 发布时隐式创建无需任何工作流 push tag也就不需要额外 PAT。七、给贡献者与 Agent 的行动清单综合 AGENTS.md 的全部规则进入本仓库开发或作为编码 Agent 参与时应遵守如下顺序定位职责涉及认证/组织/沙箱/托管算力的改动需同时兼容openresearch.sh侧本地能力改动只需落在src/或ui/src/本地验证走 dev-slotnode scripts/dev-slot.mjs start --db empty|copy绝不直接复用生产数据目录UI 改动记得重新构建在ui/执行pnpm build并提交ui/dist产物样式遵循主题别名优先bg-background/text-subtext/border-border等语义类避免任意值提交前本地过门禁至少保证cargo fmt、cargo clippy --all-targets -- -D warnings、cargo test --locked、node --test scripts/dev-slot.test.mjs通过与 CI 的checkjob 保持一致版本升级走 PR新版本必须前进、对应 tag 未发布、且同步提交重新生成的 Cargo.lock——合并该 PR 即触发发布。八、深入阅读路线围绕本文涉及的主题可以在仓库中继续深挖以下文件元文档入口CLAUDE.md → AGENTS.md项目定位与使用方式README.md开发隔离机制scripts/dev-slot.mjs 及测试 scripts/dev-slot.test.mjsCI 门禁.github/workflows/ci.yml、.github/workflows/telemetry-contract.yml发布流水线.github/workflows/release.yml、.github/workflows/release-on-bump.yml、.github/workflows/release-macos-app.yml构建通道与遥测边界build.rs、src/telemetry.rs发布配置dist-workspace.toml、Cargo.toml。这份 Repository Guide 的价值在于它把“本地优先 服务侧能力外置”的架构边界、可复现的开发环境dev-slot、以及“合并即发布”的严谨门禁浓缩成了一份可执行的协议。无论你是人类贡献者还是编码 Agent遵循它就能在 OpenResearch 仓库中安全、可预期地推进实验编排与本地研究工具链的迭代。赞分享人工智能AI Agent深度研究自主智能体Agent 编排【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址https://gitcode.com/GitHub_Trending/op/OpenResearch点击查看免费下载相关推荐OpenMed 仓库工程指南深度解读从模块组织到发布守门人的完整开发规范OpenMed 仓库工程指南深度解读从模块组织到发布守门人的完整开发规范 本指南以 OpenMed 仓库根目录下的 AGENTS.md https://lin人工智能NLP医疗健康数据脱敏本地部署大模型AI 应用MCP 服务联邦学习Reth 贡献者开发指南架构地图、CI 门禁与 PR 规范全解析基于 AGENTS.mdReth 贡献者开发指南架构地图、CI 门禁与 PR 规范全解析基于 AGENTS.md Reth AGENTS.md https://link.git区块链终极解决方案HS2-HF_Patch如何彻底改变你的Honey Select 2游戏体验终极解决方案HS2 HF_Patch如何彻底改变你的Honey Select 2游戏体验 还在为《Honey Select 2》的语言障碍和功能限制而烦恼吗后端前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考