feat(scripts): add batch tree build entry with smoke-test guide

.env.example

@@ -47,3 +47,6 @@ LLM_TTFT_TIMEOUT=30
 LLM_INTER_TOKEN_TIMEOUT=15
 LLM_RETRY_MAX_DELAY=30.0
 REDIS_CACHE_TTL=86400
+
+# 建树批量并行：全局 VLM/LLM 在途调用上限（Spec-2 工程配置）
+TREE_BUILD_API_CONCURRENCY=16

scripts/build_trees.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# 批量并行建树（Spec-2）
+# 职责：对目录下所有视频并发构建三层 TreeIndex，断点续跑。
+#
+# 用法:
+#   bash scripts/build_trees.sh --videos-dir <dir>                 # 全量
+#   bash scripts/build_trees.sh --videos-dir <dir> --limit 2       # 真实视频烟测
+#   VIDEO_CONCURRENCY=8 bash scripts/build_trees.sh --videos-dir <dir>
+#
+# 真实视频烟测流程（首次使用时执行）:
+#   1. --limit 2 建两个视频，观察日志速率与 API 并发
+#   2. 中途 Ctrl+C 后重跑，确认已完成视频被跳过、未完成视频续跑
+#   3. 检查 store/videos/<vid>/tree.json 可被 TreeIndex.load_json 加载
+#
+# 日志输出:
+#   stderr → 终端实时显示
+#   logs/build_trees.log → 完整日志（自动 rotation 50MB）
+#   logs/build_trees_telemetry.db → LLM/VLM 调用遥测
+#   logs/build_progress.json → 断点续跑进度
+#
+# api_concurrency 走 .env 的 TREE_BUILD_API_CONCURRENCY（工程配置，默认 16）
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+VIDEO_CONCURRENCY="${VIDEO_CONCURRENCY:-16}"
+
+export PYTHONUNBUFFERED=1
+
+# shellcheck source=/dev/null
+source "$(conda info --base)/etc/profile.d/conda.sh"
+conda activate Video-Tree-TRM
+
+python tools/build_trees.py \
+    --out-dir store/videos \
+    --video-concurrency "$VIDEO_CONCURRENCY" \
+    "$@"