llmrix-skill 0.2.0__py3-none-any.whl

llmrix/skill/__init__.py

@@ -0,0 +1,70 @@
+"""
+llmrix.skill — Git-backed Skill management library.
+
+Package layout:
+  core/      Cross-cutting concerns (config, exceptions, utils)
+  models/    Domain models and data schemas
+  git/       Low-level Git repository driver
+  storage/   Abstract storage interface + concrete adapters
+  services/  High-level orchestration (sync, publish, manage)
+"""
+# --- Core ---
+from .core.config import SkillConfig
+from .core.exceptions import (
+    GitSkillError,
+    SkillNotFoundError,
+    VersionNotFoundError,
+    PermissionDeniedError,
+    ValidationError,
+    GitOperationError,
+)
+from .core.utils import build_file_tree
+from .core.plugin import BaseSkill
+
+# --- Models ---
+from .models.schema import Skill, SkillVersion
+from .models.metadata import MetadataParser
+
+# --- Git ---
+from .git.repository import GitRepository
+
+# --- Storage ---
+from .storage.base import BaseStorage
+from .storage.mysql import MySQLStorage
+from .storage.sqlalchemy_store import SQLAlchemyStorage
+
+# --- Services ---
+from .services.manager import GitSkillManager
+from .services.publisher import SkillPublisher
+from .services.syncer import SkillSyncer, RemoteSource, SyncResult
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # Core
+    "SkillConfig",
+    "GitSkillError",
+    "SkillNotFoundError",
+    "VersionNotFoundError",
+    "PermissionDeniedError",
+    "ValidationError",
+    "GitOperationError",
+    "build_file_tree",
+    "BaseSkill",
+    # Models
+    "Skill",
+    "SkillVersion",
+    "MetadataParser",
+    # Git
+    "GitRepository",
+    # Storage
+    "BaseStorage",
+    "MySQLStorage",
+    "SQLAlchemyStorage",
+    # Services
+    "GitSkillManager",
+    "SkillPublisher",
+    "SkillSyncer",
+    "RemoteSource",
+    "SyncResult",
+]

llmrix/skill/core/__init__.py

@@ -0,0 +1,26 @@
+"""
+core: Cross-cutting concerns — configuration, exceptions, and utilities.
+"""
+from .config import SkillConfig
+from .exceptions import (
+    GitSkillError,
+    SkillNotFoundError,
+    VersionNotFoundError,
+    PermissionDeniedError,
+    ValidationError,
+    GitOperationError,
+)
+from .utils import build_file_tree
+from .plugin import BaseSkill
+
+__all__ = [
+    "SkillConfig",
+    "GitSkillError",
+    "SkillNotFoundError",
+    "VersionNotFoundError",
+    "PermissionDeniedError",
+    "ValidationError",
+    "GitOperationError",
+    "build_file_tree",
+    "BaseSkill",
+]

llmrix/skill/core/config.py

@@ -0,0 +1,36 @@
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+@dataclass
+class SkillConfig:
+    """Configuration for the Skill management system."""
+    repo_url: str
+    workspace: str
+    branch: str = "main"
+    skills_path: str = "skills"
+    cache_ttl: int = 300
+
+    @classmethod
+    def create(
+        cls, 
+        repo_url: str, 
+        workspace: Optional[str] = None, 
+        branch: str = "main"
+    ) -> "SkillConfig":
+        if not workspace:
+            workspace = os.path.expanduser("~/llmrix/skills/remote")
+        
+        return cls(
+            repo_url=repo_url,
+            workspace=os.path.abspath(os.path.expanduser(workspace)),
+            branch=branch
+        )
+
+    @property
+    def cache_root(self) -> str:
+        return os.path.dirname(self.workspace)
+
+    @property
+    def skills_root(self) -> str:
+        return os.path.join(self.workspace, self.skills_path)

llmrix/skill/core/exceptions.py

@@ -0,0 +1,23 @@
+class GitSkillError(Exception):
+    """Base exception for gitskill library"""
+    pass
+
+class SkillNotFoundError(GitSkillError):
+    """Raised when a skill is not found in storage"""
+    pass
+
+class VersionNotFoundError(GitSkillError):
+    """Raised when a specific version of a skill is not found"""
+    pass
+
+class PermissionDeniedError(GitSkillError):
+    """Raised when a user lacks permission to modify a skill"""
+    pass
+
+class ValidationError(GitSkillError):
+    """Raised when skill metadata or code is invalid"""
+    pass
+
+class GitOperationError(GitSkillError):
+    """Raised when a git command fails"""
+    pass

llmrix/skill/core/plugin.py

@@ -0,0 +1,31 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+class BaseSkill(ABC):
+    """
+    Standard interface contract for LLMRix skills.
+    
+    Plugin developers should inherit from this class in their `main.py` 
+    to ensure seamless integration with the host Agent framework.
+    """
+    
+    @property
+    def name(self) -> str:
+        """The identifier name of the skill."""
+        return self.__class__.__name__
+
+    @abstractmethod
+    async def execute(self, **kwargs: Any) -> Any:
+        """
+        The main execution entry point for the skill.
+        All core business logic and external API calls should be implemented here.
+        """
+        pass
+        
+    def setup(self, context: Dict[str, Any]) -> None:
+        """
+        Optional initialization hook.
+        The Agent framework can pass configuration, credentials, or runtime context 
+        here before the skill is executed.
+        """
+        pass

llmrix/skill/core/utils.py

@@ -0,0 +1,38 @@
+import os
+from typing import Any, Dict, List
+
+def build_file_tree(base_dir: str, rel_prefix: str = "") -> List[Dict[str, Any]]:
+    """
+    Recursively builds a nested file tree (directories first, sorted by name).
+    Returns structure:
+      [
+        {"name": "scripts", "path": "scripts", "type": "dir", "children": [...]},
+        {"name": "SKILL.md", "path": "SKILL.md", "type": "file", "size": 1024},
+      ]
+    """
+    items: List[Dict[str, Any]] = []
+    try:
+        entries = sorted(os.scandir(base_dir), key=lambda e: (e.is_file(), e.name))
+    except PermissionError:
+        return items
+
+    for entry in entries:
+        if entry.name.startswith("."):
+            continue
+        rel_path = f"{rel_prefix}{entry.name}" if rel_prefix else entry.name
+        if entry.is_dir(follow_symlinks=False):
+            children = build_file_tree(entry.path, rel_path + "/")
+            items.append({
+                "name":     entry.name,
+                "path":     rel_path,
+                "type":     "dir",
+                "children": children,
+            })
+        else:
+            items.append({
+                "name": entry.name,
+                "path": rel_path,
+                "type": "file",
+                "size": entry.stat().st_size,
+            })
+    return items

llmrix/skill/git/__init__.py

@@ -0,0 +1,6 @@
+"""
+git: Low-level Git repository driver.
+"""
+from .repository import GitRepository
+
+__all__ = ["GitRepository"]

llmrix/skill/git/repository.py

@@ -0,0 +1,109 @@
+import logging
+import os
+import subprocess
+from contextlib import contextmanager
+from typing import Any, Generator, List, Optional
+from llmrix.skill.core.exceptions import GitOperationError
+
+logger = logging.getLogger(__name__)
+
+class GitRepository:
+    """
+    Handles low-level Git operations for skills.
+    Focuses on repository maintenance, state transitions, and file management.
+    """
+    
+    def __init__(self, root: str, sub_dir: str = "skills"):
+        self.root = os.path.abspath(root)
+        self.sub_dir = sub_dir
+        self._lock_dir = os.path.join(self.root, ".locks")
+
+    def get_skill_path(self, code: str) -> str:
+        """Returns absolute path to a skill directory."""
+        return os.path.join(self.root, self.sub_dir, code)
+
+    def get_relative_path(self, code: str) -> str:
+        """Returns relative path to a skill from repo root."""
+        return f"{self.sub_dir}/{code}"
+
+    @contextmanager
+    def lock(self, code: str, timeout: int = 30) -> Generator[None, None, None]:
+        """Provides a distributed file lock for a specific skill code."""
+        try:
+            from filelock import FileLock
+            os.makedirs(self._lock_dir, exist_ok=True)
+            lock = FileLock(os.path.join(self._lock_dir, f"{code}.lock"), timeout=timeout)
+            with lock:
+                yield
+        except ImportError:
+            logger.warning("filelock not installed, running without concurrency protection")
+            yield
+
+    def _execute(self, command: List[str]) -> str:
+        """Executes a git command and returns the output."""
+        try:
+            result = subprocess.run(
+                ["git"] + command,
+                cwd=self.root,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                check=True
+            )
+            return result.stdout.strip()
+        except subprocess.CalledProcessError as e:
+            error_msg = (e.stdout + "\\n" + e.stderr).strip()
+            raise GitOperationError(f"Git command {' '.join(command)} failed: {error_msg}") from e
+
+    def ensure_initialized(self, remote_url: Optional[str] = None, branch: str = "main"):
+        """Ensures the repository is initialized and tracking the correct branch."""
+        if not os.path.isdir(os.path.join(self.root, ".git")):
+            if remote_url:
+                logger.info(f"Cloning skill repository from {remote_url} (branch: {branch})")
+                os.makedirs(os.path.dirname(self.root), exist_ok=True)
+                subprocess.run(["git", "clone", "--branch", branch, remote_url, self.root], check=True)
+            else:
+                logger.info(f"Initializing local skill repository (branch: {branch})")
+                os.makedirs(self.root, exist_ok=True)
+                self._execute(["init", "-b", branch])
+        
+        # Ensure skills directory exists
+        os.makedirs(os.path.join(self.root, self.sub_dir), exist_ok=True)
+
+    def fetch_latest(self, remote: str = "origin", branch: str = "main"):
+        """Pulls the latest changes from the remote repository."""
+        try:
+            self._execute(["pull", remote, branch])
+        except GitOperationError as e:
+            logger.warning(f"Git pull failed, falling back to local state: {e}")
+
+    def push_changes(self, remote: str = "origin", branch: str = "main"):
+        """Pushes local commits to the remote repository."""
+        try:
+            self._execute(["push", remote, branch])
+        except GitOperationError as e:
+            logger.warning(f"Git push failed: {e}")
+
+    def commit_skill(self, code: str, author_id: Any, message: Optional[str] = None) -> str:
+        """Adds and commits changes for a specific skill."""
+        rel_path = self.get_relative_path(code)
+        self._execute(["add", rel_path])
+        
+        # Check for staged changes
+        diff = self._execute(["diff", "--cached", "--name-only"])
+        if not diff:
+            return self._execute(["rev-parse", "HEAD"])
+            
+        msg = message or f"Update skill: {code} by user: {author_id}"
+        self._execute(["commit", "-m", msg])
+        return self._execute(["rev-parse", "HEAD"])
+
+    def revert_to_commit(self, code: str, commit_hash: str, author_id: Any, message: Optional[str] = None) -> str:
+        """Checkouts a specific commit for a skill and commits the reversal."""
+        rel_path = self.get_relative_path(code)
+        self._execute(["checkout", commit_hash, "--", rel_path])
+        self._execute(["add", rel_path])
+        
+        msg = message or f"Revert skill: {code} to {commit_hash} by user: {author_id}"
+        self._execute(["commit", "-m", msg])
+        return self._execute(["rev-parse", "HEAD"])

llmrix/skill/models/__init__.py

@@ -0,0 +1,7 @@
+"""
+models: Domain models and data schemas.
+"""
+from .schema import Skill, SkillVersion
+from .metadata import MetadataParser
+
+__all__ = ["Skill", "SkillVersion", "MetadataParser"]

llmrix/skill/models/metadata.py

@@ -0,0 +1,46 @@
+import yaml
+import re
+from typing import Any, Dict, Optional
+from llmrix.skill.core.exceptions import ValidationError
+
+class MetadataParser:
+    """Parses skill files and validates codes."""
+
+    @staticmethod
+    def parse_manifest(content: str) -> Dict[str, Any]:
+        """Extracts frontmatter from SKILL.md."""
+        if not content.startswith("---"):
+            return {}
+        try:
+            match = re.match(r"^---\s*\\n(.*?)\\n---\s*\\n", content, re.DOTALL)
+            if match:
+                return yaml.safe_load(match.group(1)) or {}
+        except Exception as e:
+            raise ValidationError(f"Failed to parse metadata frontmatter: {e}") from e
+        return {}
+
+    @staticmethod
+    def validate_code(code: str) -> None:
+        """Ensures skill code follows naming conventions."""
+        if not (code and re.match(r"^[a-z0-9_\\-]+$", code)):
+            raise ValidationError(
+                f"Invalid skill code '{code}'. Only lowercase, numbers, - and _ are allowed."
+            )
+
+    @staticmethod
+    def detect_category(code: str, name: str, description: str) -> str:
+        """Heuristically detects skill category based on keywords."""
+        text = " ".join([code, name or "", description or ""]).lower()
+        
+        KEYWORDS = [
+            ("Developer Tools", ["git", "code", "python", "javascript", "typescript", "compiler", "debug", "ide", "sdk", "api"]),
+            ("Data Analytics", ["data", "sql", "database", "excel", "csv", "chart", "analytics", "bi", "统计", "数据", "分析"]),
+            ("Content Creation", ["image", "photo", "video", "audio", "canvas", "design", "content", "图片", "图像", "设计"]),
+            ("Web & Search", ["search", "web", "browser", "crawl", "scrape", "http", "url", "搜索", "网页"]),
+            ("System Integration", ["shell", "bash", "deploy", "docker", "k8s", "ci", "cd", "monitor", "email", "notify", "自动化", "集成"]),
+        ]
+
+        for category, keywords in KEYWORDS:
+            if any(kw in text for kw in keywords):
+                return category
+        return "Other"

llmrix/skill/models/schema.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+@dataclass
+class Skill:
+    """Represents the current state of a skill."""
+    code: str
+    name: str
+    version: int = 1
+    description: Optional[str] = None
+    category: str = "Other"
+    commit_hash: Optional[str] = None
+    file_path: Optional[str] = None
+    status: int = 0
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+@dataclass
+class SkillVersion:
+    """Represents a specific point-in-time version of a skill."""
+    code: str
+    version: int
+    commit_hash: str
+    author_id: Any
+    file_path: Optional[str] = None
+    message: Optional[str] = None
+    created_at: datetime = field(default_factory=datetime.now)

llmrix/skill/services/__init__.py

@@ -0,0 +1,14 @@
+"""
+services: High-level business logic — sync, publish, and orchestration.
+"""
+from .manager import GitSkillManager
+from .publisher import SkillPublisher
+from .syncer import SkillSyncer, RemoteSource, SyncResult
+
+__all__ = [
+    "GitSkillManager",
+    "SkillPublisher",
+    "SkillSyncer",
+    "RemoteSource",
+    "SyncResult",
+]

llmrix/skill/services/manager.py

@@ -0,0 +1,98 @@
+import os
+import logging
+from typing import Any, Optional, List
+from llmrix.skill.git.repository import GitRepository
+from llmrix.skill.storage.base import BaseStorage
+from llmrix.skill.models.metadata import MetadataParser
+from llmrix.skill.services.syncer import SkillSyncer
+from llmrix.skill.services.publisher import SkillPublisher
+from llmrix.skill.core.config import SkillConfig
+from llmrix.skill.models.schema import Skill, SkillVersion
+from llmrix.skill.core.exceptions import GitSkillError
+
+logger = logging.getLogger(__name__)
+
+class GitSkillManager:
+    """
+    Converged Orchestrator for SkillHub.
+    
+    Acts as a high-level facade that decouples configuration from method calls,
+    providing a clean interface for both Agent Workers and Management APIs.
+    """
+
+    def __init__(
+        self, 
+        repo_url: str, 
+        workspace: Optional[str] = None, 
+        branch: str = "main",
+        storage: Optional[BaseStorage] = None
+    ):
+        # 1. Decouple Configuration
+        self.config = SkillConfig.create(repo_url, workspace, branch)
+        self.storage = storage
+        
+        # 2. Initialize Internal Components
+        self.repository = GitRepository(root=self.config.workspace, sub_dir=self.config.skills_path)
+        self.parser = MetadataParser()
+        
+        # 3. Read Responsibility (Syncing)
+        self.syncer = SkillSyncer(cache_dir=self.config.cache_root)
+        
+        # 4. Write Responsibility (Publishing - Lazy)
+        self._publisher = None
+        if storage:
+            self._publisher = SkillPublisher(
+                git=self.repository, 
+                storage=storage, 
+                parser=self.parser,
+                default_branch=self.config.branch
+            )
+
+    @property
+    def publisher(self) -> SkillPublisher:
+        if not self._publisher:
+            raise GitSkillError("Storage adapter is required for publishing operations.")
+        return self._publisher
+
+    def sync(self) -> str:
+        """
+        Worker Mode API: Synchronizes the local repository.
+        Uses the pre-configured branch and workspace.
+        """
+        self.repository.ensure_initialized(
+            remote_url=self.config.repo_url, 
+            branch=self.config.branch
+        )
+        self.repository.fetch_latest(branch=self.config.branch)
+        return self.repository.get_skill_path("")
+
+    def publish(self, **kwargs) -> Skill:
+        """
+        Management Mode API: Deploys a new version.
+        Arguments like 'branch' are optional as the manager uses defaults.
+        """
+        self.repository.ensure_initialized(
+            remote_url=self.config.repo_url, 
+            branch=self.config.branch
+        )
+        return self.publisher.publish(**kwargs)
+
+    def rollback(self, **kwargs) -> Skill:
+        """Management Mode API: Reverts to a previous version."""
+        self.repository.ensure_initialized(
+            remote_url=self.config.repo_url, 
+            branch=self.config.branch
+        )
+        return self.publisher.rollback(**kwargs)
+
+    def get_history(self, code: str) -> List[SkillVersion]:
+        """Retrieves release history from the connected database."""
+        if not self.storage:
+            raise GitSkillError("Storage adapter is required for history queries.")
+        return self.storage.get_history(code)
+
+    @staticmethod
+    def get_interim_path(uid: Any) -> str:
+        """Static utility to resolve a standardized interim upload path for users."""
+        base = os.path.expanduser(f"~/llmrix/skills/interim/{uid}")
+        return os.path.abspath(base)

llmrix/skill/services/publisher.py

@@ -0,0 +1,151 @@
+import os
+import shutil
+import logging
+from typing import Any, Optional
+from llmrix.skill.git.repository import GitRepository
+from llmrix.skill.storage.base import BaseStorage
+from llmrix.skill.models.metadata import MetadataParser
+from llmrix.skill.models.schema import Skill, SkillVersion
+from llmrix.skill.core.exceptions import PermissionDeniedError, VersionNotFoundError
+
+logger = logging.getLogger(__name__)
+
+class SkillPublisher:
+    """
+    Handles the deployment lifecycle of Skills.
+    Encapsulates permissions, filesystem updates, and persistence.
+    """
+
+    def __init__(
+        self, 
+        git: GitRepository, 
+        storage: BaseStorage,
+        parser: Optional[MetadataParser] = None,
+        default_branch: str = "main"
+    ):
+        self.git = git
+        self.storage = storage
+        self.parser = parser or MetadataParser()
+        self.default_branch = default_branch
+
+    def publish(
+        self,
+        code: str,
+        source_dir: str,
+        user_id: Any,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        category: Optional[str] = None,
+        message: Optional[str] = None,
+        branch: Optional[str] = None
+    ) -> Skill:
+        """Executes a full deployment workflow for a skill."""
+        target_branch = branch or self.default_branch
+        self.parser.validate_code(code)
+
+        with self.git.lock(code):
+            self.git.fetch_latest(branch=target_branch)
+
+            # 1. Authorization
+            existing = self.storage.get_skill(code)
+            if existing and not self.storage.can_modify(code, user_id):
+                raise PermissionDeniedError(f"User {user_id} lacks permission for skill {code}")
+
+            # 2. Filesystem Update
+            target_path = self.git.get_skill_path(code)
+            if os.path.exists(target_path):
+                shutil.rmtree(target_path)
+            shutil.copytree(source_dir, target_path)
+
+            # 3. Metadata Extraction
+            manifest_path = os.path.join(target_path, "SKILL.md")
+            manifest = {}
+            if os.path.exists(manifest_path):
+                with open(manifest_path, "r", encoding="utf-8") as f:
+                    manifest = self.parser.parse_manifest(f.read())
+
+            final_name = name or manifest.get("name") or code
+            final_desc = description or manifest.get("description")
+            final_cat = (
+                category 
+                or manifest.get("category") 
+                or self.parser.detect_category(code, final_name, final_desc or "")
+            )
+
+            # 4. Git Orchestration
+            commit_hash = self.git.commit_skill(code, user_id, message)
+            self.git.push_changes(branch=target_branch)
+
+            # 5. Database Persistence
+            new_version_num = (existing.version + 1) if existing else 1
+            skill = Skill(
+                code=code,
+                name=final_name,
+                version=new_version_num,
+                description=final_desc,
+                category=final_cat,
+                commit_hash=commit_hash,
+                file_path=self.git.get_relative_path(code),
+                status=0
+            )
+            
+            self.storage.save_skill(skill)
+            self.storage.add_version(SkillVersion(
+                code=code,
+                version=new_version_num,
+                commit_hash=commit_hash,
+                author_id=user_id,
+                file_path=skill.file_path,
+                message=message
+            ))
+
+            return skill
+
+    def rollback(
+        self,
+        code: str,
+        target_version: int,
+        user_id: Any,
+        message: Optional[str] = None,
+        branch: Optional[str] = None
+    ) -> Skill:
+        """Rolls back a skill to a specific historical version."""
+        target_branch = branch or self.default_branch
+        ver = self.storage.get_version(code, target_version)
+        if not ver:
+            raise VersionNotFoundError(f"Version {target_version} not found for {code}")
+
+        with self.git.lock(code):
+            self.git.fetch_latest(branch=target_branch)
+            
+            if not self.storage.can_modify(code, user_id):
+                 raise PermissionDeniedError(f"Access denied for skill {code}")
+
+            new_hash = self.git.revert_to_commit(code, ver.commit_hash, user_id, message)
+            self.git.push_changes(branch=target_branch)
+
+            existing = self.storage.get_skill(code)
+            new_version_num = (existing.version + 1) if existing else 1
+            
+            skill = Skill(
+                code=code,
+                name=existing.name,
+                version=new_version_num,
+                description=existing.description,
+                category=existing.category,
+                commit_hash=new_hash,
+                file_path=existing.file_path,
+                status=existing.status
+            )
+            
+            self.storage.save_skill(skill)
+            self.storage.add_version(SkillVersion(
+                code=code,
+                version=new_version_num,
+                commit_hash=new_hash,
+                author_id=user_id,
+                file_path=skill.file_path,
+                message=message or f"Rollback to v{target_version}"
+            ))
+            
+            return skill

llmrix/skill/services/syncer.py

@@ -0,0 +1,121 @@
+import asyncio
+import hashlib
+import logging
+import os
+import shutil
+import urllib.parse
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from llmrix.skill.git.repository import GitRepository
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class RemoteSource:
+    """Configuration for a remote skill repository source."""
+    url: str
+    branch: str = "main"
+    ssh_key: Optional[str] = None
+    username: Optional[str] = None
+    password: Optional[str] = None
+    cache_ttl: int = 300  # seconds
+    skills_path: str = "skills"
+
+    @property
+    def identity(self) -> str:
+        """Unique identifier based on URL and branch."""
+        return f"{self.url}:{self.branch}"
+
+@dataclass
+class SyncResult:
+    """Result of a repository sync operation."""
+    source: RemoteSource
+    local_path: Path
+    success: bool
+    last_sync: datetime
+    error: Optional[str] = None
+
+class SkillSyncer:
+    """
+    Manages synchronization of multiple remote skill repositories.
+    Supports local caching with TTL and authentication.
+    """
+
+    def __init__(self, cache_dir: str):
+        self.cache_dir = Path(cache_dir).absolute()
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self._locks: Dict[str, asyncio.Lock] = {}
+        self._sync_history: Dict[str, datetime] = {}
+
+    def _get_lock(self, identity: str) -> asyncio.Lock:
+        if identity not in self._locks:
+            self._locks[identity] = asyncio.Lock()
+        return self._locks[identity]
+
+    def _get_cache_path(self, source: RemoteSource) -> Path:
+        """Generates a unique directory name for the repository hash."""
+        url_hash = hashlib.md5(source.identity.encode()).hexdigest()[:12]
+        return self.cache_dir / f"repo_{url_hash}"
+
+    def _build_authed_url(self, source: RemoteSource) -> str:
+        url = source.url
+        if source.username and source.password and url.startswith("https://"):
+            encoded_user = urllib.parse.quote(source.username, safe="")
+            encoded_pass = urllib.parse.quote(source.password, safe="")
+            url = url.replace("https://", f"https://{encoded_user}:{encoded_pass}@")
+        return url
+
+    async def sync_source(self, source: RemoteSource) -> SyncResult:
+        """
+        Synchronizes a single remote source. 
+        Returns the path to the skills directory within the repo.
+        """
+        identity = source.identity
+        lock = self._get_lock(identity)
+        
+        async with lock:
+            repo_path = self._get_cache_path(source)
+            repo = GitRepository(root=str(repo_path), sub_dir=source.skills_path)
+            
+            # Check TTL
+            last_sync = self._sync_history.get(identity)
+            if last_sync and (datetime.now() - last_sync).total_seconds() < source.cache_ttl:
+                if repo_path.exists():
+                    return SyncResult(source, Path(repo.get_skill_path("")), True, last_sync)
+
+            try:
+                authed_url = self._build_authed_url(source)
+                
+                # We use a thread pool for blocking git operations since they are subprocess calls
+                loop = asyncio.get_event_loop()
+                
+                if not repo_path.exists():
+                    logger.info(f"Cloning remote skill source: {source.url}")
+                    await loop.run_in_executor(None, repo.initialize, authed_url, source.branch)
+                else:
+                    logger.debug(f"Syncing remote skill source: {source.url}")
+                    await loop.run_in_executor(None, repo.sync, "origin", source.branch)
+
+                self._sync_history[identity] = datetime.now()
+                return SyncResult(source, Path(repo.get_skill_path("")), True, self._sync_history[identity])
+
+            except Exception as e:
+                logger.error(f"Failed to sync {source.url}: {e}")
+                if repo_path.exists():
+                    logger.warning(f"Falling back to stale cache for {source.url}")
+                    return SyncResult(source, Path(repo.get_skill_path("")), True, last_sync or datetime.min, str(e))
+                return SyncResult(source, repo_path, False, datetime.min, str(e))
+
+    async def sync_all(self, sources: List[RemoteSource]) -> List[SyncResult]:
+        """Synchronizes multiple sources in parallel."""
+        tasks = [self.sync_source(s) for s in sources]
+        return await asyncio.gather(*tasks)
+
+    def clear_cache(self):
+        """Deletes all cached repositories."""
+        if self.cache_dir.exists():
+            shutil.rmtree(self.cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self._sync_history.clear()

llmrix/skill/storage/__init__.py

@@ -0,0 +1,8 @@
+"""
+storage: Abstract storage interface and concrete adapter implementations.
+"""
+from .base import BaseStorage
+from .mysql import MySQLStorage
+from .sqlalchemy_store import SQLAlchemyStorage
+
+__all__ = ["BaseStorage", "MySQLStorage", "SQLAlchemyStorage"]

llmrix/skill/storage/base.py

@@ -0,0 +1,39 @@
+from abc import ABC, abstractmethod
+from typing import Any, List, Optional
+from llmrix.skill.models.schema import Skill, SkillVersion
+
+class BaseStorage(ABC):
+    """
+    Abstract base class for skill persistence.
+    Implement this to support different databases.
+    """
+
+    @abstractmethod
+    def get_skill(self, code: str) -> Optional[Skill]:
+        """Retrieve skill by its unique code."""
+        pass
+
+    @abstractmethod
+    def save_skill(self, skill: Skill) -> None:
+        """Create or update skill metadata."""
+        pass
+
+    @abstractmethod
+    def add_version(self, version: SkillVersion) -> None:
+        """Record a new version in history."""
+        pass
+
+    @abstractmethod
+    def get_history(self, code: str) -> List[SkillVersion]:
+        """List all versions of a skill ordered by version descending."""
+        pass
+
+    @abstractmethod
+    def get_version(self, code: str, version_number: int) -> Optional[SkillVersion]:
+        """Retrieve a specific version record."""
+        pass
+
+    @abstractmethod
+    def can_modify(self, code: str, user_id: Any) -> bool:
+        """Check if the user has permission to modify the skill."""
+        pass

llmrix/skill/storage/mysql.py

@@ -0,0 +1,100 @@
+from typing import Any, List, Optional
+from llmrix.skill.storage.base import BaseStorage
+from llmrix.skill.models.schema import Skill, SkillVersion
+
+class MySQLStorage(BaseStorage):
+    def __init__(self, connection_factory):
+        self.get_conn = connection_factory
+
+    def _to_skill(self, row: dict) -> Skill:
+        return Skill(
+            code=row["skill_code"],
+            name=row["skill_name"],
+            version=row["version"],
+            description=row["introduce"],
+            category=row["category"],
+            commit_hash=row["git_commit"],
+            file_path=row["git_path"],
+            status=row["status"]
+        )
+
+    def get_skill(self, code: str) -> Optional[Skill]:
+        with self.get_conn() as conn:
+            cur = conn.cursor()
+            cur.execute("SELECT * FROM skill_info WHERE skill_code=%s AND deleted=0", (code,))
+            row = cur.fetchone()
+            return self._to_skill(row) if row else None
+
+    def save_skill(self, skill: Skill) -> None:
+        sql = """
+            INSERT INTO skill_info (skill_code, skill_name, introduce, version, git_commit, git_path, status, category)
+            VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
+            ON DUPLICATE KEY UPDATE
+                skill_name  = VALUES(skill_name),
+                introduce   = VALUES(introduce),
+                version     = VALUES(version),
+                git_commit  = VALUES(git_commit),
+                git_path    = VALUES(git_path),
+                category    = VALUES(category),
+                update_time = NOW()
+        """
+        with self.get_conn() as conn:
+            cur = conn.cursor()
+            cur.execute(sql, (
+                skill.code, skill.name, skill.description,
+                skill.version, skill.commit_hash, skill.file_path,
+                skill.status, skill.category
+            ))
+            conn.commit()
+
+    def add_version(self, version: SkillVersion) -> None:
+        sql = """
+            INSERT INTO skill_version (skill_code, version, git_commit, git_path, user_id, remark)
+            VALUES (%s, %s, %s, %s, %s, %s)
+        """
+        with self.get_conn() as conn:
+            cur = conn.cursor()
+            cur.execute(sql, (
+                version.code, version.version, version.commit_hash,
+                version.file_path, version.author_id, version.message
+            ))
+            conn.commit()
+
+    def get_history(self, code: str) -> List[SkillVersion]:
+        with self.get_conn() as conn:
+            cur = conn.cursor()
+            cur.execute("SELECT * FROM skill_version WHERE skill_code=%s AND deleted=0 ORDER BY version DESC", (code,))
+            rows = cur.fetchall()
+            return [SkillVersion(
+                code=r["skill_code"],
+                version=r["version"],
+                commit_hash=r["git_commit"],
+                author_id=r["user_id"],
+                file_path=r["git_path"],
+                message=r["remark"],
+                created_at=r["create_time"]
+            ) for r in rows]
+
+    def get_version(self, code: str, version_number: int) -> Optional[SkillVersion]:
+        with self.get_conn() as conn:
+            cur = conn.cursor()
+            cur.execute("SELECT * FROM skill_version WHERE skill_code=%s AND version=%s AND deleted=0", 
+                        (code, version_number))
+            r = cur.fetchone()
+            if not r: return None
+            return SkillVersion(
+                code=r["skill_code"],
+                version=r["version"],
+                commit_hash=r["git_commit"],
+                author_id=r["user_id"],
+                file_path=r["git_path"],
+                message=r["remark"],
+                created_at=r["create_time"]
+            )
+
+    def can_modify(self, code: str, user_id: Any) -> bool:
+        with self.get_conn() as conn:
+            cur = conn.cursor()
+            cur.execute("SELECT id FROM skill_info WHERE skill_code=%s AND user_id=%s AND deleted=0",
+                        (code, user_id))
+            return cur.fetchone() is not None

llmrix/skill/storage/sqlalchemy_store.py

@@ -0,0 +1,144 @@
+from typing import Any, List, Optional
+from sqlalchemy import create_engine, Column, Integer, String, Text, DateTime
+from sqlalchemy.orm import declarative_base, sessionmaker
+from datetime import datetime
+
+from llmrix.skill.storage.base import BaseStorage
+from llmrix.skill.models.schema import Skill, SkillVersion
+
+Base = declarative_base()
+
+class SkillModel(Base):
+    __tablename__ = "skill_info"
+    
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    skill_code = Column(String(100), unique=True, nullable=False, index=True)
+    skill_name = Column(String(200), nullable=False)
+    introduce = Column(Text, nullable=True) # Description
+    category = Column(String(100), nullable=True)
+    version = Column(Integer, default=1)
+    git_commit = Column(String(40), nullable=False)
+    git_path = Column(String(500), nullable=False)
+    status = Column(Integer, default=0)
+    user_id = Column(String(100), nullable=True) # Author/Owner
+    deleted = Column(Integer, default=0)
+    create_time = Column(DateTime, default=datetime.utcnow)
+    update_time = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+class SkillVersionModel(Base):
+    __tablename__ = "skill_version"
+    
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    skill_code = Column(String(100), nullable=False, index=True)
+    version = Column(Integer, nullable=False)
+    git_commit = Column(String(40), nullable=False)
+    git_path = Column(String(500), nullable=False)
+    user_id = Column(String(100), nullable=False)
+    remark = Column(Text, nullable=True)
+    deleted = Column(Integer, default=0)
+    create_time = Column(DateTime, default=datetime.utcnow)
+
+class SQLAlchemyStorage(BaseStorage):
+    """
+    Database agnostic storage using SQLAlchemy ORM.
+    Supports MySQL, PostgreSQL, SQLite, etc.
+    """
+    def __init__(self, engine_or_url: Any, auto_create_tables: bool = True):
+        if isinstance(engine_or_url, str):
+            self.engine = create_engine(engine_or_url)
+        else:
+            self.engine = engine_or_url
+            
+        self.SessionLocal = sessionmaker(bind=self.engine)
+        
+        if auto_create_tables:
+            Base.metadata.create_all(self.engine)
+
+    def _to_skill(self, model: SkillModel) -> Skill:
+        return Skill(
+            code=model.skill_code,
+            name=model.skill_name,
+            version=model.version,
+            description=model.introduce,
+            category=model.category,
+            commit_hash=model.git_commit,
+            file_path=model.git_path,
+            status=model.status
+        )
+
+    def get_skill(self, code: str) -> Optional[Skill]:
+        with self.SessionLocal() as db:
+            model = db.query(SkillModel).filter_by(skill_code=code, deleted=0).first()
+            return self._to_skill(model) if model else None
+
+    def save_skill(self, skill: Skill) -> None:
+        with self.SessionLocal() as db:
+            model = db.query(SkillModel).filter_by(skill_code=skill.code, deleted=0).first()
+            if model:
+                model.skill_name = skill.name
+                model.introduce = skill.description
+                model.version = skill.version
+                model.git_commit = skill.commit_hash
+                model.git_path = skill.file_path
+                model.status = skill.status
+                model.category = skill.category
+            else:
+                model = SkillModel(
+                    skill_code=skill.code,
+                    skill_name=skill.name,
+                    introduce=skill.description,
+                    version=skill.version,
+                    git_commit=skill.commit_hash,
+                    git_path=skill.file_path,
+                    status=skill.status,
+                    category=skill.category
+                )
+                db.add(model)
+            db.commit()
+
+    def add_version(self, version: SkillVersion) -> None:
+        with self.SessionLocal() as db:
+            model = SkillVersionModel(
+                skill_code=version.code,
+                version=version.version,
+                git_commit=version.commit_hash,
+                git_path=version.file_path,
+                user_id=str(version.author_id),
+                remark=version.message
+            )
+            db.add(model)
+            db.commit()
+
+    def get_history(self, code: str) -> List[SkillVersion]:
+        with self.SessionLocal() as db:
+            models = db.query(SkillVersionModel).filter_by(skill_code=code, deleted=0).order_by(SkillVersionModel.version.desc()).all()
+            return [
+                SkillVersion(
+                    code=m.skill_code,
+                    version=m.version,
+                    commit_hash=m.git_commit,
+                    author_id=m.user_id,
+                    file_path=m.git_path,
+                    message=m.remark,
+                    created_at=m.create_time
+                ) for m in models
+            ]
+
+    def get_version(self, code: str, version_number: int) -> Optional[SkillVersion]:
+        with self.SessionLocal() as db:
+            m = db.query(SkillVersionModel).filter_by(skill_code=code, version=version_number, deleted=0).first()
+            if not m: return None
+            return SkillVersion(
+                code=m.skill_code,
+                version=m.version,
+                commit_hash=m.git_commit,
+                author_id=m.user_id,
+                file_path=m.git_path,
+                message=m.remark,
+                created_at=m.create_time
+            )
+
+    def can_modify(self, code: str, user_id: Any) -> bool:
+        with self.SessionLocal() as db:
+            model = db.query(SkillModel).filter_by(skill_code=code, user_id=str(user_id), deleted=0).first()
+            return model is not None

llmrix_skill-0.2.0.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: llmrix-skill
+Version: 0.2.0
+Summary: A professional Git-based Skill management library for LLM agents.
+Author-email: LLMRix Team <support@llmrix.com>
+License: MIT
+Project-URL: Homepage, https://github.com/llmrix/llmrix-skillhub
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: filelock>=3.0.0
+Requires-Dist: sqlalchemy>=2.0.0
+
+# LLMRix Skill Plugin Library
+
+`llmrix-skill` is a professional Git-based Skill and plugin management framework designed for LLM Agents. It encapsulates the complex logic of publishing, versioning, and syncing code, prompts, and tools into an out-of-the-box plugin library, allowing developers to focus on building core Agent logic.
+
+## Core Features
+
+As the foundational plugin library for an Agent framework, it provides the following capabilities:
+
+- **Git-Driven Plugin Market**: Uses Git repositories as the Single Source of Truth (SSOT) to achieve skill persistence, version tracing, and change tracking.
+- **Out-of-the-box Dual Mode Architecture**:
+  - **Worker Mode (Execution)**: Pure lightweight synchronization, responsible for pulling skills from remote repositories to local storage for high-speed loading by Agent instances.
+  - **Management Mode (Admin)**: Integrates with databases to support multi-tenant authentication, skill publishing, metadata parsing, and version rollbacks.
+- **Dynamic Metadata Parsing**: Automatically parses and validates `SKILL.md` (YAML Frontmatter) in the skill package to extract the plugin name, description, and category.
+- **Concurrency & Safety**: Built-in distributed file lock mechanism to prevent file state race conditions during high-concurrency publishing and pulling.
+
+---
+
+## Quick Usage Guide
+
+### Installation
+
+You can integrate this plugin library into your Agent project via pip:
+
+```bash
+pip install llmrix-skill
+```
+
+### Scene 1: Syncing Plugins on Agent Execution Node (Worker Mode)
+
+In your Agent execution environment (such as background task nodes, or upon container startup), configure a specific branch to pull the latest skills for model invocation.
+
+```python
+from llmrix.skill import GitSkillManager
+
+def sync_skills_for_agent():
+    # Initialize the Manager, configuring the remote repository and target branch
+    manager = GitSkillManager(
+        repo_url="https://github.com/your-org/skill-repo.git",
+        branch="develop",                # Highly recommended: specify the branch to pull (e.g., main/develop/v1)
+        workspace="/path/to/local/cache" # Local cache path
+    )
+
+    # Execute sync, returning the absolute filesystem path where the skills are located
+    skills_path = manager.sync()
+    print(f"✅ Skill plugins synced to: {skills_path}")
+    
+    # You can now dynamically load modules under skills_path in your Agent framework
+```
+
+### Scene 2: Web Server Management & Publishing (Management Mode)
+
+In your Web API service (such as FastAPI/Django plugin market backend), use `GitSkillManager` to handle user uploads, publishing, and version rollbacks. It encapsulates database persistence and concurrent file locking.
+
+```python
+from llmrix.skill import GitSkillManager
+from llmrix.skill import MySQLStorage
+
+# 1. Configure the database adapter
+def get_db_connection():
+    # Return a pymysql/MySQLdb connection object
+    pass
+
+storage = MySQLStorage(connection_factory=get_db_connection)
+
+# 2. Initialize the Manager, dedicated for the management end
+manager = GitSkillManager(
+    repo_url="git@github.com:your-org/skill-repo.git",
+    storage=storage
+)
+
+# 3. Publish user-uploaded skills
+def publish_user_skill(user_id, uploaded_dir):
+    skill = manager.publish(
+        code="python_interpreter",      # Unique skill code
+        source_dir=uploaded_dir,        # Unzipped directory uploaded by the user
+        user_id=user_id,                # Current operating user ID (for auth)
+        message="Initial release"       
+    )
+    print(f"🚀 Publish successful: {skill.name} v{skill.version}")
+
+# 4. Version Rollback
+def rollback_skill(user_id):
+    skill = manager.rollback(
+        code="python_interpreter",
+        target_version=1,
+        user_id=user_id,
+        message="Revert due to bugs"
+    )
+```
+
+---
+
+## Skill Package Specification
+
+A standard skill plugin package is a directory containing the following files:
+
+```text
+my_awesome_skill/
+├── SKILL.md      # Skill description and metadata (Required)
+├── main.py       # Core logic (Recommended)
+└── requirements.txt # Dependencies (Optional)
+```
+
+`SKILL.md` must contain a valid YAML Frontmatter header:
+
+```markdown
+---
+name: Web Scraper Pro
+description: Powerful web scraping tool, supports dynamic rendering.
+category: Web & Search
+---
+
+Detailed Markdown documentation about this skill goes here...
+```
+
+---
+
+## Module Architecture
+
+You can directly import the required submodules for lower-level extensions:
+
+- `llmrix.skill.services`: Contains `GitSkillManager`, `SkillPublisher`, and `SkillSyncer`.
+- `llmrix.skill.storage`: Contains `BaseStorage` and `MySQLStorage`. Inherit `BaseStorage` to implement your own MongoDB or PostgreSQL adapters.
+- `llmrix.skill.git`: Low-level Git driver library `GitRepository`.
+- `llmrix.skill.models`: Data models `Skill` and `SkillVersion`.

llmrix_skill-0.2.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+llmrix/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+llmrix/skill/__init__.py,sha256=2bTh79cvfDE6YJOutPbG6FwR1VD2LUulXV9ehq9fr1s,1707
+llmrix/skill/core/__init__.py,sha256=9ugCN6KmPJLWdEeAx7OV_vdPSAUXRw1ownLaOvCSf3w,574
+llmrix/skill/core/config.py,sha256=gdS5hZQ7AT_Fu7oVgDgQOF8DKbmTToreALCTdGbLlEE,913
+llmrix/skill/core/exceptions.py,sha256=gVTrBNw0vo1FwE8B05i8fGcfCKlI7i3FFEyzi2d2dw4,624
+llmrix/skill/core/plugin.py,sha256=y2yB4dHumRML9dvLthb_S9w-ItsfthfsK7A6DWKmSkQ,944
+llmrix/skill/core/utils.py,sha256=Jn_Azb_LEzDMkb0PQnoaGMUzr-CnsDWmJLfhhnJsRzU,1296
+llmrix/skill/git/__init__.py,sha256=nB06TtVJV5-HPlQ1GwSEBOH793KNyf9npn-QSJuZyUU,113
+llmrix/skill/git/repository.py,sha256=UaD1LmHSOITO-TImjCoET6p1cl0NwAG22P_2IDnGHVE,4748
+llmrix/skill/models/__init__.py,sha256=HowL3n_j1ecwRpRj8Q72zpYFWKIolIpocGtyZ3JQCsA,180
+llmrix/skill/models/metadata.py,sha256=6F3pCZflZ-bOVwTBqya1Rz1HpPUfrorh4gjzYwuGbEs,2101
+llmrix/skill/models/schema.py,sha256=Eaa29jwH7_Eu0FqzQQaDXOZ0NLs_04PCtMRp3_qDX5A,756
+llmrix/skill/services/__init__.py,sha256=4Qu266WVFvqkIfnUMXLoa6gcjA2Uil_kRQKiSBc6PMk,332
+llmrix/skill/services/manager.py,sha256=VucU_M781BYINSn5n5r_47RTJCZJXZTA-tSzFHcAUGc,3592
+llmrix/skill/services/publisher.py,sha256=Sx43RaoOS2orx_sVXRM4QmnEZixZnAyPdTmctB_sy1k,5357
+llmrix/skill/services/syncer.py,sha256=fJvyiqRCRJZsyhwnSQjKDPDlAa3bPk7ECHgkhzw_DNo,4765
+llmrix/skill/storage/__init__.py,sha256=wsx-Tj003rFOQMSKUjeXz-brGYNyCe0k8CJqYkT8_Qc,256
+llmrix/skill/storage/base.py,sha256=smIIDR6hQtpfpD0GWAWjjC_SVutuNO7uTShkjGU4VAo,1177
+llmrix/skill/storage/mysql.py,sha256=V1Xc9HgfSzAv-XKOr8LygMZN9MHqj4Cf_O9TVIOIt-s,4054
+llmrix/skill/storage/sqlalchemy_store.py,sha256=9MmZu4KfuZch-U8j9-fov--1pcoclhFFK--IpH0QYp8,5796
+llmrix_skill-0.2.0.dist-info/METADATA,sha256=8B-yX0Iw-qr2wUMHVI_M5EOm9Ay3K61euVsnVX_d3Gc,5289
+llmrix_skill-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+llmrix_skill-0.2.0.dist-info/top_level.txt,sha256=TAjGcnZd2kd6XpS1jGciyU_vDj6rQyhDqHmOfJVW1fw,7
+llmrix_skill-0.2.0.dist-info/RECORD,,

llmrix_skill-0.2.0.dist-info/WHEEL

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

llmrix_skill-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+llmrix