[Sunrisepeak]

把 C++ 后端从 xmake + vcpkg + 头文件/PCH 迁到 mcpp + 官方包索引 + C++23 具名模块。

这是 #2 的精简版：只留下「以 mcpp + 模块化作为构建」所必需的改动。#2 里为了双构建并存而做的东西 —— xmake 侧的 asio 模块单元、三个 xmake 补丁脚本、两个构建一致性检查、以及 12 个用来定位工具链行为的临时探针工程 —— 在这里全部不带。#2 保留，作为完整的迁移记录与证据链。

	迁移前	迁移后
源码形态	317 .hpp + 180 .cpp，1 个 PCH	263 .cppm + 180 .cpp + 52 .hpp（.hpp 全在 src/vendor/）
接口/实现分离	头文件混装	接口占总行数 17.4%，接口里零个普通函数体
模块图	——	263 接口 / 179 实现单元 / 1 普通 TU / 1924 条边，无环
依赖来源	10 个 vcpkg 包	官方 mcpp-index，工程不带私有索引
机器强制的架构不变量	4 条	17 条，全部可在 Linux 上秒级判定

关键决定

import asio;，不是 #include <asio.hpp>。 头文件形态下 asio::detail::service_registry::use_service 的特化会在每个导入方重新实例化，MSVC 无法调和（fatal error C1116）。模块形态让它只实例化一次。

Windows 工具链因此从原生 cl.exe 换成 llvm（targeting MSVC ABI）。 cl.exe 无法把 asio 的 io_context::service（类内声明、类外定义的嵌套类）经 BMI 往返：

asio/io_context.hpp(1041): error C2039: 'service': is not a member of 'asio::io_context'

llvm 不是新引入的东西 —— 它是 mcpp 在 Windows 的默认工具链，也是本项目此前 xmake 一直用的 clang-cl[llvm] 背后的同一套 LLVM。

cxx_runtime = "self-contained" 一行取代分散的 /MT，并且传导到依赖包的编译行 —— 这是「工程可以直接消费官方索引」的前提。

vendor 层分两种形态，分界线是宏。 真正的第三方库（xxhash / webp / sqlite / spdlog / rfl / uWebSockets / dkm）转成 .cppm 封装模块，头文件只在那里解析一次；Windows SDK / WIL / WebView2 仍是头文件，由各模块在自己的全局模块片段里包含 —— 宏不进 BMI，而这棵树用了约 600 处（FAILED 295、SUCCEEDED 49、IID_PPV_ARGS 42、WM_* ~100）。把它们也变成模块，等于为每个宏造一个 constexpr 替身再改写全部调用点，那是一次与模块化无关的语义重构。

依赖：官方索引，工程不带私有索引

索引缺的 8 个包与 asio 的导出面扩展已经贡献并合入上游：mcpp-index#213 / #214 / #215 / #216。

WebView2 是唯一没进索引的：它是 NuGet 二进制分发，索引的形态分类里没有这一档。它继续走 prebuild，经 include_dirs / ldflags 到达构建 —— 和迁移前一样。

17 条机器强制的架构不变量

scripts/check-cpp-architecture.py + check-module-graph.py，加起来不到一秒，在 CI 的 preflight (linux) job 里先跑，Windows 构建 needs 它。每一条都是一次 Windows 构建换来的，也都反向验证过（注入违规，确认会红）。

其中一条贯穿全程 —— reachable ≠ visible：import 不传递，用到的实体必须由看得见的模块导出。头文件时代传递包含免费提供了这条依赖，所以它从来没有被写下来；「能编」的时长等于「碰巧有别的东西把它拉进来」的时长。限定名与非限定名两半都按实体判定（Ns::Enum::Enumerator 要看枚举而不是枚举项），再加上没有命名空间可认的那一半：Win32 的裸全局类型（SIZE / RECT / HWND…）与 WebView2 的标识符。

模块图必须是 DAG 这一条，暴露了头文件的 include guard 一直藏着的一个真实的环：AppState 的 29 个前向声明换成 import 之后，

app_state -> ui.notification_window.state -> …types -> core.notifications.types -> app_state

闭合。前两条回边是冗余 import，第三条是真的 —— 一个 core 层的 types 模块依赖了应用根对象。改掉了（见 src/core/notifications/types.cppm）。

迁移过程中发现的一个真实缺陷：release 构建缺 NDEBUG

场景测试报「相同内容没有得到相同 hash」。不是 hash 逻辑的问题 —— gallery 扫描器有一条 debug 捷径：

if (core::build_config::is_debug_build()) {
  return hash(file_path.string());     // 路径哈希，不读内容
}

而 is_debug_build() 只看 NDEBUG。mcpp 的 release profile 设优化级别，不管这个宏，所以 mcpp build --release 出来的产物仍然认为自己是 debug。

这不止是测试的事。 全树 14 个使用点，还决定 WebView2 指向 Vite dev server 还是内嵌资源、日志级别、调试 HTTP 路由是否注册 —— 在这个修复之前，release 产物是一个错的程序，而不是一次失败的构建。

修法是 [profile.release] cxxflags = ["-DNDEBUG"]（[profile.*] 没有 defines 键，走文档写明的透传）。它会到达 sm.core.build_config 自己的编译，所有消费者从那个 BMI 里读结论 —— 整个构建不可能像头文件时代那样自己跟自己不一致。

这一条也适用于 #2，那边尚未修（按要求保持不动）。

构建与 CI

workflow	变化
mcpp-windows.yml	新增：preflight (linux) + Windows 全量构建 + mcpp test + 产物核对
build-release.yml	原样保留，只把 xmake 段换成 mcpp
scenario-tests.yml	原样保留，只把 xmake 段换成 mcpp
deploy-docs.yml	未改动（本来就与构建系统无关）

三个 workflow 共用 .github/actions/setup-mcpp —— 一份引导，不会各自漂移。

测试：mcpp test 把 tests/**/*.cpp 每个文件编成独立二进制、按退出码判定，框架无关。于是两个测试文件各自带一个 main 和一个计数器，doctest 依赖去掉了。场景测试的窗口夹具从 tests/ 移到 scenarios/ —— 它不是测试，mcpp test 会真的去运行它。

产物路径从 build/windows/x64/release/ 变成 target/<triple>/<fingerprint>/bin/。fingerprint 覆盖所有会改变输出的东西（profile、工具链、feature 集），所以没有稳定软链接，脚本一律现找（scripts/mcpp-artifact.js）。

---

CI

workflow	结果
mcpp-windows	✅ preflight (linux) + Windows 全量构建 + mcpp test + 产物核对
Build Release	✅ release 构建 + Web 前端 + dist/ 组装 + 便携版 ZIP
Scenario Tests	✅ 端到端场景套件（gallery / recovery / capture）
deploy-docs	只在 main 的 docs/** push 上触发，本 PR 不涉及