架构与构建

NOTE

本项目更推荐先通过 Issue 讨论需求和方向，再提交 Pull Request。

对于新功能、行为调整或较大的重构，请先提交 Issue，说明要解决的问题、使用场景和预期效果。这样可以在开始编码前确认它是否符合项目定位。

已确认范围的 Issue、明确的 Bug 修复、文档改进，以及经过讨论的技术难题，都非常欢迎通过 PR 贡献。未经讨论的功能性 PR 可能会因为方向不一致而无法合并。

架构与代码规范说明

本项目核心采用 C++23 原生后端与 Vue 3 Web 前端的混合双端架构。关于详细的设计哲学、C++ 组件划分以及依赖关系，已在此仓库根目录维护了最新的 AGENTS.md。

环境要求

C++ 后端默认使用 clang-cl[llvm]（Clang + LLD）进行日常开发，正式发布使用 MSVC。

工具	要求	说明
Visual Studio 2026 / Build Tools	安装「使用 C++ 的桌面开发」及 C++ Clang 工具	Visual Studio IDE 可选
Windows SDK	10.0.22621.0+（Windows 11 SDK）
Git	最新版	克隆 vcpkg 与获取第三方依赖
xmake	3.1.0	C++ 构建系统
Node.js	v22.13+	Web 前端构建及 pnpm 脚本
JDK	21+	编译 ADB 模式的 Android DEX 服务
Android SDK Command-line Tools	Platform 36 + Build Tools 36.0.0	通过 javac/d8 构建截图服务

安装 xmake

# PowerShell（推荐）
irm https://xmake.io/psget.text | iex

# 或前往官网下载安装包
# https://xmake.io/#/getting_started?id=installation

准备 vcpkg

git clone https://github.com/microsoft/vcpkg.git D:\dev\vcpkg  # 路径自定
cd D:\dev\vcpkg
.\bootstrap-vcpkg.bat
.\vcpkg.exe integrate install

---

依赖准备

1. 获取第三方依赖

pnpm run fetch:third-party

2. 安装 pnpm 依赖

# 安装根项目及所有 workspace 项目依赖
pnpm install

3. 初始化 xmake 依赖并应用补丁

node scripts/patch-xmake-clang-cl-cxx23.js
node scripts/patch-xmake-clang-cl-deps.js

# Clang-cl + LLD（默认）
xmake f --toolchain="clang-cl[llvm]" -y

# 或使用 MSVC
# xmake f --toolchain=msvc -y

xmake f -m release -y && xmake f -m debug -y
node scripts/patch-vcpkg.js

4. 获取 Android 捕获服务（可选）

不修改 android/capture/src/ 下的 Java 代码时，无需配置 JDK 与 Android SDK，直接拉取最新 release 的预编译 jar：

pnpm run fetch:android-jar

之后 pnpm run build 会自动跳过 Android 编译。需重新从源码编译时，删除 build/android/.android-jar-fetched。

---

使用 Visual Studio IDE 开发（可选）

如需使用 Visual Studio 浏览、编辑和调试 C++ 代码，可生成由 Xmake 管理的解决方案：

xmake vs

生成后打开：

vsxmake2026\SpinningMomo.sln

构建

TIP

如果在本地搭建或构建过程中遇到工具链、依赖或环境问题，建议参考 GitHub CI 的 Build Release 工作流，它记录了当前最新且自动化跑通的标准环境配置与构建顺序。

完整构建（推荐）

# 一键完成：C++ Release + Web 前端 + Android 捕获服务 + 打包 dist/
pnpm run build

产物位于 dist/ 目录。

分步构建

# C++ 后端 - Debug（日常开发）
xmake config -m debug
xmake build

# C++ 后端 - Release
xmake release    # 构建 release 后自动恢复 debug 配置

# Web 前端
pnpm run build:web

# Android 捕获服务（可选，需要 JDK + Android SDK）
pnpm run build:android

# 打包 dist/（汇总 exe + web 资源 + Android jar）
pnpm run build:dist

Android 捕获服务

Android 端是轻量屏幕/音频捕获服务，产物为 build/android/momo-capture.jar，通过 ADB 推送由 app_process 运行，无需安装 APK。

修改 Java 代码时需配置 JDK 21 与 Android SDK（platforms;android-36、build-tools;36.0.0），然后运行 pnpm run build:android。依赖版本见 android/capture/build-config.json。

构建输出路径

构建类型	路径
Debug	build\windows\x64\debug\
Release	build\windows\x64\release\
打包产物	dist\

测试

测试只保护确定性的稳定行为和已记录不变量，不以覆盖率为目标。

单元测试

后端回归测试使用 doctest，由独立的 SpinningMomoTests 目标承载：

xmake test -v

该目标默认不参与常规构建，如提示找不到测试程序，先执行 xmake build SpinningMomoTests。

场景测试

场景测试启动真实的 SpinningMomo 进程，通过 HTTP /rpc 端口调用 JSON-RPC 验证端到端行为。 运行在临时目录下的便携版沙箱中，数据库、设置与缩略图全部落在沙箱内，不影响日常使用的实例。 默认验证 Release 产物。

场景脚本不会自动构建，需先准备 Release 产物：

xmake config -m release
xmake build
xmake build SpinningMomoScenarioWindow    # 截图与录制的场景目标窗口
xmake config -m debug                     # 可选，切回日常开发配置
pnpm run test:scenarios                   # 可加套件名子串筛选，如 gallery_core

套件为 gallery_core、gallery_recovery、capture。运行前需退出正在使用的 SpinningMomo， RPC 端口 51206 必须空闲。

不同机器的显卡编码器与音频设备存在差异，采集与录制在这些硬件上的表现仍需运行应用手工验证。

打包发布产物

便携版（ZIP）

pnpm run build:portable

MSI 安装包

需要额外安装 WiX Toolset v6：

dotnet tool install --global wix --version 6.0.2
wix extension add WixToolset.UI.wixext/6.0.2 --global
wix extension add WixToolset.BootstrapperApplications.wixext/6.0.2 --global

然后运行：

pnpm run build:installer

Web 前端开发

启动开发服务器（需 C++ 后端同时运行）：

pnpm run dev:web

Vite 开发服务器会将 /rpc 和 /static 代理到 C++ 后端（localhost:51206）。

代码生成脚本

修改以下源文件后需重新运行对应脚本：

修改内容	需运行的脚本
src/migrations/*.sql	node scripts/generate-migrations.js
src/locales/*.json	node scripts/generate-embedded-locales.js