model-with-tla:一个结合 Agent Skill、TLC Model Checker 和实现验证的工作流。

Coding Agent 已经可以完成相当复杂的软件开发任务。给它一份需求,它能够阅读现有代码、设计实现、编写测试、执行检查并修复错误。

但有一类问题仍然很难仅靠这样的开发流程发现:代码在正常执行顺序下完全正确,却在某种异步事件交错、资源生命周期变化或失败恢复路径中产生错误。

例如,一个后台任务正在处理某个资源。任务尚未完成时,资源被删除并重建,新的资源复用了原来的 ID。随后,旧任务的异步回调到达,把已经过期的结果写入新资源。

这里可能没有明显的数据竞争。每个函数单独执行都符合预期,正常路径的单元测试也能通过。真正出错的是操作的时间关系:一个结果在生成时拥有的权限,在提交时已经失效。

这类问题可以通过更细致的测试发现,但测试必须先构造出相应的事件顺序。如果开发者和 Coding Agent 都没有意识到这条路径,它就可能长期不在测试范围内。

我在过去几个月里尝试将 TLA+ 引入 Agent-assisted coding,并把相关工作封装为一个 Agent Skill:model-with-tla。

它不是一个自动证明代码正确的工具,而是一套围绕形式化模型组织开发和验证工作的流程:让 Agent 根据需求建立状态机,用 TLC 系统探索模型中的可能行为,找到违反要求的反例,再将这些反例映射到实现与测试中。

它要解决的核心问题是:

能否让 Coding Agent 在实现之外,建立一份独立的、可以主动寻找反例的行为模型?

为什么需要在代码之外建立模型?

一般的 Agent coding loop 大致是:

需求
  → 生成实现
  → 编写测试
  → 执行测试
  → 根据失败修改代码

这套流程对大量任务已经足够有效。但它有一个隐含前提:测试能够覆盖重要的错误行为。

对于异步和并发系统,错误往往不取决于某个函数的输入,而取决于多个动作发生的相对顺序。

考虑以下情况:

Task A: 读取资源状态
Task B: 替换资源
Task A: 收到旧操作的结果
Task A: 提交结果

如果 Task A 的提交逻辑只检查资源 ID,而不检查资源的具体生命周期,就可能写入一个逻辑 ID 相同、实际却已经被替换的资源。

问题不一定出在某一行条件判断,而可能出在整个系统对资源身份、异步结果和提交权限的理解上。

TLA+ 提供了另一种检查方式。

开发者不必首先编写某条确定的执行路径,而是定义系统有哪些状态、哪些动作可以改变状态,以及哪些情况绝对不允许发生。

TLC Model Checker 随后探索给定有限模型的可达状态和动作交错,寻找违反指定性质的路径。

常规测试与 TLA+ Model Checking 的状态探索对比

示意图:普通测试执行选定的场景;TLC 系统探索给定有限模型的可达状态。图中不代表实际覆盖率统计。

TLA+ 并不要求逐行模拟程序的执行。它关注的是那些会改变系统正确性的状态和动作。

例如,对于上述问题,模型可能只需要表达:

  • 当前资源的 incarnation;
  • 正在执行的操作所绑定的 incarnation;
  • 资源替换事件;
  • 异步操作完成事件;
  • 结果是否被允许提交。

然后检查一个 Safety 性质:旧资源上的操作,不能在资源被替换后修改新资源的状态。

如果模型允许违反该性质的路径,TLC 就能给出相应的状态转换序列。

这让开发者不必完全依赖自己预先想象危险的事件顺序。

model-with-tla 是什么?

model-with-tla 是一套用于并发和有状态系统的 Agent Skill。

它将三个部分组合起来:

第一部分是 Agent Skill。 它告诉 Coding Agent 什么时候值得建模、如何确定模型边界、如何定义性质,以及不同任务允许修改哪些文件和系统状态。

第二部分是 TLA+ 与 TLC。 TLA+ 负责表达状态机和正确性要求,TLC 在给定的有限配置中探索状态空间,检查不变量和时序性质,并生成反例。

第三部分是配套的检查与验证工具。 Skill 包含固定版本的 TLA+ 工具链,以及一个统一的 tla-check 命令,用于执行 SANY/TLC、检查预期结果并输出结构化证据。

三者的职责不同。

Agent 负责理解需求、建立抽象、解释反例和定位代码;TLC 负责执行模型检查;配套工具负责让检查过程和检查结果具备可重复、可判断的工程接口。

这套工作流不仅用于创建新的 TLA+ 模型,也可以用于已有系统的故障诊断、实现修改、审查和回归验证。

一次完整的建模与验证流程

整个工作流可以表示为:

model-with-tla 的完整工作流:需求、模型检查、实现映射和验证证据

第一步:确定要求,而不是复制当前实现

Agent 首先需要明确系统应该满足什么行为。

这一步非常重要,因为当前代码可能正是错误的来源。

如果简单地把现有实现翻译成 TLA+,即使 TLC 检查全部通过,也只能说明模型内部没有违反它自己指定的性质,不能说明实现符合真正的产品要求。

因此,Skill 要求区分:

  • 产品要求和已确认的设计决策;
  • 当前实现的行为;
  • 外部系统提供的事实与保证;
  • 尚未证实的假设。

例如,一个外部 API 调用超时,并不能直接证明操作没有执行成功。如果业务要求避免重复副作用,那么模型就必须保留「操作成功但响应丢失」这种可能性,除非外部 API 有明确契约排除它。

第二步:抽象出影响正确性的状态和动作

TLA+ 模型通常通过 Init 描述初始状态,通过 Next 描述允许发生的状态转换,再通过 Safety 和 Liveness 性质表达正确性要求。

重点不是把程序的全部细节搬进模型,而是找出哪些中间状态会改变正确性。

例如,一个代码中的 API 调用可能实际包含:

记录操作意图
    ↓
发起外部请求
    ↓
外部系统接受操作
    ↓
收到响应 / 响应丢失
    ↓
提交本地结果

这些阶段可能需要拆成不同的模型动作。

因为外部操作已经生效、但本地还不知道结果时,重试就可能产生重复副作用。一个同时发生的取消操作,也可能改变提交权限,却不能撤销已经发生的外部效果。

反过来,如果某个日志写入或 UI loading 状态不会改变待检查的行为,就不需要为了模拟代码细节而引入新的状态变量。

模型的粒度应由需要检查的正确性性质决定,而不是由源代码有多少函数或语句决定。

第三步:通过 TLC 寻找反例

在模型建立之后,Agent 使用 TLC 检查声明的性质。

一次正向检查可以回答:在指定的有限状态空间中,是否找到了违反性质的行为?

但仅仅检查通过还不够。

假设模型的要求是不能选择错误的资源,可是模型的资源集合中只有一个合法资源。此时,TLC 不可能发现错误选择,因为错误目标根本不存在。

model-with-tla 因此要求检查模型的 discriminability:模型不仅要允许正确行为,还必须有能力表示并识别目标错误。

对重要的 Safety 性质,应能构造相应的 negative witness,使错误行为在模型中可达,并确认 TLC 因预期性质被违反而失败。

这避免了一个常见问题:模型看似经过严格检查,实际上却没有包含它声称已经排除的错误。

第四步:把反例转成可执行的测试

TLC 输出的 counterexample 是状态转换轨迹。

Agent 需要进一步把它翻译成实际系统中的事件:

初始状态
  → 操作 A 开始
  → 资源或权限发生变化
  → 延迟事件到达
  → 出现被禁止的结果
  → 定位对应实现边界
  → 构造固定顺序的测试

这一步连接了形式化模型和真实代码。

例如,假设 TLC 发现旧资源的回调可以在替换后修改新资源。Agent 就可以构造一个受控测试:

先启动旧操作,暂停其完成回调;替换资源;再释放旧回调;最后断言新资源的状态没有被修改。

这个测试比普通的正常路径测试更有针对性,因为它直接来自一个已知能够破坏模型不变量的执行序列。

第五步:检查模型、实现和外部证据是否一致

模型通过不等于代码通过。

一个正确的模型可能把某段行为视为原子操作,但实际代码在两个语句之间允许另一个任务插入。也可能模型正确区分了资源 incarnation,而实现只使用可复用的资源 ID。

因此,model-with-tla 将验证证据分为多个层次:

Requirements model
    ↓
Refinement / focused obligation
    ↓
Controlled implementation trace
    ↓
External evidence
    ↓
Convergence observation

它要求明确区分一个局部性质检查、有限配置下的 refinement 检查,以及真正建立了声明范围内证明关系的 refinement。

当证据不完整时,工作流不会把所有结果都报告成「验证成功」,而是采用 closed、scoped、drifted、blocked、unproved 等状态表达完成范围和剩余假设。

这里的重点不是制造更多验证文件,而是防止 Agent 把某一层的成功错误地扩大为对整个系统的保证。

如何在 Coding Agent 中使用?

Skill 将工作划分为五种操作模式。

模式 什么时候使用 主要结果
design 开始设计具有复杂生命周期或并发行为的新功能 建立需求模型,检查 Safety 和 Liveness
diagnose 已经观察到故障,希望定位其时序原因 构造并解释可复现反例,不修改产品代码
refine 已有需求模型,需要修改实现或低层模型 对齐模型与实现,补充受控测试
review 需要审查模型和实现之间是否存在语义缺口 只读检查,报告可操作的问题
verify 需要重新执行已有检查或发现漂移 只读验证,报告检查结果与证据边界

例如,在开发一个包含异步任务、取消和重试的功能之前,可以显式调用 model-with-tla 的 design 模式,让 Agent 先整理状态和操作边界,构造模型并检查性质。

如果已经出现故障,则可以先使用 diagnose,要求 Agent 保留现有实现,重点复现错误路径。确认问题后,再通过 refine 修改有权限变更的代码和测试。

已有模型的项目可以使用 verify 重新运行检查,检查代码与模型是否仍然遵守相同的身份、生命周期、外部副作用和终态语义。

Skill 也会按任务选择所需的参考文档,而不是每次都要求 Agent 处理全部形式化概念。

配套的 tla-check 工具

Skill 自带 tla-check 入口,统一执行 SANY/TLC。

例如,检查一个模型的正向配置:

"<skill-directory>/.tools/tla-check" check \
  --module "/absolute/path/Model.tla" \
  --config "/absolute/path/Model.cfg" \
  --expect success

对于预期违反 NoDuplicate 的负向配置,可以将期望改为:

--expect invariant:NoDuplicate

工具不仅检查进程是否成功结束,还会比较预期的检查结果与实际观察到的结果。

如果期望的是 NoDuplicate 被违反,但 TLC 首先报告 TypeOK 违反,那么这不算成功重现目标问题。

工具还会验证所使用的 TLA+ JAR、版本信息和校验和,检查 Java 兼容性,隔离 TLC 生成的临时状态,并返回包含状态数量、搜索深度、执行耗时和诊断信息的结构化结果。

当前工具要求 Java 11 或更新版本,以及 uv。首次初始化检查环境时还需要网络连接。

这些机制不负责判断模型是否抽象正确,但能减少 Agent 在工具调用、版本漂移和结果解释上的不确定性。

一个具体例子:旧回调修改了新资源

重新考虑开头的资源管理问题。

系统中有一个逻辑资源 worker-A。资源被替换后仍然可以使用相同的名字,但旧资源和新资源并不是同一个生命周期中的实体。

旧资源回调延迟到达并错误提交到新资源的事件时序

假设 Operation X 绑定的是 incarnation 1,而当前资源已经进入 incarnation 2。

一个只比较 worker-A 名字的提交逻辑可能接受旧结果,导致新资源被错误修改。

对应的模型可以检查如下 Safety 性质(以时序逻辑记号表达):

□(Commit(r) ⇒ Authorized(r, current))

也就是说,任何被提交的结果,都必须满足当前状态下的提交权限要求。

具体怎样定义 Authorized,取决于系统的产品契约。它可能需要比较资源 incarnation、operation identity、观察版本或当前用户意图。

当 TLC 给出违反该性质的路径后,Agent 可以将其映射到资源替换、回调处理和状态提交代码,并构造控制事件顺序的测试。

还有一个需要继续处理的边界:如果旧操作不仅返回结果,还在外部系统创建了资源,那么拒绝旧结果的提交并不意味着外部资源已经消失。

此时仍然需要知道哪个操作负责清理该资源、清理是否确认完成,以及清理失败时系统应该保持什么状态。

这就是为什么 model-with-tla 不仅关注并发交错,还显式建模 identity、epoch、effect ownership、cancellation 和 convergence。

很多时序问题的根源并非执行顺序本身,而是系统在状态变化之后,仍然错误地接受了旧操作的权限、观察或责任假设。

为什么 TLA+ 和 Coding Agent 的组合值得尝试?

这种组合的价值不是让 LLM 自己完成形式化证明。

LLM 仍然负责理解系统、设计状态抽象和解释模型结果。它可能遗漏重要状态,也可能错误理解需求。

但一旦模型和性质定义明确,TLC 就能在指定的有限状态空间中系统地探索执行路径,而不必依赖 LLM 自己逐条猜测所有可能的事件顺序。

两者因此形成互补:

Coding Agent 负责构造和修改可检查的系统模型,TLC 负责寻找违反模型约束的行为,Agent 再负责把反例转化为实现修改和回归测试。

这种分工带来三个实际变化。

首先,形式化建模的成本降低了。过去需要开发者手工完成的大量建模、配置编写、结果分析和测试映射工作,现在可以由 Agent 协助执行。

其次,模型检查提供了独立于 LLM 主观判断的反馈。与要求 Agent 再次阅读自己生成的代码相比,一条由 TLC 找到的反例具有明确的状态和执行顺序,更容易成为可复现的工程问题。

最后,重要的时序假设可以被保留为可重新执行的模型与配置,而不是只存在于某次对话、代码审查意见或临时测试中。

这些收益并不意味着所有系统都值得建模。更适合的对象通常具有明确的状态生命周期、多个可能交错的操作,以及对异常顺序、重试、取消或恢复行为的要求。

形式化检查能保证什么,不能保证什么?

使用 TLA+ 时,最重要的不是得到一个成功标记,而是明确成功结果的适用范围。

第一,TLC 检查的是指定模型和配置。 如果模型遗漏了一个重要状态,或者配置通过限制状态空间排除了错误路径,检查通过并不能证明被遗漏的行为安全。

第二,Safety 和 Liveness 依赖不同的条件。 Safety 检查坏事是否可能发生;Liveness 检查在规定假设下,好事是否最终发生。

例如,对一个 completion action 施加 weak fairness,并不能保证外部服务真的返回响应。只有当相应动作持续 enabled 时,弱公平性才提供所需的调度保证。外部事件是否出现,需要单独建模或明确声明为环境假设。

第三,模型与实现之间存在需要验证的映射关系。 有限模型检查、受控代码测试和真实平台观测是不同层次的证据,不能互相替代。

model-with-tla 的 model adequacy、refinement 和 evidence closure 机制,主要就是为了让 Agent 在自动化过程中保留这些边界。

它们提高了结论的可审查性,却不能自动消除模型建错、需求不完整或外部系统违反假设的风险。

什么时候值得使用?

对于纯展示性的 UI、静态内容或没有复杂状态生命周期的确定性操作,普通测试和代码审查通常已经足够。

如果系统涉及并发请求、异步回调、资源替换、重试和去重、取消后的副作用、事务中间状态、超时恢复,或者必须最终完成的进展要求,那么通过 TLA+ 检查这些状态转换就更有价值。

尤其值得在实现前建模的是那些正常路径容易实现,但异常路径会改变资源身份、操作权限或外部副作用责任的功能。

这类错误一旦进入真实系统,往往难以通过普通日志和偶发的集成测试复现。

结语

Coding Agent 让软件实现变得更快,但实现速度的提高并不会自动增加对并发行为和生命周期边界的理解。

model-with-tla 尝试在日常 Agent-assisted coding 中加入一条不同的反馈路径:

理解行为要求
  → 建立抽象状态机
  → 检查 Safety / Liveness
  → 寻找可复现反例
  → 映射到代码与受控测试
  → 保留范围明确的验证证据

它并不是要为每一段代码提供完整的形式化证明,而是让那些过去容易停留在开发者直觉中的时序假设,变成可以表达、检查、反驳和回归验证的工程对象。

这套工作流最重要的改变,是让 Coding Agent 不仅负责生成一个实现,还能够在实现之外,系统地寻找这个实现可能违反的行为契约。

项目与实现细节: