feat(tree): expose build_async and accept injected API semaphore

Core algorithms #1/#2/#3 unchanged: only entry wrapping and semaphore
source switch (injected vs self-built); build logic untouched.
- rename _build_async to public build_async (body unchanged)
- __init__ accepts keyword-only api_semaphore for cross-video sharing
- default path (no injection) is verbatim-equivalent to previous code

tests/unit/test_video_builder.py

@@ -14,6 +14,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 from pathlib import Path
 from typing import Any
@@ -997,3 +998,44 @@ class TestHelpers:
         long_name = "a" * 100 + ".mp4"
         stem = VideoTreeBuilder._source_stem(f"/path/{long_name}")
         assert len(stem) == 64
+
+
+# ── Semaphore 注入与异步入口（Spec-2）─────────────────────────
+
+
+class TestApiSemaphoreInjection:
+    """API Semaphore 注入与 build_async 公开入口。"""
+
+    def test_injected_semaphore_stored(
+        self,
+        mock_vlm: MockVLMProvider,
+        mock_llm: MockLLMProvider,
+        tree_config: TreeConfig,
+    ) -> None:
+        """构造器注入的 Semaphore 应被保存供 build_async 使用。"""
+        sem = asyncio.Semaphore(3)
+        builder = VideoTreeBuilder(
+            vlm=mock_vlm, llm=mock_llm, config=tree_config, api_semaphore=sem
+        )
+        assert builder._api_semaphore is sem
+
+    def test_default_no_injection(
+        self,
+        mock_vlm: MockVLMProvider,
+        mock_llm: MockLLMProvider,
+        tree_config: TreeConfig,
+    ) -> None:
+        """未注入时属性为 None（build_async 内部自建，单视频行为零变化）。"""
+        builder = VideoTreeBuilder(vlm=mock_vlm, llm=mock_llm, config=tree_config)
+        assert builder._api_semaphore is None
+
+    def test_build_async_is_public(
+        self,
+        mock_vlm: MockVLMProvider,
+        mock_llm: MockLLMProvider,
+        tree_config: TreeConfig,
+    ) -> None:
+        """build_async 必须是公开协程方法（供批量编排在事件循环内调用）。"""
+        builder = VideoTreeBuilder(vlm=mock_vlm, llm=mock_llm, config=tree_config)
+        assert hasattr(builder, "build_async")
+        assert asyncio.iscoroutinefunction(builder.build_async)