DSH plugin 计划模式:状态恢复、pre-step 追加与退出到底该怎么走才最清楚
“切了计划模式却没变化”,往往不是没生效,而是选择还在等下一个 pre-step。 DSH plugin 的计划模式把状态做成整值替换的日志事件,但事件只能落在轮次之内。理解这条约束,才能解释待生效与丢失这两类现象。 DSH插件 切计划模式没反应,多半是选择还在等下一个被接受的 pre-step。
计划模式是软性指引,不是强制
它只影响提示词,不限制任何工具。(来源)
计划模式是 dsh-plan-mode 拥有的、记录到日志的逐 agent 协作状态(ctx.planMode)。激活期间,每个模型请求都会包含一段部署持有的指引。
关键定位:计划模式是软性指引。沙箱模式与审批策略分别强制限制;两者都不读写计划状态,因此部署需要分别配置它们。
该包是可选项,agent 循环不依赖它。它贡献 plan:policy 提示词段落,并注册 exit_plan_mode 工具与 /plan 命令。
plan/mode 是日志事件,不进 transcript
它持久、可回放,但模型看不到事件本身。(来源)
plan/mode({ active: boolean })是仅记日志、整值替换的会话事件:持久且可回放,绝不进入模型 transcript。
plan 单元折叠三样东西:已提交模式、命令结算结果,以及最近一次请求头记录的模式。ctx.planMode 要求注册表存在,并在激活期间等待 plan 与 turnBoundary 注册完成,之后通过保留的句柄读取状态。
客户端只接收裁剪后的 { active, pending };恢复、fork 与压缩都能从日志恢复这两项。这意味着重启后状态不会丢——丢的只可能是尚未追加的待生效选择。
待生效选择与 pre-step 追加
每个会话事件都在轮次内,所以选择必须先排队。(来源)
由于每个会话事件都位于轮次之内,用户选择会保持待生效状态,直到下一个被接受的轮内 pre-step 在派生请求之前追加该选择,无论该 pre-step 位于哪个轮次。
选择不会强制续行,因此在某轮最后一个被接受的 pre-step 之后作出的选择,会在之后的轮次追加。
set(agent, active) 记录待生效选择——目标值与已记录或已在等待的状态相同时不做任何事。get(agent) 返回 { active, pending? }:前者是用于组装当前步骤的已记录状态,后者是等待追加的已选状态。
唯一追加点是前置注册的 pre-step
先让下游接受步骤,再追加,这个顺序不能反。(来源)
agent 运行时,唯一的追加点是前置(prepend)注册的 agent/pre-step 监听器。它会观察每个候选请求步骤,包括第 1 轮第 1 步和请求恢复重试;它先调用下游监听器,只在下游接受该步骤后追加。
提示词准入发生在轮次开启之前,无法追加 plan/mode,因此在提示词处作出的选择由它开启的轮次内第一个被接受的 pre-step 追加。
两条容错规则:追加失败不能阻塞轮次,且该选择会继续等待之后被接受的轮内 pre-step。
追加用户选择时还会记录一条插件来源的 user/message 通知,但仅当最后记录的请求头描述的是另一种状态时才记录。这样模型恰好在上下文变化时收到通知,且绝不重复。
最后是官方记录的限制:在某轮最后一个被接受的 pre-step 之后作出的选择只存在于进程内;如果进程在另一个被接受的轮内 pre-step 之前退出,该选择会丢失。
配置:section 必须在加载时校验
缺字段或未知键不会等到运行期才报。(来源)
PlanModeConfig 只有 section 一个字段。section 缺失、为空白或不是字符串,以及任何未知键,都会在插件加载时失败,而不是被忽略。
计划模式激活期间,确切的 section 文本以 order 50 渲染为 plan:policy 系统提示词段落;未激活的计划模式不贡献任何文本。
这条严格校验的好处很直接:配置写错时插件起不来,而不是上线后发现计划模式静默无效。
退出工具与 /plan 命令
两条退出路径的时序不同,一条走评审,一条走参数。(来源)
exit_plan_mode 采用渐进式披露:从已选计划状态首次为激活的步骤起准入,并在会话剩余部分保持准入。所以首次进入计划模式时它进入请求的工具声明,之后的切换只改变计划指引。原生与 PTC 执行使用同一准入集合;首次进入之前调用返回 UNKNOWN_TOOL,计划模式未提交时调用会失败。
在计划模式中,它要求一份以 # 标题开头的完整 markdown 计划,并通过用户交互 seam 呈交评审:
- 批准返回
{ approved: true },并记录一个静默的待生效退出,由下一个被接受的轮内 pre-step 追加。因此计划指引在 assistant 当前这批工具调用的剩余部分继续生效,而工具结果本身报告这次转换。 - “继续规划”是一次携带用户反馈的失败调用,模型据此修订并再次呈交。
- 放弃评审返回
{ approved: false }并结束当前轮次,计划模式保持激活,直到用户发出下一条消息。 - 评审期间交互通道缺失或服务重载同样使调用失败,而不是静默离开计划模式。
/plan [off|message] 则是命令路径:单独的 /plan 选择计划模式;任何其他非空消息先选择计划模式,再通过 agent.steer() 提交该文本,使其在计划指引下成为下一步骤的普通已记录用户消息;确切参数 off 选择未激活,这还会在待生效条目被追加并对请求可见之前将其取消。
验证:进入、重启、退出
验证要覆盖待生效、恢复与取消三个交叉场景。(来源) 六步:
- 轮次之间调
set(agent, true),断言返回committed且plan/mode已追加。 - 在轮内调
set(agent, true),断言返回queued,日志暂时没有新事件。 - 让下一个 pre-step 被接受,断言事件已追加,且模型上下文里出现一条不重复的通知。
- 重启进程后调
get(agent),断言active与重启前一致。 - 首次进入计划模式前直接调用
exit_plan_mode,断言返回UNKNOWN_TOOL。 - 在待生效状态下执行
/plan off,断言待生效条目被取消而不是追加后再撤销。
如果第 3 步没有出现事件,先确认那个 pre-step 是否被下游拒绝——被拒绝的步骤不会触发追加。
计划模式的整体机制,可以对照计划模式子系统;退出先于子代理的时序问题见计划模式退出时序。
一句话收束: 计划模式只改提示词,状态靠日志恢复,选择要等被接受的 pre-step,追加在轮内唯一位置,退出要么评审要么参数。
常见问题
不会,DSH plugin 的计划模式只是软性指引。DSH plugin 的沙箱模式与审批策略分别强制限制,两者都不读写计划状态。
不会,DSH plugin 的 plan/mode 是仅记日志的会话事件。DSH plugin 让它持久且可回放,但绝不进入模型 transcript。
会,DSH plugin 在轮次之间会立即追加变更。DSH plugin 判断依据是没有轮内 pre-step 会运行,直到另一条提示词开启新轮次。
在某些时机下会,DSH plugin 明确记录了这个限制。DSH plugin 里在某轮最后一个被接受的 pre-step 之后作出的选择只存在于进程内,进程退出就会丢失。
相关术语
- plan/mode
- plan/mode 是仅记日志、整值替换的会话事件,载荷只有 active 布尔值,持久且可回放。— packages/plan/plan-mode/src/index.ts
- PlanModeConfig
- PlanModeConfig 是部署持有的计划指引配置,只有 section 一个字段,渲染为 plan:policy 提示词段落。— packages/plan/plan-mode/src/index.ts
- exit_plan_mode
- exit_plan_mode 是渐进式披露的退出工具,从计划状态首次为激活的步骤起准入,之后一直保持准入。— packages/plan/plan-mode/src/index.ts
- 待生效选择
- 待生效选择是已记录但尚未追加到日志的计划模式选择,等待下一个被接受的轮内 pre-step 追加。— DeepSeek Harness 官方参考 - 计划模式
来源
- DeepSeek Harness 官方参考 - 计划模式· deepseek-ai
- packages/plan/plan-mode/src/index.ts· deepseek-ai