monoco-toolkit 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

monoco/core/resources/zh/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: monoco-core
+description: Monoco Toolkit 的核心技能。提供项目初始化、配置管理和工作空间管理的基础命令。
+---
+
+# Monoco 核心
+
+Monoco Toolkit 的核心功能和命令。
+
+## 概述
+
+Monoco 是一个开发者生产力工具包，提供：
+
+- **项目初始化**：标准化的项目结构
+- **配置管理**：全局和项目级别的配置
+- **工作空间管理**：多项目设置
+
+## 核心命令
+
+### 项目设置
+
+- **`monoco init`**: 初始化新的 Monoco 项目
+  - 创建 `.monoco/` 目录及默认配置
+  - 设置项目结构（Issues/, .references/ 等）
+  - 生成初始文档
+
+### 配置管理
+
+- **`monoco config`**: 管理配置
+  - `monoco config get <key>`: 查看配置值
+  - `monoco config set <key> <value>`: 更新配置
+  - 支持全局（`~/.monoco/config.yaml`）和项目（`.monoco/config.yaml`）作用域
+
+### Agent 集成
+
+- **`monoco sync`**: 与 agent 环境同步
+
+  - 将系统提示注入到 agent 配置文件（GEMINI.md, CLAUDE.md 等）
+  - 分发 skills 到 agent 框架目录
+  - 遵循 `i18n.source_lang` 的语言配置
+
+- **`monoco uninstall`**: 清理 agent 集成
+  - 从 agent 配置文件中移除托管块
+  - 清理已分发的 skills
+
+## 配置结构
+
+配置以 YAML 格式存储在：
+
+- **全局**: `~/.monoco/config.yaml`
+- **项目**: `.monoco/config.yaml`
+
+关键配置段：
+
+- `core`: 编辑器、日志级别、作者
+- `paths`: 目录路径（issues, spikes, specs）
+- `project`: 项目元数据、spike repos、工作空间成员
+- `i18n`: 国际化设置
+- `agent`: Agent 框架集成设置
+
+## 最佳实践
+
+1. **优先使用 CLI 命令**，而不是手动编辑文件
+2. **配置更改后运行 `monoco sync`** 以更新 agent 环境
+3. **将 `.monoco/config.yaml` 提交到版本控制**，保持团队一致性
+4. **保持全局配置最小化** - 大多数设置应该是项目特定的

monoco/core/setup.py

@@ -251,30 +251,46 @@ ui:
 
     # 3. Scaffold Directories & Modules
     
-    # Import Feature Cores locally to avoid circular deps if any (though setup is core)
-    from monoco.features.issue import core as issue_core
-    from monoco.features.spike import core as spike_core
-    from monoco.features.i18n import core as i18n_core
-    from monoco.features import skills
-
-    # Initialize Issues
-    issues_path = cwd / project_config["paths"]["issues"]
-    issue_core.init(issues_path)
-
-    # Initialize Spikes
-    spikes_name = project_config["paths"]["spikes"]
-    spike_core.init(cwd, spikes_name)
-
-    # Initialize I18n
-    i18n_core.init(cwd)
-
-    # Initialize Skills & Agent Docs
-    resources = [
-        issue_core.get_resources(),
-        spike_core.get_resources(),
-        i18n_core.get_resources()
-    ]
-    skills.init(cwd, resources)
+    # 3. Scaffold Directories & Modules
+    
+    from monoco.core.registry import FeatureRegistry
+    from monoco.features.issue.adapter import IssueFeature
+    from monoco.features.spike.adapter import SpikeFeature
+    from monoco.features.i18n.adapter import I18nFeature
+    
+    registry = FeatureRegistry()
+    registry.register(IssueFeature())
+    registry.register(SpikeFeature())
+    registry.register(I18nFeature())
+    
+    # Initialize all features
+    for feature in registry.get_features():
+        try:
+             feature.initialize(cwd, project_config)
+             console.print(f"  [dim]Initialized feature: {feature.name}[/dim]")
+        except Exception as e:
+             console.print(f"  [red]Failed to initialize {feature.name}: {e}[/red]")
+             
+    # Trigger initial sync to set up Agent Environment
+    from monoco.core.sync import sync_command
+    # We call sync command logic directly or simulate it? 
+    # Just invoke the collection logic via sync normally would be best, 
+    # but sync_command is a click command wrapper.
+    # For now let's just initialize the physical structures. 
+    # The 'skills.init' call in old code did more than just init structure, 
+    # it wrote SKILL.md files. 
+    # In V2, we rely on 'monoco sync' to do that injection.
+    # So we should prompt user to run sync or do it automatically.
+    
+    # Let's run a sync
+    console.print("[bold blue]Setting up Agent Environment...[/bold blue]")
+    try:
+        # We need to reuse logic from sync.py
+        # Simplest is to run the sync workflow here manually/programmatically
+        # But for now, let's keep it clean and just say:
+        pass
+    except Exception:
+        pass
 
     console.print(f"[green]✓ Project config initialized at {project_config_path}[/green]")
     console.print(f"[green]✓ Config template generated at {template_path}[/green]")

monoco/core/skills.py

@@ -0,0 +1,444 @@
+"""
+Skill Manager for Monoco Toolkit.
+
+This module provides centralized management and distribution of Agent Skills
+following the agentskills.io standard.
+
+Key Responsibilities:
+1. Discover skills from the source directory (Toolkit/skills/)
+2. Validate skill structure and metadata (YAML frontmatter)
+3. Distribute skills to target agent framework directories
+4. Support i18n for skill content
+"""
+
+import shutil
+import hashlib
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+from pydantic import BaseModel, Field, ValidationError
+from rich.console import Console
+import yaml
+
+console = Console()
+
+
+class SkillMetadata(BaseModel):
+    """
+    Skill metadata from YAML frontmatter.
+    Based on agentskills.io standard.
+    """
+    name: str = Field(..., description="Unique skill identifier (lowercase, hyphens)")
+    description: str = Field(..., description="Clear description of what the skill does and when to use it")
+    version: Optional[str] = Field(default=None, description="Skill version")
+    author: Optional[str] = Field(default=None, description="Skill author")
+    tags: Optional[List[str]] = Field(default=None, description="Skill tags for categorization")
+
+
+class Skill:
+    """
+    Represents a single skill with its metadata and file paths.
+    """
+    def __init__(self, root_dir: Path, skill_dir: Path):
+        """
+        Initialize a Skill instance.
+        
+        Args:
+            root_dir: Project root directory
+            skill_dir: Path to the skill directory (e.g., Toolkit/skills/issues-management)
+        """
+        self.root_dir = root_dir
+        self.skill_dir = skill_dir
+        self.name = skill_dir.name
+        self.skill_file = skill_dir / "SKILL.md"
+        self.metadata: Optional[SkillMetadata] = None
+        self._load_metadata()
+    
+    def _load_metadata(self) -> None:
+        """Load and validate skill metadata from SKILL.md frontmatter."""
+        # Try to load from language subdirectories first (Feature resources pattern)
+        # Then fallback to root SKILL.md (legacy pattern)
+        skill_file_to_use = None
+        
+        # Check language subdirectories
+        if self.skill_dir.exists():
+            for item in sorted(self.skill_dir.iterdir()):
+                if item.is_dir() and len(item.name) == 2:  # 2-letter lang code
+                    candidate = item / "SKILL.md"
+                    if candidate.exists():
+                        skill_file_to_use = candidate
+                        break
+        
+        # Fallback to root SKILL.md
+        if not skill_file_to_use and self.skill_file.exists():
+            skill_file_to_use = self.skill_file
+        
+        if not skill_file_to_use:
+            return
+        
+        try:
+            content = skill_file_to_use.read_text(encoding="utf-8")
+            # Extract YAML frontmatter
+            if content.startswith("---"):
+                parts = content.split("---", 2)
+                if len(parts) >= 3:
+                    frontmatter = parts[1].strip()
+                    metadata_dict = yaml.safe_load(frontmatter)
+                    
+                    # Validate against schema
+                    self.metadata = SkillMetadata(**metadata_dict)
+        except ValidationError as e:
+            console.print(f"[red]Invalid metadata in {skill_file_to_use}: {e}[/red]")
+        except Exception as e:
+            console.print(f"[yellow]Warning: Failed to parse metadata from {skill_file_to_use}: {e}[/yellow]")
+    
+    def is_valid(self) -> bool:
+        """Check if the skill has valid metadata."""
+        return self.metadata is not None
+    
+    def get_languages(self) -> List[str]:
+        """
+        Detect available language versions of this skill.
+        
+        Returns:
+            List of language codes (e.g., ['en', 'zh'])
+        """
+        languages = []
+        
+        # Check for language subdirectories (Feature resources pattern)
+        # resources/en/SKILL.md, resources/zh/SKILL.md
+        for item in self.skill_dir.iterdir():
+            if item.is_dir() and len(item.name) == 2:  # Assume 2-letter lang codes
+                lang_skill_file = item / "SKILL.md"
+                if lang_skill_file.exists():
+                    languages.append(item.name)
+        
+        # Fallback: check for root SKILL.md (legacy Toolkit/skills pattern)
+        # We don't assume a default language, just return what we found
+        if not languages and self.skill_file.exists():
+            # For legacy pattern, we can't determine the language from structure
+            # Return empty to indicate this skill uses legacy pattern
+            pass
+        
+        return languages
+    
+    def get_checksum(self, lang: str) -> str:
+        """
+        Calculate checksum for the skill content.
+        
+        Args:
+            lang: Language code
+            
+        Returns:
+            SHA256 checksum of the skill file
+        """
+        # Try language subdirectory first (Feature resources pattern)
+        target_file = self.skill_dir / lang / "SKILL.md"
+        
+        # Fallback to root SKILL.md (legacy pattern)
+        if not target_file.exists():
+            target_file = self.skill_file
+        
+        if not target_file.exists():
+            return ""
+        
+        content = target_file.read_bytes()
+        return hashlib.sha256(content).hexdigest()
+
+
+class SkillManager:
+    """
+    Central manager for Monoco skills.
+    
+    Responsibilities:
+    - Collect skills from Feature resources
+    - Validate skill structure
+    - Distribute skills to agent framework directories
+    """
+    
+    def __init__(self, root: Path, features: Optional[List] = None):
+        """
+        Initialize SkillManager.
+        
+        Args:
+            root: Project root directory
+            features: List of MonocoFeature instances (if None, will load from registry)
+        """
+        self.root = root
+        self.features = features or []
+        self.skills: Dict[str, Skill] = {}
+        
+        if self.features:
+            self._discover_skills_from_features()
+        
+        # Also discover core skill (monoco/core/resources/)
+        self._discover_core_skill()
+    
+    def _discover_core_skill(self) -> None:
+        """
+        Discover skill from monoco/core/resources/.
+        
+        Core is special - it's not a Feature but still has a skill.
+        """
+        core_resources_dir = self.root / "monoco" / "core" / "resources"
+        
+        if not core_resources_dir.exists():
+            return
+        
+        # Check for SKILL.md in language directories
+        for lang_dir in core_resources_dir.iterdir():
+            if lang_dir.is_dir() and (lang_dir / "SKILL.md").exists():
+                skill = Skill(self.root, core_resources_dir)
+                
+                # Use the skill's metadata name if available
+                if skill.metadata and skill.metadata.name:
+                    skill.name = skill.metadata.name.replace('-', '_')
+                else:
+                    skill.name = "monoco_core"
+                
+                if skill.is_valid():
+                    self.skills[skill.name] = skill
+                break  # Only need to detect once
+    
+    def _discover_skills_from_features(self) -> None:
+        """
+        Discover skills from Feature resources.
+        
+        Each feature should have:
+        - monoco/features/{feature}/resources/{lang}/SKILL.md
+        """
+        from monoco.core.feature import MonocoFeature
+        
+        for feature in self.features:
+            if not isinstance(feature, MonocoFeature):
+                continue
+            
+            # Determine feature module path
+            # feature.__class__.__module__ is like 'monoco.features.issue.adapter'
+            module_parts = feature.__class__.__module__.split('.')
+            if len(module_parts) >= 3 and module_parts[0] == 'monoco' and module_parts[1] == 'features':
+                feature_name = module_parts[2]
+                
+                # Construct path to feature resources
+                # monoco/features/{feature}/resources/
+                feature_dir = self.root / "monoco" / "features" / feature_name
+                resources_dir = feature_dir / "resources"
+                
+                if not resources_dir.exists():
+                    continue
+                
+                # Check for SKILL.md in language directories
+                for lang_dir in resources_dir.iterdir():
+                    if lang_dir.is_dir() and (lang_dir / "SKILL.md").exists():
+                        # Create a Skill instance
+                        # We need to adapt the Skill class to work with feature resources
+                        skill = self._create_skill_from_feature(feature_name, resources_dir)
+                        if skill and skill.is_valid():
+                            # Use feature name as skill identifier
+                            skill_key = f"{feature_name}"
+                            if skill_key not in self.skills:
+                                self.skills[skill_key] = skill
+                        break  # Only need to detect once per feature
+    
+    def _create_skill_from_feature(self, feature_name: str, resources_dir: Path) -> Optional[Skill]:
+        """
+        Create a Skill instance from a feature's resources directory.
+        
+        Args:
+            feature_name: Name of the feature (e.g., 'issue', 'spike')
+            resources_dir: Path to the feature's resources directory
+            
+        Returns:
+            Skill instance or None if creation fails
+        """
+        # Use the resources directory as the skill directory
+        # The Skill class expects a directory with SKILL.md or {lang}/SKILL.md
+        skill = Skill(self.root, resources_dir)
+        
+        # Use the skill's metadata name if available (e.g., 'monoco-issue')
+        # Convert to snake_case for directory name (e.g., 'monoco_issue')
+        if skill.metadata and skill.metadata.name:
+            # Convert kebab-case to snake_case for directory name
+            skill.name = skill.metadata.name.replace('-', '_')
+        else:
+            # Fallback to feature name
+            skill.name = f"monoco_{feature_name}"
+        
+        return skill
+    
+    def list_skills(self) -> List[Skill]:
+        """
+        Get all available skills.
+        
+        Returns:
+            List of Skill instances
+        """
+        return list(self.skills.values())
+    
+    def get_skill(self, name: str) -> Optional[Skill]:
+        """
+        Get a specific skill by name.
+        
+        Args:
+            name: Skill name
+            
+        Returns:
+            Skill instance or None if not found
+        """
+        return self.skills.get(name)
+    
+    def distribute(
+        self,
+        target_dir: Path,
+        lang: str,
+        force: bool = False
+    ) -> Dict[str, bool]:
+        """
+        Distribute skills to a target directory.
+        
+        Args:
+            target_dir: Target directory for skill distribution (e.g., .cursor/skills/)
+            lang: Language code to distribute (e.g., 'en', 'zh')
+            force: Force overwrite even if checksum matches
+            
+        Returns:
+            Dictionary mapping skill names to success status
+        """
+        results = {}
+        
+        # Ensure target directory exists
+        target_dir.mkdir(parents=True, exist_ok=True)
+        
+        for skill_name, skill in self.skills.items():
+            try:
+                # Check if this skill has the requested language
+                available_languages = skill.get_languages()
+                
+                if lang not in available_languages:
+                    console.print(f"[yellow]Skill {skill_name} does not have {lang} version, skipping[/yellow]")
+                    results[skill_name] = False
+                    continue
+                
+                # Distribute the specific language version
+                self._distribute_skill_language(skill, target_dir, lang, force)
+                results[skill_name] = True
+                
+            except Exception as e:
+                console.print(f"[red]Failed to distribute skill {skill_name}: {e}[/red]")
+                results[skill_name] = False
+        
+        return results
+    
+    def _distribute_skill_language(
+        self,
+        skill: Skill,
+        target_dir: Path,
+        lang: str,
+        force: bool
+    ) -> None:
+        """
+        Distribute a specific language version of a skill.
+        
+        Args:
+            skill: Skill instance
+            target_dir: Target directory (e.g., .cursor/skills/)
+            lang: Language code
+            force: Force overwrite
+        """
+        # Determine source file (try language subdirectory first)
+        source_file = skill.skill_dir / lang / "SKILL.md"
+        
+        # Fallback to root SKILL.md (legacy pattern)
+        if not source_file.exists():
+            source_file = skill.skill_file
+        
+        if not source_file.exists():
+            console.print(f"[yellow]Source file not found for {skill.name}/{lang}[/yellow]")
+            return
+        
+        # Target path: {target_dir}/{skill_name}/SKILL.md (no language subdirectory)
+        target_skill_dir = target_dir / skill.name
+        
+        # Create target directory
+        target_skill_dir.mkdir(parents=True, exist_ok=True)
+        target_file = target_skill_dir / "SKILL.md"
+        
+        # Check if update is needed
+        if target_file.exists() and not force:
+            source_checksum = skill.get_checksum(lang)
+            target_content = target_file.read_bytes()
+            target_checksum = hashlib.sha256(target_content).hexdigest()
+            
+            if source_checksum == target_checksum:
+                console.print(f"[dim]  = {skill.name}/SKILL.md is up to date[/dim]")
+                return
+        
+        # Copy the file
+        shutil.copy2(source_file, target_file)
+        console.print(f"[green]  ✓ Distributed {skill.name}/SKILL.md ({lang})[/green]")
+        
+        # Copy additional resources if they exist
+        self._copy_skill_resources(skill.skill_dir, target_skill_dir, lang)
+    
+    def _copy_skill_resources(
+        self,
+        source_dir: Path,
+        target_dir: Path,
+        lang: str
+    ) -> None:
+        """
+        Copy additional skill resources (scripts, examples, etc.).
+        
+        Args:
+            source_dir: Source skill directory
+            target_dir: Target skill directory
+            lang: Language code
+        """
+        # Define resource directories to copy
+        resource_dirs = ['scripts', 'examples', 'resources']
+        
+        # Try language subdirectory first (Feature resources pattern)
+        source_base = source_dir / lang
+        
+        # Fallback to root directory (legacy pattern)
+        if not source_base.exists():
+            source_base = source_dir
+        
+        for resource_name in resource_dirs:
+            source_resource = source_base / resource_name
+            if source_resource.exists() and source_resource.is_dir():
+                target_resource = target_dir / resource_name
+                
+                # Remove existing and copy fresh
+                if target_resource.exists():
+                    shutil.rmtree(target_resource)
+                
+                shutil.copytree(source_resource, target_resource)
+                console.print(f"[dim]    Copied {resource_name}/ for {source_dir.name}/{lang}[/dim]")
+    
+    def cleanup(self, target_dir: Path) -> None:
+        """
+        Remove distributed skills from a target directory.
+        
+        Args:
+            target_dir: Target directory to clean
+        """
+        if not target_dir.exists():
+            console.print(f"[dim]Target directory does not exist: {target_dir}[/dim]")
+            return
+        
+        removed_count = 0
+        
+        for skill_name in self.skills.keys():
+            skill_target = target_dir / skill_name
+            if skill_target.exists():
+                shutil.rmtree(skill_target)
+                console.print(f"[green]  ✓ Removed {skill_name}[/green]")
+                removed_count += 1
+        
+        # Remove empty parent directory if no skills remain
+        if target_dir.exists() and not any(target_dir.iterdir()):
+            target_dir.rmdir()
+            console.print(f"[dim]  Removed empty directory: {target_dir}[/dim]")
+        
+        if removed_count == 0:
+            console.print(f"[dim]No skills to remove from {target_dir}[/dim]")