DeepSeek Harness 提供方端点询问(Model Discovery)设计解析:以 settings namespace 为键的一次性草稿探测
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-keyheader 且需要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):
- 标准
data数组({ data: [...] })——优先,存在时采用; - 富信息
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 或凭据被写入。
进一步阅读
- Agent Note 英文原版
- pi-ai 声明式提供方目录(前置改动)
- dsh-llm-pi-ai 包文档(含「从端点发现模型」小节与全部配置字段)
- dsh-llm 服务文档(注册表与操作的类型声明)
- LLM 流式子系统