README
¶
RelayMesh ⚡
高可靠 AI Agent 与人类协同交互中继网关
High-Reliability Human-in-the-Loop & Agentic Relay Hub for Modern AI Development
📖 项目简介 (Introduction)
RelayMesh 是一款专为 AI 辅助编程与自动化 Agent 打造的高性能、高可靠人机协同交互与状态中继网关。
在长周期开发与自动化任务中,AI Agent(如 Cursor、Claude Desktop、VS Code、Codex)常面临上下文压缩丢失决策、等待人工确认时频繁超时报错 (-32001)、Web 界面简陋难用、以及公网部署缺乏零信任安全等痛点。
RelayMesh 基于 Go 1.25 与 Vue 3.5 纯原生重构,提供标准 Streamable HTTP MCP 接口、沉浸式桌面级 Web 控制台、毫秒级 SSE 实时事件流与单二进制内嵌托管,常驻内存仅 ~6.4MB,支持本地开箱即用直连与公网高安全生产部署。
✨ 核心特性 (Key Features)
🤖 1. 标准 Streamable HTTP MCP 协议中枢
- 双角色无缝支持:
- 人机交互角色 (Human Feedback):
interactive_feedback、continue_feedback_session、get_session_history、list_sessions; - 任务编排与执行角色 (Task Orchestrator):
configure_task、report_progress(支持增量同步sync、结构化报告report与非阻塞检查check_feedback)。
- 人机交互角色 (Human Feedback):
- 根治客户端超时机制:服务端精细化 Long-Polling(40s 挂起上限)配合单调递增因果游标,彻底告别
-32001 Request timed out。 - 秒回直取与提前暂存:用户可在 AI 运行期间随时提前追加意见或暂存留言,AI 再次接入时 0ms 毫秒级直取。
💻 2. 沉浸式现代 Web 交互控制台
- 极简工程美学:基于 Tailwind CSS v4 与 Radix Vue 打造,纯单页沉浸式工作区,支持 跟随系统 💻 / 浅色 ☀️ / 深色 🌙 3 态循环切换。
- 全通侧栏与工作流聚合:统一以
workflow_id进行多轮会话折叠聚合,支持全文检索与类型过滤,支持 PC 端侧边栏平滑折叠展开。 - 悬浮操作与底部避让:毛玻璃悬浮反馈提交栏,支持高度自由拖拽与记忆、多行快捷预设标签与状态联动。
📝 3. 工作流级多草稿箱系统 (Multi-Drafts)
- 多卡槽独立构思:单个工作流支持最多 5 个独立草稿卡槽,支持快捷键
Ctrl + ←/Ctrl + →左右平移切换。 - 前后端双重防丢持久化:输入时本地
localStorage0 延迟响应,400ms 防抖同步写入后端 SQLite 数据库;切换会话或重新部署后草稿与附件全量平滑恢复。 - 撤回草稿绝对保护:输入区已有内容时点击撤回,系统自动开辟新卡槽暂存编辑内容,确保 100% 零覆盖、零丢失。
🔍 4. 工业级 Markdown 排版与严格字符网格
- CJK 严格 2ch 网格对齐:通过自定义字符级扫描与样式约束,强制中文字符与英文字符严格呈现 2:1 等宽网格,彻底解决 ASCII 流程图(
┌─┐、│、└─┘)在不同操作系统下的错位问题。 - 极简手势图片灯箱:全站图片打通(Markdown 正文、历史记录、输入框附件),纯净无边框无按钮,支持鼠标滚轮(0.4x~5x)无级平滑缩放、双指捏合与点击遮罩退出。
🎙️ 5. 双端口原生 HTTPS 与 ASR 语音输入
- 零依赖自签名 TLS 引擎:Go 单二进制内置证书生成器,启动时自动生成覆盖本地网卡的 10 年有效期 RSA 证书。
- 协议安全分流:
- HTTPS 端口 (
18776):Web UI 访问,直接解锁现代浏览器麦克风录音权限 (getUserMedia),内置小米 MIMO 流式 ASR 语音转文字; - HTTP 端口 (
18775):MCP 服务端点,规避 AI 客户端连接自签名证书时的 TLS 拒绝报错。
- HTTPS 端口 (
🛡️ 6. 公网生产零信任安全闭环
- Web 访问强鉴权:支持管理员账号密码认证与 7 天有效期 JWT 验签;
- 内存级原子反爆破限流器 (RateLimiter & Lockout):基于客户端 IP 的失败计数与阶梯式自动封禁,防暴力穷举;
- MCP 全局 Token 保护:支持
RELAYMESH_MCP_TOKEN,支持 Header(Bearer)与 URL Query(?token=)双通道认证; - CLI 安全重置:支持在服务器执行
./relaymesh reset-auth,一键重置自定义凭据为环境变量初始设定。
🏗️ 系统架构图 (Architecture)
┌─────────────────────────────────────────────────────────────────────────────┐
│ AI 开发客户端 (AI Clients) │
│ Cursor / Claude Desktop / VS Code / Codex │
└──────────────────────────────────────┬──────────────────────────────────────┘
│ Streamable HTTP MCP (POST /mcp)
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ RelayMesh 协作中枢核心 │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Go 1.25 单二进制服务内核 (18775/18776) │ │
│ │ - Streamable HTTP MCP Server - 内存级反爆破限流器 (Lockout) │ │
│ │ - SSE 实时事件广播 Broker - 零依赖 TLS 证书引擎 (18776) │ │
│ │ - RESTful 业务状态与草稿 API - embed.FS 纯静态网页内嵌托管 │ │
│ └───────────────────────────────────┬───────────────────────────────────┘ │
│ │ 持久化读写 │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ 纯 Go SQLite 数据库引擎 (无 CGO 依赖) │ │
│ │ sessions / tasks / workflow_drafts / system_settings │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────┬──────────────────────────────────────┘
│ SSE 实时推送 & REST API
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Vue 3.5 + Tailwind v4 Web 控制台 │
│ 沉浸式工作区 / 多草稿箱 (Ctrl+←/→) / 手势图片灯箱 / ASR 语音录音 │
└─────────────────────────────────────────────────────────────────────────────┘
🚀 部署与运行方式 (Installation & Deployment)
RelayMesh 支持多种部署运行形态,覆盖从「本地极速免安装试用」到「企业级云原生生产部署」的全部场景:
模式一:Go 原生即时运行 / 类似 npx 模式(⚡ Go 开发者首选,0 安装即下即跑)
Go 1.24+ 开发者无需手动克隆仓库或配置 Node 环境,直接通过 Go 命令行一键拉取并即时运行内嵌完整 Web 控制台的单二进制:
# 1. 直接运行最新版(自动下载、缓存并运行,类似 npx / uvx 模式)
go run github.com/teacat99/RelayMesh/cmd/relaymesh@latest
# 2. 或全局安装到 $GOPATH/bin 作为系统 CLI 工具使用
go install github.com/teacat99/RelayMesh/cmd/relaymesh@latest
relaymesh
💡 桌面环境智能唤醒:在 macOS / Windows / Linux 桌面或 WSL2 环境下启动时,RelayMesh 将在 800ms 内自动唤醒系统默认浏览器打开 Web 控制台;容器或远程无头服务器则严格静默跳过。
模式二:预编译单二进制与一键安装脚本(📦 开箱即用,免任何运行环境)
适用于没有 Go 或 Docker 环境的用户,直接下载单一绿色可执行文件,双击或一键执行即可:
1. Linux / macOS 一键安装脚本
curl -fsSL https://raw.githubusercontent.com/teacat99/RelayMesh/main/install.sh | bash
2. GitHub Releases 预编译单二进制直接下载
前往 GitHub Releases 下载对应操作系统架构的独立单文件:
- Linux (x86_64 / amd64):
relaymesh-linux-amd64 - Linux (ARM64 / aarch64):
relaymesh-linux-arm64 - macOS (Apple Silicon M系列 / arm64):
relaymesh-darwin-arm64 - macOS (Intel / amd64):
relaymesh-darwin-amd64 - Windows (x86_64):
relaymesh-windows-amd64.exe
下载后直接运行:
# Linux / macOS 赋予执行权限并运行
chmod +x relaymesh-*
./relaymesh-linux-amd64
模式三:Docker / Docker Compose 容器化部署(🐳 多架构支持,生产与常驻推荐)
官方 Docker 镜像发布于 Docker Hub(teacat99/relaymesh:latest),原生支持 linux/amd64 与 linux/arm64。
1. 本地免密直连模式(本地开发与内网常驻预览推荐)
创建 docker-compose.yml:
services:
relaymesh:
image: teacat99/relaymesh:latest
container_name: relaymesh
restart: unless-stopped
ports:
- "18775:18775"
- "18776:18776"
environment:
- RELAYMESH_HOST=0.0.0.0
- RELAYMESH_PORT=18775
- RELAYMESH_HTTPS_PORT=18776
- RELAYMESH_DB_PATH=/app/data/relaymesh.db
- RELAYMESH_PROJECT_ID=default
- RELAYMESH_ALLOW_NON_LOOPBACK=true
- GIN_MODE=release
volumes:
- ./data:/app/data
启动容器:
docker compose up -d
- HTTP 访问与 MCP 端点:
http://localhost:18775/ - HTTPS 麦克风录音访问:
https://localhost:18776/
2. 公网生产安全模式(云服务器与反向代理推荐)
创建 docker-compose.prod.yml:
services:
relaymesh:
image: teacat99/relaymesh:latest
container_name: relaymesh-prod
restart: unless-stopped
ports:
- "127.0.0.1:18775:18775"
environment:
- RELAYMESH_HOST=0.0.0.0
- RELAYMESH_PORT=18775
- RELAYMESH_HOST_NAME=prod-relayhub
- RELAYMESH_DB_PATH=/app/data/relaymesh.db
- RELAYMESH_PROJECT_ID=default
# Web 控制台管理员账号与访问强密码
- RELAYMESH_WEB_USERNAME=admin
- RELAYMESH_WEB_PASSWORD=YourStrongWebPassword2026!
- RELAYMESH_JWT_SECRET=YourRandomJWTSecretKeyAtLeast32CharsLong!
# 全局 MCP 访问 Token
- RELAYMESH_MCP_TOKEN=rmk_prod_secret_token_8888
- RELAYMESH_ALLOW_NON_LOOPBACK=true
- GIN_MODE=release
volumes:
- ./data:/app/data
启动生产容器:
docker compose -f docker-compose.prod.yml up -d
模式四:源码克隆与自主构建(🛠️ 适用于深度定制与二次开发)
# 1. 克隆项目仓库
git clone https://github.com/teacat99/RelayMesh.git
cd RelayMesh
# 2. 构建前端静态资源
pnpm --dir frontend install
pnpm --dir frontend run build
# 3. 编译纯 Go 单二进制产物(前端自动内嵌进 Go 二进制)
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/relaymesh ./cmd/relaymesh
# 4. 运行单二进制服务
./bin/relaymesh
🔌 AI 客户端配置 (AI Client Setup)
1. Cursor IDE 配置
在项目根目录 .cursor/mcp.json 或全局配置 ~/.cursor/mcp.json 中配置:
本地免密直连模式:
{
"mcpServers": {
"relaymesh": {
"url": "http://localhost:18775/mcp"
}
}
}
公网 URL 鉴权模式(推荐,配置最极简):
{
"mcpServers": {
"relaymesh": {
"url": "https://relaymesh.yourdomain.com/mcp?token=rmk_prod_secret_token_8888"
}
}
}
公网 Header 鉴权模式(企业标准):
{
"mcpServers": {
"relaymesh": {
"url": "https://relaymesh.yourdomain.com/mcp",
"headers": {
"Authorization": "Bearer rmk_prod_secret_token_8888"
}
}
}
}
2. Claude Desktop 配置
在 claude_desktop_config.json 中配置(Claude Desktop 原生仅支持 URL 形式传参):
本地免密直连模式:
{
"mcpServers": {
"relaymesh": {
"url": "http://localhost:18775/mcp"
}
}
}
公网 Token 鉴权模式(URL 嵌入):
{
"mcpServers": {
"relaymesh": {
"url": "https://relaymesh.yourdomain.com/mcp?token=rmk_prod_secret_token_8888"
}
}
}
3. VS Code Cline / Roo Code 配置
在 Cline MCP 设置中添加:
{
"mcpServers": {
"relaymesh": {
"name": "RelayMesh",
"type": "streamable-http",
"url": "https://relaymesh.yourdomain.com/mcp?token=rmk_prod_secret_token_8888"
}
}
}
🌐 Nginx / 1Panel 反向代理配置 (Reverse Proxy)
在公网生产环境部署时,建议通过 Nginx 或 1Panel 反向代理统一绑定域名与泛域名 SSL 证书:
server {
listen 443 ssl http2;
server_name relaymesh.yourdomain.com;
# SSL 证书配置
ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
# 全局代理基础配置
location / {
proxy_pass http://127.0.0.1:18775;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
client_max_body_size 50M;
}
# 关键:SSE 实时流与 MCP 长挂起专用代理配置
location ~* ^/(api/v1/events|sse/events|mcp) {
proxy_pass http://127.0.0.1:18775;
proxy_http_version 1.1;
proxy_set_header Connection '';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# 禁用代理缓存与缓冲,确保实时事件毫秒级直达
proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding off;
# 配置 1 小时长超时,防止轮询被 Nginx 提前切断
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
}
⚙️ 核心环境变量清单 (Environment Variables)
| 环境变量名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
RELAYMESH_HOST |
字符串 | 127.0.0.1 |
HTTP 服务监听 IP(容器内使用 0.0.0.0) |
RELAYMESH_PORT |
整数 | 18775 |
HTTP 服务与 MCP 端口 |
RELAYMESH_HTTPS_PORT |
整数 | 18776 |
HTTPS 原生安全端口(用于浏览器麦克风录音) |
RELAYMESH_HOST_NAME |
字符串 | 空 | 主机名标识(如 wsl, macbook, dev-server),用于多机环境区分 |
RELAYMESH_DB_PATH |
字符串 | data/relaymesh.db |
SQLite 数据库文件持久化路径 |
RELAYMESH_PROJECT_ID |
字符串 | default |
默认项目隔离标识 |
RELAYMESH_WEB_USERNAME |
字符串 | admin |
Web 控制台管理员账号 |
RELAYMESH_WEB_PASSWORD |
字符串 | 空 (免密) | Web 控制台密码(配置后强制开启 JWT 登录鉴权) |
RELAYMESH_JWT_SECRET |
字符串 | 内置默认 | JWT 签名密钥(生产环境必须修改为随机长字符串) |
RELAYMESH_MCP_TOKEN |
字符串 | 空 (免鉴权) | 全局 MCP 访问 Token(配置后 MCP 请求需携带 Token) |
RELAYMESH_TLS_ENABLED |
布尔值 | true |
是否启用内置零依赖 HTTPS 自签名 TLS 引擎 |
RELAYMESH_ASR_API_URL |
字符串 | MIMO 官方端点 | 语音识别 ASR 服务接口地址 |
RELAYMESH_ASR_API_KEY |
字符串 | 空 | 语音识别 ASR 认证密钥 |
📦 Docker 镜像发布与 CI/CD 自动化 (Docker Publishing)
方式一:GitHub Actions 自动构建与发布(推荐)
项目已内置 .github/workflows/docker-publish.yml,当推送 Tag(如 v1.0.0)或合并至 main 分支时,将自动通过 GitHub Actions 执行多架构(linux/amd64, linux/arm64)构建,并推送到:
- Docker Hub:
teacat99/relaymesh:latest - GitHub Container Registry (GHCR):
ghcr.io/<owner>/relaymesh:latest
仅需在 GitHub 仓库的 Settings -> Secrets and variables -> Actions 中配置
DOCKERHUB_USERNAME与DOCKERHUB_TOKEN。
方式二:本地一键发布脚本 (Multi-arch Buildx)
使用项目内置脚本执行多架构构建与推送:
# 1. 登录 Docker Hub
docker login
# 2. 一键构建并推送多架构镜像(默认 amd64 + arm64)
./scripts/publish-docker.sh v1.0.0
🛠️ 运维与命令行工具 (CLI Tools)
RelayMesh 单二进制内置安全重置命令,支持随时在宿主机或容器内恢复初始环境:
# 重置 Web 访问账号密码为环境变量默认值(清除数据库中的在线修改记录)
./relaymesh reset-auth
🧑💻 本地开发指南 (Development)
# 1. 启动前端 Vite 开发热重载服务器 (端口 5173,自动反代 18775 后端)
pnpm --dir frontend run dev
# 2. 启动 Go 后端单二进制服务 (端口 18775 / 18776)
go run ./cmd/relaymesh
# 3. 运行全量单元测试
go test ./...
📄 开源许可证 (License)
本项目遵循 Apache License 2.0 开源协议。欢迎个人使用、企业二次开发与商用,保留原作者商标与专利反制权益。