# Manus AI 1.4.1 后端架构完整逆向报告

> 通过逆向桌面客户端（Electron + asar 解包）和 sidecar 二进制（Go strings 分析）还原

---

## 一、整体架构

```
用户 ──► Manus 桌面客户端 (Electron)
              │
              ├── 前端 (Next.js 静态导出, Redux)
              │     │
              │     └── Connect-Web (Protobuf over HTTP POST)
              │           │
              │           ▼
              │     api.manus.im ──► Go 后端 (sdk-bizserver-go)
              │           │
              │           ├── FileService (S3 预签名)
              │           ├── ImageService (OCR + AI 生图)
              │           ├── OrchestratorSandboxService (邮件)
              │           ├── TelecomService (短信/电话)
              │           ├── PromotionService (促销码)
              │           ├── BrowserDataService (浏览器数据)
              │           └── ...12+ gRPC 服务
              │
              ├── Socket.IO (3 条 WebSocket 连接)
              │     ├── /socket.io        ──► 主聊天 (Agent 对话)
              │     ├── /notifier-v2-socket-io ──► 通知推送
              │     └── /meeting.io       ──► 语音/STT
              │
              └── sidecar (Go 本地代理)
                    │
                    └── ws://127.0.0.1:19780/sidecar (Protobuf over WS)
                          ├── Sandbox 协议 (文件系统 CRUD)
                          └── Terminal 协议 (PTY 远程终端)

云端沙箱: manus.computer (microVM/Firecracker)
  ├── VNC 远程桌面 (Neko WebRTC)
  ├── VS Code Server (OTP 认证)
  └── Web 开发服务器
```

## 二、域名体系

### 生产环境
| 域名 | 用途 |
|------|------|
| `api.manus.im` | API + WebSocket + gRPC |
| `manus.im` | 主站 |
| `manus.computer` | 沙箱环境 |
| `manus.space` | 部署平台 |
| `manus-preview.space` | 预览部署 |
| `pages.manus.im` | Pages |
| `download.manus.im` | 客户端下载/自动更新 |
| `files.manuscdn.com` | CDN |
| `metrics.manus.im` | Umami 分析 |
| `open.manus.ai` | 开放 API 文档 |
| `sentry.prod.ops.butterfly-effect.dev` | Sentry 错误监控 |
| `cname.manus.space` | 自定义域名 CNAME |
| `104.18.26.246` / `104.18.27.246` | Cloudflare 自定义域名 A 记录 |

### 开发环境
| 域名 | 用途 |
|------|------|
| `vidabiz.butterfly-effect.dev` | RPC + 通知 WebSocket |
| `localhost:4000` | 聊天 WebSocket |
| `localhost:4001` | STT WebSocket |
| `manuspre.computer` | 预发沙箱 |
| `mircovm.com` | microVM 域名（拼写错误暴露了技术栈） |

**母公司代号**: butterfly-effect.dev（蝴蝶效应）

## 三、REST API 完整列表

### Chat API (`/api/chat/`)

| 方法 | 路由 | 参数 | 说明 |
|------|------|------|------|
| GET | `/api/chat/getSessionV2` | sessionId, type?, startSegmentEndpoint?, endSegmentEndpoint? | 获取会话（分段加载） |
| GET | `/api/chat/getSession` | sessionId, type?, sig?, startEventId? | 获取会话 |
| POST | `/api/chat/deleteSession` | sessionId | 删除会话 |
| GET | `/api/chat/getSessionFilesV2` | sessionId, type?, sig?, startEventId? | 获取会话文件 |
| POST | `/api/chat/getPresignedUploadUrl` | filename, fileType, fileSize, id? | 获取 S3 预签名上传 URL |
| POST | `/api/chat/uploadComplete` | id, filename, fileSize | 上传完成通知 |
| POST | `/api/chat/getDownloadUrl` | signedCdnUrl | 获取下载 URL |
| POST | `/api/chat/requestVncOtp` | sessionId | VNC OTP（返回 nekoOtp: {username, webrtc_token}） |
| POST | `/api/chat/requestVsCodeOtp` | sessionId | VS Code OTP |
| POST | `/api/chat/startVsCodeServer` | sessionId | 启动 VS Code Server |
| POST | `/api/chat/scheduleTask` | sessionId, userId, detail, title, uid, locale... | 创建定时任务 |
| GET | `/api/chat/getSandboxStatus` | sandboxUrl, sessionId | 沙箱状态 |
| POST | `/api/chat/startSandbox` | sessionId?, sandboxUrlHost?, force? | 启动沙箱 |
| POST | `/api/chat/wakeMobilePreview` | sessionId, projectId | 唤醒移动预览 |
| GET | `/api/chat/getMobilePreviewStatus` | sessionId, projectId | 移动预览状态 |
| GET | `/api/chat/getOnlineMyBrowserClients` | - | 在线浏览器客户端列表 |
| GET | `/api/chat/getMapReduceTool` | sessionId, actionId | MapReduce 工具详情 |

### Internal API (`/api/internal/`)

| 方法 | 路由 | 参数 | 说明 |
|------|------|------|------|
| POST | `/api/internal/resetDailyQuota` | userId?, email?, password?, quota?, expirationSeconds?, whitelistOp? | 重置每日配额 |
| POST | `/api/internal/fixUrlMeta` | sessionId, password? | 修复 URL 元数据 |

### 其他 API

| 方法 | 路由 | 说明 |
|------|------|------|
| POST | `/api/user_behavior/batch_create_event_v2` | 用户行为批量上报 |
| GET | `/api/website_tool/fetch_website_favicon?host=` | 获取网站 favicon |

## 四、gRPC/Connect 服务完整列表

后端仓库：`github.com/manus-ai/sdk-bizserver-go`

### FileService (`file/v1/file.proto`)
- `SignUrl()` — 签名 URL
- `BatchSignUrl()` — 批量签名
- `SandboxSignUrl()` — 沙箱文件签名
- `SandboxSignPrivateUrl()` — 沙箱私有文件签名
- 存储桶模块：SESSION_FILE, SESSION_FEEDBACK, MARKDOWN, ANONYMOUS, SLIDE_TEMPLATE, SLIDE_IMAGE, WEB_DEV_LOGO, PROJECT, SESSION_CANVAS

### ImageService (`bizimage/v1/bizimage.proto`)
- `OCR()` — OCR 文字识别
- `GenerateImage()` — AI 图片生成
- `MarkGenerateImage()` — 标记式图片生成
- 模型：FLUX_KONTEXT_PRO, FLUX_KONTEXT_MAX, GEMINI_2_5_FLASH_IMAGE_PREVIEW, GPT_IMAGE_1, QWEN_IMAGE_EDIT, GEMINI_3_PRO_IMAGE_PREVIEW

### OrchestratorSandboxService (`orchestrator/v1/orchestrator_sandbox.proto`)
- `SandboxSendEmail()` — 从沙箱发邮件
- `SandboxListSessionEmails()` — 列出邮件
- `SandboxGetEmail()` — 获取邮件详情
- `SandboxGetEmailFileDownloadUrl()` — 邮件附件下载

### TelecomService (`telecom/v1/telecom.proto`)
- `SendSMS()` / `ListSmsMessages()` / `ListUserPhoneNumbers()`
- `ConfigureSmsCallback()`
- `MakeCall()` / `ListSessionCalls()` / `GetCall()` / `GetCallFileDownloadUrl()`

### PromotionService (`promotion/v1/promotion.proto`)
- `RedeemPromotionCode()` / `RedeemPromotionCodeV2()`
- `LoopPromotionCodeRedeemStatus()`

### BrowserDataService (`manus_browser/v1/manus_browser.proto`)
- `ListBrowserData()` / `DeleteBrowserData()`

### UserApiProxyService (`user_apiproxy/v1/user_apiproxy.proto`)
- `AudioTranscription()` — 音频转写

### OpenapiInternalService (`openapi/v1/openapi_intenal.proto`)
- `OnTaskCreatedCallback()` / `OnTaskStoppedCallback()` / `OnTaskProgressCallback()`

### EnterprisePreferenceAdminService (`enterprise/v1/enterprise_admin.proto`)
- `GetTeamPreference()` / `UpdateTeamPreference()`

### TeamDomainBlacklistService (`team/v1/team_domain_blacklist.proto`)
- `SaveDomainBlacklist/Whitelist()` / `ListDomainBlacklist/Whitelist()` / `CheckDomainAccess()`

## 五、WebSocket 消息协议

### 连接端点

| 用途 | URL | Socket.IO Path |
|------|-----|----------------|
| 主聊天 | wss://api.manus.im | /socket.io (默认) |
| 通知 | wss://api.manus.im | /notifier-v2-socket-io |
| 语音 | wss://api.manus.im | /meeting.io |

### 连接参数
```
query: {
  token: "用户认证令牌",
  locale: "zh-CN",
  tz: "Asia/Shanghai",
  clientType: "desktop"
}
transports: ["websocket"]
```

### 客户端发送的消息

**加入会话:**
```json
{
  "type": "join_session",
  "id": "<uuid>",
  "sessionId": "<session_id>",
  "lastMessageId": "<event_id>",
  "timestamp": 1234567890,
  "version": 2
}
```

**用户消息:**
```json
{
  "type": "event",
  "id": "<uuid>",
  "sessionId": "<session_id>",
  "timestamp": 1234567890,
  "messageStatus": "pending",
  "event": {
    "type": "chat",
    "sender": "user",
    "id": "<uuid>",
    "messageType": "text",
    "content": "用户消息内容",
    "contents": [],
    "attachments": [],
    "taskMode": "...",
    "extData": {}
  }
}
```

### 服务端推送的事件类型

#### Agent 核心事件
| 事件 | 说明 |
|------|------|
| `statusUpdate` | Agent 状态更新（agentStatus: running/stopped/waiting/error） |
| `toolUsed` | 工具使用完成 |
| `newPlanStep` | 新计划步骤 |
| `chat` | 聊天消息 |
| `chatDelta` | 流式增量 |
| `explanation` | 思考过程 |
| `planUpdate` | 计划更新 |
| `queueStatusChange` | 排队状态 |

#### 会话管理
| 事件 | 说明 |
|------|------|
| `session_joined` | 加入会话 |
| `session_left` | 离开会话 |
| `agent_error` | Agent 错误 |
| `collaborationStatusUpdate` | 协作状态 |
| `eventsNotifyEventsAfter` | 事件同步 |

#### WebDev 事件
| 事件 | 说明 |
|------|------|
| `webdevGitSyncCheckResult` | Git 同步检查 |
| `webdevCreateGitRepoResult` | 创建仓库结果 |
| `webdevHomepageUpdated` | 主页更新 |

#### 媒体/文件事件
| 事件 | 说明 |
|------|------|
| `speechGenerationUpdate` | 语音生成 |
| `videoGenerationUpdate` | 视频生成 |
| `terminalUpdate` | 终端更新 |
| `resourceAccessed` | 资源访问 |

#### 桌面/设备/通知
| 事件 | 说明 |
|------|------|
| `desktopDevicesUpdate` | 设备列表更新 |
| `desktopSessionConfig` | 会话配置 |
| `connectorOauthExpired` | OAuth 过期 |
| `mcpAuthorizationNotify` | MCP 授权 |
| `contextTooLong` | 上下文过长 |
| `contextTransferFlag` / `contextTransferResult` | 上下文迁移 |

## 六、Agent 工具定义

| 工具 | 子工具/操作 | 说明 |
|------|------------|------|
| `browser` | navigate, console_exec, console_view, save_image | 浏览器控制 |
| `my_browser` | - | 用户浏览器代理 |
| `computer_use` | - | 计算机操作 |
| `terminal` | - | 终端命令 |
| `text_editor` | webdev-file-edit, webdev-debug, slides | 文本编辑 |
| `search` | - | 网页搜索 |
| `search_scholar` | - | 学术搜索 |
| `search_image` | - | 图片搜索 |
| `media_viewer` | 图片生成, 视频生成 | 媒体 |
| `webdev` | init_project, check_status, save/rollback_checkpoint, restart_server, debug | Web 开发 |
| `map_reduce` | - | 并行任务 |
| `slides` | - | 幻灯片 |
| `gmail` / `google_calendar` | - | Google 集成 |
| `outlook_mail` / `outlook_calendar` | - | Outlook 集成 |
| `meta_marketing` | - | Meta 营销 |
| `suggestion` | - | 建议 |
| `task_scheduled` | - | 定时任务 |
| `need_accept` | - | 需要用户确认 |

工具状态: `start` → `argumentsFinished` → `streaming` → `success` / `error` / `fallback`

## 七、Sidecar 本地代理

### 基本信息
- **语言**: Go 1.26.0
- **大小**: 12.4 MB (arm64)
- **源码仓库**: `manus-sandbox/sbx-go-svc/packages/sidecar/`
- **开发者**: chenqiang

### 连接方式
本地 WebSocket: `ws://127.0.0.1:19780/sidecar` (Protobuf over WebSocket)

### 三层协议

**Bridge 层** (信封):
- `Envelope_Sandbox` → 文件系统操作
- `Envelope_Terminal` → 终端操作

**Sandbox 协议** (文件系统):
| 操作 | 说明 |
|------|------|
| Mount | 注册挂载路径 |
| Stat | 获取文件信息 |
| ReadDir | 读取目录 |
| ReadFile | 读取文件 |
| WriteFile | 写入文件 |
| CreateFile | 创建文件 |
| MkDir | 创建目录 |
| Remove | 删除 |
| Rename | 重命名 |
| Truncate | 截断 |

**Terminal 协议** (远程终端):
- PTY 伪终端分配
- Shell 查找 (zsh/bash/sh)
- 命令执行 + 输出读取
- Prompt 检测标记: `__MANUS_PROMPT__`
- 支持: sendLine, sendKey, sendControl, sendInterrupt, killProcess

## 八、沙箱实现

- **技术**: microVM（域名 `mircovm.com` 泄露，可能 Firecracker）
- **远程桌面**: Neko (WebRTC)，OTP 认证
- **VS Code**: 每个沙箱独立 VS Code Server
- **沙箱保留天数**: Free=1天, Lite=3天, Pro=3天, Team=7天（最高10天）
- **沙箱状态**: starting → running → pausing → paused → resuming → stopped → deleting → deleted

## 九、第三方集成密钥

| 服务 | Key |
|------|-----|
| Cloudflare Turnstile | `0x4AAAAAAA_sd0eRNCinWBgU` |
| hCaptcha | `7b4c0ca8-0e48-47b8-82de-6c1a5f7e0e16` |
| Google Drive | `1073362082968-a8ind2sh24p7c41svhvgof1bht9me0eo` |
| Google Maps | `AIzaSyDcXHo-1cHpFHPMlBDoMHnvI6r00_XkNKg` |
| FingerprintJS | `nG226lNwQWNTTWzOzKbF` |
| Amplitude | `46ac3f9abb41dd2d17a5785e052bc6d3` |
| Intercom | `k7n2hgls` |
| Facebook Pixel | `1383830073227216` |
| GTM | `GTM-TFGFC7KH` |

## 十、套餐体系

| 套餐 | 最大并发任务 | 最大定时任务 | 沙箱保留天数 |
|------|-------------|-------------|-------------|
| Free | 1 | 2 | 1 |
| Lite | 2 | 2 | 3 |
| Casual | 20 | 20 | 7 |
| Pro | 3 | 3 | 3 |
| Team | 20 | 20 | 7 |

## 十一、MCP Connector 系统

支持用户自定义 MCP 连接器:
- `MCP_TRANSPORT_TYPE_STDIO` — 命令行 (command + args + env)
- `MCP_TRANSPORT_TYPE_HTTP` — HTTP (serverUrl + customHeaders)
- `MCP_TRANSPORT_TYPE_SSE` — SSE (serverUrl + customHeaders)
- BYOK (Bring Your Own Key) 配置

## 十二、后端技术栈推断

| 组件 | 技术 |
|------|------|
| 后端语言 | Go |
| RPC 框架 | Connect (connectrpc.com) |
| 序列化 | Protobuf |
| 实时通信 | Socket.IO |
| 沙箱 | microVM (可能 Firecracker) |
| 远程桌面 | Neko (WebRTC) |
| 对象存储 | S3 兼容 + CloudFront CDN |
| 前端 | Next.js + Redux Toolkit |
| 桌面端 | Electron |
| sidecar | Go + gorilla/websocket + creack/pty |
| 监控 | Sentry + Amplitude + Umami |
| CDN | Cloudflare (104.18.x.x) |
| 支付 | Stripe |
| 人机验证 | Cloudflare Turnstile + hCaptcha |