dsh-plugin-update 0.1.1 → 0.2.0

package/README.md

@@ -1,290 +1,279 @@
-# dsh-plugin-update（更新包）
-
-可复用的更新系统装成的 npm 包：任何 DSH 插件照着文档能集成检查更新等功能。
-地图 #579 的一部分，本包包含更新核心、落盘与执行跑腿、读取器、宿主入口、客户端入口，集成步骤另见后续集成文档票（#585）。
-
-全程用词：更新系统指更新功能本身（引擎、对外接口、文档）；更新包指装着更新系统的这个 npm 包。电话指宿主对外提供的方法；落盘指宿主统一写本地文件的动作。
-
-两个名字不要搞混：本包自己的名字是 `dsh-plugin-update`（包自己叫什么）；目标包名参数是要检查更新的那个包是谁（默认是当前插件的旧包名 `dsh-mattpocock-skills-deck`）。新包查谁，由调用方传入目标包名决定。
-
-## 1. 安装
-
-```sh
-npm install dsh-plugin-update
-```
-
-要求 Node 22 或更高。当前版本 `0.1.0`。零运行时依赖。
-
-包还没公开发布时，这条命令装不上：先用本地路径代替（例如 `npm install ../dsh-plugin-update`），等包发布后才用上面的命令。发布前用 `npm view dsh-plugin-update` 查一次重名。
-
-## 2. 双入口
-
-包根即宿主侧入口（`package.json` 的 `exports` 只暴露包根与 `./package.json`）：
-
-- 包根（宿主侧用）：建更新能力、拼电话名、给调用方回电话名与处理器。宿主侧用标准模块写法，直接 `import`。
-- `dist/client.js`（客户端侧用）：电话名拼法、轮询时间口径、手工兜底命令形状。客户端侧**在构建期派生取值**（把本文件打包一次，把你自己的前缀代进去，得到三个电话名与轮询间隔的常量），面板界面不进包。
-
-## 3. 三步接入（双入口）
-
-下面例子假设你的插件标识是 `my-notes-plugin`、电话名前缀是 `notes`、要查更新的包也是 `my-notes-plugin`。
-把三处名字都换成你自己的，不要照抄 `wf`（`wf` 只是当前插件的历史取值，新插件传自己的前缀即隔离）。
-
-第 1 步：装包。
-
-```sh
-npm install dsh-plugin-update
-```
-
-要求 Node 22 或更高。零运行时依赖。包还没公开发布时先用本地路径代替（例如 `npm install ../dsh-plugin-update`），发布前用 `npm view dsh-plugin-update` 查一次重名。
-
-第 2 步：宿主侧接线（包根直接 `import`）。
-
-```js
-import { createHostUpdate } from 'dsh-plugin-update'
-
-const update = createHostUpdate(
-  { ctx, logCtx },
-  {
-    pluginId: 'my-notes-plugin',
-    prefix: 'notes',
-    targetPackageName: 'my-notes-plugin',
-  }
-)
-// 把 update.handlers 按键注册进自己的电话表，电话名从 update.phoneNames 读到，不要自己拼字符串。
-for (const [name, handler] of Object.entries(update.handlers)) {
-  registry.set(name, handler)
-}
-```
-
-这一步得到该插件的一组电话名与处理器：`notes.updateStatus`、`notes.updateCheck`、`notes.updateInstall`。
-单例复用键强制含插件标识，多插件不串内存状态与锁。其余配置（官方源、目录根、超时、轮询）全可选并带默认值，默认值等于现状，不传即走现状。
-
-第 3 步：客户端侧接线（构建期派生取值）。
-
-这一步的目标只有一句：**面板里不要写死电话名与轮询间隔，全部从本包派生出来**。做法是构建时把本包的客户端入口打包一次，把你的前缀代进去，在你的仓库里生成一个小文件，里面是三个电话名与轮询间隔的常量；面板直接引用这些常量。
-
-在第 2 步已有的配置上再补两处接线：
-
-```js
-// 生成出来的文件里长这样（名字随你，这里是本仓用的形状）：
-//   export const UPD_STATUS  = 'notes.updateStatus'
-//   export const UPD_CHECK   = 'notes.updateCheck'
-//   export const UPD_INSTALL = 'notes.updateInstall'
-//   export const UPD_POLL    = 1000
-//
-// 面板里这样用（宿主侧用同一套 phoneNames，两边必须同前缀）：
-host.call(UPD_STATUS, {})            // 查状态
-host.call(UPD_CHECK, {})             // 查新版
-host.call(UPD_INSTALL, { checkId, requestId })  // 装更新
-setInterval(readStatus, UPD_POLL)    // 轮询间隔
-```
-
-面板不再出现 `'notes.updateStatus'` 这样的字面量，也不再出现写死的 `1000`。以后要换前缀或换轮询间隔，只改本包的配置再重新派生一次，面板一行都不用动。
-
-派生要用的三样取值都在本包的客户端入口里，按名字取即可：
-
-```js
-buildClientPhoneNames('notes')  // 电话名拼法，与宿主侧同一套（前缀 + 点 + 动作名）
-CLIENT_POLL.defaultMs           // 面板轮询间隔默认值（1 秒）
-CLIENT_POLL.minMs               // 轮询间隔下限（250 毫秒，低于它要报错而不是静默取整）
-manualCommand({ ... })          // 手工兜底命令的形状，与宿主侧同一套政策
-```
-
-注意 `manualCommand` 一般不用你在面板里算：宿主每次回包都会带一条现成的手工命令（见第 9 节），面板拿到就展示，不要自己拼。
-
-**参考实现**：本包自带集成工具 `derive-client-values.mjs`，在你自己的插件仓库里跑一条命令即可（它的输入是包里的 `dist/client.js`，纯 JS，不需要你自己有 TypeScript）：
-
-```sh
-node node_modules/dsh-plugin-update/derive-client-values.mjs --prefix notes --out scripts/generated/updateClient.derived.js
-```
-
-生成的 `UPD_STATUS` / `UPD_CHECK` / `UPD_INSTALL` / `UPD_POLL` 就是上面那段面板示例要用的常量。以后换前缀或升级本包，重新跑一次这条命令即可。
-
-自定义项与注意点：
-
-- `--prefix` 必填，必须与宿主侧 `createHostUpdate` 传的 `prefix` 一致，否则面板调的电话名和宿主注册的电话名对不上。
-- `--out` 必填，且故意不给默认值：默认值会覆盖别人的文件，写错比报错更糟。
-- 工具用 `esbuild` 只做「打包一次」这件事（构建期使用，不引入运行期依赖）。esbuild 优先从本包自己的 `node_modules` 找，找不到再从你的仓库找；两处都没有时它会打印一句明确的安装提示，不静默失败。
-- `--dry-run` 只打印生成内容、不写文件，用来先看一眼再决定。
-
-客户端只做三件事：照前缀拼电话名、按间隔轮询查状态、装不上时展示手工兜底命令与待重启提示（见第 9、10 节）。
-`pluginId` 必填（非空字符串且不含路径分隔符），`prefix` 不传即 `wf`，新插件务必传自己的前缀。
-
-## 4. 配置默认值（规格 #591 冻结）
-
-| 配置键 | 默认 | 说明 |
-|---|---|---|
-| `pluginId` | 必填，无默认 | 非空字符串且不含路径分隔符 |
-| `prefix` | `wf` | 电话名前缀；新电话名 = 前缀 + 点 + 动作名 |
-| `targetPackageName` | `dsh-mattpocock-skills-deck` | 要检查更新的那个包是谁 |
-| `registryUrl` | `https://registry.npmjs.org/` | 官方源 |
-| `homeDir` | 现推导 | 环境变量 `DSH_HOME` 优先，否则家目录下 `.dsh` |
-| `checkTimeoutMs` | `10000` | 联网超时，须为有限大于 0 的数 |
-| `confirmationTtlMs` | `600000` | 凭证有效期，须为有限大于 0 的数 |
-| `installTimeoutMs` | `900000` | 安装时限，须为有限大于 0 的数 |
-| `panelPollMs` | `1000` | 面板轮询，不得小于 250 毫秒 |
-
-落盘目录按标识派生：家目录下 `updates` 加插件标识加使用范围短指纹，三文件名保持 `state.json`、`install.lock`、`before.json` 不变。标识取旧值时路径与旧原文一字不差（永久冻结）。读走双读（先新后旧），写只写新，旧路径只读保留。
-
-安装执行两条路由：桌面宿主走桌面服务（激活范围对不上宁可不装，转手工命令），普通宿主走子进程参数数组（不经 shell、不用 `PATH` 名、不按系统分支）。
-
-## 5. 冻结清单（动任一条即走破冰讨论）
-
-默认电话名、入参回参形状、配置写法（只经函数入参注入）、配方五键形状、事件字段基线（三事件各加必填 `pluginId`）、默认旧路径。加可选键只需同步改文档与白名单。完整结论见规格 #591。
-
-## 6. 门禁模板自查（#584）
-
-每条事件四样东西：事件名、级别（`error`、`warn`、`info`、`debug`）、允许字段（之外的键一律不记）、脱敏引用（`codes` 是截断或散列代号，`rules` 是具名正则名，都是引用名，命中只记规则名不记原文）。`kind` 只为计数检查服务：`resident` 常驻（始终落盘的轻量轨迹）、`ondemand` 按需（只在调试开关打开时记）、`selfmon` 自监控（日志管道自己的故障行），三类实际条数须与清单自报的 `counts` 逐项核对。`guard` 可选，一句话写清采样或节流，无特殊守卫不写。
-
-空模板见包内的 `event-list.template.json`（模板里的 `pluginId` 换成自己插件的标识）。调用方把清单拼成对象再传入，更新包不读盘：
-
-```js
-import { readFileSync } from 'node:fs'
-
-const myEventList = JSON.parse(readFileSync('./event-list.my-notes-plugin.json', 'utf8'))
-```
-
-路径形式请调用方自己读成对象再传入，更新包不读盘（字符串直接传给检查器会报错并提示先读成对象）。对象形式的清单当场验形状，错了直接报错（含中文说明），不静默修补；数组形式同样被拦下（只收对象，数组多半是把事件表直接当成了清单）。
-
-检查器经包根导出，都是纯函数，不新增日志事件：
-
-```js
-import { parseEventListManifest, checkEventFields, checkEventCounts } from 'dsh-plugin-update'
-
-const manifest = parseEventListManifest(myEventList)
-checkEventFields(manifest, 'host.call', ['method', 'pluginId'])
-checkEventCounts(manifest)
-```
-
-`parseEventListManifest` 验形状，`checkEventFields` 做字段白名单检查（未知事件名、未知字段键都算不通过，并把名单带回给调用方），`checkEventCounts` 做计数检查（增删事件必须同步改清单的 `counts`，否则这里变红）。本仓现有 55 事件对照仍以 `research/489-appendix.md` 与 `tests/verify-log-*.js` 为准，本包只给格式与检查器，不复刻那张表，免得两处对照要双写同步。
-
-第二家同机隔离自查（电话名、目录、锁互不串）：两家各传自己的插件标识与电话名前缀，电话名逐个不同，落盘目录与锁文件逐个不同，各拿各的锁互不阻塞。完整断言见包内 `tests/gate.test.mjs` 的双前缀一节，照抄即用。
-
-零运行时依赖与数组无 shell 同样在 `tests/gate.test.mjs` 里断言：`package.json` 无 `dependencies`，包内只引用相对路径与 `node:` 内建；执行器只走参数数组，不经 shell、不用 `PATH` 名、不按系统分支。
-
-## 7. 发布前 build 与门禁跑法
-
-发布前按顺序两步（演练只跑 dry-run，不真发）：
-
-```sh
-node packages/dsh-plugin-update/build.mjs
-cd packages/dsh-plugin-update && npm publish --dry-run
-```
-
-编译产物在 `dist` 下（9 个 JS：`client.js`、`commands.js`、`config.js`、`gate.js`、`host.js`、`ports.js`、`reader.js`、`service.js`、`store.js`），本地生成、不入库。发布白名单（`files`）共 4 项（`dist`、`event-list.template.json`、`README.md`、`LICENSE`，另加隐含的 `package.json`；`dist` 下 9 个 JS 全带上）。加新文件进包时同步改 `files` 并重跑 dry-run 确认文件数。
-
-门禁跑法（改包后全跑，退出码全 0 才算过）：
-
-```sh
-node --test packages/dsh-plugin-update/tests/*.test.mjs
-node tests/verify-update-regression.js
-node tests/verify-update-freshness.js
-node tests/verify-update-install.js
-node tests/verify-update-routes.js
-node tests/verify-update-panel.js
-node tests/verify-log-fields.js
-node tests/verify-log-count.js
-```
-
-## 8. 八种装不了原因（`blockedReason` 对照表）
-
-查状态返回的快照里有六个字段，其中 `canInstall` 说能不能装、`blockedReason` 说装不了的原因。
-能装时原因是空，不用看表；装不了时原因一定是下面八种之一，照表处理，不要自己猜。
-
-| 原因 | 中文含义 | 用户该做什么 |
-|---|---|---|
-| `unknown-profile` | 使用范围认不出（名字非法或目录不存在） | 检查使用范围名是否含特殊字符、目录是否还在；这种情形不给手工命令，先把范围修好 |
-| `source-install` | 当前是从源码装的，不是按版本号装的 | 这种情形不给手工命令；想走更新先按版本号重装一次 |
-| `invalid-installation` | 已装的包不完整（名字对不上、版本非法、入口文件缺失） | 重装当前版本，修好已装目录再查更新 |
-| `installation-changed` | 安装位置在使用中途变了（换了目录或换了包） | 重新打开宿主再查一次，让指纹重新绑定；还出现就重装 |
-| `pending-restart` | 新版已装到磁盘，正在跑的还是旧版（见第 10 节） | 重启宿主，让新版跑起来；这是正常终态，不是失败 |
-| `registry-conflict` | 本地声明的版本与磁盘实际版本互相矛盾 | 打开使用范围的清单文件，看目标包名那一行写的是不是版本号，改成版本号再试 |
-| `incompatible-node` | 新版要求的 Node 与当前运行的 Node 对不上 | 先升级 Node 到 22 或更高，再查更新 |
-| `recovery-required` | 上次安装被打断，留下一个半截任务 | 重新点一次安装；一直出现就按第 12 节排错 |
-
-面板拿到非空原因时，直接展示上表“用户该做什么”那一列的一句话，不要只展示英文原因本身。
-
-## 9. 手工兜底命令（自动装不上时给人复制执行）
-
-每次查状态与查新版都会顺带回一条手工命令（字段名 `manual`），能给则给、不能给则为空。
-为空是正常的两种情形：源码安装与认不出使用范围（上表前两行），此时不展示命令，只展示原因。
-
-命令形状固定（精确版本、官方源、`--save-exact`），例子里的名字是第 3 节那家自己的名字：
-
-```sh
-dsh plugin --profile my-web add --save-exact my-notes-plugin@1.2.3 --registry=https://registry.npmjs.org/
-```
-
-其中 `my-web` 是当前使用范围名，`my-notes-plugin@1.2.3` 是要装的目标包加精确版本。
-使用范围名含空格或特殊字符时命令里会自动加引号，复制整行执行即可。
-网络受限时用户可自行去掉 `--registry=` 尾巴走本地源；桌面宿主激活范围对不上时自动装会诚实失败，同样复制这条命令手工执行。
-
-宿主侧每次回包都带 `manual`，面板侧每次拿到都刷新展示，不要缓存旧命令。
-
-## 10. ⚠️ 待重启提示（显眼，必须做）
-
-`pending-restart` 不是失败，是“磁盘已是新版、正在跑的还是旧版”，必须重启宿主才生效。
-面板必须满足三条，少一条即不合格：
-
-1. 用显眼样式单独展示（例如顶部横幅加 ⚠️），不要只在日志或悬停提示里藏一行小字。
-2. 文案说清两件事：新版号是多少、重启后才生效。例子：`⚠️ 新版 1.2.3 已装好，正在跑的还是 1.2.2，重启宿主后生效。`
-3. 待重启期间不再提供安装按钮（快照里 `canInstall` 已为假），只提供重启指引与第 9 节的手工命令查询入口。
-
-判断条件只看快照：`blockedReason === 'pending-restart'` 即展示，`installedVersion !== runningVersion` 可作辅助校验，不要自己另起一套版本号比较。
-
-## 11. 轮询与凭证有效期可调
-
-四个时间都可在第 3 节第 2 步的配置里调，不传即走默认值（默认值等于现状，默认行为不变）。
-只卡下限，不设上限，越界直接抛错而不是静默取整。
-
-| 配置键 | 默认 | 下限 | 调大场景 |
-|---|---|---|---|
-| `checkTimeoutMs`（联网超时） | `10000`（10 秒） | 须为有限大于 0 的数 | 慢网络查新版总超时 |
-| `confirmationTtlMs`（凭证有效期） | `600000`（10 分钟） | 须为有限大于 0 的数 | 用户查完新版隔很久才点安装，凭证过期要重查 |
-| `installTimeoutMs`（安装时限） | `900000`（15 分钟） | 须为有限大于 0 的数 | 大包安装超过 15 分钟被终止 |
-| `panelPollMs`（面板轮询） | `1000`（1 秒） | 不得小于 250 毫秒 | 轮询太密想调疏，或想调密但不低于 250 毫秒 |
-
-例子（还是第 3 节那家自己的名字，只调两项，其余走默认）：
-
-```js
-const update = createHostUpdate(
-  { ctx, logCtx },
-  {
-    pluginId: 'my-notes-plugin',
-    prefix: 'notes',
-    targetPackageName: 'my-notes-plugin',
-    confirmationTtlMs: 20 * 60_000,
-    panelPollMs: 2000,
-  }
-)
-```
-
-客户端轮询间隔同样走 `assertPollInterval` 校验，小于 250 毫秒直接抛错。
-另有两处固定不变、不要当成可调项写进文档：查新版 2 秒内重复点击复用上次结果、安装执行终止宽限 3 秒。
-
-凭证过期（`check-expired`）是正常错误码，不是程序缺陷：用户拿着过期的检查编号点安装一定失败，面板此时重新调一次查新版、拿新凭证再提交即可。
-
-## 12. 排错
-
-按从常见到少见的顺序查，一次只动一处，动完重查一次状态。
-
-1. `pluginId` 报错说必填或含路径分隔符：换成自己插件的标识，非空且不含 `/` `\`。
-2. 电话名串台（两家插件收到对方的电话）：检查两家 `prefix` 是否相同，相同即改成不同的前缀；电话名永远从 `update.phoneNames` 读到，不要自己拼字符串。
-3. 面板轮询报错说小于 250 毫秒：把 `panelPollMs` 调到 250 或更大。
-4. 查新版总超时：先调大 `checkTimeoutMs`，再检查官方源地址是否写错、网络是否通官方源。
-5. 点安装报 `check-expired`：凭证过期了，重新查一次新版再点安装；不要重试旧编号。
-6. 点安装报 `update-busy`：同一使用范围同时只装一个，等当前任务结束再点；面板轮询看到任务离开 `installing`/`verifying` 即为空闲。
-7. 手工命令为空：对照第 8 节前两行（源码安装或认不出使用范围），先修范围再要命令。
-8. 装完版本号没变：先看是否 `pending-restart`（见第 10 节），是则重启宿主；不是则按第 8 节的表格查原因。
-9. 桌面宿主自动装失败但命令端能装：检查桌面当前激活的使用范围是不是插件所在的那一个，对不上时自动装一定诚实失败，复制第 9 节命令手工执行。
-10. 还定位不到：打开调试日志，按插件标识过滤 `host.call`、`host.call.fail`、`update.install.exec` 三个事件，看 `pluginId` 与 `route`、`exitCode` 字段；日志里不记命令与路径原文，只看枚举与数字即可定位。
-
-## 13. 新人三步自查（默认路径跑通清单）
-
-新人照第 3 节例子把名字换成自己的之后，按下面三条逐项打勾，全勾即默认路径跑通：
-
-1. 第 2 步调通：宿主启动不报错，`update.phoneNames` 读到自家前缀的三电话名（例如 `notes.updateStatus`），查状态返回六字段快照。
-2. 第 3 步调通：面板按间隔轮询到快照，能展示第 8 节的原因文案；有新版时安装按钮可用，无新版与待重启时按钮状态正确。
-3. 待重启与兜底可见：模拟一次 `pending-restart` 看到第 10 节横幅，模拟一次自动装失败看到第 9 节手工命令可复制执行。
-
-本节三条全绿即达到本票验收“新人照文档三步跑通默认路径”。
+# dsh-plugin-update
+
+给 DSH 插件加「检查更新 / 安装更新」能力的 npm 包。宿主侧一段接线，面板侧构建期派生取值，装不上时给用户一条可复制的手工命令。
+
+要求 Node 22 或更高，零运行时依赖。当前版本 `0.2.0`。
+
+装上它你会拿到三样东西：
+
+- **三个电话**：查状态（只读本地）、查新版（用户点了才联网一次）、装更新（拿凭证提交）。电话指宿主对外提供的方法。
+- **一套落盘**：任务状态、安装锁、回滚凭据，按「插件标识 + 使用范围」隔离，多插件互不干扰。
+- **面板要的派生取值**：电话名与轮询间隔，构建期从本包生成，面板里不写死。
+
+## 1. 安装
+
+```sh
+npm install dsh-plugin-update
+```
+
+把本包装成**你自己插件的依赖**即可（推荐）；老式的「把本包 vendor 进插件目录」也照旧可用。
+两种形态下，包都按**包名**在自己的 `node_modules` 链上找你的插件包——找到它，才能推出「插件装在哪、正在跑的是哪一版」。
+
+包还没公开发布时先用本地路径代替（例如 `npm install ../dsh-plugin-update`）。
+
+## 2. 三步接入
+
+下面假设你的插件标识是 `my-notes-plugin`、电话名前缀是 `notes`、要查更新的包也是 `my-notes-plugin`。
+三处名字都换成你自己的；`prefix` 不传即 `wf`（历史取值），新插件务必传自己的前缀，多插件靠它隔离。
+
+### 第 1 步：装包
+
+见第 1 节。
+
+### 第 2 步：宿主侧接线
+
+```js
+import { createHostUpdate } from 'dsh-plugin-update'
+
+const update = createHostUpdate(
+  { ctx, logCtx },
+  {
+    pluginId: 'my-notes-plugin',
+    prefix: 'notes',
+    targetPackageName: 'my-notes-plugin',
+  }
+)
+// 把处理器按键注册进自己的电话表；电话名从 update.phoneNames 读，不要自己拼字符串。
+for (const [name, handler] of Object.entries(update.handlers)) {
+  registry.set(name, handler)
+}
+```
+
+这一步得到三个电话名：`notes.updateStatus`、`notes.updateCheck`、`notes.updateInstall`。
+
+`pluginId` 必填（非空字符串，不含路径分隔符）。单例复用键强制含插件标识，多插件不串内存状态与锁。
+除 `pluginId` 之外的配置都可选并带默认值，不传即走默认（见第 3 节）。
+
+接线的第二个参数除 `{ ctx, logCtx }` 外还能给 `pluginManager`（显式交宿主管理器实例）与 `readerOverrides`。
+平时不用管；只有自动解析对不上目标包时（hoisted、多副本、开发态链接）才用得上它的 `targetPackageDir`：
+
+```js
+createHostUpdate(
+  { ctx, logCtx, readerOverrides: { targetPackageDir: '/abs/path/to/node_modules/my-notes-plugin' } },
+  { pluginId: 'my-notes-plugin', prefix: 'notes', targetPackageName: 'my-notes-plugin' }
+)
+```
+
+### 第 3 步：面板侧接线（构建期派生）
+
+目标只有一句：**面板里不要写死电话名与轮询间隔**。构建时用包内工具生成一个小文件：
+
+```sh
+node node_modules/dsh-plugin-update/derive-client-values.mjs --prefix notes --out scripts/generated/updateClient.derived.js
+```
+
+生成的常量直接在面板里用：
+
+```js
+// UPD_STATUS / UPD_CHECK / UPD_INSTALL / UPD_POLL 由上面那条命令生成
+host.call(UPD_STATUS, {})                        // 查状态
+host.call(UPD_CHECK, {})                         // 查新版
+host.call(UPD_INSTALL, { checkId, requestId })   // 装更新
+setInterval(readStatus, UPD_POLL)                // 轮询
+```
+
+派生工具的自定义项：
+
+- `--prefix` 必填，必须与宿主侧 `createHostUpdate` 传的 `prefix` 一致，否则面板调的电话名与宿主注册的对不上。
+- `--out` 必填，故意不给默认值：默认值会覆盖别人的文件。
+- `--dry-run` 只打印生成内容、不写文件。
+- 工具用 `esbuild` 打包一次（构建期使用，不引入运行期依赖）；找不到 esbuild 时打印安装提示，不静默失败。
+
+以后换前缀或升级本包，重新跑一次这条命令即可。
+
+### 升级本包（已经接入过的项目）
+
+宿主种类与安装出口都由本包自己探测和选择，**升级依赖即可，宿主侧与面板侧都不用改代码**：
+
+1. 依赖版本提到 `^0.2.0`。
+2. 重新装 / 发一版你自己的插件，让新依赖进当前使用范围（运行时用的是 `node_modules` 里那份）。
+3. 如果你自己接过一版宿主安装出口，把它删掉——它会挡在本包的路由前面。
+
+两处例外必须动代码（它们把自动探测挡住了）：显式传了 `readerOverrides.environmentKind`；显式传了与真实使用范围不符的 `profileDir` / `profileName`。
+
+`targetPackageName` 建议就是你自己的包名：使用范围目录按「装好的包住在 `<范围>/node_modules/<目标包名>`」反推。
+
+`0.2.0` 起目标包**按包名解析**（清单直解 → 入口反查 → `node_modules` 步行 → 自锚定兜底），`exports` 没导出 `.` 与 `./package.json` 的包也能命中。
+`0.1.x` 只能在本包被 vendor 进插件目录时找到目标包；以依赖形态安装时一键升级会永远不可用（面板显示假的 `installation-changed`）。
+
+## 3. 配置
+
+```js
+const update = createHostUpdate(
+  { ctx, logCtx },
+  {
+    pluginId: 'my-notes-plugin',
+    prefix: 'notes',
+    targetPackageName: 'my-notes-plugin',
+    confirmationTtlMs: 20 * 60_000,   // 只调这两项，其余走默认
+    panelPollMs: 2000,
+  }
+)
+```
+
+| 配置键 | 默认 | 说明 |
+|---|---|---|
+| `pluginId` | 必填，无默认 | 非空字符串，不含路径分隔符 |
+| `prefix` | `wf` | 电话名前缀；电话名 = 前缀 + 点 + 动作名 |
+| `targetPackageName` | `dsh-mattpocock-skills-deck` | 要检查更新的那个包是谁 |
+| `registryUrl` | `https://registry.npmjs.org/` | 官方源 |
+| `homeDir` | 现推导 | 环境变量 `DSH_HOME` 优先，否则家目录下 `.dsh` |
+| `checkTimeoutMs` | `10000` | 联网超时，须为有限大于 0 的数 |
+| `confirmationTtlMs` | `600000` | 凭证有效期，须为有限大于 0 的数 |
+| `installTimeoutMs` | `900000` | 安装时限，须为有限大于 0 的数 |
+| `panelPollMs` | `1000` | 面板轮询间隔，不得小于 250 毫秒 |
+
+配置只经函数入参注入，不读配置文件。越界直接抛错，不静默取整。
+
+落盘目录按标识派生：家目录下 `updates` 加插件标识加使用范围短指纹，三个文件名是 `state.json`、`install.lock`、`before.json`。读走双读（先新后旧），写只写新。
+标识取历史值 `dsh-mattpocock-skills-deck` 时，路径与旧版一字不差（升级不丢状态）。
+
+## 4. 安装是怎么执行的
+
+你不需要按宿主分支：包探测当前宿主，选它自己的安装出口。
+
+| 宿主 | 出口 | 说明 |
+|---|---|---|
+| 第三方 Desktop（发布 `desktopProfiles` / `desktopPnpm` 的那一支） | 桌面服务 `desktopPnpm.runPlugin` | 装进「当前激活的使用范围」；激活范围与本插件所在范围对不上时宁可不装 |
+| 官方桌面版（宿主进程内的插件管理器） | `pluginManager.installBundle` | 只收 `包名@精确版本`，不接受任何开关 |
+| 普通 DSH 宿主 | 自己起 `dsh plugin --profile <名> add …` | 参数数组直传；不经 shell、不用 `PATH` 上的命令名、不按系统分支 |
+
+三种出口都只装**精确版本**。第三方 Desktop 与普通宿主把官方源写进参数（`--registry=`），官方桌面版走管理器的 `registry` 选项。
+官方源不可达时诚实失败，不换源。装不上时宿主原话（截断到 300 字、去掉绝对路径）会写进任务说明 `job.message`，形如 `install-failed: <原话>`。
+
+时间口径：查新版 2 秒内重复点击复用上次结果；安装按 `installTimeoutMs` 计时，到点终止（官方桌面版先请求宿主取消，来不及就等它收尾再定成败）；终止宽限 3 秒。
+
+要显式覆盖出口（例如自己把宿主管理器实例交进来）：`createHostUpdate({ ctx, pluginManager })`，不传就从 `ctx` 现取。
+
+## 5. 用户会看到什么
+
+### 5.1 快照六字段
+
+查状态与查新版都返回同一份快照，恰好六个字段：
+
+| 字段 | 含义 |
+|---|---|
+| `installedVersion` | 磁盘上装着的版本 |
+| `runningVersion` | 正在跑的版本 |
+| `latestVersion` | 最近一次查新版带回来的版本（没查过为 null） |
+| `canInstall` | 现在能不能装 |
+| `blockedReason` | 装不了的原因（能装为 null） |
+| `job` | 当前任务（只读半程恒为 null） |
+
+### 5.2 八种装不了的原因
+
+面板拿到非空 `blockedReason` 时，直接展示下表「用户该做什么」那一列的一句话，不要只展示英文原因本身。
+
+| 原因 | 中文含义 | 用户该做什么 |
+|---|---|---|
+| `unknown-profile` | 使用范围或目标包认不出（名字非法、目录不存在、按包名找不到你的插件包） | 检查使用范围名与目录是否还在；插件以依赖形态接入却在别的 `node_modules` 树里（hoisted、多副本、开发态链接）时，让集成方传 `readerOverrides.targetPackageDir`；这种情形不给手工命令 |
+| `source-install` | 当前是从源码装的，不是按版本号装的 | 这种情形不给手工命令；想走更新先按版本号重装一次 |
+| `invalid-installation` | 已装的包不完整（名字对不上、版本非法、入口文件缺失） | 重装当前版本，修好已装目录再查更新 |
+| `installation-changed` | 安装位置在使用中途变了（换了目录或换了包） | 重新打开宿主再查一次；还出现就重装 |
+| `pending-restart` | 新版已装到磁盘，正在跑的还是旧版 | 重启宿主，让新版跑起来；这是正常终态，不是失败 |
+| `registry-conflict` | 本地声明的版本与磁盘实际版本互相矛盾 | 打开使用范围的清单文件，把目标包名那一行改成版本号再试 |
+| `incompatible-node` | 新版要求的 Node 与当前运行的对不上 | 先升级 Node 到 22 或更高，再查更新 |
+| `recovery-required` | 上次安装被打断，留下一个半截任务 | 重新点一次安装；一直出现就按第 6 节排错 |
+
+### 5.3 手工兜底命令
+
+每次查状态与查新版都会顺带回一条手工命令（字段名 `manual`），能给则给、不能给则为空。
+为空是正常的两种情形：源码安装、认不出使用范围（上表前两行），此时只展示原因。
+
+```sh
+dsh plugin --profile my-web add --save-exact my-notes-plugin@1.2.3 --registry=https://registry.npmjs.org/
+```
+
+使用范围名含空格或特殊字符时命令里会自动加引号，复制整行执行即可；网络受限时用户可以自行去掉 `--registry=` 走本地源。
+
+面板每次拿到回包都刷新展示这条命令，不要缓存旧的。
+
+### 5.4 ⚠️ 待重启提示（必须做）
+
+`pending-restart` 不是失败，是「磁盘已是新版、正在跑的还是旧版」。面板必须满足三条：
+
+1. 用显眼样式单独展示（例如顶部横幅加 ⚠️），不要只藏在日志或悬停提示里。
+2. 文案说清两件事：新版号是多少、重启后才生效。例如：`⚠️ 新版 1.2.3 已装好，正在跑的还是 1.2.2，重启宿主后生效。`
+3. 待重启期间不再提供安装按钮（快照里 `canInstall` 已为假），只给重启指引与手工命令入口。
+
+判断只看快照：`blockedReason === 'pending-restart'` 即展示；`installedVersion !== runningVersion` 只作辅助校验。
+
+### 5.5 轮询与凭证
+
+- 面板按 `panelPollMs` 轮询查状态；小于 250 毫秒直接抛错。
+- 装更新要带查新版的凭证（`checkId`）与本次请求编号（`requestId`）。凭证有过期时间，过期后重新查一次新版再提交。
+- 同一个 `requestId` 重复提交直接返回旧结果，不重装；同一使用范围同时只装一个，撞上会报 `update-busy`。
+
+## 6. 排错
+
+按从常见到少见的顺序查，一次只动一处，动完重查一次状态。
+
+1. `pluginId` 报必填或含路径分隔符：换成自己插件的标识，非空且不含 `/` `\`。
+2. 电话名串台（两家插件收到对方的电话）：检查两家 `prefix` 是否相同，相同即改成不同的前缀；电话名永远从 `update.phoneNames` 读。
+3. 面板轮询报错说小于 250 毫秒：把 `panelPollMs` 调到 250 或更大。
+4. 查新版总超时：先调大 `checkTimeoutMs`，再检查源地址是否写错、网络是否通。
+5. 点安装报 `check-expired`：凭证过期，重新查一次新版再点安装，不要重试旧编号。
+6. 点安装报 `update-busy`：同一使用范围同时只装一个，等当前任务离开 `installing`/`verifying` 再点。
+7. 手工命令为空：对照第 5.2 节前两行（源码安装或认不出使用范围），先修好再要命令。
+8. 装完版本号没变：先看是否 `pending-restart`（第 5.4 节），是则重启宿主；不是则按第 5.2 节的表查原因。
+9. 第三方 Desktop 自动装失败但命令能装：检查桌面当前激活的使用范围是不是插件所在的那一个；对不上时自动装一定诚实失败，复制第 5.3 节的命令手工执行。
+10. 官方桌面版（使用范围名 `desktop`）装不上：看任务里的 `message`，形如 `install-failed: <宿主原话>`，里面带着宿主的错误码（例如 `operation-error`）。`message` 可能带详情，**匹配请匹配前缀错误码，不要整串相等**；日志里这条路的路由是 `desktop-manager`。
+11. 还定位不到：打开调试日志，按插件标识过滤 `host.call`、`host.call.fail`、`update.install.exec` 三个事件，看 `pluginId` 与 `route`、`exitCode` 字段；日志里不记命令与路径原文。
+12. 以依赖形态接入后一直显示「安装位置在使用中途变了」（`installation-changed`）：`0.1.x` 的已知缺陷（拿「本包自己住在哪」推断目标包位置，依赖形态下恒失败）；升到 `0.2.0` 即修复。
+13. 报 `unknown-profile` 但使用范围名与目录都没问题：本包按包名找不到你的插件包。让集成方传 `readerOverrides.targetPackageDir`，或把本包装成插件包的依赖（别装到别的 `node_modules` 树里）。
+
+## 7. 接入自检清单
+
+照第 2 节把名字换成自己的之后，逐条打勾：
+
+1. 宿主启动不报错，`update.phoneNames` 读到自家前缀的三个电话名，查状态返回六字段快照。
+2. 面板按间隔轮询到快照，能展示第 5.2 节的原因文案；有新版时安装按钮可用，无新版与待重启时按钮状态正确。
+3. 模拟一次 `pending-restart` 能看到第 5.4 节的横幅，模拟一次自动装失败能看到第 5.3 节的命令可复制执行。
+4. 第二家同机隔离：两家各传自己的插件标识与电话名前缀，电话名、落盘目录、锁文件逐个不同，各拿各的锁互不阻塞。
+
+## 8. 包还导出什么
+
+**客户端入口**（`dist/client.js`，构建期打包用）：
+
+```js
+buildClientPhoneNames('notes')  // 电话名拼法，与宿主侧同一套（前缀 + 点 + 动作名）
+CLIENT_POLL.defaultMs           // 面板轮询默认值（1000）
+CLIENT_POLL.minMs               // 轮询下限（250，低于它要报错而不是静默取整）
+manualCommand({ ... })          // 手工兜底命令的形状，与宿主侧同一套政策
+```
+
+**事件清单检查器**（纯函数，不新增日志事件）：
+
+```js
+import { parseEventListManifest, checkEventFields, checkEventCounts } from 'dsh-plugin-update'
+
+const manifest = parseEventListManifest(myEventList)   // myEventList 是对象，先自己读盘
+checkEventFields(manifest, 'host.call', ['method', 'pluginId'])   // 字段白名单
+checkEventCounts(manifest)                                        // 计数与清单自报的 counts 对齐
+```
+
+事件清单的每条要写四样：事件名、级别（`error`/`warn`/`info`/`debug`）、允许字段（之外的键一律不记）、脱敏引用（`codes` 是截断或散列代号，`rules` 是具名正则名——都只记引用名，不记原文）。
+`kind` 分三类只为计数检查服务：`resident` 常驻、`ondemand` 按需、`selfmon` 自监控。空模板见包内的 `event-list.template.json`。
+清单要以**对象**传入：字符串或数组会被拦下并给出中文说明，不静默修补。
+
+**宿主侧工具**：
+
+```js
+resolveTargetPackage(name, { targetPackageDir })  // 按包名解析你的插件包；找不到返回 null（自己搭读取器或写测试时用）
+```
+
+## 9. 兼容与稳定性
+
+这些形状稳定，可以放心依赖：三个电话名与入参回参、快照六字段、任务公开形状、配置只经函数入参注入、安装配方五键、日志事件字段基线（三个事件各带必填 `pluginId`）、历史落盘路径。
+
+向后兼容的扩展：新增可选配置键、新增可选 `readerOverrides`（如 `targetPackageDir`）、新增宿主种类与路由取值。调用方不认新取值时按普通宿主处理即可，不会因此报错。

package/derive-client-values.mjs

@@ -110,8 +110,11 @@ if (!built.outputFiles || built.outputFiles.length !== 1) {
 }
 
 let body = Buffer.from(built.outputFiles[0].contents).toString('utf8').replace(/\r\n/g, '\n')
-// 注释里的路径归一：不同目录重跑时打包器会写出相对路径形态，统一成包名开头，保证消费方重跑零差异。
-body = body.replace(/^\/\/ (\.\.\/)+packages\//gm, '// packages/')
+// 注释里的路径归一：打包器写出的是「相对当前目录」的路径，换个目录重跑就会变成 ../ 开头，
+// 消费方重新派生一次就得到一份「只是注释不同」的 diff。这里把前导的 ../ 一律剥掉，
+// 路径注释固定成仓内形态，保证重跑零差异。
+// 只动 ../ 前缀、不动别的：本包零运行期依赖，产物里的注释只会是本包自己的文件。
+body = body.replace(/^\/\/ (?:\.\.\/)+/gm, '// ')
 
 // 打包器收尾会写一个模块级的 `export { ... };` 块。那个块拼进插件主文件闭包是语法错误
 // （闭包里只能是声明），所以拆掉它；被改名导出的符号在下面补回本名。

package/dist/client.js

@@ -1,4 +1,4 @@
-// AUTO-GENERATED by node packages/dsh-plugin-update/build.mjs — DO NOT EDIT. Source: packages/dsh-plugin-update/src/client.ts
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/client.ts
 import { buildPhoneNames, DEFAULT_PANEL_POLL_MS, MIN_PANEL_POLL_MS } from "./config.js";
 import { buildPhoneName, buildPhoneNames as buildPhoneNames2 } from "./config.js";
 import { manualCommand as manualCommand2 } from "./commands.js";

package/dist/commands.js

@@ -1,6 +1,7 @@
-// AUTO-GENERATED by node packages/dsh-plugin-update/build.mjs — DO NOT EDIT. Source: packages/dsh-plugin-update/src/commands.ts
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/commands.ts
 const PACKAGE_NAME = "dsh-mattpocock-skills-deck";
 const NPM_REGISTRY = "https://registry.npmjs.org/";
+const MANAGER_TARGET_RE = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
 const INSTALL_TIMEOUT_MS = 15 * 6e4;
 function validVersion(v) {
   return typeof v === "string" && /^\d+\.\d+\.\d+$/.test(v);
@@ -39,11 +40,21 @@ function installRecipe(input) {
   const version = input?.version;
   if (!name || !validVersion(version)) return null;
   const kind = input?.environmentKind;
-  if (kind !== "desktop" && kind !== "cli") return null;
+  if (kind !== "desktop" && kind !== "desktop-manager" && kind !== "cli") return null;
   const targetName = input?.targetPackageName ?? PACKAGE_NAME;
   const registry = input?.registryUrl ?? NPM_REGISTRY;
   const timeoutMs = input?.timeoutMs ?? INSTALL_TIMEOUT_MS;
   if (!targetName || !registry) return null;
+  if (kind === "desktop-manager") {
+    if (!MANAGER_TARGET_RE.test(targetName)) return null;
+    return {
+      route: "desktop-manager",
+      profileName: name,
+      version,
+      pluginArgs: ["add", `${targetName}@${version}`],
+      timeoutMs
+    };
+  }
   return {
     route: kind === "desktop" ? "desktop-service" : "cli-process",
     profileName: name,

package/dist/config.js

@@ -1,4 +1,4 @@
-// AUTO-GENERATED by node packages/dsh-plugin-update/build.mjs — DO NOT EDIT. Source: packages/dsh-plugin-update/src/config.ts
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/config.ts
 const DEFAULT_PREFIX = "wf";
 const PHONE_ACTIONS = ["updateStatus", "updateCheck", "updateInstall"];
 const DEFAULT_TARGET_PACKAGE = "dsh-mattpocock-skills-deck";

package/dist/gate.js

@@ -1,4 +1,4 @@
-// AUTO-GENERATED by node packages/dsh-plugin-update/build.mjs — DO NOT EDIT. Source: packages/dsh-plugin-update/src/gate.ts
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/gate.ts
 import { assertPluginId } from "./config.js";
 const EVENT_LEVELS = ["error", "warn", "info", "debug"];
 const EVENT_KINDS = ["resident", "ondemand", "selfmon"];

package/dist/host.js

@@ -1,8 +1,7 @@
-// AUTO-GENERATED by node packages/dsh-plugin-update/build.mjs — DO NOT EDIT. Source: packages/dsh-plugin-update/src/host.ts
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/host.ts
 import { realpath } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join, sep } from "node:path";
-import { fileURLToPath } from "node:url";
+import { sep } from "node:path";
 import {
   DEFAULT_CONFIRMATION_TTL_MS,
   DEFAULT_CHECK_TIMEOUT_MS,
@@ -13,10 +12,10 @@ import {
 import { manualCommand } from "./commands.js";
 import { validVersion } from "./service.js";
 import { createUpdateDiskPorts, createUpdateExecutor } from "./store.js";
-import { containingPackage, createUpdateReader, defaultHomeDir } from "./reader.js";
+import { createUpdateReader, defaultHomeDir, resolveProfileName, resolveTargetPackage } from "./reader.js";
 import { buildPhoneName, buildPhoneNames as buildPhoneNames2, resolveUpdateConfig as resolveUpdateConfig2 } from "./config.js";
 import { parseEventListManifest, checkEventFields, checkEventCounts } from "./gate.js";
-import { containingPackage as containingPackage2, defaultHomeDir as defaultHomeDir2, profileNameValid, registrySpec } from "./reader.js";
+import { containingPackage, defaultHomeDir as defaultHomeDir2, profileNameValid, registrySpec, resolveTargetPackage as resolveTargetPackage2 } from "./reader.js";
 import { createUpdateDiskPorts as createUpdateDiskPorts2, createUpdateExecutor as createUpdateExecutor2, pathsForUpdate, resolveCliEntry } from "./store.js";
 let sharedReader = null;
 let sharedReaderKey = "";
@@ -29,9 +28,22 @@ function ctxService(ctx, name) {
     return void 0;
   }
 }
-function detectEnvironmentKind(ctx) {
+function detectEnvironmentKind(ctx, profileName) {
   const profiles = ctxService(ctx, "desktopProfiles");
-  return profiles === void 0 || profiles === null ? "cli" : "desktop";
+  if (profiles !== void 0 && profiles !== null) return "desktop";
+  const manager = ctxService(ctx, "pluginManager");
+  if (hasInstallBundle(manager) && cliRefusesProfile(profileName)) return "desktop-manager";
+  return "cli";
+}
+function hasInstallBundle(manager) {
+  try {
+    return typeof manager?.installBundle === "function";
+  } catch {
+    return false;
+  }
+}
+function cliRefusesProfile(profileName) {
+  return typeof profileName === "string" && profileName.toLowerCase() === "desktop";
 }
 function watchDesktopPnpm(ctx) {
   try {
@@ -58,10 +70,11 @@ function hash8(s) {
     return "00000000";
   }
 }
-async function inferProfileDir(loaded, homeDirDefault, targetPackageName) {
+async function tryInferProfileDir(targetDir, targetPackageName) {
   try {
-    const dir = loaded && loaded.directory ? String(loaded.directory) : "";
-    const marker = `${sep}node_modules${sep}${targetPackageName}`;
+    const dir = String(targetDir || "");
+    if (!dir) return null;
+    const marker = `${sep}node_modules${sep}${String(targetPackageName || "").split("/").join(sep)}`;
     const at = dir.lastIndexOf(marker);
     if (at > 0) {
       const candidate = dir.slice(0, at);
@@ -73,24 +86,38 @@ async function inferProfileDir(loaded, homeDirDefault, targetPackageName) {
     }
   } catch {
   }
-  return join(homeDirDefault, "profiles", "web");
+  return null;
+}
+function unknownProfile() {
+  return Object.assign(new Error("unknown-profile"), { code: "unknown-profile" });
 }
 async function getSharedReader(pluginId, config, overrides = {}) {
   const env = overrides.env ?? process.env;
   const osHome = overrides.osHome ?? homedir();
   const homeDirDefault = defaultHomeDir(env, osHome);
   const targetPackageName = overrides.targetPackageName ?? config.targetPackageName;
-  const loaded = await containingPackage(fileURLToPath(import.meta.url), targetPackageName).catch(() => null);
+  const explicitTargetDir = typeof overrides.targetPackageDir === "string" && overrides.targetPackageDir ? String(overrides.targetPackageDir) : "";
+  const loaded = await resolveTargetPackage(targetPackageName, explicitTargetDir ? { targetPackageDir: explicitTargetDir } : {}).catch(
+    () => null
+  );
   const runningVersion = overrides.runningVersion ?? (loaded && validVersion(loaded.manifest.version) ? String(loaded.manifest.version) : null);
-  if (!runningVersion) throw Object.assign(new Error("unknown-profile"), { code: "unknown-profile" });
-  const profileDirInput = overrides.profileDir ?? await inferProfileDir(loaded, homeDirDefault, targetPackageName);
+  if (!runningVersion) throw unknownProfile();
+  let profileDirInput;
+  if (overrides.profileDir) {
+    profileDirInput = String(overrides.profileDir);
+  } else {
+    const anchorDir = (loaded && loaded.directory ? String(loaded.directory) : "") || explicitTargetDir;
+    const inferred = anchorDir ? await tryInferProfileDir(anchorDir, targetPackageName) : null;
+    if (!inferred) throw unknownProfile();
+    profileDirInput = inferred;
+  }
   const homeDirInput = overrides.homeDir ?? config.homeDir ?? homeDirDefault;
-  const environmentKind = overrides.environmentKind ?? detectEnvironmentKind(overrides.ctx);
+  const environmentKind = overrides.environmentKind ?? detectEnvironmentKind(overrides.ctx, resolveProfileName(overrides.profileName, profileDirInput));
   const checkTimeoutMs = overrides.checkTimeoutMs ?? config.checkTimeoutMs;
   const confirmationTtlMs = overrides.confirmationTtlMs ?? config.confirmationTtlMs;
   const installTimeoutMs = overrides.installTimeoutMs ?? config.installTimeoutMs;
   const registryUrl = overrides.registryUrl ?? config.registryUrl;
-  const key = `${pluginId}\0${config.prefix}\0${runningVersion}\0${profileDirInput}\0${overrides.profileName ?? ""}\0${homeDirInput}\0${overrides.runInstall ? "exec" : ""}\0${environmentKind}\0${targetPackageName}`;
+  const key = `${pluginId}\0${config.prefix}\0${runningVersion}\0${profileDirInput}\0${overrides.profileName ?? ""}\0${homeDirInput}\0${overrides.runInstall ? "exec" : ""}\0${environmentKind}\0${targetPackageName}\0${explicitTargetDir}`;
   if (sharedReader && sharedReaderKey === key) return sharedReader;
   const disk = overrides.readJob && overrides.writeJob ? null : createUpdateDiskPorts(homeDirInput, pluginId, profileDirInput);
   const defaultRun = createUpdateExecutor({
@@ -100,6 +127,7 @@ async function getSharedReader(pluginId, config, overrides = {}) {
     subprocess: () => overrides.subprocess ?? ctxService(overrides.ctx, "subprocess"),
     desktopPnpm: () => overrides.desktopPnpm ?? sharedDesktopPnpm,
     desktopProfiles: () => overrides.desktopProfiles ?? ctxService(overrides.ctx, "desktopProfiles"),
+    pluginManager: () => overrides.pluginManager ?? ctxService(overrides.ctx, "pluginManager"),
     runtimeExecutable: () => overrides.runtimeExecutable,
     runtimeExecArgs: () => overrides.runtimeExecArgs,
     cliEntry: () => overrides.cliEntry,
@@ -115,6 +143,7 @@ async function getSharedReader(pluginId, config, overrides = {}) {
     pluginId,
     profileName: overrides.profileName ?? void 0,
     homeDir: overrides.homeDir,
+    targetPackageDir: explicitTargetDir || void 0,
     env,
     osHome,
     fetchImpl: overrides.fetchImpl,
@@ -216,7 +245,7 @@ function createHostUpdate(deps = {}, configInput) {
   const ctx = deps.ctx ?? null;
   if (deps.desktopPnpm) sharedDesktopPnpm = deps.desktopPnpm;
   else watchDesktopPnpm(ctx);
-  const readerOverrides = { ...deps.readerOverrides ?? {}, ctx };
+  const readerOverrides = { ...deps.readerOverrides ?? {}, ctx, ...deps.pluginManager ? { pluginManager: deps.pluginManager } : {} };
   const phoneNames = buildPhoneNames(config.prefix);
   async function readStatus(args) {
     const reader = await getSharedReader(pluginId, config, {
@@ -264,7 +293,7 @@ export {
   buildPhoneNames2 as buildPhoneNames,
   checkEventCounts,
   checkEventFields,
-  containingPackage2 as containingPackage,
+  containingPackage,
   createHostUpdate,
   createUpdateDiskPorts2 as createUpdateDiskPorts,
   createUpdateExecutor2 as createUpdateExecutor,
@@ -275,5 +304,6 @@ export {
   profileNameValid,
   registrySpec,
   resolveCliEntry,
+  resolveTargetPackage2 as resolveTargetPackage,
   resolveUpdateConfig2 as resolveUpdateConfig
 };

package/dist/ports.js

@@ -1,5 +1,5 @@
-// AUTO-GENERATED by node packages/dsh-plugin-update/build.mjs — DO NOT EDIT. Source: packages/dsh-plugin-update/src/ports.ts
-const PORTS_SOURCE = "packages/dsh-plugin-update/src/ports.ts";
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/ports.ts
+const PORTS_SOURCE = "src/ports.ts";
 export {
   PORTS_SOURCE
 };

package/dist/reader.js

@@ -1,6 +1,7 @@
-// AUTO-GENERATED by node packages/dsh-plugin-update/build.mjs — DO NOT EDIT. Source: packages/dsh-plugin-update/src/reader.ts
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/reader.ts
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, realpath, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -37,6 +38,59 @@ async function containingPackage(filename, name) {
     directory = parent;
   }
 }
+async function packageAtIfNamed(directory, name) {
+  try {
+    const pkg = await packageAt(directory);
+    if (pkg.manifest && pkg.manifest.name === name) return pkg;
+  } catch {
+  }
+  return null;
+}
+async function resolveTargetPackage(targetName, opts = {}) {
+  const name = String(targetName || "");
+  if (!name) return null;
+  if (opts.targetPackageDir) return packageAtIfNamed(resolve(String(opts.targetPackageDir)), name);
+  const base = import.meta.url;
+  let req = null;
+  try {
+    req = createRequire(base);
+  } catch {
+    req = null;
+  }
+  if (req) {
+    try {
+      const pkg = await packageAtIfNamed(dirname(req.resolve(`${name}/package.json`)), name);
+      if (pkg) return pkg;
+    } catch {
+    }
+    try {
+      const entry = req.resolve(name);
+      const pkg = await containingPackage(entry, name);
+      if (pkg) return pkg;
+    } catch {
+    }
+  }
+  try {
+    let dir = dirname(fileURLToPath(base));
+    while (true) {
+      const pkg = await packageAtIfNamed(join(dir, "node_modules", name), name);
+      if (pkg) return pkg;
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+  }
+  try {
+    const pkg = await containingPackage(fileURLToPath(base), name);
+    if (pkg) return pkg;
+  } catch {
+  }
+  return null;
+}
+function resolveProfileName(profileName, profileDir) {
+  return profileName ?? basename(profileDir);
+}
 function profileNameValid(name) {
   return typeof name === "string" && name.length > 0 && Buffer.byteLength(name) <= 255 && !name.startsWith("-") && ![".", "..", "node_modules"].includes(name) && !/[\\/\x00-\x1f\x7f<>:"|?*]/u.test(name);
 }
@@ -99,7 +153,10 @@ function createUpdateReader(options) {
   const environmentKind = options.environmentKind ?? "cli";
   const targetPackageName = options.targetPackageName ?? "dsh-mattpocock-skills-deck";
   const registryUrl = options.registryUrl ?? "https://registry.npmjs.org/";
-  const loadedPackage = containingPackage(fileURLToPath(import.meta.url), targetPackageName).catch(() => null);
+  const loadedPackage = resolveTargetPackage(
+    targetPackageName,
+    options.targetPackageDir ? { targetPackageDir: options.targetPackageDir } : {}
+  ).catch(() => null);
   let boundIdentity;
   async function readInstalledReal() {
     const result = {
@@ -114,7 +171,7 @@ function createUpdateReader(options) {
       installationKey: null,
       eligible: false
     };
-    const profileName = options.profileName ?? basename(profileDirInput);
+    const profileName = resolveProfileName(options.profileName, profileDirInput);
     result.profileName = profileName;
     if (!profileNameValid(profileName)) {
       result.blockedReason = "unknown-profile";
@@ -145,6 +202,7 @@ function createUpdateReader(options) {
     result.installedVersion = typeof installed.manifest.version === "string" ? installed.manifest.version : null;
     result.packageValid = await validPackage(installed, targetPackageName);
     const loaded = await loadedPackage;
+    const loadedUnresolvable = loaded === null;
     const identity = `${homeDir}\0${profileDir}\0${profileName}\0${pluginId}`;
     const sameLoadedPackage = loaded?.directory === installed.directory && loaded?.manifest.version === installed.manifest.version;
     if (boundIdentity === void 0 && sameLoadedPackage && result.packageValid) boundIdentity = identity;
@@ -155,6 +213,7 @@ function createUpdateReader(options) {
       result.installationKey = null;
     }
     if (boundIdentity !== void 0 && boundIdentity !== identity) result.blockedReason = "installation-changed";
+    else if (loadedUnresolvable) result.blockedReason = "unknown-profile";
     else if (!sameLoadedPackage && boundIdentity === void 0) result.blockedReason = "installation-changed";
     else if (!result.packageValid) result.blockedReason = "invalid-installation";
     else if (result.sourceInstall) result.blockedReason = "source-install";
@@ -189,5 +248,7 @@ export {
   createUpdateReader,
   defaultHomeDir,
   profileNameValid,
-  registrySpec
+  registrySpec,
+  resolveProfileName,
+  resolveTargetPackage
 };

package/dist/service.js

@@ -1,4 +1,4 @@
-// AUTO-GENERATED by node packages/dsh-plugin-update/build.mjs — DO NOT EDIT. Source: packages/dsh-plugin-update/src/service.ts
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/service.ts
 const PACKAGE_NAME = "dsh-mattpocock-skills-deck";
 const NPM_REGISTRY = "https://registry.npmjs.org/";
 const CHECK_TIMEOUT_MS = 1e4;
@@ -275,13 +275,21 @@ function createUpdateCore(ports) {
       activeJobId = doing.id;
       await saveJob(doing);
       const env = await ports.readInstalled();
-      if (env.installedVersion !== job.targetVersion) throw updateError("install-failed");
-      if (env.blockedReason && env.blockedReason !== "pending-restart") throw updateError("install-failed");
+      if (env.installedVersion !== job.targetVersion) {
+        throw Object.assign(updateError("install-failed"), {
+          detail: `\u88C5\u5B8C\u6821\u9A8C\u6CA1\u8FC7\uFF1A\u78C1\u76D8\u4E0A\u662F ${env.installedVersion ?? "\u672A\u77E5"}\uFF0C\u76EE\u6807\u662F ${job.targetVersion ?? "\u672A\u77E5"}`
+        });
+      }
+      if (env.blockedReason && env.blockedReason !== "pending-restart") {
+        throw Object.assign(updateError("install-failed"), { detail: `\u88C5\u5B8C\u6821\u9A8C\u6CA1\u8FC7\uFF1A\u73AF\u5883\u62A5\u544A ${env.blockedReason}` });
+      }
       const done = { ...doing, state: "restart-required", message: null };
       await saveJob(done);
     } catch (error) {
       const code = error?.code;
-      const message = code === "installation-changed" || code === "registry-conflict" || code === "install-failed" ? String(code) : "install-failed";
+      const base = code === "installation-changed" || code === "registry-conflict" || code === "install-failed" ? String(code) : "install-failed";
+      const detail = error?.detail;
+      const message = typeof detail === "string" && detail ? `${base}: ${detail}` : base;
       const failedJob = { ...job, state: "failed", message, requestId: job.requestId ?? null };
       try {
         await saveJob(failedJob);

package/dist/store.js

@@ -1,4 +1,4 @@
-// AUTO-GENERATED by node packages/dsh-plugin-update/build.mjs — DO NOT EDIT. Source: packages/dsh-plugin-update/src/store.ts
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/store.ts
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, open, readFile, rename, realpath, stat, unlink, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, resolve } from "node:path";
@@ -294,6 +294,126 @@ async function runDesktopService(recipe, parts) {
   if (code !== 0) throw withExit(fail("install-failed"), code);
   return code;
 }
+const DETAIL_MAX = 300;
+const MANAGER_OK = ["applied", "restart-required", "overridden"];
+function withDetail(error, detail) {
+  if (detail) error.detail = detail;
+  return error;
+}
+const ABSOLUTE_PATH_RE = /[A-Za-z]:\\[^\s"']*|(^|\s)\/[^\s"']+/g;
+function sanitizeDetail(text) {
+  const flat = String(text ?? "").replace(/\s+/g, " ").trim();
+  if (!flat) return "";
+  const noPath = flat.replace(ABSOLUTE_PATH_RE, (_whole, lead) => `${lead || ""}<\u8DEF\u5F84>`);
+  return noPath.length > DETAIL_MAX ? `${noPath.slice(0, DETAIL_MAX)}\u2026` : noPath;
+}
+function detailText(error) {
+  if (typeof error === "string") return sanitizeDetail(error);
+  if (error instanceof Error) return sanitizeDetail(error.message);
+  if (error && typeof error === "object") {
+    const shape = error;
+    const code = typeof shape.code === "string" ? shape.code : "";
+    const said = typeof shape.diagnostic === "string" ? shape.diagnostic : typeof shape.message === "string" ? shape.message : "";
+    const line = [code, said].filter(Boolean).join(": ");
+    if (line) return sanitizeDetail(line);
+    try {
+      return sanitizeDetail(JSON.stringify(error));
+    } catch {
+      return sanitizeDetail(String(error));
+    }
+  }
+  return error === void 0 || error === null ? "" : sanitizeDetail(String(error));
+}
+function managerSpecOf(pluginArgs) {
+  if (!Array.isArray(pluginArgs) || pluginArgs.length !== 2) return null;
+  const [verb, spec] = pluginArgs;
+  if (verb !== "add" || typeof spec !== "string" || !spec || spec.startsWith("-")) return null;
+  return spec;
+}
+async function raceManager(running, timeoutMs, requestCancel) {
+  const settled = Promise.resolve(running).then((value) => ({ timedOut: false, value }));
+  if (!(typeof timeoutMs === "number" && timeoutMs > 0)) return await settled;
+  const TIMEOUT = /* @__PURE__ */ Symbol("install-timeout");
+  let timer = null;
+  const deadline = new Promise((settle) => {
+    timer = setTimeout(() => settle(TIMEOUT), timeoutMs);
+  });
+  let winner;
+  try {
+    winner = await Promise.race([settled, deadline]);
+  } finally {
+    if (timer !== null) {
+      try {
+        clearTimeout(timer);
+      } catch {
+      }
+    }
+  }
+  if (winner !== TIMEOUT) return winner;
+  await requestCancel();
+  return { timedOut: true };
+}
+async function settleWithin(promise, graceMs) {
+  if (!(typeof graceMs === "number" && graceMs > 0)) return null;
+  const EXPIRED = /* @__PURE__ */ Symbol("grace-expired");
+  let timer = null;
+  const deadline = new Promise((settle) => {
+    timer = setTimeout(() => settle(EXPIRED), graceMs);
+  });
+  try {
+    const winner = await Promise.race([promise, deadline]);
+    return winner === EXPIRED ? null : winner;
+  } finally {
+    if (timer !== null) {
+      try {
+        clearTimeout(timer);
+      } catch {
+      }
+    }
+  }
+}
+async function runDesktopManager(recipe, parts) {
+  try {
+    const manager = part(parts.pluginManager ?? null);
+    if (!manager || typeof manager.installBundle !== "function") throw fail("install-failed");
+    const spec = managerSpecOf(recipe.pluginArgs);
+    if (!spec) throw fail("install-failed");
+    const requestId = randomUUID();
+    const registry = part(parts.registryUrl ?? "");
+    const options = { requestId };
+    if (typeof registry === "string" && registry) options.registry = registry;
+    const running = Promise.resolve(manager.installBundle(spec, options));
+    const outcome = await raceManager(running, recipe.timeoutMs, async () => {
+      const cancel = manager.cancelInstall;
+      if (typeof cancel !== "function") return "not-running";
+      try {
+        const answer = await cancel.call(manager, requestId);
+        const status = answer && typeof answer.status === "string" ? answer.status : "";
+        return status === "cancelled" || status === "too-late" ? status : "not-running";
+      } catch {
+        return "not-running";
+      }
+    });
+    let result;
+    if (!outcome.timedOut) result = outcome.value;
+    else {
+      const settled = await settleWithin(running, TERMINATION_GRACE_MS);
+      if (!settled) {
+        void running.catch(() => {
+        });
+        throw withDetail(fail("install-failed"), "\u5B89\u88C5\u8D85\u65F6\uFF0C\u5DF2\u8BF7\u6C42\u5BBF\u4E3B\u53D6\u6D88");
+      }
+      result = settled;
+    }
+    const application = result && typeof result.application === "string" ? result.application : "";
+    if (MANAGER_OK.includes(application)) return 0;
+    if (application === "cancelled") throw withDetail(fail("install-failed"), "\u5B89\u88C5\u5DF2\u88AB\u53D6\u6D88");
+    throw withDetail(fail("install-failed"), detailText(result && result.error !== void 0 ? result.error : `application: ${application || "unknown"}`));
+  } catch (error) {
+    if (error?.code === "install-failed") throw error;
+    throw withDetail(fail("install-failed"), detailText(error));
+  }
+}
 async function runCliProcess(recipe, parts) {
   const executable = part(parts.runtimeExecutable) || (typeof process !== "undefined" ? process.execPath : "");
   const execArgs = part(parts.runtimeExecArgs) ?? (typeof process !== "undefined" && Array.isArray(process.execArgv) ? process.execArgv : []);
@@ -313,6 +433,11 @@ async function runCliProcess(recipe, parts) {
   if (outcome.timedOut || outcome.exitCode !== 0) throw withExit(fail("install-failed"), outcome.exitCode);
   return outcome.exitCode;
 }
+const INSTALL_RUNNERS = {
+  "desktop-service": runDesktopService,
+  "desktop-manager": runDesktopManager,
+  "cli-process": runCliProcess
+};
 function createUpdateExecutor(parts = {}) {
   return async function runInstall(args = {}) {
     const recipe = installRecipe({
@@ -327,11 +452,17 @@ function createUpdateExecutor(parts = {}) {
     let exitCode = null;
     try {
       if (!recipe) throw fail("install-failed");
-      exitCode = recipe.route === "desktop-service" ? await runDesktopService(recipe, parts) : await runCliProcess(recipe, parts);
+      const runner = INSTALL_RUNNERS[recipe.route] ?? null;
+      if (!runner) throw fail("install-failed");
+      exitCode = await runner(recipe, parts);
       emitInstall(parts, recipe, true, exitCode, Date.now() - startedAt);
     } catch (error) {
       emitInstall(parts, recipe, false, error?.exitCode ?? exitCode, Date.now() - startedAt);
-      throw Object.assign(fail("install-failed"), { debug: String(error?.stack || error) });
+      const detail = error?.detail;
+      throw Object.assign(fail("install-failed"), {
+        debug: String(error?.stack || error),
+        ...typeof detail === "string" && detail ? { detail } : {}
+      });
     }
   };
 }

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "dsh-plugin-update",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "可复用的更新系统装成的 npm 包：任何 DSH 插件照文档能集成检查更新等功能（地图 #579）",
   "license": "MIT",
   "author": "王辰浩",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FeatherHunter/dsh-plugin-update.git"
+  },
   "engines": {
     "node": ">=22"
   },
@@ -26,9 +30,12 @@
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
     "build": "node build.mjs",
+    "prepack": "npm run build",
+    "pretest": "npm run build",
     "test": "node --test tests/*.test.mjs"
   },
   "devDependencies": {
+    "esbuild": "^0.28.2",
     "typescript": "5.6.3"
   }
 }