dsh-github-flow 0.1.7 → 0.1.8

package/lib/commands/gh.d.ts

@@ -1,2 +1,3 @@
 import type { GhExecutor } from '../executor.js';
-export declare function registerGhCommand(commandsService: any, executor: GhExecutor): void;
+import type { UpdateChecker } from '../updater.js';
+export declare function registerGhCommand(commandsService: any, executor: GhExecutor, updateChecker?: UpdateChecker): void;

package/lib/commands/gh.js

@@ -1,4 +1,5 @@
-export function registerGhCommand(commandsService, executor) {
+import { CURRENT_PLUGIN_VERSION, PLUGIN_PACKAGE_NAME, NPM_PACKAGE_URL } from '../version.js';
+export function registerGhCommand(commandsService, executor, updateChecker) {
     if (!commandsService || typeof commandsService.register !== 'function')
         return;
     commandsService.register({
@@ -11,7 +12,14 @@ export function registerGhCommand(commandsService, executor) {
                 // 「我刚 gh auth login 到底成没成」，给他 30 秒前的缓存等于答非所问。
                 const auth = await executor.checkAuth(undefined, true);
                 const repo = await executor.getRepoMetadata();
+                const updateInfo = updateChecker?.getQuickStatus();
                 let md = `### GitHub 集成状态\n\n`;
+                // 若检测到新版本，在最上方展示醒目的升级指引横幅
+                if (updateInfo?.hasUpdate) {
+                    md += `> 🚀 **发现新版本 v${updateInfo.latestVersion}**（当前为 \`v${updateInfo.currentVersion}\`）\n`;
+                    md += `> 输入 \`/gh upgrade\` 查看升级指引，或在终端执行：\`${updateInfo.upgradeCommand}\`\n\n`;
+                }
+                md += `- **插件版本**: \`v${updateInfo?.currentVersion || CURRENT_PLUGIN_VERSION}\`\n`;
                 if (auth.loggedIn) {
                     md += `- **登录账号**: \`${auth.user || '已登录'}\`\n`;
                     md += `- **授权作用域**: ${auth.scopes?.map((s) => `\`${s}\``).join(', ') || '标准权限'}\n`;
@@ -35,15 +43,44 @@ export function registerGhCommand(commandsService, executor) {
                     text: md,
                 };
             }
+            if (trimmed === 'upgrade') {
+                const info = updateChecker ? await updateChecker.check(true) : null;
+                const curVer = info?.currentVersion || CURRENT_PLUGIN_VERSION;
+                const latestVer = info?.latestVersion || curVer;
+                const hasUpdate = info?.hasUpdate ?? false;
+                const isMac = process.platform === 'darwin';
+                const isWin = process.platform === 'win32';
+                const platformName = isMac ? 'macOS' : isWin ? 'Windows' : 'Linux';
+                let md = `### 🚀 ${PLUGIN_PACKAGE_NAME} 插件升级指南\n\n`;
+                md += `- **当前运行版本**: \`v${curVer}\`\n`;
+                md += `- **官方最新版本**: \`v${latestVer}\` ${hasUpdate ? '🔥 (有可用更新)' : '✅ (已是最新)'}\n`;
+                md += `- **操作系统环境**: \`${platformName} (${process.platform})\`\n`;
+                md += `- **npm 仓库地址**: [${NPM_PACKAGE_URL}](${NPM_PACKAGE_URL})\n\n`;
+                md += `#### 请根据你的 DSH 安装环境选择适用的升级方式：\n\n`;
+                md += `1. **DSH 官方标准工程升级（推荐）**:\n\`\`\`bash\npnpm dsh plugin add ${PLUGIN_PACKAGE_NAME}@latest\n\`\`\`\n\n`;
+                md += `2. **DSH 桌面版 Profile 环境升级**:\n\`\`\`bash\ndsh plugin --profile desktop add ${PLUGIN_PACKAGE_NAME}@latest\n\`\`\`\n`;
+                if (isMac) {
+                    md += `> 💡 *macOS 提示*：若在终端找不到 \`dsh\` 命令，可直接在桌面端目录更新：\n\`\`\`bash\ncd ~/.dsh/profiles/desktop && npm install ${PLUGIN_PACKAGE_NAME}@latest --save\n\`\`\`\n\n`;
+                }
+                else {
+                    md += `\n`;
+                }
+                md += `3. **Node 全局环境升级**:\n\`\`\`bash\nnpm install -g ${PLUGIN_PACKAGE_NAME}@latest\n\`\`\`\n\n`;
+                md += `> 💡 **升级后提示**：Node.js 运行时对已载入模块存在强缓存，升级后**请重启 DSH 服务以完全加载最新后端工具**。`;
+                return {
+                    kind: 'success',
+                    text: md,
+                };
+            }
             if (trimmed === 'help') {
                 return {
                     kind: 'success',
-                    text: `### DSH GitHub Flow 帮助\n\n- \`/gh status\`: 检查当前 GitHub CLI 账号与仓库连接\n- \`/gh help\`: 显示此帮助信息\n\n可以在对话中直接让 Agent 操作 GitHub，如：\n- *"查看当前仓库有哪些开放的 PR"* \n- *"查看最近一次 CI 失败的原因"* \n- *"帮我给当前分支创建 PR"*`,
+                    text: `### DSH GitHub Flow 帮助\n\n- \`/gh status\`: 检查当前 GitHub CLI 账号、仓库连接与插件版本\n- \`/gh upgrade\`: 检查新版本并显示全场景升级命令指引\n- \`/gh help\`: 显示此帮助信息\n\n可以在对话中直接让 Agent 操作 GitHub，如：\n- *"查看当前仓库有哪些开放的 PR"* \n- *"查看最近一次 CI 失败的原因"* \n- *"帮我给当前分支创建 PR"*`,
                 };
             }
             return {
                 kind: 'error',
-                text: `未知命令选项: /gh ${trimmed}。可用用法: /gh status, /gh help`,
+                text: `未知命令选项: /gh ${trimmed}。可用用法: /gh status, /gh upgrade, /gh help`,
             };
         },
     });

package/lib/executor.js

@@ -269,7 +269,18 @@ export class GhExecutor {
     async probeAuth(cwd) {
         const res = await this.run(['auth', 'status'], { cwd, timeoutMs: 10_000, rawText: true });
         const raw = (res.rawOutput || '') + '\n' + (res.error || '');
-        const loggedIn = raw.includes('Logged in to') || raw.includes('✓');
+        // 多重维度强健判定登录态 (容错 Windows Unicode 乱码、Keyring 告警与不同版本 CLI 输出差分)
+        const hasLoggedInFlag = /logged\s+in\s+to/i.test(raw) || raw.includes('✓') || raw.includes('√');
+        const hasActiveFlag = /active\s+account:\s*true/i.test(raw);
+        const hasTokenFlag = raw.includes('Token:') || raw.includes('Token scopes:');
+        const accountMatch = raw.match(/account\s+([A-Za-z0-9_-]+)/i);
+        const hasAccount = Boolean(accountMatch && accountMatch[1] && accountMatch[1].toLowerCase() !== 'none');
+        // 显式未登录特征排查
+        const isExplicitlyLoggedOut = /not\s+logged\s+in/i.test(raw) ||
+            raw.includes('gh auth login') ||
+            raw.includes('authentication required') ||
+            raw.includes('No accounts found');
+        const loggedIn = !isExplicitlyLoggedOut && (hasLoggedInFlag || hasActiveFlag || (hasTokenFlag && hasAccount));
         // 只要已登录或有常规输出，则必然安装了 gh
         const isNotInstalled = Boolean(res.error && (res.error.includes('系统未检测到 GitHub CLI') || res.error.includes('ENOENT')));
         const installed = loggedIn || !isNotInstalled;
@@ -292,7 +303,6 @@ export class GhExecutor {
         }
         // 解析用户名
         let user;
-        const accountMatch = raw.match(/account\s+([A-Za-z0-9_-]+)/i);
         if (accountMatch) {
             user = accountMatch[1];
         }

package/lib/main.d.ts

@@ -2,6 +2,13 @@ import { GhExecutor } from './executor.js';
 import './github-service.js';
 import type { PluginConfig } from './types.js';
 export declare const name = "dsh-github-flow";
+/**
+ * 核心服务依赖声明
+ *
+ * 必须显式声明 webServer 与 workspaceRegistry：
+ * 在 Cordis 依赖隔离机制下，只有在 inject 显式声明的服务，当前插件作用域 ctx 才能持有
+ * ctx.webServer 与 ctx.workspaceRegistry 引用，进而注册 Web UI 所需的后端 API 路由。
+ */
 export declare const inject: readonly ['tools', 'commands', 'webServer', 'workspaceRegistry'];
 export type Config = PluginConfig;
 /**
@@ -19,4 +26,8 @@ export declare const Config: {
 export declare function apply(ctx: any, config?: PluginConfig): void;
 export type GitHubService = GhExecutor;
 export * from './types.js';
+export * from './version.js';
+export * from './updater.js';
+export * from './upgrade-manager.js';
+export * from './executor.js';
 export * from './github-service.js';

package/lib/main.js

@@ -6,10 +6,20 @@ import { createRepoTool } from './tools/repo.js';
 import { createApiTool } from './tools/api.js';
 import { registerGhCommand } from './commands/gh.js';
 import { registerApiRoutes } from './api/routes.js';
+import { UpdateChecker } from './updater.js';
+import { UpgradeManager } from './upgrade-manager.js';
+import { NPM_PACKAGE_URL } from './version.js';
 // 引用即生效：加载本模块以挂上 declare module '@deepseek-ai/cordis' 的 ctx.github 类型声明，
 // 并随下面 `export * from './github-service.js'` 一起传给消费方。
 import './github-service.js';
 export const name = 'dsh-github-flow';
+/**
+ * 核心服务依赖声明
+ *
+ * 必须显式声明 webServer 与 workspaceRegistry：
+ * 在 Cordis 依赖隔离机制下，只有在 inject 显式声明的服务，当前插件作用域 ctx 才能持有
+ * ctx.webServer 与 ctx.workspaceRegistry 引用，进而注册 Web UI 所需的后端 API 路由。
+ */
 export const inject = ['tools', 'commands', 'webServer', 'workspaceRegistry'];
 /**
  * 符合 Standard Schema / Cordis Loader 契约的 Config 运行时校验规范
@@ -28,6 +38,9 @@ export const Config = {
                     maxOutputBytes: typeof cfg.maxOutputBytes === 'number' ? cfg.maxOutputBytes : undefined,
                     cacheTtlMs: typeof cfg.cacheTtlMs === 'number' ? cfg.cacheTtlMs : 15_000,
                     defaultListLimit: typeof cfg.defaultListLimit === 'number' ? cfg.defaultListLimit : 20,
+                    checkUpdate: typeof cfg.checkUpdate === 'boolean' ? cfg.checkUpdate : true,
+                    updateCheckIntervalMs: typeof cfg.updateCheckIntervalMs === 'number' ? cfg.updateCheckIntervalMs : 86_400_000,
+                    registryUrl: typeof cfg.registryUrl === 'string' ? cfg.registryUrl : undefined,
                 }
             };
         }
@@ -35,6 +48,11 @@ export const Config = {
 };
 export function apply(ctx, config = {}) {
     const executor = new GhExecutor(config);
+    const updateChecker = new UpdateChecker({
+        intervalMs: config.updateCheckIntervalMs,
+        customRegistry: config.registryUrl,
+    });
+    const upgradeManager = new UpgradeManager();
     // 1. 兑现生态服务契约：将 GitHub 执行引擎作为服务暴露给其他 DSH 插件 (ctx.github)
     if (ctx.provide && typeof ctx.provide === 'function') {
         ctx.provide('github', executor);
@@ -42,9 +60,9 @@ export function apply(ctx, config = {}) {
     else {
         ctx.github = executor;
     }
-    // 2. 注册人类 Slash 命令 (/gh status, /gh help)
+    // 2. 注册人类 Slash 命令 (/gh status, /gh upgrade, /gh help)
     if (ctx.commands) {
-        registerGhCommand(ctx.commands, executor);
+        registerGhCommand(ctx.commands, executor, updateChecker);
     }
     // 3. 注册 Agent 模型工具集（5 大核心领域工具）
     if (ctx.tools) {
@@ -58,9 +76,29 @@ export function apply(ctx, config = {}) {
     if (ctx.webServer) {
         // 传入 ctx 作用域对象，使 routes 能够通过 ctx.effect 绑定生命周期并在插件卸载/重载时自动注销；
         // cacheTtlMs 传给路由层以尊重用户的缓存 TTL 配置。
-        registerApiRoutes(ctx, executor, ctx.workspaceRegistry, config.cacheTtlMs || 15_000);
+        registerApiRoutes(ctx, executor, ctx.workspaceRegistry, config.cacheTtlMs || 15_000, updateChecker, upgradeManager);
+    }
+    // 5. 启动后低优先级后台闲时静默探测：若有新版本，仅输出一次友好的控制台提示
+    if (config.checkUpdate !== false) {
+        setTimeout(() => {
+            updateChecker.check(false).then((info) => {
+                if (info.hasUpdate) {
+                    console.log(`
+┌────────────────────────────────────────────────────────────────────────┐
+│  🚀 dsh-github-flow 插件有新版本可用: ${info.currentVersion} -> ${info.latestVersion}              │
+│  升级命令: ${info.upgradeCommand.padEnd(58, ' ')}│
+│  更新主页: ${NPM_PACKAGE_URL.padEnd(58, ' ')}│
+└────────────────────────────────────────────────────────────────────────┘
+`);
+                }
+            }).catch(() => { });
+        }, 3_000);
     }
 }
 export * from './types.js';
+export * from './version.js';
+export * from './updater.js';
+export * from './upgrade-manager.js';
+export * from './executor.js';
 // 让 `ctx.github` 的类型声明随包一起被消费方加载（声明合并在 './github-service.js' 内）
 export * from './github-service.js';

package/lib/types.d.ts

@@ -14,6 +14,12 @@ export interface PluginConfig {
     cacheTtlMs?: number;
     /** 查询列表默认限制条数，默认 20 */
     defaultListLimit?: number;
+    /** 是否开启新版本自动检查提示，默认 true */
+    checkUpdate?: boolean;
+    /** 检查更新间隔毫秒数，默认 86,400,000 (24小时) */
+    updateCheckIntervalMs?: number;
+    /** 自定义 npm Registry 镜像地址，留空则自动选用 npmmirror 与 npmjs */
+    registryUrl?: string;
 }
 export interface GhExecutionOptions {
     /** 命令执行的工作目录，优先使用当前 Agent 会话所在的 Workspace 物理路径 */
@@ -139,6 +145,8 @@ export interface GitHubOverviewData {
     runs: WorkflowRunItem[];
     lastUpdated: string;
     error?: string;
+    /** 插件版本与升级信息（由内存缓存快速读取，不阻塞首屏业务） */
+    updateInfo?: UpdateInfo;
 }
 export interface UserRepoItem {
     name: string;
@@ -199,4 +207,41 @@ export interface GlobalOverviewData {
     error?: string;
     /** 工作区矩阵读取失败的原因。区分「没有工作区」与「读不到工作区」，避免把故障显示成空状态 */
     workspaceError?: string;
+    /** 插件版本与升级信息（由内存缓存快速读取，不阻塞首屏业务） */
+    updateInfo?: UpdateInfo;
+}
+/**
+ * 插件版本检查信息
+ */
+export interface UpdateInfo {
+    currentVersion: string;
+    latestVersion?: string;
+    hasUpdate: boolean;
+    upgradeCommand: string;
+    allCommands: {
+        dshCli: string;
+        profile: string;
+        pnpm: string;
+        npm: string;
+    };
+    releaseNotesUrl: string;
+    checkedAt: number;
+}
+export type UpgradeState = 'idle' | 'upgrading' | 'success' | 'failed';
+export interface UpgradeStatusResult {
+    state: UpgradeState;
+    targetVersion?: string;
+    message?: string;
+    log?: string;
+    startedAt?: number;
+    completedAt?: number;
+    /** 识别到的宿主环境类型：desktop 为桌面版，web 为网页/CLI版 */
+    environment?: 'desktop' | 'web';
+}
+export interface UpgradeExecutionResult {
+    ok: boolean;
+    message: string;
+    needRestart: boolean;
+    log?: string;
+    environment?: 'desktop' | 'web';
 }

package/lib/updater.d.ts

@@ -0,0 +1,41 @@
+import type { UpdateInfo } from './types.js';
+/**
+ * 极简语义化版本大小比较函数 (latest > current 时返回 true)
+ *
+ * 为什么自研而不引入 semver npm 依赖：
+ * 避免为了简单的 x.y.z 比对而引入数十个传递子依赖，保持 DSH 插件轻量纯净与零运行期依赖负担。
+ * 约束条件：标准处理 x.y.z 形式，自动过滤前导 'v' 或 '^' 等非数字字符，忽略 pre-release 标签后续对比。
+ */
+export declare function isNewerVersion(current: string, latest: string): boolean;
+/**
+ * 插件版本检测引擎
+ *
+ * 架构约束与为什么这样设计：
+ * 1. 业务解耦：getQuickStatus 同步读取内存缓存，耗时 0ms，供主业务路由无感调用；
+ * 2. 闲时触发：check() 异步外网探测，首选淘宝镜像加速 (npmmirror.com)，官方 npmjs 兜底；
+ * 3. 避免击穿：通过 inFlightPromise 合并并发调用，防止多处同时触发重复请求；
+ * 4. 彻底容灾：任何网络或解析异常 100% 内部吸收，返回 hasUpdate: false，绝不影响主流程。
+ */
+export declare class UpdateChecker {
+    private cachedInfo;
+    private inFlightPromise;
+    private readonly intervalMs;
+    private readonly customRegistry?;
+    constructor(options?: {
+        intervalMs?: number;
+        customRegistry?: string;
+    });
+    /**
+     * 同步获取当前已知的版本状态（0ms 纯内存读取，绝不发外网请求）
+     */
+    getQuickStatus(): UpdateInfo;
+    /**
+     * 异步触发版本检测
+     * @param force 是否忽略 24h 缓存强制穿透探测
+     */
+    check(force?: boolean): Promise<UpdateInfo>;
+    /**
+     * 内部双 Registry 竞速/降级探测
+     */
+    private performCheck;
+}

package/lib/updater.js

@@ -0,0 +1,160 @@
+import { CURRENT_PLUGIN_VERSION, PLUGIN_PACKAGE_NAME, NPM_PACKAGE_URL, NPM_REGISTRY_MIRROR, NPM_REGISTRY_OFFICIAL, } from './version.js';
+/**
+ * 极简语义化版本大小比较函数 (latest > current 时返回 true)
+ *
+ * 为什么自研而不引入 semver npm 依赖：
+ * 避免为了简单的 x.y.z 比对而引入数十个传递子依赖，保持 DSH 插件轻量纯净与零运行期依赖负担。
+ * 约束条件：标准处理 x.y.z 形式，自动过滤前导 'v' 或 '^' 等非数字字符，忽略 pre-release 标签后续对比。
+ */
+export function isNewerVersion(current, latest) {
+    if (!current || !latest)
+        return false;
+    const parseParts = (v) => {
+        return v
+            .replace(/^[^\d]*/, '')
+            .split('-')[0]
+            .split('.')
+            .map((part) => parseInt(part, 10) || 0);
+    };
+    const cParts = parseParts(current);
+    const lParts = parseParts(latest);
+    const len = Math.max(cParts.length, lParts.length, 3);
+    for (let i = 0; i < len; i++) {
+        const c = cParts[i] ?? 0;
+        const l = lParts[i] ?? 0;
+        if (l > c)
+            return true;
+        if (l < c)
+            return false;
+    }
+    return false;
+}
+/**
+ * 插件版本检测引擎
+ *
+ * 架构约束与为什么这样设计：
+ * 1. 业务解耦：getQuickStatus 同步读取内存缓存，耗时 0ms，供主业务路由无感调用；
+ * 2. 闲时触发：check() 异步外网探测，首选淘宝镜像加速 (npmmirror.com)，官方 npmjs 兜底；
+ * 3. 避免击穿：通过 inFlightPromise 合并并发调用，防止多处同时触发重复请求；
+ * 4. 彻底容灾：任何网络或解析异常 100% 内部吸收，返回 hasUpdate: false，绝不影响主流程。
+ */
+export class UpdateChecker {
+    cachedInfo = null;
+    inFlightPromise = null;
+    intervalMs;
+    customRegistry;
+    constructor(options = {}) {
+        // 默认缓存 24 小时，杜绝高频击穿 npm
+        this.intervalMs = typeof options.intervalMs === 'number' && options.intervalMs > 0
+            ? options.intervalMs
+            : 86_400_000;
+        this.customRegistry = options.customRegistry;
+    }
+    /**
+     * 同步获取当前已知的版本状态（0ms 纯内存读取，绝不发外网请求）
+     */
+    getQuickStatus() {
+        if (this.cachedInfo) {
+            return this.cachedInfo;
+        }
+        return {
+            currentVersion: CURRENT_PLUGIN_VERSION,
+            hasUpdate: false,
+            upgradeCommand: `pnpm dsh plugin update ${PLUGIN_PACKAGE_NAME}`,
+            allCommands: {
+                dshCli: `pnpm dsh plugin update ${PLUGIN_PACKAGE_NAME}`,
+                profile: `dsh plugin --profile default add ${PLUGIN_PACKAGE_NAME}@latest`,
+                pnpm: `pnpm add ${PLUGIN_PACKAGE_NAME}@latest`,
+                npm: `npm install -g ${PLUGIN_PACKAGE_NAME}@latest`,
+            },
+            releaseNotesUrl: `${NPM_PACKAGE_URL}?activeTab=versions`,
+            checkedAt: 0,
+        };
+    }
+    /**
+     * 异步触发版本检测
+     * @param force 是否忽略 24h 缓存强制穿透探测
+     */
+    async check(force = false) {
+        const now = Date.now();
+        // 1. 命中有效缓存直接返回
+        if (!force && this.cachedInfo && now - this.cachedInfo.checkedAt < this.intervalMs) {
+            return this.cachedInfo;
+        }
+        // 2. 复用正在途中的网络请求，避免并发重复打 npm
+        if (this.inFlightPromise) {
+            return this.inFlightPromise;
+        }
+        this.inFlightPromise = this.performCheck(now).finally(() => {
+            this.inFlightPromise = null;
+        });
+        return this.inFlightPromise;
+    }
+    /**
+     * 内部双 Registry 竞速/降级探测
+     */
+    async performCheck(now) {
+        const fallback = this.getQuickStatus();
+        // 双通道策略：用户自定义源 > 国内淘宝镜像 (2.5s极速) > 官方 npmjs 源 (3.5s兜底)
+        const endpoints = [];
+        if (this.customRegistry) {
+            endpoints.push(`${this.customRegistry.replace(/\/$/, '')}/${PLUGIN_PACKAGE_NAME}/latest`);
+        }
+        else {
+            endpoints.push(`${NPM_REGISTRY_MIRROR}/${PLUGIN_PACKAGE_NAME}/latest`);
+            endpoints.push(`${NPM_REGISTRY_OFFICIAL}/${PLUGIN_PACKAGE_NAME}/latest`);
+        }
+        let latestVersion = null;
+        for (const url of endpoints) {
+            try {
+                const isMirror = url.includes('npmmirror');
+                const timeoutMs = isMirror ? 2_500 : 3_500;
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), timeoutMs);
+                const res = await fetch(url, {
+                    signal: controller.signal,
+                    headers: {
+                        'Accept': 'application/json',
+                        'User-Agent': `dsh-plugin-updater/${CURRENT_PLUGIN_VERSION}`,
+                    },
+                });
+                clearTimeout(timer);
+                if (res.ok) {
+                    const json = (await res.json());
+                    if (json && typeof json.version === 'string' && json.version.trim()) {
+                        latestVersion = json.version.trim();
+                        break;
+                    }
+                }
+            }
+            catch {
+                // 单个源故障静默尝试下一个备用源，确保高可用
+            }
+        }
+        // 若双源均未拉取到版本，保留保底数据并记录时间戳，防止密集重试
+        if (!latestVersion) {
+            this.cachedInfo = {
+                ...fallback,
+                checkedAt: now,
+            };
+            return this.cachedInfo;
+        }
+        const hasUpdate = isNewerVersion(CURRENT_PLUGIN_VERSION, latestVersion);
+        const targetPkg = `${PLUGIN_PACKAGE_NAME}@${latestVersion}`;
+        this.cachedInfo = {
+            currentVersion: CURRENT_PLUGIN_VERSION,
+            latestVersion,
+            hasUpdate,
+            upgradeCommand: `pnpm dsh plugin add ${targetPkg}`,
+            allCommands: {
+                dshCli: `pnpm dsh plugin add ${targetPkg}`,
+                profile: `dsh plugin --profile default add ${targetPkg}`,
+                pnpm: `pnpm add ${targetPkg}`,
+                npm: `npm install -g ${targetPkg}`,
+            },
+            releaseNotesUrl: `${NPM_PACKAGE_URL}?activeTab=versions`,
+            checkedAt: now,
+        };
+        return this.cachedInfo;
+    }
+}

package/lib/upgrade-manager.d.ts

@@ -0,0 +1,54 @@
+import type { UpgradeExecutionResult, UpgradeStatusResult } from './types.js';
+/**
+ * 构建跨平台环境自愈增强的 ProcessEnv (重点解决 macOS GUI 应用丢失 PATH 的痛点)
+ *
+ * 为什么必须这样做：
+ * 1. 在 macOS 系统上，若 DSH 桌面客户端由 Finder / Dock / Spotlight (GUI) 启动，进程默认只继承
+ *    极简系统 PATH (/usr/bin:/bin:/usr/sbin:/sbin)，不会自动读取用户 shell 配置文件 (~/.zshrc, ~/.bash_profile)；
+ * 2. 用户通过 Homebrew (/opt/homebrew/bin 或 /usr/local/bin) 或 nvm 安装的 node、npm、pnpm 默认在 GUI 下不可见；
+ * 3. 动态将当前 node 运行时所在目录 (path.dirname(process.execPath)) 及 Mac 常用包管理器路径注入 PATH 首端，
+ *    彻底实现 macOS 与 Linux 环境下子进程对 npm / pnpm 命令的 100% 自愈发现。
+ */
+export declare function buildCrossPlatformEnv(): NodeJS.ProcessEnv;
+/**
+ * 自动升级执行引擎
+ *
+ * 核心设计考量与约束条件：
+ * 1. 互斥保护 (Mutex)：同一时刻仅允许一个升级任务执行，防止用户连击或并发请求击垮包管理器 lockfile；
+ * 2. 环境自省 (Dev-Link Safe)：检测是否在本地源码工作区调试，若是则阻断自动覆盖，保护源码不被破坏；
+ * 3. 跨平台兼容 (macOS / Windows / Linux)：自动适配 cmd.exe 与 sh/zsh，自愈补全 macOS PATH 变量；
+ * 4. 稳态超时：设置 60s 进程上限，杜绝子进程因网络悬挂死锁宿主 WebServer；
+ * 5. 重启指引：Node.js 运行时内存不可变，升级成功后明确要求重启 DSH 彻底加载最新后端能力。
+ */
+export declare class UpgradeManager {
+    private isUpgrading;
+    private lastResult;
+    private logBuffer;
+    /**
+     * 探测当前插件是否是以本地 Git 源码软链接方式运行
+     */
+    isDevLinked(): boolean;
+    /**
+     * 智能识别当前 DSH 运行环境 (桌面版 vs Web/CLI 版)
+     *
+     * 依据事实源：
+     * 1. 桌面版启动时会固定注入 DSH_PROFILE=desktop 与 DSH_PROFILE_DIR (~/.dsh/profiles/desktop)；
+     * 2. Web版/CLI版通常 DSH_PROFILE 为 default 或自定义工作区 profile；
+     * 3. 跨平台支持：通过 os.homedir() 安全解析 ~/.dsh 目录。
+     */
+    detectEnvironment(): {
+        isDesktop: boolean;
+        profile: string;
+        profileDir?: string;
+        isDevLinked: boolean;
+        platform: NodeJS.Platform;
+    };
+    /**
+     * 获取当前升级状态
+     */
+    getStatus(): UpgradeStatusResult;
+    /**
+     * 执行一键升级核心流程
+     */
+    executeUpgrade(targetVersion?: string): Promise<UpgradeExecutionResult>;
+}