aukeys-opscli 0.0.6__py3-none-any.whl

opscli/skills/commands/cli.py

@@ -0,0 +1,389 @@
+"""Skills CLI 子命令定义。
+
+注册到 opscli 顶级命令下，提供 skills list/install/status/upgrade 四个子命令。
+所有命令输出统一 JSON 格式，方便脚本解析。
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from opscli.skills.domain.exceptions import error_to_dict
+from opscli.skills.services.manager import SkillsManager
+
+app = typer.Typer(help="Skill 生命周期管理")
+_console = Console()
+
+_TOOL_LABELS = {
+    "claude":   "Claude Code",
+    "openclaw": "OpenClaw",
+    "codex":    "Codex CLI",
+    "opencode": "OpenCode",
+}
+
+
+def _emit(payload: dict, pretty: bool) -> None:
+    """统一的 JSON 输出函数，控制是否美化格式。"""
+    if pretty:
+        typer.echo(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        typer.echo(json.dumps(payload, ensure_ascii=False))
+
+
+def _parse_multiselect(answer: str, total: int) -> list[int]:
+    """将逗号分隔的编号字符串解析为 1-based 索引列表（空字符串返回全选）。"""
+    if not answer.strip():
+        return list(range(1, total + 1))
+    indexes: list[int] = []
+    for part in answer.split(","):
+        normalized = part.strip()
+        if not normalized:
+            continue
+        if not normalized.isdigit():
+            raise ValueError(f"无效的编号: {normalized!r}")
+        idx = int(normalized)
+        if idx < 1 or idx > total:
+            raise ValueError(f"编号 {idx} 超出范围（1~{total}）")
+        indexes.append(idx)
+    return indexes or list(range(1, total + 1))
+
+
+def _tui_select_skills(manager: SkillsManager) -> list[str]:
+    """TUI：展示内置 Skill 列表，用户选择要安装哪些。返回选中的 skill 名称列表。"""
+    templates = manager.list_templates()
+    if not templates:
+        raise ValueError("未找到任何内置 Skill 模板")
+
+    table = Table(show_header=True, header_style="bold cyan", box=None, padding=(0, 1))
+    table.add_column("#", style="bold yellow", width=3)
+    table.add_column("名称", style="green", min_width=20)
+    table.add_column("版本", style="dim", width=8)
+    table.add_column("说明")
+    for idx, tmpl in enumerate(templates, start=1):
+        table.add_row(f"[{idx}]", tmpl["name"], tmpl["version"], tmpl["description"])
+
+    _console.print(Panel(table, title="[bold]可安装的 Skills[/bold]", border_style="blue"))
+
+    answer = typer.prompt(
+        "请选择要安装的 Skills（逗号分隔编号，直接回车安装全部）",
+        default="",
+        show_default=False,
+    )
+    selected_indexes = _parse_multiselect(answer, len(templates))
+    return [templates[i - 1]["name"] for i in selected_indexes]
+
+
+def _tui_select_targets(manager: SkillsManager) -> list[tuple[str, Path]] | None:
+    """TUI：展示全局检测到的工具列表，用户选择安装到哪些工具。
+
+    使用 detect_global_install_targets() 按 ~/.claude/、which claude 等规则检测，
+    而非项目级 CWD 目录。
+
+    返回选中的 [(runtime, skills_dir), ...] 列表；未检测到任何工具时返回 None。
+    """
+    targets = manager.detector.detect_global_install_targets()
+    if not targets:
+        return None
+
+    table = Table(show_header=True, header_style="bold cyan", box=None, padding=(0, 1))
+    table.add_column("#", style="bold yellow", width=3)
+    table.add_column("工具", style="green", min_width=14)
+    table.add_column("安装路径", style="dim")
+    for idx, (runtime, path) in enumerate(targets, start=1):
+        label = _TOOL_LABELS.get(runtime, runtime)
+        table.add_row(f"[{idx}]", label, str(path))
+
+    _console.print(Panel(table, title="[bold]检测到的安装目标[/bold]", border_style="blue"))
+
+    answer = typer.prompt(
+        "请选择安装目标（逗号分隔编号，直接回车安装全部）",
+        default="",
+        show_default=False,
+    )
+    selected_indexes = _parse_multiselect(answer, len(targets))
+    return [targets[i - 1] for i in selected_indexes]
+
+
+def _resolve_install_runtime(
+    manager: SkillsManager,
+    *,
+    runtime: str | None,
+    skills_dir: str | None,
+) -> str | list[str] | None:
+    """在单 Skill 安装场景下解析目标 runtime（复用原有逻辑）。"""
+    if runtime or skills_dir:
+        return runtime
+
+    detector = getattr(manager, "detector", None)
+    if detector is None:
+        return runtime
+    targets = detector.detect_available_install_targets(cwd=Path.cwd())
+    if not targets:
+        return runtime
+
+    table = Table(show_header=True, header_style="bold cyan", box=None, padding=(0, 1))
+    table.add_column("#", style="bold yellow", width=3)
+    table.add_column("工具", style="green", min_width=14)
+    table.add_column("安装路径", style="dim")
+    for idx, (target_runtime, target_path) in enumerate(targets, start=1):
+        label = _TOOL_LABELS.get(target_runtime, target_runtime)
+        table.add_row(f"[{idx}]", label, str(target_path))
+
+    _console.print(Panel(table, title="[bold]检测到的安装目标[/bold]", border_style="blue"))
+
+    answer = typer.prompt(
+        "请选择安装目标（逗号分隔编号，直接回车安装全部）",
+        default="",
+        show_default=False,
+    )
+    selected_indexes = _parse_multiselect(answer, len(targets))
+    return [targets[i - 1][0] for i in selected_indexes]
+
+
+@app.command("list")
+def list_skills(
+    skills_dir: str | None = typer.Option(None, "--skills-dir", help="指定扫描目录"),
+    pretty: bool = typer.Option(False, "--pretty", help="格式化输出"),
+):
+    """列出所有已安装的 Skill。"""
+    manager = SkillsManager()
+    status_data = manager.status(skills_dir=skills_dir)
+    _emit(
+        {
+            "success": True,
+            "command": "skills list",
+            "data": {"skills": status_data["skills"]},
+            "error": None,
+        },
+        pretty,
+    )
+
+
+@app.command("install")
+def install_skill(
+    name: str | None = typer.Argument(None, help="Skill 名称，不指定则进入交互模式安装全部"),
+    skills_dir: str | None = typer.Option(None, "--skills-dir", help="指定安装目录"),
+    runtime: str | None = typer.Option(None, "--runtime", help="claude、openclaw、all，或逗号分隔多个值"),
+    force: bool = typer.Option(False, "--force", help="覆盖已存在目录"),
+    pretty: bool = typer.Option(False, "--pretty", help="格式化输出"),
+):
+    """从内置模板安装 Skill 到本地目录。
+
+    不指定 NAME 时进入 TUI 交互模式，可多选 Skills 和安装目标。
+    """
+    manager = SkillsManager()
+    try:
+        if name is None:
+            # TUI 模式：交互选择 Skills 和安装目标
+            _install_interactive(manager, skills_dir=skills_dir, runtime=runtime, force=force, pretty=pretty)
+            return
+        # 单 Skill 安装（原有逻辑）
+        resolved_runtime = _resolve_install_runtime(
+            manager,
+            runtime=runtime,
+            skills_dir=skills_dir,
+        )
+        result = manager.install(
+            name,
+            skills_dir=skills_dir,
+            runtime=resolved_runtime,
+            force=force,
+        )
+        payload = {
+            "success": True,
+            "command": "skills install",
+            "data": result.to_dict(),
+            "error": None,
+        }
+    except Exception as exc:
+        payload = {
+            "success": False,
+            "command": "skills install",
+            "data": None,
+            "error": error_to_dict(exc),
+        }
+        _emit(payload, pretty)
+        raise typer.Exit(1)
+
+    _emit(payload, pretty)
+
+
+def _install_interactive(
+    manager: SkillsManager,
+    *,
+    skills_dir: str | None,
+    runtime: str | None,
+    force: bool,
+    pretty: bool,
+) -> None:
+    """TUI 交互安装：选择 Skills → 选择目标工具 → 批量安装。
+
+    交互模式默认 force=True（覆盖已有安装），无需手动传 --force。
+    """
+    force = True  # TUI 模式始终覆盖，避免因已安装而中断
+    # Step 1：选择要安装的 Skills
+    try:
+        skill_names = _tui_select_skills(manager)
+    except ValueError as exc:
+        _console.print(f"[red]错误：{exc}[/red]")
+        raise typer.Exit(1)
+
+    # Step 2：确定安装目标列表 —— [(runtime, Path), ...]
+    # 优先级：显式 skills_dir > 显式 runtime > TUI 全局检测
+    target_pairs: list[tuple[str, Path]] | None = None
+    if skills_dir:
+        # 用户显式指定目录：安装到唯一路径
+        target_pairs = [(runtime or "custom", Path(skills_dir).expanduser())]
+    elif runtime:
+        # 用户显式指定 runtime：通过 detector 解析为具体路径（保持原有行为）
+        runtime_list = [r.strip() for r in runtime.split(",") if r.strip()]
+        try:
+            target_pairs = manager.detector.detect_install_targets(preferred_runtimes=runtime_list)
+        except ValueError as exc:
+            _console.print(f"[red]错误：{exc}[/red]")
+            raise typer.Exit(1)
+    else:
+        # TUI 全局检测：使用 ~/.claude/、~/.openclaw/ 等全局路径
+        try:
+            target_pairs = _tui_select_targets(manager)
+        except ValueError as exc:
+            _console.print(f"[red]错误：{exc}[/red]")
+            raise typer.Exit(1)
+
+    # Step 3：批量安装（skill × target 二重循环）
+    _console.print()
+    all_results: list[dict] = []
+    errors: list[str] = []
+
+    for skill_name in skill_names:
+        if target_pairs:
+            # 有明确路径：逐目标安装，每次传入显式 skills_dir
+            for target_runtime, target_path in target_pairs:
+                try:
+                    result = manager.install(
+                        skill_name,
+                        skills_dir=str(target_path),
+                        runtime=target_runtime,
+                        force=force,
+                    )
+                    all_results.append(result.to_dict())
+                    for install in result.installs:
+                        _print_install_line(install)
+                except Exception as exc:
+                    key = f"{skill_name}@{target_path}"
+                    errors.append(f"{key}: {exc}")
+                    _console.print(f"  [red]✗[/red] [bold]{skill_name}[/bold] [red]{exc}[/red]")
+        else:
+            # 未检测到任何全局工具：交由 manager 使用默认逻辑
+            try:
+                result = manager.install(skill_name, force=force)
+                all_results.append(result.to_dict())
+                for install in result.installs:
+                    _print_install_line(install)
+            except Exception as exc:
+                errors.append(f"{skill_name}: {exc}")
+                _console.print(f"  [red]✗[/red] [bold]{skill_name}[/bold] [red]{exc}[/red]")
+
+    _console.print()
+    if errors:
+        _console.print(f"[yellow]完成：{len(all_results)} 个成功，{len(errors)} 个失败[/yellow]")
+        payload = {
+            "success": False,
+            "command": "skills install",
+            "data": {"results": all_results},
+            "error": {
+                "type": "BatchInstallError",
+                "message": "; ".join(errors),
+            },
+        }
+        _emit(payload, pretty)
+        raise typer.Exit(1)
+    else:
+        _console.print(f"[green]全部安装完成，共 {len(all_results)} 个 Skill[/green]")
+        payload = {
+            "success": True,
+            "command": "skills install",
+            "data": {"results": all_results},
+            "error": None,
+        }
+        _emit(payload, pretty)
+
+
+def _print_install_line(install: object) -> None:
+    """打印单条安装结果行。"""
+    replaced = getattr(install, "replaced", False)
+    status_icon = "↻" if replaced else "✓"
+    name = getattr(install, "name", "")
+    version = getattr(install, "version", "")
+    runtime = getattr(install, "runtime", "")
+    target_dir = getattr(install, "target_dir", "")
+    tool_label = _TOOL_LABELS.get(runtime, runtime)
+    _console.print(
+        f"  [green]{status_icon}[/green] [bold]{name}[/bold] "
+        f"[dim]{version}[/dim] → [cyan]{tool_label}[/cyan] "
+        f"[dim]({target_dir})[/dim]"
+    )
+
+
+@app.command("status")
+def status(
+    skills_dir: str | None = typer.Option(None, "--skills-dir", help="指定扫描目录"),
+    pretty: bool = typer.Option(False, "--pretty", help="格式化输出"),
+):
+    """查看 Skill 安装状态，包含远端版本对比。"""
+    manager = SkillsManager()
+    try:
+        data = manager.status(skills_dir=skills_dir)
+        payload = {
+            "success": True,
+            "command": "skills status",
+            "data": data,
+            "error": None,
+        }
+    except Exception as exc:
+        payload = {
+            "success": False,
+            "command": "skills status",
+            "data": None,
+            "error": error_to_dict(exc),
+        }
+        _emit(payload, pretty)
+        raise typer.Exit(1)
+
+    _emit(payload, pretty)
+
+
+@app.command("upgrade")
+def upgrade(
+    name: str = typer.Argument("ops-dataset-query", help="Skill 名称"),
+    skills_dir: str | None = typer.Option(None, "--skills-dir", help="指定扫描目录"),
+    force: bool = typer.Option(False, "--force", help="强制覆盖本地版本"),
+    pretty: bool = typer.Option(False, "--pretty", help="格式化输出"),
+):
+    """升级 Skill 到远端最新版本。"""
+    manager = SkillsManager()
+    try:
+        result = manager.upgrade(name=name, skills_dir=skills_dir, force=force)
+        payload = {
+            "success": True,
+            "command": "skills upgrade",
+            "data": result.to_dict(),
+            "error": None,
+        }
+    except Exception as exc:
+        payload = {
+            "success": False,
+            "command": "skills upgrade",
+            "data": None,
+            "error": error_to_dict(exc),
+        }
+        _emit(payload, pretty)
+        raise typer.Exit(1)
+
+    _emit(payload, pretty)

opscli/skills/detector.py

@@ -0,0 +1,5 @@
+"""skills detector 兼容导出。"""
+
+from opscli.skills.discovery.detector import SkillDetector
+
+__all__ = ["SkillDetector"]

opscli/skills/discovery/__init__.py

@@ -0,0 +1,5 @@
+"""skills 发现层。"""
+
+from opscli.skills.discovery.detector import SkillDetector
+
+__all__ = ["SkillDetector"]

opscli/skills/discovery/detector.py

@@ -0,0 +1,225 @@
+"""Skill 发现与检测模块。
+
+负责扫描多个候选目录，发现已安装的 Skill 并生成 SkillRecord。
+同时提供安装目标目录的检测逻辑，决定新 Skill 应安装到哪里。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from pathlib import Path
+
+from opscli.skills.domain.models import SkillRecord
+
+
+class SkillDetector:
+    """Skill 探测器，扫描磁盘目录发现已安装的 Skill。"""
+
+    def candidate_dirs(self, skills_dir: str | None = None, cwd: Path | None = None) -> list[Path]:
+        """收集所有候选扫描目录，按优先级排列并去重。
+
+        优先级从高到低：
+        1. 调用方显式指定的 skills_dir 参数
+        2. 环境变量 OPSCLI_SKILLS_DIR
+        3. 当前工作目录下的 .claude/skills
+        4. 用户主目录下的 .claude/skills
+        5. 用户主目录下的 .openclaw/skills
+        """
+        current = cwd or Path.cwd()
+        candidates: list[Path] = []
+
+        # 显式指定的目录优先级最高
+        if skills_dir:
+            candidates.append(Path(skills_dir).expanduser())
+
+        # 环境变量指定的目录次之
+        env_dir = os.getenv("OPSCLI_SKILLS_DIR")
+        if env_dir:
+            candidates.append(Path(env_dir).expanduser())
+
+        # 默认候选目录（按工具优先级排列）
+        home = Path.home()
+        candidates.extend(
+            [
+                current / ".claude" / "skills",
+                home / ".claude" / "skills",
+                home / ".openclaw" / "skills",
+                home / ".codex" / "skills",
+                self._opencode_skills_dir(),
+            ]
+        )
+
+        # 按路径去重，避免同一目录被重复扫描
+        seen: set[str] = set()
+        result: list[Path] = []
+        for item in candidates:
+            key = str(item.resolve()) if item.exists() else str(item.expanduser())
+            if key in seen:
+                continue
+            seen.add(key)
+            result.append(item)
+        return result
+
+    def discover(self, skills_dir: str | None = None, cwd: Path | None = None) -> list[SkillRecord]:
+        """扫描所有候选目录，发现已安装的 Skill。
+
+        判定条件：目录下必须存在 data/VERSION.json 文件。
+        解析失败（JSON 格式错误等）的目录会被静默跳过。
+        """
+        records: list[SkillRecord] = []
+        for base_dir in self.candidate_dirs(skills_dir=skills_dir, cwd=cwd):
+            if not base_dir.exists():
+                continue
+            # 遍历子目录，按名称排序保证输出稳定
+            for skill_dir in sorted(p for p in base_dir.iterdir() if p.is_dir()):
+                version_file = skill_dir / "data" / "VERSION.json"
+                if not version_file.exists():
+                    continue
+                try:
+                    payload = json.loads(version_file.read_text(encoding="utf-8"))
+                except Exception:
+                    continue
+                # 根据路径推断运行时类型
+                runtime = self._infer_runtime(skill_dir)
+                records.append(
+                    SkillRecord(
+                        name=skill_dir.name,
+                        version=str(payload.get("version", "unknown")),
+                        runtime=runtime,
+                        root=skill_dir,
+                        version_file=version_file,
+                    )
+                )
+        return records
+
+    def detect_install_target(self, cwd: Path | None = None, preferred_runtime: str | None = None) -> tuple[str, Path]:
+        """检测新 Skill 应该安装到哪个目录。
+
+        优先使用 preferred_runtime 参数，否则根据当前目录下是否存在对应运行时目录推断。
+        默认回退到 claude 运行时。
+
+        Returns:
+            (runtime, target_path) 二元组
+        """
+        current = cwd or Path.cwd()
+        # 显式指定运行时
+        runtime_dirs = {
+            "claude":   current / ".claude" / "skills",
+            "openclaw": current / ".openclaw" / "skills",
+            "codex":    current / ".codex" / "skills",
+            "opencode": current / ".opencode" / "skills",
+        }
+        if preferred_runtime and preferred_runtime in runtime_dirs:
+            return preferred_runtime, runtime_dirs[preferred_runtime]
+
+        # 自动检测：根据当前目录下已有的运行时目录推断
+        for runtime, path in runtime_dirs.items():
+            if path.parent.exists():
+                return runtime, path
+        # 默认使用 claude 运行时
+        return "claude", current / ".claude" / "skills"
+
+    def detect_install_targets(self, cwd: Path | None = None, preferred_runtimes: list[str] | None = None) -> list[tuple[str, Path]]:
+        """检测多个安装目标。"""
+        current = cwd or Path.cwd()
+
+        if preferred_runtimes:
+            targets: list[tuple[str, Path]] = []
+            for runtime in preferred_runtimes:
+                normalized = runtime.strip().lower()
+                if normalized == "all":
+                    return self.detect_available_install_targets(cwd=current)
+                _, path = self.detect_install_target(cwd=current, preferred_runtime=normalized)
+                targets.append((normalized, path))
+            return self._dedupe_targets(targets)
+
+        available = self.detect_available_install_targets(cwd=current)
+        if available:
+            return available
+
+        runtime, target = self.detect_install_target(cwd=current, preferred_runtime=None)
+        return [(runtime, target)]
+
+    def detect_available_install_targets(self, cwd: Path | None = None) -> list[tuple[str, Path]]:
+        """根据当前目录已存在的运行时目录，返回可用目标列表（项目级）。"""
+        current = cwd or Path.cwd()
+        targets: list[tuple[str, Path]] = []
+        if (current / ".claude").exists():
+            targets.append(("claude", current / ".claude" / "skills"))
+        if (current / ".openclaw").exists():
+            targets.append(("openclaw", current / ".openclaw" / "skills"))
+        return self._dedupe_targets(targets)
+
+    def detect_global_install_targets(self) -> list[tuple[str, Path]]:
+        """检测全局已安装的 AI 工具，返回对应的全局 Skills 安装目录。
+
+        检测规则（opscli 多工具 Skills 支持路径对照表）：
+
+        工具          macOS/Linux               Windows
+        Claude Code   ~/.claude/skills/         %USERPROFILE%/.claude/skills/
+        OpenClaw      ~/.openclaw/skills/        %USERPROFILE%/.openclaw/skills/
+        Codex CLI     ~/.codex/skills/           %USERPROFILE%/.codex/skills/
+        OpenCode      ~/.config/opencode/skills/ %LOCALAPPDATA%/opencode/skills/
+
+        检测条件：配置目录存在 或 对应命令可用（which）。
+        返回 [(runtime, skills_dir), ...] 列表，按检测顺序排列，已去重。
+        """
+        home = Path.home()
+        targets: list[tuple[str, Path]] = []
+
+        # Claude Code：~/.claude/ 存在 或 `which claude` 可用
+        if (home / ".claude").exists() or shutil.which("claude") is not None:
+            targets.append(("claude", home / ".claude" / "skills"))
+
+        # OpenClaw：~/.openclaw/ 存在 或 `which openclaw` 可用
+        if (home / ".openclaw").exists() or shutil.which("openclaw") is not None:
+            targets.append(("openclaw", home / ".openclaw" / "skills"))
+
+        # Codex CLI：~/.codex/ 存在 或 `which codex` 可用
+        if (home / ".codex").exists() or shutil.which("codex") is not None:
+            targets.append(("codex", home / ".codex" / "skills"))
+
+        # OpenCode：~/.config/opencode/（macOS/Linux）或 %LOCALAPPDATA%\opencode\（Windows）存在，或 `which opencode` 可用
+        opencode_config = self._opencode_config_dir()
+        if opencode_config.exists() or shutil.which("opencode") is not None:
+            targets.append(("opencode", self._opencode_skills_dir()))
+
+        return self._dedupe_targets(targets)
+
+    def _opencode_config_dir(self) -> Path:
+        """返回 OpenCode 的配置根目录（跨平台）。"""
+        if os.name == "nt":
+            localappdata = os.environ.get("LOCALAPPDATA", "")
+            return Path(localappdata) / "opencode" if localappdata else Path.home() / ".config" / "opencode"
+        return Path.home() / ".config" / "opencode"
+
+    def _opencode_skills_dir(self) -> Path:
+        """返回 OpenCode 的 Skills 安装目录（跨平台）。"""
+        return self._opencode_config_dir() / "skills"
+
+    def _dedupe_targets(self, targets: list[tuple[str, Path]]) -> list[tuple[str, Path]]:
+        seen: set[tuple[str, str]] = set()
+        result: list[tuple[str, Path]] = []
+        for runtime, path in targets:
+            key = (runtime, str(path))
+            if key in seen:
+                continue
+            seen.add(key)
+            result.append((runtime, path))
+        return result
+
+    def _infer_runtime(self, skill_dir: Path) -> str:
+        """根据 Skill 目录路径推断运行时类型。
+
+        优先匹配最具体的特征路径段，无法识别时默认返回 claude。
+        """
+        parts = {part.lower() for part in skill_dir.parts}
+        if ".openclaw" in parts:
+            return "openclaw"
+        if ".codex" in parts:
+            return "codex"
+        if "opencode" in parts:
+            return "opencode"
+        return "claude"

opscli/skills/domain/__init__.py

@@ -0,0 +1,23 @@
+"""skills 领域模型与异常。"""
+
+from opscli.skills.domain.exceptions import SkillRemoteError, SkillsError, error_to_dict
+from opscli.skills.domain.models import (
+    SkillBatchInstallResult,
+    SkillBatchUpgradeResult,
+    SkillInstallResult,
+    SkillRecord,
+    SkillUpgradeResult,
+    runtime_to_tool_name,
+)
+
+__all__ = [
+    "SkillsError",
+    "SkillRemoteError",
+    "error_to_dict",
+    "runtime_to_tool_name",
+    "SkillRecord",
+    "SkillInstallResult",
+    "SkillBatchInstallResult",
+    "SkillUpgradeResult",
+    "SkillBatchUpgradeResult",
+]