DeepSeek Harness LLM 接口收敛实践:移除未被消费的组装便捷面,让 `stream()` 成为唯一模型调用契约

原创2026-09-18 17:00:542,260 阅读
文章标签:人工智能AI AgentAgent 框架DeepSeek

DeepSeek Harness LLM 接口收敛实践:移除未被消费的组装便捷面,让 stream() 成为唯一模型调用契约

DeepSeek Harness(gh_mirrors/de/deepseek-harness)在其 packages/llm/llm 核心包中完成了一次典型的"接口面积收敛":将原本暴露的三条模型调用面(stream()、streamBlocks()、generate())收敛为唯一公开契约 stream(),并同步删除了 BlockAssembler 中仅为便捷面服务的专用逻辑。本文以归档 Agent Note 2026-06-20-drop-unconsumed-llm-assembled-surfaces.md 为主体,结合当前仓库源码,完整还原这次改动的背景、决策、验证与后果,并给出"以真实消费方为准裁剪推测性 API"的可复用方法:读者可以从中掌握如何用 grep 审计定位死接口、如何让测试与生产共用同一条调用路径,以及如何在预发布阶段平衡"基础优先"与"不预留未证实功能"。

背景:LLM 服务的三条调用面与一个真实消费方

LlmRuntime(packages/llm/llm/src/index.ts)是 DeepSeek Harness 的 LLM 服务:一个"适配器注册表 + 可被 waterfall 拦截的流式调用 API"。插件通过 ctx.llm.registerAdapter(providers, adapter) 注册适配器,抽象类 LlmAdapter 只要求适配器实现一个方法——stream(options)(index.ts#L270-L275),"Stream one model call as raw chunks. The only required method."

在本次改动之前,服务在模型之上暴露了三条调用面:

调用面 语义 分发路径
stream() 原始 StreamChunk(token 级增量) 通过 llm/stream waterfall
streamBlocks() "便捷视图":把分片送入 BlockAssembler,按流顺序产出已组装的 ContentBlock 复用 llm/stream 底层流
generate() 一次性完整组装的 GenerateResult 通过第二条 llm/generate waterfall

而整个仓库中 LLM 服务的唯一生产消费方是 agent loop(packages/core/agent-loop/src/agent.ts)。它对 stream() 的使用方式(agent.ts#L359-L399)揭示了为什么便捷面是多余的:

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)
  }
  ...

loop 拿到原始 chunk 流后做两件事:先把每个 chunk 原样 append 进会话日志(session.append('assistant/chunk', ...),为回放保真度保留原始序列),再并行地把同一 chunk 喂给自建的 BlockAssembler 完成组装。也就是说,真实消费方恰恰关心 token 级增量本身——因为它要持久化高保真回放数据,而不是只想要最终组装结果。

为什么组装便捷面是"推测性"的

streamBlocks() 拖带的专用逻辑

streamBlocks() 作为"按流顺序增量产出已组装块"的视图,需要 BlockAssembler 提供 flushReady() 与 flushRemaining() 两个方法(原 assembler.ts#L138-L168 区域),外加一个 flushed 游标字段——这一切仅为支持增量按序产出而存在。

对照当前 assembler.ts 保留的操作集合,差距一目了然:现在的 BlockAssembler 只保留有真实生产消费方的操作——push()(assembler.ts#L48-L95)、blocks()(assembler.ts#L157-L159)、interruptedBlocks()(assembler.ts#L168-L178)、usage(assembler.ts#L181-L183)、finish(assembler.ts#L186-L188)、replayState(assembler.ts#L195-L197)与 message()(assembler.ts#L204-L206)。loop 的全部消费就是 push() / message() / usage / finish,外加中断场景下的 interruptedBlocks()——流式 flush 与一次性服务组装都不在列。

generate() 拖带的第二套契约

generate() 则拖带得更远:GenerateResult 结果类型、BlockAssembler.result() 组装入口,以及 llm/generate 这条在同一底层流之上的第二个 waterfall 拦截面。它等于为同一个模型调用维护了两套事件契约、两套结果类型、两处可拦截点——而生产代码从未使用过其中任何一处。

消费方审计是决定性证据

Agent Note 记录的审计方法是:在 packages/*/src 与 examples/*/src 中 grep streamBlocks 与 ctx.llm.generate,找不到任何生产调用方;仅有的引用来自服务方法定义、文档与测试。测试(尤其是适配器测试)确实在用 generate() 作为便捷驱动,但测试完全可以通过同一个 assembler 辅助函数手动消费 stream()——这正是改动后实际采取的做法,无需为此保留一个公开的生产 API。

组装器的保留价值:共享的"keep/drop 决策"

值得强调的是,BlockAssembler 本身没有被弱化——它仍是从分片到消息的唯一规范组装算法(文件头注释:"the single canonical assembly algorithm")。当前实现还承载着一个生产必需的共享决策:当 finish 为 max-tokens 时,组装结果会丢弃无法安全执行的 tool-call 块(assembler.ts#L134-L149),并且发出的块与回放元数据(ReplayEnvelope)都派生自同一个 keep/drop 结果,"so they cannot disagree"。这正是"组装逻辑归一处、便捷入口不重复"的体现。

决策:stream() 作为唯一公开 LLM 调用契约

Agent Note 的决策表述非常明确:

stream() is the sole public LLM call surface. Remove streamBlocks, generate, its event/result types, and assembler helpers used only by that path.

即:

  • 公开层面:stream() 成为唯一的模型调用入口,llm/stream 成为唯一的 waterfall 拦截面;
  • 删除清单:streamBlocks、generate、GenerateResult 与相关事件类型、llm/generate waterfall,以及仅被该路径使用的 assembler 辅助方法(flushReady / flushRemaining / flushed / result());
  • 保留边界:适配器测试改为通过本地辅助函数对公开的 stream() 进行组装;BlockAssembler 仅保留有生产消费方的操作。

当前源码正是这一决策的落地结果。在 packages/llm/llm/src/index.ts 中,Cordis 事件扩展只剩一个 llm/stream waterfall 声明(index.ts#L67),LlmRuntime 的对外调用入口只有 stream(options)(index.ts#L1050-L1052),其内部经由 streamWithRegistration 包一层 ctx.waterfall(this, 'llm/stream', options, ...)(index.ts#L1054-L1064)完成拦截分发。全仓库已无 streamBlocks / generate / llm/generate 的任何残留引用。

曾考虑的替代方案:为什么不留一个测试专用便捷方法

方案:保留 generate() 作为仅供测试的便捷方法。否决理由有两层:

  1. 测试路径与生产路径应当一致:适配器测试通过共享 assembler 手动消费 stream(),走的是与生产完全相同的流式路径——这是"测试即压力"的正向约束,而不是损失。留着 generate(),测试反而会绕开生产真正使用的组装路径。
  2. "唯一调用方是测试的公开方法"正是该淘汰的死接口形态:这与 2026-06-19-drop-mutable-session-summary.md(删除可变 session summary)判定的模式完全同构——"带有受测契约的组装视图 API,由测试而非生产代码消费"。

验证方式:如何证明"删干净了"

Agent Note 的 Verification 一节给出了四条可复现的验证口径:

  1. 无死导出:streamBlocks、generate、llm/generate 及仅供它们使用的 assembler 辅助函数均已移除,且没有产生新的无用导出(可由仓库内 knip 等检查佐证,见根目录 knip.json);
  2. 适配器测试仍覆盖真实路径:两个真实适配器都通过 stream() + 共享 assembler 接受测试;
  3. 行为不变:agent loop 行为保持一致,ACP 快照的预期输出未发生变化;
  4. 文档同步:README、架构文档与模块文档不再提及已删除的调用面。

当前源码的对照检查同样支持这些结论:在 packages/llm/llm/src 全部源文件中搜索 streamBlocks、GenerateResult、flushReady、result() 均无命中;组装行为由 assembler.spec.ts 等测试持续固定。

后果:一次收敛,三个面向

1. 从核心词汇包移除公开方法

packages/llm/llm 属于"core vocabulary package"。移除公开方法意味着:未来若真有插件需要"不带 token 级增量的组装块",它必须直接调用 stream() 并自行使用 BlockAssembler,或者在有真实消费方出现时再引入一个聚焦的辅助方法。这正是预发布阶段"基础优先于预设未来"(foundation over speculative future,见 AGENTS.md)立场的体现——现在正是裁剪仅供测试的公开接口的合适时机。

2. 适配器测试变得更显式

测试失去了 generate() 的便捷包装,但这是有益的压力:测试与生产共享同一条流式路径,任何适配器都必须以生产实际使用的方式被验证。

3. waterfall 使用者失去 llm/generate

不存在任何生产监听者。今后需要做缓存、重试、日志的插件应包装 llm/stream——它仍然是唯一的提供方调用路径(single provider call path)。单一路径意味着插件作者只需要理解一套拦截语义、一套 chunk 协议,而无需在两套 waterfall 间做选择。

方法论沉淀:这是可复用的"死接口审计"模板

这次改动并非孤例,而是 DeepSeek Harness 持续执行的简化纪律的一部分(.agents/notes/archived/simplification/ 下聚集了大量同类记录)。从其直接先例 drop-mutable-session-summary 中可以提炼出完整的决策套路,与本次改动一一对应:

步骤 本次改动的落点
枚举表面 三条调用面、两套 waterfall、三处 assembler 辅助入口
审计真实消费方 全仓库 grep,确认唯一生产消费者是 agent loop 且只用 stream()
区分"测试在用"与"生产在用" 适配器测试的 generate() 调用不构成保留理由
识别拖带成本 flushReady/flushRemaining/flushed/result() + 第二条 waterfall 的维护面
给出等价替代 测试改由共享 assembler 消费 stream();未来需求用 stream() + BlockAssembler 直接满足
验证无回归 grep 无残留、快照输出不变、文档清理

其背后的原则在 drop-mutable-session-summary 中被正式记录为一条仓库约定:a passing test pins current behavior, not necessarily correct behavior(通过的测试固定的是当前行为,未必是正确的行为);行为可能是过去妥协的产物。当一个 API 只有测试在消费时,它固定住的就只是"测试存在"这一历史事实,而非真实需求。

小结:留给生产与测试的同一份契约

这次改动规模不大,但意义在于:它从 LLM 包中干净地移除了推测性接口面积,让生产与测试共享同一份模型调用契约。llm/stream + StreamChunk(协议定义见 types.ts#L356-L376)+ BlockAssembler(规范组装算法)构成了一条自洽的单一路径:适配器只产出 token 级增量,agent loop 在记录原始 chunk 的同时完成组装,任何需要"组装结果视图"的消费方都可以在自己的消费点上组合出所需形态,而不必由核心包预先替所有人买单。

对 DeepSeek Harness 的插件开发者而言,这份契约的现实含义是:所有模型调用都从 stream() 出发;需要组装结果时用 BlockAssembler(它同时为你处理 max-tokens 截断下 tool-call 的安全丢弃与回放元数据对齐);需要拦截(缓存、重试、日志)时包装 llm/stream waterfall。未来若出现真正需要无增量组装块的消费方,届时再为它引入一个聚焦的辅助方法——这就是"基础优先于预设未来"的实践注脚。

登录后查看全文
deepseek-harness