dsh-github-flow 0.5.0 → 0.6.0

package/lib/api/routes-overview.js

@@ -1,7 +1,20 @@
 import { mapLimit, tryReadWorkspaces, findWorkspacePathBySession, findMostRecentWorkspacePath, hasGitDir } from '../workspace.js';
 import { resolveIssueCategories, calculateIssueStats, basenameSafe, sendJson } from './route-helpers.js';
+import { describeDeterministicError } from '../executor/error-classifier.js';
 /** 探测单个工作区时在途的 gh 进程数上限；libuv 线程池默认 4，留出余量给其他请求 */
 const WORKSPACE_PROBE_CONCURRENCY = 3;
+/**
+ * 右侧栏单仓库 PR / Issue 的展示条数上限。
+ *
+ * 为什么从 10 提到 20：加上 `--state all` 后列表里混入了 closed/merged，
+ * 而 `gh pr list` 的排序依据是 **number 降序**（实测 30 条验证：14763、14752、
+ * 14751 …… 严格递减），不是 updatedAt。取 10 条时实测 cli/cli 只剩 5 条非 OPEN，
+ * 用户切到「Merged」可能只有 2-3 条，筛选体验形同虚设。
+ * 多拉 10 条的代价可忽略（同一个 gh 进程，仅 JSON 体积略增），
+ * 但绝不能改成「每个状态各查一次」——那会把 3 个 gh 子进程变成 6~9 个，
+ * 右侧栏首屏本就受 Promise.all 8 秒超时约束。
+ */
+const RIGHTBAR_LIST_LIMIT = 20;
 export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, checker) {
     const { bindRoute } = deps;
     // 1. 获取全局与当前仓库的 GitHub 概览
@@ -29,6 +42,19 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                     cwd = process.cwd();
                 }
                 const now = Date.now();
+                // 先行检查当前工作区是否真实包含 .git，无 .git 铁证判定为未关联仓库
+                const isGitRepo = hasGitDir(cwd);
+                // 缓存失效判定：比对 remote 配置指纹，而不是比对解析出的仓库身份。
+                //
+                // 为什么换：身份比对把「解析器的正确性」变成了「缓存有效性的前置条件」。
+                // 多 remote 布局下（如 upstream 段写在 origin 段之前），取「第一个
+                // github.com 匹配」会拿到上游仓库，与缓存里的 fork 身份恒失配，于是
+                // 每次请求都作废缓存、重拉 6 个 gh 子进程。指纹只回答「配置变没变」，
+                // 不依赖任何语义理解，对该类偏差免疫。
+                //
+                // 指纹读取是纯本地 readFileSync（几 KB），与 hasGitDir 同级开销，零子进程。
+                const remoteFingerprint = isGitRepo ? executor.getRemoteFingerprint(cwd) : null;
+                cacheMap.invalidateIfFingerprintChanged(cwd, remoteFingerprint);
                 const cachedData = cacheMap.get(cwd, now);
                 if (cachedData && !force) {
                     sendJson(res, 200, {
@@ -40,9 +66,12 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                     return;
                 }
                 const auth = await executor.checkAuth(cwd);
-                // 先行检查当前工作区是否真实包含 .git，无 .git 铁证判定为未关联仓库
-                const isGitRepo = hasGitDir(cwd);
                 const repo = isGitRepo ? await executor.getRepoMetadata(cwd) : null;
+                if (repo) {
+                    // 推导当前工作区可用的关联仓库（如 origin/Fork 与 upstream/Parent），
+                    // 仅在存在多个关联仓库或 Fork 场景下供 UI 渲染手动切换控件。
+                    repo.associatedRepos = executor.getAssociatedRepos(cwd, repo, auth?.user);
+                }
                 // 若当前工作区未关联 Git 仓库，直接返回纯净空状态，坚决不拉取远端数据
                 if (!isGitRepo || !repo) {
                     const emptyData = {
@@ -55,35 +84,72 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                         lastUpdated: new Date().toISOString(),
                         updateInfo: checker.getQuickStatus(),
                     };
-                    cacheMap.set(cwd, emptyData, now);
+                    cacheMap.set(cwd, emptyData, now, remoteFingerprint);
                     sendJson(res, 200, { ok: true, data: emptyData, fromCache: false, cwd });
                     return;
                 }
                 let pullRequests = [];
                 let issues = [];
                 let runs = [];
+                // 确定性降级说明（非错误）：在 if 块内累积、在块外随响应一起落缓存，
+                // 因此必须在请求作用域声明，不能藏在分支里。
+                const deterministicNotices = [];
                 // 面板增强信息载体（git 状态/Release 锚定/分支 PR——全部可选字段，
                 // 进缓存与快照时旧消费方零破坏，渲染层 ?. 兜底）
                 const freshExtras = {};
                 if (repo && auth.loggedIn) {
-                    // 并发拉取当前文件夹仓库的 PRs、Issues 和 Runs
+                    /*
+                     * 并发拉取当前文件夹仓库的 PRs、Issues 和 Runs。
+                     *
+                     * 必须显式传 `--state all`：gh 的默认值是 open，不传就只剩未关闭记录。
+                     * 本仓库实测 `pr list` 默认返回 []、`--state all` 才返回 [#6 CLOSED]——
+                     * 右侧栏「只显示已打开」的根因就在这里，靠前端加筛选器救不回来，
+                     * 因为数据在到达浏览器前就被 gh 过滤掉了。
+                     * 与全局面板（gh search，phase29 已移除 --state=open）保持同一口径。
+                     */
                     const [prsRes, issuesRes, runsRes] = await Promise.all([
-                        executor.run(['pr', 'list', '--json', 'number,title,state,author,headRefName,baseRefName,isDraft,mergeable,reviewDecision,statusCheckRollup,url,updatedAt', '-L', '10'], { cwd, timeoutMs: 8_000 }),
-                        executor.run(['issue', 'list', '--json', 'number,title,state,author,labels,assignees,url,updatedAt', '-L', '10'], { cwd, timeoutMs: 8_000 }),
+                        executor.run([
+                            'pr', 'list', '--state', 'all',
+                            '--json', 'number,title,state,author,headRefName,baseRefName,isDraft,mergeable,reviewDecision,statusCheckRollup,url,updatedAt',
+                            '-L', String(RIGHTBAR_LIST_LIMIT),
+                        ], { cwd, timeoutMs: 8_000 }),
+                        executor.run([
+                            'issue', 'list', '--state', 'all',
+                            '--json', 'number,title,state,author,labels,assignees,url,updatedAt',
+                            '-L', String(RIGHTBAR_LIST_LIMIT),
+                        ], { cwd, timeoutMs: 8_000 }),
                         executor.run(['run', 'list', '--json', 'databaseId,name,status,conclusion,event,headBranch,url,createdAt', '-L', '5'], { cwd, timeoutMs: 8_000 }),
                     ]);
-                    // 核心数据拉取故障检测：若拉取核心业务数据遭遇失败（网络超时/断网/接口报错），
-                    // 绝对不能把失败伪装成「0 个 PR、0 个 Issue」并假装成功返回！
-                    const failures = [];
-                    if (!prsRes.ok)
-                        failures.push(`PR 获取失败: ${prsRes.error || '网络或接口异常'}`);
-                    if (!issuesRes.ok)
-                        failures.push(`Issue 获取失败: ${issuesRes.error || '网络或接口异常'}`);
-                    if (!runsRes.ok)
-                        failures.push(`Actions 获取失败: ${runsRes.error || '网络或接口异常'}`);
-                    if (failures.length > 0) {
-                        const failureReason = failures.join('；');
-                        // 若此前内存有缓存，保全已有缓存内容，附加 networkError 与 partialFailure
+                    // 核心数据拉取故障检测：把失败按语义拆成两堆。
+                    //
+                    // 为什么必须拆：`gh` 对所有失败都返回非零退出，但两类失败的性质完全不同——
+                    // · 确定性（仓库关了 Issues / 仓库不存在 / 无权限）：重试一万次也还是失败，
+                    //   正确处置是「该字段降级为空列表 + 一句说明」，绝不能伪装成网络故障；
+                    // · 传输层（超时 / 断连 / 代理阻断）：值得回退历史快照并允许重试。
+                    // 旧实现把两者混为一谈，导致「仓库关了 Issues」弹出「网络连接失败」横幅，
+                    // 还被客户端重试器当成可恢复抖动反复空烧。
+                    const transientFailures = [];
+                    const collectFailure = (res, label) => {
+                        if (res.ok)
+                            return;
+                        const msg = res.error || '接口异常';
+                        // errorKind 由 GhExecutor 统一分类（单一事实源），这里只做分流
+                        if (res.errorKind === 'deterministic') {
+                            deterministicNotices.push(`${label}: ${describeDeterministicError(msg) || msg}`);
+                        }
+                        else {
+                            transientFailures.push(`${label}: ${msg}`);
+                        }
+                    };
+                    collectFailure(prsRes, 'PR 获取失败');
+                    collectFailure(issuesRes, 'Issue 获取失败');
+                    collectFailure(runsRes, 'Actions 获取失败');
+                    if (transientFailures.length > 0) {
+                        const failureReason = transientFailures.join('；');
+                        // 若此前内存有缓存，保全已有缓存内容，附加 networkError 与 partialFailure。
+                        // repo 必须用本次新鲜解析值覆盖：列表数据旧一点可以接受，仓库身份旧了就是错的
+                        // （典型场景：用户把 origin 从上游换成自己的 fork 后，issue list 永久失败，
+                        //  失败分支从不写缓存，旧身份被 freeze 在 fallback 里永远出不来）。
                         const fallbackCached = cacheMap.getFallback(cwd) || cacheMap.get(cwd, now);
                         if (fallbackCached && (fallbackCached.pullRequests.length > 0 || fallbackCached.issues.length > 0 || fallbackCached.runs.length > 0)) {
                             sendJson(res, 200, {
@@ -93,6 +159,7 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                                 error: failureReason,
                                 data: {
                                     ...fallbackCached,
+                                    repo: repo || fallbackCached.repo,
                                     networkError: true,
                                     networkErrorReason: failureReason,
                                     auth: { ...fallbackCached.auth, networkError: true, networkErrorReason: failureReason },
@@ -165,6 +232,13 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                     freshExtras.branches = await executor.getGitBranches(cwd).catch(() => null);
                 }
                 const issueStats = calculateIssueStats(issues);
+                /*
+                 * 截断必须可感知：`--state all` + 固定条数上限意味着历史记录可能被截掉，
+                 * 若不透出，用户切到「Closed」看到 3 条会以为仓库只有 3 个已关闭 PR。
+                 * 与全局面板 prsTruncated 同一口径。
+                 */
+                const prsTruncated = pullRequests.length >= RIGHTBAR_LIST_LIMIT;
+                const issuesTruncated = issues.length >= RIGHTBAR_LIST_LIMIT;
                 const freshData = {
                     auth,
                     repo: repo || undefined,
@@ -174,9 +248,15 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                     runs,
                     lastUpdated: new Date().toISOString(),
                     updateInfo: checker.getQuickStatus(),
+                    // 确定性降级说明随数据一起落缓存：它是仓库的稳定属性（Issues 关着就一直关着），
+                    // 每次请求重新声明没有意义，也不该让它冒泡成 networkError。
+                    ...(deterministicNotices.length > 0 ? { notices: deterministicNotices } : {}),
+                    // 仅在真的触顶时才下发，避免给正常场景增加无意义字段
+                    ...(prsTruncated ? { prsTruncated: true } : {}),
+                    ...(issuesTruncated ? { issuesTruncated: true } : {}),
                     ...freshExtras,
                 };
-                cacheMap.set(cwd, freshData, now);
+                cacheMap.set(cwd, freshData, now, remoteFingerprint);
                 sendJson(res, 200, { ok: true, data: freshData, fromCache: false, cwd });
             }
             catch (err) {
@@ -213,6 +293,10 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                 let issueStats = { total: 0, reported: 0, assigned: 0, created: 0 };
                 let workspaceMatrix = [];
                 let workspaceError;
+                /** PR 检索是否触及 limit（命中即说明可能还有更早的 PR 未返回） */
+                let prsTruncated = false;
+                // 全局驾驶舱的确定性降级说明（同单仓库口径：在分支内累积、块外落缓存）
+                const globalNotices = [];
                 if (auth.loggedIn) {
                     // 并发执行：1. 账号下仓库列表 2. 个人 PRs 3. 三维 Issue 检索（名下仓库用户提单 + 指派待办 + 我创建的）
                     // 为什么三路并发搜索：
@@ -220,25 +304,47 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                     // - --assignee=@me: 捕获团队成员或自己指派给当前账号的待办任务 (含跨组织/第三方项目)
                     // - --author=@me: 捕获当前账号亲自发起的任务与向外部提起的议题
                     // 3 个轻量进程与 repo/prs 同步 spawn，经 OS 并发调度实测仅耗时 3 秒出头，完全满足 8 秒超时门限。
-                    const issueFields = 'number,title,repository,author,assignees,labels,url,updatedAt';
+                    // 为什么不再限定 --state=open：
+                    // 实测当前账号 7 个 PR 全为 merged/closed、5 个 Issue 全为 closed，
+                    // `--state=open` 恒返回空数组（退出码仍为 0，属于"正确但无用"）。
+                    // 用户看到的就是一片空白，且无法区分「确实没有」与「请求失败」。
+                    // 改为拉全量并在前端做状态筛选：数据先可见，再谈收敛。
+                    // 同时 --json 必须补上 state 字段——不下发的话前端根本无从筛选。
+                    const issueFields = 'number,title,state,repository,author,assignees,labels,url,updatedAt';
+                    /**
+                     * PR 检索上限。提到常量是因为「命中 limit」这个事实要被下游用来判断截断，
+                     * 散落的字面量会让两处逻辑（查询与判断）出现漂移。
+                     */
+                    const PR_SEARCH_LIMIT = 30;
                     const queryResults = await Promise.allSettled([
                         executor.run(['repo', 'list', '--limit', '20', '--json', 'name,nameWithOwner,description,defaultBranchRef,isPrivate,stargazerCount,updatedAt,url'], { timeoutMs: 8_000 }),
-                        executor.run(['search', 'prs', '--author=@me', '--state=open', '--limit', '10', '--json', 'number,title,repository,url,updatedAt,isDraft'], { timeoutMs: 8_000 }),
-                        executor.run(['search', 'issues', '--owner=@me', '--state=open', '--sort=updated', '--limit', '15', '--json', issueFields], { timeoutMs: 8_000 }),
-                        executor.run(['search', 'issues', '--assignee=@me', '--state=open', '--sort=updated', '--limit', '15', '--json', issueFields], { timeoutMs: 8_000 }),
-                        executor.run(['search', 'issues', '--author=@me', '--state=open', '--sort=updated', '--limit', '15', '--json', issueFields], { timeoutMs: 8_000 }),
+                        executor.run(['search', 'prs', '--author=@me', '--limit', String(PR_SEARCH_LIMIT), '--json', 'number,title,state,repository,url,updatedAt,isDraft'], { timeoutMs: 8_000 }),
+                        executor.run(['search', 'issues', '--owner=@me', '--sort=updated', '--limit', '25', '--json', issueFields], { timeoutMs: 8_000 }),
+                        executor.run(['search', 'issues', '--assignee=@me', '--sort=updated', '--limit', '25', '--json', issueFields], { timeoutMs: 8_000 }),
+                        executor.run(['search', 'issues', '--author=@me', '--sort=updated', '--limit', '25', '--json', issueFields], { timeoutMs: 8_000 }),
                     ]);
                     const reposRes = queryResults[0].status === 'fulfilled' ? queryResults[0].value : { ok: false };
                     const prsRes = queryResults[1].status === 'fulfilled' ? queryResults[1].value : { ok: false };
                     const ownerIssuesRes = queryResults[2].status === 'fulfilled' ? queryResults[2].value : { ok: false };
                     const assignedIssuesRes = queryResults[3].status === 'fulfilled' ? queryResults[3].value : { ok: false };
                     const authorIssuesRes = queryResults[4].status === 'fulfilled' ? queryResults[4].value : { ok: false };
-                    // 检测全局拉取是否发生网络故障，绝不把网络失败当作「0 仓库、0 PR」伪造成功
+                    // 检测全局拉取是否发生网络故障，绝不把网络失败当作「0 仓库、0 PR」伪造成功。
+                    // 与单仓库概览同一口径：确定性失败（账号级搜索本就不存在确定性场景，
+                    // 但仓库列表拉取可能命中 404/403）不进入网络故障分支，只作为 notice 透出。
                     const globalFailures = [];
-                    if (!reposRes.ok)
-                        globalFailures.push(`仓库列表拉取失败: ${reposRes.error || '网络或接口异常'}`);
-                    if (!prsRes.ok)
-                        globalFailures.push(`个人 PR 拉取失败: ${prsRes.error || '网络或接口异常'}`);
+                    const collectGlobalFailure = (res, label) => {
+                        if (res.ok)
+                            return;
+                        const msg = res.error || '接口异常';
+                        if (res.errorKind === 'deterministic') {
+                            globalNotices.push(`${label}: ${describeDeterministicError(msg) || msg}`);
+                        }
+                        else {
+                            globalFailures.push(`${label}: ${msg}`);
+                        }
+                    };
+                    collectGlobalFailure(reposRes, '仓库列表拉取失败');
+                    collectGlobalFailure(prsRes, '个人 PR 拉取失败');
                     if (globalFailures.length > 0) {
                         const globalNetReason = globalFailures.join('；');
                         const fallbackGlobal = globalCache.getFallback('global') || globalCache.get('global', now);
@@ -272,6 +378,15 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                     }
                     if (prsRes.ok && Array.isArray(prsRes.data)) {
                         myPrs = prsRes.data;
+                        /*
+                         * 命中 limit 说明可能还有更早的 PR 未返回。
+                         * 去掉 --state=open 后列表按 updatedAt 降序返回「最近 30 条」，
+                         * 若账号历史 PR 超过 30 条，界面会静默少显示——
+                         * 用户无从知道「列表到此为止」还是「数据丢了」。
+                         * 必须把截断事实透出到 UI。
+                         */
+                        if (myPrs.length >= PR_SEARCH_LIMIT)
+                            prsTruncated = true;
                     }
                     // 多源 Issues 聚合、按 URL 唯一去重并排序
                     const issueMap = new Map();
@@ -343,6 +458,9 @@ export function registerOverviewRoutes(deps, executor, cacheMap, globalCache, ch
                     lastUpdated: new Date().toISOString(),
                     updateInfo: checker.getQuickStatus(),
                     ...(workspaceError ? { workspaceError } : {}),
+                    // 仅在真的触顶时才下发，避免给正常场景增加无意义字段
+                    ...(prsTruncated ? { prsTruncated: true } : {}),
+                    ...(globalNotices.length > 0 ? { notices: globalNotices } : {}),
                 };
                 globalCache.set('global', globalData, now);
                 sendJson(res, 200, { ok: true, data: globalData, fromCache: false });

package/lib/cache.d.ts

@@ -1,8 +1,9 @@
 /**
  * 有上限的 TTL 缓存。
  *
- * 为什么独立成模块：缓存语义（过期、LRU 腾退、容量上限）是缺陷高发区，但嵌在路由文件里
- * 就无法单测——import 一个已执行过的路由模块拿不到干净实例。独立出来才能覆盖边界。
+ * 为什么独立成模块：缓存语义（过期、LRU 腾退、容量上限、身份失效）是缺陷高发区，
+ * 但嵌在路由文件里就无法单测——import 一个已执行过的路由模块拿不到干净实例。
+ * 独立出来才能覆盖边界。
  */
 export declare class TtlCache<T> {
     private ttlMs;
@@ -10,6 +11,16 @@ export declare class TtlCache<T> {
     private store;
     /** 容灾备份底座：记录最后一次成功的有效快照，不受 TTL 过期或主动 refresh 清空的影响 */
     private fallbackStore;
+    /**
+     * 每个 key 对应的 remote 配置指纹。
+     *
+     * 为什么独立于 store 而不是塞进 value：store 的 value 是业务数据 T，
+     * 混入簿记字段会污染 T 的类型、序列化与消费方断言。指纹是缓存层自己的
+     * 记账信息，不参与业务读取。
+     *
+     * 缺失（Map 中无该 key）= 调用方未提供指纹，此时永不作废（保守）。
+     */
+    private fingerprintStore;
     /**
      * @param ttlMs 命中有效期；由面向用户的 cacheTtlMs 配置驱动
      * @param maxEntries 容量上限。键通常是工作区路径，一次会话就可能引入若干键，
@@ -17,9 +28,71 @@ export declare class TtlCache<T> {
      */
     constructor(ttlMs: number, maxEntries?: number);
     get(key: string, now: number): T | undefined;
-    set(key: string, data: T, now: number): void;
+    /**
+     * @param fingerprint 该 key 对应的 remote 配置指纹（可选）。
+     *
+     * 只在传入**非空字符串**时更新指纹；传入 undefined / null 一律保留旧值。
+     *
+     * 为什么 null 不能清除旧指纹：null 的真实含义是「这一次没读到」（config 被
+     * 占用、瞬时 IO 失败、路径暂不可达），不是「这个仓库没有 remote」。若把 null
+     * 当作清除，一次瞬时读取失败就会永久抹掉失效检测能力——之后 remote 真的变了
+     * 也永远发现不了，缓存里冻结的身份再也出不来。保留旧值时的行为是
+     * matchesFingerprint 返回 true（保守不作废），等下一次读到时再正确判定，
+     * 严格优于「永久失明」。
+     */
+    set(key: string, data: T, now: number, fingerprint?: string | null): void;
+    /** 三张表必须同步腾退，否则指纹会随 key 数量慢性增长 */
+    private evict;
     /** 获取最后一次有效成功的容灾底座数据（专供网络故障、超时时的 Fail-Safe 保全） */
     getFallback(key: string): T | undefined;
     get size(): number;
-    clear(): void;
+    /**
+     * 清空缓存。
+     *
+     * @param options.keepFallback 是否保留 fallbackStore 容灾底座，默认 true。
+     *   默认保留是为了「网络抖动时宁可给旧数据也别白屏」；但用户显式点击
+     *   「重试刷新」时要的语义恰恰相反——宁可空白也要重来，此时必须传 false，
+     *   否则刷新动作会被容灾底座架空（这是真实踩到过的死循环：配置文件已变、
+     *   旧快照永久冻结，刷新按钮点了等于没点）。
+     */
+    clear(options?: {
+        keepFallback?: boolean;
+    }): void;
+    /**
+     * remote 配置指纹是否仍与当前事实一致。
+     *
+     * 为什么用指纹取代「身份字符串比对」：身份比对把解析器的正确性变成了缓存
+     * 有效性的前置条件——解析一偏（如双 remote 时取错 remote 段），比对永远
+     * 失配，缓存永久不命中，每次请求都重拉全部 gh 子进程。
+     * 指纹只回答「配置变了没有」，不依赖任何语义理解，因此对该类偏差免疫。
+     *
+     * 判定口径刻意保守：任一侧取不到指纹（离线、非 Git、无 remote）即视为一致。
+     */
+    matchesFingerprint(key: string, currentFingerprint: string | null | undefined): boolean;
+    /**
+     * 仅在指纹失配时作废该 key（含容灾底座）。返回是否真的作废。
+     * 与 matchesFingerprint 分开：判定与处置是两件事，调用点语义更清晰。
+     */
+    invalidateIfFingerprintChanged(key: string, currentFingerprint: string | null | undefined): boolean;
+    /**
+     * 身份校验：缓存里的「仓库身份」是否仍与当前事实一致。
+     *
+     * @deprecated 自 S1 起由 matchesFingerprint 取代，**当前生产代码与测试均无调用点**。
+     *   保留的唯一目的是 S1 的回滚路径：若指纹方案出问题，把 routes-overview
+     *   的两行调用切回身份比对即可，无需恢复已删除的代码。
+     *   计划在 S2（离线解析对齐 git 规则）完成后连同 getRepoIdentityFromLocal 一并删除。
+     *
+     * 为什么必须取代它：该方法依赖 `.git/config` 的解析结果，而解析器在多 remote
+     * 布局下会取错段（实测），导致身份恒失配 → 缓存永久失效。
+     *
+     * @param key 工作区路径
+     * @param currentNameWithOwner 当前从本地 .git/config 解析出的 owner/repo
+     */
+    matchesIdentity(key: string, currentNameWithOwner: string | null | undefined): boolean;
+    /**
+     * 仅在身份失配时作废该键。返回是否真的作废。
+     *
+     * @deprecated 同 matchesIdentity，改用 invalidateIfFingerprintChanged。
+     */
+    invalidateIfIdentityChanged(key: string, currentNameWithOwner: string | null | undefined): boolean;
 }

package/lib/cache.js

@@ -1,8 +1,9 @@
 /**
  * 有上限的 TTL 缓存。
  *
- * 为什么独立成模块：缓存语义（过期、LRU 腾退、容量上限）是缺陷高发区，但嵌在路由文件里
- * 就无法单测——import 一个已执行过的路由模块拿不到干净实例。独立出来才能覆盖边界。
+ * 为什么独立成模块：缓存语义（过期、LRU 腾退、容量上限、身份失效）是缺陷高发区，
+ * 但嵌在路由文件里就无法单测——import 一个已执行过的路由模块拿不到干净实例。
+ * 独立出来才能覆盖边界。
  */
 export class TtlCache {
     ttlMs;
@@ -10,6 +11,16 @@ export class TtlCache {
     store = new Map();
     /** 容灾备份底座：记录最后一次成功的有效快照，不受 TTL 过期或主动 refresh 清空的影响 */
     fallbackStore = new Map();
+    /**
+     * 每个 key 对应的 remote 配置指纹。
+     *
+     * 为什么独立于 store 而不是塞进 value：store 的 value 是业务数据 T，
+     * 混入簿记字段会污染 T 的类型、序列化与消费方断言。指纹是缓存层自己的
+     * 记账信息，不参与业务读取。
+     *
+     * 缺失（Map 中无该 key）= 调用方未提供指纹，此时永不作废（保守）。
+     */
+    fingerprintStore = new Map();
     /**
      * @param ttlMs 命中有效期；由面向用户的 cacheTtlMs 配置驱动
      * @param maxEntries 容量上限。键通常是工作区路径，一次会话就可能引入若干键，
@@ -32,22 +43,43 @@ export class TtlCache {
         this.store.set(key, hit);
         return hit.data;
     }
-    set(key, data, now) {
+    /**
+     * @param fingerprint 该 key 对应的 remote 配置指纹（可选）。
+     *
+     * 只在传入**非空字符串**时更新指纹；传入 undefined / null 一律保留旧值。
+     *
+     * 为什么 null 不能清除旧指纹：null 的真实含义是「这一次没读到」（config 被
+     * 占用、瞬时 IO 失败、路径暂不可达），不是「这个仓库没有 remote」。若把 null
+     * 当作清除，一次瞬时读取失败就会永久抹掉失效检测能力——之后 remote 真的变了
+     * 也永远发现不了，缓存里冻结的身份再也出不来。保留旧值时的行为是
+     * matchesFingerprint 返回 true（保守不作废），等下一次读到时再正确判定，
+     * 严格优于「永久失明」。
+     */
+    set(key, data, now, fingerprint) {
         this.store.set(key, { data, time: now });
         this.fallbackStore.set(key, data);
+        if (typeof fingerprint === 'string' && fingerprint) {
+            this.fingerprintStore.set(key, fingerprint);
+        }
         while (this.store.size > this.maxEntries) {
             const oldest = this.store.keys().next();
             if (oldest.done)
                 break;
-            this.store.delete(oldest.value);
+            this.evict(oldest.value);
         }
         while (this.fallbackStore.size > this.maxEntries) {
             const oldest = this.fallbackStore.keys().next();
             if (oldest.done)
                 break;
-            this.fallbackStore.delete(oldest.value);
+            this.evict(oldest.value);
         }
     }
+    /** 三张表必须同步腾退，否则指纹会随 key 数量慢性增长 */
+    evict(key) {
+        this.store.delete(key);
+        this.fallbackStore.delete(key);
+        this.fingerprintStore.delete(key);
+    }
     /** 获取最后一次有效成功的容灾底座数据（专供网络故障、超时时的 Fail-Safe 保全） */
     getFallback(key) {
         return this.fallbackStore.get(key);
@@ -55,8 +87,83 @@ export class TtlCache {
     get size() {
         return this.store.size;
     }
-    clear() {
-        // 清空活动缓存以迫使后续请求重新发起网络拉取，但保留 fallbackStore 用于网络故障容灾
+    /**
+     * 清空缓存。
+     *
+     * @param options.keepFallback 是否保留 fallbackStore 容灾底座，默认 true。
+     *   默认保留是为了「网络抖动时宁可给旧数据也别白屏」；但用户显式点击
+     *   「重试刷新」时要的语义恰恰相反——宁可空白也要重来，此时必须传 false，
+     *   否则刷新动作会被容灾底座架空（这是真实踩到过的死循环：配置文件已变、
+     *   旧快照永久冻结，刷新按钮点了等于没点）。
+     */
+    clear(options = {}) {
         this.store.clear();
+        if (options.keepFallback === false) {
+            this.fallbackStore.clear();
+            this.fingerprintStore.clear();
+        }
+    }
+    /**
+     * remote 配置指纹是否仍与当前事实一致。
+     *
+     * 为什么用指纹取代「身份字符串比对」：身份比对把解析器的正确性变成了缓存
+     * 有效性的前置条件——解析一偏（如双 remote 时取错 remote 段），比对永远
+     * 失配，缓存永久不命中，每次请求都重拉全部 gh 子进程。
+     * 指纹只回答「配置变了没有」，不依赖任何语义理解，因此对该类偏差免疫。
+     *
+     * 判定口径刻意保守：任一侧取不到指纹（离线、非 Git、无 remote）即视为一致。
+     */
+    matchesFingerprint(key, currentFingerprint) {
+        const stored = this.fingerprintStore.get(key);
+        if (!stored || !currentFingerprint)
+            return true;
+        return stored === currentFingerprint;
+    }
+    /**
+     * 仅在指纹失配时作废该 key（含容灾底座）。返回是否真的作废。
+     * 与 matchesFingerprint 分开：判定与处置是两件事，调用点语义更清晰。
+     */
+    invalidateIfFingerprintChanged(key, currentFingerprint) {
+        if (this.matchesFingerprint(key, currentFingerprint))
+            return false;
+        this.evict(key);
+        return true;
+    }
+    /**
+     * 身份校验：缓存里的「仓库身份」是否仍与当前事实一致。
+     *
+     * @deprecated 自 S1 起由 matchesFingerprint 取代，**当前生产代码与测试均无调用点**。
+     *   保留的唯一目的是 S1 的回滚路径：若指纹方案出问题，把 routes-overview
+     *   的两行调用切回身份比对即可，无需恢复已删除的代码。
+     *   计划在 S2（离线解析对齐 git 规则）完成后连同 getRepoIdentityFromLocal 一并删除。
+     *
+     * 为什么必须取代它：该方法依赖 `.git/config` 的解析结果，而解析器在多 remote
+     * 布局下会取错段（实测），导致身份恒失配 → 缓存永久失效。
+     *
+     * @param key 工作区路径
+     * @param currentNameWithOwner 当前从本地 .git/config 解析出的 owner/repo
+     */
+    matchesIdentity(key, currentNameWithOwner) {
+        if (!currentNameWithOwner)
+            return true;
+        const cached = this.fallbackStore.get(key) ?? this.store.get(key)?.data;
+        if (!cached)
+            return true;
+        const cachedRepo = cached?.repo;
+        const cachedName = typeof cachedRepo?.nameWithOwner === 'string' ? cachedRepo.nameWithOwner : '';
+        if (!cachedName)
+            return true;
+        return cachedName.toLowerCase() === currentNameWithOwner.toLowerCase();
+    }
+    /**
+     * 仅在身份失配时作废该键。返回是否真的作废。
+     *
+     * @deprecated 同 matchesIdentity，改用 invalidateIfFingerprintChanged。
+     */
+    invalidateIfIdentityChanged(key, currentNameWithOwner) {
+        if (this.matchesIdentity(key, currentNameWithOwner))
+            return false;
+        this.evict(key);
+        return true;
     }
 }

package/lib/client.d.ts

@@ -11,14 +11,18 @@ declare global {
 import { formatRelativeTime, rollupCiStatus, reviewDecisionBadge, eventLabel, parseGitStatText } from './ui/utils.js';
 import { GITHUB_PANEL_CSS, injectStyles } from './ui/styles.js';
 import { renderOctocat, renderGitIcon, renderOctocatBadge, renderPluginBadge } from './ui/icons.js';
-import { getLocalSyncSettings, saveLocalSyncSettings, getStoredGlobalOverview, saveStoredGlobalOverview, clearStoredGlobalOverview, getCacheStorageMeta, getRightbarStorageKey, getStoredRightbarSnapshot, saveStoredRightbarData, getStoredHeaderCardsVisible, saveStoredHeaderCardsVisible, HEADER_CARDS_STORAGE_KEY } from './ui/storage.js';
+import { getLocalSyncSettings, saveLocalSyncSettings, getStoredGlobalOverview, saveStoredGlobalOverview, clearStoredGlobalOverview, getCacheStorageMeta, getRightbarStorageKey, getStoredRightbarSnapshot, saveStoredRightbarData, getStoredHeaderCardsVisible, saveStoredHeaderCardsVisible, HEADER_CARDS_STORAGE_KEY, getStoredRightbarStateFilter, saveStoredRightbarStateFilter, PR_STATE_FILTERS, ISSUE_STATE_FILTERS } from './ui/storage.js';
 import { BranchSelectorDropdown } from './ui/branch-selector.js';
+import { RepoSelectorDropdown } from './ui/repo-selector.js';
 import { AuthGuideCard } from './ui/auth-guide-card.js';
 import { UpgradeNotificationCard } from './ui/upgrade-card.js';
-import { NetworkAlertBanner } from './ui/network-banner.js';
+import { NetworkAlertBanner, RepoNoticeBar } from './ui/network-banner.js';
+import { resolveRepoBadges } from './ui/repo-badges.js';
 import { SyncStatusBadge } from './ui/sync-status-badge.js';
 import { CommitDetailModal } from './ui/commit-modal.js';
+import { PrDetailModal } from './ui/pr-modal.js';
+import { IssueDetailModal } from './ui/issue-modal.js';
 import { GlobalSyncSettingsModal } from './ui/sync-settings-modal.js';
 import { GithubHelpModal } from './ui/help-modal.js';
 import { GithubWorkspacePanel } from './ui/workspace-panel.js';
-export { formatRelativeTime, rollupCiStatus, reviewDecisionBadge, eventLabel, parseGitStatText, GITHUB_PANEL_CSS, injectStyles, renderOctocat, renderGitIcon, renderOctocatBadge, renderPluginBadge, getLocalSyncSettings, saveLocalSyncSettings, getStoredGlobalOverview, saveStoredGlobalOverview, clearStoredGlobalOverview, getCacheStorageMeta, getRightbarStorageKey, getStoredRightbarSnapshot, saveStoredRightbarData, getStoredHeaderCardsVisible, saveStoredHeaderCardsVisible, HEADER_CARDS_STORAGE_KEY, BranchSelectorDropdown, AuthGuideCard, UpgradeNotificationCard, NetworkAlertBanner, SyncStatusBadge, CommitDetailModal, GlobalSyncSettingsModal, GithubHelpModal, GithubWorkspacePanel, };
+export { formatRelativeTime, rollupCiStatus, reviewDecisionBadge, eventLabel, parseGitStatText, GITHUB_PANEL_CSS, injectStyles, renderOctocat, renderGitIcon, renderOctocatBadge, renderPluginBadge, getLocalSyncSettings, saveLocalSyncSettings, getStoredGlobalOverview, saveStoredGlobalOverview, clearStoredGlobalOverview, getCacheStorageMeta, getRightbarStorageKey, getStoredRightbarSnapshot, saveStoredRightbarData, getStoredHeaderCardsVisible, saveStoredHeaderCardsVisible, HEADER_CARDS_STORAGE_KEY, getStoredRightbarStateFilter, saveStoredRightbarStateFilter, PR_STATE_FILTERS, ISSUE_STATE_FILTERS, BranchSelectorDropdown, RepoSelectorDropdown, AuthGuideCard, UpgradeNotificationCard, NetworkAlertBanner, RepoNoticeBar, resolveRepoBadges, SyncStatusBadge, CommitDetailModal, PrDetailModal, IssueDetailModal, GlobalSyncSettingsModal, GithubHelpModal, GithubWorkspacePanel, };