Skip to content

Latest commit

 

History

History
1060 lines (856 loc) · 112 KB

commands.md

File metadata and controls

1060 lines (856 loc) · 112 KB

Tauri 命令层(IPC 入口)— 文件功能参考

逐文件精读源码生成。行号基于当前工作区版本,仅用于快速定位。 覆盖范围:src-tauri/src/commands/ 下 18 个命令文件(另有 mod.rs 共 19 个 .rs),当前参考表收录 139 个不同命令名;源码含 143 处命令注解(capture_screen、finish_screen_pick、download_android_apk、run_installer、save_tab_snapshot 各有 cfg 门控的两个版本,按名去重后为 138)。另有 APK 安装插件命令,见 apk-installer 插件。注册入口见 src-tauri/src/lib.rs 的 generate_handler!。

平台门控(Android/iOS):命令名集合在桌面与移动端完全一致(generate_handler! 不按平台裁剪),差异只在实现——桌面专属能力在移动端是返回明确错误的 stub,共 5 组:launcher_browse_folder / pick_steam_icon / pick_steam_icon_source(rfd 对话框)、check_update_endpoint / install_update_endpoint(updater 插件)、capture_screen / finish_screen_pick(GDI 取色)、save_tab_snapshot(PrintWindow 快照)、minimize_window / toggle_maximize_window(窗口化语义,移动端 no-op)。完整差异表见 docs/development.md §2.1。

命令速查表

命令名 定义位置 参数 返回 内部调用
get_accounts commands/account.rs:16 state: State<Arc<Mutex<AccountService>>> Result<Vec<AccountInfo>, String> ConfigService::get_all、AccountService::get_cached_accounts / AccountService::get_accounts
get_skland_accounts commands/account.rs:65 state: State<Arc<Mutex<AccountService>>> Result<Vec<SklandAccountInfo>, String> AccountService::get_skland_accounts
save_skland_account commands/account.rs:74 state、cred: String、token: String、user_id: String Result<bool, String> AccountService::save_skland_account
get_skland_account_roles commands/account.rs:89 state、user_id: String Result<AccountLoginResult, String> AccountService::get_skland_account_roles
get_skland_user_info commands/account.rs:102 state、user_id: String Result<SklandUserInfo, String> AccountService::get_skland_user_info
get_skland_user_info_by_cred commands/account.rs:129 state、cred: String、token: String Result<SklandUserInfo, String> AccountService::get_skland_user_info_by_cred
get_skland_games commands/account.rs:115 state、user_id: String、force: Option<bool> Result<Vec<SklandGameInfo>, String> AccountService::get_skland_games
add_account commands/account.rs:143 state、login_request: LoginRequest Result<AccountLoginResult, String> AccountService::add_account
logout_account commands/account.rs state、account_id: String、keep_device_token: Option<bool> Result<bool, String> AccountService::logout_account(只解绑单个角色,保留父账户与凭据)
delete_skland_account commands/account.rs:171 state、user_id: String Result<bool, String> AccountService::delete_skland_account(彻底删除父账户 + 全部角色 + 全部凭据)
batch_logout commands/account.rs:169 state、account_ids: Vec<String> Result<bool, String> AccountService::batch_logout
refresh_accounts commands/account.rs:179 state Result<AccountRefreshResult, String> AccountService::refresh_accounts
send_verification_code commands/account.rs:188 state、request: SendCodeRequest Result<bool, String> AccountService::send_verification_code
add_account_by_code commands/account.rs:201 state、login_request: CodeLoginRequest Result<AccountLoginResult, String> AccountService::add_account_by_code
gen_scan_login commands/account.rs:214 state Result<ScanLoginInfo, String> AccountService::gen_scan_login
scan_status commands/account.rs:223 state、scan_id: String Result<ScanStatus, String> AccountService::scan_status
add_account_by_scan commands/account.rs:236 state、scan_code: String、expected_user_id: Option<String> Result<AccountLoginResult, String> AccountService::add_account_by_scan
save_selected_roles commands/account.rs:250 state、cred、token、user_id、selected_roles: Vec<RoleDisplayInfo> Result<Vec<AccountInfo>, String> AccountService::save_selected_roles
get_selected_account commands/account.rs:266 state Result<Option<String>, String> AccountService::get_config_service → ConfigService::get("selected_account_id")
set_selected_account commands/account.rs:277 state、account_id: String Result<bool, String> ConfigService::set("selected_account_id", …)
check_and_refresh_cred commands/account.rs:295 state、user_id: String Result<Option<(String, String)>, String> AccountService::check_and_refresh_user_cred
authorize_role_u8token commands/account.rs:325 state、role_id: String Result<RoleU8AuthResult, String> AccountService::authorize_role_u8token
revoke_role_u8token commands/account.rs:338 state、role_id: String Result<bool, String> AccountService::revoke_role_u8token
set_lazy_load_enabled commands/account.rs:308 state、enabled: bool Result<bool, String> AccountService::set_lazy_load_enabled
is_lazy_load_enabled commands/account.rs:322 state Result<bool, String> AccountService::is_lazy_load_enabled
set_current_role_id commands/account.rs:331 state、role_id: Option<String> Result<bool, String> AccountService::set_current_role_id
query_role_data commands/account.rs:353 state、role_id、api_name、paths: Vec<String> Result<serde_json::Value, String> AccountService::query_role_data
get_attendance commands/attendance.rs:60 state: State<Arc<Mutex<AccountService>>>、role_id: String Result<serde_json::Value, String> 本地 lookup_cred_token、AccountService::check_and_refresh_user_cred、SklandService::call_skland_api(GET)、AvatarCacheService::get_or_download_image(终末地签到,靠 sk-game-role 头寻址)
do_attendance commands/attendance.rs:182 state、role_id: String Result<serde_json::Value, String> 本地 lookup_cred_token、AccountService::check_and_refresh_user_cred、SklandService::call_skland_api(POST)(终末地签到)
get_arknights_player_info commands/arknights.rs:24 state、role_id: String、force: Option<bool> Result<serde_json::Value, String> AccountService::get_arknights_player_info → resolve_arknights_target(roleId → userId + bindingUid)+ arknights_credentials(按需刷新 cred)→ ArknightsService::refresh_player_info(GET /api/v1/game/player/info?uid=)。force=false 时先用缓存(内存 → <app_data>/arknights/player_info_{uid}.json)
get_arknights_cultivate commands/arknights.rs:40 state、role_id: String Result<serde_json::Value, String> AccountService::get_arknights_cultivate → ArknightsService::fetch_cultivate(GET /api/v1/game/cultivate/player?uid=)。干员养成 player/info 已给,唯一增量是仓库 items
get_arknights_attendance commands/arknights.rs:60 state、role_id: String Result<serde_json::Value, String> AccountService::get_arknights_attendance → ArknightsService::attendance_status(GET /api/v1/game/attendance?gameId=1&uid=)。返回体在原始字段外多三项后端算好的 hasToday / todayIndex / tomorrowIndex
do_batch_attendance commands/arknights.rs:118 state、role_ids: Vec<String> Result<Vec<BatchAttendanceItem>, String> 批量签到:逐个调 AccountService::do_attendance_for_role(其内部按角色 app 自动分流明日方舟/终末地)。串行执行、每角色独立持锁;单个失败不打断整批,逐条返回 {roleId, ok, alreadySigned, error}
do_arknights_attendance commands/arknights.rs:81 state、role_id: String Result<serde_json::Value, String> AccountService::do_arknights_attendance → ArknightsService::do_attendance(POST /api/v1/game/attendance,body {gameId: 1, uid})。返回 ArknightsAttendanceResult(awards[] + tomorrowAwards[],全补好 resource.icon);今天已签到时 alreadySigned = true + 空 awards,不报错
capture_start commands/capture.rs:3 无 Result<CaptureStatus, String> utils::capture::start
capture_stop commands/capture.rs:8 无 Result<CaptureStatus, String> utils::capture::stop
capture_status commands/capture.rs:13 无 Result<CaptureStatus, String> utils::capture::status
capture_list_sessions commands/capture.rs:18 无 Result<Vec<CaptureSessionMeta>, String> utils::capture::list_sessions
capture_read_entries commands/capture.rs:23 id: String、offset: u64、limit: u64 Result<CapturePage, String> utils::capture::read_entries
capture_delete_session commands/capture.rs:32 id: String Result<(), String> utils::capture::delete_session
capture_dir commands/capture.rs:37 无 Result<String, String> utils::capture::capture_root + fs::create_dir_all
get_card_settings commands/card_config.rs:9 state、card_id: String Result<Value, String> ConfigService::get("card_settings.{card_id}")
save_card_settings commands/card_config.rs:26 state、card_id: String、settings: Value Result<bool, String> ConfigService::get + 对象浅合并 + ConfigService::set
remove_card_settings commands/card_config.rs:66 state、card_id: String Result<bool, String> ConfigService::remove("card_settings.{card_id}")
capture_screen commands/color_picker.rs:36 window: WebviewWindow Result<ScreenCapture, String> Windows:window 控制 + GDI 截屏;非 Windows:返回仅支持 Windows 的错误
finish_screen_pick commands/color_picker.rs:56 window: WebviewWindow ()(无返回) Windows:退出全屏并聚焦;非 Windows:空实现
get_config commands/config.rs:9 state: State<Arc<Mutex<ConfigService>>>、key: String Option<Value> ConfigService::get
get_game_launch_command commands/startup.rs:301 config_service: State<Arc<Mutex<ConfigService>>>、game: Option<String> Result<String, String> 校验/更新 main_exe_path 并返回含 --silent --launch-game 的带引号命令
set_config commands/config.rs:47 state、key: String、value: Value Result<(), String> 拒绝写机密键(secret_registry::has_secret_fields);否则 ConfigService::set;当 key == "proxy_config" 时额外 utils::http_client::set_global_proxy_config(Some(value))(后续 HTTP 请求即时生效)
remove_config commands/config.rs:64 state、key: String bool ConfigService::remove(同时清理凭据库条目)
get_all_configs commands/config.rs:71 state HashMap<String, Value> ConfigService::get_all_public —— 机密字段被逐字段剔除,不含凭据
get_secret_storage_status commands/config.rs:82 state Result<SecretStorageStatus, String> ConfigService::secret_backend + secrets_degraded → {backend, degraded}
get_proxy_config commands/config.rs:17 state Option<Value> ConfigService::get_proxy_config;前端未直接调用(改用 get_proxy_settings)
set_proxy_config commands/config.rs:24 state、config: Value Result<(), String> ConfigService::set_proxy_config + 刷新全局代理缓存;前端未直接调用(改用 save_proxy_settings)
remove_proxy_config commands/config.rs:38 state Result<bool, String> ConfigService::remove_proxy_config 并把全局代理缓存置空;前端未直接调用(改用 clear_proxy_settings)
get_proxy_settings commands/proxy.rs:56 state: State<Arc<Mutex<ConfigService>>> Value ConfigService::get_proxy_config,缺省返回空配置 {enabled:false,type:"http",host:"",port:8080,username:"",password:""}
save_proxy_settings commands/proxy.rs:66 state、config: Value Result<Value, String> ConfigService::set_proxy_config + utils::http_client::set_global_proxy_config(Some(config)),返回保存后的配置
clear_proxy_settings commands/proxy.rs:80 state bool ConfigService::remove_proxy_config + 全局代理缓存置空
read_system_proxy commands/proxy.rs:14 无 SystemProxyInfo utils::proxy::read_system_proxy:Windows 读 HKCU\...\Internet Settings(ProxyEnable/ProxyServer/AutoConfigURL),失败回退 HTTP(S)_PROXY/ALL_PROXY 环境变量
test_proxy_connection commands/proxy.rs:30 state、config: Option<Value>、url: Option<String> Result<TestConnectionResult, String> 取传入配置,缺省回退已保存的 proxy_config;utils::proxy::test_connection(15s 超时,默认探测 https://www.gstatic.com/generate_204,返回 {status, duration_ms})
get_gacha_pool_meta commands/gacha.rs:147 account_state、gacha_state: State<Arc<GachaService>>、role_id: String Result<serde_json::Value, String> lookup_role_owner + fresh_u8token、GachaService::get_pool_meta。仅终末地:对明日方舟角色直接返回 Err(改用 get_arknights_gacha_categories)
sync_gacha_records commands/gacha.rs:194 account_state、gacha_state、arknights_gacha_state: State<Arc<ArknightsGachaService>>、role_id: String Result<serde_json::Value, String> lookup_role_owner + fresh_u8token,然后按 owner.is_arknights() 分流:明日方舟 → ArknightsGachaService::sync_records(binding_uid, token);终末地 → GachaService::sync_records(user_id, server_id, token)
get_saved_gacha_records commands/gacha.rs:236 account_state、gacha_state、arknights_gacha_state、role_id: String Result<serde_json::Value, String> 按游戏分流读档(ArknightsGachaService::load_records_or_empty(binding_uid) / GachaService::load_records_or_empty(user_id, server_id)),不联网
sync_weapon_gacha_records commands/gacha.rs:275 account_state、gacha_state、role_id: String Result<serde_json::Value, String> lookup_role_owner + fresh_u8token、GachaService::sync_weapon_records。仅终末地:明日方舟无武器寻访,直接返回空 GachaSyncResult(不发请求、不落盘)
get_saved_weapon_gacha_records commands/gacha.rs:334 account_state、gacha_state、role_id: String Result<serde_json::Value, String> GachaService::load_weapon_records_or_empty(不联网)。仅终末地:明日方舟返回空 SavedWeaponGachaData
get_arknights_gacha_categories commands/gacha.rs:395 account_state、arknights_gacha_state: State<Arc<ArknightsGachaService>>、role_id: String Result<serde_json::Value, String> lookup_role_owner + fresh_u8token、ArknightsGachaService::get_categories(GET /api/gacha/cate)。仅明日方舟:对终末地角色返回 Err。空分类列表已被后端转成鉴权错误
resolve_gacha_avatar_map commands/gacha.rs:564 account_state、gacha_state、arknights_gacha_state、role_id: String Result<serde_json::Value, String> 终末地:GachaService::{load_records_or_empty, load_weapon_records_or_empty, load_avatar_map, save_avatar_map, load_total_catalog, save_total_catalog, total_catalog_is_stale}、AccountService::{check_and_refresh_user_cred, query_role_data}、本地 resolve_missing_from_catalog。明日方舟:直接按 CDN 规则拼 web.hycdn.cn/arknights/game/assets/char/avatar/{charId}.png,不联网、不读 wiki_catalog(属终末地目录,不含明日方舟干员)
get_gacha_record_stats commands/gacha.rs:758 account_state、gacha_state、arknights_gacha_state、role_id: String Result<serde_json::Value, String> 按游戏分流读档后 GachaService::{group_records_by_pool, count_by_rarity, count_by_char}(统计函数与游戏无关)
read_image_file commands/image.rs:18 path: String Result<tauri::ipc::Response, String>(原始字节) fs::read
get_image_cache_dir commands/image.rs:16 无 Result<String, String> utils::paths::image_cache_dir
download_image commands/image.rs:29 url: String、cache_dir: String、sub_dir: String Result<String, String> resolve_url_subdir/all_sub_dir_names、本地 extract_filename_from_url、capture::send(reqwest GET,带 Referer)
get_backgrounds_dir commands/image.rs:141 无 Result<String, String> utils::paths::backgrounds_dir
save_background_image commands/image.rs:152 data: String(base64/dataURL) Result<String, String> paths::backgrounds_dir、清空目录、base64 解码、写 bg.webp
delete_background_image commands/image.rs:190 无 Result<(), String> paths::backgrounds_dir + 删除目录下全部文件
launcher_get_process_read_bytes commands/launcher.rs:47 无 Result<u64, String> Win32 GetProcessIoCounters(非 Windows 返回 0)
launcher_check_status commands/launcher.rs:65 service: State<Arc<GameLauncherService>>、channel: String、install_path: String Result<GameStatus, String> 本地 parse_channel、GameLauncherService::check_status;只读命令,下载期间不再排队等锁
launcher_install_or_update commands/launcher.rs:86 app: AppHandle、service、channel、install_path、max_concurrent: Option<usize>(默认 8)、resume: Option<bool>(默认 true) Result<LauncherResult, String> GameLauncherService::install_or_update,按线程数并发下载、可断点续传,进度回调 emit launcher-progress
launcher_verify_and_repair commands/launcher.rs:150 app、service、channel、install_path、max_concurrent: Option<usize>、quick: Option<bool>、resume: Option<bool>(默认 true) Result<LauncherResult, String> GameLauncherService::verify_and_repair,emit launcher-progress;失败时额外发出 error 终态事件
launcher_get_remote_version commands/launcher.rs:210 service、channel Result<RemotePackage, String> GameLauncherService::get_latest_package
launcher_preload_download commands/launcher.rs:221 app、service、channel、install_path、max_concurrent: Option<usize>(默认 8)、resume: Option<bool>(默认 true) Result<LauncherResult, String> GameLauncherService::preload_download(独立预下载传入 None,由服务获取包信息),emit launcher-progress
launcher_install_preload commands/launcher.rs:266 app、service、channel、install_path、max_concurrent: Option<usize>(默认 8)、resume: Option<bool>(默认 true) Result<LauncherResult, String> GameLauncherService::install_preload:校验并下载分卷、解密安装,emit launcher-progress;前端安装成功后另行触发快速校验
launcher_get_payload_state commands/launcher.rs:310 service、channel Result<Option<PayloadState>, String> GameLauncherService::get_payload_state
launcher_cancel_download commands/launcher.rs:321 install_path: Option<String> Result<(), String> 带非空路径时先 request_cancel_cleanup(记录删除意图)再 cancel_download/cleanup_staging_files;不带路径仅置取消标志、保留缓存
launcher_has_download_cache commands/launcher.rs:340 install_path: String Result<bool, String> game_launcher_service::has_download_cache
launcher_reset_download_cancel commands/launcher.rs:348 无 Result<(), String> game_launcher_service::reset_download_cancel
launcher_cancel_switch commands/launcher.rs:354 无 Result<(), String> game_launcher_service::cancel_switch
launcher_cancel_all commands/launcher.rs:360 无 Result<(), String> game_launcher_service::cancel_download + cancel_switch
launcher_decrypt_file commands/launcher.rs:367 file_path: String Result<String, String> utils::hg_crypto::decrypt_file_to_string
launcher_get_banners commands/launcher.rs:373 service、channel Result<Vec<BannerItem>, String> GameLauncherService::get_banners
launcher_get_announcements commands/launcher.rs:384 service、channel Result<Vec<AnnouncementItem>, String> GameLauncherService::get_announcements
launcher_get_notice_content commands/launcher.rs:395 service、channel Result<LauncherNoticeContent, String> GameLauncherService::get_notice_content(Banner + 公告 + 右侧栏 sidebars 合并内容)
launcher_get_background_image commands/launcher.rs:406 service、channel Result<Option<BackgroundMedia>, String> GameLauncherService::get_background_image
launcher_start_game commands/launcher.rs:461 config_service: State<Arc<StdMutex<ConfigService>>>、install_path: String、channel: String、dx11: Option<bool>(省略时读配置 launcher_dx11,默认 false) Result<LauncherResult, String> parse_channel、process::terminate_processes(原生快照清理同名残留)、official_launcher::launch_via_official_parent(已提权时本进程直接伪造官方父进程;否则提权 helper)/ 回退 direct_launch → shell_execute_game;DX11 开启时给游戏参数追加 -force-d3d11;Steam 启动且应用未提权时在 warning 返回 overlay_unavailable
launcher_browse_folder commands/launcher.rs:658 无 Result<Option<String>, String> 桌面:rfd::FileDialog::pick_folder;移动端按 #[cfg(not(desktop))] 返回「Folder selection is not available on this platform」(rfd 只在桌面目标编译)
launcher_get_disk_space commands/launcher.rs:675 path: String Result<DiskSpace, String> 调用 powershell Get-PSDrive 子进程解析 used/free
launcher_scan_install_dir commands/launcher.rs:734 service、channel、install_path Result<FileScanResult, String> GameLauncherService::scan_install_dir
launcher_detect_channel commands/launcher.rs:770 install_path: String Result<Option<String>, String> 按游戏分派:终末地用特征 DLL(hgsdk.dll / PCGameSDK.dll / gfsdk.dll 等),明日方舟读 config.ini 的 channel;纯本地不联网
launcher_check_executable commands/launcher.rs:845 install_path: String、channel: String Result<bool, String> parse_channel + GameChannel::executable_name + Path::exists
launcher_check_game_running commands/launcher.rs:853 channel: String Result<bool, String> parse_channel + utils::process::is_process_running(同名进程需有顶层窗口或在 90 秒启动宽限内,排除无窗口挂起残留);游戏面板每 3 秒轮询
launcher_get_game_playtime commands/launcher.rs:860 无 GamePlaytime(同步返回) utils::game_playtime::snapshot(累计总时长 + 实时会话 + 运行态)
launcher_kill_game commands/launcher.rs:873 channel: String Result<bool, String>(失败为 <token>: <detail>) spawn_blocking + process::exists_once(单次快照预检)→ official_launcher::kill_game_process:就地 process::terminate_processes(原生快照 + TerminateProcess,含子进程树),AccessDenied/StillRunning 才 runas 重启自身跑 --endfield-kill-helper(提权终止)
launcher_switch_channel commands/launcher.rs:912 service、from_channel、to_channel、install_path、app: AppHandle Result<String, String> GameLauncherService::switch_channel
get_backend_logs commands/logs.rs:4 无 Vec<LogEntry> utils::logger::get_logger().get_recent_logs()
set_log_level commands/logs.rs:11 level: String("debug"|"info"|"warn"|"error") Result<(), String> LogLevel::parse → utils::logger::set_log_level(运行时切换,持久化由前端 set_config 负责)
get_log_dir commands/diagnostics.rs:7 无 Result<String, String> utils::paths::log_dir()
export_diagnostics commands/diagnostics.rs:15 app: AppHandle、frontend_logs: Vec<FrontendLogEntry>、context: Option<String> Result<String, String> utils::diagnostics::export
get_pending_crash_reports commands/diagnostics.rs:25 无 Vec<CrashReportInfo> utils::crash::pending_reports
ack_crash_reports commands/diagnostics.rs:31 paths: Vec<String> Result<(), String> utils::crash::acknowledge
get_api_health commands/diagnostics.rs:37 无 ApiHealthSnapshot utils::api_health::snapshot
reset_api_health commands/diagnostics.rs:43 无 () utils::api_health::reset
get_tray_user_info commands/tray.rs:8 config_service: State<Arc<Mutex<ConfigService>>> Result<TrayUserInfo, String> ConfigService::get::<TrayUserInfo>("tray_user_info")
steam_shortcut_defaults commands/startup.rs:324 config_service: State<Arc<Mutex<ConfigService>>>、game: Option<String> Result<SteamShortcutDefaults, String> Steam 弹窗默认值:名字、从 Endfield.exe 提取的 .ico、DX11、上次勾选的两项 Overlay 选项、开始菜单 Steam 快捷方式数量、当前是否已提权
pick_steam_icon commands/startup.rs:267 无 Result<Option<String>, String> 桌面:rfd 选择 ico/png/exe,取消返回 None;移动端 stub(cfg(not(desktop)))返回"File selection is not available on this platform"
pick_steam_icon_source commands/startup.rs:277 无 Result<Option<String>, String> 桌面:rfd 选择用于提取图标的 exe,取消返回 None;移动端 stub 同上
extract_steam_icon commands/startup.rs:289 exe_path: String Result<String, String> utils::game_icon::extract_icon 重新组装 RT_GROUP_ICON 为 .ico,写出到应用数据目录并返回路径
create_game_shortcut commands/startup.rs:405 config_service: State<Arc<Mutex<ConfigService>>>、dx11: Option<bool>、game: Option<String> Result<Option<String>, String> 用户通过 rfd 选择 .lnk 路径;PowerShell COM 创建快捷方式,启动参数按开关包含 --dx11,返回路径;取消选择返回 None
add_steam_shortcut commands/startup.rs:480 config_service: State<Arc<Mutex<ConfigService>>>、options: SteamShortcutOptions(含 game) Result<AddSteamShortcutResult, String> 允许 Steam 运行中写入:utils::steam::add_shortcut 按名字 upsert 当前账户 userdata/<id>/config/shortcuts.vdf;按勾选创建管理员 Steam 快捷方式(用户选路径)并提升开始菜单 Steam 快捷方式;返回 vdf 路径与新建/提升结果;非 Windows 返回 Err
set_tray_user commands/tray.rs:19 app: AppHandle、config_service、role_id: String Result<(), String> ConfigService::set("tray_user_info", …)、tray::update_tray_menu
update_tray_user_data commands/tray.rs:45 app、config_service、user_info: TrayUserInfo(前端由 src/utils/trayService.ts 组装,含 accountLevel) Result<(), String> ConfigService::set("tray_user_info", …)、tray::update_tray_menu
show_tray_panel commands/tray.rs:66 app: AppHandle Result<(), String> tray::show_tray_panel
hide_tray_panel commands/tray.rs:72 app: AppHandle Result<(), String> tray::hide_tray_panel
show_main_window commands/tray.rs:78 app: AppHandle Result<(), String> tray::show_main_window_focus + tray::hide_tray_panel
app_quit commands/tray.rs:87 app: AppHandle ()(无返回) app.exit(0)
tray_available commands/tray.rs:96 无 bool crate::tray::is_tray_available():Windows/macOS 恒 true;Linux 仅在托盘构建成功且会话总线存在 org.kde.StatusNotifierWatcher 时为 true
write_file commands/updater.rs:150 path: String、data: Vec<u8> Result<(), String> fs::create_dir_all(parent) + fs::write
get_temp_dir commands/updater.rs:161 无 Result<String, String> std::env::temp_dir
fetch_url commands/updater.rs:203 url: String Result<String, String> capture::send(reqwest GET)→ resp.text()
cancel_download commands/updater.rs:217 无 ()(无返回) 模块级 DOWNLOAD_CANCELLED AtomicBool 置 true,install_update_endpoint 下载循环中检查并取消
reset_download_cancel commands/updater.rs:223 无 ()(无返回) DOWNLOAD_CANCELLED 置 false,install_update_endpoint 启动前复位
download_file commands/updater.rs:231 app: AppHandle、url: String、path: String Result<u64, String> capture::send_stream 流式下载,每 256KB emit download-progress
download_android_apk commands/updater.rs:348 app: AppHandle、url: String Result<String, String> Android:只接受本仓库 GitHub Release 与镜像 updates.msk-network.cn/{stable,preview}/ 的 HTTPS APK,下载到应用私有缓存并支持取消;桌面/iOS 返回不支持错误
get_android_abi commands/updater.rs:300 无 Option<String> Android:返回本安装包的 ABI(arm64-v8a/x86_64/…,由 std::env::consts::ARCH 映射);其他平台返回 None。供前端按 ABI 选择拆分 APK
check_update_endpoint commands/updater.rs:58 app: AppHandle、endpoint: String Result<Option<UpdateEndpointInfo>, String> 桌面:限定镜像/GitHub 清单,使用 updater 检查本机平台与版本;移动端按 #[cfg(not(desktop))] 返回"Application updates are not available on this platform"(updater 插件只在桌面编译)。install_update_endpoint 同此规则
install_update_endpoint commands/updater.rs:73 app: AppHandle、endpoint: String Result<(), String> 限定端点后流式下载到 temp 文件,下载循环中检查 DOWNLOAD_CANCELLED 取消标志并删除半成品,完成后用 update.install() 验签安装;emit download-progress
run_installer commands/updater.rs:260/280 app: AppHandle、path: String Result<(), String> Windows:静默启动 NSIS 安装器并退出应用;非 Windows:返回不支持错误
minimize_window commands/window.rs:33 app: AppHandle<R> ()(无返回) app.get_window("main") → window.minimize()
toggle_maximize_window commands/window.rs:40 app: AppHandle<R> ()(无返回) is_maximized → maximize() / unmaximize()
close_window commands/window.rs:51 app: AppHandle<R> ()(无返回) window.close()
minimize_to_tray commands/window.rs:58 app: AppHandle<R> Result<(), String> 托盘可用 → window.hide();托盘不可用(tray::is_tray_available() 为 false)→ app.exit(0),避免窗口隐藏后用户无法恢复
save_tab_snapshot commands/window.rs:80/102 app: AppHandle<R>、tab_id: String、x/y/width/height: u32 Result<String, String> Windows:PrintWindow 截主窗口客户区 → 裁切 → PNG 存 snapshots/<tab_id>-<ts>.png(同 tab 旧文件清理),返回路径;非 Windows 返回不支持
delete_tab_snapshot commands/window.rs:115 tab_id: String Result<(), String> 删除该标签页的全部快照文件
get_system_snapshot commands/system_resource.rs:9 state: State<Arc<Mutex<SystemResourceService>>> Result<SystemSnapshot, String> SystemResourceService::snapshot(spawn_blocking;sysinfo + nvidia-smi)
browser_go_back commands/browser.rs:36 app: AppHandle<R>、webview_label: String Result<(), String> app.get_webview(label) → webview.eval("window.history.back();")
browser_go_forward commands/browser.rs:48 app、webview_label: String Result<(), String> webview.eval("window.history.forward();")
browser_reload commands/browser.rs:63 app、webview_label: String Result<(), String> webview.reload()(重跑初始化脚本并触发 on_page_load)
browser_navigate commands/browser.rs:77 app、webview_label: String、url: String Result<(), String> Url::parse → 校验 http/https → webview.navigate(url)
browser_current_url commands/browser.rs:92 app、webview_label: String Result<String, String> webview.url() → to_string()

src-tauri/src/commands/mod.rs

职责:纯模块声明文件,导出 account、arknights、attendance、browser、capture、card_config、color_picker、config、diagnostics、gacha、image、launcher、logs、proxy、startup、system_resource、tray、updater、window 共 19 个子模块。无命令定义,无逻辑。

src-tauri/src/commands/startup.rs

职责:静默游戏启动命令的配置、命令行文本、Windows .lnk 快捷方式,以及 Steam 第三方游戏条目的参数弹窗支撑(默认值、图标提取、写入)。Steam 条目允许在 Steam 运行时写入(写完需重启 Steam 才可见)。 导出:refresh_main_exe_path(启动初始化辅助函数)、SteamShortcutOptions、SteamShortcutDefaults、AddSteamShortcutResult、Tauri 命令 get_game_launch_command、steam_shortcut_defaults、pick_steam_icon、pick_steam_icon_source、extract_steam_icon、create_game_shortcut、add_steam_shortcut。 按游戏分区:LauncherGame(endfield / arknights)决定配置键—— 终末地沿用 launcher_install_path / launcher_channel / launcher_dx11,明日方舟用同名 _arknights 后缀键; 静默启动参数带 --game <id>(缺省 endfield,兼容升级前创建的快捷方式),驻守实例据此读对应一组键。

主要依赖:ConfigService、rfd::FileDialog、Windows PowerShell WScript.Shell COM、utils::steam、utils::game_icon、utils::official_launcher(process_is_elevated)。

符号 位置 说明
SteamShortcutOptions(Serialize/Deserialize) startup.rs:36 弹窗提交值:name、icon_path: Option<String>、dx11: Option<bool>、create_admin_shortcut、elevate_start_menu(后两项 #[serde(default)])
SteamShortcutDefaults(Serialize) startup.rs:53 steam_shortcut_defaults 的返回:name、icon_path、icon_extracted、game_exe_found、dx11、create_admin_shortcut、elevate_start_menu、start_menu_shortcut_count、is_elevated
AddSteamShortcutResult(Serialize) startup.rs:73 add_steam_shortcut 的返回:shortcuts_path、admin_shortcut: Option<String>、elevated_start_menu: Vec<String>
normalize_path startup.rs:82 剥除 canonicalize() 返回的 \\?\ / \\?\UNC\ 扩展长度前缀,避开 UNC 的还原为 \\
ensure_main_exe_path startup.rs:94 规范化当前 exe 路径;当配置缺失、无效或已变化时更新 main_exe_path
refresh_main_exe_path startup.rs:119 应用初始化时同步 exe 路径
launch_args(pub(crate)) startup.rs:26 组合 --silent --launch-game,按需追加 --dx11;不再支持 --close-after-launch
resolve_install startup.rs:138 读取并校验 launcher_install_path / launcher_channel(六个渠道全部受理),按渠道返回游戏 exe 路径(Endfield.exe / Arknights.exe)
default_steam_name startup.rs:26 未自定义名字时按当前渠道给 Steam 条目默认名:arknights* → 「明日方舟」,其余 → 「明日方舟:终末地」
steam_icon_path startup.rs:173 图标缓存路径 %LOCALAPPDATA%\\cn.msk-network.endprotocol\\steam\\<exe 名小写>.ico(endfield.ico / arknights.ico)
default_icon startup.rs:185 从游戏 exe 提取 .ico,返回 (路径, 是否提取成功, 游戏是否存在);提取失败回退为 exe 自身路径
get_game_launch_command startup.rs:301 返回带引号的当前 exe 路径及 --silent --launch-game --game <id>(game 缺省为终末地)
steam_shortcut_defaults startup.rs:324 弹窗默认值:名字缺省按渠道取(见 default_steam_name)、图标优先沿用上次保存的自定义图标否则重新提取、DX11 与应用设置同源、两项 Overlay 选项取上次保存值;附带开始菜单 Steam 快捷方式数量与当前进程是否已提权
pick_steam_icon startup.rs:267 rfd 选择图标文件(ico/png/exe),取消返回 None
pick_steam_icon_source startup.rs:277 rfd 选择用于提取图标的 exe,取消返回 None
extract_steam_icon startup.rs:289 对指定 exe 调用 utils::game_icon::extract_icon(图标名按 exe 名派生),返回生成的 .ico 路径
create_game_shortcut startup.rs:405 读取 dx11(缺省读该游戏的 launcher_dx11),用户选择保存路径后创建 Windows .lnk;exe 缺失时不设置图标;取消返回 None
add_steam_shortcut(async) startup.rs:480 校验名字非空 → utils::steam::add_shortcut 写 shortcuts.vdf(同名条目更新)→ 回写 steam_shortcut_name / steam_shortcut_icon / 两个 Overlay 选项 → 按勾选创建管理员 Steam 快捷方式(rfd 选保存路径,取消即报错)与提升开始菜单 Steam 快捷方式
powershell_literal(私有,仅 Windows) startup.rs:469 单引号转义(' → ''),用于嵌入脚本路径串
run_powershell(私有,仅 Windows) startup.rs:474 -EncodedCommand 执行脚本并收集 stderr/stdout 作为错误详情

备注:配置文件仍为 %LOCALAPPDATA%\\cn.msk-network.endprotocol\\app_config.json;键为 main_exe_path、launcher_install_path、launcher_channel、launcher_dx11,以及 Steam 弹窗记忆键 steam_shortcut_name、steam_shortcut_icon、steam_create_admin_shortcut、steam_elevate_start_menu。main_exe_path 不含 \\?\ 前缀。.lnk 快捷方式目标为主程序 exe,工作目录为 exe 所在目录;Endfield.exe 存在时其内嵌图标直接通过 $shortcut.IconLocation = '<Endfield.exe>,0' 引用;exe 缺失则不设置图标。Steam 条目的 Exe 为主程序 exe、LaunchOptions 为静默启动参数,icon 为提取出的 .ico。不再检查 steam.exe 是否正在运行——改为成功提示里告知用户需重启 Steam。


src-tauri/src/commands/account.rs

职责:账号体系的 IPC 门面(376 行 / 23 个命令)。绝大多数是 AccountService(State<Arc<tokio::sync::Mutex<AccountService>>>)的薄包装;只有 get_accounts、get_selected_account、set_selected_account 在命令层直接读写配置。

get_accounts

  • 位置:account.rs:16,#[tauri::command](async)
  • 参数:state: State<'_, Arc<Mutex<AccountService>>>
  • 返回:Result<Vec<AccountInfo>, String>
  • 逻辑:先取 AccountService::get_config_service() 锁配置,遍历所有 account_token_* 键提取 user_id,逐个调用 AccountService::get_cached_accounts(user_id) 尝试命中内存缓存;若全部用户缓存命中且非空则直接返回(log_debug! 记录 cache hit)。任一用户未命中则释放锁,改调 AccountService::get_accounts().await 走 API 拉全量并回填缓存。
  • 配置键:account_token_*

get_skland_accounts

  • 位置:account.rs:65(async)
  • 参数:state
  • 返回:Result<Vec<SklandAccountInfo>, String>
  • 逻辑:直连 AccountService::get_skland_accounts(),同步返回已绑定的森空岛账号列表,不联网。

save_skland_account

  • 位置:account.rs:74(async)
  • 参数:state、cred: String、token: String、user_id: String
  • 返回:Result<bool, String>(成功恒为 true)
  • 逻辑:用户确认绑定后调用 AccountService::save_skland_account(cred, token, user_id) 落盘,错误统一 map_err(|e| e.to_string())。

get_skland_account_roles

  • 位置:account.rs:89(async)
  • 参数:state、user_id: String
  • 返回:Result<AccountLoginResult, String>
  • 逻辑:调用 AccountService::get_skland_account_roles(user_id),拉取该森空岛账号下的游戏角色列表。

get_skland_user_info

  • 位置:account.rs:102(async)
  • 参数:state、user_id: String
  • 返回:Result<SklandUserInfo, String>
  • 逻辑:调用 AccountService::get_skland_user_info(user_id),返回昵称、头像、游戏等级/积分等资料。

get_skland_user_info_by_cred

  • 位置:account.rs:129(async)
  • 参数:state、cred: String、token: String
  • 返回:Result<SklandUserInfo, String>
  • 逻辑:调用 AccountService::get_skland_user_info_by_cred(cred, token),用刚登录得到的凭证直接请求 GET /web/v1/user(不读本地配置),供「确认绑定森空岛账户」页展示头像/昵称(此时账户尚未保存)。前端封装:accountService.getSklandUserInfoByCred。

get_skland_games

  • 位置:account.rs:115(async)
  • 参数:state、user_id: String、force: Option<bool>
  • 返回:Result<Vec<SklandGameInfo>, String>
  • 逻辑:以 force.unwrap_or(false) 调用 AccountService::get_skland_games(user_id, force);默认读缓存的游戏列表(图标等),force=true 才重新请求。

add_account

  • 位置:account.rs:143(async)
  • 参数:state、login_request: LoginRequest
  • 返回:Result<AccountLoginResult, String>
  • 逻辑:调用 AccountService::add_account(login_request) 完成密码/令牌登录并写入账号配置。

logout_account

  • 位置:account.rs:156(async)
  • 参数:state、account_id: String、keep_device_token: Option<bool>
  • 返回:Result<bool, String>
  • 逻辑:以 keep_device_token.unwrap_or(true) 调用 AccountService::logout_account(默认保留设备令牌),返回是否成功。

delete_skland_account

  • 位置:account.rs:171(async)
  • 参数:state、user_id: String
  • 返回:Result<bool, String>(账号不存在时返回 false)
  • 逻辑:调用 AccountService::delete_skland_account(&user_id)。删除 account_token_{user_id} 整条配置(ConfigService::remove 连带清理凭据库中的 cred/token/hytoken/device_token/phone),把该账号所有 roleId 从 account_list 移除,清内存缓存;若 selected_account_id 指向被删账号则改选剩余第一个(没有则置空)。不联网,不影响鹰角通行证与游戏账号
  • 与 logout_account 的区别:后者按 roleId 只解绑单个角色、保留父账户

batch_logout

  • 位置:account.rs:169(async)
  • 参数:state、account_ids: Vec<String>
  • 返回:Result<bool, String>
  • 逻辑:调用 AccountService::batch_logout(account_ids) 批量登出。

refresh_accounts

  • 位置:account.rs:179(async)
  • 参数:state
  • 返回:Result<AccountRefreshResult, String>
  • 逻辑:调用 AccountService::refresh_accounts(),强制刷新全部账号数据,返回成功/失败统计。

send_verification_code

  • 位置:account.rs:188(async)
  • 参数:state、request: SendCodeRequest
  • 返回:Result<bool, String>
  • 逻辑:调用 AccountService::send_verification_code(request) 发送登录验证码。

add_account_by_code

  • 位置:account.rs:201(async)
  • 参数:state、login_request: CodeLoginRequest
  • 返回:Result<AccountLoginResult, String>
  • 逻辑:调用 AccountService::add_account_by_code(login_request),用验证码登录并保存账号。

gen_scan_login

  • 位置:account.rs:214(async)
  • 参数:state
  • 返回:Result<ScanLoginInfo, String>
  • 逻辑:调用 AccountService::gen_scan_login(),生成扫码登录二维码信息。

scan_status

  • 位置:account.rs:223(async)
  • 参数:state、scan_id: String
  • 返回:Result<ScanStatus, String>
  • 逻辑:调用 AccountService::scan_status(&scan_id) 轮询扫码结果。

add_account_by_scan

  • 位置:account.rs:236(async)
  • 参数:state、scan_code: String、expected_user_id: Option<String>
  • 返回:Result<AccountLoginResult, String>
  • 逻辑:调用 AccountService::add_account_by_scan(scan_code, expected_user_id),扫码确认后落账号。expected_user_id 非空时(账户不可用后的重新登录)校验授权的森空岛账户是否一致,不一致返回 errorMessage = "ACCOUNT_MISMATCH:<实际userId>" 且不保存任何凭证。前端封装:accountService.addAccountByScan(scanCode, expectedUserId?)。

save_selected_roles

  • 位置:account.rs:250(async)
  • 参数:state、cred、token、user_id(均 String)、selected_roles: Vec<RoleDisplayInfo>
  • 返回:Result<Vec<AccountInfo>, String>
  • 逻辑:调用 AccountService::save_selected_roles(...) 持久化用户勾选的角色,返回更新后的账号列表。

get_selected_account

  • 位置:account.rs:266(async)
  • 参数:state
  • 返回:Result<Option<String>, String>
  • 逻辑:通过 service.get_config_service() 取 ConfigService::get("selected_account_id"),返回当前选中账号 ID(可能为 None)。
  • 配置键:selected_account_id

set_selected_account

  • 位置:account.rs:277(async)
  • 参数:state、account_id: String
  • 返回:Result<bool, String>(成功恒 true)
  • 逻辑:ConfigService::set("selected_account_id", json!(account_id)) 直接写配置。
  • 配置键:selected_account_id

check_and_refresh_cred

  • 位置:account.rs:295(async)
  • 参数:state、user_id: String
  • 返回:Result<Option<(String, String)>, String>(新 (cred, token))
  • 逻辑:调用 AccountService::check_and_refresh_user_cred(&user_id),检查凭据有效性并在需要时刷新。

authorize_role_u8token

  • 位置:account.rs:325(async)
  • 参数:state、role_id: String
  • 返回:Result<RoleU8AuthResult, String>,status ∈ authorized / failed,另有 message
  • 逻辑:调用 AccountService::authorize_role_u8token(&role_id)。后端用该角色的渠道绑定 uid 现换一次令牌做校验(u8_oauth_token → u8_token_by_uid,令牌用完即弃、不落盘),成功则把 roles[].u8Authorized 记为 true
  • 说明:官服与 B 服走同一条链,没有「渠道服不支持」分支,也不需要设备令牌
  • 配置键:无独立键(写在 account_token_{userId}.roles[].u8Authorized)

revoke_role_u8token

  • 位置:account.rs:338(async)
  • 参数:state、role_id: String
  • 返回:Result<bool, String>(是否确实取消成功)
  • 逻辑:调用 AccountService::revoke_role_u8token(&role_id),只移除 roles[].u8Authorized 开关 —— 没有凭据需要删除

set_lazy_load_enabled

  • 位置:account.rs:308(async)
  • 参数:state、enabled: bool
  • 返回:Result<bool, String>(成功恒 true)
  • 逻辑:调用 AccountService::set_lazy_load_enabled(enabled).await 切换账号懒加载开关。

is_lazy_load_enabled

  • 位置:account.rs:322(async)
  • 参数:state
  • 返回:Result<bool, String>
  • 逻辑:调用 AccountService::is_lazy_load_enabled() 读取懒加载状态。

set_current_role_id

  • 位置:account.rs:331(async)
  • 参数:state、role_id: Option<String>
  • 返回:Result<bool, String>(成功恒 true)
  • 逻辑:调用 AccountService::set_current_role_id(role_id).await 设置当前激活角色(可清空)。

query_role_data

  • 位置:account.rs:353(async)
  • 参数:state、role_id: String、api_name: String、paths: Vec<String>
  • 返回:Result<serde_json::Value, String>
  • 逻辑:调用 AccountService::query_role_data(&role_id, &api_name, &paths) 取到 HashMap<path, value> 后用 serde_json::to_value 转成 JSON 对象(key 为请求路径,缺失路径为 null;空 paths 表示返回完整数据)。全过程写 log_debug!/log_info!/log_error!。

src-tauri/src/commands/arknights.rs

职责:《明日方舟》数据命令(88 行 / 4 个命令)。与终末地的 query_role_data 平行:终末地按 roleId + serverId 走 /api/v1/game/endfield/card/detail,明日方舟按渠道绑定 uid 走 /api/v1/game/player/* 系列。全部以 role_id 作入口(前端只认 roleId),由 AccountService 内部反查出所属森空岛账户与 bindingUid。

四个命令都是薄封装:参数校验与「roleId → (userId, bindingUid)」解析、cred 刷新都在 AccountService(见 services_account.md),网络与解析在 ArknightsService(见 services_others.md)。

前端接入现状:get_arknights_player_info / get_arknights_attendance / do_arknights_attendance 已被「账户信息」「账户进度」「签到」三处调用(按角色所属游戏分流);2026-11 起 get_arknights_player_info 另有 src/utils/arknightsDataService.ts 封装,供「公开招募」「基地数据」卡片与 /recruitment /building /game-data 页面调用。get_arknights_cultivate 仍没有前端调用方。

get_arknights_player_info

  • 位置:arknights.rs:24(async)
  • 参数:state: State<'_, Arc<Mutex<AccountService>>>、role_id: String、force: Option<bool>(默认 false)
  • 返回:Result<serde_json::Value, String>(ArknightsPlayerInfo 的 JSON)
  • 逻辑:AccountService::get_arknights_player_info(role_id, force)。force=false 时先读缓存(内存 → <app_data>/arknights/player_info_{uid}.json),未命中才联网;联网成功后写缓存并更新头像。返回体包含 status(昵称/等级/理智/头像)、chars[](干员养成)、building(hire/training 可能为 null)、routine、campaign、tower、recruit(4 个栏位)、charInfoMap,以及 2026-11 新增的章节进度字段(stageInfoMap/activity[]/activityInfoMap/三张信息表/rogue/sandbox/bossRush)与 dataVersion 结构版本标记(接口不返回,由 fetch_player_info 填充;旧缓存为 0,前端 arknightsDataService 据此自动强制刷新一次)。
  • 前端调用方:src/components/cards/account-info/index.tsx、src/components/cards/account-progress/index.tsx(两者先用 resolveRoleGame(roleId) 判断游戏,是明日方舟角色才调本命令,否则走终末地的 query_role_data);src/utils/arknightsDataService.ts(公开招募/基地数据卡片 + 三个明日方舟页面)。

get_arknights_cultivate

  • 位置:arknights.rs:43(async);参数:state、role_id: String;返回:Result<serde_json::Value, String>
  • 逻辑:ArknightsService::fetch_cultivate → GET /api/v1/game/cultivate/player?uid=。干员养成 player/info 已经全给(还多了信赖/皮肤),这个接口的唯一增量是仓库 items(count 是字符串)。
  • 前端调用方:无(仓库数据暂未接入界面)。

get_arknights_attendance

  • 位置:arknights.rs:60(async);参数:state、role_id: String;返回:Result<serde_json::Value, String>
  • 逻辑:ArknightsService::attendance_status → GET /api/v1/game/attendance?gameId=1&uid=。返回本月签到日历(30 格)、已签到记录与物品静态表(resourceInfoMap,图标由后端按 resourceId 补成 https://web.hycdn.cn/arknights/game/assets/item/{id}.png)。
  • 返回体额外带三项后端计算字段:hasToday(今天是否已签到)、todayIndex / tomorrowIndex(今日/明日奖励在 calendar 里的下标)。
  • ⚠️ 返回 {code, message, data, timestamp} 外壳,不是裸 data。前端两个游戏共用一个解析器 parseAttendanceData,按 json.data.calendar 取值(终末地 get_attendance 直接原样返回森空岛响应)。只回 data 本身 → json.data 为 undefined → 解析 null → 界面「获取签到数据失败」。见 AccountService::arknights_attendance_envelope。
  • ⚠️ calendar 是累计 30 格领取轨道,下标与「几号」无关;判「今天签没签」只能看「有没有 available && !done 的格子」。详见 models.md 的 ArknightsAttendance 一节。
  • 前端调用方:src/components/cards/attendance/index.tsx、src/pages/attendance.tsx(分流三元 isArknights ? "get_arknights_attendance" : "get_attendance")。src/utils/attendanceHelpers.ts 的 detectSignedToday 优先用后端 hasToday,缺失时才本地按同一规则推。

do_batch_attendance

  • 位置:arknights.rs:118(async);参数:state、role_ids: Vec<String>;返回:Result<Vec<BatchAttendanceItem>, String>
  • 逻辑:对 role_ids 逐个调用 AccountService::do_attendance_for_role。该方法是唯一的分流点 —— 角色属于明日方舟就走 POST /api/v1/game/attendance,属于终末地就走 /web/v1/game/endfield/attendance,因此前端可以把两个游戏的角色混在一起传。
  • 返回值 BatchAttendanceItem(#[serde(rename_all = "camelCase")]):roleId / ok / alreadySigned / error。
  • 设计要点:
    • 串行执行:森空岛的签名/设备指纹链路对并发敏感,批量场景下稳定性优先于总耗时。
    • 每角色独立持锁:签到要发网络请求,长时间占着全局 Arc<Mutex<AccountService>> 会阻塞整个账户服务。
    • 单点失败不打断:每个角色独立返回 ok/error,前端逐行展示,而不是整批报错或静默部分成功。
  • 前端调用方:src/utils/attendanceService.ts 的 performBatchAttendance ← src/components/cards/attendance/attendance-batch-modal.tsx(签到页右上角「批量签到」)。

do_arknights_attendance

  • 位置:arknights.rs:81(async);参数:state、role_id: String;返回:Result<serde_json::Value, String>
  • 逻辑:ArknightsService::do_attendance → POST /api/v1/game/attendance,body {gameId: 1, uid}。与终末地签到(靠 sk-game-role 头、路径 /web/v1/game/endfield/attendance)完全不同。
  • 返回 {code, message, data} 外壳(code 透传真实业务码 0 / 10001),data 为 ArknightsAttendanceResult:code == 0 → awards[](本次奖励)+ tomorrowAwards[](明日奖励,数组),两者 resource.icon 都已补成 CDN 地址;今天已签到时接口返回 code=10001「请勿重复签到」,call_skland_api 原样放行,这里折成 alreadySigned = true + 空 awards。
  • 前端调用方:src/components/cards/attendance/index.tsx(分流三元 isArknights ? "do_arknights_attendance" : "do_attendance";按 result.alreadySigned 区分「今天已签到」与「签到成功」文案)。

src-tauri/src/commands/attendance.rs

职责:森空岛「签到」功能的 IPC 入口(254 行 / 2 个命令)。命令层自己完成「按 roleId 反查凭据 → 刷新 cred → 直接调用森空岛 HTTP API」的完整链路,而不经过独立的 attendance service。

共享辅助函数 lookup_cred_token(attendance.rs:12-55,非命令)

遍历全部 account_token_* 配置项,在 roles[] 中按 roleId 精确匹配,返回 (user_id, server_id, cred, token);找不到则返回 AppError::AuthError。配置键:account_token_*。

get_attendance

  • 位置:attendance.rs:60,#[tauri::command](async)
  • 参数:state: State<'_, Arc<Mutex<AccountService>>>、role_id: String
  • 返回:Result<serde_json::Value, String>
  • 逻辑:① 本地 lookup_cred_token 找凭据;② AccountService::check_and_refresh_user_cred(&user_id) 尝试刷新(失败则回退旧凭据,不中断);③ AccountService::skland_service() → SklandService::call_skland_api("GET", "/web/v1/game/endfield/attendance", …),附带 sk-game-role: 3_{role_id}_{server_id} 与 token 头;④ 校验响应 code==0 否则返回 Attendance API error: code=…;⑤ 遍历 data.resourceInfoMap,用 AvatarCacheService::get_or_download_image(url, ImageType::AttendanceIcon) 把奖励图标下载到本地并把 icon 字段替换成 local_path。

do_attendance

  • 位置:attendance.rs:182(async)
  • 参数:state、role_id: String
  • 返回:Result<serde_json::Value, String>
  • 逻辑:与 get_attendance 前三步相同,但以 POST(body json!({}))请求同一路径执行签到;code==0 或 api_health::is_benign_business_error 判定为幂等成功(如 code=10001, message=请勿重复签到!)时返回 Ok(json),其余业务码返回 Attendance API error: code=…。不下载奖励图标(与 get_attendance 不对称)。

src-tauri/src/commands/browser.rs

职责:in-app browser 原生子 Webview 的导航能力门面(99 行 / 5 个命令)。前端 @tauri-apps/api/webview 的 Webview 类只有生命周期与布局方法(无 eval/navigate/reload/url/onPageLoad),这些能力只在 Rust 侧 tauri::Webview 上存在,故在此以 app command 暴露;页面加载事件则由 lib.rs 的 Builder::on_page_load 反向桥接成 browser://page-load 事件。

共享辅助函数 get_webview(browser.rs:23-33,非命令)

app.get_webview(label) 取子 webview 实例,取不到返回 webview not found: {label}。

browser_go_back

  • 位置:browser.rs:36(async);参数:app: AppHandle<R>、webview_label: String;返回:Result<(), String>
  • 逻辑:webview.eval("window.history.back();")。Rust 侧没有 back(),走 eval;在子 webview 内执行的是该页同源 history,不受宿主跨域限制(对应 iframe 方案里静默失败的能力)。

browser_go_forward

  • 位置:browser.rs:48(async);同上,eval("window.history.forward();")。

browser_reload

  • 位置:browser.rs:63(async);返回:Result<(), String>
  • 逻辑:webview.reload()。不用 eval("location.reload()"):reload() 会重跑 Tauri 注入的初始化脚本并照常触发 on_page_load,前端 loading 状态才能正确回落。

browser_navigate

  • 位置:browser.rs:77(async);参数:app、webview_label: String、url: String;返回:Result<(), String>
  • 逻辑:Url::parse → 校验 scheme 必须是 http/https(WindowConfig.url 的反序列化会把其它 scheme 当 CustomProtocol,而 Webview::navigate 只接受 http/https)→ webview.navigate(url)。就地导航保留实例与浏览历史,避免销毁重建。

browser_current_url

  • 位置:browser.rs:92(async);返回:Result<String, String>
  • 逻辑:webview.url() → to_string()。用于地址栏聚焦时回读真实地址(补 SPA pushState 不触发 on_page_load 的盲区)。

安全边界:webview_label 只能由主 webview(local origin)指定。子 webview 加载的是远程站点,属 remote origin,Tauri ACL 会直接拒绝它调用任何 app command(没有匹配 remote context 的 capability),因此远程页面无法用这些命令操纵自身或其它 webview。


src-tauri/src/commands/capture.rs

职责:网络抓包会话的 IPC 门面(42 行 / 7 个命令),全部是对 utils::capture 模块函数的转发,无状态参数。

capture_start

  • 位置:capture.rs:3(async);参数:无;返回:Result<CaptureStatus, String>;逻辑:capture::start() 启动抓包。

capture_stop

  • 位置:capture.rs:8(async);参数:无;返回:Result<CaptureStatus, String>;逻辑:capture::stop() 停止抓包。

capture_status

  • 位置:capture.rs:13(async);参数:无;返回:Result<CaptureStatus, String>;逻辑:Ok(capture::status()) 读取当前状态,永不失败。

capture_list_sessions

  • 位置:capture.rs:18(async);参数:无;返回:Result<Vec<CaptureSessionMeta>, String>;逻辑:capture::list_sessions() 列出历史会话。

capture_read_entries

  • 位置:capture.rs:23(async);参数:id: String、offset: u64、limit: u64;返回:Result<CapturePage, String>;逻辑:capture::read_entries(&id, offset, limit) 分页读取会话条目。

capture_delete_session

  • 位置:capture.rs:32(async);参数:id: String;返回:Result<(), String>;逻辑:capture::delete_session(&id) 删除会话。

capture_dir

  • 位置:capture.rs:37(async);参数:无;返回:Result<String, String>;逻辑:capture::capture_root() 取根目录并 fs::create_dir_all 确保存在,返回路径字符串。

src-tauri/src/commands/card_config.rs

职责:桌面卡片个性化配置的增删改(79 行 / 3 个命令),全部经 AccountService::get_config_service() 访问配置,键名为 card_settings.{card_id}。

get_card_settings

  • 位置:card_config.rs:9(async)
  • 参数:state、card_id: String
  • 返回:Result<Value, String>(缺失时返回空对象 {})
  • 逻辑:读取 card_settings.{card_id};不存在时返回 Value::Object(Map::new())。

save_card_settings

  • 位置:card_config.rs:26(async)
  • 参数:state、card_id: String、settings: Value
  • 返回:Result<bool, String>(成功恒 true)
  • 逻辑:读取现有 card_settings.{card_id},若双方都是 JSON 对象则做浅合并(新值覆盖同名键),否则整体替换;随后 ConfigService::set 写回。

remove_card_settings

  • 位置:card_config.rs:66(async)
  • 参数:state、card_id: String
  • 返回:Result<bool, String>
  • 逻辑:ConfigService::remove("card_settings.{card_id}"),返回是否确实删除。

src-tauri/src/commands/color_picker.rs

职责:Windows 屏幕取色(吸管)流程的窗口控制与 GDI 截屏;macOS/Linux 使用仅报不支持错误的命令桩,前端不展示屏幕吸管入口。Windows 流程为「最小化 → 截取鼠标所在屏幕 → 还原并全屏 → 前端在全屏覆盖层上取色」。

内部结构

  • ScreenCapture:width/height/data,data 为 RGBA 的 base64,序列化为 camelCase。
  • capture_screen:Windows 下最小化并等待 400ms,执行 capture_screen_sync() 后还原并全屏;非 Windows 返回明确错误。
  • finish_screen_pick:Windows 下退出全屏并聚焦;非 Windows 空实现。
  • Windows 专用 capture_screen_sync():Win32 GDI 截屏:GetCursorPos → MonitorFromPoint/GetMonitorInfoW → GetDC/CreateCompatibleDC/CreateCompatibleBitmap → BitBlt → GetDIBits 取 32 位像素 → BGRA 转 RGBA → base64 编码;每步失败都返回具体错误字符串并释放 GDI 资源。

capture_screen

  • 位置:color_picker.rs:28,#[tauri::command](async)
  • 参数:window: WebviewWindow
  • 返回:Result<ScreenCapture, String>
  • 逻辑:先 window.minimize() 并 sleep(400ms)(避免截到自身窗口),用 tauri::async_runtime::spawn_blocking 在线程池执行 capture_screen_sync;无论成败随后 unminimize() + set_fullscreen(true) + set_focus() 进入全屏取色态,最后返回截屏结果。

finish_screen_pick

  • 位置:color_picker.rs:47,#[tauri::command](同步)
  • 参数:window: WebviewWindow
  • 返回:()(无返回值)
  • 逻辑:set_fullscreen(false) + set_focus(),取色完成或取消后退出全屏还原窗口。

src-tauri/src/commands/config.rs

职责:通用配置 KV 的最薄封装(5 个命令),直接持有 State<Arc<std::sync::Mutex<ConfigService>>>(注意是同步 Mutex,与 account 系列的 tokio Mutex 不同)。任何前端都可经 set_config 写入任意非机密键,是配置的总入口。

get_config

  • 位置:config.rs:9(同步);参数:state: State<Arc<Mutex<ConfigService>>>、key: String;返回:Option<Value>;逻辑:ConfigService::get(&key),锁中毒用 unwrap()(会 panic)。⚠️ 该命令可读出机密字段明文(供后端/前端确有需要的场景),目前前端无调用方读机密键。

set_config

  • 位置:config.rs:46(同步);参数:state、key: String、value: Value;返回:Result<(), String>;逻辑:先检查 secret_registry::has_secret_fields(&key),命中则直接返回错误(拒绝通过通用入口写机密字段);否则 ConfigService::set 并持久化。key == "proxy_config" 时额外刷新全局代理缓存。

remove_config

  • 位置:config.rs:64(同步);参数:state、key: String;返回:bool;逻辑:ConfigService::remove(&key),返回是否删除(同时清理凭据库里的对应机密字段)。

get_all_configs

  • 位置:config.rs:71(同步);参数:state;返回:HashMap<String, Value>;逻辑:ConfigService::get_all_public() —— 机密字段被逐字段剔除(account_token_* 只剩 roles / user_info 等非机密子字段),不含任何凭据。

get_secret_storage_status

  • 位置:config.rs:82(同步);参数:state;返回:Result<SecretStorageStatus, String>;逻辑:读 ConfigService::secret_backend() 与 secrets_degraded(),返回 { backend, degraded }。用于设置页展示机密数据的保护等级。

src-tauri/src/commands/gacha.rs

职责:抽卡(寻访)记录相关 IPC(8 个命令)。命令层承担「凭据反查 + token 刷新 + 游戏分流 + 组装 JSON」的编排,真正的请求与存储由 GachaService(终末地,State<Arc<GachaService>>)与 ArknightsGachaService(明日方舟,State<Arc<ArknightsGachaService>>)负责。

⚠️ 两个游戏的抽卡 API 完全不同,命令层是唯一的分流点:lookup_role_owner 多读一个 roles[].app 字段(RoleOwner.game),每个命令据此决定走哪条链路。 差异明细见 services_others.md 的 arknights_gacha_service.rs 一节。

内部结构

  • 1-15:导入 + TOTAL_CATALOG_REFRESH_COOLDOWN 常量(全量 Wiki 目录刷新冷却 6 小时)。
  • 22-52:RoleOwner 结构(含 game 字段与 is_arknights())—— game 取自 roles[].app,老数据缺字段时兜底 endfield。
  • 54-115:lookup_role_owner(config_service, role_id) —— 遍历 account_token_*,按 roles[].roleId 匹配,返回 RoleOwner { user_id, binding_uid, channel_master_id, server_id, authorized, game }。不要求授权、不读令牌。
  • 117-142:fresh_u8token(account_service, owner, role_id) —— 先检查 owner.authorized(未授权直接报错),非致命刷新 cred,再 AccountService::fetch_role_u8token 现换令牌(不缓存、不落盘、失败不回退旧值)。
  • 146-190:get_gacha_pool_meta(仅终末地);193-233:sync_gacha_records(分流);235-272:get_saved_gacha_records(分流)。
  • 274-331:sync_weapon_gacha_records(仅终末地,明日方舟返回空);333-392:get_saved_weapon_gacha_records(同上)。
  • 394-437:get_arknights_gacha_categories(仅明日方舟)。
  • 445-556:resolve_missing_from_catalog(私有辅助:从 Wiki 目录按名称补齐头像,见下)。
  • 563-741:resolve_gacha_avatar_map(本文件最长逻辑,见下;含明日方舟 CDN 直拼分支)。
  • 744-757:arknights_avatar_url(私有:按 CDN 规则拼明日方舟干员头像)。
  • 757-822:get_gacha_record_stats(分流)。

get_gacha_pool_meta

  • 位置:gacha.rs:147(async)
  • 参数:account_state: State<Arc<Mutex<AccountService>>>、gacha_state: State<Arc<GachaService>>、role_id: String
  • 返回:Result<serde_json::Value, String>
  • 逻辑:lookup_role_owner 定位账号 → 若是明日方舟直接返回 Err(明日方舟没有 meta,卡池枚举是 cate 的分类,走 get_arknights_gacha_categories)→ fresh_u8token 现换令牌 → GachaService::get_pool_meta(&u8token, &server_id) 取卡池 meta → serde_json::to_value 返回。配置键:account_token_*(roles[].u8Authorized / bindingUid / app)。

sync_gacha_records

  • 位置:gacha.rs:194(async)

  • 参数:account_state、gacha_state、arknights_gacha_state: State<Arc<ArknightsGachaService>>、role_id: String

  • 返回:Result<serde_json::Value, String>

  • 逻辑:lookup_role_owner → fresh_u8token 现换令牌 → 按 owner.is_arknights() 分流:

    • 明日方舟:ArknightsGachaService::sync_records(&owner.binding_uid, &u8token) —— 按渠道绑定 uid 存盘(接口不吃 server_id)
    • 终末地:GachaService::sync_records(&owner.user_id, &owner.server_id, &u8token)

    两者都是增量同步(从最新读到上次保存的最后一条并合并),返回同形状的 GachaSyncResult(前端无需区分)。未授权角色直接报错(提示去账号页授权)。

get_saved_gacha_records

  • 位置:gacha.rs:236(async)
  • 参数:account_state、gacha_state、arknights_gacha_state、role_id
  • 返回:Result<serde_json::Value, String>
  • 逻辑:仅 lookup_role_owner(不读令牌、不刷新、不联网),按游戏分流读本地记录(ArknightsGachaService::load_records_or_empty(binding_uid) / GachaService::load_records_or_empty(user_id, server_id)),无记录返回空结构。未授权(甚至刚取消授权)也能看到已同步的记录。

sync_weapon_gacha_records

  • 位置:gacha.rs:275(async)
  • 参数:account_state、gacha_state、role_id
  • 返回:Result<serde_json::Value, String>
  • 逻辑:仅终末地。《明日方舟》没有武器寻访,若是明日方舟角色则直接返回空 GachaSyncResult(new_records=0、total_records=0)——不发请求、不落盘、不报错,让前端的「同步全部记录」流程可以无条件复用。终末地则 fresh_u8token + GachaService::sync_weapon_records(...)。

get_saved_weapon_gacha_records

  • 位置:gacha.rs:334(async)
  • 参数:account_state、gacha_state、role_id
  • 返回:Result<serde_json::Value, String>
  • 逻辑:仅终末地。明日方舟返回空 SavedWeaponGachaData(前端据此隐藏「武器」分类);终末地仅 lookup_role_owner(不读令牌、不联网),调 GachaService::load_weapon_records_or_empty(&user_id, &server_id)。

get_arknights_gacha_categories

  • 位置:gacha.rs:395(async)
  • 参数:account_state、arknights_gacha_state: State<Arc<ArknightsGachaService>>、role_id: String
  • 返回:Result<serde_json::Value, String>(ArknightsGachaCategory[]:{id, name, active?})
  • 逻辑:仅明日方舟(对终末地角色返回 Err)。lookup_role_owner → 校验游戏 → fresh_u8token → ArknightsGachaService::get_categories(&u8token)(GET /api/gacha/cate)。
  • ⚠️ 空分类列表已在服务层转成 AuthError:明日方舟对任何无效 token 都返回 code=0 + 空 data,若不判空,用户会看到「同步成功、0 条记录」。前端据此提示「令牌失效/不匹配,请重新授权」。name 含换行符("限定寻访\n庆典"),前端用 formatCategoryName 压成一行。

resolve_missing_from_catalog

  • 位置:gacha.rs:292(私有函数)
  • 参数:catalog: &serde_json::Value、needed: &HashMap<String,String>(id → 显示名)、unresolved: &mut Vec<String>、map: &mut HashMap<String,String>
  • 返回:usize(本次新解析数量)
  • 逻辑:遍历 data.catalog[].typeSub[].items[] 建「显示名 → 图标」表。条目类型优先取 brief.associate.type(char/weapon);新干员/武器在目录中可能仍是预览条目(brief.associate 为 null,brief.dotType == "label_type_preview"),此时回退到所属 typeSub.id("1" = 干员、"2" = 武器)归类,名称回退 brief.name → item.name,图标取 brief.cover。随后仅对 unresolved 中仍无映射的 id 按显示名补齐,命中者写入 map 并从 unresolved 移除。

resolve_gacha_avatar_map

  • 位置:gacha.rs:564(async)
  • 参数:account_state、gacha_state、arknights_gacha_state、role_id
  • 返回:Result<serde_json::Value, String>({角色/武器 id: 图标 URL} 映射)
  • 逻辑(按游戏分流,两条路完全不同):
    • 明日方舟(owner.is_arknights()):读本地记录,筛 rarity == 6 的 char_id,直接用 arknights_avatar_url 拼 https://web.hycdn.cn/arknights/game/assets/char/avatar/{charId}.png 返回。不联网、不读 total.json、不写 gacha_avatar_map.json —— 因为 wiki_catalog(/web/v1/wiki/item/catalog)是终末地的目录,里面没有明日方舟干员; 该 CDN 规则是确定的纯函数(已用真实干员验证 200 + image/png + Access-Control-Allow-Origin: *)。
    • 终末地:① 仅 lookup_role_owner 定位账号,读本地角色+武器记录,筛出 rarity == 6 且 is_draw() 的条目,构建 id → 显示名 的 needed 表;② GachaService::load_avatar_map() 读已有映射(文件 gacha_avatar_map.json,与 app_config.json 同级),算出 missing;③ 有缺失时先非致命 check_and_refresh_user_cred,再用 load_total_catalog() 读本地 total.json 缓存并调 resolve_missing_from_catalog 解析;④ 若仍有未解析 id 且(缓存缺失或已过 TOTAL_CATALOG_REFRESH_COOLDOWN 冷却期),则 AccountService::query_role_data(&role_id, "wiki_catalog", &[]) 重新拉取全量 Wiki 目录、save_total_catalog 写盘并再次解析;⑤ 有新增则 save_avatar_map 回写文件,最后返回完整 map。

get_gacha_record_stats

  • 位置:gacha.rs:758(async)
  • 参数:account_state、gacha_state、arknights_gacha_state、role_id
  • 返回:Result<serde_json::Value, String>
  • 逻辑:仅 lookup_role_owner 定位账号(不读令牌),按游戏分流 load_records_or_empty 后在命令层组装统计 JSON:user_id、server_id、last_sync_time、total_records、total_draws、total_gifts、by_pool(GachaService::group_records_by_pool 取长度)、by_rarity(count_by_rarity)、by_char(count_by_char)。统计函数本身与游戏无关(rarity 已归一化为星数),因此两条链路共用。不发起网络请求。

src-tauri/src/commands/image.rs

职责:图片与背景图的本地缓存/读写(217 行 / 6 个命令 + 1 个私有工具函数)。涉及目录:图片缓存目录(paths::image_cache_dir,按子目录分类)与背景目录(paths::backgrounds_dir,固定单文件 bg.webp)。

read_image_file

  • 位置:image.rs:18(同步);参数:path: String;返回:Result<tauri::ipc::Response, String>(IPC 原始字节,前端拿到 ArrayBuffer);逻辑:fs::read(&path) 后原样返回,不校验路径范围(可读任意本地文件),错误信息含路径。
  • 注意:不要改回 Result<Vec<u8>, String>。Vec<u8> 会被 Tauri 序列化成 JSON 数字数组,一张 583KB 的图标在 IPC 上膨胀到约 2.3MB 文本,前端 JSON.parse 再建一个约 4.6MB 的 number[],合计约 12 倍于文件本身。调用方因此必须把返回值当 ArrayBuffer 用(长度取 byteLength,不是 length)。

get_image_cache_dir

  • 位置:image.rs:16(同步);参数:无;返回:Result<String, String>;逻辑:paths::image_cache_dir() 并 log_info! 记录结果。

download_image

  • 位置:image.rs:29(async)
  • 参数:url: String、cache_dir: String、sub_dir: String
  • 返回:Result<String, String>(本地文件路径)
  • 逻辑:① 空 URL 报错;② file:// / http://asset.localhost 开头视为已本地化直接返回;③ extract_filename_from_url 去查询串取最后一段路径作文件名;④ sub_dir 为空时先 resolve_url_subdir(&url)(URL 注册表)定子目录,未命中则遍历 all_sub_dir_names() 扫描已有缓存命中即返回,仍无则回退 misc;⑤ fs::create_dir_all 建目录,文件已存在直接返回;⑥ 用 reqwest + capture::send GET(带 Referer: https://game.skland.com/)下载、写盘、返回路径。

get_backgrounds_dir

  • 位置:image.rs:141(同步);参数:无;返回:Result<String, String>;逻辑:paths::backgrounds_dir() + log_info!。

save_background_image

  • 位置:image.rs:152(同步)
  • 参数:data: String(base64 或 data: URL)
  • 返回:Result<String, String>(保存后路径)
  • 逻辑:建背景目录 → 先删除目录内所有旧文件(副作用:只保留一张背景)→ 剥掉 data:…, 前缀 → base64 解码 → 写入 bg.webp → 返回路径。

delete_background_image

  • 位置:image.rs:190(同步);参数:无;返回:Result<(), String>;逻辑:遍历背景目录删除全部文件(任一删除失败即报错),log_info! 记录。

私有工具 extract_filename_from_url(image.rs:208-217)

去 ? 查询串后取最后一个 / 之后的片段,空则 None。


src-tauri/src/commands/launcher.rs

职责:游戏启动器(下载/校验/渠道切换/启动进程)的 IPC 层(约 1000 行 / 27 个命令)。命令以 State<Arc<GameLauncherService>> 直接取服务——服务不再被一把外层 Mutex 包住;会写安装目录的长任务(launcher_install_or_update、launcher_verify_and_repair、launcher_install_preload、launcher_switch_channel;launcher_preload_download 只写暂存不写安装目录、不做检测)先经 acquire_write_gate 取得 write_gate(容量 1 的 Semaphore)permit,再经 check_and_lock_install_dir 做占用检测 + 目录锁(utils/dir_lock.rs:Restart Manager 查谁锁了关键文件,被占用返回 LOCKED_BY:进程名 (PID n)|…;空闲则独占打开关键文件持有到任务结束),然后执行,其余命令(公告/背景图/状态查询/扫描)不再被下载堵住。涉及渠道的先经 parse_channel 把字符串转成 GameChannel 枚举;耗时操作通过回调 emit launcher-progress 事件推送进度。

内部结构

  • 1-9:导入(models::game::*、GameLauncherService、Emitter、utils::official_launcher)。
  • 11-29:launcher_get_process_read_bytes(Win32 IO 计数器)。
  • 31-50:launcher_check_status;52-102:launcher_install_or_update;104-159:launcher_verify_and_repair;161-170:launcher_get_remote_version;172-212:launcher_preload_download;214-248:launcher_install_preload;250-259:launcher_get_payload_state。
  • 261-305:下载控制、切服取消与解密。
  • 307-388:内容获取(banners / announcements / notice content / background media)。
  • 389-522:launcher_start_game(原生快照清理残留 + 提权 helper 伪造官方父进程 + 回退直启)。
  • 540-597:launcher_get_disk_space;599-668:扫描安装目录与渠道探测。
  • 670-733:游戏运行检测与进程终止;735 起:launcher_switch_channel。

launcher_get_process_read_bytes

  • 位置:launcher.rs:47(同步);参数:无;返回:Result<u64, String>;逻辑:Windows 下 GetCurrentProcess + GetProcessIoCounters 取 ReadTransferCount(任务管理器磁盘速率用),非 Windows 返回 Ok(0)。

launcher_check_status

  • 位置:launcher.rs:65(async);参数:service、channel: String、install_path: String;返回:Result<GameStatus, String>;逻辑:parse_channel → 加锁 → GameLauncherService::check_status(&ch, &install_path).await。

launcher_install_or_update

  • 位置:launcher.rs:86(async)
  • 参数:app: AppHandle、service、channel、install_path、max_concurrent: Option<usize>(缺省 8)、resume: Option<bool>(缺省 true)
  • 返回:Result<LauncherResult, String>(业务失败也包成 success:false 的 LauncherResult,不返回 Err)
  • 逻辑:构造 progress_cb 回调,每阶段 app.emit("launcher-progress", &DownloadProgress);调 GameLauncherService::install_or_update(&ch, &install_path, progress_cb, max_concurrent, resume),成功填 version 与 "Update to {v} completed",失败填错误串。resume 决定取消/失败后是否保留分片与暂存。
  • 事件:launcher-progress

launcher_verify_and_repair

  • 位置:launcher.rs:150(async)
  • 参数:app、service、channel、install_path、max_concurrent: Option<usize>、quick: Option<bool>、resume: Option<bool>
  • 返回:Result<LauncherResult, String>
  • 逻辑:GameLauncherService::verify_and_repair(..., max_concurrent.unwrap_or(12), quick.unwrap_or(false), resume.unwrap_or(true)),进度同样 emit launcher-progress;结果包成 LauncherResult,发生错误时额外 emit stage = "error" 以结束前端进度状态。

launcher_get_remote_version

  • 位置:launcher.rs:210(async);参数:service、channel;返回:Result<RemotePackage, String>;逻辑:GameLauncherService::get_latest_package(&ch, None) 取远程版本包(不带本地版本,因此不会返回 pre_patch 预下载信息)。

launcher_preload_download

  • 位置:launcher.rs:221(async)
  • 参数:app、service、channel、install_path、max_concurrent: Option<usize>、resume: Option<bool>
  • 返回:Result<LauncherResult, String>
  • 逻辑:GameLauncherService::preload_download(..., max_concurrent.unwrap_or(8), resume.unwrap_or(true), None) 预下载官方预发布补丁分卷(服务内自行读本地版本以取 pre_patch),进度 emit launcher-progress。

launcher_install_preload

  • 位置:launcher.rs:266(async)
  • 参数:app、service、channel、install_path、max_concurrent: Option<usize>、resume: Option<bool>
  • 返回:Result<LauncherResult, String>
  • 逻辑:调用 GameLauncherService::install_preload;复用已下载分卷或先下载并 MD5 校验,使用官方 pkg.cd_key 解压到暂存区并应用文件。命令完成后由前端再调用快速校验与修复;解压密码只保留在后端。
  • 事件:launcher-progress

launcher_get_payload_state

  • 位置:launcher.rs:310(async);参数:service、channel;返回:Result<Option<PayloadState>, String>;逻辑:GameLauncherService::get_payload_state(&ch),返回上次安装/更新的 payload 状态。

launcher_cancel_download

  • 位置:launcher.rs:321(async);参数:install_path: Option<String>;返回:Result<(), String>;逻辑:给了非空路径时先调 game_launcher_service::request_cancel_cleanup() 记录删除意图,再置取消标志并 cleanup_staging_files(&path);不给路径时仅 cancel_download(),后台任务会保留分片与暂存以便续传。不加 service 锁。

launcher_has_download_cache

  • 位置:launcher.rs:340(async);参数:install_path: String;返回:Result<bool, String>;逻辑:game_launcher_service::has_download_cache(&path) 判断是否有暂存目录或 .download 文件。

launcher_reset_download_cancel

  • 位置:launcher.rs:348(async);参数:无;返回:Result<(), String>;逻辑:game_launcher_service::reset_download_cancel()。

launcher_cancel_switch

  • 位置:launcher.rs:354(async);参数:无;返回:Result<(), String>;逻辑:game_launcher_service::cancel_switch() 取消渠道切换。

launcher_cancel_all

  • 位置:launcher.rs:360(async);参数:无;返回:Result<(), String>;逻辑:依次 cancel_download() + cancel_switch()。

launcher_decrypt_file

  • 位置:launcher.rs:367(async);参数:file_path: String;返回:Result<String, String>;逻辑:utils::hg_crypto::decrypt_file_to_string(&file_path) 解密游戏资源文件并返回文本。

launcher_get_banners

  • 位置:launcher.rs:373(async);参数:service、channel;返回:Result<Vec<BannerItem>, String>;逻辑:GameLauncherService::get_banners(&ch)(本渠道没有 Banner 时用回落渠道的补上)。

launcher_get_announcements

  • 位置:launcher.rs:384(async);参数:service、channel;返回:Result<Vec<AnnouncementItem>, String>;逻辑:GameLauncherService::get_announcements(&ch)(本渠道没有公告时用回落渠道的补上)。

launcher_get_notice_content

  • 位置:launcher.rs:395(async);参数:service、channel;返回:Result<LauncherNoticeContent, String>;逻辑:GameLauncherService::get_notice_content(&ch)(Banner + 公告 + 右侧栏 sidebars 合并内容,一次 batch_proxy_web_raw 带 get_banner/get_announcement/get_sidebar 三项)。三项内容各自独立在为空时用回落渠道补(B服 → 官服、GooglePlay → Global),详见 services_launcher.md 的「公告内容回落」。

launcher_get_background_image

  • 位置:launcher.rs:406(async);参数:service、channel;返回:Result<Option<BackgroundMedia>, String>;逻辑:GameLauncherService::get_background_image(&ch)。

launcher_start_game

  • 位置:launcher.rs:461(async)
  • 参数:config_service: State<Arc<StdMutex<ConfigService>>>、install_path: String、channel: String、dx11: Option<bool>(为 None 时读取配置 launcher_dx11,缺省 false)
  • 返回:Result<LauncherResult, String>
  • 逻辑:用 ch.executable_name() 拼 exe 路径,不存在直接返回 success:false;启用 DX11 时构造游戏参数 vec!["-force-d3d11"];先 process::terminate_processes(exe_name) 清理残留(原生快照 + TerminateProcess,无残留时立刻返回,旧实现的 taskkill /F /IM + sleep(500ms) 已移除)。
    • 明日方舟直接启动:Arknights.exe / ArknightsBase.dll / GameAssembly.dll 里都不存在 Games.exe / WinVerifyTrust 相关字符串(实测),方舟不校验父进程,所以 ch.is_arknights() 时清完残留直接 direct_launch,不走提权 helper 那条路。
    • 终末地:(Windows)在 spawn_blocking 中调用 official_launcher::launch_via_official_parent —— 游戏会校验自己的直接父进程必须是签名有效的官方 Games.exe,该函数先查找 + 验签官方启动器(失败即 no_launcher),然后分两条路径:应用已提权时由当前进程直接创建「挂起且永不运行的官方启动器 + 以其为父进程的游戏进程」(保留 Steam overlay 的 CreateProcess 注入链),创建完成后立即拉起独立的会话驻守进程(--endfield-session-keeper,继承游戏 / 挂起父进程 / 清理 Job 句柄)接管收尾 —— 应用退出(关窗 / 崩溃 / 更新重启)不再连带结束游戏,游戏退出后由驻守进程清理挂起启动器;未提权时用 ShellExecuteExW("runas") 以 --endfield-launch-helper 提权重启自身完成创建,命令侧用 2.5s 宽限期 + 状态文件判断 helper 是启动阶段失败还是游戏已创建(helper 本身驻守到游戏退出,同样与应用生命周期解耦)。找不到签名有效的官方启动器时回退 direct_launch(ShellExecuteW(SW_SHOWNORMAL) + 游戏参数,即旧行为)并把原因放进 LauncherResult.warning。若当前进程由 Steam 拉起(SteamClientLaunch / SteamAppId / SteamGameId / SteamOverlayGameId 之一存在)且未提权,额外在 warning 返回 overlay_unavailable。非 Windows 走 Command::spawn 并传入 game_arguments。实际实现在 launch_game(launcher.rs:477),供静默启动直接调用。启动前先以应用权限调用 process::terminate_processes;应用未提权时它无法结束上一局由提权进程创建的残留(结果为 AccessDenied,仅记 debug),提权 helper 在创建新游戏前会再调用一次同一原语清理。
  • 并发保护:static LAUNCH_IN_FLIGHT(launcher.rs:405)保证同一时刻只有一次启动,避免重复点击弹出两次 UAC / 留下两套挂起的父进程。

launcher_start_game 的 message / warning token 契约

message(失败时)与 warning(回退提示)都是 "<token>: <detail>" 形式:token 由前端映射到 i18n 文案(src/utils/launcherService.ts 的 LAUNCH_TOKEN_KEYS),detail 是后端给的技术细节(英文诊断、Win32 码)。

token 含义 触发点
not_found 游戏可执行文件不存在 命令内 exe 存在性检查
no_launcher 未找到签名有效的官方启动器 official_launcher::find_official_launcher
cancelled 用户在 UAC 上点了「否」 ShellExecuteExW → ERROR_CANCELLED(1223)
create 创建启动器父进程 / 游戏进程失败 helper 退出码 2 / 4
wait_failed 等待游戏退出失败 helper 退出码 8
fallback 已回退到直接启动(warning 字段专用,不是失败) no_launcher 回退成功后
overlay_unavailable Steam 未提权,Overlay 无法注入到管理员游戏(warning 字段专用,不是失败) Steam 启动上下文 + 当前进程未提权
unknown 其它(含 helper 提前退出的未知码、启动中重复点击) 兜底

launcher_browse_folder

  • 位置:launcher.rs:658(同步);参数:无;返回:Result<Option<String>, String>;逻辑:rfd::FileDialog::new().set_title("Select Game Directory").pick_folder(),取消返回 None。

launcher_get_disk_space

  • 位置:launcher.rs:675(async)
  • 参数:path: String
  • 返回:Result<DiskSpace, String>({total, free} 字节)
  • 逻辑:沿 ancestors() 找第一个存在的根路径,Windows 下起 powershell -NoProfile -Command "Get-PSDrive …" 解析 Used|Free 并相加得 total;非 Windows 返回 u64::MAX 占位。

launcher_scan_install_dir

  • 位置:launcher.rs:734(async);参数:service、channel、install_path;返回:Result<FileScanResult, String>;逻辑:GameLauncherService::scan_install_dir(&ch, &install_path) 扫描已有文件完整性。

launcher_detect_channel

  • 位置:launcher.rs:770(async);参数:install_path: String;返回:Result<Option<String>, String>
  • 逻辑:先按游戏分派(Endfield.exe+Endfield_Data / Arknights.exe+Arknights_Data,两者都要有 config.ini,否则 None):
    • 明日方舟(Arknights.exe+Arknights_Data):用 read_config_profile(launcher.rs:730)解密 config.ini 读 appcode/channel,channel=2 → arknights_bilibili,其余 → arknights。官方两个渠道共用同一 appcode GzD1CpaWgmSq1wew,只有 channel 能区分。
    • 终末地:先按特征 DLL 判定 glextra.dll+play_pc_sdk.dll+manifest.xml → google_play,gfsdk.dll+glfoundation.dll → global,PCGameSDK.dll → bilibili,hgsdk.dll → official;都认不出时回退到 config.ini 的 channel(appcode 必须等于 6LL0KJuqHBVz33WK)。
  • 纯本地,不联网。config.ini 是固定 AES-256-CBC 加密的渠道档案(与 game_files 同一套密钥),比特征 DLL 更权威。

launcher_check_executable

  • 位置:launcher.rs:845(同步);参数:install_path: String、channel: String;返回:Result<bool, String>;逻辑:parse_channel → Path::exists 判断渠道对应 exe 是否存在。

launcher_check_game_running

  • 位置:launcher.rs:853(异步);参数:channel: String;返回:Result<bool, String>;逻辑:parse_channel → utils::process::is_process_running(ch.process_name())(进程快照取得同名 PID,任一 PID 拥有顶层窗口或在 90 秒启动宽限内才视为运行中;无窗口的崩溃/挂起残留返回 false)。前端游戏面板每 3 秒调用;快照与窗口判定在 spawn_blocking 中执行,不阻塞 Tauri 主线程。

launcher_get_game_playtime

  • 位置:launcher.rs:860(同步);参数:无;返回:GamePlaytime({ total_seconds, session_seconds, running });逻辑:utils::game_playtime::snapshot(),返回累计总时长(不含当前会话)+ 当前会话时长 + 运行态。由后台探测任务 utils::game_playtime 维护,仅在 EndProtocol 运行期间统计。

launcher_kill_game

  • 位置:launcher.rs:873(async)
  • 参数:channel: String
  • 返回:Result<bool, String>(true = 进程已结束;false = 本来就没有同名进程;失败时 Err("<token>: <detail>"),token 为 cancelled / kill_failed / unknown)
  • 逻辑:parse_channel → spawn_blocking 里先 process::exists_once(单次快照预检,无残留直接返回 false),再走 official_launcher::kill_game_process:① 就地 process::terminate_processes(原生快照 + OpenProcess(PROCESS_TERMINATE)/TerminateProcess,含后代进程树;Terminated/Nothing 到此为止,不弹 UAC);② 结果为 AccessDenied 或 StillRunning 时用 ShellExecuteExW("runas") 以 --endfield-kill-helper --name <Endfield.exe> 重启自身(crate::run 在 logger/Tauri 初始化前由 try_run_kill_helper 截获),并阻塞等待 helper 退出码(上限 10 秒)。游戏由提权 helper 创建,未提权的 TerminateProcess 只会拿到 ERROR_ACCESS_DENIED —— 这正是旧实现「点了停止没反应」的原因;AccessDenied 由 TerminateOutcome 直接给出,因此不需要再等一轮存活轮询(旧实现的两轮 has_processes + taskkill 子进程合计约 10 秒,是「UAC 弹得慢」的主因)。旧实现的 wmic 兜底已移除(wmic 在新版 Windows 已弃用,且同样过不了权限边界)。

launcher_switch_channel

  • 位置:launcher.rs:912(async)
  • 参数:service、from_channel: String、to_channel: String、install_path: String、app: AppHandle
  • 返回:Result<String, String>(成功消息)
  • 逻辑:两个 channel 都经 parse_channel 校验,然后 GameLauncherService::switch_channel(&from, &to, &install_path, app).await(service 内部可用 app emit 进度/事件)。

src-tauri/src/commands/diagnostics.rs

职责:崩溃处理与诊断导出 IPC(48 行 / 6 个命令)。转发到 utils::crash、utils::api_health、utils::diagnostics。

get_log_dir

  • 位置:diagnostics.rs:7(同步)
  • 参数:无
  • 返回:Result<String, String>
  • 逻辑:utils::paths::log_dir() 返回应用日志目录;前端配合 revealItemInDir 打开。

export_diagnostics

  • 位置:diagnostics.rs:15(同步)
  • 参数:app: AppHandle、frontend_logs: Vec<FrontendLogEntry>、context: Option<String>(前端 invoke 传 frontendLogs / context)
  • 返回:Result<String, String>(zip 文件绝对路径)
  • 逻辑:utils::diagnostics::export 打包前端日志、后端内存日志、日志文件、崩溃报告与 manifest。

get_pending_crash_reports

  • 位置:diagnostics.rs:25(同步)
  • 参数:无
  • 返回:Vec<CrashReportInfo>
  • 逻辑:utils::crash::pending_reports;启动时前端若拿到非空列表则弹出「上次运行异常退出」提示。

ack_crash_reports

  • 位置:diagnostics.rs:31(同步)
  • 参数:paths: Vec<String>
  • 返回:Result<(), String>
  • 逻辑:utils::crash::acknowledge 在崩溃报告旁写 .log.ack,避免下次启动重复提示。

get_api_health

  • 位置:diagnostics.rs:37(同步)
  • 参数:无
  • 返回:ApiHealthSnapshot
  • 逻辑:utils::api_health::snapshot;前端在启动阶段轮询作为事件漏收兜底。

reset_api_health

  • 位置:diagnostics.rs:43(同步)
  • 参数:无
  • 返回:()
  • 逻辑:utils::api_health::reset;用户点击「已修复,重试」后解除熔断,随后前端重载页面。

src-tauri/src/commands/logs.rs

职责:后端日志读取与级别调整(2 个命令)。

get_backend_logs

  • 位置:logs.rs:4,#[tauri::command](同步)
  • 参数:无
  • 返回:Vec<LogEntry>
  • 逻辑:utils::logger::get_logger().get_recent_logs() 返回当前会话的全部内存日志;注意返回类型不是 Result。

set_log_level

  • 位置:logs.rs:11,#[tauri::command](同步)
  • 参数:level: String
  • 返回:Result<(), String>
  • 逻辑:LogLevel::parse(&level)(大小写不敏感,支持 warning)→ utils::logger::set_log_level(parsed) 更新全局原子级别;未知级别返回 "Unknown log level: ..."。持久化由前端 setLogLevel 写入 log_level 配置,后端启动时在 lib.rs setup 中读取。

src-tauri/src/commands/tray.rs

职责:托盘菜单/托盘面板的 IPC(98 行 / 8 个命令)。配置键固定为 tray_user_info(类型 TrayUserInfo),菜单刷新调用 crate::tray 模块的函数。

get_tray_user_info

  • 位置:tray.rs:8(同步)
  • 参数:config_service: State<'_, Arc<std::sync::Mutex<ConfigService>>>
  • 返回:Result<TrayUserInfo, String>
  • 逻辑:ConfigService::get::<TrayUserInfo>("tray_user_info"),缺失时返回 TrayUserInfo::default()。

set_tray_user

  • 位置:tray.rs:19(同步)
  • 参数:app: AppHandle<R>、config_service、role_id: String
  • 返回:Result<(), String>
  • 逻辑:读出已有 tray_user_info(或默认),只改 role_id 字段 → ConfigService::set("tray_user_info", …) 持久化 → crate::tray::update_tray_menu(&app, &user_info) 刷新托盘菜单。
  • 配置键:tray_user_info

update_tray_user_data

  • 位置:tray.rs:45(同步)
  • 参数:app、config_service、user_info: TrayUserInfo
  • 返回:Result<(), String>
  • 逻辑:前端拉到最新数据后整体覆盖写 tray_user_info,再 update_tray_menu 刷新菜单。user_info 由 src/utils/trayService.ts 的 refreshTrayUserData() 组装(含 accountLevel 游戏账号等级与 bpCurLevel/bpMaxLevel 通行证等级)。

show_tray_panel

  • 位置:tray.rs:66(同步);参数:app: AppHandle<R>;返回:Result<(), String>;逻辑:crate::tray::show_tray_panel(&app) 显示托盘浮层窗口。

hide_tray_panel

  • 位置:tray.rs:72(同步);参数:app;返回:Result<(), String>;逻辑:crate::tray::hide_tray_panel(&app)。

show_main_window

  • 位置:tray.rs:78(同步);参数:app;返回:Result<(), String>;逻辑:crate::tray::show_main_window_focus(&app) 显示并聚焦主窗口,随后 hide_tray_panel(&app) 收起浮层。

app_quit

  • 位置:tray.rs:87(同步);参数:app;返回:();逻辑:app.exit(0) 直接退出进程。

tray_available

  • 位置:tray.rs:96(同步);参数:无;返回:bool
  • 逻辑:crate::tray::is_tray_available()。Windows/macOS 托盘恒可用;Linux 上需要托盘构建成功且会话总线里存在 org.kde.StatusNotifierWatcher(GNOME 默认没有,TrayIconBuilder::build() 却会成功),否则返回 false。前端据此隐藏「最小化到托盘」。

src-tauri/src/commands/updater.rs

职责:应用自更新所需的通用原语(下载/写文件/装包,含 10 个命令)。Tauri updater 插件按本机平台检查、验签、安装;Android 单独检查 GitHub Release APK 并由系统安装器确认。另含模块级静态 DOWNLOAD_CANCELLED: AtomicBool 作为下载取消开关。

write_file

  • 位置:updater.rs:150(同步);参数:path: String、data: Vec<u8>;返回:Result<(), String>;逻辑:fs::create_dir_all(parent) 后 fs::write,任意路径皆可写。

get_temp_dir

  • 位置:updater.rs:161(同步);参数:无;返回:Result<String, String>;逻辑:std::env::temp_dir() 字符串化。

fetch_url

  • 位置:updater.rs:203(async);参数:url: String;返回:Result<String, String>;逻辑:capture::send(&client, client.get(&url)) 后 resp.text(),任意 URL 可 GET。

cancel_download

  • 位置:updater.rs:181(同步);参数:无;返回:();逻辑:DOWNLOAD_CANCELLED.store(true, SeqCst),install_update_endpoint 下载循环下次检查时退出并删除半成品文件。

reset_download_cancel

  • 位置:updater.rs:187(同步);参数:无;返回:();逻辑:DOWNLOAD_CANCELLED.store(false, SeqCst),install_update_endpoint 启动前复位。

download_file

  • 位置:updater.rs:195(async)
  • 参数:app: AppHandle、url: String、path: String
  • 返回:Result<u64, String>(写入的总字节数)
  • 逻辑:开始时重置取消标志 → capture::send_stream 取流 → 建父目录与目标文件 → 逐 chunk 写盘,每累计 ≥256KB(或下完)app.emit("download-progress", {downloaded, total});检测到取消标志则删除文件并返回 Err("Download cancelled");结束 flush 并返回字节数。
  • 事件:download-progress

download_android_apk

  • 位置:updater.rs:348(Android async;其他目标为 stub)
  • 参数:app: AppHandle、url: String
  • 返回:Result<String, String>(已下载 APK 的私有缓存路径)
  • 逻辑:URL 白名单由 is_allowed_apk_url 判定——gitHub.com 只接受 /mon3tr-dev/endprotocol/releases/download/ 前缀,镜像 updates.msk-network.cn 只接受 /stable/ 或 /preview/ 前缀,两者都必须以 .apk 结尾且为 https;随后流式下载到 app cache 的 updates 目录,支持 cancel_download,下载失败删除 .part 文件。
  • 事件:download-progress

get_android_abi

  • 位置:updater.rs:300(同步;非 Android 返回 None)
  • 参数:无
  • 返回:Option<String>——Android ABI 名(arm64-v8a / armeabi-v7a / x86 / x86_64)
  • 逻辑:把 std::env::consts::ARCH 映射到 Android 的 ABI 命名。启动的二进制就是所安装 APK 的 ABI,因此不需要 JNI 或 android.os.Build 反射。前端 resolveAndroidAbi 用它从 Release 的拆分 APK 里挑本机那一份(latest.json 的 android.apks[abi])。

check_update_endpoint

  • 位置:updater.rs:58(async)
  • 参数:app: AppHandle、endpoint: String
  • 返回:Result<Option<UpdateEndpointInfo>, String>
  • 逻辑:仅允许稳定/预览镜像、GitHub latest 或指定版本 Release 清单;通过 updater builder 检查本机目标与更新版本。date 字段将插件的 OffsetDateTime 格式化为 RFC 3339(time crate,Cargo.toml 显式依赖 time 0.3 + formatting)——直接 to_string() 产出的是 "2026-11-01 10:09:39.585 +00:00:00" 空格分隔格式,JS new Date() 解析为 Invalid Date。

install_update_endpoint

  • 位置:updater.rs:73(async)
  • 参数:app: AppHandle、endpoint: String
  • 返回:Result<(), String>
  • 逻辑:启动前复位取消标志;仅允许受限端点;流式下载更新包到 temp 文件,下载循环每 chunk 检查 DOWNLOAD_CANCELLED,检测到取消则删除半成品并返回错误;完成后读字节并用 update.install(bytes) 验签安装;期间 app.emit("download-progress", {downloaded, total})。

run_installer

  • 位置:updater.rs:260(windows)/280(not-windows)(async)
  • 参数:app: AppHandle、path: String
  • 返回:Result<(), String>
  • 逻辑:Windows 下以 CREATE_NO_WINDOW 标志静默启动安装器并传 /S(NSIS 静默参数),sleep(2s) 等安装器起来后 app.exit(0) 让出文件占用,由安装器替换并重启应用;非 Windows 返回明确的不支持错误。

src-tauri/src/commands/window.rs

职责:主窗口控制(4 个命令)+ 仪表盘标签页快照(2 个命令)+ 私有辅助函数。窗口命令全部针对标签为 "main" 的窗口,均为同步命令;快照命令 Windows 专用(GDI PrintWindow),非 Windows 返回不支持。

⚠️ 取窗必须用 Manager::get_window,不能用 get_webview_window:get_webview_window 内部先 get_webview(label) 再检查 window.is_webview_window(),后者要求该窗口下所有 webview 的 label 都等于窗口 label(tauri-2.12 src/window/mod.rs:1257)。in-app browser 打开时主窗口 "main" 下多出 label 为 inapp-browser-N 的子 webview,于是 get_webview_window("main") 返回 None,所有窗口命令会静默失效(表现为按钮点了没反应)。Manager::get_window 按窗口 label 查,不受子 webview 影响。

minimize_window

  • 位置:window.rs:33(同步);参数:app: tauri::AppHandle<R>;返回:();逻辑:main_window(&app) → window.minimize()(忽略错误)。

toggle_maximize_window

  • 位置:window.rs:40(同步);参数:app;返回:();逻辑:main_window(&app) → is_maximized()(失败按 false)→ 已最大化则 unmaximize(),否则 maximize()。

close_window

  • 位置:window.rs:51(同步);参数:app;返回:();逻辑:main_window(&app) → window.close(),忽略错误。

minimize_to_tray

  • 位置:window.rs:58(同步);参数:app;返回:Result<(), String>;逻辑:main_window(&app) → window.hide() 隐藏主窗口到托盘,错误转字符串。

save_tab_snapshot

  • 位置:window.rs:80(#[cfg(windows)] 异步)/ 102(非 Windows 桩,返回错误);参数:app、tab_id: String、x/y/width/height: u32(客户区物理像素矩形);返回:Result<String, String>(PNG 路径)。
  • 逻辑:main_window → window.hwnd() → HWND 转 isize 跨线程 → spawn_blocking 内 save_tab_snapshot_sync:GetClientRect 取客户区尺寸并把请求矩形夹进边界 → GetDC/CreateCompatibleDC/CreateCompatibleBitmap → PrintWindow(PW_CLIENTONLY | PW_RENDERFULLCONTENT)(常量 2 由本地定义,windows-sys 0.61 未导出;WebView2 内容必须带该标志否则截成空白)→ GetDIBits(负高度=自顶而下)读回 BGRA → 裁切 + BGRA→RGBA → png crate 编码写盘。
  • 存储:<app_data>/snapshots/<tab_id>-<时间戳>.png;写新前 prune_snapshots 删除同 tab 旧文件(只留最新)。文件名带时间戳:imageCacheManager 与浏览器均按路径缓存图片,新文件名保证重拍后的快照不被陈旧 blob 顶替。
  • 校验:validate_tab_id(≤64 字符、仅字母数字 - _);尺寸 0 或 >8192 拒绝。

delete_tab_snapshot

  • 位置:window.rs:115(同步);参数:tab_id;返回:Result<(), String>;逻辑:校验 id 后 prune_snapshots 删除该标签页全部快照。前端经 tabSnapshotService.deleteTabSnapshotFile 调用(删除标签页时)。

main_window(私有辅助)

  • 位置:window.rs:28;参数:&tauri::AppHandle<R>;返回:Option<tauri::Window<R>>;逻辑:app.get_window("main")。取不到时返回 None,调用方全部静默跳过。

私有辅助(快照相关)

  • snapshots_dir / snapshot_file_name / prune_snapshots / validate_tab_id:路径与命名策略;save_tab_snapshot_sync:GDI 截图 + 裁切 + PNG 落盘主体(仅 Windows 编译)。

src-tauri/src/commands/system_resource.rs

职责:系统资源采集命令入口(1 个命令)。仅做状态取用与线程调度,实际采集逻辑在 services/system_resource_service.rs。

get_system_snapshot

  • 位置:system_resource.rs:9(异步);参数:state: State<Arc<Mutex<SystemResourceService>>>;返回:Result<SystemSnapshot, String>。
  • 逻辑:克隆 Arc → tauri::async_runtime::spawn_blocking 内加锁并调用 SystemResourceService::snapshot(),避免高频轮询阻塞异步运行时;锁/线程错误转 String。
  • 采集内容:CPU(总体/单核使用率、实测频率(PDH % Processor Performance × 标称频率,可用 frequency_is_actual 判断)、温度)、内存/Swap、GPU(nvidia-smi,尽力而为)、磁盘列表(容量/读写速率)、网卡列表(上下行速率/累计),以及 host/os/uptime;部分失败以 errors: Vec<String>(如 gpu_unavailable、no_disk)返回。

src-tauri/src/commands/proxy.rs

职责:设置页「网络」分区的代理专用命令(6 个:4 同步 + 2 async),负责代理配置的读写与生效、系统代理读取、连通性测试、自动嗅探常用代理端口。真正的配置解析与代理构造在 utils/proxy.rs。

get_proxy_settings

  • 位置:proxy.rs:56(同步);参数:state: State<Arc<Mutex<ConfigService>>>;返回:Value。
  • 逻辑:ConfigService::get_proxy_config(),为 None 时返回空配置对象(empty_proxy_config(),enabled:false, type:"http", host:"", port:8080)。

save_proxy_settings

  • 位置:proxy.rs:66(同步);参数:state、config: Value;返回:Result<Value, String>。
  • 逻辑:ConfigService::set_proxy_config(config.clone()) → utils::http_client::set_global_proxy_config(Some(config.clone())) → 回传配置。写盘与全局缓存同时更新,因此保存后无需重启即可对所有已配置代理的 HTTP 请求生效。

clear_proxy_settings

  • 位置:proxy.rs:80(同步);参数:state;返回:bool。
  • 逻辑:ConfigService::remove_proxy_config() + 全局代理缓存置 None;锁失败时返回 false 但缓存依旧清空。

read_system_proxy

  • 位置:proxy.rs:14(同步);参数:无;返回:SystemProxyInfo(enabled/proxy_type/host/port/username/password/pac_url/from_env)。
  • 逻辑:utils::proxy::read_system_proxy():Windows 优先读注册表 HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings 的 ProxyEnable/ProxyServer/AutoConfigURL;未启用或无 ProxyServer 时回退环境变量 HTTPS_PROXY/HTTP_PROXY/ALL_PROXY(大小写都认,from_env=true)。PAC 脚本无法解析,只通过 pac_url 回传供界面提示。

test_proxy_connection

  • 位置:proxy.rs:30(async);参数:state、config: Option<Value>、url: Option<String>;返回:Result<TestConnectionResult, String>({status, duration_ms})。
  • 逻辑:config 为空时回退已保存的 proxy_config;utils::proxy::test_connection(&config, &url, 15),默认探测 https://www.gstatic.com/generate_204,能收到任何 HTTP 响应即视为代理可用。

auto_detect_proxy

  • 位置:proxy.rs:58(async);参数:无;返回:Result<ProxyConfigValue, String>({enabled, proxy_type, host, port, username, password, remote_dns, exclude})。
  • 逻辑:utils::proxy::auto_detect_proxy():按顺序探测本地常用代理端口(HTTP 7890/8080/10809/8888/8118/1080,SOCKS5 10808/7891/1080/1081/7890/8080),每个端口对 gstatic 204 与百度两个 URL 用 3 秒超时发起连通性测试(任一 URL 有成功响应即认为该代理可用),首个成功的即返回配置;全部失败则返回错误。

汇总

  • 命令总数:139(account 24、launcher 28、capture 7、gacha 7、tray 8、updater 11、image 6、config 8、proxy 6、window 6、card_config 3、attendance 2、color_picker 2、logs 2、system_resource 1、browser 5、diagnostics 6、startup 7;mod.rs 0。源码 143 处注解,capture_screen/finish_screen_pick/download_android_apk/run_installer/save_tab_snapshot 各含一对 cfg 门控版本,按名去重计;install_apk 由独立 Tauri 插件注册)。
  • 事件 emit:launcher-progress(launcher.rs)、download-progress(updater.rs)。
  • 关键配置键:account_token_*(含 cred/token/hytoken/device_token/roles[]/user_info;roles[] 内含 bindingUid 与 u8Authorized)、selected_account_id、card_settings.{card_id}、tray_user_info、proxy_config(代理设置,写入后同步刷新全局代理缓存),以及前端侧的 system_resource_defaults / todo_lists / todo_defaults(经 config 命令读写);相关本地文件:gacha_avatar_map.json、total.json、backgrounds/bg.webp。
  • 主要状态(managed state):Arc<std::sync::Mutex<ConfigService>>(config/tray/proxy 直接用)、Arc<tokio::sync::Mutex<AccountService>>(account/attendance/card_config/gacha)、Arc<GachaService>、Arc<GameLauncherService>(无外层锁,长任务由内部 write_gate 串行)、Arc<std::sync::Mutex<SystemResourceService>>(见 lib.rs 的 setup)。