# AgentWindow Web UI 用户指南

## 简介

AgentWindow Web UI 是一个基于浏览器的管理界面，用于管理你的 AI Bot 实例。采用 Apple 风格设计，提供简洁优雅的用户体验。

## 快速开始

### 启动 Web UI

```bash
agent-window ui
```

服务器将在 `http://127.0.0.1:3721` 启动，浏览器会自动打开。

### 命令选项

| 选项 | 说明 |
|------|------|
| `--port, -p <port>` | 指定端口号（默认：3721） |
| `--no-open` | 不自动打开浏览器 |
| `--dev` | 开发模式 |

---

## 功能说明

### 1. Dashboard（仪表板）

主页显示所有 Bot 实例的状态概览：

- **统计卡片**：显示总数、运行中、已停止、错误数量
- **实例卡片**：每个实例显示：
  - 名称和显示名称
  - 运行状态（运行中/已停止/错误）
  - 内存使用量
  - CPU 使用率
  - 运行时间
  - 快捷操作按钮（启动/停止/重启）

### 2. 实例管理

#### 添加实例

1. 点击右上角 **"Add Instance"** 按钮
2. 填写表单：
   - **Name**: 实例标识符（小写字母、数字、连字符）
   - **Display Name**: 显示名称
   - **Project Path**: Bot 项目路径
   - **Tags**: 标签（可选，逗号分隔）

3. 点击 **"Add Instance"** 完成

#### 删除实例

1. 进入 **Instances** 页面
2. 找到要删除的实例
3. 点击 **"Delete"** 按钮
4. 确认删除

#### 实例操作

每个实例卡片有三个操作按钮：

| 按钮 | 功能 | 说明 |
|------|------|------|
| ▶ | 启动 | 启动已停止的实例 |
| ⏸ | 停止 | 停止运行中的实例 |
| 🔄 | 重启 | 重启实例 |

### 3. 实例详情

点击实例卡片上的 **"Details"** 按钮进入详情页面，查看：

- **状态面板**：PID、内存、CPU、重启次数
- **信息面板**：路径、配置、添加时间、标签
- **实时日志**：最近的日志输出

### 4. 实时日志

日志查看器功能：

- **Live 开关**：启用/禁用实时日志流
- **类型过滤**：All / Stdout / Stderr
- **搜索**：搜索日志内容
- **导出**：下载日志为文本文件
- **清空**：清空当前日志显示
- **全屏**：全屏查看日志

### 5. 设置

设置页面显示：

- 系统信息（平台、Node 版本、版本号）
- 外观设置（深色模式切换）
- 关于信息

---

## 支持的 Bot 类型

### 类型 1: 独立 Bot

普通的 Discord/Slack Bot，具有基本结构：

```
my-bot/
├── config.json
├── package.json (含 discord.js)
└── src/
    └── bot.js
```

### 类型 2: BMAD 插件

集成 BMAD 框架的高级 Bot：

```
my-bmad-bot/
├── _bmad/              # BMAD 框架
│   ├── core/           # 核心模块
│   ├── bmm/            # BMAD 业务模块
│   └── _config/        # 配置文件
├── _agent-bridge/      # 插件目录
│   └── src/
│       └── bot.js      # Bot 入口
└── package.json        # 依赖 discord.js
```

---

## 实例添加示例

### 示例 1: 添加独立 Bot

```bash
# 假设你有一个简单 Bot 在 ~/bots/my-bot
agent-window instance add my-bot ~/bots/my-bot
```

或在 Web UI 中：
- Name: `my-bot`
- Display Name: `My Bot`
- Project Path: `/Users/yourname/bots/my-bot`

### 示例 2: 添加 BMAD Bot

```bash
# 添加 BMAD 企业 Bot
agent-window instance add corp-office ~/projects/corp-office --tags prod,bmad
```

或在 Web UI 中：
- Name: `corp-office`
- Display Name: `Corporate Office Bot`
- Project Path: `/Users/yourname/projects/corp-office`
- Tags: `prod, bmad`

---

## CLI 命令参考

### 实例管理

```bash
# 列出所有实例
agent-window instance list

# 添加实例
agent-window instance add <name> <project-path> [options]

# 删除实例
agent-window instance remove <name>

# 查看实例详情
agent-window instance info <name>

# 实例配置
agent-window instance config <name> get <key>
agent-window instance config <name> set <key> <value>
agent-window instance config <name> list
agent-window instance config <name> backup
```

### 实例操作

```bash
# 启动实例
agent-window instance start <name>

# 停止实例
agent-window instance stop <name>

# 重启实例
agent-window instance restart <name>

# 查看状态
agent-window instance status <name>

# 查看日志
agent-window instance logs <name>
```

---

## 常见问题

### Q: Web UI 无法启动？

A: 检查：
1. 端口 3721 是否被占用
2. 前端是否已构建 (`npm run ui:build`)
3. 依赖是否已安装

### Q: 添加实例失败？

A: 确保项目：
1. 路径存在且可访问
2. 包含 `package.json` 和 `src/bot.js`
3. BMAD 项目需要 `_bmad` 目录

### Q: 实例状态显示 Unknown？

A: 这表示实例未在 PM2 中运行，使用 `start` 按钮启动。

### Q: 日志不显示？

A: 检查：
1. 实例是否已启动
2. Live 开关是否已启用
3. 浏览器控制台是否有错误

---

## 键盘快捷键

| 快捷键 | 功能 |
|--------|------|
| `Cmd/Ctrl + K` | 聚焦搜索框 |
| `Esc` | 关闭模态框 |
| `Cmd/Ctrl + /` | 切换深色模式 |

---

## 技术支持

- 项目地址：https://github.com/Observer-GGboy/AgentWindow
- 问题反馈：GitHub Issues