docs/research/desktop-layout-reflection.md
Rama main · réplica de lectura del repositorio original.
# 桌面客户端布局反思：普通用户需要什么？
> 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 中落地组件与状态管理。