自治 Agent Runner

版本: v1.0.0+ | ReAct 循环 | 目标分解 | 自主任务执行

自治 Agent Runner 是一个基于 ReAct (Reason-Act-Observe) 循环的自主任务执行引擎，能够将复杂目标分解为可执行步骤并自主完成。

概述

自治 Agent Runner 是 ChainlessChain 的自主任务执行引擎，基于 ReAct（Reason-Act-Observe）推理闭环驱动。它能将复杂目标自动分解为可执行步骤链，支持最多 3 个目标并发执行、失败自动重试与重新规划、检查点断点恢复，以及不确定情况下的用户交互确认。

核心特性

🧠 ReAct 循环: Reason-Act-Observe 推理闭环，自主决策下一步行动
🎯 目标分解: 复杂目标自动拆分为可执行步骤链
⚡ 并发执行: 最多同时处理 3 个目标，支持暂停/恢复
🔄 自我修正: 步骤失败时自动重试或重新规划（最多 3 次）
💾 检查点恢复: 定期保存执行状态，支持故障后断点续行
👤 用户交互: 遇到不确定情况主动请求用户确认

系统架构

┌─────────────────────────────────────────────────┐
│           Autonomous Agent Runner                 │
├─────────────────────────────────────────────────┤
│                                                   │
│       ┌──────────┐                               │
│       │  Goal    │ ← 接收用户目标                 │
│       │ Decomposer│                               │
│       └────┬─────┘                               │
│            ▼                                      │
│  ┌────────────────────────────────────────┐      │
│  │        ReAct Loop Engine               │      │
│  │  ┌────────┐ ┌──────┐ ┌─────────┐     │      │
│  │  │Reason  │→│ Act  │→│ Observe │──┐  │      │
│  │  └────────┘ └──────┘ └─────────┘  │  │      │
│  │       ↑                           │  │      │
│  │       └───────────────────────────┘  │      │
│  └────────────────┬───────────────────┘      │
│                   │                            │
│  ┌────────┐ ┌─────▼─────┐ ┌────────────────┐  │
│  │ Skills │ │ Tool      │ │ Checkpoint     │  │
│  │ & Tools│ │ Registry  │ │ Manager        │  │
│  └────────┘ └───────────┘ └────────────────┘  │
│                                                   │
│  ┌──────────────────────────────────────────┐    │
│  │ SQLite: autonomous_goals / steps         │    │
│  └──────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘

系统概述

ReAct 循环

        ┌─────────────┐
        │   接收目标    │
        └──────┬──────┘
               ▼
        ┌─────────────┐
   ┌───→│   Reason     │ ← 分析当前状态，决定下一步
   │    │   (推理)      │
   │    └──────┬──────┘
   │           ▼
   │    ┌─────────────┐
   │    │    Act       │ ← 执行动作（调用工具/技能）
   │    │   (行动)      │
   │    └──────┬──────┘
   │           ▼
   │    ┌─────────────┐
   │    │   Observe    │ ← 观察结果，评估进度
   │    │   (观察)      │
   │    └──────┬──────┘
   │           │
   │     目标完成？
   │     ├─ 否 ──→ ┘ (继续循环)
   │     └─ 是
   │           ▼
   │    ┌─────────────┐
   │    │  Complete    │
   │    │  (完成)      │
   │    └─────────────┘
   │
   └── 异常？→ 自我修正 / 重新规划

核心特性

目标分解: 将复杂目标自动拆分为可执行步骤
自主执行: 无需人工干预即可完成多步骤任务
并发执行: 支持同时处理最多 3 个目标
暂停/恢复: 随时暂停执行，恢复后继续
用户输入: 遇到不确定情况主动请求用户确认
自我修正: 步骤失败时自动重试或重新规划
检查点: 定期保存执行状态，支持故障恢复

目标生命周期

queued → running → completed
                 → failed
         ├→ paused → running
         └→ waiting_input → running

状态	说明
`queued`	已创建，等待执行
`running`	正在执行中
`paused`	用户暂停
`waiting_input`	等待用户输入
`completed`	执行完成
`failed`	执行失败

动作类型

Agent 在执行过程中可使用以下动作：

动作类型	说明	示例
`skill`	调用内置技能	`/code-review`, `/unit-test`
`tool`	调用注册工具	文件读写、搜索、计算
`search`	搜索知识库/代码库	RAG 检索、代码搜索
`file`	文件操作	创建、编辑、删除文件
`ask_user_question`	请求用户输入	确认方案、提供信息（v0.47.0 open-agents 对标重命名）
`complete`	标记目标完成	提交最终结果

配置参考

json

{
  "autonomousAgent": {
    "maxStepsPerGoal": 100,
    "stepTimeoutMs": 120000,
    "maxConcurrentGoals": 3,
    "tokenBudgetPerGoal": 50000,
    "evaluationIntervalMs": 1000,
    "maxRetriesPerStep": 3,
    "maxReplanAttempts": 3
  }
}

参数	默认值	说明
`maxStepsPerGoal`	100	每个目标最大执行步数
`stepTimeoutMs`	120,000 (2分钟)	单步执行超时
`maxConcurrentGoals`	3	最大并发目标数
`tokenBudgetPerGoal`	50,000	每个目标的 Token 预算
`evaluationIntervalMs`	1,000 (1秒)	进度评估间隔
`maxRetriesPerStep`	3	单步最大重试次数
`maxReplanAttempts`	3	最大重新规划次数

使用示例

创建自治目标

用户: "帮我重构 user-service 模块，提升代码质量"

Agent 分解:
  Step 1: 搜索并阅读 user-service 所有源文件
  Step 2: 分析代码结构，识别问题
  Step 3: 制定重构方案（请求用户确认）
  Step 4: 逐文件执行重构
  Step 5: 运行测试确保功能正常
  Step 6: 生成重构报告

暂停与恢复

执行中 → 用户点击"暂停"
  → 保存当前检查点
  → 状态变为 paused

用户点击"恢复"
  → 加载检查点
  → 从上次断点继续执行

自我修正

Step 4 执行失败（测试不通过）
  → 观察错误信息
  → 分析失败原因
  → 调整方案（重新规划）
  → 重新执行 Step 4
  → 最多重试 3 次
  → 仍然失败 → 请求用户帮助

数据库表

`autonomous_goals`

字段	类型	说明
`id`	TEXT	目标 ID
`description`	TEXT	目标描述
`status`	TEXT	生命周期状态
`steps_total`	INTEGER	总步数
`steps_completed`	INTEGER	已完成步数
`created_at`	DATETIME	创建时间
`completed_at`	DATETIME	完成时间

`autonomous_steps`

字段	类型	说明
`id`	TEXT	步骤 ID
`goal_id`	TEXT	所属目标 ID
`action_type`	TEXT	动作类型
`description`	TEXT	步骤描述
`status`	TEXT	执行状态
`result`	TEXT	执行结果（JSON）
`error`	TEXT	错误信息

关键文件

文件	职责
`src/main/ai-engine/autonomous/autonomous-agent-runner.js`	自治 Agent 核心引擎
`src/renderer/stores/autonomous.ts`	自治 Agent 状态管理

性能指标

操作	目标	实际	状态
目标创建与分解	< 10s	~5-8s	✅
单步 Reason 推理	< 8s	~3-6s	✅
工具调用执行（Act）	< 30s	~5-20s	✅
检查点保存	< 200ms	~80ms	✅
检查点恢复	< 500ms	~200ms	✅
并发 3 目标吞吐	3x 单目标	~2.5x	✅
目标状态查询	< 100ms	~30ms	✅

测试覆盖率

文件	类型	测试数
✅ `autonomous-agent-runner.test.js`	单元	35
✅ `goal-decomposer.test.js`	单元	20
✅ `react-loop.test.js`	单元	28
✅ `checkpoint-manager.test.js`	单元	15
✅ `autonomous-agent-integration.test.js`	集成	18
合计		116

故障排查

目标长时间处于 running 状态

现象: 目标执行未结束，步数不断增长但无明显进展。

排查步骤:

检查 autonomous_steps 表中最近步骤的 result 和 error 字段
确认是否陷入死循环（同一类型的步骤反复执行），适当缩小 maxStepsPerGoal
查看 Token 消耗是否已接近 tokenBudgetPerGoal 上限
手动暂停目标，检查检查点状态后决定是否重新规划

自我修正反复失败

现象: 步骤失败后重试 3 次仍然失败，目标状态变为 failed。

排查步骤:

查看失败步骤的 error 字段，确认是工具调用失败还是 LLM 推理错误
检查相关工具（文件读写、搜索等）是否可用且权限正常
目标描述可能过于模糊，尝试用更具体的描述重新创建目标
调大 maxReplanAttempts 或 stepTimeoutMs 给 Agent 更多容错空间

并发目标相互干扰

现象: 多个目标同时修改同一文件或资源，导致冲突。

排查步骤:

检查并发目标的工作范围是否重叠，避免多个目标操作同一目录
降低 maxConcurrentGoals 为 1，排除并发问题
使用更细粒度的目标拆分，确保各目标操作独立资源

检查点恢复失败

现象: 暂停后恢复执行时，Agent 无法正确继续之前的进度。

排查步骤:

确认 autonomous_goals 和 autonomous_steps 表数据完整
检查恢复时上下文信息是否因 Session 过期而丢失
考虑放弃当前检查点，重新创建目标从头执行

安全考虑

Token 预算控制: 为每个目标设置合理的 tokenBudgetPerGoal，防止失控消耗
文件操作沙箱: Agent 的文件操作应限制在项目目录内，禁止访问系统关键路径
敏感操作确认: 涉及文件删除、Git 推送等不可逆操作时，Agent 应主动请求用户确认
执行日志审计: 所有 Agent 步骤和工具调用记录在数据库中，便于事后审查
并发限制: 合理设置 maxConcurrentGoals，避免资源争抢和意外副作用
超时保护: 通过 stepTimeoutMs 防止单步操作无限挂起
权限最小化: Agent 注册的工具集应限于任务必需范围，不暴露系统管理能力
用户可中断: 确保用户随时可暂停或终止 Agent 执行，保持人在回路控制

自治 Agent Runner ​

概述 ​

核心特性 ​

系统架构 ​

系统概述 ​

ReAct 循环 ​

核心特性 ​

目标生命周期 ​

动作类型 ​

配置参考 ​

使用示例 ​

创建自治目标 ​

暂停与恢复 ​

自我修正 ​

数据库表 ​

autonomous_goals ​

autonomous_steps ​

关键文件 ​

性能指标 ​

测试覆盖率 ​

故障排查 ​

目标长时间处于 running 状态 ​

自我修正反复失败 ​

并发目标相互干扰 ​

检查点恢复失败 ​

安全考虑 ​

相关文档 ​

自治 Agent Runner

概述

核心特性

系统架构

系统概述

ReAct 循环

核心特性

目标生命周期

动作类型

配置参考

使用示例

创建自治目标

暂停与恢复

自我修正

数据库表

`autonomous_goals`

`autonomous_steps`

关键文件

性能指标

测试覆盖率

故障排查

目标长时间处于 running 状态

自我修正反复失败

并发目标相互干扰

检查点恢复失败

安全考虑

相关文档