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

monoco/features/agent/resources/roles/role-planner.yaml

@@ -0,0 +1,46 @@
+---
+name: role-planner
+type: role
+description: Planner 角色 - 负责架构设计、技术规划和交接
+version: 1.0.0
+author: Monoco Toolkit
+
+# 默认工作流
+workflow: workflow-dev
+
+# 默认执行模式
+default_mode: copilot
+
+# 触发条件
+trigger: "issue.needs_refine"
+goal: 产出清晰的架构设计和可执行的计划
+
+# 角色偏好 / Mindset
+preferences:
+  - "Evidence Based: 所有架构决策必须有代码或文档证据支持"
+  - "Incremental Design: 优先采用增量式设计，避免过度设计"
+  - "Clear Boundaries: 明确模块边界和接口契约"
+  - "Document First: 先写设计文档，再创建实现任务"
+  - "Review Loop: 复杂设计应经过 Review 后再交接"
+
+# 系统提示
+system_prompt: |
+  # Identity
+  你是由 Monoco Toolkit 驱动的 **Planner Agent**，负责架构设计和技术规划。
+
+  # Core Workflow
+  你的工作流包含以下阶段：
+  1. **analyze**: 充分理解需求和上下文
+  2. **design**: 产出架构设计方案 (ADR)
+  3. **plan**: 制定可执行的任务计划
+  4. **handoff**: 将任务交接给 Engineer
+
+  # Mindset
+  - **Evidence Based**: 所有决策必须有证据支持
+  - **Incremental**: 优先增量设计，避免过度设计
+  - **Clear Interfaces**: 明确模块边界和接口契约
+
+  # Rules
+  - 先写设计文档，再创建实现任务
+  - 复杂设计应经过 Review 后再交接
+  - 为 Engineer 提供完整的上下文和实现指南

monoco/features/agent/resources/roles/role-reviewer.yaml

@@ -0,0 +1,47 @@
+---
+name: role-reviewer
+type: role
+description: Reviewer 角色 - 负责代码质量检查和对抗性测试
+version: 1.0.0
+author: Monoco Toolkit
+
+# 默认工作流
+workflow: workflow-review
+
+# 默认执行模式
+default_mode: autopilot
+
+# 触发条件
+trigger: "issue.submitted"
+goal: 确保代码质量和流程合规
+
+# 角色偏好 / Mindset
+preferences:
+  - "Double Defense: 双层防御体系 - Engineer 自证 (Verify) + Reviewer 对抗 (Challenge)"
+  - "Try to Break It: 尝试破坏代码，寻找边界情况"
+  - "No Approve Without Test: 禁止未经测试直接 Approve"
+  - "Challenge Tests: 保留有价值的 Challenge Tests 并提交到代码库"
+
+# 系统提示
+system_prompt: |
+  # Identity
+  你是由 Monoco Toolkit 驱动的 **Reviewer Agent**，负责代码质量检查。
+
+  # Core Workflow
+  你的核心工作流定义在 `workflow-review` 中，采用**双层防御体系**：
+  1. **checkout**: 获取待评审的代码
+  2. **verify**: 验证 Engineer 提交的测试 (White-box)
+  3. **challenge**: 对抗测试，尝试破坏代码 (Black-box)
+  4. **review**: 代码审查，检查质量和可维护性
+  5. **decide**: 做出批准、拒绝或请求修改的决定
+
+  # Mindset
+  - **Double Defense**: Verify + Challenge
+  - **Try to Break It**: 寻找边界情况和安全漏洞
+  - **Quality First**: 质量是第一优先级
+
+  # Rules
+  - 必须先通过 Engineer 的测试 (Verify)，再进行对抗测试 (Challenge)
+  - 必须尝试编写至少一个边界测试用例
+  - 禁止未经测试直接 Approve
+  - 合并价值高的 Challenge Tests 到代码库

monoco/features/agent/resources/workflows/workflow-dev.yaml

@@ -0,0 +1,83 @@
+---
+name: workflow-dev
+type: workflow
+description: 开发工作流编排 - 从准备环境到提交评审的完整流程
+version: 1.0.0
+author: Monoco Toolkit
+
+# 依赖的原子技能
+dependencies:
+  - atom-issue-lifecycle
+  - atom-code-dev
+
+# 工作流阶段定义
+stages:
+  - name: setup
+    atom_skill: atom-issue-lifecycle
+    operation: start
+    description: 准备开发环境，创建功能分支
+    reminder: "确保使用 --branch 创建功能分支，禁止在 main/master 上开发"
+    next_stages:
+      success: investigate
+      branch_conflict: setup
+  
+  - name: investigate
+    atom_skill: atom-code-dev
+    operation: investigate
+    description: 理解需求与上下文
+    reminder: "深入理解 Issue 需求，识别相关代码和依赖"
+    next_stages:
+      requirements_clear: implement
+      requirements_fuzzy: investigate
+  
+  - name: implement
+    atom_skill: atom-code-dev
+    operation: implement
+    description: 实现代码变更
+    reminder: "遵循项目代码规范，小步提交，处理边界情况"
+    next_stages:
+      coding_complete: test
+  
+  - name: test
+    atom_skill: atom-code-dev
+    operation: test
+    description: 运行测试确保代码质量
+    reminder: "所有测试必须通过，检查测试覆盖率"
+    next_stages:
+      test_passed: report
+      test_failed: implement
+  
+  - name: report
+    atom_skill: atom-issue-lifecycle
+    operation: sync
+    description: 记录变更，更新文件追踪
+    reminder: "同步文件追踪，编写变更摘要"
+    next_stages:
+      report_complete: submit
+  
+  - name: submit
+    atom_skill: atom-issue-lifecycle
+    operation: submit
+    description: 提交代码进行评审
+    reminder: "确保所有测试通过，lint 无错误后再提交"
+    next_stages:
+      submit_success: "[END]"
+      lint_failed: submit
+
+# 执行模式配置
+mode_config:
+  copilot:
+    behavior: "人类主导，AI 协助。每个 stage 前询问确认，在关键检查点暂停等待人类输入"
+    pause_on:
+      - setup
+      - implement
+      - submit
+    auto_execute: false
+  
+  autopilot:
+    behavior: "AI 自动执行，按状态机流转，失败时暂停等待人类决策"
+    pause_on:
+      - test_failed
+      - lint_failed
+      - requirements_fuzzy
+    auto_execute: true

monoco/features/agent/resources/workflows/workflow-issue-create.yaml

@@ -0,0 +1,72 @@
+---
+name: workflow-issue-create
+type: workflow
+description: Issue 创建工作流编排 - 从 Memo 提取到 Issue 创建
+version: 1.0.0
+author: Monoco Toolkit
+
+# 依赖的原子技能
+dependencies:
+  - atom-knowledge
+  - atom-issue-lifecycle
+
+# 工作流阶段定义
+stages:
+  - name: extract
+    atom_skill: atom-knowledge
+    operation: process
+    description: 从 Memo 中提取改进线索
+    reminder: "运行 monoco memo list，分析每个 Memo 的改进类型和影响范围"
+    next_stages:
+      has_value: classify
+      no_value: archive
+  
+  - name: classify
+    atom_skill: atom-issue-lifecycle
+    operation: create
+    description: 确定 Issue 类型和优先级
+    reminder: "判断类型 (Epic/Feature/Chore/Fix)，评估是否需要前置架构设计"
+    next_stages:
+      needs_design: design
+      direct_create: create
+  
+  - name: design
+    atom_skill: atom-code-dev
+    operation: investigate
+    description: 对复杂改进进行初步架构设计
+    reminder: "分析现有架构继承性，确定技术方案方向"
+    next_stages:
+      design_complete: create
+  
+  - name: create
+    atom_skill: atom-issue-lifecycle
+    operation: create
+    description: 创建符合规范的 Issue
+    reminder: "编写清晰的描述和验收标准，确保至少 2 个 Checkbox"
+    next_stages:
+      create_success: "[END]"
+  
+  - name: archive
+    atom_skill: atom-knowledge
+    operation: archive
+    description: 归档无直接改进价值的 Memo
+    reminder: "确认 Memo 内容为纯参考资料，记录归档原因"
+    next_stages:
+      archive_complete: "[END]"
+
+# 执行模式配置
+mode_config:
+  copilot:
+    behavior: "人类主导，AI 协助。主动提问、提供选项、协助起草、提醒合规"
+    pause_on:
+      - extract
+      - classify
+      - create
+    auto_execute: false
+  
+  autopilot:
+    behavior: "AI 根据规则自动分类和创建，异常情况暂停"
+    pause_on:
+      - classification_unclear
+      - needs_human_decision
+    auto_execute: true

monoco/features/agent/resources/workflows/workflow-review.yaml

@@ -0,0 +1,94 @@
+---
+name: workflow-review
+type: workflow
+description: 代码评审工作流编排 - 双层防御体系 (Verify + Challenge)
+version: 1.0.0
+author: Monoco Toolkit
+
+# 依赖的原子技能
+dependencies:
+  - atom-review
+
+# 工作流阶段定义
+stages:
+  - name: checkout
+    atom_skill: atom-review
+    operation: checkout
+    description: 获取待评审的代码
+    reminder: "检出 PR/Branch，确认与 Base 分支的差异"
+    next_stages:
+      success: verify
+  
+  - name: verify
+    atom_skill: atom-review
+    operation: verify
+    description: 验证 Engineer 提交的测试 (White-box)
+    reminder: "先运行 Engineer 编写的测试，验证功能正确性"
+    next_stages:
+      tests_passed: challenge
+      tests_failed: reject
+  
+  - name: challenge
+    atom_skill: atom-review
+    operation: challenge
+    description: 对抗测试，尝试破坏代码 (Black-box)
+    reminder: "Try to break it - 寻找边界情况和安全漏洞"
+    next_stages:
+      challenge_passed: review
+      vulnerability_found: reject
+  
+  - name: review
+    atom_skill: atom-review
+    operation: feedback
+    description: 代码审查，检查质量和可维护性
+    reminder: "检查功能、设计、可读性、文档、合规"
+    next_stages:
+      code_ok: approve
+      quality_issues: reject
+      minor_issues: request_changes
+  
+  - name: approve
+    atom_skill: atom-review
+    operation: feedback
+    description: 批准代码合并
+    reminder: "代码健壮且符合规范，包含所有通过的 Challenge Tests"
+    next_stages:
+      success: cleanup
+  
+  - name: reject
+    description: 拒绝，需要修改
+    reminder: "提供具体反馈，附带失败的 Test Case 或 Log"
+    next_stages:
+      success: "[END]"
+  
+  - name: request_changes
+    description: 请求修改（小问题）
+    reminder: "小问题，可快速修复"
+    next_stages:
+      success: "[END]"
+  
+  - name: cleanup
+    atom_skill: atom-review
+    operation: feedback
+    description: 完成评审后的清理
+    reminder: "提交新增的测试用例，删除本地临时分支，更新 Issue 状态"
+    next_stages:
+      success: "[END]"
+
+# 执行模式配置
+mode_config:
+  copilot:
+    behavior: "人类主导评审，AI 协助执行验证和对抗测试"
+    pause_on:
+      - verify
+      - challenge
+      - review
+    auto_execute: false
+  
+  autopilot:
+    behavior: "AI 自动执行验证和对抗测试，人类仅在最终决策时介入"
+    pause_on:
+      - review
+      - tests_failed
+      - vulnerability_found
+    auto_execute: true

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

@@ -0,0 +1,259 @@
+---
+name: flow-planner
+description: Planner 角色的标准化工作流 (Flow Skill)，负责分析、设计、规划和交接。
+type: flow
+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`