从源码构建（开发者）

如果你想从源码编译或参与开发：

# 克隆仓库
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 移动端开发

cd mobile_vc
flutter pub get
flutter run

这是什么

MobileVC 不是桌面终端的镜像，也不是远程桌面的替代品。

它做的是一件更直接的事：把电脑上的 AI 助手 CLI 会话变成可以被手机完整操控的工作台。

你不在电脑前，也能继续把任务推进下去：

• 继续跟助手对话
• 批准或拒绝权限请求
• 接住 Plan Mode 的多轮计划交互
• 审核 diff、接受或回滚修改
• 浏览文件、日志和运行状态
• 恢复历史会话
• 管理 Skill / Memory / Session Context
• 在助手需要你时收到推送通知（iOS APNs）

MobileVC 解决的不是”怎么远程看见电脑”，而是：

怎么让你只靠手机，就能完成电脑上的几乎全部 AI 助手工作流。

当前代码态

当前主线版本：0.2.0
整理基线：2026-04-28 当前工作区

会话链路

• 已接入原生 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。

核心价值

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

系统架构

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)

Go 后端

• 入口：cmd/server/main.go
• 负责 /ws、/healthz、/download、/api/tts/synthesize
• 通过 WebSocket 驱动完整会话状态流
• 管理 PTY runner、ADB 调试、session store、Skill / Memory、文件系统与 TTS

Flutter 客户端

• 入口：mobile_vc/lib/main.dart -> mobile_vc/lib/app/app.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. 决策再回灌给助手，形成完整闭环

这套设计的核心不是“远程操作一台电脑”，而是：

让手机成为你操控电脑上 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 冲突，也可以显式指定：

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 助手会话（示例）

claude
# 或
codex

9. 仍然支持直接启动 Go 后端

如果你想绕过 Node 启动器，原来的方式仍然可用：

AUTH_TOKEN=test go run ./cmd/server

Flutter 客户端

cd mobile_vc
flutter pub get
flutter run

确保 host / port / token 配置正确。

在 iOS / Android 上，如果 app 已退到后台但当前会话还在运行，客户端会自动开启约 90 秒的短时后台保活，尽量把最后一轮回复和提醒接住。

测试

Smoke test

建议优先运行一次 smoke test，先确认本地后端、鉴权和 WebSocket 主链路正常。

运行前请先确认本地 Go 服务已启动且 AUTH_TOKEN 与测试命令一致。

可直接运行 AUTH_TOKEN=test ./scripts/test_smoke_flow.sh 做一次最小主链路自检。

建议先启动 Go 服务，再运行一次最小主链路自检命令。