DeepSeek Harness 计划模式设计解析

DeepSeek 把自家的 agent harness 开源了出来，命令行工具名为 dsh，整个项目建立在一个口号上：一切皆插件，底层跑在 Cordis 框架上。它的各个子系统都遵循同一套纪律：状态记录到日志、能力通过接缝暴露、插件可选可拆。本文拆解其中很有代表性的一个：计划模式（Plan Mode）。它负责让 agent 先规划、经人确认、再动手，而它的实现方式恰好展示了这个项目处理协作状态的全部思路。

一、定位：只做软指引

计划模式激活期间，发给模型的每个请求都会附带一段部署方提供的指引文本，也就是 plan:policy 提示词段落，渲染顺序固定为 50。计划模式对模型行为的全部影响就这一段文字，官方文档称之为软性指引（soft guidance）。

真正带强制力的限制在别处：沙箱模式约束运行环境，审批策略要求操作先过人审。这两套机制独立运作，既不读也不写计划状态，部署时各自单独配置。计划模式本身是一个可选插件包，agent 主循环完全不依赖它，拆掉它系统照常运转。

还有一个容易忽略的细节：进入或退出计划模式只会改变提示词内容，从不改变请求携带的工具目录。exit_plan_mode 工具无论计划模式开关与否都保持注册，只是在计划模式之外执行必然失败。让模型在任何时刻都能看到这个出口，是刻意为之的设计。

二、状态记在哪：一条日志事件，不是一个内存开关

计划状态对应一条名为 plan/mode 的会话事件，值就是简单的 { active: true 或 false }。它只记日志、整值替换，持久且可回放，但绝不进入模型的对话记录。生效状态永远是会话日志的纯折叠：foldPlanMode 返回日志前缀中最后一条已记录的值，没有记录时返回 false。

这个决定的好处在下一次会话恢复时立刻显现。因为状态是日志的纯折叠，恢复、分叉、上下文压缩都不需要维护任何实时镜像就能把计划状态原样复原。界面层则通过 session/event 观察已提交的切换，不会读到中间态。

三、什么时候生效：pre-step 的追加时机

会话事件都以轮次为单位封装，于是产生一个时序问题：用户做出的选择要等下一个被接受的轮内 pre-step 在请求派生之前追加，无论那个 pre-step 落在哪一个轮次。选择从不强制续行，所以在一轮最后一个被接受的 pre-step 之后做出的选择，会留到之后的轮次才生效。

set 方法记录待生效选择，目标值与已记录或已在等待的状态相同时不做任何事；get 方法返回已记录状态加一个可选的 pending 字段。agent 运行期间唯一的追加点，是一个前置注册的 agent/pre-step 监听器：它观察每个候选请求步骤，包括第 1 轮第 1 步和请求恢复重试，先让下游监听器接受该步骤，然后才追加。提示词准入发生在轮次开启之前，无法追加 plan/mode，所以在提示词处做出的选择，由它开启的那个轮次里第一个被接受的 pre-step 代为追加。

追加失败不会阻塞轮次，选择继续等待下一个机会。追加用户选择时，仅当最后记录的请求头描述的是相反状态，才额外记一条插件来源的 user/message 通知，因此模型恰好在上下文变化时被告知，且绝不重复。文档也明确了一个局限：一轮最后一个被接受的 pre-step 之后做出的选择只存在于进程内，如果进程在此之前退出，这个选择会丢失。

四、配置：宁可启动失败，不做静默降级

配置只有一项：一段由部署方提供的 section 字符串。计划模式激活时，这段文本原样渲染为 plan:policy 系统提示词段落；未激活则不贡献任何文字。加载校验相当严格：section 缺失、空白、不是字符串，或出现任何未知键，插件直接加载失败，而不是忽略后继续跑。

五、退出工具与 /plan 命令

exit_plan_mode 在计划模式内要求提交一份以 # 标题开头的完整 markdown 计划，然后通过用户交互接缝把计划呈给人评审。批准时返回 approved，并记录一个静默的待生效退出，同样等下一个被接受的 pre-step 追加。这意味着模型当前这批工具调用的剩余部分仍在计划指引下执行，而切换本身由工具结果如实报告。用户选择继续规划，则这次调用以失败告终并携带用户反馈，模型据此修订计划再次呈交。评审期间交互通道缺失或服务重载，同样让调用失败，而不是悄悄退出计划模式。

/plan 命令有三种形态：单独的 /plan 进入计划模式；带上任意消息，先进入计划模式，再通过 agent.steer 把这段文本作为下一步的普通已记录用户消息提交；参数 off 退出计划模式，并且会在待生效的进入被追加、对请求可见之前把它取消。

六、这套设计的三个取舍

把上面的事实放在一起，能看到三条清晰的设计取向。

第一，可回放性优先。计划状态从不单独存放在内存里，永远是会话日志的纯折叠。恢复、分叉、上下文压缩这些最容易丢状态的场景，在这里不需要任何额外机制就能复原。

第二，失败优于静默。退出要评审，继续规划是一次携带反馈的失败调用，配置错误直接让插件加载失败。系统宁可让异常显式化，也不让模型在不知情中失去或获得约束。

第三，指引与强制解耦。计划模式管说服，沙箱和审批管拦截，两边不共享状态，可以按部署需求自由组合。这条边界划分，对任何在做 agent 协作与安全机制的项目都有参考价值。

项目地址：github.com/deepseek-ai/deepseek-harness，MIT 协议，目前处于开发者预览阶段。