zclaw_openfang/docs/features/02-intelligence-layer/03-reflection-engine.md

自我反思引擎 (Reflection Engine)

分类: 智能层 优先级: P1 - 重要 成熟度: L4 - 生产 最后更新: 2026-03-16

---

一、功能概述

1.1 基本信息

自我反思引擎让 Agent 能够分析自己的行为模式，发现问题并提出改进建议，是实现 Agent 自我进化的关键组件。

属性	值
分类	智能层
优先级	P1
成熟度	L4
依赖	AgentMemory, LLMService

1.2 相关文件

文件	路径	用途
核心实现	desktop/src/lib/reflection-engine.ts	反思逻辑
LLM 服务	desktop/src/lib/llm-service.ts	LLM 调用
类型定义	desktop/src/types/reflection.ts	反思类型

---

二、设计初衷

2.1 问题背景

用户痛点:

1. Agent 重复犯同样的错误
2. 无法从历史交互中学习
3. Agent 行为缺乏透明度

系统缺失能力:

• 缺乏行为分析机制
• 缺乏自动改进能力
• 缺乏自我评估能力

为什么需要: 反思是人类智能的核心特征，让 Agent 具备反思能力是实现 L4 自演化的关键。

2.2 设计目标

1. 模式检测: 识别行为模式（任务积累、偏好增长等）
2. 问题发现: 自动发现问题（记忆过多、任务未清理等）
3. 建议生成: 提出可操作的改进建议
4. 身份变更: 提议修改 Agent 身份文件

2.3 触发机制

触发条件	描述
对话次数	每 N 次对话后（默认 5 次）
时间间隔	每 N 小时后（默认 24 小时）
手动触发	用户或系统主动调用

2.4 设计约束

• 性能约束: 反思不能阻塞主流程
• 成本约束: LLM 调用需要控制频率
• 质量约束: 建议必须可操作

---

三、技术设计

3.1 核心接口

interface ReflectionResult {
  timestamp: number;
  patterns: Pattern[];
  suggestions: Suggestion[];
  identityChanges?: IdentityChangeProposal[];
}

interface Pattern {
  type: PatternType;
  description: string;
  evidence: string[];
  severity: 'info' | 'warning' | 'critical';
}

interface Suggestion {
  type: SuggestionType;
  description: string;
  action: () => Promise<void>;
  priority: 'low' | 'medium' | 'high';
}

interface IdentityChangeProposal {
  file: 'SOUL.md' | 'AGENTS.md' | 'USER.md';
  changeType: 'add' | 'modify' | 'remove';
  content: string;
  reason: string;
}

3.2 反思流程

触发反思
    │
    ▼
收集数据
    │
    ├──► 会话历史 (最近 N 条)
    ├──► 记忆统计 (各类型数量)
    ├──► 任务状态 (待完成数量)
    └──► 行为指标 (响应时间、满意度)
    │
    ▼
模式检测
    │
    ├──► 规则检测 (快速)
    │       ├── 任务积累
    │       ├── 记忆过多
    │       ├── 偏好增长
    │       └── 经验积累
    │
    └──► LLM 分析 (深度)
            ├── 行为模式
            ├── 改进机会
            └── 身份建议
    │
    ▼
生成建议
    │
    ├──► 可执行动作
    ├──► 优先级排序
    └──► 身份变更提案
    │
    ▼
存储结果

3.3 模式检测规则

const PATTERN_RULES: PatternRule[] = [
  {
    type: 'task_accumulation',
    check: (stats) => stats.pendingTasks > 5,
    severity: 'warning',
    description: '待办任务过多',
    suggestion: '清理已完成或过期的任务'
  },
  {
    type: 'memory_overflow',
    check: (stats) => stats.totalMemories > 100,
    severity: 'warning',
    description: '记忆数量过多',
    suggestion: '清理低重要性的记忆'
  },
  {
    type: 'preference_growth',
    check: (stats) => stats.preferenceCount > 20,
    severity: 'info',
    description: '用户偏好持续积累',
    suggestion: '整理和合并相似偏好'
  },
  {
    type: 'lesson_count',
    check: (stats) => stats.lessonCount > 10,
    severity: 'info',
    description: '经验教训积累',
    suggestion: '回顾并应用这些经验'
  }
];

3.4 LLM 深度分析

async function deepReflect(context: ReflectionContext): Promise<ReflectionResult> {
  const prompt = `
作为一个 AI Agent，请分析以下行为数据并提出改进建议：

## 会话历史
${context.recentConversations}

## 记忆统计
- 事实: ${context.factCount}
- 偏好: ${context.preferenceCount}
- 经验: ${context.lessonCount}
- 任务: ${context.taskCount}

## 行为指标
- 平均响应时间: ${context.avgResponseTime}ms
- 用户满意度: ${context.satisfaction}

请输出：
1. 发现的行为模式
2. 改进建议
3. 身份变更提案（如有）
  `;

  return await llmService.reflect(prompt);
}

---

四、预期作用

4.1 用户价值

价值类型	描述
效率提升	Agent 自动优化行为
体验改善	持续改进的交互质量
信任增强	透明的自我评估

4.2 系统价值

价值类型	描述
架构收益	闭环的改进机制
可维护性	自动发现问题
可扩展性	可添加新的检测规则

4.3 成功指标

指标	基线	目标	当前
建议采纳率	0%	60%	45%
问题发现率	0%	80%	70%
改进效果	-	可衡量	符合预期

---

五、实际效果

5.1 已实现功能

• 规则模式检测
• LLM 深度分析
• 改进建议生成
• 身份变更提案
• 定时触发机制
• 对话计数触发
• 结果存储

5.2 测试覆盖

• 单元测试: 28 项 (heartbeat-reflection.test.ts)
• 集成测试: 完整流程测试
• 覆盖率: ~90%

5.3 已知问题

问题	严重程度	状态	计划解决
LLM 分析成本高	中	可选	-
建议有时不够具体	低	待改进	Q2

5.4 用户反馈

反思功能帮助 Agent 持续改进，但建议需要更具体可操作。

---

六、演化路线

6.1 短期计划（1-2 周）

• 优化建议的具体性
• 添加建议执行追踪

6.2 中期计划（1-2 月）

• 可视化反思报告
• 用户反馈循环

6.3 长期愿景

• 自主执行改进
• 跨 Agent 学习

---

七、头脑风暴笔记

7.1 待讨论问题

1. 是否应该自动执行某些改进建议？
2. 如何评估反思的质量？

7.2 创意想法

• 反思分享：Agent 之间共享反思结果
• 反思评分：用户对反思结果打分
• A/B 测试：对比反思前后的效果

7.3 风险与挑战

• 技术风险: LLM 分析的不确定性
• 成本风险: 频繁反思的成本
• 缓解措施: 规则优先，LLM 可选