adam-community 1.0.28__py3-none-any.whl → 1.0.29__py3-none-any.whl

adam_community/__init__.py

@@ -1,15 +1,17 @@
-from .util import messageSend, knowledgeSearch, completionCreate, runCmd
+from .util import messageSend, knowledgeSearch, completionCreate, runCmd, execCmd, CmdResult
 from .tool import Tool
 from .cli.parser import parse_python_file, parse_directory, convert_python_type_to_json_schema
 from .__version__ import __version__
 
 __all__ = [
-    'Tool', 
-    'messageSend', 
-    'knowledgeSearch', 
-    'completionCreate', 
+    'Tool',
+    'messageSend',
+    'knowledgeSearch',
+    'completionCreate',
     'runCmd',
+    'execCmd',
+    'CmdResult',
     'parse_python_file',
-    'parse_directory', 
+    'parse_directory',
     'convert_python_type_to_json_schema'
 ]

adam_community/__version__.py

@@ -1 +1 @@
-__version__ = "1.0.28"
+__version__ = "1.0.29"

adam_community/util/__init__.py

@@ -0,0 +1,73 @@
+# Re-export all public APIs to maintain backward compatibility
+# Usage: from adam_community.util import execCmd, runCmd, ...
+
+from .config import (
+    ADAM_API_HOST,
+    ADAM_API_TOKEN,
+    ADAM_TASK_ID,
+    ADAM_USER_ID,
+    CONDA_ENV,
+    ADAM_TASK_DIR,
+)
+
+from .cmd import (
+    runCmd,
+    execCmd,
+    CmdResult,
+)
+
+from .api import (
+    retry_on_exception,
+    _make_http_request,
+    messageSend,
+    completionCreate,
+    DynamicObject,
+)
+
+from .rag import (
+    RAG,
+    knowledgeSearch,
+)
+
+from .state import (
+    _StatesManager,
+    setState,
+    getState,
+    trackPath,
+)
+
+from .markdown import (
+    markdown_color,
+    markdown_terminal,
+)
+
+__all__ = [
+    # config
+    'ADAM_API_HOST',
+    'ADAM_API_TOKEN',
+    'ADAM_TASK_ID',
+    'ADAM_USER_ID',
+    'CONDA_ENV',
+    'ADAM_TASK_DIR',
+    # cmd
+    'runCmd',
+    'execCmd',
+    'CmdResult',
+    # api
+    'retry_on_exception',
+    '_make_http_request',
+    'messageSend',
+    'completionCreate',
+    'DynamicObject',
+    # rag
+    'RAG',
+    'knowledgeSearch',
+    # state
+    '_StatesManager',
+    'setState',
+    'getState',
+    'trackPath',
+    # markdown
+    'markdown_color',
+    'markdown_terminal',
+]

adam_community/util/api.py

@@ -0,0 +1,178 @@
+import time
+import urllib.request
+import urllib.error
+import json
+import ssl
+from functools import wraps
+
+from .config import ADAM_API_HOST, ADAM_API_TOKEN, ADAM_TASK_ID
+
+
+def retry_on_exception(max_retries=3, delay=5):
+    """
+    重试装饰器，在发生异常时最多重试指定次数
+
+    Args:
+        max_retries: 最大重试次数
+        delay: 重试间隔时间（秒）
+    """
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            last_exception = None
+            for attempt in range(max_retries):
+                try:
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    last_exception = e
+                    if attempt < max_retries - 1:
+                        time.sleep(delay)
+                        continue
+                    raise last_exception
+            return None
+        return wrapper
+    return decorator
+
+
+def _make_http_request(url, data, return_json=True):
+    """
+    通用的 HTTP POST 请求函数
+
+    Args:
+        url: 请求的 URL
+        data: 请求数据（字典格式）
+        return_json: 是否将响应解析为 JSON，False 则返回文本
+
+    Returns:
+        响应数据（JSON 或文本）
+    """
+    if not ADAM_API_TOKEN:
+        raise ValueError("ADAM_API_TOKEN environment variable is not set")
+
+    headers = {
+        "Authorization": f"Bearer {ADAM_API_TOKEN}",
+        "Content-Type": "application/json"
+    }
+
+    try:
+        # 将请求数据转换为JSON字符串并编码
+        json_data = json.dumps(data).encode('utf-8')
+
+        # 创建请求对象
+        req = urllib.request.Request(url, data=json_data, headers=headers, method='POST')
+
+        context = ssl._create_unverified_context()
+
+        # 发送请求
+        with urllib.request.urlopen(req, context=context) as response:
+            # 检查响应状态码
+            if response.status >= 400:
+                raise Exception(f"HTTP错误: {response.status}")
+
+            # 读取响应
+            response_data = response.read().decode('utf-8')
+
+            # 根据需要返回 JSON 或文本
+            if return_json:
+                return json.loads(response_data)
+            else:
+                return response_data
+
+    except urllib.error.HTTPError as e:
+        raise Exception(f"HTTP请求失败 - HTTP错误 {e.code}: {e.reason}")
+    except urllib.error.URLError as e:
+        raise Exception(f"HTTP请求失败 - 网络错误: {str(e)}")
+    except json.JSONDecodeError as e:
+        if return_json:
+            raise Exception(f"HTTP请求失败 - JSON解析错误: {str(e)}")
+        else:
+            raise Exception(f"HTTP请求失败 - 响应解码错误: {str(e)}")
+    except Exception as e:
+        raise Exception(f"HTTP请求失败: {str(e)}")
+
+
+def messageSend(message):
+    """
+    发送消息给用户
+    """
+    if not ADAM_API_HOST:
+        raise ValueError("ADAM_API_HOST environment variable is not set")
+    if not ADAM_TASK_ID:
+        raise ValueError("ADAM_TASK_ID environment variable is not set")
+
+    url = f"{ADAM_API_HOST}/api/task/create_message"
+
+    request_data = {
+        "task_id": ADAM_TASK_ID,
+        "message": message,
+        "role": "tool"
+    }
+
+    try:
+        return _make_http_request(url, request_data, return_json=True)
+    except Exception as e:
+        raise Exception(f"发送消息失败: {str(e)}")
+
+
+class DynamicObject:
+    """
+    动态对象类，用于处理 JSON 响应
+
+    这个类可以动态地将字典转换为对象属性，支持嵌套的字典结构
+    同时保持原始数据的访问能力
+    """
+    def __init__(self, data):
+        self._raw_data = data
+        if isinstance(data, dict):
+            for key, value in data.items():
+                if isinstance(value, (dict, list)):
+                    setattr(self, key, self._convert_value(value))
+                else:
+                    setattr(self, key, value)
+
+    def _convert_value(self, value):
+        """递归转换嵌套的数据结构"""
+        if isinstance(value, dict):
+            return DynamicObject(value)
+        elif isinstance(value, list):
+            return [self._convert_value(item) for item in value]
+        return value
+
+    def __getattr__(self, name):
+        """处理未定义的属性访问"""
+        return self._raw_data.get(name)
+
+    def __getitem__(self, key):
+        """支持字典式访问"""
+        return self._raw_data.get(key)
+
+    def __str__(self):
+        """返回可读的字符串表示"""
+        return f"DynamicObject({self._raw_data})"
+
+    def __repr__(self):
+        return self.__str__()
+
+    def to_dict(self):
+        """将对象转换回字典"""
+        return self._raw_data
+
+
+@retry_on_exception(max_retries=3)
+def completionCreate(request_params):
+    """
+    创建 openai 的代理函数
+
+    Returns:
+        DynamicObject: 一个动态对象，可以像访问属性一样访问 API 响应的所有字段
+    """
+    if not ADAM_API_HOST:
+        raise ValueError("ADAM_API_HOST environment variable is not set")
+
+    url = f"{ADAM_API_HOST}/api/chat/completions"
+
+    try:
+        response = _make_http_request(url, request_params, return_json=True)
+        return DynamicObject(response)
+    except Exception as e:
+        raise Exception(f"调用聊天补全接口失败: {str(e)}")

adam_community/util/cmd.py

@@ -0,0 +1,166 @@
+import subprocess
+import sys
+import os
+import time
+import threading
+from dataclasses import dataclass
+from typing import Callable, Optional
+from subprocess import CalledProcessError, TimeoutExpired
+
+
+@dataclass
+class CmdResult:
+    """命令执行结果"""
+    stdout: str
+    stderr: str
+    returncode: int
+    duration: float
+    command: str
+    timed_out: bool = False
+
+
+def execCmd(
+    cmd: str,
+    *,
+    timeout: Optional[float] = None,
+    cwd: Optional[str] = None,
+    env: Optional[dict] = None,
+    shell: str = "/bin/bash",
+    echo: bool = False,
+    on_stdout: Optional[Callable[[str], None]] = None,
+    on_stderr: Optional[Callable[[str], None]] = None,
+) -> CmdResult:
+    """
+    执行 shell 命令
+
+    Args:
+        cmd: 要执行的命令
+        timeout: 超时秒数，None 表示无限制
+        cwd: 工作目录
+        env: 环境变量（合并到当前环境）
+        shell: shell 路径，默认 /bin/bash
+        echo: 是否实时打印到控制台
+        on_stdout: stdout 回调函数，签名 (line: str) -> None
+        on_stderr: stderr 回调函数，签名 (line: str) -> None
+
+    Returns:
+        CmdResult: 包含 stdout, stderr, returncode, duration, command, timed_out
+
+    Raises:
+        subprocess.CalledProcessError: 命令返回非零退出码
+        subprocess.TimeoutExpired: 命令执行超时
+    """
+    # 合并环境变量
+    process_env = os.environ.copy()
+    if env:
+        process_env.update(env)
+
+    start_time = time.time()
+    stdout_lines = []
+    stderr_lines = []
+
+    process = subprocess.Popen(
+        cmd,
+        shell=True,
+        executable=shell,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        universal_newlines=True,
+        bufsize=1,
+        cwd=cwd,
+        env=process_env,
+    )
+
+    def read_stream(stream, lines_buffer, callback, is_stderr=False):
+        """读取流并处理输出"""
+        for line in iter(stream.readline, ''):
+            line = line.rstrip('\n\r')
+            lines_buffer.append(line)
+            if echo:
+                if is_stderr:
+                    print(line, file=sys.stderr)
+                else:
+                    print(line)
+            if callback:
+                callback(line)
+        stream.close()
+
+    # 使用线程并发读取 stdout 和 stderr
+    stdout_thread = threading.Thread(
+        target=read_stream,
+        args=(process.stdout, stdout_lines, on_stdout, False)
+    )
+    stderr_thread = threading.Thread(
+        target=read_stream,
+        args=(process.stderr, stderr_lines, on_stderr, True)
+    )
+
+    stdout_thread.start()
+    stderr_thread.start()
+
+    # 等待进程完成或超时
+    timed_out = False
+    try:
+        process.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        timed_out = True
+        process.kill()
+        # 等待线程完成读取剩余输出
+        stdout_thread.join(timeout=1)
+        stderr_thread.join(timeout=1)
+
+        duration = time.time() - start_time
+        stdout_str = '\n'.join(stdout_lines)
+        stderr_str = '\n'.join(stderr_lines)
+
+        raise TimeoutExpired(
+            cmd=cmd,
+            timeout=timeout,
+            output=stdout_str,
+            stderr=stderr_str,
+        )
+
+    # 等待线程完成
+    stdout_thread.join()
+    stderr_thread.join()
+
+    duration = time.time() - start_time
+    stdout_str = '\n'.join(stdout_lines)
+    stderr_str = '\n'.join(stderr_lines)
+
+    # 检查返回码
+    if process.returncode != 0:
+        raise CalledProcessError(
+            returncode=process.returncode,
+            cmd=cmd,
+            output=stdout_str,
+            stderr=stderr_str,
+        )
+
+    return CmdResult(
+        stdout=stdout_str,
+        stderr=stderr_str,
+        returncode=process.returncode,
+        duration=duration,
+        command=cmd,
+        timed_out=False,
+    )
+
+
+def runCmd(cmd):
+    """
+    执行命令，实时输出执行结果（向后兼容）
+
+    内部调用 execCmd，失败时直接退出进程。
+    推荐使用 execCmd 以获得更好的错误处理能力。
+
+    Args:
+        cmd: 要执行的命令
+
+    Returns:
+        CmdResult: 命令执行结果
+    """
+    if os.getenv("ADAM_OUTPUT_RAW"):
+        return cmd
+
+    return execCmd(cmd, echo=True)

adam_community/util/config.py

@@ -0,0 +1,8 @@
+import os
+
+ADAM_API_HOST = os.getenv('ADAM_API_HOST', 'https://sidereus-ai.com')
+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')

adam_community/util/markdown.py

@@ -0,0 +1,8 @@
+def markdown_color(content, color):
+    return f'<span style="color: {color}">{content}</span>'
+
+
+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}'

adam_community/util/rag.py

@@ -0,0 +1,126 @@
+import json
+import logging
+from subprocess import run, CalledProcessError
+
+from .api import retry_on_exception
+
+logger = logging.getLogger(__name__)
+
+
+def _build_akb_query_command(query: str, collection: str) -> str:
+    """
+    构建 akb 查询命令，包含目录存在性检查
+
+    Args:
+        query: 查询字符串
+        collection: 知识库名称
+
+    Returns:
+        完整的 bash 命令字符串
+    """
+    collection_dir = f"/share/programs/akb/database/{collection}"
+
+    return f"""if [ ! -d "{collection_dir}" ]; then
+    echo "知识库目录不存在: {collection_dir}"
+    exit 1
+fi
+akb simple-query \\
+    -i {collection_dir}/{collection}.index \\
+    -m /share/programs/BAAI/bge-m3 \\
+    -p {collection_dir}/{collection}.parquet \\
+    -l 5 \\
+    -f json -q "{query}\""""
+
+
+class RAG:
+    """
+    搜寻RAG知识
+
+    :param str query: 需要运行的命令
+    :param str collection: 搜寻的知识库名称。必须是下面之一："DSDP","MPNN","PySCF","RFdiffusion","gaussian","protenix","GPU4PySCF","MolecularDynamics","RDkit","OpenBabel"
+    """
+
+    def call(self, query: str, collection: str):
+        cmd = _build_akb_query_command(query, collection)
+        logger.info(f"搜索知识库 {collection}: {query}")
+
+        try:
+            result = run(cmd, shell='/bin/bash', check=True, text=True, capture_output=True)
+        except CalledProcessError as e:
+            logger.error(e.stderr.strip())
+            return e.stderr.strip()
+
+        try:
+            parsed_data = json.loads(result.stdout)
+            # 如果返回的是数组，直接使用
+            if isinstance(parsed_data, list):
+                return "\n".join(parsed_data)
+            # 如果返回的是对象且包含 text 字段，使用 text 字段
+            elif isinstance(parsed_data, dict) and "text" in parsed_data:
+                text_array = parsed_data["text"]
+                if isinstance(text_array, list):
+                    return "\n".join(text_array)
+                else:
+                    return str(text_array)
+            else:
+                # 其他情况返回原始输出
+                return result.stdout
+        except Exception as e:
+            logger.error(e)
+            return result.stdout
+
+
+@retry_on_exception(max_retries=3)
+def knowledgeSearch(query_info, messages_prev, project_name, collection_name, max_messages=4):
+    """
+    知识库检索函数
+    """
+    if not collection_name:
+        raise ValueError("collection_name 参数是必需的")
+
+    try:
+        # 使用本地RAG实现
+        rag = RAG()
+        result = rag.call(query_info, collection_name)
+
+        # 构造返回格式，保持与原有API格式一致
+        response_data = {
+            "code": 0,
+            "data": {
+                "collection_name": collection_name,
+                "count": 1,
+                "result_list": [{
+                    "chunk_id": 0,
+                    "chunk_source": "document",
+                    "chunk_title": result.split("\n")[0] if result else "",
+                    "chunk_type": "text",
+                    "content": result,
+                    "doc_info": {
+                        "create_time": 0,
+                        "doc_id": "local_doc",
+                        "doc_name": f"{collection_name}_knowledge",
+                        "doc_type": "text",
+                        "source": "local"
+                    },
+                    "score": 1.0
+                }],
+                "token_usage": {
+                    "embedding_token_usage": {
+                        "completion_tokens": 0,
+                        "prompt_tokens": 0,
+                        "total_tokens": 0
+                    },
+                    "rerank_token_usage": 0
+                }
+            },
+            "message": "success",
+            "request_id": "local_request"
+        }
+
+        return json.dumps(response_data, ensure_ascii=False)
+    except Exception as e:
+        error_response = {
+            "code": 1,
+            "message": f"知识库搜索失败: {str(e)}"
+        }
+        return json.dumps(error_response, ensure_ascii=False)

adam_community/util/state.py

@@ -0,0 +1,195 @@
+import os
+import json
+import time
+
+from .config import ADAM_TASK_DIR
+
+
+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.28.dist-info → adam_community-1.0.29.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: adam_community
-Version: 1.0.28
+Version: 1.0.29
 Summary: Adam Community Tools and Utilities
 Home-page: https://github.com/yourusername/adam-community
 Author: Adam Community
@@ -97,6 +97,83 @@ classes = parse_directory(Path("./"))
 success, errors, zip_name = build_package(Path("./"))
 ```
 
+### 命令执行
+
+#### execCmd - 复杂执行
+
+`execCmd` 是新的命令执行函数，支持异常处理、超时控制、实时输出等特性。
+
+```python
+from adam_community import execCmd, CmdResult
+from subprocess import CalledProcessError, TimeoutExpired
+
+# 基本用法
+result = execCmd("python train.py")
+print(result.stdout)      # 标准输出
+print(result.stderr)      # 错误输出
+print(result.returncode)  # 退出码
+print(result.duration)    # 执行耗时（秒）
+
+# 异常处理
+try:
+    result = execCmd("python train.py", timeout=3600)
+except TimeoutExpired as e:
+    print(f"超时: {e.output}")
+except CalledProcessError as e:
+    print(f"失败 (exit {e.returncode}): {e.stderr}")
+
+# 实时输出到控制台
+result = execCmd("python train.py", echo=True)
+
+# 自定义回调（如写日志、发送到前端）
+result = execCmd(
+    "python train.py",
+    on_stdout=lambda line: logger.info(f"[OUT] {line}"),
+    on_stderr=lambda line: logger.error(f"[ERR] {line}"),
+)
+
+# 指定工作目录和环境变量
+result = execCmd(
+    "python train.py",
+    cwd="/workspace/project",
+    env={"CUDA_VISIBLE_DEVICES": "0,1"},  # 合并到当前环境
+)
+```
+
+**参数说明：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `cmd` | str | - | 要执行的命令 |
+| `timeout` | float | None | 超时秒数，None 表示无限制 |
+| `cwd` | str | None | 工作目录 |
+| `env` | dict | None | 环境变量（合并到当前环境） |
+| `shell` | str | /bin/bash | shell 路径 |
+| `echo` | bool | False | 是否实时打印到控制台 |
+| `on_stdout` | Callable | None | stdout 回调 `(line: str) -> None` |
+| `on_stderr` | Callable | None | stderr 回调 `(line: str) -> None` |
+
+**返回值 `CmdResult`：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `stdout` | str | 完整标准输出 |
+| `stderr` | str | 完整错误输出 |
+| `returncode` | int | 退出码 |
+| `duration` | float | 执行耗时（秒） |
+| `command` | str | 原始命令 |
+| `timed_out` | bool | 是否超时 |
+
+#### runCmd - 最简执行
+
+`runCmd` 是最简化版命令执行函数，实时输出到控制台，失败时直接退出进程。
+
+```python
+from adam_community import runCmd
+
+runCmd("echo 'Hello, World!'")
+```
+
 ### States Management（任务状态管理）
 
 用于在任务执行过程中记录和读取状态，与服务端共享 `states.json` 文件。

{adam_community-1.0.28.dist-info → adam_community-1.0.29.dist-info}/RECORD

@@ -1,5 +1,5 @@
-adam_community/__init__.py,sha256=vAmF9VQR6D4peppH0hnrHDmZK5cFeFPh11GIsTKUXhE,429
-adam_community/__version__.py,sha256=pC0eKGXF1PH-qw7ZFRVVeFacCzuUE-x6jPc3T4w6jNc,23
+adam_community/__init__.py,sha256=Sw3CfnL8xXYAzTXg6egENLO5IYksBLe_ivVNU20W514,476
+adam_community/__version__.py,sha256=BBmi5TxVi3pzemafZwdH6Fv0y3TGRe8rQn6QWN0sJDw,23
 adam_community/tool.py,sha256=F6jxRU3urqTfgjLIZSW-hVWyj0FpNwvY65jOODXI19w,4954
 adam_community/util.py,sha256=SDXnWLHLfJxEJ5WBnwNq_FeHNwXxGK_F36dpI_hVkNc,17766
 adam_community/cli/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
@@ -26,8 +26,15 @@ adam_community/cli/templates/long_description.md.j2,sha256=Rj6hcuNzEL0Sp17GQVCRJ
 adam_community/cli/templates/long_description_en.md.j2,sha256=xSbahwGarXlWopZqHw7lrcv1dQuvwj2ChhZv5pJmUy4,1725
 adam_community/cli/templates/rag_python.py.j2,sha256=YJL7-WIx-Dumt7lHuUGxl3Rbaw0kpkh8hpcCJ5lz9lA,2494
 adam_community/cli/templates/toolbox_python.py.j2,sha256=EOnmsJUvQRrcO7K7c88kI42gMmcM0Z4ab46qwOJXbH8,4192
-adam_community-1.0.28.dist-info/METADATA,sha256=pCes8Oix7qsB1Y_aBOWD9855DjLGW7GlDHgbClDVZF4,3628
-adam_community-1.0.28.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-adam_community-1.0.28.dist-info/entry_points.txt,sha256=4I7yRkn7cHwPY8-fWQLeAvKjc24zUy8Z65VsZNs0Wos,56
-adam_community-1.0.28.dist-info/top_level.txt,sha256=MS8jbePXKZChih9kGizNVX0I1MFZFGWBMCIW_r86qhU,15
-adam_community-1.0.28.dist-info/RECORD,,
+adam_community/util/__init__.py,sha256=HJOq2_G5hTl9GM2MmRtj7cD60oBB-4ikU5pbOjoDTZ4,1178
+adam_community/util/api.py,sha256=1msEvAY-cG2vYyrMH7OybVXYeAO1il8axtGSS0SSWWk,5367
+adam_community/util/cmd.py,sha256=LghuiDaPoikvnRA1G19SgczF8M7hZ3hSTeHKt4vIZKY,4264
+adam_community/util/config.py,sha256=On5t0kl1kD34tld5X30LwKqGsX0_WBG7vYVR7XTaT94,286
+adam_community/util/markdown.py,sha256=iT9zX3c0mO3VLrJEhPyqe285aQoLtfxirTbHlL8Jnek,333
+adam_community/util/rag.py,sha256=B7mju5YQmuvJddcsYXha4vkkJdvYDwVKrqmIQ3T_tmk,4147
+adam_community/util/state.py,sha256=NRZ2mIgj_-Ykwbun1XsyfJSWv4BPvEgLaHQHbSNIwZ0,6073
+adam_community-1.0.29.dist-info/METADATA,sha256=C6KbAAiVt4Rs9iGGbAK35NhnaFI1iXKPnpGrKxwpRmY,5891
+adam_community-1.0.29.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+adam_community-1.0.29.dist-info/entry_points.txt,sha256=4I7yRkn7cHwPY8-fWQLeAvKjc24zUy8Z65VsZNs0Wos,56
+adam_community-1.0.29.dist-info/top_level.txt,sha256=MS8jbePXKZChih9kGizNVX0I1MFZFGWBMCIW_r86qhU,15
+adam_community-1.0.29.dist-info/RECORD,,