背景与问题
当前依赖生命周期是「pip requirements 文件族 + 双 venv 环境线」：
- 声明侧：
requirements.txt / requirements-dev.txt / requirements-cu124.txt / requirements/locks/* 四处并存，锁由自研脚本 tools/generate_python_locks.py 生成；
- 环境侧：
.venv（core/dev）与 .venv_cu124（本地 CUDA 语音栈）双环境并行，Electron 探测、启动器（run_electron_cu124.bat）、ASR sidecar、llama server 都要维护多候选路径；
- CI 侧：仅 Windows 一条 pip 流（setup-python cache +
pip install -r），macOS 完全没有 CI。
痛点：声明漂移面大、双 venv 收敛成本高、锁生成器是自研维护负担、macOS 回归（如 PyAudio 源码编译）无门禁。
目标
收敛为 pyproject.toml 唯一声明 + uv.lock 唯一锁 + 单一 .venv 逐层 L1→L4，并把 Windows CI 从 pip 流重构为 uv 流、新增 macOS CI。不再存在 .venv_cu124 第二环境：L4 是同一 .venv 上追加 local-cu124 extra 后的状态。
平台支持边界
- L1 core / L2 voice：Windows 与 macOS 通用。
- L3 vad / L4 local-cu124：目前仅支持 Windows + NVIDIA 平台——官方验证、锁文件与安装基线都在 Windows 11 + CUDA 12.4，其中 L4 依赖 NVIDIA CUDA 12.4 构建（
torch==2.5.1+cu124）。
- AMD ROCm 及其他 GPU 平台：无官方支持（不提供锁文件、验证器与安装基线）。
安装合同（Windows / macOS 共用；L3/L4 仅支持 Windows + NVIDIA）
uv venv .venv --python 3.12
uv sync --locked # L1 core
uv sync --locked --extra voice # L2 voice
uv sync --locked --extra voice --extra vad # L3 vad（仅 Windows + NVIDIA）
uv sync --locked --extra voice --extra vad --extra local-cu124 # L4（仅 Windows + NVIDIA）
uv sync 为 exact 同步，升梯必须带齐下层 extras（前缀递增）；- torch/torchaudio 经
[tool.uv.sources] 仅在 Windows + local-cu124 时路由到 PyTorch cu124 index；vad 钉 torch==2.5.1，L3→L4 是同版本 wheel 换源而非版本跳变；
- uv.lock 含 win32 平台分叉（torch
2.5.1 / 2.5.1+cu124 双条目），macOS 分支不含 cu124。
范围摘要
- 删除 requirements 全族与
generate_python_locks.py；uv.lock 入库
- Windows CI 重构为 uv 流 + 新增
single-venv-ladder job（L1→L4 单环境、torch +cu124 断言、负向检查无第二 venv）
- 新增 macOS CI（L1+L2 voice：brew portaudio + PyAudio 源码编译 + verify + ruff + 平台安全契约测试 + electron build）
- 工具迁移：
verify_python_environment 拆门（cpu/ci/voice 跨平台、vad/cu124 Windows-only fail-closed）；audit_cu124_dependencies 声明侧改读 pyproject；verify_clean_python_install.ps1 改 uv
- 测试契约迁移：profile-contract / cu124-audit 改测 pyproject extras、
tool.uv.sources 路由、uv.lock 平台条目
- 运行时与文档收敛：Electron venv 探测
[.venv]；删除 run_electron_cu124.bat；asr/llm 运行时第二 venv 引用清零；README / CONTRIBUTING / release policy / README_EN 命令链 uv 化
验收标准
- C1 声明/锁收敛：requirements 文件族与锁生成器删除，全仓残留仅白名单（CI 负向断言、audit observed 快照名、测试 fixture 字符串、vendored 第三方文档）
- C2 单环境逐层（macOS 实测）：干净 venv L1→L2→L3 通过；
--profile cpu/voice 过、--profile vad fail-closed
- C3 Windows 侧：uv 流 CI + ladder job 全绿（GitHub Windows runner）
- C4 macOS CI 真跑全绿
- C5 测试契约迁移完成且本地全绿
- C6 工具退役/迁移完成
- C7 文档与启动器收敛完成
当前状态
本地（macOS M4）已全绿：干净 venv 逐层 sync+import、uv lock --check、契约测试 26+50、ruff、electron tsc+build、macOS CI 本地等价复刻。C3/C4 待 GitHub runner 真跑确认；实现 PR 见关联。
背景与问题
当前依赖生命周期是「pip requirements 文件族 + 双 venv 环境线」：
requirements.txt/requirements-dev.txt/requirements-cu124.txt/requirements/locks/*四处并存，锁由自研脚本tools/generate_python_locks.py生成；.venv（core/dev）与.venv_cu124（本地 CUDA 语音栈）双环境并行，Electron 探测、启动器（run_electron_cu124.bat）、ASR sidecar、llama server 都要维护多候选路径；pip install -r），macOS 完全没有 CI。痛点：声明漂移面大、双 venv 收敛成本高、锁生成器是自研维护负担、macOS 回归（如 PyAudio 源码编译）无门禁。
目标
收敛为
pyproject.toml唯一声明 +uv.lock唯一锁 + 单一.venv逐层 L1→L4，并把 Windows CI 从 pip 流重构为 uv 流、新增 macOS CI。不再存在.venv_cu124第二环境：L4 是同一.venv上追加local-cu124extra 后的状态。平台支持边界
torch==2.5.1+cu124）。安装合同（Windows / macOS 共用；L3/L4 仅支持 Windows + NVIDIA）
uv sync为 exact 同步，升梯必须带齐下层 extras（前缀递增）；[tool.uv.sources]仅在 Windows +local-cu124时路由到 PyTorch cu124 index；vad钉torch==2.5.1，L3→L4 是同版本 wheel 换源而非版本跳变；2.5.1/2.5.1+cu124双条目），macOS 分支不含 cu124。范围摘要
generate_python_locks.py；uv.lock入库single-venv-ladderjob（L1→L4 单环境、torch +cu124 断言、负向检查无第二 venv）verify_python_environment拆门（cpu/ci/voice 跨平台、vad/cu124 Windows-only fail-closed）；audit_cu124_dependencies声明侧改读 pyproject；verify_clean_python_install.ps1改 uvtool.uv.sources路由、uv.lock 平台条目[.venv]；删除run_electron_cu124.bat；asr/llm 运行时第二 venv 引用清零；README / CONTRIBUTING / release policy / README_EN 命令链 uv 化验收标准
--profile cpu/voice过、--profile vadfail-closed当前状态
本地（macOS M4）已全绿：干净 venv 逐层 sync+import、
uv lock --check、契约测试 26+50、ruff、electron tsc+build、macOS CI 本地等价复刻。C3/C4 待 GitHub runner 真跑确认；实现 PR 见关联。