# Web UI

CodeBuddy Code 提供内置的 Web UI，在浏览器中提供完整的交互界面。当您以 serve 模式启动或开启远程控制时，Web UI 自动可用。

## 概述

Web UI 提供与终端界面相同的核心能力，并针对浏览器进行了可视化布局优化：

- **对话**：发送消息、查看对话、实时监控工具执行
- **终端**：内嵌终端，支持分屏布局（最多 4 个面板）
- **实例**：管理和切换多个 CodeBuddy Code 实例
- **远程控制**：连接微信和企业微信渠道
- **任务**：浏览任务模版并创建定时任务
- **插件**：管理插件安装和插件市场
- **设置**：配置主题、语言、模型和权限模式
- **文档**：浏览 CLI 文档，支持全文搜索
- **API 文档**：查看交互式 Swagger UI，方便 HTTP API 探索

## 访问 Web UI

### 方式一：Serve 模式

使用 `--serve` 参数启动 CodeBuddy Code：

```bash
codebuddy --serve --port 7890
```

然后在浏览器中打开：

```
http://127.0.0.1:7890
```

### 方式二：远程控制

在已有的 CodeBuddy Code 会话中启动 Gateway：

```
/gateway
```

终端会显示二维码和 URL。用手机扫码或在浏览器中打开 URL。详见[远程控制](remote-control.md)文档。

## 认证方式

Web UI 支持两种认证模式：

| 模式 | 设置 | 说明 |
|:-----|:-----|:-----|
| 免认证（默认） | `CODEBUDDY_GATEWAY_AUTH=none` | 无需密码 |
| 密码认证 | `CODEBUDDY_GATEWAY_AUTH=password` | 启动时终端显示密码 |

认证方式（以下任一方式均可）：

- **URL 参数**：`?password=xxx` — 通过 URL 自动登录
- **登录页面**：输入终端显示的密码
- **Bearer Token**：`Authorization: Bearer <password>`，用于 API 访问

在 `~/.codebuddy/settings.json` 中配置：

```json
{
  "gateway.auth": "none"
}
```

## 功能详解

### 对话视图

默认视图，用于与 Agent 交互。核心功能：

- **富文本消息渲染**：Markdown、语法高亮代码块、表格、图片
- **工具执行展示**：内联查看工具调用、参数和结果
- **权限管理**：在浏览器中直接批准或拒绝工具权限
- **问答面板**：回答 Agent 的多选问题
- **任务进度**：实时监控后台任务和 Team 进度
- **会话管理**：新建对话、浏览历史、切换会话

### 终端视图

基于 xterm.js 的内嵌终端：

- **分屏布局**：支持水平和垂直分屏，最多 4 个面板
- **独立会话**：每个面板有独立的 PTY 会话
- **持久连接**：终端会话在页面刷新后保持
- **自适应调整**：窗口大小变化时面板自动调整

### 文档视图

在 Web UI 中直接浏览 CLI 文档：

- **全文搜索**：基于 MiniSearch 搜索所有文档
- **多语言**：自动跟随 UI 语言设置（中文/英文）
- **目录导航**：根据文档标题自动生成，带滚动追踪
- **内部跳转**：文档链接在查看器内导航（SPA 模式）
- **API 文档**：快速链接到 `/api/docs` 的交互式 Swagger UI

### 实例管理

管理多个 CodeBuddy Code 实例：

- **实例列表**：查看所有运行中的实例及其工作目录和状态
- **快速切换**：一键切换实例
- **手动添加**：通过 URL 添加远程实例
- **隧道支持**：通过 Cloudflare Tunnel 访问实例

### 设置

- **主题**：浅色、深色或跟随系统（自动检测）
- **语言**：中文、英文或跟随系统（自动检测）
- **模型**：从可用选项中选择 AI 模型
- **权限模式**：默认、接受编辑、跳过权限或规划模式

## API 文档

HTTP 服务运行时，可在以下地址访问交互式 API 探索器：

```
http://127.0.0.1:{PORT}/api/docs
```

Swagger UI 提供以下功能：

- 浏览所有可用的 REST API 端点
- 查看请求/响应 Schema
- 直接在浏览器中测试 API 调用
- 在 `/api/openapi.json` 下载 OpenAPI 3.1 规范

完整的 API 参考请见 [HTTP API 文档](http-api.md)。

## 移动端支持

Web UI 完全响应式，支持移动设备：

- **侧边栏**：小屏幕上折叠为滑出式抽屉
- **PWA 支持**：添加到主屏幕获得类原生应用体验
- **触控优化**：所有交互针对触摸操作优化
- **扫码访问**：终端扫码即可在手机上打开

## 快捷键

| 快捷键 | 操作 |
|:-------|:-----|
| `Enter` | 发送消息 |
| `Shift+Enter` | 输入换行 |
| `Escape` | 停止运行中的 Agent |

## 技术细节

- **框架**：React 18 + Zustand 状态管理
- **通信**：ACP 协议，基于 HTTP/SSE（非 WebSocket）
- **样式**：Tailwind CSS + CSS 变量主题
- **终端**：xterm.js + fit addon
- **搜索**：MiniSearch 客户端全文搜索
- **Markdown**：react-markdown + remark-gfm + 语法高亮

## 相关文档

- [远程控制](remote-control.md) — 通过 Gateway 和 Tunnel 启动 Web UI
- [HTTP API](http-api.md) — 完整的 REST API 文档
- [ACP 协议](acp.md) — IDE 集成的 Agent Client Protocol
- [设置](settings.md) — 配置选项
