VoiceStudio 仓库架构全解从根目录布局到测试体系的结构化导航【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio导读本文是 VoiceStudio 开源仓库的架构导览围绕仓库根目录的权威文档 docs/STRUCTURE.md 展开它定义了每个目录只有一个职责、每个根级文件都有存在理由的工程纪律并把后端、前端、TTS 模型、测试、脚本与部署配置组织成一个职责清晰、可独立验证的 monorepo。读完本文你将掌握 VoiceStudio 的顶层布局与各目录边界、三大测试家园的划分与隔离原理、根目录铁律及其背后的源码佐证以及项目规划中的 Turborepo 迁移路径——无论是提交 PR 还是二次开发都能快速定位什么东西该放哪里。一句话架构观单职责目录 零运行产物根目录docs/STRUCTURE.md开篇即点明两条核心原则Every folder has a single job. Every file at the root earns its place.即每个文件夹只有一个任务根目录的每个文件都要靠实力立足。它不只是一个目录树速查表更是一份工程契约所有关于东西该放哪的决策都以它为权威依据。整棵目录树在概念上可以分为四条主线用户可见产品代码backend/FastAPI 服务端frontend/React 19 Vite Tauri 桌面壳独立于工作室的 TTS 模型包omnivoice/可执行但不对用户暴露的工具scripts/测试、文档与部署配置tests/、docs/、deploy/。下面逐层展开。根目录铁律Rules of the root文档给出了四条硬性规则它们是整个仓库组织方式的宪法根目录不允许出现任何运行时产物。输出文件、临时文件、本地数据库、崩溃日志一律写入用户数据目录macOS 为~/Library/Application Support/OmniVoice/或各平台等价位置绝不进入仓库。唯一的例外是omnivoice_data/——它只是 Docker 部署时的 bind-mount 锚点deploy/docker-compose.yml 中所有服务都把omnivoice-data卷挂载到/app/omnivoice_data。根目录禁止临时脚本。一次性调试脚本统一放scripts/测试只能住在下文三大测试家园之一绝不散落在根目录。每个子目录只负责一个关注点。文档的原话是If you cant describe what goes in a directory in one sentence, its wrong——如果一句话说不清某个目录该放什么那就是设计错误。每个包都有独立清单。backend/、frontend/、omnivoice/各自通过pyproject.toml/package.json声明依赖均可独立测试而 JS 锁文件是仓库根目录的bun.lockBun workspace 约定deploy/Dockerfile 用--frozen-lockfile安装以保证可复现构建。一个易被忽略的关键细节.gitignore允许仓库内存在本地.env但真正持久的用户环境文件不在仓库里而是~/.config/omnivoice/env。它的读写由 backend/core/user_env.py 负责——设置面板Settings写入的OMNIVOICE_CACHE_DIR等键值就存于此处后端启动时通过load_into_environ()以overrideTrue语义加载确保用户的显式设置能压过 Tauri 启动器注入的默认值见该文件注释中的 #480 修复。该文件按0600权限创建因为它可能持有HF_TOKEN这类秘密。这个设计在 backend/main.py 的启动序列中真实生效.env与持久用户环境文件在导入 torch 之前就被加载。顶层目录逐层拆解根级文件清单与约定文件职责README.md/README_CN.md面向用户的中英文总览CHANGELOG.md发布历史release 工作流逐字提取对应 tag 的小节见 .github/workflows/release.ymlCLAUDE.md/AGENTS.md面向 AI Agent 的工作契约两份必须保持同步pyproject.tomluv.lockPython 项目清单含 pytest / lint 配置与锁文件package.jsonbun.lockmonorepo 清单Bun workspaces Turborepo与根级 JS 锁文件turbo.jsonTurborepo 流水线定义见下.coderabbit.yaml/greptile.jsonCodeRabbit / Greptile PR 审查配置均以CLAUDE.md为输入skills-lock.json锁定.agents/skills/的来源与哈希.gitleaks.toml密钥扫描配置.gitmodulesomnivoice-gallery/子模块backend.specPyInstaller 打包规范按约定驻留根目录alembic.ini数据库迁移配置按约定驻留根目录版本源头的约定值得单独强调真正的应用版本号定义在frontend/package.json当前为 0.5.2其余所有版本文件都镜像它——这与pyproject.toml中项目版本0.5.2一致且 backend/core/version.py 等镜像点都有专门测试守护参见测试列表中的test_app_version.py。backend/FastAPI 服务端backend/是全部服务端逻辑所在地backend/main.py 是唯一入口。文档特别警告它的启动顺序是承载性的load-bearing重排之前务必先读注释。从源码看这种顺序即契约体现在多个层面阶段化启动early-bind 重构main.py把重型导入拆成_phase_a_buildenv 恢复、cuDNN8 预载、torchaudio/模型管理导入、30 个路由模块的扇出导入在 executor 线程执行、_phase_a_finalize在事件循环上注册路由与静态挂载、_phase_bDB 初始化与后台服务。配合OMNIVOICE_EAGER_INIT环境变量uvicorn 可以在约 1 秒内绑定 socket 并响应/health与/startup/progress重型工作全部后置。测试环境pytest下则默认走 eager 路径保证约 100 处无 lifespan 的TestClient(app)调用拿到完整构建的应用。平台加固顺序Windows 下先禁用 torch.compileTORCH_COMPILE_DISABLE1再允许导入 torchMKL 的 Intel Fortran 运行时控制台处理器的FOR_DISABLE_CONSOLE_CTRL_HANDLER1必须在 torch/numpy 导入前设置HF 网络超时HF_HUB_ETAG_TIMEOUT15、HF_HUB_DOWNLOAD_TIMEOUT30与 Xet 回退HF_HUB_DISABLE_XET1在 huggingface_hub 导入前就绪truststore.inject_into_ssl()在模块级执行以支持企业代理的 TLS 证书链。这些注释都标注了对应 issue 号是理解为什么必须在这里做的第一手材料。backend/内部结构目录/文件职责api/routers/39 个路由自动 include薄薄的 HTTP/WS 层setup/子目录承载首次运行向导与模型下载core/配置、DB、任务队列、事件总线、认证/CSRF、路径安全、可选遥测、版本、诊断services/78 个业务逻辑模块TTS、配音流水线、音频 DSP、GPU 网关、引擎路由、模型生命周期engines/每个 TTS/ASR 引擎一个适配器目录worker/远程/分布式 worker——调度器、GPU 池、路由、熔断器、容量外加protocol/与inbound/mcp_shim/MCP 服务器入口docs/mcp.mdspeech_client/语音 sidecar 客户端入口schemas/Pydantic 请求/响应模型migrations/versions/Alembic 迁移——任何 schema 变更都必须经过这里plugins/插件落点见 backend/services/plugin_sdk.pyhooks/PyInstaller 运行时钩子config/models.yaml模型目录tests/隔离的 pytest 会话详见测试三家园引擎适配器家族backend/engines/ 下每个引擎一个目录包括indextts、supertonic3、confucius4、dots_tts、moss_tts_v15、pockettts、audiocpp、omnivoice_gguf、omnivoice_subprocess、voxcpm2_subprocess、moss_tts_nano_subprocess、cosyvoice_subprocess以及 ASR 侧的_asr_sidecar与本地回环引擎_echo。每个引擎目录都遵循适配器 常量 测试的小型结构例如supertonic3/内含常量模块pyproject.toml中对应的supertonic可选依赖还记录了发布者合法性审计Supertone Inc.的过程。frontend/React 19 Vite Tauri 桌面路径职责frontend/package.json应用版本号权威来源其余版本文件均镜像它src/pages/每个顶层视图一个文件src/components/可复用 UI含 audiobook / clone / dub / gallery / settings 等业务组件目录src/ui/、src/lib/共享原语与工具src/api/类型化 API 客户端每个路由组一个src/store/Zustand 切片含持久化状态迁移src/hooks/自定义 React hookssrc/i18n/locales/用户可见字符串的唯一居所src/test/vitest 配置与视觉测试助手e2e/、e2e-perf/、e2e-prod/Playwright 三套件功能、性能、打包产物src-tauri/Rust 桌面壳——后端 spawn/bootstrap、更新通道、听写快捷键、崩溃/重置/卸载处理capabilities/、icons/、wix/、debian/、appimage/为打包输入omnivoice/独立的 TTS 模型包omnivoice/是独立于工作室的底层 TTS 模型包可视为上游 OmniVoice 模型的整合包含models/、cli/omnivoice-infer、omnivoice-infer-batch、omnivoice-demo、omnivoice-dub等 CLI 入口见 pyproject.toml 的[project.scripts]、data/、eval/、scripts/、training/、utils/。pyproject.toml的 build 配置[tool.hatch.build.targets]仅打包omnivoice进一步印证了它与backend/的边界。scripts/可执行但不对用户暴露scripts/收纳一切可执行但非用户面向的工具文档点名的代表包括install.sh/install.ps1跨平台通用安装器desktop-*.mjsdev / prod / fresh 三种桌面启动器配合根package.json的dev:desktop、desktop-prod、desktop-fresh脚本smoke-test.sh端到端验证check-docs-drift.pydocs-drift CI 检查器以 docs/features.yaml 为权威清单build-omnivoice-tts.sh构建bin/下的 sidecar 二进制。deploy/Docker 部署配置deploy/Dockerfile 默认构建 CUDA 变体CI 通过BASE_IMAGE/GPU_FLAVOR覆盖参数从同一文件产出 ROCm/AMD 变体issue #1165。多阶段构建先用oven/bun:1-alpine编译 React 前端依赖根级bun.lock--frozen-lockfile再在 PyTorch 运行时阶段用uv pip install安装项目——注意它刻意保留基础镜像预装的 GPU torch 2.8.0uv pip install不带--upgrade时不会覆盖已满足约束的包并用一段 Python 断言守护GPU torch 未被未来依赖升级悄悄替换GPU_FLAVORguard。deploy/torch-constraints.txt锁定 torch/torchaudio/torchvision 三件套的解析版本防止 ABI 错配#1357。健康检查与0.0.0.0:3900绑定、OMNIVOICE_SERVER_MODE1放松桌面端回环 origin 门禁#261等细节也都在 Dockerfile 注释中给出了完整解释。docker-compose.yml 提供一键部署的五个 profilecpu、gpuNVIDIA、rocmAMD、worker-gpu、worker-rocm。默认把 3900 端口绑定在127.0.0.1以保证只有本机可达并强制要求导出OMNIVOICE_API_KEY${OMNIVOICE_API_KEY:?...}语法在未导出时直接中止启动。首个容器卷omnivoice-data与omnivoice_data/锚点对应。docs/开发者文档docs/与docs/STRUCTURE.md自身构成闭环docs/ROADMAP.md项目方向docs/RELEASING.md发布检查清单docs/features.yaml权威功能清单驱动 docs-drift CIdocs/adr/架构决策记录当前含 SPIKE-01-gguf、SPIKE-02-singing、apprun-strategy、inbound-node-mode 等docs/agents/面向 Agent 的文档其余engines/、dubbing/、install/、setup/、migration/、features/、playbooks/、specs/子目录按主题归档。其余顶层成员bin/预编译的 omnivoice-tts sidecar每个平台一个.agents/skills/规范的技能副本vite、fastapi-python由skills-lock.json锁定按路径跟随、绝不软链skills/则是本仓库对外发布的技能omnivoice、oss-maintainerinfra/install-redirect/voicestudio.sh/install的 UA 嗅探安装 worker边缘部署非 Docker 路径examples/可运行 demo 与样例输入agentic、speech-platformnotebooks/OmniVoice_Studio_Colab.ipynbomnivoice-gallery/git 子模块——已发布的语音画廊。测试三家园为什么测试被刻意分成三处文档强调测试的分裂是刻意设计而非漂移The split is deliberate, not drift每处都有独立 runnerCI 在ci.yml的同一个testjob 中以独立步骤运行全部三者家园Runner为什么独立tests/pytest tests/pyproject.toml的testpaths默认值主套件。其 tests/conftest.py 把OMNIVOICE_DATA_DIR指向一次性临时目录tempfile.mkdtemp保证任何测试都不可能触碰开发者真实的 app 状态issue #878backend/tests/pytest backend/tests/——独立 pytest 会话CI 步骤名 Run pytest (backend/tests, isolated)针对backend/裸导入的隔离会话。其 backend/tests/conftest.py 设置同样的密封数据目录文档明确警告绝不要在恢复模块级sys.modules桩——它会在收集期进程级泄漏并污染混合运行frontend/src/**/*.test.{js,jsx,ts,tsx}bun run testvitest jsdom与待测组件同目录。frontend/e2e*/承载 Playwright 套件tests/frontend/是更早的node:test集合源码佐证pyproject.toml 的[tool.pytest.ini_options]设testpaths [tests]并列出norecursedirsresearch、omnivoice/training、omnivoice/eval、frontend、deploy、.venv、node_modules、omnivoice_data等。ci.yml 的testjob 用HF_HUB_OFFLINE1作为递归防护任何在测试中途访问 huggingface.co 的代码会快速失败而不是静默下载数 GB 权重注释记录过preload_model()的 Hub 探测曾把完整 2.3 GBk2-fsa/OmniVoice检查点拉进每次联网的空缓存运行。CI 还额外跑一个独立的backend/tests会话并分别在 macOS / Windows / Linux 上用tests/smoke/做跨平台启动冒烟smoke-matrixjobWindows 上另有专门步骤跑 worker 产物路径测试捕获过os.path.join导致的inputs\sha.wav路径歧义。tests/conftest.py本身也是一份测试隔离最佳实践教材除了密封数据目录它还做了 LLM provider 三重状态env 变量 SQLite settings 存储 prefs.json的快照/恢复、HF 端点探测的确定性桩endpoint_race永不触网、core.config路径常量的跨模块泄漏修复#1269、Windows 符号链接环境的symlink_or_skip夹具等。What lives where快速落位表文档给出了一张这东西该放哪速查表是新增代码时的第一落点依据东西放哪用户面向的产品代码backend/、frontend/TTS 模型独立于工作室omnivoice/新的 TTS/ASR 引擎适配器backend/engines/engine/一切可执行但非用户面向的内容scripts/预编译平台 sidecarbin/Python 测试tests/需要隔离会话时放backend/tests/前端单元测试与组件同目录的*.test.jsx开发者 用户文档Markdowndocs/架构决策记录ADRdocs/adr/面向 Agent 的文档docs/agents/可运行 demo 与样例数据examples/运行时数据永不提交macOS 的~/Library/Application Support/OmniVoice/命名与镜像约定文件名Python 用 snake_caseJS/TS 组件用 kebab-case 或 PascalCaseMarkdown 用小写。测试镜像源码路径凡存在镜像tests/backend/镜像api/ core/ engines/ services/——例如 backend/services/ffmpeg_utils.py 对应tests/backend/services/test_ffmpeg_utils.py其余保持扁平——tests/backend/test_*.py承载后端级用例tests/test_*.py承载跨切面用例。React 组件的测试直接放在组件旁边。一次性脚本进scripts/并取描述性名字而不是在根目录放test_*.py。新增顶级目录必须提交一个同时更新本文件docs/STRUCTURE.md的 PR——这是让目录契约随仓库演进的硬性流程。根目录清理史从历史包袱到干净根目录文档用两轮清理记录解释了根目录为什么这么干净也展示了仓库对历史包袱的处理哲学第一轮清理删掉了 4 月 14 日崩溃调查留下的一次性调试脚本test_crash.py、test_server.py、test_whisper.py、test_mock.py、test_pyannote.py——它们在路由重构后引用了不存在的符号、benchmark.py、output.wav/test.wav等运行产物、crash_log.txt改写入$DATA_DIR/crash_log.txt、148 MB 的omnivoice.zip离线存档、只含.DS_Store的data/以及散落各处的.DS_Store。前 Gradio UIlegacy_gradio/先归档到research/最终在 2026-07-12 清理中移除保留在 git 历史中。2026-07-12 清理全部保留在 git 历史.planning/74 文件的 GSD 时代规划存档GSD 工作流 2026-07-08 退役四个承载决策的文档迁入docs/adr/、specs/已全部交付的特性规格 001–007现居docs/specs/、design/已被成品 UI 取代的 ASCII 原型、research/、.agents/后被赋予新职责重新引入——.agents/skills/现在存放由skills-lock.json锁定的规范技能副本。这段历史的价值在于清理不是删除而是迁移。每个条目都记录了为什么曾在根目录、去了哪里供未来决策参考。扩展路径何时迁移到 Turborepo 式 monorepo文档明确当前扁平布局flat layout对现阶段规模完全够用并给出了提案但尚未执行proposed, not yet executed的迁移蓝图VoiceStudio/ ├── apps/ │ ├── api/ ← 原 backend/ │ ├── web/ ← 原 frontend/ │ └── desktop/ ← 未来可把 src-tauri/ 抽到这里 ├── packages/ │ ├── omnivoice-model/ ← 原 omnivoice/ │ └── tts-adapters/ ← 新增ROADMAP 第三阶段的可插拔 TTS 接口 ├── config/ │ ├── docker/ │ └── pyinstaller/ ├── tests/ └── docs/迁移的触发条件是出现第二个apps/*或第二个packages/*在此之前不做。文档还明确警告没有专门 PR 不得执行此迁移因为它会破坏一大批既有约束pyproject.toml的[tool.hatch.build.targets.{sdist,wheel}]路径package.json的 workspaces 与脚本turbo.json、Dockerfile、docker-compose.yml路径backend.spec[backend/main.py]、pathex[.]frontend/src-tauri/tauri.*.conf.json的 sidecar 路径所有from backend.main import …的导入点测试、脚本frontend/package.json作为版本权威源及其镜像。现状佐证根目录 package.json 已是 Turborepo 工作区形态——workspaces: [frontend]scripts 里build/start走turbo runturbo.json 定义了build、dev、desktop、//#dev:api任务持久型任务关闭缓存。也就是说Turborepo 管线已经就位迁移的只是目录拓扑。给新贡献者的三条实操指引定位代码新增引擎 →backend/engines/engine/新增 API →backend/api/routers/新增业务逻辑 →backend/services/新增页面 →frontend/src/pages/新增脚本 →scripts/。跑对测试后端改动用uv run pytest tests/主套件需要隔离会话时uv run pytest backend/tests/前端组件测试用bun run --cwd frontend testvitest。CI 全程HF_HUB_OFFLINE1本地跑测试同样应保持离线以复现 CI 行为tests/conftest.py 已把OMNIVOICE_DATA_DIR指向一次性目录永远不会污染你的真实数据。守住根目录纪律任何运行时产物都不进仓库任何新顶级目录都必须在一个同时更新 docs/STRUCTURE.md 的 PR 中引入——这份文件就是仓库结构的唯一权威让单职责目录这条规则持续可维护。【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考