dsh-plugin 1.6.0 → 1.6.2

package/lib/http/routes.js

@@ -13,7 +13,7 @@ import { homedir, release } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { fetchViaCurl, gitLsRemote, probeUrl, systemProxy } from '../services/probe.js';
-import { activeTask, cancelTask, dumpLoaderEntries, getTask, githubRepoOf, githubTarget, globalNpmPackagesOf, hasQueuedTarget, installTargetOf, listPendingRestarts, readProfileArg, startPluginMutation, validPackageName } from '../services/install/install.js';
+import { activeTask, cancelTask, dumpLoaderEntries, getTask, githubRefOf, githubRepoOf, githubTarget, globalNpmPackagesOf, hasQueuedTarget, installTargetOf, listPendingRestarts, readProfileArg, startPluginMutation, validPackageName } from '../services/install/install.js';
 import { githubReleaseTarget } from '../services/install/release-target.js';
 import { recordInstalledVersion, recordResolvedNpmPackage, readInstalledVersions, removeInstalledVersion } from '../services/profile/installed-versions.js';
 import { isDshNpmPackageForRepo, resolveNpmPackage } from '../services/install/npm-resolve.js';
@@ -26,6 +26,7 @@ import { appendLog, clearLog, readLog, logFilePath, defaultLogFilePath, customLo
  * 不用 `/bin/sh -c`：Windows 无 /bin/sh，且 lsof/nohup 仅 POSIX 存在。
  * 由 `spawn(process.execPath, ['-e', SCRIPT, port], { detached, stdio:'ignore' })` 孵化，
  * 宿主进程被 kill 后仍能完成「停旧 → 等端口释放 → 拉起新 dsh web」。
+ * 端口探测不到监听进程时不再假装重启（记一行日志后退出，见脚本内注释）。
  */
 const HOST_RESTART_SCRIPT = String.raw `const C = require('node:child_process')
 const F = require('node:fs')
@@ -52,7 +53,16 @@ function findPids() {
   return String(out.stdout || '').split(/\s+/).filter(Boolean)
 }
 
-for (const pid of findPids()) {
+const targets = findPids()
+// 一个监听进程都没找到 = 端口探测本身就失败了（netstat 输出格式 / 本地化差异），
+// 旧宿主仍占着端口。此时再拉一个 dsh web 只会在日志里以 EADDRINUSE 静默退出，
+// 用户却看到「重启完成」——不制造这种假象，留一行可诊断的记录后退出。
+if (targets.length === 0) {
+  logLine('restart aborted: no listener found on port ' + port)
+  process.exit(0)
+}
+
+for (const pid of targets) {
   try {
     if (win) C.spawnSync('taskkill', ['/pid', pid, '/t', '/f'])
     else process.kill(Number(pid), 'SIGTERM')
@@ -65,6 +75,14 @@ let tries = 0
   setTimeout(waitForStop, 250)
 })()
 
+function logLine(msg) {
+  try {
+    const dir = P.join(O.homedir(), '.dsh', 'logs')
+    F.mkdirSync(dir, { recursive: true })
+    F.appendFileSync(P.join(dir, 'dsh-web-' + port + '.log'), '[' + new Date().toISOString() + '] ' + msg + '\n')
+  } catch {}
+}
+
 function startHost() {
   const dir = P.join(O.homedir(), '.dsh', 'logs')
   F.mkdirSync(dir, { recursive: true })
@@ -76,6 +94,13 @@ function startHost() {
   })
   child.unref()
 }`;
+/**
+ * 宿主是否由桌面应用壳托管（`ELECTRON_RUN_AS_NODE=1`：壳用 Electron 二进制以 Node 模式跑宿主）。
+ * 桌面端的宿主归应用壳管，插件重启不了它，也不该去 kill —— 详见 /restart 路由。
+ */
+export function isDesktopHost() {
+    return process.env.ELECTRON_RUN_AS_NODE === '1';
+}
 const PROFILE_RE = /^[A-Za-z0-9_-]+$/;
 const BODY_LIMIT_BYTES = 4 * 1024;
 const COMMAND_TIMEOUT_MS = 5 * 60 * 1000;
@@ -808,7 +833,10 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                     // githubRepoOf 先把各种 GitHub 地址归一成 owner/repo，让「输入地址即装」兼容粘贴完整链接。
                     const gitRepo = githubRepoOf(rawRepo);
                     const release = githubReleaseTarget(rawRepo);
-                    const repoTarget = gitRepo !== null && release === null ? githubTarget(gitRepo) : null;
+                    // 显式 pin 的 Git ref（`#tag` / `#commit`）是用户意图：保留它，且不让 npm 反查
+                    // 把这个精确修订换成 registry 上的默认版本（见 issue #130）。
+                    const pinnedRef = githubRefOf(rawRepo);
+                    const repoTarget = gitRepo !== null && release === null ? githubTarget(gitRepo, pinnedRef) : null;
                     let target = release?.target ?? repoTarget ?? (validPackageName(rawRepo) ? rawRepo : null);
                     if (target === null) {
                         sendJson(response, 400, { error: 'unsupported install target' });
@@ -848,7 +876,9 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                     // 通用机制，不针对具体插件。
                     // 反查本身计入「已尝试的安装方式」：组织 scope 与 GitHub 用户名不一致时仅凭
                     // 仓库名猜不到包名，失败提 Issue 时作者看到我们查过的命令就能直接指认正确包名。
-                    if (repoTarget !== null) {
+                    // 显式 pin 了 Git ref 时跳过 npm 反查：用户要的就是那个精确修订，
+                    // 不能用 registry 上的默认版本覆盖它（issue #130）。
+                    if (repoTarget !== null && pinnedRef === null) {
                         // 反查/记录统一用归一化后的 owner/repo（gitRepo），保证「输入完整链接」也走同一套 npm 反查
                         const repoIdentity = gitRepo ?? rawRepo;
                         const npmName = await resolveNpmPackage(repoIdentity, settings.npmRegistry);
@@ -916,7 +946,9 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                         // （见 issue #71）。握手失败时再用 curl 复核一次主页连通性：只有两者都不通
                         // 才判「网络不通」；仅握手失败（仓库不存在、私有仓库、需要凭据）放行，
                         // 交给后续预检与真实安装给出准确原因。
-                        const gitProbeTarget = repoTarget === null ? null : repoTarget.replace(/^git\+/, '');
+                        // 探针只握手仓库本身（去掉 git+ 前缀与 #ref 片段）：ls-remote 认的是仓库地址，
+                        // 带 ref 片段会干扰 URL 解析
+                        const gitProbeTarget = repoTarget === null ? null : repoTarget.replace(/^git\+/, '').replace(/#.*$/, '');
                         let net;
                         if (gitProbeTarget !== null) {
                             net = await gitLsRemote(gitProbeTarget, effectiveProxy, 6000);
@@ -1126,6 +1158,15 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
             handler: (request, response) => {
                 if (!requireTrustedPost(request, response))
                     return;
+                // 桌面端：宿主由应用壳托管，插件重启不了它。Windows 上 `taskkill /T` 会把发起
+                // 重启的助手一起结束（助手是宿主的子进程），壳再把这次外部 kill 判成宿主崩溃
+                // 弹「应用无法启动或已意外停止」；退一步说，脱离壳拉起的 `dsh web` 也服务不了
+                // 桌面 UI（缺壳注入的 desktop:boot）。故不 kill、不拉新宿主，由客户端改提示
+                // 用户从菜单/托盘退出后重新打开。
+                if (isDesktopHost()) {
+                    sendJson(response, 200, { ok: false, desktop: true });
+                    return;
+                }
                 // 当前宿主监听端口来自请求 Host 头（localhost:7923），解析失败回退 7923
                 const host = request.headers.host ?? '';
                 const portMatch = host.match(/:(\d+)$/);

package/lib/services/install/install.js

@@ -1,4 +1,4 @@
 export { addPendingRestart, clearPendingRestart, listPendingRestarts } from '../profile/pending-restart.js';
 export { dumpLoaderEntries, removeLoadedEntry } from '../loader.js';
-export { addAllowBuildsKey, githubRepoOf, githubTarget, globalNpmPackagesOf, installTargetOf, parseAllowBuildsKey, readProfileArg, validPackageName } from '../profile/profile.js';
+export { addAllowBuildsKey, githubRefOf, githubRepoOf, githubTarget, globalNpmPackagesOf, installTargetOf, parseAllowBuildsKey, readProfileArg, validPackageName } from '../profile/profile.js';
 export { activeTask, cancelTask, getTask, hasQueuedTarget, hasRunningTask, runPluginMutation, startPluginMutation } from './task-queue.js';

package/lib/services/install/preflight.js

@@ -17,7 +17,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { promisify } from 'node:util';
-import { githubRepoOf } from '../profile/profile.js';
+import { githubRefOf, githubRepoOf } from '../profile/profile.js';
 import { githubReleaseTarget } from './release-target.js';
 import { resolvePackageEntry } from './package-entry.js';
 const execFileAsync = promisify(execFile);
@@ -33,18 +33,10 @@ export async function preflightTarget(target) {
     if (source === null)
         return { ok: true, missing: null, name: null };
     const [owner, repo] = source.split('/');
-    let commit = '';
-    try {
-        const { stdout } = await execFileAsync('git', ['ls-remote', `https://github.com/${owner}/${repo}.git`, 'HEAD'], {
-            timeout: PREFLIGHT_TIMEOUT_MS,
-            maxBuffer: 1024 * 1024,
-        });
-        commit = stdout.split(/\s+/)[0] ?? '';
-    }
-    catch {
-        return { ok: true, missing: null, name: null };
-    }
-    if (!commit)
+    // 显式 pin 的 Git ref 要在它自己的修订上预检：默认分支常是 monorepo 根，与 pin 的发布包
+    // 形态不同，拿 HEAD 校验会把完整产物误判成缺入口文件（或反之）。无 pin 时仍查 HEAD。
+    const commit = await remoteCommit(owner, repo, githubRefOf(target));
+    if (commit === null)
         return { ok: true, missing: null, name: null };
     const dir = mkdtempSync(join(tmpdir(), 'dsh-preflight-'));
     try {
@@ -68,6 +60,29 @@ export async function preflightTarget(target) {
         rmSync(dir, { recursive: true, force: true });
     }
 }
+/**
+ * Resolve the commit to inspect: the pinned `ref` when given, otherwise the
+ * repository default branch (`HEAD`). A full commit SHA passes through as-is;
+ * annotated tags are peeled to their commit. Any git/network failure returns
+ * null and the caller falls back to "no preflight".
+ */
+async function remoteCommit(owner, repo, ref) {
+    if (ref !== null && /^[0-9a-f]{40}$/i.test(ref))
+        return ref;
+    try {
+        const { stdout } = await execFileAsync('git', ['ls-remote', `https://github.com/${owner}/${repo}.git`, ref ?? 'HEAD'], {
+            timeout: PREFLIGHT_TIMEOUT_MS,
+            maxBuffer: 1024 * 1024,
+        });
+        const lines = stdout.split(/\r?\n/).filter((line) => line !== '');
+        // Annotated tags list the tag object and the peeled commit (`<ref>^{}`): prefer the peel.
+        const chosen = lines.find((line) => line.endsWith('^{}')) ?? lines[lines.length - 1];
+        return chosen?.split(/\s+/)[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 function download(url, dest) {
     return new Promise((resolve, reject) => {
         const req = get(url, { timeout: PREFLIGHT_TIMEOUT_MS }, (res) => {

package/lib/services/profile/profile.js

@@ -50,11 +50,39 @@ export function profileFromArgv(argv, fallback = 'web') {
 export function profileDirectory(profile) {
     return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'profiles', profile);
 }
-/** Build a safe explicit HTTPS Git target, or null when the repo is unsafe. */
-export function githubTarget(repo) {
+/** Build a safe explicit HTTPS Git target, or null when the repo is unsafe.
+ *  When `ref` is given it is appended as a Git ref (`#tag` / `#commit`) so an
+ *  explicitly pinned revision reaches the installer instead of being dropped. */
+export function githubTarget(repo, ref) {
     if (typeof repo !== 'string' || !REPO_RE.test(repo))
         return null;
-    return `git+https://github.com/${repo}.git`;
+    const url = `git+https://github.com/${repo}.git`;
+    return ref === undefined || ref === null || ref === '' ? url : `${url}#${ref}`;
+}
+/**
+ * Extract a validated explicit Git ref (`#<ref>`) from a GitHub spec, or null.
+ * Only the fragment of a Git-style address qualifies — a pinned tag/commit is
+ * user intent and must survive target normalization, whereas `#…` on a plain
+ * web URL (`https://github.com/o/r#readme`) is a page anchor, not a ref.
+ * Git-style = `git+…` / `github:` / `git@…` / `…​.git` / bare `owner/repo`.
+ * Grammar mirrors a Git ref: no leading `.`/`-`, no `#`/whitespace.
+ */
+const GIT_REF_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+export function githubRefOf(value) {
+    if (typeof value !== 'string')
+        return null;
+    const input = value.trim();
+    const hash = input.indexOf('#');
+    if (hash <= 0)
+        return null;
+    const base = input.slice(0, hash);
+    if (githubRepoOf(base) === null)
+        return null;
+    const gitStyle = /^(?:git\+|github:|git@)/i.test(base) || /\.git$/i.test(base) || !base.includes('://');
+    if (!gitStyle)
+        return null;
+    const ref = input.slice(hash + 1);
+    return GIT_REF_RE.test(ref) ? ref : null;
 }
 /**
  * DSH 命令行前缀（官方唯一形式 `dsh plugin --profile <name> <add|update> <target>`）—— 提取其中的安装目标；

package/lib/types/http/routes.d.ts

@@ -1,5 +1,10 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { readProfileArg, type LoaderHandle } from '../services/install/install.ts';
+/**
+ * 宿主是否由桌面应用壳托管（`ELECTRON_RUN_AS_NODE=1`：壳用 Electron 二进制以 Node 模式跑宿主）。
+ * 桌面端的宿主归应用壳管，插件重启不了它，也不该去 kill —— 详见 /restart 路由。
+ */
+export declare function isDesktopHost(): boolean;
 export interface WebRoute {
     kind: 'exact';
     path: string;

package/lib/types/services/install/install.d.ts

@@ -18,5 +18,5 @@ export type { InstallResult, InstallTask, Invocation, PendingRestart, QueueItem
 export type { LoaderHandle } from '../loader.ts';
 export { addPendingRestart, clearPendingRestart, listPendingRestarts } from '../profile/pending-restart.ts';
 export { dumpLoaderEntries, removeLoadedEntry } from '../loader.ts';
-export { addAllowBuildsKey, githubRepoOf, githubTarget, globalNpmPackagesOf, installTargetOf, parseAllowBuildsKey, readProfileArg, validPackageName } from '../profile/profile.ts';
+export { addAllowBuildsKey, githubRefOf, githubRepoOf, githubTarget, globalNpmPackagesOf, installTargetOf, parseAllowBuildsKey, readProfileArg, validPackageName } from '../profile/profile.ts';
 export { activeTask, cancelTask, getTask, hasQueuedTarget, hasRunningTask, runPluginMutation, startPluginMutation } from './task-queue.ts';

package/lib/types/services/profile/profile.d.ts

@@ -12,8 +12,11 @@ export declare function readProfileArg(fallback?: string): string;
 export declare function profileFromArgv(argv: readonly string[], fallback?: string): string;
 /** Resolve a profile directory (`DSH_HOME` or `~/.dsh`). */
 export declare function profileDirectory(profile: string): string;
-/** Build a safe explicit HTTPS Git target, or null when the repo is unsafe. */
-export declare function githubTarget(repo: string): string | null;
+/** Build a safe explicit HTTPS Git target, or null when the repo is unsafe.
+ *  When `ref` is given it is appended as a Git ref (`#tag` / `#commit`) so an
+ *  explicitly pinned revision reaches the installer instead of being dropped. */
+export declare function githubTarget(repo: string, ref?: string | null): string | null;
+export declare function githubRefOf(value: string): string | null;
 export declare function installTargetOf(value: string): string;
 export declare function globalNpmPackagesOf(value: string): string[] | null;
 /** Extract an owner/repo identity from a catalog value or an installed Git spec. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "A community plugin marketplace for DeepSeek Harness, built to the official plugin spec — browse, search and install 10000+ human-curated community plugins without leaving the app. · DeepSeek Harness 社区插件市场（遵循官方开发规范）：10000+ 人工精选社区插件，每日更新。",
   "type": "module",
   "main": "lib/index.js",

package/src/client/components/PluginHubSection.tsx

@@ -311,16 +311,26 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
     if (!ok) setToast({ id: Date.now(), kind: 'revealFail' })
   }
 
-  /** 「立即重启」：POST 同源 /restart，宿主进程自杀重启；随后轮询服务恢复后整页刷新。 */
+  /** 「立即重启」：POST 同源 /restart，宿主进程自杀重启；随后轮询服务恢复后整页刷新。
+   *  桌面端宿主归应用壳管（服务端回 `desktop: true` 且不重启）：不轮询，改提示退出重开。 */
   const requestRestart = async () => {
     if (restarting) return
     setRestarting(true)
+    let desktop = false
     try {
       // 响应可能在宿主进程被 kill 前返回，也可能直接断连 —— 两种都属正常
-      await fetch('/dsh-plugin-hub/restart', { method: 'POST' })
+      const res = await fetch('/dsh-plugin-hub/restart', { method: 'POST' })
+      const data = await res.json() as { desktop?: boolean }
+      desktop = data.desktop === true
     } catch {
       /* 服务已终止，无需处理 */
     }
+    if (desktop) {
+      // 宿主不会重启，轮询等不到新服务：直接给出正确口径
+      setRestarting(false)
+      setToast({ id: Date.now(), kind: 'restartDesktop' })
+      return
+    }
     // 轮询同源端点，服务恢复后整页 reload（让新挂载的 bundle 完全初始化）
     let attempts = 0
     const poll = async () => {

package/src/client/components/modals/modals.tsx

@@ -503,8 +503,9 @@ export function Toast({ toast, t }: { toast: ToastState; t: Translate }) {
         : toast.kind === 'fail' ? t('installFail')
           : toast.kind === 'removed' ? t('uninstallDone')
             : toast.kind === 'revealFail' ? t('openFolderFail')
-              : t('uninstallFail')
-  const fail = toast.kind === 'fail' || toast.kind === 'removeFail' || toast.kind === 'revealFail'
+              : toast.kind === 'restartDesktop' ? t('toastRestartDesktop')
+                : t('uninstallFail')
+  const fail = toast.kind === 'fail' || toast.kind === 'removeFail' || toast.kind === 'revealFail' || toast.kind === 'restartDesktop'
   return h('div', {
     key: toast.id,
     className: fail ? `${styles.toast} ${styles.toastFail}` : styles.toast,

package/src/client/locales.ts

@@ -268,6 +268,8 @@ export const zh = {
   restartLater: '稍后重启',
   restarting: '正在重启…',
   restartHint: '重启会中断正在进行的安装/卸载任务，其进度将丢失。部分插件（如插件市场、顶层 bundle）需重启后才会生效。',
+  // 桌面端宿主归应用壳管、插件重启不了它：点「立即重启」时改提示用户退出重开
+  toastRestartDesktop: '桌面端的宿主由应用管理，请在应用菜单（或托盘）选择退出后重新打开，重启后生效',
   done: '完成',
   // 待重启：装完没重启的插件常驻提醒，直到宿主真正重启
   restartPendingHint: '安装成功，重启后生效',
@@ -650,6 +652,8 @@ export const en = {
   restartLater: 'Later',
   restarting: 'Restarting…',
   restartHint: 'Restarting interrupts any in-progress install / uninstall task — its progress will be lost. Some plugins (such as plugin markets / top-level bundles) only take effect after a restart.',
+  // Desktop: the app shell owns the host, so plugins cannot restart it — tell the user to quit and reopen
+  toastRestartDesktop: 'In the desktop app the host is managed by the app: quit from the app menu (or tray) and open it again — the change takes effect after that restart',
   done: 'Done',
   restartPendingHint: 'Installed — takes effect after restart',
   restartPendingHintUninstall: 'Removed — cleaned up after restart',

package/src/client/types.ts

@@ -77,7 +77,7 @@ export interface TaskState {
   lines: string[]
 }
 
-export type ToastKind = 'copied' | 'errCopied' | 'done' | 'fail' | 'removed' | 'removeFail' | 'revealFail'
+export type ToastKind = 'copied' | 'errCopied' | 'done' | 'fail' | 'removed' | 'removeFail' | 'revealFail' | 'restartDesktop'
 
 export interface ToastState {
   id: number

package/src/server/http/routes.ts

@@ -14,7 +14,7 @@ import { homedir, release } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { spawn, spawnSync } from 'node:child_process'
 import { fetchViaCurl, gitLsRemote, probeUrl, systemProxy } from '../services/probe.ts'
-import { activeTask, cancelTask, dumpLoaderEntries, getTask, githubRepoOf, githubTarget, globalNpmPackagesOf, hasQueuedTarget, installTargetOf, listPendingRestarts, readProfileArg, startPluginMutation, validPackageName, type LoaderHandle } from '../services/install/install.ts'
+import { activeTask, cancelTask, dumpLoaderEntries, getTask, githubRefOf, githubRepoOf, githubTarget, globalNpmPackagesOf, hasQueuedTarget, installTargetOf, listPendingRestarts, readProfileArg, startPluginMutation, validPackageName, type LoaderHandle } from '../services/install/install.ts'
 import { githubReleaseTarget } from '../services/install/release-target.ts'
 import { recordInstalledVersion, recordResolvedNpmPackage, readInstalledVersions, removeInstalledVersion } from '../services/profile/installed-versions.ts'
 import { isDshNpmPackageForRepo, resolveNpmPackage } from '../services/install/npm-resolve.ts'
@@ -28,6 +28,7 @@ import { appendLog, clearLog, readLog, logFilePath, defaultLogFilePath, customLo
  * 不用 `/bin/sh -c`：Windows 无 /bin/sh，且 lsof/nohup 仅 POSIX 存在。
  * 由 `spawn(process.execPath, ['-e', SCRIPT, port], { detached, stdio:'ignore' })` 孵化，
  * 宿主进程被 kill 后仍能完成「停旧 → 等端口释放 → 拉起新 dsh web」。
+ * 端口探测不到监听进程时不再假装重启（记一行日志后退出，见脚本内注释）。
  */
 const HOST_RESTART_SCRIPT = String.raw`const C = require('node:child_process')
 const F = require('node:fs')
@@ -54,7 +55,16 @@ function findPids() {
   return String(out.stdout || '').split(/\s+/).filter(Boolean)
 }
 
-for (const pid of findPids()) {
+const targets = findPids()
+// 一个监听进程都没找到 = 端口探测本身就失败了（netstat 输出格式 / 本地化差异），
+// 旧宿主仍占着端口。此时再拉一个 dsh web 只会在日志里以 EADDRINUSE 静默退出，
+// 用户却看到「重启完成」——不制造这种假象，留一行可诊断的记录后退出。
+if (targets.length === 0) {
+  logLine('restart aborted: no listener found on port ' + port)
+  process.exit(0)
+}
+
+for (const pid of targets) {
   try {
     if (win) C.spawnSync('taskkill', ['/pid', pid, '/t', '/f'])
     else process.kill(Number(pid), 'SIGTERM')
@@ -67,6 +77,14 @@ let tries = 0
   setTimeout(waitForStop, 250)
 })()
 
+function logLine(msg) {
+  try {
+    const dir = P.join(O.homedir(), '.dsh', 'logs')
+    F.mkdirSync(dir, { recursive: true })
+    F.appendFileSync(P.join(dir, 'dsh-web-' + port + '.log'), '[' + new Date().toISOString() + '] ' + msg + '\n')
+  } catch {}
+}
+
 function startHost() {
   const dir = P.join(O.homedir(), '.dsh', 'logs')
   F.mkdirSync(dir, { recursive: true })
@@ -79,6 +97,14 @@ function startHost() {
   child.unref()
 }`
 
+/**
+ * 宿主是否由桌面应用壳托管（`ELECTRON_RUN_AS_NODE=1`：壳用 Electron 二进制以 Node 模式跑宿主）。
+ * 桌面端的宿主归应用壳管，插件重启不了它，也不该去 kill —— 详见 /restart 路由。
+ */
+export function isDesktopHost(): boolean {
+  return process.env.ELECTRON_RUN_AS_NODE === '1'
+}
+
 export interface WebRoute {
   kind: 'exact'
   path: string
@@ -798,7 +824,10 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
           // githubRepoOf 先把各种 GitHub 地址归一成 owner/repo，让「输入地址即装」兼容粘贴完整链接。
           const gitRepo = githubRepoOf(rawRepo)
           const release = githubReleaseTarget(rawRepo)
-          const repoTarget = gitRepo !== null && release === null ? githubTarget(gitRepo) : null
+          // 显式 pin 的 Git ref（`#tag` / `#commit`）是用户意图：保留它，且不让 npm 反查
+          // 把这个精确修订换成 registry 上的默认版本（见 issue #130）。
+          const pinnedRef = githubRefOf(rawRepo)
+          const repoTarget = gitRepo !== null && release === null ? githubTarget(gitRepo, pinnedRef) : null
           let target: string | null = release?.target ?? repoTarget ?? (validPackageName(rawRepo) ? rawRepo : null)
           if (target === null) {
             sendJson(response, 400, { error: 'unsupported install target' })
@@ -837,7 +866,9 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
           // 通用机制，不针对具体插件。
           // 反查本身计入「已尝试的安装方式」：组织 scope 与 GitHub 用户名不一致时仅凭
           // 仓库名猜不到包名，失败提 Issue 时作者看到我们查过的命令就能直接指认正确包名。
-          if (repoTarget !== null) {
+          // 显式 pin 了 Git ref 时跳过 npm 反查：用户要的就是那个精确修订，
+          // 不能用 registry 上的默认版本覆盖它（issue #130）。
+          if (repoTarget !== null && pinnedRef === null) {
             // 反查/记录统一用归一化后的 owner/repo（gitRepo），保证「输入完整链接」也走同一套 npm 反查
             const repoIdentity = gitRepo ?? rawRepo
             const npmName = await resolveNpmPackage(repoIdentity, settings.npmRegistry)
@@ -904,7 +935,9 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
             // （见 issue #71）。握手失败时再用 curl 复核一次主页连通性：只有两者都不通
             // 才判「网络不通」；仅握手失败（仓库不存在、私有仓库、需要凭据）放行，
             // 交给后续预检与真实安装给出准确原因。
-            const gitProbeTarget = repoTarget === null ? null : repoTarget.replace(/^git\+/, '')
+            // 探针只握手仓库本身（去掉 git+ 前缀与 #ref 片段）：ls-remote 认的是仓库地址，
+            // 带 ref 片段会干扰 URL 解析
+            const gitProbeTarget = repoTarget === null ? null : repoTarget.replace(/^git\+/, '').replace(/#.*$/, '')
             let net: Awaited<ReturnType<typeof probeUrl>>
             if (gitProbeTarget !== null) {
               net = await gitLsRemote(gitProbeTarget, effectiveProxy, 6000)
@@ -1102,6 +1135,15 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
       path: '/dsh-plugin-hub/restart',
       handler: (request, response) => {
         if (!requireTrustedPost(request, response)) return
+        // 桌面端：宿主由应用壳托管，插件重启不了它。Windows 上 `taskkill /T` 会把发起
+        // 重启的助手一起结束（助手是宿主的子进程），壳再把这次外部 kill 判成宿主崩溃
+        // 弹「应用无法启动或已意外停止」；退一步说，脱离壳拉起的 `dsh web` 也服务不了
+        // 桌面 UI（缺壳注入的 desktop:boot）。故不 kill、不拉新宿主，由客户端改提示
+        // 用户从菜单/托盘退出后重新打开。
+        if (isDesktopHost()) {
+          sendJson(response, 200, { ok: false, desktop: true })
+          return
+        }
         // 当前宿主监听端口来自请求 Host 头（localhost:7923），解析失败回退 7923
         const host = request.headers.host ?? ''
         const portMatch = host.match(/:(\d+)$/)

package/src/server/services/install/install.ts

@@ -18,5 +18,5 @@ export type { InstallResult, InstallTask, Invocation, PendingRestart, QueueItem
 export type { LoaderHandle } from '../loader.ts'
 export { addPendingRestart, clearPendingRestart, listPendingRestarts } from '../profile/pending-restart.ts'
 export { dumpLoaderEntries, removeLoadedEntry } from '../loader.ts'
-export { addAllowBuildsKey, githubRepoOf, githubTarget, globalNpmPackagesOf, installTargetOf, parseAllowBuildsKey, readProfileArg, validPackageName } from '../profile/profile.ts'
+export { addAllowBuildsKey, githubRefOf, githubRepoOf, githubTarget, globalNpmPackagesOf, installTargetOf, parseAllowBuildsKey, readProfileArg, validPackageName } from '../profile/profile.ts'
 export { activeTask, cancelTask, getTask, hasQueuedTarget, hasRunningTask, runPluginMutation, startPluginMutation } from './task-queue.ts'

package/src/server/services/install/preflight.ts

@@ -17,7 +17,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pipeline } from 'node:stream/promises'
 import { promisify } from 'node:util'
-import { githubRepoOf } from '../profile/profile.ts'
+import { githubRefOf, githubRepoOf } from '../profile/profile.ts'
 import { githubReleaseTarget } from './release-target.ts'
 import { resolvePackageEntry } from './package-entry.ts'
 
@@ -44,17 +44,10 @@ export async function preflightTarget(target: string): Promise<PreflightResult>
   const source = githubRepoOf(target)
   if (source === null) return { ok: true, missing: null, name: null }
   const [owner, repo] = source.split('/')
-  let commit = ''
-  try {
-    const { stdout } = await execFileAsync('git', ['ls-remote', `https://github.com/${owner}/${repo}.git`, 'HEAD'], {
-      timeout: PREFLIGHT_TIMEOUT_MS,
-      maxBuffer: 1024 * 1024,
-    })
-    commit = stdout.split(/\s+/)[0] ?? ''
-  } catch {
-    return { ok: true, missing: null, name: null }
-  }
-  if (!commit) return { ok: true, missing: null, name: null }
+  // 显式 pin 的 Git ref 要在它自己的修订上预检：默认分支常是 monorepo 根，与 pin 的发布包
+  // 形态不同，拿 HEAD 校验会把完整产物误判成缺入口文件（或反之）。无 pin 时仍查 HEAD。
+  const commit = await remoteCommit(owner, repo, githubRefOf(target))
+  if (commit === null) return { ok: true, missing: null, name: null }
   const dir = mkdtempSync(join(tmpdir(), 'dsh-preflight-'))
   try {
     const tar = join(dir, 'pkg.tar.gz')
@@ -74,6 +67,28 @@ export async function preflightTarget(target: string): Promise<PreflightResult>
   }
 }
 
+/**
+ * Resolve the commit to inspect: the pinned `ref` when given, otherwise the
+ * repository default branch (`HEAD`). A full commit SHA passes through as-is;
+ * annotated tags are peeled to their commit. Any git/network failure returns
+ * null and the caller falls back to "no preflight".
+ */
+async function remoteCommit(owner: string, repo: string, ref: string | null): Promise<string | null> {
+  if (ref !== null && /^[0-9a-f]{40}$/i.test(ref)) return ref
+  try {
+    const { stdout } = await execFileAsync('git', ['ls-remote', `https://github.com/${owner}/${repo}.git`, ref ?? 'HEAD'], {
+      timeout: PREFLIGHT_TIMEOUT_MS,
+      maxBuffer: 1024 * 1024,
+    })
+    const lines = stdout.split(/\r?\n/).filter((line) => line !== '')
+    // Annotated tags list the tag object and the peeled commit (`<ref>^{}`): prefer the peel.
+    const chosen = lines.find((line) => line.endsWith('^{}')) ?? lines[lines.length - 1]
+    return chosen?.split(/\s+/)[0] ?? null
+  } catch {
+    return null
+  }
+}
+
 function download(url: string, dest: string): Promise<void> {
   return new Promise((resolve, reject) => {
     const req = get(url, { timeout: PREFLIGHT_TIMEOUT_MS }, (res) => {

package/src/server/services/profile/profile.ts

@@ -49,10 +49,36 @@ export function profileDirectory(profile: string): string {
   return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'profiles', profile)
 }
 
-/** Build a safe explicit HTTPS Git target, or null when the repo is unsafe. */
-export function githubTarget(repo: string): string | null {
+/** Build a safe explicit HTTPS Git target, or null when the repo is unsafe.
+ *  When `ref` is given it is appended as a Git ref (`#tag` / `#commit`) so an
+ *  explicitly pinned revision reaches the installer instead of being dropped. */
+export function githubTarget(repo: string, ref?: string | null): string | null {
   if (typeof repo !== 'string' || !REPO_RE.test(repo)) return null
-  return `git+https://github.com/${repo}.git`
+  const url = `git+https://github.com/${repo}.git`
+  return ref === undefined || ref === null || ref === '' ? url : `${url}#${ref}`
+}
+
+/**
+ * Extract a validated explicit Git ref (`#<ref>`) from a GitHub spec, or null.
+ * Only the fragment of a Git-style address qualifies — a pinned tag/commit is
+ * user intent and must survive target normalization, whereas `#…` on a plain
+ * web URL (`https://github.com/o/r#readme`) is a page anchor, not a ref.
+ * Git-style = `git+…` / `github:` / `git@…` / `…​.git` / bare `owner/repo`.
+ * Grammar mirrors a Git ref: no leading `.`/`-`, no `#`/whitespace.
+ */
+const GIT_REF_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/
+
+export function githubRefOf(value: string): string | null {
+  if (typeof value !== 'string') return null
+  const input = value.trim()
+  const hash = input.indexOf('#')
+  if (hash <= 0) return null
+  const base = input.slice(0, hash)
+  if (githubRepoOf(base) === null) return null
+  const gitStyle = /^(?:git\+|github:|git@)/i.test(base) || /\.git$/i.test(base) || !base.includes('://')
+  if (!gitStyle) return null
+  const ref = input.slice(hash + 1)
+  return GIT_REF_RE.test(ref) ? ref : null
 }
 
 /**