ygc-dsh-plugin-autoupdate 0.6.0 → 0.7.0

package/client.js

@@ -179,7 +179,9 @@ function makePanel(React) {
 
     const plugins = Array.isArray(snap.plugins) ? snap.plugins : [];
     const registryPlugins = plugins.filter((p) => p.kind === 'registry');
-    const otherPlugins = plugins.filter((p) => p.kind !== 'registry');
+    // git 与 registry 一样参与自动更新，只是比的是 commit 而不是版本号
+    const gitPlugins = plugins.filter((p) => p.kind === 'git');
+    const otherPlugins = plugins.filter((p) => p.kind !== 'registry' && p.kind !== 'git');
     const available = plugins.filter((p) => p.updateAvailable);
     const ready = available.filter((p) => !p.waitMs);
 
@@ -321,6 +323,7 @@ function makePanel(React) {
     );
 
     const pluginRow = (plugin) => {
+      const isGit = plugin.kind === 'git';
       const tone = plugin.updateAvailable
         ? plugin.waitMs
           ? 'pau-tag-warn'
@@ -333,7 +336,21 @@ function makePanel(React) {
         : plugin.latestError
           ? '查询失败'
           : '已是最新';
-      const showLatest = plugin.latest && plugin.latest !== plugin.version;
+      // git 来源没有版本号可比：当前版本只认 commit，「最新」也只写短 sha
+      const currentCommit = plugin.git && plugin.git.commit ? String(plugin.git.commit).slice(0, 10) : '';
+      const showLatest = isGit
+        ? Boolean(plugin.latest && plugin.latest !== currentCommit)
+        : Boolean(plugin.latest && plugin.latest !== plugin.version);
+      const latestLabel = isGit ? `远端 ${plugin.latest}` : `最新 v${plugin.latest}`;
+      // npm 上有同名包才算「能切换」；查不到就明确说没有，免得用户反复猜
+      const migration = plugin.npmMigration;
+      const canMigrate = !isGit && plugin.kind === 'local' && migration && migration.available;
+      const migrationNote =
+        !isGit && plugin.kind === 'local' && migration
+          ? migration.available
+            ? `npm 上有同名包 ${migration.latest}${migration.upgradable ? '（更高）' : ''}，可切换来源`
+            : 'npm 上没有同名包，保持原来源'
+          : '';
       return h(
         'div',
         { className: 'pau-row', key: plugin.name },
@@ -344,15 +361,21 @@ function makePanel(React) {
             'div',
             { className: 'pau-row-t' },
             h('span', { className: 'pau-mono' }, plugin.name),
+            isGit ? h('span', { className: 'pau-tag' }, 'Git') : null,
             h('span', { className: 'pau-tag' }, plugin.version ? `v${plugin.version}` : '未装'),
-            showLatest ? h('span', { className: 'pau-tag' }, `最新 v${plugin.latest}`) : null,
+            isGit && currentCommit ? h('span', { className: 'pau-tag' }, currentCommit) : null,
+            showLatest ? h('span', { className: 'pau-tag' }, latestLabel) : null,
             h('span', { className: `pau-tag ${tone}` }, stateText),
           ),
           plugin.latestError
             ? h('div', { className: 'pau-row-d' }, `查询失败：${plugin.latestError}`)
-            : plugin.description
-              ? h('div', { className: 'pau-row-d' }, plugin.description.slice(0, 160))
-              : null,
+            : isGit && plugin.latestMessage
+              ? h('div', { className: 'pau-row-d' }, `${plugin.latestTag ? `${plugin.latestTag} · ` : ''}${plugin.latestMessage}`)
+              : migrationNote
+                ? h('div', { className: 'pau-row-d' }, migrationNote)
+                : plugin.description
+                  ? h('div', { className: 'pau-row-d' }, plugin.description.slice(0, 160))
+                  : null,
         ),
         h(
           'select',
@@ -387,16 +410,42 @@ function makePanel(React) {
           {
             className: 'pau-btn pau-btn-sm',
             disabled: !!busy || !plugin.updateAvailable,
+            title: isGit ? '安装远端最新提交' : '安装最新版本',
             onClick: () =>
               run(`update:${plugin.name}`, async () => {
-                const next = await call('/update', { name: plugin.name, version: plugin.latest });
+                const body = isGit
+                  ? { name: plugin.name, commit: plugin.latestCommit || '' }
+                  : { name: plugin.name, version: plugin.latest };
+                const next = await call('/update', body);
                 if (next.restart) setNote(next.restart.message || '已安排重启');
+                else if (next.result && next.result.ok === false) setNote(next.result.message || '未执行');
                 else setNote(`${plugin.name} 已更新`);
                 return next;
               }),
           },
           busy === `update:${plugin.name}` ? '更新中…' : '立即更新',
         ),
+        canMigrate
+          ? h(
+              'button',
+              {
+                className: 'pau-btn pau-btn-sm',
+                disabled: !!busy,
+                title: `改用 npm 来源（${migration.latest}），之后就能按版本号自动更新`,
+                onClick: () =>
+                  run(`migrate:${plugin.name}`, async () => {
+                    const next = await call('/migrate', { name: plugin.name });
+                    setNote(
+                      next.result && next.result.ok
+                        ? `${plugin.name} 已切换到 npm ${next.result.latest}`
+                        : (next.result && next.result.message) || '切换未完成',
+                    );
+                    return next;
+                  }),
+              },
+              busy === `migrate:${plugin.name}` ? '切换中…' : '切换到 npm',
+            )
+          : null,
         h(
           'button',
           {
@@ -427,42 +476,19 @@ function makePanel(React) {
       h(
         'div',
         { className: 'pau-card-h' },
-        h('h3', { className: 'pau-card-t' }, `已装插件（${registryPlugins.length}）`),
+        h('h3', { className: 'pau-card-t' }, `已装插件（${registryPlugins.length + gitPlugins.length}）`),
         h('span', { className: 'pau-row-d' }, available.length ? `${available.length} 个可更新` : '全部最新'),
       ),
-      registryPlugins.length
-        ? registryPlugins.map(pluginRow)
+      registryPlugins.length + gitPlugins.length
+        ? registryPlugins.concat(gitPlugins).map(pluginRow)
         : h('div', { className: 'pau-empty' }, '没有可联网检查的插件'),
       otherPlugins.length
         ? h(
             'div',
             { style: { marginTop: 12 } },
-            h('div', { className: 'pau-row-d' }, '本地路径 / Git 来源 / 随安装提供（不参与版本检查）'),
+            h('div', { className: 'pau-row-d' }, '本地路径 / 随安装提供（不参与版本检查）'),
             otherPlugins.map((plugin) =>
-              h(
-                'div',
-                { className: 'pau-row', key: plugin.name },
-                h(
-                  'div',
-                  { className: 'pau-row-main' },
-                  h(
-                    'div',
-                    { className: 'pau-row-t' },
-                    h('span', { className: 'pau-mono' }, plugin.name),
-                    h(
-                      'span',
-                      { className: 'pau-tag' },
-                      plugin.kind === 'git'
-                        ? 'Git'
-                        : plugin.kind === 'local'
-                          ? '本地'
-                          : '随安装提供',
-                    ),
-                    plugin.version ? h('span', { className: 'pau-tag' }, `v${plugin.version}`) : null,
-                  ),
-                  h('div', { className: 'pau-row-d' }, plugin.spec || '由 DSH 安装提供，版本跟随宿主'),
-                ),
-              ),
+              pluginRow(plugin),
             ),
           )
         : null,

package/index.js

@@ -18,21 +18,28 @@ import {
   humanHours,
   installedMeta,
   installedVersion,
+  installedGitHead,
   isNewerVersion,
+  isUpdatableKind,
   loadState,
+  parseGitSpec,
   policyFor,
   profileBundleNames,
   profileDependencySpecs,
   pushHistory,
   saveState,
   updateKind,
+  writeDependencySpec,
 } from './lib/core.js';
-import { normalizeRegistry, queryLatest } from './lib/registry.js';
-import { installSpec, installVersion } from './lib/updater.js';
+import { normalizeRegistry, probePackage, queryLatest } from './lib/registry.js';
+import { parseLockGitCommit, queryCommitMessage, queryGitHead, queryLatestTag } from './lib/gitref.js';
+import { backupProfile, installSpec, installVersion } from './lib/updater.js';
 import { scheduleRestart } from './lib/restart.js';
 import { createApi } from './lib/api.js';
 import { installSharedPlugin, libraryRoot, shareSnapshot, syncMyFeature, writeAggregate } from './lib/share.js';
 import { resolveIdentity } from './lib/machine.js';
+import fs from 'node:fs';
+import path from 'node:path';
 
 export const inject = ['webServer'];
 
@@ -86,15 +93,29 @@ export function apply(ctx, config = {}) {
     const specs = profileDependencySpecs();
     // 「已发布」名单存在 state 里，跟着面板配置走
     const publishedNames = loadState().publishedNames || [];
+    // lockfile 只读一次：git 来源的「当前 commit」只能从这里拿
+    let lockText = '';
+    try {
+      lockText = fs.readFileSync(path.join(profileDir(), 'pnpm-lock.yaml'), 'utf8');
+    } catch {
+      /* 没有 lock 文件就退化成只有 gitHead */
+    }
     return names
       .map((name) => {
         const meta = installedMeta(name);
+        const spec = typeof specs[name] === 'string' ? specs[name] : null;
+        const kind = updateKind(name, { publishedNames });
+        const parsed = kind === 'git' ? parseGitSpec(spec) : undefined;
+        const lockCommit = kind === 'git' ? parseLockGitCommit(lockText, name) : undefined;
+        const gitHead = kind === 'git' ? installedGitHead(name) : undefined;
         return {
           name,
           version: installedVersion(name) || null,
-          spec: typeof specs[name] === 'string' ? specs[name] : null,
+          spec,
           // 自己这个包也要能被管理，否则「自动更新器本身」永远停在旧版
-          kind: updateKind(name, { publishedNames }),
+          kind,
+          // git 来源额外带：仓库、钉住的 ref、当前 commit —— 面板据此显示「落后几个提交」
+          git: kind === 'git' ? { owner: parsed?.owner, repo: parsed?.repo, ref: parsed?.ref, commit: lockCommit || gitHead } : undefined,
           description: meta.description || '',
           homepage: meta.homepage || meta.repository || '',
         };
@@ -109,6 +130,21 @@ export function apply(ctx, config = {}) {
     };
   };
 
+  /**
+   * 给 git 子进程用的代理地址。
+   *
+   * 为什么必须显式取而不是靠环境变量：Node 自己的 fetch 会读 HTTPS_PROXY，
+   * 但 `git` 是独立进程，本机 git 未配置 http.proxy 时不会读这两个变量，
+   * 直连 github.com 会超时 20 秒然后报连不上。这里按配置 → 环境变量 → 常用端口依次取。
+   */
+  const updateProxy = () => {
+    const configured = config?.gitProxy || config?.proxy;
+    if (typeof configured === 'string' && configured.trim()) return configured.trim();
+    const env = process.env.HTTPS_PROXY || process.env.https_proxy || process.env.HTTP_PROXY || process.env.http_proxy;
+    if (typeof env === 'string' && env.trim()) return env.trim();
+    return '';
+  };
+
   /* -------------------------------------------------------------- 共享 */
 
   /** 共享相关的设置（目录、特征名）从状态里读，面板改完立即生效。 */
@@ -244,42 +280,130 @@ export function apply(ctx, config = {}) {
   const runCheck = async ({ signal } = {}) => {
     const state = loadState();
     const now = Date.now();
-    const plugins = listPlugins().filter((p) => p.kind === 'registry' && p.version);
+    const compare = (a, b) => (isNewerVersion(b, a) ? 1 : a === b ? 0 : -1);
+    // registry 走版本号；git 走 commit sha。两者都要查。
+    const plugins = listPlugins().filter((p) => isUpdatableKind(p.kind) && p.version);
     const { registry, fallbackRegistries } = registries();
 
     const results = [];
     let cursor = 0;
+
+    /** registry 来源：比版本号。 */
+    const checkRegistry = async (plugin) => {
+      const answer = await queryLatest({ name: plugin.name, registry, fallbackRegistries, compare, signal });
+      if (!answer.ok) return { ...plugin, error: answer.error };
+      const newer = isNewerVersion(plugin.version, answer.latest);
+      const policy = policyFor(state, plugin.name);
+      const remaining = newer ? delayRemainingMs(state, plugin.name, answer.publishedAt, now) : 0;
+      return {
+        ...plugin,
+        latest: answer.latest,
+        publishedAt: answer.publishedAt || 0,
+        updateAvailable: newer,
+        policy: policy.policy,
+        delayHours: policy.delayHours,
+        eligible: newer && remaining === 0,
+        waitMs: remaining,
+        waitText: remaining > 0 ? humanHours(remaining) : '',
+      };
+    };
+
+    /**
+     * git 来源：比 commit sha。
+     *
+     * 判据只能是 sha，不能看 package.json 的 version——上游可以连提十次都不改版本号
+     * （本机 dsh-knowledge-wiki 就是 0.34.0 停在某个 commit 之后的典型）。
+     * 「最新」这一列写短 sha，面板才看得出差在哪。
+     *
+     * 主通道是 `git ls-remote`：不受 GitHub API 未登录每小时 60 次的限流。
+     * 代理必须显式传给 git（Node 的 env-proxy 只管 fetch，管不到 git 子进程）。
+     */
+    const checkGit = async (plugin) => {
+      const parsed = parseGitSpec(plugin.spec);
+      const policy = policyFor(state, plugin.name);
+      const base = { policy: policy.policy, delayHours: policy.delayHours };
+      if (!parsed) return { ...plugin, ...base, error: '无法解析 git 地址' };
+
+      const head = await queryGitHead({ parsed, ref: parsed.ref, proxy: updateProxy() });
+      if (!head.ok) return { ...plugin, ...base, error: head.error };
+
+      const current = plugin.git?.commit;
+      // 当前 commit 读不到时不能判成「有更新」——否则每轮都会重复安装同一个版本
+      if (!current) {
+        return {
+          ...plugin,
+          ...base,
+          latest: head.shortCommit,
+          latestCommit: head.commit,
+          updateAvailable: false,
+          unknownCurrent: true,
+          note: '读不到已装 commit，按「不更新」处理',
+        };
+      }
+      const newer = current.toLowerCase() !== head.commit;
+      if (!newer) {
+        return { ...plugin, ...base, latest: head.shortCommit, latestCommit: head.commit, updateAvailable: false };
+      }
+
+      // 有更新才去补说明与 tag：这两件事都是纯展示，失败不影响判定
+      const [detail, tag] = await Promise.all([
+        queryCommitMessage({ parsed, commit: head.commit, proxy: updateProxy(), signal }).catch(() => ({ ok: false })),
+        queryLatestTag({ parsed, proxy: updateProxy() }).catch(() => ({ ok: false })),
+      ]);
+      const publishedAt = detail.ok ? detail.publishedAt || 0 : 0;
+      const remaining = delayRemainingMs(state, plugin.name, publishedAt, now);
+      return {
+        ...plugin,
+        ...base,
+        latest: head.shortCommit,
+        latestCommit: head.commit,
+        latestMessage: detail.ok ? detail.message : '',
+        latestTag: tag.ok ? tag.tag : undefined,
+        publishedAt,
+        updateAvailable: true,
+        eligible: remaining === 0,
+        waitMs: remaining,
+        waitText: remaining > 0 ? humanHours(remaining) : '',
+      };
+    };
+
+    /**
+     * 非 registry 来源（local / git）顺带探一次 npm 同名包。
+     *
+     * 用户要的是「更新时检查有没有对应的 npm 版，有就切换」。
+     * 做法是只报不自动切：切来源要改 profile 的 package.json，
+     * 属于「换一种安装方式」，比升版本危险得多，必须人工点。
+     */
+    const probeMigration = async (plugin) => {
+      if (plugin.kind === 'registry' || plugin.kind === 'installation') return plugin;
+      const answer = await probePackage({ name: plugin.name, registry, compare, signal });
+      if (!answer.ok) return plugin;
+      if (!answer.exists) {
+        // 明确记下「npm 上没有」，避免用户反复猜
+        return { ...plugin, npmMigration: { available: false, checkedAt: now } };
+      }
+      return {
+        ...plugin,
+        npmMigration: {
+          available: true,
+          latest: answer.latest,
+          publishedAt: answer.publishedAt || 0,
+          registry: answer.registry,
+          checkedAt: now,
+          // 已装版本可能比 npm 上还新（本地改过），这种不必切
+          upgradable: Boolean(plugin.version && answer.latest && isNewerVersion(plugin.version, answer.latest)),
+        },
+      };
+    };
+
     const worker = async () => {
       for (;;) {
         const index = cursor;
         cursor += 1;
         if (index >= plugins.length) return;
         const plugin = plugins[index];
-        const answer = await queryLatest({
-          name: plugin.name,
-          registry,
-          fallbackRegistries,
-          compare: (a, b) => (isNewerVersion(b, a) ? 1 : a === b ? 0 : -1),
-          signal,
-        });
-        if (!answer.ok) {
-          results[index] = { ...plugin, error: answer.error };
-          continue;
-        }
-        const newer = isNewerVersion(plugin.version, answer.latest);
-        const policy = policyFor(state, plugin.name);
-        const remaining = newer ? delayRemainingMs(state, plugin.name, answer.publishedAt, now) : 0;
-        results[index] = {
-          ...plugin,
-          latest: answer.latest,
-          publishedAt: answer.publishedAt || 0,
-          updateAvailable: newer,
-          policy: policy.policy,
-          delayHours: policy.delayHours,
-          eligible: newer && remaining === 0,
-          waitMs: remaining,
-          waitText: remaining > 0 ? humanHours(remaining) : '',
-        };
+        const checked = plugin.kind === 'git' ? await checkGit(plugin) : await checkRegistry(plugin);
+        results[index] = await probeMigration(checked);
       }
     };
     await Promise.all(Array.from({ length: Math.min(CHECK_CONCURRENCY, plugins.length) }, worker));
@@ -303,6 +427,13 @@ export function apply(ctx, config = {}) {
           publishedAt: item.publishedAt || 0,
           checkedAt: Date.now(),
           error: item.error || '',
+          // git 来源的展示字段：短 sha 之外的提交说明与最新 tag
+          latestCommit: item.latestCommit || '',
+          latestTag: item.latestTag || '',
+          latestMessage: item.latestMessage || '',
+          updateAvailable: Boolean(item.updateAvailable),
+          // 非 npm 来源顺带记录的「npm 上有没有同名包」结论
+          npmMigration: item.npmMigration || null,
         };
         if (!item.updateAvailable) continue;
         const old = next.pending[item.name];
@@ -344,22 +475,42 @@ export function apply(ctx, config = {}) {
 
   /* -------------------------------------------------------------- 更新 */
 
-  /** 安装一个包的指定版本，并写历史。 */
-  const applyUpdate = async (name, version, reason) => {
+  /**
+   * 安装一个包的指定版本 / 提交，并写历史。
+   *
+   * registry 走 `name@version`；git 走 `name@<完整安装 spec>`——
+   * 对 git 依赖必须把 ref 一起带上，否则装出来的还是分支最新而不是这次判定的那个 commit。
+   */
+  const applyUpdate = async (name, version, reason, options = {}) => {
     // 装上哪个源跟着查询走：查的是 A，装也必须用 A，
     // 否则刚发布到 A 的版本在 B 上还不存在，pnpm 会直接装不到。
     const { registry } = registries();
-    const result = await installVersion({ ctx, name, version, registry, log });
+    const kind = options.kind || updateKind(name, { publishedNames: loadState().publishedNames });
+    let result;
+    if (kind === 'git') {
+      const spec = options.spec || profileDependencySpecs()[name];
+      const parsed = parseGitSpec(spec);
+      // 把 ref 钉到这次查到的 commit：分支会在安装期间继续往前走
+      const pinned = parsed && options.commit ? `${spec.split('#')[0]}#${options.commit}` : spec;
+      result = await installSpec({ ctx, spec: pinned, registry, log });
+    } else {
+      result = await installVersion({ ctx, name, version, registry, log });
+    }
     const next = loadState();
+    const label = kind === 'git' ? (options.commit ? String(options.commit).slice(0, 10) : version) : version;
     if (result.ok) {
       delete next.pending[name];
       pushHistory(next, {
         kind: 'update',
         reason: reason || 'auto',
         name,
-        version,
+        version: label,
+        sourceKind: kind,
         via: result.via,
-        text: `${name} 已更新到 ${version}（${result.via}）`,
+        text:
+          kind === 'git'
+            ? `${name} 已更新到提交 ${label}（${result.via}）`
+            : `${name} 已更新到 ${version}（${result.via}）`,
         restartRequired: result.restartRequired === true,
       });
     } else {
@@ -367,12 +518,13 @@ export function apply(ctx, config = {}) {
         kind: 'update-failed',
         reason: reason || 'auto',
         name,
-        version,
-        text: `${name} 更新到 ${version} 失败：${String(result.message).slice(0, 400)}`,
+        version: label,
+        sourceKind: kind,
+        text: `${name} 更新到 ${label} 失败：${String(result.message).slice(0, 400)}`,
       });
     }
     saveState(next);
-    log(result.ok ? `已更新 ${name}@${version}` : `更新失败 ${name}@${version}`);
+    log(result.ok ? `已更新 ${name}（${label}）` : `更新失败 ${name}（${label}）`);
     return result;
   };
 
@@ -386,7 +538,11 @@ export function apply(ctx, config = {}) {
       const due = checks.filter((item) => item.eligible);
       const updated = [];
       for (const item of due) {
-        const result = await applyUpdate(item.name, item.latest, reason || 'auto');
+        const result = await applyUpdate(item.name, item.latest, reason || 'auto', {
+          kind: item.kind,
+          spec: item.spec,
+          commit: item.latestCommit,
+        });
         if (result.ok) updated.push({ name: item.name, version: item.latest, restartRequired: result.restartRequired === true });
       }
 
@@ -513,10 +669,67 @@ export function apply(ctx, config = {}) {
 
   /* ---------------------------------------------------------------- API */
 
+  /**
+   * 把某个非 registry 来源的插件切换成 npm 来源。
+   *
+   * 这是「换安装方式」，比升版本危险：要改 profile 的 package.json。
+   * 所以必须人工触发，且装不上时把 package.json 原样还原。
+   */
+  const migrateToNpm = async (name, { reason } = {}) => {
+    const { registry } = registries();
+    const specs = profileDependencySpecs();
+    const spec = specs[name];
+    if (typeof spec !== 'string') return { ok: false, message: `${name} 不在 profile dependencies 里` };
+    const kind = updateKind(name, { publishedNames: loadState().publishedNames });
+    if (kind === 'registry') return { ok: false, message: `${name} 已经是 registry 来源` };
+
+    const probe = await probePackage({
+      name,
+      registry,
+      compare: (a, b) => (isNewerVersion(b, a) ? 1 : a === b ? 0 : -1),
+    });
+    if (!probe.ok) return { ok: false, message: `查询 npm 失败：${probe.error}` };
+    if (!probe.exists) return { ok: false, message: `npm 上没有 ${name}，无法切换（保持原来源）` };
+
+    backupProfile(log);
+    try {
+      // 直接把依赖写法换成 npm 版本：pnpm 会据此重新解析，lock 里换成 registry tarball
+      const result = await installSpec({ ctx, spec: `${name}@${probe.latest}`, registry, log });
+      const next = loadState();
+      if (result.ok) {
+        pushHistory(next, {
+          kind: 'migrate',
+          reason: reason || '手动',
+          name,
+          version: probe.latest,
+          fromKind: kind,
+          text: `${name} 已从 ${kind} 来源切换到 npm ${probe.latest}`,
+          restartRequired: result.restartRequired === true,
+        });
+        saveState(next);
+        return { ok: true, latest: probe.latest, kind: 'registry', via: result.via };
+      }
+      // 装不上：把 package.json 里这一行写回原样
+      writeDependencySpec(name, spec);
+      pushHistory(next, {
+        kind: 'migrate-failed',
+        reason: reason || '手动',
+        name,
+        text: `${name} 切换到 npm 失败，已还原为 ${spec}：${String(result.message).slice(0, 300)}`,
+      });
+      saveState(next);
+      return { ok: false, message: result.message };
+    } catch (error) {
+      writeDependencySpec(name, spec);
+      return { ok: false, message: String(error?.message || error) };
+    }
+  };
+
   const api = createApi({
     listPlugins,
     runCheck: checkAndRecord,
     applyUpdate,
+    migrateToNpm,
     requestRestart,
     isBusy,
     log,

package/lib/api.js

@@ -17,6 +17,7 @@ import {
   profileBundleNames,
   saveState,
   updateKind,
+  isUpdatableKind,
 } from './core.js';
 import { normalizeRegistry, queryLatest } from './registry.js';
 import { restoreBackup, listBackups } from './backup.js';
@@ -57,14 +58,19 @@ function snapshot(deps) {
     // 而 pending 里还留着旧记录。只看 pending 会把「已是最新」错标成「可更新」。
     const newer = Boolean(latest && plugin.version && isNewerVersion(plugin.version, latest));
     const active = newer ? pending : undefined;
+    // git 来源没有版本号可比，可更新性直接看检查阶段算出的 updateAvailable
+    const gitNewer = plugin.kind === 'git' ? Boolean(seen && seen.updateAvailable) : false;
     return {
       ...plugin,
       policy: policy.policy,
       delayHours: policy.delayHours,
       hasOverride: Boolean(state.perPlugin[plugin.name]),
       latest: latest || null,
+      latestTag: (seen && seen.latestTag) || null,
+      latestMessage: (seen && seen.latestMessage) || '',
+      npmMigration: (seen && seen.npmMigration) || plugin.npmMigration || null,
       latestError: seen && seen.error ? seen.error : '',
-      updateAvailable: newer,
+      updateAvailable: plugin.kind === 'git' ? gitNewer : newer,
       waitMs: active ? delayRemainingMs(state, plugin.name, active.firstSeenAt) : 0,
       waitText: active ? humanHours(delayRemainingMs(state, plugin.name, active.firstSeenAt)) : '',
     };
@@ -212,8 +218,19 @@ export function createApi(deps) {
         return;
       }
       const state = loadState();
-      if (updateKind(name, { publishedNames: state.publishedNames }) !== 'registry') {
-        json(res, 200, { ok: true, name, current, latest: null, note: '本地/仓库来源，不参与版本检查' });
+      const kind = updateKind(name, { publishedNames: state.publishedNames });
+      if (kind !== 'registry') {
+        // git / local 来源也能查，但比的是 commit 而不是版本号
+        const plugin = deps.listPlugins().find((item) => item.name === name);
+        json(res, 200, {
+          ok: true,
+          name,
+          current,
+          kind,
+          git: plugin?.git,
+          latest: null,
+          note: kind === 'git' ? 'Git 来源，请用「检查」看远端提交' : '本地来源，不参与版本检查',
+        });
         return;
       }
       const answer = await queryLatest({
@@ -244,12 +261,39 @@ export function createApi(deps) {
       const body = await readJson(req);
       const name = typeof body.name === 'string' ? body.name : '';
       const version = typeof body.version === 'string' ? body.version : '';
-      if (!name || !version) {
-        json(res, 400, { ok: false, error: '缺少 name 或 version' });
+      const commit = typeof body.commit === 'string' ? body.commit.trim().toLowerCase() : '';
+      if (!name || (!version && !commit)) {
+        json(res, 400, { ok: false, error: '缺少 name，或 version / commit' });
+        return;
+      }
+      const state = loadState();
+      const kind = updateKind(name, { publishedNames: state.publishedNames });
+      if (!isUpdatableKind(kind)) {
+        json(res, 400, {
+          ok: false,
+          error: '该插件既不是 registry 也不是 git 来源，不自动更新（本地 file: 来源可先「切换到 npm」）',
+        });
         return;
       }
-      if (updateKind(name, { publishedNames: loadState().publishedNames }) !== 'registry') {
-        json(res, 400, { ok: false, error: '该插件不是 registry 来源，不自动更新（若是已发布的自有插件，先在设置里把它列为「已发布」）' });
+      if (kind === 'git') {
+        const plugin = deps.listPlugins().find((item) => item.name === name);
+        const current = plugin?.git?.commit;
+        if (current && commit && current === commit) {
+          json(res, 200, {
+            ...snapshot(deps),
+            result: { ok: false, via: 'none', message: `${name} 当前已是提交 ${commit.slice(0, 10)}，未执行` },
+            restart: null,
+          });
+          return;
+        }
+        const result = await deps.applyUpdate(name, commit ? commit.slice(0, 10) : '', '手动', {
+          kind: 'git',
+          spec: plugin?.spec,
+          commit: commit || undefined,
+        });
+        let restart = null;
+        if (result.ok && state.autoRestart) restart = deps.requestRestart('手动更新完成', state);
+        json(res, 200, { ...snapshot(deps), result, restart });
         return;
       }
       // 只允许向上更新：面板状态可能与磁盘不同步，传进来的 version 万一更旧就会降级
@@ -263,12 +307,30 @@ export function createApi(deps) {
         return;
       }
       const result = await deps.applyUpdate(name, version, '手动');
-      const state = loadState();
+      const next = loadState();
       let restart = null;
-      if (result.ok && state.autoRestart) restart = deps.requestRestart('手动更新完成', state);
+      if (result.ok && next.autoRestart) restart = deps.requestRestart('手动更新完成', next);
       json(res, 200, { ...snapshot(deps), result, restart });
     },
 
+    /**
+     * 把非 npm 来源切到 npm 来源。必须先查得到 npm 上有这个包，且要人工触发。
+     * 这是「换安装方式」，比升版本危险，永远不自动做。
+     */
+    'POST /migrate': async (req, res) => {
+      const body = await readJson(req);
+      const name = typeof body.name === 'string' ? body.name.trim() : '';
+      if (!name) {
+        json(res, 400, { ok: false, error: '缺少 name' });
+        return;
+      }
+      const result = await deps.migrateToNpm(name, { reason: '手动' });
+      const state = loadState();
+      let restart = null;
+      if (result.ok && state.autoRestart) restart = deps.requestRestart('切换到 npm 完成', state);
+      json(res, result.ok ? 200 : 400, { ...snapshot(deps), result, restart });
+    },
+
     /** 按策略更新所有到点的包。 */
     'POST /update-all': async (req, res) => {
       const state = loadState();
@@ -277,7 +339,11 @@ export function createApi(deps) {
       const updated = [];
       const failed = [];
       for (const item of due) {
-        const result = await deps.applyUpdate(item.name, item.latest, '手动批量');
+        const result = await deps.applyUpdate(item.name, item.latest, '手动批量', {
+          kind: item.kind,
+          spec: item.spec,
+          commit: item.latestCommit,
+        });
         (result.ok ? updated : failed).push({ name: item.name, version: item.latest, message: result.message });
       }
       let restart = null;

package/lib/core.js

@@ -119,6 +119,24 @@ export function profileDependencySpecs() {
   return deps;
 }
 
+/**
+ * 直接把一个依赖写法写回 profile 的 package.json。
+ *
+ * 用途只有一个：切换到 npm 来源失败时把原写法还原。
+ * 只动 dependencies[name] 这一个键，其余字段与顺序一律保持原样（先解析再字符串写回会丢格式）。
+ */
+export function writeDependencySpec(name, spec) {
+  const file = path.join(profileDir(), 'package.json');
+  const text = fs.readFileSync(file, 'utf8');
+  const pkg = JSON.parse(text);
+  if (!pkg || typeof pkg.dependencies !== 'object' || !pkg.dependencies) return false;
+  if (typeof spec === 'string') pkg.dependencies[name] = spec;
+  else delete pkg.dependencies[name];
+  // profile 的 package.json 是 2 空格缩进，写回时保持一致
+  fs.writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+  return true;
+}
+
 /** 读已安装包的真实版本（node_modules/<name>/package.json）。 */
 export function installedVersion(name) {
   const manifest = path.join(profileDir(), 'node_modules', ...String(name).split('/'), 'package.json');
@@ -142,10 +160,59 @@ export function installedMeta(name) {
   };
 }
 
+/**
+ * 读已装副本里记录的 git commit（npm publish 时写进 package.json 的 gitHead）。
+ * 拿不到返回 undefined——真实 sha 通常在 pnpm-lock.yaml 里，由调用方另行解析。
+ */
+export function installedGitHead(name) {
+  const manifest = path.join(profileDir(), 'node_modules', ...String(name).split('/'), 'package.json');
+  const value = readJsonFile(manifest);
+  return typeof value?.gitHead === 'string' && value.gitHead ? value.gitHead.toLowerCase() : undefined;
+}
+
+/**
+ * 解析 git 依赖写法，取出仓库 URL 与钉住的 ref（分支/标签/commit）。
+ *
+ * 支持的写法（pnpm / npm 常见）：
+ *   github:user/repo
+ *   github:user/repo#v1.2.3
+ *   git+https://github.com/user/repo.git#main
+ *   git+ssh://git@github.com/user/repo.git
+ *   https://github.com/user/repo.git
+ *
+ * @returns {{url?: string, codeload?: string, ref?: string, owner?: string, repo?: string}|undefined}
+ */
+export function parseGitSpec(spec) {
+  if (typeof spec !== 'string') return undefined;
+  const value = spec.trim();
+  if (!/^(github:|git\+|git:)/i.test(value) && !/^https?:\/\/\S+\.git(#|$)/i.test(value)) return undefined;
+
+  const hashAt = value.indexOf('#');
+  const ref = hashAt >= 0 ? value.slice(hashAt + 1).trim() || undefined : undefined;
+  const body = hashAt >= 0 ? value.slice(0, hashAt) : value;
+
+  // github:owner/repo
+  let m = /^github:([^/\s]+)\/([^/\s#]+)$/i.exec(body);
+  if (m) {
+    const owner = m[1];
+    const repo = m[2].replace(/\.git$/i, '');
+    return { owner, repo, ref, url: `https://github.com/${owner}/${repo}.git` };
+  }
+
+  // git+https://… / git+ssh://… / https://…git
+  const url = body.replace(/^git\+/i, '');
+  m = /github\.com[:/]([^/\s]+)\/([^/\s#]+?)(?:\.git)?\/?$/i.exec(url);
+  if (!m) return { url, ref };
+  const owner = m[1];
+  const repo = m[2].replace(/\.git$/i, '');
+  return { owner, repo, ref, url: `https://github.com/${owner}/${repo}.git` };
+}
+
 /**
  * 判断某个包能不能自动更新。
  * 规则：
- *   - 本地路径（file:/link:/workspace:）和 git 地址不自动更新——没有「发布」概念
+ *   - 本地路径（file:/link:/workspace:）不自动更新——没有「发布」概念
+ *   - git 地址可以更新：靠 git ref 比新旧（见 gitRefKind）
  *   - 不在 profile dependencies 里的（随 DSH 安装提供的官方包）也没有可查的版本约束
  *
  * 「已发布的自有插件」例外：profile 里还是 file: 依赖，但它其实已经有 registry 产物。
@@ -165,10 +232,19 @@ export function updateKind(name, options) {
   const localish = /^(file:|link:|workspace:|portal:)/i.test(value);
   // 已在 registry 发布过的本地包，按 registry 处理（可以查新版、可以自动更新）
   if (localish) return claimed ? 'registry' : 'local';
-  if (/^(git\+|git:|github:|https?:\/\/)/i.test(value)) return claimed ? 'registry' : 'git';
+  // 只有真正的 git 写法才算 git：github: / git+ / git: / 以 .git 结尾的 URL。
+  // 普通 https:// 直链（例如 release 附件 .tgz）仍然算不可自动更新——
+  // 它没有 ref 概念，也没有版本号可查，硬当 git 处理会误开一条走不通的安装路径。
+  if (parseGitSpec(value)) return claimed ? 'registry' : 'git';
+  if (/^https?:\/\//i.test(value)) return claimed ? 'registry' : 'local';
   return 'registry';
 }
 
+/** 参与自动更新的来源（registry 走版本号，git 走 ref）。 */
+export function isUpdatableKind(kind) {
+  return kind === 'registry' || kind === 'git';
+}
+
 /* ---------------------------------------------------------------- state */
 
 /** 默认状态。 */

package/lib/gitref.js

@@ -0,0 +1,209 @@
+/**
+ * git 来源插件的「有没有新版」查询层。
+ *
+ * 与 registry.js 的分工：registry 比版本号，这里比 commit。
+ * 一条 git 依赖能确定的「当前版本」只有 commit sha，所以判据只能是 sha 而不是 package.json 的 version
+ * ——上游完全可以连着提交十次都不改 version（本机 dsh-knowledge-wiki 0.34.0 就停在
+ * commit 8716b06，而其后的提交已经改了不少功能）。
+ *
+ * 双通道：
+ *   主：`git ls-remote`（走 443 上的 git 协议，不受 GitHub API 限流影响）
+ *   辅：GitHub REST API（只为拿提交说明与 tag 名，拿不到不影响判定）
+ *
+ * 主通道的选择理由：未登录时 api.github.com 只有 60 次/小时，二十几个插件轮询几轮就打光，
+ * 而 ls-remote 没有这个限制。判定「有没有新提交」这件事 ls-remote 完全够用。
+ */
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const TIMEOUT_MS = 20000;
+const DEFAULT_REF = 'HEAD';
+
+/** 仓库标识 → API 根。只支持 GitHub；其余返回 undefined 由调用方降级。 */
+export function gitApiBase(parsed) {
+  if (!parsed || !parsed.owner || !parsed.repo) return undefined;
+  return `https://api.github.com/repos/${parsed.owner}/${parsed.repo}`;
+}
+
+/**
+ * 找一个能用的 git 可执行文件。
+ *
+ * 不假设 PATH 里有 git：本机可能只装了 DSH 自带的 @dsh-ops/git.exe（那是包装器，不是真 git），
+ * 真正能用的是 dsh-tools 里那份。候选顺序按「确定可用」优先。
+ */
+export function findGitBinary() {
+  const home = os.homedir();
+  const candidates = [
+    path.join(home, 'AppData', 'Local', 'Programs', 'dsh-tools', 'git', 'cmd', 'git.exe'),
+    'C:\\Program Files\\Git\\cmd\\git.exe',
+    'C:\\Program Files (x86)\\Git\\cmd\\git.exe',
+    '/usr/bin/git',
+    '/usr/local/bin/git',
+    'git',
+  ];
+  for (const item of candidates) {
+    try {
+      if (item === 'git') return item;
+      if (fs.existsSync(item)) return item;
+    } catch {
+      /* 继续试下一个 */
+    }
+  }
+  return 'git';
+}
+
+function runGit(args, { env, timeout = TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    const child = execFile(
+      findGitBinary(),
+      args,
+      {
+        timeout,
+        windowsHide: true,
+        maxBuffer: 8 * 1024 * 1024,
+        env: {
+          ...process.env,
+          ...env,
+          // 不让 git 弹凭据/主机确认，否则无人值守时会挂住
+          GIT_TERMINAL_PROMPT: '0',
+          GIT_ASKPASS: 'echo',
+          GIT_SSH_COMMAND: 'ssh -o BatchMode=yes -o StrictHostKeyChecking=no',
+        },
+      },
+      (error, stdout, stderr) => {
+        if (error) resolve({ ok: false, code: error.code, error: String(stderr || error.message || error).trim() });
+        else resolve({ ok: true, stdout: String(stdout || '') });
+      },
+    );
+    child.on('error', (error) => resolve({ ok: false, error: String(error?.message || error) }));
+  });
+}
+
+/**
+ * 从 pnpm-lock.yaml 文本里抠出某个包的 git 解析结果（commit sha）。
+ *
+ * 形如：
+ *   dsh-knowledge-wiki:
+ *     specifier: github:135642-163/dsh-knowledge-base
+ *     version: https://codeload.github.com/135642-163/dsh-knowledge-base/tar.gz/8716b06bf6...
+ */
+export function parseLockGitCommit(lockText, name) {
+  if (typeof lockText !== 'string' || !name) return undefined;
+  const lines = lockText.split(/\r?\n/);
+  const key = `${name}:`;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (lines[i].trim() !== key) continue;
+    for (let j = i + 1; j < Math.min(i + 7, lines.length); j += 1) {
+      const m = /^\s+version:\s*(.+)$/.exec(lines[j]);
+      if (!m) continue;
+      const sha = /([0-9a-f]{40})/i.exec(m[1]);
+      if (sha) return sha[1].toLowerCase();
+      break;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 查远端某个 ref 的 commit（走 ls-remote）。
+ *
+ * @param {{parsed: object, ref?: string, proxy?: string}} input
+ *   proxy —— 形如 http://127.0.0.1:7897。给了就通过 git 的 http.proxy 传下去；
+ *            不给则沿用环境变量（Node 的 env-proxy 对 git 无效，必须显式传 -c）。
+ */
+export async function queryGitHead({ parsed, ref, proxy }) {
+  if (!parsed || !parsed.url) return { ok: false, error: '不是可识别的 git 仓库地址' };
+  const target = ref || parsed.ref || DEFAULT_REF;
+  const args = [];
+  if (proxy) args.push('-c', `http.proxy=${proxy}`);
+  args.push('ls-remote', parsed.url, target === 'HEAD' ? 'HEAD' : target);
+
+  const result = await runGit(args);
+  if (!result.ok) {
+    // ref 写错（例如分支名打错）与网络失败要分开说
+    const text = String(result.error || '');
+    if (/not found|couldn't find remote ref/i.test(text)) {
+      return { ok: false, error: `远端没有 ${target} 这个 ref`, ref: target };
+    }
+    return { ok: false, error: text || 'ls-remote 失败', ref: target };
+  }
+  const line = result.stdout.split(/\r?\n/).find((l) => l.trim());
+  if (!line) return { ok: false, error: `远端没有 ${target}`, ref: target };
+  const [sha] = line.trim().split(/\s+/);
+  if (!/^[0-9a-f]{40}$/i.test(sha || '')) return { ok: false, error: 'ls-remote 返回的 sha 不合法', ref: target };
+  return { ok: true, ref: target, commit: sha.toLowerCase(), shortCommit: sha.slice(0, 10) };
+}
+
+/**
+ * 查远端最新 tag（走 ls-remote，按版本倒序）。
+ * 拿不到不算错——很多仓库不打 tag。
+ */
+export async function queryLatestTag({ parsed, proxy }) {
+  if (!parsed || !parsed.url) return { ok: false, error: '不是可识别的 git 仓库地址' };
+  const args = [];
+  if (proxy) args.push('-c', `http.proxy=${proxy}`);
+  args.push('ls-remote', '--tags', '--sort=-v:refname', parsed.url);
+  const result = await runGit(args);
+  if (!result.ok) return { ok: false, error: result.error };
+  for (const line of result.stdout.split(/\r?\n/)) {
+    const m = /^([0-9a-f]{40})\s+refs\/tags\/(.+?)(\^\{\})?$/.exec(line.trim());
+    if (!m) continue;
+    if (m[3]) continue; // 只要未解引用的那一行，避免重复
+    return { ok: true, tag: m[2], commit: m[1].toLowerCase() };
+  }
+  return { ok: true, tag: undefined };
+}
+
+/**
+ * 用 GitHub API 补一条提交说明（纯展示用，失败无影响）。
+ * 单独放这里是为了让主判定完全不依赖 API。
+ *
+ * 注意 API 与 ls-remote 走的不是同一条网络：ls-remote 用显式 -c http.proxy，
+ * 这里用 fetch，而 Node 的 env-proxy 只在进程启动时读环境变量。
+ * 所以显式构造代理 dispatcher，保证「代理开了就一定能过」。
+ */
+export async function queryCommitMessage({ parsed, commit, proxy, signal }) {
+  const base = gitApiBase(parsed);
+  if (!base || !commit) return { ok: false };
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 8000);
+  const onAbort = () => controller.abort();
+  if (signal) {
+    if (signal.aborted) controller.abort();
+    else signal.addEventListener('abort', onAbort, { once: true });
+  }
+  let dispatcher;
+  try {
+    if (proxy) {
+      const { ProxyAgent } = await import('undici');
+      dispatcher = new ProxyAgent(proxy);
+    }
+  } catch {
+    dispatcher = undefined; // 拿不到 undici 就退回普通 fetch
+  }
+  try {
+    const response = await fetch(`${base}/commits/${commit}`, {
+      signal: controller.signal,
+      dispatcher,
+      headers: { accept: 'application/vnd.github+json', 'user-agent': 'dsh-plugin-autoupdate/0.7' },
+    });
+    if (!response.ok) return { ok: false, error: `HTTP ${response.status}` };
+    const value = await response.json();
+    const message = String(value?.commit?.message || '').split('\n')[0].slice(0, 120);
+    const date = value?.commit?.author?.date || value?.commit?.committer?.date;
+    const ms = typeof date === 'string' ? Date.parse(date) : NaN;
+    return { ok: true, message, publishedAt: Number.isFinite(ms) ? ms : 0 };
+  } catch (error) {
+    return { ok: false, error: String(error?.message || error) };
+  } finally {
+    clearTimeout(timer);
+    if (signal) signal.removeEventListener('abort', onAbort);
+    try {
+      await dispatcher?.close?.();
+    } catch {
+      /* ignore */
+    }
+  }
+}

package/lib/registry.js

@@ -118,3 +118,29 @@ export async function queryLatest({ name, registry, fallbackRegistries, compare,
   }
   return { ok: false, name, error: lastError || 'registry unreachable', registries: tried };
 }
+
+/**
+ * 探测一个包在 registry 上是否存在（用于「本地/git 来源能否改成 npm 来源」）。
+ *
+ * 与 queryLatest 分开：这里不关心最新版是多少，只回答「npm 上有没有这个包」。
+ * 404 / Not found 明确返回 exists:false；网络错误返回 ok:false 而不是 exists:false——
+ * 把「查不到」与「查不了」混为一谈会诱导用户在断网时误判。
+ *
+ * @returns {Promise<{ok: boolean, exists: boolean, latest?: string, publishedAt?: number, error?: string, registry?: string}>}
+ */
+export async function probePackage({ name, registry, compare, signal }) {
+  const base = normalizeRegistry(registry);
+  const result = await fetchJson(packageUrl(base, name), signal);
+  if (!result.ok) {
+    if (result.status === 404) return { ok: true, exists: false, registry: base };
+    return { ok: false, exists: false, error: result.error, registry: base };
+  }
+  const doc = result.value;
+  // npm 对未收录的包有时回 200 + {"error":"Not found"}，必须看内容再说
+  if (doc && typeof doc.error === 'string' && !doc.versions) {
+    return { ok: true, exists: false, registry: base, note: doc.error };
+  }
+  const latest = pickLatest(doc, compare);
+  if (!latest) return { ok: true, exists: false, registry: base, note: 'package has no versions' };
+  return { ok: true, exists: true, latest, publishedAt: publishedAt(doc, latest), registry: base };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ygc-dsh-plugin-autoupdate",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "DSH 插件自动更新器：定时检查已装插件的新版本并按策略升级；把自己的插件特征（清单+本地副本+本机汇总）同步到共享插件库自己那一格，本机标识与会话同步插件共用，并汇集他人清单供人工选用。",
   "icon": "icon.svg",
@@ -33,7 +33,8 @@
     "lib/restart.js",
     "lib/share.js",
     "lib/updater.js",
-    "locale/*.json"
+    "locale/*.json",
+    "lib/gitref.js"
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",