zclaw_openfang/plans/humble-popping-anchor.md

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 宽度

<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. 点击按钮时从右侧滑出抽屉

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

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)

/* 强调色 */
--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 */

尺寸规范

/* 导航栏 */
--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. 暗色模式验证: 暗色模式下样式正确

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 小时