MikuMikuAR 文档

Appearance

Go 后端核心（App 生命周期 + 配置系统） ​

系统概览 ​

Go 端唯一的 Wails 绑定服务体（internal/app 包）。App 结构体持有全部后端状态（HTTP 服务表、配置缓存、下载监听器、LLM 取消句柄、日志环形缓冲、广场预热窗口），通过 ServiceStartup/ServiceShutdown 管理生命周期。config.go 实现双层配置持久化（bootstrap + settings）+ 版本迁移。

核心职责 ​

  • app.go — App 结构体 + 生命周期 + 各 Select* 文件对话框入口 + 数据模型（ModelEntry/SoftwareEntry/ModelMeta/UIState/OverridePaths/Config/EnvState/RenderPreset）。
  • config.go — 双层配置读取（configDir()/config.json 引导 → 含 ResourceRoot 时叠加 settingDir()/config.json）、finaliseConfig 迁移（v0→v1 library_root→resource_root）、Android storage mode 同步。
  • log_ring.go — LogRing 环形缓冲（cap 200）+ DualWriter（ring + stderr 双写），供 AI 诊断助手取后端日志（ADR-196/205）。
  • a11y*.go — GetSystemA11ySettings，按平台（windows/其他）返回系统无障碍设置。
  • mpr_on.go/mpr_off.go — 构建标签互斥的 coopCoepEnabled 常量（MPR 多线程 WASM 物理，ADR-099）。

对外 API（节选） ​

  • NewApp(version, buildTime, commitHash) — 构造 App。
  • ServiceStartup(ctx, options) — 恢复下载监听 + 后台清理孤立缓存 + 清理 legacy serve 目录。
  • ServiceShutdown() — 见不变量（watcher→plaza→HTTP 三级关闭）。
  • GetConfig() (*Config, error) — RLock 读取（含缓存）。
  • updateConfig(mutate, rescan) — Lock 写 + 可选重扫模型库。
  • GetBuildInfo() / GetAppVersion() — 构建信息（-ldflags 注入）。

与其他子系统关系 ​

  • 被 Wails 绑定层自动生成（@bindings），前端经 core-backend / wails-bindings 调用。
  • 依赖 internal/dialogs（文件对话框）、internal/util（错误包装/SafeCall）、internal/thumbnail、internal/i18nerr。
  • 持有并驱动 watch.go（watcher）、zipextract.go（HTTP 服务表）、proxy.go、plaza_window.go（预热窗口）。

前端接入入口 ​

  • 前端通过 @/core/wails-bindings（代理化，ADR-176）调用全部绑定。
  • 设置页：frontend/src/menus/settings-system.ts（无障碍/系统设置）、settings-about.ts（GetBuildInfo）。
  • AI 诊断：AiGetBackendLogs / AiGetBackendState 供 settings-diagnostic 面板使用。

不变量 ​

  • 配置单写者：任何 Set*/配置变更必须经 updateConfig(mutate, rescan)，禁止在 config.go 外直接改字段。
  • 生命周期配对：ServiceStartup 里 go func 启动的后台任务不要求同步阻塞，但 Shutdown 必须清理所有可回收资源。
  • 平台分支用 isAndroid 变量 + 文件名后缀构建标签（_desktop/_android/_windows）。

验证入口 ​

  • 测试：internal/app/app_test.go、internal/app/shutdown_test.go。
  • 命令：go test ./internal/app/。