fix: cmd 的转义只加在真正没被保护的那个字符上;示例补 <cstddef>

Windows e2e 两红,Linux examples 一红,两条都是这一轮自己引入的。

## 一、把引号也一起转义,打断了每一次包获取

上一条提交的做法是:先按子进程的规则引用,再给**每个 cmd 元字符,包括引号本身**
前缀 `^`。理由在纸面上成立 —— 没有裸引号,cmd 就从不进入引用区,于是每个元字符都是
被转义而不是被引用的。

**Windows CI 的读数是:每一次 `install_packages` 都退 1**,包括那两次 JSON 里一个
元字符都没有的(`compat:widget@1.38.1`、`mcpplibs:tpl-demo@1.0.0`)。而这个 job 里
只有那两次调用,也就是**走到这条路的每一次都失败了**。

改成保守的那条规则:引用之后,**按 cmd 看到的引用状态**走一遍(每个 `"` 都翻转它,
因为 cmd 不认 MSVCRT 的 `\"`),只给**落在引用区之外**的元字符加 `^`。引用区里的元
字符本来就是惰性的,而 `^` 在那里是个普通字符。

于是「没有东西要转义」的载荷输出与 `quote_windows` **逐字节相同** —— 那是绝大多数
载荷,也正是被打断的那些。而 `>=2026.3` 里那个 `>` 只多一个 `^`。

判据补了一条:`NothingToEscapeMeansByteIdenticalToPlainQuoting`,直接拿 CI 里失败的
那两个 JSON 当输入。cmd 的模拟器也补上了「`^` 在引用区内是普通字符」这一半 —— 只建
模前一半,它会接受一个 cmd 并不接受的形状。

## 二、示例:`std::size_t` 要 `#include <cstddef>`

`src/cpu/render.cpp` 在 libstdc++ 下编得过、在 libc++ 下编不过:

    src/cpu/render.cpp:56:52: error: no type named 'size_t' in namespace 'std'

标准头有权带进它需要的其他头,而带进哪些因实现而异。本地默认工具链是 gcc,CI 那一步
用的是 llvm —— **同一台机器上的两个答案**。点名一个类型的翻译单元必须包含声明它的那个
头,不管上一个实现顺手给了什么。

`src/vulkan/render.cpp` 同样补上(它此前靠 `<vulkan/vulkan.h>` 间接得到)。

可迁移的:**本地验示例要用 CI 那一步用的工具链**(`mcpp build --toolchain llvm@…`),
否则验的是另一个标准库。

Author: speak-agent

examples/10-graphics/offscreen/src/cpu/render.cpp

@@ -7,6 +7,17 @@
 // `render_device_name`, never the image.
 #include "render/render.h"
 
+// `<cstddef>` FOR `std::size_t`, AND IT IS NOT PEDANTRY.
+//
+// A standard header is entitled to bring in whichever others it needs, and
+// which ones it brings differs between implementations. This file compiled
+// against libstdc++ and then failed against libc++ on the same machine:
+//
+//   src/cpu/render.cpp:56:52: error: no type named 'size_t' in namespace 'std'
+//
+// A translation unit that names a type has to include the header that declares
+// it, whatever the last implementation happened to hand it for free.
+#include <cstddef>
 #include <cmath>
 
 namespace {

examples/10-graphics/offscreen/src/vulkan/render.cpp

@@ -19,6 +19,7 @@
 
 #include <vulkan/vulkan.h>
 
+#include <cstddef>
 #include <cstdint>
 #include <cstring>
 #include <vector>

modules/platform/src/shell.cppm

@@ -41,11 +41,20 @@ std::string quote_posix(std::string_view s);
 //
 // which arrived as a package-provisioning failure naming a package.
 //
-// The answer is the standard double escape: quote for the child, then prefix
-// every cmd metacharacter -- the quotes included -- with `^`. With no `"` left
-// unescaped cmd never enters a quoted region, so every metacharacter is
-// escaped rather than quoted, which is the only state in which both rules
-// hold. cmd removes the carets and the child sees exactly `quote_windows`.
+// The answer escapes exactly what needs it: quote for the child, then walk the
+// result tracking the quote state CMD sees -- every `"` toggles it, because cmd
+// does not know MSVCRT's `\"` -- and prefix `^` to any metacharacter that falls
+// outside a quoted region. Inside one it is already inert, and `^` there is a
+// literal character rather than an escape.
+//
+// ESCAPING EVERY METACHARACTER INCLUDING THE QUOTES WAS TRIED FIRST AND
+// BROKE EVERY PAYLOAD. It is defensible on paper -- with no bare `"`, cmd never
+// enters a quoted region and each metacharacter is escaped rather than quoted
+// -- and Windows CI answered `exit 1` for every package fetch, including the
+// ones whose JSON contains no metacharacter at all. So the rule here is the
+// conservative one: a payload with nothing to escape comes out byte-identical
+// to `quote_windows`, and only the character that is actually unprotected
+// acquires a caret.
 //
 // `%` IS NOT ESCAPED AND CANNOT BE. Variable expansion happens before caret
 // processing, and the batch-file escape (`%%`) is not available on a command
@@ -101,15 +110,24 @@ std::string quote_posix(std::string_view s) {
 std::string quote_windows_through_cmd(std::string_view s) {
     const std::string inner = quote_windows(s);
     std::string out;
-    out.reserve(inner.size() * 2);
+    out.reserve(inner.size() + 8);
+    // cmd's quote state, which is toggled by EVERY `"` -- it does not know
+    // MSVCRT's `\"`. Inside a quoted region a metacharacter is already inert
+    // and `^` is a literal character, so only the characters that fall OUTSIDE
+    // one are escaped. That keeps the result byte-identical to `quote_windows`
+    // for every payload with nothing to escape, which is nearly all of them.
+    bool inQuotes = false;
     for (char c : inner) {
-        switch (c) {
-            case '"': case '<': case '>': case '&': case '|':
-            case '^': case '(': case ')':
-                out.push_back('^');
-                break;
-            default:
-                break;
+        if (c == '"') { inQuotes = !inQuotes; out.push_back(c); continue; }
+        if (!inQuotes) {
+            switch (c) {
+                case '<': case '>': case '&': case '|':
+                case '^': case '(': case ')':
+                    out.push_back('^');
+                    break;
+                default:
+                    break;
+            }
         }
         out.push_back(c);
     }

tests/unit/test_windows_command_line.cpp

@@ -160,7 +160,10 @@ CmdParse simulate_cmd_c(std::string_view wrapped) {
     bool inQuotes = false;
     for (std::size_t i = 0; i < line.size(); ++i) {
         char c = line[i];
-        if (c == '^') {                       // escapes the next character
+        // `^` escapes the next character OUTSIDE a quoted region; inside one
+        // it is an ordinary character. Modelling only the first half would let
+        // this simulator accept a shape cmd does not.
+        if (c == '^' && !inQuotes) {
             if (i + 1 < line.size()) out.passedOn.push_back(line[++i]);
             continue;
         }
@@ -238,6 +241,22 @@ TEST(WindowsCommandLine, MetacharacterQuotingSurvivesBothParsers) {
         << "the child received something other than the JSON that was meant";
 }
 
+TEST(WindowsCommandLine, NothingToEscapeMeansByteIdenticalToPlainQuoting) {
+    // The conservative half of the rule, and it is the half that was measured
+    // the hard way: an earlier version escaped every metacharacter INCLUDING
+    // the quotes, which is defensible on paper and broke every package fetch on
+    // Windows -- including the ones whose JSON contains no metacharacter. A
+    // payload with nothing to escape must come out exactly as before.
+    for (std::string_view plain : {
+             R"({"targets":["mcpplibs:tpl-demo@1.0.0"],"yes":true})",
+             R"({"targets":["compat:widget@1.38.1"],"yes":true})",
+             R"(a plain path C:\Program Files\x)" }) {
+        EXPECT_EQ(mcpp::platform::shell::quote_windows_through_cmd(plain),
+                  mcpp::platform::shell::quote_windows(plain))
+            << "a payload with no metacharacter acquired an escape: " << plain;
+    }
+}
+
 TEST(WindowsCommandLine, MetacharacterQuotingIsUnchangedForPlainText) {
     // A payload with nothing to escape must not acquire carets, so the common
     // case stays legible in a log.