zclaw_openfang/docs/ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md

ZCLAW Agent 智能演化深度分析与实施方案

文档日期：2026-03-24 定位：ZCLAW_NEXT_EVOLUTION_STRATEGY.md 的专题补充文档，聚焦 Agent 智能层的深度差距分析与演化路径 核心问题：ZCLAW 当前的 Agent 只是"解决问题的帮手"，而 ZCLAW 的 Agent 是"可持续成长的助手"——如何弥合这一差距？

后续升级路径：ZCLAW_OPENVIKING_INTEGRATION_PLAN.md 中规划了基于 OpenViking（火山引擎开源 AI 智能体上下文数据库）的升级方案，作为本文档 Phase 1 自建记忆系统的后续增强选项。当前优先按本文档方案实施。

📊 实施进度（2026-03-24 更新）

Phase	状态	交付物	测试覆盖
Phase 1: 持久记忆 + 身份演化	✅ 已完成	agent-memory.ts, agent-identity.ts, memory-extractor.ts, MemoryPanel.tsx	42 tests
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	身份演化系统（SOUL.md、变更提案、版本管理）
03-reflection-engine.md	反思引擎（行为分析、改进建议、人格提案）
04-heartbeat-engine.md	心跳巡检（主动巡检、智能提醒、自主触发）
06-context-compaction.md	上下文压缩（Token 管理、智能摘要、信息保留）

---

一、问题诊断：为什么 ZCLAW 的 Agent "不够聪明"

1.1 现象描述

维度	ZCLAW Agent	ZCLAW Agent 当前状态
记忆	跨会话持久记忆，自动沉淀重要信息	每次对话从零开始，无持久记忆
主动性	Heartbeat 定时巡检 + Cron 精确调度	纯被动响应，用户不问就不动
人格连续性	SOUL.md / AGENTS.md / MEMORY.md 持续演化	静态配置文件，Agent 不能自我更新
上下文管理	自动压缩 + 记忆冲刷，无限对话不丢关键信息	上下文窗口满即丢失，无压缩机制
技能成长	100+ 社区 Skills，Agent 自主发现和安装	技能系统存在但 Agent 无法自主扩展
多 Agent 协作	单 Agent 深度模式	有 Clone 管理但无协作编排
自我反思	对话后自动总结、学习、调整行为	无自我反思和行为调整机制

1.2 根因分析

ZCLAW Agent 的"不聪明"不是模型能力问题，而是Agent 基础设施缺失：

ZCLAW Agent = LLM + 持久记忆 + 主动调度 + 自我演化的身份 + 技能生态 + 上下文治理
ZCLAW Agent   = LLM + 临时会话 + 静态配置
                      ↑ 差距在这里：缺少让 Agent 持续成长的基础设施

具体缺失的基础设施层：

1. Memory Layer（记忆层） — 完全缺失
2. Proactive Engine（主动引擎） — 完全缺失
3. Identity Evolution（身份演化） — 有静态配置，无动态演化
4. Context Management（上下文治理） — 只有基础流式，无压缩/冲刷
5. Skill Discovery（技能发现） — 有列表，无自主发现与安装
6. Reflection Loop（反思循环） — 完全缺失

---

二、竞品 Agent 智能体系深度解剖

2.1 ZCLAW：最完整的"可成长 Agent"参考

2.1.1 两层记忆系统

ZCLAW 的记忆设计是其核心竞争力：

Layer 1：Daily Logs（短期日记）

memory/
├── 2026-03-01.md    # 当日事件、任务、决策
├── 2026-03-02.md
├── 2026-03-03.md
└── 2026-03-04.md

• Agent 自动写入：完成的任务、做出的决策、学到的信息、遇到的错误
• 时间戳式积累，形成 Agent 的"工作日志"

Layer 2：MEMORY.md（长期策展记忆）

• Agent 自己决定什么值得永久记住
• 用户偏好、项目上下文、关键决策、经验教训
• 只有主会话才能写入，避免并发冲突

核心创新：压缩前自动记忆冲刷（Memory Flush Before Compaction）

1. 上下文窗口接近软阈值（默认 20000 tokens）
2. 触发静默记忆冲刷（用户不可见的 Agent 内部操作）
3. Agent 审查即将被压缩的对话，提取重要信息写入持久记忆
4. 压缩执行，旧对话被摘要替代
5. 重要信息已安全保存在 memory/ 和 MEMORY.md 中

这意味着：Agent 可以进行无限长的对话而不丢失关键信息。

记忆工具

• memory_search — 语义向量搜索 + SQLite FTS5 关键词匹配
• memory_get — 精确文件读取

2.1.2 Heartbeat 引擎（主动心跳）

ZCLAW 的心跳系统让 Agent 从"被动回应者"变为"主动助手"：

# HEARTBEAT.md（用户可编辑的巡检清单）
- 检查邮件是否有紧急消息
- 检查日历未来 2 小时内的事件
- 如果后台任务完成，总结结果
- 如果空闲超过 8 小时，发送简短问候

工作机制：

• 主会话中以可配置间隔运行（默认 30 分钟）
• 读取 HEARTBEAT.md 中的检查清单
• 批量处理所有检查项
• 无需关注时返回 HEARTBEAT_OK（静默，不打扰用户）
• 有需要关注的事项时通过配置的渠道通知用户

2.1.3 Cron 精确调度

与 Heartbeat 互补：

• Heartbeat 擅长：批量巡检、上下文感知、高效低成本
• Cron 擅长：精确时间点、隔离会话、可用不同模型/思维级别

// 每个 Cron 任务运行在独立的 cron:<jobId> 会话中
// 不污染主会话历史

2.1.4 工作区身份文件（Agent 的人格层）

SOUL.md      — Agent 是谁（身份定义）
AGENTS.md    — Agent 如何行为（操作指令）
USER.md      — 用户是谁（用户画像）
IDENTITY.md  — 对外身份标识
TOOLS.md     — 可用工具清单
HEARTBEAT.md — 主动巡检指令
BOOTSTRAP.md — 初始化引导
MEMORY.md    — 持久记忆库

关键设计：这些文件Agent 自己可以读取和修改。Agent 可以：

• 更新自己的 SOUL.md（自我认知演化）
• 更新 MEMORY.md（知识积累）
• 读取 USER.md（理解用户偏好）

这使得 Agent 的人格和知识是可版本控制、可审查、可回滚的：

git commit -m "agent learned about project X"
git diff  # 查看 Agent 的人格变化

2.1.5 会话持久化与压缩

• JSONL + 树结构：id/parentId 链接，支持对话分支
• 崩溃安全：append-only，最多丢一行
• 可重放：顺序读取即可重放全部交互
• 智能压缩：
  • 上下文窗口守卫持续监控 token 数
  • 软阈值触发 → 记忆冲刷 → 压缩 → 新分支
  • compaction-safeguard 扩展：自适应 token 预算
  • context-pruning 扩展：基于 TTL 的工具结果修剪

2.2 NanoClaw：轻量级但有效的记忆与协作

2.2.1 SQLite 持久记忆

• 消息、会话、状态全部存 SQLite
• 重启后完整恢复
• 完全可查询

2.2.2 Per-Group CLAUDE.md

• 每个聊天群组有独立的 CLAUDE.md 记忆文件
• Agent 在不同上下文中表现不同的"人格"
• 隔离但灵活

2.2.3 Agent Swarms（多 Agent 协作）

• 第一个支持 Agent Swarms 的个人 AI 助手
• 多个专业化 Agent 协作处理复杂任务
• 每个 Agent 有自己的专长和上下文

2.2.4 容器级隔离

• Agent 运行在独立 Linux 容器中
• 文件系统隔离（不是权限检查）
• 安全边界清晰

2.3 ZeroClaw：高效的记忆与模块化

2.3.1 SQLite + 向量搜索

• 对话历史和上下文信息存储在 SQLite
• 向量搜索实现语义记忆召回
• 高效的长期记忆检索

2.3.2 Tool-Driven Research Phase

• 响应前先通过工具收集信息
• Web 查询、API 调用等
• "先调研，再回答"的智能模式

2.3.3 Trait-Based 可替换架构

• Provider / Channel / Memory / Tools 全部可替换
• 记忆后端可以独立演化
• 适合作为架构参考

---

三、ZCLAW Agent 智能差距量化评估

3.1 Agent 智能成熟度模型

定义 5 个成熟度级别：

级别	定义	特征
L0 — 无状态响应	每次对话从零开始	纯 LLM 包装器
L1 — 会话感知	单次会话内有上下文	能在一次对话中保持连贯
L2 — 持久记忆	跨会话记住关键信息	记住用户偏好、项目上下文
L3 — 主动智能	不需要用户触发就能行动	Heartbeat、Cron、主动通知
L4 — 自我演化	能修改自己的行为和知识	自我反思、技能发现、人格迭代

3.2 各系统评级

能力维度	ZCLAW	NanoClaw	ZeroClaw	ZCLAW 当前
短期记忆（会话内）	L1 ✅	L1 ✅	L1 ✅	L1 ✅
长期记忆（跨会话）	L2 ✅	L2 ✅	L2 ✅	L0 ❌
记忆检索（语义搜索）	L2+ ✅	L2 ✅	L2+ ✅	L0 ❌
上下文压缩	L2 ✅	L1	L1	L0 ❌
压缩前记忆冲刷	L2+ ✅	❌	❌	L0 ❌
主动巡检（Heartbeat）	L3 ✅	❌	❌	L0 ❌
定时任务（Cron）	L3 ✅	L3 ✅	❌	L0 ❌
Agent 自修改身份文件	L4 ✅	L2	L1	L0 ❌
自动记忆策展	L4 ✅	L2	L1	L0 ❌
技能自主发现/安装	L4 ✅	L2	L1	L0 ❌
多 Agent 协作	L2	L3 ✅	L1	L0 ❌
自我反思循环	L4 ✅	L2	L1	L0 ❌

3.3 差距总结

ZCLAW 当前处于 L1（会话感知）级别，而 ZCLAW 已经达到 L4（自我演化）级别。

差距不是线性的——每一级的价值都是指数增长：

• L0→L1：用户体验从"不可用"到"可用"
• L1→L2：用户体验从"工具"到"助手"（最关键的跃迁）
• L2→L3：用户体验从"助手"到"伙伴"
• L3→L4：用户体验从"伙伴"到"自主智能体"

---

四、从竞品中应吸收的核心能力清单

4.1 必须吸收（P0 — 决定产品存活）

能力	来源	价值	实现复杂度
持久记忆系统	ZCLAW + ZeroClaw	从 L1 跃迁到 L2 的核心	中
上下文压缩 + 记忆冲刷	ZCLAW	无限对话不丢信息	中
工作区身份文件动态化	ZCLAW	Agent 人格可演化	低
记忆搜索（语义 + 关键词）	ZCLAW + ZeroClaw	精确召回历史信息	中到高

4.2 强烈建议吸收（P1 — 形成差异化竞争力）

能力	来源	价值	实现复杂度
Heartbeat 主动巡检	ZCLAW	从 L2 跃迁到 L3	中
Cron 定时任务	ZCLAW + NanoClaw	精确调度能力	低到中
Agent 自我反思循环	ZCLAW	行为持续优化	中
多 Agent 协作框架	NanoClaw	复杂任务分工	高

4.3 可选吸收（P2 — 生态化扩展）

能力	来源	价值	实现复杂度
技能市场与自主安装	ZCLAW	能力无限扩展	高
容器级执行隔离	NanoClaw	安全执行环境	高
向量记忆后端可替换	ZeroClaw	灵活的记忆架构	中

4.4 不吸收

能力	原因
ZCLAW 的纯文件系统记忆	ZCLAW 桌面端更适合 SQLite/IndexedDB + 文件混合方案
NanoClaw 的纯 fork 定制模式	ZCLAW 需要平台化扩展
ZeroClaw 的 Rust 重写	当前阶段不值得重写运行时

---

五、Agent 智能演化专题头脑风暴方案

5.1 会议目标

围绕"如何让 ZCLAW Agent 从问题解决者演化为持续成长的智能助手"形成共识，输出：

1. Agent 智能演化的优先级排序
2. 记忆系统的技术方案选型
3. 主动智能的产品边界定义
4. 90 天 Agent 智能演化路线图

5.2 会前准备

必读材料：

• 本文档（重点阅读第二、三章）
• docs/ZCLAW_NEXT_EVOLUTION_STRATEGY.md（架构层全景）
• 当前 config/SOUL.md、config/AGENTS.md（了解现状）

会前思考题（每位参会者提前书面回答）：

1. 用户视角：你作为用户，最希望 ZCLAW 记住你的什么？
2. 产品视角：Agent 主动推送消息，用户的接受边界在哪里？
3. 技术视角：记忆数据存在哪里最合理？文件系统、SQLite、还是云端？
4. 安全视角：Agent 能自动修改自己的配置文件，风险可控吗？
5. 差异化视角：相比 ZCLAW，ZCLAW 的 Agent 智能应该在哪个方向上做得更好？

5.3 会议议程（3 小时）

第一阶段：差距共识（30 分钟）

目标：团队对"我们的 Agent 差在哪里"形成统一认知

• 演示对比：ZCLAW Agent 的记忆/主动行为 vs ZCLAW Agent 的当前表现
• 走读本文档的 L0-L4 成熟度评估
• 确认：团队是否认同 L1→L2 是当前最关键的跃迁？

产出：差距确认清单 + 目标级别共识

第二阶段：记忆系统方案讨论（45 分钟）

目标：确定 ZCLAW 记忆系统的技术方案

讨论主题：

A. 记忆存储方案选型

方案	优点	缺点	适合场景
纯文件系统（ZCLAW 风格）	可审查、可 git、透明	搜索性能差、并发控制弱	单用户/开发者
SQLite + FTS5	查询强、结构化、桌面原生	不可直接 git	桌面产品
SQLite + 向量搜索（ZeroClaw 风格）	语义召回强	需要嵌入模型	高级记忆
混合方案：SQLite + Markdown 导出	兼顾查询和可审查性	同步复杂度	推荐方案

B. 记忆分层设计

┌─────────────────────────────────────────────────┐
│  L3: 身份记忆（SOUL / AGENTS / USER 演化轨迹）   │  ← 最稳定，变更需审批
├─────────────────────────────────────────────────┤
│  L2: 长期记忆（用户偏好、项目知识、经验教训）       │  ← Agent 自动策展
├─────────────────────────────────────────────────┤
│  L1: 工作记忆（当前任务上下文、临时笔记）           │  ← 会话级，可丢弃
├─────────────────────────────────────────────────┤
│  L0: 瞬时记忆（当前对话上下文窗口）                │  ← 纯 LLM 上下文
└─────────────────────────────────────────────────┘

C. 记忆操作接口

需要定义的最小记忆 API：

• memory.save(content, tags, importance) — 保存记忆
• memory.search(query, filters) — 语义搜索
• memory.get(id) — 精确获取
• memory.forget(id) — 遗忘（用户可手动触发）
• memory.flush(context) — 上下文压缩前的记忆冲刷
• memory.curate() — 定期策展（合并重复、提升重要记忆）

第三阶段：主动智能边界讨论（45 分钟）

目标：定义 ZCLAW Agent 主动行为的产品边界

讨论主题：

A. Heartbeat 产品化

核心问题：

• 心跳间隔多少合适？（ZCLAW 默认 30 分钟）
• 哪些检查项是默认启用的？
• 如何避免"通知骚扰"？
• 桌面端的心跳应该通过什么渠道通知？（系统通知？应用内通知？飞书消息？）

B. Cron 任务系统

核心问题：

• 现有 scheduledTasks API 是否足够？
• 任务执行的隔离级别？（新会话 vs 主会话？）
• 任务失败的重试和告警策略？

C. 主动推送的用户偏好控制

用户可配置的主动行为级别：

🔇 静默模式    — 永不主动推送，仅被动响应
🔔 轻度主动    — 仅紧急事项推送（如定时任务完成、重要邮件）
📢 标准主动    — 定期巡检 + 任务通知 + 建议推送
🤖 全自主模式  — Agent 自行判断何时推送，包括主动建议

第四阶段：Agent 自我演化机制（30 分钟）

目标：确定 Agent 是否允许自我修改，以及修改的边界

讨论主题：

A. Agent 可自修改的文件范围

文件	Agent 可读	Agent 可写	需要用户确认
SOUL.md（身份）	✅	⚠️ 需确认	✅
AGENTS.md（行为指令）	✅	⚠️ 需确认	✅
USER.md（用户画像）	✅	✅ 自动更新	❌
MEMORY.md（记忆库）	✅	✅ 自动更新	❌
HEARTBEAT.md（巡检清单）	✅	⚠️ 需确认	✅

B. 自我反思循环设计

每 N 次对话后触发自我反思：
1. 回顾最近对话中的失败/成功模式
2. 提取行为改进建议
3. 更新 MEMORY.md 中的"经验教训"条目
4. 如果建议涉及 SOUL.md / AGENTS.md 修改，生成 PR 式的变更建议
5. 用户审批后生效

C. 人格版本控制

• 每次身份文件变更自动生成快照
• 用户可回滚到任意历史版本
• 支持 A/B 测试不同人格配置

第五阶段：优先级排序与路线图（30 分钟）

目标：形成可执行的 90 天 Agent 智能演化路线图

使用 ICE 评分法排序：

• Impact（影响力）：对用户体验的提升程度
• Confidence（信心）：技术可行性确信度
• Ease（易实现度）：实现成本和周期

能力	Impact	Confidence	Ease	ICE 分	建议阶段
持久记忆（SQLite）	10	9	7	630	Phase 1
身份文件动态化	8	9	9	648	Phase 1
上下文压缩 + 冲刷	9	8	6	432	Phase 2
记忆语义搜索	8	7	5	280	Phase 2
Heartbeat 引擎	9	8	6	432	Phase 3
Cron 任务增强	7	9	7	441	Phase 2
自我反思循环	8	7	5	280	Phase 3
多 Agent 协作	9	6	4	216	Phase 4
技能自主发现	7	6	4	168	Phase 4

产出：按 ICE 排序的能力清单 + 分阶段路线图

---

六、Agent 智能演化详细实施方案

6.1 总体架构设计

┌──────────────────────────────────────────────────────────────┐
│                    ZCLAW Desktop UI                           │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ ChatArea  │ │ MemoryUI │ │HeartbeatUI│ │ AgentUI  │       │
│  └─────┬────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘       │
├────────┼───────────┼────────────┼────────────┼──────────────┤
│        ▼           ▼            ▼            ▼               │
│  ┌─────────────────────────────────────────────────┐        │
│  │              Agent Intelligence Core             │        │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────────────┐│        │
│  │  │ Memory   │ │ Proactive│ │ Identity         ││        │
│  │  │ Manager  │ │ Engine   │ │ Evolution Engine ││        │
│  │  └────┬─────┘ └────┬─────┘ └────┬─────────────┘│        │
│  │       │            │            │               │        │
│  │  ┌────▼────────────▼────────────▼──────┐       │        │
│  │  │        Agent Context Manager         │       │        │
│  │  │  (压缩 / 冲刷 / 召回 / 注入)         │       │        │
│  │  └────────────────┬────────────────────┘       │        │
│  └───────────────────┼─────────────────────────────┘        │
├──────────────────────┼──────────────────────────────────────┤
│                      ▼                                       │
│  ┌─────────────────────────────────────────────────┐        │
│  │            Runtime Adapter Layer                  │        │
│  │  (ZCLAW / ZCLAW / Future Native Runtime)   │        │
│  └─────────────────────────────────────────────────┘        │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                    │
│  │ SQLite   │ │ Markdown │ │ Vector   │  ← Storage Layer   │
│  │ Memory DB│ │ Identity │ │ Index    │                     │
│  └──────────┘ └──────────┘ └──────────┘                    │
└─────────────────────────────────────────────────────────────┘

6.2 Phase 1：持久记忆 + 身份动态化（第 1-3 周）

目标：让 ZCLAW Agent 从 L1 跃迁到 L2 — 这是最关键的一步

6.2.1 记忆存储层实现

技术选型：SQLite（via Tauri 的 better-sqlite3 或 sql.js）+ Markdown 导出

// src/lib/agent-memory.ts

interface MemoryEntry {
  id: string;
  agentId: string;           // 关联的 Agent
  content: string;           // 记忆内容
  type: 'fact' | 'preference' | 'lesson' | 'context' | 'task';
  importance: number;        // 0-10，越高越不容易被遗忘
  source: 'auto' | 'user' | 'reflection';  // 来源
  tags: string[];            // 标签
  createdAt: string;         // ISO 时间戳
  lastAccessedAt: string;    // 最后访问时间（用于 LRU 修剪）
  accessCount: number;       // 访问次数
  conversationId?: string;   // 关联的对话 ID
}

interface MemoryManager {
  // 写入
  save(entry: Omit<MemoryEntry, 'id' | 'createdAt' | 'lastAccessedAt' | 'accessCount'>): Promise<MemoryEntry>;

  // 搜索
  search(query: string, options?: {
    agentId?: string;
    type?: MemoryEntry['type'];
    tags?: string[];
    limit?: number;
    minImportance?: number;
  }): Promise<MemoryEntry[]>;

  // 精确获取
  get(id: string): Promise<MemoryEntry | null>;

  // 遗忘
  forget(id: string): Promise<void>;

  // 批量遗忘（低重要性 + 长时间未访问）
  prune(options: { maxAge?: number; minImportance?: number }): Promise<number>;

  // 导出为 Markdown（可审查）
  exportToMarkdown(agentId: string): Promise<string>;

  // 统计
  stats(agentId: string): Promise<{
    totalEntries: number;
    byType: Record<string, number>;
    oldestEntry: string;
    newestEntry: string;
  }>;
}

SQLite Schema：

CREATE TABLE memories (
  id TEXT PRIMARY KEY,
  agent_id TEXT NOT NULL,
  content TEXT NOT NULL,
  type TEXT NOT NULL CHECK(type IN ('fact','preference','lesson','context','task')),
  importance INTEGER NOT NULL DEFAULT 5,
  source TEXT NOT NULL DEFAULT 'auto',
  tags TEXT DEFAULT '[]',  -- JSON array
  created_at TEXT NOT NULL,
  last_accessed_at TEXT NOT NULL,
  access_count INTEGER NOT NULL DEFAULT 0,
  conversation_id TEXT,
  embedding BLOB  -- 预留向量字段，Phase 2 启用
);

CREATE INDEX idx_memories_agent ON memories(agent_id);
CREATE INDEX idx_memories_type ON memories(agent_id, type);
CREATE INDEX idx_memories_importance ON memories(agent_id, importance DESC);

-- FTS5 全文搜索
CREATE VIRTUAL TABLE memories_fts USING fts5(content, tags, content=memories, content_rowid=rowid);

6.2.2 记忆自动采集

在 chatStore.ts 的消息流中注入记忆采集逻辑：

// 在每次对话结束（流式完成后）触发
async function extractAndSaveMemories(
  messages: Message[],
  agentId: string,
  conversationId: string
): Promise<void> {
  // 使用 LLM 从对话中提取值得记忆的信息
  const extractionPrompt = `
    请从以下对话中提取值得长期记住的信息。
    只提取以下类型：
    - fact: 用户告知的事实（如"我的公司叫 XXX"）
    - preference: 用户的偏好（如"我喜欢简洁的回答"）
    - lesson: 本次对话的经验教训
    - task: 未完成的任务或承诺

    输出 JSON 数组，每项包含 content, type, importance(1-10), tags[]。
    如果没有值得记忆的内容，返回空数组 []。
  `;

  // 调用 LLM 提取 → 存入 MemoryManager
}

6.2.3 身份文件动态化

将现有静态 config/SOUL.md、AGENTS.md、USER.md 改造为每个 Agent 独立 + 可由 Agent 更新的机制：

~/.zclaw/agents/<agentId>/
├── SOUL.md          # Agent 身份定义（Agent 可提议修改，需用户确认）
├── AGENTS.md        # 行为指令
├── USER.md          # 用户画像（Agent 可自动更新）
├── MEMORY.md        # Markdown 格式的记忆导出（只读快照）
└── memory.db        # SQLite 记忆数据库

关键设计：

• USER.md Agent 可自动更新（记录学到的用户偏好）
• SOUL.md / AGENTS.md Agent 可提议修改 → 生成"变更建议" → 用户审批
• 每次修改自动生成快照（时间戳命名），支持回滚

6.2.4 记忆注入到上下文

在每次发送消息到 LLM 前，自动注入相关记忆：

async function buildContextWithMemory(
  userMessage: string,
  agentId: string,
  existingContext: Message[]
): Promise<Message[]> {
  // 1. 搜索相关记忆
  const relevantMemories = await memoryManager.search(userMessage, {
    agentId,
    limit: 10,
    minImportance: 3,
  });

  // 2. 读取 Agent 身份文件
  const soulContent = await readAgentFile(agentId, 'SOUL.md');
  const userProfile = await readAgentFile(agentId, 'USER.md');

  // 3. 构建增强的系统提示
  const memoryContext = relevantMemories.length > 0
    ? `\n\n## 相关记忆\n${relevantMemories.map(m =>
        `- [${m.type}] ${m.content}`
      ).join('\n')}`
    : '';

  const enhancedSystemPrompt = `${soulContent}\n\n## 用户画像\n${userProfile}${memoryContext}`;

  // 4. 注入到上下文
  return [
    { role: 'system', content: enhancedSystemPrompt },
    ...existingContext,
  ];
}

6.2.5 Phase 1 交付物

• src/lib/agent-memory.ts — MemoryManager 实现
• src/lib/agent-identity.ts — 身份文件管理
• src/lib/memory-extractor.ts — 对话记忆自动提取
• src/components/MemoryPanel.tsx — 记忆查看/搜索/删除 UI
• src/components/AgentIdentityEditor.tsx — 身份文件编辑 + 变更历史
• 单元测试 + 集成测试
• 每个 Agent 独立的工作空间目录结构

6.2.6 Phase 1 验收标准

• ✅ 对话结束后自动提取并持久化记忆
• ✅ 新对话自动加载相关历史记忆
• ✅ Agent 能说出"上次你提到过 XXX"
• ✅ 用户可以在 UI 中查看、搜索、删除记忆
• ✅ 身份文件每个 Agent 独立，且可在 UI 中编辑
• ✅ USER.md 会随对话自动更新

---

6.3 Phase 2：上下文治理 + Cron 增强（第 4-6 周）

目标：让 Agent 能进行无限长的对话而不丢失关键信息，并具备定时任务能力

6.3.1 上下文压缩引擎

// src/lib/context-compactor.ts

interface CompactionConfig {
  softThresholdTokens: number;   // 软阈值（默认 15000）
  reserveTokens: number;         // 保留空间（默认 4000）
  memoryFlushEnabled: boolean;   // 压缩前是否冲刷记忆
}

class ContextCompactor {
  // 监控上下文 token 数
  checkThreshold(messages: Message[], config: CompactionConfig): boolean;

  // 执行记忆冲刷（提取即将被压缩的对话中的重要信息）
  async memoryFlush(
    messagesToCompact: Message[],
    agentId: string
  ): Promise<void>;

  // 执行压缩（将旧消息摘要化）
  async compact(
    messages: Message[],
    config: CompactionConfig
  ): Promise<{
    compactedMessages: Message[];  // 压缩后的消息列表
    summary: string;                // 压缩摘要
    flushedMemories: number;       // 冲刷的记忆数
  }>;
}

压缩流程：

上下文接近阈值
    ↓
[记忆冲刷] Agent 静默审查即将被压缩的消息，提取重要信息存入持久记忆
    ↓
[压缩执行] 旧消息被 LLM 摘要替代
    ↓
[新分支] 摘要作为新的上下文起点
    ↓
用户无感知，对话继续

6.3.2 记忆语义搜索（向量检索）

// 使用本地嵌入模型（如 transformers.js 的 all-MiniLM-L6-v2）
// 或调用 LLM API 的嵌入接口

interface VectorMemorySearch {
  // 为记忆生成嵌入向量
  embed(text: string): Promise<Float32Array>;

  // 语义搜索
  semanticSearch(
    query: string,
    agentId: string,
    topK: number
  ): Promise<Array<{ entry: MemoryEntry; similarity: number }>>;
}

6.3.3 Cron 定时任务增强

现有 scheduledTasks API 已有基础框架，需增强：

interface EnhancedScheduledTask {
  id: string;
  name: string;
  schedule: string;              // cron 表达式
  prompt: string;                // 任务执行时的提示
  agentId: string;               // 使用哪个 Agent 执行
  isolatedSession: boolean;      // 是否在独立会话中执行
  notifyOnComplete: boolean;     // 完成时是否通知
  notifyChannel: 'desktop' | 'feishu' | 'all';
  retryPolicy: {
    maxRetries: number;
    retryInterval: number;
  };
  lastRun?: string;
  lastResult?: 'success' | 'failure' | 'skipped';
  status: 'active' | 'paused';
}

6.3.4 Phase 2 交付物

• src/lib/context-compactor.ts — 上下文压缩 + 记忆冲刷
• src/lib/vector-memory.ts — 向量记忆搜索
• src/components/ScheduledTaskManager.tsx — 增强的定时任务 UI
• 压缩过程的用户可见状态提示
• 定时任务的执行历史和日志

6.3.5 Phase 2 验收标准

• ✅ 超长对话自动压缩，用户无感知
• ✅ 压缩前关键信息已保存到持久记忆
• ✅ 记忆搜索支持语义匹配
• ✅ 定时任务可创建、暂停、查看历史
• ✅ 定时任务执行结果可通过桌面通知推送

---

6.4 Phase 3：主动智能 + 自我反思（第 7-10 周）

目标：让 Agent 从 L2 跃迁到 L3+，具备主动巡检和自我改进能力

6.4.1 Heartbeat 引擎

// src/lib/heartbeat-engine.ts

interface HeartbeatConfig {
  enabled: boolean;
  intervalMinutes: number;       // 默认 30
  quietHoursStart?: string;      // 免打扰开始时间（如 "22:00"）
  quietHoursEnd?: string;        // 免打扰结束时间（如 "08:00"）
  checklistPath: string;         // HEARTBEAT.md 路径
  notifyChannel: 'desktop' | 'feishu' | 'all';
  proactivityLevel: 'silent' | 'light' | 'standard' | 'autonomous';
}

class HeartbeatEngine {
  // 启动心跳循环
  start(config: HeartbeatConfig): void;

  // 停止
  stop(): void;

  // 单次心跳执行
  async tick(): Promise<HeartbeatResult>;

  // 心跳结果
  // - HEARTBEAT_OK：无需关注，静默
  // - HeartbeatAlert：有需要关注的事项
}

interface HeartbeatResult {
  status: 'ok' | 'alert';
  alerts?: Array<{
    title: string;
    content: string;
    urgency: 'low' | 'medium' | 'high';
    source: string;  // 来自哪个检查项
  }>;
  checkedItems: number;
  timestamp: string;
}

HEARTBEAT.md 示例：

# ZCLAW 心跳巡检清单

## 工作相关
- 检查是否有未完成的任务需要跟进
- 检查工作目录是否有新文件需要处理

## 系统相关
- 检查 Gateway 连接状态
- 检查磁盘空间是否充足

## 用户关怀
- 如果今天是工作日且用户还未使用，发送简短问候
- 如果有定时任务完成，汇总结果

6.4.2 自我反思循环

// src/lib/reflection-engine.ts

interface ReflectionConfig {
  triggerAfterConversations: number;  // 每 N 次对话后触发（默认 5）
  triggerAfterHours: number;          // 每 N 小时触发（默认 24）
  allowSoulModification: boolean;     // 是否允许建议修改 SOUL.md
  requireApproval: boolean;           // 身份修改是否需要用户审批
}

class ReflectionEngine {
  // 触发一次反思
  async reflect(agentId: string): Promise<ReflectionResult>;
}

interface ReflectionResult {
  // 行为模式分析
  patterns: Array<{
    observation: string;   // 观察到的模式
    frequency: number;     // 出现频率
    sentiment: 'positive' | 'negative' | 'neutral';
  }>;

  // 改进建议
  improvements: Array<{
    area: string;          // 改进领域
    suggestion: string;    // 具体建议
    priority: 'high' | 'medium' | 'low';
  }>;

  // 身份文件变更建议（如果有）
  identityChanges?: Array<{
    file: string;          // SOUL.md / AGENTS.md
    currentContent: string;
    suggestedContent: string;
    reason: string;
  }>;

  // 新增记忆
  newMemories: MemoryEntry[];
}

6.4.3 Phase 3 交付物

• src/lib/heartbeat-engine.ts — Heartbeat 引擎
• src/lib/reflection-engine.ts — 自我反思引擎
• src/components/HeartbeatConfig.tsx — 心跳配置 UI
• src/components/ReflectionLog.tsx — 反思日志查看 UI
• Agent 身份文件变更建议的审批流 UI
• 桌面通知集成

6.4.4 Phase 3 验收标准

• ✅ Agent 定期自动巡检，有事项时通过桌面通知告知
• ✅ 用户可编辑 HEARTBEAT.md 自定义检查项
• ✅ Agent 定期自我反思，生成改进建议
• ✅ 身份文件变更需用户审批，支持回滚
• ✅ 免打扰时段不推送通知

---

6.5 Phase 4：多 Agent 协作 + 技能生态（第 11-16 周） — ✅ 已完成

目标：构建 Agent 协作框架和技能自主发现能力

6.5.1 多 Agent 协作框架

// src/lib/agent-swarm.ts

interface SwarmConfig {
  coordinator: string;           // 协调者 Agent ID
  specialists: Array<{
    agentId: string;
    role: string;               // 专长描述
    capabilities: string[];     // 能力标签
  }>;
  taskDecomposition: 'auto' | 'manual';
  communicationStyle: 'sequential' | 'parallel' | 'debate';
}

interface SwarmTask {
  id: string;
  description: string;
  subtasks: Array<{
    id: string;
    assignedTo: string;        // Agent ID
    description: string;
    status: 'pending' | 'running' | 'done' | 'failed';
    result?: string;
  }>;
  status: 'planning' | 'executing' | 'aggregating' | 'done';
}

协作模式：

• Sequential（顺序）：一个 Agent 完成后交给下一个
• Parallel（并行）：多个 Agent 同时处理不同子任务
• Debate（辩论）：多个 Agent 对同一问题给出观点，协调者综合

6.5.2 技能自主发现

// src/lib/skill-discovery.ts

interface SkillDiscovery {
  // 根据用户需求搜索可用技能
  searchSkills(query: string): Promise<SkillInfo[]>;

  // 建议安装技能（Agent 主动）
  suggestSkills(recentConversations: Conversation[]): Promise<SkillSuggestion[]>;

  // 安装技能（需用户确认）
  installSkill(skillId: string): Promise<void>;
}

6.5.3 Phase 4 交付物

• ✅ desktop/src/lib/agent-swarm.ts — 多 Agent 协作引擎（Sequential/Parallel/Debate 三种模式）
• ✅ desktop/src/lib/skill-discovery.ts — 技能发现与推荐（12 个内置技能，关键词搜索 + 对话模式推荐）
• ✅ desktop/src/store/chatStore.ts — dispatchSwarmTask + searchSkills 集成
• ✅ tests/desktop/swarm-skills.test.ts — 43 项单元测试
• 📋 src/components/SwarmDashboard.tsx — 协作任务面板（UI 待实现）
• 📋 src/components/SkillMarket.tsx — 技能市场 UI（UI 待实现）

---

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 中的架构演化是互补关系：

架构演化（策略文档）	Agent 智能演化（本文档）	交叉点
Phase 0: 统一叙事	—	Agent 身份文件纳入叙事统一范围
Phase 1: 领域模型标准化	Phase 1: 持久记忆 + 身份动态化	MemoryEntry 纳入 Canonical Domain Model
Phase 2: Adapter 层落地	Phase 2: 上下文治理	记忆存储作为 Memory Adapter 接口
Phase 3: 平台能力增强	Phase 3: 主动智能	Heartbeat / Cron 作为平台级能力
Phase 4: 安全治理	Phase 3: 自我反思	Agent 自修改需要安全策略
Phase 5: 产品化生态	Phase 4: 多 Agent + 技能生态	技能市场 + 协作框架

建议执行顺序：架构层 Phase 0-1 先行（统一叙事 + 领域模型），然后 Agent 智能 Phase 1 与架构 Phase 2 并行推进。

---

八、关键技术决策点（需团队讨论确认）

决策 1：记忆存储位置

选项	优点	缺点	推荐
A. 全部 SQLite（本地）	离线可用、查询快、桌面原生	多设备同步难	✅ 推荐短期
B. 全部云端	多设备同步	隐私敏感、需要后端	❌ 当前不适合
C. SQLite 本地 + 可选云同步	兼顾两者	实现复杂度高	✅ 推荐中期

决策 2：记忆提取时机

选项	优点	缺点	推荐
A. 每条消息后实时提取	不遗漏	LLM 调用成本高	❌
B. 对话结束后批量提取	成本低、上下文完整	可能忘记中间信息	✅ 推荐
C. 压缩前 + 对话结束后	最安全	稍增加复杂度	✅ 推荐中期

决策 3：Heartbeat 运行位置

选项	优点	缺点	推荐
A. 桌面端前台进程	实现简单	应用关闭则停止	❌
B. Tauri Rust 后台服务	应用关闭仍可运行	实现复杂	✅ 推荐
C. Gateway 运行时侧	与运行时一体	依赖运行时在线	作为补充

决策 4：Agent 自修改的安全边界

选项	优点	缺点	推荐
A. Agent 不可修改任何配置	最安全	无法自我演化	❌
B. Agent 可自由修改所有文件	最灵活	风险不可控	❌
C. 分级：USER.md 自由 / 其他需审批	平衡安全与演化	审批流需 UI 支持	✅ 推荐

---

九、成功度量指标

9.1 用户体验指标

指标	当前基线	Phase 1 目标	Phase 3 目标
Agent 记住用户偏好的比例	0%	>60%	>85%
跨会话上下文连续性	无	基本可用	流畅
用户需要重复说明信息的次数	每次都需要	减少 50%	减少 80%
Agent 主动有用推送的比例	0%	N/A	>70% 有用

9.2 技术指标

指标	当前基线	Phase 1 目标	Phase 3 目标
记忆持久化延迟	N/A	<500ms	<200ms
记忆搜索延迟	N/A	<200ms（FTS5）	<100ms（向量+FTS5）
上下文压缩信息保留率	0%	N/A（Phase 2）	>90%
心跳执行成功率	N/A	N/A	>99%

9.3 智能成熟度目标

时间点	目标级别	关键能力
Phase 1 完成	L2（持久记忆）	跨会话记忆、身份动态化
Phase 2 完成	L2+	上下文压缩、语义搜索、Cron 任务
Phase 3 完成	L3（主动智能）	Heartbeat、自我反思
Phase 4 完成	L3+	多 Agent 协作、技能自主发现
长期目标	L4（自我演化）	完整的自主行为优化循环

---

十、风险与缓解

风险	影响	缓解措施
LLM 记忆提取成本过高	增加 API 调用费用	对话结束后批量提取 + 本地小模型预筛
记忆数据库膨胀	存储空间 + 搜索变慢	自动修剪低重要性 + 长期未访问的记忆
Heartbeat 过度打扰用户	用户体验下降	分级主动性 + 免打扰时段 + 用户可随时关闭
Agent 自修改导致行为异常	信任危机	分级审批 + 自动快照 + 一键回滚
上下文压缩丢失关键信息	对话质量下降	压缩前记忆冲刷 + 用户可查看压缩摘要
多 Agent 协作的一致性	结果矛盾	协调者 Agent 做最终决策 + 冲突解决策略

---

十一、立即可执行的行动（本周）

P0（本周必须启动）— ✅ 全部完成

1. ✅ 确认记忆存储技术选型

   • Phase 1 采用 localStorage 持久化（无外部依赖），升级路径已预留 SQLite + FTS5
   • 输出：agent-memory.ts MemoryManager 实现 + 42 项单元测试

2. ✅ 设计 MemoryEntry schema 并评审

   • 完整 TypeScript 接口：id, agentId, content, type, importance, source, tags, createdAt, lastAccessedAt, accessCount, conversationId
   • 支持 5 种类型：fact, preference, lesson, context, task

3. ✅ 重构 Agent 工作空间目录结构

   • 通过 AgentIdentityManager 实现每个 Agent 独立的 SOUL/AGENTS/USER.md
   • 支持快照、回滚、变更审批流

P1（下周启动）— ✅ 全部完成

4. ✅ 实现 MemoryManager 核心接口

   • save / search / get / getAll / forget / prune / exportToMarkdown / stats
   • 输出：desktop/src/lib/agent-memory.ts + 42 项测试

5. ✅ 在 chatStore 中集成记忆注入

   • sendMessage 前自动搜索相关记忆 + 注入身份系统提示
   • 输出：chatStore.ts memory-enhanced 发送流程

6. ✅ 实现对话记忆自动提取

   • Phase 1 规则匹配提取 + Phase 2 LLM 提取 prompt 已预留
   • 输出：desktop/src/lib/memory-extractor.ts + 测试

P2（额外完成）— ✅

7. ✅ 上下文压缩引擎 — desktop/src/lib/context-compactor.ts (23 tests)
8. ✅ 心跳巡检引擎 — desktop/src/lib/heartbeat-engine.ts (28 tests shared)
9. ✅ 自我反思引擎 — desktop/src/lib/reflection-engine.ts
10. ✅ 记忆浏览 UI — desktop/src/components/MemoryPanel.tsx (RightPanel 第4个 tab)

---

十二、总结

ZCLAW 当前 Agent 与 ZCLAW Agent 的核心差距不在 LLM 能力，而在 Agent 基础设施。

ZCLAW 构建了一套完整的"Agent 成长基础设施"：

• 记忆让 Agent 有了"过去"
• Heartbeat让 Agent 有了"主动意识"
• 身份演化让 Agent 有了"自我成长"
• 上下文治理让 Agent 有了"无限续航"

ZCLAW 要做的不是复制 ZCLAW，而是：

在桌面端场景下，构建一套更适合中文用户、更注重隐私、更强调团队协作的 Agent 成长基础设施。

具体路径：

1. Phase 1（最紧急）：持久记忆 + 身份动态化 → L1 到 L2 的跃迁
2. Phase 2：上下文治理 + 语义搜索 + Cron → 巩固 L2
3. Phase 3：Heartbeat + 自我反思 → L2 到 L3 的跃迁
4. Phase 4：多 Agent 协作 + 技能生态 → 向 L4 进发

L1 到 L2 的跃迁是当前最高杠杆的工作——这一步完成后，用户就能感受到"ZCLAW 认识我了"。

---

附录：参考资料

公开技术分析

• Inside ZCLAW: How the World's Fastest-Growing AI Agent Actually Works Under the Hood
• Inside ZCLAW: How a Persistent AI Agent Actually Works
• ZeroClaw: A Minimal Rust-Based AI Agent Framework for Self-Hosted Systems
• NanoClaw Official Site

当前仓库文档

• docs/ZCLAW_NEXT_EVOLUTION_STRATEGY.md — 架构层全景对比
• config/SOUL.md / config/AGENTS.md / config/USER.md — 当前静态身份配置
• desktop/src/store/agentStore.ts — 当前 Agent 管理实现
• desktop/src/store/chatStore.ts — 当前对话管理实现
• desktop/src/components/CloneManager.tsx — 当前 Clone 管理 UI