# Shizuku 工具

Shizuku 让普通应用可以执行系统命令。AiVerse 接入后，AI 获得一个名为 `Shizuku` 的工具，可通过它在手机系统上运行 `pm`、`am`、`cmd` 等命令，弥补本地容器（PRoot）拿不到系统权限的短板。

## 前置：安装并启动 Shizuku

1. 从 [Shizuku 官网](https://shizuku.rikka.app/download/) 或应用商店安装 Shizuku。
2. 打开 Shizuku，按应用内指引启动服务：
   - Android 11 及以上：开启「无线调试」后可直接在手机上启动；
   - Android 10 及以下：需连接电脑用 adb 启动。

## 在 AiVerse 中授权

打开「设置 → 软件权限 → Shizuku」，页面显示当前状态：

- **未安装**：点击前往下载安装。
- **服务未运行**：点击打开 Shizuku 并启动服务。
- **未授权**：点击申请授权，Shizuku 弹出授权框，选择「允许」。
- **已就绪**：授权完成，AI 即可使用 `Shizuku` 工具。

从 Shizuku 应用返回 AiVerse 时，状态会自动刷新。

## 使用与安全

`Shizuku` 直接操作宿主 Android 系统，权限高危，因此在工具授权上按**高危工具**处理：

- **每次调用都会弹出授权确认**：包括 `ls` 这类只读命令，不走内置安全白名单，也不会因已有规则自动放行。
- **不支持「始终允许」**：弹窗中的「始终允许」按钮不可用（会显示原因），只能单次放行，不生成记忆规则。
- **AUTO（自动）模式下同样弹窗**：AUTO 的「全放行」对它不生效；仅当开启「设置 → 工具授权 → 禁用安全拦截」后，AUTO 下才恢复自动放行（BUILD 模式仍逐次确认、不可记忆）。
- **PLAN（计划）模式**下，该工具与其他写操作一样被拦截。
- 项目权限规则中的**禁止规则**对它依然生效（命中 `deny` 会被直接拒绝）。

## 手机控制（PhoneControl）

除通用命令工具外，AiVerse 还提供 `PhoneControl` 工具，通过**无障碍服务**直接控制手机屏幕与应用，无需 Shizuku 授权。入口在「设置 → 手机控制」，需先开启其中的「无障碍权限」服务（该服务只在 AI 做手机上的事时工作）。

支持的操作：

- **读屏**（`read_screen`）：返回当前屏幕的可交互元素列表（如 `[1] 按钮 点赞`），AI 按文本定位元素 id。
- **点击元素**（`click_element`）：按 id 无障碍点击，不靠截图坐标。
- **打开应用**（`open_app`）：指定 `package_name`（如 `com.tencent.mm`）打开对应应用。
- **点击坐标**（`tap`）：指定 `x`、`y` 坐标执行点击。
- **滑动**（`swipe`）：指定起点与终点坐标执行滑动，可设时长。
- **长按**（`long_press`）：指定坐标长按，可设时长。
- **输入文字**（`input_text`）：向焦点输入文字（不支持 `;` `&` `|` `` ` `` `$` `\` 等特殊字符）。
- **按键**（`key_event`）：支持 `BACK` / `HOME` / `RECENT` / `NOTIFICATIONS` / `QUICK_SETTINGS`。
- **列出已安装应用**（`list_apps`）：返回设备上已安装的应用，可只列第三方。

`PhoneControl` 直接操纵手机，属**超高危险**操作，因此：

- **每次执行都需用户确认**：即使开启「设置 → 工具授权 → 禁用安全拦截」或「一键允许所有工具」，每次调用仍会弹出确认，且**无法保存为始终允许**。
- **确认走悬浮窗**：确认框以系统悬浮窗形式弹出，无论应用在前台还是你停留在其他页面，都能看到「拒绝 / 允许」。
- **需要悬浮窗权限**：悬浮确认依赖「显示在其他应用上层」权限。未授予时该工具会被直接拒绝并提示开启（系统设置 → 应用 → AiVerse → 显示在其他应用上层）。
- **发送、付款、删除这类动作会先问你**；AI 不会代填密码和验证码，不会替你付款，也不会改系统设置和权限。
- **PLAN（计划）模式**下被拦截；项目权限规则中的**禁止规则**依然生效。

### 灵动岛（悬浮条）

手机控制操作期间，屏幕上方会常驻一条**悬浮条**（灵动岛），可随时暂停或停止，避免操作失控：

- **闲置时不透明度**：操作暂停时悬浮条的透明度。
- **闲置时自动收起**：收成小球，点按展开。
- **完成后返回该应用**：收起悬浮条，回到你刚才操作的应用看结果。

> 需先开启「设置 → 手机控制」里的无障碍服务，`PhoneControl` 才能执行。

**1.0.0 起**，手机控制页按返回键回到设置主菜单。

## 常见问题

**命令报「Shizuku 未就绪」**

按设置页提示依次确认：已安装 → 服务已启动 → 已授权。设备重启后 Shizuku 服务通常需要重新启动（Android 11+ 可在 Shizuku 内重新开启无线调试启动）。

**`Shizuku` 工具执行失败但没有明显报错**

部分命令需要特定系统权限，`Shizuku` 并不具备所有权限。可在终端中用 `Bash` 对比，确认是命令本身还是权限问题。