dsh-github-flow 0.5.0 → 0.7.0

package/lib/destructive.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 破坏性操作声明表 + 统一闸门。
+ *
+ * 为什么要有这张表：同一个「拦截 → 返回影响评估 → 要求 confirm: true」的模式在
+ * 16 个 (工具, action) 上各写了一遍。任何一处忘写就是漏洞，而漏洞是**看不见的**
+ * （工具照常返回成功，没人知道本该拦一次）。表化之后「没有条目 = 没有闸门」可以
+ * 一眼审完，并且能被测试穷举。
+ *
+ * 拦截点收在一处实现（`wrapWithGate`），由每个工具的工厂函数返回时套上——见文件末尾该函数的注释。`src/tools/` 里不再保留任何一行闸门代码。
+ *
+ * ⚠️ 与旧实现的一处已知差异：`cache delete` / `issue transfer` / `label delete` 的
+ * 旧文案里内插了**运行时解析出的仓库名**（`repoTarget`）。注册期拿不到它（要额外打
+ * 一次 `gh repo view`），因此文案改为不内插仓库名。渲染层只消费
+ * warning/impact/requiredAction 三个字段，不消费 repo，故输出形态无变化。
+ */
+/** 闸门状态字面量的唯一来源：工具层与渲染层都引用它，不再各写一遍字符串。 */
+export declare const GATE_BLOCKED: 'AWAITING_CONFIRMATION';
+export interface GatePayload {
+    status: typeof GATE_BLOCKED;
+    warning: string;
+    impact: string;
+    requiredAction: string;
+    /** 部分工具额外回显的定位字段（action / name / gist_id / cache_id / key / all） */
+    [key: string]: unknown;
+}
+interface GateSpec {
+    /**
+     * 命中条件。缺省 = 该 action 恒拦。
+     *
+     * 为什么需要这个字段：`release upload` 只在 clobber 时危险、`skill publish` 只在
+     * 正式发布时危险。条件写进表里，过滤逻辑就不再散落在各工具的分支里。
+     * 同时用它表达「原实现里位于闸门之前的必填校验」——否则一个缺参数的调用会先拿到
+     * 「请确认」而不是本该拿到的「必须提供 xxx」，那是行为回退。
+     */
+    when?: (args: any) => boolean;
+    describe(args: any): GatePayload;
+}
+export declare const DESTRUCTIVE_ACTIONS: Record<string, Record<string, GateSpec>>;
+/**
+ * 统一闸门：命中则返回拦截载荷，否则返回 undefined。
+ *
+ * `confirm === true` 的判定放在这里而不是每个 describe 里——15 份重复的
+ * `if (args.confirm !== true)` 正是这次要消掉的东西。
+ */
+export declare function guardDestructive(toolName: string, args: any): GatePayload | undefined;
+/**
+ * 用闸门包一层 execute（注册期唯一入口）。
+ *
+ * 为什么包在注册期而不是 `executor.run()`：`run()` 只看得见 argv，看不见
+ * `action` / `confirm` 语义。把语义解析塞进 argv 层就是把简单问题复杂化。
+ *
+ * 保持 `name` / `description` / `parameters` / `output` 原样，只替换 `execute`，
+ * 宿主侧的 schema 校验与渲染链路完全不受影响。
+ */
+export declare function wrapWithGate<T extends {
+    name: string;
+    execute: (...a: any[]) => any;
+}>(tool: T): T;
+export {};

package/lib/destructive.js

@@ -0,0 +1,285 @@
+/**
+ * 破坏性操作声明表 + 统一闸门。
+ *
+ * 为什么要有这张表：同一个「拦截 → 返回影响评估 → 要求 confirm: true」的模式在
+ * 16 个 (工具, action) 上各写了一遍。任何一处忘写就是漏洞，而漏洞是**看不见的**
+ * （工具照常返回成功，没人知道本该拦一次）。表化之后「没有条目 = 没有闸门」可以
+ * 一眼审完，并且能被测试穷举。
+ *
+ * 拦截点收在一处实现（`wrapWithGate`），由每个工具的工厂函数返回时套上——见文件末尾该函数的注释。`src/tools/` 里不再保留任何一行闸门代码。
+ *
+ * ⚠️ 与旧实现的一处已知差异：`cache delete` / `issue transfer` / `label delete` 的
+ * 旧文案里内插了**运行时解析出的仓库名**（`repoTarget`）。注册期拿不到它（要额外打
+ * 一次 `gh repo view`），因此文案改为不内插仓库名。渲染层只消费
+ * warning/impact/requiredAction 三个字段，不消费 repo，故输出形态无变化。
+ */
+/** 闸门状态字面量的唯一来源：工具层与渲染层都引用它，不再各写一遍字符串。 */
+export const GATE_BLOCKED = 'AWAITING_CONFIRMATION';
+const str = (v) => (v === undefined || v === null ? '' : String(v).trim());
+/** 有值即认为「调用方已经给到了定位参数」，可以进入拦截而不是先报缺参。 */
+const has = (v) => str(v) !== '';
+export const DESTRUCTIVE_ACTIONS = {
+    github_pr: {
+        // 默认检出不带 -f；只有显式 force 才需要二次确认（会丢弃本地未推送提交）
+        checkout: {
+            when: (a) => a.force === true,
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ force 会把本地分支重置到 PR #${str(a.pr_number)} 的最新状态，丢弃本地未推送的提交。`,
+                impact: '重置后本地分支与 PR 头一致，本地独有提交只能通过 git reflog 找回。',
+                requiredAction: '如确认重置，请附加 `force: true, confirm: true` 重新调用。',
+            }),
+        },
+        merge: {
+            // 缺 pr_number 时旧实现先抛「merge 操作必须提供 pr_number」；闸门前移后必须自己把
+            // 这条前置校验编码进 when，否则会返回一个「PR #」空号的确认载荷（实测）。
+            when: (a) => has(a.pr_number),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 高危操作拦截：你即将合并 PR #${str(a.pr_number)}（合并策略: ${a.merge_method || 'squash'}${a.delete_branch ? '，且删除源分支' : ''}）。`,
+                impact: '合并操作将直接向基准分支写入代码并更新远端 PR 状态。',
+                requiredAction: '如确认执行合并，请向用户明确确认并附加 `confirm: true` 重新调用。',
+            }),
+        },
+        revert: {
+            when: (a) => has(a.pr_number),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 高危操作拦截：你即将对 PR #${str(a.pr_number)} 创建反向提交（revert）。`,
+                impact: '将在远端创建反向提交并生成新的 revert PR——这是新增远端实体，不是本地操作。',
+                requiredAction: '如确认执行，请向用户明确确认并附加 `confirm: true` 重新调用。',
+            }),
+        },
+    },
+    github_issue: {
+        close: {
+            // 缺 issue_number 时旧实现先抛「close 操作必须提供 issue_number」
+            when: (a) => has(a.issue_number),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 高危操作拦截：你即将关闭 Issue #${str(a.issue_number)}。`,
+                impact: '关闭后该议题状态将变更为 CLOSED，请与用户确认是否确实已解决或需要关闭。',
+                requiredAction: '如确认关闭，请在参数中附加 `confirm: true` 重新调用。',
+            }),
+        },
+        delete: {
+            // 缺 issue_number 时旧实现先抛「delete 操作必须提供 issue_number」
+            when: (a) => has(a.issue_number),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 高危操作拦截：你即将**物理删除** Issue #${str(a.issue_number)}（非 close，不可恢复）。`,
+                impact: 'Issue 编号将永久消失，全部评论与附件随之湮灭，GraphQL 层无法恢复——这与 close（可 reopen 逆转）有本质区别。',
+                requiredAction: '如确认删除，请与用户核实后附加 `confirm: true` 重新调用。',
+            }),
+        },
+        transfer: {
+            // 旧实现按 issue_number → target_repo → 同仓 的顺序抛错；前两条要在这里保住，
+            // 同仓校验依赖运行时解析出的 repoTarget，只能在工具内（confirm 之后）暴露。
+            when: (a) => has(a.issue_number) && has(a.target_repo),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 高危操作拦截：你即将把 Issue #${str(a.issue_number)} 迁移到 ${str(a.target_repo)}。`,
+                impact: `迁移后 Issue 归属 ${str(a.target_repo)}（原 URL 301 重定向），标签/里程碑不随迁，操作不可静默撤回。需要目标仓库的写权限。`,
+                requiredAction: '如确认迁移，请与用户核实后附加 `confirm: true` 重新调用。',
+            }),
+        },
+    },
+    github_release: {
+        // 原实现先校验 tag / assets 再判 clobber，条件里一并带上，避免缺参时先拿到确认提示
+        upload: {
+            when: (a) => a.clobber === true && has(a.tag) && Array.isArray(a.assets) && a.assets.length > 0,
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 高危操作拦截：你即将覆盖上传 Release ${str(a.tag)} 的同名旧资产（clobber 模式）。`,
+                impact: 'clobber 会先删除既有同名资产再上传；若上传中途失败，旧资产已丢失且无法恢复。',
+                requiredAction: '如确认覆盖，请向用户核实并附加 `confirm: true` 重新调用。',
+            }),
+        },
+        delete: {
+            when: (a) => has(a.tag),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 高危操作拦截：你即将删除 Release ${str(a.tag)}${a.cleanup_tag ? ' 及其 Git Tag' : ''}。`,
+                impact: '删除 Release 不可逆；若同时清理 Tag，引用该 Tag 的历史版本入口将全部失效。',
+                requiredAction: '如确认删除，请与用户核实并附加 `confirm: true` 重新调用。',
+            }),
+        },
+    },
+    github_secret: {
+        delete: {
+            when: (a) => has(a.name),
+            describe: (a) => {
+                // 与旧实现同口径：kind === 'variable' 时按 Variable 措辞，否则按 Secret
+                const isVariable = a.kind === 'variable';
+                const kindLabel = isVariable ? 'Variable' : 'Secret';
+                return {
+                    status: GATE_BLOCKED,
+                    warning: `⚠️ 高危操作拦截：你即将删除 ${kindLabel}「${str(a.name)}」${a.org ? `（组织 ${str(a.org)}）` : ''}。`,
+                    impact: isVariable
+                        ? '删除后所有引用该变量的工作流将取不到值，运行中的构建立即失败。'
+                        : '删除后所有引用该密钥的 CI/CD 工作流将立即无法取到值，运行中的构建会失败。',
+                    requiredAction: '如确认删除，请向用户核实并附加 `confirm: true` 重新调用。',
+                };
+            },
+        },
+    },
+    github_label: {
+        delete: {
+            when: (a) => has(a.name),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                action: 'delete',
+                name: a.name,
+                warning: `⚠️ 高危破坏性操作：即将删除仓库标签 "${str(a.name)}"`,
+                impact: '删除标签不可逆，且会导致目标仓库内所有已打上该标签的 Issue 与 PR 自动解绑该标记。',
+                requiredAction: `如确认彻底删除，请在参数中附加 \`confirm: true\` 重新调用。示例：\`github_label(action: 'delete', name: '${str(a.name)}', confirm: true)\``,
+            }),
+        },
+    },
+    github_cache: {
+        // 三条删除分支共用一套 confirm 语义。选择器缺失时原实现会抛「必须指定…」，
+        // 这里 predicate 为 false，把精确报错留给工具本体，不用泛化文案顶替。
+        delete: {
+            when: (a) => a.all === true || has(a.cache_id) || has(a.key),
+            describe: (a) => {
+                const cacheIdStr = str(a.cache_id);
+                const keyStr = str(a.key);
+                const hasAll = a.all === true;
+                // 分支判定与工具本体的归一化同口径：cache_id 非空即按 ID 删除，否则按 key
+                const byId = cacheIdStr !== '';
+                const targetDesc = hasAll
+                    ? '清空该仓库的所有 GitHub Actions 构建缓存'
+                    : byId
+                        ? `删除仓库中 ID 为 "${cacheIdStr}" 的构建缓存`
+                        : `删除仓库中 Key 为 "${keyStr}" 的构建缓存`;
+                return {
+                    status: GATE_BLOCKED,
+                    action: 'delete',
+                    ...(hasAll ? { all: true } : byId ? { cache_id: cacheIdStr } : { key: keyStr }),
+                    warning: `⚠️ 高危破坏性操作：即将${targetDesc}`,
+                    impact: '删除构建缓存不可逆，会导致后续流水线构建无法复用依赖与构建产物，显著增加 CI 运行耗时。',
+                    requiredAction: '如确认删除，请在参数中附加 `confirm: true` 重新调用。',
+                };
+            },
+        },
+    },
+    github_codespace: {
+        delete: {
+            when: (a) => has(a.codespace),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 销毁确认拦截：你即将永久删除云端开发环境「${str(a.codespace)}」。`,
+                impact: '物理销毁 Codespace 将永久释放云端计算资源，环境中任何未提交并推送到远端 Git 的临时修改都将无法找回。',
+                requiredAction: '如确认销毁该实例，请核对环境名称并在参数中附加 `confirm: true` 重新调用。',
+            }),
+        },
+    },
+    github_gist: {
+        delete: {
+            when: (a) => has(a.gist_id),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                action: 'delete',
+                gist_id: str(a.gist_id),
+                warning: `⚠️ 高危破坏性操作：即将永久删除 Gist 代码片段 "${str(a.gist_id)}"`,
+                impact: '删除 Gist 为物理删除，无法通过 GitHub API 恢复，所有引用该 Gist URL 的外部链接将失效并返回 404。',
+                requiredAction: `如确认彻底删除，请在参数中附加 \`confirm: true\` 重新调用。示例：\`github_gist(action: 'delete', gist_id: '${str(a.gist_id)}', confirm: true)\``,
+            }),
+        },
+    },
+    github_project: {
+        'item-delete': {
+            when: (a) => has(a.item_id),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 删除确认拦截：你即将从看板中删除条目（ID: ${str(a.item_id)}）。`,
+                impact: '该操作将从项目看板中物理移除该条目（若是关联的 Issue/PR，实体不会被删除，仅解除看板关联）。',
+                requiredAction: '如确认删除，请在参数中附加 `confirm: true` 重新调用。',
+            }),
+        },
+    },
+    github_skill: {
+        install: {
+            when: (a) => has(a.repository),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 安装确认拦截：你即将从仓库「${str(a.repository)}」安装 Skill${a.skill_name ? `「${str(a.skill_name)}」` : ''}到本地${a.scope === 'user' ? '用户主目录（全局）' : '当前项目'}。`,
+                impact: '安装会在本地磁盘写入 SKILL.md 及附属文件，并可能影响目标 Agent 宿主的默认行为。',
+                requiredAction: '如确认安装，请向用户核实并附加 `confirm: true` 重新调用。',
+            }),
+        },
+        // 只在「正式发布」分支拦截：dry_run 缺省为真（预演），fix 模式也是本地产物修复。
+        // 原实现先校验 tag，这里一并带上，缺 tag 仍由工具本体抛出「必须提供版本 tag」。
+        publish: {
+            when: (a) => a.dry_run === false && a.fix !== true && has(a.tag),
+            describe: (a) => {
+                const cleanTag = str(a.tag);
+                return {
+                    status: GATE_BLOCKED,
+                    warning: `⚠️ 发布确认拦截：你即将正式发布 Agent Skill 并创建 GitHub Release（Tag: ${cleanTag}）。`,
+                    impact: `该操作将在仓库中打上「agent-skills」Topic、创建 Git Tag「${cleanTag}」并发布正式 GitHub Release，向所有用户公开提供该版本。`,
+                    requiredAction: `如确认发布，请核实版本号并在参数中附加 \`confirm: true\` 重新调用。`,
+                };
+            },
+        },
+    },
+    /*
+     * 任务级原语（s8）：默认只读，唯一会写远端的是 review_pr 的 write 模式。
+     *
+     * 为什么 when 要判 `write === true`：`review_pr` 默认只产出上下文包（不写回），
+     * 若恒拦，Agent 连"看一眼这个 PR 该审什么"都要先确认一次，闸门就变成了噪音。
+     */
+    github_task: {
+        review_pr: {
+            when: (a) => a.write === true && has(a.pr_number),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 写回拦截：你即将向 PR #${str(a.pr_number)} 提交一条公开可见的 Review（含行级评注）。`,
+                impact: '该 Review 会立即出现在 PR 时间线上并通知相关人，删除只能逐条进行。',
+                requiredAction: '如确认写回，请附加 `write: true, confirm: true` 重新调用；只想看结论请去掉 `write`。',
+            }),
+        },
+    },
+};
+/**
+ * 统一闸门：命中则返回拦截载荷，否则返回 undefined。
+ *
+ * `confirm === true` 的判定放在这里而不是每个 describe 里——15 份重复的
+ * `if (args.confirm !== true)` 正是这次要消掉的东西。
+ */
+export function guardDestructive(toolName, args) {
+    const table = DESTRUCTIVE_ACTIONS[toolName];
+    if (!table)
+        return undefined;
+    const action = typeof args?.action === 'string' ? args.action : '';
+    // 必须挡原型链：`action: "toString"` 会让 table[action] 命中原型上的函数，
+    // spec.describe 不是函数直接 TypeError（复核报告 C-05，11 工具 × 16 组合全崩）。
+    const spec = Object.prototype.hasOwnProperty.call(table, action) ? table[action] : undefined;
+    if (!spec)
+        return undefined;
+    if (args?.confirm === true)
+        return undefined;
+    if (spec.when && !spec.when(args))
+        return undefined;
+    return spec.describe(args);
+}
+/**
+ * 用闸门包一层 execute（注册期唯一入口）。
+ *
+ * 为什么包在注册期而不是 `executor.run()`：`run()` 只看得见 argv，看不见
+ * `action` / `confirm` 语义。把语义解析塞进 argv 层就是把简单问题复杂化。
+ *
+ * 保持 `name` / `description` / `parameters` / `output` 原样，只替换 `execute`，
+ * 宿主侧的 schema 校验与渲染链路完全不受影响。
+ */
+export function wrapWithGate(tool) {
+    return {
+        ...tool,
+        async execute(args, ctx) {
+            const gate = guardDestructive(tool.name, args);
+            if (gate)
+                return gate;
+            return tool.execute(args, ctx);
+        },
+    };
+}

package/lib/executor/args-guard.d.ts

@@ -0,0 +1,17 @@
+/**
+ * gh argv 的「位置参数」守卫。
+ *
+ * 为什么需要它：`gh` 用 cobra/pflag 解析 argv，"以 - 开头的 token" 一律优先当
+ * 选项。工具把用户输入直接 push 成**位置参数**时，`pr_number: "--force"` 会变成
+ * `gh pr checkout --force`——破坏性闸门判的是**参数**，而危险在 **argv**，
+ * 两者不在同一层（复核报告 C-01 的三条绕过全是这个形状）。
+ *
+ * 为什么只拒绝 `-` 开头而不是做全量字符白名单：
+ * 各工具的位置参数语义差异很大（编号是数字、名字是任意非空串、路径可以有斜杠），
+ * 统一白名单会误伤合法输入；而"不能是选项"是所有位置参数**共有**的唯一硬约束。
+ * 具体格式（正整数 / owner-repo / 数字 ID）仍由各工具自己的校验负责。
+ *
+ * 空值不在此处报错：调用方各自的「必须提供 X」文案更准确，这里越俎代庖会把
+ * 两个不同原因的错误合并成一个，反而降低可诊断性。
+ */
+export declare function assertPositionArg(value: unknown, label: string): string;

package/lib/executor/args-guard.js

@@ -0,0 +1,23 @@
+/**
+ * gh argv 的「位置参数」守卫。
+ *
+ * 为什么需要它：`gh` 用 cobra/pflag 解析 argv，"以 - 开头的 token" 一律优先当
+ * 选项。工具把用户输入直接 push 成**位置参数**时，`pr_number: "--force"` 会变成
+ * `gh pr checkout --force`——破坏性闸门判的是**参数**，而危险在 **argv**，
+ * 两者不在同一层（复核报告 C-01 的三条绕过全是这个形状）。
+ *
+ * 为什么只拒绝 `-` 开头而不是做全量字符白名单：
+ * 各工具的位置参数语义差异很大（编号是数字、名字是任意非空串、路径可以有斜杠），
+ * 统一白名单会误伤合法输入；而"不能是选项"是所有位置参数**共有**的唯一硬约束。
+ * 具体格式（正整数 / owner-repo / 数字 ID）仍由各工具自己的校验负责。
+ *
+ * 空值不在此处报错：调用方各自的「必须提供 X」文案更准确，这里越俎代庖会把
+ * 两个不同原因的错误合并成一个，反而降低可诊断性。
+ */
+export function assertPositionArg(value, label) {
+    const raw = typeof value === 'number' ? String(value) : String(value ?? '').trim();
+    if (raw.startsWith('-')) {
+        throw new Error(`${label} 非法：位置参数不能以 "-" 开头（收到 "${raw}"），它会被 gh 当成命令行选项而不是取值。`);
+    }
+    return raw;
+}

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` 查看作用域，或请仓库管理员提升权限。';
+}