本地工具路径DTU_*环境变量改造落地：10处调用点去硬编码+变量优先解析，本机全链路验证通过，文档同步收口，requirements补pre-commit

test/host/common/unit_test_harness.py

@@ -48,26 +48,49 @@ import tempfile
 from dataclasses import dataclass, field
 
 # ----------------------------- 工具链探测位置 -----------------------------
-# 顺序 = 优先级；`_first` 取每个根目录下最大的版本子目录（新版本优先）。
-VS_ROOTS = [
-    r"C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools",
-    r"C:\Program Files (x86)\Microsoft Visual Studio\2019\Community",
-    r"C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional",
-    r"C:\Program Files\Microsoft Visual Studio\2022\BuildTools",
-    r"C:\Program Files\Microsoft Visual Studio\2022\Community",
-    r"C:\Program Files\Microsoft Visual Studio\2022\Professional",
-    r"C:\Program Files\Microsoft Visual Studio\2022\Enterprise",
-    r"C:\Program Files\Microsoft Visual Studio\2026\BuildTools",
-    r"C:\Program Files\Microsoft Visual Studio\2026\Community",
-    # VS2026 的实际安装目录是 "18"（2026-10 台架实测：vswhere → ...\18\Community，
+# 显式覆盖（环境变量，见 docs/环境与部署/本地工具路径环境变量方案.md）：
+#   DTU_MSVC_CL           x64 Host cl.exe 完整路径（最高优先级；无效直接报错）
+#   DTU_WINDOWS_KITS_ROOT Windows Kits\10 根目录
+# 未设置时用标准布局自动探测：默认安装根由系统变量 %ProgramFiles% /
+# %ProgramFiles(x86)% 推导（不写死盘符）；`_first` 取每个根目录下最大的版本子目录。
+
+
+def _default_vs_roots():
+    """标准 VS 安装根（2019 -> Program Files (x86)；2022/2026 -> Program Files）。"""
+    pf = os.environ.get("ProgramFiles", r"C:\Program Files")
+    pf86 = os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")
+    roots = []
+    for year, base in (("2019", pf86), ("2022", pf), ("2026", pf)):
+        for edition in ("BuildTools", "Community", "Professional", "Enterprise"):
+            roots.append(os.path.join(base, "Microsoft Visual Studio", year, edition))
+    # VS2026 的实际安装目录名是 "18"（2026-10 台架实测：vswhere → ...\18\Community，
     # MSVC 14.51 + SDK 10.0.26100 布局与 2022 一致，cl.exe 路径模式不变）；
-    # 上面两条 "2026" 目录名在本机并不存在，保留以防将来布局回改
-    r"C:\Program Files\Microsoft Visual Studio\18\BuildTools",
-    r"C:\Program Files\Microsoft Visual Studio\18\Community",
-    r"C:\Program Files\Microsoft Visual Studio\18\Professional",
-    r"C:\Program Files\Microsoft Visual Studio\18\Enterprise",
-]
-SDK_ROOTS = [r"C:\Program Files (x86)\Windows Kits\10"]
+    # 上面 "2026" 目录名在本机并不存在，保留以防将来布局回改
+    for edition in ("BuildTools", "Community", "Professional", "Enterprise"):
+        roots.append(os.path.join(pf, "Microsoft Visual Studio", "18", edition))
+    return roots
+
+
+def _default_sdk_roots():
+    r"""Windows SDK 默认安装根（%ProgramFiles(x86)%\Windows Kits\10）。"""
+    pf86 = os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")
+    return [os.path.join(pf86, "Windows Kits", "10")]
+
+
+def _sdk_dirs(sdk):
+    """返回某 Windows Kits 根下的 (include 子目录列表, lib 子目录列表)。"""
+    sdk_inc = _first(os.path.join(sdk, r"Include\*"))
+    sdk_lib = _first(os.path.join(sdk, r"Lib\*"))
+    inc = []
+    if sdk_inc:
+        inc = [os.path.join(sdk_inc, "ucrt"),
+               os.path.join(sdk_inc, "shared"),
+               os.path.join(sdk_inc, "um")]
+    lib = []
+    if sdk_lib:
+        lib = [os.path.join(sdk_lib, "ucrt", "x64"),
+               os.path.join(sdk_lib, "um", "x64")]
+    return inc, lib
 
 # 编译开关（各模块共用；模块特有开关见 TestBuild.extra_flags）
 _BASE_FLAGS = [
@@ -127,13 +150,32 @@ def decode(b):
 
 
 def locate_toolchain():
-    """返回 (cl.exe, include_dirs, lib_dirs)；找不到返回 (None, [], [])。"""
-    cl = None
-    for vs in VS_ROOTS:
-        c = _first(os.path.join(vs, r"VC\Tools\MSVC\*\bin\Hostx64\x64\cl.exe"))
-        if c:
-            cl = c
-            break
+    """返回 (cl.exe, include_dirs, lib_dirs)；找不到返回 (None, [], [])。
+
+    优先级（见方案文档）：DTU_MSVC_CL / DTU_WINDOWS_KITS_ROOT（显式设置但
+    无效 → 立即报错，**不静默回退**自动探测）→ 标准布局自动探测
+    （_default_vs_roots / _default_sdk_roots）。
+    """
+    # ---- cl.exe ----
+    explicit_cl = os.environ.get("DTU_MSVC_CL", "").strip()
+    if explicit_cl:
+        if not os.path.isfile(explicit_cl):
+            print("[ENV] DTU_MSVC_CL 已设置但不存在: {}（请修正变量值，不做自动探测回退）"
+                  .format(explicit_cl), file=sys.stderr)
+            return None, [], []
+        tail = os.path.normpath(explicit_cl).lower()
+        if not tail.endswith(os.path.join("bin", "hostx64", "x64", "cl.exe")):
+            print("[ENV] DTU_MSVC_CL 必须是 x64 Host 编译器（路径以 bin\\Hostx64\\x64\\cl.exe 结尾）: {}"
+                  .format(explicit_cl), file=sys.stderr)
+            return None, [], []
+        cl = explicit_cl
+    else:
+        cl = None
+        for vs in _default_vs_roots():
+            c = _first(os.path.join(vs, r"VC\Tools\MSVC\*\bin\Hostx64\x64\cl.exe"))
+            if c:
+                cl = c
+                break
     if not cl:
         return None, [], []
 
@@ -143,20 +185,26 @@ def locate_toolchain():
     inc = [os.path.join(msvc_ver_dir, "include")]
     lib = [os.path.join(msvc_ver_dir, "lib", "x64")]
 
-    for sdk in SDK_ROOTS:
-        sdk_inc = _first(os.path.join(sdk, r"Include\*"))
-        sdk_lib = _first(os.path.join(sdk, r"Lib\*"))
-        if sdk_inc:
-            inc += [
-                os.path.join(sdk_inc, "ucrt"),
-                os.path.join(sdk_inc, "shared"),
-                os.path.join(sdk_inc, "um"),
-            ]
-        if sdk_lib:
-            lib += [
-                os.path.join(sdk_lib, "ucrt", "x64"),
-                os.path.join(sdk_lib, "um", "x64"),
-            ]
+    # ---- Windows SDK ----
+    explicit_sdk = os.environ.get("DTU_WINDOWS_KITS_ROOT", "").strip()
+    if explicit_sdk:
+        if not os.path.isdir(explicit_sdk):
+            print("[ENV] DTU_WINDOWS_KITS_ROOT 已设置但不存在: {}（请修正变量值，不做自动探测回退）"
+                  .format(explicit_sdk), file=sys.stderr)
+            return None, [], []
+        sdk_inc, sdk_lib = _sdk_dirs(explicit_sdk)
+        if not sdk_inc and not sdk_lib:
+            print("[ENV] DTU_WINDOWS_KITS_ROOT 下未找到 Include\\<ver> 或 Lib\\<ver>: {}".format(explicit_sdk),
+                  file=sys.stderr)
+            return None, [], []
+    else:
+        sdk_inc, sdk_lib = [], []
+        for sdk in _default_sdk_roots():
+            sdk_inc, sdk_lib = _sdk_dirs(sdk)
+            if sdk_inc or sdk_lib:
+                break
+    inc += sdk_inc
+    lib += sdk_lib
     return cl, inc, lib
 
 
@@ -168,7 +216,7 @@ def build_and_run(build, out=None):
 
     cl, inc, lib = locate_toolchain()
     if not cl:
-        print("[ENV] 找不到 MSVC cl.exe（需要 VS2019/2022/2026 的 C++ 工具链）", file=err)
+        print("[ENV] 找不到 MSVC cl.exe（设置 DTU_MSVC_CL，或安装 VS2019/2022/2026 的 C++ 工具链）", file=err)
         return 2
 
     tmp = tempfile.gettempdir()