dsh-github-flow 0.1.7 → 0.2.0

package/lib/commands/gh.d.ts

@@ -1,2 +1,3 @@
 import type { GhExecutor } from '../executor.js';
-export declare function registerGhCommand(commandsService: any, executor: GhExecutor): void;
+import type { UpdateChecker } from '../updater.js';
+export declare function registerGhCommand(commandsService: any, executor: GhExecutor, updateChecker?: UpdateChecker): void;

package/lib/commands/gh.js

@@ -1,4 +1,5 @@
-export function registerGhCommand(commandsService, executor) {
+import { CURRENT_PLUGIN_VERSION, PLUGIN_PACKAGE_NAME, NPM_PACKAGE_URL } from '../version.js';
+export function registerGhCommand(commandsService, executor, updateChecker) {
     if (!commandsService || typeof commandsService.register !== 'function')
         return;
     commandsService.register({
@@ -11,7 +12,14 @@ export function registerGhCommand(commandsService, executor) {
                 // 「我刚 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`;
@@ -35,15 +43,44 @@ export function registerGhCommand(commandsService, executor) {
                     text: md,
                 };
             }
+            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`;
+                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 官方标准工程升级（推荐）**:\n\`\`\`bash\npnpm dsh plugin add ${PLUGIN_PACKAGE_NAME}@latest\n\`\`\`\n\n`;
+                md += `2. **DSH 桌面版 Profile 环境升级**:\n\`\`\`bash\ndsh plugin --profile desktop 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 {
+                    kind: 'success',
+                    text: md,
+                };
+            }
             if (trimmed === 'help') {
                 return {
                     kind: 'success',
-                    text: `### DSH GitHub Flow 帮助\n\n- \`/gh status\`: 检查当前 GitHub CLI 账号与仓库连接\n- \`/gh help\`: 显示此帮助信息\n\n可以在对话中直接让 Agent 操作 GitHub，如：\n- *"查看当前仓库有哪些开放的 PR"* \n- *"查看最近一次 CI 失败的原因"* \n- *"帮我给当前分支创建 PR"*`,
+                    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"*`,
                 };
             }
             return {
                 kind: 'error',
-                text: `未知命令选项: /gh ${trimmed}。可用用法: /gh status, /gh help`,
+                text: `未知命令选项: /gh ${trimmed}。可用用法: /gh status, /gh upgrade, /gh help`,
             };
         },
     });

package/lib/executor.d.ts

@@ -1,4 +1,5 @@
 import type { GhExecutionOptions, GhResult, AuthStatus, RepoMetadata, PluginConfig } from './types.js';
+import type { ProxyManager } from './proxy.js';
 /**
  * 按「字符数 + UTF-8 字节数」双口径截断输出。
  * 抽成纯函数是刻意的：截断逻辑是崩溃高发区（切碎多字节字符、误伤 JSON、把二进制流截成垃圾），
@@ -14,10 +15,26 @@ export declare class GhExecutor {
     maxOutputChars: number;
     /** UTF-8 字节口径的硬上限；未配置时按 maxOutputChars × 4 推导（覆盖 CJK 3 字节与 emoji 4 字节） */
     maxOutputBytes: number;
+    /**
+     * 列表类查询的默认条数上限。
+     * 为什么挂在 executor 而不是给每个工具工厂加 config 参数：executor 是全部
+     * 工具共享的依赖注入点，配置语义本就属于「执行层默认值」；工厂签名零改动，
+     * 且热更新路径 updateConfig 能同步刷新。工具内以 `?? 20` 兜底保证旧配置兼容。
+     */
+    defaultListLimit: number;
+    /**
+     * 代理管理器引用（可选依赖）。
+     * 注入后每次 gh 子进程拉起都会合并代理环境变量——这是「工具调用 + Web 页面数据
+     * 全部走代理」的唯一咽喉（两条链路共用本 executor）。未注入时零干预，
+     * gh 自然继承宿主系统环境变量（系统级代理或直连），即「默认走系统设置」语义。
+     */
+    private proxyManager?;
     /** 认证状态缓存。`gh auth status` 实测 5.4 秒，而它位于全局驾驶舱关键路径的最前面 */
     private authCache;
     constructor(config?: PluginConfig);
     updateConfig(config?: PluginConfig): void;
+    /** 注入代理管理器（main.ts 装配时调用一次；测试可注入 mock） */
+    attachProxyManager(manager: ProxyManager): void;
     /**
      * 智能解析最可靠的工作区物理路径：
      * 1. 优先使用显式指定的有效 cwd（若包含 .git 目录）

package/lib/executor.js

@@ -95,6 +95,20 @@ export class GhExecutor {
     maxOutputChars;
     /** UTF-8 字节口径的硬上限；未配置时按 maxOutputChars × 4 推导（覆盖 CJK 3 字节与 emoji 4 字节） */
     maxOutputBytes;
+    /**
+     * 列表类查询的默认条数上限。
+     * 为什么挂在 executor 而不是给每个工具工厂加 config 参数：executor 是全部
+     * 工具共享的依赖注入点，配置语义本就属于「执行层默认值」；工厂签名零改动，
+     * 且热更新路径 updateConfig 能同步刷新。工具内以 `?? 20` 兜底保证旧配置兼容。
+     */
+    defaultListLimit;
+    /**
+     * 代理管理器引用（可选依赖）。
+     * 注入后每次 gh 子进程拉起都会合并代理环境变量——这是「工具调用 + Web 页面数据
+     * 全部走代理」的唯一咽喉（两条链路共用本 executor）。未注入时零干预，
+     * gh 自然继承宿主系统环境变量（系统级代理或直连），即「默认走系统设置」语义。
+     */
+    proxyManager;
     /** 认证状态缓存。`gh auth status` 实测 5.4 秒，而它位于全局驾驶舱关键路径的最前面 */
     authCache = null;
     constructor(config = {}) {
@@ -102,12 +116,15 @@ export class GhExecutor {
         this.defaultTimeoutMs = config.defaultTimeoutMs || 30_000;
         this.maxOutputChars = config.maxOutputChars || 24_000;
         this.maxOutputBytes = config.maxOutputBytes || this.maxOutputChars * 4;
+        this.defaultListLimit = config.defaultListLimit || 20;
     }
     updateConfig(config = {}) {
         if (config.ghPath)
             this.ghPath = config.ghPath;
         if (config.defaultTimeoutMs)
             this.defaultTimeoutMs = config.defaultTimeoutMs;
+        if (config.defaultListLimit)
+            this.defaultListLimit = config.defaultListLimit;
         if (config.maxOutputChars) {
             this.maxOutputChars = config.maxOutputChars;
             if (!config.maxOutputBytes)
@@ -116,6 +133,10 @@ export class GhExecutor {
         if (config.maxOutputBytes)
             this.maxOutputBytes = config.maxOutputBytes;
     }
+    /** 注入代理管理器（main.ts 装配时调用一次；测试可注入 mock） */
+    attachProxyManager(manager) {
+        this.proxyManager = manager;
+    }
     /**
      * 智能解析最可靠的工作区物理路径：
      * 1. 优先使用显式指定的有效 cwd（若包含 .git 目录）
@@ -173,8 +194,15 @@ export class GhExecutor {
                     ...process.env,
                     GH_NO_UPDATE_NOTIFIER: '1', // 禁用 CLI 版本更新检查，避免污染 stdout
                     NO_COLOR: '1', // 禁用 ANSI 颜色转义字符
+                    // 代理环境变量注入在 options.env 之前：调用方显式传入的 env 仍可覆盖
+                    // 代理（保持 options.env 的既有语义优先级），正常调用方不传则代理生效。
+                    ...(this.proxyManager?.getEnv('gh') || {}),
                     ...options.env,
                 },
+                // 仅在显式传入 stdin 时附加 input 键：promisified execFile 会把 input
+                // 写入子进程 stdin 后立即结束流。不传则保持既有行为（继承/null 句柄），
+                // 确保对全部既有调用方零破坏。
+                ...(options.stdin !== undefined ? { input: options.stdin } : {}),
             });
             let rawOutput = (stdout || '').trim();
             if (!rawOutput && stderr) {
@@ -269,7 +297,18 @@ export class GhExecutor {
     async probeAuth(cwd) {
         const res = await this.run(['auth', 'status'], { cwd, timeoutMs: 10_000, rawText: true });
         const raw = (res.rawOutput || '') + '\n' + (res.error || '');
-        const loggedIn = raw.includes('Logged in to') || raw.includes('✓');
+        // 多重维度强健判定登录态 (容错 Windows Unicode 乱码、Keyring 告警与不同版本 CLI 输出差分)
+        const hasLoggedInFlag = /logged\s+in\s+to/i.test(raw) || raw.includes('✓') || raw.includes('√');
+        const hasActiveFlag = /active\s+account:\s*true/i.test(raw);
+        const hasTokenFlag = raw.includes('Token:') || raw.includes('Token scopes:');
+        const accountMatch = raw.match(/account\s+([A-Za-z0-9_-]+)/i);
+        const hasAccount = Boolean(accountMatch && accountMatch[1] && accountMatch[1].toLowerCase() !== 'none');
+        // 显式未登录特征排查
+        const isExplicitlyLoggedOut = /not\s+logged\s+in/i.test(raw) ||
+            raw.includes('gh auth login') ||
+            raw.includes('authentication required') ||
+            raw.includes('No accounts found');
+        const loggedIn = !isExplicitlyLoggedOut && (hasLoggedInFlag || hasActiveFlag || (hasTokenFlag && hasAccount));
         // 只要已登录或有常规输出，则必然安装了 gh
         const isNotInstalled = Boolean(res.error && (res.error.includes('系统未检测到 GitHub CLI') || res.error.includes('ENOENT')));
         const installed = loggedIn || !isNotInstalled;
@@ -292,7 +331,6 @@ export class GhExecutor {
         }
         // 解析用户名
         let user;
-        const accountMatch = raw.match(/account\s+([A-Za-z0-9_-]+)/i);
         if (accountMatch) {
             user = accountMatch[1];
         }

package/lib/main.d.ts

@@ -2,6 +2,13 @@ import { GhExecutor } from './executor.js';
 import './github-service.js';
 import type { PluginConfig } from './types.js';
 export declare const name = "dsh-github-flow";
+/**
+ * 核心服务依赖声明
+ *
+ * 必须显式声明 webServer 与 workspaceRegistry：
+ * 在 Cordis 依赖隔离机制下，只有在 inject 显式声明的服务，当前插件作用域 ctx 才能持有
+ * ctx.webServer 与 ctx.workspaceRegistry 引用，进而注册 Web UI 所需的后端 API 路由。
+ */
 export declare const inject: readonly ['tools', 'commands', 'webServer', 'workspaceRegistry'];
 export type Config = PluginConfig;
 /**
@@ -19,4 +26,9 @@ export declare const Config: {
 export declare function apply(ctx: any, config?: PluginConfig): void;
 export type GitHubService = GhExecutor;
 export * from './types.js';
+export * from './version.js';
+export * from './updater.js';
+export * from './upgrade-manager.js';
+export * from './executor.js';
+export * from './proxy.js';
 export * from './github-service.js';

package/lib/main.js

@@ -4,12 +4,27 @@ import { createIssueTool } from './tools/issue.js';
 import { createRunTool } from './tools/run.js';
 import { createRepoTool } from './tools/repo.js';
 import { createApiTool } from './tools/api.js';
+import { createReleaseTool } from './tools/release.js';
+import { createSecretTool } from './tools/secret.js';
+import { createSkillTool } from './tools/skill.js';
+import { createHelpTool } from './tools/help.js';
 import { registerGhCommand } from './commands/gh.js';
 import { registerApiRoutes } from './api/routes.js';
+import { UpdateChecker } from './updater.js';
+import { UpgradeManager } from './upgrade-manager.js';
+import { ProxyManager } from './proxy.js';
+import { NPM_PACKAGE_URL } from './version.js';
 // 引用即生效：加载本模块以挂上 declare module '@deepseek-ai/cordis' 的 ctx.github 类型声明，
 // 并随下面 `export * from './github-service.js'` 一起传给消费方。
 import './github-service.js';
 export const name = 'dsh-github-flow';
+/**
+ * 核心服务依赖声明
+ *
+ * 必须显式声明 webServer 与 workspaceRegistry：
+ * 在 Cordis 依赖隔离机制下，只有在 inject 显式声明的服务，当前插件作用域 ctx 才能持有
+ * ctx.webServer 与 ctx.workspaceRegistry 引用，进而注册 Web UI 所需的后端 API 路由。
+ */
 export const inject = ['tools', 'commands', 'webServer', 'workspaceRegistry'];
 /**
  * 符合 Standard Schema / Cordis Loader 契约的 Config 运行时校验规范
@@ -28,6 +43,10 @@ export const Config = {
                     maxOutputBytes: typeof cfg.maxOutputBytes === 'number' ? cfg.maxOutputBytes : undefined,
                     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,
+                    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,
                 }
             };
         }
@@ -35,6 +54,18 @@ export const Config = {
 };
 export function apply(ctx, config = {}) {
     const executor = new GhExecutor(config);
+    // 代理管理器：优先读取用户在驾驶舱保存的 proxy.json，回落 cordis.patch.yml 的
+    // proxyUrl 预置值；两者皆无时保持直连（gh 自然继承宿主系统环境变量）。
+    // 装配后 executor/upgradeManager/updater 三条外联链路全部经它路由。
+    const proxyManager = new ProxyManager(config.proxyUrl);
+    executor.attachProxyManager(proxyManager);
+    const updateChecker = new UpdateChecker({
+        intervalMs: config.updateCheckIntervalMs,
+        customRegistry: config.registryUrl,
+    });
+    updateChecker.applyProxy(proxyManager);
+    const upgradeManager = new UpgradeManager();
+    upgradeManager.attachProxyManager(proxyManager);
     // 1. 兑现生态服务契约：将 GitHub 执行引擎作为服务暴露给其他 DSH 插件 (ctx.github)
     if (ctx.provide && typeof ctx.provide === 'function') {
         ctx.provide('github', executor);
@@ -42,25 +73,63 @@ export function apply(ctx, config = {}) {
     else {
         ctx.github = executor;
     }
-    // 2. 注册人类 Slash 命令 (/gh status, /gh help)
+    // 2. 注册人类 Slash 命令 (/gh status, /gh upgrade, /gh help)
     if (ctx.commands) {
-        registerGhCommand(ctx.commands, executor);
+        registerGhCommand(ctx.commands, executor, updateChecker);
     }
-    // 3. 注册 Agent 模型工具集（5 大核心领域工具）
+    // 3. 注册 Agent 模型工具集（核心领域工具 + 元指南）
     if (ctx.tools) {
         ctx.tools.register(createPrTool(executor));
         ctx.tools.register(createIssueTool(executor));
         ctx.tools.register(createRunTool(executor));
         ctx.tools.register(createRepoTool(executor));
         ctx.tools.register(createApiTool(executor));
+        ctx.tools.register(createReleaseTool(executor));
+        ctx.tools.register(createSecretTool(executor));
+        ctx.tools.register(createSkillTool(executor));
+        ctx.tools.register(createHelpTool(executor));
     }
     // 4. 注册面向 Client 端的 WebServer HTTP 路由（如果当前环境启用了 Web UI 服务）
     if (ctx.webServer) {
         // 传入 ctx 作用域对象，使 routes 能够通过 ctx.effect 绑定生命周期并在插件卸载/重载时自动注销；
         // cacheTtlMs 传给路由层以尊重用户的缓存 TTL 配置。
-        registerApiRoutes(ctx, executor, ctx.workspaceRegistry, config.cacheTtlMs || 15_000);
+        // proxyManager 传入以挂载 /api/github/proxy* 设置路由（驾驶舱代理设置入口）。
+        registerApiRoutes(ctx, executor, ctx.workspaceRegistry, config.cacheTtlMs || 15_000, updateChecker, upgradeManager, proxyManager);
+    }
+    // 5. 启动后低优先级后台闲时静默探测：若有新版本，仅输出一次友好的控制台提示
+    if (config.checkUpdate !== false) {
+        // 包裹在 ctx.effect 中（Cordis 规范）：热重载/卸载发生在 3 秒延迟窗口内时，
+        // 取消挂起的定时器，避免旧实例在新实例加载后仍向控制台打印升级横幅。
+        // 无头/测试环境缺 ctx.effect 时优雅退化为裸定时器（一次性触发，无泄漏）。
+        const scheduleProbe = () => {
+            const timer = setTimeout(() => {
+                updateChecker.check(false).then((info) => {
+                    if (info.hasUpdate) {
+                        console.log(`
+┌────────────────────────────────────────────────────────────────────────┐
+│  🚀 dsh-github-flow 插件有新版本可用: ${info.currentVersion} -> ${info.latestVersion}              │
+│  升级命令: ${info.upgradeCommand.padEnd(58, ' ')}│
+│  更新主页: ${NPM_PACKAGE_URL.padEnd(58, ' ')}│
+└────────────────────────────────────────────────────────────────────────┘
+`);
+                    }
+                }).catch(() => { });
+            }, 3_000);
+            return () => clearTimeout(timer);
+        };
+        if (typeof ctx.effect === 'function') {
+            ctx.effect(scheduleProbe);
+        }
+        else {
+            scheduleProbe();
+        }
     }
 }
 export * from './types.js';
+export * from './version.js';
+export * from './updater.js';
+export * from './upgrade-manager.js';
+export * from './executor.js';
+export * from './proxy.js';
 // 让 `ctx.github` 的类型声明随包一起被消费方加载（声明合并在 './github-service.js' 内）
 export * from './github-service.js';

package/lib/proxy.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 网络代理管理器：插件全部外联流量的唯一代理状态权威源。
+ *
+ * 设计依据（docs/plans/proxy-support-plan.md）：
+ * - gh 子进程链路（9 工具 + Web API 数据）经标准环境变量 HTTPS_PROXY/HTTP_PROXY/NO_PROXY 驱动，
+ *   实测 gh CLI 完整遵循 Go net/http 约定；
+ * - Node fetch 链路（updater 的 npm registry 探测）无视环境变量，需 undici ProxyAgent
+ *   dispatcher 驱动——插件自身不依赖 undici，运行时从 DSH 宿主 require 链动态解析；
+ * - 不走 Cordis Config 承载：配置变更会触发插件全量 reload（工具注销重注册），
+ *   而代理是高频试错型设置。持久化用独立文件，保存即生效、零重载。
+ * - 未设置时零干预：不注入任何环境变量、不动 fetch dispatcher，
+ *   gh 与 fetch 自然回落到系统环境变量（若宿主本身配置了 HTTPS_PROXY）或直连。
+ */
+export interface ProxyConfig {
+    /** 代理地址，如 "http://127.0.0.1:7890"。空串 = 未启用（回落系统环境/直连） */
+    url: string;
+    /** NO_PROXY 排除列表（逗号分隔）。localhost,127.0.0.1 恒被强制前置，防止本机 Web API 回环请求被代理劫持 */
+    noProxy: string;
+    /** 是否同步应用于 npm registry 探测与一键升级链路（包管理器走环境变量，天然支持） */
+    applyToPackageManager: boolean;
+}
+export interface ProxyProbeResult {
+    ok: boolean;
+    at: number;
+    latencyMs?: number;
+    error?: string;
+}
+export interface ProxyStateSnapshot {
+    config: ProxyConfig;
+    /** fetch 链路（undici dispatcher）是否可用。不可用时 npm 探测保持直连，GitHub 链路不受影响 */
+    fetchProxyAvailable: boolean;
+    lastProbe?: ProxyProbeResult;
+}
+/**
+ * 校验用户输入的代理地址。
+ * 为什么白名单 scheme：地址将注入到全部 gh/npm 子进程环境变量并可能驱动 fetch dispatcher，
+ * 放行 file://、gopher:// 等怪异 scheme 属于扩大攻击面；内嵌凭据会随进程 env 暴露，禁止保存。
+ */
+export declare function validateProxyUrl(input: unknown): {
+    ok: boolean;
+    url?: string;
+    error?: string;
+};
+export declare class ProxyManager {
+    private config;
+    private lastProbe;
+    private fetchProxyAvailable;
+    private activeDispatcherUrl;
+    /** 安装代理 dispatcher 前的进程默认 dispatcher 快照（关闭代理时恢复，防残留） */
+    private defaultDispatcher;
+    constructor(presetUrl?: string);
+    /** 读取持久化文件；不存在时回落 cordis.patch.yml 预置值；再无则保持默认直连 */
+    private load;
+    /**
+     * 原子写持久化文件：先写临时文件再 rename，杜绝并发/崩溃产生半截 JSON。
+     * 写盘失败（目录权限/沙箱）不抛出：代理是「尽力持久化」语义——内存态已生效，
+     * 仅丢失重启恢复能力；用一次 console.warn 提示用户，UI 仍能正常工作。
+     */
+    private persist;
+    /**
+     * 生成注入子进程的代理环境变量。
+     * 未启用时返回 {}——绝不覆盖 process.env 中既有的系统级代理设置（用户不设插件代理
+     * 时 gh 自然继承宿主环境变量，即「默认走系统设置」语义）。
+     * socks5 对 gh（Go runtime）原生有效；对 npm 同样有效（pacote/agent-base 支持）。
+     */
+    getEnv(scope?: 'gh' | 'package-manager'): Record<string, string>;
+    /**
+     * 应用 fetch dispatcher（npm registry 探测链路）。
+     * undici 的 ProxyAgent 不支持 socks5：该场景显式标记不可用并保持直连，
+     * UI 需如实提示差异（GitHub 链路正常走 socks5），不做静默降级。
+     * dispatcher 按 url 缓存重建，url 未变化时零开销。
+     *
+     * 关闭代理时必须恢复默认全局 dispatcher：setGlobalDispatcher 是进程级副作用，
+     * 若只清空本实例状态而不回滚 dispatcher，此前安装的 ProxyAgent 会永久残留，
+     * 「启用→关闭」后 npm 探测仍走死代理直到进程重启。首次安装前先快照原 dispatcher。
+     */
+    applyFetchDispatcher(): boolean;
+    /** 保存新配置并立即生效（写文件 + 重应用 dispatcher），返回完整状态快照 */
+    save(input: Partial<ProxyConfig>): {
+        ok: boolean;
+        error?: string;
+        state: ProxyStateSnapshot;
+    };
+    /** 经当前代理配置探测 GitHub API 连通性（2.5s 超时）。失败不回滚保存——离线预配置是合法场景 */
+    probe(): Promise<ProxyProbeResult>;
+    snapshot(): ProxyStateSnapshot;
+}