ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 的 Agent 所有权:谁创建、谁持有句柄、拦截决策到底在哪一层生效

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek HarnessAgent 所有权AgentHandleagent/pre-step
Agent 由 ctx.agents 创建,句柄只交给调用方,dispose 是能力而非常规状态。本文讲 create 与 resume 的差别、setup 的发布前窗口、Agent 句柄上的投递动作,以及 pre-step 拦截决策的边界。

在 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,但一个建立新会话,一个接管已持久化的会话。(来源) 选择依据:

  1. create() — 在一个调用方提供的 SessionId 下构建全新会话与 agent。适合新任务、子代理派生、一次性实验。
  2. 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 完成。(来源) 官方给出的顺序是:

  1. Session 入库,session/created 完成;
  2. setup(agentCtx, agent) 被调用;
  3. Agent 注册;
  4. agent/created 发出;
  5. 第一次提示词组装。

这个顺序决定了一件事:凡经 agentCtx 注册的内容,都先于 agent/created 与第一次提示词组装存在。反过来说,如果你在 agent/created 之后再补注册,第一次组装就已经错过了。

setup 还有两个常被忽略的细节:其一,agentCtx 拥有作用域注册,显式 Agent 提供确切的子 Session,Context 不需要反向属性;其二,setup 可以返回一个同步 commit,它会在发布前一刻被调用。

回滚语义必须写进你的插件设计:setup 拒绝、commit 抛出、或所有者 dispose,三者走同一条撤销路径——移除 Session,但保留恢复出的待处理输入与已存储事件。换句话说,失败不会留下半个 Agent,也不会顺手把你辛苦恢复的输入删掉。

句柄上真正能做的事

Agent 是插件面向编程的 surface,它提供投递与观察,不提供任意改状态。(来源) 按用途分成四组:

  1. 投递 — send(message, target, wakeup) 直接暴露 target 与 wakeup 路由;followup()、steer()、inject() 是固定预设的别名。
  2. 取消与收敛 — cancel(cause, options) 清空排队与 steering 工作并中止活跃轮次;whenIdle() 等到整个 agent 活动归于静止。
  3. 维护 — runMaintenance(task) 从真正的空闲阶段跑一个非轮次任务,公开状态仍保持 idle。
  4. 持久投影 — 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。返回值只有两种形态:

ts
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 排空。

一条最小所有权链路的验证

把“创建→发起→拦截→结束”串起来跑一遍,比读十遍接口定义更能确认所有权。(来源) 五步:

  1. 用固定 SessionId 调 create(),在 setup 里注册一个探针服务,断言它在 agent/created 之前已可解析。
  2. 读 handle.agent.status,应为 idle;调用 followup() 后进入 running。
  3. 用 whenIdle() 等待收敛,断言状态回到 idle,且 inbox.nextTurn 已空。
  4. 在 agent/pre-step 第一次返回 reject,断言没有 step/start、轮次未消耗步骤、已领取批次没有回填。
  5. 调 handle.dispose(),断言 ctx.agents.get(id) 不再返回该 agent,且 agent/disposed 已发出。

如果你还没理清一轮对话里 turn 与 step 的先后,先读Agent 生命周期,再回来读这篇的所有权视角;想确认包与依赖的划分,看插件规范。

一句话收束: 创建走 create 或 resume,句柄只给调用方,装配只信 setup,拦截只认 pre-step;其余位置都只能观察,不能替代。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 里 ctx.agents.get(id) 拿到的 Agent 能直接销毁吗?

不能,DSH plugin 的销毁能力只挂在创建时返回的 AgentHandle 上。DSH plugin 的 get(id) 返回的是裸 Agent,用于投递与观察;句柄只暴露给创建它的消费方所有者,所以想销毁一个 Agent,必须先拿到当初那份句柄。

DSH plugin 的 create 和 resume 可以互换使用吗?

不能,DSH plugin 的 create 需要调用方提供 SessionId 并新建会话,resume 则先加载持久会话。DSH plugin 用 CreateAgentOptions 描述新建所需的一切,用 ResumeAgentOptions 描述持久标识,两者字段不同,不能混用。

DSH plugin 的 setup 抛出异常会留下半个 Agent 吗?

不会,DSH plugin 会撤销事务并移除 Session。DSH plugin 的 setup 拒绝、commit 抛出与所有者 dispose 走同一条回滚路径,恢复出的待处理输入及已存储事件会被保留。

DSH plugin 的 pre-step 拒绝一批消息算错误吗?

不算,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 官方参考 - 核心

来源