docs/ENV_SETUP_Windows.md

@@ -1,106 +1,82 @@
 # Geopro 3.0 桌面客户端 — Windows 开发环境从零搭建指引
 
-适用：Windows 10 22H2 / Windows 11，64 位，MSVC 2022 工具链。
-目标：从一台干净的机器，搭到能 `cmake --build` 出可运行的 Qt6 + VTK9 桌面程序。
+适用：Windows 10 22H2 / Windows 11，64 位，**MSVC 2022（v143）工具链**。
+目标：从一台干净的机器，搭到 `build.bat app` 能编出可运行、且**不因 ABI 不匹配崩溃**的 Qt6 + VTK9 桌面程序。
 
-> 配套设计文档：`docs/superpowers/specs/2026-06-07-geopro-desktop-m1-design.md`
+> 最后核对：2026-07-01，已对齐 `CMakePresets.json` / `vcpkg.json` / 根 `CMakeLists.txt` / `build.bat` 的真实配置。
+> ⚠️ 若你手里有更早版本的本文档：**§6.1/§7/§9 曾残留「全 vcpkg（Qt/VTK 也走 vcpkg）」的旧方案，与现状矛盾——以本版为准。** 现状是「方案②-修订」：**官方预编译 Qt + 源码编 VTK + vcpkg 只管非 Qt 依赖**。
 
 ---
 
-## 0. 总览
+## 0. 总览（方案②-修订）
 
-> ⚠️ **构建方案已改定为「方案②-修订」**（经双专家评审 + 实机勘验）。本文档大部分步骤按此更新；**权威步骤以设计 §11 + `docs/superpowers/plans/2026-06-07-m1-phase0-spikes.md` 为准**。
->
-> **方案②-修订要点**：单一 Qt = **官方 MSVC 预编译 Qt**（`D:\Qt\6.11.1\msvc2022_64`）。**凡依赖 Qt 的组件(VTK/ADS/QtKeychain)都不走 vcpkg**（vcpkg 的 Qt 依赖端口会再编一份 qtbase = 双份冲突）：VTK 用官方 Qt 源码编到 install 前缀；ADS/QtKeychain 走 FetchContent；仅非 Qt 依赖(GDAL/PROJ/OpenSSL/Eigen/...)走 vcpkg。
-> **关键事实**：① 用户原装 `D:\Qt\6.11.1` 是 **MinGW 版**(MSVC 不可链)，须在 Qt 维护工具里补装 **MSVC 2022 64-bit** kit；② VTK 无 MSVC 预编译，三方案都必须源码编；③ 本机 VS18 = MSVC 14.51，链官方 Qt(v143)属"新链旧"，ABI 安全。
+**单一 Qt = 官方 MSVC 预编译 Qt**（`D:\Qt\6.11.1\msvc2022_64`）。**凡依赖 Qt 的组件都不走 vcpkg**（vcpkg 的 Qt 端口会再编一份 qtbase = 双份 Qt 冲突）：
 
-四块：① 编译器（VS18 / MSVC 14.51）② Git ③ vcpkg（仅非 Qt 依赖）④ 官方 MSVC Qt + 源码 VTK。
+| 组件 | 来源 | 备注 |
+|---|---|---|
+| Qt 6.11.1（Core/Gui/Widgets/Network/Sql/Concurrent/OpenGL + tools） | **官方 MSVC 2022 64-bit kit**（§4） | 路径由预设 `CMAKE_PREFIX_PATH` 指定 |
+| VTK 9.6.x（GUISupportQt/RenderingOpenGL2/RenderingFreeType/InteractionStyle/FiltersSources…） | **源码 Release 编 → `external/vtk-install`**（§5） | 必须对齐同一份 Qt + 同一工具集 + Release/`/MD` |
+| ADS（Qt-Advanced-Docking-System 4.3.1） | **FetchContent 自动**（配置时拉，对接官方 Qt） | 无需手动 |
+| QtKeychain v0.14.0 | **FetchContent 自动**（`BUILD_WITH_QT6`） | 无需手动 |
+| Qwt 6.2（二维科学图表） | **手工克隆到 `external/qwt-src`**（§5.3，gitignored） | 缺失则详情页图表功能不编入 |
+| vendored 3DGPRViewer（geopro_gpr3dv） | 仓库内 `external/gpr3dviewer`（随仓库） | 无需手动 |
+| 非 Qt 依赖：eigen3 / gdal / gtest / nlohmann-json / openssl / proj | **vcpkg manifest**（`vcpkg.json`，有 baseline 锁版本） | 配置时自动拉 |
+
+**ABI 铁律（否则运行时崩溃，见 §10）**：Qt(预编译 msvc2022) / VTK(你自己编) / app / 所有 FetchContent 组件，**必须同一工具集(v143)、同一运行时(`/MD`)、同一配置(全 Release)**。任何一处混 Debug/Release 或换工具集，`std::map`/`std::string` 跨界就崩。
 
 ---
 
-## 1. Visual Studio 2022（MSVC + CMake + Ninja）
+## 1. Visual Studio（MSVC v143 + CMake + Ninja）
 
-1. 安装 **Visual Studio 2022 Community**（或更高）。
-2. 勾选工作负载 **「使用 C++ 的桌面开发」(Desktop development with C++)**，确保包含：
+1. 安装 **Visual Studio 2022 Community**（或更高）。`build.bat` 也兼容 VS2026 preview，但**其工具集必须与预编译 Qt 的 msvc2022(v143) ABI 兼容**——若用 VS2026 的更新工具集，稳妥做法是**用同一工具集重编 VTK**（§5），别让 Qt(v143 预编译) 与 VTK/app(更新工具集) 混。
+2. 勾选工作负载 **「使用 C++ 的桌面开发」**，确保含：
    - MSVC v143 - VS 2022 C++ x64/x86 生成工具
    - Windows 11 SDK（或 Windows 10 SDK）
-   - C++ CMake tools for Windows（自带 CMake + Ninja）
-   - C++ AddressSanitizer（用于 Debug Sanitizer，规约 §10.2）
-3. 验证：开「x64 Native Tools Command Prompt for VS 2022」，运行：
-   ```
-   cl
-   cmake --version      # 应 ≥ 3.21
-   ninja --version
-   ```
+   - C++ CMake tools for Windows（自带 CMake ≥3.21 + Ninja）
+   - C++ AddressSanitizer（Debug Sanitizer 用）
+3. 验证（开「x64 Native Tools Command Prompt for VS」）：`cl` / `cmake --version`（≥3.21）/ `ninja --version`。
 
-> 之后所有 cmake/vcpkg 命令都在 **x64 Native Tools 命令行** 里跑（已设好 MSVC 环境变量）。
+> `build.bat` 会用 `vswhere` 自动定位 VS 并激活 MSVC 环境，所以**日常构建直接跑 `build.bat` 即可**，不必手动开 x64 命令行。但 `cmake/ninja/cl` **不在 PATH**，手动跑 cmake 前需先激活 vcvars64。
 
 ---
 
 ## 2. Git
 
-1. 安装 [Git for Windows](https://git-scm.com/download/win)。
-2. 验证：`git --version`。
-3. 本项目当前**尚未初始化 git 仓库**——首次提交前需 `git init`（见 §7）。
+1. 安装 [Git for Windows](https://git-scm.com/download/win)，`git --version` 验证。
+2. 本项目**已是 git 仓库**（无需 `git init`）；正常 `git clone` 即可。
 
 ---
 
-## 3. vcpkg（依赖管理）
+## 3. vcpkg（仅非 Qt 依赖）
 
 ```powershell
-# 选一个不含空格/中文的路径，例如 C:\dev
-git clone https://github.com/microsoft/vcpkg C:\dev\vcpkg
+git clone https://github.com/microsoft/vcpkg C:\dev\vcpkg   # 路径不含空格/中文
 C:\dev\vcpkg\bootstrap-vcpkg.bat
+setx VCPKG_ROOT "C:\dev\vcpkg"     # 永久；新开终端生效
 ```
-
-设环境变量（系统环境变量或当前会话）：
-```powershell
-$env:VCPKG_ROOT = "C:\dev\vcpkg"
-setx VCPKG_ROOT "C:\dev\vcpkg"     # 永久（新开终端生效）
-```
-
-> 本项目用 **vcpkg manifest 模式**（`vcpkg.json`），不需要手动 `vcpkg install`；CMake 配置时按清单自动拉取。
+- **manifest 模式**：根 `vcpkg.json` 声明依赖 + `builtin-baseline` 锁版本，CMake 配置时自动拉取，**无需手动 `vcpkg install`**。
+- 实际依赖（勿加 Qt/VTK 进来）：`eigen3, gdal, gtest, nlohmann-json, openssl, proj`。
+- **不要随意 `vcpkg x-update-baseline`**——baseline 已锁，改动会漂移依赖版本、可能引入 ABI 不一致。
+- 首次会编 GDAL/PROJ 等，较久；可选配 `VCPKG_BINARY_SOURCES` 二进制缓存加速。
 
 ---
 
-## 4. Qt（官方 MSVC 预编译 kit）
+## 4. Qt（官方 MSVC 2022 64-bit kit）
 
-**用官方安装器,但必须是 MSVC kit**(你原装的 `mingw_64` 在 MSVC 下不可用):
+**必须是 MSVC kit**——若你原装的是 `mingw_64`，MSVC 下不可链：
 
-1. `.\qt-online-installer-windows-x64-4.11.0.exe --mirror https://ftp.jaist.ac.jp/pub/qtproject`
-2. 打开 `D:\Qt\MaintenanceTool.exe` → Add or remove components → 登录 Qt 账号。
-3. 展开 Qt → Qt 6.11.1,勾选 **MSVC 2022 64-bit**,安装。
-4. 完成后存在 `D:\Qt\6.11.1\msvc2022_64\lib\cmake\Qt6`(供 `find_package(Qt6)`)。
+1. 用官方在线安装器（或已装则开 `D:\Qt\MaintenanceTool.exe`）→ Add or remove components → 登录 Qt 账号。
+2. 展开 Qt → **Qt 6.11.1**，勾选 **MSVC 2022 64-bit**，安装。
+3. 完成后应存在 `D:\Qt\6.11.1\msvc2022_64\lib\cmake\Qt6`。
+4. 预设通过 `CMAKE_PREFIX_PATH=D:/Qt/6.11.1/msvc2022_64` 找到它（§6）。**全链路只此一份 Qt。**
 
-CMake 经 `CMAKE_PREFIX_PATH=D:/Qt/6.11.1/msvc2022_64` 找到它(见 §6 预设)。**全链路只此一份 Qt**。
+> 若你的 Qt 装在别处/别的版本：**改预设/环境的 `CMAKE_PREFIX_PATH` 指向你的 `msvc2022_64`，但版本仍须是 6.11.1**（换版本可能与源码编的 VTK/ADS 不匹配）。
 
 ---
 
-## 5. 依赖来源（方案②-修订）
+## 5. 源码依赖（手工准备）
 
-| 类别 | 组件 | 来源 |
-|---|---|---|
-| Qt | qtbase/widgets/network/sql/concurrent/opengl + tools | 官方 MSVC kit(§4) |
-| VTK | vtk 9.3[qt,opengl]（+gdal/proj 可选） | **源码编 → install 前缀**(§5.2) |
-| Qt 依赖小件 | ADS、QtKeychain | **FetchContent 对接官方 Qt**(§6.2) |
-| 非 Qt 依赖 | gdal/proj/openssl/eigen3/spdlog/fmt/nlohmann-json/gtest | **vcpkg**(下方 vcpkg.json) |
-
-### 5.1 `vcpkg.json`（仅非 Qt 依赖）
-
-```json
-{
-  "name": "geopro-desktop",
-  "version": "0.1.0",
-  "dependencies": ["gdal","proj","eigen3","spdlog","fmt","nlohmann-json","openssl","gtest"]
-}
-```
-- **凡依赖 Qt 的(vtk[qt]/qtkeychain/qt-advanced-docking-system)绝不放进 vcpkg**——否则 vcpkg 会再编一份 qtbase = 双份 Qt 冲突(已核 `ports/vtk/vcpkg.json`)。
-- `vcpkg x-update-baseline --add-initial-baseline` 锁版本(规约 §5.4)。
-- 先配 `VCPKG_BINARY_SOURCES` 二进制缓存(实测当前为空),省 GDAL/PROJ 重编。
-
-### 5.2 VTK 源码编到 install 前缀（用官方 Qt）
-
-实机用 **VTK 9.6.2**(最新稳定,对 Qt 6.11 兼容最好),源码/构建全放 **D:**(C: 仅剩 ~1GB)。脚本见 `external/build_vtk.bat`(已 .gitignore),要点:
+### 5.1 VTK 9.6.x 源码编到 `external/vtk-install`（用官方 Qt，Release）
 
 ```bat
 call "<VS>\VC\Auxiliary\Build\vcvars64.bat"
@@ -114,18 +90,32 @@ cmake -S D:\dev\vtk-src -B D:\dev\vtk-build -G Ninja ^
   -D CMAKE_INSTALL_PREFIX=D:/Git/lanbingtech/geopro/external/vtk-install
 cmake --build D:\dev\vtk-build --target install
 ```
-完成后 `external/vtk-install/lib/cmake/vtk-9.6` 供 `find_package(VTK)`(已在 `CMakePresets.json` 设 `VTK_DIR`)。
-> 注:VTK 用 **Release** 编。因此**冒烟程序也用 `msvc-release` 预设构建**,以匹配 Release VTK + Release Qt(避免 `/MD` vs `/MDd` 混链)。需要 Debug 调试 VTK 时再出一份 Debug VTK。
+- 完成后 `external/vtk-install/lib/cmake/vtk-9.6` 供 `find_package(VTK)`（`CMakePresets.json` 里 `VTK_DIR` 已指向它）。
+- **必须 Release + 与本项目相同的工具集(v143)编**；因此**本项目也用 `msvc-release` 构建**，避免 `/MD` vs `/MDd` 或 Debug/Release 混链（→ §10 崩溃）。需要调试 VTK 时另出一份 Debug VTK，且此时 app 也须整套 Debug。
+- 根 `CMakeLists.txt` 里 `find_package(VTK REQUIRED COMPONENTS ...)` **必须列组件**（否则 `VTK_LIBRARIES` 为空、链不到）；当前组件：`GUISupportQt / RenderingOpenGL2 / RenderingFreeType / InteractionStyle / FiltersSources`（随渲染层增补）。
+
+### 5.2 ADS / QtKeychain（FetchContent，自动）
+
+无需手动——根 `CMakeLists.txt` 用 `FetchContent` 拉 **ADS 4.3.1** 与 **QtKeychain v0.14.0**，对接同一份官方 Qt（`BUILD_WITH_QT6=ON`）。首次配置会 clone，需能访问 GitHub。
+
+### 5.3 Qwt 6.2（手工克隆到 `external/qwt-src`）
+
+二维科学图表（数据集详情散点/等值线）依赖 Qwt。`external/qwt-src` 已 gitignore，须自备：
+
+```powershell
+# 克隆/解压 Qwt 6.2 源码到 external/qwt-src，使 external/qwt-src/src 存在
+git clone --branch qwt-6.2 https://git.code.sf.net/p/qwt/git external/qwt-src
+```
+- CMake 检测到 `external/qwt-src/src` 才 include `cmake/qwt.cmake` 编 Qwt；**缺失则相关图表功能不编入**（不报错，但详情图表缺失）。
 
 ---
 
-## 6. CMake 接线
+## 6. CMake 接线（现状，勿照旧文档）
 
-### 6.1 `CMakePresets.json`（项目根）
+### 6.1 `CMakePresets.json`（真实内容）
 
 ```json
 {
-  "version": 3,
   "configurePresets": [
     {
       "name": "msvc-debug",
@@ -134,112 +124,92 @@ cmake --build D:\dev\vtk-build --target install
       "cacheVariables": {
         "CMAKE_BUILD_TYPE": "Debug",
         "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
-        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
+        "VCPKG_TARGET_TRIPLET": "x64-windows",
+        "CMAKE_PREFIX_PATH": "D:/Qt/6.11.1/msvc2022_64",
+        "VTK_DIR": "${sourceDir}/external/vtk-install/lib/cmake/vtk-9.6"
       }
     },
-    {
-      "name": "msvc-release",
-      "inherits": "msvc-debug",
+    { "name": "msvc-release", "inherits": "msvc-debug",
       "binaryDir": "${sourceDir}/build/release",
-      "cacheVariables": { "CMAKE_BUILD_TYPE": "Release" }
-    }
+      "cacheVariables": { "CMAKE_BUILD_TYPE": "Release" } }
   ]
 }
 ```
-> 全 vcpkg 方案下**不设 `CMAKE_PREFIX_PATH` 指向官方 Qt**——vcpkg 工具链接管 Qt 查找（避免双 Qt）。
+- **预设确实设 `CMAKE_PREFIX_PATH`（官方 Qt）+ `VTK_DIR`（源码编的 VTK）**——这是「方案②-修订」的核心，别按旧文档去掉它。
+- vcpkg 只经 `CMAKE_TOOLCHAIN_FILE` 管非 Qt 依赖；triplet `x64-windows`。
 
-### 6.2 顶层 `CMakeLists.txt`（骨架）
+### 6.2 根 `CMakeLists.txt` 要点
 
-```cmake
-cmake_minimum_required(VERSION 3.21)
-project(geopro_desktop LANGUAGES CXX)
-set(CMAKE_CXX_STANDARD 17)
-set(CMAKE_CXX_STANDARD_REQUIRED ON)
-set(CMAKE_AUTOMOC ON)
-set(CMAKE_AUTORCC ON)
-set(CMAKE_AUTOUIC ON)
+- `find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets Network Sql Concurrent)`。
+- `find_package(VTK REQUIRED COMPONENTS GUISupportQt RenderingOpenGL2 RenderingFreeType InteractionStyle FiltersSources)`（**必须列组件**）。
+- MSVC flags：`/utf-8 /MP /W4 /permissive-`；非 Debug 配置产 PDB（`/Zi` + `/DEBUG` + `/OPT:REF,ICF`）。
+- ADS/QtKeychain 经 FetchContent；Qwt 经 `cmake/qwt.cmake`（存在才编）。
+- 视图层用 **`QVTKOpenGLStereoWidget`**（QOpenGLWidget 系，ADS reparent 友好）。
 
-find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets Network Sql Concurrent)
-find_package(VTK REQUIRED)            # 含 GUISupportQt（vtk[qt]）→ QVTKOpenGLStereoWidget
-find_package(GDAL CONFIG REQUIRED)
-find_package(PROJ CONFIG REQUIRED)
-find_package(Eigen3 CONFIG REQUIRED)
-find_package(spdlog CONFIG REQUIRED)
-find_package(nlohmann_json CONFIG REQUIRED)
-find_package(OpenSSL REQUIRED)
-# find_package(Qt6Keychain CONFIG REQUIRED)   # qtkeychain
-# ADS：vcpkg 端口验证通过后 find_package；否则用下方 FetchContent
+---
 
-add_subdirectory(src)
-enable_testing()
-add_subdirectory(tests)
+## 7. 首次配置、编译、运行、部署
+
+**日常直接用 `build.bat`（推荐）**：
 ```
-
-> VTK 链接用 `vtk_module_autoinit`；视图层用 **`QVTKOpenGLStereoWidget`**（QOpenGLWidget 系，ADS reparent 友好，见设计 §K-9），不用 native 版。
-
-> **ADS 备选引入**（若 vcpkg 端口不可用，spike 阶段确定）：
-> ```cmake
-> include(FetchContent)
-> FetchContent_Declare(ads GIT_REPOSITORY https://github.com/githubuser0xFFFF/Qt-Advanced-Docking-System.git GIT_TAG <tag>)
-> FetchContent_MakeAvailable(ads)
-> ```
-
----
-
-## 7. 首次配置、编译、运行
-
-```powershell
-# 在 x64 Native Tools 命令行、项目根目录
-git init                                   # 首次：初始化仓库
-vcpkg x-update-baseline --add-initial-baseline
-
-cmake --preset msvc-debug                  # 首次会编译 VTK 等，耗时较长
-cmake --build build/debug
-
-# 运行（VTK/Qt 的 dll 需在 PATH 或同目录）
-.\build\debug\src\app\geopro_desktop.exe
+build.bat app       # 配置(首次)+ 增量编 geopro_desktop（Release）
+build.bat test      # 编 + ctest 跑单测
+build.bat run       # 编 + 启动
+build.bat rebuild   # 强制 --clean-first 全量重编（增量疑似漏编时用）
+build.bat configure # CMakeLists 改动后强制重跑 configure
 ```
+- `build.bat` 固定 `--preset msvc-release`、`build/release`，自动激活 MSVC 环境。exe：`build/release/src/app/geopro_desktop.exe`。
+- 首次会拉 vcpkg 依赖 + FetchContent(ADS/QtKeychain)，较久；VTK/Qt/Qwt 须已按 §4/§5 就位。
 
-**运行期 DLL 部署（单一 vcpkg 链路）**：
-- 全部 dll（含 Qt）来自 vcpkg：`build/vcpkg_installed/x64-windows/(debug/)bin`。
-- 用 CMake `TARGET_RUNTIME_DLLS` + `add_custom_command(POST_BUILD)` 自动拷贝到 exe 目录（实现阶段加）。
-- **不混用官方 Qt 的 `windeployqt`**——本方案 Qt 来自 vcpkg，混用会拷错版本造成双 Qt 冲突。
-- Qt plugins（platforms/imageformats/sqldrivers 等）由 vcpkg 部署脚本处理；如缺再用 vcpkg 安装树里的 `windeployqt` 对齐同一份 Qt。
+**运行期 DLL 部署（官方 Qt，非 vcpkg）**：
+- Qt6*.dll + plugins：用**官方 Qt 的 `windeployqt`**（`D:\Qt\6.11.1\msvc2022_64\bin\windeployqt.exe`）对齐**同一份官方 Qt** 到 exe 目录。
+- VTK*.dll：从 `external/vtk-install/bin` 拷到 exe 目录（或加进 PATH）。
+- **只保证 exe 目录一份 Qt6*.dll（无双 Qt）**；勿混入别处/vcpkg 的 Qt。
 
 ---
 
-## 8. AI 编码上下文基础设施（规约 §10.1，强烈建议先建）
+## 8. AI/IDE 上下文（clangd）
 
-项目根放：
-
-- `.clang-format`：统一风格（基于 LLVM/Google + 团队微调）。
-- `.clangd`：
-  ```yaml
-  CompileFlags:
-    CompilationDatabase: build/debug
-  ```
-  使 clangd 读取 `compile_commands.json`，给 AI/IDE 精确类型上下文。
-- VS Code 装 **clangd** 扩展（禁用微软 C++ IntelliSense 避免冲突），或 CLion 直接用 CMake。
+- `.clangd`：`CompileFlags.CompilationDatabase: build/release`（对齐 `build.bat` 的主构建目录；若你主要用 Debug 则指 `build/debug`）。`CMAKE_EXPORT_COMPILE_COMMANDS=ON` 会在该目录产 `compile_commands.json`。
+- VS Code 用 **clangd** 扩展（禁用微软 C++ IntelliSense 避免冲突）。
 
 ---
 
-## 9. 验证清单
+## 9. 构建环境兼容性检查清单（交付/接手前逐项核对）
 
-- [ ] `cl` / `cmake` / `ninja` / `git` 命令可用
-- [ ] `VCPKG_ROOT` 已设
-- [ ] `vcpkg.json` 含 qtbase + vtk[qt]（共用一份 Qt），preset **未**指向官方 Qt
-- [ ] `cmake --preset msvc-debug` 成功（Qt+VTK 已拉取编译，首次较久）
-- [ ] `cmake --build` 出 exe
-- [ ] exe 能起一个空 Qt 窗 + 一个 `QVTKOpenGLStereoWidget` 渲染窗（冒烟测试）
-- [ ] 部署后 exe 目录只有一份 Qt6*.dll（无双 Qt）
-- [ ] `compile_commands.json` 生成，clangd 正常索引
+> 目的：把「配置错→运行时随机崩溃」变成「一眼可查」。**任何一项不满足都可能导致 §10 的 `std::map`/`std::string` ABI 崩溃。**
+
+### 9.1 前置就位
+- [ ] `cl` / `cmake`(≥3.21) / `ninja` / `git` 可用；`VCPKG_ROOT` 已设。
+- [ ] Qt **6.11.1** 的 **`msvc2022_64`**（MSVC，非 MinGW）存在于 `CMAKE_PREFIX_PATH` 指向处；`.../msvc2022_64/lib/cmake/Qt6` 在。
+- [ ] `external/vtk-install/lib/cmake/vtk-9.6` 存在（VTK 已源码编 install）。
+- [ ] `external/qwt-src/src` 存在（如需详情页图表）。
+- [ ] `vcpkg.json` 的 `builtin-baseline` 未被改动。
+
+### 9.2 ABI 一致性（最关键，防崩溃）
+- [ ] **单一配置**：Qt(预编译) / VTK(你编) / app / ADS / QtKeychain / Qwt **全 Release**（或全 Debug），**绝不混**。日常一律 `build.bat`（msvc-release）。
+- [ ] **同一工具集**：VTK/app 用的 MSVC 工具集与预编译 Qt 的 **v143(msvc2022)** ABI 兼容；若用 VS2026-preview 工具集，**用它重编 VTK**，别让 Qt(v143) 与 VTK/app(更新集) 混。
+- [ ] **同一运行时**：全部 `/MD`（Release 动态 CRT），`_ITERATOR_DEBUG_LEVEL=0`。**绝不把 Release 的 Qt/VTK 链进 Debug 的 app**（Debug 是 `/MDd` + IDL=2，STL 布局不同）。
+- [ ] **VTK 来源正确**：是**你按 §5.1 源码 Release 编、对齐本 Qt** 的那份；**不是** vcpkg 的 VTK、不是别处/别配置的 VTK。
+- [ ] **单一 Qt**：exe 目录/PATH 只有一份 Qt6*.dll，无双 Qt。
+
+### 9.3 干净构建验证
+- [ ] 删 `build/` 后 `build.bat app` 从零配置**无错**（尤其无「找不到 Qt6/VTK」「add_subdirectory 目录不存在」）。
+- [ ] `build.bat test` → ctest 全绿。
+- [ ] 启动 app、点对象树、渲染视图**不崩**（§10 的崩溃即出现在这里）。
 
 ---
 
-## 10. 与设计文档对应的 spike 门槛
+## 10. 已知崩溃签名 → 根因速查
 
-本指引服务于设计 §15 的第一周 spike：① 全 vcpkg 构建/部署打通（本文）；② ADS + `QVTKOpenGLStereoWidget` 浮动/重停靠不黑屏；③ 真实样本跑通 banded contour。三者通过再进入完整实现计划。
+| 现象 | 根因 | 处理 |
+|---|---|---|
+| **点对象树/渲染时，崩在 `std::_Tree::_Find_lower_bound`（`std::map`/`set` 查找），`_Myhead` 是 `0xFFFF...` 之类垃圾值，读取访问冲突** | **STL ABI 不匹配**：Debug/Release 混链、`/MD` vs `/MDd`、`_ITERATOR_DEBUG_LEVEL` 不一致、或工具集不匹配（最常见：**别处/别配置的 VTK/Qt**，或 **Debug app 链 Release 依赖**） | 按 §9.2 逐项核对；**删 `build/` 全 Release 干净重建**；确认 VTK 是 §5.1 那份 |
+| 链接期报「找不到 Qt6::/VTK::」 | 预设 `CMAKE_PREFIX_PATH`/`VTK_DIR` 指向不存在 | 按 §4/§5 就位或改预设路径 |
+| 配置报「add_subdirectory ... 不是已存在目录」 | 引用了未随仓库的目录（如误提交本地临时工具目录） | 从 `CMakeLists.txt` 去掉该引用，或补齐该目录 |
+| 详情页图表缺失但不报错 | `external/qwt-src` 未就位（§5.3） | 克隆 Qwt 后重配置 |
+| 双 Qt / 起不来找不到 platform 插件 | 混入了 vcpkg/别处的 Qt dll | 只用官方 `windeployqt` 对齐单一 Qt |
 
 ---
 
-*遇到具体报错（VTK/Qt/GDAL 链接、ADS 端口、双 Qt）按规约 §10.4 由工程师复核；AI 协助按 build-error-resolver 流程逐条解决。*
+*遇到具体报错按规约由工程师复核；AI 协助按 build-error-resolver 流程逐条解决。*