Metadata-Version: 2.4
Name: cmp-gateway
Version: 0.1.25
Summary: Codex 多模型接入与体验增强系统：本地多模型网关（Responses API → 多上游协议）
Author: cmp-dev
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: httpx<1.0,>=0.27.0
Requires-Dist: keyring<26.0,>=25.0.0
Requires-Dist: pydantic<3.0,>=2.7.0
Requires-Dist: rich<15.0,>=13.7.0
Requires-Dist: starlette<1.0,>=0.37.2
Requires-Dist: tomli-w<2.0,>=1.0.0
Requires-Dist: typer<1.0,>=0.12.0
Requires-Dist: uvicorn<1.0,>=0.30.0
Description-Content-Type: text/markdown

# Codex 多模型接入与体验增强系统

在本机运行一个**多模型网关**，让你在完整保留 Codex harness（项目上下文、AGENTS.md、沙箱、审批、Shell、补丁、Git 工作流、会话记录）的前提下，按需切换：

- **OpenAI 原生模型**（ChatGPT 订阅登录或 OpenAI API Key，走 Codex 内置 Provider，不经过网关）；
- **第三方模型**（首期：DeepSeek 官方、Kimi/Moonshot 官方，经独立 API Key 通过本地网关接入）。

> 当前状态：**M0~M6 实现完成；真实环境验证清单 7 项已于 2026-08-06 全部完成**
> （真实上游探测/集成、wire_api 双平台实锤、真实 Codex E2E、fixture 真机重录、UI 覆盖层等价验证、S-06 终验；
> 个别项含"有偏差"备注，见 [任务交接文档](task-handoff.md) §3）。

## 为什么需要它

Codex 的价值不仅来自模型，更来自它的 harness。直接换聊天客户端会失去项目理解、工具执行、沙箱与审批等能力；而 Codex 自定义模型 Provider 只支持 Responses wire API，DeepSeek/Kimi 官方接口主要兼容 OpenAI Chat Completions——简单改 `base_url` 无法解决协议、工具调用、流式事件与推理内容重放问题。本项目用一个本地网关补上这一层，同时提供余额可见、会话连续性与体验增强。

## 核心设计

```
用户 (Windows / WSL)
   │
   ▼
Codex CLI / Desktop ───────► OpenAI 内置 Provider ──────► OpenAI（ChatGPT 登录 / API Key）
   │  （harness：沙箱·审批·Shell·补丁·Git）
   │
   └─ multi_gateway ──► 本地多模型网关 127.0.0.1:8787 ──► DeepSeek 官方 API
                          Responses API（统一入口）   ──► Kimi / Moonshot API
                          │                            ──► 其他来源（OpenRouter / 本地模型等）
                          ├─ Canonical IR（统一中间表示）
                          ├─ 协议适配器（openai-chat / anthropic / passthrough）
                          ├─ Provider 插件（认证·专有参数·余额·错误归一化）
                          └─ 能力注册表 · 显式路由 · 账户状态 · Handoff
```

**核心原则**：Codex 继续拥有执行能力；网关只负责模型协议、路由、账户状态与兼容性。

- **双域模型**：OpenAI 原生域（订阅权益）与 multi_gateway 域（各 Provider 独立计费）完全隔离，不混淆。
- **逻辑模型 ID**：`<provider>/<alias>`（如 `deepseek/default`、`kimi/default`），与上游具体型号解耦。
- **适配器与插件分离**：同协议平台复用转换逻辑，新增一个 OpenAI Chat 兼容 Provider 不改核心代码。
- **会话连续性**：跨 Provider 默认生成 Provider 中立的 **Handoff Snapshot** 开新线程继续；原线程跨域恢复仅为实验模式。
- **余额可见**：统一账户状态模型（DeepSeek `/user/balance`、Kimi `/v1/users/me/balance`），60 秒缓存，本地面板只读展示。
- **UI 可选**：Codex Desktop 状态面板经本机回环 CDP 注入（Shadow DOM），不改官方二进制；失效不影响 CLI/网关。

## 功能速览

| 能力 | 说明 |
|---|---|
| 统一 Responses 端点 | 网关实现 `/v1/responses`（JSON + SSE），Codex 原生对接 |
| 协议转换 | Responses ↔ OpenAI Chat Completions；Anthropic Messages 预留 |
| 工具调用 | function 工具、freeform/`apply_patch` 包装、多轮工具 reasoning 重放、流式参数重组 |
| 能力校验 | 目录声明 + 实测探测（true / adapter / false / unknown），不支持则请求前拒绝 |
| 快捷启动 | `cmp codex start --project . --model deepseek/default` 一条命令切换来源 |
| 模型切换与思考强度 | `cmp codex use <别名> --effort <档>`；统一 effort 映射各上游（DeepSeek x_high 裁剪、Kimi 全档位，实测见 usage-guide §4） |
| 长上下文行为适配（0.1.13） | 按模型开关（models.toml `long_context_reminder`，默认关）：超长上下文+短指令时注入通用执行提醒（见 usage-guide §4.4） |
| 项目连续性 | 项目锚点索引 + Handoff Snapshot（保留工作目录、Git 状态、指令、待办与摘要） |
| 账户状态 | 余额/额度统一建模、缓存与脱敏展示 |
| 诊断与回滚 | `cmp doctor`、`cmp config-explain`、脱敏诊断包、`cmp rollback` 一键恢复原生状态 |

## 安全与隐私要点

- 网关**只监听 `127.0.0.1`**（默认 8787），本机随机令牌认证。
- API Key 只存 Windows Credential Manager / 系统 keyring，**永不进入**仓库、普通日志、诊断包、DOM 或 localStorage。
- **手动路由优先**：429、余额不足、超时只报错，绝不自动把代码转发到另一平台；项目-Provider 首次使用需显式授权。
- ChatGPT Plus 权益与第三方 API 账户完全独立；本项目不破解、代理或导出 ChatGPT OAuth 凭据。
- 所有对 Codex 配置与 UI 的改动先备份、可一键回滚。
- **不使用网关时 Codex 完全正常（关键精神）**：`cmp gateway stop` 一条指令关闭网关并
  恢复现场（配置回退原生态、生成块移除；环境变量保留），历史会话与原生 OpenAI 不受影响。

## 文档

| 文档 | 说明 |
|---|---|
| [详细设计方案 v1.0](docs/Codex多模型接入与体验增强系统_详细设计方案_v1.0.docx) | 唯一权威需求与设计来源（需求、架构、接口、安全、测试、路线图） |
| [开发计划总览](tasks/README.md) | M0–M6 里程碑、依赖关系、离线基线与发布验收门槛 |
| [任务交接文档](task-handoff.md) | 接手维护必读：进度、真实环境验证清单、代码地图、偏差与红线 |
| [架构文档](docs/architecture.md) | 组件边界、Mermaid 图、ADR-001~007 状态 |
| [错误码登记表](docs/error-codes.md) | CMP-<域>-<编号> 全部已登记错误码（新增必须登记） |
| [Provider 开发指南](docs/provider-development.md) | 三步接入、安全清单、S-06 终验流程 |
| [上游实测笔记](docs/provider-notes.md) | DeepSeek/Kimi 能力基线（2026-08-06 已实测回填） |
| [Codex 配置基线](docs/codex-config.md) | 版本/覆盖规则/wire_api 实测（已双平台回填） |
| [技术选型](docs/tech-stack.md) | 选型理由与放弃方案对比 |
| [安全设计](docs/security.md) | §7 威胁模型落地与验证结果 |
| [日常使用指南](docs/usage-guide.md) | 安装后每天怎么用（选模型/检查/更新） |
| [排障指南](docs/troubleshooting.md) | 常见问题定位与修复 |
| [修复日志](report/fix_log.md) | 开发完成后发现/修复的问题全记录（根因+验证，持续追加） |
| [许可证审查](docs/license-review.md) | OQ-06 结论（MIT，发布审计已完成） |
| [一致性检查报告](docs/consistency-reports/) | 设计方案 vs 架构 vs 代码的定期核查报告 |

## 快速开始（已实现）

```powershell
# 前置：Windows 11 / WSL，uv 环境（见 docs/tech-stack.md）
cmp init                                        # 初始化目录、本地令牌、示例配置
cmp provider-add deepseek                     # 交互式添加 Provider，Key 只写入凭据管理器
cmp provider-add kimi
cmp serve                                     # 启动本地网关（127.0.0.1:8787）
cmp codex start --project . --model deepseek/default   # 生成 profile 并用 DeepSeek 启动 Codex
cmp codex use kimi/default                       # 切换默认模型（重启/新线程生效；Desktop 日常入口）
cmp codex resume --project . --model kimi/default --handoff auto   # 生成 Handoff 切换 Kimi 继续项目
cmp doctor                                      # 全面自检
cmp gateway stop                                # 关闭网关并恢复现场（回到纯原生 Codex）
```

> 注：以上命令均已实现并通过自动化测试；真实环境验证清单（上游实测、wire_api 基线、
> 真实 Codex E2E、fixture 重录、UI 覆盖层、S-06）已于 2026-08-06 全部完成，
> 详情见 [task-handoff.md](task-handoff.md) §3 与 [一致性检查报告](docs/consistency-reports/)。

## 项目状态与路线图

| 里程碑 | 交付结果 | 状态 |
|---|---|---|
| M0 研究与基线 | 可重复的最小 Responses 请求样本 | 已完成（2026-08-06 真机重录与实测回填） |
| M1 网关 MVP | 文本请求可通过网关完成 | 已完成 |
| M2 双 Provider | DeepSeek/Kimi 完成文本和余额测试 | 已完成（真实 API 集成 10/10） |
| M3 Harness 兼容 | Shell 与 apply_patch E2E 通过 | 已完成（真实 Codex CLI E2E 通过） |
| M4 启动与会话 | 一条命令切换并继续项目 | 已完成 |
| M5 UI 原型 | 不改官方二进制的可选 UI | 已完成（Edge 等价验证；Desktop 受 MSIX 限制；模型切换闭环 M5-T04 已实现，重启/新线程生效） |
| M6 扩展生态 | 新增 Provider 的文档化流程 | 已完成（S-06 终验通过） |

目标平台：Windows 11（主）/ WSL 与 Linux（兼容）。技术栈：Python + uv（MVP），单用户本机回环部署。

## 非目标

不破解/代理 ChatGPT OAuth 凭据；不把 Plus 权益转化为通用 API；不修改 Codex 官方二进制；首期不做自动选最便宜模型或用户不知情的跨平台转发；不承诺跨厂商私有 reasoning 无损迁移；不做云端多用户网关。

## 许可证

[MIT](LICENSE)。发布审计（依赖许可证核对、密钥安全审计）已于 2026-08-06 完成，
详见 [发布就绪审计报告](docs/consistency-reports/2026-08-06-release-readiness-report.md)。

## 发布与安装

- PyPI：<https://pypi.org/project/cmp-gateway/>（v0.1.0 起，wheel + sdist）
- 远端仓库：<https://github.com/Pigeon258/codex-multi-provider>（公开，MIT）
- GitHub Release：<https://github.com/Pigeon258/codex-multi-provider/releases>（附构建产物）

```bash
# uv（推荐，从 PyPI）
uv tool install cmp-gateway
# 或 pip
pip install cmp-gateway

# 或从 GitHub Release 直装
uv tool install --upgrade cmp-gateway   # PyPI（推荐）；或 GitHub Releases 页下载 wheel：https://github.com/Pigeon258/codex-multi-provider/releases
```
