Optio 开发者指南:五层测试体系与 Monorepo 开发环境完整上手教程

原创2026-10-15 17:00:591,663 阅读

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 运行时的协议适配 —

Optio 控制台总览界面:工作队列、用量限额、本地会话与持久智能体一览

理解这个布局的好处是:当你改动某个包时,能立刻知道该跑哪一层测试。

🛠 开发环境搭建:三步跑起全套

前置依赖安装清单

按 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

Optio 创建工作表单:触发器选择、Pod 或本机执行、仓库与连接配置

下面逐层拆解每层的机制与文件位置。

第一层:单元测试——全 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 端会话与终端并排展示,Agent 对话实时可查

第四层: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 把质量门禁自动化:

  1. 提交前:lint-staged 对暂存的 .ts/.tsx 跑 ESLint + Prettier,随后全局执行 pnpm format:check 和 pnpm turbo typecheck(见 package.json 的 lint-staged 字段);
  2. 提交信息:强制 Conventional Commits(feat: / fix: / refactor: 等),由 commitlint 校验;
  3. 数据库改动:修改 apps/api/src/db/schema.ts 后手写新迁移 SQL(Unix 时间戳前缀),用 bash scripts/check-migration-prefixes.sh 检查前缀重复;
  4. 移动端模型生成:iOS / Android 的类型文件由 pnpm gen:swift / pnpm gen:kotlin 从 packages/shared 生成,禁止手改,CI 会校验同步。

🖼 产品全貌:测试守护的是什么

创建 Work 表单完整视图:触发器、执行位置、仓库、连接与技能配置

五层测试守护的对象,就是这套覆盖 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 的全部能力。

登录后查看全文
optio