dsh-github-flow 0.5.0 → 0.6.0

package/lib/executor.js

@@ -1,16 +1,91 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { findMostRecentWorkspacePath, findWorkspacePathBySession, hasGitDir } from './workspace.js';
+// 图片 URL 提取复用 Agent 工具链的同一份实现：弹窗只展示计数与外链，
+// 但「哪些 URL 算图片」必须与 github_issue(view_images) 完全同源，否则
+// 用户会看到「附件 2 张」却下载不到对应图片。
+import { extractImageUrls } from './tools/image-utils.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, parseUncommittedDiff, parseGitStatText } from './executor/git-parser.js';
+import { parseGitStatusOutput, parseGitLogLines, parseGitBranchLines, parseUncommittedDiff, parseGitStatText, parseRemoteUrls, parseGitConfig, resolveRemoteTarget, parseGithubUrl, parseRemoteHost, classifyRepoLayout, pickGithubRemote, splitUnifiedDiff, } 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 } 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, };
 const execFileAsync = promisify(execFile);
+/**
+ * `gh repo view` 的字段集。
+ *
+ * 为什么必须集中一处：同一份字段列表此前在 getRepoMetadata 里重复了两遍，
+ * 补字段时漏改一处就会出现「在线路径有 isFork、兜底路径没有」的不一致。
+ *
+ * 字段取舍：
+ *   - parent 只返回骨架（id/name/owner.login），不含 stargazerCount
+ *     ——`--json` 不支持嵌套子字段（实测 `Unknown JSON field: "parent.stargazerCount"`）
+ *   - viewerPermission 是只读仓库的写操作前置拦截依据
+ */
+const REPO_VIEW_FIELDS = 'nameWithOwner,name,owner,defaultBranchRef,description,isPrivate,url,stargazerCount,forkCount,isFork,parent,viewerPermission';
+/**
+ * `gh issue view --json` 的完整字段集（gh 2.96.0 实测的合法全集子集）。
+ *
+ * 为什么集中一处：同一份字段列表要被「常规调用」与「降级重试」两处消费，
+ * 散落成字面量必然漂移。字段取舍全部基于实测响应形态：
+ *   - `closedByPullRequestsReferences` 节点只有 id/number/repository/url，
+ *     不含 title/state，UI 因此只渲染编号链接；
+ *   - `milestone` 形态为 {number,title,description,dueOn}，没有 state；
+ *   - `subIssuesSummary` 为 {completed,percentCompleted,total}。
+ */
+const ISSUE_DETAIL_FULL_FIELDS = 'number,title,state,stateReason,author,createdAt,updatedAt,closedAt,url,body,labels,assignees,milestone,isPinned,issueType,comments,closedByPullRequestsReferences,subIssuesSummary';
+/**
+ * Issue 详情的降级字段集。
+ *
+ * 为什么需要：老版本 gh 遇到未知 JSON 字段会**整体失败**（实测
+ * `gh issue view --json bogusField` → `Unknown JSON field: "bogusField"`）。
+ * 这里只保留长期稳定、几乎不可能被移除的字段，保证低版本宿主仍能看到
+ * 正文与评论时间线——缺失的里程碑/关联 PR 只是少几个装饰位，不致命。
+ */
+const ISSUE_DETAIL_BASE_FIELDS = 'number,title,state,author,createdAt,updatedAt,url,body,labels,assignees,milestone,comments';
+/**
+ * 把 `gh repo view --json` 的原始结果映射为 RepoMetadata。
+ *
+ * 抽出的理由：同一段映射原先在 getRepoMetadata 里写了两遍（上下文探测 + 精确探测），
+ * 逐字符相同。补 3 个字段要改两处，必然漂移。
+ *
+ * @param fallbackNameWithOwner d.nameWithOwner 缺失时的兜底（离线解析结果）
+ */
+function mapRepoMetadata(d, fallbackNameWithOwner) {
+    const nameWithOwner = d?.nameWithOwner || fallbackNameWithOwner || '';
+    const meta = {
+        nameWithOwner,
+        name: d?.name || '',
+        owner: d?.owner?.login || '',
+        defaultBranch: d?.defaultBranchRef?.name || 'main',
+        description: d?.description || '',
+        isPrivate: Boolean(d?.isPrivate),
+        url: d?.url || `https://github.com/${nameWithOwner}`,
+        stargazerCount: typeof d?.stargazerCount === 'number' ? d.stargazerCount : 0,
+        forkCount: typeof d?.forkCount === 'number' ? d.forkCount : 0,
+    };
+    if (typeof d?.isFork === 'boolean')
+        meta.isFork = d.isFork;
+    // parent 的 nameWithOwner 需自行拼接：gh 只给 {name, owner:{login}}
+    const parentOwner = d?.parent?.owner?.login;
+    const parentName = d?.parent?.name;
+    if (typeof d?.isFork === 'boolean' && d.isFork && typeof parentOwner === 'string' && typeof parentName === 'string') {
+        const parentFull = `${parentOwner}/${parentName}`;
+        meta.parent = { nameWithOwner: parentFull, url: `https://github.com/${parentFull}` };
+    }
+    // 只接受已知档位，未知值一律不带——避免把陌生的 gh 新档位当成可写权限
+    const perm = typeof d?.viewerPermission === 'string' ? d.viewerPermission.toUpperCase() : '';
+    if (perm === 'ADMIN' || perm === 'MAINTAIN' || perm === 'WRITE' || perm === 'TRIAGE' || perm === 'READ') {
+        meta.viewerPermission = perm;
+    }
+    return meta;
+}
 /** 认证状态缓存时长。用户手动 `gh auth login/logout` 后最多 30 秒内面板才会反映，属可接受代价 */
 const AUTH_CACHE_TTL_MS = 30_000;
 /** gh 版本缓存时长。与 authCache 同哲学：gh 升级是分钟级低频事件，30 秒陈旧窗口无实际影响 */
@@ -162,7 +237,8 @@ export class GhExecutor {
                 const errBuf = Buffer.isBuffer(stderr) ? stderr : (stderr ? Buffer.from(String(stderr)) : null);
                 if (!buf.length) {
                     const errMsg = errBuf ? errBuf.toString('utf8').trim() : '';
-                    return { ok: false, error: errMsg || '二进制输出为空' };
+                    const msg = errMsg || '二进制输出为空';
+                    return { ok: false, error: msg, errorKind: classifyGhError(msg) };
                 }
                 return { ok: true, data: buf, binaryBytes: buf.length, truncated: false };
             }
@@ -172,7 +248,7 @@ export class GhExecutor {
             if (!rawOutput && errText) {
                 rawOutput = errText.trim();
             }
-            const outcome = truncateOutput(rawOutput, this.maxOutputChars, this.maxOutputBytes);
+            const outcome = truncateOutput(rawOutput, options.maxOutputChars ?? this.maxOutputChars, options.maxOutputBytes ?? this.maxOutputBytes);
             rawOutput = outcome.text;
             const truncated = outcome.truncated;
             // 如果未被截断且命令带有 --json 或包含 api，尝试解析为 JSON
@@ -214,10 +290,24 @@ export class GhExecutor {
                     rawOutput = truncateOutput(outText.trim(), this.maxOutputChars, this.maxOutputBytes).text;
                 }
             }
+            // 权限不足时的处置指引。
+            //
+            // 为什么在 executor 层拼进 error，而不是让 97 个工具调用点各自 `throw new Error(res.error + hint)`：
+            // 全仓有 97 处 `throw new Error(res.error)`，逐一改必然遗漏；而模型只能看到 error
+            // 字符串，不拼进去等于永远看不到指引。在唯一的事实源处拼一次，所有调用点自动获益。
+            //
+            // permissionRemedy 字段仍然独立保留：程序化消费方（未来的 UI、诊断面板）
+            // 可以只取指引而不用从 error 里再解析一遍。
+            const remedy = permissionRemedy(friendlyError, args.join(' '));
+            const finalError = remedy ? `${friendlyError}\n\n${remedy}` : friendlyError;
             return {
                 ok: false,
-                error: friendlyError,
+                error: finalError,
                 rawOutput,
+                // 失败语义分类：上层（概览路由 / UI 重试器）据此决定是重试、回退快照
+                // 还是直接把「仓库关了 Issues」降级成空列表。分类只有这一处事实源。
+                errorKind: classifyGhError(friendlyError),
+                ...(remedy ? { permissionRemedy: remedy } : {}),
             };
         }
     }
@@ -699,6 +789,383 @@ export class GhExecutor {
             return { ok: false, error: msg };
         }
     }
+    /**
+     * 推导当前工作区可供用户切换的全部关联 GitHub 仓库列表。
+     *
+     * 数据来源（纯本地+拓扑合成，零新增网络开销）：
+     * 1. 扫描本地 .git/config 的所有 GitHub remote（如 origin, upstream 等）；
+     * 2. 若当前仓库为 Fork 且存在 parent（上游），合并上游仓库（支持本地未配 upstream 的情形）；
+     * 3. 标识当前基准 (isCurrent) 及角色 (fork, upstream, origin, parent)。
+     */
+    getAssociatedRepos(cwd, currentRepo, currentUser) {
+        const items = [];
+        const seen = new Set();
+        const cfg = this.readParsedGitConfig(cwd);
+        if (cfg && Array.isArray(cfg.remotes)) {
+            for (const r of cfg.remotes) {
+                const gh = parseGithubUrl(r.url);
+                if (!gh)
+                    continue;
+                const full = `${gh.owner}/${gh.repo}`;
+                const fullKey = full.toLowerCase();
+                if (seen.has(fullKey))
+                    continue;
+                seen.add(fullKey);
+                const isCurrent = Boolean(currentRepo && currentRepo.nameWithOwner && currentRepo.nameWithOwner.toLowerCase() === fullKey);
+                let role = 'remote';
+                if (r.name === 'upstream') {
+                    role = 'upstream';
+                }
+                else if (currentUser && gh.owner.toLowerCase() === currentUser.toLowerCase()) {
+                    role = 'fork';
+                }
+                else if (r.name === 'origin') {
+                    role = 'origin';
+                }
+                items.push({
+                    nameWithOwner: full,
+                    remoteName: r.name,
+                    url: `https://github.com/${full}`,
+                    isCurrent,
+                    role,
+                });
+            }
+        }
+        // 若当前是在线识别出的 Fork 仓库且存在 parent，但本地尚未配置 upstream remote
+        if (currentRepo?.isFork && currentRepo.parent?.nameWithOwner) {
+            const parentFull = currentRepo.parent.nameWithOwner;
+            const parentKey = parentFull.toLowerCase();
+            if (!seen.has(parentKey)) {
+                seen.add(parentKey);
+                const isCurrent = Boolean(currentRepo.nameWithOwner && currentRepo.nameWithOwner.toLowerCase() === parentKey);
+                items.push({
+                    nameWithOwner: parentFull,
+                    url: currentRepo.parent.url || `https://github.com/${parentFull}`,
+                    isCurrent,
+                    role: 'parent',
+                });
+            }
+        }
+        return items;
+    }
+    /**
+     * 设置当前工作区的默认基准 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 别名，杜绝命令注入。
+     */
+    async setDefaultRepo(cwd, targetRepoOrRemote) {
+        const targetCwd = this.resolveWorkspaceCwd(cwd);
+        if (!hasGitDir(targetCwd)) {
+            return { ok: false, error: '当前工作区不是有效的 Git 仓库' };
+        }
+        const clean = (targetRepoOrRemote || '').trim();
+        // 安全白名单校验：只允许字母、数字、点号、短横线、下划线及至多一个斜杠（owner/repo 或 remoteName）
+        if (!clean || clean.startsWith('-') || clean.includes('..') || clean.includes('\\') || !/^[a-zA-Z0-9_.-]+(\/[a-zA-Z0-9_.-]+)?$/.test(clean)) {
+            return { ok: false, error: '非法目标仓库参数，仅允许 owner/repo 或有效 remote 别名' };
+        }
+        const r = await this.run(['repo', 'set-default', clean], {
+            cwd: targetCwd,
+            timeoutMs: 10_000,
+        });
+        if (!r.ok) {
+            return { ok: false, error: r.error || '设置默认基准仓库失败' };
+        }
+        return { ok: true, target: clean };
+    }
+    /**
+     * 获取 Pull Request 完整详情与变更 Diff 数据（用于 PR 在线审阅与代码比对）。
+     *
+     * 架构设计：
+     * 1. 严格参数白名单校验（PR 编号必须为正整数，repo 必须为合法 owner/repo 格式）；
+     * 2. 并行拉取元数据 (gh pr view) 与 Unified Diff (gh pr diff)；
+     * 3. 在内存通过 splitUnifiedDiff 对 Diff 原文按修改文件切片索引，
+     *    前端点击任一文件即可 0ms 呈现代码行级增删对比，绝无二次网络往返。
+     */
+    async getPrDetail(cwd, prNumber, repo) {
+        const targetCwd = this.resolveWorkspaceCwd(cwd);
+        const num = Number(prNumber);
+        if (!num || isNaN(num) || num <= 0) {
+            return { ok: false, error: '缺少有效 PR 编号（必须为正整数）' };
+        }
+        const cleanRepo = typeof repo === 'string' ? repo.trim() : '';
+        if (cleanRepo && !/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(cleanRepo)) {
+            return { ok: false, error: '非法仓库全名参数（仅允许 owner/repo 格式）' };
+        }
+        const viewArgs = [
+            'pr',
+            'view',
+            String(num),
+            '--json',
+            'number,title,state,isDraft,url,createdAt,updatedAt,author,baseRefName,headRefName,body,reviewDecision,statusCheckRollup,comments,reviews,files,additions,deletions',
+        ];
+        if (cleanRepo)
+            viewArgs.push('-R', cleanRepo);
+        const diffArgs = ['pr', 'diff', String(num)];
+        if (cleanRepo)
+            diffArgs.push('-R', cleanRepo);
+        /**
+         * 行级审查评论的抓取通道。
+         *
+         * 为什么单独走 API：`gh pr view --json comments` 只返回对话区（issue-level），
+         * 挂在代码行上的 review comment 一条都拿不到。实测 cli/cli#14752 有 10 条
+         * 行级评论而 `--json comments` 为零。
+         */
+        const fetchLineComments = async (fullName) => {
+            if (!fullName)
+                return [];
+            const r = await this.run([`api`, `repos/${fullName}/pulls/${num}/comments?per_page=100`], { cwd: targetCwd, timeoutMs: 12_000 });
+            if (!r.ok || !Array.isArray(r.data))
+                return [];
+            return r.data
+                .filter((c) => c && typeof c.path === 'string')
+                .map((c) => ({
+                id: String(c.id ?? ''),
+                path: String(c.path),
+                line: typeof c.line === 'number' ? c.line : (typeof c.original_line === 'number' ? c.original_line : null),
+                side: c.side ? String(c.side) : undefined,
+                author: { login: String(c.user?.login || 'unknown') },
+                body: String(c.body || ''),
+                createdAt: String(c.created_at || ''),
+            }));
+        };
+        // 本地可推导出仓库全名时就三路并发（UI 通常已传入 repo），
+        // 推导不出则先用空结果占位，待 view 返回后从权威 url 补拉。
+        const repoGuess = cleanRepo || (this.getRepoIdentityFromLocal(targetCwd)?.nameWithOwner || '');
+        const [rView, rDiff, guessedLineComments] = await Promise.all([
+            this.run(viewArgs, { cwd: targetCwd, timeoutMs: 15_000 }),
+            // PR diff 走程序化消费通道（按文件切片，一次只渲染一个文件），
+            // 不进入模型上下文，因此显式放宽 24KB 默认阈值——实测普通 PR 的
+            // diff 已达 39KB，沿用默认会被静默截断，导致后半数文件点开皆空。
+            this.run(diffArgs, {
+                cwd: targetCwd,
+                timeoutMs: 25_000,
+                rawText: true,
+                maxOutputChars: 2_000_000,
+                maxOutputBytes: 8 * 1024 * 1024,
+            }),
+            // 第三路：行级审查评论。本地能推导仓库名时与上面两路并发，不增加串行等待。
+            repoGuess ? fetchLineComments(repoGuess) : Promise.resolve([]),
+        ]);
+        if (!rView.ok || !rView.data) {
+            return { ok: false, error: rView.error || `获取 PR #${num} 详情失败` };
+        }
+        const raw = rView.data;
+        // 本地推不出仓库名（无 repo 参数且非 Git 目录）时，用 view 返回的权威 URL
+        // 补拉一次行级评论。这是少见路径，多一次往返换来评论不丢，值得。
+        let lineComments = guessedLineComments;
+        if (!repoGuess) {
+            const m = /github\.com\/([^/]+)\/([^/]+)\/pull\//i.exec(String(raw.url || ''));
+            if (m)
+                lineComments = await fetchLineComments(`${m[1]}/${m[2]}`);
+        }
+        const fullDiff = rDiff.ok ? (typeof rDiff.data === 'string' ? rDiff.data : rDiff.rawOutput || '') : '';
+        const fileDiffs = splitUnifiedDiff(fullDiff);
+        const prDetail = {
+            number: Number(raw.number) || num,
+            title: String(raw.title || ''),
+            state: (raw.state || 'OPEN').toUpperCase(),
+            isDraft: Boolean(raw.isDraft),
+            url: String(raw.url || ''),
+            createdAt: String(raw.createdAt || ''),
+            updatedAt: String(raw.updatedAt || ''),
+            author: {
+                login: String(raw.author?.login || 'ghost'),
+                avatarUrl: raw.author?.avatarUrl ? String(raw.author.avatarUrl) : undefined,
+            },
+            headRefName: String(raw.headRefName || ''),
+            baseRefName: String(raw.baseRefName || ''),
+            headRepoOwner: raw.headRepositoryOwner?.login ? String(raw.headRepositoryOwner.login) : undefined,
+            body: String(raw.body || ''),
+            reviewDecision: raw.reviewDecision ? String(raw.reviewDecision) : undefined,
+            statusCheckRollup: raw.statusCheckRollup,
+            additions: Number(raw.additions) || 0,
+            deletions: Number(raw.deletions) || 0,
+            files: Array.isArray(raw.files)
+                ? raw.files.map((f) => ({
+                    path: String(f.path || ''),
+                    additions: Number(f.additions) || 0,
+                    deletions: Number(f.deletions) || 0,
+                    changeType: String(f.changeType || 'MODIFIED'),
+                }))
+                : [],
+            comments: Array.isArray(raw.comments)
+                ? raw.comments.map((c) => ({
+                    id: String(c.id || ''),
+                    author: {
+                        login: String(c.author?.login || 'unknown'),
+                        avatarUrl: c.author?.avatarUrl ? String(c.author.avatarUrl) : undefined,
+                    },
+                    authorAssociation: c.authorAssociation ? String(c.authorAssociation) : undefined,
+                    body: String(c.body || ''),
+                    createdAt: String(c.createdAt || ''),
+                    url: String(c.url || ''),
+                }))
+                : [],
+            reviews: Array.isArray(raw.reviews)
+                ? raw.reviews.map((rv) => ({
+                    id: String(rv.id || ''),
+                    author: { login: String(rv.author?.login || 'unknown') },
+                    state: String(rv.state || ''),
+                    body: String(rv.body || ''),
+                    submittedAt: String(rv.submittedAt || ''),
+                }))
+                : [],
+            fileDiffs,
+            lineComments,
+            ...(rDiff.truncated ? { diffTruncated: true } : {}),
+        };
+        return { ok: true, data: prDetail };
+    }
+    /**
+     * 获取 Issue 完整详情（供 IssueDetailModal 在线查看消费）。
+     *
+     * 架构设计：
+     * 1. 严格参数白名单（编号必须为正整数，repo 必须为 owner/repo 形态）——与
+     *    getPrDetail 同一套规则，杜绝任何形式的命令/路径注入；
+     * 2. 单次 `gh issue view --json` 往返即可拿到正文、评论时间线、里程碑与关联 PR，
+     *    不拆成多路并发（Issue 没有 diff 这类重载荷，多开进程反而增加失败面）；
+     * 3. 老版本 gh 遇未知字段会整体失败，因此保留 BASE 字段集降级链。
+     */
+    async getIssueDetail(cwd, issueNumber, repo) {
+        const targetCwd = this.resolveWorkspaceCwd(cwd);
+        const num = Number(issueNumber);
+        if (!num || isNaN(num) || num <= 0 || !Number.isInteger(num)) {
+            return { ok: false, error: '缺少有效 Issue 编号（必须为正整数）' };
+        }
+        const cleanRepo = typeof repo === 'string' ? repo.trim() : '';
+        if (cleanRepo && !/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(cleanRepo)) {
+            return { ok: false, error: '非法仓库全名参数（仅允许 owner/repo 格式）' };
+        }
+        const buildArgs = (fields) => {
+            const args = ['issue', 'view', String(num), '--json', fields];
+            if (cleanRepo)
+                args.push('-R', cleanRepo);
+            return args;
+        };
+        /**
+         * 输出阈值必须显式放宽。
+         *
+         * 为什么：executor 默认 maxOutputChars=24000，实测含 149 条评论的 Issue
+         * JSON 达 117KB；一旦被截断，run() 会跳过 JSON.parse，data 恒为 undefined，
+         * 于是弹窗只能显示「元数据全空 + 零评论」的假详情——比报错更糟。
+         * 放宽到 2M/8MB 与 getPrDetail 的 diff 通道同口径。
+         */
+        const execOpts = {
+            cwd: targetCwd,
+            timeoutMs: 20_000,
+            maxOutputChars: 2_000_000,
+            maxOutputBytes: 8 * 1024 * 1024,
+        };
+        let fieldsDegraded = false;
+        let r = await this.run(buildArgs(ISSUE_DETAIL_FULL_FIELDS), execOpts);
+        // 老版本 gh 会以 `Unknown JSON field: "closedAt"` 整体拒绝：
+        // 这不是网络问题，也不该让整个功能不可用——退回长期稳定字段集重试一次。
+        if (!r.ok && /Unknown JSON field/i.test(String(r.error || ''))) {
+            fieldsDegraded = true;
+            r = await this.run(buildArgs(ISSUE_DETAIL_BASE_FIELDS), execOpts);
+        }
+        if (!r.ok) {
+            return { ok: false, error: r.error || `获取 Issue #${num} 详情失败` };
+        }
+        // 截断 / 解析失败都必须显式失败：静默返回空评论会被误读成「没有讨论」。
+        if (r.truncated || !r.data || typeof r.data !== 'object') {
+            return {
+                ok: false,
+                error: `Issue #${num} 的讨论内容过长，已超出插件单次读取上限。请在浏览器中查看完整讨论（${cleanRepo ? `https://github.com/${cleanRepo}/issues/${num}` : '仓库 Issues 页面'}）。`,
+            };
+        }
+        const raw = r.data;
+        const comments = Array.isArray(raw.comments)
+            ? raw.comments.map((c) => ({
+                id: String(c.id || ''),
+                author: {
+                    login: String(c.author?.login || 'ghost'),
+                    avatarUrl: c.author?.avatarUrl ? String(c.author.avatarUrl) : undefined,
+                },
+                authorAssociation: c.authorAssociation ? String(c.authorAssociation) : undefined,
+                body: String(c.body || ''),
+                createdAt: String(c.createdAt || ''),
+                url: String(c.url || ''),
+                ...(c.isMinimized === true ? { isMinimized: true } : {}),
+                ...(c.minimizedReason ? { minimizedReason: String(c.minimizedReason) } : {}),
+                ...(c.includesCreatedEdit === true ? { includesCreatedEdit: true } : {}),
+            }))
+            : [];
+        const body = String(raw.body || '');
+        // 图片清单：正文 + 全部评论合并去重，与 github_issue(view_images) 同源
+        const imageSources = [body];
+        for (const c of comments)
+            imageSources.push(c.body);
+        const images = Array.from(new Set(imageSources.flatMap((b) => extractImageUrls(b))));
+        const linkedPrs = Array.isArray(raw.closedByPullRequestsReferences)
+            ? raw.closedByPullRequestsReferences
+                .filter((p) => p && Number(p.number) > 0)
+                .map((p) => {
+                const repoName = p.repository?.name && p.repository?.owner?.login
+                    ? `${p.repository.owner.login}/${p.repository.name}`
+                    : undefined;
+                return {
+                    number: Number(p.number),
+                    url: String(p.url || ''),
+                    ...(repoName ? { repository: repoName } : {}),
+                };
+            })
+            : [];
+        const detail = {
+            number: Number(raw.number) || num,
+            title: String(raw.title || ''),
+            state: String(raw.state || 'OPEN').toUpperCase() === 'CLOSED' ? 'CLOSED' : 'OPEN',
+            stateReason: raw.stateReason ? String(raw.stateReason) : undefined,
+            url: String(raw.url || ''),
+            createdAt: String(raw.createdAt || ''),
+            updatedAt: String(raw.updatedAt || ''),
+            closedAt: raw.closedAt ? String(raw.closedAt) : undefined,
+            author: {
+                login: String(raw.author?.login || 'ghost'),
+                avatarUrl: raw.author?.avatarUrl ? String(raw.author.avatarUrl) : undefined,
+            },
+            body,
+            labels: Array.isArray(raw.labels)
+                ? raw.labels.map((l) => ({
+                    name: String(l.name || ''),
+                    ...(l.color ? { color: String(l.color) } : {}),
+                    ...(l.description ? { description: String(l.description) } : {}),
+                }))
+                : [],
+            assignees: Array.isArray(raw.assignees)
+                ? raw.assignees
+                    .map((a) => ({ login: String(a.login || '') }))
+                    .filter((a) => a.login)
+                : [],
+            ...(raw.milestone && raw.milestone.title
+                ? {
+                    milestone: {
+                        ...(typeof raw.milestone.number === 'number' ? { number: raw.milestone.number } : {}),
+                        title: String(raw.milestone.title),
+                        ...(raw.milestone.dueOn ? { dueOn: String(raw.milestone.dueOn) } : {}),
+                    },
+                }
+                : {}),
+            ...(raw.isPinned === true ? { isPinned: true } : {}),
+            ...(raw.issueType?.name ? { issueType: String(raw.issueType.name) } : {}),
+            comments,
+            linkedPrs,
+            ...(raw.subIssuesSummary && typeof raw.subIssuesSummary.total === 'number'
+                ? {
+                    subIssues: {
+                        completed: Number(raw.subIssuesSummary.completed) || 0,
+                        total: Number(raw.subIssuesSummary.total) || 0,
+                    },
+                }
+                : {}),
+            images,
+            ...(fieldsDegraded ? { fieldsDegraded: true } : {}),
+        };
+        return { ok: true, data: detail };
+    }
     /** 生成当前操作系统平台的推荐安装引导与命令 */
     getPlatformInstallGuide() {
         return getPlatformInstallGuide();
@@ -828,41 +1295,208 @@ export class GhExecutor {
         };
     }
     /**
-     * 仅从本地 .git/config 解析仓库身份，绝不发起网络请求。
+     * 从 `refs/remotes/<remote>/HEAD` 符号引用中读取仓库默认分支。
      *
-     * 为什么需要它：全局驾驶舱要为每个工作区认识别仓库，而 getRepoMetadata 会调用
-     * `gh repo view` 走网络。实测 5 个工作区时该端点冷启动 20.5 秒，其中绝大部分耗在这 5 次
-     * 网络往返上——而有界并发根本救不了它，因为瓶颈是网络延迟而不是进程排队。
-     * 工作区矩阵只需要「这个目录属于哪个仓库」这一身份信息，本地 .git/config 已经完整具备，
-     * 描述/star 数等富字段是当前仓库详情才需要的。这一步把每个工作区从 1 次网络往返降为 0。
+     * 为什么只认这一个来源（其余全部实测排除）：
+     *   - `packed-refs` 只存具体 sha，不含 symbolic ref —— 读不到；
+     *   - 当前 HEAD 指向的是**用户 checkout 的分支**，不是仓库默认分支，语义错误；
+     *   - 猜 main/master —— 无依据，宁可回落固定值也不猜。
+     *
+     * @returns 分支名；文件不存在（未 fetch 过）或内容不是符号引用时返回 null，
+     *          由调用方回落到既有默认值（保持原有行为，不引入新错误）
      */
-    getRepoIdentityFromLocal(cwd) {
+    readDefaultBranchFromRef(remoteName, cwd) {
+        try {
+            const info = this.resolveGitDirInfo(cwd);
+            if (!info)
+                return null;
+            // refs 存放在共享目录（worktree 与主仓库共用），已实测
+            const headRefPath = path.join(info.commonDir, 'refs', 'remotes', remoteName, 'HEAD');
+            if (!fs.existsSync(headRefPath))
+                return null;
+            const raw = fs.readFileSync(headRefPath, 'utf8');
+            // 内容形如 `ref: refs/remotes/origin/main`
+            const m = /^\s*ref:\s*refs\/remotes\/[^/]+\/(.+?)\s*$/m.exec(raw);
+            return m ? m[1] : null;
+        }
+        catch {
+            return 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) {
         const targetCwd = cwd || this.resolveWorkspaceCwd();
         try {
-            const gitConfigPath = path.join(targetCwd, '.git', 'config');
-            if (!fs.existsSync(gitConfigPath))
+            const dotGit = path.join(targetCwd, '.git');
+            if (!fs.existsSync(dotGit))
                 return null;
-            const configText = fs.readFileSync(gitConfigPath, 'utf8');
-            const match = configText.match(/github\.com[:/]([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+?)(?:\.git)?(?:\s|\r|\n|$)/i);
-            if (!match)
+            const st = fs.statSync(dotGit);
+            if (st.isDirectory())
+                return { localDir: dotGit, commonDir: dotGit };
+            if (!st.isFile())
                 return null;
-            const owner = match[1];
-            const repoName = match[2];
-            const nameWithOwner = `${owner}/${repoName}`;
-            return {
-                nameWithOwner,
-                name: repoName,
-                owner,
-                defaultBranch: 'main',
-                description: '',
-                isPrivate: false,
-                url: `https://github.com/${nameWithOwner}`,
-            };
+            // worktree/submodule：.git 是文本文件，内容形如 `gitdir: C:/repo/.git/worktrees/wt`
+            const pointer = fs.readFileSync(dotGit, 'utf8');
+            const m = /^\s*gitdir:\s*(.+?)\s*$/m.exec(pointer);
+            if (!m)
+                return null;
+            const gitDirRaw = m[1].replace(/[\\/]+$/, '');
+            const localDir = path.isAbsolute(gitDirRaw) ? path.normalize(gitDirRaw) : path.resolve(targetCwd, gitDirRaw);
+            if (!fs.existsSync(localDir))
+                return null;
+            // worktree：<localDir>/commondir 记录共享仓库目录（相对 localDir）
+            const commonDirFile = path.join(localDir, 'commondir');
+            if (fs.existsSync(commonDirFile)) {
+                try {
+                    const rel = fs.readFileSync(commonDirFile, 'utf8').trim();
+                    if (rel) {
+                        const common = path.resolve(localDir, rel);
+                        if (fs.existsSync(path.join(common, 'config')))
+                            return { localDir, commonDir: common };
+                    }
+                }
+                catch {
+                    // commondir 读失败 → 退回 localDir（至少还能读到局部配置）
+                }
+            }
+            return { localDir, commonDir: localDir };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 解析工作区真实的 git 目录（共享仓库目录）。
+     * 薄封装自 resolveGitDirInfo：读 `config` 的场景（远程指纹）只需要共享目录。
+     */
+    resolveGitDirPath(cwd) {
+        return this.resolveGitDirInfo(cwd)?.commonDir ?? 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) {
+        try {
+            const gitDir = this.resolveGitDirPath(cwd);
+            if (!gitDir)
+                return null;
+            const configPath = path.join(gitDir, 'config');
+            if (!fs.existsSync(configPath))
+                return null;
+            const urls = parseRemoteUrls(fs.readFileSync(configPath, 'utf8'));
+            // 排序后拼接：remote 数量、书写顺序、命名方式都不影响指纹——
+            // 只有「url 集合本身」变化才会改变指纹，这正是「配置变没变」的定义。
+            // 空集合同样参与哈希（得到空串的 SHA-256 前缀），语义是「已读、无 remote」，
+            // 与读取失败的 null 是两回事。
+            const normalized = [...urls].sort().join('\n');
+            return crypto.createHash('sha256').update(normalized, 'utf8').digest('hex').slice(0, 12);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 读取并解析工作区的 git 远程视图（`.git/config` + `HEAD`）。
+     * 内部方法：把「两个路径各读哪个文件」的细节收敛在一处，
+     * 避免各调用点自己拼路径读错 worktree 的文件。
+     */
+    readParsedGitConfig(cwd) {
+        const info = this.resolveGitDirInfo(cwd);
+        if (!info)
+            return null;
+        try {
+            const configPath = path.join(info.commonDir, 'config');
+            if (!fs.existsSync(configPath))
+                return null;
+            const configText = fs.readFileSync(configPath, 'utf8');
+            // HEAD 必须从 localDir 读：worktree 下 commonDir/HEAD 是主工作树的分支名
+            const headPath = path.join(info.localDir, 'HEAD');
+            const headText = fs.existsSync(headPath) ? fs.readFileSync(headPath, 'utf8') : null;
+            return parseGitConfig(configText, headText);
         }
         catch {
             return null;
         }
     }
+    /**
+     * 仅从本地 `.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) {
+        const cfg = this.readParsedGitConfig(cwd);
+        if (!cfg)
+            return null;
+        const layout = classifyRepoLayout(cfg);
+        /**
+         * 按布局分类选目标 remote —— 与 `.git/config` 书写顺序无关。
+         *
+         * github-only  ：完全按 git 规则（branch.<当前分支>.remote → origin → 首个）
+         * github-mixed ：git 选中的不是 GitHub → 在 GitHub remote 中按
+         *                origin 优先 → 名字字典序（pickGithubRemote）
+         * 其余          ：无 GitHub remote，返回 null，不猜测
+         */
+        let target = null;
+        if (layout === 'github-only') {
+            target = resolveRemoteTarget(cfg);
+        }
+        else if (layout === 'github-mixed') {
+            target = pickGithubRemote(cfg);
+        }
+        if (!target)
+            return null;
+        const gh = parseGithubUrl(target.url);
+        if (!gh)
+            return null;
+        const nameWithOwner = `${gh.owner}/${gh.repo}`;
+        return {
+            nameWithOwner,
+            name: gh.repo,
+            owner: gh.owner,
+            // 默认分支：从该 remote 的 HEAD 符号引用推断，读不到才回落 'main'
+            defaultBranch: this.readDefaultBranchFromRef(target.name, cwd) || 'main',
+            description: '',
+            isPrivate: false,
+            url: `https://github.com/${nameWithOwner}`,
+            layout,
+        };
+    }
     /**
      * 获取当前目录（工作区）关联的远程仓库元数据
      * 采用 gh repo view + 本地 git remote 双保险机制，彻底杜绝已配置远程却误判未关联的问题
@@ -875,61 +1509,32 @@ export class GhExecutor {
             return null;
         }
         // 1. 优先尝试由 gh 直接根据当前上下文识别
-        const res = await this.run(['repo', 'view', '--json', 'nameWithOwner,name,owner,defaultBranchRef,description,isPrivate,url,stargazerCount,forkCount'], { cwd: targetCwd, timeoutMs: 10_000 });
+        const res = await this.run(['repo', 'view', '--json', REPO_VIEW_FIELDS], { cwd: targetCwd, timeoutMs: 10_000 });
         if (res.ok && res.data && res.data.nameWithOwner) {
-            const d = res.data;
-            return {
-                nameWithOwner: d.nameWithOwner || '',
-                name: d.name || '',
-                owner: d.owner?.login || '',
-                defaultBranch: d.defaultBranchRef?.name || 'main',
-                description: d.description || '',
-                isPrivate: Boolean(d.isPrivate),
-                url: d.url || `https://github.com/${d.nameWithOwner}`,
-                stargazerCount: typeof d.stargazerCount === 'number' ? d.stargazerCount : 0,
-                forkCount: typeof d.forkCount === 'number' ? d.forkCount : 0,
-            };
+            return mapRepoMetadata(res.data);
         }
-        // 2. 原生文件解析：直接读取本地 .git/config 文件（0 子进程开销、免疫沙箱 EPERM）
-        try {
-            const gitConfigPath = path.join(targetCwd, '.git', 'config');
-            if (fs.existsSync(gitConfigPath)) {
-                const configText = fs.readFileSync(gitConfigPath, 'utf8');
-                const match = configText.match(/github\.com[:/]([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+?)(?:\.git)?(?:\s|\r|\n|$)/i);
-                if (match) {
-                    const owner = match[1];
-                    const repoName = match[2];
-                    const nameWithOwner = `${owner}/${repoName}`;
-                    // 使用精确的 owner/repo 向 gh 获取元数据（显式传参，不依赖无上下文的探测）
-                    const directRes = await this.run(['repo', 'view', nameWithOwner, '--json', 'nameWithOwner,name,owner,defaultBranchRef,description,isPrivate,url,stargazerCount,forkCount'], { cwd: targetCwd, timeoutMs: 10_000 });
-                    if (directRes.ok && directRes.data && directRes.data.nameWithOwner) {
-                        const d = directRes.data;
-                        return {
-                            nameWithOwner: d.nameWithOwner || nameWithOwner,
-                            name: d.name || repoName,
-                            owner: d.owner?.login || owner,
-                            defaultBranch: d.defaultBranchRef?.name || 'main',
-                            description: d.description || '',
-                            isPrivate: Boolean(d.isPrivate),
-                            url: d.url || `https://github.com/${nameWithOwner}`,
-                            stargazerCount: typeof d.stargazerCount === 'number' ? d.stargazerCount : 0,
-                            forkCount: typeof d.forkCount === 'number' ? d.forkCount : 0,
-                        };
-                    }
-                    // 若离线或网络受限，由本地 git remote 配置兜底返回
-                    return {
-                        nameWithOwner,
-                        name: repoName,
-                        owner,
-                        defaultBranch: 'main',
-                        description: '已成功关联本地 Git 远程仓库',
-                        isPrivate: false,
-                        url: `https://github.com/${nameWithOwner}`,
-                    };
-                }
+        // 2. 原生文件解析：走与 getRepoIdentityFromLocal 完全相同的解析器
+        //    （0 子进程开销、免疫沙箱 EPERM）。
+        //    为什么不再自己写一份正则：两处各维护一份必然漂移，且旧正则
+        //    「取第一个 github.com 匹配」在多 remote 布局下会取到上游仓库。
+        const local = this.getRepoIdentityFromLocal(targetCwd);
+        if (local) {
+            const { nameWithOwner } = local;
+            // 使用精确的 owner/repo 向 gh 获取元数据（显式传参，不依赖无上下文的探测）
+            const directRes = await this.run(['repo', 'view', nameWithOwner, '--json', REPO_VIEW_FIELDS], {
+                cwd: targetCwd,
+                timeoutMs: 10_000,
+            });
+            if (directRes.ok && directRes.data && directRes.data.nameWithOwner) {
+                return mapRepoMetadata(directRes.data, nameWithOwner);
             }
+            // 若离线或网络受限，由本地 git remote 配置兜底返回。
+            // 注意：此处不带 isFork / parent / viewerPermission —— 离线无从得知，绝不猜测。
+            return {
+                ...local,
+                description: '已成功关联本地 Git 远程仓库',
+            };
         }
-        catch { }
         return null;
     }
 }