docs: 注释与教学文案专业化(消除口语化表达)

Author: Sunrisepeak

book/en/src/base/chapter_1.md

@@ -86,7 +86,7 @@ After entering the automated code practice environment using `d2x checker`, the
 // Exercise: Automated Code Practice Tutorial
 //
 // Tips:
-//    This is an "exercises are tests" automated practice project. Two ways to play:
+//    This is an "exercises are tests" automated practice project. Two modes of use:
 //
 //      d2x checker                  guided mode: auto-detects your edits, passing advances you
 //      mcpp test -p src/en/intro    native mode: plain mcpp — the test report IS your progress

book/src/base/chapter_1.md

@@ -86,10 +86,10 @@ d2x update
 // Exercise/练习: 自动化代码练习使用教学
 //
 // Tips/提示:
-//    这是一个「练习即测试」的自动化代码练习项目。两种玩法任选:
+//    这是一个「练习即测试」的自动化代码练习项目。两种使用方式任选:
 //
-//      d2x checker              闯关模式: 自动检测、通过即进入下一题
-//      mcpp test -p src/intro       原生模式: 直接用 mcpp 跑, 测试结果就是进度表
+//      d2x checker              引导模式: 自动检测,通过后进入下一题
+//      mcpp test -p src/intro       原生模式: 直接使用 mcpp 运行, 测试报告即学习进度
 //
 //    你需要根据控制台的报错和提示信息修改代码。约定只有三个:
 //

d2x/buildtools/src/discovery.cppm

@@ -33,7 +33,7 @@ export struct Exercise {
     fs::path    file;       // 绝对路径
 };
 
-// .d2x.json 里我们只关心 "lang"。写一个完整 JSON 解析器是杀鸡用牛刀，
+// .d2x.json 中此处只需读取 "lang"。引入完整 JSON 解析器并无必要，
 // 但也不能假装解析——这里只做一件明确的事：取出 "lang" 的字符串值。
 export std::string read_lang(const fs::path& root) {
     std::ifstream in(root / ".d2x.json");
@@ -85,7 +85,7 @@ std::string humanize(std::string_view topic) {
 // 练习 id 直接来自目录/文件名，而它有两个危险去向：
 //   1. d2x 把它拼进一条 shell 命令（`<provider> check <id>`）
 //   2. 我们把 test 名拼进 `mcpp test <pattern>` 命令行
-// 带反引号、引号或换行的名字能在任一处越界。在源头挡住比在下游转义更可靠。
+// 带反引号、引号或换行的名字在任一处都可能越界。在发现阶段拒绝比在下游各自转义更可靠。
 export bool valid_id(std::string_view id) {
     if (id.empty()) return false;
     return std::ranges::all_of(id, [](unsigned char c) {

d2x/buildtools/src/runner.cppm

@@ -185,8 +185,8 @@ export struct RunReport {
     std::vector<Failure> failures;
 };
 
-// 判定顺序（与代码一致，注意 wait 先于退出码——d2x 库里 wait 会把退出码
-// 顶成 1，若先看退出码，blocked 会全部误判成 fail）：
+// 判定顺序（与代码一致；wait 必须先于退出码判定——d2x 库在存在未拆除的
+// wait 时会将退出码置为 1，若先判退出码，blocked 会被整体误判为 fail）：
 //   有 ok:false            → Fail，每条失败都能转成一个 Diagnostic
 //   无失败、有 wait        → Blocked（答案已对，只差拆路障）
 //   无失败但退出码非 0     → Fail（纯崩溃 / 练习自己 return 非 0）

d2x/buildtools/tests/e2e.sh

@@ -6,9 +6,9 @@
 #
 # 这是 rustlings `cargo dev check --require-solutions` 的等价物。
 #
-# 两道防线(各自都咬过人,见 .agents/docs 参考文档):
+# 两道防线(均源自历史缺陷,背景见 .agents/docs 参考文档):
 #   - 脏树检查: 练习/答案目录有未提交改动时拒绝运行 —— 脚本要把答案覆盖到
-#     练习上再用 git 还原,未提交的改动会被吃掉
+#     练习上再用 git 还原,未提交的改动会被覆盖丢失
 #   - 防空转: overlay 后 passed 总数为 0 时直接失败,绝不静默绿灯
 #
 # 用法:  bash d2x/buildtools/tests/e2e.sh [zh|en|all]   (默认 all)
@@ -31,7 +31,7 @@ run_lang() {
     local dirty
     dirty=$(git status --porcelain -- "${test_dirs[@]}" solutions/ | head -20)
     if [[ -n "$dirty" ]]; then
-        echo "E2E($label) 拒绝运行: 练习/答案目录有未提交改动(脚本的覆盖-还原会吃掉它们):"
+        echo "E2E($label) 拒绝运行: 练习/答案目录存在未提交改动(脚本的覆盖-还原流程会将其覆盖丢失):"
         echo "$dirty"
         return 1
     fi

d2x/src/d2x.cppm

@@ -22,7 +22,7 @@ import std;
 //                   把「为什么失败」变成结构化诊断、把 wait 区分成 blocked。
 //                   未设置时不写文件：学习者直接跑二进制零摩擦。
 //
-// 可见输出的设计（学习者每天面对的三行）：
+// 可见输出的设计（学习者直接看到的三类输出行）：
 //   ✅ | <what> (<actual> == <expected>)                     绿
 //   ❌ | <what> (<actual> == <expected>)  -> <file>:<line>  红
 //   🚧 | Delete the d2x::wait() to continue  -> <file>:<line>  黄
@@ -104,9 +104,9 @@ inline void report_wait(const char* file, int line) {
     emit(out);
 }
 
-// std::formattable 是 SFINAE 安全的探测；直接在 requires 里写
-// std::format("{}", v) 会踩进未特化 std::formatter 的 static_assert
-// 硬错误（scoped enum、自定义类型的练习实测中招）。
+// std::formattable 是 SFINAE 安全的探测；若直接在 requires 表达式里写
+// std::format("{}", v)，会触发未特化 std::formatter 的 static_assert
+// 硬错误（scoped enum、自定义类型的练习中已实际出现）。
 inline std::string show_impl(const auto& v) {
     using T = std::remove_cvref_t<decltype(v)>;
     if constexpr (std::formattable<T, char>) return std::format("{}", v);

mcpp.toml

@@ -1,6 +1,6 @@
-# d2mcpp 根 workspace。练习即测试:每个 C++ 标准是 src/ 下的一个真实工程,
-# 练习是它的 tests/,mcpp test 直接就是进度表;d2x checker 驱动同一条链。
-# d2x/ 是练习库(import d2x)与 Provider 的家。
+# d2mcpp 根 workspace。练习即测试:每个 C++ 标准对应 src/ 下的一个 mcpp 工程,
+# 练习即该工程的 tests/,mcpp test 的测试报告即学习进度;d2x checker 复用同一条链路。
+# d2x/ 目录包含练习库(import d2x)与 Provider(buildtools/)。
 [workspace]
 members = [
     "d2x",

src/en/intro/tests/hello-mcpp.cpp

@@ -5,7 +5,7 @@
 // Exercise: Automated Code Practice Usage Tutorial
 //
 // Tips:
-//    This is an "exercises are tests" automated practice project. Two ways to play:
+//    This is an "exercises are tests" automated practice project. Two modes of use:
 //
 //      d2x checker              guided mode: auto-detects your edits, passing advances you
 //      mcpp test -p src/en/intro    native mode: plain mcpp — the test report IS your progress

src/intro/tests/hello-mcpp.cpp

@@ -5,10 +5,10 @@
 // Exercise/练习: 自动化代码练习使用教学
 //
 // Tips/提示:
-//    这是一个「练习即测试」的自动化代码练习项目。两种玩法任选:
+//    这是一个「练习即测试」的自动化代码练习项目。两种使用方式任选:
 //
-//      d2x checker              闯关模式: 自动检测、通过即进入下一题
-//      mcpp test -p src/intro       原生模式: 直接用 mcpp 跑, 测试结果就是进度表
+//      d2x checker              引导模式: 自动检测,通过后进入下一题
+//      mcpp test -p src/intro       原生模式: 直接使用 mcpp 运行, 测试报告即学习进度
 //
 //    你需要根据控制台的报错和提示信息修改代码。约定只有三个:
 //