Wineclouds Studio多窗口管理器

██╗    ██╗██╗███╗   ██╗███████╗ ██████╗██╗      ██████╗ ██╗   ██╗██████╗ ███████╗
██║    ██║██║████╗  ██║██╔════╝██╔════╝██║     ██╔═══██╗██║   ██║██╔══██╗██╔════╝
██║ █╗ ██║██║██╔██╗ ██║█████╗  ██║     ██║     ██║   ██║██║   ██║██║  ██║███████╗
██║███╗██║██║██║╚██╗██║██╔══╝  ██║     ██║     ██║   ██║██║   ██║██║  ██║╚════██║
╚███╔███╔╝██║██║ ╚████║███████╗╚██████╗███████╗╚██████╔╝╚██████╔╝██████╔╝███████║
 ╚══╝╚══╝ ╚═╝╚═╝  ╚═══╝╚══════╝ ╚═════╝╚══════╝ ╚═════╝  ╚═════╝ ╚═════╝ ╚══════╝
                 The Windows workspace for multi-window workflows

Wineclouds Studio 是一个 WinUI 3 桌面应用，帮助用户在多开客户端、远程会话、构建任务或多显示器工作台中持续关注关键窗口和视觉状态。应用以管理员权限运行，以便稳定访问目标窗口并注册全局热键。

0.1.8

0.1.8 新增和调整了以下能力：

• 首页升级为六项能力概览，覆盖硬件信息、窗口管理、屏幕区域检测、设置中心与账号入口。
• 主窗口默认以 1440 × 900 居中启动，并在较小工作区中自动收缩。
• 主导航改用 Windows 11 Segoe Fluent Icons，明暗主题下保持统一的单色线框风格。
• 新增设置中心，可选择“极简白”“极夜黑”或跟随系统，并设置关闭主窗口时直接退出或最小化到系统托盘。
• 新增超级调色盘，首批提供极简白与极夜黑两套内置主题，其他配色入口暂时预留。
• 新增“关于 Wineclouds”，展示开发者“酒酒的云”、版本、项目与许可证信息。
• 新增 ASP.NET Core 10 邮箱账号 API，支持邮箱验证码注册、登录、Token 刷新、当前账号读取、退出和邮箱验证码重置密码；WinUI 客户端使用 Windows Credential Locker 保持登录。
• 邮箱推送系统支持 SMTP（MailKit）和腾讯云 SES HTTPS API 双通道，验证码模板变量化发送，带速率限制和重放防护。
• 新增会员激活码兑换系统，支持多等级订阅（免费/护卫舰/驱逐舰/巡洋舰）与管理员后台生成激活码。
• 调整窗口管理器的进程列表密度，并统一监控和检测模块的启动／停止按钮样式。

能力概览

适用场景

• 多开应用：将关键客户端以实时缩略图固定在桌面上，通过点击或热键快速切换。
• 设备盘点：快速查看当前电脑的 Windows 版本与主要硬件配置，便于排查和记录。
• 状态监看：监测远程桌面、构建任务、下载进度或告警区域的颜色变化。
• 多显示器协作：在整个虚拟桌面范围内选择检测区域，持续关注副屏状态。
• 个性化工作台：在极简白、极夜黑或系统主题之间切换，并按习惯配置关闭与托盘行为。

架构

flowchart TB
    App[App / MainWindow\nWinUI 3 导航壳] --> H[首页]
    App --> I[硬件信息]
    App --> A[窗口管理器]
    App --> B[屏幕区域检测]
    App --> F[软件更新]
    App --> S[设置中心]
    App --> U[登录]
    App --> D[预留模块 D-E]

    H --> H1[逐字符 Logo 动画]
    I --> I1[WMI 硬件与系统查询]
    I --> I2[运行时间与手动刷新]
    A --> A1[DWM Thumbnail]
    A --> A2[全局热键]
    A --> A3[窗口配置存储]
    B --> B1[屏幕捕获]
    B --> B2[颜色分析与状态机]
    B --> B3[MP3 循环播放]
    B --> B4[检测配置存储]
    F --> F1[GitHub Release 清单]
    F --> F2[安装包下载与 SHA-256 校验]
    F --> F3[退出后启动 NSIS]
    S --> S1[主题与超级调色盘]
    S --> S2[关闭行为配置]
    S --> S3[系统托盘]
    U --> U1[登录／注册／找回密码界面]
    U --> U2[本地输入校验]
    App --> L[共享日志]

核心代码均位于 src/WinecloudsStudio：页面负责交互与生命周期，服务层封装 Windows API 和业务能力，Core 保持屏幕颜色分析与状态机的独立性，Shared/Logging 提供全局日志能力。

快速使用

硬件信息

1. 打开“硬件信息”，应用会在后台读取本机 Windows 与主要硬件配置。
2. 顶部卡片显示机型、系统版本和实时运行时间，下方清单展示各类设备详情。
3. 硬件发生变化或需要重新查询时，点击“刷新信息”。
4. 页面只读取本机信息，不修改 BIOS、驱动、注册表或硬件配置。

窗口管理器

1. 在“窗口管理器”中刷新并选择要关注的窗口。
2. 设置缩略图尺寸、透明度、置顶、标题、边框、位置锁定与网格吸附；这些显示设置可在监控期间动态调整。
3. 创建窗口分组并配置前进、后退热键。
4. 按需启用“隐藏当前活动窗口的缩略图”或“切换后最小化上一个窗口”。
5. 开始监控；可点击缩略图激活窗口，或用分组热键循环切换。

屏幕区域检测

1. 打开“屏幕区域检测”，框选需要监控的区域。
2. 选择或拾取目标颜色，并设置容差、最少目标像素、最小连通面积与确认帧数。
3. 选择本地 MP3 文件作为提醒声音。
4. 开始检测；目标颜色稳定出现时循环提醒，稳定消失后自动停止并重新布防。

软件更新

1. 打开“软件更新”，程序会自动检查 GitHub 上的最新正式 Release。
2. 有新版本时查看版本说明和安装包信息，然后点击“下载并安装”。
3. 程序会把安装包写入受保护的 ProgramData 暂存目录，并同时校验 update.json 中的 SHA-256；主程序退出后，辅助进程还会复核路径、ACL、摘要、Authenticode 有效性及构建时固定的发布证书。
4. Release 标签、项目版本和安装包文件名必须使用相同版本，例如 v0.1.8、0.1.8 和 WinecloudsStudio-Setup-0.1.8-win-x64.exe。

设置、主题与托盘

1. 打开“设置”，在“外观与行为”中选择极简白、极夜黑或跟随 Windows 系统主题。
2. 在“超级调色盘”中查看实时主题预览，并选择当前开放的内置配色。
3. 选择关闭主窗口时“直接退出应用”或“最小化到系统托盘”。
4. 启用托盘模式后，可双击托盘图标恢复窗口，或通过右键菜单退出。

Wineclouds 账号

Wineclouds Studio 内置完整的邮箱账号系统，由 ASP.NET Core Identity 提供后端支持。

账号功能概览：

邮箱推送系统：

项目提供双通道验证码邮件发送方案：

验证码安全策略：

邮件模板：

注册验证码和密码重置验证码的腾讯云 SES 模板分别位于：

• docs/email-templates/tencent-ses-registration-code.html
• docs/email-templates/tencent-ses-password-reset-code.html

模板变量为 {{code}}（验证码）和 {{minutes}}（有效期分钟数）。

Ubuntu + Docker 的完整生产部署步骤见 deploy/ubuntu-docker/README.md。该方案使用 api.wineclouds.cn、PostgreSQL、Docker Secret 和宿主机 Nginx，不改变现有 wineclouds.cn 网站。

1. 当前生产方案使用腾讯云 SES HTTPS API。先创建并审核注册验证码模板，然后通过服务器 Secret 配置以下值；不要把 SecretKey 提交到仓库：

$env:Email__Provider = “TencentSesApi”
$env:Email__TencentSes__Region = “ap-guangzhou”
$env:Email__TencentSes__SecretId = “CAM 子用户 SecretId”
$env:Email__TencentSes__SecretKey = “CAM 子用户 SecretKey”
$env:Email__TencentSes__FromAddress = “verify@notify.wineclouds.cn”
$env:Email__TencentSes__FromName = “Wineclouds”
$env:Email__TencentSes__RegistrationTemplateId = “55394”
$env:Email__TencentSes__PasswordResetTemplateId = “密码重置模板 ID”
$env:EmailVerification__Pepper = “replace-with-a-long-random-server-secret”

可上传到腾讯云的注册和密码重置模板变量均为 {{code}} 和 {{minutes}}。个人实名认证用户通过 API 的 HTTPS 443 发信，不需要 SMTP 权限，也不受云服务器 TCP 25 封禁影响。

企业账号或已有 SMTP 权限时，也可以将提供程序切换为 Smtp：

$env:Email__Provider = “Smtp”
$env:Email__Smtp__Host = “gz-smtp.qcloudmail.com” # 广州区
$env:Email__Smtp__Port = “465”                    # 隐式 TLS
$env:Email__Smtp__SecurityMode = “SslOnConnect”
$env:Email__Smtp__UserName = “verify@account.example.com”
$env:Email__Smtp__Password = “控制台生成的 SMTP 密码”
$env:Email__Smtp__FromAddress = “verify@account.example.com”

腾讯云还提供香港区 smtp.qcloudmail.com 和国际站 sg-smtp.qcloudmail.com。根据腾讯云 2026 年产品公告，2026 年 3 月 2 日后新开通邮件推送的个人实名认证用户不再提供 SMTP 发信权限，此类账号应改用腾讯云 SES HTTPS API，或升级企业认证。参见腾讯云 SMTP 服务地址和邮件推送产品动态。

腾讯云 CVM 默认封禁对外 TCP 25 不影响 SMTP 备用配置：API 服务器只会主动连接腾讯云 SES 的 465 端口，不监听或使用 25 端口。若服务商要求 587，则把 Port 改为 587，同时把 SecurityMode 改为 StartTls。

会员激活码系统：

管理员可通过 tools/GenerateMembershipCode.ps1 生成激活码，指定套餐等级和有效期：

$headers = @{ “Authorization” = “Bearer $adminAccessToken”; “Content-Type” = “application/json” }
$body = @{ planId = “frigate”; durationDays = 365; maxRedemptions = 1; note = “年度会员” } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri “https://api.wineclouds.cn/v1/admin/codes” -Headers $headers -Body $body

用户在客户端”登录”页面登录后，输入激活码即可兑换升级。

2. 在同一个 PowerShell 窗口启动账号 API：

dotnet run --project .\src\WinecloudsStudio.Api\WinecloudsStudio.Api.csproj --launch-profile http

3. 启动 Wineclouds Studio，打开”登录 → 注册”，填写邮箱并发送验证码。输入邮件中的 6 位验证码，以及至少 8 位、包含小写字母与数字的密码。
4. 验证码 5 分钟有效，同一邮箱 60 秒内不能重复发送、每天最多发送 10 次，连续输错 5 次后失效。
5. 注册成功后会自动登录；Refresh Token 保存在 Windows Credential Locker，重新启动客户端时会自动恢复账号。
6. 默认账号 API 地址为 https://api.wineclouds.cn/。本地开发时可通过 WINECLOUDS_ACCOUNT_API_URL=http://127.0.0.1:5047/ 环境变量覆盖。
7. 找回密码使用单独的六位验证码和腾讯 SES 模板；重置成功后回到登录页使用新密码。微信登录尚未开放。

运行要求

• Windows 10 1809（17763）或更高版本，64 位系统。
• 应用启动时会请求管理员权限；若取消 UAC 提示，应用将退出。
• 使用窗口管理功能时，目标应用也应以可访问的同等或更低权限运行。
• 声音提醒仅支持本地 MP3 文件。

从源码构建

开发环境：

• .NET 10 SDK
• Windows App SDK（通过 NuGet 还原）
• NSIS 3.x（仅创建安装包时需要）

dotnet restore .\WinecloudsStudio.slnx
dotnet build .\WinecloudsStudio.slnx --configuration Release --property:Platform=x64
dotnet run --project .\src\WinecloudsStudio\WinecloudsStudio.csproj

创建自包含的 x64 安装包：

.\scripts\New-Installer.ps1 -Configuration Release

安装包输出到 artifacts\installer\output\，发布载荷输出到 artifacts\installer\publish-win-x64\。两者都是可再生产物，不应提交到版本库。

发布更新版本

仓库包含 .github/workflows/release.yml。发布正式更新时：

1. 创建带必需审核人的 GitHub Environment release-signing，在其中配置 WINDOWS_SIGNING_CERTIFICATE_BASE64（受信任代码签名 PFX 的 Base64）和 WINDOWS_SIGNING_CERTIFICATE_PASSWORD；再设置 Repository Variable UPDATE_SIGNER_CERTIFICATE_SHA256 为叶证书 DER 的 SHA-256 指纹。构建与签名在不同 runner/job 中完成，签名 job 会核对 PFX 与固定指纹，缺少或不一致时安全失败。证书轮换时，可暂时设置 NEXT_UPDATE_SIGNER_CERTIFICATE_SHA256，让过渡版本同时固定当前和下一张证书。
2. 修改 src/WinecloudsStudio/WinecloudsStudio.csproj 中的 Version。
3. 提交并推送代码，确认 main 构建正常。
4. 创建与项目版本完全一致的标签，例如：

git tag v0.1.8
git push origin v0.1.8

标签推送后，GitHub Actions 会自动：

• 配置 .NET 10 和 NSIS。
• 生成 Windows x64 自包含安装器。
• 使用 SHA-256 和 RFC 3161 时间戳签署安装器，并验证 Authenticode 信任链与签名证书。
• 生成对应的 .sha256 校验文件。
• 创建 GitHub Release，或覆盖同一标签下的旧安装包资产。
• 生成并上传包含版本、下载地址、文件大小和 SHA-256 的 update.json。

软件更新模块通过 releases/latest/download/update.json 获取最新正式版，不消耗 GitHub REST API 配额。清单中的 Release 标签、项目版本、安装包文件名和 SHA-256 必须相互一致；即使 GitHub Release 中的安装包与摘要同时被替换，客户端也会因为 Authenticode 证书指纹不匹配而拒绝执行。签名证书轮换前，应先用旧证书发布一个同时信任新证书的过渡版本。

项目结构

WinecloudsStudio.slnx
├── src/WinecloudsStudio/
│   ├── App.xaml(.cs)                 # 应用启动、提权与关闭生命周期
│   ├── MainWindow.xaml(.cs)          # 导航壳与模块页面缓存
│   ├── Assets/                       # 应用图标和资源
│   ├── Modules/
│   │   ├── Home/                     # 逐字符 Logo 与工作流概览首页
│   │   ├── SystemInformation/        # WMI 硬件读取、运行时间与信息页面
│   │   ├── WindowManager/            # 缩略图、热键、窗口配置与 Windows API 互操作
│   │   ├── ScreenDetection/          # 捕获、颜色识别、状态机、提醒与配置
│   │   ├── Settings/                 # 主题、调色盘、托盘关闭行为与关于页面
│   │   ├── Login/                    # 账号交互界面与本地输入校验
│   │   ├── Reserved/                 # 软件更新及预留模块 D-E
│   │   └── Navigation/               # 未实现模块的兜底页面
│   └── Shared/Logging/               # 异步文件日志
├── src/WinecloudsStudio.Api/         # ASP.NET Core Identity 邮箱账号 API
│   ├── Services/                      # EmailRegistrationService、PasswordResetService、
│   │                                  # SmtpEmailSender、TencentSesRegistrationEmailSender
│   └── Models/                        # ApplicationUser、MembershipPlan、MembershipSubscription
├── docs/                              # 账号、会员与邮箱模板技术文档
├── installer/                        # NSIS 安装器定义
├── scripts/New-Installer.ps1         # 发布与打包脚本
└── README.md

配置、日志与故障排查

应用数据位于 %LOCALAPPDATA%\WinecloudsStudio\：

开发账号数据库位于 %LOCALAPPDATA%\WinecloudsStudio\AccountServer\accounts.db。验证码只保存加盐哈希，不保存明文。SQLite 只用于本地开发；Ubuntu + Docker 生产部署使用独立 PostgreSQL 数据库。

日志对未处理异常和未观察任务异常进行记录；错误级别消息会立即落盘，普通消息由后台线程批量刷新。日志默认保留最近 7 天，适合在启动失败、热键注册失败、窗口操作失败或检测异常时提供排查依据。

常见问题：

• 无法激活目标窗口：确认 Wineclouds Studio 已以管理员权限运行，并检查目标窗口未被更高权限进程保护。
• 热键无法注册：该组合键可能已被其他程序占用；更换为未占用的键位后重试。
• 颜色检测误报：提高最少目标像素数或最小连通面积，适当收紧颜色容差，并增加确认帧数。
• 没有声音提醒：确认选择的是可读取的本地 MP3 文件，且 Windows 当前音频输出可用。
• 关闭窗口后程序仍在运行：在设置中选择了“最小化到系统托盘”；可从托盘菜单退出，或改回“直接退出应用”。

发布约定

• 仅提交源码、构建脚本、安装器定义和必要的资源文件。
• bin/、obj/、.vs/、artifacts/ 等构建缓存和发布产物必须忽略。
• 配置、日志、密钥和其他敏感本地文件不得提交；若确有必要，应提供脱敏的 .example 示例文件。
• 安装包使用 LZMA 固实压缩，并以自包含方式发布，避免依赖用户机器上的共享运行时。

许可证

MIT License