Aptos Move 规范推理实战:深入 move-inf 的混合战术、WP 推理与候选检查工作流
Aptos Move 规范推理实战:深入 move-inf 的混合战术、WP 推理与候选检查工作流
在 Aptos 区块链的 Move 开发中,为智能合约补全完整的规范(specification)与循环不变量,是让 Move Prover 能证明合约正确性的关键一步,也是公认的高门槛工作。Aptos 在 aptos-move/flow/cont 目录下提供了一套面向 AI Agent 的 Move 开发工作流(move-flow),其中 move-inf Agent 专门负责"规范推理"(Specification inference):自动推断缺失的合约条件与循环不变量,并借助最弱前置条件(Weakest Precondition, WP)推理与候选检查(candidate check)完成验证闭环。本文以 spec_inf_tasks.md 为核心,结合其配套模板与仓库源码,完整拆解这套推理工作流的战术体系、工具调用链、诊断处理规则与输出纪律,帮助你理解并复现一套"从 WP 推导到 Prover 验证"的自动化规范补全流程。
一、任务定位:move-inf 在做什么
move-inf 是 aptos-move/flow/cont/agents 下的一个 Agent 定义,其任务说明位于 agents/move-inf.md,并在 skills/move-inf/SKILL.md 中给出了技能级描述:"Infer and verify complete Move specifications and loop invariants. Use when contracts are missing; not merely to check existing specs."(推断并验证完整的 Move 规范与循环不变量;仅在合约缺失时使用,而非用于检查既有规范)。
任务模板 spec_inf_tasks.md 开篇即给出核心任务定义:
- 为请求的函数或模块推断一份完整的规范;
- 保留可执行行为(executable behavior),即不能改变函数实际的运行语义;
- 保留用户已编写的规范,即推理出的内容必须与用户手写的条件共存,不能覆盖或篡改。
整个工作流明确强调:规范推理是一个"编译加证明"的循环(compile-and-prove loop),而不是"编译加测试"的循环。单元测试通过只能说明部分输入路径行为正确,而 Prover 对所有输入进行推理,因此运行包内单元测试既不能佐证合约成立,也无法定位缺失条件,还会在包内留下覆盖率映射。这一原则在 spec_inf_rules.md 中被反复强调。
二、战术体系:direct、hybrid-flexible 与 hybrid-guided
模板支持三种推理战术,其中两种混合战术(hybrid)默认启用,具体默认值由 inference_tactic 参数决定,表现形式为连字符替换(replace(from="_", to="-"),例如 hybrid_guided 渲染为 hybrid-guided)。调用者可以通过 /move-inf hybrid-guided <scope> 或 /move-inf hybrid-flexible <scope> 显式选择战术并指定推理范围(scope),其余参数由 $ARGUMENTS 传入,Agent 必须只遵循被选中的战术。
2.1 Direct tactic(直接战术)
当 inference_tactic == "agent_only" 时启用。该战术要求 Agent 直接从实现代码与依赖合约中推导契约(contract)与循环不变量,一次只检查一个连贯的候选方案,然后只修复被拒绝的部分,不借助 WP 工具的自动化推导通道。
2.2 Flexible hybrid tactic(灵活混合战术,hybrid-flexible)
该战术把 move_package_wp 作为一条可选的推理通道(inference pass)开放给 Agent,由 Agent 自主决定是否使用、何时使用,可将其与直接推理、不变量综合(invariant synthesis)结合。WP 可以在任何 scope 上运行,包括含循环的函数。其结果的解读统一遵循 WP tool 一节(见下文第四节)。
关键行为差异由 no_wp_simplification 参数控制:
- 默认(未设置该参数):在可修复的警告(repairable warnings)全部解决后,按契约需要尽可能简化推导结果,同时保持其语义不变,再检查候选;
- 设置
no_wp_simplification:直接检查生成的子句,仅在需要处理诊断时才对生成内容做改动,避免无意义的化简。
2.3 Guided hybrid tactic(引导式混合战术,hybrid-guided)
这是最结构化的战术,规定了严格的操作顺序,也是模板中笔墨最多的部分:
- 在请求的 scope 上运行 WP(
move_package_wp),包括含循环的函数,并将结果输出到指定位置; - 处理 WP 的诊断,遵循 WP tool 一节:缺失循环不变量时逐个函数修复并重跑 WP;保留继承自被调用方的 partiality(继承的部分性),因为重试调用方无法消除它;
- (默认情况下)化简 WP 推导出的内容,同时保留每一个 result(返回结果)、abort(中止)与 frame(全局状态修改)义务,化简参考见后续章节;
- 检查候选(candidate check):若修复超时则使用证明指引(proof guidance);若对未经修改且无警告的 WP 输出仍然出现反例(counterexample),则该反例属于工具 bug,应上报失败条件而非弱化合约。
若设置了 no_wp_simplification,第 3 步省略,直接检查生成的子句。模板通过条件语句 {% if args.no_wp_simplification %}3{% else %}4{% endif %} 动态编号,可见"简化"在默认流程中被视为独立且必须的一步。
三、核心工具链:四个关键命令的分工
规范推理闭环由四类工具协作完成,模板 core_tools.md 与 spec_inf_rules.md 给出了明确分工:
| 工具 | 职责 | 关键参数 |
|---|---|---|
move_package_wp |
推导(推理)条件并写回源码 | package_path;可选 filter("module" 或 "module::function");spec_output: "inline"(默认,写入源码)或 "file"(生成 .spec.move 伴随文件) |
move_spec_check |
唯一的完成判定工具:编译包、验证目标、拒绝自我弱化的合约并报告未覆盖的义务类别 | package_path;可选 filter;timeout(建议初试 initial_verification_timeout 秒、重试 max_verification_timeout 秒) |
move_package_verify |
定位验证失败(候选检查报告失败后使用) | package_path + 显式 timeout;filter、exclude、split_vcs_by_assert: true、error_limit |
move_package_status / move_package_manifest / move_package_query |
回答包结构问题 | 均需 package_path(指向含 Move.toml 的目录) |
其中 move_package_query 提供结构化查询能力:module_summary(签名与声明)、facts(详细声明、属性与源码位置)、dep_graph(模块依赖)、call_graph(包级调用)、function_usage(指定 function: "module::function" 后给出该函数的直接/传递调用与闭包捕获)。模板特别提醒:用 function_usage 确认可执行调用与闭包捕获,而不是从 import 推断依赖。
需要强调的是,move_spec_check 在接受候选时本身就执行验证,因此它取代了收尾时对 move_package_verify 的重复调用:紧接着再跑一次验证是重复劳动(check 即将做的工作),之后再跑则是重复证明(check 已证明过的内容)。Prover 只用于初始诊断或通过更窄的 filter 定位已报告失败。
四、WP 工具语义:推导结果如何解读
wp_tool.md 是 WP 工具的唯一权威说明。move_package_wp 从返回、中止、调用与状态更新自后向前(backward)推导条件,即经典的最弱前置条件推理:用循环不变量表示循环,不变量未约束的值在循环后视为任意值(见 wp_concepts.md)。
推导结果按函数逐一解读,分为五种情况:
-
无警告(No warnings):生成的规范按构造即完整且正确,涵盖隐式算术、边界、资源与被调用方中止。注意 WP 不运行 Prover,因此验证仍可能超时——此时应修复证明或使用等价的、对求解器友好的表达式,但不得弱化合约。若对未修改、无警告的输出出现编译错误或反例,属于工具 bug。
-
缺失或不充分的循环不变量(Missing or inadequate loop invariant):补充一个"进入时成立、每次迭代保持"的不变量。警告中提供的有界循环头观察(bounded loop-head observations)只描述所展示的执行前缀,不是证明——应从中概括出在入口成立且能跨越一条回边(back-edge)的谓词。修复后删除过期的生成函数子句,但保留不变量、辅助函数与用户子句,再为该函数重跑 WP。
-
部分 opaque 或无函数体被调用方(Partial opaque or bodyless callee specification):这是唯一能让调用方合法地部分化(partial)的被调用方情形。当该边界保持部分时,调用方不可能拥有完全的中止覆盖。正确做法是:保留
pragma aborts_if_is_partial、在契约中注明该具名被调用方,不要通过重写调用方或删除 pragma 来宣称全量性。候选检查对继承部分性的接受规则见下文。 -
透明被调用方缺少完整 opaque 契约(Transparent callee without a complete opaque contract):WP 无法在此情况下补全调用方。若该被调用方在可编辑 scope 内(例如同模块),先为它推断并验证 opaque 契约,再对调用方重跑 WP;若在 scope 外,将依赖上报为 corpus/package 阻塞项(其所有者必须提供完整且已验证的 opaque 契约)。绝不允许以此为由在调用方上启用
aborts_if_is_partial。 -
未建模的 Prover 内建函数(Unmodeled prover intrinsic):这属于 WP 工具 bug。Intrinsic 执行 Prover 内建语义而非其 Move 函数体,因此不要为其添加源码级规范或将其 opaque 化——WP 必须在内部提供其值、中止与变更语义。
模板以一句话收束:"条件的意外丢失、畸形输出或任何其他推理失败都是工具 bug,而不是弱化规范的邀请。"
五、候选检查:推理的收尾判定
candidate_check.md 定义了推理(以及手写验证)的收尾步骤。move_spec_check 是规范被"测试"的方式:它编译包、验证目标、拒绝自我弱化的合约(如验证被禁用或跳过、空洞条件(vacuous)、无被调用方支撑的部分中止 pragma),并报告合约未覆盖的义务类别。
判定结果分三类:
- 接受(Accepted):请求的 scope 已完成,停止并报告;
- 拒绝(Rejected):标题行指明哪个检查失败,后续诊断行格式为
path:line: code: message。用聚焦的move_package_verify定位验证失败并修复后重跑候选检查。弱化代码(weakening code)指向引入弱化的子句;若弱化并非你引入的(项目本就存在的可信边界),应上报而非移除; - 不可用(Unavailable):Prover 未能运行。这不是对规范本身的判定,照实上报即可。
候选检查"按书面内容读取规范"(reads the specification as written)。一个合法的自查技巧是:通过突变一条条件并重新检查来试探自己的契约,以确认某条子句确实承担了证明义务——代价是每试探一次就要多跑一轮验证。
六、推理规则与安全护栏:什么能做、什么不能做
spec_inf_rules.md 是本任务的共享决策与安全护栏,任何战术都必须遵守。
6.1 范围与证据
- 只在请求的函数或模块内工作;除非用户要求测试规范,否则跳过
#[test]与#[test_only]函数; - 写条件前先读实现、既有规范与相关被调用方契约;
- 保留用户编写的规范:若与实现冲突,上报冲突而非静默改变其含义。
6.2 完成标准
描述调用方可观察的全部行为:正常结果与被修改的引用值;每一个直接与传递的中止(含算术、边界与资源访问);全局状态变更及其 modifies 框架;真实的 API 前置条件;证明函数体所需的循环不变量。边界情形必须显式检查——相似的控制流可能在空输入或单元素输入上表现不同,且没有源码 assert! 的算术也可能中止。
6.3 pragma opaque 的正确使用
- 为推理目标编写的规范必须加
pragma opaque。这是整个任务被评判的核心声明:它告诉 Prover 调用方可以只依据契约(而不读函数体)被验证。缺失 result、abort 或 frame 的契约不仅是"不完整",而是错误——调用方将针对实现未兑现的承诺被验证。因此应把契约写到"该声明成立",而不是删掉 pragma 让部分契约自圆其说。 pragma opaque不会关闭函数自身函数体的验证,opaque 契约仍然必须针对实现被证明;- 不要给 scope 之外的辅助函数添加
pragma opaque:只有 scope 内的函数会被证明,辅助函数的 opaque 契约将在目标的调用点被"假设"而从未被验证,候选检查会因此拒绝。透明辅助函数根本不需要契约——Prover 读取其函数体,目标将针对辅助函数的真实行为被证明。
6.4 禁止弱化
绝不能为了通过验证而弱化契约:不删除或收窄行为条件、不发明限制性 requires、不启用部分中止覆盖、不省略 frame、不跳过验证。替换条件只能用语义等价且完整的形式。
6.5 继承的部分性(Inherited partiality)
部分中止覆盖只有一条狭窄例外:当调用方针对 opaque 被调用方的契约(而非函数体)被验证,而该契约本身是部分时,调用方已无精确中止条件可写,此时 pragma aborts_if_is_partial 是诚实的表达而非弱化。它只对你发现的部分性生效(推理为被调用方报告的部分性,或起始代码树中已有的部分性)——你自己写入的部分性不在此列(把辅助函数标记为部分再引用它,会为任何契约开脱,候选检查会拒绝)。例外适用时,必须在契约中说明部分性来自哪个被调用方;该被调用方保持部分期间,调用方必须保持部分,这条警告不是调用方的修复义务,也不需要反复调用 WP。
七、循环不变量推理:四种常见形态与 folds_of
循环抽象是规范推理中最需要技巧的部分。模板要求从不变量与循环退出时所需的事实推导不变量,它必须初始成立、单次迭代保持、并约束每个被循环修改的相关值。被报告"需要不变量"的循环会附带前几次迭代的有界循环头事实,需将其概括为入口成立且跨越一条回边的谓词。常见形态包括:
- 累加(Accumulation):把累加器与已处理前缀关联,常借助递归辅助函数或"已处理 + 剩余守恒"关系;
- 搜索(Search):记录索引边界与已处理前缀上已知的事实,包括结果所需的首个匹配/无匹配事实;
- 量化遍历(Quantified traversal):把最终量词限制在已访问前缀上;
- 有状态遍历(Stateful traversal):把被修改的引用或资源与其循环前状态关联,并声明必要的 frame 事实。
对行内高阶迭代器引入的循环,当其捕获变换器(capture transformer)能精确表达累积效果时,使用 folds_of 不变量:folds_of<f>(values, i) 概括一元回调在前缀上的效果,folds_of<f>(|j| (j, values[j]), i) 提供显式参数元组;该谓词包含累积捕获效果与前缀无中止行为,仅作为循环不变量有效。若 Prover 提示 fold 不适用,改写为等价普通循环并提供显式不变量。
被推断出的 vacuous(空洞)或 sathard(SMT 求解困难)子句是未解决的义务,不是可删除的子句,需诊断其来源:循环 havoc 需要更强循环抽象;困难的量词或非线性表达式需要等价、求解器友好的表示;未约束的 result_of / ensures_of / aborts_of 载体需要更强的被调用方或函数值契约。
八、证明失败诊断与超时策略
推理出的契约最终要过 Prover 这一关,verification_ref.md 提供了完整的失败诊断框架。
8.1 读反例
反例展示一次失败执行的帧与求解器选定的值。要点:具名局部变量以其源码名出现,result 是返回值,先从这里推理;$t<N> 是编译器/Prover 引入的临时量(无源码对应物,不要在规范中引用);标记 (spec) 的帧位于函数规范块内(求值的是条件而非执行代码);<generic> 是被隐藏的类型参数值;函数值以其来源实体打印,闭包显示其打包函数与按参数名捕获的参数。反例中函数值的行为只由规范对载体的陈述决定,因此要为其提供精确的 result_of 与 aborts_of 条件。
8.2 中止码解读
诊断中止码不匹配前,先读依赖的 error.move(本仓库位于 aptos-move/framework/move-stdlib/sources/error.move)。std::error::canonical 契约故意 opaque:其 [abstract] 后置条件只返回类别(category),[concrete] 后置条件描述运行时编码 (category << 16) + reason。例如 error::invalid_argument(40) 运行时编码为 0x10028,但在抽象契约下 Prover 只见类别 0x1(error::INVALID_ARGUMENT)——因此只有类别的反例本身不是工具 bug,也不意味着运行时 reason 丢失。在抽象契约生效处应使用类别常量,而运行时单元测试仍用具体编码。
8.3 编辑前分类
失败按五类处理:编译/规范语言错误先修语法、名称解析、放置或非法 old() 用法;后置条件反例追踪正常路径,判断是实现在违约、被调用方契约太弱还是循环不变量丢失了必要事实;中止反例枚举直接与传递中止(含算术、索引、资源与 opaque 被调用方),补全精确中止行为;frame 失败对比可执行全局写与 modifies 子句(尤其跨 opaque 被调用方);不变量失败分别检查初始化、保持与循环退出蕴含——更强的不变量只有函数体能证明它才有用;超时/资源耗尽把契约视为"未解决"而非"错误"或"已验证"。
8.4 超时分析
超时诊断附带重放证据(prover 在 profiling 求解器下重跑捕获的查询),计数描述同一义务但不精确,+ 表示下界。量词活动(quantifier activity)按求解器实例化排序并命名源码位置——应减少该条目需要的实例化,而非提高预算;definition of spec function 条目指向辅助函数:使其递归与循环对齐(一次义务展开一步)并保持单一递归;forall 条目指向书写的量词:给出有效 trigger 或用 frame/有界关系替代。非线性算术活动(arith-nla-* 计数器)出现时,优先加法递推而非闭式解,不变量中避免符号乘积。
超时策略按序执行:① 化简 WP 生成或手写表达式(移除已证明冗余、提取公因子、替换机械更新、修复空洞或 sathard 循环输出);② 用 split_vcs_by_assert 与小 assert 证明提示暴露中间事实;③ 用等价 frame、有界关系或递归辅助函数替换敌意无界量词;④ 优先加法递推;⑤ 把可复用事实证明为 lemma 并用 apply 显式实例化,对分析点名的递归辅助函数或 forall ... apply 加 [weight = N] 让求解器停止自行展开;⑥ 按需提高单条件超时(通常建议 max_verification_timeout 秒,非硬上限)。
九、输出纪律与最终报告
9.1 输出纪律
- 每条书写的条件与不变量标记
[inferred],绝不标记既有用户子句; - 遵循包的
inline或.spec.move放置约定,循环不变量永远留在其可执行循环旁; - 避免等价重复与空规范块,为非显然的辅助函数和 lemma 写文档;
- 收尾时文件格式化、编译干净,scope 内无未解决的
vacuous、sathard、无不变量循环或不适用 fold 诊断。
9.2 最终报告
spec_inf_report.md 规定推理结束以至多三条紧凑要点收尾:
- Result(结果):陈述新增的契约或不变量及最终验证/接受状态;未解决时点明阻塞义务;
- Strategy(策略):说明采用的方法与关键工具,以及该策略为何适合此问题;
- Decision points(决策点):总结最多两个关键抉择,每个都配以促成该抉择的证据或结果;省略例行步骤与逐轮流水账。
十、Move 规范语言要点速查
推理产物最终以 Move 规范语言书写,spec_lang.md 提供了工作流自用的速查:
- 函数契约:
spec function_name { ... }挂载条件(软关键字函数名用spec @function_name)。requires e是前置状态求值的调用方义务;aborts_if e描述前置状态中允许的中止(完整中止检查下,所有aborts_if的析取刻画函数中止行为,无子句表示未指定、全函数用aborts_if false);ensures e是后置状态求值的正常返回保证,前置状态值用old(e);modifies global<T>(addr)声明可能变更的全局状态框架——opaque 函数若可变全局资源需覆盖每个资源/地址效果,而只读不写的函数不应虚构modifies; - opaque 与 intrinsic:
pragma opaque改变调用方验证方式(用契约代替实现),但不关闭自身函数体验证;pragma intrinsic表示内建 Prover 语义,不要为其发明 opaque 契约或函数体证明; - 规范表达式:
result在ensures中表示返回值;global<T>(addr)/exists<T>(addr)检查全局资源;规范使用数学整数(数值界如MAX_U64指 Move 值,规范表达式内算术无界);表达式作用于值而非引用(用v.field而非*v);old(e)表示函数入口值,不要在已是前置状态表达式的requires/aborts_if中使用,循环不变量中old(x)仅对函数参数有效,其他循环前值需先存入局部变量; .spec.move伴随文件:spec module { ... }放辅助函数、lemma 与模块不变量,spec function_name { ... }放函数条件,不存在spec <module_name> { ... }形式;[inferred]标记:WP 可能输出[inferred = vacuous](状态未约束)与[inferred = sathard](SMT 求解困难),两者都表示未解决的推理输出。
十一、工作流生态:从 Agent 定义到插件钩子
这套推理工作流不是孤立模板,而是完整编排体系的一部分:
- 入口组装:agents/move-inf.md 与 skills/move-inf/SKILL.md 通过
{% include "templates/spec_inf_tasks.md" %}引入任务模板,再按需引入参考材料(spec_inf_ref.md 组合了规则、WP 概念、WP 工具、核心工具与规范语言),最后追加验证参考与报告模板。SKILL.md在tactic_selectable时给出参数提示[hybrid-guided|hybrid-flexible] [scope]; - 引用聚合:spec_inf_ref.md 说明推理参考材料的分层组织:规则 → WP 概念 →(启用时)WP 工具 → 核心工具 → 规范语言,形成"任务 + 参考"的双层模板结构,
once守卫确保每份材料只渲染一次; - 插件钩子:hooks/hooks.json 定义了
move-flow插件的三个钩子:会话启动时检查move-flow二进制是否存在(不存在则提示安装或设置MOVE_FLOW环境变量);每次编辑/写入.move文件后自动执行move-flow hook edit(保持格式化与编译清洁);每次用户提交提示时执行move-flow hook package-path(自动推断当前包路径)。
结语
从 spec_inf_tasks.md 这张任务编排模板出发,可以完整还原 move-inf 的规范推理闭环:选择战术(direct / hybrid-flexible / hybrid-guided)→ 用 move_package_wp 做最弱前置条件推导 → 按 WP 工具语义分类处理诊断(补循环不变量、保留继承部分性、上报工具 bug)→ 化简并保留全部义务 → 用 move_spec_check 做候选检查收尾,全程遵守"不弱化契约、[inferred] 标记、pragma opaque 只加给 scope 内目标"的输出纪律。这套流程把"补全 Move 规范"从依赖个人经验的苦差事,变成了可复现、可判定、可上报的工具化流程——对于在 Aptos 上编写高价值合约并希望用 Prover 证明其正确性的团队,它既是实战操作手册,也是理解 WP 推理与 Prover 验证协同方式的绝佳范本。