dsh-github-flow 0.1.4 → 0.1.6

package/README.en.md

@@ -32,13 +32,36 @@
    - **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`).
 
 ---
 
+## 📸 UI Previews
+
+### Global Cockpit (Main Navigation)
+Overview of account-wide repositories, local workspace matrix mapping, and pending personal PRs/issues:
+
+<p align="center">
+  <img src="./docs/images/1.png" alt="GitHub Global Cockpit" width="100%" />
+</p>
+
+### Session Right Sidebar Panel (In-Session Collaboration)
+Automatically detects current workspace repository, displaying live PR checks, Actions pipelines, and quick action shortcuts:
+
+<p align="center">
+  <img src="./docs/images/2.png" alt="Session Right Sidebar Panel" width="100%" />
+</p>
+
+---
+
 ## 🚀 Installation
 
 Run in your DSH terminal to install directly from npm:
@@ -61,7 +84,7 @@ dsh plugin --profile web add dsh-github-flow
 | `github_issue` | `list`, `view`, `create`, `comment`, `close`, `reopen` | Search and view issues, create issues, add comments |
 | `github_run` | `list`, `view`, `log_failed`, `rerun`, `cancel` | Monitor Actions workflows; `log_failed` extracts failure logs for automatic fixes |
 | `github_repo` | `view`, `search_code`, `search_repos` | Query repository metadata, search cross-repo code |
-| `github_api` | Any GitHub REST / GraphQL endpoint | Universal escape hatch for custom queries (supports `--jq`) |
+| `github_api` | Any GitHub REST / GraphQL endpoint | Universal escape hatch for custom queries (supports `--jq`, plus a `raw` response-body mode) |
 
 ---
 
@@ -85,10 +108,17 @@ Customize options in your `cordis.patch.yml` or profile:
         ghPath: 'gh'              # Custom path to gh binary
         defaultTimeoutMs: 30000   # Timeout in milliseconds
         maxOutputChars: 24000     # Maximum characters per output (Token guard)
-        cacheTtlMs: 15000         # Web overview cache time
+        maxOutputBytes: 96000     # Hard UTF-8 byte ceiling per output, defaults to maxOutputChars * 4
+        cacheTtlMs: 15000         # Single-repo overview cache TTL (ms); the global cockpit caches for 20x this, floor 5 minutes
         defaultListLimit: 20      # Default page size
 ```
 
+> On Web panel refresh cadence: a global cockpit refresh runs a dozen or so `gh` calls
+> (measured 8-13 s on a local machine), so it caches for 5 minutes and re-fetches when you
+> click "🔄 Refresh global data". The workspace matrix only reads local `.git/config` to
+> identify repository ownership and makes no network requests. The `/gh status` command
+> always bypasses the auth cache, so you see the real state immediately after `gh auth login`.
+
 ---
 
 ## 🔌 Ecosystem Service Extension (Cordis Service)

package/README.md

@@ -32,13 +32,36 @@
    - **全局驾驶舱**（主导航栏 `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`）。
 
 ---
 
+## 📸 界面预览
+
+### 全局全景驾驶舱 (Global Cockpit)
+透视账号云端所有 GitHub 仓库、本地工作区矩阵联动状态，以及待办 PR 和 Issues：
+
+<p align="center">
+  <img src="./docs/images/1.png" alt="GitHub 全景驾驶舱" width="100%" />
+</p>
+
+### 会话右侧栏工作区面板 (Session Workspace Panel)
+自动绑定当前工程关联仓库，常驻呈现 PR 状态药丸、Actions 构建流水线与 2x2 黄金操作网格：
+
+<p align="center">
+  <img src="./docs/images/2.png" alt="右侧栏工作区面板" width="100%" />
+</p>
+
+---
+
 ## 🚀 安装指南
 
 在 DSH 终端执行以下命令直接从 npm 安装：
@@ -61,7 +84,7 @@ dsh plugin --profile web add dsh-github-flow
 | `github_issue` | `list`, `view`, `create`, `comment`, `close`, `reopen` | 查看与搜索 Issue、创建 Issue、追加排查进展评论 |
 | `github_run` | `list`, `view`, `log_failed`, `rerun`, `cancel` | 查看 CI 构建流水线，特别是 `log_failed` 可直接提取报错日志供 Agent 修复 |
 | `github_repo` | `view`, `search_code`, `search_repos` | 查看仓库元数据、跨仓库代码搜索 |
-| `github_api` | 任意端点（如 `repos/{owner}/{repo}/releases`） | 底层直接调用 REST / GraphQL API（支持 `--jq` 预过滤） |
+| `github_api` | 任意端点（如 `repos/{owner}/{repo}/releases`） | 底层直接调用 REST / GraphQL API（支持 `--jq` 预过滤、`raw` 原始响应体模式） |
 
 ---
 
@@ -85,10 +108,16 @@ dsh plugin --profile web add dsh-github-flow
         ghPath: 'gh'              # GitHub CLI 程序路径（内网或特定环境可指定绝对路径）
         defaultTimeoutMs: 30000   # 命令执行超时时间（毫秒）
         maxOutputChars: 24000     # 单次命令最大返回字符数（防 Token 溢出保护）
-        cacheTtlMs: 15000         # 界面概览数据缓存时间（毫秒）
+        maxOutputBytes: 96000     # 单次命令最大返回字节数硬上限，默认 maxOutputChars × 4
+        cacheTtlMs: 15000         # 单仓库概览缓存时长（毫秒）；全局驾驶舱按此值的 20 倍缓存，下限 5 分钟
         defaultListLimit: 20      # 默认查询列表返回条数
 ```
 
+> 关于 Web 面板的刷新节奏：全局驾驶舱每次刷新要执行十余次 `gh`（本机实测 8-13 秒），
+> 因此它按 5 分钟缓存，并在你点击「🔄 刷新全局数据」时强制重取。
+> 工作区矩阵只读取本地 `.git/config` 识别仓库归属，不发起网络请求。
+> `/gh status` 命令始终绕过认证缓存，保证你 `gh auth login` 后立刻能看到真实状态。
+
 ---
 
 ## 🔌 生态服务扩展 (Cordis Service)

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.d.ts

@@ -1,2 +1,7 @@
 import type { GhExecutor } from '../executor.js';
-export declare function registerApiRoutes(webServerService: any, executor: GhExecutor, workspaceRegistry?: any): void;
+/**
+ * 由用户配置推导全局驾驶舱的缓存时长。
+ * 抽成导出的纯函数：TTL 的推导规则是测试断言的对象，埋在闭包里就只能靠猜。
+ */
+export declare function globalCacheTtlMs(cacheTtlMs: number): number;
+export declare function registerApiRoutes(ctxOrWebServer: any, executor: GhExecutor, workspaceRegistry?: any, cacheTtlMs?: number): void;

package/lib/api/routes.js

@@ -1,16 +1,89 @@
-const cacheMap = new Map();
-const CACHE_TTL_MS = 15_000;
-export function registerApiRoutes(webServerService, executor, workspaceRegistry) {
-    if (!webServerService || typeof webServerService.register !== 'function')
+import path from 'node:path';
+import { TtlCache } from '../cache.js';
+import { mapLimit, tryReadWorkspaces, findWorkspacePathBySession, findMostRecentWorkspacePath, hasGitDir } from '../workspace.js';
+/** path.basename 在空串/异常输入上会抛错，工作区路径来自磁盘文件，必须防御 */
+function basenameSafe(p) {
+    try {
+        return path.basename(p) || p;
+    }
+    catch {
+        return p;
+    }
+}
+/** 探测单个工作区时在途的 gh 进程数上限；libuv 线程池默认 4，留出余量给其他请求 */
+const WORKSPACE_PROBE_CONCURRENCY = 3;
+/**
+ * 全局驾驶舱的缓存时长下限。
+ * 这个端点要 spawn 十几次 gh，比单仓库概览重得多，因此不直接沿用 cacheTtlMs（默认 15s）。
+ * 定在 5 分钟的依据：它展示的是「我的仓库 / 待办 PR / Issues」这类分钟级不变的数据，
+ * 而每次刷新本机实测要 8-13 秒。缓存太短等于让用户反复等这段延迟——实测 60 秒缓存下，
+ * 用户 65 秒后再打开面板仍需等 9.7 秒。仍随 cacheTtlMs 缩放，用户调大时这里同步变长。
+ */
+const GLOBAL_CACHE_MIN_TTL_MS = 300_000;
+/**
+ * 由用户配置推导全局驾驶舱的缓存时长。
+ * 抽成导出的纯函数：TTL 的推导规则是测试断言的对象，埋在闭包里就只能靠猜。
+ */
+export function globalCacheTtlMs(cacheTtlMs) {
+    const base = Number.isFinite(cacheTtlMs) && cacheTtlMs >= 0 ? cacheTtlMs : 15_000;
+    return Math.max(base * 20, GLOBAL_CACHE_MIN_TTL_MS);
+}
+/** open_browser 只允许 http/https，杜绝 file:// 与自定义协议被当作打开目标 */
+function isSafeExternalUrl(raw) {
+    if (typeof raw !== 'string' || raw.length === 0 || raw.length > 2048)
+        return false;
+    try {
+        const parsed = new URL(raw);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+export function registerApiRoutes(ctxOrWebServer, executor, workspaceRegistry, cacheTtlMs = 15_000) {
+    const ctx = ctxOrWebServer;
+    const webServer = ctx?.webServer || ctx;
+    if (!webServer || typeof webServer.register !== 'function')
         return;
+    const cacheMap = new TtlCache(cacheTtlMs);
+    const globalCache = new TtlCache(globalCacheTtlMs(cacheTtlMs));
     function sendJson(res, status, data) {
         res.statusCode = status;
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.setHeader('Cache-Control', 'no-store');
         res.end(JSON.stringify(data));
     }
+    /**
+     * 注册单个路由并返回注销器。
+     * 为什么需要前置探测与清理：Cordis 插件在经历热重载、异常崩溃或重新启用时，若先前的 disposer
+     * 未能顺利执行，宿主全局长生命周期的 WebServer 内部 exact/prefixes 映射表中会残留历史路由；
+     * 而 WebServer.register 会在键冲突时直接抛出 duplicate route 异常阻断激活。
+     * 前置探测并清理残留条目可实现自愈防护与安全幂等注册。
+     */
+    const registerOneRoute = (route) => {
+        const table = route.kind === 'exact' ? webServer.exact : webServer.prefixes;
+        if (table && typeof table.delete === 'function' && table.has(route.path)) {
+            table.delete(route.path);
+        }
+        return webServer.register(route);
+    };
+    /**
+     * 将路由生命周期绑定到 Cordis 上下文作用域。
+     * 为什么必须包裹在 ctx.effect 中：Cordis 框架要求外部服务的绑定通过 effect 纳管，
+     * 当插件被禁用、配置更新热重载或 scope 销毁时，Cordis 会自动执行返回的 disposer，
+     * 干净地从 WebServer 中注销路由，彻底杜绝孤儿路由残留与重复注册报错。
+     * 当在缺乏 ctx.effect 的简易单元测试环境下运行时，优雅退化为直接注册。
+     */
+    const bindRoute = (route) => {
+        if (ctx && typeof ctx.effect === 'function') {
+            ctx.effect(() => registerOneRoute(route), `github-flow: ${route.kind} ${route.path}`);
+        }
+        else {
+            registerOneRoute(route);
+        }
+    };
     // 1. 获取全局与当前仓库的 GitHub 概览
-    webServerService.register({
+    bindRoute({
         kind: 'exact',
         path: '/api/github/overview',
         handler: async (req, res) => {
@@ -22,58 +95,20 @@ export function registerApiRoutes(webServerService, executor, workspaceRegistry)
                 const url = new URL(req.url || '', 'http://127.0.0.1');
                 let cwd = url.searchParams.get('cwd');
                 const sessionId = url.searchParams.get('sessionId');
-                // 1. 优先通过 sessionId 从 workspace.json 逆向解析物理路径
+                // 会话 ID → 物理路径，以及「最近活跃工作区」兜底，统一由 workspace 模块提供
                 if (!cwd && sessionId) {
-                    try {
-                        const fs = await import('node:fs');
-                        const path = await import('node:path');
-                        const os = await import('node:os');
-                        const wsJsonPath = path.join(os.homedir(), '.dsh', 'storages', 'workspace.json');
-                        if (fs.existsSync(wsJsonPath)) {
-                            const wsData = JSON.parse(fs.readFileSync(wsJsonPath, 'utf8'));
-                            const workspaces = wsData.tables?.workspaces || {};
-                            for (const wsId of Object.keys(workspaces)) {
-                                const item = workspaces[wsId];
-                                if (item.sessionIds && item.sessionIds.includes(sessionId)) {
-                                    cwd = item.path;
-                                    break;
-                                }
-                            }
-                        }
-                    }
-                    catch (e) { }
+                    cwd = findWorkspacePathBySession(sessionId) || null;
                 }
-                // 2. 若仍未获取，从 workspace.json 自动匹配最近活跃的工作区
                 if (!cwd) {
-                    try {
-                        const fs = await import('node:fs');
-                        const path = await import('node:path');
-                        const os = await import('node:os');
-                        const wsJsonPath = path.join(os.homedir(), '.dsh', 'storages', 'workspace.json');
-                        if (fs.existsSync(wsJsonPath)) {
-                            const wsData = JSON.parse(fs.readFileSync(wsJsonPath, 'utf8'));
-                            const workspaces = wsData.tables?.workspaces || {};
-                            let latestItem = null;
-                            for (const wsId of Object.keys(workspaces)) {
-                                const item = workspaces[wsId];
-                                if (!latestItem || new Date(item.updatedAt || 0) > new Date(latestItem.updatedAt || 0)) {
-                                    latestItem = item;
-                                }
-                            }
-                            if (latestItem && latestItem.path) {
-                                cwd = latestItem.path;
-                            }
-                        }
-                    }
-                    catch (e) { }
+                    cwd = findMostRecentWorkspacePath() || null;
                 }
                 if (!cwd) {
                     cwd = process.cwd();
                 }
                 const now = Date.now();
-                const cached = cacheMap.get(cwd);
-                if (cached && now - cached.time < CACHE_TTL_MS) {
-                    sendJson(res, 200, { ok: true, data: cached.data, fromCache: true, cwd });
+                const cachedData = cacheMap.get(cwd, now);
+                if (cachedData) {
+                    sendJson(res, 200, { ok: true, data: cachedData, fromCache: true, cwd });
                     return;
                 }
                 const auth = await executor.checkAuth(cwd);
@@ -84,9 +119,9 @@ export function registerApiRoutes(webServerService, executor, workspaceRegistry)
                 if (repo && auth.loggedIn) {
                     // 并发拉取当前文件夹仓库的 PRs、Issues 和 Runs
                     const [prsRes, issuesRes, runsRes] = await Promise.all([
-                        executor.run(['pr', 'list', '--json', 'number,title,state,author,headRefName,baseRefName,isDraft,mergeable,reviewDecision,statusCheckRollup,url,updatedAt', '-L', '10'], { cwd, timeoutMs: 12_000 }),
-                        executor.run(['issue', 'list', '--json', 'number,title,state,author,labels,assignees,url,updatedAt', '-L', '10'], { cwd, timeoutMs: 12_000 }),
-                        executor.run(['run', 'list', '--json', 'databaseId,name,status,conclusion,event,headBranch,url,createdAt', '-L', '5'], { cwd, timeoutMs: 12_000 }),
+                        executor.run(['pr', 'list', '--json', 'number,title,state,author,headRefName,baseRefName,isDraft,mergeable,reviewDecision,statusCheckRollup,url,updatedAt', '-L', '10'], { cwd, timeoutMs: 8_000 }),
+                        executor.run(['issue', 'list', '--json', 'number,title,state,author,labels,assignees,url,updatedAt', '-L', '10'], { cwd, timeoutMs: 8_000 }),
+                        executor.run(['run', 'list', '--json', 'databaseId,name,status,conclusion,event,headBranch,url,createdAt', '-L', '5'], { cwd, timeoutMs: 8_000 }),
                     ]);
                     if (prsRes.ok && Array.isArray(prsRes.data))
                         pullRequests = prsRes.data;
@@ -103,7 +138,7 @@ export function registerApiRoutes(webServerService, executor, workspaceRegistry)
                     runs,
                     lastUpdated: new Date().toISOString(),
                 };
-                cacheMap.set(cwd, { data: freshData, time: now });
+                cacheMap.set(cwd, freshData, now);
                 sendJson(res, 200, { ok: true, data: freshData, fromCache: false, cwd });
             }
             catch (err) {
@@ -112,16 +147,17 @@ export function registerApiRoutes(webServerService, executor, workspaceRegistry)
         },
     });
     // 2. 强制刷新缓存
-    webServerService.register({
+    bindRoute({
         kind: 'exact',
         path: '/api/github/refresh',
         handler: async (req, res) => {
             cacheMap.clear();
+            globalCache.clear();
             sendJson(res, 200, { ok: true, message: '缓存已清空，下次读取将拉取最新数据' });
         },
     });
     // 3. 右侧栏快捷操作代理接口
-    webServerService.register({
+    bindRoute({
         kind: 'exact',
         path: '/api/github/action',
         handler: async (req, res) => {
@@ -155,14 +191,62 @@ export function registerApiRoutes(webServerService, executor, workspaceRegistry)
                             break;
                         }
                         case 'open_browser': {
-                            if (!payload.url)
-                                throw new Error('缺少 url 参数');
-                            const { exec } = await import('node:child_process');
-                            const openCmd = process.platform === 'win32' ? `start "" "${payload.url}"` : (process.platform === 'darwin' ? `open "${payload.url}"` : `xdg-open "${payload.url}"`);
-                            exec(openCmd);
+                            // 原实现把 payload.url 直接拼进 shell 字符串再交给 exec()，
+                            // 形如 https://x" & calc & " 的 URL 可闭合引号并追加任意命令——本机任意页面
+                            // 都能通过 POST 这个端点触发命令执行。
+                            // 现在改为：先用 URL 解析白名单协议，再用 execFile 参数数组传递，全程不经过 shell。
+                            if (!isSafeExternalUrl(payload.url)) {
+                                throw new Error('url 参数无效：只允许 http/https 开头的完整地址');
+                            }
+                            const { execFile } = await import('node:child_process');
+                            const [bin, args] = process.platform === 'win32'
+                                ? ['cmd', ['/c', 'start', '', payload.url]]
+                                : process.platform === 'darwin'
+                                    ? ['open', [payload.url]]
+                                    : ['xdg-open', [payload.url]];
+                            // 不 await，也不让打开失败反向影响接口语义；仅记录以便排查
+                            execFile(bin, args, (err) => {
+                                if (err)
+                                    console.warn('[dsh-github-flow] 打开浏览器失败:', err?.message || err);
+                            });
                             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}` });
                     }
@@ -174,7 +258,7 @@ export function registerApiRoutes(webServerService, executor, workspaceRegistry)
         },
     });
     // 4. 获取全局视角的驾驶舱概览数据 (不绑定单一项目)
-    webServerService.register({
+    bindRoute({
         kind: 'exact',
         path: '/api/github/global-overview',
         handler: async (req, res) => {
@@ -182,18 +266,29 @@ export function registerApiRoutes(webServerService, executor, workspaceRegistry)
                 sendJson(res, 405, { ok: false, message: '仅支持 GET 请求' });
                 return;
             }
+            // 全局驾驶舱要 spawn 十几次 gh（认证 + 仓库 + PR + Issue + 每个工作区探测），
+            // 实测冷启动曾达 18.9 秒。缓存是这里唯一的解药：面板每次挂载都会来取一次。
+            const now = Date.now();
+            const cachedGlobal = globalCache.get('global', now);
+            if (cachedGlobal) {
+                sendJson(res, 200, { ok: true, data: cachedGlobal, fromCache: true });
+                return;
+            }
             try {
                 const auth = await executor.checkAuth();
                 let userRepos = [];
                 let myPrs = [];
                 let myIssues = [];
                 let workspaceMatrix = [];
+                let workspaceError;
                 if (auth.loggedIn) {
                     // 并发执行：1. 账号下仓库列表 2. 个人 PRs 3. 个人 Issues
+                    // 超时压到 8 秒：本机实测 `gh search issues --author=@me` 单次就要 10 秒，
+                    // 它是这组的木桶短板，直接决定首屏等待时间。面板查询不值得为它多等 4 秒。
                     const [reposRes, prsRes, issuesRes] = await Promise.all([
-                        executor.run(['repo', 'list', '--limit', '20', '--json', 'name,nameWithOwner,description,defaultBranchRef,isPrivate,stargazerCount,updatedAt,url'], { timeoutMs: 12_000 }),
-                        executor.run(['search', 'prs', '--author=@me', '--state=open', '--limit', '10', '--json', 'number,title,repository,url,updatedAt'], { timeoutMs: 12_000 }),
-                        executor.run(['search', 'issues', '--author=@me', '--state=open', '--limit', '10', '--json', 'number,title,repository,url,updatedAt'], { timeoutMs: 12_000 }),
+                        executor.run(['repo', 'list', '--limit', '20', '--json', 'name,nameWithOwner,description,defaultBranchRef,isPrivate,stargazerCount,updatedAt,url'], { timeoutMs: 8_000 }),
+                        executor.run(['search', 'prs', '--author=@me', '--state=open', '--limit', '10', '--json', 'number,title,repository,url,updatedAt'], { timeoutMs: 8_000 }),
+                        executor.run(['search', 'issues', '--author=@me', '--state=open', '--limit', '10', '--json', 'number,title,repository,url,updatedAt'], { timeoutMs: 8_000 }),
                     ]);
                     if (reposRes.ok && Array.isArray(reposRes.data)) {
                         userRepos = reposRes.data.map((r) => ({
@@ -214,36 +309,27 @@ export function registerApiRoutes(webServerService, executor, workspaceRegistry)
                         myIssues = issuesRes.data;
                     }
                 }
-                // 4. 解析本地所有工作区与 GitHub 关联矩阵
-                try {
-                    const fs = await import('node:fs');
-                    const path = await import('node:path');
-                    const os = await import('node:os');
-                    const wsJsonPath = path.join(os.homedir(), '.dsh', 'storages', 'workspace.json');
-                    if (fs.existsSync(wsJsonPath)) {
-                        const wsData = JSON.parse(fs.readFileSync(wsJsonPath, 'utf8'));
-                        const workspaces = wsData.tables?.workspaces || {};
-                        const wsEntries = Object.keys(workspaces).map((id) => ({ id, ...workspaces[id] }));
-                        // 并发探测每个工作区路径的 Git Remote
-                        const matrixResults = await Promise.all(wsEntries.map(async (ws) => {
-                            const hasGit = fs.existsSync(path.join(ws.path, '.git'));
-                            let repoMeta = undefined;
-                            if (hasGit) {
-                                repoMeta = (await executor.getRepoMetadata(ws.path)) || undefined;
-                            }
-                            return {
-                                id: ws.id,
-                                title: ws.title || path.basename(ws.path),
-                                path: ws.path,
-                                hasGit,
-                                repo: repoMeta,
-                                sessionCount: (ws.sessionIds && ws.sessionIds.length) || 0,
-                            };
-                        }));
-                        workspaceMatrix = matrixResults;
-                    }
+                // 解析本地所有工作区与 GitHub 关联矩阵
+                const wsRead = tryReadWorkspaces();
+                workspaceError = wsRead.error;
+                if (!workspaceError) {
+                    const wsEntries = wsRead.workspaces.filter((ws) => ws.path);
+                    // 有界并发探测：每个工作区最多 spawn 2 个 gh 进程，无上限并发会让它们全挤进
+                    // libuv 默认 4 线程的队列里排队，延迟随工作区数量线性劣化。
+                    // 这里刻意只用本地 .git/config 识别身份、不发网络请求——全局矩阵只需要「属于哪个仓库」，
+                    // 每次网络往返都要秒级，5 个工作区就足以把该端点拖到 20 秒。
+                    workspaceMatrix = await mapLimit(wsEntries, WORKSPACE_PROBE_CONCURRENCY, async (ws) => {
+                        const hasGit = hasGitDir(ws.path);
+                        return {
+                            id: ws.id,
+                            title: ws.title || basenameSafe(ws.path),
+                            path: ws.path,
+                            hasGit,
+                            repo: hasGit ? executor.getRepoIdentityFromLocal(ws.path) || undefined : undefined,
+                            sessionCount: ws.sessionIds.length,
+                        };
+                    });
                 }
-                catch (e) { }
                 const globalData = {
                     auth,
                     userRepos,
@@ -251,8 +337,10 @@ export function registerApiRoutes(webServerService, executor, workspaceRegistry)
                     myPrs,
                     myIssues,
                     lastUpdated: new Date().toISOString(),
+                    ...(workspaceError ? { workspaceError } : {}),
                 };
-                sendJson(res, 200, { ok: true, data: globalData });
+                globalCache.set('global', globalData, now);
+                sendJson(res, 200, { ok: true, data: globalData, fromCache: false });
             }
             catch (err) {
                 sendJson(res, 500, { ok: false, error: err.message || '获取全局驾驶舱数据失败' });

package/lib/cache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 有上限的 TTL 缓存。
+ *
+ * 为什么独立成模块：缓存语义（过期、LRU 腾退、容量上限）是缺陷高发区，但嵌在路由文件里
+ * 就无法单测——import 一个已执行过的路由模块拿不到干净实例。独立出来才能覆盖边界。
+ */
+export declare class TtlCache<T> {
+    private ttlMs;
+    private maxEntries;
+    private store;
+    /**
+     * @param ttlMs 命中有效期；由面向用户的 cacheTtlMs 配置驱动
+     * @param maxEntries 容量上限。键通常是工作区路径，一次会话就可能引入若干键，
+     *   没有上限时长期运行的 Web 服务会慢性增长（旧实现只有 /refresh 会清空）
+     */
+    constructor(ttlMs: number, maxEntries?: number);
+    get(key: string, now: number): T | undefined;
+    set(key: string, data: T, now: number): void;
+    get size(): number;
+    clear(): void;
+}

package/lib/cache.js

@@ -0,0 +1,48 @@
+/**
+ * 有上限的 TTL 缓存。
+ *
+ * 为什么独立成模块：缓存语义（过期、LRU 腾退、容量上限）是缺陷高发区，但嵌在路由文件里
+ * 就无法单测——import 一个已执行过的路由模块拿不到干净实例。独立出来才能覆盖边界。
+ */
+export class TtlCache {
+    ttlMs;
+    maxEntries;
+    store = new Map();
+    /**
+     * @param ttlMs 命中有效期；由面向用户的 cacheTtlMs 配置驱动
+     * @param maxEntries 容量上限。键通常是工作区路径，一次会话就可能引入若干键，
+     *   没有上限时长期运行的 Web 服务会慢性增长（旧实现只有 /refresh 会清空）
+     */
+    constructor(ttlMs, maxEntries = 64) {
+        this.ttlMs = ttlMs;
+        this.maxEntries = maxEntries;
+    }
+    get(key, now) {
+        const hit = this.store.get(key);
+        if (!hit)
+            return undefined;
+        if (now - hit.time >= this.ttlMs) {
+            this.store.delete(key);
+            return undefined;
+        }
+        // 命中后重新插入：Map 的迭代顺序即插入顺序，重插让顺序逼近 LRU，腾退时淘汰最久未用者
+        this.store.delete(key);
+        this.store.set(key, hit);
+        return hit.data;
+    }
+    set(key, data, now) {
+        this.store.set(key, { data, time: now });
+        while (this.store.size > this.maxEntries) {
+            const oldest = this.store.keys().next();
+            if (oldest.done)
+                break;
+            this.store.delete(oldest.value);
+        }
+    }
+    get size() {
+        return this.store.size;
+    }
+    clear() {
+        this.store.clear();
+    }
+}