# Mira Gateway 安装手册（给 Agent 执行）

> **你的任务**：在用户的 Mac 上安装并启动 Mira Gateway，让 Mira 手机 App 能连接
> MiMo Desktop。完成后把**配对码**发回给用户——用户在手机上输入它即完成绑定。
>
> **完成的定义**：状态接口 `desktop` 与 `bridge` 两项均为 true，且配对码已交到用户手里。

## 0. 背景（30 秒读懂）

```text
用户的 Mac：MiMo Desktop（AI 编程助手，跑着引擎）
      ↕ 你即将安装的 Mira Gateway（本机常驻服务 + Desktop 插件薄桥）
用户的手机：Mira App（看会话 · 发消息 · 远程审批）
```

Gateway 只在局域网内工作（默认），不暴露公网。**它持有的令牌可代表用户在 Mac 上
执行命令——全程不要把令牌贴到任何公开位置。**

## 1. 前置检查

逐条执行，任何一条不满足就停下问用户，不要硬装：

```bash
sw_vers                          # macOS 13+
node -v                          # Node.js ≥ 20
python3 --version                # Python 3（安装脚本用）
git --version
ls "/Applications/Xiaomi MiMo.app"   # MiMo Desktop 已安装
```

再确认 MiMo Desktop **已登录且能正常对话**（问用户一句即可）。

## 2. 安装

```bash
# 2.1 取源码（位置随意，建议 ~/XiaomiMiMoProjects/Mira）
git clone https://github.com/Jinhan000/Mira.git ~/XiaomiMiMoProjects/Mira
cd ~/XiaomiMiMoProjects/Mira

# 2.2 一键安装（幂等，可重复执行）
chmod +x MiraGateway/install-to-desktop.sh
./MiraGateway/install-to-desktop.sh
```

脚本会自动完成：生成双令牌（手机用 `publicToken` / 插件通信用 `bridgeToken`，写入
`~/.config/mimocode/mira-gateway.json`）→ 把薄桥写进 Desktop 插件声明
（`engine-config/mimocode.jsonc`）→ 用 `launchd` 常驻守护进程（`com.max.mira-gateway`）→ 自检。

**脚本末尾的「验证: /api/status → HTTP 200」此刻可能失败**（Desktop 还没重启、桥未加载），
这是预期的，继续下一步。

## 3. 重启 MiMo Desktop

让薄桥随引擎加载（插件只在启动时装载）：

```bash
osascript -e 'quit app "Xiaomi MiMo"' && sleep 2 && open -a "Xiaomi MiMo"
```

⚠️ 告知用户：重启会中断 Desktop 里正在跑的任务，挑个空档执行。

## 4. 验证（三关全过才算装好）

```bash
# 4.1 守护活着？
launchctl print "gui/$(id -u)/com.max.mira-gateway" | grep -E "state|pid"

# 4.2 双灯状态（从状态文件取 token）
TOK=$(python3 -c "import json;print(json.load(open('$HOME/.config/mimocode/mira-gateway.status.json'))['token'])")
curl -sS "http://127.0.0.1:7788/api/status?token=$TOK"
# 期望：desktop.online=true 且 desktop.bridge=true（bridge 需 Desktop 已重启）
```

**桥为 false 的处理**：再等 10 秒重试 → 仍 false 则确认 Desktop 确实重启过 → 看
`~/.config/mimocode/mira-gateway.log` 尾部报错，按第 6 节排障。

```bash
# 4.3 手机可达？在 Mac 上看局域网 IP，把 URL 发给用户：
ipconfig getifaddr en0 || ipconfig getifaddr en1
# 形如 http://192.168.x.x:7788/（手机需连同一 Wi-Fi）
```

## 5. 生成配对码（最后一步，交回用户）

对 MiMo Desktop 说一句：**「生成配对码」**（或在你自己的会话里调用工具
`mira_pairing_code`）。会得到：

- 6 位配对码（10 分钟内有效，单次使用）
- 可扫码/点开的链接

把**配对码 + 链接**发回用户。用户在 Mira App 的配对页输入即可完成绑定。

## 6. 排障速查

| 症状 | 原因与处置 |
|---|---|
| 安装脚本报「连续 5 个端口被占用」或验证 000 | 7788 被占：`lsof -iTCP:7788` 查占用者；多为旧版网关，停掉即可 |
| `desktop.bridge` 一直 false | Desktop 没重启，或插件声明未生效：重跑第 2.2 步再重启 Desktop |
| curl 401 | token 不对：用 `~/.config/mimocode/mira-gateway.status.json` 里的 `token` |
| 手机打不开 URL | 不在同一 Wi-Fi / macOS 防火墙拦了 node：系统设置 → 网络 → 防火墙 → 允许 `node` |
| 守护没跑 | `launchctl kickstart -k "gui/$(id -u)/com.max.mira-gateway"`；日志在 `~/.config/mimocode/mira-gateway.log` |
| 审批卡片手机看不到 | 手机 App 保持前台连着即可实时；杀掉 App 重开 |

## 7. 安全边界（务必转告用户）

- **token = Mac 的钥匙**：拿到它就能代表用户执行命令。只存在手机与
  `~/.config/mimocode/mira-gateway.json` 里，不进聊天记录、不进截图、不进公开仓库。
- 默认**仅局域网**可达。要公网远程须走 Cloudflare Tunnel / VPN 之类加密通道，
  **严禁把 7788 端口直接映射公网**。
- 不再使用时按第 8 节卸载，令牌随配置一并删除。

## 8. 卸载

```bash
launchctl bootout "gui/$(id -u)/com.max.mira-gateway"
rm ~/Library/LaunchAgents/com.max.mira-gateway.plist
# 从 Desktop 插件声明（engine-config/mimocode.jsonc）里移除 mira-bridge 条目
rm ~/.config/mimocode/mira-gateway.json ~/.config/mimocode/mira-gateway.status.json
```

---

## 故障回报

装不上时，把以下三样发给用户（由用户转给维护者）：

```bash
tail -30 ~/.config/mimocode/mira-gateway.log
cat ~/.config/mimocode/mira-gateway.status.json   # 其中 token 请打码
node -v && sw_vers
```