Skip to content

模桥 · ModelBridge 源码证据 ​

本页记录 2026-10-31 的 widened docs sync:先沿一次请求找交接,再用失败、并发和协议约束反查。调查起点为 12a0f67ef4d2e715e421104f31bac5a10a8c159c 及其后的未提交工作树;历史信息整理后的对应锚点见同步记录。源码检查、模拟测试、文档构建和生产验收分别记账。

Evidence Traversal Log ​

PassPurposeInspected evidenceWhat changed in the model
Pass 1从真实入口建立输入、配置、选择与输出链_worker.js 的 fetch、handleRequest、checkProxyAuth、handleV1Proxy、handleCompletions、resolveModelName、callOpenAICompatibleAPI;wrangler.toml;tests/universal-upstreams.test.mjs选定 OpenAI 聊天输入访问已配置上游的代表场景;区分客户端协议、模型目标和账号凭据。
Pass 2用失败与并发挑战主流程,补全被跳过的依赖AppConfigStore、readRequestJson、fetchUpstream、shouldRetryUpstream;配置、请求安全、协议与账号专项测试;tools/、工作流、文档站配置和脚本DO 是配置权威;明确拒绝与不确定结果必须分开;协议转换不能静默丢弃约束;把访问配置、协议路由、资源配额拆成各自的说明页。
Pass 1(2026-11-02)沿新平台入口跟随一次调用createGateway、src/platforms/、src/state/、deploy/、tools/build-platforms.mjs共享核心保留;新平台直接访问上游,状态仍经认证服务访问原 DO。
Pass 2(2026-11-02)检查平台边界与并发反例状态通道、运行时预算和产物回归;Makers/ESA 官方规格;OAuth 取消交叉审查强一致读取不能替代串行更新;首字节、总时长、状态 body 取消和请求级 OAuth 刷新必须分别约束;真实平台尚未验收。
Pass 1(2026-11-02,自建状态)跟随三个入口到真实持久化服务GatewayStateStore、sqlite.mjs、Node HTTP 宿主、三入口集成、六套构建模板自建 SQLite 成为独立权威,无 Cloudflare DO/KV 必需依赖;模型流仍直接由网关请求上游。
Pass 2(2026-11-02,自建状态)挑战事务、重启、迁移和 HTTP 边界跨连接及跨进程更新、会话重启、空库导入竞态、在线备份、取消与 raw path 测试;Node/SQLite 官方文档和独立复核事务保护完整读改写;旧快照不能覆盖已有状态;修复仅含 VIEW 的其他数据库被误接管;本地集成与生产验收分开。
Pass 1(2026-11-02,部署验收)从生成产物进入实际 Linux 容器和官方 CLIDockerfile、Caddy 模板、verify-self-hosted-container.mjs、verify-state-tls.mjs、verify-edge-builds.mjs把源码导入与产物运行分开;私有 CA TLS 与公网证书分开;按平台记录真正可用的本地命令。
Pass 2(2026-11-02,部署验收)检查恢复、证书拒绝、权限和清理边界Linux 0600/WAL/硬链接、备份恢复到新路径、跨 origin 会话、未信任 CA、错误主机名、资源 UUID 标签与独立复核备份恢复不能覆盖含旧 WAL/SHM 的路径;TLS 负例不能用网络失败替代;不登录、上传或把通用打包标为厂商验收。
Pass 1(2026-11-02,内部审查)沿旧核心与新宿主交界检查文档、安全、逻辑及资源使用共享状态引擎、SQLite/远程信号、OAuth 控制请求、ESA 管理诊断、构建和维护工具;README 与概念页把订阅者取消、共享任务关闭、控制请求读取及平台总预算分别建模;修正仍把用量权威写成 DO 的文档。
Pass 2(2026-11-02,内部审查)用真实文件与并发反例验证修复用量 A/B 取消、无响应网络关闭、父子信号、OAuth 挂起/超限/滴流、ESA 零探针拒绝、构建硬链接、摘要数组类型回归修复跨请求取消污染、诊断部分执行、悬挂读取及目录外文件覆盖;摘要严格类型属于授权输入加固,不是越权。
Pass 1(2026-11-02,第二轮审查)反查上一轮修复及未覆盖的成功/错误路径模型目录去重、数据库路径与备份、平台成功上传/HEAD、OAuth 和目录诊断;SQLite GraphQL 传输封装备份路径必须与 WAL 对应,硬链接主文件别名不能充当当前权威;成功响应也需要清理未使用上传。
Pass 2(2026-11-02,第二轮审查)对照真实 WAL、算法规模及旧 GraphQL 错误语义撤销后硬链接备份反例、目录 1000/5000/10000 模型夹具、HTTP/GraphQL 错误矩阵及平台生命周期测试打开与备份拒绝多链接 DB;集合去重保留目录顺序;有界传输仍保留明确鉴权拒绝回退,其他失败不扩散。
Pass 1(2026-11-02,第三轮审查)沿容量与清理边界追查前两轮遗漏满 16 MiB 配置导出、未鉴权停滞上传、半开 CONNECT/Upgrade/解析错误、协议拒绝等待上游取消;Cloudflare 官方 DO 容量说明区分配置字节与迁移封装、认证与正文缓冲、发出取消与取消确认;原生 DO 和自建 SQLite 容量不能混同。
Pass 2(2026-11-02,第三轮审查)交叉验证修复与旧契约SQLite→认证服务→导出导入往返、超限写入回滚后撤销、真实 TCP、取消未决/抛错/拒绝、完整旧协议矩阵与 keepalive/鉴权中断连导出仅增加元数据余量;认证前置、特殊连接有限关闭;共享取消及时结束本地消费且不重发生成。Expect 上传正常关闭是反证,没有为其增加修复。

理解提要 ​

场景:客户端用实例调用密钥向 /v1/chat/completions 发送模型别名和消息,别名指向一个已配置的供应商模型。网关核验调用权,解析目标,再从启用且允许该模型的账号中选择上游。普通结果或 SSE 返回客户端协议。

难点是三种权限和多种协议同时存在:知道一个模型名字,不代表有可用账号;请求要求的工具、思考或格式约束,也不一定能跨供应商实现。失败例是网络中断后不能判断是否已经生成,因此不会换账号重做。可推翻这个模型的证据是第二次生成调用、错误凭据路由或被丢弃的显式约束;下一步应检查具体协议与目标账号的组合,而非从聊天成功推断全部兼容。

证据表 ​

ClaimEvidenceConfidenceCaveatUsed by
三个平台通过认证状态服务共享自建 SQLite;DO 桥接可选远程通道(仓库文件:src/state/remote.mjs)、服务(仓库文件:src/state/service.mjs)、三入口集成(仓库文件:tests/self-hosted-platforms.test.mjs)已确认本地实现Bearer 令牌属于高权限边界,不提供被盗令牌防重放;云端持久化另验平台指南
请求级网络、输入及流预算与其他请求隔离运行时(仓库文件:src/platforms/shared.mjs)、核心注入回归(仓库文件:tests/gateway-runtime.test.mjs)、预算回归(仓库文件:tests/platform-runtime.test.mjs)已确认本地实现原生 signal 存在不证明真实断连传播平台指南、上游与配额
六套部署产物隔离 Node 模块与边缘入口、源码与静态目录,不读取真实 Secret构建器(仓库文件:tools/build-platforms.mjs)、产物测试(仓库文件:tests/platform-build.test.mjs)、部署工具(仓库文件:tools/verify-edge-builds.mjs)已确认本地实现Wrangler dry-run/workerd 与其他平台、云端部署分别验收代码地图、平台指南
自建产物可以在隔离 Linux 容器运行,Caddy TLS 保持链与主机名验证容器工具(仓库文件:tools/verify-self-hosted-container.mjs)、TLS 工具(仓库文件:tools/verify-state-tls.mjs)、TLS 客户端断言(仓库文件:tools/verification/state-tls-client.mjs)实际结果见同步记录内部 CA 不证明公网签发;容器重启不等于主机掉电恢复平台指南、部署说明
管理凭据、实例调用密钥和供应商凭据分工不同请求与鉴权(仓库文件:_worker.js):handleRequest、checkProxyAuth、checkAdminAuth;安全断言(仓库文件:tests/security-hardening.test.mjs)已确认不证明真实 Secret 的保管方式访问与配置、主流程
配置、会话与用量由选定权威保存;SQLite 配置/会话事务覆盖读改写,KV 只用于原生 DO 首次迁移共享引擎(仓库文件:_worker.js)、SQLite 存储(仓库文件:src/state/sqlite.mjs)、真实事务断言(仓库文件:tests/sqlite-state.test.mjs)、DO 兼容断言(仓库文件:tests/config-auth.test.mjs)已确认本地实现SQLite 支持边界为单机本地磁盘,用量刷新合并不跨进程;云端迁移另验访问与配置
导入只接受无业务状态的数据库,备份不覆盖已有目标维护工具(仓库文件:tools/state-admin.mjs)、导入及备份断言(仓库文件:tests/state-admin.test.mjs)已确认本地实现工具不能证明导出时旧写入已冻结,恢复旧备份需核对撤销平台指南
JSON 限制累计实际字节,错误不回显原始解析输入有界读取(仓库文件:_worker.js):readRequestJson、requestJsonErrorResponse;请求安全回归(仓库文件:tests/review-request-security.test.mjs)已确认16 MiB 包含内嵌 base64,不是上下文 token 限额主流程、访问与配置
目标供应商、启用状态、指定账号和模型白名单共同筛选凭据模型选择(仓库文件:_worker.js):resolveModelName、parseUpstreamTarget、getMatchingUpstreamAccounts;跨上游断言(仓库文件:tests/universal-upstreams.test.mjs)已确认空账号模型列表不限制模型;上游实际权限仍未知路由与协议
更换供应商要求新凭据并清除继承目标信息账号归一化(仓库文件:_worker.js):normalizeProviderAccountInput;账号回归(仓库文件:tests/review-account-embedding-round2.test.mjs)已确认同供应商留空保留原凭据访问与配置
只有 401/403/404/429 等明确拒绝可换账号,最多三个候选上游边界(仓库文件:_worker.js):shouldRetryUpstream、fetchUpstream;失败与预算断言(仓库文件:tests/upstream-safety.test.mjs)已确认并非任意错误自动恢复;取消不等于停止计费上游与配额、主流程
显式协议约束不能执行时拒绝,不伪造正常终止协议回归(仓库文件:tests/review-protocol-regressions.test.mjs)、别名与工具回归(仓库文件:tests/review-protocol-round2.test.mjs);normalizeGeminiRequestFields、geminiFinishToOpenAI已确认测试覆盖指定字段和组合,不是完整供应商兼容认证路由与协议
嵌入输入配置及输出的数量、索引、维度和数值需校验嵌入实现(仓库文件:_worker.js):normalizeEmbeddingOptions、validateEmbeddingOutput;上游回归(仓库文件:tests/review-upstream-regressions.test.mjs)、账号回归已确认非法成功响应不重新生成;真实模型维度与权限另验路由与协议
OAuth 刷新合并仅作用于同一实例,用量查询有独立缓存OAuth 与用量实现(仓库文件:_worker.js):getAntigravityToken、refreshAntigravityToken、usageAccountGroups;配额回归(仓库文件:tests/quota-project-regressions.test.mjs)已确认不是跨实例锁,也不是硬性预算控制上游与配额
离线护栏检查索引与提交对象,例外撤销不能继续复用旧判定维护脚本(仓库文件:tools/repo_maintenance_guard.py)、隔离 Git 回归(仓库文件:tests/repo-maintenance-guard.test.mjs)已确认大文件等扫描边界见 SECURITY;不能替代业务测试贡献规范(仓库文件:CONTRIBUTING.md)、代码地图
CI 测试与上游提案隔离,文档站独立构建测试工作流(仓库文件:.github/workflows/test.yml)、上游提案(仓库文件:.github/workflows/sync-upstream.yml)、站点配置(仓库文件:docs-site/.vitepress/config.mts)已确认配置审阅不等于远端工作流已成功运行代码地图

覆盖范围与排除 ​

第一方实现范围:根 Worker、平台与状态适配器、部署模板和构建器、测试、离线维护工具、GitHub 工作流、文档站配置与默认主题入口。品牌 SVG 和截图只核对展示入口;源码地图列出责任及验证位置。

相邻路径已确认但不逐段解释:管理界面每个交互、用量 GraphQL 字段、所有模型的多模态能力和完整跨协议组合。node_modules、构建产物、缓存、未启用的文档装饰资源及其第三方 vendor 不作为业务实现证据。没有访问真实账号、读取生产私有配置或执行线上请求。

反证与后续问题 ​

反证检查(Falsifying check):如果同一个不确定网络结果触发第二轮生成、被撤销的密钥因并发写重新出现、或跨供应商转换丢掉显式约束后继续调用,应修改主流程模型并增加对应回归。

下一位读者可能问(Next reader question):怎样知道一个具体模型与协议组合能用于生产?先检查路由支持与拒绝边界,再单独验证真实账号权限、云端存储和流取消;本地模拟与文档构建不能替代这些结果。实际执行记录集中在同步记录。

证据状态:除特别标注外,本页基于当前源码已确认。