diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..bb06550 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,52 @@ +# ZCLAW 文档中心 + +## 快速导航 + +| 文档 | 说明 | +|------|------| +| [开发指南](DEVELOPMENT.md) | 开发环境设置、构建、测试 | +| [OpenViking 集成](OPENVIKING_INTEGRATION.md) | 记忆系统集成文档 | +| [用户手册](USER_MANUAL.md) | 终端用户使用指南 | +| [Agent 进化计划](ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md) | Agent 智能层发展规划 | +| [工作总结](WORK_SUMMARY_2026-03-16.md) | 最新工作进展 | + +## 文档结构 + +``` +docs/ +├── DEVELOPMENT.md # 开发指南 +├── OPENVIKING_INTEGRATION.md # OpenViking 集成 +├── USER_MANUAL.md # 用户手册 +├── ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md # Agent 进化计划 +├── WORK_SUMMARY_*.md # 工作总结（按日期） +│ +├── archive/ # 归档文档 +│ ├── completed-plans/ # 已完成的计划 +│ ├── research-reports/ # 研究报告 +│ └── openclaw-legacy/ # OpenClaw 遗留文档 +│ +├── knowledge-base/ # 技术知识库 +│ ├── openfang-technical-reference.md # OpenFang 技术参考 +│ ├── openfang-websocket-protocol.md # WebSocket 协议 +│ ├── troubleshooting.md # 故障排除 +│ └── ... +│ +├── plans/ # 执行计划 +│ └── ... +│ +└── test-reports/ # 测试报告 + └── ... +``` + +## 项目状态 + +- **Agent 智能层**: Phase 1-3 完成（274 tests passing） +- **OpenViking 集成**: 本地服务器管理完成 +- **文档整理**: 完成 + +## 贡献指南 + +1. 新文档放在适当的目录中 +2. 使用清晰的文件命名（小写、连字符分隔） +3. 计划文件使用日期前缀：`YYYY-MM-DD-description.md` +4. 完成后将计划移动到 `archive/completed-plans/` diff --git a/docs/WORK_SUMMARY_2026-03-16.md b/docs/WORK_SUMMARY_2026-03-16.md new file mode 100644 index 0000000..c699991 --- /dev/null +++ b/docs/WORK_SUMMARY_2026-03-16.md @@ -0,0 +1,111 @@ +# ZCLAW 工作总结 - 2026-03-16 + +## 完成的工作 + +### 1. OpenViking 本地服务器管理（隐私优先部署） + +**问题**：用户可能有隐私顾虑，会话数据不能上传到远程服务器。 + +**解决方案**：实现本地 OpenViking 服务器管理功能。 + +#### 新增文件 + +| 文件 | 功能 | +|------|------| +| `desktop/src-tauri/src/viking_server.rs` | Rust 后端服务器管理（启动/停止/状态） | +| `desktop/src/lib/viking-server-manager.ts` | TypeScript 服务器管理客户端 | +| `desktop/src/lib/viking-adapter.ts` | 更新为多模式适配器（local/sidecar/remote） | + +#### 功能特性 + +- **自动模式检测**：优先尝试本地服务器 → sidecar → remote +- **隐私保证**：所有数据存储在 `~/.openviking/`，服务器只监听 `127.0.0.1` +- **优雅降级**：当本地服务器不可用时自动回退 + +#### Tauri 命令 + +```rust +viking_server_status() // 获取服务器状态 +viking_server_start() // 启动本地服务器 +viking_server_stop() // 停止服务器 +viking_server_restart() // 重启服务器 +``` + +### 2. 文档整理与归档 + +**之前**：文档散落在多个位置，文件名混乱（如 `greedy-prancing-cocke.md`） + +**之后**：规范化文档结构 + +``` +docs/ +├── DEVELOPMENT.md # 开发指南 +├── OPENVIKING_INTEGRATION.md # OpenViking 集成文档（已更新） +├── USER_MANUAL.md # 用户手册 +├── ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md # Agent 进化计划 +├── archive/ # 归档文档 +│ ├── completed-plans/ # 已完成的计划 +│ ├── research-reports/ # 研究报告 +│ └── openclaw-legacy/ # OpenClaw 遗留文档 +├── knowledge-base/ # 技术知识库 +│ ├── openfang-technical-reference.md +│ ├── openfang-websocket-protocol.md +│ └── ... +├── plans/ # 执行计划 +└── test-reports/ # 测试报告 +``` + +### 3. 测试验证 + +| 测试类型 | 结果 | +|---------|------| +| TypeScript 编译 | ✅ 无错误 | +| Viking Adapter 测试 | ✅ 21 passed | +| Rust 测试 | ✅ 10 passed | +| Cargo Build | ✅ 成功 | + +## 提交记录 + +``` +c8202d0 feat(viking): add local server management for privacy-first deployment +``` + +## 当前项目状态 + +### 已完成 + +- [x] Agent 智能层 Phase 1-3（274 passing tests） +- [x] OpenViking 本地服务器管理 +- [x] 文档结构整理 + +### 进行中 + +- [ ] OpenViking 真实 CLI 集成（需要用户安装 `pip install openviking`） +- [ ] 多 Agent 协作 UI 产品化 + +### 待办 + +- [ ] RuntimeAdapter 接口抽象 +- [ ] 领域模型标准化 + +## 下一步建议 + +1. **用户安装 OpenViking**： + ```bash + pip install openviking --upgrade + ``` + +2. **测试本地服务器**： + ```bash + openviking-server --version + ``` + +3. **验证集成**： + 启动 ZCLAW 桌面应用，检查记忆面板是否正常工作 + +## 文件变更统计 + +- 新增文件：4 个 +- 修改文件：3 个 +- 归档文件：10+ 个 +- 文档更新：1 个 diff --git a/docs/NEXT_SESSION.md b/docs/archive/NEXT_SESSION.md similarity index 100% rename from docs/NEXT_SESSION.md rename to docs/archive/NEXT_SESSION.md diff --git a/docs/SYSTEM_ANALYSIS.md b/docs/archive/SYSTEM_ANALYSIS.md similarity index 100% rename from docs/SYSTEM_ANALYSIS.md rename to docs/archive/SYSTEM_ANALYSIS.md diff --git a/docs/ZCLAW_NEXT_EVOLUTION_STRATEGY.md b/docs/archive/ZCLAW_NEXT_EVOLUTION_STRATEGY.md similarity index 100% rename from docs/ZCLAW_NEXT_EVOLUTION_STRATEGY.md rename to docs/archive/ZCLAW_NEXT_EVOLUTION_STRATEGY.md diff --git a/docs/architecture-v2.md b/docs/archive/architecture-v2.md similarity index 100% rename from docs/architecture-v2.md rename to docs/archive/architecture-v2.md diff --git a/docs/archive/completed-plans/ZCLAW_OPENVIKING_INTEGRATION_PLAN.md b/docs/archive/completed-plans/ZCLAW_OPENVIKING_INTEGRATION_PLAN.md new file mode 100644 index 0000000..ad930af --- /dev/null +++ b/docs/archive/completed-plans/ZCLAW_OPENVIKING_INTEGRATION_PLAN.md @@ -0,0 +1,1197 @@ +# 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 的量化优势（基于官方评测） + +| 指标 | OpenClaw 原生记忆 | OpenClaw + LanceDB | OpenClaw + 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. **开发更快**：已有 OpenClaw 记忆插件，可直接适配 +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 | 基础设施 | 部署文档 + 性能基准 | +| 阅读 OpenClaw 记忆插件源码，评估适配 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 OpenClaw 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 子进程 │ +│ ├── OpenClaw 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. **后端**：OpenClaw 记忆插件适配评估 +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（运行时层） │ │ +│ │ ┌──────────────────┐ ┌─────────────────────────────────┐│ │ +│ │ │ OpenClaw 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 | 评估 OpenClaw 记忆插件代码 | 后端 | 适配方案 | 确认适配路径和工作量 | + +#### 关键技术验证点 + +**验证 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 隔离变化；参与社区反馈 | +| **与现有 OpenClaw 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 OpenClaw 记忆插件源码 | 后端 | 适配方案评估 | +| 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 +- **OpenClaw 记忆插件**: `examples/openclaw-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 + } +} +``` diff --git a/docs/new-session-prompt-openfang-migration.md b/docs/archive/new-session-prompt-openfang-migration.md similarity index 100% rename from docs/new-session-prompt-openfang-migration.md rename to docs/archive/new-session-prompt-openfang-migration.md diff --git a/docs/openclaw-to-openfang-migration-brainstorm.md b/docs/archive/openclaw-to-openfang-migration-brainstorm.md similarity index 100% rename from docs/openclaw-to-openfang-migration-brainstorm.md rename to docs/archive/openclaw-to-openfang-migration-brainstorm.md diff --git a/docs/claw-ecosystem-deep-dive-report.md b/docs/archive/research-reports/claw-ecosystem-deep-dive-report.md similarity index 100% rename from docs/claw-ecosystem-deep-dive-report.md rename to docs/archive/research-reports/claw-ecosystem-deep-dive-report.md diff --git a/docs/openfang-technical-reference.md b/docs/knowledge-base/openfang-technical-reference.md similarity index 100% rename from docs/openfang-technical-reference.md rename to docs/knowledge-base/openfang-technical-reference.md diff --git a/docs/plans/2026-03-12-zclaw-delivery-execution-plan.md b/docs/plans/2026-03-12-zclaw-delivery-execution-plan.md new file mode 100644 index 0000000..ac7b5e0 --- /dev/null +++ b/docs/plans/2026-03-12-zclaw-delivery-execution-plan.md @@ -0,0 +1,467 @@ +# ZCLAW 交付执行计划（2026-03-12） + +## 1. 计划目标 + +本计划的目标不是继续做“功能堆叠”，而是把当前仓库推进到**可安装、可启动、可连接、可对话、可配置、可验证**的可交付状态。 + +当前对“完整可用 ZCLAW”的定义如下： + +- 用户能够在本机启动 ZCLAW 桌面应用 +- 用户安装 ZCLAW 时，OpenClaw 运行时已经随包提供，而不是要求用户另行安装 +- 桌面应用能够引导并管理随 ZCLAW 一起分发的本地 OpenClaw Gateway +- 前端能够稳定连接 Gateway，并完成基础握手与鉴权 +- 用户能够创建、编辑、切换 Agent（Clone） +- 用户能够发起真实对话并收到流式回复 +- 关键设置页不再只是静态占位，而是尽量接到真实后端能力 +- 有一套清晰的验收与收尾流程，支持阶段性提交与后续发布 + +--- + +## 2. 当前基线 + +### 2.1 已完成的关键能力 + +- Gateway 握手参数已修正，能够兼容 OpenClaw 2026.3.11 +- Token 鉴权已接入前端连接流程 +- `zclaw-ui` 插件可被 Gateway 正常加载 +- Agent 的创建、编辑、保存链路已打通 +- `scripts/setup.ts` 已可在已有 `~/.openclaw/openclaw.json` 时非破坏性合并插件与 skills 路径 +- 自定义插件 manifest/package id 对齐问题已修复 + +### 2.2 当前仍阻塞交付的核心问题 + +按交付优先级排序，当前最关键的缺口为： + +1. **桌面端尚未真正接管 Gateway 生命周期** + - `src/gateway/manager.ts` 已存在，但未被 Tauri 壳使用 + - `desktop/src-tauri/src/lib.rs` 仍是默认模板 + - 当前产品更像“前端连接外部 Gateway”，还不是“完整桌面应用” + +2. **当前仍默认依赖用户独立安装 OpenClaw** + - 这与最终产品目标不一致 + - 最终必须做到：安装 ZCLAW 后即可直接使用 OpenClaw 能力 + - 因此现阶段的 CLI/PATH 依赖只能作为开发期和过渡期方案 + +3. **真实桌面链路缺少本地运行闭环验证** + - 需要验证 Tauri 内从启动 Gateway 到连接、到拉数据、到发消息的完整过程 + +4. **设置体系中仍有若干页面/按钮处于占位状态** + - 部分页面已有 UI 但尚未连接真实能力 + - 会影响“可用”判断，尤其是用户首次体验 + +5. **交付收尾缺少固定验收流程** + - 需要统一 smoke test、安装前检查、文档更新、阶段提交点 + +--- + +## 3. 总体推进策略 + +### 3.1 核心原则 + +- **先打通闭环，再做扩展**：优先修复阻塞真实使用的能力缺口，而不是继续加功能 +- **优先最短交付路径**：优先复用 OpenClaw 现有 CLI/service 能力，而不是一开始就做完整 sidecar 架构 +- **最终必须内置 OpenClaw**：开发阶段允许复用系统已安装的 OpenClaw，但交付阶段必须改为随 ZCLAW 一起分发和托管 +- **浏览器模式不回退**：新增 Tauri 能力必须有运行时保护，不影响现有浏览器预览/开发体验 +- **阶段可提交**：每个阶段都有独立验收标准，达到后可形成 clean checkpoint + +### 3.2 本轮优先级 + +- **P0**：Tauri 桌面壳接入本地 Gateway 生命周期管理 +- **P0**：完成真实桌面端基础闭环验证 +- **P0**：确定并落地“ZCLAW 安装即内置 OpenClaw”的分发方案 +- **P1**：补齐最影响可用性的设置页占位项 +- **P1**：形成交付前 smoke checklist 和文档更新 +- **P2**：补测试、清理遗留代码、准备打包发布 + +--- + +## 4. 分阶段执行计划 + +## Phase A：桌面端本地 Gateway 生命周期管理（当前最高优先级） + +### A.1 目标 + +让 ZCLAW 桌面应用在 Tauri 环境下具备对本地 OpenClaw Gateway 的基础管理能力： + +- 查询本地 Gateway 状态 +- 启动本地 Gateway +- 停止本地 Gateway +- 重启本地 Gateway +- 在前端展示本地状态，并与现有 WebSocket 连接状态区分开 + +### A.2 实现策略 + +优先采用**Tauri Rust 命令封装 OpenClaw CLI** 的方式，而不是直接引入完整 sidecar： + +- Rust 侧封装以下命令： + - `openclaw gateway status --json` + - `openclaw gateway start --json` + - `openclaw gateway stop --json` + - `openclaw gateway restart --json` +- 前端通过 `invoke` 调用 Rust 命令 +- 通过运行时判断，仅在 Tauri 环境中启用这组能力 +- 浏览器模式继续保留“手工连接外部 Gateway”的现有逻辑 + +说明： + +- 这一阶段是**开发期过渡方案** +- 它的价值是先把桌面端产品闭环跑通 +- 但它**不是最终交付形态** +- 最终交付必须把 OpenClaw 运行时随 ZCLAW 一起打包，而不是要求用户本机已有 `openclaw` + +### A.3 代码范围 + +- `desktop/src-tauri/src/lib.rs` +- `desktop/src/lib/tauri-gateway.ts`（新增） +- `desktop/src/store/gatewayStore.ts` +- `desktop/src/components/Settings/General.tsx` +- 如有必要：`desktop/src/components/RightPanel.tsx` + +### A.4 验收标准 + +- Tauri 环境可正常调用本地 Gateway 管理命令 +- 设置页能看到“本地 Gateway”状态卡片 +- 用户可点击启动/停止/重启 +- 启动成功后，前端可继续连接并拉取基础数据 +- 浏览器模式不因该改动而报错或白屏 +- 开发环境下，即使仍依赖系统 `openclaw`，也已经明确与最终 bundling 方案解耦 + +### A.5 风险与应对 + +- **风险**：不同机器上 `openclaw` 不在 PATH + - **应对**：前端明确提示“未安装 OpenClaw CLI”或“命令不可用” +- **风险**：`status --json` / `start --json` 输出结构不稳定 + - **应对**：Rust 侧优先使用 `serde_json::Value` 宽松解析，再映射到前端稳定结构 +- **风险**：服务模式与前台 `gateway run` 并存导致认知混乱 + - **应对**：UI 文案明确说明“本地服务状态”和“当前 WebSocket 连接状态”是两层状态 + +--- + +## Phase B：真实桌面端基础闭环验证 + +### B.1 目标 + +确认 ZCLAW 在 Tauri 壳内已经不是“能打开 UI”，而是“能完成一次真实任务闭环”： + +- 本地 Gateway 启动/可达 +- 前端连接成功 +- Clone 列表加载成功 +- Agent 创建/编辑成功 +- 首条消息发送成功 +- 收到真实流式回复 + +### B.2 任务清单 + +- 启动桌面应用并检查本地 Gateway 状态 +- 验证连接状态、版本、插件状态、workspace 信息是否能拉取 +- 验证创建 Agent +- 验证编辑 Agent 并刷新右侧面板数据 +- 验证 bootstrap 文件生成状态 +- 验证聊天发送与回复流 +- 记录关键报错与回退路径 + +### B.3 验收标准 + +- 至少完成一次完整桌面端对话闭环 +- Agent 的创建与编辑在真实环境可用 +- 连接失败、Gateway 未安装、未启动等错误能明确提示 +- 关键路径没有阻塞性的控制台报错 + +--- + +## Phase C：OpenClaw 随包分发与运行时托管 + +### C.1 目标 + +把当前“依赖用户本机单独安装 OpenClaw”的开发态方案，推进到真正可交付的产品方案： + +- 用户安装 ZCLAW 时，OpenClaw 运行时已经包含在安装包内 +- ZCLAW 启动后，能够直接找到并启动内置 OpenClaw +- 用户不需要再单独安装一套 OpenClaw CLI / 环境 + +### C.2 目标形态 + +最终交付建议采用以下形态： + +- 安装包内包含 OpenClaw 可执行运行时或受控分发产物 +- Tauri Rust 侧通过固定相对路径或 sidecar 机制调用该运行时 +- ZCLAW 负责： + - 初始化 OpenClaw home / workspace + - 写入或合并默认配置 + - 启动 / 停止 / 重启 Gateway + - 读取日志与状态 + +### C.3 方案比较 + +#### 方案 1：继续依赖系统安装的 `openclaw` + +优点： + +- 当前开发改造最少 + +缺点： + +- 不符合最终产品目标 +- 用户安装体验差 +- 环境差异和 PATH 问题会显著增加支持成本 + +结论： + +- **仅适合开发期，不可作为最终交付方案** + +#### 方案 2：把 OpenClaw 作为 sidecar / bundled runtime 随 ZCLAW 分发 + +优点： + +- 符合 QClaw / AutoClaw 式的一体化交付体验 +- 可控性高 +- 便于做安装后自启动、版本锁定、升级兼容 + +缺点： + +- 需要处理体积、签名、跨平台打包、路径定位 + +结论： + +- **这是最终推荐方案** + +### C.4 实施任务 + +- 确认 OpenClaw 可分发形态 + - npm 包直接落地 + - 预构建二进制 + - 内置 Node + OpenClaw 组合运行时 +- 确认 Tauri 2 下 sidecar / bundled binary 的最佳实现方式 +- 为 Windows 优先落地一版 bundling 方案 +- 调整 Rust 侧命令执行逻辑 + - 优先调用内置运行时 + - 开发模式可回退到系统 `openclaw` +- 验证安装后首次启动流程 + - 不依赖用户额外安装 + - 可直接启动 Gateway + - 可连接、可聊天、可配置 + +### C.5 验收标准 + +- 全新机器上，未单独安装 OpenClaw 的情况下，可直接安装并启动 ZCLAW +- ZCLAW 可成功拉起内置 OpenClaw Gateway +- Agent / 聊天 / 设置等核心功能可正常工作 +- 用户文档不再要求“先安装 OpenClaw 再使用 ZCLAW” + +--- + +## Phase D：设置页可用性补齐 + +### D.1 目标 + +梳理 Settings 体系中“看起来像功能、实际上还是占位”的部分，优先补齐最影响交付感知的项。 + +### D.2 优先补齐范围 + +优先级从高到低建议如下： + +1. **General / ModelsAPI** + - Gateway 管理与连接语义统一 + - 去掉误导性按钮或接到真实逻辑 + +2. **Workspace / Skills / MCPServices** + - 至少展示真实读取结果 + - 对未支持能力明确标注“暂未接入”而不是伪交互 + +3. **IMChannels** + - 飞书状态尽量走真实探测 + - 对未完成渠道使用明确状态说明 + +4. **Privacy / UsageStats / About** + - 以展示真实数据和静态说明为主，收尾体验 + +### D.3 判定标准 + +- 对用户可点击的动作，尽量有真实效果 +- 对暂未接入的能力，明确说明而不是假按钮 +- 页面不出现明显“假功能”感 + +--- + +## Phase E：交付前 smoke test 与文档收尾 + +### E.1 目标 + +形成一套最小但明确的交付前检查流程，避免“本地看起来能用、别人拿到跑不起来”。 + +### E.2 交付前 smoke checklist + +#### 环境检查 + +- `pnpm -v` +- `pnpm --dir desktop tauri --version` + +说明： + +- 最终交付 smoke test 不应再把系统级 `openclaw --version` 作为前置要求 +- 应改为验证 ZCLAW 内置运行时是否可用 + +#### 桌面启动检查 + +- `pnpm --dir desktop tauri dev` +- UI 能正常打开 +- 设置页不白屏 + +#### Gateway 闭环检查 + +- 本地 Gateway 状态可读 +- 能启动/停止/重启 +- 前端连接成功 + +#### 核心功能检查 + +- Clone 列表加载 +- 新建 Clone +- 编辑 Clone +- 发送首条消息 +- 收到流式回复 + +#### 配置检查 + +- quick config 可读写 +- workspace 信息可读取 +- 插件状态可显示 + +#### 安装闭环检查 + +- 全新环境中无需单独安装 OpenClaw +- 安装 ZCLAW 后首次启动即可使用 +- 若内置运行时损坏或缺失，错误提示明确 + +### E.3 文档更新项 + +- 更新 README：区分浏览器模式与 Tauri 桌面模式 +- 补充本地 Gateway 启动/连接说明 +- 补充已知限制与后续路线 +- 在 `PROGRESS.md` 中登记本轮交付成果 + +--- + +## Phase F：交付后加强项（不是当前阻塞项） + +以下事项重要，但不应阻塞本轮“完整可用”目标： + +- 更完整的 Tauri sidecar / 进程托管架构 +- 安装包/自动更新 +- 更高覆盖率测试 +- v1 归档代码清理 +- 微信 / QQ Channel 扩展 +- 新 Session Prompt 等增强功能 + +这些能力应在当前闭环稳定后进入下一轮计划。 + +--- + +## 5. 实施顺序与里程碑 + +## Milestone 1：桌面端本地 Gateway 管理打通 + +输出物： + +- Tauri 命令桥 +- 前端本地 Gateway 状态卡片 +- 启停/重启操作 + +完成标志： + +- 能在桌面应用中看到并操作本地 Gateway 服务状态 + +## Milestone 2：真实桌面闭环通过 + +输出物： + +- 真实运行验证记录 +- 阻塞 bug 列表（若有） +- 修复后的可用路径 + +完成标志： + +- 从桌面打开到完成一次对话全链路可用 + +## Milestone 3：OpenClaw 随包分发打通 + +输出物： + +- Windows 优先的一体化 bundling 方案 +- ZCLAW 优先调用内置 OpenClaw 运行时 +- 安装后无需用户额外安装 OpenClaw 的可运行链路 + +完成标志： + +- 在未安装 OpenClaw 的机器/环境中，安装 ZCLAW 后即可直接使用 + +## Milestone 4：设置页与交付收尾 + +输出物： + +- 最小可交付设置体验 +- smoke checklist +- README / PROGRESS 更新 + +完成标志： + +- 仓库进入“可给他人试用”的状态 + +--- + +## 6. 本轮立即执行项 + +按当前优先级，接下来立刻执行： + +1. 在 Tauri Rust 侧实现 Gateway 管理命令 +2. 在前端新增 Tauri Gateway bridge +3. 在 `gatewayStore` 中接入本地 Gateway 状态与动作 +4. 在 Settings > General 中增加本地 Gateway 管理卡片 +5. 明确 OpenClaw 随包分发方案，避免把系统安装依赖固化为最终设计 +6. 进行编译/运行级验证 +7. 若验证通过，记录到 `PROGRESS.md` + +--- + +## 7. 阶段提交策略 + +本轮按以下 checkpoint 推进： + +### Checkpoint A + +- 完成计划文档 +- 完成 Tauri 命令桥与前端接线 + +### Checkpoint B + +- 完成本地 Gateway 管理 UI +- 完成基础验证 + +### Checkpoint C + +- 完成 OpenClaw bundling / sidecar 方案设计 +- 明确 Windows 优先的交付路径 + +### Checkpoint D + +- 完成设置页收尾 / 文档更新 / smoke checklist + +说明： + +- 代码会按干净阶段组织 +- 如需执行远端 `push`，仍单独确认 + +--- + +## 8. 结论 + +当前最短、最正确的交付路径，不是继续扩展更多功能，而是先把 ZCLAW 从“能连 Gateway 的前端”推进成“能在桌面端真正管理并使用内置 OpenClaw 的产品”。 + +因此，本轮执行的核心结论是： + +- **先做 Tauri 本地 Gateway 生命周期管理** +- **再完成 OpenClaw 随包分发方案** +- **然后做真实桌面端闭环验证** +- **最后收尾设置页与交付文档** + +这条路线最符合当前仓库状态，也最接近“完整可用 ZCLAW”的真实交付目标。 diff --git a/docs/plans/2026-03-16-openviking-local-deployment.md b/docs/plans/2026-03-16-openviking-local-deployment.md new file mode 100644 index 0000000..85aba58 --- /dev/null +++ b/docs/plans/2026-03-16-openviking-local-deployment.md @@ -0,0 +1,426 @@ +# ZCLAW OpenViking 深度集成方案 + +## Context + +**背景**：ZCLAW 项目基于 OpenFang 定制开发，目标是结合 OpenClaw、NanoClaw、ZeroClaw 等系统的优点。当前 Agent 智能层已超前完成（Phase 1-3 完成, Phase 4 部分完成)，但 OpenViking 集成依赖外部 Python 服务，用户安装繁琐。 + +**问题**：如何深度集成 OpenViking，避免 Python 依赖，实现无感安装体验？ + +**目标**：以 OpenViking Rust CLI (`ov`) 为核心，通过 Tauri sidecar 集成，让记忆系统成为原生组件。CLI 缺失的功能再自行开发补充。 + +--- + +## 关键决策总结 + +基于头脑风暴讨论，确定以下技术决策： + +| 决策点 | 选择 | 理由 | +|--------|------|------| +| **集成方式** | OpenViking Rust CLI + 自建补充 | 利用成熟工具，减少开发量，缺失功能自行补充 | +| **记忆存储** | CLI 内置 SQLite + sqlite-vec | CLI 已实现，无需重复开发 | +| **Embedding 模型** | doubao-embedding-vision | 中文效果优秀，火山引擎生态 | +| **记忆提取** | LLM 提取 | 对话结束后调用 LLM 分析并提取 | +| **部署方式** | Tauri Sidecar | CLI 作为可执行文件随应用分发 | + +--- + +## Architecture Design + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ZCLAW Desktop (Tauri + React) │ +│ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ React UI Layer │ │ +│ │ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────────┐ │ │ +│ │ │ ChatArea │ │MemoryPanel│ │SwarmPanel│ │ SkillMarket │ │ │ +│ │ └────┬─────┘ └────┬─────┘ └─────┬─────┘└──────┬───────┘ │ │ +│ └───────────┼────────────┼─────────────┼───────────────┼─────┘ │ +│ ▼ ▼ ▼ ▼ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ TypeScript Integration Layer │ │ +│ │ ┌──────────────────────────────────────────────────────┐ │ │ +│ │ │ VikingAdapter (已存在，保持兼容) │ │ │ +│ │ └──────────────────────────────────────────────────────┘ │ │ +│ └──────────────────────────┬─────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────────▼─────────────────────────────────┐ │ +│ │ Tauri Command Layer (Rust) │ │ +│ │ ┌────────────────────────────────────────────────────────┐│ │ +│ │ │ SidecarWrapper: 调用 `ov` CLI ││ │ +│ │ │ - invoke('viking_add', ...) → ov add ││ │ +│ │ │ - invoke('viking_find', ...) → ov find ││ │ +│ │ │ - invoke('viking_grep', ...) → ov grep ││ │ +│ │ └────────────────────────────────────────────────────────┘│ │ +│ │ ┌────────────────────────────────────────────────────────┐│ │ +│ │ │ SupplementalModule: CLI 缺失功能补充 ││ │ +│ │ │ - SessionExtractor (LLM 记忆提取) ││ │ +│ │ │ - EmbeddingService (doubao API 封装) ││ │ +│ │ │ - ContextBuilder (L0/L1/L2 分层加载) ││ │ +│ │ └────────────────────────────────────────────────────────┘│ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────────▼─────────────────────────────────┐ │ +│ │ Storage Layer │ │ +│ │ ┌──────────────────┐ ┌──────────────────────────────────┐ │ │ +│ │ │ OpenViking CLI │ │ AppData (配置) │ │ │ +│ │ │ ~/.viking/ │ │ ~/.zclaw/config.toml │ │ │ +│ │ │ - SQLite + vec │ │ │ │ │ +│ │ │ - 向量索引 │ │ │ │ │ +│ │ └──────────────────┘ └──────────────────────────────────┘ │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## OpenViking Rust CLI 能力分析 + +### CLI 已实现功能 (直接使用) + +| 命令 | 功能 | 状态 | +|------|------|------| +| `ov add ` | 添加资源到索引 | ✅ 可用 | +| `ov find ` | 语义搜索 | ✅ 可用 | +| `ov grep ` | 正则搜索 | ✅ 可用 | +| `ov ls ` | 列出资源 | ✅ 可用 | +| `ov tree ` | 目录树 | ✅ 可用 | +| `ov chat` | 交互式对话 | ✅ 可用 | + +### CLI 缺失功能 (需要自建) + +| 功能 | 说明 | 优先级 | +|------|------|--------| +| Session Extraction | 对话后 LLM 提取记忆 | 高 | +| L0/L1/L2 分层加载 | Token 优化上下文构建 | 高 | +| Embedding 批量生成 | doubao API 封装 | 中 | +| 记忆老化/清理 | 低重要性记忆自动清理 | 低 | +| 多 Agent 隔离 | agent_id 维度隔离 | 中 | + +--- + +## Implementation Phases + +### Phase 1: Sidecar 集成 (Week 1) + +**Goal**: 将 OpenViking CLI 集成为 Tauri sidecar + +#### Steps + +1. **下载并嵌入 CLI** + ```bash + # 将 ov 二进制放入 src-tauri/binaries/ + # Windows: ov-x86_64-pc-windows-msvc.exe + # macOS: ov-x86_64-apple-darwin + # Linux: ov-x86_64-unknown-linux-gnu + ``` + +2. **配置 tauri.conf.json** + ```json + { + "tauri": { + "bundle": { + "externalBin": ["binaries/ov"] + } + } + } + ``` + +3. **创建 Tauri Commands** + ```rust + // src-tauri/src/viking_commands.rs + + #[tauri::command] + pub async fn viking_add(uri: String, content: String) -> Result { + let sidecar = Command::new_sidecar("ov") + .map_err(|e| e.to_string())?; + let output = sidecar + .args(["add", &uri]) + .output() + .await + .map_err(|e| e.to_string())?; + Ok(String::from_utf8_lossy(&output.stdout).to_string()) + } + + #[tauri::command] + pub async fn viking_find(query: String, limit: usize) -> Result, String> { + let sidecar = Command::new_sidecar("ov") + .map_err(|e| e.to_string())?; + let output = sidecar + .args(["find", "--json", &query, "--limit", &limit.to_string()]) + .output() + .await + .map_err(|e| e.to_string())?; + + serde_json::from_slice(&output.stdout) + .map_err(|e| e.to_string()) + } + ``` + +#### Files to Create + +| File | Purpose | +|------|---------| +| `src-tauri/src/viking_commands.rs` | Tauri 命令封装 | +| `src-tauri/binaries/ov-*` | Sidecar 二进制 | + +#### Files to Modify + +| File | Changes | +|------|---------| +| `src-tauri/src/lib.rs` | 注册 viking 模块 | +| `src-tauri/tauri.conf.json` | 添加 externalBin 配置 | +| `desktop/src/lib/viking-adapter.ts` | 添加 `invoke()` 调用 | + +### Phase 2: TypeScript 适配层 (Week 1-2) + +**Goal**: 更新 VikingAdapter 使用 Tauri 命令 + +#### Key Changes + +```typescript +// desktop/src/lib/viking-adapter.ts + +import { invoke } from '@tauri-apps/api/tauri'; + +export class VikingAdapter { + private mode: 'sidecar' | 'remote' = 'sidecar'; + + async addResource(uri: string, content: string): Promise { + if (this.mode === 'sidecar') { + await invoke('viking_add', { uri, content }); + } else { + // Remote fallback + await this.httpClient.addResource(uri, content); + } + } + + async find(query: string, options?: FindOptions): Promise { + if (this.mode === 'sidecar') { + return await invoke('viking_find', { + query, + limit: options?.limit || 10 + }); + } else { + return this.httpClient.find(query, options); + } + } +} +``` + +### Phase 3: 补充模块开发 (Week 2-3) + +**Goal**: 实现 CLI 缺失的功能 + +#### 3.1 Session Extractor + +```rust +// src-tauri/src/memory/extractor.rs + +pub struct SessionExtractor { + llm_client: LlmClient, +} + +impl SessionExtractor { + /// Extract memories from conversation + pub async fn extract( + &self, + messages: Vec, + agent_id: &str, + ) -> Result, Error> { + let prompt = self.build_extraction_prompt(&messages); + let response = self.llm_client.complete(&prompt).await?; + self.parse_extraction(&response, agent_id) + } +} +``` + +#### 3.2 Context Builder (L0/L1/L2) + +```rust +// src-tauri/src/memory/context_builder.rs + +pub struct ContextBuilder { + viking: VikingSidecar, +} + +impl ContextBuilder { + /// Build layered context for token efficiency + pub async fn build_context( + &self, + query: &str, + agent_id: &str, + max_tokens: usize, + ) -> Result { + // L0: Quick scan - top 50 by similarity + let l0_results = self.viking.find(query, 50).await?; + + // L1: Load overview for top 10 + let l1_items = self.load_overviews(&l0_results[..10]).await?; + + // L2: Full content for top 3 + let l2_items = self.load_full_content(&l0_results[..3]).await?; + + Ok(EnhancedContext { l1_items, l2_items }) + } +} +``` + +#### Files to Create + +| File | Purpose | +|------|---------| +| `src-tauri/src/memory/mod.rs` | 模块入口 | +| `src-tauri/src/memory/extractor.rs` | LLM 记忆提取 | +| `src-tauri/src/memory/context_builder.rs` | L0/L1/L2 分层加载 | +| `src-tauri/src/llm/client.rs` | doubao API 客户端 | + +### Phase 4: UI 集成 (Week 3-4) + +**Goal**: 完善记忆面板 UI + +#### Files to Modify + +| File | Changes | +|------|---------| +| `desktop/src/components/MemoryPanel.tsx` | 集成 sidecar 模式 | +| `desktop/src/components/RetrievalTrace.tsx` | 显示 L0/L1/L2 检索轨迹 | +| `desktop/src/store/chatStore.ts` | 使用新的 VikingAdapter | + +--- + +## Critical Files + +### Existing Files (Reuse) + +| File | Path | Purpose | +|------|------|---------| +| VikingAdapter | `desktop/src/lib/viking-adapter.ts` | 保持兼容，添加 sidecar 模式 | +| VikingHttpClient | `desktop/src/lib/viking-client.ts` | 远程模式时使用 | +| AgentMemory | `desktop/src/lib/agent-memory.ts` | 现有记忆接口 | +| MemoryPanel | `desktop/src/components/MemoryPanel.tsx` | 现有 UI | + +### New Files (Create) + +| File | Path | Purpose | +|------|------|---------| +| VikingCommands | `src-tauri/src/viking_commands.rs` | Sidecar 命令封装 | +| SessionExtractor | `src-tauri/src/memory/extractor.rs` | LLM 提取 (CLI 缺失) | +| ContextBuilder | `src-tauri/src/memory/context_builder.rs` | 分层加载 (CLI 缺失) | +| LlmClient | `src-tauri/src/llm/client.rs` | doubao API 封装 | + +--- + +## Dependencies to Add + +```toml +# src-tauri/Cargo.toml +[dependencies] +tauri = { version = "2", features = ["process-command-api"] } +tokio = { version = "1", features = ["full"] } +reqwest = { version = "0.11" } # For LLM API calls +serde = { version = "1", features = ["derive"] } +serde_json = "1" +``` + +--- + +## Verification Plan + +### Unit Tests + +```bash +# Run Rust tests +cargo test --manifest-path=src-tauri/Cargo.toml + +# Run TypeScript tests +pnpm vitest run tests/desktop/memory*.test.ts +``` + +### Integration Tests + +1. **Sidecar 启动**: CLI 能正确作为 sidecar 运行 +2. **Memory Save/Load**: 通过 Tauri 命令保存和检索记忆 +3. **Vector Search**: 语义搜索返回相关结果 +4. **Session Extraction**: 对话结束后正确提取记忆 +5. **Context Building**: L0/L1/L2 分层加载正常工作 +6. **UI Integration**: MemoryPanel 正确显示数据 + +### Manual Testing + +1. 启动应用，验证 CLI sidecar 自动启动 +2. 发送消息，检查记忆是否保存 +3. 发送新消息，验证 Agent 能回忆之前的信息 +4. 测试记忆搜索功能 +5. 验证无 Python 依赖 + +--- + +## Migration Path + +### From Current State + +``` +Current: Target: + +viking-client.ts ─────────────► Tauri Command +(HTTP to Python server) (Sidecar wrapper) + │ + ▼ +viking-adapter.ts ──────────────► Dual mode: sidecar + remote fallback +``` + +### Data Compatibility + +- OpenViking CLI 使用 `~/.viking/` 目录存储数据 +- 与 Python Server 版本数据格式兼容 +- 可无缝迁移现有数据 + +--- + +## Success Criteria + +- [ ] OpenViking CLI 作为 sidecar 正确运行 +- [ ] Tauri 命令可调用 CLI 功能 +- [ ] 记忆保存和检索功能正常 +- [ ] 语义搜索返回相关结果 +- [ ] LLM 记忆提取正常工作 (自建模块) +- [ ] L0/L1/L2 分层加载正常工作 (自建模块) +- [ ] MemoryPanel UI 正确显示 +- [ ] 所有测试通过 +- [ ] **无需 Python 依赖** + +--- + +## Risks and Mitigations + +| Risk | Mitigation | +|------|------------| +| CLI 二进制兼容性 | 提供多平台预编译版本 | +| CLI 功能不足 | 自建补充模块填补空白 | +| Embedding API 限流 | 实现本地缓存 | +| LLM 提取失败 | 保留规则提取作为 fallback | +| Sidecar 启动失败 | 优雅降级到远程模式 | + +--- + +## Timeline + +| Week | Phase | Deliverables | +|------|-------|--------------| +| 1 | Sidecar 集成 | CLI 嵌入 + Tauri 命令 + TypeScript 适配 | +| 2 | 补充模块 | SessionExtractor + ContextBuilder | +| 3 | LLM 集成 | doubao API 客户端 + 提取逻辑 | +| 4 | UI 集成 | MemoryPanel + RetrievalTrace | +| 5 | 测试完善 | 集成测试 + 文档 | + +--- + +## 开发策略总结 + +1. **Phase 1**: 直接集成 OpenViking Rust CLI 作为 sidecar +2. **Phase 2**: 检测 CLI 功能覆盖度 +3. **Phase 3**: 自行开发 CLI 缺失的功能 (Session Extraction, Context Builder) +4. **Phase 4**: UI 完善和测试 + +**核心原则**: 最大化利用现有成熟工具，最小化自建代码量，只在必要时补充缺失功能。 diff --git a/docs/plans/cached-greeting-cocke.md b/docs/plans/cached-greeting-cocke.md new file mode 100644 index 0000000..0b211c2 --- /dev/null +++ b/docs/plans/cached-greeting-cocke.md @@ -0,0 +1,615 @@ +# ZCLAW UI/UX 全面优化计划 + +## 背景 + +ZCLAW 是基于 OpenFang (Rust Agent OS) 的 AI Agent 桌面客户端。经过 Phase 1-8 的功能开发，系统已达到 93% API 覆盖率和 100% UI 组件完成度。现在需要对前端设计元素进行全面优化，提升用户操作效率与视觉体验。 + +## 当前状态分析 + +### 代码结构 +- **框架**: React 18 + TypeScript + Tauri +- **样式**: Tailwind CSS v4.2.1 +- **状态管理**: Zustand (gatewayStore, chatStore, teamStore) +- **图标**: lucide-react +- **组件数量**: 37 个组件 + +### 现有设计特点 +- **主色调**: Orange (#f97316) 作为品牌色 +- **布局**: 三栏式 (Sidebar w-64 | Main flex-1 | RightPanel w-80) +- **暗黑模式**: 部分支持 (部分组件有 `dark:` 变体) +- **动画**: 基础 CSS 动画 (animate-pulse, animate-spin) + +--- + +## 发现的问题 + +### 1. 设计系统问题 (CRITICAL) + +| 问题 | 位置 | 影响 | +|------|------|------| +| 无 UI 组件库 | 全局 | 一致性差，重复代码 | +| 颜色系统不完整 | index.css | 品牌识别度低 | +| 暗黑模式不完整 | 多个组件 | 用户体验不一致 | +| **使用 Emoji 作为 UI 图标** | ChatArea, App.tsx | 不专业，违反设计规范 | + +### 2. 可访问性问题 (CRITICAL) + +| 问题 | 位置 | 影响 | +|------|------|------| +| 缺少 aria-label | 图标按钮 | 屏幕阅读器无法识别 | +| 焦点状态不明显 | 多个交互元素 | 键盘导航困难 | +| 颜色对比度不足 | text-gray-400 类 | 可读性差 | + +### 3. 交互与动画 (HIGH) + +| 问题 | 位置 | 影响 | +|------|------|------| +| 无过渡动画库 | 全局 | 交互生硬 | +| 悬停状态不一致 | 多个组件 | 用户困惑 | +| 缺少骨架屏 | 数据加载 | 感知性能差 | + +### 4. 视觉层次 (MEDIUM) + +| 问题 | 位置 | 影响 | +|------|------|------| +| 卡片阴影过轻 | shadow-sm | 层次不明显 | +| 间距不一致 | padding/margin | 视觉混乱 | +| 字体过小 | text-xs | 可读性差 | + +### 5. 用户体验 (MEDIUM) + +| 问题 | 位置 | 影响 | +|------|------|------| +| 空状态设计简陋 | 多个列表 | 缺乏引导 | +| 错误提示不明显 | 表单等 | 用户困惑 | +| 加载反馈不足 | API 调用 | 用户焦虑 | + +--- + +## 用户确认的优化方向 + +| 决策项 | 选择 | +|--------|------| +| 动画库 | ✅ 引入 Framer Motion | +| 暗黑模式 | ✅ 完整支持所有组件 | +| 组件库 | ✅ 创建 Button, Card, Input 等基础组件 | + +--- + +## 优化方案 + +### Phase 1: 设计系统建立 (P0) + +#### 1.1 CSS 变量系统 + +**文件**: `desktop/src/index.css` + +```css +:root { + /* Brand Colors */ + --color-primary: #f97316; + --color-primary-hover: #ea580c; + --color-primary-light: #fff7ed; + + /* Semantic Colors */ + --color-success: #22c55e; + --color-warning: #eab308; + --color-error: #ef4444; + --color-info: #3b82f6; + + /* Neutral Colors */ + --color-bg: #ffffff; + --color-bg-secondary: #f9fafb; + --color-border: #e5e7eb; + --color-text: #111827; + --color-text-secondary: #6b7280; + --color-text-muted: #9ca3af; + + /* Spacing Scale */ + --space-xs: 4px; + --space-sm: 8px; + --space-md: 16px; + --space-lg: 24px; + --space-xl: 32px; + + /* Border Radius */ + --radius-sm: 6px; + --radius-md: 8px; + --radius-lg: 12px; + --radius-xl: 16px; + --radius-full: 9999px; + + /* Shadows */ + --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05); + --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1); + --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1); + + /* Transitions */ + --transition-fast: 150ms ease; + --transition-normal: 200ms ease; + --transition-slow: 300ms ease; +} + +.dark { + --color-bg: #0f172a; + --color-bg-secondary: #1e293b; + --color-border: #334155; + --color-text: #f1f5f9; + --color-text-secondary: #94a3b8; + --color-text-muted: #64748b; +} +``` + +#### 1.2 统一 Tailwind 配置 + +**文件**: `desktop/tailwind.config.js` (新建) + +```javascript +export default { + theme: { + extend: { + colors: { + primary: { + DEFAULT: 'var(--color-primary)', + hover: 'var(--color-primary-hover)', + light: 'var(--color-primary-light)', + }, + }, + boxShadow: { + 'card': 'var(--shadow-md)', + 'hover': 'var(--shadow-lg)', + }, + transitionDuration: { + 'fast': '150ms', + 'normal': '200ms', + }, + }, + }, +} +``` + +### Phase 2: 基础组件库 (P0) + +#### 2.1 Button 组件 + +**文件**: `desktop/src/components/ui/Button.tsx` + +```tsx +import { forwardRef } from 'react'; +import { motion } from 'framer-motion'; +import { cn } from '../../lib/utils'; + +interface ButtonProps extends React.ButtonHTMLAttributes { + variant?: 'primary' | 'secondary' | 'ghost' | 'danger'; + size?: 'sm' | 'md' | 'lg'; + loading?: boolean; +} + +export const Button = forwardRef( + ({ className, variant = 'primary', size = 'md', loading, children, disabled, ...props }, ref) => { + return ( + + {loading && } + {children} + + ); + } +); + +const variants = { + primary: 'bg-primary text-white hover:bg-primary-hover', + secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200', + ghost: 'text-gray-600 hover:bg-gray-100', + danger: 'bg-red-500 text-white hover:bg-red-600', +}; + +const sizes = { + sm: 'px-3 py-1.5 text-xs', + md: 'px-4 py-2 text-sm', + lg: 'px-6 py-3 text-base', +}; +``` + +#### 2.2 Card 组件 + +**文件**: `desktop/src/components/ui/Card.tsx` + +```tsx +import { motion } from 'framer-motion'; +import { cn } from '../../lib/utils'; + +interface CardProps { + children: React.ReactNode; + className?: string; + hoverable?: boolean; + onClick?: () => void; +} + +export function Card({ children, className, hoverable, onClick }: CardProps) { + const Component = hoverable ? motion.div : 'div'; + + return ( + + {children} + + ); +} +``` + +#### 2.3 cn() 工具函数 + +**文件**: `desktop/src/lib/utils.ts` + +```typescript +import { clsx, type ClassValue } from 'clsx'; +import { twMerge } from 'tailwind-merge'; + +export function cn(...inputs: ClassValue[]) { + return twMerge(clsx(inputs)); +} +``` + +**原则**: 使用 SVG 图标 (lucide-react)，不使用 emoji 作为 UI 元素 + +| 文件 | 当前 | 修改为 | +|------|------|--------| +| `ChatArea.tsx:79` | `🤖` | `` | +| `ChatArea.tsx:279` | `🦞` (消息气泡) | `` (自定义图标) | +| `App.tsx:79` | `🤖` | `` | +| `App.tsx:98` | `👥` | `` | +| `Sidebar.tsx:98` | 用户头像 emoji | 首字母 + 渐变背景 | + +### Phase 3: 可访问性改进 (P0) + +#### 3.1 添加 aria-label + +**关键文件**: +- `Sidebar.tsx` - 设置按钮、tab 切换 +- `ChatArea.tsx` - 发送按钮、附件按钮、模型选择器 +- `RightPanel.tsx` - tab 切换、刷新按钮 +- `SettingsLayout.tsx` - 返回按钮、菜单项 + +```tsx +// 示例修复 + +``` + +#### 3.2 焦点状态增强 + +```css +/* 全局焦点样式 */ +:focus-visible { + outline: 2px solid var(--color-primary); + outline-offset: 2px; +} + +/* 按钮焦点 */ +.btn:focus-visible { + ring: 2px; + ring-color: var(--color-primary); + ring-offset: 2px; +} +``` + +#### 3.3 颜色对比度修复 + +| 当前 | 对比度 | 修复 | +|------|--------|------| +| `text-gray-400` on white | 3.1:1 (FAIL) | 改为 `text-gray-500` (#6b7280) 4.6:1 | +| `text-gray-300` on white | 2.9:1 (FAIL) | 改为 `text-gray-600` (#4b5563) 7.0:1 | + +### Phase 4: 交互与动画增强 (P1) + +#### 4.1 Framer Motion 动画系统 + +**新文件**: `desktop/src/lib/animations.ts` + +```typescript +import { Variants } from 'framer-motion'; + +// 页面切换动画 +export const pageVariants: Variants = { + initial: { opacity: 0, y: 10 }, + animate: { opacity: 1, y: 0 }, + exit: { opacity: 0, y: -10 }, +}; + +// 列表项交错动画 +export const listItemVariants: Variants = { + hidden: { opacity: 0, x: -10 }, + visible: { opacity: 1, x: 0 }, +}; + +// 按钮点击动画 +export const buttonTap = { scale: 0.98 }; + +// 卡片悬停动画 +export const cardHover = { y: -2, boxShadow: '0 10px 25px -5px rgb(0 0 0 / 0.1)' }; + +// 默认过渡配置 +export const defaultTransition = { + duration: 0.2, + ease: [0.4, 0, 0.2, 1], +}; +``` + +**使用示例**: +```tsx +import { motion, AnimatePresence } from 'framer-motion'; +import { pageVariants, defaultTransition } from '../lib/animations'; + +// 页面切换 + + + {content} + + +``` + +**新文件**: `desktop/src/components/ui/Skeleton.tsx` + +```tsx +export function Skeleton({ className }: { className?: string }) { + return ( +
+ ); +} + +export function CardSkeleton() { + return ( +
+ + + +
+ ); +} +``` + +#### 4.3 Toast 通知系统 + +**新文件**: `desktop/src/components/ui/Toast.tsx` + +用于替代 `alert()` 和内联错误消息。 + +### Phase 5: 视觉层次优化 (P1) + +#### 5.1 卡片阴影增强 + +```diff +- className="rounded-xl border border-gray-200 bg-white p-4 shadow-sm" ++ className="rounded-xl border border-gray-200 bg-white p-4 shadow-sm hover:shadow-md transition-shadow duration-200" +``` + +#### 5.2 间距标准化 + +| 区域 | 当前 | 标准 | +|------|------|------| +| 页面内边距 | 不一致 | `p-6` (24px) | +| 卡片内边距 | `p-3`/`p-4` | `p-4` (16px) | +| 列表项间距 | `space-y-1`/`space-y-2` | `space-y-2` (8px) | +| 区域间距 | `space-y-3`/`space-y-4` | `space-y-4` (16px) | + +#### 5.3 字体大小优化 + +| 类型 | 当前 | 建议 | +|------|------|------| +| 正文 | `text-xs` (12px) | `text-sm` (14px) | +| 小标签 | `text-[10px]` | `text-xs` (12px) | +| 标题 | `text-lg` | 保持 | + +### Phase 6: 用户体验改进 (P2) + +#### 6.1 空状态设计 + +**新组件**: `EmptyState.tsx` + +```tsx +interface EmptyStateProps { + icon: React.ReactNode; + title: string; + description: string; + action?: React.ReactNode; +} + +export function EmptyState({ icon, title, description, action }: EmptyStateProps) { + return ( +
+
+
+ {icon} +
+

+ {title} +

+

+ {description} +

+ {action} +
+
+ ); +} +``` + +#### 6.2 错误状态设计 + +- 使用红色边框和背景 +- 显示错误图标 +- 提供重试按钮 + +#### 6.3 加载状态改进 + +- 按钮加载时禁用并显示 spinner +- 列表加载时显示骨架屏 +- 全局加载时显示顶部进度条 + +--- + +## 实施顺序 + +### 阶段 1: 基础设施 (2-3 天) +1. 安装依赖: `framer-motion clsx tailwind-merge` +2. 创建 CSS 变量系统 (含完整暗黑模式) +3. 创建 tailwind.config.js +4. 创建 utils.ts (cn 函数) +5. 创建 animations.ts (Framer Motion 预设) + +### 阶段 2: 基础组件库 (2-3 天) +1. 创建 Button 组件 (含变体: primary, secondary, ghost) +2. 创建 Card 组件 (含悬停动画) +3. 创建 Input 组件 (含焦点状态) +4. 创建 Badge 组件 +5. 创建 Skeleton 组件 +6. 创建 EmptyState 组件 +7. 创建 Toast 组件 + +### 阶段 3: 可访问性修复 (1-2 天) +1. 添加 aria-label 到所有图标按钮 +2. 修复颜色对比度问题 +3. 增强焦点状态 +4. 添加键盘导航支持 + +### 阶段 4: 视觉优化 (2-3 天) +1. 移除所有 emoji 图标，替换为 SVG +2. 使用基础组件库重构现有组件 +3. 标准化间距 +4. 增强卡片阴影和悬停效果 +5. 完善暗黑模式支持 + +### 阶段 5: 交互增强 (2-3 天) +1. 添加 Framer Motion 页面切换动画 +2. 添加列表项动画 (stagger) +3. 添加按钮点击反馈 +4. 实现骨架屏加载 +5. 集成 Toast 通知系统 + +### 阶段 6: 组件重构 (2-3 天) +1. 重构 Sidebar 组件 (使用新组件库 + 动画) +2. 重构 ChatArea 组件 +3. 重构 RightPanel 组件 +4. 重构 SettingsLayout 组件 +5. 完整暗黑模式测试 + +--- + +## 关键文件清单 + +### 需要修改的文件 + +| 文件 | 修改内容 | +|------|----------| +| `desktop/src/index.css` | 添加 CSS 变量系统 | +| `desktop/src/components/Sidebar.tsx` | aria-label, 动画, emoji 移除 | +| `desktop/src/components/ChatArea.tsx` | aria-label, emoji 移除, 空状态 | +| `desktop/src/components/RightPanel.tsx` | aria-label, 间距标准化 | +| `desktop/src/components/Settings/SettingsLayout.tsx` | aria-label, 间距标准化 | +| `desktop/src/App.tsx` | emoji 移除, 空状态组件 | + +### 需要新建的文件 + +| 文件 | 用途 | +|------|------| +| `desktop/tailwind.config.js` | Tailwind 自定义配置 | +| `desktop/src/components/ui/Button.tsx` | 按钮组件 | +| `desktop/src/components/ui/Card.tsx` | 卡片组件 | +| `desktop/src/components/ui/Input.tsx` | 输入框组件 | +| `desktop/src/components/ui/Badge.tsx` | 标签组件 | +| `desktop/src/components/ui/Skeleton.tsx` | 骨架屏组件 | +| `desktop/src/components/ui/EmptyState.tsx` | 空状态组件 | +| `desktop/src/components/ui/Toast.tsx` | Toast 通知组件 | +| `desktop/src/lib/utils.ts` | cn() 工具函数 | +| `desktop/src/lib/animations.ts` | Framer Motion 动画预设 | + +### 需要安装的依赖 + +```bash +cd desktop +pnpm add framer-motion clsx tailwind-merge +``` + +--- + +## 验证方法 + +### 1. 视觉验证 +```bash +pnpm tauri:dev +``` +- 检查所有页面在浅色/深色模式下的显示 +- 检查所有交互元素的悬停状态 +- 检查所有空状态的显示 + +### 2. 可访问性验证 +- 使用 Chrome DevTools Lighthouse 进行可访问性审计 +- 使用 Tab 键进行键盘导航测试 +- 使用屏幕阅读器测试 (NVDA/JAWS) + +### 3. 类型检查 +```bash +cd desktop && pnpm tsc --noEmit +``` + +### 4. 构建验证 +```bash +pnpm build +``` + +--- + +## 预期成果 + +1. **设计系统**: 完整的 CSS 变量和 Tailwind 配置 +2. **组件库**: 7 个可复用 UI 组件 (Button, Card, Input, Badge, Skeleton, EmptyState, Toast) +3. **可访问性**: Lighthouse 可访问性分数 > 90 +4. **暗黑模式**: 所有组件完整支持暗黑模式 +5. **动画系统**: Framer Motion 动画预设和页面过渡 +6. **视觉一致性**: 所有组件遵循统一设计规范 +7. **无 Emoji**: 所有 UI 图标使用 SVG + +--- + +*计划创建: 2026-03-15* +*预计完成: 11-17 个工作日* diff --git a/docs/plans/fancy-sprouting-teacup.md b/docs/plans/fancy-sprouting-teacup.md new file mode 100644 index 0000000..e4134a5 --- /dev/null +++ b/docs/plans/fancy-sprouting-teacup.md @@ -0,0 +1,663 @@ +# OpenFang Hands & Workflow 集成开发方案 + +## 上下文 + +**目标**: 将 OpenFang 的 Hands 和 Workflow 功能深度集成到 ZClaw 桌面客户端，提供与 OpenFang Web 界面对等的用户体验。 + +**当前状态**: +- ZClaw 已有基础的 `HandsPanel.tsx` 和 `WorkflowList.tsx` 组件 +- 这些组件功能有限，缺少 OpenFang 的核心 UI 特性 +- OpenFang v0.4.0 提供了 8 个 Hands 和完整的 Workflow/Scheduler 系统 + +**参考界面**: http://127.0.0.1:50051 (OpenFang Dashboard) + +--- + +## 一、OpenFang 界面分析总结 + +### 1.1 Hands 页面设计 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Hands — Curated Autonomous Capability Packages │ +│ Available 8 Active │ +├─────────────────────────────────────────────────────────────────┤ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ 🌐 Browser Hand [READY] │ │ +│ │ Autonomous web browser — navigates sites... │ │ +│ │ │ │ +│ │ REQUIREMENTS │ │ +│ │ ✓ Python 3 must be installed │ │ +│ │ ✓ Chromium or Google Chrome must be installed │ │ +│ │ │ │ +│ │ 18 tool(s) · 3 metric(s) [productivity] │ │ +│ │ [Details] [Activate] │ │ +│ └─────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +**详情弹窗内容**: +- AGENT CONFIG: Provider, Model +- REQUIREMENTS: 检查项和状态 (✓/✗) +- TOOLS: 工具名称列表 +- DASHBOARD METRICS: 指标名称列表 +- Activate 按钮 + +### 1.2 Workflows 页面设计 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Workflows │ +│ What are Workflows? Workflows chain multiple agents... │ +│ [List] [Visual Builder] [+ New Workflow] │ +├─────────────────────────────────────────────────────────────────┤ +│ NAME │ STEPS │ CREATED │ ACTIONS │ +│ ──────────────────┼───────┼──────────────┼────────────────────│ +│ 测试工作流 │ 1 │ 2026/3/14 │ [Run][Edit][Del] │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 1.3 Scheduler 页面设计 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Scheduler [+ New Job] │ +│ [Scheduled Jobs] [Event Triggers] [Run History] │ +├─────────────────────────────────────────────────────────────────┤ +│ Scheduled Jobs │ +│ Create cron-based scheduled jobs... │ +│ │ +│ [No scheduled jobs] │ +│ Create a cron job to run agents on a recurring schedule. │ +│ [+ Create Scheduled Job] │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 1.4 Approvals 页面设计 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Execution Approvals [Refresh] │ +│ [All] [Pending] [Approved] [Rejected] │ +├─────────────────────────────────────────────────────────────────┤ +│ [No approvals] │ +│ When agents request permission for sensitive actions, │ +│ they'll appear here. │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 二、ZClaw 现有实现分析 + +### 2.1 已有组件 + +| 文件 | 功能 | 完成度 | +|------|------|--------| +| `HandsPanel.tsx` | Hand 列表、触发、审批、取消 | 40% | +| `WorkflowList.tsx` | Workflow 列表、执行 | 30% | +| `TriggersPanel.tsx` | Trigger 列表 | 20% | +| `gatewayStore.ts` | 状态管理 (Hands/Workflow API) | 60% | + +### 2.2 缺失功能 + +1. **Hands**: + - ❌ 详情弹窗 (Details Modal) + - ❌ Requirements 状态检查可视化 + - ❌ 工具和指标列表展示 + - ❌ Agent Config 显示 (Provider/Model) + - ❌ 激活动画和状态反馈 + - ❌ 分类标签 (productivity/data/content/communication) + +2. **Workflows**: + - ❌ 创建/编辑 Workflow + - ❌ Visual Builder + - ❌ 执行历史查看 + - ❌ 步骤详情展示 + +3. **Scheduler**: + - ❌ Scheduled Jobs 管理 + - ❌ Event Triggers 管理 + - ❌ Cron 表达式编辑器 + - ❌ Run History + +4. **Approvals**: + - ❌ 独立 Approvals 页面 + - ❌ 筛选功能 (All/Pending/Approved/Rejected) + - ❌ 审批详情展示 + +--- + +## 三、开发方案 + +### 3.1 Phase 1: 增强 HandsPanel (优先级: 高) + +**目标**: 提供与 OpenFang 对等的 Hands 管理体验 + +**文件修改**: +- `desktop/src/components/HandsPanel.tsx` (重写) +- `desktop/src/components/HandDetailsModal.tsx` (新建) +- `desktop/src/store/gatewayStore.ts` (扩展) + +**UI 设计**: + +```tsx +// HandCard 组件结构 +
+
+ {hand.icon} +

{hand.name}

+ {/* READY/SETUP NEEDED/RUNNING */} +
+ +

{hand.description}

+ + {/* Requirements 检查 */} + {hand.requirements && ( +
+ REQUIREMENTS + {hand.requirements.map(req => ( +
+ {req.met ? '✓' : '✗'} + {req.description} +
+ ))} +
+ )} + + {/* 元信息 */} +
+ {hand.toolCount} tool(s) + {hand.metricCount} metric(s) + {hand.category} +
+ + {/* 操作按钮 */} +
+ + +
+
+``` + +**HandDetailsModal 组件**: + +```tsx +// 详情弹窗 + + + {hand.icon} +

{hand.name}

+ + + + + {/* Agent Config */} +
+ + +
+ + {/* Requirements */} +
+ {hand.requirements.map(req => ( + + ))} +
+ + {/* Tools */} +
+ +
+ + {/* Dashboard Metrics */} +
+ +
+ + + + + + + +``` + +**API 扩展**: + +```typescript +// gatewayStore.ts 扩展 +interface Hand { + id: string; + name: string; + description: string; + status: 'idle' | 'running' | 'needs_approval' | 'error' | 'unavailable'; + icon?: string; + category?: string; // productivity, data, content, communication + provider?: string; + model?: string; + requirements?: Array<{ + description: string; + met: boolean; + details?: string; + }>; + tools?: string[]; + metrics?: string[]; + toolCount?: number; + metricCount?: number; + currentRunId?: string; +} + +// 新增 API 调用 +getHandDetails: (name: string) => Promise; +activateHand: (name: string, params?: Record) => Promise; +deactivateHand: (name: string) => Promise; +``` + +### 3.2 Phase 2: 增强 WorkflowList (优先级: 高) + +**目标**: 提供完整的 Workflow 管理能力 + +**文件修改**: +- `desktop/src/components/WorkflowList.tsx` (重写) +- `desktop/src/components/WorkflowEditor.tsx` (新建) +- `desktop/src/components/WorkflowHistory.tsx` (新建) +- `desktop/src/store/gatewayStore.ts` (扩展) + +**UI 设计**: + +```tsx +// WorkflowList 组件结构 +
+
+

Workflows

+
+ + +
+ +
+ +

+ Workflows chain multiple agents into automated pipelines... +

+ + + + + + + + + + + + {workflows.map(wf => ( + + + + + + + ))} + +
NAMESTEPSCREATEDACTIONS
{wf.name}{wf.steps}{formatDate(wf.createdAt)} + + + + +
+
+``` + +**WorkflowEditor 组件** (简化版): + +```tsx + +
+
+ +