fh_tool-cli 0.2.3__tar.gz → 0.2.5__tar.gz

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fh_tool-cli
-Version: 0.2.3
+Version: 0.2.5
 Summary: 用于本地管理 FiberHome fh_tool 接口的 Python CLI
 Author: Gxxk
 License-Expression: AGPL-3.0-or-later
@@ -82,11 +82,12 @@ fh-tool dev-info --ip 192.168.1.1 --mac AABBCCDDEEFF
 
 ## 常用命令
 
-低风险 probe：
+低风险 probe（输出 `fh_port`/`fh_port_source` 与各候选端口 `fh_ports` 明细，可用于诊断 fh_tool API 所在端口）：
 
 ```bash
 fh-tool probe
 fh-tool probe --json
+fh-tool probe --fh-port 80
 ```
 
 读取设备信息：
@@ -129,6 +130,29 @@ fh-tool telnet enable --confirm
 fh-tool ports --ports 23,80,443,8080
 ```
 
+## fh_tool 端口与型号/固件兼容性
+
+不同型号/固件的 fh_tool 后端监听端口可能不同。大多数固件在 `8080`，但例如 **HG6142A3（固件 V03.00.M0000）** 的 fh_tool API 位于 `http://192.168.1.1:80/fh_tool/api`（80 端口）。
+
+工具默认行为：
+
+1. 先尝试默认端口 `8080`；
+2. 仅当 `8080` TCP 不可达时，自动探测候选端口（当前为 `80`，用 `GetDevInfo` / HTTP surface 验证），并在结果 JSON 的 `fh_port`/`fh_port_source` 字段中说明最终使用的端口和来源（`argument`/`default`/`auto_detected`/`default_unverified`）；
+3. 探测失败时沿用 `8080` 并在错误信息中给出引导。
+
+也可以显式指定端口（跳过探测）：
+
+```bash
+fh-tool dev-info --fh-port 80
+fh-tool call --func GetDevInfo --fh-port 80
+```
+
+已知局限：
+
+- 如果 `8080` 与 `80` 同时 TCP 开放、但 fh_tool API 只在 `80`，TCP 快筛会停留在 `8080` 并以 HTTP/解密错误失败，此时需要 `--fh-port 80` 显式指定；`fh-tool probe --json` 的 `fh_ports` 字段可以诊断这种场景。
+- 设备返回的绝对下载 URL（含端口）按原样使用，不会重写端口。
+- `HTTP 4xx/5xx`、解密失败不会触发端口切换——那说明 8080 上有 HTTP 服务，问题在路径/协议/MAC 而非端口。
+
 ## 本地 VM 测试环境
 
 如果已经在 `/mnt/dev-cold/HG5143F-ONU-vm` 启动本地 userspace VM，可直接用它测试 `cfg_cmd` 和 Web AJAX，不需要碰真实网关：
@@ -151,6 +175,18 @@ fh-tool wan list --backend local-vm
 
 `local-vm` 只是在本机 proot VM 内执行厂商 `cfg_cmd`。`--vm-root` 必须指向 VM 工作区目录，也就是包含 `bin/proot-shell` 和 `rootfs-vm/fhrom/bin/cfg_cmd` 的目录；默认是 `/mnt/dev-cold/HG5143F-ONU-vm`。不要把它指到里面的 `rootfs-vm/`。
 
+也可以从 HG5143F 原始 MTD dump 构建同类 userspace VM。`collect` 默认只输出 dry-run 计划，不读 flash；真正采集必须加 `--confirm`，自动开启 Telnet 也必须显式加 `--auto-enable-telnet --confirm`：
+
+```bash
+fh-tool vm collect --ip 192.168.1.1 --output ./hg5143f-dumps
+fh-tool vm collect --ip 192.168.1.1 --output ./hg5143f-dumps --auto-enable-telnet --confirm
+fh-tool vm build --dump-dir ./hg5143f-dumps --output ./HG5143F-ONU-vm
+fh-tool vm verify --vm-root ./HG5143F-ONU-vm
+fh-tool vm verify --vm-root ./HG5143F-ONU-vm --with-fhapi --with-http
+```
+
+`vm build` 需要 `ubireader_extract_images`、`ubireader_extract_files`、`unsquashfs`、`jefferson`、`qemu-arm-static` 和 `proot`。输出目录会包含 `rootfs-vm/`、`source/`、`logs/`、`bin/`、`build-manifest.json`、`verify-manifest.json` 和 `events.ndjson`。生成的 VM 是 32-bit ARM userspace under `qemu-arm-static`/`proot -0`，不是完整板级 QEMU 启动；默认不会运行完整 `/etc/rc.d/rcS`。
+
 Web AJAX 读取命令只读。需要复用已有 Web session 时加 `--sessionid`；需要登录时可显式传 `--password-stdin` 或 `--password`。未显式提供密码时默认 `--username useradmin --password-source auto`，会依次尝试 `GetAdminAccount` 和 cfg 路径读取 Web superadmin 密码；cfg 来源需要 Telnet 时会默认使用 HG5143F 派生 Telnet 凭据 fallback，可用 `--no-derived-credentials` 关闭。失败不会阻塞只读抓取，并会在结果里返回脱敏 login summary。sessionid、密码、LOID、PPPoE 等敏感字段默认会脱敏；只有显式加 `--reveal-secrets` 才输出明文。
 
 后台 AJAX 接口发现以 live discovery 为主路径，不需要 HAR，也不需要 rootfs：

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.5}/README.md

@@ -66,11 +66,12 @@ fh-tool dev-info --ip 192.168.1.1 --mac AABBCCDDEEFF
 
 ## 常用命令
 
-低风险 probe：
+低风险 probe（输出 `fh_port`/`fh_port_source` 与各候选端口 `fh_ports` 明细，可用于诊断 fh_tool API 所在端口）：
 
 ```bash
 fh-tool probe
 fh-tool probe --json
+fh-tool probe --fh-port 80
 ```
 
 读取设备信息：
@@ -113,6 +114,29 @@ fh-tool telnet enable --confirm
 fh-tool ports --ports 23,80,443,8080
 ```
 
+## fh_tool 端口与型号/固件兼容性
+
+不同型号/固件的 fh_tool 后端监听端口可能不同。大多数固件在 `8080`，但例如 **HG6142A3（固件 V03.00.M0000）** 的 fh_tool API 位于 `http://192.168.1.1:80/fh_tool/api`（80 端口）。
+
+工具默认行为：
+
+1. 先尝试默认端口 `8080`；
+2. 仅当 `8080` TCP 不可达时，自动探测候选端口（当前为 `80`，用 `GetDevInfo` / HTTP surface 验证），并在结果 JSON 的 `fh_port`/`fh_port_source` 字段中说明最终使用的端口和来源（`argument`/`default`/`auto_detected`/`default_unverified`）；
+3. 探测失败时沿用 `8080` 并在错误信息中给出引导。
+
+也可以显式指定端口（跳过探测）：
+
+```bash
+fh-tool dev-info --fh-port 80
+fh-tool call --func GetDevInfo --fh-port 80
+```
+
+已知局限：
+
+- 如果 `8080` 与 `80` 同时 TCP 开放、但 fh_tool API 只在 `80`，TCP 快筛会停留在 `8080` 并以 HTTP/解密错误失败，此时需要 `--fh-port 80` 显式指定；`fh-tool probe --json` 的 `fh_ports` 字段可以诊断这种场景。
+- 设备返回的绝对下载 URL（含端口）按原样使用，不会重写端口。
+- `HTTP 4xx/5xx`、解密失败不会触发端口切换——那说明 8080 上有 HTTP 服务，问题在路径/协议/MAC 而非端口。
+
 ## 本地 VM 测试环境
 
 如果已经在 `/mnt/dev-cold/HG5143F-ONU-vm` 启动本地 userspace VM，可直接用它测试 `cfg_cmd` 和 Web AJAX，不需要碰真实网关：
@@ -135,6 +159,18 @@ fh-tool wan list --backend local-vm
 
 `local-vm` 只是在本机 proot VM 内执行厂商 `cfg_cmd`。`--vm-root` 必须指向 VM 工作区目录，也就是包含 `bin/proot-shell` 和 `rootfs-vm/fhrom/bin/cfg_cmd` 的目录；默认是 `/mnt/dev-cold/HG5143F-ONU-vm`。不要把它指到里面的 `rootfs-vm/`。
 
+也可以从 HG5143F 原始 MTD dump 构建同类 userspace VM。`collect` 默认只输出 dry-run 计划，不读 flash；真正采集必须加 `--confirm`，自动开启 Telnet 也必须显式加 `--auto-enable-telnet --confirm`：
+
+```bash
+fh-tool vm collect --ip 192.168.1.1 --output ./hg5143f-dumps
+fh-tool vm collect --ip 192.168.1.1 --output ./hg5143f-dumps --auto-enable-telnet --confirm
+fh-tool vm build --dump-dir ./hg5143f-dumps --output ./HG5143F-ONU-vm
+fh-tool vm verify --vm-root ./HG5143F-ONU-vm
+fh-tool vm verify --vm-root ./HG5143F-ONU-vm --with-fhapi --with-http
+```
+
+`vm build` 需要 `ubireader_extract_images`、`ubireader_extract_files`、`unsquashfs`、`jefferson`、`qemu-arm-static` 和 `proot`。输出目录会包含 `rootfs-vm/`、`source/`、`logs/`、`bin/`、`build-manifest.json`、`verify-manifest.json` 和 `events.ndjson`。生成的 VM 是 32-bit ARM userspace under `qemu-arm-static`/`proot -0`，不是完整板级 QEMU 启动；默认不会运行完整 `/etc/rc.d/rcS`。
+
 Web AJAX 读取命令只读。需要复用已有 Web session 时加 `--sessionid`；需要登录时可显式传 `--password-stdin` 或 `--password`。未显式提供密码时默认 `--username useradmin --password-source auto`，会依次尝试 `GetAdminAccount` 和 cfg 路径读取 Web superadmin 密码；cfg 来源需要 Telnet 时会默认使用 HG5143F 派生 Telnet 凭据 fallback，可用 `--no-derived-credentials` 关闭。失败不会阻塞只读抓取，并会在结果里返回脱敏 login summary。sessionid、密码、LOID、PPPoE 等敏感字段默认会脱敏；只有显式加 `--reveal-secrets` 才输出明文。
 
 后台 AJAX 接口发现以 live discovery 为主路径，不需要 HAR，也不需要 rootfs：

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fh_tool-cli"
-version = "0.2.3"
+version = "0.2.5"
 description = "用于本地管理 FiberHome fh_tool 接口的 Python CLI"
 readme = "README.md"
 requires-python = ">=3.11"

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.5}/src/fh_tool_cli/__init__.py

@@ -1,3 +1,3 @@
 """Local CLI for FiberHome fh_tool endpoints."""
 
-__version__ = "0.2.1"
+__version__ = "0.2.5"

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.5}/src/fh_tool_cli/argparse_utils.py

@@ -25,6 +25,16 @@ def parse_ports(value: str) -> list[int]:
     return ports
 
 
+def normalize_port(value: str) -> int:
+    try:
+        port = int(value, 10)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"不符规范的 port: {value}") from exc
+    if not 1 <= port <= 65535:
+        raise argparse.ArgumentTypeError(f"port 超出范围: {value}")
+    return port
+
+
 def parse_scalar(value: str) -> Any:
     lowered = value.lower()
     if lowered == "true":

fh_tool_cli-0.2.5/src/fh_tool_cli/backends/fh_tool.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import argparse
+import logging
+from typing import Any
+
+import requests
+
+from ..client import tcp_open
+from ..config_store import format_mac, resolve_ip, resolve_mac
+from ..crypto import decrypt_payload, derive_crypto, encrypt_payload
+from ..errors import FHToolError
+from ..fh_endpoints import (
+    DEFAULT_FH_TOOL_PORT,
+    FALLBACK_FH_TOOL_PORTS,
+    PORT_PROBE_TCP_TIMEOUT,
+    fh_tool_url,
+)
+from ..output import log_event
+
+FH_TOOL_API_PATH = "/fh_tool/api"
+FH_TOOL_UPLOAD_PATH = "/fh_tool/upload"
+TOOL_DOWNLOAD_PATH = "/fh_tool/tool_download"
+SURFACE_PROBE_PATHS = (FH_TOOL_API_PATH, FH_TOOL_UPLOAD_PATH, TOOL_DOWNLOAD_PATH)
+
+
+def fh_tool_call(
+    ip: str,
+    mac: str,
+    payload: dict[str, Any],
+    timeout: float,
+    *,
+    port: int = DEFAULT_FH_TOOL_PORT,
+) -> dict[str, Any]:
+    crypto = derive_crypto(mac)
+    encrypted = encrypt_payload(payload, crypto)
+    url = fh_tool_url(ip, port, FH_TOOL_API_PATH)
+    func = str(payload.get("func", "unknown"))
+    log_event(logging.INFO, "fh_tool.api.request", ip=ip, port=port, path=FH_TOOL_API_PATH, func=func)
+    try:
+        response = requests.post(
+            url,
+            data=encrypted,
+            headers={
+                "Content-Type": "text/plain",
+                "Connection": "close",
+            },
+            timeout=timeout,
+            allow_redirects=False,
+        )
+    except requests.RequestException as exc:
+        log_event(logging.INFO, "fh_tool.api.error", ip=ip, path=FH_TOOL_API_PATH, func=func, error=str(exc))
+        raise FHToolError(f"无法连接 {url}: {exc}") from exc
+
+    if response.status_code != 200:
+        log_event(
+            logging.INFO,
+            "fh_tool.api.http_error",
+            ip=ip,
+            path=FH_TOOL_API_PATH,
+            func=func,
+            status_code=response.status_code,
+        )
+        raise FHToolError(f"{FH_TOOL_API_PATH} 返回 HTTP {response.status_code}")
+
+    try:
+        result = decrypt_payload(response.text, crypto)
+    except Exception as exc:
+        log_event(logging.INFO, "fh_tool.api.decrypt_error", ip=ip, path=FH_TOOL_API_PATH, func=func)
+        raise FHToolError("响应解密失败，MAC 可能不匹配或固件协议不同") from exc
+    log_event(
+        logging.INFO,
+        "fh_tool.api.response",
+        ip=ip,
+        path=FH_TOOL_API_PATH,
+        func=func,
+        status_code=response.status_code,
+        result=result.get("result") if isinstance(result, dict) else None,
+    )
+    return result
+
+
+def api_payload(func: str, params: dict[str, Any] | None = None, index: str = "1") -> dict[str, Any]:
+    payload: dict[str, Any] = {"index": str(index), "func": func}
+    if params:
+        payload.update(params)
+    return payload
+
+
+def verify_fh_tool_port(ip: str, port: int, mac: str, timeout: float) -> bool:
+    try:
+        result = fh_tool_call(ip, mac, api_payload("GetDevInfo"), timeout, port=port)
+    except FHToolError:
+        return False
+    return result.get("result") == 0
+
+
+def _surface_reachable(ip: str, port: int, timeout: float) -> bool:
+    url = fh_tool_url(ip, port, FH_TOOL_API_PATH)
+    try:
+        response = requests.get(url, timeout=timeout, allow_redirects=False)
+    except requests.RequestException:
+        return False
+    log_event(logging.DEBUG, "fh_tool.port.surface", ip=ip, port=port, status_code=response.status_code)
+    return True
+
+
+def resolve_fh_port(
+    args: argparse.Namespace,
+    ip: str,
+    *,
+    mac: str | None = None,
+    timeout: float,
+    candidates: tuple[int, ...] = FALLBACK_FH_TOOL_PORTS,
+) -> tuple[int, str]:
+    """解析 fh_tool 后端端口：显式 --fh-port > 8080 TCP 快筛 > 候选端口探测 > 回退默认。
+
+    仅当 8080 TCP 不可达时才触发候选端口探测；HTTP 4xx/5xx、解密失败不触发切换。
+    """
+    explicit = getattr(args, "fh_port", None)
+    if explicit is not None:
+        log_event(logging.DEBUG, "fh_tool.port.explicit", ip=ip, port=explicit)
+        return explicit, "argument"
+
+    tcp_timeout = min(timeout, PORT_PROBE_TCP_TIMEOUT)
+    if tcp_open(ip, DEFAULT_FH_TOOL_PORT, tcp_timeout):
+        log_event(logging.DEBUG, "fh_tool.port.default_ok", ip=ip, port=DEFAULT_FH_TOOL_PORT)
+        return DEFAULT_FH_TOOL_PORT, "default"
+
+    tried: list[int] = []
+    for port in candidates:
+        if port == DEFAULT_FH_TOOL_PORT:
+            continue
+        tried.append(port)
+        if not tcp_open(ip, port, tcp_timeout):
+            continue
+        verified_by = "surface"
+        if mac:
+            if verify_fh_tool_port(ip, port, mac, timeout):
+                verified_by = "getdevinfo"
+            elif not _surface_reachable(ip, port, timeout):
+                continue
+        log_event(
+            logging.INFO,
+            "fh_tool.port.fallback_selected",
+            ip=ip,
+            port=port,
+            default_port=DEFAULT_FH_TOOL_PORT,
+            verified_by=verified_by,
+        )
+        return port, "auto_detected"
+
+    log_event(
+        logging.INFO,
+        "fh_tool.port.fallback_failed",
+        ip=ip,
+        tried=tried,
+        default_port=DEFAULT_FH_TOOL_PORT,
+    )
+    return DEFAULT_FH_TOOL_PORT, "default_unverified"
+
+
+def _unverified_port_hint(exc: FHToolError) -> FHToolError:
+    candidates = ", ".join(str(port) for port in FALLBACK_FH_TOOL_PORTS)
+    return FHToolError(
+        f"{exc}\n"
+        f"（提示：已自动探测候选端口 {candidates}，未发现 fh_tool 服务。"
+        "可运行 fh-tool probe 查看各端口/路径状态，或用 --fh-port 显式指定端口；"
+        "部分型号/固件（如 HG6142A3 V03.00.M0000）的 fh_tool API 在 80 端口）"
+    )
+
+
+def probe_fh_port_candidates(
+    ip: str,
+    mac: str | None,
+    timeout: float,
+    ports: tuple[int, ...] | None = None,
+) -> dict[str, dict[str, Any]]:
+    """对候选端口逐个报告 tcp/surface/getdevinfo 状态，供 probe 命令诊断端点。"""
+    if ports is None:
+        ports = tuple(dict.fromkeys([DEFAULT_FH_TOOL_PORT, *FALLBACK_FH_TOOL_PORTS]))
+    tcp_timeout = min(timeout, PORT_PROBE_TCP_TIMEOUT)
+    report: dict[str, dict[str, Any]] = {}
+    for port in ports:
+        entry: dict[str, Any] = {
+            "tcp": tcp_open(ip, port, tcp_timeout),
+            "surface": {},
+            "getdevinfo": None,
+        }
+        for path in SURFACE_PROBE_PATHS:
+            url = fh_tool_url(ip, port, path)
+            try:
+                response = requests.get(url, timeout=timeout, allow_redirects=False)
+                entry["surface"][path] = {
+                    "status_code": response.status_code,
+                    "content_type": response.headers.get("Content-Type"),
+                }
+            except requests.RequestException as exc:
+                entry["surface"][path] = {"error": str(exc)}
+        if mac and entry["tcp"]:
+            try:
+                dev_info = fh_tool_call(ip, mac, api_payload("GetDevInfo"), timeout, port=port)
+                entry["getdevinfo"] = {
+                    "ok": dev_info.get("result") == 0,
+                    "response": dev_info,
+                }
+            except FHToolError as exc:
+                entry["getdevinfo"] = {"ok": False, "error": str(exc)}
+        report[str(port)] = entry
+    return report
+
+
+def call_method(args: argparse.Namespace, func: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+    ip, ip_source = resolve_ip(args)
+    mac, mac_source = resolve_mac(args, ip, required=True)
+    assert mac is not None
+    port, port_source = resolve_fh_port(args, ip, mac=mac, timeout=args.timeout)
+    try:
+        response = fh_tool_call(ip, mac, api_payload(func, params), args.timeout, port=port)
+    except FHToolError as exc:
+        if port_source == "default_unverified":
+            raise _unverified_port_hint(exc) from exc
+        raise
+    return {
+        "ip": ip,
+        "ip_source": ip_source,
+        "mac": format_mac(mac),
+        "mac_source": mac_source,
+        "fh_port": port,
+        "fh_port_source": port_source,
+        "request": api_payload(func, params),
+        "response": response,
+    }
+
+
+def response_download_url(response: dict[str, Any]) -> str:
+    url = response.get("Dowloadurl") or response.get("Downloadurl") or response.get("downloadurl")
+    if not isinstance(url, str) or not url:
+        raise FHToolError(f"响应中没有 Dowloadurl: {response}")
+    return url

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.5}/src/fh_tool_cli/cli.py

@@ -21,9 +21,13 @@ from .argparse_utils import parse_json_object, parse_kv, parse_ports
 from .backends.fh_tool import (
     FH_TOOL_API_PATH,
     FH_TOOL_UPLOAD_PATH,
+    TOOL_DOWNLOAD_PATH,
     api_payload,
     call_method,
     fh_tool_call,
+    fh_tool_url,
+    probe_fh_port_candidates,
+    resolve_fh_port,
     response_download_url,
 )
 from .backup import (
@@ -101,6 +105,9 @@ from .upload import (
     upload_workflow_plan,
 )
 from .output import emit
+from .vm_build import build_vm
+from .vm_collect import collect_vm_dumps
+from .vm_verify import verify_vm
 
 
 SENSITIVE_PLAN_KEY_RE = re.compile(
@@ -181,6 +188,7 @@ def command_probe(args: argparse.Namespace) -> dict[str, Any]:
     ip, ip_source = resolve_ip(args)
     mac, mac_source = resolve_mac(args, ip, required=False, allow_prompt=False)
     ports = parse_ports(args.ports)
+    fh_port, fh_port_source = resolve_fh_port(args, ip, mac=mac, timeout=args.timeout)
 
     result: dict[str, Any] = {
         "mode": "probe",
@@ -188,13 +196,16 @@ def command_probe(args: argparse.Namespace) -> dict[str, Any]:
         "ip_source": ip_source,
         "mac": format_mac(mac) if mac else None,
         "mac_source": mac_source,
+        "fh_port": fh_port,
+        "fh_port_source": fh_port_source,
         "tcp": {str(port): tcp_open(ip, port, args.timeout) for port in ports},
         "surface": {},
         "fh_tool_probe": None,
+        "fh_ports": probe_fh_port_candidates(ip, mac, args.timeout),
     }
 
-    for path in [FH_TOOL_API_PATH, FH_TOOL_UPLOAD_PATH, "/fh_tool/tool_download"]:
-        url = f"http://{ip}:8080{path}"
+    for path in [FH_TOOL_API_PATH, FH_TOOL_UPLOAD_PATH, TOOL_DOWNLOAD_PATH]:
+        url = fh_tool_url(ip, fh_port, path)
         try:
             response = requests.get(url, timeout=args.timeout, allow_redirects=False)
             result["surface"][path] = {
@@ -211,6 +222,7 @@ def command_probe(args: argparse.Namespace) -> dict[str, Any]:
                 mac,
                 api_payload("GetDevInfo"),
                 args.timeout,
+                port=fh_port,
             )
             result["fh_tool_probe"] = {
                 "func": "GetDevInfo",
@@ -294,6 +306,42 @@ def command_backup_verify(args: argparse.Namespace) -> dict[str, Any]:
     return verify_backup(Path(args.path).expanduser())
 
 
+def command_vm_collect(args: argparse.Namespace) -> dict[str, Any]:
+    confirmed = is_confirmed(args)
+    result_prefix: dict[str, Any] = {}
+    if confirmed and args.auto_enable_telnet:
+        result_prefix["auto_enable_telnet"] = call_method(args, "TelnetEnable", {"telnet": "1"})
+    result = collect_vm_dumps(
+        shell_runner=_telnet_root_shell_runner_from_args(args) if confirmed else (lambda _command: ""),
+        output_dir=Path(args.output).expanduser(),
+        confirmed=confirmed,
+        all_mtd=args.all_mtd,
+        requested_partitions=args.partition,
+        chunk_size=args.chunk_size,
+        retries=args.retries,
+    )
+    if result_prefix:
+        result.update(result_prefix)
+    return result
+
+
+def command_vm_build(args: argparse.Namespace) -> dict[str, Any]:
+    return build_vm(
+        dump_dir=Path(args.dump_dir).expanduser(),
+        output_dir=Path(args.output).expanduser(),
+        rootfs_slot=args.rootfs_slot,
+        force=args.force,
+    )
+
+
+def command_vm_verify(args: argparse.Namespace) -> dict[str, Any]:
+    return verify_vm(
+        vm_root=Path(args.vm_root).expanduser(),
+        with_fhapi=args.with_fhapi,
+        with_http=args.with_http,
+    )
+
+
 def command_restore_backup(args: argparse.Namespace) -> dict[str, Any]:
     dry_run = not is_confirmed(args)
     if args.target == "device":
@@ -771,6 +819,7 @@ def command_log_download(args: argparse.Namespace) -> dict[str, Any]:
             url_value,
             Path(args.output).expanduser(),
             args.timeout,
+            port=result["fh_port"],
         )
     return result
 
@@ -812,7 +861,7 @@ def command_download_file(args: argparse.Namespace) -> dict[str, Any]:
         output = Path(args.output).expanduser()
     else:
         output = Path.cwd() / Path(url_value.split("?", 1)[0]).name
-    result["download"] = download_to_file(result["ip"], url_value, output, args.timeout)
+    result["download"] = download_to_file(result["ip"], url_value, output, args.timeout, port=result["fh_port"])
     return result
 
 
@@ -944,14 +993,19 @@ def command_raw_call(args: argparse.Namespace) -> dict[str, Any]:
 
 def command_download_url(args: argparse.Namespace) -> dict[str, Any]:
     ip, ip_source = resolve_ip(args)
+    mac, _mac_source = resolve_mac(args, ip, required=False, allow_prompt=False)
+    fh_port, fh_port_source = resolve_fh_port(args, ip, mac=mac, timeout=args.timeout)
     return {
         "ip": ip,
         "ip_source": ip_source,
+        "fh_port": fh_port,
+        "fh_port_source": fh_port_source,
         "download": download_to_file(
             ip,
             args.url,
             Path(args.output).expanduser(),
             args.timeout,
+            port=fh_port,
         ),
     }
 
@@ -959,6 +1013,8 @@ def command_download_url(args: argparse.Namespace) -> dict[str, Any]:
 def command_upload(args: argparse.Namespace) -> dict[str, Any]:
     dry_run = not is_confirmed(args)
     ip, ip_source = resolve_ip(args)
+    mac, _mac_source = resolve_mac(args, ip, required=False, allow_prompt=False)
+    fh_port, fh_port_source = resolve_fh_port(args, ip, mac=mac, timeout=args.timeout)
     file_path = Path(args.file).expanduser()
     result = upload_file(
         ip=ip,
@@ -966,9 +1022,12 @@ def command_upload(args: argparse.Namespace) -> dict[str, Any]:
         file_path=file_path,
         sessionid=args.sessionid,
         timeout=args.timeout,
+        port=fh_port,
         dry_run=dry_run,
     )
     result["ip_source"] = ip_source
+    result["fh_port"] = fh_port
+    result["fh_port_source"] = fh_port_source
     if dry_run:
         _attach_dry_run_notice(result)
     return result
@@ -981,6 +1040,9 @@ def _command_handlers() -> dict[str, Any]:
         "command_config_decrypt": command_config_decrypt,
         "command_backup_create": command_backup_create,
         "command_backup_verify": command_backup_verify,
+        "command_vm_collect": command_vm_collect,
+        "command_vm_build": command_vm_build,
+        "command_vm_verify": command_vm_verify,
         "command_restore_backup": command_restore_backup,
         "command_credentials_derive": command_credentials_derive,
         "command_cfg_get": command_cfg_get,

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.5}/src/fh_tool_cli/click_cli.py

@@ -257,6 +257,14 @@ def _parameter_from_action(action: argparse.Action) -> click.Parameter | None:
 
 
 def _option_from_action(action: argparse.Action) -> click.Option:
+    option_strings = list(action.option_strings)
+    inferred_names = {
+        option.lstrip("-").replace("-", "_")
+        for option in option_strings
+        if option.startswith("--")
+    }
+    if action.dest not in inferred_names:
+        option_strings.append(action.dest)
     kwargs: dict[str, Any] = {
         "help": None if action.help is argparse.SUPPRESS else action.help,
         "hidden": action.help is argparse.SUPPRESS,
@@ -279,7 +287,7 @@ def _option_from_action(action: argparse.Action) -> click.Option:
             type=_type_from_action(action),
         )
 
-    return click.Option(list(action.option_strings), **kwargs)
+    return click.Option(option_strings, **kwargs)
 
 
 def _argument_from_action(action: argparse.Action) -> click.Argument:

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.5}/src/fh_tool_cli/client.py

@@ -9,6 +9,7 @@ from urllib.parse import urljoin
 import requests
 
 from .errors import FHToolError
+from .fh_endpoints import DEFAULT_FH_TOOL_PORT
 from .output import log_event
 
 
@@ -23,14 +24,21 @@ def tcp_open(ip: str, port: int, timeout: float) -> bool:
         return False
 
 
-def make_download_url(ip: str, value: str) -> str:
+def make_download_url(ip: str, value: str, port: int = DEFAULT_FH_TOOL_PORT) -> str:
     if value.startswith("http://") or value.startswith("https://"):
         return value
-    return urljoin(f"http://{ip}:8080", value)
+    return urljoin(f"http://{ip}:{port}", value)
 
 
-def download_to_file(ip: str, url_value: str, output: Path, timeout: float) -> dict[str, Any]:
-    url = make_download_url(ip, url_value)
+def download_to_file(
+    ip: str,
+    url_value: str,
+    output: Path,
+    timeout: float,
+    *,
+    port: int = DEFAULT_FH_TOOL_PORT,
+) -> dict[str, Any]:
+    url = make_download_url(ip, url_value, port)
     log_event(logging.INFO, "download.start", url=url, output=str(output))
     try:
         response = requests.get(url, timeout=timeout, stream=True)

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.5}/src/fh_tool_cli/commands/web.py

@@ -10,7 +10,7 @@ from typing import Any
 from ..account import WEB_ADMIN_PASSWORD_PATH
 from ..argparse_utils import parse_json_object, parse_kv
 from ..backends.cfg_cmd import CfgCmdBackend
-from ..backends.fh_tool import api_payload, fh_tool_call
+from ..backends.fh_tool import api_payload, fh_tool_call, resolve_fh_port
 from ..backends.local_vm import DEFAULT_VM_ROOT, LocalVmShell
 from ..backends.telnet import TelnetCredentials, TelnetShell
 from ..backends.web_ajax import DEFAULT_AJAX_PATH, DEFAULT_WEB_LOGIN_PORT, WebAjaxClient
@@ -182,7 +182,8 @@ def _web_password_from_admin_account(args: argparse.Namespace) -> str:
     ip, _ip_source = resolve_ip(args)
     mac, _mac_source = resolve_mac(args, ip, required=True, allow_prompt=True)
     assert mac is not None
-    result = fh_tool_call(ip, mac, api_payload("GetAdminAccount"), args.timeout)
+    fh_port, _fh_port_source = resolve_fh_port(args, ip, mac=mac, timeout=args.timeout)
+    result = fh_tool_call(ip, mac, api_payload("GetAdminAccount"), args.timeout, port=fh_port)
     password = _extract_password_from_mapping(result)
     if not password:
         raise FHToolError("GetAdminAccount 响应中没有可用 password 字段")

fh_tool_cli-0.2.5/src/fh_tool_cli/fh_endpoints.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+# fh_tool 后端端点常量与 URL 构造。
+# 独立成模块以避免 client.py 与 backends.fh_tool 之间的循环导入：
+# backends.fh_tool 导入 client.tcp_open，而 client.py 需要这里的默认端口。
+
+DEFAULT_FH_TOOL_PORT = 8080
+# 8080 TCP 不可达时依次尝试的候选端口；HG6142A3 V03.00.M0000 实测 fh_tool API 在 80 端口。
+FALLBACK_FH_TOOL_PORTS = (80,)
+# TCP 探测超时上限（秒），控制候选端口全部不可达时的最坏延迟。
+PORT_PROBE_TCP_TIMEOUT = 2.0
+
+
+def fh_tool_base_url(ip: str, port: int) -> str:
+    return f"http://{ip}:{port}"
+
+
+def fh_tool_url(ip: str, port: int, path: str) -> str:
+    return f"{fh_tool_base_url(ip, port)}{path}"