DeepSeek Harness 的 LLM 调用接口收敛:移除未消费的 `streamBlocks` 与 `generate`,只保留 `stream()` 单一契约
DeepSeek Harness 的 LLM 调用接口收敛:移除未消费的 streamBlocks 与 generate,只保留 stream() 单一契约
LlmService 曾在流式模型调用之上暴露三层接口,而实际唯一的生产消费方 agent loop 只使用原始分片流。DeepSeek Harness(@deepseek-ai/dsh-llm)据此做了一次典型的「接口面积收敛」:移除 streamBlocks()、generate() 及其事件/结果类型,让 stream() 成为唯一的公开 LLM 调用契约。本文以归档的 Agent Note(2026-06-20-drop-unconsumed-llm-assembled-surfaces.zh.md)为主线,结合当前仓库源码还原问题背景、决策依据、替代方案与落地后果,并给出对插件开发者最有价值的结论:llm/stream waterfall 是未来缓存、重试、日志等中间件唯一应包装的调用路径。
背景:三个调用接口的由来与分化
在移除之前,LlmService 在底层模型之上暴露了三个调用接口,各自对应不同的消费形态:
| 接口 | 返回形态 | 分发路径 | 设计意图 |
|---|---|---|---|
stream() |
原始 StreamChunk 流 |
llm/stream waterfall(瀑布式事件) |
让调用方拿到未经组装的逐片数据,自行决定如何消费 |
streamBlocks() |
按流顺序已组装的 ContentBlock |
内部将分片送入 BlockAssembler 后产出 |
为「不关心 token 级增量」的消费方提供便捷视图 |
generate() |
完整组装的 GenerateResult |
第二条 llm/generate waterfall |
在同一底层流之上再建一个「拦截面」,一次性返回完整结果 |
从归档文档的描述看,streamBlocks() 实现于历史版本的 packages/llm/llm/src/index.ts(约 137-144 行),generate() 在同一文件的 151-157 行。这两个便捷接口本质上都是对 stream() 之上 BlockAssembler 组装能力的不同封装。
问题:唯一生产消费方只用了 stream()
文档给出的核心事实是:LLM 服务唯一的生产消费方是 agent loop(智能体循环),而它只使用 stream()。
在 packages/core/agent-loop/src/agent.ts 的 step() 方法中可以看到这段真实调用链:
const assembler = new BlockAssembler()
const chunkSeqs: number[] = []
try {
const stream = preparedCall?.stream(request) ?? this.loopCtx.llm.stream(request)
signal.throwIfAborted()
for await (const chunk of stream) {
signal.throwIfAborted()
chunkSeqs.push(this.session.append('assistant/chunk', { turn, step, chunk }).seq)
assembler.push(chunk)
}
signal.throwIfAborted()
} catch (error) { /* 中断时用 assembler.interruptedBlocks() 收尾 */ }
关键点在于 for await 循环体的两行:
this.session.append('assistant/chunk', ...)—— 把每一个原始分片同步写入会话日志;assembler.push(chunk)—— 同时喂给BlockAssembler做组装。
这正是文档所强调的设计动机:agent loop 需要在并行组装的同时记录原始分片,以保证回放保真度(高保真重放数据必须来自原始 chunk,而不是已组装块的二次加工)。组装视图接口恰恰丢掉了这种增量信息——它们是为「不关心 token 级增量的消费方」推测性构建的,而唯一真实消费方恰恰关心增量。
文档进一步确认,在 packages/*/src 与 examples/*/src 中 grep streamBlocks 与 ctx.llm.generate 找不到任何生产调用方,仅有的引用来自服务方法定义、文档和测试;适配器测试用 generate() 作为便捷驱动,但它们完全可以通过同一个 assembler 辅助函数手动消费 stream()。
拖带成本:便捷接口在底座上留下了专用逻辑
两个便捷接口并非零成本封装,它们各自拖带了一块只为「按序增量产出 / 一次性服务组装」而存在的底座逻辑:
streamBlocks()拖带的部分:历史版本的 packages/llm/llm/src/assembler.ts(约 138-168 行)中为按序增量产出而实现的flushReady()与flushRemaining(),以及flushed游标字段;generate()拖带的部分:GenerateResult结果类型、BlockAssembler.result()方法,以及llm/generate这个在同一底层流之上的第二个 waterfall 拦截面。
对照当前仓库中的 packages/llm/llm/src/assembler.ts,可以确认这些专用逻辑已不存在:BlockAssembler 的公开操作仅剩 push(chunk)、blocks()、interruptedBlocks()、只读的 usage / finish / replayState,以及 message(source)——与文档陈述的「agent loop 对 assembler 的使用仅限于 push() / message() / usage / finish,不涉及流式 flush 或一次性服务组装」完全吻合。此外 interruptedBlocks() 这个为中断收尾而保留的能力(assembler.ts)正被 agent.ts 的中断分支消费,属于「有生产消费方的操作」。
当前 packages/llm/llm/src/index.ts 中 Cordis 事件声明也只剩一个 waterfall:
interface Events {
'llm/stream'(this: LlmRuntime, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
}
LlmAdapter 的抽象基类也只要求子类实现唯一一个必需方法 abstract stream(options)(index.ts),prepareCall 返回的一代注册绑定流入口同样是 stream(options)——整个包从服务到适配器边界都是一条流式路径。
决策:stream() 成为唯一公开调用接口
基于上述事实,归档文档记录的决策是明确的:
stream()是唯一保留的公开 LLM 调用接口;- 移除
streamBlocks、generate,以及它们的事件/结果类型(如GenerateResult、llm/generate事件); - 移除仅被该路径使用的 assembler 辅助方法(
flushReady()、flushRemaining()、result()); - 适配器测试改为通过本地辅助函数对公开流进行组装,走与生产完全相同的流式路径;
BlockAssembler只保留有生产消费方的操作。
这一决策与之前「删除可变会话 summary」的归档笔记属于同类模式:带有受测契约的组装视图 API,由测试而非生产代码消费。测试驱动的接口不构成保留公开 API 的正当理由。
曾考虑的替代方案
归档文档记录了一个被明确否决的替代方案:保留 generate() 作为仅供测试的便捷方法。
否决理由是:适配器测试通过共享 assembler 手动消费 stream() 即可,走的与生产完全相同;一个唯一调用方只有测试的公开方法,正是此前「删除可变会话 summary」先例所淘汰的死接口形态。文档同时给出了面向未来的开放态度:如果将来确实出现「不需要增量、只要组装块」的消费方,届时再为该消费方引入一个聚焦的辅助方法,而不是现在保留一个没有消费者的预设接口。
验证:删除后的可证实状态
归档文档记载的验证项,在当前仓库中均可逐一对应核实:
streamBlocks、generate、llm/generate均已移除:对 packages/llm/llm/src 的检索仅命中无关的错误码常量文件,事件声明中已无llm/generate;- 未产生新的无用导出:
LlmRuntime、LlmAdapter、BlockAssembler的导出面(index.ts)只覆盖被消费的能力; - 两个真实适配器通过
stream()和共享 assembler 接受测试:例如 packages/llm/llm-deepseek/tests/adapter.spec.ts 中直接以adapter.stream(...)构造请求并 drain,端到端测试则通过ctx.llm.stream({...})消费(packages/llm/llm-deepseek/tests/adapter.e2e.ts); - 循环行为保持一致:ACP 快照预期输出未变;
- 文档同步:README、架构文档和模块文档不再提及已删除表面。
后果与插件开发启示
对包内架构的影响
- 从一个核心词汇包中移除了公开方法。未来如果有插件需要不带增量的组装块,它需要直接调用
stream()并使用BlockAssembler,或在有真实消费方时重新引入一个聚焦的辅助方法。归档文档特别强调,鉴于预发布阶段「基础优先于预设未来」的立场(见 AGENTS.md),当时正是裁剪仅供测试的公开接口的合适时机。 - 适配器测试变得更显式。测试失去了
generate()的便捷包装层,但这是一次有益的压力:测试与生产共享同一条流式路径,测试通过并不代表生产路径不可用。
对 waterfall 使用者的最重要结论
waterfall 使用者失去了 llm/generate,但该事件本就没有生产监听者。 未来的缓存 / 重试 / 日志等插件应包装 llm/stream——它仍然是唯一的提供方调用路径。当前仓库中的 packages/core/agent-loop/src/invariant.ts 就是这种包装的现成范例:它监听 llm/stream,对 loop 构建的请求校验请求体是否冻结、会话 ID 是否存活、消息序列能否从会话日志重建、请求头是否与日志折叠结果一致,校验通过后调用 next() 放行到适配器。这个 invariant 插件正是「中间件在 llm/stream 上做拦截」的标准姿势,未来的缓存、重试、日志插件可以沿用同一模式。
小结
这次改动规模不大,但它从 LLM 包中干净地移除了预设的接口面积:生产与测试最终共享唯一一份模型调用契约——stream() 原始分片流 + BlockAssembler 增量组装。对 DeepSeek Harness 的插件开发者而言,这篇文章可以提炼出三条可直接落地的经验:
- 调用模型只用
ctx.llm.stream(request),需要组装块时自行持有BlockAssembler实例并push()每个分片,结束后读取blocks()/message()/usage/finish; - 中间件(缓存、重试、日志、可观测性)只包装
llm/streamwaterfall,它是唯一的模型调用拦截点; - 公开 API 必须由生产代码消费,仅有测试消费的便捷接口属于「预设未来」,应随本次先例一并裁剪。