# 灵犀 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/)

## 截图

![image-20260605110600556](images/image-20260605110600556.png)

![image-20260605111350089](images/image-20260605111350089.png)

![image-20260605112225956](images/image-20260605112225956.png)

![image-20260605112232538](images/image-20260605112232538.png)

![image-20260605112249301](images/image-20260605112249301.png)

![image-20260605112258549](images/image-20260605112258549.png)

![image-20260605112345806](images/image-20260605112345806.png)

![image-20260605112357126](images/image-20260605112357126.png)

![image-20260605112404714](images/image-20260605112404714.png)

![image-20260605112415322](images/image-20260605112415322.png)

![image-20260605112422748](images/image-20260605112422748.png)

![image-20260605112429991](images/image-20260605112429991.png)

![image-20260605112440115](images/image-20260605112440115.png)

![image-20260605112449337](images/image-20260605112449337.png)

![image-20260605112457985](images/image-20260605112457985.png)

![image-20260605112506765](images/image-20260605112506765.png)

![image-20260605112514779](images/image-20260605112514779.png)

![image-20260605112523181](images/image-20260605112523181.png)

![image-20260605112532959](images/image-20260605112532959.png)

![image-20260605112540539](images/image-20260605112540539.png)

![image-20260605112546802](images/image-20260605112546802.png)

![image-20260605112557080](images/image-20260605112557080.png)



---

## 许可证

本项目采用 [BSL-1.1](./LICENSE) 许可证。