feat(context_management): Add memory extractor component and context management toolkit #500

agentuniverse/agent/action/tool/context_tool/__init__.py

@@ -0,0 +1,7 @@
+# !/usr/bin/env python3
+# -*- coding:utf-8 -*-
+
+# @Time    : 2025/12/7 16:20
+# @Author  : pengqingsong.pqs
+# @Email   : pengqingsong.pqs@antgroup.com
+# @FileName: __init__.py.py

agentuniverse/agent/action/tool/context_tool/base_context_tool.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+# -*- coding:utf-8 -*-
+
+# @Time    : 2025/12/7 16:20
+# @Author  : pengqingsong.pqs
+# @Email   : pengqingsong.pqs@antgroup.com
+# @FileName: base_context_tool.py
+
+import os
+from abc import ABC
+
+from pydantic import Field
+
+from agentuniverse.agent.action.tool.tool import Tool
+from agentuniverse.base.util.env_util import get_from_env
+
+
+class BaseContextTool(Tool, ABC):
+    """Context tool base class
+
+    Provides basic functionality for session_id directory management
+    All context tools inherit from this class
+    """
+
+    context_file_rootpath: str = Field(
+        default_factory=lambda: get_from_env("CONTEXT_FILE_ROOTPATH") if get_from_env("CONTEXT_FILE_ROOTPATH") else "/tmp/agentuniverse_context",
+        description="Context file root path"
+    )
+
+    def _get_session_directory(self, session_id: str) -> str:
+        """Get directory path for session_id
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            Session directory path
+        """
+        return os.path.join(self.context_file_rootpath, f"session_{session_id}")
+
+    def _ensure_session_directory(self, session_id: str) -> str:
+        """Ensure session_id directory exists
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            Session directory path
+        """
+        session_dir = self._get_session_directory(session_id)
+        os.makedirs(session_dir, exist_ok=True)
+        return session_dir
+
+    def _get_file_path(self, session_id: str, file_name: str) -> str:
+        """Get full file path
+
+        Args:
+            session_id: Session ID
+            file_name: File name
+
+        Returns:
+            Full file path
+        """
+        # If no extension, default to .md
+        if '.' not in file_name:
+            file_name = f"{file_name}.md"
+
+        session_dir = self._ensure_session_directory(session_id)
+        return os.path.join(session_dir, file_name)
+
+    def _file_exists(self, session_id: str, file_name: str) -> bool:
+        """Check if file exists
+
+        Args:
+            session_id: Session ID
+            file_name: File name
+
+        Returns:
+            Whether file exists
+        """
+        file_path = self._get_file_path(session_id, file_name)
+        return os.path.exists(file_path)
+
+    def _read_file_content(self, file_path: str) -> str:
+        """Read file content
+
+        Args:
+            file_path: File path
+
+        Returns:
+            File content
+        """
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                return f.read()
+        except FileNotFoundError:
+            raise FileNotFoundError(f"File does not exist: {file_path}")
+        except Exception as e:
+            raise Exception(f"File reading failed: {str(e)}")
+
+    def _write_file_content(self, file_path: str, content: str) -> None:
+        """Write file content
+
+        Args:
+            file_path: File path
+            content: Content to write
+        """
+        try:
+            with open(file_path, 'w', encoding='utf-8') as f:
+                f.write(content)
+        except Exception as e:
+            raise Exception(f"File writing failed: {str(e)}")
+
+    def _get_relative_path(self, session_id: str, file_name: str) -> str:
+        """Get file path relative to root path
+
+        Args:
+            session_id: Session ID
+            file_name: File name
+
+        Returns:
+            Relative path
+        """
+        if '.' not in file_name:
+            file_name = f"{file_name}.md"
+        return f"session_{session_id}/{file_name}"

agentuniverse/agent/action/tool/context_tool/config/__init__.py

@@ -0,0 +1,7 @@
+# !/usr/bin/env python3
+# -*- coding:utf-8 -*-
+
+# @Time    : 2025/12/7 16:20
+# @Author  : pengqingsong.pqs
+# @Email   : pengqingsong.pqs@antgroup.com
+# @FileName: __init__.py.py

agentuniverse/agent/action/tool/context_tool/config/context_append_to_file.yaml

@@ -0,0 +1,34 @@
+name: 'context_append_to_file'
+description: |
+  该工具可以向指定上下文中的文件末尾追加内容，保留原有内容。
+
+  输入参数（JSON格式）：
+  ```json
+  {
+    "file_name": "目标文件名（字符串，必需）",
+    "content": "要追加的内容（字符串，必需）",
+    "session_id": "会话ID（字符串，必需）"
+  }
+  ```
+
+  输出参数（JSON格式）：
+  ```json
+  {
+    "message": "操作结果消息（字符串）"
+  }
+  ```
+
+  工具输入示例（JSON格式）：
+  ```json
+  {
+    "file_name": "example.md",
+    "content": "新增内容",
+    "session_id": "your_session_id"
+  }
+  ```
+tool_type: 'func'
+input_keys: ['file_name', 'content', 'session_id']
+metadata:
+  type: 'TOOL'
+  module: 'agentuniverse.agent.action.tool.context_tool.context_append_to_file'
+  class: 'ContextAppendToFileTool'

agentuniverse/agent/action/tool/context_tool/config/context_create_file.yaml

@@ -0,0 +1,35 @@
+name: 'context_create_file'
+description: |
+  该工具用于创建或更新上下文中的文件。
+
+  输入参数（JSON格式）：
+  ```json
+  {
+    "file_name": "文件名称（字符串，必需）",
+    "content": "文件内容（字符串，必需）", 
+    "session_id": "会话ID（字符串，必需）"
+  }
+  ```
+
+  输出参数（JSON格式）：
+  ```json
+  {
+    "message": "操作结果消息（字符串）",
+    "file_url": "文件相对路径（字符串）"
+  }
+  ```
+
+  工具输入示例（JSON格式）：
+  ```json
+  {
+    "file_name": "example.md",
+    "content": "文件内容",
+    "session_id": "your_session_id"
+  }
+  ```
+tool_type: 'func'
+input_keys: ['file_name', 'content', 'session_id']
+metadata:
+  type: 'TOOL'
+  module: 'agentuniverse.agent.action.tool.context_tool.context_create_file'
+  class: 'ContextCreateFileTool'

agentuniverse/agent/action/tool/context_tool/config/context_download_files.yaml

@@ -0,0 +1,39 @@
+name: 'context_download_files'
+description: |
+  该工具可以获取上下文中文件的访问路径或者地址，提供给用户或者其他工具使用。
+
+  输入参数（JSON格式）：
+  ```json
+  {
+    "file_name": "文件名称，多个文件用英文逗号分隔（字符串，必需）",
+    "session_id": "会话ID（字符串，必需）"
+  }
+  ```
+
+  输出参数（JSON格式）：
+  ```json
+  {
+    "file_list": [
+      {
+        "file": "文件名（字符串）",
+        "fileUrl": "文件相对路径（字符串）",
+        "message": "下载结果消息（字符串）"
+      }
+    ],
+    "message": "总体操作结果消息（字符串）"
+  }
+  ```
+
+  工具输入示例（JSON格式）：
+  ```json
+  {
+    "file_name": "example.md",
+    "session_id": "your_session_id"
+  }
+  ```
+tool_type: 'func'
+input_keys: ['file_name', 'session_id']
+metadata:
+  type: 'TOOL'
+  module: 'agentuniverse.agent.action.tool.context_tool.context_download_files'
+  class: 'ContextDownloadFilesTool'

agentuniverse/agent/action/tool/context_tool/config/context_insert.yaml

@@ -0,0 +1,37 @@
+name: 'context_insert'
+description: |
+  该工具可以在指定上下文中的文件的指定行号后插入文本内容。
+
+  输入参数（JSON格式）：
+  ```json
+  {
+    "file_name": "目标文件名（字符串，必需）",
+    "insert_text": "插入文本（字符串，必需）",
+    "session_id": "会话ID（字符串，必需）",
+    "insert_line": "插入行号，0表示文件开头，不指定则在末尾插入（字符串，可选）"
+  }
+  ```
+
+  输出参数（JSON格式）：
+  ```json
+  {
+    "message": "操作结果消息（字符串）",
+    "result": "操作结果状态，success/error（字符串）"
+  }
+  ```
+
+  工具输入示例（JSON格式）：
+  ```json
+  {
+    "file_name": "example.md",
+    "insert_line": "3",
+    "insert_text": "新增内容",
+    "session_id": "your_session_id"
+  }
+  ```
+tool_type: 'func'
+input_keys: ['file_name', 'insert_text', 'session_id', 'insert_line']
+metadata:
+  type: 'TOOL'
+  module: 'agentuniverse.agent.action.tool.context_tool.context_insert'
+  class: 'ContextInsertTool'

agentuniverse/agent/action/tool/context_tool/config/context_list_files.yaml

@@ -0,0 +1,31 @@
+name: 'context_list_files'
+description: |
+  该工具可以列出保存在上下文中的所有文件名称。
+
+  输入参数（JSON格式）：
+  ```json
+  {
+    "session_id": "会话ID（字符串，必需）"
+  }
+  ```
+
+  输出参数（JSON格式）：
+  ```json
+  {
+    "all_files": "所有文件名，用逗号分隔（字符串）",
+    "message": "操作结果消息（字符串）"
+  }
+  ```
+
+  工具输入示例（JSON格式）：
+  ```json
+  {
+    "session_id": "your_session_id"
+  }
+  ```
+tool_type: 'func'
+input_keys: ['session_id']
+metadata:
+  type: 'TOOL'
+  module: 'agentuniverse.agent.action.tool.context_tool.context_list_files'
+  class: 'ContextListFilesTool'

agentuniverse/agent/action/tool/context_tool/config/context_read_files.yaml

@@ -0,0 +1,43 @@
+name: 'context_read_files'
+description: |
+  该工具可以读取上下文中指定名称的文件内容，支持多文件和行范围读取。
+
+  输入参数（JSON格式）：
+  ```json
+  {
+    "file_name": "文件名称，多个文件用英文逗号分隔（字符串，必需）",
+    "session_id": "会话ID（字符串，必需）",
+    "line_range": "阅读指定的行范围，格式如[1, 10]（字符串，可选）",
+    "display_line_numbers": "是否显示行号，true/false（字符串，可选，默认false）"
+  }
+  ```
+
+  输出参数（JSON格式）：
+  ```json
+  {
+    "file_list": [
+      {
+        "file": "文件名（字符串）",
+        "content": "文件内容（字符串）",
+        "message": "读取结果消息（字符串）"
+      }
+    ],
+    "message": "总体操作结果消息（字符串）"
+  }
+  ```
+
+  工具输入示例（JSON格式）：
+  ```json
+  {
+    "file_name": "example.md",
+    "session_id": "your_session_id",
+    "line_range": "[1, 10]",
+    "display_line_numbers": "true"
+  }
+  ```
+tool_type: 'func'
+input_keys: ['file_name', 'session_id']
+metadata:
+  type: 'TOOL'
+  module: 'agentuniverse.agent.action.tool.context_tool.context_read_files'
+  class: 'ContextReadFilesTool'