dsh-github-flow 0.4.0 → 0.6.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/error-classifier.d.ts

@@ -0,0 +1,55 @@
+/**
+ * gh 错误语义分类（确定性配置错误 vs 可重试的传输层故障）。
+ *
+ * 为什么必须区分：`gh` 失败时一律以非零退出码返回，调用方只能看到一段 stderr
+ * 文本。过去上层（Web 概览路由）把所有非零退出统一当成「网络错误」，于是
+ * 「仓库关闭了 Issues」这种永久性配置事实被伪装成网络抖动——既弹出误导性的
+ * 「网络连接失败」横幅，又触发 3 轮阶梯退避重试与每 5-10 分钟一轮的自动同步，
+ * 把确定性失败当成偶发抖动反复空烧。
+ *
+ * 判据全部来自 gh 2.96 实测 stderr：
+ *   - the 'o/r' repository has disabled issues
+ *   - the 'o/r' repository has discussions disabled
+ *   - GraphQL: Could not resolve to a Repository with the name 'o/r'. (repository)
+ *   - HTTP 403 / Not Found (HTTP 404)
+ *
+ * 纯文本判定，不做任何 I/O——它是 GhResult.errorKind 的唯一事实源。
+ */
+/** gh 失败结果的语义种类 */
+export type GhErrorKind = 
+/** 传输层故障（超时、DNS、连接重置、代理阻断）：值得重试，允许回退历史快照 */
+'transient'
+/** 确定性失败（仓库关闭 issues、仓库不存在、权限不足）：重试永远无意义 */
+ | 'deterministic'
+/** 命令失败但无明确归属，按可重试处理（保守不误杀） */
+ | 'unknown';
+/**
+ * 判定一次 gh 失败的语义种类。
+ *
+ * 优先级设计：确定性 > 限流放行 > 传输层 > unknown。
+ * 为什么不把「同时命中确定性与传输层」判为 transient：若仓库关闭了 Issues，
+ * 网络恢复后该命令依然失败。判成 transient 会让调用方每轮回退旧快照、
+ * 永远收敛不到正确状态。确定性一旦命中就该立刻停止重试。
+ */
+export declare function classifyGhError(errorText: string | undefined | null): GhErrorKind;
+/**
+ * 把确定性失败翻译成面向用户的友好说明。
+ * 返回 null 表示不属于确定性失败，调用方应走原有网络故障路径。
+ */
+export declare function describeDeterministicError(errorText: string | undefined | null): string | null;
+/** 该错误是否值得重试（供 UI 层决定是否走阶梯退避） */
+export declare function isRetryableError(errorText: string | undefined | null): boolean;
+export declare function isPermissionError(errorText: string | undefined | null): boolean;
+/**
+ * 把「权限不足」翻译成可操作的处置指引。
+ *
+ * 为什么不能只回一句「无权限」：Agent 与用户都需要知道**下一步做什么**。
+ * GitHub 的权限错误有明确解法路径（提权到 Triage/Write、或改用 fork 工作流），
+ * 把这条路径说出来，比让用户自己搜错误文本有用得多。
+ *
+ * @param errorText gh 的 stderr
+ * @param action 可选：正在执行的动作标识（如 'merge' / 'close' / 'add_label'），
+ *               用于在错误文本特征不足时精准匹配
+ * @returns 指引文本；非权限错误返回 null（不产生噪音）
+ */
+export declare function permissionRemedy(errorText: string | undefined | null, action?: string): string | null;

package/lib/executor/error-classifier.js

@@ -0,0 +1,199 @@
+/**
+ * gh 错误语义分类（确定性配置错误 vs 可重试的传输层故障）。
+ *
+ * 为什么必须区分：`gh` 失败时一律以非零退出码返回，调用方只能看到一段 stderr
+ * 文本。过去上层（Web 概览路由）把所有非零退出统一当成「网络错误」，于是
+ * 「仓库关闭了 Issues」这种永久性配置事实被伪装成网络抖动——既弹出误导性的
+ * 「网络连接失败」横幅，又触发 3 轮阶梯退避重试与每 5-10 分钟一轮的自动同步，
+ * 把确定性失败当成偶发抖动反复空烧。
+ *
+ * 判据全部来自 gh 2.96 实测 stderr：
+ *   - the 'o/r' repository has disabled issues
+ *   - the 'o/r' repository has discussions disabled
+ *   - GraphQL: Could not resolve to a Repository with the name 'o/r'. (repository)
+ *   - HTTP 403 / Not Found (HTTP 404)
+ *
+ * 纯文本判定，不做任何 I/O——它是 GhResult.errorKind 的唯一事实源。
+ */
+/**
+ * 确定性失败的 stderr 特征表。
+ *
+ * 为什么用特征串而不是退出码：gh 对上述场景统一返回 exit 1，退出码无法区分
+ * 「仓库关了 Issues」与「网线掉了」。文本特征是唯一可用的判据。
+ * 每条都必须来自实测输出——误判会把真实网络故障降级成静默空数据，比误报更糟。
+ */
+const DETERMINISTIC_PATTERNS = [
+    // 仓库级开关关闭（Issues / Discussions / Projects / Wiki）。
+    // 注意 gh 的措辞不统一（实测）：
+    //   issues      → "repository has disabled issues"
+    //   discussions → "repository has discussions disabled"
+    // 词序相反，所以两种形态都要覆盖，不能只写一种。
+    {
+        re: /repository has (?:disabled )?(issues|discussions|projects|wiki)(?: disabled)?/i,
+        reason: '该仓库未开启该项协作功能',
+    },
+    // 仓库不可达（不存在 / 无权限 / 已改名）：GraphQL 与 REST 两条通道
+    { re: /Could not resolve to a Repository/i, reason: '仓库不存在或当前账号无权访问' },
+    { re: /Not Found \(HTTP 404\)/i, reason: '仓库或资源不存在' },
+    // 分支 / PR / Issue 单体不存在
+    { re: /Branch not found/i, reason: '分支不存在' },
+    // GraphQL 通道的权限不足（实测形态）：
+    //   GraphQL: ItQianChen does not have the correct permissions to execute `AddLabelsToLabelable` (addLabelsToLabelable)
+    //   GraphQL: ItQianChen does not have the correct permissions to execute `DeleteIssue` (deleteIssue)
+    // 这类文本里没有 "HTTP 403"，若不单列会被归为 unknown，进而被当成可重试抖动——
+    // 而权限不足重试一万次也不会变。
+    { re: /does not have the correct permissions to execute/i, reason: '当前账号对该仓库的权限不足' },
+];
+/** 把「仓库未开启某项功能」翻译成点名说明（比笼统的“未开启协作功能”有用） */
+const DISABLED_FEATURE_LABEL = {
+    issues: 'Issues',
+    discussions: 'Discussions',
+    projects: 'Projects',
+    wiki: 'Wiki',
+};
+/**
+ * 限流类 403 必须先于通用 403 放行。
+ * 为什么单列：GitHub 的 `HTTP 403` 既可能是「无权限」（确定性），也可能是
+ * 「API rate limit exceeded / secondary rate limit」（几分钟后可恢复）。
+ * 把限流误判成确定性会让学生等一会儿就能好的请求被判死刑。
+ */
+const RATE_LIMIT_RE = /rate limit|secondary rate limit|abuse detection/i;
+/** 传输层故障特征（显式白名单，用于给出「可重试」的准确语义） */
+const TRANSIENT_PATTERNS = [
+    /命令执行超时/,
+    /\bETIMEDOUT\b/i,
+    /\bECONNRESET\b/i,
+    /\bECONNREFUSED\b/i,
+    /\bENOTFOUND\b/i,
+    /\bEAI_AGAIN\b/i,
+    /socket hang up/i,
+    /TLS handshake/i,
+    /proxyconnect/i,
+    /spawn EPERM/i,
+    /network is unreachable/i,
+    /Could not resolve host/i,
+    /no such host/i,
+];
+/**
+ * 判定一次 gh 失败的语义种类。
+ *
+ * 优先级设计：确定性 > 限流放行 > 传输层 > unknown。
+ * 为什么不把「同时命中确定性与传输层」判为 transient：若仓库关闭了 Issues，
+ * 网络恢复后该命令依然失败。判成 transient 会让调用方每轮回退旧快照、
+ * 永远收敛不到正确状态。确定性一旦命中就该立刻停止重试。
+ */
+export function classifyGhError(errorText) {
+    const text = String(errorText || '');
+    if (!text)
+        return 'unknown';
+    // 限流 403 先放行，避免被下面的通用 403 规则当成确定性失败
+    if (RATE_LIMIT_RE.test(text))
+        return 'transient';
+    for (const { re } of DETERMINISTIC_PATTERNS) {
+        if (re.test(text))
+            return 'deterministic';
+    }
+    // 通用 403 放在确定性表之后、transient 之前：无权限属于确定性
+    if (/HTTP 403/i.test(text))
+        return 'deterministic';
+    for (const re of TRANSIENT_PATTERNS) {
+        if (re.test(text))
+            return 'transient';
+    }
+    return 'unknown';
+}
+/**
+ * 把确定性失败翻译成面向用户的友好说明。
+ * 返回 null 表示不属于确定性失败，调用方应走原有网络故障路径。
+ */
+export function describeDeterministicError(errorText) {
+    const text = String(errorText || '');
+    if (!text)
+        return null;
+    if (RATE_LIMIT_RE.test(text))
+        return null;
+    // 先处理「仓库关闭某项功能」：点名到具体功能，比笼统措辞更容易让用户行动
+    const disabled = /repository has (?:disabled )?(issues|discussions|projects|wiki)(?: disabled)?/i.exec(text);
+    if (disabled) {
+        const label = DISABLED_FEATURE_LABEL[disabled[1].toLowerCase()] || disabled[1];
+        return `该仓库未开启 ${label}`;
+    }
+    for (const { re, reason } of DETERMINISTIC_PATTERNS) {
+        if (re.test(text))
+            return reason;
+    }
+    if (/HTTP 403/i.test(text))
+        return '当前账号无此操作权限';
+    return null;
+}
+/** 该错误是否值得重试（供 UI 层决定是否走阶梯退避） */
+export function isRetryableError(errorText) {
+    return classifyGhError(errorText) !== 'deterministic';
+}
+/**
+ * 判断一段错误是否属于「权限不足」（而非仓库配置、不存在等确定性错误）。
+ *
+ * 为什么单独判定：确定性错误里只有权限这一类有「解法路径」（提权 / 换 fork 工作流），
+ * 其余（仓库关了 Issues、分支不存在）说再多也没用。
+ */
+const PERMISSION_RE = /does not have the correct permissions to execute|HTTP 403|Resource not accessible|Forbidden|must have (?:admin|push|write|triage|maintain) (?:access|permissions?)/i;
+export function isPermissionError(errorText) {
+    const text = String(errorText || '');
+    if (!text)
+        return false;
+    // 限流也常以 403 出现，但它不是权限问题——放行会让用户去改权限，做无用功
+    if (RATE_LIMIT_RE.test(text))
+        return false;
+    return PERMISSION_RE.test(text);
+}
+/**
+ * 已知操作 → 所需权限档位 的映射。
+ *
+ * 键取自 GitHub 的 GraphQL mutation 名与 gh 子命令动词（实测捕获）。
+ * 为什么不用完整枚举：GitHub 有上百个 mutation，穷举既不可能也没必要——
+ * 未命中的一律走默认指引，仍然是对的。
+ */
+const ACTION_PERMISSION_MAP = [
+    {
+        // 同时覆盖 GraphQL mutation 名（AddLabelsToLabelable）与 CLI 参数形态
+        // （--add-label / --remove-label）——两者出现在不同层级的错误文本里。
+        re: /AddLabelsToLabelable|RemoveLabelsFromLabelable|UpdateIssue|CloseIssue|TransferIssue|add-?label|remove-?label|close-?issue|issue (?:edit|close|pin|lock|transfer)/i,
+        level: 'Triage',
+        hint: '管理他人 Issue/PR（加标签、关闭、指派）需要 Triage 及以上权限。可请仓库管理员授予，或改用评论表达意见。',
+    },
+    {
+        re: /mergePullRequest|MergePullRequest|\bmerge\b|CreateRef|createRef|\bpush\b|CreateCommitOnBranch/i,
+        level: 'Write',
+        hint: '合并 PR / 推送代码需要 Write 及以上权限。若是他人仓库，请先 fork 到自己的账号，在 fork 上提交后向上游发起 PR。',
+    },
+    {
+        re: /DeleteIssue|deleteIssue|DeleteRepository|deleteRepository|TransferRepository|\bdelete\b/i,
+        level: 'Admin',
+        hint: '物理删除与仓库级操作需要管理员权限。这类操作不可逆，请联系仓库管理员执行。',
+    },
+];
+/**
+ * 把「权限不足」翻译成可操作的处置指引。
+ *
+ * 为什么不能只回一句「无权限」：Agent 与用户都需要知道**下一步做什么**。
+ * GitHub 的权限错误有明确解法路径（提权到 Triage/Write、或改用 fork 工作流），
+ * 把这条路径说出来，比让用户自己搜错误文本有用得多。
+ *
+ * @param errorText gh 的 stderr
+ * @param action 可选：正在执行的动作标识（如 'merge' / 'close' / 'add_label'），
+ *               用于在错误文本特征不足时精准匹配
+ * @returns 指引文本；非权限错误返回 null（不产生噪音）
+ */
+export function permissionRemedy(errorText, action) {
+    if (!isPermissionError(errorText))
+        return null;
+    const haystack = `${String(errorText || '')} ${String(action || '')}`;
+    for (const { re, hint } of ACTION_PERMISSION_MAP) {
+        if (re.test(haystack))
+            return hint;
+    }
+    // 默认指引：不指定具体档位。
+    // 为什么：只知道「权限不足」时猜档位很容易猜错（我们实测就猜错过——
+    // READ 用户能建 Issue，而不是处处受限），说错比不说更糟。
+    return '当前账号对该仓库的权限不足。可运行 `gh auth status` 查看作用域，或请仓库管理员提升权限。';
+}