DeepSeek Harness 事件域语义会话是事实日志agent 是实时事件通道【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本篇技术指南解析 DeepSeek Harness 内部一条贯穿智能体循环agent loop、持久化与会话回放的架构约定session/*、agent/*、tools/*三个事件域如何各司其职以及持久的可回放事实是SessionEvent实时拦截或瞬态/活对象信号是agent/toolsCordis 事件这条边界规则。读完你将掌握事件到底应该写入会话日志还是作为实时事件发出、轮次/步骤边界为什么只能从session/event读取、以及作为插件作者或 Claude Code / Codex 钩子桥接的开发者在编写监听器时应如何选择订阅面。本文以仓库内已实现的架构决策记录 2026-06-30-event-domain-semantics.zh.md 为核心骨架并结合packages/core/session与packages/core/agent-loop的源码实现加以印证。背景事件域边界为何需要被固定DeepSeek Harness 通过 Cordis 事件分类体系扩展 agent loop详见微内核事件分类体系 Agent Note。随着该分类体系不断增长三个事件域之间的界限开始变得模糊session/*承载持久的、事件溯源的日志SessionEventMap。agent/*承载运行时实时信号向插件传递Agent句柄。tools/*承载工具注册表与执行流水线。两个具体问题促使团队固定语义。第一若干轮次/步骤边界此前同时作为持久的SessionEventturn/start、turn/end、step/start、step/end和镜像的agent/*emitagent/turn-start、agent/turn-end、agent/step-start、agent/step-end存在。消费方对同一事实拥有两个真源每次生命周期变更都必须同时更新两处极易产生不一致。第二钩子子系统需要一个连贯且有文档的订阅表面——插件作者以及基于其上的 Claude Code / Codex 钩子桥接必须在不阅读循环代码的情况下知道应该监听会话事件还是 agent 事件以及为什么。这套词汇是拦截决策、持久的hook/*日志以及 Claude Code 和 Codex 桥接的共同基础。决策三个域各司其职session/*——持久的、可回放的事实日志session/*域拥有SessionEventMap。在源码中该映射定义于 packages/core/session/src/types.ts其中四个边界事件被明确声明为持久事实export interface SessionEventMap { // ... turn/start: { turn: number } turn/end: { turn: number; reason: TurnEndReason } step/start: { turn: number; step: number } step/end: { turn: number; step: number } }该域遵循三条约束每条记录仅含 JSON不含活对象——事件可以序列化、落盘、回放不依赖运行时内存中的对象身份。每次追加触发一次session/eventemit并伴随session/flush并行持久性检查点保证日志在持久化层面可被安全追踪。它是实时 transcript文本记录的唯一源想渲染或响应已发生事件的消费方在此订阅因此实时渲染与回放投影共享同一条路径——实时看到的、与回放得到的是同一份数据不存在两个真源。此外轮次中途的 steering转向指令作为持久的user/message存在于会话日志中Assistant stream 的证据只在一个assistant/message或assistant/attemptsettlement 内才变为持久事实。这些事件类型同样定义在 types.ts。agent/*——运行时实时表面agent/*域始终携带活的Agent用于实时拦截与观测。从 packages/core/agent-loop/src/agent.ts 的实现可以归纳出它的具体成员拦截 waterfall瀑布式事件agent/pre-step见 agent.ts、agent/request见 agent.ts、agent/request-error见 agent.ts负责变换、拒绝或恢复请求。awaited 停止观测agent/turn-stopping通过dispatch.serial被串行等待见 agent.ts用于观察停止边界。瞬态 emit报告生命周期、状态、inbox 插入、领取与丢弃、错误以及进程本地的agent/assistant-streamframe见 agent.ts。关键界限轮次和步骤边界不在此处——它们是从session/event读取的持久 Session event不再由agent/*镜像。tools/*——工具注册表与执行流水线该域负责工具注册表与执行流水线相关信号与持久会话日志无关本文不展开。边界规则用一条规则统一三个域持久的、可回放的事实是SessionEvent实时拦截或瞬态/活对象信号是agent/toolsCordis 事件。推论轮次或步骤边界是持久事实因此存在于会话日志中并从session/event源读取——不会被镜像为agent/*emit。这条规则是判断一切事件归属的决策判据信号特征归属域典型事件持久、可回放、纯 JSONsession/*turn/start、turn/end、step/start、step/end、user/message、assistant/message实时拦截、变换、拒绝/恢复agent/*agent/pre-step、agent/request、agent/request-error瞬态/活对象信号、进程本地流agent/*agent/turn-stopping、agent/assistant-stream、生命周期与 inbox 相关 emit工具注册与执行流水线tools/*工具注册表相关事件将规则应用于边界镜像四个镜像事件被移除将上述边界规则落到曾经的双重记录实现上结论非常明确全部四个边界镜像——agent/turn-start、agent/turn-end、agent/step-start、agent/step-end——被移除。原因与证据如下没有生产消费方需要在边界处获取活的Agent。ACPAgent Client Protocol桥接将其进行中的提示词与精确对应的session/eventturn/start/turn/end事件对关联其他 transcript 消费方同样从持久流派生边界。这一决策由移除边界镜像事件 Agent Note 负责记录与执行。移除 emit 简化了循环的closeStep/closeTurn各只需一次 append无需配对 emit。closeStep仅追加step/endcloseTurn仅追加turn/end不再存在日志一份、实时一份的双写问题。在 packages/core/agent-loop/src/agent.ts 中可以验证当前实时事件集合只包含agent/pre-step、agent/turn-stopping、agent/assistant-stream、agent/request、agent/request-error等而四个边界镜像事件不再出现——与文档所述已移除状态一致。后果与实现细节循环行为从双写到单写循环不再 emit 任何边界镜像closeStep仅追加step/endcloseTurn仅追加turn/end。Session.append负责post-commit observer 隔离抛出异常的边界 observer 无法改变轮次结果也不会饿死后续消费方但事件接纳失败或内部校验失败仍会在边界进入日志之前向外抛出——失败可见性没有被吞掉只是与 observer 的行为解耦。stepOpen标记的语义变得精确循环仅在append(step/start)返回后才标记步骤已打开stepOpen true。内部分发校验在日志推入之前运行可能在不打开步骤的情况下拒绝post-commitsession/eventobserver 的失败被隔离在Session.append内部。因此该标记精确表示已提交的、欠一个后续step/end的边界。测试迁移行为随测试一同迁移之前通过已移除 emit 观察边界的测试现在观察持久的turn/start/turn/end/step/start/step/end会话事件——它们所锁定的行为边界顺序、步骤计数不变只是读取的源移到了规范源。而那些抛出异常的轮次边界 emit 监听器的用例被删除因为该代码路径不再存在没有 emit 可供抛出。这遵循了根目录 AGENTS.md 中测试记录行为而非黄金真相的原则行为与其测试一同迁移或一同消亡测试断言的是行为本身而不是某个实现巧合。事件表面收敛生成的 Cordis 事件表面docs/subsystems 各页不再列出镜像事件。这意味着所有面向插件作者的事件文档都与实际运行时行为一致不存在文档里写着、代码里没有的幻影事件。例外agent/steering单独处理agent/steering它不是边界镜像不在本文档的移除范围内它由后续的移除agent/steering镜像 emit Agent Note 单独移除——因为它镜像的是持久的中途 steeringuser/message属于同一类持久事实被重复实时镜像的问题但生命周期与边界事件不同需要独立决策与迁移。对插件与桥接开发者的订阅指南基于上述语义订阅决策可以简化为一条经验法则需要渲染、回放、统计或审计已经发生的事情包括轮次/步骤边界、消息、转向指令→ 订阅session/event从持久SessionEventMap读取。需要在事情发生前拦截、变换或拒绝请求级→ 订阅agent/pre-step、agent/request、agent/request-error这类 waterfall。需要观测停止边界或进程本地的流式帧→ 订阅agent/turn-stopping、agent/assistant-stream。只要遵循持久事实进会话日志、实时信号走 agent 事件的规则插件作者和 Claude Code / Codex 钩子桥接就不需要阅读 agent loop 的实现代码也能准确判断监听对象。延伸阅读事件域划分的上游依据微内核事件分类体系 Agent Note会话事件溯源的总体设计事件溯源会话 Agent Note移除边界镜像事件的完整实现说明移除边界镜像事件 Agent Note移除agent/steering镜像的后续决策移除agent/steering镜像 emit Agent Note事件类型与SessionEventMap的源码定义packages/core/session/src/types.tsagent 实时事件的实际实现packages/core/agent-loop/src/agent.ts测试与实现的原则约定AGENTS.md【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考