# WebUI 指南

# 网页界面

网页界面适合大多数新手。它比命令行更直观，可以同时看到聊天记录、设置、知识库、技能、工具和任务状态。

## 启动网页界面

网页界面由 WebSocket 频道提供。先确认配置中有：

    {
      "channels": {
        "websocket": {
          "enabled": true,
          "host": "127.0.0.1",
          "port": 18790
        }
      }
    }

然后启动网关：

    uv run tinybot gateway

浏览器打开：

    http://127.0.0.1:18790

如果你只是本机使用，`host` 建议保持 `127.0.0.1`，不要改成公网可访问地址。

## 界面区域

区域 | 用途
--- | ---
左侧会话列表 | 新建会话、切换历史会话、继续之前的对话
中间聊天区 | 输入需求、查看 Tinybot 的回复和执行过程
右侧面板 | 管理工具、知识库、技能、设置和工作区文件
顶部或状态区 | 查看当前模型、连接状态、任务状态

## 第一次使用流程

1. 打开网页后先进入设置面板
2. 确认 Provider、API Key、Model 已配置
3. 回到聊天区，发送一条简单消息测试
4. 再尝试让 Tinybot 读取工作区或整理文档

测试消息示例：

    你好，请告诉我你当前使用的模型，并说明你能帮我做什么。

如果它能正常回复，再尝试：

    请阅读当前工作区的 README，帮我总结项目用途和启动方式。

## 会话管理

网页界面会保存会话历史。你可以：

操作 | 说明
--- | ---
新建会话 | 用于开始一个新的主题
切换会话 | 回到之前的上下文继续提问
清空会话 | 删除当前会话的历史上下文
删除会话 | 移除不再需要的历史记录

建议不同任务使用不同会话。例如“项目分析”“写文档”“日常问答”分开，这样上下文更清晰。

## 右侧功能面板

### 设置

用于修改模型、密钥、工作区和工具开关。新手最常用的是：

设置 | 用途
--- | ---
`providers.*.apiKey` | 配置对应 AI 服务的密钥
`agents.defaults.model` | 选择模型
`agents.defaults.workspace` | 设置文件操作范围
`tools.restrictToWorkspace` | 限制 Tinybot 只能操作工作区

### 工具

显示 Tinybot 当前能使用的工具。工具包括文件操作、命令执行、网络搜索、MCP 扩展等。工具越多，能力越强，但也更需要你明确授权范围。

### 知识库

用于让 Tinybot 引用你提供的资料回答问题。适合放产品手册、项目说明、流程规范、会议资料等。

### 技能

技能是行为说明。你可以启用、禁用或创建技能，让 Tinybot 在特定场景下按固定流程工作。

### 工作区文件

用于查看 Tinybot 能访问的文件范围。让 Agent 修改文件前，建议先确认工作区指向正确目录。

## 什么时候使用网页界面

场景 | 推荐程度
--- | ---
第一次配置 Tinybot | 推荐
长时间和 AI 协作 | 推荐
管理知识库和技能 | 推荐
快速问一句话 | 命令行 `agent -m` 更快
作为 API 后端集成 | 使用 `tinybot api`

## 常见问题

### 浏览器打不开

检查：

1. 是否启动了 `uv run tinybot gateway`
2. WebSocket 频道是否启用
3. 端口是否被占用
4. 地址是否写成了 `http://127.0.0.1:18790`

### 页面能打开，但 AI 不回复

检查：

1. API Key 是否正确
2. 模型名称是否匹配 Provider
3. 账户余额是否足够
4. 后端终端是否有错误日志

### 修改设置后没有立即生效

模型和密钥通常可以动态更新。少数网关、频道或工具配置可能需要重启：

    uv run tinybot gateway

## 下一步

- 知识库：把自己的文档交给 Tinybot 使用
- 技能系统：让 Tinybot 按固定工作流办事
- 配置说明：理解每个常用配置项