docs+ci: 本地上手三步走 + 平台矩阵拆分(linux/macos/win10/win11/win 无 MSVC STL)

README(三语 + book 两语)重写「本地练习环境」段,改成明确的三步:

  1. 装工具 —— `xlings install d2x mcpp -y`,两个工具名都链到各自仓库
  2. 取课程并验证环境 —— 默认 `d2x install d2mcpp` → `cd d2mcpp` → `mcpp test`;
     clone 源码那条路收进 <details>,作为可选项而不是与默认路径并列的「二选一」
  3. 开始练习 —— `d2x checker` / `d2x status`

第 2 步把 `mcpp test` 摆到台面上是有意的:练习就是测试,新环境跑一遍
「全部不通过」既是练习的起点,也已经证明工具链是通的。

CI 从单个 ubuntu job 拆成五档平台矩阵,每档都跑完整两层验证:

  linux / macos / windows-10 线(windows-2022)/ windows-11 线(windows-2025)
  / windows 且无 MSVC STL

最后一档把 runner 上的 Visual Studio 藏掉(改名 vswhere.exe 与 VC 目录 +
清空 VS* 环境变量,并就地检查后置条件),模拟学习者的干净 Windows —— 这
才是多数人的机器。mcpp 应当自动回落到自带的 winlibs MinGW,产物 target
目录名(x86_64-windows-gnu)就是断言依据。

两层验证:
  - `mcpp test`(已有 e2e.sh)—— pristine 全不过 + 覆盖答案后全过
  - `d2x checker`(新增 checker-e2e.sh)—— 答案就位后 checker 必须自己走完
    52 道题并退 0

加第二层是因为 checker 在 mcpp test 之上还叠了 Provider 的 NDJSON 协议、
进度持久化、文件监听三层;这三层断掉时 mcpp test 照样全绿,Windows 上就
出过这种静默回归(#87)。checker-e2e.sh 的看门狗自己用 shell 轮询实现,
不依赖 timeout(1)(macOS 默认没有)。

顺带:
- .xlings.json pin 上抬 —— mcpp 2026.8.1.1 → 2026.8.2.1(裸 Windows 自动
  回落 MinGW 是这个版本才有的能力,无 MSVC STL 那一档依赖它),
  d2x 2026.08.02.1 → 2026.08.02.2
- 修复文件名核对 job:它还在按迁移前的布局找 `intro/tests cpp*/tests`,
  练习早已搬进 src/,于是一个文件都没扫到、永远绿。现在真的核对 52 对。
- 工作流触发路径补上 .xlings.json

本地已验:e2e.sh all(zh/en 各 52/52)、checker-e2e.sh zh 与 en 均全过。

Author: Sunrisepeak

.github/workflows/dslings-ref-ci.yml

@@ -7,12 +7,25 @@ name: Validate exercises and reference solutions
 # 练习即测试：e2e 走 `mcpp test`，与 `d2x checker` 内部的 Provider 是同一条
 # 链路，所以 CI 绿灯等价于学习者本地能跑通，而不是另一条平行的构建路径。
 #
+# 两层都要验，因为它们的失效方式不同：
+#   - `mcpp test`   —— 编译/运行这一层(e2e.sh)
+#   - `d2x checker` —— 在它之上还叠了 Provider 的 NDJSON 协议、进度持久化、
+#                      文件监听三层(checker-e2e.sh)。这三层断掉时 mcpp test
+#                      照样全绿，Windows 上就出过这样的静默回归(d2mcpp#87)。
+#
+# 平台矩阵拆成五档，因为它们各有各的踩法，合成一个 ubuntu job 等于没测：
+#   linux / macos / windows-10 线 / windows-11 线 / windows 且无 MSVC STL
+# 最后一档见下方 mask_msvc 的注释。
+#
 # 依赖 mcpp >= 0.0.104(测试能力批次:逐测试隔离 / 过滤 / --list / --timeout /
 # --message-format json / tests 吃 [build].flags)。
 #
-# 但真正的下限已被上游抬高:mcpplibs 依赖索引现在要求 mcpp >= 0.0.109,更低的
-# 版本一律 E0006「index requires mcpp >= 0.0.109」而拒绝解析依赖 —— 原先钉的
-# 0.0.104 自此装不出来。pin 见 .xlings.json,当前为 2026.8.1.1。
+# 但真正的下限已被上游抬高两次:
+#   - mcpplibs 依赖索引要求 mcpp >= 0.0.109,更低版本一律 E0006 拒绝解析依赖
+#   - 「无 MSVC STL 的 Windows」这一档要求 mcpp >= 2026.8.2.1:自动回落到
+#     winlibs MinGW(x86_64-windows-gnu)是那个版本才有的能力,再早的版本在
+#     裸 Windows 上直接硬失败
+# pin 见 .xlings.json,当前为 2026.8.2.1。
 
 on:
   push:
@@ -23,6 +36,7 @@ on:
       - "d2x/**"
       - "mcpp.toml"
       - ".d2x.json"
+      - ".xlings.json"
       - ".github/workflows/dslings-ref-ci.yml"
   pull_request:
     paths:
@@ -31,52 +45,172 @@ on:
       - "d2x/**"
       - "mcpp.toml"
       - ".d2x.json"
+      - ".xlings.json"
       - ".github/workflows/dslings-ref-ci.yml"
   workflow_dispatch:
 
+env:
+  XLINGS_VERSION: "0.4.51"
+  XLINGS_NON_INTERACTIVE: "1"
+
 jobs:
   validate-exercises:
-    runs-on: ubuntu-latest
+    name: validate (${{ matrix.name }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 120
 
-    env:
-      XLINGS_VERSION: "0.4.51"
-      XLINGS_NON_INTERACTIVE: "1"
+    # GitHub 不提供 Windows 客户端版的 x64 托管 runner,只有 Server 镜像;这里
+    # 用与各自客户端版共享内核基线的 Server 镜像代表两条产品线:
+    #   windows-2022 = Server 2022,与 Windows 10 22H2 同基线(10.0.20348)
+    #   windows-2025 = Server 2025,与 Windows 11 24H2 同基线(10.0.26100)
+    # 这是托管 runner 上能覆盖到的最接近真实 Win10/Win11 的组合。
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: linux
+            os: ubuntu-latest
+            langs: all          # zh + en 两套课程都验
+          - name: macos
+            os: macos-14
+            langs: zh
+          - name: windows-10 baseline
+            os: windows-2022
+            langs: zh
+          - name: windows-11 baseline
+            os: windows-2025
+            langs: zh
+          # 学习者的机器上装了 Visual Studio 才是少数情况。这一档把 VS 从
+          # runner 上藏掉，验证「一台干净的 Windows」同样能跑完整门课 ——
+          # mcpp 会自动回落到自带的 winlibs MinGW(x86_64-windows-gnu)。
+          - name: windows-11, no MSVC STL
+            os: windows-2025
+            langs: zh
+            mask_msvc: true
+
+    defaults:
+      run:
+        shell: bash
 
     steps:
       - uses: actions/checkout@v4
 
+      # 必须排在装工具链之前:此后的任何一步都不该看见 Visual Studio。
+      - name: Mask Visual Studio (simulate a bare Windows box)
+        if: matrix.mask_msvc
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Continue'
+
+          # mcpp 的三条 MSVC 发现路径(vswhere / 环境变量 / 已知路径扫描)最终
+          # 都落到 <vsRoot>\VC\Tools\MSVC，所以藏的是 VC 目录而不是 VS 根目录：
+          # 根目录在 runner 上被进程占着改不了名，低一层的 VC 可以。
+          $vswhere = "C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe"
+          if (Test-Path $vswhere) { Rename-Item $vswhere "vswhere.exe.masked" }
+
+          Resolve-Path "C:\Program Files*\Microsoft Visual Studio\*\*\VC" `
+              -ErrorAction SilentlyContinue | ForEach-Object {
+            $p = $_.Path
+            Write-Host "masking $p"
+            try { Rename-Item -LiteralPath $p -NewName "VC.masked" -ErrorAction Stop }
+            catch { Write-Host "  rename failed: $($_.Exception.Message)" }
+          }
+
+          foreach ($v in @('VSINSTALLDIR','VCINSTALLDIR','VCToolsInstallDir',
+                           'VS170COMNTOOLS','VS160COMNTOOLS','VS150COMNTOOLS')) {
+            "$v=" | Out-File -Append -FilePath $env:GITHUB_ENV -Encoding utf8
+          }
+
+          # 就地检查遮蔽的后置条件。漏遮的后果是这一档静悄悄变成第二个
+          # windows-11 baseline —— 绿灯，但什么都没验到。
+          $left = Get-ChildItem "C:\Program Files*\Microsoft Visual Studio\*\*\VC\Tools\MSVC" `
+              -Directory -ErrorAction SilentlyContinue
+          if ($left) {
+            Write-Host "FAIL: VC tools still present after masking:"
+            $left | ForEach-Object { Write-Host "  $($_.FullName)" }
+            exit 1
+          }
+          Write-Host "Visual Studio masked: no VC\Tools\MSVC remains."
+
       # 官方一键安装脚本自带镜像回退。手动 curl GitHub release 包会被
       # release CDN 的间歇性 504 打断。
-      - name: Install xlings ${{ env.XLINGS_VERSION }}
+      - name: Install xlings ${{ env.XLINGS_VERSION }} (Linux/macOS)
+        if: runner.os != 'Windows'
         run: |
           set -eu
           curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh \
             | bash -s "v${XLINGS_VERSION}"
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
 
-      # 按 .xlings.json 安装 mcpp。mcpp 自带工具链沙箱，无需另装 gcc。
-      - name: Install mcpp
+      - name: Install xlings (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          irm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.ps1 | iex
+          "$env:USERPROFILE\.xlings\subos\current\bin" | Out-File -Append -FilePath $env:GITHUB_PATH -Encoding utf8
+
+      # 按 .xlings.json 安装 mcpp + d2x。mcpp 自带工具链沙箱,无需另装 gcc。
+      - name: Install pinned toolchain (.xlings.json)
         run: |
           set -eu
           xlings update
           xlings install -y
+          mcpp --version
+          d2x --version
+
+      - name: Report runner OS
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $os = Get-CimInstance Win32_OperatingSystem
+          Write-Host "runner=${{ matrix.os }}  caption=$($os.Caption)  build=$($os.Version)"
 
       - name: Build d2x Provider
         run: mcpp build -p d2x/buildtools
 
-      - name: Validate exercises and solutions (zh + en)
-        run: bash d2x/buildtools/tests/e2e.sh all
+      # mcpp 把产物按 target triple 分目录，所以目录名就是「实际用了哪条
+      # 工具链」最直接的证据。遮蔽生效时它必须是 gnu 而不是 msvc。
+      - name: Assert MinGW fallback took effect (no MSVC STL)
+        if: matrix.mask_msvc
+        run: |
+          set -eu
+          ls d2x/buildtools/target/
+          if [ ! -d d2x/buildtools/target/x86_64-windows-gnu ]; then
+            echo "FAIL: 期望回落到 x86_64-windows-gnu，实际产物 target 目录如上"
+            exit 1
+          fi
+          echo "OK: 无 MSVC STL 时回落到 winlibs MinGW (x86_64-windows-gnu)"
+
+      # 第一层:`mcpp test` —— pristine 全部不通过 + 覆盖答案后全部通过
+      - name: mcpp test (pristine fails, solutions all pass)
+        run: bash d2x/buildtools/tests/e2e.sh ${{ matrix.langs }}
+
+      # 第二层:`d2x checker` —— 答案就位后 checker 必须自己走完全程并退 0
+      - name: d2x checker (solutions drive it to completion)
+        run: bash d2x/buildtools/tests/checker-e2e.sh zh
+
+      - name: d2x checker — en course
+        if: matrix.langs == 'all'
+        run: bash d2x/buildtools/tests/checker-e2e.sh en
+
+  # 纯文件名核对，与工具链无关，跑一个平台就够。
+  solutions-parity:
+    name: exercises ↔ solutions filename parity
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
 
       - name: Verify exercises ↔ solutions filename parity
         run: |
           set -eu
           # en/ 镜像跳过 —— 参考答案与语言无关，两边共用同一份
           missing=0
-          for f in $(find intro/tests cpp*/tests -name '*.cpp'); do
-            std="${f%%/*}"
-            rel="${f#*/tests/}"
-            if [ ! -f "solutions/$std/$rel" ]; then
-              echo "::warning::missing solutions/$std/$rel (paired with $f)"
+          for f in $(find src/intro/tests src/cpp*/tests -name '*.cpp'); do
+            rel="${f#src/}"
+            std="${rel%%/*}"
+            rest="${rel#*/tests/}"
+            if [ ! -f "solutions/$std/$rest" ]; then
+              echo "::warning::missing solutions/$std/$rest (paired with $f)"
               missing=$((missing+1))
             fi
           done

.xlings.json

@@ -1,12 +1,12 @@
 {
   "workspace": {
-    "d2x": "2026.08.02.1",
+    "d2x": "2026.08.02.2",
     "mdbook": "0.4.43",
     "code": "",
     "mcpp": {
-      "linux": "2026.8.1.1",
-      "macosx": "2026.8.1.1",
-      "windows": "2026.8.1.1"
+      "linux": "2026.8.2.1",
+      "macosx": "2026.8.2.1",
+      "windows": "2026.8.2.1"
     }
   }
 }

README.md

@@ -43,7 +43,7 @@
 
 ### Interactive Code Practice (Local)
 
-**Step 1 - Install the d2x tool**
+**Step 1 - Install the [d2x](https://github.com/d2learn/d2x) and [mcpp](https://github.com/mcpp-community/mcpp) tools**
 
 <details>
   <summary>click to view xlings installation command</summary>
@@ -69,34 +69,48 @@ irm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_i
 </details>
 
 ```bash
-xlings install d2x -y        # exercise framework CLI
+xlings install d2x mcpp -y   # d2x: exercise framework CLI | mcpp: C++ build & test tool
 ```
 
-**Step 2 - Get the course (choose one)**
+**Step 2 - Get the course, then configure and verify the environment**
 
 ```bash
-# Option A - one command: download the course, toolchain auto-configured
-d2x install d2mcpp
+d2x install d2mcpp           # download the course, toolchain auto-configured
 cd d2mcpp
+mcpp test                    # verify the environment: every exercise compiles and runs
 ```
 
+> The exercises **are** the tests. On a fresh checkout `mcpp test` reports them all as
+> failing — that is the expected starting point, and it already proves your toolchain
+> works. Drop the reference answers from `solutions/` in and the very same command goes
+> all green.
+
+<details>
+  <summary>optional - start from the git source instead</summary>
+
+---
+
 ```bash
-# Option B - git clone the source
 git clone https://github.com/mcpp-community/d2mcpp.git   # or your fork
 cd d2mcpp
 xlings install -y            # toolchain pinned by .xlings.json
+mcpp test                    # same environment check
 ```
 
 > Tip: fork this repo and clone your fork — `git commit / push` keeps your practice progress in your own repository.
 
+---
+
+</details>
+
 **Step 3 - Start practicing**
 
 ```bash
 d2x checker                  # practice loop: edit -> save -> auto-check -> advance
 d2x status                   # progress overview
 ```
 
-> Exercises are real mcpp tests — `mcpp test -p src/cpp11` works too (no d2x involved).
+> Want to run a single chapter without d2x? `mcpp test -p src/cpp11` works too.
 
 **👉 [more details...](https://mcpp-community.github.io/d2mcpp/base/chapter_1.html)**
 

README.zh.hant.md

@@ -43,7 +43,7 @@
 
 ### 建立本地練習環境
 
-**第一步 - 安裝 d2x 工具**
+**第一步 - 安裝 [d2x](https://github.com/d2learn/d2x) 和 [mcpp](https://github.com/mcpp-community/mcpp) 工具**
 
 <details>
   <summary>點選查看xlings安裝指令</summary>
@@ -69,34 +69,46 @@ irm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_i
 </details>
 
 ```bash
-xlings install d2x -y        # 練習框架 CLI
+xlings install d2x mcpp -y   # d2x: 練習框架 CLI | mcpp: C++ 建置與測試工具
 ```
 
-**第二步 - 獲取課程(二選一)**
+**第二步 - 獲取課程, 並配置和驗證環境**
 
 ```bash
-# 方式 A - 一鍵安裝: 下載課程,環境自動配置
-d2x install d2mcpp
+d2x install d2mcpp           # 下載課程,環境自動配置
 cd d2mcpp
+mcpp test                    # 驗證環境: 每道練習都能編譯並執行
 ```
 
+> 練習**就是**測試。剛拿到課程時 `mcpp test` 會報告全部未通過 —— 這正是練習的起點,
+> 同時也說明工具鏈已經跑通了。把 `solutions/` 裡的參考答案覆蓋進去,同一條指令就會全綠。
+
+<details>
+  <summary>可選 - 改用 clone 專案原始碼的方式</summary>
+
+---
+
 ```bash
-# 方式 B - git clone 原始碼
 git clone https://github.com/mcpp-community/d2mcpp.git   # 或你 fork 後的倉庫
 cd d2mcpp
 xlings install -y            # 按 .xlings.json 安裝固定版本工具鏈
+mcpp test                    # 同樣的環境驗證
 ```
 
 > 建議: 先 fork 本倉庫再 clone 自己的 fork —— 通過 `git commit / push` 把練習進度保存到自己的倉庫裡。
 
+---
+
+</details>
+
 **第三步 - 開始練習**
 
 ```bash
 d2x checker                  # 練習循環: 編輯 -> 保存 -> 自動偵測 -> 推進
 d2x status                   # 進度總覽
 ```
 
-> 練習就是真實的 mcpp 測試 —— 不經過 d2x,直接 `mcpp test -p src/cpp11` 同樣可用。
+> 想單獨跑某一章而不經過 d2x? 直接 `mcpp test -p src/cpp11` 同樣可用。
 
 **👉 [更多細節...](https://mcpp-community.github.io/d2mcpp/base/chapter_1.html)**