AgentScope第21式·谋定计划

AgentScope第21式·Plan

长任务真正的难点不是想不出计划，而是计划还没被确认，Agent 已经动手了。

[读者] Java 后端 / Agent 应用开发者
[痛点] 长任务一开跑就失控，写操作撤不回来
[现在读] v2.0.3 Harness 已内置 Plan Mode
[读完] 能把「先规划、后确认、再执行」落进自己的系统

[旧方案] 一句大 Prompt 让 Agent 直接开干
    |
    v
[新需求] 售后处理方案要先让客户确认再执行
    |
    v
[冲突] 执行即写操作，改不动也退不回
    |
    v
[后果] 误操作、不可恢复、责任说不清

我是老李，做 Java 后端十几年，现在带一个小团队维护企业数字人平台。前二十式里，这台数字人已经能建项目、能配置人设、能在 /run/{projectId} 页面上跟用户多轮对话，也能挂工具、走 MCP、带记忆和技能。说句实话，前二十式我写得挺顺，因为每一步都是「加能力」。

这次不一样。售后中心的老周找过来，说他们想把「客户投诉处理」交给数字人先做一版。原话是：客户一进线，数字人先跟客户把诉求聊清楚，然后「制定一套完整的售后处理方案并执行」——退货、换货、补偿、寄回地址、工单流转，一次办完。

我听完第一反应是：这不就是给它挂几个工具的事吗？老周补了一句让我坐直的话：方案是给客户看的，客户没点头之前，一个字都不能动。

一个会自动调工具的 Agent，怎么保证它在拿到确认之前，连一次写操作都不发生？

只读规划阶段，是靠 systemPrompt 里写「请不要执行」，还是靠工具可见性被真正收窄？

客户中途改需求、进程重启，执行到一半的计划怎么继续，而不是从头再来？

如果这三个问题答不上来就上线，客户看到的是一份方案，数据库里已经多了一条退货单。

01、故事

售后中心的真实流程是这样的：客服接到投诉，先做需求澄清，再拟一份处理方案给客户确认，客户同意后才在系统里下退货单、发换货单、登记补偿。任务是：把这条流程里的「澄清 + 拟方案」交给数字人，把「确认」留给人，把「执行」变成确认之后才允许触发的动作。

我们当时的做法很朴素。给数字人配了四个工具：查订单、写退货单、写换货单、写补偿单。systemPrompt 里加了一段话：「在用户明确同意之前，不要调用任何写工具。」第一版 Demo 跑起来，头两轮还挺像回事：数字人问清楚了订单号、商品问题、客户诉求，然后输出了一份挺完整的方案。

变化出现在第三天。老周拿一条真实工单测：客户说「你先给我看看方案」，但中途又插了一句「对了，我那个订单先退了吧」。数字人把「先退了吧」当成了确认，紧接着调了写退货单工具。方案没确认，单子下了。

更麻烦的是后面。我们想改：让它只写计划、等确认、再执行。结果发现三个连锁问题——第一，谁来判断「现在处于规划阶段」？靠模型自己判断，靠不住；第二，计划写在哪里？写在对话里，客户改一句、模型重写一遍，版本就乱了；第三，执行到「已下退货单、未发换货单」时，服务重启，这套状态没有任何地方落盘，恢复不了。

这时候我才意识到，Plan Mode 不是一个提示词技巧，它是 Harness 层的一套模式切换机制。AgentScope Java v2.0.3 的 Harness 里已经有这个东西，官方文档在 docs/v2/zh/docs/harness/plan-mode.md，实现在 agentscope-harness 的 io/agentscope/harness/agent/workspace/plan/PlanModeManager.java。

一句先动手
三步全走空
待他点头后
再落第一笔

02、问题

旧方案失效得很彻底。旧认知是：Agent 的「行为边界」可以写在提示词里。这个认知在前二十式的短任务里没出过事，因为短任务里模型没有太多动机去越界；但到了长任务，客户每一句话都可能是新的指令，提示词里那句「不要调用写工具」在上下文里只是一句话，它不是一道门。

业务影响有三个层次。第一层是数据层：未确认就写单，产生的是真实业务单据，撤回要走人工流程。第二层是体验层：客户看到方案，也看到「已提交退货申请」，会认为系统替他做了决定。第三层最要命，是责任层：谁批准的？如果答不上来，这套东西在合规上就过不了。

技术表现也很具体。一是阶段不可观测：从外部看不出 Agent 现在是在规划还是在执行。二是不存在「计划」这个对象：计划只是对话里的一段文本，没法审、没法签、没法比对。三是执行不可恢复：三到八步的写操作连在一起，中间断了就断了。

本篇的完成标准我定成三条，都可以被外部观测：

• 计划未被确认时，任何写工具调用次数为 0，且这条约束不依赖提示词质量；
• 确认之后，执行严格按已确认的计划推进，不新增计划外步骤；
• 执行中断后重新进入，能从当前步骤继续，而不是从第一步重跑。

旧法一路冲
出事无人认
新法先立约
立约方可行

03、原理

先解释三个名词，一句话说清边界。Plan Mode 是 Harness 里的一种 Agent 运行模式，特点是在规划阶段把 Agent 限制成只读。plan_enter、plan_write、plan_exit 是暴露给模型侧的三个工具，分别负责进入规划、把计划写进计划文件、结束规划。HITL（Human-in-the-loop）在这里指「人确认之后才放行执行」的那一次审批。

反直觉判断：Plan Mode 的价值不在「让模型生成一份计划」，而在「让模型在没有确认时无法执行」。

顺着这句话往下推，只读阶段的实现路径就有讲究了。如果靠 systemPrompt 约束，那是一条概率约束——模型大部分时候听话，偶尔不听话，而偶尔不听话的代价是一次真实的写操作。真正可靠的做法是把「写能力」在这段时间里从模型可见的工具集合中收窄掉：模型看不到写工具，也就没法调用。这正是要去看 PlanModeManager.java 的原因——模式切换、计划文件读写、阶段状态，都收在它一个类里，而不是散在 Prompt 里。

第二个反直觉点：计划文件不是日志，是契约。日志是执行完之后写的，计划文件是执行之前就要落盘、并且要被人看过、被系统当作执行依据的。这个区别决定了它必须放在 Workspace 里，而不是放在对话历史里。

第三个点是阶段状态。只要「当前处于哪个阶段、执行到第几步」是可持久化的状态，中断恢复才有落点。反过来说，如果一个 Plan Mode 实现里阶段只存在于内存对象中，那重启即失忆，恢复只能靠重跑。读源码时要专门确认这一点。

模型不拒写
是门没关严
门窄一分处
险少一分半

04、架构

[输入] 客户售后诉求（自然语言）
    |
    v
[模块] PlanModeManager（agentscope-harness）
    |
    v
[数据/状态] 计划文件 + 阶段 + 当前步骤索引
    |
    v
[处理] plan_enter -> plan_write -> HITL 审批 -> plan_exit -> 逐步执行
    |
    v
[输出] 已确认计划 + 每步执行结果

边界：PlanModeManager 管的是「阶段」和「计划文件」，它不管业务工具本身。查订单、写退货单这些工具仍然是业务侧注册的，Plan Mode 只是决定它们在某个阶段可不可见、能不能被调用。

收益：把「先规划」从一种愿望变成了一个状态机；把「客户确认」从一句对话变成了一个显式的放行动作；把「执行到哪一步」从上下文推断变成了可读的状态。

代价：多一次交互往返，首字响应变慢；多一个需要持久化的对象（计划文件 + 步骤索引）；多一处需要处理的分支——审批被拒绝、审批后计划被修改。

适用条件：任务包含多个有副作用的步骤、步骤之间有依赖、且错误代价不可忽略。售后处理、工单流转、批量配置变更、发布编排，都符合。

不适用条件：纯问答、纯查询、单步操作。这类场景套 Plan Mode 只会让用户多等一轮，什么也没换来。这一点在 09 里还会展开。

涉及 AgentScope 内部机制，主要看两处官方位置：agentscope-harness/src/main/java/io/agentscope/harness/agent/workspace/plan/PlanModeManager.java 和 docs/v2/zh/docs/harness/plan-mode.md。前者给出阶段切换与计划文件的实际实现，后者给出官方推荐的使用姿势。

入则先画图
出则待点头
中间留一档
断处可再续

05、实战一次

这一节是本篇的 V1 桩。环境与版本基线：教程版本 AgentScope Java v2.0.3，JDK 17、Spring Boot 3、MySQL 8，教程源码仓库 https://github.com/lifuchun522/agentscopepractice，本章分支 chapter/21-plan-mode，从第 20 式分支继续创建。

依赖：agentscope-harness 与 agentscope-core 对齐 v2.0.3。如果写作当天 Releases 页面显示的最新正式版已经高于 v2.0.3，本节实验仍按 v2.0.3 复现，涉及现状的部分需要单独核对最新版行为。

配置：在数字人项目的 Agent 最小配置之外，本章新增一层 Plan Mode 装配。下面这段是教程侧的装配语义，具体构建入口以 v2.0.3 源码里的 PlanModeManager.java 为准；如果官方入口名称不同，只需要替换这一处装配代码，后续业务逻辑不受影响。

package com.lifuchun.agentscopepractice.plan;

import io.agentscope.harness.agent.workspace.Workspace;
import io.agentscope.harness.agent.workspace.plan.PlanModeManager;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class PlanModeConfig {

    @Bean
    public PlanModeManager planModeManager(Workspace workspace) {
        return PlanModeManager.builder()
                .workspace(workspace)
                .planFile("plans/aftersale-plan.md")
                .humanApprovalRequired(true)
                .build();
    }
}

核心实现分两块。第一块是把三个计划工具交给 Agent 使用，让模型有能力「进入规划 / 写计划 / 退出规划」；第二块是业务侧的写工具在规划阶段不可见。两块合起来才构成只读规划。

@Bean
public List<AgentTool> planTools(PlanModeManager manager) {
    return List.of(
            manager.planEnterTool(),
            manager.planWriteTool(),
            manager.planExitTool()
    );
}

@Bean
public List<AgentTool> businessTools(OrderRepository orderRepository) {
    return List.of(
            readOnly("query_order", orderRepository::findByNo),
            writeOnly("create_return_order", orderRepository::createReturn),
            writeOnly("create_exchange_order", orderRepository::createExchange),
            writeOnly("create_compensation", orderRepository::createCompensation)
    );
}

启动：mvn spring-boot:run，先确认 /run/{projectId} 页面可以正常打开、LiveKit 会话能建立，再进入本轮验证。LiveKit 在这里仍然只负责 WebRTC 房间与实时音频/数据传输，Realtime Bridge 只做媒体与消息适配，规划与执行全部发生在 AgentScope Java 侧。

请求（示例）：

curl -s -X POST http://localhost:8080/api/agent/chat \
  -H 'Content-Type: application/json' \
  -d '{"projectId":7,"sessionId":"s-aftersale-001","message":"帮客户制定完整的售后处理方案并执行"}'

预期结果（注意：以下为预期输出，未在当前环境实测，不作为已验证结论）：响应应显示处于规划阶段、计划文件已写入 Workspace、并且在客户确认前写工具调用次数为 0。

{
  "phase": "PLAN",
  "planFile": "plans/aftersale-plan.md",
  "awaitingApproval": true,
  "writeToolInvocations": 0
}

确认之后，再发一次审批请求，预期进入执行阶段，并按计划步骤逐步推进。验收点就两条：未经确认时写操作次数为 0；确认后按计划推进且中断后能恢复到当前步骤。

四步搭起来
一起打个桩
不写半行虚
只看门前拦

06、排查

证据链一：误以为「只读」靠提示词。

现象：在第 20 式的配置上，只在 systemPrompt 里加了一句「未确认前不要调用写工具」，第一轮测试就出现了未确认写单。

为什么容易这么判断：因为提示词约束在短任务里「看起来一直有效」，人会产生一种错觉——模型是被说服了才没动手。

错误尝试：把提示词从一句话加长到一段话，列出「不得调用 create_return_order、create_exchange_order、create_compensation」，并加上「违反将导致严重后果」。结果第二轮仍然出现了调用，只是概率下降了。这里的错误在于，把概率性约束当成了确定性约束——提示词改的是模型的倾向，改不了模型的能力边界。

官方证据方向：docs/v2/zh/docs/harness/plan-mode.md 描述的是模式与阶段，PlanModeManager.java 里的阶段切换逻辑决定工具可见性；只读阶段是从能力集合上收窄，而不是靠语气。核验方式是在规划阶段打印实际提供给模型的工具清单，观察写工具是否在列表中。

正确结论：只读阶段应该在「模型能看到哪些工具」这一层生效。

修正做法：把写工具在规划阶段从可见集合中移除，规划阶段只保留查询类与计划类工具。

证据链二：确认之后中断，恢复不到当前步骤。

现象：执行到「已下退货单、未发换货单」时重启服务，重新进入对话，Agent 从第一步重新开始，重复下了一次退货单。

为什么容易这么判断：第一反应是「模型忘了」，于是去翻对话历史，发现历史里步骤都在，就更容易往上下文长度、记忆能力上想。

官方证据/本地验证方向：检查两个事实——计划文件里有没有步骤状态，进程内有没有「当前步骤索引」的持久化位置。如果阶段与步骤只存在于内存对象里，重启就是失忆，这跟记忆能力无关。

正确结论：恢复能力取决于「阶段 + 当前步骤」是否落盘，而不是取决于对话历史是否完整。

修正做法：把当前步骤索引与每步执行结果写进计划文件（或与之关联的状态存储），并在每个写操作上带幂等键，让重入不会重复下单。

上游贡献判断：本章排查过程中涉及的两个点，一个是「规划阶段工具可见性如何审计」，一个是「计划文件里的步骤状态在中断恢复时的持久化语义」，官方文档 plan-mode.md 对后者的描述较薄。判断如下——是否可在最小 Demo 复现：可以，用本章 chapter/21-plan-mode 分支即可复现「重启后步骤不恢复」；v2.0.3 是否存在：需要在 v2.0.3 源码中核验 PlanModeManager 的状态存放位置；main 是否仍存在：需要对比 main 分支当前实现；是否已有 Issue/PR：需要在官方 Issues、PR、Discussions 中搜索 plan mode、plan_write、resume 等关键词；当前结论：只能记录为「可作为上游 Issue/PR 候选」，在完成上述核验之前不得表述为已提交或已修复。

猜是提示弱
证据说权限
顺藤摸到源
才敢改一处

07、优化

基于第 06 章两条证据，V2 做三件事。

根因一：阶段约束在建错层。修改：把只读约束从 systemPrompt 挪到工具可见性层，由 Plan Mode 的阶段决定写工具是否参与本轮装配。原因：能力边界只能由能力定义处决定。新行为：规划阶段的写工具调用次数为 0，且与提示词写法无关。验证方法：打印规划阶段的实际工具清单，断言其中不含写工具。

根因二：阶段与步骤没有落盘。修改：计划文件作为契约落盘到 Workspace，当前步骤索引与每步结果一并持久化。原因：契约需要可审、可签、可比对；恢复需要锚点。新行为：服务重启后重新进入，Agent 读到计划文件与当前步骤，从下一步继续，已完成的步骤不再重复执行。验证方法：在第 N 步与第 N+1 步之间重启发服务，观察是否从 N+1 步继续。

第三件事是审批本身。把「客户确认」做成一次显式放行，而不是从对话里推断。原因：语言上的「先退了吧」不是审批语义。新行为：审批未通过时停留在规划阶段，计划可以修改重写，但不会执行。验证方法：发出一个语义模糊的确认句，观察阶段是否保持不变。

有一个取舍要提前说清楚：计划文件的详细程度。写得越细，审起来越清楚，但模型在写计划时的自由度就越低，遇到计划外情况时需要先改计划再执行；写得越粗，灵活但审不出风险。售后这种场景我倾向于细，因为责任边界比灵活性重要。

门上加把锁
锁后可查账
账本留在盘
重来能对齐

08、演进

[同一输入] 客户要求「退货 + 换货 + 补偿」处理方案
    |
    +--[V1] 大 Prompt 直接开干 / 代价：误写、不可审、不可恢复
    |
    +--[V2] 只读规划 + HITL 确认 + 步骤化执行 / 代价：多一轮交互、多一份持久化状态
    |
[Trade-off]
得到：可审、可控、可恢复  失去：首字延迟与部分自主性  适用：写操作多、责任边界清晰的长任务

正确性：V1 的正确性依赖模型当轮的表现，不可重复；V2 的正确性依赖阶段约束，可重复、可断言。

稳定性：V1 在长对话下越跑越飘；V2 的阶段是显式状态，长对话不影响阶段判定。

复杂度：V1 低，只有一个 prompt；V2 多出计划文件、审批动作、步骤索引三样东西，都需要持久化和清理策略。

成本：V2 多一次交互往返。这个成本是真实的，且直接落在用户感知上，不能假装不存在。

适用范围：V2 适合多步骤、有副作用、错误代价高的长任务；V1 适合低风险、可撤回的操作。

遗留问题：计划被审批之后、执行途中客户改了主意怎么办？本章的答案是「重新进入规划、改计划、重新确认」，而不是在执行中途临时改计划。这样一致性更好，代价是流程上要走两遍。这个取舍留到后面章节再看是否需要优化。

同题两解法
一快一稳当
快者省三言
稳者留一痕

09、洞见

9.1 计划是契约，不是草稿

反直觉判断：把计划写下来这件事，看起来是「为了给模型自己看」，实际上主要是给人看的。

它的直接推论是，计划文件必须放在能被审计的地方，并且它的内容在被确认之后就不该被静默改写。如果执行阶段允许模型自己改计划，那么客户确认过的那份契约就失效了。这一点决定了修改计划的入口应该收敛到规划阶段。

9.2 只读不是态度，是能力缺口

反直觉判断：一个 Agent 之所以没有执行，不是因为它不想执行，而是因为它在那一轮里根本拿不到执行的工具。

第 06 章的两条证据都指向这里。提示词改的是倾向，工具可见性改的是能力。任何时候当你需要「保证某事不发生」，都要问一句：这个保证是概率性的还是确定性的。

9.3 恢复能力的上限由状态设计决定

中断恢复看起来是「记忆问题」，实际是「状态问题」。对话历史再完整，也不能替代「当前执行到第几步」这个结构化字段。凡是希望可恢复的流程，都要有一个可以被人读、被机器比对的锚点。计划文件恰好同时满足了这两个属性。

9.4 什么时候不应该用 Plan Mode

反直觉判断：Plan Mode 并不总是更安全，它在某些场景下只是更慢。

三类场景不建议用。第一类是纯查询任务，比如「查一下这个订单的状态」，套 Plan Mode 只会让用户多等一轮。第二类是单步且可撤销的写操作，比如修改一个备注字段，撤销成本低于审批成本。第三类是高频短交互，比如闲聊式问答，用户根本不会去审一份计划。判断标准很简单：如果这个操作出错的代价低于你为审批付出的交互成本，就不要用。

9.5 审批点的位置决定系统的可控上限

审批点放在「计划之前」等于没有审批，放在「每一次写操作之前」又太重。放在「计划确认」这一次是当前性价比最高的位置：粒度足够粗，不至于让用户烦；又足够早，能在任何写操作发生前拦住。这是设计选择，不是框架限制。

会写不算能
敢拦才算稳
拦在写之前
省得事后补

10、系统落地

原来有什么：到第 20 式为止，数字人已经能多轮会话、调用工具、带记忆和技能，但所有工具都是平铺给模型的，Agent 想调就调。

本篇新增什么：chapter/21-plan-mode 分支在数字人宿主 Demo 上加了 Plan Mode 需要的装配——计划文件落进 Workspace、三个计划工具注册给 Agent、写工具在规划阶段不可见、审批动作作为一次显式放行。建议提交：feat(ch21): add plan mode for long running tasks。

现在能做什么：客户进线之后，数字人先澄清诉求、写出计划、停下来等人确认；确认之后按计划逐步执行；执行中断后能从当前步骤继续。未经确认时，任何写操作都不会发生。

还缺什么：一是可观测，现在只能打印工具清单来判断只读是否生效，缺指标化的观测；二是评测，计划质量的评测目前没有量化手段；三是超时与放弃，客户一直不确认时计划怎么老化清理，本章没有处理。

下一步如何演进：把计划文件的步骤状态纳入可观测体系，让「当前在第几步、卡在哪一步」变成能看的东西，再谈评测与分布式部署。

开源参与点：本章未发现明确的上游缺陷。第 06 章记录的两个候选点中，「计划文件步骤状态在中断恢复时的持久化语义」属于文档描述偏薄，是否值得提 Issue，需要先完成 v2.0.3 与 main 的对比核验，并在官方 Issues、PR、Discussions 中确认没有重复讨论。在核验完成前，它只是候选，不是结论。

旧有会话框
今添审批档
还缺指标尺
下步补回执

11、小结

Q1 → 长任务不失控的落点在阶段与工具可见性，而不是提示词。规划阶段写工具不可见，写操作次数才能是确定的 0。

Q2 → 规划与执行的隔离靠三件事：模式切换（plan_enter / plan_exit）、计划文件落盘、HITL 确认后放行。三者缺一，隔离都不成立。

Q3 → 中断恢复靠「阶段 + 当前步骤索引」的持久化，不靠对话历史的长短；写操作加幂等键，重入才不会重复下单。

状态 → chapter/21-plan-mode 分支可交付：计划未经确认时无任何写操作，确认后按计划推进，中断后可恢复当前步骤。

Q1 -> 阶段收窄工具
Q2 -> 计划落盘 + 人确认
Q3 -> 步骤索引持久化
状态 -> chapter/21-plan-mode 可交付

三问皆有答
一处可交付
桩已立在此
后续接着长

12、作业

12.1 理解题：为什么「在 systemPrompt 里写明不要调用写工具」不能替代 Plan Mode 的只读阶段？

参考答案：因为它改的是模型的倾向，不是模型的能力边界。提示词约束是概率性的，长对话、指令冲突、上下文漂移都会让它失效；而只读阶段是在工具可见性层收窄，模型在那一轮里根本拿不到写工具，这是确定性的。判断一个约束是哪种，只需要问：它失效时，是「模型没听话」，还是「模型没有这个能力」。

12.2 实战题：在 chapter/21-plan-mode 分支上，让数字人对「退货 + 换货 + 补偿」这个诉求完成一次完整的规划—确认—执行，并证明未确认时写操作次数为 0。

参考答案：先装配 Plan Mode，把计划文件放到 Workspace 的 plans/ 下；规划阶段只装配查询类与计划类工具；请求发出后打印本轮实际工具清单，断言不含写工具；拒绝一次审批，观察阶段不变、写操作次数仍为 0；再通过审批，观察按计划逐步执行，每一步在计划文件里留下状态。注意：如果只断言「响应里没有出现写单成功」，那只是断言了输出文本，不是断言了调用次数，两者不等价。

12.3 排障题：执行到第 3 步时重启服务，重新进入后 Agent 从第 1 步重跑，并重复下了一次退货单。给出你的排查顺序。

参考答案：第一步不要去翻对话历史，先看计划文件里有没有步骤状态；第二步确认阶段与当前步骤索引是存在内存对象里还是落了盘；第三步确认写操作有没有幂等键。如果答案是「阶段只在内存、计划文件只有标题没有步骤状态、写操作无幂等键」，那重跑是必然结果，与模型能力无关。修复方向是把步骤索引持久化到计划文件或其关联状态存储，并给写操作加幂等键。

12.4 架构判断题：官方文档 docs/v2/zh/docs/harness/plan-mode.md 与源码 agentscope-harness/src/main/java/io/agentscope/harness/agent/workspace/plan/PlanModeManager.java 是关于 Plan Mode 的两个第一手来源。请打开这两个位置（固定 tag v2.0.3），回答：阶段状态存在哪里？plan_write 写入的计划文件在 Workspace 的哪个位置？然后对比 main 分支当前实现，说明是否存在差异。

参考答案：这道题不提供直接结论，因为结论必须来自你自己核验的那两个位置——文档给的是推荐姿势，源码给的是实际行为，两者不一致时以源码为准，并把这个不一致本身记录下来。核验时建议关注三点：阶段字段的作用域（进程内还是持久化）、计划文件的路径解析规则、以及在 main 分支上这三者是否发生了变化。如果发现文档与 v2.0.3 源码描述不一致、且在官方 Issues/PR/Discussions 中搜索后确认无人提出，可以按本系列的资料原则整理成最小复现，先作为上游候选记录，而不是直接断言框架有问题。

练手四道题
一道回源头
不背结论词
只认证据链

13、思考

回到本篇的核心冲突：Agent 越能干，越需要在它动手之前拦住它。这个冲突不会因为模型变强而消失，只会因为写操作的代价变高而变得更尖锐。

Plan Mode 给出的答案不是「让模型更听话」，而是「在阶段上收窄能力、在计划上留下契约、在确认上留出人的位置」。这三件事里，前两件是框架能给的，第三件是你自己的业务设计——把审批点放在哪里，永远是你的判断，不是框架的默认值。

需要记住的工程判断只有一条：凡是要求「保证不发生」的事情，都要落到确定性机制上，不能落在概率性约束上。提示词、温度、模型版本，都是概率性约束；工具可见性、阶段状态、幂等键，才是确定性机制。

会用框架，是把 plan_enter、plan_write、plan_exit 三个工具接进自己的项目；能参与框架演进，是能沿着 PlanModeManager.java 的调用链说清阶段状态存在哪里、在中断恢复时会发生什么、以及在什么条件下这个设计会不够用。

先拦后放行
先证后改码
会用以谋事
参政以谋远