deepseek-harness 的 SSE 解析重构用 eventsource-parser 替换 llm-deepseek 手写解析器【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harnessDeepSeek Harness 的llm-deepseek适配器曾手写实现了一套约 67 行的 Server-Sent EventsSSE流式解析逻辑用于解析 DeepSeek chat-completions 端点的流式响应。本文基于仓库内已归档的技术决策笔记.agents/notes/archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md另有中文版与当前源码完整还原这次用成熟库替换手写传输层的重构它删掉了约 108 行重复验证 SSE 规范行为的测试将解析职责委托给事实标准库eventsource-parser而把适配器自身的代码收敛到只剩 DeepSeek[DONE]哨兵与STREAM_CLOSED协议。读完本文你将理解 SSE 流式响应在 Harness 中的完整链路fetch→ 解码 → 事件分帧 →[DONE]终止 →StreamChunk翻译以及一次功能等价但语义更严格的替换所带来的行为差异。重构背景为什么手写 SSE 解析器会被替换在重构之前packages/llm/llm-deepseek/src/sse.ts手写实现了完整的 SSE 解析用流式TextDecoder处理分块到达的字节流按\r?\n\r?\n切分事件块提取并拼接data:载荷、跳过注释行与无关字段识别[DONE]结束哨兵在 EOF 未遇到[DONE]时抛出STREAM_CLOSED错误冲刷最后一个没有空行终止的事件块。这段代码约 67 行却配套了约 108 行的专用测试tests/sse.spec.ts逐一重新验证了 SSE 规范行为UTF-8 跨分块拆分、CRLF 处理、多行data:拼接、冒号后无空格的字段格式等。而它的唯一消费方是 adapter.ts 中的yield* translate(parseSse(response.body))—— 整个手写解析器只服务这一处调用。决策笔记指出这正是eventsource-parser库所覆盖的职责面它是事实标准的 SSE 解析器Vercel AI SDK 与 MCP SDK 底层都依赖它零依赖、持续维护并且早已通过modelcontextprotocol/sdk以传递依赖的形式出现在本仓库的 lockfile 中。换句话说直接采用它并不会新增供应链面却能删除一整块重新发明轮子的代码与测试。新实现把 SSE 分帧交给 EventSourceParserStream重构后的 sse.ts 从约 67 行缩减到 40 行核心是一个纯粹的管道组合import { EventSourceParserStream } from eventsource-parser/stream import { LlmError } from deepseek-ai/dsh-llm /** The terminal payload DeepSeek (and OpenAI) send after the last chunk. */ export const DONE [DONE] export async function* parseSse( stream: ReadableStreamBufferSource, onComment?: (comment: string) void, ): AsyncGeneratorstring { const events stream .pipeThrough(new TextDecoderStream()) .pipeThrough(new EventSourceParserStream({ onComment })) for await (const { data } of events) { yield data if (data DONE) return } throw new LlmError(SSE stream ended without [DONE], STREAM_CLOSED) }新的parseSse只做三件事字节 → 文本通过new TextDecoderStream()处理流式 UTF-8 解码天然解决一个字符被网络分块拆开的问题文本 → 事件通过new EventSourceParserStream({ onComment })完成 SSE 分帧包括\r?\n\r?\n事件块切分、data:载荷提取与多行拼接、注释行: ...与event:/id:/retry:等非数据字段的跳过以及前导 BOM 剥离DeepSeek 协议收缩逐事件yield data遇到字面量[DONE]即正常返回若流结束仍未见到[DONE]则抛出LlmError(SSE stream ended without [DONE], STREAM_CLOSED)。整个组合只用到 Node ^22.19 引擎下限就内置的 Web Streams 原语TextDecoderStream、pipeThrough、可异步迭代的ReadableStream因此不需要额外的运行时垫片。模块的 JSDoc 也明确标注了新职责边界分帧、块重组、UTF-8/CRLF/BOM、注释与字段跳过、多data:拼接都属于eventsource-parser的合约本模块只保留 DeepSeek 协议层。依赖变化重构后eventsource-parser正式成为llm-deepseek的第二个运行时依赖第一个是deepseek-ai/schemastery。在 package.json 中可以确认dependencies: { eventsource-parser: ^3.1.0, deepseek-ai/schemastery: workspace:^ }lockfilepnpm-lock.yaml中锁定的版本为eventsource-parser3.1.0且该包在锁文件中被标记为{}零传递依赖与零依赖的声明一致。调用链从 HTTP 响应体到 StreamChunkparseSse处于 DeepSeek 直连适配器的传输层末端。在 adapter.ts 的request()私有生成器中响应体经过一次调用被直接送入翻译层if (!response.body) { throw new LlmError(DeepSeek API returned no response body, EMPTY_RESPONSE) } yield* translate(parseSse(response.body, onActivity))其中onActivity是传输活跃度回调——它被透传给EventSourceParserStream({ onComment })的注释回调用于给适配器的空闲看门狗idleWatchdog默认DEFAULT_STREAM_IDLE_TIMEOUT_MS 300_000见 adapter.ts提供心跳脉冲同时保证 SSE 注释行永远不进入业务载荷流。这一点在 sse.ts 的文档注释中有明确约定comments never enter the yielded payload stream。下游的 translate.ts 消费parseSse产出的字符串序列每个非[DONE]载荷被JSON.parse为 wire chunk解析失败抛MALFORMED_RESPONSEdelta.reasoning_content、delta.content、delta.tool_calls分别累积为 reasoning / text / tool-call 三类块逐段产出reasoning-delta、text-delta、tool-call-deltafinish_reason与usage被延迟挂起直到遇见[DONE]才统一发出block-end、usage、finish从而兼容finish 附带 usage与末尾独立 usage 块两种形态并保证 finish 之后不再有任何块若没有[DONE]就耗尽理论上parseSse会先抛错translate 兜底抛出同样的STREAM_CLOSED。也就是说parseSse与translate通过以[DONE]结尾的字符串序列这一协议解耦前者管传输与分帧后者管业务语义。测试收缩只钉 DeepSeek 协议合约重构最重要的删减发生在测试侧。旧的tests/sse.spec.ts用约 108 行重新证明了 SSE 规范行为跨块 UTF-8、CRLF、多data:拼接、冒号后无空格新版本将这些全部视为eventsource-parser的合约不再重复验证只保留 DeepSeek 协议层测试用例见 tests/sse.spec.ts验证的合约产出载荷并最终产出[DONE]哨兵正常流data: {a:1}\n\ndata: [DONE]\n\n→[{a:1}, DONE]注释带外上报且不产出: keep-alive只进入onComment回调不进入载荷流[DONE]后停止产出即使后面还有data: {late:1}也不再 yieldEOF 未到[DONE]抛STREAM_CLOSED正常结束却无哨兵 截断空流抛STREAM_CLOSED空响应 截断事件中途关闭抛STREAM_CLOSEDdata: {a未闭合 截断尾部[DONE]缺少空行终止符视为截断规范严格分帧未以空行终止的事件不会分发测试通过bytes(...fragments)辅助函数把多个字符串片段当作多次网络读取来构造输入流再用collect收集生成器产出——这种写法让分块边界对解析层完全透明正好印证了新架构的职责划分分帧容错是库的合约协议判定是本模块的合约。一个有意的行为偏差丢失尾部冲刷重构引入了一处有意的健壮性回退值得使用者特别注意旧手写解析器会冲刷最后一个缺少终止空行的事件块——也就是说如果流以data: [DONE]结尾且没有末尾的\n\n旧实现仍会正常产出[DONE]并优雅结束。而eventsource-parser是规范严格的事件只在空行终止符处分发因此这种尾部形态现在会被判定为STREAM_CLOSED截断错误。决策笔记和 sse.spec.ts 都明确记录了这一定性真实厂商和仓库内的dsh-llm-mock-server见 packages/llm/llm-deepseek/tests/mock-server.ts总是正确终止每个事件冲刷只是一个从未被观察到的健壮性修饰而不是真实厂商形态——所以缺失终止符在语义上更接近截断而非可恢复事件。如果你在对接自定义的 OpenAI 兼容端点时发现流在末尾报STREAM_CLOSED优先检查你的服务端是否漏发了最后一个空行。另一个顺带获得的收益BOM 与 maxBufferSize除了解析职责转移eventsource-parser还带来了两处手写解析器没有的能力sse.ts 模块注释对此有明确说明剥离前导 BOM手写解析器在遇到data:前缀之前若夹带一个 UTF-8 BOM 会匹配失败库则直接处理maxBufferSize硬化可对事件缓冲区大小设上限防御超长事件块的资源消耗这是手写版本完全没有的防护。这两点均来自库本身的能力可参考eventsource-parser包的流式 API 文档按需开启。备选方案回顾决策笔记记录了被否决的另外两条路线保留手写解析器在双适配器设计验证twin-adapters决策下看起来合理——dsh-llm-deepseek被刻意设计为 pi-ai 适配器的手写对照版本。但该决策的承重区分在于拥有 fetch/translate 内部实现 vs 委托给完整厂商 SDK而一个约 700 字节的 SSE 微解析器只是传输管道不是被验证的设计本身。这条理由被明确写入了更新后的 twin-adapters 决策文档The twin identity is owning the fetch/translate internals rather than delegating to a full provider SDK, not hand-rolling transport plumbing.createParser({ onEvent })回调 API可以用手写TextDecoder循环驱动但pipeThrough的流式组合能删除更多手写代码因此最终选择了EventSourceParserStream。重构后果与经验总结这次重构的最终后果可以归纳为三点与决策笔记的 Consequences 一一对应协议面收敛剩余的 shim 只编码 DeepSeek[DONE]/STREAM_CLOSED协议SSE 分帧边界情况成为eventsource-parser的合约不再在本仓库重复证明。测试从重证规范收缩为钉协议维护成本显著下降。健壮性语义更严格如上文所述未以空行终止的尾部[DONE]从被冲刷变为STREAM_CLOSED测试固化的是新语义。文档同步更新twin-adapters 决策文档中hand-rolled fetch SSE parsing的表述随之收窄为direct fetch with library-framed SSE并在同一变更中更新而不是留下过期声明dsh-llm适配器的 JSDoc 也做了同步修改。从项目工程实践角度看这是一次教科书式的传输管道交给成熟库、业务协议自己持有的拆分eventsource-parser因其事实标准地位AI SDK / MCP SDK 同款、零依赖与既有传递依赖身份而入选替换后llm-deepseek的运行时依赖仅从 1 个增至 2 个换来的是约 67 行源码与约 108 行测试的净删减以及 BOM 处理、缓冲上限等顺带硬化。若你想深入本模块的其余部分可以继续阅读 translate.tswire chunk 到StreamChunk的翻译、adapter.ts直连 fetch 适配器的完整请求/重试/看门狗逻辑以及 twin-adapters 决策文档双适配器设计验证的完整来龙去脉。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 deepseek-harness 的 SSE 解析重构：用 eventsource-parser 替换 llm-deepseek 手写解析器
deepseek-harness 的 SSE 解析重构用 eventsource-parser 替换 llm-deepseek 手写解析器【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harnessDeepSeek Harness 的llm-deepseek适配器曾手写实现了一套约 67 行的 Server-Sent EventsSSE流式解析逻辑用于解析 DeepSeek chat-completions 端点的流式响应。本文基于仓库内已归档的技术决策笔记.agents/notes/archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md另有中文版与当前源码完整还原这次用成熟库替换手写传输层的重构它删掉了约 108 行重复验证 SSE 规范行为的测试将解析职责委托给事实标准库eventsource-parser而把适配器自身的代码收敛到只剩 DeepSeek[DONE]哨兵与STREAM_CLOSED协议。读完本文你将理解 SSE 流式响应在 Harness 中的完整链路fetch→ 解码 → 事件分帧 →[DONE]终止 →StreamChunk翻译以及一次功能等价但语义更严格的替换所带来的行为差异。重构背景为什么手写 SSE 解析器会被替换在重构之前packages/llm/llm-deepseek/src/sse.ts手写实现了完整的 SSE 解析用流式TextDecoder处理分块到达的字节流按\r?\n\r?\n切分事件块提取并拼接data:载荷、跳过注释行与无关字段识别[DONE]结束哨兵在 EOF 未遇到[DONE]时抛出STREAM_CLOSED错误冲刷最后一个没有空行终止的事件块。这段代码约 67 行却配套了约 108 行的专用测试tests/sse.spec.ts逐一重新验证了 SSE 规范行为UTF-8 跨分块拆分、CRLF 处理、多行data:拼接、冒号后无空格的字段格式等。而它的唯一消费方是 adapter.ts 中的yield* translate(parseSse(response.body))—— 整个手写解析器只服务这一处调用。决策笔记指出这正是eventsource-parser库所覆盖的职责面它是事实标准的 SSE 解析器Vercel AI SDK 与 MCP SDK 底层都依赖它零依赖、持续维护并且早已通过modelcontextprotocol/sdk以传递依赖的形式出现在本仓库的 lockfile 中。换句话说直接采用它并不会新增供应链面却能删除一整块重新发明轮子的代码与测试。新实现把 SSE 分帧交给 EventSourceParserStream重构后的 sse.ts 从约 67 行缩减到 40 行核心是一个纯粹的管道组合import { EventSourceParserStream } from eventsource-parser/stream import { LlmError } from deepseek-ai/dsh-llm /** The terminal payload DeepSeek (and OpenAI) send after the last chunk. */ export const DONE [DONE] export async function* parseSse( stream: ReadableStreamBufferSource, onComment?: (comment: string) void, ): AsyncGeneratorstring { const events stream .pipeThrough(new TextDecoderStream()) .pipeThrough(new EventSourceParserStream({ onComment })) for await (const { data } of events) { yield data if (data DONE) return } throw new LlmError(SSE stream ended without [DONE], STREAM_CLOSED) }新的parseSse只做三件事字节 → 文本通过new TextDecoderStream()处理流式 UTF-8 解码天然解决一个字符被网络分块拆开的问题文本 → 事件通过new EventSourceParserStream({ onComment })完成 SSE 分帧包括\r?\n\r?\n事件块切分、data:载荷提取与多行拼接、注释行: ...与event:/id:/retry:等非数据字段的跳过以及前导 BOM 剥离DeepSeek 协议收缩逐事件yield data遇到字面量[DONE]即正常返回若流结束仍未见到[DONE]则抛出LlmError(SSE stream ended without [DONE], STREAM_CLOSED)。整个组合只用到 Node ^22.19 引擎下限就内置的 Web Streams 原语TextDecoderStream、pipeThrough、可异步迭代的ReadableStream因此不需要额外的运行时垫片。模块的 JSDoc 也明确标注了新职责边界分帧、块重组、UTF-8/CRLF/BOM、注释与字段跳过、多data:拼接都属于eventsource-parser的合约本模块只保留 DeepSeek 协议层。依赖变化重构后eventsource-parser正式成为llm-deepseek的第二个运行时依赖第一个是deepseek-ai/schemastery。在 package.json 中可以确认dependencies: { eventsource-parser: ^3.1.0, deepseek-ai/schemastery: workspace:^ }lockfilepnpm-lock.yaml中锁定的版本为eventsource-parser3.1.0且该包在锁文件中被标记为{}零传递依赖与零依赖的声明一致。调用链从 HTTP 响应体到 StreamChunkparseSse处于 DeepSeek 直连适配器的传输层末端。在 adapter.ts 的request()私有生成器中响应体经过一次调用被直接送入翻译层if (!response.body) { throw new LlmError(DeepSeek API returned no response body, EMPTY_RESPONSE) } yield* translate(parseSse(response.body, onActivity))其中onActivity是传输活跃度回调——它被透传给EventSourceParserStream({ onComment })的注释回调用于给适配器的空闲看门狗idleWatchdog默认DEFAULT_STREAM_IDLE_TIMEOUT_MS 300_000见 adapter.ts提供心跳脉冲同时保证 SSE 注释行永远不进入业务载荷流。这一点在 sse.ts 的文档注释中有明确约定comments never enter the yielded payload stream。下游的 translate.ts 消费parseSse产出的字符串序列每个非[DONE]载荷被JSON.parse为 wire chunk解析失败抛MALFORMED_RESPONSEdelta.reasoning_content、delta.content、delta.tool_calls分别累积为 reasoning / text / tool-call 三类块逐段产出reasoning-delta、text-delta、tool-call-deltafinish_reason与usage被延迟挂起直到遇见[DONE]才统一发出block-end、usage、finish从而兼容finish 附带 usage与末尾独立 usage 块两种形态并保证 finish 之后不再有任何块若没有[DONE]就耗尽理论上parseSse会先抛错translate 兜底抛出同样的STREAM_CLOSED。也就是说parseSse与translate通过以[DONE]结尾的字符串序列这一协议解耦前者管传输与分帧后者管业务语义。测试收缩只钉 DeepSeek 协议合约重构最重要的删减发生在测试侧。旧的tests/sse.spec.ts用约 108 行重新证明了 SSE 规范行为跨块 UTF-8、CRLF、多data:拼接、冒号后无空格新版本将这些全部视为eventsource-parser的合约不再重复验证只保留 DeepSeek 协议层测试用例见 tests/sse.spec.ts验证的合约产出载荷并最终产出[DONE]哨兵正常流data: {a:1}\n\ndata: [DONE]\n\n→[{a:1}, DONE]注释带外上报且不产出: keep-alive只进入onComment回调不进入载荷流[DONE]后停止产出即使后面还有data: {late:1}也不再 yieldEOF 未到[DONE]抛STREAM_CLOSED正常结束却无哨兵 截断空流抛STREAM_CLOSED空响应 截断事件中途关闭抛STREAM_CLOSEDdata: {a未闭合 截断尾部[DONE]缺少空行终止符视为截断规范严格分帧未以空行终止的事件不会分发测试通过bytes(...fragments)辅助函数把多个字符串片段当作多次网络读取来构造输入流再用collect收集生成器产出——这种写法让分块边界对解析层完全透明正好印证了新架构的职责划分分帧容错是库的合约协议判定是本模块的合约。一个有意的行为偏差丢失尾部冲刷重构引入了一处有意的健壮性回退值得使用者特别注意旧手写解析器会冲刷最后一个缺少终止空行的事件块——也就是说如果流以data: [DONE]结尾且没有末尾的\n\n旧实现仍会正常产出[DONE]并优雅结束。而eventsource-parser是规范严格的事件只在空行终止符处分发因此这种尾部形态现在会被判定为STREAM_CLOSED截断错误。决策笔记和 sse.spec.ts 都明确记录了这一定性真实厂商和仓库内的dsh-llm-mock-server见 packages/llm/llm-deepseek/tests/mock-server.ts总是正确终止每个事件冲刷只是一个从未被观察到的健壮性修饰而不是真实厂商形态——所以缺失终止符在语义上更接近截断而非可恢复事件。如果你在对接自定义的 OpenAI 兼容端点时发现流在末尾报STREAM_CLOSED优先检查你的服务端是否漏发了最后一个空行。另一个顺带获得的收益BOM 与 maxBufferSize除了解析职责转移eventsource-parser还带来了两处手写解析器没有的能力sse.ts 模块注释对此有明确说明剥离前导 BOM手写解析器在遇到data:前缀之前若夹带一个 UTF-8 BOM 会匹配失败库则直接处理maxBufferSize硬化可对事件缓冲区大小设上限防御超长事件块的资源消耗这是手写版本完全没有的防护。这两点均来自库本身的能力可参考eventsource-parser包的流式 API 文档按需开启。备选方案回顾决策笔记记录了被否决的另外两条路线保留手写解析器在双适配器设计验证twin-adapters决策下看起来合理——dsh-llm-deepseek被刻意设计为 pi-ai 适配器的手写对照版本。但该决策的承重区分在于拥有 fetch/translate 内部实现 vs 委托给完整厂商 SDK而一个约 700 字节的 SSE 微解析器只是传输管道不是被验证的设计本身。这条理由被明确写入了更新后的 twin-adapters 决策文档The twin identity is owning the fetch/translate internals rather than delegating to a full provider SDK, not hand-rolling transport plumbing.createParser({ onEvent })回调 API可以用手写TextDecoder循环驱动但pipeThrough的流式组合能删除更多手写代码因此最终选择了EventSourceParserStream。重构后果与经验总结这次重构的最终后果可以归纳为三点与决策笔记的 Consequences 一一对应协议面收敛剩余的 shim 只编码 DeepSeek[DONE]/STREAM_CLOSED协议SSE 分帧边界情况成为eventsource-parser的合约不再在本仓库重复证明。测试从重证规范收缩为钉协议维护成本显著下降。健壮性语义更严格如上文所述未以空行终止的尾部[DONE]从被冲刷变为STREAM_CLOSED测试固化的是新语义。文档同步更新twin-adapters 决策文档中hand-rolled fetch SSE parsing的表述随之收窄为direct fetch with library-framed SSE并在同一变更中更新而不是留下过期声明dsh-llm适配器的 JSDoc 也做了同步修改。从项目工程实践角度看这是一次教科书式的传输管道交给成熟库、业务协议自己持有的拆分eventsource-parser因其事实标准地位AI SDK / MCP SDK 同款、零依赖与既有传递依赖身份而入选替换后llm-deepseek的运行时依赖仅从 1 个增至 2 个换来的是约 67 行源码与约 108 行测试的净删减以及 BOM 处理、缓冲上限等顺带硬化。若你想深入本模块的其余部分可以继续阅读 translate.tswire chunk 到StreamChunk的翻译、adapter.ts直连 fetch 适配器的完整请求/重试/看门狗逻辑以及 twin-adapters 决策文档双适配器设计验证的完整来龙去脉。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考