# VTBox

**Repository Path**: Ky1eYang/VTBox

## Basic Information

- **Project Name**: VTBox
- **Description**: Kotlin Compose 宿主+Java 沙盒核心+Rust NDK的Android应用沙盒空间
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-12
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VTBox

单 Guest Android 虚拟化宿主：Kotlin Compose 宿主 + Java 虚拟化核心 + Rust NDK。安装多个不同 Index 的 VTBox 宿主即可获得彼此隔离的 Guest。

## 环境

- JDK 17+
- Android SDK / NDK（见 `local.properties`）
- Rust + `cargo-ndk` + target `aarch64-linux-android`
- `adb` / `scrcpy` 可选

自检：

```powershell
.\scripts\setup-env.ps1
```

## 模块

| 模块 | 说明 |
|------|------|
| `app` | Compose UI：扫描、安装、替换、删除和打开 Guest |
| `core-common` | `AppInfo` / `GuestApp` 模型 |
| `core-virtual` | `AppScanner` / `GuestManager` / `VirtualCore` |
| `core-native` | Rust JNI：`libvtbox_native.so` |

Host 主进程中的 Rust 传输层使用固定 2 MiB 共享内存环形缓冲（RX 环）接收虚拟进程事件，并统一输出到 `VTBoxMonitor` logcat。另有独立 TX 命令环（Host → Guest UI 进程，TLV + eventfd）用于下发截图、模拟点击等指令，结果经 RX 环回传，详见 [TRANSPORT.md](README/TRANSPORT.md)。每个 Host 只使用 `:v1` 和 `:v1_push`；不同 Index 的 Host 由 Android 包隔离。

Host 顶栏的“采集设置”可在 Guest 启动前配置总开关与生命周期、触摸、Hook、任务、IPC、图形、进程和 Debug Collector。触摸默认关闭，启用后在完整手势终结时紧凑记录 MotionEvent 轨迹，但不记录 View 文本或输入内容。

## 构建

```powershell
# 可选：单独编 native
.\scripts\build-native.ps1

# Debug APK（默认 Index 1）
.\gradlew.bat :app:assembleDebug

# 构建或直接安装另一个独立 Host
.\gradlew.bat :app:installDebug -PvtboxIndex=2
```

产物示例：`app\build\outputs\apk\debug\VTBox1-0.1.5-debug.apk`。Index 只接受不带符号和前导零的正整数，默认值为 `1`；应用 ID 为 `com.kyle.VTBox{Index}.host`，应用标签为 `VTBox {Index}`。

安装：

```powershell
adb install -r app\build\outputs\apk\debug\VTBox1-0.1.5-debug.apk
```

## 使用

1. 打开 VTBox → 右下角 **添加**
2. 扫描本机桌面应用并选择一个作为唯一 Guest
3. 已有 Guest 时再次选择会先要求确认替换；取消不修改数据，确认后才切换
4. **打开** 使用固定 `:v1` 进程；**删除** 移除 Guest 并停用对应桌面快捷方式

添加应用时会显示 APK 的实际复制进度，复制完成后的沙盒准备以及启动阶段使用等待指示。添加完成后不再自动询问桌面快捷方式，可按条目右侧的桌面图标按需添加。受 Android 固定快捷方式权限限制，少数桌面可能暂时保留已删除实例的失效图标，点击时不会再启动克隆。

## 虚拟化引擎

已落地（优先 API 26–28）：

| 能力 | 说明 |
|------|------|
| HookManager | 虚拟进程内 AMS / PM / Instrumentation / HCallback |
| PackageParser | 沙盒 APK → 组件表 + ApplicationInfo 路径改写 |
| VClassLoader | PathClassLoader + arm64 so 解压 + Resources |
| StubActivity P1 | 宿主预埋 80 个 P1 Activity Stub，启动时改写为 Guest Activity |
| VirtualCore.launchGuest | 解析 LAUNCHER → Stub Intent → 固定 `:v1` 进程 |

打开沙盒应用时走虚拟化管线。复杂 App 仍可能失败，请用 logcat 观察：

```powershell
adb logcat -s VirtualCore:I HookManager:I HCallbackHook:I VClient:I StubActivity:W AndroidRuntime:E
```

### Debug 自动诊断

`DebugLaunchActivity` 仅存在于 Debug APK。推荐通过 PowerShell 脚本调用；脚本会检查 ADB 设备、安装当前 Debug APK、生成会话 ID、轮询跨进程 JSONL 报告，并在失败时输出根因、Hook 状态、最近阶段、相关进程和过滤后的 logcat。

常用命令：

```powershell
# Guest 与本机可选应用
.\scripts\debug-guest.ps1 -Index 1 -List
.\scripts\debug-guest.ps1 -Index 2 -ListInstalled -Query 微信

# 添加、预检与启动
.\scripts\debug-guest.ps1 -Index 1 -AddPackage com.tencent.mm
.\scripts\debug-guest.ps1 -Index 1 -AddPackage com.example.app -Replace
.\scripts\debug-guest.ps1 -Index 1 -Inspect -Deep
.\scripts\debug-guest.ps1 -Index 1 -Launch -TimeoutSeconds 60

# 指定设备，并把原始 JSONL 留给复现或问题报告
.\scripts\debug-guest.ps1 -Index 1 -Launch -Serial <adb-serial> `
    -ReportPath .\build\debug-reports\session.jsonl

# 强制重装，或为 Debug 包授予当前系统可授予的运行时权限
.\scripts\debug-guest.ps1 -Index 1 -List -ForceInstall
.\scripts\debug-guest.ps1 -Index 1 -GrantPermissions
```

脚本按 Index 推导宿主包名，并比较对应本地 APK 与设备 `base.apk` 的 SHA-256。已有 Guest 时 `-AddPackage` 必须显式增加 `-Replace`，脚本不会自动删除旧数据。成功启动以 Guest `onResume` 后继续观察 2 秒且无终止异常为准。

Debug 构建默认保留可观察到的原始 Intent、URI、账号/令牌、聊天文本、设备/Wi-Fi 信息及最多 16 KiB 媒体预览。这些报告仅限授权测试环境，不得使用真实账号或公开上传。Release 不输出详细原始参数。

不使用脚本时，可做最小 logcat 观察：

```powershell
adb logcat -s VTBoxMonitor:I DebugReporter:I DebugLaunch:E VirtualCore:I HookManager:I `
    HCallbackHook:I VClient:I InstrProxy:I StubActivity:W AndroidRuntime:E
```

通过内置命令操控 DebugLaunchActivity,具体查看README/TRANSPORT.md。
```powershell
$SID = [guid]::NewGuid().ToString()
adb shell am start -n com.kyle.VTBox1.host/com.kyle.vtbox.host.DebugLaunchActivity --es command launch --es sessionId "$SID"
```

## 包名

namespace 为 `com.kyle.vtbox.*`，宿主 applicationId 为 `com.kyle.VTBox{Index}.host` · minSdk 26 · arm64-v8a。版本由 `core-native/rust/Cargo.toml` 统一维护。

## Roadmap

- 完善 API 26–28 虚拟化链路，并逐步兼容更高 Android 版本。
- 补全 Activity、Service、Provider、BroadcastReceiver、文件系统与 Binder 身份虚拟化。
- 提升微信等主流复杂应用的兼容性、稳定性和不同 Host Index 间隔离。
- 由 Rust 启动独立调试服务线程，采集 Hook、进程、崩溃和性能事件。
- 建立带版本、鉴权和权限边界的上位机通信协议。
- 建设自动化兼容测试、设备矩阵、回归诊断与问题报告能力。