RelayMesh

module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 2, 2026 License: Apache-2.0

README

RelayMesh ⚡

高可靠 AI Agent 与人类协同交互中继网关
High-Reliability Human-in-the-Loop & Agentic Relay Hub for Modern AI Development

Go Version Vue Version Tailwind CSS MCP Protocol Single Binary Memory License


📖 项目简介 (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)。
  • 根治客户端超时机制:服务端精细化 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 + → 左右平移切换。
  • 前后端双重防丢持久化:输入时本地 localStorage 0 延迟响应,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 拒绝报错。
🛡️ 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 开源协议。欢迎个人使用、企业二次开发与商用,保留原作者商标与专利反制权益。

Directories

Path Synopsis
cmd
relaymesh command
internal
api
mcp
Package web embeds the built frontend assets into the Go binary.
Package web embeds the built frontend assets into the Go binary.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL