bykcli-plugin 1.0.0a5__py3-none-any.whl

bykcli/__init__.py

@@ -0,0 +1,5 @@
+from bykcli.core.plugin import PluginProtocol
+
+__version__ = "1.0.0a5"
+
+

bykcli/__main__.py

@@ -0,0 +1,23 @@
+"""支持 ``python -m bykcli`` 运行。"""
+
+import sys
+
+
+if __name__ == "__main__":
+    # --scan-plugins: Rust 调用的无头模式，仅扫描插件并写缓存，不启动 CLI
+    if len(sys.argv) >= 2 and sys.argv[1] == "--scan-plugins":
+        from pathlib import Path
+
+        from bykcli.infra.cache import _build_cache
+        from bykcli.infra.persistence import write_json
+
+        cache_dir = Path.home() / ".bykcli" / "cache"
+        cache_dir.mkdir(parents=True, exist_ok=True)
+
+        data = _build_cache()
+        write_json(cache_dir / "app.json", data)
+        sys.exit(0)
+
+    from bykcli.app import create_cli
+
+    create_cli()()

bykcli/api/__init__.py

@@ -0,0 +1,35 @@
+"""面向子命令和插件的公开运行时 API。"""
+
+from bykcli.api.context import CommandContext, pass_command_context, get_app_context
+from bykcli.api.paths import (
+    PathItem,
+    PathProvider,
+    register_path_provider,
+    get_path_provider,
+    global_path_items,
+)
+
+from bykcli.api.network import (
+    get_private_networks,
+    ensure_port_available,
+)
+
+from bykcli.core.state import StateStore
+
+__all__ = [
+    # 上下文
+    "CommandContext",
+    "pass_command_context",
+    "get_app_context",
+    # 路径管理
+    "PathItem",
+    "PathProvider",
+    "register_path_provider",
+    "get_path_provider",
+    "global_path_items",
+    # 网络工具
+    "get_private_networks",
+    "ensure_port_available",
+    # 状态存储
+    "StateStore",
+]

bykcli/api/context.py

@@ -0,0 +1,65 @@
+"""面向子命令的上下文封装。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from functools import update_wrapper
+import logging
+from typing import Any, Callable, TypeVar, cast
+
+import click
+
+from bykcli.app import CliState
+from bykcli.core.context import AppContext, CommandContextLike
+from bykcli.core.state import StateStore
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@dataclass(slots=True)
+class CommandContext(CommandContextLike):
+    """提供给子命令的便捷上下文。"""
+
+    name: str
+    app: AppContext
+    logger: logging.Logger
+    _state_cache: dict[str, StateStore] = field(default_factory=dict, init=False, repr=False)
+
+    def state(self, name: str = "state") -> StateStore:
+        """获取当前命令的专属存储。"""
+        if name not in self._state_cache:
+            self._state_cache[name] = self.app.command_store(self.name, name)
+        return self._state_cache[name]
+
+def _get_group_name(ctx: click.Context) -> str:
+    """获取二级命令名"""
+    node = ctx
+    while node.parent and node.parent.parent is not None:
+        node = node.parent
+    return node.command.name or "unknown"
+
+def build_command_context(ctx: click.Context) -> CommandContext:
+    """根据当前 Click 上下文构建命令上下文"""
+    state = cast(CliState, ctx.obj)
+    command_name = _get_group_name(ctx)
+    return CommandContext(
+        name=command_name,
+        app=state.context,
+        logger=state.context.get_command_logger(command_name),
+    )
+
+
+def pass_command_context(func: F) -> F:
+    """向子命令注入便捷上下文。"""
+
+    @click.pass_context
+    def new_func(ctx: click.Context, *args: Any, **kwargs: Any) -> Any:
+        return ctx.invoke(func, build_command_context(ctx), *args, **kwargs)
+
+    return cast(F, update_wrapper(new_func, func))
+
+
+def get_app_context() -> AppContext:
+    """获取当前应用上下文。"""
+    from bykcli.runtime import build_runtime
+    return build_runtime()

bykcli/api/network.py

@@ -0,0 +1,91 @@
+"""网络工具函数。"""
+import socket
+from typing import List, Dict
+
+
+# 网络接口分类规则：(关键词列表，类型名称，是否虚拟接口，优先级)
+IFACE_RULES = [
+    (['vmware', 'vmnet'],         'vmware',     True,  30),
+    (['vbox', 'virtualbox'],      'virtualbox', True,  30),
+    (['docker', 'wsl'],           'container',  True,  40),
+    (['bluetooth'],               'bluetooth',  True,  60),
+    (['ethernet', '以太网'],       'ethernet',   False, 10),
+    (['wlan', 'wi-fi', '无线'],   'wifi',       False, 10),
+    (['loopback'],                'loopback',   True,  100),
+]
+
+
+def detect_iface_type(iface: str) -> tuple[str, bool, int]:
+    """检测网络接口类型。"""
+    lname = iface.lower()
+    for keywords, t, virtual, prio in IFACE_RULES:
+        if any(k in lname for k in keywords):
+            return t, virtual, prio
+    return 'unknown', False, 50
+
+
+def get_private_networks() -> List[Dict]:
+    """获取所有局域网 IP 地址信息。"""
+    try:
+        import psutil
+    except ImportError:
+        return [{
+            "iface": "localhost",
+            "ips": ["127.0.0.1"],
+            "type": "loopback",
+            "virtual": True,
+            "priority": 100
+        }]
+
+    results = []
+    interfaces = psutil.net_if_addrs()
+
+    for iface, addrs in interfaces.items():
+        ips = []
+        iface_type, is_virtual, priority = detect_iface_type(iface)
+
+        for addr in addrs:
+            if addr.family != socket.AF_INET:
+                continue
+
+            ip = addr.address
+
+            # 跳过回环地址和链路本地地址
+            if ip.startswith('127.'):
+                continue
+            if ip.startswith('169.254.'):
+                continue
+            # 只保留私有 IP 地址
+            if ip.startswith(('10.', '192.168.', '172.')):
+                ips.append(ip)
+
+        if ips:
+            results.append({
+                "iface": iface,
+                "ips": ips,
+                "type": iface_type,
+                "virtual": is_virtual,
+                "priority": priority
+            })
+
+    # 按优先级排序（数字越小优先级越高）
+    results.sort(key=lambda x: x['priority'])
+    
+    # 如果没有找到任何局域网 IP，返回 localhost
+    if not results:
+        results.append({
+            "iface": "localhost",
+            "ips": ["127.0.0.1"],
+            "type": "loopback",
+            "virtual": True,
+            "priority": 100
+        })
+    
+    return results
+
+
+def ensure_port_available(port: int, host: str = "0.0.0.0") -> None:
+    """检查端口是否可用。"""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        s.bind((host, int(port)))

bykcli/api/paths.py

@@ -0,0 +1,30 @@
+"""路径展示注册与渲染。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from bykcli.core.context import AppContext
+
+PathItem = tuple[str, str]
+PathProvider = Callable[[AppContext], list[PathItem]]
+
+_PATH_PROVIDERS: dict[str, PathProvider] = {}
+
+
+def register_path_provider(command_name: str, provider: PathProvider) -> None:
+    """注册子命令路径提供器。"""
+    _PATH_PROVIDERS[command_name] = provider
+
+
+def get_path_provider(command_name: str) -> PathProvider | None:
+    """获取某个子命令的路径提供器。"""
+    return _PATH_PROVIDERS.get(command_name)
+
+
+def global_path_items(context: AppContext) -> list[PathItem]:
+    """返回默认展示的全局路径。"""
+    return [
+        ("CLI Home", str(context.paths.root_dir)),
+        ("Logs Directory", str(context.paths.logs_dir)),
+    ]

bykcli/app.py

@@ -0,0 +1,151 @@
+"""CLI 应用装配。"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+import click
+
+from bykcli.core.context import AppContext
+from bykcli.core.errors import CliError
+
+logger = logging.getLogger("bykcli")
+
+
+class PluginAwareGroup(click.Group):
+    """支持插件动态加载的命令组。"""
+
+    runtime_provider: Any = None
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        return super().parse_args(ctx, args)
+
+    def resolve_command(
+        self,
+        ctx: click.Context,
+        args: list[str],
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        orig_args = list(args)
+        try:
+            return super().resolve_command(ctx, args)
+        except click.UsageError:
+            pass
+
+        if not orig_args:
+            return super().resolve_command(ctx, orig_args)
+
+        context = self._get_context(ctx)
+
+        # 检查缓存中的插件命令，按需加载单个插件
+        from bykcli.infra.cache import load_cache
+        from bykcli.infra.registry import load_single_plugin
+
+        cache_data = load_cache(context.paths.cache_dir / "app.json")
+        if orig_args[0] in cache_data.get("commands", {}):
+            cmd_name = orig_args[0]
+            module_path = cache_data["commands"][cmd_name]["module"]
+            load_single_plugin(self, cmd_name, module_path)
+            return super().resolve_command(ctx, orig_args)
+
+        # 未知命令
+        raise click.UsageError(f"Unknown command: {orig_args[0]}")
+
+    def _get_context(self, ctx: click.Context) -> AppContext:
+        """在命令解析阶段获取运行时上下文。"""
+        if ctx.obj is not None:
+            return ctx.obj.context
+        if callable(self.runtime_provider):
+            return self.runtime_provider()  # type: ignore[return-type]
+        raise click.ClickException("Runtime context not yet initialized")
+
+    def invoke(self, ctx: click.Context) -> Any:
+        """统一兜底未处理异常"""
+        try:
+            return super().invoke(ctx)
+        except click.ClickException:
+            raise
+        except click.exceptions.Exit:
+            raise
+        except CliError as exc:
+            logger.warning("cli error: %s", exc)
+            raise click.ClickException(str(exc)) from exc
+        except SystemExit:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("unexpected cli error")
+            log_file = "log file"
+            try:
+                if ctx.obj and hasattr(ctx.obj, 'context'):
+                    log_file = getattr(ctx.obj.context.paths, 'app_log_file', 'log file')
+            except Exception:
+                pass
+
+            raise click.ClickException(
+                f"Unexpected error occurred, see logs at: {log_file}"
+            ) from exc
+
+
+@dataclass(slots=True)
+class CliState:
+    """Click 根命令共享状态。"""
+
+    context: AppContext
+
+
+def version_callback(
+    ctx: click.Context,
+    _param: click.Parameter,
+    value: bool,
+) -> None:
+    """Show version and exit."""
+    if not value or ctx.resilient_parsing:
+        return
+
+    from bykcli.runtime import build_runtime
+
+    app_context: AppContext = ctx.obj.context if ctx.obj else build_runtime()
+    click.echo(f"v{app_context.version}")
+    ctx.exit()
+
+
+def create_cli() -> click.Group:
+    """创建根 CLI 对象。"""
+
+    from bykcli.runtime import build_runtime
+
+    runtime: AppContext | None = None
+
+    def get_runtime() -> AppContext:
+        nonlocal runtime
+        if runtime is None:
+            runtime = build_runtime()
+        return runtime
+
+    @click.group(
+        cls=PluginAwareGroup,
+        context_settings={"help_option_names": ["-h", "--help"]},
+        add_help_option=False,
+        invoke_without_command=True,
+    )
+    @click.option(
+        "--version",
+        "-v",
+        is_flag=True,
+        callback=version_callback,
+        expose_value=False,
+        is_eager=True,
+        help="Show version and exit.",
+    )
+    @click.pass_context
+    def cli(ctx: click.Context) -> None:
+        ctx.obj = CliState(context=get_runtime())
+        ctx.obj.context.logger.info("BYK CLI v%s started", ctx.obj.context.version)
+        if ctx.invoked_subcommand is None:
+            from bykcli.infra.view import render_dashboard
+
+            render_dashboard(ctx.obj.context, cli)
+
+    cli.runtime_provider = get_runtime
+    return cli

bykcli/core/__init__.py

@@ -0,0 +1,14 @@
+"""核心能力模块。"""
+
+from bykcli.core.context import AppContext, CommandContextLike
+from bykcli.core.environment import EnvironmentInfo
+from bykcli.core.persistence import PathLayout
+from bykcli.core.state import StateStore
+
+__all__ = [
+    "AppContext",
+    "CommandContextLike",
+    "EnvironmentInfo",
+    "PathLayout",
+    "StateStore",
+]

bykcli/core/context.py

@@ -0,0 +1,50 @@
+"""CLI 运行时上下文。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import logging
+from typing import TYPE_CHECKING, Protocol
+
+from bykcli.core.environment import EnvironmentInfo
+from bykcli.core.persistence import PathLayout
+
+if TYPE_CHECKING:
+    from bykcli.core.state import StateStore
+
+
+class CommandContextLike(Protocol):
+    """命令上下文协议。"""
+
+    name: str
+    app: "AppContext"
+    logger: logging.Logger
+
+    def state(self, name: str = "state") -> "StateStore": ...
+
+
+@dataclass(slots=True)
+class AppContext:
+    """子命令共享的核心上下文。"""
+
+    app_name: str
+    version: str
+    paths: PathLayout
+    environment: EnvironmentInfo
+    logger: logging.Logger
+
+    def command_store(
+        self,
+        command_name: str,
+        name: str = "state",
+    ) -> StateStore:
+        """返回某个子命令的状态存储。"""
+        raise NotImplementedError
+
+    def store(self, name: str = "byk.config") -> StateStore:
+        """返回应用级共享状态存储。"""
+        raise NotImplementedError
+
+    def get_command_logger(self, command_name: str) -> logging.Logger:
+        """获取命令专属 logger。"""
+        raise NotImplementedError

bykcli/core/environment.py

@@ -0,0 +1,29 @@
+"""运行环境信息。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import platform
+import sys
+
+
+@dataclass(slots=True)
+class EnvironmentInfo:
+    """CLI 运行环境信息。"""
+
+    app_name: str
+    version: str
+    python_version: str
+    executable: str
+    platform_name: str
+
+
+def collect_environment(app_name: str, version: str) -> EnvironmentInfo:
+    """收集当前运行环境。"""
+    return EnvironmentInfo(
+        app_name=app_name,
+        version=version,
+        python_version=platform.python_version(),
+        executable=sys.executable,
+        platform_name=platform.platform(),
+    )

bykcli/core/errors.py

@@ -0,0 +1,7 @@
+"""统一异常定义。"""
+
+from __future__ import annotations
+
+
+class CliError(RuntimeError):
+    """面向终端用户的业务异常。"""

bykcli/core/persistence.py

@@ -0,0 +1,53 @@
+"""持久化路径布局。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class PathLayout:
+    """持久化目录布局数据结构。"""
+
+    root_dir: Path
+    state_dir: Path
+    logs_dir: Path
+    runtime_dir: Path
+    app_log_file: Path
+    cache_dir: Path
+
+    @staticmethod
+    def _validate_safe_name(value: str, field_name: str) -> str:
+        """校验名称安全性，防止路径穿越和脏数据文件名。"""
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError(f"{field_name} 不能为空")
+        if normalized in {".", ".."}:
+            raise ValueError(f"{field_name} 不能为 '.' 或 '..'")
+        if "/" in normalized or "\\" in normalized:
+            raise ValueError(f"{field_name} 不能包含路径分隔符")
+        return normalized
+
+    def command_state_dir(self, command_name: str) -> Path:
+        """返回子命令专属目录。"""
+        safe_command_name = self._validate_safe_name(command_name, "command_name")
+        path = self.state_dir / safe_command_name
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def command_state_file(self, command_name: str, *parts: str) -> Path:
+        """返回子命令专属文件路径。"""
+        target = self.command_state_dir(command_name)
+        for part in parts:
+            safe_part = self._validate_safe_name(part, "part")
+            target = target / safe_part
+        target.parent.mkdir(parents=True, exist_ok=True)
+        return target
+
+    def state_file(self, name: str) -> Path:
+        """返回应用级状态文件路径。"""
+        safe_name = self._validate_safe_name(name, "name")
+        path = self.state_dir / f"{safe_name}.json"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        return path

bykcli/core/plugin.py

@@ -0,0 +1,21 @@
+"""插件注册协议。"""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    import click
+
+
+@runtime_checkable
+class PluginProtocol(Protocol):
+    """bykcli 插件协议。
+
+    就两个成员：
+        commands:  {子命令名: 描述}，用于仪表盘展示
+        register:  实例方法，接收 cli，在此添加子命令
+    """
+
+    commands: dict[str, str]
+
+    def register(self, cli: "click.Group") -> None: ...

bykcli/core/state.py

@@ -0,0 +1,20 @@
+"""子命令状态存储协议。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol
+
+
+class StateStore(Protocol):
+    """状态存储协议。"""
+
+    path: Path
+
+    def load(self) -> dict[str, Any]: ...
+    def save(self, data: dict[str, Any]) -> dict[str, Any]: ...
+    def get(self, key: str, default: Any = None) -> Any: ...
+    def set(self, key: str, value: Any) -> dict[str, Any]: ...
+    def update(self, values: dict[str, Any]) -> dict[str, Any]: ...
+    def delete(self, key: str) -> dict[str, Any]: ...
+    def clear(self) -> dict[str, Any]: ...

bykcli/infra/cache.py

@@ -0,0 +1,109 @@
+"""插件缓存：entry_points 元数据扫描与磁盘缓存。
+
+启动时只需一次 IO 读 app.json，plugins 数量不影响启动性能。
+pip install/uninstall 后 site-packages mtime 变化自动触发缓存重建。
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+import site
+import time
+from importlib.metadata import entry_points
+from pathlib import Path
+
+from bykcli.infra.persistence import read_json, write_json
+
+logger = logging.getLogger("bykcli")
+
+
+def get_watched_mtimes() -> dict[str, float]:
+    """收集 site-packages 目录的 mtime，用于缓存失效检测。"""
+    mtimes: dict[str, float] = {}
+    try:
+        paths = site.getsitepackages()
+    except Exception:
+        return mtimes
+    for p in paths:
+        if os.path.exists(p):
+            try:
+                mtimes[p] = os.path.getmtime(p)
+            except OSError:
+                pass
+    return mtimes
+
+
+def is_cache_stale(cached_mtimes: dict[str, float]) -> bool:
+    """对比当前 mtime 与缓存，判断缓存是否失效。"""
+    current = get_watched_mtimes()
+    return current != cached_mtimes
+
+
+def scan_plugins() -> dict[str, dict[str, str]]:
+    """扫描 entry_points，import 插件类展开 commands。
+
+    对每个 entry_point，import 其 Plugin 类，读取 commands dict，
+    展开为扁平 {命令名: {module, description}} 结构。
+    """
+    commands: dict[str, dict[str, str]] = {}
+
+    try:
+        plugin_entries = entry_points(group="bykcli.plugins")
+    except TypeError:
+        plugin_entries = entry_points().get("bykcli.plugins", [])  # type: ignore[attr-defined]
+
+    for ep in plugin_entries:
+        try:
+            module_name, class_name = ep.value.rsplit(":", 1)
+            module = importlib.import_module(module_name)
+            plugin_cls = getattr(module, class_name)
+            for cmd, desc in plugin_cls.commands.items():
+                if cmd in commands:
+                    logger.warning(
+                        "command '%s' from %s overrides existing from %s",
+                        cmd, ep.value, commands[cmd]["module"],
+                    )
+                commands[cmd] = {
+                    "module": ep.value,
+                    "description": desc,
+                }
+        except Exception:
+            logger.exception("failed to scan plugin %s", ep.name)
+
+    return commands
+
+
+def _build_cache() -> dict:
+    """构建缓存数据结构。"""
+    return {
+        "watched_mtimes": get_watched_mtimes(),
+        "scanned_at": time.time(),
+        "commands": scan_plugins(),
+    }
+
+
+def load_cache(cache_file: Path) -> dict:
+    """读取缓存文件，失效时自动重建。
+
+    Args:
+        cache_file: ~/.bykcli/cache/app.json 路径
+
+    Returns:
+        缓存数据 dict，保证 commands 键存在
+    """
+    data = read_json(cache_file, default=None)
+
+    if data is None:
+        data = _build_cache()
+        write_json(cache_file, data)
+        return data
+
+    cached_mtimes = data.get("watched_mtimes", {})
+    if is_cache_stale(cached_mtimes):
+        data = _build_cache()
+        write_json(cache_file, data)
+        return data
+
+    return data

bykcli/infra/logging.py

@@ -0,0 +1,70 @@
+"""统一日志初始化。"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from bykcli.core.context import AppContext
+
+
+def _get_log_config(context: AppContext) -> dict:
+    """从配置文件读取日志配置。"""
+    try:
+        logging_config = context.store("byk.config").get("logging", {})
+        if isinstance(logging_config, dict):
+            return logging_config
+    except Exception:
+        pass
+    return {}
+
+
+def setup_logging(app_log_file: Path) -> logging.Logger:
+    """初始化应用日志。"""
+    logger = logging.getLogger("bykcli")
+    if logger.handlers:
+        return logger
+
+    logger.setLevel(logging.INFO)
+    handler = logging.FileHandler(app_log_file, encoding="utf-8")
+    handler.setFormatter(
+        logging.Formatter(
+            fmt="%(asctime)s %(levelname)s [%(name)s] %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+    )
+    logger.addHandler(handler)
+    logger.propagate = False
+    logger.debug("logger initialized")
+    return logger
+
+
+def create_command_logger(context: AppContext, command_name: str) -> logging.Logger:
+    """创建命令专属 logger"""
+    logger = logging.getLogger(f"bykcli.{command_name}")
+
+    if not logger.handlers:
+        log_config = _get_log_config(context)
+        level_str = log_config.get("level", "INFO").upper()
+        separate = log_config.get("separate", True)
+
+        try:
+            level = getattr(logging, level_str)
+        except AttributeError:
+            level = logging.INFO
+
+        logger.setLevel(level)
+
+        log_file = context.paths.logs_dir / f"{command_name}.log"
+        handler = logging.FileHandler(log_file, encoding="utf-8")
+        handler.setFormatter(
+            logging.Formatter(
+                fmt="%(asctime)s %(levelname)s [%(name)s] %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            )
+        )
+        logger.addHandler(handler)
+
+        logger.propagate = not separate
+
+    return logger

bykcli/infra/persistence.py

@@ -0,0 +1,93 @@
+"""统一持久化路径与基础文件操作。"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import tempfile
+from typing import Any, TypeVar
+
+from bykcli.core.errors import CliError
+from bykcli.core.persistence import PathLayout
+
+T = TypeVar("T")
+
+def build_path_layout(app_name: str) -> PathLayout:
+    """构建目录布局并确保目录存在。"""
+    root_dir = Path.home() / f".{app_name}"
+    state_dir = root_dir / "state"
+    logs_dir = root_dir / "logs"
+    runtime_dir = root_dir / "runtime"
+    cache_dir = root_dir / "cache"
+
+    for directory in (root_dir, state_dir, logs_dir, runtime_dir, cache_dir):
+        directory.mkdir(parents=True, exist_ok=True)
+
+    return PathLayout(
+        root_dir=root_dir,
+        state_dir=state_dir,
+        logs_dir=logs_dir,
+        runtime_dir=runtime_dir,
+        app_log_file=logs_dir / "app.log",
+        cache_dir=cache_dir,
+    )
+
+
+def read_json(path: Path, default: T) -> T:
+    """读取 JSON 文件。"""
+    if not path.exists():
+        return default
+
+    try:
+        with path.open("r", encoding="utf-8") as file:
+            data = json.load(file)
+    except json.JSONDecodeError as exc:
+        raise CliError(f"Failed to parse JSON file: {path}") from exc
+    except OSError as exc:
+        raise CliError(f"Unable to read file: {path}") from exc
+
+    return data if data is not None else default
+
+
+def write_json(path: Path, data: Any) -> None:
+    """以原子方式写入 JSON 文件。"""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w",
+            delete=False,
+            dir=path.parent,
+            encoding="utf-8",
+        ) as temp_file:
+            json.dump(data, temp_file, indent=2, ensure_ascii=False)
+            temp_path = Path(temp_file.name)
+        temp_path.replace(path)
+    except OSError as exc:
+        raise CliError(f"Unable to write file: {path}") from exc
+
+
+def read_text(path: Path, default: str | None = None) -> str | None:
+    """读取文本文件。"""
+    if not path.exists():
+        return default
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise CliError(f"Unable to read file: {path}") from exc
+
+
+def write_text(path: Path, content: str) -> None:
+    """以原子方式写入文本文件。"""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w",
+            delete=False,
+            dir=path.parent,
+            encoding="utf-8",
+        ) as temp_file:
+            temp_file.write(content)
+            temp_path = Path(temp_file.name)
+        temp_path.replace(path)
+    except OSError as exc:
+        raise CliError(f"Unable to write file: {path}") from exc

bykcli/infra/registry.py

@@ -0,0 +1,26 @@
+"""插件发现与注册。"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+
+import click
+
+logger = logging.getLogger("bykcli")
+
+
+def load_single_plugin(cli: click.Group, cmd_name: str, module_path: str) -> None:
+    """按需加载单个插件：import → 实例化 → plugin.register(cli)。
+
+    Args:
+        cli: Click Group 对象
+        cmd_name: 命令名（用于日志）
+        module_path: "hello.byk:Plugin" 格式的导入路径（包.模块:类名）
+    """
+    module_name, class_name = module_path.rsplit(":", 1)
+    module = importlib.import_module(module_name)
+    plugin_cls = getattr(module, class_name)
+    plugin = plugin_cls()
+    plugin.register(cli)
+    logger.debug("plugin loaded on demand: %s from %s", cmd_name, module_path)

bykcli/infra/state.py

@@ -0,0 +1,53 @@
+"""状态存储的 JSON 文件实现。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from bykcli.core.state import StateStore
+from bykcli.infra.persistence import read_json, write_json
+
+
+@dataclass(slots=True)
+class JsonStateStore:
+    """基于 JSON 文件的状态存储实现。"""
+
+    path: Path
+
+    def load(self) -> dict[str, Any]:
+        """读取完整状态。"""
+        data = read_json(self.path, default={})
+        return data if isinstance(data, dict) else {}
+
+    def save(self, data: dict[str, Any]) -> dict[str, Any]:
+        """覆盖保存完整状态。"""
+        write_json(self.path, data)
+        return data
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """读取单个状态值。"""
+        return self.load().get(key, default)
+
+    def set(self, key: str, value: Any) -> dict[str, Any]:
+        """保存单个状态值。"""
+        data = self.load()
+        data[key] = value
+        return self.save(data)
+
+    def update(self, values: dict[str, Any]) -> dict[str, Any]:
+        """批量更新状态。"""
+        data = self.load()
+        data.update(values)
+        return self.save(data)
+
+    def delete(self, key: str) -> dict[str, Any]:
+        """删除单个状态值。"""
+        data = self.load()
+        data.pop(key, None)
+        return self.save(data)
+
+    def clear(self) -> dict[str, Any]:
+        """清空当前状态文件。"""
+        return self.save({})

bykcli/infra/view.py

@@ -0,0 +1,25 @@
+"""根命令仪表盘"""
+
+from __future__ import annotations
+
+import click
+
+from bykcli.core.context import AppContext
+from bykcli.infra.cache import load_cache
+
+
+def render_dashboard(context: AppContext, cli: click.Group) -> None:
+    click.echo(cli.get_help(click.Context(cli)))
+
+    # Commands：从缓存读取（零 import）
+    cache_data = load_cache(context.paths.cache_dir / "app.json")
+    commands = cache_data.get("commands", {})
+    if commands:
+        cmd_entries = sorted(
+            (name, info.get("description", "") if isinstance(info, dict) else str(info))
+            for name, info in commands.items()
+        )
+        click.echo()
+        click.echo("Commands:")
+        for name, desc in cmd_entries:
+            click.echo(f"  ({name}, {desc})")

bykcli/runtime.py

@@ -0,0 +1,58 @@
+"""运行时装配。"""
+
+from __future__ import annotations
+
+import logging
+
+from bykcli import __version__
+from bykcli.core.context import AppContext
+from bykcli.core.environment import collect_environment
+from bykcli.infra.logging import create_command_logger, setup_logging
+from bykcli.infra.persistence import build_path_layout
+from bykcli.infra.state import JsonStateStore
+
+
+class _RuntimeAppContext(AppContext):
+    """运行时上下文，带缓存。"""
+
+    _store_cache: dict[str, JsonStateStore]
+    _command_store_cache: dict[tuple[str, str], JsonStateStore]
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._store_cache = {}
+        self._command_store_cache = {}
+
+    def command_store(self, command_name: str, name: str = "state"):
+        key = (command_name, name)
+        if key not in self._command_store_cache:
+            self._command_store_cache[key] = JsonStateStore(
+                path=self.paths.command_state_file(command_name, f"{name}.json"),
+            )
+        return self._command_store_cache[key]
+
+    def store(self, name: str = "byk.config"):
+        if name not in self._store_cache:
+            self._store_cache[name] = JsonStateStore(
+                path=self.paths.state_file(name),
+            )
+        return self._store_cache[name]
+
+    def get_command_logger(self, command_name: str) -> logging.Logger:
+        return create_command_logger(self, command_name)
+
+
+def build_runtime() -> AppContext:
+    """构建应用运行时。"""
+    app_name = "bykcli"
+    paths = build_path_layout(app_name=app_name)
+    environment = collect_environment(app_name=app_name, version=__version__)
+    global_logger = setup_logging(paths.app_log_file)
+
+    return _RuntimeAppContext(
+        app_name=app_name,
+        version=__version__,
+        paths=paths,
+        environment=environment,
+        logger=global_logger,
+    )

bykcli_plugin-1.0.0a5.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: bykcli-plugin
+Version: 1.0.0a5
+Summary: Plugin infrastructure for bykcli
+Author-email: fcbyk <731240932@qq.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: bykcli<2.0,>=1.0.0a5
+Provides-Extra: test
+Requires-Dist: pytest<8.0.0,>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov<5.0.0,>=4.0.0; extra == "test"
+Provides-Extra: build
+Requires-Dist: commitizen; extra == "build"
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+Dynamic: license-file
+
+# bykcli-plugin
+
+[![Python](https://img.shields.io/badge/python-%E2%89%A53.10-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![Tests](https://github.com/fcbyk/bykcli/actions/workflows/test.yml/badge.svg)](https://github.com/fcbyk/bykcli/actions/workflows/test.yml)
+[![Coverage](https://codecov.io/gh/fcbyk/bykcli/branch/main/graph/badge.svg)](https://codecov.io/gh/fcbyk/bykcli)
+[![License](https://img.shields.io/github/license/fcbyk/bykcli.svg)](https://github.com/fcbyk/bykcli/blob/main/LICENSE)
+
+Plugin infrastructure for [bykcli](https://github.com/fcbyk/bykcli).
+
+## Install
+
+```bash
+pip install bykcli-plugin
+```
+
+## Usage
+
+Implement `PluginProtocol` and register your commands:
+
+```python
+# my_plugin.py
+import click
+from bykcli import PluginProtocol
+
+class MyPlugin(PluginProtocol):
+    commands = {"hello": "say hello"}
+
+    def register(self, cli: click.Group) -> None:
+        @cli.command()
+        @click.pass_context
+        def hello(ctx):
+            click.echo("Hello from my plugin!")
+```
+
+## API
+
+- **PluginProtocol** — class-based plugin registration protocol
+- **CommandContext / pass_command_context / get_app_context** — command runtime context
+- **PathItem / PathProvider / register_path_provider** — path management
+- **get_private_networks / ensure_port_available** — network utilities
+- **StateStore** — persistent key-value storage per command
+
+## License
+
+MIT

bykcli_plugin-1.0.0a5.dist-info/RECORD

@@ -0,0 +1,27 @@
+bykcli/__init__.py,sha256=xsFL09a1Q8qq4UpJ40zY-KYREG6GQxrarni5fCWIdjw,73
+bykcli/__main__.py,sha256=yuL4pTPoJHbzCRkJUA6ioHiDTNuCXvlcSfvgTUmt4JA,652
+bykcli/app.py,sha256=dDQF6KgPqk5ue0ohb4nTph7zBAacqjF2377gzLBX__M,4476
+bykcli/runtime.py,sha256=jTAUwnqIpQhbvBZeq31i_7eA21xVPVtDxzfRkiBR2w4,1900
+bykcli/api/__init__.py,sha256=9FWuchdejILLQfAiI4X7-ghRCX7QHQq0jSzVi1lYyV0,764
+bykcli/api/context.py,sha256=3oumWF7L4CSzxbRLBFNhEftaI2qNiENVliZuaoT3UPQ,1998
+bykcli/api/network.py,sha256=1HPVhv5Q57bG8dqJiPsqMJrsHFwRPFGWERRixW5jI3g,2787
+bykcli/api/paths.py,sha256=Ia_QpBuNhAvG1TQ5Vb0XL-crNuWxbVRfSRkkids8U5k,857
+bykcli/core/__init__.py,sha256=1Tv1cy39NBGtxvr_pmoGR8nGzTdCxxph47VPMH4JlYg,350
+bykcli/core/context.py,sha256=lSKvzsVznuUZpRJkjqDzCMtTHu1WzxsvC9xhoLTJrZ0,1232
+bykcli/core/environment.py,sha256=6RGzkSEcVHGgo7sMNbljIuJlM615_Gdv8tJr3GLttNI,640
+bykcli/core/errors.py,sha256=3VSTixvdw6rJS0tjMKZQfexkHuv85VxKbaNrrICW4gM,143
+bykcli/core/persistence.py,sha256=YM-AHViBSR5UEdaEscEOQKqDlmltbOFfu02gytYJgz8,1865
+bykcli/core/plugin.py,sha256=ElT1ATpMcIeT-mkGXfOUaOBiYDO1AV1k4d5i-LzlPXk,499
+bykcli/core/state.py,sha256=2lBufRsoLVfHLNgr39ja5FWFalQKuDKNXNE1BI1fsTg,606
+bykcli/infra/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bykcli/infra/cache.py,sha256=87l70F68DmPm51atI5xF6-mKZGbyK7VXH2y1aYRPc4o,3181
+bykcli/infra/logging.py,sha256=djm7HtgUQJGUmYpRVs_z8PQBYc3qyvJ97GSqo8iTDS4,1992
+bykcli/infra/persistence.py,sha256=AtG5oUEgn2eWSeUFNzTWP-B9ZXjRGZApaaRvlcx4RfA,2795
+bykcli/infra/registry.py,sha256=qrCbOqU1Vgj6qrm5yNJ58pM4x6aSaB-hz68lyacr5yE,784
+bykcli/infra/state.py,sha256=MGmpiSXwF_XJsA64xBErytK7jMmrCPrcK78hExD_nls,1514
+bykcli/infra/view.py,sha256=pll_OAGbnLSTHGvJ_ssKjQ52ij7SqYxQ4Lx6QQQHw4Y,774
+bykcli_plugin-1.0.0a5.dist-info/licenses/LICENSE,sha256=b14kwwwpTtEFAEc-R2iWZCxemR8mELElygr36bmD9f4,1061
+bykcli_plugin-1.0.0a5.dist-info/METADATA,sha256=BFWuu6xWLYZsJRbEvNdqHsFPjqiFwBkYSp7Ef6GiiU8,2416
+bykcli_plugin-1.0.0a5.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+bykcli_plugin-1.0.0a5.dist-info/top_level.txt,sha256=lgRiXX_EMVcor6xgxcASGY7iOsjF0w67dOWdkPxbGtI,7
+bykcli_plugin-1.0.0a5.dist-info/RECORD,,

bykcli_plugin-1.0.0a5.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bykcli_plugin-1.0.0a5.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yoki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bykcli_plugin-1.0.0a5.dist-info/top_level.txt

@@ -0,0 +1 @@
+bykcli