# 三阶段计划：按模型上下文配置 feature

对应 issue #1171 / #931。从原型验证到全栈 PR，分三阶段递进。

## 阶段一：原型验证

**目标**：验证「CodexPlusPlus 生成 catalog + codex 客户端 实读 1M」端到端可行，拿到可用产物格式。

### 任务
1. **A 预检（手工对拍）**
   - 手抄 cc-switch 格式 catalog：`deepseek-v4-pro` → `context_window:1000000` / `max_context_window:1000000`
   - config.toml 写 `model_catalog_json` 指针 + `model = deepseek-v4-pro`
   - 直接起 codex 客户端（PureApi，不经 relay 代理），确认报 ~1M
   - 记录 Mac 路径格式（相对/绝对、是否需转义）、effective_percent 行为

2. **B 最小生成函数**
   - 新增 `generate_profile_model_catalog(home, profile)`：解析 `model_list` 后缀 → 生成 catalog JSON → 写 `<home>/model-catalogs/<id>.json`
   - 抄 cc-switch template clone 思路，字段齐全
   - config.toml 注入 `model_catalog_json` 相对路径指针
   - 插入 apply 流程（`apply_context_limits_to_config` 之后），opt-in，无后缀 no-op
   - catalog 含 profile 全部模型（解 #1064 单模型副作用）

3. **实跑对拍**
   - 实跑原型产物，起 codex 客户端 确认报 1M，与 A 样本对比
   - 验证必验项（见 spec 第五节）：Mac 路径、字段名、auto_compact null、effective_percent、单模型副作用

4. **测试**
   - 新增 `relay_config.rs` 用例：有后缀生成、无后缀 no-op、手写指针不覆盖、相对路径、含全部模型

### 验证标准
- codex 客户端 读原型 catalog 报 ~1M（非 258K）
- `cargo test` 全过，旧测试不受影响
- catalog 产物格式与 cc-switch 对拍一致

### 产出
- 可用 catalog 生成函数 + 测试
- 验证报告（字段、路径、副作用结论）

---

## 阶段二：后端完整化

**目标**：补齐解析回传与压缩配置，后端能力完整。

### 任务
1. **解析回传 context_window**
   - 改 `parse_model_catalog_json_models`（`model_catalog.rs:678`）：读 catalog 时保留 `context_window` 一并返回
   - 前端 `/model` 列表与模型展示拿到真实窗口（诉求 3）

2. **auto_compact 按比例/按模型**
   - catalog 条目支持 `auto_compact_token_limit`（按模型）
   - 设置层支持「压缩比例」（如 85%），应用时按 `context_window × 比例` 计算写入
   - 顶层 `model_auto_compact_token_limit` 保留作回退

3. **effective_context_window_percent**
   - 按阶段一验证结论决定写 100 / 省略 / 可配

4. **测试完善**
   - 解析回传字段测试
   - 按比例压缩计算测试
   - 边界：空 model_list、仅无后缀、混合后缀

### 验证标准
- 前端能拿到每模型真实 context_window
- 压缩阈值按模型/按比例生效
- `cargo test` 全过

---

## 阶段三：前端全栈 + PR

**目标**：前端结构化展示，全测试，提 PR 合并主仓。

### 任务
1. **前端结构化展示**
   - `model_list` textarea 后缀解析：高亮/校验 `[1M]` 语法
   - 模型列表按模型显示真实窗口（读 catalog 回传）
   - 仿 cc-switch modelCatalog 表格（可选，按需）

2. **auto_compact UI**
   - 设置页「压缩比例」/「绝对长度」选项
   - 按模型精细化（若需要）

3. **兼容性与回归**
   - 旧 profile 序列化回落
   - Windows 路径转义（#931 坑）按平台处理
   - 全量 `cargo test` + 前端构建

4. **提 PR**
   - feature 分支 `codex/per-model-context`
   - PR 描述引用 #1171 / #931，说明方案与验证
   - 对齐主仓 commit/测试规范

### 验证标准
- 前端按模型显示真实窗口，切换即生效
- 全测试通过，旧行为兼容
- PR 可合并主仓

---

## 里程碑

| 阶段 | 产出 | 风险点 |
| --- | --- | --- |
| 一 | 原型验证 + 生成函数 | codex 字段/路径兼容（实跑确认） |
| 二 | 解析回传 + 压缩配置 | 字段回传前端链路 |
| 三 | 前端全栈 + PR | Windows 兼容、合并规范 |
