dsh-github-flow 0.1.3 → 0.1.5

package/README.en.md

@@ -22,21 +22,41 @@
 
 1. **Zero-Configuration Authentication**:
    - Seamlessly reuses existing host credentials from `gh auth login` (OAuth tokens / system Keyrings) without exposing plain-text Personal Access Tokens (PATs) in DSH.
-2. **Deep Workspace Affinity (CWD Binding)**:
-   - Automatically scopes commands to the active session workspace. `gh` resolves the remote repository and current Git branch automatically, saving model tokens from redundant `owner/repo` arguments.
+2. **Deep Workspace Affinity & Zero-Config Detection**:
+   - Automatically scopes commands to the active session workspace by natively reading local `.git/config` and mapping DSH `workspace.json`. Neither models nor humans need to supply redundant `owner/repo` arguments.
 3. **High Signal-to-Noise Ratio & Token Budget Protection**:
    - Consolidates over 70+ scattered micro-tools into **5 focused domain tools**.
    - Queries use `--json <fields>` projections by default; long diffs and failed CI logs are safely truncated (default 24KB) to protect the model's context window.
-4. **Dual Native Web UI Views**:
+   - All tool outputs are defensively normalized into root objects to strictly comply with DSH Tool Gateway schema validation.
+4. **Dual Native Web UI Views & Dynamic Dual-Theme Support**:
    - **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 quick action buttons inside the session.
+   - **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**:
    - Exposes native `GitHubService` (`ctx.github`) for ecosystem extensibility;
-   - Strongly typed runtime validation via Schemastery (`Config`);
+   - 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:
@@ -59,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) |
 
 ---
 
@@ -83,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

@@ -22,21 +22,41 @@
 
 1. **零鉴权配置，开箱即用**：
    - 自动复用宿主机已通过 `gh auth login` 认证的登录凭据（OAuth Token / 系统 Keyring），无需在 DSH 中存储任何明文 GitHub PAT。
-2. **工作区目录深度亲和 (CWD 绑定)**：
-   - 自动继承当前会话所在的 Workspace 物理目录，`gh` 自动识别当前 Git 仓库与本地工作分支，无需 Agent 每次显式传递 `owner/repo`。
+2. **工作区目录深度亲和与零参数探测 (CWD & Git Auto-Binding)**：
+   - 自动绑定当前会话所在的物理工作区目录，原生直读本地 `.git/config` 并映射 `workspace.json`，无需 Agent 或人类手动传参 `owner/repo`，零参数直接识别关联仓库。
 3. **高信噪比与 Token 防溢出治理**：
    - 拒绝 70+ 个碎片化微型工具撑爆上下文，收敛聚合为 **5 大领域核心 Tool**。
    - 所有查询原生采用 `--json <fields>` 按需返回；对 `diff`、`log_failed` 设置安全截断保护（默认 24KB），防止模型上下文窗口溢出崩溃。
-4. **原生 Web UI 双重视图**：
+   - 工具层已通过防御性输出包装，列表与标量 100% 契合 DSH 工具网关模式约束。
+4. **原生 Web UI 双重视图与双模式自适应**：
    - **全局驾驶舱**（主导航栏 `sidebar.panellist`，Order 20）：透视账号全局仓库、本地工作区矩阵、个人待办 PR 与 Issues；
-   - **右侧栏工作区面板**（`sidebarRightTabs`，Order 40）：在会话引导页与右侧抽屉常驻呈现当前仓库的 PR 列表、Checks 状态药丸与快捷操作。
+   - **右侧栏工作区面板**（`sidebarRightTabs`，Order 40）：常驻呈现当前仓库的 PR 状态、Checks 门禁药丸与 2x2 黄金快捷网格（浏览器打开、查看 PRs、快速创建 PR、新建 Issue），一键直达官方比对与创建页，零弹窗依赖；
+   - **全场景双模式原生自适应**：深度契合 DSH 官方 DSW（DeepSeek Web）设计变量规范，通过 `body[data-ds-dark-theme]` 驱动浅色与深色主题实时零延迟平滑切换。
 5. **符合 Cordis 官方微内核架构**：
    - 暴露原生 `GitHubService`（`ctx.github`），允许生态其他插件复用；
-   - 具备 Schemastery 强类型运行时配置校验（`Config`）；
+   - 具备符合 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 安装：
@@ -59,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` 原始响应体模式） |
 
 ---
 
@@ -83,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/cordis.patch.yml

@@ -1,3 +1,3 @@
 - insert:
-    - id: github-flow-v3
-      name: 'D:/Desktop/AgentWork/DSHQuestion/dsh-github-flow/lib/main.js'
+    - id: github-flow
+      name: dsh-github-flow

package/docs/architecture.md

@@ -55,15 +55,21 @@
 - 直接复用宿主机由 `gh auth login` 认证的安全凭证（系统 Keychain / Windows Credential Manager / 系统的加密存储）；
 - 天然支持多账号、企业 GitHub (GH Enterprise) 以及各种 OAuth 作用域。
 
-### 2.2 工作区 CWD 亲和 (Workspace Affinity)
-- 会话内的所有命令默认在当前 Agent 会话物理目录（`cwd`）执行；
-- `gh` 引擎自动逆向推导关联的远程仓库（识别 `origin` 或 `github` remote），免去大模型每次必须传递 `owner/repo` 的繁重上下文负担。
+### 2.2 工作区深度亲和与零参数探测 (Workspace Affinity & Auto-Binding)
+- 结合 `$env:DSH_SESSION_ID` 逆向解析 `~/.dsh/storages/workspace.json`，自动锁定当前活跃会话物理工作区；
+- 原生免子进程直接读取工作区 `.git/config`，自动识别远程仓库，免去大模型或人类每次传递 `owner/repo` 的繁重上下文负担；
+- 具备离线优雅兜底机制，无论在何种受限环境下调用均不崩溃。
 
-### 2.3 上下文 Token 保护 (Token Budget Guard)
+### 2.3 上下文 Token 保护与防御性输出包装 (Token Budget Guard)
 - 所有的 `gh` 查询原生采用 `--json <fields>` 结构化投影；
-- 对长文本输出（如大型 PR 的完整 `diff`、CI 失败步骤日志）设置安全截断阈值（默认 24KB），保留头尾关键上下文并添加显式截断标记，杜绝撑爆模型上下文。
+- 对长文本输出（如大型 PR 的完整 `diff`、CI 失败步骤日志）设置安全截断阈值（默认 24KB），保留头尾关键上下文并添加显式截断标记，杜绝撑爆模型上下文；
+- 所有 Agent 工具的输出统一经过 `normalizeOutput` 归一化，列表自动打包为 `{ items, count }`，标量打包为 `{ result }`，100% 严丝合缝契合 DSH 工具网关模式约束。
 
-### 2.4 Cordis 微内核标准规范
-- **硬依赖解耦**：顶层仅强依赖 `['tools']`，Web 服务与命令服务采用动态作用域注入，在纯终端 / Headless 模式下零卡死；
+### 2.4 原生浅色/深色主题自适应与 2x2 黄金操作栏
+- 全面对齐 DSH 官方 DSW 语义设计变量，基于 `body[data-ds-dark-theme]` 驱动无闪烁双模式切换；
+- 右侧栏 2x2 快捷操作栏彻底废弃失效的 Electron `prompt()` 阻塞弹窗，全面采用官方直达模式（Compare / New Issue），享有 100% 官方富文本体验。
+
+### 2.5 Cordis 微内核标准规范
+- **服务依赖就绪**：声明 `['tools', 'commands', 'webServer', 'workspaceRegistry']`，确保 Web 路由与命令服务在环境就绪后激活；
 - **生命周期 Effect 闭环**：所有 HTTP 路由与命令注册均持有 Disposer 清理函数，插件热重载或重新挂载时自动彻底注销，零内存泄漏；
-- **配置自校验**：基于 `@deepseek-ai/schemastery` 实现强类型声明与运行时校验。
+- **配置自校验与服务暴露**：基于 Standard Schema 规范实现强类型校验与默认值注入，通过 `ctx.provide('github', executor)` 向生态插件暴露单例服务。

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();
+    }
+}