背景
我对当前 Amadeus 在 Linux 下的安装、后端、Electron、角色渲染、语音、VAD、本地模型和动态壁纸等路径进行了一轮实机验证。
本轮工作的主要目标不是重新实现一套 Linux runtime，而是确认当前项目已有能力在 Linux 下的实际状态，并逐步将 Linux 的兼容性和维护程度完善到接近当前 Windows / macOS 的水平。
主要关注：
- 当前哪些功能已经可以直接在 Linux 下工作；
- 哪些问题会阻塞标准安装或正常使用；
- 哪些已有能力缺少 Linux CI、依赖 profile 或使用文档；
- 哪些问题属于真正的平台边界，需要 Linux-specific implementation；
- 在尽量不影响现有 Windows / macOS 路径的前提下建立长期可维护的 Linux 支持。
目前的总体结论是：
Amadeus 的大部分核心路径已经具备较好的跨平台基础。Linux 当前更主要缺少持续集成、依赖配置、文档和正式 qualification，而不是需要进行大规模的平台移植。
验证环境
本轮主要实机环境：
- Arch Linux
- Linux Zen kernel
- Python 3.12 project environment
- uv
- Electron
- Wayland
- niri
- NVIDIA RTX 4060 Laptop GPU 8GB
另外对 GNOME Wayland 下的动态壁纸路径进行了实际验证。
需要说明的是：
- Arch Linux 是本轮主要实机验证环境；
- 当前结果不能直接代表所有 Linux 发行版；
- 对发行版相关问题会尽量区分 Linux 通用问题和 rolling-release / 新 toolchain 问题；
- KDE 等其他桌面环境目前尚未进行实机 qualification；
- Linux 兼容工作会尽量复用现有跨平台实现，不计划为了 Linux 改变已经正常工作的 Windows / macOS 行为。
当前验证结果
| 能力 |
Linux 状态 |
说明 |
| L1 Core / Backend |
通过 |
locked environment、server import、backend、WebSocket 均正常 |
| Electron build |
通过 |
npm ci / npm run build 正常 |
| Electron desktop |
通过 |
Wayland 实机启动、backend discovery、GUI 渲染正常 |
| Character rendering |
通过 |
SpriteForge / KTX2 / PixiJS 实际显示正常 |
| L2 Voice runtime |
部分通过 |
runtime 可运行，但标准 voice extra 被 AEC dependency 阻塞 |
| L3 CPU VAD |
通过 |
verifier 和实际语音片段检测均正常 |
| GPT-SoVITS CUDA TTS |
实验验证通过 |
Linux + NVIDIA 实机推理成功，但当前 dependency profile 尚未正式覆盖 Linux |
| Qwen3-ASR CUDA |
实验验证通过 |
Linux + NVIDIA 实机识别成功 |
| GNOME Wayland Wallpaper |
实验验证通过 |
通过兼容的 Web wallpaper host 可正常运行 |
| niri Wallpaper |
未 qualification |
涉及 layer-shell / interactive overlay 等 compositor-specific 集成 |
| Linux CI |
正在补充 |
第一阶段 Core qualification workflow 已准备 |
1. L1 Core / Backend
L1 是目前最明确的 Linux 兼容路径。
以下流程已经在 Linux 实机通过：
uv venv .venv --python 3.12
uv sync --locked
环境验证：
uv run --locked --no-sync \
python tools/verify_python_environment.py --profile cpu
后端可以正常启动：
uv run --locked --no-sync \
python -m server.app --port 17777
WebSocket handlers、runtime.status、capability.list 等基础路径均正常。
目前没有发现需要 Linux-specific runtime implementation 的问题。
因此这里的优先工作不是增加新的 Linux Core 实现，而是通过 CI 固化当前已经存在的跨平台能力，避免后续修改产生 Linux regression。
2. Electron / Character Rendering
Electron renderer 可以在 Linux 正常构建：
cd electron
npm ci
npm run build
在 Wayland 实机环境中，Electron desktop 可以正常：
- 自动发现
.venv/bin/python3
- 启动 Python backend
- 建立 WebSocket 连接
- 渲染主界面
- 使用主要页面和基础功能
角色渲染链路也已经完成实机验证：
KTX2 assets
↓
SpriteForgeAnimator
↓
RenderHandler
↓
PixiJS
↓
Electron renderer
↓
visible character
Kurisu 角色可以在 Linux Electron 界面中实际显示并播放动画。
目前没有发现需要单独维护 Linux renderer implementation 的问题。
后续重点是补充 Linux desktop qualification，并在必要时处理真正属于 OS integration 的差异。
3. L2 Voice：AEC dependency 阻塞标准安装
这是目前发现的最明确的 Linux dependency 问题。
在当前 Arch Linux toolchain 下：
uv sync --locked --extra voice
会在：
aec-audio-processing==1.0.1
编译阶段失败。
当前测试环境使用较新的 GCC / Abseil，aec-audio-processing 内置的 WebRTC 代码仍使用旧的 absl::Nullable<T*> API，与当前 Abseil headers 不兼容。
进一步验证发现：
- PyAudio 可以正常安装；
av 可以正常安装；scipy 可以正常安装；soundfile 可以正常安装；- voice verifier 可以通过；
- backend 在缺少 AEC 时可以正常降级为
aec realtime enabled=False；
- 当前 server runtime 未发现对
aec-audio-processing 的直接强制 import。
因此目前需要进一步明确这里的 dependency contract：
AEC 应该作为 L2 Voice 的 mandatory dependency，还是作为 optional capability？
该问题计划单独建立 Issue 处理。
根据最终确定的 dependency contract，再决定是：
- 保持 mandatory 并解决当前 toolchain compatibility；
- 将 AEC 拆分为 optional extra；
- 或采用其他更合适的依赖组织方式。
目前只确认该问题会在本次 Arch / 新 toolchain 环境触发，因此暂不将其描述为所有 Linux 发行版都会遇到的问题。
4. L3 CPU VAD
CPU VAD 已经在 Linux 实机验证。
使用 CPU PyTorch 环境后：
python tools/verify_python_environment.py --profile vad-cpu
可以正常通过。
另外使用实际语音素材进行了 Silero VAD 推理，可以正常检测 speech segments。
因此目前没有发现 L3 本身存在 Linux runtime compatibility 问题。
后续工作主要是逐步补充对应的 Linux dependency / qualification 路径，而不是增加 Linux-specific VAD implementation。
5. L4 NVIDIA CUDA
Linux + NVIDIA 下已经实际完成：
- GPT-SoVITS CUDA TTS
- Qwen3-ASR CUDA inference
本轮测试硬件：
NVIDIA RTX 4060 Laptop GPU 8GB
两条实际推理路径均成功。
但这里需要区分：
Linux + NVIDIA runtime 可以工作，并不代表当前 local-cu124 dependency profile 已经正式覆盖 Linux。
当前项目的 cu124 dependency routing 仍主要面向现有 Windows + NVIDIA 路径。
Linux 实机验证中，需要显式安装正确的 CUDA PyTorch build，才能得到实际可用的 CUDA environment。
因此目前更准确的状态是：
Linux NVIDIA runtime 已经实验验证，但尚缺少能够稳定复现该环境的正式 dependency profile。
后续计划单独处理 Linux NVIDIA dependency profile，使：
clean install
↓
correct CUDA PyTorch build
↓
environment verification
↓
local inference
成为可重复的标准流程，而不是依赖手工修正环境。
第一阶段 Linux CI 暂不加入 CUDA qualification。
6. Linux Desktop / Wallpaper
Wallpaper 与 Core Linux compatibility 分开考虑。
它除了 Amadeus 本身的 Web runtime 外，还受到 Linux desktop environment / Wayland compositor 的窗口模型影响，因此不适合简单地用一个统一的 Linux platform branch 处理。
GNOME Wayland
在 GNOME Wayland 环境中，通过兼容的 Web wallpaper host 已经实际验证：
- Amadeus Web wallpaper 可以加载；
- 角色动画正常；
- 动态状态可以更新；
- voice-triggered subtitle 可以更新。
这至少说明 Amadeus Web wallpaper frontend 本身不存在普遍性的 Linux / Wayland incompatibility。
niri
niri 下目前仍属于实验状态。
现阶段已经确认：
- Web wallpaper 内容本身可以运行；
- layer-shell 可以提供真正的 background layer；
- 普通 Wallpaper Engine Web wallpaper 可以通过对应 host 在 niri 下运行。
但 Amadeus 当前 wallpaper architecture 还涉及额外的透明 interactive overlay。
在 niri 这样的 standalone Wayland compositor 下，这会进一步涉及：
- layer-shell
- input handling
- overlay window semantics
- compositor-specific window management
目前实验 wrapper 本身也仍存在尚未定位的问题，因此现阶段不能将结果直接归因为 Amadeus runtime bug。
所以：
standalone Wayland compositor 的 wallpaper integration 暂时不作为 Linux Core compatibility 的 blocker。
后续如果继续处理，会优先考虑清晰的平台集成边界，而不是在 Core / renderer 中加入大量针对不同 compositor 的条件分支。
7. Linux CI
第一阶段已经准备新增：
.github/workflows/python-linux.yml
这一阶段的目的不是通过一条 CI workflow 宣布完整 Linux support，而是先为已经确认可工作的 Linux Core 路径建立 regression baseline。
初始 workflow 使用：
- Ubuntu 24.04
- Python 3.12.10
- uv 0.12.8
- Node.js 22.21.1
覆盖：
- locked L1 + dev installation
ci environment verifier- L1 model-less dependency contract
- Ruff
- architecture view check
- platform-safe contract test subset
- Electron renderer build
第一阶段暂不覆盖：
- Voice / AEC
- VAD
- CUDA
- GUI runtime
- Wayland session
- Wallpaper
这些能力会根据实际 Linux qualification 结果逐步纳入，而不是在第一条 CI 中一次性扩大范围。
对应的第一阶段 PR 保持为独立 CI change，不修改 runtime 和现有平台行为。
后续工作计划
当前 Linux 兼容工作的目标是逐步补齐与现有 Windows / macOS 路径之间的差距，而不是额外建立一套独立的 Linux runtime。
计划按照以下顺序推进。
P0：Linux Core CI
首先建立 Linux L1 / Electron build qualification。
目标：
将目前已经验证可运行的 Linux Core 路径变成持续的 regression contract。
对应的第一阶段 CI PR 已准备。
P0：AEC dependency
单独处理当前 aec-audio-processing 对标准 Voice 安装造成的阻塞。
首先明确 AEC 在 L2 中的 dependency contract，再根据结果实现对应修改。
避免为了 Linux 临时绕过依赖，而使不同平台产生难以维护的行为差异。
P1：Linux 使用文档
在基础 CI 稳定后，补充 Linux source deployment / Electron startup 文档。
目标是让 Linux 用户可以按照与当前 Windows / macOS 类似的清晰路径完成：
environment setup
↓
dependency installation
↓
backend startup
↓
Electron startup
尽量减少目前依赖手工排查环境的情况。
P1：Linux NVIDIA dependency profile
基于已经完成的 GPT-SoVITS / Qwen3-ASR 实机验证，补充可重复的 Linux NVIDIA dependency profile。
重点是解决当前 CUDA runtime 虽然可以工作，但标准 dependency path 尚不能稳定复现实机环境的问题。
P1：Linux Desktop qualification
继续验证和补齐 Electron desktop 在 Linux 下的实际行为，包括：
- backend discovery
- GUI startup
- renderer behavior
- audio path
- 必要的 platform-specific system integration
这里仍优先复用现有跨平台实现。
只有确认某项行为确实属于操作系统边界时，再增加 Linux-specific implementation。
后续：Wayland compositor integration
GNOME 与 standalone Wayland compositor 的 wallpaper hosting 模型存在明显差异。
niri / layer-shell / interactive overlay 等问题后续单独研究。
这一部分属于 desktop integration，而不是当前 Core Linux compatibility 的前置条件。
当前结论
目前没有发现 Amadeus 需要进行一次大规模的 Linux port。
相反，本轮实机验证表明：
- Core / Backend 已经可以工作；
- Electron desktop 已经可以工作；
- Character Rendering 已经可以工作；
- CPU VAD 已经可以工作；
- NVIDIA TTS / ASR runtime 已经可以工作；
- Web Wallpaper frontend 也已经在 Linux 桌面环境中得到实际验证。
因此当前 Linux 兼容工作的重点，是把这些已经存在的跨平台能力逐步补齐到接近当前 Windows / macOS 的支持和维护程度。
近期主要工作集中在：
- Linux CI qualification；
- Voice / AEC dependency；
- Linux NVIDIA dependency profile；
- Linux source deployment / startup 文档；
- Electron desktop qualification；
- 必要的 desktop environment / compositor integration。
后续 Linux 兼容工作会尽量遵循一个原则：
优先固化已有跨平台能力，只在确实属于平台边界的位置增加 Linux-specific implementation。
这样可以在完善 Linux 兼容性的同时，尽量降低长期维护成本，并避免对现有 Windows / macOS 路径造成不必要的影响。
背景
我对当前 Amadeus 在 Linux 下的安装、后端、Electron、角色渲染、语音、VAD、本地模型和动态壁纸等路径进行了一轮实机验证。
本轮工作的主要目标不是重新实现一套 Linux runtime，而是确认当前项目已有能力在 Linux 下的实际状态，并逐步将 Linux 的兼容性和维护程度完善到接近当前 Windows / macOS 的水平。
主要关注：
目前的总体结论是：
验证环境
本轮主要实机环境：
另外对 GNOME Wayland 下的动态壁纸路径进行了实际验证。
需要说明的是：
当前验证结果
npm ci/npm run build正常voiceextra 被 AEC dependency 阻塞1. L1 Core / Backend
L1 是目前最明确的 Linux 兼容路径。
以下流程已经在 Linux 实机通过：
环境验证：
后端可以正常启动：
WebSocket handlers、
runtime.status、capability.list等基础路径均正常。目前没有发现需要 Linux-specific runtime implementation 的问题。
因此这里的优先工作不是增加新的 Linux Core 实现，而是通过 CI 固化当前已经存在的跨平台能力，避免后续修改产生 Linux regression。
2. Electron / Character Rendering
Electron renderer 可以在 Linux 正常构建：
cd electron npm ci npm run build在 Wayland 实机环境中，Electron desktop 可以正常：
.venv/bin/python3角色渲染链路也已经完成实机验证：
Kurisu 角色可以在 Linux Electron 界面中实际显示并播放动画。
目前没有发现需要单独维护 Linux renderer implementation 的问题。
后续重点是补充 Linux desktop qualification，并在必要时处理真正属于 OS integration 的差异。
3. L2 Voice：AEC dependency 阻塞标准安装
这是目前发现的最明确的 Linux dependency 问题。
在当前 Arch Linux toolchain 下：
会在：
编译阶段失败。
当前测试环境使用较新的 GCC / Abseil，
aec-audio-processing内置的 WebRTC 代码仍使用旧的absl::Nullable<T*>API，与当前 Abseil headers 不兼容。进一步验证发现：
av可以正常安装；scipy可以正常安装；soundfile可以正常安装；aec realtime enabled=False；aec-audio-processing的直接强制 import。因此目前需要进一步明确这里的 dependency contract：
该问题计划单独建立 Issue 处理。
根据最终确定的 dependency contract，再决定是：
目前只确认该问题会在本次 Arch / 新 toolchain 环境触发，因此暂不将其描述为所有 Linux 发行版都会遇到的问题。
4. L3 CPU VAD
CPU VAD 已经在 Linux 实机验证。
使用 CPU PyTorch 环境后：
可以正常通过。
另外使用实际语音素材进行了 Silero VAD 推理，可以正常检测 speech segments。
因此目前没有发现 L3 本身存在 Linux runtime compatibility 问题。
后续工作主要是逐步补充对应的 Linux dependency / qualification 路径，而不是增加 Linux-specific VAD implementation。
5. L4 NVIDIA CUDA
Linux + NVIDIA 下已经实际完成：
本轮测试硬件：
两条实际推理路径均成功。
但这里需要区分：
当前项目的 cu124 dependency routing 仍主要面向现有 Windows + NVIDIA 路径。
Linux 实机验证中，需要显式安装正确的 CUDA PyTorch build，才能得到实际可用的 CUDA environment。
因此目前更准确的状态是：
后续计划单独处理 Linux NVIDIA dependency profile，使：
成为可重复的标准流程，而不是依赖手工修正环境。
第一阶段 Linux CI 暂不加入 CUDA qualification。
6. Linux Desktop / Wallpaper
Wallpaper 与 Core Linux compatibility 分开考虑。
它除了 Amadeus 本身的 Web runtime 外，还受到 Linux desktop environment / Wayland compositor 的窗口模型影响，因此不适合简单地用一个统一的 Linux platform branch 处理。
GNOME Wayland
在 GNOME Wayland 环境中，通过兼容的 Web wallpaper host 已经实际验证：
这至少说明 Amadeus Web wallpaper frontend 本身不存在普遍性的 Linux / Wayland incompatibility。
niri
niri 下目前仍属于实验状态。
现阶段已经确认：
但 Amadeus 当前 wallpaper architecture 还涉及额外的透明 interactive overlay。
在 niri 这样的 standalone Wayland compositor 下，这会进一步涉及：
目前实验 wrapper 本身也仍存在尚未定位的问题，因此现阶段不能将结果直接归因为 Amadeus runtime bug。
所以：
后续如果继续处理，会优先考虑清晰的平台集成边界，而不是在 Core / renderer 中加入大量针对不同 compositor 的条件分支。
7. Linux CI
第一阶段已经准备新增：
这一阶段的目的不是通过一条 CI workflow 宣布完整 Linux support，而是先为已经确认可工作的 Linux Core 路径建立 regression baseline。
初始 workflow 使用：
覆盖：
cienvironment verifier第一阶段暂不覆盖：
这些能力会根据实际 Linux qualification 结果逐步纳入，而不是在第一条 CI 中一次性扩大范围。
对应的第一阶段 PR 保持为独立 CI change，不修改 runtime 和现有平台行为。
后续工作计划
当前 Linux 兼容工作的目标是逐步补齐与现有 Windows / macOS 路径之间的差距，而不是额外建立一套独立的 Linux runtime。
计划按照以下顺序推进。
P0：Linux Core CI
首先建立 Linux L1 / Electron build qualification。
目标：
对应的第一阶段 CI PR 已准备。
P0：AEC dependency
单独处理当前
aec-audio-processing对标准 Voice 安装造成的阻塞。首先明确 AEC 在 L2 中的 dependency contract，再根据结果实现对应修改。
避免为了 Linux 临时绕过依赖，而使不同平台产生难以维护的行为差异。
P1：Linux 使用文档
在基础 CI 稳定后，补充 Linux source deployment / Electron startup 文档。
目标是让 Linux 用户可以按照与当前 Windows / macOS 类似的清晰路径完成：
尽量减少目前依赖手工排查环境的情况。
P1：Linux NVIDIA dependency profile
基于已经完成的 GPT-SoVITS / Qwen3-ASR 实机验证，补充可重复的 Linux NVIDIA dependency profile。
重点是解决当前 CUDA runtime 虽然可以工作，但标准 dependency path 尚不能稳定复现实机环境的问题。
P1：Linux Desktop qualification
继续验证和补齐 Electron desktop 在 Linux 下的实际行为，包括：
这里仍优先复用现有跨平台实现。
只有确认某项行为确实属于操作系统边界时，再增加 Linux-specific implementation。
后续：Wayland compositor integration
GNOME 与 standalone Wayland compositor 的 wallpaper hosting 模型存在明显差异。
niri / layer-shell / interactive overlay 等问题后续单独研究。
这一部分属于 desktop integration，而不是当前 Core Linux compatibility 的前置条件。
当前结论
目前没有发现 Amadeus 需要进行一次大规模的 Linux port。
相反，本轮实机验证表明：
因此当前 Linux 兼容工作的重点，是把这些已经存在的跨平台能力逐步补齐到接近当前 Windows / macOS 的支持和维护程度。
近期主要工作集中在：
后续 Linux 兼容工作会尽量遵循一个原则：
这样可以在完善 Linux 兼容性的同时，尽量降低长期维护成本，并避免对现有 Windows / macOS 路径造成不必要的影响。