AskaEth/Cyrene
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

refactor: 认证系统重构 + DevTools CLI 重写 + 文档全面更新

Browse Source 
- auth: Login 简化为管理员始终通过 .env 验证，GetProfile 修正 admin DB 查询
- devtools: .sh/.bat 同步重写为完整 CLI (start/stop/status/logs/build/db:*)
- docs: 新增 devtools.md，重写 Deploy.md (三种方式+Windows说明)，更新 README/gateway-api
- voice-service: DashScope 实时流式 STT 支持
- gateway: Phase 6 多模型配置 + 多端客户端管理 + WebSocket 增强

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
AskaEth
2026-05-24 14:55:47 +08:00
parent 83e94d9e97
commit 7eb5e984c2
18 changed files with 2405 additions and 677 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Deploy.md
+307 -125
View File
@@ -1,184 +1,366 @@
# Cyrene 部署指南
三种方式启动开发环境：**DevTools 一键**（推荐）、**手动逐服务**、**Docker Compose**。
---
## 环境要求
- Go 1.21+
- Node.js 20+
- Docker & Docker Compose
| 依赖 | 版本 | 用途 |
|------|------|------|
| Go | 1.21+ | 编译后端服务 |
| Node.js | 20+ (LTS) | 前端 / DevTools |
| Docker & Docker Compose | — | 数据库 & 基础设施 |
| Git Bash (Windows) | — | 运行 devtools.sh |
## 快速启动
### Windows 额外要求
### 1. 环境变量配置
- **Git for Windows**（提供 Git Bash 终端），安装时选择 "Git Bash Here"
- Go 和 Node.js 需加入系统 **PATH**（安装时勾选 "Add to PATH"）
- Docker Desktop 需启用 **WSL 2** 后端
Windows 提供两个启动脚本：
| 脚本 | 终端 | 适用场景 |
|------|------|----------|
| `devtools.bat` | CMD / PowerShell | 双击运行，无需 Git Bash |
| `devtools.sh` | Git Bash | 完整 CLI 体验（推荐） |
两者支持相同的命令集，日常开发推荐使用 Git Bash 运行 `./devtools.sh`；快速启动可直接双击 `devtools.bat`。
---
## 方式一：DevTools 一键启动（推荐）
### 1. 配置环境变量
```bash
cp backend/.env.example backend/.env
# 编辑 backend/.env，至少配置 LLM_API_KEY
# 编辑 backend/.env，至少配置:
# LLM_API_URL / LLM_API_KEY / LLM_MODEL
# ADMIN_USERNAME / ADMIN_PASSWORD
```
### 2. 启动基础设施
### 2. 启动数据库
```bash
./devtools.sh db:start
```
### 3. 编译并启动全部服务
```bash
./devtools.sh start --build
```
首次运行会编译全部后端 Go 服务（约 1-2 分钟），之后按依赖顺序启动全部 9 个服务，每步等待健康检查通过。
### 4. 打开控制台
| 地址 | 说明 |
|------|------|
| `http://localhost:9090` | DevTools 管理面板 |
| `http://localhost:5173` | 前端聊天界面 |
详细 CLI 用法见 [docs/api/devtools.md](docs/api/devtools.md)。
---
## 方式二：手动逐服务启动
适用于需要精细控制或调试单个服务的场景。
### 1. 配置 + 数据库
```bash
cp backend/.env.example backend/.env # 编辑配置
docker compose -f docker-compose.dev.db.yml up -d
```
此命令启动以下服务：
| 服务 | 端口 | 用途 |
|------|------|------|
| PostgreSQL + pgvector | 5432 | 关系数据库与向量检索 |
| Redis | 6379 | 缓存与会话 |
| Qdrant | 6333 (HTTP) / 6334 (gRPC) | 向量数据库 |
| MinIO | 9000 (API) / 9001 (Console) | 对象存储 |
| NATS | 4222 / 8222 (Monitoring) | 消息队列 |
### 3. 启动后端服务
推荐使用 DevTools 一键管理：
### 2. 按依赖顺序编译并启动
```bash
./devtools.sh start all # 编译并顺序启动所有后端 + 前端
./devtools.sh status # 查看各服务运行状态
./devtools.sh restart gateway # 单独重启某个服务
# 1) 记忆服务 (端口 8091)
cd backend/memory-service && go build -o main.exe ./cmd/main.go && ./main.exe
# 2) 工具引擎 (端口 8092)
cd backend/tool-engine && go build -o main.exe ./cmd/main.go && ./main.exe
# 3) 插件管理器 (端口 8094)
cd backend/plugin-manager && go build -o main.exe ./cmd/main.go && ./main.exe
# 4) IoT 调试服务 (端口 8083)
cd backend/iot-debug-service && go build -o main.exe ./cmd/main.go && ./main.exe
# 5) 语音服务 (端口 8093)
cd backend/voice-service && go build -o main.exe ./cmd/main.go && ./main.exe
# 6) AI-Core (端口 8081)
cd backend/ai-core && go build -o main.exe ./cmd/main.go && ./main.exe
# 7) 多平台桥接 (端口 8095)
cd backend/platform-bridge && go build -o main.exe ./cmd/main.go && ./main.exe
# 8) Gateway (端口 8080)
cd backend/gateway && go build -o main.exe ./cmd/main.go && ./main.exe
# 9) 前端 (端口 5173)
cd frontend/web && npm install && npx vite --host 0.0.0.0
```
或手动逐服务启动（每个在新终端中）：
> **注意**: Linux/macOS 下去掉 `.exe` 后缀。GOWORK=off 是必需的（项目使用 Go workspace）。
```bash
# 1) 记忆服务
cd backend/memory-service && go build -o main ./cmd/main.go && ./main
---
# 2) 工具引擎
cd backend/tool-engine && go build -o main ./cmd/main.go && ./main
## 方式三：Docker Compose
# 3) IoT 调试服务 (模拟智能家居设备)
cd backend/iot-debug-service && go build -o main ./cmd/main.go && ./main
# 4) 语音服务 (可选，需安装 whisper.cpp)
cd backend/voice-service && go build -o main ./cmd/main.go && ./main
# 5) AI-Core (LLM 推理与对话编排)
cd backend/ai-core && go build -o main ./cmd/main.go && ./main
# 6) Gateway (API 网关，最后启动)
cd backend/gateway && go build -o main ./cmd/main.go && ./main
```
### 4. 启动前端
```bash
cd frontend/web && npm install && npm run dev
```
访问 `http://localhost:5173`
### 5. 启动 DevTools 管理面板 (可选)
```bash
cd devtools && npm install && npm start
```
访问 `http://localhost:9090`
## 使用 Docker Compose 完整启动
### 开发环境
### 开发环境（基础设施 + 6 个后端服务）
```bash
docker compose -f docker-compose.dev.yml up -d
```
启动所有基础设施 + 6 个后端服务（AI-Core、Gateway、Memory Service、Tool Engine、Voice Service、IoT Debug Service），前端仍需本地启动。
启动服务：postgres, redis, qdrant, minio, nats, memory-service, tool-engine, voice-service, iot-debug-service, ai-core, gateway。前端需本地启动。
> plugin-manager 和 platform-bridge 目前不包含在 docker-compose 中，需本地启动。
### 生产环境
```bash
# 编辑 .env，配置生产密钥
docker compose up -d
```
额外包含 Caddy 反向代理（自动 TLS），前端静态文件由 Gateway 直接托管。
---
## 项目架构
```
Cyrene/
├── frontend/web/ # React 前端 (Vite + TypeScript + Tailwind + Zustand)
├── frontend/web/ # React 前端 (Vite + TypeScript)
├── backend/
│ ├── ai-core/ # AI 推理核心 (LLM 对话编排、人设注入、工具调用、后台思考)
│ ├── gateway/ # API 网关 (JWT 认证、路由、限流、WebSocket Hub)
│ ├── memory-service/ # 记忆服务 (CRUD、语义检索、LLM 提取)
│ ├── tool-engine/ # 工具引擎 (12+ 内置工具：计算器、HTTP、IoT、文件等)
│ ├── voice-service/ # 语音服务 (Edge-TTS + Whisper STT)
│ ├── iot-debug-service/ # IoT 调试服务 (8 个模拟设备：灯/空调/窗帘/传感器/门锁)
│ └── proto/ # Protobuf 定义 (预留)
├── devtools/ # 开发管理面板 (Express)
├── scripts/ # 辅助脚本
├── test/ # E2E 测试 (CDP/Chromium)
├── docs/ # 文档与调试记录
├── debug/ # 诊断脚本
├── docker-compose.dev.db.yml # 开发基础设施 (仅 DB)
├── docker-compose.dev.yml # 开发环境 (DB + 后端服务)
├── docker-compose.yml # 生产环境 (DB + 后端 + Caddy)
└── Caddyfile # 反向代理配置
│ ├── ai-core/ # AI 推理核心 (LLM 编排、人设注入、工具调用、后台思考)
│ ├── gateway/ # API 网关 (JWT、路由、限流、WebSocket Hub)
│ ├── memory-service/ # 记忆服务 (CRUD、语义检索、衰减、自动提取)
│ ├── tool-engine/ # 工具引擎 (13+ 内置工具：计算器/HTTP/IoT/文件等)
│ ├── voice-service/ # 语音服务 (DashScope STT + Edge-TTS)
│ ├── iot-debug-service/ # IoT 调试服务 (8 个模拟智能家居设备)
│ ├── plugin-manager/ # 插件管理器 (14 个内置插件)
│ ├── platform-bridge/ # 多平台桥接 (QQ / Telegram / Discord / Webhook)
│ └── pkg/ # 共享包 (logger)
├── devtools/ # DevTools 管理面板 (Express + WebSocket)
├── scripts/ # 辅助脚本 (migrate / tunnel / whisper-setup)
├── test/ # E2E 测试
├── docs/ # 文档
├── docker-compose.dev.db.yml # 开发基础设施
├── docker-compose.dev.yml # 开发环境 (DB + 后端)
├── docker-compose.yml # 生产环境 (+ Caddy)
└── devtools.sh # DevTools CLI
```
---
## 服务端口
| 端口 | 服务 |
| 端口 | 服务 | 对外 |
|------|------|------|
| 5173 | Frontend (Vite) | 是 |
| 8080 | Gateway API | **是**（唯一客户端入口） |
| 8081 | AI-Core | 否 |
| 8083 | IoT Debug | 否 |
| 8091 | Memory Service | 否 |
| 8092 | Tool Engine | 否 |
| 8093 | Voice Service | 否 |
| 8094 | Plugin Manager | 否 |
| 8095 | Platform Bridge | 否 |
| 9090 | DevTools | 是 |
| 5432 | PostgreSQL | 否 |
| 6379 | Redis | 否 |
| 6333 | Qdrant HTTP | 否 |
| 6334 | Qdrant gRPC | 否 |
| 9000 | MinIO S3 | 否 |
| 9001 | MinIO Console | 否 |
| 4222 | NATS | 否 |
| 8222 | NATS Monitoring | 否 |
> **客户端只需连接 Gateway (8080)**。所有后端服务不直接对外暴露。
---
## 核心环境变量
完整列表见 `backend/.env.example`。
### 必填
| 变量 | 说明 |
|------|------|
| 5173 | 前端 (Vite) |
| 8080 | Gateway API |
| 8081 | AI-Core API |
| 8083 | IoT 调试服务 |
| 8091 | 记忆服务 |
| 8092 | 工具引擎 |
| 8093 | 语音服务 |
| 9090 | DevTools 管理面板 |
| 5432 | PostgreSQL |
| 6379 | Redis |
| 6333 | Qdrant HTTP |
| 6334 | Qdrant gRPC |
| 9000 | MinIO S3 |
| 9001 | MinIO Console |
| 4222 | NATS |
| 8222 | NATS Monitoring |
| `LLM_API_URL` | LLM API 地址 |
| `LLM_API_KEY` | LLM API 密钥 |
| `LLM_MODEL` | 主模型 |
| `ADMIN_USERNAME` | 管理员用户名 |
| `ADMIN_PASSWORD` | 管理员密码 |
| `JWT_SECRET` | JWT 签名密钥 |
## 环境变量
参考 `backend/.env.example`：
### 推荐配置
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `ENV` | 运行环境 | `development` |
| `LLM_API_URL` | LLM API 地址 | `https://api.openai.com/v1` |
| `LLM_API_KEY` | LLM API 密钥 | — |
| `LLM_MODEL` | 主模型 | `gpt-4o` |
| `LLM_FALLBACK_MODEL` | 回退模型 | `gpt-4o-mini` |
| `POSTGRES_HOST` | PostgreSQL 主机 | `localhost` |
| `POSTGRES_PORT` | PostgreSQL 端口 | `5432` |
| `POSTGRES_USER` | PostgreSQL 用户 | `cyrene` |
| `POSTGRES_PASSWORD` | PostgreSQL 密码 | — |
| `POSTGRES_DB` | PostgreSQL 库名 | `cyrene_ai` |
| `REDIS_HOST` | Redis 主机 | `localhost` |
| `REDIS_PORT` | Redis 端口 | `6379` |
| `JWT_SECRET` | JWT 签名密钥 | — |
| `JWT_EXPIRY_HOURS` | JWT 过期时间 | `720` |
| `MINIO_ENDPOINT` | MinIO 地址 | `localhost:9000` |
| `MINIO_ACCESS_KEY` | MinIO Access Key | — |
| `MINIO_SECRET_KEY` | MinIO Secret Key | — |
| `VECTOR_DB_URL` | Qdrant 地址 | `http://localhost:6333` |
| `ADMIN_USERNAME` | 管理员账户 | `admin` |
| `ADMIN_PASSWORD` | 管理员密码 | — |
| `ADMIN_NICKNAME` | 昔涟对管理员的称呼 | `管理员` |
| `ENV` | 运行环境 | `development` |
| `REGISTRATION_ENABLED` | 开放注册 | `true` |
| `ENABLE_BACKGROUND_THINKING` | 后台思考 | `true` |
| `INTERNAL_SERVICE_TOKEN` | 内部服务通信 Token | — |
| `ADMIN_NICKNAME` | 管理员显示昵称 | `管理员` |
| `JWT_EXPIRY_HOURS` | JWT 有效期 | `720` |
| `ENABLE_BACKGROUND_THINKING` | 后台自主思考 | `true` |
| `THINK_OFFLINE_GAP_SEC` | 离线时思考间隔 | `600` |
| `ALLOWED_ORIGINS` | CORS 跨域白名单 | `http://localhost:5173,...` |
| `INTERNAL_SERVICE_TOKEN` | 服务间通信 Token | — |
| `WEBHOOK_API_KEY` | Webhook API Key | — |
| `IOT_SERVICE_URL` | IoT 服务地址 | `http://localhost:8083` |
### 语音 (可选)
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `DASHSCOPE_API_KEY` | 阿里云 DashScope API Key | — |
| `DASHSCOPE_STT_MODEL` | STT 模型 | `qwen3-asr-flash-...` |
| `TTS_PROVIDER` | TTS 引擎 | `edge-tts` |
| `TTS_VOICE` | TTS 语音 | `zh-CN-XiaoxiaoNeural` |
| `ASR_PROVIDER` | ASR 引擎 | `faster-whisper` |
| `ASR_MODEL` | ASR 模型 | `medium` |
| `ASR_PROVIDER` | 本地 ASR 引擎 | `faster-whisper` |
### 服务地址
| 变量 | 默认值 |
|------|--------|
| `MEMORY_SERVICE_URL` | `http://localhost:8091` |
| `TOOL_ENGINE_URL` | `http://localhost:8092` |
| `VOICE_SERVICE_URL` | `http://localhost:8093` |
| `IOT_SERVICE_URL` | `http://localhost:8083` |
### 数据库 / 存储
| 变量 | 默认值 |
|------|--------|
| `POSTGRES_HOST` / `POSTGRES_PORT` | `localhost` / `5432` |
| `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | `cyrene` / — / `cyrene_ai` |
| `REDIS_HOST` / `REDIS_PORT` | `localhost` / `6379` |
| `MINIO_ENDPOINT` | `localhost:9000` |
| `VECTOR_DB_URL` | `http://localhost:6333` |
---
## 数据库管理
```bash
# 通过 DevTools CLI
./devtools.sh db:start # 启动
./devtools.sh db:stop # 停止
./devtools.sh db:status # 状态检查
# 直接 Docker Compose
docker compose -f docker-compose.dev.db.yml up -d
docker compose -f docker-compose.dev.db.yml down
# 开发数据库容器名
docker exec -it cyrene_postgres psql -U cyrene -d cyrene_ai
```
---
## 平台迁移
从 Linux 迁移到 Windows 的详细指南见 [Migration.md](Migration.md)。
---
## 附：Windows 部署说明
### 启动脚本
| 脚本 | 终端 | 说明 |
|------|------|------|
| `devtools.bat` | CMD / PowerShell | 双击即可运行，无需 Git Bash |
| `devtools.sh` | Git Bash | 完整 CLI（推荐） |
```cmd
:: CMD 中直接运行
devtools.bat start --build
devtools.bat status
devtools.bat logs gateway
:: Git Bash 中运行
./devtools.sh start --build
./devtools.sh status
```
### 编译差异
Windows 下 Go 编译产物为 `main.exe` 而非 `main`。DevTools 已自动处理此差异，手动编译时需要注意：
```bash
# Windows (Git Bash / PowerShell)
go build -o main.exe ./cmd/main.go
./main.exe
# Linux / macOS
go build -o main ./cmd/main.go
./main
```
所有 Go 服务编译时必须设置 `GOWORK=off`：
```bash
GOWORK=off go build -o main.exe ./cmd/main.go
```
### 端口与进程管理
Windows 没有 `fuser` / `ss` 命令，等价操作为：
```bash
# 查看端口占用
netstat -ano | findstr ":8080"
# 杀进程 (PowerShell)
powershell -Command "Stop-Process -Id <PID> -Force"
# 或者直接用 DevTools CLI（跨平台兼容）
./devtools.sh status # 查看各服务端口状态
./devtools.sh stop # 停止 DevTools
```
### Docker Desktop
安装 Docker Desktop 后确保：
1. **Settings → General** → 勾选 "Use WSL 2 based engine"
2. **Settings → Resources → WSL Integration** → 启用对应发行版
3. 启动 Docker Desktop 后等待引擎就绪，再执行 `docker compose` 命令
若遇到`docker: error during connect`，说明 Docker Desktop 未运行，启动后重试。
### Node.js 版本
建议使用 **Node.js 20 LTS**。Node.js 22-24 存在 WebSocket 相关的已知问题（`UV_HANDLE_CLOSING` 崩溃），开发环境建议降级到 v20。
### Git Bash PATH
若 Git Bash 中找不到 `go` 或 `node`：
```bash
# 检查 PATH
echo $PATH
# 手动添加（添加到 ~/.bashrc 或 ~/.bash_profile）
export PATH="$PATH:/c/Program Files/Go/bin"
export PATH="$PATH:/c/Program Files/nodejs"
```
### 快速排错
| 症状 | 可能原因 | 解决 |
|------|----------|------|
| `go: command not found` | Go 未加入 PATH | 重启 Git Bash 或手动 `export PATH` |
| `Only one usage of each socket address` | 端口被占用 | `./devtools.sh stop` 或用 PowerShell 杀进程 |
| `docker: error during connect` | Docker Desktop 未启动 | 启动 Docker Desktop 等待就绪 |
| `GOWORK` 相关编译错误 | 未设置 GOWORK=off | `export GOWORK=off` 或在命令前加 `GOWORK=off` |
| `npm install` 卡住 | Windows 下 npm 网络问题 | 设置镜像 `npm config set registry https://registry.npmmirror.com` |
README.md
+158 -116
View File
@@ -1,87 +1,80 @@
# Cyrene - 昔涟
# Cyrene — 昔涟
昔涟 (本项目) 是一个开源的基于 LLM 平台的智能体，提供多人格对话、IoT 设备操控、记忆管理、自动化规则、知识库、语音交互等功能。
基于 LLM 的开源智能体平台：多人格对话、IoT 设备操控、记忆管理、自动化规则、知识库、语音交互、多平台桥接。
---
## 架构
```
┌─────────────────────────────────────────────────────────┐
│ Frontend (React + Vite) │
│ localhost:5173 │
└─────────────────────┬───────────────────────────────────┘
│ HTTP + WebSocket
┌─────────────────────▼───────────────────────────────────┐
│ Gateway (Go/Gin) │
│ localhost:8080 │
│ JWT Auth · Rate Limit · WS Hub · API 路由 │
└──┬────────┬────────┬────────┬────────┬────────┬────────┘
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐
│ AI │ │Memory│ │Tool │ │Voice │ │ IoT │ │ Infra │
│ Core │ │Svc │ │Engine│ │Svc │ │Debug │ │ │
│:8081 │ │:8091 │ │:8092 │ │:8093 │ │:8083 │ │ PG:5432 │
│ │ │ │ │ │ │ │ │ │ │ Redis │
│ LLM │ │CRUD │ │执行 │ │STT/ │ │模拟 │ │ :6379 │
│ 编排 │ │检索 │ │工具 │ │TTS │ │设备 │ │ Qdrant │
│ 人设 │ │ │ │调用 │ │ │ │管理 │ │ :6333 │
│ 工具 │ │ │ │ │ │ │ │ │ │ MinIO │
│ 后台 │ │ │ │ │ │ │ │ │ │ :9000 │
│ 思考 │ │ │ │ │ │ │ │ │ │ NATS │
└──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────────┘
┌──────────────────────────────────────────────────────────────────┐
│ Frontend (React + Vite) │
│ localhost:5173 │
└──────────────────────┬───────────────────────────────────────────┘
│ HTTP + WebSocket
┌──────────────────────▼───────────────────────────────────────────┐
│ Gateway (Go/Gin) │
│ localhost:8080 │
│ JWT Auth · Rate Limit · WS Hub · API 路由 │
└──┬───────┬────────┬────────┬────────┬────────┬────────┬─────────┘
│ │ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼ ▼
┌─────┐┌─────┐┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐┌──────────┐
│AI ││Mem- ││Tool ││Voice ││IoT ││Plugin││Plat- ││ Infra │
│Core ││ory ││Engine││Svc ││Debug ││Mgr ││form ││ │
│:8081││:8091││:8092 ││:8093 ││:8083 ││:8094 ││Bridge││ PG:5432 │
│ ││ ││ ││ ││ ││ ││:8095 ││ Redis │
│LLM ││CRUD ││工具 ││STT/ ││模拟 ││插件 ││QQ/ ││ :6379 │
│编排 ││检索 ││调用 ││TTS ││设备 ││托管 ││TG/ ││ Qdrant │
│人设 ││衰减 ││链 ││ ││管理 ││沙箱 ││DC/ ││ :6333 │
│后台 ││ ││ ││ ││ ││ ││Webhk ││ MinIO │
│思考 ││ ││ ││ ││ ││ ││ ││ :9000 │
└─────┘└─────┘└──────┘└──────┘└──────┘└──────┘└──────┘└──────────┘
```
**客户端只需连接 Gateway (8080)**。所有后端服务不直接对外暴露。
---
## 功能
- **多人格对话** — 可配置的角色扮演系统，带上下文构建和子会话路由
- **IoT 操控** — 模拟智能家居设备（灯、空调、窗帘、传感器、门锁），支持语音/文本控制
- **记忆管理** — LLM 驱动的长期记忆提取、存储和检索（PostgreSQL + pgvector）
- **自动化** — 规则引擎 + 场景执行（定时、条件触发、Webhook）
- **每日简报** — 定时生成当日汇总
- **多人格对话** — 可配置的角色扮演系统，支持子会话路由和上下文构建
- **IoT 操控** — 8 个模拟智能家居设备（灯/空调/窗帘/传感器/门锁），语音/文本控制
- **记忆管理** — LLM 驱动的长期记忆提取、存储、语义检索、衰减（pgvector）
- **自动化** — 规则引擎 + 场景执行（定时/条件触发/Webhook）
- **每日简报** — 定时生成当日汇总并推送
- **提醒** — 创建/管理定时提醒，到期 WebSocket 推送
- **知识库** — 文档管理 + 向量检索
- **文件管理** — 上传、下载、缩略图、图片 AI 分析
- **语音交互** — 浏览器端 STT（Web Speech API）+ TTS，服务端支持 Whisper
- **WebSocket** — 实时消息推送、IoT 状态广播、通知
- **PWA** — 可安装为桌面/移动应用，离线支持
- **后台思考** — AI 在对话间隙自主进行反思和记忆整理
- **Webhook 接入** — 支持 Discord、通用 Webhook 第三方平台接入
- **知识库** — 文档管理 + 向量语义检索
- **文件管理** — 上传/下载/缩略图/图片 AI 分析
- **语音交互** — 服务端 DashScope STT + Edge-TTS，支持实时流式语音
- **WebSocket** — 实时消息推送、IoT 状态广播、通知、流式响应
- **后台思考** — AI 在对话间隙自主反思和记忆整理
- **PWA** — 可安装为桌面/移动应用
- **多平台桥接** — QQ / Telegram / Discord / Webhook 第三方平台接入
- **插件系统** — 14 个内置插件（计算器/HTTP/加密/搜索/IoT 等），沙箱隔离
- **多模型配置** — 支持多 Provider / 多 Model / 路由规则
## 项目结构
```
Cyrene/
├── frontend/
│ ├── web/ # React 前端 (Vite + TypeScript + Tailwind)
│ └── packages/shared/ # 共享类型/工具
├── backend/
│ ├── ai-core/ # AI 推理核心 (LLM 编排、人设注入、工具调用、后台思考)
│ ├── gateway/ # API 网关 (JWT 认证、路由、限流、WebSocket Hub)
│ ├── memory-service/ # 记忆服务 (CRUD、检索、LLM 提取)
│ ├── tool-engine/ # 工具引擎 (计算器、HTTP、IoT、文件操作等)
│ ├── voice-service/ # 语音服务 (TTS/STT，基于 Edge-TTS + Whisper)
│ ├── iot-debug-service/# IoT 调试服务 (模拟智能家居设备)
│ └── proto/ # Protobuf 定义 (预留)
├── devtools/ # 开发管理面板 (Express，服务管理/日志/性能)
├── scripts/ # 辅助脚本 (Whisper 安装、SSH 隧道、数据迁移)
├── test/ # E2E 测试脚本 (CDP/Chromium)
├── docs/ # 项目文档与调试记录
├── debug/ # 诊断与缓存脚本
├── docker-compose.dev.db.yml # 开发环境基础设施 (仅 DB)
├── docker-compose.dev.yml # 开发环境一键启动
├── docker-compose.yml # 生产环境 (含 Caddy)
└── Caddyfile # 反向代理配置
```
---
## 快速开始
### 前提条件
- Go 1.21+
- Node.js 20+
- Node.js 20 LTS
- Docker & Docker Compose
- Git Bash（Windows 用户）
### 1. 启动基础设施
### 1. 配置环境变量
```bash
cp backend/.env.example backend/.env
# 编辑 backend/.env，至少配置:
# LLM_API_URL / LLM_API_KEY / LLM_MODEL
# ADMIN_USERNAME / ADMIN_PASSWORD
```
### 2. 启动数据库
```bash
docker compose -f docker-compose.dev.db.yml up -d
@@ -89,68 +82,96 @@ docker compose -f docker-compose.dev.db.yml up -d
启动 PostgreSQL (pgvector)、Redis、Qdrant、MinIO、NATS。
### 2. 启动后端服务
使用 DevTools 一键管理：
### 3. 启动全部服务
```bash
# Linux / macOS
./devtools.sh start all # 编译并启动所有后端 + 前端
./devtools.sh status # 查看服务状态
./devtools.sh logs ai-core # 查看 AI-Core 日志
# Linux / macOS (Git Bash)
./devtools.sh start --build
# Windows
devtools.bat # 启动 DevTools Web 面板
# 浏览器打开 http://localhost:9090，点击「一键启动」
# Windows CMD / PowerShell
devtools.bat start --build
```
或手动逐个启动：
按依赖顺序编译并启动全部 9 个服务：memory → tool-engine → plugin-manager → iot-debug → voice → ai-core → platform-bridge → gateway → frontend。
启动后访问：
| 地址 | 说明 |
|------|------|
| `http://localhost:5173` | 前端聊天界面 |
| `http://localhost:9090` | DevTools 管理面板 |
使用 `.env` 中配置的 `ADMIN_USERNAME` / `ADMIN_PASSWORD` 登录。
### 其他 CLI 命令
```bash
# 编译并运行各服务
cd backend/memory-service && go run ./cmd/main.go &
cd backend/tool-engine && go run ./cmd/main.go &
cd backend/iot-debug-service && go run ./cmd/main.go &
cd backend/voice-service && go run ./cmd/main.go &
cd backend/ai-core && go run ./cmd/main.go &
cd backend/gateway && go run ./cmd/main.go &
./devtools.sh status # 查看服务状态
./devtools.sh logs gateway # 查看 Gateway 日志
./devtools.sh build ai-core # 单独编译 AI-Core
./devtools.sh db:status # 检查数据库状态
./devtools.sh help # 完整帮助
```
### 3. 启动前端
详见 [docs/api/devtools.md](docs/api/devtools.md)。
```bash
cd frontend/web && npm install && npm run dev
---
## 项目结构
```
Cyrene/
├── frontend/
│ └── web/ # React 前端 (Vite + TypeScript + Tailwind)
├── backend/
│ ├── ai-core/ # AI 推理核心 (LLM 编排、人设注入、工具调用、后台思考)
│ ├── gateway/ # API 网关 (JWT 认证、路由、限流、WebSocket Hub)
│ ├── memory-service/ # 记忆服务 (CRUD、语义检索、衰减、LLM 提取)
│ ├── tool-engine/ # 工具引擎 (13+ 内置工具，支持工具调用链)
│ ├── voice-service/ # 语音服务 (DashScope STT + Edge-TTS)
│ ├── iot-debug-service/ # IoT 调试服务 (8 个模拟智能家居设备)
│ ├── plugin-manager/ # 插件管理器 (14 个内置插件、沙箱隔离)
│ ├── platform-bridge/ # 多平台桥接 (QQ / Telegram / Discord / Webhook)
│ └── pkg/ # 共享包 (logger)
├── devtools/ # DevTools 管理面板 (Express + WebSocket)
├── scripts/ # 辅助脚本 (migrate / tunnel / whisper-setup)
├── test/ # E2E 测试
├── docs/ # 文档与调试记录
│ └── api/ # API 文档
├── docker-compose.dev.db.yml # 开发基础设施 (仅 DB)
├── docker-compose.dev.yml # 开发环境一键启动
├── docker-compose.yml # 生产环境 (含 Caddy)
├── devtools.sh # DevTools CLI (Git Bash)
├── devtools.bat # DevTools CLI (CMD / PowerShell)
└── Caddyfile # 反向代理配置
```
访问 `http://localhost:5173`，默认管理员账户 `admin` / `cyrene-dev-admin`。
### 4. 配置环境变量
```bash
cp backend/.env.example backend/.env
# 编辑 backend/.env，填入 LLM API Key 等必要配置
```
---
## 服务端口
| 端口 | 服务 |
|------|------|
| 5173 | 前端 (Vite dev server) |
| 8080 | Gateway API |
| 8081 | AI-Core (LLM 推理) |
| 8083 | IoT 调试服务 |
| 8091 | 记忆服务 |
| 8092 | 工具引擎 |
| 8093 | 语音服务 |
| 9090 | DevTools 管理面板 |
| 5432 | PostgreSQL |
| 6379 | Redis |
| 6333 | Qdrant HTTP |
| 6334 | Qdrant gRPC |
| 9000 | MinIO S3 |
| 9001 | MinIO Console |
| 4222 | NATS |
| 8222 | NATS Monitoring |
| 端口 | 服务 | 对外 |
|------|------|------|
| 5173 | Frontend (Vite) | 是 |
| 8080 | Gateway API | **是**（唯一客户端入口） |
| 8081 | AI-Core | 否 |
| 8083 | IoT Debug | 否 |
| 8091 | Memory Service | 否 |
| 8092 | Tool Engine | 否 |
| 8093 | Voice Service | 否 |
| 8094 | Plugin Manager | 否 |
| 8095 | Platform Bridge | 否 |
| 9090 | DevTools | 是 |
| 5432 | PostgreSQL | 否 |
| 6379 | Redis | 否 |
| 6333 | Qdrant HTTP | 否 |
| 6334 | Qdrant gRPC | 否 |
| 9000 | MinIO S3 | 否 |
| 9001 | MinIO Console | 否 |
| 4222 | NATS | 否 |
| 8222 | NATS Monitoring | 否 |
---
## 技术栈
@@ -163,15 +184,36 @@ cp backend/.env.example backend/.env
| 向量库 | Qdrant |
| 对象存储 | MinIO |
| 消息队列 | NATS |
| 语音 | DashScope STT / Edge-TTS / Whisper.cpp |
| 反向代理 | Caddy (生产环境) |
| 语音 | Edge-TTS / Whisper.cpp |
---
## 文档
| 文档 | 说明 |
|------|------|
| [Deploy.md](Deploy.md) | 部署指南（含 Windows 说明） |
| [docs/api/gateway-api.md](docs/api/gateway-api.md) | 客户端 API 文档 |
| [docs/api/devtools.md](docs/api/devtools.md) | DevTools CLI + Web 控制台文档 |
| [docs/api/backend-services/](docs/api/backend-services/) | 后端服务 API 文档 |
| [docs/dev_must_read.md](docs/dev_must_read.md) | 开发者必读 |
---
## 部署
- 开发环境：`docker compose -f docker-compose.dev.yml up -d`
- 生产环境：`docker compose up -d`（含 Caddy 反向代理 + 自动 TLS）
```bash
# 开发环境（基础设施 + 后端服务）
docker compose -f docker-compose.dev.yml up -d
详见 [Deploy.md](Deploy.md) 和 [Migration.md](Migration.md)（Linux → Windows 迁移指南）。
# 生产环境（含 Caddy 反向代理 + 自动 TLS）
docker compose up -d
```
详见 [Deploy.md](Deploy.md)。
---
## License
backend/gateway/cmd/main.go
+1 -1
View File
@@ -70,7 +70,7 @@ func main() {
if err != nil {
logger.Printf("⚠ 管理员密码哈希生成失败: %v", err)
} else {
if _, err := store.CreateUser(s.DB(), cfg.AdminUsername, string(passwordHash), true); err != nil {
if _, err := store.CreateUser(s.DB(), cfg.AdminUsername, "管理员", string(passwordHash), true); err != nil {
logger.Printf("⚠ 创建默认管理员失败: %v", err)
} else {
logger.Printf("✅ 默认管理员用户已创建 (username: %s)", cfg.AdminUsername)
backend/gateway/internal/handler/auth_handler.go
+23 -44
View File
@@ -3,7 +3,6 @@ package handler
import (
"database/sql"
"fmt"
"github.com/yourname/cyrene-ai/pkg/logger"
"net/http"
"regexp"
"strings"
@@ -126,7 +125,9 @@ func (h *AuthHandler) Register(c *gin.Context) {
})
}
// Login 用户登录 (支持管理员账户和普通用户)
// Login 用户登录
// 管理员始终通过 .env 配置验证，不受数据库状态影响
// 普通用户通过数据库 bcrypt 密码哈希验证
func (h *AuthHandler) Login(c *gin.Context) {
var req struct {
Username string `json:"username" binding:"required"`
@@ -138,7 +139,6 @@ func (h *AuthHandler) Login(c *gin.Context) {
return
}
// 用户名格式校验：仅允许字母、数字、下划线，长度 3-32
if !usernameRegex.MatchString(req.Username) {
c.JSON(http.StatusBadRequest, gin.H{"error": "用户名格式无效"})
return
@@ -147,56 +147,36 @@ func (h *AuthHandler) Login(c *gin.Context) {
var userID string
var nickname string
// 尝试从 users 表查询用户
authenticated, err := h.verifyUserPassword(req.Username, req.Password)
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": "服务器内部错误"})
return
}
if authenticated {
// 用户存在于 users 表中且密码验证通过
if req.Username == h.cfg.AdminUsername {
userID = "admin"
} else {
userID = "user_" + req.Username
// 管理员：始终通过 .env 配置验证，不依赖数据库
if req.Username == h.cfg.AdminUsername && req.Password == h.cfg.AdminPassword {
userID = "admin"
nickname = h.cfg.AdminNickname
if nickname == "" {
nickname = "管理员"
}
// 获取用户昵称
// 数据库可用时从 DB 获取昵称（覆盖配置默认值）
if h.db != nil {
if u, err := store.GetUserByUsername(h.db, req.Username); err == nil && u != nil {
nickname = u.Nickname
}
}
} else if req.Username == h.cfg.AdminUsername && h.db != nil {
// 管理员用户尚未迁移到 users 表，尝试用配置中的密码验证
if req.Password != h.cfg.AdminPassword {
} else {
// 普通用户：数据库 bcrypt 验证
authenticated, err := h.verifyUserPassword(req.Username, req.Password)
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": "服务器内部错误"})
return
}
if !authenticated {
c.JSON(http.StatusUnauthorized, gin.H{"error": "用户名或密码错误"})
return
}
// 密码正确，迁移 admin 到 users 表
passwordHash, err := bcrypt.GenerateFromPassword([]byte(req.Password), bcrypt.DefaultCost)
if err != nil {
logger.Printf("⚠ 迁移管理员密码哈希失败: %v", err)
} else {
if _, err := store.CreateUser(h.db, req.Username, "管理员", string(passwordHash), true); err != nil {
logger.Printf("⚠ 迁移管理员到 users 表失败: %v", err)
} else {
logger.Println("✅ 管理员已迁移到 users 表")
userID = "user_" + req.Username
if h.db != nil {
if u, err := store.GetUserByUsername(h.db, req.Username); err == nil && u != nil {
nickname = u.Nickname
}
}
userID = "admin"
nickname = "管理员"
} else if req.Username == h.cfg.AdminUsername {
// 数据库不可用时的回退：使用配置中的管理员密码
if req.Password != h.cfg.AdminPassword {
c.JSON(http.StatusUnauthorized, gin.H{"error": "用户名或密码错误"})
return
}
userID = "admin"
nickname = "管理员"
} else {
c.JSON(http.StatusUnauthorized, gin.H{"error": "用户名或密码错误"})
return
}
token, err := h.cfg.GenerateToken(userID)
@@ -205,7 +185,6 @@ func (h *AuthHandler) Login(c *gin.Context) {
return
}
// 生成 refresh_token (长期有效)
refreshToken, err := h.cfg.GenerateRefreshToken(userID)
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": "生成刷新令牌失败"})
@@ -311,7 +290,7 @@ func (h *AuthHandler) GetProfile(c *gin.Context) {
var nickname string
if isAdmin {
username = "admin"
username = h.cfg.AdminUsername
} else if strings.HasPrefix(userID, "user_") {
username = strings.TrimPrefix(userID, "user_")
} else {
backend/gateway/internal/handler/chat_handler.go
+143 -8
View File
@@ -4,11 +4,12 @@ import (
"bufio"
"bytes"
"crypto/rand"
"encoding/base64"
"encoding/hex"
"encoding/json"
"fmt"
"github.com/yourname/cyrene-ai/pkg/logger"
"io"
"mime/multipart"
"net/http"
"strings"
"time"
@@ -19,6 +20,7 @@ import (
"github.com/yourname/cyrene-ai/gateway/internal/config"
"github.com/yourname/cyrene-ai/gateway/internal/store"
"github.com/yourname/cyrene-ai/gateway/internal/ws"
"github.com/yourname/cyrene-ai/pkg/logger"
)
// ChatHandler 聊天处理器
@@ -422,6 +424,8 @@ func (h *ChatHandler) streamResponse(client *ws.Client, mode string, reqBody []b
Type: "stream_end",
MessageID: msgID,
SessionID: client.SessionID,
Content: fullText,
Text: fullText,
Timestamp: time.Now().UnixMilli(),
})
@@ -458,14 +462,145 @@ func (h *ChatHandler) streamResponse(client *ws.Client, mode string, reqBody []b
// handleVoiceInput 处理语音输入
func (h *ChatHandler) handleVoiceInput(client *ws.Client, msg ws.ClientMessage) {
// MVP阶段：返回提示
response := ws.ServerMessage{
Type: "error",
MessageID: "msg_" + generateID(),
Error: "语音处理功能将在后续版本中启用",
Timestamp: time.Now().UnixMilli(),
audioB64 := msg.AudioData
if audioB64 == "" {
client.SendMessage(ws.ServerMessage{
Type: "error",
MessageID: "msg_" + generateID(),
Error: "语音数据为空",
Timestamp: time.Now().UnixMilli(),
})
return
}
client.SendMessage(response)
format := msg.Mode
if format == "" {
format = "webm"
}
// 在 goroutine 中处理转录，避免阻塞 ReadPump
go func() {
text, err := h.transcribeAudio(audioB64, format)
if err != nil {
logger.Printf("[voice] 转录失败: %v", err)
client.SendMessage(ws.ServerMessage{
Type: "voice_transcript",
MessageID: "msg_" + generateID(),
Error: fmt.Sprintf("语音识别失败: %v", err),
Timestamp: time.Now().UnixMilli(),
})
return
}
if text == "" {
client.SendMessage(ws.ServerMessage{
Type: "voice_transcript",
MessageID: "msg_" + generateID(),
Text: "",
Timestamp: time.Now().UnixMilli(),
})
return
}
// 发送转录结果给前端
client.SendMessage(ws.ServerMessage{
Type: "voice_transcript",
MessageID: "msg_" + generateID(),
Text: text,
Timestamp: time.Now().UnixMilli(),
})
// 将转录文本作为聊天消息处理
chatMsg := ws.ClientMessage{
Type: "message",
Content: text,
Mode: msg.Mode,
}
h.handleChatMessage(client, chatMsg)
}()
}
// transcribeAudio 将 base64 编码的音频发送到 voice-service 进行转录。
func (h *ChatHandler) transcribeAudio(audioB64 string, format string) (string, error) {
audioData, err := decodeBase64(audioB64)
if err != nil {
return "", fmt.Errorf("解码音频数据失败: %w", err)
}
// 构建 multipart form
var buf bytes.Buffer
mw := multipart.NewWriter(&buf)
ext := ".webm"
switch format {
case "wav", "wave":
ext = ".wav"
case "mp3", "mpeg":
ext = ".mp3"
case "ogg", "opus":
ext = ".ogg"
case "pcm":
ext = ".pcm"
}
fw, err := mw.CreateFormFile("audio", "recording"+ext)
if err != nil {
return "", fmt.Errorf("创建表单字段失败: %w", err)
}
if _, err := fw.Write(audioData); err != nil {
return "", fmt.Errorf("写入音频数据失败: %w", err)
}
mw.Close()
voiceURL := h.cfg.VoiceServiceURL
if voiceURL == "" {
voiceURL = "http://localhost:8093"
}
httpReq, err := http.NewRequest("POST", voiceURL+"/api/v1/transcribe", &buf)
if err != nil {
return "", fmt.Errorf("创建请求失败: %w", err)
}
httpReq.Header.Set("Content-Type", mw.FormDataContentType())
httpClient := &http.Client{Timeout: 60 * time.Second}
resp, err := httpClient.Do(httpReq)
if err != nil {
return "", fmt.Errorf("voice-service 调用失败: %w", err)
}
defer resp.Body.Close()
respBody, err := io.ReadAll(resp.Body)
if err != nil {
return "", fmt.Errorf("读取响应失败: %w", err)
}
var result struct {
Success bool `json:"success"`
Text string `json:"text"`
Error string `json:"error"`
}
if err := json.Unmarshal(respBody, &result); err != nil {
return "", fmt.Errorf("解析响应失败: %w", err)
}
if !result.Success {
if result.Error != "" {
return "", fmt.Errorf("%s", result.Error)
}
return "", fmt.Errorf("转录返回空结果")
}
return result.Text, nil
}
// decodeBase64 解码 base64 字符串（支持 Data URL 前缀）。
func decodeBase64(s string) ([]byte, error) {
// 移除 data:xxx;base64, 前缀
if idx := strings.Index(s, ","); idx != -1 {
s = s[idx+1:]
}
return base64.StdEncoding.DecodeString(s)
}
// handleHistoryRequest 处理历史消息请求
backend/gateway/internal/store/user_store.go
+16 -11
View File
@@ -12,6 +12,7 @@ import (
type User struct {
ID int `json:"id"`
Username string `json:"username"`
Nickname string `json:"nickname"`
PasswordHash string `json:"-"`
IsAdmin bool `json:"is_admin"`
CreatedAt time.Time `json:"created_at"`
@@ -23,6 +24,7 @@ func CreateUsersTable(db *sql.DB) error {
query := `CREATE TABLE IF NOT EXISTS users (
id SERIAL PRIMARY KEY,
username VARCHAR(255) UNIQUE NOT NULL,
nickname VARCHAR(255) DEFAULT '',
password_hash VARCHAR(255) NOT NULL,
is_admin BOOLEAN DEFAULT FALSE,
created_at TIMESTAMPTZ DEFAULT NOW(),
@@ -33,6 +35,9 @@ func CreateUsersTable(db *sql.DB) error {
return fmt.Errorf("创建 users 表失败: %w", err)
}
// 迁移：为已有 users 表添加 nickname 列
db.Exec(`ALTER TABLE users ADD COLUMN IF NOT EXISTS nickname VARCHAR(255) DEFAULT ''`)
// 创建索引
indexQueries := []string{
`CREATE INDEX IF NOT EXISTS idx_users_username ON users(username)`,
@@ -52,10 +57,10 @@ func CreateUsersTable(db *sql.DB) error {
func GetUserByUsername(db *sql.DB, username string) (*User, error) {
var u User
err := db.QueryRow(
`SELECT id, username, password_hash, is_admin, created_at, updated_at
`SELECT id, username, COALESCE(nickname, '') as nickname, password_hash, is_admin, created_at, updated_at
FROM users WHERE username = $1`,
username,
).Scan(&u.ID, &u.Username, &u.PasswordHash, &u.IsAdmin, &u.CreatedAt, &u.UpdatedAt)
).Scan(&u.ID, &u.Username, &u.Nickname, &u.PasswordHash, &u.IsAdmin, &u.CreatedAt, &u.UpdatedAt)
if err == sql.ErrNoRows {
return nil, nil
@@ -70,7 +75,7 @@ func GetUserByUsername(db *sql.DB, username string) (*User, error) {
// ListUsers 列出所有用户
func ListUsers(db *sql.DB) ([]User, error) {
rows, err := db.Query(
`SELECT id, username, password_hash, is_admin, created_at, updated_at
`SELECT id, username, COALESCE(nickname, '') as nickname, password_hash, is_admin, created_at, updated_at
FROM users ORDER BY id`,
)
if err != nil {
@@ -81,7 +86,7 @@ func ListUsers(db *sql.DB) ([]User, error) {
var users []User
for rows.Next() {
var u User
if err := rows.Scan(&u.ID, &u.Username, &u.PasswordHash, &u.IsAdmin, &u.CreatedAt, &u.UpdatedAt); err != nil {
if err := rows.Scan(&u.ID, &u.Username, &u.Nickname, &u.PasswordHash, &u.IsAdmin, &u.CreatedAt, &u.UpdatedAt); err != nil {
return nil, fmt.Errorf("扫描用户行失败: %w", err)
}
users = append(users, u)
@@ -109,16 +114,16 @@ func DeleteUser(db *sql.DB, userID int) error {
}
// CreateUser 创建新用户
func CreateUser(db *sql.DB, username, passwordHash string, isAdmin bool) (*User, error) {
func CreateUser(db *sql.DB, username, nickname, passwordHash string, isAdmin bool) (*User, error) {
now := time.Now()
var u User
err := db.QueryRow(
`INSERT INTO users (username, password_hash, is_admin, created_at, updated_at)
VALUES ($1, $2, $3, $4, $4)
ON CONFLICT (username) DO UPDATE SET updated_at = $4
RETURNING id, username, password_hash, is_admin, created_at, updated_at`,
username, passwordHash, isAdmin, now,
).Scan(&u.ID, &u.Username, &u.PasswordHash, &u.IsAdmin, &u.CreatedAt, &u.UpdatedAt)
`INSERT INTO users (username, nickname, password_hash, is_admin, created_at, updated_at)
VALUES ($1, $2, $3, $4, $5, $5)
ON CONFLICT (username) DO UPDATE SET nickname = $2, updated_at = $5
RETURNING id, username, COALESCE(nickname, '') as nickname, password_hash, is_admin, created_at, updated_at`,
username, nickname, passwordHash, isAdmin, now,
).Scan(&u.ID, &u.Username, &u.Nickname, &u.PasswordHash, &u.IsAdmin, &u.CreatedAt, &u.UpdatedAt)
if err != nil {
return nil, fmt.Errorf("创建用户失败: %w", err)
backend/gateway/internal/ws/client.go
+7 -2
View File
@@ -19,7 +19,7 @@ const (
pingPeriod = (pongWait * 9) / 10
// 最大消息大小
maxMessageSize = 65536
maxMessageSize = 2 * 1024 * 1024 // 2MB 支持语音消息
)
// Client WebSocket客户端
@@ -135,11 +135,16 @@ func (c *Client) SendMessage(msg ServerMessage) error {
return err
}
defer func() {
if r := recover(); r != nil {
logger.Printf("[WS] 发送消息时连接已关闭: type=%s user=%s", msg.Type, c.UserID)
}
}()
select {
case c.Send <- data:
return nil
default:
// 通道满：记录警告并返回错误（避免静默丢弃）
logger.Printf("[WS] 发送通道已满，丢弃消息: type=%s user=%s", msg.Type, c.UserID)
return nil
}
backend/voice-service/cmd/main.go
+1 -1
View File
@@ -28,7 +28,7 @@ func main() {
if sttSvc.IsAvailable() {
dashAvailable := cfg.DashScopeAPIKey != ""
if dashAvailable {
logger.Println("STT: DashScope Gummy (主) + Whisper (回退)")
logger.Printf("STT: DashScope 实时=%s, 离线=%s + Whisper (回退)", cfg.DashScopeSTTRealtime, cfg.DashScopeModel)
} else {
logger.Println("STT: Whisper 本地引擎")
}
backend/voice-service/internal/config/config.go
+34 -10
View File
@@ -11,20 +11,44 @@ type Config struct {
MaxAudioSize int64 // 字节
// DashScope STT 配置
DashScopeAPIKey string
DashScopeModel string
DashScopeAPIKey string
DashScopeModel string // 离线/非实时 ASR 模型
DashScopeSTTRealtime string // 实时 ASR 模型
}
// Load 从环境变量加载配置
// Load 从 models.json 和环境变量加载配置。
// models.json 优先级高于环境变量。
func Load() *Config {
// 从 models.json 加载 ASR 配置
modelsAPIKey, modelsOffline, modelsRealtime := LoadModelsConfig()
// .env / 环境变量作为回退
envAPIKey := getEnv("DASHSCOPE_API_KEY", "")
envModel := getEnv("DASHSCOPE_STT_MODEL", "qwen3-asr-flash-2026-02-10")
envRealtime := getEnv("DASHSCOPE_STT_REALTIME_MODEL", "qwen3-asr-flash-realtime")
apiKey := modelsAPIKey
if apiKey == "" {
apiKey = envAPIKey
}
offlineModel := modelsOffline
if offlineModel == "" {
offlineModel = envModel
}
realtimeModel := modelsRealtime
if realtimeModel == "" {
realtimeModel = envRealtime
}
return &Config{
Port: getEnv("PORT", "8093"),
WhisperBinary: getEnv("WHISPER_BINARY", "./whisper.cpp/main"),
WhisperModel: getEnv("WHISPER_MODEL", "./whisper.cpp/models/ggml-small.bin"),
WhisperLanguage: getEnv("WHISPER_LANGUAGE", "zh"),
MaxAudioSize: 10 * 1024 * 1024, // 10MB
DashScopeAPIKey: getEnv("DASHSCOPE_API_KEY", ""),
DashScopeModel: getEnv("DASHSCOPE_STT_MODEL", "gummy-chat-v1"),
Port: getEnv("PORT", "8093"),
WhisperBinary: getEnv("WHISPER_BINARY", "./whisper.cpp/main"),
WhisperModel: getEnv("WHISPER_MODEL", "./whisper.cpp/models/ggml-small.bin"),
WhisperLanguage: getEnv("WHISPER_LANGUAGE", "zh"),
MaxAudioSize: 10 * 1024 * 1024, // 10MB
DashScopeAPIKey: apiKey,
DashScopeModel: offlineModel,
DashScopeSTTRealtime: realtimeModel,
}
}
backend/voice-service/internal/config/models_config.go
+110
View File
@@ -0,0 +1,110 @@
package config
import (
"encoding/json"
"os"
"path/filepath"
)
// ModelsJSON 映射 models.json 文件结构（仅提取语音相关字段）。
type ModelsJSON struct {
Providers map[string]ModelsProvider `json:"providers"`
Models map[string]ModelsModel `json:"models"`
Routing map[string]ModelsRouting `json:"routing"`
}
type ModelsProvider struct {
Name string `json:"name"`
BaseURL string `json:"base_url"`
APIKey string `json:"api_key"`
}
type ModelsModel struct {
ID string `json:"id"`
Name string `json:"name"`
Provider string `json:"provider"`
}
type ModelsRouting struct {
Purpose string `json:"purpose"`
FallbackChain []string `json:"fallback_chain"`
}
// LoadModelsConfig 从 backend/models.json 加载模型配置。
// 返回 provider API key 和 ASR 模型名称。如果文件不存在则返回零值。
func LoadModelsConfig() (apiKey string, offlineModel string, realtimeModel string) {
// 尝试多个可能的路径
candidates := []string{
"models.json",
"../models.json",
"../../models.json",
filepath.Join("..", "models.json"),
}
var data []byte
var err error
for _, p := range candidates {
data, err = os.ReadFile(p)
if err == nil {
break
}
}
if data == nil {
return
}
var cfg ModelsJSON
if err := json.Unmarshal(data, &cfg); err != nil {
return
}
// 从 speech_recognition_offline 路由取离线模型
if r, ok := cfg.Routing["speech_recognition_offline"]; ok && len(r.FallbackChain) > 0 {
modelID := r.FallbackChain[0]
if m, ok := cfg.Models[modelID]; ok {
offlineModel = m.Name
if m.Name == "" {
offlineModel = m.ID
}
// 从 provider 取 API key
if p, ok := cfg.Providers[m.Provider]; ok && apiKey == "" {
apiKey = p.APIKey
}
}
}
// 从 speech_recognition 路由取实时模型
if r, ok := cfg.Routing["speech_recognition"]; ok && len(r.FallbackChain) > 0 {
modelID := r.FallbackChain[0]
if m, ok := cfg.Models[modelID]; ok {
realtimeModel = m.Name
if realtimeModel == "" {
realtimeModel = m.ID
}
// 从 provider 取 API key
if p, ok := cfg.Providers[m.Provider]; ok && apiKey == "" {
apiKey = p.APIKey
}
}
}
// 如果 routing 里没有，尝试从所有 models 中找带有 ASR tag 的模型
if offlineModel == "" {
for _, m := range cfg.Models {
if m.Provider == "dashscope" && m.Name != "" {
if offlineModel == "" {
offlineModel = m.Name
}
}
}
}
// 从 provider 取 API key (兜底)
if apiKey == "" {
if p, ok := cfg.Providers["dashscope"]; ok {
apiKey = p.APIKey
}
}
return
}
backend/voice-service/internal/handler/streaming_stt.go
+65 -25
View File
@@ -21,8 +21,8 @@ var upgrader = websocket.Upgrader{
}
// StreamingSTTHandler 处理实时语音识别 WebSocket 连接。
// 客户端通过 WebSocket 流式发送音频二进制帧，服务端逐帧转发到 DashScope，
// 将识别结果通过 WebSocket JSON 消息返回。
// 客户端通过 WebSocket 流式发送音频二进制帧，服务端通过一条持久的
// DashScope WebSocket 连接转发音频并持续返回识别结果。
type StreamingSTTHandler struct {
svc *service.STTService
}
@@ -46,6 +46,10 @@ func (h *StreamingSTTHandler) HandleStreamingSTT(w http.ResponseWriter, r *http.
if language == "" {
language = "zh"
}
format := r.URL.Query().Get("format")
if format == "" {
format = "pcm"
}
conn, err := upgrader.Upgrade(w, r, nil)
if err != nil {
@@ -54,12 +58,47 @@ func (h *StreamingSTTHandler) HandleStreamingSTT(w http.ResponseWriter, r *http.
}
defer conn.Close()
logger.Printf("[stream-stt] 客户端已连接")
logger.Printf("[stream-stt] 客户端已连接, format=%s, language=%s", format, language)
// 创建持久的 DashScope 流式会话
session, err := h.svc.StartStreaming(format, language)
if err != nil {
logger.Printf("[stream-stt] 创建 DashScope 会话失败: %v", err)
conn.WriteJSON(map[string]interface{}{
"type": "error",
"error": "启动语音识别失败: " + err.Error(),
})
return
}
defer session.Close()
var mu sync.Mutex
conn.SetWriteDeadline(time.Now().Add(60 * time.Second))
conn.SetReadDeadline(time.Now().Add(300 * time.Second)) // 5 分钟超时
// 读取音频帧并发送到 DashScope
// goroutine: 读取 DashScope 结果并推送到客户端
resultDone := make(chan struct{})
go func() {
defer close(resultDone)
for result := range session.Results() {
mu.Lock()
if result.Error != "" {
logger.Printf("[stream-stt] DashScope 错误: %s", result.Error)
conn.WriteJSON(map[string]interface{}{
"type": "error",
"error": result.Error,
})
} else if result.Text != "" {
conn.WriteJSON(map[string]interface{}{
"type": "result",
"text": result.Text,
"isFinal": result.IsFinal,
})
}
mu.Unlock()
}
}()
// 主循环: 读取客户端音频帧
for {
msgType, data, err := conn.ReadMessage()
if err != nil {
@@ -69,11 +108,13 @@ func (h *StreamingSTTHandler) HandleStreamingSTT(w http.ResponseWriter, r *http.
break
}
// 支持文本控制消息
// 文本控制消息
if msgType == websocket.TextMessage {
var ctrl map[string]interface{}
if json.Unmarshal(data, &ctrl) == nil {
if ctrl["action"] == "stop" {
action, _ := ctrl["action"].(string)
if action == "stop" {
logger.Printf("[stream-stt] 客户端请求停止")
mu.Lock()
conn.WriteJSON(map[string]interface{}{
"type": "done",
@@ -82,34 +123,33 @@ func (h *StreamingSTTHandler) HandleStreamingSTT(w http.ResponseWriter, r *http.
mu.Unlock()
break
}
// 支持动态切换语言
if lang, ok := ctrl["language"].(string); ok && lang != "" {
language = lang
logger.Printf("[stream-stt] 切换语言: %s", lang)
}
}
continue
}
// 二进制音频帧：进行识别
if msgType == websocket.BinaryMessage {
format := r.URL.Query().Get("format")
if format == "" {
format = "pcm"
}
text, err := h.svc.Transcribe(data, format, language)
mu.Lock()
if err != nil {
// 二进制音频帧: 发送到 DashScope
if msgType == websocket.BinaryMessage && len(data) > 0 {
if err := session.SendAudio(data); err != nil {
logger.Printf("[stream-stt] 发送音频帧失败: %v", err)
mu.Lock()
conn.WriteJSON(map[string]interface{}{
"type": "error",
"error": err.Error(),
})
} else if text != "" {
conn.WriteJSON(map[string]interface{}{
"type": "result",
"text": text,
"final": true,
"error": "发送音频失败: " + err.Error(),
})
mu.Unlock()
break
}
mu.Unlock()
}
}
// 等待结果推送完成
<-resultDone
logger.Printf("[stream-stt] 会话结束")
}
// RegisterStreamingRoutes 注册流式 STT 路由。
backend/voice-service/internal/service/dashscope_stt.go
+430 -183
View File
@@ -2,15 +2,21 @@ package service
import (
"context"
"encoding/base64"
"encoding/json"
"fmt"
"os"
"os/exec"
"strings"
"sync"
"time"
"github.com/gorilla/websocket"
)
// DashScopeSTT 使用阿里云百炼 Gummy 模型进行语音识别。
// WebSocket API: wss://dashscope.aliyuncs.com/api-ws/v1/inference
// DashScopeSTT 使用阿里云百炼 Qwen ASR 模型进行语音识别。
// 实时模型 (qwen3-asr-flash-realtime) 通过 WebSocket realtime 端点进行流式识别，
// 基于 session/VAD 协议（类似 OpenAI Realtime API）。
type DashScopeSTT struct {
apiKey string
model string
@@ -20,7 +26,7 @@ type DashScopeSTT struct {
// NewDashScopeSTT 创建 DashScope STT 客户端。
func NewDashScopeSTT(apiKey, model string) *DashScopeSTT {
if model == "" {
model = "gummy-chat-v1"
model = "qwen3-asr-flash-realtime"
}
return &DashScopeSTT{
apiKey: apiKey,
@@ -34,232 +40,402 @@ func (d *DashScopeSTT) IsAvailable() bool {
return d.apiKey != ""
}
// sttMessage 定义 STT WebSocket 协议消息格式。
type sttMessage struct {
Header sttHeader `json:"header"`
Payload sttPayload `json:"payload"`
// Model 返回模型名。
func (d *DashScopeSTT) Model() string { return d.model }
// --- Realtime 端点协议消息类型 ---
type rtClientMsg struct {
EventID string `json:"event_id,omitempty"`
Type string `json:"type"`
Session interface{} `json:"session,omitempty"`
Audio string `json:"audio,omitempty"`
}
type sttHeader struct {
Streaming string `json:"streaming"`
TaskID string `json:"task_id"`
Action string `json:"action"`
type rtServerMsg struct {
EventID string `json:"event_id,omitempty"`
Type string `json:"type"`
Session json.RawMessage `json:"session,omitempty"`
Error *rtError `json:"error,omitempty"`
// response.audio_transcript.delta
Delta string `json:"delta,omitempty"`
Response *struct {
Output []struct {
Transcript string `json:"transcript,omitempty"`
} `json:"output,omitempty"`
} `json:"response,omitempty"`
// transcription completed transcript
Transcript string `json:"transcript,omitempty"`
// conversation.item.input_audio_transcription.completed
Item *struct {
Content []struct {
Transcript string `json:"transcript,omitempty"`
} `json:"content,omitempty"`
} `json:"item,omitempty"`
}
type sttPayload struct {
Model string `json:"model"`
TaskGroup string `json:"task_group"`
Task string `json:"task"`
Function string `json:"function"`
Input map[string]interface{} `json:"input,omitempty"`
Parameters sttParameters `json:"parameters"`
Output map[string]interface{} `json:"output,omitempty"`
}
type sttParameters struct {
SampleRate int `json:"sample_rate"`
Format string `json:"format"`
TranscriptionEnabled bool `json:"transcription_enabled"`
TranslationEnabled bool `json:"translation_enabled"`
SourceLanguage string `json:"source_language,omitempty"`
MaxEndSilence int `json:"max_end_silence,omitempty"`
}
// sttServerMsg 服务端返回的消息格式。
type sttServerMsg struct {
Header sttServerHeader `json:"header"`
Payload sttServerPayload `json:"payload"`
}
type sttServerHeader struct {
TaskID string `json:"task_id"`
Event string `json:"event"`
}
type sttServerPayload struct {
Output map[string]interface{} `json:"output,omitempty"`
Usage map[string]interface{} `json:"usage,omitempty"`
Error sttError `json:"error,omitempty"`
}
type sttError struct {
type rtError struct {
Type string `json:"type"`
Code string `json:"code"`
Message string `json:"message"`
Param string `json:"param,omitempty"`
}
// Transcribe 将音频数据发送到 DashScope 进行识别，返回识别文本。
// 使用 realtime 端点，通过 Server VAD 自动检测语音并触发转录。
func (d *DashScopeSTT) Transcribe(ctx context.Context, audioData []byte, format string, language string) (string, error) {
if !d.IsAvailable() {
return "", fmt.Errorf("DashScope API Key 未配置")
}
dialer := websocket.Dialer{
HandshakeTimeout: 10 * time.Second,
url := fmt.Sprintf("wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=%s", d.model)
header := map[string][]string{
"Authorization": {"Bearer " + d.apiKey},
}
header := make(map[string][]string)
header["Authorization"] = []string{"Bearer " + d.apiKey}
conn, _, err := dialer.DialContext(ctx, "wss://dashscope.aliyuncs.com/api-ws/v1/inference", header)
dialer := websocket.Dialer{HandshakeTimeout: 10 * time.Second}
conn, _, err := dialer.DialContext(ctx, url, header)
if err != nil {
return "", fmt.Errorf("连接 DashScope STT 失败: %w", err)
}
defer conn.Close()
conn.SetReadDeadline(time.Now().Add(d.timeout))
// 1. session.created
conn.SetReadDeadline(time.Now().Add(10 * time.Second))
var msg rtServerMsg
if err := conn.ReadJSON(&msg); err != nil {
return "", fmt.Errorf("等待 session.created 失败: %w", err)
}
if msg.Type != "session.created" {
return "", fmt.Errorf("预期 session.created 但收到: %s", msg.Type)
}
taskID := fmt.Sprintf("cyrene-stt-%d", time.Now().UnixNano())
// 规范化音频格式
normFormat := normalizeSTTFormat(format)
// 2. session.update
if language == "" || language == "auto" {
language = "zh"
}
// 发送 run-task
startMsg := sttMessage{
Header: sttHeader{
Streaming: "duplex",
TaskID: taskID,
Action: "run-task",
},
Payload: sttPayload{
Model: d.model,
TaskGroup: "audio",
Task: "asr",
Function: "recognition",
Parameters: sttParameters{
SampleRate: 16000,
Format: normFormat,
TranscriptionEnabled: true,
TranslationEnabled: false,
SourceLanguage: language,
updateMsg := rtClientMsg{
Type: "session.update",
Session: map[string]interface{}{
"modalities": []string{"text"},
"input_audio_format": "pcm",
"sample_rate": 16000,
"input_audio_transcription": map[string]interface{}{
"language": language,
},
"turn_detection": map[string]interface{}{
"type": "server_vad",
},
},
}
if err := conn.WriteJSON(startMsg); err != nil {
return "", fmt.Errorf("发送 run-task 失败: %w", err)
conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
if err := conn.WriteJSON(updateMsg); err != nil {
return "", fmt.Errorf("发送 session.update 失败: %w", err)
}
// 等待 task-started
var textResult string
var mu sync.Mutex
started := make(chan struct{})
errc := make(chan error, 1)
done := make(chan struct{})
// 3. session.updated
conn.SetReadDeadline(time.Now().Add(10 * time.Second))
if err := conn.ReadJSON(&msg); err != nil {
return "", fmt.Errorf("等待 session.updated 失败: %w", err)
}
if msg.Type == "error" && msg.Error != nil {
return "", fmt.Errorf("session.update 失败: %s", msg.Error.Message)
}
// 4. 规范化音频格式并发送
pcmData, err := convertToPCM16(audioData, format)
if err != nil {
return "", fmt.Errorf("音频格式转换失败: %w", err)
}
chunkSize := 3200
for i := 0; i < len(pcmData); i += chunkSize {
end := i + chunkSize
if end > len(pcmData) {
end = len(pcmData)
}
chunkB64 := base64.StdEncoding.EncodeToString(pcmData[i:end])
audioMsg := rtClientMsg{
Type: "input_audio_buffer.append",
Audio: chunkB64,
}
conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
if err := conn.WriteJSON(audioMsg); err != nil {
return "", fmt.Errorf("发送音频数据失败: %w", err)
}
}
// 5. 等待转录结果
// 用 goroutine + channel 避免 gorilla/websocket 超时后重复读取 panic
type readResult struct {
msg rtServerMsg
err error
}
msgCh := make(chan readResult, 1)
readDone := make(chan struct{})
defer close(readDone)
go func() {
defer close(done)
startedClosed := false
for {
var msg sttServerMsg
if err := conn.ReadJSON(&msg); err != nil {
select {
case errc <- fmt.Errorf("读取响应失败: %w", err):
default:
}
select {
case <-readDone:
return
default:
}
var m rtServerMsg
err := conn.ReadJSON(&m)
select {
case msgCh <- readResult{m, err}:
case <-readDone:
return
}
switch msg.Header.Event {
case "task-started":
if !startedClosed {
close(started)
startedClosed = true
}
case "result-generated":
if out, ok := msg.Payload.Output["transcription"]; ok {
if transMap, ok := out.(map[string]interface{}); ok {
if text, ok := transMap["text"].(string); ok {
mu.Lock()
textResult = text
mu.Unlock()
}
}
}
case "task-finished":
return
case "task-failed":
errMsg := msg.Payload.Error.Message
if errMsg == "" {
errMsg = "未知错误"
}
select {
case errc <- fmt.Errorf("DashScope 识别失败: %s (code=%s)", errMsg, msg.Payload.Error.Code):
default:
}
if err != nil {
return
}
}
}()
// 等待 task-started 或错误
select {
case <-started:
case err := <-errc:
return "", err
case <-ctx.Done():
return "", ctx.Err()
}
var textResult string
silenceTimeout := 3 * time.Second
timer := time.NewTimer(60 * time.Second)
defer timer.Stop()
// 发送音频数据（分块发送，每块 ~10KB）
chunkSize := 10240
for i := 0; i < len(audioData); i += chunkSize {
end := i + chunkSize
if end > len(audioData) {
end = len(audioData)
}
conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
if err := conn.WriteMessage(websocket.BinaryMessage, audioData[i:end]); err != nil {
return "", fmt.Errorf("发送音频数据失败: %w", err)
}
}
for {
select {
case result := <-msgCh:
if result.err != nil {
if websocket.IsUnexpectedCloseError(result.err) {
return "", fmt.Errorf("连接异常关闭: %w", result.err)
}
return textResult, nil
}
// 发送 finish-task
finishMsg := sttMessage{
Header: sttHeader{
Streaming: "duplex",
TaskID: taskID,
Action: "finish-task",
},
}
if err := conn.WriteJSON(finishMsg); err != nil {
return "", fmt.Errorf("发送 finish-task 失败: %w", err)
}
msg := result.msg
// 等待完成
select {
case <-done:
mu.Lock()
text := textResult
mu.Unlock()
if text == "" {
return "", fmt.Errorf("未收到识别结果")
switch msg.Type {
case "conversation.item.input_audio_transcription.completed":
if msg.Transcript != "" {
if textResult != "" {
textResult += "\n"
}
textResult += msg.Transcript
}
if textResult == "" && msg.Item != nil {
for _, c := range msg.Item.Content {
if c.Transcript != "" {
textResult = c.Transcript
}
}
}
case "response.audio_transcript.delta":
if msg.Delta != "" {
textResult += msg.Delta
}
case "response.done":
if textResult == "" && msg.Response != nil {
for _, o := range msg.Response.Output {
if o.Transcript != "" {
textResult += o.Transcript
}
}
}
if textResult != "" {
return textResult, nil
}
case "error":
if msg.Error != nil {
return "", fmt.Errorf("DashScope 识别失败: %s", msg.Error.Message)
}
return "", fmt.Errorf("DashScope 返回未知错误")
}
if textResult != "" {
timer.Reset(silenceTimeout)
}
case <-timer.C:
return textResult, nil
}
return text, nil
case err := <-errc:
return "", err
case <-ctx.Done():
return "", ctx.Err()
}
}
// normalizeSTTFormat 将音频格式映射到 DashScope 支持的格式名。
func normalizeSTTFormat(format string) string {
switch format {
case "wav":
return "wav"
case "mp3", "mpeg":
return "mp3"
case "ogg", "opus":
return "ogg"
case "flac":
return "flac"
case "m4a", "aac", "mp4":
return "aac"
default:
return "pcm"
// --- 流式识别 (StreamingSession) ---
// StreamingSession 维护一个持久的 DashScope WebSocket 连接，用于实时语音识别。
type StreamingSession struct {
conn *websocket.Conn
results chan StreamingResult
done chan struct{}
mu sync.Mutex
closed bool
}
// StreamingResult 实时识别结果。
type StreamingResult struct {
Text string `json:"text"`
IsFinal bool `json:"is_final"`
Error string `json:"error,omitempty"`
}
// StartStreaming 建立 DashScope realtime WebSocket 连接并返回 StreamingSession。
func (d *DashScopeSTT) StartStreaming(ctx context.Context, format, language string) (*StreamingSession, error) {
if !d.IsAvailable() {
return nil, fmt.Errorf("DashScope API Key 未配置")
}
url := fmt.Sprintf("wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=%s", d.model)
header := map[string][]string{
"Authorization": {"Bearer " + d.apiKey},
}
dialer := websocket.Dialer{HandshakeTimeout: 10 * time.Second}
conn, _, err := dialer.DialContext(ctx, url, header)
if err != nil {
return nil, fmt.Errorf("连接 DashScope STT 失败: %w", err)
}
// 1. session.created
conn.SetReadDeadline(time.Now().Add(10 * time.Second))
var msg rtServerMsg
if err := conn.ReadJSON(&msg); err != nil {
conn.Close()
return nil, fmt.Errorf("等待 session.created 失败: %w", err)
}
if msg.Type != "session.created" {
conn.Close()
return nil, fmt.Errorf("预期 session.created 但收到: %s", msg.Type)
}
// 2. session.update
if language == "" || language == "auto" {
language = "zh"
}
updateMsg := rtClientMsg{
Type: "session.update",
Session: map[string]interface{}{
"modalities": []string{"text"},
"input_audio_format": "pcm",
"sample_rate": 16000,
"input_audio_transcription": map[string]interface{}{
"language": language,
},
"turn_detection": map[string]interface{}{
"type": "server_vad",
},
},
}
conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
if err := conn.WriteJSON(updateMsg); err != nil {
conn.Close()
return nil, fmt.Errorf("发送 session.update 失败: %w", err)
}
// 3. session.updated
conn.SetReadDeadline(time.Now().Add(10 * time.Second))
if err := conn.ReadJSON(&msg); err != nil {
conn.Close()
return nil, fmt.Errorf("等待 session.updated 失败: %w", err)
}
if msg.Type == "error" && msg.Error != nil {
conn.Close()
return nil, fmt.Errorf("session.update 失败: %s", msg.Error.Message)
}
session := &StreamingSession{
conn: conn,
results: make(chan StreamingResult, 64),
done: make(chan struct{}),
}
go session.readLoop()
return session, nil
}
// SendAudio 发送一帧 PCM 音频数据到 DashScope。
// data 必须是 16-bit little-endian PCM，16000Hz，mono。
func (s *StreamingSession) SendAudio(data []byte) error {
s.mu.Lock()
defer s.mu.Unlock()
if s.closed {
return fmt.Errorf("session 已关闭")
}
b64 := base64.StdEncoding.EncodeToString(data)
msg := rtClientMsg{
Type: "input_audio_buffer.append",
Audio: b64,
}
s.conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
return s.conn.WriteJSON(msg)
}
// Results 返回识别结果通道。
func (s *StreamingSession) Results() <-chan StreamingResult {
return s.results
}
// Close 结束会话并关闭 WebSocket 连接。
func (s *StreamingSession) Close() error {
s.mu.Lock()
if s.closed {
s.mu.Unlock()
return nil
}
s.closed = true
s.mu.Unlock()
finishMsg := rtClientMsg{Type: "session.finish"}
s.conn.SetWriteDeadline(time.Now().Add(5 * time.Second))
s.conn.WriteJSON(finishMsg)
select {
case <-s.done:
case <-time.After(5 * time.Second):
}
close(s.results)
return s.conn.Close()
}
// readLoop 读取 DashScope 服务端返回的消息并转换为 StreamingResult。
func (s *StreamingSession) readLoop() {
defer close(s.done)
for {
var msg rtServerMsg
if err := s.conn.ReadJSON(&msg); err != nil {
s.results <- StreamingResult{Error: fmt.Sprintf("读取响应失败: %v", err)}
return
}
switch msg.Type {
case "conversation.item.input_audio_transcription.completed":
if msg.Transcript != "" {
s.results <- StreamingResult{Text: msg.Transcript, IsFinal: true}
} else if msg.Item != nil {
for _, c := range msg.Item.Content {
if c.Transcript != "" {
s.results <- StreamingResult{Text: c.Transcript, IsFinal: true}
}
}
}
case "response.audio_transcript.delta":
s.results <- StreamingResult{Text: msg.Delta, IsFinal: false}
case "response.done":
// 全部完成
case "error":
errMsg := "未知错误"
if msg.Error != nil {
errMsg = msg.Error.Message
}
s.results <- StreamingResult{Error: fmt.Sprintf("DashScope 识别失败: %s", errMsg)}
return
case "response.created", "input_audio_buffer.committed",
"input_audio_buffer.speech_started", "input_audio_buffer.speech_stopped",
"conversation.item.created", "conversation.item.input_audio_transcription.text",
"response.audio_transcript.done":
// 内部事件，忽略
}
}
}
@@ -271,3 +447,74 @@ func (d *DashScopeSTT) GetStatus() map[string]interface{} {
"provider": "dashscope",
}
}
// normalizeSTTFormat 规范化音频格式字符串。
func normalizeSTTFormat(format string) string {
switch strings.ToLower(format) {
case "pcm", "wav", "mp3", "mpeg", "ogg", "opus", "flac", "m4a", "mp4", "aac", "webm":
return strings.ToLower(format)
default:
return format
}
}
// convertToPCM16 将音频数据转换为 16-bit PCM 16000Hz mono。
func convertToPCM16(data []byte, format string) ([]byte, error) {
normFormat := normalizeSTTFormat(format)
switch normFormat {
case "pcm":
return data, nil
case "wav":
if len(data) > 44 {
return data[44:], nil
}
return data, nil
default:
return transcodeToPCM(data, normFormat)
}
}
// transcodeToPCM 使用 ffmpeg 将音频数据转码为 PCM 16-bit 16000Hz mono。
func transcodeToPCM(data []byte, format string) ([]byte, error) {
inFile, err := os.CreateTemp(os.TempDir(), "cyrene-asr-in-*."+format)
if err != nil {
return nil, fmt.Errorf("创建输入临时文件失败: %w", err)
}
inPath := inFile.Name()
defer os.Remove(inPath)
if _, err := inFile.Write(data); err != nil {
inFile.Close()
return nil, fmt.Errorf("写入输入临时文件失败: %w", err)
}
inFile.Close()
outFile, err := os.CreateTemp(os.TempDir(), "cyrene-asr-out-*.pcm")
if err != nil {
return nil, fmt.Errorf("创建输出临时文件失败: %w", err)
}
outPath := outFile.Name()
outFile.Close()
defer os.Remove(outPath)
cmd := exec.Command("ffmpeg",
"-i", inPath,
"-ar", "16000",
"-ac", "1",
"-c:a", "pcm_s16le",
"-f", "s16le",
outPath,
"-y",
)
cmd.Stderr = nil
if err := cmd.Run(); err != nil {
return nil, fmt.Errorf("音频转码失败 (ffmpeg): %w", err)
}
outData, err := os.ReadFile(outPath)
if err != nil {
return nil, fmt.Errorf("读取转码结果失败: %w", err)
}
return outData, nil
}
backend/voice-service/internal/service/stt_service.go
+25 -4
View File
@@ -16,21 +16,27 @@ import (
var SupportedLanguages = []string{"zh", "en", "ja", "ko", "auto"}
// STTService 语音转文字服务。
// 优先使用 DashScope Gummy API，不可用时回退到本地 Whisper。
// 优先使用 DashScope API，不可用时回退到本地 Whisper。
type STTService struct {
whisperBinary string
whisperModel string
language string
dashscope *DashScopeSTT
dashscope *DashScopeSTT // 实时 ASR (qwen3-asr-flash-realtime)
}
// NewSTTService 创建 STT 服务。
func NewSTTService(cfg *config.Config) *STTService {
// 实时模型用于所有 WebSocket ASR 请求（支持 one-shot 和 streaming）
// 离线模型 (qwen3-asr-flash-2026-02-10) 是 HTTP REST API，暂未实现
model := cfg.DashScopeSTTRealtime
if model == "" {
model = cfg.DashScopeModel
}
return &STTService{
whisperBinary: cfg.WhisperBinary,
whisperModel: cfg.WhisperModel,
language: cfg.WhisperLanguage,
dashscope: NewDashScopeSTT(cfg.DashScopeAPIKey, cfg.DashScopeModel),
dashscope: NewDashScopeSTT(cfg.DashScopeAPIKey, model),
}
}
@@ -58,15 +64,30 @@ func (s *STTService) Transcribe(audioData []byte, format string, language string
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
text, err := s.dashscope.Transcribe(ctx, audioData, format, language)
if err == nil && text != "" {
if err == nil {
return text, nil
}
// DashScope 失败，返回具体错误而不是回退到 Whisper
return "", fmt.Errorf("语音识别失败: %w", err)
}
// 回退到本地 Whisper
return s.transcribeWhisper(audioData, format, language)
}
// StartStreaming 创建持久的流式语音识别会话。
func (s *STTService) StartStreaming(format, language string) (*StreamingSession, error) {
if !s.dashscope.IsAvailable() {
return nil, fmt.Errorf("流式识别需要 DashScope，请配置 DASHSCOPE_API_KEY")
}
if language == "" {
language = s.language
}
ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
defer cancel()
return s.dashscope.StartStreaming(ctx, format, language)
}
// transcribeWhisper 使用本地 Whisper 引擎转录。
func (s *STTService) transcribeWhisper(audioData []byte, format string, language string) (string, error) {
if _, err := os.Stat(s.whisperBinary); err != nil {
devtools.bat
+248 -39
View File
@@ -1,91 +1,300 @@
@echo off
setlocal enabledelayedexpansion
:: ========================================
:: Cyrene DevTools Launcher (Windows)
:: Cyrene DevTools CLI (Windows CMD)
:: 用法: devtools.bat [命令] [选项]
:: ========================================
set "SCRIPT_DIR=%~dp0"
set "DEVTOOLS_DIR=%SCRIPT_DIR%devtools"
set "ROOT=%SCRIPT_DIR%"
if "%DEVTOOLS_PORT%"=="" (set PORT=9090) else (set PORT=%DEVTOOLS_PORT%)
set "LOG_DIR=%SCRIPT_DIR%logs"
set "LOG_DIR=%DEVTOOLS_DIR%\logs"
set "LOG_FILE=%LOG_DIR%\sh.log"
set "DB_COMPOSE_FILE=%ROOT%docker-compose.dev.db.yml"
echo ==========================================
echo Cyrene DevTools
echo ==========================================
:: 解析第一个参数作为命令
set CMD=%1
if "%CMD%"=="" set CMD=start
if "%CMD%"=="help" goto :help
if "%CMD%"=="--help" goto :help
if "%CMD%"=="/?" goto :help
if "%CMD%"=="start" goto :start
if "%CMD%"=="stop" goto :stop
if "%CMD%"=="status" goto :status
if "%CMD%"=="logs" goto :logs
if "%CMD%"=="build" goto :build
if "%CMD%"=="db:start" goto :db_start
if "%CMD%"=="db:stop" goto :db_stop
if "%CMD%"=="db:status" goto :db_status
cd /d "%DEVTOOLS_DIR%"
echo [ERROR] Unknown command: %CMD%
echo.
goto :help
:: Node.js check
:: ==========================================
:help
echo Cyrene DevTools - Development Management Tool
echo.
echo Usage: devtools.bat [command] [options]
echo.
echo Commands:
echo start Start DevTools console (default)
echo start --build Build all services before start
echo start --fresh Force restart all services before start
echo stop Stop DevTools console
echo status Show all service status
echo logs [service] View service logs (default: last 20 lines)
echo build [service] Build service(s) (omit to build all)
echo db:start Start database containers
echo db:stop Stop database containers
echo db:status Check database connection status
echo help Show this help
echo.
echo Options:
echo --build Build all backend services before start
echo --fresh Force restart all services before start
echo.
echo Examples:
echo devtools.bat Quick start
echo devtools.bat start --build Build and start
echo devtools.bat start --fresh Fresh restart
echo devtools.bat logs gateway View Gateway log
echo devtools.bat build ai-core Build AI-Core only
echo devtools.bat db:status Check database
echo.
echo Web console: http://localhost:%PORT%
exit /b 0
:: ==========================================
:check_node
where node >nul 2>&1
if %ERRORLEVEL%==0 (
set NODE_CMD=node
) else if exist "C:\Program Files\nodejs\node.exe" (
set "NODE_CMD=C:\Program Files\nodejs\node.exe"
) else (
echo [ERROR] Node.js not found.
pause
exit /b 1
goto :eof
)
for /f "tokens=*" %%i in ('!NODE_CMD! --version') do echo Node.js: %%i
if exist "C:\Program Files\nodejs\node.exe" (
set "NODE_CMD=C:\Program Files\nodejs\node.exe"
goto :eof
)
echo [ERROR] Node.js not found. Install Node.js 20+ and add to PATH.
pause
exit /b 1
:: Check and free port
set PID_FOUND=0
:: ==========================================
:start
echo.
echo ==========================================
echo Cyrene DevTools
echo ==========================================
call :check_node
for /f "tokens=*" %%i in ('!NODE_CMD! --version') do echo Node.js: %%i
echo Port: %PORT%
:: Check for --build / --fresh
set DO_BUILD=0
set DO_FRESH=0
for %%a in (%*) do (
if "%%a"=="--build" set DO_BUILD=1
if "%%a"=="--fresh" set DO_FRESH=1
)
:: Build if requested
if %DO_BUILD%==1 (
echo.
echo [INFO] Building all backend services...
call :build_all
)
:: Fresh restart if requested
if %DO_FRESH%==1 (
echo.
echo [INFO] Force restarting all services...
curl -s -X POST "http://localhost:%PORT%/api/services/start-all-fresh" >nul 2>&1
)
:: Check if already running
curl -s -o nul "http://localhost:%PORT%/api/health" 2>nul
if %ERRORLEVEL%==0 (
echo.
echo [OK] DevTools already running: http://localhost:%PORT%
echo API: http://localhost:%PORT%/api/health
exit /b 0
)
:: Free port
for /f "tokens=5" %%a in ('netstat -ano ^| findstr /R ":%PORT% " ^| findstr "LISTENING"') do (
set PID_FOUND=1
echo [WARN] Port %PORT% in use by PID %%a, releasing...
taskkill /PID %%a /F >nul 2>&1
timeout /t 1 /nobreak >nul
echo [OK] Port released
)
if %PID_FOUND%==1 timeout /t 1 /nobreak >nul
:: Install dependencies if needed
cd /d "%DEVTOOLS_DIR%"
:: Install dependencies
if not exist "node_modules\" (
echo [INFO] Installing dependencies...
call npm install
call npm install --silent
)
:: Ensure log directory exists
:: Ensure log directory
if not exist "%LOG_DIR%" mkdir "%LOG_DIR%"
echo.
echo [INFO] Starting DevTools on port %PORT%
echo Web UI: http://localhost:%PORT%
echo API: http://localhost:%PORT%/api/health
echo Web UI: http://localhost:%PORT%
echo API: http://localhost:%PORT%/api/health
echo WebSocket: ws://localhost:%PORT%/ws
echo.
:: Launch DevTools in background
start "Cyrene-DevTools" /B !NODE_CMD! src\index.js 1>>"%LOG_FILE%" 2>&1
:: Health check (up to 30s)
echo [INFO] Waiting for DevTools to be ready...
set MAX_WAIT=30
set WAITED=0
:health_loop
if %WAITED% geq %MAX_WAIT% goto :timeout
powershell -Command "try { (Invoke-WebRequest 'http://localhost:%PORT%/api/health' -TimeoutSec 2 -UseBasicParsing).StatusCode -eq 200 } catch { $false }" | findstr "True" >nul 2>&1
if %ERRORLEVEL%==0 (
echo.
echo [OK] DevTools is ready.
echo Log: %LOG_FILE%
echo ==========================================
echo DevTools is ready!
echo Console: http://localhost:%PORT%
echo Log: %LOG_FILE%
echo ==========================================
echo.
exit /b 0
)
timeout /t 1 /nobreak >nul
set /a WAITED+=1
goto :health_loop
:timeout
if exist "%LOG_FILE%" (
echo.
echo [WARN] Still starting - waited %MAX_WAIT%s
echo Check http://localhost:%PORT%/api/health
echo Log: %LOG_FILE%
) else (
echo.
echo [ERROR] Startup failed, see: %LOG_FILE%
pause
echo.
echo [WARN] Still starting - waited %MAX_WAIT%s
echo Check http://localhost:%PORT%/api/health
exit /b 0
:: ==========================================
:stop
for /f "tokens=5" %%a in ('netstat -ano ^| findstr /R ":%PORT% " ^| findstr "LISTENING"') do (
echo [INFO] Stopping DevTools (PID: %%a)...
taskkill /PID %%a /F >nul 2>&1
echo [OK] DevTools stopped
exit /b 0
)
echo [INFO] DevTools is not running
exit /b 0
:: ==========================================
:status
curl -s -o nul "http://localhost:%PORT%/api/health" 2>nul
if %ERRORLEVEL% neq 0 (
echo [ERROR] DevTools is offline
exit /b 1
)
endlocal
echo [OK] DevTools online
echo.
echo Service Status:
curl -s "http://localhost:%PORT%/api/services" 2>nul | !NODE_CMD! -e "const d=require('fs').readFileSync(0,'utf-8');const s=JSON.parse(d);for(const[k,v]of Object.entries(s)){const icon=v.status==='running'?'+':' ';const pid=v.pid?' (PID:'+v.pid+')':'';const upt=v.uptime?' uptime:'+Math.round(v.uptime/1000)+'s':'';console.log(' ['+icon+'] '+v.name.padEnd(18)+v.status+pid+upt);}" 2>nul
echo.
echo Database:
powershell -Command "$tcp=New-Object Net.Sockets.TcpClient;try{$tcp.Connect('127.0.0.1',5432);' [OK] PostgreSQL online'}catch{' [--] PostgreSQL offline'};$tcp.Dispose()" 2>nul
exit /b 0
:: ==========================================
:logs
set SVC_ID=%2
set LINES=%3
if "%SVC_ID%"=="" (
echo Usage: devtools.bat logs ^<service-id^> [lines]
echo Available: gateway, ai-core, memory-service, tool-engine, voice-service, iot-debug-service, plugin-manager, platform-bridge, frontend
exit /b 1
)
if "%LINES%"=="" set LINES=20
set "LOG_PATH=%LOG_DIR%\%SVC_ID%.log"
if not exist "%LOG_PATH%" (
echo [WARN] Log file not found: %LOG_PATH%
exit /b 1
)
echo === %SVC_ID% log (last %LINES% lines) ===
powershell -Command "Get-Content '%LOG_PATH%' -Tail %LINES%" 2>nul
exit /b 0
:: ==========================================
:build
call :check_node
set SVC_ID=%2
if not "%SVC_ID%"=="" goto :build_one
:build_all
echo [INFO] Building all backend services...
set SERVICES=memory-service:backend/memory-service tool-engine:backend/tool-engine iot-debug-service:backend/iot-debug-service voice-service:backend/voice-service ai-core:backend/ai-core plugin-manager:backend/plugin-manager platform-bridge:backend/platform-bridge gateway:backend/gateway
for %%s in (%SERVICES%) do (
for /f "tokens=1,2 delims=:" %%a in ("%%s") do (
if exist "%ROOT%%%b" (
echo Building %%a...
cd /d "%ROOT%%%b"
set GOWORK=off
go build -o main.exe .\cmd\main.go 2>&1
if !ERRORLEVEL!==0 (
echo [OK] %%a
) else (
echo [FAIL] %%a
)
)
)
)
cd /d "%ROOT%"
echo [OK] Build complete
exit /b 0
:build_one
for %%s in (memory-service:backend/memory-service tool-engine:backend/tool-engine iot-debug-service:backend/iot-debug-service voice-service:backend/voice-service ai-core:backend/ai-core plugin-manager:backend/plugin-manager platform-bridge:backend/platform-bridge gateway:backend/gateway) do (
for /f "tokens=1,2 delims=:" %%a in ("%%s") do (
if "%%a"=="%SVC_ID%" (
if not exist "%ROOT%%%b" (
echo [ERROR] Service directory not found: %%b
exit /b 1
)
echo [INFO] Building %%a...
cd /d "%ROOT%%%b"
set GOWORK=off
go build -o main.exe .\cmd\main.go 2>&1
if !ERRORLEVEL!==0 (echo [OK] %%a) else (echo [FAIL] %%a)
cd /d "%ROOT%"
exit /b !ERRORLEVEL!
)
)
)
echo [ERROR] Unknown service: %SVC_ID%
echo Available: memory-service, tool-engine, iot-debug-service, voice-service, ai-core, plugin-manager, platform-bridge, gateway
exit /b 1
:: ==========================================
:db_start
echo [INFO] Starting database containers...
if not exist "%DB_COMPOSE_FILE%" (
echo [ERROR] File not found: %DB_COMPOSE_FILE%
exit /b 1
)
docker compose -f "%DB_COMPOSE_FILE%" up -d
echo [OK] Database containers started
exit /b 0
:: ==========================================
:db_stop
echo [INFO] Stopping database containers...
if not exist "%DB_COMPOSE_FILE%" (
echo [ERROR] File not found: %DB_COMPOSE_FILE%
exit /b 1
)
docker compose -f "%DB_COMPOSE_FILE%" down
echo [OK] Database containers stopped
exit /b 0
:: ==========================================
:db_status
powershell -Command "$tcp=New-Object Net.Sockets.TcpClient;try{$tcp.Connect('127.0.0.1',5432);Write-Host ' [OK] PostgreSQL online'}catch{Write-Host ' [--] PostgreSQL offline'};$tcp.Dispose()" 2>nul
exit /b 0
devtools.sh
+447 -90
View File
@@ -1,110 +1,467 @@
#!/bin/bash
# ========================================
# Cyrene DevTools 启动脚本
# 自动处理端口冲突、依赖安装和服务管理
# 管理开发环境: 数据库 / 服务编译 / DevTools 控制台
# ========================================
set -e
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
DEVTOOLS_DIR="$SCRIPT_DIR/devtools"
ROOT="$SCRIPT_DIR"
PORT="${DEVTOOLS_PORT:-9090}"
LOG_DIR="$SCRIPT_DIR/logs"
LOG_DIR="$DEVTOOLS_DIR/logs"
LOG_FILE="$LOG_DIR/sh.log"
# 颜色输出
# 颜色
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
CYAN='\033[0;36m'
NC='\033[0m' # No Color
BOLD='\033[1m'
NC='\033[0m'
echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo -e "${CYAN} 🛠️ Cyrene DevTools${NC}"
echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
# ========== 平台检测 ==========
IS_WIN=false
case "$(uname -s)" in
MINGW*|MSYS*|CYGWIN*) IS_WIN=true ;;
esac
# 切换到 devtools 目录
cd "$DEVTOOLS_DIR"
# ========== 帮助 ==========
show_help() {
echo -e "${CYAN}Cyrene DevTools${NC} — 开发环境管理工具"
echo ""
echo -e "${BOLD}用法:${NC} ./devtools.sh [命令] [选项]"
echo ""
echo -e "${BOLD}命令:${NC}"
echo " (无参数) 启动 DevTools 控制台 (默认)"
echo " start 启动 DevTools 控制台"
echo " start --fresh 强制重启全部后端服务后启动"
echo " start --build 编译全部服务后启动"
echo " stop 停止 DevTools 控制台"
echo " status 查看所有服务状态"
echo " logs [服务ID] 查看服务日志 (默认显示最近 20 行)"
echo " build [服务ID] 编译服务 (不指定则编译全部)"
echo " db:start 启动数据库容器 (Docker Compose)"
echo " db:stop 停止数据库容器"
echo " db:status 检查数据库连接状态"
echo " help 显示此帮助"
echo ""
echo -e "${BOLD}选项:${NC}"
echo " --port, -p <端口> 指定 DevTools 端口 (默认: 9090)"
echo " --fresh 启动前强制重启全部后端服务"
echo " --build 启动前编译全部服务"
echo ""
echo -e "${BOLD}示例:${NC}"
echo " ./devtools.sh # 快速启动"
echo " ./devtools.sh start --build # 编译后启动"
echo " ./devtools.sh start --fresh # 全新重启"
echo " ./devtools.sh logs gateway # 查看 Gateway 日志"
echo " ./devtools.sh build ai-core # 仅编译 AI-Core"
echo " ./devtools.sh db:status # 检查数据库"
echo ""
echo -e "${BOLD}Web 控制台:${NC} http://localhost:$PORT"
}
# 确保 Node.js 可用
if ! command -v node &> /dev/null; then
if [ -x /usr/local/node/bin/node ]; then
export PATH="/usr/local/node/bin:$PATH"
# ========== 依赖检查 ==========
check_deps() {
local missing=0
# Node.js
if ! command -v node &>/dev/null; then
if [ -x /usr/local/node/bin/node ]; then
export PATH="/usr/local/node/bin:$PATH"
else
echo -e "${RED}✗ Node.js 未安装${NC}"
missing=1
fi
fi
# Docker (用于数据库)
if ! command -v docker &>/dev/null; then
echo -e "${YELLOW}⚠ Docker 未安装 (数据库容器功能不可用)${NC}"
fi
# Go (用于编译后端服务)
if ! command -v go &>/dev/null; then
if $IS_WIN && [ -f "/c/Program Files/Go/bin/go.exe" ]; then
export PATH="$PATH:/c/Program Files/Go/bin"
else
echo -e "${YELLOW}⚠ Go 未安装 (服务编译功能不可用)${NC}"
fi
fi
return $missing
}
# ========== 加载 .env ==========
load_env() {
local env_file="$ROOT/backend/.env"
if [ -f "$env_file" ]; then
echo -e "${GREEN}✓ 加载环境变量: backend/.env${NC}"
set -a
source "$env_file"
set +a
else
echo -e "${RED}❌ 未找到 Node.js，请先安装 Node.js${NC}"
echo -e "${YELLOW}⚠ 未找到 backend/.env，使用默认值${NC}"
fi
}
# ========== 端口工具 (跨平台) ==========
port_in_use() {
local port=$1
if $IS_WIN; then
netstat -ano 2>/dev/null | grep -q ":$port " | grep -q "LISTENING"
else
ss -tlnp 2>/dev/null | grep -q ":$port " || netstat -tlnp 2>/dev/null | grep -q ":$port "
fi
}
kill_port() {
local port=$1
if $IS_WIN; then
local pid=$(netstat -ano 2>/dev/null | grep ":$port " | grep "LISTENING" | awk '{print $NF}' | head -1)
if [ -n "$pid" ] && [ "$pid" != "0" ]; then
powershell -Command "Stop-Process -Id $pid -Force" 2>/dev/null || true
fi
else
fuser -k "$port/tcp" 2>/dev/null || true
fi
sleep 1
}
# ========== 健康检查 ==========
health_check() {
local url=$1
local max_wait=${2:-30}
local waited=0
while [ $waited -lt $max_wait ]; do
if curl -s -o /dev/null -w "%{http_code}" "$url" 2>/dev/null | grep -q "200"; then
return 0
fi
sleep 1
waited=$((waited + 1))
done
return 1
}
# ========== 数据库管理 ==========
DB_COMPOSE_FILE="$ROOT/docker-compose.dev.db.yml"
db_status() {
if port_in_use 5432; then
echo -e "${GREEN}✓ PostgreSQL 在线 (端口 5432)${NC}"
return 0
else
echo -e "${RED}✗ PostgreSQL 离线${NC}"
return 1
fi
}
db_start() {
echo -e "${CYAN}启动数据库容器...${NC}"
if [ ! -f "$DB_COMPOSE_FILE" ]; then
echo -e "${RED}✗ 未找到 $DB_COMPOSE_FILE${NC}"
return 1
fi
docker compose -f "$DB_COMPOSE_FILE" up -d
echo -e "${YELLOW}等待数据库就绪...${NC}"
if health_check "http://localhost:5432" 30; then
echo -e "${GREEN}✓ 数据库已就绪${NC}"
else
echo -e "${YELLOW}⚠ 数据库可能仍在启动中，请稍后检查${NC}"
fi
}
db_stop() {
echo -e "${CYAN}停止数据库容器...${NC}"
if [ ! -f "$DB_COMPOSE_FILE" ]; then
echo -e "${RED}✗ 未找到 $DB_COMPOSE_FILE${NC}"
return 1
fi
docker compose -f "$DB_COMPOSE_FILE" down
echo -e "${GREEN}✓ 数据库已停止${NC}"
}
# ========== 服务编译 ==========
SERVICES=(
"memory-service:backend/memory-service"
"tool-engine:backend/tool-engine"
"iot-debug-service:backend/iot-debug-service"
"voice-service:backend/voice-service"
"ai-core:backend/ai-core"
"plugin-manager:backend/plugin-manager"
"platform-bridge:backend/platform-bridge"
"gateway:backend/gateway"
)
build_service() {
local id=$1
local dir=$2
local label=${3:-$id}
echo -e "${CYAN}[编译] $label...${NC}"
local binary="main"
$IS_WIN && binary="main.exe"
cd "$ROOT/$dir"
if GOWORK=off go build -o "$binary" ./cmd/main.go 2>&1; then
echo -e "${GREEN} ✓ $label 编译完成${NC}"
return 0
else
echo -e "${RED} ✗ $label 编译失败${NC}"
return 1
fi
}
build_all() {
echo -e "${BOLD}编译全部后端服务...${NC}"
local failed=0
for entry in "${SERVICES[@]}"; do
IFS=':' read -r id dir <<< "$entry"
# 检查目录是否存在
if [ -d "$ROOT/$dir" ]; then
build_service "$id" "$dir" "$id" || failed=$((failed + 1))
fi
done
if [ $failed -eq 0 ]; then
echo -e "${GREEN}✓ 全部编译完成${NC}"
else
echo -e "${YELLOW}⚠ $failed 个服务编译失败${NC}"
fi
cd "$ROOT"
return $failed
}
# ========== 查看日志 ==========
show_logs() {
local service_id=$1
local lines=${2:-20}
local log_path="$LOG_DIR/${service_id}.log"
if [ ! -f "$log_path" ]; then
echo -e "${YELLOW}日志文件不存在: $log_path${NC}"
return 1
fi
echo -e "${BOLD}=== $service_id 日志 (最近 $lines 行) ===${NC}"
tail -n "$lines" "$log_path"
}
# ========== 启动 DevTools ==========
start_devtools() {
local do_build=false
local do_fresh=false
# 解析参数
for arg in "$@"; do
case $arg in
--build) do_build=true ;;
--fresh) do_fresh=true ;;
--port=*) PORT="${arg#*=}" ;;
-p) shift; PORT="$1" ;;
esac
done
echo ""
echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo -e "${CYAN} Cyrene DevTools${NC}"
echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
# 依赖检查
check_deps || exit 1
echo -e "${YELLOW}Node.js:${NC} $(node --version)"
command -v go &>/dev/null && echo -e "${YELLOW}Go:${NC} $(go version | cut -d' ' -f3)"
command -v docker &>/dev/null && echo -e "${YELLOW}Docker:${NC} $(docker --version | cut -d' ' -f3 | tr -d ',')"
# 加载环境变量
load_env
# 编译 (如果指定)
if $do_build; then
build_all
fi
# 全新重启 (如果指定)
if $do_fresh; then
echo -e "${YELLOW}强制重启全部后端服务...${NC}"
curl -s -X POST "http://localhost:$PORT/api/services/start-all-fresh" 2>/dev/null || true
fi
# 检查并释放端口
if port_in_use "$PORT"; then
# 检查是否是已有 DevTools 实例
if curl -s -o /dev/null "http://localhost:$PORT/api/health" 2>/dev/null; then
echo -e "${GREEN}✓ DevTools 已在运行: http://localhost:$PORT${NC}"
echo -e "${CYAN} API: http://localhost:$PORT/api/health${NC}"
return 0
fi
echo -e "${YELLOW}⚠ 端口 $PORT 被占用，正在释放...${NC}"
kill_port "$PORT"
fi
# 切换到 devtools 目录
cd "$DEVTOOLS_DIR"
# 安装依赖
if [ ! -d "node_modules" ] || [ ! -f "node_modules/.package-lock.json" ]; then
echo -e "${YELLOW}安装依赖...${NC}"
npm install --silent
fi
# 确保日志目录存在
mkdir -p "$LOG_DIR"
echo ""
echo -e "${GREEN}启动 DevTools 服务器 (端口: $PORT)...${NC}"
echo -e "${CYAN} Web 控制台: http://localhost:$PORT${NC}"
echo -e "${CYAN} API: http://localhost:$PORT/api/health${NC}"
echo -e "${CYAN} WebSocket: ws://localhost:$PORT/ws${NC}"
echo ""
echo -e "${YELLOW}正在后台启动...${NC}"
# 后台启动 DevTools
nohup node src/index.js > "$LOG_FILE" 2>&1 &
local pid=$!
cd "$ROOT"
# 等待健康检查
echo -e "${YELLOW}等待服务就绪...${NC}"
if health_check "http://localhost:$PORT/api/health" 30; then
echo ""
echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo -e "${GREEN} DevTools 已启动！${NC}"
echo -e "${GREEN} PID: ${pid}${NC}"
echo -e "${GREEN} 控制台: http://localhost:$PORT${NC}"
echo -e "${GREEN} 日志: ${LOG_FILE}${NC}"
echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo ""
# 检查数据库状态
db_status
return 0
fi
# 超时
if kill -0 "$pid" 2>/dev/null; then
echo ""
echo -e "${YELLOW}⚠ 服务可能仍在启动中 (已等待 30 秒)${NC}"
echo -e "${CYAN} 请稍后检查 http://localhost:$PORT/api/health${NC}"
else
echo ""
echo -e "${RED}✗ 服务启动失败，请检查日志: ${LOG_FILE}${NC}"
return 1
fi
}
# ========== 停止 DevTools ==========
stop_devtools() {
if port_in_use "$PORT"; then
echo -e "${CYAN}停止 DevTools...${NC}"
if $IS_WIN; then
kill_port "$PORT"
else
fuser -k "$PORT/tcp" 2>/dev/null || true
fi
echo -e "${GREEN}✓ DevTools 已停止${NC}"
else
echo -e "${YELLOW}DevTools 未在运行${NC}"
fi
}
# ========== 查看状态 ==========
show_status() {
if curl -s -o /dev/null "http://localhost:$PORT/api/health" 2>/dev/null; then
echo -e "${GREEN}✓ DevTools 在线${NC}"
# 获取服务状态
local status_json=$(curl -s "http://localhost:$PORT/api/services" 2>/dev/null)
if [ -n "$status_json" ]; then
echo ""
echo -e "${BOLD}服务状态:${NC}"
local tmpfile="$(mktemp)"
echo "$status_json" > "$tmpfile"
node -e "
const fs = require('fs');
const data = JSON.parse(fs.readFileSync(process.argv[1], 'utf-8'));
for (const [id, svc] of Object.entries(data)) {
const icon = svc.status === 'running' ? '✓' : svc.status === 'stopped' ? '✗' : '○';
const color = svc.status === 'running' ? '\x1b[32m' : '\x1b[31m';
const pid = svc.pid ? ' (PID: ' + svc.pid + ')' : '';
const uptime = svc.uptime ? ' | uptime: ' + Math.round(svc.uptime / 1000) + 's' : '';
console.log(' ' + color + icon + '\x1b[0m ' + svc.name.padEnd(16) + ' [' + svc.status + ']' + pid + uptime);
}
" "$tmpfile"
rm -f "$tmpfile"
fi
# 数据库状态
echo ""
db_status
else
echo -e "${RED}✗ DevTools 离线${NC}"
fi
}
# ========== 主入口 ==========
CMD="${1:-start}"
shift 2>/dev/null || true
case "$CMD" in
help|--help|-h)
show_help
;;
start|"")
start_devtools "$@"
;;
stop)
stop_devtools
;;
status)
show_status
;;
logs)
if [ -z "$1" ]; then
echo -e "${YELLOW}用法: ./devtools.sh logs <服务ID>${NC}"
echo "可用服务: gateway, ai-core, memory-service, tool-engine, voice-service, iot-debug-service, plugin-manager, platform-bridge, frontend"
exit 1
fi
show_logs "$1" "${2:-20}"
;;
build)
check_deps || exit 1
load_env
if [ -n "$1" ]; then
# 查找服务目录
for entry in "${SERVICES[@]}"; do
IFS=':' read -r id dir <<< "$entry"
if [ "$id" = "$1" ]; then
build_service "$id" "$dir" "$id"
exit $?
fi
done
echo -e "${RED}未知服务: $1${NC}"
echo "可用服务: ${SERVICES[*]}"
exit 1
else
build_all
fi
;;
db:start)
db_start
;;
db:stop)
db_stop
;;
db:status)
db_status
;;
*)
echo -e "${RED}未知命令: $CMD${NC}"
echo ""
show_help
exit 1
fi
fi
echo -e "${YELLOW}Node.js:${NC} $(node --version)"
echo -e "${YELLOW}npm:${NC} $(npm --version)"
# 加载 backend/.env 环境变量
ENV_FILE="$SCRIPT_DIR/backend/.env"
if [ -f "$ENV_FILE" ]; then
echo -e "${GREEN}✅ 加载环境变量: $ENV_FILE${NC}"
set -a
# shellcheck disable=SC1090
source "$ENV_FILE"
set +a
else
echo -e "${YELLOW}⚠ 未找到 .env 文件，使用默认值${NC}"
fi
# 检查并释放端口
if ss -tlnp 2>/dev/null | grep -q ":$PORT "; then
echo -e "${YELLOW}⚠ 端口 $PORT 已被占用，正在释放...${NC}"
fuser -k "$PORT/tcp" 2>/dev/null || true
sleep 1
echo -e "${GREEN}✅ 端口 $PORT 已释放${NC}"
fi
# 安装依赖 (如有需要)
if [ ! -d "node_modules" ] || [ ! -f "node_modules/.package-lock.json" ]; then
echo -e "${YELLOW}📦 安装依赖...${NC}"
npm install --silent
fi
# 确保日志目录存在
mkdir -p "$LOG_DIR"
echo ""
echo -e "${GREEN}🚀 启动 DevTools 服务器 (端口: $PORT)...${NC}"
echo -e "${CYAN} Web 控制台: http://localhost:$PORT${NC}"
echo -e "${CYAN} API: http://localhost:$PORT/api/health${NC}"
echo -e "${CYAN} WebSocket: ws://localhost:$PORT/ws${NC}"
echo ""
echo -e "${YELLOW}⏳ 正在后台启动所有服务...${NC}"
# 后台启动 DevTools，日志写入 ./logs/sh.log
nohup node src/index.js > "$LOG_FILE" 2>&1 &
DEVTOOLS_PID=$!
# 健康检查（最多等待 30 秒）
MAX_WAIT=30
WAITED=0
while [ $WAITED -lt $MAX_WAIT ]; do
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:$PORT/api/health" 2>/dev/null || true)
if [ "$HTTP_CODE" = "200" ]; then
echo ""
echo -e "${GREEN}✅ 所有服务启动完成！${NC}"
echo -e "${CYAN} PID: ${DEVTOOLS_PID}${NC}"
echo -e "${CYAN} 日志文件: ${LOG_FILE}${NC}"
echo ""
exit 0
fi
sleep 1
WAITED=$((WAITED + 1))
done
# 超时处理
if kill -0 "$DEVTOOLS_PID" 2>/dev/null; then
echo ""
echo -e "${YELLOW}⚠ 服务可能仍在启动中（已等待 ${MAX_WAIT} 秒）${NC}"
echo -e "${CYAN} PID: ${DEVTOOLS_PID}${NC}"
echo -e "${CYAN} 日志文件: ${LOG_FILE}${NC}"
echo -e "${YELLOW} 请稍后检查 http://localhost:$PORT/api/health${NC}"
else
echo ""
echo -e "${RED}❌ 服务启动失败，请检查日志: ${LOG_FILE}${NC}"
exit 1
fi
;;
esac
devtools/public/index.html
+132 -13
View File
@@ -164,8 +164,10 @@ tr.expanded td { background: var(--bg3); }
/* 表单 */
.form-group { margin-bottom: 12px; }
.form-group label { display: block; font-size: 12px; color: var(--text2); margin-bottom: 4px; font-weight: 500; }
.form-row { display: flex; gap: 10px; }
.form-row > * { flex: 1; }
.form-row { display: flex; gap: 10px; align-items: flex-start; }
.form-row > label { flex: 0 0 140px; padding-top: 6px; }
.form-row > :not(label) { flex: 1; }
.form-row .form-row-narrow { flex: 0 0 auto !important; }
input, select, textarea {
width: 100%; padding: 8px 12px; background: var(--bg); border: 1px solid var(--border);
border-radius: var(--radius-sm); color: var(--text); font-size: 13px; font-family: inherit;
@@ -819,11 +821,12 @@ function connectWS() {
document.getElementById('ws-status-text').textContent = '断开(重连中)';
wsRetryTimer = setTimeout(connectWS, 3000);
};
ws.onerror = () => ws.close();
ws.onerror = () => { document.getElementById('ws-dot').className = 'disconnected'; };
ws.onmessage = (ev) => {
const msg = JSON.parse(ev.data);
if (msg.type === 'log') handleWSLog(msg.data);
if (msg.type === 'stt-log') handleSTTLog(msg);
if (msg.type === 'voice_transcript') handleVoiceTranscript(msg);
if (msg.type === 'status') {
STATE.serviceStatus = msg.data;
if (STATE.activePanel === 'services') renderServiceCards();
@@ -3014,7 +3017,116 @@ async function renderSTTPanel() {
'⚠️ Voice-Service 未运行 — 新的语音识别请求将无法处理。请在「服务管理」面板中启动 Voice-Service。</div>';
}
container.innerHTML = statsHtml + tableHtml + voiceStatusHtml;
// 语音录制测试卡片
var recorderHtml = buildVoiceRecorderCard();
container.innerHTML = statsHtml + recorderHtml + tableHtml + voiceStatusHtml;
}
// ---- 语音录制测试 ----
var voiceMediaRecorder = null;
var voiceAudioChunks = [];
function buildVoiceRecorderCard() {
var isRecording = !!voiceMediaRecorder;
return '<div class="card" style="margin-bottom:14px">' +
'<div class="card-header"><span class="card-title">🎙️ 语音录制测试</span>' +
'<span style="font-size:11px;color:var(--text3)">录音后自动发送到 ASR 模型识别并传入对话</span></div>' +
'<div style="display:flex;align-items:center;gap:10px;flex-wrap:wrap">' +
'<button class="btn btn-accent" id="btn-record-start" onclick="startVoiceRecord()" ' + (isRecording ? 'disabled' : '') + '>🎙️ 开始录音</button>' +
'<button class="btn btn-red" id="btn-record-stop" onclick="stopVoiceRecord()" ' + (isRecording ? '' : 'disabled') + '>⏹️ 停止录音</button>' +
'<span id="record-status" style="font-size:12px;color:var(--text2)">' + (isRecording ? '🔴 录音中...' : '点击按钮开始录音') + '</span>' +
'<span id="record-timer" style="font-size:12px;font-family:monospace;color:var(--accent)"></span>' +
'</div>' +
'<div id="voice-result" style="margin-top:10px;font-size:12px;color:var(--text2)"></div>' +
'</div>';
}
var voiceRecordTimer = null;
var voiceRecordSeconds = 0;
async function startVoiceRecord() {
if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
alert('当前浏览器不支持录音功能');
return;
}
try {
var stream = await navigator.mediaDevices.getUserMedia({ audio: true });
voiceAudioChunks = [];
voiceMediaRecorder = new MediaRecorder(stream, { mimeType: MediaRecorder.isTypeSupported('audio/webm;codecs=opus') ? 'audio/webm;codecs=opus' : 'audio/webm' });
voiceMediaRecorder.ondataavailable = function(e) { if (e.data.size > 0) voiceAudioChunks.push(e.data); };
voiceMediaRecorder.onstop = function() {
stream.getTracks().forEach(function(t) { t.stop(); });
processVoiceRecording();
};
voiceMediaRecorder.start();
voiceRecordSeconds = 0;
updateVoiceRecordUI(true);
voiceRecordTimer = setInterval(function() {
voiceRecordSeconds++;
var el = document.getElementById('record-timer');
if (el) el.textContent = voiceRecordSeconds + 's';
}, 1000);
} catch(e) {
alert('无法访问麦克风: ' + e.message);
}
}
function stopVoiceRecord() {
if (voiceMediaRecorder && voiceMediaRecorder.state === 'recording') {
voiceMediaRecorder.stop();
}
if (voiceRecordTimer) { clearInterval(voiceRecordTimer); voiceRecordTimer = null; }
updateVoiceRecordUI(false);
}
function updateVoiceRecordUI(isRecording) {
var startBtn = document.getElementById('btn-record-start');
var stopBtn = document.getElementById('btn-record-stop');
var statusEl = document.getElementById('record-status');
var timerEl = document.getElementById('record-timer');
if (startBtn) startBtn.disabled = isRecording;
if (stopBtn) stopBtn.disabled = !isRecording;
if (statusEl) statusEl.innerHTML = isRecording ? '🔴 录音中...' : '点击按钮开始录音';
if (timerEl) timerEl.textContent = isRecording ? '0s' : '';
}
async function processVoiceRecording() {
var resultEl = document.getElementById('voice-result');
if (!resultEl) return;
if (voiceAudioChunks.length === 0) {
resultEl.innerHTML = '<span style="color:var(--orange)">录音数据为空</span>';
return;
}
var blob = new Blob(voiceAudioChunks, { type: 'audio/webm' });
resultEl.innerHTML = '<span style="color:var(--text3)">📤 发送音频到 ASR 引擎 (' + (blob.size / 1024).toFixed(1) + ' KB)...</span>';
var reader = new FileReader();
reader.onload = function() {
var base64 = reader.result.split(',')[1];
if (ws && ws.readyState === WebSocket.OPEN) {
ws.send(JSON.stringify({
type: 'voice_input',
mode: 'voice_msg',
audio_data: base64,
session_id: STATE.activeSession || 'default',
timestamp: Date.now()
}));
resultEl.innerHTML = '<span style="color:var(--text3)">⏳ 等待语音识别结果...</span>';
} else {
resultEl.innerHTML = '<span style="color:var(--red)">WebSocket 未连接，无法发送语音</span>';
}
};
reader.readAsDataURL(blob);
}
function handleVoiceTranscript(msg) {
var resultEl = document.getElementById('voice-result');
if (!resultEl) return;
if (msg.text) {
resultEl.innerHTML = '<div style="padding:8px 12px;background:var(--green-bg);border-radius:var(--radius-sm);border:1px solid var(--green)">' +
'<strong style="color:var(--green)">✅ 识别结果:</strong> ' + escHtml(msg.text) + '</div>';
}
}
function prependSTTTableRow(entry) {
@@ -3910,10 +4022,10 @@ function updateModelTemplateOptions() {
html += filtered.map(function(m) {
return '<div class="fetched-model-item"' +
' data-model="' + escHtml(m) + '"' +
' onclick="var mn=this.getAttribute(\"data-model\");selectFetchedModel(mn);"' +
' onclick="var mn=this.getAttribute(\'data-model\');selectFetchedModel(mn);"' +
' style="padding:6px 12px;cursor:pointer;font-size:12px;border-bottom:1px solid var(--border);transition:background .12s"' +
' onmouseenter="this.style.background=\"var(--bg3)\""' +
' onmouseleave="this.style.background=\"\"">' + escHtml(m) + '</div>';
' onmouseenter="this.style.background=\'var(--bg3)\'"' +
' onmouseleave="this.style.background=\'\'">' + escHtml(m) + '</div>';
}).join('');
}
html += '</div>';
@@ -3936,10 +4048,10 @@ function updateModelTemplateOptions() {
} else {
results.innerHTML = filtered.map(function(m) {
return '<div class="fetched-model-item" data-model="' + escHtml(m) + '"' +
' onclick="var mn=this.getAttribute(\"data-model\");selectFetchedModel(mn);"' +
' onclick="var mn=this.getAttribute(\'data-model\');selectFetchedModel(mn);"' +
' style="padding:6px 12px;cursor:pointer;font-size:12px;border-bottom:1px solid var(--border);transition:background .12s"' +
' onmouseenter="this.style.background=\"var(--bg3)\""' +
' onmouseleave="this.style.background=\"\"">' + escHtml(m) + '</div>';
' onmouseenter="this.style.background=\'var(--bg3)\'"' +
' onmouseleave="this.style.background=\'\'">' + escHtml(m) + '</div>';
}).join('');
}
}
@@ -4059,11 +4171,13 @@ function showModelForm(id) {
}).join('') + '</select></div>' +
(isEdit ? '' :
'<div class="form-row"><label>📋 快速模板</label>' +
'<div>' +
'<div style="display:flex;gap:8px">' +
'<div id="model-template-area" style="flex:1"><select id="model-template" class="input" onchange="applyModelTemplate(this.value)" style="background:var(--bg3)">' +
'<option value="">-- 选择模型模板 / 查询获取 --</option></select></div>' +
'<button type="button" class="btn btn-sm" id="btn-fetch-models" onclick="fetchProviderModels()" style="white-space:nowrap" disabled>🔍 查询</button></div>' +
'<div style="font-size:11px;color:var(--text3);margin-top:4px">选择 Provider 后可用模板或点击查询在线获取模型列表</div></div>') +
'<div style="font-size:11px;color:var(--text3);margin-top:4px">选择 Provider 后可用模板或点击查询在线获取模型列表</div>' +
'</div></div>') +
'<div class="form-row"><label>描述</label>' +
'<input id="model-desc" class="input" value="' + escHtml(defaults.description || '') + '" placeholder="用于日常对话的模型"></div>' +
'<div class="form-row" style="display:flex;gap:12px"><div style="flex:1"><label>优先级</label>' +
@@ -4188,12 +4302,17 @@ function showRoutingForm(purpose) {
'<option value="memory_extraction"'+ (defaults.purpose === 'memory_extraction' ? ' selected' : '') +'>memory_extraction (记忆提取)</option>' +
'<option value="roleplay"'+ (defaults.purpose === 'roleplay' ? ' selected' : '') +'>roleplay (角色扮演)</option>' +
'<option value="long_context"'+ (defaults.purpose === 'long_context' ? ' selected' : '') +'>long_context (长文档处理)</option>' +
'<option value="speech_recognition"'+ (defaults.purpose === 'speech_recognition' ? ' selected' : '') +'>speech_recognition (实时语音识别)</option>' +
'<option value="speech_recognition_offline"'+ (defaults.purpose === 'speech_recognition_offline' ? ' selected' : '') +'>speech_recognition_offline (非实时语音识别)</option>' +
'</select></div>' +
'<div class="form-row"><label>回退模型链 <span style="color:var(--text2);font-weight:400">(勾选即加入，顺序=表格显示顺序)</span></label>' +
(models.length > 0 ? '<div class="btn-group" style="margin-bottom:8px">' +
'<div style="margin-bottom:10px">' +
'<div style="display:flex;align-items:center;gap:10px;margin-bottom:8px">' +
'<label style="flex:0 0 140px;padding-top:6px">回退模型链 <span style="color:var(--text2);font-weight:400">(勾选即加入，顺序=表格显示顺序)</span></label>' +
(models.length > 0 ? '<div class="btn-group">' +
'<button type="button" class="btn btn-xs" onclick="var cbs=document.querySelectorAll(\'input[name=routing-model]\');cbs.forEach(function(c){c.checked=true})">全选</button>' +
'<button type="button" class="btn btn-xs" onclick="var cbs=document.querySelectorAll(\'input[name=routing-model]\');cbs.forEach(function(c){c.checked=false})">取消全选</button>' +
'</div>' : '') +
'</div>' +
modelCheckboxes + '</div>' +
'<div class="form-row"><label style="display:flex;align-items:center;gap:6px;cursor:pointer">' +
'<input type="checkbox" id="routing-required"' + (defaults.required ? ' checked' : '') + '> 必需 (所有模型不可用时返回错误，而非回退到 .env)</label></div>' +
docs/api/devtools.md
+242
View File
@@ -0,0 +1,242 @@
# Cyrene DevTools 文档
DevTools 是 Cyrene 项目的开发管理控制台，提供 Web UI + CLI 两种使用方式。默认端口 **9090**。
---
## 目录
1. [CLI 命令 (devtools.sh)](#1-cli-命令)
2. [Web 控制台面板](#2-web-控制台面板)
3. [REST API](#3-rest-api)
---
## 1. CLI 命令
`./devtools.sh [命令] [选项]`
### 基本命令
| 命令 | 说明 |
|------|------|
| `start` | 启动 DevTools 控制台 |
| `start --build` | 编译全部后端服务后启动 |
| `start --fresh` | 强制重启全部后端服务后启动 |
| `stop` | 停止 DevTools 控制台 |
| `status` | 查看所有服务状态（运行/停止、PID、uptime） |
| `logs <服务ID> [行数]` | 查看服务日志 |
| `build [服务ID]` | 编译服务（不指定则编译全部） |
| `db:start` | 启动 Docker 数据库容器 |
| `db:stop` | 停止 Docker 数据库容器 |
| `db:status` | 检查数据库连接状态 |
| `help` | 显示帮助 |
### 选项
| 选项 | 说明 |
|------|------|
| `--port, -p <端口>` | 指定 DevTools 端口 (默认: 9090) |
| `--fresh` | 启动前强制重启全部后端服务 |
| `--build` | 启动前编译全部服务 |
### 可用服务 ID
`gateway`, `ai-core`, `memory-service`, `tool-engine`, `voice-service`, `iot-debug-service`, `plugin-manager`, `platform-bridge`, `frontend`
### 示例
```bash
./devtools.sh # 快速启动
./devtools.sh start --build # 编译后启动
./devtools.sh start --fresh # 全新重启
./devtools.sh logs gateway 20 # 查看 Gateway 最近 20 行日志
./devtools.sh build ai-core # 仅编译 AI-Core
./devtools.sh db:status # 检查数据库状态
```
---
## 2. Web 控制台面板
`http://localhost:9090` — 左侧导航栏共 14 个面板。
### 2.1 仪表盘 (Dashboard)
首页总览：服务运行数、活跃会话数、消息总数、记忆总数、数据库状态、系统资源占用。5 秒自动刷新 + WebSocket 实时推送。
### 2.2 记忆管理 (Memory)
对 Memory-Service 的 CRUD 操作。支持搜索、添加、删除记忆，按 `user_id` 筛选。
### 2.3 会话监看 (Sessions)
查看所有活跃会话，按用户分组，查看消息历史，支持多端客户端列表。
### 2.4 服务管理 (Services)
| 操作 | 说明 |
|------|------|
| 一键启动 | 按依赖顺序启动全部 9 个服务 |
| 强制重启 | 先停止全部再重新启动 |
| 单个启动/停止/重启 | 针对每个服务的独立操作 |
| 编译 | 重新编译 Go 服务并启动 |
启动顺序：memory-service → tool-engine → plugin-manager → iot-debug-service → voice-service → ai-core → platform-bridge → gateway → frontend。每步等待健康检查通过。
### 2.5 性能监控 (Performance)
实时 CPU / 内存 使用率，每个服务独立监控，历史曲线图表，定期采集 pidusage。
### 2.6 IoT 设备 (IoT Devices)
代理到 `iot-debug-service`，管理 8 个模拟设备：
- 卧室设备：灯、空调、温度传感器、湿度传感器
- 客厅设备：灯、空调、窗帘
- 安防设备：智能门锁
支持开关切换、属性设置、操作历史查询。WebSocket 实时推送状态变更。
### 2.7 工具调用 (Tool Calls)
代理到 `tool-engine`，查询工具调用记录和统计数据，按工具名筛选。
### 2.8 语音识别 (STT)
STT 转录日志（内存环形缓冲，最多 200 条），支持上传音频文件转录并记录处理时长、识别结果。
### 2.9 数据库监看 (Database)
检查 PostgreSQL / Redis / Qdrant / MinIO / NATS 端口状态，执行 Docker Compose 管理（启动/停止/重启），查询 PostgreSQL 记忆表行数。
### 2.10 自主思考 (Thinking)
代理到 `memory-service`，查看后台自主思考日志，支持按 `user_id` 筛选。
### 2.11 记忆时间线 (Timeline)
合并记忆 + 思考日志为统一时间线，按时间降序排列。
### 2.12 第三方聊天 (Chat Platforms)
代理到 `platform-bridge`，管理 QQ / Telegram 等平台的 Bot 配置和消息日志。
### 2.13 客户端管理 (Clients)
代理到 Gateway，查看所有已知客户端（设备名、UA、在线状态、备注），支持设置备注。
### 2.14 模型配置 (Model Config)
代理到 Gateway Admin API，管理多模型配置系统：
| 子标签 | 说明 |
|--------|------|
| Providers | LLM 服务商配置（API URL、Key、超时等） |
| Models | 模型定义（名称、Provider、参数、优先级、标签） |
| Routing | 路由规则（用途 → 模型回退链） |
---
## 3. REST API
DevTools 自身暴露的 REST API，供脚本和外部工具使用。
### 健康检查
```
GET /api/health
→ { "status": "ok", "service": "cyrene-devtools", "uptime": 3600, "wsClients": 2 }
```
### 服务管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/services` | 所有服务状态 |
| GET | `/api/services/:id` | 单个服务状态 |
| POST | `/api/services/:id/start` | 启动服务 |
| POST | `/api/services/:id/stop` | 停止服务 |
| POST | `/api/services/:id/restart` | 重启服务 |
| POST | `/api/services/:id/build` | 编译服务 |
| POST | `/api/services/start-all` | 按序启动全部 |
| POST | `/api/services/start-all-fresh` | 强制重启全部 |
| POST | `/api/services/stop-all` | 停止全部 |
### 仪表盘
```
GET /api/dashboard
→ { services, performance, sessions, memory, database, system }
```
### 日志
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/logs/:id` | 最近 N 行 (`?lines=200&offset=0`) |
| GET | `/api/logs/:id/recent` | 最近 100 行 |
| DELETE | `/api/logs/:id` | 清空日志 |
### 数据库
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/database/status` | 端口检查 + 记忆表行数 |
| GET | `/api/db/status` | 简单在线状态 |
| POST | `/api/db/start` | docker compose up |
| POST | `/api/db/stop` | docker compose down |
| POST | `/api/db/restart` | docker compose down + up |
### 代理路由 (均需 Gateway 在线)
所有代理路由自动获取 Gateway JWT Token（通过 admin 凭据登录并缓存）。
| DevTools 路径 | 目标服务 | 实际路径 |
|---------------|----------|----------|
| `/api/memory/*` | Gateway | `/api/v1/memory/*` |
| `/api/sessions*` | Gateway | `/api/v1/admin/sessions*` |
| `/api/clients*` | Gateway | `/api/v1/admin/clients*` |
| `/api/model-config/*` | Gateway | `/api/v1/admin/models/*` |
| `/api/iot/devices*` | IoT Debug | `/api/v1/devices*` |
| `/api/tool-calls*` | Tool-Engine | `/api/v1/tools/calls*` |
| `/api/voice/status` | Voice-Service | `/api/v1/status` |
| `/api/voice/transcribe` | Voice-Service | `/api/v1/transcribe` |
| `/api/voice/logs` | DevTools 内部 | 内存环形缓冲区 |
| `/api/v1/thinking*` | Memory-Service | `/api/v1/thinking*` |
| `/api/memory-timeline` | Memory-Service | 合并 Memories + Thinking |
| `/api/chat-platforms/*` | Platform-Bridge | `/api/v1/*` |
| `/api/proxy/:id/health` | 各服务 | 健康检查 |
### 性能监控
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/performance` | 当前性能快照 |
| GET | `/api/performance/dashboard` | 仪表盘聚合数据 |
| GET | `/api/performance/history` | 所有服务历史 |
| GET | `/api/performance/:id` | 单个服务历史 |
| GET | `/api/performance/:id/summary` | 汇总统计 |
### WebSocket
```
ws://localhost:9090/ws
```
实时推送类型：`log`（服务日志）、`status`（服务状态变更）、`stt-log`（STT 处理日志）。
---
## 服务全览
| 服务 ID | 名称 | 端口 | 类型 |
|---------|------|------|------|
| `gateway` | Gateway | 8080 | Go |
| `ai-core` | AI-Core | 8081 | Go |
| `iot-debug-service` | IoT Debug | 8083 | Go |
| `memory-service` | 记忆服务 | 8091 | Go |
| `tool-engine` | 工具引擎 | 8092 | Go |
| `voice-service` | 语音识别服务 | 8093 | Go |
| `plugin-manager` | 插件管理器 | 8094 | Go |
| `platform-bridge` | 多平台桥接 | 8095 | Go |
| `frontend` | Frontend | 5173 | Vite |
docs/api/gateway-api.md
+16 -5
View File
@@ -66,6 +66,8 @@ Auth: 无。IP 限流 ~5/min。仅 `REGISTRATION_ENABLED=true` 时可用（默
Auth: 无。IP 限流 ~5/min。
管理员始终通过 `.env` 中的 `ADMIN_USERNAME` / `ADMIN_PASSWORD` 验证，不依赖数据库状态。普通用户通过数据库 bcrypt 密码哈希验证。
```json
// 请求
{
@@ -75,7 +77,7 @@ Auth: 无。IP 限流 ~5/min。
// 响应 200
{
"user_id": "admin",
"user_id": "admin", // admin 用户固定为 "admin"，普通用户为 "user_<username>"
"nickname": "string",
"token": "JWT",
"refresh_token": "JWT (30天)",
@@ -112,20 +114,29 @@ Auth: JWT（可接受已过期的 token，或在 body 中提供 refresh_token）
Auth: JWT。根据 token 返回当前登录用户的信息。
```json
// 响应 200
// 响应 200 (管理员)
{
"user_id": "admin",
"username": "admin",
"nickname": "叶酱",
"nickname": "管理员",
"is_admin": true,
"created_at": "2024-01-01T00:00:00Z"
"created_at": "2026-01-01T00:00:00Z"
}
// 响应 200 (普通用户)
{
"user_id": "user_alice",
"username": "alice",
"nickname": "Alice",
"is_admin": false,
"created_at": "2026-01-01T00:00:00Z"
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `user_id` | string | 用户 ID（admin 为 `"admin"`，普通用户为 `"user_<username>"`） |
| `username` | string | 用户名 |
| `username` | string | 用户名（管理员为 `.env` 中配置的 `ADMIN_USERNAME`） |
| `nickname` | string | 显示昵称 |
| `is_admin` | bool | 是否管理员 |
| `created_at` | string | 注册时间 (RFC3339)，数据库不可用时为 null |