feat(models): bridge Chat Completions and Responses through Claude runtime

docs/协作/多模型协议桥接-实施方案-01.md

@@ -0,0 +1,52 @@
+# 多模型协议桥接实施方案 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 视觉验收尚未进行。结果和剩余限制在交付文档单独登记。