docs(designs): apply Codex review fixes to Spec-1/2/3

2026-07-11 07:54:48 -04:00
parent a5666b4f16
commit ef402c46a2
3 changed files with 48 additions and 7 deletions
@@ -47,9 +47,19 @@ graph LR

 熔断阈值按 repair_trees 惯例缩放：`max(cfg_threshold, api_concurrency * 2)`。

+**配置归属（D7 规则，Codex 审查补充）**：
+
+| 参数 | 归属 | 理由 |
+|------|------|------|
+| `api_concurrency` | 工程配置 `.env`（`TREE_BUILD_API_CONCURRENCY=16`） | 端点保护参数，少变、随部署环境定 |
+| `video_concurrency` | sh 脚本写死（默认 16）+ CLI 单次覆盖 | 单机吞吐参数，随硬件观测调整，不进科研 YAML（不会被实验扫动） |
+
 ### builder 改动（唯一的存量修改）

-`VideoTreeBuilder` 的内部 Semaphore 改为**可注入参数**（构造器可选传入外部 Semaphore；不传则自建，单视频调用行为零变化）。builder 内部协程链本就显式传递 Semaphore，改动面极小。
+两处（Codex 审查修正后）：
+
+1. **公开异步入口**：现有 `build()` 是同步壳（内部 `asyncio.run(self._build_async(...))`），在异步批量编排里调用会触发"事件循环嵌套"运行时错误。将 `_build_async` 提升为公开 `build_async()` 供批量工具调用；同步 `build()` 保留原样（内部改为调 `build_async`），单视频调用方零影响。
+2. **Semaphore 注入**：内部 Semaphore 改为构造器可选参数（不传则自建，行为零变化）。builder 内部协程链本就显式传递 Semaphore，改动面极小。

 ### 断点续跑