dsh-github-flow 0.1.8 → 0.2.1

package/lib/api/route-helpers.d.ts

@@ -0,0 +1,47 @@
+import type { IssueCategory, IssueStats } from '../types.js';
+/**
+ * 依据当前登录账号判定 Issue 的归属身份维度 (可多选):
+ * - reported: 用户提起的 (属于当前账号名下仓库，但作者不是本人)
+ * - assigned: 被分配的 (指派列表中包含当前账号)
+ * - created: 我创建的 (作者是当前账号)
+ *
+ * 为什么这样划分：
+ * 在真实工程实践中，Maintainer 不仅要关注自己创建的任务，更要对社区/用户提交的 Bug 反馈负责，
+ * 同时还要处理他人指派的待办任务。这三个维度互补且可能重叠。
+ */
+export declare function resolveIssueCategories(issue: {
+    author?: {
+        login?: string;
+    } | null;
+    assignees?: Array<{
+        login?: string;
+    }> | null;
+    repository?: {
+        nameWithOwner?: string;
+    } | null;
+}, currentUser?: string, explicitRepoOwner?: string): IssueCategory[];
+export declare function calculateIssueStats(issues: Array<{
+    categories?: IssueCategory[];
+}>): IssueStats;
+/** path.basename 在空串/异常输入上会抛错，工作区路径来自磁盘文件，必须防御 */
+export declare function basenameSafe(p: string): string;
+/**
+ * 由用户配置推导全局驾驶舱的缓存时长。
+ * 抽成导出的纯函数：TTL 的推导规则是测试断言的对象，埋在闭包里就只能靠猜。
+ */
+export declare function globalCacheTtlMs(cacheTtlMs: number): number;
+/** open_browser 只允许 http/https，杜绝 file:// 与自定义协议被当作打开目标 */
+export declare function isSafeExternalUrl(raw: unknown): raw is string;
+/** JSON 响应统一出口：no-store 防代理/浏览器缓存干扰面板数据新鲜度语义 */
+export declare function sendJson(res: any, status: number, data: any): void;
+/**
+ * 读取并解析请求 JSON body（带默认 256KB 上限防护）。
+ * 集中处理超限/畸形 JSON 的错误语义，避免每个 handler 复制流收集样板。
+ */
+export declare function readJsonBody(req: any, maxBytes?: number): Promise<any>;
+/** 各路由分组共享的依赖包类型：注册器装配时一次性注入，分组内不再触碰全局 */
+export interface RouteDeps {
+    bindRoute: (route: any) => void;
+    sendJson: typeof sendJson;
+    readJsonBody: typeof readJsonBody;
+}

package/lib/api/route-helpers.js

@@ -0,0 +1,134 @@
+/**
+ * API 路由共享工具层。
+ *
+ * 为什么从 routes.ts 拆出：这些工具被全部路由分组文件消费（sendJson/readJsonBody/
+ * issue 聚合/TTL 推导），放在任何一个分组文件里都会造成分组之间的横向依赖；
+ * 独立成无状态模块后，各分组只依赖它，注册器只装配。
+ */
+import path from 'node:path';
+/**
+ * 依据当前登录账号判定 Issue 的归属身份维度 (可多选):
+ * - reported: 用户提起的 (属于当前账号名下仓库，但作者不是本人)
+ * - assigned: 被分配的 (指派列表中包含当前账号)
+ * - created: 我创建的 (作者是当前账号)
+ *
+ * 为什么这样划分：
+ * 在真实工程实践中，Maintainer 不仅要关注自己创建的任务，更要对社区/用户提交的 Bug 反馈负责，
+ * 同时还要处理他人指派的待办任务。这三个维度互补且可能重叠。
+ */
+export function resolveIssueCategories(issue, currentUser, explicitRepoOwner) {
+    const categories = [];
+    if (!currentUser)
+        return categories;
+    const currentLower = currentUser.toLowerCase();
+    const authorLogin = issue.author?.login?.toLowerCase();
+    const isAuthor = Boolean(authorLogin && authorLogin === currentLower);
+    const isAssignee = Array.isArray(issue.assignees) &&
+        issue.assignees.some((a) => a.login?.toLowerCase() === currentLower);
+    // 仓库 owner 判定：优先从 repository.nameWithOwner 提取，兜底使用 explicitRepoOwner
+    let repoOwner = explicitRepoOwner?.toLowerCase();
+    if (!repoOwner && issue.repository?.nameWithOwner) {
+        repoOwner = issue.repository.nameWithOwner.split('/')[0]?.toLowerCase();
+    }
+    const isOwnerRepo = Boolean(repoOwner && repoOwner === currentLower);
+    if (isAuthor)
+        categories.push('created');
+    if (isAssignee)
+        categories.push('assigned');
+    // 如果是当前用户维护的仓库，且作者不是本人，则明确归为「用户提起的」
+    if (isOwnerRepo && !isAuthor)
+        categories.push('reported');
+    return categories;
+}
+export function calculateIssueStats(issues) {
+    let reported = 0;
+    let assigned = 0;
+    let created = 0;
+    for (const item of issues) {
+        const cats = item.categories || [];
+        if (cats.includes('reported'))
+            reported++;
+        if (cats.includes('assigned'))
+            assigned++;
+        if (cats.includes('created'))
+            created++;
+    }
+    return {
+        total: issues.length,
+        reported,
+        assigned,
+        created,
+    };
+}
+/** path.basename 在空串/异常输入上会抛错，工作区路径来自磁盘文件，必须防御 */
+export function basenameSafe(p) {
+    try {
+        return path.basename(p) || p;
+    }
+    catch {
+        return p;
+    }
+}
+/**
+ * 全局驾驶舱的缓存时长下限。
+ * 这个端点要 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:// 与自定义协议被当作打开目标 */
+export 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;
+    }
+}
+/** JSON 响应统一出口：no-store 防代理/浏览器缓存干扰面板数据新鲜度语义 */
+export 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));
+}
+/**
+ * 读取并解析请求 JSON body（带默认 256KB 上限防护）。
+ * 集中处理超限/畸形 JSON 的错误语义，避免每个 handler 复制流收集样板。
+ */
+export function readJsonBody(req, maxBytes = 256 * 1024) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > maxBytes) {
+                reject(new Error(`请求体超过 ${maxBytes} 字节上限`));
+                req.destroy();
+                return;
+            }
+            body += chunk;
+        });
+        req.on('end', () => {
+            try {
+                resolve(body ? JSON.parse(body) : {});
+            }
+            catch {
+                reject(new Error('请求体不是合法 JSON'));
+            }
+        });
+        req.on('error', reject);
+    });
+}

package/lib/api/routes-actions.d.ts

@@ -0,0 +1,23 @@
+import type { GhExecutor } from '../executor.js';
+import { TtlCache } from '../cache.js';
+import type { GitHubOverviewData, GlobalOverviewData } from '../types.js';
+import { type RouteDeps } from './route-helpers.js';
+/**
+ * 构造「在新终端窗口运行命令」的平台命令（execFile 数组形态，不经 shell）。
+ *
+ * Issue #2 修复要点：
+ * - Windows：cmd.exe（显式 .exe，规避 GUI 父进程 PATH 解析差异）+ start 的窗口标题
+ *   占位 "DSH GitHub"——start 的首个带引号参数会被解析为标题而非程序，占位后
+ *   powershell.exe 才能被稳定识别为目标程序；
+ * - macOS：osascript 驱动 Terminal.app，命令经引号转义拼入 AppleScript；
+ * - Linux：发行版终端二进制与参数形态各异（gnome-terminal 用 `--`、konsole 用
+ *   `-e`、xfce4-terminal 用 `-x`），单一硬编码在主流桌面大概率不存在——由
+ *   detectLinuxTerminal 按探测结果返回对应形态。
+ */
+export declare function buildTerminalCommand(command: string): {
+    bin: string;
+    args: string[];
+} | null;
+/** 测试辅助：重置 Linux 终端探测缓存（便于单测注入不同探测环境） */
+export declare function resetLinuxTerminalCache(): void;
+export declare function registerActionRoutes(deps: RouteDeps, executor: GhExecutor, cacheMap: TtlCache<GitHubOverviewData>, globalCache: TtlCache<GlobalOverviewData>): void;

package/lib/api/routes-actions.js

@@ -0,0 +1,239 @@
+/**
+ * 动作类路由：缓存强制刷新 + 右侧栏快捷操作（create_pr/create_issue/open_browser/open_terminal）。
+ * 共同特征：POST 触发、读少写多、无缓存语义，与概览类路由的演进方向不同。
+ */
+import { spawn } from 'node:child_process';
+import { isSafeExternalUrl, sendJson } from './route-helpers.js';
+/**
+ * 构造「在新终端窗口运行命令」的平台命令（execFile 数组形态，不经 shell）。
+ *
+ * Issue #2 修复要点：
+ * - Windows：cmd.exe（显式 .exe，规避 GUI 父进程 PATH 解析差异）+ start 的窗口标题
+ *   占位 "DSH GitHub"——start 的首个带引号参数会被解析为标题而非程序，占位后
+ *   powershell.exe 才能被稳定识别为目标程序；
+ * - macOS：osascript 驱动 Terminal.app，命令经引号转义拼入 AppleScript；
+ * - Linux：发行版终端二进制与参数形态各异（gnome-terminal 用 `--`、konsole 用
+ *   `-e`、xfce4-terminal 用 `-x`），单一硬编码在主流桌面大概率不存在——由
+ *   detectLinuxTerminal 按探测结果返回对应形态。
+ */
+export function buildTerminalCommand(command) {
+    if (process.platform === 'win32') {
+        return {
+            bin: 'cmd.exe',
+            // -NoProfile 是 Windows 兼容基线：powershell.exe 是全量自带的 5.1，其默认执行
+            // 策略常为 Restricted——加载用户 profile（如 conda init 写入的）会就地报
+            // UnauthorizedAccess 红错（实测：winget 安装仍正常，但启动噪音吓人）。
+            // 白名单命令（gh/winget/brew/apt）均不依赖用户 profile 环境；pwsh 7 是个人
+            // 安装不作依赖，-NoProfile 在 5.1/7 语义一致，一并消除该类报错并加速启动。
+            args: ['/c', 'start', 'DSH GitHub', 'powershell.exe', '-NoExit', '-NoProfile', '-Command', command],
+        };
+    }
+    if (process.platform === 'darwin') {
+        // AppleScript 字符串内的双引号以 \" 转义；白名单命令虽无引号，仍统一转义防未来扩展踩坑
+        const escaped = command.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        return {
+            bin: 'osascript',
+            args: [
+                '-e', `tell application "Terminal" to do script "${escaped}"`,
+                '-e', 'tell application "Terminal" to activate',
+            ],
+        };
+    }
+    if (process.platform === 'linux') {
+        const terminal = detectLinuxTerminal();
+        if (!terminal)
+            return null;
+        // 各终端「执行命令并保持窗口」的参数形态不同：
+        // - gnome-terminal -- <sh> -c：新版 -e 已弃用，-- 后直接跟命令行
+        // - konsole/xfce4-terminal/xterm：-e/-x 执行，sh -c + exec 保交互语义
+        //   （命令结束后 exec sh 落回交互 shell，窗口不闪退）
+        const shArgs = ['sh', '-c', `${command}; exec sh`];
+        switch (terminal) {
+            case 'gnome-terminal': return { bin: 'gnome-terminal', args: ['--', ...shArgs] };
+            case 'konsole': return { bin: 'konsole', args: ['-e', ...shArgs] };
+            case 'xfce4-terminal': return { bin: 'xfce4-terminal', args: ['-x', ...shArgs] };
+            case 'x-terminal-emulator': return { bin: 'x-terminal-emulator', args: ['-e', ...shArgs] };
+            case 'xterm': return { bin: 'xterm', args: ['-e', ...shArgs] };
+            default: return null;
+        }
+    }
+    return null;
+}
+/** Linux 终端探测结果缓存（进程级）：which 探测有子进程成本，会话内只做一次 */
+let cachedLinuxTerminal;
+/**
+ * 探测当前 Linux 桌面可用的终端模拟器（按桌面占有率排序）。
+ * 返回 null 表示全部不可用——调用方据此走失败分支而非硬编码赌一个。
+ */
+function detectLinuxTerminal() {
+    if (cachedLinuxTerminal !== undefined)
+        return cachedLinuxTerminal;
+    const candidates = ['gnome-terminal', 'konsole', 'xfce4-terminal', 'x-terminal-emulator', 'xterm'];
+    try {
+        const { execFileSync } = require('node:child_process');
+        for (const name of candidates) {
+            try {
+                execFileSync('which', [name], { stdio: 'ignore', timeout: 2_000 });
+                cachedLinuxTerminal = name;
+                return name;
+            }
+            catch { /* 该候选不存在，试下一个 */ }
+        }
+    }
+    catch { /* which 本身不可用（极端环境），视为无可用终端 */ }
+    cachedLinuxTerminal = null;
+    return null;
+}
+/** 测试辅助：重置 Linux 终端探测缓存（便于单测注入不同探测环境） */
+export function resetLinuxTerminalCache() {
+    cachedLinuxTerminal = undefined;
+}
+/**
+ * 执行终端唤起并等待真实结果（Issue #2 核心修复：不再先斩后奏报假成功）。
+ * start/osascript 场景下命令随宿主立即退出，close 即代表唤起动作用的成败；
+ * err 与 stderr 原样上抛给调用方决定 HTTP 语义。
+ */
+function launchTerminalAndWait(command) {
+    return new Promise((resolve) => {
+        const built = buildTerminalCommand(command);
+        if (!built) {
+            resolve({ ok: false, error: '未找到可用的系统终端（Linux 下请先安装 gnome-terminal / konsole 等任一终端模拟器）' });
+            return;
+        }
+        // stdio 必须忽略：start 唤起的交互式窗口会继承 execFile 的 stdout/stderr 管道句柄，
+        // -NoExit 窗口存活期间管道永不关闭——回调要等满 10s 超时甚至不触发（实测复现：
+        // 唤起成功的窗口让 HTTP 响应挂起 10s+）。交互终端本就不该捕获输出；stdio ignore
+        // 后等待语义回归 cmd.exe 自身退出（start 创建窗口后立即返回，亚秒级）。
+        // 改用原生 spawn：execFile 的类型与实现都强制 stdout 管道捕获，而交互终端唤起
+        // 场景需要的恰恰是「不捕获」——spawn 的 stdio:'ignore' 是官方支持的干净形态。
+        const child = spawn(built.bin, built.args, {
+            stdio: 'ignore',
+            detached: false,
+        });
+        // 10s 兜底超时：正常路径 cmd.exe start 毫秒级返回；超时视为唤起故障并如实回传
+        let timedOut = false;
+        const killTimer = setTimeout(() => { timedOut = true; child.kill(); }, 10_000);
+        child.on('error', (err) => {
+            clearTimeout(killTimer);
+            resolve({ ok: false, error: err.message });
+        });
+        child.on('close', (code) => {
+            clearTimeout(killTimer);
+            if (code === 0) {
+                resolve({ ok: true });
+            }
+            else if (timedOut) {
+                // kill 触发的 close 是 code=null——如实归因为超时而非"退出码 null"
+                resolve({ ok: false, error: '终端启动命令 10 秒未返回（可能被安全软件拦截）' });
+            }
+            else {
+                resolve({ ok: false, error: `终端启动命令退出码 ${code}` });
+            }
+        });
+    });
+}
+export function registerActionRoutes(deps, executor, cacheMap, globalCache) {
+    const { bindRoute } = deps;
+    // 1. 强制刷新缓存
+    bindRoute({
+        kind: 'exact',
+        path: '/api/github/refresh',
+        handler: async (req, res) => {
+            cacheMap.clear();
+            globalCache.clear();
+            sendJson(res, 200, { ok: true, message: '缓存已清空，下次读取将拉取最新数据' });
+        },
+    });
+    // 2. 右侧栏快捷操作代理接口
+    bindRoute({
+        kind: 'exact',
+        path: '/api/github/action',
+        handler: async (req, res) => {
+            if (req.method !== 'POST') {
+                sendJson(res, 405, { ok: false, message: '仅支持 POST 请求' });
+                return;
+            }
+            let body = '';
+            req.on('data', (chunk) => { body += chunk; });
+            req.on('end', async () => {
+                try {
+                    const payload = body ? JSON.parse(body) : {};
+                    const cwd = payload.cwd || process.cwd();
+                    switch (payload.action) {
+                        case 'create_pr': {
+                            const cmd = ['pr', 'create', '--title', payload.title || 'Update', '--body', payload.body || 'Created from DSH Rightbar'];
+                            if (payload.draft)
+                                cmd.push('--draft');
+                            const r = await executor.run(cmd, { cwd });
+                            if (!r.ok)
+                                throw new Error(r.error);
+                            sendJson(res, 200, { ok: true, message: 'PR 创建成功', url: r.rawOutput });
+                            break;
+                        }
+                        case 'create_issue': {
+                            const cmd = ['issue', 'create', '--title', payload.title || 'New Issue', '--body', payload.body || 'Created from DSH Rightbar'];
+                            const r = await executor.run(cmd, { cwd });
+                            if (!r.ok)
+                                throw new Error(r.error);
+                            sendJson(res, 200, { ok: true, message: 'Issue 创建成功', url: r.rawOutput });
+                            break;
+                        }
+                        case 'open_browser': {
+                            // 原实现把 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}`);
+                            }
+                            // Issue #2 修复：等待真实唤起结果再回传——旧实现 execFile 异步回调吞错、
+                            // 路由先行返回 ok:true，导致终端弹不弹都提示成功。
+                            const launch = await launchTerminalAndWait(command);
+                            if (!launch.ok) {
+                                sendJson(res, 500, {
+                                    ok: false,
+                                    message: `唤起终端失败：${launch.error}。请手动打开系统终端执行：${command}`,
+                                });
+                                return;
+                            }
+                            sendJson(res, 200, { ok: true, message: '已唤起系统终端' });
+                            break;
+                        }
+                        default:
+                            sendJson(res, 400, { ok: false, message: `未知的操作类型: ${payload.action}` });
+                    }
+                }
+                catch (err) {
+                    sendJson(res, 500, { ok: false, error: err.message || '操作执行失败' });
+                }
+            });
+        },
+    });
+}

package/lib/api/routes-lifecycle.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 生命周期类路由：版本检查 / 一键升级 / 升级状态轮询 / 认证轻量探针 / 更新源设置。
+ * 共同特征：服务插件自身状态而非 GitHub 业务数据，故障语义独立于概览链路。
+ */
+import type { GhExecutor } from '../executor.js';
+import type { UpdateChecker } from '../updater.js';
+import type { UpgradeManager } from '../upgrade-manager.js';
+import { type RouteDeps } from './route-helpers.js';
+export declare function registerLifecycleRoutes(deps: RouteDeps, executor: GhExecutor, checker: UpdateChecker, upgrader: UpgradeManager): void;

package/lib/api/routes-lifecycle.js

@@ -0,0 +1,126 @@
+import { loadUpdateSettings, saveUpdateSettings, isValidUpdateMode, describeUpdateMode } from '../update-settings.js';
+import { sendJson, readJsonBody } from './route-helpers.js';
+export function registerLifecycleRoutes(deps, executor, checker, upgrader) {
+    const { bindRoute } = deps;
+    // 1. 闲时静默检查更新端点（前端在 gh 业务数据完全拉取就绪后，由 idle 延时静默触发）
+    bindRoute({
+        kind: 'exact',
+        path: '/api/github/check-update',
+        handler: async (req, res) => {
+            if (req.method !== 'GET') {
+                sendJson(res, 405, { ok: false, message: '仅支持 GET 请求' });
+                return;
+            }
+            try {
+                const url = new URL(req.url || '', 'http://127.0.0.1');
+                const force = url.searchParams.get('force') === 'true';
+                const info = await checker.check(force);
+                sendJson(res, 200, { ok: true, data: info });
+            }
+            catch (err) {
+                sendJson(res, 500, { ok: false, error: err.message || '检查更新失败' });
+            }
+        },
+    });
+    // 2. 一键自动升级触发端点（用户点击操作横幅按钮后发起）
+    bindRoute({
+        kind: 'exact',
+        path: '/api/github/upgrade',
+        handler: async (req, res) => {
+            if (req.method !== 'POST') {
+                sendJson(res, 405, { ok: false, message: '仅支持 POST 请求' });
+                return;
+            }
+            try {
+                // 一键升级是用户显式动作，不受 checkUpdate 配置熔断：check() 在禁用时
+                // 会返回 latestVersion 缺失的兜底态，此时回退 'latest' 让 pnpm 自行解析
+                // 最新版（与 UpgradeManager 自身的 targetVersion 可选语义一致）。
+                const info = await checker.check(false);
+                const target = info.latestVersion || 'latest';
+                const result = await upgrader.executeUpgrade(target);
+                sendJson(res, result.ok ? 200 : 500, result);
+            }
+            catch (err) {
+                sendJson(res, 500, { ok: false, message: err.message || '执行自动升级异常' });
+            }
+        },
+    });
+    // 3. 升级状态与实时日志查询端点
+    bindRoute({
+        kind: 'exact',
+        path: '/api/github/upgrade-status',
+        handler: async (req, res) => {
+            if (req.method !== 'GET') {
+                sendJson(res, 405, { ok: false, message: '仅支持 GET 请求' });
+                return;
+            }
+            sendJson(res, 200, { ok: true, data: upgrader.getStatus() });
+        },
+    });
+    // 5. 更新源设置：GET 读取（store 权威，缺省 official）/ POST 保存并立即用新源验证
+    bindRoute({
+        kind: 'exact',
+        path: '/api/github/update-settings',
+        handler: async (req, res) => {
+            if (req.method === 'GET') {
+                const mode = loadUpdateSettings();
+                sendJson(res, 200, { ok: true, data: { mode, description: describeUpdateMode(mode) } });
+                return;
+            }
+            if (req.method !== 'POST') {
+                sendJson(res, 405, { ok: false, message: '仅支持 GET / POST 请求' });
+                return;
+            }
+            try {
+                const body = await readJsonBody(req);
+                const mode = body?.mode;
+                if (!isValidUpdateMode(mode)) {
+                    sendJson(res, 400, { ok: false, message: `非法更新源模式: ${String(mode)}（允许 official / mirror / off）` });
+                    return;
+                }
+                // 写盘失败不阻断内存态生效（save 内部已 warn），返回携带 error 提示重启后需重设
+                const saved = saveUpdateSettings(mode);
+                checker.applySettings(mode);
+                // 非 off 模式：立即用新源真探一次，把结果带回前端展示（缓存已被 applySettings 失效）
+                let probe = null;
+                if (mode !== 'off') {
+                    const info = await checker.check(true);
+                    probe = { latestVersion: info.latestVersion, hasUpdate: info.hasUpdate, checkedAt: info.checkedAt };
+                }
+                sendJson(res, 200, {
+                    ok: true,
+                    data: {
+                        mode,
+                        description: describeUpdateMode(mode),
+                        persisted: saved.ok,
+                        persistError: saved.error,
+                        probe,
+                    },
+                });
+            }
+            catch (err) {
+                sendJson(res, 500, { ok: false, message: err.message || '保存更新源设置失败' });
+            }
+        },
+    });
+    // 4. 快速认证状态轻量探针 (耗时 < 500ms，专供登录自愈检测与快速恢复)
+    bindRoute({
+        kind: 'exact',
+        path: '/api/github/auth',
+        handler: async (req, res) => {
+            if (req.method !== 'GET') {
+                sendJson(res, 405, { ok: false, message: '仅支持 GET 请求' });
+                return;
+            }
+            try {
+                const url = new URL(req.url || '', 'http://127.0.0.1');
+                const force = url.searchParams.get('force') === 'true';
+                const auth = await executor.checkAuth(undefined, force);
+                sendJson(res, 200, { ok: true, auth });
+            }
+            catch (err) {
+                sendJson(res, 500, { ok: false, error: err.message || '认证检测失败' });
+            }
+        },
+    });
+}

package/lib/api/routes-overview.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 概览类路由：单仓库 overview + 全局驾驶舱 global-overview。
+ * 这两个端点是面板首屏关键路径（也是项目里最重的两个 handler），单独成组
+ * 便于按「读密集」特征统一演进（缓存策略、字段投影、并发控制）。
+ */
+import type { GhExecutor } from '../executor.js';
+import { TtlCache } from '../cache.js';
+import type { UpdateChecker } from '../updater.js';
+import type { GitHubOverviewData, GlobalOverviewData } from '../types.js';
+import { type RouteDeps } from './route-helpers.js';
+export declare function registerOverviewRoutes(deps: RouteDeps, executor: GhExecutor, cacheMap: TtlCache<GitHubOverviewData>, globalCache: TtlCache<GlobalOverviewData>, checker: UpdateChecker): void;