Repository Wiki
ChanIok/SpinningMomo

打包产物：便携版、dist 与安装器（WiX MSI）

SpinningMomo（旋转吧大喵）的发布链路由三类产物构成：xmake release 产出的便携版（免安装、直接在 build\windows\x64\release\ 运行的原生 Win32 C++ 可执行文件与内嵌 web 资源）、聚合到 dist/ 的分发目录，以及由 scripts/build-installer.js 驱动的 WiX MSI 安装包与 WiX Bundle setup.exe。本页梳理这三类产物的形态、构建入口、版本号来源与验证方式。

Purpose and Scope

本页覆盖：

  • 便携版（Release 构建输出）的目录形态与"绿色运行"语义
  • dist/ 分发目录的内容构成（exe + web resources）
  • 安装器构建入口 node scripts/build-installer.js / pnpm run build:installer，以及 MSI 与 WiX Bundle 的关系
  • 安装器脚本的命令行开关（--msi-only、--version）与默认版本来源 version.json
  • 产物与测试的关系（场景测试默认以 Release 产物为门禁）

本页不覆盖（留给兄弟页面）：

  • xmake 构建系统内部与自定义任务（tasks/ 中的 release、vs 任务）的实现细节 —— 见构建系统相关页面
  • Android 采集中间件 momo-capture.jar 的打包（pnpm run build:android，产物在 build\android\）
  • docs/ VitePress 文档站的构建 —— 它不属于运行时分发内容
  • 应用内的自动更新功能（features/update）

Overview

SpinningMomo 是仅面向 Windows 的原生 Win32 C++ 应用，内嵌 WebView2 前端（Vue 3）。这一定位直接决定了它的打包形态：

  1. 便携版（Portable）：xmake release 将可执行文件与资源直接产出到 build\windows\x64\release\。仓库的场景测试明确将其描述为 "isolated portable sandboxes"（隔离的便携沙箱）中测试 SpinningMomo.exe，说明 Release 产物本身就是免安装、可直接运行的绿色形态。
  2. dist/ 分发目录：仓库记载 Distribution: dist/ (exe + web resources)，即分发时以"可执行文件 + web 前端资源"的组合交付。
  3. 安装器（Installer）：通过 node scripts/build-installer.js（或 pnpm run build:installer）构建。脚本生成一个 MSI 安装包，并默认额外生成一个基于 WiX Bundle 的 setup .exe，两者都输出到 dist/。WiX 源文件位于 installer/ 目录。

版本号以仓库根部的 version.json 为默认来源，命令行 --version X.Y.Z 可覆盖之。

Architecture

下面的架构图依据 AGENTS.md 与 AGENTS.md 的 Build Output / Installer 章节 绘制。实线为 AGENTS.md 明确记载的数据流；虚线（.->）为合理推断（例如安装器脚本消费 Release 产物），其内部实现未在本页核实：

Loading diagram...

图中的关键分层含义：

  • 构建层：xmake release 负责 C++ 后端的 Release 编译；pnpm run build:web 单独构建前端。二者是独立入口，最终在分发层汇合。
  • 安装器构建层：scripts/build-installer.js 是唯一的安装器编排入口，WiX 源文件集中在 installer/（AGENTS.md 记载 installer/ 为 "WiX source files for MSI and bundle installer generation"）。
  • 分发层：MSI、setup .exe、以及 exe + web 资源统一落在 dist/。
  • 验证层：场景测试默认以 build/windows/x64/release/ 下的 Release 产物为被测对象。

Core Flow：从源码到安装器产物

依据 AGENTS.md 中记录的命令，一次完整的发布流程按以下顺序执行：

Loading diagram...

逐步说明：

  1. xmake release —— 编译 C++ 后端的 Release 版本。便携版产物落在 build\windows\x64\release\，Debug 版本则落在 build\windows\x64\debug\（见 AGENTS.md Build Output）。
  2. pnpm run build:web —— 构建 web 前端。分发包中 "exe + web resources" 的 web 资源部分即来自这一步。
  3. node scripts/build-installer.js —— 安装器构建入口（也可用 pnpm run build:installer）。该脚本：
    • 以 version.json 为默认版本来源；
    • 生成 MSI 安装包；
    • 默认额外生成基于 WiX Bundle 的 setup .exe；
    • 两者均输出到 dist/。

Usage Examples

便携版构建命令

AGENTS.md "Build & Development" 章节记录的完整命令集（原样摘录）：

text
1# C++ backend — debug 2xmake build 3 4# C++ backend — release 5xmake release 6 7# Web frontend 8pnpm run build:web 9 10# Android capture service 11pnpm run build:android

Source: AGENTS.md

其中 xmake release 是便携版/Release 产物的构建入口；xmake build 默认产出 Debug。

安装器构建（AGENTS.md 原文）

AGENTS.md 的 Installer 章节对安装器构建的完整描述（原样摘录）：

text
1Installers are built via `node scripts/build-installer.js` (or `pnpm run build:installer`). 2The script builds an MSI package and, by default, a WiX bundle-based setup `.exe`, 3both under `dist/`. Use `--msi-only` to skip the bundle; use `--version X.Y.Z` to 4override `version.json`.

Source: AGENTS.md

对应的调用形式：

bash
1# 默认：MSI + WiX Bundle setup.exe，版本取自 version.json 2node scripts/build-installer.js 3 4# 或通过 pnpm 5pnpm run build:installer 6 7# 仅构建 MSI，跳过 Bundle 8node scripts/build-installer.js --msi-only 9 10# 覆盖 version.json 的版本号 11node scripts/build-installer.js --version 1.2.3

Source: AGENTS.md（命令行形式由该段描述归纳而来；脚本源码 scripts/build-installer.js 在本页未能读取，未核实内部实现）

场景测试中的便携沙箱用法

AGENTS.md Testing 章节展示了 Release 便携版在测试中的角色（节选自原文）：

text
1They test a compiled `SpinningMomo.exe` in isolated portable sandboxes via JSON-RPC. 2The default gates the Release build (`build/windows/x64/release/`); content-hash 3semantics only hold in Release, so run `xmake release` before testing. 4Point at another build (e.g. Debug) via `--exe=<path>` / `SPINNING_MOMO_EXE`.

Source: AGENTS.md

要点：场景测试默认门禁 Release 产物；内容哈希（content-hash）语义只在 Release 下成立，因此测试前必须先 xmake release；可用 --exe=<path> 或环境变量 SPINNING_MOMO_EXE 指向其他构建（如 Debug）。

Configuration Options

选项类型默认值作用
--msi-onlyCLI 开关（boolean）关闭传给 scripts/build-installer.js 时跳过 WiX Bundle setup .exe 的生成，仅构建 MSI
--version X.Y.ZCLI 参数（string）取自 version.json覆盖安装器版本号，不修改 version.json 本身
version.json仓库文件仓库当前值安装器构建的默认版本号来源（文件内容未在本页核实）
SPINNING_MOMO_EXE环境变量（string）—场景测试中指定被测可执行文件路径，等价于 --exe=<path>
--exe=<path>测试 CLI 参数（string）build/windows/x64/release/场景测试指向其他构建产物（如 Debug）

Source: AGENTS.md、AGENTS.md

Professional Notes

产物目录一览

产物路径生成入口说明
便携版 Releasebuild\windows\x64\release\xmake release免安装可直接运行；场景测试默认门禁对象
Debug 构建build\windows\x64\debug\xmake build开发调试用，不用于分发
Android 中间件build\android\momo-capture.jarpnpm run build:androidAndroid 采集中间件，见 android/capture/README.md
分发内容dist/构建流程汇聚"exe + web resources"，以及安装器输出
MSI 安装包dist/node scripts/build-installer.jsWiX 编译产出
Bundle setup.exedist/node scripts/build-installer.js（默认开启）WiX Bundle 驱动的安装器

Source: AGENTS.md

失败模式与边界情况（基于源码证据的部分）

  • 测试前未跑 Release：AGENTS.md 明确 "content-hash semantics only hold in Release"，如果直接对 Debug 构建运行场景测试，内容哈希语义不成立，可能导致测试结论不可信。缓解方式：先执行 xmake release。
  • 测试与应用实例冲突：场景测试会启动一个编译好的 SpinningMomo.exe，AGENTS.md 要求 "Close any running application instance before testing"，否则端口/资源占用可能干扰测试。
  • 自动构建策略：仓库约定 "Do not run builds automatically; let the user confirm or run manually"，即打包与构建命令需人工确认后执行，不应被脚本/代理自动触发。

设计意图（WHY）

  • 便携优先，安装器其次：工具型桌面应用（围绕游戏窗口的截图/录制工作流）天然适合"解压即用"的分发形态；MSI/Bundle 则覆盖偏好正式安装的用户与企业场景。双形态分发由同一个脚本（scripts/build-installer.js）统一编排，避免两套维护路径。
  • MSI 与 Bundle 分离输出：MSI 是标准 Windows 安装单元，Bundle setup .exe 可封装引导与依赖；提供 --msi-only 让发布者在只需要 MSI（例如已有自有引导流程）时跳过 Bundle，减少构建时间与产物体积。
  • 版本号集中在 version.json：让版本来源单点化，同时保留 --version 覆盖能力，便于 CI 或临时发布（例如候选版）不改仓库文件。
  • installer/ 与 tasks/ 分离：AGENTS.md 将 installer/（WiX 源）与 tasks/（xmake 自定义任务如 release、vs）列为独立仓库面，说明"安装器定义"与"构建任务编排"是刻意分离的关注点。

Extension Points

  • 修改安装器行为：WiX 源文件集中在 installer/（MSI 与 Bundle 生成），调整安装界面、组件、升级逻辑应从这里入手。
  • 调整发布/构建流程：tasks/ 下的自定义 xmake 任务（release、vs）是构建编排的扩展点。
  • 脚本源码未核实说明：scripts/build-installer.js 与 installer/ 内的 WiX 文件在本页的资料收集预算内未能读取，其内部实现（例如如何定位 Release 产物、如何调用 WiX 工具链、--msi-only 的具体分支逻辑）未在本页核实。如需深入，请直接阅读 scripts/build-installer.js 与 installer/ 目录。

Tests

  • 场景测试（TypeScript）：位于 tests/scenarios/，通过 pnpm run test:scenarios 运行，在隔离的便携沙箱中以 JSON-RPC 方式驱动编译好的 SpinningMomo.exe。它是对便携版产物最直接的端到端验证（见 AGENTS.md Testing）。
  • C++ 单元测试：遗留 doctest 单元测试位于 tests/，经 xmake test 运行（同上来源）。
  • AGENTS.md — 仓库总览：构建命令、产物目录、安装器入口与测试策略
  • android/capture/README.md — Android 采集中间件架构与打包说明
  • docs/developer/architecture.md — 完整的环境搭建与构建步骤（AGENTS.md 指向的权威来源）
  • 应用内更新机制的页面（features/update 相关）与 xmake 构建系统页面见本目录下的兄弟页面

Sources

(1 files)
AGENTS.md