ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 计划模式:状态恢复、pre-step 追加与退出到底该怎么走才最清楚

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness计划模式pre-stepexit_plan_mode
重启后计划模式状态丢了,或退出时待生效选择没有冲刷。本文讲 plan/mode 的整值替换语义、选择为何待生效、pre-step 的唯一追加点,以及 exit_plan_mode 与 /plan 两条退出路径。

“切了计划模式却没变化”,往往不是没生效,而是选择还在等下一个 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 选择未激活,这还会在待生效条目被追加并对请求可见之前将其取消。

验证:进入、重启、退出

验证要覆盖待生效、恢复与取消三个交叉场景。(来源) 六步:

  1. 轮次之间调 set(agent, true),断言返回 committed 且 plan/mode 已追加。
  2. 在轮内调 set(agent, true),断言返回 queued,日志暂时没有新事件。
  3. 让下一个 pre-step 被接受,断言事件已追加,且模型上下文里出现一条不重复的通知。
  4. 重启进程后调 get(agent),断言 active 与重启前一致。
  5. 首次进入计划模式前直接调用 exit_plan_mode,断言返回 UNKNOWN_TOOL。
  6. 在待生效状态下执行 /plan off,断言待生效条目被取消而不是追加后再撤销。

如果第 3 步没有出现事件,先确认那个 pre-step 是否被下游拒绝——被拒绝的步骤不会触发追加。

计划模式的整体机制,可以对照计划模式子系统;退出先于子代理的时序问题见计划模式退出时序。

一句话收束: 计划模式只改提示词,状态靠日志恢复,选择要等被接受的 pre-step,追加在轮内唯一位置,退出要么评审要么参数。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的计划模式会强制限制写入,还是只是软性指引?

不会,DSH plugin 的计划模式只是软性指引。DSH plugin 的沙箱模式与审批策略分别强制限制,两者都不读写计划状态。

DSH plugin 的 plan/mode 会进模型 transcript 吗?

不会,DSH plugin 的 plan/mode 是仅记日志的会话事件。DSH plugin 让它持久且可回放,但绝不进入模型 transcript。

DSH plugin 在轮次之外切换计划模式,会立刻写进日志吗?

会,DSH plugin 在轮次之间会立即追加变更。DSH plugin 判断依据是没有轮内 pre-step 会运行,直到另一条提示词开启新轮次。

DSH plugin 的待生效选择在什么情况下会丢,会丢在哪?

在某些时机下会,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 官方参考 - 计划模式

来源