Calliope

基于 Rust + Slint 的 Mumble 兼容语音通信客户端，目标平台为 Linux 桌面原生客户端与 WASM/Web 客户端。

本仓库当前处于原生 CLI MVP 阶段：CLI、ViewModel、原生 Runtime 与 mTLS Mumble 会话已形成可运行主链路；GUI 与 WebTransport/Web 客户端尚未完成。功能完成状态以 docs/long-term-roadmap.md 为准，本文只描述当前真实能力。

当前能力（2026-08 基线）

已验证（存在实现与测试证据）：

• CLI：ratatui 全屏 TUI、命令历史/补全、日志滚动、终端恢复。
• Vault 身份：24 词 BIP39 助记词初始化、PIN 解锁、确定性 DerivedCert 派生、AES-256-GCM 加密 vault；ImportedCert 的底层加密存储模型与 round-trip 已验证，但 CLI/GUI 导入管理入口尚未实现。
• 连接与控制面：TCP/TLS + 客户端证书 mTLS、Version/Authenticate/ServerSync/Reject/Ping 握手、频道与用户快照、凭证挑战生命周期、当前频道文本消息。
• 语音数据面：Opus 编解码、TLS UDPTunnel 收发、Mumble OCB-AES128 加密 UDP 与 TCP fallback、soundboard WAV 发送、远端 WAV 录音；native microphone capture 已接入出站主链路，但 speaker/mixer 入站播放尚未接入，因此设备级实时双向通话仍未完成。
• ViewModel 状态机：唯一 TEA 产品契约（Msg → update → (AppEvent, Cmd)），连接、频道树、聊天、Vault、收藏、媒体生命周期均为 SSOT。

部分完成 / 未实现：

• GUI 为视觉原型 + 局部状态投影，无完整连接旅程。
• WASM 仅能加载 UI，Browser Runtime 与 WebTransport 客户端不存在。
• Gateway 有原型，但安全边界、双向 UDP 与可部署性未闭合。

架构

采用 TEA（The Elm Architecture）与控制面/数据面分离：

• ViewModel（calliope-client/src/viewmodel/）：纯 Rust 状态机，业务状态唯一来源，零 Slint/I/O 依赖。
• Runtime（calliope-runtime/）：副作用执行器（网络、音频、文件），通过 mpsc 收 Cmd、回写 Msg。
• 音频数据面：PCM/Opus 帧在 Runtime 内部 ring buffer 直通，不进入 ViewModel；只有 mute/talking 等低频状态成为 Msg。

Crate	职责
calliope-core	纯类型、trait、vault、密码学
calliope-transport-native	原生 TCP/TLS 传输（仅桌面）
calliope-client	ViewModel + Slint GUI（桌面/WASM）
calliope-runtime	I/O 副作用：cpal 音频、文件、网络、session
calliope-gateway	WebTransport ↔ TCP/UDP 桥（原型）
calliope-server	自有服务器（进行中）
calliope-wire	服务器 wire 协议
calliope-mocks	mockall 测试 mock 与 fixture
calliope-cli	调试 REPL（真实 TEA 循环）

关键约束：calliope-runtime 只依赖 calliope-core（非 WASM 下 cfg-gate 依赖 calliope-transport-native），不得依赖 calliope-client，以保证 client 的 WASM 兼容性。

领域术语见 CONTEXT.md，整体设计见 docs/architecture.md。

环境要求

必须使用 Nix + devenv：

# 首次克隆后
direnv allow

# 之后每个 shell 自动获得 Rust nightly 与系统库
# (alsa, opus, wayland, mesa, dbus, murmur, openssl, pipewire)

LD_LIBRARY_PATH 与 SLINT_FONT_DIR 由 devenv.nix 设置，不要覆盖。

构建与运行

# 桌面 GUI（主应用）
cargo run -p calliope-client

# CLI 调试 REPL
cargo run -p calliope-cli

# Gateway 服务器（从 CWD 读取 gateway-config.json）
cargo run -p calliope-gateway

# WASM 构建（手动脚本，非 Trunk）
./crates/calliope-client/build-wasm.sh

Rust 通道为 nightly（由 devenv.nix 固定），wasm32-unknown-unknown target 已预装。

测试

统一使用 cargo nextest（不用 cargo test），配置在 .config/nextest.toml：

# 单元测试（src/ 内联 #[cfg(test)]）
cargo nextest run -E 'kind(lib)'

# 集成测试（crate 级 tests/ 目录）
XDG_RUNTIME_DIR=/tmp/opencode devenv shell cargo nextest run --profile integration -E 'kind(test)'

# 真实 Murmur mTLS 聊天与 fixture 生命周期测试
XDG_RUNTIME_DIR=/tmp/opencode devenv shell cargo nextest run --profile integration -E 'binary(=mtls_chat) | binary(=murmur_fixture)'

# 串行 CLI PTY 旅程
XDG_RUNTIME_DIR=/tmp/opencode devenv shell cargo nextest run --profile integration -E 'binary(=cli_mtls_chat_pty)'

约定：

• 无快照测试，无 WASM 测试 runner；集成与 PTY 测试默认全部运行，不使用 ignore 标记或 feature gate。
• 真实 Murmur 测试只使用 Nix 提供的 mumble-server 与 OpenSSL 进程 fixture，不使用 Docker 或 testcontainers。
• Murmur fixture 并发上限 2；PTY 测试串行（murmur-integration / serial-e2e test group）。
• 多 agent 并行开发期间，全量 integration profile 只由集成者与本地全量门禁执行（见 docs/agents/parallel.md）。

本地 CI 门禁

本仓库不使用 GitHub Actions。原 CI 的七个 job 由单一本地入口串行复现，必须在 devenv shell 内运行；入口从任意 CWD 定位仓库：

# 全部阶段（默认），按下列顺序串行
devenv shell -- tools/check.sh

# 单个阶段
devenv shell -- tools/check.sh fmt             # cargo fmt --all -- --check
devenv shell -- tools/check.sh lib-tests       # xvfb-run -a cargo nextest run --retries 1 -E 'kind(lib)'
devenv shell -- tools/check.sh integration     # daemon helper 回归 + audio world + integration nextest
devenv shell -- tools/check.sh gui-acceptance  # GUI Python/driver/display/D-Bus/probe/lifecycle
devenv shell -- tools/check.sh spa-checks      # npm ci / test / check:dist / test:browser
devenv shell -- tools/check.sh rustdoc         # cargo doc --workspace --no-deps
devenv shell -- tools/check.sh wasm-build      # wasm32 build

# 选择器与用法
devenv shell -- tools/check.sh --help

all 按上方顺序运行；每个阶段沿用原 job 的超时预算；任一阶段失败会立即以非零状态退出并指明失败阶段。tools/check.sh 的行为测试为 bash tools/test-support/test-check.sh。

文档索引

• CONTEXT.md — 领域术语与不变量（权威）
• docs/architecture.md — 架构设计
• docs/long-term-roadmap.md — 功能审查与长期路线（当前完成状态基线）
• docs/standards/viewmodel-ssot.md — ViewModel 单一事实来源规范
• docs/standards/commenting.md — 注释与 Rustdoc 规范
• docs/mumble-voice-transport.md — Mumble 语音传输设计
• docs/commit-rules.md — 提交规范

参与开发

本仓库由人类与 AI agent 协作开发。修改代码前必须阅读 AGENTS.md；多 agent 并行开发期间另见 docs/agents/parallel.md 的所有权地图与 worktree 隔离规则。

提交遵循 Conventional Commits（type(scope): message），详见 docs/commit-rules.md。

License

Apache-2.0