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 纯原生重构,支持 原生 stdio 本地直启(随 AI 客户端自启退出、零配置开箱即用) 与 Streamable HTTP MCP 双 Transport 架构,提供沉浸式桌面级 Web 控制台、毫秒级 SSE 实时事件流与单二进制内嵌托管,常驻内存仅 ~6.4MB,兼顾本地极简免配置运行与公网高安全生产部署。
✨ 核心特性 (Key Features)
⚡ 0. 原生本地 stdio 直启与双 Transport 架构 (New in v1.2.0)
- 单一配置开箱即用:无需克隆仓库、无需配置 Token、无需手动启动后台守护,Cursor / Claude 配置文件一条
go run ...@latest mcp stdio即可即时运行; - 双 Transport 共享内核:stdio 与 HTTP 双 Transport 共享同一个状态存储、同一个
mcp.Server实例,stdio 运行期间自动伴随本地 Web 控制台; - 工作区绝对零污染:stdio 模式下数据库与自签名证书自动存放于 OS 标准用户目录(Linux:
~/.local/share/relaymesh;macOS:Application Support;Windows:%LOCALAPPDATA%),绝不向代码项目目录写入任何临时文件; - 全生命周期平滑管理:客户端关闭
stdin时平滑退出,端口冲突自动 Fail Fast 友好提示,stdout 严格独占 MCP JSON-RPC 消息流。
🤖 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. 直接运行最新版 HTTP 服务(自动下载、缓存并运行,类似 npx / uvx 模式)
go run github.com/teacat99/RelayMesh/cmd/relaymesh@latest
# 2. 或直接运行原生 stdio MCP 模式(为 Cursor / Claude 等 MCP Host 提供直启端点)
go run github.com/teacat99/RelayMesh/cmd/relaymesh@latest mcp stdio
# 3. 或全局安装到 $GOPATH/bin 作为系统 CLI 工具使用
go install github.com/teacat99/RelayMesh/cmd/relaymesh@latest
relaymesh # 启动 HTTP/HTTPS 常驻服务与 Web 控制台
relaymesh mcp stdio # 启动原生 stdio MCP 服务
💡 桌面环境智能唤醒:在 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 赋予执行权限并运行 HTTP 常驻服务
chmod +x relaymesh-*
./relaymesh-linux-amd64
# 或以原生 stdio 模式运行(与 AI 客户端直接交互)
./relaymesh-linux-amd64 mcp stdio
模式三: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
user: "0:0" # 以 root 运行,避免 bind mount 权限问题(Alpine 最小镜像 + 单二进制,安全风险极低)
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 中配置:
原生 stdio 本地直启(⚡ 推荐,零配置免常驻,进程随 Cursor 启动/退出):
方式 A:Go 开发者免克隆免安装(自动拉取最新版即时运行,类似 npx 模式):
{
"mcpServers": {
"relaymesh": {
"command": "go",
"args": [
"run",
"github.com/teacat99/RelayMesh/cmd/relaymesh@latest",
"mcp",
"stdio"
]
}
}
}
方式 B:单二进制直启(开箱即用,零运行环境依赖):
{
"mcpServers": {
"relaymesh": {
"command": "/path/to/relaymesh",
"args": [
"mcp",
"stdio"
]
}
}
}
本地常驻 HTTP 服务直连模式(适用于 Docker 或后台长期运行的本地服务):
{
"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 中配置:
原生 stdio 本地直启(⚡ 推荐,随 Claude Desktop 一键自启):
{
"mcpServers": {
"relaymesh": {
"command": "go",
"args": [
"run",
"github.com/teacat99/RelayMesh/cmd/relaymesh@latest",
"mcp",
"stdio"
]
}
}
}
本地常驻 HTTP 服务直连模式:
{
"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 证书。
方式一:1Panel / 宝塔等面板反向代理(推荐)
在面板中创建网站并配置反向代理后,修改 proxy 配置文件(如 /www/sites/relaymesh.yourdomain.com/proxy/relaymesh.conf),确保包含以下关键指令:
location ^~ / {
proxy_pass http://127.0.0.1:18775;
proxy_http_version 1.1;
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 REMOTE-HOST $remote_addr;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $http_connection;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Port $server_port;
# SSE 实时流:禁用缓冲,确保事件即时推送
proxy_buffering off;
proxy_cache off;
# MCP 长轮询:延长超时防止断连(3600s = 1 小时)
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_connect_timeout 60s;
proxy_ssl_server_name off;
proxy_ssl_name $proxy_host;
}
方式二:手写 Nginx server 块配置
server {
listen 443 ssl http2;
server_name relaymesh.yourdomain.com;
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_http_version 1.1;
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_set_header Upgrade $http_upgrade;
proxy_set_header Connection $http_connection;
# SSE 实时流与 MCP 长轮询必须配置
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
client_max_body_size 50M;
}
}
关键配置说明:
proxy_buffering off是 SSE 实时事件流的必需项,否则 Nginx 缓冲会导致前端无法收到实时更新。proxy_read_timeout 3600s防止 MCP 长轮询连接被 Nginx 默认 60s 超时切断。
⚙️ 核心环境变量清单 (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 单二进制内置标准 CLI 常用命令:
# 1. 默认无参或显式 serve:启动 HTTP/HTTPS 后台服务与 Web 控制台
./relaymesh
./relaymesh serve
# 2. 原生 stdio MCP 模式:直接作为 MCP 客户端的子进程运行
./relaymesh mcp stdio
# 3. 重置 Web 访问账号密码为环境变量默认值(清除数据库中的在线修改记录)
./relaymesh reset-auth
# 4. 查看当前版本
./relaymesh version
🧑💻 本地开发指南 (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 开源协议。欢迎个人使用、企业二次开发与商用,保留原作者商标与专利反制权益。