DeepSeek Harness 计划模式（Plan Mode）完全指南：per-agent 协作状态、配置与受审退出机制

DeepSeek Harness 计划模式Plan Mode完全指南per-agent 协作状态、配置与受审退出机制【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness导读Plan Mode 是 DeepSeek Harness 提供的一种按 Agentper-agent持久化的协作状态——开启后Agent 在先探索与设计、后执行的引导下工作并把完整方案通过exit_plan_mode工具提交给人类审批。本文以.agents/notes/archived/feature/2026-07-07-plan-mode.md这份设计文档为骨架结合当前仓库中落地实现的deepseek-ai/dsh-plan-mode包位于 packages/plan/plan-mode、docs/subsystems/plan.md 子系统参考、工具目录与配置目录完整讲解其设计动机、当前简化后的契约、配置方式、命令行用法、底层事件折叠原理以及它与沙箱、审批等强制轴的边界。Plan Mode 的核心思想可以用一句话概括模式是软的——它只通过提示词引导模型从不自行执行任何限制真正的强制力来自独立的沙箱模式与审批策略两个轴。理解这条软引导 独立强制的边界是正确使用和部署 Plan Mode 的前提。1. 背景与设计动机为什么需要一种具名的会话模式在设计 Plan Mode 之前DeepSeek Harness 缺少一种持久化手段让某个 Agent 进入一种可区分的工作姿态working stance。设计文档2026-07-07-plan-mode.md明确指出Plan Mode 需要同时满足四个要求在规划引导下探索与设计模型在执行前先产出可评审的产物plan artifact跨越明确的审批边界方案必须经过人类显式同意才能进入执行可复现reconstructable会话恢复resume或派生fork时模式状态必须无额外机制地还原且不能让模型可见的请求与会话日志发生偏离与既有扩展接缝协作system-prompt/assemble负责按步装配引导ctx.userInteraction承载审批提问与纠错反馈SessionEventMap承载持久的 per-agent 事实。围绕这些接缝原设计提出了一套泛化命名模式注册表generic named-mode registrymode/set事件、ctx.modes服务、ModeConfig.modes定义映射、dsh-mode包。但后续的简化决策2026-07-22-plan-specific-collaboration-state.md发现产品只发货了plan这一个模式泛化 API 的所有未来可能支持模式名校验正则、保留名规则、ctx.modes.list()、已退休定义回退都是无人消费的维护负担而且 mode 一词横跨了多个不相关领域——沙箱模式是ctx.sandboxPolicy拥有的强制执行策略plan 模式是贡献引导与受审退出的协作姿态二者不应被塞进同一个命名模式抽象。因此当前仓库中的落地形态是plan 专属的产品包包名deepseek-ai/dsh-plan-mode位于 packages/plan/plan-mode持久事实plan/mode: { active: boolean }替代原设计的mode/set: { mode: string }折叠函数foldPlanMode(events)空日志默认值为false服务ctx.planMode.get(agent)返回{ active, pending? }set(agent, active)记录边界应用的选择提示词区块固定的plan:policy替代mode:policy命令与工具/plan [message]、/plan off、exit_plan_mode。设计历史说明原文档中描述的泛化mode/set、ctx.modes、ModeConfig.modes定义映射等 API 属于已被简化决策取代的历史设计当前仓库不再提供exit_plan_mode与plan/mode才是现行契约。阅读本指南时请以当前实现一节为准。2. 当前实现Plan Mode 的设计契约2.1 状态是日志的纯函数而非实时镜像Plan Mode 的持久状态是一个 log-only、whole-value-replace整值替换的会话事件plan/mode: { active: boolean } // SessionEventMap 成员仅写日志、非表面non-surface、 // 整值替换——日志中最后一个值即当前状态 DEFAULT false // 空日志无 plan/mode 事件的折叠结果foldPlanMode(events, end?)返回前缀中最后记录的值不存在时返回false。因为会话日志即事实通道所以恢复resume与派生fork子代理的 fork 继承父代理日志中的plan/mode无额外机制新 spawn 的代理从非活动状态开始无创建期 mode 选项见下文限制压缩compactionplan/mode不是表面节点压缩无法遮蔽它UI 观察通过session/event读取提交的模式翻转没有agent/*实时镜像可订阅。这个设计正是从命名模式注册表简化后保留不动的部分——原文档强调折叠状态是 per-agent 的、日志独有且非表面、压缩无法遮蔽简化后由plan/mode与foldPlanMode继续承担。2.2 待定选择与步边界pre-step追加由于每个会话事件都被回合turn包围一个用户选择不能立刻写入日志而是保持pending状态直到下一个被接受的 in-turnagent/pre-step在请求装配前追加它。具体行为见 docs/subsystems/plan.md 与 src/index.tsset(agent, active)记录待定选择若目标与已记录或已待定状态相同则为 no-opget(agent)返回{ active: boolean; pending?: boolean }——当前步装配所用的记录状态 等待追加的选择状态运行中 Agent 唯一的追加点是前置的agent/pre-step监听器它观察每一个提议的请求步包括第 1 回合第 1 步与请求恢复重试先调用下游监听器只有步被接受后才追加plan/mode追加失败不能阻塞回合选择保持 pending 等待后续被接受的 in-turn pre-step用户选择追加时仅当最后记录的request/header描述了相反状态才追加一条插件来源的user/message通知用户将此会话切换到了 plan 模式——净零翻转plan 后又切回不产生任何通知首个请求前设置的模式不通知区块本身就是状态陈述工具驱动的退出通过其自身的工具结果叙述。set的返回语义来自 docs/subsystems/plan.md 的 Cordis API 目录为committed已立即记录、queued等待下一个被接受的 in-turn pre-step、cancelled清除了相反的待定选择记录状态已匹配、noop已在目标状态。2.3 软层计算区块 稳定退出工具Plan Mode 的整个表面都是软的提示词区块注册{ name: plan:policy, order: 500, text: context … }从AssembleContext.agent读取调用代理的模式解析为配置引导文本或空串。active 时精确渲染部署配置的section文本first-party order 500inactive 时贡献空文本稳定工具目录exit_plan_mode通过ctx.tools注册一次在 plan 模式 inactive 时也保持注册因此进入/退出 plan 模式只改变request/header中的提示词部分原生工具 schema 与 Code Mode 的 PTC SDK 保持逐字节不变tool-catalog 目录明确记录exit_plan_mode stays in the model-facing schema while planning is inactive so transitions add no tool-catalog churn on top of the plan-policy change见 docs/tool-catalog.md不设执行门禁没有任何tools/pre-execute监听器模式本身不拦截任何工具调用。2.4 受审退出exit_plan_modeexit_plan_mode是 Plan Mode 与人类之间的结构化过渡其完整契约参数唯一必填参数plan: string——方案以 markdown 书写且必须以#标题开头前置校验无调用代理agent-less时拒绝执行沿todo_write先例折叠模式非 active 时拒绝空方案或无标题方案在提问前拒绝评审通过 user-questions 接缝发起单选评审Approve/Keep planning 自由文本反馈detail携带完整方案原文通过条件只有恰好一个、且无自定义文本的Approve选择表示同意其余任何形态都 fail closed——评审未提供或失败时调用同样失败退化为人工/plan off绝不出现未受审退出批准后记录一条 silent不叙述的 pending 退出选择由下一个被接受的 in-turn pre-step 追加plan 引导在当前工具批次的剩余部分仍然有效工具结果本身报告状态转换保持规划Keep planning返回携带用户反馈原文的 correctiveisError模式保持在 active模型修订后重新提交。渲染意图上presentCall是一个以方案首个标题为卡题、方案 markdown 为内容的 generic 卡片随后是 generic 结果卡片。关于视觉渲染、token 与 KV Cache 影响packages/plan/plan-mode/README.md 的 Model Experience 章节有逐项说明inactive 不增加 token进入/退出改变 first-party order 500 之后的系统提示词因此从该点开始的缓存路径会变化但工具目录不再抖动。3. 部署配置一行 YAML 开启 Plan ModePlan Mode 的定义是经过校验的插件 Config遵循仓库惯例无需改代码即可从cordis.yml变更。当前唯一必填配置是引导文本section——任何多余字段都会在加载时失败- name: deepseek-ai/dsh-plan-mode config: section: | You are in plan mode. Explore and design before presenting the complete plan through exit_plan_mode.字段默认值含义section必填plan 模式激活时以plan:policy提示词区块渲染的引导文本校验规则docs/subsystems/plan.md 与 docs/config-catalog.mdsection缺失、空白或非字符串以及任何未知键都在插件加载时失败而不是被静默忽略包本身不内置任何模型指令——规划行为的全部引导都来自部署方提供的文本当前没有泛化的模式定义映射也不支持通过配置添加第二个模式原设计中additional modes use the same config map的泛化能力已随简化决策移除未来若出现第二个协作姿态将是一次显式设计决策而非配置项。/** Deployment-owned plan guidance. */ interface PlanModeConfig { /** Guidance rendered as the plan:policy prompt section while plan mode is active. */ section: string }4. 命令行与前端使用/plan、/plan off 与评审4.1 命令契约当ctx.commands被组合时插件注册/plan [off|message]详见 packages/interaction/commands/README.md 与 src/index.ts输入行为/plan选择 active进入 plan 模式/plan message先选择 active再把去除首尾空白后的消息通过agent.steer()提交使其成为受影响步中的一条普通已记录用户消息在 plan 引导之下图片附件随 steered 消息一并携带/plan off选择 inactive不经过模型输入直接退出也能取消一个尚未生效的待定进入选择带图片的/plan off被拒绝以免图片丢失命令名与结果不进入模型历史只有显式的消息体作为普通用户消息被记录。命令在任何支持斜杠命令的前端可用如 Web 客户端/plan可携带图片。4.2 完整端到端流程用户在 Web / TUI 输入/plan [message]或直接驱动ctx.planMode从下一步起每个请求都携带部署配置的plan:policy引导区块模型在引导下探索与设计把变更推迟进方案模型调用exit_plan_mode提交 markdown 方案——用户界面显示方案卡片并弹出评审用户选择Approveplan 模式在下一个步边界切换为非活动下一步的请求头移除引导区块而工具 schema 不变此后执行跟踪交给todo_write用户选择Keep planning可附反馈模型收到携带反馈的 corrective 错误修订后重新提交。4.3 观察模式状态接口如 Web UI可以显示 plan 模式是否激活、以及请求的切换是否仍在等待生效pending。该状态在所有标签页一致并在重启后保持它来自日志折叠而非进程内变量。5. 依赖、接缝与优雅降级dsh-plan-mode是一个产品包而非 capability-seam 三件套接口/实现/消费者——模式的可变部分是配置值而非实现拆分会制造空的实现包这与审批接缝、todo/先例的不预拆分判断一致。其依赖关系见 docs/tool-catalog.md 与 packages/plan/plan-mode/package.json对cordis、dsh-session、dsh-agent、dsh-tools、dsh-system-prompt为对等依赖注入[tools, systemPrompt]执行期机会性地ctx.get读取ctx.userQuestions类型级对等依赖边与前端相关的只有可选的类型级对等边dsh-commands用于注册/plan。包外的一切都通过监听器参与defensive-patterns策略插件不得阻塞提示或回合因此移除该包即可优雅地去掉 Plan Mode不会破坏消费者。终端前端不需要任何模式专属代码——插件自己把每个命令注册到命令注册表退出评审复用组合后的 user-questions 提供者的提示队列与ask_user_question同队列无新机制。当部署没有组合任何 user-questions 提供者时Plan Mode 保持安全但手动ctx.userQuestions缺失时接缝无法解析exit_plan_mode返回 correctiveisError退出降级为人工/plan off永远不会出现未受审退出。引导文本会告诉模型通过exit_plan_mode呈现方案若失败则用散文询问用户——模型保持呈现而非卡死。6. 边界澄清Plan Mode 与沙箱、审批是两个独立的轴这是整个设计中最重要的一条边界也是原文档 FAQ 反复强调的点Plan Mode 是协作姿态plan/mode折叠不读取也不写沙箱与审批旋钮沙箱模式是强制旋钮sandbox/mode折叠见 docs/subsystems/sandbox.md负责真正的内核级只读等约束二者互不干扰与 Codex 将 Plan/Default 协作预设与其沙箱/审批设置分开的做法一致。因此想要在规划期间获得内核强制的只读下限同时设置两个旋钮切换 Plan Mode并且把沙箱模式选项设为只读——顺序无关每个开关只改变自己的折叠无干扰、无需要退出的恢复步骤。日志把每个轴归属到自己的事件姿态记入plan/mode约束记入bash/sandbox-mode。同样地不存在 per-mode 工具允许/拒绝列表因为哪些工具在规划模式下安全是每个工具自身的属性它的效果 effects而不是模式的属性手工维护的名字列表会在新工具含 MCP 服务器到来时悄然腐烂还会造成看起来像安全边界而实际不是的过度承诺。直到工具定义声明其效果元数据原文档 Deferred 中留待的readOnlyHint/destructiveHint方向之前Plan Mode 的约束方式就是section引导 退出评审。这是被明确接受的成本不是缺陷。7. 已知限制与注意事项依据 packages/plan/plan-mode/README.md 的 Known Limitations 与 docs/subsystems/plan.md引导而非强制忽略引导的模型在规划期间仍可能执行变更真正的防护面是评审时刻、会话日志以及独立配置的沙箱、审批、文件系统策略待定选择是进程本地的回合最后一次被接受的 pre-step 之后做出的选择若进程在另一次被接受的 in-turn pre-step 前退出则丢失UI 需重新应用原设计预留的 idle-record 原语是逃生舱无创建期 plan 选项fork 子代理继承日志中的 plan 状态新 spawn 的子代理从 inactive 开始活的子代理无法打开评审被另一活代理拥有的子代理调用exit_plan_mode会失败并被要求把未决决策写进最终结果只有plan-review这一种专属评审渲染器Web UI其他交互提供者通过其通用选项流呈现同一请求缓存影响进入/退出 Plan Mode 会从 first-party order 500 起改变系统提示词该点之后的缓存路径变化但工具 schema 与 Code Mode SDK 不再抖动。8. 测试与验证证据当前实现由多层测试钉住见 packages/plan/plan-mode/testsplan-mode.spec.ts边界顺序、重试、追加失败、HMR 释放、提示词装配、原生与 PTC 模式 schema 稳定、评审结果、不变量覆盖经由布尔服务projection.spec.tsplan会话投影单元——把已记录的/plan命令运行转为候选目标在plan/mode上提交记录状态并为view推导{ active, pending }integration.spec.ts完整exit_plan_mode评审弧线的包级测试invariant.spec.tsplan/mode载荷形状校验。仓库级测试apps/web/tests/plan-control-row.e2e.ts覆盖 Web 前端的 plan 控制行。原设计的录制场景input.json中的setMode步操作与elicitationAnswers队列随交互式 ACP 场景退役当前 keyless TUI 场景覆盖/plan message进入与/plan off直接退出并验证每个已提交的plan/mode先于其改变的request/header。9. 进一步阅读设计决策原文2026-07-07-plan-mode.md含 Alternatives considered 与 Consequences 的完整历史现行设计决策2026-07-22-plan-specific-collaboration-state.md子系统参考docs/subsystems/plan.md含ctx.planMode的 Cordis API 签名包 READMEpackages/plan/plan-mode/README.mdModel Experience 与限制细节工具目录条目docs/tool-catalog.mdexit_plan_mode的精确 schema配置目录条目docs/config-catalog.md每个可接受字段的 JSDoc源码packages/plan/plan-mode/src/index.ts、src/types.ts、src/invariant.ts。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考