ChatGPTClaudeGrok / X / CursorGemini

深入理解 DSH plugin 同会话目标:生命周期、持久变更与通知到底怎么对齐才不容易乱

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness同会话目标GoalRef生命周期
目标反复被更新,或重启后目标状态与通知对不上。本文讲 GoalRef 的比较并设置、四个持久阶段的分工、goal/change 快照与墓碑,以及 activation 为何不持久、Round 编号由谁标注。

目标的“状态”其实有两层:一层在日志里,一层在进程里。 DSH plugin 的持久阶段回答目标发生了什么,而 activation 只回答续跑消费方现在能不能开始另一个 Round。把两层当成一层,就会出现“重启后目标还在,但自动续跑没了”的误判。 DSH插件 的目标状态分两层:一层在日志里,一层在进程里。

GoalRef 是比较并设置的修订号

每次获准的持久变更都会递增 revision。(来源)

GoalId 是品牌化 id。调用方通过 GoalRef 修改一个确切修订版本,它只有两项:稳定的 id 与正整数 revision。

这条设计让并发更新有一个确定的胜负判定:陈旧修订会被拒绝,而不是悄悄覆盖别人的修改。排查“我改的目标怎么没生效”时,先看手里那份 revision 是不是已经过期。

持久阶段回答目标发生了什么;进程本地激活状态则另行回答续跑消费方能否开始另一个 Round。两者刻意分开。

四个持久阶段

blocked 是唯一表示“因问题而停止”的状态。(来源)

GoalPhase 有四种:

  1. active — 目标在进行;
  2. paused — 被暂停;
  3. blocked — 因问题停止,且必须携带原因;
  4. complete — 已完成。

GoalBlockReason 包含两项:策略选择的稳定 code(lower-kebab-case,用于路由)与非空 message(给人和模型阅读的说明)。

GoalSnapshot 在 GoalRef 之上加了 objective、phase、可选 blockedReason 与 maxGoalRounds。blockedReason 恰好只在 phase 为 blocked 时存在——这条不变量是判断状态是否合法的关键。

GoalView 里哪些是派生的

activation 永远不持久化。(来源)

GoalView 在快照之上加了四个字段:roundsStarted(该目标已准入的最高轮次号)、createdAt、updatedAt 与 activation。

前三项来自持久事件与投影;activation 是进程本地的续跑资格,绝不持久化。服务还会在不改变持久状态的情况下发布进程本地 activation 边沿,客户端消费该事件获得实时状态。

GoalActivationChanged 的载荷是 sessionId 加上可选的当前 goal(id、revision、activation);没有当前目标时该字段缺失。

持久变更只有一条事件

要么是完整快照,要么是清除墓碑。(来源)

每次变更都是持久的 goal/change 会话事件,载荷分两种:

  • GoalSnapshotChangeMeta — kind、version: 1、operation(排除 clear)、完整 goal 快照、roundsStarted、createdAt 与 updatedAt;
  • GoalClearChangeMeta — kind、version: 1、operation: 'clear'、cleared: GoalRef 与 clearedAt。

严格折叠与持久投影只从这些事件派生生命周期状态;inbox 变更不会影响 goal 状态。这条边界让“用户排队了一条新消息”和“目标阶段变化”互不干扰。

Round 编号由续跑消费方标注

roundsStarted 只被获准的 user/message 推进。(来源)

续跑消费方会为每个获准的用户消息轮次标注正数且连续的 Round 编号和当前修订号。只有这些获准的 user/message 事件会推进 roundsStarted。

回放会拒绝五类非法输入:非正数 Round、编号缺口、陈旧修订号、已停止阶段、超出上限。GoalMessageSource 就是这套归属的形状:kind: 'goal'、goalId、revision 与正数 round。

所以“目标跑了第几轮”不是数消息条数,而是看消息上带的 Round。这正是回放能严格校验的原因。

请求、通知与服务行为

创建解析默认值,编辑至少给一个字段。(来源)

CreateGoalRequest 只有 objective 与可选 maxGoalRounds。创建操作会区分“调用方省略字段”与“采用部署配置值”,create() 在内部解析后者。

EditGoalRequest 是局部替换,运行时校验器要求至少提供一个字段。每条变更通知都会携带获准的操作与确切修订号;清除操作不带 goal。GoalChanged 的形状就是 { operation, ref, goal? }。

GoalService 的职责清单值得记:解析创建默认值、从可选注册的 goal 投影读取严格回放结果、校验传入的 agent 是注册表中的确切活跃实例、以比较并设置方式执行变更,并发出 goal/changed 通知;监听器故障会被隔离。

注册表或 key 缺失时,第一次依赖它们的访问会失败。这条“延迟失败”比加载期失败更隐蔽,排查时要注意第一次访问的时机。

disarm(agent) 则不改变持久阶段与修订号,只移除进程本地的续跑授权。生命周期所有者会在卸载 driver 前调用它;之后由人授权的 resume 会记录新的 activation 边沿。

验证:创建、更新、重启、完成

验证要同时看修订号、持久阶段与 activation 三层。(来源) 六步:

  1. 调 create 省略 maxGoalRounds,断言用的是部署配置值,且 revision 为 1。
  2. 用旧 GoalRef 调 edit,断言被拒绝,目标没有被覆盖。
  3. 调 pause 后 resume,断言阶段变化且 revision 递增,activation 由事件更新。
  4. 重启进程后调 get,断言阶段与 roundsStarted 与重启前一致。
  5. 调 block 传一个 lower-kebab-case 代码,断言 blockedReason 存在;再调 complete,断言它消失。
  6. 调 clear,断言返回的墓碑 revision 比被清除快照大一,且历史仍可回放。

如果第 4 步 activation 丢了而阶段还在,那是预期行为:activation 本来就是进程本地状态。

目标反复失效的排查,可以对照目标与自动循环修复;持久化边界见持久化 seam。

一句话收束: 修订号做比较并设置、blocked 是唯一的故障停止、activation 不落盘、变更只有一条事件、Round 由续跑消费方标注、disarm 只收授权不改阶段。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 activation 会持久化吗?

不会,DSH plugin 明确说 activation 只是进程本地续跑资格。DSH plugin 的持久阶段回答目标发生了什么,activation 回答续跑消费方能否开始另一个 Round。

DSH plugin 的 blocked 和 paused 有什么区别?

DSH plugin 用 blocked 表示因问题而停止,它是唯一的这种持久状态。DSH plugin 的 blocked 还要求携带策略负责的代码与说明,paused 只是暂停。

DSH plugin 修改同会话目标的时候,需要带上当前修订号吗?

需要,DSH plugin 用 GoalRef 做比较并设置。DSH plugin 每次获准的持久变更都会递增修订号,陈旧修订会被回放拒绝。

DSH plugin 清除目标的时候,会把历史事件一起删掉吗?

不会,DSH plugin 清除保留墓碑与历史。DSH plugin 写入的是 operation 为 clear 的 goal/change 事件,携带 cleared 与 clearedAt。

相关术语

GoalRef
GoalRef 是单个确切目标修订版的比较并设置身份,含稳定 GoalId 与正整数 revision。— packages/goal/goal/src/types.ts
GoalPhase
GoalPhase 是持久续跑阶段,取值为 active、paused、blocked 与 complete。— packages/goal/goal/src/types.ts
GoalSnapshot
GoalSnapshot 是每次非清除变更写入的完整持久状态,含目标、阶段、可选阻塞原因与轮次上限。— packages/goal/goal/src/types.ts
GoalMessageSource
GoalMessageSource 是获准续跑轮次的消息归属,含 goalId、revision 与正的 round 编号。— packages/goal/goal/src/types.ts

来源