2941 Desktop App Guide 10235456

# OpenAkita 桌面终端 - 使用指南与功能介绍

> OpenAkita Desktop Terminal —— 集 AI 聊天、IM 通道监控、技能管理、系统状态、全流程配置于一体的桌面客户端。

---

## 目录

- [概览](#概览)
- [快速开始](#快速开始)
- [一、聊天](#一聊天)
- [二、IM 通道监控](#二im-通道监控)
- [三、技能管理](#三技能管理)
- [四、系统状态](#四系统状态)
- [五、配置向导](#五配置向导)
- [附录：快捷键与技巧](#附录快捷键与技巧)

---

## 概览

OpenAkita 桌面终端基于 **Tauri 2 + React 18** 构建，通过 HTTP SSE 连接后端 `openakita serve` 服务。支持两种运行模式：

- **本地模式**：桌面端自动启动本地后端服务（需完成配置向导）
- **远程模式**：连接已在运行的 `openakita serve` 实例（适合开发调试或服务器部署）

### 界面布局

```
+------------------------------------------+
| 标题栏                                    |
+--------+---------------------------------+
| 侧边栏  | 顶栏：工作区 | 状态 | 端点数 | 操作按钮 |
|        +---------------------------------+
| 聊天    |                                 |
| IM 通道 |        主内容区域                 |
| 技能    |                                 |
| 状态    |                                 |
| 配置 ▸  |                                 |
+--------+---------------------------------+
```

**顶栏信息**：当前工作区名称、服务运行状态（绿色/灰色指示灯）、可用端点数、远程模式标识、连接/断开/刷新/语言切换按钮。

---

## 快速开始

1. **首次启动**：打开应用后，展开左侧「配置」，按照 9 步向导完成初始化
2. **启动服务**：顶栏点击「启动服务」，或在终端运行 `openakita serve`
3. **连接服务**：如果已有后端运行，点击顶栏「连接服务」输入地址（默认 `127.0.0.1:18900`）
4. **开始使用**：点击侧边栏「聊天」即可对话

---

## 一、聊天

聊天页面是桌面终端的核心功能，提供完整的 AI 对话体验，与 IM/CLI 通道使用相同的 Agent 管线（Persona、记忆、工具、技能、上下文压缩）。

### 1.1 基本对话

- **流式输出**：AI 回复实时流式显示，支持 Markdown 渲染（表格、代码块、列表等）
- **代码高亮**：代码块自动语法高亮（highlight.js）
- **消息保持**：切换到其他页面再回来，聊天记录不会丢失

### 1.2 LLM 端点选择

输入框左侧有模型选择器：

- **自动选择**（默认）：系统自动选择可用端点，故障时自动切换
- **指定端点**：从下拉列表中选择特定端点（如 `gpt-5.2`、`claude-opus`），指定后不会自动回退，出错时直接提示

### 1.3 多模态输入

| 输入方式 | 操作 | 支持格式 |
|---------|------|---------|
| 文字 | 直接输入 | - |
| 图片 | 点击附件按钮或粘贴 | PNG, JPG, JPEG, WebP, GIF |
| 文件 | 点击附件按钮 | PDF, TXT, MD, PY, JS, TS, JSON, CSV 等 |
| 语音 | 点击麦克风按钮录音 | 自动录制为 WebM 并上传 |
| 粘贴图片 | Ctrl+V 粘贴剪贴板图片 | 自动识别并添加为附件 |

附件会显示为预览缩略图，可点击删除。

### 1.4 斜杠命令

在输入框中输入 `/` 弹出命令面板，支持模糊搜索和键盘导航（上下键 + Enter）：

| 命令 | 功能 | 示例 |
|------|------|------|
| `/model <端点>` | 切换 LLM 端点 | `/model gpt-5.2` |
| `/plan` | 开启/关闭 Plan 模式 | `/plan` |
| `/clear` | 清空当前对话 | `/clear` |
| `/skill <技能名>` | 查看技能用法 | `/skill docx` |
| `/persona <角色>` | 切换 Agent 人格 | `/persona girlfriend` |
| `/agent <名称>` | 切换 Agent（多 Agent 模式） | `/agent researcher` |
| `/agents` | 查看可用 Agent 列表 | `/agents` |
| `/help` | 显示帮助 | `/help` |

**可用人格预设**：`default`（默认助手）、`business`（商务）、`tech_expert`（技术专家）、`butler`（管家）、`girlfriend`（女友感）、`boyfriend`（男友感）、`family`（家人感）、`jarvis`（贾维斯）

### 1.5 Plan 模式

点击输入框内的 Plan 按钮开启，AI 在执行复杂任务前会先制定计划：

- **计划创建**：AI 自动拆解任务为多个步骤
- **步骤追踪**：每个步骤实时显示状态（待执行 / 执行中 / 已完成 / 已跳过 / 失败）
- **可视化**：计划以卡片形式展示在对话流中，进度一目了然

适合 3 个以上工具协作的复杂任务。简单任务建议关闭，AI 会直接执行。

### 1.6 思考过程显示

AI 的推理思考过程以可折叠面板展示：

- 默认折叠，点击「思考过程」可展开查看
- 包含 AI 的内部推理、决策逻辑
- 支持深度思考模式（thinking model）

### 1.7 向用户提问（ask_user）

当 AI 需要澄清信息或确认操作时，会显示提问卡片：

- 支持自由文本输入回复
- 回复后 AI 继续执行任务
- 有超时机制（约 2 分钟），超时后 AI 自行决策

### 1.8 文件与图片接收

AI 通过 `deliver_artifacts` 工具发送的文件会在对话中内联展示：

| 类型 | 展示方式 |
|------|---------|
| 图片 | 内联显示缩略图，点击在新窗口打开 |
| 语音 | 内联音频播放器 |
| 文件 | 显示文件名和大小，点击下载 |

### 1.9 工具调用展示

AI 调用工具时，对话中会显示工具调用详情：

- 工具名称和参数（可展开查看）
- 执行结果
- 便于了解 AI 的操作过程和调试

---

## 二、IM 通道监控

IM 通道页面用于查看和管理所有已配置的即时通讯通道。

### 2.1 支持的 IM 通道

| 通道 | 类型 | 协议 |
|------|------|------|
| Telegram | Bot | Telegram Bot API |
| 飞书 (Feishu) | 企业应用 | WebSocket 长连接 |
| 企业微信 (WeCom) | 智能机器人 | Webhook 回调 |
| 钉钉 (DingTalk) | 智能机器人 | Stream 模式 |
| QQ 官方机器人 | Bot | QQ 开放平台 API |
| OneBot | Bot | OneBot v11 协议 |

### 2.2 通道状态

每个通道显示：

- **连接状态**：在线（绿色）/ 离线（灰色）/ 配置缺失（黄色）
- **会话数**：当前活跃会话数量
- **应用类型**：如「智能机器人」「企业应用」等
- **应用图标**：各 IM 平台 Logo

### 2.3 会话查看

- 左侧面板：通道列表 + 该通道下的会话列表
- 右侧面板：选中会话的消息记录
- 支持显示文本、图片、语音、文件等消息类型
- 每 30 秒自动轮询更新

---

## 三、技能管理

技能（Skills）是 OpenAkita 的可扩展能力模块，遵循 Agent Skills 标准。

### 3.1 已安装技能

- **技能列表**：展示所有已安装技能的名称、描述、类型（系统/外部）
- **状态标识**：
  - 已启用 / 已禁用
  - 配置完整 / 配置不完整（需要填写 API Key 等）
- **技能配置**：点击技能展开配置表单，支持的配置类型：
  - 文本输入（string）
  - 密钥输入（secret，带显示/隐藏切换）
  - 下拉选择（select）
  - 开关（bool）
  - 数字（number）
- **保存配置**：配置保存到工作区 `.env` 文件

### 3.2 技能市场

技能市场由 [skills.sh](https://skills.sh) 提供支持：

- **实时搜索**：输入关键词（如 `react`、`testing`、`deploy`）搜索全球技能库
- **安装量排序**：搜索结果按安装量排序
- **一键安装**：点击安装按钮，自动下载并注册到本地
- **默认推荐**：进入市场时自动展示热门技能

### 3.3 内置技能示例

系统内置 60+ 系统技能和 29+ 外部技能，涵盖：

| 分类 | 技能示例 |
|------|---------|
| 文件操作 | run-shell, read-file, write-file, list-directory |
| 浏览器自动化 | browser-task, browser-navigate, browser-click, browser-screenshot |
| 桌面自动化 | desktop-click, desktop-type, desktop-screenshot, desktop-hotkey |
| 文档处理 | docx, pdf, pptx, xlsx |
| 开发工具 | code-reviewer, changelog-generator, mcp-builder |
| 网络搜索 | web-search, news-search |
| 任务调度 | schedule-task, list-scheduled-tasks |
| 记忆管理 | add-memory, search-memory |
| 多媒体 | generate-image, video-downloader, image-understanding |

---

## 四、系统状态

状态面板提供系统运行状况的全面视图。

### 4.1 服务状态

- **运行状态**：显示后端服务是否运行中，以及进程 PID
- **操作按钮**：
  - 启动服务
  - 停止服务（优雅关闭）
  - 重启服务

### 4.2 LLM 端点健康检测

- **端点列表**：展示所有已配置的 LLM 端点
- **状态指示**：
  - 健康（绿色）：正常可用
  - 降级（黄色）：有失败但仍可用
  - 不可用（红色）：连续失败，进入冷却期
- **延迟**：每个端点的响应延迟（毫秒）
- **Key 状态**：API Key 是否已配置
- **检测操作**：单个端点检测 / 全部检测
- **只读检测**：健康检测不会影响端点的冷却状态，不干扰正在进行的 AI 对话

### 4.3 IM 通道健康检测

- **通道列表**：Telegram、飞书、企业微信、钉钉、QQ 官方机器人、OneBot
- **状态**：在线 / 离线 / 未配置 / Key 缺失
- **独立检测**：IM 检测与 LLM 检测完全解耦，互不影响

### 4.4 开机自启

- 开关控制：启用/禁用开机自动启动
- Windows 下通过注册表实现
- macOS 下通过 LaunchAgent 实现
- 自启动时以后台模式运行（托盘常驻，不弹主窗口）

---

## 五、配置向导

配置向导共 9 个步骤，引导用户完成从零到运行的全部设置。已完成的步骤标记绿色勾号，支持自由跳转到已完成步骤。

### 步骤 1：开始

- 平台信息展示（操作系统、架构）
- 配置流程概览
- 开始按钮

### 步骤 2：工作区

- 创建或选择工作区
- 工作区存储 `.env` 配置、`llm_endpoints.json` 端点配置、`SOUL.md` 等身份文件
- 支持多工作区管理

### 步骤 3：Python 环境

- **内置 Python**：一键安装嵌入式 Python（推荐）
- **系统 Python**：检测系统已安装的 Python 路径
- 路径过长时悬浮显示完整路径

### 步骤 4：安装

- **创建虚拟环境**：一键在工作区创建 venv
- **安装 openakita**：从 PyPI 安装，支持：
  - 版本选择
  - 镜像源配置（清华、阿里等）
  - 安装选项（all / windows / browser 等 extras）
- **更新/卸载**

### 步骤 5：LLM 端点

- **端点列表**：展示已配置的所有 LLM 端点
- **添加/编辑**：弹窗表单配置：
  - 端点名称
  - API Base URL
  - API Key（密码模式，带眼睛图标切换）
  - 模型名称
  - 能力标签（text / vision / tools / thinking）
  - 超时设置
- **删除**：SVG 图标按钮
- 至少需要配置一个端点才能继续

### 步骤 6：IM 通道

- 支持 6 个通道：Telegram、飞书、企业微信、钉钉、QQ 官方机器人、OneBot
- 每个通道：
  - 启用/禁用开关
  - 凭证配置（Bot Token、App ID/Secret、Webhook 等）
  - 文档链接（点击跳转外部浏览器）
- 保存配置到 `.env`

### 步骤 7：工具与技能

- **MCP 服务**：Browser-Use 等 MCP 服务配置
- **桌面自动化**：启用/禁用
- **Whisper 语音识别**：模型选择
- **网络代理**：HTTP/HTTPS/SOCKS 代理配置
- **GitHub Token**：用于技能安装等
- **已安装技能列表**：折叠展示
- 每个配置项带感叹号提示，悬浮显示功能说明

### 步骤 8：Agent 与系统

- **Agent 名称**：自定义 AI 助手名称
- **人格预设**：下拉选择（8 种预设角色）
- **调度器**：定时任务开关
- **会话管理**：会话超时、并发等
- **日志级别**：DEBUG / INFO / WARNING / ERROR
- **记忆系统**：开关及配置

### 步骤 9：完成

- **配置检查**：一键验证所有配置是否完整
- **启动服务**：配置完成后直接启动
- **卸载与清理**：移除运行时数据

---

## 附录：快捷键与技巧

### 聊天快捷键

| 快捷键 | 功能 |
|--------|------|
| `Enter` | 发送消息 |
| `Shift+Enter` | 换行 |
| `Ctrl+V` | 粘贴图片 |
| `/` | 打开斜杠命令面板 |
| `上下键` | 命令面板中导航 |
| `Esc` | 关闭命令面板 |

### 使用技巧

1. **远程调试**：在终端运行 `openakita serve`，桌面端点击「连接服务」输入地址，Python 代码修改即时生效（无需重编译）
2. **端点故障**：如果某个端点连续失败 3 次会进入 1 小时冷却期，可在状态面板手动检测解除
3. **复杂命令**：Windows 环境下多行 Python 命令会自动写入临时文件执行，避免 cmd.exe 换行截断问题
4. **技能搜索**：技能市场搜索支持英文关键词，如 `react`、`deploy`、`testing`、`changelog`
5. **语言切换**：顶栏右侧地球图标按钮，支持中文/英文即时切换
6. **开机自启**：在状态页开启后，系统启动时自动以托盘模式常驻后台

---

## 技术架构

```
桌面终端 (Tauri 2 + React 18)
├── 前端 (TypeScript/React)
│   ├── App.tsx ─── 主框架、路由、状态管理
│   ├── ChatView.tsx ─── AI 聊天
│   ├── SkillManager.tsx ─── 技能管理
│   └── i18n/ ─── 国际化 (中/英)
├── Rust 后端 (Tauri Commands)
│   ├── 工作区管理
│   ├── Python 环境检测
│   ├── 服务启停控制
│   └── HTTP 代理 (绕过 CORS)
└── Python 后端 (FastAPI)
    ├── /api/chat ─── SSE 流式聊天
    ├── /api/health ─── 健康检测
    ├── /api/skills ─── 技能管理
    ├── /api/im ─── IM 通道
    ├── /api/config ─── 配置读写
    ├── /api/files ─── 文件服务
    └── /api/upload ─── 文件上传
```

---

*本文档基于 OpenAkita v1.10.2，最后更新：2026-02-12*