DeepSeek Harness 事件体系精简移除agent/stream-chunk让 token 流回归单一真源【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本篇文章聚焦 DeepSeek Harnessdeepseek-ai系列包组成的插件化智能体运行时内部一次关键的架构收敛决策从 agent 事件分类体系中移除agent/stream-chunk实时事件使模型 token 流只以持久化的assistant/chunk会话事件作为唯一真源。你将了解到双真源问题为何有害、为什么持久化分片被裁定为权威、实时镜像事件为何是冗余以及插件应如何迁移到session/event订阅。核心决策记录见 Agent Note: Stop mirroring the token stream as an agent event中文版该记录已标记为implemented已实施并于 2026-07-27 归档。问题同一份 token 事实被同时写入两个真源在 DeepSeek Harness 的 agent loop智能体循环实现中模型生成的每一个 token delta 曾经被同时做两件事持久化作为assistant/chunk会话事件写入会话日志实时发射作为携带完全相同数据的agent/stream-chunkCordis 事件广播给订阅者。在当时的 agent loop 驱动实现 中这两行代码仅相隔一行const chunkEvent session.append(assistant/chunk, { turn, step, chunk }) chunkSeqs.push(chunkEvent.seq) ctx.emit(agent/stream-chunk, agent, turn, step, chunk) // ← the mirror两条通道的数据完全一致通道事件载荷语义持久事件assistant/chunk{ turn, step, chunk }会话日志中的 token 级记录可回放实时事件agent/stream-chunk(agent, turn, step, chunk)并行实时广播额外携带Agent句柄关键证据在于实时发射相比会话事件唯一多出的东西就是实时的Agent句柄而当时唯一的消费方直接丢弃了它——其处理函数签名是(_agent, _turn, _step, chunk)四个参数中前三个全部弃用。也就是说这个实时事件除了制造冗余之外没有提供任何被实际使用的增量信息。这种重复与 DeepSeek Harness 此前为轮次/步骤边界消除的边界镜像是同一类问题消费方面对同一个持久事实的两个真源每次变更都必须同时触及两者——会话事件要 append、镜像事件要 emit还要同步维护文档、不变量检查、测试与快照期望。参见先前已实施的决策记录 Agent Note: Stop mirroring durable boundaries as agent events该记录移除了agent/turn-start、agent/turn-end、agent/step-start、agent/step-end四个边界镜像事件。值得注意的是边界镜像移除时刻意推迟了对分片流的处理当时给出的理由是assistant/chunk持久化仍承载关键约束所以以后可以将分片流作为镜像评估但那是一项独立决策。本文所依据的这份 Agent Note正是那项独立的决策。前提已定持久化分片是权威且将保留推迟处理所依赖的前提在移除方案被单独否决后已经明确。反向提案 Agent Note: assembled assistant messages only位于 rejected 目录即已否决曾建议停止持久化分片、仅保留瞬态实时流事件但被否决原因是以下三类关键能力都依赖持久化的assistant/chunk序列高保真回放逐 token 级别的回放需要原始分片序列部分失败的流流中途中断如达到 max-tokens、被取消时已交付的文本/推理前缀需要从分片还原快照回放会话快照的恢复同样依赖分片级记录。会话子系统文档也印证了这一地位——在 会话事件词汇表 中assistant/chunk被明确定义为/** Raw stream chunk — token-level replay fidelity. */ assistant/chunk: { turn: number; step: number; chunk: StreamChunk }注释直接点明其用途是token 级回放保真度。StreamChunk一词本身来自 LLM 服务包核心llm包定义了消息、内容块与 stream-chunk 词汇供每个插件和会话日志共用各 provider 适配器只负责把自家 wire 格式翻译进这套词汇。也就是说assistant/chunk是持久的、承重的 token 流而agent/stream-chunk只是它的纯冗余镜像。决策移除agent/stream-chunksession/event成为唯一实时 transcript 流在前提确立后决策顺理成章从 agent 事件分类体系中移除agent/stream-chunk。token 流不再通过 Agent 优先的事件读取而是统一通过session/event以assistant/chunk的形式读取——持久化与回放本来就在使用同一个序列。由此session/event成为唯一的实时 transcript文本记录流承载assistant 分片assistant/chunk轮次/步骤边界turn/start、turn/end、step/start、step/end工具活动tool/call、tool/result等todo 等其余会话事件。从当前仓库源码可以验证该决策已落地。在 agent loop 的 step 执行体 中流式消费循环现在只剩持久化写入镜像发射已不存在for await (const chunk of stream) { signal.throwIfAborted() chunkSeqs.push(this.session.append(assistant/chunk, { turn, step, chunk }).seq) assembler.push(chunk) }分片序号chunkSeqs随后被用于assistant/message事件的sourceEventSeqs关联进一步说明会话日志中的分片序列是承重的构建材料而非可丢弃的旁路数据。消费方核查没有生产消费方需要 Agent 优先 的 token 镜像决策记录对三类潜在消费方逐一做了核查持久化、回放与交互式渲染器它们直接消费权威的会话流session/event本来就不依赖镜像仅面向自动化的 ACPAgent Client Protocol桥接层见 Agent Note: ACP automation-only protocol它发出的是已提交的assistant/message文本而非原始分片因此两种分片事件持久事件和镜像事件它都不需要其他生产消费方没有任何一个需要在分片时刻拿到Agent优先的 token 镜像。由此得出结论实时发射相对会话事件多出的Agent句柄没有消费价值整个镜像事件是纯冗余。范围界定移除什么保留什么决策边界非常清晰只移除实时镜像绝不动持久化移除agent/stream-chunk—— 仅此一个事件。未触及事件保留原因assistant/chunk持久会话事件权威 token 流原样保留。本决策移除的是实时镜像而非持久化移除持久化的提案已单独遭到否决见上文 assembled assistant messages onlyagent/steering它是控制信号不是 token 流其持久孪生事件是steering/message镜像发射由后续决策单独移除Remove theagent/steeringmirror emitagent/status、agent/error、agent/created/agent/disposed、agent/queued、agent/session-start生命周期/控制事件不是 transcript 数据也没有持久副本不在本次范围曾考虑的替代方案移除持久化、仅保留瞬态实时流——这是与最终决策相反方向的裁剪已被单独否决见 assembled assistant messages only高保真回放、部分失败的流以及快照回放都依赖持久化的assistant/chunk序列。既然持久化一侧被裁定保留实时发射自然就是配对中冗余的那一半。后果与插件迁移指南决策落地后插件 API 发生了如下变化不再可能从Agent优先事件观察 token 增量——agent/stream-chunk已从事件分类体系中消失。推荐的迁移方式订阅session/event按event.type assistant/chunk过滤当确实需要在分片时刻拿到实时Agent句柄时通过ctx.agents.get(session.id)直接按会话 id 查找。ctx.on(session/event, (session, event) { if (event.type ! assistant/chunk) return const { turn, step, chunk } event.data // 需要实时句柄时再按需查找 const agent ctx.agents.get(session.id) // …处理分片 })决策记录明确指出没有生产消费方需要在分片时刻取得实时Agent这与边界镜像移除所做的取舍相同均可接受。分片级消费方本就不应依赖一个可能与持久日志发生漂移的第二事件馈送。延伸agent/*事件的分类学总结通过这份记录可以归纳出 DeepSeek Harness 对agent/*事件的一条清晰分类原则凡是存在持久孪生事件session 事件的实时镜像一律移除——agent/turn-start等四个边界镜像边界镜像移除、agent/stream-chunk本记录、agent/steeringsteering 镜像移除先后被清理没有持久副本的生命周期/控制事件agent/status、agent/error、agent/created/agent/disposed、agent/queued等继续保留为实时事件因为它们不是 transcript 数据。这背后的工程原则值得插件开发者借鉴一份持久事实只应有一个真源。会话日志session/event是唯一的实时 transcript 流所有渲染、回放、持久化消费方统一从它读取agent/*事件只承载生命周期与控制信号。这也让 agent 事件的分发机制得以保持轻量——在 agent 事件分发实现 中agentEvents构建的融合分发器只对真正的 agent-subject 事件处理函数首个参数为携带agent的载荷、this为ScopedAgent进行作用域绑定分发事件分类体系越精简类型安全边界就越清晰。对于维护 DeepSeek Harness 插件生态的开发者理解这条决策有助于避免在新插件中重新引入会话事件 镜像事件的双写模式并正确选择事件订阅入口看 token 流订阅session/event看生命周期订阅agent/*控制事件。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考