fix(cdb): arguments 是 argv,不是 shell 词

消费者(clangd)逐字 exec `arguments`,不经 shell。所以一个仍带着 shell 引号的 token
不是 flag,而是一个不存在的文件名。

用户报的是 Windows 上 `-fmodule-file=` 带多余双引号、每次构建后要手工删。核实后比
报告更严重,而且在 Linux 上就能复现 —— 带空格的项目路径 + llvm:

  '-fmodule-file=std=/tmp/.../my project/.../std.pcm      <- 闭合引号没了
  '-fprebuilt-module-path=/tmp/.../my project/.../pcm.cache'

第一条不只是多个引号:token 在引号**内部**的空格处被切断,一个参数变成两个,其中一个
带着永不闭合的开引号。

机制是四步各自合理的叠加:`shell_quote_arg` 的触发集含反斜杠(Windows 路径必含,所以
那里每个带路径的 flag 都被引号包住)→ 加引号对 ninja 是对的 → `split_flags` 撤销 ninja
转义并重新分词 → 但它不认引号。

`split_flags` 原来的注释把原则写对了 ——「消费者逐字 exec,所以转义必须撤销」—— 只实现
了一半,漏掉同一理由下的 shell 引号。现在三件事都做,且**顺序**是要点:ninja 的 `$ `
反转义必须发生在引号**内**,否则被引号包住的空格先把 token 切断,那正是原来的 bug。

中间的引号是数据不是引用:`-DGREETING="hi"` 保留内部引号,否则宏的含义就变了。

判据写成「任何 token 不以引号开头/结尾,且带空格的路径是一个 token」,不是「clangd 能
用了」—— 后者在不含空格的路径上恒真,正是它至今没被发现的原因:所有 e2e 的项目路径都
不含空格。

`split_flags` 由匿名 namespace 提升为导出:它就是那份契约,该由测试钉住而不是靠通读
生成文档来推断。

  tests/unit/test_compile_commands.cpp  +5(9 条);端到端复验:带引号 token 归零

Author: speak-agent

.agents/docs/2026-08-08-wire-protocol-implementation-plan.md

@@ -0,0 +1,95 @@
+# 机器可读输出协议 —— 拆分实施计划
+
+> 设计:`2026-08-08-machine-readable-output-protocol-design.md`(对 RFC #379 的核对与修正)
+> 已定:未知格式走 **stderr + rc=2**;`pack --format` **声明为例外**。
+
+## 顺序与理由
+
+设计文档 §4.5 把 CDB 引号缺陷排在阶段 1 之前,理由是「协议做得再好,也救不了一个内容
+本身就坏掉的出口」。照此排:
+
+```
+W0  CDB 引号(§4.5)          —— 今天就在坏,且与协议正交,先修
+W1  stdout 归属(阶段 0)      —— 未知选项/未知值统一 stderr + rc=2
+W2  mcpp.wire 模块(阶段 1)   —— envelope + destructive + --protocol-version
+W3  --format 归一(阶段 2)    —— --json 永久别名,入口一处归一
+W4  接入(阶段 3a)            —— self env / xpkg parse / cache list
+```
+
+W4 之后的 `metadata` / `--configure-only`(阶段 3b/3c)**不在本次范围** —— 它们是新增
+能力而非契约统一,且依赖 #372 的拆分结论。
+
+## W0 —— CDB 的 `arguments` 带 shell 引号
+
+**File:** `src/build/compile_commands.cppm`
+
+- [ ] **Step 1** 红:带空格路径 + llvm 的单测,断言
+      ① 任何 token 不以引号开头/结尾;② 带空格的路径是**一个** token
+- [ ] **Step 2** 跑,确认 FAIL(今天两条都不满足)
+- [ ] **Step 3** 让 `split_flags` 认引号。**顺序陷阱**:ninja 的 `$ ` 反转义必须发生在
+      引号**内**,否则被引号包住的空格先把 token 切断 —— 那正是现在的 bug
+- [ ] **Step 4** 绿
+- [ ] **Step 5** Commit
+
+判据不能写成「clangd 能用了」——在不含空格的路径上恒真,正是它至今没被发现的原因。
+
+## W1 —— stdout 归属
+
+**Files:** `src/cli.cppm`、`src/main.cpp`(+ 依赖 `mcpplibs.cmdline` 的处置)
+
+- [ ] **Step 1** 红:e2e 断言未知**选项**与未知**值**在通道(stderr)与退出码(2)上一致
+- [ ] **Step 2** 跑,FAIL(今天:未知选项 → stdout/rc=1;未知值 → stderr/rc=2)
+- [ ] **Step 3** 实现。`mcpplibs.cmdline:127` 用 `std::println` 写 stdout,在依赖里 ——
+      **本次不改依赖**,改为 mcpp 侧接管 `ParseResult`:不走 `App::run()` 的内建错误
+      打印,自己输出到 stderr 并返回 2
+- [ ] **Step 4** 绿
+- [ ] **Step 5** Commit
+
+## W2 —— `mcpp.wire`(独立模块)
+
+**New:** `src/wire.cppm`
+
+- [ ] **Step 1** 单测:envelope 形状(`schemaVersion` / `kind` / `destructive` /
+      `mcpp.version` / `mcpp.protocol{min,max}` / `data` / `diagnostics`)
+- [ ] **Step 2** 实现。`Diagnostic/Position/Range/Severity` 与 envelope 构造从 #372 的
+      `src/ide/model.cppm`、`src/ide/snapshot.cppm` 提升(设计文档 §5-B)
+- [ ] **Step 3** `mcpp --protocol-version`:输出 `{min,max}` **加命令 → destructive 静态表**
+      (设计 §2.3 —— untrusted 门要在执行前知道)
+- [ ] **Step 4** golden fixture,且**反向验证过**(改字段名要变红,设计 §4)
+- [ ] **Step 5** Commit
+
+## W3 —— `--format` 归一
+
+**Files:** `src/cli.cppm`(入口归一)、各 `cmd_*.cppm`
+
+- [ ] **Step 1** 单测:`--json` 与 `--format json` 产出**逐字节相同**
+- [ ] **Step 2/3** 入口一处 `--json` → `--format json`;核心只见 `--format`
+- [ ] **Step 4** 绿;`--json` 永久保留、**不打 deprecation 警告**
+- [ ] **Step 5** Commit
+
+`pack --format tar|dir` 不动(已定为例外),文档写明。
+
+## W4 —— 接入 envelope
+
+**Files:** `cmd_self.cppm`(新增 `self env --format json`)、`cmd_xpkg.cppm`、`cmd_cache.cppm`
+
+- [ ] **Step 1** 每个 `kind` 一个 golden fixture(反向验证过)
+- [ ] **Step 2** `self env` 覆盖 mcpp-vscode#8 §2.4:MCPP_HOME / registry / xlings home /
+      index repos / default toolchain
+- [ ] **Step 3** `xpkg parse` / `cache list` 包进 envelope(`schemaVersion` 随之而来)
+- [ ] **Step 4** 绿
+- [ ] **Step 5** Commit
+
+## 平台特化的去处
+
+按要求:平台差异进 `src/platform/`,协议本体独立 `.cppm`。
+
+- 协议本体 → **`src/wire.cppm`**(新模块,不依赖任何命令)
+- 路径/引号的平台差异 → 已在 `src/platform/`(`env::path_list_separator` 等);W0 的
+  引号识别是**平台无关**的(引号本身两平台都要剥),不新增平台分支
+
+## 交付
+
+- 全部并入 **PR #385**(与 docs 一起)
+- 版本已是 2026.8.8.3(刚发布)⇒ 本次**跳过版本 bump**,除非 CI 要求
+- xlings pin 已是 2026.8.8.1(索引最新)⇒ 无需再抬

src/build/compile_commands.cppm

@@ -21,6 +21,13 @@ import mcpp.libs.json;
 
 export namespace mcpp::build {
 
+// Split one flag string into CDB `arguments` tokens.
+//
+// Exported because it IS the contract: what a consumer receives in
+// `arguments` is decided here, and that contract needs pinning by test
+// rather than by inspection of a whole generated document.
+std::vector<std::string> split_flags(std::string_view s);
+
 // Generate compile_commands.json content as a string.
 std::string emit_compile_commands(const BuildPlan& plan, const CompileFlags& flags);
 
@@ -54,50 +61,87 @@ bool is_c_source(const std::filesystem::path& src) {
     return ext == ".c" || ext == ".m";
 }
 
-// Split a flag string into individual tokens AND un-escape ninja-style
-// path escapes (`$ ` → space, `$:` → `:`, `$$` → `$`).
+}  // namespace
+
+// Split one flag string into CDB `arguments` tokens.
+//
+// Three things happen here, and the ORDER between them is the whole point.
+//
+// 1. Ninja escapes are undone (`$ ` -> space, `$:` -> `:`, `$$` -> `$`).
+//    `flags.cppm::escape_path` adds them so a path survives embedding in a
+//    ninja rule string. A CDB consumer execs `arguments` literally -- no
+//    ninja -- so `C$:\Users\...` would be a path that does not exist.
+//
+// 2. Shell quoting is removed. `flags.cppm::shell_quote_arg` wraps a token
+//    whose characters would split or alter a word in `sh -c` / cmd.exe --
+//    and its trigger set contains the BACKSLASH, so on Windows every
+//    path-bearing flag is quoted. That quoting is correct for ninja and
+//    wrong for a consumer that never invokes a shell: the quotes arrive as
+//    part of the filename.
+//
+// 3. Tokens split on spaces -- but not on a space that came from `$ `, and
+//    not on one inside quotes.
+//
+// Getting (3) wrong is what shipped: quoting was ignored entirely, so a
+// quoted path containing a space was cut in half at that space. Measured on
+// a real build under `/tmp/.../my project`:
+//
+//   '-fmodule-file=std=/tmp/.../my project/.../std.pcm   <- closing quote gone
+//   '-fprebuilt-module-path=/tmp/.../my project/.../pcm.cache'
 //
-// `flags.cppm::escape_path` ninja-escapes path arguments so they survive
-// embedding in ninja rule strings. Those escaped strings are then captured
-// into `f.cxx` / `f.cc` which is what we receive here. CDB consumers like
-// clangd exec the `arguments` array literally — no ninja involved — so
-// escaped chars must be undone or paths like `C:\Users\...` come through
-// as `C$:\Users\...` and break clangd's path resolution on Windows. (The
-// same issue would silently affect any POSIX path containing a space or
-// `$` — those just happen to be rare.)
+// One argument became two, one of them opening a quote that never closes.
+// The comment that used to live here stated the right principle -- consumers
+// exec literally, so escapes must be undone -- and implemented half of it.
 //
-// Splitting and un-escaping in one pass is correct: a literal space inside
-// a path appears as `$ ` in the input, which we must NOT treat as a token
-// separator.
+// A quote in the MIDDLE of a token is data: `-DGREETING="hi"` keeps its
+// inner quotes, or the define changes meaning. Only a quote that OPENS a
+// region is quoting.
 std::vector<std::string> split_flags(std::string_view s) {
     std::vector<std::string> out;
     std::string token;
+    bool started = false;          // token has begun (so "" is a real empty arg)
+    char quote = 0;                // active quote char, 0 when outside
+
     auto flush = [&] {
-        if (!token.empty()) {
-            out.push_back(std::move(token));
-            token.clear();
-        }
+        if (started) { out.push_back(std::move(token)); token.clear(); }
+        started = false;
     };
+
     for (std::size_t i = 0; i < s.size(); ++i) {
         char c = s[i];
+
+        // Ninja escapes first, and INSIDE quotes too -- a quoted path's space
+        // arrives as `$ ` because flags.cppm escapes before it quotes.
         if (c == '$' && i + 1 < s.size()) {
             char nc = s[i + 1];
             if (nc == ' ' || nc == ':' || nc == '$') {
                 token.push_back(nc);
+                started = true;
                 ++i;
                 continue;
             }
         }
-        if (c == ' ') {
-            flush();
-        } else {
+
+        if (quote) {
+            if (c == quote) { quote = 0; continue; }   // closes the region
             token.push_back(c);
+            continue;
         }
+
+        // Opens a region only at a token boundary; elsewhere it is data.
+        if ((c == '"' || c == '\'') && !started) { quote = c; started = true; continue; }
+
+        if (c == ' ') { flush(); continue; }
+
+        token.push_back(c);
+        started = true;
     }
     flush();
     return out;
 }
 
+namespace {
+
 std::vector<std::string> local_include_args(const CompileUnit& cu) {
     std::vector<std::string> args;
     args.reserve(cu.localIncludeDirs.size());

tests/unit/test_compile_commands.cpp

@@ -92,3 +92,83 @@ TEST(CompileCommandsMerge, MalformedExistingFallsBackToFresh) {
     EXPECT_NE(merged.find("src/main.cpp"), std::string::npos) << merged;
     EXPECT_NE(merged.find("-O2"), std::string::npos) << merged;
 }
+
+// ── CDB arguments must be argv, not shell words ─────────────────────────────
+//
+// A consumer (clangd) execs `arguments` LITERALLY — no shell. So a token that
+// still carries the quoting a shell would have removed is not a flag, it is a
+// filename that does not exist.
+//
+// This is reachable on every platform, and was found on Windows first only
+// because `shell_quote_arg`'s trigger set contains the backslash: every
+// Windows path has one, so every path-bearing flag there gets quoted. On
+// POSIX it takes a space in the path — which is why no e2e caught it: none of
+// their project paths have one.
+//
+// Measured before the fix, from a real build under `/tmp/.../my project`:
+//
+//   '-fmodule-file=std=/tmp/.../my project/.../std.pcm     <- closing quote gone
+//   '-fprebuilt-module-path=/tmp/.../my project/.../pcm.cache'
+//
+// The first is worse than a stray quote: the token was split at the space
+// INSIDE the quotes, so one argument became two, one of them opening a quote
+// that never closes.
+namespace {
+
+bool is_quoted(std::string_view s) {
+    if (s.size() < 2) return false;
+    return (s.front() == '"' && s.back() == '"')
+        || (s.front() == '\'' && s.back() == '\'');
+}
+bool has_edge_quote(std::string_view s) {
+    return !s.empty()
+        && (s.front() == '"' || s.front() == '\''
+         || s.back()  == '"' || s.back()  == '\'');
+}
+
+}  // namespace
+
+TEST(CompileCommandsArgs, StripsPosixQuotingFromAToken) {
+    auto out = mcpp::build::split_flags("-O2 '-fprebuilt-module-path=/a/b' -g");
+    ASSERT_EQ(out.size(), 3u);
+    EXPECT_EQ(out[1], "-fprebuilt-module-path=/a/b");
+    for (auto const& t : out) EXPECT_FALSE(has_edge_quote(t)) << t;
+}
+
+TEST(CompileCommandsArgs, StripsWindowsQuotingFromAToken) {
+    auto out = mcpp::build::split_flags(R"(-O2 "-IC:\Users\x\inc" -g)");
+    ASSERT_EQ(out.size(), 3u);
+    EXPECT_EQ(out[1], R"(-IC:\Users\x\inc)");
+    for (auto const& t : out) EXPECT_FALSE(has_edge_quote(t)) << t;
+}
+
+// The one that bit: a quoted path containing a space is ONE argument. The
+// space arrives ninja-escaped (`$ `) because flags.cppm escapes before it
+// quotes, so the un-escape has to happen INSIDE the quotes — do it in the
+// wrong order and the token splits exactly here.
+TEST(CompileCommandsArgs, AQuotedPathWithASpaceStaysOneToken) {
+    auto out = mcpp::build::split_flags(
+        "-O2 '-fmodule-file=std=/tmp/my$ project/std.pcm' -g");
+    ASSERT_EQ(out.size(), 3u) << "the quoted path was split";
+    EXPECT_EQ(out[1], "-fmodule-file=std=/tmp/my project/std.pcm");
+    for (auto const& t : out) EXPECT_FALSE(has_edge_quote(t)) << t;
+}
+
+// Unquoted input must keep behaving exactly as before: ninja escapes undone,
+// split on spaces.
+TEST(CompileCommandsArgs, UnquotedInputIsUnchanged) {
+    auto out = mcpp::build::split_flags("-IC$:/x -DA=1 -Idir$ with$ space");
+    ASSERT_EQ(out.size(), 3u);
+    EXPECT_EQ(out[0], "-IC:/x");
+    EXPECT_EQ(out[1], "-DA=1");
+    EXPECT_EQ(out[2], "-Idir with space");
+}
+
+// A quote in the MIDDLE of a token is data, not quoting: `-DA="x"` must keep
+// its inner quotes or the define changes meaning.
+TEST(CompileCommandsArgs, InnerQuotesAreNotStripped) {
+    auto out = mcpp::build::split_flags(R"(-DGREETING="hi")");
+    ASSERT_EQ(out.size(), 1u);
+    EXPECT_EQ(out[0], R"(-DGREETING="hi")");
+    EXPECT_FALSE(is_quoted(out[0]));
+}