# 多模型协议桥接实施方案 01

日期：2026-10-21。起点：`8fcfb69408716a98d4fd09bd34912048ba419891`。
用户要求：Chat Completions 与 Responses 同批实现；Gemini 暂不考虑；UI 不漂移。

## 范围与边界

- 保留 Claude Agent SDK、文件/终端执行、MCP、Skill、授权、会话与消息渲染机制。
- Anthropic Messages 维持直接连接；OpenAI Chat Completions / Responses 经过 YCode 主进程回环协议桥。
- 仅参考 magpie 的公开协议转换思路（参考提交 `ba319a7587923fc7a4ea3859658244d591261a59`），不引入其订阅账号、登录发现、插件、MCP、Skill、工具执行机制或完整网关。
- 不对接 wuli-go；不新增自动路由、账号轮换、模型回退、供应商页面、远程网关管理。
- 不自动读取用户账号或调用真实模型 API。模拟上游与 mock SDK 验证和真实 SDK / Windows 验收分别记录。

## 结构

1. `shared/models.ts`、`model-support.ts`：协议族与明确 API 偏好分别表达；旧 Anthropic 配置兼容。
2. `main/models.ts`、`model-connection.ts`：发现、测试、保存、回显尊重明确 API；协议变更使验证缓存失效。沿用密钥加密和原子存储。
3. `main/model-bridge/`：Messages 解析、统一结构、Chat / Responses 编解码、SSE、错误、取消与本机监听生命周期。
4. `agent/claude/claude-kernel.ts`：只为非 Anthropic 模型取得桥接租约；真实上游密钥不传给 SDK，使用独立本机令牌。缓存身份包含 API、上游模型/地址、能力与凭据修订。
5. `chat-turn-service.ts`：只允许实际已实现的 API，继续使用同一内核与事件契约。

每个内核固定当前路由。普通队列仍在新回合开始时解析会话模型；立即追加仍沿用当前回合模型。权限入队快照与下次消息设置不改。禁止把此次工作扩大为队列模型快照语义迁移。

## UI 冻结

- 现有新增/编辑模型的“接口协议”下拉框增加两个选项，合计 Anthropic Messages、OpenAI Chat Completions、OpenAI Responses。
- 模型选择器仅更新支持判断及真实能力数据，不新增列表分组、图标、徽标或弹窗。
- 不改选择器 `source.mjs`、`source.css`、`source-adapter.css`；不改模型设置 CSS、ChatPane、MessageBubble 或对话组件布局。
- 现有错误/连接反馈位置复用；获取模型目录成功不等于生成、工具及流式兼容已验收。
- 无能力的思考档位不虚构。历史配置编辑后不得强制改写为 Anthropic。

## 协议与安全契约

- 仅监听回环地址，随机端口、独立租约认证；请求不能携带任意目标 URL/密钥改变路由。
- 不转发 SDK 本地认证到上游；不把凭据写入日志、事件或测试产物。
- 支持非流式及流式文本、图片、工具定义/调用/结果、增量 JSON 参数、用量与结束原因。
- 工具只做格式转换，绝不由桥执行。未知或无法保真的能力明确报错，不静默成功。
- SSE 处理跨网络块分片与断流；已发送内容后不自动重放，不伪造正常完成。
- 用户取消/客户端断开取消上游连接；内核关闭、失败及应用退出撤销租约。
- token 估算与真实上游用量分离；思考签名不伪造，跨协议/重启后的不透明推理状态须如实标注限制。

## 交付与验收

- 两种 API 同批提交；Anthropic 原路径不回归。
- 离线协议测试：请求映射、两种响应格式、SSE 分片、工具多轮、图片、错误、取消、端点认证、双会话隔离。
- mock SDK 主机测试：直接/桥接环境、凭据隔离、启动竞态、协议变更重建、失败/关闭清理、现有授权规则。
- 模型管理回归：新增/编辑/重开、偏好持久化、目录与生成测试身份、缓存失效、密钥不泄漏。
- 现有核心、对齐、对话、授权、持久化与生产构建按实际可运行入口验证。
- UI 最终在 Windows 对照相同尺寸浅/深色旧场景截图；只允许新增协议选项及模型文案变化。离线 DOM 和构建不能替代实机视觉验收。
- 真实模型与 SDK 端到端兼容、压缩/恢复与供应商特有行为，不得用 mock 通过宣称已完成。

状态：实现与离线验证完成；真实 SDK、真实供应商与 Windows 视觉验收尚未进行。结果和剩余限制在交付文档单独登记。