xt-cli 0.2.1__py3-none-any.whl

__init__.py

@@ -0,0 +1,5 @@
+"""xt-cli package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.1"

__main__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cli.py

@@ -0,0 +1,342 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable
+from typing import Sequence
+
+from __init__ import __version__
+from errors import XtCliError
+
+_TASK_REGISTRY: dict[str, tuple[Callable[..., int], bool, Callable[[argparse.ArgumentParser], None] | None, str | None, str, int]] = {}
+_SCOPE_PARSERS: dict[str, Callable[[argparse.ArgumentParser], None]] = {}
+
+
+def register_scope_parser(source: str, fn: Callable[[argparse.ArgumentParser], None]) -> None:
+    """注册 scope 级 parser。"""
+    _SCOPE_PARSERS[source] = fn
+
+
+def register_task(
+    name: str,
+    handler: Callable[..., int],
+    *,
+    independent: bool = False,
+    add_parser: Callable[[argparse.ArgumentParser], None] | None = None,
+    help: str | None = None,
+    source: str = "builtin",
+    priority: int = 100,
+) -> None:
+    """注册 task 及其处理函数。"""
+    _TASK_REGISTRY[name] = (handler, independent, add_parser, help, source, priority)
+
+
+def add_shared_args_builtin(parser: argparse.ArgumentParser) -> None:
+    """内置共享 option——所有 builtin task 均可访问。
+
+    当前暂无内置共享 option 需求，此处仅做示例。
+    取消注释即可激活：
+        parser.add_argument("--builtin_shared", action="store_true", help="builtin shared option example")
+    """
+    pass
+
+# 注册内置 scope parser
+register_scope_parser("builtin", add_shared_args_builtin)
+
+
+def _build_global_parser(add_help: bool) -> argparse.ArgumentParser:
+    """构建仅含全局 option 的 parser（无 subparser），用于 pass 1 预解析。"""
+    parser = argparse.ArgumentParser(
+        prog="xt",
+        usage="xt [GLOBAL OPTIONS] TASK [TASK OPTIONS] ...",
+        description=f"xt command line interface\nversion: {__version__}",
+        formatter_class=argparse.RawTextHelpFormatter,
+        epilog="The sdk directory must contain .xt-sdk-version.",
+        add_help=add_help,
+    )
+    parser.add_argument("--version", action="version", version=f"xt cli {__version__}")
+
+    global_group = parser.add_argument_group("global options")
+    global_group.add_argument("--target", "-t", metavar="<target>", help="Target name or path\ne.g. windows/simulator")
+    global_group.add_argument("--sdk", metavar="<path>", help="SDK directory path\ne.g. D:/work/xt-sdk")
+    global_group.add_argument("--toolchain-path", dest="toolchain_path", metavar="<path>", help="Toolchain directory path")
+    global_group.add_argument("--project", "-p", metavar="<path>", help="Project directory path")
+    global_group.add_argument("--board", metavar="<board>", help="Board name, if add_deps(\"xt_board\")\ne.g. e837n_v01")
+    global_group.add_argument("--dirty", action="store_true", help="Allow building with dirty repositories")
+    global_group.add_argument("--no-track", action="store_true",
+                              help="Skip updating xt_vers.jsonc for this build")
+    global_group.add_argument("--strict", action="store_true",
+                              help="Strict mode: enforce all constraints, abort on dirty")
+    global_group.add_argument("--sync-deps", action="store_true",
+                              help="Checkout repos to match xt_deps.jsonc versions before build")
+
+    return parser
+
+
+def _source_rank(source: str) -> int:
+    """返回 source 在 help 列表中的排序权重。"""
+    if source == "builtin":
+        return 0
+    if source.startswith("platform"):
+        return 1
+    if source == "project":
+        return 2
+    return 99
+
+
+def _build_task_parser(add_help: bool) -> argparse.ArgumentParser:
+    """构建带 subparser 的 parser——全局 option + 各 task 作为 subcommand。
+
+    用于：1) 预扫描 --help 显示含 subcommand 的全局帮助
+          2) 逐段解析 task_args
+
+    task 按 source 分组（builtin → platform → project），每组内按 priority 排序。
+    """
+    parser = _build_global_parser(add_help)
+
+    # 顶层 scope options 分组（xt --help 可见）
+    for source in sorted(_SCOPE_PARSERS.keys(), key=lambda s: _source_rank(s)):
+        group = parser.add_argument_group(f"{source} shared options")
+        _SCOPE_PARSERS[source](group)
+
+    subs = parser.add_subparsers(dest="task", title="tasks")
+    sorted_tasks = sorted(
+        _TASK_REGISTRY.items(),
+        key=lambda item: (_source_rank(item[1][4]), item[1][5], item[0]),
+    )
+    for name, (_, _independent, add_parser, help_desc, source, _priority) in sorted_tasks:
+        tagged_help = f"[{source}]  {help_desc}" if help_desc else f"[{source}]"
+        sub = subs.add_parser(name, help=tagged_help, add_help=True,
+                              formatter_class=argparse.RawTextHelpFormatter)
+
+        if add_parser is not None:
+            add_parser(sub)
+        elif source not in _SCOPE_PARSERS:
+            sub.epilog = "No task-specific options."
+
+    return parser
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """全局 parser（仅含 global option，无 subparser），用于 pass 1。"""
+    return _build_global_parser(add_help=False)
+
+
+def build_help_parser() -> argparse.ArgumentParser:
+    """带顶层 --help + subcommand 的 parser，用于预扫描路由。"""
+    return _build_task_parser(add_help=True)
+
+
+def _split_task_segments(unknown_args: list[str]) -> list[tuple[str, list[str]]]:
+    """按 task 名切分 unknown_args 为 (task_name, task_args) 段。
+
+    首个 task 之前的参数作为共享前缀追加到所有 segment。
+    """
+    segments: list[tuple[str, list[str]]] = []
+    current_task: str | None = None
+    current_args: list[str] = []
+    pre_task_args: list[str] = []
+
+    for arg in unknown_args:
+        if arg in _TASK_REGISTRY:
+            if current_task is not None:
+                segments.append((current_task, current_args))
+            else:
+                pre_task_args = list(current_args)
+            current_task = arg
+            current_args = []
+        else:
+            current_args.append(arg)
+
+    if current_task is not None:
+        segments.append((current_task, current_args))
+
+    if pre_task_args:
+        for i in range(len(segments)):
+            segments[i] = (segments[i][0], pre_task_args + segments[i][1])
+
+    return segments
+
+
+def _apply_independent(segments: list[tuple[str, list[str]]]) -> list[tuple[str, list[str]]]:
+    """若存在 independent task，仅保留该 task 段。"""
+    for name, _task_args in segments:
+        _, independent, _add_parser, _help, _source, _priority = _TASK_REGISTRY[name]
+        if independent:
+            return [(name, _task_args)]
+    return segments
+
+
+def _sort_tasks(segments: list[tuple[str, list[str]]]) -> list[tuple[str, list[str]]]:
+    """按 priority 排序（数值越小越先执行），同优先级保持用户输入顺序（stable sort）。"""
+    return sorted(segments, key=lambda x: _TASK_REGISTRY.get(x[0], (None, None, None, None, None, 99))[5])
+
+
+def _discover_hook_tasks(parsed_args: argparse.Namespace) -> None:
+    """扫描 hook 文件，自动注册自定义 task。"""
+    from context import build_context_from_options
+    from hooks import discover_hook_tasks
+
+    try:
+        context = build_context_from_options(
+            cwd=parsed_args.project,
+            project_dir=parsed_args.project,
+            sdk_dir=parsed_args.sdk,
+            target=parsed_args.target,
+            toolchain_path=parsed_args.toolchain_path,
+            board=parsed_args.board,
+        )
+    except Exception:
+        return
+
+    hook_results, scope_parsers = discover_hook_tasks(context)
+    for task_name, add_parser, source, help_desc in hook_results:
+        if task_name not in _TASK_REGISTRY:
+            _register_hook_task(task_name, source=source, add_parser=add_parser, help_desc=help_desc)
+    for source, fn in scope_parsers.items():
+        if source not in _SCOPE_PARSERS:
+            register_scope_parser(source, fn)
+
+
+def _register_hook_task(task_name: str, source: str = "project", add_parser: Callable[[argparse.ArgumentParser], None] | None = None, help_desc: str | None = None) -> None:
+    """将 hook 中的 handle_<task> 封装为标准 handler 并注册。"""
+    from constants import PRIORITY_DEFAULT
+
+    def hook_handler(context, global_args: argparse.Namespace, shared_args: argparse.Namespace, self_args: argparse.Namespace, unknown_args: list[str]) -> int:
+        from hooks import dispatch_hook
+
+        result = dispatch_hook(context, task_name, unknown_args,
+                               global_args=global_args,
+                               shared_args=shared_args,
+                               self_args=self_args)
+        if not result.handled:
+            print(f"Unknown task: {task_name}", file=sys.stderr)
+            return 1
+        return result.returncode
+
+    register_task(task_name, hook_handler, independent=False, source=source, add_parser=add_parser,
+                  help=help_desc, priority=PRIORITY_DEFAULT)
+
+
+def _execute_tasks(
+    parsed_args: argparse.Namespace,
+    segments: list[tuple[str, list[str]]],
+) -> int:
+    """按顺序执行 task 段，每段用 subparser 解析。"""
+    from context import build_context_from_options
+
+    # 先逐段解析（--help 在此阶段触发 SystemExit，避免不必要的 context 构建）
+    # 使用 bare parser（不含全局 option），确保 self_args 仅含 task 专属值
+    task_parser = argparse.ArgumentParser(add_help=False)
+    task_subs = task_parser.add_subparsers(dest="task")
+    for name, (_, _, add_parser, _, _, _) in _TASK_REGISTRY.items():
+        sub = task_subs.add_parser(name, add_help=True)
+        if add_parser:
+            add_parser(sub)
+        else:
+            sub.epilog = "No task-specific options."
+
+    parsed_segments: list[tuple[str, argparse.Namespace, argparse.Namespace, list[str]]] = []
+    shared_hook_args: list[str] = []
+
+    # 合并所有 task_args，一次性解析 shared_args——确保 shared option 不限制位置
+    combined_args: list[str] = []
+    for _, task_args in segments:
+        combined_args.extend(task_args)
+    shared_args = argparse.Namespace()
+    if _SCOPE_PARSERS:
+        scope_parser = argparse.ArgumentParser(add_help=False)
+        for source in sorted(_SCOPE_PARSERS.keys(), key=lambda s: _source_rank(s)):
+            _SCOPE_PARSERS[source](scope_parser)
+        shared_args, _ = scope_parser.parse_known_args(combined_args)
+
+    for name, task_args in segments:
+        parsed_task, hook_args = task_parser.parse_known_args([name] + task_args)
+        parsed_segments.append((name, shared_args, parsed_task, hook_args))
+        for a in hook_args:
+            if a not in shared_hook_args:
+                shared_hook_args.append(a)
+
+    # 为第一个非 independent task 构建 context
+    ctx: object = None
+    for name, _shared_args, _parsed_task, _hook_args in parsed_segments:
+        _, independent, _add_parser, _help, _source, _priority = _TASK_REGISTRY[name]
+        if not independent:
+            ctx = build_context_from_options(
+                cwd=parsed_args.project,
+                project_dir=parsed_args.project,
+                sdk_dir=parsed_args.sdk,
+                target=parsed_args.target,
+                toolchain_path=parsed_args.toolchain_path,
+                board=parsed_args.board,
+            )
+            break
+
+    for name, shared_args, parsed_task, _hook_args in parsed_segments:
+        handler, _independent, _add_parser, _help, _source, _priority = _TASK_REGISTRY[name]
+
+        # 平台专属 task 校验：source=platform/xxx 时检查当前平台匹配
+        if _source.startswith("platform/") and ctx is not None:
+            expected_platform = _source.split("/", 1)[1]
+            if getattr(ctx, "platform_name", "") != expected_platform:
+                print(f"[xt cli] Task '{name}' is only available on platform "
+                      f"'{expected_platform}', current platform is '{ctx.platform_name}'")
+                continue
+
+        rc = handler(ctx, parsed_args, shared_args, parsed_task, shared_hook_args)
+        if rc != 0:
+            return rc
+    return 0
+
+
+def _main(argv: Sequence[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+
+    # 预扫描：-h/--help 出现在任何 task 名之前 → 全局 help
+    task_idx = next((i for i, a in enumerate(args) if a in _TASK_REGISTRY), len(args))
+    if any(a in {"-h", "--help"} for a in args[:task_idx]):
+        parser = build_parser()
+        parsed_args, _ = parser.parse_known_args(args)
+        _discover_hook_tasks(parsed_args)
+        build_help_parser().parse_args(args)  # raises SystemExit
+        return 0
+
+    # 第一步：全局 parse_known_args（add_help=False，--help 流入 task 段）
+    parser = build_parser()
+    parsed_args, unknown_args = parser.parse_known_args(args)
+
+    # 扫 hook 注册自定义 task
+    _discover_hook_tasks(parsed_args)
+
+    segments = _split_task_segments(unknown_args)
+
+    if not segments:
+        if unknown_args:
+            if set(unknown_args) & {"-h", "--help"}:
+                build_help_parser().parse_args(args)
+                return 0
+            parser.error(f"unrecognized arguments: {' '.join(unknown_args)}")
+        parser.print_help()
+        return 0
+
+    segments = _apply_independent(segments)
+    segments = _sort_tasks(segments)
+
+    return _execute_tasks(parsed_args, segments)
+
+def main(argv: Sequence[str] | None = None) -> int:
+    try:
+        sys.stdout.reconfigure(line_buffering=True)
+    except Exception:
+        pass
+    try:
+        return _main(argv)
+    except XtCliError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("KeyboardInterrupt")
+        return 1
+
+# 导入命令模块触发 register_task 注册
+from commands import build_cmd, clean_cmd, config_cmd, deps_cmd, fullclean_cmd  # noqa: F401, E402

commands/build_cmd.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import argparse
+
+from cli import register_task
+from hooks import dispatch_hook
+from models import BuildContext
+from output import print_step
+from xmake import build_command, run_xmake
+
+
+def handle_build_command(context: BuildContext, global_args: argparse.Namespace, shared_args: argparse.Namespace, self_args: argparse.Namespace, unknown_args: list[str]) -> int:
+    """处理 build 命令。"""
+    # --sync-deps: 在依赖检查之前 checkout 仓库
+    sync_deps = getattr(global_args, "sync_deps", False)
+    if sync_deps:
+        from dependencies import sync_dependencies
+        dirty_allowed = getattr(global_args, "dirty", False)
+        sync_dependencies(context, dirty_allowed=dirty_allowed)
+
+    # 在 dispatch_hook 之前检查依赖版本（防止 hook 绕过）
+    from dependencies import check_dependencies, _print_warnings_box
+    dirty_allowed = getattr(global_args, "dirty", False)
+    strict = getattr(global_args, "strict", False)
+    passed, warnings = check_dependencies(context, dirty_allowed=dirty_allowed, strict=strict)
+    if not passed:
+        return 1
+
+    hook_result = dispatch_hook(context, "build", unknown_args, global_args=global_args, shared_args=shared_args, self_args=self_args)
+    if hook_result.handled:
+        return hook_result.returncode
+
+    from hooks import run_lifecycle_hook
+
+    before_ret = run_lifecycle_hook(context, "before_build", unknown_args, global_args, shared_args, self_args)
+    if before_ret != 0:
+        return before_ret
+
+    print_step("build")
+    if warnings:
+        _print_warnings_box(warnings)
+    result = run_xmake(context, build_command(context))
+
+    run_lifecycle_hook(context, "after_build", unknown_args, global_args, shared_args, self_args)
+
+    # 在 after_build hook 之后更新版本追踪（反映最终仓库状态）
+    if result.returncode == 0:
+        from dependencies import update_dependencies, _is_track_enabled
+        no_track = getattr(global_args, "no_track", False)
+        if not no_track and _is_track_enabled(context):
+            update_dependencies(context)
+
+    return result.returncode
+
+
+def add_args_build(parser: argparse.ArgumentParser) -> None:
+    """注册 build 专属 option 说明。"""
+    parser.epilog = (
+        "Global flags affecting build:\n"
+        "  --dirty      Allow building with dirty repositories (always warns)\n"
+        "  --no-track   Skip updating xt_vers.jsonc for this build\n"
+        "  --strict     Enforce all constraints as error, abort on dirty\n"
+        "  --sync-deps  Checkout repos to match xt_deps.jsonc versions before build"
+    )
+
+
+register_task("build", handle_build_command, independent=False, add_parser=add_args_build, help="Build the project", priority=20)

commands/clean_cmd.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import argparse
+
+from cli import register_task
+from hooks import dispatch_hook
+from models import BuildContext
+from output import print_step
+from xmake import build_clean_command, run_xmake
+
+
+def handle_clean_command(context: BuildContext, global_args: argparse.Namespace, shared_args: argparse.Namespace, self_args: argparse.Namespace, unknown_args: list[str]) -> int:
+    """处理 clean 命令。"""
+    hook_result = dispatch_hook(context, "clean", unknown_args, global_args=global_args, shared_args=shared_args, self_args=self_args)
+    if hook_result.handled:
+        return hook_result.returncode
+
+    from hooks import run_lifecycle_hook
+
+    before_ret = run_lifecycle_hook(context, "before_clean", unknown_args, global_args, shared_args, self_args)
+    if before_ret != 0:
+        return before_ret
+
+    print_step("clean")
+    result = run_xmake(context, build_clean_command(context))
+
+    run_lifecycle_hook(context, "after_clean", unknown_args, global_args, shared_args, self_args)
+    return result.returncode
+
+
+register_task("clean", handle_clean_command, independent=False, help="Clean build artifacts", priority=10)

commands/config_cmd.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from cli import register_task
+from config import get_config_value, reset_config_key, set_config_value
+from config import _resolve_config_store
+from constants import PRIORITY_INDEPENDENT
+from errors import CliUsageError
+from models import BuildContext
+
+
+def add_args_config(parser: argparse.ArgumentParser) -> None:
+    """注册 config 专属 option。"""
+    action_group = parser.add_mutually_exclusive_group()
+    action_group.add_argument("--get", dest="get_key", metavar="<key>", help="Get config value")
+    action_group.add_argument("--reset", dest="reset_key", metavar="<key>", help="Reset config value")
+    action_group.add_argument("--show", dest="show_config", action="store_true", help="Show all config values")
+    parser.add_argument("--platform", metavar="<platform>", help="Select platform scope")
+    parser.add_argument("--local", action="store_true", help="Use local config file")
+    parser.add_argument(
+        "--debug", dest="config_debug", metavar="<0|1>", choices=("0", "1"),
+        help="Set debug flag, 0 disables and 1 enables debug output",
+    )
+    parser.add_argument(
+        "--deps-on-version-fail", dest="deps_on_version_fail",
+        metavar="<warn|error|ignore>", choices=("warn", "error", "ignore"),
+        help="Default behavior for version constraint mismatch",
+    )
+    parser.add_argument(
+        "--deps-on-target-fail", dest="deps_on_target_fail",
+        metavar="<warn|error|ignore>", choices=("warn", "error", "ignore"),
+        help="Default behavior for target constraint mismatch",
+    )
+    parser.add_argument(
+        "--deps-track", dest="deps_track",
+        metavar="<true|false>", choices=("true", "false"),
+        help="Enable or disable xt_vers.jsonc tracking",
+    )
+
+
+def handle_config_command(context: BuildContext, global_args: argparse.Namespace, shared_args: argparse.Namespace, self_args: argparse.Namespace, unknown_args: list[str]) -> int:
+    """处理 config 命令。"""
+    cwd = Path.cwd()
+
+    if self_args.get_key is not None:
+        value, source = get_config_value(
+            key=self_args.get_key,
+            platform=self_args.platform,
+            use_local=self_args.local,
+            cwd=cwd,
+        )
+        print(f"{value} (from {source})")
+        return 0
+
+    if self_args.reset_key is not None:
+        source = reset_config_key(
+            key=self_args.reset_key,
+            platform=self_args.platform,
+            use_local=self_args.local,
+            cwd=cwd,
+        )
+        print(f"{self_args.reset_key} reset (from {source})")
+        return 0
+
+    set_key, set_value = _resolve_set_action(global_args, self_args)
+    if set_key is not None and set_value is not None:
+        source = set_config_value(
+            key=set_key,
+            value=set_value,
+            platform=self_args.platform if self_args else None,
+            use_local=self_args.local if self_args else False,
+            cwd=cwd,
+        )
+        stored_value, _ = get_config_value(
+            key=set_key,
+            platform=self_args.platform if self_args else None,
+            use_local=self_args.local if self_args else False,
+            cwd=cwd,
+        )
+        print(f"{set_key} set to {stored_value} (from {source})")
+        return 0
+
+    _show_all_config(cwd)
+    return 0
+
+
+def _resolve_set_action(parsed_global: argparse.Namespace, parsed_task) -> tuple[str | None, str | None]:
+    """解析设置动作。"""
+    set_actions = [
+        ("sdk", parsed_global.sdk),
+        ("target", parsed_global.target),
+        ("board", parsed_global.board),
+        ("debug", getattr(parsed_task, "config_debug", None) if parsed_task else None),
+        ("toolchain-path", parsed_global.toolchain_path),
+        ("deps.on_version_fail", getattr(parsed_task, "deps_on_version_fail", None) if parsed_task else None),
+        ("deps.on_target_fail", getattr(parsed_task, "deps_on_target_fail", None) if parsed_task else None),
+        ("deps.track", getattr(parsed_task, "deps_track", None) if parsed_task else None),
+    ]
+    selected_actions = [(key, value) for key, value in set_actions if value is not None]
+    if len(selected_actions) > 1:
+        raise CliUsageError("Only one config set action is allowed")
+    if not selected_actions:
+        return None, None
+    return selected_actions[0]
+
+
+def _show_all_config(cwd: Path) -> None:
+    """展示所有配置（分区：local / global / defaults）。"""
+    from config import _LOCAL_CONFIG_FILENAME
+
+    local_store = _resolve_config_store(use_local=True, cwd=cwd, home=None)
+    global_store = _resolve_config_store(use_local=False, cwd=cwd, home=None)
+
+    local_data = local_store.load_or_default()
+    global_data = global_store.load_or_default()
+
+    local_path = cwd / _LOCAL_CONFIG_FILENAME
+    global_path = global_store.path
+
+    print(f"--- Local config ({local_path}) ---")
+    if local_data:
+        _print_config_section(local_data)
+    else:
+        print("(empty)")
+
+    print(f"\n--- Global config ({global_path}) ---")
+    if global_data:
+        _print_config_section(global_data)
+    else:
+        print("(empty)")
+
+    _print_defaults_section(local_data, global_data)
+
+
+def _print_config_section(data: dict) -> None:
+    """输出配置段内容。"""
+    for key in sorted(data):
+        if key == "config_version":
+            continue
+        value = data[key]
+        if key == "toolchains" and isinstance(value, dict):
+            for platform in sorted(value):
+                print(f"toolchain-path ({platform}) = {value[platform]}")
+        elif key == "deps_configs" and isinstance(value, dict):
+            for sub_key in sorted(value):
+                print(f"deps.{sub_key} = {value[sub_key]}")
+        else:
+            print(f"{key} = {value}")
+
+
+_REGISTERED_KEYS = [
+    "sdk", "target", "board", "debug", "toolchain-path",
+    "deps.on_version_fail", "deps.on_target_fail", "deps.track",
+]
+
+_DEFAULT_VALUES = {
+    "target": "windows/simulator",
+    "board": "(not set)",
+    "debug": 0,
+    "deps.on_version_fail": "warn",
+    "deps.on_target_fail": "warn",
+    "deps.track": False,
+}
+
+
+def _print_defaults_section(local_data: dict, global_data: dict) -> None:
+    """输出默认值段（仅显示本地和全局中均未设置的键）。"""
+    lines: list[str] = []
+    for key in _REGISTERED_KEYS:
+        if key == "toolchain-path":
+            continue
+        value = _resolve_best_value(key, local_data, global_data)
+        if value is not None:
+            continue
+        default = _DEFAULT_VALUES.get(key, "(not set)")
+        lines.append(f"{key} = {default}")
+
+    if lines:
+        print("\n--- Defaults ---")
+        for line in lines:
+            print(line)
+
+
+def _resolve_best_value(key: str, local_data: dict, global_data: dict):
+    """从 local/global 数据中解析最佳值。"""
+    if key.startswith("deps."):
+        sub_key = key[5:]
+        for data in (local_data, global_data):
+            deps = data.get("deps_configs")
+            if isinstance(deps, dict) and sub_key in deps:
+                return deps[sub_key]
+        return None
+
+    for data in (local_data, global_data):
+        if key in data:
+            return data[key]
+    return None
+
+
+register_task("config", handle_config_command, independent=True, add_parser=add_args_config, help="Configure settings", priority=PRIORITY_INDEPENDENT)