dsh-github-flow 0.1.5 → 0.1.6

package/README.en.md

@@ -32,7 +32,12 @@
    - **Global Cockpit** (`sidebar.panellist`, Order 20): Account-wide repository overview, local workspace matrix, and pending personal PRs/issues.
    - **Right Sidebar Panel** (`sidebarRightTabs`, Order 40): Shows current repository status, PR list with CI check pills, and a 2x2 quick action grid (Open Repo, View PRs, Create PR, New Issue) with zero popup dependencies.
    - **Native Light/Dark Dual-Theme Adaptation**: Deeply aligned with DSH official DSW (DeepSeek Web) design tokens, seamlessly reacting to `body[data-ds-dark-theme]` without lag or flickering.
-5. **Standard Cordis Microkernel Compliance**:
+5. **Robust Environment Diagnosis & Three-State Setup Engine**:
+   - Zero-guesswork onboarding: Accurately differentiates `NOT_INSTALLED` (`Missing`), `NOT_LOGGED_IN` (`Required`), and `AUTHENTICATED` (`Active`).
+   - OS-aware installation guides: Auto-detects platform (Windows/macOS/Linux) and suggests native package manager commands (`winget install --id GitHub.cli`, `brew install gh`) with official installer links.
+   - Interactive helpers: One-click command copying and security-whitelisted terminal launcher.
+   - **Focus Auto-Recovery**: Automatically detects authorization completion when returning to the DSH window, transitioning to full workspace view without manual page reloads.
+6. **Standard Cordis Microkernel Compliance**:
    - Exposes native `GitHubService` (`ctx.github`) for ecosystem extensibility;
    - Strongly typed runtime validation via Standard Schema (`Config`);
    - Domain event broadcasting (`github/pr:create`, `github/issue:create`).

package/README.md

@@ -32,7 +32,12 @@
    - **全局驾驶舱**（主导航栏 `sidebar.panellist`，Order 20）：透视账号全局仓库、本地工作区矩阵、个人待办 PR 与 Issues；
    - **右侧栏工作区面板**（`sidebarRightTabs`，Order 40）：常驻呈现当前仓库的 PR 状态、Checks 门禁药丸与 2x2 黄金快捷网格（浏览器打开、查看 PRs、快速创建 PR、新建 Issue），一键直达官方比对与创建页，零弹窗依赖；
    - **全场景双模式原生自适应**：深度契合 DSH 官方 DSW（DeepSeek Web）设计变量规范，通过 `body[data-ds-dark-theme]` 驱动浅色与深色主题实时零延迟平滑切换。
-5. **符合 Cordis 官方微内核架构**：
+5. **健全的环境诊断与三态就绪引导 (Three-State Setup Engine)**：
+   - 告别空状态困惑：精准建立「未安装 CLI (`Missing`)」➜「已安装未登录 (`Required`)」➜「已认证就绪 (`Active`)」三态状态机；
+   - 自动识别宿主机操作系统（Windows/macOS/Linux），按平台提供包管理器安装命令（Windows 下 `winget install --id GitHub.cli`、macOS 下 `brew install gh`）与官方安装包直达；
+   - 支持一键复制命令与安全白名单系统终端一键唤起；
+   - 具备**窗口焦点自愈（Focus Auto-Recovery）**机制：切到外部终端或浏览器授权完毕后，切回 DSH 界面自动探测刷新，无感恢复。
+6. **符合 Cordis 官方微内核架构**：
    - 暴露原生 `GitHubService`（`ctx.github`），允许生态其他插件复用；
    - 具备符合 Standard Schema 规范的运行时配置校验（`Config`）；
    - 支持领域事件系统（`github/pr:create`, `github/issue:create`）。

package/docs/architecture.md

@@ -73,3 +73,9 @@
 - **服务依赖就绪**：声明 `['tools', 'commands', 'webServer', 'workspaceRegistry']`，确保 Web 路由与命令服务在环境就绪后激活；
 - **生命周期 Effect 闭环**：所有 HTTP 路由与命令注册均持有 Disposer 清理函数，插件热重载或重新挂载时自动彻底注销，零内存泄漏；
 - **配置自校验与服务暴露**：基于 Standard Schema 规范实现强类型校验与默认值注入，通过 `ctx.provide('github', executor)` 向生态插件暴露单例服务。
+
+### 2.6 三态环境诊断与交互引导状态机 (Setup & Authentication Lifecycle Guard)
+- **三态状态模型 (Three-State Machine)**：将环境就绪判定严格划分为 `NOT_INSTALLED`（未安装 CLI）、`NOT_LOGGED_IN`（已安装未登录）、`AUTHENTICATED`（已认证）三态，彻底消除“把未安装当作未登录”的状态屏蔽隐患；
+- **平台自适应安装策略**：后端探测到 `ENOENT` 时根据 `process.platform` 组装对应平台的安装命令（Windows: `winget`，macOS: `brew`，Linux: `apt/dnf`）与官方安装包地址；
+- **安全辅助与白名单终端唤起**：Web 端提供一键命令复制，后端 `/api/github/action` 提供 `open_terminal` 安全白名单唤起接口（只允许预设命令），避免在前端模拟复杂交互式 PTY 的脆弱性；
+- **焦点感知自愈 (Focus Auto-Recovery)**：前端挂载 `window.focus` 事件监听，用户在外部浏览器或终端完成认证后切回 DSH 界面，自动静默重新探测并无缝更新 UI，实现零摩擦闭环体验。

package/lib/api/routes.js

@@ -212,6 +212,41 @@ export function registerApiRoutes(ctxOrWebServer, executor, workspaceRegistry, c
                             sendJson(res, 200, { ok: true, message: '已在浏览器打开' });
                             break;
                         }
+                        case 'open_terminal': {
+                            const command = typeof payload.command === 'string' ? payload.command.trim() : 'gh auth login';
+                            // 严格白名单过滤，严防任意命令注入
+                            const allowedCommands = [
+                                'gh auth login',
+                                'winget install --id GitHub.cli',
+                                'brew install gh',
+                                'sudo apt install gh',
+                                'sudo dnf install gh',
+                            ];
+                            if (!allowedCommands.includes(command)) {
+                                throw new Error(`不支持唤起该指令: ${command}`);
+                            }
+                            const { execFile } = await import('node:child_process');
+                            let bin = 'cmd';
+                            let args = [];
+                            if (process.platform === 'win32') {
+                                bin = 'cmd';
+                                args = ['/c', 'start', 'powershell', '-NoExit', '-Command', command];
+                            }
+                            else if (process.platform === 'darwin') {
+                                bin = 'osascript';
+                                args = ['-e', `tell application "Terminal" to do script "${command}"`, '-e', 'tell application "Terminal" to activate'];
+                            }
+                            else {
+                                bin = 'x-terminal-emulator';
+                                args = ['-e', command];
+                            }
+                            execFile(bin, args, (err) => {
+                                if (err)
+                                    console.warn('[dsh-github-flow] 唤起终端失败:', err?.message || err);
+                            });
+                            sendJson(res, 200, { ok: true, message: '已请求唤起系统终端' });
+                            break;
+                        }
                         default:
                             sendJson(res, 400, { ok: false, message: `未知的操作类型: ${payload.action}` });
                     }

package/lib/client.js

@@ -633,6 +633,110 @@ body[data-ds-dark-theme] .dsh-github-repo-link {
 body[data-ds-dark-theme] .dsh-github-subheading {
   color: var(--dsw-alias-label-primary, #f0f6fc);
 }
+
+/* 15. 就绪引导横幅 (Setup Guide Banner) */
+.dsh-github-guide-card {
+  padding: 16px;
+  border-radius: 8px;
+  margin-bottom: 16px;
+  border: 1px solid var(--dsw-alias-border-l2, #d0d7de);
+  background: var(--dsw-alias-bg-layer-1, #f6f8fa);
+}
+.dsh-github-guide-card.warning {
+  border-color: rgba(210, 153, 34, 0.4);
+  background: rgba(210, 153, 34, 0.08);
+}
+.dsh-github-guide-card.danger {
+  border-color: rgba(248, 81, 73, 0.4);
+  background: rgba(248, 81, 73, 0.08);
+}
+.dsh-github-guide-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 15px;
+  font-weight: 600;
+  margin-bottom: 6px;
+  color: var(--dsw-alias-label-primary, #1f2328);
+}
+body[data-ds-dark-theme] .dsh-github-guide-header {
+  color: var(--dsw-alias-label-primary, #f0f6fc);
+}
+.dsh-github-guide-desc {
+  font-size: 13px;
+  color: var(--dsw-alias-label-secondary, #656d76);
+  line-height: 1.5;
+  margin-bottom: 12px;
+}
+body[data-ds-dark-theme] .dsh-github-guide-desc {
+  color: var(--dsw-alias-label-secondary, #8c8c8c);
+}
+.dsh-github-cmd-box {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  background: var(--dsw-alias-bg-base, #ffffff);
+  border: 1px solid var(--dsw-alias-border-l2, #d0d7de);
+  border-radius: 6px;
+  padding: 8px 12px;
+  font-family: var(--ds-font-family-code, monospace);
+  font-size: 13px;
+  color: var(--dsw-alias-label-primary, #1f2328);
+  margin-bottom: 12px;
+}
+body[data-ds-dark-theme] .dsh-github-cmd-box {
+  background: var(--dsw-alias-bg-layer-2, #161b22);
+  border-color: var(--dsw-alias-border-l1, #30363d);
+  color: var(--dsw-alias-label-primary, #f0f6fc);
+}
+.dsh-github-copy-btn {
+  padding: 4px 10px;
+  font-size: 12px;
+  border-radius: 4px;
+  border: 1px solid var(--dsw-alias-border-l2, #d0d7de);
+  background: var(--dsw-alias-bg-layer-1, #f6f8fa);
+  color: var(--dsw-alias-label-primary, #1f2328);
+  cursor: pointer;
+  white-space: nowrap;
+  transition: all 0.15s ease;
+}
+body[data-ds-dark-theme] .dsh-github-copy-btn {
+  background: var(--dsw-alias-bg-layer-2, #21262d);
+  border-color: var(--dsw-alias-border-l1, #30363d);
+  color: var(--dsw-alias-label-primary, #c9d1d9);
+}
+.dsh-github-copy-btn:hover {
+  background: var(--dsw-alias-interactive-bg-hover, #ebeef1);
+}
+body[data-ds-dark-theme] .dsh-github-copy-btn:hover {
+  background: #30363d;
+}
+.dsh-github-copy-btn.copied {
+  color: #2da44e !important;
+  border-color: #2da44e !important;
+  background: rgba(45, 164, 78, 0.15) !important;
+}
+.dsh-github-steps-list {
+  font-size: 12px;
+  color: var(--dsw-alias-label-secondary, #656d76);
+  line-height: 1.6;
+  margin: 0 0 12px 18px;
+  padding: 0;
+}
+body[data-ds-dark-theme] .dsh-github-steps-list {
+  color: var(--dsw-alias-label-secondary, #8c8c8c);
+}
+.dsh-github-guide-actions {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+.dsh-github-guide-tip {
+  font-size: 11px;
+  color: var(--dsw-alias-label-tertiary, #8c8c8c);
+  margin-top: 10px;
+  line-height: 1.4;
+}
 `;
         function injectStyles() {
             var styleId = "dsh-plugin-github-styles";
@@ -672,6 +776,120 @@ body[data-ds-dark-theme] .dsh-github-subheading {
                 }
             }, renderOctocat(Math.round(size * 0.58), "#ffffff"));
         }
+        // 认证与安装引导卡片组件（响应式自适应中央大面板与右侧栏）
+        function AuthGuideCard(props) {
+            var auth = props ? props.auth : null;
+            var onRefresh = props ? props.onRefresh : () => { };
+            var isRightbar = Boolean(props && props.isRightbar);
+            var [copied, setCopied] = React.useState(false);
+            var [launching, setLaunching] = React.useState(false);
+            var [toastMsg, setToastMsg] = React.useState(null);
+            var notInstalled = !auth?.installed;
+            var guide = auth?.installGuide;
+            var defaultCmd = notInstalled
+                ? (guide?.command || "winget install --id GitHub.cli")
+                : "gh auth login";
+            var copyCmd = (cmd) => {
+                try {
+                    if (navigator && navigator.clipboard && navigator.clipboard.writeText) {
+                        navigator.clipboard.writeText(cmd);
+                    }
+                    else {
+                        var input = document.createElement("textarea");
+                        input.value = cmd;
+                        document.body.appendChild(input);
+                        input.select();
+                        document.execCommand("copy");
+                        document.body.removeChild(input);
+                    }
+                    setCopied(true);
+                    setTimeout(() => setCopied(false), 2000);
+                }
+                catch (e) {
+                    console.warn("复制失败:", e);
+                }
+            };
+            var launchTerminal = async (cmd) => {
+                setLaunching(true);
+                setToastMsg(null);
+                try {
+                    var res = await fetch("/api/github/action", {
+                        method: "POST",
+                        headers: { "Content-Type": "application/json" },
+                        body: JSON.stringify({ action: "open_terminal", command: cmd })
+                    });
+                    var json = await res.json();
+                    if (json.ok) {
+                        setToastMsg("已唤起系统终端，请在弹出窗口中完成操作");
+                        setTimeout(() => setToastMsg(null), 4000);
+                    }
+                    else {
+                        setToastMsg(json.message || "唤起失败，请在终端手动运行");
+                    }
+                }
+                catch (e) {
+                    setToastMsg("无法连接后台服务，请在终端手动运行");
+                }
+                finally {
+                    setLaunching(false);
+                }
+            };
+            var openDownload = async () => {
+                var url = guide?.downloadUrl || "https://cli.github.com/";
+                try {
+                    await fetch("/api/github/action", {
+                        method: "POST",
+                        headers: { "Content-Type": "application/json" },
+                        body: JSON.stringify({ action: "open_browser", url })
+                    });
+                }
+                catch (e) {
+                    window.open(url, "_blank", "noopener,noreferrer");
+                }
+            };
+            var h = React.createElement;
+            return h("div", {
+                className: "dsh-github-guide-card " + (notInstalled ? "danger" : "warning"),
+                style: isRightbar ? { padding: "12px", marginBottom: "12px" } : undefined
+            }, 
+            // 头部
+            h("div", { className: "dsh-github-guide-header" }, notInstalled ? "⚠️ 未检测到 GitHub CLI (gh)" : "🔑 GitHub 账号尚未登录", h("span", { className: "dsh-github-badge " + (notInstalled ? "dsh-badge-red" : "dsh-badge-yellow") }, notInstalled ? "未安装" : "未认证")), 
+            // 描述
+            h("div", { className: "dsh-github-guide-desc" }, notInstalled
+                ? (guide?.description || "DSH GitHub Flow 插件依赖官方 GitHub CLI 工具与云端进行安全交互，当前系统 PATH 中未检测到该工具。")
+                : "检测到本机已安装 GitHub CLI，请完成账号授权以解锁仓库管理、PR 审查和 Issues 待办。"), 
+            // 命令代码展示框
+            h("div", { className: "dsh-github-cmd-box" }, h("code", null, defaultCmd), h("button", {
+                className: "dsh-github-copy-btn " + (copied ? "copied" : ""),
+                onClick: () => copyCmd(defaultCmd),
+                title: "复制命令到剪贴板"
+            }, copied ? "✓ 已复制" : "📋 复制命令")), 
+            // 步骤提示
+            !notInstalled && !isRightbar
+                ? h("ol", { className: "dsh-github-steps-list" }, h("li", null, "打开系统终端（PowerShell / CMD / Terminal），运行上述命令；"), h("li", null, "按提示依次选择「GitHub.com」➜「HTTPS」➜「Login with a web browser」；"), h("li", null, "按回车打开浏览器确认授权后，切回本页面即可自动恢复。"))
+                : null, 
+            // 操作按钮区域
+            h("div", { className: "dsh-github-guide-actions" }, h("button", {
+                className: "dsh-github-action-btn",
+                onClick: () => launchTerminal(defaultCmd),
+                disabled: launching,
+                title: "自动唤起系统终端并执行该命令"
+            }, launching ? "正在唤起..." : (notInstalled ? "💻 唤起终端安装" : "💻 唤起终端登录")), notInstalled
+                ? h("button", {
+                    className: "dsh-github-action-btn",
+                    onClick: openDownload,
+                    title: "打开 GitHub CLI 官方下载主页获取安装包"
+                }, "🌐 官网安装包 (.msi/.pkg)")
+                : null, h("button", {
+                className: "dsh-github-action-btn",
+                onClick: onRefresh,
+                title: "重新检测登录与安装状态"
+            }, "🔄 刷新状态")), toastMsg
+                ? h("div", { style: { fontSize: "12px", color: "var(--dsw-alias-link, #0969da)", marginTop: "8px" } }, `ℹ️ ${toastMsg}`)
+                : null, h("div", { className: "dsh-github-guide-tip" }, notInstalled
+                ? "💡 提示：使用包管理器安装完成后，若未立即识别，可重启 DeepSeek Harness 应用刷新系统环境变量 PATH。"
+                : "💡 提示：凭证由官方 GitHub CLI 加密保存在操作系统安全凭据库中，授权完毕切回本窗口将自动识别刷新。"));
+        }
         // 渲染 GitHub 仓库信息与操作视图的核心函数
         function renderGithubRepoView(h, data, loading, error, onRefresh, isRightbar = false) {
             var auth = data ? data.auth : null;
@@ -749,7 +967,10 @@ body[data-ds-dark-theme] .dsh-github-subheading {
                     : r.conclusion === "failure"
                         ? h("span", { className: "dsh-github-badge dsh-badge-red" }, "✕ 失败")
                         : h("span", { className: "dsh-github-badge dsh-badge-yellow" }, r.status))))));
-            return [headerEl, repoCardEl, actionsBarEl, prSectionEl, runSectionEl];
+            var authGuideEl = !auth?.loggedIn
+                ? h(AuthGuideCard, { auth, onRefresh, isRightbar })
+                : null;
+            return [headerEl, authGuideEl, repoCardEl, actionsBarEl, prSectionEl, runSectionEl].filter(Boolean);
         }
         // 1. 右侧栏专属视图 (Right Sidebar Tab Body)
         function GithubRightbarBody(props) {
@@ -806,6 +1027,16 @@ body[data-ds-dark-theme] .dsh-github-subheading {
             React.useEffect(() => {
                 loadData(false);
             }, [loadData]);
+            // 窗口切回自动探测自愈
+            React.useEffect(() => {
+                var onFocus = () => {
+                    if (!data?.auth?.loggedIn) {
+                        loadData(false);
+                    }
+                };
+                window.addEventListener("focus", onFocus);
+                return () => window.removeEventListener("focus", onFocus);
+            }, [data, loadData]);
             var h = React.createElement;
             return h("div", { className: "dsh-github-rightbar-container" }, ...renderGithubRepoView(h, data, loading, error, () => loadData(true), true));
         }
@@ -878,6 +1109,16 @@ body[data-ds-dark-theme] .dsh-github-subheading {
                 }
             }, []);
             React.useEffect(() => { loadData(false); }, [loadData]);
+            // 窗口切回自动探测自愈
+            React.useEffect(() => {
+                var onFocus = () => {
+                    if (!data?.auth?.loggedIn) {
+                        loadData(false);
+                    }
+                };
+                window.addEventListener("focus", onFocus);
+                return () => window.removeEventListener("focus", onFocus);
+            }, [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 全景驾驶舱")), h("button", {
                 className: "dsh-github-refresh-btn",
@@ -894,7 +1135,19 @@ body[data-ds-dark-theme] .dsh-github-subheading {
             var myIssues = (data && data.myIssues) || [];
             var errorEl = error ? h("div", { style: { color: "#f85149", background: "rgba(248,81,73,0.1)", border: "1px solid rgba(248,81,73,0.3)", padding: "8px 12px", borderRadius: "6px", marginBottom: "16px", fontSize: "12px" } }, `⚠️ 加载失败: ${error}`) : null;
             // 顶部统计卡片
-            var statsCardsEl = h("div", { className: "dsh-github-overview-cards" }, h("div", { className: "dsh-github-card" }, h("div", { className: "dsh-github-card-title" }, "CLI 认证账号"), h("div", { className: "dsh-github-card-value" }, auth?.loggedIn ? `👤 ${auth.user}` : "未登录", auth?.loggedIn ? h("span", { className: "dsh-github-badge dsh-badge-green" }, "Active") : null)), h("div", { className: "dsh-github-card" }, h("div", { className: "dsh-github-card-title" }, "账号云端仓库"), h("div", { className: "dsh-github-card-value" }, `${userRepos.length} 个 Repositories`)), h("div", { className: "dsh-github-card" }, h("div", { className: "dsh-github-card-title" }, "本地工作区联动"), h("div", { className: "dsh-github-card-value" }, `${workspaceMatrix.length} 个工作区 (${workspaceMatrix.filter((w) => w.repo).length} 个已关联)`)));
+            var statsCardsEl = h("div", { className: "dsh-github-overview-cards" }, h("div", { className: "dsh-github-card" }, h("div", { className: "dsh-github-card-title" }, "CLI 认证账号"), h("div", { className: "dsh-github-card-value" }, auth?.loggedIn
+                ? `👤 ${auth.user}`
+                : !auth?.installed
+                    ? "❌ 未安装 CLI"
+                    : "⚠️ 未登录", auth?.loggedIn
+                ? h("span", { className: "dsh-github-badge dsh-badge-green" }, "Active")
+                : !auth?.installed
+                    ? h("span", { className: "dsh-github-badge dsh-badge-red" }, "Missing")
+                    : h("span", { className: "dsh-github-badge dsh-badge-yellow" }, "Required"))), h("div", { className: "dsh-github-card" }, h("div", { className: "dsh-github-card-title" }, "账号云端仓库"), h("div", { className: "dsh-github-card-value" }, `${userRepos.length} 个 Repositories`)), h("div", { className: "dsh-github-card" }, h("div", { className: "dsh-github-card-title" }, "本地工作区联动"), h("div", { className: "dsh-github-card-value" }, `${workspaceMatrix.length} 个工作区 (${workspaceMatrix.filter((w) => w.repo).length} 个已关联)`)));
+            // 安装与登录引导组件（未登录或未安装时显式展开）
+            var authGuideEl = !auth?.loggedIn
+                ? h(AuthGuideCard, { auth, onRefresh: () => loadData(true), isRightbar: false })
+                : null;
             // Tab 栏
             var tabsEl = h("div", { className: "dsh-github-tabs" }, h("button", { className: `dsh-github-tab-btn ${activeTab === 'workspaces' ? 'active' : ''}`, onClick: () => setActiveTab('workspaces') }, `📂 本地工作区矩阵 (${workspaceMatrix.length})`), h("button", { className: `dsh-github-tab-btn ${activeTab === 'repos' ? 'active' : ''}`, onClick: () => setActiveTab('repos') }, `☁️ 我的 GitHub 仓库 (${userRepos.length})`), h("button", { className: `dsh-github-tab-btn ${activeTab === 'mywork' ? 'active' : ''}`, onClick: () => setActiveTab('mywork') }, `📋 个人待办 (PR: ${myPrs.length} · Issue: ${myIssues.length})`));
             // 内容区
@@ -907,18 +1160,28 @@ body[data-ds-dark-theme] .dsh-github-subheading {
                     : null))));
             }
             else if (activeTab === 'repos') {
-                var filteredRepos = userRepos.filter((r) => !searchQuery || r.nameWithOwner.toLowerCase().includes(searchQuery.toLowerCase()) || r.description?.toLowerCase().includes(searchQuery.toLowerCase()));
-                contentEl = h("div", null, h("input", {
-                    className: "dsh-github-search-input",
-                    placeholder: "🔍 搜索我的 GitHub 仓库...",
-                    value: searchQuery,
-                    onChange: (e) => setSearchQuery(e.target.value)
-                }), h("div", { className: "dsh-github-list" }, filteredRepos.map((r) => h("div", { key: r.nameWithOwner, className: "dsh-github-item" }, h("a", { className: "dsh-github-item-title", href: r.url, target: "_blank" }, r.nameWithOwner), r.description ? h("div", { className: "dsh-github-item-desc" }, r.description) : null, h("div", { className: "dsh-github-item-meta" }, h("span", null, `默认分支: ${r.defaultBranch}`), r.isPrivate ? h("span", { className: "dsh-github-badge dsh-badge-yellow" }, "Private") : h("span", { className: "dsh-github-badge dsh-badge-green" }, "Public"), h("span", null, `⭐ ${r.stargazerCount}`))))));
+                if (!auth?.loggedIn) {
+                    contentEl = h("div", { className: "dsh-github-empty" }, "当前尚未认证登录 GitHub 账号，无法读取云端仓库列表。请先完成上方的安装或登录指引。");
+                }
+                else {
+                    var filteredRepos = userRepos.filter((r) => !searchQuery || r.nameWithOwner.toLowerCase().includes(searchQuery.toLowerCase()) || r.description?.toLowerCase().includes(searchQuery.toLowerCase()));
+                    contentEl = h("div", null, h("input", {
+                        className: "dsh-github-search-input",
+                        placeholder: "🔍 搜索我的 GitHub 仓库...",
+                        value: searchQuery,
+                        onChange: (e) => setSearchQuery(e.target.value)
+                    }), h("div", { className: "dsh-github-list" }, filteredRepos.map((r) => h("div", { key: r.nameWithOwner, className: "dsh-github-item" }, h("a", { className: "dsh-github-item-title", href: r.url, target: "_blank" }, r.nameWithOwner), r.description ? h("div", { className: "dsh-github-item-desc" }, r.description) : null, h("div", { className: "dsh-github-item-meta" }, h("span", null, `默认分支: ${r.defaultBranch}`), r.isPrivate ? h("span", { className: "dsh-github-badge dsh-badge-yellow" }, "Private") : h("span", { className: "dsh-github-badge dsh-badge-green" }, "Public"), h("span", null, `⭐ ${r.stargazerCount}`))))));
+                }
             }
             else {
-                contentEl = h("div", null, h("h3", { className: "dsh-github-subheading" }, `🔀 我发起的 PR (${myPrs.length})`), myPrs.length === 0 ? h("div", { className: "dsh-github-empty", style: { marginBottom: "16px" } }, "暂无开放中的 PR") : h("div", { className: "dsh-github-list", style: { marginBottom: "16px" } }, myPrs.map((pr) => h("div", { key: pr.number, className: "dsh-github-item" }, h("a", { className: "dsh-github-item-title", href: pr.url, target: "_blank" }, `[${pr.repository?.nameWithOwner || 'Repo'}] #${pr.number} ${pr.title}`)))), h("h3", { className: "dsh-github-subheading" }, `📝 我的待办 Issues (${myIssues.length})`), myIssues.length === 0 ? h("div", { className: "dsh-github-empty" }, "暂无开放中的 Issue") : h("div", { className: "dsh-github-list" }, myIssues.map((is) => h("div", { key: is.number, className: "dsh-github-item" }, h("a", { className: "dsh-github-item-title", href: is.url, target: "_blank" }, `[${is.repository?.nameWithOwner || 'Repo'}] #${is.number} ${is.title}`)))));
+                if (!auth?.loggedIn) {
+                    contentEl = h("div", { className: "dsh-github-empty" }, "当前尚未认证登录 GitHub 账号，无法读取个人待办 PR 与 Issues。请先完成上方的安装或登录指引。");
+                }
+                else {
+                    contentEl = h("div", null, h("h3", { className: "dsh-github-subheading" }, `🔀 我发起的 PR (${myPrs.length})`), myPrs.length === 0 ? h("div", { className: "dsh-github-empty", style: { marginBottom: "16px" } }, "暂无开放中的 PR") : h("div", { className: "dsh-github-list", style: { marginBottom: "16px" } }, myPrs.map((pr) => h("div", { key: pr.number, className: "dsh-github-item" }, h("a", { className: "dsh-github-item-title", href: pr.url, target: "_blank" }, `[${pr.repository?.nameWithOwner || 'Repo'}] #${pr.number} ${pr.title}`)))), h("h3", { className: "dsh-github-subheading" }, `📝 我的待办 Issues (${myIssues.length})`), myIssues.length === 0 ? h("div", { className: "dsh-github-empty" }, "暂无开放中的 Issue") : h("div", { className: "dsh-github-list" }, myIssues.map((is) => h("div", { key: is.number, className: "dsh-github-item" }, h("a", { className: "dsh-github-item-title", href: is.url, target: "_blank" }, `[${is.repository?.nameWithOwner || 'Repo'}] #${is.number} ${is.title}`)))));
+                }
             }
-            return h("div", { className: "dsh-github-panel" }, headerEl, errorEl, statsCardsEl, tabsEl, contentEl);
+            return h("div", { className: "dsh-github-panel" }, headerEl, errorEl, statsCardsEl, authGuideEl, tabsEl, contentEl);
         }
         var inject = ["slots", "sidebarRightTabs", "sessions", "layout", "theme"];
         function apply(ctx) {

package/lib/executor.d.ts

@@ -39,6 +39,8 @@ export declare class GhExecutor {
      *   而 Web 面板每次挂载都会来问一次，重复执行实测要 5.4 秒，属于纯浪费。
      */
     checkAuth(cwd?: string, bypassCache?: boolean): Promise<AuthStatus>;
+    /** 生成当前操作系统平台的推荐安装引导与命令 */
+    private getPlatformInstallGuide;
     /** 实际执行 `gh auth status` 并解析结果，不含缓存逻辑 */
     private probeAuth;
     /**

package/lib/executor.js

@@ -222,19 +222,46 @@ export class GhExecutor {
         }
         return value;
     }
+    /** 生成当前操作系统平台的推荐安装引导与命令 */
+    getPlatformInstallGuide() {
+        const p = process.platform;
+        if (p === 'win32') {
+            return {
+                command: 'winget install --id GitHub.cli',
+                altCommand: 'scoop install gh',
+                downloadUrl: 'https://cli.github.com/',
+                description: '推荐使用 Windows Package Manager (winget) 一键安装，或下载官方 .msi 安装包。',
+            };
+        }
+        if (p === 'darwin') {
+            return {
+                command: 'brew install gh',
+                altCommand: 'port install gh',
+                downloadUrl: 'https://cli.github.com/',
+                description: '推荐使用 Homebrew 安装 GitHub CLI。',
+            };
+        }
+        return {
+            command: 'sudo apt install gh',
+            altCommand: 'sudo dnf install gh',
+            downloadUrl: 'https://cli.github.com/',
+            description: '推荐使用系统包管理器安装（Debian/Ubuntu 运行 apt，Fedora/CentOS 运行 dnf）。',
+        };
+    }
     /** 实际执行 `gh auth status` 并解析结果，不含缓存逻辑 */
     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('✓');
         // 只要已登录或有常规输出，则必然安装了 gh
-        const isNotInstalled = Boolean(res.error && res.error.includes('系统未检测到 GitHub CLI'));
+        const isNotInstalled = Boolean(res.error && (res.error.includes('系统未检测到 GitHub CLI') || res.error.includes('ENOENT')));
         const installed = loggedIn || !isNotInstalled;
         if (!installed) {
             return {
                 installed: false,
                 loggedIn: false,
                 platform: process.platform,
+                installGuide: this.getPlatformInstallGuide(),
                 raw: res.error,
             };
         }

package/lib/types.d.ts

@@ -33,6 +33,16 @@ export interface GhResult<T = unknown> {
     /** 是否因超出安全阈值而被截断 */
     truncated?: boolean;
 }
+export interface AuthInstallGuide {
+    /** 推荐包管理器命令，例如 Windows 下 "winget install --id GitHub.cli" */
+    command: string;
+    /** 备选命令（如 choco/scoop/brew） */
+    altCommand?: string;
+    /** 官方下载与安装文档链接 */
+    downloadUrl: string;
+    /** 简明指引提示 */
+    description?: string;
+}
 export interface AuthStatus {
     installed: boolean;
     loggedIn: boolean;
@@ -42,6 +52,7 @@ export interface AuthStatus {
     activeAccount?: boolean;
     protocol?: string;
     scopes?: string[];
+    installGuide?: AuthInstallGuide;
     raw?: string;
 }
 export interface RepoMetadata {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-github-flow",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "icon": "icon.svg",
   "description": "GitHub Flow: Native GitHub CLI (gh) integration for DeepSeek Harness — Agent Tools, Slash Commands, and Web UI Workspace",
   "type": "module",