diff --git a/docs/OPENVIKING_INTEGRATION.md b/docs/OPENVIKING_INTEGRATION.md index be816c4..dbcd4c8 100644 --- a/docs/OPENVIKING_INTEGRATION.md +++ b/docs/OPENVIKING_INTEGRATION.md @@ -429,6 +429,84 @@ cd desktop pnpm vitest run tests/desktop/memory*.test.ts ``` +## 火山引擎 (Volcengine) 配置 + +### 激活 Embedding 模型 + +**重要**：火山引擎的 Embedding 模型需要在控制台单独激活。 + +1. **登录火山引擎控制台**： + https://console.volcengine.com/ark + +2. **激活 Embedding 模型**： + - 进入「模型推理」→「模型服务」 + - 搜索并激活以下模型之一： + - `Doubao-Embedding` (推荐，1024 维) + - `Doubao-Embedding-Large` (2048 维) + +3. **获取 Endpoint ID**： + - 激活后，复制模型的 **Endpoint ID** + - 格式类似：`ep-xxxxxxxxxxxx` + +4. **更新配置文件**： + + 使用 Endpoint ID（推荐）： + ```json + { + "embedding": { + "dense": { + "api_base": "https://ark.cn-beijing.volces.com/api/v3", + "api_key": "your-api-key", + "provider": "volcengine", + "model": "ep-xxxxxxxxxxxx", + "dimension": 1024 + } + } + } + ``` + + 或使用模型名称（需要在控制台激活）： + ```json + { + "embedding": { + "dense": { + "api_base": "https://ark.cn-beijing.volces.com/api/v3", + "api_key": "your-api-key", + "provider": "volcengine", + "model": "doubao-embedding", + "dimension": 1024 + } + } + } + ``` + +### 常见错误 + +| 错误 | 原因 | 解决方案 | +|------|------|----------| +| `ModelNotOpen` | 模型未激活 | 在控制台激活对应的 Embedding 模型 | +| `InvalidEndpointOrModel.NotFound` | Endpoint ID 不存在 | 检查 Endpoint ID 是否正确 | +| `404 Not Found` | API 路径错误 | 确认 `api_base` 为 `https://ark.cn-beijing.volces.com/api/v3` | + +### 测试 Embedding 配置 + +```bash +# 启动服务器后，测试向量搜索 +curl -X POST http://127.0.0.1:1933/api/v1/search/search \ + -H "Content-Type: application/json" \ + -d '{"query": "test query", "limit": 5}' +``` + +成功响应： +```json +{"status":"ok","result":[],"error":null} +``` + +失败响应（需要激活模型）： +```json +{"status":"error","error":{"message":"Volcengine embedding failed: ModelNotOpen..."}} +``` + ## 故障排除 ### Q: OpenViking CLI not found diff --git a/plans/2026-03-12-zclaw-delivery-execution-plan.md b/plans/2026-03-12-zclaw-delivery-execution-plan.md deleted file mode 100644 index ac7b5e0..0000000 --- a/plans/2026-03-12-zclaw-delivery-execution-plan.md +++ /dev/null @@ -1,467 +0,0 @@ -# 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/plans/cached-greeting-cocke.md b/plans/cached-greeting-cocke.md deleted file mode 100644 index 0b211c2..0000000 --- a/plans/cached-greeting-cocke.md +++ /dev/null @@ -1,615 +0,0 @@ -# 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/plans/fancy-sprouting-teacup.md b/plans/fancy-sprouting-teacup.md deleted file mode 100644 index e4134a5..0000000 --- a/plans/fancy-sprouting-teacup.md +++ /dev/null @@ -1,663 +0,0 @@ -# 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 - -
-
- -