# 桌面客户端布局反思：普通用户需要什么？

> Note: The `bash` tool has been removed. `shell` is now the only command execution tool. See `2026-06-03-shell-unification-design.md`.

> 基于当前 Mao 桌面端（Electron + Vue）的界面现状，从**普通用户**视角反思布局问题，并提出适合大众使用者的信息架构方向。  
> 本文是**设计反思**，不替代 `desktop-ux-refactor-plan.md` 中的技术实施清单。

---

## 一、我们在为谁设计？

### 1.1 两类用户，两种心智模型

| 维度 | 开发者 / 高级用户 | 普通用户 |
|------|------------------|----------|
| 目标 | 让 Agent 在仓库里改代码、跑命令、出 PR | 把一件事办完：写报告、查资料、整理文档、回答问题 |
| 成功标准 | 命令输出正确、diff 可审查、工具链可追溯 | **答案清晰、步骤少、不用懂技术名词** |
| 对「工作目录」的理解 | 项目根路径，和 git 强绑定 | 「这是在哪干活？」—— 最好根本不用看到 |
| 对「对话列表」的理解 | 会话 = 一次任务尝试，可回溯 | 和微信聊天记录一样：找上次聊过什么 |
| 容忍的界面复杂度 | 高（VS Code、终端、多面板） | 低（ChatGPT、备忘录、邮件客户端） |

当前界面明显按**左栏开发者工具 + 顶栏管理后台 + 聊天里嵌终端**来组织，三类用户心智被叠在同一屏里，导致「什么都有一点，但没有一件事被照顾到」。

### 1.2 普通用户打开应用时只想回答三个问题

1. **我现在能找谁帮忙？**（选 Agent / 选能力）
2. **上次做到哪了？**（继续未完成的任务）
3. **接下来我该说什么？**（输入框是唯一行动点）

其余一切——Hub、创建 Agent、执行模式、WebSocket 连接状态、工作目录路径、工具名 `@bash`——都是**实现细节**，应默认隐藏或收纳到「高级设置」。

---

## 二、当前布局为何「杂乱、毫无重点」？

### 2.1 结构层：导航与内容抢同一块注意力

```
┌─────────────────────────────────────────────────────────────┐
│  Logo  工作台 | Hub | 创建 Agent              🔔  用户      │  ← 全局导航（3 个产品级入口）
├──────────┬──────────────────────────────────────────────────┤
│  对话    │  Tool Agent  ●本地已连接        [+ 新对话]       │  ← 会话级标题 + 技术状态
│  ─────   │  工作目录 /Users/.../myagent          [更换]     │  ← 路径条（开发者信息）
│  ls -l   │                                                  │
│  你有哪些│  [用户气泡]  [终端黑框 ls 输出]  [@ bash]         │  ← 聊天 + 工具原始输出
│  tools?  │  [助手长文解释权限 rwx...]                       │
│  ...     │  [输入框........................]  📎 发送        │
└──────────┴──────────────────────────────────────────────────┘
```

**问题归纳：**

| 现象 | 对普通用户的伤害 |
|------|------------------|
| 顶栏 3 Tab + 左侧「对话」+ 聊天头「新对话」 | 三条路径都能「开始新东西」，不知道点哪个 |
| 会话列表每项显示 Agent 名 + 相对时间，标题常是命令片段（`ls -l`） | 无法扫一眼认出「这是哪件事」 |
| 聊天区 max-width 900px 居中，两侧大量留白 | 主内容显得小，侧栏反而挤 |
| 工作目录条常驻主区顶部 | 长路径占视线，像报错信息 |
| 终端输出以黑框全宽嵌在对话流里 | 像进了黑客电影，和上方解释性文字**重复叙述同一件事** |
| 「本地已连接」与「云端模式」并列在标题旁 | 用户不关心传输层，只关心「能不能用」 |

本质是：**没有单一视觉锚点**。用户的眼睛在顶栏、侧栏、标题、路径、黑终端、灰气泡之间跳转，找不到「我现在只需要看这里」。

### 2.2 内容层：技术叙事压过任务叙事

截图中的典型一轮交互：

1. 用户发 `ls -l`
2. Agent 返回**完整终端 listing**（十几行权限、大小、日期）
3. 用户发 `?`
4. Agent 再用**自然语言**解释 `-rw-r--r--` 含义

对开发者：步骤 2 是「证据」，步骤 4 是「解读」。  
对普通用户：步骤 2 已经吓退一半人，步骤 4 才是他们唯一需要的内容——**布局却把最吓人的放在最显眼的位置**。

工具卡片（`ToolCallCard`）、`@bash` 标签、mono 字体路径，都在强化「这是一个开发环境」，而不是「这是一个帮我干活的助手」。

### 2.3 流程层：首页与聊天页是两套产品

- **工作台**：Agent 卡片网格 → 点击 → 弹窗选 CLOUD/LOCAL → 进入聊天  
- **聊天页**：自带会话侧栏、工作目录、连接状态  

普通用户的预期（来自 ChatGPT / 豆包 / Copilot）：

- 打开 → **直接就是对话**，或「继续上次对话」
- Agent 选择是**换助手**，不是换「页面模式」

当前路径：`工作台 → 选 Agent → 选模式 → 聊天 → 再发现还要选工作目录`，**四步才到输入框**，心流已断。

---

## 三、普通用户适用的布局原则

### 3.1 一个主舞台（One Primary Stage）

任意时刻，屏幕上**只有一个区域**承担 80% 注意力：

| 场景 | 主舞台 | 其余全部降级 |
|------|--------|--------------|
| 对话中 | 消息流 + 底部输入框 | 历史、设置、工具详情 → 可折叠/抽屉 |
| 选助手 | Agent 列表或搜索 | 无侧栏、无顶栏多 Tab |
| 看结果 | 任务结果摘要（非原始日志） | 原始终端 →「查看详情」二级 |

**反例（当前）**：顶栏、侧栏、header、workspace、消息、输入 —— 六层水平带同时存在。

### 3.2 任务语言，而非系统语言

界面文案与列表标题应使用**人话**：

| 系统语言（应避免作为主文案） | 任务语言（应用作标题/摘要） |
|------------------------------|----------------------------|
| `ls -l` | 查看项目里有哪些文件 |
| Tool Agent | 文件与命令助手 |
| LOCAL / WebSocket 已连接 | 在本机运行（小字提示即可） |
| `/Users/.../myagent` | 当前项目：myagent |
| `@bash` 工具调用成功 | 已执行命令（展开可看） |

会话列表应用**首条用户意图**或**自动摘要**作标题，而不是最后一条命令。

### 3.3 渐进披露（Progressive Disclosure）

```
默认看到：结论 + 一两句说明 + [展开过程]
点击展开：命令、完整输出、文件 diff、连接诊断
进入设置：执行模式、白名单、Hub、创建 Agent
```

普通用户路径：**输入 → 等 → 读结论**；  
高级用户路径：同一屏面上多一个「过程」抽屉，而不是把终端塞进对话气泡。

### 3.4 导航按频率分层，不按功能模块分层

| 频率 | 应放位置 | 当前问题 |
|------|----------|----------|
| 每天多次 | 侧栏或底部：最近对话 | 与工作台 Agent 网格重复 |
| 每周几次 | 二级：换 Agent、Hub | 与「工作台」同级顶栏 Tab |
| 很少 | 设置 / 高级：创建 Agent、模式、目录 | 「创建 Agent」与「工作台」并列顶栏 |

顶栏 ideal 状态：**只有 Logo + 当前上下文标题 + 用户菜单**。  
「Hub」「创建 Agent」进设置或「发现更多助手」入口。

### 3.5 空间：宽聊窄辅，而非窄聊宽辅

聊天产品（iMessage、ChatGPT、Slack DM）的共同规律：

- **对话列占 60–75% 宽度**（当前约 50%，且被 max-width 限制得更窄）
- 辅助信息 **≤25%**，且可收起为图标
- 移动端逻辑：**辅助信息变抽屉，而不是永久占宽**

当前侧栏 + 居中窄列，造成「辅助信息比正文还抢眼」的倒置。

---

## 四、推荐的布局范式（三种可选方向）

### 方案 A：对话优先（最贴近普通用户）

适合：以「问问题、得答案」为主，工具执行为后台能力。

```
┌────────────────────────────────────────────────────────────┐
│  ←  文件助手 · 本机运行 ▾                          ⚙  👤  │  单行顶栏：上下文 + 收纳菜单
├────────────┬───────────────────────────────────────────────┤
│  今天       │                                               │
│  · 整理…    │         [助手] 已帮你看过项目目录，           │
│  昨天       │         共 12 个文件，主要包括…                 │
│  · 天气…    │         [查看执行过程]                        │
│             │                                               │
│  [收起 ◀]   │  ┌─────────────────────────────────────────┐  │
│             │  │  输入你想做的事…              📎  ➤   │  │
│             │  └─────────────────────────────────────────┘  │
└────────────┴───────────────────────────────────────────────┘
```

要点：

- 默认**无**工作目录条；项目在首次本地任务时以轻提示选择「文件夹」
- 工具输出默认折叠为一行摘要卡片
- 侧栏按**日期分组** + 任务化标题
- Hub / 创建 Agent 不在顶栏

### 方案 B：任务优先（适合「交办一件事」）

适合：用户说「帮我把登录模块 refactor 掉」，过一会儿回来看结果。

```
┌────────────────────────────────────────────────────────────┐
│  工作台                                    [+ 新任务]  👤   │
├────────────────────────────────────────────────────────────┤
│  进行中                                                     │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  ● 整理 Q1 报告 · 文档助手    正在写第 3 节…  [打开]  │  │
│  └──────────────────────────────────────────────────────┘  │
│  最近完成 · 昨天 · 更早                                       │
│  ┌────────┐ ┌────────┐ ┌────────┐                           │
│  │ 代码助手│ │ 写作助手│ │ + 更多 │  ← 次要：选助手           │
│  └────────┘ └────────┘ └────────┘                           │
└────────────────────────────────────────────────────────────┘
```

进入任务后，布局退回方案 A 的单对话主舞台；工作台不再是 Agent 卡片墙。

### 方案 C：双栏审查（适合本地改文件的高级场景，非默认）

仅当用户开启「开发者模式」或 Agent 类型为 Code 时启用：

```
┌────────────────────────────────────────────────────────────┐
│  任务：修复单元测试失败                              [完成] │
├──────────────────────┬─────────────────────────────────────┤
│  对话（摘要为主）      │  过程 / 变更（可切换 Tab）           │
│                      │  · 执行步骤时间线                    │
│                      │  · 文件 diff                        │
└──────────────────────┴─────────────────────────────────────┘
```

**普通用户不应默认看到双栏**；这是 power user 的 opt-in。

---

## 五、对现有组件的具体映射

| 现有组件 | 建议处置（普通用户默认） |
|----------|-------------------------|
| `TopNav` 三 Tab | 收敛为：Logo + 当前页标题；Hub/创建进菜单 |
| `SessionPanel` | 保留但：日期分组、任务标题、默认更窄或可收起 |
| `ChatHeader` 连接状态 | 合并为一个状态点；断连才 toast |
| `WorkspaceBar` | 收进首次本地任务引导或设置；主区不常驻 |
| `ToolCallCard` 展开终端 | 默认折叠 + 人话摘要；「查看原始输出」二级 |
| `WorkbenchView` Agent 网格 | 改为「进行中任务」列表；Agent 选择降级 |
| 模式选择弹窗 | 记住上次；或按 Agent 预设，不每次询问 |

---

## 六、信息优先级清单（设计自检用）

设计或评审任一屏时，可按下面排序检查视觉权重是否一致：

1. **用户下一步行动**（输入框、继续按钮、审批）
2. **任务结果 / 助手回复正文**（人话、结构化结论）
3. **当前上下文**（哪个助手、哪次对话 — 一行即可）
4. **历史入口**（侧栏，可收起）
5. **执行过程**（折叠卡片）
6. **系统/连接/路径/工具名**（仅故障或高级模式展示）

若 6 比 2 更显眼，该屏对普通用户不合格。

---

## 七、与「Apple 风」视觉的关系

项目设计 token 参考了 Apple 官网式克制（大留白、少阴影、单一 Action Blue）。  
**克制不等于空洞**：Apple 产品页也有明确**视觉焦点**（一张产品图、一句 headline）。

当前客户端学到了「浅灰背景 + SF 字体」，但没学到「**每屏只有一个 hero**」。  
普通用户需要的不是更多灰色分区，而是：

- 更大的**可读回复区**
- 更少的**并行横条**
- 更明确的**主按钮**（发送 / 继续 / 批准）

美学应服务「一眼知道看哪里」，而不是增加分区数量。

---

## 八、结论：什么样的布局才「适合普通用户」？

一句话：**把 Mao 从「开发环境里的聊天插件」改成「以对话为主、以任务为记忆、以结论为默认展示」的助手产品。**

具体意味着：

1. **默认单栏对话**，侧栏可收起；顶栏极简；工作目录与连接状态不抢主舞台。  
2. **首页展示「我要继续的事」**，不是 Agent 卡片墙。  
3. **列表和标题说人话**，不说命令、路径、工具名。  
4. **工具输出渐进披露**，终端/Diff 是详情，不是主内容。  
5. **导航按使用频率分层**，创建 Agent、Hub、模式选择进二级。  
6. **开发者双栏、审查、日志** 作为高级能力 opt-in，而非默认布局。

若只做一件事：**让用户打开应用 3 秒内看到输入框，且眼睛只被输入框和最后一条助手回复吸引**——其余信息都是可选背景。  
当前布局的失败，不在于组件丑，而在于**从未决定「谁才是这一屏的主角」**。普通用户需要的，正是这个主角——**他们的问题和 Agent 的回答**，而不是工作台、Hub、路径和终端。

---

## 附录：与现有文档的关系

| 文档 | 侧重点 |
|------|--------|
| 本文 `desktop-layout-reflection.md` | 普通用户心智、布局范式、信息优先级 |
| `desktop-ux-refactor-plan.md` | Codex 映射、组件拆分、实施优先级 P0–P3 |
| `docs/best-agent-spec/DESIGN.md` | 视觉 token 与品牌规范 |

建议实施顺序：先按本文确定**默认布局范式（推荐方案 A + 任务化首页 B）**，再在 refactor plan 中落地组件与状态管理。