Files
codex-proxy-rs/docs/development.md
T
ZyyandCodex f4058c1d2e test: align backend coverage with current behavior
Remove obsolete field assertions and the ignored Codex binary TLS comparison. Keep coverage for request validation, compatibility, and local TLS handshakes.

Co-authored-by: Codex <noreply@openai.com>
2026-11-19 15:56:12 +08:00

152 lines
7.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 开发与源码联调
除克隆仓库外,命令均在宿主仓库根目录执行。协作与验收见 [贡献与审查](../CONTRIBUTING.md),部署配置与数据维护见 [部署与运维](../deploy/README.md)
| 任务 | 入口 |
| --- | --- |
| 修改宿主前后端 | [环境与依赖](#环境与依赖) → [启动宿主](#启动宿主) |
| 定位模块与共享实现 | [源码入口](#源码入口) |
| 同时修改 UI 或插件 | [源码联调](#源码联调) → [启动与检查](#启动与检查) |
| 验证本地 SDK | [本地 SDK 验证](#本地-sdk-验证) |
| 提交跨仓库改动 | [编辑与提交](#编辑与提交) |
## 环境与依赖
使用 Node.js 26.13.1、PostgreSQL、Redis 和各前端 `packageManager` 指定的 pnpm。宿主 CI 与 Docker 读取 `frontend/package.json`。
在仓库根目录运行 Cargo 时,用 `+版本号` 选择 `backend/rust-toolchain.toml` 指定的[工具链](architecture.md#验证命令)
```bash
git clone https://github.com/zyycn/codex-proxy-rs.git
cd codex-proxy-rs
pnpm --dir frontend install --frozen-lockfile
```
宿主前端的依赖、锁文件与 ESLint 配置位于 `frontend/`
- **版本固定**:`@codex-proxy/ui` 使用固定 GitHub 标签或提交,锁文件记录实际提交、源码归档地址及完整性摘要
- **安装与构建**:pnpm 按 UI 自身锁文件准备依赖,执行 `prepack` 生成 JS、CSS 和类型声明,普通 `dev`、`build`、发行 CI 和 Docker 使用编译产物,无需初始化子模块
- **构建许可**:`frontend/pnpm-workspace.yaml` 的 `allowBuilds` 按仓库放行自有 UI 包脚本。升级时核对源码并更新锁文件
## 启动宿主
使用源码仓库自带的 Compose 与配置模板,按[手动安装](../deploy/README.md#手动安装)中的配置与权限要求准备 `deploy/config.yaml` 和 `.runtime/` 目录
数据库及 Redis 可由 Compose 启动:
```bash
docker compose -f deploy/compose.yaml up -d postgres redis
cargo +1.99.1 run --manifest-path backend/Cargo.toml -p codex-proxy-rs --locked
```
后端从当前目录向上查找 `deploy/config.yaml`,本机运行时数据库与 Redis 地址应指向可访问的本机端口
`host.runtime_data_dir` 和日志的相对路径以该配置文件所在目录解析
另开终端启动管理端:
```bash
pnpm --dir frontend dev
```
后端代理由 `frontend/vite.config.ts` 配置,验证 WebSocket 时直接连接后端
前后端检查见 [贡献与审查](../CONTRIBUTING.md#验证),数据库集成测试使用[专用测试库](../backend/migrations/README.md#本地测试库)
## 源码入口
[后端 Workspace 边界](architecture.md#3-workspace-边界) · [前端模块职责](architecture.md#34-前端模块职责) · [共享 UI 组件架构](../modules/ui/playground/guide/architecture.md)
Messages 与 Responses 的纯协议转换位于 `backend/crates/gateway-protocol/src/anthropic/`,
HTTP 入口位于 `backend/crates/gateway-api/src/openai/messages.rs`,
账号协议分派、HTTP 执行和计数位于 `backend/crates/providers/openai/src/provider/messages/`。
模块职责见 [Provider 与协议边界](architecture.md#5-provider-与协议边界)
联调协议时分别准备使用 `responses` 和 `messages` 的 API Key 账号,并通过账号分组与 Client Key 固定上游范围,
避免混合账号池使一次请求选中其他协议。对 Responses、Chat 和 Messages 三个入口分别检查 JSON 与 SSE,
再核对工具往返、取消、错误和输入计数;请求格式及六种组合见 [模型数据面](api.md#3-模型数据面与模型目录)。
Messages 账号只配置 HTTP;本地计数估算不能替代上游计费核对
OpenAI 的 `transport::tls::` 测试在本机回环地址采集 ClientHello,覆盖默认 HTTP、自定义 CA 的 HTTP 和 WebSocket。运行方式见[后端验证命令](architecture.md#验证命令)
## 源码联调
宿主、组件库和官方插件保留独立仓库,通过 Git 子模块在同一目录开发:
| 目录 | 仓库与职责 |
| --- | --- |
| `frontend` / `backend` | 宿主管理端与 Rust 网关 |
| `modules/ui` | `codex-proxy-ui`,共用组件与主题 |
| `modules/plugins` | `codex-proxy-plugins`,官方插件示例 |
各仓库的 CI 使用锁定依赖。联调前确认所选提交的公开接口兼容
### 检出与安装
首次检出可同时下载子模块:
```bash
git clone --recurse-submodules https://github.com/zyycn/codex-proxy-rs.git
cd codex-proxy-rs
```
在已有仓库中,先保存子模块改动,再用 `git submodule update --init --recursive` 检出宿主指定的提交。拉取宿主更新后也用此命令对齐
在宿主根目录安装各项目依赖:
```bash
pnpm --dir modules/ui install --frozen-lockfile
pnpm --dir frontend install --frozen-lockfile
pnpm --dir modules/plugins/examples/workbench/frontend install --frozen-lockfile
```
### 启动与检查
在各自终端启动所需服务:
```bash
pnpm --dir frontend dev:source # 管理端,引用本地 UI
pnpm --dir modules/plugins/examples/workbench/frontend dev:source # 插件页面,引用本地 UI
pnpm --dir modules/ui dev # 组件库交互示例
```
管理端需要[已启动的网关](#启动宿主)。插件独立预览的宿主桥使用模拟数据;已安装插件读取包内静态资源,修改后需重新构建、打包和安装
`dev:source` 使用 Vite 的 `source` 模式,由 `@codex-proxy/ui/vite` 的 `CodexProxyUI` 适配器将公开入口解析到 `modules/ui`,并统一处理共享依赖、源码预构建排除与开发服务的文件访问范围。入口映射以 UI 包 `exports` 中的 `codex-proxy-source` 条件为准,由 Vite 热更新。插件单独检出时仍用普通 `dev`;`source` 模式需要上述子模块目录结构
```bash
pnpm --dir frontend build:source
pnpm --dir modules/plugins/examples/workbench/frontend build:source
```
`build:source` 用各项目的 `tsconfig.source.json` 检查源码类型,管理端构建到 `frontend/node_modules/.vite/source-dist`,示例构建到其前端项目的 `.vite/source-dist`,不改写正式依赖、锁文件或 `dist`。
### 本地 SDK 验证
插件正式 SDK 依赖仍由其 Cargo 锁文件固定。需要验证尚未发布的 SDK 修改时,在临时副本运行 Cargo patch,避免改写插件锁文件。以下命令从宿主根目录执行:
```bash
(
set -e
cpr_sdk_check_dir=$(mktemp -d)
trap 'rm -rf "$cpr_sdk_check_dir"' EXIT
mkdir "$cpr_sdk_check_dir/backend"
cp modules/plugins/examples/workbench/backend/Cargo.{toml,lock} "$cpr_sdk_check_dir/backend/"
cp -R modules/plugins/examples/workbench/backend/{src,tests} "$cpr_sdk_check_dir/backend/"
cp modules/plugins/examples/workbench/plugin.json "$cpr_sdk_check_dir/"
RUST_MIN_STACK=16777216 CARGO_TARGET_DIR="$PWD/backend/target/plugin-development" \
cargo +1.99.1 test --manifest-path "$cpr_sdk_check_dir/backend/Cargo.toml" \
--config "patch.\"https://github.com/zyycn/codex-proxy-rs.git\".gateway-plugin-sdk.path=\"$PWD/backend/crates/gateway-plugin/sdk\""
)
```
独立插件的构建、打包和安装后功能验证见 [Workbench 示例](../modules/plugins/examples/workbench/README.md)。
宿主插件集成测试的数据库与 Redis 配置见[本地测试库](../backend/migrations/README.md#本地测试库)
## 编辑与提交
1. 在要修改的子模块内先创建分支,例如 `git -C modules/ui switch -c feat/select`。初次初始化的子模块通常处于 detached HEAD
2. 在子模块运行自身检查,并在宿主根目录运行所需联调检查
3. 在对应仓库提交、推送并合并组件库或插件 PR
4. 需要升级依赖时,在管理端或插件仓库固定 UI 标签或提交并更新锁文件。插件 SDK 固定到提供所需合同的宿主提交
5. 在宿主仓库提交代码和子模块指针。指针须可从远程检出,更新指针不会升级消费方依赖