dsh-github-flow 0.1.8 → 0.2.1

package/lib/commands/gh.js

@@ -1,4 +1,5 @@
 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) {
     if (!commandsService || typeof commandsService.register !== 'function')
         return;
@@ -53,12 +54,20 @@ export function registerGhCommand(commandsService, executor, updateChecker) {
                 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`;
-                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`;
+                // 官方 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`;
                 }

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

@@ -1,9 +1,87 @@
-import { execFile } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import fs from 'node:fs';
 import path from 'node:path';
 import { findMostRecentWorkspacePath, findWorkspacePathBySession, hasGitDir } from './workspace.js';
 const execFileAsync = promisify(execFile);
+/**
+ * spawn 形态的执行通道（stdin 可选注入）。
+ *
+ * 为什么存在：execFile 的 input 选项在本机（node 22.18.0 + Windows）实测从不写入
+ * 子进程 stdin——既无数据也无 EOF，管道永久悬空（gh secret set 等需要 stdin 的
+ * 命令会一直等到超时）。最小复现：execFile+input 对 `cmd /c more` 与 node 子进程
+ * 均挂起；而 spawn + stdin.end(data) 全部正常。此函数即为后者的工程化封装，
+ * 仅在调用方显式传入 stdin 时使用，其余路径保持 execFileAsync 零改动。
+ *
+ * 为什么超时要自己管：spawn 无 timeout 选项，用 kill + SIGTERM 兜底；
+ * 输出按 maxBuffer 手工聚合（上限与 execFile 路径一致，15MB）。
+ */
+function spawnWithStdin(ghPath, args, opts) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(ghPath, args, {
+            cwd: opts.cwd,
+            env: opts.env,
+            windowsHide: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const outChunks = [];
+        const errChunks = [];
+        let totalBytes = 0;
+        let killed = false;
+        let settled = false;
+        const timer = setTimeout(() => {
+            killed = true;
+            child.kill();
+        }, opts.timeout);
+        const settle = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (err)
+                reject(err);
+            else
+                resolve({ stdout: Buffer.concat(outChunks), stderr: Buffer.concat(errChunks), killed });
+        };
+        // 聚合上限：超出即杀（与 execFile maxBuffer 语义一致；gh 正常输出远小于此）
+        const MAX_BYTES = 15 * 1024 * 1024;
+        child.stdout?.on('data', (d) => {
+            totalBytes += d.length;
+            outChunks.push(d);
+            if (totalBytes > MAX_BYTES) {
+                killed = true;
+                child.kill();
+            }
+        });
+        child.stderr?.on('data', (d) => { errChunks.push(d); });
+        child.on('error', (err) => {
+            // spawn 失败（如 ENOENT）对齐 execFile 的错误形状：code 保留在 Error 上
+            const e = Object.assign(new Error(err.message), { code: err.code });
+            settle(e);
+        });
+        child.on('close', (code, signal) => {
+            if (killed) {
+                // 超时/超量被杀：对齐 execFile 的 Timeout 错误形状（err.killed + signal）
+                const e = Object.assign(new Error(`Command timed out after ${opts.timeout}ms`), { killed: true, signal: signal || 'SIGTERM' });
+                settle(e);
+                return;
+            }
+            if (code !== 0) {
+                const e = Object.assign(new Error(`Command failed with exit code ${code}`), { code, stderr: Buffer.concat(errChunks).toString('utf8').slice(0, 800) });
+                settle(e);
+                return;
+            }
+            settle();
+        });
+        // stdin 注入：end(data) 半关闭（写完即 EOF），子进程流式读取或一次性读取均可
+        child.stdin?.end(opts.stdin, (err) => {
+            if (err && !settled) {
+                const e = Object.assign(new Error(`stdin write failed: ${err.message}`), { code: 'EPIPE' });
+                settle(e);
+            }
+        });
+    });
+}
 /** 认证状态缓存时长。用户手动 `gh auth login/logout` 后最多 30 秒内面板才会反映，属可接受代价 */
 const AUTH_CACHE_TTL_MS = 30_000;
 /**
@@ -95,6 +173,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 +194,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 +211,10 @@ export class GhExecutor {
         if (config.maxOutputBytes)
             this.maxOutputBytes = config.maxOutputBytes;
     }
+    /** 注入代理管理器（main.ts 装配时调用一次；测试可注入 mock） */
+    attachProxyManager(manager) {
+        this.proxyManager = manager;
+    }
     /**
      * 智能解析最可靠的工作区物理路径：
      * 1. 优先使用显式指定的有效 cwd（若包含 .git 目录）
@@ -164,21 +263,60 @@ export class GhExecutor {
     async run(args, options = {}) {
         const cwd = this.resolveWorkspaceCwd(options.cwd, options.sessionId);
         const timeout = options.timeoutMs || this.defaultTimeoutMs;
+        // 二进制模式（如 gh api 下载图片字节流）：stdout 保持 Buffer，绕过 UTF-8
+        // 字符串转换（PNG 等二进制经 utf8 解码必然损坏），也不做截断（截断只面向
+        // 文本 Token 预算）。显式开启才生效，既有调用方零感知。
+        const binary = options.binary === true;
         try {
-            const { stdout, stderr } = await execFileAsync(this.ghPath, args, {
+            // stdin 显式传入时走 spawn 通道：execFile 的 input 选项在本机从不真正写入
+            // （详见 spawnWithStdin 注释），gh secret set 等命令会挂到超时。其余调用
+            // 保持 execFileAsync 原路径零改动。
+            const commonOpts = {
                 cwd,
-                timeout,
-                maxBuffer: 15 * 1024 * 1024, // 15MB 进程缓冲
                 env: {
                     ...process.env,
                     GH_NO_UPDATE_NOTIFIER: '1', // 禁用 CLI 版本更新检查，避免污染 stdout
                     NO_COLOR: '1', // 禁用 ANSI 颜色转义字符
+                    // 代理环境变量注入在 options.env 之前：调用方显式传入的 env 仍可覆盖
+                    // 代理（保持 options.env 的既有语义优先级），正常调用方不传则代理生效。
+                    ...(this.proxyManager?.getEnv('gh') || {}),
                     ...options.env,
                 },
-            });
-            let rawOutput = (stdout || '').trim();
-            if (!rawOutput && stderr) {
-                rawOutput = stderr.trim();
+            };
+            let stdout;
+            let stderr;
+            if (options.stdin !== undefined) {
+                const r = await spawnWithStdin(this.ghPath, args, { ...commonOpts, timeout, stdin: options.stdin });
+                stdout = r.stdout;
+                stderr = r.stderr;
+            }
+            else {
+                const r = await execFileAsync(this.ghPath, args, {
+                    ...commonOpts,
+                    timeout,
+                    maxBuffer: 15 * 1024 * 1024, // 15MB 进程缓冲
+                    ...(binary ? { encoding: 'buffer' } : {}),
+                });
+                stdout = r.stdout;
+                stderr = r.stderr;
+            }
+            // 二进制通道：Buffer 原样返回（调用方自行写文件/校验魔数），stderr 仅作
+            // 错误线索不做输出回退——把错误提示字节当图片保存毫无意义。
+            // TS 无法从 options 展开的 encoding 键收窄 stdout 类型，这里显式归一化。
+            if (binary) {
+                const buf = Buffer.isBuffer(stdout) ? stdout : Buffer.from(String(stdout ?? ''));
+                const errBuf = Buffer.isBuffer(stderr) ? stderr : (stderr ? Buffer.from(String(stderr)) : null);
+                if (!buf.length) {
+                    const errMsg = errBuf ? errBuf.toString('utf8').trim() : '';
+                    return { ok: false, error: errMsg || '二进制输出为空' };
+                }
+                return { ok: true, data: buf, binaryBytes: buf.length, truncated: false };
+            }
+            const outText = Buffer.isBuffer(stdout) ? stdout.toString('utf8') : String(stdout ?? '');
+            const errText = Buffer.isBuffer(stderr) ? stderr.toString('utf8') : String(stderr ?? '');
+            let rawOutput = outText.trim();
+            if (!rawOutput && errText) {
+                rawOutput = errText.trim();
             }
             const outcome = truncateOutput(rawOutput, this.maxOutputChars, this.maxOutputBytes);
             rawOutput = outcome.text;

package/lib/main.d.ts

@@ -30,4 +30,5 @@ 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,11 +4,17 @@ 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';
+import { loadUpdateSettings } from './update-settings.js';
 // 引用即生效：加载本模块以挂上 declare module '@deepseek-ai/cordis' 的 ctx.github 类型声明，
 // 并随下面 `export * from './github-service.js'` 一起传给消费方。
 import './github-service.js';
@@ -41,6 +47,7 @@ export const Config = {
                     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,
                 }
             };
         }
@@ -48,11 +55,26 @@ 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,
+        // checkUpdate: false 熔断全部探测入口（路由/命令/启动横幅共用此实例）
+        enabled: config.checkUpdate !== false,
     });
+    // 更新源设置（UI 持久化 store 优先于 Cordis 静态配置）：
+    // 启动时读取并应用到 checker；UI 保存时经路由直接调 applySettings 热切换。
+    const updateMode = loadUpdateSettings();
+    updateChecker.applySettings(updateMode);
+    updateChecker.applyProxy(proxyManager);
     const upgradeManager = new UpgradeManager();
+    upgradeManager.attachProxyManager(proxyManager);
+    // 注入查询函数而非静态值：用户切源后，下一次一键升级的 registry 实时跟随
+    upgradeManager.attachUpdateModeQuery(() => updateChecker.getSourceMode());
     // 1. 兑现生态服务契约：将 GitHub 执行引擎作为服务暴露给其他 DSH 插件 (ctx.github)
     if (ctx.provide && typeof ctx.provide === 'function') {
         ctx.provide('github', executor);
@@ -64,35 +86,52 @@ export function apply(ctx, config = {}) {
     if (ctx.commands) {
         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, updateChecker, upgradeManager);
+        // proxyManager 传入以挂载 /api/github/proxy* 设置路由（驾驶舱代理设置入口）。
+        registerApiRoutes(ctx, executor, ctx.workspaceRegistry, config.cacheTtlMs || 15_000, updateChecker, upgradeManager, proxyManager);
     }
     // 5. 启动后低优先级后台闲时静默探测：若有新版本，仅输出一次友好的控制台提示
     if (config.checkUpdate !== false) {
-        setTimeout(() => {
-            updateChecker.check(false).then((info) => {
-                if (info.hasUpdate) {
-                    console.log(`
+        // 包裹在 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);
+                    }
+                }).catch(() => { });
+            }, 3_000);
+            return () => clearTimeout(timer);
+        };
+        if (typeof ctx.effect === 'function') {
+            ctx.effect(scheduleProbe);
+        }
+        else {
+            scheduleProbe();
+        }
     }
 }
 export * from './types.js';
@@ -100,5 +139,6 @@ 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;
+}