小虾 Local Agent 架构设计：控制用户本地电脑

> 发布日期：2026-03-31 | 作者：Tony @ Jay's Lab

> 分类：私有报告 | 项目：xiaoxia.app

>

> 小虾从"云端容器托管"延伸到"本地代理执行"的架构设计方案。基于 Manus Desktop 的经验教训和 OpenClaw Node 的实战踩坑，设计一个轻量、安全、透明的本地 Agent。

1. 背景与动机

1.1 为什么需要本地 Agent？

小虾（xiaoxia.app）当前架构是纯云端：用户的 AI agent 运行在 K3s 托管的 Docker 容器中。但很多高价值场景需要访问用户本地环境：

• 开发者工具链：操作本地 IDE、运行本地测试、管理 Git 仓库
• 文件管理：整理本地文档、处理本地图片/视频
• 系统自动化：定时备份、批量重命名、环境配置
• GUI 操作：代填表单、自动化重复性操作
• 本地 GPU 利用：用户的显卡跑推理，不用付云端 GPU 费用

1.2 Manus Desktop 的先例

Manus 于 2026 年 3 月 17-18 日发布 Desktop App（Meta 收购后首个大动作），采用混合执行模型：

• 本地执行：文件操作、终端命令、GUI 控制、GPU 计算
• 云端执行：LLM 推理、任务规划、代码生成

Manus 的问题（用户反馈）：

• Credit 消耗不透明，用户不知道钱花在哪
• 复杂任务可靠性差
• Electron 打包，安装包 200MB+
• 权限模型不清晰

1.3 OpenClaw Node 的经验

我们已有 OpenClaw Node 的实战经验（Mac mini 配对），踩过的关键坑：

2. 核心架构

2.1 总体设计

用户本地电脑                              小虾云端
┌──────────────────┐                  ┌───────────────┐
│  xiaoxia-agent    │◄── WebSocket ──►│  控制面 API     │
│  (轻量守护进程)     │   (出站连接)      │  + LLM 推理    │
│                   │                  │  + 任务调度     │
│  ├─ exec 模块      │                  │  + 用户 Dashboard│
│  ├─ fs 模块        │                  └───────────────┘
│  ├─ screen 模块    │
│  ├─ gui 模块       │
│  ├─ approval 模块  │
│  └─ heartbeat     │
└──────────────────┘

核心原则：本地只做执行，云端做决策。

Agent 本身不含任何 LLM，就是一个听指令干活的"手脚"。所有智能决策（任务分解、代码生成、错误分析）都在云端完成。

2.2 为什么 WebSocket 出站连接？

传统方案（如 SSH）需要云端主动连接用户电脑，面临：

• NAT 穿透问题（家庭网络、公司防火墙）
• 端口暴露安全风险
• 动态 IP 处理

WebSocket 出站连接天然解决所有问题：

• Agent → 云端（出站），NAT/防火墙友好
• 用户电脑不暴露任何端口
• 断线自动重连
• TLS 加密（连接云端的标准 HTTPS）

2.3 与 Manus 的架构对比

3. 权限模型

3.1 三级权限体系

这是与 Manus 最大的差异化：完全透明的权限控制。

3.2 操作审批流程

云端发来命令: exec("npm install", cwd="~/projects/my-app")
        │
        ▼
┌─ 权限检查 ─┐
│ 当前级别: L2 │
│ 目录白名单:   │──── ~/projects/ ✅ 在白名单内
│ 命令白名单:   │──── npm ✅ 在白名单内
└──────────┘
        │
        ▼ 自动放行（L2 + 白名单匹配）
    执行命令

云端发来命令: exec("sudo apt install nginx")
        │
        ▼
┌─ 权限检查 ─┐
│ 当前级别: L2 │
│ sudo 命令   │──── ❌ 需要 L3 权限
└──────────┘
        │
        ▼ 弹出确认
┌────────────────────────────────┐
│ ☁️ 小虾想执行:                   │
│ sudo apt install nginx          │
│                                 │
│ ⚠️ 此操作需要管理员权限            │
│                                 │
│ [允许一次] [允许并升级到L3] [拒绝]  │
└────────────────────────────────┘

3.3 审计日志

所有操作记录在本地日志文件（用户可随时查看）：

{
  "timestamp": "2026-03-31T11:30:00Z",
  "action": "exec",
  "command": "npm install",
  "directory": "~/projects/my-app",
  "approval": "auto_whitelist",
  "result": "success",
  "duration_ms": 12340
}

4. 通信协议

4.1 JSON-RPC 2.0 over WebSocket

选择 JSON-RPC 2.0 的原因：

• 标准化，有大量现成库
• 双向通信（云端→agent 命令，agent→云端 结果/审批请求）
• 易于调试（JSON 可读）

4.2 消息类型

云端 → Agent：执行命令

{
  "jsonrpc": "2.0",
  "method": "exec",
  "params": {
    "command": "ls -la ~/Documents",
    "timeout_ms": 30000,
    "stream": true
  },
  "id": "task-001"
}

Agent → 云端：流式输出

{
  "jsonrpc": "2.0",
  "method": "output",
  "params": {
    "task_id": "task-001",
    "chunk": "total 128\ndrwxr-xr-x  5 jay  staff  160 Mar 31 10:00 .\n",
    "done": false
  }
}

Agent → 云端：需要用户审批

{
  "jsonrpc": "2.0",
  "method": "approval_required",
  "params": {
    "task_id": "task-001",
    "action": "exec",
    "command": "sudo systemctl restart nginx",
    "reason": "需要管理员权限",
    "current_level": "L2",
    "required_level": "L3"
  }
}

Agent → 云端：系统信息

{
  "jsonrpc": "2.0",
  "method": "sysinfo",
  "params": {
    "os": "darwin",
    "arch": "arm64",
    "hostname": "jays-macbook",
    "cpu": "Apple M4",
    "ram_gb": 16,
    "disk_free_gb": 128,
    "gpu": "Apple M4 GPU (10-core)",
    "agent_version": "0.1.0",
    "permission_level": "L2"
  }
}

4.3 安全机制

5. 技术实现

5.1 为什么选 Go？

Go 是最平衡的选择：和小虾主体统一、交叉编译方便、用户零依赖。

5.2 GUI 技术选型

Go 的 GUI 生态不如 Electron 丰富，但对 Agent 来说不需要复杂 UI。采用分层策略：

Go GUI 库现状：

推荐方案：systray（日常）+ Wails（设置面板）

v0.1  纯 CLI，无 GUI                        → 0 额外依赖
v0.2  + systray 托盘图标（状态/权限/暂停）      → +1MB
v0.3  + Wails 设置面板（白名单/日志/设备详情）   → +15MB

v0.2 系统托盘：用 getlantern/systray，代码极简：

systray.SetIcon(icon)
systray.SetTitle("🦐 小虾 Agent")
mStatus := systray.AddMenuItem("✅ 已连接", "")
mPermission := systray.AddMenuItem("权限: L2 标准", "")
mLogs := systray.AddMenuItem("查看日志", "")
systray.AddSeparator()
mQuit := systray.AddMenuItem("退出", "")

90% 的日常交互（看状态、改权限、暂停）托盘菜单就够了。

v0.3 Wails 设置面板：需要更丰富 UI 时才引入。

Go 后端（agent 核心逻辑）
    ↕ 绑定调用
Web 前端（Vue/Svelte，打包进二进制）

• 最终产物仍是单个二进制（~15-20MB，比 Electron 200MB 好 10 倍）
• 前端随便用 Vue/React/Svelte，UI 质量和 Web 一样
• 不需要装浏览器，用系统 WebView（macOS WebKit / Windows WebView2）

核心原则：不要一上来就做 GUI。 先让 CLI 跑通，托盘够日常用，复杂设置面板等有用户反馈再加。

5.3 Windows 平台适配

Go 交叉编译原生支持 Windows：GOOS=windows GOARCH=amd64 go build -o xiaoxia-agent.exe

平台差异通过 //go:build 条件编译处理：

// exec_windows.go
//go:build windows
func runCommand(cmd string) *exec.Cmd {
    return exec.Command("powershell", "-NoProfile", "-c", cmd)
}

// exec_unix.go
//go:build !windows
func runCommand(cmd string) *exec.Cmd {
    return exec.Command("sh", "-c", cmd)
}

Windows 安装脚本：

irm https://xiaoxia.app/install.ps1 | iex

Go 标准库（os/exec、filepath）已处理大部分跨平台差异，核心逻辑（WebSocket、JSON-RPC、权限检查）完全不用改。

5.2 模块设计

xiaoxia-agent/
├── main.go              // 入口，启动 WebSocket 连接
├── cmd/
│   ├── pair.go          // 配对命令
│   ├── start.go         // 启动守护进程
│   └── status.go        // 查看状态
├── internal/
│   ├── ws/
│   │   └── client.go    // WebSocket 客户端，重连逻辑
│   ├── executor/
│   │   ├── exec.go      // 命令执行（带超时、流式输出）
│   │   ├── fs.go        // 文件操作（读/写/列表）
│   │   ├── screen.go    // 屏幕截图
│   │   └── gui.go       // GUI 自动化（v0.4+）
│   ├── approval/
│   │   ├── checker.go   // 权限检查
│   │   ├── prompt.go    // 终端/GUI 弹窗确认
│   │   └── whitelist.go // 白名单管理
│   ├── config/
│   │   └── config.go    // 配置文件管理
│   └── logger/
│       └── audit.go     // 审计日志
├── config.toml          // 用户配置
└── audit.log            // 操作日志

5.3 配对流程

用户操作                          小虾云端

1. 下载 agent
   curl -fsSL https://xiaoxia.app/install.sh | sh

2. 运行配对
   $ xiaoxia-agent pair
   
   显示: "请在 xiaoxia.app 输入配对码: ABC-XYZ-123"
                                    │
3. 用户在网页端输入配对码 ─────────────►│
                                    │
4. 云端生成 Agent Token ◄────────────┘
   + 绑定到用户账户
                                    │
5. Agent 收到 Token ◄───────────────┘
   保存到 ~/.xiaoxia/credentials.json
   
6. WebSocket 长连接建立 ──────────────►
   
   $ xiaoxia-agent start
   ✅ 已连接到 xiaoxia.app
   📋 权限级别: L1 (只读)
   💡 运行 'xiaoxia-agent config' 调整权限

5.4 安装脚本设计

#!/bin/bash
# install.sh — 一键安装 xiaoxia-agent

set -e

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)

case "$ARCH" in
  x86_64)  ARCH="amd64" ;;
  aarch64|arm64) ARCH="arm64" ;;
  *) echo "不支持的架构: $ARCH"; exit 1 ;;
esac

URL="https://xiaoxia.app/dl/xiaoxia-agent-${OS}-${ARCH}"
DEST="/usr/local/bin/xiaoxia-agent"

echo "⬇️  下载 xiaoxia-agent (${OS}/${ARCH})..."
curl -fsSL "$URL" -o "$DEST"
chmod +x "$DEST"

echo "✅ 安装完成！"
echo ""
echo "下一步："
echo "  xiaoxia-agent pair    # 绑定到你的小虾账户"
echo "  xiaoxia-agent start   # 启动 agent"

6. 渐进式功能路线

Phase 1：CLI Agent（v0.1，1-2 周）

最小可行产品，验证核心架构：

支持的命令：
├── exec     — 执行 shell 命令，流式返回输出
├── read     — 读取文件内容
├── write    — 写入文件
├── ls       — 列出目录
├── sysinfo  — 返回系统信息
└── ping     — 心跳

交互方式：纯终端（无 GUI）

Phase 2：系统托盘 GUI（v0.2，+1 周）

┌─────────────────────────┐
│ 🦐 小虾 Agent           │
│                         │
│ 状态: ✅ 已连接           │
│ 权限: L2 (标准)          │
│ 今日操作: 23 次          │
│                         │
│ [查看日志] [调整权限]     │
│ [暂停] [断开连接]        │
└─────────────────────────┘

• macOS: 菜单栏图标（用 Go 的 systray 库）
• Windows: 系统托盘
• Linux: AppIndicator

Phase 3：屏幕感知（v0.3，+1 周）

新增命令：
├── screenshot  — 截取全屏/指定窗口
├── ocr         — 识别屏幕文字（调用云端视觉模型）
└── windows     — 列出当前打开的窗口

使用场景：

• "帮我看看屏幕上这个报错是什么"
• "总结我正在看的这篇文章"

Phase 4：GUI 自动化（v0.4，+2 周）

新增命令：
├── click      — 点击屏幕坐标/元素
├── type       — 输入文字
├── hotkey     — 发送快捷键
└── scroll     — 滚动

实现方式：

• macOS: AppleScript / Accessibility API
• Windows: Win32 API / UI Automation
• Linux: xdotool / ydotool

Phase 5：跨设备任务连续性（v0.5，+1 周）

核心场景：云端开始，本地继续

用户在手机/网页端对小虾说:
  "帮我在我的电脑上创建一个新的 React 项目"

云端任务调度器:
  1. 检查用户有哪些在线 agent
  2. 选择目标设备（jays-macbook, L2 权限）
  3. 生成执行计划
  4. 通过 WebSocket 发送到 agent
  
Agent 执行:
  exec("npx create-react-app my-project", cwd="~/projects/")
  exec("cd my-project && code .", cwd="~/projects/")  // 打开 VS Code
  
结果返回给用户手机:
  "✅ React 项目已创建在 ~/projects/my-project/，VS Code 已打开"

7. 定价策略

7.1 Agent 本身免费

Agent 是开源的、免费的。小虾赚钱的方式是云端服务（LLM 推理 + 任务调度），不是本地软件。

7.2 云端计费

7.3 与 Manus 定价对比

8. 安全考量

8.1 威胁模型

8.2 关键安全原则

1. Agent 端可以拒绝任何命令：即使云端发来指令，本地检查不通过就不执行

2. 用户始终有最终控制权：可以随时暂停、断开、卸载

3. 最小权限原则：默认只读，逐步升级

4. 审计不可篡改：本地日志 append-only，云端也保留副本

8.3 macOS 特殊处理

首次运行时的权限引导：

1. 辅助功能权限（GUI 自动化需要）
   → 系统偏好设置 → 隐私与安全性 → 辅助功能
   → 添加 xiaoxia-agent

2. 屏幕录制权限（截图需要）
   → 系统偏好设置 → 隐私与安全性 → 屏幕录制
   → 添加 xiaoxia-agent

3. 完全磁盘访问（可选，访问 ~/Desktop 等受保护目录）
   → 系统偏好设置 → 隐私与安全性 → 完全磁盘访问

Agent 提供一键引导脚本：
$ xiaoxia-agent setup-permissions

9. 云端 Relay 架构：Agent 连接管理

用户本地 agent 通过 WebSocket 连接云端，云端需要一个组件来管理这些连接。有两种方案：

9.1 方案 A：独立 Relay 服务（推荐）

xiaoxia-agent (用户电脑)
    │ WSS 出站连接
    ▼
xiaoxia-relay (独立 Go 服务，跑在小虾云端)
    │ 内部 HTTP API
    ▼
xiaoxia-hosting (现有控制面)
    │
    ▼
LLM Proxy → 模型推理

xiaoxia-relay 是一个独立的 Go 进程，核心职责：

• 连接池管理：维护所有在线 agent 的 WebSocket 长连接
• 命令路由：将 LLM 的执行指令路由到正确的 agent
• 心跳监控：30 秒心跳，断连后立即标记设备离线
• 断线重连：agent 自动重连，relay 恢复会话状态
• 内部 API：暴露 HTTP 接口给 hosting 服务调用

内部 API 示例：

POST /api/v1/agents/{agent_id}/exec
{
  "command": "ls -la ~/Documents",
  "timeout_ms": 30000
}

GET /api/v1/agents/{agent_id}/status
→ { "online": true, "permission_level": "L2", "os": "darwin", ... }

GET /api/v1/agents
→ [{ "agent_id": "abc123", "hostname": "jays-macbook", "online": true }, ...]

优点：

• 与现有 hosting 服务解耦，可独立扩容
• 连接数增长后加 relay 实例即可（水平扩展）
• 核心代码量 ~300-500 行 Go

9.2 方案 B：作为 OpenClaw 插件

如果小虾的 AI 层直接使用 OpenClaw：

xiaoxia-agent (用户电脑)
    │ WSS
    ▼
openclaw-xiaoxia-plugin (OpenClaw 插件)
    │ 注册为 Tool
    ▼
OpenClaw Gateway
    │
    ▼
LLM → tool_call: agent.exec("npm install")

插件将 agent 连接注册为 OpenClaw 的 Tool，LLM 直接通过 tool_call 操作用户电脑。本质上就是 OpenClaw Node 的思路，只是换成了 WebSocket 出站连接（而非 Node 的入站连接）。

优点：零代码即可让 LLM 操作本地电脑

缺点：强依赖 OpenClaw 框架

9.3 方案选择

推荐先做方案 A（独立 Relay），原因：

1. 小虾是独立产品，不应强依赖 OpenClaw

2. 连接管理逻辑不复杂，Go 标准库就够

3. 后续如果想接入 OpenClaw 生态，写一个薄 adapter 把 Relay API 包装成 OpenClaw Tool 即可

两个方案不互斥——先有独立 Relay，再用 adapter 接入 OpenClaw 是最灵活的路径。

9.4 完整数据流

以用户在手机上对小虾说"帮我在电脑上跑 npm install"为例：

1. 用户消息 → 小虾 Hosting API
2. Hosting → LLM Proxy → LLM 推理
3. LLM 返回 tool_call: { "method": "exec", "command": "npm install" }
4. Hosting → Relay 内部 API: POST /agents/{id}/exec
5. Relay → WebSocket → xiaoxia-agent (用户电脑)
6. Agent 权限检查 → L2 白名单匹配 → 自动放行（或弹确认）
7. Agent 执行命令，流式返回输出
8. Relay → Hosting → LLM（读取输出，生成回复）
9. Hosting → 用户手机: "✅ npm install 完成，安装了 127 个包"

10. 与 OpenClaw 的关系

10.1 技术复用

小虾 Agent 和 OpenClaw Node 解决的是同一类问题。可以考虑：

• Agent 协议兼容 OpenClaw Node Protocol（让 OpenClaw 用户也能用小虾 Agent）
• 共享 GUI 自动化库（屏幕截图、OCR、点击）
• 审批模型可以直接参考 OpenClaw 的 exec-approvals

10.2 差异化

11. 实施计划

10.1 MVP 时间线

总计：~6-8 周 到功能完整版

10.2 优先级

1. v0.1 是关键：验证 WebSocket 通信 + 权限模型 + 基础执行

2. v0.2 提升体验：有 GUI 才像个正经产品

3. v0.3-v0.5 按需求排：看用户反馈决定优先级

10.3 开源策略

• Agent 端完全开源（MIT License）
• 云端控制面不开源（商业核心）
• 通信协议公开文档（第三方可以实现自己的 agent）

12. 总结

关键设计决策

1. Go 单二进制：<10MB，零依赖，三平台

2. WebSocket 出站连接：NAT 友好，零配置

3. 三级权限 + 逐操作确认：比 Manus 透明 10 倍

4. Agent 端开源：信任基础，竞品做不到

5. 本地执行免费：只收云端 LLM 推理费用

与 Manus 的护城河

Manus 有先发优势和 Meta 资源，但小虾可以在三个方面赢：

1. 价格：$5/月 vs $39/月

2. 透明度：开源 agent + 逐操作计费

3. 轻量级：8MB vs 200MB

下一步

• [ ] 写 xiaoxia-agent Go 骨架（WebSocket + exec/read/write）
• [ ] 设计配对码生成和验证 API
• [ ] 在小虾控制面加 "设备管理" 页面
• [ ] 内测：先用自己的 Mac mini 测试

参考链接

• Manus Desktop App 深度报告 — 我们的 Manus 分析
• OpenClaw Node 文档 — 现有 Node 协议参考
• Go systray 库 — 跨平台系统托盘
• JSON-RPC 2.0 规范
• gorilla/websocket — Go WebSocket 库
• Manus 官网 — 竞品参考