DSH plugin 怎么写 LLM 适配器？给 DeepSeek Harness 接入新模型提供方

给 DeepSeek Harness 接入新模型提供方的办法就是写一个 LLM 适配器：继承 LlmAdapter、实现 stream()，把提供方无关请求转成厂商 API，再把响应转回 Harness 分片。 最后用 ctx.llm.registerAdapter() 注册到对应路由，并按需覆写 resolveModel() 与 listModels()。这是让 DSH插件 支持任意模型后端的关键开发面。

DSH plugin 的 LLM 适配器是什么：继承 LlmAdapter 实现 stream()

LLM 适配器是一个继承 LlmAdapter 并实现 stream() 的类，负责双向翻译：入站把 Harness 请求转成厂商 API，出站把响应转回 Harness 分片（来源）。 官方最小实现如下：

import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'
import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'

class MyAdapter extends LlmAdapter {
  private apiKey: string

  constructor(apiKey: string) {
    super()
    this.apiKey = apiKey
  }

  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
    // 1. Convert options.messages to the provider format.
    // 2. Call the streaming API.
    // 3. Convert the response into StreamChunk values.
  }
}

export interface Config {
  apiKey: string
  providers: string[]
}

export const Config: Schema<Config> = Schema.object({
  apiKey: Schema.string().required(),
  providers: Schema.array(Schema.string()).required(),
})

export const name = 'my-llm-adapter'
export const inject = ['llm']

export function apply(ctx: Context, config: Config) {
  const adapter = new MyAdapter(config.apiKey)
  ctx.llm.registerAdapter(config.providers, adapter)
}

按四步落一个适配器插件：

1. 写适配器类 — 继承 LlmAdapter，实现 async *stream(options)。预期：类型提示要求返回 AsyncIterable<StreamChunk>。
2. 声明 Config 与 inject — 用 schemastery 定义 apiKey 等字段，并声明 inject = ['llm']。预期：ctx.llm 可用，密钥可按官方方式通过 !!js process.env.MY_KEY 注入。
3. 在 apply 注册 — ctx.llm.registerAdapter(config.providers, adapter)。预期：options.provider 命中该路由时走你的适配器。
4. 覆写可选方法 — 需要时实现 resolveModel() / listModels()。预期：模型选择器能列出你提供的模型。

注册基于副作用且对 HMR 安全：每个提供方路由只对应一个适配器，重复注册会抛异常，多路由注册要么全部成功要么全部失败（来源）。

DSH plugin 的 stream() 怎么写：StreamChunk 协议与关键规则

stream() 必须按官方 StreamChunk 协议产分片，顺序与配对是硬约束（来源）。 关键规则如下：

• 每个 block-start 都必须有对应的 block-end；index 从 0 递增标识内容块。
• usage 必须在 finish 之前发出，finish 必须是最后一个分片，之后不再发出任何内容。
• tool-call-delta 的 argumentsDelta 是原始 JSON 文本的增量；提供方若返回已解析对象，要在 block-end 时重新 stringify。
• 稳健做法：缓冲 finish / usage 直到提供方的流结束标记再统一 flush，以处理末尾只带 usage 分片的情况。

协议片段按下面生成：

yield { type: 'block-start', index: 0, blockType: 'text' }
yield { type: 'text-delta', index: 0, text: 'Hello' }
yield { type: 'block-end', index: 0, block: { type: 'text', text: 'Hello world' } }
yield { type: 'usage', usage: { inputTokens: 100, outputTokens: 50 } }
yield { type: 'finish', reason: { kind: 'stop' } }

如果某个 GenerateOptions 字段你的提供方不支持，必须抛 LlmError(..., 'UNSUPPORTED_OPTION')，不得静默丢弃。 官方参考实现是 packages/llm/llm-deepseek/（直接 HTTP，SSE 由 eventsource-parser 分帧）与 packages/llm/llm-pi-ai/。

DSH plugin 怎么注册并提供模型元数据

options.provider 选择适配器、options.model 是提供方模型 id，因此动态模型目录适配器无需重启生命周期就能提供新模型（来源）。 在 cordis.yml 里把适配器与 agent loop 串起来：

- id: my-llm
  name: './src/my-llm-adapter.ts'
  config:
    apiKey: !!js process.env.MY_API_KEY
    providers:
      - my-provider

- id: agent-loop
  name: '@deepseek-ai/dsh-agent-loop'
  config:
    agents:
      - id: main
        provider: my-provider
        model: my-model-v1

覆写 resolveModel(provider, model, signal?) 是声明模型能力的地方：返回确切的提供方 / 模型身份，以及可选的 context 与 reasoning 元数据；推理强度是适配器映射到提供方请求的有序不透明 ID，要保留适配器给出的权威列表（含支持时的 off），不要提升为核心枚举，也不要自动调整不支持的值。异步查询必须响应可选 signal，让取消与资源释放停稳。

错误只有两条合法路径：从 stream() 抛出带稳定 code 的 LlmError（传输与协议故障），或以 finish { kind: 'error' | 'aborted' } 结束流（提供方带内故障）。每个 HTTP 请求还要合并 attributionHeaders() 并传递 options.signal：

if (!response.ok) {
  throw new LlmError(`Provider API error: ${response.status}`, 'PROVIDER_HTTP_ERROR')
}

写完自检：usage 是否在 finish 之前、finish 是否最后；不支持的字段是否抛 UNSUPPORTED_OPTION；signal 是否透传；路由是否与别人的适配器冲突。想先了解适配器挂载的 ctx.llm 扩展点属于哪类能力，看 能力 Seams 与核心服务；想对照社区实现，可在 DSH Plugin Hub 找同类适配器插件。