dsh-github-flow 0.2.1 → 0.3.0

package/lib/executor.d.ts

@@ -1,5 +1,36 @@
-import type { GhExecutionOptions, GhResult, AuthStatus, RepoMetadata, PluginConfig } from './types.js';
+import type { GhExecutionOptions, GhResult, AuthStatus, RepoMetadata, PluginConfig, GitLocalStatus, GitCommitLog, GitCommitEntry } from './types.js';
 import type { ProxyManager } from './proxy.js';
+/**
+ * 从 `gh --version` 输出中解析语义化版本号。
+ * 抽成导出纯函数的原因与 truncateOutput 相同：解析逻辑是「看似简单实则易错」的边界区，
+ * 必须能用单元测试钉死（不匹配输入返回 null 而非抛错，调用方据此走 fail-open）。
+ */
+export declare function parseGhVersion(output: string): string | null;
+/**
+ * 数值分段比较两个 gh 版本：a>b 返回 1、a<b 返回 -1、相等返回 0。
+ * 为什么不能用字符串比较：`'2.96.0' < '2.100.0'` 在字典序下为 false（'1'<'9'），
+ * 这会把 2.100 误判为低于 2.96，导致可用命令被错误降级。逐段 Number 比较是唯一正确姿势。
+ */
+export declare function compareGhVersions(a: string, b: string): number;
+/**
+ * 解析 `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 declare function parseGitStatusOutput(output: string): GitLocalStatus | null;
+/**
+ * 解析 `git log` 输出为提交条目数组。
+ * 支持两种形态：
+ * 1. 结构化带详情：%x1e 为 commit 间分隔符，%x1f 为字段间分隔符（含 fullSha/email/date/body/stat）；
+ * 2. 简易管道符：%h|%an|%ar|%s 行格式（兼容旧单测输入）。
+ * 空输出返回 []。
+ */
+export declare function parseGitLogLines(output: string): GitCommitEntry[];
 /**
  * 按「字符数 + UTF-8 字节数」双口径截断输出。
  * 抽成纯函数是刻意的：截断逻辑是崩溃高发区（切碎多字节字符、误伤 JSON、把二进制流截成垃圾），
@@ -22,6 +53,12 @@ export declare class GhExecutor {
      * 且热更新路径 updateConfig 能同步刷新。工具内以 `?? 20` 兜底保证旧配置兼容。
      */
     defaultListLimit: number;
+    /**
+     * 是否注入 AI_AGENT='dsh'（gh 官方 agent 识别信号，默认 true）。
+     * 挂在 executor 而非工具参数：注入点是「每次 gh 子进程拉起」这一全局咽喉，
+     * 与 GH_NO_UPDATE_NOTIFIER/NO_COLOR 同级，语义上属于执行层默认值。
+     */
+    agentEnvInjection: boolean;
     /**
      * 代理管理器引用（可选依赖）。
      * 注入后每次 gh 子进程拉起都会合并代理环境变量——这是「工具调用 + Web 页面数据
@@ -31,6 +68,11 @@ export declare class GhExecutor {
     private proxyManager?;
     /** 认证状态缓存。`gh auth status` 实测 5.4 秒，而它位于全局驾驶舱关键路径的最前面 */
     private authCache;
+    /**
+     * gh 版本号缓存。只缓存成功解析值（authCache 哲学：不确定结果不缓存）——
+     * 探测失败/未安装时不落缓存，用户装好 gh 后下一次探测立即生效。
+     */
+    private ghVersionCache;
     constructor(config?: PluginConfig);
     updateConfig(config?: PluginConfig): void;
     /** 注入代理管理器（main.ts 装配时调用一次；测试可注入 mock） */
@@ -57,6 +99,81 @@ export declare class GhExecutor {
      *   而 Web 面板每次挂载都会来问一次，重复执行实测要 5.4 秒，属于纯浪费。
      */
     checkAuth(cwd?: string, bypassCache?: boolean): Promise<AuthStatus>;
+    /**
+     * 获取当前 gh 版本号（带 30s TTL 缓存），失败返回 null。
+     * 底层直连 execFileAsync 而不走 this.run()：run() 会先解析工作区（可能读
+     * workspace.json 与目录扫描）再做截断/JSON 解析，对一次 10ms 的版本字符串
+     * 查询是纯开销；直连也彻底规避 runGuarded → 探测 → run 的递归风险。
+     */
+    getGhVersion(): Promise<string | null>;
+    /**
+     * 底层版本探测（独立方法而非内联：测试需要在不触发真实子进程的前提下
+     * 验证 getGhVersion 的缓存分支——覆写此方法即注入确定输出）。
+     * 直连 execFileAsync 而不走 this.run()：run() 会先解析工作区（可能读
+     * workspace.json 与目录扫描）再做截断/JSON 解析，对一次 10ms 的版本字符串
+     * 查询是纯开销；直连也彻底规避 runGuarded → 探测 → run 的递归风险。
+     */
+    protected probeGhVersionRaw(): Promise<string>;
+    /**
+     * 守卫执行器：按 gh 版本门槛路由「主命令 → 降级链路 → 升级指引」三态。
+     *
+     * 为什么是「检查+执行」一体的方法而非纯探测接口：检查与执行分离会在两者之间
+     * 留下竞隙（版本可能在间隙变化），且降级标注逻辑会被迫散落到每个工具的 if/else。
+     *
+     * fail-open 纪律：版本探测自身失败（null）时直接执行主命令——守卫是路由优化
+     * 不是安全边界，探测故障不应拦截业务；gh 未安装场景由主命令产出既有 ENOENT
+     * 安装引导，这里不重复造错误路径。
+     */
+    runGuarded<T = unknown>(args: string[], options?: GhExecutionOptions & {
+        /** 该能力要求的最低 gh 版本，如 '2.95.0'；缺省时等价于直接 run（渐进采用） */
+        minVersion?: string;
+        /** 人类可读能力名，用于错误信息，如 'gh repo read-file' */
+        capability?: string;
+        /** 版本不足时的降级链路（如 github_api contents 端点封装）；无则报错带升级指引 */
+        fallback?: () => Promise<GhResult<T>>;
+    }): Promise<GhResult<T> & {
+        degraded?: boolean;
+        degradedReason?: string;
+    }>;
+    /** gh 升级命令按平台提示（复用三态状态机的平台判断口径） */
+    private getGhUpgradeHint;
+    /**
+     * 本地 Git 状态只读探测（白名单通道）。
+     *
+     * 这是本插件首次执行 git（此前仅 gh）——git 存在大量写命令，风险等级高于 gh，
+     * 因此白名单不落在「命令名过滤」而落在「命令形态常量」：spawn 参数是下方
+     * 硬编码的数组字面量，无任何动态拼接路径，写操作物理不可达（cwd 之外零输入，
+     * 而 cwd 本身也是插件解析的工作区路径）。
+     *
+     * 零网络：status 基于 remote-tracking ref（上次 fetch 的快照），毫秒级本地读取，
+     * 符合 global-overview 端点「工作区探测不发网络」的性能红线。
+     */
+    getLocalGitStatus(cwd?: string): Promise<GitLocalStatus | null>;
+    /**
+     * 本地 Git 提交记录（三段一次返回：本地领先 / 远程领先 / 最近提交）。
+     *
+     * 白名单纪律与 getLocalGitStatus 同源：下方两个命令形态常量硬编码
+     * （log + 修订范围语法，range 段由 hasUpstream 守卫后才拼接且仅两个
+     * 固定形态 @{u}..HEAD / HEAD..@{u}——不含任何用户输入路径）。
+     * 领先/落后列表基于 remote-tracking ref（上次 fetch 快照），与 status
+     * 的 ahead/behind 计数同一数据口径；格式 %h|%an|%ar|%s 实测可结构化解析。
+     */
+    getGitCommitLog(cwd?: string, hasUpstream?: boolean, limit?: number): Promise<GitCommitLog | null>;
+    /**
+     * 分页获取最近提交记录（用于 Git 面板下滑触底继续加载）。
+     */
+    getGitRecentLog(cwd?: string, limit?: number, skip?: number): Promise<{
+        commits: GitCommitEntry[];
+        totalCount?: number;
+    }>;
+    /**
+     * 单条提交详情（点击提交行弹窗的数据源）。
+     * 白名单纪律延续：show 命令形态常量硬编码；sha 参数经 ^[0-9a-f]{4,40}$
+     * 十六进制校验后才拼接——这是 git 白名单通道首次接受「外部传入的单值」，
+     * 正则把值域锁死在纯十六进制（注入面为零：任何 shell 元字符/子命令
+     * 语法都不可能通过校验）。输出为 git show --stat 原文（含文件变更统计）。
+     */
+    getGitCommitDetail(cwd: string | undefined, sha: string): Promise<string | null>;
     /** 生成当前操作系统平台的推荐安装引导与命令 */
     private getPlatformInstallGuide;
     /** 实际执行 `gh auth status` 并解析结果，不含缓存逻辑 */

package/lib/executor.js

@@ -84,6 +84,130 @@ function spawnWithStdin(ghPath, args, opts) {
 }
 /** 认证状态缓存时长。用户手动 `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 按字节缓冲区
@@ -180,6 +304,12 @@ export class GhExecutor {
      * 且热更新路径 updateConfig 能同步刷新。工具内以 `?? 20` 兜底保证旧配置兼容。
      */
     defaultListLimit;
+    /**
+     * 是否注入 AI_AGENT='dsh'（gh 官方 agent 识别信号，默认 true）。
+     * 挂在 executor 而非工具参数：注入点是「每次 gh 子进程拉起」这一全局咽喉，
+     * 与 GH_NO_UPDATE_NOTIFIER/NO_COLOR 同级，语义上属于执行层默认值。
+     */
+    agentEnvInjection;
     /**
      * 代理管理器引用（可选依赖）。
      * 注入后每次 gh 子进程拉起都会合并代理环境变量——这是「工具调用 + Web 页面数据
@@ -189,12 +319,18 @@ export class GhExecutor {
     proxyManager;
     /** 认证状态缓存。`gh auth status` 实测 5.4 秒，而它位于全局驾驶舱关键路径的最前面 */
     authCache = null;
+    /**
+     * gh 版本号缓存。只缓存成功解析值（authCache 哲学：不确定结果不缓存）——
+     * 探测失败/未安装时不落缓存，用户装好 gh 后下一次探测立即生效。
+     */
+    ghVersionCache = null;
     constructor(config = {}) {
         this.ghPath = config.ghPath || 'gh';
         this.defaultTimeoutMs = config.defaultTimeoutMs || 30_000;
         this.maxOutputChars = config.maxOutputChars || 24_000;
         this.maxOutputBytes = config.maxOutputBytes || this.maxOutputChars * 4;
         this.defaultListLimit = config.defaultListLimit || 20;
+        this.agentEnvInjection = config.agentEnvInjection !== false;
     }
     updateConfig(config = {}) {
         if (config.ghPath)
@@ -203,6 +339,8 @@ export class GhExecutor {
             this.defaultTimeoutMs = config.defaultTimeoutMs;
         if (config.defaultListLimit)
             this.defaultListLimit = config.defaultListLimit;
+        if (config.agentEnvInjection !== undefined)
+            this.agentEnvInjection = config.agentEnvInjection;
         if (config.maxOutputChars) {
             this.maxOutputChars = config.maxOutputChars;
             if (!config.maxOutputBytes)
@@ -280,6 +418,11 @@ export class GhExecutor {
                     // 代理环境变量注入在 options.env 之前：调用方显式传入的 env 仍可覆盖
                     // 代理（保持 options.env 的既有语义优先级），正常调用方不传则代理生效。
                     ...(this.proxyManager?.getEnv('gh') || {}),
+                    // gh 官方 agent 识别信号（detect.go 最高优先级通用变量）：≥2.99 切 text-only
+                    // spinner、≥2.100 误用时打印完整 help、telemetry 归因到 dsh；<2.99 忽略之。
+                    // 覆盖继承自宿主环境的同名变量——插件比外层环境更清楚自己的直接驱动者是
+                    // DSH（嵌套 agent 场景归因不失真）；options.env 仍可覆盖（与代理变量同语义）。
+                    ...(this.agentEnvInjection ? { AI_AGENT: 'dsh' } : {}),
                     ...options.env,
                 },
             };
@@ -377,6 +520,220 @@ export class GhExecutor {
         }
         return value;
     }
+    /**
+     * 获取当前 gh 版本号（带 30s TTL 缓存），失败返回 null。
+     * 底层直连 execFileAsync 而不走 this.run()：run() 会先解析工作区（可能读
+     * workspace.json 与目录扫描）再做截断/JSON 解析，对一次 10ms 的版本字符串
+     * 查询是纯开销；直连也彻底规避 runGuarded → 探测 → run 的递归风险。
+     */
+    async getGhVersion() {
+        const now = Date.now();
+        if (this.ghVersionCache && now - this.ghVersionCache.at < GH_VERSION_CACHE_TTL_MS) {
+            return this.ghVersionCache.value;
+        }
+        const version = parseGhVersion(await this.probeGhVersionRaw());
+        // 只缓存成功解析值：失败不落缓存，用户装好 gh 后下一次探测立即生效
+        if (version) {
+            this.ghVersionCache = { at: now, value: version };
+        }
+        return version;
+    }
+    /**
+     * 底层版本探测（独立方法而非内联：测试需要在不触发真实子进程的前提下
+     * 验证 getGhVersion 的缓存分支——覆写此方法即注入确定输出）。
+     * 直连 execFileAsync 而不走 this.run()：run() 会先解析工作区（可能读
+     * workspace.json 与目录扫描）再做截断/JSON 解析，对一次 10ms 的版本字符串
+     * 查询是纯开销；直连也彻底规避 runGuarded → 探测 → run 的递归风险。
+     */
+    async probeGhVersionRaw() {
+        try {
+            const { stdout } = await execFileAsync(this.ghPath, ['--version'], {
+                timeout: 3_000,
+                windowsHide: true,
+            });
+            return String(stdout);
+        }
+        catch {
+            // 未安装/超时/PATH 抖动：返回空串，由 parseGhVersion 归一为 null → fail-open
+            return '';
+        }
+    }
+    /**
+     * 守卫执行器：按 gh 版本门槛路由「主命令 → 降级链路 → 升级指引」三态。
+     *
+     * 为什么是「检查+执行」一体的方法而非纯探测接口：检查与执行分离会在两者之间
+     * 留下竞隙（版本可能在间隙变化），且降级标注逻辑会被迫散落到每个工具的 if/else。
+     *
+     * fail-open 纪律：版本探测自身失败（null）时直接执行主命令——守卫是路由优化
+     * 不是安全边界，探测故障不应拦截业务；gh 未安装场景由主命令产出既有 ENOENT
+     * 安装引导，这里不重复造错误路径。
+     */
+    async runGuarded(args, options = {}) {
+        const { minVersion, capability, fallback, ...runOptions } = options;
+        if (!minVersion) {
+            return this.run(args, runOptions);
+        }
+        const current = await this.getGhVersion();
+        // 探测失败 fail-open：直接执行主命令（见方法注释），错误路径交由主命令的既有处理
+        if (current === null || compareGhVersions(current, minVersion) >= 0) {
+            return this.run(args, runOptions);
+        }
+        if (fallback) {
+            const res = await fallback();
+            return {
+                ...res,
+                degraded: true,
+                degradedReason: `当前 gh ${current} 低于 ${capability || minVersion} 所需版本 ${minVersion}，已切换 API 降级链路`,
+            };
+        }
+        return {
+            ok: false,
+            error: `此能力需要 gh ≥ ${minVersion}（当前 ${current}）。${this.getGhUpgradeHint()}`,
+        };
+    }
+    /** 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/。';
+    }
+    /**
+     * 本地 Git 状态只读探测（白名单通道）。
+     *
+     * 这是本插件首次执行 git（此前仅 gh）——git 存在大量写命令，风险等级高于 gh，
+     * 因此白名单不落在「命令名过滤」而落在「命令形态常量」：spawn 参数是下方
+     * 硬编码的数组字面量，无任何动态拼接路径，写操作物理不可达（cwd 之外零输入，
+     * 而 cwd 本身也是插件解析的工作区路径）。
+     *
+     * 零网络：status 基于 remote-tracking ref（上次 fetch 的快照），毫秒级本地读取，
+     * 符合 global-overview 端点「工作区探测不发网络」的性能红线。
+     */
+    async getLocalGitStatus(cwd) {
+        try {
+            // 纯本地毫秒级；3s 超时兜底异常文件系统
+            const { stdout } = await execFileAsync('git', ['status', '-sb', '--porcelain'], {
+                cwd: cwd || undefined,
+                timeout: 3_000,
+                windowsHide: true,
+            });
+            return parseGitStatusOutput(String(stdout));
+        }
+        catch {
+            // 非 Git 目录 / git 未安装 / 超时：静默降级为 null（调用方不渲染该行）
+            return null;
+        }
+    }
+    /**
+     * 本地 Git 提交记录（三段一次返回：本地领先 / 远程领先 / 最近提交）。
+     *
+     * 白名单纪律与 getLocalGitStatus 同源：下方两个命令形态常量硬编码
+     * （log + 修订范围语法，range 段由 hasUpstream 守卫后才拼接且仅两个
+     * 固定形态 @{u}..HEAD / HEAD..@{u}——不含任何用户输入路径）。
+     * 领先/落后列表基于 remote-tracking ref（上次 fetch 快照），与 status
+     * 的 ahead/behind 计数同一数据口径；格式 %h|%an|%ar|%s 实测可结构化解析。
+     */
+    async getGitCommitLog(cwd, hasUpstream = true, limit = 15) {
+        const empty = { aheadCommits: [], behindCommits: [], recent: [] };
+        const logFmt = '--pretty=format:%x1e%h%x1f%H%x1f%an%x1f%ae%x1f%ad%x1f%ar%x1f%s%x1f%b%x1f';
+        try {
+            const recentRes = await execFileAsync('git', ['log', `-${Math.max(1, limit)}`, logFmt, '--stat', '--no-decorate'], {
+                cwd: cwd || undefined,
+                timeout: 4_000,
+                windowsHide: true,
+            });
+            empty.recent = parseGitLogLines(String(recentRes.stdout));
+            try {
+                const countRes = await execFileAsync('git', ['rev-list', '--count', 'HEAD'], {
+                    cwd: cwd || undefined,
+                    timeout: 2_000,
+                    windowsHide: true,
+                });
+                const cnt = parseInt(String(countRes.stdout).trim(), 10);
+                if (!isNaN(cnt))
+                    empty.totalCount = cnt;
+            }
+            catch { }
+            if (!hasUpstream)
+                return empty; // 无 upstream：领先/落后无从谈起，仅最近提交
+            const aheadRes = await execFileAsync('git', ['log', '@{u}..HEAD', logFmt, '--stat', '--no-decorate'], {
+                cwd: cwd || undefined,
+                timeout: 3_000,
+                windowsHide: true,
+            });
+            empty.aheadCommits = parseGitLogLines(String(aheadRes.stdout));
+            const behindRes = await execFileAsync('git', ['log', 'HEAD..@{u}', logFmt, '--stat', '--no-decorate'], {
+                cwd: cwd || undefined,
+                timeout: 3_000,
+                windowsHide: true,
+            });
+            empty.behindCommits = parseGitLogLines(String(behindRes.stdout));
+            return empty;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 分页获取最近提交记录（用于 Git 面板下滑触底继续加载）。
+     */
+    async getGitRecentLog(cwd, limit = 15, skip = 0) {
+        const logFmt = '--pretty=format:%x1e%h%x1f%H%x1f%an%x1f%ae%x1f%ad%x1f%ar%x1f%s%x1f%b%x1f';
+        const safeLimit = Math.min(Math.max(1, limit), 50);
+        const safeSkip = Math.max(0, skip);
+        const args = ['log', `-${safeLimit}`, logFmt, '--stat', '--no-decorate'];
+        if (safeSkip > 0) {
+            args.push('--skip', String(safeSkip));
+        }
+        try {
+            const { stdout } = await execFileAsync('git', args, {
+                cwd: cwd || undefined,
+                timeout: 5_000,
+                windowsHide: true,
+            });
+            const commits = parseGitLogLines(String(stdout));
+            let totalCount;
+            try {
+                const countRes = await execFileAsync('git', ['rev-list', '--count', 'HEAD'], {
+                    cwd: cwd || undefined,
+                    timeout: 2_000,
+                    windowsHide: true,
+                });
+                const cnt = parseInt(String(countRes.stdout).trim(), 10);
+                if (!isNaN(cnt))
+                    totalCount = cnt;
+            }
+            catch { }
+            return { commits, totalCount };
+        }
+        catch {
+            return { commits: [] };
+        }
+    }
+    /**
+     * 单条提交详情（点击提交行弹窗的数据源）。
+     * 白名单纪律延续：show 命令形态常量硬编码；sha 参数经 ^[0-9a-f]{4,40}$
+     * 十六进制校验后才拼接——这是 git 白名单通道首次接受「外部传入的单值」，
+     * 正则把值域锁死在纯十六进制（注入面为零：任何 shell 元字符/子命令
+     * 语法都不可能通过校验）。输出为 git show --stat 原文（含文件变更统计）。
+     */
+    async getGitCommitDetail(cwd, sha) {
+        if (!/^[0-9a-f]{4,40}$/i.test(sha))
+            return null; // 形态校验：纯十六进制短/全 sha
+        try {
+            const { stdout } = await execFileAsync('git', ['show', '--stat', '--pretty=format:%H%n%an <%ae>%n%ad%n%s%n%b', sha], {
+                cwd: cwd || undefined,
+                timeout: 3_000,
+                windowsHide: true,
+            });
+            return String(stdout);
+        }
+        catch {
+            return null;
+        }
+    }
     /** 生成当前操作系统平台的推荐安装引导与命令 */
     getPlatformInstallGuide() {
         const p = process.platform;

package/lib/main.js

@@ -45,6 +45,7 @@ export const Config = {
                     cacheTtlMs: typeof cfg.cacheTtlMs === 'number' ? cfg.cacheTtlMs : 15_000,
                     defaultListLimit: typeof cfg.defaultListLimit === 'number' ? cfg.defaultListLimit : 20,
                     checkUpdate: typeof cfg.checkUpdate === 'boolean' ? cfg.checkUpdate : true,
+                    agentEnvInjection: cfg.agentEnvInjection !== false,
                     updateCheckIntervalMs: typeof cfg.updateCheckIntervalMs === 'number' ? cfg.updateCheckIntervalMs : 86_400_000,
                     registryUrl: typeof cfg.registryUrl === 'string' ? cfg.registryUrl : undefined,
                     proxyUrl: typeof cfg.proxyUrl === 'string' ? cfg.proxyUrl : undefined,

package/lib/renderers/markdown.d.ts

@@ -20,6 +20,12 @@ export declare function formatStateBadge(state?: string, isDraft?: boolean): str
 export declare function formatCiBadge(status?: string, conclusion?: string): string;
 /** 格式化合并冲突状态 */
 export declare function formatConflictBadge(status?: string): string;
+/**
+ * 降级链路可见标注（runGuarded 契约的渲染兑现）。
+ * 为什么必须可见：降级若是静默的，Agent 就无法感知能力边界（同一 action 在
+ * 不同 gh 版本上走不同链路）；一条 blockquote 注释成本一行，换链路透明。
+ */
+export declare function appendDegradedNote(value: any): string;
 export declare function renderPrMarkdown(args: any, value: any): string;
 export declare function renderIssueMarkdown(args: any, value: any): string;
 export declare function renderRunMarkdown(args: any, value: any): string;