Agent迭代引擎

> 从执行中学习、提炼、进化 —— 完整的经验迭代闭环

概述

Agent迭代引擎将日志记录、经验提炼、晋升机制、衰退管理、智能检索和成长报告整合为统一闭环，帮助Agent从每次任务执行中持续积累和进化。

┌─────────────────────────────────────────────────────────┐
│                    Agent迭代引擎                          │
│                                                          │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐           │
│  │ 日志记录  │───→│ 经验提炼  │───→│ 晋升机制  │           │
│  │ 学习/错误 │    │ 卡片生成  │    │ 冲突检测  │           │
│  │ /需求    │    │ 去重合并  │    │ SOUL/TOOLS│           │
│  └──────────┘    └──────────┘    └──────────┘           │
│       ↑               ↑               │                  │
│       │          ┌──────────┐         │                  │
│       │          │ 经验衰退  │←────────┤                  │
│       │          │ 权重衰减  │         │                  │
│       │          │ 过期归档  │         ↓                  │
│       │          └──────────┘    ┌──────────┐           │
│       │                          │ 成长报告  │           │
│       └──────────────────────────│ 统计分析  │           │
│                                  │ 学习曲线  │           │
│  ┌──────────┐                    └──────────┘           │
│  │ 智能检索  │                                           │
│  │ 关联推荐  │                                           │
│  └──────────┘                                           │
└─────────────────────────────────────────────────────────┘

快速参考表

快速上手

🎯 新手必读：3分钟快速上手指南

包含：

• 安装配置
• 第一次记录学习
• 提炼经验
• 查看成长报告
• 5个最常用命令速查

❓ 常见问题：FAQ文档

⚠️ 避坑指南：常见问题与解决方案

安装与配置

安装

将技能目录复制到工作空间：

cp -r agent-iteration-engine ~/.openclaw/skills/
# 或项目级
cp -r agent-iteration-engine ./skills/

初始化

首次使用时，引擎会自动创建工作空间目录和日志文件：

.迭代引擎/
├── 学习日志.md
├── 错误日志.md
├── 需求日志.md
└── 成长报告/

Hook配置（可选）

激活器Hook — 每次提交提示后提醒评估学习：

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{"type": "command", "command": "./skills/agent-iteration-engine/scripts/activator.sh"}]
    }]
  }
}

错误检测Hook — 命令失败时自动提醒：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "./skills/agent-iteration-engine/scripts/error-detector.sh"}]
    }]
  }
}

工作空间结构

项目根目录/
├── SOUL.md              # 行为准则（晋升目标）
├── TOOLS.md             # 工具经验（晋升目标）
├── AGENTS.md            # 工作流（晋升目标）
├── .迭代引擎/            # 引擎工作空间
│   ├── 学习日志.md
│   ├── 错误日志.md
│   ├── 需求日志.md
│   ├── 晋升历史.json
│   └── 成长报告/
│       └── 周报_YYYYMMDD.md
├── data/
│   ├── experience_db.json   # 经验库
│   └── config.json          # 配置文件
└── skills/
    └── agent-iteration-engine/

核心功能一：日志记录

三层日志系统，从自我进化技能整合而来。

学习日志

记录纠正、洞察、知识缺口和最佳实践。

日志ID格式: 学习-YYYYMMDD-XXX（如 学习-20250115-A3B）

经验权重来源:

状态流转: 待处理 → 进行中 → 已解决 → 已晋升/已归档

错误日志

记录命令失败、异常和非预期行为。

日志ID格式: 错误-YYYYMMDD-XXX

需求日志

记录用户请求的尚不存在的功能。

日志ID格式: 需求-YYYYMMDD-XXX

自动检测

引擎可自动检测以下场景并记录日志：

核心功能二：经验提炼

从任务执行中提取结构化经验卡片。

经验卡片结构

## 经验卡片 #编号

### 📋 场景
- 任务类型：[类型]
- 触发条件：什么情况下会遇到

### 🎯 方法
- 核心方法：用什么方法解决的
- 关键步骤：1. 2. 3.
- 涉及技能：[技能列表]

### ⚠️ 避坑指南
- 常见错误：容易踩的坑
- 解决方案：如何避免

### 📊 效果评估
- 结果：成功/失败/部分成功
- 效率提升：[描述]
- 可复用性：高/中/低

### 💡 延伸应用
- 还能用在哪些地方

### 🏷️ 标签
#类型 #技能 #价值等级

多种输入方式

去重机制

• 新增经验时自动检测重复
• 相似度>70%时提示可能重复
• 处理选项：合并/覆盖/保留

核心功能三：晋升机制

将高价值经验晋升到项目记忆文件。

晋升条件

> 特殊规则：用户纠正且权重≥0.9的经验，可降低复现次数要求。

晋升目标

晋升流程

1. 评估：检查权重、复现次数、来源
2. 冲突检测：与目标文件现有内容比对
3. 生成预览：精炼内容供确认
4. 执行晋升：写入目标文件
5. 记录历史：保存晋升记录

冲突检测

晋升前自动检测与现有规则的冲突：

核心功能四：经验衰退

防止经验库膨胀，自动管理经验生命周期。

权重计算

权重 = (基础权重 + 复现加成 + 召回加成) × 时效衰减因子

衰退状态

衰退操作

• 自动降权：长期未被召回的经验权重持续衰减
• 标记归档：权重低于0.2标记为"待归档"
• 手动提升：可手动干预提升特定经验的权重

核心功能五：智能检索与提醒

检索约束

关联推荐

当查看或新增经验时，自动推荐相关经验：

1. 同批次推荐：本次对话中已生成的相关经验
2. 标签匹配：共享≥2个相同标签的经验优先
3. 场景关联：触发条件相近的经验优先
4. 互补推荐：成功经验+失败教训对比展示
5. 数量限制：每次推荐≤5条

推荐约束

• 需求匹配：推荐必须与当前任务相关
• 避免重复：同一经验24小时内不重复推荐
• 用户可控：可关闭自动推荐

核心功能六：成长报告

报告内容

报告周期

核心功能七：经验导出

导出选项：全量导出、筛选导出、单条导出。

触发方式与命令

命令行

# 日志记录
python scripts/main.py 学习 --摘要 "..." --分类 知识缺口 --来源 用户纠正
python scripts/main.py 错误 --摘要 "..." --错误信息 "TimeoutError"
python scripts/main.py 需求 --能力 "..."

# 经验操作
python scripts/main.py 提炼 --输入 task.json --输出 result.json
python scripts/main.py 搜索 "关键词"
python scripts/main.py 导出 --格式 json --输出 file.json

# 晋升与检测
python scripts/main.py 晋升 --经验ID xxx --目标 TOOLS.md
python scripts/main.py 冲突检测 --摘要 "..." --目标 SOUL.md

# 报告与衰退
python scripts/main.py 成长报告 --周期 周
python scripts/main.py 衰退
python scripts/main.py 统计

命令别名

为了更快输入，支持以下命令别名：

查看命令示例

每个命令都支持 --示例 参数，可以查看该命令的使用示例（不执行）：

# 查看学习命令示例
python scripts/main.py 学习 --示例

# 查看晋升命令示例
python scripts/main.py 晋升 --示例

# 查看向导命令示例
python scripts/main.py 向导 --示例

向导模式

使用 向导 命令可以实现一站式操作，无需记住复杂参数：

# 一站式记录学习
python scripts/main.py 向导 --操作 学习 --摘要 "发现新方法"

# 一站式记录错误
python scripts/main.py 向导 --操作 错误 --摘要 "文件读取失败"

# 一站式提炼
python scripts/main.py 向导 --操作 提炼 --输入 task.json

# 查看向导帮助
python scripts/main.py 向导

错误码查询

使用 错误码 命令查看所有错误码及其含义：

# 查看所有错误码
python scripts/main.py 错误码

# 查看特定错误码详情
python scripts/main.py 错误码 ERR001

Shell脚本

# 激活器（Hook用）
./scripts/activator.sh

# 错误检测（Hook用）
./scripts/error_detector.sh

# 技能提取
./scripts/extract_skill.sh 新技能名 --dry-run
./scripts/extract_skill.sh 新技能名

日志格式规范

学习日志

## [学习-YYYYMMDD-XXX] 分类

**记录时间**: YYYY-MM-DD HH:MM:SS
**优先级**: 低/中/高/紧急
**状态**: 待处理
**领域**: 通用
**经验权重**: 0.5
**来源**: 自主发现

### 摘要
一句话描述

### 详情
完整上下文

### 建议行动
具体措施

### 元数据
- 来源: 自主发现
- 相关文件: 无
- 标签: 无
- 关联: 无

---

错误日志

## [错误-YYYYMMDD-XXX] 命令名称

**记录时间**: YYYY-MM-DD HH:MM:SS
**优先级**: 高
**状态**: 待处理
**领域**: 通用
**经验权重**: 0.7

### 摘要
什么失败了

### 错误信息
\```
实际错误消息
\```

### 上下文
- 命令: xxx
- 参数: xxx

### 建议修复
可能的解决方案

### 元数据
- 可复现: 是/否/未知
- 关联: 无

---

需求日志

## [需求-YYYYMMDD-XXX] 功能名称

**记录时间**: YYYY-MM-DD HH:MM:SS
**优先级**: 中
**状态**: 待处理
**领域**: 通用
**经验权重**: 0.3

### 需求描述
用户想要什么

### 用户上下文
为什么需要

### 复杂度评估
简单/中等/复杂

### 元数据
- 频率: 首次/反复

---

晋升规则

何时晋升

• 经验适用于多个文件/功能
• 任何贡献者（人或Agent）都应知道的知识
• 防止重复犯错的规则
• 项目特定的约定

晋升格式

从详细经验精炼为简洁规则：

原始经验（冗长）:

> 项目使用pnpm工作空间。尝试npm install但失败了。锁文件是pnpm-lock.yaml。必须使用pnpm install。

晋升后（简洁）:

## 包管理
- 包管理器: pnpm（不是npm）- 使用 `pnpm install`

技能提取

当经验价值足够高，可提取为独立技能：

./scripts/extract_skill.sh 新技能名 --dry-run  # 预览
./scripts/extract_skill.sh 新技能名            # 创建

提取条件：复现≥2次、已验证、非显而易见、广泛适用、用户标记。

使用示例

详细示例请参阅 references/examples.md。

快速示例

记录学习:

引擎.记录学习(分类="纠正", 摘要="项目使用pnpm", 来源="用户纠正", 优先级="高")

提炼经验:

引擎.提炼经验(任务信息={类型:"写作", 目标:"撰写PRD", 过程:"调研→梳理→撰写", 结果:"成功"})

晋升:

引擎.晋升(经验ID="xxx", 目标="TOOLS.md")

成长报告:

引擎.生成报告(周期="周")

配置选项