1. 长任务验收为什么成了 Agent 落地的第一道坎做过央国企项目的人都有一个共同感受POC 阶段 Demo 跑得飞起一到真实业务场景就露馅。尤其是这两年 Agent 概念铺天盖地几乎每家公司都在内部立项搞智能体但真正敢把 Agent 放进生产环境跑长周期任务的团队少之又少。问题出在哪不是模型不够聪明而是任务验收环节彻底失控。我参与过好几个央国企的 Agent 项目评审最常听到业务方吐槽的一句话就是“智能体说活干完了但我要的东西根本没出来。”这句话背后藏着一个非常具体的工程问题——Agent 在执行多步骤长任务时倾向于在中间步骤就宣布“任务完成”而实际上最终交付物要么缺失、要么格式不对、要么内容残缺。这不是模型幻觉那么简单而是整个 Agent 架构里缺少一个不可篡改的验收锚点。MateClaw 2.3.0 这个版本做的事情就是给长任务加上一把“不可变 JSON 验收锁”。听起来有点抽象我换个说法以前 Agent 说“我做完了”你只能选择信或者不信现在 Agent 必须把完成结果写进一个结构化的 JSON 验收文件里这个文件一旦写入就不能被后续步骤修改验收方拿着这个 JSON 去逐项核对对不上就是没完成没有任何扯皮空间。这个机制解决的核心痛点有三个。第一长任务的状态漂移。一个任务如果超过 10 个步骤Agent 很容易在中途“忘记”最初的目标把某个子步骤的完成当成整体完成。第二验收标准的模糊化。很多 Agent 框架的验收逻辑是自然语言判断比如“检查任务是否完成”这种判断本身就不可靠。第三多 Agent 协作时的责任推诿。当多个 Agent 串联工作时上游说交给了下游下游说没收到合格输入最后没人对最终结果负责。适合读这篇内容的人我大致分三类。一类是正在做 Agent 项目落地的工程团队尤其是承接央国企数字化项目的技术负责人一类是 Agent 框架的开发者想了解长任务验收机制的设计思路还有一类是技术管理者需要判断一个 Agent 方案到底能不能上生产。不管你是哪一类接下来我会把 MateClaw 2.3.0 这套验收锁机制的来龙去脉、实操细节和踩坑经验全部摊开讲。2. MateClaw 2.3.0 验收锁的整体设计思路拆解2.1 为什么是 JSON 而不是数据库或消息队列第一次看到“不可变 JSON 验收锁”这个设计时我的反应是为什么不用数据库记录任务状态为什么不用消息队列做验收通知非要搞一个 JSON 文件后来跟 MateClaw 的核心开发者聊过之后才明白这个选择背后有非常现实的考量。央国企的项目环境有一个特点部署环境高度受限但审计要求极高。很多项目现场不允许 Agent 服务直连外部数据库也不允许引入额外的中间件。JSON 文件是唯一一种既能结构化表达、又能被人工直接审阅、还能纳入版本管理系统的格式。具体来说JSON 验收锁的设计遵循了四条原则。写入即冻结验收 JSON 一旦由 Agent 写入指定路径文件权限立即变为只读后续任何步骤尝试修改都会触发异常并记录审计日志。结构可校验JSON 的 schema 是预定义的每个字段都有明确的类型和必填约束验收方可以用标准 JSON Schema 工具做机器校验。内容可追溯每个验收 JSON 都包含任务 ID、执行 Agent 标识、时间戳、步骤清单和交付物哈希值形成完整的证据链。人工可读即使没有验收工具业务方用任何文本编辑器打开 JSON 也能看懂任务到底完成了什么。这四条原则里我认为最关键的是“写入即冻结”。很多 Agent 框架也有任务状态记录但状态是可以被后续步骤覆盖的。比如某个步骤先写了“完成”后面发现有问题又改成“未完成”这种可变状态在审计场景下毫无意义。MateClaw 的做法是验收 JSON 只写一次写完就锁死要修正只能新建一个带版本号的验收文件旧文件永久保留。2.2 验收锁在 Agent 架构中的位置要理解验收锁的作用得先看清楚它在整个 Agent 执行链路中处于什么位置。MateClaw 的架构大致分为四层任务规划层、步骤执行层、验收锁层和审计输出层。任务规划层负责把用户的长任务拆解成有序步骤列表每个步骤都有明确的输入输出定义。步骤执行层负责实际调用工具、模型或子 Agent 来完成每个步骤。验收锁层是 2.3.0 新增的它不参与任务执行只在每个关键步骤完成后和整个任务结束时进行验收写入。审计输出层负责把验收 JSON 汇总成可读的审计报告。这个分层设计的好处是验收逻辑与执行逻辑彻底解耦。以前很多 Agent 框架把验收判断写在执行代码里导致执行 Agent 既当运动员又当裁判员。现在验收锁层是独立的执行 Agent 只能往验收 JSON 里写结果不能修改验收规则本身。我画不出图但你可以这样理解执行 Agent 就像工地上的施工队验收锁层就像监理单位。施工队说这面墙砌好了监理单位拿着验收单逐项检查检查通过就在验收单上签字并归档施工队拿不到签字就不能进入下一道工序。这个类比虽然简化了技术细节但核心逻辑是一致的。2.3 不可变性的技术实现路径“不可变”这个词说起来简单实现起来有好几种路径每种都有不同的适用场景。MateClaw 2.3.0 采用的是文件系统级不可变 内容哈希锚定的组合方案。文件系统级不可变是指验收 JSON 写入完成后通过设置文件属性为只读并在 Agent 运行时环境中禁用对该路径的写权限。这样即使 Agent 后续步骤想修改文件操作系统层面就会直接拒绝。内容哈希锚定是指验收 JSON 的内容会计算一个 SHA-256 哈希值这个哈希值会被写入任务主日志。任何对验收 JSON 的篡改都会导致哈希值不匹配审计时一查便知。注意文件系统级不可变在不同操作系统上的表现有差异。Linux 环境下可以用 chattr i 实现真正的不可变Windows 环境下只读属性可以被有权限的进程修改。如果项目部署在 Windows 环境建议额外启用内容哈希校验作为兜底。除了这两种还有一种更严格的方案是写入区块链或分布式账本但央国企内网环境通常不具备这个条件所以 MateClaw 没有采用。还有一种方案是写入只读对象存储但对象存储的写入延迟较高不适合高频验收场景。综合下来文件系统级不可变加哈希锚定是当前环境下最平衡的选择。3. 验收 JSON 的结构设计与字段详解3.1 核心字段清单与含义验收 JSON 的结构设计直接决定了验收锁能不能真正锁住。MateClaw 2.3.0 的验收 JSON 包含以下核心字段我逐个解释它们的用途和填写要求。字段名类型必填说明task_idstring是任务唯一标识由任务规划层生成全局唯一agent_idstring是执行该任务的 Agent 标识多 Agent 场景下用于区分step_indexinteger是当前验收对应的步骤序号从 1 开始step_namestring是步骤名称与任务规划层的步骤定义一致statusstring是验收状态枚举值completed、partial、faileddeliverablesarray是交付物列表每个元素包含路径、类型和哈希值acceptance_criteriaarray是验收标准列表逐条对应任务规划时的要求timestampstring是ISO 8601 格式的时间戳精确到毫秒previous_hashstring否上一步验收 JSON 的哈希值用于链式校验signaturestring否Agent 签名用于验证验收 JSON 的来源这张表里的字段看起来不多但每个字段的设计都有讲究。比如 status 字段只有三个枚举值没有“进行中”这个状态。为什么因为验收锁只在步骤完成后写入进行中的状态由执行层自己维护不进入验收锁。这样设计的好处是验收 JSON 永远只记录确定的结果不会出现“写了一半”的中间态。deliverables 字段是一个数组每个元素包含三个子字段path 表示交付物路径type 表示交付物类型如 file、url、texthash 表示交付物内容的哈希值。这个设计让验收方不仅能知道 Agent 声称完成了什么还能实际去核对交付物是否存在、内容是否匹配。3.2 验收标准如何与任务规划对齐验收 JSON 里的 acceptance_criteria 字段是最容易被忽视、也最容易出问题的部分。很多团队在任务规划阶段只写了任务目标没有写验收标准导致验收锁写入时 acceptance_criteria 是空的验收锁形同虚设。MateClaw 的做法是任务规划层在拆解步骤时必须为每个步骤定义至少一条验收标准。验收标准是一个结构化对象包含 criterion_id、description、check_method 和 expected_value 四个字段。check_method 支持三种类型exact_match精确匹配、contains包含匹配和 custom_script自定义脚本校验。我举个例子。假设一个长任务是“从多个数据源采集数据并生成汇总报告”其中一个步骤是“采集数据源 A 的数据”。这个步骤的验收标准可以这样定义{ criterion_id: step_3_criterion_1, description: 数据源 A 的采集记录数不少于 1000 条, check_method: custom_script, expected_value: record_count 1000 }这样定义之后验收锁写入时就必须附带实际采集到的记录数验收方用 custom_script 一跑就知道是否达标。如果 Agent 声称完成了但实际只采集了 500 条验收直接失败任务不会进入下一步。实操心得验收标准的定义最好由业务方和技术方共同确认不要由 Agent 自动生成。我见过太多项目让模型自动生成验收标准结果标准要么太宽松“数据已采集”要么太苛刻“数据零误差”都不具备可操作性。3.3 哈希链如何防止验收结果被篡改哈希链是验收锁不可变性的核心技术保障。每个验收 JSON 都包含 previous_hash 字段指向同一个任务中上一步验收 JSON 的哈希值。这样所有步骤的验收 JSON 就形成了一条链任何一步被篡改后续所有步骤的哈希值都会对不上。具体计算方式是对验收 JSON 的内容排除 signature 字段做规范化序列化然后计算 SHA-256 哈希。规范化序列化是指按照字段名字典序排序、去除多余空白、统一编码格式。这样即使 JSON 文件的格式有细微差异只要内容一致哈希值就一致。哈希链的校验流程是这样的验收方从任务主日志中获取最终验收 JSON 的哈希值然后反向逐级校验每个验收 JSON 的 previous_hash 是否与前一步的实际哈希值匹配。如果全部匹配说明验收链完整可信如果某一级不匹配说明该级之后的验收结果都不可信。这个机制在央国企审计场景下特别有价值。审计人员不需要理解 Agent 的内部逻辑只需要验证哈希链是否完整就能判断任务验收过程是否被篡改。这比人工翻阅日志效率高得多也比单纯依赖 Agent 自报告可靠得多。4. 长任务验收锁的实操流程与关键环节4.1 任务规划阶段的验收标准预埋验收锁能不能发挥作用很大程度上在任务规划阶段就决定了。如果规划阶段没有预埋验收标准执行阶段就没有东西可锁。MateClaw 2.3.0 要求任务规划层在生成步骤列表时同步生成每个步骤的验收标准模板。具体操作上任务规划层会输出一个任务定义 JSON结构如下{ task_id: task_20260115_001, task_name: 多源数据采集与汇总报告生成, steps: [ { step_index: 1, step_name: 数据源A采集, acceptance_criteria: [ { criterion_id: step_1_criterion_1, description: 采集记录数不少于1000条, check_method: custom_script, expected_value: record_count 1000 } ] }, { step_index: 2, step_name: 数据源B采集, acceptance_criteria: [ { criterion_id: step_2_criterion_1, description: 采集记录数不少于500条, check_method: custom_script, expected_value: record_count 500 } ] } ] }这个任务定义 JSON 会在任务启动时写入任务主日志作为后续验收的基准。执行 Agent 不能修改这个文件只能按照它来执行和验收。我踩过的一个坑是任务规划阶段定义的验收标准太粗比如只写了“数据采集完成”没有写具体数量要求。结果执行 Agent 采集了 10 条数据也声称完成验收锁虽然写入了但验收标准本身没有约束力。后来我们强制要求每条验收标准必须包含可量化的 expected_value这个问题才解决。4.2 执行阶段的验收锁写入时机验收锁的写入时机非常关键。写早了步骤还没真正完成写晚了执行 Agent 可能已经进入下一步验收锁失去意义。MateClaw 2.3.0 的规则是每个步骤的所有验收标准都通过校验后立即写入验收锁写入完成后才能进入下一步。这个规则在执行层的实现方式是每个步骤执行完毕后执行 Agent 先不直接进入下一步而是调用验收锁写入接口。写入接口会做三件事第一检查该步骤的所有验收标准是否都有对应的校验结果第二校验结果是否全部通过第三如果全部通过生成验收 JSON 并写入指定路径同时设置文件为只读。如果任何一条验收标准未通过写入接口会返回失败并附带未通过的验收标准列表。执行 Agent 收到失败后可以选择重试该步骤、调整执行策略或上报人工介入。但无论如何不能跳过验收锁直接进入下一步。注意验收锁写入接口本身也要做权限控制。只有经过认证的执行 Agent 才能调用写入接口且每个 Agent 只能写入自己负责步骤的验收 JSON。这样可以防止某个 Agent 越权写入其他步骤的验收结果。4.3 验收锁的读取与校验操作验收锁写入后验收方需要读取并校验。MateClaw 提供了命令行工具和 API 两种方式。命令行工具适合人工抽查API 适合集成到自动化验收流水线。命令行工具的基本用法是mateclaw verify --task-id task_20260115_001 --step 3 --verbose这个命令会读取任务 ID 为 task_20260115_001 的第 3 步验收 JSON逐项校验验收标准并输出校验报告。如果加上 --verbose 参数还会输出每个验收标准的详细校验过程。API 方式适合批量校验。验收方可以调用/api/v1/acceptance/verify接口传入任务 ID 和步骤范围接口会返回所有步骤的校验结果汇总。如果任何一步校验失败接口会返回失败详情和失败原因。校验过程中有一个细节需要注意验收 JSON 的哈希校验和验收标准校验是分开的。哈希校验确认验收 JSON 本身没有被篡改验收标准校验确认 Agent 声称的完成结果是否真实达标。两者都通过才算验收成功。我见过有的团队只做了哈希校验没有做验收标准校验结果 Agent 写入了格式正确但内容不达标的验收 JSON验收方却以为通过了。4.4 多 Agent 协作场景下的验收链管理央国企的长任务往往不是单个 Agent 能完成的需要多个 Agent 协作。比如一个数据治理任务可能由采集 Agent、清洗 Agent、分析 Agent 和报告 Agent 串联完成。这种情况下验收链的管理就变得复杂。MateClaw 2.3.0 的处理方式是每个 Agent 负责的步骤都有独立的验收 JSON但这些验收 JSON 通过 previous_hash 字段串联成一条完整的链。采集 Agent 的验收 JSON 是链的起点报告 Agent 的验收 JSON 是链的终点。任何一个环节的验收失败都会导致后续环节无法写入验收锁。这种设计的好处是责任清晰。如果最终报告有问题验收方可以沿着验收链反向排查快速定位是哪个 Agent 的哪个步骤出了问题。比如报告 Agent 的验收 JSON 显示它正确汇总了分析 Agent 的输出但分析 Agent 的验收 JSON 显示它接收到的清洗数据不完整那问题就出在清洗 Agent 或采集 Agent 身上。多 Agent 场景下还有一个坑Agent 之间的交接标准要统一。如果采集 Agent 定义的“完成”是采集到 1000 条原始数据而清洗 Agent 定义的“合格输入”是 1000 条去重后的数据两者对不上验收链就会断裂。我们的做法是在任务规划阶段就定义好每个步骤的输出格式和数量要求所有 Agent 都按照这个标准执行。5. 常见问题排查与避坑经验实录5.1 验收锁写入失败的高频原因在实际操作中验收锁写入失败是最常见的问题。我整理了一份排查速查表覆盖了大部分场景。问题现象可能原因排查方法解决方案写入返回权限错误验收目录权限不足检查 Agent 运行账户对验收目录的写权限调整目录权限或更换运行账户写入返回文件已存在同一步骤重复写入检查任务是否被重复触发清理重复任务或增加任务去重逻辑写入返回哈希不匹配previous_hash 字段错误核对上一步验收 JSON 的实际哈希值修正 previous_hash 生成逻辑写入返回验收标准未通过实际结果不达标查看未通过的验收标准详情重试步骤或调整执行策略写入超时验收目录所在磁盘满或IO瓶颈检查磁盘空间和IO负载清理磁盘或更换存储路径这张表里我认为最需要重视的是“验收标准未通过”。很多团队遇到这个问题时第一反应是修改验收标准让它通过这是绝对错误的做法。验收标准是任务规划阶段确定的执行阶段不能修改。正确的做法是让 Agent 重试步骤或者上报人工介入判断是标准不合理还是执行有问题。5.2 验收标准定义过严或过松的平衡技巧验收标准定义过严Agent 永远无法通过任务卡死定义过松验收锁形同虚设。这个平衡怎么把握我的经验是遵循“三可原则”可量化、可复现、可协商。可量化是指验收标准必须有明确的数值或布尔判断不能是“质量良好”这种主观描述。可复现是指任何人按照验收标准去校验都能得到相同的结果。可协商是指验收标准在任务规划阶段可以由业务方和技术方协商调整但一旦任务启动就不能再改。具体操作上我建议对每个步骤的验收标准做一次“反向测试”假设 Agent 只完成了最低限度的工作能不能通过这条验收标准如果能通过说明标准太松假设 Agent 完美完成了工作但因为某个无关紧要的细节不达标能不能通过如果不能通过说明标准太严。举个例子。一个“生成汇总报告”的步骤验收标准如果写“报告文件存在”那太松了Agent 生成一个空文件也能通过。如果写“报告文件包含所有 20 个字段且每个字段精确到小数点后 4 位”那可能太严了因为业务方实际只需要小数点后 2 位。合理的标准是“报告文件包含所有 20 个字段数值字段精确到小数点后 2 位且总行数不少于 100 行”。5.3 验收锁与人工复核的衔接方式验收锁再严格也不能完全替代人工复核。央国企的项目尤其如此很多交付物需要业务专家做最终判断。MateClaw 2.3.0 的设计是验收锁负责机器可校验的部分人工复核负责机器难以校验的部分。具体衔接方式是验收锁写入后如果所有机器校验都通过任务进入“待人工复核”状态。人工复核人员通过验收工具查看验收 JSON 和交付物确认无误后签署人工复核意见。人工复核意见也会写入一个独立的 JSON 文件与验收锁关联但不修改验收锁。这种设计的好处是机器验收和人工复核各司其职互不干扰。机器验收保证了基本质量底线人工复核处理了复杂判断。而且人工复核意见也是结构化的可以纳入审计链。实操心得人工复核环节最容易出的问题是复核人员直接点“通过”而不实际查看交付物。我们的做法是在验收工具里强制要求复核人员对每个交付物做一次“打开并确认”操作操作记录会写入复核日志。虽然增加了操作步骤但显著降低了漏检率。5.4 验收锁对 Agent 性能的影响评估引入验收锁后Agent 的执行链路变长了性能肯定会有影响。具体影响有多大我在一个测试环境中做了对比。测试任务是 50 个步骤的数据处理任务分别在启用验收锁和未启用验收锁的情况下运行 10 次。未启用验收锁时平均执行时间是 12 分 30 秒启用验收锁后平均执行时间是 13 分 45 秒。性能开销大约是 10%。这 10% 的开销主要来自三个方面验收 JSON 的生成和写入、哈希计算、文件权限设置。其中哈希计算占了大头因为每个步骤的验收 JSON 都要计算 SHA-256。如果任务步骤特别多比如超过 100 步哈希计算的开销会更明显。优化建议是对于步骤数超过 50 的长任务可以考虑对验收 JSON 做批量哈希计算而不是每步单独计算。MateClaw 2.3.0 已经内置了这个优化但需要手动开启。开启方式是在任务配置中设置batch_hash: true。另外验收锁的写入路径最好放在本地 SSD 上不要放在网络存储上。网络存储的写入延迟可能是本地 SSD 的 10 倍以上会显著拖慢验收锁写入速度。如果必须用网络存储建议增加写入超时时间并启用异步写入模式。6. 从验收锁延伸出去的长任务治理思路验收锁解决的是“任务完成确认”这一个环节的问题但长任务的治理远不止这一个环节。我在多个项目中总结下来长任务要真正跑稳至少还需要在三个地方下功夫。第一个是任务状态的可视化。验收锁只记录完成状态不记录进行状态。如果任务卡在某个步骤验收方只能看到“未完成”看不到卡在哪里。MateClaw 2.3.0 配套了一个任务状态面板实时展示每个步骤的执行状态、耗时和重试次数。这个面板的数据来自执行层与验收锁互补。第二个是异常重试的策略化。验收锁写入失败后Agent 需要重试。但重试不能是无脑重试要有策略。我们的做法是对于验收标准未通过的情况最多重试 3 次每次重试调整执行参数对于权限或IO错误立即停止并上报不重试。重试策略也写入任务定义 JSON执行 Agent 必须遵守。第三个是验收数据的长期归档。验收锁 JSON 和人工复核意见都是重要的审计资料需要长期保存。央国企的审计要求通常是保存 5 年以上。我们的做法是验收锁写入后自动同步到归档存储归档存储采用只读模式任何修改都需要审批。归档时保留完整的哈希链确保多年后仍可校验。最后分享一个我在实际项目中总结的小技巧验收锁的 JSON 文件命名最好包含任务 ID、步骤序号和时间戳比如task_20260115_001_step_003_20260115T143022.json。这样即使文件被移动到其他目录也能通过文件名快速识别归属。而且按文件名排序就是按时间排序人工翻阅时非常方便。这个细节看起来不起眼但在审计场景下能省不少事。