Amadeus: Real-Time Multimodal AI Agent for Desktop Interaction

一层面向本地 AI OS 的交互界面

中文 | English

_{点击画面观看 10 分钟完整演示}

0.15 Alpha：路由权威、开关与验收范围

[!IMPORTANT] 本仓库包含可构建、可运行的公开源码，本分支为 0.15 Alpha 候选版， 不是带安装器的正式桌面发行版。Amadeus 第一方代码依据 GNU Affero General Public License v3.0（AGPL-3.0） 开源。 第三方代码与外部资产保留各自条款。

想先跑起来？ → 快速开始。想先了解项目，从 Amadeus 想解决什么 开始。

Amadeus 想解决什么

语音助手、桌面角色与执行型 Agent 往往分散在不同窗口：一个负责聊天，一个 负责表演，另一个在终端或浏览器中工作。长任务开始后，用户又很难知道它进行 到了哪里、需要什么权限，以及失败后能否继续。

Amadeus 试图把这些体验连成一个闭环：

1. Talk — 自然交流：语音或文字对话，并能在生成、合成和真实播放过程中随时打断。
2. Embody — 角色具身：语音、字幕、口型、表情和场景行为沿同一条播放时间线发生。
3. Act — 委派执行：主角色把工作交给注册的 Work Provider，而不是直接获得所有工具。
4. Control — 保持掌控：Project、Draft、Artifact、进度、权限、Diff 和结果保持可见，并可继续、重试或接管。

角色负责交流和叙述，专业 Provider 负责执行，Host 负责身份、状态、权限、 持久化与恢复。

演示切片

实时对话与角色表现	场景化工作状态
语音、字幕、口型与表情绑定到真实播放进度。	后台任务驱动角色行为、场景状态和结果叙述。

演示视频展示了实时语音、角色表现、桌面场景、Browser / OpenClaw 任务以及 论文检索流程。当前源码的桌面界面、Provider 接入和资产边界已经继续演进， 视频应被视为一次产品切片，而不是逐像素安装预览。

[!NOTE] 演示中的角色、场景、声音及其他第三方素材只用于展示原型，不属于 Amadeus 代码许可证授权范围。公开源码不包含未获得再分发许可的角色包、模型权重、 参考音频或创作中间资产。

当前核心能力

MCP 与 Skills 即使共用 Host registry，也只授予兼容 Provider；Main Chat 不能直接调用 MCP 工具。远程 DeepSeek 是主 Chat 基线；远程 ASR/TTS 是显式 兼容路径，不会在本地语音失败后静默上传或产生第二笔计费请求。

仓库地图

electron/       Electron main、preload、React renderer 与 Settings
server/         认证后的本地后端、Host 控制面与 AUIP
core/           Main Chat runtime 与会话集成
agent_host/     Provider contracts、adapters、Work identity 与 capabilities
asr/            Conversation / Wake 识别后端
tts/            合成后端、分句 pipeline、播放与口型信号
render/         SpriteForge runtime adapter 与 PixiJS renderer
wallpaper/      Electron/Lively host 与 Win32 桌面放置
vn_player/      Experimental VN Player integration
assets/         Git-owned UI 资产与外部 runtime 资产落点
release/        公开源码选择、provenance 与 deterministic archive policy

main.py 不是应用入口，只输出退役提示。Python 主入口是 uv run --locked --no-sync python -m server.app --port 17777，桌面入口是 Windows run_electron_utf8.bat / macOS npm run electron:dev（自动发现 .venv，L1–L4 通用）。

系统架构

图中有三个刻意的“不合并”：

• Main Chat、Work Provider 与 AUIP application 是不同权限域；
• MCP/Skills 不会因为 registry 共用而直接暴露给 Main Chat；
• Artifact、identity、permission 与 receipt 是 Host 核验的事实，模型叙述不能替代。

当前 Codex 由 App Server 或 Direct transport 接入，不依赖旧 Locus 网关。 Claude CLI 将在后续作为独立 direct Provider 进入同一边界，而不是恢复 Locus。

AUIP 应用会话（application sessions）

AUIP 是 Amadeus 的 cooperative application protocol，不是 Provider、MCP 或主 Chat 工具系统。它解决的是：当 Work 已生成一个可运行 Artifact，用户如何在 保留 Host 权限边界的前提下，继续让 Amadeus 与这个应用协作。

verified Work Artifact
  -> Host prepares a short-lived attach ticket
  -> application registers declared state/events/actions
  -> bounded AppSession
  -> character receives scoped projection and action receipts

• ticket 绑定当前 Session、不可变 Artifact 引用与有效期；应用提交 Artifact id，而不是任意路径。
• Host 校验 workspace 归属、类型、digest 和启动入口，并拥有 AppSession identity、revision 与 action authority。
• 应用只能发布 manifest 中声明的状态和语义事件，只能接收已声明且经过授权的 typed action。
• AUIP 不授予 work.*、provider.*、tts.*、任意文件系统或其他 Session 权限。
• 断连成为可见状态并使待确认动作失效，不会在陈旧状态上静默继续。

当前 schema 是实验性的 amadeus.auip/v0；协议实现、Web SDK、 Managed Core、应用示例和集成测试均位于本仓库。详见 AUIP 应用会话文档。 Code-Amadeus/AUIP 维护协议现状、实现入口与 后续 SDK 发布条件；目前尚未发布独立版本的 SDK 或独立 conformance suite。

快速开始

依赖按能力分四级：先装最小的 L1 跑通，再按需升梯（默认阶梯中 torch 在 L3/L4 进入安装；可选 RAG 也会引入 本地 embedding/Torch 依赖）。Windows 是当前参考平台，macOS 的 L1/L2 安装与 CI 单独验证；实际 桌面、麦克风和播放体验仍需设备验收。L3 可选择 CPU VAD，无需 NVIDIA GPU； L4 的当前 cu124 配置面向 Windows + NVIDIA。Windows ROCm 7.2.1 已有互斥的 local-rocm 实验锁与验证入口，但尚未完成受支持 AMD GPU 的端到端验收；RTX 50 系 cu128 与 Apple Silicon MPS 已提供实验安装配置。 统一使用 uv 与 Python 3.12，CI 固定 uv 0.12.8。

Linux 用户请从下方的 Linux（实验性） 章节开始。

各安装配置均使用同一个 .venv。每次给出完整目标配置： uv sync 会精确同步，漏带会移除已装层。torch-cpu、local-cu124、local-cu128、local-mps 与 local-rocm 两两互斥；切换构建时替换对应 extra，并保留 voice、vad。 详见安装配置与迁移。

• 主 Chat 默认远程 DeepSeek；llama.cpp 是可选本地 LLM profile（见 兼容路径），不是安装前提。
• L2 无 vad 层时，语音端点自动降级为能量检测；安装 vad 后恢复 silero 精准端点与打断。
• Windows 上每装完一级可验证导入合同（ci 同 cpu）： uv run --locked --no-sync python tools/verify_python_environment.py --profile <cpu|voice|vad-cpu>， L4 用 --profile cu124 --require-cuda-device；ROCm 实验入口用 --profile rocm 并继续执行 GPU compute probe。导入/构建验证不替代真实模型与音频设备测试。
• 纯文字 / headless（CI）场景用 L1 即可：uv run --locked --no-sync python -m server.app --port 17777 直接启动后端；严格文字模式设置 TTS_BACKEND=disabled 并关闭 Wake。

参考硬件

L1/L2（Windows / macOS）

• CPython 3.12（由 uv 管理，无需系统安装）
• Node.js 22（当前参考 22.21.1）
• 无 GPU 要求

L4 cu124（Windows 本地模型）追加

• CUDA 12.4-compatible NVIDIA GPU，目标 8 GiB VRAM
• 16 GiB 内存起步，32 GiB 推荐

具体峰值取决于本地 ASR/TTS 模型与并发配置；8 GiB / 16–32 GiB 描述的是远程 Chat + 本地语音配置。选用本地 LLM 时需要按模型、量化、 context 和 GPU offload 另行评估内存。

基础环境（L1/L2，Windows / macOS）

安装 uv（Windows：winget install astral-sh.uv；macOS：brew install uv）， 然后克隆并按梯级安装——两个平台的命令完全一致：

git clone https://github.com/Code-Amadeus/Amadeus.git
cd Amadeus

uv venv .venv --python 3.12
uv sync --locked                              # L1 core
uv sync --locked --extra voice                # L2 voice（可选）

macOS 上 PyAudio（L2 语音采集）从源码编译，需要先 brew install portaudio。

venv 固定命名为 .venv：Electron 启动器会自动发现它（Windows Scripts\python.exe，macOS bin/python3），无需手动设置 AMADEUS_PYTHON。

Electron 前端（全平台）：

cd electron
npm ci
npm run build
cd ..

npm ci 会通过项目 postinstall 安装锁定的 Electron 运行时。国内网络可为 npm/Electron 配置镜像（如 ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/）。

Linux（实验性）

Linux 目前属于实验性源码运行路径，尚未纳入完整支持的平台范围。 第一阶段 Linux CI（#63） 已通过 Ubuntu 24.04 上的 L1 + dev 锁定安装、环境导入与无模型依赖检查、基础契约测试、 Ruff、架构视图检查及 Electron 构建。另有独立 Voice source-build CI，验证锁定安装、 AEC 导入、bundled Abseil 选择及相关契约。CI 不覆盖 Electron GUI、真实音频设备、 VAD/本地模型推理、Wayland 会话或壁纸集成。 另有 cu128 候选安装、依赖和 CPU VAD 回切检查，均不替代真实 GPU 模型验收。

社区已报告 Arch Linux / Wayland 下的桌面与角色渲染等实机结果；这些结果不代表 所有发行版或桌面环境均已验证。环境记录、已知问题和后续进展见 Linux 跟踪 issue #64。

先安装 Git、uv（CI 使用 0.12.8）和 Node.js 22 （CI 使用 22.21.1），从无需 GPU 或语音包的 L1 开始：

git clone https://github.com/Code-Amadeus/Amadeus.git
cd Amadeus
uv venv .venv --python 3.12.10
uv sync --locked
cp .env.example .env

编辑 .env，填写 DEEPSEEK_API_KEY，设置 TTS_BACKEND=disabled，并保持 WAKE_ENABLED=false，先验证文字路径。然后在项目根目录检查环境：

uv run --locked --no-sync python tools/verify_python_environment.py --profile cpu

在 Linux 图形桌面会话中构建并启动 Electron；启动器会自动发现 .venv/bin/python3 并启动后端：

cd electron
npm ci
npm run build
npm run electron:dev

如只需 headless 后端，可改为在项目根目录运行：

uv run --locked --no-sync python -m server.app --port 17777

需要远程语音、录音和播放时，可在同一 .venv 安装 L2。Ubuntu 24.04 先安装 CI 使用的源码构建前置包；其他发行版请使用对应的软件包名称：

sudo apt-get update
sudo apt-get install --no-install-recommends -y build-essential pkg-config portaudio19-dev
uv sync --locked --extra voice
uv run --locked --no-sync python tools/verify_python_environment.py --profile voice

升级到语音或本地模型前，请留意以下实验边界：

• Voice / AEC：Linux 使用基于官方 aec-audio-processing==1.0.1 sdist 的仓库内 源码，强制选择 bundled Abseil 20240722.0，避免选中新版 system Abseil 导致的构建 失败。该修改不更改系统 Abseil；Windows/macOS 继续使用 registry 包。来源、独立 补丁与移除条件见 AEC provenance。 构建/导入通过不代表真实设备上的回声消除或完整语音交互已验收。
• VAD / NVIDIA：Linux CPU VAD 与 local-cu128 候选已有明确的 Torch 构建选择 和安装/契约 CI；cu124 参考配置仍面向 Windows。真实 GPU 模型推理及完整语音 交互继续按设备验收，见下方候选配置说明。
• 桌面 / 壁纸：GUI 与 Wayland compositor 集成仍需分别验收；GNOME 的社区结果 不代表 niri、KDE 或其他桌面也可用。

VAD 与本地模型

与 L1/L2 共用同一个 .venv，选择完整的能力与构建组合：

L3 vad — 实时打断（torch 随之以 CPU 版进入安装）：

uv sync --locked --extra voice --extra vad --extra torch-cpu
uv run --locked --no-sync python tools\verify_python_environment.py --profile vad-cpu

L4 local-cu124 — 本地语音模型栈：在同一 .venv 上选择 CUDA 配置，torch 换为 CUDA 12.4 构建（经 pyproject.toml 的 [tool.uv.sources] 路由到 PyTorch cu124 index，仅 Windows + 本 extra 生效）：

uv sync --locked --extra voice --extra vad --extra local-cu124
uv run --locked --no-sync python tools\verify_python_environment.py --profile cu124 --require-cuda-device

L4 profile 固定 torch==2.6.0+cu124、torchaudio==2.6.0+cu124 和本地模型 依赖集；它以当前实际运行环境为第一版基线。

实验 local-rocm（Windows）：同一 .venv 可精确选择 AMD 官方 ROCm 7.2.1、 Torch/Torchaudio 2.9.1 与完整本地模型依赖；Qwen ASR 和 GPT-SoVITS 在常驻 sidecar 子进程中运行，但默认仍使用当前 .venv 的解释器。该入口默认关闭，且与 cu124/CPU Torch 构建互斥。安装后必须先运行环境验证与真实 FP32 GPU compute probe；即使 torch.cuda.is_available() 返回 True，compute 失败也不得继续模型测试。完整命令、 设备矩阵和验收边界见 Windows ROCm 实验 sidecar。

本机 Radeon 780M（gfx1103）实测可被 ROCm 枚举，但首次 FP32 计算在 AMD HIP DLL 中崩溃；该核显不在 AMD 官方 7.2.1 Windows PyTorch 矩阵内，因此不能作为可用目标。

实验 Torch 2.7 配置：local-cu128（Windows/Linux x86_64）与 local-mps（Apple Silicon）提供锁定的 Torch/Torchaudio 2.7.0 安装入口。 现有 Windows cu124 仍保留为参考配置，Windows ROCm 继续使用 AMD 配套的 2.9.1。

# Windows/Linux NVIDIA 候选，包含完整模型依赖
uv sync --locked --extra voice --extra vad --extra local-cu128
uv run --locked --no-sync python tools/verify_python_environment.py --profile cu128

# Apple Silicon 安装候选
uv sync --locked --extra voice --extra vad --extra local-mps
uv run --locked --no-sync python tools/verify_python_environment.py --profile mps

以上为互斥选择，按当前平台只执行一组。安装检查与 CPU 契约 CI 不代表 GPU 推理、 麦克风、连续播放和打断已验收。#67 报告了 M4 Max 上独立 Qwen-ASR MPS 实测； 当前应用内 Qwen 仍只支持 CPU/CUDA 设备选择，安装此配置不会自动接通 ASR MPS。 现有 GPT-SoVITS MPS 路径可使用该候选环境，2.7.0 上的模型回归仍需实测。

RTX 50 系应评估 cu128 候选，不能使用旧 cu124 作为 Blackwell 运行依据。 FlashAttention 保持可选；已找到匹配 cp312/Torch 2.7/cu128 的 Windows 社区 wheel 和 Linux 上游 wheel，来源、哈希与验证范围见 Torch 2.7 与 FlashAttention 候选。

安装外部运行资产

另提供默认关闭的角色知识 RAG 选项，支持远程和本地 Main Chat。 它包含可直接构建的中日文基础资料，也支持自己的知识目录；Settings 可查看实际阈值和加载状态。 RAG 会额外安装本地 embedding/Torch 依赖。资料、索引构建、诊断与验证范围见说明。

完整本地语音需要 Qwen ASR 与 GPT-SoVITS v3 语音包；视觉和角色包可选：

uv run --locked --no-sync python tools\external_assets.py verify C:\Downloads\amadeus-asr-qwen3-0.6b.zip
uv run --locked --no-sync python tools\external_assets.py install C:\Downloads\amadeus-asr-qwen3-0.6b.zip
uv run --locked --no-sync python tools\external_assets.py verify C:\Downloads\amadeus-voice-kurisu-gpt-sovits-v3.zip
uv run --locked --no-sync python tools\external_assets.py install C:\Downloads\amadeus-voice-kurisu-gpt-sovits-v3.zip

# 可选：场景与 KTX2 角色动画
uv run --locked --no-sync python tools\external_assets.py install C:\Downloads\amadeus-visual-runtime.zip
uv run --locked --no-sync python tools\external_assets.py install C:\Downloads\amadeus-character-kurisu.zip
uv run --locked --no-sync python tools\external_assets.py status

如果没有预制 Qwen 包，可直接把上游 snapshot 下载到同一个固定落点；运行时 保持离线，不会在第一次录音时临时联网：

uv run --locked --no-sync python -c "from huggingface_hub import snapshot_download; snapshot_download('Qwen/Qwen3-ASR-0.6B', local_dir='assets/models/asr/qwen3-asr-0.6b')"

GPT-SoVITS 日文前端第一次使用会准备 OpenJTalk 字典。希望正式启动时不再下载， 可预先运行一次：

uv run --locked --no-sync python -c "import pyopenjtalk; print(pyopenjtalk.g2p('準備完了'))"

配置与启动

复制 .env 并填写 DeepSeek API key（Windows：Copy-Item .env.example .env； macOS：cp .env.example .env），然后在 Settings 中核对：

• Models：deepseek、官方 endpoint、deepseek-v4-flash 与 API key；
• Voice：远程 TTS/ASR 端点（如 MiMo）；L4 本地栈另需 Qwen model 目录、GPT-SoVITS v3 checkpoints、reference audio/text、麦克风、AEC 和 barge-in；
• General：可选角色包状态与呈现设置。

启动：

• Windows：run_electron_utf8.bat（单一启动器；自动发现 .venv，L1–L4 通用）
• macOS：cd electron && npm run electron:dev

macOS 登录后自动启动壁纸可使用原生 Amadeus Wallpaper.app；构建、验证和 LaunchAgent 安装步骤见 macOS 壁纸自启动。

启动型设置变更后按 Restart backend to apply。角色包显示 Not installed 是健康状态，不影响 Chat、Work 或 headless 启动。

默认 B2 AppSession 动作路径不会阻塞首次配置。尚未配置受支持的 AUIP 动作模型凭据时，Chat 和 Settings 仍可启动；应用动作保持 fail-closed， Settings 会明确显示缺少的能力。

兼容路径

可选本地 LLM

需要 llama.cpp 时，显式设置 LLM_PROVIDER=local，配置 executable / GGUF 或已存在的 OpenAI-compatible endpoint，再按需启动：

.\start_llm_server.bat

LM Studio、Ollama、llama-cli 和 hybrid profiles 仍保留，但不会在 DeepSeek 失败后自动切换。

可选远程模型建议

下表是面向当前 API 的推荐 profile，不改变上述角色分工，也不会在端点 失败后自动切换 provider：

外部模型与运行资产

模型权重、参考音频、角色包及大型/版权敏感素材独立分发；源码仓库只保留 必要图标、默认壁纸、schema、validator 和安装工具。

当前目录合同包括 asr-qwen3-0.6b、voice-kurisu-gpt-sovits-v3、 visual-runtime 与 character-kurisu。前两个组成完整本地语音 profile； 后两个只影响场景和角色呈现。

uv run --locked --no-sync python tools\external_assets.py verify C:\path\to\asset-bundle.zip
uv run --locked --no-sync python tools\external_assets.py install C:\path\to\asset-bundle.zip
uv run --locked --no-sync python tools\external_assets.py status

external_assets.py 是纯标准库工具，在任一梯级的 .venv 下运行均可。运行本地语音 模型还需匹配的模型依赖与硬件，安装资产包本身不会补齐这些依赖。cu124 正式配置和 ROCm 实验边界见安装配置。

SpriteForge 角色包最终应落在：

assets/spriteforge/runtime/kurisu/
  runtime_manifest.json
  graph_config.json
  spriteforge_mouth_config.json
  textures/

安装器保持标准 assets/... 路径、校验 SHA-256、跳过相同文件并拒绝意外覆盖。 详见外部资产包与 角色包合同。

壁纸模式（推荐 Lively Wallpaper）

Windows 下推荐用开源的 Lively Wallpaper 托管 Amadeus 网页壁纸； Wallpaper Engine 仍保留兼容。启动 Amadeus 后，将下列本地网页 URL 添加到 Lively（推荐 WebView2），再在 Amadeus 左侧栏点击 Wallpaper：

http://127.0.0.1:17777/wallpaper/lively/index.html

该稳定入口会自动发现实际 asset/bridge 端口；壁纸模式关闭时会原地等待， 不要手工写死 17778 或 17797。诊断时可运行 uv run --locked --no-sync python tools\run_wallpaper_engine_bridge.py 并使用它打印的 Lively URL。 详见 Lively 入口说明。

macOS 没有对应的 Lively/Wallpaper Engine 桌面宿主。点击 Wallpaper 后， Electron 会直接创建桌面层的全场景窗口，并用独立透明窗口承载可交互 Canvas； 场景本身保持鼠标穿透，不会挡住 Finder 桌面图标。该能力目前属于社区实机验证候选， 不构成正式 macOS 支持；依赖与 CI 由 #46 承接，目前也不包含签名、公证或安装器。

图形性能配置

所有 PixiJS 角色与壁纸表面共享一个 .env 图形 Profile：

自定义帧率支持 10–240 FPS，resolution 支持 0.25–4.0。示例：

GRAPHICS_PROFILE=custom
RENDER_MAX_FPS=45
RENDER_MAX_RESOLUTION=1.25

Wallpaper Engine 通过 applyGeneralProperties().fps 提供用户 FPS 设置时，运行时采用该设置与项目 Profile 中较低的有效值；Electron、 Lively 及普通角色表面没有该宿主设置，直接使用项目 Profile。 暂不提供对应 GUI，修改 .env 后需重启 Amadeus。

配置所有权

启动值优先级固定为：

1. 父进程环境变量（最高权威，在 GUI 中显示为 locked）；
2. Electron desktop settings；
3. 仓库根目录 .env；
4. config/settings.py 默认值。

Settings 不会回写 .env。普通模型、语音、麦克风、Provider/MCP、视觉、头像和 角色包状态应从 GUI 配置；高级诊断、实验阈值和测试开关留在 .env。密钥通过 操作系统 safeStorage 加密。详见配置所有权与 本地实例认证。

当前发布边界

开发与贡献

uv sync --locked --extra dev      # core + 开发工具；会移除未选择的语音/模型层
# 保留语音/模型能力时，在完整安装命令末尾追加 --extra dev
uv run --locked --no-sync python tools\verify_python_environment.py --profile ci
uv run --locked --no-sync python -X utf8 tools\run_tests.py

cd electron
npm ci
npm run build
npm audit --audit-level=high

提交前请阅读 CONTRIBUTING.md 与 ROADMAP.md。 产品语义、权限、协议、Provider/MCP/Skill、Project/Draft/Artifact 或 AUIP 边界变化 应先开 Issue；小型修复、文档、测试和纯呈现 UI 变更可直接发 PR。安全问题请按 SECURITY.md 私下报告。

公开历史与许可证

公开仓库从一个整理后的初始提交开始。内部研发 commit、实验 branch、已删除角色 素材、模型、密钥、会话、本地路径及原始共作者元数据没有迁入公开 Git 历史。 代码本身按当前发行边界保留。

Amadeus 第一方源码和修改依据 GNU Affero General Public License v3.0（AGPL-3.0） 开源。 第三方组件保留各自许可证，见 LICENSES 与 THIRD_PARTY_NOTICES.md。代码许可证不会自动授予角色、 模型、参考音频或外部资产包的权利。

相关项目

• Aqua-TTS：MIT 的低延迟 GPT-SoVITS v3 推理运行时；Amadeus 当前不要求安装 Aqua 才能启动。
• Amadeus SpriteForge：已公开源码的 0.1.0 Source Alpha，提供本地 sprite 资产检查、行为图编辑与 KTX2 角色包预览/导出；项目代码采用 AGPL-3.0-only，生成服务与 Amadeus 运行时独立。
• AUIP：已在 Amadeus 中实现的实验性 application-session / typed-action 协议；独立仓库维护现状与公开实现入口，独立版本 SDK 和 conformance suite 尚未发布。
• GPT-SoVITS：内嵌语音合成推理基础。
• OpenClaw：可选外部 Work gateway。