fix preflight

docs/publishing.md

@@ -53,14 +53,24 @@ python build/run.py release preflight --version 0.5.2
 
 | 步骤 | 检查内容 |
 | --- | --- |
-| `repo-state` | 是 git 仓库、工作树干净、记录 HEAD（`--allow-dirty` 可豁免） |
+| `repo-state` | 是 git 仓库、工作树干净、记录 HEAD（`--allow-dirty` 可豁免，用于提交前预检） |
 | `version-consistency` | `src/orisys/__init__.py::__version__` == pyproject 的 dynamic attr == `SDK/<version>/` 中 wheel 文件名里的版本 |
-| `duplicate-guard` | `SDK/<version>/` 已有产物则拒绝（`--force` 豁免）；`--check-pypi` 时只读查询 PyPI，版本已存在则拒绝 |
+| `duplicate-guard` | 该版本是否**已经发布过**：本地 git tag（`v<version>` / `<version>`，含 sibling `orisys-sdk-release` 仓库）命中即拒绝；`--check-pypi` 时再查 PyPI。`SDK/<version>/` 里已有 wheel 只作信息展示——那是 preflight 的正常输入，不是错误 |
 | `tests` | `pytest -m "not slow and not hardware"`（`--longrun` 时包含 slow） |
 | `bundle-precheck` | 每个 `[[tool.orisys.bundle.items]]` 至少解析出 1 个文件；finger 必需资产存在 |
 | `wheel-inspection` | 逐个 wheel 做静态断言：文件名/版本/METADATA 字段/RECORD 哈希/压缩包路径/体积上限/无 pyc 与缓存/无 `orisys/**/*.py` 源码泄漏/与源码树逐文件字节一致 |
 | `wheel-runtime` | 在一次性 venv 中安装该 wheel，断言内置 configs/sensors 资产可加载，并对真实视频跑 40 帧公开流水线（无需相机、无 GUI） |
 
+正常顺序是**先构建、再 preflight**，不需要额外开关：
+
+```powershell
+python build/run.py wheel-win
+python build/run.py manylinux
+python build/run.py release preflight --all-wheel-pythons --check-pypi
+```
+
+提交前想先看结果（此时工作树通常还是脏的）：加 `--allow-dirty --keep-going`。
+
 产物报告：
 
 - `build/release/reports/<version>/preflight.json` — 机器可读，含每个 wheel 的 sha256，供后续发布步骤复用
@@ -115,7 +125,7 @@ python build/run.py verify --gui-dist --product ory_finger
 1. 用 `release preflight` 拿到 PASS（并保留 `preflight.json`）。
 2. 把 `SDK/<version>/` 同步到 `orisys-sdk-release` 仓库的 `release/<version>/`。
 3. GitHub：打 tag **`v<version>`** 并创建 Release，上传 6 个 wheel 作为附件。
-   - 注意历史 tag 里有一个 typo：`0.50`（与 `v0.5.2` 指向同一 commit）。
+   - 注意历史 tag 里有一个 typo：`0.50`（与 `v0.5.1` 指向同一 commit）。
 4. PyPI：先 TestPyPI 再正式仓库。
 
 ```powershell
@@ -133,7 +143,10 @@ python -m twine upload SDK/0.5.2/*.whl
 | 0.4.3 | — | 有 | 有 |
 | 0.4.4 | 有 | **无** | **无** |
 | 0.5.0 | 有 | **无** | **无** |
-| 0.5.2 | 有 | 有 | 有（tag `v0.5.2` + typo tag `0.50`） |
+| 0.5.1 | 有 | 有 | 有（tag `v0.5.1` + typo tag `0.50`） |
+| 0.5.2 | 有 | **待发布** | **待发布**（`release preflight --check-pypi` 确认 PyPI 尚无 0.5.2） |
+
+> 本表按 2026 年 0.5.2 构建时的实际状态填写。`0.5.1` 这一行曾被一次全局替换误改成 `0.5.2` 并丢失，请勿再用「全局把 0.5.1 替换成新版本号」的方式改本文件——历史事实不应该被改。
 
 ---