# ZCLAW × OpenViking 跨部门头脑风暴与开发实施方案 > **文档日期**：2026-03-15 > **定位**：基于 OpenViking（火山引擎开源 AI 智能体上下文数据库）技术，结合 ZCLAW Agent 智能演化需求，制定跨部门协作的完整开发方案 > **关联文档**： > - [`ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md`](./ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md) — Agent 智能差距分析 > - [`ZCLAW_NEXT_EVOLUTION_STRATEGY.md`](./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（中文）](https://github.com/volcengine/OpenViking/blob/main/README_CN.md) 3. [`ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md`](./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 维度 ├── / │ ├── 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// ← 每个 Agent 的身份、记忆、技能 ├── resources/ ← 工作区文件、项目知识 └── agent/shared/ ← 跨 Agent 共享知识 ``` **价值**：所有上下文通过统一的 `viking://` 协议访问，消除碎片化。 ### 3.2 分层上下文加载 → ZCLAW 的 Token 成本控制 **OpenViking 核心**：L0（摘要 ~100 tokens）→ L1（概览 ~2k tokens）→ L2（详情 完整内容） **ZCLAW 映射**： ```typescript // 每次对话前的上下文构建 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//memories/lessons_learned/ │ → "用户喜欢先看方案再动手" → viking://agent//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 进程管理** ```rust // src-tauri/src/viking_sidecar.rs use tauri::Manager; use std::process::Command; pub fn start_viking_server(app: &tauri::App) -> Result<(), Box> { 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** ```typescript // src/lib/viking-client.ts interface VikingClient { // 健康检查 status(): Promise; // 资源管理 addResource(uri: string, content: string, metadata?: Record): Promise; ls(path: string): Promise; tree(path: string, depth?: number): Promise; // 检索 find(query: string, options?: FindOptions): Promise; grep(pattern: string, options?: GrepOptions): Promise; // 记忆管理 saveMemory(path: string, content: string, level?: 'L0' | 'L1' | 'L2'): Promise; readMemory(path: string, level?: 'L0' | 'L1' | 'L2'): Promise; // 会话管理 extractMemories(sessionContent: string): Promise; } class VikingHttpClient implements VikingClient { constructor(private baseUrl: string = 'http://localhost:1933') {} async find(query: string, options?: FindOptions): Promise { 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 实现 ```typescript // 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 { await this.client.addResource( `viking://user/memories/preferences/${key}`, value, { type: 'preference', auto_level: 'true' } ); } async saveUserFact(category: string, content: string): Promise { 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 { return this.client.find(query, { scope: 'viking://user/memories/', limit, level: 'L1', // 默认返回概览级别 }); } // === Agent 记忆 === async saveAgentLesson(agentId: string, lesson: string, tags: string[]): Promise { 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 { 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 { return this.client.find(query, { scope: `viking://agent/${agentId}/memories/`, limit, level: 'L1', }); } // === 上下文构建（核心）=== async buildEnhancedContext( userMessage: string, agentId: string, options?: { maxTokens?: number } ): Promise { 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 { // 调用 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 集成 ```typescript // 修改 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 ```typescript // 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//SOUL.md ~/.zclaw/agents//AGENTS.md ~/.zclaw/agents//USER.md 2. OpenViking（可检索，语义索引） viking://agent//identity/soul viking://agent//identity/instructions viking://agent//identity/user_profile 同步机制： - 本地文件修改 → 自动同步到 OpenViking - Agent 建议修改 → 先写入 viking://agent//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 自动会话管理（上下文压缩 + 记忆冲刷） ```typescript // 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 { 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 引擎 ```typescript // src/lib/heartbeat-engine.ts class HeartbeatEngine { private intervalId: NodeJS.Timer | null = null; private viking: VikingAdapter; async start(config: HeartbeatConfig): Promise { 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 { // 读取 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 定时任务增强 ```typescript // src/lib/cron-scheduler.ts class CronScheduler { // 增强现有的 scheduledTasks 系统 // - 每个任务在独立会话中执行（不污染主对话） // - 执行结果自动存入 viking://agent//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 自我反思循环 ```typescript // src/lib/reflection-engine.ts class ReflectionEngine { // 定期分析最近对话，提取行为模式 // 生成改进建议 // 如建议修改 SOUL.md/AGENTS.md → 用户审批流 // 所有反思记录存入 viking://agent//memories/reflections/ } ``` #### 4.5.2 多 Agent 协作 ```typescript // src/lib/agent-swarm.ts class AgentSwarm { // 利用 OpenViking 的 viking://agent/swarm/ 命名空间 // 协调多个 Agent 处理复杂任务 // 任务分解 → 分配 → 执行 → 结果聚合 // 共享记忆通过 viking://agent/shared/ 传递 } ``` #### 4.5.3 技能自主发现 ```typescript // src/lib/skill-discovery.ts class SkillDiscovery { // 分析用户需求 → 搜索 viking://agent//skills/available/ // 如果现有技能不足 → 建议安装新技能 // 新技能信息存入 viking://agent//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 定制） ```json { "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 } } ```