DSH plugin 的 Agent 所有权:谁创建、谁持有句柄、拦截决策到底在哪一层生效
在 DSH plugin 里,Agent 不是随手构造的对象,而是一份带所有权的资源。 谁调用创建、谁收下句柄、谁能在哪一层拦截,是三件必须分开确认的事。分不清这三件事,插件就会出现“能拿到 Agent 却销毁不掉”“注册了钩子却没生效”的错位。 下文讲的 Agent、句柄与拦截,对 DSH插件 和 DeepSeek插件 是同一套契约。
三种身份:创建者、所有者、持有者
创建动作、生命周期所有权与会话身份是三件不同的事,混在一起写,跨插件传递时必然泄漏。(来源) 对照如下:
| 身份 | 指什么 | 代码里的体现 |
|---|---|---|
| 创建者 | 触发这次 agent 构造的调用方 | ctx.agents.create() 或 resume() |
| 所有者 | 持有句柄、能拆除它的一方 | AgentHandle.dispose() |
| 结构性所有者 | 提供工厂或服务 API 的提供方 | 提供方卸载时排空其创建的句柄 |
| 会话身份 | 持久日志的归属 | agent.id(SessionId) |
第一次读 core 页面容易忽略的一点是:agent/ 与 agent-loop/ 是一对包。前者声明 Agent 接口、实时注册表、发起者作用域与 agent/* 事件词汇;后者是公开约定的唯一具体实现。扩展插件依赖 agent,包括需要发起 Agent 时,而绝不直接依赖 agent-loop,这样循环才保持可替换。
你写插件时如果只是想按 agent 隔离注册,不需要碰循环,只需要认准 scope/ 提供的 createScope、scopeOf 与 scopeTarget。
create 与 resume:差别不在“新”
两条路径都返回 AgentHandle,但一个建立新会话,一个接管已持久化的会话。(来源) 选择依据:
create()— 在一个调用方提供的SessionId下构建全新会话与 agent。适合新任务、子代理派生、一次性实验。resume()— 先加载持久会话,再在新进程里恢复 agent。适合重启后继续、崩溃恢复、跨会话续跑。
CreateAgentOptions 携带共享标识以及新 agent 发布前所需的一切,逐项都有明确职责:
meta— 会话元数据,包含已校验的cwd、fork 谱系、isSeeded标记、来源分类、委派深度与agentPreset;inheritedEventCount— 精确的 fork cut,决定从父会话的哪一格切出;seed— 可选的回放前缀;agentOptions— 按 agent 的路由与输出设置;signal— 仅创建期有效的取消信号;setup— 发布前的装配回调。
ResumeAgentOptions 是持久标识的对应项,只有 resumeSessionId、agentOptions、signal 与 setup 四项。看到这里就能明白为什么两者不能互换:恢复路径没有 meta,也没有 fork cut,因为它的会话已经在盘上。
setup:唯一的发布前装配窗口
凡是希望“从第一个提示词起就生效”的注册,都必须经 setup 的 agentCtx 完成。(来源) 官方给出的顺序是:
- Session 入库,
session/created完成; setup(agentCtx, agent)被调用;- Agent 注册;
agent/created发出;- 第一次提示词组装。
这个顺序决定了一件事:凡经 agentCtx 注册的内容,都先于 agent/created 与第一次提示词组装存在。反过来说,如果你在 agent/created 之后再补注册,第一次组装就已经错过了。
setup 还有两个常被忽略的细节:其一,agentCtx 拥有作用域注册,显式 Agent 提供确切的子 Session,Context 不需要反向属性;其二,setup 可以返回一个同步 commit,它会在发布前一刻被调用。
回滚语义必须写进你的插件设计:setup 拒绝、commit 抛出、或所有者 dispose,三者走同一条撤销路径——移除 Session,但保留恢复出的待处理输入与已存储事件。换句话说,失败不会留下半个 Agent,也不会顺手把你辛苦恢复的输入删掉。
句柄上真正能做的事
Agent 是插件面向编程的 surface,它提供投递与观察,不提供任意改状态。(来源) 按用途分成四组:
- 投递 —
send(message, target, wakeup)直接暴露 target 与 wakeup 路由;followup()、steer()、inject()是固定预设的别名。 - 取消与收敛 —
cancel(cause, options)清空排队与 steering 工作并中止活跃轮次;whenIdle()等到整个 agent 活动归于静止。 - 维护 —
runMaintenance(task)从真正的空闲阶段跑一个非轮次任务,公开状态仍保持idle。 - 持久投影 —
inbox的nextTurn与nextStep、model的current()与select(),都是可回放的持久状态。
三个容易误读的地方值得单独记住:
status只有idle与running;dispose会把 agent 从注册表移除并发出agent/disposed,它不是第三种状态值。running描述的是整个驱动器的排空区间,可能跨越连续的排队轮次,因此它不能证明某个轮次仍然打开。followup()不返回句柄,它给的MessageId标识的是 inbox 的插入、认领与丢弃事实,不是之后的助手输出,也不是轮次结束。
initiator:因果归因,不是授权
ctx.agents 携带的 initiator 就是上面那个确切 Agent,不是单独的 frame,也不是复制的标识。(来源) 四个方法各有分工:
currentInitiator()— 读取继承来的发起者,边界外返回undefined,适合日志、追踪、指标这类允许无 agent 调用的场景;requireInitiator()— 读取并在无边界时抛错,适合契约上必须挂在 driver 之下的私有 helper;withInitiator(agent, operation)— 以一个确切 Agent 运行操作,同步值与 Promise 原样保留;withoutInitiator(operation)— 在隐藏继承发起者的边界内运行,适合懒加载的共享定时器、队列泵、连接池维护,避免它们继承第一个碰巧初始化它们的 Agent。
官方的警告要当成硬约束:环境中存在 initiator 既不能证明存活,也不代表授权。主体与所有者必须显式,worker、进程、持久化、wire 边界上的身份也必须显式。队列或 wire 接收方只有在校验显式身份并解析到确切存活 Agent 之后,才能建立这个边界,而 withInitiator 本身这两件事都不做。
拦截决策发生在 pre-step,不在句柄上
插件想影响“这一步跑不跑、跑哪些消息”,正式通道只有 agent/pre-step 一条。(来源) 它接收的 payload 携带三样东西:独占的已领取批次 messages、拟进入步骤的坐标 turn 与 step、以及当前轮次的取消 signal。返回值只有两种形态:
type PreStepDecision =
| { kind: 'reject' }
| { kind: 'enter'; messages: UserMessage[]; startsRequestSeries?: true }
reject 不会打开步骤。enter 提供在 step/start 后追加的完整消息批次。最终决策里被省略的已领取消息保持删除状态,而领取之后才插入的输入仍然留待后续处理。首次提案运行在已打开的轮次内、任何步骤开始之前;工具 continuation 可以在步骤之间提交空的已领取批次。
另外两个决策点不要和 pre-step 混用:
agent/request-error在失败的模型步骤关闭之后、其轮次关闭之前运行。listener 可以在失败轮次的 signal 仍存活时修复持久状态或等待策略工作;返回{ kind: 'retry' }且不调用next()即接管恢复,返回默认的undefined会让失败保持终态。agent/turn-stopping在轮次没有工具或 steering 后续时运行,且先于最后一次 steering 排空。
一条最小所有权链路的验证
把“创建→发起→拦截→结束”串起来跑一遍,比读十遍接口定义更能确认所有权。(来源) 五步:
- 用固定
SessionId调create(),在setup里注册一个探针服务,断言它在agent/created之前已可解析。 - 读
handle.agent.status,应为idle;调用followup()后进入running。 - 用
whenIdle()等待收敛,断言状态回到idle,且inbox.nextTurn已空。 - 在
agent/pre-step第一次返回reject,断言没有step/start、轮次未消耗步骤、已领取批次没有回填。 - 调
handle.dispose(),断言ctx.agents.get(id)不再返回该 agent,且agent/disposed已发出。
如果你还没理清一轮对话里 turn 与 step 的先后,先读Agent 生命周期,再回来读这篇的所有权视角;想确认包与依赖的划分,看插件规范。
一句话收束: 创建走 create 或 resume,句柄只给调用方,装配只信 setup,拦截只认 pre-step;其余位置都只能观察,不能替代。
常见问题
不能,DSH plugin 的销毁能力只挂在创建时返回的 AgentHandle 上。DSH plugin 的 get(id) 返回的是裸 Agent,用于投递与观察;句柄只暴露给创建它的消费方所有者,所以想销毁一个 Agent,必须先拿到当初那份句柄。
不能,DSH plugin 的 create 需要调用方提供 SessionId 并新建会话,resume 则先加载持久会话。DSH plugin 用 CreateAgentOptions 描述新建所需的一切,用 ResumeAgentOptions 描述持久标识,两者字段不同,不能混用。
不会,DSH plugin 会撤销事务并移除 Session。DSH plugin 的 setup 拒绝、commit 抛出与所有者 dispose 走同一条回滚路径,恢复出的待处理输入及已存储事件会被保留。
不算,DSH plugin 的 reject 只表示不打开步骤。DSH plugin 把 agent/pre-step 的返回值分成 reject 与 enter 两种,reject 时已认领批次保持删除、轮次不消耗步骤,这是正常的准入结果。
相关术语
- AgentHandle
- AgentHandle 是 ctx.agents.create 与 resume 返回的受拥有句柄,包含 agent 与 dispose() 两项,dispose 是所有者的能力。— packages/core/agent/src/index.ts
- AgentFactory
- AgentFactory 是注册表背后的创建接口,由 agent-loop 通过 ctx.agents.setFactory() 注册,消费方无需依赖具体循环包。— DeepSeek Harness 官方参考 - 核心
- initiator
- initiator 是 ctx.agents 携带的进程本地发起者,用于同进程因果归因,存在既不等于存活,也不代表授权。— DeepSeek Harness 官方参考 - 核心
- PreStepDecision
- PreStepDecision 是 agent/pre-step 的返回类型,只有 reject 与 enter 两种形态,enter 携带 step/start 之后追加的消息批次。— DeepSeek Harness 官方参考 - 核心
来源
- DeepSeek Harness 官方参考 - 核心· deepseek-ai
- packages/core/agent/src/index.ts· deepseek-ai