人工智能AI AgentAgent 框架DeepSeek【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址https://gitcode.com/gh_mirrors/de/deepseek-harness点击查看免费下载导读本篇技术文章基于 DeepSeek Harness 仓库中已落地的架构决策笔记2026-08-06-agent-event-payload-objects.md状态为 implemented深入剖析 Agent 作用域事件从位置参数 松散约定演进为单 payload 对象 融合 dispatcher的完整设计历程。读者将掌握十二个agent/*事件与goal/changed事件的新签名契约、agentEvents/emitAgentEvent融合派发的底层原理主体注入与作用域键不可分叉的强制约束、ReactLoopAgent零分配热路径的实现方式以及这一决策对插件开发者监听器/发射器编写方带来的实际收益。问题背景位置参数事件契约的不可扩展性在本次架构调整之前DeepSeek Harness 中的 Agent 作用域事件采用**位置参数positional arguments**约定。一个典型的事件签名由三部分组成开头的agent主体subject事件专属的字段event-specific fields末尾的next回调用于 waterfall/serial 类型的事件链。这种约定带来的核心痛点在于契约分散在参数列表中而不是集中在一个具名 payload 中。具体表现为新增字段即重写所有调用方任何一次字段扩展都迫使跨包across packages重写每一个监听器listener和发射器emitter退役上下文类型即全局重构例如PreStepContext与RequestFailureContext这类为事件专门包装的上下文类型一旦需要退役所有引用它们的位置都要同步修改可读性差调用方必须记住参数的顺序和含义无法从单个具名对象中直观理解事件的完整形状。从源码可以确认旧设计中的PreStepContext与RequestFailureContext正是这类为事件专门包装的中间类型——它们在本次调整中被正式退役其字段直接平铺进了agent/pre-step与agent/request-error的 payload 中见下文事件清单。决策每个 Agent 事件只接收一个 payload 对象本次架构决策的核心原则可以概括为一句话每个 Agent 作用域事件恰好接收一个 payload 对象作为其第一个参数。统一的 payload 契约新约定下payload 对象的内部结构遵循固定规则payload 组成部分说明agent事件主体subject始终携带由 dispatcher 注入事件专属字段每个事件各自的业务字段直接平铺在 payload 上signal当事件支持取消时携带的AbortSignal如agent/pre-step、agent/request、agent/turn-stoppingnext末尾参数仅 waterfall/serial 事件保留始终是最后一个参数不属于 payload其中next保持为最后一个参数这一细节非常关键它意味着对于链式事件监听器仍然能通过末尾的next进行围绕式around-middleware组合但所有业务数据都统一收拢到第一个具名 payload 中。受影响的事件范围本次调整覆盖三类事件合计 14 个十二个agent/*事件——在 packages/core/agent/src/runtime-types.ts 中有完整的类型声明agent-loop/config-start-failed——唯一没有主体的特例事件直接从 context 发射不走作用域载体验证goal/changed——由 goal 域声明的 Agent 作用域事件。十二个agent/*事件完整签名清单以下签名均出自 packages/core/agent/src/runtime-types.ts 的Events声明可作为插件开发者编写监听器的权威参考。所有事件的第一个参数都是 payload 对象且监听器通过this: ScopedAgent声明作用域载体契约纯通知型事件emit 派发返回 voidpayload 无 signal事件名payload 形状触发语义agent/created{ agent }Agent 创建并发布agent/disposed{ agent }Agent 销毁与 created 配对agent/status{ agent, status }状态迁移idle / runningagent/inbox/inserted{ agent, message }消息进入 inboxagent/inbox/claimed{ agent, message, turn }消息被 step 认领agent/inbox/discarded{ agent, message }消息被丢弃agent/error{ agent, turn, step, error }步骤级错误上报含未知类型错误串行链事件serial 派发事件名payload 形状说明agent/turn-stopping{ agent, turn, signal }turn 结束前的收尾钩子按序 await 所有监听器waterfall 围绕式事件waterfall 派发末尾带next回调事件名payload 形状next 返回类型agent/pre-step{ agent, messages, turn, step, signal }PromisePreStepDecisionenter / rejectagent/request{ agent, turn, step, signal }PromiseLlmCallConfig请求配置提案agent/request-error{ agent, turn, step, provider, failure, retryPolicy, signal }PromiseRequestErrorAction重试或终止从这些签名可以清楚看到旧PreStepContext与RequestFailureContext的字段去向agent/pre-step的 payload 直接携带messages/turn/step/signalagent/request-error的 payload 直接携带provider/failure/retryPolicy/signal中间上下文类型不再需要。特例事件agent-loop/config-start-failed该事件声明于 packages/core/agent-loop/src/index.tsagent-loop/config-start-failed(payload: { sessionId: SessionId; error: unknown }): void它是唯一没有主体的受影响事件——事件本身携带会话 ID 与错误信息由 loop 在配置启动失败时从ctx直接发射见同文件 L394 附近的发射逻辑const args: unknown[] [agent-loop/config-start-failed, { sessionId, error }]监听器异常同样被单独捕获并以errorChain记录告警避免污染生命周期。goal/changed事件声明于 packages/goal/goal/src/domain.tsgoal/changed(this: import(deepseek-ai/dsh-scope).ScopedAgent, payload: { agent: Agent; change: GoalChanged }): void作为 goal 域中受 Agent 作用域约束的事件它同样遵循payload 携带agent主体的约定监听器声明ScopedAgent的this从而纳入融合派发表面见下文AgentSubjectEvent类型推导。核心实现融合 dispatcher 的源码级剖析本次决策的落地核心位于 packages/core/agent/src/dispatch.ts。该文件实现了融合fused派发机制——把主体注入与作用域派发两个动作合并到唯一的注入点。AgentSubjectEvent类型层面的自动收编dispatch.ts 通过类型推导自动识别哪些事件属于 Agent 主体事件dispatch.tsexport type AgentSubjectEvent { [K in keyof Events]: Events[K] extends (this: ScopedAgent, ...args: infer P) unknown ? P extends [infer Payload, ...unknown[]] ? Payload extends { agent: Agent } ? K : never : never : never }[keyof Events]这个条件类型同时检查两个条件this必须是ScopedAgent——声明作用域载体契约第一个参数必须是携带agent: Agent字段的 payload 对象。这一双重检查有实际意义它可以排除碰巧携带agent字段的普通事件其this不是ScopedAgent以及零参数事件其参数元组无法通过 rest-tuple 检查确保它们不会误入融合派发表面。agentEvents(ctx, agent)唯一的主体注入点agentEvents是融合 dispatcher 的工厂函数其签名与行为如下export function agentEvents( ctx: Context, agent: Agent, carrier: ScopedAgent agentCarrier(agent), ): AgentEventDispatch其核心机制包含两个层面1. 主体注入subject injection内部通过fused闭包把agent注入到调用方传入的 payload 剩余字段中const fused K extends AgentSubjectEvent(payload: PayloadRestK): PayloadOfK ({ ...payload, agent } as PayloadOfK)注意这里的展开顺序——agent字段在展开之后写入。这正是注入的主体优先的实现保障即使某个结构上可接受的 payload 碰巧自带agent字段也无法覆盖 dispatcher 注入的权威主体。从类型层面PayloadRestK OmitPayloadOfK object, agentdispatch.ts已经保证了调用方根本传不进agent字段。2. 作用域载体耦合scope-carrier coupling每次派发都以carrierscopeTarget(agent, agent)生成的载体dispatch.ts作为thisArg调用 Cordis 事件机制从而保证作用域载体键与 payload 的agent不可能分叉——监听器只能在对应 Agent 的作用域内收到事件而 payload 中的agent又恰好是那个 Agent。三种派发模式的统一入口AgentEventDispatch接口dispatch.ts为每个 Agent 主体事件统一提供三种派发方法方法底层机制语义事件示例emit(name, payload)手写遍历回调不依赖 Cordisemit的Array.mapfire-and-forget 通知逐监听器隔离同步抛出与 Promise 拒绝一个监听器失败不影响后续监听器agent/status、agent/errorserial(name, payload)Cordisserial按序 await 的串行链agent/turn-stoppingwaterfall(name, payload, ...rest)Cordiswaterfall围绕式中间件链rest的末元素即最内层nextagent/pre-step、agent/request、agent/request-error其中emit的实现尤其值得注意dispatch.ts它没有直接调用 Cordis 的ctx.emit而是通过ctx.events.dispatch(emit, args)取回调集合后自行遍历。原因写在注释里——Cordis 的emit通过Array.map调用回调一个同步抛出会饿死后续监听器返回的 Promise 会被直接丢弃而 Agent 通知属于非否决型non-vetoing事件所以 dispatcher 自行解析过滤后的回调集合用 try/catch Promise.resolve(...).catch把每个监听器的失败独立记录到ctx.logger.warn既不会否决生命周期推进也不会饿死后续观察者。这一点在 packages/core/agent/tests/agent.spec.ts 中有直接测试佐证同步抛出与异步拒绝的监听器互不影响后续监听器仍能收到status。emitAgentEvent一次性发射的便捷路径对于只发射一次的调用方dispatch.ts 还提供了一次性便捷函数dispatch.tsexport function emitAgentEventK extends AgentSubjectEvent( ctx: Context, agent: Agent, name: K, payload: PayloadRestK, ): void { agentEvents(ctx, agent).emit(name, payload) }它的语义等价于agentEvents(ctx, agent).emit(...)但由于每次调用都会临时构建 dispatcher因此只适合一次性发射——反复发射的场景应当使用下文ReactLoopAgent的做法构造函数中构建一次、反复复用。派生工具assembleContextFordispatch.ts 还导出了assembleContextFor(agent, signal?)dispatch.ts用于构建 prompt 组装上下文同时设置{ agent, scope: agent, ...(signal ? { signal } : {}) }保证 agent 作用域的 prompt 与工具贡献不会被静默遗漏。零分配热路径ReactLoopAgent 的 dispatcher 复用文档中的一句关键结论是ReactLoopAgent在构造函数中构建一次 dispatcher并将每个 emit、serial 和 waterfall 都经由它路由因此热路径上的 dispatch 不产生任何分配。这一点在 packages/core/agent-loop/src/agent.ts 中得到完整印证1. 构造函数构建一次L93this.dispatch agentEvents(loopCtx, this)ReactLoopAgent在构造时就把 dispatcher 存为私有字段private readonly dispatch: AgentEventDispatch见 L79 注释Fused dispatcher, built once in the constructor so hot-path dispatches never allocate。2. 事件全部经由该 dispatcher 路由例如inbox 生命周期L94-L98this.dispatch.emit(agent/inbox/inserted, { message })、agent/inbox/discarded、agent/inbox/claimed状态迁移L116setPhase中this.dispatch.emit(agent/status, { status })错误上报L213this.dispatch.emit(agent/error, { turn, step, error })pre-step 决策链L241-L247this.dispatch.waterfall(agent/pre-step, { messages: claimed, ...position, signal }, next)——这里的signal就是当前回合的取消信号next是默认的 enter 决策turn 收尾L303this.dispatch.serial(agent/turn-stopping, { turn, signal })请求配置提案L476-L479this.dispatch.waterfall(agent/request, { turn, step, signal }, next)请求失败处理L390-L400this.dispatch.waterfall(agent/request-error, { turn, step, provider, failure, retryPolicy, signal }, next)。由于agentEvents的第三参数carrier默认可省略内部agentCarrier(agent)每次调用会重新生成载体agent-loop的构造函数通过一次性调用规避了反复构建载体的开销而fused闭包中agent的注入不需要额外分配。可以推断loop 每个 step 的 dispatch 只产生 payload 对象的构造开销而不会产生载体、dispatcher 或闭包的重复分配这正是文档所说hot-path dispatches allocate nothing的工程含义。备选方案为什么不做位置签名或手工构造主体文档记录了两种被否决的备选方案理解它们能更清楚地看到最终决策的权衡备选方案一保留位置签名代价新增字段或退役上下文类型依旧需要重写每个监听器和 emitter契约继续分散在参数列表否决理由与本次要解决的问题完全同构等于不解决问题。备选方案二在每个 dispatch 位置手工构造主体做法loop 的中间设计曾调用ctx.waterfall(this.carrier, …)并传入手工构造的{ agent: this, … }payload优点避免了每次 dispatch 的分配致命缺点主体注入逻辑被复制到每个 dispatch 位置一旦某个位置漏写或写错作用域键scope key与 payload 主体就会分叉——监听器收到的事件其agent字段与事件实际所在的作用域不一致造成难以排查的跨域泄漏否决理由融合 dispatcher 将主体注入收敛为唯一注入点所有派发模式emit/serial/waterfall共用从结构上消除分叉可能。决策收益面向插件开发者的实践结论本次决策的直接收益可以归纳为三点全部可以在仓库源码中找到依据一次形状变更one-shape change监听器签名一次性命名完整 payload见 runtime-types.ts 中全部事件的payload单参数声明扩展 payload 或退役上下文类型对所有监听器和发射器都是同一次形状变更而非跨包逐点重写。主体/作用域耦合由 dispatcher 强制agentEvents(ctx, agent)同时注入主体并选择载体scopeTarget(agent, agent)调用方无法传入与载体不一致的agent字段类型层PayloadRest已剔除运行层展开顺序保证注入优先所有派发模式共用该约束。热路径零分配ReactLoopAgent在构造函数构建一次 dispatcher 并复用emit/serial/waterfall 全部经它路由loop 热路径的 dispatch 保持分配友好。对于在 DeepSeek Harness 中编写插件的开发者这意味着新的监听器编写范式是ctx.on(agent/xxx, ({ agent, ...fields }) { ... })——第一个参数即完整 payload无需再记忆参数顺序发射方则应优先通过ctx.agents取得 Agent 后使用agentEvents(ctx, agent)复用场景或emitAgentEvent(ctx, agent, name, payload)一次性场景。延伸阅读架构决策笔记原文2026-08-06-agent-event-payload-objects.md 及中文版融合 dispatcher 实现packages/core/agent/src/dispatch.ts事件类型声明权威签名packages/core/agent/src/runtime-types.ts零分配热路径实现packages/core/agent-loop/src/agent.tsgoal/changed事件声明packages/goal/goal/src/domain.tsagent-loop/config-start-failed事件声明与发射packages/core/agent-loop/src/index.ts事件契约回归测试packages/core/agent/tests/agent.spec.ts 与 packages/core/agent-loop/tests/contract-regressions.spec.ts作用域体系相关笔记2026-07-08-agent-scope-contexts.md 与 2026-07-12-agent-scope-runtime-design.md赞分享人工智能AI AgentAgent 框架DeepSeek【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址https://gitcode.com/gh_mirrors/de/deepseek-harness点击查看免费下载相关推荐DeepSeek Harness Agent 作用域架构以 agent.ctx 为核心的单层注册隔离设计DeepSeek Harness Agent 作用域架构以 agent.ctx 为核心的单层注册隔离设计 本文围绕 DeepSeek Harness 中已落地人工智能AI AgentAgent 框架DeepSeekDeepSeek Harness 事件精简实践移除 agent/stream-chunk 镜像事件让 session/event 成为唯一 Token 流事实源DeepSeek Harness 事件精简实践移除 agent/stream chunk 镜像事件让 session/event 成为唯一 Token 流事人工智能AI AgentAgent 框架DeepSeekDeepSeek Harness 发起 Agent 作用域设计基于 AsyncLocalStorage 的进程内信任链DeepSeek Harness 发起 Agent 作用域设计基于 AsyncLocalStorage 的进程内信任链 导读 本文剖析 DeepSeek Ha人工智能AI AgentAgent 框架DeepSeek创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考