dsh-github-flow 0.2.1 → 0.4.0

package/lib/executor.js

@@ -1,172 +1,20 @@
-import { execFile, spawn } from 'node:child_process';
+import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { findMostRecentWorkspacePath, findWorkspacePathBySession, hasGitDir } from './workspace.js';
+// 子模块纯函数解耦导入并对外部 Re-export 保证 100% 向后兼容
+import { parseGhVersion, compareGhVersions } from './executor/version-utils.js';
+import { spawnWithStdin, safeSlice, cutByUtf8Bytes, truncateOutput } from './executor/process-utils.js';
+import { parseGitStatusOutput, parseGitLogLines, parseGitBranchLines } from './executor/git-parser.js';
+import { getPlatformInstallGuide, getGhUpgradeHint } from './executor/platform-guide.js';
+export { parseGhVersion, compareGhVersions, spawnWithStdin, safeSlice, cutByUtf8Bytes, truncateOutput, parseGitStatusOutput, parseGitLogLines, parseGitBranchLines, getPlatformInstallGuide, getGhUpgradeHint, };
 const execFileAsync = promisify(execFile);
-/**
- * spawn 形态的执行通道（stdin 可选注入）。
- *
- * 为什么存在：execFile 的 input 选项在本机（node 22.18.0 + Windows）实测从不写入
- * 子进程 stdin——既无数据也无 EOF，管道永久悬空（gh secret set 等需要 stdin 的
- * 命令会一直等到超时）。最小复现：execFile+input 对 `cmd /c more` 与 node 子进程
- * 均挂起；而 spawn + stdin.end(data) 全部正常。此函数即为后者的工程化封装，
- * 仅在调用方显式传入 stdin 时使用，其余路径保持 execFileAsync 零改动。
- *
- * 为什么超时要自己管：spawn 无 timeout 选项，用 kill + SIGTERM 兜底；
- * 输出按 maxBuffer 手工聚合（上限与 execFile 路径一致，15MB）。
- */
-function spawnWithStdin(ghPath, args, opts) {
-    return new Promise((resolve, reject) => {
-        const child = spawn(ghPath, args, {
-            cwd: opts.cwd,
-            env: opts.env,
-            windowsHide: true,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        const outChunks = [];
-        const errChunks = [];
-        let totalBytes = 0;
-        let killed = false;
-        let settled = false;
-        const timer = setTimeout(() => {
-            killed = true;
-            child.kill();
-        }, opts.timeout);
-        const settle = (err) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            if (err)
-                reject(err);
-            else
-                resolve({ stdout: Buffer.concat(outChunks), stderr: Buffer.concat(errChunks), killed });
-        };
-        // 聚合上限：超出即杀（与 execFile maxBuffer 语义一致；gh 正常输出远小于此）
-        const MAX_BYTES = 15 * 1024 * 1024;
-        child.stdout?.on('data', (d) => {
-            totalBytes += d.length;
-            outChunks.push(d);
-            if (totalBytes > MAX_BYTES) {
-                killed = true;
-                child.kill();
-            }
-        });
-        child.stderr?.on('data', (d) => { errChunks.push(d); });
-        child.on('error', (err) => {
-            // spawn 失败（如 ENOENT）对齐 execFile 的错误形状：code 保留在 Error 上
-            const e = Object.assign(new Error(err.message), { code: err.code });
-            settle(e);
-        });
-        child.on('close', (code, signal) => {
-            if (killed) {
-                // 超时/超量被杀：对齐 execFile 的 Timeout 错误形状（err.killed + signal）
-                const e = Object.assign(new Error(`Command timed out after ${opts.timeout}ms`), { killed: true, signal: signal || 'SIGTERM' });
-                settle(e);
-                return;
-            }
-            if (code !== 0) {
-                const e = Object.assign(new Error(`Command failed with exit code ${code}`), { code, stderr: Buffer.concat(errChunks).toString('utf8').slice(0, 800) });
-                settle(e);
-                return;
-            }
-            settle();
-        });
-        // stdin 注入：end(data) 半关闭（写完即 EOF），子进程流式读取或一次性读取均可
-        child.stdin?.end(opts.stdin, (err) => {
-            if (err && !settled) {
-                const e = Object.assign(new Error(`stdin write failed: ${err.message}`), { code: 'EPIPE' });
-                settle(e);
-            }
-        });
-    });
-}
 /** 认证状态缓存时长。用户手动 `gh auth login/logout` 后最多 30 秒内面板才会反映，属可接受代价 */
 const AUTH_CACHE_TTL_MS = 30_000;
-/**
- * 按码点安全截取字符串，等价于 String.prototype.slice 但对孤立的代理对（surrogate pair）做占位替换。
- * 为什么必须这样截：本文件末尾会按 UTF-8 字节数截断，而 node:child_process 把 stdout 按字节缓冲区
- * 切分后再 toString('utf8')，一个汉字被从中间切开时会变成 U+FFFD 替换字符。直接用 slice 会把半截
- * 代理对留在结果里，导致下游 JSON.stringify 产出孤立转义序列、写入文件时编码报错。
- */
-function safeSlice(input, start, end) {
-    const chars = Array.from(input);
-    const from = Math.max(0, start);
-    const to = end === undefined ? chars.length : Math.max(from, end);
-    return chars.slice(from, to).map((c) => (c.length === 1 && c.charCodeAt(0) >= 0xd800 && c.charCodeAt(0) <= 0xdfff ? '\ufffd' : c)).join('');
-}
-/**
- * 以 UTF-8 字节数（而非字符串长度）为口径，从两端保留内容。
- * 为什么需要：maxOutputChars 数的是字符，中文一个字占 3 字节。只按字符限长时，
- * 中文环境下真实放行的字节量可达标称值的数倍，Token 预算保护会失真。
- * 采用二分查找定位截断点，避免对超大输出逐字符累加造成 O(n) 反复编码。
- */
-function cutByUtf8Bytes(input, headBytes, tailBytes) {
-    const encoder = new TextEncoder();
-    const totalBytes = encoder.encode(input).length;
-    if (totalBytes <= headBytes + tailBytes) {
-        return { head: input, tail: '', keptHeadBytes: totalBytes, keptTailBytes: 0, truncated: false };
-    }
-    const chars = Array.from(input);
-    const atByte = (limit, fromEnd) => {
-        let lo = 0;
-        let hi = chars.length;
-        let bytes = 0;
-        while (lo < hi) {
-            const mid = (lo + hi + 1) >> 1;
-            const slice = fromEnd ? chars.slice(chars.length - mid) : chars.slice(0, mid);
-            const size = encoder.encode(slice.join('')).length;
-            if (size <= limit) {
-                lo = mid;
-                bytes = size;
-            }
-            else {
-                hi = mid - 1;
-            }
-        }
-        return { count: lo, bytes };
-    };
-    const headPart = atByte(headBytes, false);
-    const tailPart = atByte(tailBytes, true);
-    return {
-        head: safeSlice(input, 0, headPart.count),
-        tail: safeSlice(input, chars.length - tailPart.count),
-        keptHeadBytes: headPart.bytes,
-        keptTailBytes: tailPart.bytes,
-        truncated: true,
-    };
-}
-/**
- * 按「字符数 + UTF-8 字节数」双口径截断输出。
- * 抽成纯函数是刻意的：截断逻辑是崩溃高发区（切碎多字节字符、误伤 JSON、把二进制流截成垃圾），
- * 但通过真实 gh 命令很难稳定复现超限输出，抽出来才能用单元测试覆盖边界。
- */
-export function truncateOutput(input, maxChars, maxBytes) {
-    // 双重口径限长：字符数守住 Token 预算，字节数守住真实传输量。
-    // 中文场景下两者会分别触发，因此两条路径的提示文案必须区分，避免用户按错误的配置项去调参。
-    if (input.length > maxChars) {
-        // 保留前 1/3 字符和尾部 1/2 字符，保留开头上下文和错误尾部
-        const headLen = Math.floor(maxChars * 0.35);
-        const tailLen = Math.floor(maxChars * 0.55);
-        const head = safeSlice(input, 0, headLen);
-        const tail = safeSlice(input, input.length - tailLen);
-        return {
-            text: `${head}\n\n... [⚠️ 提示：内容过长已由 DSH GitHub 插件截断中间部分，当前截取前 ${Math.round(headLen / 1024)}KB 与后 ${Math.round(tailLen / 1024)}KB] ...\n\n${tail}`,
-            truncated: true,
-        };
-    }
-    const byteCut = cutByUtf8Bytes(input, Math.floor(maxBytes * 0.35), Math.floor(maxBytes * 0.55));
-    if (byteCut.truncated) {
-        // 这里必须用「实际保留的字节数」而非 maxChars 推导值：字节口径触发时 maxChars 往往远大于
-        // 字节上限，早先版本照抄字符分支的算法，会报出与实际严重不符的「已保留 100KB」（实际仅数百字节）。
-        return {
-            text: `${byteCut.head}\n\n... [⚠️ 提示：内容超出 UTF-8 字节上限 (${maxBytes} bytes) 已截断中间部分，实际保留前 ${byteCut.keptHeadBytes} 字节与后 ${byteCut.keptTailBytes} 字节；如需放宽请调大配置项 maxOutputBytes] ...\n\n${byteCut.tail}`,
-            truncated: true,
-        };
-    }
-    return { text: input, truncated: false };
-}
+/** gh 版本缓存时长。与 authCache 同哲学：gh 升级是分钟级低频事件，30 秒陈旧窗口无实际影响 */
+const GH_VERSION_CACHE_TTL_MS = 30_000;
 export class GhExecutor {
     ghPath;
     defaultTimeoutMs;
@@ -180,6 +28,12 @@ export class GhExecutor {
      * 且热更新路径 updateConfig 能同步刷新。工具内以 `?? 20` 兜底保证旧配置兼容。
      */
     defaultListLimit;
+    /**
+     * 是否注入 AI_AGENT='dsh'（gh 官方 agent 识别信号，默认 true）。
+     * 挂在 executor 而非工具参数：注入点是「每次 gh 子进程拉起」这一全局咽喉，
+     * 与 GH_NO_UPDATE_NOTIFIER/NO_COLOR 同级，语义上属于执行层默认值。
+     */
+    agentEnvInjection;
     /**
      * 代理管理器引用（可选依赖）。
      * 注入后每次 gh 子进程拉起都会合并代理环境变量——这是「工具调用 + Web 页面数据
@@ -189,12 +43,18 @@ export class GhExecutor {
     proxyManager;
     /** 认证状态缓存。`gh auth status` 实测 5.4 秒，而它位于全局驾驶舱关键路径的最前面 */
     authCache = null;
+    /**
+     * gh 版本号缓存。只缓存成功解析值（authCache 哲学：不确定结果不缓存）——
+     * 探测失败/未安装时不落缓存，用户装好 gh 后下一次探测立即生效。
+     */
+    ghVersionCache = null;
     constructor(config = {}) {
         this.ghPath = config.ghPath || 'gh';
         this.defaultTimeoutMs = config.defaultTimeoutMs || 30_000;
         this.maxOutputChars = config.maxOutputChars || 24_000;
         this.maxOutputBytes = config.maxOutputBytes || this.maxOutputChars * 4;
         this.defaultListLimit = config.defaultListLimit || 20;
+        this.agentEnvInjection = config.agentEnvInjection !== false;
     }
     updateConfig(config = {}) {
         if (config.ghPath)
@@ -203,6 +63,8 @@ export class GhExecutor {
             this.defaultTimeoutMs = config.defaultTimeoutMs;
         if (config.defaultListLimit)
             this.defaultListLimit = config.defaultListLimit;
+        if (config.agentEnvInjection !== undefined)
+            this.agentEnvInjection = config.agentEnvInjection;
         if (config.maxOutputChars) {
             this.maxOutputChars = config.maxOutputChars;
             if (!config.maxOutputBytes)
@@ -216,41 +78,28 @@ export class GhExecutor {
         this.proxyManager = manager;
     }
     /**
-     * 智能解析最可靠的工作区物理路径：
-     * 1. 优先使用显式指定的有效 cwd（若包含 .git 目录）
-     * 2. 使用显式传入的 sessionId 或环境变量 DSH_SESSION_ID 精确反查工作区
-     * 3. 递归探测：若传入了 explicitCwd（如聚合父目录），自动检查其直系子目录中是否包含 Git 仓库
-     * 4. 匹配 ~/.dsh/storages/workspace.json 中最近活跃且存在 .git 的仓库工作区
-     * 5. 回退到 process.cwd()
+     * 解析命令实际执行的工作区根目录
+     * 严格遵循数据事实源与工作区物理所有权，消除越权篡改：
+     * 1. 显式路径第一优先级：调用方只要显式指定了路径，该物理路径即为唯一事实源，原样返回自身；
+     *    绝不递归扫描子目录、绝不越权篡改；无 Git 目录则让下游探测真实反映无 Git 状态；
+     * 2. 仅在未显式指定 cwd 时，才尝试使用 sessionId 或环境变量 DSH_SESSION_ID 反查工作区；
+     * 3. 仅在完全未指定 cwd 且无会话时（全局命令行调用），才兜底回退到最近活跃的 Git 工作区或 process.cwd()。
      */
     resolveWorkspaceCwd(explicitCwd, explicitSessionId) {
-        // 1. 显式路径优先，若有效且直接包含 .git 目录，则直接使用
-        if (explicitCwd && hasGitDir(explicitCwd)) {
+        // 1. 显式路径第一优先级：只要显式指定了路径且在磁盘真实存在，原样返回该目录作为唯一事实源！
+        // 绝不进入子目录去“借用”子项目的 Git 仓库，杜绝在聚合目录或未绑定工作区中张冠李戴！
+        if (explicitCwd && fs.existsSync(explicitCwd)) {
             return explicitCwd;
         }
-        // 2. 使用显式传入的 sessionId 或环境变量中的 DSH_SESSION_ID 反查
+        // 2. 仅在未显式指定 cwd 时，使用显式传入的 sessionId 或环境变量中的 DSH_SESSION_ID 反查
         const targetSessionId = explicitSessionId || process.env.DSH_SESSION_ID;
         if (targetSessionId) {
-            const bySession = findWorkspacePathBySession(targetSessionId);
-            if (bySession && hasGitDir(bySession))
-                return bySession;
-        }
-        // 3. 递归探测：若传入了 explicitCwd（如非 Git 的父工作区目录），检查其一级子目录中是否存在 Git 仓库
-        if (explicitCwd && fs.existsSync(explicitCwd)) {
-            try {
-                const entries = fs.readdirSync(explicitCwd, { withFileTypes: true });
-                for (const entry of entries) {
-                    if (entry.isDirectory()) {
-                        const subDir = path.join(explicitCwd, entry.name);
-                        if (hasGitDir(subDir)) {
-                            return subDir;
-                        }
-                    }
-                }
+            const sessionPath = findWorkspacePathBySession(targetSessionId);
+            if (sessionPath && fs.existsSync(sessionPath)) {
+                return sessionPath;
             }
-            catch { }
         }
-        // 4. 从工作区配置中匹配最近活跃且明确具备 .git 的仓库路径
+        // 3. 仅在完全没有显式指定目录与会话工作区（如无上下文的全局调用）时，才从工作区配置中匹配最近活跃且明确具备 .git 的仓库路径
         const recent = findMostRecentWorkspacePath();
         if (recent)
             return recent;
@@ -280,6 +129,11 @@ export class GhExecutor {
                     // 代理环境变量注入在 options.env 之前：调用方显式传入的 env 仍可覆盖
                     // 代理（保持 options.env 的既有语义优先级），正常调用方不传则代理生效。
                     ...(this.proxyManager?.getEnv('gh') || {}),
+                    // gh 官方 agent 识别信号（detect.go 最高优先级通用变量）：≥2.99 切 text-only
+                    // spinner、≥2.100 误用时打印完整 help、telemetry 归因到 dsh；<2.99 忽略之。
+                    // 覆盖继承自宿主环境的同名变量——插件比外层环境更清楚自己的直接驱动者是
+                    // DSH（嵌套 agent 场景归因不失真）；options.env 仍可覆盖（与代理变量同语义）。
+                    ...(this.agentEnvInjection ? { AI_AGENT: 'dsh' } : {}),
                     ...options.env,
                 },
             };
@@ -370,58 +224,368 @@ export class GhExecutor {
             return this.authCache.value;
         }
         const value = await this.probeAuth(cwd);
-        // 只缓存确定的结果：出错时（未安装/未登录/网络异常）不缓存，
-        // 否则用户 `gh auth login` 之后还要再等满一个 TTL 才能看到面板恢复。
-        if (value.loggedIn) {
+        // 成功登录且无网络故障时落缓存
+        if (value.loggedIn && !value.networkError) {
             this.authCache = { at: now, value };
         }
-        return value;
-    }
-    /** 生成当前操作系统平台的推荐安装引导与命令 */
-    getPlatformInstallGuide() {
-        const p = process.platform;
-        if (p === 'win32') {
+        else if (value.networkError && this.authCache && this.authCache.value.loggedIn) {
+            // 容灾保全：若本次刷新遭遇网络波动，但之前已有确凿的有效登录缓存，
+            // 保全已有登录身份，仅追加网络异常标识，绝不让界面闪烁误报为「未登录」
             return {
-                command: 'winget install --id GitHub.cli',
-                altCommand: 'scoop install gh',
-                downloadUrl: 'https://cli.github.com/',
-                description: '推荐使用 Windows Package Manager (winget) 一键安装，或下载官方 .msi 安装包。',
+                ...this.authCache.value,
+                networkError: true,
+                networkErrorReason: value.networkErrorReason,
             };
         }
-        if (p === 'darwin') {
+        return value;
+    }
+    /**
+     * 获取当前 gh 版本号（带 30s TTL 缓存），失败返回 null。
+     * 底层直连 execFileAsync 而不走 this.run()：run() 会先解析工作区（可能读
+     * workspace.json 与目录扫描）再做截断/JSON 解析，对一次 10ms 的版本字符串
+     * 查询是纯开销；直连也彻底规避 runGuarded → 探测 → run 的递归风险。
+     */
+    async getGhVersion() {
+        const now = Date.now();
+        if (this.ghVersionCache && now - this.ghVersionCache.at < GH_VERSION_CACHE_TTL_MS) {
+            return this.ghVersionCache.value;
+        }
+        const version = parseGhVersion(await this.probeGhVersionRaw());
+        // 只缓存成功解析值：失败不落缓存，用户装好 gh 后下一次探测立即生效
+        if (version) {
+            this.ghVersionCache = { at: now, value: version };
+        }
+        return version;
+    }
+    /**
+     * 底层版本探测（独立方法而非内联：测试需要在不触发真实子进程的前提下
+     * 验证 getGhVersion 的缓存分支——覆写此方法即注入确定输出）。
+     * 直连 execFileAsync 而不走 this.run()：run() 会先解析工作区（可能读
+     * workspace.json 与目录扫描）再做截断/JSON 解析，对一次 10ms 的版本字符串
+     * 查询是纯开销；直连也彻底规避 runGuarded → 探测 → run 的递归风险。
+     */
+    async probeGhVersionRaw() {
+        try {
+            const { stdout } = await execFileAsync(this.ghPath, ['--version'], {
+                timeout: 3_000,
+                windowsHide: true,
+            });
+            return String(stdout);
+        }
+        catch {
+            // 未安装/超时/PATH 抖动：返回空串，由 parseGhVersion 归一为 null → fail-open
+            return '';
+        }
+    }
+    /**
+     * 守卫执行器：按 gh 版本门槛路由「主命令 → 降级链路 → 升级指引」三态。
+     *
+     * 为什么是「检查+执行」一体的方法而非纯探测接口：检查与执行分离会在两者之间
+     * 留下竞隙（版本可能在间隙变化），且降级标注逻辑会被迫散落到每个工具的 if/else。
+     *
+     * fail-open 纪律：版本探测自身失败（null）时直接执行主命令——守卫是路由优化
+     * 不是安全边界，探测故障不应拦截业务；gh 未安装场景由主命令产出既有 ENOENT
+     * 安装引导，这里不重复造错误路径。
+     */
+    async runGuarded(args, options = {}) {
+        const { minVersion, capability, fallback, ...runOptions } = options;
+        if (!minVersion) {
+            return this.run(args, runOptions);
+        }
+        const current = await this.getGhVersion();
+        // 探测失败 fail-open：直接执行主命令（见方法注释），错误路径交由主命令的既有处理
+        if (current === null || compareGhVersions(current, minVersion) >= 0) {
+            return this.run(args, runOptions);
+        }
+        if (fallback) {
+            const res = await fallback();
             return {
-                command: 'brew install gh',
-                altCommand: 'port install gh',
-                downloadUrl: 'https://cli.github.com/',
-                description: '推荐使用 Homebrew 安装 GitHub CLI。',
+                ...res,
+                degraded: true,
+                degradedReason: `当前 gh ${current} 低于 ${capability || minVersion} 所需版本 ${minVersion}，已切换 API 降级链路`,
             };
         }
         return {
-            command: 'sudo apt install gh',
-            altCommand: 'sudo dnf install gh',
-            downloadUrl: 'https://cli.github.com/',
-            description: '推荐使用系统包管理器安装（Debian/Ubuntu 运行 apt，Fedora/CentOS 运行 dnf）。',
+            ok: false,
+            error: `此能力需要 gh ≥ ${minVersion}（当前 ${current}）。${this.getGhUpgradeHint()}`,
         };
     }
-    /** 实际执行 `gh auth status` 并解析结果，不含缓存逻辑 */
+    /** gh 升级命令按平台提示（复用三态状态机的平台判断口径） */
+    getGhUpgradeHint() {
+        return getGhUpgradeHint();
+    }
+    /**
+     * 本地 Git 状态只读探测（白名单通道）。
+     *
+     * 这是本插件首次执行 git（此前仅 gh）——git 存在大量写命令，风险等级高于 gh，
+     * 因此白名单不落在「命令名过滤」而落在「命令形态常量」：spawn 参数是下方
+     * 硬编码的数组字面量，无任何动态拼接路径，写操作物理不可达（cwd 之外零输入，
+     * 而 cwd 本身也是插件解析的工作区路径）。
+     *
+     * 零网络：status 基于 remote-tracking ref（上次 fetch 的快照），毫秒级本地读取，
+     * 符合 global-overview 端点「工作区探测不发网络」的性能红线。
+     */
+    async getLocalGitStatus(cwd) {
+        try {
+            // 纯本地毫秒级；3s 超时兜底异常文件系统
+            const { stdout } = await execFileAsync('git', ['status', '-sb', '--porcelain'], {
+                cwd: cwd || undefined,
+                timeout: 3_000,
+                windowsHide: true,
+            });
+            return parseGitStatusOutput(String(stdout));
+        }
+        catch {
+            // 非 Git 目录 / git 未安装 / 超时：静默降级为 null（调用方不渲染该行）
+            return null;
+        }
+    }
+    /**
+     * 本地 Git 提交记录（三段一次返回：本地领先 / 远程领先 / 最近提交）。
+     *
+     * 白名单纪律与 getLocalGitStatus 同源：下方两个命令形态常量硬编码
+     * （log + 修订范围语法，range 段由 hasUpstream 守卫后才拼接且仅两个
+     * 固定形态 @{u}..HEAD / HEAD..@{u}——不含任何用户输入路径）。
+     * 领先/落后列表基于 remote-tracking ref（上次 fetch 快照），与 status
+     * 的 ahead/behind 计数同一数据口径；格式 %h|%an|%ar|%s 实测可结构化解析。
+     */
+    async getGitCommitLog(cwd, hasUpstream = true, limit = 15) {
+        const empty = { aheadCommits: [], behindCommits: [], recent: [] };
+        const logFmt = '--pretty=format:%x1e%h%x1f%H%x1f%an%x1f%ae%x1f%ad%x1f%ar%x1f%s%x1f%b%x1f';
+        try {
+            const recentRes = await execFileAsync('git', ['log', `-${Math.max(1, limit)}`, logFmt, '--stat', '--no-decorate'], {
+                cwd: cwd || undefined,
+                timeout: 4_000,
+                windowsHide: true,
+            });
+            empty.recent = parseGitLogLines(String(recentRes.stdout));
+            try {
+                const countRes = await execFileAsync('git', ['rev-list', '--count', 'HEAD'], {
+                    cwd: cwd || undefined,
+                    timeout: 2_000,
+                    windowsHide: true,
+                });
+                const cnt = parseInt(String(countRes.stdout).trim(), 10);
+                if (!isNaN(cnt))
+                    empty.totalCount = cnt;
+            }
+            catch { }
+            if (!hasUpstream)
+                return empty; // 无 upstream：领先/落后无从谈起，仅最近提交
+            const aheadRes = await execFileAsync('git', ['log', '@{u}..HEAD', logFmt, '--stat', '--no-decorate'], {
+                cwd: cwd || undefined,
+                timeout: 3_000,
+                windowsHide: true,
+            });
+            empty.aheadCommits = parseGitLogLines(String(aheadRes.stdout));
+            const behindRes = await execFileAsync('git', ['log', 'HEAD..@{u}', logFmt, '--stat', '--no-decorate'], {
+                cwd: cwd || undefined,
+                timeout: 3_000,
+                windowsHide: true,
+            });
+            empty.behindCommits = parseGitLogLines(String(behindRes.stdout));
+            return empty;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 分页获取最近提交记录（用于 Git 面板下滑触底继续加载）。
+     */
+    async getGitRecentLog(cwd, limit = 15, skip = 0) {
+        const logFmt = '--pretty=format:%x1e%h%x1f%H%x1f%an%x1f%ae%x1f%ad%x1f%ar%x1f%s%x1f%b%x1f';
+        const safeLimit = Math.min(Math.max(1, limit), 50);
+        const safeSkip = Math.max(0, skip);
+        const args = ['log', `-${safeLimit}`, logFmt, '--stat', '--no-decorate'];
+        if (safeSkip > 0) {
+            args.push('--skip', String(safeSkip));
+        }
+        try {
+            const { stdout } = await execFileAsync('git', args, {
+                cwd: cwd || undefined,
+                timeout: 5_000,
+                windowsHide: true,
+            });
+            const commits = parseGitLogLines(String(stdout));
+            let totalCount;
+            try {
+                const countRes = await execFileAsync('git', ['rev-list', '--count', 'HEAD'], {
+                    cwd: cwd || undefined,
+                    timeout: 2_000,
+                    windowsHide: true,
+                });
+                const cnt = parseInt(String(countRes.stdout).trim(), 10);
+                if (!isNaN(cnt))
+                    totalCount = cnt;
+            }
+            catch { }
+            return { commits, totalCount };
+        }
+        catch {
+            return { commits: [] };
+        }
+    }
+    /**
+     * 单条提交详情（点击提交行弹窗的数据源）。
+     * 白名单纪律延续：show 命令形态常量硬编码；sha 参数经 ^[0-9a-f]{4,40}$
+     * 十六进制校验后才拼接——这是 git 白名单通道首次接受「外部传入的单值」，
+     * 正则把值域锁死在纯十六进制（注入面为零：任何 shell 元字符/子命令
+     * 语法都不可能通过校验）。输出为 git show --stat 原文（含文件变更统计）。
+     */
+    async getGitCommitDetail(cwd, sha) {
+        if (!/^[0-9a-f]{4,40}$/i.test(sha))
+            return null; // 形态校验：纯十六进制短/全 sha
+        try {
+            const { stdout } = await execFileAsync('git', ['show', '--stat', '--pretty=format:%H%n%an <%ae>%n%ad%n%s%n%b', sha], {
+                cwd: cwd || undefined,
+                timeout: 3_000,
+                windowsHide: true,
+            });
+            return String(stdout);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 纯本地读取工作区的所有 Git 分支（按提交时间倒序）。
+     * 包含当前 HEAD 分支标记、关联 upstream、最新提交简述与相对时间。
+     * 零网络往返，毫秒级本地管道输出。
+     */
+    async getGitBranches(cwd) {
+        const targetCwd = this.resolveWorkspaceCwd(cwd);
+        if (!hasGitDir(targetCwd)) {
+            return null;
+        }
+        const fmt = '%(refname:short)|%(HEAD)|%(upstream:short)|%(committerdate:relative)|%(objectname:short)|%(subject)';
+        try {
+            const { stdout } = await execFileAsync('git', ['branch', '-a', '--sort=-committerdate', `--format=${fmt}`], {
+                cwd: targetCwd,
+                timeout: 4_000,
+                windowsHide: true,
+            });
+            return parseGitBranchLines(String(stdout));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 安全切换当前工作区的 Git 分支。
+     * 三重安全防御纪律：
+     * 1. 目标工作区必须存在有效的 .git 目录；
+     * 2. 分支名称严格执行字符白名单校验，防命令行参数注入；
+     * 3. 检查工作区干净度（dirtyCount），若有未提交或未保存的变更直接阻断，杜绝代码被破坏性覆盖。
+     */
+    async switchGitBranch(cwd, branchName) {
+        const targetCwd = this.resolveWorkspaceCwd(cwd);
+        if (!hasGitDir(targetCwd)) {
+            return { ok: false, error: '当前工作区不是有效的 Git 仓库' };
+        }
+        const cleanBranch = (branchName || '').trim();
+        // 安全白名单校验：只允许字母、数字、点号、斜杠、减号和下划线，禁止以 - 开头（防 flag 注入），禁止包含连续点号 ..
+        if (!cleanBranch || cleanBranch.startsWith('-') || cleanBranch.includes('..') || cleanBranch.includes('\\') || !/^[a-zA-Z0-9_\/.-]+$/.test(cleanBranch)) {
+            return { ok: false, error: '非法分支名称，仅允许字母、数字、短横线、下划线与斜杠组合' };
+        }
+        // 防线二：工作区未提交变更阻断（Dirty File Guard）
+        const gitSt = await this.getLocalGitStatus(targetCwd);
+        if (gitSt && gitSt.dirtyCount > 0) {
+            return {
+                ok: false,
+                error: `工作区有 ${gitSt.dirtyCount} 个未提交的文件变更。为防止代码被覆盖，请先提交或保存后再切换分支。`,
+            };
+        }
+        try {
+            let args = ['checkout', cleanBranch];
+            let targetName = cleanBranch;
+            if (cleanBranch.startsWith('origin/')) {
+                targetName = cleanBranch.replace(/^origin\//, '');
+                // 若本地已有同名分支，直接切本地；若无则通过 --track 建立追踪分支
+                const branches = await this.getGitBranches(targetCwd);
+                const hasLocal = branches?.branches.some((b) => !b.isRemote && b.name === targetName);
+                args = hasLocal ? ['checkout', targetName] : ['checkout', '--track', cleanBranch];
+            }
+            await execFileAsync('git', args, {
+                cwd: targetCwd,
+                timeout: 5_000,
+                windowsHide: true,
+            });
+            return { ok: true, currentBranch: targetName };
+        }
+        catch (err) {
+            const stderr = err?.stderr?.toString().trim();
+            const msg = stderr || err?.message || '切换分支失败';
+            return { ok: false, error: msg };
+        }
+    }
+    /** 生成当前操作系统平台的推荐安装引导与命令 */
+    getPlatformInstallGuide() {
+        return getPlatformInstallGuide();
+    }
+    /**
+     * 纯本地检测宿主机 GitHub CLI 配置文件中是否存在已配置的账号凭据。
+     * 零子进程、零网络往返，毫秒级读取，专供断网与网络卡顿时的 Fail-Safe 容灾降级。
+     */
+    checkLocalGhCredential() {
+        try {
+            const candidates = [];
+            if (process.platform === 'win32') {
+                const appData = process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
+                candidates.push(path.join(appData, 'GitHub CLI', 'hosts.yml'));
+            }
+            candidates.push(path.join(os.homedir(), '.config', 'gh', 'hosts.yml'));
+            for (const file of candidates) {
+                if (fs.existsSync(file)) {
+                    const content = fs.readFileSync(file, 'utf8');
+                    // 匹配 hosts.yml 中的 user: xxx 或 users:\n  xxx:
+                    const userMatch = content.match(/user:\s*([A-Za-z0-9_-]+)/i) || content.match(/users:\s*[\r\n]+\s+([A-Za-z0-9_-]+):/i);
+                    const hasOauth = content.includes('oauth_token') || content.includes('users:');
+                    if (userMatch || hasOauth) {
+                        return {
+                            user: userMatch ? userMatch[1] : undefined,
+                            hasToken: true,
+                        };
+                    }
+                }
+            }
+        }
+        catch { }
+        return null;
+    }
+    /**
+     * 实际执行认证探测并解析结果，不含外部缓存逻辑。
+     * 解耦本地安装态、本地凭据态与网络可达态：
+     * 1. 安装态通过 getGhVersion 本地轻量确认，网络超时/断网绝不篡改 installed 结论；
+     * 2. 本地凭据通过 checkLocalGhCredential 读取，断网时仍可识别人类账号；
+     * 3. 精准分流网络超时/异常（networkError）与真正的未认证（explicitLoggedOut）。
+     */
     async probeAuth(cwd) {
+        // 1. 本地安装态先行探测（纯本地进程调用，零网络依赖）
+        const version = await this.getGhVersion().catch(() => null);
+        const isInstalledLocally = Boolean(version);
+        // 2. 本地已存登录凭据探测（纯本地文件读取，零网络依赖）
+        const localCred = this.checkLocalGhCredential();
+        // 3. 执行 gh auth status 校验远端有效性
         const res = await this.run(['auth', 'status'], { cwd, timeoutMs: 10_000, rawText: true });
         const raw = (res.rawOutput || '') + '\n' + (res.error || '');
-        // 多重维度强健判定登录态 (容错 Windows Unicode 乱码、Keyring 告警与不同版本 CLI 输出差分)
+        // 4. 精准网络异常特征检测（超时、DNS解析失败、代理拒绝、连接重置）
+        const isTimeout = Boolean(res.error && (res.error.includes('执行超时') || res.error.includes('timed out')));
+        const isNetworkError = isTimeout || /dial\s+tcp|connectex|connection\s+refused|lookup\s+api\.github\.com|getaddrinfow|TLS\s+handshake|proxyconnect|network\s+is\s+unreachable|i\/o\s+timeout/i.test(raw);
+        // 5. 显式未登录特征（必须排除网络错误干扰，仅在无网络问题且 CLI 明确指示未登录时成立）
+        const isExplicitlyLoggedOut = !isNetworkError && (/not\s+logged\s+in/i.test(raw) ||
+            raw.includes('gh auth login') ||
+            raw.includes('authentication required') ||
+            raw.includes('No accounts found'));
+        // 6. 成功登录特征判定
         const hasLoggedInFlag = /logged\s+in\s+to/i.test(raw) || raw.includes('✓') || raw.includes('√');
         const hasActiveFlag = /active\s+account:\s*true/i.test(raw);
         const hasTokenFlag = raw.includes('Token:') || raw.includes('Token scopes:');
         const accountMatch = raw.match(/account\s+([A-Za-z0-9_-]+)/i);
         const hasAccount = Boolean(accountMatch && accountMatch[1] && accountMatch[1].toLowerCase() !== 'none');
-        // 显式未登录特征排查
-        const isExplicitlyLoggedOut = /not\s+logged\s+in/i.test(raw) ||
-            raw.includes('gh auth login') ||
-            raw.includes('authentication required') ||
-            raw.includes('No accounts found');
-        const loggedIn = !isExplicitlyLoggedOut && (hasLoggedInFlag || hasActiveFlag || (hasTokenFlag && hasAccount));
-        // 只要已登录或有常规输出，则必然安装了 gh
-        const isNotInstalled = Boolean(res.error && (res.error.includes('系统未检测到 GitHub CLI') || res.error.includes('ENOENT')));
-        const installed = loggedIn || !isNotInstalled;
+        // 7. 安装状态结论：若本地版本已确认，或者命令返回了非 ENOENT 的输出，必然已安装
+        const isNotInstalled = !isInstalledLocally && Boolean(res.error && (res.error.includes('系统未检测到 GitHub CLI') || res.error.includes('ENOENT')));
+        const installed = isInstalledLocally || !isNotInstalled;
         if (!installed) {
             return {
                 installed: false,
@@ -431,6 +595,25 @@ export class GhExecutor {
                 raw: res.error,
             };
         }
+        // 8. 网络异常处理：绝不能把网络超时/断网归咎为“未登录”或“未安装”
+        if (isNetworkError) {
+            const errorReason = isTimeout
+                ? '连接 GitHub API 超时 (10 秒)。请检查网络连通性或代理配置。'
+                : '无法连接至 GitHub 服务器（网络波动或被系统代理阻断）。';
+            return {
+                installed: true,
+                // 若本地确认有配置好的账号，保持 loggedIn 为 true（Fail-Safe 容灾），并标记 networkError
+                loggedIn: Boolean(localCred?.hasToken || hasLoggedInFlag),
+                user: localCred?.user || (accountMatch ? accountMatch[1] : undefined),
+                host: 'github.com',
+                platform: process.platform,
+                networkError: true,
+                networkErrorReason: errorReason,
+                hasLocalToken: Boolean(localCred?.hasToken),
+                raw,
+            };
+        }
+        const loggedIn = !isExplicitlyLoggedOut && (hasLoggedInFlag || hasActiveFlag || (hasTokenFlag && hasAccount));
         if (!loggedIn) {
             return {
                 installed: true,
@@ -440,7 +623,7 @@ export class GhExecutor {
             };
         }
         // 解析用户名
-        let user;
+        let user = localCred?.user;
         if (accountMatch) {
             user = accountMatch[1];
         }
@@ -506,6 +689,11 @@ export class GhExecutor {
      */
     async getRepoMetadata(cwd, sessionId) {
         const targetCwd = this.resolveWorkspaceCwd(cwd, sessionId);
+        // 绝对前置门禁：当前目录若自身不存在 .git 目录，铁证如山判定为未关联本地 Git 仓库
+        // 直接返回 null，杜绝一切在非 Git 目录误报关联的可能！
+        if (!hasGitDir(targetCwd)) {
+            return null;
+        }
         // 1. 优先尝试由 gh 直接根据当前上下文识别
         const res = await this.run(['repo', 'view', '--json', 'nameWithOwner,name,owner,defaultBranchRef,description,isPrivate,url'], { cwd: targetCwd, timeoutMs: 10_000 });
         if (res.ok && res.data && res.data.nameWithOwner) {