dsh-github-flow 0.3.0 → 0.5.0

package/lib/commands/gh.d.ts

@@ -1,3 +1,8 @@
 import type { GhExecutor } from '../executor.js';
 import type { UpdateChecker } from '../updater.js';
-export declare function registerGhCommand(commandsService: any, executor: GhExecutor, updateChecker?: UpdateChecker): void;
+import { TelemetryCollector } from '../telemetry.js';
+/**
+ * 注册人类 Slash 快捷指令集
+ * 采用扁平化一级指令 + 二级参数容错双轨机制，消除用户“敲了 /gh 不会加参数”的交互盲区
+ */
+export declare function registerGhCommand(commandsService: any, executor: GhExecutor, updateChecker?: UpdateChecker, telemetryCollector?: TelemetryCollector): void;

package/lib/commands/gh.js

@@ -1,95 +1,168 @@
 import { CURRENT_PLUGIN_VERSION, PLUGIN_PACKAGE_NAME, NPM_PACKAGE_URL } from '../version.js';
 import { loadUpdateSettings, describeUpdateMode } from '../update-settings.js';
-export function registerGhCommand(commandsService, executor, updateChecker) {
+import { defaultTelemetryCollector } from '../telemetry.js';
+/**
+ * 构建 GitHub 状态大盘与诊断报告 Markdown
+ */
+async function buildStatusReport(executor, updateChecker, telemetryCollector) {
+    // 人类显式诊断必须绕过缓存：用户敲 /gh 往往正是为了确认
+    // 「我刚 gh auth login 到底成没成」，给他 30 秒前的缓存等于答非所问。
+    const auth = await executor.checkAuth(undefined, true);
+    const repo = await executor.getRepoMetadata();
+    const updateInfo = updateChecker?.getQuickStatus();
+    let md = `### GitHub 集成状态\n\n`;
+    // 若检测到新版本，在最上方展示醒目的升级指引横幅
+    if (updateInfo?.hasUpdate) {
+        md += `> 🚀 **发现新版本 v${updateInfo.latestVersion}**（当前为 \`v${updateInfo.currentVersion}\`）\n`;
+        md += `> 输入 \`/gh-upgrade\` 查看升级指引，或在终端执行：\`${updateInfo.upgradeCommand}\`\n\n`;
+    }
+    md += `- **插件版本**: \`v${updateInfo?.currentVersion || CURRENT_PLUGIN_VERSION}\`\n`;
+    if (auth.loggedIn) {
+        md += `- **登录账号**: \`${auth.user || '已登录'}\`\n`;
+        md += `- **授权作用域**: ${auth.scopes?.map((s) => `\`${s}\``).join(', ') || '标准权限'}\n`;
+    }
+    else {
+        md += `- **登录状态**: ❌ 未登录 GitHub\n`;
+        md += `> 提示：请在系统终端执行 \`gh auth login\` 进行登录。\n`;
+    }
+    if (repo) {
+        md += `\n**当前关联仓库**:\n`;
+        md += `- 仓库名: [${repo.nameWithOwner}](${repo.url})\n`;
+        md += `- 默认分支: \`${repo.defaultBranch}\`\n`;
+        if (repo.description)
+            md += `- 简介: ${repo.description}\n`;
+    }
+    else {
+        md += `\n*当前目录尚未关联 Git 远程仓库或未托管在 GitHub。*\n`;
+    }
+    // 遥测运行时健康度与降级率小节
+    const collector = telemetryCollector || defaultTelemetryCollector;
+    const summary = collector.getSummary();
+    let healthBadge = '🟢 极佳';
+    if (summary.statusLevel === 'NEEDS_ATTENTION')
+        healthBadge = '🔴 需关注';
+    else if (summary.statusLevel === 'GOOD')
+        healthBadge = '🟡 良好';
+    md += `\n**工具链运行时可观测性 (Telemetry)**:\n`;
+    md += `- 综合健康度: ${healthBadge} (${summary.healthScore} 分)\n`;
+    md += `- 统计样本量: ${summary.totalCalls} 次 Agent 工具调用\n`;
+    md += `- API 降级率: \`${summary.degradationRate}%\` (${summary.degradedCount} 次降级)\n`;
+    if (summary.recommendations.length > 0 && summary.degradationRate > 0) {
+        md += `> 💡 优化建议: ${summary.recommendations[0]}\n`;
+    }
+    md += `\n> 💡 **快捷指令指引**: 可直接输入 \`/gh-upgrade\` 检查组件更新，输入 \`/gh-help\` 查看 Agent 协作范例。`;
+    return md;
+}
+/**
+ * 构建插件版本升级指南 Markdown
+ */
+async function buildUpgradeReport(updateChecker) {
+    const info = updateChecker ? await updateChecker.check(true) : null;
+    const curVer = info?.currentVersion || CURRENT_PLUGIN_VERSION;
+    const latestVer = info?.latestVersion || curVer;
+    const hasUpdate = info?.hasUpdate ?? false;
+    const isMac = process.platform === 'darwin';
+    const isWin = process.platform === 'win32';
+    const platformName = isMac ? 'macOS' : isWin ? 'Windows' : 'Linux';
+    let md = `### 🚀 ${PLUGIN_PACKAGE_NAME} 插件升级指南\n\n`;
+    md += `- **当前运行版本**: \`v${curVer}\`\n`;
+    // 当前更新源：排查「查不到新版」时用户需可见自己在用哪个源
+    const liveMode = updateChecker?.getSourceMode?.() ?? null;
+    const effectiveMode = liveMode ?? loadUpdateSettings();
+    md += `- **当前更新源**: ${describeUpdateMode(effectiveMode)}\n`;
+    md += `- **官方最新版本**: \`v${latestVer}\` ${hasUpdate ? '🔥 (有可用更新)' : '✅ (已是最新)'}\n`;
+    md += `- **操作系统环境**: \`${platformName} (${process.platform})\`\n`;
+    md += `- **npm 仓库地址**: [${NPM_PACKAGE_URL}](${NPM_PACKAGE_URL})\n\n`;
+    md += `#### 请根据你的 DSH 安装环境选择适用的升级方式：\n\n`;
+    md += `1. **DSH 桌面版 Profile 环境升级（推荐）**:\n\`\`\`bash\ndsh plugin --profile desktop add ${PLUGIN_PACKAGE_NAME}@latest\n\`\`\`\n\n`;
+    md += `2. **DSH Web / CLI 环境**（profile 名按实际环境填写）:\n\`\`\`bash\ndsh plugin --profile web add ${PLUGIN_PACKAGE_NAME}@latest\n\`\`\`\n`;
+    if (isMac) {
+        md += `> 💡 *macOS 提示*：若在终端找不到 \`dsh\` 命令，可直接在桌面端目录更新：\n\`\`\`bash\ncd ~/.dsh/profiles/desktop && npm install ${PLUGIN_PACKAGE_NAME}@latest --save\n\`\`\`\n\n`;
+    }
+    else {
+        md += `\n`;
+    }
+    md += `3. **Node 全局环境升级**:\n\`\`\`bash\nnpm install -g ${PLUGIN_PACKAGE_NAME}@latest\n\`\`\`\n\n`;
+    md += `> 💡 **升级后提示**：Node.js 运行时对已载入模块存在强缓存，升级后**请重启 DSH 服务以完全加载最新后端工具**。`;
+    return md;
+}
+/**
+ * 构建使用帮助与 Agent 提示词范例 Markdown
+ */
+function buildHelpReport() {
+    return [
+        '### 🧭 DSH GitHub Flow 快捷指令帮助\n',
+        '- `/gh`：查看当前 GitHub CLI 账号认证状态、关联仓库与运行时健康度（直接回车即可）',
+        '- `/gh-upgrade`：检查新版本并输出针对当前系统的最佳升级命令',
+        '- `/gh-help`：显示此使用指南与 Agent 对话范例\n',
+        '*(提示：熟练用户亦可使用二级语法，如 `/gh upgrade`、`/gh status`)*\n',
+        '#### 可以在对话框直接让 Agent 操作 GitHub，例如：',
+        '- *"帮我看看今天在 GitHub 上有哪些需要我处理的事情？"*',
+        '- *"查看当前仓库有哪些开放的 PR，审查 PR #12 的代码差异"*',
+        '- *"查看最近一次 CI 失败的原因并尝试自动修复"*',
+        '- *"帮我给当前分支创建一个 PR 并附带改动说明"*',
+        '- *"在当前仓库发起一个新的 RFC 讨论方案"*',
+    ].join('\n');
+}
+/**
+ * 注册人类 Slash 快捷指令集
+ * 采用扁平化一级指令 + 二级参数容错双轨机制，消除用户“敲了 /gh 不会加参数”的交互盲区
+ */
+export function registerGhCommand(commandsService, executor, updateChecker, telemetryCollector) {
     if (!commandsService || typeof commandsService.register !== 'function')
         return;
+    // 1. 主指令 /gh（默认直接回车输出状态，同时兼容 /gh status, /gh upgrade, /gh help 及常见别名）
     commandsService.register({
         name: 'gh',
-        description: 'GitHub CLI 状态与诊断快捷指令',
+        description: '查看 GitHub 账号状态、关联仓库与运行时健康度（直接回车即可执行）',
         async handler({ rawInput }) {
-            const trimmed = (rawInput || '').trim();
-            if (!trimmed || trimmed === 'status') {
-                // 人类显式诊断必须绕过缓存：用户敲 /gh status 往往正是为了确认
-                // 「我刚 gh auth login 到底成没成」，给他 30 秒前的缓存等于答非所问。
-                const auth = await executor.checkAuth(undefined, true);
-                const repo = await executor.getRepoMetadata();
-                const updateInfo = updateChecker?.getQuickStatus();
-                let md = `### GitHub 集成状态\n\n`;
-                // 若检测到新版本，在最上方展示醒目的升级指引横幅
-                if (updateInfo?.hasUpdate) {
-                    md += `> 🚀 **发现新版本 v${updateInfo.latestVersion}**（当前为 \`v${updateInfo.currentVersion}\`）\n`;
-                    md += `> 输入 \`/gh upgrade\` 查看升级指引，或在终端执行：\`${updateInfo.upgradeCommand}\`\n\n`;
-                }
-                md += `- **插件版本**: \`v${updateInfo?.currentVersion || CURRENT_PLUGIN_VERSION}\`\n`;
-                if (auth.loggedIn) {
-                    md += `- **登录账号**: \`${auth.user || '已登录'}\`\n`;
-                    md += `- **授权作用域**: ${auth.scopes?.map((s) => `\`${s}\``).join(', ') || '标准权限'}\n`;
-                }
-                else {
-                    md += `- **登录状态**: ❌ 未登录 GitHub\n`;
-                    md += `> 提示：请在系统终端执行 \`gh auth login\` 进行登录。\n`;
-                }
-                if (repo) {
-                    md += `\n**当前关联仓库**:\n`;
-                    md += `- 仓库名: [${repo.nameWithOwner}](${repo.url})\n`;
-                    md += `- 默认分支: \`${repo.defaultBranch}\`\n`;
-                    if (repo.description)
-                        md += `- 简介: ${repo.description}\n`;
-                }
-                else {
-                    md += `\n*当前目录尚未关联 Git 远程仓库或未托管在 GitHub。*\n`;
-                }
+            const trimmed = (rawInput || '').trim().toLowerCase();
+            // 智能容错：无参数、status、info、auth 均直接直出状态大盘
+            if (!trimmed || trimmed === 'status' || trimmed === 'info' || trimmed === 'auth' || trimmed === 'check') {
                 return {
                     kind: 'success',
-                    text: md,
+                    text: await buildStatusReport(executor, updateChecker, telemetryCollector),
                 };
             }
-            if (trimmed === 'upgrade') {
-                const info = updateChecker ? await updateChecker.check(true) : null;
-                const curVer = info?.currentVersion || CURRENT_PLUGIN_VERSION;
-                const latestVer = info?.latestVersion || curVer;
-                const hasUpdate = info?.hasUpdate ?? false;
-                const isMac = process.platform === 'darwin';
-                const isWin = process.platform === 'win32';
-                const platformName = isMac ? 'macOS' : isWin ? 'Windows' : 'Linux';
-                let md = `### 🚀 ${PLUGIN_PACKAGE_NAME} 插件升级指南\n\n`;
-                md += `- **当前运行版本**: \`v${curVer}\`\n`;
-                // 当前更新源：排查「查不到新版」时（镜像同步滞后）用户需可见自己在用哪个源。
-                // 优先读 checker 内存态（store 写盘失败时磁盘是旧值，活实例才是事实源），
-                // 无 checker 或未初始化（sourceMode=null 的 legacy 路径）回落磁盘 store。
-                const liveMode = updateChecker?.getSourceMode?.() ?? null;
-                const effectiveMode = liveMode ?? loadUpdateSettings();
-                md += `- **当前更新源**: ${describeUpdateMode(effectiveMode)}\n`;
-                md += `- **官方最新版本**: \`v${latestVer}\` ${hasUpdate ? '🔥 (有可用更新)' : '✅ (已是最新)'}\n`;
-                md += `- **操作系统环境**: \`${platformName} (${process.platform})\`\n`;
-                md += `- **npm 仓库地址**: [${NPM_PACKAGE_URL}](${NPM_PACKAGE_URL})\n\n`;
-                md += `#### 请根据你的 DSH 安装环境选择适用的升级方式：\n\n`;
-                // 官方 CLI 语义：--profile 为必填参数（dsh plugin --profile <name> add <pkg>），
-                // 任何不带 --profile 的形态（含 pnpm dsh plugin add）都会直接报 required option 错误。
-                md += `1. **DSH 桌面版 Profile 环境升级（推荐）**:\n\`\`\`bash\ndsh plugin --profile desktop add ${PLUGIN_PACKAGE_NAME}@latest\n\`\`\`\n\n`;
-                md += `2. **DSH Web / CLI 环境**（profile 名按实际环境填写）:\n\`\`\`bash\ndsh plugin --profile web add ${PLUGIN_PACKAGE_NAME}@latest\n\`\`\`\n`;
-                if (isMac) {
-                    md += `> 💡 *macOS 提示*：若在终端找不到 \`dsh\` 命令，可直接在桌面端目录更新：\n\`\`\`bash\ncd ~/.dsh/profiles/desktop && npm install ${PLUGIN_PACKAGE_NAME}@latest --save\n\`\`\`\n\n`;
-                }
-                else {
-                    md += `\n`;
-                }
-                md += `3. **Node 全局环境升级**:\n\`\`\`bash\nnpm install -g ${PLUGIN_PACKAGE_NAME}@latest\n\`\`\`\n\n`;
-                md += `> 💡 **升级后提示**：Node.js 运行时对已载入模块存在强缓存，升级后**请重启 DSH 服务以完全加载最新后端工具**。`;
+            // 二级 upgrade / update 别名容错
+            if (trimmed === 'upgrade' || trimmed === 'update' || trimmed === 'up' || trimmed === 'version') {
                 return {
                     kind: 'success',
-                    text: md,
+                    text: await buildUpgradeReport(updateChecker),
                 };
             }
-            if (trimmed === 'help') {
+            // 二级 help / ? 别名容错
+            if (trimmed === 'help' || trimmed === 'h' || trimmed === '?') {
                 return {
                     kind: 'success',
-                    text: `### DSH GitHub Flow 帮助\n\n- \`/gh status\`: 检查当前 GitHub CLI 账号、仓库连接与插件版本\n- \`/gh upgrade\`: 检查新版本并显示全场景升级命令指引\n- \`/gh help\`: 显示此帮助信息\n\n可以在对话中直接让 Agent 操作 GitHub，如：\n- *"查看当前仓库有哪些开放的 PR"* \n- *"查看最近一次 CI 失败的原因"* \n- *"帮我给当前分支创建 PR"*`,
+                    text: buildHelpReport(),
                 };
             }
             return {
                 kind: 'error',
-                text: `未知命令选项: /gh ${trimmed}。可用用法: /gh status, /gh upgrade, /gh help`,
+                text: `未知命令选项: /gh ${rawInput}。可用快捷指令: /gh（查看状态）、/gh-upgrade（检查升级）、/gh-help（帮助）。`,
+            };
+        },
+    });
+    // 2. 扁平化一级指令 /gh-upgrade（下拉菜单一键可见，无需手动输入空格与子命令）
+    commandsService.register({
+        name: 'gh-upgrade',
+        description: '检查插件新版本并查看一键自动升级指引',
+        async handler() {
+            return {
+                kind: 'success',
+                text: await buildUpgradeReport(updateChecker),
+            };
+        },
+    });
+    // 3. 扁平化一级指令 /gh-help（下拉菜单一键可见，查看指南与 Agent 提示词范例）
+    commandsService.register({
+        name: 'gh-help',
+        description: '查看 GitHub 协作帮助与 Agent 提示词范例',
+        async handler() {
+            return {
+                kind: 'success',
+                text: buildHelpReport(),
             };
         },
     });

package/lib/executor/git-parser.d.ts

@@ -0,0 +1,57 @@
+import type { GitLocalStatus, GitCommitEntry, GitBranchesResult } from '../types.js';
+/**
+ * 解析 `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, maxFiles?: number): 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[];
+/**
+ * 解析 git branch -a --sort=-committerdate 格式化输出。
+ * 格式为: %(refname:short)|%(HEAD)|%(upstream:short)|%(committerdate:relative)|%(objectname:short)|%(subject)
+ */
+export declare function parseGitBranchLines(output: string): GitBranchesResult;
+/**
+ * 解析 unified diff 输出，统计增删行数与区块数量。
+ * 忽略 diff 文件头（--- 和 +++），仅统计真正的改动行（+ 与 -）。
+ */
+export declare function parseUncommittedDiff(rawDiff: string): {
+    additions: number;
+    deletions: number;
+    hunksCount: number;
+};
+export interface GitStatFileInfo {
+    path: string;
+    total: number;
+    additions: number;
+    deletions: number;
+    isBinary: boolean;
+    rawRight?: string;
+}
+export interface GitStatSummary {
+    filesChanged: number;
+    insertions: number;
+    deletions: number;
+}
+export interface GitStatParsedResult {
+    files: GitStatFileInfo[];
+    summary: GitStatSummary | null;
+}
+/**
+ * 解析 `git show --stat` 或 `git log --stat` 的统计文本为结构化列表与增删数字。
+ * 能够从 `19 ++++++++++++++++++-` 精准推导 additions=18, deletions=1，
+ * 提取文件路径与 `X files changed, Y insertions(+), Z deletions(-)` 汇总。
+ */
+export declare function parseGitStatText(statText: string): GitStatParsedResult | null;

package/lib/executor/git-parser.js

@@ -0,0 +1,255 @@
+/**
+ * 解析 `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, maxFiles = 20) {
+    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 = [];
+    const limit = maxFiles > 0 ? maxFiles : Number.MAX_SAFE_INTEGER;
+    for (let i = 1; i < lines.length && dirtyFiles.length < limit; 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).trim();
+        const renameArrow = p.indexOf(' -> ');
+        if (renameArrow >= 0)
+            p = p.slice(renameArrow + 4).trim();
+        if (p.startsWith('"') && p.endsWith('"') && p.length >= 2) {
+            p = p.slice(1, -1);
+        }
+        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('|'),
+        };
+    });
+}
+/**
+ * 解析 git branch -a --sort=-committerdate 格式化输出。
+ * 格式为: %(refname:short)|%(HEAD)|%(upstream:short)|%(committerdate:relative)|%(objectname:short)|%(subject)
+ */
+export function parseGitBranchLines(output) {
+    const lines = output.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    let current = '';
+    const branches = [];
+    const seenNames = new Set();
+    for (const line of lines) {
+        const parts = line.split('|');
+        if (parts.length < 5)
+            continue;
+        const rawRef = parts[0].trim();
+        // 过滤掉指向 HEAD 的符号引用（如 origin/HEAD）
+        if (rawRef.includes('/HEAD') || rawRef === 'HEAD')
+            continue;
+        const isCurrent = parts[1].trim() === '*';
+        const upstream = parts[2].trim() || undefined;
+        const relativeTime = parts[3].trim() || '';
+        const shortSha = parts[4].trim() || '';
+        const subject = parts.slice(5).join('|').trim();
+        // 区分远程分支与本地分支
+        const isRemote = rawRef.startsWith('origin/') || rawRef.startsWith('remotes/');
+        const cleanName = rawRef.replace(/^remotes\//, '');
+        if (seenNames.has(cleanName))
+            continue;
+        seenNames.add(cleanName);
+        if (isCurrent) {
+            current = cleanName;
+        }
+        branches.push({
+            name: cleanName,
+            isCurrent,
+            isRemote,
+            upstream,
+            shortSha,
+            subject,
+            relativeTime,
+        });
+    }
+    // 若未从 * 解析到当前分支，默认以第一条本地分支兜底
+    if (!current && branches.length > 0) {
+        const local = branches.find((b) => !b.isRemote);
+        current = local ? local.name : branches[0].name;
+    }
+    return { current, branches };
+}
+/**
+ * 解析 unified diff 输出，统计增删行数与区块数量。
+ * 忽略 diff 文件头（--- 和 +++），仅统计真正的改动行（+ 与 -）。
+ */
+export function parseUncommittedDiff(rawDiff) {
+    let additions = 0;
+    let deletions = 0;
+    let hunksCount = 0;
+    if (!rawDiff || typeof rawDiff !== 'string') {
+        return { additions, deletions, hunksCount };
+    }
+    const lines = rawDiff.split('\n');
+    for (const line of lines) {
+        if (line.startsWith('@@')) {
+            hunksCount++;
+        }
+        else if (line.startsWith('+') && !line.startsWith('+++')) {
+            additions++;
+        }
+        else if (line.startsWith('-') && !line.startsWith('---')) {
+            deletions++;
+        }
+    }
+    return { additions, deletions, hunksCount };
+}
+/**
+ * 解析 `git show --stat` 或 `git log --stat` 的统计文本为结构化列表与增删数字。
+ * 能够从 `19 ++++++++++++++++++-` 精准推导 additions=18, deletions=1，
+ * 提取文件路径与 `X files changed, Y insertions(+), Z deletions(-)` 汇总。
+ */
+export function parseGitStatText(statText) {
+    if (!statText || typeof statText !== 'string')
+        return null;
+    const lines = statText.split('\n');
+    const files = [];
+    let summary = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        // 检查汇总行（如 6 files changed, 62 insertions(+), 6 deletions(-)）
+        const summaryMatch = trimmed.match(/(\d+)\s+files?\s+changed(?:,\s+(\d+)\s+insertions?\(\+\))?(?:,\s+(\d+)\s+deletions?\(-\))?/i);
+        if (summaryMatch) {
+            summary = {
+                filesChanged: parseInt(summaryMatch[1], 10),
+                insertions: parseInt(summaryMatch[2] || '0', 10),
+                deletions: parseInt(summaryMatch[3] || '0', 10),
+            };
+            continue;
+        }
+        // 检查文件变更行（包含 | 分隔符）
+        const pipeIdx = trimmed.indexOf('|');
+        if (pipeIdx > 0) {
+            let left = trimmed.slice(0, pipeIdx).trim();
+            const right = trimmed.slice(pipeIdx + 1).trim();
+            // 去除文件名两端可能的双引号
+            if (left.startsWith('"') && left.endsWith('"') && left.length >= 2) {
+                left = left.slice(1, -1);
+            }
+            if (/^Bin\b/i.test(right)) {
+                files.push({ path: left, total: 0, additions: 0, deletions: 0, isBinary: true, rawRight: right });
+            }
+            else {
+                const numMatch = right.match(/^(\d+)(.*)$/);
+                if (numMatch) {
+                    const total = parseInt(numMatch[1], 10);
+                    const graph = numMatch[2].trim();
+                    let plusCount = 0;
+                    let minusCount = 0;
+                    for (let i = 0; i < graph.length; i++) {
+                        if (graph[i] === '+')
+                            plusCount++;
+                        else if (graph[i] === '-')
+                            minusCount++;
+                    }
+                    let additions = 0;
+                    let deletions = 0;
+                    if (plusCount === 0 && minusCount === 0) {
+                        additions = total;
+                    }
+                    else if (minusCount === 0) {
+                        additions = total;
+                        deletions = 0;
+                    }
+                    else if (plusCount === 0) {
+                        additions = 0;
+                        deletions = total;
+                    }
+                    else {
+                        if (plusCount + minusCount === total) {
+                            additions = plusCount;
+                            deletions = minusCount;
+                        }
+                        else {
+                            const addExact = Math.round((total * plusCount) / (plusCount + minusCount));
+                            additions = addExact;
+                            deletions = Math.max(0, total - addExact);
+                        }
+                    }
+                    files.push({ path: left, total, additions, deletions, isBinary: false });
+                }
+            }
+        }
+    }
+    if (files.length === 0 && !summary)
+        return null;
+    return { files, summary };
+}

package/lib/executor/platform-guide.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 获取当前平台的推荐 gh 安装引导与命令。
+ * 覆盖 Windows (winget/scoop)、macOS (Homebrew/MacPorts)、Linux (apt/dnf)。
+ */
+export declare function getPlatformInstallGuide(): {
+    command: string;
+    altCommand: string;
+    downloadUrl: string;
+    description: string;
+};
+/**
+ * gh 升级命令按平台提示（复用三态状态机的平台判断口径）。
+ */
+export declare function getGhUpgradeHint(): string;

package/lib/executor/platform-guide.js

@@ -0,0 +1,40 @@
+/**
+ * 获取当前平台的推荐 gh 安装引导与命令。
+ * 覆盖 Windows (winget/scoop)、macOS (Homebrew/MacPorts)、Linux (apt/dnf)。
+ */
+export function getPlatformInstallGuide() {
+    const p = process.platform;
+    if (p === 'win32') {
+        return {
+            command: 'winget install --id GitHub.cli',
+            altCommand: 'scoop install gh',
+            downloadUrl: 'https://cli.github.com/',
+            description: '推荐使用 Windows Package Manager (winget) 一键安装，或下载官方 .msi 安装包。',
+        };
+    }
+    if (p === 'darwin') {
+        return {
+            command: 'brew install gh',
+            altCommand: 'port install gh',
+            downloadUrl: 'https://cli.github.com/',
+            description: '推荐使用 Homebrew 安装 GitHub CLI。',
+        };
+    }
+    return {
+        command: 'sudo apt install gh',
+        altCommand: 'sudo dnf install gh',
+        downloadUrl: 'https://cli.github.com/',
+        description: '推荐使用系统包管理器安装（Debian/Ubuntu 运行 apt，Fedora/CentOS 运行 dnf）。',
+    };
+}
+/**
+ * gh 升级命令按平台提示（复用三态状态机的平台判断口径）。
+ */
+export function 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/。';
+}