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

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

@@ -1,137 +0,0 @@
----
-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

@@ -1,169 +0,0 @@
-from datetime import datetime
-from typing import Optional
-from pathlib import Path
-from pydantic import BaseModel, Field, ConfigDict
-
-from .worker import Worker
-from monoco.core.hooks import HookContext, HookRegistry, get_registry
-from monoco.core.config import find_monoco_root
-
-
-class Session(BaseModel):
-    """
-    Represents a runtime session of a worker.
-    Persisted state of the session.
-    """
-
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    id: str = Field(..., description="Unique session ID (likely UUID)")
-    issue_id: str = Field(..., description="The Issue ID this session is working on")
-    role_name: str = Field(..., description="Name of the role employed")
-    status: str = Field(
-        default="pending", description="pending, running, suspended, terminated"
-    )
-    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
-    # For now, let's keep it simple. The git log IS the history.
-
-
-class RuntimeSession:
-    """
-    The in-memory wrapper around the Session model and the active Worker.
-    """
-
-    def __init__(
-        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}"
-        )
-        # In real impl, checking out branch happening here
-        self.model.status = "running"
-        self.model.updated_at = datetime.now()
-
-        try:
-            # 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.
-        """
-        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()
-        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":
-                    print(f"  Hook warning: {result.message}")
-        except Exception as e:
-            # Don't let hook errors prevent session termination
-            print(f"  Hook execution error: {e}")
-
-        if self.worker:
-            self.worker.stop()
-
-        self.model.status = "terminated"
-        self.model.updated_at = datetime.now()
-        self._save()

monoco/features/artifact/resources/zh/skills/monoco_atom_artifact/SKILL.md

@@ -1,278 +0,0 @@
----
-name: monoco_atom_artifact
-description: 多模态文档处理 Skill。指导 Agent 将 Office 文档转换为 PDF 并渲染为 WebP 图片，注册到 Monoco Artifact 系统。
-type: atom
-version: 1.0.0
----
-
-# Monoco Artifact: 多模态文档处理
-
-本 Skill 指导 Agent 执行 Office 文档 → PDF → WebP 的完整转换流程，并将结果注册为 Monoco Artifact。
-
-## 概述
-
-多模态文档处理允许 Agent:
-
-1. 将 Office 文档 (.docx, .xlsx, .pptx) 转换为 PDF
-2. 将 PDF 页面渲染为 WebP 图片 (150 DPI)
-3. 使用 Monoco CLI 注册转换产物为 Artifact
-
-## 环境探测
-
-在执行转换前，Agent 必须探测以下依赖:
-
-### 1. LibreOffice (soffice)
-
-```bash
-# 检查 soffice 是否可用
-which soffice
-soffice --version
-
-# 常见安装路径 (macOS)
-# /Applications/LibreOffice.app/Contents/MacOS/soffice
-
-# 常见安装路径 (Linux)
-# /usr/bin/soffice
-# /usr/lib/libreoffice/program/soffice
-```
-
-**如果未安装**:
-
-- **macOS**: `brew install --cask libreoffice`
-- **Ubuntu/Debian**: `sudo apt-get install libreoffice`
-- **CentOS/RHEL**: `sudo yum install libreoffice`
-
-### 2. Python 依赖
-
-```bash
-# 检查 PyMuPDF (fitz)
-python3 -c "import fitz; print(fitz.__doc__)"
-
-# 安装依赖
-pip install pymupdf pillow
-```
-
-### 3. Monoco CLI
-
-```bash
-# 验证 monoco 可用
-monoco --version
-```
-
-## 转换工作流
-
-### 标准转换流程
-
-```mermaid
-flowchart LR
-    A[Office Doc] -->|soffice| B[PDF]
-    B -->|fitz| C[WebP Images]
-    C -->|monoco| D[Artifact Registry]
-```
-
-### 步骤 1: Office → PDF
-
-使用 LibreOffice Headless 模式进行转换:
-
-```bash
-# 基础转换
-soffice --headless --convert-to pdf --outdir /output/path /input/document.docx
-
-# 推荐参数 (高质量、安全模式)
-soffice \
-  --headless \
-  --convert-to pdf:writer_pdf_Export:ExportBookmarks=true \
-  --outdir /output/path \
-  /input/document.docx
-```
-
-**参数说明**:
-
-- `--headless`: 无 GUI 模式，适合服务器/自动化环境
-- `--convert-to pdf`: 指定输出格式
-- `--outdir`: 输出目录
-- `ExportBookmarks=true`: 保留文档书签
-
-### 步骤 2: PDF → WebP
-
-使用 PyMuPDF (fitz) 渲染页面:
-
-```python
-import fitz  # PyMuPDF
-from pathlib import Path
-
-def pdf_to_webp(pdf_path: str, output_dir: str, dpi: int = 150) -> list[str]:
-    """
-    将 PDF 页面渲染为 WebP 图片。
-
-    Args:
-        pdf_path: PDF 文件路径
-        output_dir: 输出目录
-        dpi: 渲染分辨率 (默认 150 DPI)
-
-    Returns:
-        生成的 WebP 文件路径列表
-    """
-    doc = fitz.open(pdf_path)
-    output_path = Path(output_dir)
-    output_path.mkdir(parents=True, exist_ok=True)
-
-    webp_files = []
-    zoom = dpi / 72  # 72 DPI 是 PDF 默认分辨率
-    mat = fitz.Matrix(zoom, zoom)
-
-    for page_num in range(len(doc)):
-        page = doc[page_num]
-        pix = page.get_pixmap(matrix=mat)
-
-        webp_file = output_path / f"page_{page_num + 1:03d}.webp"
-        pix.save(str(webp_file))
-        webp_files.append(str(webp_file))
-
-    doc.close()
-    return webp_files
-```
-
-**DPI 选择指南**:
-| DPI | 用途 | 文件大小 |
-|-----|------|----------|
-| 72 | 预览/缩略图 | 小 |
-| 150 | 标准阅读 (推荐) | 中等 |
-| 300 | 高质量打印 | 大 |
-
-### 步骤 3: 注册 Artifact
-
-使用 Monoco CLI 注册产物:
-
-```bash
-# 注册单个文件
-monoco artifact register \
-  --file /path/to/page_001.webp \
-  --type image/webp \
-  --source-document original.docx \
-  --page 1
-
-# 批量注册整个目录
-monoco artifact register-batch \
-  --dir /path/to/webp/output \
-  --pattern "*.webp" \
-  --source-document original.docx
-```
-
-> **注意**: 如果 `monoco artifact` 命令不可用，使用 `monoco project` 或文件元数据记录产物信息。
-
-## 辅助脚本
-
-项目提供 `scripts/doc-to-webp.py` 脚本简化转换流程:
-
-```bash
-# 完整转换流程
-python scripts/doc-to-webp.py /path/to/document.docx --output ./artifacts --dpi 150
-
-# 仅转换特定页面
-python scripts/doc-to-webp.py document.docx --pages 1-5,10
-
-# 保留中间 PDF
-python scripts/doc-to-webp.py document.docx --keep-pdf
-```
-
-## 异常处理
-
-### 常见问题排查
-
-#### 1. 字体缺失
-
-**症状**: PDF 中文字显示为方块或乱码
-
-**解决方案**:
-
-```bash
-# macOS: 安装中文字体
-brew install font-noto-cjk
-
-# Linux: 安装文泉驿字体
-sudo apt-get install fonts-wqy-zenhei
-
-# 或使用 Docker 运行 (包含完整字体)
-docker run --rm -v $(pwd):/docs \
-  linuxserver/libreoffice \
-  soffice --headless --convert-to pdf /docs/input.docx
-```
-
-#### 2. 转换锁死/超时
-
-**症状**: soffice 进程无响应
-
-**解决方案**:
-
-```bash
-# 设置超时
- timeout 60 soffice --headless --convert-to pdf input.docx
-
-# 检查并清理僵尸进程
-pkill -9 soffice
-pkill -9 soffice.bin
-```
-
-#### 3. PDF 渲染质量差
-
-**症状**: WebP 图片模糊或有锯齿
-
-**解决方案**:
-
-- 提高 DPI (建议 150-300)
-- 使用抗锯齿矩阵:
-
-```python
-mat = fitz.Matrix(zoom, zoom).prerotate(0)
-pix = page.get_pixmap(matrix=mat, alpha=False)
-```
-
-#### 4. 内存不足 (大文档)
-
-**症状**: 处理大 PDF 时内存溢出
-
-**解决方案**:
-
-```python
-# 逐页处理，及时释放内存
-for page_num in range(len(doc)):
-    page = doc[page_num]
-    pix = page.get_pixmap(matrix=mat)
-    pix.save(f"page_{page_num}.webp")
-    pix = None  # 显式释放
-    page = None
-```
-
-## Agent 执行模板
-
-当用户要求处理文档时，按以下步骤执行:
-
-```
-1. [探测] 检查 soffice 和 PyMuPDF 是否可用
-   └─ 如果缺失 → 提示用户安装并提供命令
-
-2. [转换] Office → PDF
-   └─ 使用 soffice --headless --convert-to pdf
-   └─ 验证 PDF 生成成功
-
-3. [渲染] PDF → WebP
-   └─ 使用 scripts/doc-to-webp.py 或内联代码
-   └─ 默认 150 DPI，可根据需求调整
-
-4. [注册] 调用 monoco 注册 Artifact
-   └─ 记录 source-document 和 page 元数据
-
-5. [汇报] 向用户展示:
-   - 生成的文件列表
-   - 文件大小统计
-   - 任何警告或错误
-```
-
-## 最佳实践
-
-1. **临时文件管理**: 使用 `tempfile.TemporaryDirectory` 管理中间文件
-2. **错误重试**: 转换失败时自动重试 1-2 次
-3. **并发控制**: 大文档处理时限制并发页面数
-4. **元数据保留**: 始终记录原始文档名称和转换参数
-5. **清理策略**: 转换完成后可选保留或删除中间 PDF

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

@@ -1,35 +0,0 @@
----
-name: monoco_atom_glossary
-description: Official Monoco Glossary and Operational Laws
-tags: [core, definition]
-type: atom
-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/skills/monoco_atom_glossary/SKILL.md

@@ -1,35 +0,0 @@
----
-name: monoco_atom_glossary
-description: Monoco 官方术语表和操作法则
-tags: [core, definition]
-type: atom
-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 的智能层。