企业官网建设流程全解析

cloudroom-core 是一个开源、可自托管的 Rust 运行时，让 Claude Code、Codex、Pi 等 AI 编程 Agent 运行在你自己的 Linux 机器上，并持久保存它们的对话历史。本文将带你从零开始：搭建环境、构建二进制、跑通cargo test与 Python E2E 测试套件，最后了解如何以 Apache 2.0 许可证参与这个开源项目。

📦 先认识仓库：目录结构一眼看懂

打开仓库，你会看到清晰的三层结构：

几个值得先看的文件：

• src/main.rs：服务入口，同时提供preview、secret、thread等 CLI 子命令
• src/api/mod.rs：HTTP API 层
• src/runtime/mod.rs：Agent 进程驱动，src/runtime/claude.rs、src/runtime/codex.rs、src/runtime/pi.rs 分别对接各家 CLI
• src/session/mod.rs：会话状态、队列与恢复逻辑
• docs/setup.md：官方部署指南（Ubuntu 24.04）

项目约定是「一个 Rust 包、一个服务，应用集成全部走 API」，见 AGENTS.md。

🛠️ 一键搭建开发环境

环境需求很轻：

• Rust 1.89+：Cargo.toml 中声明rust-version = "1.89"
• Git
• Node.js 24（部分 harness 依赖，需系统级安装到/usr/local/bin或/usr/bin，不能只装在 nvm 里）
• 你想运行的Agent CLI（Codex、Pi 等）

克隆仓库：

git clone https://gitcode.com/gh_mirrors/cl/cloudroom-core cd cloudroom-core

🔨 构建二进制：cargo build 快速上手

两条核心命令（来自 README.md）：

cargo build --locked --release cargo test --locked --all-targets

💡小贴士：始终保留--locked参数，它强制使用 Cargo.lock 锁定的依赖版本，避免依赖悄悄漂移导致构建不一致——这也是本项目 CI 的硬性要求。

构建完成后，优化产物位于target/release/cloudroom，部署时会被安装到/usr/local/lib/cloudroom/cloudroom，由 systemd 服务拉起，细节见 docs/setup.md 与 install/cloudroom.service。

✅ 跑通 cargo test：理解测试分层

项目的测试体系分为Rust 集成测试和Python E2E 测试两层。

Rust 集成测试：cargo test --all-targets

cargo test --locked --all-targets会执行 tests/ 下的 Rust 测试。它们用「fixture 假 CLI」替代真实 Agent，确定性极强：

Python E2E 测试：真实 HTTP + 模拟网站

tests/里还有一组 Python 脚本，启动真实的 Rust 服务进行端到端验证：

• tests/core_e2e.py：核心 E2E，用 tests/fake_api.py 模拟 Cloudroom 网站；--fixture模式可在不产生真实推理的情况下检查 HTTP 与诊断；只把选中账户的auth.json复制到一次性 Codex home，绝不改动已有数据库和服务
• tests/core_fixture.py：确定性的 Rust HTTP / Codex 协议检查，无需推理和数据库
• tests/pi_e2e.py、tests/cursor_http.py：针对 Pi / Cursor 的协议测试，涉及真实推理的脚本需要已安装的 CLI 和有效凭证
• tests/storage_e2e.py：磁盘安全测试，只能以 root 身份在一次性 Linux VM 上运行（sudo python3 tests/storage_e2e.py --disposable --mixed），切勿在客户主机上执行

官方验证清单（摘自 docs/harnesses.md）：

python3 tests/core_fixture.py python3 tests/pi_http.py python3 tests/cursor_http.py python3 tests/pi_e2e.py python3 tests/core_e2e.py --fixture

⚠️注意：本地测试全部通过只说明功能正常，不代表部署就绪——Linux cgroup 磁盘保护和真实 PostgreSQL 上传有各自独立的验证路径，见 tests/storage_e2e.py 的文档说明。

🤝 参与贡献：三步验证 + Apache 2.0

提交改动前，AGENTS.md 要求依次通过三道关卡：

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

参与建议：

1. 大改动先开 Issue 讨论，再提交 Pull Request（见 README.md）
2. 保持约定：一个 Rust 包、一个服务；凭证与内部笔记只放在被忽略的文件里
3. 安全相关设计可参考 adr/0001-accept-privileged-core-service.md，了解「有特权的 core 服务 + 无特权的 agent 用户」这一核心权衡
4. 项目为 pre-release 状态，以Apache 2.0许可发布，见 LICENSE

更多深入阅读：docs/api.md（全部端点与错误码）、docs/session-lifecycle.md（会话恢复语义）、docs/observability.md（诊断）、docs/storage.md（磁盘策略）。

🚀 现在你已经掌握了 cloudroom-core 的构建与测试全流程，可以开始探索源码、修复问题并提交你的第一个 PR 了。