myagent-ai 1.31.3 → 1.32.0

package/core/workflow_engine.py

@@ -0,0 +1,1002 @@
+"""
+core/workflow_engine.py - 工作流引擎模块
+==========================================
+类似 GitHub Actions 的 Agent 工作流系统，支持:
+  - 每个 Agent 拥有独立工作流空间
+  - 步骤式执行 (browser / shell / api / condition / delay ...)
+  - 模板变量引用 {{steps.N.result}} / {{variables.xxx}}
+  - 完整的执行记录与日志
+  - 线程安全操作
+"""
+from __future__ import annotations
+
+import ast
+import asyncio
+import json
+import os
+import re
+import shutil
+import subprocess
+import threading
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from core.logger import get_logger
+from core.utils import generate_id, sanitize_filename, timestamp, truncate_str
+
+logger = get_logger("myagent.workflow")
+
+# ---------------------------------------------------------------------------
+# 路径安全：防止 agent_path / workflow_id 中的目录遍历攻击
+# ---------------------------------------------------------------------------
+_SAFE_PATH_RE = re.compile(r"^[\w.\-]+$")
+
+
+def _safe_path_segment(value: str, field_name: str = "path") -> str:
+    """校验路径段，只允许 字母/数字/下划线/点/横线，防止目录遍历。"""
+    if not value or not _SAFE_PATH_RE.match(value):
+        raise ValueError(
+            f"非法 {field_name}: '{value}'，只允许字母、数字、下划线、点和横线"
+        )
+    return value
+
+
+# ---------------------------------------------------------------------------
+# 安全表达式求值 (用于 condition 步骤)
+# ---------------------------------------------------------------------------
+_ALLOWED_BUILTINS = {
+    "len": len,
+    "str": str,
+    "int": int,
+    "float": float,
+    "bool": bool,
+    "list": list,
+    "dict": dict,
+    "abs": abs,
+    "min": min,
+    "max": max,
+    "sum": sum,
+    "round": round,
+    "True": True,
+    "False": False,
+    "None": None,
+}
+
+
+def _safe_eval(expression: str, context: Dict) -> bool:
+    """
+    安全地求值条件表达式。
+
+    只允许简单的比较和算术运算，通过 AST 白名单限制可用的节点类型。
+    context 中包含 ``steps`` 字典和 ``variables`` 字典。
+    """
+    try:
+        tree = ast.parse(expression.strip(), mode="eval")
+    except SyntaxError as exc:
+        raise ValueError(f"条件表达式语法错误: {exc}") from exc
+
+    # 仅允许的 AST 节点类型
+    allowed_nodes = (
+        ast.Expression,
+        ast.BoolOp,
+        ast.And,
+        ast.Or,
+        ast.Not,
+        ast.Compare,
+        ast.Eq,
+        ast.NotEq,
+        ast.Lt,
+        ast.LtE,
+        ast.Gt,
+        ast.GtE,
+        ast.In,
+        ast.NotIn,
+        ast.Is,
+        ast.IsNot,
+        ast.Call,
+        ast.Constant,
+        ast.Name,
+        ast.Attribute,
+        ast.Subscript,
+        ast.Load,
+        ast.UnaryOp,
+        ast.UAdd,
+        ast.USub,
+        ast.BinOp,
+        ast.Add,
+        ast.Sub,
+        ast.Mult,
+        ast.Div,
+        ast.Mod,
+        ast.Num,
+        ast.Str,
+    )
+
+    for node in ast.walk(tree):
+        if not isinstance(node, allowed_nodes):
+            raise ValueError(
+                f"条件表达式包含不允许的操作: {ast.dump(node)}"
+            )
+
+    # 编译并执行
+    code = compile(tree, "<condition>", "eval")
+    result = eval(code, {"__builtins__": _ALLOWED_BUILTINS}, context)  # noqa: S307
+    return bool(result)
+
+
+# ===========================================================================
+# WorkflowEngine
+# ===========================================================================
+
+
+class WorkflowEngine:
+    """工作流引擎：管理 Agent 工作流的 CRUD 与执行。
+
+    存储布局::
+
+        <data_dir>/workflows/<agent_path>/<workflow_id>.json
+        <data_dir>/workflows/<agent_path>/runs/<run_id>.json
+    """
+
+    def __init__(self, data_dir: Path | str | None = None) -> None:
+        if data_dir is None:
+            data_dir = Path.home() / ".myagent" / "data"
+        self._data_dir = Path(data_dir)
+        self._workflows_base = self._data_dir / "workflows"
+        self._lock = threading.Lock()
+
+    # ------------------------------------------------------------------
+    # 内部路径辅助
+    # ------------------------------------------------------------------
+
+    def _agent_dir(self, agent_path: str) -> Path:
+        """返回 Agent 的工作流目录。"""
+        _safe_path_segment(agent_path, "agent_path")
+        return self._workflows_base / agent_path
+
+    def _workflow_file(self, agent_path: str, workflow_id: str) -> Path:
+        _safe_path_segment(workflow_id, "workflow_id")
+        return self._agent_dir(agent_path) / f"{workflow_id}.json"
+
+    def _runs_dir(self, agent_path: str) -> Path:
+        return self._agent_dir(agent_path) / "runs"
+
+    def _run_file(self, agent_path: str, run_id: str) -> Path:
+        _safe_path_segment(run_id, "run_id")
+        return self._runs_dir(agent_path) / f"{run_id}.json"
+
+    # ------------------------------------------------------------------
+    # 读取 / 写入工具
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _read_json(path: Path) -> Optional[Dict]:
+        """安全读取 JSON 文件。"""
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except (FileNotFoundError, json.JSONDecodeError, OSError) as exc:
+            logger.warning("读取 JSON 失败 %s: %s", path, exc)
+            return None
+
+    @staticmethod
+    def _write_json(path: Path, data: Dict) -> None:
+        """写入 JSON 文件（pretty-print）。"""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps(data, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+
+    # ------------------------------------------------------------------
+    # CRUD
+    # ------------------------------------------------------------------
+
+    def list_workflows(self, agent_path: str | None = None) -> List[Dict]:
+        """列出工作流。若 ``agent_path`` 为 None 则扫描所有 Agent。"""
+        workflows: List[Dict] = []
+        if agent_path is not None:
+            base = self._agent_dir(agent_path)
+            search_dirs: List[Path] = [base] if base.is_dir() else []
+        else:
+            if not self._workflows_base.is_dir():
+                return workflows
+            search_dirs = [
+                p for p in self._workflows_base.iterdir() if p.is_dir()
+            ]
+
+        for agent_dir in search_dirs:
+            for fp in sorted(agent_dir.glob("wf_*.json")):
+                wf = self._read_json(fp)
+                if wf:
+                    workflows.append(wf)
+        return workflows
+
+    def get_workflow(
+        self, agent_path: str, workflow_id: str
+    ) -> Optional[Dict]:
+        """获取单个工作流。"""
+        path = self._workflow_file(agent_path, workflow_id)
+        return self._read_json(path)
+
+    def create_workflow(self, agent_path: str, data: Dict) -> Dict:
+        """创建新工作流，自动生成 ID。"""
+        _safe_path_segment(agent_path, "agent_path")
+
+        now = timestamp()
+        wf_id = f"wf_{int(time.time())}_{generate_id()[:6]}"
+
+        # 构建工作流对象
+        workflow: Dict[str, Any] = {
+            "id": wf_id,
+            "name": data.get("name", "未命名工作流"),
+            "description": data.get("description", ""),
+            "agent_path": agent_path,
+            "enabled": data.get("enabled", True),
+            "schedule": data.get("schedule", ""),
+            "steps": data.get("steps", []),
+            "variables": data.get("variables", {}),
+            "created_at": now,
+            "updated_at": now,
+            "last_run": None,
+            "last_status": None,
+            "run_count": 0,
+        }
+
+        path = self._workflow_file(agent_path, wf_id)
+        with self._lock:
+            self._write_json(path, workflow)
+
+        logger.info(
+            "创建工作流 [%s] %s (agent=%s)", wf_id, workflow["name"], agent_path
+        )
+        return workflow
+
+    def update_workflow(
+        self, agent_path: str, workflow_id: str, data: Dict
+    ) -> Dict:
+        """更新工作流字段和步骤。"""
+        path = self._workflow_file(agent_path, workflow_id)
+        with self._lock:
+            workflow = self._read_json(path)
+            if workflow is None:
+                raise FileNotFoundError(
+                    f"工作流不存在: {agent_path}/{workflow_id}"
+                )
+
+            # 可更新的字段
+            updatable_fields = (
+                "name", "description", "enabled", "schedule",
+                "steps", "variables",
+            )
+            for field in updatable_fields:
+                if field in data:
+                    workflow[field] = data[field]
+
+            workflow["updated_at"] = timestamp()
+            self._write_json(path, workflow)
+
+        logger.info(
+            "更新工作流 [%s] %s", workflow_id, workflow.get("name")
+        )
+        return workflow
+
+    def delete_workflow(self, agent_path: str, workflow_id: str) -> bool:
+        """删除工作流及其运行记录。"""
+        path = self._workflow_file(agent_path, workflow_id)
+        runs_dir = self._runs_dir(agent_path)
+
+        with self._lock:
+            if not path.exists():
+                return False
+            path.unlink()
+            logger.info("删除工作流 [%s]", workflow_id)
+
+            # 清理关联的运行记录
+            if runs_dir.is_dir():
+                prefix = f"{workflow_id}_"
+                removed = 0
+                for fp in runs_dir.glob(f"{prefix}*.json"):
+                    fp.unlink()
+                    removed += 1
+                if removed:
+                    logger.info(
+                        "清理工作流 [%s] 的 %d 条运行记录", workflow_id, removed
+                    )
+
+        return True
+
+    def duplicate_workflow(
+        self,
+        agent_path: str,
+        workflow_id: str,
+        new_name: str | None = None,
+    ) -> Dict:
+        """复制工作流，生成新的 ID。"""
+        src = self.get_workflow(agent_path, workflow_id)
+        if src is None:
+            raise FileNotFoundError(
+                f"工作流不存在: {agent_path}/{workflow_id}"
+            )
+
+        copy_data = {
+            "name": new_name or f"{src['name']} (副本)",
+            "description": src.get("description", ""),
+            "enabled": False,  # 副本默认禁用，防止误触
+            "schedule": src.get("schedule", ""),
+            "steps": src.get("steps", []),
+            "variables": dict(src.get("variables", {})),
+        }
+        return self.create_workflow(agent_path, copy_data)
+
+    # ------------------------------------------------------------------
+    # 模板渲染
+    # ------------------------------------------------------------------
+
+    def _render_template(self, template: str, context: Dict) -> str:
+        """替换模板变量::
+
+            {{steps.N.result}}   → 步骤 N 的执行结果
+            {{steps.N.error}}    → 步骤 N 的错误信息
+            {{variables.xxx}}    → 工作流变量
+            {{agent_path}}       → 当前 Agent 路径
+            {{now}}              → 当前时间 ISO 格式
+        """
+        if not template or "{{" not in template:
+            return template
+
+        def _replacer(match: re.Match) -> str:
+            expr = match.group(1).strip()
+            try:
+                # steps.N.result / steps.N.error
+                if expr.startswith("steps."):
+                    parts = expr.split(".", 2)
+                    if len(parts) >= 3:
+                        step_idx = int(parts[1])
+                        field = parts[2]
+                        step_result = context.get("steps_results", {}).get(
+                            step_idx, {}
+                        )
+                        val = step_result.get(field, "")
+                        return str(val) if val is not None else ""
+                    return ""
+
+                # variables.xxx
+                if expr.startswith("variables."):
+                    var_name = expr[len("variables."):]
+                    val = context.get("variables", {}).get(var_name, "")
+                    return str(val) if val is not None else ""
+
+                # 内置变量
+                if expr == "agent_path":
+                    return str(context.get("agent_path", ""))
+                if expr == "now":
+                    return timestamp()
+
+                # 尝试从 context 顶层取值
+                if expr in context:
+                    return str(context[expr])
+
+                return ""
+            except (KeyError, ValueError, IndexError, TypeError) as exc:
+                logger.debug("模板渲染失败 '%s': %s", expr, exc)
+                return ""
+
+        return re.sub(r"\{\{(.*?)\}\}", _replacer, template)
+
+    def _render_params(
+        self, params: Dict[str, Any], context: Dict
+    ) -> Dict[str, Any]:
+        """递归渲染参数字典中所有字符串值。"""
+        rendered: Dict[str, Any] = {}
+        for key, value in params.items():
+            if isinstance(value, str):
+                rendered[key] = self._render_template(value, context)
+            elif isinstance(value, dict):
+                rendered[key] = self._render_params(value, context)
+            elif isinstance(value, list):
+                rendered[key] = [
+                    self._render_template(v, context)
+                    if isinstance(v, str)
+                    else v
+                    for v in value
+                ]
+            else:
+                rendered[key] = value
+        return rendered
+
+    # ------------------------------------------------------------------
+    # 步骤执行
+    # ------------------------------------------------------------------
+
+    def _execute_step(self, step: Dict, context: Dict) -> Dict:
+        """执行单个步骤。
+
+        Args:
+            step: 步骤定义 ``{"id": N, "type": "...", "params": {...}}``
+            context: 执行上下文，包含 ``steps_results``, ``variables``,
+                     ``agent_path``, ``browser_page`` 等
+
+        Returns:
+            ``{"status": "success"|"failed"|"skipped", "result": ..., "error": ...}``
+        """
+        step_type = step.get("type", "")
+        params = self._render_params(step.get("params", {}) or {}, context)
+
+        try:
+            handler = {
+                "browser_open": self._step_browser_open,
+                "delay": self._step_delay,
+                "shell": self._step_shell,
+                "browser_extract": self._step_browser_extract,
+                "browser_screenshot": self._step_browser_screenshot,
+                "send_email": self._step_send_email,
+                "api_call": self._step_api_call,
+                "condition": self._step_condition,
+            }.get(step_type)
+
+            if handler is None:
+                return {
+                    "status": "failed",
+                    "result": None,
+                    "error": f"未知步骤类型: {step_type}",
+                }
+
+            result = handler(params, context)
+            return {"status": "success", "result": result, "error": None}
+
+        except Exception as exc:
+            logger.error(
+                "步骤 #%d [%s] 执行失败: %s",
+                step.get("id", "?"),
+                step_type,
+                exc,
+            )
+            return {
+                "status": "failed",
+                "result": None,
+                "error": truncate_str(str(exc), 2000),
+            }
+
+    # --- 步骤实现 ---
+
+    def _step_browser_open(self, params: Dict, context: Dict) -> str:
+        """browser_open: 使用 stealth 浏览器打开 URL。"""
+        url = params.get("url", "")
+        profile = params.get("profile", "")
+
+        try:
+            from aiskills.browser_stealth import open_stealth_browser
+
+            page = open_stealth_browser(url=url, profile=profile or None)
+            if page:
+                context["browser_page"] = page
+            return f"浏览器已打开: {url}"
+        except ImportError:
+            logger.warning("aiskills.browser_stealth 不可用，模拟打开")
+            return f"[模拟] 浏览器已打开: {url}"
+        except Exception as exc:
+            raise RuntimeError(f"浏览器启动失败: {exc}") from exc
+
+    def _step_delay(self, params: Dict, context: Dict) -> str:
+        """delay: 等待指定秒数。"""
+        seconds = float(params.get("seconds", 1))
+        seconds = max(0.1, min(seconds, 300))  # 限制 0.1 ~ 300 秒
+        time.sleep(seconds)
+        return f"等待 {seconds} 秒完成"
+
+    def _step_shell(self, params: Dict, context: Dict) -> str:
+        """shell: 执行 Shell 命令。"""
+        command = params.get("command", "")
+        if not command:
+            raise ValueError("Shell 命令不能为空")
+
+        timeout = int(params.get("timeout", 120))
+        timeout = max(1, min(timeout, 600))  # 限制 1 ~ 600 秒
+
+        logger.info("执行 Shell 命令: %s", command)
+        proc = subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            encoding="utf-8",
+            errors="replace",
+        )
+
+        output_parts = []
+        if proc.stdout:
+            output_parts.append(proc.stdout.strip())
+        if proc.stderr:
+            output_parts.append(f"[stderr] {proc.stderr.strip()}")
+        if proc.returncode != 0:
+            output_parts.append(f"[exit code: {proc.returncode}]")
+
+        result = "\n".join(output_parts) if output_parts else "(无输出)"
+        if proc.returncode != 0:
+            raise RuntimeError(f"命令执行失败 (exit {proc.returncode}): {result}")
+        return result
+
+    def _step_browser_extract(self, params: Dict, context: Dict) -> str:
+        """browser_extract: 从浏览器页面提取内容。"""
+        selector = params.get("selector", "")
+        attribute = params.get("attribute", "text")
+
+        page = context.get("browser_page")
+        if page is None:
+            raise RuntimeError(
+                "浏览器页面未打开，请先执行 browser_open 步骤"
+            )
+
+        try:
+            from DrissionPage import ChromiumPage
+
+            if not isinstance(page, ChromiumPage):
+                raise RuntimeError("当前浏览器对象类型不支持提取操作")
+
+            elements = page.eles(selector)
+            if not elements:
+                return "(未找到匹配元素)"
+
+            results = []
+            for el in elements:
+                if attribute == "text":
+                    results.append(el.text)
+                else:
+                    val = el.attr(attribute)
+                    if val:
+                        results.append(str(val))
+
+            extracted = "\n".join(results)
+            logger.info(
+                "提取到 %d 条元素: %s", len(results), truncate_str(extracted, 200)
+            )
+            return truncate_str(extracted, 50000)
+
+        except ImportError:
+            raise RuntimeError("DrissionPage 未安装，无法执行提取操作")
+        except Exception as exc:
+            raise RuntimeError(f"页面提取失败: {exc}") from exc
+
+    def _step_browser_screenshot(self, params: Dict, context: Dict) -> str:
+        """browser_screenshot: 截取浏览器页面截图。"""
+        save_path = params.get("save_path", "")
+        if not save_path:
+            raise ValueError("save_path 不能为空")
+
+        page = context.get("browser_page")
+        if page is None:
+            raise RuntimeError(
+                "浏览器页面未打开，请先执行 browser_open 步骤"
+            )
+
+        try:
+            # 确保父目录存在
+            Path(save_path).parent.mkdir(parents=True, exist_ok=True)
+            page.get_screenshot(path=save_path, full_page=True)
+            return f"截图已保存: {save_path}"
+        except Exception as exc:
+            raise RuntimeError(f"截图失败: {exc}") from exc
+
+    def _step_send_email(self, params: Dict, context: Dict) -> str:
+        """send_email: 发送邮件（当前为占位实现，记录日志并返回）。"""
+        to = params.get("to", "")
+        subject = params.get("subject", "")
+        body = params.get("body", "")
+
+        if not to:
+            raise ValueError("收件人 (to) 不能为空")
+
+        # 占位实现：记录日志，后续接入真实 SMTP / API
+        logger.info(
+            "发送邮件 → %s | 主题: %s | 正文: %s",
+            to,
+            subject,
+            truncate_str(body, 200),
+        )
+        return f"邮件已发送至 {to}，主题: {subject}"
+
+    def _step_api_call(self, params: Dict, context: Dict) -> str:
+        """api_call: 调用 HTTP API。"""
+        url = params.get("url", "")
+        method = (params.get("method") or "GET").upper()
+        headers_raw = params.get("headers", "{}")
+        body = params.get("body", "")
+
+        if not url:
+            raise ValueError("API URL 不能为空")
+
+        # 解析 headers
+        try:
+            headers = (
+                json.loads(headers_raw)
+                if isinstance(headers_raw, str)
+                else headers_raw
+            )
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Headers JSON 解析失败: {exc}") from exc
+
+        try:
+            import requests  # type: ignore
+        except ImportError:
+            raise RuntimeError("requests 库未安装，无法执行 API 调用")
+
+        logger.info("API 调用 %s %s", method, url)
+        try:
+            resp = requests.request(
+                method=method,
+                url=url,
+                headers=headers,
+                data=body if body else None,
+                timeout=60,
+            )
+            result = f"HTTP {resp.status_code}\n{resp.text}"
+            resp.raise_for_status()
+            return truncate_str(result, 50000)
+        except requests.exceptions.HTTPError as exc:
+            return truncate_str(f"HTTP 错误: {exc}\n{resp.text}", 50000)
+        except requests.exceptions.RequestException as exc:
+            raise RuntimeError(f"API 调用失败: {exc}") from exc
+
+    def _step_condition(self, params: Dict, context: Dict) -> str:
+        """condition: 评估条件表达式，决定继续或停止。
+
+        返回特殊标记 ``__CONTINUE__`` 或 ``__STOP__`` 由上层解析。
+        """
+        expression = params.get("expression", "")
+        on_true = params.get("on_true", "next")
+        on_false = params.get("on_false", "stop")
+
+        if not expression:
+            raise ValueError("条件表达式不能为空")
+
+        # 构建求值上下文
+        eval_context: Dict[str, Any] = {
+            "steps": context.get("steps_results", {}),
+            "variables": context.get("variables", {}),
+        }
+
+        try:
+            result = _safe_eval(expression, eval_context)
+        except (ValueError, TypeError, SyntaxError) as exc:
+            raise ValueError(f"条件求值失败: {exc}") from exc
+
+        if result:
+            action = on_true
+            logger.info("条件 [%s] = True → %s", expression, action)
+        else:
+            action = on_false
+            logger.info("条件 [%s] = False → %s", expression, action)
+
+        # 返回动作标记
+        if action == "stop":
+            return "__STOP__"
+        return f"条件满足 (={result})，继续执行"
+
+    # ------------------------------------------------------------------
+    # 工作流执行
+    # ------------------------------------------------------------------
+
+    async def run_workflow(
+        self,
+        agent_path: str,
+        workflow_id: str,
+        variables: Dict | None = None,
+    ) -> Dict:
+        """按顺序执行工作流中的所有步骤，记录结果。
+
+        Args:
+            agent_path: Agent 路径
+            workflow_id: 工作流 ID
+            variables: 运行时覆盖变量（合并到工作流变量中）
+
+        Returns:
+            执行记录 dict
+        """
+        workflow = self.get_workflow(agent_path, workflow_id)
+        if workflow is None:
+            raise FileNotFoundError(
+                f"工作流不存在: {agent_path}/{workflow_id}"
+            )
+
+        steps = workflow.get("steps", [])
+        if not steps:
+            logger.warning("工作流 [%s] 没有步骤", workflow_id)
+
+        # 合并变量：运行时变量覆盖工作流变量
+        merged_vars = dict(workflow.get("variables", {}))
+        if variables:
+            merged_vars.update(variables)
+
+        run_id = f"run_{int(time.time())}_{generate_id()[:6]}"
+        now = timestamp()
+
+        run_record: Dict[str, Any] = {
+            "run_id": run_id,
+            "workflow_id": workflow_id,
+            "agent_path": agent_path,
+            "status": "running",
+            "started_at": now,
+            "finished_at": None,
+            "steps_log": [],
+        }
+
+        # 构建执行上下文
+        exec_context: Dict[str, Any] = {
+            "agent_path": agent_path,
+            "variables": merged_vars,
+            "steps_results": {},
+            "browser_page": None,
+        }
+
+        logger.info(
+            "========== 工作流开始 [%s] %s (%d 步) ==========",
+            run_id,
+            workflow.get("name", ""),
+            len(steps),
+        )
+
+        should_stop = False
+        overall_status = "completed"
+
+        for step in steps:
+            step_id = step.get("id", 0)
+            step_name = step.get("name", "")
+            step_type = step.get("type", "")
+            step_started = timestamp()
+
+            if should_stop:
+                step_log = {
+                    "step_id": step_id,
+                    "name": step_name,
+                    "type": step_type,
+                    "status": "skipped",
+                    "started_at": step_started,
+                    "finished_at": timestamp(),
+                    "result": None,
+                    "error": "前置条件不满足，跳过",
+                }
+                run_record["steps_log"].append(step_log)
+                continue
+
+            logger.info(
+                "  → 步骤 #%d [%s] %s ...", step_id, step_type, step_name
+            )
+
+            # 执行步骤
+            result = self._execute_step(step, exec_context)
+            step_finished = timestamp()
+
+            step_status = result["status"]
+            step_result = result.get("result")
+            step_error = result.get("error")
+
+            step_log = {
+                "step_id": step_id,
+                "name": step_name,
+                "type": step_type,
+                "status": step_status,
+                "started_at": step_started,
+                "finished_at": step_finished,
+                "result": truncate_str(str(step_result), 50000)
+                if step_result is not None
+                else None,
+                "error": step_error,
+            }
+            run_record["steps_log"].append(step_log)
+
+            # 存储结果供后续步骤引用
+            exec_context["steps_results"][step_id] = {
+                "result": step_result,
+                "error": step_error,
+                "status": step_status,
+            }
+
+            # 检查是否需要停止
+            if step_status == "failed":
+                logger.error(
+                    "  ✗ 步骤 #%d 失败: %s", step_id, step_error
+                )
+                overall_status = "failed"
+                should_stop = True
+            elif (
+                step_status == "success"
+                and isinstance(step_result, str)
+                and step_result == "__STOP__"
+            ):
+                logger.info("  ■ 步骤 #%d 触发停止", step_id)
+                overall_status = "stopped"
+                should_stop = True
+            else:
+                logger.info(
+                    "  ✓ 步骤 #%d 完成", step_id
+                )
+
+        # 清理浏览器
+        if exec_context.get("browser_page"):
+            try:
+                exec_context["browser_page"].quit()
+            except Exception:
+                pass
+
+        # 写入运行记录
+        run_record["finished_at"] = timestamp()
+        run_record["status"] = overall_status
+        run_file = self._run_file(agent_path, run_id)
+
+        with self._lock:
+            self._write_json(run_file, run_record)
+
+        # 更新工作流统计
+        with self._lock:
+            wf_path = self._workflow_file(agent_path, workflow_id)
+            wf = self._read_json(wf_path)
+            if wf:
+                wf["last_run"] = run_record["started_at"]
+                wf["last_status"] = overall_status
+                wf["run_count"] = wf.get("run_count", 0) + 1
+                wf["updated_at"] = timestamp()
+                self._write_json(wf_path, wf)
+
+        logger.info(
+            "========== 工作流结束 [%s] 状态: %s ==========",
+            run_id,
+            overall_status,
+        )
+        return run_record
+
+    # ------------------------------------------------------------------
+    # 运行记录查询
+    # ------------------------------------------------------------------
+
+    def list_runs(
+        self,
+        agent_path: str,
+        workflow_id: str | None = None,
+        limit: int = 20,
+    ) -> List[Dict]:
+        """列出执行运行记录，按时间倒序。"""
+        runs_dir = self._runs_dir(agent_path)
+        if not runs_dir.is_dir():
+            return []
+
+        records: List[Dict] = []
+        pattern = (
+            f"{workflow_id}_*.json" if workflow_id else "run_*.json"
+        )
+
+        for fp in sorted(runs_dir.glob(pattern), reverse=True):
+            rec = self._read_json(fp)
+            if rec:
+                records.append(rec)
+                if len(records) >= limit:
+                    break
+
+        return records
+
+    def get_run(
+        self, agent_path: str, run_id: str
+    ) -> Optional[Dict]:
+        """获取单条运行记录。"""
+        path = self._run_file(agent_path, run_id)
+        return self._read_json(path)
+
+    def delete_run(self, agent_path: str, run_id: str) -> bool:
+        """删除单条运行记录。"""
+        path = self._run_file(agent_path, run_id)
+        with self._lock:
+            if not path.exists():
+                return False
+            path.unlink()
+        return True
+
+    def cleanup_old_runs(
+        self,
+        agent_path: str,
+        workflow_id: str | None = None,
+        keep_count: int = 50,
+    ) -> int:
+        """清理旧运行记录，仅保留最近 N 条。"""
+        runs = self.list_runs(
+            agent_path, workflow_id, limit=99999
+        )
+        if len(runs) <= keep_count:
+            return 0
+
+        removed = 0
+        for rec in runs[keep_count:]:
+            if self.delete_run(agent_path, rec["run_id"]):
+                removed += 1
+
+        if removed:
+            logger.info(
+                "清理了 %d 条旧运行记录 (agent=%s, keep=%d)",
+                removed,
+                agent_path,
+                keep_count,
+            )
+        return removed
+
+    # ------------------------------------------------------------------
+    # 工作流启用/禁用
+    # ------------------------------------------------------------------
+
+    def toggle_workflow(
+        self, agent_path: str, workflow_id: str, enabled: bool | None = None
+    ) -> Dict:
+        """切换工作流启用/禁用状态。若 enabled 为 None 则自动取反。"""
+        workflow = self.get_workflow(agent_path, workflow_id)
+        if workflow is None:
+            raise FileNotFoundError(
+                f"工作流不存在: {agent_path}/{workflow_id}"
+            )
+        if enabled is None:
+            enabled = not workflow.get("enabled", True)
+        return self.update_workflow(
+            agent_path, workflow_id, {"enabled": enabled}
+        )
+
+    # ------------------------------------------------------------------
+    # 工作流排序
+    # ------------------------------------------------------------------
+
+    def reorder_steps(
+        self,
+        agent_path: str,
+        workflow_id: str,
+        step_ids: List[int],
+    ) -> Dict:
+        """重新排列工作流步骤顺序。"""
+        workflow = self.get_workflow(agent_path, workflow_id)
+        if workflow is None:
+            raise FileNotFoundError(
+                f"工作流不存在: {agent_path}/{workflow_id}"
+            )
+
+        existing_steps = {s["id"]: s for s in workflow.get("steps", [])}
+        reordered = []
+        for sid in step_ids:
+            if sid in existing_steps:
+                reordered.append(existing_steps[sid])
+
+        # 附加不在新顺序中的步骤（安全兜底）
+        existing_ids = set(reordered)
+        for s in workflow.get("steps", []):
+            if s["id"] not in existing_ids:
+                reordered.append(s)
+
+        return self.update_workflow(
+            agent_path, workflow_id, {"steps": reordered}
+        )
+
+    # ------------------------------------------------------------------
+    # 统计信息
+    # ------------------------------------------------------------------
+
+    def get_stats(self, agent_path: str) -> Dict[str, Any]:
+        """获取 Agent 的工作流统计信息。"""
+        workflows = self.list_workflows(agent_path)
+        total_runs = 0
+        success_runs = 0
+        failed_runs = 0
+
+        for wf in workflows:
+            rc = wf.get("run_count", 0)
+            total_runs += rc
+            if wf.get("last_status") == "completed":
+                success_runs += 1
+            elif wf.get("last_status") == "failed":
+                failed_runs += 1
+
+        return {
+            "agent_path": agent_path,
+            "total_workflows": len(workflows),
+            "enabled_workflows": sum(
+                1 for wf in workflows if wf.get("enabled", True)
+            ),
+            "total_runs": total_runs,
+            "success_runs": success_runs,
+            "failed_runs": failed_runs,
+        }