lingxi-ai/README.md

灵犀 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 绑定
• 普通管理员仅可管理自己的账户信息

维护命令：

# 清除登录 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 配置：

# 构建并启动
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。

本地开发

前置要求： Node.js ≥ 23

npm ci --ignore-scripts
npm rebuild node-pty
npm run dev

服务	地址
前端（Vite 热更新）	http://localhost:8649
BFF 后端	http://localhost:8647

连接 Docker 中间件、共用 ./data 目录时，可设置：

$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

构建生产包：

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。

---

系统架构

浏览器
  ↓
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

截图

---

许可证

本项目采用 BSL-1.1 许可证。