Optio 开发者指南:五层测试体系与 Monorepo 开发环境完整上手教程
Optio 开发者指南:五层测试体系与 Monorepo 开发环境完整上手教程
Optio 是一个自托管的 AI Agent 编排平台,让 Claude Code、Codex、Copilot 等编码智能体像 CI/CD 流水线一样在你的 Kubernetes 集群上运行。本文面向首次参与开发的贡献者,带你快速搭好 Monorepo 开发环境,并掌握它引以为傲的五层测试体系——从毫秒级的单元测试到真实 LLM 运行的冒烟测试,层层递进、互不干扰。
📦 Monorepo 结构一览:先看懂代码怎么组织
Optio 采用 Turborepo + pnpm 10 管理的 Monorepo,所有子包通过 pnpm-workspace.yaml 声明,分为 apps/*(应用)和 packages/*(共享库)两大区:
| 目录 | 职责 | 技术栈 |
|---|---|---|
apps/api |
Fastify API 服务器 + 14 个 BullMQ 后台 worker | Fastify 5、Drizzle ORM、Redis |
apps/web |
Next.js 15 Web UI | Tailwind CSS v4、Zustand、Playwright |
apps/ios |
原生 iOS 客户端 | SwiftUI |
apps/android |
原生 Android 客户端 | Kotlin + Jetpack Compose |
apps/cli |
optio 命令行工具(含 Optio Local 守护进程) |
TypeScript |
packages/shared |
类型定义、状态机、工作规范等共享代码 | 被所有应用依赖 |
packages/container-runtime |
容器运行时抽象(K8s / Docker / fake) | 测试的关键拼图 |
packages/agent-adapters |
六种 Agent 运行时的协议适配 | — |
理解这个布局的好处是:当你改动某个包时,能立刻知道该跑哪一层测试。
🛠 开发环境搭建:三步跑起全套
前置依赖安装清单
按 CONTRIBUTING.md 的要求,你需要准备:
- Node.js 22+
- pnpm 10+(
npm install -g pnpm) - Docker Desktop 并启用 Kubernetes
一键部署本地集群
git clone https://gitcode.com/gh_mirrors/opt/optio
cd optio
pnpm install
./scripts/setup-local.sh
setup-local.sh 会构建全部镜像并通过 Helm 部署到本地 K8s 集群(配置文件见 helm/optio/values.local.yaml)。完成后打开 http://localhost:30310 即可完成首次设置,API 监听在 http://localhost:30400。
之后日常开发只需热重载模式:
pnpm dev # 启动 API + Web 双服务
pnpm turbo typecheck # 对全部 6 个包做类型检查
pnpm turbo test # 跑所有单元测试(Vitest,全 mock、无基础设施)
🧪 五层测试体系:Optio 的质量护城河
这是理解 Optio 工程文化的核心。官方规则写得很直白:"一个改动,在覆盖它的测试层全部通过之前,就不算完成。" 前四层是确定性的——无集群、无 LLM 调用、零成本,全部跑在 CI 里;第五层只在本地执行。
| 层级 | 命令 | 覆盖内容 | 何时运行 |
|---|---|---|---|
| 1. 单元测试 | pnpm turbo test |
纯逻辑、mock 掉服务的 API 路由 | 任何改动(必跑) |
| 2. 集成测试 | pnpm --filter @optio/api test:integration |
服务层 + 真实 Postgres + Redis:状态机、协调器 CAS、触发器、密钥加密 | 改了 DB schema / 服务 / worker |
| 3. 流水线 e2e | pnpm --filter @optio/api test:e2e |
真实 API 服务器(全部 14 个 worker)经 HTTP 驱动,容器运行时换成 fake | 改了 worker / 路由 / 启动流程 |
| 4. Web e2e | pnpm --filter @optio/web test:e2e |
Playwright 驱动浏览器,遍历所有顶层页面 | 改了 Web UI |
| 5. Live 冒烟 | bash scripts/smoke-e2e.sh |
真实 K8s Pod + 真实 Agent 认证 + 一次真实 LLM 运行(约 $0.01) | 改了 Pod 生命周期 / 镜像 / Helm;仅本地,绝不进 CI |
下面逐层拆解每层的机制与文件位置。
第一层:单元测试——全 mock、毫秒级反馈
单元测试文件命名为 *.test.ts,散布在 packages/shared 和 apps/api/src 各处。Vitest 配置见 apps/api/vitest.config.ts,注意它显式排除了 *.int.test.ts 和 e2e/**,防止有人在单测层意外拉起真实基础设施。CI 环境下会自动开启 v8 覆盖率并强制执行阈值(行 50%、分支 65%)。
pnpm turbo test
第二层:集成测试——真实数据库,隔离到文件粒度
集成测试命名 *.int.test.ts,独立配置在 apps/api/vitest.integration.config.ts。它的精妙之处在于隔离模型:
- 通过 scripts/test-infra.sh 自动拉起一次性容器:
optio-test-postgres(端口 54329)和optio-test-redis(端口 63790),外加一个三节点 Redis Cluster 供集群模式测试使用; - 每个测试文件都获得一个从已迁移模板克隆的私有数据库 + 一个租用的 Redis 逻辑库——因此并发运行互不干扰,
globalSetup还会清扫崩溃残留; pool: "forks"让每个文件跑在独立进程中,模块级单例(数据库池、Redis 连接)天然绑定到该文件自己的私有库。
典型范例是 apps/api/src/db/harness.int.test.ts,行工厂在 apps/api/src/test-utils/integration/fixtures.ts。
第三层:流水线 e2e——真实服务器 + 假 Pod
这一层是性价比最高的设计。e2e/*.e2e.test.ts 会完整启动真实 API 服务器(vitest.e2e.config.ts 将 maxWorkers 限制为 2,避免 4 核 CI 跑机资源饥饿),覆盖 HTTP API → BullMQ → worker → 日志流 → 协调器 → 终态的整条流水线,但容器运行时被替换为 fake 实现(packages/container-runtime/src/fake.ts)。
Fake runtime 通过"提示词指令"扮演智能体,你可以在测试提示词里写入:
[[mock:pr]]—— 输出 PR URL,推进到pr_opened[[mock:fail]]/[[mock:silent]]/[[mock:hang]]/[[mock:sleep:MS]][[mock:cost:X]]—— 模拟费用
这让任务/Job/持久智能体的完整生命周期测试既免费又确定。29 个 e2e 用例覆盖启动迁移、WebSocket 日志流、RBAC、预算等,入口在 apps/api/e2e/。
第四层:Web e2e——Playwright 驱动真实 UI
pnpm --filter @optio/web test:e2e 会调用 apps/web/e2e/launch-stack.ts:它先拉起测试 Postgres/Redis 容器、克隆私有数据库,再以 hermetic 模式启动真实 API(API 4931 端口、Web 3131 端口,避开开发默认端口),同时 next dev 代理到它,并预置好仓库、任务、Job 运行等数据,让每个页面都有非空状态可断言。27 个 Playwright 用例覆盖终端渲染、工作表单、侧边栏等全部顶层页面。首次运行记得:
cd apps/web && npx playwright install chromium
第五层:Live 冒烟——真实集群 + 真实 LLM
bash scripts/smoke-e2e.sh 对已部署的栈做最终验证(scripts/smoke-e2e.sh):API 健康检查 → Web 页面可达 → 创建一个一行提示词的真实 Job → 走完 K8s Pod 流水线 → 等待完成并删除。真实 LLM 运行只花大约一美分,可用 --no-llm 跳过。改了 Pod 生命周期、镜像或 Helm 配置后,这是提交前的最后关。
🔁 开发工作流约定:提交之前必过四关
项目用 Husky + lint-staged + commitlint 把质量门禁自动化:
- 提交前:
lint-staged对暂存的.ts/.tsx跑 ESLint + Prettier,随后全局执行pnpm format:check和pnpm turbo typecheck(见 package.json 的lint-staged字段); - 提交信息:强制 Conventional Commits(
feat:/fix:/refactor:等),由 commitlint 校验; - 数据库改动:修改 apps/api/src/db/schema.ts 后手写新迁移 SQL(Unix 时间戳前缀),用
bash scripts/check-migration-prefixes.sh检查前缀重复; - 移动端模型生成:iOS / Android 的类型文件由
pnpm gen:swift/pnpm gen:kotlin从packages/shared生成,禁止手改,CI 会校验同步。
🖼 产品全貌:测试守护的是什么
五层测试守护的对象,就是这套覆盖 Web、iOS、Android 的完整工作台:任务生命周期、触发器派发、日志实时流、持久智能体、本地终端……测试体系与功能矩阵一一对应,这正是"改动什么就跑哪层"能够成立的原因。
✅ 上手检查清单
- [ ]
pnpm install完成,./scripts/setup-local.sh部署成功 - [ ]
pnpm turbo test全部通过(第一层) - [ ]
pnpm --filter @optio/api test:integration通过(第二层,Docker 需在运行) - [ ]
pnpm --filter @optio/api test:e2e通过(第三层) - [ ] 改 UI 时
pnpm --filter @optio/web test:e2e通过(第四层) - [ ] 后端改动后重建镜像、重部署本地集群并跑
bash scripts/smoke-e2e.sh(第五层)
按这个清单走一遍,你就已经具备了向 Optio 提交高质量 PR 的全部能力。



