skilllite 0.1.0__py3-none-any.whl

skilllite/core/metadata.py

@@ -0,0 +1,338 @@
+"""
+Skill metadata parsing from SKILL.md files.
+
+This is a CORE module - do not modify without explicit permission.
+
+Follows the official Claude Agent Skills specification:
+https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/specification
+
+Network access and language are derived from the 'compatibility' field.
+Entry point is auto-detected from scripts/ directory.
+"""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+@dataclass
+class NetworkPolicy:
+    """Network access policy for a skill (derived from compatibility field)."""
+    enabled: bool = False
+    outbound: List[str] = field(default_factory=list)
+
+@dataclass
+class SkillMetadata:
+    """Skill metadata parsed from SKILL.md YAML front matter."""
+    name: str
+    entry_point: str
+    language: Optional[str] = None
+    description: Optional[str] = None
+    version: Optional[str] = None
+    compatibility: Optional[str] = None
+    network: NetworkPolicy = field(default_factory=NetworkPolicy)
+    input_schema: Optional[Dict[str, Any]] = None
+    output_schema: Optional[Dict[str, Any]] = None
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any], skill_dir: Optional[Path] = None) -> "SkillMetadata":
+        """Create SkillMetadata from parsed YAML front matter."""
+        version = data.get("version")
+        if not version and "metadata" in data:
+            version = data["metadata"].get("version")
+        
+        compatibility = data.get("compatibility")
+        
+        # Parse network policy from compatibility field
+        network = parse_compatibility_for_network(compatibility)
+        
+        # Auto-detect entry point
+        entry_point = ""
+        if skill_dir:
+            detected = detect_entry_point(skill_dir)
+            if detected:
+                entry_point = detected
+        
+        # Detect language from compatibility or entry point
+        language = parse_compatibility_for_language(compatibility)
+        if not language and entry_point:
+            language = detect_language_from_entry_point(entry_point)
+        
+        return cls(
+            name=data.get("name", ""),
+            entry_point=entry_point,
+            language=language,
+            description=data.get("description"),
+            version=version,
+            compatibility=compatibility,
+            network=network,
+            input_schema=data.get("input_schema"),
+            output_schema=data.get("output_schema")
+        )
+
+
+def parse_compatibility_for_network(compatibility: Optional[str]) -> NetworkPolicy:
+    """
+    Parse compatibility string to extract network policy.
+    
+    Examples:
+        - "Requires network access" -> enabled=True
+        - "Requires Python 3.x, internet" -> enabled=True
+        - "Requires git, docker" -> enabled=False
+    """
+    if not compatibility:
+        return NetworkPolicy()
+    
+    compat_lower = compatibility.lower()
+    
+    # Check for network/internet keywords
+    needs_network = any(keyword in compat_lower for keyword in [
+        "network", "internet", "http", "api", "web"
+    ])
+    
+    if needs_network:
+        return NetworkPolicy(
+            enabled=True,
+            outbound=["*:80", "*:443"]  # Allow all HTTP/HTTPS by default
+        )
+    
+    return NetworkPolicy()
+
+
+def parse_compatibility_for_language(compatibility: Optional[str]) -> Optional[str]:
+    """
+    Parse compatibility string to detect language.
+    
+    Examples:
+        - "Requires Python 3.x" -> "python"
+        - "Requires Node.js" -> "node"
+        - "Requires bash" -> "bash"
+    """
+    if not compatibility:
+        return None
+    
+    compat_lower = compatibility.lower()
+    
+    if "python" in compat_lower:
+        return "python"
+    elif "node" in compat_lower or "javascript" in compat_lower or "typescript" in compat_lower:
+        return "node"
+    elif "bash" in compat_lower or "shell" in compat_lower:
+        return "bash"
+    
+    return None
+
+
+def detect_language_from_entry_point(entry_point: str) -> Optional[str]:
+    """Detect language from entry point file extension."""
+    if entry_point.endswith(".py"):
+        return "python"
+    elif entry_point.endswith(".js") or entry_point.endswith(".ts"):
+        return "node"
+    elif entry_point.endswith(".sh"):
+        return "bash"
+    return None
+
+def detect_entry_point(skill_dir: Path) -> Optional[str]:
+    """
+    Auto-detect entry point from skill directory.
+    
+    Detection strategy (in order of priority):
+    1. Look for main.* files (main.py, main.js, main.ts, main.sh)
+    2. Look for index.* files (common in Node.js projects)
+    3. Look for run.* or entry.* files
+    4. If only one script file exists, use it as entry point
+    5. If multiple scripts exist, return None (requires explicit config or LLM inference)
+    
+    Returns:
+        Relative path to entry point (e.g., "scripts/main.py"), or None if not detected
+    """
+    scripts_dir = skill_dir / "scripts"
+    if not scripts_dir.exists():
+        return None
+    
+    supported_extensions = [".py", ".js", ".ts", ".sh"]
+    
+    # Priority 1: Look for main.* files
+    for ext in supported_extensions:
+        main_file = scripts_dir / f"main{ext}"
+        if main_file.exists():
+            return f"scripts/main{ext}"
+    
+    # Priority 2: Look for index.* files (common in Node.js)
+    for ext in supported_extensions:
+        index_file = scripts_dir / f"index{ext}"
+        if index_file.exists():
+            return f"scripts/index{ext}"
+    
+    # Priority 3: Look for run.* or entry.* files
+    for prefix in ["run", "entry", "app", "cli"]:
+        for ext in supported_extensions:
+            candidate = scripts_dir / f"{prefix}{ext}"
+            if candidate.exists():
+                return f"scripts/{prefix}{ext}"
+    
+    # Priority 4: If only one script file exists, use it
+    script_files = []
+    for ext in supported_extensions:
+        script_files.extend(scripts_dir.glob(f"*{ext}"))
+    
+    # Filter out test files and __init__.py
+    script_files = [
+        f for f in script_files 
+        if not f.name.startswith("test_") 
+        and not f.name.endswith("_test.py")
+        and f.name != "__init__.py"
+        and not f.name.startswith(".")
+    ]
+    
+    if len(script_files) == 1:
+        return f"scripts/{script_files[0].name}"
+    
+    # Multiple scripts or no scripts found - return None
+    # This will be handled by LLM inference or explicit configuration
+    return None
+
+def detect_all_scripts(skill_dir: Path) -> List[Dict[str, str]]:
+    """
+    Detect all executable scripts in a skill directory.
+    
+    This is useful for skills with multiple entry points (like skill-creator
+    which has init_skill.py, package_skill.py, etc.)
+    
+    Returns:
+        List of dicts with 'name', 'path', and 'language' for each script
+    """
+    scripts_dir = skill_dir / "scripts"
+    if not scripts_dir.exists():
+        return []
+    
+    extension_to_language = {
+        ".py": "python",
+        ".js": "node",
+        ".ts": "node",
+        ".sh": "bash",
+    }
+    
+    scripts = []
+    for ext, lang in extension_to_language.items():
+        for script_file in scripts_dir.glob(f"*{ext}"):
+            # Skip test files and __init__.py
+            if (script_file.name.startswith("test_") 
+                or script_file.name.endswith("_test.py")
+                or script_file.name == "__init__.py"
+                or script_file.name.startswith(".")):
+                continue
+            
+            # Generate a tool name from the script filename
+            tool_name = script_file.stem.replace("_", "-")
+            
+            scripts.append({
+                "name": tool_name,
+                "path": f"scripts/{script_file.name}",
+                "language": lang,
+                "filename": script_file.name,
+            })
+    
+    return scripts
+
+def detect_language(skill_dir: Path, metadata: Optional[SkillMetadata] = None) -> str:
+    """
+    Detect the programming language of a skill.
+    
+    Args:
+        skill_dir: Path to the skill directory
+        metadata: Optional metadata object (may contain language info)
+        
+    Returns:
+        Language string (e.g., "python", "node", "bash")
+    """
+    # First check metadata
+    if metadata and metadata.language:
+        return metadata.language
+    
+    # Check entry point extension
+    if metadata and metadata.entry_point:
+        entry_ext = Path(metadata.entry_point).suffix
+        ext_map = {".py": "python", ".js": "node", ".ts": "node", ".sh": "bash"}
+        if entry_ext in ext_map:
+            return ext_map[entry_ext]
+    
+    # Scan scripts directory
+    scripts_dir = skill_dir / "scripts"
+    if scripts_dir.exists():
+        for ext, lang in [(".py", "python"), (".js", "node"), (".ts", "node"), (".sh", "bash")]:
+            if any(scripts_dir.glob(f"*{ext}")):
+                return lang
+    
+    return "unknown"
+
+def extract_yaml_front_matter(content: str, skill_dir: Optional[Path] = None) -> SkillMetadata:
+    """
+    Extract YAML front matter from markdown content.
+    
+    Args:
+        content: Full markdown content
+        skill_dir: Optional skill directory path for auto-detection
+        
+    Returns:
+        SkillMetadata object
+    """
+    # Check for YAML front matter (between --- markers)
+    front_matter_match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+    
+    data = {}
+    if front_matter_match:
+        try:
+            data = yaml.safe_load(front_matter_match.group(1))
+            if not isinstance(data, dict):
+                data = {}
+        except yaml.YAMLError:
+            data = {}
+    
+    return SkillMetadata.from_dict(data, skill_dir)
+
+def parse_skill_metadata(skill_dir: Path) -> SkillMetadata:
+    """Parse SKILL.md file and extract metadata from YAML front matter."""
+    skill_md_path = skill_dir / "SKILL.md"
+    if not skill_md_path.exists():
+        raise FileNotFoundError(f"SKILL.md not found in directory: {skill_dir}")
+    content = skill_md_path.read_text(encoding="utf-8")
+    metadata = extract_yaml_front_matter(content, skill_dir)
+    
+    return metadata
+
+def get_skill_summary(content: str, max_length: int = 200) -> str:
+    """
+    Extract a concise summary from SKILL.md content.
+    
+    Removes YAML front matter, code blocks, and headers to extract
+    the main descriptive text.
+    
+    Args:
+        content: Full SKILL.md content
+        max_length: Maximum length of the summary
+        
+    Returns:
+        Extracted summary string
+    """
+    # Remove YAML front matter
+    content_clean = re.sub(r"^---\s*\n.*?\n---\s*\n", "", content, flags=re.DOTALL)
+    # Remove code blocks
+    content_clean = re.sub(r"```[\s\S]*?```", "", content_clean)
+    # Remove headers
+    content_clean = re.sub(r"^#+\s*", "", content_clean, flags=re.MULTILINE)
+    
+    lines = [line.strip() for line in content_clean.split("\n") if line.strip()]
+    summary_lines = []
+    current_length = 0
+    
+    for line in lines:
+        if current_length + len(line) > max_length:
+            break
+        summary_lines.append(line)
+        current_length += len(line) + 1
+    
+    return " ".join(summary_lines)[:max_length]

skilllite/core/prompt_builder.py

@@ -0,0 +1,321 @@
+"""
+Prompt Builder - System prompt context generation.
+
+This module handles:
+- Generating system prompt context for LLM
+- Formatting skill information for different modes
+- Skills status reporting and logging
+"""
+
+import json
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+from .skill_info import SkillInfo
+
+if TYPE_CHECKING:
+    from .registry import SkillRegistry
+
+
+class PromptBuilder:
+    """
+    Builder for generating system prompt context from skills.
+    
+    Supports multiple disclosure modes:
+    - summary: Brief overview of skills
+    - standard: Input schema and usage summary
+    - progressive: Summary with "more details available" hint
+    - full: Complete instructions and references
+    """
+    
+    def __init__(self, registry: "SkillRegistry"):
+        """
+        Initialize the prompt builder.
+        
+        Args:
+            registry: Skill registry for accessing skill info
+        """
+        self._registry = registry
+    
+    def get_system_prompt_context(
+        self,
+        include_full_instructions: bool = True,
+        include_references: bool = False,
+        include_assets: bool = False,
+        skills: Optional[List[str]] = None,
+        mode: str = "full",
+        max_tokens_per_skill: Optional[int] = None
+    ) -> str:
+        """
+        Generate system prompt context containing skill information.
+        
+        Args:
+            include_full_instructions: Include full instructions (affects mode)
+            include_references: Include reference documents
+            include_assets: Include asset files
+            skills: Specific skills to include (None = all)
+            mode: Disclosure mode (summary, standard, progressive, full)
+            max_tokens_per_skill: Max tokens per skill content
+            
+        Returns:
+            Formatted system prompt context string
+        """
+        if not include_full_instructions and mode == "full":
+            mode = "standard"
+        
+        lines = ["# Available Skills\n"]
+        target_skills = self._registry.list_skills()
+        if skills:
+            target_skills = [
+                info for info in self._registry.list_skills()
+                if info.name in skills
+            ]
+        
+        if mode == "progressive":
+            lines.append("\n> **Note**: Skill details are shown in summary mode.\n\n")
+        
+        for info in target_skills:
+            skill_lines = self._format_skill_context(
+                info,
+                mode=mode,
+                include_references=include_references,
+                include_assets=include_assets,
+                max_tokens=max_tokens_per_skill
+            )
+            lines.extend(skill_lines)
+            lines.append("\n---\n")
+        
+        return "\n".join(lines)
+    
+    def _format_skill_context(
+        self,
+        info: SkillInfo,
+        mode: str = "full",
+        include_references: bool = False,
+        include_assets: bool = False,
+        max_tokens: Optional[int] = None
+    ) -> List[str]:
+        """Format a single skill's context based on the disclosure mode."""
+        from ..parsing import get_skill_summary
+        
+        lines = [f"## {info.name}\n"]
+        if info.description:
+            lines.append(f"**Description:** {info.description}\n")
+        
+        if mode == "summary":
+            full_content = info.get_full_content()
+            if full_content:
+                summary = get_skill_summary(full_content, max_length=150)
+                if summary:
+                    lines.append(f"\n**Summary:** {summary}\n")
+        
+        elif mode == "standard":
+            if info.metadata.input_schema:
+                lines.append("\n**Input Schema:**\n")
+                schema_str = json.dumps(info.metadata.input_schema, indent=2, ensure_ascii=False)
+                lines.append(f"```json\n{schema_str}\n```\n")
+            full_content = info.get_full_content()
+            if full_content:
+                summary = get_skill_summary(full_content, max_length=200)
+                if summary:
+                    lines.append(f"\n**Usage:** {summary}\n")
+        
+        elif mode == "progressive":
+            if info.metadata.input_schema:
+                lines.append("\n**Input Schema:**\n")
+                schema_str = json.dumps(info.metadata.input_schema, indent=2, ensure_ascii=False)
+                lines.append(f"```json\n{schema_str}\n```\n")
+            full_content = info.get_full_content()
+            if full_content:
+                summary = get_skill_summary(full_content, max_length=150)
+                if summary:
+                    lines.append(f"\n**Summary:** {summary}\n")
+            has_more = bool(
+                info.get_references() or
+                info.get_assets() or
+                (full_content and len(full_content) > 300)
+            )
+            if has_more:
+                lines.append(f"\n> 💡 *More details available.*\n")
+        
+        else:  # full mode
+            full_content = info.get_full_content()
+            if full_content:
+                if max_tokens and len(full_content) > max_tokens * 4:
+                    full_content = full_content[:max_tokens * 4] + "\n\n... (truncated)"
+                lines.append("\n### Instructions\n")
+                lines.append(full_content)
+                lines.append("\n")
+        
+        # Include references for full/standard modes
+        if include_references and mode in ["full", "standard"]:
+            refs = info.get_references()
+            if refs:
+                lines.append("\n### Reference Documents\n")
+                for filename, content in refs.items():
+                    lines.append(f"\n#### {filename}\n")
+                    if max_tokens and len(content) > max_tokens * 2:
+                        content = content[:max_tokens * 2] + "\n... (truncated)"
+                    lines.append(content)
+                    lines.append("\n")
+        
+        # Include assets for full/standard modes
+        if include_assets and mode in ["full", "standard"]:
+            assets = info.get_assets()
+            if assets:
+                lines.append("\n### Assets\n")
+                for filename, content in assets.items():
+                    lines.append(f"\n#### {filename}\n")
+                    if isinstance(content, dict):
+                        content_str = json.dumps(content, indent=2, ensure_ascii=False)
+                        if max_tokens and len(content_str) > max_tokens * 2:
+                            content_str = content_str[:max_tokens * 2] + "\n... (truncated)"
+                        lines.append(f"```json\n{content_str}\n```\n")
+                    else:
+                        if max_tokens and len(str(content)) > max_tokens * 2:
+                            content = str(content)[:max_tokens * 2] + "\n... (truncated)"
+                        lines.append(f"```\n{content}\n```\n")
+        
+        return lines
+    
+    def get_skill_details(self, skill_name: str) -> Optional[str]:
+        """Get full details for a specific skill."""
+        info = self._registry.get_skill(skill_name)
+        if not info:
+            return None
+        lines = self._format_skill_context(
+            info,
+            mode="full",
+            include_references=True,
+            include_assets=True
+        )
+        return "\n".join(lines)
+    
+    def get_skills_summary(self) -> str:
+        """Get a compact summary of all available skills."""
+        return self.get_system_prompt_context(mode="summary")
+    
+    def estimate_context_tokens(
+        self,
+        mode: str = "full",
+        include_references: bool = False,
+        include_assets: bool = False
+    ) -> int:
+        """Estimate the number of tokens the system prompt context will use."""
+        context = self.get_system_prompt_context(
+            mode=mode,
+            include_references=include_references,
+            include_assets=include_assets
+        )
+        return len(context) // 4
+    
+    def get_skill_context(self, skill_name: str) -> Optional[Dict[str, Any]]:
+        """Get complete context for a specific skill."""
+        info = self._registry.get_skill(skill_name)
+        if not info:
+            return None
+        return info.get_context(include_references=True, include_assets=True)
+    
+    def get_all_skill_contexts(self) -> Dict[str, Dict[str, Any]]:
+        """Get complete context for all skills."""
+        return {
+            info.name: info.get_context(include_references=True, include_assets=True)
+            for info in self._registry.list_skills()
+        }
+    
+    # ==================== Skills Status & Logging ====================
+    
+    def get_skills_status(self) -> Dict[str, Any]:
+        """
+        Get structured status information about all loaded skills.
+        
+        Returns a dict with:
+        - all_skills: list of all skill names
+        - executable_tools: list of executable skill/tool names
+        - multi_script_tools: list of multi-script tool names
+        - prompt_only_guides: list of prompt-only skill names
+        - details: dict mapping skill name to its details
+        """
+        executable = self._registry.list_executable_skills()
+        prompt_only = self._registry.list_prompt_only_skills()
+        multi_script_tools = self._registry.list_multi_script_tools()
+        
+        # Build list of executable tool names
+        executable_tool_names = []
+        for info in executable:
+            if info.metadata.entry_point:
+                executable_tool_names.append(info.name)
+        executable_tool_names.extend(multi_script_tools)
+        
+        details = {}
+        for info in self._registry.list_skills():
+            refs = info.get_references()
+            assets = info.get_assets()
+            scripts = info.get_all_scripts()
+            
+            is_multi_script = info.name in [
+                t["skill_name"] for t in self._registry.multi_script_tools.values()
+            ]
+            
+            details[info.name] = {
+                "description": info.description,
+                "is_executable": bool(info.metadata.entry_point) or is_multi_script,
+                "is_multi_script": is_multi_script,
+                "has_references": bool(refs),
+                "has_assets": bool(assets),
+                "references": list(refs.keys()) if refs else [],
+                "assets": list(assets.keys()) if assets else [],
+                "scripts": [s["name"] for s in scripts] if scripts else [],
+            }
+        
+        return {
+            "all_skills": self._registry.skill_names(),
+            "executable_tools": executable_tool_names,
+            "multi_script_tools": multi_script_tools,
+            "prompt_only_guides": [s.name for s in prompt_only],
+            "details": details,
+        }
+    
+    def print_skills_status(self, verbose: bool = False) -> None:
+        """Print a formatted status of all loaded skills."""
+        status = self.get_skills_status()
+        
+        print(f"📦 已加载 Skills: {status['all_skills']}")
+        
+        if status["executable_tools"]:
+            print(f"   🔧 可调用工具 (Tools): {status['executable_tools']}")
+        
+        if status["multi_script_tools"]:
+            print(f"   🔨 多脚本工具 (Multi-script): {status['multi_script_tools']}")
+        
+        if status["prompt_only_guides"]:
+            print(f"   📝 参考指南 (Prompt-only): {status['prompt_only_guides']}")
+        
+        if verbose:
+            for name, detail in status["details"].items():
+                extras = []
+                if detail["has_references"]:
+                    extras.append(f"refs={detail['references']}")
+                if detail["has_assets"]:
+                    extras.append(f"assets={detail['assets']}")
+                if extras:
+                    print(f"   📄 {name}: {', '.join(extras)}")
+                if detail["description"]:
+                    skill_type = "Tool" if detail["is_executable"] else "Guide"
+                    print(f"      └─ [{skill_type}] {detail['description']}")
+    
+    def get_prompt_only_status(self) -> List[Dict[str, str]]:
+        """Get status info for prompt-only skills."""
+        return [
+            {"name": s.name, "description": s.description or ""}
+            for s in self._registry.list_prompt_only_skills()
+        ]
+    
+    def print_prompt_only_status(self) -> None:
+        """Print status of prompt-only skills."""
+        prompt_only = self.get_prompt_only_status()
+        if prompt_only:
+            names = [s["name"] for s in prompt_only]
+            print(f"📝 已注入参考指南 (Prompt-only Skills): {names}")
+            for s in prompt_only:
+                if s["description"]:
+                    print(f"   └─ {s['name']}: {s['description']}")