Cyrene/docs/api/devtools.md

Cyrene DevTools 文档

DevTools 是 Cyrene 项目的开发管理控制台，提供 Web UI + CLI 两种使用方式。默认端口 9090。

---

目录

1. CLI 命令 (devtools.sh)
2. Web 控制台面板
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

示例

./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