dsh-app-updater 1.3.0 → 1.3.2

package/CHANGELOG.md

@@ -2,6 +2,81 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [1.3.2] — 2026-11-01
+
+### 修复
+
+- **macOS 上「未检测到任何已安装应用」**（用户实测报告）：1.3.0/1.3.1 的 macOS 扫描只执行
+  `brew list --cask --versions`，也就是**只有通过 Homebrew 装过的应用才会出现在列表里**。
+  一台正常使用的 Mac 上绝大多数应用是拖 DMG 装的，于是该命令返回空 → 界面显示「未检测到
+  任何已安装应用」，日志里是「Homebrew 报告 0 个已安装 cask 应用」。这不是「没有应用」，
+  而是**根本没有枚举应用**。现在（`lib/macos.js`）：
+  - 枚举标准应用目录里的 `.app`：`/Applications`、`/Applications/Utilities`、
+    `/System/Applications`（及其 `Utilities`）、`~/Applications`，用 `plutil` 读每个
+    bundle 的 `Info.plist` 取显示名与版本（读不到时退回 `defaults read`）；
+  - 抓取 Homebrew 的 cask 目录（`formulae.brew.sh/api/cask.json`，本地缓存 24 小时）把
+    `.app` 反查到 cask token，从而知道**官网最新版本**；
+  - 只有**确实由 Homebrew 管理**的应用才标记为可一键更新；其余应用如实列出并标注原因
+    （`not-managed` 非 Homebrew 管理 / `store-managed` 由 App Store 管理 /
+    `system-component` 系统组件），绝不假装能更新。
+- **同一个 `.app` 被多个 cask 声明时匹配错乱**：真实目录里 `iterm2` 与 `iterm2@nightly`
+  都声明 `iTerm.app`，旧写法「后写覆盖」会让匹配结果随目录顺序漂移（实测会把同一个应用
+  列出两次）。现在保留全部候选，由 `pickCask` 按「已装 > 非弃用/停用 > 主 token >
+  token 与应用名相等」挑选。
+- **没有 Homebrew 也能扫描**：`capabilitiesFor` 不再把「macOS 无 Homebrew」判成不可扫描 ——
+  应用照样列出来，只是无法判断/驱动更新，提示改为「安装 Homebrew 后可一键升级 cask 应用」。
+- **设置面板按平台显示**：macOS 上不再出现「自动提权安装」「下载失败时回退 winget」
+  「包含应用商店应用」（Windows 概念），改为 macOS 专属的「包含 App Store 应用」与
+  「包含非 Homebrew 应用」（新增设置项 `includeUnmanagedApps`，默认开启）。
+- **空状态文案分平台**：macOS 下列表为空时提示去看运行日志里的「枚举应用目录」记录，
+  而不是干巴巴一句「未检测到任何已安装应用」。
+
+### 新增
+
+- **`lib/macos.js`**：应用目录枚举、`Info.plist` 解析、cask 目录缓存与解析、cask 匹配、
+  列表合并（纯函数 `buildMacosItems` 便于单测）。
+- 日志更细：分别记录「枚举到多少个 .app」「Homebrew 报告多少个 cask」「读取 cask 目录结果」，
+  macOS 上再出现异常时一眼能看出断在哪一步。
+
+### 测试
+
+- `test/unit.mjs` 152 项（新增 macOS 应用枚举 20 项、同名 cask 挑选 6 项、cask 目录解析 6 项）；
+  用**真实** `formulae.brew.sh/api/cask.json`（7824 个 cask）验证过匹配与去重。
+- `test/render.mjs` 44 项（新增 macOS 设置面板 6 项、macOS 空状态文案 2 项）。
+- `test/deny.mjs` 12 项不变。
+
+## [1.3.1] — 2026-11-01
+
+### 安全
+
+- **「仅凭回环地址放行」改为默认拒绝**（插件市场 dshopen.org 对 1.3.0 的复核意见）：
+  1.3.0 接入 `connection` 准入后仍留了一条退回路径 —— 宿主没有 `connection` 服务，或请求
+  不带任何连接凭据且来自回环地址时，直接按「本机信任」放行。在没有准入服务的旧宿主上，
+  任何本机进程（以及能向回环发起请求的页面）都能借此调用 `/update`、`/settings` 等安装接口，
+  等于绕过认证。1.3.1 起这条路径**默认关闭**：
+  - 宿主有 `connection`：一律以 `admit()` 的结果为准，`401` / `403` / `409` 原样返回
+    （响应头 `X-DSH-Admission: denied`）。只有「401 + 回环 + 无凭据 + 用户显式开启兼容模式」
+    这一种例外，且必须在下面第 2 条的前提下才成立。
+  - 宿主没有 `connection`：**默认 403**，不再自动相信回环地址。
+- **兼容模式必须由用户显式开启**（保留给确实跑在旧宿主上的用户）：插件配置
+  `allowLegacyLoopback: true`（`cordis.patch.yml` 覆盖同名条目）或环境变量
+  `DSH_APP_UPDATER_ALLOW_LEGACY_LOOPBACK=1`，两者默认都没有。开启后：
+  - 放行的请求带 `X-DSH-Admission: loopback-legacy-optin` 与 `X-DSH-Admission-Warning`；
+  - `state.json` / `health.json` 新增 `admission` 字段（`mode` / `service` /
+    `allowLegacyLoopback` / `warning`），复核时不必读代码就能确认当前路径；
+  - 设置页顶部显示红色警示条，日志写一条 `warn`。
+- **准入拒绝统一返回 JSON**：`401`/`403`/`409` 带 `{ ok:false, error, admission:"denied" }`，
+  不再用纯文本，排障时能直接看出是被准入挡掉的。
+
+### 测试
+
+- `test/unit.mjs`：准入用例从 6 项扩到 25 项，覆盖兼容模式开关（配置 / 环境变量 / 缺省关闭）、
+  无 `connection` 服务默认拒绝、显式开启后放行、非回环仍拒绝、`409`、带凭据未认证不放行等。
+- 新增 `test/deny.mjs`：起真实 HTTP 服务，验证无 `connection` 且未开兼容模式时**每一条路由**
+  都是 `403 + X-DSH-Admission: denied`；再验证显式开启后放行并标注 opt-in 响应头。
+- `test/render.mjs`：新增兼容模式警示条 4 项（开启显示、样式、文案、默认不显示）。
+- 自测命令更新为 `node test/unit.mjs && node test/render.mjs && node test/deny.mjs`。
+
 ## [1.3.0] — 2026-10-31
 
 ### 修复

package/CONTRACT.md

@@ -41,10 +41,14 @@ dsh-app-updater/
 
 全部 `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`）。
+宿主自己的 `/api` 路由用的同一套），被拒即返回 `401`（未认证）/ `403`（不可信来源）/
+`409`（连接被占用），响应头带 `X-DSH-Admission: denied`；写操作再要求 `confirm: true`。
+
+**默认拒绝**（1.3.1 起）：宿主没有 `connection` 服务时不再「仅凭回环地址放行」，而是 `403`。
+只有用户显式开启兼容模式（插件配置 `allowLegacyLoopback: true` 或环境变量
+`DSH_APP_UPDATER_ALLOW_LEGACY_LOOPBACK=1`）时，回环请求才放行，并带
+`X-DSH-Admission: loopback-legacy-optin` 与 `X-DSH-Admission-Warning`（见 `lib/index.js` 的
+`admissionGate` / `resolveLegacyLoopbackOptIn`）。
 
 ### GET /dsh-app-updater/state.json
 
@@ -62,7 +66,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, "downloadDir": "", "keepInstallers": true, "hashFallbackUpgrade": true, "dryRun": false, "matchSystemArch": true, "autoElevate": true },
+  // 准入现状，供界面与复核确认当前走哪条路径（默认 "deny" 不会出现在能读到响应的地方）
+  "admission": { "mode": "connection|connection+loopback-legacy|loopback-legacy-optin|deny", "service": true, "allowLegacyLoopback": false, "warning": null }
 }
 ```
 
@@ -70,20 +76,25 @@ dsh-app-updater/
 
 ```jsonc
 {
-  "id": "Google.Chrome",            // winget id；注册表项 "reg:<key>"；macOS "brew:<cask token>"
+  "id": "Google.Chrome",            // winget id；注册表项 "reg:<key>"；macOS 由 Homebrew 管理的是 "brew:<cask token>"，其余 "macapp:<bundle id>"
   "name": "Google Chrome",
   "version": "155.0.8059.85",       // 已安装版本，未知时 ""
   "available": "156.0.8078.48",     // 可升级到的版本，无更新时 ""
   "publisher": "Google LLC",
-  "source": "winget",               // winget | msstore | registry | homebrew
+  "source": "winget",               // winget | msstore | registry | homebrew | appstore | app
   "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 | cask | null（未知）
+  "reason": null,                   // null | "not-in-catalog" | "not-managed" | "unknown-version" | "pinned" | "store-managed" | "system-component"
+  "kind": "exe"                     // exe | msi | msix | inno | cask | app | null（未知）
 }
 ```
 
+`reason` 里的 `not-managed` 是 macOS 专用：应用在标准目录里枚举到了，但不是由 Homebrew 管理
+（拖 DMG / 手动安装），所以能列出、不能一键更新。`source` 的 `app` / `appstore` 同理只出现在
+macOS。macOS 的扫描范围是 `/Applications`、`/Applications/Utilities`、`/System/Applications`
+（及其 `Utilities`）与 `~/Applications`；装在别处的应用不在范围内。
+
 ### POST /dsh-app-updater/scan
 
 body `{ "confirm": true, "force": true }` → `{ "ok": true, "started": true }`（异步；结果看 state.json / apps.json）

package/README.en.md

@@ -88,8 +88,9 @@ State file: `%USERPROFILE%\.dsh\dsh-app-updater\state.json`
 
 | Key | Default | Meaning |
 |---|---|---|
-| `includeStoreApps` | `true` | List Store (MSIX) apps too (display only). |
-| `includeRegistryOnly` | `true` | Fill in apps missing from the winget catalog using the registry (display only). |
+| `includeStoreApps` | `true` | List store apps too (MSIX on Windows, App Store on macOS; display only). |
+| `includeRegistryOnly` | `true` | Windows: fill in apps missing from the winget catalog using the registry (display only). |
+| `includeUnmanagedApps` | `true` | macOS: also list apps that Homebrew does not manage (drag-to-Applications installs; display only). |
 | `downloadDir` | empty | Custom download folder; empty = `%USERPROFILE%\Downloads\DSH App Updater`. Must be absolute. |
 | `keepInstallers` | `true` | Keep the installer after a successful update. |
 | `hashFallbackUpgrade` | `true` | Fall back to `winget upgrade` when the download fails. |
@@ -110,8 +111,25 @@ curl -X POST -H "Content-Type: application/json" \
 
 ## Safety boundaries
 
-- **Every write requires loopback + explicit confirmation**: `scan` / `update` / `cancel` /
-  `settings` / `open-downloads` accept only requests from loopback with `confirm:true`.
+- **Every route is deny-by-default**: each request first goes through `ctx.connection.admit(request)`
+  — DSH's Host/Origin fence plus browser-session / API authentication, the same gate the host uses for
+  its own `/api` routes. Rejected requests get `401` / `403` / `409` with `X-DSH-Admission: denied`.
+- **Legacy loopback mode is off by default** (since 1.3.1): when the host has no `connection`
+  service, requests are no longer trusted just because they come from loopback — they get `403`.
+  If you really need it on an old host, opt in explicitly, either via plugin config:
+
+  ```yaml
+  - id: dsh-app-updater
+    config:
+      allowLegacyLoopback: true
+  ```
+
+  or by exporting `DSH_APP_UPDATER_ALLOW_LEGACY_LOOPBACK=1` before starting DSH. Once enabled, allowed
+  requests carry `X-DSH-Admission: loopback-legacy-optin` and `X-DSH-Admission-Warning`, the
+  `admission` field in `state.json` / `health.json` reports `mode: "loopback-legacy-optin"`, the
+  settings page shows a red banner, and a `warn` line is written to the log.
+- **Every write still requires explicit confirmation**: `scan` / `update` / `cancel` /
+  `settings` / `open-downloads` require `confirm:true`.
 - **No guessed silent switches**: the publisher's declared `Silent` switches are preferred;
   generic defaults are used only when a manifest is unavailable.
 - **Elevation only for installs, and on demand**: install commands that need administrator rights
@@ -130,8 +148,10 @@ curl -X POST -H "Content-Type: application/json" \
 
 - **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.
+- **macOS**: no extra dependency is needed to **list** apps (the plugin reads `.app` bundles from
+  `/Applications` and friends); judging and applying updates needs `brew` ([Homebrew](https://brew.sh)).
+  Without Homebrew the apps are still listed, with a note that installing Homebrew enables one-click
+  cask upgrades.
 - No third-party npm dependencies: the host half uses Node built-ins only, the browser half
   only the host-provided `react`.
 
@@ -142,7 +162,7 @@ The plugin detects its own environment at startup and picks the installer that m
 | 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 |
+| macOS 11+ | Apple Silicon / Intel | **Homebrew casks** | apps are enumerated from `/Applications` and friends, then matched against the cask catalog; Homebrew resolves the right cask for the machine. Without Homebrew the apps are still listed, they just cannot be upgraded in one click |
 | 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.
@@ -152,9 +172,13 @@ The result is shown in the status line and in the settings panel's “运行环
 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.
+> The macOS app enumeration (`/Applications` + `Info.plist`) and cask matching are covered by unit
+> tests and were validated against the real `formulae.brew.sh` catalog (7,800+ casks), but the
+> macOS **install/update execution** has not been verified on a real Mac — this plugin is developed
+> on Windows. Please open an issue if something misbehaves there.
+>
+> Only the standard application directories are enumerated. Apps installed elsewhere (a custom
+> folder, the Desktop, an external volume) are outside the scan scope by design.
 
 ## HTTP API (host half)
 
@@ -191,8 +215,9 @@ Then add `dsh-app-updater` to `dsh.profile.bundles` in the profile's `package.js
 ## Tests
 
 ```bash
-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/unit.mjs     # 152 checks: table parsing, version compare, manifest & switches, OS/arch detection, Homebrew parsing, macOS app enumeration & cask matching
+node test/render.mjs   # 44 checks: settings panel (per platform), rehearsal 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
 ```
 

package/README.md

@@ -93,9 +93,10 @@ dsh plugin --profile web add https://github.com/19952730389/dsh-app-updater/rele
 
 | 键 | 默认 | 说明 |
 |---|---|---|
-| `includeStoreApps` | `true` | 是否把商店（MSIX）应用列进来（只展示，不会被更新）。 |
-| `includeRegistryOnly` | `true` | 是否用注册表补齐 winget 未收录的应用（只展示，不能更新）。 |
-| `downloadDir` | 空 | 自定义安装包下载目录；空 = `%USERPROFILE%\Downloads\DSH App Updater`。 |
+| `includeStoreApps` | `true` | 是否把商店应用列进来（Windows 是 MSIX、macOS 是 App Store 应用；只展示，不会被更新）。 |
+| `includeRegistryOnly` | `true` | Windows：是否用注册表补齐 winget 未收录的应用（只展示，不能更新）。 |
+| `includeUnmanagedApps` | `true` | macOS：是否把非 Homebrew 管理（拖 DMG / 手动装）的应用也列出来（只展示，不能更新）。 |
+| `downloadDir` | 空 | 自定义安装包下载目录；空 = `%USERPROFILE%\Downloads\DSH App Updater`（macOS 为 `~/Downloads/DSH App Updater`）。 |
 | `keepInstallers` | `true` | 更新后保留安装包；`false` 则在安装完成后删掉该应用刚下载的包。 |
 | `hashFallbackUpgrade` | `true` | 下载失败时退回 `winget upgrade` 兜底。 |
 | `dryRun` | `false` | **演练模式**：只下载官网全量安装包、不执行安装。用来先看会装什么。 |
@@ -113,14 +114,32 @@ curl -X POST -H "Content-Type: application/json" \
 `downloadDir` 会被校验：必须留空（用默认目录）或是绝对路径（`D:\Apps`）／UNC 路径（`\\server\share`），
 否则返回 `400` 并在面板里显示红字提示，不会把安装包写到意料之外的位置。
 
+> 这些路由**默认拒绝**：请求必须通过宿主的 `connection` 准入（浏览器里就是带上 DSH 页面的会话
+> Cookie），或在**没有 `connection` 服务的旧宿主**上由你显式开启兼容模式（见「安全边界」）。
+> 仅凭「来自 127.0.0.1」不再放行 —— 1.3.1 已把这条路径改成默认拒绝。
+
 ---
 
 ## 安全边界
 
-- **接入宿主 connection 准入**：每个请求先过 `ctx.connection.admit(request)` —— DSH 用来做
+- **路由默认拒绝**：每个请求先过 `ctx.connection.admit(request)` —— DSH 用来做
   Host/Origin 信任校验与浏览器会话 / API 认证的那套边界（宿主自己的 `/api` 路由用的就是它），
-  未通过的请求直接得到 `401`/`403`。宿主没有 `connection` 服务、或请求不带任何连接凭据且来自
-  回环地址时，退回旧的「回环」规则，并在响应头标注 `X-DSH-Admission: loopback-legacy`。
+  未通过的请求直接得到 `401` / `403` / `409`，响应头带 `X-DSH-Admission: denied`。
+- **兼容模式默认关闭**（1.3.1 起）：宿主没有 `connection` 服务时**不再**「仅凭回环地址放行」，
+  一律 `403`。旧宿主上确实需要时，必须由你**显式**开启，二选一：
+  - 插件配置（`cordis.patch.yml` 里覆盖同名条目）：
+
+    ```yaml
+    - id: dsh-app-updater
+      config:
+        allowLegacyLoopback: true
+    ```
+
+  - 或启动 DSH 前设置环境变量 `DSH_APP_UPDATER_ALLOW_LEGACY_LOOPBACK=1`。
+
+  开启后：放行的回环请求带 `X-DSH-Admission: loopback-legacy-optin` 与
+  `X-DSH-Admission-Warning`，`state.json` / `health.json` 的 `admission` 字段会标明
+  `mode: "loopback-legacy-optin"`，设置页顶部也会出现红色提示条；日志里记一条 `warn`。
 - **写操作还要显式确认**：`scan` / `update` / `cancel` / `settings` / `open-downloads` 必须带 `confirm:true`。
 - **不猜测静默参数**：优先用发布方在清单里声明的 `Silent` 参数；清单缺失时才按安装包类型用保守的默认开关。
 - **需要管理员时自动提权**：机器级安装包（MSI、写入 `Program Files`）交给
@@ -136,7 +155,7 @@ curl -X POST -H "Content-Type: application/json" \
 ## 依赖
 
 - **Windows**：`winget.exe`（Microsoft「应用安装程序 / App Installer」）。没装 winget 时插件仍能列出注册表里的应用，但无法判断是否有新版本。
-- **macOS**：`brew`（[Homebrew](https://brew.sh)）。没装 Homebrew 时明确报告引擎不可用，不会假装能更新。
+- **macOS**：无需额外依赖即可**列出**应用（直接读 `/Applications` 等目录里的 `.app`）；要判断并执行更新需要 `brew`（[Homebrew](https://brew.sh)）。没装 Homebrew 时会照常列出应用，并说明「安装 Homebrew 后可一键升级 cask 应用」。
 - 不需要任何第三方 npm 依赖；宿主半身只用 Node 内置模块，浏览器半身只用宿主提供的 `react`。
 
 ## 接口（宿主半身）
@@ -171,8 +190,9 @@ dsh plugin --profile <profile> add link:/path/to/dsh-app-updater
 ## 测试
 
 ```bash
-node test/unit.mjs              # 66 项：定宽表格解析、版本比较、清单与静默参数、系统/架构识别、Homebrew 解析
-node test/render.mjs            # 32 项：设置面板、演练提示、列宽拖拽、请求体
+node test/unit.mjs              # 152 项：定宽表格解析、版本比较、清单与静默参数、系统/架构识别、Homebrew 解析、macOS 应用枚举与 cask 匹配
+node test/render.mjs            # 44 项：设置面板（按平台）、演练提示、列宽拖拽、请求体
+node test/deny.mjs              # 12 项：无 connection 服务时逐路由验证默认拒绝
 node test/harness.mjs --scan    # 用假 cordis ctx + 真 HTTP 把宿主半身跑起来
 ```
 
@@ -183,7 +203,7 @@ 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 时明确报告引擎不可用 |
+| macOS 11+ | Apple Silicon / Intel | **Homebrew cask** | 应用从 `/Applications` 等目录枚举，再按 cask 目录匹配；Homebrew 自己按本机架构取 cask。没装 Homebrew 时仍能列出应用，只是不能一键更新 |
 | 其它 | — | 无 | 扫描/更新接口返回 400 并说明原因 |
 
 识别结果会显示在状态行与设置面板的「运行环境」里，例如
@@ -201,8 +221,12 @@ UAC 为「始终通知」时每次安装会弹一次确认；把 DSH 本身以
 Edge 走它自带的更新服务：winget 目录里的 `Microsoft.Edge` 是企业版 MSI，与本机消费版的
 安装技术不匹配（`0x8A15008E`），winget 会直接拒绝。
 
-> macOS 的 Homebrew 路径是按 Homebrew 官方 CLI 行为实现的，识别与解析逻辑有单测覆盖；
-> 但本插件主要在 Windows 上开发，macOS 上的安装/更新没有真机验证过，遇到问题请开 Issue。
+> macOS 的应用枚举（`/Applications` 等目录 + `Info.plist`）与 cask 匹配逻辑有单测覆盖，
+> 并用真实的 `formulae.brew.sh` 目录（7800+ cask）验证过匹配与去重；
+> 但本插件主要在 Windows 上开发，macOS 上的**安装/更新执行**没有真机验证过，遇到问题请开 Issue。
+>
+> macOS 上只枚举标准应用目录。应用如果装在别处（例如 `~/Desktop` 或自定义目录），
+> 本插件看不到它 —— 这不是漏扫，是扫描范围之外。
 
 ## 卸载
 

package/lib/client.js

@@ -34,7 +34,9 @@ window.__ModuleLoader__.load({
     const MIN_COL_PX = 48;
     const MAX_COL_PX = 640;
 
-    /* 设置项 → 中文标签与说明 */
+    /* 设置项 → 中文标签与说明。
+       `only` 限定平台：跨平台的开关不写，平台专属的开关只有对应系统才显示，
+       避免 macOS 上出现「自动提权安装」这种 Windows 概念。 */
     const TOGGLES = [
       {
         key: "keepInstallers",
@@ -56,26 +58,49 @@ window.__ModuleLoader__.load({
         key: "autoElevate",
         label: "自动提权安装",
         hint: "需要管理员的安装包（MSI、写入 Program Files）改由管理员上下文执行；UAC 开启时每次安装会弹一次确认",
+        only: "windows",
       },
       {
         key: "hashFallbackUpgrade",
         label: "下载失败时回退 winget",
         hint: "官网包哈希与目录记录不一致时，改用 winget 安装同源全量包",
+        only: "windows",
       },
       {
         key: "includeStoreApps",
         label: "包含应用商店应用",
         hint: "商店 / MSIX 应用只列出，更新仍由 Microsoft Store 负责",
+        only: "windows",
       },
       {
         key: "includeRegistryOnly",
         label: "包含目录未收录应用",
         hint: "用注册表补齐 winget 目录未收录的软件（只列出，无法自动更新）",
+        only: "windows",
+      },
+      {
+        key: "includeStoreApps",
+        label: "包含 App Store 应用",
+        hint: "App Store 应用只列出，升级仍由 App Store 负责",
+        only: "macos",
+      },
+      {
+        key: "includeUnmanagedApps",
+        label: "包含非 Homebrew 应用",
+        hint: "把拖 DMG / 手动安装的应用也列出来（只列出，无法自动更新）",
+        only: "macos",
       },
     ];
 
+    /** 当前平台该显示的开关（未知平台按 Windows 显示，保持兼容）。 */
+    function togglesFor(family) {
+      const fam = family === "macos" ? "macos" : "windows";
+      return TOGGLES.filter((t) => !t.only || t.only === fam);
+    }
+
     const REASON_TEXT = {
       "not-in-catalog": "软件目录未收录",
+      "not-managed": "非 Homebrew 管理",
       "unknown-version": "版本未知",
       "system-component": "系统组件",
       pinned: "版本被固定",
@@ -87,6 +112,8 @@ window.__ModuleLoader__.load({
       msstore: "msstore",
       registry: "registry",
       homebrew: "homebrew",
+      appstore: "App Store",
+      app: "应用",
     };
 
     /** 引擎显示名 */
@@ -170,6 +197,8 @@ window.__ModuleLoader__.load({
       ".appupd-badge-msstore{border-color:rgba(52,211,153,.55);color:#34d399;}",
       ".appupd-badge-registry{border-color:rgba(148,163,184,.5);}",
       ".appupd-badge-homebrew{border-color:rgba(251,191,36,.55);color:#fbbf24;}",
+      ".appupd-badge-appstore{border-color:rgba(52,211,153,.55);color:#34d399;}",
+      ".appupd-badge-app{border-color:rgba(148,163,184,.5);}",
       ".appupd-envline{font-size:12px;color:var(--dsw-alias-label-primary,#f3f4f6);word-break:break-word;}",
       ".appupd-state-new{font-weight:600;color:var(--dsw-alias-brand-primary,#4f8cff);white-space:nowrap;}",
       ".appupd-state-ok{color:#34d399;white-space:nowrap;}",
@@ -200,6 +229,8 @@ window.__ModuleLoader__.load({
 
       /* 演练模式警示条 */
       ".appupd-banner{display:flex;align-items:center;gap:8px;padding:6px 10px;border-radius:8px;border:1px solid rgba(251,191,36,.5);background:rgba(251,191,36,.12);color:#fbbf24;font-size:12px;}",
+      /* 兼容模式（仅回环放行）警示条：默认关闭，开启时用红色提醒 */
+      ".appupd-banner-warn{border-color:rgba(239,68,68,.55);background:rgba(239,68,68,.12);color:#f87171;}",
 
       /* 插件设置面板 */
       ".appupd-panel{border:1px solid var(--dsw-alias-border-l1,#4b5563);border-radius:8px;overflow:hidden;}",
@@ -632,6 +663,8 @@ window.__ModuleLoader__.load({
         (state && state.envSummary) ||
         (env ? [env.osName || env.platform, env.archLabel].filter(Boolean).join(" · ") : "环境未知");
       const engineText = !state ? "" : engineTextOf(engine);
+      /* 平台族：设置面板与空状态文案都要用，必须在下面的组件定义之前算出来 */
+      const family = (env && env.family) || (platform === "darwin" ? "macos" : "windows");
 
       const filtered = react.useMemo(() => {
         if (!items) return [];
@@ -907,7 +940,17 @@ window.__ModuleLoader__.load({
             "还没有检测过，点右上角『刷新检测』开始"
           );
         }
-        if (!items.length) return h("div", { className: "appupd-empty" }, "未检测到任何已安装应用");
+        if (!items.length) {
+          // 分平台给出可执行的下一步，而不是一句「未检测到任何已安装应用」
+          return h(
+            "div",
+            { className: "appupd-empty" },
+            family === "macos"
+              ? "未在应用目录里找到应用。若确认本机有应用，请看看下面的运行日志里「枚举应用目录」的记录；" +
+                "应用装在非标准位置时本插件看不到它。"
+              : "未检测到任何已安装应用"
+          );
+        }
         return h("div", { className: "appupd-empty" }, "没有匹配的应用");
       };
 
@@ -917,7 +960,10 @@ window.__ModuleLoader__.load({
 
       const settings = (state && state.settings) || {};
       const dryRunOn = Boolean(settings.dryRun);
-      const effectiveDir = (state && state.downloadDir) || "%USERPROFILE%\\Downloads\\DSH App Updater";
+      const visibleToggles = togglesFor(family);
+      const effectiveDir =
+        (state && state.downloadDir) ||
+        (family === "macos" ? "~/Downloads/DSH App Updater" : "%USERPROFILE%\\Downloads\\DSH App Updater");
 
       const dryRunBanner = dryRunOn
         ? h(
@@ -927,6 +973,21 @@ window.__ModuleLoader__.load({
           )
         : null;
 
+      /* 兼容模式：只有用户显式开启（插件配置 / 环境变量）才会出现，默认不显示 */
+      const admission = (state && state.admission) || null;
+      const legacyOn = Boolean(admission && admission.allowLegacyLoopback);
+      const legacyBanner = legacyOn
+        ? h(
+            "div",
+            { className: "appupd-banner appupd-banner-warn", role: "alert" },
+            h(
+              "span",
+              null,
+              "兼容模式已开启：没有连接凭据的本机回环请求会被放行（旧宿主没有 connection 准入时才会用到）。非必要请关闭，见 README 的「安全」一节。"
+            )
+          )
+        : null;
+
       const switchEl = (key) => {
         const on = Boolean(settings[key]);
         return h("button", {
@@ -1026,7 +1087,7 @@ window.__ModuleLoader__.load({
                   )
                 )
               ),
-              ...TOGGLES.map((t) =>
+              ...visibleToggles.map((t) =>
                 h(
                   "div",
                   { className: "appupd-field", key: t.key },
@@ -1195,6 +1256,9 @@ window.__ModuleLoader__.load({
         /* 3. 演练模式提示 */
         dryRunBanner,
 
+        /* 3b. 兼容模式（仅回环放行）提示：默认不出现 */
+        legacyBanner,
+
         /* 4. 进度 */
         progress,