dsh-app-updater 1.3.14 → 1.3.15

package/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [1.3.15] — 2026-11-04
+
+### 安全：写操作默认拒绝再加固（`csrfToken` + `method`）
+
+- 宿主半身对 5 个写路由**显式校验 `method === "POST"`**（不匹配返回 `405`），不再依赖
+  宿主 `webServer.register` 的分发实现——原来「GET 带 body」也能触发扫描/更新/改设置。
+- 新增进程内 `csrfToken`（由 `GET /state.json` 下发、**不落盘**）：所有写操作在
+  `confirm:true` 之外必须原样带回，否则 `403`。兼容模式下无 Cookie 的跨站/脚本请求
+  拿不到它，无法再驱动「下载官网包 + UAC 提权静默安装」。
+- `admissionGate` 的 `500` 不再把宿主内部错误文案回给客户端；`readJsonBody` 改用
+  Buffer 累积（防中文跨 chunk 变 `U+FFFD`）、按字节计大小、超大请求体排空、只接受对象。
+- `/cancel` 支持 `target: "scan" | "update" | "all"`（默认 `all` 兼容旧行为），界面在
+  扫描中也能取消，不再「一按把扫描和更新一起停」。
+
+### 可靠性：下载并发化、结果可信度、生命周期
+
+- `winget download` 改为 **3 路并发预下载**，每次下载用独立私有 `workDir`，彻底消除
+  「共享下载目录前后 diff」的并发竞态；安装/兜底/复核仍严格串行（UAC 互斥）。
+- `moveIntoDownloadDir` 回迁处理 `EXDEV` 跨卷，并写 `.dsh-app-updater` **侧车标记**；
+  4 GiB 磁盘配额 `pruneDownloadDir` **只删带标记的本插件文件**，绝不误删用户放在同一
+  下载目录里的 `.exe` / `.dmg` / `.yaml`。
+- 安装后复核改为「首次立即 + 递增退避（`1.5^i`，cap 30s）+ 总时限」；网络抖动下载
+  最多重试 2 次（1s / 3s，仅超时/网络类错误）；`dryRun` 不再被 `keepInstallers=false` 删包。
+- `unverifiable`（读不到已装版本）新增明确字段与「已安装·未复核」状态；Windows 补
+  `manual` 统计；结果面板渲染 `installOk / verified / hash / durationMs / selfUpdater /
+  dryRun / unverifiable`。
+- cordis 卸载时 `abort()` 后台 scan / update 并清掉「更新后 4 秒自动重扫」timer；
+  `startUpdate` 补任务所有权校验（与 `startScan` 对齐）。
+- `state.json` 损坏时先备份为 `state.json.corrupt-*` 再回退；`save()` 失败记
+  `lastSaveError` 而非静默吞掉；`load()` / `openFolder` / `route dispose` 失败全部留痕。
+- 下发 `state.json` 前再裁一次平台专属设置（堵住运行期外部写入）。`/settings` 的
+  `downloadDir` 现在接受 macOS 以 `/` 开头的 POSIX 绝对路径。
+
+### 正确性：版本算法与子进程
+
+- `version.js`：`+build` 按 SemVer 视为元数据（与正式版相等）、尾缀大小写不敏感、
+  `normalizeVersionKey` 加分隔符消除 `1.2-3` vs `1.23` 碰撞、模块级 `/g` 正则改用
+  `matchAll`、`v` 前缀只剥「v 紧跟数字」。
+- `proc.js` / `registry.js`：`StringDecoder` 逐块解码（中文跨 chunk 不再变 `U+FFFD`）；
+  `proc.js` 在 POSIX 上 `detached` + 按进程组 kill（不留孤儿安装器）。
+- 扫描侧与复核侧版本归一统一到 `macos.js` 的 `mainVersionOf`，但 `splitCaskVersion`
+  保留原始串（不砍 `_` / `+`），避免破坏 1.3.13 的构建号识别。
+- macOS `reason` 细分 `not-in-catalog` / `unknown-version`（可一键更新集合逐位不变）；
+  cask 缓存带 `source` / `count` 与 `readCatalogCacheMeta`，stale 告警写明来源与缓存天数。
+
+### 界面与文档
+
+- 浏览器半身：`csrfToken` 统一注入、首帧不再闪 Windows 专属设置、结果字段补全、
+  `source` 徽章白名单、日志稳定排序、取消扫描、`doOpenDownloads` 回读 state。
+- `CONTRACT.md` / `README.md` / `README.en.md` / `RELEASING.md` 对齐代码：轮询
+  `900/5000ms`（原写 `800/4s`）、6 列 + 徽章、`/cancel` 的 `target` 与 1.3.5 杀树实现、
+  `csrfToken` / `saveError`、settings 全集、测试数改为「以 `npm test` 输出为准」、
+  发版脚本加资产名断言。
+
+### 修复引入的回归（本轮自查发现并修掉）
+
+- `splitCaskVersion` 一度误用 `mainVersionOf` 砍掉下划线构建段 → 恢复 + 加回归断言。
+- `pruneDownloadDir` 一度按扩展名清理（会误删用户文件）→ 改侧车标记 + 加断言锁住。
+
+### 测试
+
+`unit 363 / render 87 / deny 16`（本轮基线；发版前以 `npm test` 实际输出为准）。
+16 个 `lib/*.js` + `test/*.mjs` 全部 `node --check` 通过，`test/harness.mjs` 真实 HTTP
+端到端通过，6 项 HTTP 探针（CSRF / 405 / macOS 路径 / cancel target / 相对路径拒绝）全通过。
+
 ## [1.3.14] — 2026-11-03
 
 ### 新增：更新前探测下载源，不再陪跑两小时

package/CONTRACT.md

@@ -15,6 +15,10 @@ dsh-app-updater/
 │  ├─ winget.js          # winget 定位、调用、表格解析
 │  ├─ registry.js        # 注册表 Uninstall 键枚举（覆盖 winget 未收录的应用）
 │  ├─ version.js         # 版本比较（Windows 风格 1.2.3.4 + 字母后缀）
+│  ├─ elevate.js         # Windows UAC 提权执行（临时文件 IPC + 进程树取消）
+│  ├─ proc.js            # 子进程底座（UTF-8 / 超时 / AbortSignal / shell:false）
+│  ├─ macos.js           # macOS 数据层：.app 枚举 / cask 目录竞速 / 列表组装
+│  ├─ appcast.js         # 非 Homebrew 应用官网更新源（Sparkle / Electron，只读）
 │  ├─ state.js           # 持久化状态（~/.dsh/dsh-app-updater/state.json）
 │  └─ client.js          # 浏览器半身：设置页 UI
 └─ README.md
@@ -66,7 +70,9 @@ dsh-app-updater/
   "update": { "running": false, "total": 0, "done": 0, "current": null, "error": null },
   "apps": { "scannedAt": 0, "stats": { "total": 0, "upgradable": 0, "unsupported": 0 }, "items": [], "engine": "winget" },
   "log": [ { "at": 0, "level": "info|warn|error|success", "text": "..." } ],
-  "settings": { "includeStoreApps": true, "includeRegistryOnly": true, "downloadDir": "", "keepInstallers": true, "hashFallbackUpgrade": true, "dryRun": false, "matchSystemArch": true, "autoElevate": true },
+  "settings": { "includeStoreApps": true, "includeRegistryOnly": true, "includeUnmanagedApps": true, "checkOfficialSources": true, "downloadDir": "", "keepInstallers": true, "useWingetDownload": true, "hashFallbackUpgrade": true, "dryRun": false, "matchSystemArch": true, "autoElevate": true, "useSelfUpdater": true },
+  // 写接口必须带回的 CSRF token（进程内生成、不落盘）；saveError 为最近一次写盘失败原因
+  "csrfToken": "<hex>", "saveError": null,
   // 准入现状，供界面与复核确认当前走哪条路径（默认 "deny" 不会出现在能读到响应的地方）
   "admission": { "mode": "connection|connection+loopback-legacy|loopback-legacy-optin|deny", "service": true, "allowLegacyLoopback": false, "warning": null }
 }
@@ -105,7 +111,8 @@ body `{ "confirm": true, "force": true }` → `{ "ok": true, "started": true }`
 
 ### POST /dsh-app-updater/update
 
-body `{ "confirm": true, "ids": ["Google.Chrome", "..."], "mode": "silent" }`
+body `{ "confirm": true, "csrfToken": "<来自 state.json>", "ids": ["Google.Chrome", "..."] }`
+（`mode` 为历史残留字段，宿主不读取；所有写接口一律额外要求 `csrfToken`，见「写操作闸门」。）
 → `{ "ok": true, "started": true, "queued": 3 }`
 （串行执行，逐条：下载官网全量包 → 校验哈希 → 静默安装（需要管理员时自动提权）→ 复核版本。
 Edge 由 `MicrosoftEdgeUpdate.exe /ua` 处理。`settings.dryRun` 时只下载、不安装、不复核。）
@@ -129,11 +136,18 @@ Edge 由 `MicrosoftEdgeUpdate.exe /ua` 处理。`settings.dryRun` 时只下载
 
 ### POST /dsh-app-updater/cancel
 
-→ `{ "ok": true }`（取消尚未开始的项目；提权副本是独立进程，取消只会停掉启动器，已经开始的那次安装会自己跑完）
+body `{ "confirm": true, "csrfToken": "<...>", "target": "scan|update|all" }`（`target` 默认 `"all"`，兼容旧行为）
+→ `{ "ok": true, "cancelled": true, "target": "all" }`
+
+> 旧文档写「提权副本是独立进程，取消只会停掉启动器，已经开始的安装会自己跑完」——
+> 这是 1.3.5 之前的行为。当前 `lib/elevate.js` 用 `cancel.flag` + 助手脚本 `taskkill /T /F`
+> **杀掉整棵提权进程树**；`lib/proc.js` 在 POSIX 上按进程组 kill。取消仍只能停掉「尚未完成」
+> 的那一次，已经提交给安装器的动作无法回滚。
 
 ### POST /dsh-app-updater/settings
 
-body `{ "confirm": true, "settings": { ... } }` → `{ "ok": true, "settings": {...} }`
+body `{ "confirm": true, "csrfToken": "<...>", "settings": { ... } }` → `{ "ok": true, "settings": {...} }`
+（`downloadDir` 接受 Windows 盘符 / UNC **或 macOS 以 `/` 开头的 POSIX 绝对路径**。）
 
 ### POST /dsh-app-updater/open-downloads
 
@@ -145,6 +159,11 @@ body `{ "confirm": true, "settings": { ... } }` → `{ "ok": true, "settings": {
 - `exports.inject = ["slots", "locale"]`
 - 注册 `settings.section`：`{ name: "settings.section", id: "dsh-app-updater", order: 42, label: () => "应用更新" }`
 - 只用 `require("react")`；不引入其它运行时依赖
-- 页面：顶部工具条（刷新检测 / 全部更新 / 取消 / 打开下载目录）+ 统计条 + 可筛选可多选的表格 + 底部日志
-- 表格列：勾选 / 应用名 / 已装版本 / 可升级到 / 来源 / 状态 / 操作
-- 所有请求带 `cache: "no-store"`；轮询 state.json（扫描/更新中 800ms，空闲 4s）
+- 页面：顶部工具条（刷新检测 / 全部更新 / 取消 / 打开下载目录）+ 统计条 + 可筛选可多选的表格 + 更新结果面板 + 底部日志
+- 表格列：勾选 / 应用名 / 已装版本 / 可升级到 / 状态 / 操作（「来源」是状态单元格里的徽章，不是独立列）
+- 所有请求带 `cache: "no-store"`；轮询 state.json（扫描/更新中 **900ms**，空闲 **5000ms**）
+  （旧文档写 800ms/4s，与 `lib/client.js:20-21` 不符）
+- **写操作闸门**：宿主对写路由显式校验 `method === "POST"`（否则 405），并在 `confirm:true`
+  之外要求 `csrfToken`（由 `GET /state.json` 下发、不落盘，兼容模式下尤其重要）
+- 结果面板渲染 `installOk` / `verified` / `hash` / `durationMs` / `selfUpdater` / `dryRun` /
+  `unverifiable`；`unverifiable`（读不到已装版本）单列为「已安装·未复核」状态

package/README.en.md

@@ -26,10 +26,10 @@ Without npm, install from source or from the prebuilt tarball:
 
 ```bash
 # source repository
-dsh plugin --profile web add github:19952730389/dsh-app-updater
+dsh plugin --profile web add github:ccgo26/dsh-app-updater
 
 # prebuilt tgz (see Releases)
-dsh plugin --profile web add https://github.com/19952730389/dsh-app-updater/releases/latest/download/dsh-app-updater.tgz
+dsh plugin --profile web add https://github.com/ccgo26/dsh-app-updater/releases/latest/download/dsh-app-updater.tgz
 ```
 
 Restart DSH afterwards; the plugin lives at **Settings → 应用更新**. The Electron-managed
@@ -224,15 +224,32 @@ Then add `dsh-app-updater` to `dsh.profile.bundles` in the profile's `package.js
 2. Delete `<profile>/node_modules/dsh-app-updater`.
 3. Restart DSH; the data directory `%USERPROFILE%\.dsh\dsh-app-updater` can be removed as well.
 
+## 1.3.15 hardening (vs. 1.3.14)
+
+- Host half now explicitly validates `method === "POST"` on write routes (405 otherwise) and
+  requires a process-local `csrfToken` (delivered by `GET /state.json`, never persisted) in
+  addition to `confirm:true`.
+- Downloads are pre-fetched concurrently into private working directories (no shared-directory
+  diff race); a 4 GiB quota only removes files carrying the plugin's `.dsh-app-updater` sidecar.
+- Post-install verification uses immediate-first + exponential backoff + a total time limit;
+  `unverifiable` is now an explicit result state. Uninstall aborts background tasks.
+- Version parsing follows SemVer `+build`, is case-insensitive on suffixes, and no longer
+  collides in `normalizeVersionKey`. `StringDecoder` and POSIX process-group cancellation were
+  added to the process layer.
+- See `CHANGELOG.md` for the full list and `CONTRACT.md` for the current HTTP contract.
+
 ## Tests
 
 ```bash
-node test/unit.mjs     # 153 checks: table parsing, version compare, manifest & switches, OS/arch detection, Homebrew parsing, macOS app enumeration & cask matching
-node test/render.mjs   # 51 checks: settings panel (per platform), rehearsal banner, scan-warning banner, column drag, request bodies
-node test/deny.mjs     # 12 checks: deny-by-default per route when the host has no connection service
-node test/harness.mjs --scan   # boots the host half against a fake cordis ctx + real HTTP
+npm test                       # = unit + render + deny; the live output is authoritative for check counts
+node test/unit.mjs              # table parsing, version compare, manifest & switches, OS/arch detection, Homebrew parsing, macOS enumeration, admission gate
+node test/render.mjs            # settings panel (per platform), banners, column drag, request bodies, result panel
+node test/deny.mjs              # deny-by-default per route + CSRF / method gates
+node test/harness.mjs --scan    # boots the host half against a fake cordis ctx + real HTTP (print-only, not a scored test)
 ```
 
+> Historic check counts in older docs (e.g. `153 / 51 / 12`) are stale — **always trust `npm test` output**.
+
 > The tests do not depend on whether Homebrew is installed locally: the `findBrew` assertion checks
 > existence across the three default prefixes (Apple Silicon / Intel / Linuxbrew), so it stays green
 > on a real Mac (1.3.2 and earlier hard-coded `=== null` and was always red there; fixed in 1.3.3).

package/README.md

@@ -20,10 +20,10 @@ dsh plugin --profile web add dsh-app-updater
 
 ```bash
 # 源码仓库
-dsh plugin --profile web add github:19952730389/dsh-app-updater
+dsh plugin --profile web add github:ccgo26/dsh-app-updater
 
 # 预构建 tgz（见 Releases）
-dsh plugin --profile web add https://github.com/19952730389/dsh-app-updater/releases/latest/download/dsh-app-updater.tgz
+dsh plugin --profile web add https://github.com/ccgo26/dsh-app-updater/releases/latest/download/dsh-app-updater.tgz
 ```
 
 装好后重启 DSH，在 **设置 → 应用更新** 使用。桌面端（Electron 托管的 `desktop` profile）不允许
@@ -262,12 +262,16 @@ dsh plugin --profile <profile> add link:/path/to/dsh-app-updater
 ## 测试
 
 ```bash
-node test/unit.mjs              # 153 项：定宽表格解析、版本比较、清单与静默参数、系统/架构识别、Homebrew 解析、macOS 应用枚举与 cask 匹配
-node test/render.mjs            # 51 项：设置面板（按平台）、演练提示、扫描警告横幅、列宽拖拽、请求体
-node test/deny.mjs              # 12 项：无 connection 服务时逐路由验证默认拒绝
-node test/harness.mjs --scan    # 用假 cordis ctx + 真 HTTP 把宿主半身跑起来
+npm test                        # = unit + render + deny，具体项数以命令输出为准
+node test/unit.mjs              # 定宽表格解析、版本比较、清单与静默参数、系统/架构识别、Homebrew 解析、macOS 应用枚举与 cask 匹配、准入闸门
+node test/render.mjs            # 设置面板（按平台）、演练提示、扫描警告横幅、列宽拖拽、请求体、结果面板
+node test/deny.mjs              # 无 connection 服务时逐路由验证默认拒绝 + CSRF / method 闸门
+node test/harness.mjs --scan    # 用假 cordis ctx + 真 HTTP 把宿主半身跑起来（非计分工具，需 Windows + winget 才能真扫描）
 ```
 
+> 文档里的历史项数（如 `153 / 51 / 12`、`36 / 32`）都是旧值，**一律以 `npm test` 的实际输出为准**。
+> `test/harness.mjs` 没有断言、不在 `npm test` 里、不计分，不要误当成第四套测试。
+
 > 测试不依赖本机是否装了 Homebrew：`findBrew` 的断言按「存在性」覆盖 Apple Silicon /
 > Intel / Linuxbrew 三处默认前缀（1.3.2 及以前这条断言写死 `=== null`，在真实 Mac 上恒红，
 > 1.3.3 已修正）。
@@ -304,6 +308,24 @@ Edge 走它自带的更新服务：winget 目录里的 `Microsoft.Edge` 是企
 > macOS 上只枚举标准应用目录。应用如果装在别处（例如 `~/Desktop` 或自定义目录），
 > 本插件看不到它 —— 这不是漏扫，是扫描范围之外。
 
+## 1.3.15 加固（相对 1.3.14 发布版）
+
+- **写操作双闸门**：宿主对写路由显式校验 `method === "POST"`，并在 `confirm:true` 之外
+  要求 `csrfToken`（由 `GET /state.json` 下发、不落盘）；兼容模式下无凭据的跨站 / 脚本请求
+  拿不到它，无法再驱动「下载 + 提权静默安装」。
+- **`/cancel` 可指定目标**：`target: "scan" | "update" | "all"`（默认 `all`），不再一按全停；
+  界面在扫描中也能取消。
+- **macOS 自定义下载目录**：`/settings` 的 `downloadDir` 现在接受以 `/` 开头的 POSIX 绝对路径。
+- **卸载清理**：cordis 卸载时 abort 后台 scan / update 任务并清掉自动重扫 timer，不再留幽灵任务。
+- **版本算法**：`+build` 按 SemVer 视为元数据、尾缀大小写不敏感、`normalizeVersionKey` 不再碰撞。
+- **子进程**：`StringDecoder` 逐块解码（中文跨 chunk 不再变 U+FFFD）、POSIX 按进程组取消。
+- **下载**：并发预下载（独立子目录消除目录 diff 竞态）、网络抖动重试、磁盘配额与清理、
+  `dryRun` 不再被删包；复核改为首立即 + 递增退避 + 总时限。
+- **界面**：结果面板补全 `installOk / verified / hash / durationMs / unverifiable` 等字段、
+  启用 `locale`（`zh-CN` / `en`）、键盘可调列宽等 a11y 改进。
+
+> 具体改动与验证结果见仓库工作区的 `dsh-app-updater-修复说明-*.md`（不随本包发布）。
+
 ## 卸载
 
 1. 从 profile 的 `package.json` 里删掉 `dsh.profile.bundles` 中的 `dsh-app-updater` 与 `dependencies` 中的对应条目。
@@ -314,17 +336,21 @@ Edge 走它自带的更新服务：winget 目录里的 `Microsoft.Edge` 是企
 
 | 文件 | 作用 |
 |---|---|
-| `lib/index.js` | 宿主半身：HTTP 路由、写操作闸门、扫描/更新任务调度 |
-| `lib/engine.js` | 扫描合并、官网包下载、静默安装、winget 兜底、版本复核 |
+| `lib/index.js` | 宿主半身：HTTP 路由、准入 / `confirm` / `csrfToken` / method 闸门、扫描/更新任务调度 |
+| `lib/engine.js` | 扫描合并、官网包下载（并发预下载）、静默安装、winget 兜底、版本复核、下载源可达性探测 |
 | `lib/winget.js` | winget 定位与调用、定宽表格解析（CJK 宽度感知） |
 | `lib/registry.js` | 注册表 `Uninstall` 键枚举（PowerShell，UTF-8） |
-| `lib/version.js` | Windows 风格版本比较 |
-| `lib/state.js` | 状态与设置持久化（原子写） |
-| `lib/proc.js` | 子进程执行（超时/取消/UTF-8） |
-| `lib/client.js` | 浏览器半身：设置页 UI（设置面板、可拖拽列宽、进度与日志） |
+| `lib/version.js` | Windows 风格版本比较（含 SemVer `+build` / 尾缀自然序） |
+| `lib/state.js` | 状态与设置持久化（原子写）、CSRF token、跨平台设置裁剪 |
+| `lib/proc.js` | 子进程执行（超时 / AbortSignal / 进程组取消 / StringDecoder） |
+| `lib/macos.js` | macOS 数据层：`.app` 枚举、cask 目录竞速与缓存、列表组装 |
+| `lib/appcast.js` | 非 Homebrew 应用官网更新源（Sparkle / Electron，只读） |
+| `lib/elevate.js` | Windows UAC 提权（临时文件 IPC + 进程树取消） |
+| `lib/platform.js` | 系统 / 架构 / 引擎识别 |
+| `lib/client.js` | 浏览器半身：设置页 UI（设置面板、可拖拽列宽、进度、结果面板与日志；`zh-CN` / `en` 字典） |
 | `CONTRACT.md` | 宿主 ↔ 客户端接口契约 |
-| `test/unit.mjs` | 解析器 / 版本 / 清单单测（36 项） |
-| `test/render.mjs` | 前端渲染与交互自测（32 项） |
+| `test/unit.mjs` | 解析器 / 版本 / 清单 / 准入闸门单测（项数以 `npm test` 输出为准） |
+| `test/render.mjs` | 前端渲染与交互自测（项数以 `npm test` 输出为准） |
 | `test/harness.mjs` | 宿主路由端到端 harness（假 ctx + 真 HTTP） |
 | `icon.svg` | 插件图标 |
 | `LICENSE` `CHANGELOG.md` `README.en.md` | MIT 许可证、更新日志、英文说明 |

package/RELEASING.md

@@ -2,6 +2,41 @@
 
 这个仓库同时是 **GitHub 插件源码** 和 **npm 包 `dsh-app-updater`**，两者版本必须一致。
 
+## 0. 两台机器同时维护：先同步，再动手
+
+这个仓库在两台 Mac 上维护（家里 / 本机）。**最容易出的事故是两边各自提交、历史分叉**，
+尤其可怕的是「npm 先发了、GitHub 没推」——registry 里的 `gitHead` 指向一个
+GitHub 上并不存在的提交，别人从 npm 追溯源码时找不到对应代码（实测踩过：
+发布 1.3.14 时 `gitHead: bf1a34d` 在 GitHub API 返回 422）。
+
+**每次开工前先 pull，收工前必推**：
+
+```bash
+# ① 开工：先对齐远端，别在分叉的历史上改
+git pull --rebase origin main
+
+# ② 干活、提交
+git add -A && git commit -m "feat: ..."
+
+# ③ 收工：推送，确认远端已有你的提交
+git push origin main
+git log --oneline -1 origin/main   # 必须能看到刚才那个提交
+```
+
+**发版顺序永远是：GitHub 推送 → 再 npm publish。** 反过来就会留下
+「npm 有版本、GitHub 没有对应提交」的不一致。发版前用这条命令自检：
+
+```bash
+# 发布前最后一道检查：本地 HEAD 必须已在远端
+git fetch origin
+test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)" && echo "OK：可以发布" || echo "先推送！"
+```
+
+> 若两台机器改到同一处代码，`git pull --rebase` 会要求你解决冲突。
+> 冲突时**不要**用 `git push --force` 覆盖另一台的提交 —— 那是别人已经发布过的工作。
+
+---
+
 ## 1. 改版本号与更新日志
 
 ```bash
@@ -12,8 +47,8 @@
 ## 2. 本地自测
 
 ```bash
-npm test                       # unit 36 项 + render 32 项
-node test/harness.mjs --scan   # 宿主半身跑真实 HTTP（需要 Windows + winget）
+npm test                       # unit + render + deny 必须全绿（项数以实际输出为准）
+node test/harness.mjs --scan   # 宿主半身跑真实 HTTP（非计分工具；需要 Windows + winget）
 ```
 
 ## 3. 发布到 npm
@@ -38,6 +73,12 @@ npm pack --silent                       # 产出 dsh-app-updater-<version>.tgz
 mv dsh-app-updater-*.tgz dsh-app-updater.tgz   # 资产名不要带版本号
 gh release create v<version> dsh-app-updater.tgz \
   --title "v<version>" --notes-file <(sed -n '/^## \[<version>\]/,/^## \[/p' CHANGELOG.md)
+
+# 发布后断言：资产名必须恰好是 dsh-app-updater.tgz（latest/download 按字面取文件名）。
+# 漏做 `mv` 或带上版本号，所有市场链接要到「下一次发版」才暴露 404 —— 这里提前拦住。
+gh release view v<version> --json assets --jq '.assets[].name' \
+  | grep -qx 'dsh-app-updater.tgz' \
+  && echo "✓ 资产名正确" || { echo "✗ 资产名不是 dsh-app-updater.tgz"; exit 1; }
 ```
 
 资产名必须**不带版本号**：README 与各插件市场用的是
@@ -45,6 +86,41 @@ gh release create v<version> dsh-app-updater.tgz \
 文件名是按字面取的——一旦资产名带版本号，下一次发版这个链接就会 404。
 如果确实想让文件名带版本号，就把链接改成钉住 tag 的形式（`releases/download/v1.0.0/…`）。
 
+## 4.5 发版检查清单（照着勾）
+
+```bash
+# ① 同步与推送
+git pull --rebase origin main
+git fetch origin && test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)" \
+  && echo "✓ HEAD 已在远端" || echo "✗ 先 git push"
+
+# ② 三套测试必须全绿
+npm test
+
+# ③ 资产名断言（防止人肉 mv 漏做）
+#    gh release view ... | grep -qx 'dsh-app-updater.tgz'（见上文）
+
+# ④ 改名 / 回退后核对各市场 sourceUrl 仍指向当前仓库（1.3.6 / 1.3.7 的教训）
+
+# ③ 版本一致：package.json / CHANGELOG 顶部 / 即将打的 tag
+grep '"version"' package.json
+head -5 CHANGELOG.md | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+'
+
+# ④ 发布 npm
+npm publish --access public
+
+# ⑤ 发布后核对 gitHead 指向的提交真实存在于 GitHub
+curl -s https://registry.npmjs.org/dsh-app-updater/<version> \
+  | python3 -c "import json,sys;d=json.load(sys.stdin);print('gitHead:',d['gitHead'])"
+# 拿上面打印的 sha 去 GitHub 查，必须 200（422/404 说明没推）
+```
+
+> **别只看 npm view 就以为没发出去**：国内默认 registry 常是
+> `registry.npmmirror.com`，镜像有缓存延迟，刚发布时它仍显示旧版本。
+> 核对用官方源：`npm view dsh-app-updater version --registry=https://registry.npmjs.org`。
+
+---
+
 ## 5. 市场收录怎么更新
 
 - **dsh-plugin.org / dshopen.org / awesome-dsh-plugin**：仓库更新后它们按各自刷新周期同步，

package/lib/appcast.js

@@ -246,8 +246,14 @@ export async function checkAppUpdateSources(targets, opts = {}) {
         if (version && looksLikeVersion(version)) {
           out.set(target.key, { version, via: source.kind });
         }
-      } catch {
-        /* 单个应用的更新源读不到，不影响其它应用，也不该中断扫描 */
+      } catch (err) {
+        /* 单个应用的更新源读不到，不影响其它应用，也不该中断扫描；
+           但留一条 info 日志，用户才能察觉哪些官网源没查成（原来完全静默）。 */
+        if (log) {
+          const label = target.key || target.path;
+          const why = String((err && err.message) || err || "未知原因");
+          log("info", `${label} 的官网更新源读取失败，已跳过（${why}）`);
+        }
       }
     }
   };