dsh-app-updater 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# 更新日志
+
+本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [1.0.0] — 2026-10-31
+
+首个可用版本。
+
+### 检测
+
+- 用 `winget list` 列出已安装应用（含 winget 目录收录的软件与商店 / MSIX 包），并用注册表三处
+  `Uninstall` 键补齐 winget 目录未收录的软件。全程只读注册表与文件，**不启动任何被检测的应用**。
+- 用 `winget upgrade --include-unknown` 取「已装版本 → 可升级版本」，按包 Id 与清单合并。
+- 版本比较支持 Windows 风格的 `1.2.3.4`、日期风格 `2026.7.992920`、带后缀 `0.9.2+2026103013`
+  以及 `1.2.3-beta` 这类预发布标记。
+- 定宽表格解析按**显示宽度**切列（CJK 占 2 列），并剔除 `15 upgrades available.` 之类的尾部提示行。
+
+### 更新
+
+- 一键更新链路：`winget download` 从**发布方官网**拉取**完整安装包**（下载时核对清单里的 SHA-256）→
+  解析随包落盘的 winget 清单，取发布方自己声明的 `InstallerSwitches.Silent` →
+  静默安装 → 用 `winget list --id` 复核安装后版本。
+- 官网包哈希与目录记录不一致（发布方重签了安装包）或清单禁止直接下载时，自动退回
+  `winget upgrade --id … --exact --silent`（同源全量包，下载与安装交给 winget）。
+- 安装包与清单留档在下载目录，便于核对来源；可关闭「保留安装包」在安装后自动清理。
+- 需要管理员权限的安装包会正常弹出 UAC，插件不做静默提权。
+
+### 界面
+
+- 设置 → 应用更新：工具条（刷新检测 / 全部更新 / 更新所选 / 取消 / 打开下载目录）、
+  状态行、进度条、筛选行、应用表格、可折叠日志。
+- 表格列宽默认给足以完整显示应用名，并且**每列可拖拽调宽、双击恢复默认**，偏好记在浏览器本地。
+- 插件设置面板：安装包下载目录（含绝对路径校验）、保留安装包、演练模式、下载失败回退 winget、
+  包含商店应用、包含目录未收录应用。演练模式开启时页面顶部有醒目提示。
+- 全部写操作要求本机（loopback）来源并显式带 `confirm:true`。

package/CONTRACT.md

@@ -0,0 +1,93 @@
+# dsh-app-updater 契约（宿主 ↔ 客户端）
+
+插件 id：`dsh-app-updater`　显示名：应用更新（App Updater）
+
+## 文件布局
+
+```
+dsh-app-updater/
+├─ package.json          # main: ./lib/index.js, exports ./client, dsh.bundle.patch, dsh.client
+├─ cordis.patch.yml      # insert 行：id=dsh-app-updater, name=dsh-app-updater
+├─ lib/
+│  ├─ index.js           # 宿主半身：cordis 插件，注册 /dsh-app-updater/* 路由
+│  ├─ engine.js          # 扫描 / 下载 / 安装编排
+│  ├─ winget.js          # winget 定位、调用、表格解析
+│  ├─ registry.js        # 注册表 Uninstall 键枚举（覆盖 winget 未收录的应用）
+│  ├─ version.js         # 版本比较（Windows 风格 1.2.3.4 + 字母后缀）
+│  ├─ state.js           # 持久化状态（~/.dsh/dsh-app-updater/state.json）
+│  └─ client.js          # 浏览器半身：设置页 UI
+└─ README.md
+```
+
+## 宿主 HTTP 路由
+
+全部 `kind: "exact"`，前缀 `/dsh-app-updater/`。写操作要求 loopback + `confirm: true`。
+
+### GET /dsh-app-updater/state.json
+
+```jsonc
+{
+  "ok": true,
+  "platform": "win32",
+  "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": [] },
+  "log": [ { "at": 0, "level": "info|warn|error|success", "text": "..." } ],
+  "settings": { "includeStoreApps": true, "includeRegistryOnly": true, "downloadDir": "", "keepInstallers": true, "hashFallbackUpgrade": true, "dryRun": false }
+}
+```
+
+`apps.items[]`（单条应用）：
+
+```jsonc
+{
+  "id": "Google.Chrome",            // winget id；纯注册表项为 "reg:<GUID 或 key 尾段>"
+  "name": "Google Chrome",
+  "version": "155.0.8059.85",       // 已安装版本，未知时 ""
+  "available": "156.0.8078.48",     // 可升级到的版本，无更新时 ""
+  "publisher": "Google LLC",
+  "source": "winget",               // winget | msstore | registry
+  "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（未知）
+}
+```
+
+### POST /dsh-app-updater/scan
+
+body `{ "confirm": true, "force": true }` → `{ "ok": true, "started": true }`（异步；结果看 state.json / apps.json）
+
+### GET /dsh-app-updater/apps.json
+
+`{ "ok": true, "scannedAt": 0, "stats": {...}, "items": [App...], "warnings": ["..."] }`
+
+### POST /dsh-app-updater/update
+
+body `{ "confirm": true, "ids": ["Google.Chrome", "..."], "mode": "silent" }`
+→ `{ "ok": true, "started": true, "queued": 3 }`（串行执行，逐条下载官网全量包 → 校验 → 静默安装）
+
+### POST /dsh-app-updater/cancel
+
+→ `{ "ok": true }`（取消尚未开始的项目；正在安装的进程会收到终止请求）
+
+### POST /dsh-app-updater/settings
+
+body `{ "confirm": true, "settings": { ... } }` → `{ "ok": true, "settings": {...} }`
+
+### POST /dsh-app-updater/open-downloads
+
+→ `{ "ok": true, "path": "..." }`（在资源管理器中打开下载目录）
+
+## 客户端要求
+
+- `window.__ModuleLoader__.load({ id: "dsh-app-updater", factory: (require) => { ... } })`
+- `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）

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 19952730389
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,177 @@
+# 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)
+![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
+with one click — downloading the **full installer from each vendor's own website** and
+installing it silently. **The detected applications are never launched.**
+
+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
+```
+
+Prebuilt `.tgz` (see [Releases](https://github.com/19952730389/dsh-app-updater/releases)):
+
+```bash
+dsh plugin --profile web add https://github.com/19952730389/dsh-app-updater/releases/latest/download/dsh-app-updater.tgz
+```
+
+Restart DSH afterwards; the plugin lives at **Settings → 应用更新**. The Electron-managed
+`desktop` profile does not accept `dsh plugin` writes, so link the package into that
+profile's `node_modules` and add it to `dsh.profile.bundles` manually.
+
+---
+
+## What it actually does
+
+| Step | How |
+|---|---|
+| 1. List installed apps | `winget list` (apps known to the winget catalog plus Store/MSIX packages) **and** the three Windows registry `Uninstall` keys (apps the catalog does not know). Read-only: no application is ever started. |
+| 2. Decide whether an update exists | `winget upgrade --include-unknown` gives "installed version → available version" from the official winget catalog, merged into the inventory by package id. |
+| 3. One-click update | `winget download` fetches the **vendor's full installer** from the URL recorded in the winget manifest (SHA-256 verified), the downloaded manifest supplies the publisher's own `InstallerSwitches.Silent`, the installer runs silently, and the resulting version is re-read with `winget list --id`. |
+| 4. Fallback | If the vendor re-signed the installer (hash no longer matches the catalog) or the manifest forbids direct download, it falls back to `winget upgrade --id … --exact --silent` — still the full installer from the vendor, with winget doing the fetching and installing. |
+
+Those download URLs really are the vendors' own: `github.com/git-for-windows/…`,
+`dl.google.com/dl/chrome/install/…`, `download.cpuid.com/cpu-z/…`, `dl.hdslb.com/…`.
+Both the installer and its `.yaml` manifest are kept in the download folder, so the
+`InstallerUrl`, `InstallerSha256` and silent switches can be audited afterwards.
+
+---
+
+## Usage
+
+1. Open **Settings → 应用更新**.
+2. Click **刷新检测** (nothing runs in the background; scanning only happens when you ask).
+3. The table sorts updateable apps first. Use the search box and the
+   **全部 / 仅可更新 / 未收录** segments to narrow it down.
+4. Tick the apps to update (or press **全部更新**), or update a single app from its row.
+5. While updating you get a progress bar, the current app name and a per-item log;
+   **取消** stops the items that have not started yet.
+6. **打开下载目录** reveals the downloaded vendor installers in Explorer.
+
+### Status values
+
+| Status | Meaning |
+|---|---|
+| **有新版本** | The catalog reports a higher version; one-click update is available. |
+| **已是最新** | No newer version in the catalog. |
+| **未收录** | An update exists in the catalog but this plugin cannot drive it (see reasons below). |
+
+| Reason | Meaning |
+|---|---|
+| 软件目录未收录 | The app is not in the winget catalog (registry-only software), so its official update cannot be discovered or downloaded. |
+| 由应用商店管理 | MSIX / Store app — update it through Microsoft Store. |
+| 版本未知 | The installed version cannot be read (winget reports `Unknown`); updating is still allowed. |
+| 系统组件 | System component / runtime; not driven by this plugin by default. |
+
+---
+
+## Settings
+
+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). |
+| `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. |
+| `dryRun` | `false` | **Rehearsal mode**: download the vendor's full installer but never install it. |
+
+Everything above is editable from the plugin's own settings panel inside the settings page.
+The panel also accepts API calls:
+
+```bash
+curl -X POST -H "Content-Type: application/json" \
+  -d '{"confirm":true,"settings":{"dryRun":true}}' \
+  http://127.0.0.1:<port>/dsh-app-updater/settings
+```
+
+---
+
+## Safety boundaries
+
+- **Every write requires loopback + explicit confirmation**: `scan` / `update` / `cancel` /
+  `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.
+- **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
+  list registry apps, but cannot tell whether they are up to date.
+- No third-party npm dependencies: the host half uses Node built-ins only, the browser half
+  only the host-provided `react`.
+
+## 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) |
+| 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 |
+| POST | `/dsh-app-updater/settings` | `{confirm:true, settings:{...}}` |
+| POST | `/dsh-app-updater/open-downloads` | `{confirm:true}` open the download folder |
+
+## Install (from a checkout)
+
+```bash
+# from a local checkout
+dsh plugin --profile <profile> add file:/path/to/dsh-app-updater
+
+# or as a local link
+dsh plugin --profile <profile> add link:/path/to/dsh-app-updater
+```
+
+Then add `dsh-app-updater` to `dsh.profile.bundles` in the profile's `package.json`
+(the bundled `cordis.patch.yml` mounts the host half) and reload DSH.
+
+## Uninstall
+
+1. Remove `dsh-app-updater` from `dsh.profile.bundles` and from `dependencies` in the profile's `package.json`.
+2. Delete `<profile>/node_modules/dsh-app-updater`.
+3. Restart DSH; the data directory `%USERPROFILE%\.dsh\dsh-app-updater` can be removed as well.
+
+## Tests
+
+```bash
+node test/unit.mjs     # 36 checks: table parsing, version compare, manifest & switch 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
+```
+
+## Layout
+
+| File | Purpose |
+|---|---|
+| `lib/index.js` | Host half: HTTP routes, write gate, scan/update scheduling |
+| `lib/engine.js` | Inventory merge, vendor installer download, silent install, winget fallback, version re-check |
+| `lib/winget.js` | winget discovery/invocation, fixed-width table parsing (CJK-aware) |
+| `lib/registry.js` | Registry `Uninstall` enumeration (PowerShell, UTF-8) |
+| `lib/version.js` | Windows-style version comparison |
+| `lib/state.js` | Settings and state persistence (atomic writes) |
+| `lib/proc.js` | Child process runner (timeouts, cancellation, UTF-8) |
+| `lib/client.js` | Browser half: the settings page UI |
+| `CONTRACT.md` | Host ↔ client interface contract |
+
+## License
+
+MIT

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# dsh-app-updater — 应用更新（DSH 插件）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+检测本机**所有已安装的 Windows 应用**是否有新版本，并从各自**官网下载完整安装包**一键静默更新。
+检测过程**不需要打开被检测的软件**。
+
+入口：DeepSeek Harness → 设置 → **应用更新**
+
+## 安装
+
+```bash
+# 从源码仓库安装（复制即可）
+dsh plugin --profile web add github:19952730389/dsh-app-updater
+```
+
+发行 `.tgz` 见 [Releases](https://github.com/19952730389/dsh-app-updater/releases)：
+
+```bash
+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)
+![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)
+
+**简体中文** · [English](README.en.md) · [更新日志](CHANGELOG.md) · MIT
+
+---
+
+## 它到底做了什么
+
+| 步骤 | 实现 |
+|---|---|
+| ① 列出已装应用 | `winget list`（覆盖 winget 目录收录的软件 + 商店/MSIX 包）+ Windows 注册表三处 `Uninstall` 键（覆盖 winget 未收录的软件）。全程只读文件与注册表，不启动任何应用。 |
+| ② 判断有没有新版本 | `winget upgrade --include-unknown`：由 winget 官方软件目录给出「已装版本 → 可升级版本」，并与 ①的清单按 Id 合并。 |
+| ③ 一键更新 | `winget download` 把**发布方官网的完整安装包**下载到你指定的目录（下载时按清单核对 SHA-256），解析随包落盘的 winget 清单得到发布方自己的静默参数，再执行静默安装；安装完成后用 `winget list --id` 复核版本号。 |
+| ④ 失败兜底 | 若官网安装包被发布方重新签发导致哈希与目录记录不一致、或清单禁止直接下载，自动退回 `winget upgrade --id <id> --exact --silent`（同样是从官网拉取完整安装包，只是下载与安装过程交给 winget）。 |
+
+**「从对应官网下载」是真的官网**：安装包地址来自 winget 清单里的 `InstallerUrl`，例如
+- Git → `https://github.com/git-for-windows/git/releases/download/...`
+- CPU-Z → `https://download.cpuid.com/cpu-z/...`
+- 哔哩哔哩 → `https://dl.hdslb.com/...`
+- Chrome → `https://dl.google.com/dl/chrome/install/...`
+
+下载目录（默认 `%USERPROFILE%\Downloads\DSH App Updater`）里会同时留一份 `.yaml` 清单，
+里面有发布方声明的 `InstallerUrl` / `InstallerSha256` / `InstallerSwitches.Silent`，可以自行核对来源。
+
+---
+
+## 使用
+
+1. 打开 **设置 → 应用更新**。
+2. 点 **刷新检测**（不会自动跑后台任务；只有你点了才扫）。
+3. 列表默认按「有新版本优先」排序，可用搜索框和 **全部 / 仅可更新 / 未收录** 分段筛选。
+4. 勾选要更新的应用（或点 **全部更新** 一次处理当前筛选下所有可更新项），点行尾 **更新** 也可单个更新。
+5. 更新期间有进度条、当前应用名与逐条日志；**取消** 会停止尚未开始的项目。
+6. **打开下载目录** 可以在资源管理器中查看已下载的官网安装包。
+7. 同一页的 **插件设置** 面板里可以改下载目录、保留安装包、演练模式等开关（见「设置项」）。
+8. 表格列宽默认给足以完整显示应用名；**拖动表头右侧的分隔条** 可以调整该列宽度（双击恢复默认），
+   偏好记在浏览器本地，下次打开仍是你的宽度。
+
+### 状态含义
+
+| 状态 | 含义 |
+|---|---|
+| **有新版本** | 软件目录给出更高的版本号，可一键更新。 |
+| **已是最新** | 目录里没有更高版本。 |
+| **未收录** | 目录里找到了更新，但本插件无法驱动它更新（见下）。 |
+
+| 原因 | 含义 |
+|---|---|
+| 软件目录未收录 | 该软件不在 winget 目录里（例如只在注册表登记的国产软件），无法判断/下载官网更新。 |
+| 由应用商店管理 | MSIX / 商店应用，请用 Microsoft Store 更新。 |
+| 版本未知 | 应用当前版本读不出来（winget 显示 `Unknown`），仍然允许尝试更新。 |
+| 系统组件 | 系统组件/运行时，默认不建议由第三方驱动更新。 |
+
+---
+
+## 设置项
+
+状态文件：`%USERPROFILE%\.dsh\dsh-app-updater\state.json`
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `includeStoreApps` | `true` | 是否把商店（MSIX）应用列进来（只展示，不会被更新）。 |
+| `includeRegistryOnly` | `true` | 是否用注册表补齐 winget 未收录的应用（只展示，不能更新）。 |
+| `downloadDir` | 空 | 自定义安装包下载目录；空 = `%USERPROFILE%\Downloads\DSH App Updater`。 |
+| `keepInstallers` | `true` | 更新后保留安装包；`false` 则在安装完成后删掉该应用刚下载的包。 |
+| `hashFallbackUpgrade` | `true` | 下载失败时退回 `winget upgrade` 兜底。 |
+| `dryRun` | `false` | **演练模式**：只下载官网全量安装包、不执行安装。用来先看会装什么。 |
+
+用 API 改设置（等价于设置面板，适合脚本化）：
+
+```bash
+curl -X POST -H "Content-Type: application/json" \
+  -d '{"confirm":true,"settings":{"dryRun":true}}' \
+  http://127.0.0.1:<port>/dsh-app-updater/settings
+```
+
+`downloadDir` 会被校验：必须留空（用默认目录）或是绝对路径（`D:\Apps`）／UNC 路径（`\\server\share`），
+否则返回 `400` 并在面板里显示红字提示，不会把安装包写到意料之外的位置。
+
+---
+
+## 安全边界
+
+- **写操作全部要求本机来源 + 显式确认**：`scan` / `update` / `cancel` / `settings` / `open-downloads` 只接受 loopback 请求且必须带 `confirm:true`。
+- **不猜测静默参数**：优先用发布方在清单里声明的 `Silent` 参数；清单缺失时才按安装包类型用保守的默认开关。
+- **不静默提权**：需要管理员权限的安装包会正常弹出 UAC，由你决定是否放行。
+- **安装后复核版本**：更新完会重新查询一次版本并记录，日志里能看到「更新完成，当前版本 X」。
+- **不做系统组件更新**：`.NET` 运行时、VC++ 运行库等仍会列出来，但默认不作为一键更新的目标。
+- **只写自己的目录**：状态与日志写在 `~/.dsh/dsh-app-updater/`，不碰 profile 与宿主配置。
+
+---
+
+## 依赖
+
+- **Windows**（`winget.exe`，即 Microsoft「应用安装程序 / App Installer」）。没装 winget 时插件仍能列出注册表里的应用，但无法判断是否有新版本。
+- 不需要任何第三方 npm 依赖；宿主半身只用 Node 内置模块，浏览器半身只用宿主提供的 `react`。
+
+## 接口（宿主半身）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/dsh-app-updater/state.json` | 当前状态、应用清单、日志、设置 |
+| GET | `/dsh-app-updater/apps.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}` 取消未开始项 |
+| POST | `/dsh-app-updater/settings` | `{confirm:true, settings:{...}}` |
+| POST | `/dsh-app-updater/open-downloads` | `{confirm:true}` 打开下载目录 |
+
+## 安装（开发）
+
+```bash
+# 本地目录安装
+dsh plugin --profile <profile> add file:/path/to/dsh-app-updater
+
+# 或者用链接（开发时改代码即时生效）
+dsh plugin --profile <profile> add link:/path/to/dsh-app-updater
+```
+
+装好后把 `dsh-app-updater` 加进 profile `package.json` 的 `dsh.profile.bundles` 清单
+（包内自带的 `cordis.patch.yml` 会挂载宿主半身），然后重启 DSH 即可在设置页看到入口。
+
+> 桌面端（Electron 托管）的 `desktop` profile 不允许用 `dsh plugin` 直接改写，
+> 需要在 profile 的 `node_modules` 下建立指向本包的 junction 并手动补 `bundles` 与依赖。
+
+## 测试
+
+```bash
+node test/unit.mjs              # 36 项：定宽表格解析、版本比较、安装包清单与静默参数
+node test/render.mjs            # 32 项：设置面板、演练提示、列宽拖拽、请求体
+node test/harness.mjs --scan    # 用假 cordis ctx + 真 HTTP 把宿主半身跑起来
+```
+
+## 卸载
+
+1. 从 profile 的 `package.json` 里删掉 `dsh.profile.bundles` 中的 `dsh-app-updater` 与 `dependencies` 中的对应条目。
+2. 删除 `%USERPROFILE%\.dsh\profiles\<profile>\node_modules\dsh-app-updater`。
+3. 重启 DSH；数据目录 `%USERPROFILE%\.dsh\dsh-app-updater` 可自行删除。
+
+## 文件
+
+| 文件 | 作用 |
+|---|---|
+| `lib/index.js` | 宿主半身：HTTP 路由、写操作闸门、扫描/更新任务调度 |
+| `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（设置面板、可拖拽列宽、进度与日志） |
+| `CONTRACT.md` | 宿主 ↔ 客户端接口契约 |
+| `test/unit.mjs` | 解析器 / 版本 / 清单单测（36 项） |
+| `test/render.mjs` | 前端渲染与交互自测（32 项） |
+| `test/harness.mjs` | 宿主路由端到端 harness（假 ctx + 真 HTTP） |
+| `icon.svg` | 插件图标 |
+| `LICENSE` `CHANGELOG.md` `README.en.md` | MIT 许可证、更新日志、英文说明 |

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-app-updater 的 bundle 补丁层。
+#
+# 一行 insert 挂载宿主半身；浏览器半身由 package.json 的 dsh.client 声明，
+# 并绑定在 name 为裸包名的这一行上。
+- insert:
+    - id: dsh-app-updater
+      name: 'dsh-app-updater'
+      config: {}

package/icon.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128" role="img" aria-label="DSH 应用更新">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#5b9bff"/>
+      <stop offset="1" stop-color="#2f6f4f"/>
+    </linearGradient>
+    <linearGradient id="win" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#ffffff"/>
+      <stop offset="1" stop-color="#dbe7ff"/>
+    </linearGradient>
+  </defs>
+
+  <rect x="4" y="4" width="120" height="120" rx="28" fill="url(#bg)"/>
+
+  <!-- 应用窗口 -->
+  <rect x="26" y="30" width="76" height="58" rx="10" fill="url(#win)"/>
+  <rect x="26" y="30" width="76" height="16" rx="10" fill="#1f2937" opacity="0.82"/>
+  <circle cx="36" cy="38" r="3.2" fill="#f87171"/>
+  <circle cx="46" cy="38" r="3.2" fill="#fbbf24"/>
+  <circle cx="56" cy="38" r="3.2" fill="#34d399"/>
+  <rect x="36" y="54" width="34" height="5" rx="2.5" fill="#2f4f7a" opacity="0.55"/>
+  <rect x="36" y="64" width="48" height="5" rx="2.5" fill="#2f4f7a" opacity="0.3"/>
+  <rect x="36" y="74" width="26" height="5" rx="2.5" fill="#2f4f7a" opacity="0.3"/>
+
+  <!-- 下载箭头 -->
+  <path d="M64 60 L64 92" stroke="#ffffff" stroke-width="9" stroke-linecap="round"/>
+  <path d="M48 80 L64 96 L80 80" fill="none" stroke="#ffffff" stroke-width="9" stroke-linecap="round" stroke-linejoin="round"/>
+  <rect x="42" y="100" width="44" height="8" rx="4" fill="#ffffff" opacity="0.9"/>
+
+  <!-- 环形更新标记 -->
+  <path d="M92 44 A30 30 0 0 1 92 84" fill="none" stroke="#ffffff" stroke-width="7" stroke-linecap="round" opacity="0.85"/>
+  <path d="M88 78 L96 86 L88 92" fill="none" stroke="#ffffff" stroke-width="7" stroke-linecap="round" stroke-linejoin="round" opacity="0.85"/>
+</svg>