adam-community 1.0.23__tar.gz → 1.0.25__tar.gz

{adam_community-1.0.23 → adam_community-1.0.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: adam_community
-Version: 1.0.23
+Version: 1.0.25
 Summary: Adam Community Tools and Utilities
 Home-page: https://github.com/yourusername/adam-community
 Author: Adam Community
@@ -80,6 +80,35 @@ classes = parse_directory(Path("./"))
 success, errors, zip_name = build_package(Path("./"))
 ```
 
+### States Management（任务状态管理）
+
+用于在任务执行过程中记录和读取状态，与服务端共享 `states.json` 文件。
+
+```python
+from adam_community.util import setState, getState, trackPath
+
+# 记录文件列表（自动与服务端和其他 Tool 的文件合并）
+setState("files", [
+    {"path": "output/result.json", "is_dir": False, "mtime": 1704100800},
+    {"path": "cache", "is_dir": True, "mtime": 1704100000}
+])
+
+# 获取合并后的文件列表（来自 server + 所有 tools）
+files = getState("files")
+
+# 记录自定义状态（支持嵌套 key）
+setState("stage", "data_cleaning")
+setState("config.threshold", 0.5)
+
+# 获取状态
+stage = getState("stage")              # -> "data_cleaning"
+threshold = getState("config.threshold")  # -> 0.5
+
+# 追踪文件/目录（自动检测 is_dir 和 mtime，先进先出，最多 30 条）
+trackPath("/path/to/output/result.json")
+trackPath("/path/to/cache")
+```
+
 ## 功能特性
 
 - **Python 文件解析**: 自动解析 Python 类和函数的文档字符串

{adam_community-1.0.23 → adam_community-1.0.25}/README.md

@@ -50,6 +50,35 @@ classes = parse_directory(Path("./"))
 success, errors, zip_name = build_package(Path("./"))
 ```
 
+### States Management（任务状态管理）
+
+用于在任务执行过程中记录和读取状态，与服务端共享 `states.json` 文件。
+
+```python
+from adam_community.util import setState, getState, trackPath
+
+# 记录文件列表（自动与服务端和其他 Tool 的文件合并）
+setState("files", [
+    {"path": "output/result.json", "is_dir": False, "mtime": 1704100800},
+    {"path": "cache", "is_dir": True, "mtime": 1704100000}
+])
+
+# 获取合并后的文件列表（来自 server + 所有 tools）
+files = getState("files")
+
+# 记录自定义状态（支持嵌套 key）
+setState("stage", "data_cleaning")
+setState("config.threshold", 0.5)
+
+# 获取状态
+stage = getState("stage")              # -> "data_cleaning"
+threshold = getState("config.threshold")  # -> 0.5
+
+# 追踪文件/目录（自动检测 is_dir 和 mtime，先进先出，最多 30 条）
+trackPath("/path/to/output/result.json")
+trackPath("/path/to/cache")
+```
+
 ## 功能特性
 
 - **Python 文件解析**: 自动解析 Python 类和函数的文档字符串

adam_community-1.0.25/adam_community/__version__.py

@@ -0,0 +1 @@
+__version__ = "1.0.25"

adam_community-1.0.25/adam_community/cli/templates/agent_python.py.j2

@@ -0,0 +1,334 @@
+from adam_community.tool import Tool
+from adam_community.util import runCmd
+import json
+import datetime
+
+
+# 输出处理常量
+MAX_OUTPUT_LENGTH = 10000
+TRUNCATE_PREFIX_LENGTH = 5000
+TRUNCATE_SUFFIX_LENGTH = 5000
+SUMMARY_STDOUT_LENGTH = 300
+SUMMARY_STDERR_LENGTH = 200
+
+
+def truncate_output(text):
+    """截断过长的输出文本。
+    
+    Args:
+        text (str): 需要截断的文本
+        
+    Returns:
+        str: 截断后的文本
+    """
+    if len(text) <= MAX_OUTPUT_LENGTH:
+        return text
+    return (text[:TRUNCATE_PREFIX_LENGTH] + 
+            "\n...输出太长已省略...\n" + 
+            text[-TRUNCATE_SUFFIX_LENGTH:])
+
+
+def get_status_info(exit_code):
+    """获取执行状态信息。
+    
+    Args:
+        exit_code (int): 退出码
+        
+    Returns:
+        tuple: (状态图标, 状态文本) 元组
+    """
+    if exit_code == 0:
+        return "✅", "成功"
+    return "❌", "失败"
+
+
+def format_output_display(stdout, stderr, exit_code, tool_display_name):
+    """格式化输出显示文本。
+    
+    Args:
+        stdout (str): 标准输出
+        stderr (str): 错误输出
+        exit_code (int): 退出码
+        tool_display_name (str): 工具显示名称
+        
+    Returns:
+        str: 格式化的Markdown文本
+    """
+    status_icon, status_text = get_status_info(exit_code)
+    
+    display_parts = [
+        f"## {status_icon} {tool_display_name}处理{status_text}",
+        "",
+        "### 📋 处理结果",
+        f"- 退出码: {exit_code}",
+        "- 标准输出:",
+        "```",
+        stdout,
+        "```"
+    ]
+    
+    if stderr:
+        display_parts.extend([
+            "",
+            "### ⚠️ 错误/警告信息",
+            "```",
+            stderr,
+            "```"
+        ])
+    
+    return "\n".join(display_parts)
+
+
+def generate_summary(stdout, stderr, exit_code, tool_name):
+    """生成执行结果摘要。
+    
+    Args:
+        stdout (str): 标准输出
+        stderr (str): 错误输出
+        exit_code (int): 退出码
+        tool_name (str): 工具名称
+        
+    Returns:
+        str: 执行摘要文本
+    """
+    if exit_code != 0:
+        summary = f"{tool_name}执行失败（退出码: {exit_code}）。"
+        if stderr:
+            summary += f" 错误信息: {stderr[:SUMMARY_STDERR_LENGTH]}"
+        return summary
+    
+    if stderr:
+        summary = f"{tool_name}执行完成但有警告。"
+        summary += f" 输出: {stdout[:SUMMARY_STDERR_LENGTH]}"
+        summary += f" 警告: {stderr[:SUMMARY_STDERR_LENGTH]}"
+        return summary
+    
+    summary = f"{tool_name}执行成功。"
+    summary += f" 输出摘要: {stdout[:SUMMARY_STDOUT_LENGTH]}"
+    return summary
+
+
+class {{ name.replace("-", "_") }}_tool(Tool):
+    """
+    {{ description }}
+    
+    Args:
+        input_text (str): 输入的文本内容
+        mode (str, optional): 处理模式，可选值：basic、advanced
+    """
+    DISPLAY_NAME = "{{ display_name }}工具"
+    NETWORK = False
+    CPU = 1
+    GPU = 0
+    SIF = "adam-base:1.0.0"
+    
+    # 输出文件配置
+    OUTPUT_FILE = "output.txt"
+
+    def inputShow(self, **kwargs):
+        """AI决定使用该工具时调用，用于向用户展示当前调用的工具信息。
+        
+        Args:
+            kwargs (dict): 包含args、message、files、user、task_id等参数的字典。
+        
+        Returns:
+            str: 给用户显示的字符串（可使用markdown渲染）。
+        """
+        args = kwargs['args']
+        input_text = args['input_text']
+        mode = args.get('mode', 'basic')
+        
+        show_text = f"正在使用 {{ display_name }} 工具处理文本内容"
+        if mode == 'advanced':
+            show_text += "（高级模式）"
+        
+        return Tool.markdown_terminal(
+            show_text,
+            workdir=kwargs.get("task_id", ""),
+            user=kwargs.get("user", "Adam"),
+            conda_env=getattr(self, "CONDA_ENV", "base")
+        )
+
+    def call(self, kwargs):
+        """Tool 逻辑实现函数"""    
+        args = kwargs['args']
+        input_text = args['input_text']
+        mode = args.get('mode', 'basic')
+        
+        # TODO: 在这里实现你的主要逻辑
+        if mode == 'advanced':
+            result = f"高级模式处理: {input_text}"
+        else:
+            result = f"基础模式处理: {input_text}"
+        
+        # 生成bash命令
+        bash_script = f'''# {{ display_name }} 处理脚本
+echo "开始处理: {input_text}"
+echo "处理模式: {mode}"
+
+# TODO: 在这里添加实际的处理命令
+echo "{result}"
+
+# 生成输出文件
+echo "处理完成" > {self.OUTPUT_FILE}
+echo "结果: {result}" >> {self.OUTPUT_FILE}
+
+echo "处理完成，结果已保存到 {self.OUTPUT_FILE}"
+'''
+        
+        return runCmd(bash_script)
+    
+    def outputShow(self, kwargs):
+        """任务结束时调用，用于向用户展示工具执行结果。
+        
+        Args:
+            kwargs (dict): 包含stdout、stderr、exit_code等执行结果的字典。
+        
+        Returns:
+            tuple: (用户显示字符串, 文件列表) 元组。
+                - 用户显示字符串 (str): 格式化的显示文本
+                - 文件列表 (list): 生成的文件列表，会在前端提供下载
+        """
+        stdout = truncate_output(kwargs.get('stdout', ''))
+        stderr = truncate_output(kwargs.get('stderr', ''))
+        exit_code = kwargs.get('exit_code', 0)
+        
+        display_text = format_output_display(
+            stdout, stderr, exit_code, "{{ display_name }} "
+        )
+        
+        # 根据执行结果判断生成的文件
+        file_list = []
+        if exit_code == 0 or self.OUTPUT_FILE in kwargs.get('stdout', ''):
+            file_list.append(self.OUTPUT_FILE)
+        
+        return display_text, file_list
+    
+    def summary(self, kwargs):
+        """任务结束时调用，用于向AI提供执行结果摘要。
+        
+        Args:
+            kwargs (dict): 包含stdout、stderr、exit_code等执行结果的字典。
+        
+        Returns:
+            str: 给AI的文本摘要，应简洁明了，避免上下文过长。
+        """
+        stdout = truncate_output(kwargs.get('stdout', ''))
+        stderr = truncate_output(kwargs.get('stderr', ''))
+        exit_code = kwargs.get('exit_code', 0)
+        
+        return generate_summary(
+            stdout, stderr, exit_code, "{{ display_name }}工具"
+        )
+
+
+class {{ name.replace("-", "_") }}_advanced_tool(Tool, calltype="python"):    
+    """{{ description }} - 高级功能
+    
+    Args:
+        input_file (str): 输入文件路径
+        output_format (str): 输出格式，可选值：json、csv、txt
+    """    
+    DISPLAY_NAME = "{{ display_name }}高级工具"
+    NETWORK = False
+    CPU = 1
+    GPU = 0
+    SIF = "adam-base:1.0.0"
+    CONDA_ENV = "base"
+    
+    # 输出文件配置
+    OUTPUT_FILE = "result.json"
+    DEFAULT_OUTPUT_FORMAT = "json"
+
+    def inputShow(self, **kwargs):
+        """AI决定使用该工具时调用，用于向用户展示当前调用的工具信息。
+        
+        Args:
+            kwargs (dict): 包含args、message、files、user、task_id等参数的字典。
+        
+        Returns:
+            str: 给用户显示的字符串（可使用markdown渲染）。
+        """
+        args = kwargs['args']
+        input_file = args['input_file']
+        output_format = args.get('output_format', self.DEFAULT_OUTPUT_FORMAT)
+        
+        show_text = (f"正在使用 {{ display_name }} 高级工具处理文件: {input_file}"
+                    f"（输出格式: {output_format}）")
+        
+        return Tool.markdown_terminal(
+            show_text,
+            workdir=kwargs.get("task_id", ""),
+            user=kwargs.get("user", "Adam"),
+            conda_env=self.CONDA_ENV
+        )
+    
+    def call(self, kwargs):    
+        """Tool 逻辑实现函数"""
+        args = kwargs['args']
+        input_file = args['input_file']
+        output_format = args.get('output_format', self.DEFAULT_OUTPUT_FORMAT)
+        
+        # TODO: 在这里实现你的Python逻辑
+        result = {
+            'input_file': input_file,
+            'output_format': output_format,
+            'processed_at': datetime.datetime.now().isoformat(),
+            'result': 'Python工具处理完成'
+        }
+        
+        # 对于Python工具，必须使用print输出结果
+        print(f"Python工具处理完成，输入文件: {input_file}")
+        print(f"输出格式: {output_format}")
+        print(f"处理结果: {result}")
+        
+        # 生成输出文件
+        if output_format == 'json':
+            with open(self.OUTPUT_FILE, 'w', encoding='utf-8') as f:
+                json.dump(result, f, indent=2, ensure_ascii=False)
+            print(f"结果已保存到 {self.OUTPUT_FILE}")
+    
+    def outputShow(self, kwargs):
+        """任务结束时调用，用于向用户展示工具执行结果。
+        
+        Args:
+            kwargs (dict): 包含stdout、stderr、exit_code等执行结果的字典。
+        
+        Returns:
+            tuple: (用户显示字符串, 文件列表) 元组。
+                - 用户显示字符串 (str): 格式化的显示文本
+                - 文件列表 (list): 生成的文件列表，会在前端提供下载
+        """
+        stdout = truncate_output(kwargs.get('stdout', ''))
+        stderr = truncate_output(kwargs.get('stderr', ''))
+        exit_code = kwargs.get('exit_code', 0)
+        
+        display_text = format_output_display(
+            stdout, stderr, exit_code, "{{ display_name }} 高级工具"
+        )
+        
+        # 根据输出格式判断生成的文件
+        file_list = []
+        args = kwargs.get('args', {})
+        output_format = args.get('output_format', self.DEFAULT_OUTPUT_FORMAT)
+        if output_format == 'json' and exit_code == 0:
+            file_list.append(self.OUTPUT_FILE)
+        
+        return display_text, file_list
+    
+    def summary(self, kwargs):
+        """任务结束时调用，用于向AI提供执行结果摘要。
+        
+        Args:
+            kwargs (dict): 包含stdout、stderr、exit_code等执行结果的字典。
+        
+        Returns:
+            str: 给AI的文本摘要，应简洁明了，避免上下文过长。
+        """
+        stdout = truncate_output(kwargs.get('stdout', ''))
+        stderr = truncate_output(kwargs.get('stderr', ''))
+        exit_code = kwargs.get('exit_code', 0)
+        
+        return generate_summary(
+            stdout, stderr, exit_code, "{{ display_name }}高级工具"
+        )

{adam_community-1.0.23 → adam_community-1.0.25}/adam_community/util.py

@@ -10,6 +10,7 @@ import logging
 import ssl
 from functools import wraps
 from subprocess import run, CalledProcessError
+import time
 
 logger = logging.getLogger(__name__)
 
@@ -18,6 +19,7 @@ ADAM_API_TOKEN = os.getenv('ADAM_API_TOKEN')
 ADAM_TASK_ID = os.getenv('ADAM_TASK_ID')
 ADAM_USER_ID = os.getenv('ADAM_USER_ID')
 CONDA_ENV = os.getenv('CONDA_ENV')
+ADAM_TASK_DIR = os.getenv('ADAM_TASK_DIR')
 
 
 def _build_akb_query_command(query: str, collection: str) -> str:
@@ -368,3 +370,195 @@ def markdown_terminal(content, conda_env="base", user="Adam", workdir=""):
     user = markdown_color(f"{user}@Adam", "green")
     workdir = markdown_color(f":~/{workdir}", "blue")
     return f'({conda_env}) {user}{workdir}$ {content}'
+
+
+# ========== States Management ==========
+
+class _StatesManager:
+    """内部状态管理类"""
+    _tool_name = "tool"
+
+    def _get_states_file(self) -> str:
+        """获取 states.json 文件路径"""
+        # 1. 优先使用环境变量
+        task_dir = ADAM_TASK_DIR
+        if task_dir:
+            return os.path.join(task_dir, ".slurm", "states.json")
+
+        # 2. 尝试当前目录的 .slurm
+        current_dir = os.getcwd()
+        local_states = os.path.join(current_dir, ".slurm", "states.json")
+        if os.path.exists(local_states):
+            return local_states
+
+        # 3. 在当前目录创建
+        return local_states
+
+    def _read(self) -> dict:
+        """读取 states.json，保留所有来源的数据"""
+        states_file = self._get_states_file()
+        if not os.path.exists(states_file):
+            return {
+                "files": {"updated_at": None, "sources": {}},
+                "states": {"source": None, "updated_at": None, "data": {}}
+            }
+        try:
+            with open(states_file, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            return {
+                "files": {"updated_at": None, "sources": {}},
+                "states": {"source": None, "updated_at": None, "data": {}}
+            }
+
+    def _write(self, data: dict):
+        """写入 states.json"""
+        states_file = self._get_states_file()
+        os.makedirs(os.path.dirname(states_file), exist_ok=True)
+        with open(states_file, 'w', encoding='utf-8') as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+
+    def _set_nested(self, data: dict, key: str, value):
+        """设置嵌套值，支持 dot notation"""
+        keys = key.split('.')
+        current = data
+        for k in keys[:-1]:
+            current = current.setdefault(k, {})
+        current[keys[-1]] = value
+
+    def _get_nested(self, data: dict, key: str, default=None):
+        """获取嵌套值，支持 dot notation"""
+        keys = key.split('.')
+        current = data
+        for k in keys:
+            if isinstance(current, dict):
+                current = current.get(k)
+            else:
+                return default
+            if current is None:
+                return default
+        return current
+
+    def set(self, key: str, value):
+        """
+        设置状态
+
+        特殊 key:
+            "files" - 记录文件列表，会自动补充到 files.sources[tool_name]
+            其他 - 记录到 states.data
+        """
+        data = self._read()
+
+        if key == "files":
+            data["files"]["sources"][self._tool_name] = {
+                "updated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                "items": value
+            }
+        else:
+            self._set_nested(data["states"]["data"], key, value)
+
+        self._write(data)
+
+    def get(self, key: str):
+        """
+        获取状态
+
+        Returns:
+            状态值，不存在返回 None
+        """
+        data = self._read()
+
+        if key == "files":
+            # 合并所有来源的文件列表
+            merged = {}
+            for source, content in data["files"]["sources"].items():
+                for item in content.get("items", []):
+                    path = item.get("path")
+                    if not path:
+                        continue
+                    mtime = item.get("mtime", 0)
+                    if path not in merged or mtime > merged[path]["mtime"]:
+                        merged[path] = item
+            result = list(merged.values())
+            # 按 mtime 降序排序
+            result.sort(key=lambda x: x.get("mtime", 0), reverse=True)
+            return result
+
+        return self._get_nested(data["states"]["data"], key)
+
+    def cleanup(self):
+        """清理当前工具的所有记录"""
+        data = self._read()
+        data["files"]["sources"].pop(self._tool_name, None)
+        self._write(data)
+
+    def trackPath(self, path: str, max_items: int = 30):
+        """
+        追踪文件/目录，自动检测文件信息并记录
+
+        Args:
+            path: 文件或目录路径
+            max_items: 最大记录数量，先进先出
+        """
+        if not os.path.exists(path):
+            return
+
+        # 检测文件信息
+        try:
+            is_dir = os.path.isdir(path)
+            mtime = int(os.path.getmtime(path))
+            # 从环境变量获取 task_dir
+            task_dir = os.getenv('ADAM_TASK_DIR')
+            if task_dir:
+                rel_path = os.path.relpath(path, task_dir)
+            else:
+                rel_path = path
+        except (OSError, ValueError):
+            return
+
+        # 获取当前文件列表
+        data = self._read()
+        source = self._tool_name
+        items = data["files"]["sources"].get(source, {}).get("items", [])
+
+        # 检查是否已存在相同路径，存在则移除（后面会加到末尾，保持最新追踪的在最后）
+        items = [item for item in items if item.get("path") != rel_path]
+
+        # 添加到末尾（最新的位置）
+        items.append({"path": rel_path, "is_dir": is_dir, "mtime": mtime})
+
+        # 先进先出，保留最多 max_items 条
+        if len(items) > max_items:
+            items = items[-max_items:]
+
+        # 写回
+        data["files"]["sources"][source] = {
+            "updated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "items": items
+        }
+        self._write(data)
+
+
+# 全局实例
+_states = _StatesManager()
+
+
+def setState(key: str, value):
+    """设置状态"""
+    return _states.set(key, value)
+
+
+def getState(key: str):
+    """获取状态"""
+    return _states.get(key)
+
+
+def trackPath(path: str, max_items: int = 30):
+    """
+    追踪文件/目录，自动检测文件信息并记录
+
+    Args:
+        path: 文件或目录路径
+        max_items: 最大记录数量，先进先出，默认 30
+    """
+    return _states.trackPath(path, max_items)

{adam_community-1.0.23 → adam_community-1.0.25}/adam_community.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: adam_community
-Version: 1.0.23
+Version: 1.0.25
 Summary: Adam Community Tools and Utilities
 Home-page: https://github.com/yourusername/adam-community
 Author: Adam Community
@@ -80,6 +80,35 @@ classes = parse_directory(Path("./"))
 success, errors, zip_name = build_package(Path("./"))
 ```
 
+### States Management（任务状态管理）
+
+用于在任务执行过程中记录和读取状态，与服务端共享 `states.json` 文件。
+
+```python
+from adam_community.util import setState, getState, trackPath
+
+# 记录文件列表（自动与服务端和其他 Tool 的文件合并）
+setState("files", [
+    {"path": "output/result.json", "is_dir": False, "mtime": 1704100800},
+    {"path": "cache", "is_dir": True, "mtime": 1704100000}
+])
+
+# 获取合并后的文件列表（来自 server + 所有 tools）
+files = getState("files")
+
+# 记录自定义状态（支持嵌套 key）
+setState("stage", "data_cleaning")
+setState("config.threshold", 0.5)
+
+# 获取状态
+stage = getState("stage")              # -> "data_cleaning"
+threshold = getState("config.threshold")  # -> 0.5
+
+# 追踪文件/目录（自动检测 is_dir 和 mtime，先进先出，最多 30 条）
+trackPath("/path/to/output/result.json")
+trackPath("/path/to/cache")
+```
+
 ## 功能特性
 
 - **Python 文件解析**: 自动解析 Python 类和函数的文档字符串