VCP Mobile _{^{Project Avatar}}

From Desktop Client to Cyber-Physical Avatar.

<img src="https://img.shields.io/badge/version-1.0.3-blue" alt="version">
<img src="https://img.shields.io/badge/platform-Android-green?logo=android" alt="platform">
<img src="https://img.shields.io/badge/framework-Tauri%20v2%20%7C%20Vue%203-26A17B?logo=tauri" alt="framework">
<img src="https://img.shields.io/badge/backend-Rust%20%7C%20Tokio-000000?logo=rust" alt="backend">
<img src="https://img.shields.io/badge/UI-UnoCSS%20%7C%20Glassmorphism-4f46e5" alt="UI">
<img src="https://img.shields.io/badge/license-MIT-yellow" alt="license">

Table of Contents

1. What is VCP Mobile
2. Key Features
3. Architecture
4. Project Structure
5. Tech Stack
6. Documentation
7. Quick Start
8. Development & Testing
9. Contributing & Governance
10. FAQ & Troubleshooting
11. License & Credits

1. What is VCP Mobile

VCP Mobile（代号 Project Avatar）是 VCPChat 的移动端进化版，一个基于 Tauri v2 + Vue 3 + Rust 构建的 Android 原生应用。核心目标是将 AI Agent 的交互能力以低延迟、高内存安全性的方式带入物理移动端。

与桌面端 VCPChat 不同，Project Avatar 并非简单的界面适配，而是一次架构层面的彻底重构。我们采用了 Double-Track 3-Tier 架构 —— Rust 核心层、Tauri IPC 桥接层、Vue 3 渲染层物理隔离，使每一个层级都可以独立演进而不产生耦合债务。

与市面上其他移动端 AI 应用相比，VCP Mobile 的独特之处在于： - Backend-Driven Streaming：消息生命周期完全由后端 SSE 事件驱动，前端不做任何预创建或状态猜测 - 自定义增量同步协议：不依赖第三方云服务，移动端与桌面端通过 WebSocket + HTTP 双通道直接同步 - 14+ 设备能力工具：将手机本身变成一个分布式计算节点，AI 可直接调用位置、传感器、CPU/GPU 信息等原生能力

演进历程

项目从首个 commit 起即采用 Tauri v2 + Vue 3 + Rust 栈，不存在 Node.js / Electron 或 Tauri v1 的历史阶段。Rust 的所有权模型和零成本抽象为移动端提供了编译期内存安全保障，Tokio 异步运行时确保网络 IO 不阻塞主线程，这对流式聊天体验至关重要。

2. Key Features

⚡ Backend-Driven Streaming

流式聊天的消息生命周期已全面转为后端 SSE 事件驱动，前端不再承担消息生命周期管理。

• 后端通过 StreamEvent（thinking / content / blocks / end / error）逐事件下发
• 前端 chatStreamStore 仅做状态映射，不做任何消息预创建或内容猜测
• 显著简化 chatHistoryStore，消除前后端状态不一致的隐患
• 支持 LinesCodec 流式解析，降低移动端内存峰值

┌─────────────┐     SSE Stream      ┌─────────────────┐
│   Backend   │ ──StreamEvent─────► │  chatStreamStore│
│  (Rust)     │  thinking/content   │   (Vue/Pinia)   │
└─────────────┘   /blocks/end       └─────────────────┘

🧠 Tarven 上下文注入规则

结构化提示词注入规则引擎，支持在对话流的任意节点精确插入外部上下文。

• system_suffix：在系统提示词前/后追加内容
• user_suffix：在用户消息前/后追加内容
• context_inject：在对话历史指定深度注入自定义角色消息
• 规则支持 scope（global / agent / group）分级生效
• sort_order 排序机制确保多规则冲突时可预期
• WYSIWYG 实时预览，所见即所得

🔄 分布式增量同步（Delta Sync V2）

移动端与桌面端通过自定义三阶段协议保持实时同步，无需第三方云服务。

• 基于 SHA-256 Hash 的差异检测，避免全量传输
• WebSocket + HTTP 双通道设计：控制面走 WebSocket，数据面走 HTTP
• 冲突解决采用逻辑时钟与 updated_at 策略，保证最终一致性
• WAL（Write-Ahead Logging）模式 SQLite，降低移动端并发写入锁竞争

📎 多模态附件引擎 2.0

插件化附件系统，支持从图像到文档的全类型处理。

• AttachmentRegistry 注册表 + AttachmentFactory 工厂 + AttachmentClassifier 分类器
• 支持 8 种类型：Image / Video / Audio / Document / Code / Text / Other
• 双轨上传策略：
• Android 原生 File Picker（常规文件）
• 高速 TCP 通道（大文件分块上传）
• AttachmentViewer 全屏查看器，挂载于语义化 z-viewer 层级
• 文件上传：无大小限制，系统级 rename + SHA-256 流式哈希计算
• 文本提取：50 MB 文件硬上限防 OOM，提取结果按 1000 万字符截断
• 视频帧提取：Base64 累计 18 MB 动态截断，确保请求体在 20 MB 以内
• 音频提取：3500 秒（约 58 分钟）时长硬截断

🎯 Model 管理与选择器

• modelStore 集中管理模型列表、收藏状态、热门排行
• 10 分钟 TTL 缓存 + 锁频防护，避免重复请求
• ModelSelector BottomSheet 弹层：收藏 > 热门 > 字母序三级排序
• 与 AgentSettingsView 深度联动，切换模型即时生效

🏗️ Semantic Z-Index / SlidePage 虚拟导航

11 级语义化层级系统，彻底消灭 z-[999] 魔法数字。

• 三层保障：CSS 变量 --layer-* + UnoCSS 快捷类 z-* + TypeScript 常量 LAYER_*
• SlidePage 虚拟页面栈：非路由跳转，通过 overlayStore 管理，动态 Z-Index = 40 + stackIndex
• Operation Aegis 模态历史栈支持物理返回键 LIFO 消费

🔧 14+ 设备能力工具（分布式节点）— TODO

distributed/ 模块将手机转化为 AI 可直接调用的分布式计算节点，提供 14+ 原生设备能力：

• device_info / device_status_summary — 设备综合信息
• location — GPS 与网络定位
• battery — 电量与充电状态
• clipboard — 剪贴板读写
• cpu_info / gpu_info / memory_info / storage_info — 硬件监控
• network_info — 网络类型与连接状态
• ambient_sensor / motion_sensor — 环境传感器与运动传感器
• notification — 本地通知推送
• frontend_bridge — 前后端能力桥接

🤖 Agent / Group 交互

• AgentList 支持拖拽排序（SortableJS）+ Swipe 手势（编辑/删除）
• AgentSettingsView / GroupSettingsView 设置面板，与 ModelSelector 联动
• vue-cropper 头像裁剪 + Dominant Color 主色调提取
• 群组对话支持 group_context_assembler 与 group_speaking_policy 发言策略

🌊 WebGL 流体动态背景

WebGLFluidBackground.vue 提供高性能流体模拟动态背景，仅用于关于界面（About Section）的视觉特效。

🚀 OTA 热更新

• APK 本体 OTA 升级 + 前端资源热更新双通道
• confirm_frontend_boot 回滚保护机制：新资源加载失败时自动回退至上一稳定版本
• frontend_update_manager 管理下载、校验、应用全生命周期

3. Architecture

VCP Mobile 采用 Double-Track 3-Tier（双轨三层）架构，将 UI 渲染层、IPC 桥接层、Rust 核心层物理隔离，并向下延伸为 Android 原生插件层，实现端到端的类型安全与内存安全。

3.1 分层概念

┌───────────────────────────────────────────────────────────────┐
│                    Rendering Layer                             │
│  Vue 3.5 + Pinia 3 + UnoCSS                                   │
│  src/ —— 组件、Store、Composable、Directive                    │
├───────────────────────────────────────────────────────────────┤
│                    IPC Bridge Layer                            │
│  Tauri v2 —— invoke / listen / Channel                        │
│  前端调用 Rust command，后端通过 Channel 推送 SSE Stream       │
├───────────────────────────────────────────────────────────────┤
│                    Core Layer                                  │
│  Rust + Tokio                                                 │
│  src-tauri/src/vcp_modules/ —— 7 大领域：                     │
│    agent / chat / group / infra / persistence / sync / updater │
│  src-tauri/src/distributed/ —— 14+ 设备能力工具               │
├───────────────────────────────────────────────────────────────┤
│                    Native Layer                                │
│  Kotlin Android Plugin (tauri-plugin-vcp-mobile)              │
│  屏幕常亮、前台保活、键盘 Insets、生命周期桥接                 │
└───────────────────────────────────────────────────────────────┘

Double-Track 指两条独立的数据通道： - Request-Response Track：Vue invoke → Rust Command → 返回 Result<T, String>，用于配置读写、CRUD 操作。 - Streaming Track：Rust Channel → 前端 listen / EventSource，用于 SSE Stream、WebSocket 消息、进度推送。

3.2 典型数据流

发送消息（Send Message）：

Vue Input → chatSessionStore
         → invoke("send_chat_message", payload)
         → Rust chat service → VCP API
         ← SSE Stream
         → Channel.emit() → Vue chatStreamStore
         → chatHistoryStore 追加消息块

增量同步（Delta Sync）：

Vue → invoke("start_sync") → Rust sync service
  → WebSocket 握手 → Delta Sync 协议
  → SHA-256 Hash compare（本地 vs 远端）
  → 生成增量 patch → SQLite WAL 写入
  → 前端 syncStore 更新进度与状态

3.3 状态管理

全局状态由 18 个 Pinia Stores 组成，全部使用 Composition API 风格（defineStore('id', () => { ... })），摒弃 Options API。

3.4 Android 原生插件通信分层

tauri-plugin-vcp-mobile 统一管理全部 Android 原生能力，不同功能采用不同的通信方式：

关键设计决策： - KeyboardInsetsManager 和 LifecycleBridge 不使用 Tauri 标准事件通道，而是通过 evaluateJavascript 直接注入 window.CustomEvent - StreamKeepaliveService 使用 START_STICKY + IMPORTANCE_HIGH + Android 14+ FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING - 屏幕常亮使用 Raw JNI 而非 PluginHandle，避免跨语言序列化开销

4. Project Structure

VCPMobile/
├── src/                          # Vue 3 前端源码
│   ├── main.ts                   # 应用入口
│   ├── App.vue                   # 根布局（引导流程 + 侧边栏手势）
│   ├── core/
│   │   ├── stores/               # 18 Pinia Stores（Composition API）
│   │   ├── composables/          # 15 个全局组合式函数
│   │   ├── router/               # Hash 模式路由
│   │   ├── directives/           # v-intersection-observer, v-longpress
│   │   ├── types/                # 全局 TypeScript 类型
│   │   ├── constants/            # 层级常量、主题 Token
│   │   └── utils/                # 同步服务、通用工具
│   ├── features/                 # 领域功能模块（Feature Co-location）
│   │   ├── chat/                 # 对话引擎、消息渲染、输入增强
│   │   ├── agent/                # Agent/Group CRUD、设置面板、拖拽排序
│   │   ├── topic/                # 主题管理
│   │   ├── settings/             # 全局设置、主题选择
│   │   ├── notification/         # 通知中心与 Toast
│   │   ├── sync/                 # 同步状态 UI
│   │   └── distributed/          # 设备工具调用 UI
│   ├── components/
│   │   ├── layout/               # AgentSidebar, BootScreen, RightSidebar
│   │   ├── ui/                   # BottomSheet, ToastManager 等原语
│   │   └── settings/             # 设置页原子组件
│   └── assets/                   # 主题 CSS、Logo 预览
├── src-tauri/                    # Tauri v2 + Rust 后端
│   ├── src/
│   │   ├── lib.rs                # Tauri Command 注册、managed state
│   │   ├── vcp_modules/          # 业务逻辑（7 大领域）
│   │   │   ├── agent/
│   │   │   ├── chat/
│   │   │   ├── group/
│   │   │   ├── infra/
│   │   │   ├── persistence/
│   │   │   ├── sync/
│   │   │   └── updater/
│   │   └── distributed/          # 设备能力工具（14+ tools）
│   ├── plugins/vcp-mobile/       # Android 原生插件
│   │   ├── src/                  # Rust 侧（screen / stream / system）
│   │   ├── android/              # Kotlin 侧（Service / Bridge / Manager）
│   │   ├── guest-js/             # 前端 TS 调用封装
│   │   └── permissions/          # Tauri v2 权限声明
│   └── Cargo.toml                # Rust 依赖与 Release 优化配置
├── docs/                         # 四层技术文档体系
│   ├── vue_docs/                 # 前端文档（24 份）
│   ├── modules/                  # Rust 模块文档（17 份）
│   ├── sync/                     # 同步协议文档（20 份）
│   ├── plugins/                  # 原生插件文档（9 份）
│   └── *.md                      # 顶层规范（架构、UI 层级、依赖管理）
├── plans/                        # 知识治理体系（5 层目录）
├── scripts/                      # 开发辅助脚本
├── .github/workflows/            # CI/CD（类型检查 + Release APK）
├── package.json                  # pnpm 依赖与脚本
├── vite.config.ts                # Vite 配置（端口 1420/1421）
├── uno.config.ts                 # UnoCSS 预设与主题色
└── tsconfig.json                 # TS 严格模式配置

关键文件速查

CI/CD 工作流

Release 工作流环境：Node 22, pnpm 10, Java 17 (temurin), Android NDK 29.0.13846066。APK 自动重命名为 VCPMobile_v{VERSION}_arm64-v8a.apk。

5. Tech Stack