miagent Gateway

已连接的 Agent

架构说明

miagent 采用 Gateway + Agent 架构。Agent 通常运行在个人电脑或局域网内，无需公网 IP，通过 WebSocket 长连接主动连接到 Gateway。 Gateway 的 Web Service Proxy 将浏览器的 HTTP 请求通过已有的 WebSocket 隧道转发到 Agent 本地的 Web 服务，实现内网穿透。

# 请求链路
Browser
  │  GET http://gateway2.7up.top/web/{agentId}/path
  ▼
Gateway :3000  (Express)
  │  路由匹配 /web/:agentId/*
  │  → 查 AgentRegistry，确认 agentId 存在且开启了 webService
  │  → 序列化为 web.request (JSON-RPC 2.0)
  │  → 通过已有 WebSocket 发送给 Agent
  ▼
Agent  (局域网，无公网 IP)
  │  收到 web.request
  │  → fetch("http://localhost:{port}" + path)
  ▼
本地 Web 服务  (Hono / Vite / 任意 HTTP 服务)
  │  返回 HTTP Response
  ▼
Agent → web.response (JSON-RPC 2.0) → Gateway → Browser

接入规范

1. Gateway 配置（config.json）

{
  "channels": {
    "webService": {
      "enabled": true,
      "pathPrefix": "/web",          // 代理路由前缀，默认 /web
      "authToken": "your-token",    // 可选，Bearer token 鉴权
      "timeoutMs": 30000            // 单次请求超时，默认 30 s
    }
  }
}

2. Agent 配置（agent.config.json）

{
  "agentId": "my-agent",
  "gatewayUrl": "ws://gateway.example.com/agent",
  "gatewayToken": "your-secret-token",
  "webService": {
    "port": 4173,             // Agent 本地 Web 服务监听端口（仅 localhost）
    "pathPrefix": "/"        // 可选，路径前缀，默认 /
  }
}

3. Agent 本地 Web 服务（推荐使用 Hono）

// 参考 dotai/templates/server 的 Hono 模板
import { Hono } from 'hono'
import { serve } from '@hono/node-server'

const app = new Hono()

app.get('/api/hello', (c) => c.json({ message: 'Hello from Agent!' }))
app.get('/api/status', (c) => c.json({ ok: true, ts: Date.now() }))

serve({ fetch: app.fetch, port: 4173, hostname: '127.0.0.1' })
// 注意：hostname 绑定 127.0.0.1，不对外暴露

4. 访问方式

# 无鉴权
GET http://gateway2.7up.top/web/{agentId}/api/hello

# 有鉴权（Gateway config.json 配置了 authToken）
curl -H "Authorization: Bearer your-token" \
     http://gateway2.7up.top/web/{agentId}/api/hello

# 完整路径映射规则
http://gateway2.7up.top/web/{agentId}/          →  http://localhost:{port}/
http://gateway2.7up.top/web/{agentId}/api/x     →  http://localhost:{port}/api/x
http://gateway2.7up.top/web/{agentId}/static/y  →  http://localhost:{port}/static/y

底层协议

Web Service Proxy 基于已有的 Gateway↔Agent WebSocket 连接，复用 JSON-RPC 2.0 协议，无需额外端口或连接。

{
  "jsonrpc": "2.0",
  "id": "web_xxx",
  "method": "web.request",
  "params": {
    "requestId": "web_1234",
    "httpMethod": "GET",
    "path": "/api/hello",
    "query": "foo=bar",
    "headers": { ... },
    "body": ""  // base64
  }
}

{
  "jsonrpc": "2.0",
  "id": "web_xxx",
  "result": {
    "statusCode": 200,
    "headers": {
      "content-type": "application/json"
    },
    "body": "eyJva..."  // base64
  }
}

当前限制

以下能力在当前版本（Phase 1）尚未支持，计划后续迭代：