DeepSeek through the Anthropic Messages protocol
通过 Anthropic Messages 协议调用 DeepSeek
Messages represents thinking, signatures, tool calls, tool results, and cumulative usage as native protocol fields. Translating only the endpoint or flattening assistant history loses information needed by subsequent tool turns.
English
Problem
Messages represents thinking, signatures, tool calls, tool results, and cumulative usage as native protocol fields. Translating only the endpoint or flattening assistant history loses information needed by subsequent tool turns.
Decision
The DeepSeek adapter serves Messages under one deepseek-official route and llm-deepseek settings namespace. The single-protocol reference owns the transport scope. PreparedAdapterCall freezes the endpoint, credential reference, and model capabilities; retries retain that generation while subsequent calls read new configuration.
The adapter follows the DeepSeek compatibility documentation and Anthropic streaming protocol. The pi-ai Anthropic implementation informed the handling of adjacent user messages, cumulative usage, fragmented tool arguments, and optional thinking signatures. DeepSeek effort uses output_config.effort; an Anthropic thinking token budget does not control DeepSeek effort. The adapter forwards explicit temperature values; DeepSeek accepts that parameter with thinking enabled and ignores its value, so callers retain their existing thinking configuration.
Assistant blocks remain the durable model-visible content. A versioned ReplayEnvelope stores only the protocol format, model identity, aligned block kinds, and signatures absent from those blocks. Same-model Messages continuation restores signatures verbatim, including empty signatures; foreign history carries no invented signature. Unusable metadata follows the existing replay degradation rule: the request omits signatures with a warning while preserving durable content; historical tool arguments use the empty-input fallback when Messages cannot represent them. This keeps provider replay data opaque to the loop while preserving it through Session persistence and block pruning.
The adapter prefers Files references for deterministic request images, with upload caching, refresh, quota recovery, and attachment offload. The Files client follows the exact /v1 root rule and sends the required beta header. Cached ids remain scoped by the resolved Files root and credential, so equivalent /v1 and unversioned roots share uploads. Metadata omits expiry, so local reuse is bounded from the original upload time without asserting remote deletion. A Files-resolution failure rebuilds the complete request under the independent inline-image budget; caller cancellation stops it. The image policy preserves the 128 MiB retained-image budget, 20 MiB inline base64 budget, and oldest-prefix offload in both requests and token measurement.
JSON syntax failure after a successful HTTP response does not establish a transport failure. Files decoding uses the existing INVALID_RESPONSE code with operation context instead of relabeling the failure as TRANSPORT or adding a retry; the provider README owns the error fields.
System updates use the existing route capability when explicitly declared for an endpoint/model. Messages retains the initial top-level system and emits later snapshots as native system turns after the corresponding user/tool-result turn, preserving previously sent prefixes. This placement differs from the loop's system-before-user admission; serialization changes neither the durable log nor conversation-turn order. Undeclared routes consolidate the latest snapshot at the top level, including direct compaction calls. Capability inference from protocol or model names is insufficient because support and update semantics depend on the deployed endpoint.
Web displays DeepSeek with an endpoint and credential reference. Without an endpoint override, resolution uses https://api.deepseek.com/anthropic. Overrides must support Messages. The adapter follows the exact /v1 root rule rather than inferring compatibility from other version-like suffixes. One model catalog advertises the capabilities declared by its entries.
The adapter uses the existing request-extension registry after native serialization and accepts captured contributions after HTTP 2xx, before reading the stream. Session-log delivery and plugin inventory retain their owners and remain outside model input. The auxiliary web-search provider retains its separate endpoint, request, and settings.
Alternatives considered
Separate Messages provider identity. This duplicates credentials, catalogs, and settings cards, and forces users to reselect models when adopting Messages. The deepseek-official identity keeps those user choices stable.
Delegate the new route to pi-ai or the Anthropic SDK. Both provide maintained protocol implementations, but the requested direct adapter needs DeepSeek-specific configuration, attachment policy, credential resolution, and retry ownership. A small stream translator with a maintained SSE parser keeps these responsibilities explicit; the library-backed adapter remains available independently.
Persist complete native responses or flatten thinking into text. Full responses duplicate logged content and complicate truncation alignment. Flattening changes the next model input. Minimal aligned replay metadata preserves the missing protocol information without a new Session format.
Always rewrite the top-level system prompt. This discards the cache-preserving native update path on capable routes. Explicit capability selection keeps that path while retaining ordinary replacement for other endpoints; converting system instructions to user text would also lose their priority.
Consequences
The package owns wire validation, stop-reason mapping, cancellation, and error classification, so protocol changes require adapter maintenance. User and tool-result input follows the saved-input compatibility rule; other unsupported content and incomplete streams fail explicitly. The existing retry consumer owns retries; the existing assembler drops incomplete tool calls at the output limit. Messages serves the shared base, Web, and standalone first-party compositions. Explicit endpoint overrides must support Messages.
Verification covers wire fixtures, real Loader composition, per-file unit coverage, recorded Session replay with unknown replay versions, a Web Messages Session replay, and credential-gated text, thinking, tool continuation, image, and cancellation requests. Live gateway checks establish compatibility with the configured gateway; they do not establish compatibility with every Anthropic proxy.
中文
问题
Messages 以原生协议字段表示思考、签名、工具调用、工具结果和累计用量。仅替换端点或压平助手历史会丢失后续工具轮次需要的信息。
决策
DeepSeek 适配器在唯一的 deepseek-official 路由和 llm-deepseek 设置命名空间下提供 Messages。单协议说明拥有传输范围。PreparedAdapterCall 固定端点、凭据引用与模型能力；重试保留该代配置，后续调用读取新配置。
适配器遵循 DeepSeek 兼容文档 和 Anthropic 流协议。pi-ai 的 Anthropic 实现为相邻用户消息、累计用量、工具参数分片和可选思考签名的处理提供参考。DeepSeek 通过 output_config.effort 设置思考强度；Anthropic 思考 token 预算不控制 DeepSeek 思考强度。适配器转发显式 temperature 值；DeepSeek 在启用思考时接受该参数但忽略其值，因此调用方可以保留已有思考配置。
助手内容块保留持久化的模型可见内容。带版本的 ReplayEnvelope 仅保存协议格式、模型标识、对齐的块类型以及内容块未包含的签名。同模型续接原样恢复签名，包括空签名；外部历史不生成虚构签名。不可用的元数据遵循现有回放降级规则：请求省略签名并记录警告，保留持久化内容；Messages 无法表示历史工具参数时使用空输入兜底。提供者回放数据对循环保持不透明，同时能够随 Session 持久化和内容块裁剪保留。
适配器优先使用确定性请求图片的 Files 引用，并管理上传缓存、刷新、配额恢复与附件省略。Files 客户端遵循精确 /v1 根地址规则并发送必需的 beta 标头。缓存 id 按解析后的 Files 根地址与凭据限定作用域，因此等价的 /v1 与无版本根地址共用上传。元数据不含过期时间，因此本地复用以原始上传时间为界，不断言远端删除。Files 解析失败会按独立内联图片预算重建完整请求；调用方取消会停止它。图片策略在请求和 token 计量中保留 128 MiB 保留图片预算、20 MiB 内联 base64 预算及最旧前缀省略。
成功 HTTP 响应之后的 JSON 语法错误不足以证明传输故障。Files 解码复用已有的 INVALID_RESPONSE code 并补充操作上下文，不将其改标为 TRANSPORT 或添加重试；错误字段由 provider README 维护。
系统提示词更新在端点与模型显式声明支持时，使用现有路由能力。Messages 保留初始顶层 system，在对应的用户或工具结果轮次之后，将后续快照发送为原生 system 轮次，保留此前发送的前缀。这个位置不同于循环先 system、后 user 的接纳顺序；序列化既不改写持久化日志，也不改变对话轮次的顺序。未声明能力的路由将最新快照归并到顶层，直接压缩调用也如此。仅凭协议或模型名称推断能力并不充分，因为支持情况和更新语义取决于实际部署的端点。
Web 显示 DeepSeek，并提供端点与凭据引用。没有端点覆盖时，解析使用 https://api.deepseek.com/anthropic。覆盖地址必须支持 Messages。适配器遵循精确 /v1 根地址规则，不从其他类似版本的后缀推断兼容性。单一模型目录公布各条目声明的能力。
适配器在原生序列化后使用现有请求扩展注册表，并在 HTTP 2xx 后、读取流之前接受已捕获贡献。会话日志投递和插件清单仍由原有包负责，并留在模型输入之外。辅助 web 搜索提供方保留独立的端点、请求与设置。
考虑过的替代方案
独立的 Messages 提供方身份。 这会重复凭据、目录与设置卡，并迫使用户在采用 Messages 时重新选择模型。deepseek-official 身份使这些用户选择保持稳定。
把新路由委托给 pi-ai 或 Anthropic SDK。 两者均提供持续维护的协议实现，但所需的直接适配器需要 DeepSeek 专属配置、附件策略、凭证解析和重试所有权。小型流转换器配合持续维护的 SSE 解析器使这些职责保持明确；库实现适配器仍可独立使用。
持久化完整原生响应，或把思考压平为文本。 完整响应重复已记录内容，并使截断对齐复杂化。压平会改变下一次模型输入。最小化的对齐回放元数据可以保留缺失的协议信息，无需新增 Session 格式。
始终重写顶层系统提示词。 这会丢弃支持该能力的路由上能够保留缓存的原生更新方式。显式选择能力既保留该方式，也为其他端点保留普通替换；将 system 指令转成 user 文本还会失去其优先级。
结果
该包负责协议校验、停止原因映射、取消和错误分类，因此协议变化需要维护适配器。用户与工具结果输入遵循已保存输入兼容规则；其他不支持的内容和不完整的流会明确报错。现有重试消费者负责重试；现有装配器在输出达到上限时丢弃未完成的工具调用。Messages 服务共享 base、Web 和独立的官方组合。显式端点覆盖必须支持 Messages。
验证覆盖协议夹具、真实 Loader 组合、逐文件单元覆盖率、已记录 Session 回放与未知回放版本，Web Messages Session 回放，以及凭证控制的文本、思考、工具续接、图片和取消请求。真实网关检查证明与已配置网关的兼容性，不能证明与所有 Anthropic 代理兼容。