Metadata-Version: 2.5
Name: codex-catalog
Version: 1.0.0
Summary: Codex Custom Model Catalog Builder
Requires-Python: >=3.13
Requires-Dist: requests>=2.28.0
Description-Content-Type: text/markdown

# Codex Catalog Builder (`cxc` / `codex-catalog`)

便捷、健壮的 OpenAI Codex 自定义模型目录交互式构建工具（TUI）。

用于一键从第三方代理/反代 API 获取可用模型列表，克隆官方最新旗舰模型模板，交互式配置上下文窗口（Context Window）与排除规则，并安全原子写入 `~/.codex/custom_catalog.json`。

---

## ✨ 核心特性

- 🏛️ **两级内置模型同步（官方模型安全保障）**
  - **一级在线源**：自动从 GitHub 官方源（`openai/codex` 仓库）同步最新官方内置模型定义。
  - **二级本地缓存**：网络受限或离线时，自动读取 `~/.codex/models_cache.json` 兜底补全。
  - 生成目录时完整保留所有官方内置模型原有配置，绝不覆盖或丢失官方模型。

- 🎯 **基准模板智能评估与交互式克隆**
  - 启动时按「公开发布状态 > 主次代际版本 (如 v6.0 > v5.6 > v5.5 > v5.4) > 官方优先级 > 上下文窗口」智能推荐最佳克隆基准。
  - 支持键盘上下键 `[↑/↓]` 交互式选择克隆基准（默认高亮官方首推主力模型，直接回车即可确认）。
  - **模板深度安全清洗**：自动抹除基准模型特有的退役迁移标记（`upgrade`）、新手提示（`availability_nux`）、编译哈希（`comp_hash`）等，确保派生出的自定义模型健康可用。

- 🔄 **代理模型自动获取与去重**
  - 自动解析 `~/.codex/config.toml` 中当前激活的 `model_provider` 配置（读取 `base_url` 与 `experimental_bearer_token`）。
  - 请求代理 `/models` 端点拉取全部可用模型，并自动过滤已在官方内置库中的同名模型（官方定义自动保留）。

- 💡 **配置状态回显与增量维护（幂等性）**
  - 启动时自动读取已有 `~/.codex/custom_catalog.json`。
  - 自动回显之前已配置的自定义 Context（标记 `[x]`）与已排除模型（标记 `[-]`），二次配置或增量更新模型时无需重复设置。

- ⌨️ **全键盘友好 TUI 交互**
  - **编辑模式（光标实时操控）**：
    - `[↑/↓]` 移动光标
    - `[空格]` 切换自定义 Context 标记 `[x]`
    - `[e]` 切换单项排除/恢复标记 `[-]`（排除的模型不会写入文件）
    - `[a]` 全选自定义 / 全选取消
    - `[x]` 全选排除 / 全选恢复
    - `[Enter]` 确认并逐步输入自定义 Context
    - `[ESC]` 放弃当前修改并还原
  - **主菜单模式**：支持按键快速切换编辑模式、范围序号批量选中（如 `1, 3, 5-8` 或 `10~12`）、批量排除、批量恢复及一键应用退出。

- 🔢 **智能 Priority 顺延与上下文同步**
  - 动态计算官方内置模型中的最大 Priority，自定义模型按顺序在其后分配递增 Priority，避免破坏官方内置模型的优先展示。
  - 自动同步更新 `context_window` 与 `max_context_window`。

- 🛡️ **原子安全落盘（Atomic Save）**
  - 写入临时文件并通过底层 `fsync` 强制刷盘后执行原子替换，杜绝断电或强退导致配置文件损坏或变空。

---

## 📋 前置要求

1. **Python 环境**：Python `>= 3.13`，推荐使用 [uv](https://github.com/astral-sh/uv) 进行包与环境管理。
2. **Codex 配置**：确保本机已安装并初始化 Codex，并在 `~/.codex/config.toml` 中配置了有效的代理 Provider。

示例 `~/.codex/config.toml` 配置：

```toml
model_provider = "my_proxy"

[model_providers.my_proxy]
base_url = "https://api.your-proxy-domain.com/v1"
experimental_bearer_token = "sk-xxxxxxxxxxxxxxxxxxxxxxxx"
```

---

## 🚀 快速开始

### 从 PyPI 安装

```bash
uv tool install codex-catalog
cxc
```

也可以免安装运行：

```bash
uvx --from codex-catalog cxc
```

### 1. 开发环境直接运行

使用 `uv` 无需手动创建虚拟环境，直接运行主程序：

```bash
uv run codex_catalog_builder.py
```

> 也可以通过项目安装的全局命令别名运行：
> ```bash
> uv run cxc
> ```
>
> 原有命令 `uv run codex-catalog` 仍然可用，两个命令调用同一入口。

### 2. 打包为独立单文件可执行程序

无需在全局环境预装 PyInstaller，直接通过 `uv --with` 运行打包命令：

```bash
uv run --with pyinstaller pyinstaller -F -n codex-catalog codex_catalog_builder.py
```

打包完成后，可执行程序将生成在 `dist/` 目录下：
- Windows: `dist/codex-catalog.exe`
- Linux: `dist/codex-catalog`

生成后可将对应平台的可执行程序复制到系统的 `PATH` 目录（或任意便捷位置），直接在终端中随时调用。

---

## 📖 操作指南

运行程序后，将经历以下三个主要阶段：

```
[1. 同步官方模型] ──> [2. 选择基准模板] ──> [3. TUI 模型管理主界面] ──> [4. 保存并退出]
 (GitHub / 缓存)     (↑/↓ 选择, Enter 确认)    (编辑/选中/排除/修改 Context)   (写入 custom_catalog.json)
```

### 阶段 1：同步官方内置模型
程序启动时会自动请求 GitHub 官方仓库获取最新的内置模型定义；若网络连接超时或失败，会自动回退读取本机的 `~/.codex/models_cache.json` 缓存。

### 阶段 2：选择基准克隆模板
程序会展示当前活跃且健康的官方旗舰模型候选列表（按版本、可见性及官方推荐优先级排序）。
- 使用 `[↑/↓]` 移动光标选择。
- 默认已高亮官方首选推荐模型，直接按下 `[Enter]` 即可确认。

### 阶段 3：TUI 交互与状态管理
进入主界面后，将显示代理返回的自定义模型列表。每行前的状态标记含义：
- `[ ]` **默认包含**：写入文件，使用基准模板的默认 Context Window（如 272,000 tokens）。
- `[x]` **自定义**：写入文件，使用用户单独指定的 Context Window。
- `[-]` **已排除**：不写入 `custom_catalog.json`。

#### 主菜单操作快捷键

| 按键 | 功能 | 说明 |
| :---: | :--- | :--- |
| `1` | **编辑模式** | 进入光标直接操作模式（支持空格标记、e 键排除等） |
| `2` | **批量选中模式** | 输入序号范围（如 `1, 3, 5-8`）批量标记并自定义 Context |
| `3` | **批量取消选中** | 输入序号范围将模型重置为默认模板 Context |
| `4` | **批量排除模式** | 输入序号范围批量标记排除（不写入文件） |
| `5` | **恢复排除模式** | 输入序号范围恢复为默认包含 |
| `6` | **应用并退出** | 生成完整配置，原子写入 `~/.codex/custom_catalog.json` 并退出 |

#### 编辑模式快捷键

| 按键 | 功能 |
| :---: | :--- |
| `↑` / `↓` | 移动光标 |
| `空格` | 切换当前模型为自定义状态 `[x]` / 默认状态 `[ ]` |
| `e` / `E` | 切换当前模型为排除状态 `[-]` / 默认状态 `[ ]` |
| `a` / `A` | 全选自定义 / 全选取消 |
| `x` / `X` | 全选排除 / 全选恢复 |
| `Enter` | 确认选择，并依次为所有标记为 `[x]` 的模型配置 Context Window |
| `ESC` | 放弃本次编辑模式的所有更改，还原初始状态 |

#### Context Window 输入格式
当提示输入 Context Window 时，支持多种常用写法：
- 带单位缩写：如 `128k`、`200k`、`1m`（不区分大小写，自动按 1,000 / 1,000,000 换算）
- 纯数字：如 `131072`、`200000`
- 直接回车：保持当前显示的数值不变
- 按 `ESC`：随时取消本次配置流程并安全回退

---

## 📁 产物与路径说明

| 路径 | 作用 |
| :--- | :--- |
| `~/.codex/config.toml` | Codex 核心配置文件，用于读取 `model_provider`、`base_url` 与认证 Token |
| `~/.codex/models_cache.json` | 官方客户端运行生成的本地内置模型缓存，用作离线同步兜底 |
| `~/.codex/custom_catalog.json` | 本工具的最终产物，Codex 官方客户端将读取此文件加载自定义模型目录 |

---

## ❓ 常见问题 (FAQ)

**Q: 运行后提示 `未找到 Codex 配置文件` 或 `缺少 base_url 字段`？**  
A: 请确认本机已启动过 Codex 并完成了基础配置。请检查 `~/.codex/config.toml` 中是否正确配置了 `model_provider` 以及对应的 `[model_providers.<name>]` 段。

**Q: GitHub 在线同步官方模型提示超时怎么办？**  
A: 程序内置了自动回退机制。只要您此前正常使用过 Codex，本机即会存在 `~/.codex/models_cache.json` 缓存，程序会自动读取本地缓存中的模型数据，无需担心。

**Q: 配置完成后，如何在 Codex 中生效？**  
A: 保存成功后，直接打开或重启 Codex 客户端/应用，在模型切换下拉列表中即可看到新注入的自定义模型。
