# ZClaw 桌面应用布局优化计划

## 一、设计参考

基于腾讯 WorkBuddy 的 HTML 设计稿，学习其布局风格并适配 ZClaw 的功能需求。

### WorkBuddy 布局结构

```
┌────────────────────────────────────────────────────────────────┐
│                    顶部工具栏 (h-14 = 56px)                     │
├────────────────┬───────────────────────────────────────────────┤
│                │                                               │
│   左侧导航栏    │                主内容区                        │
│   w-64 (256px) │               flex-1                          │
│                │          (占据全部剩余空间)                     │
│  ┌──────────┐  │                                               │
│  │ 搜索框   │  │    - 聊天界面 (居中卡片)                        │
│  ├──────────┤  │    - 专家中心 (网格卡片)                        │
│  │ 新建任务 │  │    - 技能市场 (网格卡片)                        │
│  ├──────────┤  │    - 自动化 (模板卡片)                         │
│  │ Claw    │  │                                               │
│  │ 专家    │  │                                               │
│  │ 技能    │  │                                               │
│  │ 插件    │  │                                               │
│  │ 自动化  │  │                                               │
│  ├──────────┤  │                                               │
│  │ 空状态   │  │                                               │
│  └──────────┘  │                                               │
│  ┌──────────┐  │                                               │
│  │ 用户头像 │  │                                               │
│  └──────────┘  │                                               │
└────────────────┴───────────────────────────────────────────────┘
```

### 关键设计特点

1. **无右侧面板** - 所有功能通过左侧导航切换，在主内容区显示
2. **紧凑导航栏** - 256px 固定宽度，包含搜索和所有导航项
3. **最大化主内容区** - 占据全部剩余空间
4. **卡片式布局** - 主内容区使用卡片网格展示内容
5. **绿色强调色** - emerald-500 作为主强调色
6. **Inter 字体** - 现代简洁的字体

---

## 二、ZClaw 功能映射

### 导航项映射

| WorkBuddy | ZClaw | 功能说明 |
|-----------|-------|---------|
| Claw | 聊天 (Chat) | AI 对话，核心功能 |
| 专家 | 分身 (Agents) | Agent 列表和管理 |
| 技能 | 技能 (Skills) | 技能市场 |
| 插件 | Hands | 7 个自主能力包 |
| 自动化 | 工作流 (Workflow) | 工作流和调度 |

### 额外功能处理

ZClaw 有额外的功能需要处理：
- **团队协作** → 添加到导航项
- **Swarm 协作** → 添加到导航项
- **详情面板** (RightPanel) → **改为抽屉或合并到主内容区**

---

## 三、新布局方案

### 方案：WorkBuddy 风格 + 详情抽屉

```
┌────────────────────────────────────────────────────────────────┐
│  [Z] ZCLAW                              [📋 详情] [⚙ 设置]     │
├────────────────┬───────────────────────────────────────────────┤
│  🔍 搜索...    │                                               │
├────────────────┤                                               │
│  ✨ 新对话     │                                               │
├────────────────┤                                               │
│  💬 聊天      │              主内容区                           │
│  🤖 分身 ←   │           (flex-1)                              │
│  🖐️ Hands    │                                               │
│  ⚡ 工作流    │        根据导航显示对应内容:                      │
│  📦 技能     │        - 聊天界面                                │
│  👥 团队     │        - Agent 列表 + 详情                       │
│  🐝 Swarm    │        - Hands 列表 + 详情                       │
├────────────────┤        - 工作流编辑器                          │
│  暂无任务     │        - 技能市场                               │
├────────────────┤        - 团队列表                              │
│  👤 用户     │        - Swarm 仪表盘                            │
└────────────────┴───────────────────────────────────────────────┘
                        ↑ 点击 [📋 详情] 可从右侧滑出抽屉
```

### 布局尺寸

| 区域 | 尺寸 | 说明 |
|------|------|------|
| 左侧导航栏 | `w-64` (256px) | 与 WorkBuddy 一致 |
| 顶部工具栏 | `h-14` (56px) | 与 WorkBuddy 一致 |
| 主内容区 | `flex-1` | 占据全部剩余空间 |
| 详情抽屉 | `w-80` (320px) | 按需滑出 |

---

## 四、详细实施计划

### Phase 1: 重构 Sidebar 组件

**修改文件**: `desktop/src/components/Sidebar.tsx`

**改动内容**:
1. 移除顶部 Tab 栏（改为单一导航列表）
2. 添加搜索框
3. 添加"新对话"按钮
4. 导航项使用图标 + 文字
5. 保持 256px 宽度

```tsx
<aside className="w-64 bg-white border-r border-gray-200 flex flex-col">
  {/* 搜索框 */}
  <div className="p-3">
    <SearchInput placeholder="搜索..." />
  </div>

  {/* 新对话按钮 */}
  <button className="mx-3 mb-2 flex items-center gap-3 px-3 py-2 bg-gray-100 rounded-lg">
    <Sparkles className="text-emerald-500" />
    <span>新对话</span>
  </button>

  {/* 导航项 */}
  <nav className="flex-1 px-3 space-y-0.5 overflow-y-auto">
    <NavItem icon={MessageSquare} label="聊天" active />
    <NavItem icon={Bot} label="分身" />
    <NavItem icon={Hand} label="Hands" />
    <NavItem icon={GitBranch} label="工作流" />
    <NavItem icon={Package} label="技能" />
    <NavItem icon={Users} label="团队" />
    <NavItem icon={Layers} label="Swarm" />
  </nav>

  {/* 用户栏 */}
  <div className="p-3 border-t">
    <UserBar />
  </div>
</aside>
```

### Phase 2: 移除 RightPanel，改为抽屉

**修改文件**: `desktop/src/App.tsx`

**改动内容**:
1. 移除常驻的 RightPanel
2. 添加详情抽屉状态
3. 在顶部工具栏添加"详情"按钮
4. 点击按钮时从右侧滑出抽屉

```tsx
const [showDetailDrawer, setShowDetailDrawer] = useState(false);

// 布局
<div className="h-screen flex">
  <Sidebar />
  <main className="flex-1 flex flex-col">
    <header className="h-14 border-b flex items-center px-4">
      <span className="font-medium">{viewTitle}</span>
      <div className="flex-1" />
      <Button onClick={() => setShowDetailDrawer(true)}>
        <ClipboardList /> 详情
      </Button>
      <Button onClick={onOpenSettings}>
        <Settings />
      </Button>
    </header>
    <div className="flex-1 overflow-hidden">
      {/* 主内容 */}
    </div>
  </main>

  {/* 详情抽屉 */}
  <DetailDrawer open={showDetailDrawer} onClose={() => setShowDetailDrawer(false)}>
    <RightPanelContent />
  </DetailDrawer>
</div>
```

### Phase 3: 创建 DetailDrawer 组件

**新建文件**: `desktop/src/components/DetailDrawer.tsx`

```tsx
import { motion, AnimatePresence } from 'framer-motion';

export function DetailDrawer({ open, onClose, children }) {
  return (
    <AnimatePresence>
      {open && (
        <>
          {/* 遮罩 */}
          <motion.div
            initial={{ opacity: 0 }}
            animate={{ opacity: 1 }}
            exit={{ opacity: 0 }}
            className="fixed inset-0 bg-black/20 z-40"
            onClick={onClose}
          />
          {/* 抽屉 */}
          <motion.aside
            initial={{ x: 320 }}
            animate={{ x: 0 }}
            exit={{ x: 320 }}
            transition={{ type: 'spring', damping: 25, stiffness: 300 }}
            className="fixed right-0 top-0 bottom-0 w-80 bg-white border-l z-50 flex flex-col"
          >
            <header className="h-14 border-b flex items-center px-4">
              <span className="font-medium">详情</span>
              <button onClick={onClose} className="ml-auto">
                <X />
              </button>
            </header>
            <div className="flex-1 overflow-y-auto">
              {children}
            </div>
          </motion.aside>
        </>
      )}
    </AnimatePresence>
  );
}
```

### Phase 4: 主内容区适配

**修改文件**: 各视图组件

根据 WorkBuddy 的风格调整各页面布局：
- **聊天页**: 居中卡片式输入框，上方消息列表
- **分身页**: 左侧列表 + 右侧详情（或卡片网格）
- **Hands 页**: 列表 + 详情
- **工作流页**: 列表 + 编辑器
- **技能页**: 网格卡片布局（参考 WorkBuddy 技能页）

---

## 五、关键文件清单

| 文件 | 操作 | 说明 |
|------|------|------|
| `components/Sidebar.tsx` | 重构 | 改为 WorkBuddy 风格导航 |
| `components/DetailDrawer.tsx` | **新建** | 右侧滑出抽屉 |
| `components/TopBar.tsx` | **新建** | 顶部工具栏 |
| `App.tsx` | 重构 | 新布局结构 |
| `RightPanel.tsx` | 重构 | 内容移入 DetailDrawer |

---

## 六、颜色和样式规范

### 主色调 (参考 WorkBuddy)

```css
/* 强调色 */
--primary: #10b981; /* emerald-500 */
--primary-hover: #059669; /* emerald-600 */

/* 背景 */
--bg-main: #ffffff;
--bg-sidebar: #ffffff;
--bg-input: #f9fafb; /* gray-50 */

/* 边框 */
--border: #e5e7eb; /* gray-200 */
--border-light: #f3f4f6; /* gray-100 */

/* 文字 */
--text-primary: #111827; /* gray-900 */
--text-secondary: #6b7280; /* gray-500 */
--text-muted: #9ca3af; /* gray-400 */
```

### 尺寸规范

```css
/* 导航栏 */
--sidebar-width: 256px;
--header-height: 56px;

/* 间距 */
--spacing-xs: 4px;
--spacing-sm: 8px;
--spacing-md: 12px;
--spacing-lg: 16px;

/* 圆角 */
--radius-sm: 6px;
--radius-md: 8px;
--radius-lg: 12px;
```

---

## 七、验证方法

1. **布局验证**: 检查各组件在正确位置
2. **导航验证**: 点击导航项切换视图
3. **抽屉验证**: 点击详情按钮抽屉滑出
4. **响应式验证**: 窗口缩放时布局正确
5. **暗色模式验证**: 暗色模式下样式正确

```bash
pnpm dev
# 手动测试各项功能
```

---

## 八、视觉效果对比

### 改造前

```
┌────────────────────────────────────────────────────────────────┐
│ [Tab: 分身|Hands|工作流|技能|团队|协作]                          │
├────────────────────────────────────────────────┬───────────────┤
│              主内容区 (~50%)                    │  RightPanel   │
│                                                │   (320px)     │
└────────────────────────────────────────────────┴───────────────┘
```

### 改造后 (WorkBuddy 风格)

```
┌────────────────┬───────────────────────────────────────────────┐
│  🔍 搜索      │                                               │
│  ✨ 新对话    │                                               │
│  💬 聊天     │                                               │
│  🤖 分身     │              主内容区                          │
│  🖐️ Hands   │              (100%)                            │
│  ⚡ 工作流   │                                               │
│  📦 技能    │         [📋 详情] → 按需显示抽屉                 │
│  👥 团队    │                                               │
│  🐝 Swarm   │                                               │
│  ──────────  │                                               │
│  👤 用户    │                                               │
└────────────────┴───────────────────────────────────────────────┘
      256px
```

**空间优化**:
- 移除常驻 RightPanel，主内容区从 ~50% 扩大到 ~100%
- 详情通过抽屉按需显示，不占用常驻空间

---

## 九、实施预估

| Phase | 工作量 | 优先级 |
|-------|--------|--------|
| Phase 1: 重构 Sidebar | 2h | P0 |
| Phase 2: 移除 RightPanel，改为抽屉 | 1.5h | P0 |
| Phase 3: 创建 DetailDrawer | 1h | P0 |
| Phase 4: 主内容区适配 | 2h | P1 |

**总计**: 约 6.5 小时