codex-lb开发者指南本地开发环境搭建、测试体系与OpenSpec驱动开发流程【免费下载链接】codex-lbCodex/ChatGPT multiple account load balancer proxy with usage tracking, dashboard, and OpenCode-compatible endpoints项目地址: https://gitcode.com/gh_mirrors/co/codex-lbcodex-lb是一个面向 Codex/ChatGPT 多账号的负载均衡器与代理load balancer proxy内置用量追踪、Web 仪表盘和 OpenCode 兼容端点。如果你打算参与贡献这篇开发者指南将带你在 5 分钟内搭好本地开发环境讲清楚它的四层测试体系并拆解 OpenSpec 驱动开发spec-driven development的完整流程——从提案到归档一份都不会漏。一、codex-lb 是什么先认识你要开发的项目一句话概括多个 Codex/ChatGPT 账号 一个代理入口 一套用量仪表盘。客户端把请求发给 codex-lb它根据账号配额、健康度和粘性会话策略把请求路由到最合适的账号并记录每次请求的用量与延迟。启动后访问localhost:2455即可进入仪表盘添加账号即开始工作项目的技术栈部分技术位置后端Python 3.13 / FastAPI用uv管理app/仪表盘前端React TypeScript用bun管理frontend/原生出站模块Rustegress worker 等 4 个 cratecrates/数据库SQLite默认/ PostgreSQLAlembic 迁移app/db/快速上手文档见 docs/getting-started.md。二、本地开发环境搭建uv 五条命令搞定codex-lb 是 Python 项目完全由uv机器可读的约定汇总在 AGENTS.md。最快环境搭建步骤# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/co/codex-lb cd codex-lb # 2. 一键安装 Python 3.13 全部依赖含开发依赖 uv sync --all-extras --dev # 3. 激活虚拟环境可选uv run 本身就不需要激活 source .venv/bin/activate # 4. 安装 pre-commit 钩子本地 CI 的守门员 uv run pre-commit install # 5. 验证代理可运行 uv run codex-lb --help几个要点Python 版本requires-python 3.13声明在 pyproject.toml 中uv 会自动处理。前端依赖进入 frontend/ 后执行bun install --frozen-lockfile与 CI 保持一致。类型系统除ruff之外项目还用了 Astral 的ty类型检查器make typecheck即可运行。本地跑起来并登录仪表盘# 启动代理零配置所有设置都有默认值 uv run codex-lb首次远程访问仪表盘需要 bootstrap token 设置初始密码本地访问localhost则直接免登录。登录页长这样三、理解目录结构代码都住在哪里. ├── app/ # Python 应用代理、账号、仪表盘后端 │ ├── modules/proxy/ # 代理与负载均衡核心 │ ├── core/ # 基础设施认证、限流、弹性、追踪 │ └── db/ # 数据模型 267 个 Alembic 迁移 ├── frontend/ # 仪表盘 SPAReact TS ├── crates/ # Rust 出站 worker 等 4 个 crate ├── tests/ # 分层测试体系见下节 ├── openspec/ # SSOT规格、变更提案、归档 ├── deploy/helm/codex-lb/ # Helm ChartK8s 部署 └── scripts/ # 架构守卫、发布工具等后端核心逻辑在 app/modules/proxy/94 个文件是整个项目的重心基础设施层在 app/core/。四、测试体系四层 pytest 切片 本地 CI测试目录 tests/ 按金字塔分层全部由 Makefile 中的目标统一调度层级目录特点Make 目标单元测试tests/unit/快速、隔离hermetic200 个测试文件make test-unit集成测试tests/integration/启动完整应用、打本地 socketmake test-integration-core端到端tests/e2e/完整 API 流程认证、代理流、OpenAI SDK 兼容make test-e2e模拟测试tests/simulation/虚拟时钟 属性测试Hypothesis并入test-unit负载测试tests/load/Node.js 编写的 spike/soak/stress手动运行常用测试命令速查# 跑单个测试文件开发时最常用 uv run pytest tests/unit/test_load_balancer.py -q # 四个 pytest 切片 make test-unit # 单元 模拟 make test-integration-core # 集成核心CI 中还会切 3 个分片并行 make test-e2e # 端到端 make test-postgres # 需要本地 PostgreSQL 的 60 个指定用例 # 迁移图健康检查SQLite / Postgres make migration-check make migration-check-postgres两个关键机制值得了解PostgreSQL 目标是点名制不是所有集成测试都需要 Postgres而是 Makefile 中POSTGRES_PYTEST_TARGETS显式列出的 60 条用例迁移契约、查询计划、并发升级等本地没有 Postgres 也不影响其余测试。架构守卫fitness ratchetsmake lint除了ruff checkruff format --check还会运行 5 个架构检查脚本如 scripts/check_migration_topology.py防止 Alembic 迁移图分叉、scripts/check_proxy_architecture.py 和 scripts/check_settings_tiers.py。它们把不许越界变成了可执行规则。本地 CI一条命令复刻云端门禁# 快速门禁lint/类型/Rust/前端/单元/打包 make ci-fast # 完整本地 CI含集成、e2e、Postgres、Helm、Docker 镜像扫描 make ci # 或用 pre-commit 钩子等价于 make ci uv run pre-commit run local-ci --hook-stage manual --all-filesRust 侧另有独立链路make rust-checkfmt clippy 测试 release 构建和make rust-auditcargo-deny 依赖审计。五、OpenSpec 驱动开发先提案后写码这是 codex-lb 最核心的工程文化OpenSpec 是变更驱动开发的唯一事实来源SSOT。任何改变可观察行为、API 契约或数据库 schema 的 PR都必须先有 OpenSpec 变更。目录结构与角色分工openspec/ ├── config.yaml # 工作流配置与文档规则 ├── specs/capability/ │ ├── spec.md # 规范性需求MUST/SHALL只写可测试的需求 │ └── context.md # 自由格式目的、权衡、运维备注 ├── changes/change/ # 进行中的变更提案 │ ├── proposal.md # Why What Changes │ ├── tasks.md # 可勾选的实现清单 │ └── specs/ # 增量规格delta └── changes/archive/ # 已完成并验证的变更3000 份归档标准开发流程5 步读规格先在openspec/specs/**找到相关 capability例如 openspec/specs/sticky-session-operations/spec.md。建变更如果改动行为先创建openspec/changes/kebab-case/写 proposal tasks。实现逐条完成任务保持spec.md与代码同步。验证openspec validate --specs。归档验证通过后 verify archive未验证的变更不许归档。一个真实案例从提案到落地的完整形态仓库里正在进行中的变更 openspec/changes/weight-selection-by-relative-ttft/ 是很好的范本。它的 proposal.md 用生产数据论证为什么慢账号 cohorts 的首 token p50 高 0.7 秒却拿到全份额度再列出精确到函数级的What Changestasks.md 把实现拆成 4 组可勾选任务测试任务甚至写明了每个场景的断言口径。OpenSpec 的文档规则定义在 openspec/config.yamlspec.md只放需求叙述性内容进context.md用户文档统一放docs/且必须链接回 owning capability——绝不允许 docs/ 变成第二事实来源。仪表盘类变更还要求附前后对比截图例如这个变更留存的证据图六、提交、合并门禁与发布节奏Conventional Commits 是版本号的来源项目使用 Conventional Commits release-please你永远不需要手动改CHANGELOG.md或版本号。PR 标题即提交标题fix(proxy): ...触发 patchfeat(...)触发 minor。合并前必须通过的六道门禁CI 全绿Helm / 迁移 / PostgreSQL 任务也是门禁的一部分不是可选项CodeRabbit 的 P1/P2 发现逐条修复、回应或说明理由mergeable CLEAN无冲突、无未解决的评审意见行为变更必须有openspec/changes/slug/纯重构、纯文档、测试稳定性 PR 豁免Fixes #N/Closes #N关联 issue简单性门禁新特性默认关闭或零配置每个新CODEX_LB_*环境变量必须回答为什么不能是默认值README/.env.example/仪表盘导航条目都有预算上限见 .github/simplicity-budgets.toml。Beta 优先的发布通道稳定版不直接切先发布vX.Y.Z-beta.N在至少一个生产级部署上浸泡 48 小时无回归才合并稳定版 release PR。规范见openspec/specs/release-management/。七、开发者上手清单阅读 .github/CONTRIBUTING.md 与 AGENTS.mdgit cloneuv sync --all-extras --devuv run pre-commit installuv run codex-lb本地跑通打开仪表盘make ci-fast跑绿一遍找一个带good first issue标签的 issue判断是否需要先建 OpenSpec 变更拿不准要不要 OpenSpec开 draft PR 问维护者参与贡献的完整细节代码风格、协作规则、14 天 bus-factor 逃生阀都在 .github/CONTRIBUTING.md 里。现在打开你的终端从make test-unit开始第一次与 codex-lb 握手吧。【免费下载链接】codex-lbCodex/ChatGPT multiple account load balancer proxy with usage tracking, dashboard, and OpenCode-compatible endpoints项目地址: https://gitcode.com/gh_mirrors/co/codex-lb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 codex-lb开发者指南：本地开发环境搭建、测试体系与OpenSpec驱动开发流程
codex-lb开发者指南本地开发环境搭建、测试体系与OpenSpec驱动开发流程【免费下载链接】codex-lbCodex/ChatGPT multiple account load balancer proxy with usage tracking, dashboard, and OpenCode-compatible endpoints项目地址: https://gitcode.com/gh_mirrors/co/codex-lbcodex-lb是一个面向 Codex/ChatGPT 多账号的负载均衡器与代理load balancer proxy内置用量追踪、Web 仪表盘和 OpenCode 兼容端点。如果你打算参与贡献这篇开发者指南将带你在 5 分钟内搭好本地开发环境讲清楚它的四层测试体系并拆解 OpenSpec 驱动开发spec-driven development的完整流程——从提案到归档一份都不会漏。一、codex-lb 是什么先认识你要开发的项目一句话概括多个 Codex/ChatGPT 账号 一个代理入口 一套用量仪表盘。客户端把请求发给 codex-lb它根据账号配额、健康度和粘性会话策略把请求路由到最合适的账号并记录每次请求的用量与延迟。启动后访问localhost:2455即可进入仪表盘添加账号即开始工作项目的技术栈部分技术位置后端Python 3.13 / FastAPI用uv管理app/仪表盘前端React TypeScript用bun管理frontend/原生出站模块Rustegress worker 等 4 个 cratecrates/数据库SQLite默认/ PostgreSQLAlembic 迁移app/db/快速上手文档见 docs/getting-started.md。二、本地开发环境搭建uv 五条命令搞定codex-lb 是 Python 项目完全由uv机器可读的约定汇总在 AGENTS.md。最快环境搭建步骤# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/co/codex-lb cd codex-lb # 2. 一键安装 Python 3.13 全部依赖含开发依赖 uv sync --all-extras --dev # 3. 激活虚拟环境可选uv run 本身就不需要激活 source .venv/bin/activate # 4. 安装 pre-commit 钩子本地 CI 的守门员 uv run pre-commit install # 5. 验证代理可运行 uv run codex-lb --help几个要点Python 版本requires-python 3.13声明在 pyproject.toml 中uv 会自动处理。前端依赖进入 frontend/ 后执行bun install --frozen-lockfile与 CI 保持一致。类型系统除ruff之外项目还用了 Astral 的ty类型检查器make typecheck即可运行。本地跑起来并登录仪表盘# 启动代理零配置所有设置都有默认值 uv run codex-lb首次远程访问仪表盘需要 bootstrap token 设置初始密码本地访问localhost则直接免登录。登录页长这样三、理解目录结构代码都住在哪里. ├── app/ # Python 应用代理、账号、仪表盘后端 │ ├── modules/proxy/ # 代理与负载均衡核心 │ ├── core/ # 基础设施认证、限流、弹性、追踪 │ └── db/ # 数据模型 267 个 Alembic 迁移 ├── frontend/ # 仪表盘 SPAReact TS ├── crates/ # Rust 出站 worker 等 4 个 crate ├── tests/ # 分层测试体系见下节 ├── openspec/ # SSOT规格、变更提案、归档 ├── deploy/helm/codex-lb/ # Helm ChartK8s 部署 └── scripts/ # 架构守卫、发布工具等后端核心逻辑在 app/modules/proxy/94 个文件是整个项目的重心基础设施层在 app/core/。四、测试体系四层 pytest 切片 本地 CI测试目录 tests/ 按金字塔分层全部由 Makefile 中的目标统一调度层级目录特点Make 目标单元测试tests/unit/快速、隔离hermetic200 个测试文件make test-unit集成测试tests/integration/启动完整应用、打本地 socketmake test-integration-core端到端tests/e2e/完整 API 流程认证、代理流、OpenAI SDK 兼容make test-e2e模拟测试tests/simulation/虚拟时钟 属性测试Hypothesis并入test-unit负载测试tests/load/Node.js 编写的 spike/soak/stress手动运行常用测试命令速查# 跑单个测试文件开发时最常用 uv run pytest tests/unit/test_load_balancer.py -q # 四个 pytest 切片 make test-unit # 单元 模拟 make test-integration-core # 集成核心CI 中还会切 3 个分片并行 make test-e2e # 端到端 make test-postgres # 需要本地 PostgreSQL 的 60 个指定用例 # 迁移图健康检查SQLite / Postgres make migration-check make migration-check-postgres两个关键机制值得了解PostgreSQL 目标是点名制不是所有集成测试都需要 Postgres而是 Makefile 中POSTGRES_PYTEST_TARGETS显式列出的 60 条用例迁移契约、查询计划、并发升级等本地没有 Postgres 也不影响其余测试。架构守卫fitness ratchetsmake lint除了ruff checkruff format --check还会运行 5 个架构检查脚本如 scripts/check_migration_topology.py防止 Alembic 迁移图分叉、scripts/check_proxy_architecture.py 和 scripts/check_settings_tiers.py。它们把不许越界变成了可执行规则。本地 CI一条命令复刻云端门禁# 快速门禁lint/类型/Rust/前端/单元/打包 make ci-fast # 完整本地 CI含集成、e2e、Postgres、Helm、Docker 镜像扫描 make ci # 或用 pre-commit 钩子等价于 make ci uv run pre-commit run local-ci --hook-stage manual --all-filesRust 侧另有独立链路make rust-checkfmt clippy 测试 release 构建和make rust-auditcargo-deny 依赖审计。五、OpenSpec 驱动开发先提案后写码这是 codex-lb 最核心的工程文化OpenSpec 是变更驱动开发的唯一事实来源SSOT。任何改变可观察行为、API 契约或数据库 schema 的 PR都必须先有 OpenSpec 变更。目录结构与角色分工openspec/ ├── config.yaml # 工作流配置与文档规则 ├── specs/capability/ │ ├── spec.md # 规范性需求MUST/SHALL只写可测试的需求 │ └── context.md # 自由格式目的、权衡、运维备注 ├── changes/change/ # 进行中的变更提案 │ ├── proposal.md # Why What Changes │ ├── tasks.md # 可勾选的实现清单 │ └── specs/ # 增量规格delta └── changes/archive/ # 已完成并验证的变更3000 份归档标准开发流程5 步读规格先在openspec/specs/**找到相关 capability例如 openspec/specs/sticky-session-operations/spec.md。建变更如果改动行为先创建openspec/changes/kebab-case/写 proposal tasks。实现逐条完成任务保持spec.md与代码同步。验证openspec validate --specs。归档验证通过后 verify archive未验证的变更不许归档。一个真实案例从提案到落地的完整形态仓库里正在进行中的变更 openspec/changes/weight-selection-by-relative-ttft/ 是很好的范本。它的 proposal.md 用生产数据论证为什么慢账号 cohorts 的首 token p50 高 0.7 秒却拿到全份额度再列出精确到函数级的What Changestasks.md 把实现拆成 4 组可勾选任务测试任务甚至写明了每个场景的断言口径。OpenSpec 的文档规则定义在 openspec/config.yamlspec.md只放需求叙述性内容进context.md用户文档统一放docs/且必须链接回 owning capability——绝不允许 docs/ 变成第二事实来源。仪表盘类变更还要求附前后对比截图例如这个变更留存的证据图六、提交、合并门禁与发布节奏Conventional Commits 是版本号的来源项目使用 Conventional Commits release-please你永远不需要手动改CHANGELOG.md或版本号。PR 标题即提交标题fix(proxy): ...触发 patchfeat(...)触发 minor。合并前必须通过的六道门禁CI 全绿Helm / 迁移 / PostgreSQL 任务也是门禁的一部分不是可选项CodeRabbit 的 P1/P2 发现逐条修复、回应或说明理由mergeable CLEAN无冲突、无未解决的评审意见行为变更必须有openspec/changes/slug/纯重构、纯文档、测试稳定性 PR 豁免Fixes #N/Closes #N关联 issue简单性门禁新特性默认关闭或零配置每个新CODEX_LB_*环境变量必须回答为什么不能是默认值README/.env.example/仪表盘导航条目都有预算上限见 .github/simplicity-budgets.toml。Beta 优先的发布通道稳定版不直接切先发布vX.Y.Z-beta.N在至少一个生产级部署上浸泡 48 小时无回归才合并稳定版 release PR。规范见openspec/specs/release-management/。七、开发者上手清单阅读 .github/CONTRIBUTING.md 与 AGENTS.mdgit cloneuv sync --all-extras --devuv run pre-commit installuv run codex-lb本地跑通打开仪表盘make ci-fast跑绿一遍找一个带good first issue标签的 issue判断是否需要先建 OpenSpec 变更拿不准要不要 OpenSpec开 draft PR 问维护者参与贡献的完整细节代码风格、协作规则、14 天 bus-factor 逃生阀都在 .github/CONTRIBUTING.md 里。现在打开你的终端从make test-unit开始第一次与 codex-lb 握手吧。【免费下载链接】codex-lbCodex/ChatGPT multiple account load balancer proxy with usage tracking, dashboard, and OpenCode-compatible endpoints项目地址: https://gitcode.com/gh_mirrors/co/codex-lb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考