# 04 给新机型写脚本

机型脚本是一个 Python 文件，记录「在哪个 App、点哪几个字、关哪几个开关」。有了机型脚本，同型号的手机几分钟跑完。

## 机型脚本放在哪

```text
recipes/<品牌>-<型号>/recipe.py
```

`<型号>` 用 `adb shell getprop ro.product.model` 的输出，比如 `PLP120`、`M154FF`、`PNM-AN10`。`run.py` 按这个名字自动匹配。

同一份脚本适用多个型号时，在脚本里写 `MODELS = ["M154FF", "2608BPX34C"]`，这些型号都会用它。

没有本型号脚本时，`run.py` 会找同品牌的脚本作参考，`recipe --ref` 才会跑，客户端里默认不勾。参考脚本、版本对不上的脚本都用**安全模式**跑：只关 `only=[…]` 里点名的开关，不做整页全关。所以脚本里尽量写 `only`。

## 为什么每个型号要单独做

同一个品牌，系统小版本不同，设置页也会变。实测例子：

| 机型 | 系统 | 浏览器设置入口 | 视频设置入口 |
|---|---|---|---|
| Find N6 | ColorOS 16.0.9 | 底部 ☰ → 齿轮 | 我的 → 设置 → 个性化内容管理 |
| Find X9 Ultra | ColorOS 16.0.10 | 底部「我的」→ 设置 | 找不到「我的」 |

所以机型脚本开头写明录制时的系统版本（`BUILD`，和 `ro.build.display.id` 或小米的 HyperOS 版本号 `ro.mi.os.version.incremental` 的开头比对），版本不同时引擎会提醒并进安全模式。

入口名在新旧版本之间会变，脚本里可以写成「有就点、没有跳过」，参考 `recipes/xiaomi-M154FF/recipe.py` 里的 `maybe()`。

**保护类开关**：「限制广告跟踪」「防止广告追踪」「关闭个性化推荐」这类以「限制 / 防止 / 阻止 / 禁止 / 关闭」开头、和广告有关的开关，打开才是保护。`p.off()` 会把它们拨到「开」，脚本不用另外处理。

## 一段机型脚本长什么样

```python
# OPPO Find N6（PLP120，ColorOS 16.0.9）机型脚本
BUILD = "PLP120_16.0.9"          # ro.build.display.id 的开头

@step("软件商店")
def _():
    p.start("com.heytap.market")                 # 拉起 App，关掉开屏弹窗
    p.go("我的", "设置")                          # 点「我的」，直到屏幕上出现「设置」
    p.tap("设置", exact=True, scrolls=0)
    if p.tap("隐私", exact=True):                 # 找到「隐私」就点，找不到会翻页
        p.off(only=["个性化推荐"], page="商店·隐私")   # 只关标题含「个性化推荐」的开关
        p.back()
    if p.tap("服务管理", exact=True):
        p.off(keep=["帮助与客服", "应用安全"], page="商店·服务管理")   # 全关，保留这两项
        p.back()
```

`@step` 的定义复制已有机型脚本开头那段即可。

## 引擎提供的动作

| 动作 | 作用 |
|---|---|
| `p.start(包名, activity=None)` | 拉起 App 或指定页面 |
| `p.setting(关键词, 结果)` | 在系统设置里搜索关键词，点搜索结果 |
| `p.tap(文字, exact=True, scrolls=6)` | 找到文字就点；`scrolls=0` 只看当前屏，3 秒内边等边关弹窗 |
| `p.go(文字, 期望)` | 点文字，直到期望的文字出现 |
| `p.off(keep=[], only=None, page="")` | 关当前页开着的开关；`only` 只关这些，`keep` 保留这些 |
| `p.back(n)` | 按 n 次返回 |
| `p.find(文字)` | 只找不点，返回坐标或 None |
| `p.confirm()` | 关开关时弹出确认框，点确认 |
| `p.d.shell(命令)` | 执行任意 shell 命令 |

一段里第一个入口没找到，后面的入口只看当前屏，不再翻页，这一段几秒结束，不会乱点。

## 写机型脚本的步骤

1. 手动走一遍：

   ```bash
   python3 tool/fast.py -s S ls            # 看当前屏幕上有什么字、什么开关
   python3 tool/fast.py -s S tap 我的 设置   # 一步一步点进去
   python3 tool/fast.py -s S scan          # 到了设置页，列出所有开关
   ```

2. 把走通的路径写成 `@step`。
3. 能用 activity 拉起的页面用 activity 写，最快也最稳：

   ```bash
   adb -s S shell dumpsys window | grep mCurrentFocus   # 停在设置页时查当前 activity
   ```

   写成 `p.start("包名", ".settings.XxxActivity")`。

4. 跑一遍：`python3 tool/run.py -s S recipe 软件商店`。
5. 跑全部，记下用时，填进 README 的机型表。

## 探路工具（实验）

```bash
python3 tool/explore.py -s S com.heytap.market com.heytap.browser
```

逐个打开 App 的设置页和子页，列出像广告的开关，输出 `探路-<型号>.tsv`。只读，不拨开关。目前在部分 App 上进了子页回不来，结果仅供参考。

## 提交 PR

1. 新建 `recipes/<品牌>-<型号>/recipe.py`。
2. 在 `docs/清单/` 对应品牌的清单里补上这个机型的差异。
3. 在 README 机型表里加一行，写明实测日期和用时。
4. 不要提交 `backups/` 目录，里面有你手机的应用列表和通知记录。