dsh-plugin-resolver 0.1.0 → 0.1.2

package/ABLATION.md

@@ -7,7 +7,7 @@ node test/ablation.mjs          # 人类可读报告
 node test/ablation.mjs --json   # 机器可读
 ```
 
-运行环境：`runtime=0.2.0-rc.2`（本仓库开发所对的宿主版本）；日期 2026-10-18。网络类数字随线路波动，量级结论稳定。
+运行环境：DSH 0.2.x（本仓库开发所对的宿主版本线）；日期 2026-10-18。网络类数字随线路波动，量级结论稳定。
 
 ## 汇总
 

package/BENCHMARK.md

@@ -71,6 +71,6 @@ node test/benchmark.mjs
 ## 4. 插件不能压缩的部分（诚实边界）
 
 - **pnpm 下载与编译时间**是物理成本：镜像安装仍要 ~13 s，源码构建仍要 ~2 分钟。插件省的是决策、试错、验证与上下文，不是 CPU/带宽。
-- **替换已加载插件**仍要重启宿主（`restart-required`）：这是 loader 模块缓存 + 打包 Electron 没有 Node 内部 loader 的硬边界，插件如实报出来，不伪装成功。
+- **替换已加载插件**仍要重启宿主（`restart-required`）：这是 loader 模块缓存 + 打包宿主没有 Node 内部 loader 的硬边界，插件如实报出来，不伪装成功。
 - **同名歧义**仍需要一次人类/上层的选择（`owner=`），插件故意不猜。
 - 目录是社区维护的第三方列表，插件只保证"按声明来源装对版本"，不做安全审计。

package/README.md

@@ -5,6 +5,7 @@
 
 [![test](https://github.com/sakikoTGW/dsh-plugin-resolver/actions/workflows/test.yml/badge.svg)](https://github.com/sakikoTGW/dsh-plugin-resolver/actions/workflows/test.yml)
 [![ablation](https://github.com/sakikoTGW/dsh-plugin-resolver/actions/workflows/ablation.yml/badge.svg)](https://github.com/sakikoTGW/dsh-plugin-resolver/actions/workflows/ablation.yml)
+[![npm](https://img.shields.io/npm/v/dsh-plugin-resolver?logo=npm)](https://www.npmjs.com/package/dsh-plugin-resolver)
 [![license](https://img.shields.io/github/license/sakikoTGW/dsh-plugin-resolver)](LICENSE)
 [![node](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](package.json)
 [![DSH](https://img.shields.io/badge/DSH-0.2.0--rc.2%2B-4d6bfe)](https://github.com/deepseek-ai/deepseek-harness)
@@ -20,13 +21,13 @@
 
 ## 为什么要它
 
-**场景**：给一台 DSH `0.2.0-rc.2` 装两个真实插件——`dsh-better-sidebar`（npm 上的 latest 要求更高内核）和 `dsh-browser`（6 个同名 owner、GitHub-only、还要本地构建扩展）。当时在 agent 侧，这是这样一串手工活：
+**场景**：给一台 DSH 装两个真实插件——`dsh-better-sidebar`（npm 上的 latest 不保证兼容当前内核）和 `dsh-browser`（6 个同名 owner、GitHub-only、还要本地构建扩展）。当时在 agent 侧，这是这样一串手工活：
 
 | 实际会发生的事 | 代价（真机实测） |
 |---|---|
 | 目录在 GitHub Pages 上，拉一次 6.4 MB | **91 s**，模型还得读一堆条目 |
 | 同一个名字有多个 owner（`dsh-browser` 有 6 个） | 靠猜，猜错就装错来源 |
-| `latest` 未必兼容当前内核（如 `0.28.0` 要 `^0.2.1-rc.1`，宿主是 `0.2.0-rc.2`） | 装上后启动预检把它静默禁用 |
+| `latest` 未必兼容当前内核（peer 线或 `engines.dsh` 可能高于宿主） | 装上后启动预检把它静默禁用 |
 | 直连 npmjs 慢 | 两次 **90 s 超时**，换镜像后 13.4 s |
 | GitHub-only 仓库不提交构建产物 | `dsh plugin add github:…` 装了个 `main` 指向不存在文件的包 |
 | 装完不知道有没有生效 | 需要另找手段回读 loader entry / 前端 boot 表 |
@@ -55,12 +56,12 @@ flowchart LR
 要求 **DSH `>=0.2.0-rc.2 <0.3.0`**（已在 `engines.dsh` 声明）。纯 JS、无构建、无 install 脚本，三种方式都不需要 `allowBuilds` 授权：
 
 ```sh
-# npm（官方推荐，发布后）
-dsh plugin --profile web add dsh-plugin-resolver
+# npm（已发布 0.1.2；profile 名以你的 DSH 安装为准）
+dsh plugin --profile <profile> add dsh-plugin-resolver
 # GitHub 源码安装（建议锁 commit）
-dsh plugin --profile web add github:sakikoTGW/dsh-plugin-resolver#<commit>
+dsh plugin --profile <profile> add github:sakikoTGW/dsh-plugin-resolver#<commit>
 # tarball
-npm pack && dsh plugin --profile web add ./dsh-plugin-resolver-0.1.0.tgz
+npm pack && dsh plugin --profile <profile> add ./dsh-plugin-resolver-0.1.2.tgz
 ```
 
 装完（宿主重启后最稳）直接说：
@@ -68,7 +69,7 @@ npm pack && dsh plugin --profile web add ./dsh-plugin-resolver-0.1.0.tgz
 > "帮我装 dsh-browser" → 它会先问/列出 6 个同名候选；
 > "装 dsh-builtin-browser" → 自动选到与你内核兼容的版本并装好。
 
-官方插件市场索引（需先打开实验性「自定义插件市场」，然后 `插件 → 发现 → 添加索引源`）：
+插件市场（Discover）索引（在插件页打开实验性「自定义插件市场」，然后 `插件 → 发现 → 添加索引源`）：
 
 ```text
 https://sakikoTGW.github.io/dsh-plugin-resolver/market/index.json
@@ -78,19 +79,18 @@ https://sakikoTGW.github.io/dsh-plugin-resolver/market/index.json
 
 ```text
 $ plugin_resolve dsh-builtin-browser
-target kind: npm   running DSH: 0.2.0-rc.2
+target kind: npm   running DSH: 0.2.1-rc.2
 package: dsh-builtin-browser@0.4.13
 install spec: dsh-builtin-browser@0.4.13
 registry: https://registry.npmmirror.com/
 notes:
-- newest of 39 published versions whose DSH peer range accepts 0.2.0-rc.2
+- newest published version whose DSH peer range accepts the running host
 ```
 
 ```text
 $ plugin_resolve dsh-better-sidebar
-package: dsh-better-sidebar@0.26.1
-skipped versions:
-- 0.28.0: @deepseek-ai/dsh-agent needs ^0.2.1-rc.1, host is 0.2.0-rc.2
+package: dsh-better-sidebar@0.28.0
+install spec: dsh-better-sidebar@0.28.0
 ```
 
 ## 四个工具
@@ -115,6 +115,20 @@ skipped versions:
 - **GitHub-only**：检出到 `$DSH_HOME/plugin-sources/<owner>__<repo>`，缺构建产物且声明了 `build` 时执行 `pnpm install` + `pnpm run build`，随后 `installBundle('link:<pkgDir>')`，已构建的检出直接复用；
 - **显式 spec**（`github:` / `link:` / `file:` / `https:`）：原样交给插件管理器。
 
+## 重启判定
+
+`plugin_install` 不再无条件要求重启；安装前后会比较：
+
+- `pluginManager.listBundles()` 的 bundle 集合
+- 已安装包运行时文件的 hash（排除 README / docs / 版本号）
+
+结果：
+
+- 无变化 / 仅版本号变化 / 管理器已就地应用 → `restart: not required`
+- bundle 新增、运行时代码变化、client 半变化 → `restart: required — <原因>`
+
+本插件自身的 `logic/` 改动可以按 mtime 热加载，不需要重启；新增 bundle 或宿主壳变化仍然必须重启。
+
 ## 结构：稳定壳 + 可热加载逻辑
 
 ```
@@ -128,7 +142,7 @@ logic/             目录 / 版本 / 兼容 / 安装编排（每次调用按 mti
 - **改 `logic/` 任何文件 → 下一次工具调用立即生效，不用重启宿主**
 - 只有改动工具定义层（`index.js` / `host/register.js`）才需要重启
 
-这是为打包桌面版设计的：它拿不到真 HMR 所需的 Node 内部模块加载器，但"重新 import 一个带新 query 的模块"完全可行。
+这是为无 HMR 的打包运行环境设计的：宿主拿不到真 HMR 所需的 Node 内部模块加载器，但"重新 import 一个带新 query 的模块"完全可行。
 
 ## 效果
 
@@ -150,7 +164,7 @@ node test/ablation.mjs    # 消融测试（无副作用）
 ## 测试与 CI
 
 ```sh
-npm test        # = selftest(19) + harness(10)
+npm test        # = selftest(25) + harness(10)
 npm run bench   # 基准
 npm run ablate  # 消融
 ```
@@ -163,10 +177,10 @@ npm run ablate  # 消融
 ## 已知限制
 
 - 兼容性以 npm 元数据里的 peer / `engines.dsh` 为准，宿主启动预检另有判断时以宿主为准；
-- **替换已加载插件**仍需要重启宿主（loader 模块缓存 + 打包 Electron 无 Node 内部 loader），插件会如实报 `restart-required`；
+- **替换已加载插件**仍需要重启宿主（loader 模块缓存 + 打包宿主无 Node 内部 loader）；`plugin_install` 会先比较安装前后的 bundle 集合与运行时文件 hash，只有真正变化时才报 `restart-required`；
 - 同名歧义不猜，需要调用方给 `owner=` 或完整 spec；
 - 目录是社区维护的第三方列表，插件只保证"按声明来源装对版本"，不做安全审计；
-- GitHub 源码构建依赖本机 `pnpm`（优先 `$DSH_HOME/.desktop-bin/pnpm*`）与 `tar`，大仓库首次构建较慢。
+- GitHub 源码构建依赖宿主环境里的 `pnpm`（PATH 或 `DSH_PNPM_PATH`）与 `tar`，大仓库首次构建较慢。
 
 ## License
 

package/logic/api.js

@@ -15,7 +15,7 @@
 const __v = new URL(import.meta.url).searchParams.get('v') ?? ''
 const __q = (name) => `./${name}${__v === '' ? '' : `?v=${encodeURIComponent(__v)}`}`
 const { baseName, loadCatalog, searchCatalog } = await import(__q('catalog.js'))
-const { installGithubSource, installRegistry, verifyInstall } = await import(__q('install.js'))
+const { installGithubSource, installRegistry, verifyInstall, capturePackageRuntime, decideRestart } = await import(__q('install.js'))
 const { resolveTarget } = await import(__q('resolve.js'))
 const { oneLine, stars } = await import(__q('util.js'))
 
@@ -122,6 +122,16 @@ export async function pluginInstall(ctx, manager, options, args) {
     let packageName = plan.name
     let steps = []
     let application = 'unknown'
+    let beforeRuntime = null
+    let bundlesBefore = []
+    if (plan.kind === 'npm' && typeof plan.name === 'string' && plan.name !== '') {
+      beforeRuntime = await capturePackageRuntime(plan.name).catch(() => null)
+    }
+    try {
+      bundlesBefore = (await manager.listBundles()).map((bundle) => bundle.name)
+    } catch {
+      bundlesBefore = []
+    }
 
     if (plan.kind === 'github') {
       const result = await installGithubSource(manager, plan, {
@@ -140,10 +150,11 @@ export async function pluginInstall(ctx, manager, options, args) {
       if (steps.length > 0) lines.push(`steps: ${steps.join(' → ')}`)
     } else {
       const { summary } = await installRegistry(manager, plan)
-      application = summary.application
+      const alreadyInstalled = /already-installed/i.test(summary.error ?? '')
+      application = alreadyInstalled ? 'applied' : summary.application
       if (packageName === null && summary.bundle) packageName = summary.bundle
-      lines.push(`install: ${summary.application} (${summary.stage})`)
-      if (summary.error) lines.push(`error: ${summary.error}`)
+      lines.push(alreadyInstalled ? 'install: already installed (no change)' : `install: ${summary.application} (${summary.stage})`)
+      if (summary.error && !alreadyInstalled) lines.push(`error: ${summary.error}`)
       if (summary.pendingBuilds.length > 0) {
         lines.push(`pending build scripts (needs approval): ${summary.pendingBuilds.join(', ')}`)
       }
@@ -163,14 +174,26 @@ export async function pluginInstall(ctx, manager, options, args) {
         lines.push(`- bundle: ${health.bundle.name}@${health.bundle.version ?? '?'} enabled=${health.bundle.enabled}`)
       }
       lines.push(`- package: ${packageName}${health.hasClient ? ` (client half via ${health.clientSource})` : ' (host-only)'}`)
-      const next = []
-      if (application === 'restart-required') {
-        next.push('restart DSH fully: replacing an already-mounted plugin cannot be hot-swapped safely')
+      let afterRuntime = null
+      let bundlesAfter = []
+      try {
+        afterRuntime = await capturePackageRuntime(packageName)
+        bundlesAfter = (await manager.listBundles()).map((bundle) => bundle.name)
+      } catch {
+        // keep the manager's own restart decision
       }
+      const restart = decideRestart({ before: beforeRuntime, after: afterRuntime, bundlesBefore, bundlesAfter, managerApplication: application })
+      lines.push('', `restart: ${restart.required ? 'required' : 'not required'} — ${restart.reason}`)
+      if (application === 'restart-required' && !restart.required) {
+        lines.push('- note: manager requested a restart, but runtime files are unchanged')
+      }
+      if (!restart.required && restart.versionChanged) lines.push('- version label updates after the next restart')
+      const next = []
+      if (restart.required) next.push(`restart DSH fully: ${restart.reason}`)
       if (health.entry?.fiberPhase === 'failed') next.push('host half failed to load; inspect the harness log for the error')
-      if (health.hasClient && application !== 'restart-required') next.push('client half exists: refresh the GUI (Ctrl+R) to load it')
-      if (health.entry?.fiberPhase === 'active' && !health.hasClient && application !== 'restart-required') {
-        next.push('host-only: no GUI refresh required')
+      if (restart.clientChanged) next.push('client half changed: refresh the GUI (Ctrl+R) to load it')
+      if (health.entry?.fiberPhase === 'active' && !health.hasClient && !restart.required && !restart.codeChanged) {
+        next.push('host-only: no restart or GUI refresh required')
       }
       if (next.length > 0) lines.push('', `next: ${next.join('; ')}`)
     }

package/logic/install.js

@@ -1,8 +1,8 @@
-// Reloadable module: local dependencies carry this module's `?v=` query.
-const __v = new URL(import.meta.url).searchParams.get('v') ?? ''
-const __q = (name) => `./${name}${__v === '' ? '' : `?v=${encodeURIComponent(__v)}`}`
-const { dshHome, dirExists, runProcess } = await import(__q('util.js'))
-const { registryBase } = await import(__q('resolve.js'))
+// Reloadable module: local dependencies carry this module's `?v=` query.
+const __v = new URL(import.meta.url).searchParams.get('v') ?? ''
+const __q = (name) => `./${name}${__v === '' ? '' : `?v=${encodeURIComponent(__v)}`}`
+const { dshHome, dirExists, runProcess } = await import(__q('util.js'))
+const { registryBase } = await import(__q('resolve.js'))
 /**
  * Installation: drive the profile's plugin manager, build GitHub-only sources,
  * and verify what actually landed.
@@ -17,6 +17,7 @@ const { registryBase } = await import(__q('resolve.js'))
 
 import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import path from 'node:path'
 
 /** Longest a source install may run before the tool reports a timeout. */
@@ -95,21 +96,138 @@ export async function installRegistry(manager, plan) {
  * @returns {Promise<any | undefined>}
  */
 export async function installedManifest(packageName) {
-  const candidates = []
-  if (process.env.DSH_PROFILE_DIR) candidates.push(process.env.DSH_PROFILE_DIR)
-  const home = process.env.DSH_HOME && process.env.DSH_HOME !== '' ? process.env.DSH_HOME : null
+  const packageDir = await installedPackageDir(packageName)
+  if (packageDir === undefined) return undefined
+  try {
+    return JSON.parse(await readFile(path.join(packageDir, 'package.json'), 'utf8'))
+  } catch {
+    return undefined
+  }
+}
+
+/** Candidate profile directories, most specific first. */
+function profileDirs() {
+  const dirs = []
+  if (process.env.DSH_PROFILE_DIR) dirs.push(process.env.DSH_PROFILE_DIR)
+  const home = process.env.DSH_HOME && process.env.DSH_HOME !== '' ? process.env.DSH_HOME : dshHome()
   if (home) {
-    const profile = process.env.DSH_PROFILE && process.env.DSH_PROFILE !== '' ? process.env.DSH_PROFILE : 'web'
-    candidates.push(path.join(home, 'profiles', profile))
+    const profile = process.env.DSH_PROFILE && process.env.DSH_PROFILE !== '' ? process.env.DSH_PROFILE : 'desktop'
+    for (const name of [profile, 'desktop', 'web']) dirs.push(path.join(home, 'profiles', name))
+  }
+  return [...new Set(dirs)]
+}
+
+/**
+ * Locate an installed package directory without assuming one profile layout.
+ * @param {string} packageName
+ * @returns {Promise<string | undefined>}
+ */
+export async function installedPackageDir(packageName) {
+  for (const profileDir of profileDirs()) {
+    const candidate = path.join(profileDir, 'node_modules', packageName)
+    if (existsSync(path.join(candidate, 'package.json'))) return candidate
   }
-  for (const profileDir of candidates) {
+  return undefined
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+/** Runtime files that decide whether the loaded code actually changed. */
+async function hashRuntimeFiles(dir) {
+  const files = []
+  async function walk(current) {
+    let entries
     try {
-      return JSON.parse(await readFile(path.join(profileDir, 'node_modules', packageName, 'package.json'), 'utf8'))
+      entries = await readdir(current, { withFileTypes: true })
     } catch {
-      // try the next candidate
+      return
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === 'test' || entry.name === 'tests' || entry.name === 'fixtures' || entry.name === 'examples' || entry.name === '.git' || entry.name === '.github') continue
+      if (/^(license|notice|readme)/i.test(entry.name)) continue
+      const abs = path.join(current, entry.name)
+      if (entry.isDirectory()) {
+        await walk(abs)
+        continue
+      }
+      if (!entry.isFile()) continue
+      const ext = path.extname(entry.name).toLowerCase()
+      if (ext === '.md' || ext === '.markdown' || ext === '.map' || ext === '.d.ts' || ext === '.pdb') continue
+      if (entry.name === 'package.json') continue
+      try {
+        files.push(`${path.relative(dir, abs).split(path.sep).join('/')}:${sha256(await readFile(abs))}`)
+      } catch {
+        // unreadable runtime file: treating it as absent is safer than crashing
+      }
     }
   }
-  return undefined
+  await walk(dir)
+  files.sort()
+  return files
+}
+
+/**
+ * Snapshot the installed package's runtime identity. README/docs and the
+ * version field are excluded: those changes do not alter loaded code.
+ * @param {string} packageName
+ * @returns {Promise<{version: string, hash: string, clientHash: string, hasClient: boolean, dir: string} | null>}
+ */
+export async function capturePackageRuntime(packageName) {
+  const dir = await installedPackageDir(packageName)
+  if (dir === undefined) return null
+  try {
+    const manifest = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8'))
+    const files = await hashRuntimeFiles(dir)
+    const meta = {
+      main: manifest.main ?? null,
+      exports: manifest.exports ?? null,
+      dsh: manifest.dsh ?? null,
+      dependencies: manifest.dependencies ?? {},
+      peerDependencies: manifest.peerDependencies ?? {},
+    }
+    const clientFiles = files.filter((line) => /(^|[/\\])[^/\\]*client[^/\\]*\.(?:js|mjs|cjs|ts):/i.test(line))
+    return {
+      version: String(manifest.version ?? ''),
+      hash: sha256(`${JSON.stringify(meta)}\n${files.join('\n')}`),
+      clientHash: sha256(clientFiles.join('\n')),
+      hasClient: Boolean(manifest.dsh?.client),
+      dir,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Decide whether install results really require a restart. Bundle additions and
+ * changed runtime/client files do; no-op reinstall and metadata-only version
+ * bumps do not. A manager-applied in-place change needs no restart either.
+ * @param {{before: any, after: any, bundlesBefore: string[], bundlesAfter: string[], managerApplication: string}} input
+ */
+export function decideRestart({ before, after, bundlesBefore, bundlesAfter, managerApplication }) {
+  const beforeNames = new Set(bundlesBefore ?? [])
+  const afterNames = new Set(bundlesAfter ?? [])
+  const added = [...afterNames].filter((name) => !beforeNames.has(name))
+  const removed = [...beforeNames].filter((name) => !afterNames.has(name))
+  if (added.length > 0 || removed.length > 0) {
+    return { required: true, reason: `bundle set changed (${[...added, ...removed].join(', ')})`, bundleChanged: true, codeChanged: true, clientChanged: false, versionChanged: false }
+  }
+  if (!before || !after) {
+    const required = managerApplication === 'restart-required'
+    return { required, reason: required ? 'manager requested a restart (no runtime snapshot)' : 'manager applied it in place', bundleChanged: false, codeChanged: false, clientChanged: false, versionChanged: false }
+  }
+  const versionChanged = before.version !== after.version
+  const codeChanged = before.hash !== after.hash
+  const clientChanged = Boolean(before.hasClient && after.hasClient && before.clientHash !== after.clientHash)
+  if (!codeChanged) {
+    return { required: false, reason: versionChanged ? 'runtime files are unchanged (version label only)' : 'runtime files are unchanged', bundleChanged: false, codeChanged: false, clientChanged: false, versionChanged }
+  }
+  if (managerApplication === 'applied') {
+    return { required: false, reason: 'manager applied the change in place', bundleChanged: false, codeChanged: true, clientChanged, versionChanged }
+  }
+  return { required: true, reason: clientChanged ? 'client half changed' : 'runtime code changed', bundleChanged: false, codeChanged: true, clientChanged, versionChanged }
 }
 
 /**
@@ -162,14 +280,8 @@ export async function verifyInstall(ctx, manager, packageName) {
 
 /** Locate a pnpm executable usable for a source build. */
 export function resolvePnpm() {
-  const home = dshHome()
-  const candidates =
-    process.platform === 'win32'
-      ? [path.join(home, '.desktop-bin', 'pnpm.cmd'), path.join(home, '..', '..', '.desktop-bin', 'pnpm.cmd')]
-      : [path.join(home, '.desktop-bin', 'pnpm')]
-  for (const candidate of candidates) {
-    if (existsSync(candidate)) return candidate
-  }
+  const explicit = process.env.DSH_PNPM_PATH
+  if (typeof explicit === 'string' && explicit !== '' && existsSync(explicit)) return explicit
   return process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm'
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-resolver",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Agent-facing DSH plugin resolver: search the catalog, pick a version the running DSH accepts, install (registry or GitHub-source build), and verify - no trial and error.",
   "type": "module",
   "main": "index.js",