@ninkch/dsh-infinite-canvas 0.18.3 → 0.18.5

package/docs/artcraft-handoff.md

@@ -1,14 +1,14 @@
-# ArtCraft ↔ 无限画布 对接手册（画布侧需求书）
+# ArtCraft ↔ 无限画布 对接手册（画布侧调用契约）
 
-> 供 dsh-artcraft 侧对照实施/实测。本文只描述**画布侧发起的调用与期望**，
-> 契约基础：`dsh-artcraft/README.md`（已实现并验证其 HTTP 形状）。
-> 画布侧代码：`dsh-infinite_canvas/client.js`（dsh-infinite-canvas v0.16+）中 `craft*` 相关段。
+> 供 dsh-artcraft 侧对照实施/实测。本文只描述**画布侧发起的调用与期望**。
+> **契约基线（BLK-02 修复后，2026-10-19）**：ArtCraft 是纯桥接插件，**没有自己的数据根**；
+> 画布一律传 **`base`（项目绝对目录）+ `path`（相对路径）**，绝不发「无 base 的相对 `rel`」。
+> 历史版本（≤0.17.18）基于 `<artcraft dataRoot>/<项目slug>/` 的约定已废弃，见 §7。
 
 ## 1. 环境配置（artcraft.config.json）
 
 ```jsonc
 {
-  "dataRoot": "C:/craft-workspace",          // 任意可写目录；画布按 <dataRoot>/<项目slug>/ 隔离
   "bins": {
     "photocraft":  "C:/craft/photocraft-...-portable",   // 目录（自动拼 photocraft-cli.exe）或完整 exe 或 PATH 裸名
     "filmcraft":   "C:/craft/filmcraft-...-portable",
@@ -18,29 +18,36 @@
 }
 ```
 
-- 画布对 bins.*.found 的判定完全信任 `GET /artcraft/api/status`；`note` 字段会原文展示给用户（红灯原因）。
-- `dataRoot.path` 会被拼进 FCP7 XML 的 `file://localhost/` 绝对引用——**必须是 FilmCraft 能访问的本机绝对路径**。
+- **没有 `dataRoot` 配置项**（0.3.x 起移除）。产物落在哪，完全由调用方传的 `base`/`cwd` 决定。
+- 画布对 `bins.*.found` 的判定完全信任 `GET /artcraft/api/status`；`note` 字段会原文展示给用户（红灯原因）。
+- `/status` 返回 `plugin / version / platform / config / bins / control / jobs / tools`，**不含 dataRoot**；
+  画布不再读取 `status.dataRoot`（旧代码读它是恒空，导致「数据目录不一致」提醒永不触发）。
 
 ## 2. 画布会发起的 HTTP 调用（逐条）
 
 | # | 调用 | 触发时机 | 画布侧超时 | 期望响应 |
 |---|---|---|---|---|
-| 1 | `GET /api/status` | 设置卡片/各 Craft 入口挂载时（静默探测） | 20s | `dataRoot.path/exists`、`bins.*.found/note` |
-| 2 | `POST /api/fs?action=write&rel=…` | 资产同步 / timeline.xml / srt / grade.json | 180s | `{ok,rel,size}`；**body 为原始 Blob**（视频可达数十 MB） |
-| 3 | `POST /api/job` | PhotoCraft 处理 / FilmCraft 导出 | 30s | `{id,…}` |
-| 4 | `GET /api/job?id=…&tail=…` | 轮询（PhotoCraft 1.5s / FilmCraft 2s） | 20s | `{status,stdout,stderr,outputs:[{rel,exists,size}]}` |
-| 5 | `POST /api/job/cancel` | 用户点取消 | 20s | 任意 |
-| 6 | `GET /api/file?rel=…` | 回收产物（graded 图 / final.mp4） | 180s | 原始字节 + 按扩展名 content-type |
-
-- rel 一律**相对 dataRoot、正斜杠、无前导 /**，形如 `<项目slug>/media/…`。
+| 1 | `GET /api/status` | 设置卡片/各 Craft 入口挂载时（静默探测） | 20s | `bins.*.found/note`、`version` |
+| 2 | `POST /api/fs?action=write&base=<绝对目录>&path=<相对路径>` | 资产同步 / timeline.xml / srt | 180s | `{ok,path,size}`；**body 为原始 Blob**（视频可达数十 MB） |
+| 3 | `POST /api/fs`（JSON `{base,path,text}`） | timeline.xml / subs.srt（文本） | 60s | `{ok,path,size}` |
+| 4 | `GET /api/fs?op=readtext&base=<绝对目录>&path=<相对路径>` | 读回文本 | 20s | `{path,text}` |
+| 5 | `POST /api/job`（含 `cwd` = 项目绝对目录、`outputs` 用相对路径） | PhotoCraft 处理 / FilmCraft 导出 | 30s | `{id,…}` |
+| 6 | `GET /api/job?id=…&tail=…` | 轮询（PhotoCraft 1.5s / FilmCraft 2s） | 20s | `{status,stdout,stderr,outputs:[{rel,exists,size}]}` |
+| 7 | `POST /api/job/cancel` | 用户点取消 | 20s | 任意 |
+| 8 | `GET /api/file?base=<绝对目录>&path=<相对路径>` | 回收产物（graded 图 / final.mp4） | 180s | 原始字节 + 按扩展名 content-type |
+
+- **`base` 必须是绝对路径**，由画布 Host 的 `projectDirGet` RPC 解析：`<画布数据根>/projects/<项目物理文件夹>`；
+  `path` 是相对 `base` 的正斜杠路径，形如 `craft/media/x.png`、`craft/timeline.xml`、`craft/out/final.mp4`。
+- **画布绝不发「只有 `rel`、没有 `base`」的相对路径**：那样会被 ArtCraft 按**插件进程 cwd** 解析，
+  返回 200 却把文件写到 `C:\Users\PC\.dsh\profiles\desktop\`（BLK-02 的现场缺陷）。
 - 画布在 status 不可达/404 时全部 Craft 入口置灰并提示，不会发后续调用。
 
-## 3. 画布发起的确切 CLI 命令行（cwd = dataRoot）
+## 3. 画布发起的确切 CLI 命令行（args 内一律绝对路径，`cwd` = 项目绝对目录）
 
 ### 3.1 PhotoCraft 单图处理（T4，已实现）
 
 ```
-photocraft-cli run <项目slug>/media/<assetId>.<ext> --cmd <命令ID> --params <JSON字符串> --out <项目slug>/out/graded/<assetId>-graded<ext>
+photocraft-cli run <项目绝对目录>\craft\media\<assetId>.<ext> --cmd <命令ID> --params <JSON字符串> --out <项目绝对目录>\craft\out\graded\<assetId>-graded<ext>
 ```
 
 - 已内置命令（下拉可选，用户可自定义任意 cmd）：
@@ -51,7 +58,7 @@ photocraft-cli run <项目slug>/media/<assetId>.<ext> --cmd <命令ID> --params
 ### 3.2 PhotoCraft 批量（配方已确认，UI 未接）
 
 ```
-photocraft-cli batch --actions <项目slug>/craft/grade.json --in <项目slug>/media --out <项目slug>/out/graded
+photocraft-cli batch --actions <项目绝对目录>\craft\grade.json --in <项目绝对目录>\craft\media --out <项目绝对目录>\craft\out\graded
 ```
 
 grade.json：`{ "actions": [ { "cmd": "...", "params": {...} }, … ] }`
@@ -61,38 +68,42 @@ grade.json：`{ "actions": [ { "cmd": "...", "params": {...} }, … ] }`
 画布写入两个文件后发起（args 为 JSON 数组，用户可在确认框编辑）：
 
 ```
-写入 <项目slug>/craft/timeline.xml   （FCP7 XML xmeml v1，单视频轨顺序片段）
-写入 <项目slug>/craft/subs.srt       （按片段顺序的字幕）
-然后：
-filmcraft-cli --project <项目slug>/craft/drama.fcproj --import <项目slug>/craft/timeline.xml --export <项目slug>/out/final.mp4
+写入 <项目绝对目录>\craft\timeline.xml   （FCP7 XML xmeml v1，单视频轨顺序片段）
+写入 <项目绝对目录>\craft\subs.srt       （按片段顺序的字幕）
+然后（cwd = 项目绝对目录，outputs = craft/out/final.mp4）：
+filmcraft-cli --project <项目绝对目录>\craft\drama.fcproj --import <项目绝对目录>\craft\timeline.xml --export <项目绝对目录>\craft\out\final.mp4
 ```
 
+- xmeml 的 `<pathurl>` 用 `file://localhost/<媒体绝对路径>`，媒体绝对路径 = 项目绝对目录 + `craft/media/<文件名>`。
+
 **需实测回填的问题**：
 1. `--project` 指向的 `.fcproj` 不存在时是否自动创建？还是需要先 `init`？
 2. 导入时间线的确切子命令形态（`--import` 一次调用？还是 `import` 子命令 + `export` 子命令两步）？
 3. `--export` 的格式参数（h264 预设名/质量参数/CRF？音频是否自动混入源片段音轨？）
-4. xmeml 的 `<pathurl>file://localhost/…` 引用是否能自动 relink 到 media/ 下文件（含中文/空格/URL 编码）？
+4. xmeml 的 `<pathurl>file://localhost/…` 引用是否能自动 relink 到 craft/media/ 下文件（含中文/空格/URL 编码）？
 5. 字幕：是否支持 `--subs <srt>` 之类参数烧录/挂载？（画布已生成 subs.srt，参数确定后追加）
 
 ### 3.4 EffectCraft（T6 骨架，画布 UI 未接）
 
 ```
-effectcraft-cli render --comp Main --out <项目slug>/out/intro.mp4 <项目slug>/craft/intro.ecproj
+effectcraft-cli render --comp Main --out <项目绝对目录>\craft\out\intro.mp4 <项目绝对目录>\craft\intro.ecproj
 ```
 
 ## 4. 目录与命名约定（画布侧已实现，artcraft 无需感知，但排错时有用）
 
 ```
-<dataRoot>/<项目slug>/
-  media/<assetId><ext>        画布资产（ext 由 mime/name 推断：png/jpg/webp/webm/mp4/mp3/wav）
-  craft/timeline.xml          FCP7 XML（xmeml v1，30fps，单视频轨）
-  craft/subs.srt              成片字幕（与片段顺序一致）
-  craft/grade.json            （批量调色预留）
-  out/graded/<assetId>-graded<ext>
-  out/final.mp4
+<画布数据根>/projects/<项目物理文件夹>/
+  craft/media/<资产名>-<id尾4><ext>   画布资产（ext 由 mime 优先推断）
+  craft/timeline.xml                  FCP7 XML（xmeml v1，30fps，单视频轨）
+  craft/subs.srt                      成片字幕（与片段顺序一致）
+  craft/grade.json                    （批量调色预留）
+  craft/out/graded/<assetId>-graded<ext>
+  craft/out/final.mp4
+  image/ text/ video/ …               Host 落的资产文件（0.18 起按类型分目录）
 ```
 
-- `<项目slug>`：项目名去掉 `\/:*?"<>|` 后保留中文；重名冲突加 `-<项目id尾4>` 后缀；slug 一经分配稳定不变（映射画布侧持久化）。
+- **目录基准是项目 id 对应的物理文件夹**，由 Host 维护（`canvas.meta.json` 的 `folder` 字段）；
+  清单缺条目时回退为项目 id。**不再使用项目名 slug**（slug 只存在浏览器 localStorage，Host 与 ArtCraft 都无法可靠重建）。
 - 同名重复同步 = **覆盖写**（幂等）。
 
 ## 5. 退出码与错误约定（画布轮询依赖）
@@ -103,8 +114,20 @@ effectcraft-cli render --comp Main --out <项目slug>/out/intro.mp4 <项目slug>
 
 ## 6. 联调流程建议
 
-1. `artcraft.config.json` 配好三 bins + dataRoot → `GET /api/status` 三绿灯。
-2. 画布资产页点"同步全部资产到磁盘"→ 检查 `<dataRoot>/<项目>/media/` 出现文件。
-3. 资产卡 → PhotoCraft 处理 → 选"智能锐化" → 开始处理 → 确认 `out/graded/` 产物入库。
-4. 搭一个最小分镜流（2 个视频片段）→ 成片节点 FilmCraft 导出 → 用 `artcraft_cli {bin:"filmcraft",args:["commands"]}`（或本地 `filmcraft-cli commands`）核对 3.3 的五个问题 → 回填确认框默认 args。
+1. `artcraft.config.json` 配好 bins → `GET /api/status` 各灯绿。
+2. 画布资产页点"同步全部资产到磁盘"→ 检查 `<画布数据根>/projects/<项目>/craft/media/` 出现文件
+   （**不是** DSH profile 目录）。
+3. 资产卡 → PhotoCraft 处理 → 选"智能锐化" → 开始处理 → 确认 `craft/out/graded/` 产物入库。
+4. 搭一个最小分镜流（2 个视频片段）→ 成片节点 FilmCraft 导出 → 用 `artcraft_cli {bin:"filmcraft",args:["commands"]}`
+   （或本地 `filmcraft-cli commands`）核对 3.3 的五个问题 → 回填确认框默认 args。
 5. 全绿后把实测参数发回画布侧更新默认模板。
+
+## 7. 历史约定（已废弃，排错时仅作线索）
+
+| 已废弃 | 现状 |
+|---|---|
+| `artcraft.config.json` 的 `dataRoot` | 0.3.x 移除；画布不再读取 |
+| `GET /status` 的 `dataRoot.path/exists` | 不再返回；画布改用自己的 `projectDirGet` |
+| `?action=write&rel=<项目slug>/…`（无 base） | 被按插件进程 cwd 解析 → 200 静默错位（BLK-02）；已全部改为 `base`+`path` |
+| `?op=readtext&rel=…`、`/file?rel=…` | 同上，全部改 `base`+`path` |
+| `<artcraft dataRoot>/<项目slug>/` 目录布局 | 改为 `<画布数据根>/projects/<物理文件夹>/craft/`；历史 slug 目录不迁移、标遗留 |

package/docs/guide.en.md

@@ -28,6 +28,18 @@ Two ways to drive it, best combined:
 
 3. First time: finish the basics in the **Settings** tab (see section 5), then start from the chat.
 
+### 2.1 Keep the canvas beside the chat (right-pane tab)
+
+You don't have to flip between the **Chat** and **Canvas** views: the canvas also opens as a tab in the **Harness right pane**, so you can talk on the left and storyboard on the right at the same time.
+
+1. Open the right pane (titled **开始 / Start**).
+2. Click the **无限画布 / Infinite Canvas** card — the canvas opens as a tab beside the conversation, sharing the same projects, nodes and assets as the full-page panel.
+3. Drag the pane wider, or use the pane's fullscreen button, for more canvas room.
+
+![Infinite Canvas as a right-pane tab](./images/harness-right-pane.png)
+
+> **One live canvas at a time** (shared node graph and generation state). If the full-page panel is also open, opening it in the pane **moves** the canvas there instead of duplicating it — the other side shows a "move the canvas here" button to bring it back.
+
 ---
 
 ## 3. The core: driving the canvas from chat (a full episode)

package/docs/guide.zh-CN.md

@@ -28,6 +28,18 @@
 
 3. 首次使用先到**设置**页签完成基础配置（见第 5 节），回到对话即可开工。
 
+### 2.1 让画布停在对话旁边（右栏页签）
+
+不想在「对话」和「画布」两个视图之间来回切：画布也能作为 **Harness 右侧面板的一个页签**打开，左边对话、右边分镜同屏工作。
+
+1. 打开右侧面板（标题为**开始**）。
+2. 点 **无限画布** 卡片 → 画布作为页签出现在对话右侧，与全屏面板共享同一批项目/节点/资产。
+3. 把右栏拖宽，或用右栏的全屏按钮，可获得更大画布区域。
+
+![无限画布作为右侧面板页签](./images/harness-right-pane.png)
+
+> **同一时刻只有一个画布实例**（共享节点图与生成状态）。若全屏面板也开着，在右栏打开会把画布**移动**过来而不是复制一份，另一侧显示「把画布切换到这里」按钮；点它即可切回去。
+
 ---
 
 ## 3. 核心：用对话驱动画布（以第一集完整制作为例）

package/docs/migration-0.18.md

@@ -10,9 +10,21 @@ upgrading an existing deployment and moving data to a new machine.
 |---|---|
 | Asset metadata in **each browser's IndexedDB** | **`<dataRoot>/canvas.db`** (SQLite, WAL) — one source of truth for every browser |
 | Project documents in `~/.dsh/infinite-canvas/projects/*.json` + a mirror in the data directory | Stored in `canvas.db`; the old files are frozen and no longer written |
-| Media in `<dataRoot>/projects/<project>/<kind>/…` + metadata mirror `assets.json` | New uploads go to `<dataRoot>/objects/<sha2>/<sha256>` (content-addressed, deduplicated); legacy files stay where they are and keep working |
+| Media in `<dataRoot>/projects/<project>/<kind>/…` + metadata mirror `assets.json` | New uploads go to `<dataRoot>/projects/<project>/<kind>/…` and are recorded in `canvas.db`; legacy files stay where they are and keep working |
 | Copying the data directory was not enough to migrate | The data directory **is** the complete data package — copy it, point the data root at it, done |
 
+## A note on `objects/` (versions 0.18.0–0.18.4)
+
+For a few 0.18 releases, newly uploaded media was stored content-addressed under
+`<dataRoot>/objects/<sha2>/<sha256>` instead of the project folder. That **write
+path has since been retired** — current versions never create new objects — but
+**media uploaded during 0.18.0–0.18.4 still lives there and is still served** by
+`GET /api/object`. Keep the `objects/` directory when you copy or back up your data
+root, otherwise those older assets will fail to load.
+
+Deleting an asset still reclaims its object when no other asset references it, so
+the directory does not grow unbounded.
+
 ## Upgrade the production machine
 
 1. **Update the plugin to 0.18.0** (in DSH: check updates on the Infinite Canvas
@@ -37,7 +49,10 @@ upgrading an existing deployment and moving data to a new machine.
    back into `canvas.db`). If you must copy a running directory, copy all
    `canvas.db*` files (`canvas.db`, `canvas.db-wal`, `canvas.db-shm`).
 2. Copy the **entire data directory** to the new machine (e.g. `D:\canvas-data`),
-   including `objects/`.
+   including `objects/` — the historical object store (see the note above) is still
+   needed for media uploaded on 0.18.0–0.18.4. If you started on 0.18.0–0.18.4 and
+   never upgraded in between, your newest assets may be in `objects/`; after the
+   upgrade, keep that folder.
 3. On the new machine, install the plugin (0.18+), open Infinite Canvas →
    Settings → data root → point it at the copied directory. The database mounts
    as-is; if the directory is an old ≤ 0.17 layout (no `canvas.db`), the one-shot
@@ -58,13 +73,15 @@ tunnel behind access control if the content matters.
 Downgrade the plugin to 0.17.x and it reads the legacy stores again. Everything
 that existed before the upgrade is still in its original location (old project
 JSON files, `assets.json`, media files) — 0.18 freezes them rather than deleting.
-Data created **after** upgrading lives only in `canvas.db`/`objects/` and will
-not appear under 0.17.x, so treat rollback as a one-way door for new data.
+Data created **after** upgrading lives only in `canvas.db` (and, for media uploaded
+on 0.18.0–0.18.4, `objects/`) and will not appear under 0.17.x, so treat rollback as
+a one-way door for new data.
 
 ## Backup
 
 With the Harness stopped, backing up the data directory is a plain file copy:
-`canvas.db` (plus `-wal`/`-shm` if present) and `objects/`. To verify integrity
-after restoring, open the canvas and spot-check a few assets; the database can be
-rebuilt from a frozen ≤ 0.17 layout plus browser-side uploads if ever needed
-(`objectsGc` reclaims orphaned objects).
+`canvas.db` (plus `-wal`/`-shm` if present), `projects/`, and — if you ever ran
+0.18.0–0.18.4 — the historical `objects/` directory. To verify integrity after
+restoring, open the canvas and spot-check a few assets; the database can be rebuilt
+from a frozen ≤ 0.17 layout plus browser-side uploads if ever needed. Unreferenced
+objects are reclaimed automatically when the asset that pointed at them is deleted.

package/docs/release.md

@@ -49,21 +49,35 @@ node scripts/smoke-render.mjs   # 渲染冒烟：抓渲染期 ReferenceError（
 
 ## 3. 发布前校验（脚本全绿才算过）
 
+**唯一入口**：
+
 ```
-node scripts/check-pack.mjs     # 打包清单 + 元数据核对（npm pack --dry-run）
-node scripts/smoke-render.mjs   # 渲染冒烟：假 React 走真实组件树
-node scripts/test-update.mjs    # 更新检查功能测试（真实 registry 比对）
-node scripts/test-tools.mjs     # 对话工具 schema 校验（标准 JSON Schema，防方言错误）
-node scripts/test-mentions.mjs  # @引用解析单测（解析/高亮转义/设定集匹配/[图N]绑定/命名）
-node scripts/audit.mjs          # 机械化体检（i18n 键对齐/CSS 类/节点类型覆盖/RPC 与工具一致）
-node scripts/test-host-hardening.mjs # Host 加固回归（读流错误接管/项目合并与墓碑/来源校验等）
-node scripts/test-llm-stream.mjs   # LLM 流式与推理模型重试（思考实时推送/按配置上限重试）
-node scripts/test-sync-bible.mjs   # 同步合并回归（设定集拉回/边墓碑防复活）
-node scripts/test-user-scenarios.mjs # 用户实测场景定向复验（轮询无损/自动连线/设定集读写）
-node scripts/test-dataroot.mjs       # 数据目录回归（项目名文件夹/文档镜像/资产索引/一键导入）
-node scripts/test-image-proxy.mjs    # 图片 API 代理回归（CORS 规避：JSON/二进制/状态码透传/超时）
+node scripts/regress.mjs --strict     # 发版门禁：四态输出，SKIP 也算失败
+node scripts/regress.mjs              # 日常开发：条件用例缺前置记 SKIP，不算失败
+node scripts/regress.mjs --list       # 看当前清单
 ```
 
+清单以 `scripts/regress.mjs` 的 `SUITE` 为**唯一事实源**（与 `RELEASING.md` §标准发版流程第 1 步逐项一致），
+**当前项数与分组以 `node scripts/regress.mjs --list` 实时输出为准——runbook 不写死项数**（门禁新增脚本时这里是必漏之地）。
+
+| 分组 | 脚本 |
+| --- | --- |
+| 静态审计 | `audit.mjs` |
+| 渲染与组件 | `smoke-render.mjs`、`test-drag-alt.mjs`、`test-download-ext.mjs`、`test-craft-base.mjs` |
+| 核心链路（历史事故区） | `test-compose.mjs`、`test-tools.mjs`、`test-mentions.mjs`、`test-llm-stream.mjs`、`test-sync-bible.mjs`、`test-user-scenarios.mjs`、`test-host-hardening.mjs` |
+| 存储与数据目录 | `test-db.mjs`、`test-delete-project.mjs`、`test-dataroot.mjs` |
+| 网络与条件用例 | `test-image-proxy.mjs`、`test-update.mjs`（需网络）、`test-real-project.mjs`、`test-real-project-graph.mjs`（需真实数据根） |
+| 打包 | `check-pack.mjs` |
+
+**为什么要有 regress**：此前最危险的成片链路（`test-compose.mjs`）**不在任何门禁清单里**——历史上
+`bc77bb8e fix(finalcut): 每次合成都崩(ReferenceError: dur is not defined)` 正是只在用户点"合成"时炸、
+静态审计抓不到的典型，而修复它时这条链路连跑都没人跑。
+
+**条件用例纪律**：`test-real-project.mjs` / `test-real-project-graph.mjs` 读真实数据根
+（默认 `D:/data/canvas-data`，可用 `DSH_IC_DATA_ROOT` 覆盖）、`test-update.mjs` 打真实 npm registry。
+缺前置时它们会打印"跳过"并 exit 0 —— 这是**假绿**，所以发版一律 `--strict`（SKIP 判失败），
+且 SKIP 时必须打印"原因 + 缺失的前置"。
+
 `check-pack` 防的三类事故：漏打包（如 locale/icon 没进包）、多打包（`.github`/`scripts` 混入）、元数据漂移（版本/exports/`dsh.bundle.patch`）。
 
 ## 4. 层②：Beta 集成测试（已随令牌时代退场，存档）
@@ -112,9 +126,9 @@ git push origin main dev
 ## 7. 发布日检查清单
 
 - [ ] dev 全部改动已提交并推送
-- [ ] 10 项回归脚本全绿（§3 清单）+ 涉及 UI 的重启实测通过
+- [ ] `node scripts/regress.mjs --strict` 全绿（项数以 `node scripts/regress.mjs --list` 为准，不在此写死；SKIP 算失败）+ 涉及 UI 的重启实测通过
 - [ ] `package.json` version = 目标版本号（自查，勿依赖守卫）
 - [ ] **用户明确批准版本号**
-- [ ] 合并 main 并推送 → 建 GitHub Release `vX.Y.Z`（指向 main）
+- [ ] 合并 main（**`git push origin main` 由维护者本人执行**）→ 建 GitHub Release `vX.Y.Z`（指向 main）
 - [ ] Actions 绿 + `npm view`（官方源）版本正确
 - [ ] 汇报版本号 + "重启 Harness 后生效"