matrix-for-agents 0.1.2__py3-none-any.whl

agentmatrix/skills/filesystem.py

@@ -0,0 +1,204 @@
+# skills/filesystem.py
+import os
+from pathlib import Path
+from ..core.action import register_action
+
+
+class FileSkillMixin:
+    """
+    文件系统技能包。
+    需要宿主类 (Agent) 提供 private_workspace 和 current_workspace 属性。
+    """
+
+    def _resolve_path(self, workspace_root: Path, relative_path: str = ".") -> Path:
+        """
+        安全路径解析，防止路径穿越攻击
+
+        Args:
+            workspace_root: workspace 根目录 (Path 对象)
+            relative_path: 相对路径，默认 "." 表示根目录
+
+        Returns:
+            解析后的绝对路径 (Path 对象)
+
+        Raises:
+            ValueError: 路径穿越检测或 workspace_root 为 None
+        """
+        # 1. 检查 workspace_root
+        if workspace_root is None:
+            raise ValueError("Workspace is not initialized. Please set workspace_root first.")
+
+        # 2. 规范化根目录
+        workspace_root = workspace_root.resolve()
+
+        # 3. 拼接并规范化目标路径
+        target_path = (workspace_root / relative_path).resolve()
+
+        # 4. 安全检查：确保目标路径在 workspace_root 内部
+        try:
+            target_path.relative_to(workspace_root)
+        except ValueError:
+            raise ValueError(
+                f"Security Alert: Path traversal detected. "
+                f"Attempted to access {relative_path}, which is outside workspace."
+            )
+
+        return target_path
+
+    # ========== Private Workspace Methods ==========
+
+    @register_action(
+        "列出私有工作区的文件。用于查看有哪些文件可用。",
+        param_infos={
+            "relative_path": "子目录路径，默认 '.' 表示根目录"
+        }
+    )
+    async def list_private_file(self, relative_path: str = ".") -> str:
+        """列出私有工作区中的文件和目录"""
+        try:
+            workspace = self.private_workspace
+            target_dir = self._resolve_path(workspace, relative_path)
+
+            if not target_dir.exists():
+                return f"Directory not found: {relative_path}"
+
+            items = []
+            for item in target_dir.iterdir():
+                marker = "[DIR] " if item.is_dir() else "[FILE]"
+                items.append(f"{marker}{item.name}")
+
+            return "\n".join(items) if items else "(Empty Directory)"
+
+        except Exception as e:
+            return f"Error listing private files: {str(e)}"
+
+    @register_action(
+        "读取私有工作区的文件内容。仅支持文本文件。",
+        param_infos={
+            "relative_path": "文件相对路径"
+        }
+    )
+    async def read_private_file(self, relative_path: str) -> str:
+        """读取私有工作区中的文本文件"""
+        try:
+            workspace = self.private_workspace
+            file_path = self._resolve_path(workspace, relative_path)
+
+            if not file_path.exists():
+                return f"Error: File '{relative_path}' does not exist."
+
+            if not file_path.is_file():
+                return f"Error: '{relative_path}' is not a file."
+
+            # 文件大小限制：50KB
+            MAX_SIZE = 50 * 1024
+            if file_path.stat().st_size > MAX_SIZE:
+                return f"Error: File too large ({file_path.stat().st_size} bytes). Limit: {MAX_SIZE} bytes."
+
+            return file_path.read_text(encoding='utf-8')
+
+        except UnicodeDecodeError:
+            return "Error: Binary file detected. Cannot read as text."
+        except Exception as e:
+            return f"Error reading private file: {str(e)}"
+
+    @register_action(
+        "写入内容到私有工作区的文件。",
+        param_infos={
+            "relative_path": "文件相对路径",
+            "content": "要写入的文本内容"
+        }
+    )
+    async def write_private_file(self, relative_path: str, content: str) -> str:
+        """写入内容到私有工作区的文件"""
+        try:
+            workspace = self.private_workspace
+            file_path = self._resolve_path(workspace, relative_path)
+
+            # 自动创建父目录
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+
+            file_path.write_text(content, encoding='utf-8')
+            return f"Success: Written to private workspace '{relative_path}'"
+
+        except Exception as e:
+            return f"Error writing private file: {str(e)}"
+
+    # ========== Shared Workspace Methods ==========
+
+    @register_action(
+        "列出共享工作区的文件。用于查看有哪些文件可用。",
+        param_infos={
+            "relative_path": "子目录路径，默认 '.' 表示根目录"
+        }
+    )
+    async def list_shared_file(self, relative_path: str = ".") -> str:
+        """列出共享工作区中的文件和目录"""
+        try:
+            workspace = self.current_workspace
+            target_dir = self._resolve_path(workspace, relative_path)
+
+            if not target_dir.exists():
+                return f"Directory not found: {relative_path}"
+
+            items = []
+            for item in target_dir.iterdir():
+                marker = "[DIR] " if item.is_dir() else "[FILE]"
+                items.append(f"{marker}{item.name}")
+
+            return "\n".join(items) if items else "(Empty Directory)"
+
+        except Exception as e:
+            return f"Error listing shared files: {str(e)}"
+
+    @register_action(
+        "读取共享工作区的文件内容。仅支持文本文件。",
+        param_infos={
+            "relative_path": "文件相对路径"
+        }
+    )
+    async def read_shared_file(self, relative_path: str) -> str:
+        """读取共享工作区中的文本文件"""
+        try:
+            workspace = self.current_workspace
+            file_path = self._resolve_path(workspace, relative_path)
+
+            if not file_path.exists():
+                return f"Error: File '{relative_path}' does not exist."
+
+            if not file_path.is_file():
+                return f"Error: '{relative_path}' is not a file."
+
+            # 文件大小限制：50KB
+            MAX_SIZE = 50 * 1024
+            if file_path.stat().st_size > MAX_SIZE:
+                return f"Error: File too large ({file_path.stat().st_size} bytes). Limit: {MAX_SIZE} bytes."
+
+            return file_path.read_text(encoding='utf-8')
+
+        except UnicodeDecodeError:
+            return "Error: Binary file detected. Cannot read as text."
+        except Exception as e:
+            return f"Error reading shared file: {str(e)}"
+
+    @register_action(
+        "写入内容到共享工作区的文件。",
+        param_infos={
+            "relative_path": "文件相对路径",
+            "content": "要写入的文本内容"
+        }
+    )
+    async def write_shared_file(self, relative_path: str, content: str) -> str:
+        """写入内容到共享工作区的文件"""
+        try:
+            workspace = self.current_workspace
+            file_path = self._resolve_path(workspace, relative_path)
+
+            # 自动创建父目录
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+
+            file_path.write_text(content, encoding='utf-8')
+            return f"Success: Written to shared workspace '{relative_path}'"
+
+        except Exception as e:
+            return f"Error writing shared file: {str(e)}"

agentmatrix/skills/notebook.py

@@ -0,0 +1,158 @@
+
+from ..core.action import register_action
+from datetime import datetime,timezone
+import json
+import os
+import uuid
+import asyncio
+import textwrap
+import traceback
+class NotebookMixin:
+
+    @register_action(
+        "从详细的系统日志记录中查找信息，补充遗忘的记忆",
+        param_infos={
+            "query": "想找什么？(自然语言描述)"
+        }
+    )
+    async def search_in_diary(self, query):
+        search_result = await asyncio.to_thread(
+            self.sync_search_in_history,
+            query=query
+        )
+        return search_result
+
+    def sync_search_in_history(self, query):
+        max_count = 10 #最多检查 10 封邮件
+        session = self.current_session
+        user_session_id = session.user_session_id
+        partial_results = []
+        for index in range(max_count):
+            mails = self.post_office.get_mails_by_range(user_session_id, self.name, start=index, end=index +1)
+            if mails:
+                m = mails[0]
+                mail_text = str(m)
+                    
+
+                search_history_prompt = textwrap.dedent(f"""
+                    你是一个专业的历史邮件管理助理。负责从系统邮件历史中查找能够回答用户问题的邮件。
+                    你只是负责查找，不需要回答问题。如果发现可以完整回答用户问题的邮件，就报告找到了。
+                    如果具有部分有用信息，就摘录出来。
+                    如果没有能回答问题的信息，就报告没有找到。
+
+                    用户现在想找的信息是：
+                    {query}
+
+                    [现在的查看的邮件是]：
+                    {mail_text}
+
+                    [应答的要求]：
+                    1. 严格按照下面的专业格式报告查找的结果：
+                    2. 如果这封邮件包含用户想找的信息，就输出 “FOUND"。单一单词，不要附加任何额外信息。
+                    3. 如果这封邮件包含用户想找的部分信息，就摘录这部分可能有用的信息的原文，并且直接输出。只输出原文，不要任何其他信息。
+                    4. 如果这封邮件没有任何有用信息，输出 "NOT_FOUND"。单一单词，不要附加任何额外信息
+                    5. 总之，你的输出要么是 “FOUND”，要么是 “NOT_FOUND”，要么是邮件中摘录的部分原文。任何其他内容都被认为是不专业的。
+                """)
+                messages= [{"role": "user", "content": search_history_prompt}]
+
+                response = self.cerebellum.backend.think(messages=messages)
+                reply_str= response['reply']
+                if reply_str == "FOUND":
+                    return textwrap.dedent(f"""
+                        Found relevant information in email
+                        {mail_text}
+                    """)
+                elif reply_str == "NOT_FOUND":
+                    continue
+                else:
+                    # 部分有用信息
+
+                    partial_results.append(textwrap.dedent(f"""[{m.timestamp}]:
+                        {reply_str}
+                    """))
+        if partial_results:
+            return_str = "Found following partial information in diary:\n"
+            for info in partial_results:
+                return_str += info + "\n"
+            return return_str
+        else:
+            return "No relevant information found in diary."
+        
+
+
+    @register_action(
+        "记笔记。记录关键信息",
+        param_infos={
+            "content": "具体的记忆内容 (自然语言)"
+        }
+    )
+    async def take_note(self, content):
+        notebook_filepath = os.path.join(self.workspace_root, ".matrix", self.name, "notebook", f"{self.current_user_session_id}.jsonl")
+        if not os.path.exists(notebook_filepath):
+            os.makedirs(os.path.dirname(notebook_filepath), exist_ok=True)
+        current_timestamp = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
+        record_id = str(uuid.uuid4())
+        
+
+        note_record ={
+            "id":record_id,
+            "created_at": current_timestamp,  #用于判断信息的新旧
+            "content": content,
+
+        }
+
+        #把笔记保存到文件
+        with open(notebook_filepath, "a") as f:
+            f.write(json.dumps(note_record) + "\n")
+        session = self.current_session
+        user_session_id = session.user_session_id
+
+        await self.vector_db.add_documents("notebook", [content], 
+            metadatas={"created_at": current_timestamp,
+                       "creator": self.name,
+                       "user_session_id": user_session_id
+                }, 
+            ids=[record_id]
+        )
+
+        
+        return "Note saved."
+
+        
+    
+
+    
+    
+
+    @register_action(
+        "Vector Search查笔记。查找以前记录的笔记",
+        param_infos={
+            "query": "想找什么？(自然语言描述)",
+        }
+    )
+    async def search_notebook(self, query):
+        session = self.current_session
+        user_session_id = session.user_session_id
+        where = {
+                    "$and": [
+                        {"user_session_id": user_session_id},
+                        {"creator": self.name}
+                    ]
+                }
+        results = await self.vector_db.query("notebook", [query], where, n_results=5)
+        if results['documents'] and results['documents'][0]:
+            return_str = "Most relevant notes:\n"
+            for doc, metadata,distance in zip(results['documents'][0], results['metadatas'][0], results['distances'][0]):
+                return_str += textwrap.dedent(f"""#### On : {metadata['created_at']} (Vector search distance: {distance} )  
+                    
+                    {doc}
+
+                """)
+            return return_str
+        else:
+            return "No notes found."
+
+
+
+        
+        

agentmatrix/skills/project_management.py

@@ -0,0 +1,114 @@
+# skills/project_management.py
+import os
+import time
+import textwrap
+from datetime import datetime
+from ..core.action import register_action
+
+class ProjectManagementMixin:
+    """
+    赋予 Agent 项目经理的能力：
+    1. 维护一个持久化的 Project Board (看板)。
+    2. 能够主动压缩上下文 (Memory Compression)，只保留看板和最近的对话。
+    3. 自动归档旧的历史记录到文件 (Audit Trail)。
+    """
+
+    def _get_board(self):
+        """获取当前看板，如果没有则初始化"""
+        if not hasattr(self, 'project_board') or self.project_board is None:
+            self.project_board = "Project Initialized. Waiting for scope definition."
+        return self.project_board
+
+    def _archive_history(self, old_history, reason):
+        """[Side Effect] 将被清理的对话记录归档到本地文件，防止永久丢失"""
+        if not self.workspace_root:
+            return
+
+        archive_dir = os.path.join(self.workspace_root, self.name, "logs", "archives")
+        os.makedirs(archive_dir, exist_ok=True)
+        
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        filename = f"{self.name}_archive_{timestamp}.log"
+        filepath = os.path.join(archive_dir, filename)
+
+        with open(filepath, "w", encoding='utf-8') as f:
+            f.write(f"=== ARCHIVE REASON: {reason} ===\n")
+            f.write(f"=== BOARD STATE ===\n{self.project_board}\n")
+            f.write("=== CONVERSATION HISTORY ===\n")
+            for msg in old_history:
+                role = msg.get('role','')
+                content = msg.get('content','')
+                if role and content:
+                    f.write(f"[{role}]: {content}\n{'-'*20}\n")
+        
+        if hasattr(self, 'logger'):
+            self.logger.info(f"Old memory archived to {filename}")
+
+    @register_action(
+        "阶段总结，更新项目看板,Markdown格式。项目状态发生重要变化后或者处理了比较多封邮件后需要阶段性的总结。保留所有关键信息",
+        param_infos={
+            "summary": "最新的全局项目状态总结",
+        }
+    )
+    async def update_board(self, summary: str):
+        """
+        Planner 的记忆重置操作。
+        """
+        # 1. 更新内存变量
+        self.project_board = summary
+        session = self.current_session
+        
+        # 2. 归档逻辑 (Archiving) - 这是一个好习惯，防止总结错了找不回原文
+        # 我们归档除了 System Prompt 和 Anchor 之外的所有中间层
+
+        # history 这个时候应该是这样的的
+        # （1）system prompt
+        # （2）第一个 user msg (anchor task, incoming email)
+        # （3）第一个 assistant msg (intent + action )
+        # (N 轮对话)
+        # 【倒数第四】user msg
+        # 【倒数第三】assistant msg
+        # 【倒数第二】 user msg
+        # [倒数第一】assistant msg (intent + action = update_board)
+
+
+        if len(session.history) > 10:
+            # history[0] = System, history[1] = Anchor
+            # 切片范围：从索引 2 到 最后（不包含即将生成的 Feedback）
+            msgs_to_archive = session.history[2:]
+            self._archive_history(msgs_to_archive, reason=f"Board Update: {summary[:20]}...")
+
+            # 3. 构造新的“中间层” (The Compressed State)
+            # 用 System 角色或者 Assistant 角色都可以。
+            # 用 System 角色更像“上帝视角的旁白”，用 Assistant 角色更像“我自己的笔记”。
+            # 这里推荐用 System 格式，以此区隔于普通的对话。
+            board_msg = {
+                "role": "assistant", 
+                "content": textwrap.dedent(f"""
+                    Latest project status
+                    
+                    ### 📌 CURRENT PROJECT BOARD
+                    {self.project_board}
+                    
+                """)
+            }
+            
+            # 4. 重组 History
+            # [System Prompt] + [Anchor Task] + [New Board]
+            # 注意：这里我们只取前两个。如果 history 长度不足 2（比如刚开始就 update），要做保护
+            base_history = session.history[:2] 
+            #从
+            # 覆盖 Session History
+            session.history = base_history + [board_msg]
+            
+            # 5. 返回结果
+            # 这个返回值会被 BaseAgent 追加到 history 的末尾，成为新的激活信号
+            return "Project status reviewed."
+        else:
+            return "Status is up to date"
+    
+
+
+# skills/project_management.py
+
+    

agentmatrix/skills/report_writer.py

@@ -0,0 +1,194 @@
+import os
+from pathlib import Path
+from dataclasses import dataclass, field
+from typing import List, AsyncIterator, Optional
+import fitz  # PyMuPDF
+# 正确的 Marker 导入方式
+from marker.models import load_all_models
+from marker.convert import convert_single_pdf
+
+
+import torch
+import textwrap
+from ..skills.report_writer_utils import *
+from ..core.action import register_action
+
+
+@dataclass
+class ResearchState:
+    """研究状态数据结构，在整个流程中流转"""
+    main_subject: str                       # 研究主题
+    main_purpose: str                     # 研究目的
+    input_dir : str
+    output_dir: str
+    blueprint: str = ""             # 调查蓝图（大纲、核心问题清单、预设章节）
+    concept_notes: str = ""         # 概念笔记（Markdown格式，包含实体定义、关系、来源）
+    draft_content: str = ""         # 正文草稿（Markdown格式，分章节填充的内容）
+    scrachpad: str = ""              # 临时草稿（Markdown格式，用于临时保存的笔记）
+    processed_files: List[str] = field(default_factory=list)  # 进度记录
+
+
+class ReportWriterSkillMixin:
+
+
+
+    async def ask_ai(self, prompt:str, sys_prompt:str = None) -> str:
+        messages =[]
+        if sys_prompt:
+            messages.append({"role": "system", "content": sys_prompt})
+        messages.append({"role": "user", "content": prompt})
+        response = await self.brain.think(messages)
+        self.logger.debug(f"AI Think: {response['reasoning']}")
+        self.logger.debug(f"AI Reply: {response['reply']}")
+        return response['reply']
+
+    @register_action(
+        "编写报告blueprint，需要提供报告主题和研究目的说明，生成研究方案",
+        param_infos={
+            
+            "main_subject": "报告主题",
+            "main_purpose": "研究目的，要解决或者研究的问题",
+            "src_dir": "可选非必须，输入资料目录",
+            "output_dir": "可选非必须，报告输出目录",
+            
+        }
+    )
+    async def write_report(self, main_subject: str, main_purpose: str, src_dir: str =".", output_dir: str="."):
+        """
+        阅读分析src_dir中的资料，撰写主题为main_subject、目的为main_purpose的报告，保存到output_dir中。
+        """
+        # 初始化状态
+        state = ResearchState(main_subject=main_subject, main_purpose= main_purpose, input_dir=src_dir, output_dir=output_dir)
+
+        # Phase 0: 先验生成
+        await self._phase0_theorist(state)
+        
+        
+        # Phase 1: 侦察与校准
+        state = await self._phase1_scout(state, src_dir)
+        '''
+        # Phase 2: 全量迭代
+        state = await self._phase2_execution_loop(state, src_dir)
+
+        # Phase 3: 终稿润色
+        final_report = await self._phase3_finalizer(state)
+
+        # 保存最终报告
+        self._save_final_report(final_report, output_dir)
+        '''
+
+    # ========== Phase 0: The Theorist ==========
+    async def _phase0_theorist(self, state: ResearchState) -> ResearchState:
+        main_subject = state.main_subject
+        main_purpose = state.main_purpose
+        #第一步，先生成人设prompt:
+        persona_prompt = textwrap.dedent(PERSONA_DESIGNER).replace("{{main_subject}}", main_subject).replace("{{main_purpose}}", main_purpose)
+        persona= await self.ask_ai(persona_prompt)
+        #第二步，生成blueprint prompt:
+        sys_prompt = textwrap.dedent(BLUEPRINT_DESIGNER).replace("{{persona}}", persona)
+        user_input = f"""
+        请基于以下主题和目标，生成一份 **Deep Research Blueprint**。
+
+        ### 用户输入
+        **研究主题**: {main_subject}
+        **研究动机/目标**: 
+            {main_purpose}
+        """
+        state.blueprint = await self.ask_ai(user_input, sys_prompt)
+
+
+        return state.blueprint
+        
+        
+
+        
+
+    # ========== Phase 1: The Scout ==========
+    async def _phase1_scout(self, state: ResearchState, src_dir: str) -> ResearchState:
+        """采样文档，修正蓝图"""
+        pass
+
+    async def _sample_and_analyze(self, state: ResearchState, src_dir: str, sample_count: int = 5):
+        """并行采样分析文档，生成Delta Reports"""
+        pass
+
+    async def _synthesize_blueprint(self, state: ResearchState, delta_reports: List[str]) -> str:
+        """主编合成：汇总Delta Reports，生成专用蓝图"""
+        pass
+
+    # ========== Phase 2: The Execution Loop ==========
+    async def _phase2_execution_loop(self, state: ResearchState, src_dir: str) -> ResearchState:
+        """流式阅读所有文档，迭代更新笔记和草稿"""
+        async for chunk in self._document_stream_generator(src_dir):
+            # Step A: 更新知识库
+            state.concept_notes = await self._update_concept_notes(state.concept_notes, chunk)
+
+            # Step B: 更新草稿
+            state.draft_content = await self._update_draft(state.blueprint, state.draft_content,
+                                                          state.concept_notes, chunk)
+
+        return state
+
+    async def _update_concept_notes(self, current_notes: str, new_text: str) -> str:
+        """识别新实体/新定义，或更新旧实体的属性/关系"""
+        pass
+
+    async def _update_draft(self, blueprint: str, current_draft: str, notes: str, new_text: str) -> str:
+        """判断new_text是否回答了蓝图中的问题，整合进草稿"""
+        pass
+
+    # ========== Phase 3: The Finalizer ==========
+    async def _phase3_finalizer(self, state: ResearchState) -> str:
+        """润色正文，生成附录"""
+        pass
+
+    # ========== Utility Functions ==========
+    async def _document_stream_generator(self, src_dir: str) -> AsyncIterator[str]:
+        """文档流生成器：封装文件读取，提供统一的yield chunk接口"""
+        pass
+
+    def _save_checkpoint(self, state: ResearchState, output_dir: str, phase_name: str):
+        """保存检查点：每个阶段结束时保存State为Markdown文件"""
+        pass
+
+    def _load_checkpoint(self, checkpoint_path: str) -> Optional[ResearchState]:
+        """加载检查点：从Markdown文件恢复State"""
+        pass
+
+    def _save_final_report(self, report: str, output_dir: str):
+        """保存最终报告"""
+        pass
+         
+
+### 如何使用这个函数
+
+
+if __name__ == '__main__':
+    # ==================== 使用示例 ====================
+    
+    # 定义你的 PDF 文件路径和输出目录
+    # 请确保将 'path/to/your/document.pdf' 替换为你的实际文件路径
+    my_pdf = 'path/to/your/document.pdf'
+    output_directory = 'output'
+    
+    # 示例1：转换整个 PDF 文档
+    # 不提供 start_page 和 end_page 参数
+    self.logger.debug("--- 任务1: 转换整个 PDF ---")
+    if Path(my_pdf).exists():
+        convert_pdf_to_markdown(my_pdf, output_directory)
+    else:
+        self.logger.debug(f"示例文件 '{my_pdf}' 不存在，请修改路径后重试。")
+        
+    # 示例2：只转换 PDF 的第 2 到 3 页
+    self.logger.debug("\n--- 任务2: 转换 PDF 的第 2-3 页 ---")
+    if Path(my_pdf).exists():
+        convert_pdf_to_markdown(my_pdf, output_directory, start_page=2, end_page=3)
+    else:
+        self.logger.debug(f"示例文件 '{my_pdf}' 不存在，请修改路径后重试。")
+
+    # 示例3：只转换第 5 页
+    self.logger.debug("\n--- 任务3: 只转换 PDF 的第 5 页 ---")
+    if Path(my_pdf).exists():
+        convert_pdf_to_markdown(my_pdf, output_directory, start_page=5, end_page=5)
+    else:
+        self.logger.debug(f"示例文件 '{my_pdf}' 不存在，请修改路径后重试。")