技术白皮书

1. 协议兼容：同协议直通，跨协议才转换

平台同时提供三类对外协议入口，每类都注册带 /v1 前缀和不带前缀两个路径：

核心取舍是不做无谓的协议归一：当客户端协议与渠道上游协议一致、且流式模式匹配时，走原始直通，上游 SSE/JSON 原样转发，完整保留 signature、cache_control、block 顺序、citations、thinking 等字段；只有跨协议时才做字段映射。

2. 客户端模板（client_preset）：按客户端"伪装"上游请求

很多编码类客户端对上游有特定的 header、默认 body 字段和协议形态要求。平台内置客户端预设，让一个渠道可以按目标客户端形态构造上游请求：

• 预设 → 目标协议映射：codex-cli→Responses、claude-code→Anthropic、gemini-cli→Gemini、cursor / cline / roo-code / opencode / workbuddy→OpenAI。渠道 protocol 与 client_preset 不一致时，按预设目标协议构造上游 payload。
• 按客户端补默认字段：例如 codex-cli 的 Responses 形态会补齐 instructions、text.verbosity、store=false、include=["reasoning.encrypted_content"]、reasoning.effort、prompt_cache_key 等，采用深度缺省合并——只补客户端没显式给的字段。
• 客户端识别：依次从 header（User-Agent 等）、body 的 client_type/client_preset、system 首条消息特征（如 "You are Claude Code"/"You are Codex"）判定。

3. 思考/推理字段：关闭即省略，不污染默认值

不同协议、不同客户端表达"思考"的字段各异（reasoning_effort / thinking / reasoning / thinking_budget 等）。平台的原则是不给上游塞客户端没要的字段：

• API Key 级 thinking 注入时，客户端已显式带该协议标准 thinking 参数则不覆盖。
• "关闭思考"一律通过省略参数表达：OpenAI 直接删 reasoning_effort，Anthropic 用标准 {"type":"disabled"}，Responses 删 reasoning。
• 跨协议构建请求时只复制存在的字段，context_management、mcp_servers、container 仅在源请求存在时才透传。
• Qwen 风格的非标准思考键（thinking_enabled / thinking_mode / thinking_budget 等）会映射为标准 reasoning_effort 后删除，避免污染上游。

4. 多渠道账号池与智能选路

每个 Provider 维护账号池，账号带优先级、权重、限流和运行态。智能选择不是简单轮询，而是多因子评分：

5. 限流、冻结与重试

• 多级限流：API Key 级 RPM/RPD/TPM/并发（Redis 固定窗口 + 原子并发占用），账号级 RPM/TPM/并发 headroom，模型级 TPM 固定窗口。
• 冻结策略：429 与上游异常触发冷却；渠道可配 freeze_policy 按状态码/响应头/错误码/模型匹配，scope 支持渠道/渠道模型/账号/账号模型，可永久冻结。
• 非重试 4xx 也走冻结：所有上游 HTTPException 先经冻结策略——例如 403 命中规则会当天冻结该账号，而不是简单透传。
• 两级重试：账号级重试（Provider 自身 retry_count 或全局配置）+ 模型组回退管线（visited 防环、backup_group 回退）。
• 上下文超限硬编码归一：prompt_too_long / context_length_exceeded 等特征被抽为硬编码归一器，命中判断零 IO 先行，出口层统一成 400 invalid_request_error，上游原文只进日志。

6. 计费与用量口径

• total = 输入 + 输出。缓存读、缓存写是输入 token 的明细子集，不额外计入 total；平台不采信上游自报的 total，一律用 prompt + completion 重算。
• 零 completion 兜底（协议无关）：usage 里 completion 为 0 但响应确有内容时，删除该 usage 让后续估算兜底；确实无内容才判为异常空输出。内容检测覆盖 OpenAI/Gemini/Anthropic/Responses 各类帧。
• 口径一致：管理端面板与主链路使用同一套 usage 归一逻辑，避免两处口径漂移。

7. CDP 浏览器工具（内置 MCP）

CDP 桥接把一个真实 Chrome 会话的能力暴露为 12 个 MCP 工具。配套 MV3 扩展通过 WebSocket 连接平台，平台把 Chrome DevTools Protocol 能力包装为工具供 Agent 或外部 MCP 客户端调用：

两种 token 不能混用

8. 浏览器内 Agent：网页里直接对话

除了把浏览器当工具，平台还支持在网页里直接和 Agent 对话——由一套 chat_* 帧协议驱动，复用同一条扩展 WebSocket，按帧 type 前缀与 CDP 驱动帧分流：

• chat_list_agents / chat_send / chat_abort / chat_new_conversation / chat_load_conversation / chat_list_conversations 等帧覆盖会话生命周期。
• 每帧按连接身份校验：Agent 是否对该 client 授权、页面是否属于该 client（会话级隔离）。
• 对话流以 chat_event 帧回传；底层 chunked 传输被截断时有专门的收尾处理，避免半截流污染会话。

效果：用户在受控浏览器页面里就能让 Agent 读取当前页、执行 JS、跨标签操作，Agent 的模型调用仍走平台统一网关和权限校验。

9. 终端与节点 Agent：无需 SSH 的执行

• 浏览器 PTY 终端：浏览器 WebSocket → 数据服务 → 控制服务 → NodeConnect 帧 → 节点本机 PTY（Unix pty / Windows ConPTY），输入、输出、窗口 resize 全在受控连接内；终端默认从节点用户 home 目录启动，连接断开时节点关闭残留 shell。
• host exec：在节点宿主机执行单条命令并结构化返回 stdout/stderr/exit_code，受超时（默认 2 分钟、上限 10 分钟）和输出上限（默认 1 MiB、上限 16 MiB）保护，需要节点声明 host_exec=true 能力。
• execution 节点跑 provider CLI：execution 节点在工作区内运行 claude/codex/gemini/opencode 等 CLI 会话，输出/结果/事件流式回传，会话配置以带版本号的帧下发并确认。
• 节点 HTTP 代理：请求可通过节点自身网络出口发起（用节点 IP、NAT 后网络或内网资源），响应以隧道帧回传。

10. 请求级观测

每一次客户端请求对应一个 request_id，每次账号尝试（attempt）逐条记录，attempt_key 唯一、attempt_no 顺序编号，以 request_id 建立关系。记录字段包括：

• request_id / API Key lineage 快照 / provider / account / 请求模型 / routed model / upstream 返回模型 / endpoint
• success / status / stream / duration / 首 token 时间 / prompt·completion·total·cached·cache_creation·reasoning token
• 请求路径、上游状态、错误、脱敏请求/响应头、按策略保留的正文、路由耗时分项、routing 降级标记、proxy 信息

PostgreSQL 是权威存储；开启后可把大字段 payload 旁路双写到 ClickHouse（started=version1 / finalized=version2），双写失败只丢批、绝不影响主链路和路由。