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

monoco/features/agent/resources/zh/skills/flow_reviewer/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: flow-reviewer
+description: Reviewer 角色的标准化工作流 (Flow Skill)。定义从代码检出、对抗性测试到评审完成的标准操作流程，确保代码质量和流程合规。
+type: flow
+role: reviewer
+version: 1.1.0
+---
+
+# Reviewer Flow
+
+Reviewer 角色的标准化工作流，确保 "Checkout → Verify → Challenge → Review → Decide → Cleanup" 流程。核心理念是**双层防御体系**：Engineer 负责自证 (Verify)，Reviewer 负责对抗 (Challenge)。
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Checkout: 收到评审请求
+
+    Checkout --> Verify: 检出完成
+    Checkout --> Checkout: 检出失败<br/>(环境检查)
+
+    Verify --> Challenge: 现有测试通过
+    Verify --> Verify: 现有测试失败<br/>(记录问题)
+
+    Challenge --> Review: 对抗测试完成
+    Challenge --> Reject: 发现致命漏洞
+
+    Review --> Approve: 代码 & 架构 OK
+    Review --> Reject: 发现质量问题
+
+    Reject --> Checkout: 修复后重审
+
+    Approve --> Cleanup: 批准
+
+    Cleanup --> [*]: 清理完成
+```
+
+## 执行步骤
+
+### 1. Checkout (检出)
+
+- **目标**: 获取待评审的代码
+- **检查点**:
+  - [ ] 检出 PR/Branch
+  - [ ] 确认与 Base 分支的差异
+  - [ ] 检查环境配置
+
+### 2. Verify (验证)
+
+- **目标**: 验证 Engineer 提交的功能正确性和测试覆盖 (White-box)
+- **检查点**:
+  - [ ] 运行 **Engineer 编写的** 单元测试
+  - [ ] 运行集成测试 (如适用)
+  - [ ] 检查测试覆盖率报告
+  - [ ] **决策**: 如果现有测试失败，直接进入 `Reject` 流程。
+
+### 3. Challenge (对抗测试)
+
+- **目标**: 尝试破坏代码，寻找边界情况和安全漏洞 (Black-box / Edge Cases)
+- **思维模式**: "Try to break it"
+- **操作**:
+  1. 分析代码逻辑，寻找 Engineer 视角的盲区（并发、大/小数值、注入攻击等）。
+  2. 编写新的 **Challenge Test Cases**。
+  3. 运行这些新测试。
+- **检查点**:
+  - [ ] **漏洞发现**: 如果新测试导致 Crash 或逻辑错误 -> **Reject** (并将测试用例作为反馈)。
+  - [ ] **鲁棒性验证**: 如果新测试通过 -> **保留测试用例** (提交到代码库) 并进入下一步。
+
+### 4. Review (代码审查)
+
+- **目标**: 检查代码质量、架构设计和可维护性
+- **检查清单**:
+  - [ ] **功能**: 代码是否实现了需求？
+  - [ ] **设计**: 架构是否合理？是否遵循 KISS 原则？
+  - [ ] **可读性**: 命名和注释是否清晰？
+  - [ ] **文档**: 文档是否同步更新？
+  - [ ] **合规**: 是否遵循项目 Lint 规范？
+
+### 5. Decide (决策)
+
+- **目标**: 做出批准或拒绝的决定
+- **选项**:
+  - **Approve**: 代码健壮且符合规范 (包含所有通过的 Challenge Tests)
+  - **Reject**: 需要修改，提供具体反馈 (附带失败的 Test Case 或 Log)
+  - **Request Changes**: 小问题，可快速修复
+
+### 6. Cleanup (清理)
+
+- **目标**: 完成评审后的环境清理
+- **检查点**:
+  - [ ] 提交新增的测试用例 (如有)
+  - [ ] 删除本地临时分支
+  - [ ] 更新 Issue 状态
+  - [ ] 记录评审意见到 Review Comments
+
+## 决策分支
+
+| 条件                      | 动作                                    |
+| ------------------------- | --------------------------------------- |
+| 现有测试 (Verify) 失败    | Reject，要求 Engineer 修复              |
+| 对抗测试 (Challenge) 崩溃 | Reject，提交该测试用例证明漏洞          |
+| 代码风格问题              | Request Changes 或提供建议              |
+| 设计问题                  | Reject，要求重新设计                    |
+| 一切正常                  | Approve，并合并价值高的 Challenge Tests |
+
+## 评审意见模板
+
+```markdown
+## Review Comments
+
+### 🛡️ Challenge Reports
+
+- [Pass/Fail] Test Case: `test_concurrency_limit`
+- [Pass/Fail] Test Case: `test_invalid_inputs`
+
+### ✅ 优点
+
+-
+
+### ⚠️ 建议
+
+-
+
+### ❌ 必须修改
+
+-
+
+### 📝 其他
+
+-
+```
+
+## 合规要求
+
+- **必须**: 先通过 Engineer 的测试 (Verify)，再进行对抗测试 (Challenge)
+- **必须**: 试图编写至少一个边界测试用例
+- **禁止**: 未经测试直接 Approve

monoco/features/agent/worker.py

@@ -8,12 +8,14 @@ class Worker:
     Represents an active or pending agent session assigned to a specific role and issue.
     """
 
-    def __init__(self, role: RoleTemplate, issue_id: str):
+    def __init__(self, role: RoleTemplate, issue_id: str, timeout: Optional[int] = None):
         self.role = role
         self.issue_id = issue_id
+        self.timeout = timeout
         self.status = "pending"  # pending, running, suspended, terminated
         self.process_id: Optional[int] = None
         self._process = None
+        self.start_at: Optional[float] = None
 
     def start(self, context: Optional[dict] = None):
         """
@@ -26,6 +28,8 @@ class Worker:
         print(f"Starting worker {self.role.name} for issue {self.issue_id}")
 
         try:
+            import time
+            self.start_at = time.time()
             self._execute_work(context)
             self.status = "running"
         except Exception as e:
@@ -97,6 +101,23 @@ class Worker:
         if not self._process:
             return self.status
 
+        # Check timeout
+        if (
+            self.status == "running"
+            and self.timeout
+            and self.start_at
+        ):
+            import time
+
+            elapsed = time.time() - self.start_at
+            if elapsed > self.timeout:
+                print(
+                    f"\n[{self.role.name}] [bold red]Timeout exceeded[/bold red] ({self.timeout}s). Terminating process..."
+                )
+                self.stop()
+                self.status = "timeout"
+                return self.status
+
         returncode = self._process.poll()
         if returncode is None:
             return "running"
@@ -118,14 +139,29 @@ class Worker:
 
     def stop(self):
         """
-        Stop the worker session.
+        Stop the worker session and kill the process if running.
         """
         if self.status == "terminated":
             return
 
         print(f"Stopping worker {self.role.name} for issue {self.issue_id}")
+
+        if self._process:
+            try:
+                # Try graceful termination
+                self._process.terminate()
+                # Wait a bit
+                try:
+                    self._process.wait(timeout=2)
+                except Exception:
+                    # Force kill if still running
+                    self._process.kill()
+            except Exception as e:
+                print(f"Error stopping process: {e}")
+
         self.status = "terminated"
         self.process_id = None
+        self._process = None
 
     def __repr__(self):
         return (

monoco/features/glossary/adapter.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+from typing import Dict
+from monoco.core.feature import MonocoFeature, IntegrationData
+
+
+class GlossaryFeature(MonocoFeature):
+    @property
+    def name(self) -> str:
+        return "glossary"
+
+    def initialize(self, root: Path, config: Dict) -> None:
+        # Glossary does not require file initialization in the workspace
+        pass
+
+    def integrate(self, root: Path, config: Dict) -> IntegrationData:
+        # Determine language from config, default to 'en'
+        lang = config.get("i18n", {}).get("source_lang", "en")
+
+        # Resource path: monoco/features/glossary/resources/{lang}/AGENTS.md
+        base_dir = Path(__file__).parent / "resources"
+
+        # Try specific language, fallback to 'en'
+        prompt_file = base_dir / lang / "AGENTS.md"
+        if not prompt_file.exists():
+            prompt_file = base_dir / "en" / "AGENTS.md"
+
+        content = ""
+        if prompt_file.exists():
+            content = prompt_file.read_text(encoding="utf-8").strip()
+
+        return IntegrationData(system_prompts={"Glossary": content})

monoco/features/glossary/config.py

@@ -0,0 +1,5 @@
+from dataclasses import dataclass
+
+@dataclass
+class GlossaryConfig:
+    enabled: bool = True

monoco/features/glossary/resources/en/AGENTS.md

@@ -0,0 +1,29 @@
+### Glossary
+
+#### Monoco Glossary
+
+##### Core Architecture Metaphor: "Linux Distro"
+
+| Term             | Definition                                                                                          | Metaphor                            |
+| :--------------- | :-------------------------------------------------------------------------------------------------- | :---------------------------------- |
+| **Monoco**       | The Agent Operating System Distribution. Managed policy, workflow, and package system.              | **Distro** (e.g., Ubuntu, Arch)     |
+| **Kimi CLI**     | The core runtime execution engine. Handles LLM interaction, tool execution, and process management. | **Kernel** (Linux Kernel)           |
+| **Session**      | An initialized instance of the Agent Kernel, managed by Monoco. Has state and context.              | **Init System / Daemon** (systemd)  |
+| **Issue**        | An atomic unit of work with state (Open/Done) and strict lifecycle.                                 | **Unit File** (systemd unit)        |
+| **Skill**        | A package of capabilities (tools, prompts, flows) that extends the Agent.                           | **Package** (apt/pacman package)    |
+| **Context File** | Configuration files (e.g., `GEMINI.md`, `AGENTS.md`) defining environment rules and preferences.    | **Config** (`/etc/config`)          |
+| **Agent Client** | The user interface connecting to Monoco (CLI, VSCode, Zed).                                         | **Desktop Environment** (GNOME/KDE) |
+
+##### Key Concepts
+
+###### Context File
+
+Files like `GEMINI.md` that provide the "Constitution" for the Agent. They define the role, scope, and behavioral policies of the Agent within a specific context (Root, Directory, Project).
+
+###### Headless
+
+Monoco is designed to run without a native GUI. It exposes its capabilities via standard protocols (LSP, ACP) to be consumed by various Clients (IDEs, Terminals).
+
+###### Universal Shell
+
+The concept that the CLI is the universal interface for all workflows. Monoco acts as an intelligent layer over the shell.

monoco/features/glossary/resources/en/skills/monoco_glossary/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: monoco-glossary
+description: Official Monoco Glossary and Operational Laws
+tags: [core, definition]
+type: standard
+version: 1.0.0
+---
+
+# Monoco Glossary
+
+## Core Architecture Metaphor: "Linux Distro"
+
+| Term             | Definition                                                                                          | Metaphor                            |
+| :--------------- | :-------------------------------------------------------------------------------------------------- | :---------------------------------- |
+| **Monoco**       | The Agent Operating System Distribution. Managed policy, workflow, and package system.              | **Distro** (e.g., Ubuntu, Arch)     |
+| **Kimi CLI**     | The core runtime execution engine. Handles LLM interaction, tool execution, and process management. | **Kernel** (Linux Kernel)           |
+| **Session**      | An initialized instance of the Agent Kernel, managed by Monoco. Has state and context.              | **Init System / Daemon** (systemd)  |
+| **Issue**        | An atomic unit of work with state (Open/Done) and strict lifecycle.                                 | **Unit File** (systemd unit)        |
+| **Skill**        | A package of capabilities (tools, prompts, flows) that extends the Agent.                           | **Package** (apt/pacman package)    |
+| **Context File** | Configuration files (e.g., `GEMINI.md`, `AGENTS.md`) defining environment rules and preferences.    | **Config** (`/etc/config`)          |
+| **Agent Client** | The user interface connecting to Monoco (CLI, VSCode, Zed).                                         | **Desktop Environment** (GNOME/KDE) |
+
+## Key Concepts
+
+### Context File
+
+Files like `GEMINI.md` that provide the "Constitution" for the Agent. They define the role, scope, and behavioral policies of the Agent within a specific context (Root, Directory, Project).
+
+### Headless
+
+Monoco is designed to run without a native GUI. It exposes its capabilities via standard protocols (LSP, ACP) to be consumed by various Clients (IDEs, Terminals).
+
+### Universal Shell
+
+The concept that the CLI is the universal interface for all workflows. Monoco acts as an intelligent layer over the shell.

monoco/features/glossary/resources/zh/AGENTS.md

@@ -0,0 +1,29 @@
+### 术语表
+
+#### Monoco 术语表
+
+##### 核心架构隐喻: "Linux 发行版"
+
+| 术语 | 定义 | 隐喻 |
+| :--- | :--- | :--- |
+| **Monoco** | 智能体操作系统发行版。管理策略、工作流和包系统。 | **发行版** (如 Ubuntu, Arch) |
+| **Kimi CLI** | 核心运行时执行引擎。处理 LLM 交互、工具执行和进程管理。 | **内核** (Linux Kernel) |
+| **Session** | 由 Monoco 管理的智能体内核初始化实例。具有状态和上下文。 | **初始化系统/守护进程** (systemd) |
+| **Issue** | 具有状态（Open/Done）和严格生命周期的原子工作单元。 | **单元文件** (systemd unit) |
+| **Skill** | 扩展智能体功能的工具、提示词和流程包。 | **软件包** (apt/pacman package) |
+| **Context File** | 定义环境规则和行为偏好的配置文件（如 `GEMINI.md`, `AGENTS.md`）。 | **配置** (`/etc/config`) |
+| **Agent Client** | 连接 Monoco 的用户界面（CLI, VSCode, Zed）。 | **桌面环境** (GNOME/KDE) |
+
+##### 关键概念
+
+###### Context File
+
+像 `GEMINI.md` 这样的文件，为智能体提供"宪法"。它们定义了特定上下文（根目录、目录、项目）中智能体的角色、范围和行为策略。
+
+###### Headless
+
+Monoco 设计为无需原生 GUI 即可运行。它通过标准协议（LSP, ACP）暴露其能力，供各种客户端（IDE、终端）使用。
+
+###### Universal Shell
+
+CLI 是所有工作流的通用接口的概念。Monoco 作为 shell 的智能层。

monoco/features/glossary/resources/zh/skills/monoco_glossary/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: monoco-glossary
+description: Monoco 官方术语表和操作法则
+tags: [core, definition]
+type: standard
+version: 1.0.0
+---
+
+# Monoco 术语表
+
+## 核心架构隐喻: "Linux 发行版"
+
+| 术语 | 定义 | 隐喻 |
+| :--- | :--- | :--- |
+| **Monoco** | 智能体操作系统发行版。管理策略、工作流和包系统。 | **发行版** (如 Ubuntu, Arch) |
+| **Kimi CLI** | 核心运行时执行引擎。处理 LLM 交互、工具执行和进程管理。 | **内核** (Linux Kernel) |
+| **Session** | 由 Monoco 管理的智能体内核初始化实例。具有状态和上下文。 | **初始化系统/守护进程** (systemd) |
+| **Issue** | 具有状态（Open/Done）和严格生命周期的原子工作单元。 | **单元文件** (systemd unit) |
+| **Skill** | 扩展智能体功能的工具、提示词和流程包。 | **软件包** (apt/pacman package) |
+| **Context File** | 定义环境规则和行为偏好的配置文件（如 `GEMINI.md`, `AGENTS.md`）。 | **配置** (`/etc/config`) |
+| **Agent Client** | 连接 Monoco 的用户界面（CLI, VSCode, Zed）。 | **桌面环境** (GNOME/KDE) |
+
+## 关键概念
+
+### Context File
+
+像 `GEMINI.md` 这样的文件，为智能体提供"宪法"。它们定义了特定上下文（根目录、目录、项目）中智能体的角色、范围和行为策略。
+
+### Headless
+
+Monoco 设计为无需原生 GUI 即可运行。它通过标准协议（LSP, ACP）暴露其能力，供各种客户端（IDE、终端）使用。
+
+### Universal Shell
+
+CLI 是所有工作流的通用接口的概念。Monoco 作为 shell 的智能层。

monoco/features/i18n/resources/en/skills/i18n_scan_workflow/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: i18n-scan-workflow
+description: I18n Scan Workflow (Flow Skill). Defines the standard operational process from scanning missing translations to generating translation tasks, ensuring multilingual documentation quality.
+type: flow
+domain: i18n
+version: 1.0.0
+---
+
+# I18n Scan Workflow
+
+Standardized workflow for I18n scanning, ensuring the "Scan → Identify → Generate Tasks" process.
+
+## Workflow State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Scan: Trigger scan
+    
+    Scan --> Identify: Scan completed
+    Scan --> Scan: Configuration error<br/>(fix configuration)
+    
+    Identify --> GenerateTasks: Missing found
+    Identify --> [*]: No missing<br/>(completed)
+    
+    GenerateTasks --> [*]: Task generation completed
+```
+
+## Execution Steps
+
+### 1. Scan (Scanning)
+
+- **Goal**: Scan all documents in the project, identify translation coverage
+- **Input**: Project files, i18n configuration
+- **Output**: Scan report
+- **Checkpoints**:
+  - [ ] Check i18n configuration in `.monoco/config.yaml`
+  - [ ] Run `monoco i18n scan`
+  - [ ] Confirm source and target language settings are correct
+  - [ ] Verify exclusion rules (.gitignore, build directories, etc.)
+
+### 2. Identify (Identify Missing)
+
+- **Goal**: Analyze scan results, identify specific missing translations
+- **Strategy**: Compare source and target files
+- **Checkpoints**:
+  - [ ] List all source files with missing translations
+  - [ ] Identify missing target languages
+  - [ ] Assess impact scope of missing translations
+  - [ ] Sort by priority (core documents first)
+
+### 3. Generate Tasks (Generate Tasks)
+
+- **Goal**: Create tracking tasks for missing translations
+- **Strategy**: Create Issue or memo based on missing status
+- **Checkpoints**:
+  - [ ] Create Feature Issue for core document missing translations
+  - [ ] Create Memo reminder for secondary document missing translations
+  - [ ] Annotate file paths requiring translation in the Issue
+  - [ ] Set reasonable priority and deadline
+
+## Decision Branches
+
+| Condition | Action |
+|-----------|--------|
+| Configuration error | Fix `.monoco/config.yaml`, rescan |
+| No missing translations | Process completed, no further action needed |
+| Large amount missing | Create Epic, split into multiple Features |
+| Critical document missing | High priority, create Issue immediately |
+
+## Compliance Requirements
+
+- **Required**: Verify i18n configuration is correct before scanning
+- **Required**: All core documents must have corresponding translations
+- **Recommended**: Run scans regularly (e.g., weekly)
+- **Recommended**: Bind translation tasks with feature development
+
+## Related Commands
+
+```bash
+# Scan for missing translations
+monoco i18n scan
+
+# Create translation task
+monoco issue create feature -t "Translate {filename} to {lang}"
+
+# Add memo
+monoco memo add "Needs translation: {filepath}"
+```
+
+## Output Example
+
+After scanning completes, a report like the following should be generated:
+
+```
+I18n Scan Report
+================
+Source Language: en
+Target Languages: zh, ja
+
+Missing Translations:
+- docs/guide.md → zh/guide.md [MISSING]
+- docs/api.md → ja/api.md [MISSING]
+
+Coverage: 85%
+```

monoco/features/i18n/resources/en/{SKILL.md → skills/monoco_i18n/SKILL.md}

@@ -1,6 +1,8 @@
 ---
 name: monoco-i18n
 description: Internationalization quality control for documentation. Ensures multi-language documentation stays synchronized.
+type: standard
+version: 1.0.0
 ---
 
 # Documentation I18n

monoco/features/i18n/resources/zh/{SKILL.md → skills/monoco_i18n/SKILL.md}

@@ -1,6 +1,8 @@
 ---
 name: monoco-i18n
 description: 文档国际化质量控制。确保多语言文档保持同步。
+type: standard
+version: 1.0.0
 ---
 
 # 文档国际化

monoco/features/issue/core.py

@@ -515,7 +515,7 @@ def update_issue(
     temp_meta = IssueMetadata(**data)
 
     # Use engine to validate the transition
-    engine.validate_transition(
+    transition = engine.validate_transition(
         from_status=current_status,
         from_stage=current_stage,
         to_status=target_status,
@@ -659,6 +659,8 @@ def update_issue(
     path.write_text(new_content)
 
     # 3. Handle physical move if status changed
+    # Save old path before move for git tracking
+    old_path_before_move = path
     if status and status != current_status:
         # Move file
         prefix = issue_id.split("-")[0].upper()
@@ -702,17 +704,16 @@ def update_issue(
         # Only auto-commit if we're in a git repo
         git_service = IssueGitService(project_root)
         if git_service.is_git_repository():
-            # Determine old path if status changed (file was moved)
+            # Use the saved old path before file move for git tracking
             old_path_for_git = None
-            if status and status != current_status:
-                # The original path before move
-                old_path_for_git = find_issue_path(issues_root, issue_id)
+            if status and status != current_status and old_path_before_move != path:
+                old_path_for_git = old_path_before_move
 
             commit_result = git_service.commit_issue_change(
                 issue_id=issue_id,
                 action=action,
                 issue_file_path=path,
-                old_file_path=old_path_for_git if old_path_for_git != path else None,
+                old_file_path=old_path_for_git,
                 no_commit=no_commit,
             )
             # Attach commit result to metadata for optional inspection
@@ -721,9 +722,47 @@ def update_issue(
     # Update returned metadata with final absolute path
     updated_meta.path = str(path.absolute())
     updated_meta.actions = get_available_actions(updated_meta)
+
+    # Execute Post Actions (Trigger)
+    if transition and hasattr(transition, "post_actions") and transition.post_actions:
+        _execute_post_actions(transition.post_actions, updated_meta)
+
     return updated_meta
 
 
+def _execute_post_actions(actions: List[str], meta: IssueMetadata):
+    """
+    Execute a list of shell commands as post-actions.
+    Supports template substitution with issue metadata.
+    """
+    import shlex
+    import subprocess
+    from rich.console import Console
+    
+    console = Console()
+    data = meta.model_dump(mode="json")
+    
+    for action in actions:
+        try:
+            # Safe template substitution
+            cmd = action.format(**data)
+        except KeyError as e:
+            console.print(f"[yellow]Trigger Warning:[/yellow] Missing key for template '{action}': {e}")
+            continue
+            
+        console.print(f"[bold cyan]Triggering:[/bold cyan] {cmd}")
+        
+        args = shlex.split(cmd)
+        
+        try:
+            # Run in foreground to allow interaction if needed (e.g. agent output)
+            subprocess.run(args, check=True)
+        except subprocess.CalledProcessError as e:
+            console.print(f"[red]Trigger Failed:[/red] Command '{cmd}' exited with code {e.returncode}")
+        except Exception as e:
+            console.print(f"[red]Trigger Error:[/red] {e}")
+
+
 def start_issue_isolation(
     issues_root: Path, issue_id: str, mode: str, project_root: Path
 ) -> IssueMetadata:

monoco/features/issue/engine/machine.py

@@ -134,13 +134,14 @@ class StateMachine:
         to_stage: Optional[str],
         solution: Optional[str] = None,
         meta: Optional[IssueMetadata] = None,
-    ) -> None:
+    ) -> Optional[TransitionConfig]:
         """
         Validate if a transition is allowed. Raises ValueError if not.
         If meta is provided, also validates criticality-based policies.
+        Returns the TransitionConfig if a transition occurred, None if no change.
         """
         if from_status == to_status and from_stage == to_stage:
-            return  # No change is always allowed (unless we want to enforce specific updates)
+            return None  # No change is always allowed (unless we want to enforce specific updates)
 
         transition = self.find_transition(
             from_status, from_stage, to_status, to_stage, solution
@@ -160,6 +161,8 @@ class StateMachine:
         # Criticality-based policy checks
         if meta and meta.criticality:
             self._validate_criticality_policy(meta, from_stage, to_stage)
+            
+        return transition
 
     def _validate_criticality_policy(
         self,

monoco/features/issue/models.py

@@ -67,6 +67,7 @@ class IssueType(str, Enum):
     FEATURE = "feature"
     CHORE = "chore"
     FIX = "fix"
+    ARCH = "arch"
 
 
 class IssueStatus(str, Enum):