adfd7024df
- Restructure §8 from "文档沉淀规则" to "文档管理规则" with 4 subsections - Add docs/ structure with features/ and knowledge-base/ directories - Add feature documentation template with 7 sections (概述/设计初衷/技术设计/预期作用/实际效果/演化路线/头脑风暴) - Add feature update trigger matrix (新增/修改/完成/问题/反馈) - Add documentation quality checklist - Add §16
302 lines
6.7 KiB
Markdown
302 lines
6.7 KiB
Markdown
# 自我反思引擎 (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 核心接口
|
||
|
||
```typescript
|
||
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 模式检测规则
|
||
|
||
```typescript
|
||
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 深度分析
|
||
|
||
```typescript
|
||
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 已实现功能
|
||
|
||
- [x] 规则模式检测
|
||
- [x] LLM 深度分析
|
||
- [x] 改进建议生成
|
||
- [x] 身份变更提案
|
||
- [x] 定时触发机制
|
||
- [x] 对话计数触发
|
||
- [x] 结果存储
|
||
|
||
### 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 可选
|