dsh-github-flow 0.3.0 → 0.4.0

package/lib/executor.js

@@ -1,296 +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;
 /** gh 版本缓存时长。与 authCache 同哲学：gh 升级是分钟级低频事件，30 秒陈旧窗口无实际影响 */
 const GH_VERSION_CACHE_TTL_MS = 30_000;
-/**
- * 从 `gh --version` 输出中解析语义化版本号。
- * 抽成导出纯函数的原因与 truncateOutput 相同：解析逻辑是「看似简单实则易错」的边界区，
- * 必须能用单元测试钉死（不匹配输入返回 null 而非抛错，调用方据此走 fail-open）。
- */
-export function parseGhVersion(output) {
-    const m = /gh version (\d+\.\d+\.\d+)/.exec(output || '');
-    return m ? m[1] : null;
-}
-/**
- * 数值分段比较两个 gh 版本：a>b 返回 1、a<b 返回 -1、相等返回 0。
- * 为什么不能用字符串比较：`'2.96.0' < '2.100.0'` 在字典序下为 false（'1'<'9'），
- * 这会把 2.100 误判为低于 2.96，导致可用命令被错误降级。逐段 Number 比较是唯一正确姿势。
- */
-export function compareGhVersions(a, b) {
-    const pa = a.split('.').map(Number);
-    const pb = b.split('.').map(Number);
-    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-        const da = pa[i] ?? 0;
-        const db = pb[i] ?? 0;
-        if (da > db)
-            return 1;
-        if (da < db)
-            return -1;
-    }
-    return 0;
-}
-/**
- * 解析 `git status -sb --porcelain` 输出为结构化状态。
- * 抽导出纯函数（parseGhVersion 同理）：三形态解析是易错边界区，单测钉死。
- *
- * 输出形态（实测）：
- *   `## master...origin/master [ahead 2, behind 1]`  有 ahead/behind
- *   `## master...origin/master`                       与远程同步
- *   `## master` / `## HEAD (no branch)`               无 upstream（ahead/behind 未知=-1）
- * 后续每行 `<XY> <path>` 为 porcelain 变更项（XY 两字符状态码，?? = untracked）。
- */
-export function parseGitStatusOutput(output) {
-    const lines = (output || '').split('\n').filter((l) => l.length > 0);
-    if (lines.length === 0 || !lines[0].startsWith('## '))
-        return null;
-    const branchLine = lines[0].slice(3); // 去掉 '## ' 前缀
-    const hasUpstream = branchLine.includes('...');
-    const branchPart = hasUpstream ? branchLine.split('...')[0] : branchLine.split(' ')[0];
-    let ahead = -1;
-    let behind = -1;
-    if (hasUpstream) {
-        // ahead/behind 段在 upstream 之后（可能与 #id 同现：origin/master #12）。
-        // git 输出形态实测：`[ahead 2]` / `[behind 1]` / `[ahead 2, behind 1]`——
-        // 单括号内逗号分隔，behind 不必然前邻 '['（正则不可锚定 '['，否则
-        // `[ahead 2, behind 1]` 形态的 behind 永远漏解析——单测抓到的真实 Bug）
-        const trackingPart = branchLine.split('...')[1] || '';
-        ahead = 0;
-        behind = 0;
-        const aheadMatch = /ahead (\d+)/.exec(trackingPart);
-        const behindMatch = /behind (\d+)/.exec(trackingPart);
-        if (aheadMatch)
-            ahead = Number(aheadMatch[1]);
-        if (behindMatch)
-            behind = Number(behindMatch[1]);
-        // 仅 ahead 无 behind 时 behind=0（反之亦然）——git 输出只列非零侧
-    }
-    const dirtyFiles = [];
-    for (let i = 1; i < lines.length && dirtyFiles.length < 20; i++) {
-        const line = lines[i];
-        if (line.length < 4)
-            continue;
-        const status = line.slice(0, 2).trim() || 'M';
-        // 路径可能含空格（git 不加引号场景）；rename 形态 `R  old -> new` 取 new
-        let p = line.slice(3);
-        const renameArrow = p.indexOf(' -> ');
-        if (renameArrow >= 0)
-            p = p.slice(renameArrow + 4);
-        dirtyFiles.push({ status, path: p });
-    }
-    return {
-        branch: branchPart.replace(/\s*\(no branch\)$/, '') || 'HEAD',
-        ahead,
-        behind,
-        dirtyCount: Math.max(0, lines.length - 1),
-        hasUpstream,
-        dirtyFiles,
-    };
-}
-/**
- * 解析 `git log` 输出为提交条目数组。
- * 支持两种形态：
- * 1. 结构化带详情：%x1e 为 commit 间分隔符，%x1f 为字段间分隔符（含 fullSha/email/date/body/stat）；
- * 2. 简易管道符：%h|%an|%ar|%s 行格式（兼容旧单测输入）。
- * 空输出返回 []。
- */
-export function parseGitLogLines(output) {
-    const out = (output || '').trim();
-    if (!out)
-        return [];
-    if (out.includes('\x1e') || out.includes('\x1f')) {
-        const records = out.split('\x1e').filter((c) => c.trim().length > 0);
-        return records.map((chunk) => {
-            const parts = chunk.split('\x1f');
-            return {
-                sha: (parts[0] || '').trim(),
-                fullSha: (parts[1] || '').trim() || undefined,
-                author: (parts[2] || '').trim(),
-                email: (parts[3] || '').trim() || undefined,
-                date: (parts[4] || '').trim() || undefined,
-                relative: (parts[5] || '').trim(),
-                subject: (parts[6] || '').trim(),
-                body: (parts[7] || '').trim() || undefined,
-                stat: (parts[8] || '').trim() || undefined,
-            };
-        });
-    }
-    return out.split('\n').filter(Boolean).map((line) => {
-        const parts = line.split('|');
-        return {
-            sha: parts[0] || '',
-            author: parts[1] || '',
-            relative: parts[2] || '',
-            subject: parts.slice(3).join('|'),
-        };
-    });
-}
-/**
- * 按码点安全截取字符串，等价于 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 };
-}
 export class GhExecutor {
     ghPath;
     defaultTimeoutMs;
@@ -354,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;
@@ -513,11 +224,19 @@ 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 };
         }
+        else if (value.networkError && this.authCache && this.authCache.value.loggedIn) {
+            // 容灾保全：若本次刷新遭遇网络波动，但之前已有确凿的有效登录缓存，
+            // 保全已有登录身份，仅追加网络异常标识，绝不让界面闪烁误报为「未登录」
+            return {
+                ...this.authCache.value,
+                networkError: true,
+                networkErrorReason: value.networkErrorReason,
+            };
+        }
         return value;
     }
     /**
@@ -593,12 +312,7 @@ export class GhExecutor {
     }
     /** gh 升级命令按平台提示（复用三态状态机的平台判断口径） */
     getGhUpgradeHint() {
-        const p = process.platform;
-        if (p === 'win32')
-            return '升级命令：`winget upgrade GitHub.cli`（或从 https://cli.github.com/ 下载最新 .msi）。';
-        if (p === 'darwin')
-            return '升级命令：`brew upgrade gh`（或从 https://cli.github.com/ 下载最新安装包）。';
-        return '升级方式：更新系统包（Debian/Ubuntu: `sudo apt update && sudo apt install gh`；Fedora: `sudo dnf upgrade gh`），或见 https://cli.github.com/。';
+        return getGhUpgradeHint();
     }
     /**
      * 本地 Git 状态只读探测（白名单通道）。
@@ -734,51 +448,144 @@ export class GhExecutor {
             return null;
         }
     }
-    /** 生成当前操作系统平台的推荐安装引导与命令 */
-    getPlatformInstallGuide() {
-        const p = process.platform;
-        if (p === 'win32') {
-            return {
-                command: 'winget install --id GitHub.cli',
-                altCommand: 'scoop install gh',
-                downloadUrl: 'https://cli.github.com/',
-                description: '推荐使用 Windows Package Manager (winget) 一键安装，或下载官方 .msi 安装包。',
-            };
+    /**
+     * 纯本地读取工作区的所有 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));
         }
-        if (p === 'darwin') {
+        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 {
-                command: 'brew install gh',
-                altCommand: 'port install gh',
-                downloadUrl: 'https://cli.github.com/',
-                description: '推荐使用 Homebrew 安装 GitHub CLI。',
+                ok: false,
+                error: `工作区有 ${gitSt.dirtyCount} 个未提交的文件变更。为防止代码被覆盖，请先提交或保存后再切换分支。`,
             };
         }
-        return {
-            command: 'sudo apt install gh',
-            altCommand: 'sudo dnf install gh',
-            downloadUrl: 'https://cli.github.com/',
-            description: '推荐使用系统包管理器安装（Debian/Ubuntu 运行 apt，Fedora/CentOS 运行 dnf）。',
-        };
+        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;
     }
-    /** 实际执行 `gh auth status` 并解析结果，不含缓存逻辑 */
+    /**
+     * 实际执行认证探测并解析结果，不含外部缓存逻辑。
+     * 解耦本地安装态、本地凭据态与网络可达态：
+     * 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,
@@ -788,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,
@@ -797,7 +623,7 @@ export class GhExecutor {
             };
         }
         // 解析用户名
-        let user;
+        let user = localCred?.user;
         if (accountMatch) {
             user = accountMatch[1];
         }
@@ -863,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) {

package/lib/git-watcher.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Git 元数据变更事件载荷
+ */
+export interface GitChangeEvent {
+    /** 是否检测到本地 Git 元数据变动 */
+    changed?: boolean;
+    /** 触发时间戳（毫秒） */
+    at?: number;
+    /** 是否因达到长轮询上限而超时返回 */
+    timeout?: boolean;
+}
+/**
+ * Git 监听器配置项
+ */
+export interface GitWatchOptions {
+    /** 防抖时间（毫秒），默认 800ms */
+    debounceMs?: number;
+    /** 长轮询超时时间（毫秒），默认 35,000ms */
+    timeoutMs?: number;
+}
+/**
+ * 定向针对 .git/HEAD 与 .git/index 创建非递归文件系统监听器。
+ * 零源码目录遍历，避免句柄耗尽与高 CPU 占用。
+ *
+ * 核心机制：
+ * 1. 靶向监听：仅监控 .git/HEAD 与 .git/index，若都不存在则兜底监控 .git 目录；
+ * 2. 800ms 防抖合并：避免连续 git 操作（如 git add 多个文件）产生事件风暴；
+ * 3. 单次触发保证（At-Most-Once）：变更触发或超时熔断后，立即自动执行清理并释放全部句柄；
+ * 4. 显式释放：返回可随时主动调用的清理函数 stop()。
+ *
+ * @param cwd 目标 Git 仓库根目录
+ * @param onTrigger 变更发生或超时触发时的回调函数
+ * @param options 可选配置项（防抖与超时时间）
+ * @returns 停止监听并释放全部句柄的清理函数
+ */
+export declare function watchGitMetadata(cwd: string, onTrigger: (event: GitChangeEvent) => void, options?: GitWatchOptions): () => void;