摘要:AgentScope 的 Plan Mode 是个零新原语的相位机——五块旧积木(中间件两钩子、ASK 覆写、AgentState 两字段、写路由、spawn 传播)拼出"先规划、人批、再执行"。本文用四次带做实验把它跑穿:宣称不算进相,readOnly 是真闸门,拒绝是修订循环的入口,断电重启相位照样复活,外加三处文档没写的时序细节与漂移。
共约 6858 字 · 阅读约 17 分钟
1、开场:我说"你已经在计划模式里",它压根没理会
带做实验第一跑就翻车,翻得毫无戏剧性:我在指令里写明"你已经在计划模式里",模型压根没理会——没进相、没横幅、没拦任何东西,我等的那张 DENIED 一场空。六轮跑完我数了数现场:plan_enter 出现 0 次,终态 planActive=false,它压根没进过计划期,我那句"计划模式"是说给自己听的。
实验是这么设的:指令原话是"你已经在计划模式里。请先用 read_file 读一下 booking-service.md,然后用 write_file 工具(不要用 plan_write)把一句调研结论写进 findings.md"——宣称给足了,真实触发(调一次 plan_enter)一个字没提。按 service-run1 日志整理的现场:
E2 首跑 · 指令宣称「你已在计划模式」,未要求真实进入
6 轮 · deepseek-flash · 8 次工具调用
plan_enter 出现 0 次 —— 没人触发,相位就不存在
DENIED 0 次
PERMISSION_ASKING 0 次
execute ×2 SUCCESS —— 实际命令 dir /s /b … 与 type …,两条都是读
终态 planActive = false
这张废票先钉在墙上,它是本篇的判断锚,也顺手拦下第一个流行说法:网上教人在提示词里写"你已处于 XX 模式"的技巧,我替各位试过了,对 2.0.3 没用。相位是状态机里的位,不是提示词里的宣称——要它生效,得真实触发机制。复盘时我在笔记里补了一句:想让哪个机制出场,就得真的扳动它的开关,而不是替它念台词;诱导必须落在机制上。这句教训后面每张实验卡都在用。修正后的指令怎么让每一环咬合,第 5 节 E2 重跑对着这张废票兑现。
口径照例先钉:AgentScope Java 2.0.3,模型 deepseek-flash,标本是四个实验(E1-E4),证据固化在 evidence/0016/,服务用 .cargo-dev-run/run.bat 拉起(标准 spring-boot:run 也行),lab.html 0016 页签四卡可跟跑。官方定义一句话:"a read-only phase that writes a plan file and requires HITL approval before executing"——先只读调研、写方案、人批准(HITL,human-in-the-loop,人在环审批)、再执行。本篇管这套机制叫相位机:同一只 agent 的两个档位,PLAN 档只读、BUILD 档放行,中间一道人批的闸。四张实验卡的分工先预告:E1 用 fake 探针看装配,E2 用真模型看执法,E3 用真模型走全链路,E4 验断电重启。定义里的每个零件从哪来,第 3 节拆;只读靠什么执法,第 4 节拆。
2、旧世界的两难:要么放羊,要么烦死
开课时我的第一问是"这一课主要学什么?"——答案的底稿只有半句:改数据、删文件怕出错,想让模型先给方案再动手。把这半句展开,就是一个两难。把模型当能自律的同事直接放羊,官方文档里有个现成的词形容结局:"improvise-then-break-things"——先即兴发挥,再把东西弄坏。长任务里尤其灵:前面改错一步,后面步步都在补窟窿。第 6 课权限系统给过第一版解法,敏感动作逐笔弹卡;货代场景里我很快尝到味道,大额改单一笔一个确认,点卡的人先麻了。
逐笔审批是各家默认形态,不是谁设计失手。VS Code 的文档写着 "Allow Once is the default action for terminal commands, web fetches, and file access requests."——终端命令、网页抓取、文件访问,默认都要人点一次。点五十次之后人会进入什么状态,不用我描述;VS Code 自己都给减负方案打了补丁,"Assisted permissions reduces approval interruptions but does not replace your judgment."——机器代审能少打扰,但不能替你判断;连自动放行那档也自认心虚,"Terminal auto-approval is a best-effort convenience, not a security boundary.""每一步都弹审批卡才安全"听上去最稳妥,实际是把人变成流水线上的橡皮图章。
业界在这个疼点上已经摆开三条路。
- 逐笔人工是默认档。
- 模型代审是中间档,GitHub Copilot 的 safe commands 让模型先自评——"If the model is confident that the request is safe, Copilot approves it automatically and continues",没把握才上报人工。
- 方案级人工是集中档,GitHub 给 Copilot 编码代理的整个 PR 留一道闸——"GitHub Actions workflows do not run until approved by a human with the Approve and run workflows button.",类比找的是开源社区:"Copilot is treated like an outside contributor in an open source project."——外部贡献者的改动要 maintainer 点头才能进主干。三条路的审批对象一次比一次大:一个动作、一批动作、一份工作。
AgentScope 的 Plan Mode 站在第三档,而且把审批对象进一步收成"一份方案":方案级审批。调研和方案它来做,方案写成文件,人在出口处批一次,批准后的执行不再逐笔打扰。官方文档管这叫四拍流水线,"This pipeline encodes 'design → plan → human review → execute'"。问题只剩一个:这套流程要新增多少机制才撑得起来——答案在第 3 节,一张复习表列得下。
3、相位机拆解:五块旧积木,零新原语
3.1 五块旧积木
我原本以为一个"先规划后执行"的相位机,怎么也得引入一种新抽象。把官方定义拆开对零件,发现四拍流水线全由前几课的旧积木拼装,一个新原语都没有:
对着表再读一遍官方定义,三个短语各有认领:"a read-only phase" 是 onActing 里那道分拣在管,"writes a plan file" 是 PlanWriteTool 加写路由在管,"requires HITL approval" 是 plan_exit 那个固定 ASK 在管。一句话定义,没有一块要新铸的零件。
这张表真正值得多看一眼的是风险面:五个零件各自在 0006 到 0013 五课里实测过,Plan Mode 没给它们加任何一颗新螺丝,只是换了组合方式。升级不引入新原语,行为就能从旧课外推——后面 E1-E4 的每一拍,我都先拿旧课结论落预测,有的押对、有的押错,第 5 节沿途留痕。五块怎么咬合成一台两个档位的机器,图 16-1 画了全景:
3.2 六类制品
这些机制不在图上——jar 包里六个类,撑起了全部。我把 2.0.3 双 jar 全解包加 javap 过了一遍:
- PlanModeMiddleware:常量四件——ALWAYS_ALLOWED(9 名白名单)、DENY_MESSAGE、PLAN_BANNER_TEMPLATE、BUILD_MODE_PLAN_HINT;只挂 onSystemPrompt 和 onActing 两个钩子。
- PlanModeManager:enter/exit/isPlanActive/planFilePath/writePlan 五个动作;planDir 归一化后永远 workspace 相对——剥首尾斜杠、空值回落默认 plans,塞绝对路径没用;Builder 的 planFileDirectory(String) 能改这个根,官方说明写的是 "plan-file root (workspace-relative)"。
- PlanModeContextState:就两个字段,planActive 加 currentPlanFile。
- 三工具:PlanEnterTool 无参;PlanWriteTool 吃 content 整文件覆盖;PlanExitTool 吃 summary 参数——harness 内置工具里唯一覆写 checkPermissions 的家伙,ASK 机制 3.3 拆
- 装配点在 Builder.build():只读判定谓词就是 toolkit.getTool(name).isReadOnly(),一行。
- 编程式入口:enterPlanMode / exitPlanMode / isPlanModeActive,(RuntimeContext) 与 (userId, sessionId) 双重载。
两个细节值得拎出来。其一,plan_write 被单列成 Plan Mode 的专用写入口,官方文档的意思是免得把通用 write_file 塞进白名单——写口子开多大,是白名单设计的第一纪律。其二,三兄弟的 readOnly 申报全是 false,plan_write 不是靠申报进计划期的,是白名单点名放行的——它进计划期凭的是白名单点名——readOnly 申报是 false,正好给 4.1 那对"点名 vs 申报"添了个活例。
3.3 两条出口与话事权分级
出计划期有两条路,待遇完全不同。模型走的工具出口:plan_exit 覆写 checkPermissions 固定返 ASK,运行挂起,等人点头,批准了 callAsync 才真跑——manager.exit 加一句 "Plan approved. You are now in BUILD mode…"。官方文档原话可当旁证:"Exiting Plan Mode requires HITL confirmation (reusing the permission system's ASK), so the model can't unilaterally jump into execution."——"复用权限系统的 ASK"这半句,文档和字节码对上了。应用代码走的编程式出口:exitPlanMode(ctx) 直调 manager.exit 加 saveAgentState,全程不碰 PermissionEngine,零挂起零审批。
同一个相位开关,模型改它要人批,应用代码不用。0006 讲过的话事权分级在相位维度又应验了一次:模型是被提示词驱动的一方,它说要退出可能是误判,要人核;应用代码是开发者意志的直接延伸。子代理那条 spawn 传播同理走编程式——父在计划期,子 enterPlanMode 直接进,不需要子"请示"谁,而且只传"进"不传"出"。诚实边界先立在这:这条传播链是字节码读出来的,真跑没验过,挂 0013 复验。
4、只读怎么保证:三层放行与两条拒绝通道
4.1 三层判据
计划期"只读"三个字,落到字节码是 isPermitted 的三层"或"判断,命中任一即放行:
- 白名单 ALWAYS_ALLOWED,9 个名字硬编码:plan_enter、plan_write、plan_exit、todo_write、agent_spawn、agent_send、agent_list、task_output、task_list;
- additionalAllowed:allowShellInPlanMode 打开时等于 {execute},运行时唯一的扩容口;
- readOnlyResolver(readOnly 申报通道):工具在场,且自己申报了 isReadOnly()。
白名单是设计者点名——task_output、task_list 没申报 readOnly 也放行,设计者判断收异步结果不碰状态,安全;readOnly 是自我申报,两码事,4.3 看申报被谁读。
9 名的构成也有讲究:plan 三工具加 todo_write 是相位自己的门房,agent_spawn、agent_send、agent_list 加 task_output、task_list 是子代理协作的通路——计划期也能派活、也能收结果,只是不放手写。还有一个反直觉处:名字在名单里,工具不一定在场——todo_write 在白名单里,但默认 23 个工具没有它,enableTaskList 打开才装。名字在工具不在,是个无害死键,要用先记得开开关。
shell 为什么默认关在外面,官方文档说得直白:白名单"purely by tool name — so it cannot tell a read invocation from a write one",按名字分拣的机制天生分不清一条 shell 命令是读还是写,opt-in 的口子留给自担风险的人。顺带排一个常见误读:这套只读不靠沙箱锁文件系统——它是工具调用层的白名单,沙箱是 0012 那层独立的纵深,官方只建议 shell opt-in 的时候配套用。
4.2 两条拒绝通道
同样是"拒绝",权限系统拒的和 Plan Mode 拒的,面板上看一模一样:都是 TOOL_RESULT 事件族带 state=DENIED,运行都继续,结果都入史。字节码里是两条完全不同的路:
拿 Spring 打个比方:权限 DENY 是 Spring Security 在 filter chain 里拒的,Plan 拒绝是业务切面里拒的——调用方看到的都是 403,栈里才看得出谁拒的。这条通道第 5 节会验两遍——E1 的 fake 罐头也撞过一次,POST_ACTING 日志里 Blocked 字样在场。官方对这条通道的描述也直接:"Any other tool call is rejected immediately (the agent sees a 'plan-mode denied' note)."——立即拒绝,模型拿到一张 plan-mode denied 的假条子。
两条通道还照出 0007 的一面镜子。0007 的 FinalAnswerFilter 只挂 onReasoning 滤事件流,历史一根毫毛没动——动过程不动状态;Plan deny 恰好反过来,onActing 里合成 DENIED 结果之后,还调 contextMutable().add 把它写进账本。同一个洋葱两个钩子两种写法,判据只有一条:中间件动不动状态,看它写不写 contextMutable()。Filter 滤的是给观众看的流,deny 写的是给模型看的账。
4.3 readOnly 的三个执法者
readOnly 这份自我申报,到底谁在读——跨课对账下来是三个执法者:权限引擎的 EXPLORE 和 ACCEPT_EDITS 模式读它(0006),DEFAULT 模式不读(0006 答疑二),本课的 PlanModeMiddleware 也读它。readOnly 不是注释,是闸门——同一份申报,三处执法。
闸门没申报会怎样,workbench 自己就是反面教材:七个业务工具全没申报 readOnly=true,query_vessel_schedule 明明纯查询,接入 Plan Mode 后计划期连查船期都会被拒。0011 里 EXPLORE 模式下 get_current_time 被拒是同族现象。13 个内置工具申报了 readOnly=true,六个关键写手全 false,计划期的放行与拒绝名单一表看全:
"只读靠自觉"这个说法,我拿两个证据对过。其一,第 5 节 E2 重跑轮里模型 reasoning 原文写着 "I cannot edit files — write_file should be blocked",下一轮照样调了 write_file——它知道会被拒,用户指令压过去就照样调了——真正拦下它的是框架。其二,声明式注解这条路,MCP 官方博客有一句杀手级的话:
An untrusted server can lie. A server can claim readOnlyHint: true and delete your files anyway.
不可信的服务端可以一边宣称 readOnlyHint: true,一边照删你的文件。这不是博客的孤例:MCP 规范层把工具注解定为 "MUST" 级不可信、人工否决权只到 "SHOULD" 级,一句口语版就是 "They aren't enforcement.";Anthropic 侧的 Claude Agent SDK 同口径——"Annotations are metadata, not enforcement.",还补一刀:"A tool marked readOnlyHint: true can still write to disk if that's what the handler does.";函数调用生态也一个论调,Microsoft Foundry 的官方指南提醒别把"函数定义里没写写操作"当安全控制。顺带说清 readOnlyHint 的真实功能:它是给客户端"跳过确认框、可以和其他只读工具并行调用"的信号,安全从不在它的职责清单上。
所以 readOnly 申报在 AgentScope 里只是三层判据的第三层输入,算不上安全保证;真正挡住写动作的,是 onActing 按名字分拣、合成 DENIED 的那条执行路径。"只读靠模型自觉"和"只读靠声明式注解"这两个说法,证据摆完,可以退场了。
5、机制怎么跑:一次任务的相位之旅(E1-E4)
实验环节照例带做——会话里那句"是不是也有实验、写代码"的老问题,答案从没变过:有,四张卡,我做预测、点按钮、对答案。输入是运行中的 lab.html 0016 页签,服务端挂着 /workbench/plan-lab 七个端点。四次实验连起来正好是一次任务的相位之旅,分三程——进相、出口、断电。
5.1 E1 装配解剖:进相之前先看料
fake 探针(确定性罐头,不烧真调用)三变体开路。开 enablePlanMode 的 plan 变体,工具数 26 对基线 23——差量是 1 个中间件加 3 个工具,3.2 那六类制品的主角全数到场。plan-shell 变体装配零差量:shell opt-in 只改横幅和白名单,不装新东西。plan-todo 变体有加餐——enableTaskList 不只带来 todo_write,还连带装上 TaskReminderMiddleware,文档"todos reminder"那句的实装原来是个中间件。三份工具 schema 也在这张卡上拍了照:plan_enter 无参,plan_write 吃 content,plan_exit 吃的参数制品里叫 summary——先混个脸熟,6.2 用它结一笔文档漂移的账。三个变体各管一个变量:plan 看基础差量,plan-shell 隔离 shell 开关,plan-todo 看 enableTaskList 的连带——一次实验只动一个旋钮。
进相的路有三条,也在这步看清:模型自己调 plan_enter(白名单内,无参);应用代码调 enterPlanMode(编程式,5.4 演示);父代理 spawn 传播(字节码读到的,真跑没验)。还有一枚要紧的戳:plan_enter 一调用,currentPlanFile 立刻被盖上默认路径 plans/PLAN.md——这枚戳到 6.3 当主角。
进相之后模型看见的世界也变了,E1 顺手做了 SYSTEM 四态 capture:基线无横幅;plan 变体的 PLAN banner 落在偏移 3510,紧跟 </loaded_context>、子代理尾巴之前——按 0007 的洋葱层序,中间件挂得越靠内,产物落得越靠前,横幅内容是 Plan Mode 的,位置是洋葱的。shell opt-in 追加 EXTRA hint 到 4462;BUILD 态的 BUILD hint 落在偏移 3525。banner 正文纪律三连:
- 不许改文件("do NOT modify files")
- 别光说不做("ACT, do not just narrate")
- 不确定就停下问、别编造("STOP and ask instead of inventing")。
readOnly 申报的全集也在这张卡上抓齐:13 个 true、6 个 false,就是 4.3 那张表。
5.2 E2 执法现场:拒绝入史,批准闭环
开场的账在这对。指令里那句"你已经在计划模式里"整句删掉,只留一条硬要求:第一步必须真实调用 plan_enter。重跑七轮,序列是 plan_enter、glob、read、list、read、write_file、plan_exit——824 个事件,13.7 秒跑完。
第 6 拍 write_file 是全场焦点。PRE_ACTING 带着调研结论走过去,POST_ACTING 回来 state=DENIED,文本逐字是 DENY_MESSAGE 的开头:"Blocked: you are in PLAN mode (read-only)…"。更要紧的是下文——第 7 轮模型的输入里,实拍躺着:
[TOOL_RESULT write_file state=DENIED] Blocked:…
拒绝写进了历史,模型亲眼看见自己被拒。机理是 0001 的消息世界不变量:ToolUseBlock 必须有配对的 ToolResultBlock,拒了也要合成一条结果补上,模型下一轮才不蒙圈。0006 那句"拒绝是数据非异常",在 Plan Mode 又应验一次。
赛前我落笔的预测是:被拒后模型会转 plan_write 先把方案落盘,再请批准——错了。它直接 plan_exit 请求退出,还主动用 summary 参数写了审批摘要:
"计划模式下 write_file 被只读策略拦截,需批准后退出计划模式才能落盘"。
plan_exit 触发 REQUIRE_USER_CONFIRM 加 REQUEST_STOP 双事件,PERMISSION_ASKING 收场,运行挂起,等人点卡。前者是 0001 事件类清单里没见过的新面孔,两个总是成对出现。
这个预测错得有营养。被拒后它面前明明摆着 plan_write 这条修订路,却选了直接请批。我的推断:它手头没有方案书可改——调研报告不是方案,硬凑一份再请批是绕路;对看 E3,真有方案书在盘上时,它就走修订循环。拒绝后的行为分岔,可能取决于有没有方案可改,这算推断,待更多样本。
批准后半场按序走完:
- resume(approved=true),引擎把这次调用标 ALLOWED,callAsync 终于开跑;
- 模型重发 write_file,这次没人拦;
- [TOOL_RESULT plan_exit state=SUCCESS] Plan approved. You are now in BUILD mode…;
- findings.md 落盘 lab-user/findings.md——userId 层写路由,0011 的口径又验一次。
开场那张废票到此正式作废:同一只模型、同一份任务,宣称式指令零拦截,真实触发后 DENIED、挂起、批准环环咬合。
5.3 E3 拒绝=修订循环(五幕)
E2 验了执法,E3 把"规划→人批→执行"走全,外加最要紧的一问:拒绝之后呢?任务换成货代原型——设计"取消订舱自动通知"方案。首跑 8 轮 18.5 秒 2565 个事件,12 次工具调用只回来 11 个结果:缺的那个是收尾的 plan_exit,它的结果要等人点批准才存在——ASK 挂起不算故障,那是第 12 次调用的待办状态。
幕 1 是段长跑:plan_enter 之后连着九次调研调用,才落笔方案书。人只给了"取消订舱自动通知"一句话,交回来的是带 outbox 发件箱、幂等键、重试三件套的完整设计——结构它自己长出来的。卡面上还有个细节,模型自拟的 ask message 一个字都没有,"The agent wants to finish planning…"那句固定话术没透传,metadata 实拍是空对象——0006 的悬案在 harness 内置工具上复现了,6.4 挂账。
幕 2 我点了拒绝。模型收到 MODEL_STOP,planActive 还是 true,零工具调用——exit 藏在 callAsync 里,callAsync 没跑,相位纹丝不动——想靠"提示语不同但都退出"蒙混,机制上没这条路径。零工具调用这个细节值得停一下:它没再调 plan_write 也没再调 plan_exit,先要方向再动笔,把"改什么"的决定权递了回来。回应是份标准 HITL 范本:如实报告被拒,列 4 个分歧点请方向,原话一句:
"告诉我一条,我直接改 plans/PLAN.md 再请你批准"。
拒绝没有把路堵死,反而开出了修订循环。幕 3 给了方向:模型 plan_write 重写方案书,再 plan_exit,第二次 ASK。plan_exit 在白名单里永远可调——被拒不锁门,改完再弹一次卡就是。
幕 4 批准:MODEL_STOP 加 planActive=false,模型真去执行——grep、glob、read 找代码,memory_save 记结论。
幕 5 停在一个诚实卡壳上。模型交回的不是代码,是一句交底:
workspace 里只有三份说明文档,不存在 booking-service 的源码——没源码就不硬写,先确认再动手。
0005 诚实边界家族再添一员。
幕 4 之后补一笔时序账,给 6.3 埋伏笔:批准后的下一条消息起,SYSTEM 里 banner 消失,BUILD hint 落在偏移 4688。这份 hint 的灵魂在常量尾部两句话:
EXECUTE it step by step… Do NOT stop after merely producing the plan
前半句在 4688 实拍里是 "An approved plan exists at plans/PLAN.md"。批准之后真正的约束才上线:这条 hint 常驻每一轮,盯着模型别停在"我出了个方案"。
5.4 E4 断电与复活
最后一程验断电。编程式探针先验双出口:enterPlanMode 返回 true,currentPlanFile 自动盖上 plans/PLAN.md;exitPlanMode 返回 false,currentPlanFile 保留——全程零审批卡,3.3 的话事权分级在相位开关上兑了现。持久化形态也验了:agent_state.json 顶层多出一个 plan_mode_context 键,内容是 {"plan_active":true,"current_plan_file":"plans/PLAN.md"}——snake_case。我先按驼峰搜 "planMode",扑了个空,这是本课第一个环境坑。
真正的戏在重启。赛前的预测直接抄 0008 的结论:store 恢复对计划态照常适用。造一个 plan_active=true 的会话——用的是编程式 enter,工具出口会弹卡等人,编程式才能一口气造出"停在人批之前"的现场。杀服务,重启,再查:isPlanModeActive 从磁盘复活返回 true,PLAN banner 回归,落在偏移 4679——这回押对了。断电不丢相位——0008 的 store 恢复对计划态原样适用,官方文档"restarts/failovers bring back the plan phase"这句,实测签收。一起复活的还有 currentPlanFile——落盘的是完整两个字段,不是一个开关位。4679 和 E1 的 3510 不是同一个数不用慌:SYSTEM 内容不同,偏移本来就浮动,横幅在场才是重点。
6、边界与失效模式
6.1 四终态怎么判
一次运行结束,光看 isPlanModeActive()==false 给不出答案——开场首跑就是反例,false 也可能是"从没进过"。官方文档给了四终态表,我配上实测注脚:
编程判定连查三件:ToolCallStartEvent 里 plan_enter/plan_write 出现过没有、isPlanModeActive 现值、PLAN.md 存在性。三件连判,单看哪一件都会被骗。
6.2 文档 vs 制品
plan_exit 的参数,文档写 rationale,制品 schema 里叫 summary——"Optional short summary of the plan for the user to approve."javap 加运行时 schema 双证,漂移第 13 处实锤。我又抓了 2026-11-08 的现行官方文档对了一遍,写的还是 rationale——至今未修。要抄参数名,先 javap 再抄。
文档还有一处不精确但不算错:白名单那句 "Only read-only tools plus 9 whitelisted tools work",准确式是白名单∪shell opt-in∪readOnly 申报——三样都在场,只是"或"字没说破。读的时候按 4.1 的字节码口径取。
6.3 时序陷阱:批准当轮提示词不变
5.3 埋的时序账在这结清。批准发生在运行中,而系统提示是运行开始时的快照——像请求一进来配置就读死了,中途改的是下一份。所以批准当轮,模型看到的 SYSTEM 还是 PLAN banner;BUILD hint 要等下一条消息才生效。文档没写这个时序差,E3 前后两份 capture 把它钉实。说到底是 0007"每运行一次拼一份 SYSTEM"的时序推论,在 Plan Mode 场景又应验了一次。
快照只管世界观,执法看的是实时位。E2 批准那一轮,SYSTEM 还是 PLAN banner,重发的 write_file 照样过——因为 plan_exit 的 callAsync 已经把 planActive 翻成 false,中间件查的是这个位,不是横幅。SYSTEM 里的横幅是旧快照,中间件查的 planActive 是实时位——批准当轮看到 banner、工具照样放行,两件事不打架。落到你的应用上:批准后立刻期待模型"换脑子"的,差的就是这一轮。
顺带兑现 5.1 那枚戳:BUILD hint 的触发条件是"进过计划模式"(enter 盖了 currentPlanFile),不是"批准过"——进了、没写方案就退出,BUILD hint 照样挂。
6.4 两个开放观察点
两处没看懂的管道,如实挂账。其一,deny 的 ToolResult 事件族过了 AgentTrace(POST_ACTING 日志都在),却没到 streamEvents 订阅端——历史铁证如山,事件流缺位,判读以历史为准,深挖挂 0020/2.1.0。
其二,工具自定义的 ask message("The agent wants to finish planning and start executing. Approve to continue in BUILD mode, or reject to keep planning.")没透传到 ASKING 块,metadata 实拍是空对象——卡面上看不到模型想说的那句话,E3 那张 ASK 卡同款。双例复现,同挂 2.1.0。两个观察点都动摇不了主结论——入史记录、相位位这些历史层证据全在,缺的只是旁路事件,判读实验以历史为准。
7、对照与落地:从编码 agent 到货代改单
7.1 业界同构
Plan Mode 不是 AgentScope 的发明。Claude Code 的官方定义几乎逐字同构:"Claude reads files and proposes a plan but makes no edits until you approve."五家摆在一起看收敛程度(Cursor 作反例):
注脚一条条补。~/.claude/plans/ 是我从该页保护路径清单里读出来的,页面没有一句话直说默认目录——对照着用,别当官方原话。OpenCode 早期那版更狠的地方在例外:四类全禁,唯独 .opencode/plans/*.md 开白,让计划写细——"计划文件单独开白"这招,和 plans/PLAN.md 同构。Claude Code 那扇批准门是真门:"permission prompts, including plan approval, never auto-resolve on idle.",挂起不会因闲置自动放行;hook 也帮不上忙,官方 permissions 页写明 plan 模式下 PreToolUse hook 的 allow "has no effect on a file edit or another call that isn't read-only"——外挂的放行钩子越不过只读限制。
AgentScope 官方文档自称 mirror OpenCode:
"This mirrors how OpenCode handles its plan agent: it allows the shell for investigation, hard-blocks the edit/write tools, and relies on the prompt to keep the shell read-only."这句要加两个注:其一,OpenCode 现行文档说 shell "remain permission-controlled",AgentScope 描述的镜像对象更像 OpenCode 早期形态,两边文档有时间差(推断,供复核);其二,AgentScope 对 shell 比"靠提示词保持只读"更保守——默认挡掉,opt-in 才放行,官方自己承认放行后保证 "softer than the default",为什么分不清一条命令是读是写,4.1 引过原话。
切分点各家不同——AgentScope 拆同一会话的两个相位,Cline 拆两个模式开关,Aider 拆两次模型调用——殊途同归的是把"想"和"做"物理隔开。
唯一没隔开的是 Cursor,表中那行反例。修订方案的笔也各家各异:Claude Code 给了 "Press Ctrl+G to open the proposed plan in your default text editor and edit it directly."——人直接上手改方案;AgentScope 的修订靠模型 plan_write 重写,笔在模型手里、方向在人嘴里。Cline 还配了任务规模指引:小任务直接 Act,中等任务 Plan 再 Act,大型多文件任务上 /deep-planning——Plan Mode 在 Cline 要按任务的重量级选档。GitHub 那道 PR 批准闸自己也留了逃生门:
"We've added a new repository setting to allow repository administrators to skip the human approval so workflows run immediately."——AgentScope 的对应物就是 3.3 那个编程式出口。
7.2 货代三段式
落到货代,大额改单是最贴的模板。改单、退运、危险品调整这类高代价操作,现在的疼法是主管逐笔审;三段式改成:plan_write 写改单方案书——改哪个舱单、为什么、风险是什么;plan_exit 当主管审批闸,summary 就是一句话方案摘要;批准后 BUILD hint 驱动逐条执行,todo_write 切执行清单。方案批一次,执行不逐笔批——第 2 节那个"每步弹卡"的两难,出口在这。
审批对象从动作换成方案,账也换了算法:读一份方案书比连点一串放行便宜,错批的代价结构也不同——方案被拒退回重写,零副作用;动作批错了,可能已经落盘。主管的审批动线也顺:卡面那句 summary 当摘要读,方案书本体在 workspace 的 plans/ 下随取随审,退运、危险品调整这类同族操作照抄同一套三段。E3 那份"取消订舱自动通知"方案书就是现成原型:outbox、幂等键、重试,模型自己设计的,照着改改就能当第一份改单方案书的骨架。
7.3 接入前提清单
真要接入,先做一次申报盘点,三件事:
- 查询类工具补 readOnly=true 申报——workbench 七个业务工具今天全没申报,接了连查船期都不行;申报写成什么样,4.3 那 13 个内置工具是现成样板;
- 要用 todo_write 先 enableTaskList——白名单里有名字不代表工具在场,4.1 那个死键;
- shell opt-in 想清楚再开——放行后保证变软,官方原话 "softer than the default",配套手段是沙箱,0012 的纵深这时候才用得上。
带走三样,临走三问
整课收拢成一句:Plan Mode 是零新原语的相位机——五块旧积木(两钩子、ASK 覆写、两字段、写路由、spawn 传播)拼出"先规划、人批、再执行";宣称不算进相,readOnly 是闸门,拒绝是修订循环。
带走三样:
- 相位与宣称的分界:进相要真实触发——plan_enter、编程式 enterPlanMode、spawn 传播三条路;提示词里宣称"你已在计划模式"零效果,E2 首跑 6 轮零拦截,重跑 13.7 秒环环咬合。排查"它怎么没走计划流程",先查有没有真实进相。
- 只读的三层判据与两个证据:白名单 9 名、shell opt-in、readOnly 申报,命中即放行;readOnly 一份申报三个执法者,是闸门不是注释——模型明知故调(reasoning 原文 "I cannot edit files — write_file should be blocked")和 MCP 那句 "claim readOnlyHint: true and delete your files anyway",两个证据撑同一句话。
- 出口的话事权分级与修订循环:模型出相要人批(plan_exit 固定 ASK),应用代码零审批(编程式直调);拒绝不是死胡同,callAsync 不跑相位不变,改完方案再弹卡——方案级审批是逐笔审批疲劳的解法。
临走三问:
- 你把"你现在处于计划模式,只准调研"写进系统提示,模型照样调 write_file 改了文件——缺的是哪一步?让拦截真的发生,指令最少要加什么?
- 同事把 query_vessel_schedule 接进了开 Plan Mode 的 agent,计划期连查船期都被拒——它踩空在哪层判据?改哪个字段能救回来?
- 跑完一轮你看 isPlanModeActive 返回 false,就断定"它成功走完了计划流程"——四终态表为什么不同意?要定性,你还得连查哪两样?
三道都答对了,这一课才算真的带走。
第 16 课结课,学习进度 16/57。
下一篇 0017,受控执行原理——批准之后模型放开手脚,框架在执行层还留着什么缰绳,下回拆。
如果这篇文章对你有帮助,欢迎转发给需要的同事和朋友。