# TUI

## TUI（界面与操作）

UCAgent 自带基于 Textual 构建的终端界面（TUI），用于在本地交互式观察任务进度、消息流与控制台输出，并直接输入命令（如进入/退出循环、切换模式、执行调试命令等）。

### 界面组成

如“图 6：tui 界面组成所示例”

![tui界面组成](./tui-part.png)

- Mission 面板（左侧）

  - 阶段列表：显示当前任务的阶段（索引、标题、阶段技能（技能开启时）、失败数、耗时）。颜色含义：
    - 绿色：已完成阶段
    - 红色：当前进行阶段
    - 黄色：被跳过的阶段（显示“skipped”）
  - Changed Files：近期修改文件（含修改时间与相对时间，如“3m ago”）。较新的文件以绿色显示。
  - Tools Call：工具调用状态与计数。忙碌中的工具会以黄色高亮（如 SqThink(2)）。
  - Deamon Commands：后台运行的 demo 命令列表（带开始时间与已运行时长）。

- Status 面板（右上）

  - 显示 API 与代理状态摘要，以及当前面板尺寸参数（便于调节布局时参考）。

- Messages 面板（右上中）

  - 实时消息流（模型回复、工具输出、系统提示）。
  - 支持焦点与滚动控制，标题会显示“当前/总计”的消息定位。例如：Messages (123/456)。

- Console（底部）
  - Output：命令与系统输出区域，支持分页浏览。
  - Input：命令输入行（默认提示符 “(UnityChip) ”）。提供历史、补全、忙碌提示等。

提示：界面每秒自动刷新一次（不影响输入）。当消息或输出过长时，会进入分页或手动滚动模式。

### 操作与快捷键

**全局操作**

- Enter：执行当前输入命令；若输入为空会重复上一次命令；输入 q/Q/exit/quit 退出 TUI。
- Ctrl+C：取消正在运行的命令；若无命令在运行则退出 TUI。
- Esc：
  - 若正在浏览 Messages 的历史，退出手动滚动并返回末尾；
  - 若 Output 正在分页查看，退出分页；
  - 若帮助面板已打开，关闭帮助面板；
  - 否则清空输入行并聚焦到底部输入框。
- Tab：命令补全；再次按 Tab 可循环浏览候选项。
- Shift+Left：清空输入行。

**面板大小调整**

- Ctrl+Left / Ctrl+Right：缩小/增大左侧 Mission 面板宽度。
- Ctrl+Up / Ctrl+Down：增大/缩小底部 Console 输出区域高度。
- Ctrl+H / Ctrl+J / Ctrl+K / Ctrl+L：Vim 风格的面板调整快捷键，功能分别等同于 Ctrl+Left / Ctrl+Down / Ctrl+Up / Ctrl+Right（即 h=左 j=下 k=上 l=右）。

**Console 操作**

- Up / Down：
  - 若 Output 在分页模式，用于翻页；
  - 否则用于命令历史导航（将历史命令放入输入行，可编辑后回车执行）。
- PageUp / PageDown：在 Console Output 中翻页浏览。
- Shift+Right：清空 Console Output。

分页模式提示：当 Output 进入分页浏览时，底部会提示 "PageUp/PageDown: scroll, Esc: exit"，Esc 退出分页并返回输入状态。

**Messages 面板操作**

- Up / Down（Messages 面板获焦时）：手动滚动消息列表。
- Esc（Messages 面板获焦时）：退出手动滚动，恢复自动跟随最新消息。

**主题与帮助**

- Ctrl+T：打开主题选择器弹窗。选中主题后按 Enter 确认，按 Esc 取消并恢复原主题。
- F1：显示/隐藏快捷键帮助面板。

### 命令与用法

- 普通命令：直接输入并回车，例如 loop、tui、help 等（由内部调试器处理）。
- 历史命令：在输入行为空时按 Enter，将重复执行上一条命令。
- 清屏：输入 clear 并回车，仅清空 Output（不影响消息记录）。
- 演示/后台命令：命令末尾添加 & 将在后台运行，完成后会在 Output 区域提示结束；当前后台命令可通过 list_demo_cmds 查看。
- 直接执行系统/危险命令：以 ! 前缀执行（例如 !loop），该模式执行后优先滚动到最新输出。
- 列出后台命令：list_demo_cmds 显示正在运行的 demo 命令列表与开始时间。

#### 消息配置（message_config）

- 作用：在运行中查看/调整消息裁剪策略，控制历史保留与 LLM 输入 token 上限。
- 命令：
  - message_config 查看当前配置
  - message_config <key> <value> 设置配置项
- 可配置项：
  - max_keep_msgs：保留的历史消息条数（影响会话记忆窗口）
  - max_token：进入模型前的消息裁剪 token 上限（影响开销/截断）
- 示例：
  - message_config
  - message_config max_keep_msgs 8
  - message_config max_token 4096

其他说明

- 自动补全：支持命令名与部分参数的补全；候选项过多时分批显示，可多次按 Tab 查看剩余项。
- 忙碌提示：命令执行期间，输入框标题会轮转显示 (wait.), (wait..), (wait...)，表示正在处理。
- 自动滚动：Messages 面板和 Console 输出区均支持智能自动滚动。默认状态下自动跟随最新内容；使用鼠标滚轮或键盘翻页会进入手动滚动模式，保持当前位置不变；当手动滚动到末尾时，会自动恢复跟随模式。也可按 Esc 直接退出手动滚动。
- 错误容错：若某些 UI 操作异常（如终端不支持某些控制序列），TUI 会尽量回退到安全状态继续运行。

## 与 Web Master 协同使用

TUI 与 Web 并非互斥，推荐按场景组合：

1. TUI 适合本地快速调试与细粒度命令输入。
2. Web Master 适合集群化观察、托管任务运维与远程协作。

协同建议：

1. 用 Launch 页面完成文件准备与编译启动。
2. 用 Task 页面跟踪启动与日志。
3. 进入 Agent 页面执行阶段批量控制与结果复盘。
4. 需要本地即时修复时，切回 TUI 或本地终端。

注意：

1. 启用 web-terminal 时，可与本地终端并行。
2. 多终端会话场景建议用不同 URL 或页签区分任务。
