dsh-github-flow 0.5.0 → 0.7.0

package/lib/executor/run-log.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 把 gh 的非零退出翻译成给人看的结论；返回 `null` 表示「这是真错误，原样上抛」。
+ *
+ * 两类必须吸收的错误（实测）：
+ * 1. `no failed jobs` —— 工作流本身成功或没有失败步骤，这是确定性答案而非故障；
+ * 2. `Access is denied` —— gh 往本机缓存目录写日志 zip 被系统拒绝，属宿主环境
+ *    问题。原样透传会让调用方（尤其是模型）误判成构建故障，给出自查路径更可行动。
+ *
+ * runId 参与文案：同一个弹窗里可能并排看几个 run，不带编号的报错无法定位。
+ */
+export declare function interpretRunLogError(error: string, runId: string | number): string | null;
+export interface PlainFailureExcerpt {
+    /** 可直接塞进 `<pre>` 的纯文本；空日志时为空串 */
+    text: string;
+    mode: 'anchors' | 'tail' | 'empty';
+    /** 萃取到的失败块总数（可能大于展示的块数） */
+    blockCount: number;
+    droppedBlocks: number;
+    /** 原始日志或二次裁剪是否发生过截断（真值即「结论可能不完整」） */
+    truncated: boolean;
+}
+/**
+ * 把整段日志压成纯文本失败摘要。
+ *
+ * 为什么要有独立的纯文本渲染：弹窗里用 `<pre>` 显示，Markdown 的代码围栏与
+ * 引用块会被当成字面量原样打出来（` ``` ` 出现在日志正文里时更乱）。Markdown 版
+ * 留给 Agent 工具，两者共用同一套锚点萃取与尾部回退，只是排版不同。
+ *
+ * 预算裁剪是**第二道**：gh 侧已按 2MB 截过一次，这里再按 `budget` 裁一次的目的
+ * 是别把几万字塞进 DOM（浏览器渲染与滚动都会明显变卡）。两道截断都必须写进
+ * 返回文本——「没找到更多失败块」与「更多失败块被裁掉了」是相反结论。
+ */
+export declare function buildPlainFailureExcerpt(rawLog: string, opts?: {
+    budget?: number;
+    truncated?: boolean;
+}): PlainFailureExcerpt;

package/lib/executor/run-log.js

@@ -0,0 +1,78 @@
+/**
+ * 失败日志的两个共用件：错误语义映射 + 纯文本锚点摘要。
+ *
+ * 为什么单独成模块而不是各写一遍：
+ * 同一份 `gh run view --log-failed` 输出有两个消费方——Agent 工具（`github_run`
+ * 的 `log_failed`，渲染成 Markdown 进模型上下文）与人在面板里看的 Run 详情弹窗
+ * （渲染成 `<pre>` 纯文本）。两者的**排版**不同，但「什么算失败、哪条是环境故障
+ * 不是构建故障、被截断了必须说明」这三条语义必须一致；各写一份的下场是
+ * Agent 说「没有失败步骤」而弹窗说「拉取失败」。
+ *
+ * 约束：本模块只做纯文本变换，零 I/O、零子进程。真正的 gh 调用留在调用方，
+ * 方便两边各自决定超时与输出预算。
+ */
+import { extractFailureAnchors, tailLines } from './failure-anchors.js';
+/**
+ * 把 gh 的非零退出翻译成给人看的结论；返回 `null` 表示「这是真错误，原样上抛」。
+ *
+ * 两类必须吸收的错误（实测）：
+ * 1. `no failed jobs` —— 工作流本身成功或没有失败步骤，这是确定性答案而非故障；
+ * 2. `Access is denied` —— gh 往本机缓存目录写日志 zip 被系统拒绝，属宿主环境
+ *    问题。原样透传会让调用方（尤其是模型）误判成构建故障，给出自查路径更可行动。
+ *
+ * runId 参与文案：同一个弹窗里可能并排看几个 run，不带编号的报错无法定位。
+ */
+export function interpretRunLogError(error, runId) {
+    const err = String(error || '');
+    if (err.includes('no failed jobs') || err.includes('not failed')) {
+        return `工作流 Run #${runId} 中未检测到任何失败的任务步骤 (状态正常)。`;
+    }
+    if (err.includes('Access is denied') || err.includes('拒绝访问')) {
+        return `无法提取 Run #${runId} 的失败日志：gh CLI 向本机缓存目录写入日志压缩包时被系统拒绝 (${err.trim().slice(0, 200)})。建议检查 gh 缓存目录（如 %LocalAppData%\\GitHub CLI）的写权限后重试，或改用 github_api 拉取日志端点。`;
+    }
+    return null;
+}
+/**
+ * 把整段日志压成纯文本失败摘要。
+ *
+ * 为什么要有独立的纯文本渲染：弹窗里用 `<pre>` 显示，Markdown 的代码围栏与
+ * 引用块会被当成字面量原样打出来（` ``` ` 出现在日志正文里时更乱）。Markdown 版
+ * 留给 Agent 工具，两者共用同一套锚点萃取与尾部回退，只是排版不同。
+ *
+ * 预算裁剪是**第二道**：gh 侧已按 2MB 截过一次，这里再按 `budget` 裁一次的目的
+ * 是别把几万字塞进 DOM（浏览器渲染与滚动都会明显变卡）。两道截断都必须写进
+ * 返回文本——「没找到更多失败块」与「更多失败块被裁掉了」是相反结论。
+ */
+export function buildPlainFailureExcerpt(rawLog, opts = {}) {
+    const budget = Number.isFinite(opts.budget) && opts.budget > 0 ? Math.floor(opts.budget) : 120_000;
+    const src = typeof rawLog === 'string' ? rawLog : '';
+    if (!src.trim()) {
+        return { text: '', mode: 'empty', blockCount: 0, droppedBlocks: 0, truncated: Boolean(opts.truncated) };
+    }
+    const anchored = extractFailureAnchors(src);
+    const mode = anchored.blocks.length > 0 ? 'anchors' : 'tail';
+    const parts = [];
+    if (opts.truncated) {
+        parts.push('⚠️ 原始日志体量超出单次读取上限，以下仅基于已获取的部分。');
+    }
+    if (mode === 'anchors') {
+        parts.push(`共命中 ${anchored.totalBlocks} 个失败块，以下为前 ${anchored.blocks.length} 个：`);
+        anchored.blocks.forEach((b, i) => {
+            parts.push(`\n===== 失败块 ${i + 1}（日志第 ${b.startLine} 行起）=====\n${b.text}`);
+        });
+        if (anchored.droppedBlocks > 0) {
+            parts.push(`\n⚠️ 另有 ${anchored.droppedBlocks} 个失败块未展示（共 ${anchored.totalBlocks} 个），完整日志请在 GitHub 打开。`);
+        }
+    }
+    else {
+        parts.push('未匹配到已知框架的失败锚点，以下为日志尾部 200 行：\n');
+        parts.push(tailLines(src, 200));
+    }
+    let text = parts.join('\n');
+    let truncated = Boolean(opts.truncated);
+    if (text.length > budget) {
+        text = `${text.slice(0, budget)}\n\n⚠️ 摘要已按 ${budget} 字符上限截断，上述失败块可能不完整。`;
+        truncated = true;
+    }
+    return { text, mode, blockCount: anchored.totalBlocks, droppedBlocks: anchored.droppedBlocks, truncated };
+}

package/lib/executor.d.ts

@@ -1,16 +1,28 @@
-import type { GhExecutionOptions, GhResult, AuthStatus, RepoMetadata, PluginConfig, GitLocalStatus, GitCommitLog, GitCommitEntry, GitBranchesResult } from './types.js';
+import type { GhExecutionOptions, GhResult, AuthStatus, RepoMetadata, PluginConfig, GitLocalStatus, WorkspaceCleanResult, GitCommitLog, GitCommitEntry, GitBranchesResult, AssociatedRepoItem, PrDetailData, IssueDetailData, RunDetailData, RunLogExcerptData } from './types.js';
 import type { ProxyManager } from './proxy.js';
 import { parseGhVersion, compareGhVersions } from './executor/version-utils.js';
 import { spawnWithStdin, safeSlice, cutByUtf8Bytes, truncateOutput } from './executor/process-utils.js';
-import { parseGitStatusOutput, parseGitLogLines, parseGitBranchLines, parseUncommittedDiff, parseGitStatText } from './executor/git-parser.js';
+import { type PrReviewResult } from './executor/pr-review.js';
+import { parseGitStatusOutput, parseGitLogLines, parseGitBranchLines, parseUncommittedDiff, parseGitStatText, parseRemoteUrls, parseGitConfig, resolveRemoteTarget, parseGithubUrl, parseRemoteHost, classifyRepoLayout, pickGithubRemote, splitUnifiedDiff } from './executor/git-parser.js';
+import type { ParsedGitConfig, ParsedRemote } from './executor/git-parser.js';
 import { getPlatformInstallGuide, getGhUpgradeHint } from './executor/platform-guide.js';
-export { parseGhVersion, compareGhVersions, spawnWithStdin, safeSlice, cutByUtf8Bytes, truncateOutput, parseGitStatusOutput, parseGitLogLines, parseGitBranchLines, parseUncommittedDiff, parseGitStatText, getPlatformInstallGuide, getGhUpgradeHint, };
+import { classifyGhError, describeDeterministicError, isRetryableError, permissionRemedy, isPermissionError, type GhErrorKind } from './executor/error-classifier.js';
+export { parseGhVersion, compareGhVersions, spawnWithStdin, safeSlice, cutByUtf8Bytes, truncateOutput, parseGitStatusOutput, parseGitLogLines, parseGitBranchLines, parseUncommittedDiff, parseGitStatText, parseRemoteUrls, parseGitConfig, resolveRemoteTarget, parseGithubUrl, parseRemoteHost, classifyRepoLayout, pickGithubRemote, splitUnifiedDiff, getPlatformInstallGuide, getGhUpgradeHint, classifyGhError, describeDeterministicError, isRetryableError, permissionRemedy, isPermissionError, };
+export type { GhErrorKind, ParsedGitConfig, ParsedRemote };
 export declare class GhExecutor {
     ghPath: string;
     defaultTimeoutMs: number;
     maxOutputChars: number;
     /** UTF-8 字节口径的硬上限；未配置时按 maxOutputChars × 4 推导（覆盖 CJK 3 字节与 emoji 4 字节） */
     maxOutputBytes: number;
+    /**
+     * 累计 gh 子进程调用次数（只增不清零，`run()` 每次 +1）。
+     *
+     * 为什么需要：任务原语（github_task）要如实汇报 `cost.ghCalls`，
+     * 而「原语是否真的比手动串步骤省钱」是这个能力存在的唯一判据。
+     * 消费方用「调用前快照 → 调用后求差」的方式取区间计数。
+     */
+    ghCalls: number;
     /**
      * 列表类查询的默认条数上限。
      * 为什么挂在 executor 而不是给每个工具工厂加 config 参数：executor 是全部
@@ -51,6 +63,34 @@ export declare class GhExecutor {
      * 3. 仅在完全未指定 cwd 且无会话时（全局命令行调用），才兜底回退到最近活跃的 Git 工作区或 process.cwd()。
      */
     resolveWorkspaceCwd(explicitCwd?: string, explicitSessionId?: string): string;
+    /**
+     * 18 个工具的唯一工作区入口：把 execContext 归一成 `{ cwd, sessionId }`。
+     *
+     * 为什么必须走这里而不是各工具写 `execContext?.cwd || process.cwd()`：
+     * 三级解析里第 1 级是「显式 cwd 且磁盘存在即原样返回」，而 `process.cwd()`
+     * 恒满足该条件——于是第 2 级「按 sessionId 反查真实工作区」**永远不会触发**。
+     * 工具层把 `process.cwd()` 当兜底传下去，等于把整个会话亲和机制架空。
+     *
+     * ⚠️ 刻意**不复用** `resolveWorkspaceCwd` 的第 3 级（`findMostRecentWorkspacePath`）：
+     * 那一级是给「完全无上下文的 CLI 场景」用的，会把目录定到**最近活跃的任意仓库**。
+     * 工具调用的默认目录必须可预测——落到一个与本会话无关的仓库意味着读错库、
+     * 更糟的是写到错库（merge / release create / label delete 都会打错地方）。
+     * 实测：抹掉 DSH_SESSION_ID 后 `resolveWorkspaceCwd(undefined, undefined)` 返回的是
+     * 一个与本会话无关的仓库路径，而 `process.cwd()` 是当前进程目录。
+     *
+     * 解析顺序：显式 cwd（原样透传，含不存在的情况，与旧行为一致）→ session 反查 →
+     * process.cwd()。三级都拿不到时才回到进程目录，与 s5 之前的兜底完全一致。
+     */
+    resolveExecScope(execContext?: {
+        cwd?: string;
+        sessionId?: string;
+        session?: {
+            id?: string;
+        };
+    }): {
+        cwd: string;
+        sessionId?: string;
+    };
     /**
      * 安全执行 gh 命令
      * 采用 execFile 参数数组隔离，彻底杜绝 Shell 字符串拼接注入漏洞
@@ -113,7 +153,7 @@ export declare class GhExecutor {
      * 零网络：status 基于 remote-tracking ref（上次 fetch 的快照），毫秒级本地读取，
      * 符合 global-overview 端点「工作区探测不发网络」的性能红线。
      */
-    getLocalGitStatus(cwd?: string): Promise<GitLocalStatus | null>;
+    getLocalGitStatus(cwd?: string, timeoutMs?: number): Promise<GitLocalStatus | null>;
     /**
      * 分页获取本地未提交文件列表（无网络开销，纯本地毫秒级响应）
      */
@@ -170,18 +210,185 @@ export declare class GhExecutor {
      * 零网络往返，毫秒级本地管道输出。
      */
     getGitBranches(cwd?: string): Promise<GitBranchesResult | null>;
+    /**
+     * 发版输入：最近 tag + 该 tag 以来的提交（供 `github_task(prepare_release)` 使用）。
+     *
+     * 为什么要在 executor 里开这个口子，而不是让工具自己拼 git 命令：
+     * 命令形态必须集中（本文件顶部就是"git 白名单"纪律），否则每个新工具都会
+     * 自己发明一套 argv，`phase34` 的契约网也就管不到它们了。
+     *
+     * 安全性：两条命令的形态**全部固定**——`describe --tags --abbrev=0` 无参数注入；
+     * log 的修订范围段只拼 `git describe` 自己的输出，且先过 `/^[A-Za-z0-9._\/-]+$/`
+     * 白名单校验，杜绝把任意字符串当 revision 传进 git。
+     */
+    getReleaseInputs(cwd?: string, fromTagOverride?: string): Promise<{
+        ok: boolean;
+        fromTag: string | null;
+        commits: Array<{
+            sha: string;
+            subject: string;
+            author: string;
+            date: string;
+            body: string;
+        }>;
+        totalCommits: number;
+        error?: string;
+    }>;
+    /**
+     * 工作区干净度闸门（唯一实现）。
+     *
+     * 为什么抽成公共方法：会改变工作区分支/内容的入口有三条——界面切分支（switchGitBranch）、
+     * `github_pr(checkout)`、`github_issue(develop)`。此前只有第一条有脏检查，后两条直穿，
+     * 于是「强阻断」的成文承诺只对界面成立。安全不变量必须只有一处实现。
+     *
+     * 三态语义（fail-closed）：
+     * - `null`（git 读不到）→ 拒绝。读不到状态≠干净，放行等于闸门失效。
+     * - `dirtyCount > 0` → 拒绝，并带前 5 条样例便于用户判断。
+     * - 其余 → 放行。
+     *
+     * 超时为什么单独给 20s：`getLocalGitStatus` 默认 3s 是给概览面板用的（读不到就不渲染那一行），
+     * 但这里是一次安全判决——大型仓库 / 网络盘 / OneDrive 同步目录下 `git status` 冷启动超 3s
+     * 很常见，用 3s 会把"慢"误判成"脏/不可用"，直接把 checkout 挡死。
+     */
+    ensureCleanWorkspace(cwd: string | undefined): Promise<WorkspaceCleanResult>;
     /**
      * 安全切换当前工作区的 Git 分支。
      * 三重安全防御纪律：
      * 1. 目标工作区必须存在有效的 .git 目录；
      * 2. 分支名称严格执行字符白名单校验，防命令行参数注入；
-     * 3. 检查工作区干净度（dirtyCount），若有未提交或未保存的变更直接阻断，杜绝代码被破坏性覆盖。
+     * 3. 工作区干净度交给 ensureCleanWorkspace（唯一实现，与 checkout / develop 共用）。
      */
     switchGitBranch(cwd: string | undefined, branchName: string): Promise<{
         ok: boolean;
         currentBranch?: string;
         error?: string;
     }>;
+    /**
+     * 推导当前工作区可供用户切换的全部关联 GitHub 仓库列表。
+     *
+     * 数据来源（纯本地+拓扑合成，零新增网络开销）：
+     * 1. 扫描本地 .git/config 的所有 GitHub remote（如 origin, upstream 等）；
+     * 2. 若当前仓库为 Fork 且存在 parent（上游），合并上游仓库（支持本地未配 upstream 的情形）；
+     * 3. 标识当前基准 (isCurrent) 及角色 (fork, upstream, origin, parent)。
+     */
+    getAssociatedRepos(cwd?: string, currentRepo?: RepoMetadata | null, currentUser?: string | null): AssociatedRepoItem[];
+    /**
+     * 设置当前工作区的默认基准 GitHub 仓库（调用官方 `gh repo set-default` 并在本地 git config 持久化）。
+     *
+     * 为什么调用 gh repo set-default：
+     * 1. 它会在 .git/config 写入 `remote.<name>.gh-resolved = base`，这是官方的持久化事实源；
+     * 2. 执行后，不仅本插件的 Web 驾驶舱，外部系统终端中运行的 gh pr, gh issue, gh run 也将 100% 对齐；
+     * 3. 严格做参数格式校验，仅允许合法的 owner/repo 或合法 remote 别名，杜绝命令注入。
+     */
+    setDefaultRepo(cwd: string | undefined, targetRepoOrRemote: string): Promise<{
+        ok: boolean;
+        target?: string;
+        error?: string;
+    }>;
+    /**
+     * 获取 Pull Request 完整详情与变更 Diff 数据（用于 PR 在线审阅与代码比对）。
+     *
+     * 架构设计：
+     * 1. 严格参数白名单校验（PR 编号必须为正整数，repo 必须为合法 owner/repo 格式）；
+     * 2. 并行拉取元数据 (gh pr view) 与 Unified Diff (gh pr diff)；
+     * 3. 在内存通过 splitUnifiedDiff 对 Diff 原文按修改文件切片索引，
+     *    前端点击任一文件即可 0ms 呈现代码行级增删对比，绝无二次网络往返。
+     */
+    getPrDetail(cwd?: string, prNumber?: number | string, repo?: string): Promise<{
+        ok: boolean;
+        data?: PrDetailData;
+        error?: string;
+    }>;
+    /**
+     * 提交带行级评注的 PR review（REST 通道）。
+     *
+     * 为什么必须走 REST：`gh pr review` 只有 `--approve/--request-changes/--comment`，
+     * 没有任何行级参数（`gh pr review --help` 里 line/side/path 零命中）。行级评注
+     * 的唯一入口是 `POST /repos/{owner}/{repo}/pulls/{n}/reviews` 的 `comments[]`。
+     *
+     * 为什么一次 review 一个请求（而不是逐条 `POST /pulls/{n}/comments`）：
+     * 通知只发一轮，也避开 secondary rate limit 的「创建内容过快」判定。
+     *
+     * 422 降级：行级评注被拒（典型原因：该行不在 diff 的可评论侧，如纯删除行）
+     * 时，把评注折叠进 review 正文重试一次。内容不能丢，但降级必须显式可见。
+     */
+    createPrReview(cwd: string | undefined, repo: string | undefined, prNumber: number | string, input: {
+        event?: unknown;
+        body?: unknown;
+        comments?: unknown;
+        commit_id?: unknown;
+    }): Promise<PrReviewResult>;
+    /**
+     * 获取 Issue 完整详情（供 IssueDetailModal 在线查看消费）。
+     *
+     * 架构设计：
+     * 1. 严格参数白名单（编号必须为正整数，repo 必须为 owner/repo 形态）——与
+     *    getPrDetail 同一套规则，杜绝任何形式的命令/路径注入；
+     * 2. 单次 `gh issue view --json` 往返即可拿到正文、评论时间线、里程碑与关联 PR，
+     *    不拆成多路并发（Issue 没有 diff 这类重载荷，多开进程反而增加失败面）；
+     * 3. 老版本 gh 遇未知字段会整体失败，因此保留 BASE 字段集降级链。
+     */
+    getIssueDetail(cwd?: string, issueNumber?: number | string, repo?: string): Promise<{
+        ok: boolean;
+        data?: IssueDetailData;
+        error?: string;
+    }>;
+    /**
+     * 详情类接口的仓库参数归一化（PR / Issue / Run 共用）。
+     *
+     * 返回 `''` = 未传（由本地 remote 决定）；返回 `null` = 非法。
+     *
+     * 为什么要收编三处各自的校验：历史实现各写一份正则，只有 `setDefaultRepo` 额外
+     * 拒绝 `-` 开头与 `..`，其余靠「恒以 `-R <value>` 成对传入」兜底（复核报告 C-13）。
+     * 「成对传入所以安全」是当前调用形状的安全，不是接口的安全——多一处调用方就多
+     * 一次赌。统一到这里后，`-` 开头/`..`/反斜杠在任何详情入口都进不来。
+     */
+    private normalizeRepoFullName;
+    /**
+     * 获取单次 Actions Run 的完整详情（run + jobs + steps）。
+     *
+     * 架构设计：
+     * 1. **run_id 只认纯数字**。它会被当作 `gh run view` 的位置参数拼进 argv，
+     *    不做白名单就等于把「用参数值注入 flag」这条已知缺陷（复核报告 C-01）
+     *    复制到新通道——`--web`、`--log` 都能冒充编号。
+     * 2. 单次往返拿全：`jobs` 里已经包含 steps 树，没有需要并行拉取的第二路。
+     * 3. **日志不在这里拉**。实测单次失败日志 4–40 秒（本机代理下还直接连接重置），
+     *    挂在详情上等于让弹窗首屏去赌网络；日志走 getRunLogExcerpts() 按需拉。
+     */
+    getRunDetail(cwd?: string, runId?: number | string, repo?: string): Promise<{
+        ok: boolean;
+        data?: RunDetailData;
+        error?: string;
+    }>;
+    /**
+     * 按需拉取失败日志并压成纯文本摘要（供 Run 详情弹窗消费）。
+     *
+     * 与 github_run(log_failed) 的关系：同一份 `--log-failed` 原始输出、同一套锚点
+     * 萃取与尾部回退，只是排版不同（弹窗要的是 `<pre>` 纯文本，不是 Markdown）。
+     *
+     * 为什么逐 job 拉而不是整 run 一次拉：`gh run view --log-failed` 会把**整次运行**
+     * 的日志包都下载下来再过滤，矩阵构建下等于为了一个失败 job 拖几十 MB；`-j <jobId>`
+     * 是 gh 支持的定向形态（见 `gh run view --help`），失败 job 通常只有 1–3 个。
+     *
+     * 为什么单个 job 失败仍返回 ok:true：部分成功比整体失败有用——已拿到的块照常展示，
+     * 失败的那个进 errors[] 并在界面上显式可重试。只有参数非法才是 ok:false。
+     */
+    getRunLogExcerpts(cwd?: string, runId?: number | string, jobIds?: Array<number | string>, repo?: string, 
+    /**
+     * 本批日志的总预算（毫秒，默认 `RUN_LOG_TOTAL_BUDGET_MS`）。
+     *
+     * 为什么需要：单 job 超时 60s × 最多 3 个串行 = 最坏 180s。这个调用挂在 HTTP
+     * 路由上，而宿主 WebServer 是全 GUI 共享的——一次点击占住三分钟不可接受。
+     * 超预算的 job 进 `errors[]`（显式、可单独重试），而不是让连接一直挂着。
+     * 允许外部传入只为可测：传 0 能验证「超预算」分支而不必真的等待。
+     */
+    opts?: {
+        totalBudgetMs?: number;
+    }): Promise<{
+        ok: boolean;
+        data?: RunLogExcerptData;
+        error?: string;
+    }>;
     /** 生成当前操作系统平台的推荐安装引导与命令 */
     private getPlatformInstallGuide;
     /**
@@ -201,13 +408,77 @@ export declare class GhExecutor {
      */
     private probeAuth;
     /**
-     * 仅从本地 .git/config 解析仓库身份，绝不发起网络请求。
+     * 从 `refs/remotes/<remote>/HEAD` 符号引用中读取仓库默认分支。
+     *
+     * 为什么只认这一个来源（其余全部实测排除）：
+     *   - `packed-refs` 只存具体 sha，不含 symbolic ref —— 读不到；
+     *   - 当前 HEAD 指向的是**用户 checkout 的分支**，不是仓库默认分支，语义错误；
+     *   - 猜 main/master —— 无依据，宁可回落固定值也不猜。
+     *
+     * @returns 分支名；文件不存在（未 fetch 过）或内容不是符号引用时返回 null，
+     *          由调用方回落到既有默认值（保持原有行为，不引入新错误）
+     */
+    readDefaultBranchFromRef(remoteName: string, cwd?: string): string | null;
+    /**
+     * 解析工作区真实的 git 目录的**两个**路径：局部目录与共享仓库目录。
+     *
+     * 为什么必须分开：worktree 的 `HEAD` 在局部目录（`.git/worktrees/<name>/HEAD`），
+     * 而 `config` 在共享目录（`commondir` 指向处）。只解析其中一个必然读错：
+     *   - 只读局部 → 找不到 config（remote 配置在共享目录）
+     *   - 只读共享 → 拿到**主工作树**的分支名，进而按错误分支查 `branch.*.remote`
+     *
+     * 实测：主工作树 HEAD 是 `ref: refs/heads/master`，worktree 的是 `ref: refs/heads/feat`。
+     *
+     * 常规仓库两者指向同一目录。
+     *
+     * @returns 两个绝对路径；非 Git 目录/指针不可解析时返回 null（绝不抛错）
+     */
+    resolveGitDirInfo(cwd?: string): {
+        localDir: string;
+        commonDir: string;
+    } | null;
+    /**
+     * 解析工作区真实的 git 目录（共享仓库目录）。
+     * 薄封装自 resolveGitDirInfo：读 `config` 的场景（远程指纹）只需要共享目录。
+     */
+    resolveGitDirPath(cwd?: string): string | null;
+    /**
+     * remote 配置指纹：全部 remote url 去重、排序、拼接后取 SHA-256 前 12 位。
+     *
+     * 为什么不用身份解析做缓存失效判定：身份解析要回答「变成了什么」，
+     * 一旦解析器对某种 config 布局有偏差（如双 remote 时取错 remote 段），
+     * 比对就永远失配——缓存再也不命中，每次请求都重拉全部 gh 子进程。
+     * 指纹只回答「变了没有」，不依赖任何语义理解，因此对该类偏差免疫。
+     *
+     * 反例（实测）：`git remote rename origin upstream` 后 `git remote add origin <fork>`，
+     * config 里 upstream 段排在 origin 段前，取「第一个 github.com 匹配」会拿到上游，
+     * 而 git 权威解析（branch.<name>.remote → origin）拿到的是 fork。
+     *
+     * @returns 12 位十六进制指纹；仅当「非 Git 目录 / config 不可读」时返回 null
+     *          （调用方据此保守判定为「未变更」，绝不因探测失败误清空缓存）。
+     *          注意：**config 可读但没有任何 remote 时返回的是空集合的哈希，不是 null**——
+     *          「仓库没有远程」是一个确定事实，它与「读不到配置」必须区分开：
+     *          否则用户删光 remote 后指纹恒为 null，旧快照再也无法失效。
+     */
+    getRemoteFingerprint(cwd?: string): string | null;
+    /**
+     * 读取并解析工作区的 git 远程视图（`.git/config` + `HEAD`）。
+     * 内部方法：把「两个路径各读哪个文件」的细节收敛在一处，
+     * 避免各调用点自己拼路径读错 worktree 的文件。
+     */
+    private readParsedGitConfig;
+    /**
+     * 仅从本地 `.git/config` 解析仓库身份，绝不发起网络请求。
      *
      * 为什么需要它：全局驾驶舱要为每个工作区认识别仓库，而 getRepoMetadata 会调用
      * `gh repo view` 走网络。实测 5 个工作区时该端点冷启动 20.5 秒，其中绝大部分耗在这 5 次
      * 网络往返上——而有界并发根本救不了它，因为瓶颈是网络延迟而不是进程排队。
      * 工作区矩阵只需要「这个目录属于哪个仓库」这一身份信息，本地 .git/config 已经完整具备，
      * 描述/star 数等富字段是当前仓库详情才需要的。这一步把每个工作区从 1 次网络往返降为 0。
+     *
+     * 解析口径与 git 一致（三级回落），不再「取 config 里第一个 github.com 匹配」——
+     * 后者在 `git remote rename origin upstream` + `add origin <fork>` 的布局下会取到上游，
+     * 而 git 认的是 origin（实测）。
      */
     getRepoIdentityFromLocal(cwd?: string): RepoMetadata | null;
     /**