Files
Agent-Workbench/docs/MODEL-REQUEST-CONTRACT.md
T

26 lines
3.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 模型请求契约
本批对应 I14/I12,以实际发送的 API 版本、认证、请求头、路径与非提示参数为范围。模型注册表资料版本与 API 请求版本分别管理;旧 ordered-prefix v1/v2 的方法和原 SHA 保持。
## 官方依据
来源固定在 [SOURCE.json](../tests/fixtures/model-request-contract/SOURCE.json),11 份有效资料共 480878 字节,其中 7 份 DeepSeek 原件引用此前已提交的固定来源,不重复下载。各正文 SHA、获取表示和日期逐项保存。
- [Anthropic 版本](https://platform.claude.com/docs/en/api/versioning):必须发送 anthropic-version,当前推荐 2026-10-21;2023-06-01 仍在版本历史。新版拒绝 temperature、top_p、top_k、assistant 直接 document、user 非空 citations 等列明用法。
- [Anthropic 概览](https://platform.claude.com/docs/en/api/overview):推荐 Authorization Bearer,仍支持 x-api-key;新官方连接采用可靠官方默认,已有连接保留原默认。
- [Anthropic Beta](https://platform.claude.com/docs/en/api/beta-headers):用户显式选择,多个值用逗号组成一个头;未知或不相容 beta 由上游返回原错误,不自动移除或换版重放。
- [OpenAI 概览](https://developers.openai.com/api/reference/overview):Bearer;组织、项目、客户端请求 ID 是可选头;响应 openai-version 当前 2020-10-01,与注册表版本无关。官方建议的头大小与客户端 ID 长度不变成本工作台新增的本地拦截额度。
- [DeepSeek Messages](https://api-docs.deepseek.com/api/create-message.md):版本头可选,x-api-key/Bearer 均支持。按 DeepSeek 自身契约处理,不能套用 Anthropic 全部必填条件。
单独迁移页的一次获取返回 HTTP 200,但最终地址是 claude.com/app-unavailable-in-region,正文是地区不可用页面。该原件和原获取记录保留;SOURCE 将其明确标成 accepted=false,不作为迁移文档或配置依据。当前只依据成功取得的版本历史中明确列出的变更。
## 实现范围与回顾
连接请求设置与原生 JSON 分开。保留版本/beta/额外头/认证和模型及目录路径;Run 与每个池成员各自冻结有效设置,实际选中成员决定发送契约。凭据仍由现有独立 Key 管理,自定义鉴权头引用凭据;普通版本/beta/非鉴权头编辑不重新加密已有 Key。
每次物理尝试保留 body 原 JSON SHA;另记录准备提交给 fetch 的去凭据头、方法、端点、版本、绑定和非提示参数指纹。明确该记录的规范化/脱敏表示,不称 HTTP 原字节;相同指纹只说明观察字段相同,缓存命中、真实兼容和工程收益仍由上游实际结果独立证明。
原 Run 推导的对照单列为 `frozen-run-contract` / `frozen-request-contract-redacted-v1`,鉴权只表示模板,不证明本次已带 Key。物理尝试记录为 `prepared-fetch-arguments` / `fetch-request-metadata-redacted-v1`,采用传给 fetch 的有效头。新目录声明另绑定实际目录地址、有效头模板和凭据修订;组织、项目、版本或凭据变化后不把旧声明当当前事实,原目录与旧快照仍保留。逐字符串脱敏不改请求 JSON 结构,空规格也能显示未知。
默认 unrestricted/passthrough/preserve 与持久 ask/auto/full 保持。不改用户原生参数、不自动换线/换版本/重放失败请求。不请求真实模型或读取真实 Key、不写正式数据/配置或部署;历史网络异常、unknown、重复读取、R/W 边界与 Purge 收益 unknown 保留。