🧬 Self-Evolving-Core v5.2.0 — Agent自进化能力

> 让Agent拥有"同一个坑只踩一次"的记忆力。
>
> 核心能力：学习环闭合 + 数据零截断 + 双地同步

⚡ 30秒上手

3条铁律，记住就行：

① 安装/升级：python3 {SKILL_PATH}/scripts/upgrade_agent.py --deploy

② 每次任务结束 → log：
   python3 domains/_shared/evolution_guardian.py log <domain> "<任务>" <success|failed|partial>

③ ★ 不需要手动review了！
   log每3次 → R1自动触发 → auto-review自动提取经验 → 写入experiences.json

> AI只需做一件事：执行log。其余全自动。

1. 核心概念

1.1 工作流闭环

用户给任务 → Router路由(经验+免疫预检) → AI执行 → log记账
                                                    ↓
                                              每3次任务(R1)
                                                    ↓
                                           auto-review [自动！]
                                                    ↓
                                         扫描最近N条任务日志
                                                    ↓
                                    ┌───────────────┴───────────────┐
                                    ▼                               ▼
                              成功×≥2次                        含失败
                              L2程序性经验                    L2教训+免疫规则
                                    ↓                               ↓
                              experiences.json              immune_rules.json
                                    └───────────────┬──────────────┘
                                                  ↓
                                    下次Router加载时自动生效

1.2 四条进化规则（log自动检测+自动执行）

1.3 四层记忆

1.4 免疫规则

Router每次任务前自动预检：

1.5 数据完整性保证（★ 第三轮审计核心修复）

所有数据存储路径零截断：

2. 命令参考

入口：python3 domains/_shared/evolution_guardian.py <command>

2.1 log — 任务记账（★ 唯一必做的操作）

# 基础用法
log <domain> "<task>" <success|failed|partial>

# 完整用法
log <domain> "<task>" <result> [error_type] [error_category] [tokens] [duration_sec]

# 失败时附带教训（直接写experiences+immune_rules）
log data "API超时" failed timeout API --lesson="需要加retry机制"

# ★ v5.1新增: trace和context参数（GEPA思想）
log data "任务" success --trace="tool1→tool2→tool3" --context="因为X选择Y方案"

关键行为：
- 新域自动创建目录（不再拒绝）
- ★ v5.1: 新域自动注册到Router的index.json（域名作为触发词）
- 成功后自动检查R1-R4并执行对应动作
- R1触发时立即自动执行 review --auto（异步，日志写入auto-review.log）
- ★ v5.1: 耗时自动计算（从上次log时间推算）
- ★ v5.1: token显示N/A（无法自知时不显示误导性的0）

2.2 review — 复盘（★ 自动经验提取引擎）

review <domain>         # 完整报告模式（详细输出每组任务分析）
review <domain> --auto  # 轻量自动模式（R1调用，单行摘要）

提取算法：

输入: recent_tasks(20条) + evolution.log(全部历史)
  ↓
按 _normalize_task_type() 聚类分组
  ↓
┌────────────────────┬──────────────────────┬──────────────┐
│ 成功组 × ≥2次      │ 含失败记录            │ 单次/混合     │
│ → L2程序性经验      │ → L2教训 + 免疫规则    │ → 跳过       │
│ 置信度 0.5~0.95    │ 置信度固定 0.8        │ 样本不足      │
└────────────────────┴──────────────────────┴──────────────┘
  ↓
与已有 experiences.json 去重（单字级token重叠>=85% = 已存在；50-85%冲突窗口标记旧经验deprecated）
  ↓
写入新经验和规则

2.3 check — 域诊断

check <domain>    # 文件完整性 / 经验库 / 任务统计 / 免疫系统

2.4 evolve / feedback / distill / archive-logs / experience-update / hot-experiences / decay

evolve <domain> "原因描述"
feedback admin negative <strong|medium|mild> "<触发词>" "<上下文>"
distill --from-daily    # 每日日志→STM
distill --from-stm      # STM→MEMORY.md
distill                 # 仅应急：MEMORY超200行
archive-logs [--days=N] [--dry-run]
experience-update <domain> <id> <deprecate|supersede> [new_id]

# ★ v5.1 新增
hot-experiences [数量]   # 输出所有域中最高价值经验（供session初始化）
decay [--dry-run]        # 经验置信度衰减（>30天+proven<=1 → conf-=0.1; <=0.3→deprecated）

3. 目录结构

项目根目录/
├── domains/
│   ├── _shared/
│   │   ├── evo-config.json           ← 全局配置(阈值)
│   │   ├── evolution_guardian.py     ← ★ 统一入口
│   │   ├── domain_router.py         ← 领域路由引擎
│   │   ├── evo-feedback.json        ← 反馈记录
│   │   └── admin-experiences.json   ← 跨域共享经验
│   │
│   └── <域名>/                       ← 中文语义命名（禁止hash/英文缩写）
│       ├── experiences.json          ← review自动写入
│       ├── memory.json               ← 统计(recent_tasks等)
│       ├── immune_rules.json          ← review自动写入
│       └── evolution.log             ← 进化日志(Review的数据源之一)
│
├── memory/                              ← 记忆目录（IDE无关，部署时自动发现或创建）
│   ├── MEMORY.md                     ← 长期元层(<200行,含PINNED强制校验区)
│   ├── short-term-memory.md          ← STM缓冲
│   ├── YYYY-MM-DD.md                 ← 每日日志
│   └── archive/                      ← 归档
│
└── workspace/.tmp/l4-memory.json      ← Session临时

4. 双地同步规则（★ 关键）

修改以下3个文件后必须双地同步：

> {SKILL_HOME} = 你使用的IDE的skill安装目录。WorkBuddy: ~/.workbuddy/skills/；Cursor: ~/.cursor/skills/；其他IDE请查阅对应文档。

为什么？ 新工作空间部署时从 skill 源码复制文件到工作副本。不同步 = 新工作空间拿到旧版 bug。

验证命令：

diff domains/_shared/evolution_guardian.py {SKILL_HOME}/self-evolving-core/scripts/evolution_guardian.py
# 期望输出：空（完全一致）

5. MEMORY.md 规范（★ 纯净性原则）

5.1 PINNED 区强制内容

MEMORY.md 顶部 <!-- PINNED_SECTION --> 到 <!-- PINNED_SECTION_END --> 之间为永驻区，蒸馏不会删除。必须包含：

• 🔴 沟通规范（称呼/语调/执行原则）
• 🔴 运行模式（Domain框架唯一模式）
• 🔴 核心操作纪律P0（路由→log→自检）
• 🔴 批判性思维规则
• 🔴 项目目录管理规则（中文命名）
• 🔴 领域经验管理规则（保存位置/创建方式/双地同步）

5.2 纯净性要求

6. 域管理规则

6.1 域命名

6.2 域创建方式

7. 部署与升级

7.1 首次部署（新项目）

python3 {SKILL_PATH}/scripts/upgrade_agent.py --deploy [--root <目录>] [--yes]

自动完成：识别架构 → 创建域 → 注入钩子 → 整理MEMORY.md → 架构优化建议

7.2 从旧版升级（已部署用户）

Step 1: 从skill源码覆盖3个核心文件到工作副本

cp {SKILL_HOME}/self-evolving-core/scripts/evolution_guardian.py \
   <项目>/domains/_shared/evolution_guardian.py
cp {SKILL_HOME}/self-evolving-core/scripts/domain_router.py \
   <项目>/domains/_shared/domain_router.py
cp {SKILL_HOME}/self-evolving-core/scripts/evo-config.json \
   <项目>/domains/_shared/evo-config.json

Step 2: 更新 MEMORY.md（手动，不可覆盖）
- 去掉PINNED区外的版本号
- 在 <!-- PINNED_SECTION_END --> 前补全「领域经验管理规则」章节

Step 3: 验证

python3 domains/_shared/evolution_guardian.py check _shared
python3 domains/_shared/evolution_guardian.py log _shared "升级验证" success "" ""

> 详细升级步骤见：自进化系统升级提示词-v5.1.0.md（skill 目录下）

8. 经验质量与去重

8.1 经验质量分级

8.2 去重保护与冲突检测

• 精确匹配: scenario完全相同 → 跳过
• 模糊匹配: 单字级token重叠 >= 85% → 视为已存在 → 跳过（短文本<3 token保护：跳过模糊匹配）
• 冲突检测: 50-85%重叠窗口 → 旧经验标记deprecated + 新经验增加supersedes链
• 防止同类经验反复堆积，同时保证新认知能替代过时经验

8.3 experiences.json Schema (v5.2)

{
  "id": "lesson_xxx_0",
  "status": "active|deprecated",
  "layer": "L2",
  "scenario": "任务描述（完整，不截断）",
  "keywords": ["关键词", "keyword_en"],
  "lang": "zh|en|mixed",
  "steps": ["教训: xxx"],
  "insight": "经验核心内容",
  "trace": "tool1→tool2→tool3（决策路径）",
  "context": "因为X所以选择Y方案",
  "why_failed": "error_type（失败原因分类）",
  "confidence": 0.7,
  "proven_count": 1,
  "superseded_by": null,
  "supersedes": ["被本经验替代的旧经验id列表"],
  "source_task": "原始任务描述",
  "agent": "admin",
  "tags": ["from_log_lesson", "failure"],
  "timestamp": "2026-05-19T14:00:00",
  "updated_at": "2026-05-19T14:00:00"
}

9. 记忆管理（三段式蒸馏）

每日日志 → distill --from-daily → STM新内容区
  → distill --from-stm → MEMORY.md(PINNED区之后)
  → distill(仅应急) → experiences.json

10. 配置参考

domains/_shared/evo-config.json:

{
  "consecutive_error_threshold": 2,
  "review_every_n_tasks": 3,
  "negative_feedback_threshold": 1,
  "memory_line_threshold": 150,
  "stm_distill_threshold": 20,
  "log_archive_days": 15
}

11. 禁止行为

• ❌ 不执行log记账
• ❌ 连续使用失败方法超过2次
• ❌ 忽略log输出的🔴/📊/⚠️/📋行动指令
• ❌ 数据类任务编撰/默认填充值（查不到→置空Null）
• ❌ log输出出现🔄Auto-Review后不确认是否成功执行
• ❌ 修改核心脚本后不同步到skill源码（双地一致是硬性要求）
• ❌ 用hash/英文无意义命名创建新城
• ❌ 在MEMORY.md中写入具体经验原文或版本号

12. FAQ

13. 版本历史

"好的Agent不是不犯错，而是同一个坑只踩一次——而且越踩越聪明。"