项目结构¶

VoiceStudio/
│
├── README.md ⟵ user-facing overview (translations: docs/readme/README_*.md)
├── CHANGELOG.md                 ⟵ release history; Electron releases use the tagged section
├── CLAUDE.md / AGENTS.md        ⟵ matching copies of the agent operating rules
├── LICENSE / LICENSE-NOTICE.md / SPONSORS.md   ⟵ legal terms, required notices, supporters
│
├── pyproject.toml               ⟵ Python metadata plus the pytest and lint settings
├── uv.lock                      ⟵ Python lockfile
├── package.json                 ⟵ monorepo manifest (Bun workspaces) and THE app
│                                   version (pyproject.toml + backend/core/version.py mirror it)
├── bun.lock                     ⟵ JS lockfile — repo-root, covers the electron/ workspace
├── flake.nix, flake.lock        ⟵ community Nix dev shells + NixOS FHS env (docs/install/nix.md)
│
├── .coderabbit.yaml / greptile.json   ⟵ bot-review setup; CLAUDE.md supplies both rule sets
├── skills-lock.json             ⟵ records the origin and digest of each .agents/skills/ copy
├── .gitleaks.toml               ⟵ repository secret-detection policy
├── .gitmodules                  ⟵ registers omnivoice-gallery
├── .python-version              ⟵ interpreter selection for Python tooling
├── .dockerignore                ⟵ Docker build context filter
├── alembic.ini                  ⟵ DB migration config (stays at root by alembic convention)
│
├── .gitignore                   ⟵ excludes a checkout-local .env; Settings persists user choices in
│                                   ~/.config/omnivoice/env through backend/core/user_env.py
│
├── backend/                     ⟵ FastAPI server
│   ├── main.py                  sole process entry; its annotated startup sequence must retain its order
│   ├── api/routers/             44 routers, auto-included; HTTP/WS adaptation stays thin here
│   │   └── setup/               setup-wizard endpoints and model acquisition
│   ├── core/                    shared infrastructure: configuration, persistence, job/event plumbing,
│   │                            auth and CSRF, safe paths, analytics consent, version and diagnostics
│   ├── services/                116 modules of business logic spanning speech, dubbing, DSP, GPU dispatch,
│   │                            engine selection and loaded-model ownership
│   ├── engines/                 per-engine adapters: audiocpp, confucius4, cosyvoice_gguf,
│   │                            cosyvoice_subprocess, dots_tts, indextts, moss_tts_nano_subprocess,
│   │                            moss_tts_v15, omnivoice_gguf, omnivoice_subprocess, pockettts,
│   │                            supertonic3, voxcpm2_subprocess, whisper_cpp, _asr_sidecar, _echo
│   ├── schemas/                 Pydantic types at the request/response boundary
│   ├── config/models.yaml       catalogue of selectable models
│   ├── migrations/versions/     mandatory Alembic home for database evolution
│   ├── plugins/                 extension landing area; contract lives in services/plugin_sdk.py
│   ├── mcp_shim/                MCP launch surface documented by docs/mcp.md
│   ├── speech_client/           client entry for the speech sidecar
│   └── tests/                   separately collected backend test session (details below)
│
├── electron/                    ⟵ the only desktop app and web UI (Electron + React 19)
│   ├── src/main/                lifecycle, backend supervisor, runtime setup, updater, native IPC
│   ├── src/preload/             typed contextBridge → window.voicestudio
│   ├── src/renderer/            desktop React app: routes/, features/, components/, i18n/locales/
│   ├── src/shared/              modules shared by the desktop and browser builds (api/, i18n/,
│   │                            store/, ui/, utils/) — not a runnable app
│   ├── tests/                   packaged-app, installer and workflow smoke tests
│   ├── build/                   packaging inputs: icons, entitlements, Info.plist
│   ├── scripts/                 dev launcher, AppImage update-info embedding
│   ├── vite.web.config.ts       browser build (`bun run build:web`) → frontend/dist/
│   └── electron-builder.config.mjs   installers: DMG/zip, NSIS, AppImage + deb
│
├── native/desktop-bridge/       ⟵ Rust helper used by Electron
│
├── frontend/dist/               ⟵ build output of `bun run build:web` (gitignored): the web UI
│                                   the backend serves in Docker and, from Electron packages, to LAN devices
│
├── omnivoice/                   ⟵ the underlying TTS model package
│   ├── models/
│   ├── cli/                     CLI entry points (omnivoice-infer, etc.)
│   ├── data/                    data utilities used by the model
│   ├── eval/                    evaluation scripts
│   ├── scripts/                 one-off utilities that ship with the package
│   ├── training/
│   └── utils/
│
├── tests/                       ⟵ default pytest collection selected by pyproject.toml `testpaths`
│   ├── conftest.py              redirects OMNIVOICE_DATA_DIR to disposable state for the whole session
│   ├── backend/ / scripts/      path-shaped coverage for those source areas
│   ├── smoke/                   quick end-to-end gates; isolated CI job runs with HF_HUB_OFFLINE=1
│   ├── evals/                   evals.yml-driven output-quality checks
│   ├── probe/ / fixtures/       diagnostic probes and reusable inputs
│   └── frontend/                retained node:test suite for utilities and developer tooling
│
├── scripts/                     ⟵ development, packaging and release commands (sh, Python, mjs)
│   ├── install.sh / install.ps1 installers delivered from voicestudio.sh/install
│   ├── dev-backend.mjs          supervisor behind `bun run dev:api`
│   ├── setup.py                 platform finishing step for `bun run setup:api`, including ROCm opt-in
│   ├── electron-smoke-test.mjs  packaged-launch probe invoked by `bun run smoke-test`
│   ├── prepare_electron_release.py, check_electron_release_assets.py   artifact verification
│   ├── check-docs-drift.py      checks docs-drift.yml against authoritative docs/features.yaml
│   └── build-omnivoice-tts.sh   produces the sidecars stored under bin/
│
├── bin/                         ⟵ one precompiled omnivoice-tts sidecar for each supported platform
├── .agents/skills/              ⟵ real-file canonical skills whose revisions are locked in skills-lock.json
├── skills/                      ⟵ distributable voicestudio and voicestudio-maintainer skill packages
│
├── deploy/                      ⟵ container delivery plus the hosted installer worker
│   ├── Dockerfile               CUDA baseline; BASE_IMAGE and GPU_FLAVOR let CI build ROCm too
│   ├── docker-compose.yml       local one-command stack
│   ├── torch-constraints.txt    image-specific torch-family lock
│   ├── dockerhub-overview.md    release-synchronised Docker Hub description
│   └── install-worker/          Cloudflare worker serving voicestudio.sh/install; embeds both installers
│                                from scripts/ (see docs/install/script.md)
│
├── docs/                        ⟵ engineering references, product imagery and brand material
│   ├── STRUCTURE.md             this map
│   ├── ROADMAP.md               planned direction
│   ├── RELEASING.md             complete multi-channel shipping checklist
│   ├── features.yaml            source inventory consumed by docs-drift.yml
│   ├── adr/                     durable architectural decisions
│   ├── agents/                  tracker, triage-role and domain instructions for agents
│   ├── engines/ dubbing/ install/ setup/ migration/ features/ playbooks/ specs/
│   ├── media/ screenshots/      supporting media and captured UI
│   ├── preview.png / logo.*     repository preview and logo assets
│   └── languages.md training.md data_preparation.md evaluation.md voice-design.md
│
├── examples/                    ⟵ executable samples and inputs, including agentic/ and config/
├── notebooks/                   ⟵ contains OmniVoice_Studio_Colab.ipynb
├── omnivoice-gallery/           ⟵ submodule that publishes the voice gallery
│
├── omnivoice_data/              ⟵ Docker bind-mount target (gitignored)
│                                   DB + HF cache live here when running via compose
│
├── .github/workflows/           ⟵ ci, electron-build, electron-release, docker, security,
│                                   docs-drift, evals, install-smoke, build-omnivoice-tts,
│                                   cla, commit-identity, cosyvoice-dependencies
└── .git/

VoiceStudio/
├── apps/
│   ├── api/                 ← was backend/
│   └── desktop/             ← was electron/ (desktop + browser UI)
├── packages/
│   ├── omnivoice-model/     ← was omnivoice/
│   └── tts-adapters/        ← new; the pluggable TTS interface from ROADMAP phase 3
├── config/
│   └── docker/
├── tests/
└── docs/