aukeys-opscli 0.0.6__py3-none-any.whl

opscli/skills/domain/exceptions.py

@@ -0,0 +1,51 @@
+"""skills 模块异常定义。
+
+统一封装对外错误对象，保证 CLI JSON 输出结构稳定。
+"""
+
+from __future__ import annotations
+
+
+class SkillsError(Exception):
+    """skills 模块统一异常基类。"""
+
+    def to_dict(self) -> dict[str, object]:
+        """转换为稳定的错误对象，便于 CLI 直接输出 JSON。"""
+        return {
+            "type": self.__class__.__name__,
+            "message": str(self),
+        }
+
+
+class SkillRemoteError(SkillsError):
+    """远端 Skill 接口异常。"""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        endpoint: str | None = None,
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.endpoint = endpoint
+        self.status_code = status_code
+
+    def to_dict(self) -> dict[str, object]:
+        """输出附带远端定位信息的错误对象。"""
+        payload = super().to_dict()
+        if self.endpoint is not None:
+            payload["endpoint"] = self.endpoint
+        if self.status_code is not None:
+            payload["status_code"] = self.status_code
+        return payload
+
+
+def error_to_dict(exc: Exception) -> dict[str, object]:
+    """将任意异常转换为稳定的错误对象。"""
+    if isinstance(exc, SkillsError):
+        return exc.to_dict()
+    return {
+        "type": exc.__class__.__name__,
+        "message": str(exc),
+    }

opscli/skills/domain/models.py

@@ -0,0 +1,144 @@
+"""Skills 模块的数据模型定义。
+
+包含 Skill 生命周期中各阶段的数据结构：发现记录、安装结果、升级结果。
+所有 dataclass 均提供 to_dict() 方法用于 JSON 序列化输出。
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+def runtime_to_tool_name(runtime: str) -> str:
+    """将内部 runtime 标识转换为对外稳定的工具名。"""
+    mapping = {
+        "claude": "claude-code",
+        "openclaw": "openclaw",
+    }
+    return mapping.get(runtime, runtime)
+
+
+@dataclass
+class SkillRecord:
+    """已发现的 Skill 记录。
+
+    由 SkillDetector 扫描磁盘目录后生成，描述一个已安装 Skill 的基本信息。
+    """
+
+    name: str           # Skill 名称，对应目录名
+    version: str        # 当前版本号，读取自 data/VERSION.json
+    runtime: str        # 运行时类型：claude 或 openclaw
+    root: Path          # Skill 根目录绝对路径
+    version_file: Path  # VERSION.json 文件绝对路径
+
+    def to_dict(self) -> dict:
+        """转换为可 JSON 序列化的字典，Path 字段转为字符串。"""
+        data = asdict(self)
+        data["runtime"] = runtime_to_tool_name(self.runtime)
+        data["root"] = str(self.root)
+        data["version_file"] = str(self.version_file)
+        return data
+
+
+@dataclass
+class SkillInstallResult:
+    """Skill 安装操作的结果。
+
+    由 SkillsManager.install() 返回，记录安装目标路径及是否覆盖了已有安装。
+    """
+
+    name: str           # Skill 名称
+    runtime: str        # 目标运行时类型
+    target_dir: Path    # 安装目标目录
+    version: str        # 安装后的版本号
+    replaced: bool      # 是否覆盖了已有安装
+
+    def to_dict(self) -> dict:
+        """转换为可 JSON 序列化的字典，Path 字段转为字符串。"""
+        data = asdict(self)
+        data["runtime"] = runtime_to_tool_name(self.runtime)
+        data["target_dir"] = str(self.target_dir)
+        return data
+
+
+@dataclass
+class SkillBatchInstallResult:
+    """批量安装结果。"""
+
+    name: str
+    installs: list[SkillInstallResult]
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "version": self.installs[0].version if self.installs else "unknown",
+            "installed_paths": [
+                {
+                    "tool": runtime_to_tool_name(item.runtime),
+                    "path": str(item.target_dir),
+                    "replaced": item.replaced,
+                }
+                for item in self.installs
+            ],
+        }
+
+
+@dataclass
+class SkillUpgradeResult:
+    """Skill 升级操作的结果。
+
+    由 SkillsUpdater.upgrade_dataset_fields() 返回，记录版本变化和是否实际更新。
+    """
+
+    name: str               # Skill 名称
+    from_version: str       # 升级前版本号
+    to_version: str         # 升级后版本号（未更新时与 from_version 相同）
+    runtime: str            # 所属运行时
+    target_dir: Path        # Skill 根目录
+    updated: bool           # 是否实际执行了更新
+    field_count: int = 0    # 当前用户可见字段数
+
+    def to_dict(self) -> dict:
+        """转换为可 JSON 序列化的字典，Path 字段转为字符串。"""
+        data = asdict(self)
+        data["runtime"] = runtime_to_tool_name(self.runtime)
+        data["target_dir"] = str(self.target_dir)
+        return data
+
+
+@dataclass
+class SkillBatchUpgradeResult:
+    """批量升级结果。"""
+
+    name: str
+    results: list[SkillUpgradeResult]
+
+    def to_dict(self) -> dict:
+        updated = self._group_results(updated=True)
+        already_latest = self._group_results(updated=False)
+        return {
+            "updated": updated,
+            "already_latest": already_latest,
+            "failed": [],
+        }
+
+    def _group_results(self, *, updated: bool) -> list[dict]:
+        grouped: dict[tuple[str, str, str, int], dict] = {}
+        for item in self.results:
+            if item.updated is not updated:
+                continue
+            key = (item.name, item.from_version, item.to_version, item.field_count)
+            group = grouped.setdefault(
+                key,
+                {
+                    "name": item.name,
+                    "from_version": item.from_version,
+                    "to_version": item.to_version,
+                    "field_count": item.field_count,
+                    "tools": [],
+                },
+            )
+            group["tools"].append(runtime_to_tool_name(item.runtime))
+
+        return list(grouped.values())

opscli/skills/exceptions.py

@@ -0,0 +1,5 @@
+"""skills exceptions 兼容导出。"""
+
+from opscli.skills.domain.exceptions import SkillRemoteError, SkillsError, error_to_dict
+
+__all__ = ["SkillsError", "SkillRemoteError", "error_to_dict"]

opscli/skills/manager.py

@@ -0,0 +1,5 @@
+"""skills manager 兼容导出。"""
+
+from opscli.skills.services.manager import SkillsManager
+
+__all__ = ["SkillsManager"]

opscli/skills/models.py

@@ -0,0 +1,19 @@
+"""skills models 兼容导出。"""
+
+from opscli.skills.domain.models import (
+    SkillBatchInstallResult,
+    SkillBatchUpgradeResult,
+    SkillInstallResult,
+    SkillRecord,
+    SkillUpgradeResult,
+    runtime_to_tool_name,
+)
+
+__all__ = [
+    "runtime_to_tool_name",
+    "SkillRecord",
+    "SkillInstallResult",
+    "SkillBatchInstallResult",
+    "SkillUpgradeResult",
+    "SkillBatchUpgradeResult",
+]

opscli/skills/services/__init__.py

@@ -0,0 +1,5 @@
+"""skills 服务层。"""
+
+from opscli.skills.services.manager import SkillsManager
+
+__all__ = ["SkillsManager"]

opscli/skills/services/manager.py

@@ -0,0 +1,276 @@
+"""Skill 生命周期管理器。
+
+提供 Skill 的安装、列表查询、状态检查、升级等核心业务逻辑。
+是 CLI 层（cli.py）和底层组件（detector/updater）之间的中间协调层。
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+from opscli.skills.discovery.detector import SkillDetector
+from opscli.skills.domain.exceptions import error_to_dict
+from opscli.skills.domain.models import (
+    SkillBatchInstallResult,
+    SkillBatchUpgradeResult,
+    SkillInstallResult,
+    SkillRecord,
+    SkillUpgradeResult,
+    runtime_to_tool_name,
+)
+from opscli.skills.sync.updater import SkillsUpdater
+
+
+class SkillsManager:
+    """Skill 管理器，协调检测器和更新器完成 Skill 生命周期管理。"""
+
+    def __init__(self) -> None:
+        self.detector = SkillDetector()             # 负责 Skill 发现
+        self.updater = SkillsUpdater()              # 负责远端数据拉取和升级
+        self.templates_dir = Path(__file__).parent.parent / "templates"  # 内置 Skill 模板目录
+
+    def list_templates(self) -> list[dict]:
+        """扫描内置模板目录，返回可安装的 Skill 列表。
+
+        每项包含 name、version、description（从 SKILL.md 首段提取）。
+        """
+        templates: list[dict] = []
+        if not self.templates_dir.exists():
+            return templates
+        for skill_dir in sorted(p for p in self.templates_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
+            version = str(payload.get("version", "unknown"))
+            description = self._extract_skill_description(skill_dir)
+            templates.append({"name": skill_dir.name, "version": version, "description": description})
+        return templates
+
+    def _extract_skill_description(self, skill_dir: Path) -> str:
+        """从 SKILL.md 提取 Skill 简介（标题后第一个非空行）。
+
+        自动跳过 YAML frontmatter（--- 包裹区域）。
+        """
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.exists():
+            return ""
+        try:
+            lines = skill_md.read_text(encoding="utf-8").splitlines()
+        except Exception:
+            return ""
+
+        # 跳过 YAML frontmatter（以 --- 开头和结尾的区域）
+        in_frontmatter = False
+        content_lines: list[str] = []
+        for line in lines:
+            stripped = line.strip()
+            if stripped == "---" and not content_lines:
+                in_frontmatter = not in_frontmatter
+                continue
+            if in_frontmatter:
+                continue
+            content_lines.append(line)
+
+        # 从正文内容中提取：跳过标题行（# 开头），取第一个非空的普通文本行
+        skip_title = True
+        for line in content_lines:
+            stripped = line.strip()
+            if skip_title and stripped.startswith("#"):
+                skip_title = False
+                continue
+            if stripped and not stripped.startswith("#") and not stripped.startswith(">"):
+                return stripped[:30] + ("…" if len(stripped) > 30 else "")
+        return ""
+
+    def list_skills(self, skills_dir: str | None = None, cwd: Path | None = None) -> list[SkillRecord]:
+        """列出所有已安装的 Skill，委托给 SkillDetector.discover()。"""
+        return self.detector.discover(skills_dir=skills_dir, cwd=cwd)
+
+    def install(
+        self,
+        skill_name: str,
+        *,
+        skills_dir: str | None = None,
+        cwd: Path | None = None,
+        runtime: str | list[str] | None = None,
+        force: bool = False,
+    ) -> SkillBatchInstallResult:
+        """从内置模板安装 Skill 到目标目录。
+
+        流程：
+        1. 检查模板是否存在（只支持内置 Skill）
+        2. 确定安装目标路径（显式指定 或 自动检测）
+        3. 若目标已存在且未指定 force，则报错
+        4. 将模板目录整体复制到目标位置
+
+        Args:
+            skill_name: 要安装的 Skill 名称（如 "ops-dataset-query"）
+            skills_dir: 显式指定安装根目录
+            cwd: 当前工作目录，用于自动检测安装目标
+            runtime: 运行时类型（claude/openclaw）
+            force: 是否覆盖已存在的安装
+        """
+        template_dir = self.templates_dir / skill_name
+        if not template_dir.exists():
+            raise ValueError(f"不支持的内置 Skill: {skill_name}")
+
+        current = cwd or Path.cwd()
+        if skills_dir:
+            targets = [(str(runtime or "custom"), Path(skills_dir).expanduser())]
+        else:
+            runtime_list = self._normalize_runtime_arg(runtime)
+            targets = self.detector.detect_install_targets(
+                cwd=current,
+                preferred_runtimes=runtime_list,
+            )
+
+        installs: list[SkillInstallResult] = []
+        for target_runtime, target_root in targets:
+            target_root.mkdir(parents=True, exist_ok=True)
+            target_dir = target_root / skill_name
+
+            replaced = False
+            if target_dir.exists():
+                if not force:
+                    raise ValueError(f"Skill 已存在: {target_dir}")
+                shutil.rmtree(target_dir)
+                replaced = True
+
+            shutil.copytree(template_dir, target_dir)
+            installs.append(
+                SkillInstallResult(
+                    name=skill_name,
+                    runtime=target_runtime,
+                    target_dir=target_dir,
+                    version=self._read_version(target_dir),
+                    replaced=replaced,
+                )
+            )
+
+        return SkillBatchInstallResult(name=skill_name, installs=installs)
+
+    def status(self, skills_dir: str | None = None, cwd: Path | None = None) -> dict:
+        """查询 Skill 安装状态，包含本地信息和远端版本对比。
+
+        返回结构：
+        - installed: 本地已安装 Skill 列表（附带远端版本和是否有更新）
+        - remote_manifest: 远端 manifest 数据（可能为 None）
+        - remote_error: 远端请求失败时的错误信息
+        """
+        records = self.list_skills(skills_dir=skills_dir, cwd=cwd)
+
+        # 获取远端 manifest（仅支持 ops-dataset-query）
+        remote_manifest = None
+        remote_summary = None
+        remote_error = None
+        try:
+            remote_summary = self.updater.build_remote_summary("ops-dataset-query")
+            remote_manifest = remote_summary.get("manifest")
+        except Exception as exc:
+            remote_error = error_to_dict(exc)
+
+        remote_version = None
+        if remote_manifest:
+            remote_version = str(remote_manifest.get("version", "v0.0.0"))
+
+        # 为每个已安装 Skill 附带远端版本信息
+        enriched: list[dict] = []
+        for item in records:
+            row = item.to_dict()
+            if item.name == "ops-dataset-query" and remote_version:
+                row["remote_version"] = remote_version
+                row["has_update"] = self.updater.compare_versions(item.version, remote_version) < 0
+            else:
+                row["remote_version"] = None
+                row["has_update"] = False
+            enriched.append(row)
+
+        return {
+            "skills": self._summarize_installed_skills(enriched),
+            "installed": enriched,
+            "remote_manifest": remote_manifest,
+            "remote_summary": remote_summary,
+            "remote_error": remote_error,
+        }
+
+    def upgrade(
+        self,
+        *,
+        name: str = "ops-dataset-query",
+        skills_dir: str | None = None,
+        cwd: Path | None = None,
+        force: bool = False,
+    ) -> SkillBatchUpgradeResult:
+        """升级指定 Skill 到最新版本。
+
+        当前仅支持 ops-dataset-query 的升级。会先查找本地已安装的记录，
+        再委托给 SkillsUpdater 执行实际的远端数据拉取和文件替换。
+
+        Args:
+            name: 要升级的 Skill 名称
+            skills_dir: 指定扫描目录
+            cwd: 当前工作目录
+            force: 是否强制升级（即使版本号相同也重新拉取）
+        """
+        records = self.list_skills(skills_dir=skills_dir, cwd=cwd)
+        targets = [item for item in records if item.name == name]
+        if not targets:
+            raise ValueError(f"未找到已安装 Skill: {name}")
+        if name != "ops-dataset-query":
+            raise ValueError(f"暂不支持升级 Skill: {name}")
+
+        results = [
+            self.updater.upgrade_ops_dataset_query(target, force=force)
+            for target in targets
+        ]
+        return SkillBatchUpgradeResult(name=name, results=results)
+
+    def _normalize_runtime_arg(self, runtime: str | list[str] | None) -> list[str] | None:
+        """统一解析 runtime 参数。"""
+        if runtime is None:
+            return None
+        if isinstance(runtime, list):
+            return runtime
+        parts = [item.strip() for item in runtime.split(",") if item.strip()]
+        return parts or None
+
+    def _read_version(self, target_dir: Path) -> str:
+        """从安装目录的 data/VERSION.json 中读取版本号。"""
+        version_file = target_dir / "data" / "VERSION.json"
+        payload = json.loads(version_file.read_text(encoding="utf-8"))
+        return str(payload.get("version", "unknown"))
+
+    def _summarize_installed_skills(self, records: list[dict]) -> list[dict]:
+        """按 skill 名称聚合安装记录，生成稳定的对外 JSON 结构。"""
+        grouped: dict[str, dict] = {}
+        for item in records:
+            group = grouped.setdefault(
+                item["name"],
+                {
+                    "name": item["name"],
+                    "local_version": item["version"],
+                    "remote_version": item["remote_version"],
+                    "has_update": item["has_update"],
+                    "installed_paths": [],
+                },
+            )
+
+            if item["version"] != group["local_version"]:
+                group["local_version"] = max(str(group["local_version"]), str(item["version"]))
+            if item["remote_version"] and not group["remote_version"]:
+                group["remote_version"] = item["remote_version"]
+            group["has_update"] = group["has_update"] or item["has_update"]
+            group["installed_paths"].append(
+                {
+                    "tool": runtime_to_tool_name(item["runtime"]),
+                    "path": item["root"],
+                }
+            )
+
+        return list(grouped.values())

opscli/skills/sync/__init__.py

@@ -0,0 +1,5 @@
+"""skills 同步层。"""
+
+from opscli.skills.sync.updater import SkillsUpdater
+
+__all__ = ["SkillsUpdater"]