權限啟用

虛擬熒幕、截圖與觸控注入都需要 shell 級權限。Android 版提供三條路徑，推薦內置 ADB：不需要電腦、不需要 Root、不需要另裝管理器。

方式	前提	重新啟動後	安全面
內置 ADB	Android 11+（9–10 需先 `adb tcpip 5555`）	需重新啟用	僅迴環連接，RSA 認證
Root	已 root（Magisk 等）	通常自動可用	授予 root 權限
外部 Shizuku	已安裝 Shizuku / Sui	取決於管理器	複用其授權

內置 ADB

內置實現移植自 shizuku-m（Apache-2.0），包含無線配對、離線重連與加密密鑰存儲。

Android 11 及以上

開啟開發者選項

設定 → 關於手機 → 連續點擊版本號 7 次。然後在「系統 → 開發者選項」中打開無線調試。

進入配對頁

應用內：設定 → 運行與安全 → 內置 Shizuku → 開始配對。

獲取配對碼

在系統的「使用配對碼配對設備」頁面選擇「配對碼配對」。系統會顯示六位配對碼與連接埠。

通知可用：直接在應用彈出的通知裏輸入配對碼。
通知不可用：用分熒幕，把系統配對頁與應用並排，展開「設備配對 → 手動輸入配對碼」，填寫連接埠與六位碼。

確認調試授權

如果系統彈出「允許 USB 調試嗎」，勾選「始終允許」並確定。這一步容易被忽略，漏掉會表現為「配對成功但服務起不來」。

等待啟用

成功後啟動頁顯示狀態與「返回應用」，配對錶單自動收起。配對碼不會被儲存。

Android 9–10

系統沒有無線調試配對介面，需要先借助電腦把 adbd 切到 TCP 模式：

bash

adb devices            # 确认设备已连接
adb tcpip 5555         # 让 adbd 监听 5555

之後在應用內連接 127.0.0.1:5555。USB 線可以拔掉，但設備重新啟動後需要重新執行。

斷網與重連

啟用後，本次開機內即使斷網、開飛行模式，也能重新連接。失效條件：

設備重新啟動
撤銷調試授權
關閉開發者選項 / 無線調試
清除應用數據

以上任一情況都需要重新啟用。

5555 連接埠

系統 adbd 監聽 5555，可能對區域網絡開放。應用客戶端只連接 127.0.0.1，且 adbd 仍要求系統認可的 RSA 密鑰。但請不要在公共網絡下長期開啟無線調試，也不要在不認識的設備上點「允許調試」。

密鑰存儲

RSA 私鑰由 Android Keystore 的 AES-GCM 密鑰加密後儲存在應用私有偏好中，排除雲備份與設備遷移。配對碼只用於當前操作，不落盤、不寫日誌。

Root

已 root 設備可以選擇 Root 後端：

在啟用頁選擇 Root。
授予超級用戶權限（Magisk / KernelSU 等會彈出視窗）。
應用通過 app_process 拉起特權服務，Binder 回投時校驗 root/shell UID 與一次性 token。

Root 路徑與 ADB 路徑完全獨立：RootUserService 的忽略安全檢查 Context 只存在於特權子進程，不會擴散到普通 app 進程。

Root 不是「更高級的 ADB」

Root 提供的是不同的啟動鏈路與權限上下文。遇到 ADB 路徑失敗時，切 Root 可能繞過問題，但不代表問題消失。

外部 Shizuku

已經裝了 Shizuku / Sui 並授權的用戶：

啟用頁選擇外部服務。
確認 Shizuku 正在運行且已授權本應用。
應用複用其用戶服務路徑。

如果同時存在內置認證，SHIZUKU 後端優先使用內置連接；沒有內置認證時才回退外部服務。已連接的外部服務會繼續運行，重新綁定後走內置路徑。

選擇邏輯

text

后端选择
├── 内置 ADB 已激活 → 使用内置
├── 外部 Shizuku 已授权 → 使用外部
└── Root 可用 → 使用 Root

實際優先級由 PermissionManager 的狀態機決定：Shizuku 與 root 連接器只暴露無 Binder 的狀態投影，過期連接與死亡回調按 Binder 身份丟棄。

驗證啟用成功

檢查	期望
啟用頁狀態	已就緒 / Ready
掛機頁	能建立虛擬熒幕並顯示畫面
啟動任務	能截圖、點擊，任務推進
日誌	無 `Binder` 超時、無 `SecurityException`

失敗疑難排解

現象	原因	處理
配對碼輸入後無反應	未確認 USB 調試授權	重新配對，注意系統彈出視窗
「配對成功但服務未啟動」	5555 未監聽 / 被系統回收	重開無線調試；Android 9–10 重跑 `adb tcpip 5555`
Binder 超時	特權進程被殺	關閉電池優化，重試
聯發科設備啟動即崩	`LoadedApk.makeApplication` 注入	應用已用 Context-only 路徑規避；仍失敗請附日誌
重新啟動後失效	正常行為	重新啟用
外部 Shizuku 連不上	管理器未運行 / 授權被撤	打開管理器重新授權

啟動失敗與 Binder 超時可以查看應用私有目錄下的：

text

debug/embedded_adb_launch.log

安全邊界

項	設計
服務發佈	內置路徑不發佈通用 Shizuku 服務，不為其他應用授權
回投校驗	只接受 root/shell UID + 一次性 token，超時/取消即撤銷
進程死亡	App 進程死亡會銷燬特權子進程
連接埠	客戶端只連回環；不對區域網絡發起連接
日誌	配對碼不寫入日誌

權限啟用

內置 ADB ​

Android 11 及以上 ​

Android 9–10 ​

斷網與重連 ​

密鑰存儲 ​

Root ​

外部 Shizuku ​

選擇邏輯 ​

驗證啟用成功 ​

失敗疑難排解 ​

安全邊界 ​