release: prepare WaveBench 0.8.28 and distribution gates

.github/workflows/ci.yml

@@ -2,8 +2,12 @@ name: CI
 
 on:
   push:
-    branches: [master, main]
+    branches: [master, main, Dev]
   pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
 
 jobs:
   test:
@@ -96,3 +100,57 @@ jobs:
           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
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          version: "0.12.15"
+      - name: Build sdist and wheel from sdist
+        run: uv build --no-sources --out-dir "${{ runner.temp }}/distributions"
+      - name: Check release identity and notes
+        shell: bash
+        run: |
+          args=()
+          if [[ "$GITHUB_REF_TYPE" == tag ]]; then args=(--tag "$GITHUB_REF_NAME"); fi
+          python scripts/check_release.py --artifacts "${{ runner.temp }}/distributions" "${args[@]}"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: ${{ runner.temp }}/distributions/*
+          if-no-files-found: error
+
+  wheel-smoke:
+    name: Wheel ${{ matrix.os }} Python ${{ matrix.python-version }}
+    needs: build
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12"]
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          version: "0.12.15"
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: ${{ runner.temp }}/distributions
+      - name: Install and exercise wheel outside the checkout
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          python scripts/smoke_wheel.py --artifacts "${{ runner.temp }}/distributions" --version "$version"

.github/workflows/docs.yml

@@ -2,7 +2,7 @@ name: Documentation
 
 on:
   push:
-    branches: [master, main]
+    branches: [master, main, Dev]
     paths:
       - ".agents/skills/wavebench-docs/**"
       - ".github/workflows/docs.yml"
@@ -33,6 +33,10 @@ on:
       - "src/wavebench/**"
       - "wavebench.example.toml"
   workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
 
 jobs:
   build:
@@ -69,3 +73,9 @@ jobs:
 
       - name: Report documentation impact
         run: uv run --no-sync python scripts/docs_impact.py
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: documentation-site
+          path: site/
+          if-no-files-found: error

.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release candidate
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+  docs:
+    uses: ./.github/workflows/docs.yml
+  draft:
+    name: Draft verified release
+    needs: [ci, docs]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: distributions
+      - name: Create draft with verified assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          gh release create "$RELEASE_TAG" distributions/* \
+            --verify-tag --draft --title "WaveBench $RELEASE_TAG" \
+            --notes-file "docs/releases/$RELEASE_TAG.md"

CHANGELOG.md

@@ -1,6 +1,19 @@
 # WaveBench 更新日志
 
-这里记录已经打过 Git tag 的版本。内容以 tag 之前已经合入的代码、测试、发布说明和边界记录为事实源；路线图里的候选功能不算已发布能力。没有独立 tag 的 release notes 草稿只并入对应正式版本，不单列为版本。版本号和时间以仓库 tag 为准，当前开发分支的变化不放在历史版本里。
+版本变化以对应源码和发布说明为依据，正式发行状态以 [GitHub Releases](https://github.com/Scaxlibur/WaveBench/releases) 为准。未发布的设计继续保留在 RFC 中。
+
+## v0.8.28
+
+[完整发布说明](docs/releases/v0.8.28.md)。
+
+- 新增示波器观察、波形期望检查及只读 MCP 建议入口，明确采集副作用与不完整验收状态。
+- 开发环境和受管插件安装采用 uv，保留旧 pip 安装记录的恢复兼容。
+- 统一运行时版本身份和插件版本比较，增加独立 wheel 安装与 tag 发布门禁。
+- 修复 Windows 分析结果原子替换的短暂占用失败。
+
+## v0.8.27 — 2026-09-08
+
+[完整发布说明](https://github.com/Scaxlibur/WaveBench/releases/tag/v0.8.27)。该版本包含信号处理流水线、批量和双通道分析、Source／RF Source 扩展、状态恢复、资源租约与原生 Windows 支持。
 
 ## v0.8.0 — 2026-07-24
 

README.md

@@ -69,18 +69,15 @@ WaveBench 是面向电子设计调试和日常实验的 Python 测量台。它
 
 ## 无硬件快速开始
 
-以下 uv 流程面向尚未发布的 `Dev` 开发线，版本选择见[安装说明](docs/getting-started/installation.md)。安装 [uv](https://docs.astral.sh/uv/getting-started/installation/) 后，在新的工作副本运行以下命令。它们只安装包、列出模板并打印一个示例 plan，不会连接仪器或打开输出。
+正式发行包从 [GitHub Releases](https://github.com/Scaxlibur/WaveBench/releases) 获取，安装与开发线入口见[安装说明](docs/getting-started/installation.md)。在已安装 WaveBench 的环境中运行以下命令，可生成一个示例 plan，不会连接仪器或打开输出。
 
 ```bash
-git clone --branch Dev https://github.com/Scaxlibur/WaveBench.git
-cd WaveBench
-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
+python -m wavebench --version
+python -m wavebench run template --list
+python -m wavebench run template source-scope-sine --output example.toml
 ```
 
-最后一条命令以 `safety_limits=ok / 安全上限=通过` 结束时，表示示例 plan 已通过离线检查。完整的预期结果、Windows 命令和下一步见[无硬件快速开始](docs/getting-started/quickstart.md)。
+按[无硬件快速开始](docs/getting-started/quickstart.md)准备演示配置并执行离线检查。以 `safety_limits=ok / 安全上限=通过` 结束时，表示示例 plan 已通过检查。
 
 ## 支持范围
 

docs/README_EN.md

@@ -6,16 +6,15 @@ 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.
+Install a release wheel with Python 3.11+ and [uv](https://docs.astral.sh/uv/getting-started/installation/). The [installation guide](getting-started/installation.md) separates release installations, fixed-tag source checkouts, and the unreleased `Dev` branch. Run the following with the installed environment's Python:
 
 ```bash
-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
+python -m wavebench --version
+python -m wavebench run template --list
+python -m wavebench run template source-scope-sine --output example.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.
+These commands perform no instrument I/O. Follow the [Chinese Quickstart](getting-started/quickstart.md) to create an offline configuration and check the plan. A successful check prints `safety_limits=ok / 安全上限=通过`.
 
 ## Safety boundary
 

docs/development/contributing.md

@@ -14,4 +14,4 @@ WaveBench 的代码、文档、schema 和测试在同一仓库中维护。提交
 
 新增或修改用户可见行为时，更新唯一 canonical Reference，并用[文档工作流](documentation.md)进行 scoped review。插件专用流程见[插件开发](plugin-development.md)。
 
-尚未发布的示波器观察入口及执行验收合同见[开发线示波器观察](scope-observation.md)。
+示波器观察的实现与回归合同见[示波器观察实现与验收](scope-observation.md)。发布步骤见[发布版本](releasing.md)。

docs/development/plugin-development.md

@@ -48,6 +48,8 @@ Core 内置 DG 回退驱动也提供该接口；内置版本随 Core 发布，
 
 ## 验证
 
+Core `0.8.28` 起，descriptor 的最低／最高 Core 版本与包的 `Requires-Dist` 均按 PEP 440 范围校验。显式安装的开发版可以落在兼容区间内，但 `0.8.28.dev1` 不满足 `>=0.8.28`；`<0.9` 也不接受 `0.9.0rc1`。两个声明须使用一致边界，缺少 Core 安装元数据的 `0+unknown` 不应视为兼容版本。
+
 ```bash
 python -m wavebench plugin package check <plugin-path>
 python -m wavebench plugin install <plugin-path> --dry-run

docs/development/releasing.md

@@ -0,0 +1,38 @@
+# 发布版本
+
+发布以一个确定提交和一组已经验证的发行物为单位。`pyproject.toml` 是唯一可编辑版本源；安装后的版本来自发行包 metadata。保留 Hatchling 构建后端。
+
+## 准备发布提交
+
+1. 选择正式版本，在无动态仪器插件的开发环境中更新 `pyproject.toml`、`uv.lock` 和 editable 安装元数据。
+2. 将发布说明写入 `docs/releases/v<version>.md`，首行为 `# WaveBench v<version> 发布说明`；从 CHANGELOG 链接到它。
+3. 同步安装示例、相关功能状态和固定版本链接。稳定版文档取自发布 tag，开发线使用独立入口。
+4. 运行源码检查、生成 Reference 检查、文档审计及严格构建。PR 和 `Dev` push 的 CI 还会构建发行物，并验证 Linux／Windows × Python 3.11／3.12 的独立 wheel 安装。
+
+本地可在新的输出目录执行与 CI 相同的发行物检查：
+
+```bash
+uv build --no-sources --out-dir /tmp/wavebench-release
+python scripts/check_release.py --artifacts /tmp/wavebench-release --tag v0.8.28
+python scripts/smoke_wheel.py --artifacts /tmp/wavebench-release --version 0.8.28
+```
+
+替换示例版本和输出目录。独立 smoke 会创建临时虚拟环境并解析 wheel 的运行依赖，可能访问软件源；不连接仪器，不复用开发环境依赖。现有离线 wheel/sdist 测试仍用于检查包布局。
+
+## tag 验证与 Release 草稿
+
+在获得发布授权、目标提交检查通过后，创建并推送与项目版本一致的 `v<version>` tag。`Release candidate` 工作流复用 CI 和 Documentation 工作流，对该 tag 的提交重新验证：
+
+- 项目版本、锁文件、wheel/sdist metadata、tag 及发布说明一致。
+- 源码测试、静态检查、独立 wheel smoke 通过。
+- 生成 Reference、文档审计与 MkDocs 严格构建通过。
+
+全部通过后，工作流下载同一次运行的 `distributions` artifact，附加到 GitHub Release 草稿，正文直接取自仓库中的发布说明，不重新构建发行包。站点保存在 `documentation-site` artifact 中；当前流程不部署 GitHub Pages。
+
+维护者检查草稿正文、目标 tag 和附件后，再执行最终发布。工作流失败时不发布，修复后重新验证最终提交；不能借用旧提交的成功结果。已公开 tag 和发行物不覆盖，修复通过新版本交付。
+
+发布后开发线改为下一版本的 `.devN`，重新同步锁文件与安装元数据。稳定使用说明继续指向固定 tag。
+
+## 分支检查
+
+`CI` 覆盖 PR 和 `master`、`main`、`Dev` 的 push。Documentation 在普通分支事件中保留路径筛选；tag 发布工作流直接调用它，不受路径筛选影响。将检查设为分支必需项时，避免选择可能因路径筛选而不运行的工作流。

docs/development/scope-observation.md

@@ -1,17 +1,16 @@
-# 开发线示波器观察
+# 示波器观察实现与验收
 
-> 状态：`Proposed / Future`，开发线已实现、尚未正式发布。
-> 本页面向实现与测试人员，记录开发线的执行合同；不表示已安装的正式版本提供这些入口。
+本页面向 Core 实现与测试人员，记录 `0.8.28` 的执行合同。用户入口见 [CLI Reference](../reference/cli.md)和 [MCP 操作指南](../how-to/serve-mcp.md)。
 
 ## 实现入口与职责
 
 CLI 的 `scope observe` 和 MCP 的 `scope.observe` / `scope.advise` 由
 `services/agent_observe.py`、`services/agent_advise.py`、`ScopeService` 与 `mcp_http.py`
-共同实现。CLI 参数以本开发线的 `cli_parser.py` 和离线 `--help` 为准。
+共同实现。CLI 参数以 `cli_parser.py` 和离线 `--help` 为准。
 Core 表达观察、访问约束、会话和报告语义；型号通道、端接与传输差异由 descriptor 和 driver
 提供，不在观察层维护型号范围表。
 
-MCP 的 `doctor.config` 同属未发布入口，调用 `doctor_records()` 并返回结构化检查记录。
+MCP 的 `doctor.config` 调用 `doctor_records()` 并返回结构化检查记录。
 它不读取波形或执行建议；实际查询合同以 doctor 与 driver 实现为准。
 
 ## 观察与建议
@@ -78,8 +77,5 @@ duty_percent = 50
 以及缺证据建议与同步默认值。测试只使用 fake
 transport 和合成信号，不连接设备；实机 evidence 属于单独授权的插件验证。
 
-发布时依据实际 tag 和实现将正式可用行为转入 CLI Reference 和 MCP How-to，并保留唯一
-事实来源。本页不提前承诺发布版本、插件支持范围或硬件验收结论。
-
 相关合同见[安全模型](../concepts/safety-model.md)、[会话与恢复](../concepts/sessions-and-recovery.md)、
 [插件模型](../concepts/plugin-model.md)和[测试说明](testing.md)。

docs/getting-started/installation.md

@@ -1,27 +1,48 @@
 # 安装 WaveBench
 
-本页用于安装 `Dev` 开发线，并确认 CLI 已可运行。该开发线的 uv 安装与插件管理后端尚未发布；使用已发布版本时，应查阅[对应 tag 的安装说明](https://github.com/Scaxlibur/WaveBench/blob/v0.8.27/docs/getting-started/installation.md)。完成后会得到一个独立虚拟环境和可验证的 `--help` 输出。
+本页对应 WaveBench `0.8.28`。发行物及发布状态以 [GitHub Releases](https://github.com/Scaxlibur/WaveBench/releases) 为准；旧版本应使用对应 tag 下的文档。
 
-## 前置条件
+## 安装发行包
 
-- Python 3.11 或更高版本。
-- PATH 中可用的 [uv](https://docs.astral.sh/uv/getting-started/installation/)。
-- 一个新的 `Dev` 工作副本；已有仪器插件的环境按[管理仪器插件](../how-to/manage-plugins.md)处理。
+需要 Python 3.11 或更高版本，以及 PATH 中可用的 [uv](https://docs.astral.sh/uv/getting-started/installation/)。从对应 Release 下载 wheel，在源码仓库之外创建专用运行环境：
 
-## 安装基础包
+```bash
+uv venv .venv-runtime --python 3.12
+uv pip install --python .venv-runtime /path/to/wavebench-0.8.28-py3-none-any.whl
+```
+
+将 wheel 路径替换为实际下载位置。Bash 使用：
+
+```bash
+.venv-runtime/bin/python -m wavebench --version
+.venv-runtime/bin/python -m wavebench --help
+```
+
+PowerShell 使用：
+
+```powershell
+.venv-runtime\Scripts\python.exe -m wavebench --version
+.venv-runtime\Scripts\python.exe -m wavebench --help
+```
+
+版本应显示 `wavebench 0.8.28`。后续示例中的 `python` 指这个环境的解释器。运行环境不执行源码项目的 `uv sync`；动态插件的检查、升级和恢复见[管理仪器插件](../how-to/manage-plugins.md)。
 
-以下命令适用于 Bash 和 PowerShell：
+## 从固定版本源码安装
+
+需要仓库中的示例计划或修改代码时，使用固定 tag 的新工作副本：
 
 ```bash
-git clone --branch Dev https://github.com/Scaxlibur/WaveBench.git
+git clone --branch v0.8.28 https://github.com/Scaxlibur/WaveBench.git
 cd WaveBench
 uv sync --locked
-uv run --no-sync wavebench --help
+uv run --no-sync wavebench --version
 ```
 
-最后一条命令列出 `run`、`scope`、`source`、`power`、`dmm`、`doctor`、`plugin` 等一级命令时，基础安装完成。
+`uv sync --locked` 按 `uv.lock` 准备 `.venv`，并以 editable 方式安装 Core。`uv run --no-sync` 使用已准备的环境，不在运行命令前调整依赖。tag 在正式发布准备完成后可用。
+
+## 使用开发线
 
-`uv sync --locked` 按 `uv.lock` 准备 `.venv`，并以 editable 方式安装 Core。`uv run --no-sync` 使用已准备的环境，不在运行命令前调整依赖。
+跟进未发布修改时，将克隆命令中的 `--branch v0.8.28` 换成 `--branch Dev`。开发线的行为以当前源码、版本查询和文档为准，不作为已发布版本的功能保证。修改包版本后重新同步环境，更新 editable 安装的元数据。
 
 uv 不读取 `pip.conf` 或 `PIP_INDEX_URL`。使用镜像或私有软件源时，先按 [uv 软件源配置](https://docs.astral.sh/uv/concepts/indexes/)设置索引，再运行安装命令。
 
@@ -36,12 +57,18 @@ uv 不读取 `pip.conf` 或 `PIP_INDEX_URL`。使用镜像或私有软件源时
 | `dev` | 本地测试和静态检查。 |
 | `docs` | 文档站点预览与构建。 |
 
-按实际任务安装，例如：
+发行包安装时，在 wheel 路径后加所需 extras：
+
+```bash
+uv pip install --python .venv-runtime "/path/to/wavebench-0.8.28-py3-none-any.whl[analysis,tui]"
+```
+
+源码开发环境按实际任务同步，例如：
 
 ```bash
 uv sync --locked --extra dev --extra analysis --extra tui
 ```
 
-每次同步应列出所有需要的 extras；默认精确同步会移除未选择的可选组件和锁文件未声明的包。运行环境与开发环境的区别见[管理仪器插件](../how-to/manage-plugins.md)。
+每次同步应列出所有需要的 extras；默认精确同步会移除未选择的可选组件和锁文件未声明的包。已有仪器插件的环境应采用专用运行方式。
 
-可选组件不连接仪器。安装后先继续[无硬件快速开始](quickstart.md)，不要直接执行硬件写入命令。
+安装后继续[无硬件快速开始](quickstart.md)，确认离线命令可用后再配置实验台。