# AI agent手机监控

**Repository Path**: hades00/mobile_monitor

## Basic Information

- **Project Name**: AI agent手机监控
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-04-29
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mobile Monitor

> 把桌面 AI Agent 的"思考与工具调用"实时投到你手机上，并在高危操作前远程审批。

**Mobile Monitor** 是一套 **桌面端 ↔ 移动端** 的实时监控与控制系统：桌面端运行基于 OpenCode SDK 的 AI Agent，移动端通过 WebSocket 订阅推理事件流，看 Agent 在做什么、给它发指令、远程批准它请求的高危工具权限。

```
┌──────────────────┐    LAN / Relay    ┌──────────────────┐
│   Desktop (Host) │  ◀──────────────▶ │  Mobile (Client) │
│  OpenCode Agent  │  thinking / tool  │   Flutter App    │
│  + Auth + WS Hub │   permission_req  │  Riverpod + WS   │
└──────────────────┘                   └──────────────────┘
```

---

## 核心能力

- **实时事件流**：thinking / message / tool_call / session 状态，端到端 P95 延迟 LAN < 50ms、中继 < 200ms
- **远程权限审批**：Agent 调用高危工具时，手机弹出操作栏，选择 仅一次 / 本次会话 / 永久
- **远程发起任务**：移动端发 prompt 与快捷命令（`/plan` `/build` `/init` `/revert`）
- **断线 resume**：基于 seq 的环形缓冲，弱网切网后无丢消息
- **零信任配对**：7 位配对码 + 桌面端二次确认，30 天 RefreshToken 旋转，单设备可一键吊销
- **隐私优先**：中继不解密业务报文；事件默认本机存储；30 天可配置保留期

---

## 5 分钟快速上手

### 1. 启动后端

```bash
cd backend
npm install
npm run dev          # http://localhost:7443
open http://localhost:7443/docs    # Swagger UI
```

**环境变量（常用）**

| 变量 | 说明 |
| ---- | ---- |
| `OPENCODE_MODE` | `mock`（默认，可跑通事件流+权限）或 `real` + 适配模块 |
| `OPENCODE_MODULE` | 动态 `import()` 的适配包路径，导出 `createOpencodeRealHandler` |
| `NETWORK_MODE` | `lan` / `relay` / `both`；非 `lan` 且配置 `RELAY_URL`+`RELAY_TOKEN` 时桌面会反向连 relay |
| `RELAY_URL` | 如 `ws://VPS:8787`（与 relay 服务同端口） |
| `RELAY_TOKEN` | 与 relay 进程 `RELAY_TOKEN` 相同 |
| `RELAY_DEVICE_ID` | 配对后设备的 UUID；不填则取库中首个 active 设备 |
| `JWT_SECRET` | 生产务必固定，否则重启后 token 全部失效 |

### 2. 生成配对码

```bash
curl -X POST http://localhost:7443/api/admin/pair-code
# => { "pair_code": "1234567", "expires_in": 120 }
```

### 3. 启动移动端

```bash
cd mobile
flutter pub get
flutter run --dart-define=API_BASE_URL=http://10.0.2.2:7443/api
# 或 mock 模式（无需后端）：
flutter run --dart-define=USE_MOCK=true
```

输入服务器地址 + 配对码，桌面端确认"允许接入" → 进入监控页。

> 完整流程图与最小验证脚本：[`docs/guides/user-quickstart.md`](./docs/guides/user-quickstart.md)

---

## 系统架构

```mermaid
flowchart LR
    subgraph Desktop["Desktop (Host)"]
        SDK[OpenCode SDK<br/>Agent]
        WS[WS Hub<br/>:7443 TLS]
        Auth[Auth + Pair]
        DB[(SQLite<br/>WAL)]
        SDK --> WS
        Auth --> DB
        WS --> DB
    end

    subgraph Cloud["Relay (Optional)"]
        Relay[WSS Relay<br/>不解密报文]
        Redis[(Redis Pub/Sub)]
        Relay --> Redis
    end

    subgraph Mobile["Mobile (Client)"]
        App[Flutter App<br/>Riverpod + go_router]
        RT[RealtimeClient<br/>seq + resume]
        App --> RT
    end

    Desktop -- "WSS LAN (mDNS)" --> Mobile
    Desktop -. "WSS fallback" .-> Relay
    Mobile  -. "WSS fallback" .-> Relay
```

**网络选路**：默认 LAN 直连（mDNS 发现），不可达自动回退中继；视频流在 v1.2 接入 WebRTC P2P。
**协议**：单连 WS 上承载控制信令 + 事件流，单调 seq + 累积 ACK + 环形缓冲实现 resume。
详细设计：[`docs/architecture/`](./docs/architecture/)

---

## 仓库结构

```
mobile_monitor/
├── backend/              桌面端后端：Fastify + WS + SQLite
│   ├── src/{routes,ws,store,plugins}
│   ├── migrations/       生产 schema (001_init.sql)
│   └── test/             smoke test
├── mobile/               Flutter 应用
│   └── lib/
│       ├── core/         config/network/websocket/router/storage
│       ├── features/     auth, control, monitor, sessions, settings
│       ├── shared/       通用组件 + 主题
│       └── mock/         USE_MOCK=true 时启用
├── tests/mock-server/    桩 server（弱网/断线场景）
└── docs/                 全部文档
```

---

## 文档地图

| 你是…… | 推荐入口 |
| ------ | -------- |
| 第一次用 | [快速上手](./docs/guides/user-quickstart.md) → [完整使用手册](./docs/guides/user-manual.md) |
| 要部署到外网 / HTTPS | [部署指南](./docs/guides/deployment.md) |
| 后端 / 移动端开发者 | [开发环境搭建](./docs/guides/dev-setup.md) → [贡献指南](./docs/guides/contributing.md) |
| 想看协议 / 架构 | [系统架构总览](./docs/architecture/overview.md) → [WS 协议](./docs/architecture/05-websocket-protocol.md) → [认证设计](./docs/architecture/16-auth-design.md) |
| 后端集成 | [OpenAPI 3.1](./docs/api/openapi.yaml) · Swagger UI `/docs` |
| 出问题了 | [开发者排查](./docs/guides/troubleshooting.md) · [使用故障排查](./docs/troubleshooting.md) |

完整文档索引见 [`docs/README.md`](./docs/README.md)。

---

## 技术栈

| 端 | 选型 |
| -- | ---- |
| 后端 | Node.js 20 LTS · Fastify 4 · `@fastify/jwt` · `@fastify/websocket` · SQLite 3.45（WAL/FTS5/JSON1） |
| 移动端 | Flutter 3.22 · Dart 3.4 · Riverpod 2.5 · go_router 14 · dio 5 · web_socket_channel 3 · Hive · flutter_secure_storage |
| 中继（可选） | 见 [`relay/`](./relay/) · Node `ws` 透传 + `GET /health`（Redis 为后续横向扩展） |
| 测试 | node:test + Testcontainers · flutter_test + mocktail · integration_test + Patrol |

选型依据见 [`docs/mobile-tech-stack-decision.md`](./docs/mobile-tech-stack-decision.md)。

---

## 项目状态

当前版本 **v0.1.0-draft**。详见 [`CHANGELOG.md`](./CHANGELOG.md)。

| 模块 | 状态 |
| ---- | ---- |
| 设计文档（认证 / 网络 / WS 协议 / 持久化） | ✅ |
| OpenAPI 3.1 + SQL migration | ✅ |
| RESTful API（pair / auth / sessions / commands） | ✅ |
| WebSocket 实时通道 + OpenCode mock 桥 | ✅ 桌面侧 |
| OpenCode 真实 SDK | 🔧 设置 `OPENCODE_MODE=real` 与 `OPENCODE_MODULE` 适配器 |
| 移动端：技术栈 + 共享组件 + Mock | ✅ |
| 移动端：配对 / 监控 / 控制 / 会话列表 / 设置 页面 | 🚧 部分完成 |
| 自动化测试 / 性能稳定性测试 | 🚧 准备中 |
| 中继服务（MVP 透传） | ✅ [`relay/`](./relay/) |
| WebRTC P2P 视频流 | ⏳ v1.2 |

---

## 贡献

欢迎提 PR！请先读 [`docs/guides/contributing.md`](./docs/guides/contributing.md)（详细版本）了解：

- 分支与 Conventional Commits 规范
- PR 模板与 Code Review 标准
- 协议 / Schema 变更的同步要求

安全漏洞请勿在公开 Issue 提交，发邮件至 `security@example.com`。

---

## License

MIT — 详见 [`LICENSE`](./LICENSE)。