feat: add CW-026 Local Voice plugin

2026-07-27 00:33:25 +08:00
commit 5d680928b9
29 changed files with 2697 additions and 0 deletions
@@ -0,0 +1,132 @@
+# Verified macOS installation
+
+This procedure recreates the production configuration verified on an Apple
+Silicon MacBook Pro. It installs the software and model separately from the
+private authorized voice-asset archive.
+
+## Verified configuration
+
+- Apple Silicon macOS
+- Python 3.11
+- CosyVoice3 `0.1.0+metal`
+- 24 kHz Candle model: `spensercai/CosyVoice3-0.5B-Candle`
+- ffmpeg and Whisper available on `PATH`
+- Metal inference with full-precision weights
+
+## 1. Install system prerequisites
+
+Install Homebrew if it is not already present, then install:
+
+```bash
+brew install python@3.11 ffmpeg
+```
+
+Install the Whisper CLI into an isolated environment or with `pipx`. Confirm:
+
+```bash
+ffmpeg -version
+whisper --help
+python3.11 --version
+```
+
+## 2. Create the runtime
+
+The default runtime is:
+
+```text
+~/Library/Application Support/MPM Local Voice/runtime
+```
+
+Create its `models`, `voices`, `jobs`, and `wheels` directories. Create a Python
+3.11 virtual environment beside or inside the runtime and activate it.
+
+For a guided installation after downloading the model and private packages:
+
+```bash
+zsh scripts/install_macos.sh \
+  --wheel /path/to/cosyvoice3-0.1.0+metal-cp310-abi3-macosx_11_0_arm64.whl \
+  --assets /path/to/local-voice-authorized-assets-v0.1.0.tar.gz \
+  --model-dir /path/to/CosyVoice3-0.5B-Candle
+```
+
+## 3. Install the tested Metal wheel
+
+Copy this file from the private CW-026 recovery package:
+
+```text
+cosyvoice3-0.1.0+metal-cp310-abi3-macosx_11_0_arm64.whl
+```
+
+Expected SHA-256:
+
+```text
+c9c04352fe0e559b7b43129baae7035b25b48922e2296498efc53c39874d4e39
+```
+
+Install the wheel and runtime Python dependencies:
+
+```bash
+python -m pip install ./wheels/cosyvoice3-0.1.0+metal-cp310-abi3-macosx_11_0_arm64.whl
+python -m pip install numpy==2.4.6 soundfile==0.14.0
+```
+
+## 4. Install the model
+
+Download `spensercai/CosyVoice3-0.5B-Candle` from Hugging Face into:
+
+```text
+runtime/models/CosyVoice3-0.5B-Candle
+```
+
+The private recovery manifest contains hashes for the production model files.
+At minimum the directory must contain:
+
+- `llm.safetensors`
+- `flow.safetensors`
+- `hift.safetensors`
+- `campplus.onnx`
+- `speech_tokenizer_v3.onnx`
+- `config.json`
+
+The model is approximately 4.7 GB and is not bundled with the public plugin.
+
+## 5. Install authorized voice assets
+
+Extract the private archive so the runtime contains:
+
+```text
+runtime/voices/donna
+runtime/voices/chris-engineer
+runtime/voices/grandpa-bomber
+runtime/voices/ryan-pitch-meeting
+runtime/voices/val-holiday
+```
+
+Do not publish or redistribute this archive.
+
+## 6. Verify
+
+From the plugin root:
+
+```bash
+python scripts/local_voice.py doctor --device metal
+python scripts/verify_install.py --device metal
+```
+
+Every dependency, model, and voice profile must report `PASS`.
+
+## 7. Install the plugin
+
+For Claude CoWork, install `local-voice-v0.1.0.plugin` from the private CW-026
+folder. For Codex, install from the MPM marketplace or use the same repository
+source containing `.codex-plugin/plugin.json`.
+
+Start a new task after installation so the host loads the skill.
+
+## Restore policy
+
+The public repository is authoritative for code and documentation. The private
+CW-026 folder is authoritative for the tested wheel, authorized voice assets,
+checksums, plugin packages, and recovery notes. The model is reproducible from
+its exact source and hashes; an optional offline model archive may be added
+later.