harmonyrun 0.4.9__tar.gz

harmonyrun-0.4.9/.claude/plans/0-1-0-src-harmonyrun-staged-scroll.md

@@ -0,0 +1,129 @@
+# `src/harmonyrun` 模块级变更对比报告:0.1.0 → 当前
+
+> 本文是**分析报告**,不是实现计划。用户只关注 `src/harmonyrun` 下代码,按模块对比 0.1.0 到现在的差异。
+
+## Context
+
+- **基线 `0.1.0`** = commit `f669cdd`(2026-05-17 "补充最新的plan实现")
+- **当前 HEAD** = commit `203a2d0`(= tag `v0.3.0` + 4 commits)
+- 仓库另有 tag `0.5.28`(commit `f86e247` "删除Android相关代码")在旧 Android `droidrun` 谱系上,**不在当前主线**,本报告忽略。
+- 区间内 `src/harmonyrun` 累计:**181 文件变更,+7884 / −3728**,横跨 50 个提交;104 新增、12 删除、65 修改、0 重命名(prompt 重构走"删旧 .py + 增 .j2 树",git 不识别为 rename)。
+
+### 各模块改动量
+
+| 模块 | +行 | −行 | 文件 | 性质 |
+|---|---:|---:|---:|---|
+| `agent` | 4100 | 2240 | 110 | 范式重构(最大面) |
+| `cli` | 1206 | 137 | 6 | 新增控制台捕获 + 反馈链路 |
+| `tools` | 778 | 79 | 11 | 感知增强 + 方向翻转 + 原子捕获 |
+| `traces` | 558 | 67 | 5 | 报告延迟生成 + 反馈按钮 |
+| `batch` | 494 | 229 | 22 | prompts 迁移 + 多语言 + 回调 |
+| `hdcutils` | 491 | 951 | 15 | **净删**:后端抽象/屏幕流移除 |
+| `config` | 180 | 13 | 6 | 多语言 + 姿态 + per-case 覆盖 |
+| `__init__.py` | 62 | 0 | 1 | SDK 公共导出 +20 |
+| `mcp` | 8 | 8 | 2 | 截图 png→jpeg |
+| `farm` | 3 | 3 | 2 | 微调 |
+| `log_handlers.py` | 4 | 1 | 1 | tee 兼容修正 |
+
+---
+
+## 1. `agent`(+4100/−2240,本质是消息架构范式切换)
+
+**核心:从"历史线性积累 + 二阶 LLM 压缩" → "固定块级 state-user 架构 + 滑窗 + cache 锚点"。**
+
+- **prompts 体系**:`fast_agent / manager / executor` 三处 `prompts.py`(分别 308/409/281 行 Python 段常量)全部删除,迁到 Jinja2 模板树。约定:数字前缀子目录(`01_role/`…)+ 每块一对 `en.j2`/`zh.j2` + 可选 `_meta.md`;Environment 用 `StrictUndefined` + `trim_blocks=False`/`keep_trailing_newline=True`;工具名/XML 标签/参数名恒英文,只切自然语言。
+- **context_pack v1→v2**(已核实常量):
+  - 0.1.0:`RECENT_SCREENSHOTS_TO_SEND=1`、`COMPRESS_EVERY_N_STEPS=10`、`KEEP_RECENT_STEPS_RAW=5`、`COMPRESS_AFTER_STEP=15`(压缩驱动)。
+  - HEAD:`SCREENSHOTS_PER_TURN=1`、`MAX_AGENT_HISTORY_ITEMS=25`、`FULL_A11Y_FOR_LAST_N_STEPS=2`(滑窗驱动,最近 2 步带完整 a11y,更早只留骨架行)。
+  - 每步固定发 2~4 条消息:`SystemMessage` + 多块 `HumanMessage`(GOAL_XML / AGENT_HISTORY_XML / CURRENT_DEVICE_STATE_XML / prev+current 截图 / NEXT_STEP_XML)+ 可选最近一组 tool round。
+  - `cache_control` 只挂 system 末尾 + GOAL 块 + AGENT_HISTORY 块;**image 块永不挂**;DEVICE_STATE/NEXT_STEP 不挂。
+  - `pack_messages_for_send` 签名改:`(history=...)` → `(state_user_message=..., recent_tool_pair=...)`。
+  - `message_history` 从核心内存结构 **降级为 trace-only**,LLM 输入每轮从 `step_observations` 重建。
+- **compression 整组删除**:`agent/compression/{__init__,compressor,prompts}.py`(原 stage-A 确定性摘要 + stage-B LLM 改写 + fallback)。连带:`llm_loader._OPTIONAL_PROFILES` 从 `("history_compressor",)` 变 `()`;`prompt_resolver` 删 `history_compressor_system` 角色;`event_handler` 删 `HistoryCompressedEvent` 分支。
+- **FastAgent 内核**:抽出 `state.py`(原 `_FastState`)、新增 `state_user.py`(`build_state_user_for_step` 多块组装)、新增 `final_chance.py`(stagnation/max-steps 时给最后一轮,tool 绑定限 `complete`,强制判定而非 inconclusive)。
+- **state 模型**:新增 `last_tool_round`(native tool-calling 要求整对回传)、`last_state_delta`(设备侧可观测变化快照,渲染 `<state_change>` 回灌)、`previous_screenshot`;删 `last_compressed_step`/`last_digest_text`。
+- **动作集合稳定**:`ACTION_SPECS` 仍是单一真源,无新增/删除 action。
+
+---
+
+## 2. `hdcutils`(+491/−951,唯一净删模块)
+
+**核心:废除后端抽象层 + 移除 RPC 屏幕流,数据路径下沉、按调用动态降级。**
+
+- **删 `backends/`**(`base`/`socket_backend`/`shell_backend`,共 ~502 行):原 SocketBackend(持久 TCP RPC + 帧格式标准化)/ ShellBackend(逐次 `uitest dumpLayout`)逻辑内聚进 `device/screen.py:ScreenOps`。layout 改 **per-call** 决策(`ui_mode` 参数 + `_resolve_ui_mode`),socket 失败后置 `_socket_dead` 粘性标志自动降级 shell。
+- **删 `rpc/screen_pump.py`**(134 行)+ `rpc/client.py` 的全部屏幕流方法(`start/stop_screen_stream`、`capture_screen_once` 等):截图改用无状态 `hdc shell snapshot_display -t jpeg`,不再走 uitest 守护进程的持续帧流。
+- **`HdcDevice` / `build_harmony_driver` 删 `ui_backend` 参数**;`ensure_uitest_ready()` 改为无条件调 `ensure_agent_pushed()`,失败降级为警告不中断。
+- **新增任务栈导入(Tier 1.4)**:`device/apps.py` 加 `MissionInfo` dataclass + `parse_mission_list()` + `dump_mission_list()`(解析 `aa dump -l`),供 perception 构造 backStack。
+- `rpc/recovery.py` 的 tier-2 简化(不再处理屏幕 socket)。
+
+---
+
+## 3. `tools`(+778/−79,感知与驱动增强)
+
+- **driver**:
+  - `base.py`/`proxy.py`/`harmony.py`/`recording.py` 新增原子接口 `get_ui_tree_with_screenshot()`(单往返同时拿树+截图);ProxyDriver 补显式转发。
+  - `harmony.py` 新增**方向翻转**机制(`orientation_flip_by_model` 配置 + `_FLIP_MAP` + 读/写路径翻转,让 LLM 看到的方向与请求动作一致),`factory.py` 删 `ui_backend`、加 `orientation_flip_by_model`。
+  - `recording.py` 新增原始 dump 持久化(`set_raw_dump` + `_dump_raw_uitree`/`_dump_raw_screenshot`,落 `uitest_raw/`)。
+- **perception**:
+  - `pipeline.py:process_ui_tree` + `extractors/phone_state.py` 新增 `mission_list` 参数与 `backStack` 字段注入(仅有后台任务时才输出,避噪)。
+  - `formatters/indexed_formatter.py` 新增 back-stack 渲染行、`selected`(活跃 tab)标记、`CLIPPED_*_BY_Npx` 裁剪标记(`_compute_clip_markers`)。
+  - 新增 `perception/ui/offline.py:OfflineStateProvider` —— 为 `harmonyrun-evals` 走真实 a11y 管道做黑盒感知,导出到 `perception/ui/__init__.py`。
+
+---
+
+## 4. `cli`(+1206/−137,第二大改动面)
+
+- **新增 `cli/_capture.py`**(~207 行):进程级 stdout/stderr tee 单例(`_TeeStream`),`enable_console_capture()`(须在 `setup_cli_logging` 前)→ `attach_console_logfile(path)`(轨迹目录就绪后切磁盘镜像)。1MB 缓冲上限,穿透 `isatty`/`fileno`。
+- **新增 `cli/feedback.py`**(~565 行):`harmonyrun feedback [path]` 打包 trajectory zip(含 console.log,默认排除录屏)→ `gh` 推 GitHub draft release + 建 `claude-fix` issue;无 gh 时降级浏览器预填表单;支持 `--dry-run`。
+- **新增 `cli/view.py`**(~241 行):`harmonyrun view [path]` 起本地 HTTP 动态渲染轨迹/套件报告,不落 HTML 文件。
+- `cli/main.py` 注册 `feedback`/`view` 子命令,`run`/`test` 接入捕获 + `on_suite_trajectory_allocated` 回调;`cli/run.py` 加 `save_uitest_raw`。
+
+---
+
+## 5. `traces`(+558/−67)
+
+- `case_report.py:render_case_html` 返回值 `Path`→`str`(不再直接落盘,交 `view` 服务);新增 `_build_feedback_config` 注入 `__INLINE_FEEDBACK_JSON__`(反馈按钮 "📮 提交反馈")。
+- `folder.py` 新增 `uitest_raw_*` 路径与 `ensure_uitest_raw_dir`;截图统一 `.png`→`.jpeg`。
+- 新增 `traces/format.py`(`TRAJECTORY_FORMAT_VERSION`)供 `view` 检测过期轨迹;模板 `case_report.html` 大幅扩展(反馈按钮 + 原始用例信息面板)。
+
+---
+
+## 6. `batch`(+494/−229)
+
+- 删 `batch/loading/prompts.py`(153 行)→ `batch/loading/prompts/` Jinja2 树;`build_*_goal` 全链路加 `language` 参数。
+- `models.py` 新增 `TestCase.config_overrides`(per-case 覆盖),level 扩到 L0–L5。
+- `execution/runner.py`:新增 `_apply_display_preferences()`(setup 阶段按 orientation/fold 调姿态);per-case `apply_overrides` 隔离 deep-copy;trace 注入原始用例字段;移除即时 `render_case_html`(改 `view` 按需生成)。
+- `suite_runner.py` 加 `on_suite_trajectory_allocated` 回调(避免 batch import cli);`reporting/live.py` 只写 `report.json` + 新增 `find_latest_suite_run`。
+- `schemas/test_suite.schema.json`:level 枚举扩 L3–L5 + 新增 `config_overrides`。
+
+---
+
+## 7. `config`(+180/−13)
+
+- `schema/agent.py` 新增 `prompt_language`(en/zh)。
+- `schema/runtime.py`:**删 `ui_backend`**;新增 `orientation`/`fold_display`/`stream_screenshots`/`save_uitest_raw`。
+- `manager.py` 新增 `devices.yaml` 旁路加载(`_load_orientation_flip_map_from_yaml`)+ `_apply_runtime_env_overrides`(`HARMONYRUN_STREAM_SCREENSHOTS`/`HARMONYRUN_SAVE_UITEST_RAW`)。
+
+---
+
+## 8. 其余
+
+- **`mcp`**(+8/−8):截图 mime `image/png`→`image/jpeg`(perception tool + 两个 resource),actions 微调。atomic 模式与分层不变。
+- **`farm`**(+3/−3):仅文档 + server/app.py 微调。
+- **`__init__.py`**(+62):`_LAZY_EXPORTS` 扩出 ~20 个 SDK 入口(`pack_messages_for_send`/`build_*_xml`/`StepObservation`/`build_harmony_driver`/`UIState`/`OfflineStateProvider`/`find_latest_suite_run`/`load_test_cases`/`render_case_html`/`TraceFolder`/`apply_overrides` 等)。
+- **`log_handlers.py`**(+4/−1):`CLILogHandler` 的 `Console(file=stream or sys.stdout)`→`Console(file=stream)`,让 tee 能 retroactively 抓住 rich 输出。
+- `app_cards`/`hypium`:本区间无改动。
+
+---
+
+## 跨切面主题(设计演进方向)
+
+1. **消息架构范式切换**:压缩驱动 → 块级 state-user + 滑窗 + cache 锚点(agent 大头)。
+2. **设备通路简化**:后端抽象/屏幕流移除,改 per-call 路由 + 无状态 snapshot + 自动降级(hdcutils 净删)。
+3. **更精准的设备侧上下文**:任务栈 backStack、CLIPPED 裁剪标记、方向翻转、原始 uitest dump 落盘 —— 全部来自设备可观测源,契合 harness 哲学。
+4. **报告解耦**:JSON 单一事实源,HTML 由 `harmonyrun view` 按需动态生成(runner/reporting 不再即时写 HTML)。
+5. **反馈驱动闭环**:console tee → zip → `harmonyrun feedback` → GitHub issue/Action 自动分析。
+6. **prompts 工程化 + 多语言**:四处 prompts.py → Jinja2 模板树,`prompt_language` 全链路。
+7. **评测可复现**:`OfflineStateProvider` 让 evals 走真实感知管道。
+
+> 注:CLAUDE.md 记 "N=2 双截图",但代码真值 `SCREENSHOTS_PER_TURN=1`(prev/current 滚动机制已就位,发送数常量默认 1)—— 属文档漂移,以代码为准。

harmonyrun-0.4.9/.claude/plans/01-/344/272/221/347/253/257/346/234/215/345/212/241/345/231/250/347/273/217/346/234/254/345/234/260/344/270/255/350/275/254/350/256/277/351/227/256/347/234/237/346/234/272-/342/200/224-/345/217/257/350/241/214/346/200/247/345/210/206/346/236/220.md

@@ -0,0 +1,420 @@
+# 云端服务器经本地中转访问真机 — 可行性分析
+
+- 会话时间: 2026-04-22T08:04:13
+- 会话 ID: `e1e23ed9-6085-4290-bb3f-56925e8f2a8a`
+- 计划版本数: 2
+
+## 原始诉求
+
+> 此诉求和当前代码仓没有太大关系，我是想让你帮我分析下这套方案的落地可行性，我现在有一台云端服务器，服务器上有全套的鸿蒙开发环境，比如HDC命令，我想实现一套可以让服务器直连我某一台真实手机的能力，这个手机我可以通过某一台电脑连接，我可以在电脑上也配合启动一套服务用来中转消息，我核心的诉求就是分析下让服务器的环境中能通过hdc命令访问这台真实手机的方案可行性。当前代码仓中有写关于socket与手机交互的能力，我不知道对你这次分析有没有借鉴作用，你可以借鉴分析下。
+
+---
+
+## Plan v1 (2026-04-22T08:17:24)
+
+## 方案可行性分析：云端服务器通过 hdc 远程访问本地真机
+
+### Context（背景与目标）
+
+- **现状**：云端服务器已具备鸿蒙开发环境（含 hdc 命令），但没有物理 USB 口，无法直接接手机。
+- **目标**：让云端服务器的 `hdc xxx` 命令像"设备就在本地 USB"一样，透明地作用在"电脑 A 上连着的真机"。
+- **已确认的假设**（来自用户对齐）：
+  1. 网络方向：**电脑 A 可主动出网连云端**（云端无法主动回连），→ 采用 SSH 反向隧道。
+  2. 云端使用范围：**仅命令行 hdc** (`hdc shell` / `hdc file send|recv` / `hdc list targets` 等)，不需要在云端直连 fport 本地端口。
+  3. 规模：**当前一台手机，未来可能多台**，方案需为多设备预留扩展性。
+- **参考**：当前仓库 [droidrun](/Users/legend/Desktop/Code/droidrun) 已有 `run_hdc()` 统一封装（[_utils.py:79-174](src/droidrun/agent/harmony/_utils.py#L79-L174)），印证"只要 hdc 环境变量生效，所有命令自动走远程"这一思路可行。
+
+---
+
+### 结论先行
+
+**可行性：高，且落地代价很小。** 核心只要三件事：
+
+1. 电脑 A 上用 `hdc -m` 起远程模式 server（仅监听 127.0.0.1）。
+2. 电脑 A 上常驻一条 SSH 反向隧道，把 `127.0.0.1:8710` 送到云端 `127.0.0.1:8710`。
+3. 云端设置 `HDC_SERVER_HOST=127.0.0.1` / `HDC_SERVER_PORT=8710`。
+
+命令层所有 hdc 调用即刻透明远程化，无需改业务代码。多台手机天然由同一 hdc server 并管，云端用 `hdc -t <serial>` 区分。
+
+---
+
+### HDC 的远程能力（只保留本方案用到的事实）
+
+- HDC 与 ADB 架构一致：`client ⇄ server（8710）⇄ daemon（设备内）`。一个 server 可同时管多台设备。
+- `hdc -m -s <bind>:<port>`：以远程模式启动 server，允许外部 client 接入。
+- `HDC_SERVER_HOST` / `HDC_SERVER_PORT`：client 通过环境变量定位远程 server（零代码改动）。
+- 多设备区分：`hdc -t <serial> <sub-command>` 或 `hdc list targets` 列出当前 server 下所有设备。
+- **hdc 协议本身无加密、无认证**：必须走加密隧道保护；严禁让 server 监听 `0.0.0.0`。
+
+---
+
+### 推荐架构
+
+```
+┌─────────────────────┐                              ┌──────────────────────┐
+│ 云端服务器           │                              │ 电脑 A                │
+│ ─────────────────── │                              │ ────────────────────  │
+│ HDC_SERVER_HOST=    │                              │                      │
+│   127.0.0.1         │◄──── SSH reverse tunnel ─────┤ hdc -m -s            │
+│ HDC_SERVER_PORT=    │      127.0.0.1:8710          │   127.0.0.1:8710     │
+│   8710              │        (电脑主动建立)          │                      │
+│                     │                              │   │ USB / WiFi       │
+│ hdc list targets    │                              │   │                  │
+│ hdc -t <s> shell …  │                              │   ▼                  │
+│ hdc -t <s> file …   │                              │ 📱 手机 1..N          │
+└─────────────────────┘                              └──────────────────────┘
+```
+
+**关键操作序列**：
+
+1. **电脑 A（一次性初始化）**：
+   ```sh
+   hdc kill
+   hdc -m -s 127.0.0.1:8710        # 仅监听本机，把风险面交给 SSH
+   hdc list targets                # 确认本机能看到手机
+   ```
+
+2. **电脑 A（常驻反向隧道）**：
+   ```sh
+   autossh -M 0 -N \
+     -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
+     -o ExitOnForwardFailure=yes \
+     -R 127.0.0.1:8710:127.0.0.1:8710 \
+     <user>@<云端>
+   # 建议包成 systemd user service / launchd plist / Windows 任务，开机自启
+   ```
+
+3. **云端（使用）**：
+   ```sh
+   export HDC_SERVER_HOST=127.0.0.1
+   export HDC_SERVER_PORT=8710
+   hdc list targets                                   # 应看到电脑 A 上的手机
+   hdc -t <serial> shell uname -a
+   hdc -t <serial> file send ./x /data/local/tmp/x
+   hdc -t <serial> file recv /data/local/tmp/log ./
+   ```
+
+---
+
+### 多手机扩展（前瞻设计）
+
+**默认路径（推荐，最简单）**：一台电脑 A 上只跑**一个** hdc server，所有 USB/WiFi 接入的手机都挂在它下面。
+
+- 云端用 `hdc -t <serial>` 明确指定目标设备；`hdc list targets` 返回全部 serial。
+- 扩容时只需把新手机插电脑 A（或用 `hdc tconn` 接入局域网的手机），**隧道和环境变量都不变**。
+- 这是 HDC 原生语义，与单机开发体验一致。
+
+**需要考虑独立实例的两种情况**：
+
+| 场景 | 处理 |
+|---|---|
+| 多个电脑 A（不同地点各接一批手机） | 每台电脑跑一份 hdc server，分别用不同端口反向转发（8710/8711/8712…），云端按端口区分"机位"而非按 serial |
+| 多用户抢占同一台手机 | 在云端或电脑 A 前置一层代理（最简即 SSH ForceCommand 脚本），按登录账号做 `hdc -t` 注入与审计 |
+
+---
+
+### 安全加固（必做）
+
+- **hdc -m 必须只监听 127.0.0.1**，绝不监听 0.0.0.0。所有外部访问全部经过 SSH。
+- **SSH 账号专用**：云端给电脑 A 配一个受限账号，禁用 shell，只允许 port forward：
+  ```
+  # /home/<user>/.ssh/authorized_keys on 云端
+  command="/bin/false",no-pty,no-X11-forwarding,permitopen="127.0.0.1:8710" ssh-ed25519 AAAA... tunnel@电脑A
+  ```
+- **云端 sshd 配置**：`AllowTcpForwarding yes`，`GatewayPorts no`（避免意外对外暴露）。
+- **可选增强**：在 hdc server 外包一层 mTLS 代理（`stunnel` / `ghostunnel`），为多用户场景准备。
+- **合规提醒**：`hdc shell` 具有接近 root 的调试能力，凭据应一机一号、可审计、可快速吊销。
+
+---
+
+### 借鉴 droidrun 仓库的启发（虽与本方案关联不大）
+
+- 仓库的 `run_hdc()` 通用执行器（[_utils.py:79-174](src/droidrun/agent/harmony/_utils.py#L79-L174)）印证：**只要环境变量生效，上层业务代码不用改**。若未来想把 droidrun 整体搬到云端，只需在调用侧统一注入 `HDC_SERVER_HOST/PORT`。
+- 仓库的"socket / shell 双后端"配置（[config_manager.py:115](src/droidrun/config_manager.py#L115)）展示了一个优雅降级模式。即便不需要 fport 直连能力，这也是"业务需要直连设备端口时"的一条备用路径——强行切 `ui_backend=shell`，全走 `hdc shell`+`hdc file recv`，在远程 server 模式下天然可用。
+- **与本方案的关系**：用户明确只要命令行 hdc，因此仓库中那套"fport + 直连 127.0.0.1:port"的 socket 模式**不会被触发**，不需要为 fport 动态端口做二级隧道，方案大幅简化。
+
+---
+
+### 风险清单
+
+| 风险 | 影响 | 缓解 |
+|---|---|---|
+| hdc client/server 版本不一致 | 协议不兼容直接断连 | 云端与电脑 A 的 hdc 二进制必须来自**同一个 SDK 版本**；运维脚本锁定版本并定期核对 `hdc -v` |
+| SSH 隧道断连 | 全部命令失败 | `autossh` + `ServerAliveInterval=30`；systemd/launchd 自动重启；云端对隧道端口做存活探测告警 |
+| 电脑 A 意外共享账号 / 权限外泄 | 等同于把手机 root shell 给了外人 | authorized_keys 强制 `permitopen` + `command=/bin/false`；定期轮换密钥 |
+| 多用户并发操作同一台手机 | hdc 本身不做锁，命令相互干扰 | 当前单用户场景无问题；需要时在电脑 A 前加一个串行化代理，或直接约定"一机一人" |
+| 长连接 / 阻塞命令（如 `hdc shell` 交互） | 隧道中断时云端客户端可能僵死 | 命令层加 `timeout` 包裹（参考仓库 [_utils.py:79-174](src/droidrun/agent/harmony/_utils.py#L79-L174) 的做法） |
+
+---
+
+### 最小可行验证（MVP，20 分钟以内可跑通）
+
+1. 电脑 A 装好鸿蒙 SDK，USB 连上一台手机，`hdc list targets` 应看到设备。
+2. 电脑 A：`hdc kill && hdc -m -s 127.0.0.1:8710`。
+3. 电脑 A：`ssh -N -R 127.0.0.1:8710:127.0.0.1:8710 <user>@<云端>`（先手动跑一次验证打通）。
+4. 云端新开一个 shell：
+   ```sh
+   export HDC_SERVER_HOST=127.0.0.1 HDC_SERVER_PORT=8710
+   hdc list targets                       # 看到手机 serial 即成功
+   hdc -t <serial> shell uname -a          # 远端执行
+   echo "hello" > /tmp/a && hdc -t <serial> file send /tmp/a /data/local/tmp/a_from_cloud
+   hdc -t <serial> file recv /data/local/tmp/a_from_cloud /tmp/b && cat /tmp/b
+   ```
+5. 全部通过即说明协议层打通。之后把 SSH 隧道包成 `autossh` / systemd 常驻、把 `hdc -m` 写进电脑 A 开机项即可上线。
+
+MVP 通过即代表方案无拦路虎，后续工程化只是"脚本化 + 监控告警 + 多手机接入时的 serial 路由约定"。
+
+---
+
+### 需要在电脑 A / 云端执行的关键文件/配置清单
+
+- 电脑 A：开机自启脚本或 systemd user unit，内容为 `hdc kill; hdc -m -s 127.0.0.1:8710`。
+- 电脑 A：`autossh` 常驻任务（参数见上文）。
+- 云端：目标用户 `~/.ssh/authorized_keys` 中加入**受限隧道公钥**（`command="/bin/false"`, `permitopen="127.0.0.1:8710"`）。
+- 云端：在使用 hdc 的服务/登录环境中导出 `HDC_SERVER_HOST=127.0.0.1`、`HDC_SERVER_PORT=8710`（写入 `/etc/profile.d/hdc.sh` 或业务容器的环境变量）。
+- 双方：hdc 二进制版本锁定（记录到运维 runbook）。
+
+---
+
+## Plan v2 (2026-04-22T08:30:20)
+
+## 方案可行性分析：云端服务器通过 hdc 远程驱动本地真机（含 socket 后端）
+
+### Context（背景与目标）
+
+- **现状**：云端服务器已具备鸿蒙开发环境（含 hdc），但没有物理 USB 口。
+- **新目标**：云端不仅能跑 `hdc` 命令，还要能**像 droidrun 一样完整驱动这台手机**；且为了高效，**UI 树（a11y 树）和截图必须走 socket 后端**，不退化到 `hdc shell`。
+- **网络假设（用户已确认）**：电脑 A 可主动连云端，云端无法回连 → 所有跨网通道走**电脑 A 发起**的 SSH。
+- **规模假设**：当前一台手机，未来可能多台。
+- **参考仓库**：[droidrun](/Users/legend/Desktop/Code/droidrun)。关键代码已读确认：
+  - `hdc fport` 在 [_uitest_rpc.py:741-752](droidrun/hdcutils/_uitest_rpc.py#L741-L752) 建立。
+  - 每个 `UitestRpcClient` **只分配一个** `_local_port`（[_uitest_rpc.py:744](droidrun/hdcutils/_uitest_rpc.py#L744)），main/layout/screen **三个 socket 共用同一本地端口**（[_uitest_rpc.py:519](droidrun/hdcutils/_uitest_rpc.py#L519)、[_uitest_rpc.py:795](droidrun/hdcutils/_uitest_rpc.py#L795)、[_uitest_rpc.py:799-800](droidrun/hdcutils/_uitest_rpc.py#L799-L800)），因为远端 `localabstract:uitest_socket` 支持多连接复用。
+  - 结论：**每台手机只需 1 条额外隧道**（+ 1 条公用的 hdc 协议隧道），不需要 3 条。
+
+---
+
+### 核心困难：fport 本地端口不在云端
+
+当 `hdc` 环境变量指向远程 server 时，云端执行的 `hdc fport tcp:PORT localabstract:uitest_socket` 实际在**电脑 A**的 `127.0.0.1:PORT` 上开监听，而 droidrun 紧接着在**云端进程里**跑 `asyncio.open_connection("127.0.0.1", PORT)`（[_uitest_rpc.py:523](droidrun/hdcutils/_uitest_rpc.py#L523) / [_uitest_rpc.py:800](droidrun/hdcutils/_uitest_rpc.py#L800) / [_uitest_rpc.py:887-901](droidrun/hdcutils/_uitest_rpc.py#L887-L901)）——云端上这个端口没人监听，直接失败。
+
+这是唯一真正需要解决的工程点。命令层（hdc shell/file/list）已在上一版方案中打通，不再赘述。
+
+---
+
+### 三条可行路径（按改动量递增）
+
+#### 路径 A：**固定 uitest 端口 + 双反向隧道**（推荐 MVP）
+
+让 `_local_port` 不再动态分配，改用约定好的固定端口；电脑 A 的 SSH 反向隧道预先把这个端口也打穿。
+
+**改动点**：
+- [_uitest_rpc.py:744](droidrun/hdcutils/_uitest_rpc.py#L744) 的 `get_free_port()` 改为"优先读环境变量 `DROIDRUN_UITEST_LOCAL_PORT`，否则退化到现行动态分配"。单行改动，不破坏本地开发体验。
+- 电脑 A 的 SSH 隧道由一条变两条：
+  ```sh
+  autossh -N \
+    -R 127.0.0.1:8710:127.0.0.1:8710 \
+    -R 127.0.0.1:18012:127.0.0.1:18012 \
+    <user>@<云端>
+  ```
+- 云端业务环境：
+  ```sh
+  export HDC_SERVER_HOST=127.0.0.1
+  export HDC_SERVER_PORT=8710
+  export DROIDRUN_UITEST_LOCAL_PORT=18012
+  ```
+
+**多手机扩展**：
+- 每加一台手机，云端为其分配一个独立端口（18013、18014…），反向隧道对应加一条 `-R`。
+- droidrun 的 `UitestRpcClient` 本就按设备 serial 实例化，`_local_port` 端口在业务启动时按 serial → 端口映射注入即可。
+- 约定一张简单的映射表（YAML/env），运维侧维护。
+
+**优点**：
+- 代码改动最小（一两行 + env 注入），可 20 分钟落地。
+- 性能开销仅"一次 SSH 加密 + 一次 TCP 跳"，JPEG 0.5x 屏幕流在公网可稳定（典型 100KB–1MB/帧）。
+- 无新增运行时组件，可靠性等同 SSH。
+
+**缺点**：
+- 端口池由人手动维护，扩容到几十台时琐碎。
+- 云端业务若并发多实例同一设备，会冲突（但这本来 uitest daemon 也不支持并发多 client）。
+
+---
+
+#### 路径 B：**电脑 A 侧跑 uitest gateway 代理**（推荐进化版）
+
+电脑 A 上常驻一个小型代理进程，专门负责：本地建 fport + 连 uitest abstract socket，对外（云端方向）暴露一个按"设备 serial"多路复用的统一入口。
+
+**架构**：
+```
+云端 droidrun (多实例 / 多设备)
+  ↓ asyncio.open_connection("127.0.0.1", 9000)
+  ↓ SSH reverse tunnel -R 9000:127.0.0.1:9000
+电脑 A: uitest-gateway (监听 9000)
+  ├─ 握手帧：选定 target serial
+  ├─ 内部 hdc fport tcp:动态 localabstract:uitest_socket
+  └─ 把云端连接的字节双向桥到本地 fport 端口
+手机 uitest daemon
+```
+
+**对 droidrun 的改动**：
+- `_ensure_forward`：在云端启用"gateway 模式"时跳过 `hdc fport`（因为 fport 由 gateway 代管）。
+- `_ensure_socket` / `_ensure_layout_socket_unlocked` / `_ensure_screen_socket_unlocked`：三处 `open_connection("127.0.0.1", port)` 改为"连 gateway + 发一个 1 帧的握手（设备 serial + 通道类型）"。
+- 用 `ui_backend` 类似的配置开关控制（`"socket"` / `"socket-gateway"` / `"shell"`），本地开发不变。
+
+**优点**：
+- 云端不再需要感知电脑 A 的端口布局，扩容手机零运维。
+- 代理层可做图像降帧/降采样（如把 0.5x 再压到 0.25x 或跳帧），**公网带宽可控性显著好于路径 A**。
+- 支持多用户/多 droidrun 实例并发，按 serial 排他加锁，顺便解决 uitest daemon 单 client 的限制。
+- 隧道只有一条（9000 复用），配置简单。
+
+**缺点**：
+- 需要实现并维护 gateway（估计 300–600 行 Python/Go）。
+- 协议设计：握手 + 三通道多路复用 + 错误传播，要做好才能稳。
+- 对 droidrun 的三个 `open_connection` 站点做抽象（`_connect_uitest_channel(kind)` 之类的方法），中等改动。
+
+---
+
+#### 路径 C：**把 driver 下沉到电脑 A，云端只剩 agent/LLM**（性能最优）
+
+彻底拆分：云端只跑"决策层"（LLM agent、规划、状态机），**真正驱动手机的代码跑在电脑 A**，两者通过一层更高抽象的 RPC（HTTP/gRPC/WebSocket）沟通。
+
+**边界**：
+- 云端 → 电脑 A：`dump_layout` / `snapshot` / `tap(x, y)` / `input_text` / `set_rotation` 等"动作级"RPC。
+- 电脑 A → 云端：事件回调、屏幕帧流（可按云端 agent 实际消费频率拉，而非手机推多少传多少）。
+
+**对仓库的改动**：
+- 把 `HdcDevice` 和 `UitestRpcClient` 抽成"本地 driver"和"远端 driver"两实现，共享同一套接口。
+- 远端 driver 客户端在云端，服务端在电脑 A（可以复用 droidrun 的现有实现 + 一层 HTTP 包装）。
+
+**优点**：
+- 性能最优：uitest socket 不跨公网，图像可在电脑 A 就地压缩/编码（甚至转成 H.264 流）。
+- 延迟可控（RPC 频率由云端主动拉而非被动接）。
+- 最符合"把沉重 I/O 留在设备侧、把智力留在云端"的分布式架构直觉。
+
+**缺点**：
+- 改动最大：需要设计接口、拆代码、引入 RPC 框架、做双向错误/超时/重连。
+- 落地周期按周计。
+- 调试链路更长（问题可能出在云端、隧道、电脑 A、手机四者任意一层）。
+
+---
+
+### 推荐路线
+
+**分两阶段走**：
+
+1. **阶段一（本周内）：路径 A**
+   - 最小改动验证整条链路：反向隧道 × 2 + 环境变量 + `get_free_port()` 可被 env 覆盖。
+   - 产出：一份可复现的 MVP 脚本 + 对 droidrun 的 1–2 行 patch。
+   - 验收：云端调 `HarmonyDriver.get_ui_tree()` 和 `capture_screen()` 能正常拿到内容；`ui_backend=socket` 不降级。
+
+2. **阶段二（若长期使用 / 多手机多用户）：路径 B**
+   - 在路径 A 稳定后，把 gateway 写出来、切换 `ui_backend=socket-gateway`。
+   - 阶段一的隧道和 env 管理开销消失，扩容成本随之趋零。
+
+**暂不推荐路径 C**，除非云端并发跑几十路 agent 需要严格带宽控制，或屏幕流的公网延迟成为 agent 决策瓶颈再回头考虑。
+
+---
+
+### 架构图（目标形态：路径 A + hdc 命令兼容）
+
+```
+┌───────────────────────────┐                             ┌──────────────────────────┐
+│ 云端服务器                 │                             │ 电脑 A                   │
+│ ───────────────────────── │                             │ ────────────────────     │
+│ HDC_SERVER_HOST=127.0.0.1 │                             │                          │
+│ HDC_SERVER_PORT=8710      │◄── SSH -R 8710 ─────────────┤ hdc -m -s 127.0.0.1:8710 │
+│ DROIDRUN_UITEST_LOCAL_    │                             │                          │
+│   PORT=18012              │◄── SSH -R 18012 ────────────┤ 127.0.0.1:18012          │
+│                           │   (电脑 A 发起的 autossh)     │    ▲                    │
+│  droidrun HarmonyDriver   │                             │    │ hdc fport           │
+│   ├─ hdc list targets     │                             │    │                    │
+│   ├─ UitestRpcClient      │                             │  localabstract:          │
+│   │   open_connection(    │                             │    uitest_socket         │
+│   │     127.0.0.1, 18012) │                             │    │                    │
+│   └─ get_ui_tree /         │                             │    ▼                    │
+│       capture_screen       │                             │  📱 手机                 │
+└───────────────────────────┘                             └──────────────────────────┘
+```
+
+---
+
+### 对 droidrun 仓库的具体改动（路径 A）
+
+1. **[_uitest_rpc.py:741-752](droidrun/hdcutils/_uitest_rpc.py#L741-L752) `_ensure_forward()`**
+   - 读取 env `DROIDRUN_UITEST_LOCAL_PORT`（或构造参数注入），若存在则替代 `get_free_port()`。
+   - 多手机场景：支持 `DROIDRUN_UITEST_LOCAL_PORT_<serial>` 或按构造参数传入。
+2. **端口占用清理**：在复用固定端口时，`_ensure_forward` 前面加一次 `hdc fport rm` 的容错（避免上次崩溃残留）。仓库已有 `fport rm` 逻辑（[_uitest_rpc.py:754-765](droidrun/hdcutils/_uitest_rpc.py#L754-L765)），仅需在 `_ensure_forward` 前也调一次。
+3. **配置项**：在 `config_manager.py` 加一个可选字段（如 `device.uitest_local_port`），方便多实例编排。
+
+**非侵入性**：本地开发不设这些 env/配置时，行为与现在完全一致。
+
+---
+
+### 安全加固
+
+- `hdc -m` 仅监听 `127.0.0.1`。
+- `uitest_socket` 的固定本地端口同样仅监听 `127.0.0.1`。
+- SSH 账号：`authorized_keys` 用 `command="/bin/false"` + `permitopen="127.0.0.1:8710"` 和每个 `permitopen="127.0.0.1:1801X"` 约束。
+- 云端 sshd：`AllowTcpForwarding yes`、`GatewayPorts no`。
+- 合规：hdc shell + uitest 等价于手机 root 级控制，凭据一机一号、可审计、可吊销。
+
+---
+
+### 风险清单（相对上一版新增项加粗）
+
+| 风险 | 影响 | 缓解 |
+|---|---|---|
+| hdc client/server 版本不一致 | 协议不兼容直接断连 | 云端与电脑 A 使用同一版本的 hdc |
+| SSH 隧道断连 | 所有命令与 socket 失败 | autossh + `ServerAliveInterval=30` + systemd 常驻 |
+| **公网抖动导致屏幕流卡顿** | agent 看到的帧不新鲜 | 仓库屏幕推送走"保留最新一帧"策略（[_uitest_rpc.py:436-479](droidrun/hdcutils/_uitest_rpc.py#L436-L479)），天然容忍；若仍不够，进化到路径 B 做代理层降帧 |
+| **uitest daemon 单 client 限制** | 多云端进程抢同一手机会互相踢 | 路径 A 通过单实例约束规避；路径 B 在 gateway 层做 serial 级串行化锁 |
+| **固定端口冲突（多手机 / 多部署）** | fport 建立失败 | 每台手机独立端口；部署前 `hdc fport ls` 清理 |
+| 电脑 A 账号外泄 | 等同手机 root 泄漏 | `permitopen` 白名单、密钥轮换 |
+
+---
+
+### 最小可行验证（MVP）
+
+1. 电脑 A：
+   ```sh
+   hdc kill
+   hdc -m -s 127.0.0.1:8710
+   hdc list targets    # 确保本地能看到手机
+   ```
+2. 电脑 A：
+   ```sh
+   autossh -M 0 -N -o ServerAliveInterval=30 -o ExitOnForwardFailure=yes \
+     -R 127.0.0.1:8710:127.0.0.1:8710 \
+     -R 127.0.0.1:18012:127.0.0.1:18012 \
+     <user>@<云端>
+   ```
+3. 对 droidrun 打 patch：`_ensure_forward()` 读 env（改动 ≤10 行）。
+4. 云端：
+   ```sh
+   export HDC_SERVER_HOST=127.0.0.1 HDC_SERVER_PORT=8710
+   export DROIDRUN_UITEST_LOCAL_PORT=18012
+   python -c "
+   import asyncio
+   from droidrun.agent.harmony import HarmonyDriver
+   async def main():
+       d = await HarmonyDriver.create(serial='<serial>')
+       print(await d.get_ui_tree())        # 走 socket 后端
+       png = await d.capture_screen()
+       open('/tmp/x.png','wb').write(png)
+   asyncio.run(main())
+   "
+   ```
+5. 验证 `/tmp/x.png` 有效 + `ui_backend=socket` 模式没有触发 shell 降级（仓库日志里会打印）。
+
+通过即说明 a11y tree 与截图的 socket 路径已在云端跑通。
+
+---
+
+### 是否要立刻启动路径 B / C 的探讨
+
+视运行规模决定：
+- 单用户 / ≤3 台手机 / 主要是开发验证：**停在路径 A**。
+- 多用户 / 十台以上手机 / 需要并发共享设备：**启动路径 B**（gateway）。
+- 跨大区部署、公网带宽紧张、agent 决策频率高：**考虑路径 C**。
+
+本文档聚焦"能跑通 + 不降级 socket 后端"这一首要目标，推荐按路径 A 落地后再评估是否升级。
+