--- version: 2.0 last-updated: 2026-03-09 status: 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 中的进化钩子 ```typescript /** * ChatPipeline 的 PreProcessor 注入进化上下文 */ class EvolutionPreProcessor implements PipelineStage { constructor( private memoryStore: MemoryStore, private evoMapEngine: EvoMapEngine, private soulManager: SoulManager, ) {} async process(context: ChatContext): Promise { 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 { // 异步执行，不阻塞响应。使用 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`）时，进化引擎同样可以工作： ```typescript 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 记忆索引表 ```sql 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 向量检索 ```typescript class VectorMemorySearch { /** * 使用已有的 sqlite-vec 依赖进行语义搜索 */ async semanticSearch( query: string, limit: number = 5, ): Promise { // 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 { // ... } } ``` --- ## 五、EvoMap V2 ### 5.1 与 ToolRegistry 联动 ```typescript class EvoMapEngine { private toolRegistry: ToolRegistry; /** * 当 Agent 使用工具成功时，更新该工具在 EvoMap 中的置信度 */ async reinforceTool(toolId: string, outcome: ToolOutcome): Promise { 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 { 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 模式发现 ```typescript /** * 当同一个 Agent 被多个 Channel 使用时， * 跨 Channel 的使用模式可以帮助发现更通用的最佳实践。 */ class CrossChannelAnalyzer { async analyzePatterns(): Promise { 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 内容 ```markdown --- 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 ```typescript class SoulManagerV2 { private soulUpdater: SoulUpdater; /** * 生成注入到 ChatPipeline 的 Soul 上下文 * 根据当前对话的 Channel、用户、任务类型动态裁剪 */ async getPromptContext(context: { channelId?: string; userId?: string; taskType?: string; }): Promise { 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; } } ``` --- ## 七、后台任务 ```typescript 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 { 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 接口设计 ```typescript // 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 } ``` --- ## 相关文档 - [V1 总览](../architecture/OVERVIEW.md) - [V1 核心组件](../architecture/COMPONENTS.md) - [V1 循环流程](../architecture/LOOP.md) - [V1 存储实现](../architecture/STORAGE.md) - [Skills & MCP](./03-SKILLS-MCP.md) - [会话管理](./04-SESSION-CHAT.md) - [Channel 接入](./05-CHANNELS.md)