YZWater3/docs/superpowers/specs/2026-09-01-autostart-design.md

开机自启动功能设计

概述

为 YZWater3 添加跨平台（Windows/Linux/macOS）开机自启动功能。用户可在参数设置页面（ViewB）切换开关，开启后应用随系统启动自动运行。

设计决策

决策	选择	理由
启动行为	仍显示登录窗口	保持安全性，不自动登录
UI 位置	ViewB 参数设置页面	与其他配置项在一起
实现方案	单服务 + 平台检测	代码集中，改动少，符合项目风格
平台支持	Windows/Linux/macOS	项目已支持三平台

架构

数据流

用户切换开关 → ViewBViewModel.RunAtStartup setter
  → StartupService.SetAutoStart(value)     // 操作注册表/autostart/LaunchAgent
  → ConfigService.GetConfig().RunAtStartup = value  // 持久化到 JSON
  → ConfigService.SaveConfig()

涉及文件

层级	文件	改动
Model	src/YZWater.Core/Models/SystemConfig.cs	新增 RunAtStartup 属性
Service	src/YZWater.Core/Services/StartupService.cs	新建，跨平台开机自启动管理
ViewModel	src/YZWater.Core/ViewModels/ViewBViewModel.cs	新增 RunAtStartup 属性 + 保存逻辑
View	src/YZWater.Avalonia/Views/ViewB.axaml	新增 ToggleSwitch 控件
csproj	src/YZWater.Core/YZWater.Core.csproj	添加 Microsoft.Win32.Registry 包引用

详细设计

1. SystemConfig 模型

新增属性：

[ObservableProperty] private bool _runAtStartup;

2. StartupService

public static class StartupService
{
    private const string AppName = "YZWater";
    
    public static bool SetAutoStart(bool enabled)
    public static bool IsAutoStartEnabled()
    private static string GetExecutablePath()
    
    // 平台特定实现
    private static bool SetWindowsAutoStart(bool enabled)
    private static bool SetLinuxAutoStart(bool enabled)
    private static bool SetMacAutoStart(bool enabled)
    
    private static bool IsWindowsAutoStartEnabled()
    private static bool IsLinuxAutoStartEnabled()
    private static bool IsMacAutoStartEnabled()
}

各平台实现：

• Windows：操作注册表 HKCU\Software\Microsoft\Windows\CurrentVersion\Run
• Linux：创建/删除 ~/.config/autostart/yzwater.desktop
• macOS：创建/删除 ~/Library/LaunchAgents/com.yxwater.yzwater.plist

错误处理：

• 所有操作包裹 try-catch，失败记录日志并返回 false
• 使用 RuntimeInformation.IsOSPlatform() 判断平台
• 未知平台返回 false

3. ViewBViewModel

新增属性：

[ObservableProperty] private bool _runAtStartup;

属性变更处理：

partial void OnRunAtStartupChanged(bool value)
{
    var success = StartupService.SetAutoStart(value);
    if (!success)
    {
        _runAtStartup = !value;  // 回滚
        OnPropertyChanged(nameof(RunAtStartup));
    }
    else
    {
        var config = ConfigService.GetConfig();
        if (config != null)
        {
            config.RunAtStartup = value;
            ConfigService.SaveConfig();
        }
    }
}

加载配置：

private void LoadConfig()
{
    var config = ConfigService.GetConfig();
    if (config != null)
    {
        // ... 现有代码
        RunAtStartup = config.RunAtStartup;
    }
}

4. ViewB View

添加 ToggleSwitch：

<StackPanel Orientation="Horizontal" Spacing="10" Margin="0,10">
    <TextBlock Text="开机自启动：" VerticalAlignment="Center"/>
    <ToggleSwitch IsChecked="{Binding RunAtStartup}"/>
</StackPanel>

依赖

• Microsoft.Win32.Registry NuGet 包（仅 Windows 平台需要，通过条件引用）

测试要点

1. Windows：启用后检查注册表 HKCU\...\Run 中是否有 YZWater 键
2. Linux：启用后检查 ~/.config/autostart/yzwater.desktop 文件是否存在且内容正确
3. macOS：启用后检查 ~/Library/LaunchAgents/com.yxwater.yzwater.plist 文件
4. 跨平台：在非 Windows 平台上禁用时不应抛出异常
5. 配置持久化：重启应用后开关状态是否正确恢复
6. 错误处理：当注册表/文件操作失败时，UI 是否正确回滚