AgentScope Java v2 第17课,从意图到事实要过几道门

0 阅读21分钟

封面

摘要:模型的工具调用只是意图——没身份、没许可、没事实。本课把七课摸过的控制点装进博客 04 的两张平面逐格打分:审批九要素 1 满 3 半 5 空,环境契约九项 2 满 4 半 3 空,八类事件五实装两空格。2.0.3 把「拦」做成了引擎里的门,门后留了门闩和改档口;验收、进度、幂等这些格子还空着,是应用层的活。开场的翻案顺带演示证据分级:javap 签名是强推断,编译三关才是实测。

共约 5595 字 · 阅读约 14 分钟

开场:我记了一笔不存在的漂移,被一句追问翻了案

  先自曝一笔旧账。0012 的漂移台账第 10 处,我记的是"2.0.3 没有 DockerFilesystemSpec"——立账那天我把 filesystem、spec 两个包翻了个底朝天,没有就是没有,这笔我觉得稳得很。结课收尾时,用户一句追问送上门:相关的代码是不是都帮我开发了,实验是不是都做了,截图、代码、日志等等有没有进入学习资料。这句追问和 Lab-1 那次审计是同一款——学习者的审计意识两次抓出真缺口。

  我照实盘点,顺手把这条旧判决重新搜了一遍——类好好地在 sandbox/impl/docker/ 包里待着,image、network、cpuCount、memorySizeBytes、snapshotSpec、workspaceSpec 等 11 个字段一个不少。

  翻车点不是懒,是方法:搜包≠搜类。我搜的是两个包,类名没逐个 jar 找过;目录树里没有,不等于 jar 里没有。翻案之后证据跟着升级:原先只有 javap 签名核对,那叫强推断;审计追出的缺口还不止这一处——截图、服务端日志、考古记录的落档也都欠着,于是补证轮一起还:编译验证、考古落档、截图归档。编译那关补了三关探针——探针源码、classpath 配法、完整输出都在 evidence/0017/docker-spec-compile.txt 的 §1-§3(探针不调模型,无需 API key),此处节选:

$ javac DockerSpecProbe.java
JAVAC_OK

$ java DockerSpecProbe
compiled-and-linked
builder.accepted-filesystem-spec: true

  javac 过第一关(javac 成功时本身无输出,JAVAC_OK 是我标在档里的退出码 0 判读);java 起得来、链接得上是第二关;链上最后一步真执行、不抛异常返回非空是第三关——第三关完整输出带实现类全名,档里可查,此处有删节。三关全过,强推断升实测,旧判决作废。

  把这段翻案放在第 17 课开头,不只为了认错。它跟本课主角长着同一张脸:模型的意图要变成环境里的事实,中间隔着一串门;"我搜过的包里没有"就是一次没过门的意图,被追问逼回去重走一道门,才落成实测。口径照例先钉:AgentScope Java 2.0.3,标本是 0016 E3 五幕那次 run(2026-11-07 跑)加 0017 补证轮(2026-11-08),探针用 JDK 21;文中 evidence/ 路径一律相对 workbench 项目根。这节课拆的就是这串门:2.0.3 把哪几道装进了引擎,门后留了什么,门外还空着哪些格子。拆法照旧过闸:一次调用七拍、一张审批卡九格、一份环境契约九项、八类事件逐类归位——每一闸给打分,空格写上谁来做。

1、意图不是行动:三重不保证

  博客 04 开篇有一句话,值得原样抄给没读过系列的同事:

模型输出的工具调用只是一项行动意图。它没有自动获得当前用户身份,不等于企业策略允许执行,也不能证明远程系统已经产生预期结果。

  三重不保证:没身份、没许可、没事实。写 Java 的人对这串有体感——controller 收到请求,参数合法不等于身份对,身份对不等于有权限,有权限不等于下游真落库。模型吐出的工具调用,就是这条链路的发起端。这三重各对应后面一节:没身份,审批卡的"身份"格是空的(第 3 节);没许可,得过六步阶梯那道门(第 2、4 节);没事实,验收层根本没装(第 5 节)——博客这句话其实是全篇的目录。

  七课上到这里可以合龙了。博客给的合龙框架叫"行动与反馈系统",两张平面:Action Plane 管"拦不拦"——能力披露、参数校验、身份绑定、权限审批、隔离执行,五个控制点串成一道闸;Feedback Plane 管"记不记"——事件流、Trace、Evaluation 三层记录。两张平面不是两个模块,是同一次行动的两个视角。

  0016 那次 write_file 被拒就是双面现场:阶梯把它拦下,AgentTrace 留了痕,streamEvents 订阅端却没收到——同一件事,三处看见的东西不一样,只看一边会被骗。deny 是两边都有份的角色:走阶梯是它的 Action 面,留痕是它的 Feedback 面,拆开读才完整。图 17-1 把七课的住户请上两张平面——0001、0004、0005、0006、0012、0013、0016,各自在哪个平面的哪个控制点入座,图里对号。

01-AGENTSCOPEJA

2、一次被拦下的调用走了七拍

  平面先只拆一张:Action Plane 的第一道闸就是工具调用审批。拿 0006 那次 create_booking 当标本,一次被拦的调用在 2.0.3 里走七拍:

  1. 模型输出 ToolUseBlock,意图入账;
  2. 六步阶梯开裁——deny 规则、ask 规则、工具自检、allow 规则、mode 分性、兜底,先命中先裁决,这单停在第 2 步的 ask 规则;
  3. 判 ASK,账本记 ASKING,审批卡挂进 interrupts[];
  4. run 收尾——注意,是结束,不是暂停;
  5. 人点卡,resume 回来,这是一个新请求;
  6. 批准则标 ALLOWED,工具真跑;拒绝则合成 DENIED 结果回填 ToolResultBlock;
  7. 结果入账,AgentTrace 留痕。

  蓝图里 Action 生命周期画了 10 个态,2.0.3 折成 8 个语义格(终态并一格、异步并一格),格格有实物可指:

02-蓝图态2.0.3对应物出

  折叠的两处值得看一眼。终态并格:成败共用一个回填块,error 标志区分生死,消息世界的配对不变量不许拆成两个块。异步并格更说明问题:蓝图给"已受理、等结果"留了独立态,2.0.3 把这个等待整体挪去了 Task 层。timeout=0 的活不随 run 死,结果走 task_output 兜底取回(0013 E4 实测)。等待发生在任务层,不在动作层,这是 2.0.3 对"异步"的全部态度。

2.2 挂起=运行结束

  第 4 拍值得单拎,它反直觉:审批卡还挂在页面上,运行已经结束了。0006 的现场是这么走的:审批卡停在页面,账本记着 ASKING,RUN_FINISHED 已经发出——进程里没有一条线程在等你点头。这不是 HTTP 那种挂线程等数据库返回,倒像 Azure Pipelines 的部署前审批:门禁是流水线里独立的一关,人工批准或拒绝是关卡的一种配置,不是部署动作本身。resume 则是一个新请求,带着新账本重新进门。

  Interrupt record 里有个 expiresAt 字段,摆明了过期语义该有人管;AWS CodePipeline 的审批动作内建了这条:批准则恢复执行,七天内无人处理,等同动作失败。2.0.3 把字段给了,定时器没配:谁挂表、过期后账本记什么、要不要通知模型,按 API 面推断全归应用层(这一条未实测)。卡面等人,后头还得有人看表。这对应用的排查方式是直接改写:界面卡住别去查进程,先查账本里那条 ASKING 还在不在——run 的死活和页面的卡,是两回事。

  跟它划清界限的是另一个东西:interruption 包。权限 ASK 是运行末挂起,interruption 是运行中掐断——InterruptContext 记下被掐时还挂着的工具意图。ReActAgent 的 interrupt() 有 7 个重载,从无参到 (userId, sessionId) 组合都有——引擎把"叫停"当常用入口做。一个等人,一个叫停,别混。

2.3 空的两格

  8 个语义格全有实物,空的是两个机制格。其一,编排查询口:蓝图设想应用随时能问"这单现在处于哪格",2.0.3 没有这个 API:"当前跑到第几拍"这类监控页面得自己从事件流和账本里拼,这是我自己补的用法设想,蓝图只说到"没有查询口"为止。其二,幂等键:idempotency_key 双 jar grep 零命中。空格不是"我没找到"——证据里有一项对账,蓝图里 15 个机制词逐个往双 jar 里 grep,全零,空是搜实了的。

  幂等这格在货代里就是"同一张改单别执行两次":网络抖一下应用重试 resume,两次执行就是两次改单,中间没有键挡着——这笔账现在记在应用侧的请求单上。

3、审批卡上少印的五行

  门有了,门上贴的条子呢?博客 4.4.2 给审批请求列了九要素:想做什么、为什么、身份、作用对象、影响、参数差异、可逆性、失败处理、批准范围。2.0.3 实际递上来的是 Interrupt record,7 个字段:id、reason、message、toolCallId、responseSchema、expiresAt、metadata。逐格打分:

03-九要素Interrupt

  1 满、3 半、5 空。先把账定性:这笔分不是扣分。打分是自建清单——知道框架没给什么,才知道自己要写什么。

  两处细节把"空"讲实。"为什么"那格,workbench 的做法是应用层拼卡面(面板的 app.js)加模型自觉——plan_exit 自己往 summary 里填摘要,0016 那句"计划模式下 write_file 被只读策略拦截,需批准后退出计划模式才能落盘"就是模型手写的,框架一个字没给。身份格还有个隐性洞:卡上没有"谁批的、谁改的参",审计要落会话的 log.jsonl 自己查。影响、可逆性、失败处理三格,蓝图设想框架给,2.0.3 全留给应用。照蓝图验收的人会以为卡上九项俱全——"框架有审批,治理就齐了",本课后面五节都在拆这句。

4、蓝图要少问,引擎默认多问

4.1 分歧在哪

  九要素是纸面,默认档位才是天天撞上的那道门,这里蓝图和引擎真分歧了。博客 4.4.1 原话:

ASK 不是默认兜底。过多审批会让用户形成机械确认,也让 Agent 失去连续性。

  2.0.3 的 DEFAULT 模式第 6 步,兜底恰恰是 ASK,而且不分读写——0006 的 probe06 实测过,没挂任何规则的 get_current_time 照样停下等人。两边话事人不同:博客讲企业应然,fail 的那端是审批疲劳;2.0.3 讲框架默认,它不知道你的业务里哪些调用算低风险,fail-safe 宁多问不漏放。

  先各让一步:都对。审批疲劳链的机理不玄:卡一多,人就开始不看内容点确认,排在后面的危险动作同样被放行,这正是博客说的"机械确认";0006 答疑推过更硬的一条,无人值守跑批挂满 ask 规则,agent 会卡死等一个不会来的人。fail-safe 那端同样成立:框架不读你的业务规则表,它不知道查运价和删单的差别,唯一能做的保守选择就是停下来问,第一次误删没有后悔药。机制没有分歧,分歧在默认档位。"蓝图说的"和"2.0.3 做的"要分开记账——这是本课第二回撞见,第一回是开场的翻案。

4.2 怎么改

  落到自己项目,四步把档位调对:

  1. 查询类工具显式挂 ALLOW,别让查运价这类调用去撞兜底;
  2. 高风险动作用参数级规则——改单金额超阈值才 ASK,小额直接过;
  3. 无人值守场景把 ask 规则换成 deny 或 allow,二选一,不留"等人"的中间态;
  4. 还不放心就收窄工具加沙箱,0012 的纵深这时候才用上。

  规则表是你的,不是框架的——落地是改规则,不是抱怨引擎多问。四步改完,probe06 那种"查个时间也要人批"的卡就消失了——规则表是第一天的活,不是上线后的补丁。

5、三层审批装了两层半

  档位调完再看全景。审批往上还有一层:HITL 三层次(human-in-the-loop,人在环审批)。逐层对:

  1. Plan 审批——0016 实装:plan_write 写方案书,plan_exit 弹卡,拒绝是修订循环,模型列分歧点等方向;
  2. Action 审批——0006 实装:ASK 挂卡,卡上可 editedArgs 改参,resume 闭环;
  3. 结果验收——半格:交付通道在(deliver_artifact),验收判定无(Verifier 全 jar 零命中),"完成"只剩模型自觉,还是 SYSTEM 指令里"必须静默交付"压出来的自觉。

  标题里那个"半"就是这么来的:第三层的管道铺了,闸门没装——交付做得成,"做没做成"没人判。

5.1 三层次判决与 PACV

  博客把审批流程写成四拍 Preview→Approve→Commit→Verify,2.0.3 装了前三缺第四:预览有(卡面全参,方案书在盘上可审),批准有(可改参),提交有(resume 后执行),Verify 空——批准即置 ALLOWED,没有"重新校验对象版本"。这一缺在真实环境里有实害:审批卡挂半小时,目标文件可能早被人改过,批的是 A,执行的是 A'。Terraform 把这步做成显式状态(plan 完停在 Needs Confirmation,apply 前须有权限者动手),Stripe 把创建和扣款拆成两个调用——预览与执行分家是业界常态,但验证环节谁也没替你做。

  Verify 这一拍业界倒有现成参考。NIST 词汇表的职责分离条目收着双人规则:双人操作的第一执行者可以是任何授权用户,第二人必须与其不同;银行核心系统把它叫 maker-checker,制单与放行拆成两个角色。注意这只是"另一双眼",不等于"重新校验对象"——2.0.3 连这一拍都没装,四眼原则要架在审批角色上,得应用自己搭。

5.2 批准与拒绝的语义

  两句官方原话钉住这两条路:

批准结果应生成短时、限定目标与动作的授权,不能把整个 Session 永久切换成无条件放行模式。

拒绝也必须成为可恢复的任务事实,让 Harness 保留草稿并说明未完成项。

  第一句 2.0.3 打了对折:批准即置 ALLOWED 只对这一笔短时限权,不整段放行;"限定目标与动作"的细粒度授权,没有;Lab-1 那次 chat 腿 BYPASS 是我明知故犯的取舍,账记在那边。第二句实测兑现:0016 拒绝分支,草稿在 0016 实验台的 plans/PLAN.md 里纹丝没动,模型列四个分歧点等方向——拒绝可恢复,是真的。

6、环境契约是草图不是合同

6.1 九项打分

  动作要落地,得有环境接着。博客 4.3 的 Environment Contract 列了九项,2.0.3 逐项对——开场翻案的那个 DockerFilesystemSpec 全字段族(image、network、cpuCount、memorySizeBytes、environment、exposedPorts、additionalRunArgs、snapshotSpec、workspaceSpec、workspaceRoot、client,11 个)就住在这层:

04-契约项2.0.3现状判决

  2 满、4 半、3 空,判词:接口草图,不是合同范本——"声明"侧比"兑现"侧成熟。快照那项要单独看一眼,它是文件账和进程账两本账:

$ 沙箱 state 接口   → {"created": false}    进程账:没有活容器
$ ls snapshots/     → 4 × tar(各 10240 B) 文件账:快照都在
容器没了,快照还是文件;没有一键恢复,hydrate 得自己写。

  (按 evidence/0017/e3-environment-contract.json 快照对账记录整理)

  两本账对不上不是坏事,是提醒:文件能带走,进程活不过关机。"持久"只兑现了一半——断电续跑得先把 tar 装回新容器,hydrate 那一脚没人替你踩。

6.2 空格自建

  三个空格都要应用层补课,我按货代单证脚本的沙箱逐格记过:secret——environment(Map) 直塞,密文跟着环境变量落配置、落日志,"短时限权不记录密文"得自己包一层引用机制;依赖清单——镜像自带什么用什么,构建不可复现,pip 清单我写进了镜像构建脚本;审计清理——0012 的坑还在身上,stop 不真停、close 异步,收尾脚本里留着强杀加 rm -f。加上网络白名单,货代沙箱上线前要自建的就是这四件。四件的共同点是都不难,难的是想起来要写——蓝图读着像都有,合同签完才发现要自备四样。

7、八类事件:五类实装,两类连车都没搭

7.1 归位打分

  执行完,用户看见什么?这就切到 Feedback Plane 的"事件流"那层了。博客 4.5.1 列了八类事件,拿 0016 E3 五幕那次 run 对账(evidence/0016/json/e3-run1-curated.json,2565 个事件、16 个类型;八类分类对账另存 evidence/0017/e2-event-categories.json),逐类归位:

05-事件类本run计数归位T

  口径先说清:实装 5 类(Error 那格机制在、本 run 没触发)、搭车 1 类、协议层空 2 类。用户侧感知两句:长任务看不到"处理到第几步"——那次 run 里 12 次工具调用的先后就是全部线索,界面只能数 Tool 事件自己脑补阶段,"第几步"没有任何字段承载;产物交付在事件流里无一等公民信号,得去 TOOL_CALL_RESULT 里捞。先把一个易错结论拆掉:Progress 计数 0,不等于 2.0.3 没能力,三层分清:没有一等公民事件类型是协议层的事,没有机制才是能力层的事;2.0.3 有机制(提醒靠 system prompt 注入,产物靠工具回填),缺的只是协议层的专门事件。0 事件≠没机制≠没能力,三层各自成立。判 Progress 这格时我一开始也写成"没能力",对账单逼着我把三层拆开重写——打分表的价值就在这,它不许你含糊。

7.2 性格差

  没有专门事件,2.0.3 的性格是爱搭车:Usage 借 MODEL_CALL_END 出场,审批挂起借 RUN_FINISHED 里捎带的 interrupts[],Artifact 连附加字段都没有;产物只能以普通工具结果的身份被客户端解析。为什么这么设计?新增事件类型是协议破坏性变更,老客户端收到不认识的类型会炸;往现有事件捎字段是向后兼容——搭车不是偷懒,是版本策略。对照格 Approval:同样搭车,给了结构化 7 字段加 resume 强契约,待遇天差地别,可见空格是设计选择不是技术上限。

  另一处性格差方向相反:thinking 全量暴露。博客说"模型内部的隐藏推理不需要通过 Streaming 暴露",2.0.3 把 ThinkingBlock 全量转成 REASONING_MESSAGE_*,同一次 run 里 440 条 delta。对学习者是透明红利,我的考古一半靠它;对生产企业是泄露面,上线前这条流得自己掐。

7.3 别家的做法

  没有 Progress 类不是孤例,四家对了一遍(2026-11-08 查证)。Anthropic 的流式协议按消息和内容块切分,事件清单里没有进度类;它的协议页倒专门写了一句:可能新增事件类型,你的代码应优雅处理未知事件——协议层对扩展的稳健性要求,反向解释了为什么各家不爱加类型。OpenAI Agents SDK 用离散的运行条目事件做进度,tool_called、tool_output 都是一等事件,官方明说可用于"向最终用户展示进度更新"。Vercel AI SDK 的流协议里有 start-step/finish-step,一步等于"后端的一次 LLM API 调用",连工具审批请求/响应都做成了流部件。

  Claude Code 的 todo 清单干脆不是事件类型,官方文档原话:"You see each change in the message stream as a structured tool call."——清单变更以结构化工具调用出场,渲染权在客户端。两派收拢:步进级事件(OpenAI、Vercel),进度即数据(Anthropic、Claude Code)。AgentScope 站第二派,且连数据部件都没给——这格是真要自己写。

8、空格子清单:缺的不是能力,是收口

  各闸对完账,空格子集中挂牌,每格写上谁来做:

  1. 结果验收——Evaluation Harness 全 jar 零命中,挂 Eval-1;观测量有"多大"缺"为什么",哪份 Context 导出哪个 Action 没有结构化承载,Trace 缺因果;项目里那份 13 处的漂移台账就是手工版对账,开场第 10 处翻案恰好演示了判决为什么必须可复查;
  2. 编排查询口——"当前处于哪格"没有 API,应用层自己从事件流和账本拼监控;
  3. 进度与产物事件——应用层自己写:进度从 system prompt 注入或工具回填里自己提,产物信号自己包一层;
  4. 幂等与续传——幂等键应用层记,续传挂 0020/0024;
  5. A2A——挂 0029;
  6. 治理级能力目录——运行时注册表有 Tool/Model/Skill/Subagent 四个,治理目录空;注册表答"有哪些工具",治理目录要答"谁管它、它还活着吗、改动谁审批",两回事。

  最后拉别家收口。2026-11-08 查证:Spring AI 2.0.2 参考文档对工具执行链的完整描述里没有审批环节,官方原话是 "it is the application that owns the tool calling logic";LangChain4j 维护者在 issue 里直说 "There is currently no interface/API to implement HITL in LC4J.",另有讨论把持久化与可恢复归到集成层——"perhaps better of kept at the integration layer rather than in the framework itself";它唯一的框架级尝试是新 agentic 模块的 @HumanInTheLoop,页面自己标注整个模块实验性、随时可能变。时效提醒也带上:Spring AI 文档里 spring-ai-session 标注计划进入 2.1,这个领域各家都在动,上面的结论带日期,引用前先核对版本。

  对照下来分工清楚:别家把"要不要拦"留给应用代码,AgentScope 把"拦"做成引擎里的一道门,门后留着门闩(checkPermissions 覆写位)和改档口 setPermissionMode(运行时切权限模式,AgentConfig 之外唯一的运行时改档口)。门内的活引擎干了,门外这六格,是应用层的。

带走三样,临走三问

  整课收拢成一句:意图到事实隔着一串门,2.0.3 把"拦"装进了引擎(六步阶梯→ASK 挂起→resume 新请求),门后留了门闩和改档口;门外的格子——验收、进度、幂等、续传、治理目录——是应用层的活,打分表就是施工清单。

  带走三样:

  1. 挂起=运行结束,resume=新请求:审批卡挂在页面,进程里的 run 已经收尾;接着跑不是"继续",是新请求重新进门。排查"卡住不动",先分清它是在等人还是已经死了。
  2. 蓝图与制品分开记账:九要素 1 满 3 半 5 空,九项契约 2 满 4 半 3 空,八类事件五实装一搭车两空格——"框架有审批,治理就齐了"过不了这张账;照蓝图以为全有,落地第一天就翻车。
  3. 证据分级,判决可翻:javap 签名是强推断,编译+链接+执行才是实测,重要判决升到实测级再入档;搜包≠搜类,开场的翻案就是这么来的。

  临走三问:

  1. 你的 agent 无人值守跑批,跑到一半停了,审批卡在页面上没人点——run 现在是什么状态?若要求"半小时没人批就作废",应用层得记什么、查什么?
  2. 同事看完蓝图说"框架连审批都有,治理还愁什么"——把九要素表摊给他,5 个空格是哪 5 格?卡上"为什么做这件事",现在靠谁填?
  3. 产品要"处理到第几步"的进度条,你在事件流里搜不到 Progress 类型——按"三层分清"的口径,这该判"没能力"还是"没机制"?差的那层谁来补?

  三道都答对了,这一课才算真的带走。

  第 17 课结课,学习进度 17/57。

  下一篇 0018,Channel——agent 与聊天界面这类入口之间的适配层,gateway 包 42 个类已经排好队,下回拆。


如果这篇文章对你有帮助,欢迎转发给需要的同事和朋友。