abyss-cli 0.1.0__py3-none-any.whl

abyss/extensions/registry.py

@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+"""
+扩展注册表
+跟踪所有通过 /extension install 安装的扩展，持久化到 ~/.abyss/registry.json。
+记录：ID、类型、来源 URL、subpath、ref、commit hash、安装时间。
+用于：/extension update（按 commit 判断有无更新）、/extension remove（精确清理）。
+"""
+import json
+import threading
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+class ExtensionType(Enum):
+    """扩展类型。"""
+    SKILL = "skill"
+    COMMAND = "command"
+    HOOK = "hook"
+    MCP = "mcp"
+
+
+@dataclass
+class InstalledExtension:
+    """已安装的扩展记录。"""
+    id: str
+    type: ExtensionType
+    source_url: str
+    subpath: str
+    ref: str
+    commit: str
+    installed_at: str
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["type"] = self.type.value
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "InstalledExtension":
+        return cls(
+            id=d["id"],
+            type=ExtensionType(d["type"]),
+            source_url=d["source_url"],
+            subpath=d.get("subpath", ""),
+            ref=d.get("ref", "HEAD"),
+            commit=d.get("commit", ""),
+            installed_at=d.get("installed_at", ""),
+        )
+
+
+class ExtensionRegistry:
+    """已安装扩展的注册表，JSON 持久化。"""
+
+    def __init__(self, registry_path: Path):
+        self._path = registry_path
+        self._lock = threading.Lock()
+        self._items: Dict[str, InstalledExtension] = {}
+        self._load()
+
+    def _load(self) -> None:
+        """从文件加载，文件不存在则空注册表"""
+        if not self._path.exists():
+            return
+        try:
+            with open(self._path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            for ext_data in data.get("extensions", []):
+                ext = InstalledExtension.from_dict(ext_data)
+                self._items[ext.id] = ext
+        except (json.JSONDecodeError, OSError, KeyError):
+            self._items = {}
+
+    def _save(self) -> None:
+        """持久化到文件"""
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        data = {"extensions": [ext.to_dict() for ext in self._items.values()]}
+        with open(self._path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+
+    def add(self, ext: InstalledExtension) -> None:
+        """添加或覆盖扩展记录"""
+        with self._lock:
+            self._items[ext.id] = ext
+            self._save()
+
+    def get(self, ext_id: str) -> Optional[InstalledExtension]:
+        """按 ID 获取扩展"""
+        return self._items.get(ext_id)
+
+    def list_all(self) -> List[InstalledExtension]:
+        """返回所有已安装扩展"""
+        return list(self._items.values())
+
+    def list_by_type(self, ext_type: ExtensionType) -> List[InstalledExtension]:
+        """按类型过滤"""
+        return [e for e in self._items.values() if e.type == ext_type]
+
+    def remove(self, ext_id: str) -> bool:
+        """按 ID 移除。返回是否存在并被移除"""
+        with self._lock:
+            if ext_id in self._items:
+                del self._items[ext_id]
+                self._save()
+                return True
+            return False
+
+    def update_commit(self, ext_id: str, new_commit: str) -> None:
+        """更新扩展的 commit hash，用于 update 子命令"""
+        with self._lock:
+            if ext_id in self._items:
+                self._items[ext_id].commit = new_commit
+                self._save()
+
+
+def create_default_registry() -> ExtensionRegistry:
+    """创建指向 ~/.abyss/registry.json 的默认注册表"""
+    return ExtensionRegistry(registry_path=Path.home() / ".abyss" / "registry.json")

abyss/extensions/url_parser.py

@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+"""
+包源 URL 解析器
+解析用户在 install/update 子命令中提供的 URL，提取 git clone 地址、子目录、ref。
+
+支持的 URL 格式：
+  https://github.com/user/repo
+  https://github.com/user/repo.git
+  https://github.com/user/repo?subdir=skills/python-test
+  https://github.com/user/repo?subdir=skills/py&ref=v1.0
+  https://github.com/user/repo/tree/main/skills/python-test
+  git@github.com:user/repo.git
+"""
+import re
+from dataclasses import dataclass
+from urllib.parse import urlparse, parse_qs
+
+
+# GitHub tree 路径格式：/tree/<ref>/<subpath>（可在 path 任意位置）
+_GH_TREE_RE = re.compile(r"/tree/([^/]+)(?:/(.*))?$")
+
+
+@dataclass
+class PackageSource:
+    """解析后的包来源信息。"""
+    clone_url: str
+    subpath: str = ""
+    ref: str = "HEAD"
+
+    def __repr__(self):
+        return f"PackageSource({self.clone_url}, subpath={self.subpath!r}, ref={self.ref!r})"
+
+
+def parse_source_url(url: str) -> PackageSource:
+    """解析用户输入的源 URL，返回 PackageSource。无法识别时抛 ValueError。
+
+    参数：
+        url: 用户输入的 URL 或 SSH 路径
+
+    返回：
+        PackageSource(克隆地址, 子目录, ref)
+    """
+    url = url.strip()
+    if not url:
+        raise ValueError("URL 不能为空")
+
+    # SSH 形式：git@host:user/repo.git
+    if url.startswith("git@") and ":" in url:
+        return PackageSource(clone_url=url)
+
+    # 必须含 scheme
+    if not re.match(r"^[a-zA-Z][a-zA-Z0-9+.\-]*://", url):
+        raise ValueError(f"无法识别的 URL 格式: {url}")
+
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https", "git", "ssh"):
+        raise ValueError(f"不支持的协议: {parsed.scheme}")
+
+    # 提取 ?query
+    subpath_q = ""
+    ref = "HEAD"
+    if parsed.query:
+        qs = parse_qs(parsed.query)
+        if "subdir" in qs and qs["subdir"]:
+            subpath_q = qs["subdir"][0]
+        if "ref" in qs and qs["ref"]:
+            ref = qs["ref"][0]
+
+    # 解析 /tree/<ref>/<subpath>，在 path 任意位置匹配
+    subpath_tree = ""
+    tree_match = _GH_TREE_RE.search(parsed.path)
+    if tree_match:
+        ref = tree_match.group(1)
+        subpath_tree = (tree_match.group(2) or "").strip("/")
+        # 截掉 /tree/<ref>/<subpath> 及其前面的 /
+        base_path = parsed.path[: tree_match.start()].rstrip("/")
+    else:
+        base_path = parsed.path.rstrip("/")
+
+    subpath = (subpath_q or subpath_tree).strip("/")
+
+    clone_url = f"{parsed.scheme}://{parsed.netloc}{base_path}"
+    if not clone_url.endswith(".git"):
+        clone_url += ".git"
+
+    return PackageSource(clone_url=clone_url, subpath=subpath, ref=ref)

abyss/hooks/__init__.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""
+Hooks 模块
+提供生命周期事件钩子机制（PreToolUse/PostToolUse/PreLLMRequest 等）
+"""
+from .runner import HookRunner, HookResult, create_default_runner
+
+__all__ = [
+    "HookRunner",
+    "HookResult",
+    "create_default_runner",
+]

abyss/hooks/runner.py

@@ -0,0 +1,144 @@
+# -*- coding: utf-8 -*-
+"""
+Hook Runner 模块
+在 Agent 生命周期的特定节点（PreToolUse/PostToolUse/PreLLMRequest 等）
+自动触发用户配置的可执行脚本。
+
+目录结构：
+  hooks_dir/
+    PreToolUse/
+      01_validate.bat   # Windows
+      01_validate.sh    # Unix
+    PostToolUse/
+      log.bat
+
+环境变量传递：context 字典中的每个 key 会以 ABYSS_<KEY_UPPER> 形式注入子进程。
+Pre* 事件中钩子退出码非 0 视为阻断信号（block=True）。
+"""
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+# 可执行的脚本扩展名（按平台）
+_WIN_EXTS = {".bat", ".cmd", ".ps1"}
+_UNIX_EXTS = {".sh", ".bash", ".py", ""}
+
+
+@dataclass
+class HookResult:
+    """单个钩子执行结果。"""
+    name: str
+    success: bool
+    block: bool
+    stdout: str
+    stderr: str
+    returncode: int
+
+
+class HookRunner:
+    """从目录加载并执行生命周期事件钩子。"""
+
+    def __init__(self, hooks_dir: Optional[Path] = None):
+        self._hooks_dir = hooks_dir
+        # 事件名 -> 钩子脚本路径列表（按文件名排序）
+        self._hooks: Dict[str, List[Path]] = {}
+        if hooks_dir is not None:
+            self._load_from_dir(hooks_dir)
+
+    def _load_from_dir(self, hooks_dir: Path) -> None:
+        """扫描 hooks_dir/<event>/ 下的可执行脚本"""
+        if not hooks_dir.exists() or not hooks_dir.is_dir():
+            return
+        for event_dir in hooks_dir.iterdir():
+            if not event_dir.is_dir():
+                continue
+            event_name = event_dir.name
+            scripts = []
+            for f in event_dir.iterdir():
+                if not f.is_file():
+                    continue
+                if not self._is_executable(f):
+                    continue
+                scripts.append(f)
+            scripts.sort(key=lambda p: p.name)
+            self._hooks[event_name] = scripts
+
+    @staticmethod
+    def _is_executable(path: Path) -> bool:
+        """判断文件是否为可执行脚本（按平台扩展名过滤）"""
+        ext = path.suffix.lower()
+        if sys.platform.startswith("win"):
+            return ext in _WIN_EXTS
+        return ext in _UNIX_EXTS or os.access(path, os.X_OK)
+
+    def list_hooks(self, event: str) -> List[Path]:
+        """返回指定事件的所有钩子脚本路径"""
+        return list(self._hooks.get(event, []))
+
+    def run(self, event: str, context: Dict[str, str]) -> List[HookResult]:
+        """执行指定事件的所有钩子，按文件名排序依次运行。
+        context 中的键值会以 ABYSS_<KEY_UPPER> 注入子进程环境变量。
+        返回每个钩子的执行结果。
+        """
+        results = []
+        for script in self._hooks.get(event, []):
+            result = self._run_script(script, context)
+            results.append(result)
+            # Pre* 事件中阻断后不再执行后续钩子
+            if result.block and event.startswith("Pre"):
+                break
+        return results
+
+    @staticmethod
+    def _run_script(script: Path, context: Dict[str, str]) -> HookResult:
+        """执行单个钩子脚本"""
+        env = os.environ.copy()
+        for key, value in context.items():
+            env_key = f"ABYSS_{key.upper()}"
+            env[env_key] = str(value)
+
+        try:
+            if sys.platform.startswith("win"):
+                # Windows 用 cmd 执行 .bat/.cmd
+                proc = subprocess.run(
+                    ["cmd", "/c", str(script)],
+                    capture_output=True, text=True,
+                    env=env, timeout=30, encoding="utf-8", errors="replace"
+                )
+            else:
+                proc = subprocess.run(
+                    [str(script)],
+                    capture_output=True, text=True,
+                    env=env, timeout=30, encoding="utf-8", errors="replace"
+                )
+            returncode = proc.returncode
+            stdout = proc.stdout or ""
+            stderr = proc.stderr or ""
+        except subprocess.TimeoutExpired:
+            return HookResult(
+                name=script.name, success=False, block=False,
+                stdout="", stderr="timeout after 30s", returncode=-1
+            )
+        except Exception as e:
+            return HookResult(
+                name=script.name, success=False, block=False,
+                stdout="", stderr=str(e), returncode=-1
+            )
+
+        return HookResult(
+            name=script.name,
+            success=(returncode == 0),
+            block=(returncode != 0),
+            stdout=stdout,
+            stderr=stderr,
+            returncode=returncode,
+        )
+
+
+def create_default_runner() -> HookRunner:
+    """创建指向 ~/.abyss/hooks/ 的默认 HookRunner"""
+    return HookRunner(hooks_dir=Path.home() / ".abyss" / "hooks")

abyss/logger.py

@@ -0,0 +1,218 @@
+# -*- coding: utf-8 -*-
+"""
+事件日志系统
+记录 abyss CLI 所有关键事件，包括 API 调用、工具执行、错误、卡顿等。
+日志存储在 ~/.abyss/logs/ 下，按天轮转，保留最近 30 天。
+格式: ISO时间 | 类别 | 事件 | 详情
+"""
+import os
+import json
+import time
+import threading
+import glob as _glob
+from datetime import datetime, timedelta
+from pathlib import Path
+
+LOG_DIR = Path.home() / ".abyss" / "logs"
+LOG_RETENTION_DAYS = 30
+MAX_PAYLOAD_LEN = 2000
+
+
+class EventLogger:
+    """线程安全的事件日志记录器。每日自动轮转，自动清理过期日志。"""
+
+    def __init__(self):
+        LOG_DIR.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+        self._date = None
+        self._file = None
+
+    def _rotate_if_needed(self):
+        today = datetime.now().strftime("%Y-%m-%d")
+        if self._date == today and self._file:
+            return
+        if self._file:
+            self._file.close()
+        self._date = today
+        log_path = LOG_DIR / f"abyss_{today}.log"
+        self._file = open(str(log_path), "a", encoding="utf-8", buffering=1)
+        self._cleanup_old()
+
+    def _cleanup_old(self):
+        cutoff = datetime.now() - timedelta(days=LOG_RETENTION_DAYS)
+        for fp in _glob.glob(str(LOG_DIR / "abyss_*.log")):
+            try:
+                fname = os.path.basename(fp)
+                date_part = fname.replace("abyss_", "").replace(".log", "")
+                if datetime.strptime(date_part, "%Y-%m-%d") < cutoff:
+                    os.remove(fp)
+            except (ValueError, OSError):
+                pass
+
+    def _write(self, category: str, event: str, payload: str):
+        self._rotate_if_needed()
+        ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S.") + f"{int(time.time() * 1000) % 1000:03d}"
+        line = f"{ts} | {category:11s} | {event:24s} | {payload}\n"
+        with self._lock:
+            self._file.write(line)
+            self._file.flush()
+
+    def _fmt(self, **kwargs) -> str:
+        parts = []
+        for k, v in kwargs.items():
+            if isinstance(v, str) and len(v) > MAX_PAYLOAD_LEN:
+                v = v[:MAX_PAYLOAD_LEN] + f"...[{len(v)}]"
+            elif isinstance(v, (dict, list)):
+                v = json.dumps(v, ensure_ascii=False, default=str)
+                if len(v) > MAX_PAYLOAD_LEN:
+                    v = v[:MAX_PAYLOAD_LEN] + f"...[{len(v)}]"
+            parts.append(f"{k}={v}")
+        return " ".join(parts)
+
+    def session_start(self, **kwargs):
+        self._write("SESSION", "start", self._fmt(**kwargs))
+
+    def session_end(self, reason=""):
+        self._write("SESSION", "end", f"reason={reason}" if reason else "reason=normal")
+
+    def user_input(self, text: str):
+        self._write("USER_INPUT", "", f"text={text!r}")
+
+    def slash_command(self, cmd: str):
+        self._write("SLASH_CMD", "", f"cmd={cmd}")
+
+    def api_request(self, **kwargs):
+        self._write("API", "request_start", self._fmt(**kwargs))
+
+    def api_first_token(self, latency_ms: int):
+        self._write("API", "first_token", f"latency_ms={latency_ms}")
+
+    def api_response(self, **kwargs):
+        self._write("API", "response", self._fmt(**kwargs))
+
+    def api_error(self, error: str):
+        self._write("API", "error", f"error={error!r}")
+
+    def api_retry(self, attempt: int, wait_s: float, reason: str):
+        self._write("API", "retry", f"attempt={attempt} wait_s={wait_s:.2f} reason={reason}")
+
+    def tool_start(self, name: str, **kwargs):
+        self._write("TOOL", "start", self._fmt(name=name, **kwargs))
+
+    def tool_end(self, name: str, success: bool, duration_ms: int, **kwargs):
+        self._write("TOOL", "end", self._fmt(name=name, success=success, duration_ms=duration_ms, **kwargs))
+
+    def spinner_start(self, message: str):
+        self._write("SPINNER", "start", f"message={message}")
+
+    def spinner_stop(self, message: str = ""):
+        self._write("SPINNER", "stop", f"message={message}" if message else "")
+
+    def batch_header(self, round_num: int, total: int, max_rounds: int):
+        self._write("BATCH", "header", f"round={round_num} total={total} max={max_rounds}")
+
+    def stream_content_start(self):
+        self._write("STREAM", "content_start", "")
+
+    def stream_reasoning_start(self):
+        self._write("STREAM", "reasoning_start", "")
+
+    def keyboard_interrupt(self):
+        self._write("SIGNAL", "keyboard_interrupt", "")
+
+    def eof(self):
+        self._write("SIGNAL", "eof", "")
+
+    def error(self, message: str, exc_info: str = ""):
+        payload = f"message={message!r}"
+        if exc_info:
+            payload += f" traceback={exc_info!r}"
+        self._write("ERROR", "", payload)
+
+    def flush(self):
+        if self._file:
+            with self._lock:
+                self._file.flush()
+
+
+_logger = EventLogger()
+
+
+def get_logger() -> EventLogger:
+    return _logger
+
+
+def session_start(**kwargs):
+    _logger.session_start(**kwargs)
+
+
+def session_end(reason=""):
+    _logger.session_end(reason)
+
+
+def user_input(text: str):
+    _logger.user_input(text)
+
+
+def slash_command(cmd: str):
+    _logger.slash_command(cmd)
+
+
+def api_request(**kwargs):
+    _logger.api_request(**kwargs)
+
+
+def api_first_token(latency_ms: int):
+    _logger.api_first_token(latency_ms)
+
+
+def api_response(**kwargs):
+    _logger.api_response(**kwargs)
+
+
+def api_error(error: str):
+    _logger.api_error(error)
+
+
+def api_retry(attempt: int, wait_s: float, reason: str):
+    _logger.api_retry(attempt, wait_s, reason)
+
+
+def tool_start(name: str, **kwargs):
+    _logger.tool_start(name, **kwargs)
+
+
+def tool_end(name: str, success: bool, duration_ms: int, **kwargs):
+    _logger.tool_end(name, success, duration_ms, **kwargs)
+
+
+def spinner_start(message: str):
+    _logger.spinner_start(message)
+
+
+def spinner_stop(message: str = ""):
+    _logger.spinner_stop(message)
+
+
+def batch_header(round_num: int, total: int, max_rounds: int):
+    _logger.batch_header(round_num, total, max_rounds)
+
+
+def stream_content_start():
+    _logger.stream_content_start()
+
+
+def stream_reasoning_start():
+    _logger.stream_reasoning_start()
+
+
+def keyboard_interrupt():
+    _logger.keyboard_interrupt()
+
+
+def eof():
+    _logger.eof()
+
+
+def error(message: str, exc_info: str = ""):
+    _logger.error(message, exc_info)