DeepSeek Harness 提供方端点询问(Model Discovery)设计解析:以 settings namespace 为键的一次性草稿探测

原创2026-09-21 19:52:02978 阅读
文章标签:人工智能AI AgentAgent 框架DeepSeek

DeepSeek Harness 提供方端点询问(Model Discovery)设计解析:以 settings namespace 为键的一次性草稿探测

DeepSeek Harness(Everything is a Plugin)的 dsh-llm 服务为配置界面提供了一套「询问草稿中的提供方端点」的能力:当用户正在表单中输入一个尚未保存的网关 baseURL 与 API 密钥时,插件可以代表这个草稿向端点发起一次 GET 询问「你服务哪些模型」,并把结果以候选列表交还给用户挑选采纳。本文基于 Agent Note 原文 并结合 dsh-llm 与 dsh-llm-pi-ai 的源码实现,完整讲解该 seam 的问题背景、以 settings namespace 为键的决策、协议层携带机密的安全边界、支持的协议与响应解析规则,以及可验证的测试覆盖。

背景问题:路由成为声明之后,端点不再自我说明

在一次架构改动(pi-ai 声明式提供方目录)之后,pi-ai 路由从「catalog 查表」变成了「一份声明」:适配器不再把人限制在已安装的 catalog 里——这正是那次改动的目的。但代价是,没有任何东西告诉用户某个端点究竟服务什么模型。接入一个兼容网关的人,必须先知道它的模型 id 才能完成配置,而 OpenAI 与 Anthropic 兼容端点恰恰会通过各自协议的模型列表路由公布这份信息。

显而易见的答案——后台刷新的运行时动态 catalog——随下层一并被拒绝了:

  • 它会把路由的模型列表变成需要缓存、失效语义与离线路径的外部可变状态;
  • 而产品需求要窄得多:只需要一次性的询问,其答案由用户采纳进 settings.yaml,从而让 settings.yaml 始终是决定路由服务内容的唯一真源。

更麻烦的是,被问的对象还不存在:正在新增的提供方没有路由、没有已存 profile、也没有已存凭据;端点与密钥都是用户尚在输入的表单值。而现有的每个 LLM Service Definition 操作都以已注册的提供方路由为键,因此没有一个能承载它。

核心决策:询问以 settings namespace 为键

为什么不以提供方路由为键

与其他每个 LLM Service Definition 操作对称、也能让请求省去端点,看起来顺理成章。但催生该功能的场景——新增提供方——没有路由,于是这个操作只对已配置好的提供方可用,而它们恰恰最不需要它。这是被明确否决的方案之一(见原文 Alternatives considered)。

最终决策是:询问以 settings namespace 为键。理由在源码注释中同样被记录(packages/llm/llm/src/types.ts):

Configuration surfaces send the draft a user is still editing, so the request carries the endpoint and credential directly instead of naming a route: a provider being added has no route to name.

配置界面已经从可配置提供方目录(configurable-provider directory)里拿到了 namespace,因此它天然是界面与插件之间的握手键;而一个正在被新增的提供方没有路由可点名。从源码结构看,这个选择同时刻意排除了「枚举已注册 namespace」的能力:界面询问不了时,会从拒绝(NO_DISCOVERY)里知道这一点,而不是维护一份无人消费的列表。

两个公开操作

注册表实现在 packages/llm/llm/src/index.ts:

registerModelDiscovery(
  settingsNs: string,
  discover: (request: LlmModelDiscoveryRequest, signal?: AbortSignal)
    => Promise<readonly LlmDiscoveredModel[]>,
): () => void
  • 每个 namespace 只有一份 offer,重复注册抛 DUPLICATE_DISCOVERY,空 namespace 抛 INVALID_DISCOVERY;
  • 注册随 fiber dispose(资源释放),生命周期不超出创建它的 fiber;
  • 对应的发起方是 ctx.llm.discoverModels(settingsNs, request, signal?)(index.ts),它先校验「provider 与 baseURL 至少有一个非空」(否则 INVALID_DISCOVERY),再委托给注册的回调,最后做归一化:丢弃空 id、去重、逐字段复制而不凭空补容量。

草稿请求与候选回复的类型定义

LlmModelDiscoveryRequest 在 packages/llm/llm/src/types.ts:

字段 可选 含义
provider 是 草稿正在编辑的既有路由;适配器已描述的路由直接由适配器自己的注册表作答、完全不联网
baseURL 是 要询问的端点;适配器未描述的路由必须提供它
api 是 端点所说的线上协议(wire protocol),草稿点名时带上
apiKey 是 仅限本次询问的凭据;harness 永不存储它

操作侧在 LlmModelDiscoveryOperation 上附加 signal?: AbortSignal 承载调用方取消。

LlmDiscoveredModel(types.ts)除 id 外每个字段都可选,因为大多数列表只公布一个 id:

interface LlmDiscoveredModel {
  id: string            // 端点接受的模型 id
  name?: string         // 端点提供的可读名称
  contextWindow?: number
  maxTokens?: number
  inputModalities?: readonly ModelModality[]
}

回复是候选(candidates)而非 catalog:采纳其中一条的界面仍要补上适配器所需的容量(比如 reasoning 能力、模态声明等)。目录成员身份是建议性的,绝不改变路由与请求校验——这与 LlmModelInfo 的 advisory 语义一致(types.ts)。

安全边界:第三个承载机密的载荷

llm.discoverModels 会把同一份草稿送过协议层。它的 apiKey 是第三个、也是最后一个可承载机密的载荷(另两个是 settings.update/mutate 与 credentials.set),且绝不被存储或回显。原文特别说明的边界,在实现里逐条成立:

  • 宿主发起 GET、回报结果:Connection 用与完整 Host API 相同的会话认证该方法——匿名调用者绝不能获得「让宿主向任意 URL 发起 GET 并回报结果」的探测能力。
  • 每一种拒绝都折叠为 model-discovery-failed:在类型层面它是 RemoteErrorDetailsMap 里的 llm/model-discovery-rejected,message 是适配器自己的文本,details 点名被询问的端点(settingsNs、baseURL),绝不点名所提供的凭据。实现见 remoteDiscoverModels。
  • apiKey 随客户端外发信封同行,subscribeEnvelopes() 观察者看得到;把那个抽头脱敏是整个配置面的改动,不该由这一个方法独自决定(原文明确承认这是刻意保留的权衡)。

在 discovery.ts 的实现中,凭据还有更细的分层规则:

  • 表单中新键入的密钥优先于已存凭据:只有草稿没有 apiKey 时才会惰性解析已存凭据(stored?.resolveApiKey()),因此键入密钥失败不会牵连一把本次询问用不上的已存密钥;
  • catalog 路由作答时完全不触碰凭据——只有真正要联网的分支才会走到凭据解析;
  • 已配置且具名的路由会在 Host 内读取已存凭据和部署方持有的 profile headers:凭据是只写的,精选的 Models 页面不编辑 headers,因此页面草稿无法重建两者;
  • usableProbeKey 会在构造 header 前拒绝不可表示的密钥(空、或含 HTTP header 无法承载的字符),避免把本地确定性错误误报成「网络不可达」;
  • profile headers 最先装入,固定协议 headers、键入或已存的协议凭据以及 Harness attribution(attributionHeaders(),见 attribution.ts)随后以大小写不敏感方式赢得相应冲突。

dsh-llm-pi-ai 的落地:协议、URL 归一化与响应解析

dsh-llm-pi-ai 应用 dsh-llm-pi-ai README 记录的列表路由、认证、URL 归一化、响应格式与元数据规则。核心实现全部在 packages/llm/llm-pi-ai/src/discovery.ts。

受支持的协议集合(刻意很窄)

const LISTABLE_PROTOCOLS: ReadonlySet<string> = new Set([
  'anthropic-messages',
  'openai-completions',
  'openai-responses',
])
  • OpenAI 系:GET {baseURL}/models,bearer 认证;
  • Anthropic Messages:x-api-key + anthropic-version: 2023-06-01,原生 GET /v1/models?limit=1000,且最多读取一页、不跟随 has_more(第一页之外需手工添加);
  • 没有文档化列表约定的协议以 DISCOVERY_UNSUPPORTED 回答,让界面回退到手工填写,而不是把猜错的响应字段报成一个空提供方——这正对应原文「询问每一种 pi-ai 协议」方案的否决理由:Google 的字段集合与 Azure 的请求约定不同(Azure 用 api-key header 且需要 api-version 查询参数),Codex 使用 OAuth,猜测会无法与「提供方没有模型」区分。

baseURL 按前缀处理,保留部署路径段

function listingUrl(baseURL: string, api: string): string {
  const base = baseURL.replace(/\/+$/, '')
  if (api !== 'anthropic-messages') return `${base}/models`
  const root = base.endsWith('/v1') ? base.slice(0, -3) : base
  return `${root}/v1/models?limit=${String(ANTHROPIC_MODEL_LIMIT)}`
}

baseURL 被当作前缀而非待解析 URL,因此 https://gateway.example/openai/v1 这类部署路径段会保持不变,不会在 URL 解析中丢失。Anthropic 的列表 URL 接受带或不带末尾 /v1 的 API 根地址(网关文档两种写法都会发布),只有这个列表 URL 归一化该段;模型请求收到的仍是配置原样的 baseURL。

响应格式:标准数组与富信息对象

readListing 接受两种格式(discovery.ts):

  1. 标准 data 数组({ data: [...] })——优先,存在时采用;
  2. 富信息 models 对象({ models: { <id>: {...} } })——每个键即请求侧接受的模型 id,嵌套 id 仅在键为空时作为回退(网关可能在键下放规范 id 而非请求别名);只有对象值的条目是模型,原始类型属性被忽略(可能是目录元数据)。

容量字段做了大量拼写兼容归一化,例如 contextWindow/context_window/context_length/max_input_tokens/limit.context,输出上限取 maxOutputTokens/max_output_tokens/maxTokens/max_tokens/limit.output/top_provider.max_completion_tokens——Anthropic 的 max_input_tokens 与 max_tokens 会进入相同容量字段。没有可用 id 的条目被跳过而非让整个询问失败(一行坏数据不应剥夺用户看到其余目录的权利),缺失的显示名回退到该请求 id,使 Web 表单总能拿到完整可读的行。

四兆字节上限:声明长度只作善意提示

端点是用户自己填的 URL,因此回复在四兆字节上限下读取,且上限落在实际收到的字节上:

  • 先看声明的 content-length,作为善意提示——诚实服务器可在不传输任何字节的情况下被拒绝;
  • 但绝不把它当作边界:流式(未声明长度)回复由累积读取字节强制约束,一旦超限立即抛 DISCOVERY_FAILED。

这与 dsh-web-fetch 面对自己的调用方提供 URL 时所用的两段式模式一致(readBounded)。

其他行为细节

  • 草稿未选协议时按 openai-completions 询问:这是网关最可能说的一种形态,代价是误导向的端点会以 401 呈现为凭据问题,手工填写仍是出路;
  • 提供方失败与网络失败是独立的询问结果:非 2xx 响应点名状态码(401/403 额外提示检查 API key),fetch 抛错则报「could not reach <url>」,调用方取消折叠为 ABORTED;
  • 不可达、非 JSON、非列表响应分别给出可诊断的错误文本;
  • 配置错误在询问之前拦截:Profile 解析拒绝 Fetch 无法表示的名称与值(adapter.spec.ts 覆盖),格式错误的部署 header 会在询问前以配置错误报告。

为什么不用 pi-ai 自己的 refresh 机制

pi-ai 提供了 createProvider({ fetchModels }) 加上 Models.refresh() 与 ModelsStore,而下层本来就在构造 pi-ai Provider 对象。原文明确拒绝了这条路径:

  • 把询问接到它们上面,意味着每问一次就要构造一个用完即弃的提供方与集合;
  • 而 ModelsStore 的全部目的——跨运行持久化 catalog——恰恰与「settings.yaml 拥有 catalog」的决定相抵触;
  • 而且它什么也换不来:没有任何一个 pi-ai 内置提供方实现了 fetchModels,因此 HTTP 调用及其响应解析无论如何都是本包的代码;直接 fetch 才如实说出正在发生的事。

其他被否决的替代方案

方案 否决理由
以提供方路由为键 与每个 LLM Service Definition 操作对称,但催生该功能的场景没有路由;操作只对已配置好的提供方可用,而它们最不需要它
把能力挂在 LlmAdapter 上 适配器要经由路由注册才能抵达,问题相同;且会让一个适配器实例回答它并不服务的端点的问题
让 Host 读取整个已存 profile 而非接受草稿 新增提供方必须先保存一份不可用的配置;端点已改却尚未保存的表单会静默地去询问旧地址。草稿仍是端点和协议的权威来源(Host 侧窄例外:只写凭据与部署配置的 profile headers)
询问每一种 pi-ai 协议 基于响应相似性的覆盖会显得武断,让猜错的响应与「提供方没有模型」无法区分
用 response.text() 缓冲再判断长度 更简单,但上限会在字节到达之后才生效,而端点是用户随手填的任意 URL

后果与取舍

收益

  • 接入网关的人可以直接问它服务什么,不必翻它的文档;答案以候选形式抵达,由用户自己挑选,而不是被背着写进配置;
  • 缺少 scheme、不支持的 scheme 或 URL 格式错误都会直接在字段处失败,不发起 Remote 调用;localhost、IPv4 与 IPv6 字面地址以及自定义端口仍然有效(测试固定了这些行为);
  • 提供方失败与网络失败是独立的询问结果;
  • 端点公布更丰富元数据时,采纳候选会把 id、名称、上下文窗口与最大输出 token 数填进 Web 的可编辑行;
  • 已配置的企业网关会为询问与模型请求使用同一组部署 headers 和 Harness User-Agent,无需给浏览器协议增加 header 注入字段;
  • seam 因此多了一个刻意保持很小的注册表:每个 namespace 一份、不存储、生命周期不超出 fiber。

代价

  • 协议层多了第三个承载机密的载荷,配置面的只写接口从两个方法变成三个;
  • 发现覆盖范围仍按协议而非按提供方划分,使用不受支持请求约定的端点仍须手工填写;
  • 由于没有任何环节会重跑该询问,模型列表的新鲜度依旧只到最近一次编辑为止——这与下层刻意做出的取舍是同一个。

测试覆盖:从注册表到完整 UI 链路

  • packages/llm/llm/tests/topology.spec.ts 覆盖注册表本身:每个 namespace 一份、随 fiber dispose、丢弃重复与不可用 id 且不凭空补容量的归一化、NO_DISCOVERY/INVALID_DISCOVERY 两种拒绝、只有 provider 时直接以空列表作答(适配器可能知道它而无需端点),以及 model-discovery-rejected 的 Remote 映射(message 透传、details 含 settingsNs 与 baseURL)。
  • packages/llm/llm-pi-ai/tests/discovery.spec.ts 用本地 HTTP 服务器驱动探测:标准数组与富信息对象的每种受支持元数据拼写、Anthropic 原生路径与容量字段、不同于嵌套规范 id 的路由键、名称回退、被保留的部署路径、无凭据、已配置路由提供自己的已存凭据与 headers 而键入密钥无需解析已存凭据便可压过它、catalog 路由完全不解析凭据即作答、被丢弃的行、401/403 与服务器故障之别、非列表与非 JSON 响应、不可达端点、调用方取消、不支持的协议,以及尺寸上限的「声明长度」与「流式」两种形态。
  • packages/llm/llm-pi-ai/tests/loader-composition.spec.ts 通过 Loader 启动 settings 与 credentials,证明仅配置在 settings 中的 headers 会抵达 GET /models,且请求所持有的 headers 赢得冲突。
  • adapter.spec.ts 拒绝 Fetch 无法表示的 profile headers;dynamic-config.spec.ts 证明 settings 写入会报告该配置错误,同时上一组可用路由仍继续服务。
  • packages/client/connection/tests/node-half.host.spec.ts 固定 llm/discoverModels 的 /api 承载注册(L271、L597)。
  • 设置页的组件测试与构建后 Web 测试则验证:完整草稿抵达 Remote、格式错误和非 HTTP(S) 的自定义提供方 URL 不会发起请求、带自定义端口的 localhost 与 IP 字面地址仍然有效、提供方失败与 URL 错误保持区别、缺席字段保持缺席、所选元数据填满四个可编辑模型字段、用户调整过的行优先于重新发现结果、筛选后的取消选择会清除隐藏候选项,以及选择前没有 settings namespace 或凭据被写入。

进一步阅读

登录后查看全文
deepseek-harness