docs+devcontainer: 快速开始重排(在线可用/本地两步走/fork 保存进度),Codespaces 环境修复

- devcontainer: xlings 升至 v0.4.68;xlings install 加 -y(非交互环境不再挂起);
  postAttach 显式补 PATH;postCreate 预热 Provider,首次进入 checker 不再长时间无反馈
- README(en/zh/zh.hant): 本地流程拆为 安装 d2x 工具 -> 获取课程(d2x install / git clone 二选一)
  -> 开始练习;新增 fork 后用 git commit/push 保存练习进度的建议

Author: Sunrisepeak

.devcontainer/devcontainer.json

@@ -13,5 +13,5 @@
   },
   "remoteUser": "vscode",
   "postCreateCommand": "/bin/bash .devcontainer/postCreate.sh",
-  "postAttachCommand": "d2x checker"
+  "postAttachCommand": "/bin/bash -c 'export PATH=\"$HOME/.xlings/subos/current/bin:$PATH\"; d2x checker'"
 }

.devcontainer/postCreate.sh

@@ -1,18 +1,22 @@
-# postCreate.sh
 #!/usr/bin/env bash
+# Codespaces/devcontainer 初始化:安装 xlings,再按 .xlings.json 配置课程工具链(mcpp + d2x)
 set -euo pipefail
 
 sudo apt-get update
 sudo apt-get install -y ncurses-bin libtinfo6 libncursesw6 curl ca-certificates git
 
 if ! command -v xlings >/dev/null 2>&1; then
-  curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s -- v0.4.14
+  curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s "v0.4.68"
 fi
 
-echo "xlings installed"
-
-# source PATH so xlings/d2x are available in this shell
 export PATH="$HOME/.xlings/subos/current/bin:$PATH"
-[ -f "$HOME/.bashrc" ] && source "$HOME/.bashrc"
 
-xlings install
+xlings update
+xlings install -y
+
+# 预热 Provider:把首次构建(含工具链下载)放在环境准备阶段,
+# 避免首次进入 d2x checker 时长时间无反馈。
+mcpp run -q -p d2x/buildtools -- describe > /dev/null \
+  || echo "warning: provider warm-up failed; d2x checker will build it on first run"
+
+echo "d2mcpp environment ready"

README.md

@@ -37,12 +37,14 @@
 
 ### Interactive Code Practice (Online)
 
-> [**click the button below**](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=mcpp-community/d2mcpp) to automatically complete the configuration in the cloud and enter the practice code detection mode
+> [**click the button below**](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=mcpp-community/d2mcpp) — the cloud environment configures itself (a few minutes on first launch), then the exercise checker starts automatically
 
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=mcpp-community/d2mcpp)
 
 ### Interactive Code Practice (Local)
 
+**Step 1 - Install the d2x tool**
+
 <details>
   <summary>click to view xlings installation command</summary>
 
@@ -68,8 +70,28 @@ irm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_i
 
 ```bash
 xlings install d2x -y        # exercise framework CLI
-d2x install d2mcpp           # get the course, environment auto-configured
+```
+
+**Step 2 - Get the course (choose one)**
+
+```bash
+# Option A - one command: download the course, toolchain auto-configured
+d2x install d2mcpp
+cd d2mcpp
+```
+
+```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
+```
+
+> Tip: fork this repo and clone your fork — `git commit / push` keeps your practice progress in your own repository.
+
+**Step 3 - Start practicing**
+
+```bash
 d2x checker                  # practice loop: edit -> save -> auto-check -> advance
 d2x status                   # progress overview
 ```

README.zh.hant.md

@@ -37,12 +37,14 @@
 
 ### 線上程式碼練習
 
-> [**點擊下方按鈕**](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=mcpp-community/d2mcpp) 即可在雲端自動完成設定, 並進入練習程式碼偵測模式
+> [**點擊下方按鈕**](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=mcpp-community/d2mcpp) —— 雲端自動完成環境設定(首次啟動需幾分鐘), 隨後自動進入練習偵測模式
 
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=mcpp-community/d2mcpp)
 
 ### 建立本地練習環境
 
+**第一步 - 安裝 d2x 工具**
+
 <details>
   <summary>點選查看xlings安裝指令</summary>
 
@@ -68,9 +70,29 @@ irm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_i
 
 ```bash
 xlings install d2x -y        # 練習框架 CLI
-d2x install d2mcpp           # 一鍵獲取課程,環境自動配置
+```
+
+**第二步 - 獲取課程(二選一)**
+
+```bash
+# 方式 A - 一鍵安裝: 下載課程,環境自動配置
+d2x install d2mcpp
+cd d2mcpp
+```
+
+```bash
+# 方式 B - git clone 原始碼
+git clone https://github.com/mcpp-community/d2mcpp.git   # 或你 fork 後的倉庫
 cd d2mcpp
-d2x checker                  # 練習循環: 編輯 -> 保存 -> 自動檢測 -> 推進
+xlings install -y            # 按 .xlings.json 安裝固定版本工具鏈
+```
+
+> 建議: 先 fork 本倉庫再 clone 自己的 fork —— 通過 `git commit / push` 把練習進度保存到自己的倉庫裡。
+
+**第三步 - 開始練習**
+
+```bash
+d2x checker                  # 練習循環: 編輯 -> 保存 -> 自動偵測 -> 推進
 d2x status                   # 進度總覽
 ```
 

README.zh.md

@@ -33,15 +33,17 @@
 
 ## 快速开始
 
+> 尝试 `Code -> Book -> Video -> X -> Code`
+
 ### 在线代码练习
 
-> [**点击下面按钮**](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=mcpp-community/d2mcpp) 即可在云端自动完成配置, 并进入练习代码检测模式
+> [**点击下面按钮**](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=mcpp-community/d2mcpp) —— 云端自动完成环境配置(首次启动需几分钟), 随后自动进入练习检测模式
 
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=mcpp-community/d2mcpp)
 
 ### 搭建本地练习环境
 
-> 尝试 `Code -> Book -> Video -> X -> Code`
+**第一步 - 安装 d2x 工具**
 
 <details>
   <summary>点击查看xlings安装命令</summary>
@@ -68,8 +70,28 @@ irm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_i
 
 ```bash
 xlings install d2x -y        # 练习框架 CLI
-d2x install d2mcpp           # 一键获取课程,环境自动配置
+```
+
+**第二步 - 获取课程(二选一)**
+
+```bash
+# 方式 A - 一键安装: 下载课程,环境自动配置
+d2x install d2mcpp
+cd d2mcpp
+```
+
+```bash
+# 方式 B - git clone 源码
+git clone https://github.com/mcpp-community/d2mcpp.git   # 或你 fork 后的仓库
 cd d2mcpp
+xlings install -y            # 按 .xlings.json 安装固定版本工具链
+```
+
+> 建议: 先 fork 本仓库再 clone 自己的 fork —— 通过 `git commit / push` 把练习进度保存到自己的仓库里。
+
+**第三步 - 开始练习**
+
+```bash
 d2x checker                  # 练习循环: 编辑 -> 保存 -> 自动检测 -> 推进
 d2x status                   # 进度总览
 ```