abyss-cli 0.1.0__py3-none-any.whl

abyss/extensions/cli.py

@@ -0,0 +1,160 @@
+# -*- coding: utf-8 -*-
+"""
+扩展管理 CLI
+提供 abyss extension install/update/remove/list/show 子命令。
+
+使用 ABYSS_HOME 环境变量可覆盖默认的 ~/.abyss 根目录（便于测试）。
+"""
+import os
+import shutil
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from .installer import PackageInstaller
+from .registry import (
+    ExtensionRegistry, ExtensionType, InstalledExtension, create_default_registry,
+)
+
+
+def _abyss_root() -> Path:
+    """获取 abyss 根目录，优先用 ABYSS_HOME 环境变量"""
+    home = os.environ.get("ABYSS_HOME")
+    if home:
+        return Path(home)
+    return Path.home() / ".abyss"
+
+
+def _make_installer(abyss_root: Path) -> PackageInstaller:
+    """构造 PackageInstaller（带 cache + registry）"""
+    cache_dir = abyss_root / ".cache" / "git"
+    registry = ExtensionRegistry(registry_path=abyss_root / "registry.json")
+    return PackageInstaller(
+        abyss_root=abyss_root,
+        cache_dir=cache_dir,
+        registry=registry,
+    )
+
+
+def _type_from_str(s: str) -> ExtensionType:
+    """字符串转 ExtensionType"""
+    return ExtensionType(s.lower())
+
+
+@click.group(name="extension")
+def extension_cli():
+    """管理 Skill/Command/Hook/MCP 扩展包。"""
+
+
+@extension_cli.command(name="install")
+@click.argument("url")
+@click.option("--id", "ext_id", required=True, help="扩展唯一标识（用于管理）")
+@click.option("--type", "ext_type_str", type=click.Choice(["skill", "command", "hook", "mcp"]),
+              default=None, help="限定安装类型，默认自动检测")
+@click.option("--subpath", default=None, help="仓库内子目录路径")
+def install_cmd(url, ext_id, ext_type_str, subpath):
+    """从 Git 仓库或本地路径安装扩展。"""
+    abyss_root = _abyss_root()
+    installer = _make_installer(abyss_root)
+    registry = installer._registry
+
+    if registry.get(ext_id) is not None:
+        raise click.ClickException(f"扩展 ID 已存在: {ext_id}（请用 update 或先 remove）")
+
+    ext_type = _type_from_str(ext_type_str) if ext_type_str else None
+
+    full_url = url
+    if subpath:
+        sep = "&" if "?" in full_url else "?"
+        full_url = f"{full_url}{sep}subdir={subpath}"
+
+    click.echo(f"正在安装 {ext_id} from {url} ...")
+    ext = installer.install(url=full_url, ext_id=ext_id, ext_type=ext_type)
+    if ext is None:
+        raise click.ClickException(
+            f"安装失败：URL 无效或仓库内未发现已知扩展类型（skills/commands/hooks/mcp.json）"
+        )
+
+    click.echo(f"[OK] 已安装 {ext.id} (类型: {ext.type.value}, commit: {ext.commit[:8]})")
+
+
+@extension_cli.command(name="update")
+@click.argument("ext_id")
+def update_cmd(ext_id):
+    """更新已安装的扩展。"""
+    abyss_root = _abyss_root()
+    installer = _make_installer(abyss_root)
+    click.echo(f"正在更新 {ext_id} ...")
+    ext = installer.update(ext_id)
+    if ext is None:
+        raise click.ClickException(f"扩展不存在: {ext_id}")
+    click.echo(f"[OK] 已更新 {ext.id} (commit: {ext.commit[:8]})")
+
+
+@extension_cli.command(name="remove")
+@click.argument("ext_id")
+@click.option("-y", "--yes", is_flag=True, help="跳过确认")
+def remove_cmd(ext_id, yes):
+    """卸载已安装的扩展。"""
+    abyss_root = _abyss_root()
+    installer = _make_installer(abyss_root)
+    ext = installer._registry.get(ext_id)
+    if ext is None:
+        raise click.ClickException(f"扩展不存在: {ext_id}")
+
+    if not yes:
+        click.confirm(f"确认卸载 {ext_id} ({ext.type.value})?", abort=True)
+
+    if installer.remove(ext_id):
+        click.echo(f"[OK] 已卸载 {ext_id}")
+    else:
+        raise click.ClickException(f"卸载失败: {ext_id}")
+
+
+@extension_cli.command(name="list")
+@click.option("--type", "type_filter", type=click.Choice(["skill", "command", "hook", "mcp"]),
+              default=None, help="按类型过滤")
+def list_cmd(type_filter):
+    """列出已安装的扩展。"""
+    abyss_root = _abyss_root()
+    registry = ExtensionRegistry(registry_path=abyss_root / "registry.json")
+
+    if type_filter:
+        exts = registry.list_by_type(_type_from_str(type_filter))
+    else:
+        exts = registry.list_all()
+
+    if not exts:
+        click.echo("暂无已安装的扩展。使用 `abyss extension install <url>` 安装。")
+        return
+
+    # 表格输出
+    click.echo(f"{'ID':<20} {'类型':<10} {'来源':<50} {'Commit':<10}")
+    click.echo("-" * 92)
+    for ext in exts:
+        source = ext.source_url
+        if len(source) > 48:
+            source = source[:45] + "..."
+        click.echo(
+            f"{ext.id:<20} {ext.type.value:<10} {source:<50} {ext.commit[:8]:<10}"
+        )
+
+
+@extension_cli.command(name="show")
+@click.argument("ext_id")
+def show_cmd(ext_id):
+    """显示扩展详细信息。"""
+    abyss_root = _abyss_root()
+    registry = ExtensionRegistry(registry_path=abyss_root / "registry.json")
+    ext = registry.get(ext_id)
+    if ext is None:
+        raise click.ClickException(f"扩展不存在: {ext_id}")
+
+    click.echo(f"ID:           {ext.id}")
+    click.echo(f"类型:         {ext.type.value}")
+    click.echo(f"来源:         {ext.source_url}")
+    click.echo(f"子目录:       {ext.subpath or '(根)'}")
+    click.echo(f"Ref:          {ext.ref}")
+    click.echo(f"Commit:       {ext.commit}")
+    click.echo(f"安装时间:     {ext.installed_at}")

abyss/extensions/installer.py

@@ -0,0 +1,452 @@
+# -*- coding: utf-8 -*-
+"""
+扩展包安装器
+从 Git 仓库或本地路径安装 Skill/Command/Hook/MCP，并自动分发到 ~/.abyss/ 对应目录。
+
+仓库约定目录结构：
+  skills/<name>/SKILL.md   → ~/.abyss/skills/<name>/SKILL.md
+  commands/*.md            → ~/.abyss/commands/*.md
+  hooks/<event>/*.{bat,sh} → ~/.abyss/hooks/<event>/*
+  mcp.json                 → ~/.abyss/mcp.json (合并)
+
+文件分发时按 ext_id 隔离到 ~/.abyss/.installed/<ext_id>/ 目录，
+remove 时按隔离目录精确删除，不会误删其他扩展。
+"""
+import shutil
+import subprocess
+import hashlib
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Callable, List, Optional, Set
+from urllib.parse import parse_qs
+
+from .url_parser import parse_source_url, PackageSource
+from .registry import (
+    ExtensionRegistry, ExtensionType, InstalledExtension,
+)
+
+
+# 已知的分发目录
+_KNOWN_DIRS = {"skills", "commands", "hooks"}
+_MCP_FILE = "mcp.json"
+
+
+def _default_fetcher(src: PackageSource, target: Path) -> str:
+    """默认 fetcher：调 git clone 浅克隆到 target。
+
+    返回 commit hash。
+    """
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if target.exists():
+        shutil.rmtree(target)
+
+    cmd = ["git", "clone", "--depth=1"]
+    if src.ref and src.ref != "HEAD":
+        cmd.extend(["--branch", src.ref])
+    cmd.extend([src.clone_url, str(target)])
+    subprocess.run(cmd, check=True, capture_output=True, text=True, encoding="utf-8")
+
+    # 获取 commit hash
+    out = subprocess.run(
+        ["git", "-C", str(target), "rev-parse", "HEAD"],
+        capture_output=True, text=True, check=True, encoding="utf-8"
+    )
+    return out.stdout.strip()
+
+
+def _commit_from_fetcher(src: PackageSource, cache_target: Path) -> str:
+    """从缓存目录读取 commit hash"""
+    head_file = cache_target / ".abyss_commit"
+    if head_file.exists():
+        return head_file.read_text(encoding="utf-8").strip()
+    try:
+        out = subprocess.run(
+            ["git", "-C", str(cache_target), "rev-parse", "HEAD"],
+            capture_output=True, text=True, encoding="utf-8"
+        )
+        if out.returncode == 0:
+            commit = out.stdout.strip()
+            cache_target.mkdir(parents=True, exist_ok=True)
+            head_file.write_text(commit, encoding="utf-8")
+            return commit
+    except Exception:
+        pass
+    return ""
+
+
+class PackageInstaller:
+    """扩展包安装器。"""
+
+    def __init__(
+        self,
+        abyss_root: Path,
+        cache_dir: Path,
+        registry: ExtensionRegistry,
+        fetcher: Optional[Callable[[PackageSource, Path], str]] = None,
+    ):
+        self._abyss_root = Path(abyss_root)
+        self._cache_dir = Path(cache_dir)
+        self._registry = registry
+        self._fetcher = fetcher or _default_fetcher
+        # 每个 ext_id 的隔离安装目录
+        self._installed_root = self._abyss_root / ".installed"
+
+    def _cache_path(self, src: PackageSource) -> Path:
+        """根据 clone_url 派生缓存目录名（用 hash 避免路径过长）"""
+        url_hash = hashlib.md5(src.clone_url.encode("utf-8")).hexdigest()[:12]
+        return self._cache_dir / url_hash
+
+    def _isolation_dir(self, ext_id: str) -> Path:
+        """每个 ext_id 独立的安装目录"""
+        return self._installed_root / ext_id
+
+    def _dispatch_files(
+        self,
+        source_dir: Path,
+        target_root: Path,
+        ext_id: str,
+        ext_type: Optional[ExtensionType] = None,
+    ) -> Set[str]:
+        """把 source_dir 中的 skills/commands/hooks 分发到 target_root。
+
+        实际写入位置：target_root/.installed/<ext_id>/<subdir>
+        这样 remove 时可按 ext_id 精确清理。
+
+        返回分发的扩展类型集合。
+        """
+        if not source_dir.exists() or not source_dir.is_dir():
+            return set()
+
+        isolation = target_root / ".installed" / ext_id
+        isolation.mkdir(parents=True, exist_ok=True)
+        dispatched = set()
+
+        # 子目录分发：skills / commands / hooks
+        if ext_type is None or ext_type == ExtensionType.SKILL:
+            src_skills = source_dir / "skills"
+            if src_skills.exists():
+                self._copy_tree(src_skills, isolation / "skills")
+                dispatched.add("skills")
+        if ext_type is None or ext_type == ExtensionType.COMMAND:
+            src_cmds = source_dir / "commands"
+            if src_cmds.exists():
+                self._copy_tree(src_cmds, isolation / "commands")
+                dispatched.add("commands")
+        if ext_type is None or ext_type == ExtensionType.HOOK:
+            src_hooks = source_dir / "hooks"
+            if src_hooks.exists():
+                self._copy_tree(src_hooks, isolation / "hooks")
+                dispatched.add("hooks")
+
+        # MCP 配置：合并到 ~/.abyss/mcp.json
+        if ext_type is None or ext_type == ExtensionType.MCP:
+            src_mcp = source_dir / _MCP_FILE
+            if src_mcp.exists():
+                isolation_mcp = isolation / _MCP_FILE
+                shutil.copy2(src_mcp, isolation_mcp)
+                self._merge_mcp_config(isolation_mcp, target_root / _MCP_FILE)
+                dispatched.add("mcp")
+
+        # 创建符号链接或创建聚合目录：
+        # 实际上技能加载器从 ~/.abyss/skills/ 扫描
+        # 所以要让 abyss 能找到这些文件
+        self._link_to_aggregate(target_root, ext_id, dispatched)
+
+        return dispatched
+
+    def _copy_tree(self, src: Path, dst: Path) -> None:
+        """复制整个目录树"""
+        if dst.exists():
+            shutil.rmtree(dst)
+        shutil.copytree(src, dst)
+
+    def _link_to_aggregate(
+        self,
+        target_root: Path,
+        ext_id: str,
+        dispatched: Set[str],
+    ) -> None:
+        """把隔离目录中分发的内容用符号链接暴露到 aggregate 目录。
+
+        aggregate 目录布局（与原约定一致）：
+          ~/.abyss/skills/<name>/SKILL.md
+          ~/.abyss/commands/<name>.md
+          ~/.abyss/hooks/<event>/<script>
+        """
+        isolation = target_root / ".installed" / ext_id
+
+        for kind in ("skills", "commands", "hooks"):
+            if kind not in dispatched:
+                continue
+            src = isolation / kind
+            if not src.exists():
+                continue
+            agg_root = target_root / kind
+            agg_root.mkdir(parents=True, exist_ok=True)
+            for child in src.iterdir():
+                dst = agg_root / child.name
+                if dst.exists() or dst.is_symlink():
+                    if dst.is_symlink() or dst.is_file():
+                        dst.unlink()
+                    elif dst.is_dir():
+                        shutil.rmtree(dst)
+                try:
+                    # Windows 上 symlink 可能需要开发者权限；fallback 到复制
+                    dst.symlink_to(child.resolve(), target_is_directory=child.is_dir())
+                except (OSError, NotImplementedError):
+                    if child.is_dir():
+                        if dst.exists():
+                            shutil.rmtree(dst)
+                        shutil.copytree(child, dst)
+                    else:
+                        shutil.copy2(child, dst)
+
+        # mcp.json 是合并而非链接，单独处理
+        if "mcp" in dispatched:
+            mcp_dst = target_root / _MCP_FILE
+            # 已经在 _merge_mcp_config 中合并，隔离目录里保留完整副本
+            pass
+
+    def _merge_mcp_config(self, new_mcp: Path, dest_mcp: Path) -> None:
+        """合并 mcp.json 中的 mcp_servers 列表到目标文件"""
+        try:
+            new_data = json.loads(new_mcp.read_text(encoding="utf-8"))
+        except Exception:
+            return
+        new_servers = new_data.get("mcp_servers", []) or []
+
+        existing = []
+        if dest_mcp.exists():
+            try:
+                existing_data = json.loads(dest_mcp.read_text(encoding="utf-8"))
+                existing = existing_data.get("mcp_servers", []) or []
+            except Exception:
+                existing = []
+
+        # 按 name 去重
+        seen = {s.get("name") for s in existing if s.get("name")}
+        merged = list(existing)
+        for s in new_servers:
+            if s.get("name") and s["name"] not in seen:
+                merged.append(s)
+                seen.add(s["name"])
+
+        dest_mcp.parent.mkdir(parents=True, exist_ok=True)
+        dest_mcp.write_text(
+            json.dumps({"mcp_servers": merged}, indent=2, ensure_ascii=False),
+            encoding="utf-8"
+        )
+
+    def _remove_dispatched(self, ext_id: str) -> None:
+        """删除指定 ext_id 分发的所有文件"""
+        isolation = self._installed_root / ext_id
+        if not isolation.exists():
+            return
+
+        # 清理 aggregate 中的符号链接
+        for kind in ("skills", "commands", "hooks"):
+            agg_root = self._abyss_root / kind
+            if not agg_root.exists():
+                continue
+            isolation_kind = isolation / kind
+            if not isolation_kind.exists():
+                continue
+            for child in isolation_kind.iterdir():
+                dst = agg_root / child.name
+                if dst.is_symlink():
+                    dst.unlink()
+                elif dst.exists():
+                    if dst.is_dir():
+                        shutil.rmtree(dst)
+                    else:
+                        dst.unlink()
+
+        # 清理 mcp.json 中属于此扩展的 server
+        mcp_isolation = isolation / _MCP_FILE
+        if mcp_isolation.exists():
+            try:
+                iso_data = json.loads(mcp_isolation.read_text(encoding="utf-8"))
+                iso_servers = {s.get("name") for s in iso_data.get("mcp_servers", []) or []}
+                dest_mcp = self._abyss_root / _MCP_FILE
+                if dest_mcp.exists() and iso_servers:
+                    dest_data = json.loads(dest_mcp.read_text(encoding="utf-8"))
+                    dest_data["mcp_servers"] = [
+                        s for s in dest_data.get("mcp_servers", []) or []
+                        if s.get("name") not in iso_servers
+                    ]
+                    dest_mcp.write_text(
+                        json.dumps(dest_data, indent=2, ensure_ascii=False),
+                        encoding="utf-8"
+                    )
+            except Exception:
+                pass
+
+        # 删除整个隔离目录
+        shutil.rmtree(isolation)
+
+    def install(
+        self,
+        url: str,
+        ext_id: str,
+        ext_type: Optional[ExtensionType] = None,
+    ) -> Optional[InstalledExtension]:
+        """安装扩展。返回安装记录，失败返回 None。
+
+        参数：
+            url: Git 仓库 URL 或本地路径
+            ext_id: 扩展唯一标识
+            ext_type: 限定只安装某种类型，None 表示自动检测所有
+        """
+        # 支持本地路径
+        if url.startswith("file://"):
+            from urllib.parse import urlparse
+            import re
+            parsed = urlparse(url)
+            # file:///d:/xxx 标准格式：scheme:// + 空 host + 绝对 path
+            if parsed.path:
+                # 去掉前导 /（Windows 上 Path('/d:/xxx') 不可定位）
+                local_part = parsed.path.lstrip("/")
+            else:
+                # file://xxx 非标准格式（user 输入省略了第三个 /）：
+                # 从 netloc + 原始 URL 推回
+                # 例如 file://d:/xxx 实际 = file:///d:/xxx
+                tail = re.sub(r"^file:///?", "", url)
+                if "?" in tail:
+                    tail = tail.split("?", 1)[0]
+                local_part = tail
+            local_path = Path(local_part)
+            subpath = ""
+            if parsed.query:
+                subpath = parse_qs(parsed.query).get("subdir", [""])[0]
+            if not local_path.exists():
+                return None
+            return self._install_from_local(local_path, ext_id, ext_type, subpath)
+
+        try:
+            src = parse_source_url(url)
+        except ValueError:
+            return None
+
+        cache_target = self._cache_path(src)
+        try:
+            commit = self._fetcher(src, cache_target)
+        except Exception:
+            return None
+
+        if not commit:
+            commit = _commit_from_fetcher(src, cache_target)
+
+        # 提取 subpath
+        if src.subpath:
+            source_dir = cache_target / src.subpath
+        else:
+            source_dir = cache_target
+
+        if not source_dir.exists():
+            return None
+
+        dispatched = self._dispatch_files(
+            source_dir, self._abyss_root, ext_id, ext_type
+        )
+        if not dispatched:
+            return None
+
+        ext = InstalledExtension(
+            id=ext_id,
+            type=ext_type or ExtensionType.SKILL,
+            source_url=url,
+            subpath=src.subpath,
+            ref=src.ref,
+            commit=commit,
+            installed_at=datetime.now().isoformat(timespec="seconds"),
+        )
+        self._registry.add(ext)
+        return ext
+
+    def _install_from_local(
+        self,
+        local_path: Path,
+        ext_id: str,
+        ext_type: Optional[ExtensionType],
+        subpath: str = "",
+    ) -> Optional[InstalledExtension]:
+        """从本地目录安装（开发/测试用）
+
+        参数：
+            local_path: 仓库根目录
+            subpath: 子路径，相对于 local_path。
+                     当指定 subpath 时，按以下规则解析：
+                     - subpath 含 "skills" 段：当 ext_type=SKILL 时视为单个 skill 目录
+                     - 其他情况：subpath 作为分发根，仍按 skills/commands/hooks 扫描
+        """
+        source_dir = local_path / subpath if subpath else local_path
+        if not source_dir.is_dir():
+            return None
+
+        # 如果 subpath 明确指向 skills/<name> 且指定了 SKILL 类型，
+        # 直接把 source_dir 当作单个 skill 目录复制到 ~/.abyss/skills/<name>
+        if (ext_type == ExtensionType.SKILL and subpath
+                and ("skills" in subpath.split("/") or source_dir.joinpath("SKILL.md").exists())):
+            target_skill_dir = self._abyss_root / "skills" / source_dir.name
+            target_skill_dir.parent.mkdir(parents=True, exist_ok=True)
+            self._copy_tree(source_dir, target_skill_dir)
+            isolation = self._abyss_root / ".installed" / ext_id
+            isolation.mkdir(parents=True, exist_ok=True)
+            self._copy_tree(source_dir, isolation / "skills" / source_dir.name)
+            ext = InstalledExtension(
+                id=ext_id,
+                type=ExtensionType.SKILL,
+                source_url=f"file://{local_path}{'?' + 'subdir=' + subpath if subpath else ''}",
+                subpath=subpath,
+                ref="local",
+                commit=hashlib.md5(
+                    str(source_dir.stat().st_mtime).encode("utf-8")
+                ).hexdigest()[:12],
+                installed_at=datetime.now().isoformat(timespec="seconds"),
+            )
+            self._registry.add(ext)
+            return ext
+
+        dispatched = self._dispatch_files(
+            source_dir, self._abyss_root, ext_id, ext_type
+        )
+        if not dispatched:
+            return None
+
+        commit = hashlib.md5(
+            str(source_dir.stat().st_mtime).encode("utf-8")
+        ).hexdigest()[:12]
+
+        ext = InstalledExtension(
+            id=ext_id,
+            type=ext_type or ExtensionType.SKILL,
+            source_url=f"file://{local_path}{'?' + 'subdir=' + subpath if subpath else ''}",
+            subpath=subpath,
+            ref="local",
+            commit=commit,
+            installed_at=datetime.now().isoformat(timespec="seconds"),
+        )
+        self._registry.add(ext)
+        return ext
+
+    def remove(self, ext_id: str) -> bool:
+        """卸载扩展：删除分发的文件并从注册表移除。"""
+        ext = self._registry.get(ext_id)
+        if ext is None:
+            return False
+        self._remove_dispatched(ext_id)
+        self._registry.remove(ext_id)
+        return True
+
+    def update(self, ext_id: str) -> Optional[InstalledExtension]:
+        """更新扩展：重新拉取并分发。"""
+        ext = self._registry.get(ext_id)
+        if ext is None:
+            return None
+        return self.install(
+            url=ext.source_url,
+            ext_id=ext_id,
+            ext_type=ext.type,
+        )