企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 工作流
• Agent 编排
• RAG
• 工具调用
• 后端
• 前端

MateClaw 的持久目标（Persistent Goal）能力，让一个跨越数小时甚至更久的长任务在服务重启、网络抖动或模型调用失败后，依然能靠数据库检查点（Checkpoint）自动恢复并续跑，而不必从头再来。本文用尽量少的代码，讲清这套机制的完整原理：续跑调度、租约心跳、检查点写入、以及重启后的恢复决策四步是如何协作的。

MateClaw 控制台概览

🎯 一、持久目标解决什么问题？

普通的对话式 Agent 有一个天然短板：一次会话只能跑一段有限的工作。任务太大时，模型会在迭代次数用尽后停下，等待用户再发一条消息。

MateClaw 的持久目标机制（源码位于 goal 模块）改变了这一点：

• 跨轮次续跑：目标（Goal）创建后保持active状态，系统会自动注入"跟进指令"，让 Agent 一段一段（Segment）继续推进，直到验收标准（Criteria）全部满足才进入completed。
• 状态机清晰：目标生命周期为create → active ↔ paused → completed / abandoned / exhausted，定义见 GoalStatus.java。
• 有预算护栏：默认turn_budget=20、llm_call_budget=200，防止失控消耗，见 GoalProperties.java。

但"跨小时"运行意味着一件事几乎必然发生：执行途中服务会重启、进程会崩溃、模型调用会失败。长任务如何不丢进度？答案就是下面这套检查点 + 恢复体系。

🧩 二、四个核心角色：谁负责续跑与恢复

持久目标子系统由四个组件协作完成，全部位于 goal/service：

它们各自落库两张核心表：mate_goal_continuation（目标的调度状态）与mate_goal_attempt（单次执行的检查点快照），分别由 GoalContinuationStore.java 与GoalAttemptStore维护。

⏱️ 三、租约（Lease）：长任务防"重复执行"的钥匙

跨小时的任务无法依赖"进程还活着"来保证安全，MateClaw 用的是带超时的租约：

1. 认领：协调器为每次执行生成一个唯一的leaseToken，租期默认60 秒（LEASE_SECONDS=60，见 GoalRunCoordinator.java），写入数据库即视为"认领成功"。
2. 心跳续租：执行期间，监督者每 5 秒 tick 一次（GoalContinuationSupervisor.java），调用renew把租约再续 60 秒。
3. 过期判定：一旦进程崩溃，心跳停止，租约最多 60 秒后过期——恢复服务随后扫描"租约已过期但仍处于 running 状态"的执行，将其安全接管。

所有对数据库的写入都必须携带正确的 leaseToken（即"fenced write"），旧的、已经失效的执行即使残留在内存里，也无法再修改数据，从根本上避免了"两个执行同时续跑同一个目标"的问题。

📸 四、检查点在哪里写？一次执行的完整旅程

真正干活的是 GoalSegmentRunner.java。它把 Agent 的流式输出过程中的关键事件实时固化为检查点，写入mate_goal_attempt表（写入口见 GoalAttemptStore.checkpoint）：

对应代码在流式回调中按事件打点：收到tool_call_started写uncertain/tool_started，收到tool_call_completed写resolved/tool_completed，消息保存后写resolved/message_saved并记录消息 ID（GoalSegmentRunner.java）。

这意味着：任务的每一步进展都不只存在于内存和对话流里，而是持续同步进了数据库——这是"自动恢复续跑"能够成立的物理基础。

🚑 五、重启之后：恢复决策是怎么做的？

服务重启（或租约过期）后，恢复服务扫描过期执行并逐一"分类"。核心逻辑只有短短几行，见 GoalRecoveryService.classify：

if replaySafety == "uncertain" → 阻塞，转人工审查 else if checkpointType == "message_saved" → 对账已保存消息，然后继续 else if checkpointType == "tool_completed" → 凭已有证据从断点续跑 else → 安全重试，从头重跑本段

四种恢复决策一览（定义见 GoalRecoveryService.java）：

• ✅RETRY_SAFE：停在provider_started，尚未产生副作用，直接重跑本段即可；
• 🔁RESUME_FROM_EVIDENCE：停在tool_completed，工具结果已确定，凭落库证据继续，不重复执行工具；
• 📎RECONCILE_MESSAGE：停在message_saved，回复已入库，恢复时只做消息对账，避免重复回复；
• ⛔BLOCK_UNCERTAIN_SIDE_EFFECT：停在tool_started且结果未知（比如"转账"工具执行到一半服务挂了）。此时自动暂停目标并标记为blocked，等待人工确认副作用是否发生——宁可停住，也不冒险重复执行。

这正是"检查点恢复"里最关键的设计：恢复不是无脑重放，而是依据检查点携带的安全级别做差异化处理。恢复完成后，执行记录被标记为retryable或blocked（recoverExpired 流程），下一轮监督者 tick 会把它当作到期任务重新认领，任务就此无缝续上。

🔍 六、动手验证：查看你的持久目标与执行证据

机制讲完，你可以从界面与 API 两个角度观察它：

界面层：在 Agents 页面的目标面板中，每个目标卡片都会显示完成度、验收清单与运行证据，组件为 GoalsPanel.vue；其中的"执行证据"列表 ExecutionEvidenceList.vue 展示目标推进过程中沉淀的每一步证据。

API 层：GoalExecutionController.java 提供两个只读接口：

• GET /api/v1/goals/{id}/execution— 目标的调度状态（queued / running / retry、失败次数、原因等）；
• GET /api/v1/goals/{id}/execution/attempts— 最近 50 次执行的明细，含checkpointType、replaySafety、finishReason，可以直接看到每次断点停在了哪一步。

⚙️ 七、值得了解的配置项

所有配置集中在mateclaw.goal.*前缀下（GoalProperties.java）：

💡实践建议：把需要跨小时运行的任务（批量数据处理、长文档生产、多阶段调研）显式创建为持久目标并开启自动跟进；同时保留allow-auto-followup作为应急总闸，出现异常时一键冻结所有自主续跑。

📌 小结

MateClaw 的跨小时长任务可靠性，来自一套环环相扣的设计：

1. 持久化调度：目标状态与调度队列全部落库，重启不丢失；
2. 租约 + 心跳：60 秒租约配合 5 秒 tick，既防重复执行，又能及时发现"失联"的执行；
3. 流式检查点：工具开始/完成、消息落库等关键事件实时写入检查点，并标注重放安全性；
4. 差异化恢复：重启后按检查点类型四选一——安全重试、凭证据续跑、消息对账、或暂停待人工审查。

这套"检查点 + 租约 + 恢复分类"的组合，让 MateClaw 的长任务在真实运维环境里做到了中断不丢进度、恢复不出错。

相关模块路径速查：

• 持久目标核心源码：goal 模块
• 恢复决策：GoalRecoveryService.java
• 目标配置：GoalProperties.java
• 前端目标面板：GoalsPanel.vue

• 人工智能
• AI Agent
• Agent 工作流
• Agent 编排
• RAG
• 工具调用
• 后端
• 前端