agstack 1.14.0__tar.gz → 1.16.0__tar.gz

{agstack-1.14.0 → agstack-1.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.14.0
+Version: 1.16.0
 Summary: Production-ready toolkit for building FastAPI and LLM applications
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{agstack-1.14.0 → agstack-1.16.0}/agstack/llm/flow/flow.py

@@ -16,6 +16,28 @@ if TYPE_CHECKING:
     from .nodes.base import NodeHandler
 
 
+_OPERATORS = (">=", "<=", "!=", "==", ">", "<")
+
+
+def _parse_literal(s: str) -> Any:
+    """解析字面量值"""
+    if s in ("true", "True"):
+        return True
+    if s in ("false", "False"):
+        return False
+    if s in ("none", "None", "null"):
+        return None
+    try:
+        return int(s)
+    except ValueError:
+        pass
+    try:
+        return float(s)
+    except ValueError:
+        pass
+    return s
+
+
 @dataclass
 class RetryPolicy:
     """节点重试策略"""
@@ -42,6 +64,7 @@ class Flow:
     nodes: list[dict[str, Any]] = field(default_factory=list)
     edges: list[dict[str, Any]] = field(default_factory=list)
     variables: dict[str, Any] = field(default_factory=dict)
+    cycle_limits: dict[str, int] = field(default_factory=dict)
 
     _node_handlers: dict[str, "NodeHandler"] = field(default_factory=dict, init=False, repr=False)
 
@@ -67,25 +90,46 @@ class Flow:
 
     # ── 边驱动路由 ──
 
-    def _resolve_next_node(self, current_id: str, result: str | None = None) -> str | None:
-        """根据当前节点和执行结果，通过 edges 查找下一节点"""
-        for edge in self.edges:
-            if edge.get("source") == current_id:
-                cond = edge.get("condition")
-                if cond is None or cond == result:
-                    return edge.get("target")
-        return None
-
-    @staticmethod
-    def _extract_route_key(result: Any) -> str:
-        """从节点输出 dict 中提取路由键。
-
-        节点输出 dict 中若包含 ``choice`` 字段，即为路由键。
-        没有 ``choice`` 则默认 ``"done"``。
+    def _eval_condition(self, condition: str, context: "FlowContext") -> bool:
+        """对边条件表达式求值"""
+        for op in _OPERATORS:
+            if op in condition:
+                left, right = condition.split(op, 1)
+                left_val = context.resolve_reference(left.strip())
+                right_val = _parse_literal(right.strip())
+                if op == "==":
+                    return left_val == right_val
+                if op == "!=":
+                    return left_val != right_val
+                try:
+                    if op == ">":
+                        return left_val > right_val
+                    if op == "<":
+                        return left_val < right_val
+                    if op == ">=":
+                        return left_val >= right_val
+                    if op == "<=":
+                        return left_val <= right_val
+                except TypeError:
+                    return False
+                break
+        return bool(context.resolve_reference(condition.strip()))
+
+    def _resolve_next_node(self, current_id: str, context: "FlowContext", force_fallback: bool = False) -> str | None:
+        """根据当前节点，通过 edges 表达式求值查找下一节点。
+
+        force_fallback=True 时跳过条件边，只走无条件边（用于循环超限逃逸）。
         """
-        if isinstance(result, dict):
-            return str(result.get("choice", "done"))
-        return "done"
+        fallback_target: str | None = None
+        for edge in self.edges:
+            if edge.get("source") != current_id:
+                continue
+            cond = edge.get("condition")
+            if cond is None:
+                fallback_target = edge.get("target")
+            elif not force_fallback and self._eval_condition(cond, context):
+                return edge.get("target")
+        return fallback_target
 
     # ── message 节点 ──
 
@@ -102,6 +146,34 @@ class Flow:
 
     # ── 带重试的节点执行（统一走 NodeHandler） ──
 
+    def _resolve_visibility(self, node_type: str, config: dict) -> tuple[str | None, bool]:
+        """从 node config 和 registry 解析可见性（label, echo）
+
+        优先级：flow node config > registry 注册属性
+        """
+        from .registry import registry
+
+        label = config.get("label")
+        explicit_echo = "echo" in config
+        echo = config.get("echo", False)
+
+        if not explicit_echo and label is None:
+            if node_type == "agent":
+                agent_name = config.get("agent_name", "")
+                label = registry.get_agent_label(agent_name)
+                if not label:
+                    echo = registry.get_agent_echo(agent_name)
+            elif node_type == "tool":
+                tool_name = config.get("tool_name", "")
+                label = registry.get_tool_label(tool_name)
+                if not label:
+                    echo = registry.get_tool_echo(tool_name)
+
+        if label and not explicit_echo:
+            echo = True
+
+        return label, echo
+
     async def _execute_node_with_retry(
         self,
         node: dict,
@@ -120,6 +192,7 @@ class Flow:
 
         policy = self._get_retry_policy(node)
         label = handler.get_step_name(node, node_id)
+        vis_label, vis_echo = self._resolve_visibility(node_type, node.get("config", {}))
         last_error: Exception | None = None
 
         for attempt in range(policy.max_retries + 1):
@@ -140,6 +213,9 @@ class Flow:
                     )
 
                 async for evt in handler.stream(node, context, node_id):
+                    evt["_node_id"] = node_id
+                    evt["_label"] = vis_label
+                    evt["_echo"] = vis_echo
                     yield evt
                 return
 
@@ -158,10 +234,16 @@ class Flow:
 
     # ── 执行入口 ──
 
+    def _check_cycle_limit(self, node_id: str, visit_count: dict[str, int]) -> bool:
+        """检查节点是否超出循环次数限制。返回 True 表示超限。"""
+        limit = self.cycle_limits.get(node_id)
+        if limit is not None and visit_count.get(node_id, 0) > limit:
+            return True
+        return False
+
     async def run(self, context: "FlowContext") -> dict[str, Any]:
         """执行 Flow"""
         if not self.edges:
-            # 向后兼容：无 edges 时按 nodes 列表顺序执行
             for node in self.nodes:
                 node_id = node.get("id")
                 if not node_id:
@@ -175,12 +257,21 @@ class Flow:
                 else:
                     raise NodeExecutionError("UNKNOWN_NODE_TYPE", args={"node_type": node_type})
         else:
-            # edge 驱动执行
             current_node_id: str | None = self.nodes[0]["id"] if self.nodes else None
+            visit_count: dict[str, int] = {}
+
             while current_node_id:
                 node = self.get_node_config(current_node_id)
                 if not node:
                     break
+
+                # 循环计数与超限检测
+                visit_count[current_node_id] = visit_count.get(current_node_id, 0) + 1
+                force_fallback = self._check_cycle_limit(current_node_id, visit_count)
+                if force_fallback:
+                    current_node_id = self._resolve_next_node(current_node_id, context, force_fallback=True)
+                    continue
+
                 context.current_node = current_node_id
                 node_type: str = node.get("type", "")
 
@@ -189,7 +280,7 @@ class Flow:
                     template = config.get("content", "")
                     text = template.format_map(_SafeFormatDict(context.variables))
                     context.set_output(current_node_id, {"result": text})
-                    current_node_id = self._resolve_next_node(current_node_id, "done")
+                    current_node_id = self._resolve_next_node(current_node_id, context)
 
                 elif node_type == "parallel":
                     config = node.get("config", {})
@@ -207,8 +298,13 @@ class Flow:
                             context.set_output(branch_id, result)
 
                     await asyncio.gather(*[_run_branch(bid) for bid in branches])
-                    context.set_output(current_node_id, {"choice": "done"})
-                    current_node_id = self._resolve_next_node(current_node_id, "done")
+                    merged: dict[str, Any] = {}
+                    for bid in branches:
+                        branch_result = context.outputs.get(bid, {})
+                        if isinstance(branch_result, dict):
+                            merged.update(branch_result)
+                    context.set_output(current_node_id, merged)
+                    current_node_id = self._resolve_next_node(current_node_id, context)
 
                 elif node_type == "iteration":
                     config = node.get("config", {})
@@ -238,44 +334,13 @@ class Flow:
                             results.append(context.outputs.get(body_nodes[-1]))
 
                     context.set_output(current_node_id, {"results": results})
-                    current_node_id = self._resolve_next_node(current_node_id, "done")
-
-                elif node_type == "loop":
-                    config = node.get("config", {})
-                    body_nodes_l: list[str] = config.get("body", [])
-                    condition_node_id = config.get("condition_node")
-                    break_cond = config.get("break_condition", "done")
-                    max_iter = config.get("max_iterations", 10)
-                    loop_var = config.get("loop_variable", "loop_count")
-
-                    for iteration in range(max_iter):
-                        context.set_variable(loop_var, iteration)
-                        for body_node_id in body_nodes_l:
-                            body_node = self.get_node_config(body_node_id)
-                            if not body_node:
-                                continue
-                            body_type: str = body_node.get("type", "")
-                            body_handler = self._node_handlers.get(body_type)
-                            if body_handler:
-                                body_result = await body_handler.execute(body_node, context)
-                                context.set_output(body_node_id, body_result)
-                        if condition_node_id:
-                            cond_result = context.outputs.get(condition_node_id, {})
-                            if isinstance(cond_result, dict) and cond_result.get("choice") == break_cond:
-                                break
-
-                    context.set_output(current_node_id, {"choice": "done"})
-                    current_node_id = self._resolve_next_node(current_node_id, "done")
+                    current_node_id = self._resolve_next_node(current_node_id, context)
 
                 elif node_type in self._node_handlers:
-                    # 所有执行类节点统一分发
                     handler = self._node_handlers[node_type]
                     result = await handler.execute(node, context)
                     context.set_output(current_node_id, result)
-                    route_key = self._extract_route_key(result)
-                    current_node_id = self._resolve_next_node(current_node_id, route_key) or self._resolve_next_node(
-                        current_node_id, "done"
-                    )
+                    current_node_id = self._resolve_next_node(current_node_id, context)
 
                 else:
                     raise NodeExecutionError("UNKNOWN_NODE_TYPE", args={"node_type": node_type})
@@ -298,7 +363,7 @@ class Flow:
         yield event.step_finished(step_name=f"flow:{self.name}")
 
     async def _stream_sequential(self, context: "FlowContext") -> AsyncIterator[dict[str, Any]]:
-        """顺序流式执行（原有逻辑）"""
+        """顺序流式执行"""
         for node in self.nodes:
             node_id = node.get("id")
             if not node_id:
@@ -320,6 +385,7 @@ class Flow:
     async def _stream_edge_driven(self, context: "FlowContext") -> AsyncIterator[dict[str, Any]]:
         """边驱动流式执行"""
         current_node_id: str | None = self.nodes[0]["id"] if self.nodes else None
+        visit_count: dict[str, int] = {}
 
         while current_node_id:
             node = self.get_node_config(current_node_id)
@@ -330,18 +396,32 @@ class Flow:
                 )
                 raise NodeExecutionError("NODE_NOT_FOUND", args={"node_id": current_node_id})
 
+            # 循环计数与超限检测
+            visit_count[current_node_id] = visit_count.get(current_node_id, 0) + 1
+            force_fallback = self._check_cycle_limit(current_node_id, visit_count)
+            if force_fallback:
+                current_node_id = self._resolve_next_node(current_node_id, context, force_fallback=True)
+                continue
+
             context.current_node = current_node_id
             node_type: str = node.get("type", "")
 
             if node_type == "message":
                 async for evt in self._emit_message(node, context):
+                    evt["_node_id"] = current_node_id
+                    evt["_label"] = None
+                    evt["_echo"] = False
                     yield evt
-                current_node_id = self._resolve_next_node(current_node_id, "done")
+                current_node_id = self._resolve_next_node(current_node_id, context)
 
             elif node_type == "parallel":
                 config = node.get("config", {})
                 branches = config.get("branches", [])
-                yield event.step_started(step_name=f"parallel:{current_node_id}")
+                step_evt = event.step_started(step_name=f"parallel:{current_node_id}")
+                step_evt["_node_id"] = current_node_id
+                step_evt["_label"] = None
+                step_evt["_echo"] = False
+                yield step_evt
 
                 async def _exec_branch(branch_id: str) -> None:
                     branch_node = self.get_node_config(branch_id)
@@ -355,9 +435,18 @@ class Flow:
                         context.set_output(branch_id, result)
 
                 await asyncio.gather(*[_exec_branch(bid) for bid in branches])
-                context.set_output(current_node_id, {"choice": "done"})
-                yield event.step_finished(step_name=f"parallel:{current_node_id}")
-                current_node_id = self._resolve_next_node(current_node_id, "done")
+                merged: dict[str, Any] = {}
+                for bid in branches:
+                    branch_result = context.outputs.get(bid, {})
+                    if isinstance(branch_result, dict):
+                        merged.update(branch_result)
+                context.set_output(current_node_id, merged)
+                fin_evt = event.step_finished(step_name=f"parallel:{current_node_id}")
+                fin_evt["_node_id"] = current_node_id
+                fin_evt["_label"] = None
+                fin_evt["_echo"] = False
+                yield fin_evt
+                current_node_id = self._resolve_next_node(current_node_id, context)
 
             elif node_type == "iteration":
                 config = node.get("config", {})
@@ -371,7 +460,11 @@ class Flow:
                 body_nodes: list[str] = config.get("body", [])
                 results: list[Any] = []
 
-                yield event.step_started(step_name=f"iteration:{current_node_id}")
+                step_evt = event.step_started(step_name=f"iteration:{current_node_id}")
+                step_evt["_node_id"] = current_node_id
+                step_evt["_label"] = None
+                step_evt["_echo"] = False
+                yield step_evt
                 for idx, item in enumerate(items):
                     context.set_variable(item_var, item)
                     context.set_variable(index_var, idx)
@@ -388,48 +481,17 @@ class Flow:
                         results.append(context.outputs.get(body_nodes[-1]))
 
                 context.set_output(current_node_id, {"results": results})
-                yield event.step_finished(step_name=f"iteration:{current_node_id}")
-                current_node_id = self._resolve_next_node(current_node_id, "done")
-
-            elif node_type == "loop":
-                config = node.get("config", {})
-                body_nodes_l: list[str] = config.get("body", [])
-                condition_node_id = config.get("condition_node")
-                break_cond = config.get("break_condition", "done")
-                max_iter = config.get("max_iterations", 10)
-                loop_var = config.get("loop_variable", "loop_count")
-
-                yield event.step_started(step_name=f"loop:{current_node_id}")
-                for iteration in range(max_iter):
-                    context.set_variable(loop_var, iteration)
-                    for body_node_id in body_nodes_l:
-                        body_node = self.get_node_config(body_node_id)
-                        if not body_node:
-                            continue
-                        body_type = body_node.get("type", "")
-                        body_handler = self._node_handlers.get(body_type)
-                        if body_handler:
-                            body_result = await body_handler.execute(body_node, context)
-                            context.set_output(body_node_id, body_result)
-                    # 检查终止条件
-                    if condition_node_id:
-                        cond_result = context.outputs.get(condition_node_id, {})
-                        if isinstance(cond_result, dict) and cond_result.get("choice") == break_cond:
-                            break
-
-                context.set_output(current_node_id, {"choice": "done"})
-                yield event.step_finished(step_name=f"loop:{current_node_id}")
-                current_node_id = self._resolve_next_node(current_node_id, "done")
+                fin_evt = event.step_finished(step_name=f"iteration:{current_node_id}")
+                fin_evt["_node_id"] = current_node_id
+                fin_evt["_label"] = None
+                fin_evt["_echo"] = False
+                yield fin_evt
+                current_node_id = self._resolve_next_node(current_node_id, context)
 
             elif node_type in self._node_handlers:
-                # 所有执行类节点统一分发
                 async for evt in self._execute_node_with_retry(node, context, current_node_id):
                     yield evt
-                result = context.outputs.get(current_node_id, {})
-                route_key = self._extract_route_key(result)
-                current_node_id = self._resolve_next_node(current_node_id, route_key) or self._resolve_next_node(
-                    current_node_id, "done"
-                )
+                current_node_id = self._resolve_next_node(current_node_id, context)
 
             else:
                 yield event.run_error(

{agstack-1.14.0 → agstack-1.16.0}/agstack/llm/flow/loader.py

@@ -60,4 +60,5 @@ class FlowLoader:
             nodes=nodes,
             edges=config.get("edges", []),
             variables=config.get("variables", {}),
+            cycle_limits=config.get("cycle_limits", {}),
         )

{agstack-1.14.0 → agstack-1.16.0}/agstack/llm/flow/nodes/agent_node.py

@@ -19,13 +19,17 @@ class AgentNodeHandler(NodeHandler):
 
     node_type = "agent"
 
-    _NODE_KEYS = frozenset({"agent_name", "inputs"})
+    _NODE_KEYS = frozenset({"agent_name", "inputs", "label", "echo"})
 
-    def _create_agent(self, config: dict):
+    def _create_agent(self, config: dict, context: "FlowContext"):
         agent_name = config.get("agent_name")
         if not agent_name:
             raise FlowError("MISSING_AGENT_NAME", 400)
-        agent_kwargs = {k: v for k, v in config.items() if k not in self._NODE_KEYS}
+        agent_kwargs = {
+            k: context.resolve_reference(v) if isinstance(v, str) else v
+            for k, v in config.items()
+            if k not in self._NODE_KEYS
+        }
         agent = registry.create_agent(agent_name, **agent_kwargs)
         if not agent:
             raise FlowError("AGENT_NOT_FOUND", 404, {"agent_name": agent_name})
@@ -34,8 +38,10 @@ class AgentNodeHandler(NodeHandler):
     async def execute(self, node: dict, context: "FlowContext") -> Any:
         config = node.get("config", {})
         resolved = self.resolve_inputs(config, context)
-        ag = self._create_agent(config)
-        return await ag.run(context, inputs=resolved)
+        ag = self._create_agent(config, context)
+        result = await ag.run(context, inputs=resolved)
+        structured = context.outputs.pop(ag.name, None)
+        return structured if structured is not None else result
 
     async def stream(self, node: dict, context: "FlowContext", node_id: str) -> AsyncIterator[dict[str, Any]]:
         config = node.get("config", {})
@@ -43,9 +49,13 @@ class AgentNodeHandler(NodeHandler):
 
         yield event.step_started(step_name=step_name)
         resolved = self.resolve_inputs(config, context)
-        ag = self._create_agent(config)
+        ag = self._create_agent(config, context)
         async for evt in ag.stream(context, inputs=resolved):
             yield evt
-        result = context.get_last_output(ag.name) or ""
-        context.set_output(node_id, {"result": result})
+        structured = context.outputs.pop(ag.name, None)
+        if structured is not None:
+            context.set_output(node_id, structured)
+        else:
+            result = context.get_last_output(ag.name) or ""
+            context.set_output(node_id, {"result": result})
         yield event.step_finished(step_name=step_name)

{agstack-1.14.0 → agstack-1.16.0}/agstack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.14.0
+Version: 1.16.0
 Summary: Production-ready toolkit for building FastAPI and LLM applications
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{agstack-1.14.0 → agstack-1.16.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agstack"
-version = "1.14.0"
+version = "1.16.0"
 description = "Production-ready toolkit for building FastAPI and LLM applications"
 readme = "README.md"
 license = "MIT"

{agstack-1.14.0 → agstack-1.16.0}/tests/test_flow_io.py

@@ -130,28 +130,51 @@ class TestTool:
         assert result.error is not None and "boom" in result.error
 
 
-# ── _extract_route_key ──
+# ── _eval_condition ──
 
 
-class TestExtractRouteKey:
-    """路由键提取测试"""
+class TestEvalCondition:
+    """条件表达式求值测试"""
 
-    def test_dict_with_choice(self):
-        assert Flow._extract_route_key({"choice": "qa"}) == "qa"
-
-    def test_dict_without_choice(self):
-        assert Flow._extract_route_key({"result": "hello"}) == "done"
-
-    def test_dict_empty(self):
-        assert Flow._extract_route_key({}) == "done"
-
-    def test_non_dict(self):
-        assert Flow._extract_route_key("some string") == "done"
-        assert Flow._extract_route_key(None) == "done"
-        assert Flow._extract_route_key(42) == "done"
-
-    def test_choice_as_non_string(self):
-        assert Flow._extract_route_key({"choice": 123}) == "123"
+    def test_eq_string(self):
+        flow = Flow(flow_id="t", name="t")
+        ctx = FlowContext()
+        ctx.set_output("detect1", {"choice": "qa"})
+        assert flow._eval_condition("$o.detect1.choice == qa", ctx) is True
+        assert flow._eval_condition("$o.detect1.choice == chitchat", ctx) is False
+
+    def test_eq_bool(self):
+        flow = Flow(flow_id="t", name="t")
+        ctx = FlowContext(variables={"has_context": True})
+        assert flow._eval_condition("$v.has_context == true", ctx) is True
+        assert flow._eval_condition("$v.has_context == false", ctx) is False
+
+    def test_numeric_comparison(self):
+        flow = Flow(flow_id="t", name="t")
+        ctx = FlowContext()
+        ctx.set_output("eval", {"score": 0.9})
+        assert flow._eval_condition("$o.eval.score > 0.8", ctx) is True
+        assert flow._eval_condition("$o.eval.score < 0.8", ctx) is False
+        assert flow._eval_condition("$o.eval.score >= 0.9", ctx) is True
+        assert flow._eval_condition("$o.eval.score <= 0.9", ctx) is True
+
+    def test_neq(self):
+        flow = Flow(flow_id="t", name="t")
+        ctx = FlowContext(variables={"status": "error"})
+        assert flow._eval_condition("$v.status != ok", ctx) is True
+        assert flow._eval_condition("$v.status != error", ctx) is False
+
+    def test_truthy_check(self):
+        flow = Flow(flow_id="t", name="t")
+        ctx = FlowContext(variables={"flag": True, "empty": ""})
+        assert flow._eval_condition("$v.flag", ctx) is True
+        assert flow._eval_condition("$v.empty", ctx) is False
+        assert flow._eval_condition("$v.missing", ctx) is False
+
+    def test_type_error_returns_false(self):
+        flow = Flow(flow_id="t", name="t")
+        ctx = FlowContext(variables={"name": "alice"})
+        assert flow._eval_condition("$v.name > 5", ctx) is False
 
 
 # ── NodeHandler.resolve_inputs ──
@@ -460,33 +483,66 @@ class TestLLMChatNodeHandler:
 
 
 class TestFlowRouting:
-    """Flow 路由和 loop break 测试"""
+    """Flow 路由测试"""
 
-    def test_resolve_next_node_with_condition(self):
+    def test_resolve_next_node_with_expression(self):
         flow = Flow(
             flow_id="test",
             name="test",
             edges=[
-                {"source": "detect1", "condition": "qa", "target": "qa_node"},
-                {"source": "detect1", "condition": "chitchat", "target": "chat_node"},
-                {"source": "detect1", "condition": "done", "target": "end_node"},
+                {"source": "detect1", "condition": "$o.detect1.choice == qa", "target": "qa_node"},
+                {"source": "detect1", "condition": "$o.detect1.choice == chitchat", "target": "chat_node"},
+                {"source": "detect1", "target": "end_node"},
             ],
         )
-        assert flow._resolve_next_node("detect1", "qa") == "qa_node"
-        assert flow._resolve_next_node("detect1", "chitchat") == "chat_node"
-        assert flow._resolve_next_node("detect1", "done") == "end_node"
+        ctx = FlowContext()
+        ctx.set_output("detect1", {"choice": "qa"})
+        assert flow._resolve_next_node("detect1", ctx) == "qa_node"
+
+        ctx.set_output("detect1", {"choice": "chitchat"})
+        assert flow._resolve_next_node("detect1", ctx) == "chat_node"
+
+        ctx.set_output("detect1", {"choice": "unknown"})
+        assert flow._resolve_next_node("detect1", ctx) == "end_node"
 
-    def test_route_key_from_detect_result(self):
-        """detect 返回 {"choice": "qa"} 应该正确路由"""
-        detect_result = {"choice": "qa"}
-        route_key = Flow._extract_route_key(detect_result)
-        assert route_key == "qa"
+    def test_fallback_edge(self):
+        """无条件边作为 fallback"""
+        flow = Flow(
+            flow_id="test",
+            name="test",
+            edges=[
+                {"source": "node1", "condition": "$v.x == yes", "target": "branch_a"},
+                {"source": "node1", "target": "branch_b"},
+            ],
+        )
+        ctx = FlowContext(variables={"x": "no"})
+        assert flow._resolve_next_node("node1", ctx) == "branch_b"
+
+    def test_no_matching_edge(self):
+        """所有条件都不满足且无 fallback 时返回 None"""
+        flow = Flow(
+            flow_id="test",
+            name="test",
+            edges=[
+                {"source": "node1", "condition": "$v.x == yes", "target": "branch_a"},
+            ],
+        )
+        ctx = FlowContext(variables={"x": "no"})
+        assert flow._resolve_next_node("node1", ctx) is None
 
-    def test_route_key_from_normal_result(self):
-        """普通节点（无 choice）应该路由到 done"""
-        normal_result = {"result": "some text"}
-        route_key = Flow._extract_route_key(normal_result)
-        assert route_key == "done"
+    def test_cycle_limit_forces_fallback(self):
+        """循环超限时强制走 fallback"""
+        flow = Flow(
+            flow_id="test",
+            name="test",
+            edges=[
+                {"source": "loop_node", "condition": "$v.done == false", "target": "loop_node"},
+                {"source": "loop_node", "target": "exit_node"},
+            ],
+        )
+        ctx = FlowContext(variables={"done": False})
+        # force_fallback=True 时跳过条件边
+        assert flow._resolve_next_node("loop_node", ctx, force_fallback=True) == "exit_node"
 
 
 # ── Full data flow integration ──
@@ -658,3 +714,123 @@ class TestLLMEmbedNodeHandler:
         asyncio.get_event_loop().run_until_complete(handler.execute(node, ctx))
         call_args = mock_client.embed.call_args
         assert call_args.kwargs["model"] == "bge-m3"
+
+
+# ── Cycle limits integration ──
+
+
+class TestCycleLimits:
+    """图级别循环边 + cycle_limits 集成测试"""
+
+    def test_cycle_terminates_at_limit(self):
+        """循环边在达到 cycle_limits 时强制走 fallback"""
+        flow = Flow(
+            flow_id="test",
+            name="cycle_test",
+            nodes=[
+                {
+                    "id": "counter",
+                    "type": "python",
+                    "config": {
+                        "code": ("def main(n=None, **kwargs):\n    return {'n': (n if n is not None else 0) + 1}"),
+                        "inputs": {"n": "$o.counter.n"},
+                    },
+                },
+                {
+                    "id": "done",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'finished': True}"},
+                },
+            ],
+            edges=[
+                {"source": "counter", "condition": "$o.counter.n < 100", "target": "counter"},
+                {"source": "counter", "target": "done"},
+            ],
+            cycle_limits={"counter": 3},
+        )
+        ctx = FlowContext()
+        asyncio.get_event_loop().run_until_complete(flow.run(ctx))
+        # counter 最多执行 3 次，第 4 次进入时触发超限走 fallback
+        assert ctx.outputs["counter"]["n"] == 3
+        assert ctx.outputs["done"] == {"finished": True}
+
+    def test_cycle_without_limit_follows_condition(self):
+        """无 cycle_limits 时正常按条件退出循环"""
+        flow = Flow(
+            flow_id="test",
+            name="natural_exit",
+            nodes=[
+                {
+                    "id": "inc",
+                    "type": "python",
+                    "config": {
+                        "code": ("def main(n=None, **kwargs):\n    return {'n': (n if n is not None else 0) + 1}"),
+                        "inputs": {"n": "$o.inc.n"},
+                    },
+                },
+                {
+                    "id": "end",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'end': True}"},
+                },
+            ],
+            edges=[
+                {"source": "inc", "condition": "$o.inc.n < 5", "target": "inc"},
+                {"source": "inc", "target": "end"},
+            ],
+        )
+        ctx = FlowContext()
+        asyncio.get_event_loop().run_until_complete(flow.run(ctx))
+        assert ctx.outputs["inc"]["n"] == 5
+        assert ctx.outputs["end"] == {"end": True}
+
+
+# ── Parallel merge integration ──
+
+
+class TestParallelMerge:
+    """并行节点自动合并测试"""
+
+    def test_parallel_auto_merges_branch_results(self):
+        """parallel 节点各分支的 dict 结果自动合并"""
+        flow = Flow(
+            flow_id="test",
+            name="parallel_merge",
+            nodes=[
+                {
+                    "id": "par",
+                    "type": "parallel",
+                    "config": {"branches": ["kw_search", "vec_search"]},
+                },
+                {
+                    "id": "kw_search",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'keyword_results': [1, 2]}"},
+                },
+                {
+                    "id": "vec_search",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'vector_results': [3, 4]}"},
+                },
+                {
+                    "id": "merge_consumer",
+                    "type": "python",
+                    "config": {
+                        "code": (
+                            "def main(kw=None, vec=None, **kwargs):\n    return {'combined': (kw or []) + (vec or [])}"
+                        ),
+                        "inputs": {
+                            "kw": "$o.par.keyword_results",
+                            "vec": "$o.par.vector_results",
+                        },
+                    },
+                },
+            ],
+            edges=[
+                {"source": "par", "target": "merge_consumer"},
+            ],
+        )
+        ctx = FlowContext()
+        asyncio.get_event_loop().run_until_complete(flow.run(ctx))
+        assert ctx.outputs["par"] == {"keyword_results": [1, 2], "vector_results": [3, 4]}
+        assert ctx.outputs["merge_consumer"] == {"combined": [1, 2, 3, 4]}

{agstack-1.14.0 → agstack-1.16.0}/tests/test_flow_switch_subflow.py

@@ -293,8 +293,8 @@ class TestSwitchEdgeRouting:
                 },
             ],
             edges=[
-                {"source": "model_switch", "target": "agent_a", "condition": "strong"},
-                {"source": "model_switch", "target": "pipeline_b", "condition": "basic"},
+                {"source": "model_switch", "condition": "$o.model_switch.choice == strong", "target": "agent_a"},
+                {"source": "model_switch", "condition": "$o.model_switch.choice == basic", "target": "pipeline_b"},
             ],
         )
 
@@ -330,8 +330,8 @@ class TestSwitchEdgeRouting:
                 },
             ],
             edges=[
-                {"source": "sw", "target": "node_a", "condition": "a"},
-                {"source": "sw", "target": "node_b", "condition": "b"},
+                {"source": "sw", "condition": "$o.sw.choice == a", "target": "node_a"},
+                {"source": "sw", "condition": "$o.sw.choice == b", "target": "node_b"},
             ],
         )