description: "面向用户与维护者的 DeepSeek chat-completions 适配器说明：配置 deepseek-official 路由、thinking 与图片输入。" kind: "package-reference"

@xfcodeai/dsh-llm-deepseek

English | 中文

概述

使用本包可通过 deepseek-official 路由流式调用 DeepSeek 模型，包括配置 thinking 与推理强度、向视觉模型输入图片，以及查看建议性模型目录。端点、凭据、目录与 thinking 策略均按请求解析，因此有效的用户设置更改会在下一个请求生效，无需重启进程。它适合 DeepSeek 官方 API 或 OpenAI 兼容网关；由于路由名不同，可与 pi-ai 包并用。

目录

• 使用本包
• 理解实现
• 进一步探索
• 模型体验
• 已知限制与延期工作
• 开发备注

使用本包

当组合需要通过 harness LLM（大语言模型）服务流式调用 DeepSeek 模型时挂载本插件。它注册唯一的 deepseek-official 路由，并按请求解析连接事实，因此组合条目加可选用户设置分节即可驱动整个适配器。

何时选择

当部署面向 DeepSeek 官方 API（可选地通过 baseURL 指向的 OpenAI 兼容网关）时选择本适配器。当同一组合还要通过 pi-ai 目录路由其他提供方或手工声明的网关时，选择 dsh-llm-pi-ai；两个适配器可以同时挂载，因为它们的路由名不冲突。为 deepseek-official 注册任何其他适配器会以 DUPLICATE_ADAPTER 失败。

最小配置

- name: '@xfcodeai/dsh-llm-deepseek'
  config:
    apiKeyEnv: DEEPSEEK_API_KEY  # credential reference, resolved per request
    baseURL: https://api.deepseek.com # optional; $DEEPSEEK_BASE_URL then this default
    reasoningEffort: high        # optional; off | low | high | max
    maxTokens: 256000            # optional per-request output cap
    maxRequestFilesBytes: 134217728
    maxInlineRequestImageBytes: 20971520
    maxImagesPerRequest: 600
    filesApiTimeoutMs: 60000

请求用 provider: deepseek-official 选择路由；模型 id 原样传到协议，因此新增 DeepSeek 模型无需重新注册。省略 models 时公布支持文本和图像的 deepseek-flash 和 deepseek-v4-flash-vision-exp，以及仅支持文本的 deepseek-v4-flash 和 deepseek-v4-pro，各自的上下文窗口均为 1,000,000 token。显式列表会替换这些默认值，未列出的模型 id 仍作为纯文本路由原样通过。包括模型发现工具在内的客户端可通过 ctx.llm.listModels('deepseek-official') 读取这些建议性条目。支持图片的条目可把 imagePixelBudget 设置为正整数或 low，也可以设置 imageMaxBytes。当端点把 messages 中任意位置最新的 system 消息读作完整的有效系统提示词时，条目可以声明 systemPromptUpdate: in-history；适配器会在已解析模型与已准备调用上报告该模式，agent loop（智能体循环）随后把变化后的提示词追加到已缓存历史之后，而不是改写开头的 system 消息（决策规则）。默认的 deepseek-flash 条目声明该模式；其他模型需通过 models 显式声明，in-history 以外的任何值都会在加载时以 llm-deepseek: catalog model "<id>" systemPromptUpdate must be "in-history" when present 失败。

| 字段 | 默认值 | 含义 | |---|---|---| | apiKeyEnv | DEEPSEEK_API_KEY | 按请求解析的凭据引用：先经凭据 seam，再到环境变量 | | baseURL | https://api.deepseek.com | 端点基址；设置了 $DEEPSEEK_BASE_URL 时优先 | | thinking | enabled | 部署策略；disabled 把所有请求锁定为 off | | reasoningEffort | high | 默认强度：off、low、high 或 max | | maxTokens | 256,000 | 单次请求输出上限；模型自身上限与显式请求值优先 | | defaultContextWindow | 1,000,000 | 无精确值模型的容量回退 | | models | V41 Flash + V4 Flash + V4 Pro + V4 Flash Vision Exp | 供发现消费方查看的建议性目录 | | streamIdleTimeoutMs | 300,000 | 单次流读取未完成的最大提供方空闲时间 | | maxRequestFilesBytes | 128 MiB | 按最旧优先卸载前保留的请求图片字节高水位 | | maxInlineRequestImageBytes | 20 MiB | 独立的 base64 回退高水位 | | maxImagesPerRequest | 600 | 保留请求图片数量的高水位 | | imageOffloadByteQuantum | 64 MiB | Files 模式最旧前缀移除量子 | | inlineImageOffloadByteQuantum | 10 MiB | 内联模式最旧前缀移除量子 | | imageOffloadCountQuantum | 20 | 数量超限移除量子 | | filesApiTimeoutMs | 60,000 | 每张图片 Files 解析截止时间 | | fileExpiresAfterSeconds | 604,800 | 请求的上传图片生存期 | | fileRefreshMarginSeconds | 3,600 | 低于此剩余生存期时替换 id | | fileQuotaCleanupBatch | 100 | 配额重试前删除的、归 harness 所有的最旧文件数 | | retryPolicy | normal，20 次重试，500 毫秒到 10 秒 | 由 dsh-llm-retry 执行的提供方自有重试策略 |

生成的配置目录是每个受支持字段及其 JSDoc 的穷尽式真源。

带 thinking 与图片的流式调用

支持图片的路由会在自身像素与字节预算内把每个持久引用解析为确定性请求版本。imagePixelBudget 接受正整数或 low；省略时使用总计 640,000 像素，low 使用总计 512×512 像素，imageMaxBytes 默认为 1 MiB。带 alpha 的图片使用 effort 0 的 WebP，不透明图片使用 JPEG，并采用 85/75/60 质量阶梯；全部候选都超过目标时保留最小输出。每张保留图片前都有文本，注明完整附件 id 与实际请求尺寸。当前文件系统可以映射附件提供方的宿主对象时，该文本还携带只读执行世界路径与可写副本使用的扩展名。纯文本与未列出路由接收稳定附件占位符，而持久历史继续保留图片引用。

适配器通常通过 DeepSeek Files API 上传这些确切请求字节，并发送 file-id 块。文件解析失败或超时会用相同请求版本的 base64 data URL 重建整份 chat 请求；一次请求绝不混用 file id 与内联图片。缓存 id 按端点与 API key 限定作用域，在到期前刷新，根据提供方的陈旧文件错误失效，并通过带等待方局部取消的 singleflight 解析。配额失败会先删除一批配置数量的最旧 harness 文件，再重试一次上传。

Files 模式通过 maxRequestFilesBytes 与 maxImagesPerRequest 限制保留请求版本；内联回退有独立 base64 预算。两种模式都按配置的字节或数量量子移除最旧前缀。每张省略图片都有自己的模型可见占位符，包含显示名或附件 id，以及可用时的规范化尺寸、媒体类型与当前只读路径。分阶高水位策略避免每新增一张图片都改写旧请求前缀。

reasoningEffort 选择公布的默认值。当部署策略允许 thinking 时，确切模型元数据会按顺序公开 off、low、high 与 max 强度及选择指引。low、high 与 max 启用 thinking 并以 reasoning_effort 序列化，适配器自有的 off 则发送 thinking.type: disabled。不支持的取值会在网络 I/O 前以 UNSUPPORTED_REASONING_EFFORT 失败；thinking: disabled 会在插件加载时拒绝任何非 off 强度。purpose: 'session-title' 的请求会强制关闭 thinking，把有界输出留给可见标题文本。

动态配置

连接事实通过可选 settings 与凭据 seam 每次操作重新读取一次。用户设置文档中的 llm-deepseek: 分节无需重启即可覆盖任何字段；违反 schema 之外约束的快照会保留最后有效事实并记录失败。API 密钥从提供端点、图片与 Files 策略及空闲预算的同一快照按流调用解析，因此被拒绝的设置代际不会贡献其中任何事实。图片请求在请求时解析附件服务，因此加载顺序不会冻结图片可用性。

提供方专用请求字段

存在 ctx.deepseekLlmApiExtensions 时，适配器会在 fetch 前根据确切序列化基础请求准备已注册顶层字段。准备或字段冲突在 HTTP 前失败；2xx 响应后，适配器会在消费 SSE（Server-Sent Events）前接受每项已捕获贡献。传输与非 2xx 失败不会接受它们。随产品交付的组合用它提供可选增量 dsh_session_log 字段和默认启用的活跃 dsh_plugin_packages 清单；两者都留在模型输入之外。

失败与恢复

非 2xx 响应以稳定 code 失败：AUTH（401/403）、QUOTA、RATE_LIMIT、CONTEXT_WINDOW_EXCEEDED、INVALID_REQUEST、SERVER 以及其他情况的 HTTP_<status>；响应前传输失败抛出 TRANSPORT，调用方中止抛出 ABORTED，流空闲超时抛出 TIMEOUT。请求扩展准备、字段冲突或 2xx 后接受失败使用 REQUEST_EXTENSION。当提供方未指出 file id 时，规范化图片拒绝会列出所有可能附件及其持久位置。陈旧文件拒绝会使点名映射（或该次尝试使用的全部映射）失效，并允许一次替换 chat 尝试。协议违规抛出 STREAM_CLOSED 或 MALFORMED_RESPONSE；不带内容块的终止 stop 变成 EMPTY_RESPONSE，默认重试策略会重试它。任何位置都没有密钥的请求以 MISSING_CREDENTIAL 失败；格式错误的凭据以 INVALID_CREDENTIAL 失败，并点名需要修复的引用——绝不包含密钥的任何部分。

理解实现

本节解释适配器背后的设计；可观察行为已在使用本包中完整说明。

设计理念

插件建立在一个显式解析步骤与一条注册事实之上。resolveAdapterOptions() 是从原始配置到已校验连接事实的唯一路径，适配器通过 thunk 每次操作重新读取这些事实——基址、目录、请求默认值、图片与 Files 策略及空闲预算都会作用于下一个请求，而进行中的流保持其启动时的事实。注册时捕获的唯一事实是重试策略：解析值变化时，插件会在一个同步区段内原位重新注册路由，因此任何请求都观察不到空档。

源码地图

| 文件 | 职责 | |---|---| | src/index.ts | 插件入口：Config schema、按请求解析、settings 与凭据接线 | | src/adapter.ts | DeepSeekAdapter：模型解析、图片投影、Files 回退、带空闲超时的流式调用 | | src/file-store.ts + src/files-api.ts | 限定作用域的上传缓存、到期、陈旧 id 恢复、配额清理与远程文件操作 | | src/serialize.ts | 协议序列化：thinking 默认值、Files 或内联图片块、历史规则 | | src/sse.ts | 直接 fetch 流的 eventsource-parser SSE 分帧 | | src/translate.ts | 把 SSE 载荷翻译为 harness StreamChunk 值；工具调用的 id 与 name 是身份，后续分片重复发送空串或 null 时保留已建立的值 | | src/types.ts | 上述模块共享的协议级类型 |

协议流程

一次 stream() 调用通常发一条 chat 请求：解析确定性请求图片、优先使用 Files id、准备所有已注册顶层请求扩展、向解析后的 baseURL 发起 fetch、在 HTTP 2xx 后接受扩展事务，并把 SSE 流翻译为 harness 协议。文件解析失败会让首条 chat 使用内联模式；提供方的陈旧文件响应允许一次替换尝试，且替换解析失败时也使用内联模式。每条 chat 与 Files 调用都在模型输入之外携带共享归因和稳定匿名用户 id，会话调用还携带 session id。推理历史会按需序列化回请求，缓存计量则把 DeepSeek 的缓存命中指标映射进 harness 用量桶。

进一步探索

当包级约定不够用时阅读以下页面。它们从服务约定逐步进入孪生适配器、重试执行器与共享类型。

• dsh-llm 服务——本适配器注册其上的提供方无关服务。
• llm-pi-ai 适配器——服务其他提供方与网关的库实现孪生。
• LLM 流式子系统——StreamChunk 协议与适配器约定。
• llm-retry——应用本适配器 retryPolicy 的重试执行器。
• DeepSeek 请求扩展——提供方专用顶层字段的生命周期与接受语义。
• 会话日志上传——可选的增量 dsh_session_log 贡献。
• 插件包清单——默认启用的 dsh_plugin_packages 贡献。
• 孪生 LLM 适配器——为什么 DeepSeek 交付两个结构不同的适配器。
• 强制应用归因标头——每个提供方请求携带的身份。

模型体验

DeepSeek 请求

模型看到什么

所选 DeepSeek 模型会收到 harness 系统提示词、消息历史、工具 schema、停止序列与调用配置（maxTokens、reasoningEffort、temperature），不包含适配器撰写的提示词散文。提供方专用请求扩展字段留在模型输入之外。视觉模型通常接收 Files API 引用形式的用户与工具结果图片，其旁带附件句柄和请求预览尺寸。当前执行文件系统可以映射附件提供方的宿主对象时，它还会收到规范化对象路径；描述符会把该副本标记为只读，并警告规范化可能缩放或重新编码上传内容。Files 解析失败时，全部保留图片改用内联 data URL；超出预算的较旧图片则在占位文本中保留当前请求已解析的访问方式。此前 assistant 轮次的推理内容会原样传回，无论该轮次是否调用了工具。

Token 影响

提供方分词决定精确的文本与图片 token 输入。适配器声明按路由的 imageRequestPricing：它根据持久记录中的字节长度复现最旧优先的图片 offload，并按投影后的尺寸使用公开的视觉计量规则（14 px patch 网格、3:1 降采样、544×544 放大下限、单图 1024 token 上限）为每张保留图片计价。这使 token 计量服务可以在请求发出前为图片压力定价；上报的 usage 仍是权威值。推理回传会把每个推理轮次的思维链带进后续请求，而丢弃超预算图片会避免再次为它们付费。可用时报告缓存读取用量。totalTokens 是精确的 prompt_tokens + completion_tokens 汇总值；提供方给出的 total_tokens 不一致时省略该值。

KV Cache 影响

未改变的已组装前缀有资格获得 DeepSeek 缓存复用，本适配器会在用量中报告。确定性的请求图片字节并不意味着完整前缀固定不变：执行世界路径变化会改写历史描述符文本，刷新上传会替换 file_id，Files 到 base64 的回退也会改变图片表示。这些变化以及模型路由、提示词、schema、历史或图片预算变化，都可能从首个受影响 token 起阻止复用；推理回传在每个推理轮次上追加内容。在声明了 systemPromptUpdate: in-history 的目录条目上，同一请求序列延续期间的系统提示词变化会追加到已缓存历史之后，因此直到该历史末尾的前缀仍可复用；工具 schema 变化仍会从第一个改变的 token 起阻止复用。

DeepSeek 响应

模型看到什么

推理、文本与原始字符串工具参数会被翻译为 harness 分片，供 loop 记录并组装。

Token 影响

生成的 token 遵循请求中记录的推理强度与 maxTokens；只有 loop 保留的块会影响后续输入。

KV Cache 影响

loop 保留的响应块会追加到下一个请求，并保留其更早的可复用前缀；被丢弃的块不再有后续缓存影响。更换提供方或模型会选中不同的缓存域。

已知限制与延期工作

这些限制说明适配器在哪里停止、由未来工作接续。它们是当前包约束，不是通用 DeepSeek 对比或任务积压。

• 设置中的 models 列表会整体替换组合列表——设置层按字段合并，数组只算一个字段；按条目合并目录需要带键的形状。

• 不映射 tool_choice——不属于核心词汇（与 pi-ai 孪生共享）。

• 请求使用原始 fetch，而非 @cordisjs/plugin-http——没有共享代理或拦截配置。

• 跳过插件新增的内容块类型——核心文本与受支持图片块会被序列化，空工具输出以字面量 (no output) 过线。

• 图片是仅用于输入的持久附件——不支持直接外部 URL 与 assistant 图片输出；DeepSeek 输入通常使用 Files API，仅在单次请求恢复时使用内联 base64。

• 默认目录预注册 deepseek-flash 及其文本、图片和历史内更新能力，不探测网关可用性。网关开放该 ID 前，请求可能以 INVALID_REQUEST 失败。配置 DEEPSEEK_API_KEY 和支持该 ID 的网关后，设置 DEEPSEEK_FLASH_E2E=1 可启用本包 e2e 测试文件中的 Chat Completions 协议验证。

• 默认请求图片投影限制为 640,000 总像素，低于提供方约 1300×1300 的处理预算，可能丢弃可用细节。每个模型的 imagePixelBudget 可以覆盖默认值。更改默认值会改变请求内容，需要单独验证快照（决策）。

开发备注

本开发备注是不具权威性的工作上下文：尚未决定的探索方向与维护者备注。已交付的行为与既定理由以上文、包代码和相关 Agent Note 为准。

• OpenRouter 专属应用归因标头延期到未来显式 OpenRouter 适配器或模式；OpenAI 兼容网关请求只携带共享归因基线。
• off 推理强度绝不会以 reasoning_effort: 'off' 过线；它序列化为 thinking: { type: 'disabled' } 并省略该字段，从而对拒绝未知强度取值的网关保持协议拼写有效。

运行时不变式： 不发布伴生入口。本包没有独立事件序列或可变数据关系，相关约定在所属 seam 强制执行。