添加中文启动指南：Conda后端 + Bun前端双端启动方法 - #990
Conversation
📝 WalkthroughWalkthrough新增 Voicebox 中文启动指南，覆盖环境安装、依赖配置、后端与前端启动、桌面应用开发、Web 开发、端口说明、故障排查、环境重置和常用命令。项目同时新增 Python 3.12 配置、uv 依赖配置及 Make 工作流。 ChangesVoicebox 项目环境与开发工作流
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (1)
README_CN.md (1)
386-395: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win标注 Hugging Face 镜像的信任边界。
HF_ENDPOINT=https://hf-mirror.comroutes model downloads through a third-party mirror. Mark it as unofficial, keep the official endpoint as the default, and tell users to use the mirror only when they trust it. Verify whether authenticated Hugging Face requests can also use this endpoint.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@README_CN.md` around lines 386 - 395, Update the Hugging Face mirror guidance near the model-download FAQ to identify https://hf-mirror.com as an unofficial third-party endpoint, state that the official Hugging Face endpoint remains the default, and advise users to use the mirror only if they trust it. Clarify whether authenticated Hugging Face requests are supported through this endpoint, without implying broader compatibility than confirmed.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README_CN.md`:
- Around line 18-24: 修正 README_CN.md 目录中的所有 Markdown 锚点，使其与对应标题生成的实际 fragment
完全一致；重点更新“快速开始（双端启动）”“后端启动（Conda 方式）”和“前端启动（Bun 方式）”等包含标点或空格的链接，并保留目录顺序与标题文本不变。
- Around line 44-50: Update the Miniconda installation section in README_CN.md
so the Linux/macOS instructions no longer share the Linux x86_64 download
command. Provide correct macOS installer commands for Intel and Apple Silicon,
while retaining the Linux command, or replace the platform-specific commands
with the official installer selector link.
- Around line 242-250: 更新 README_CN.md 中“桌面应用前端（配合 Tauri）”章节，将桌面开发启动方式统一为终端 2
执行根目录的 bun run dev；移除要求先进入 tauri 目录执行 bun run tauri dev 的说明，并明确 tauri/dev 仅用于
Vite 开发服务器，不作为桌面应用启动命令。
- Around line 98-99: 更新 README_CN.md 的 AMD GPU 安装说明，移除仅安装 torch 和 torchaudio 的
ROCm 6.3 索引命令；参照 backend/requirements-rocm.txt，将 AMD/Linux 与其他平台拆分为对应指令，并确保
torch、torchaudio 和 torchvision 使用仓库固定的 ROCm 7.2.1 依赖或 AMD 官方 validated 安装方案。
- Around line 171-172: 在 README_CN.md
的“方式2：指定主机地址”示例前补充安全前提说明：由于当前后端没有可靠的认证授权保护，0.0.0.0
仅应在可信局域网且已配置网络隔离或防火墙时使用；否则引导用户改用 --host 127.0.0.1。
---
Nitpick comments:
In `@README_CN.md`:
- Around line 386-395: Update the Hugging Face mirror guidance near the
model-download FAQ to identify https://hf-mirror.com as an unofficial
third-party endpoint, state that the official Hugging Face endpoint remains the
default, and advise users to use the mirror only if they trust it. Clarify
whether authenticated Hugging Face requests are supported through this endpoint,
without implying broader compatibility than confirmed.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| - [环境要求](#环境要求) | ||
| - [快速开始（双端启动）](#快速开始双端启动) | ||
| - [后端启动（Conda 方式）](#后端启动conda-方式) | ||
| - [前端启动（Bun 方式）](#前端启动bun-方式) | ||
| - [桌面应用开发](#桌面应用开发) | ||
| - [Web 版本开发](#web-版本开发) | ||
| - [常见问题](#常见问题) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
修正目录锚点。
markdownlint-cli2 在 Line 18 through Line 22 and Line 24 reports MD051. These fragments are invalid, so the table of contents does not reliably navigate to the headings. Use the renderer-generated fragments or add explicit anchors.
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 18-18: Link fragments should be valid
(MD051, link-fragments)
[warning] 19-19: Link fragments should be valid
(MD051, link-fragments)
[warning] 20-20: Link fragments should be valid
(MD051, link-fragments)
[warning] 21-21: Link fragments should be valid
(MD051, link-fragments)
[warning] 22-22: Link fragments should be valid
(MD051, link-fragments)
[warning] 24-24: Link fragments should be valid
(MD051, link-fragments)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README_CN.md` around lines 18 - 24, 修正 README_CN.md 目录中的所有 Markdown
锚点，使其与对应标题生成的实际 fragment 完全一致；重点更新“快速开始（双端启动）”“后端启动（Conda 方式）”和“前端启动（Bun
方式）”等包含标点或空格的链接，并保留目录顺序与标题文本不变。
Source: Linters/SAST tools
| ```bash | ||
| # Linux/macOS 下载安装 Miniconda | ||
| wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh | ||
| bash Miniconda3-latest-Linux-x86_64.sh | ||
|
|
||
| # 或访问官网下载：https://docs.conda.io/en/latest/miniconda.html | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
为 macOS 提供正确的 Miniconda 安装命令。
Line 45 labels this block for Linux and macOS, but Line 46 downloads a Linux x86_64 installer. This file cannot run on macOS, including Apple Silicon. Split the commands by operating system and architecture, or link to the official installer selector.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README_CN.md` around lines 44 - 50, Update the Miniconda installation section
in README_CN.md so the Linux/macOS instructions no longer share the Linux x86_64
download command. Provide correct macOS installer commands for Intel and Apple
Silicon, while retaining the Linux command, or replace the platform-specific
commands with the official installer selector link.
| # --- AMD GPU (ROCm 6.3) --- | ||
| # pip install torch torchaudio --index-url https://download.pytorch.org/whl/rocm6.3 |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "## Files matching README and ROCm requirements"
git ls-files | rg '(^|/)(README_CN\.md|backend/requirements-rocm\.txt)$' || true
echo
echo "## README_CN.md lines around AMD/ROCm section"
sed -n '80,115p' README_CN.md
echo
echo "## backend/requirements-rocm.txt first lines"
if [ -f backend/requirements-rocm.txt ]; then
sed -n '1,40p' backend/requirements-rocm.txt
fi
echo
echo "## Search for ROCm references in README_CN.md"
rg -n -i 'roc|m\.rocom|amdgpu|AMD|torch' README_CN.mdRepository: jamiepine/voicebox
Length of output: 1783
🌐 Web query:
PyTorch ROCm 6.3 pip index-url download.pytorch.org/whl/rocm6.3 torch torchvision
💡 Result:
To install PyTorch with ROCm 6.3 support, you have two primary options: using the official PyTorch wheel repository or using AMD-validated wheels [1][2]. Option 1: Using the PyTorch wheel repository The official PyTorch repository provides wheels for ROCm 6.3 at https://download.pytorch.org/whl/rocm6.3 [3][4]. You can install specific versions (such as 2.7.x) using the index URL: pip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1 --index-url https://download.pytorch.org/whl/rocm6.3 Option 2: Using AMD-validated wheels (Recommended by AMD) AMD recommends using the wheels available at their dedicated repository (repo.radeon.com) for tested compatibility with specific ROCm releases [5]. For ROCm 6.3.2, wheels are available at https://repo.radeon.com/rocm/manylinux/rocm-rel-6.3.2/ [6]. To install manually from this repository, you must download the specific.whl files matching your Python version and architecture, then install them via pip [5]: # Example for Python 3.12 (Ubuntu 24.04) wget https://repo.radeon.com/rocm/manylinux/rocm-rel-6.3.2/torch-2.4.0%2Brocm6.3.2-cp312-cp312-linux_x86_64.whl wget https://repo.radeon.com/rocm/manylinux/rocm-rel-6.3.2/torchvision-0.19.0%2Brocm6.3.2-cp312-cp312-linux_x86_64.whl #... download other dependencies like pytorch_triton_rocm and torchaudio... pip install torch-2.4.0+rocm6.3.2-cp312-cp312-linux_x86_64.whl torchvision-0.19.0+rocm6.3.2-cp312-cp312-linux_x86_64.whl... Note: AMD notes that wheels from PyTorch.org are not tested as extensively by them as the versions in their own repository, and manual installation from repo.radeon.com requires ensuring compatibility with your specific Python environment [5]. Always check the official PyTorch "Get Started" page for the latest installation commands [7][5].
Citations:
- 1: https://rocm.docs.amd.com/projects/install-on-linux/en/docs-6.3.3/install/3rd-party/pytorch-install.html
- 2: https://rocm.docs.amd.com/projects/install-on-linux/en/docs-6.3.2/install/3rd-party/pytorch-install.html
- 3: https://download.pytorch.org/whl/rocm6.3
- 4: https://pytorch.org/get-started/previous-versions/
- 5: https://rocm.docs.amd.com/projects/radeon-ryzen/en/docs-6.3.2/docs/install/native_linux/install-pytorch.html
- 6: https://repo.radeon.com/rocm/manylinux/rocm-rel-6.3.2/
- 7: https://pytorch.org/get-started/locally/
🌐 Web query:
PyTorch ROCm 7.2.1 pip index-url download.pytorch.org/whl/rocm7.2.1
💡 Result:
For PyTorch support with ROCm 7.2.1, AMD recommends using specific wheel files hosted on their own repository (repo.radeon.com) rather than the standard PyTorch pip index [1][2][3]. While PyTorch nightly builds may contain ROCm 7.2 support [4][5][6], AMD provides explicitly validated production releases for PyTorch 2.9.1 with ROCm 7.2.1 [7][6][8]. To install these specific versions, follow the official AMD documentation for your platform (Linux or Windows), which involves manually downloading the wheels [1][2][9]. For example, on supported Linux systems, you can install the validated PyTorch 2.9.1 + ROCm 7.2.1 packages using the following approach [2][10]: 1. Download the required wheels from the AMD repository: - torch-2.9.1+rocm7.2.1...whl - torchvision-0.24.0+rocm7.2.1...whl - triton-3.5.1+rocm7.2.1...whl - torchaudio-2.9.0+rocm7.2.1...whl 2. Install the wheels using pip: pip3 install <filename_torch> <filename_torchvision> <filename_triton> <filename_torchaudio> For comprehensive installation instructions, compatibility matrices, and direct download links, refer to the official AMD ROCm documentation [1][7][6]. AMD notes that while nightly wheels may be available at download.pytorch.org, they are not tested as extensively as the versions provided via repo.radeon.com [1][2][6].
Citations:
- 1: https://rocm.docs.amd.com/projects/radeon-ryzen/en/latest/docs/install/installrad/native_linux/install-pytorch.html
- 2: https://rocm.docs.amd.com/projects/radeon-ryzen/en/latest/docs/install/installryz/native_linux/install-pytorch.html
- 3: https://rocm.docs.amd.com/projects/radeon-ryzen/en/docs-7.2.1/docs/install/installrad/native_linux/install-pytorch.html
- 4: https://rocm.docs.amd.com/projects/install-on-linux/en/docs-7.2.1/install/3rd-party/pytorch-install.html
- 5: https://rocmdocs.amd.com/projects/install-on-linux/en/latest/install/3rd-party/pytorch-install.html
- 6: https://rocm.docs.amd.com/projects/radeon-ryzen/en/latest/docs/compatibility/compatibilityrad/native_linux/native_linux_compatibility.html
- 7: https://rocm.docs.amd.com/projects/radeon-ryzen/en/docs-7.2.1/docs/compatibility/compatibilityryz/native_linux/native_linux_compatibility.html
- 8: https://rocm.docs.amd.com/en/docs-7.2.3/compatibility/ml-compatibility/pytorch-compatibility.html
- 9: https://rocm.docs.amd.com/projects/radeon-ryzen/en/docs-7.2.1/docs/install/installrad/windows/install-pytorch.html
- 10: https://rocm.docs.amd.com/projects/radeon-ryzen/en/docs-7.2.1/docs/install/installryz/native%5Flinux/install-pytorch.html
让 AMD/ROCm 安装说明与仓库依赖文件对齐。
当前 AMD 部分指向未测试过 torchvision 的公开 ROCm 6.3 索引，而 backend/requirements-rocm.txt 为 ROCm 7.2.1 固定了 torch、torchaudio 和 torchvision。将 AMD 说明拆分为平台特定指令，并使用仓库 requirements 文件或 AMD 官方 validated 安装方案安装这些包。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README_CN.md` around lines 98 - 99, 更新 README_CN.md 的 AMD GPU 安装说明，移除仅安装
torch 和 torchaudio 的 ROCm 6.3 索引命令；参照 backend/requirements-rocm.txt，将 AMD/Linux
与其他平台拆分为对应指令，并确保 torch、torchaudio 和 torchvision 使用仓库固定的 ROCm 7.2.1 依赖或 AMD 官方
validated 安装方案。
| # 方式2：指定主机地址（允许局域网访问） | ||
| uvicorn backend.main:app --reload --host 0.0.0.0 --port 17493 |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 4 -e '0\.0\.0\.0|auth|authorization|api[_-]?key|Depends\(|middleware' backend backend/README.mdRepository: jamiepine/voicebox
Length of output: 50376
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '--- candidate auth/security files ---\n'
git ls-files backend | rg -n '.*(auth|security|middleware|client|key|role|permission|depend|middleware).*' || true
printf '\n--- exact auth/z security tokens ---\n'
rg -n --glob '!backend/app.py' \
'Bearer\s*\$\{|Authorization|API[_-]?[Aa]uth|api[_-]?key|HttpBearer|OAuth2|PasswordOAuth2|Security\s*\(Depends|AuthenticationError|AuthError|permission|role|ALLOWED_ORIGIN|allow_cors' backend/api auth security 2>/dev/null || true
printf '\n--- app middleware section ---\n'
sed -n '160,220p' backend/app.py
cat -n backend/app.py | sed -n '220,340p'
printf '\n--- route auth usage summary ---\n'
python3 - <<'PY'
import pathlib,re
for p in pathlib.Path('backend/routes').glob('*.py'):
txt=p.read_text()
if 'Depends(' in txt or 'Security(' in txt or 'Authorization' in txt or 'Bearer' in txt:
lines=txt.splitlines()
print(f'\n{p}')
for i,l in enumerate(lines,1):
if re.search(r'\b(Depends|Security|Authorization|Bearer|HTTPBearer|OAuth2|SecuritySchemes|APIKey|ApiKey|permission|permission)', l):
print(f'{i}: {l}')
printf '\n--- route files with security-related names/content excluding auth-specific ---\n'
rg -n --glob 'backend/routes/*.py' '(^router\.|Security\s*\(|HttpBearer|Bearer|Authorization|Depends\s*\([^)]*Security[^)]*)|permission|role|auth' backend/routes || true
PY
printf '\n--- README lines around recommendation ---\n'
cat -n README_CN.md | sed -n '155,185p'
cat -n README.md | sed -n '155,185p'Repository: jamiepine/voicebox
Length of output: 247
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- candidate auth/security files ---'
git ls-files backend | rg -n '.*(auth|security|middleware|client|key|role|perm|depend).*' || true
printf '%s\n' ''
printf '%s\n' '--- exact auth/z security tokens ---'
rg -n --glob '!backend/app.py' \
'Bearer\s*\$\{|Authorization|API[_-]?[Aa]uth|api[_-]?key|HttpBearer|OAuth2|PasswordOAuth2|Security\s*\(|AuthenticationError|AuthError|permission|role|ALLOWED_ORIGIN|allow_cors' backend/api auth security 2>/dev/null || true
printf '%s\n' ''
printf '%s\n' '--- app middleware section ---'
sed -n '160,220p' backend/app.py
cat -n backend/app.py | sed -n '220,340p'
printf '%s\n' ''
printf '%s\n' '--- route auth usage summary ---'
python3 - <<'PY'
import pathlib,re
for p in pathlib.Path('backend/routes').glob('*.py'):
txt=p.read_text()
if 'Depens(' in txt or 'Security(' in txt or 'Authorization' in txt or 'Bearer' in txt:
pass
if 'Depends(' in txt or 'Security(' in txt or 'Authorization' in txt or 'Bearer' in txt or 'permission' in txt:
lines=txt.splitlines()
print(f'\n{p}')
for i,l in enumerate(lines,1):
if re.search(r'\b(Depends|Security|Authorization|Bearer|HttpBearer|OAuth2|SecuritySchemes|APIKey|ApiKey|permission|role|auth)', l):
print(f'{i}: {l}')
PY
printf '%s\n' ''
printf '%s\n' '--- route files with security-related pattern ---\n'
rg -n --glob 'backend/routes/*.py' '(^router\.|Security\s*\( |HttpBearer|Bearer|Authorization|Depends\s*\([^)]*Security[^)]*)|permission|role|auth' backend/routes || true
printf '%s\n' ''
printf '%s\n' '--- README lines around recommendation ---'
cat -n README_CN.md | sed -n '155,185p'
cat -n README.md | sed -n '155,185p'Repository: jamiepine/voicebox
Length of output: 15968
在 0.0.0.0 示例前加上安全边界说明。
当前后端没有显式的认证或授权前置依赖；ClientIdMiddleware 不会保护其他主机调用。添加一条明确的前提说明，例如“仅用于可信局域网且你已自行设置网络隔离/防火墙，否则使用 --host 127.0.0.1"。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README_CN.md` around lines 171 - 172, 在 README_CN.md
的“方式2：指定主机地址”示例前补充安全前提说明：由于当前后端没有可靠的认证授权保护，0.0.0.0
仅应在可信局域网且已配置网络隔离或防火墙时使用；否则引导用户改用 --host 127.0.0.1。
| ### 桌面应用前端（配合 Tauri） | ||
|
|
||
| 如果你要开发桌面应用，需要在 `tauri` 目录启动： | ||
|
|
||
| ```bash | ||
| # 需要先确保后端已在 17493 端口运行 | ||
| cd tauri | ||
| bun run tauri dev | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 3 '"(dev|build|tauri)"|workspaces' package.json
for dir in app tauri; do
if [ -f "$dir/package.json" ]; then
echo "== $dir/package.json =="
rg -n -C 3 '"(dev|build|tauri)"' "$dir/package.json"
fi
doneRepository: jamiepine/voicebox
Length of output: 1339
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== README_CN package/dev command references =="
rg -n -C 4 'bun run (setup:dev|dev|dev:web|dev:server|dev:landing)|cd tauri|tauri dev|tauri build|Tauri|桌面应用|桌面应用前端' README_CN.md
echo
echo "== package/workspace files =="
for f in package.json tauri/package.json tauri/tauri.conf.json; do
if [ -f "$f" ]; then
echo "== $f =="
sed -n '1,220p' "$f"
fi
doneRepository: jamiepine/voicebox
Length of output: 5018
统一桌面开发的启动说明。
根目录 bun run dev 已在 setup:dev 后执行 cd tauri && bun run tauri dev，而桌面前端章节又要求先进入 tauri 后执行 bun run tauri dev。说明应以终端 2 的 bun run dev 为桌面开发启动方式；tauri/dev 命令是 vite，不应指向桌面应用 Tauri 启动。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README_CN.md` around lines 242 - 250, 更新 README_CN.md 中“桌面应用前端（配合
Tauri）”章节，将桌面开发启动方式统一为终端 2 执行根目录的 bun run dev；移除要求先进入 tauri 目录执行 bun run tauri
dev 的说明，并明确 tauri/dev 仅用于 Vite 开发服务器，不作为桌面应用启动命令。
There was a problem hiding this comment.
Actionable comments posted: 8
🧹 Nitpick comments (1)
启动指南.md (1)
386-395: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win不要将 Hugging Face 镜像源设置为当前默认值。
HF_ENDPOINT=...会把模型下载重定向到第三方端点。保留https://huggingface.co为默认值，仅作为可选方案，并提醒用户在信任该镜像后再设置；如需鉴权下载，说明第三方镜像同样会承载HF_TOKEN流量。🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@启动指南.md` around lines 386 - 395, 更新“模型下载慢怎么办？”中的 Hugging Face 配置说明：保留 https://huggingface.co 作为默认端点，将 https://hf-mirror.com 仅作为用户确认信任后的可选方案，并提醒需要鉴权时第三方镜像同样会承载 HF_TOKEN 流量。
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@启动指南.md`:
- Around line 430-440: 将“环境重置”命令明确标注为仅适用于 Linux/macOS，并补充对应的 Windows PowerShell
清理命令，覆盖 Conda 环境、各目录的 node_modules 以及 backend 下的 __pycache__ 和
*.egg-info，确保两类系统用户都能执行。
- Around line 259-264: 更新“文档网站开发”说明及对应配置，确保干净检出后执行 cd docs && bun run dev 前会安装
docs 的独立依赖：优先将 docs 加入根 package.json 的 workspaces；若不适用，则在开发命令前补充 cd docs && bun
install。
- Around line 44-50: 将 Miniconda 安装说明中的 Linux/macOS 合并命令拆分：Linux
使用对应架构的安装器，macOS 分别提供 Intel 与 Apple Silicon
安装器，或仅保留官方安装器选择页面链接；确保每条命令与目标操作系统和架构匹配。
- Around line 171-172: Update the “方式2：指定主机地址” guidance around the uvicorn
command to state that 0.0.0.0 should only be used on a trusted, isolated LAN
with appropriate firewall and authentication protections; direct other users to
use --host 127.0.0.1.
- Around line 18-24: 修正启动指南目录中的所有 Markdown 链接锚点，使其与对应标题渲染后生成的 fragment
完全一致，重点检查“快速开始（双端启动）”“后端启动（Conda 方式）”“前端启动（Bun
方式）”等包含中文标点、括号或空格的标题；保持目录条目和标题对应关系不变，并确保 markdownlint MD051 不再报告问题。
- Around line 410-415: 移除“强制使用 CPU”示例及 VOICEBOX_FORCE_CPU
环境变量说明，避免将未被后端读取的变量描述为有效开关；保留基于 VOICEBOX_BACKEND_VARIANT、binary 名称或自动探测的后端选择说明。
- Around line 242-250: 更新“桌面应用前端（配合 Tauri）”这段说明，与 Frontend dev
章节的标准启动流程保持一致；当前只写进入 tauri 后直接运行 bun run tauri dev，但根目录的 bun run dev 会先执行 bun
run setup:dev。请在该段落中优先引导使用 bun run dev 作为桌面应用标准流程，若仍保留直接进入 tauri 的路径，则明确需要先执行
bun run setup:dev 再运行 bun run tauri dev，保持 tauri 启动说明与 setup:dev / bun run dev
的实际行为一致。
- Around line 98-99: 更新“AMD GPU (ROCm 6.3)”安装说明，使其与 justfile 中的 ROCm 选择逻辑一致：优先使用
VOICEBOX_ROCM_VERSION，Linux Navi 4 默认使用 ROCm 7.2，其他 AMD GPU 默认使用 ROCm
6.3；同时明确支持的 GPU、操作系统与对应 PyTorch wheel 索引。
---
Nitpick comments:
In `@启动指南.md`:
- Around line 386-395: 更新“模型下载慢怎么办？”中的 Hugging Face 配置说明：保留
https://huggingface.co 作为默认端点，将 https://hf-mirror.com
仅作为用户确认信任后的可选方案，并提醒需要鉴权时第三方镜像同样会承载 HF_TOKEN 流量。
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| ```bash | ||
| # Linux/macOS 下载安装 Miniconda | ||
| wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh | ||
| bash Miniconda3-latest-Linux-x86_64.sh | ||
|
|
||
| # 或访问官网下载：https://docs.conda.io/en/latest/miniconda.html | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
拆分 Linux 与 macOS 的 Miniconda 安装命令。
Line 45 将命令标为 Linux/macOS，但 Line 46 下载的是 Linux x86_64 安装器。该文件不能在 macOS 上运行，也不适用于 Apple Silicon。请按操作系统和架构提供安装器，或仅链接到官方安装器选择页面。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@启动指南.md` around lines 44 - 50, 将 Miniconda 安装说明中的 Linux/macOS 合并命令拆分：Linux
使用对应架构的安装器，macOS 分别提供 Intel 与 Apple Silicon
安装器，或仅保留官方安装器选择页面链接；确保每条命令与目标操作系统和架构匹配。
| # --- AMD GPU (ROCm 6.3) --- | ||
| # pip install torch torchaudio --index-url https://download.pytorch.org/whl/rocm6.3 |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== files =="
git ls-files | rg '(^|/)启动指南\.md$|(^|/)justfile$|README|voicebox' || true
echo
echo "== 启动指南.md relevant sections =="
if [ -f 启动指南.md ]; then
nl -ba 启动指南.md | sed -n '80,115p'
fi
echo
echo "== justfile rocms/version/gpu references =="
if [ -f justfile ]; then
rg -n "ROCm|rocm|VOICEBOX_ROCM_VERSION|gpu|Navi|4|6\.3|7\.2|torch" justfile || true
fi
echo
echo "== all local references to 启动指南 or voicebox_rocm_version or rocM =="
rg -n "启动指南|VOICEBOX_ROCM_VERSION|ROCm 6\.3|rocM|rocm" . --glob '!{*.png,*.jpg,*.jpeg,*.gif,*.json}' || trueRepository: jamiepine/voicebox
Length of output: 1305
🌐 Web query:
VoiceBox jamepine repo justfile VOICEBOX_ROCM_VERSION ROCm 6.3 7.2 GPU selection
💡 Result:
In the jamiepine/voicebox repository, VOICEBOX_ROCM_VERSION is an environment variable used to specify the version of ROCm for which PyTorch should be installed when running on Linux with an AMD GPU [1][2][3]. The project uses this variable within the justfile and Docker configurations to select the appropriate PyTorch wheel from the official PyTorch index (https://download.pytorch.org/whl/rocm${VOICEBOX_ROCM_VERSION}) [1][3][4]. Key details regarding this configuration include: Default and Selection Logic: - The default value is 6.3 [2][3][4]. - If the GPU is detected as RDNA 4 (via lspci output matching "Navi 4"), the version is automatically set to 7.2 [1]. - Users can manually override this by exporting the variable, for example: export ROCM_VERSION=7.2 [2][3]. GPU Selection and Configuration: - On Linux/AMD, Voicebox automatically configures the ROCm runtime environment [5]. - The HSA_OVERRIDE_GFX_VERSION environment variable is used to force the ROCm runtime to treat the GPU as a specific GFX version, which is particularly important if auto-detection fails or when using newer GPUs [2][5]. - Common GFX version overrides include: - 12.0.0 for RDNA 4 (RX 9000 series) [2] - 11.0.0 for RDNA 3 (RX 7000 series / Strix Halo) [2][5] - 10.3.0 for RDNA 2 (RX 6000 series) [2][5] - 10.1.0 for RDNA 1 (RX 5000 series) [2] - 9.0.0 for older Vega cards [2][5] For Docker users, the configuration is managed via the docker-compose.rocm.yml overlay, which allows for passing these environment variables and device mappings (/dev/kfd and /dev/dri) to the container [2][3].
Citations:
- 1: https://github.com/jamiepine/voicebox/blob/f2cf2a72/justfile
- 2: https://github.com/jamiepine/voicebox/blob/main/docker-compose.rocm.yml
- 3: fix(docker): add ROCm GPU support via compose overlay #630
- 4: https://github.com/jamiepine/voicebox/blob/main/Dockerfile
- 5: https://docs.voicebox.sh/overview/gpu-acceleration
🏁 Script executed:
#!/bin/bash
set -u
echo "== justfile outline/size =="
wc -l justfile
head -220 justfile
echo
echo "== 启动指南.md relevant sections =="
for f in 启动指南.md docs/content/docs/README.md README.md; do
if [ -f "$f" ]; then
echo "--- $f ---"
awk 'NR>=80 && NR<=115 {printf "%7d\t%s\n", NR, $0}' "$f"
fi
done
echo
echo "== rocm/gpu/version references =="
python3 - <<'PY'
from pathlib import Path
import re
terms = ['ROCM', 'ROCm', 'rocm', 'VOICEBOX_ROCM_VERSION', 'VOICEBOX GPU', 'VOICEBOX_ROCM', '6.3', '7.2', 'Navi', 'RDNA', 'gfx', 'pip install torch']
for path in Path('.').rglob('*'):
if path.is_file() and not any(part in {'.git','node_modules','build','dist'}) for part in path.parts):
try:
text = path.read_text(errors='ignore')
except Exception:
continue
if any(term in text for term in terms):
lines = [(i+1, line) for i,line in enumerate(text.splitlines()) if any(term in line for term in terms)]
if lines and path.name != 'voicebox-logo.png':
print(f"--- {path} ---")
for i,l in lines[:50]:
print(f"{i:4}: {l}")
PYRepository: jamiepine/voicebox
Length of output: 13951
将 AMD/ROCm 安装说明与仓库选择逻辑对齐。
justfile 在 Linux AMD GPU 上优先使用 VOICEBOX_ROCM_VERSION，没有该变量时会将 Detect Navi 4 设为 6.3 以外的 7.2，其他情况用 6.3。指南目前固定为 ROCm 6.3，会让 Navi 4 等 GPU 安装错误的 PyTorch wheel。复用仓库的选择逻辑，或补充支持的 GPU、操作系统和 ROCm 版本矩阵。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@启动指南.md` around lines 98 - 99, 更新“AMD GPU (ROCm 6.3)”安装说明，使其与 justfile 中的
ROCm 选择逻辑一致：优先使用 VOICEBOX_ROCM_VERSION，Linux Navi 4 默认使用 ROCm 7.2，其他 AMD GPU
默认使用 ROCm 6.3；同时明确支持的 GPU、操作系统与对应 PyTorch wheel 索引。
| # 方式2：指定主机地址（允许局域网访问） | ||
| uvicorn backend.main:app --reload --host 0.0.0.0 --port 17493 |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win
为 0.0.0.0 添加安全前提。
绑定到 0.0.0.0 会让开发 API 监听所有网卡。当前说明只写“允许局域网访问”，没有说明可信网络、防火墙或认证要求。请明确仅在受信任且已隔离的局域网使用；其他情况使用 --host 127.0.0.1。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@启动指南.md` around lines 171 - 172, Update the “方式2：指定主机地址” guidance around the
uvicorn command to state that 0.0.0.0 should only be used on a trusted, isolated
LAN with appropriate firewall and authentication protections; direct other users
to use --host 127.0.0.1.
| ### 桌面应用前端（配合 Tauri） | ||
|
|
||
| 如果你要开发桌面应用，需要在 `tauri` 目录启动： | ||
|
|
||
| ```bash | ||
| # 需要先确保后端已在 17493 端口运行 | ||
| cd tauri | ||
| bun run tauri dev | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== files =="
git ls-files | rg '(^|/)(package\.json|启动指南\.md|README.*|setup)' || true
echo "== package.json scripts =="
if [ -f package.json ]; then
cat package.json | jq '.scripts // {}'
fi
echo "== relevant doc lines =="
if [ -f 启动指南.md ]; then
sed -n '220,345p' 启动指南.md | cat -n
else
echo "missing 启动指南.md"
fi
echo "== search setup/dev references =="
rg -n "bun run (dev|setup:dev|tauri)|setup:dev|启动指南|启动 Tauri|tauri dev" .Repository: jamiepine/voicebox
Length of output: 6830
让 Frontend dev 章节和桌面应用启动一致。
Lines 242-250 要求进入 tauri 目录后直接执行 bun run tauri dev，但根目录 bun run dev 会先执行 bun run setup:dev 再启动 Tauri。保持桌面应用标准流程为 bun run dev；若保留直接进入 tauri 的分支，需先执行 bun run setup:dev 或说明可跳过该步骤。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@启动指南.md` around lines 242 - 250, 更新“桌面应用前端（配合 Tauri）”这段说明，与 Frontend dev
章节的标准启动流程保持一致；当前只写进入 tauri 后直接运行 bun run tauri dev，但根目录的 bun run dev 会先执行 bun
run setup:dev。请在该段落中优先引导使用 bun run dev 作为桌面应用标准流程，若仍保留直接进入 tauri 的路径，则明确需要先执行
bun run setup:dev 再运行 bun run tauri dev，保持 tauri 启动说明与 setup:dev / bun run dev
的实际行为一致。
| ### 文档网站开发 | ||
|
|
||
| ```bash | ||
| cd docs | ||
| bun run dev | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
为文档站安装独立依赖。
Line 132 说明根目录 bun install 会安装所有工作区依赖，但根 package.json 的 workspaces 仅包含 app、tauri、web 和 landing，不包含 docs。因此，干净检出后执行 cd docs && bun run dev 时没有安装文档站依赖。请将 docs 加入工作区，或在此处增加 cd docs && bun install。 (raw.githubusercontent.com)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@启动指南.md` around lines 259 - 264, 更新“文档网站开发”说明及对应配置，确保干净检出后执行 cd docs && bun
run dev 前会安装 docs 的独立依赖：优先将 docs 加入根 package.json 的 workspaces；若不适用，则在开发命令前补充 cd
docs && bun install。
| 可以通过环境变量强制指定： | ||
|
|
||
| ```bash | ||
| # 强制使用 CPU | ||
| VOICEBOX_FORCE_CPU=1 uvicorn backend.main:app --reload --port 17493 | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n --glob '*.py' \
'VOICEBOX_FORCE_CPU|FORCE_CPU|VOICEBOX_BACKEND_VARIANT|backend_variant|get_backend_type' \
backendRepository: jamiepine/voicebox
Length of output: 2499
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== platform_detect.py =="
cat -n backend/utils/platform_detect.py | sed -n '1,140p'
echo "== backend backends init relevant =="
cat -n backend/backends/__init__.py | sed -n '1,90p'
cat -n backend/backends/__init__.py | sed -n '210,265p'
cat -n backend/backends/__init__.py | sed -n '400,440p'
cat -n backend/backends/__init__.py | sed -n '670,800p'
echo "== server.py env setup =="
cat -n backend/server.py | sed -n '40,70p'
cat -n backend/server.py | sed -n '260,280p'
echo "== README lines =="
cat -n 启动指南.md | sed -n '390,425p'
echo "== environment variable references =="
rg -n --glob '*.py' 'os\.environ\.|getenv|FORCE_CPU|backend_variant|backend_type' backend | sed -n '1,220p'Repository: jamiepine/voicebox
Length of output: 23401
移除无效的环境变量说明。
VOICEBOX_FORCE_CPU 不会被后端代码读取；当前后端选择只处理 VOICEBOX_BACKEND_VARIANT、binary 名称或自动探测。这个命令会静默按现有自动选择继续运行，不要把它写成有效的 CPU 强制开关。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@启动指南.md` around lines 410 - 415, 移除“强制使用 CPU”示例及 VOICEBOX_FORCE_CPU
环境变量说明，避免将未被后端读取的变量描述为有效开关；保留基于 VOICEBOX_BACKEND_VARIANT、binary 名称或自动探测的后端选择说明。
| ```bash | ||
| # 1. 删除 Conda 环境 | ||
| conda deactivate | ||
| conda env remove -n voicebox | ||
|
|
||
| # 2. 删除 node_modules | ||
| rm -rf node_modules app/node_modules tauri/node_modules web/node_modules landing/node_modules docs/node_modules | ||
|
|
||
| # 3. 清除 Python 缓存 | ||
| find backend -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null | ||
| find backend -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
标明环境重置命令仅适用于 Unix，或补充 Windows PowerShell 版本。
Lines 430-440 使用 rm -rf 和 find -exec，但没有操作系统说明。Windows 用户无法直接执行这些命令。请补充 PowerShell 等价命令，或将本节标记为 Linux/macOS 专用。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@启动指南.md` around lines 430 - 440, 将“环境重置”命令明确标注为仅适用于 Linux/macOS，并补充对应的
Windows PowerShell 清理命令，覆盖 Conda 环境、各目录的 node_modules 以及 backend 下的 __pycache__
和 *.egg-info，确保两类系统用户都能执行。
There was a problem hiding this comment.
Actionable comments posted: 5
♻️ Duplicate comments (3)
启动指南.md (3)
630-631: 🎯 Functional Correctness | 🟡 Minor移除无效的 CPU 强制开关。
后端不会读取
VOICEBOX_FORCE_CPU。该命令不会强制使用 CPU，可能静默继续使用自动选择的后端。请删除该示例，或改用后端实际读取的VOICEBOX_BACKEND_VARIANT配置。🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@启动指南.md` around lines 630 - 631, 更新启动指南中的 uv 启动示例，移除未被后端读取的 VOICEBOX_FORCE_CPU 环境变量；如需保留 CPU 强制示例，改用后端实际读取的 VOICEBOX_BACKEND_VARIANT 配置。
437-439: 🎯 Functional Correctness | 🟡 Minor让 Tauri 启动流程执行
setup:dev。当前路径直接执行
bun run tauri dev。根目录的标准脚本bun run dev会先执行bun run setup:dev。请优先使用bun run dev，或在直接启动前明确执行bun run setup:dev。🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@启动指南.md` around lines 437 - 439, 更新“启动指南”中的 Tauri 启动流程，优先将当前直接执行的 bun run tauri dev 替换为会先执行 setup:dev 的 bun run dev；若必须保留直接启动方式，则在其前面明确执行 bun run setup:dev。
21-21: 🎯 Functional Correctness | 🟡 Minor修正 uv 后端章节的目录锚点。
markdownlint-cli2仍在 Line 21 报告 MD051。当前 fragment 与标题生成的实际 ID 不一致，目录项不能可靠跳转。请使用渲染器生成的 fragment，或为目标标题添加显式锚点，并重新运行 markdownlint。🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@启动指南.md` at line 21, 修正目录中的“后端启动（uv 方式，推荐）”链接，使其 fragment 与目标标题实际生成的 ID 一致；优先采用渲染器生成的锚点，或为该标题添加显式锚点，并重新运行 markdownlint-cli2 确认 MD051 消失。Source: Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@启动指南.md`:
- Around line 117-118: 更新“AMD GPU (ROCm 6.3)”安装说明，参照 justfile 中的
VOICEBOX_ROCM_VERSION、Navi 4、rocm6.3 和 rocm7.2 选择逻辑：优先遵循
VOICEBOX_ROCM_VERSION，未设置时 Navi 4 默认使用 ROCm 7.2，其他受支持的 AMD GPU 使用 ROCm
6.3；不要再固定为单一 ROCm 版本。
- Around line 324-325: 更新“方式5：自定义数据目录”中的启动命令，显式添加前端和健康检查流程所需的 17493
端口参数，确保使用自定义数据目录时服务监听端口与指南其他流程一致。
- Around line 373-399: 统一启动指南中的依赖安装流程：检查快速开始部分使用的 uv pip
install、requirements.txt 与后续 uv sync/uv lock/uv add 的配置来源，确保
torch、chatterbox-tts、hume-tada、mlx-*、ruff、pytest 等依赖统一声明在 backend/pyproject.toml
并反映到 uv.lock；同时调整文档命令，避免用户混用依赖源导致 uv sync 移除未声明的包。
- Line 359: 删除启动指南中的无效“uv pip install --dev
<package-name>”命令，并改为文档支持的开发依赖方式：使用“uv add --dev <package-name>”，或根据上下文改为“uv
sync”/“uv run”。
- Around line 537-538: 更新“启动指南”中的 Conda 桌面流程，避免将未安装的 just 作为前置依赖；将 just dev
替换为已提供的 bun run dev，或明确补充 just 的安装步骤并确保 justfile 使用已激活的 Conda 环境。
---
Duplicate comments:
In `@启动指南.md`:
- Around line 630-631: 更新启动指南中的 uv 启动示例，移除未被后端读取的 VOICEBOX_FORCE_CPU 环境变量；如需保留
CPU 强制示例，改用后端实际读取的 VOICEBOX_BACKEND_VARIANT 配置。
- Around line 437-439: 更新“启动指南”中的 Tauri 启动流程，优先将当前直接执行的 bun run tauri dev
替换为会先执行 setup:dev 的 bun run dev；若必须保留直接启动方式，则在其前面明确执行 bun run setup:dev。
- Line 21: 修正目录中的“后端启动（uv 方式，推荐）”链接，使其 fragment 与目标标题实际生成的 ID
一致；优先采用渲染器生成的锚点，或为该标题添加显式锚点，并重新运行 markdownlint-cli2 确认 MD051 消失。
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| # --- AMD GPU (ROCm 6.3) --- | ||
| # uv pip install torch torchaudio --index-url https://download.pytorch.org/whl/rocm6.3 |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major
不要固定 AMD 安装为 ROCm 6.3。
Lines 117-118 can select the wrong PyTorch wheel for Linux Navi 4 hardware. Align this section with the repository selection logic: honor VOICEBOX_ROCM_VERSION, use ROCm 7.2 for Navi 4 by default, and use ROCm 6.3 for other supported AMD GPUs.
#!/bin/bash
set -u
rg -n 'VOICEBOX_ROCM_VERSION|Navi 4|rocm6\.3|rocm7\.2' justfile || true🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@启动指南.md` around lines 117 - 118, 更新“AMD GPU (ROCm 6.3)”安装说明，参照 justfile 中的
VOICEBOX_ROCM_VERSION、Navi 4、rocm6.3 和 rocm7.2 选择逻辑：优先遵循
VOICEBOX_ROCM_VERSION，未设置时 Navi 4 默认使用 ROCm 7.2，其他受支持的 AMD GPU 使用 ROCm
6.3；不要再固定为单一 ROCm 版本。
| # 方式5：自定义数据目录 | ||
| uv run python -m backend.main --data-dir ./data |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
为自定义数据目录命令保留 17493 端口。
backend/main.py 的 --port 默认值是 8000。该命令未指定端口，但本指南的前端和健康检查流程使用 17493。执行此命令后，前端会连接错误的端口。
建议修改
-uv run python -m backend.main --data-dir ./data
+uv run python -m backend.main --data-dir ./data --port 17493📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # 方式5：自定义数据目录 | |
| uv run python -m backend.main --data-dir ./data | |
| # 方式5：自定义数据目录 | |
| uv run python -m backend.main --data-dir ./data --port 17493 |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@启动指南.md` around lines 324 - 325, 更新“方式5：自定义数据目录”中的启动命令，显式添加前端和健康检查流程所需的 17493
端口参数，确保使用自定义数据目录时服务监听端口与指南其他流程一致。
| uv pip install <package-name> | ||
|
|
||
| # 安装开发依赖 | ||
| uv pip install --dev <package-name> |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
command -v uv >/dev/null
uv --version
help="$(uv pip install --help)"
if grep -Eq '(^|[[:space:]])--dev([[:space:]]|$)' <<<"$help"; then
echo "Unexpected: uv pip install exposes --dev"
exit 1
fi
grep -Eq -- '--group' <<<"$help"Repository: jamiepine/voicebox
Length of output: 156
🏁 Script executed:
set -euo pipefail
uv --version
echo '--- uv pip install --help relevant lines ---'
uv pip install --help | sed -n '1,140p'
echo '--- uv add --help dev relevant lines ---'
uv add --help | sed -n '1,160p'Repository: jamiepine/voicebox
Length of output: 196
🏁 Script executed:
set -euo pipefail
cat -n 启动指南.md | sed -n '345,365p'Repository: jamiepine/voicebox
Length of output: 613
🌐 Web query:
uv pip install --dev option uv add dev
💡 Result:
There is no --dev option for the uv pip install command because the uv pip interface is designed to be a pip-compatible tool that manages packages in the current environment rather than reading project-level dependency groups [1]. To manage development dependencies in uv, you should use the project-based workflow rather than the uv pip interface [1][2]. 1. Adding Development Dependencies: Use the uv add command with the --dev flag to add a package to the dev dependency group [3][4]. $ uv add --dev This command automatically updates your pyproject.toml and your uv.lock file [5][6]. 2. Installing Development Dependencies: When working with a uv project, development dependencies (specifically the dev group) are installed by default when you run uv sync or uv run [3][7][8]. 3. Excluding Development Dependencies: If you need to exclude development dependencies (for example, in a production or deployment environment), you can use the --no-dev flag with commands like uv sync [9][8]. $ uv sync --no-dev If you are using the uv pip interface and need to handle groups, note that the --group argument is generally not supported for pip commands, and the pip interface is intended for environments where project-level group definitions are not the primary mechanism [1][2]. For deployments, it is recommended to use uv export or uv sync to generate your environment [1][8].
Citations:
- 1: Add a --no-dev option to
uv pipcommands astral-sh/uv#10437 - 2: How can I do soething like this
uv pip install -r pyproject.toml --group devastral-sh/uv#14590 - 3: https://docs.astral.sh/uv/concepts/projects/dependencies/
- 4: https://pydevtools.com/handbook/how-to/how-to-add-a-dependency-with-uv/
- 5: https://stackoverflow.com/questions/78902565/how-do-i-install-python-dev-dependencies-using-uv
- 6: https://docs.astral.sh/uv/guides/projects/
- 7: https://docs.astral.sh/uv/reference/settings/
- 8: https://docs.astral.sh/uv/concepts/projects/sync/
- 9: https://docs.astral.sh/uv/reference/cli/
删除无效的 uv pip install --dev 命令。
uv pip install 不接受 --dev；如需使用 uv 的开发依赖流程，可用 uv add --dev <package-name>，或改用 uv sync/uv run。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@启动指南.md` at line 359, 删除启动指南中的无效“uv pip install --dev
<package-name>”命令，并改为文档支持的开发依赖方式：使用“uv add --dev <package-name>”，或根据上下文改为“uv
sync”/“uv run”。
| # 需要先配置好 Python 环境（venv 方式，或自行调整 justfile） | ||
| just dev |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
不要让 Conda 桌面流程依赖未安装的 just。
环境要求没有安装 just 的步骤。干净环境执行 just dev 会直接失败。请复用 bun run dev，或补充 just 的安装步骤并确认 justfile 使用已激活的 Conda 环境。
建议修改
-just dev
+bun run dev🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@启动指南.md` around lines 537 - 538, 更新“启动指南”中的 Conda 桌面流程，避免将未安装的 just 作为前置依赖；将
just dev 替换为已提供的 bun run dev，或明确补充 just 的安装步骤并确保 justfile 使用已激活的 Conda 环境。
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@Makefile`:
- Around line 151-154: Update the Makefile kill target to stop only processes
launched by this worktree: reuse a repository-local PID file or recorded process
group created by the startup target, validate the recorded processes before
terminating them, and remove the PID tracking file afterward. Eliminate broad
pkill patterns, including the uvicorn and vite commands.
In `@pyproject.toml`:
- Around line 106-110: Pin the Git sources for qwen-tts, linacodec, and Zipvoice
in pyproject.toml using tested immutable commit revisions, then regenerate and
commit uv.lock with the corresponding pinned metadata; update the installation
flow in Makefile lines 84-105 only as needed to install from the lockfile.
In `@README.md`:
- Around line 37-41: Update the README navigation links for 下载 and 功能 to use the
anchors generated from their translated section headings instead of `#download`
and `#features`. Leave the other navigation links unchanged.
- Around line 408-420: 更新 README 的“快速开始”部分，将 just setup/dev 替换为 Makefile 定义的
make setup/dev，并将依赖安装说明改为通过 uv sync 完成；同步前置条件，移除 just，改为要求安装 uv，并将 Python
版本声明调整为当前配置要求。
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: c32c5d39-623f-431c-8f06-2a99c3b7cf82
⛔ Files ignored due to path filters (1)
uv.lockis excluded by!**/*.lock
📒 Files selected for processing (4)
.python-versionMakefileREADME.mdpyproject.toml
| kill: | ||
| -pkill -f "uvicorn backend.main:app" 2>/dev/null || true | ||
| -pkill -f "vite" 2>/dev/null || true | ||
| @echo "开发进程已终止。" |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Restrict make kill to processes created by this worktree.
pkill -f "vite" matches every user process with vite in its command line. It can terminate an unrelated Web development server. Track the launched process IDs in a repository-local PID file, or terminate only the recorded process group.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@Makefile` around lines 151 - 154, Update the Makefile kill target to stop
only processes launched by this worktree: reuse a repository-local PID file or
recorded process group created by the startup target, validate the recorded
processes before terminating them, and remove the PID tracking file afterward.
Eliminate broad pkill patterns, including the uvicorn and vite commands.
| [tool.uv.sources] | ||
| # Git 源依赖 | ||
| qwen-tts = { git = "https://github.com/QwenLM/Qwen3-TTS.git" } | ||
| linacodec = { git = "https://github.com/ysharma3501/LinaCodec.git" } | ||
| Zipvoice = { git = "https://github.com/ysharma3501/LuxTTS.git" } |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
test -f uv.lock
uv lock --check
rg -n '^\s*(qwen-tts|linacodec|Zipvoice)\s*=' pyproject.toml
rg -n 'uv (sync|pip install).*torch|--index-url|--locked' MakefileRepository: jamiepine/voicebox
Length of output: 196
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'repo files relevant to dependency configuration:\n'
git ls-files | rg '(^|/)(pyproject\.toml|uv\.lock|Makefile|Pipfile|requirements|setup\.py|setup\.cfg)$|\.toml$' || true
printf '\npyproject Git sources and lockfile presence:\n'
[ -f pyproject.toml ] && rg -n '^\s*(qwen-tts|linacodec|Zipvoice)\s*=|^\[tool\.uv\.sources\]|^\[tool\.uv\]' pyproject.toml || true
[ -f uv.lock ] && printf 'uv.lock exists\n' || printf 'uv.lock missing\n'
printf '\nMakefile GPU wheel and uv sync sections:\n'
[ -f Makefile ] && sed -n '70,115p' Makefile || true
printf '\nSearch for locked sync or torch backend package sources:\n'
rg -n 'uv (sync|pip install)|torch_index|--index-url|--locked|rocm|cu128|download\.pytorch\.org/whl|Qwen3-TTS|LinaCodec|LuxTTS' Makefile pyproject.toml uv.lock 2>/dev/null || trueRepository: jamiepine/voicebox
Length of output: 3244
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
import re
from pathlib import Path
pyproject = Path('pyproject.toml').read_text()
uvlock = Path('uv.lock').read_text()
makefile = Path('Makefile').read_text()
git_sources = {}
for section, content in re.findall(r'\[([^\]]+)\]\n(.*?)(?=\n\[|\Z)', pyproject, re.S):
if section == 'tool.uv.sources':
for line in content.splitlines():
m = re.match(r'\s*([A-Za-z][\w-]?)\s*=\s*\{[^\n\}]*', line)
if m and ('git = ' in line):
git_sources[m.group(1)] = {
'line': line.strip(),
'has_revision': any(tok in line for tok in ['rev =', 'tag =', 'branch =']),
'url': re.search(r'git\s*=\s*"([^"]+)"', line).group(1) if re.search(r'git\s*=\s*"([^"]+)"', line) else None,
}
lock_sources = {}
for name in git_sources:
pattern = f'\\nname = "{name}"\\n'
if pattern in uvlock:
idx = uvlock.index(pattern)
block = uvlock[idx:uvlock.index('\n\n', idx+1) if '\n\n' in uvlock[idx+1:] else len(uvlock)]
lock_sources[name] = {
'has_git_metadata': 'source = { git =' in block or "'git': {'url'" in block or '"git": {"url"' in block,
'locked_git_url': re.search(r'git[= ]+[\'"]([^\'"]+)[\'"]', block) and re.search(r'git[= ]+[\'"]([^\'"]+)[\'"]', block).group(1),
'locked_ref': re.search(r'rev[= ]+[\'"]([^\'"]+)[\'"]', block) or re.search(r"rev[= ]+'([^']+)'", block) or re.search(r"rev[= ]+\"([^\"]+)\"", block),
'locked_git_branch_tag': re.search(r"(branch|tag)[= ]+[\'"]([^\'"]+)[\'"]", block),
}
make = makefile.splitlines()
for i,line in enumerate(make,1):
if 'uv sync' in line or 'uv pip install torch' in line or '--index-url' in line or '--locked' in line:
print(f"Makefile line {i}: {line.strip()}")
print("\nGit source entries:", git_sources)
print("\nLockfile Git metadata:", lock_sources)
PYRepository: jamiepine/voicebox
Length of output: 410
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
import re
from pathlib import Path
pyproject = Path('pyproject.toml').read_text()
uvlock = Path('uv.lock').read_text()
makefile = Path('Makefile').read_text()
git_sources = {}
for section, content in re.findall(r'\[([^\]]+)\]\n(.*?)(?=\n\[|\Z)', pyproject, re.S):
if section == 'tool.uv.sources':
for line in content.splitlines():
m = re.match(r'\s*([A-Za-z][\w-]?)\s*=\s*\{[^\n\}]*', line)
if m and 'git = ' in line:
git_sources[m.group(1)] = {
'line': line.strip(),
'has_revision': any(tok in line for tok in ['rev =', 'tag =', 'branch =']),
'url': re.search(r'git\s*=\s*"([^"]+)"', line).group(1),
}
lock_sources = {}
for name in git_sources:
pattern = '\nname = "' + name + '"\n'
if pattern in uvlock:
idx = uvlock.index(pattern)
block_end = idx + 1
for pos in range(idx + 1, len(uvlock)):
if uvlock[pos] == '\n' and pos < len(uvlock) - 1 and uvlock[pos + 1] == '\n':
block_end = pos
break
block = uvlock[idx:block_end]
lock_sources[name] = {
'has_git_metadata': bool(re.search(r"source\s*=\s*\{\s*\\*\\*git|source\s*=\s*\{\s*git", block)),
'locked_git_url': re.search(r'git[= ]+[\'"]([^\'"]+)[\'"]', block),
'locked_rev': re.search(r"rev[= ]+[\'"]([^\'"]+)[\'"]", block),
'locked_branch_tag': re.search(r"(branch|tag)[= ]+[\'"]([^\'"]+)[\'"]", block),
}
for i, line in enumerate(makefile.splitlines(), 1):
if 'uv sync' in line or 'uv pip install torch' in line or '--index-url' in line or '--locked' in line:
print("Makefile line", i, ":", line.strip())
print("\nGit source entries:")
for name, data in git_sources.items():
print(" ", name, ":", data)
print("\nLockfile Git metadata:")
for name, data in lock_sources.items():
print(" ", name, ":", data)
PYRepository: jamiepine/voicebox
Length of output: 370
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
import re
from pathlib import Path
pyproject = Path('pyproject.toml').read_text()
uvlock = Path('uv.lock').read_text()
makefile = Path('Makefile').read_text()
git_sources = {}
for section, content in re.findall(r'\[([^\]]+)\]\n(.*?)(?=\n\[|\Z)', pyproject, re.S):
if section == 'tool.uv.sources':
for line in content.splitlines():
m = re.match(r'\s*([A-Za-z][\w-]?)\s*=\s*\{[^\n\}]*', line)
if m and 'git = ' in line:
git_sources[m.group(1)] = {
'line': line.strip(),
'has_revision': any(tok in line for tok in ['rev =', 'tag =', 'branch =']),
'url': re.search(r'git\s*=\s*"([^"]+)"', line).group(1),
}
lock_sources = {}
for name in git_sources:
pattern = '\nname = "' + name + '"\n'
if pattern in uvlock:
idx = uvlock.index(pattern)
block_end = idx + 1
for pos in range(idx + 1, len(uvlock)):
if uvlock[pos] == '\n' and pos < len(uvlock) - 1 and uvlock[pos + 1] == '\n':
block_end = pos
break
block = uvlock[idx:block_end]
lock_sources[name] = {
'has_git_metadata': bool(re.search(r'source\s*=\s*\{.*\bgit\b', block, re.S)),
'locked_ref': re.search(r'"\brev\b",\s*"([^"]+)"', block),
'locked_branch_tag': re.search(r'\b(branch|tag)\b",\s*"([^"]+)"', block),
}
for i, line in enumerate(makefile.splitlines(), 1):
if 'uv sync' in line or 'uv pip install torch' in line or '--index-url' in line or '--locked' in line:
print("Makefile line", i, ":", line.strip())
print("\nGit source entries:")
for name, data in git_sources.items():
print(" ", name, ":", data)
print("\nLockfile Git metadata:")
for name, data in lock_sources.items():
print(" ", name, ":", data)
PYRepository: jamiepine/voicebox
Length of output: 543
Pin the Git dependency source and lock it before install.
The Git sources do not declare an immutable rev, tag, or branch, and the lockfile does not contain pinned metadata for qwen-tts, linacodec, or Zipvoice. The dependency installation remains tied to commit history rather than a reproducible uv.lock.
pyproject.toml#L106-L110: Add a tested commit pin to each Git source and adduv.lockwhen the lockfile is missing.
[suggest_improvement]
📍 Affects 2 files
pyproject.toml#L106-L110(this comment)Makefile#L84-L105
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pyproject.toml` around lines 106 - 110, Pin the Git sources for qwen-tts,
linacodec, and Zipvoice in pyproject.toml using tested immutable commit
revisions, then regenerate and commit uv.lock with the corresponding pinned
metadata; update the installation flow in Makefile lines 84-105 only as needed
to install from the lockfile.
| <a href="https://docs.voicebox.sh">文档</a> • | ||
| <a href="#download">下载</a> • | ||
| <a href="#features">功能</a> • | ||
| <a href="#api">API</a> • | ||
| <a href="docs/content/docs/overview/troubleshooting.mdx">Troubleshooting</a> | ||
| <a href="docs/content/docs/overview/troubleshooting.mdx">故障排除</a> |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
更新翻译后失效的导航锚点。
下载 和 功能 标题已翻译，但链接仍使用 #download 和 #features。GitHub 页面无法跳转到对应章节。
建议修改
- <a href="`#download`">下载</a> •
- <a href="`#features`">功能</a> •
+ <a href="`#下载`">下载</a> •
+ <a href="`#功能`">功能</a> •📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <a href="https://docs.voicebox.sh">文档</a> • | |
| <a href="#download">下载</a> • | |
| <a href="#features">功能</a> • | |
| <a href="#api">API</a> • | |
| <a href="docs/content/docs/overview/troubleshooting.mdx">Troubleshooting</a> | |
| <a href="docs/content/docs/overview/troubleshooting.mdx">故障排除</a> | |
| <a href="https://docs.voicebox.sh">文档</a> • | |
| <a href="`#下载`">下载</a> • | |
| <a href="`#功能`">功能</a> • | |
| <a href="`#api`">API</a> • | |
| <a href="docs/content/docs/overview/troubleshooting.mdx">故障排除</a> |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 37 - 41, Update the README navigation links for 下载
and 功能 to use the anchors generated from their translated section headings
instead of `#download` and `#features`. Leave the other navigation links unchanged.
| ### 快速开始 | ||
|
|
||
| ```bash | ||
| git clone https://github.com/jamiepine/voicebox.git | ||
| cd voicebox | ||
|
|
||
| just setup # creates Python venv, installs all deps | ||
| just dev # starts backend + desktop app | ||
| just setup # 创建 Python 虚拟环境，安装所有依赖 | ||
| just dev # 启动后端 + 桌面应用 | ||
| ``` | ||
|
|
||
| Install [just](https://github.com/casey/just): `brew install just` or `cargo install just`. Run `just --list` to see all commands. | ||
| 安装 [just](https://github.com/casey/just)：`brew install just` 或 `cargo install just`。运行 `just --list` 查看所有命令。 | ||
|
|
||
| **Prerequisites:** [Bun](https://bun.sh), [Rust](https://rustup.rs), [Python 3.11+](https://python.org), [Tauri Prerequisites](https://v2.tauri.app/start/prerequisites/), and [Xcode](https://developer.apple.com/xcode/) on macOS. | ||
| **前置条件：** [Bun](https://bun.sh)、[Rust](https://rustup.rs)、[Python 3.11+](https://python.org)、[Tauri 前置条件](https://v2.tauri.app/start/prerequisites/)，macOS 上还需要 [Xcode](https://developer.apple.com/xcode/)。 |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
将快速开始说明与新的 Make/uv/Python 配置保持一致。
Makefile 定义的是 make setup 和 make dev，并通过 uv sync 安装 Python 依赖。当前文档要求用户安装并运行 just，且仍声明 Python 3.11+。这会导致新环境无法按 README 完成安装。
建议修改
-just setup # 创建 Python 虚拟环境，安装所有依赖
-just dev # 启动后端 + 桌面应用
+make setup # 使用 uv 和 Bun 安装依赖
+make dev # 启动后端 + 桌面应用
-安装 [just](https://github.com/casey/just)：`brew install just` 或 `cargo install just`。
-运行 `just --list` 查看所有命令。
+安装 [uv](https://docs.astral.sh/uv/)、Bun、Rust 和 Tauri 前置依赖。
+运行 `make` 查看可用目标。
-**前置条件：** ... [Python 3.11+](https://python.org) ...
+**前置条件：** ... [Python 3.12](https://python.org) ...📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### 快速开始 | |
| ```bash | |
| git clone https://github.com/jamiepine/voicebox.git | |
| cd voicebox | |
| just setup # creates Python venv, installs all deps | |
| just dev # starts backend + desktop app | |
| just setup # 创建 Python 虚拟环境，安装所有依赖 | |
| just dev # 启动后端 + 桌面应用 | |
| ``` | |
| Install [just](https://github.com/casey/just): `brew install just` or `cargo install just`. Run `just --list` to see all commands. | |
| 安装 [just](https://github.com/casey/just)：`brew install just` 或 `cargo install just`。运行 `just --list` 查看所有命令。 | |
| **Prerequisites:** [Bun](https://bun.sh), [Rust](https://rustup.rs), [Python 3.11+](https://python.org), [Tauri Prerequisites](https://v2.tauri.app/start/prerequisites/), and [Xcode](https://developer.apple.com/xcode/) on macOS. | |
| **前置条件：** [Bun](https://bun.sh)、[Rust](https://rustup.rs)、[Python 3.11+](https://python.org)、[Tauri 前置条件](https://v2.tauri.app/start/prerequisites/)，macOS 上还需要 [Xcode](https://developer.apple.com/xcode/)。 | |
| ### 快速开始 | |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 408 - 420, 更新 README 的“快速开始”部分，将 just setup/dev 替换为
Makefile 定义的 make setup/dev，并将依赖安装说明改为通过 uv sync 完成；同步前置条件，移除 just，改为要求安装 uv，并将
Python 版本声明调整为当前配置要求。
1 participant
Summary by CodeRabbit