# 聚合 API 供应商轮转实施计划

> 生成时间：2026-05-27 16:07:51
> 工作区：`/Users/albertluo/workSpace/albertLuo/createSomethingNew/CodexPlusPlus`
> 角色：Agent-4（验证与交付）
> 范围：API 供应商新增“自动聚合 API 轮转”对话；支持四种策略；成员从已有供应商勾选。
> 约束：本文档仅准备验证清单与交付计划，不修改业务代码。

## 1. 子 Agent 开工模板

- 目标：为聚合 API 供应商轮转功能准备验证清单和文档落盘。
- 输入：API 供应商新增自动聚合 API 轮转对话，四种策略，成员从已有供应商勾选。
- 输出：`docs/plan/20260527160751519_聚合API供应商轮转实施计划.md`。
- 验收标准：文档落盘；列出建议执行的最小验证命令。
- 负责文件：仅新增 `docs/plan/20260527160751519_聚合API供应商轮转实施计划.md`。
- 预计耗时：5-10 分钟。
- 心跳频率：60 秒。

## 2. 功能验收范围

### 2.1 产品行为

- 在“供应商配置”页提供“自动聚合 API 轮转”创建入口。
- 对话内可以从已有供应商列表勾选成员，不允许输入游离于现有列表之外的成员。
- 至少勾选 2 个成员后才允许保存聚合供应商。
- 支持四种轮转策略，并在保存后可被配置持久化、重新加载和编辑。
- 聚合供应商应能出现在供应商列表中，并能被正常切换为当前供应商。
- 删除或修改成员供应商时，聚合供应商需要给出明确状态：成员缺失、成员不可用或需要重新选择。

### 2.2 四种策略建议

实现按用户确认的四种策略验收：

1. 失败切换：优先使用第一个成员，失败、限流或上游错误后切到下一个成员。
2. 按对话轮转：每个新对话分配一个成员，同一对话保持固定成员。
3. 按请求轮转：每次请求按成员顺序切换，适合能力接近的供应商池。
4. 权重轮转：按成员权重分配请求，权重越高承担越多请求。

字段名固定为 `failover`、`conversationRoundRobin`、`requestRoundRobin`、`weightedRoundRobin`，需要在 UI、持久化配置和调用路径上保持一致。

## 3. 建议任务拆分

### Task 1：数据模型与持久化检查

负责人：Agent-2 / Agent-BE-Rust
负责目录：

- `crates/codex-plus-core/src`
- `apps/codex-plus-manager/src-tauri/src`

验收标准：

- 聚合供应商字段不会破坏已有单供应商配置反序列化。
- 老配置缺少聚合字段时仍能正常加载。
- 保存后重新打开应用，聚合供应商成员、策略、排序、权重仍保留。

### Task 2：前端对话与成员勾选

负责人：Agent-3 / Agent-FE-React
负责文件：

- `apps/codex-plus-manager/src/App.tsx`
- `apps/codex-plus-manager/src/styles.css`

验收标准：

- 创建入口可见，文案明确。
- 对话只展示已有供应商作为候选成员。
- 当前正在编辑的聚合供应商不能勾选自身。
- 不足 2 个成员、没有策略、成员重复时保存按钮不可用或保存失败提示明确。
- 移动端和桌面宽度下文本不溢出、按钮不遮挡。

### Task 3：轮转选择逻辑

负责人：Agent-2 / Agent-BE-Rust
负责目录：

- `crates/codex-plus-core/src`

验收标准：

- 失败切换、按对话轮转、按请求轮转、权重轮转四种策略均有确定性单元测试。
- 单个成员不可用时，不影响其他可用成员继续工作。
- 所有成员不可用时返回明确错误，不静默回落到错误供应商。
- 不泄露成员供应商 API Key 到日志、错误提示或前端通知。

### Task 4：端到端冒烟

负责人：Agent-4
负责范围：

- 前端类型检查
- Rust 单元/集成测试
- Tauri 构建前检查
- 手工 UI 冒烟清单

验收标准：

- 最小验证命令通过，或明确记录失败原因与阻塞点。
- 手工路径覆盖：创建聚合供应商、选择四种策略、保存、重载、切换、删除成员供应商后的提示。

## 4. 只读检查到的可用命令

### 4.1 前端管理端

`apps/codex-plus-manager/package.json` 暴露命令：

```bash
cd apps/codex-plus-manager && npm run check
cd apps/codex-plus-manager && npm run vite:build
cd apps/codex-plus-manager && npm run build
cd apps/codex-plus-manager && npm run dev
```

说明：

- `npm run check`：TypeScript 静态检查，适合作为最小前端验证。
- `npm run vite:build`：前端产物构建，适合 UI 改动后的构建验证。
- `npm run build`：包含 `cargo build -p codex-plus-launcher --release && tauri build`，成本较高，建议放在合并前或发版前。
- `npm run dev`：本地 Tauri 开发调试。

### 4.2 Rust workspace

根目录存在 `Cargo.toml` workspace，成员包括：

- `crates/codex-plus-core`
- `crates/codex-plus-data`
- `apps/codex-plus-launcher`
- `apps/codex-plus-manager/src-tauri`

建议命令：

```bash
cargo test -p codex-plus-core
cargo test -p codex-plus-data
cargo test -p codex-plus-manager
cargo test --workspace
cargo build --workspace
```

说明：

- `cargo test -p codex-plus-core`：优先覆盖供应商配置、协议代理、轮转逻辑。
- `cargo test -p codex-plus-manager`：优先覆盖 Tauri command 层与配置读写桥接。
- `cargo test --workspace`：全量 Rust 回归，耗时更高。
- `cargo build --workspace`：合并前构建兜底。

## 5. 最小验证命令

优先建议实现 Agent 完成后执行以下最小集合：

```bash
cd /Users/albertluo/workSpace/albertLuo/createSomethingNew/CodexPlusPlus
cargo test -p codex-plus-core
cargo test -p codex-plus-manager
cd apps/codex-plus-manager && npm run check
```

若涉及样式、布局或对话交互，追加：

```bash
cd /Users/albertluo/workSpace/albertLuo/createSomethingNew/CodexPlusPlus/apps/codex-plus-manager
npm run vite:build
```

若准备合并或发版，追加：

```bash
cd /Users/albertluo/workSpace/albertLuo/createSomethingNew/CodexPlusPlus
cargo test --workspace
cargo build --workspace
cd apps/codex-plus-manager && npm run build
```

## 6. 手工冒烟清单

- 打开供应商配置页，确认“自动聚合 API 轮转”入口存在。
- 已有 0 个或 1 个普通供应商时，创建聚合供应商应提示成员不足。
- 已有 2 个以上普通供应商时，勾选成员后可保存。
- 分别选择四种策略保存，重新打开详情后策略保持不变。
- 调整成员顺序后保存，按请求轮转策略按新顺序展示或生效。
- 权重轮转策略下，权重为空、0、非数字、极大值都有明确校验。
- 删除一个被聚合引用的普通供应商后，聚合供应商展示成员缺失或不可用状态。
- 切换到聚合供应商后，配置预览不应显示错误成员的 API Key。
- 失败提示不包含完整 API Key，只允许展示脱敏前缀或供应商名称。

## 7. 风险与回滚

### 7.1 主要风险

- 配置兼容风险：新增聚合字段可能影响旧版本配置加载。
- 调用路径风险：聚合供应商如果被当作普通供应商写入 `config.toml`，可能导致 base URL 或 API Key 为空。
- 状态一致性风险：成员供应商删除、重命名、拖动排序后，聚合引用可能失效。
- 安全风险：轮转失败日志可能打印成员 API Key。
- UI 风险：供应商列表和对话都集中在 `App.tsx`，改动容易影响现有供应商新增、编辑、切换流程。

### 7.2 回滚方案

- 前端入口回滚：隐藏或移除“自动聚合 API 轮转”入口，保留已有普通供应商流程。
- 数据兼容回滚：读取配置时忽略聚合供应商字段，不删除用户已有普通供应商。
- 调用路径回滚：切换供应商时若检测到聚合类型不可用，阻止写入 `config.toml` 并提示用户选择普通供应商。
- 测试回滚：保留新增单元测试中对旧配置兼容的用例，避免回滚后引入老配置不可读问题。

## 8. 交付模板

- 结果摘要：已完成聚合 API 供应商轮转功能验证计划落盘；未改业务代码。
- 改动点：新增 `docs/plan/20260527160751519_聚合API供应商轮转实施计划.md`。
- 验证：只读检查 `apps/codex-plus-manager/package.json` 与 workspace `Cargo.toml`，整理出最小验证命令。
- 风险与回滚：见本文档第 7 节。
- 请求关闭：Agent-4 文档与验证清单任务已完成，请 Agent-0 回收关闭。
