企业官网建设流程全解析

长任务最危险的失败，不是报错。

而是 Agent 很顺利地跑完十几轮，留下一个语气笃定的“任务已完成”，随后你才发现：导出的 JSON 少了字段，文件在最后一次修改后没有重新检查，审批恢复到了错误的目标，或者某次服务重启让旧证据被当成了新证据。

这些问题有一个共同点：系统把“完成”当成模型判断，而不是服务端状态。

MateClaw 2.2.0 已经让 Persistent Goal 能跨请求、跨有界执行片段和后端重启继续运行。2.3.0 继续往完成语义里钻了一层：用户定义验收要求，Agent 发布不可变 JSON 产物，服务端对指定版本执行检查，再把检查结果绑定到当前要求。

要求变了、产物换代了、版本过期了、权限失效了，旧绑定立即失效。Agent 不能靠一句 PASS 绕过去。

从v2.2.0到v2.3.0，仓库差异涉及 574 个文件，新增约 2.8 万行。大量改动不在首页功能，而在事务边界、租约、身份恢复、符号链接、SSE 分帧和回放测试里。这很符合 2.3.0 的气质：少讲“智能”，多修“凭什么算完成”。

图 1：2.3.0 沿着“验收、证据、恢复、干预、技能资产”五条链路加固长任务运行时。

一、Agent 的“我完成了”，为什么不够

一个常见的长任务流程是：

用户给目标 ↓ Agent 调工具、写文件、跑检查 ↓ 模型总结执行过程 ↓ 模型判断：完成

问题出在最后一步。

模型看到的上下文可能被压缩，工具结果可能只是摘要，文件可能在检查后又被改写，当前验收标准也可能已经被用户更新。即使模型没有幻觉，它基于的也可能是过期快照。

2.3.0 把这条链改成：

用户配置当前要求 ↓ Agent 读取槽位与 generation ↓ Agent 发布严格 JSON → 生成不可变版本 ↓ 服务端从存储字节执行字段检查 ↓ 检查结果绑定到：要求修订 + artifactId + generation ↓ 共享完成入口重新校验所有当前绑定

图 2：验收不是 Agent 自报结果，而是服务端针对不可变版本生成可失效的绑定。

这不是给 prompt 再加一句“请认真检查”。它改变了完成判定的数据结构。

二、托管 JSON 验收：把完成权移到服务端

用户可以在目标面板配置 JSON 验收要求：要求键、产物槽位，以及必须存在的顶层字段。配置入口属于用户，Agent 工具不能替用户修改验收标准。

假设一份研究任务最终需要发布如下产物：

{"summary":"市场结论","items":[{"name":"项目 A","score":87}],"sources":["https://example.com/source"]}

用户可以要求summary、items、sources三个字段必须存在且非null。运行时协议分三步：

1. Agent 调用getManagedGoalJsonSlots，读取当前要求、槽位和 generation；
2. 调用publishManagedGoalJson，向指定槽位发布严格 JSON 对象；
3. 调用checkManagedGoalJson，提交当前要求修订、产物 ID 和 generation。

检查由服务端读取实际存储字节完成，不接受调用方直接传入 PASS。工作空间里的某个文件路径，也不能冒充托管发布版本。

一条有效绑定至少回答四个问题：

• 检查的是哪条当前要求？
• 对应哪个不可变产物？
• 检查的是该槽位的哪一代？
• 检查时的目标定义和授权状态是否仍然有效？

所有当前要求都有有效绑定，并且原有 Goal checklist 也全部通过、有非空证据时，目标才能完成。

绑定为什么必须失效

下面任一事件发生，旧检查都不能继续充当完成凭据：

• 用户修改验收要求；
• Goal 定义发生修订；
• 槽位发布了新 generation；
• 产物版本超过有效期；
• 正文完整性检查失败；
• 当前运行所有者或账户权限不再匹配。

换句话说，2.3.0 保存的不是一张永久通行证，而是一条带条件的验收引用。

绑定与 Goal version 在同一事务里更新。事务失败，不留下半张“通过凭据”；完成事务回滚，也不会提前发布完成事件或写入完成记忆。

这类细节看起来啰嗦，却正是长任务在重启、并发与审批恢复下不自相矛盾的基础。

三、这不是完整 JSON Schema，更不是业务正确性证明

2.3.0 的托管 JSON 验收刻意收窄了范围。

当前 recipe 只检查用户指定的顶层字段是否存在且非null：

• 每条要求可配置 1—16 个不同字段；
• 每个字段名长度为 1—128 个字符；
• 每个版本最多 1 MiB UTF-8；
• 每个 Goal 最多保存 32 个版本；
• 版本有效期为 24 小时。

它不检查完整 JSON Schema，不验证字段类型，也不判断业务内容是否正确。

例如sources字段存在但内容是空数组，字段存在性检查可能通过；某个评分是 87 还是 8.7，也不是当前 recipe 的职责。

这种边界不是能力不足的遮掩，反而让契约更清楚：

2.3.0 解决“产物结构是否具备用户要求的最小形状”，不假装解决任意业务验收。

如果业务需要类型、范围、签名或领域规则，应在外部校验器、专用 Tool 或后续验收 recipe 中实现，而不是把所有正确性都塞给模型判断。

还有一个容易误读的字段：acceptanceEligible=true只表示这一条要求在当前条件下可作为验收绑定，不代表整个 Goal 已经完成。

四、执行证据先做账本，不急着做万能门禁

2.3.0 新增持久执行证据，记录执行 attempt 与产物信息，并支持：

• 按需检查产物版本变化；
• 有界 JSON 产物诊断；
• 离线回放评估；
• 在 UI 中查看执行证据。

默认配置是：

mateclaw.execution-evidence.mode=observe

当前支持observe和off。如果配置enforce，启动时会明确拒绝。

图 3：Execution Evidence 负责记录与诊断；Managed JSON Acceptance 才进入完成判定。两条链不能混用。

这条边界值得单独说。普通产物诊断的结果是acceptanceEligible=false，不能替代托管 JSON 绑定。观察模式先解决“发生了什么、检查了什么、产物是否变化”，并没有假装所有工具和文件都已经进入统一强制验收域。

执行证据的落库也做了几项底层收口：

• observation 状态与行记录原子写入；
• 后续命令观察不会覆盖已经记录的失败；
• 权限撤销后清除已列出的证据内容；
• 生成文件读取先检查所有权；
• 下载、重载和产物收集拒绝符号链接；
• HTML 等预览内容使用沙箱策略隔离。

比起“我们有审计日志”，这些约束更能说明账本是否可信。

五、审批和排队输入恢复：连“是谁点的”也要持久化

长任务恢复不只需要保存 Goal ID。

审批可能跨后端重启，用户输入可能在 Agent 忙碌时排队，账号可能被禁用或用户名被重新使用。如果恢复时只记住“有一个用户批准过”，身份边界就会漂移。

2.3.0 在审批、延迟输入和恢复路径中保留：

• 选中的 Goal；
• 请求者内部账户身份；
• continuation、attempt 与 owner token；
• 当前有效租约；
• 对话、工作空间与 Agent 归属。

恢复前重新检查账户和权限。终态 Goal 不会因为队列里还有一条旧输入就被自动复活；已经结算的审批也不能重新夺回运行所有权。

图 4：重启后恢复的是带身份、租约和所有权约束的 continuation，而不是一条裸消息。

这部分没有炫目的 UI，但它修的是典型的分布式状态机问题：恢复的不只是数据，还必须恢复当时有效的授权上下文。

六、Team Run 终于能在中途“扶一把”

2.3.0 为团队 worker 增加受控干预。

当成员停在工具审批时，用户可以在 Team Run 详情中批准或拒绝；需要补充信息时，可以发送最长 4000 字符的反馈。

但它不是向运行中的 worker 随意插话：

• 有待处理审批时，必须先处理审批；
• 任务、运行、成员会话和权限归属会被重新校验；
• worker 必须处于空闲状态；
• 新一轮执行必须先取得会话执行许可；
• 获批工具回放失败且外部副作用不确定时，任务停靠等待复核。

最后一条尤其重要。再次点击批准，不等于允许系统盲目重放一次可能已经扣款、发送或写入外部系统的操作。

图 5：干预先过归属、权限、空闲与会话许可门禁；副作用状态不确定时停靠复核。

同时，异步委派加入执行时限与取消传播。长任务可以被干预，但不会因此绕开原有租约和副作用边界。

七、Skill 文件夹上传：终于不用一个文件一个文件点

技能文件管理现在支持上传文档和整个文件夹，目标位置包括：

• references/
• templates/
• scripts/

选择文件夹时会保留相对目录结构，例如：

references/ └── manual/ ├── chapter-01.pdf └── images/ └── architecture.png

上传限制是明确的：

• 服务端单文件最大 10 MiB；
• 前端单批最多 100 个文件；
• 单批合计最多 50 MiB；
• 文本以 UTF-8 保存；
• 二进制以 Base64 编码入库，同步到技能工作目录时恢复为原始字节；
• 路径穿越、非法分隔符、重复目标与超长路径会被拒绝；
• 上传需要工作空间管理员权限，内置技能文件只读；
• 覆盖已有路径前必须确认。

上传成功只代表附件进入技能资产，不代表文件已经被读取、执行或验证。这也是一个很“2.3”的边界：存进去，不等于用过；用过，也不等于验收过。

八、那些决定线上体验的修复

2.3.0 还有一批不适合写成大标题，却会直接影响生产运行的改动。

DeepSeek Harness

• 受管 Runtime 配置可以持久保存；
• 会话历史按有界窗口恢复；
• 输出 token 上限传给 SDK，避免只在宿主侧写了预算、外部循环却不知道。

推理模型与流式响应

• 推理模型探测和参数错误处理更稳；
• vLLM 的 reasoning 内容不再丢失，并遵循思考开关；
• SSE 同时兼容LF与CRLF行结束符；
• 代理缓冲被关闭，减少“后端在流，前端半天不动”的假卡死；
• 高频文本 delta 合并，降低渲染和网络开销；
  -停止回退后，聊天 UI 能正确收束状态。

Cron、工具与记忆

• Cron 长任务持久化心跳，投递状态迁移有条件守卫；
• 图执行错误不再被错误标记为成功；
• 关闭时取消尚未启动的延迟任务；
• 电子表格提取规模有上限，工具调用落实统一截止时间；
• 长期记忆召回按所有者隔离，临时约束不会被写成长期偏好；
• 被截断的上下文摘要直接拒绝；
• 前端增加可移植的 Snowflake ID 精度检查器。

这些改动没有改变产品口号，却减少了一类最难排查的问题：每层看起来都没报错，最后状态却悄悄错了。

关键源码落点

想直接看实现，可以从这几处开始：

• ManagedGoalJsonTool.java：Agent 侧读取槽位、发布版本和发起检查的入口；
• GoalJsonAcceptanceService.java：用户要求、权限与托管验收服务；
• JsonArtifactRecipe.java：顶层字段检查的实际范围；
• ExecutionEvidenceRecorder.java：observe/off模式与enforce拒绝逻辑；
• TeamWorkerInterventionService.java：成员审批回放和反馈干预；
• SkillController.java：Skill 文件上传与路径边界。

九、升级前要知道什么

2.3.0 包含 V190—V202 数据库迁移，覆盖：

• Cron heartbeat；
• 执行证据账本；
• 记忆召回唯一身份；
• Goal evaluation revision；
• JSON requirements、artifacts、bindings；
• JSON 绝对过期时间与 owner lease；
• 排队输入账户身份和选定 Goal；
• 审批 attempt handoff；
• Skill 文件编码。

支持 H2、MySQL 与 Kingbase/PostgreSQL 对应迁移路径。

升级建议：

1. 先备份数据库和工作空间文件；
2. 启动时确认 Flyway 已完整执行至 V202；
3. 重新核对已有持久 Goal 的验收要求与待处理审批；
4. 如果使用代理或网关，检查 SSE 是否关闭缓冲；
5. 不要把 observe evidence 当成强制验收；
6. 不要把顶层字段检查写成“完整业务正确性验证”。

十、快速开始

gitclone https://github.com/mateaix/mateclaw.gitcdmateclawcp.env.example .envdockercompose up-d

启动后访问http://localhost:18080。

默认账号为admin，默认密码为admin123。正式部署前请修改默认凭据，并根据环境设置模型、工作空间、工具权限与持久目标预算。

MateClaw 采用 Apache License 2.0 开源，支持自托管。

写在最后

Agent 系统最容易演示的是“会不会做”。最难工程化的是另外三件事：

• 做到哪一步，状态能不能恢复；
• 产物发生变化，旧证据会不会失效；
• 系统说完成时，能不能指出对应的要求和版本。

MateClaw 2.3.0 没有发明万能验收器。它先把一段明确、有限、能够做对的路径钉死：用户定义顶层字段要求，Agent 发布不可变 JSON 版本，服务端检查存储字节，完成入口验证当前绑定。

这条路径不华丽，但足够硬。

Agent 可以负责执行，完成权必须留在可验证的系统状态里。

央国企的太一智能体：https://mate.vip/enterprise/

• GitHub：https://github.com/mateaix/mateclaw
• v2.3.0 更新日志：https://claw.mate.vip/docs/zh/releases/2.3.0
• 持久目标文档：https://claw.mate.vip/docs/zh/goals
• 在线文档：https://claw.mate.vip/docs
• 在线演示：https://claw-demo.mate.vip