18 KiB
18 KiB
version, last-updated, status
| version | last-updated | status |
|---|---|---|
| 2.0 | 2026-03-09 | design |
06 — Agent 自我进化架构（V2 落地方案）
一、与 V1 设计的关系
V1 架构文档（docs/architecture/）已定义了完整的自我进化理论框架：
- OVERVIEW.md — 产品定位、三区隔离、七层循环
- COMPONENTS.md — Memory / Skill Creator / EvoMap / Soul.md 类型定义
- LOOP.md — 七层循环流程接口
- STORAGE.md — Markdown 存储方案
V2 的目标是将这些设计落地到本地完整体服务中，与 ChatEngine、ToolRegistry、ModelGateway 深度集成。
二、V2 进化引擎架构
┌──────────────────────────────────────────────────────────────────────┐
│ EvolutionEngine (进化引擎) │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ MemoryStore │ │ EvoMapEngine │ │ SoulManager │ │
│ │ 记忆系统 │ │ 进化图谱引擎 │ │ 灵魂文件管理 │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ┌──────▼─────────────────▼─────────────────▼──────────────────────┐ │
│ │ Integration Layer (集成层) │ │
│ │ │ │
│ │ ChatEngine ←──→ EvolutionEngine ←──→ ToolRegistry │ │
│ │ (对话时注入记忆) (执行后编码学习) (技能CRUD联动) │ │
│ │ │ │
│ │ ChannelGateway ←──→ EvolutionEngine │ │
│ │ (多渠道经验汇总) (跨渠道模式发现) │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Background Tasks (后台任务) │ │
│ │ 定期反思 · 记忆清理 · 技能优化 · EvoMap 更新 │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────┘
三、与 ChatEngine 集成
3.1 ChatPipeline 中的进化钩子
/**
* ChatPipeline 的 PreProcessor 注入进化上下文
*/
class EvolutionPreProcessor implements PipelineStage {
constructor(
private memoryStore: MemoryStore,
private evoMapEngine: EvoMapEngine,
private soulManager: SoulManager,
) {}
async process(context: ChatContext): Promise<ChatContext> {
const taskType = await this.classifyTask(context.userMessage);
// 1. 注入 Soul 上下文
const soulContext = await this.soulManager.getPromptContext();
context.systemPromptParts.push(soulContext);
// 2. 查询相关记忆
const memories = await this.memoryStore.recall({
taskType,
constraints: context.constraints,
limit: 5,
});
if (memories.length > 0) {
context.systemPromptParts.push(
`\n## 相关经验\n${memories
.map((m) => `- [${m.type}] ${m.summary} (置信度: ${m.confidence})`)
.join("\n")}`,
);
}
// 3. 查询 EvoMap 推荐方案
const decision = await this.evoMapEngine.getDecision(taskType);
if (decision && decision.confidence > 0.7) {
context.systemPromptParts.push(
`\n## 推荐方案\n根据历史经验，推荐: ${decision.bestAction} (成功率: ${decision.successRate})`,
);
}
return context;
}
}
/**
* ChatPipeline 的 PostProcessor 编码学习
*/
class EvolutionPostProcessor implements PipelineStage {
async process(context: ChatContext): Promise<ChatContext> {
// 异步执行，不阻塞响应。使用 queueMicrotask + try/catch 确保进化编码失败不影响用户体验
queueMicrotask(async () => {
try {
const outcome = this.extractOutcome(context);
if (outcome.success) {
await this.memoryStore.writeSuccess(outcome);
await this.evoMapEngine.reinforce(outcome);
await this.soulManager.recordSuccess(outcome);
} else {
await this.memoryStore.writeFailure(outcome);
await this.evoMapEngine.recordFailure(outcome);
await this.soulManager.recordFailure(outcome);
}
// 检查是否可以提取新技能
if (outcome.success && outcome.toolCalls.length >= 3) {
await this.tryExtractSkill(outcome);
}
} catch (error) {
// 进化失败不应影响用户体验，仅记录日志
log.warn("Evolution encoding failed:", error);
}
});
return context;
}
}
3.2 Agent Service 集成
当消息路由到远程 Agent Service（如 https://testagent.xspaceagi.com）时，进化引擎同样可以工作：
class RemoteAgentEvolutionAdapter {
/**
* 监听远程 Agent 的 SSE 流，从中提取学习数据
*/
observeRemoteSession(
sseStream: ReadableStream,
sessionContext: { taskType: string; userId: string; channelId?: string },
): void {
// 1. 收集 tool_call / text 事件
// 2. 判断最终结果（成功/失败）
// 3. 编码为本地记忆
// 4. 更新 EvoMap
// → 即使用远程 Agent，本地也能积累经验
}
}
四、MemoryStore V2
4.1 混合存储策略
MemoryStore
│
┌──────────────┼──────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Markdown │ │ SQLite │ │ sqlite-vec │
│ 记忆文件 │ │ 结构化索引 │ │ 向量检索 │
│ (人类可读) │ │ (快速查询) │ │ (语义搜索) │
└──────────────┘ └──────────────┘ └──────────────┘
- Markdown 文件：保留 V1 设计，存储成功/失败记忆的详细内容（人类可读）
- SQLite 索引表：快速查询（按 task/type/confidence/时间）
- sqlite-vec 向量：语义相似性检索（项目已依赖
sqlite-vec）
4.2 记忆索引表
CREATE TABLE memory_entries (
id TEXT PRIMARY KEY,
type TEXT NOT NULL, -- 'success' | 'failure' | 'insight'
task_type TEXT NOT NULL, -- 任务类型标签
summary TEXT NOT NULL, -- 简要描述
file_path TEXT NOT NULL, -- 对应 Markdown 文件路径
confidence REAL DEFAULT 0,
access_count INTEGER DEFAULT 0,
last_accessed INTEGER,
-- 上下文
environment TEXT, -- 环境描述
constraints TEXT, -- JSON 数组
-- 动作
tool_used TEXT,
command TEXT,
-- 结果
success INTEGER,
time_taken_ms INTEGER,
user_feedback TEXT, -- 'positive' | 'negative' | 'neutral'
-- 来源追溯
session_id TEXT,
channel_id TEXT,
created_at INTEGER NOT NULL,
updated_at INTEGER NOT NULL
);
CREATE INDEX idx_memory_task ON memory_entries(task_type);
CREATE INDEX idx_memory_type ON memory_entries(type);
CREATE INDEX idx_memory_confidence ON memory_entries(confidence DESC);
4.3 向量检索
class VectorMemorySearch {
/**
* 使用已有的 sqlite-vec 依赖进行语义搜索
*/
async semanticSearch(
query: string,
limit: number = 5,
): Promise<MemoryEntry[]> {
// 1. 使用本地嵌入模型或 Provider API 生成查询向量
const queryEmbedding = await this.generateEmbedding(query);
// 2. 使用 sqlite-vec 进行向量近似搜索
const results = db
.prepare(
`
SELECT m.*, distance
FROM memory_entries m
JOIN memory_vectors v ON m.id = v.memory_id
WHERE v.embedding MATCH ?
ORDER BY distance
LIMIT ?
`,
)
.all(queryEmbedding, limit);
return results;
}
/**
* 嵌入生成策略
* - 优先使用本地模型（Ollama text-embedding）
* - 回退到 Provider API（OpenAI text-embedding-3-small）
* - 最后回退到关键词 TF-IDF
*/
async generateEmbedding(text: string): Promise<Float32Array> {
// ...
}
}
五、EvoMap V2
5.1 与 ToolRegistry 联动
class EvoMapEngine {
private toolRegistry: ToolRegistry;
/**
* 当 Agent 使用工具成功时，更新该工具在 EvoMap 中的置信度
*/
async reinforceTool(toolId: string, outcome: ToolOutcome): Promise<void> {
const tool = this.toolRegistry.getToolById(toolId);
if (!tool) return;
const situation = `use-tool:${tool.name}`;
const currentNode = await this.getDecisionNode(situation);
if (outcome.success) {
currentNode.confidence = Math.min(currentNode.confidence + 0.02, 1.0);
currentNode.evidence.successCount++;
tool.metadata.successRate = this.recalculateSuccessRate(tool, true);
} else {
currentNode.confidence = Math.max(currentNode.confidence - 0.05, 0.0);
currentNode.evidence.failureCount++;
tool.metadata.successRate = this.recalculateSuccessRate(tool, false);
}
await this.saveDecisionNode(situation, currentNode);
await this.toolRegistry.updateToolMetadata(toolId, tool.metadata);
}
/**
* 为给定任务推荐最佳工具组合
*/
async recommendTools(taskType: string): Promise<ToolRecommendation[]> {
const decisionNode = await this.getDecisionNode(taskType);
return decisionNode.options
.filter((opt) => opt.confidence > 0.5)
.sort((a, b) => b.confidence - a.confidence)
.map((opt) => ({
toolId: opt.action,
confidence: opt.confidence,
expectedSuccessRate: opt.expectedSuccessRate,
reason: `${opt.evidence.successCount} 次成功 / ${opt.evidence.failureCount} 次失败`,
}));
}
}
5.2 跨 Channel 模式发现
/**
* 当同一个 Agent 被多个 Channel 使用时，
* 跨 Channel 的使用模式可以帮助发现更通用的最佳实践。
*/
class CrossChannelAnalyzer {
async analyzePatterns(): Promise<CrossChannelInsight[]> {
const memories = await this.memoryStore.query({
groupBy: "channel_id",
minEntries: 10,
});
const insights: CrossChannelInsight[] = [];
// 发现所有 Channel 共同的成功模式
const commonSuccessPatterns = this.findCommonPatterns(
memories.filter((m) => m.success),
);
for (const pattern of commonSuccessPatterns) {
if (pattern.coverage > 0.8) {
// 80% 以上 Channel 都验证过
insights.push({
type: "universal-pattern",
description: pattern.description,
confidence: pattern.confidence,
channels: pattern.channels,
});
}
}
return insights;
}
}
六、Soul.md V2
6.1 扩展 Soul 内容
---
name: soul
version: 42
last-updated: 2026-03-09
---
# Soul.md - Agent 自我认知
## 身份
我是 Qiming Agent，在 QimingClaw 桌面应用中运行的 AI 助手。
## 我的服务端点
- 本地推理: OpenAI (gpt-4o) · Anthropic (claude-sonnet-4)
- 远程 Agent: https://testagent.xspaceagi.com
## 我的 Channel
- 飞书 Bot: 服务 23 个用户, 回复 1,234 条消息
- 钉钉 Bot: 服务 12 个用户, 回复 567 条消息
## 核心原则
1. 用户目标优先
2. 优先使用验证过的工具和方法
3. 失败时尝试备选方案
4. 记录所有尝试以供学习
5. 【新增】同一任务跨 Channel 验证后可提升置信度
## 工具掌握度
| 工具 | 使用次数 | 成功率 | 最后使用 |
| ---------- | -------- | ------ | ---------- |
| parse-json | 234 | 98% | 2026-03-08 |
| install-uv | 89 | 95% | 2026-03-07 |
| web-search | 156 | 87% | 2026-03-09 |
## 最近学到的教训
- `2026-03-08`: 处理大文件时应分块读取，避免内存溢出
- `2026-03-07`: 飞书卡片消息对 Markdown 表格支持有限，改用 text 格式
## 统计数据
- 总任务数: 2,345
- 成功率: 91.2%
- 服务 Channel: 2 个
- 活跃用户: 35 人
6.2 SoulManager V2
class SoulManagerV2 {
private soulUpdater: SoulUpdater;
/**
* 生成注入到 ChatPipeline 的 Soul 上下文
* 根据当前对话的 Channel、用户、任务类型动态裁剪
*/
async getPromptContext(context: {
channelId?: string;
userId?: string;
taskType?: string;
}): Promise<string> {
const soul = await this.loadSoul();
let prompt = `## Agent 身份\n${soul.identity}\n`;
prompt += `\n## 核心原则\n${soul.principles.map((p, i) => `${i + 1}. ${p}`).join("\n")}\n`;
// 按任务类型注入相关技能
if (context.taskType) {
const relevantTools = soul.toolProficiency
.filter((t) => t.taskTypes.includes(context.taskType!))
.sort((a, b) => b.successRate - a.successRate)
.slice(0, 5);
if (relevantTools.length > 0) {
prompt += `\n## 推荐工具\n${relevantTools
.map((t) => `- ${t.name} (成功率: ${t.successRate}%)`)
.join("\n")}\n`;
}
}
// 按 Channel 注入特定经验
if (context.channelId) {
const channelLessons = soul.lessons
.filter((l) => l.channelId === context.channelId)
.slice(-3);
if (channelLessons.length > 0) {
prompt += `\n## 该渠道注意事项\n${channelLessons
.map((l) => `- ${l.lesson}`)
.join("\n")}\n`;
}
}
return prompt;
}
}
七、后台任务
class EvolutionScheduler {
/**
* 注册后台进化任务
*/
start(): void {
// 每日反思
setInterval(() => this.dailyReflection(), 24 * 60 * 60 * 1000);
// 每小时记忆清理（轻量）
setInterval(() => this.memoryCleanup(), 60 * 60 * 1000);
// 每 50 次任务触发技能优化
this.taskCounter.on("milestone:50", () => this.optimizeSkills());
}
async dailyReflection(): Promise<void> {
log.info("[Evolution] Starting daily reflection...");
// 1. 收集最近 24h 的记忆
const recentMemories = await this.memoryStore.getRecent(
24 * 60 * 60 * 1000,
);
// 2. 分析模式
const patterns = this.analyzePatterns(recentMemories);
// 3. 更新 EvoMap
for (const pattern of patterns.success) {
await this.evoMapEngine.reinforcePattern(pattern);
}
for (const pattern of patterns.failure) {
await this.evoMapEngine.recordAntiPattern(pattern);
}
// 4. 更新 Soul.md
const reflection = {
insights: patterns.insights,
newPrinciples: patterns.principles,
toolUpdates: patterns.toolUpdates,
};
await this.soulManager.updateReflection(reflection);
// 5. 跨 Channel 分析
const crossChannelInsights =
await this.crossChannelAnalyzer.analyzePatterns();
if (crossChannelInsights.length > 0) {
await this.soulManager.addInsights(crossChannelInsights);
}
log.info(
`[Evolution] Reflection complete: ${patterns.insights.length} insights`,
);
}
}
八、IPC 接口设计
// Memory
'evolution:memory:search' → MemoryEntry[]
'evolution:memory:recent' → MemoryEntry[]
'evolution:memory:stats' → MemoryStats
// EvoMap
'evolution:evomap:decision' → DecisionNode
'evolution:evomap:recommend' → ToolRecommendation[]
// Soul
'evolution:soul:get' → SoulContent
'evolution:soul:stats' → SoulStats
// Dashboard
'evolution:dashboard' → EvolutionDashboard
// Control
'evolution:reflect:trigger' → ReflectionResult
'evolution:reset' → { success: boolean }
'evolution:export' → { data: string } // JSON export
'evolution:import' → { success: boolean }