refactor: 重构重试策略、条件函数与上下文注入逻辑

主要变更：
1. 替换旧retries参数为RetryPolicy配置
2. 重构条件函数，支持上下文参数与动态依赖判断
3. 更新上下文注入逻辑，支持软依赖与更清晰的注入描述
4. 新增sglang CLI命令与相关配置
5. 格式化代码统一列表与参数写法
6. 更新文档与测试用例适配新API

tests/test_conditions.py

@@ -1,142 +1,218 @@
 """Tests for conditions module."""
 
+from __future__ import annotations
+
 import os
 import sys
 from unittest.mock import patch
 
 from pyflowx.conditions import (
+    IS_LINUX,
+    IS_MACOS,
+    IS_POSIX,
+    IS_WINDOWS,
     BuiltinConditions,
     Constants,
 )
 
+_CTX: dict[str, object] = {}
+
 
 def test_constants_is_windows():
-    """Test Constants.IS_WINDOWS is correct."""
     assert (sys.platform == "win32") == Constants.IS_WINDOWS
 
 
 def test_constants_is_linux():
-    """Test Constants.IS_LINUX is correct."""
     assert (sys.platform == "linux") == Constants.IS_LINUX
 
 
 def test_constants_is_macos():
-    """Test Constants.IS_MACOS is correct."""
     assert (sys.platform == "darwin") == Constants.IS_MACOS
 
 
 def test_constants_is_posix():
-    """Test Constants.IS_POSIX is correct."""
     assert (sys.platform != "win32") == Constants.IS_POSIX
 
 
+def test_module_level_static_conditions():
+    assert IS_WINDOWS(_CTX) == Constants.IS_WINDOWS
+    assert IS_LINUX(_CTX) == Constants.IS_LINUX
+    assert IS_MACOS(_CTX) == Constants.IS_MACOS
+    assert IS_POSIX(_CTX) == Constants.IS_POSIX
 
-def test_builtin_conditions_python_version_major_only():
-    """Test BuiltinConditions.PYTHON_VERSION with major only."""
-    # Test with current Python version
+
+def test_python_version_major_only():
     current_major = sys.version_info.major
-    assert BuiltinConditions.PYTHON_VERSION(current_major) is True
-    assert BuiltinConditions.PYTHON_VERSION(current_major + 1) is False
+    assert BuiltinConditions.PYTHON_VERSION(current_major)(_CTX) is True
+    assert BuiltinConditions.PYTHON_VERSION(current_major + 1)(_CTX) is False
 
 
-def test_builtin_conditions_python_version_with_minor():
-    """Test BuiltinConditions.PYTHON_VERSION with major and minor."""
+def test_python_version_with_minor():
     current_major = sys.version_info.major
     current_minor = sys.version_info.minor
-    assert BuiltinConditions.PYTHON_VERSION(current_major, current_minor) is True
-    assert BuiltinConditions.PYTHON_VERSION(current_major, current_minor + 1) is False
+    assert BuiltinConditions.PYTHON_VERSION(current_major, current_minor)(_CTX) is True
+    assert BuiltinConditions.PYTHON_VERSION(current_major, current_minor + 1)(_CTX) is False
 
 
-def test_builtin_conditions_python_version_at_least():
-    """Test BuiltinConditions.PYTHON_VERSION_AT_LEAST."""
+def test_python_version_at_least():
     current_major = sys.version_info.major
     current_minor = sys.version_info.minor
-    # Current version should be at least itself
-    assert BuiltinConditions.PYTHON_VERSION_AT_LEAST(current_major, current_minor) is True
-    # Current version should be at least an older version
-    assert BuiltinConditions.PYTHON_VERSION_AT_LEAST(current_major - 1, 0) is True
-    # Current version should NOT be at least a newer version
-    assert BuiltinConditions.PYTHON_VERSION_AT_LEAST(current_major + 1, 0) is False
+    assert BuiltinConditions.PYTHON_VERSION_AT_LEAST(current_major, current_minor)(_CTX) is True
+    assert BuiltinConditions.PYTHON_VERSION_AT_LEAST(current_major - 1, 0)(_CTX) is True
+    assert BuiltinConditions.PYTHON_VERSION_AT_LEAST(current_major + 1, 0)(_CTX) is False
 
 
-def test_builtin_conditions_HAS_INSTALLED_true():
-    """Test BuiltinConditions.HAS_INSTALLED when app exists."""
-    # Python should always be available
-    condition = BuiltinConditions.HAS_INSTALLED("python")
-    assert condition() is True
+def test_has_installed_true():
+    condition = BuiltinConditions.HAS_INSTALLED("python3")
+    assert condition(_CTX) is True
 
 
-def test_builtin_conditions_HAS_INSTALLED_false():
-    """Test BuiltinConditions.HAS_INSTALLED when app doesn't exist."""
+def test_has_installed_false():
     condition = BuiltinConditions.HAS_INSTALLED("nonexistent_app_12345")
-    assert condition() is False
+    assert condition(_CTX) is False
 
 
-def test_builtin_conditions_env_var_exists_true():
-    """Test BuiltinConditions.ENV_VAR_EXISTS when variable exists."""
+def test_env_var_exists_true():
     with patch.dict(os.environ, {"TEST_VAR": "value"}):
         condition = BuiltinConditions.ENV_VAR_EXISTS("TEST_VAR")
-        assert condition() is True
+        assert condition(_CTX) is True
 
 
-def test_builtin_conditions_env_var_exists_false():
-    """Test BuiltinConditions.ENV_VAR_EXISTS when variable doesn't exist."""
+def test_env_var_exists_false():
     condition = BuiltinConditions.ENV_VAR_EXISTS("NONEXISTENT_VAR_12345")
-    assert condition() is False
+    assert condition(_CTX) is False
 
 
-def test_builtin_conditions_env_var_equals_true():
-    """Test BuiltinConditions.ENV_VAR_EQUALS when value matches."""
+def test_env_var_equals_true():
     with patch.dict(os.environ, {"TEST_VAR": "expected_value"}):
         condition = BuiltinConditions.ENV_VAR_EQUALS("TEST_VAR", "expected_value")
-        assert condition() is True
+        assert condition(_CTX) is True
 
 
-def test_builtin_conditions_env_var_equals_false():
-    """Test BuiltinConditions.ENV_VAR_EQUALS when value doesn't match."""
+def test_env_var_equals_false():
     with patch.dict(os.environ, {"TEST_VAR": "different_value"}):
         condition = BuiltinConditions.ENV_VAR_EQUALS("TEST_VAR", "expected_value")
-        assert condition() is False
+        assert condition(_CTX) is False
 
 
-def test_builtin_conditions_not():
-    """Test BuiltinConditions.NOT."""
-    true_condition = lambda: True  # noqa: E731
-    false_condition = lambda: False  # noqa: E731
+def test_not():
+    true_cond = BuiltinConditions.HAS_INSTALLED("python3")
+    false_cond = BuiltinConditions.HAS_INSTALLED("nonexistent_app_12345")
 
-    not_true = BuiltinConditions.NOT(true_condition)
-    assert not_true() is False
-
-    not_false = BuiltinConditions.NOT(false_condition)
-    assert not_false() is True
+    assert BuiltinConditions.NOT(true_cond)(_CTX) is False
+    assert BuiltinConditions.NOT(false_cond)(_CTX) is True
 
 
-def test_builtin_conditions_and_all_true():
-    """Test BuiltinConditions.AND when all conditions are true."""
-    true_condition = lambda: True  # noqa: E731
-    condition = BuiltinConditions.AND(true_condition, true_condition, true_condition)
-    assert condition() is True
+def test_and_all_true():
+    cond = BuiltinConditions.AND(
+        BuiltinConditions.HAS_INSTALLED("python3"),
+        BuiltinConditions.HAS_INSTALLED("python3"),
+    )
+    assert cond(_CTX) is True
 
 
-def test_builtin_conditions_and_one_false():
-    """Test BuiltinConditions.AND when one condition is false."""
-    true_condition = lambda: True  # noqa: E731
-    false_condition = lambda: False  # noqa: E731
-    condition = BuiltinConditions.AND(true_condition, false_condition, true_condition)
-    assert condition() is False
+def test_and_one_false():
+    cond = BuiltinConditions.AND(
+        BuiltinConditions.HAS_INSTALLED("python3"),
+        BuiltinConditions.HAS_INSTALLED("nonexistent_app"),
+    )
+    assert cond(_CTX) is False
 
 
-def test_builtin_conditions_or_all_false():
-    """Test BuiltinConditions.OR when all conditions are false."""
-    false_condition = lambda: False  # noqa: E731
-    condition = BuiltinConditions.OR(false_condition, false_condition, false_condition)
-    assert condition() is False
+def test_or_all_false():
+    cond = BuiltinConditions.OR(
+        BuiltinConditions.HAS_INSTALLED("nonexistent1"),
+        BuiltinConditions.HAS_INSTALLED("nonexistent2"),
+    )
+    assert cond(_CTX) is False
 
 
-def test_builtin_conditions_or_one_true():
-    """Test BuiltinConditions.OR when one condition is true."""
-    true_condition = lambda: True  # noqa: E731
-    false_condition = lambda: False  # noqa: E731
-    condition = BuiltinConditions.OR(false_condition, true_condition, false_condition)
-    assert condition() is True
+def test_or_one_true():
+    cond = BuiltinConditions.OR(
+        BuiltinConditions.HAS_INSTALLED("nonexistent1"),
+        BuiltinConditions.HAS_INSTALLED("python3"),
+    )
+    assert cond(_CTX) is True
 
+
+# ---------------------------------------------------------------------- #
+# 上下文条件：基于上游依赖结果
+# ---------------------------------------------------------------------- #
+def test_dep_equals_true():
+    ctx = {"upstream": 42}
+    cond = BuiltinConditions.DEP_EQUALS("upstream", 42)
+    assert cond(ctx) is True
+
+
+def test_dep_equals_false():
+    ctx = {"upstream": 99}
+    cond = BuiltinConditions.DEP_EQUALS("upstream", 42)
+    assert cond(ctx) is False
+
+
+def test_dep_equals_missing_dep():
+    cond = BuiltinConditions.DEP_EQUALS("missing", 42)
+    assert cond({}) is False
+
+
+def test_dep_matches_true():
+    ctx = {"upstream": [1, 2, 3]}
+    cond = BuiltinConditions.DEP_MATCHES("upstream", lambda v: len(v) == 3)
+    assert cond(ctx) is True
+
+
+def test_dep_matches_false():
+    ctx = {"upstream": [1, 2]}
+    cond = BuiltinConditions.DEP_MATCHES("upstream", lambda v: len(v) == 3)
+    assert cond(ctx) is False
+
+
+def test_dep_matches_exception_returns_false():
+    ctx = {"upstream": ""}
+    cond = BuiltinConditions.DEP_MATCHES("upstream", lambda v: v[0])
+    assert cond(ctx) is False
+
+
+def test_dep_present_true():
+    ctx = {"upstream": "value"}
+    cond = BuiltinConditions.DEP_PRESENT("upstream")
+    assert cond(ctx) is True
+
+
+def test_dep_present_false_none():
+    # pyrefly: ignore [implicit-any-empty-container]
+    ctx = {"upstream": None}
+    cond = BuiltinConditions.DEP_PRESENT("upstream")
+    assert cond(ctx) is False
+
+
+def test_dep_present_false_missing():
+    cond = BuiltinConditions.DEP_PRESENT("missing")
+    assert cond({}) is False
+
+
+def test_dep_truthy_true():
+    ctx = {"upstream": [1]}
+    cond = BuiltinConditions.DEP_TRUTHY("upstream")
+    assert cond(ctx) is True
+
+
+def test_dep_truthy_false():
+    # pyrefly: ignore [implicit-any-empty-container]
+    ctx = {"upstream": []}
+    cond = BuiltinConditions.DEP_TRUTHY("upstream")
+    assert cond(ctx) is False
+
+
+def test_dep_truthy_missing():
+    cond = BuiltinConditions.DEP_TRUTHY("missing")
+    assert cond({}) is False
+
+
+def test_logical_combination_with_dep_conditions():
+    ctx = {"a": 1, "b": 0}
+    cond = BuiltinConditions.AND(
+        BuiltinConditions.DEP_EQUALS("a", 1),
+        BuiltinConditions.NOT(BuiltinConditions.DEP_TRUTHY("b")),
+    )
+    assert cond(ctx) is True

tests/test_context.py

@@ -141,7 +141,7 @@ class TestDescribeInjection:
 
         spec = px.TaskSpec("t", fn, depends_on=("a",))
         desc = describe_injection(spec)
-        assert "a=<result:a>" in desc
+        assert "a=<dep:a>" in desc
         assert "ctx=<Context>" in desc
         assert "flag=<default>" in desc
 

tests/test_executors.py

@@ -84,7 +84,9 @@ def test_retries_then_succeeds() -> None:
             raise RuntimeError("not yet")
         return "ok"
 
-    graph = px.Graph.from_specs([px.TaskSpec("flaky", flaky, retries=2)])
+    graph = px.Graph.from_specs([
+        px.TaskSpec("flaky", flaky, retry=px.RetryPolicy(max_attempts=3)),
+    ])
     report = px.run(graph, strategy="sequential")
     assert report.success
     assert report["flaky"] == "ok"
@@ -95,7 +97,9 @@ def test_retries_exhausted() -> None:
     def always_fail() -> None:
         raise RuntimeError("nope")
 
-    graph = px.Graph.from_specs([px.TaskSpec("f", always_fail, retries=2)])
+    graph = px.Graph.from_specs([
+        px.TaskSpec("f", always_fail, retry=px.RetryPolicy(max_attempts=3)),
+    ])
     with pytest.raises(TaskFailedError) as exc_info:
         _ = px.run(graph, strategy="sequential")
     assert exc_info.value.attempts == 3
@@ -332,7 +336,9 @@ def test_async_timeout_retry_then_succeed() -> None:
             await asyncio.sleep(10)  # 触发超时
         return "ok"
 
-    graph = px.Graph.from_specs([px.TaskSpec("a", flaky, retries=2, timeout=0.05)])
+    graph = px.Graph.from_specs([
+        px.TaskSpec("a", flaky, retry=px.RetryPolicy(max_attempts=3), timeout=0.05),
+    ])
     report = px.run(graph, strategy="async")
     assert report.success
     assert report["a"] == "ok"
@@ -349,7 +355,9 @@ def test_async_failure_retry_branch(caplog: pytest.LogCaptureFixture) -> None:
             raise RuntimeError("not yet")
         return "ok"
 
-    graph = px.Graph.from_specs([px.TaskSpec("a", flaky, retries=2)])
+    graph = px.Graph.from_specs([
+        px.TaskSpec("a", flaky, retry=px.RetryPolicy(max_attempts=3)),
+    ])
     with caplog.at_level("WARNING", logger="pyflowx"):
         report = px.run(graph, strategy="async")
     assert report.success
@@ -489,7 +497,7 @@ def test_run_empty_graph() -> None:
 # ---------------------------------------------------------------------- #
 def test_downstream_skipped_when_upstream_skipped_sequential() -> None:
     """上游任务被 SKIPPED 后，下游任务也应被 SKIPPED（sequential 策略）."""
-    never_true = lambda: False  # noqa: E731
+    never_true = lambda _ctx: False  # noqa: E731
 
     def downstream(upstream: str) -> str:
         return upstream + "_processed"
@@ -506,7 +514,7 @@ def test_downstream_skipped_when_upstream_skipped_sequential() -> None:
 
 def test_downstream_skipped_when_upstream_skipped_thread() -> None:
     """上游任务被 SKIPPED 后，下游任务也应被 SKIPPED（thread 策略）."""
-    never_true = lambda: False  # noqa: E731
+    never_true = lambda _ctx: False  # noqa: E731
 
     def downstream(upstream: str) -> str:
         return upstream + "_processed"
@@ -530,7 +538,7 @@ def test_downstream_skipped_when_upstream_skipped_async() -> None:
     async def downstream(upstream: str) -> str:
         return upstream + "_processed"
 
-    never_true = lambda: False  # noqa: E731
+    never_true = lambda _ctx: False  # noqa: E731
 
     graph = px.Graph.from_specs([
         px.TaskSpec("upstream", upstream, conditions=(never_true,)),
@@ -544,7 +552,7 @@ def test_downstream_skipped_when_upstream_skipped_async() -> None:
 
 def test_downstream_executes_when_upstream_succeeds() -> None:
     """上游任务成功时，下游任务应正常执行."""
-    always_true = lambda: True  # noqa: E731
+    always_true = lambda _ctx: True  # noqa: E731
 
     def upstream() -> str:
         return "hello"

tests/test_executors_edge_cases.py

@@ -85,7 +85,7 @@ def test_verbose_run_with_skipped_lifecycle(capsys: pytest.CaptureFixture[str]):
     spec = px.TaskSpec(
         "test",
         fn=lambda: "result",
-        conditions=(lambda: False,),
+        conditions=(lambda _ctx: False,),
     )
     graph = px.Graph.from_specs([spec])
     report = px.run(graph, strategy="sequential", verbose=True)
@@ -140,7 +140,7 @@ def test_verbose_event_callback_skipped():
     spec = px.TaskSpec(
         "test",
         fn=lambda: "result",
-        conditions=(lambda: False,),
+        conditions=(lambda _ctx: False,),
         verbose=True,
     )
     graph = px.Graph.from_specs([spec])
@@ -161,7 +161,11 @@ def test_execute_sync_with_retries():
             raise ValueError("temporary error")
         return "success"
 
-    spec = px.TaskSpec("retry_test", fn=failing_function, retries=3)
+    spec = px.TaskSpec(
+        "retry_test",
+        fn=failing_function,
+        retry=px.RetryPolicy(max_attempts=3),
+    )
     graph = px.Graph.from_specs([spec])
 
     # Should succeed after retries
@@ -182,7 +186,11 @@ def test_execute_async_with_retries():
             raise ValueError("temporary error")
         return "success"
 
-    spec = px.TaskSpec("retry_async_test", fn=failing_async_function, retries=3)
+    spec = px.TaskSpec(
+        "retry_async_test",
+        fn=failing_async_function,
+        retry=px.RetryPolicy(max_attempts=3),
+    )
     graph = px.Graph.from_specs([spec])
 
     # Should succeed after retries
@@ -196,7 +204,7 @@ def test_execute_sync_skip_on_condition():
     spec = px.TaskSpec(
         "skip_test",
         fn=lambda: "result",
-        conditions=(lambda: False,),
+        conditions=(lambda _ctx: False,),
     )
     graph = px.Graph.from_specs([spec])
 
@@ -210,7 +218,7 @@ def test_execute_async_skip_on_condition():
     spec = px.TaskSpec(
         "skip_async_test",
         fn=lambda: "result",
-        conditions=(lambda: False,),
+        conditions=(lambda _ctx: False,),
     )
     graph = px.Graph.from_specs([spec])
 

tests/test_graph.py

@@ -13,13 +13,11 @@ def _fn() -> None:
 
 
 def test_from_specs_builds_graph() -> None:
-    graph = px.Graph.from_specs(
-        [
-            px.TaskSpec("a", _fn),
-            px.TaskSpec("b", _fn, depends_on=("a",)),
-            px.TaskSpec("c", _fn, depends_on=("a", "b")),
-        ]
-    )
+    graph = px.Graph.from_specs([
+        px.TaskSpec("a", _fn),
+        px.TaskSpec("b", _fn, depends_on=("a",)),
+        px.TaskSpec("c", _fn, depends_on=("a", "b")),
+    ])
     assert set(graph.names) == {"a", "b", "c"}
     assert graph.dependencies("c") == ("a", "b")
     assert len(graph) == 3
@@ -28,23 +26,19 @@ def test_from_specs_builds_graph() -> None:
 
 def test_from_specs_allows_forward_references() -> None:
     # b depends on a, but a is declared after b — order should not matter.
-    graph = px.Graph.from_specs(
-        [
-            px.TaskSpec("b", _fn, depends_on=("a",)),
-            px.TaskSpec("a", _fn),
-        ]
-    )
+    graph = px.Graph.from_specs([
+        px.TaskSpec("b", _fn, depends_on=("a",)),
+        px.TaskSpec("a", _fn),
+    ])
     assert graph.layers() == [["a"], ["b"]]
 
 
 def test_duplicate_task_raises() -> None:
     with pytest.raises(DuplicateTaskError):
-        _ = px.Graph.from_specs(
-            [
-                px.TaskSpec("a", _fn),
-                px.TaskSpec("a", _fn),
-            ]
-        )
+        _ = px.Graph.from_specs([
+            px.TaskSpec("a", _fn),
+            px.TaskSpec("a", _fn),
+        ])
 
 
 def test_missing_dependency_raises() -> None:
@@ -57,24 +51,20 @@ def test_missing_dependency_raises() -> None:
 
 def test_cycle_detection() -> None:
     with pytest.raises(CycleError):
-        _ = px.Graph.from_specs(
-            [
-                px.TaskSpec("a", _fn, depends_on=("c",)),
-                px.TaskSpec("b", _fn, depends_on=("a",)),
-                px.TaskSpec("c", _fn, depends_on=("b",)),
-            ]
-        )
+        _ = px.Graph.from_specs([
+            px.TaskSpec("a", _fn, depends_on=("c",)),
+            px.TaskSpec("b", _fn, depends_on=("a",)),
+            px.TaskSpec("c", _fn, depends_on=("b",)),
+        ])
 
 
 def test_layers_grouping() -> None:
-    graph = px.Graph.from_specs(
-        [
-            px.TaskSpec("a", _fn),
-            px.TaskSpec("b", _fn),
-            px.TaskSpec("c", _fn, depends_on=("a", "b")),
-            px.TaskSpec("d", _fn, depends_on=("c",)),
-        ]
-    )
+    graph = px.Graph.from_specs([
+        px.TaskSpec("a", _fn),
+        px.TaskSpec("b", _fn),
+        px.TaskSpec("c", _fn, depends_on=("a", "b")),
+        px.TaskSpec("d", _fn, depends_on=("c",)),
+    ])
     layers = graph.layers()
     assert layers == [["a", "b"], ["c"], ["d"]]
 
@@ -85,12 +75,10 @@ def test_self_dependency_rejected() -> None:
 
 
 def test_to_mermaid() -> None:
-    graph = px.Graph.from_specs(
-        [
-            px.TaskSpec("a", _fn),
-            px.TaskSpec("b", _fn, depends_on=("a",)),
-        ]
-    )
+    graph = px.Graph.from_specs([
+        px.TaskSpec("a", _fn),
+        px.TaskSpec("b", _fn, depends_on=("a",)),
+    ])
     mermaid = graph.to_mermaid()
     assert mermaid.startswith("graph TD")
     assert 'a["a"]' in mermaid
@@ -104,13 +92,11 @@ def test_to_mermaid_invalid_orientation() -> None:
 
 
 def test_subgraph_by_tags() -> None:
-    graph = px.Graph.from_specs(
-        [
-            px.TaskSpec("a", _fn, tags=("ingest",)),
-            px.TaskSpec("b", _fn, depends_on=("a",), tags=("ingest",)),
-            px.TaskSpec("c", _fn, depends_on=("b",), tags=("report",)),
-        ]
-    )
+    graph = px.Graph.from_specs([
+        px.TaskSpec("a", _fn, tags=("ingest",)),
+        px.TaskSpec("b", _fn, depends_on=("a",), tags=("ingest",)),
+        px.TaskSpec("c", _fn, depends_on=("b",), tags=("report",)),
+    ])
     sub = graph.subgraph(["ingest"])
     assert set(sub.names) == {"a", "b"}
     # Edge to dropped task c is removed; b no longer waits for anything
@@ -119,13 +105,11 @@ def test_subgraph_by_tags() -> None:
 
 
 def test_subgraph_by_names() -> None:
-    graph = px.Graph.from_specs(
-        [
-            px.TaskSpec("a", _fn),
-            px.TaskSpec("b", _fn, depends_on=("a",)),
-            px.TaskSpec("c", _fn, depends_on=("b",)),
-        ]
-    )
+    graph = px.Graph.from_specs([
+        px.TaskSpec("a", _fn),
+        px.TaskSpec("b", _fn, depends_on=("a",)),
+        px.TaskSpec("c", _fn, depends_on=("b",)),
+    ])
     sub = graph.subgraph_by_names(["a", "b"])
     assert set(sub.names) == {"a", "b"}
     # c is dropped, so b's dep on c (none here) — but a->b edge preserved.
@@ -139,12 +123,10 @@ def test_subgraph_by_names_unknown() -> None:
 
 
 def test_describe() -> None:
-    graph = px.Graph.from_specs(
-        [
-            px.TaskSpec("a", _fn),
-            px.TaskSpec("b", _fn, depends_on=("a",)),
-        ]
-    )
+    graph = px.Graph.from_specs([
+        px.TaskSpec("a", _fn),
+        px.TaskSpec("b", _fn, depends_on=("a",)),
+    ])
     desc = graph.describe()
     assert "Layer 1" in desc
     assert "Layer 2" in desc
@@ -187,12 +169,10 @@ def test_spec_accessor() -> None:
 
 
 def test_dependencies_accessor() -> None:
-    graph = px.Graph.from_specs(
-        [
-            px.TaskSpec("a", _fn),
-            px.TaskSpec("b", _fn, depends_on=("a",)),
-        ]
-    )
+    graph = px.Graph.from_specs([
+        px.TaskSpec("a", _fn),
+        px.TaskSpec("b", _fn, depends_on=("a",)),
+    ])
     assert graph.dependencies("a") == ()
     assert graph.dependencies("b") == ("a",)
 
@@ -210,16 +190,20 @@ def test_empty_graph_layers() -> None:
 
 
 def test_subgraph_preserves_metadata() -> None:
-    """子图应保留原任务的 retries/timeout/tags 等元数据。"""
-    graph = px.Graph.from_specs(
-        [
-            px.TaskSpec("a", _fn, tags=("x",), retries=3, timeout=5.0),
-            px.TaskSpec("b", _fn, depends_on=("a",), tags=("y",)),
-        ]
-    )
+    """子图应保留原任务的 retry/timeout/tags 等元数据。"""
+    graph = px.Graph.from_specs([
+        px.TaskSpec(
+            "a",
+            _fn,
+            tags=("x",),
+            retry=px.RetryPolicy(max_attempts=3),
+            timeout=5.0,
+        ),
+        px.TaskSpec("b", _fn, depends_on=("a",), tags=("y",)),
+    ])
     sub = graph.subgraph(["x"])
     spec = sub.spec("a")
-    assert spec.retries == 3
+    assert spec.retry.max_attempts == 3
     assert spec.timeout == 5.0
     assert spec.tags == ("x",)
 

tests/test_runner.py

@@ -29,24 +29,20 @@ def _echo_graph(name: str = "echo_task", msg: str = "hello") -> px.Graph:
 
 def _failing_graph() -> px.Graph:
     """构造一个必定失败的单任务图."""
-    return px.Graph.from_specs(
-        [
-            px.TaskSpec(
-                "fail",
-                cmd=["python", "-c", "import sys; sys.exit(1)"],
-            )
-        ]
-    )
+    return px.Graph.from_specs([
+        px.TaskSpec(
+            "fail",
+            cmd=["python", "-c", "import sys; sys.exit(1)"],
+        )
+    ])
 
 
 def _multi_task_graph() -> px.Graph:
     """构造一个带依赖的多任务图."""
-    return px.Graph.from_specs(
-        [
-            px.TaskSpec("a", cmd=[*ECHO_CMD, "a"]),
-            px.TaskSpec("b", cmd=[*ECHO_CMD, "b"], depends_on=("a",)),
-        ]
-    )
+    return px.Graph.from_specs([
+        px.TaskSpec("a", cmd=[*ECHO_CMD, "a"]),
+        px.TaskSpec("b", cmd=[*ECHO_CMD, "b"], depends_on=("a",)),
+    ])
 
 
 # ---------------------------------------------------------------------- #
@@ -240,12 +236,10 @@ class TestCliRunnerRunSuccess:
         def track_b() -> None:
             executed.append("b")
 
-        runner = px.CliRunner(
-            {
-                "a": px.Graph.from_specs([px.TaskSpec("a", track_a)]),
-                "b": px.Graph.from_specs([px.TaskSpec("b", track_b)]),
-            }
-        )
+        runner = px.CliRunner({
+            "a": px.Graph.from_specs([px.TaskSpec("a", track_a)]),
+            "b": px.Graph.from_specs([px.TaskSpec("b", track_b)]),
+        })
         _ = runner.run(["b"])
         assert executed == ["b"]
 
@@ -318,15 +312,13 @@ class TestCliRunnerVerbose:
 
     def test_verbose_prints_skip_lifecycle(self, capsys: pytest.CaptureFixture[str]) -> None:
         """verbose 模式下跳过的任务应打印跳过信息."""
-        graph = px.Graph.from_specs(
-            [
-                px.TaskSpec(
-                    "skip_me",
-                    cmd=[*ECHO_CMD, "skip"],
-                    conditions=(lambda: False,),
-                ),
-            ]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec(
+                "skip_me",
+                cmd=[*ECHO_CMD, "skip"],
+                conditions=(lambda _ctx: False,),
+            ),
+        ])
         runner = px.CliRunner({"skip": graph})
         _ = runner.run(["skip"])
         captured = capsys.readouterr()
@@ -394,13 +386,11 @@ class TestCliRunnerList:
 
     def test_list_prints_all_commands(self, capsys: pytest.CaptureFixture[str]) -> None:
         """--list 应打印所有命令."""
-        runner = px.CliRunner(
-            {
-                "clean": _echo_graph("c", "clean"),
-                "build": _echo_graph("b", "build"),
-                "test": _echo_graph("t", "test"),
-            }
-        )
+        runner = px.CliRunner({
+            "clean": _echo_graph("c", "clean"),
+            "build": _echo_graph("b", "build"),
+            "test": _echo_graph("t", "test"),
+        })
         _ = runner.run(["--list"])
         captured = capsys.readouterr()
         assert "clean" in captured.out
@@ -523,30 +513,26 @@ class TestCliRunnerIntegration:
 
     def test_condition_skipped_command_succeeds(self) -> None:
         """条件不满足时任务跳过, 整体仍成功."""
-        graph = px.Graph.from_specs(
-            [
-                px.TaskSpec(
-                    "skip_me",
-                    cmd=[*ECHO_CMD, "should not run"],
-                    conditions=(lambda: False,),
-                ),
-            ]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec(
+                "skip_me",
+                cmd=[*ECHO_CMD, "should not run"],
+                conditions=(lambda _ctx: False,),
+            ),
+        ])
         runner = px.CliRunner({"skip": graph})
         exit_code = runner.run(["skip"])
         assert exit_code == CliExitCode.SUCCESS.value
 
     def test_condition_met_command_succeeds(self) -> None:
         """条件满足时任务执行, 整体成功."""
-        graph = px.Graph.from_specs(
-            [
-                px.TaskSpec(
-                    "run_me",
-                    cmd=[*ECHO_CMD, "should run"],
-                    conditions=(lambda: True,),
-                ),
-            ]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec(
+                "run_me",
+                cmd=[*ECHO_CMD, "should run"],
+                conditions=(lambda _ctx: True,),
+            ),
+        ])
         runner = px.CliRunner({"run": graph})
         exit_code = runner.run(["run"])
         assert exit_code == CliExitCode.SUCCESS.value
@@ -562,14 +548,12 @@ class TestCliRunnerIntegration:
 
             return fn
 
-        graph = px.Graph.from_specs(
-            [
-                px.TaskSpec("a", make("a")),
-                px.TaskSpec("b", make("b"), depends_on=("a",)),
-                px.TaskSpec("c", make("c"), depends_on=("a",)),
-                px.TaskSpec("d", make("d"), depends_on=("b", "c")),
-            ]
-        )
+        graph = px.Graph.from_specs([
+            px.TaskSpec("a", make("a")),
+            px.TaskSpec("b", make("b"), depends_on=("a",)),
+            px.TaskSpec("c", make("c"), depends_on=("a",)),
+            px.TaskSpec("d", make("d"), depends_on=("b", "c")),
+        ])
         runner = px.CliRunner({"diamond": graph})
         exit_code = runner.run(["diamond"])
         assert exit_code == CliExitCode.SUCCESS.value
@@ -577,12 +561,10 @@ class TestCliRunnerIntegration:
 
     def test_mixed_fn_and_cmd_commands(self) -> None:
         """混合 fn 和 cmd 的命令应都能执行."""
-        runner = px.CliRunner(
-            {
-                "fn_cmd": px.Graph.from_specs([px.TaskSpec("fn", fn=lambda: "fn-result")]),
-                "cmd_cmd": px.Graph.from_specs([px.TaskSpec("cmd", cmd=[*ECHO_CMD, "cmd-result"])]),
-            }
-        )
+        runner = px.CliRunner({
+            "fn_cmd": px.Graph.from_specs([px.TaskSpec("fn", fn=lambda: "fn-result")]),
+            "cmd_cmd": px.Graph.from_specs([px.TaskSpec("cmd", cmd=[*ECHO_CMD, "cmd-result"])]),
+        })
         assert runner.run(["fn_cmd"]) == CliExitCode.SUCCESS.value
         assert runner.run(["cmd_cmd"]) == CliExitCode.SUCCESS.value
 

tests/test_task.py

@@ -6,7 +6,7 @@ from datetime import datetime
 
 import pytest
 
-from pyflowx.task import TaskResult, TaskSpec, TaskStatus
+from pyflowx.task import RetryPolicy, TaskResult, TaskSpec, TaskStatus
 
 
 def _fn() -> None:
@@ -18,9 +18,9 @@ def test_spec_empty_name_rejected() -> None:
         TaskSpec("", _fn)
 
 
-def test_spec_negative_retries_rejected() -> None:
-    with pytest.raises(ValueError, match="retries"):
-        TaskSpec("a", _fn, retries=-1)
+def test_spec_negative_max_attempts_rejected() -> None:
+    with pytest.raises(ValueError, match="max_attempts"):
+        TaskSpec("a", _fn, retry=RetryPolicy(max_attempts=0))
 
 
 def test_spec_zero_timeout_rejected() -> None:

tests/test_task_edge_cases.py

@@ -67,7 +67,9 @@ def test_taskspec_wrap_cmd_verbose():
 
 def test_taskspec_wrap_cmd_error():
     """Test TaskSpec._wrap_cmd handles command error."""
-    spec = TaskSpec("test", cmd=["python", "-c", "import sys; sys.exit(1)"])
+    import sys
+
+    spec = TaskSpec("test", cmd=[sys.executable, "-c", "import sys; sys.exit(1)"])
     wrapped_fn = spec.effective_fn
 
     with pytest.raises(RuntimeError, match="命令执行失败"):
@@ -105,10 +107,10 @@ def test_taskspec_conditions_check():
     spec = px.TaskSpec(
         "test",
         fn=lambda: "result",
-        conditions=(lambda: True,),
+        conditions=(lambda _ctx: True,),
     )
 
-    assert spec.should_execute() is True
+    assert spec.should_execute({})[0] is True
 
 
 def test_taskspec_conditions_false():
@@ -116,10 +118,10 @@ def test_taskspec_conditions_false():
     spec = px.TaskSpec(
         "test",
         fn=lambda: "result",
-        conditions=(lambda: False,),
+        conditions=(lambda _ctx: False,),
     )
 
-    assert spec.should_execute() is False
+    assert spec.should_execute({})[0] is False
 
 
 def test_taskspec_conditions_multiple():
@@ -127,10 +129,10 @@ def test_taskspec_conditions_multiple():
     spec = px.TaskSpec(
         "test",
         fn=lambda: "result",
-        conditions=(lambda: True, lambda: True, lambda: True),
+        conditions=(lambda _ctx: True, lambda _ctx: True, lambda _ctx: True),
     )
 
-    assert spec.should_execute() is True
+    assert spec.should_execute({})[0] is True
 
 
 def test_taskspec_conditions_multiple_one_false():
@@ -138,10 +140,10 @@ def test_taskspec_conditions_multiple_one_false():
     spec = px.TaskSpec(
         "test",
         fn=lambda: "result",
-        conditions=(lambda: True, lambda: False, lambda: True),
+        conditions=(lambda _ctx: True, lambda _ctx: False, lambda _ctx: True),
     )
 
-    assert spec.should_execute() is False
+    assert spec.should_execute({})[0] is False
 
 
 def test_taskspec_list_cmd_timeout_mocked():
@@ -218,27 +220,28 @@ def test_taskspec_shell_cmd_os_error_mocked():
 # ---------------------------------------------------------------------- #
 def test_skip_if_missing_with_available_command():
     """skip_if_missing=True 时，命令存在应返回 True."""
-    # python 命令在测试环境中一定存在
-    spec = TaskSpec("test", cmd=["python", "--version"], skip_if_missing=True)
-    assert spec.should_execute() is True
+    import sys
+
+    spec = TaskSpec("test", cmd=[sys.executable, "--version"], skip_if_missing=True)
+    assert spec.should_execute({})[0] is True
 
 
 def test_skip_if_missing_with_missing_command():
     """skip_if_missing=True 时，命令不存在应返回 False."""
     spec = TaskSpec("test", cmd=["definitely_not_installed_app_xyz"], skip_if_missing=True)
-    assert spec.should_execute() is False
+    assert spec.should_execute({})[0] is False
 
 
 def test_skip_if_missing_false_with_missing_command():
     """skip_if_missing=False 时，命令不存在也应返回 True（不检查）."""
     spec = TaskSpec("test", cmd=["definitely_not_installed_app_xyz"], skip_if_missing=False)
-    assert spec.should_execute() is True
+    assert spec.should_execute({})[0] is True
 
 
 def test_skip_if_missing_with_shell_cmd_not_checked():
     """skip_if_missing=True 时，shell 命令（str）不检查，应返回 True."""
     spec = TaskSpec("test", cmd="definitely_not_installed_app_xyz", skip_if_missing=True)
-    assert spec.should_execute() is True
+    assert spec.should_execute({})[0] is True
 
 
 def test_skip_if_missing_with_callable_cmd_not_checked():
@@ -248,7 +251,7 @@ def test_skip_if_missing_with_callable_cmd_not_checked():
         return 0
 
     spec = TaskSpec("test", cmd=custom_cmd, skip_if_missing=True)
-    assert spec.should_execute() is True
+    assert spec.should_execute({})[0] is True
 
 
 def test_skip_if_missing_with_fn_not_checked():
@@ -258,7 +261,7 @@ def test_skip_if_missing_with_fn_not_checked():
         return 0
 
     spec = TaskSpec("test", fn=my_fn, skip_if_missing=True)
-    assert spec.should_execute() is True
+    assert spec.should_execute({})[0] is True
 
 
 def test_skip_if_missing_with_empty_cmd_list():
@@ -266,37 +269,39 @@ def test_skip_if_missing_with_empty_cmd_list():
     spec = TaskSpec("test", cmd=[""], skip_if_missing=True)
     # 空字符串命令，shutil.which 返回 None
     # 但 cmd[0] 是空字符串，shutil.which("") 返回 None
-    assert spec.should_execute() is False
+    assert spec.should_execute({})[0] is False
 
 
 def test_skip_if_missing_combined_with_conditions():
     """skip_if_missing=True 与 conditions 组合使用."""
+    import sys
+
     # conditions 返回 False，应跳过
     spec = TaskSpec(
         "test",
-        cmd=["python", "--version"],
+        cmd=[sys.executable, "--version"],
         skip_if_missing=True,
-        conditions=(lambda: False,),
+        conditions=(lambda _ctx: False,),
     )
-    assert spec.should_execute() is False
+    assert spec.should_execute({})[0] is False
 
     # conditions 返回 True，命令存在，应执行
     spec = TaskSpec(
         "test",
-        cmd=["python", "--version"],
+        cmd=[sys.executable, "--version"],
         skip_if_missing=True,
-        conditions=(lambda: True,),
+        conditions=(lambda _ctx: True,),
     )
-    assert spec.should_execute() is True
+    assert spec.should_execute({})[0] is True
 
     # conditions 返回 True，命令不存在，应跳过
     spec = TaskSpec(
         "test",
         cmd=["definitely_not_installed_app_xyz"],
         skip_if_missing=True,
-        conditions=(lambda: True,),
+        conditions=(lambda _ctx: True,),
     )
-    assert spec.should_execute() is False
+    assert spec.should_execute({})[0] is False
 
 
 def test_skip_if_missing_skips_task_in_run():

tests/test_taskspec_commands.py

@@ -52,7 +52,7 @@ def test_taskspec_with_conditions_skip():
     """测试条件不满足时任务被跳过."""
 
     # 创建一个永远不会满足的条件
-    def never_true():
+    def never_true(_ctx):
         return False
 
     graph = px.Graph.from_specs([
@@ -73,7 +73,7 @@ def test_taskspec_with_conditions_execute():
     """测试条件满足时任务正常执行."""
 
     # 创建一个总是满足的条件
-    def always_true():
+    def always_true(_ctx):
         return True
 
     graph = px.Graph.from_specs([
@@ -103,17 +103,17 @@ def test_platform_conditions():
         px.TaskSpec(
             "win_task",
             cmd=win_cmd,
-            conditions=(lambda: Constants.IS_WINDOWS,),
+            conditions=(lambda _ctx: Constants.IS_WINDOWS,),
         ),
         px.TaskSpec(
             "linux_task",
             cmd=posix_cmd,
-            conditions=(lambda: Constants.IS_LINUX,),
+            conditions=(lambda _ctx: Constants.IS_LINUX,),
         ),
         px.TaskSpec(
             "macos_task",
             cmd=posix_cmd,
-            conditions=(lambda: Constants.IS_MACOS,),
+            conditions=(lambda _ctx: Constants.IS_MACOS,),
         ),
     ])
 
@@ -137,17 +137,15 @@ def test_platform_conditions():
 
 def test_app_installed_conditions():
     """测试应用安装条件."""
-    # 测试 python 应该总是安装的
-    if sys.platform == "win32":
-        python_cmd = ["python", "--version"]
-    else:
-        python_cmd = ["python3", "--version"]
+    # 使用 sys.executable 保证可移植
+    python_cmd = [sys.executable, "--version"]
+    py_name = "python" if sys.platform == "win32" else "python3"
 
     graph = px.Graph.from_specs([
         px.TaskSpec(
             "python_check",
             cmd=python_cmd,
-            conditions=(BuiltinConditions.HAS_INSTALLED("python"),),
+            conditions=(BuiltinConditions.HAS_INSTALLED(py_name),),
         ),
     ])
 
@@ -162,18 +160,18 @@ def test_combined_conditions():
     """测试组合条件."""
     # AND 条件
     and_condition = BuiltinConditions.AND(
-        lambda: True,
-        lambda: True,
+        lambda _ctx: True,
+        lambda _ctx: True,
     )
 
     # OR 条件
     or_condition = BuiltinConditions.OR(
-        lambda: True,
-        lambda: False,
+        lambda _ctx: True,
+        lambda _ctx: False,
     )
 
     # NOT 条件
-    not_condition = BuiltinConditions.NOT(lambda: False)
+    not_condition = BuiltinConditions.NOT(lambda _ctx: False)
 
     graph = px.Graph.from_specs([
         px.TaskSpec(
@@ -228,7 +226,7 @@ def test_taskspec_with_timeout():
         # 短时间任务应该成功
         px.TaskSpec(
             "short_task",
-            cmd=["python", "-c", "import time; time.sleep(0.1)"],
+            cmd=[sys.executable, "-c", "import time; time.sleep(0.1)"],
             timeout=1.0,
         ),
     ])
@@ -245,13 +243,13 @@ def test_taskspec_dependency_with_conditions():
         px.TaskSpec(
             "first",
             cmd=[*ECHO_CMD, "first"],
-            conditions=(lambda: True,),
+            conditions=(lambda _ctx: True,),
         ),
         px.TaskSpec(
             "second",
             cmd=[*ECHO_CMD, "second"],
             depends_on=("first",),
-            conditions=(lambda: True,),
+            conditions=(lambda _ctx: True,),
         ),
         px.TaskSpec(
             "third",
@@ -378,7 +376,7 @@ class TestTaskSpecVerbose:
         graph = px.Graph.from_specs([
             px.TaskSpec(
                 "fail",
-                cmd=["python", "-c", "import sys; sys.exit(1)"],
+                cmd=[sys.executable, "-c", "import sys; sys.exit(1)"],
                 verbose=True,
             )
         ])
@@ -414,7 +412,7 @@ class TestTaskSpecCmdErrors:
             px.TaskSpec(
                 "fail",
                 cmd=[
-                    "python",
+                    sys.executable,
                     "-c",
                     "import sys; sys.stderr.write('error-msg'); sys.exit(1)",
                 ],
@@ -437,7 +435,9 @@ class TestTaskSpecCmdErrors:
         """shell 命令失败时应抛出 RuntimeError."""
         from pyflowx.errors import TaskFailedError
 
-        graph = px.Graph.from_specs([px.TaskSpec("fail", cmd='python -c "import sys; sys.exit(1)"')])
+        graph = px.Graph.from_specs([
+            px.TaskSpec("fail", cmd=f'{sys.executable} -c "import sys; sys.exit(1)"'),
+        ])
         with pytest.raises(TaskFailedError) as exc_info:
             _ = px.run(graph, strategy="sequential")
         assert "Shell 命令执行失败" in str(exc_info.value.cause)
@@ -450,7 +450,7 @@ class TestTaskSpecCmdErrors:
         graph = px.Graph.from_specs([
             px.TaskSpec(
                 "slow",
-                cmd=["python", "-c", "import time; time.sleep(5)"],
+                cmd=[sys.executable, "-c", "import time; time.sleep(5)"],
                 timeout=0.1,
             )
         ])
@@ -463,7 +463,13 @@ class TestTaskSpecCmdErrors:
         """shell 命令超时应抛出 RuntimeError."""
         from pyflowx.errors import TaskFailedError
 
-        graph = px.Graph.from_specs([px.TaskSpec("slow", cmd='python -c "import time; time.sleep(5)"', timeout=0.1)])
+        graph = px.Graph.from_specs([
+            px.TaskSpec(
+                "slow",
+                cmd=f'{sys.executable} -c "import time; time.sleep(5)"',
+                timeout=0.1,
+            ),
+        ])
         with pytest.raises(TaskFailedError) as exc_info:
             _ = px.run(graph, strategy="sequential")
         assert "超时" in str(exc_info.value.cause)