From 928ec8c37b75708fd68a96c9a496a763a1a6a102 Mon Sep 17 00:00:00 2001
From: iomgaa <iomgaaycz@gmail.com>
Date: Sat, 11 Jul 2026 12:04:34 -0400
Subject: [PATCH] feat(scripts): add batch tree build entry with smoke-test
 guide

---
 .env.example           |  3 +++
 scripts/build_trees.sh | 38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+)
 create mode 100755 scripts/build_trees.sh

diff --git a/.env.example b/.env.example
index a0d4906..bb48729 100644
--- a/.env.example
+++ b/.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
diff --git a/scripts/build_trees.sh b/scripts/build_trees.sh
new file mode 100755
index 0000000..6406a55
--- /dev/null
+++ b/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" \
+    "$@"