minion-code 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

minion_code/subagents/builtin/plan.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Built-in Plan subagent configuration."""
+
+from ..subagent import SubagentConfig
+
+PLAN_SYSTEM_PROMPT = """You are a software architect and planning specialist. Your role is to explore codebases and design implementation plans.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
+- Creating new files (no file_write, touch, or file creation)
+- Modifying existing files (no file_edit operations)
+- Deleting files (no rm or deletion)
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans.
+
+## Your Process
+
+1. **Understand Requirements**: Analyze what needs to be built or changed.
+
+2. **Explore Thoroughly**:
+   - Find existing patterns and conventions using glob, grep, and file_read
+   - Understand the current architecture
+   - Identify similar features as reference
+   - Trace through relevant code paths
+
+3. **Design Solution**:
+   - Create implementation approach
+   - Consider trade-offs and architectural decisions
+   - Follow existing patterns where appropriate
+
+4. **Detail the Plan**:
+   - Provide step-by-step implementation strategy
+   - Identify files to create/modify with specific changes
+   - Anticipate potential challenges
+
+## Output Format
+
+End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- path/to/file1.ts - [Brief reason]
+- path/to/file2.ts - [Brief reason]
+
+REMEMBER: You can ONLY explore and plan. You CANNOT modify any files."""
+
+
+def get_plan_subagent() -> SubagentConfig:
+    """Get the Plan subagent configuration."""
+    return SubagentConfig(
+        name="Plan",
+        description="Software architect agent for designing implementation plans by exploring codebases and identifying patterns",
+        when_to_use="When you need to design an implementation plan, understand how to approach a complex feature, or analyze architecture before making changes",
+        tools=["glob", "grep", "file_read", "ls", "web_fetch", "web_search"],
+        system_prompt=PLAN_SYSTEM_PROMPT,
+        model_name="inherit",
+        location="builtin",
+        readonly=True,
+    )

minion_code/subagents/subagent.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Subagent configuration dataclass representing a loaded subagent type.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+import yaml
+
+
+@dataclass
+class SubagentConfig:
+    """Represents a configured subagent type with its metadata and settings."""
+
+    name: str  # Unique identifier (e.g., "Explore", "Plan")
+    description: str  # Short description of what the agent does
+    when_to_use: str  # When the user should use this agent
+    tools: List[str] = field(default_factory=lambda: ["*"])  # Tool filter: ["*"] = all
+    system_prompt: Optional[str] = None  # Custom system prompt for this agent type
+    model_name: str = "inherit"  # "inherit" = use parent, or specific model name
+
+    # Additional metadata
+    path: Optional[Path] = None  # Path to config file (for file-based configs)
+    location: str = "builtin"  # builtin, project, user
+    readonly: bool = False  # If True, agent only gets read-only tools
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_yaml(
+        cls, yaml_path: Path, location: str = "project"
+    ) -> Optional["SubagentConfig"]:
+        """
+        Parse a SUBAGENT.yaml file and create a SubagentConfig instance.
+
+        Args:
+            yaml_path: Path to the SUBAGENT.yaml file
+            location: Where the subagent was found (project, user)
+
+        Returns:
+            SubagentConfig instance or None if parsing fails
+        """
+        if not yaml_path.exists():
+            return None
+
+        try:
+            content = yaml_path.read_text(encoding="utf-8")
+            data = yaml.safe_load(content)
+        except (yaml.YAMLError, IOError):
+            return None
+
+        if not data:
+            return None
+
+        name = data.get("name")
+        description = data.get("description")
+        when_to_use = data.get("when_to_use")
+
+        if not name or not description or not when_to_use:
+            return None
+
+        # Load system_prompt from separate file if specified
+        system_prompt = data.get("system_prompt")
+        if (
+            system_prompt
+            and isinstance(system_prompt, str)
+            and system_prompt.startswith("file:")
+        ):
+            prompt_file = yaml_path.parent / system_prompt[5:]
+            if prompt_file.exists():
+                system_prompt = prompt_file.read_text(encoding="utf-8")
+            else:
+                system_prompt = None
+
+        return cls(
+            name=name,
+            description=description,
+            when_to_use=when_to_use,
+            tools=data.get("tools", ["*"]),
+            system_prompt=system_prompt,
+            model_name=data.get("model_name", "inherit"),
+            path=yaml_path.parent,
+            location=location,
+            readonly=data.get("readonly", False),
+            metadata=data.get("metadata", {}),
+        )
+
+    def to_xml(self) -> str:
+        """
+        Format subagent as XML for inclusion in prompts.
+
+        Returns:
+            XML formatted subagent entry
+        """
+        tools_str = ", ".join(self.tools) if self.tools != ["*"] else "All tools"
+        return f"""<subagent>
+<name>{self.name}</name>
+<description>{self.description}</description>
+<when_to_use>{self.when_to_use}</when_to_use>
+<tools>{tools_str}</tools>
+<location>{self.location}</location>
+</subagent>"""
+
+    def to_prompt_line(self) -> str:
+        """
+        Format subagent as a single line for tool description.
+
+        Returns:
+            Formatted prompt line like: "- Explore: Fast codebase exploration... (Tools: glob, grep)"
+        """
+        tools_str = ", ".join(self.tools) if self.tools != ["*"] else "All tools"
+        return f"- {self.name}: {self.description} (Tools: {tools_str})"
+
+    def __repr__(self) -> str:
+        return f"SubagentConfig(name={self.name!r}, location={self.location!r})"

minion_code/subagents/subagent_loader.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Subagent Loader - discovers and loads subagent configurations from standard directories.
+"""
+
+import logging
+from pathlib import Path
+from typing import List, Optional
+
+from .subagent import SubagentConfig
+from .subagent_registry import SubagentRegistry, get_subagent_registry
+from .builtin import get_all_builtin_subagents
+
+logger = logging.getLogger(__name__)
+
+
+class SubagentLoader:
+    """
+    Discovers and loads subagent configurations.
+
+    Search paths (in priority order - lower priority registered first):
+    1. builtin (code-defined)
+    2. ~/.claude/subagents or ~/.minion/subagents (user-level)
+    3. .claude/subagents or .minion/subagents (project-level)
+
+    Project-level overrides user-level, which overrides builtin.
+    """
+
+    SUBAGENT_DIRS = [
+        ".claude/agents",  # Claude Code compatible
+        ".minion/agents",  # Minion compatible
+        ".claude/subagents",  # Legacy/alternative
+        ".minion/subagents",  # Legacy/alternative
+    ]
+
+    SUBAGENT_FILE = "SUBAGENT.yaml"
+
+    def __init__(self, project_root: Optional[Path] = None):
+        """Initialize the subagent loader."""
+        self.project_root = Path(project_root) if project_root else Path.cwd()
+        self.home_dir = Path.home()
+
+    def get_search_paths(self) -> List[tuple[Path, str]]:
+        """
+        Get all subagent search paths with their location type.
+        Returns paths in priority order (lowest priority first).
+        """
+        paths = []
+
+        # User-level paths (lower priority than project)
+        for subagent_dir in self.SUBAGENT_DIRS:
+            user_path = self.home_dir / subagent_dir
+            paths.append((user_path, "user"))
+
+        # Project-level paths (highest priority)
+        for subagent_dir in self.SUBAGENT_DIRS:
+            project_path = self.project_root / subagent_dir
+            paths.append((project_path, "project"))
+
+        return paths
+
+    def discover_subagents(self, subagents_dir: Path) -> List[Path]:
+        """
+        Discover all subagent directories within a subagents directory.
+        A subagent directory must contain a SUBAGENT.yaml file.
+        """
+        if not subagents_dir.exists() or not subagents_dir.is_dir():
+            return []
+
+        subagent_files = []
+
+        for item in subagents_dir.iterdir():
+            if item.is_dir():
+                subagent_yaml = item / self.SUBAGENT_FILE
+                if subagent_yaml.exists():
+                    subagent_files.append(subagent_yaml)
+
+        return subagent_files
+
+    def load_subagent(self, yaml_path: Path, location: str) -> Optional[SubagentConfig]:
+        """Load a single subagent from its SUBAGENT.yaml file."""
+        try:
+            subagent = SubagentConfig.from_yaml(yaml_path, location)
+            if subagent:
+                logger.debug(f"Loaded subagent: {subagent.name} from {yaml_path}")
+            else:
+                logger.warning(f"Failed to parse subagent: {yaml_path}")
+            return subagent
+        except Exception as e:
+            logger.error(f"Error loading subagent from {yaml_path}: {e}")
+            return None
+
+    def load_all(self, registry: Optional[SubagentRegistry] = None) -> SubagentRegistry:
+        """
+        Load all subagents (builtin + custom) into the registry.
+        Builtin is registered first (lowest priority), then user, then project.
+        """
+        if registry is None:
+            registry = get_subagent_registry()
+
+        # 1. Register builtin subagents first (lowest priority)
+        for subagent in get_all_builtin_subagents():
+            registered = registry.register(subagent)
+            if registered:
+                logger.debug(f"Registered builtin subagent: {subagent.name}")
+
+        # 2. Load from file system (user then project)
+        for search_path, location in self.get_search_paths():
+            subagent_files = self.discover_subagents(search_path)
+
+            for yaml_path in subagent_files:
+                subagent = self.load_subagent(yaml_path, location)
+                if subagent:
+                    registered = registry.register(subagent)
+                    if registered:
+                        logger.debug(f"Registered {location} subagent: {subagent.name}")
+                    else:
+                        logger.debug(
+                            f"Skipped subagent {subagent.name} - already registered from higher priority"
+                        )
+
+        return registry
+
+    def reload(self, registry: Optional[SubagentRegistry] = None) -> SubagentRegistry:
+        """Reload all subagents, clearing the existing registry first."""
+        if registry is None:
+            registry = get_subagent_registry()
+
+        registry.clear()
+        return self.load_all(registry)
+
+
+def load_subagents(project_root: Optional[Path] = None) -> SubagentRegistry:
+    """Convenience function to load all subagents."""
+    loader = SubagentLoader(project_root)
+    return loader.load_all()
+
+
+def get_available_subagents() -> List[SubagentConfig]:
+    """Get list of all available subagents."""
+    registry = get_subagent_registry()
+
+    if len(registry) == 0:
+        load_subagents()
+
+    return registry.list_all()

minion_code/subagents/subagent_registry.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Subagent Registry - manages loaded subagent configurations and provides lookup functionality.
+"""
+
+from typing import Dict, Optional, List
+from .subagent import SubagentConfig
+
+
+class SubagentRegistry:
+    """
+    Registry for managing loaded subagent configurations.
+
+    Subagents are organized by name and can be looked up for task execution.
+    The registry handles subagent deduplication based on priority.
+    Priority: builtin < user < project (project overrides all)
+    """
+
+    PRIORITY_ORDER = {"builtin": 2, "user": 1, "project": 0}
+
+    def __init__(self):
+        self._subagents: Dict[str, SubagentConfig] = {}
+        self._subagents_by_location: Dict[str, List[SubagentConfig]] = {
+            "builtin": [],
+            "project": [],
+            "user": [],
+        }
+
+    def register(self, subagent: SubagentConfig) -> bool:
+        """
+        Register a subagent in the registry.
+
+        Project subagents take precedence over user subagents,
+        which take precedence over builtin.
+
+        Args:
+            subagent: SubagentConfig instance to register
+
+        Returns:
+            True if the subagent was registered, False if it was skipped
+        """
+        existing = self._subagents.get(subagent.name)
+
+        if existing:
+            existing_priority = self.PRIORITY_ORDER.get(existing.location, 99)
+            new_priority = self.PRIORITY_ORDER.get(subagent.location, 99)
+
+            if new_priority >= existing_priority:
+                # Skip - existing subagent has higher or equal priority
+                return False
+
+        self._subagents[subagent.name] = subagent
+        self._subagents_by_location[subagent.location].append(subagent)
+        return True
+
+    def get(self, name: str) -> Optional[SubagentConfig]:
+        """Get a subagent by name."""
+        return self._subagents.get(name)
+
+    def exists(self, name: str) -> bool:
+        """Check if a subagent exists in the registry."""
+        return name in self._subagents
+
+    def list_all(self) -> List[SubagentConfig]:
+        """Get all registered subagents."""
+        return list(self._subagents.values())
+
+    def list_names(self) -> List[str]:
+        """Get all registered subagent names."""
+        return list(self._subagents.keys())
+
+    def list_by_location(self, location: str) -> List[SubagentConfig]:
+        """Get subagents by location type."""
+        return self._subagents_by_location.get(location, [])
+
+    def clear(self):
+        """Clear all registered subagents."""
+        self._subagents.clear()
+        for location in self._subagents_by_location:
+            self._subagents_by_location[location].clear()
+
+    def generate_subagents_prompt(self, char_budget: int = 10000) -> str:
+        """
+        Generate a prompt listing all available subagents in XML format.
+
+        Args:
+            char_budget: Maximum characters for subagents list
+
+        Returns:
+            Formatted subagents prompt in XML format
+        """
+        subagents = self.list_all()
+
+        if not subagents:
+            return ""
+
+        entries = []
+        total_chars = 0
+
+        for subagent in subagents:
+            entry = subagent.to_xml()
+            if total_chars + len(entry) > char_budget:
+                break
+            entries.append(entry)
+            total_chars += len(entry)
+
+        if not entries:
+            return ""
+
+        subagents_xml = "\n".join(entries)
+        return f"""<available_subagents>
+{subagents_xml}
+</available_subagents>"""
+
+    def generate_tool_description_lines(self) -> str:
+        """
+        Generate description lines for the Task tool.
+
+        Returns:
+            Multi-line string with each subagent's prompt line
+        """
+        subagents = self.list_all()
+        return "\n".join(s.to_prompt_line() for s in subagents)
+
+    def __len__(self) -> int:
+        return len(self._subagents)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._subagents
+
+    def __iter__(self):
+        return iter(self._subagents.values())
+
+
+# Global subagent registry instance
+_subagent_registry: Optional[SubagentRegistry] = None
+
+
+def get_subagent_registry() -> SubagentRegistry:
+    """Get the global subagent registry instance."""
+    global _subagent_registry
+    if _subagent_registry is None:
+        _subagent_registry = SubagentRegistry()
+    return _subagent_registry
+
+
+def reset_subagent_registry():
+    """Reset the global subagent registry."""
+    global _subagent_registry
+    _subagent_registry = None

minion_code/tools/__init__.py

@@ -19,9 +19,11 @@ from .glob_tool import GlobTool
 from .ls_tool import LsTool
 from .python_interpreter_tool import PythonInterpreterTool
 from .user_input_tool import UserInputTool
+from .task_tool import TaskTool
 
 from .todo_write_tool import TodoWriteTool
 from .todo_read_tool import TodoReadTool
+from .skill_tool import SkillTool
 
 # Tool mapping
 TOOL_MAPPING = {
@@ -37,9 +39,10 @@ TOOL_MAPPING = {
         LsTool,
         PythonInterpreterTool,
         UserInputTool,
-
+        TaskTool,
         TodoWriteTool,
         TodoReadTool,
+        SkillTool,
     ]
 }
 
@@ -57,13 +60,16 @@ __all__ = [
     "LsTool",
     # Execution tools
     "PythonInterpreterTool",
+    # Task tools
+    "TaskTool",
     # Web tools
     # Interactive tools
     "UserInputTool",
-
     # Todo tools
     "TodoWriteTool",
     "TodoReadTool",
+    # Skill tools
+    "SkillTool",
     # Utilities
     "TOOL_MAPPING",
 ]

minion_code/tools/bash_tool.py

@@ -6,8 +6,9 @@ Bash command execution tool
 
 import os
 import subprocess
-from typing import Optional
+from typing import Optional, Any
 from minion.tools import BaseTool
+from ..utils.output_truncator import truncate_output
 
 
 class BashTool(BaseTool):
@@ -26,6 +27,10 @@ class BashTool(BaseTool):
     }
     output_type = "string"
 
+    def __init__(self, workdir: Optional[str] = None, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.workdir = workdir
+
     def forward(self, command: str, timeout: Optional[int] = 30) -> str:
         """Execute bash command"""
         try:
@@ -34,13 +39,15 @@ class BashTool(BaseTool):
             if any(dangerous in command.lower() for dangerous in dangerous_commands):
                 return f"Error: Dangerous command prohibited - {command}"
 
+            # Use injected workdir if available, otherwise fallback to cwd
+            cwd = self.workdir if self.workdir else os.getcwd()
             result = subprocess.run(
                 command,
                 shell=True,
                 capture_output=True,
                 text=True,
                 timeout=timeout,
-                cwd=os.getcwd(),
+                cwd=cwd,
             )
 
             output = ""
@@ -50,9 +57,15 @@ class BashTool(BaseTool):
                 output += f"Standard error:\n{result.stderr}\n"
             output += f"Exit code: {result.returncode}"
 
-            return output
+            return self.format_for_observation(output)
 
         except subprocess.TimeoutExpired:
             return f"Command execution timeout ({timeout} seconds)"
         except Exception as e:
             return f"Error executing command: {str(e)}"
+
+    def format_for_observation(self, output: Any) -> str:
+        """格式化输出，自动截断过大内容"""
+        if isinstance(output, str):
+            return truncate_output(output, tool_name=self.name)
+        return str(output)