Agent Harness 长期运行架构设计文档

1. 设计概述

1.1 设计目标

设计一个可长期稳定运行的 Agent Harness（以下简称“Harness”），作为核心调度中枢，串联多个 Agent、AI 模型、CLI 工具，实现复杂工程任务的全流程自动化执行。核心解决“多智能体协同、任务可追溯、故障可恢复、结果可验证”四大痛点，支持从任务启动到复盘回滚的全生命周期管理，适配长期、高频、复杂的工程场景（如自动化部署、数据治理、模型训练流水线等）。

核心设计原则

• 松耦合架构：Harness 与 Agent、工具、模型解耦，支持动态注册、扩展，无需修改核心代码即可新增组件。
• 状态可持久化：全流程状态、中间结果、操作记录实时持久化，避免因重启、崩溃导致任务中断或数据丢失。
• 故障韧性：支持失败重试、降级执行、人工介入，确保任务在部分组件故障时仍能推进或优雅恢复。
• 可追溯性：每一步操作、决策、结果均留存证据，形成完整证据链，支持复盘、审计和回滚。
• 灵活可配置：任务流程、组件调度规则、审批逻辑、完成条件均可通过配置实现，无需硬编码。

2. 核心架构设计

Harness 采用“三层架构+多组件协同”模式，核心分为「调度层」「执行层」「存储层」，辅以「审批层」「审计层」「复盘层」，各层职责清晰、协同联动。整体架构如下：

2.1 架构总览图

2.2 各层核心职责

2.2.1 调度层（Supervisor）

Harness 的核心大脑，负责任务全生命周期的调度与管控，是整个系统的“决策中心”。

• 任务解析：接收用户提交的任务（含任务目标、多阶段流程、组件依赖、完成条件、审批规则等），解析为可执行的步骤序列。
• 节点分配：根据任务步骤的资源需求（CPU、内存、权限），将步骤分配给合适的 Worker Node 执行。
• 状态管控：实时监控每个步骤的执行状态（待执行、执行中、成功、失败、待审批），同步更新全局任务状态。
• 决策调度：根据步骤执行结果、状态变化，决定下一步操作（继续执行、重试、触发审批、终止任务、回滚）。
• 依赖管理：处理步骤间的依赖关系（串行、并行），确保前序步骤完成后再执行后续步骤。

2.2.2 执行层（Worker Node）

任务的“执行载体”，负责具体步骤的落地，调用各类 Agent、模型、CLI 工具，是系统的“执行手脚”。支持动态扩容，可根据任务量增减 Worker 节点。

• 组件调用：根据调度层分配的任务步骤，调用指定的 Agent、AI 模型、CLI 工具，传递输入参数，获取执行结果。
• 状态上报：实时将步骤执行状态（执行中、成功、失败）、中间结果、异常信息上报给调度层。
• 证据收集：收集步骤执行过程中的所有输出（日志、结果文件、截图、接口响应），上传至存储层，形成证据链。
• 本地缓存：临时缓存步骤执行的中间数据，减少重复计算，提升执行效率（缓存可配置过期时间）。
• 指令执行：执行调度层下发的重试、回滚、终止等指令。

2.2.3 存储层

负责全系统数据的持久化存储，确保数据不丢失、可追溯，是系统的“记忆中心”。采用多存储介质协同，适配不同数据类型的需求。

• 状态存储（Redis + MySQL）：Redis 存储实时任务状态、步骤状态、 Worker 节点状态（高并发读写）；MySQL 存储任务元数据、步骤详情、审批记录、复盘结果（持久化、可查询）。
• 证据存储（对象存储 MinIO/S3）：存储步骤执行过程中的证据文件（日志、结果文件、截图、模型输出等），支持按任务 ID、步骤 ID 分级归档，可下载、可预览。
• 日志存储（ElasticSearch）：存储系统操作日志、组件调用日志、异常日志，支持按时间、任务 ID、组件类型检索，用于问题排查、审计。

2.2.4 审批层（Reviewer）

负责人工介入审批，适用于高风险步骤（如删除数据、修改核心配置、部署生产环境），确保任务执行的安全性。

• 审批触发：当任务步骤配置了“人工审批”规则时，调度层触发审批流程，向指定 Reviewer 推送审批通知（邮件、钉钉、系统内消息）。
• 审批操作：Reviewer 查看步骤详情、前置证据，执行“通过”“驳回”“驳回并修改”操作，填写审批意见。
• 审批同步：审批结果实时同步给调度层，调度层根据审批结果决定下一步操作（通过则继续执行，驳回则终止或回滚）。

2.2.5 审计层

负责任务全流程的审计，确保操作合规、可追溯，生成审计报告，支撑复盘和合规检查。

• 日志采集：采集调度层、执行层、审批层的所有操作日志，关联任务 ID、步骤 ID、用户 ID。
• 证据校验：校验证据链的完整性（确保每个步骤都有对应的证据，证据未被篡改）。
• 审计报告：任务完成/终止后，自动生成审计报告，包含任务详情、执行过程、审批记录、证据清单、异常信息。

2.2.6 复盘层

负责任务完成后的复盘分析和回滚操作，优化任务流程，提升系统稳定性。

• 复盘分析：自动统计任务执行耗时、步骤成功率、失败原因、资源消耗，生成复盘报告，提出优化建议（如调整重试次数、优化组件调用顺序）。
• 回滚操作：支持手动/自动回滚，根据任务步骤的回滚配置（如回滚脚本、回滚参数），调用 Worker 节点执行回滚操作，恢复到任务执行前的状态，回滚过程留存证据。

3. 状态机设计

Harness 采用“全局任务状态 + 步骤状态”双层状态机，确保任务执行的有序性和可管控性。状态流转严格遵循预设规则，所有状态变化均会持久化并记录日志。

3.1 全局任务状态机

全局任务状态描述整个任务的生命周期，流转如下：

3.2 步骤状态机

每个任务步骤对应独立的状态机，步骤状态决定全局任务状态的流转，流转如下：

3.3 状态持久化规则

• 状态变更触发：每一次状态变化（如任务从“待执行”变为“执行中”，步骤从“执行中”变为“成功”），均触发持久化操作。
• 持久化内容：状态值、变更时间、变更原因（如“执行成功”“审批驳回”“重试”）、操作人（如调度系统、Reviewer、Worker 节点）。
• 持久化频率：实时持久化（状态变更后 100ms 内完成存储），确保崩溃、重启后可快速恢复状态。

4. Supervisor/Worker/Reviewer 职责边界

三者是 Harness 核心执行角色，职责严格分离、协同配合，避免权限滥用和职责混乱，确保系统稳定运行。

4.1 职责边界表

角色	核心职责	权限范围	禁止操作
Supervisor（调度者）	1. 解析任务、分配 Worker 节点；2. 监控任务/步骤状态；3. 决策下一步操作（重试、审批、终止）；4. 触发复盘、回滚；5. 管理组件注册与调度规则。	1. 读取/修改任务/步骤状态；2. 分配/取消 Worker 任务；3. 触发审批、复盘、回滚；4. 管理组件注册信息。	1. 直接执行任务步骤；2. 修改审批结果；3. 篡改证据和日志；4. 手动修改 Worker 执行结果。
Worker（执行者）	1. 接收 Supervisor 分配的步骤任务；2. 调用 Agent/模型/CLI 工具；3. 收集执行证据；4. 上报执行状态和结果；5. 执行重试、回滚指令。	1. 调用指定的组件（Agent/模型/CLI）；2. 读取任务步骤参数；3. 上传证据文件；4. 上报状态和结果。	1. 修改任务/步骤状态；2. 擅自调用未分配的组件；3. 篡改执行结果和证据；4. 拒绝执行 Supervisor 合法指令。
Reviewer（审批者）	1. 接收审批通知；2. 查看步骤详情和前置证据；3. 执行审批操作（通过、驳回）；4. 填写审批意见。	1. 查看指定任务步骤的详情和证据；2. 提交审批结果和意见；3. 查看自己的审批记录。	1. 修改任务/步骤执行状态；2. 篡改证据和日志；3. 审批非自己负责的任务；4. 擅自跳过审批流程。

4.2 协同流程

\1. Supervisor 解析任务后，将步骤分配给 Worker；2. Worker 执行步骤并上报状态/证据；3. 若步骤需审批，Supervisor 触发审批，Reviewer 完成审批并反馈；4. Supervisor 根据审批结果/执行结果，决定下一步操作；5. 任务完成后，Supervisor 触发复盘，Reviewer 可参与复盘意见。

5. 持久化状态设计

持久化是 Harness 长期运行的核心保障，需存储“任务、步骤、组件、状态、证据、日志”六大类数据，采用“分层存储+冗余备份”策略，确保数据安全和可恢复性。

5.1 持久化数据分类及存储介质

数据类型	核心内容	存储介质	备份策略	过期策略
任务元数据	任务 ID、名称、描述、创建人、创建时间、目标、流程配置、完成条件、审批规则。	MySQL	每日全量备份 + 实时增量备份	永久保存（用于审计、复盘）
步骤数据	步骤 ID、任务 ID、步骤名称、依赖步骤、组件类型、输入参数、执行结果、状态、执行时间。	MySQL + Redis	MySQL 同任务元数据备份；Redis 主从复制	永久保存（关联任务）
状态数据	任务状态、步骤状态、状态变更时间、变更原因、操作人。	Redis + MySQL	Redis 主从复制；MySQL 实时增量备份	永久保存（用于追溯）
证据数据	步骤执行日志、结果文件、截图、组件响应、回滚记录。	MinIO/S3	多地域备份 + 版本控制	可配置（默认 1 年，重要任务永久保存）
日志数据	系统操作日志、组件调用日志、异常日志、审批日志。	ElasticSearch	索引分片 + 定期备份	可配置（默认 6 个月）
组件数据	Agent/模型/CLI 注册信息、调用地址、权限配置、版本信息。	MySQL	同任务元数据备份	永久保存（组件注销后标记状态，不删除）

5.2 持久化恢复机制

当 Harness 重启、崩溃或节点故障时，通过以下流程恢复状态：

1. 从 MySQL 加载所有未完成的任务元数据、步骤数据、状态历史。
2. 从 Redis 加载实时状态（若 Redis 故障，从 MySQL 加载最新状态）。
3. Worker 节点重启后，主动向 Supervisor 上报自身状态，Supervisor 核对未完成的步骤，重新分配任务。
4. 证据数据从对象存储加载，确保每个步骤的证据链完整。
5. 恢复完成后，Supervisor 重新监控所有未完成任务，继续执行后续步骤。

6. 完成定义与防假完成机制

明确任务“完成”的标准，同时建立防假完成机制，避免因组件异常、数据篡改导致的“伪成功”，确保任务真正达到预期目标。

6.1 任务完成定义（双重校验）

任务完成需同时满足「步骤条件」和「目标条件」，二者缺一不可，由 Supervisor 负责校验。

6.1.1 步骤条件

• 所有串行步骤均执行成功（无失败、无未执行、无待审批状态）。
• 并行步骤按配置要求，达到指定成功率（如“3个并行步骤中至少2个成功”）。
• 所有需审批的步骤均已通过审批，审批意见完整。

6.1.2 目标条件

根据任务预设的目标，由 Supervisor 或指定组件（如校验 Agent）执行目标校验，示例如下：

• 自动化部署任务：目标服务正常启动，接口返回 200，健康检查通过。
• 数据治理任务：目标数据量达标、数据质量校验通过（无缺失、无异常）。
• 模型训练任务：模型准确率、召回率达到预设阈值，训练日志无异常。

6.2 防假完成机制（四层防护）

• 第一层：证据校验。Supervisor 校验每个步骤的证据链完整性，若证据缺失、篡改（通过哈希校验），判定为“假完成”，标记步骤失败。
• 第二层：结果复核。对关键步骤的执行结果，由独立的校验组件（与执行组件解耦）进行复核，如“部署完成后，由监控 Agent 再次检查服务状态”。
• 第三层：异常检测。通过日志分析、指标监控，检测组件执行过程中的异常（如执行时间过长、输出格式异常、接口报错），即使组件返回“成功”，也判定为“可疑完成”，触发人工复核。
• 第四层：审计校验。审计层在任务完成后，自动校验“步骤条件”“目标条件”的一致性，若存在不匹配，标记任务为“假完成”，触发回滚和复盘。

6.3 假完成处理流程

\1. 检测到假完成后，Supervisor 立即将任务状态改为“终止（假完成）”；2. 触发人工介入，通知相关负责人核查；3. 核查后，若可恢复，执行重试或回滚操作；若不可恢复，终止任务，生成假完成报告，纳入复盘。

7. 证据链设计

证据链是任务可追溯、可审计、可复盘的核心，需确保“每一步操作有记录、每一个结果有依据、每一次变更有痕迹”，形成完整、不可篡改的证据闭环。

7.1 证据链组成

每个任务对应一条完整的证据链，按“任务-步骤-操作”分级归档，包含以下内容：

• 任务级证据：任务创建记录、流程配置文件、审批规则、最终结果报告、审计报告、复盘报告。
• 步骤级证据：步骤分配记录、输入参数、组件调用日志、执行过程日志、输出结果（文件/数据）、状态变更记录、审批记录（若有）、重试记录（若有）、回滚记录（若有）。
• 操作级证据：每个操作（如组件调用、审批、重试）的时间、操作人、操作内容、接口响应、异常信息（若有）。

7.2 证据收集与存储

• 收集时机：步骤执行过程中实时收集，每完成一个操作（如调用组件、上报状态），立即收集对应的证据。
• 收集方式：Worker 节点负责收集本地执行证据（日志、结果文件），并上传至对象存储；Supervisor 收集状态变更、审批、调度等证据，同步至 MySQL 和对象存储。
• 存储结构：按“任务 ID/步骤 ID/证据类型”分级存储，如：task_123/step_456/logs/、task_123/step_456/results/，便于检索和下载。
• 防篡改：对所有证据文件进行哈希加密，哈希值存储在 MySQL 中，每次读取时校验哈希值，确保证据未被篡改。

7.3 证据使用场景

• 审批场景：Reviewer 查看步骤证据，作为审批决策的依据。
• 故障排查：任务失败时，通过证据链定位失败原因（如组件调用报错、参数错误）。
• 审计场景：生成审计报告时，提取证据链内容，证明任务执行合规。
• 复盘场景：复盘时，通过证据链分析执行过程中的问题，优化流程。
• 回滚场景：回滚时，参考证据链中的步骤执行记录，确保回滚到正确状态。

8. 失败恢复机制

失败恢复是 Harness 长期运行的关键，需覆盖“组件失败、步骤失败、节点失败、系统崩溃”等各类故障场景，确保任务可继续推进或优雅终止，减少损失。

8.1 失败类型及恢复策略

失败类型	定义	恢复策略	触发条件
组件调用失败	Worker 调用 Agent/模型/CLI 时，出现超时、报错、无响应。	1. 自动重试（可配置重试次数、重试间隔）；2. 重试失败后，切换备用组件（若配置）；3. 无备用组件，触发人工介入。	组件返回错误码、调用超时（超过预设阈值）。
步骤执行失败	组件调用成功，但执行结果未达到步骤预期（如数据校验失败、模型训练不达标）。	1. 检查输入参数，自动重试（可配置）；2. 重试失败后，触发人工审批（是否修改参数后重试）；3. 审批驳回，终止步骤，触发任务回滚。	步骤结果校验未通过、输出格式异常。
Worker 节点失败	Worker 节点崩溃、离线，无法继续执行任务。	1. Supervisor 检测到节点离线后，将该节点上的未完成步骤重新分配给其他健康节点；2. 若步骤已执行部分，根据中间缓存和证据，恢复执行进度（避免重复执行）。	Worker 节点心跳中断（超过预设时间）、状态上报失败。
Supervisor 失败	调度层崩溃、重启，无法进行任务调度。	1. 启动备用 Supervisor（主从架构），接管调度权限；2. 从存储层加载所有任务状态，恢复调度逻辑；3. 核对未完成步骤，重新分配任务。	Supervisor 心跳中断、无法响应 Worker 上报。
系统崩溃	整个 Harness 系统崩溃（如服务器宕机、存储故障）。	1. 重启系统，从存储层恢复所有任务、步骤、状态数据；2. 重启所有 Worker 节点，重新分配未完成任务；3. 校验证据链完整性，确保恢复后无数据丢失。	系统整体离线、存储无法访问。

8.2 恢复优先级与重试规则

• 恢复优先级：核心任务（如生产部署）> 普通任务；关键步骤（如数据写入、服务启动）> 辅助步骤（如日志收集）。
• 重试规则：可配置重试次数（默认 3 次）、重试间隔（默认 10s），支持指数退避（如第一次 10s，第二次 20s，第三次 40s）；关键步骤可配置“人工确认后重试”。
• 降级策略：当多个组件同时失败时，优先保障核心组件的恢复，非核心组件可暂时降级（如日志收集组件失败，可先完成任务，后续补全日志）。

8.3 失败告警与人工介入

• 告警触发：当失败次数达到阈值、无恢复策略可用、出现严重异常（如证据篡改）时，触发告警（邮件、钉钉、短信），通知相关负责人。
• 人工介入：负责人可查看失败详情、证据链，执行“手动重试、修改参数、终止任务、触发回滚”等操作，介入记录留存至证据链。

9. 复盘与回滚机制

9.1 复盘机制

复盘的核心是“总结经验、优化流程”，分为“自动复盘”和“手动复盘”，所有复盘结果均持久化，用于后续任务优化。

9.1.1 复盘触发条件

• 自动触发：任务完成（成功/失败）、任务终止（审批驳回、假完成、手动终止）后，自动触发复盘。
• 手动触发：用户/管理员可针对任意已归档任务，手动触发复盘。

9.1.2 复盘内容

• 任务执行概况：任务耗时、步骤成功率、资源消耗（CPU、内存）。
• 失败分析：失败步骤、失败原因、恢复过程、改进建议（如调整重试次数、优化组件调用顺序）。
• 合规审计：是否符合审批规则、证据链是否完整、是否存在假完成。
• 优化建议：针对流程、组件、调度规则的改进建议，自动同步至任务配置模板。

9.1.3 复盘流程

9.2 回滚机制

回滚用于“任务执行失败、假完成、审批驳回”等场景，将系统恢复到任务执行前的状态，确保数据和服务的一致性，回滚过程全程留痕。

9.2.1 回滚触发条件

• 自动触发：任务标记为“失败（不可恢复）”“假完成”，且配置了“自动回滚”规则。
• 手动触发：用户/管理员针对未完成、已完成的任务，手动触发回滚（需审批，避免误操作）。

9.2.2 回滚策略

• 步骤级回滚：仅回滚指定失败步骤，不影响其他已成功步骤（适用于步骤间无强依赖的场景）。
• 任务级回滚：回滚整个任务的所有步骤，恢复到任务执行前的初始状态（适用于步骤间有强依赖、任务失败影响较大的场景）。
• 增量回滚：仅回滚发生变更的内容（如修改的配置、写入的数据），减少回滚耗时（适用于大型任务）。

9.2.3 回滚流程

10. MVP 版本取舍（最小可行产品）

MVP 版本核心目标：实现“多组件调度、任务执行、状态持久化、基础失败恢复”，优先保障核心功能可用，砍掉非必要的复杂特性，快速落地验证。

10.1 MVP 保留功能（核心必选）

• 核心架构：调度层（Supervisor）、执行层（Worker）、存储层（基础存储），实现任务解析、步骤分配、组件调用。
• 状态机：简化版全局任务状态机（待执行、执行中、成功、失败、终止）和步骤状态机，确保状态流转正常。
• 持久化：核心数据（任务元数据、步骤数据、状态数据、基础证据）的持久化，支持重启恢复。
• 组件调用：支持 Agent、CLI 工具的调用（暂不支持 AI 模型集群，仅支持单模型调用）。
• 基础失败恢复：组件调用失败的自动重试、Worker 节点失败的任务重新分配。
• 基础证据链：步骤执行日志、结果文件的收集与存储，支持简单检索。
• 完成定义：简化版双重校验（步骤全部成功 + 基础目标校验）。

10.2 MVP 砍掉功能（后续迭代）

• 复杂审批：砍掉多级审批、审批意见流转，仅保留简单的“同意/驳回”审批（可选）。
• 高级复盘：砍掉自动复盘分析、优化建议生成，仅保留手动复盘记录。
• 高级回滚：砍掉增量回滚、步骤级回滚，仅保留简单的任务级回滚（需手动配置回滚脚本）。
• 防假完成：砍掉证据哈希校验、独立复核组件，仅保留基础的证据缺失检测。
• 高级监控：砍掉实时指标监控、异常检测，仅保留基础的日志记录和失败告警。
• 组件扩展：砍掉动态组件注册、组件版本管理，仅支持静态配置的组件调用。
• 高可用：砍掉 Supervisor 主从架构、多地域备份，仅支持单节点部署（适合测试和小规模使用）。

10.3 MVP 迭代路线

MVP 落地后，按以下顺序迭代补充砍掉的功能：1. 高级回滚 & 复盘 → 2. 防假完成机制 → 3. 复杂审批 → 4. 组件扩展 & 高可用 → 5. 高级监控 & 自动化优化。

11. 总结

本设计的 Agent Harness 通过“松耦合架构、完善的状态机、清晰的职责边界、可靠的持久化、完整的证据链、 robust 的失败恢复”，实现复杂工程任务的长期稳定运行。MVP 版本聚焦核心功能，快速落地验证，后续通过迭代补充高级特性，逐步提升系统的稳定性、可扩展性和安全性，适配更多复杂场景的需求。