dsh-github-flow 0.4.0 → 0.5.0

package/lib/ui/utils.js

@@ -64,3 +64,163 @@ export function eventLabel(event) {
         return "🔀 PR";
     return e || "";
 }
+/**
+ * 带有阶梯退避重试（Backoff Retry）的通用异步拉取函数
+ *
+ * 核心设计理由与约束：
+ * 1. 应对代理节点不稳定、TLS 握手卡顿、短时网络抖动（半秒至两秒微断流）；
+ * 2. 阶梯退避时序：第 1 次失败等 1s (1000ms)，第 2 次等 2s (2000ms)，第 3 次等 4s (4000ms)，附加 0~200ms Jitter；
+ * 3. 智能区分软硬错误：401/403/404/400 确定性错误坚决不重试，仅在网络超时、不可达、或带有 networkError 时重试；
+ * 4. 严格响应外部 AbortSignal，组件卸载或用户手动打断时立即退出等待，绝无内存泄漏。
+ */
+export async function fetchWithRetry(url, options = {}, config = {}) {
+    var maxRetries = config.maxRetries !== undefined ? config.maxRetries : 3;
+    var baseDelayMs = config.baseDelayMs !== undefined ? config.baseDelayMs : 1000;
+    var signal = config.signal || options.signal;
+    var attempt = 0;
+    while (true) {
+        attempt++;
+        var currentRes = null;
+        var currentJson = null;
+        var failureReason = "";
+        var shouldRetry = false;
+        try {
+            if (signal && signal.aborted) {
+                throw new Error("Aborted");
+            }
+            currentRes = await fetch(url, { ...options, signal });
+            // 硬错误守卫：客户端确定性错误（如未授权、权限拒绝、不存在、参数错误）坚决不重试
+            if (currentRes.status === 401 || currentRes.status === 403 || currentRes.status === 404 || currentRes.status === 400) {
+                currentJson = await currentRes.json().catch(() => ({}));
+                return { res: currentRes, json: currentJson };
+            }
+            if (!currentRes.ok) {
+                failureReason = "HTTP " + currentRes.status + " " + currentRes.statusText;
+                shouldRetry = true;
+            }
+            else {
+                currentJson = await currentRes.json().catch(() => null);
+                // 业务层软错误检测（后端返回了 200，但标记了 networkError 或 partialFailure）
+                var isNetworkError = Boolean(currentJson && (currentJson.partialFailure ||
+                    currentJson.data?.partialFailure ||
+                    currentJson.data?.networkError ||
+                    currentJson.data?.auth?.networkError));
+                if (isNetworkError) {
+                    failureReason = currentJson.error || currentJson.data?.networkErrorReason || "云端接口网络抖动";
+                    shouldRetry = true;
+                }
+                else {
+                    // 成功获取完整且无网络错误的数据
+                    return { res: currentRes, json: currentJson };
+                }
+            }
+        }
+        catch (err) {
+            if ((signal && signal.aborted) || err.name === "AbortError") {
+                throw err;
+            }
+            failureReason = err.message || "网络连接中断或超时";
+            shouldRetry = true;
+        }
+        // 判断是否已耗尽重试次数
+        if (!shouldRetry || attempt > maxRetries) {
+            if (currentRes) {
+                return { res: currentRes, json: currentJson || {} };
+            }
+            throw new Error(failureReason || "网络请求失败");
+        }
+        // 计算阶梯退避等待时间：baseDelayMs * 2^(attempt - 1) + Jitter 自适应微扰
+        var exponentialDelay = baseDelayMs * Math.pow(2, attempt - 1);
+        var maxJitter = Math.min(200, Math.floor(exponentialDelay * 0.2));
+        var jitter = Math.floor(Math.random() * (maxJitter + 1));
+        var totalDelay = exponentialDelay + jitter;
+        if (config.onRetry) {
+            config.onRetry(attempt, totalDelay, failureReason);
+        }
+        // 可中断的睡眠等待
+        await new Promise((resolve, reject) => {
+            var timer = setTimeout(resolve, totalDelay);
+            if (signal) {
+                signal.addEventListener("abort", () => {
+                    clearTimeout(timer);
+                    reject(new Error("Aborted"));
+                }, { once: true });
+            }
+        });
+    }
+}
+export function parseGitStatText(statText) {
+    if (!statText || typeof statText !== "string")
+        return null;
+    var lines = statText.split("\n");
+    var files = [];
+    var summary = null;
+    for (var i = 0; i < lines.length; i++) {
+        var line = lines[i].trim();
+        if (!line)
+            continue;
+        var summaryMatch = line.match(/(\d+)\s+files?\s+changed(?:,\s+(\d+)\s+insertions?\(\+\))?(?:,\s+(\d+)\s+deletions?\(-\))?/i);
+        if (summaryMatch) {
+            summary = {
+                filesChanged: parseInt(summaryMatch[1], 10),
+                insertions: parseInt(summaryMatch[2] || "0", 10),
+                deletions: parseInt(summaryMatch[3] || "0", 10),
+            };
+            continue;
+        }
+        var pipeIdx = line.indexOf("|");
+        if (pipeIdx > 0) {
+            var left = line.slice(0, pipeIdx).trim();
+            var right = line.slice(pipeIdx + 1).trim();
+            if (left.startsWith('"') && left.endsWith('"') && left.length >= 2) {
+                left = left.slice(1, -1);
+            }
+            if (/^Bin\b/i.test(right)) {
+                files.push({ path: left, total: 0, additions: 0, deletions: 0, isBinary: true, rawRight: right });
+            }
+            else {
+                var numMatch = right.match(/^(\d+)(.*)$/);
+                if (numMatch) {
+                    var total = parseInt(numMatch[1], 10);
+                    var graph = numMatch[2].trim();
+                    var plusCount = 0;
+                    var minusCount = 0;
+                    for (var j = 0; j < graph.length; j++) {
+                        if (graph[j] === "+")
+                            plusCount++;
+                        else if (graph[j] === "-")
+                            minusCount++;
+                    }
+                    var additions = 0;
+                    var deletions = 0;
+                    if (plusCount === 0 && minusCount === 0) {
+                        additions = total;
+                    }
+                    else if (minusCount === 0) {
+                        additions = total;
+                        deletions = 0;
+                    }
+                    else if (plusCount === 0) {
+                        additions = 0;
+                        deletions = total;
+                    }
+                    else {
+                        if (plusCount + minusCount === total) {
+                            additions = plusCount;
+                            deletions = minusCount;
+                        }
+                        else {
+                            var addExact = Math.round((total * plusCount) / (plusCount + minusCount));
+                            additions = addExact;
+                            deletions = Math.max(0, total - addExact);
+                        }
+                    }
+                    files.push({ path: left, total, additions, deletions, isBinary: false });
+                }
+            }
+        }
+    }
+    if (files.length === 0 && !summary)
+        return null;
+    return { files, summary };
+}

package/lib/ui/workspace-panel.js

@@ -11,6 +11,7 @@ export function GithubWorkspacePanel() {
     var [lastSyncedAt, setLastSyncedAt] = React.useState(initialSnapshot?.savedAt || 0);
     var [isSettingsModalOpen, setIsSettingsModalOpen] = React.useState(false);
     var [settingsInitialSection, setSettingsInitialSection] = React.useState("sync");
+    var [isHelpModalOpen, setIsHelpModalOpen] = React.useState(false);
     var [error, setError] = React.useState(null);
     var [updateInfo, setUpdateInfo] = React.useState(null);
     var [activeTab, setActiveTab] = React.useState("workspaces");
@@ -104,9 +105,18 @@ export function GithubWorkspacePanel() {
             if (forceRefresh) {
                 url += "?force=true";
             }
-            var res = await fetch(url, { signal: controller.signal });
+            // 接入 1s/2s/4s 阶梯退避重试，平滑吸收代理节点与网络的偶发抖动断流
+            var { res, json } = await fetchWithRetry(url, {}, {
+                signal: controller.signal,
+                maxRetries: 3,
+                baseDelayMs: 1000,
+                onRetry: (attempt) => {
+                    setSyncStatus("syncing");
+                    setError(`网络抖动，正在自愈重试 (${attempt}/3)...`);
+                },
+            });
             if (!res.ok) {
-                var errText = await res.text().catch(() => "");
+                var errText = (typeof json === "string" ? json : JSON.stringify(json)) || res.statusText;
                 var failMsg = `获取全局数据失败（HTTP ${res.status}）${errText ? ": " + errText : ""}`;
                 setSyncStatus("failed");
                 setError(failMsg);
@@ -114,7 +124,6 @@ export function GithubWorkspacePanel() {
                     showToast("❌ 刷新失败：" + failMsg);
                 return;
             }
-            var json = await res.json();
             if (json.ok && json.data) {
                 var isFail = Boolean(json.partialFailure ||
                     json.data.partialFailure ||
@@ -241,8 +250,16 @@ export function GithubWorkspacePanel() {
                     .catch(function () { });
             }
         };
+        var onOnline = () => {
+            // 监听网络由断网恢复连接瞬间，自动静默发起一次全量同步，消除离线警告横幅并拉新
+            loadData(false);
+        };
         window.addEventListener("focus", onFocus);
-        return () => window.removeEventListener("focus", onFocus);
+        window.addEventListener("online", onOnline);
+        return () => {
+            window.removeEventListener("focus", onFocus);
+            window.removeEventListener("online", onOnline);
+        };
     }, [data, loadData]);
     var h = React.createElement;
     var headerEl = h("div", { className: "dsh-github-header" }, h("div", { className: "dsh-github-title" }, renderOctocatBadge(32), h("h2", null, "GitHub 全景驾驶舱"), renderPluginBadge(h), h(SyncStatusBadge, { syncStatus, lastSyncedAt }), proxyActive && proxyActive.enabled
@@ -267,6 +284,11 @@ export function GithubWorkspacePanel() {
         onClick: () => loadData(true),
         disabled: loading,
     }, loading ? "同步中..." : "🔄 刷新全局数据"), h("button", {
+        className: "dsh-github-btn-sm",
+        onClick: () => setIsHelpModalOpen(true),
+        title: "打开使用帮助与实战手册大窗口（Esc 可退出）",
+        style: { padding: "6px 12px" },
+    }, "📖 使用指南"), h("button", {
         className: "dsh-github-btn-sm",
         onClick: openSettingsDefault,
         title: "配置数据同步节奏、本地缓存、网络代理与插件信息",
@@ -460,5 +482,8 @@ export function GithubWorkspacePanel() {
             },
         })
         : null;
-    return h("div", { className: "dsh-github-panel", ref: panelRef }, toastEl, headerEl, networkAlertBannerEl, upgradeBannerEl, errorEl, statsCardsEl, authGuideEl, tabsEl, contentEl, settingsModalEl);
+    return h("div", { className: "dsh-github-panel", ref: panelRef }, toastEl, headerEl, networkAlertBannerEl, upgradeBannerEl, errorEl, statsCardsEl, authGuideEl, tabsEl, contentEl, settingsModalEl, h(GithubHelpModal, {
+        isOpen: isHelpModalOpen,
+        onClose: () => setIsHelpModalOpen(false),
+    }));
 }

package/lib/upgrade-manager.d.ts

@@ -1,5 +1,9 @@
-import type { UpgradeExecutionResult, UpgradeStatusResult } from './types.js';
+import type { UpgradeExecutionResult, UpgradeStatusResult, UpgradeErrorType } from './types.js';
 import type { ProxyManager } from './proxy.js';
+/**
+ * 分析升级失败日志中的深层错误特征（重点识别 DSH 内置包管理器 minimumReleaseAge 24 小时防投毒策略）
+ */
+export declare function detectUpgradeErrorType(log?: string): UpgradeErrorType;
 /**
  * 构建跨平台环境自愈增强的 ProcessEnv (重点解决 macOS GUI 应用丢失 PATH 的痛点)
  *

package/lib/upgrade-manager.js

@@ -4,6 +4,20 @@ import fs from 'node:fs';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { PLUGIN_PACKAGE_NAME } from './version.js';
+/**
+ * 分析升级失败日志中的深层错误特征（重点识别 DSH 内置包管理器 minimumReleaseAge 24 小时防投毒策略）
+ */
+export function detectUpgradeErrorType(log) {
+    if (!log)
+        return 'UNKNOWN';
+    if (/ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION|minimumReleaseAge/i.test(log)) {
+        return 'MINIMUM_RELEASE_AGE_VIOLATION';
+    }
+    if (/ETIMEDOUT|timeout|执行超时/i.test(log)) {
+        return 'TIMEOUT';
+    }
+    return 'UNKNOWN';
+}
 /**
  * 构建跨平台环境自愈增强的 ProcessEnv (重点解决 macOS GUI 应用丢失 PATH 的痛点)
  *
@@ -370,10 +384,18 @@ export class UpgradeManager {
             this.lastResult = { state: 'success', targetVersion: wantVersion, message: successMsg, completedAt, environment: env.isDesktop ? 'desktop' : 'web' };
         }
         else {
+            const fullLog = this.logBuffer.join('\n');
+            const errorType = detectUpgradeErrorType(fullLog);
+            let failMsg = `升级失败（安装命令返回非零退出码）。${targetVersion ? `目标版本 ${targetVersion} 未安装成功。` : ''}${actionHint}，或稍后重试一键升级。`;
+            // 智能识别：DSH 内置包管理器 minimumReleaseAge 24 小时防投毒安全锁机制
+            if (errorType === 'MINIMUM_RELEASE_AGE_VIOLATION') {
+                failMsg = `🛡️ 触发 DSH 新版本 24 小时安全保护期（npm 供应链防投毒策略）。检测到目标版本刚刚发布未满 24 小时，DSH 内置包管理器暂缓了自动静默升级以保障系统安全。\n【推荐解决步骤】：\n1. 立即尝鲜：请先【完全退出关闭 DSH 应用程序】，然后在系统终端执行手动安装命令（点击「📋 复制命令」获取）；\n2. 稍后升级：无需操作，发版满 24 小时后直接在此点击「⚡ 一键自动升级」即可平滑完成。`;
+            }
             this.lastResult = {
                 state: 'failed',
                 targetVersion,
-                message: `升级失败（安装命令返回非零退出码）。${targetVersion ? `目标版本 ${targetVersion} 未安装成功。` : ''}${actionHint}，或稍后重试一键升级。`,
+                errorType,
+                message: failMsg,
                 completedAt,
                 environment: env.isDesktop ? 'desktop' : 'web',
             };
@@ -581,6 +603,7 @@ export class UpgradeManager {
                         ok: false,
                         message: this.lastResult.message || `升级退出码异常 (${code})`,
                         needRestart: false,
+                        errorType: this.lastResult.errorType,
                         environment: env.isDesktop ? 'desktop' : 'web',
                         log: this.logBuffer.join('\n'),
                     };

package/lib/version.d.ts

@@ -6,7 +6,7 @@
  * 2. 避免在 ESM 运行时动态读取 package.json 引入 fs 权限和路径解析边界问题；
  * 3. 方便在 CI 发布流水线或 build 脚本中自动化校准。
  */
-export declare const CURRENT_PLUGIN_VERSION = "0.4.0";
+export declare const CURRENT_PLUGIN_VERSION = "0.5.0";
 export declare const PLUGIN_PACKAGE_NAME = "dsh-github-flow";
 export declare const NPM_PACKAGE_URL = "https://www.npmjs.com/package/dsh-github-flow";
 export declare const NPM_REGISTRY_MIRROR = "https://registry.npmmirror.com";

package/lib/version.js

@@ -6,7 +6,7 @@
  * 2. 避免在 ESM 运行时动态读取 package.json 引入 fs 权限和路径解析边界问题；
  * 3. 方便在 CI 发布流水线或 build 脚本中自动化校准。
  */
-export const CURRENT_PLUGIN_VERSION = '0.4.0';
+export const CURRENT_PLUGIN_VERSION = '0.5.0';
 export const PLUGIN_PACKAGE_NAME = 'dsh-github-flow';
 export const NPM_PACKAGE_URL = 'https://www.npmjs.com/package/dsh-github-flow';
 export const NPM_REGISTRY_MIRROR = 'https://registry.npmmirror.com';

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsh-github-flow",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "icon": "icon.svg",
-  "description": "GitHub 工作流引擎：为 DeepSeek Harness 提供原生 GitHub CLI (gh) 集成——9 大 Agent 领域工具（PR 审查合并、Issue 任务流转、CI 失败诊断、发版交付、密钥管理、Agent Skills 生态）、/gh 人类快捷指令、Web UI 全景驾驶舱与一键跨平台自动升级；零凭证侵入复用宿主机 gh 登录态，内置 Token 防溢出截断、高危操作二次确认与密文安全输入通道。",
+  "description": "GitHub 工作流引擎：为 DeepSeek Harness 提供原生 GitHub CLI (gh) 集成——18 大 Agent 领域工具（PR 审查合并、Issue 任务流转、CI 失败诊断、发版交付、密钥管理、Agent Skills、标签与保护规则集、构建缓存治理、代码片段 Gist、跨仓待办大盘、Copilot 智能体调度、社区 Discussions、Projects v2 看板、云端 Codespaces、运行时遥测与自愈健康度）、/gh 人类快捷指令、Web UI 全景驾驶舱与一键跨平台自动升级；零凭证侵入复用宿主机 gh 登录态，内置 Token 防溢出截断、高危操作二次确认与密文安全输入通道。",
   "type": "module",
   "main": "./lib/main.js",
   "repository": {