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

monoco/features/agent/manager.py

@@ -25,22 +25,56 @@ class SessionManager:
         self._sessions: Dict[str, RuntimeSession] = {}
         self.project_root = project_root or find_monoco_root()
         self.config = config
-        
+
+        self.sessions_dir = self.project_root / ".monoco" / "sessions"
+        self.sessions_dir.mkdir(parents=True, exist_ok=True)
+
         # Initialize hook registry
         self.hook_registry = hook_registry or get_registry()
-        
+
         # Load hooks from config if available
         self._load_hooks_from_config()
 
+        # Load persisted sessions
+        self._load_sessions()
+
+    def _load_sessions(self):
+        """Load sessions from disk."""
+        import json
+
+        for session_file in self.sessions_dir.glob("*.json"):
+            try:
+                data = json.loads(session_file.read_text())
+                session_model = Session(**data)
+                # Rehydrate as Observer
+                runtime = RuntimeSession(
+                    session_model,
+                    worker=None,  # No worker for loaded sessions initially (Observer mode)
+                    hook_registry=self.hook_registry,
+                    project_root=self.project_root,
+                    save_callback=self._save_session,
+                )
+                self._sessions[session_model.id] = runtime
+                # Check status immediately to see if it's still running
+                runtime.refresh_status()
+            except Exception as e:
+                print(f"Failed to load session {session_file}: {e}")
+
+    def _save_session(self, session: Session):
+        """Save session to disk."""
+        file_path = self.sessions_dir / f"{session.id}.json"
+        file_path.write_text(session.model_dump_json(indent=2))
+
     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
@@ -60,14 +94,21 @@ class SessionManager:
             branch_name=branch_name,
         )
 
-        worker = Worker(role, issue_id)
+        # 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, 
+            session_model,
             worker,
             hook_registry=self.hook_registry,
             project_root=self.project_root,
+            save_callback=self._save_session,
         )
         self._sessions[session_id] = runtime
+        self._save_session(session_model)
         return runtime
 
     def get_session(self, session_id: str) -> Optional[RuntimeSession]:
@@ -82,5 +123,5 @@ class SessionManager:
         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
+            # We keep the record for history
             # del self._sessions[session_id]

monoco/features/agent/models.py

@@ -19,9 +19,9 @@ class RoleTemplate(BaseModel):
     )
 
 
-class AgentConfig(BaseModel):
+class AgentRoleConfig(BaseModel):
     roles: List[RoleTemplate] = Field(default_factory=list)
 
 
 # Backward compatibility alias
-SchedulerConfig = AgentConfig
+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:
+      - "功能是否正确实现"
+      - "代码是否符合设计规范"
+      - "测试是否充分"
+      - "文档是否同步更新"
+      - "是否遵循项目规范"

monoco/{core/resources/en → features/agent/resources/en/skills/monoco_atom_core}/SKILL.md

@@ -1,6 +1,8 @@
 ---
-name: monoco-core
+name: monoco_atom_core
 description: Core skill for Monoco Toolkit. Provides essential commands for project initialization, configuration, and workspace management.
+type: atom
+version: 1.0.0
 ---
 
 # Monoco Core

monoco/features/agent/resources/en/skills/monoco_workflow_agent_engineer/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: monoco_workflow_agent_engineer
+description: Standardized workflow for the Engineer role (Flow Skill). Defines the standard operating procedure from requirement investigation to code submission, ensuring test coverage and code quality.
+type: workflow
+role: engineer
+version: 1.0.0
+---
+
+# Engineer Flow
+
+Standardized workflow for the Engineer role, ensuring code development follows the "Investigate → Code → Test → Report → Submit" process.
+
+## Workflow State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Investigate: Receive Task
+    
+    Investigate --> Code: Requirements Clear
+    Investigate --> Investigate: Requirements Fuzzy<br/>(Request Clarification)
+    
+    Code --> Test: Coding Complete
+    
+    Test --> Test: Test Failed<br/>(Fix Code)
+    Test --> Report: Test Passed
+    
+    Report --> Submit: Report Complete
+    
+    Submit --> [*]: Submission Successful
+```
+
+## Execution Steps
+
+### 1. Investigate
+
+- **Goal**: Fully understand requirements, identify technical risks and dependencies
+- **Input**: Issue description, relevant code, dependent Issues
+- **Output**: Technical solution draft, risk checklist
+- **Checkpoints**:
+  - [ ] Read and understand Issue description
+  - [ ] Identify relevant code files
+  - [ ] Check dependent Issue status
+  - [ ] Assess technical feasibility
+
+### 2. Code
+
+- **Goal**: Implement feature or fix defect
+- **Prerequisites**: Requirements are clear, branch is created (`monoco issue start <ID> --branch`)
+- **Checkpoints**:
+  - [ ] Follow project coding standards
+  - [ ] Write/update necessary documentation
+  - [ ] Handle edge cases
+
+### 3. Test
+
+- **Goal**: Ensure code quality and functional correctness
+- **Strategy**: Loop testing until passed
+- **Checkpoints**:
+  - [ ] Write/update unit tests
+  - [ ] Run test suite (`pytest`, `cargo test`, etc.)
+  - [ ] Fix failed tests
+  - [ ] Check test coverage
+
+### 4. Report
+
+- **Goal**: Document changes, update Issue status
+- **Checkpoints**:
+  - [ ] Update Issue file tracking (`monoco issue sync-files`)
+  - [ ] Write change summary
+  - [ ] Update task checklist (Checkboxes)
+
+### 5. Submit
+
+- **Goal**: Complete code submission, enter review process
+- **Checkpoints**:
+  - [ ] Run `monoco issue lint` for compliance check
+  - [ ] Run `monoco issue submit <ID>`
+  - [ ] Wait for review results
+
+## Decision Branches
+
+| Condition | Action |
+|-----------|--------|
+| Requirements unclear | Return to Investigate, request clarification |
+| Test failed | Return to Code, fix issues |
+| Lint failed | Fix compliance issues, resubmit |
+| Review rejected | Return to Code, modify according to feedback |
+
+## Compliance Requirements
+
+- **Prohibited**: Skip tests and submit directly
+- **Prohibited**: Modify code directly on main/master branch
+- **Required**: Use `monoco issue start --branch` to create feature branch
+- **Required**: All unit tests must pass before Submit

monoco/features/agent/resources/en/skills/monoco_workflow_agent_manager/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: monoco_workflow_agent_manager
+description: Standardized workflow for the Manager role (Flow Skill). Defines the standard operating procedure from inbox organization to task assignment, ensuring clear requirements and reasonable task breakdown.
+type: workflow
+role: manager
+version: 1.0.0
+---
+
+# Manager Flow
+
+Standardized workflow for the Manager role, focusing on inbox organization, requirement refinement, and task assignment.
+
+## Workflow State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Inbox: New Input
+    
+    Inbox --> Triage: Review
+    
+    Triage --> Refine: Needs Clarification
+    Triage --> Assign: Ready
+    Triage --> Archive: Not Actionable
+    
+    Refine --> Assign: Refined
+    Refine --> Refine: Still Unclear
+    
+    Assign --> [*]: Task Assigned
+    Archive --> [*]: Discarded
+```
+
+## Execution Steps
+
+### 1. Inbox (收件箱)
+
+- **Goal**: Collect all new inputs (Memos, external requests, ideas)
+- **Input**: Raw notes, meeting minutes, user feedback
+- **Checkpoints**:
+  - [ ] Run `monoco memo list` to check pending memos
+  - [ ] Review external issue trackers (if any)
+  - [ ] Collect stakeholder requests
+
+### 2. Triage (分类)
+
+- **Goal**: Quick classification of inbox items
+- **Checkpoints**:
+  - [ ] Is this actionable?
+  - [ ] Is this a bug, feature, chore, or epic?
+  - [ ] Does it need immediate attention?
+  - [ ] Is there enough context to proceed?
+
+### 3. Refine (细化)
+
+- **Goal**: Transform vague ideas into actionable requirements
+- **Checkpoints**:
+  - [ ] Clarify the "Why" (business value)
+  - [ ] Define the "What" (acceptance criteria)
+  - [ ] Identify dependencies and blockers
+  - [ ] Estimate effort (rough sizing)
+
+### 4. Assign (指派)
+
+- **Goal**: Create proper Issues and assign to team members
+- **Checkpoints**:
+  - [ ] Create Issue using `monoco issue create <type> -t "Title"`
+  - [ ] Link related Memos or Issues
+  - [ ] Set appropriate priority and labels
+  - [ ] Assign to team member (or leave unassigned for pickup)
+
+### 5. Archive (归档)
+
+- **Goal**: Clean up non-actionable items
+- **Checkpoints**:
+  - [ ] Document why it's not actionable
+  - [ ] Move to appropriate archive location
+  - [ ] Update stakeholders if needed
+
+## Decision Matrix
+
+| Input Type | Action | Next Step |
+|------------|--------|-----------|
+| Clear bug report | Create Fix Issue | Assign |
+| Vague feature idea | Needs refinement | Refine |
+| Technical debt | Create Chore Issue | Assign |
+| Strategic initiative | Create Epic | Refine |
+| Pure reference material | Archive | Archive |
+
+## Best Practices
+
+1. **Inbox Zero**: Process inbox regularly, don't let items accumulate
+2. **Clear Acceptance Criteria**: Every Issue must have verifiable acceptance criteria
+3. **Right Sizing**: Break down large tasks into manageable Issues
+4. **Context Preservation**: Always link back to original memos or requests

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

@@ -0,0 +1,85 @@
+---
+name: monoco_workflow_agent_planner
+description: Standardized workflow for the Planner role (Flow Skill). Responsible for analysis, design, planning, and handoff.
+type: workflow
+role: planner
+version: 1.0.0
+---
+
+# Planner Flow
+
+Standardized workflow for the Planner role, focusing on technical analysis, architecture design, and implementation planning.
+
+## Workflow State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Analyze: Receive Requirements
+    
+    Analyze --> Design: Requirements Understood
+    Analyze --> Analyze: Needs More Info
+    
+    Design --> Plan: Design Approved
+    Design --> Design: Design Rejected
+    
+    Plan --> Handoff: Plan Complete
+    
+    Handoff --> [*]: Ready for Implementation
+```
+
+## Execution Steps
+
+### 1. Analyze (分析)
+
+- **Goal**: Deep understanding of requirements and constraints
+- **Input**: Feature/Chore Issue, stakeholder requirements
+- **Output**: Analysis document, technical constraints list
+- **Checkpoints**:
+  - [ ] Read and understand requirements thoroughly
+  - [ ] Identify technical constraints (performance, security, compatibility)
+  - [ ] Research existing solutions and patterns
+  - [ ] Document assumptions and risks
+
+### 2. Design (设计)
+
+- **Goal**: Create technical design and architecture
+- **Checkpoints**:
+  - [ ] Define system architecture and components
+  - [ ] Design data models and interfaces
+  - [ ] Consider scalability and maintainability
+  - [ ] Document design decisions (ADR)
+
+### 3. Plan (规划)
+
+- **Goal**: Break down design into implementable tasks
+- **Checkpoints**:
+  - [ ] Create sub-tasks or child Issues
+  - [ ] Define dependencies between tasks
+  - [ ] Estimate effort for each task
+  - [ ] Identify required skills and resources
+
+### 4. Handoff (交接)
+
+- **Goal**: Prepare comprehensive handoff to Engineering
+- **Checkpoints**:
+  - [ ] Document implementation guidelines
+  - [ ] Create technical specification (if needed)
+  - [ ] Update parent Issue with plan summary
+  - [ ] Link all child Issues to parent
+
+## Output Artifacts
+
+| Artifact | Purpose | Location |
+|----------|---------|----------|
+| Analysis Notes | Document findings and constraints | Issue comments or linked doc |
+| Architecture Diagram | Visual representation of design | `docs/architecture/` or Issue |
+| ADR | Record design decisions | `docs/adr/` |
+| Task Breakdown | List of implementable sub-tasks | Child Issues |
+| Technical Spec | Detailed implementation guide | Issue description or linked doc |
+
+## Best Practices
+
+1. **Design for Change**: Anticipate future changes in your design
+2. **Prototype When Uncertain**: Build quick prototypes to validate approaches
+3. **Review Early**: Get feedback on designs before full planning
+4. **Document Trade-offs**: Always document why certain decisions were made