dsh-github-flow 0.2.0 → 0.3.0

package/lib/executor.js

@@ -1,11 +1,213 @@
-import { execFile } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import fs from 'node:fs';
 import path from 'node:path';
 import { findMostRecentWorkspacePath, findWorkspacePathBySession, hasGitDir } from './workspace.js';
 const execFileAsync = promisify(execFile);
+/**
+ * spawn 形态的执行通道（stdin 可选注入）。
+ *
+ * 为什么存在：execFile 的 input 选项在本机（node 22.18.0 + Windows）实测从不写入
+ * 子进程 stdin——既无数据也无 EOF，管道永久悬空（gh secret set 等需要 stdin 的
+ * 命令会一直等到超时）。最小复现：execFile+input 对 `cmd /c more` 与 node 子进程
+ * 均挂起；而 spawn + stdin.end(data) 全部正常。此函数即为后者的工程化封装，
+ * 仅在调用方显式传入 stdin 时使用，其余路径保持 execFileAsync 零改动。
+ *
+ * 为什么超时要自己管：spawn 无 timeout 选项，用 kill + SIGTERM 兜底；
+ * 输出按 maxBuffer 手工聚合（上限与 execFile 路径一致，15MB）。
+ */
+function spawnWithStdin(ghPath, args, opts) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(ghPath, args, {
+            cwd: opts.cwd,
+            env: opts.env,
+            windowsHide: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const outChunks = [];
+        const errChunks = [];
+        let totalBytes = 0;
+        let killed = false;
+        let settled = false;
+        const timer = setTimeout(() => {
+            killed = true;
+            child.kill();
+        }, opts.timeout);
+        const settle = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (err)
+                reject(err);
+            else
+                resolve({ stdout: Buffer.concat(outChunks), stderr: Buffer.concat(errChunks), killed });
+        };
+        // 聚合上限：超出即杀（与 execFile maxBuffer 语义一致；gh 正常输出远小于此）
+        const MAX_BYTES = 15 * 1024 * 1024;
+        child.stdout?.on('data', (d) => {
+            totalBytes += d.length;
+            outChunks.push(d);
+            if (totalBytes > MAX_BYTES) {
+                killed = true;
+                child.kill();
+            }
+        });
+        child.stderr?.on('data', (d) => { errChunks.push(d); });
+        child.on('error', (err) => {
+            // spawn 失败（如 ENOENT）对齐 execFile 的错误形状：code 保留在 Error 上
+            const e = Object.assign(new Error(err.message), { code: err.code });
+            settle(e);
+        });
+        child.on('close', (code, signal) => {
+            if (killed) {
+                // 超时/超量被杀：对齐 execFile 的 Timeout 错误形状（err.killed + signal）
+                const e = Object.assign(new Error(`Command timed out after ${opts.timeout}ms`), { killed: true, signal: signal || 'SIGTERM' });
+                settle(e);
+                return;
+            }
+            if (code !== 0) {
+                const e = Object.assign(new Error(`Command failed with exit code ${code}`), { code, stderr: Buffer.concat(errChunks).toString('utf8').slice(0, 800) });
+                settle(e);
+                return;
+            }
+            settle();
+        });
+        // stdin 注入：end(data) 半关闭（写完即 EOF），子进程流式读取或一次性读取均可
+        child.stdin?.end(opts.stdin, (err) => {
+            if (err && !settled) {
+                const e = Object.assign(new Error(`stdin write failed: ${err.message}`), { code: 'EPIPE' });
+                settle(e);
+            }
+        });
+    });
+}
 /** 认证状态缓存时长。用户手动 `gh auth login/logout` 后最多 30 秒内面板才会反映，属可接受代价 */
 const AUTH_CACHE_TTL_MS = 30_000;
+/** gh 版本缓存时长。与 authCache 同哲学：gh 升级是分钟级低频事件，30 秒陈旧窗口无实际影响 */
+const GH_VERSION_CACHE_TTL_MS = 30_000;
+/**
+ * 从 `gh --version` 输出中解析语义化版本号。
+ * 抽成导出纯函数的原因与 truncateOutput 相同：解析逻辑是「看似简单实则易错」的边界区，
+ * 必须能用单元测试钉死（不匹配输入返回 null 而非抛错，调用方据此走 fail-open）。
+ */
+export function parseGhVersion(output) {
+    const m = /gh version (\d+\.\d+\.\d+)/.exec(output || '');
+    return m ? m[1] : null;
+}
+/**
+ * 数值分段比较两个 gh 版本：a>b 返回 1、a<b 返回 -1、相等返回 0。
+ * 为什么不能用字符串比较：`'2.96.0' < '2.100.0'` 在字典序下为 false（'1'<'9'），
+ * 这会把 2.100 误判为低于 2.96，导致可用命令被错误降级。逐段 Number 比较是唯一正确姿势。
+ */
+export function compareGhVersions(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const da = pa[i] ?? 0;
+        const db = pb[i] ?? 0;
+        if (da > db)
+            return 1;
+        if (da < db)
+            return -1;
+    }
+    return 0;
+}
+/**
+ * 解析 `git status -sb --porcelain` 输出为结构化状态。
+ * 抽导出纯函数（parseGhVersion 同理）：三形态解析是易错边界区，单测钉死。
+ *
+ * 输出形态（实测）：
+ *   `## master...origin/master [ahead 2, behind 1]`  有 ahead/behind
+ *   `## master...origin/master`                       与远程同步
+ *   `## master` / `## HEAD (no branch)`               无 upstream（ahead/behind 未知=-1）
+ * 后续每行 `<XY> <path>` 为 porcelain 变更项（XY 两字符状态码，?? = untracked）。
+ */
+export function parseGitStatusOutput(output) {
+    const lines = (output || '').split('\n').filter((l) => l.length > 0);
+    if (lines.length === 0 || !lines[0].startsWith('## '))
+        return null;
+    const branchLine = lines[0].slice(3); // 去掉 '## ' 前缀
+    const hasUpstream = branchLine.includes('...');
+    const branchPart = hasUpstream ? branchLine.split('...')[0] : branchLine.split(' ')[0];
+    let ahead = -1;
+    let behind = -1;
+    if (hasUpstream) {
+        // ahead/behind 段在 upstream 之后（可能与 #id 同现：origin/master #12）。
+        // git 输出形态实测：`[ahead 2]` / `[behind 1]` / `[ahead 2, behind 1]`——
+        // 单括号内逗号分隔，behind 不必然前邻 '['（正则不可锚定 '['，否则
+        // `[ahead 2, behind 1]` 形态的 behind 永远漏解析——单测抓到的真实 Bug）
+        const trackingPart = branchLine.split('...')[1] || '';
+        ahead = 0;
+        behind = 0;
+        const aheadMatch = /ahead (\d+)/.exec(trackingPart);
+        const behindMatch = /behind (\d+)/.exec(trackingPart);
+        if (aheadMatch)
+            ahead = Number(aheadMatch[1]);
+        if (behindMatch)
+            behind = Number(behindMatch[1]);
+        // 仅 ahead 无 behind 时 behind=0（反之亦然）——git 输出只列非零侧
+    }
+    const dirtyFiles = [];
+    for (let i = 1; i < lines.length && dirtyFiles.length < 20; i++) {
+        const line = lines[i];
+        if (line.length < 4)
+            continue;
+        const status = line.slice(0, 2).trim() || 'M';
+        // 路径可能含空格（git 不加引号场景）；rename 形态 `R  old -> new` 取 new
+        let p = line.slice(3);
+        const renameArrow = p.indexOf(' -> ');
+        if (renameArrow >= 0)
+            p = p.slice(renameArrow + 4);
+        dirtyFiles.push({ status, path: p });
+    }
+    return {
+        branch: branchPart.replace(/\s*\(no branch\)$/, '') || 'HEAD',
+        ahead,
+        behind,
+        dirtyCount: Math.max(0, lines.length - 1),
+        hasUpstream,
+        dirtyFiles,
+    };
+}
+/**
+ * 解析 `git log` 输出为提交条目数组。
+ * 支持两种形态：
+ * 1. 结构化带详情：%x1e 为 commit 间分隔符，%x1f 为字段间分隔符（含 fullSha/email/date/body/stat）；
+ * 2. 简易管道符：%h|%an|%ar|%s 行格式（兼容旧单测输入）。
+ * 空输出返回 []。
+ */
+export function parseGitLogLines(output) {
+    const out = (output || '').trim();
+    if (!out)
+        return [];
+    if (out.includes('\x1e') || out.includes('\x1f')) {
+        const records = out.split('\x1e').filter((c) => c.trim().length > 0);
+        return records.map((chunk) => {
+            const parts = chunk.split('\x1f');
+            return {
+                sha: (parts[0] || '').trim(),
+                fullSha: (parts[1] || '').trim() || undefined,
+                author: (parts[2] || '').trim(),
+                email: (parts[3] || '').trim() || undefined,
+                date: (parts[4] || '').trim() || undefined,
+                relative: (parts[5] || '').trim(),
+                subject: (parts[6] || '').trim(),
+                body: (parts[7] || '').trim() || undefined,
+                stat: (parts[8] || '').trim() || undefined,
+            };
+        });
+    }
+    return out.split('\n').filter(Boolean).map((line) => {
+        const parts = line.split('|');
+        return {
+            sha: parts[0] || '',
+            author: parts[1] || '',
+            relative: parts[2] || '',
+            subject: parts.slice(3).join('|'),
+        };
+    });
+}
 /**
  * 按码点安全截取字符串，等价于 String.prototype.slice 但对孤立的代理对（surrogate pair）做占位替换。
  * 为什么必须这样截：本文件末尾会按 UTF-8 字节数截断，而 node:child_process 把 stdout 按字节缓冲区
@@ -102,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 页面数据
@@ -111,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)
@@ -125,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)
@@ -185,11 +401,16 @@ export class GhExecutor {
     async run(args, options = {}) {
         const cwd = this.resolveWorkspaceCwd(options.cwd, options.sessionId);
         const timeout = options.timeoutMs || this.defaultTimeoutMs;
+        // 二进制模式（如 gh api 下载图片字节流）：stdout 保持 Buffer，绕过 UTF-8
+        // 字符串转换（PNG 等二进制经 utf8 解码必然损坏），也不做截断（截断只面向
+        // 文本 Token 预算）。显式开启才生效，既有调用方零感知。
+        const binary = options.binary === true;
         try {
-            const { stdout, stderr } = await execFileAsync(this.ghPath, args, {
+            // stdin 显式传入时走 spawn 通道：execFile 的 input 选项在本机从不真正写入
+            // （详见 spawnWithStdin 注释），gh secret set 等命令会挂到超时。其余调用
+            // 保持 execFileAsync 原路径零改动。
+            const commonOpts = {
                 cwd,
-                timeout,
-                maxBuffer: 15 * 1024 * 1024, // 15MB 进程缓冲
                 env: {
                     ...process.env,
                     GH_NO_UPDATE_NOTIFIER: '1', // 禁用 CLI 版本更新检查，避免污染 stdout
@@ -197,16 +418,48 @@ 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,
                 },
-                // 仅在显式传入 stdin 时附加 input 键：promisified execFile 会把 input
-                // 写入子进程 stdin 后立即结束流。不传则保持既有行为（继承/null 句柄），
-                // 确保对全部既有调用方零破坏。
-                ...(options.stdin !== undefined ? { input: options.stdin } : {}),
-            });
-            let rawOutput = (stdout || '').trim();
-            if (!rawOutput && stderr) {
-                rawOutput = stderr.trim();
+            };
+            let stdout;
+            let stderr;
+            if (options.stdin !== undefined) {
+                const r = await spawnWithStdin(this.ghPath, args, { ...commonOpts, timeout, stdin: options.stdin });
+                stdout = r.stdout;
+                stderr = r.stderr;
+            }
+            else {
+                const r = await execFileAsync(this.ghPath, args, {
+                    ...commonOpts,
+                    timeout,
+                    maxBuffer: 15 * 1024 * 1024, // 15MB 进程缓冲
+                    ...(binary ? { encoding: 'buffer' } : {}),
+                });
+                stdout = r.stdout;
+                stderr = r.stderr;
+            }
+            // 二进制通道：Buffer 原样返回（调用方自行写文件/校验魔数），stderr 仅作
+            // 错误线索不做输出回退——把错误提示字节当图片保存毫无意义。
+            // TS 无法从 options 展开的 encoding 键收窄 stdout 类型，这里显式归一化。
+            if (binary) {
+                const buf = Buffer.isBuffer(stdout) ? stdout : Buffer.from(String(stdout ?? ''));
+                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 || '二进制输出为空' };
+                }
+                return { ok: true, data: buf, binaryBytes: buf.length, truncated: false };
+            }
+            const outText = Buffer.isBuffer(stdout) ? stdout.toString('utf8') : String(stdout ?? '');
+            const errText = Buffer.isBuffer(stderr) ? stderr.toString('utf8') : String(stderr ?? '');
+            let rawOutput = outText.trim();
+            if (!rawOutput && errText) {
+                rawOutput = errText.trim();
             }
             const outcome = truncateOutput(rawOutput, this.maxOutputChars, this.maxOutputBytes);
             rawOutput = outcome.text;
@@ -267,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

@@ -14,6 +14,7 @@ import { UpdateChecker } from './updater.js';
 import { UpgradeManager } from './upgrade-manager.js';
 import { ProxyManager } from './proxy.js';
 import { NPM_PACKAGE_URL } from './version.js';
+import { loadUpdateSettings } from './update-settings.js';
 // 引用即生效：加载本模块以挂上 declare module '@deepseek-ai/cordis' 的 ctx.github 类型声明，
 // 并随下面 `export * from './github-service.js'` 一起传给消费方。
 import './github-service.js';
@@ -44,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,
@@ -62,10 +64,18 @@ export function apply(ctx, config = {}) {
     const updateChecker = new UpdateChecker({
         intervalMs: config.updateCheckIntervalMs,
         customRegistry: config.registryUrl,
+        // checkUpdate: false 熔断全部探测入口（路由/命令/启动横幅共用此实例）
+        enabled: config.checkUpdate !== false,
     });
+    // 更新源设置（UI 持久化 store 优先于 Cordis 静态配置）：
+    // 启动时读取并应用到 checker；UI 保存时经路由直接调 applySettings 热切换。
+    const updateMode = loadUpdateSettings();
+    updateChecker.applySettings(updateMode);
     updateChecker.applyProxy(proxyManager);
     const upgradeManager = new UpgradeManager();
     upgradeManager.attachProxyManager(proxyManager);
+    // 注入查询函数而非静态值：用户切源后，下一次一键升级的 registry 实时跟随
+    upgradeManager.attachUpdateModeQuery(() => updateChecker.getSourceMode());
     // 1. 兑现生态服务契约：将 GitHub 执行引擎作为服务暴露给其他 DSH 插件 (ctx.github)
     if (ctx.provide && typeof ctx.provide === 'function') {
         ctx.provide('github', executor);

package/lib/renderers/markdown.d.ts

@@ -11,10 +11,21 @@
 export declare function sanitizeCell(text: any, maxLen?: number): string;
 /** 格式化 PR / Issue 状态药丸徽章 */
 export declare function formatStateBadge(state?: string, isDraft?: boolean): string;
-/** 格式化 CI 工作流状态徽章 */
+/**
+ * 格式化 CI 工作流状态徽章。
+ * 第二参数按调用域语义不同：run 域传 conclusion（success/failure/cancelled/skipped），
+ * pr checks 域传 bucket（pass/fail/pending/skipping/cancel）——取值族不同但映射到
+ * 同一组徽章；state 参数兜底（in_progress/queued 等进行中态）。
+ */
 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;