安装与首次运行

Muxiva 当前为 pre-alpha。发布自动化已经可以构建独立 CLI 压缩包与 Python Wheel；第一次公开 Tag 仍受发布账号归属确认门禁保护。

安装 CLI

Homebrew Tap 激活后，macOS ARM64 与 Intel 用户无需 Rust Toolchain 即可安装原生二进制：

brew install PiyotaHu/muxiva/muxiva
muxiva --version

第一次正式 Tag 发布前，使用源码 Checkout 安装：

git clone https://github.com/PiyotaHu/muxiva.git
cd muxiva
cargo install --locked --path crates/muxiva-cli
muxiva --version

完成安装后，应用开发者日常只使用 muxiva，不需要通过 cargo run 启动整个 Workspace。

源码安装需要 Git 与 rust-toolchain.toml 指定的 Rust Toolchain。CMake、CPython、 maturin、Node.js 与 pnpm 仅在贡献者构建相应 SDK 或示例时需要。发布维护者请阅读发布运维。

CLI 入口

直接运行 muxiva 会优先显示 Headless Runtime 入口；muxiva --help 会解释每个命令：

命令	作用
`muxiva init [目录]`	创建包含 `graph.json` 与 `.muxiva/` 的完整项目
`muxiva validate <项目或图>`	只校验，不创建或执行 Node
`muxiva run <项目或图>`	执行会自然结束的有限 Graph
`muxiva serve <项目或图>`	不依赖 Studio，长期运行实时 Graph 和最小 Client API
`muxiva studio [项目或图]`	可选的可视化设计与本地调试工具
`muxiva doctor [--voice]`	检查工具链、项目和真实语音 Demo 就绪状态
`muxiva simulate`	运行无网络的合成 Runtime 测试夹具，不是产品 Demo

第一次运行：真实语音助手

Muxiva 的开发者主体验是带真实凭据的 Qwen + Agora Voice Room，而不是合成 ASR、 LLM 或 TTS 输出。macOS 安装脚本会自动下载并校验 Agora SDK；Qwen 不需要下载 SDK。两个短期 RTC Token、API Key 与 Workspace ID 的申请步骤见从零运行真实语音 Agent。

./examples/voice-agent/setup.sh
cp examples/voice-agent/.env.example examples/voice-agent/.env
# macOS：默认打开 Studio
./examples/voice-agent/run.sh
# Linux / Docker：启动 Headless Runtime
./examples/voice-agent/run.sh --headless
# Headless 模式的另一个终端
cd examples/voice-agent && npm run voice-room

run.sh 在 macOS 和 Windows Shell 默认选择 Studio，在 Linux 默认选择 Headless； --studio 与 --headless 可以在任何平台显式覆盖。

创建并运行 Graph

muxiva init my-agent
muxiva validate my-agent
muxiva run my-agent
muxiva serve my-realtime-agent

init 会创建 my-agent/graph.json、.muxiva/nodes/、.muxiva/templates/ 与项目 README。validate 不产生副作用。run 使用精确 Node Registry 编译 Graph、实例化 Factory，并通过并发 Runtime 在有界执行与关闭期限内运行。传入单个 .json 文件的旧用法仍然兼容。实时服务使用 serve，它会持续运行直到 Graph 自然结束或收到 Ctrl-C/SIGTERM，并提供与独立网页连接所需的最小 HTTP API。

打开 Studio

cd my-agent
muxiva studio

Studio 会自动发现 graph.json。如果当前目录不是项目，则安全创建 muxiva.graph.json；在 Muxiva 源码仓库根目录运行时，会自动打开旗舰 Voice Agent 工作区。服务只监听本机并生成随机访问 Token。下一步阅读 Studio 指南。