From 6c64d704d797f68bcf9834a1d7e61cb5f162096d Mon Sep 17 00:00:00 2001 From: iven Date: Tue, 24 Mar 2026 00:38:31 +0800 Subject: [PATCH] docs: add self-evolution documentation and fix SOUL.md persistence - Create 01-identity-evolution.md: Identity system architecture (SOUL.md, USER.md, change proposals, version management) - Create 04-heartbeat-engine.md: Proactive behavior system (heartbeat config, alerts, proactivity levels) - Create 06-context-compaction.md: Context compression system (token management, summarization, information retention) - Update ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md: Add Phase 5 self-evolution UX roadmap - Fix AgentOnboardingWizard: Persist SOUL.md and USER.md after agent creation - Fix llm-service: Add Tauri kernel mode detection for memory system LLM calls - Fix kernel: Kernel config takes priority over agent's persisted model Co-Authored-By: Claude Opus 4.6 --- .../src/components/AgentOnboardingWizard.tsx | 29 ++ docs/ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md | 79 +++- .../01-identity-evolution.md | 220 ++++++++++ .../04-heartbeat-engine.md | 274 +++++++++++++ .../06-context-compaction.md | 383 ++++++++++++++++++ 5 files changed, 982 insertions(+), 3 deletions(-) create mode 100644 docs/features/02-intelligence-layer/01-identity-evolution.md create mode 100644 docs/features/02-intelligence-layer/04-heartbeat-engine.md create mode 100644 docs/features/02-intelligence-layer/06-context-compaction.md diff --git a/desktop/src/components/AgentOnboardingWizard.tsx b/desktop/src/components/AgentOnboardingWizard.tsx index 1055439..6c0d17d 100644 --- a/desktop/src/components/AgentOnboardingWizard.tsx +++ b/desktop/src/components/AgentOnboardingWizard.tsx @@ -25,6 +25,8 @@ import { EmojiPicker } from './ui/EmojiPicker'; import { PersonalitySelector } from './PersonalitySelector'; import { ScenarioTags } from './ScenarioTags'; import type { Clone } from '../store/agentStore'; +import { intelligenceClient } from '../lib/intelligence-client'; +import { generateSoulContent, generateUserContent } from '../lib/personality-presets'; // === Types === @@ -192,6 +194,33 @@ export function AgentOnboardingWizard({ isOpen, onClose, onSuccess }: AgentOnboa } if (clone) { + // Persist SOUL.md and USER.md to the identity system + try { + const soulContent = generateSoulContent({ + agentName: formData.agentName, + emoji: formData.emoji, + personality: formData.personality, + scenarios: formData.scenarios, + }); + + const userContent = generateUserContent({ + userName: formData.userName, + userRole: formData.userRole, + scenarios: formData.scenarios, + }); + + // Write SOUL.md (agent personality) + await intelligenceClient.identity.updateFile(clone.id, 'soul', soulContent); + + // Write USER.md (user profile) + await intelligenceClient.identity.updateFile(clone.id, 'user_profile', userContent); + + console.log('[Onboarding] SOUL.md and USER.md persisted for agent:', clone.id); + } catch (err) { + console.warn('[Onboarding] Failed to persist identity files:', err); + // Don't fail the whole onboarding if identity persistence fails + } + setSubmitStatus('success'); setTimeout(() => { onSuccess?.(clone); diff --git a/docs/ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md b/docs/ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md index 9534f24..caddcf2 100644 --- a/docs/ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md +++ b/docs/ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md @@ -1,12 +1,12 @@ # ZCLAW Agent 智能演化深度分析与实施方案 -> **文档日期**：2026-03-15 -> **定位**：`ZCLAW_NEXT_EVOLUTION_STRATEGY.md` 的**专题补充文档**，聚焦 Agent 智能层的深度差距分析与演化路径 +> **文档日期**：2026-03-24 +> **定位**：`ZCLAW_NEXT_EVOLUTION_STRATEGY.md` 的**专题补充文档**，聚焦 Agent 智能层的深度差距分析与演化路径 > **核心问题**：ZCLAW 当前的 Agent 只是"解决问题的帮手"，而 OpenClaw 的 Agent 是"可持续成长的助手"——如何弥合这一差距？ > > **后续升级路径**：[`ZCLAW_OPENVIKING_INTEGRATION_PLAN.md`](./ZCLAW_OPENVIKING_INTEGRATION_PLAN.md) 中规划了基于 **OpenViking**（火山引擎开源 AI 智能体上下文数据库）的升级方案，作为本文档 Phase 1 自建记忆系统的**后续增强**选项。当前优先按本文档方案实施。 -### 📊 实施进度（2026-03-15 更新） +### 📊 实施进度（2026-03-24 更新） | Phase | 状态 | 交付物 | 测试覆盖 | |-------|------|--------|---------| @@ -14,8 +14,18 @@ | **Phase 2: 上下文压缩** | ✅ 已完成 | `context-compactor.ts` + chatStore 集成 | 23 tests | | **Phase 3: 主动智能 + 自我反思** | ✅ 已完成 | `heartbeat-engine.ts`, `reflection-engine.ts` | 28 tests | | **Phase 4: 多 Agent 协作 + 技能生态** | ✅ 已完成 | `agent-swarm.ts`, `skill-discovery.ts` + chatStore 集成 | 43 tests | +| **Phase 5: 自我进化 UX** | 🚧 进行中 | 人格变更审批 UI、演化历史、反思→人格连接 | — | | **全量测试** | ✅ 317 passing | 13 test files | — | +### 📚 详细文档索引 + +| 文档 | 内容 | +|------|------| +| [01-identity-evolution.md](./features/02-intelligence-layer/01-identity-evolution.md) | 身份演化系统（SOUL.md、变更提案、版本管理） | +| [03-reflection-engine.md](./features/02-intelligence-layer/03-reflection-engine.md) | 反思引擎（行为分析、改进建议、人格提案） | +| [04-heartbeat-engine.md](./features/02-intelligence-layer/04-heartbeat-engine.md) | 心跳巡检（主动巡检、智能提醒、自主触发） | +| [06-context-compaction.md](./features/02-intelligence-layer/06-context-compaction.md) | 上下文压缩（Token 管理、智能摘要、信息保留） | + --- ## 一、问题诊断：为什么 ZCLAW 的 Agent "不够聪明" @@ -980,6 +990,69 @@ interface SkillDiscovery { --- +### 6.6 Phase 5：自我进化 UX 闭环（进行中） + +**目标**：让用户真正感受到 Agent 的"成长性"，连接反思→人格变更→用户审批的完整闭环 + +#### 6.6.1 核心问题 + +Phase 1-4 完成了底层能力，但用户体验存在断层： + +| 问题 | 现状 | 目标 | +|------|------|------| +| 人格选择不持久 | `generateSoulContent()` 只返回字符串 | SOUL.md 写入文件系统 | +| 反思不触发变更 | 反思结果只生成建议 | 自动生成人格变更提案 | +| 用户无法审批 | 无变更提案 UI | 展示差异，支持接受/拒绝 | +| 无演化历史 | 无版本管理 | 时间线 + 回滚能力 | + +#### 6.6.2 自我进化流程 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Self-Evolution Flow │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────┐ ┌───────────┐ ┌──────────────────┐ │ +│ │ 对话历史 │───▶│ 反思引擎 │───▶│ 人格变更提案 │ │ +│ │ │ │ │ │ (SOUL.md delta) │ │ +│ └──────────┘ └───────────┘ └────────┬─────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────┐ ┌───────────┐ ┌──────────────────┐ │ +│ │ 更新后的 │◀───│ 用户审批 │◀───│ 审批 UI │ │ +│ │ SOUL.md │ │ │ │ (变更对比) │ │ +│ └──────────┘ └───────────┘ └──────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────────┐ │ +│ │ 演化历史 │ │ +│ │ - 时间戳快照 │ │ +│ │ - 差异可视化 │ │ +│ │ - 回滚能力 │ │ +│ └──────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +#### 6.6.3 实现计划 + +| 优先级 | 任务 | 状态 | 说明 | +|--------|------|------|------| +| P0.1 | SOUL.md 持久化到 Onboarding | ✅ 完成 | AgentOnboardingWizard 调用 identity.updateFile() | +| P0.2 | 智能层文档更新 | ✅ 完成 | 身份演化、心跳、上下文压缩文档 | +| P1.1 | 人格变更提案 UI | 📋 待实现 | IdentityChangeProposal.tsx | +| P1.2 | 反思→人格连接 | 📋 待实现 | 反思引擎自动生成提案 | +| P1.3 | 演化历史回滚 | 📋 待实现 | PersonalityVersionControl.tsx | + +#### 6.6.4 预期用户体验 + +1. **创建 Agent 时**：向导选择人格 → 自动生成并持久化 SOUL.md +2. **使用过程中**：Agent 反思对话 → 发现"用户偏好简洁回复" → 生成 SOUL.md 变更提案 +3. **审批时**：用户看到 diff 视图 → 点击"接受"或"拒绝" +4. **回溯时**：查看演化历史时间线 → 选择历史版本 → 一键回滚 + +--- + ## 七、与架构层演化方案的整合 本文档的 Agent 智能演化与 `ZCLAW_NEXT_EVOLUTION_STRATEGY.md` 中的架构演化是**互补关系**： diff --git a/docs/features/02-intelligence-layer/01-identity-evolution.md b/docs/features/02-intelligence-layer/01-identity-evolution.md new file mode 100644 index 0000000..40fa020 --- /dev/null +++ b/docs/features/02-intelligence-layer/01-identity-evolution.md @@ -0,0 +1,220 @@ +# 身份演化系统 (Identity Evolution) + +> **成熟度**: L4 - 生产 +> **最后更新**: 2026-03-24 +> **负责人**: Intelligence Layer Team + +## 概述 + +身份演化系统是 ZCLAW 自我进化能力的核心，让 Agent 能够： +1. **定义人格** - 通过 SOUL.md 定义核心特质 +2. **演化人格** - 基于对话反思自动改进 +3. **版本管理** - 跟踪人格变更历史，支持回滚 + +--- + +## 核心概念 + +### 身份文件 (Identity Files) + +每个 Agent 有三个核心身份文件： + +| 文件 | 用途 | 示例内容 | +|------|------|----------| +| `soul` (SOUL.md) | Agent 人格定义 | 核心特质、沟通风格、专业领域 | +| `instructions` | 行为指令集 | 执行规则、约束条件 | +| `user_profile` (USER.md) | 用户画像 | 用户偏好、角色、场景 | + +### 身份变更提案 (Identity Change Proposal) + +```typescript +interface IdentityChangeProposal { + id: string; + agent_id: string; + file: 'soul' | 'instructions' | 'user_profile'; + current_content: string; + proposed_content: string; + diff: string; // Unified diff + reason: string; // AI 生成的变更原因 + status: 'pending' | 'approved' | 'rejected'; + created_at: string; +} +``` + +--- + +## 技术实现 + +### 核心文件 + +| 文件 | 用途 | +|------|------| +| `desktop/src/lib/intelligence-client.ts` | 前端身份 API 客户端 | +| `desktop/src/lib/intelligence-backend.ts` | 身份管理后端实现 | +| `desktop/src/lib/personality-presets.ts` | 人格预设和 SOUL.md 生成 | +| `desktop/src/components/AgentOnboardingWizard.tsx` | 引导向导，创建时持久化 SOUL.md | + +### API 接口 + +```typescript +// intelligence-client.ts +identity: { + // 获取 Agent 的所有身份文件 + get(agentId: string): Promise; + + // 读取单个文件内容 + readFile(agentId: string, file: string): Promise; + + // 更新文件内容（自动创建快照） + updateFile(agentId: string, file: string, content: string): Promise; + + // 构建完整的人格 Prompt + buildPrompt(agentId: string, memoryContext?: string): Promise; + + // 变更提案 + proposeChange(proposal: Omit): Promise; + getProposals(): Promise; + approveProposal(proposalId: string): Promise; + rejectProposal(proposalId: string): Promise; + + // 版本管理 + getSnapshots(agentId: string, limit?: number): Promise; + restoreSnapshot(agentId: string, snapshotId: string): Promise; +} +``` + +### SOUL.md 生成 + +```typescript +// personality-presets.ts +export function generateSoulContent(config: { + agentName: string; + emoji?: string; + personality?: string; // professional | friendly | creative | concise + scenarios?: string[]; // coding, writing, product, data, design... + communicationStyle?: string; +}): string; +``` + +生成的 SOUL.md 包含： +- 核心特质（基于人格预设） +- 沟通风格 +- 专业领域 +- 边界约束 +- 语气设定 + +--- + +## 数据流 + +### 创建时持久化 + +``` +AgentOnboardingWizard + │ + ├── createClone() → 创建 Agent + │ + ├── generateSoulContent() → 生成 SOUL.md + │ + ├── generateUserContent() → 生成 USER.md + │ + └── identity.updateFile() → 持久化到存储 +``` + +### 演化流程 + +``` +对话历史 + │ + ▼ +反思引擎 (Reflection Engine) + │ + ├── 分析对话模式 + │ + ├── 识别人格改进点 + │ + ▼ +identity.proposeChange() → 创建变更提案 + │ + ▼ +用户审批 UI + │ + ├── approveProposal() → 应用变更 + │ │ + │ └── 创建快照 + │ + └── rejectProposal() → 丢弃提案 +``` + +--- + +## 人格预设 + +| ID | 名称 | 特质 | +|----|------|------| +| `professional` | 专业严谨 | 严谨分析、准确执行、专业术语、结构化输出 | +| `friendly` | 友好亲切 | 热情回应、通俗易懂、主动关怀、耐心解答 | +| `creative` | 创意灵活 | 创新思维、多角度探索、灵活应变、突破常规 | +| `concise` | 简洁高效 | 直击要点、快速响应、高效执行、精炼表达 | + +--- + +## 使用场景 + +### 场景 1：首次创建 Agent + +1. 用户通过 AgentOnboardingWizard 创建 Agent +2. 选择人格预设和使用场景 +3. 系统自动生成 SOUL.md 和 USER.md +4. 持久化到身份存储 + +### 场景 2：基于反思的人格演化 + +1. Agent 进行多轮对话 +2. 反思引擎分析对话模式 +3. 发现用户偏好（如"不要那么啰嗦"） +4. 生成人格变更提案 +5. 用户审批后更新 SOUL.md + +### 场景 3：回滚到之前版本 + +1. 用户觉得新人格不合适 +2. 查看演化历史 +3. 选择之前的快照 +4. 一键恢复 + +--- + +## 集成点 + +| 组件 | 集成方式 | +|------|----------| +| **RightPanel** | 显示身份文件内容、变更提案 | +| **ReflectionEngine** | 触发人格变更提案 | +| **AutonomyManager** | 审批自主级别下的自动变更 | +| **ChatStore** | 使用 `buildPrompt()` 构建系统提示 | + +--- + +## 限制与未来改进 + +### 当前限制 + +1. **前端回滚 UI 未实现** - `getSnapshots()` 和 `restoreSnapshot()` API 存在但无 UI +2. **变更提案通知缺失** - 提案创建后无主动通知用户 +3. **Tauri 模式下文件存储** - 当前使用内存存储，重启后丢失 + +### 未来改进 + +1. **文件系统持久化** - 将身份文件写入 `~/.zclaw/agents/{agentId}/` +2. **变更提案通知** - 添加桌面通知或消息提示 +3. **人格版本对比** - 可视化 diff 显示变更内容 +4. **多人格切换** - 支持同一 Agent 保存多套人格配置 + +--- + +## 相关文档 + +- [00-agent-memory.md](./00-agent-memory.md) - 记忆系统 +- [03-reflection-engine.md](./03-reflection-engine.md) - 反思引擎 +- [05-autonomy-manager.md](./05-autonomy-manager.md) - 自主授权 diff --git a/docs/features/02-intelligence-layer/04-heartbeat-engine.md b/docs/features/02-intelligence-layer/04-heartbeat-engine.md new file mode 100644 index 0000000..b37463c --- /dev/null +++ b/docs/features/02-intelligence-layer/04-heartbeat-engine.md @@ -0,0 +1,274 @@ +# 心跳巡检引擎 (Heartbeat Engine) + +> **成熟度**: L4 - 生产 +> **最后更新**: 2026-03-24 +> **负责人**: Intelligence Layer Team + +## 概述 + +心跳巡检引擎是 ZCLAW 主动行为的核心，定期执行检查任务： +1. **主动巡检** - 定期检查系统状态、待办事项 +2. **智能提醒** - 根据上下文生成提醒 +3. **自主触发** - 在自主级别下自动执行操作 + +--- + +## 核心概念 + +### 心跳配置 (HeartbeatConfig) + +```typescript +interface HeartbeatConfig { + enabled: boolean; // 是否启用心跳 + interval_minutes: number; // 心跳间隔（分钟） + quiet_hours_start: string | null; // 静默时段开始（如 "22:00"） + quiet_hours_end: string | null; // 静默时段结束（如 "08:00"） + notify_channel: 'ui' | 'desktop' | 'all'; // 通知渠道 + proactivity_level: 'silent' | 'light' | 'standard' | 'autonomous'; // 主动级别 + max_alerts_per_tick: number; // 每次心跳最大提醒数 +} +``` + +### 心跳提醒 (HeartbeatAlert) + +```typescript +interface HeartbeatAlert { + title: string; // 提醒标题 + content: string; // 提醒内容 + urgency: 'low' | 'medium' | 'high'; // 紧急程度 + source: string; // 来源模块 + timestamp: string; // 时间戳 +} +``` + +### 心跳结果 (HeartbeatResult) + +```typescript +interface HeartbeatResult { + status: 'ok' | 'alert'; // 状态 + alerts: HeartbeatAlert[]; // 提醒列表 +} +``` + +--- + +## 主动级别 + +| 级别 | 行为 | +|------|------| +| `silent` | 仅记录日志，不发送通知 | +| `light` | 发送 UI 内通知 | +| `standard` | 发送桌面通知 | +| `autonomous` | 自主执行操作（需用户授权） | + +--- + +## 技术实现 + +### 核心文件 + +| 文件 | 用途 | +|------|------| +| `desktop/src/lib/intelligence-backend.ts` | 心跳后端实现 | +| `desktop/src/domains/intelligence/store.ts` | 状态管理 | +| `desktop/src/domains/intelligence/types.ts` | 类型定义 | + +### Store 接口 + +```typescript +interface IntelligenceStore { + // 状态 + heartbeatConfig: HeartbeatConfig | null; + heartbeatHistory: HeartbeatResult[]; + isHeartbeatRunning: boolean; + + // 操作 + initHeartbeat(agentId: string, config?: HeartbeatConfig): Promise; + startHeartbeat(agentId: string): Promise; + stopHeartbeat(agentId: string): Promise; + tickHeartbeat(agentId: string): Promise; +} +``` + +### 后端实现 + +```typescript +// intelligence-backend.ts +export const heartbeat = { + config: { + get: async (agentId: string): Promise => {...}, + update: async (agentId: string, config: Partial): Promise => {...}, + }, + + start: async (agentId: string): Promise => {...}, + stop: async (agentId: string): Promise => {...}, + tick: async (agentId: string): Promise => {...}, +}; +``` + +--- + +## 心跳巡检任务 + +每次心跳 `tick` 执行以下检查： + +### 1. 任务检查 +- 检查是否有待办任务 (type=task) +- 检查任务是否到期 +- 生成任务提醒 + +### 2. 上下文检查 +- 检查对话历史长度 +- 触发上下文压缩建议 +- 检查记忆提取机会 + +### 3. 反思检查 +- 检查距离上次反思的对话数 +- 触发反思引擎 +- 生成人格变更提案 + +### 4. 系统检查 +- 检查 Gateway 连接状态 +- 检查 API 配额 +- 检查更新可用性 + +--- + +## 使用场景 + +### 场景 1：定时任务提醒 + +``` +心跳 tick (每 30 分钟) + │ + ├── 检查任务记忆 + │ + ├── 发现到期任务："明天 10 点提醒我开会" + │ + └── 生成 HeartbeatAlert + title: "任务提醒" + content: "10:00 有会议" + urgency: "medium" +``` + +### 场景 2：反思触发 + +``` +心跳 tick + │ + ├── 检查对话数 >= 10 + │ + ├── 距离上次反思 > 1 小时 + │ + └── 触发 ReflectionEngine.reflect() + │ + └── 生成人格变更提案 +``` + +### 场景 3：自主级别下的自动操作 + +``` +心跳 tick (autonomous 级别) + │ + ├── 检查用户授权 + │ + ├── 发现可自动执行的任务 + │ + └── 执行操作（如：整理记忆、压缩上下文） +``` + +--- + +## 与其他组件的集成 + +``` +┌─────────────────────────────────────────────────────┐ +│ Heartbeat Engine │ +├─────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ Memory Store │◀────│ 任务检查 │ │ +│ └──────────────┘ └──────────────┘ │ +│ │ │ │ +│ │ ▼ │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ Reflection │◀────│ 反思触发 │ │ +│ │ Engine │ └──────────────┘ │ +│ └──────────────┘ │ +│ │ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────┐ │ +│ │ Identity Evolution │ │ +│ │ (人格变更提案) │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────┘ +``` + +--- + +## 配置示例 + +### 开发者模式 +```typescript +{ + enabled: true, + interval_minutes: 5, + quiet_hours_start: null, + quiet_hours_end: null, + notify_channel: 'ui', + proactivity_level: 'light', + max_alerts_per_tick: 3 +} +``` + +### 生产模式 +```typescript +{ + enabled: true, + interval_minutes: 30, + quiet_hours_start: "22:00", + quiet_hours_end: "08:00", + notify_channel: 'all', + proactivity_level: 'standard', + max_alerts_per_tick: 5 +} +``` + +### 自主模式 +```typescript +{ + enabled: true, + interval_minutes: 15, + quiet_hours_start: "23:00", + quiet_hours_end: "07:00", + notify_channel: 'desktop', + proactivity_level: 'autonomous', + max_alerts_per_tick: 10 +} +``` + +--- + +## 限制与未来改进 + +### 当前限制 + +1. **前端定时器依赖** - 心跳依赖页面打开，后台时不运行 +2. **无持久化调度** - 重启后心跳不自动恢复 +3. **静默时段实现不完整** - 时区处理可能有问题 + +### 未来改进 + +1. **后台心跳** - 使用 Service Worker 或 Tauri 后台任务 +2. **智能间隔调整** - 根据用户活跃度动态调整间隔 +3. **云端同步** - 多设备心跳状态同步 + +--- + +## 相关文档 + +- [03-reflection-engine.md](./03-reflection-engine.md) - 反思引擎 +- [05-autonomy-manager.md](./05-autonomy-manager.md) - 自主授权 +- [01-identity-evolution.md](./01-identity-evolution.md) - 身份演化 diff --git a/docs/features/02-intelligence-layer/06-context-compaction.md b/docs/features/02-intelligence-layer/06-context-compaction.md new file mode 100644 index 0000000..3931b1a --- /dev/null +++ b/docs/features/02-intelligence-layer/06-context-compaction.md @@ -0,0 +1,383 @@ +# 上下文压缩系统 (Context Compaction) + +> **成熟度**: L4 - 生产 +> **最后更新**: 2026-03-24 +> **负责人**: Intelligence Layer Team + +## 概述 + +上下文压缩系统解决了无限对话长度的核心挑战： +1. **Token 限制管理** - 监控对话长度，防止超出模型限制 +2. **智能摘要** - 将历史对话压缩为简洁摘要 +3. **信息保留** - 确保关键决策、偏好、上下文不丢失 +4. **无感知压缩** - 用户无需手动管理对话历史 + +--- + +## 核心概念 + +### 压缩配置 (CompactionConfig) + +```typescript +interface CompactionConfig { + soft_threshold_tokens: number; // 软阈值（触发压缩建议） + hard_threshold_tokens: number; // 硬阈值（强制压缩） + reserve_tokens: number; // 为响应预留的 token + memory_flush_enabled: boolean; // 是否在压缩前刷新记忆 + keep_recent_messages: number; // 保留的最近消息数 + summary_max_tokens: number; // 摘要最大 token 数 + use_llm: boolean; // 是否使用 LLM 生成摘要 + llm_fallback_to_rules: boolean; // LLM 失败时回退到规则 +} +``` + +### 压缩检查 (CompactionCheck) + +```typescript +interface CompactionCheck { + should_compact: boolean; // 是否需要压缩 + current_tokens: number; // 当前 token 数 + threshold: number; // 触发阈值 + urgency: 'none' | 'soft' | 'hard'; // 紧急程度 +} +``` + +### 压缩结果 (CompactionResult) + +```typescript +interface CompactionResult { + compacted_messages: CompactableMessage[]; // 压缩后的消息列表 + summary: string; // 生成的摘要 + original_count: number; // 原始消息数 + retained_count: number; // 保留消息数 + flushed_memories: number; // 刷新的记忆数 + tokens_before_compaction: number; // 压缩前 token + tokens_after_compaction: number; // 压缩后 token +} +``` + +--- + +## 压缩流程 + +``` +┌─────────────────────────────────────────────────────────┐ +│ Context Compaction │ +├─────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ │ +│ │ 新消息到达 │ │ +│ └──────┬───────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────┐ soft_threshold ┌─────────┐ │ +│ │ Token 计算 │─────────────────────────▶│ 建议压缩 │ │ +│ └──────┬───────┘ └─────────┘ │ +│ │ │ +│ │ hard_threshold │ +│ ▼ │ +│ ┌──────────────┐ │ +│ │ 强制压缩 │ │ +│ └──────┬───────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────┐ │ +│ │ 1. 保留最近 N 条消息 │ │ +│ │ 2. 对旧消息生成摘要 │ │ +│ │ 3. 可选：提取记忆到 Memory Store │ │ +│ │ 4. 替换旧消息为摘要 │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────┐ │ +│ │ 压缩完成 │ │ +│ └──────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────┘ +``` + +--- + +## Token 估算算法 + +### CJK + 英文混合估算 + +```rust +// Rust 实现 (compactor.rs) +pub fn estimate_tokens(text: &str) -> usize { + let mut tokens: f64 = 0.0; + for char in text.chars() { + let code = char as u32; + if code >= 0x4E00 && code <= 0x9FFF { + // CJK 基本汉字 → 1.5 tokens + tokens += 1.5; + } else if code >= 0x3400 && code <= 0x4DBF { + // CJK 扩展 A → 1.5 tokens + tokens += 1.5; + } else if code >= 0x3000 && code <= 0x303F { + // CJK 标点 → 1.0 token + tokens += 1.0; + } else if char == ' ' || char == '\n' || char == '\t' { + // 空白字符 → 0.25 token + tokens += 0.25; + } else { + // ASCII 字符 → ~0.3 token (4 chars ≈ 1 token) + tokens += 0.3; + } + } + tokens.ceil() as usize +} +``` + +**设计原则**：宁可高估，不可低估。高估会提前触发压缩，但不会导致 API 错误。 + +--- + +## 摘要生成 + +### 规则摘要（当前实现） + +```rust +fn generate_summary(&self, messages: &[CompactableMessage]) -> String { + let mut sections: Vec = vec!["[以下是之前对话的摘要]".to_string()]; + + // 1. 提取讨论主题 + let topics = extract_topics(user_messages); + sections.push(format!("讨论主题: {}", topics.join("; "))); + + // 2. 提取关键结论 + let conclusions = extract_conclusions(assistant_messages); + sections.push(format!("关键结论:\n- {}", conclusions.join("\n- "))); + + // 3. 提取技术上下文（代码片段等） + let tech_context = extract_technical_context(messages); + sections.push(format!("技术上下文: {}", tech_context.join(", "))); + + // 4. 统计信息 + sections.push(format!("(已压缩 {} 条消息)", messages.len())); + + sections.join("\n") +} +``` + +### 摘要示例 + +``` +[以下是之前对话的摘要] +讨论主题: 如何在 Rust 中实现异步 HTTP 服务器; 性能优化建议 +关键结论: +- 使用 tokio::run 作为异步运行时 +- 考虑使用连接池减少开销 +- 建议启用 HTTP/2 支持提升性能 +技术上下文: 代码片段 (rust), 代码片段 (toml) +(已压缩 24 条消息，其中用户 12 条，助手 12 条) +``` + +--- + +## 技术实现 + +### 核心文件 + +| 文件 | 用途 | +|------|------| +| `desktop/src-tauri/src/intelligence/compactor.rs` | Rust 压缩核心实现 | +| `desktop/src/lib/intelligence-backend.ts` | TypeScript API 封装 | +| `desktop/src/domains/intelligence/store.ts` | 状态管理 | + +### Tauri Commands + +```rust +#[tauri::command] +pub fn compactor_estimate_tokens(text: String) -> usize; + +#[tauri::command] +pub fn compactor_estimate_messages_tokens(messages: Vec) -> usize; + +#[tauri::command] +pub fn compactor_check_threshold( + messages: Vec, + config: Option, +) -> CompactionCheck; + +#[tauri::command] +pub fn compactor_compact( + messages: Vec, + agent_id: String, + conversation_id: Option, + config: Option, +) -> CompactionResult; +``` + +### 前端 API + +```typescript +// intelligence-backend.ts +export const compactor = { + estimateTokens(text: string): Promise; + estimateMessagesTokens(messages: CompactableMessage[]): Promise; + checkThreshold(messages: CompactableMessage[], config?: CompactionConfig): Promise; + compact(messages: CompactableMessage[], agentId: string, conversationId?: string, config?: CompactionConfig): Promise; +}; +``` + +--- + +## 使用场景 + +### 场景 1：自动压缩 + +```typescript +// 在发送消息前检查 +const check = await intelligence.compactor.checkThreshold(messages); + +if (check.urgency === 'hard') { + // 强制压缩 + const result = await intelligence.compactor.compact(messages, agentId); + setMessages(result.compacted_messages); + console.log(`压缩完成: ${result.tokens_before_compaction} → ${result.tokens_after_compaction} tokens`); +} else if (check.urgency === 'soft') { + // 建议用户压缩或等待 + showCompactionSuggestion(); +} +``` + +### 场景 2：手动压缩 + +```typescript +// 用户主动触发压缩 +const result = await intelligence.compactor.compact( + messages, + agentId, + conversationId, + { + soft_threshold_tokens: 12000, + keep_recent_messages: 10, + } +); +``` + +### 场景 3：压缩 + 记忆提取 + +```typescript +// 压缩前先提取记忆 +if (config.memory_flush_enabled) { + const memories = await extractMemoriesFromOldMessages(oldMessages); + for (const memory of memories) { + await intelligence.memory.store(memory); + } +} + +// 然后执行压缩 +const result = await intelligence.compactor.compact(messages, agentId); +``` + +--- + +## 与其他组件的集成 + +``` +┌─────────────────────────────────────────────────────┐ +│ Context Compactor │ +├─────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ ChatStore │────▶│ Token 检查 │ │ +│ └──────────────┘ └──────────────┘ │ +│ │ │ │ +│ │ ▼ │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ Memory Store │◀────│ 记忆提取 │ │ +│ └──────────────┘ └──────────────┘ │ +│ │ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────┐ │ +│ │ 摘要生成 │ │ +│ │ - 规则提取（当前） │ │ +│ │ - LLM 摘要（可选） │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────┐ │ +│ │ 压缩后消息 │ │ +│ └──────────────┘ │ +│ │ +└─────────────────────────────────────────────────────┘ +``` + +--- + +## 配置示例 + +### 开发模式（频繁压缩测试） + +```typescript +{ + soft_threshold_tokens: 5000, + hard_threshold_tokens: 8000, + reserve_tokens: 2000, + memory_flush_enabled: true, + keep_recent_messages: 4, + summary_max_tokens: 400, + use_llm: false, + llm_fallback_to_rules: true, +} +``` + +### 生产模式（较长上下文） + +```typescript +{ + soft_threshold_tokens: 15000, + hard_threshold_tokens: 20000, + reserve_tokens: 4000, + memory_flush_enabled: true, + keep_recent_messages: 6, + summary_max_tokens: 800, + use_llm: false, + llm_fallback_to_rules: true, +} +``` + +### 大上下文模式（32K 模型） + +```typescript +{ + soft_threshold_tokens: 25000, + hard_threshold_tokens: 30000, + reserve_tokens: 6000, + memory_flush_enabled: true, + keep_recent_messages: 10, + summary_max_tokens: 1200, + use_llm: true, // 启用 LLM 摘要 + llm_fallback_to_rules: true, +} +``` + +--- + +## 限制与未来改进 + +### 当前限制 + +1. **规则摘要质量有限** - 无法理解复杂语义，可能丢失重要细节 +2. **无增量压缩** - 每次都重新处理所有旧消息 +3. **无压缩预览** - 用户无法在压缩前预览摘要内容 +4. **LLM 摘要未实现** - `use_llm: true` 配置存在但未实际使用 + +### 未来改进 + +1. **LLM 增强摘要** - 使用轻量模型生成高质量摘要 +2. **增量压缩** - 只处理新增的消息，保留之前的摘要 +3. **压缩预览** - 显示摘要内容，允许用户编辑 +4. **智能保留** - 基于重要性的消息保留策略 +5. **压缩历史** - 保存压缩记录，支持回溯 + +--- + +## 相关文档 + +- [00-agent-memory.md](./00-agent-memory.md) - 记忆系统 +- [03-reflection-engine.md](./03-reflection-engine.md) - 反思引擎 +- [04-heartbeat-engine.md](./04-heartbeat-engine.md) - 心跳巡检