# Jarvis TUI 快速开始

## 使用场景

当你希望通过终端界面与 Jarvis 进行交互时，可以使用 TUI（Terminal User Interface）版本。TUI 提供了图形化的终端界面，支持：

- 可视化 Agent 管理
- 实时聊天交互
- 终端命令执行
- 文件查看与编辑

## 启动 TUI

### 操作步骤

1. 打开终端
2. 输入启动命令：

   ```bash
   jvs-tui
   ```

   或者：

   ```bash
   python -m jarvis.jarvis_tui
   ```

3. 等待 TUI 界面加载完成

### 你会看到的提示与反馈

- 启动成功后会显示 "Jarvis TUI" 标题
- 首次启动会自动进入登录界面

## 登录流程

### 使用场景

首次使用或会话过期时，需要先登录到 Jarvis 网关。

### 操作步骤

1. 在登录界面，你会看到两个输入框：
   - **服务器地址**：输入 Jarvis 网关地址（默认：`localhost:8000`）
   - **密码**：输入认证密码

2. 填写服务器地址（如保持默认可直接跳过）

3. 填写密码

4. 按以下方式之一提交登录：
   - 点击「登录」按钮
   - 在密码框中按回车键

5. 等待登录验证

### 你会看到的提示与反馈

- **登录成功**：自动跳转到主界面
- **认证失败**：显示红色错误提示「认证失败：xxx」
- **连接失败**：显示红色错误提示「连接失败：xxx」
- **输入为空**：显示对应字段的必填提示

### 注意事项

- 按 `Esc` 键可以退出 TUI 应用
- 确保 Jarvis 网关服务已启动

## 功能清单

Jarvis TUI 提供以下核心功能：

| 功能分类       | 功能名称      | 功能描述                     | 使用场景                  |
| -------------- | ------------- | ---------------------------- | ------------------------- |
| **认证管理**   | 登录/注销     | 连接到 Jarvis 网关并认证身份 | 首次使用或会话过期时      |
| **Agent 管理** | 新建 Agent    | 创建新的 Agent 实例          | 需要独立对话上下文时      |
| **Agent 管理** | 选择 Agent    | 切换当前活跃的 Agent         | 在多个 Agent 间切换       |
| **Agent 管理** | 删除 Agent    | 移除不需要的 Agent           | 清理不再使用的 Agent      |
| **聊天交互**   | 发送消息      | 向当前 Agent 发送文本消息    | 与 Agent 进行对话         |
| **聊天交互**   | 流式回复      | 实时显示 Agent 的逐字回复    | 等待长回答时查看进度      |
| **聊天交互**   | Markdown 渲染 | 自动格式化代码、表格等格式   | 查看结构化内容            |
| **聊天交互**   | 历史对话      | 保存和加载 Agent 的对话历史  | 回顾之前的交流内容        |
| **终端操作**   | 终端面板      | 在 TUI 内执行系统命令        | 无需退出 TUI 即可运行命令 |
| **终端操作**   | 显示/隐藏终端 | 按需切换终端面板可见性       | 节省屏幕空间              |
| **连接管理**   | 连接状态显示  | 实时显示与网关的连接状态     | 监控连接健康度            |
| **连接管理**   | 重新连接      | 手动触发与网关的重新连接     | 连接断开或异常时          |
| **界面操作**   | 快捷键支持    | 提供多种快捷键提升操作效率   | 快速执行常用操作          |
| **界面操作**   | 侧边栏导航    | 通过侧边栏管理和选择 Agent   | 直观管理多个 Agent        |

## 主界面介绍

登录后进入主界面，界面分为以下几个区域：

```text
┌─────────────────────────────────────────────────────────┐
│  Header (标题栏)                                         │
├──────────┬──────────────────────────────┬───────────────┤
│          │  连接状态                     │               │
│  侧边栏   │  ┌──────────────────────┐   │   终端面板     │
│  (Agents) │  │     聊天面板          │   │  (可隐藏)     │
│          │  │                      │   │               │
│          │  ├──────────────────────┤   │               │
│          │  │     输入面板          │   │               │
│          │  └──────────────────────┘   │               │
├──────────┴──────────────────────────────┴───────────────┤
│  Footer (快捷键提示)                                      │
└─────────────────────────────────────────────────────────┘
```

### 各区域功能

| 区域         | 功能说明                                         |
| ------------ | ------------------------------------------------ |
| **侧边栏**   | 显示 Agent 列表，支持新建、选择、删除 Agent      |
| **连接状态** | 显示当前与网关的连接状态（已连接/连接中/未连接） |
| **聊天面板** | 显示与当前 Agent 的对话历史，支持 Markdown 渲染  |
| **输入面板** | 输入消息内容，发送给当前 Agent                   |
| **终端面板** | 执行系统命令（默认隐藏，可按快捷键显示）         |

## 核心功能操作指南

### 1. Agent 管理

#### 新建 Agent

**操作步骤：**

1. 在侧边栏点击「新建」按钮，或按快捷键 `Ctrl+N`
2. 系统会自动创建新 Agent（名称格式：`Agent-序号`）
3. 新 Agent 会自动选中并出现在侧边栏列表中

**你会看到的提示与反馈：**

- 侧边栏列表中出现新的 Agent 项
- 右下角弹出提示：「已创建 Agent-X」
- 聊天面板切换到新 Agent（初始为空）

#### 选择 Agent

**操作步骤：**

1. 在侧边栏的 Agent 列表中点击目标 Agent
2. 或在列表中上下移动选择后按回车

**你会看到的提示与反馈：**

- 选中的 Agent 前显示「●」标记
- 聊天面板加载该 Agent 的历史消息
- 连接状态更新（如需要重新连接）

#### 删除 Agent

**操作步骤：**

1. 在侧边栏选中要删除的 Agent
2. 点击「删除」按钮

**你会看到的提示与反馈：**

- 该 Agent 从侧边栏列表中移除
- 右下角弹出提示：「Agent 已删除」

### 2. 发送消息

**操作步骤：**

1. 确保已选择一个 Agent（侧边栏中有选中项）
2. 在底部输入面板中输入消息内容
3. 按以下方式之一发送：
   - 点击「发送」按钮
   - 按 `Ctrl+Enter` 组合键

**你会看到的提示与反馈：**

- 你的消息显示在聊天面板右侧（标注「你：」）
- Agent 回复显示在左侧（标注「Jarvis：」）
- 支持流式输出（逐字显示）
- 消息内容支持 Markdown 格式渲染

### 3. 终端面板

**使用场景：**

需要在 TUI 中直接执行系统命令时使用。

**操作步骤：**

1. 按 `Ctrl+T` 显示/隐藏终端面板
2. 在终端输入框中输入命令
3. 按回车执行命令

**你会看到的提示与反馈：**

- 命令输出显示在终端面板中
- 错误信息以红色显示
- 成功信息以绿色显示

### 4. 连接管理

#### 重新连接

**操作步骤：**

- 按 `Ctrl+R` 重新连接到网关

**你会看到的提示与反馈：**

- 连接状态变为黄色「连接中...」
- 连接成功后变为绿色「● 已连接」
- 右下角弹出提示：「连接成功」

#### 注销登录

**操作步骤：**

- 按 `Ctrl+L` 注销当前登录

**你会看到的提示与反馈：**

- 断开所有连接
- 返回登录界面
- 清除本地存储的认证信息

## 快捷键列表

| 快捷键       | 功能       | 说明                   |
| ------------ | ---------- | ---------------------- |
| `Ctrl+Q`     | 退出       | 关闭 TUI 应用          |
| `Ctrl+T`     | 切换终端   | 显示/隐藏终端面板      |
| `Ctrl+N`     | 新建 Agent | 创建新的 Agent 实例    |
| `Ctrl+L`     | 注销       | 退出登录，返回登录界面 |
| `Ctrl+R`     | 重连       | 重新连接到网关         |
| `Esc`        | 退出       | 在登录界面时退出应用   |
| `Ctrl+Enter` | 发送       | 在输入面板中发送消息   |

## 常见问题

### Q1: 启动时提示找不到命令

**问题现象：**

```bash
command not found: jvs-tui
```

**解决方法：**

确保 Jarvis 已正确安装：

```bash
pip install -e .
```

或使用模块方式启动：

```bash
python -m jarvis.jarvis_tui
```

### Q2: 登录时连接失败

**可能原因：**

- Jarvis 网关服务未启动
- 服务器地址或端口错误
- 网络问题

**解决方法：**

1. 确认网关服务已启动
2. 检查服务器地址格式（如 `localhost:8000`）
3. 确认防火墙允许连接

### Q3: 发送消息无响应

**可能原因：**

- 未选择 Agent
- Agent 未连接
- 网关连接断开

**解决方法：**

1. 在侧边栏选择一个 Agent
2. 观察连接状态，确保显示「已连接」
3. 如需要，按 `Ctrl+R` 重新连接

### Q4: 如何查看历史对话

**操作方法：**

- 在侧边栏选择对应的 Agent
- 聊天面板会自动加载该 Agent 的历史消息
- 使用鼠标滚轮或方向键上下滚动查看

## 注意事项

1. **连接依赖**：TUI 需要连接到运行中的 Jarvis 网关服务才能正常工作
2. **Agent 隔离**：每个 Agent 有独立的对话历史，切换 Agent 会切换聊天内容
3. **终端面板**：终端面板默认隐藏，按需显示以避免占用过多空间
4. **消息格式**：输入消息支持纯文本，Agent 回复支持 Markdown 格式渲染
5. **会话保持**：登录信息会本地保存，下次启动时无需重新登录（除非手动注销）
