yi
245 lines
6.4 KiB
Markdown
245 lines
6.4 KiB
Markdown
# 灵犀 Studio
|
||
|
||
> 面向多模型 AI Agent 的一体化 Web 管理控制台。在一个界面中完成对话、渠道配置、用量分析、任务调度与系统运维。
|
||
|
||
---
|
||
|
||
## 产品简介
|
||
|
||
灵犀 Studio 是私有化部署的 AI 工作台，支持：
|
||
|
||
- 多会话实时对话与流式输出
|
||
- 多平台渠道统一接入与配置
|
||
- 按 Profile 隔离的配置、模型、文件与权限
|
||
- 用量统计、定时任务、技能与日志管理
|
||
- Web 终端与群聊协作
|
||
|
||
默认访问地址：
|
||
|
||
| 场景 | 地址 |
|
||
|------|------|
|
||
| 本地开发 | http://localhost:8649 |
|
||
| Docker 部署 | http://localhost:11000（可在 `.env` 中修改） |
|
||
|
||
默认登录：`admin` / `123456`（首次登录后请尽快修改）
|
||
|
||
---
|
||
|
||
## 核心功能
|
||
|
||
### AI 对话
|
||
|
||
- Socket.IO 实时流式聊天
|
||
- 多会话创建、重命名、删除与切换
|
||
- Markdown 渲染、代码高亮、工具调用详情
|
||
- 按 Profile 隔离的文件上传与下载
|
||
- `Ctrl+K` 搜索本地会话
|
||
- 多模型选择与 Token 用量展示
|
||
|
||
### 平台渠道
|
||
|
||
支持 Telegram、Discord、Slack、WhatsApp、Matrix、飞书、微信、企业微信等平台的统一配置，凭证与渠道行为分别写入环境变量与配置文件。
|
||
|
||
### 运维与管理
|
||
|
||
- **用量分析**：Token 统计、费用估算、模型分布与趋势图
|
||
- **定时任务**：Cron 表达式管理，支持立即触发
|
||
- **模型管理**：Provider 自动发现、OAuth 登录、默认模型切换
|
||
- **多 Profile**：创建、克隆、导入导出，按账号授权访问
|
||
- **文件浏览**：支持 local / Docker / SSH / Singularity 后端
|
||
- **群聊**：多 Agent 房间、@提及路由、消息持久化
|
||
- **技能与记忆**：浏览已安装技能，管理用户笔记与档案
|
||
- **日志**：按级别、文件与关键词过滤查看
|
||
- **Web 终端**：基于 xterm 的多会话终端
|
||
|
||
### 认证与账户
|
||
|
||
- Token 认证与用户名密码登录
|
||
- 超级管理员可管理用户与 Profile 绑定
|
||
- 普通管理员仅可管理自己的账户信息
|
||
|
||
维护命令：
|
||
|
||
```bash
|
||
# 清除登录 IP 锁定
|
||
hermes-web-ui clear-login-locks
|
||
|
||
# 清除锁定并重启服务
|
||
hermes-web-ui clear-login-locks --restart
|
||
|
||
# 重置默认管理员账户为 admin / 123456
|
||
hermes-web-ui reset-default-login
|
||
```
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### Docker 部署（推荐）
|
||
|
||
项目根目录已提供 `docker-compose.yml` 与 `.env` 配置：
|
||
|
||
```bash
|
||
# 构建并启动
|
||
docker compose up -d --build
|
||
|
||
# 查看日志
|
||
docker compose logs -f hermes-webui
|
||
```
|
||
|
||
常用配置（`.env`）：
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `PORT` | Web UI 端口，默认 `11000` |
|
||
| `HERMES_DATA_DIR` | 数据目录，默认 `./data` |
|
||
| `WEBUI_IMAGE` | 镜像名称，默认 `lingxi-web-ui:latest` |
|
||
|
||
数据持久化：
|
||
|
||
- Agent 运行时数据：`./data`
|
||
- Web UI 状态与认证：`./data/hermes-web-ui/`
|
||
- 认证 Token：`./data/hermes-web-ui/.token`
|
||
|
||
更详细的 Docker 说明见 [docs/docker.md](./docs/docker.md)。
|
||
|
||
### 本地开发
|
||
|
||
**前置要求：** Node.js ≥ 23
|
||
|
||
```bash
|
||
npm ci --ignore-scripts
|
||
npm rebuild node-pty
|
||
npm run dev
|
||
```
|
||
|
||
| 服务 | 地址 |
|
||
|------|------|
|
||
| 前端（Vite 热更新） | http://localhost:8649 |
|
||
| BFF 后端 | http://localhost:8647 |
|
||
|
||
连接 Docker 中间件、共用 `./data` 目录时，可设置：
|
||
|
||
```powershell
|
||
$env:HERMES_HOME = (Resolve-Path ".\data").Path
|
||
$env:HERMES_WEB_UI_HOME = (Resolve-Path ".\data\hermes-web-ui").Path
|
||
$env:HERMES_AGENT_ROOT = "<本机 hermes-agent 路径>"
|
||
npm run dev
|
||
```
|
||
|
||
构建生产包：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
---
|
||
|
||
## 环境变量
|
||
|
||
常用进程级配置：
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `PORT` | `8648` | Web UI 监听端口 |
|
||
| `BIND_HOST` | `0.0.0.0` | 绑定地址 |
|
||
| `HERMES_WEB_UI_HOME` | `~/.hermes-web-ui` | Web UI 数据目录 |
|
||
| `HERMES_HOME` | 平台默认 | Agent 运行时数据目录 |
|
||
| `HERMES_DATA_DIR` | `./hermes_data` | Docker 挂载的数据根目录 |
|
||
| `AUTH_TOKEN` | 自动生成 | 显式指定认证 Token |
|
||
| `CORS_ORIGINS` | `*` | 跨域配置 |
|
||
| `LOG_LEVEL` | `info` | 服务日志级别 |
|
||
| `HERMES_WEB_UI_BACKEND_PORT` | `8648` | 开发模式后端端口 |
|
||
| `HERMES_WEB_UI_FRONTEND_PORT` | `8649` | 开发模式前端端口 |
|
||
|
||
完整变量列表与 Bridge / Gateway 相关配置，请参阅项目内环境变量注释与 [DEVELOPMENT.md](./DEVELOPMENT.md)。
|
||
|
||
---
|
||
|
||
## 系统架构
|
||
|
||
```
|
||
浏览器
|
||
↓
|
||
BFF 服务（Koa + Socket.IO）
|
||
↓
|
||
Agent Bridge → Agent 运行时
|
||
↓
|
||
CLI / Profile 配置 / 渠道凭证
|
||
```
|
||
|
||
- **前端**：Vue 3 单页应用，按 `hermes/` 命名空间组织 Agent 相关模块
|
||
- **后端**：Koa BFF，负责聊天流、会话 CRUD、文件服务、配置代理与 WebSocket 终端
|
||
- **数据**：Web UI 使用本地 SQLite；Agent 状态与 Profile 配置独立存储
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 前端 | Vue 3、TypeScript、Vite、Naive UI、Pinia、Vue Router、vue-i18n |
|
||
| 后端 | Koa 2、Socket.IO、node-pty |
|
||
| 存储 | SQLite |
|
||
| 运行时 | Node.js ≥ 23 |
|
||
|
||
---
|
||
|
||
## 相关资源
|
||
|
||
- 源码库：[xinmi.cloud](https://xinmi.cloud/)
|
||
|
||
## 截图
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
本项目采用 [BSL-1.1](./LICENSE) 许可证。
|