# 使用说明

面向「装好之后怎么用」。安装见 [README](../README.md#安装)，出问题见 [排障](troubleshooting.md)。

## 侧栏

**📱 手机** 面板注册在 DSH 原生右侧栏里 —— 侧栏面板是 DSH 原生右侧栏功能，与 `dsh-better-sidebar` 无关，也不需要安装它。打开方式：**DSH 右侧栏自己的开关按钮 → 引导胶囊里选「📱 手机」**。

面板不是当前选中页签时，视频流会**自动暂停**（省手机电量与带宽），切回来自动重连。

| 操作 | 行为 |
|---|---|
| 单击画面 | 点击手机 |
| 按住不放 | 长按（交给 Android 判定，约 500ms 触发） |
| 拖动 | 真拖拽：DOWN + 每 8ms 一个 MOVE + UP，由手机自己判定是滚动还是拖动 |
| 滚轮 | `INJECT_SCROLL_EVENT`，实测 1 格 = 192 设备像素 ≈ 0.08 屏 |
| 双指 | 缩放 |
| 键盘 | 点面板即聚焦，按键直通手机（含 Backspace / 方向键）；焦点在面板自己的输入框里时自动让路 |

**清晰度**：自适应（按面板 DPR 倒推 `maxSize`）/ 省流 / 标准 / 高清。改档会重新拉流，画面会短暂黑一下。

**截图 / 长截图**：落盘到设置里的截图目录（默认 `~/.dsh/android-phone/shots`）。长截图是逐帧采集 + 拼接，超过 22000px 自动切块成 `<name>-pNN.png`。

**状态行**：`画面 N fps` · `M Mbps` · `编码 W×H` · `前台 <包名>`。
静止页面只有 5~6fps 是正常的 —— scrcpy 的虚拟显示只在内容变化时出帧。

## 设置页

两个入口，内容一样：

- 侧栏**顶栏画质右边的「⚙ 设置」**
- **DSH「插件」页 → `dsh-android-phone` 详情页**（与上面那个入口内容一样，随时可用；右侧栏里没有「📱 手机」页签时也从这里改）

| 区块 | 内容 |
|---|---|
| ① 截图 | 保存地址（文本框 + 打开目录 + 恢复默认）、自动清理（关闭 / 1 / 3 / 7 / 30 天）、立即清理 |
| ② Skill | 只读列出 `skills/` 里的技能（名字、描述、路径可复制） |
| ③ 画质 | 与顶栏下拉同源，这里改也一样 |
| ④ 打开 App | 「▶ 打开」下拉的候选列表，可改名、可增删；「从手机添加」只列**桌面上有图标的 App** |

设置存在 `~/.dsh/android-phone/settings.json`。自动清理只删截图目录里**本插件生成的**文件名（`<时间戳>-*.png` / `-pNN.png`），其它文件不动。

## 打开 App

工具栏下拉选 App，再点「▶ 打开」。下拉**只列设置里保存过的候选**，默认 6 个：

京东 / 淘宝 / 拼多多 / 抖音 / 微信 / QQ

想加手机里已装的 App：`⚙ 设置 → ④ 打开 App → 从手机添加`，挑一个（列表只列桌面有图标的），名字默认取包名末段、可以改成中文，然后点「💾 保存 App 列表」。包名非法会被丢掉；全部非法则保留原列表。

## 会话与控制权

**单会话**：整台手机只起一个 `scrcpy-server`，视频与控制是**同一个会话的两条 socket**（`adb reverse` + `tunnel_forward=false`，启动约 1.5 秒）。

- 侧栏打开即起会话
- 无人订阅、也无人操作超过 **45 秒**才停 —— 所以模型可以在后台安心操作手机
- 会话意外断开会自动重启（有退避），侧栏也会自动重连视频流

**控制权**：默认 `owner=ai`。

| 事件 | 结果 |
|---|---|
| 人碰一下画面 | 自动接管，此后模型的动作被拒绝 |
| 人**点顶栏灰色控制权胶囊** | 立即交还模型（胶囊变回绿色） |
| 人静默 60 秒 | 自动交还模型 |
| 模型调 `phone_takeover {owner:'ai'}` | 立刻要回 |
| 顶栏胶囊文案 | 固定「🤖 模型持有」，只有颜色变：绿 = 模型，灰 = 人；人持有时它是按钮，点 = 交还 |

画面是给模型/用户的**监视窗**：模型跑流程时能实时看到每一步；人操作的动作会标记 `by:'human'`，与模型区分。

## 技能（不在包内）

插件包**不带业务流程技能**（`skills/` 故意留空）。技能属于流程与路径，按 DSH 官方设计应由用户或官方技能目录管理；
塞进插件包会导致「插件升级覆盖用户技能」「profile 里写死插件绝对路径」这类问题。

想用这 12 个 `phone_*` 工具串流程，把 skill 放进你自己的技能目录即可。
历史上有过一个 `jd-shop-longshot`（京东搜索 → 店铺 tab → 进店 → 店铺首页长截图），1.0.0 起移到包外维护。

## 安装与卸载

### 安装

用 DSH 官方入口（设置 → 插件 → 添加插件），三种来源：

- **本地绝对路径** —— 最常用，也最适合开发（装成链接后改代码重启即生效）
- **Git 地址** —— 仓库公开后填 `https://github.com/Lovepeace-art/dsh-android-phone`
- **包名** —— 需要先发布到 npm，目前未发布

DSH 会自动完成依赖安装、写 `dsh.profile.bundles`、建 `node_modules` 链接，不需要额外脚本。装完**重启 DSH**。

### 卸载

设置 → 插件 → 移除该插件，然后重启 DSH。只会摘掉依赖与 bundle 注册，**不动手机、不动截图**。

### 注意事项

- 装完确认环境是否齐备：`npm run doctor`（只读自检：Node / 平台 / vendor 里的 adb 与 scrcpy-server / adb 可用性与版本 / 设备在线 / 屏幕参数 / 截图目录可写 / profile 里指向本仓库 / bundles 已注册）。
- 本机装成**指向仓库的链接**时，改仓库文件重启即生效，不用重装；只在换机器、挪仓库、改包名、profile 重建时才需要重装。