企业官网建设流程全解析

如何参与OpenResearch开发？dev-slot、CI与贡献者完整工作流

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

想参与OpenResearch（orxCLI）开发吗？本文带你走通从克隆仓库、用dev-slot一键起本地实例，到通过CI 检查与版本发布流的贡献者完整工作流。OpenResearch 是一个"本地优先"的研究智能体工作台，能把 Claude Code、Codex、OpenCode、Cursor 等编码智能体变成能读文献、跑实验、出成果的研究智能体。

🧭 先认识项目结构

在动手前，花 2 分钟看懂仓库布局，后面每一步都会用到：

核心约定写在 AGENTS.md 里：Rust 代码在src/，仪表盘在ui/src/；本地功能保持本地，只有openresearch.sh服务侧能力（组织、托管算力）才走生产 API 客户端。

💡 仓库里附带的 demo/nanochat/ 演示了一个完整研究闭环：用智能体训练 nanochat 并做缩放律分析。下图中正是研究智能体产出的实验证据——IsoFLOP 曲线与最优模型规模/训练 token 数：

📥 克隆仓库并搭建开发环境

OpenResearch 开发需要 Rust（stable）与 pnpm（Node 22+）。dev-slot 的生命周期管理仅支持macOS / Linux（见 scripts/dev-slot.mjs）。

git clone https://gitcode.com/GitHub_Trending/op/OpenResearch cd OpenResearch

工具基于git worktree工作：它要求恰好存在一个main分支的工作树作为主检出（worktreeInfo 逻辑），每个特性分支放在独立 worktree 中，互不干扰：

git worktree add ../openresearch-feature -b my-feature

🚀 用 dev-slot 一键启动本地实例

这是贡献者最重要的工具：它让每个 worktree 拥有独立的数据目录、端口和进程，避免污染你正常使用的orx本地库。

四条命令覆盖全部生命周期：

数据库两种模式（见 initializeDatabase）：

• --db empty：全新空库，从零验证功能；
• --db copy：对正常 CLI 数据库做WAL 安全快照，并复制运行日志——想复现真实数据问题时用它。

槽位分配规则：工具从 slot 1–9 中挑选空闲槽位（用flock/lockf加咨询锁防止竞态，见 acquireAdvisoryLock），每个槽位独占一组端口与目录：

所有数据落在~/.local/share/openresearch-dev/下：每个槽位有独立的ORX_DATA_DIR、ORX_CACHE_DIR、XDG_CONFIG_HOME（slotEnvironment），而CARGO_TARGET_DIR全局共享，避免每个 worktree 重复编译整个 Rust 依赖树。

启动时它会自动：为 UI 安装依赖（pnpm install --frozen-lockfile）→ 以cargo run -- up --no-browser --port <槽位端口>拉起后端 → 以pnpm dev --strictPort拉起 UI → 等待后端日志出现 "dashboard on" 且 API 就绪后，才打印可访问地址（startUnlocked）。

node scripts/dev-slot.mjs start --db copy --open # Dev slot ready (copy) # Backend: http://127.0.0.1:4901 # UI: http://localhost:5201/

✅ 提交前：对照 CI 做本地自检

CI 定义在 .github/workflows/ci.yml 中。合并前先在本地跑通这些检查，可大幅减少返工：

Rust 侧（对应fmt, clippy, test任务，ci.yml L75-L93）：

cargo fmt --all --check cargo clippy --all-targets -- -D warnings cargo build --locked cargo test --locked

UI 侧（ci.yml L40-L66）：

node ui/scripts/check-i18n.mjs # 国际化目录完整性 node ui/scripts/check-styles.mjs # 样式 token 检查 cd ui && pnpm typecheck # 类型检查 node --test --experimental-strip-types ui/tests/*.test.mjs

两个最容易踩的坑：

1. ui/dist是提交的。改了ui/src/后必须运行pnpm build并把再生成的产物一起提交（AGENTS.md）。
2. 样式规范：优先使用规范 Tailwind 工具类与项目主题别名（如bg-background、text-subtext、border-border），只在无可用工具类时才用任意值。

另外 CI 还会校验"源码构建的遥测通道必须是 development"（ci.yml L84-L90）——开发构建不发送任何使用分析，这条由 CI 强制保证，无需你处理，但改动version --build-channel相关逻辑时务必留意。

🛡️ CI 流水线与分支保护

PR 合并有三道关卡：

1. fmt, clippy, test：在 ubuntu 上跑上面全部检查，外加 dev-slot 自身的单测node --test scripts/dev-slot.test.mjs。
2. windows build, test：Windows 上单独跑 clippy、构建与测试，并产出 release 版orx.exe构件供下载——这是多数改动唯一会遇到的 Windows 环境，改 CLI 时值得留意。
3. version sanity（仅 PR 触发）：专门看守版本号，规则见 version-guard 任务：版本只能向前、不能复用已发布的 tag、版本号变化必须同步重新生成 Cargo.lock。

两个值得理解的 CI 细节：

• PR 测试的是GitHub 模拟合并结果（refs/pull/<编号>/merge），而不是你的分支头。也就是说 main 后续更新不会自动重跑已开的 PR——如果你怀疑 CI 结果过期，手动 re-run 或 rebase。
• main分支保护要求fmt, clippy, test与version sanity全部通过（管理员同样适用），不要求 merge queue（AGENTS.md）。

📦 版本发布流：bump 即发布

OpenResearch 的发布机制很优雅："合并一个 bump 版本号的 PR" 就是发布行为本身。

完整链路（.github/workflows/release-on-bump.yml）：

1. 你在评审过的 PR 中修改 Cargo.toml 的version，并重新生成Cargo.lock一起提交；
2. 合并推送到main后，release-on-bump.yml检测到"本次推送改动了版本且对应 tag 尚未存在"，才 dispatchrelease.yml（带version-bump标签标记 PR）；
3. release.yml基于 cargo-dist（配置见 dist-workspace.toml）构建 macOS（双架构）、Linux（musl 双架构）、Windows 安装包，发布 GitHub Release 时顺带创建 tag——没有任何工作流主动推 tag，规避了 GitHub 的防递归规则；
4. 发布前会先跑同一套 CI 工作流，CI 不成功就不发布。

普通贡献者不需要碰这条流，但如果你要参与发布或签名相关改动（.github/workflows/、/macos/、scripts/package-macos-app.sh），它们受 .github/CODEOWNERS 保护，必须经维护者评审——这些文件能触达 macOS 签名证书，属安全敏感区。

📋 贡献者速查清单

• 按main+ 特性 worktree 组织代码，用node scripts/dev-slot.mjs start --db copy --open调试
• Rust：fmt/clippy -D warnings/build --locked/test --locked全绿
• UI：改完记得pnpm build并提交ui/dist；i18n 与样式检查通过
• 本地功能保持本地化，服务侧能力才走生产 API 客户端
• 涉及版本号时同步重新生成Cargo.lock
• 若 CI 疑似过期，手动 re-run（模拟合并特性导致 main 更新不会自动重跑）

🎯 准备好后，挑一个带标签的 issue 或直接从小型 UI/文档改进入手，跑通一次 dev-slot → 本地自检 → PR CI 的全流程，你就正式加入 OpenResearch 的贡献者行列了。

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