🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
Sign In

@justprove/mobilevc

Package Overview
Dependencies
Maintainers
1
Versions
32
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@justprove/mobilevc - npm Package Compare versions

Comparing version
0.2.9
 to
0.2.10
+6
-6
package.json
{
"name": "@justprove/mobilevc",
"version": "0.2.9",
"version": "0.2.10",
"description": "Claude Code mobile workspace launcher with precompiled MobileVC backend binaries.",

@@ -33,8 +33,8 @@ "license": "MIT",

"optionalDependencies": {
"@justprove/mobilevc-server-darwin-arm64": "0.2.9",
"@justprove/mobilevc-server-darwin-x64": "0.2.9",
"@justprove/mobilevc-server-linux-arm64": "0.2.9",
"@justprove/mobilevc-server-linux-x64": "0.2.9",
"@justprove/mobilevc-server-win32-x64": "0.2.9"
"@justprove/mobilevc-server-darwin-arm64": "0.2.10",
"@justprove/mobilevc-server-darwin-x64": "0.2.10",
"@justprove/mobilevc-server-linux-arm64": "0.2.10",
"@justprove/mobilevc-server-linux-x64": "0.2.10",
"@justprove/mobilevc-server-win32-x64": "0.2.10"
}
}
+111
-469
README.md

@@ -8,12 +8,12 @@ # 📱 MobileVC — 手机就是你的 AI 编程助手控制台

<p align="center">
<strong>摆脱键盘和鼠标的束缚，用手机随时接管电脑上的 AI 编程助手（Claude / Codex）。</strong>
<strong>摆脱键盘和鼠标，用手机直接接管电脑上的 Claude / Codex 会话。</strong>
</p>
<p align="center">
<em>MobileVC 把 AI 助手会话中的等待、审批、审核和继续执行，变成一套专为移动端设计的操作闭环。</em>
<em>MobileVC 把等待、审批、审核和继续执行，整理成一套适合手机操作的闭环。</em>
</p>
<p align="center">
<img src="https://img.shields.io/badge/Go-1.21-blue" />
<img src="https://img.shields.io/badge/Flutter-3.13-blue" />
<img src="https://img.shields.io/badge/Go-1.25-blue" />
<img src="https://img.shields.io/badge/Flutter-3.41-blue" />
<img src="https://img.shields.io/badge/License-MIT-green" />

@@ -28,3 +28,3 @@ <img src="https://img.shields.io/npm/v/%40justprove%2Fmobilevc" />

<p align="center">
快速访问：<a href="https://www.mobilevc.top">mobilevc.top</a>
<strong>手机安装：</strong><a href="https://www.mobilevc.top">官网首页</a>（iOS 走 TestFlight，Android 走 APK 下载）
</p>

@@ -38,34 +38,36 @@

## 🚀 快速开始
## 这是什么
### 一键安装启动（推荐）
MobileVC 不是远程桌面，也不是终端镜像。它把电脑上正在运行的 AI 助手 CLI 会话带到手机上，让你在离开电脑时继续推进任务：
- 接住权限请求
- 推进 Plan Mode
- 审核 diff
- 恢复历史会话
- 浏览文件、日志和运行状态
- 管理 Skill / Memory / Context
---
## 快速开始
### 一键安装启动
```bash
# 1. 全局安装
npm install -g @justprove/mobilevc
# 2. 启动服务（首次会引导配置）
mobilevc start
# 3. 访问 Web 端
# 浏览器打开 http://localhost:8001
```
启动后会自动显示：
- 本机访问地址
- 局域网访问地址
- 手机扫码连接二维码
首次启动会引导你完成基础配置，并打印本机地址、局域网地址和二维码。
### 移动端连接
> 配置 Token 时，终端输入内容不会显示，这是正常的。直接输入完整 Token 后按回车即可。
**方式一：扫码连接**
1. 手机访问 https://mobilevc.top/install/ 安装客户端
2. 打开客户端，点击"扫码连接"
3. 扫描终端显示的二维码即可
### 手机连接
**方式二：手动配置**
- 局域网：填写终端显示的局域网地址、端口和 Token
- 公网：配置反向代理后填写公网地址
1. 手机访问 [官网首页](https://www.mobilevc.top)
2. iOS 点击 TestFlight 链接安装，Android 点击 APK 下载
3. 打开客户端，使用扫码连接或手动配置
4. 连接成功后，在输入框输入 `claude` 或 `codex`
> **连接成功后**，在输入框输入 `claude` 或 `codex` 即可进入 AI 会话模式，开始与助手对话。
> 官网可能需要国内网络环境访问。如果页面打不开，先切换到国内网络后再安装。

@@ -75,25 +77,19 @@ ### 常用命令

```bash
mobilevc status # 查看服务状态
mobilevc logs # 查看日志
mobilevc logs --follow # 实时日志
mobilevc config # 重新配置
mobilevc stop # 停止服务
mobilevc status
mobilevc logs
mobilevc logs --follow
mobilevc config
mobilevc stop
```
### 公网连接（Relay 模式）
### Relay 模式
不在同一 WiFi 下也能用手机连电脑。MobileVC 提供**官方公网中继服务器**，端到端加密，免费使用。
不在同一 WiFi 下也能连：
```bash
# 安装
npm install -g @justprove/mobilevc
# 启动（LAN + Relay 双模）
mobilevc public --relay wss://relay.mobilevc.top:9443
```
终端会打印配对二维码，手机扫码即可通过 E2EE 加密隧道连接你的电脑。无论你在哪里、手机用什么网络，都能连上。
如果只想走 Relay，不开放局域网：
如果只想走 Relay、不开放局域网：
```bash

@@ -103,243 +99,57 @@ mobilevc public --relay wss://relay.mobilevc.top:9443 --network-exposure-mode relay-only

> **安全说明**：Relay 只转发加密数据包，无法解密你的会话内容。密钥通过扫码（带外）传递，服务器端看不到明文。详见[架构安全分析](docs/guides/relay-deployment.md)。
Relay 只转发加密数据包，服务器看不到明文。密钥通过扫码带外传递。
**自建 Relay（可选）**：如果你需要独立部署中继节点，完整步骤见 [docs/guides/relay-deployment.md](docs/guides/relay-deployment.md)。
自建 Relay 指南见 [docs/guides/relay-deployment.md](docs/guides/relay-deployment.md)。
## Documentation
The root directory now keeps only entry-point docs and release notes. Topic docs live under `docs/`:
- Documentation index: [docs/README.md](docs/README.md)
- Project index: [docs/project-index.md](docs/project-index.md)
- Architecture blueprint: [docs/architecture/blueprint.md](docs/architecture/blueprint.md)
- Current logic notes: [docs/architecture/current-logic.md](docs/architecture/current-logic.md)
- Relay deployment guide: [docs/guides/relay-deployment.md](docs/guides/relay-deployment.md)
- Push setup checklist: [docs/guides/push-integration-checklist.md](docs/guides/push-integration-checklist.md)
- Web embed path: [docs/guides/web-embed-path.md](docs/guides/web-embed-path.md)
- Flutter Web blank screen: [docs/troubleshooting/flutter-web-blank-screen.md](docs/troubleshooting/flutter-web-blank-screen.md)
- Changelog: [CHANGELOG.md](CHANGELOG.md)
---
## 从源码构建（开发者）
## 最近更新
如果你想从源码编译或参与开发：
- `@justprove/mobilevc` 已发布到 `0.2.9`
- 修复了 `mobilevc public --relay` 成功连接一次后，后端停止再重启可能无法重新注册/配对的问题
- Android 安装包已切到 `arm64-v8a`，官网上的 Android 下载入口当前指向 `1.0.0 (20260531 arm64)`
- iOS Release / Profile 的 Archive 签名身份已明确为 `Apple Distribution`
- 移动端新增语音通话预沟通入口，可自配 Voice API / TTS API 后先用语音确认任务，再交给本机 Claude / Codex 执行
```bash
# 克隆仓库
git clone https://github.com/JayCRL/MobileVC.git
cd MobileVC
# 安装依赖
npm install
# 构建 Flutter Web
cd mobile_vc
flutter pub get
flutter build web --release
cd ..
# 同步 Web 构建产物
npm run sync:web
# 启动 Go 后端
AUTH_TOKEN=test go run ./cmd/server
# 或构建二进制
go build -o mobilevc-server ./cmd/server
./mobilevc-server
```
### Flutter 移动端开发
```bash
cd mobile_vc
flutter pub get
flutter run
```
---
## 这是什么
## 主要能力
MobileVC 不是桌面终端的镜像，也不是远程桌面的替代品。
它做的是一件更直接的事：**把电脑上的 AI 助手 CLI 会话变成可以被手机完整操控的工作台。**
你不在电脑前，也能继续把任务推进下去：
- 继续跟助手对话
- 批准或拒绝权限请求
- 接住 Plan Mode 的多轮计划交互
- 审核 diff、接受或回滚修改
- 浏览文件、日志和运行状态
- 恢复历史会话
- 语音通话预沟通，并把确认后的任务交给本机 Claude / Codex
- 继续电脑上的 Claude / Codex 会话
- 处理权限确认和 Plan Mode
- 按组查看并接受或回滚多文件 diff
- 浏览文件、日志、运行态和历史会话
- 管理 Skill / Memory / Session Context
- 在助手需要你时收到推送通知（iOS APNs）
- 接收权限和进度推送
- 可选 TTS
- Android 模拟器调试
MobileVC 解决的不是”怎么远程看见电脑”，而是：
> **怎么让你只靠手机，就能完成电脑上的几乎全部 AI 助手工作流。**
---
## 当前代码态
## 对比定位
当前主线版本：`0.2.0`
整理基线：`2026-04-28` 当前工作区
MobileVC 的定位不是“把终端塞进手机”，而是把 AI 编程助手的高频等待态做成手机上的结构化操作。下面只展示 MobileVC 在这些对比场景里的优势，不评价其他产品优劣。
### 会话链路
| 对比对象 | MobileVC 展示出的优势 |
|---|---|
| Codex-Remote | 同时覆盖 Claude / Codex；本机 npm 后端可控；权限、Plan Mode、diff 审核、Skill / Memory / Context、文件和日志都在同一套移动端工作流里 |
| 传统 SSH / 远程终端工具 | 不需要在小屏幕里操作终端；常见动作变成按钮和卡片；扫码连接、Token 鉴权、通知、状态同步和文件 / diff 查看都围绕 AI 助手场景设计 |
| Happy | 更偏本机私有工作台：Go 后端跑在自己的开发机上，支持 LAN + 官方 Relay，安装可从 npm 开始，并围绕 Claude / Codex 的权限、审查、会话恢复和项目文件流做深度整合 |
- 已接入原生 Claude CLI 会话：扫描 `~/.claude/projects/<cwd>/*.jsonl`，在会话列表显示为”电脑 Claude”，可直接 resume
- 已接入原生 Codex 会话：读取 `~/.codex/state_5.sqlite` 和 `~/.codex/history.jsonl`，在会话列表显示为”电脑 Codex”
- 连接或重连时，如果当前已经选中 session，会自动补发 `session_resume`，并带上 `lastSeenEventCursor` / `lastKnownRuntimeState`
- 切换工作目录时会自动刷新 `session_list`，会话列表跟随当前 cwd
- 历史会话恢复时，可从原生 Claude jsonl 补齐缺失的 assistant 回复
- **会话归属追踪**：`Ownership` 字段在创建时标记 `mobilevc`，桌面 Claude CLI 接管时升级为 `claude-native`，防止切后台误入观察模式
- **运行态锁存器**：`ExecutionActive` 在执行期间锁存为 `true`，切换前后台不再出现”运行中↔等待输入”的状态跳动
### 权限、审核与通知
- 权限规则自动应用已经收敛到后端，前端只负责展示结果
- Claude 权限批准链路直接回写 `control_response`，避免授权后热重启循环；approve 会带回原始 tool input 的 `updatedInput`
- Claude 默认采用官方 `permission-model-auto`
- 用户手动同意和会话/长期规则命中走同一条后端授权写回路径，不再向会话注入“已授权，继续”
- 客户端带着过期 `permissionRequestId` 回来时，后端会重新下发当前待处理权限请求，用户重新点一次即可，不会把旧请求误批准
- 等待权限确认期间，前端抑制后台 snapshot / delta 带来的临时运行态跳动，保持连续的待授权状态
- 普通输入遇到待处理权限请求会被后端拦截，避免把文本写入正在等待结构化权限响应的 Claude stdin
- Diff 查看器支持字符级高亮和 unchanged block 折叠
- 停止中的 UI 有独立 `_isStopping` 状态，banner / 按钮 / 输入框语义一致
- 推送链路已覆盖 APNs、前后台补发和 action-needed 去重
- **后台进度推送**：Agent 思考、工具执行、错误、assistant 回复等事件也触发 APNs 推送，进度类事件 30s 防抖，在线时跳过避免重复
### Web 与发布工具
- `npm run sync:web` 会把 `mobile_vc/build/web/` 同步到 `cmd/server/web/`
- Go 后端实际嵌入的是 `cmd/server/web/`，不再以根目录 `web/` 作为当前 source of truth
- 安装页与发布脚本位于 `mobile_vc/scripts/`，当前仓库已跟踪 iOS OTA、TestFlight 和安装页渲染流程
详细变更历史见 [CHANGELOG.md](CHANGELOG.md)。
---
## 核心价值
## 工作方式
### 1. 为手机重写 AI 助手的交互
手机上的操作不该依赖键盘盲输。MobileVC 把 AI 助手会话的关键等待态拆出来，做成更适合触摸屏的一键动作和可视化面板：
- 普通输入
- 权限确认
- Plan Mode 继续/推进
- 代码审查
- 会话恢复
- 技能 / 记忆管理
### 2. 让你离开电脑也不掉线
你不需要守在桌面前，也不需要回到键盘旁。
- 出门在外也能继续推进任务
- 电脑不在身边也能批准修改
- 助手正在等待你时，手机能立即收到推送通知
- 复杂工作流不会因为离开键盘而中断
### 3. 把工作流做成”点一下就能继续”的手机体验
MobileVC 不是为了展示”能远程看见什么”，而是为了让你真正把事做完，而且做得更快、更直观：
- 看得见：skill 胶囊、memory 卡片、diff 组、日志和运行状态一目了然
- 点得快：启用 / 停用、允许 / 拒绝、接受 / 回滚都能直接点选
- 一键化：一键同步 skill / memory，一句话生成 skill，一句话修改 memory
- 自动化：助手生成结果可自动回写 catalog，并刷新管理面板
- 可视化：当前会话启用项、同步状态、最近同步时间都清楚展示
这是一套为手机设计的 AI 助手控制台。
---
## 主要功能
管 AI 助手会话
- 在手机上连接本机 AI 助手 CLI 会话（Claude / Codex）
- 继续当前任务，而不是重新开始
- 支持创建、切换、加载、删除会话
### 2. 权限确认与 Plan Mode
- 支持权限请求的允许 / 拒绝
- 自动识别已过期或被替换的权限请求，并刷新为当前可确认的请求
- 支持助手进入 Plan Mode 后的多轮计划交互
- 计划、权限、普通输入分流处理
- 移动端用按钮推进流程，不再依赖 CLI 盲输
### 3. 多文件 Diff 审核
- 按修改组查看待审内容
- 在同一组内切换多个文件
- 查看文件内容或 diff
- 支持 accept / revert / revise
- review 操作会自动锁定当前真正待处理的 diff，避免切换文件后误点到旧目标
- 审核决策会发送显式文本指令，对 Claude / Codex 的兼容性更稳定
- 支持一键接受全部待审核 diff
### 4. 文件、日志、运行控制与状态查看
- 浏览项目文件树
- 读取文件内容
- 通过 HTTP 下载文件
- 查看终端执行日志
- 在不同 execution 间切换 stdout / stderr
- 会话执行中可直接从输入栏停止当前运行
- 自动清理终端噪音（`Wall time`、空 `Output:` 报头、重复错误），时间线只保留有效内容
- 查看 runtime info 和 session 历史
### 5. Skill / Memory / Session Context 管理
- Skill 以“胶囊”形式展示，轻点即可执行，长按即可查看详情和修改入口
- Memory 以“卡片”形式展示，内容、启用状态、来源和同步状态一眼可见
- 支持一键同步 skill / memory，和本机助手目录保持一致
- 支持一句话生成 skill、一句话修改 skill / memory
- 结果可自动回写 catalog，并立即刷新管理面板
### 6. 后台提醒与进度推送
- 当助手需要你操作时发送提醒（权限确认、Plan Mode、代码审核、继续输入）
- **进度推送**：Agent 思考中、执行工具、assistant 回复、错误等也会通过 APNs 推送，不再只通知"需要操作"的时刻
- 进度推送 30s 防抖，避免轰炸；WebSocket 在线时自动跳过进度推送（已实时送达）
- 支持前台到后台的过渡排队：`inactive` 状态收到的提醒会在真正进入后台后补发
- 从 `inactive` 恢复到前台时也会补抓一次遗漏提醒，并按内容指纹去重
- Android 初始化时会主动请求通知权限，iOS / macOS 也会同步申请系统通知授权
- iOS / Android 在后台且会话忙碌时会自动开启短时保活，降低关键提醒丢失概率
- 通过 action-needed 信号去重，避免重复打扰
### 7. 可选 TTS
- 支持把助手的关键信息转成语音
- 更适合移动中、通勤中或不方便盯屏的场景
### 8. Android 模拟器调试
- Flutter 端右上角提供 ADB 调试入口
- 后端会自动检测本机 `adb`、`emulator`、可用 AVD 和已连接设备
- 已有在线设备时可直接进入调试，通过 `WebRTC + H264` 实时推送模拟器画面到移动端
- 没有在线设备但存在可用 AVD 时，可在前端直接启动模拟器
- 在移动端点击预览画面会通过 WebRTC DataChannel 即时回传为 `adb tap`
---
## 系统架构
```text
Mobile browser / Flutter app
│
▼
MobileVC Go server
│
├─ WebSocket event stream
├─ Assistant CLI runtime / PTY runner
├─ ADB / Android Emulator + WebRTC(H264) bridge
├─ session + projection store
└─ Python ChatTTS sidecar (optional)
│
▼
MobileVC Go server
│
├─ WebSocket event stream
├─ PTY / assistant runtime
├─ ADB + WebRTC bridge
├─ session store
└─ ChatTTS sidecar (optional)
```

@@ -351,143 +161,43 @@

- 负责 `/ws`、`/healthz`、`/download`、`/api/tts/synthesize`
- 通过 WebSocket 驱动完整会话状态流
- 管理 PTY runner、ADB 调试、session store、Skill / Memory、文件系统与 TTS
- 编排会话、权限、文件、日志、Skill / Memory 和 ADB 调试
### Flutter 客户端
- 入口：`mobile_vc/lib/main.dart` -> `mobile_vc/lib/app/app.dart`
- 入口：`mobile_vc/lib/main.dart`
- 根状态由 `SessionController` 驱动
- 首页是 `SessionHomePage`
- 负责把后端事件变成手机上可操作的 UI 状态
- 右上角 ADB 图标可打开模拟器调试面板
- 负责把后端事件渲染成手机上可操作的界面
### 后端协议
Go 后端通过结构化事件流向前端推送状态，例如：
- `runtime_phase`
- `interaction_request`
- `session_history`
- `skill_catalog_result`
- `memory_list_result`
- `file_diff`
- `prompt_request`
- `agent_state`
---
## 工作原理
## 文档导航
1. Flutter 连接 Go 后端 WebSocket
2. Go 后端启动或恢复 AI 助手 CLI 的 PTY 会话
3. 助手在执行中发出等待态、权限态、计划态等结构化信号
4. Flutter 将这些信号渲染成适合手机的操作界面
5. 用户在手机上批准、继续、回退、审核或输入
6. 决策再回灌给助手，形成完整闭环
- 文档索引：[docs/README.md](docs/README.md)
- 项目索引：[docs/project-index.md](docs/project-index.md)
- 架构蓝图：[docs/architecture/blueprint.md](docs/architecture/blueprint.md)
- 当前逻辑说明：[docs/architecture/current-logic.md](docs/architecture/current-logic.md)
- Relay 部署指南：[docs/guides/relay-deployment.md](docs/guides/relay-deployment.md)
- 推送集成清单：[docs/guides/push-integration-checklist.md](docs/guides/push-integration-checklist.md)
- Web 嵌入链路：[docs/guides/web-embed-path.md](docs/guides/web-embed-path.md)
- Flutter Web 白屏排查：[docs/troubleshooting/flutter-web-blank-screen.md](docs/troubleshooting/flutter-web-blank-screen.md)
- 变更历史：[CHANGELOG.md](CHANGELOG.md)
这套设计的核心不是“远程操作一台电脑”，而是：
> **让手机成为你操控电脑上 AI 助手的主入口。**
---
## 快速开始
## 从源码构建
推荐按照下面这条路径上手：
1. 在电脑上安装并启动 MobileVC
2. 在手机上安装客户端并连接
3. 开始使用 AI 助手
详细步骤见上方"🚀 快速开始"章节。
---
MobileVC 支持把 `Claude` 或 `codex` 作为 AI 引擎使用（例如在移动端连接配置里把 `Engine` 设置为 `codex`）。
- Skill 执行会按 `Engine=codex` 路由为 `codex "<prompt>"`。
- 运行态模型识别会显示为 `codex`。
- `runtime_info: doctor` 会额外检查 `codex` CLI 是否可用。
> 说明：当前“会话热恢复/权限热切换”在支持 `resume` 的引擎下体验更完整；Codex 以通用 PTY 交互能力为主。
### 会话目录过滤与电脑端 Codex 无感恢复
当你在 Flutter 端进入某个项目目录后，再打开“会话列表”，MobileVC 会：
- 把当前目录作为 `cwd` 传给后端
- 只展示这个目录下相关的 MobileVC 本地会话
- 同时自动合并电脑上该目录对应的原生 Codex 会话
这意味着你可以直接在手机端：
- 进入项目目录
- 打开会话管理
- 看到之前在电脑上用 Codex 跑过的历史会话
- 点开后直接继续聊，不需要手动记会话 ID，也不需要手动输入 `codex resume ...`
实现方式上，后端会读取本机：
- `~/.codex/state_5.sqlite`
- `~/.codex/history.jsonl`
并为这些电脑端原生会话建立 MobileVC 本地镜像记录。镜像只负责：
- 在手机端展示历史
- 记录当前移动端继续输入后的投影状态
- 把后续消息自动路由成对应的 `codex resume <session-id>` 续聊
列表里标记为 `电脑 Codex` 的会话就是这类原生 Codex 会话。它们支持加载和继续，不支持在 MobileVC 内删除。
> Smoke test：运行 `AUTH_TOKEN=test ./scripts/test_smoke_flow.sh` 可快速验证后端、WebSocket 与会话主链路。
>
> Codex smoke：运行 `AUTH_TOKEN=test ./scripts/smoke_codex_backend.sh` 可验证 Codex 适配后的后端启动、WS 会话与基础交互链路。
### 7.1 Android 模拟器调试
后端会优先自动探测：
- `ADB_PATH` / `EMULATOR_PATH`
- `ANDROID_HOME` / `ANDROID_SDK_ROOT`
- macOS 常见 SDK 路径，如 `~/Library/Android/sdk`
如果你有多个 ADB server 冲突，也可以显式指定：
```bash
ADB_SERVER_PORT=5038 AUTH_TOKEN=test go run ./cmd/server
```
进入方式：
1. 启动后端并连接 Flutter 客户端
2. 点击右上角手机图标打开 `ADB 调试`
3. 如果已检测到在线设备，直接点“进入调试”
4. 如果没有在线设备但检测到 AVD，直接点“启动模拟器”
5. 视频链路会通过 `WebRTC + H264` 建立，点击控制通过 DataChannel 回传
6. 画面出现后，可在移动端直接点击预览画面进行调试
说明：
- 当前首帧通常会在模拟器画面发生变化后出现，因此连接后如果界面完全静止，首帧可能略晚到达
- 如本机存在多个 ADB server 冲突，建议显式指定 `ADB_SERVER_PORT`
### 8. 启动 AI 助手会话（示例）
```text
claude
# 或
codex
```
### 9. 仍然支持直接启动 Go 后端
如果你想绕过 Node 启动器，原来的方式仍然可用：
```bash
git clone https://github.com/JayCRL/MobileVC.git
cd MobileVC
npm install
cd mobile_vc
flutter pub get
flutter build web --release
cd ..
npm run sync:web
AUTH_TOKEN=test go run ./cmd/server
```
---
### Flutter 移动端开发
## Flutter 客户端
```bash

@@ -499,26 +209,4 @@ cd mobile_vc

> 确保 host / port / token 配置正确。
>
> 在 iOS / Android 上，如果 app 已退到后台但当前会话还在运行，客户端会自动开启约 90 秒的短时后台保活，尽量把最后一轮回复和提醒接住。
### smoke test
---
## 测试
### Smoke test
建议优先运行一次 smoke test，先确认本地后端、鉴权和 WebSocket 主链路正常。
运行前请先确认本地 Go 服务已启动且 `AUTH_TOKEN` 与测试命令一致。
可直接运行 `AUTH_TOKEN=test ./scripts/test_smoke_flow.sh` 做一次最小主链路自检。
建议先启动 Go 服务，再运行一次最小主链路自检命令。
Smoke test：`AUTH_TOKEN=test ./scripts/test_smoke_flow.sh`，用于快速验证后端、WebSocket 和会话流是否可用。
它会连接本地服务并跑一轮最小端到端流程，帮助你确认环境是否正常。
如果该命令通过，通常说明鉴权、WebSocket 与会话主链路都已就绪。
建议在启动 Go 服务后先跑一次，快速确认 WebSocket、会话流和鉴权都可用。
也可在使用 `mobilevc start` 启动后立即执行同一命令做一次主链路自检。
```bash

@@ -528,15 +216,12 @@ AUTH_TOKEN=test ./scripts/test_smoke_flow.sh

### Go
---
```bash
go test ./...
```
## 发布与安装页
### Flutter
- `mobile_vc/scripts/build_ios_ota.sh`：生成 iPhone OTA IPA，并可选用于内部测试分发
- `mobile_vc/scripts/build_ios_testflight.sh`：TestFlight 打包 / 上传辅助脚本
- `mobile_vc/scripts/update_install_page_testflight.sh`：更新官网首页上的 TestFlight 信息
- `mobile_vc/scripts/render_install_page.py`：统一渲染官网安装入口页面
- Android release：`flutter build apk --release --target-platform android-arm64`
```bash
cd mobile_vc
flutter test
```
---

@@ -558,66 +243,23 @@

说明：根目录 `web/` 和 `web.backup/` 只保留历史产物/备份语义，当前嵌入链路以 `cmd/server/web/` 为准。
---
## 发布与安装页脚本
## 测试
- `mobile_vc/scripts/build_ios_ota.sh`：生成 iPhone OTA IPA，并可选直接上传安装页
- `mobile_vc/scripts/build_ios_testflight.sh`：TestFlight 打包/上传辅助脚本
- `mobile_vc/scripts/update_install_page_testflight.sh`：更新安装页上的 TestFlight 信息
- `mobile_vc/scripts/render_install_page.py`：统一渲染安装页 `index.html`
```bash
go test ./...
cd mobile_vc && flutter test
```
更完整的文档导航见 [docs/project-index.md](docs/project-index.md)。
---
## English Summary
## 开源许可
MobileVC turns your phone into the control center for an AI coding assistant CLI session (Claude or Codex) running on your computer.
本项目采用 [MIT License](LICENSE) 开源协议。
It is built for the moments when you are away from the keyboard but still need to keep shipping: approve permissions, handle Plan Mode, review diffs, inspect files and logs, resume sessions, and keep the workflow moving.
### What it gives you
- Mobile AI assistant control
- Permission confirmations
- Plan Mode handling
- Multi-file diff review
- File / log / runtime inspection
- Session resume and history
- Directory-scoped session discovery with seamless desktop Codex resume
- Skill capsules and memory cards
- One-tap sync and AI-assisted authoring
- Skill / Memory / Context management
- Optional TTS notifications
### The idea
Not a terminal mirror.
Not a desktop clone.
**A phone-first workflow that lets you operate your desktop AI coding assistant almost entirely from mobile.**
---
## 📄 开源许可
## 贡献
本项目采用 [MIT License](LICENSE) 开源协议。
欢迎提交 Issue 和 Pull Request。
这意味着你可以：
- ✅ 自由使用、复制、修改、合并、发布、分发本软件
- ✅ 用于商业或非商业目的
- ✅ 再许可和销售软件副本
唯一的要求是：
- 📋 在所有副本中保留版权声明和许可声明
详细条款请查看 [LICENSE](LICENSE) 文件。
### 贡献
欢迎提交 Issue 和 Pull Request！
如果你想参与开发或有任何建议，欢迎到 [LINUX DO 社区](https://linux.do) 讨论交流。
---
如果你想参与开发或交流实现细节，可以到 [LINUX DO 社区](https://linux.do) 讨论。