深入理解 DSH plugin 同会话目标:生命周期、持久变更与通知到底怎么对齐才不容易乱
目标的“状态”其实有两层:一层在日志里,一层在进程里。 DSH plugin 的持久阶段回答目标发生了什么,而 activation 只回答续跑消费方现在能不能开始另一个 Round。把两层当成一层,就会出现“重启后目标还在,但自动续跑没了”的误判。 DSH插件 的目标状态分两层:一层在日志里,一层在进程里。
GoalRef 是比较并设置的修订号
每次获准的持久变更都会递增 revision。(来源)
GoalId 是品牌化 id。调用方通过 GoalRef 修改一个确切修订版本,它只有两项:稳定的 id 与正整数 revision。
这条设计让并发更新有一个确定的胜负判定:陈旧修订会被拒绝,而不是悄悄覆盖别人的修改。排查“我改的目标怎么没生效”时,先看手里那份 revision 是不是已经过期。
持久阶段回答目标发生了什么;进程本地激活状态则另行回答续跑消费方能否开始另一个 Round。两者刻意分开。
四个持久阶段
blocked 是唯一表示“因问题而停止”的状态。(来源)
GoalPhase 有四种:
active— 目标在进行;paused— 被暂停;blocked— 因问题停止,且必须携带原因;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 三层。(来源) 六步:
- 调
create省略maxGoalRounds,断言用的是部署配置值,且revision为 1。 - 用旧
GoalRef调edit,断言被拒绝,目标没有被覆盖。 - 调
pause后resume,断言阶段变化且revision递增,activation 由事件更新。 - 重启进程后调
get,断言阶段与roundsStarted与重启前一致。 - 调
block传一个 lower-kebab-case 代码,断言blockedReason存在;再调complete,断言它消失。 - 调
clear,断言返回的墓碑revision比被清除快照大一,且历史仍可回放。
如果第 4 步 activation 丢了而阶段还在,那是预期行为:activation 本来就是进程本地状态。
目标反复失效的排查,可以对照目标与自动循环修复;持久化边界见持久化 seam。
一句话收束: 修订号做比较并设置、blocked 是唯一的故障停止、activation 不落盘、变更只有一条事件、Round 由续跑消费方标注、disarm 只收授权不改阶段。
常见问题
不会,DSH plugin 明确说 activation 只是进程本地续跑资格。DSH plugin 的持久阶段回答目标发生了什么,activation 回答续跑消费方能否开始另一个 Round。
DSH plugin 用 blocked 表示因问题而停止,它是唯一的这种持久状态。DSH plugin 的 blocked 还要求携带策略负责的代码与说明,paused 只是暂停。
需要,DSH plugin 用 GoalRef 做比较并设置。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
来源
- DeepSeek Harness 官方参考 - 同会话目标· deepseek-ai
- packages/goal/goal/src/types.ts· deepseek-ai