使用指南与主要功能地图
旋转吧大喵（SpinningMomo）是一款面向《无限暖暖》的 Windows 桌面工具，围绕"游戏摄影"这一核心场景，提供游戏窗口比例/尺寸切换、8K–12K 超高清截图与录制、以及自动索引照片与视频的游戏摄影图库。本页是用户侧的总入口：完成从下载、安装、首次配置到拍出第一张超清竖构图的完整路径，并给出全部主要功能的功能地图与对应深入文档的导航。
目的与范围
本页覆盖：
- 程序的下载渠道、版本形态（安装版/便携版）与系统运行环境要求
- 首次启动的完整流程：UAC 授权 → 初始配置向导 → 悬浮窗出现
- 《无限暖暖》内的前置游戏设置（显示模式与照片画质）
- 拍出第一张超清竖构图的逐步操作
- 应用整体架构的鸟瞰视图（双进程模型、模块划分），帮助理解"悬浮窗 / 托盘 / 主界面 / 后端"之间的关系
- 主要功能地图：每个功能是什么、入口在哪、深入文档在哪一页
- 常见首次使用问题的排查
本页不覆盖（留给兄弟页面）：
- 各功能的完整用法与参数细节——见
features/*各专项页（窗口控制、截图、录制、图库、HDR、ADB、局域网） - 开发者的构建步骤与代码架构规范——见
developer/architecture（构建指南） - 法律、隐私与致谢信息——见
about/legal与about/credits - 更多拍摄技巧与 FAQ——见
guide/tips与guide/faq
概述
从用户视角看，SpinningMomo 的工作方式是：程序以管理员权限运行，通过悬浮窗（以及托盘图标、右键菜单）控制《无限暖暖》的游戏窗口，把窗口临时切换为超高分辨率的竖构图比例，从而绕过原生截图的分辨率限制；拍照完成后再一键恢复窗口。所有拍摄产物会被自动索引进内置图库，支持标签、评分、时间线、颜色筛选和批量整理。
项目 README 中对功能定位的原始描述如下：
1旋转吧大喵（SpinningMomo）
2
3▸ 一键切换游戏窗口比例/尺寸，完美适配竖构图拍摄、相册浏览等场景
4
5▸ 突破原生限制，支持生成 8K-12K 超高清游戏截图和录制
6
7▸ 内置游戏摄影图库，自动索引照片与视频，支持标签、评分、时间线、颜色筛选和批量整理
8
9▸ 专为《无限暖暖》优化，同时兼容多数窗口化运行的其他游戏关键术语：
| 术语 | 含义 |
|---|---|
| 悬浮窗（floating window） | 常驻屏幕的原生小窗，是窗口控制、拍照、录制的最主要操作入口，快捷键 Ctrl + ` 可隐藏/显示 |
| 托盘图标 / 右键菜单 | 基于命令注册表（commands registry）驱动的第二操作入口，可重新选择目标窗口 |
| 叠加层 / 预览窗 | 高分辨率窗口超出屏幕时的辅助预览手段 |
| 主界面 | WebView2 承载的 Vue 前端，承载图库、设置、关于等功能模块 |
| 大喵相机 | 《无限暖暖》游戏内的摄影模式，是本工具的拍摄入口 |
应用架构鸟瞰
虽然本页面向使用者，但理解程序的结构有助于明白"为什么必须管理员权限""悬浮窗和主界面为什么是两套东西"。SpinningMomo 是原生 Win32 C++ 后端 + 内嵌 WebView2 前端的双进程结构，两者通过 JSON-RPC 2.0 通信：
架构要点（依据仓库的 AGENTS.md 工程说明）：
- 双传输层：生产模式下 Vue 应用运行在 WebView2 内，走 WebView 桥；开发模式下在浏览器中运行，走 uWebSockets 的 HTTP + SSE（端口 51206），SSE 提供服务端到客户端的推送。前端通过检测
window.chrome.webview自动选择传输层。 - 后端不做 OOP 类层次：采用 POD 结构体 + 自由函数，所有状态集中在唯一的
core::AppState根对象中。 - 命令注册表：悬浮窗右键菜单与托盘图标由
core::commands注册表驱动，动作、开关状态、i18n 文案与可选热键统一绑定。 - 用例编排层：跨模块的工作流编排集中在
usecase.hpp/.cpp，这是"拍一张超清竖构图"这类跨功能流程的归属地。
1The application is a **native Win32 C++ backend** that hosts an embedded **WebView2** frontend.
2Communication happens over **JSON-RPC 2.0** through two transport layers:
3- **WebView bridge** — used when the Vue app runs inside WebView2 (production)
4- **HTTP + SSE** — used when the Vue app runs in a browser during development
5 (uWebSockets on port 51206). SSE provides server-to-client push notifications.主要功能地图
程序的全部用户可见能力按模块组织，每个功能在文档站内都有对应的专项页面。功能与入口的对应关系如下：
| 功能 | 一句话说明 | 主要入口 | 深入文档 |
|---|---|---|---|
| 窗口控制 | 一键切换游戏窗口比例/尺寸（如 9:16），拍完一键重置 | 悬浮窗、托盘右键菜单 | features/window |
| 超清截图 | 突破原生限制生成 8K–12K 截图 | 悬浮窗 | features/screenshot |
| 录制 | 高分辨率游戏录像 | 悬浮窗 | features/recording |
| 游戏摄影图库 | 自动索引照片与视频，标签/评分/时间线/颜色筛选/批量整理 | 主界面 | features/gallery |
| HDR | 高动态范围成像相关能力 | — | features/hdr |
| ADB 投屏 | 连接 Android 设备的采集链路（后端含 momo-capture 守护进程） | — | features/adb |
| 局域网 | 跨设备连接相关能力 | — | features/lan |
补充说明：
- 图库子系统有严格的资产身份、元数据继承与"30 天缺失生命周期"等不变量，其扫描器/监视器约束在
src/features/gallery/README.md中单独维护。 - Android 采集服务源码位于
android/，其 VirtualDisplay 流水线与 ADB 调试细节见android/capture/README.md。 - 前端功能模块按
web/src/features/组织（gallery、settings、home、about、map、onboarding、common、playground），其中 onboarding 即首次启动时的配置向导界面。
核心流程：从安装到第一张超清竖构图
首次使用的完整链路如下，每一步都对应官方使用文档 docs/guide/getting-started.md 中的实际内容：
下载与版本选择
1提供两种版本：
2
3- **安装版（.exe）**：含安装向导，推荐大多数用户使用，支持卸载管理
4- **便携版（.zip）**：免安装，适合不想写入注册表的用户
5
6::: warning 便携版使用注意
7请**右键压缩包 > 全部解压缩**，将所有文件提取到一个单独的文件夹中，再运行其中的 `SpinningMomo.exe`。
8
9直接在压缩包内双击运行，或只单独提取 exe 文件，会导致程序缺少必要资源而无法正常使用。
10:::设计意图：便携版将 exe 与资源文件（含内嵌前端的静态资源）一并打包，单独提取 exe 会缺资源，因此文档用醒目警告强调"全部解压缩"。
系统要求与首次启动
1::: warning 运行环境
2- **操作系统**：Windows 10 1903 (Build 18362) 或更高版本（64 位）
3- **WebView2**：主界面依赖 [Microsoft WebView2 运行时](https://developer.microsoft.com/zh-cn/microsoft-edge/webview2/)
4 （**≥ 123.0.2420.47**），现代 Windows 通常已内置
5:::WebView2 是主界面（图库、设置等 Vue 界面）的承载容器；悬浮窗、托盘则是原生 Win32 UI，不依赖 WebView2。这就是"主界面依赖 WebView2，而悬浮窗不依赖"的结构性原因（对应后端 ui::* 模块）。
首次启动会触发 UAC 提示，必须点击"是"授予管理员权限——程序调整游戏窗口（窗口控制功能）必须使用此权限，这是拒绝 UAC 后功能失效的直接原因。
初始配置向导（Onboarding）
前端 web/src/features/onboarding/ 模块承载配置向导，共两步：
- 第 1 步：选择界面语言和主题（深色 / 浅色 / 跟随系统）
- 第 2 步：确认目标窗口标题（即被控制的《无限暖暖》窗口）
配置完成后悬浮窗自动出现。悬浮窗的显示切换快捷键为 Ctrl + `（键盘左上角反引号键，数字 1 左边）。
游戏内前置设置
在《无限暖暖》内需确认两项，这是超清截图链路成立的前提：
- 显示模式：选择 窗口模式
- 拍照 - 照片画质：选择 窗口分辨率
原理：游戏按"窗口分辨率"输出照片，因此把窗口临时切换到 8K 竖构图后，拍出的照片即为 8K 竖构图——这也是"突破原生限制"的实现方式。
拍摄第一张超清竖构图
11. 打开大喵相机进入摄影模式，找好场景和角色位置
22. 在悬浮窗中选择比例 **9:16** 与分辨率 **8K**（性能较低可选 4K / 6K）
33. 画面超出屏幕属正常现象，可在悬浮窗中开启 **叠加层** 或 **预览窗** 辅助预览
44. 按空格键拍照，完成后在悬浮窗中点击 **重置窗口** 恢复窗口大小要点：
- 分辨率档位：8K 为推荐值，性能较低可选 4K / 6K（后端
features::*中的 screenshot / window_control / letterbox 模块负责实际切换）。 - 超出屏幕是预期行为：物理显示器分辨率低于窗口分辨率时窗口会溢出屏幕，辅助手段是叠加层与预览窗。
- 收尾必须重置窗口：拍照后点击"重置窗口"恢复原始尺寸。
环境要求与配置项总览
本页作为入口页，不逐项罗列各功能的细粒度设置（属于 features/* 兄弟页面范围），这里汇总"开始使用前"层面的环境与配置项：
| 项目 | 类型 | 默认 / 要求 | 说明 |
|---|---|---|---|
| 操作系统 | 环境 | Windows 10 1903 (Build 18362)+，64 位 | 硬性要求 |
| WebView2 运行时 | 环境 | ≥ 123.0.2420.47，通常系统已内置 | 主界面（Vue 前端）依赖；悬浮窗等原生 UI 不依赖 |
| 管理员权限 | 环境 | 首次启动 UAC 授予 | 调整游戏窗口必须 |
| 界面语言 / 主题 | 配置（向导第 1 步） | — | 深色 / 浅色 / 跟随系统 |
| 目标窗口标题 | 配置（向导第 2 步） | — | 指定被控制的《无限暖暖》窗口；可随时通过悬浮窗右键菜单重新选择 |
| 悬浮窗显示切换 | 快捷键 | Ctrl + ` | 隐藏 / 显示悬浮窗 |
| 显示模式（游戏内） | 游戏设置 | 窗口模式 | 超清截图前提 |
| 照片画质（游戏内） | 游戏设置 | 窗口分辨率 | 超清截图前提 |
| 截图分辨率档位 | 功能选项 | 推荐 8K，可选 4K / 6K | 性能不足时降档 |
常见问题与故障排查（首次使用）
依据 docs/guide/getting-started.md 中明确给出的排查路径：
| 现象 | 原因与处理 |
|---|---|
| 便携版运行报缺少资源 | 未"全部解压缩"或只提取了 exe。右键压缩包 > 全部解压缩到独立文件夹后重试 |
| 无法调整游戏窗口 | 拒绝了 UAC 提示。重新以管理员权限运行 |
| 提示"未找到目标窗口" | 右键悬浮窗（或托盘图标），在菜单中重新选择目标窗口 |
| 主界面空白 / 无法加载 | WebView2 运行时缺失或版本低于 123.0.2420.47，安装/升级 WebView2 |
| 拍摄时画面超出屏幕 | 属正常现象；在悬浮窗开启叠加层或预览窗辅助预览 |
| 拍完后窗口未恢复 | 在悬浮窗中点击"重置窗口" |
更多进阶技巧与 FAQ 见 guide/tips 与 guide/faq 兄弟页面。
与其他目录面的关系
本仓库除用户向文档外还包含若干配套目录，它们与使用指南的关系如下（依据 AGENTS.md 的仓库面说明）：
android/— Android 采集守护进程 momo-capture，服务于 ADB 投屏功能链路docs/— VitePress 文档站（本页所属），独立于运行时打包playground/— 独立 Node/TypeScript 脚本，用于后端 HTTP/RPC 调试实验installer/— WiX 源文件，用于生成 MSI 与 bundle 安装包（对应"安装版 .exe"形态）tasks/— xmake 自定义任务（release、vs），属构建侧
相关链接
- 用户文档站：https://spin.infinitymomo.com
- README.md — 项目简介、下载地址与致谢
- AGENTS.md — 仓库工程结构与架构约定（双进程模型、AppState、RPC 端点组织）
- docs/guide/getting-started.md — 安装与运行原始文档（本页核心来源）
- 功能专项页：
features/window、features/screenshot、features/recording、features/gallery、features/hdr、features/adb、features/lan - 构建指南：
developer/architecture；法律与隐私：about/legal；致谢：about/credits