新增真机 ArkWeb DevTools 一键脚本 + 文档补多设备/fport 坑

- scripts/arkweb-devtools.sh：自动找 hdc、选真机(排除模拟器)、取 pid(没运行则拉起)、
  清掉端口上所有旧转发并重建 tcp:9222、curl 自验。幂等可反复跑；应用重启后重跑即可重连。
  （修正：hdc `fport rm` 需 local/remote 两参数分开传，否则删不掉；会累积多条旧转发需逐条清。）
- 文档加「一键脚本」快速开始、「多设备必须带 -t」提示、fport rm 两参数/累积排查。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/开发调试/真机ArkWeb-DevTools调试.md

@@ -6,6 +6,20 @@
 
 ---
 
+## 🚀 最快：一键脚本
+
+```bash
+bash scripts/arkweb-devtools.sh
+```
+
+它会自动：找 hdc → 选真机（排除模拟器）→ 取应用 pid（没运行则拉起）→ **清掉端口上所有旧转发**并重建 `tcp:9222` → curl 自验。
+成功后去 Chrome 打开 `chrome://inspect`，在 **Discover network targets** 里加 `localhost:9222`（只需加一次），点页面的 **inspect**。
+**应用一旦重启 pid 变、连接断了，重跑这条脚本即可**（端口不变、chrome 配置不用改、幂等可反复跑）。
+
+> 想手动理解原理 / 脚本不适用你的环境时，看下面的分步说明。
+
+---
+
 ## 0. 前置条件
 
 1. **必须是 debug 包**。本工程在 `BridgeGameContainer.aboutToAppear()` 里仅 debug 调用了
@@ -30,8 +44,9 @@ ArkWeb 开启远程调试后，会在应用进程下开一个 **abstract domain
 hdc -t <设备serial> fport tcp:9222 localabstract:webview_devtools_remote_$(hdc -t <设备serial> shell pidof com.lobby.daoqi | tr -d '\r')
 ```
 
-- `<设备serial>`：`hdc list targets` 里那一串（多设备时必填；单设备可省略 `-t <serial>`）。
-- 单设备简化版：
+- `<设备serial>`：`hdc list targets` 里那一串。
+- **⚠ 多设备必须带 `-t <serial>`**：如果同时连了真机 + 模拟器（`hdc list targets` 会列出真机 serial 和形如 `127.0.0.1:5555` 的模拟器），**不带 `-t` 可能把命令发到模拟器上，pidof/转发都打在错的设备 → chrome 里找不到真机页面**。真机 serial 是不含 `:` 的那一串。
+- **单设备**才可省略 `-t <serial>`：
 
 ```bash
 hdc fport tcp:9222 localabstract:webview_devtools_remote_$(hdc shell pidof com.lobby.daoqi | tr -d '\r')
@@ -103,6 +118,7 @@ devecocli log --keyword ARKWEB-CONSOLE
 
 - **`chrome://inspect` 里 Remote Target 一直空**：多半是没建 fport，或建错 pid（应用重启过）。重跑第 1 步并用第 2 步 `curl /json` 自查。
 - **`curl /json/version` 连不上**：① 不是 debug 包（没开 `setWebDebuggingAccess`）；② `pidof` 没取到（应用没在前台运行）；③ fport 没建成功（`hdc fport ls` 看下）。
+- **`[Fail]TCP Port listen failed at 9222`**：9222 上已存在转发（每次 `fport` 都会累积一条，应用多次重启后会有多条指向已死 pid 的）。只要 `curl /json` 通就不影响用。想清干净：`hdc -t <serial> fport ls | grep 9222` 看有几条，逐条删——⚠ **`fport rm` 要把 local 和 remote 两段分开传**（`fport rm tcp:9222 localabstract:webview_devtools_remote_<pid>`，不能 `fport rm tcp:9222`，也不能写成一个带空格的字符串）。一键脚本已自动清理。
 - **页面是 `<canvas>` 看不到 DOM 结构**：H5 游戏（gameabc/ifast 引擎）大量内容画在 canvas 上，DevTools 的 Elements 只能看到外层 `<canvas>`，看不到「按钮」等精灵——这是正常的，它们是引擎在 canvas 内绘制的，不是 DOM 元素。
 
 ---