Graph —— DAG 构建
=================

``Graph`` 管理任务集合，提供建构建、校验、分层、可视化能力。

构建方式
--------

.. code-block:: python

   # 图级默认值：TaskSpec 字段为 None 时回退
   defaults = px.GraphDefaults(retry=px.RetryPolicy(max_attempts=2), timeout=60.0)

   graph = px.Graph.from_specs([...], defaults=defaults)  # 整批校验（推荐）

   # 或增量构建
   graph = px.Graph(defaults=defaults)
   graph.add(px.TaskSpec("a", fn_a))
   graph.add(px.TaskSpec("b", fn_b, ("a",)))

常用方法
--------

.. code-block:: python

   graph.validate()                    # 显式校验（环检测）
   graph.layers()                      # 拓扑分层（Kahn 算法）
   graph.to_mermaid()                  # Mermaid 可视化
   graph.describe()                    # 人类可读摘要
   graph.subgraph(("api",))            # 按标签切片
   graph.subgraph_by_names(("a", "b")) # 按名称切片
   graph.map("fetch", [1, 2, 3], lambda i: TaskSpec(f"fetch_{i}", ...))  # 批量 fan-out

图组合
------

``compose`` / ``GraphComposer`` 把带字符串引用的多个图展开为纯 ``Graph``：

.. code-block:: python

   graphs = {
       "build": px.Graph.from_specs([px.TaskSpec("b", cmd=["echo", "b"])]),
       "all": px.Graph.from_specs(["build", px.TaskSpec("t", cmd=["echo", "t"])]),
   }
   resolved = px.compose(graphs)  # "all" 图中的 "build" 引用被展开

引用格式：``"command_name"``（整个图）或 ``"command_name.task_name"``（特定任务）。
``CliRunner`` 内部自动调用 ``compose``。

完整方法说明详见 :doc:`/api`。