# TUI 布局架构

## 1. Identity

- **What it is:** MiniCC 终端用户界面的整体布局和组件组织
- **Purpose:** 为用户提供清晰、高效的聊天交互界面

## 2. 整体布局

```
┌──────────────────────────────────────┐
│        Header (MiniCC 时钟)          │
├──────────────────────────────────────┤
│     chat_container (VerticalScroll)  │
│  ├─ MessagePanel (用户/助手消息)    │
│  ├─ ToolCallLine (工具调用单行)     │
│  ├─ SubAgentLine (SubAgent 单行)   │
│  └─ DiffView (文件变更预览)         │
├──────────────────────────────────────┤
│     Input (用户输入框，焦点)          │
├──────────────────────────────────────┤
│ 📦 Model │ 📁 CWD │ 🌿 Branch │ Token│
├──────────────────────────────────────┤
│  Footer (快捷键: Ctrl+C退出, Ctrl+L清屏)
└──────────────────────────────────────┘
```

## 3. 核心组件

### Header
显示应用标题和实时时钟。Textual 内置组件，无需自定义。

### chat_container (VerticalScroll)
**文件:** `minicc/app.py:85` (`VerticalScroll`)

主消息区域，包含：
- `MessagePanel`: 用户/助手消息（支持 Markdown）
- `ToolCallLine`: 工具调用单行显示（`🔧 name (param) ✅/❌`）
- `SubAgentLine`: SubAgent 任务单行显示（`🤖 prompt ⏳/🔄/✅/❌`）
- `DiffView`: 文件变更预览（颜色区分 +/-/context）

消息自动滚动到最新。容器由 `_on_tool_call()` 管理组件挂载。

### Input
用户输入框，提交时触发 `on_input_submitted` 事件。

### BottomBar
**文件:** `minicc/app.py:87-92` (BottomBar 组件)

分区块显示：
- `📦 模型`: provider:model
- `📁 目录`: 当前 cwd
- `🌿 分支`: git 分支名
- `⬆️⬇️ Token`: 输入/输出 token 数

实时更新，不可折叠。

### Footer
显示快捷键列表。Textual 内置组件。

## 4. 消息流处理

消息处理链：
```
Input.Submitted
  → _process_message(user_input)
    → agent.run_stream_events() [异步流处理]
      → PartStartEvent → 开始流式输出
      → PartDeltaEvent → 累积 text delta
      → 工具调用事件 → _on_tool_call()
         ├─ spawn_agent → mount SubAgentLine
         └─ 其他工具 → mount ToolCallLine
      → 最终事件 (AgentRunResultEvent)
         → _update_tokens() [更新 BottomBar token]
         → _append_message() [mount MessagePanel]
  → 自动滚动到底部
```

关键方法：
- `_process_message()` (app.py:140-170): 消息处理入口
- `_on_tool_call()` (app.py:175-202): 工具调用回调
- `_update_tokens()` (app.py:207-215): token 更新

## 5. 快捷键

| 快捷键 | 功能 |
|--------|------|
| Ctrl+C | 退出应用 |
| Ctrl+L | 清屏并重置 |
| Escape | 取消当前操作 |

## 6. 设计演进

### v0.x (初版)
- 水平布局: chat_container + side_panel
- 侧边栏显示: StatusBar + info_card + TabbedContent
- 可折叠面板: CollapsibleToolPanel / SubAgentPanel

### v1.0 (当前)
- 纵向布局: Header → chat_container → Input → BottomBar → Footer
- 移除侧边栏，释放水平空间
- **单行简洁设计:** ToolCallLine / SubAgentLine (不再可折叠)
  - `🔧 name (param) ✅` 一行显示完整工具调用
  - `🤖 prompt ⏳` 一行显示 SubAgent 状态
- **BottomBar:** 恒定显示关键上下文 (模型/目录/分支/Token)

### 设计优势
- **视觉清洁:** 移除冗余信息和可折叠交互
- **信息密度高:** BottomBar 在一行内显示 4 项关键信息
- **空间利用率:** 聊天区域宽度增加 ~30-40%
- **交互简化:** 消息与工具调用内联，无需切换 Tab
