Two LLM adapters as a design-verification twin
以两个 LLM 适配器作为设计验证孪生体
`dsh-llm` owns a provider-neutral streaming vocabulary — the `StreamChunk` protocol (`block-start`, `text-delta`, `reasoning-delta`, `tool-call-delta`, `block-end`, `usage`, `finish`) and the content-block types ([the content-block vocabulary](2026-06-11-content-block-vocabulary.md)). A vocabulary defined against a single adapter risks baking that adapter's quirks into the "neutral" contract: anything the one impleme
English
Problem
dsh-llm owns a provider-neutral streaming vocabulary — the StreamChunk protocol (block-start, text-delta, reasoning-delta, tool-call-delta, block-end, usage, finish) and the content-block types (the content-block vocabulary). A vocabulary defined against a single adapter risks baking that adapter's quirks into the "neutral" contract: anything the one implementation happens to do becomes the de-facto spec, and the abstraction is unverified until a second provider arrives — by which point the leak is expensive to fix.
Decision
Ship two adapters against the one contract from the start, deliberately built on different internals:
dsh-llm-deepseek— directfetch+ in-repo translation against the DeepSeek API; SSE framing is delegated toeventsource-parser(the archived SSE-parser swap). The twin identity is owning the fetch/translate internals rather than delegating to a full provider SDK, not hand-rolling transport plumbing.dsh-llm-pi-ai— the same endpoint through the@earendil-works/pi-ailibrary (its own event vocabulary).
The rule they enforce: anything the StreamChunk vocabulary cannot express for BOTH implementations is a core-vocabulary bug, caught immediately rather than at the next provider. The pair pinned down conventions now documented on StreamChunk in dsh-llm/src/types.ts: usage emitted before finish, nothing after finish, tool-call arguments as raw JSON strings end-to-end, and the two sanctioned error paths (throw from stream() or end with finish {kind:'error'|'aborted'}) that a consumer must handle on both sides — a divergence the library-backed adapter surfaced that a single direct-fetch adapter would have hidden.
Alternatives considered
- A single adapter — less code and half the e2e cost, but leaves the "provider-neutral" claim unverified; the vocabulary would encode DeepSeek-via-fetch assumptions silently.
- A mock second adapter — cheaper but doesn't exercise a real provider's wire quirks, so it proves little. The twin is real-on-real.
Consequences
The twin doubles adapter and key-gated e2e maintenance—both cover V4 Flash and Pro across representative reasoning modes—in exchange for continuous seam-neutrality validation and a second implementation example. Both use apiKey, baseURL, and models; the direct-fetch adapter exposes thinking/reasoningEffort, while pi-ai exposes one reasoning level. A future conformance suite could justify retiring one adapter through a superseding Agent Note.
中文
问题
dsh-llm 拥有一套提供方无关的流式词汇：StreamChunk 协议（block-start、text-delta、reasoning-delta、tool-call-delta、block-end、usage、finish）以及内容块类型（内容块词汇）。如果词汇仅针对单个适配器定义，就有可能将该适配器的特异行为固化到「中立」约定中：唯一实现碰巧做了什么，什么就成为事实上的规范；在第二个提供方到来之前，抽象层未经验证——而届时修复这种泄漏的代价已经很高。
决策
从一开始就针对同一份约定交付两个适配器，刻意基于不同的内部实现构建：
dsh-llm-deepseek：直接fetch+ 仓库内翻译逻辑对接 DeepSeek API；SSE（Server-Sent Events）分帧委托给eventsource-parser（已归档的 SSE 解析器替换）。孪生身份在于自行持有 fetch/translate 内部实现而非委托给完整的提供方 SDK，不在于手写传输层管道。dsh-llm-pi-ai：通过@earendil-works/pi-ai库访问同一端点（该库有自己的事件词汇）。
二者共同执行的规则是：凡 StreamChunk 词汇无法为两个实现同时表达的内容，都是核心词汇的缺陷——立即暴露，而非等到下一个提供方接入时才发现。这对孪生适配器确立了现已记录在 dsh-llm/src/types.ts 中 StreamChunk 上的约定：usage 在 finish 之前发出、finish 之后不再有任何事件、工具调用的 arguments 全程以原始 JSON 字符串传递，以及消费方必须在两侧都处理的两条合法错误路径（stream() 抛异常，或者以 finish {kind:'error'|'aborted'} 结束）。这一分歧正是由基于库的适配器暴露出来的，单一直接 fetch 适配器会将其隐藏。
曾考虑的替代方案
- 单一适配器：代码更少、e2e 成本减半，但「提供方无关」的声明无从验证；词汇会默默编码 DeepSeek-via-fetch 的假设。
- mock 第二适配器：更便宜，但不会触及真实提供方的协议格式（wire format）怪癖，因此证明力有限。孪生体是真实对真实的验证。
后果
孪生体使适配器和需要密钥的 e2e 维护量翻倍——两者都覆盖 V4 Flash 和 Pro 在各代表性推理（reasoning）模式下的行为——换来的是持续的 seam 中立性验证和第二份实现示例。两个适配器均使用 apiKey、baseURL 和 models；直接 fetch 适配器暴露 thinking/reasoningEffort，pi-ai 适配器暴露一个 reasoning 级别。未来如果有一致性测试套件，可以通过后续 Agent Note 论证退役其中一个适配器。