fh_tool-cli 0.2.1__tar.gz → 0.2.2__tar.gz

{fh_tool_cli-0.2.1/src/fh_tool_cli.egg-info → fh_tool_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fh_tool-cli
-Version: 0.2.1
+Version: 0.2.2
 Summary: 用于本地管理 FiberHome fh_tool 接口的 Python CLI
 Author: Gxxk
 License-Expression: AGPL-3.0-or-later
@@ -9,8 +9,10 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: System :: Networking
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.0
 Requires-Dist: cryptography>=42.0.0
 Requires-Dist: requests>=2.31.0
+Requires-Dist: rich>=13.7.0
 
 # fh_tool-cli
 
@@ -38,6 +40,18 @@ uv run fh-tool --help
 
 下文示例中的 `fh-tool ...` 如果是在源码目录内运行，可以统一写成 `uv run fh-tool ...`。
 
+## CLI 输出和日志
+
+CLI 入口使用 Click，错误和日志输出使用 Rich。命令结果只写 stdout；错误、警告和日志写 stderr，便于脚本把 stdout 当作数据流处理。
+
+```bash
+fh-tool --verbose probe --json
+fh-tool --quiet config show
+fh-tool --log-file fh-tool.log dev-info
+```
+
+`--json` 输出稳定的 machine-readable JSON，不混入日志或样式。当前默认人类输出仍保持 pretty JSON，以兼容已有脚本；后续可以在不影响 `--json` 的前提下逐步增加表格化输出。
+
 ## 快速配置
 
 保存默认 IP/MAC：
@@ -135,7 +149,7 @@ 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/`。
 
-Web AJAX 读取命令只读。需要复用已有 Web session 时加 `--sessionid`；需要登录时可显式传 `--password-stdin` 或 `--password`。未显式提供密码时默认 `--username useradmin --password-source auto`，会依次尝试 `GetAdminAccount` 和 cfg 路径读取 Web superadmin 密码；失败不会阻塞只读抓取。sessionid、密码、LOID、PPPoE 等敏感字段默认会脱敏；只有显式加 `--reveal-secrets` 才输出明文。
+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` 关闭。失败不会阻塞只读抓取。sessionid、密码、LOID、PPPoE 等敏感字段默认会脱敏；只有显式加 `--reveal-secrets` 才输出明文。
 
 后台 AJAX 接口发现以 live discovery 为主路径，不需要 HAR，也不需要 rootfs：
 
@@ -160,11 +174,12 @@ fh-tool web services set --service telnet --enabled 0 --confirm
 
 常规 Web 写接口优先使用 typed 参数。`web ajax post` 和 `web ajax replay` 支持任意已知或未知 AJAX method，默认只输出计划，不发 POST；执行必须加 `--confirm`，且默认拒绝空 payload。`--json-payload` 和可重复的 `--param k=v` 仍保留为固件差异逃生口，合并顺序是 typed 参数、JSON、最后 `--param` 覆盖。旧的确认参数会直接报弃用错误。
 
-Telnet/cfg/诊断命令默认不会自动套用派生凭据。如果设备仍是 HG5143F 默认 Telnet 规则，并且已提供或保存 MAC，可以显式加 `--use-derived-credentials` 作为 fallback：
+Telnet/cfg/诊断命令在未显式传 Telnet 密码时，会默认使用 HG5143F 派生 Telnet 凭据 fallback；显式传入的用户名/密码始终优先。如果设备不是该规则，或需要保留空凭据/自定义认证，可加 `--no-derived-credentials` 关闭。`--use-derived-credentials` 仍作为兼容参数接受：
 
 ```bash
-fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer --use-derived-credentials
-fh-tool wan list --use-derived-credentials
+fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer
+fh-tool wan list
+fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer --no-derived-credentials
 ```
 
 诊断命令保持只读；`ip status` 这类依赖 VM/userspace 工具的命令会分别标记每个 probe 的 `ok/output/error`，工具缺失时输出 `partial_failure=true`，不会吞掉其它已成功字段。

fh_tool_cli-0.2.1/PKG-INFO → fh_tool_cli-0.2.2/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.4
-Name: fh_tool-cli
-Version: 0.2.1
-Summary: 用于本地管理 FiberHome fh_tool 接口的 Python CLI
-Author: Gxxk
-License-Expression: AGPL-3.0-or-later
-Keywords: FiberHome,fh_tool,ONU,gateway,telecomadmin
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: System :: Networking
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-Requires-Dist: cryptography>=42.0.0
-Requires-Dist: requests>=2.31.0
-
 # fh_tool-cli
 
 本项目是本地管理 FiberHome `/fh_tool` 接口的 Python CLI，目标是快速管理/调整你自己的设备。
@@ -38,6 +24,18 @@ uv run fh-tool --help
 
 下文示例中的 `fh-tool ...` 如果是在源码目录内运行，可以统一写成 `uv run fh-tool ...`。
 
+## CLI 输出和日志
+
+CLI 入口使用 Click，错误和日志输出使用 Rich。命令结果只写 stdout；错误、警告和日志写 stderr，便于脚本把 stdout 当作数据流处理。
+
+```bash
+fh-tool --verbose probe --json
+fh-tool --quiet config show
+fh-tool --log-file fh-tool.log dev-info
+```
+
+`--json` 输出稳定的 machine-readable JSON，不混入日志或样式。当前默认人类输出仍保持 pretty JSON，以兼容已有脚本；后续可以在不影响 `--json` 的前提下逐步增加表格化输出。
+
 ## 快速配置
 
 保存默认 IP/MAC：
@@ -135,7 +133,7 @@ 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/`。
 
-Web AJAX 读取命令只读。需要复用已有 Web session 时加 `--sessionid`；需要登录时可显式传 `--password-stdin` 或 `--password`。未显式提供密码时默认 `--username useradmin --password-source auto`，会依次尝试 `GetAdminAccount` 和 cfg 路径读取 Web superadmin 密码；失败不会阻塞只读抓取。sessionid、密码、LOID、PPPoE 等敏感字段默认会脱敏；只有显式加 `--reveal-secrets` 才输出明文。
+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` 关闭。失败不会阻塞只读抓取。sessionid、密码、LOID、PPPoE 等敏感字段默认会脱敏；只有显式加 `--reveal-secrets` 才输出明文。
 
 后台 AJAX 接口发现以 live discovery 为主路径，不需要 HAR，也不需要 rootfs：
 
@@ -160,11 +158,12 @@ fh-tool web services set --service telnet --enabled 0 --confirm
 
 常规 Web 写接口优先使用 typed 参数。`web ajax post` 和 `web ajax replay` 支持任意已知或未知 AJAX method，默认只输出计划，不发 POST；执行必须加 `--confirm`，且默认拒绝空 payload。`--json-payload` 和可重复的 `--param k=v` 仍保留为固件差异逃生口，合并顺序是 typed 参数、JSON、最后 `--param` 覆盖。旧的确认参数会直接报弃用错误。
 
-Telnet/cfg/诊断命令默认不会自动套用派生凭据。如果设备仍是 HG5143F 默认 Telnet 规则，并且已提供或保存 MAC，可以显式加 `--use-derived-credentials` 作为 fallback：
+Telnet/cfg/诊断命令在未显式传 Telnet 密码时，会默认使用 HG5143F 派生 Telnet 凭据 fallback；显式传入的用户名/密码始终优先。如果设备不是该规则，或需要保留空凭据/自定义认证，可加 `--no-derived-credentials` 关闭。`--use-derived-credentials` 仍作为兼容参数接受：
 
 ```bash
-fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer --use-derived-credentials
-fh-tool wan list --use-derived-credentials
+fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer
+fh-tool wan list
+fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer --no-derived-credentials
 ```
 
 诊断命令保持只读；`ip status` 这类依赖 VM/userspace 工具的命令会分别标记每个 probe 的 `ok/output/error`，工具缺失时输出 `partial_failure=true`，不会吞掉其它已成功字段。

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fh_tool-cli"
-version = "0.2.1"
+version = "0.2.2"
 description = "用于本地管理 FiberHome fh_tool 接口的 Python CLI"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -18,8 +18,10 @@ classifiers = [
     "Topic :: System :: Networking",
 ]
 dependencies = [
+    "click>=8.1.0",
     "cryptography>=42.0.0",
     "requests>=2.31.0",
+    "rich>=13.7.0",
 ]
 
 [project.scripts]

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.2}/src/fh_tool_cli/cli.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import argparse
-import json
 import re
 import sys
 from pathlib import Path
@@ -10,6 +9,7 @@ from typing import Any, Callable
 import requests
 
 from .account import (
+    PasswordInput,
     account_show,
     read_secret_from_args,
     set_su_runtime_password,
@@ -63,9 +63,12 @@ from .config_store import (
     resolve_mac,
     save_config,
 )
+from .credential_sources import (
+    complete_hg5143f_telnet_login,
+    derive_hg5143f_su_password_from_args,
+)
 from .credentials import (
     derive_credentials,
-    derive_hg5143f_telnet,
 )
 from .diagnostics import (
     firewall_status,
@@ -97,17 +100,7 @@ from .upload import (
     upload_file_info,
     upload_workflow_plan,
 )
-
-
-def emit(data: Any, json_mode: bool) -> None:
-    if json_mode:
-        print(json.dumps(data, ensure_ascii=False, indent=2))
-        return
-
-    if isinstance(data, dict):
-        print(json.dumps(data, ensure_ascii=False, indent=2))
-    else:
-        print(data)
+from .output import emit
 
 
 SENSITIVE_PLAN_KEY_RE = re.compile(
@@ -355,18 +348,12 @@ def _telnet_credentials_from_args(args: argparse.Namespace) -> TelnetCredentials
     ip, _ip_source = resolve_ip(args)
     username = getattr(args, "username", None)
     password = _password_from_args(args)
-
-    if getattr(args, "use_derived_credentials", False):
-        mac, _mac_source = resolve_mac(args, ip, required=True)
-        assert mac is not None
-        derived = derive_hg5143f_telnet(mac)
-        if username and username != derived.username and password is None:
-            raise CliError(
-                "--use-derived-credentials 只能为默认 HG5143F Telnet 账号补齐密码；"
-                "自定义 --username 需要同时提供密码"
-            )
-        username = username or derived.username
-        password = password or derived.password
+    username, password = complete_hg5143f_telnet_login(
+        args,
+        ip=ip,
+        username=username,
+        password=password,
+    )
 
     return TelnetCredentials(
         host=ip,
@@ -525,15 +512,43 @@ def command_account_set_su_runtime_password(args: argparse.Namespace) -> dict[st
         return _write_dry_run_plan(
             "account set-su-runtime-password",
             "set-su-runtime-password 会覆写 runtime su password",
-            target={"password_input": _password_input_mode(args)},
+            target={"input_mode": _su_runtime_password_input_mode(args)},
             side_effects={"runtime_password_write": False},
         )
-    secret = read_secret_from_args(args)
+    secret, password_source = _su_runtime_password_from_args(args)
     result = set_su_runtime_password(_telnet_shell_from_args(args).run, secret.password)
     result["generated"] = secret.generated
+    result["password_source"] = password_source
     return result
 
 
+def _su_runtime_password_from_args(args: argparse.Namespace) -> tuple[PasswordInput, str]:
+    selected = [
+        getattr(args, "password", None) is not None,
+        getattr(args, "password_stdin", False),
+        getattr(args, "generate", False),
+    ]
+    if any(selected):
+        secret = read_secret_from_args(args)
+        if getattr(args, "password", None) is not None:
+            return secret, "argument"
+        if getattr(args, "password_stdin", False):
+            return secret, "stdin"
+        return secret, "generate"
+    ip, _ip_source = resolve_ip(args)
+    return PasswordInput(
+        derive_hg5143f_su_password_from_args(args, ip=ip),
+        generated=False,
+    ), "derived-hg5143f-su"
+
+
+def _su_runtime_password_input_mode(args: argparse.Namespace) -> str:
+    mode = _password_input_mode(args)
+    if mode == "required_on_confirm":
+        return "derived-hg5143f-su-on-confirm"
+    return mode
+
+
 def command_autoupdate_status(args: argparse.Namespace) -> dict[str, Any]:
     return autoupdate_status(
         _cfg_backend_from_args(args),
@@ -1017,18 +1032,9 @@ def add_api_command(
 
 
 def main(argv: list[str] | None = None) -> int:
-    args = parse_args(argv)
-    try:
-        result = args.handler(args)
-    except (argparse.ArgumentTypeError, CliError, FHToolError, ValueError) as exc:
-        print(f"错误: {exc}", file=sys.stderr)
-        return 2
-    except KeyboardInterrupt:
-        print("已取消", file=sys.stderr)
-        return 130
-
-    emit(result, getattr(args, "json", False))
-    return 0
+    from .click_cli import run_click_cli
+
+    return run_click_cli(argv, _command_handlers())
 
 
 if __name__ == "__main__":

fh_tool_cli-0.2.2/src/fh_tool_cli/click_cli.py

@@ -0,0 +1,297 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from types import SimpleNamespace
+from typing import Any, Callable
+
+import click
+
+from .errors import CliError, FHToolError
+from .output import configure_logging, emit, emit_cancelled, emit_error
+from .parser import HandlerMap, build_parser
+
+
+CONTEXT_SETTINGS = {
+    "help_option_names": ["-h", "--help"],
+    "ignore_unknown_options": False,
+}
+
+
+class FHToolClickError(click.ClickException):
+    exit_code = 2
+
+    def show(self, file: Any | None = None) -> None:
+        emit_error(self.format_message())
+
+
+class ArgparseParamType(click.ParamType):
+    name = "value"
+
+    def __init__(
+        self,
+        converter: Callable[[str], Any] | None = None,
+        *,
+        choices: list[Any] | tuple[Any, ...] | None = None,
+    ) -> None:
+        self.converter = converter
+        self.choices = tuple(choices or ())
+
+    def convert(self, value: Any, param: click.Parameter | None, ctx: click.Context | None) -> Any:
+        if value is None:
+            return None
+        try:
+            converted = self.converter(value) if self.converter else value
+        except argparse.ArgumentTypeError as exc:
+            self.fail(str(exc), param, ctx)
+        except ValueError as exc:
+            self.fail(str(exc), param, ctx)
+
+        if self.choices and converted not in self.choices:
+            choices = ", ".join(str(item) for item in self.choices)
+            self.fail(f"must be one of: {choices}", param, ctx)
+        return converted
+
+
+def build_click_cli(handlers: HandlerMap) -> click.Group:
+    parser = build_parser(handlers)
+    command = _command_from_parser(parser, name="fh-tool", fixed={}, help_text=parser.description)
+    if not isinstance(command, click.Group):
+        raise TypeError("root parser must produce a Click group")
+
+    command.params.insert(
+        0,
+        click.Option(
+            ["--log-file"],
+            help="写入日志文件",
+        ),
+    )
+    command.params.insert(
+        0,
+        click.Option(
+            ["-q", "--quiet"],
+            count=True,
+            help="减少非结果输出",
+        ),
+    )
+    command.params.insert(
+        0,
+        click.Option(
+            ["-v", "--verbose"],
+            count=True,
+            help="增加日志详细度，可重复",
+        ),
+    )
+    return command
+
+
+def run_click_cli(argv: list[str] | None, handlers: HandlerMap) -> int:
+    command = build_click_cli(handlers)
+    effective_args = list(sys.argv[1:] if argv is None else argv)
+    if not effective_args:
+        effective_args = ["--help"]
+    try:
+        result = command.main(args=effective_args, prog_name="fh-tool", standalone_mode=False)
+    except click.ClickException as exc:
+        if isinstance(exc, FHToolClickError):
+            exc.show()
+        else:
+            emit_error(exc.format_message())
+        return exc.exit_code
+    except KeyboardInterrupt:
+        emit_cancelled()
+        return 130
+    return result if isinstance(result, int) else 0
+
+
+def _command_from_parser(
+    parser: argparse.ArgumentParser,
+    *,
+    name: str,
+    fixed: dict[str, Any],
+    help_text: str | None,
+) -> click.Command:
+    subparsers = _subparsers_action(parser)
+    params = [_parameter_from_action(action) for action in _parser_parameter_actions(parser)]
+    params = [param for param in params if param is not None]
+
+    if subparsers is None:
+        return click.Command(
+            name=name,
+            params=params,
+            callback=_leaf_callback(parser, fixed),
+            help=help_text,
+            context_settings=CONTEXT_SETTINGS,
+        )
+
+    handler = parser._defaults.get("handler")
+    group = click.Group(
+        name=name,
+        params=params,
+        callback=_group_callback(parser, fixed) if handler is not None else _parent_callback(fixed),
+        invoke_without_command=handler is not None,
+        no_args_is_help=handler is None,
+        help=help_text,
+        context_settings=CONTEXT_SETTINGS,
+    )
+    for child_name, child_parser in subparsers.choices.items():
+        child_fixed = {**fixed, subparsers.dest: child_name}
+        child_help = _subparser_help(subparsers, child_name)
+        child = _command_from_parser(
+            child_parser,
+            name=child_name,
+            fixed=child_fixed,
+            help_text=child_help,
+        )
+        group.add_command(child, name=child_name)
+    return group
+
+
+def _parent_callback(fixed: dict[str, Any]) -> Callable[..., None]:
+    @click.pass_context
+    def callback(ctx: click.Context, **kwargs: Any) -> None:
+        configure_logging(
+            verbose=int(kwargs.pop("verbose", 0) or 0),
+            quiet=int(kwargs.pop("quiet", 0) or 0),
+            log_file=kwargs.pop("log_file", None),
+        )
+        state = ctx.ensure_object(dict)
+        state.update(fixed)
+        state.update(_normalize_click_values(kwargs))
+
+    return callback
+
+
+def _group_callback(parser: argparse.ArgumentParser, fixed: dict[str, Any]) -> Callable[..., int | None]:
+    @click.pass_context
+    def callback(ctx: click.Context, **kwargs: Any) -> int | None:
+        configure_logging(
+            verbose=int(kwargs.pop("verbose", 0) or 0),
+            quiet=int(kwargs.pop("quiet", 0) or 0),
+            log_file=kwargs.pop("log_file", None),
+        )
+        state = ctx.ensure_object(dict)
+        state.update(fixed)
+        state.update(_normalize_click_values(kwargs))
+        if ctx.invoked_subcommand is not None:
+            return None
+        return _run_parser_handler(parser, state)
+
+    return callback
+
+
+def _leaf_callback(parser: argparse.ArgumentParser, fixed: dict[str, Any]) -> Callable[..., int]:
+    @click.pass_context
+    def callback(ctx: click.Context, **kwargs: Any) -> int:
+        state = ctx.ensure_object(dict)
+        state.update(fixed)
+        state.update(_normalize_click_values(kwargs))
+        return _run_parser_handler(parser, state)
+
+    return callback
+
+
+def _run_parser_handler(parser: argparse.ArgumentParser, values: dict[str, Any]) -> int:
+    args_values = dict(parser._defaults)
+    args_values.update(values)
+    handler = args_values.get("handler")
+    if handler is None:
+        raise FHToolClickError("missing command handler")
+    args = SimpleNamespace(**args_values)
+
+    try:
+        result = handler(args)
+    except (argparse.ArgumentTypeError, CliError, FHToolError, ValueError) as exc:
+        raise FHToolClickError(str(exc)) from exc
+
+    emit(result, bool(getattr(args, "json", False)))
+    return 0
+
+
+def _normalize_click_values(values: dict[str, Any]) -> dict[str, Any]:
+    normalized: dict[str, Any] = {}
+    for key, value in values.items():
+        if isinstance(value, tuple):
+            normalized[key] = list(value)
+        else:
+            normalized[key] = value
+    return normalized
+
+
+def _subparsers_action(parser: argparse.ArgumentParser) -> argparse._SubParsersAction[argparse.ArgumentParser] | None:
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            return action
+    return None
+
+
+def _parser_parameter_actions(parser: argparse.ArgumentParser) -> list[argparse.Action]:
+    return [
+        action
+        for action in parser._actions
+        if not isinstance(action, (argparse._HelpAction, argparse._SubParsersAction))
+    ]
+
+
+def _parameter_from_action(action: argparse.Action) -> click.Parameter | None:
+    if action.option_strings:
+        return _option_from_action(action)
+    return _argument_from_action(action)
+
+
+def _option_from_action(action: argparse.Action) -> click.Option:
+    kwargs: dict[str, Any] = {
+        "help": None if action.help is argparse.SUPPRESS else action.help,
+        "hidden": action.help is argparse.SUPPRESS,
+    }
+
+    if isinstance(action, argparse._StoreTrueAction):
+        kwargs.update(is_flag=True, default=bool(action.default), flag_value=True)
+    elif isinstance(action, argparse._StoreFalseAction):
+        kwargs.update(is_flag=True, default=bool(action.default), flag_value=False)
+    elif isinstance(action, argparse._AppendAction):
+        kwargs.update(
+            multiple=True,
+            default=tuple(action.default or ()),
+            type=_type_from_action(action),
+        )
+    else:
+        kwargs.update(
+            required=bool(getattr(action, "required", False)),
+            default=None if action.default is argparse.SUPPRESS else action.default,
+            type=_type_from_action(action),
+        )
+
+    return click.Option(list(action.option_strings), **kwargs)
+
+
+def _argument_from_action(action: argparse.Action) -> click.Argument:
+    nargs = action.nargs if action.nargs is not None else 1
+    return click.Argument(
+        [action.dest],
+        required=nargs not in ("?", "*"),
+        nargs=nargs,
+        type=_type_from_action(action),
+    )
+
+
+def _type_from_action(action: argparse.Action) -> click.ParamType:
+    choices = list(action.choices) if action.choices is not None else None
+    converter = action.type
+    if converter is None and not choices:
+        return click.STRING
+    return ArgparseParamType(converter, choices=choices)
+
+
+def _subparser_help(
+    action: argparse._SubParsersAction[argparse.ArgumentParser],
+    name: str,
+) -> str | None:
+    for choice_action in action._choices_actions:
+        if choice_action.dest == name:
+            return choice_action.help
+    parser = action.choices.get(name)
+    for choice_action in action._choices_actions:
+        if action.choices.get(choice_action.dest) is parser:
+            return choice_action.help
+    return None

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.2}/src/fh_tool_cli/commands/web.py

@@ -15,6 +15,7 @@ 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
 from ..config_store import DEFAULT_CONFIG_PATH, normalize_ip, resolve_ip, resolve_mac
+from ..credential_sources import complete_hg5143f_telnet_login
 from ..errors import CliError, FHToolError
 from ..risk import dry_run_notice, is_confirmed
 from ..web_discovery import (
@@ -188,29 +189,40 @@ def _cfg_backend_from_web_args(args: argparse.Namespace) -> CfgCmdBackend:
             expensive_missing_paths=True,
         )
     ip, _ip_source = resolve_ip(args)
+    username, password = _web_telnet_login_from_args(args, ip)
     return CfgCmdBackend(
         TelnetShell(
             TelnetCredentials(
                 host=ip,
                 port=getattr(args, "telnet_port", 23),
-                username=getattr(args, "telnet_username", None),
-                password=_web_telnet_password_from_args(args),
+                username=username,
+                password=password,
                 timeout=args.timeout,
             )
         ).run
     )
 
 
-def _web_telnet_password_from_args(args: argparse.Namespace) -> str | None:
+def _web_telnet_login_from_args(
+    args: argparse.Namespace,
+    ip: str,
+) -> tuple[str | None, str | None]:
     has_password = getattr(args, "telnet_password", None) is not None
     has_stdin = getattr(args, "telnet_password_stdin", False)
     if has_password and has_stdin:
         raise CliError("cfg password source 只能选择 --telnet-password 或 --telnet-password-stdin")
+    username = getattr(args, "telnet_username", None)
+    password: str | None = None
     if has_stdin:
-        return sys.stdin.readline().rstrip("\n")
-    if has_password:
-        return str(args.telnet_password)
-    return None
+        password = sys.stdin.readline().rstrip("\n")
+    elif has_password:
+        password = str(args.telnet_password)
+    return complete_hg5143f_telnet_login(
+        args,
+        ip=ip,
+        username=username,
+        password=password,
+    )
 
 
 def _extract_password_from_mapping(value: Any) -> str | None:
@@ -557,6 +569,11 @@ def add_web_options(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--telnet-username", help="cfg 密码来源 Telnet 用户名")
     parser.add_argument("--telnet-password", help="cfg 密码来源 Telnet 密码")
     parser.add_argument("--telnet-password-stdin", action="store_true", help="从 stdin 读取 cfg 密码来源 Telnet 密码")
+    parser.add_argument(
+        "--no-derived-credentials",
+        action="store_true",
+        help="关闭 cfg 密码来源的默认 HG5143F 派生 Telnet 凭据 fallback",
+    )
     parser.add_argument("--reveal-secrets", action="store_true", help="输出 Web AJAX sensitive 明文")
     parser.add_argument("--json", action="store_true", help="输出 machine-readable JSON")
 

fh_tool_cli-0.2.2/src/fh_tool_cli/credential_sources.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import argparse
+
+from .config_store import resolve_mac
+from .credentials import HG5143F_TELNET_USERNAME, derive_hg5143f_su, derive_hg5143f_telnet
+from .errors import CliError
+
+
+def derived_credentials_enabled(args: argparse.Namespace) -> bool:
+    return not getattr(args, "no_derived_credentials", False)
+
+
+def complete_hg5143f_telnet_login(
+    args: argparse.Namespace,
+    *,
+    ip: str,
+    username: str | None,
+    password: str | None,
+    explicit_flag_name: str = "--use-derived-credentials",
+) -> tuple[str | None, str | None]:
+    if password is not None or not derived_credentials_enabled(args):
+        return username, password
+
+    explicit_derived = bool(getattr(args, "use_derived_credentials", False))
+    if username and username != HG5143F_TELNET_USERNAME:
+        if explicit_derived:
+            raise CliError(
+                f"{explicit_flag_name} 只能为默认 HG5143F Telnet 账号补齐密码；"
+                "自定义用户名需要同时提供密码"
+            )
+        return username, password
+
+    mac, _mac_source = resolve_mac(args, ip, required=True)
+    assert mac is not None
+    derived = derive_hg5143f_telnet(mac)
+    return username or derived.username, derived.password
+
+
+def derive_hg5143f_su_password_from_args(
+    args: argparse.Namespace,
+    *,
+    ip: str,
+) -> str:
+    mac, _mac_source = resolve_mac(args, ip, required=True)
+    assert mac is not None
+    return derive_hg5143f_su(mac).password

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.2}/src/fh_tool_cli/credentials.py

@@ -59,7 +59,7 @@ def derive_hg5143f_telnet(mac: str) -> DerivedCredential:
         persistent=True,
         target="telnet-login",
         confidence="high-hg5143f-local-live-verified",
-        integration_level="explicit-opt-in-telnet-fallback",
+        integration_level="automatic-telnet-fallback",
         note=(
             "Default Telnet login credential observed on HG5143F V4 firmware. "
             "Explicit CLI username/password still override it."

fh_tool_cli-0.2.2/src/fh_tool_cli/output.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+
+
+def configure_logging(*, verbose: int = 0, quiet: int = 0, log_file: str | None = None) -> None:
+    level = logging.WARNING
+    if quiet:
+        level = logging.ERROR
+    elif verbose >= 2:
+        level = logging.DEBUG
+    elif verbose == 1:
+        level = logging.INFO
+
+    handlers: list[logging.Handler] = [logging.StreamHandler(sys.stderr)]
+    if log_file:
+        path = Path(log_file).expanduser()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handlers.append(logging.FileHandler(path, encoding="utf-8"))
+
+    logging.basicConfig(
+        level=level,
+        format="%(levelname)s %(name)s: %(message)s",
+        handlers=handlers,
+        force=True,
+    )
+
+
+def emit(data: Any, json_mode: bool) -> None:
+    if json_mode or isinstance(data, dict):
+        sys.stdout.write(json.dumps(data, ensure_ascii=False, indent=2) + "\n")
+        return
+
+    sys.stdout.write(str(data) + "\n")
+
+
+def emit_error(message: str) -> None:
+    Console(file=sys.stderr).print(f"[bold red]错误:[/bold red] {message}")
+
+
+def emit_cancelled() -> None:
+    Console(file=sys.stderr).print("[yellow]已取消[/yellow]")

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.2}/src/fh_tool_cli/parser.py

@@ -118,7 +118,12 @@ def add_telnet_options(
     parser.add_argument(
         "--use-derived-credentials",
         action="store_true",
-        help="显式使用已验证的 HG5143F 派生 Telnet 凭据作为 fallback",
+        help="兼容参数；HG5143F 派生 Telnet 凭据现在默认作为 fallback",
+    )
+    parser.add_argument(
+        "--no-derived-credentials",
+        action="store_true",
+        help="关闭默认 HG5143F 派生 Telnet 凭据 fallback",
     )
 
 

fh_tool_cli-0.2.1/README.md → fh_tool_cli-0.2.2/src/fh_tool_cli.egg-info/PKG-INFO

@@ -1,3 +1,19 @@
+Metadata-Version: 2.4
+Name: fh_tool-cli
+Version: 0.2.2
+Summary: 用于本地管理 FiberHome fh_tool 接口的 Python CLI
+Author: Gxxk
+License-Expression: AGPL-3.0-or-later
+Keywords: FiberHome,fh_tool,ONU,gateway,telecomadmin
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: rich>=13.7.0
+
 # fh_tool-cli
 
 本项目是本地管理 FiberHome `/fh_tool` 接口的 Python CLI，目标是快速管理/调整你自己的设备。
@@ -24,6 +40,18 @@ uv run fh-tool --help
 
 下文示例中的 `fh-tool ...` 如果是在源码目录内运行，可以统一写成 `uv run fh-tool ...`。
 
+## CLI 输出和日志
+
+CLI 入口使用 Click，错误和日志输出使用 Rich。命令结果只写 stdout；错误、警告和日志写 stderr，便于脚本把 stdout 当作数据流处理。
+
+```bash
+fh-tool --verbose probe --json
+fh-tool --quiet config show
+fh-tool --log-file fh-tool.log dev-info
+```
+
+`--json` 输出稳定的 machine-readable JSON，不混入日志或样式。当前默认人类输出仍保持 pretty JSON，以兼容已有脚本；后续可以在不影响 `--json` 的前提下逐步增加表格化输出。
+
 ## 快速配置
 
 保存默认 IP/MAC：
@@ -121,7 +149,7 @@ 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/`。
 
-Web AJAX 读取命令只读。需要复用已有 Web session 时加 `--sessionid`；需要登录时可显式传 `--password-stdin` 或 `--password`。未显式提供密码时默认 `--username useradmin --password-source auto`，会依次尝试 `GetAdminAccount` 和 cfg 路径读取 Web superadmin 密码；失败不会阻塞只读抓取。sessionid、密码、LOID、PPPoE 等敏感字段默认会脱敏；只有显式加 `--reveal-secrets` 才输出明文。
+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` 关闭。失败不会阻塞只读抓取。sessionid、密码、LOID、PPPoE 等敏感字段默认会脱敏；只有显式加 `--reveal-secrets` 才输出明文。
 
 后台 AJAX 接口发现以 live discovery 为主路径，不需要 HAR，也不需要 rootfs：
 
@@ -146,11 +174,12 @@ fh-tool web services set --service telnet --enabled 0 --confirm
 
 常规 Web 写接口优先使用 typed 参数。`web ajax post` 和 `web ajax replay` 支持任意已知或未知 AJAX method，默认只输出计划，不发 POST；执行必须加 `--confirm`，且默认拒绝空 payload。`--json-payload` 和可重复的 `--param k=v` 仍保留为固件差异逃生口，合并顺序是 typed 参数、JSON、最后 `--param` 覆盖。旧的确认参数会直接报弃用错误。
 
-Telnet/cfg/诊断命令默认不会自动套用派生凭据。如果设备仍是 HG5143F 默认 Telnet 规则，并且已提供或保存 MAC，可以显式加 `--use-derived-credentials` 作为 fallback：
+Telnet/cfg/诊断命令在未显式传 Telnet 密码时，会默认使用 HG5143F 派生 Telnet 凭据 fallback；显式传入的用户名/密码始终优先。如果设备不是该规则，或需要保留空凭据/自定义认证，可加 `--no-derived-credentials` 关闭。`--use-derived-credentials` 仍作为兼容参数接受：
 
 ```bash
-fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer --use-derived-credentials
-fh-tool wan list --use-derived-credentials
+fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer
+fh-tool wan list
+fh-tool cfg get InternetGatewayDevice.DeviceInfo.Manufacturer --no-derived-credentials
 ```
 
 诊断命令保持只读；`ip status` 这类依赖 VM/userspace 工具的命令会分别标记每个 probe 的 `ok/output/error`，工具缺失时输出 `partial_failure=true`，不会吞掉其它已成功字段。

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.2}/src/fh_tool_cli.egg-info/SOURCES.txt

@@ -5,13 +5,16 @@ src/fh_tool_cli/account.py
 src/fh_tool_cli/argparse_utils.py
 src/fh_tool_cli/backup.py
 src/fh_tool_cli/cli.py
+src/fh_tool_cli/click_cli.py
 src/fh_tool_cli/client.py
 src/fh_tool_cli/config_decrypt.py
 src/fh_tool_cli/config_store.py
+src/fh_tool_cli/credential_sources.py
 src/fh_tool_cli/credentials.py
 src/fh_tool_cli/crypto.py
 src/fh_tool_cli/diagnostics.py
 src/fh_tool_cli/errors.py
+src/fh_tool_cli/output.py
 src/fh_tool_cli/parser.py
 src/fh_tool_cli/remote.py
 src/fh_tool_cli/risk.py
@@ -36,6 +39,7 @@ tests/test_account.py
 tests/test_backup.py
 tests/test_cfg_cmd.py
 tests/test_cli_risk.py
+tests/test_click_cli.py
 tests/test_config_decrypt.py
 tests/test_credentials.py
 tests/test_diagnostics.py

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.2}/src/fh_tool_cli.egg-info/requires.txt

@@ -1,2 +1,4 @@
+click>=8.1.0
 cryptography>=42.0.0
 requests>=2.31.0
+rich>=13.7.0

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.2}/tests/test_account.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import argparse
 import unittest
+from unittest.mock import patch
 
 from fh_tool_cli.account import (
     TELNET_PASSWORD_PATH,
@@ -12,6 +13,8 @@ from fh_tool_cli.account import (
     set_telnet_password,
 )
 from fh_tool_cli.backends.cfg_cmd import CfgCmdBackend
+from fh_tool_cli.cli import parse_args
+from fh_tool_cli.credentials import HG5143F_SU_PASSWORD_PREFIX
 from fh_tool_cli.errors import CliError
 
 
@@ -71,6 +74,50 @@ class AccountTests(unittest.TestCase):
         self.assertFalse(result["persistent"])
         self.assertEqual(len(calls), 1)
 
+    def test_set_su_runtime_password_uses_derived_default(self) -> None:
+        calls: list[str] = []
+        args = parse_args(
+            [
+                "account",
+                "set-su-runtime-password",
+                "--ip",
+                "192.168.1.1",
+                "--mac",
+                "D8F50736BC10",
+                "--confirm",
+            ]
+        )
+
+        class FakeShell:
+            def run(self, command: str) -> str:
+                calls.append(command)
+                return "ok"
+
+        with patch("fh_tool_cli.cli._telnet_shell_from_args", return_value=FakeShell()):
+            result = args.handler(args)
+
+        self.assertEqual(result["password_source"], "derived-hg5143f-su")
+        self.assertEqual(result["value"], "[REDACTED]")
+        self.assertIn(HG5143F_SU_PASSWORD_PREFIX, calls[0])
+        self.assertIn("36BC10", calls[0])
+
+    def test_set_su_runtime_password_dry_run_mentions_derived_default(self) -> None:
+        args = parse_args(
+            [
+                "account",
+                "set-su-runtime-password",
+                "--ip",
+                "192.168.1.1",
+                "--mac",
+                "D8F50736BC10",
+            ]
+        )
+
+        result = args.handler(args)
+
+        self.assertEqual(result["target"]["input_mode"], "derived-hg5143f-su-on-confirm")
+        self.assertFalse(result["executed"])
+
 
 if __name__ == "__main__":
     unittest.main()

fh_tool_cli-0.2.2/tests/test_click_cli.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import unittest
+
+from fh_tool_cli import cli
+
+
+class ClickCliTests(unittest.TestCase):
+    def test_main_uses_click_entrypoint_and_emits_json(self) -> None:
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+
+        with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+            exit_code = cli.main(["--verbose", "config", "show", "--json"])
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(stderr.getvalue(), "")
+        payload = json.loads(stdout.getvalue())
+        self.assertIn("path", payload)
+        self.assertIsInstance(payload["config"], dict)
+
+    def test_click_parameter_errors_use_cli_error_channel(self) -> None:
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+
+        with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+            exit_code = cli.main(
+                [
+                    "web",
+                    "port-mapping",
+                    "set",
+                    "--external-port",
+                    "not-a-port",
+                    "--ip",
+                    "127.0.0.1",
+                ]
+            )
+
+        self.assertEqual(exit_code, 2)
+        self.assertEqual(stdout.getvalue(), "")
+        self.assertIn("错误:", stderr.getvalue())
+        self.assertIn("port 必须是整数", stderr.getvalue())
+
+    def test_click_help_is_available(self) -> None:
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+
+        with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+            exit_code = cli.main(["--help"])
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(stderr.getvalue(), "")
+        self.assertIn("Usage: fh-tool", stdout.getvalue())
+        self.assertIn("--log-file", stdout.getvalue())
+
+    def test_no_args_shows_help_without_error(self) -> None:
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+
+        with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+            exit_code = cli.main([])
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(stderr.getvalue(), "")
+        self.assertIn("Usage: fh-tool", stdout.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()

{fh_tool_cli-0.2.1 → fh_tool_cli-0.2.2}/tests/test_credentials.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import unittest
 
 from fh_tool_cli.cli import _telnet_credentials_from_args, parse_args
+from fh_tool_cli.commands.web import _web_telnet_login_from_args
 from fh_tool_cli.credentials import (
     HG5143F_SU_PASSWORD_PREFIX,
     HG5143F_TELNET_PASSWORD_PREFIX,
@@ -21,7 +22,7 @@ class CredentialsTests(unittest.TestCase):
         self.assertEqual(credential.username, "telnetadmin")
         self.assertTrue(credential.password.startswith(HG5143F_TELNET_PASSWORD_PREFIX))
         self.assertTrue(credential.password.endswith("36BC10"))
-        self.assertEqual(credential.integration_level, "explicit-opt-in-telnet-fallback")
+        self.assertEqual(credential.integration_level, "automatic-telnet-fallback")
 
     def test_hg5143f_su_derivation_is_display_only(self) -> None:
         credential = derive_hg5143f_su("D8F50736BC10")
@@ -70,7 +71,7 @@ class CredentialsTests(unittest.TestCase):
         self.assertEqual(result["credentials"][0]["password"], "[REDACTED]")
         self.assertEqual(result["credentials"][0]["target"], "telnet-login")
 
-    def test_telnet_derived_credentials_are_explicit_fallback(self) -> None:
+    def test_telnet_derived_credentials_are_default_fallback(self) -> None:
         args = parse_args(
             [
                 "cfg",
@@ -80,7 +81,6 @@ class CredentialsTests(unittest.TestCase):
                 "192.168.1.1",
                 "--mac",
                 "D8F50736BC10",
-                "--use-derived-credentials",
             ]
         )
 
@@ -90,6 +90,25 @@ class CredentialsTests(unittest.TestCase):
         self.assertIsNotNone(credentials.password)
         self.assertTrue(credentials.password.endswith("36BC10"))
 
+    def test_telnet_derived_credentials_can_be_disabled(self) -> None:
+        args = parse_args(
+            [
+                "cfg",
+                "get",
+                "InternetGatewayDevice.DeviceInfo.Manufacturer",
+                "--ip",
+                "192.168.1.1",
+                "--mac",
+                "D8F50736BC10",
+                "--no-derived-credentials",
+            ]
+        )
+
+        credentials = _telnet_credentials_from_args(args)
+
+        self.assertIsNone(credentials.username)
+        self.assertIsNone(credentials.password)
+
     def test_explicit_telnet_password_overrides_derived_password(self) -> None:
         args = parse_args(
             [
@@ -132,6 +151,26 @@ class CredentialsTests(unittest.TestCase):
         with self.assertRaises(CliError):
             _telnet_credentials_from_args(args)
 
+    def test_web_cfg_telnet_source_uses_derived_credentials_by_default(self) -> None:
+        args = parse_args(
+            [
+                "web",
+                "ajax",
+                "get",
+                "get_base_info",
+                "--ip",
+                "192.168.1.1",
+                "--mac",
+                "D8F50736BC10",
+            ]
+        )
+
+        username, password = _web_telnet_login_from_args(args, "192.168.1.1")
+
+        self.assertEqual(username, "telnetadmin")
+        self.assertIsNotNone(password)
+        self.assertTrue(password.endswith("36BC10"))
+
 
 if __name__ == "__main__":
     unittest.main()