Tianyi Cui
a8cf78630c
The translators' clause-by-clause verification pass caught the English pages' final wording refinements (tui built-in dialogs enumeration and display()'s line-feed exception, invariants whitespace-padded/companion phrasing, client-modules fiber-lifecycle parenthetical, storage strict sequence, workspace first-successful-start) landing after the initial zh versions; this aligns the eight pages and re-records their pairs.
4.9 KiB
计划模式
English | 中文
计划模式是 dsh-plan-mode 拥有的、记录到日志的逐 agent（智能体）协作状态（ctx.planMode，PlanModeService）：激活期间，一段部署持有的指引段落会影响每个模型请求。它是软性指引，有意独立于沙箱模式与审批策略这两条强制执行轴：那些旋钮（knob）从不读写计划状态，需要硬边界的部署另行组合两者。该包（package）是一项可选能力，不属于 agent loop（智能体循环）主干；它的对外表面是 plan:policy 提示词段落、始终保持注册的 exit_plan_mode 工具和 /plan 命令。设计说明负责决策依据；包 README 负责模型体验与限制细节。
源码：packages/plan/plan-mode/src/index.ts
已记录状态与恢复
plan/mode（{ active: boolean }）是仅记日志、整值替换的会话事件：持久且可回放，绝不进入模型 transcript（文本记录）。foldPlanMode(events, end?) 返回前缀中最后一条已记录值，没有时返回 false：生效状态始终是会话日志的纯折叠，因此恢复、fork 与压缩（compaction）无需实时镜像即可将其复原，UI 通过 session/event 观察已提交的切换。完整事件声明见持久化日志事件目录。
待定意图与轮次边界冲刷
由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到轮次边界。set(agent, active) 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），get(agent) 返回 { active: boolean; pending?: boolean }，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
服务会在三类边界处、于受影响的请求组装之前冲刷一条待定选择：提示词提交、普通轮次延续和请求恢复重试。冲刷在下游监听器链之后运行，因此在某个异步监听器等待期间到达的选择，仍会影响紧随该边界的那个请求。冲刷失败会被收容（计划策略绝不能阻塞提示词或轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 user/message 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（README 限制）。
配置
/** Deployment-owned plan guidance. */
interface PlanModeConfig {
/** Guidance rendered as the `plan:policy` prompt section while plan mode is active. */
section: string
}
section 缺失、为空白或不是字符串，以及任何未知键，都会在插件加载时失败，而不是静默地不产生任何指引。计划模式激活期间，确切的 section 文本以 order 50 渲染为 plan:policy 系统提示词段落；未激活的计划模式不贡献任何文本。
退出工具与 /plan 命令
exit_plan_mode 在计划模式未激活时仍保持注册，因此跨越边界只改变提示词段落，绝不改变请求的工具目录；在计划模式之外执行会失败。在计划模式中，它要求一份以 # 标题开头的完整 markdown 计划，并通过用户交互 seam 呈交评审。批准返回 { approved: true }，并记录一个静默（不叙述）的待定退出，在该步骤之后冲刷：计划指引在 assistant 本批工具调用的剩余部分继续生效，而工具结果本身叙述这次转换。「继续规划」则是一次携带用户反馈的失败调用，模型据此修订并再次呈交；评审期间交互通道缺失或服务重载同样使调用失败，而不是静默离开计划模式。
当 ctx.commands 被组合时，插件注册 /plan [off|message]：单独的 /plan 选择计划模式；任何其他非空消息先选择计划模式，再通过 agent.steer() 提交该文本，使其在计划指引下成为下一步骤的普通已记录用户消息；确切参数 off 选择未激活，这还会在计划模式尚未进入任何请求之前，取消尚未冲刷的待定条目。
服务
ctx.planMode 拥有已记录的计划状态、边界处的应用与叙述、plan:policy 段落、/plan 命令和稳定注册的退出工具；get/set 签名见生成的服务目录。