zclaw_openfang/docs/archive/completed-plans/ZCLAW_OPENVIKING_INTEGRATION_PLAN.md

ZCLAW × OpenViking 跨部门头脑风暴与开发实施方案

文档日期：2026-03-15
定位：基于 OpenViking（火山引擎开源 AI 智能体上下文数据库）技术，结合 ZCLAW Agent 智能演化需求，制定跨部门协作的完整开发方案
关联文档：

• ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md — Agent 智能差距分析
• ZCLAW_NEXT_EVOLUTION_STRATEGY.md — 架构层全景对比

---

一、战略判断：为什么 OpenViking 是 ZCLAW Agent 智能化的关键拼图

1.1 ZCLAW 的核心痛点（已确认）

在 ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md 中，我们诊断出 ZCLAW Agent 处于 L1（会话感知） 级别，缺失六大基础设施：

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

1.2 OpenViking 精准解决了哪些痛点

ZCLAW 痛点	OpenViking 解决方案	覆盖程度
记忆层缺失	viking://user/memories/ + viking://agent/memories/ 统一记忆管理	✅ 完全覆盖
上下文治理缺失	L0/L1/L2 三层上下文按需加载 + 自动会话管理	✅ 完全覆盖
记忆检索效果差	目录递归检索（比扁平向量搜索精准得多）	✅ 完全覆盖
检索黑盒不可调试	可视化检索轨迹	✅ 完全覆盖
技能/资源碎片化	viking:// 虚拟文件系统统一管理	✅ 完全覆盖
主动引擎缺失	❌ OpenViking 不提供（需自建 Heartbeat/Cron）	❌ 需自建
反思循环缺失	自动会话管理的"记忆自迭代"部分覆盖	⚠️ 部分覆盖

1.3 OpenViking 的量化优势（基于官方评测）

指标	ZCLAW 原生记忆	ZCLAW + LanceDB	ZCLAW + OpenViking	提升幅度
任务完成率	35.65%	44.55%	52.08%	+46% vs 原生
输入 Token 消耗	24,611,530	51,574,530	4,264,396	-83% vs 原生

关键洞察：OpenViking 不仅效果更好，而且成本低一个数量级。这对 ZCLAW 的用户（中国市场、成本敏感）极其关键。

1.4 战略结论

OpenViking 应该取代我们之前规划的自建 SQLite 记忆方案，成为 ZCLAW Agent 智能化的核心上下文引擎。

原因：

1. 效果更好：目录递归检索 >> 扁平向量搜索，任务完成率提升 46%
2. 成本更低：L0/L1/L2 分层加载，Token 消耗降低 83-91%
3. 开发更快：已有 ZCLAW 记忆插件，可直接适配
4. 架构更优：viking:// 文件系统范式天然统一了记忆、资源、技能
5. 生态对齐：火山引擎/字节跳动出品，与 ZCLAW 的中国市场定位高度契合

---

二、跨部门头脑风暴方案

2.1 参与部门与角色

部门/角色	参会人	职责
产品	产品负责人	定义用户场景、验收标准、优先级
前端	桌面端开发（Tauri/React）	UI 交互方案、记忆面板、检索可视化
后端	Gateway/Runtime 开发	OpenViking 服务集成、API 设计、数据流
AI/算法	Agent 调优工程师	Prompt 设计、记忆提取策略、模型选型
基础设施	运维/部署工程师	OpenViking Server 部署、性能监控、资源规划
测试	QA 工程师	测试策略、基线对比、回归验证

2.2 会前准备（会议前 3 天完成）

必读材料

1. 本文档（重点阅读第一、三、五章）
2. OpenViking 官方 README（中文）
3. ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md（重点阅读第一~三章的差距分析）
4. 当前 config/SOUL.md、config/AGENTS.md（了解现状）

技术预研（指定负责人提前完成）

预研任务	负责部门	输出物
本地部署 OpenViking Server 并跑通 Quick Start	基础设施	部署文档 + 性能基准
阅读 ZCLAW 记忆插件源码，评估适配 ZCLAW 的工作量	后端	适配方案评估报告
设计 ZCLAW 桌面端记忆面板 UX 原型	产品 + 前端	Figma/草图原型
测试 OpenViking 在中文场景下的检索效果	AI/算法	检索效果报告
评估 Tauri 进程中嵌入 OpenViking Python 服务的可行性	基础设施	技术可行性报告

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

1. 产品视角：用户最希望 ZCLAW "记住"什么？记忆面板应该长什么样？
2. 前端视角：检索轨迹可视化如何在桌面端呈现？对现有 UI 架构的影响？
3. 后端视角：OpenViking Server 作为 ZCLAW 的子进程 vs 独立服务，哪种更适合桌面产品？
4. AI 视角：L0/L1/L2 分层策略如何适配中文语境？记忆提取 Prompt 需要哪些定制？
5. 基础设施视角：OpenViking 的 Python + Go 依赖如何与 ZCLAW 的 Tauri (Rust) + Node.js 栈共存？
6. 测试视角：如何建立 Agent 智能化的量化评测基线？

2.3 会议议程（4 小时，分两个半天）

---

上半场：认知对齐 + 技术决策（2 小时）

第一节：战略对齐（30 分钟）

目标：全团队对"为什么选 OpenViking"形成共识

• 演示：ZCLAW 当前 Agent vs ZCLAW Agent 的能力对比（活动 Demo）
• 数据：OpenViking 的评测数据（+46% 任务完成率，-83% Token 成本）
• 架构：OpenViking 如何填补 ZCLAW 的 6 大基础设施缺失
• 投票确认：是否以 OpenViking 作为 ZCLAW 的核心上下文引擎

产出：Go/No-Go 决策

第二节：架构方案讨论（45 分钟）

目标：确定 OpenViking 与 ZCLAW 的集成架构

讨论议题 A：集成模式选型

方案 1：嵌入式（OpenViking 作为 ZCLAW 进程内组件）
┌──────────────────────────────────┐
│ ZCLAW Desktop (Tauri)            │
│  ├── React UI                    │
│  ├── Rust Backend                │
│  │   └── 管理 OpenViking 子进程   │
│  ├── ZCLAW Gateway (Node.js)  │
│  └── OpenViking Server (Python)  │  ← 作为 sidecar 进程
└──────────────────────────────────┘

方案 2：独立服务（OpenViking 独立部署）
┌──────────────┐    HTTP    ┌──────────────────┐
│ ZCLAW Desktop│ ◄────────► │ OpenViking Server │
│  (Tauri)     │            │  (独立部署)        │
└──────────────┘            └──────────────────┘

方案 3：混合模式（开发期嵌入，生产期可选独立）
┌──────────────────────────────────┐
│ ZCLAW Desktop (Tauri)            │
│  ├── VikingAdapter（抽象接口）     │
│  │   ├── EmbeddedViking          │  ← 默认：进程内 sidecar
│  │   └── RemoteViking            │  ← 可选：连接远程服务
│  └── ...                         │
└──────────────────────────────────┘

方案	优点	缺点	推荐
嵌入式	零配置、用户无感	Python 依赖大、打包复杂	⚠️
独立服务	解耦、性能好	用户需额外部署	❌ 桌面产品不适合
混合模式	灵活、渐进式	接口设计需前期投入	✅ 推荐

讨论议题 B：数据流设计

用户发送消息
    │
    ▼
[ChatStore] ──→ [ContextBuilder]
                    │
                    ├── 1. 查询 OpenViking：相关记忆 + 资源
                    │   viking://user/memories/preferences/
                    │   viking://agent/memories/task_history/
                    │   viking://resources/workspace_docs/
                    │
                    ├── 2. 读取 Agent 身份文件
                    │   SOUL.md / AGENTS.md / USER.md
                    │
                    ├── 3. L0/L1/L2 分层加载
                    │   L0: 先加载摘要（~100 tokens/条）
                    │   L1: 相关项加载概览（~2k tokens/条）
                    │   L2: 必要时加载完整内容
                    │
                    ▼
            [增强的 System Prompt]
                    │
                    ▼
            [LLM 调用] ──→ [响应]
                                │
                                ▼
                        [MemoryExtractor]
                            │
                            ├── 提取用户偏好 → viking://user/memories/
                            ├── 提取任务经验 → viking://agent/memories/
                            └── 更新身份文件 → USER.md（自动）/ SOUL.md（需审批）

讨论议题 C：Viking URI 命名空间设计

viking://
├── resources/                        # ZCLAW 资源
│   ├── workspace/                    # 用户工作区文件
│   ├── knowledge-base/               # 项目知识库
│   └── external/                     # 外部导入的资源
│
├── user/                             # 用户维度
│   └── memories/
│       ├── preferences/              # 偏好（语言、代码风格、沟通方式）
│       │   ├── language_preference
│       │   ├── coding_style
│       │   └── communication_style
│       ├── facts/                    # 事实（公司、项目、人物关系）
│       │   ├── company_info
│       │   ├── project_contexts
│       │   └── contacts
│       └── history/                  # 交互历史摘要
│           ├── daily/
│           └── weekly/
│
└── agent/                            # Agent 维度
    ├── <agentId>/
    │   ├── identity/                 # 身份文件
    │   │   ├── soul                  # SOUL.md 内容
    │   │   ├── instructions          # AGENTS.md 内容
    │   │   └── changelog             # 身份演化记录
    │   ├── memories/                 # Agent 记忆
    │   │   ├── lessons_learned/      # 经验教训
    │   │   ├── task_patterns/        # 任务模式
    │   │   └── tool_tips/            # 工具使用技巧
    │   └── skills/                   # Agent 技能
    │       ├── available/
    │       └── learned/
    ├── shared/                       # 跨 Agent 共享记忆
    │   ├── common_knowledge/
    │   └── coordination/
    └── swarm/                        # 多 Agent 协作
        └── task_results/

产出：集成架构方案 + 数据流设计 + URI 命名空间初稿

第三节：技术预研结果汇报（45 分钟）

各部门汇报预研结果：

1. 基础设施：OpenViking 本地部署结果、资源消耗、启动时间
2. 后端：ZCLAW 记忆插件适配评估
3. AI/算法：中文检索效果、分层策略效果
4. 前端：记忆面板 UX 原型展示

产出：技术可行性确认 + 风险清单

---

下半场：方案细化 + 排期规划（2 小时）

第四节：分组讨论（60 分钟）

分三个并行小组，各组产出具体方案：

小组 A：上下文引擎组（后端 + AI + 基础设施）

讨论要点：

1. OpenViking Server 打包策略（Python 打包进 Tauri Bundle？PyInstaller？）
2. OpenViking API 与 ZCLAW Gateway 的集成点
3. 记忆提取 Prompt 的中文定制方案
4. Embedding 模型选型（推荐：doubao-embedding-vision 或 text-embedding-3-large）
5. 自动会话管理的触发时机（对话结束后？压缩前？定时？）

产出：上下文引擎技术方案文档

小组 B：前端体验组（产品 + 前端）

讨论要点：

1. 记忆面板 UI（查看、搜索、删除、重要度标记）
2. 检索轨迹可视化组件（目录树 + 命中高亮）
3. Agent 身份文件编辑器（diff 视图 + 审批流）
4. Heartbeat 通知交互（桌面通知 vs 应用内通知）
5. 上下文消耗仪表盘（L0/L1/L2 用量可视化）

产出：前端交互方案文档 + 线框图

小组 C：质量保障组（测试 + 各部门代表）

讨论要点：

1. Agent 智能化评测基线建立（参考 LoCoMo 测试集）
2. 中文场景测试集构建
3. 性能基准（记忆检索延迟、Token 消耗）
4. 回归测试策略（确保不破坏现有功能）
5. 用户体验 A/B 测试方案

产出：测试策略文档 + 评测基线

第五节：方案汇总与排期（60 分钟）

1. 三个小组依次汇报（各 10 分钟）
2. 交叉评审与整合（15 分钟）
3. ICE 优先级排序（15 分钟）
4. 里程碑与排期确认（10 分钟）

最终产出：

• ✅ 集成架构方案（经团队共识）
• ✅ 各模块技术方案文档
• ✅ 分阶段里程碑与排期
• ✅ 责任分工矩阵（RACI）

---

三、OpenViking 五大核心概念与 ZCLAW 的映射

3.1 文件系统管理范式 → ZCLAW 的统一上下文管理

OpenViking 核心：用 viking:// 虚拟文件系统统一管理记忆、资源、技能

ZCLAW 映射：

当前 ZCLAW 的碎片化状态：
- 记忆 → 无（完全缺失）
- 身份 → config/SOUL.md, AGENTS.md（静态文件）
- 技能 → skills/ 目录（手动管理）
- 资源 → 无（无资源管理）
- 对话 → chatStore（纯前端 state）

引入 OpenViking 后的统一状态：
viking://
├── user/memories/     ← 用户偏好、事实、历史
├── agent/<id>/        ← 每个 Agent 的身份、记忆、技能
├── resources/         ← 工作区文件、项目知识
└── agent/shared/      ← 跨 Agent 共享知识

价值：所有上下文通过统一的 viking:// 协议访问，消除碎片化。

3.2 分层上下文加载 → ZCLAW 的 Token 成本控制

OpenViking 核心：L0（摘要 ~100 tokens）→ L1（概览 ~2k tokens）→ L2（详情 完整内容）

ZCLAW 映射：

// 每次对话前的上下文构建
async function buildContext(userMessage: string, agentId: string) {
  // Step 1: L0 检索 — 快速判断哪些记忆/资源相关（低成本）
  const l0Results = await viking.find(userMessage, { level: 'L0', limit: 50 });
  // 成本：~50 × 100 = 5000 tokens

  // Step 2: L1 加载 — 对相关项加载概览（中等成本）
  const relevantItems = l0Results.filter(r => r.score > 0.7);
  const l1Results = await viking.read(relevantItems, { level: 'L1' });
  // 成本：~10 × 2000 = 20000 tokens

  // Step 3: L2 按需 — 只在必要时加载完整内容（高成本但精准）
  const criticalItems = l1Results.filter(r => r.needsDetail);
  const l2Results = await viking.read(criticalItems, { level: 'L2' });
  // 成本：仅 2-3 条完整内容

  return combineContext(l0Results, l1Results, l2Results);
}

Token 节省估算：

方案	每次对话 Token 消耗	月度成本（假设 100 次/天）
无记忆（当前）	基础 ~4k	基线
全量注入（暴力方案）	~50k+	12.5x
OpenViking 分层加载	~8-12k	2-3x（可控）

3.3 目录递归检索 → ZCLAW 的精准上下文召回

OpenViking 核心：

1. 意图分析 → 生成多个检索条件
2. 初始定位 → 向量检索锁定高分目录
3. 精细探索 → 目录内二次检索
4. 递归深入 → 子目录逐层检索
5. 结果聚合 → 返回最相关上下文

ZCLAW 映射：

用户问"上次那个飞书集成的问题怎么解决的？"

传统 RAG：
  → 向量搜索 "飞书集成 问题 解决"
  → 返回 10 个扁平切片，可能丢失上下文

OpenViking 递归检索：
  → 意图分析：[飞书, 集成, 问题解决, 历史]
  → 定位目录：viking://agent/memories/lessons_learned/
  → 目录内搜索：发现 feishu_integration_troubleshoot
  → 递归子目录：发现 auth_issue, webhook_config, api_rate_limit
  → 聚合返回：完整的飞书集成问题解决方案（含上下文）

3.4 可视化检索轨迹 → ZCLAW 的可调试记忆

OpenViking 核心：每次检索的目录浏览和文件定位轨迹完整保留

ZCLAW 映射：

┌─────────────────────────────────────────────────────────┐
│ 🔍 记忆检索轨迹                                         │
│                                                         │
│ 查询："飞书集成问题"                                      │
│                                                         │
│ viking://                                               │
│ ├── user/memories/              [分数: 0.3] ⬜ 跳过      │
│ ├── agent/zclaw-main/memories/  [分数: 0.8] ✅ 进入      │
│ │   ├── lessons_learned/        [分数: 0.9] ✅ 进入      │
│ │   │   ├── feishu_integration  [分数: 0.95] ✅ 命中!    │
│ │   │   ├── gateway_handshake   [分数: 0.4] ⬜ 跳过      │
│ │   │   └── model_config        [分数: 0.2] ⬜ 跳过      │
│ │   └── task_patterns/          [分数: 0.5] ⬜ 跳过      │
│ └── resources/knowledge-base/   [分数: 0.6] ⚠️ 备选      │
│                                                         │
│ 📊 消耗: L0=500 tokens | L1=2000 tokens | L2=0 tokens   │
└─────────────────────────────────────────────────────────┘

价值：当 Agent 回忆不准确时，用户和开发者可以看到检索路径，精准定位问题。

3.5 自动会话管理 → ZCLAW 的记忆自迭代

OpenViking 核心：会话结束时自动提取记忆，更新用户和 Agent 记忆目录

ZCLAW 映射：

对话结束
    │
    ▼
[OpenViking 自动会话管理]
    │
    ├── 提取用户记忆
    │   → "用户偏好中文回复" → viking://user/memories/preferences/language
    │   → "用户在做飞书集成" → viking://user/memories/facts/current_project
    │
    ├── 提取 Agent 经验
    │   → "调用飞书API时需要先检查token有效性" → viking://agent/<id>/memories/lessons_learned/
    │   → "用户喜欢先看方案再动手" → viking://agent/<id>/memories/task_patterns/
    │
    └── 更新身份文件（需审批的变更）
        → "建议 SOUL.md 增加：在执行前先展示方案" → 生成变更建议

---

四、完整开发方案

4.1 总体架构

┌─────────────────────────────────────────────────────────────────┐
│                      ZCLAW Desktop (Tauri)                       │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │                    React UI Layer                           │  │
│  │  ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────────┐│  │
│  │  │ ChatArea  │ │MemoryUI  │ │RetrievalUI│ │ HeartbeatUI  ││  │
│  │  │          │ │ (记忆面板) │ │(检索轨迹)  │ │ (心跳配置)   ││  │
│  │  └────┬─────┘ └────┬─────┘ └─────┬─────┘ └──────┬───────┘│  │
│  └───────┼────────────┼─────────────┼───────────────┼────────┘  │
│          ▼            ▼             ▼               ▼            │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │              Agent Intelligence Core (TypeScript)           │  │
│  │  ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │  │
│  │  │ VikingAdapter│ │ ProactiveEng │ │ IdentityEvolution  │ │  │
│  │  │ (上下文引擎)  │ │ (主动引擎)    │ │ (身份演化引擎)      │ │  │
│  │  └──────┬───────┘ └──────┬───────┘ └────────┬───────────┘ │  │
│  │         │                │                   │             │  │
│  │  ┌──────▼────────────────▼───────────────────▼──────┐     │  │
│  │  │            ContextBuilder（上下文构建器）           │     │  │
│  │  │  L0 摘要检索 → L1 概览加载 → L2 按需详情           │     │  │
│  │  └─────────────────────┬────────────────────────────┘     │  │
│  └────────────────────────┼──────────────────────────────────┘  │
│                           │                                      │
│  ┌────────────────────────▼──────────────────────────────────┐  │
│  │              Runtime Layer（运行时层）                       │  │
│  │  ┌──────────────────┐  ┌─────────────────────────────────┐│  │
│  │  │ ZCLAW Gateway  │  │ OpenViking Server (sidecar)     ││  │
│  │  │ (Node.js)         │  │ (Python, HTTP API on :1933)     ││  │
│  │  │ Port: 18789       │  │ Embedding + VLM + Storage       ││  │
│  │  └──────────────────┘  └─────────────────────────────────┘│  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │              Storage Layer（存储层）                         │  │
│  │  ┌──────────────┐ ┌──────────────┐ ┌───────────────────┐ │  │
│  │  │ OpenViking   │ │ Markdown     │ │ ZCLAW Config      │ │  │
│  │  │ Workspace    │ │ Identity     │ │ (Tauri AppData)   │ │  │
│  │  │ (向量+文本)   │ │ Files        │ │                   │ │  │
│  │  └──────────────┘ └──────────────┘ └───────────────────┘ │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

4.2 Phase 0：技术验证 POC（第 1 周）

目标：验证 OpenViking 在 ZCLAW 桌面端环境中可行

任务清单

#	任务	负责	输出	验收标准
0.1	在 Windows 上部署 OpenViking Server	基础设施	部署脚本	ov status 返回正常
0.2	测试 OpenViking Python 包在 Windows 的兼容性	基础设施	兼容性报告	pip install openviking 成功，CLI 可用
0.3	用 Tauri sidecar 管理 OpenViking Server 进程	后端	POC 代码	Tauri 应用启动时自动启动 OV Server
0.4	从 TypeScript 调用 OpenViking HTTP API	后端	API Client POC	成功执行 add-resource / find / grep
0.5	测试中文内容的写入和检索效果	AI/算法	检索效果报告	中文记忆写入后可被语义检索命中
0.6	评估 ZCLAW 记忆插件代码	后端	适配方案	确认适配路径和工作量

关键技术验证点

验证 1：OpenViking Server 进程管理

// src-tauri/src/viking_sidecar.rs

use tauri::Manager;
use std::process::Command;

pub fn start_viking_server(app: &tauri::App) -> Result<(), Box<dyn std::error::Error>> {
    let resource_dir = app.path().resource_dir()?;
    let viking_path = resource_dir.join("openviking-server");

    let child = Command::new(&viking_path)
        .env("OPENVIKING_CONFIG_FILE", get_viking_config_path(app)?)
        .spawn()?;

    // 存储进程 handle 以便退出时清理
    app.manage(VikingProcess(child));
    Ok(())
}

验证 2：TypeScript OpenViking Client

// src/lib/viking-client.ts

interface VikingClient {
  // 健康检查
  status(): Promise<VikingStatus>;

  // 资源管理
  addResource(uri: string, content: string, metadata?: Record<string, string>): Promise<void>;
  ls(path: string): Promise<VikingEntry[]>;
  tree(path: string, depth?: number): Promise<VikingTree>;

  // 检索
  find(query: string, options?: FindOptions): Promise<FindResult[]>;
  grep(pattern: string, options?: GrepOptions): Promise<GrepResult[]>;

  // 记忆管理
  saveMemory(path: string, content: string, level?: 'L0' | 'L1' | 'L2'): Promise<void>;
  readMemory(path: string, level?: 'L0' | 'L1' | 'L2'): Promise<string>;

  // 会话管理
  extractMemories(sessionContent: string): Promise<ExtractedMemory[]>;
}

class VikingHttpClient implements VikingClient {
  constructor(private baseUrl: string = 'http://localhost:1933') {}

  async find(query: string, options?: FindOptions): Promise<FindResult[]> {
    const resp = await fetch(`${this.baseUrl}/api/find`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ query, ...options }),
    });
    return resp.json();
  }
  // ... 其他方法
}

Phase 0 成功标准

• ✅ OpenViking Server 在 Windows 上稳定运行
• ✅ Tauri 可管理 OV Server 生命周期
• ✅ TypeScript 可成功调用 OV HTTP API
• ✅ 中文内容写入后可被语义检索命中
• ✅ 记忆写入 → 检索延迟 < 500ms

---

4.3 Phase 1：核心记忆系统（第 2-4 周）

目标：Agent 从 L1（会话感知）跃迁到 L2（持久记忆）

4.3.1 VikingAdapter 实现

// src/lib/viking-adapter.ts

/**
 * ZCLAW 与 OpenViking 的适配层
 * 封装 OpenViking API，提供 ZCLAW 语义的记忆操作
 */
export class VikingAdapter {
  private client: VikingHttpClient;

  constructor(serverUrl: string = 'http://localhost:1933') {
    this.client = new VikingHttpClient(serverUrl);
  }

  // === 用户记忆 ===

  async saveUserPreference(key: string, value: string): Promise<void> {
    await this.client.addResource(
      `viking://user/memories/preferences/${key}`,
      value,
      { type: 'preference', auto_level: 'true' }
    );
  }

  async saveUserFact(category: string, content: string): Promise<void> {
    await this.client.addResource(
      `viking://user/memories/facts/${category}/${Date.now()}`,
      content,
      { type: 'fact', auto_level: 'true' }
    );
  }

  async searchUserMemories(query: string, limit: number = 10): Promise<MemoryResult[]> {
    return this.client.find(query, {
      scope: 'viking://user/memories/',
      limit,
      level: 'L1',  // 默认返回概览级别
    });
  }

  // === Agent 记忆 ===

  async saveAgentLesson(agentId: string, lesson: string, tags: string[]): Promise<void> {
    await this.client.addResource(
      `viking://agent/${agentId}/memories/lessons_learned/${Date.now()}`,
      lesson,
      { tags: tags.join(','), type: 'lesson', auto_level: 'true' }
    );
  }

  async saveAgentTaskPattern(agentId: string, pattern: string): Promise<void> {
    await this.client.addResource(
      `viking://agent/${agentId}/memories/task_patterns/${Date.now()}`,
      pattern,
      { type: 'pattern', auto_level: 'true' }
    );
  }

  async searchAgentMemories(
    agentId: string,
    query: string,
    limit: number = 10
  ): Promise<MemoryResult[]> {
    return this.client.find(query, {
      scope: `viking://agent/${agentId}/memories/`,
      limit,
      level: 'L1',
    });
  }

  // === 上下文构建（核心）===

  async buildEnhancedContext(
    userMessage: string,
    agentId: string,
    options?: { maxTokens?: number }
  ): Promise<EnhancedContext> {
    const maxTokens = options?.maxTokens ?? 8000;

    // Step 1: L0 快速扫描
    const l0UserMemories = await this.client.find(userMessage, {
      scope: 'viking://user/memories/',
      level: 'L0',
      limit: 30,
    });
    const l0AgentMemories = await this.client.find(userMessage, {
      scope: `viking://agent/${agentId}/memories/`,
      level: 'L0',
      limit: 30,
    });

    // Step 2: 筛选高相关项，加载 L1
    const relevant = [...l0UserMemories, ...l0AgentMemories]
      .filter(r => r.score > 0.6)
      .sort((a, b) => b.score - a.score)
      .slice(0, 15);

    const l1Results = await Promise.all(
      relevant.map(r => this.client.readMemory(r.uri, 'L1'))
    );

    // Step 3: Token 预算控制
    let tokenBudget = maxTokens;
    const contextItems: ContextItem[] = [];

    for (const item of l1Results) {
      const itemTokens = estimateTokens(item.content);
      if (tokenBudget - itemTokens < 0) break;
      contextItems.push(item);
      tokenBudget -= itemTokens;
    }

    return {
      memories: contextItems,
      totalTokens: maxTokens - tokenBudget,
      retrievalTrace: this.buildTrace(l0UserMemories, l0AgentMemories, relevant),
    };
  }

  // === 会话记忆提取 ===

  async extractAndSaveMemories(
    messages: Message[],
    agentId: string,
    conversationId: string
  ): Promise<ExtractionResult> {
    // 调用 OpenViking 的自动会话管理
    const result = await this.client.extractMemories(
      messages.map(m => `[${m.role}]: ${m.content}`).join('\n')
    );

    // 分类保存
    for (const memory of result.userMemories) {
      await this.saveUserFact(memory.category, memory.content);
    }
    for (const memory of result.agentMemories) {
      await this.saveAgentLesson(agentId, memory.content, memory.tags);
    }

    return {
      saved: result.userMemories.length + result.agentMemories.length,
      userMemories: result.userMemories.length,
      agentMemories: result.agentMemories.length,
    };
  }
}

4.3.2 ChatStore 集成

// 修改 desktop/src/store/chatStore.ts

// 在 sendMessage 流程中注入记忆
sendMessage: async (content: string) => {
  // ... 现有逻辑 ...

  // 🆕 构建增强上下文
  const viking = getVikingAdapter();
  const enhancedContext = await viking.buildEnhancedContext(
    content,
    currentAgent.id,
    { maxTokens: 8000 }
  );

  // 🆕 将记忆注入到系统提示
  const systemPromptWithMemory = buildSystemPrompt(
    agentIdentity,
    enhancedContext.memories
  );

  // 发送到 Gateway（带增强上下文）
  await client.chat(content, {
    sessionKey,
    systemPrompt: systemPromptWithMemory,
  });
},

// 🆕 在流式完成后触发记忆提取
onStreamComplete: async (messages, agentId, conversationId) => {
  const viking = getVikingAdapter();
  const result = await viking.extractAndSaveMemories(
    messages, agentId, conversationId
  );
  console.log(`[Memory] 提取了 ${result.saved} 条记忆`);
},

4.3.3 记忆面板 UI

// src/components/MemoryPanel.tsx

// 功能：
// 1. 记忆浏览（viking:// 目录树视图）
// 2. 记忆搜索（语义搜索 + 关键词搜索）
// 3. 记忆详情（L0/L1/L2 分层查看）
// 4. 记忆删除（用户手动遗忘）
// 5. 检索轨迹查看（最近一次对话的检索路径）
// 6. Token 消耗统计（L0/L1/L2 分布饼图）

4.3.4 身份文件动态化

每个 Agent 的身份文件同时存在于两个位置：

1. 本地文件系统（可编辑，Git 友好）
   ~/.zclaw/agents/<agentId>/SOUL.md
   ~/.zclaw/agents/<agentId>/AGENTS.md
   ~/.zclaw/agents/<agentId>/USER.md

2. OpenViking（可检索，语义索引）
   viking://agent/<agentId>/identity/soul
   viking://agent/<agentId>/identity/instructions
   viking://agent/<agentId>/identity/user_profile

同步机制：
- 本地文件修改 → 自动同步到 OpenViking
- Agent 建议修改 → 先写入 viking://agent/<id>/identity/changelog → 用户审批 → 同步到本地文件

Phase 1 交付物

交付物	文件路径	描述
VikingAdapter	src/lib/viking-adapter.ts	OpenViking 适配层
VikingClient	src/lib/viking-client.ts	HTTP API Client
ContextBuilder	src/lib/context-builder.ts	L0/L1/L2 分层上下文构建
MemoryExtractor	src/lib/memory-extractor.ts	对话记忆自动提取
AgentIdentity	src/lib/agent-identity.ts	身份文件管理 + 双向同步
MemoryPanel	src/components/MemoryPanel.tsx	记忆浏览/搜索/删除 UI
RetrievalTrace	src/components/RetrievalTrace.tsx	检索轨迹可视化
ChatStore 改造	src/store/chatStore.ts	集成记忆注入 + 提取
单元测试	tests/desktop/viking-*.test.ts	覆盖核心逻辑

Phase 1 验收标准

• ✅ 对话结束后自动提取记忆到 OpenViking
• ✅ 新对话前自动检索并注入相关历史记忆
• ✅ Agent 能说出"上次你提到过 XXX"
• ✅ 用户可在 MemoryPanel 中浏览、搜索、删除记忆
• ✅ 检索轨迹可视化，可观察 Agent 的"思考路径"
• ✅ Token 消耗相比全量注入降低 >60%
• ✅ 身份文件每个 Agent 独立，支持 UI 编辑

---

4.4 Phase 2：上下文治理 + 主动智能（第 5-8 周）

目标：巩固 L2 + 初步达到 L3（主动智能）

4.4.1 自动会话管理（上下文压缩 + 记忆冲刷）

// src/lib/session-manager.ts

class SessionManager {
  private viking: VikingAdapter;
  private compactionConfig = {
    softThresholdTokens: 15000,
    reserveTokens: 4000,
    memoryFlushEnabled: true,
  };

  // 上下文窗口监控
  async checkAndCompact(messages: Message[], agentId: string): Promise<Message[]> {
    const totalTokens = estimateTokens(messages);
    const threshold = this.compactionConfig.softThresholdTokens;

    if (totalTokens < threshold) return messages;

    // Step 1: 记忆冲刷（压缩前提取重要信息）
    if (this.compactionConfig.memoryFlushEnabled) {
      const oldMessages = messages.slice(0, -5); // 保留最近 5 条
      await this.viking.extractAndSaveMemories(oldMessages, agentId, 'compaction');
    }

    // Step 2: 调用 OpenViking 的会话压缩
    const summary = await this.viking.compactSession(messages);

    // Step 3: 替换旧消息为摘要
    return [
      { role: 'system', content: `[之前的对话摘要] ${summary}` },
      ...messages.slice(-5),
    ];
  }
}

4.4.2 Heartbeat 引擎

// src/lib/heartbeat-engine.ts

class HeartbeatEngine {
  private intervalId: NodeJS.Timer | null = null;
  private viking: VikingAdapter;

  async start(config: HeartbeatConfig): Promise<void> {
    this.intervalId = setInterval(async () => {
      if (this.isQuietHours(config)) return;

      const result = await this.tick(config);
      if (result.status === 'alert') {
        await this.notify(result.alerts, config.notifyChannel);
      }
    }, config.intervalMinutes * 60 * 1000);
  }

  private async tick(config: HeartbeatConfig): Promise<HeartbeatResult> {
    // 读取 HEARTBEAT.md 检查清单
    const checklist = await this.viking.readMemory(
      `viking://agent/${config.agentId}/identity/heartbeat`,
      'L2'
    );

    // 让 LLM 评估每个检查项
    const assessment = await this.assessChecklist(checklist);

    return assessment;
  }
}

4.4.3 Cron 定时任务增强

// src/lib/cron-scheduler.ts

class CronScheduler {
  // 增强现有的 scheduledTasks 系统
  // - 每个任务在独立会话中执行（不污染主对话）
  // - 执行结果自动存入 viking://agent/<id>/memories/task_results/
  // - 支持飞书/桌面通知推送
}

Phase 2 交付物

交付物	描述
SessionManager	自动压缩 + 记忆冲刷
HeartbeatEngine	主动巡检引擎
CronScheduler	增强的定时任务调度
HeartbeatConfig UI	心跳配置面板
桌面通知集成	Tauri 原生通知 + 飞书推送

Phase 2 验收标准

• ✅ 超长对话自动压缩，关键信息不丢失
• ✅ Heartbeat 按配置间隔执行巡检
• ✅ 用户可编辑 HEARTBEAT.md 自定义检查项
• ✅ 定时任务在独立会话中执行，结果可查看
• ✅ 桌面通知正常推送

---

4.5 Phase 3：自我演化 + 多 Agent 协作（第 9-14 周）

目标：达到 L3+，向 L4 迈进

4.5.1 自我反思循环

// src/lib/reflection-engine.ts

class ReflectionEngine {
  // 定期分析最近对话，提取行为模式
  // 生成改进建议
  // 如建议修改 SOUL.md/AGENTS.md → 用户审批流
  // 所有反思记录存入 viking://agent/<id>/memories/reflections/
}

4.5.2 多 Agent 协作

// src/lib/agent-swarm.ts

class AgentSwarm {
  // 利用 OpenViking 的 viking://agent/swarm/ 命名空间
  // 协调多个 Agent 处理复杂任务
  // 任务分解 → 分配 → 执行 → 结果聚合
  // 共享记忆通过 viking://agent/shared/ 传递
}

4.5.3 技能自主发现

// src/lib/skill-discovery.ts

class SkillDiscovery {
  // 分析用户需求 → 搜索 viking://agent/<id>/skills/available/
  // 如果现有技能不足 → 建议安装新技能
  // 新技能信息存入 viking://agent/<id>/skills/learned/
}

---

4.6 分阶段里程碑总览

Week 1        Week 2-4       Week 5-8        Week 9-14
  │              │              │               │
  ▼              ▼              ▼               ▼
┌─────┐    ┌─────────┐    ┌─────────┐    ┌──────────┐
│Phase│    │ Phase 1  │    │ Phase 2 │    │ Phase 3  │
│  0  │    │          │    │         │    │          │
│     │    │ 核心记忆  │    │上下文治理│    │ 自我演化  │
│ POC │    │ L1 → L2  │    │ L2巩固  │    │ L3 → L4  │
│验证  │    │          │    │+ L3初步 │    │          │
└──┬──┘    └────┬─────┘    └────┬────┘    └────┬─────┘
   │            │               │              │
   ▼            ▼               ▼              ▼
 OV可用     Agent记住你      Agent主动帮你   Agent自我成长
 中文OK     记忆可视化      心跳+定时任务    多Agent协作
 API通      Token降60%     压缩不丢信息    技能自发现

---

五、RACI 责任分工矩阵

任务	产品	前端	后端	AI/算法	基础设施	测试
Phase 0: POC
OV 部署与验证	I	I	C	C	R	I
API Client POC	I	I	R	C	A	I
中文检索测试	I	I	C	R	A	C
Phase 1: 核心记忆
VikingAdapter	C	I	R	C	A	I
ContextBuilder	C	I	R	R	A	I
MemoryExtractor	C	I	C	R	A	I
MemoryPanel UI	R	R	C	I	I	C
RetrievalTrace UI	C	R	C	I	I	C
ChatStore 集成	C	R	C	I	I	C
测试用例	C	C	C	C	I	R
Phase 2: 主动智能
SessionManager	C	I	R	C	A	C
HeartbeatEngine	R	C	R	C	A	C
CronScheduler	C	I	R	I	A	C
HeartbeatConfig UI	R	R	C	I	I	C
桌面通知	C	R	I	I	C	C
Phase 3: 自我演化
ReflectionEngine	C	I	C	R	A	C
AgentSwarm	R	C	R	R	A	C
SkillDiscovery	R	R	C	C	I	C

R=Responsible(执行), A=Accountable(负责), C=Consulted(咨询), I=Informed(知会)

---

六、关键技术决策（需在头脑风暴中确认）

决策 1：OpenViking Server 部署模式

选项	描述	推荐
A. Tauri Sidecar	打包进安装包，应用启动时自动启动	✅ 推荐（桌面产品最佳体验）
B. 独立安装	用户自己安装 OpenViking	❌ 用户体验差
C. 云端服务	连接远程 OpenViking 实例	作为高级选项

决策 2：Embedding 模型选型

选项	维度	成本	中文效果	推荐
doubao-embedding-vision-250615	1024	低（火山引擎）	✅ 优秀	✅ 中国用户推荐
text-embedding-3-large	3072	中	✅ 良好	国际用户推荐
jina-embeddings-v3	1024	中	✅ 良好	备选
本地 Ollama	可变	免费	⚠️ 取决于模型	离线场景

决策 3：VLM 模型选型

选项	用途	推荐
doubao-seed-2-0-pro	语义处理、L0/L1 生成	✅ 推荐（与 ZCLAW 中国模型策略对齐）
gpt-4o	语义处理	备选
通过 LiteLLM 接入用户自选模型	灵活性	中长期目标

决策 4：记忆提取时机

选项	触发条件	推荐
A. 对话结束后	流式完成 + 3 秒无新消息	✅ 推荐（Phase 1）
B. 压缩前 + 对话结束后	软阈值触发 + 对话结束	✅ 推荐（Phase 2）
C. 每条消息后	实时	❌ 成本过高

决策 5：Python 依赖打包方案

选项	描述	安装包增量	推荐
A. PyInstaller 冻结	将 OV Server 编译为独立可执行文件	~200MB	✅ 推荐
B. 内嵌 Python	Tauri 包含 Python 运行时	~100MB	⚠️ 复杂
C. 要求用户安装 Python	依赖用户环境	0	❌ 用户体验差
D. Rust CLI 替代	使用 ov_cli Rust 版本	~10MB	✅ 探索中（功能可能不完整）

---

七、风险与缓解

风险	影响	概率	缓解措施
OpenViking Windows 兼容性问题	阻塞 Phase 0	中	提前在 Phase 0 验证；备选方案：WSL2
Python 依赖打包困难	安装包过大/复杂	高	优先评估 Rust CLI；PyInstaller 冻结作为保底
中文语义检索效果不理想	记忆质量下降	低	Phase 0 预研；可选调优 Embedding 模型
OpenViking Server 资源消耗大	桌面性能下降	中	监控内存/CPU；配置低资源模式
API 不稳定/不够成熟	集成困难	中	封装 VikingAdapter 隔离变化；参与社区反馈
与现有 ZCLAW Gateway 冲突	两套运行时共存问题	低	端口隔离；VikingAdapter 统一入口

---

八、预期成果

短期（Phase 0-1 完成后）

• ZCLAW Agent 具备持久记忆能力，能记住用户偏好和项目上下文
• Token 消耗降低 60-80%（得益于 L0/L1/L2 分层加载）
• 用户可视化查看 Agent 的记忆和检索路径
• 用户感知：从"每次都要重新说"到"它认识我了"

中期（Phase 2 完成后）

• Agent 主动巡检并通知重要事项
• 超长对话不丢失关键信息
• 定时任务可靠执行
• 用户感知：从"被动工具"到"主动伙伴"

长期（Phase 3 完成后）

• Agent 持续自我改进
• 多 Agent 协作处理复杂任务
• 技能自主发现和推荐
• 用户感知：从"伙伴"到"自主智能体"

---

九、立即可执行的行动

本周（Phase 0 启动）

#	行动	负责人	产出
1	Windows 上 pip install openviking 并运行 openviking-server	基础设施	部署验证报告
2	测试 ov add-resource + ov find 中文内容	AI/算法	中文效果报告
3	阅读 OpenViking ZCLAW 记忆插件源码	后端	适配方案评估
4	创建 src/lib/viking-client.ts HTTP API Client	后端	TypeScript Client
5	设计记忆面板 UX 草图	产品+前端	线框图
6	发出头脑风暴会议邀请 + 会前材料	产品	日历邀请

下周（Phase 0 → Phase 1 过渡）

#	行动
7	Tauri sidecar 管理 OV Server 进程 POC
8	VikingAdapter 核心接口实现
9	ContextBuilder L0/L1/L2 分层加载实现
10	召开跨部门头脑风暴（确认方案）

---

附录：OpenViking 技术参考

核心链接

• GitHub: https://github.com/volcengine/OpenViking
• 文档: https://www.openviking.ai/docs
• ZCLAW 记忆插件: examples/zclaw-memory-plugin/
• VikingBot: bot/README.md

API 端点速查

端点	方法	用途
/api/status	GET	健康检查
/api/resources	POST	添加资源
/api/find	POST	语义检索
/api/grep	POST	关键词搜索
/api/ls	GET	列出目录内容
/api/tree	GET	目录树
/api/session/extract	POST	会话记忆提取

OpenViking 配置模板（ZCLAW 定制）

{
  "storage": {
    "workspace": "${ZCLAW_DATA_DIR}/openviking_workspace"
  },
  "log": {
    "level": "INFO",
    "output": "file"
  },
  "embedding": {
    "dense": {
      "api_base": "${EMBEDDING_API_BASE}",
      "api_key": "${EMBEDDING_API_KEY}",
      "provider": "volcengine",
      "dimension": 1024,
      "model": "doubao-embedding-vision-250615"
    },
    "max_concurrent": 5
  },
  "vlm": {
    "api_base": "${VLM_API_BASE}",
    "api_key": "${VLM_API_KEY}",
    "provider": "volcengine",
    "model": "doubao-seed-2-0-pro-260215",
    "max_concurrent": 10
  }
}