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

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

@@ -0,0 +1,259 @@
+---
+name: monoco_workflow_agent_planner
+description: Planner 角色的标准化工作流 (Flow Skill)，负责分析、设计、规划和交接。
+type: workflow
+role: planner
+version: 1.0.0
+author: Monoco Toolkit
+---
+
+# flow_planner
+
+Planner 角色的标准化工作流 (Flow Skill)，负责分析、设计、规划和交接。
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Analyze: 接收输入
+    
+    Analyze --> Design: 需求清晰
+    Analyze --> Analyze: 信息不足<br/>(收集更多)
+    
+    Design --> Plan: 设计完成
+    Design --> Design: 方案冲突<br/>(重新设计)
+    
+    Plan --> Handoff: 规划完成
+    Plan --> Plan: 依赖复杂<br/>(调整计划)
+    
+    Handoff --> [*]: 交接成功
+```
+
+---
+
+## 执行步骤
+
+### 1. Analyze (分析)
+
+**目标**: 充分理解需求和上下文
+
+**入口条件**:
+- 接收到 Memo 或 Issue 输入
+- 或检测到需要细化的任务
+
+**自动执行检查点**:
+
+- [ ] **读取输入**: 读取 Memo 或 Issue 的完整内容
+- [ ] **识别上下文**: 识别相关代码文件、模块和依赖
+- [ ] **检查架构**: 检查现有架构和技术栈
+- [ ] **评估范围**: 评估影响范围和复杂度
+- [ ] **记录发现**: 将分析结果记录到 Issue 或创建新的研究 Issue
+
+**退出条件**:
+- 需求清晰明确 → 进入 Design
+- 信息不足 → 返回 Analyze，收集更多信息
+
+**命令参考**:
+```bash
+# 读取 Memo
+monoco memo list
+monoco memo open <id>
+
+# 读取 Issue
+cat Issues/<type>/<status>/<issue-file>.md
+
+# 检查相关代码
+grep -r "pattern" monoco/
+```
+
+---
+
+### 2. Design (设计)
+
+**目标**: 产出架构设计方案
+
+**入口条件**:
+- Analyze 阶段完成，需求清晰
+
+**自动执行检查点**:
+
+- [ ] **系统架构**: 设计系统架构和组件关系
+- [ ] **继承性评估**: 评估与现有系统的兼容性
+- [ ] **安全评估**: 识别安全风险和缓解措施
+- [ ] **性能评估**: 评估性能影响和优化方案
+- [ ] **可维护性**: 考虑可维护性和扩展性
+- [ ] **设计文档**: 编写架构设计文档 (Architecture Decision Record)
+
+**退出条件**:
+- 设计完成且通过自评 → 进入 Plan
+- 架构冲突 → 返回 Design，重新设计方案
+
+**设计输出模板**:
+```markdown
+## Architecture Design
+
+### 1. 系统架构
+[架构图或描述]
+
+### 2. 组件关系
+- Component A → Component B
+- 接口定义: ...
+
+### 3. 技术选型
+- 语言/框架: ...
+- 依赖库: ...
+
+### 4. 风险评估
+| 风险 | 影响 | 缓解措施 |
+|------|------|----------|
+| ...  | ...  | ...      |
+```
+
+---
+
+### 3. Plan (规划)
+
+**目标**: 制定可执行的任务计划
+
+**入口条件**:
+- Design 阶段完成，架构方案确定
+
+**自动执行检查点**:
+
+- [ ] **任务分解**: 将工作分解为可执行的单元 (Issue/Feature)
+- [ ] **依赖分析**: 识别任务间的依赖关系
+- [ ] **工作量估算**: 估算每个任务的工作量和优先级
+- [ ] **创建 Issue**: 使用 `monoco issue create` 创建子任务
+- [ ] **更新父 Issue**: 更新原始 Issue 的任务列表和依赖
+
+**退出条件**:
+- 规划完成 → 进入 Handoff
+- 依赖复杂 → 返回 Plan，调整任务分解
+
+**命令参考**:
+```bash
+# 创建子任务
+monoco issue create feature -t "子任务标题" --parent <parent-id>
+
+# 更新 Issue
+monoco issue edit <id> --add-task "任务描述"
+```
+
+---
+
+### 4. Handoff (交接)
+
+**目标**: 将任务交接给 Engineer
+
+**入口条件**:
+- Plan 阶段完成，任务已分解为可执行单元
+
+**自动执行检查点**:
+
+- [ ] **上下文摘要**: 生成完整的上下文摘要 (Context Summary)
+- [ ] **更新 Issue**: 更新 Issue 描述，包含技术设计和执行步骤
+- [ ] **标记状态**: 标记 Issue 为 `ready_for_dev`
+- [ ] **通知 Engineer**: 如系统支持，通知 Engineer 有新任务
+
+**交接文档模板**:
+```markdown
+## Handoff Document
+
+### Context
+[任务背景和目标的简要描述]
+
+### Architecture
+[架构设计的关键点]
+
+### Implementation Guide
+[实现步骤和注意事项]
+
+### Acceptance Criteria
+- [ ] 验收标准 1
+- [ ] 验收标准 2
+
+### Related Files
+- `path/to/file1.py`
+- `path/to/file2.py`
+
+### Dependencies
+- 依赖 Issue: #XXX
+- 阻塞 Issue: #YYY
+```
+
+**退出条件**:
+- 交接成功 → 工作流结束
+
+---
+
+## 决策分支
+
+| 条件 | 动作 | 说明 |
+|------|------|------|
+| 信息不足 | 返回 Analyze | 收集更多信息，可能创建 Spike Issue |
+| 架构冲突 | 返回 Design | 重新设计方案，记录决策理由 |
+| 依赖复杂 | 返回 Plan | 调整任务分解，简化依赖关系 |
+| 规划完成 | 进入 Handoff | 交接给 Engineer |
+
+---
+
+## 与 Engineer 的协作
+
+```
+Planner (Analyze → Design → Plan)
+         ↓
+    创建/细化 Issue
+         ↓
+Engineer (Investigate → Code → Test → Submit)
+         ↓
+Reviewer (Review → Approve/Reject)
+         ↓
+    [如需要] → 返回 Planner 重新规划
+```
+
+### 协作接口
+
+**Planner → Engineer**:
+- 输出: 细化的 Issue + 架构设计文档
+- 格式: Issue 描述中包含 "## Implementation Guide" 章节
+- 标记: Issue 标记为 `ready_for_dev`
+
+**Engineer → Planner**:
+- 触发: Engineer 发现需求不清或架构问题
+- 动作: 标记 Issue 为 `needs_refine`，Planner 重新介入
+
+---
+
+## 使用方式
+
+### 手动触发
+
+```bash
+# 以 Planner 角色运行
+monoco agent run --role Planner --input Issues/Features/open/FEAT-XXXX.md
+```
+
+### 自动触发
+
+当满足以下条件时自动触发:
+1. 新 Memo 创建且包含 `#plan` 标签
+2. Issue 被标记为 `needs_refine`
+3. Epic 创建后需要分解为 Features
+
+---
+
+## 最佳实践
+
+1. **Evidence Based**: 所有架构决策必须有代码或文档证据支持
+2. **Incremental Design**: 优先采用增量式设计，避免过度设计
+3. **Clear Boundaries**: 明确模块边界和接口契约
+4. **Document First**: 先写设计文档，再创建实现任务
+5. **Review Loop**: 复杂设计应经过 Review 后再交接
+
+---
+
+## 相关资源
+
+- Role 定义: `monoco/features/agent/resources/roles/planner.yaml`
+- Engineer Flow: `.agent/skills/flow_engineer/SKILL.md`
+- Reviewer Flow: `.agent/skills/flow_reviewer/SKILL.md`

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

@@ -0,0 +1,137 @@
+---
+name: monoco_workflow_agent_reviewer
+description: Reviewer 角色的标准化工作流 (Flow Skill)。定义从代码检出、对抗性测试到评审完成的标准操作流程，确保代码质量和流程合规。
+type: workflow
+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/session.py

@@ -25,6 +25,7 @@ class Session(BaseModel):
     branch_name: str = Field(
         ..., description="Git branch name associated with this session"
     )
+    pid: Optional[int] = Field(default=None, description="Process ID of the worker")
     created_at: datetime = Field(default_factory=datetime.now)
     updated_at: datetime = Field(default_factory=datetime.now)
     # History could be a list of logs or pointers to git commits
@@ -37,22 +38,33 @@ class RuntimeSession:
     """
 
     def __init__(
-        self, 
-        session_model: Session, 
-        worker: Worker,
+        self,
+        session_model: Session,
+        worker: Optional[Worker],
         hook_registry: Optional[HookRegistry] = None,
         project_root: Optional[Path] = None,
+        save_callback: Optional[callable] = None,
     ):
         self.model = session_model
         self.worker = worker
         self.hook_registry = hook_registry or get_registry()
         self.project_root = project_root or find_monoco_root()
+        self.save_callback = save_callback
+
+    def _save(self):
+        if self.save_callback:
+            self.save_callback(self.model)
 
     def _create_hook_context(self) -> HookContext:
         """Create a HookContext from the current session state."""
         return HookContext.from_runtime_session(self, self.project_root)
 
     def start(self, context: Optional[dict] = None):
+        if not self.worker:
+            raise RuntimeError(
+                "Cannot start session in observer mode (no worker attached)"
+            )
+
         print(
             f"Session {self.model.id}: Starting worker on branch {self.model.branch_name}"
         )
@@ -64,50 +76,83 @@ class RuntimeSession:
             # Execute on_session_start hooks
             hook_context = self._create_hook_context()
             self.hook_registry.execute_on_session_start(hook_context)
-            
+
             self.worker.start(context)
             # Async mode: we assume it started running.
             # Use poll or refresh_status to check later.
             self.model.status = "running"
+            self.model.pid = self.worker.process_id
         except Exception:
             self.model.status = "failed"
             raise
         finally:
             self.model.updated_at = datetime.now()
+            self._save()
 
     def refresh_status(self) -> str:
         """
         Polls the worker and updates the session model status.
         """
-        worker_status = self.worker.poll()
-        self.model.status = worker_status
+        if self.worker:
+            worker_status = self.worker.poll()
+            self.model.status = worker_status
+        else:
+            # Observer mode
+            if self.model.pid:
+                try:
+                    import os
+
+                    # Check if process exists.
+                    # kill(pid, 0) does not send a signal but raises OSError if pid missing
+                    os.kill(self.model.pid, 0)
+                    # If we are here, process exists. We assume running if it was running.
+                    # We can't detect "suspended" easily without psutil.
+                    if self.model.status == "terminated":
+                        # If we thought it was terminated but it's alive, maybe update?
+                        # Or keep as terminated? Let's assume running if found.
+                        pass
+                except OSError:
+                    self.model.status = "terminated"
+            else:
+                self.model.status = "terminated"
+
         self.model.updated_at = datetime.now()
-        return worker_status
+        self._save()
+        return self.model.status
 
     def suspend(self):
+        if not self.worker:
+            raise RuntimeError("Cannot suspend session in observer mode")
+
         print(f"Session {self.model.id}: Suspending worker")
         self.worker.stop()
         self.model.status = "suspended"
         self.model.updated_at = datetime.now()
+        self._save()
         # In real impl, ensure git commit of current state?
 
     def resume(self):
+        if not self.worker:
+            raise RuntimeError("Cannot resume session in observer mode")
+
         print(f"Session {self.model.id}: Resuming worker")
         self.worker.start()  # In real impl, might need to re-init process
 
         # Async mode: assume running
         self.model.status = "running"
+        self.model.pid = self.worker.process_id
         self.model.updated_at = datetime.now()
+        self._save()
 
     def terminate(self):
         print(f"Session {self.model.id}: Terminating")
-        
+
         # Execute on_session_end hooks before stopping worker
         # This allows hooks to perform cleanup while session context is still valid
         try:
             hook_context = self._create_hook_context()
             results = self.hook_registry.execute_on_session_end(hook_context)
-            
+
             # Log hook results
             for result in results:
                 if result.status == "failure":
@@ -115,7 +160,10 @@ class RuntimeSession:
         except Exception as e:
             # Don't let hook errors prevent session termination
             print(f"  Hook execution error: {e}")
-        
-        self.worker.stop()
+
+        if self.worker:
+            self.worker.stop()
+
         self.model.status = "terminated"
         self.model.updated_at = datetime.now()
+        self._save()

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/artifact/adapter.py

@@ -0,0 +1,33 @@
+from pathlib import Path
+from typing import Dict
+from monoco.core.loader import FeatureModule, FeatureMetadata
+from monoco.core.feature import IntegrationData
+
+
+class ArtifactFeature(FeatureModule):
+    """Artifact management feature module."""
+
+    @property
+    def metadata(self) -> FeatureMetadata:
+        return FeatureMetadata(
+            name="artifact",
+            version="1.0.0",
+            description="Artifact management system for Monoco",
+            dependencies=["core"],
+            priority=20,
+        )
+
+    def integrate(self, root: Path, config: Dict) -> IntegrationData:
+        """Provide integration data for agent environment."""
+        lang = config.get("i18n", {}).get("source_lang", "zh")
+        base_dir = Path(__file__).parent / "resources"
+        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={"Artifacts & Mailroom": content})

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

@@ -0,0 +1,14 @@
+# Artifacts & Mailroom
+
+Monoco Artifacts 系统提供了多模态产物的生命周期管理能力，包括：
+
+1. **内容寻址存储 (CAS)**: 所有产物存储在全局池 `~/.monoco/artifacts` 中，基于内容的 SHA256 哈希值进行寻址和去重。
+2. **自动化摄取 (Mailroom)**: 通过监听 `.monoco/dropzone/` 目录，自动触发文档（Office, PDF 等）到 WebP 的转换流程。
+3. **环境追踪**: 自动探测系统中的 `LibreOffice`, `PyMuPDF` 等工具链。
+4. **元数据管理**: 项目本地维护 `manifest.jsonl`，记录所有产物的类型、哈希及创建时间。
+
+### 常用操作建议
+
+- **上传文档**: 建议将原始文档放入 `.monoco/dropzone/`，等待 Mailroom 自动完成转换并注册为 Artifact。
+- **查看产物**: 检查 `.monoco/artifacts/manifest.jsonl` 获取当前可用的产物列表。
+- **引用产物**: 在多模态分析时，可以使用产物的 ID 或本地软链接路径。