dsh-github-flow 0.1.4 → 0.1.5

package/README.en.md

@@ -39,6 +39,24 @@
 
 ---
 
+## 📸 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 +79,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 +103,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

@@ -39,6 +39,24 @@
 
 ---
 
+## 📸 界面预览
+
+### 全局全景驾驶舱 (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 +79,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 +103,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/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,11 +191,24 @@ 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;
                         }
@@ -174,7 +223,7 @@ export function registerApiRoutes(webServerService, executor, workspaceRegistry)
         },
     });
     // 4. 获取全局视角的驾驶舱概览数据 (不绑定单一项目)
-    webServerService.register({
+    bindRoute({
         kind: 'exact',
         path: '/api/github/global-overview',
         handler: async (req, res) => {
@@ -182,18 +231,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 +274,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 +302,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();
+    }
+}

package/lib/client.js

@@ -837,25 +837,43 @@ body[data-ds-dark-theme] .dsh-github-subheading {
             var loadData = React.useCallback(async (forceRefresh = false) => {
                 setLoading(true);
                 setError(null);
+                // 全局驾驶舱要 spawn 十几次 gh，冷启动可能超过 10 秒。
+                // 不设显式超时的话浏览器会抛一个与真实原因无关的网络错误，
+                // 早先这里会把所有失败都归因成「后端服务未就绪或接口不存在」——归因错误比没有报错更糟。
+                var controller = new AbortController();
+                var timedOut = false;
+                var timer = setTimeout(function () { timedOut = true; controller.abort(); }, 30000);
                 try {
                     if (forceRefresh)
                         await fetch("/api/github/refresh", { method: "POST" }).catch(() => { });
-                    var res = await fetch("/api/github/global-overview");
+                    var res = await fetch("/api/github/global-overview", { signal: controller.signal });
                     if (!res.ok) {
                         var errText = await res.text().catch(() => "");
-                        setError(`后端服务未就绪或接口不存在 (${res.status}): ${errText || res.statusText}`);
+                        setError(`获取全局数据失败（HTTP ${res.status}）${errText ? ": " + errText : ""}`);
                         return;
                     }
                     var json = await res.json();
-                    if (json.ok && json.data)
+                    if (json.ok && json.data) {
                         setData(json.data);
-                    else
+                        // 工作区矩阵单独失败时不能静默：否则界面显示「暂无工作区」，把故障伪装成空状态
+                        if (json.data.workspaceError) {
+                            setError("工作区列表读取失败：" + json.data.workspaceError);
+                        }
+                    }
+                    else {
                         setError(json.error || "获取全局数据失败");
+                    }
                 }
                 catch (err) {
-                    setError(err.message);
+                    if (timedOut || err.name === "AbortError") {
+                        setError("获取超时（30 秒）：本机 gh 命令响应过慢，通常是网络或工作区数量较多所致。可稍后重试，或减少同时打开的工作区。");
+                    }
+                    else {
+                        setError("无法连接后端服务：" + (err.message || err));
+                    }
                 }
                 finally {
+                    clearTimeout(timer);
                     setLoading(false);
                 }
             }, []);

package/lib/commands/gh.js

@@ -7,7 +7,9 @@ export function registerGhCommand(commandsService, executor) {
         async handler({ rawInput }) {
             const trimmed = (rawInput || '').trim();
             if (!trimmed || trimmed === 'status') {
-                const auth = await executor.checkAuth();
+                // 人类显式诊断必须绕过缓存：用户敲 /gh status 往往正是为了确认
+                // 「我刚 gh auth login 到底成没成」，给他 30 秒前的缓存等于答非所问。
+                const auth = await executor.checkAuth(undefined, true);
                 const repo = await executor.getRepoMetadata();
                 let md = `### GitHub 集成状态\n\n`;
                 if (auth.loggedIn) {

package/lib/executor.d.ts

@@ -1,8 +1,21 @@
 import type { GhExecutionOptions, GhResult, AuthStatus, RepoMetadata, PluginConfig } from './types.js';
+/**
+ * 按「字符数 + UTF-8 字节数」双口径截断输出。
+ * 抽成纯函数是刻意的：截断逻辑是崩溃高发区（切碎多字节字符、误伤 JSON、把二进制流截成垃圾），
+ * 但通过真实 gh 命令很难稳定复现超限输出，抽出来才能用单元测试覆盖边界。
+ */
+export declare function truncateOutput(input: string, maxChars: number, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+};
 export declare class GhExecutor {
     ghPath: string;
     defaultTimeoutMs: number;
     maxOutputChars: number;
+    /** UTF-8 字节口径的硬上限；未配置时按 maxOutputChars × 4 推导（覆盖 CJK 3 字节与 emoji 4 字节） */
+    maxOutputBytes: number;
+    /** 认证状态缓存。`gh auth status` 实测 5.4 秒，而它位于全局驾驶舱关键路径的最前面 */
+    private authCache;
     constructor(config?: PluginConfig);
     updateConfig(config?: PluginConfig): void;
     /**
@@ -20,8 +33,24 @@ export declare class GhExecutor {
     run<T = unknown>(args: string[], options?: GhExecutionOptions): Promise<GhResult<T>>;
     /**
      * 检查宿主机当前 GitHub CLI 的认证状态与账号信息
+     *
+     * @param cwd 解析工作区用的路径
+     * @param bypassCache 跳过进程内缓存。`/gh status` 这类人类显式发起的诊断必须看到实时结果，
+     *   而 Web 面板每次挂载都会来问一次，重复执行实测要 5.4 秒，属于纯浪费。
      */
-    checkAuth(cwd?: string): Promise<AuthStatus>;
+    checkAuth(cwd?: string, bypassCache?: boolean): Promise<AuthStatus>;
+    /** 实际执行 `gh auth status` 并解析结果，不含缓存逻辑 */
+    private probeAuth;
+    /**
+     * 仅从本地 .git/config 解析仓库身份，绝不发起网络请求。
+     *
+     * 为什么需要它：全局驾驶舱要为每个工作区认识别仓库，而 getRepoMetadata 会调用
+     * `gh repo view` 走网络。实测 5 个工作区时该端点冷启动 20.5 秒，其中绝大部分耗在这 5 次
+     * 网络往返上——而有界并发根本救不了它，因为瓶颈是网络延迟而不是进程排队。
+     * 工作区矩阵只需要「这个目录属于哪个仓库」这一身份信息，本地 .git/config 已经完整具备，
+     * 描述/star 数等富字段是当前仓库详情才需要的。这一步把每个工作区从 1 次网络往返降为 0。
+     */
+    getRepoIdentityFromLocal(cwd?: string): RepoMetadata | null;
     /**
      * 获取当前目录（工作区）关联的远程仓库元数据
      * 采用 gh repo view + 本地 git remote 双保险机制，彻底杜绝已配置远程却误判未关联的问题