Migrate dependency and plugin management to uv

.agents/skills/wavebench/SKILL.md

@@ -121,12 +121,12 @@ Reference 只从本入口直接链接，保持一层目录；详细命令和型
 按阶段选择预检，不把以下命令作为每个任务的固定清单：
 
 ```bash
-.venv/bin/python -m pip check
+uv pip check --python .venv
 .venv/bin/wavebench run check --plan plans/<plan>.toml --config wavebench.toml
 .venv/bin/wavebench run verify --plan plans/<plan>.toml --config wavebench.toml
 ```
 
-`pip check` 用于依赖变化或环境诊断；`run check` 是离线检查；`run verify` 会连接仪器，只有已授权实时预检时执行。
+`uv pip check` 用于依赖变化或环境诊断；`run check` 是离线检查；`run verify` 会连接仪器，只有已授权实时预检时执行。
 已授权执行的真实计划遵循 `run check → run verify → run plan → run report`，并同时检查步骤状态、质量门、期望指标、产物和最终设备状态。仅检查计划的请求到离线检查结果即完成。TUI 界面开发使用 `tui --fake`。
 
 ## External research

.agents/skills/wavebench/references/development-validation.md

@@ -13,6 +13,11 @@
 
 ## 验证分层
 
+Core 新开发环境使用 `uv sync --locked --extra dev --extra analysis --extra tui`。
+按任务增加 `--extra pdf`、`--extra report3d` 或 `--extra docs`。
+已有仪器插件的环境不执行默认精确同步；优先新建隔离环境，或显式使用 `--inexact` 后核对插件状态。
+准备完成后可用 `uv run --no-sync` 执行命令，避免验证期间变更依赖。
+
 按风险选择最窄的验证集合：
 
 以下命令以 POSIX 虚拟环境路径为例；原生 Windows 将 `.venv/bin/python` 替换为

.agents/skills/wavebench/references/plugins.md

@@ -29,6 +29,10 @@
 
 ## 安装边界
 
+安装、卸载和源码构建要求 PATH 中可用的 uv，目标虚拟环境不需要 pip。
+实际仪器环境与开发环境分开；不对装有受管插件的环境运行默认 `uv sync`，以免移除 Core 锁文件未声明的插件。
+混合开发环境显式使用 `--inexact`，随后检查依赖和受管插件状态。
+
 只安装用户明确授权的可信本地目录或 wheel：
 
 ```bash

.github/workflows/ci.yml

@@ -24,30 +24,33 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          cache: pip
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          version: "0.12.15"
+          enable-cache: true
 
       - name: Install package and test dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install -e ".[dev,analysis,pdf]"
+        run: uv sync --locked --python "${{ matrix.python-version }}" --extra dev --extra analysis --extra pdf
 
       - name: Run Ruff
-        run: python -m ruff check .
+        run: uv run --no-sync python -m ruff check .
 
       - name: Audit documentation
         if: matrix.python-version == '3.11'
-        run: python .agents/skills/wavebench-docs/scripts/audit_docs.py --quiet-warnings
+        run: uv run --no-sync python .agents/skills/wavebench-docs/scripts/audit_docs.py --quiet-warnings
 
       - name: Check generated Reference
         if: matrix.python-version == '3.11'
-        run: python scripts/generate_docs.py --check
+        run: uv run --no-sync python scripts/generate_docs.py --check
 
       - name: Report documentation impact
         if: matrix.python-version == '3.11'
-        run: python scripts/docs_impact.py
+        run: uv run --no-sync python scripts/docs_impact.py
 
       - name: Run unit tests
-        run: python -m pytest -q
+        run: uv run --no-sync python -m pytest -q
 
   test-windows:
     name: Windows Python ${{ matrix.python-version }} tests
@@ -67,25 +70,29 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          cache: pip
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          version: "0.12.15"
+          enable-cache: true
 
       - name: Install package and Windows test dependencies
-        shell: pwsh
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install -e ".[dev,analysis,tui]"
-          python -m pip check
+        run: uv sync --locked --python "${{ matrix.python-version }}" --extra dev --extra analysis --extra tui
+
+      - name: Check dependencies
+        run: uv pip check --python .venv
 
       - name: Run Ruff
-        run: python -m ruff check .
+        run: uv run --no-sync python -m ruff check .
 
       - name: Run unit tests
-        run: python -m pytest -q
+        run: uv run --no-sync python -m pytest -q
 
       - name: Run offline CLI smoke tests
         shell: pwsh
         run: |
-          python -m wavebench --help
-          python -m wavebench run schema | Out-Null
-          python -m wavebench run template --list
-          python -m wavebench lock status TCPIP::192.0.2.10::INSTR
+          uv run --no-sync python -m wavebench --help
+          uv run --no-sync python -m wavebench run schema | Out-Null
+          uv run --no-sync python -m wavebench run template --list
+          uv run --no-sync python -m wavebench lock status TCPIP::192.0.2.10::INSTR

.github/workflows/docs.yml

@@ -12,6 +12,7 @@ on:
       - "mkdocs.yml"
       - "plans/**"
       - "pyproject.toml"
+      - "uv.lock"
       - "scripts/docs_impact.py"
       - "scripts/generate_docs.py"
       - "src/wavebench/**"
@@ -26,6 +27,7 @@ on:
       - "mkdocs.yml"
       - "plans/**"
       - "pyproject.toml"
+      - "uv.lock"
       - "scripts/docs_impact.py"
       - "scripts/generate_docs.py"
       - "src/wavebench/**"
@@ -46,21 +48,24 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: "3.11"
-          cache: pip
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          version: "0.12.15"
+          enable-cache: true
 
       - name: Install documentation dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install -e ".[dev,docs]"
+        run: uv sync --locked --python 3.11 --extra dev --extra docs
 
       - name: Check generated Reference
-        run: python scripts/generate_docs.py --check
+        run: uv run --no-sync python scripts/generate_docs.py --check
 
       - name: Audit documentation
-        run: python .agents/skills/wavebench-docs/scripts/audit_docs.py --quiet-warnings
+        run: uv run --no-sync python .agents/skills/wavebench-docs/scripts/audit_docs.py --quiet-warnings
 
       - name: Build site
-        run: mkdocs build --strict
+        run: uv run --no-sync mkdocs build --strict
 
       - name: Report documentation impact
-        run: python scripts/docs_impact.py
+        run: uv run --no-sync python scripts/docs_impact.py

README.md

@@ -69,16 +69,15 @@ WaveBench 是面向电子设计调试和日常实验的 Python 测量台。它
 
 ## 无硬件快速开始
 
-以下命令只安装包、列出模板并打印一个示例 plan；不会连接仪器或打开输出。
+以下 uv 流程面向尚未发布的 `Dev` 开发线，版本选择见[安装说明](docs/getting-started/installation.md)。安装 [uv](https://docs.astral.sh/uv/getting-started/installation/) 后，在新的工作副本运行以下命令。它们只安装包、列出模板并打印一个示例 plan，不会连接仪器或打开输出。
 
 ```bash
-git clone https://github.com/Scaxlibur/WaveBench.git
+git clone --branch Dev https://github.com/Scaxlibur/WaveBench.git
 cd WaveBench
-python3 -m venv .venv
-.venv/bin/python -m pip install -e .
-.venv/bin/python -m wavebench run template --list
-.venv/bin/python -m wavebench run template source-scope-sine --print
-.venv/bin/python -m wavebench run check --plan plans/closure_sine_1k.toml
+uv sync --locked
+uv run --no-sync wavebench run template --list
+uv run --no-sync wavebench run template source-scope-sine --print
+uv run --no-sync wavebench run check --plan plans/closure_sine_1k.toml
 ```
 
 最后一条命令以 `safety_limits=ok / 安全上限=通过` 结束时，表示示例 plan 已通过离线检查。完整的预期结果、Windows 命令和下一步见[无硬件快速开始](docs/getting-started/quickstart.md)。
@@ -105,6 +104,17 @@ python3 -m venv .venv
 
 ## 文档与贡献
 
+Core 开发环境由 `uv.lock` 固定依赖版本：
+
+```bash
+uv sync --locked --extra dev --extra analysis --extra tui
+uv run --no-sync pytest -q
+uv run --no-sync ruff check .
+```
+
+`pdf`、`report3d` 和 `docs` 可按需用 `--extra` 加入。默认同步会移除未声明的包；
+已安装仪器插件的运行环境应与开发环境分开，详见[管理仪器插件](docs/how-to/manage-plugins.md)。
+
 - [文档首页](docs/index.md)
 - [示例计划及硬件边界](plans/README.md)
 - [管理仪器插件](docs/how-to/manage-plugins.md)
@@ -121,4 +131,4 @@ WaveBench 使用 MIT 许可证。
 
 <img src="https://www.krill-code.com/brand/logo-horizontal.png" alt="Krill" width="150" />
 
-感谢 [Krill AI](https://www.krill-code.com/) 对本项目的赞助。
+感谢 [Krill AI](https://www.krill-code.com/) 对本项目的赞助。

docs/README_EN.md

@@ -6,12 +6,13 @@ The current complete documentation is maintained in Chinese. This page is an Eng
 
 ## Start without instruments
 
+Use a new checkout of the unreleased `Dev` branch, Python 3.11+, and [uv](https://docs.astral.sh/uv/getting-started/installation/) on PATH. The [installation guide](getting-started/installation.md) explains checkout and index configuration and links to released-version instructions.
+
 ```bash
-python3 -m venv .venv
-.venv/bin/python -m pip install -e .
-.venv/bin/python -m wavebench run template --list
-.venv/bin/python -m wavebench run template source-scope-sine --print
-.venv/bin/python -m wavebench run check --plan plans/closure_sine_1k.toml
+uv sync --locked
+uv run --no-sync wavebench run template --list
+uv run --no-sync wavebench run template source-scope-sine --print
+uv run --no-sync wavebench run check --plan plans/closure_sine_1k.toml
 ```
 
 The last command succeeds with `safety_limits=ok / 安全上限=通过`. It performs no instrument I/O. See the [Chinese Quickstart](getting-started/quickstart.md) for expected output, Windows commands, and the next steps.

docs/development/documentation.md

@@ -46,12 +46,14 @@ python scripts/docs_impact.py --base <base-revision> --head HEAD
 
 ## 站点预览与发布
 
+在不含受管仪器插件的 `Dev` 开发环境中运行；uv 与工作副本准备见[安装说明](../getting-started/installation.md)。
+
 ```bash
-python -m pip install -e ".[docs]"
-mkdocs serve
-mkdocs build --strict
+uv sync --locked --extra dev --extra docs
+uv run --no-sync mkdocs serve
+uv run --no-sync mkdocs build --strict
 ```
 
 `mkdocs.yml` 只映射当前的开始使用、教程、How-to、Reference、Concepts、开发和 RFC 入口；archive 与旧入口不在主导航中。GitHub Actions 会在文档或潜在事实源变化时执行严格构建。
 
-当前站点采用 default branch 的 latest 视图。需要稳定版时，建议从发布 tag 或 release branch 构建独立站点版本；在尚无实际发布需求前，不维护历史文档副本。GitHub Pages 发布应在仓库 Pages 策略、域名和权限明确后，由单独的 deploy workflow 处理；本仓库当前只验证构建，不自动发布。
+本地站点反映当前 checkout；`Dev` 中尚未发布的变更应标明开发线状态。稳定版文档从对应发布 tag 构建，不以默认分支或开发分支替代。GitHub Pages 发布应在仓库 Pages 策略、域名和权限明确后，由单独的 deploy workflow 处理；本仓库当前只验证构建，不自动发布。

docs/getting-started/installation.md

@@ -1,46 +1,47 @@
 # 安装 WaveBench
 
-本页用于在本地工作副本中安装 WaveBench，并确认 CLI 已可运行。完成后会得到一个独立虚拟环境和可验证的 `--help` 输出。
+本页用于安装 `Dev` 开发线，并确认 CLI 已可运行。该开发线的 uv 安装与插件管理后端尚未发布；使用已发布版本时，应查阅[对应 tag 的安装说明](https://github.com/Scaxlibur/WaveBench/blob/v0.8.27/docs/getting-started/installation.md)。完成后会得到一个独立虚拟环境和可验证的 `--help` 输出。
 
 ## 前置条件
 
 - Python 3.11 或更高版本。
-- 已检出的 WaveBench 源码。
+- PATH 中可用的 [uv](https://docs.astral.sh/uv/getting-started/installation/)。
+- 一个新的 `Dev` 工作副本；已有仪器插件的环境按[管理仪器插件](../how-to/manage-plugins.md)处理。
 
 ## 安装基础包
 
+以下命令适用于 Bash 和 PowerShell：
+
 ```bash
-python3 -m venv .venv
-.venv/bin/python -m pip install --upgrade pip
-.venv/bin/python -m pip install -e .
-.venv/bin/python -m wavebench --help
+git clone --branch Dev https://github.com/Scaxlibur/WaveBench.git
+cd WaveBench
+uv sync --locked
+uv run --no-sync wavebench --help
 ```
 
-PowerShell：
+最后一条命令列出 `run`、`scope`、`source`、`power`、`dmm`、`doctor`、`plugin` 等一级命令时，基础安装完成。
 
-```powershell
-py -3.11 -m venv .venv
-.\.venv\Scripts\python.exe -m pip install --upgrade pip
-.\.venv\Scripts\python.exe -m pip install -e .
-.\.venv\Scripts\python.exe -m wavebench --help
-```
+`uv sync --locked` 按 `uv.lock` 准备 `.venv`，并以 editable 方式安装 Core。`uv run --no-sync` 使用已准备的环境，不在运行命令前调整依赖。
 
-最后一条命令列出 `run`、`scope`、`source`、`power`、`dmm`、`doctor`、`plugin` 等一级命令时，基础安装完成。
+uv 不读取 `pip.conf` 或 `PIP_INDEX_URL`。使用镜像或私有软件源时，先按 [uv 软件源配置](https://docs.astral.sh/uv/concepts/indexes/)设置索引，再运行安装命令。
 
 ## 可选组件
 
 | Extra | 用途 |
 | --- | --- |
-| `.[tui]` | 实验性终端控制面板。 |
-| `.[analysis]` | 频响分析与校准所需的分析依赖。 |
-| `.[pdf]` | 离线报告的 PDF 输出。 |
-| `.[report3d]` | 报告中的交互式三维图。 |
-| `.[dev]` | 本地测试和静态检查。 |
+| `tui` | 实验性终端控制面板。 |
+| `analysis` | 频响分析与校准所需的分析依赖。 |
+| `pdf` | 离线报告的 PDF 输出。 |
+| `report3d` | 报告中的交互式三维图。 |
+| `dev` | 本地测试和静态检查。 |
+| `docs` | 文档站点预览与构建。 |
 
 按实际任务安装，例如：
 
 ```bash
-.venv/bin/python -m pip install -e ".[tui]"
+uv sync --locked --extra dev --extra analysis --extra tui
 ```
 
+每次同步应列出所有需要的 extras；默认精确同步会移除未选择的可选组件和锁文件未声明的包。运行环境与开发环境的区别见[管理仪器插件](../how-to/manage-plugins.md)。
+
 可选组件不连接仪器。安装后先继续[无硬件快速开始](quickstart.md)，不要直接执行硬件写入命令。

docs/getting-started/quickstart.md

@@ -4,49 +4,43 @@
 
 ## 前置条件
 
-- Python 3.11 或更高版本。
-- 一个新的 WaveBench 工作副本。
+- Python 3.11 或更高版本，以及 [uv](https://docs.astral.sh/uv/getting-started/installation/)。
+- 一个新的 `Dev` 工作副本；该开发线尚未发布，获取方式与已发布版本入口见[安装说明](installation.md)。
 - 不需要 `wavebench.toml`，也不需要连接仪器。
 
 ## 1. 创建虚拟环境并安装
 
-在仓库根目录运行：
+在新的仓库工作副本中运行，Bash 与 PowerShell 使用相同命令：
 
 ```bash
-python3 -m venv .venv
-.venv/bin/python -m pip install -e .
+uv sync --locked
 ```
 
-PowerShell：
-
-```powershell
-py -3.11 -m venv .venv
-.\.venv\Scripts\python.exe -m pip install -e .
-```
-
-安装完成后，后续命令使用同一虚拟环境中的 Python；不依赖 shell 是否已激活虚拟环境。
+依赖版本来自 `uv.lock`，项目以 editable 方式安装到 `.venv`。
+已有仪器插件的环境不要执行默认同步，因为未声明的包会被移除；实际仪器使用采用
+[专用运行环境](../how-to/manage-plugins.md)。
 
 ## 2. 检查命令入口
 
 ```bash
-.venv/bin/python -m wavebench --help
+uv run --no-sync wavebench --help
 ```
 
-输出会列出 `run`、`scope`、`source`、`power`、`dmm`、`doctor`、`plugin` 和 `capability` 等命令域。PowerShell 中将前缀替换为 `.\.venv\Scripts\python.exe`。
+输出会列出 `run`、`scope`、`source`、`power`、`dmm`、`doctor`、`plugin` 和 `capability` 等命令域。`--no-sync` 使用已经准备好的环境，不在执行前更改依赖。
 
 ## 3. 查看并打印一个模板
 
 ```bash
-.venv/bin/python -m wavebench run template --list
-.venv/bin/python -m wavebench run template source-scope-sine --print
+uv run --no-sync wavebench run template --list
+uv run --no-sync wavebench run template source-scope-sine --print
 ```
 
 第一条命令应包含 `source-scope-sine`。第二条命令会把 TOML 打印到标准输出，其中包含实验段和 `[[steps]]`；它不会写文件、加载配置或连接仪器。
 
 ## 4. 离线检查现有示例
 
 ```bash
-.venv/bin/python -m wavebench run check --plan plans/closure_sine_1k.toml
+uv run --no-sync wavebench run check --plan plans/closure_sine_1k.toml
 ```
 
 成功时，输出末尾为 `safety_limits=ok / 安全上限=通过`。`run check` 会解析 plan、检查 schema、离线安全上限和声明的 capability；它不会打开 transport 或访问仪器。
@@ -55,6 +49,6 @@ py -3.11 -m venv .venv
 
 - 想理解模板如何进入真实实验流程，阅读[从模板到报告](../tutorials/from-template-to-report.md)。
 - 已准备连接实验台时，先阅读[配置实验台](configure-bench.md)和[执行一次实验](../how-to/run-an-experiment.md)。
-- 需要查询字段时，运行 `python -m wavebench run schema`，并阅读[run plan Reference](../reference/run-schema.md)。
+- 需要查询字段时，运行 `uv run --no-sync wavebench run schema`，并阅读[run plan Reference](../reference/run-schema.md)。
 
 `run verify` 会对配置中的仪器执行只读身份查询，`run plan` 会执行真实实验；两者不属于本页的无硬件流程。