新增真机 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 元素。
 
 ---

scripts/arkweb-devtools.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# 一键建立真机 ArkWeb DevTools 端口转发，供 chrome://inspect 调试 H5。
+# 自动：找 hdc → 选真机(排除模拟器) → 取应用 pid(没运行则拉起) → 重建 tcp:9222 转发 → 验证。
+#
+# 用法：
+#   bash scripts/arkweb-devtools.sh                 # 默认 com.lobby.daoqi, 端口 9222
+#   bash scripts/arkweb-devtools.sh <bundle> <port> [serial]
+# 之后在 Chrome 打开 chrome://inspect → Discover network targets → 加 localhost:9222 → inspect。
+# 应用一旦重启 pid 会变、转发失效，重跑本脚本即可（端口不变，chrome 配置不用改）。
+
+set -u
+BUNDLE="${1:-com.lobby.daoqi}"
+PORT="${2:-9222}"
+SERIAL="${3:-}"
+export MSYS_NO_PATHCONV=1   # git-bash 下避免 localabstract 路径被转换
+
+find_hdc() {
+  command -v hdc >/dev/null 2>&1 && { echo hdc; return 0; }
+  local p
+  for p in "$HOME"/AppData/Local/OpenHarmony/Sdk/*/toolchains/hdc \
+           "$HOME"/AppData/Local/Huawei/Sdk/*/*/toolchains/hdc; do
+    [ -x "$p" ] && { echo "$p"; return 0; }
+  done
+  p="/c/Program Files/Huawei/DevEco Studio/sdk/default/openharmony/toolchains/hdc.exe"
+  [ -x "$p" ] && { echo "$p"; return 0; }
+  return 1
+}
+
+HDC="$(find_hdc)" || { echo "✗ 找不到 hdc，请把 <SDK>/toolchains 加入 PATH"; exit 1; }
+
+# 选真机：排除 127.0.0.1 模拟器；未指定 serial 时取第一台真机
+if [ -z "$SERIAL" ]; then
+  SERIAL="$("$HDC" list targets 2>/dev/null | tr -d '\r' | grep -v '127.0.0.1' | grep -viE 'empty|^\s*$' | head -1)"
+fi
+[ -z "$SERIAL" ] && { echo "✗ 没有连接的真机（hdc list targets 为空或只有模拟器）"; exit 1; }
+echo "真机:  $SERIAL"
+
+# 取 pid，没运行就拉起（注意：必须是 debug 包，才开了 setWebDebuggingAccess）
+PID="$("$HDC" -t "$SERIAL" shell pidof "$BUNDLE" 2>/dev/null | tr -d '\r')"
+if [ -z "$PID" ]; then
+  echo "应用未运行，拉起 $BUNDLE …"
+  "$HDC" -t "$SERIAL" shell aa start -a EntryAbility -b "$BUNDLE" >/dev/null 2>&1
+  sleep 3
+  PID="$("$HDC" -t "$SERIAL" shell pidof "$BUNDLE" 2>/dev/null | tr -d '\r')"
+fi
+[ -z "$PID" ] && { echo "✗ 取不到应用 pid（确认是 debug 包且在前台运行）"; exit 1; }
+echo "pid:   $PID"
+
+# 先删干净端口上【所有】旧转发（会积累多条指向已死 pid 的）。
+# 注意 hdc 的 `fport rm` 要 local/remote 两个参数分开传（不能是单个带空格的字符串），故 $rule 不加引号让其分词。
+"$HDC" -t "$SERIAL" fport ls 2>/dev/null | tr -d '\r' | awk -v p="tcp:$PORT" '$2==p{print $2" "$3}' | while IFS= read -r rule; do
+  # shellcheck disable=SC2086
+  [ -n "$rule" ] && "$HDC" -t "$SERIAL" fport rm $rule >/dev/null 2>&1
+done
+# 建新转发（指向当前 pid）
+"$HDC" -t "$SERIAL" fport "tcp:$PORT" "localabstract:webview_devtools_remote_$PID" 2>&1 | tr -d '\r'
+
+# 验证
+if curl -s -m 6 "http://localhost:$PORT/json" 2>/dev/null | grep -q '"type"'; then
+  echo "✓ 就绪：http://localhost:$PORT 已能列出页面"
+  echo "→ Chrome 打开 chrome://inspect，Discover network targets 加 localhost:$PORT，点页面的 inspect"
+else
+  echo "⚠ 转发已建，但 /json 暂无页面（应用可能还没加载完）。稍等几秒再： curl http://localhost:$PORT/json"
+fi