monoco-toolkit 0.3.6__py3-none-any.whl → 0.3.10__py3-none-any.whl

monoco/features/agent/flow_skills.py

@@ -0,0 +1,281 @@
+"""
+Flow Skills Manager for Monoco Scheduler.
+
+This module provides management and injection of standard Agent workflow skills
+(Flow Skills) following the Kimi CLI Flow Skill format.
+
+Note: This module is now a thin wrapper around SkillManager for backward compatibility.
+New code should use SkillManager directly for multi-skill architecture support.
+
+Key Responsibilities:
+1. Discover flow skills from resources/skills/ directory
+2. Inject flow skills to target agent framework directories
+3. Handle .gitignore updates for injected skills
+"""
+
+import shutil
+from pathlib import Path
+from typing import List, Set
+from rich.console import Console
+
+console = Console()
+
+# Prefix for injected flow skills to avoid conflicts
+FLOW_SKILL_PREFIX = "monoco_flow_"
+
+# Gitignore pattern for flow skills
+GITIGNORE_PATTERN = f"{FLOW_SKILL_PREFIX}*/"
+
+
+def discover_flow_skills(resources_dir: Path) -> List[Path]:
+    """
+    Discover all flow skill directories in the resources/skills/ directory.
+
+    Flow skills are identified by either:
+    1. Directory name starting with "flow_" (legacy pattern)
+    2. SKILL.md containing "type: flow" in front matter (new pattern)
+
+    Args:
+        resources_dir: Path to the resources directory (e.g., monoco/features/scheduler/resources/)
+
+    Returns:
+        List of paths to flow skill directories
+    """
+    skills_dir = resources_dir / "skills"
+    if not skills_dir.exists():
+        return []
+
+    flow_skills = []
+    for item in skills_dir.iterdir():
+        if not item.is_dir():
+            continue
+
+        skill_file = item / "SKILL.md"
+        if not skill_file.exists():
+            continue
+
+        # Check legacy pattern: directory starts with "flow_"
+        if item.name.startswith("flow_"):
+            flow_skills.append(item)
+            continue
+
+        # Check new pattern: SKILL.md contains "type: flow" in front matter
+        try:
+            content = skill_file.read_text(encoding="utf-8")
+            # Look for type: flow in front matter (between --- markers)
+            if content.startswith("---"):
+                front_matter_end = content.find("---", 3)
+                if front_matter_end != -1:
+                    front_matter = content[3:front_matter_end]
+                    if "type: flow" in front_matter:
+                        flow_skills.append(item)
+        except Exception:
+            pass  # Skip files that can't be read
+
+    return sorted(flow_skills)
+
+
+def inject_flow_skill(
+    skill_dir: Path, target_dir: Path, prefix: str = FLOW_SKILL_PREFIX
+) -> bool:
+    """
+    Inject a single flow skill to the target directory.
+
+    Args:
+        skill_dir: Source flow skill directory (e.g., .../flow_engineer/)
+        target_dir: Target directory for skill injection (e.g., .agent/skills/)
+        prefix: Prefix to add to the skill directory name
+
+    Returns:
+        True if injection successful, False otherwise
+    """
+    try:
+        # Calculate target skill name with prefix
+        # e.g., flow_engineer -> monoco_flow_engineer
+        target_skill_name = f"{prefix}{skill_dir.name}"
+        target_skill_dir = target_dir / target_skill_name
+
+        # Remove existing skill directory if present
+        if target_skill_dir.exists():
+            shutil.rmtree(target_skill_dir)
+
+        # Copy skill directory
+        shutil.copytree(skill_dir, target_skill_dir)
+
+        console.print(f"[green]  ✓ Injected {target_skill_name}/[/green]")
+        return True
+
+    except Exception as e:
+        console.print(f"[red]  ✗ Failed to inject {skill_dir.name}: {e}[/red]")
+        return False
+
+
+def sync_flow_skills(
+    resources_dir: Path,
+    target_dir: Path,
+    prefix: str = FLOW_SKILL_PREFIX,
+    force: bool = False,
+) -> dict:
+    """
+    Synchronize all flow skills from resources to target directory.
+
+    This function:
+    1. Discovers all flow skills in resources/skills/
+    2. Injects them to target_dir with the specified prefix
+    3. Optionally removes skills that no longer exist in source
+
+    Args:
+        resources_dir: Path to the resources directory
+        target_dir: Target directory for skill injection (e.g., .agent/skills/)
+        prefix: Prefix to add to skill directory names
+        force: Force re-injection even if skills already exist
+
+    Returns:
+        Dictionary with 'injected', 'failed', 'removed' counts
+    """
+    results = {"injected": 0, "failed": 0, "removed": 0}
+
+    # Ensure target directory exists
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # Discover flow skills
+    flow_skills = discover_flow_skills(resources_dir)
+
+    if not flow_skills:
+        console.print("[yellow]No flow skills found in resources[/yellow]")
+        return results
+
+    console.print(f"[dim]Found {len(flow_skills)} flow skill(s)[/dim]")
+
+    # Track expected skill names
+    expected_skills: Set[str] = set()
+
+    # Inject each flow skill
+    for skill_dir in flow_skills:
+        target_skill_name = f"{prefix}{skill_dir.name}"
+        expected_skills.add(target_skill_name)
+
+        # Check if already exists and not force
+        target_skill_dir = target_dir / target_skill_name
+        if target_skill_dir.exists() and not force:
+            # Check if source is newer
+            source_mtime = (skill_dir / "SKILL.md").stat().st_mtime
+            target_mtime = (target_skill_dir / "SKILL.md").stat().st_mtime
+
+            if source_mtime <= target_mtime:
+                console.print(f"[dim]  = {target_skill_name}/ is up to date[/dim]")
+                continue
+
+        if inject_flow_skill(skill_dir, target_dir, prefix):
+            results["injected"] += 1
+        else:
+            results["failed"] += 1
+
+    # Clean up orphaned skills (optional, when force=True)
+    if force:
+        for item in target_dir.iterdir():
+            if item.is_dir() and item.name.startswith(prefix):
+                if item.name not in expected_skills:
+                    shutil.rmtree(item)
+                    console.print(f"[dim]  - Removed orphaned {item.name}/[/dim]")
+                    results["removed"] += 1
+
+    return results
+
+
+def update_gitignore(project_root: Path, pattern: str = GITIGNORE_PATTERN) -> bool:
+    """
+    Add flow skill pattern to .gitignore if not present.
+
+    Args:
+        project_root: Project root directory
+        pattern: Gitignore pattern to add
+
+    Returns:
+        True if .gitignore was updated or already contains pattern
+    """
+    gitignore_path = project_root / ".gitignore"
+
+    try:
+        # Read existing content
+        if gitignore_path.exists():
+            content = gitignore_path.read_text(encoding="utf-8")
+            lines = content.splitlines()
+        else:
+            lines = []
+
+        # Check if pattern already exists
+        for line in lines:
+            if line.strip() == pattern or line.strip() == f"/{pattern}":
+                return True
+
+        # Add pattern with comment
+        comment = "# Monoco Flow Skills (auto-generated)"
+        new_lines = [comment, pattern, ""]
+
+        # Append to file
+        with open(gitignore_path, "a", encoding="utf-8") as f:
+            # Add newline if file doesn't end with one
+            if lines and not content.endswith("\n"):
+                f.write("\n")
+            f.write("\n".join(new_lines))
+
+        console.print(f"[green]  ✓ Updated .gitignore with {pattern}[/green]")
+        return True
+
+    except Exception as e:
+        console.print(f"[red]  ✗ Failed to update .gitignore: {e}[/red]")
+        return False
+
+
+def remove_flow_skills(target_dir: Path, prefix: str = FLOW_SKILL_PREFIX) -> int:
+    """
+    Remove all injected flow skills from target directory.
+
+    Args:
+        target_dir: Target directory (e.g., .agent/skills/)
+        prefix: Prefix used for flow skill directories
+
+    Returns:
+        Number of skills removed
+    """
+    if not target_dir.exists():
+        return 0
+
+    removed_count = 0
+    for item in target_dir.iterdir():
+        if item.is_dir() and item.name.startswith(prefix):
+            shutil.rmtree(item)
+            console.print(f"[green]  ✓ Removed {item.name}/[/green]")
+            removed_count += 1
+
+    return removed_count
+
+
+def get_flow_skill_commands(target_dir: Path, prefix: str = FLOW_SKILL_PREFIX) -> List[str]:
+    """
+    Get list of available flow skill commands.
+
+    In Kimi CLI, flow skills are invoked via /flow:<role> command.
+    This function extracts the role names from injected flow skills.
+
+    Args:
+        target_dir: Target directory (e.g., .agent/skills/)
+        prefix: Prefix used for flow skill directories
+
+    Returns:
+        List of available /flow:<role> commands
+    """
+    if not target_dir.exists():
+        return []
+
+    commands = []
+    for item in target_dir.iterdir():
+        if item.is_dir() and item.name.startswith(prefix):
+            # Extract role from directory name
+            # e.g., monoco_flow_engineer -> engineer
+            role = item.name[len(prefix) + 5:]  # Remove prefix + "flow_"
+            if role:
+                commands.append(f"/flow:{role}")
+
+    return sorted(commands)

monoco/features/agent/manager.py

@@ -0,0 +1,91 @@
+from typing import Dict, List, Optional
+import uuid
+from pathlib import Path
+
+from .models import RoleTemplate
+from .worker import Worker
+from .session import Session, RuntimeSession
+from monoco.core.hooks import HookRegistry, get_registry
+from monoco.core.config import find_monoco_root, MonocoConfig
+
+
+class SessionManager:
+    """
+    Manages the lifecycle of sessions.
+    Responsible for creating, tracking, and retrieving sessions.
+    """
+
+    def __init__(
+        self,
+        project_root: Optional[Path] = None,
+        hook_registry: Optional[HookRegistry] = None,
+        config: Optional[MonocoConfig] = None,
+    ):
+        # In-memory storage for now. In prod, this might be a DB or file-backed.
+        self._sessions: Dict[str, RuntimeSession] = {}
+        self.project_root = project_root or find_monoco_root()
+        self.config = config
+        
+        # Initialize hook registry
+        self.hook_registry = hook_registry or get_registry()
+        
+        # Load hooks from config if available
+        self._load_hooks_from_config()
+
+    def _load_hooks_from_config(self) -> None:
+        """Load and register hooks from configuration."""
+        if self.config is None:
+            try:
+                from monoco.core.config import get_config
+                self.config = get_config(str(self.project_root))
+            except Exception:
+                return
+        
+        # Load hooks from config
+        if self.config and hasattr(self.config, "session_hooks"):
+            hooks_config = self.config.session_hooks
+            if hooks_config:
+                self.hook_registry.load_from_config(hooks_config, self.project_root)
+
+    def create_session(self, issue_id: str, role: RoleTemplate) -> RuntimeSession:
+        session_id = str(uuid.uuid4())
+        branch_name = (
+            f"agent/{issue_id}/{session_id[:8]}"  # Simple branch naming strategy
+        )
+
+        session_model = Session(
+            id=session_id,
+            issue_id=issue_id,
+            role_name=role.name,
+            branch_name=branch_name,
+        )
+
+        # Get timeout from config
+        timeout = 900
+        if self.config and hasattr(self.config, "agent"):
+            timeout = self.config.agent.timeout_seconds
+
+        worker = Worker(role, issue_id, timeout=timeout)
+        runtime = RuntimeSession(
+            session_model, 
+            worker,
+            hook_registry=self.hook_registry,
+            project_root=self.project_root,
+        )
+        self._sessions[session_id] = runtime
+        return runtime
+
+    def get_session(self, session_id: str) -> Optional[RuntimeSession]:
+        return self._sessions.get(session_id)
+
+    def list_sessions(self, issue_id: Optional[str] = None) -> List[RuntimeSession]:
+        if issue_id:
+            return [s for s in self._sessions.values() if s.model.issue_id == issue_id]
+        return list(self._sessions.values())
+
+    def terminate_session(self, session_id: str):
+        session = self.get_session(session_id)
+        if session:
+            session.terminate()
+            # We might want to keep the record for a while, so don't delete immediately
+            # del self._sessions[session_id]

monoco/features/{scheduler → agent}/models.py

@@ -4,14 +4,13 @@ from pydantic import BaseModel, Field
 
 class RoleTemplate(BaseModel):
     name: str = Field(
-        ..., description="Unique identifier for the role (e.g., 'crafter')"
+        ..., description="Unique identifier for the role (e.g., 'Planner')"
     )
     description: str = Field(..., description="Human-readable description of the role")
     trigger: str = Field(
         ..., description="Event that triggers this agent (e.g., 'issue.created')"
     )
     goal: str = Field(..., description="The primary goal/output of this agent")
-    tools: List[str] = Field(default_factory=list, description="List of allowed tools")
     system_prompt: str = Field(
         ..., description="The system prompt template for this agent"
     )
@@ -20,5 +19,9 @@ class RoleTemplate(BaseModel):
     )
 
 
-class SchedulerConfig(BaseModel):
+class AgentRoleConfig(BaseModel):
     roles: List[RoleTemplate] = Field(default_factory=list)
+
+
+# Backward compatibility alias
+SchedulerConfig = AgentRoleConfig

monoco/features/agent/resources/atoms/atom-code-dev.yaml

@@ -0,0 +1,61 @@
+---
+name: atom-code-dev
+type: atom
+domain: code
+description: 代码开发的原子操作 - 调研、实现、测试、文档
+version: 1.0.0
+author: Monoco Toolkit
+
+# 系统级合规规则
+compliance_rules:
+  - rule: "遵循项目代码规范"
+    severity: warning
+  
+  - rule: "优先编写测试"
+    severity: warning
+    mindset: "TDD"
+  
+  - rule: "保持代码简单直观"
+    severity: info
+    mindset: "KISS"
+
+# 原子操作定义
+operations:
+  - name: investigate
+    description: 理解需求与上下文，识别相关代码和依赖
+    reminder: "理解需求后再开始编码，识别相关文件和依赖 Issue"
+    checkpoints:
+      - "阅读并理解 Issue 描述"
+      - "识别相关代码文件"
+      - "检查依赖 Issue 状态"
+      - "评估技术可行性"
+    output: "技术方案草稿、风险清单"
+  
+  - name: implement
+    description: 实现代码变更
+    reminder: "遵循项目代码规范，小步提交，处理边界情况"
+    checkpoints:
+      - "遵循项目代码规范"
+      - "编写/更新必要的文档"
+      - "处理边界情况"
+      - "保持代码可审查性（单次提交 < 400 行）"
+  
+  - name: test
+    description: 运行测试确保代码质量
+    reminder: "所有测试必须通过，检查测试覆盖率"
+    checkpoints:
+      - "编写/更新单元测试"
+      - "运行测试套件 (pytest, cargo test, etc.)"
+      - "修复失败的测试"
+      - "检查测试覆盖率"
+    compliance_rules:
+      - rule: "所有单元测试必须通过后才能提交"
+        severity: error
+  
+  - name: document
+    description: 更新文档
+    reminder: "代码变更必须同步更新文档"
+    checkpoints:
+      - "更新代码注释"
+      - "更新相关文档"
+      - "更新 CHANGELOG（如适用）"

monoco/features/agent/resources/atoms/atom-issue-lifecycle.yaml

@@ -0,0 +1,73 @@
+---
+name: atom-issue-lifecycle
+type: atom
+domain: issue
+description: Issue 生命周期管理的原子操作 - 创建、启动、提交、关闭工作单元
+version: 1.0.0
+author: Monoco Toolkit
+
+# 系统级合规规则（定义一次，全局生效）
+compliance_rules:
+  - rule: "禁止在 main/master 分支直接修改代码"
+    severity: error
+    check: "git branch --show-current"
+    fail_if: "main|master"
+  
+  - rule: "必须使用 feature 分支进行开发"
+    severity: error
+    command: "monoco issue start <ID> --branch"
+  
+  - rule: "提交前必须通过 lint 检查"
+    severity: error
+    command: "monoco issue lint"
+  
+  - rule: "每个 Issue 必须至少包含 2 个 Checkbox"
+    severity: error
+    check: "checkbox_count >= 2"
+  
+  - rule: "Review/Done 阶段必须包含 Review Comments"
+    severity: warning
+    check: "review_comments_section exists"
+
+# 原子操作定义
+operations:
+  - name: create
+    description: 创建新的 Issue 工作单元
+    command: "monoco issue create <type> -t <title>"
+    reminder: "选择合适的类型 (epic/feature/chore/fix)，编写清晰的描述"
+    checkpoints:
+      - "必须包含至少 2 个 Checkbox"
+      - "标题必须与 Front Matter 一致"
+  
+  - name: start
+    description: 启动开发，创建功能分支
+    command: "monoco issue start <ID> --branch"
+    reminder: "确保使用 --branch 创建功能分支，禁止在 main/master 上开发"
+    checkpoints:
+      - "禁止在 main/master 分支直接修改代码"
+      - "必须创建 feature 分支"
+  
+  - name: sync
+    description: 同步文件追踪，记录修改的文件
+    command: "monoco issue sync-files"
+    reminder: "定期同步文件追踪，保持 Issue 与代码变更同步"
+  
+  - name: lint
+    description: 检查 Issue 合规性
+    command: "monoco issue lint"
+    reminder: "提交前必须运行 lint 检查"
+    checkpoints:
+      - "必须通过所有合规检查"
+  
+  - name: submit
+    description: 提交代码进行评审
+    command: "monoco issue submit <ID>"
+    reminder: "确保所有测试通过，lint 无错误后再提交"
+    checkpoints:
+      - "所有单元测试必须通过"
+      - "必须通过 lint 检查"
+  
+  - name: close
+    description: 关闭 Issue，清理环境
+    command: "monoco issue close <ID> --solution completed --prune"
+    reminder: "代码合并后及时关闭 Issue，清理 feature 分支"

monoco/features/agent/resources/atoms/atom-knowledge.yaml

@@ -0,0 +1,55 @@
+---
+name: atom-knowledge
+type: atom
+domain: knowledge
+description: 知识管理的原子操作 - 捕获、处理、转化、归档
+version: 1.0.0
+author: Monoco Toolkit
+
+# 系统级合规规则
+compliance_rules:
+  - rule: "Memo 是临时的，不应无限堆积"
+    severity: warning
+  
+  - rule: "可执行的想法必须转为 Issue 追踪"
+    severity: error
+
+# 原子操作定义
+operations:
+  - name: capture
+    description: 快速捕获 fleeting ideas
+    command: "monoco memo add <content>"
+    reminder: "保持简洁，不中断当前工作流，添加上下文"
+    checkpoints:
+      - "使用简洁的描述"
+      - "添加上下文（-c file:line 如适用）"
+      - "不中断当前任务流"
+  
+  - name: process
+    description: 定期处理 Memo，评估价值
+    command: "monoco memo list"
+    reminder: "定期回顾和分类 Memo（建议每周）"
+    checkpoints:
+      - "运行 monoco memo list 查看所有 Memo"
+      - "评估每个 Memo 的价值"
+      - "分类：可执行 / 纯参考 / 无价值"
+  
+  - name: convert
+    description: 将可执行的 Memo 转化为 Issue
+    command: "monoco issue create <type> -t <title>"
+    reminder: "有价值的想法尽快转为 Issue"
+    checkpoints:
+      - "判断 Issue 类型 (feature/chore/fix)"
+      - "编写清晰的描述和验收标准"
+      - "关联原始 Memo"
+    compliance_rules:
+      - rule: "可执行的想法必须转为 Issue 追踪"
+        severity: error
+  
+  - name: archive
+    description: 归档纯参考资料
+    reminder: "纯参考资料归档保存，无价值的直接删除"
+    checkpoints:
+      - "确认 Memo 内容为纯参考资料"
+      - "移动到知识库或文档"
+      - "从 Memo 列表中移除"

monoco/features/agent/resources/atoms/atom-review.yaml

@@ -0,0 +1,60 @@
+---
+name: atom-review
+type: atom
+domain: review
+description: 代码评审的原子操作 - 检出、验证、对抗、反馈
+version: 1.0.0
+author: Monoco Toolkit
+
+# 系统级合规规则
+compliance_rules:
+  - rule: "必须先通过 Engineer 的测试 (Verify)，再进行对抗测试 (Challenge)"
+    severity: error
+  
+  - rule: "必须尝试编写至少一个边界测试用例"
+    severity: warning
+  
+  - rule: "禁止未经测试直接 Approve"
+    severity: error
+
+# 原子操作定义
+operations:
+  - name: checkout
+    description: 检出待评审的代码
+    reminder: "获取待评审的 PR/Branch，确认与 Base 分支的差异"
+    checkpoints:
+      - "检出 PR/Branch"
+      - "确认与 Base 分支的差异"
+      - "检查环境配置"
+  
+  - name: verify
+    description: 验证 Engineer 提交的测试 (White-box)
+    reminder: "先运行 Engineer 编写的测试，验证功能正确性"
+    checkpoints:
+      - "运行 Engineer 编写的单元测试"
+      - "运行集成测试（如适用）"
+      - "检查测试覆盖率报告"
+    compliance_rules:
+      - rule: "如果现有测试失败，直接进入 Reject 流程"
+        severity: error
+  
+  - name: challenge
+    description: 对抗测试，尝试破坏代码 (Black-box / Edge Cases)
+    reminder: "Try to break it - 寻找边界情况和安全漏洞"
+    checkpoints:
+      - "分析代码逻辑，寻找盲区（并发、大/小数值、注入攻击等）"
+      - "编写新的 Challenge Test Cases"
+      - "运行这些新测试"
+    compliance_rules:
+      - rule: "必须尝试编写至少一个边界测试用例"
+        severity: warning
+  
+  - name: feedback
+    description: 提供评审反馈
+    reminder: "明确批准、拒绝或请求修改，提供具体反馈"
+    checkpoints:
+      - "功能是否正确实现"
+      - "代码是否符合设计规范"
+      - "测试是否充分"
+      - "文档是否同步更新"
+      - "是否遵循项目规范"