dsh-app-updater 1.0.0 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,88 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [1.3.0] — 2026-10-31
+
+### 修复
+
+- **机器级安装全部失败的问题**：进程没有管理员令牌时，MSI 直接失败（msiexec 1603，
+  MSI 日志里是 `Error 1925: You do not have sufficient privileges…`），而部分安装器是
+  **静默退出 0 却什么都没装**（实测 Logitech G HUB）。两个现象同源，都是权限。
+- **安装后复核**：退出码 0 不再等于成功。安装完成后用「安装前版本 / 安装后版本 / 目标版本」
+  判断是否真的生效，没生效就如实报失败 —— 原来只看退出码，会把 G HUB 那种
+  「退出码 0、版本没变」的情况误报成「更新完成」。
+- **架构过滤回退**：`winget download/upgrade --architecture x64` 在清单里没有该架构时现在能
+  正确识别（中文报错是「找不到适用的安装程序」，旧正则只匹配了「没有适用」）并退回不限架构
+  重试；`winget upgrade` 兜底同时补上 `--include-unknown`（虎牙直播的已装版本被读成 Unknown，
+  不带它直接「目录里没有适用的更新」）。
+- **Edge**：winget 目录里的 `Microsoft.Edge` 是企业版 MSI，与本机消费版 Edge 的安装技术不匹配，
+  winget 直接拒绝（`0x8A15008E`「安装技术与当前安装的版本不同，请卸载包并安装较新版本」），
+  现在先走 Edge 自带的更新服务 `MicrosoftEdgeUpdate.exe /ua`；若它没生效（实测该机的
+  EdgeUpdate 引擎目录是 `1.3.311.5` 而服务主程序还是 `1.3.275.13`，服务起不来，`/ua` 直接
+  `0x80070002`），自动退回安装 winget 目录里的官网全量包（企业版 MSI，提权执行）——
+  实测这一步能把 Edge 正常装到目标版本，winget 拒绝执行只是因为它的策略。
+- **读不到版本的应用**：虎牙直播的卸载信息里没有版本号，winget 永远显示 `Unknown`。
+  复核阶段不再把它误判为失败，改为「已安装、未复核」写进结果与日志。
+- **「安装包不生效」的软件给出可操作提示**：实测 Logitech G HUB 的更新包早已下载到
+  `%ProgramData%\LGHUB\next.json` 指向的 depots（build 880806 / 2026.7.992920），但安装器
+  `--silent` 与 `winget upgrade` 都会在 3 秒内退出 0 且什么都不装，只有**启动 G HUB 本体**
+  之后 `current.json` 才跳到新版本。插件承诺不启动用户的软件，所以这类情况现在会在失败
+  原因里直接给出「手动打开一次该应用即可完成升级」的提示（`updateHintFor`）。
+- **MSI 日志**：MSI 安装现在带 `/l*v <下载目录>\<包名>.msi.log`，失败时把日志路径写进错误信息
+  （「Error 1925」就是这么被找到的）。
+- **残留清单**：关闭「保留安装包」时，现在连 winget 落盘的 `.yaml` 清单一并删除。
+
+### 新增
+
+- **自动提权安装**（`lib/elevate.js`）：需要管理员的安装类命令交给 `Start-Process -Verb RunAs`
+  的提权副本执行，退出码与输出写进临时文件后读回。新增开关「自动提权安装」（默认开启）。
+  UAC 为「始终通知」时每次安装会弹一次确认；把 `ConsentPromptBehaviorAdmin` 设为 0
+  （管理员静默提权）时完全无感。
+- 说明：提权副本是独立进程，取消更新只会停掉启动器，已经开始的那次安装会自己跑完。
+
+### 安全
+
+- **接入宿主 connection 准入**（插件市场 dshopen.org 对 1.2.0 的复核意见）：所有
+  `/dsh-app-updater/*` 路由先过 `ctx.connection.admit(request)` —— DSH 用来做 Host/Origin
+  信任校验与浏览器会话 / API 认证的那套边界，宿主自己的 `/api` 路由用的就是它。
+  未通过准入的请求直接得到 `401`/`403`；带凭据的请求一律以准入结果为准。
+  只有在宿主没有 `connection` 服务、或者请求不带任何连接凭据且来自回环地址时，才退回旧的
+  「回环」规则，并在响应头标注 `X-DSH-Admission: loopback-legacy`（宿主自己的 Electron
+  载体与本机脚本都不带 Cookie，需要一个不误伤它们的路径）。
+- 因此 README 里「用 curl 直接改设置」的例子现在需要带上 DSH 的会话 Cookie，或在
+  `connection` 不可用的宿主上从回环地址调用。
+
+### 说明
+
+- 读类命令（`winget list` / `upgrade --include-unknown` / `--version`）不提权。
+- `update.results[]` 新增 `installOk`（安装器自身是否报成功）与 `manifest`（落盘的清单位置）。
+
+## [1.2.0] — 2026-10-31
+
+### 新增
+
+- **运行环境识别**（`lib/platform.js`）：识别 Windows / macOS / 其它系统、具体版本与名称
+  （`Windows 11（build 26300）`、`macOS 15（Sequoia）`）、CPU 架构（ARM64 / x64 / Intel / x86），
+  并记录 CPU 型号与线程数。Windows on ARM 上跑 x64 的 Node 时，靠 `PROCESSOR_ARCHITEW6432`
+  仍能还原出真实架构，而不是被骗成 x64。
+- **按架构挑选安装包**：Windows 侧把识别到的架构传给 winget 的 `--architecture`，让「官网全量包」
+  与当前系统/芯片匹配；清单里没有该架构的安装包时自动退回自动匹配，并在日志里说明。
+  macOS 侧由 Homebrew 按本机架构取对应 cask。新增开关「按本机架构安装包」（默认开启）。
+- **macOS 更新引擎（Homebrew cask）**：用 `brew list --cask --versions` 拿已装版本、
+  `brew outdated --json=v2 --cask --greedy` 拿可升级版本，`brew upgrade --cask <token>` 更新；
+  演练模式改用 `brew fetch --cask <token>`，只下载安装包不安装。没有 Homebrew 时明确报告
+  「不可用」，而不是假装能更新。
+- **界面**：状态行与设置面板新增「运行环境」（系统 · 架构 · 引擎）；引擎不可用时红字给出原因；
+  应用来源新增 `homebrew` 徽章。
+- `/health.json` 增加 `version` / `env` / `envSummary` / `engine` / `capabilities`；
+  `state.json` 同步带出这些字段。
+
+### 说明
+
+- macOS 路径无法在开发机（Windows）上真机验证，因此识别与 Homebrew 输出解析均以注入式单测覆盖
+  （`test/unit.mjs` 共 66 项），安装/更新命令按 Homebrew 官方 CLI 行为编写。
+- 扫描/更新接口按平台放行：Windows 与 macOS 通过，其它系统返回 400 并说明原因。
+
 ## [1.0.0] — 2026-10-31
 
 首个可用版本。

package/CONTRACT.md

@@ -10,7 +10,8 @@ dsh-app-updater/
 ├─ cordis.patch.yml      # insert 行：id=dsh-app-updater, name=dsh-app-updater
 ├─ lib/
 │  ├─ index.js           # 宿主半身：cordis 插件，注册 /dsh-app-updater/* 路由
-│  ├─ engine.js          # 扫描 / 下载 / 安装编排
+│  ├─ platform.js        # 运行环境识别：Windows / macOS、版本、CPU 架构、引擎选择
+│  ├─ engine.js          # 扫描 / 下载 / 安装编排（Windows=winget / macOS=Homebrew）
 │  ├─ winget.js          # winget 定位、调用、表格解析
 │  ├─ registry.js        # 注册表 Uninstall 键枚举（覆盖 winget 未收录的应用）
 │  ├─ version.js         # 版本比较（Windows 风格 1.2.3.4 + 字母后缀）
@@ -19,9 +20,31 @@ dsh-app-updater/
 └─ README.md
 ```
 
+## 运行环境与引擎
+
+- `platform.js` 输出 `env`：`{ platform, family: windows|macos|other, osName, osVersion, osBuild, arch: arm64|x64|x86, archLabel, wingetArch, cpuModel, cpuCount }`。
+- 引擎：Windows → `winget`；macOS → `homebrew`；其它 → `none`（扫描/更新接口返回 400）。
+- 架构匹配：`settings.matchSystemArch !== false` 时，Windows 侧把 `env.wingetArch` 传给
+  `winget download/upgrade --architecture`；清单缺该架构时自动退回自动匹配并写日志。
+  macOS 侧由 Homebrew 决定 cask 架构。
+- 提权（`lib/elevate.js`）：`settings.autoElevate !== false` 且当前进程没有管理员令牌时，
+  安装类命令（安装包本体、`winget upgrade` 兜底）交给 `Start-Process -Verb RunAs` 的提权副本
+  执行，退出码与输出写进临时文件后读回；`cancelled` 表示 UAC 被取消（1223）。
+  读类命令（`winget list` / `upgrade --include-unknown` / `--version`）不提权。
+- 复核：安装后必须用「安装前版本 / 安装后版本 / 目标版本」判断是否真的生效，退出码 0 不算成功
+  （机器级安装包在未提权时会静默退出 0 却什么都没装）。`update.results[].installOk` 记录
+  安装器自身是否报成功，`verified` 记录复核时读到的版本。
+- 自带更新服务：Edge 的 winget 目录条目是企业版 MSI，与本机消费版安装技术不匹配
+  （`0x8A15008E`），改走 `MicrosoftEdgeUpdate.exe /ua`，再由复核轮询确认版本就位。
+
 ## 宿主 HTTP 路由
 
-全部 `kind: "exact"`，前缀 `/dsh-app-updater/`。写操作要求 loopback + `confirm: true`。
+全部 `kind: "exact"`，前缀 `/dsh-app-updater/`。每个请求先过 **connection 准入**：
+`ctx.connection.admit(req)`（DSH 的 Host/Origin 信任校验 + 浏览器会话 / API 认证，
+宿主自己的 `/api` 路由用的同一套），被拒即返回 `401`（未认证）/ `403`（不可信来源）；
+写操作再要求 `confirm: true`。
+宿主没有 `connection` 服务、或请求不带任何连接凭据且来自回环地址时，退回旧的「回环」检查，
+并在响应头标注 `X-DSH-Admission: loopback-legacy`（`lib/index.js` 的 `admissionGate`）。
 
 ### GET /dsh-app-updater/state.json
 
@@ -29,13 +52,17 @@ dsh-app-updater/
 {
   "ok": true,
   "platform": "win32",
+  "env": { "platform": "win32", "family": "windows", "osName": "Windows 11", "osVersion": "10.0.26300", "osBuild": "26300", "arch": "x64", "archLabel": "x64（AMD64）", "wingetArch": "x64", "cpuModel": "13th Gen Intel(R) Core(TM) i7-13700K", "cpuCount": 24 },
+  "envSummary": "Windows 11（build 26300） · x64（AMD64）",
+  "engine": { "id": "winget", "available": true, "version": "1.29.380" },
+  "capabilities": { "scan": true, "update": true, "checkVersions": true, "storeAppsIncluded": true, "note": "" },
   "winget": { "available": true, "version": "v1.29.380", "path": "C:\\...\\winget.exe" },
   "phase": "idle",                 // idle | scanning | updating
   "scan": { "running": false, "startedAt": 0, "finishedAt": 0, "error": null },
   "update": { "running": false, "total": 0, "done": 0, "current": null, "error": null },
-  "apps": { "scannedAt": 0, "stats": { "total": 0, "upgradable": 0, "unsupported": 0 }, "items": [] },
+  "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 }
+  "settings": { "includeStoreApps": true, "includeRegistryOnly": true, "downloadDir": "", "keepInstallers": true, "hashFallbackUpgrade": true, "dryRun": false, "matchSystemArch": true, "autoElevate": true }
 }
 ```
 
@@ -43,17 +70,17 @@ dsh-app-updater/
 
 ```jsonc
 {
-  "id": "Google.Chrome",            // winget id；纯注册表项为 "reg:<GUID 或 key 尾段>"
+  "id": "Google.Chrome",            // winget id；注册表项 "reg:<key>"；macOS "brew:<cask token>"
   "name": "Google Chrome",
   "version": "155.0.8059.85",       // 已安装版本，未知时 ""
   "available": "156.0.8078.48",     // 可升级到的版本，无更新时 ""
   "publisher": "Google LLC",
-  "source": "winget",               // winget | msstore | registry
+  "source": "winget",               // winget | msstore | registry | homebrew
   "installLocation": "C:\\Program Files\\Google\\Chrome\\Application",
   "hasUpdate": true,
   "updateSupported": true,          // 本插件能否驱动更新
   "reason": null,                   // null | "not-in-catalog" | "unknown-version" | "pinned" | "store-managed" | "system-component"
-  "kind": "exe"                     // exe | msi | msix | inno | null（未知）
+  "kind": "exe"                     // exe | msi | msix | inno | cask | null（未知）
 }
 ```
 
@@ -68,11 +95,30 @@ body `{ "confirm": true, "force": true }` → `{ "ok": true, "started": true }`
 ### POST /dsh-app-updater/update
 
 body `{ "confirm": true, "ids": ["Google.Chrome", "..."], "mode": "silent" }`
-→ `{ "ok": true, "started": true, "queued": 3 }`（串行执行，逐条下载官网全量包 → 校验 → 静默安装）
+→ `{ "ok": true, "started": true, "queued": 3 }`
+（串行执行，逐条：下载官网全量包 → 校验哈希 → 静默安装（需要管理员时自动提权）→ 复核版本。
+Edge 由 `MicrosoftEdgeUpdate.exe /ua` 处理。`settings.dryRun` 时只下载、不安装、不复核。）
+
+`update.results[]`（每条一次更新）：
+
+```jsonc
+{
+  "id": "Microsoft.Edge",
+  "ok": false,              // 最终结论：复核不通过就是 false，哪怕安装器报成功
+  "installOk": true,        // 安装器自身是否报成功（退出码 0 / winget 成功）
+  "error": "安装报告成功，但没有生效：版本没有变化（仍为 156.0.4314.50，目标 156.0.4314.58）",
+  "installer": "C:\\...\\Microsoft Edge_156.0.4314.58_Machine_X64_msi_en-US.msi",
+  "manifest": "C:\\...\\Microsoft Edge_156.0.4314.58_Machine_X64_msi_en-US.yaml",
+  "verified": "156.0.4314.50",   // 复核时读到的已装版本
+  "selfUpdater": "edgeupdate",  // 走自带更新服务时存在
+  "note": "已交给 Microsoft Edge 更新服务，等待版本就位",
+  "durationMs": 33288
+}
+```
 
 ### POST /dsh-app-updater/cancel
 
-→ `{ "ok": true }`（取消尚未开始的项目；正在安装的进程会收到终止请求）
+→ `{ "ok": true }`（取消尚未开始的项目；提权副本是独立进程，取消只会停掉启动器，已经开始的那次安装会自己跑完）
 
 ### POST /dsh-app-updater/settings
 

package/README.en.md

@@ -1,28 +1,34 @@
 # dsh-app-updater — App Updater for DeepSeek Harness
 
 **English** | [简体中文](README.md)
-![version](https://img.shields.io/badge/version-1.0.0-4b6fff?style=flat-square)
+[![npm](https://img.shields.io/npm/v/dsh-app-updater?style=flat-square&label=npm&color=0891b2&logo=npm)](https://www.npmjs.com/package/dsh-app-updater)
 ![license](https://img.shields.io/badge/license-MIT-2f6f4f?style=flat-square)
 ![platform](https://img.shields.io/badge/platform-Windows-7da1de?style=flat-square)
 ![dsh-plugin](https://img.shields.io/badge/DSH-plugin-263146?style=flat-square)
 
 
-Detect every installed Windows application that has a newer version, then update them
+Detect every installed application that has a newer version, then update them
 with one click — downloading the **full installer from each vendor's own website** and
 installing it silently. **The detected applications are never launched.**
+Windows (winget) and macOS (Homebrew), architecture-aware: ARM64 and x64/Intel installers are
+chosen to match the machine.
 
 Where to find it: DeepSeek Harness → Settings → **应用更新 (App Updater)**
 
 ## Install
 
 ```bash
-# straight from the source repository
-dsh plugin --profile web add github:19952730389/dsh-app-updater
+# npm package (recommended; also one-click installable from the plugin center)
+dsh plugin --profile web add dsh-app-updater
 ```
 
-Prebuilt `.tgz` (see [Releases](https://github.com/19952730389/dsh-app-updater/releases)):
+Without npm, install from source or from the prebuilt tarball:
 
 ```bash
+# source repository
+dsh plugin --profile web add github:19952730389/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
 ```
 
@@ -88,6 +94,8 @@ State file: `%USERPROFILE%\.dsh\dsh-app-updater\state.json`
 | `keepInstallers` | `true` | Keep the installer after a successful update. |
 | `hashFallbackUpgrade` | `true` | Fall back to `winget upgrade` when the download fails. |
 | `dryRun` | `false` | **Rehearsal mode**: download the vendor's full installer but never install it. |
+| `matchSystemArch` | `true` | Match the installer to the detected system and CPU architecture (Windows passes `--architecture`; macOS is resolved by Homebrew). |
+| `autoElevate` | `true` | **Automatic elevation**: install commands that need administrator rights run in an elevated copy (UAC prompts once per install, when UAC prompts at all). |
 
 Everything above is editable from the plugin's own settings panel inside the settings page.
 The panel also accepts API calls:
@@ -106,25 +114,55 @@ curl -X POST -H "Content-Type: application/json" \
   `settings` / `open-downloads` accept only requests from loopback with `confirm:true`.
 - **No guessed silent switches**: the publisher's declared `Silent` switches are preferred;
   generic defaults are used only when a manifest is unavailable.
-- **No silent elevation**: installers that need administrator rights show the normal UAC prompt.
-- **Version is verified after installing** and recorded in the log.
+- **Elevation only for installs, and on demand**: install commands that need administrator rights
+  (MSI packages, installers writing into `Program Files`, the `winget upgrade` fallback) run in an
+  elevated copy through `Start-Process -Verb RunAs`. With UAC set to "always notify" you get one
+  prompt per install; with `ConsentPromptBehaviorAdmin = 0` it is completely silent. Reads
+  (`winget list` / `upgrade --include-unknown` / `--version`) never elevate.
+- **A zero exit code is not success**: after installing, the plugin compares the installed version
+  against the target version and reports a failure when nothing actually changed — machine-scope
+  installers silently exit 0 without installing anything when they lack administrator rights
+  (Logitech G HUB used to be reported as "updated" that way).
 - **System components** (`.NET`, VC++ runtimes, …) are listed but not updated by default.
 - **Only its own directory is written**: state and logs live in `~/.dsh/dsh-app-updater/`.
 
 ## Requirements
 
-- **Windows** with `winget.exe` (Microsoft App Installer). Without winget the plugin can still
+- **Windows**: `winget.exe` (Microsoft App Installer). Without winget the plugin can still
   list registry apps, but cannot tell whether they are up to date.
+- **macOS**: `brew` ([Homebrew](https://brew.sh)). Without Homebrew the plugin reports the engine
+  as unavailable instead of pretending it can update anything.
 - No third-party npm dependencies: the host half uses Node built-ins only, the browser half
   only the host-provided `react`.
 
+## Supported systems and architectures
+
+The plugin detects its own environment at startup and picks the installer that matches it:
+
+| System | Architecture | Engine | Notes |
+|---|---|---|---|
+| Windows 10 / 11 | x64 / ARM64 / x86 | **winget** | the detected architecture is passed as `winget --architecture`; if the manifest has no installer for it, the plugin falls back to automatic matching and says so in the log |
+| macOS 11+ | Apple Silicon / Intel | **Homebrew casks** | Homebrew itself resolves the right cask for the machine; without Homebrew the engine is reported unavailable |
+| anything else | — | none | the scan/update routes answer 400 with the reason |
+
+The result is shown in the status line and in the settings panel's “运行环境 / Environment” row, e.g.
+`Windows 11（build 26300） · x64（AMD64） · winget 1.29.380` or
+`macOS 15（Sequoia） · Apple Silicon（ARM64） · Homebrew 4.5.0`.
+
+The “按本机架构安装包 / match system architecture” switch (on by default) can be turned off to hand
+the choice back to winget; Homebrew always resolves for the local architecture.
+
+> The macOS/Homebrew path follows Homebrew's documented CLI behaviour and its detection and parsing
+> logic are covered by unit tests, but it has not been verified on a real Mac — this plugin is
+> developed on Windows. Please open an issue if something misbehaves there.
+
 ## HTTP API (host half)
 
 | Method | Path | Purpose |
 |---|---|---|
 | GET | `/dsh-app-updater/state.json` | Status, inventory, log, settings |
 | GET | `/dsh-app-updater/apps.json` | Inventory and statistics only |
-| GET | `/dsh-app-updater/health.json` | Self-check (route count, data directory) |
+| GET | `/dsh-app-updater/health.json` | Self-check: version, environment, engine, capabilities, route count, data directory |
 | POST | `/dsh-app-updater/scan` | `{confirm:true, force:true}` start scanning |
 | POST | `/dsh-app-updater/update` | `{confirm:true, ids:[...]}` start the update queue |
 | POST | `/dsh-app-updater/cancel` | `{confirm:true}` cancel items not yet started |
@@ -153,7 +191,7 @@ Then add `dsh-app-updater` to `dsh.profile.bundles` in the profile's `package.js
 ## Tests
 
 ```bash
-node test/unit.mjs     # 36 checks: table parsing, version compare, manifest & switch parsing
+node test/unit.mjs     # 66 checks: table parsing, version compare, manifest & switches, OS/arch detection, Homebrew parsing
 node test/render.mjs   # 32 checks: settings panel, rehearsal banner, column drag, request bodies
 node test/harness.mjs --scan   # boots the host half against a fake cordis ctx + real HTTP
 ```

package/README.md

@@ -1,27 +1,35 @@
 # dsh-app-updater — 应用更新（DSH 插件）
 
-检测本机**所有已安装的 Windows 应用**是否有新版本，并从各自**官网下载完整安装包**一键静默更新。
+检测本机**所有已安装应用**是否有新版本，并从各自**官网下载完整安装包**一键静默更新。
 检测过程**不需要打开被检测的软件**。
+自动识别 **Windows / macOS** 与 **ARM64 / x64（Intel）** 架构，按当前系统与芯片挑选对应的安装包。
 
 入口：DeepSeek Harness → 设置 → **应用更新**
 
 ## 安装
 
 ```bash
-# 从源码仓库安装（复制即可）
-dsh plugin --profile web add github:19952730389/dsh-app-updater
+# npm 包（推荐，插件中心同样可一键安装）
+dsh plugin --profile web add dsh-app-updater
 ```
 
-发行 `.tgz` 见 [Releases](https://github.com/19952730389/dsh-app-updater/releases)：
+> 刚发布的新版本可能被 pnpm 的 `minimumReleaseAge` 策略暂缓一段时间；想立刻装到指定版本就显式写版本号：
+> `dsh plugin --profile web add dsh-app-updater@1.2.0`（细节见 [RELEASING.md](RELEASING.md)）。
+
+不想走 npm，也可以用源码或发行包：
 
 ```bash
+# 源码仓库
+dsh plugin --profile web add github:19952730389/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，在 **设置 → 应用更新** 使用。桌面端（Electron 托管的 `desktop` profile）不允许
 `dsh plugin` 直接改写，需在 profile 的 `node_modules` 下建 junction 并手动补 `bundles`。
 
-![version](https://img.shields.io/badge/version-1.0.0-4b6fff?style=flat-square)
+[![npm](https://img.shields.io/npm/v/dsh-app-updater?style=flat-square&label=npm&color=0891b2&logo=npm)](https://www.npmjs.com/package/dsh-app-updater)
 ![license](https://img.shields.io/badge/license-MIT-2f6f4f?style=flat-square)
 ![platform](https://img.shields.io/badge/platform-Windows-7da1de?style=flat-square)
 ![dsh-plugin](https://img.shields.io/badge/DSH-plugin-263146?style=flat-square)
@@ -91,6 +99,8 @@ dsh plugin --profile web add https://github.com/19952730389/dsh-app-updater/rele
 | `keepInstallers` | `true` | 更新后保留安装包；`false` 则在安装完成后删掉该应用刚下载的包。 |
 | `hashFallbackUpgrade` | `true` | 下载失败时退回 `winget upgrade` 兜底。 |
 | `dryRun` | `false` | **演练模式**：只下载官网全量安装包、不执行安装。用来先看会装什么。 |
+| `matchSystemArch` | `true` | 按识别到的系统与芯片架构挑选安装包（Windows 传 `--architecture`；macOS 由 Homebrew 决定）。 |
+| `autoElevate` | `true` | **自动提权安装**：需要管理员的安装包（MSI、写入 `Program Files`）改由管理员上下文执行；UAC 开启时每次安装会弹一次确认。 |
 
 用 API 改设置（等价于设置面板，适合脚本化）：
 
@@ -107,10 +117,17 @@ curl -X POST -H "Content-Type: application/json" \
 
 ## 安全边界
 
-- **写操作全部要求本机来源 + 显式确认**：`scan` / `update` / `cancel` / `settings` / `open-downloads` 只接受 loopback 请求且必须带 `confirm:true`。
+- **接入宿主 connection 准入**：每个请求先过 `ctx.connection.admit(request)` —— DSH 用来做
+  Host/Origin 信任校验与浏览器会话 / API 认证的那套边界（宿主自己的 `/api` 路由用的就是它），
+  未通过的请求直接得到 `401`/`403`。宿主没有 `connection` 服务、或请求不带任何连接凭据且来自
+  回环地址时，退回旧的「回环」规则，并在响应头标注 `X-DSH-Admission: loopback-legacy`。
+- **写操作还要显式确认**：`scan` / `update` / `cancel` / `settings` / `open-downloads` 必须带 `confirm:true`。
 - **不猜测静默参数**：优先用发布方在清单里声明的 `Silent` 参数；清单缺失时才按安装包类型用保守的默认开关。
-- **不静默提权**：需要管理员权限的安装包会正常弹出 UAC，由你决定是否放行。
-- **安装后复核版本**：更新完会重新查询一次版本并记录，日志里能看到「更新完成，当前版本 X」。
+- **需要管理员时自动提权**：机器级安装包（MSI、写入 `Program Files`）交给
+  `Start-Process -Verb RunAs` 的提权副本执行（可在设置里关掉「自动提权安装」）；
+  UAC 为「始终通知」时每次安装会弹一次确认。
+- **安装后复核版本**：用「安装前 / 安装后 / 目标」三个版本判断这次更新是否真的生效 ——
+  退出码 0 不再等于成功（机器级安装包在没提权时会静默退出 0 却什么都没装）。
 - **不做系统组件更新**：`.NET` 运行时、VC++ 运行库等仍会列出来，但默认不作为一键更新的目标。
 - **只写自己的目录**：状态与日志写在 `~/.dsh/dsh-app-updater/`，不碰 profile 与宿主配置。
 
@@ -118,7 +135,8 @@ curl -X POST -H "Content-Type: application/json" \
 
 ## 依赖
 
-- **Windows**（`winget.exe`，即 Microsoft「应用安装程序 / App Installer」）。没装 winget 时插件仍能列出注册表里的应用，但无法判断是否有新版本。
+- **Windows**：`winget.exe`（Microsoft「应用安装程序 / App Installer」）。没装 winget 时插件仍能列出注册表里的应用，但无法判断是否有新版本。
+- **macOS**：`brew`（[Homebrew](https://brew.sh)）。没装 Homebrew 时明确报告引擎不可用，不会假装能更新。
 - 不需要任何第三方 npm 依赖；宿主半身只用 Node 内置模块，浏览器半身只用宿主提供的 `react`。
 
 ## 接口（宿主半身）
@@ -127,7 +145,7 @@ curl -X POST -H "Content-Type: application/json" \
 |---|---|---|
 | GET | `/dsh-app-updater/state.json` | 当前状态、应用清单、日志、设置 |
 | GET | `/dsh-app-updater/apps.json` | 只取应用清单与统计 |
-| GET | `/dsh-app-updater/health.json` | 自检（路由数、数据目录） |
+| GET | `/dsh-app-updater/health.json` | 自检：版本、运行环境、引擎与能力、路由数、数据目录 |
 | POST | `/dsh-app-updater/scan` | `{confirm:true, force:true}` 开始扫描 |
 | POST | `/dsh-app-updater/update` | `{confirm:true, ids:[...]}` 开始更新队列 |
 | POST | `/dsh-app-updater/cancel` | `{confirm:true}` 取消未开始项 |
@@ -153,11 +171,39 @@ dsh plugin --profile <profile> add link:/path/to/dsh-app-updater
 ## 测试
 
 ```bash
-node test/unit.mjs              # 36 项：定宽表格解析、版本比较、安装包清单与静默参数
+node test/unit.mjs              # 66 项：定宽表格解析、版本比较、清单与静默参数、系统/架构识别、Homebrew 解析
 node test/render.mjs            # 32 项：设置面板、演练提示、列宽拖拽、请求体
 node test/harness.mjs --scan    # 用假 cordis ctx + 真 HTTP 把宿主半身跑起来
 ```
 
+## 支持的系统与架构
+
+插件启动时会识别本机环境，并据此挑选对应架构的安装包：
+
+| 系统 | 架构 | 更新引擎 | 说明 |
+|---|---|---|---|
+| Windows 10 / 11 | x64 / ARM64 / x86 | **winget** | 把识别到的架构传给 `winget --architecture`；清单没有该架构的包时自动退回自动匹配并记录日志 |
+| macOS 11+ | Apple Silicon / Intel | **Homebrew cask** | Homebrew 自己按本机架构取 cask；没有 Homebrew 时明确报告引擎不可用 |
+| 其它 | — | 无 | 扫描/更新接口返回 400 并说明原因 |
+
+识别结果会显示在状态行与设置面板的「运行环境」里，例如
+`Windows 11（build 26300） · x64（AMD64） · winget 1.29.380` 或
+`macOS 15（Sequoia） · Apple Silicon（ARM64） · Homebrew 4.5.0`。
+
+还可以在设置面板里关掉「按本机架构安装包」——关闭后把选择权交回 winget 自己（Homebrew 一直按本机架构）。
+
+机器级安装（MSI、写入 `Program Files`）需要管理员权限，否则 MSI 会返回 1603（MSI 日志里是
+`Error 1925: You do not have sufficient privileges…`），部分安装器则可能**静默退出 0 却什么都没装**。
+因此安装类命令默认自动提权执行（设置里的「自动提权安装」，默认开启）：安装包本体与
+`winget upgrade` 兜底都交给 `Start-Process -Verb RunAs` 的提权副本，装完再按
+「安装前版本 / 安装后版本 / 目标版本」复核这次更新是否真的生效。
+UAC 为「始终通知」时每次安装会弹一次确认；把 DSH 本身以管理员身份运行则不会再弹。
+Edge 走它自带的更新服务：winget 目录里的 `Microsoft.Edge` 是企业版 MSI，与本机消费版的
+安装技术不匹配（`0x8A15008E`），winget 会直接拒绝。
+
+> macOS 的 Homebrew 路径是按 Homebrew 官方 CLI 行为实现的，识别与解析逻辑有单测覆盖；
+> 但本插件主要在 Windows 上开发，macOS 上的安装/更新没有真机验证过，遇到问题请开 Issue。
+
 ## 卸载
 
 1. 从 profile 的 `package.json` 里删掉 `dsh.profile.bundles` 中的 `dsh-app-updater` 与 `dependencies` 中的对应条目。

package/RELEASING.md

@@ -0,0 +1,76 @@
+# 发版流程
+
+这个仓库同时是 **GitHub 插件源码** 和 **npm 包 `dsh-app-updater`**，两者版本必须一致。
+
+## 1. 改版本号与更新日志
+
+```bash
+# package.json 的 version 改成新版本，例如 1.0.1
+# CHANGELOG.md 顶部加一节（遵循 keep-a-changelog 的写法）
+```
+
+## 2. 本地自测
+
+```bash
+npm test                       # unit 36 项 + render 32 项
+node test/harness.mjs --scan   # 宿主半身跑真实 HTTP（需要 Windows + winget）
+```
+
+## 3. 发布到 npm
+
+npm 目前要求发布必须通过 2FA，或使用**开启 Bypass 2FA 的 Granular Access Token**：
+
+```bash
+# 方式 A：账号已开 2FA
+npm publish --access public --otp=<6 位动态码>
+
+# 方式 B：用带 Bypass 2FA 的 token（写入临时 userconfig，别写进仓库）
+npm publish --access public --userconfig=<某个仓库外的 .npmrc>
+```
+
+> 注意：带 Bypass 2FA 的令牌可以做发布，但**不能**做 `npm unpublish` / 账号类操作，
+> 那些仍然需要在网页上以 2FA 完成。
+
+## 4. 打 GitHub Release（附预构建包）
+
+```bash
+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)
+```
+
+资产名必须**不带版本号**：README 与各插件市场用的是
+`releases/latest/download/dsh-app-updater.tgz`，`latest/download/` 只解析 `latest`，
+文件名是按字面取的——一旦资产名带版本号，下一次发版这个链接就会 404。
+如果确实想让文件名带版本号，就把链接改成钉住 tag 的形式（`releases/download/v1.0.0/…`）。
+
+## 5. 市场收录怎么更新
+
+- **dsh-plugin.org / dshopen.org / awesome-dsh-plugin**：仓库更新后它们按各自刷新周期同步，
+  一般不需要重新提交；条目信息（版本、Star、更新时间）会自动跟上。
+- **dsh.works / DSH.SO / DSH STORE**：全部自动抓取，无需任何操作。
+- **DSH Plugin Index（realoiyo.github.io）**：只抓 npm 包，`npm publish` 后下次重建即更新。
+- 提交入口（首次收录用）：
+  - dsh-plugin.org → https://github.com/dshplugin/dsh-plugin-hub/issues （模板见其 submit 页）
+  - dshopen.org → https://github.com/polang233/dsh-plugin-index/issues/new?template=plugin-add.yml
+  - awesome-dsh-plugin → 向仓库提 PR，新增 `data/plugins/<owner>__<repo>.yml`（见其 contributing.md）
+
+### 刚发版时别人可能装到旧版本
+
+pnpm 默认有 `minimumReleaseAge`（新发布的包先观察一段时间才参与解析）。profile 里若没写
+`minimumReleaseAge: 0`，`dsh plugin add <包名>` 在发版后的一段时间内可能仍解析到上一个版本：
+
+```bash
+# 立刻拿到刚发布的版本：显式指定版本号
+dsh plugin --profile web add dsh-app-updater@<version>
+```
+
+这不是包的问题，是消费端的供应链策略；等宽限期过去后不带版本号也会解析到新版。
+（排查时看 profile 的 `pnpm-workspace.yaml`：`minimumReleaseAge` 与 `minimumReleaseAgeExclude`。）
+
+## 6. 本地开发时的桌面端安装
+
+Electron 托管的 `desktop` profile 不接受 `dsh plugin` 写入。做法是在
+`<profile>/node_modules` 下建立指向本仓库的目录 junction，并把包名加进 profile
+`package.json` 的 `dsh.profile.bundles` 与 `dependencies`，重启 DSH 生效。