Amadeus

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

[!IMPORTANT] 本仓库包含可构建、可运行的公开源码，当前版本为 0.1 α， 不是带安装器的正式桌面发行版。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，实现位于本仓库。详见 AUIP 应用会话文档。独立的 Code-Amadeus/auip 目前仍是公共 namespace placeholder，本版本不声称已经发布独立 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 仍是社区配置记录。 统一使用 uv 与 Python 3.12，CI 固定 uv 0.12.8。

四个默认梯级与 ROCm 实验选项均使用同一个 .venv。每次给出完整目标配置： uv sync 会精确同步，漏带会移除已装层。torch-cpu、local-cu124 与 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/）。

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 矩阵内，因此不能作为可用目标。

GeForce RTX 50 系（Blackwell，社区验证配置）：本项目当前使用的 torch==2.6.0+cu124 profile 不兼容 RTX 50 系，无法运行本地 CUDA 语音模型。50 系用户需要更新 NVIDIA 驱动，并改用社区已验证可运行的 PyTorch 2.7.0 CUDA 12.8 组合。

GeForce RTX 50 series (Blackwell, community-validated configuration): the current torch==2.6.0+cu124 profile is incompatible with RTX 50-series GPUs and cannot run the local CUDA voice models. Update the NVIDIA driver and use the community-validated PyTorch 2.7.0 CUDA 12.8 combination instead:

请在单独的实验项目虚拟环境（例如 .venv_cu128）中运行以下命令， 不要改