guest 守护进程 vphoned

vphoned 是运行在 iOS VM 内部的常驻守护进程（LaunchDaemon），是宿主控制 guest 的执行端。宿主发的每一条控制请求——触摸注入、文件传输、应用管理、账户切换、keychain、剪贴板、位置模拟、PVFS 文件视图规则管理——最终都由 vphoned 在 guest 内落地。源码在仓库 scripts/vphoned/ 下（Objective-C）。

提供的能力

vphoned 与宿主通过 vsock 通信，握手时宣告 caps（能力列表）。宿主据此决定哪些功能可用，例如触摸注入走 guest 侧还是 VZ multitouch。

能力	说明
hid / touch	键盘 HID 事件与单指触摸注入（归一化坐标）
file	guest 文件系统 list/get/put/mkdir/delete/rename/settime/chmod
apps / ipa_install	应用枚举/启动/前台/终止；IPA 安装
clipboard	UIPasteboard 文本与图片读写
keychain	keychain 条目查询与写入
accounts	按 App 的多档案账户切换
location	模拟 GPS 位置注入与清除
settings / url	CFPreferences 读写、打开 URL
devmode	ARM 开发者模式（arm 后需重启）
keyboard	Unicode 文本输入（签名带键盘 App Group 时可用；跨变体键盘安装后默认可用，仅 less 不含）
port_forward	guest 内服务到 host 的端口转发中继
pvfs	每进程文件视图（PVFS）规则管理（仅 dev/jb/exp 变体，见下文专节）

另外三条独立数据通道不走命令循环：SSH 桥（vsock 2222，inetd 模式 spawn dropbear，guest 零 TCP 暴露）、虚拟相机帧中转（vsock 1338）、端口转发（vsock 1339）。

vphoned 伪装成 Apple 的 com.apple.mobile.assetd（/usr/libexec/assetd）常驻，KeepAlive 保活，启动时还会禁用自动锁屏——否则锁屏后宿主截屏只剩黑帧、触摸注入失效。日志落在 guest 内 /var/root/vphoned-logs/。

make vphoned 快速迭代

改完 scripts/vphoned/ 下的代码，一条命令交叉编译并签名：

make vphoned

流程为：xcrun -sdk iphoneos clang -arch arm64 交叉编译 → 拷贝到 $(VM_DIR)/.vphoned.signed → ldid 用 signcert.p12 + entitlements 签名（需提前 brew install ldid-procursus）。构建带增量指纹，源码无变化时秒过。

推入运行中的 guest（无需重启 VM）

make vphoned 产出新的 .vphoned.signed 后，用以下任一方式推入运行中的 guest：

# 方式一：Connect 菜单 → "Check for vphoned Update"

# 方式二：HostControl socket
echo '{"t":"vphoned_update"}' | nc -U "$(VM_DIR)/vphone.sock"

# 方式三：CLI 子命令
vphone-cli control vphoned-update

方式四（GUI）：vphone-manager 详情页 Guest tab 的「Upgrade vphoned」按钮——自动比对 guest 上报的 build hash 与 Manager 构建，一键推送内置签名二进制（本地 VM 原子写入 bundle；远程 VM 经节点 agent 上传）。变体防护：仅 regular 变体 VM 放行，其他变体会被拒绝并提示走各自更新途径。

更新机制：宿主握手时携带新二进制 SHA-256，guest 比对发现不一致即回 need_update；宿主随后推送整个二进制，guest 落盘缓存后自重启（利用 launchd KeepAlive），新代码立即生效。若缓存版本连续 3 次启动失败，自动回退到安装版二进制，可从握手信息里的 running_from（cache/install）判断当前在跑哪一份。

vphoned 还支持优雅重启（restart 命令）：回 ok 后对全部在途请求做 3 秒有界排干再退出，由 launchd KeepAlive 重新拉起同一二进制——不写缓存、不动失败计数，适合配置类变更或需要干净重启的场景。宿主侧经 HostControl 的 vphoned_restart 命令触发（Manager 与自动化框架使用）。

下次正常 make boot / vm launch 时，.vphoned.signed 会在启动前自动暂存进 bundle，握手时一并完成更新。

适用边界

这条热更新通道只替换 guest 内的 vphoned 进程二进制。适用与不适用：

改动类型	走 make vphoned + 热更新？
scripts/vphoned/ 下任意 guest 进程逻辑（命令 handler、服务实现）	✅ 可以
键盘扩展（keyboard_extension/，跨变体默认安装）	❌ 需重走 CFW 安装
固件补丁（dfu / LLB / txm / kernelcache）	❌ 必须重走 fw_patch* + 启动流程
guest 内其他系统组件（CFW 文件、launchd 配置）	❌ 重走 make boot 对应管线

判据很简单：只要改动不进 /usr/libexec/assetd 这一个进程，热更新就够不着。

新的 VM 首次部署

注意 make vphoned 只负责产物与推送；vphoned 的 launchd plist 与二进制首次进入 guest 是由 CFW 安装阶段完成的（cfw install / vm create 管线的一部分）。全新创建的 VM 上无需手动安装 vphoned。

首启 IPA 自举队列

vphoned 启动时后台扫描 /usr/libexec/.vphone-pending-ipas/ 内的 .ipa（只认 .ipa，不认 .tipa）自动安装：键盘扩展 IPA 与用户在建机时附加的 IPA（vm create --stage-ipa / cfw install --stage-ipa / Manager 向导 Apps 区 / 远程创建的 extraIPAs）都走这条队列。每个 IPA 最多重试 6 次、间隔 10 秒（等待安装守护进程就绪），成功后写 done marker 防止重装；无有效证书的 IPA 会先做 ad-hoc 重签再安装，任意来源的 IPA 都能离线装进系统。less 变体没有 CFW 阶段，不适用。

PVFS 每进程文件视图规则

PVFS（per-process file view）是 dev/jb/exp 变体内核提供的「每进程文件视图」能力：同一台 VM 上，不同进程看到的文件系统可以不同。规则由 vphoned 统一管理，一行一条，四类动作：

动作	效果
REDIRECT	对 src_path 的访问重定向到 target_path（src/target 以 / 结尾即递归目录）
DENY	拒绝访问，对进程表现为文件不存在
HIDE	从目录列表中隐藏指定路径
ALLOW	进程级白名单豁免

conf 格式为 binary_path|src_path|target_path|action，binary_path 是目标进程二进制的绝对路径，* 匹配所有进程：

/bin/cat|/private/var/test/pvfs_redirect.txt|/private/var/test/pvfs_tgt.txt|REDIRECT

规则持久化在 guest 内（/var/root/vphone_rules.conf），VM 重启后由 vphoned 自动重新推送。宿主侧经 control 命令热更新，改动即时生效、无需重启 VM：

vphone-cli control pvfs-list                     # 查看当前规则（原始 conf + 解析结果）
vphone-cli control pvfs-apply --file rules.conf  # 推送宿主侧规则文件并立即生效
vphone-cli control pvfs-reload                   # 重读 guest 内 conf 并重推（配合 guest 内编辑）
make pvfs_sync                                   # 一键同步宿主侧规则文件（VM 需运行中）

vm cryptid-redirect 基于同一套规则：为已装 App 配置 cryptid=1 副本的 REDIRECT + HIDE，让 App 自读二进制时看到「已加密」形态，规避越狱 / 脱壳检测（GUI 拖拽 / 菜单安装 IPA 时自动完成）。该能力仅 dev/jb/exp 变体具备（握手 caps 含 pvfs）；regular 变体或旧版 vphoned 上相关命令返回能力错误（响应带 capability 字段）。

排障提示

• 命令报缺能力（响应带 capability 字段）：先 make vphoned 并推送更新，很多能力是运行时探测追加的。
• 怀疑更新进了崩溃循环：看 guest 日志 /var/root/vphoned-logs/ 与宿主日志中的 running_from / cache_fail_count；连续 3 次失败会自动回退安装版，可删掉缓存后重试。
• 触摸不生效：先确认握手 caps 含 touch；iOS 26.x base 上触摸走 VZ multitouch 原生路径，属正常现象。