VPS-Commander 开发与协议规范

1. 技术基线

Go + SQLite + net/http + WebSocket。组件：cmd/hub、cmd/agent、cmd/mcp-stdio；internal/api、auth、cluster、executor、mcp、security、storage、web、notify、model。

2. Agent Protocol

Agent 主动连接 /agent/ws。握手包含 protocol version、AgentVersion、capabilities、per-device credential。 Hub 依据 credential 建立 canonical device identity；device/name 只能作为路由参数。

3. HTTP

/api/v1/devices、/api/v1/exec、/api/v1/file/read、/api/v1/file/list、/api/v1/file/info、/api/v1/file/search、/api/v1/process/session、/api/v1/file/write、/api/v1/devices/file/edit_block、/api/v1/mcp/、/api/v1/security/、/api/v1/notifications/webhook*、/healthz、/openapi.json。 Panel 使用 /panel/*。

4. MCP

serverInfo version：1.2.0；protocolVersion：2024-11-05。 11 tools：list_devices、exec_command、read_file、read_multiple_files、create_directory、move_file、list_processes、edit_block、write_file、list_agent_mcp、call_agent_mcp。远程 HTTP 当前为 legacy SSE：GET /mcp/sse + POST /mcp/message?sessionId=...；本地为 stdio。

5. MCP 授权

exec → High；read → Low；write/edit/create/move → Medium；call_agent_mcp → mcp；list_agent_mcp → read。 MCP adapter 与 direct Agent MCP 使用同一 Hub security model。

6. 认证

HTTP/MCP：Authorization: Bearer API_KEY。禁止 ?token、?key、?api_key。 Agent：per-device credential；SQLite 只保存 hash；生产不依赖 Cluster Secret fallback。 Panel：浏览器只持有 Panel Session；Admin Token 在服务端 bridge。

7. 资源

ExecLimiter 32；SearchLimiter 8；Node.WriteMu；Node.OpMu。 Session：ring 2MB；total 8MB；hard TTL 30m；idle TTL 10m；cleanup。

8. 测试

go test ./...；go test -race ./...；git diff --check。生产额外要求 clean tree、vcs.modified=false、revision 与 release commit 一致、单 Agent 灰度、Hub recovery、MCP smoke、security matrix。

9. v2.1

P0：EffectiveRisk fail-closed；Agent token 不进入 argv/cmdline。 P1：Principal/Operator、Session owner 强隔离、完整身份审计链。 v2.1 不改变 Low/Medium/High 语义，不恢复 Shared Secret。

2.2 KiB Raw Blame History Unescape Escape