dsh-github-flow 0.1.8 → 0.2.1

package/lib/tools/secret.d.ts

@@ -0,0 +1,60 @@
+import type { GhExecutor } from '../executor.js';
+export declare function createSecretTool(executor: GhExecutor): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            repo: {
+                type: string;
+                description: string;
+            };
+            name: {
+                type: string;
+                description: string;
+            };
+            value: {
+                type: string;
+                description: string;
+            };
+            org: {
+                type: string;
+                description: string;
+            };
+            env: {
+                type: string;
+                description: string;
+            };
+            app: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            visibility: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            confirm: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    output: {
+        schema: {
+            type: string;
+        };
+        render(args: any, value: any): {
+            type: string;
+            text: string;
+        }[];
+    };
+    execute(args: any, execContext: any): Promise<Record<string, any>>;
+};

package/lib/tools/secret.js

@@ -0,0 +1,175 @@
+function normalizeOutput(data) {
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return { items: data, count: data.length };
+    }
+    return { result: data !== undefined && data !== null ? data : '' };
+}
+/**
+ * 渲染 secret 工具输出。
+ * 独立于 markdown.ts 渲染器的原因：这里有一条硬性安全规则——任何分支都不允许
+ * 渲染 value 字段（哪怕是调试用途）。逻辑集中在本地一眼可审，避免在通用渲染器
+ * 里混入「按字段名黑名单过滤」的隐蔽约束。
+ */
+function renderSecretOutput(args, value) {
+    if (!value)
+        return '无返回内容';
+    if (value.status === 'AWAITING_CONFIRMATION') {
+        return [
+            `> ### ${value.warning}`,
+            `> - **影响评估**: ${value.impact}`,
+            `> - **确认指引**: ${value.requiredAction}`,
+        ].join('\n');
+    }
+    if (Array.isArray(value.items) && args?.action === 'list') {
+        const list = value.items.filter(Boolean);
+        if (list.length === 0)
+            return '📭 当前仓库尚未配置任何 Secret。';
+        const rows = list.map((s) => {
+            const name = `\`${String(s.name || '-')}\``;
+            const vis = s.visibility ? String(s.visibility) : '-';
+            const date = s.updatedAt ? s.updatedAt.slice(0, 10) : '-';
+            return `| ${name} | ${vis} | ${date} |`;
+        });
+        return [
+            `**当前已配置 ${list.length} 个 Secret（仅名称，永不展示明文）:**\n`,
+            '| 密钥名称 | 可见性 | 最近更新 |',
+            '| :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    if (typeof value.message === 'string') {
+        return `**${value.message}**`;
+    }
+    return JSON.stringify(value, null, 2);
+}
+export function createSecretTool(executor) {
+    return {
+        name: 'github_secret',
+        description: '管理 GitHub Actions 仓库密钥 (Secrets)：查看已配置的密钥名称列表、设置/更新密钥值（如 NPM_TOKEN、部署密钥）。密文经标准输入安全传递，绝不出现在命令行参数中，也不会在输出中回显。删除需 confirm: true。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'set', 'delete'],
+                    description: 'Secret 操作类型。',
+                },
+                repo: {
+                    type: 'string',
+                    description: '目标仓库 [owner/repo]，留空则自动识别当前本地 Git 仓库。',
+                },
+                name: {
+                    type: 'string',
+                    description: '密钥名称（set/delete 动作使用，如 "NPM_TOKEN"、"DOCKER_PASSWORD"）。',
+                },
+                value: {
+                    type: 'string',
+                    description: '密钥明文内容（set 动作使用）。内部通过子进程标准输入传递，避免在进程命令行被 ps/任务管理器窃取。',
+                },
+                org: {
+                    type: 'string',
+                    description: '组织级密钥的所属组织名（可选，映射 --org）。',
+                },
+                env: {
+                    type: 'string',
+                    description: '环境级密钥的部署环境名（可选，映射 --env）。',
+                },
+                app: {
+                    type: 'string',
+                    enum: ['actions', 'agents', 'codespaces', 'dependabot'],
+                    description: '密钥归属的应用（可选，映射 --app，默认 actions）。',
+                },
+                visibility: {
+                    type: 'string',
+                    enum: ['all', 'private', 'selected'],
+                    description: '组织级密钥的可见范围（可选，仅 org 场景有意义）。',
+                },
+                confirm: {
+                    type: 'boolean',
+                    description: '删除密钥时的确认标志。删除不可逆，未传 true 时仅输出影响评估。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: renderSecretOutput(args, value) }];
+            },
+        },
+        async execute(args, execContext) {
+            const cwd = execContext?.cwd || process.cwd();
+            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            // org 作用域的密钥挂在组织上，与具体仓库无关：既不需要仓库识别，
+            // 也不能把 -R 与 --org 同时传给 gh（两者语义冲突，gh 会报错）。
+            const isOrgScope = Boolean(args.org);
+            let repoTarget = args.repo;
+            if (!repoTarget && !isOrgScope) {
+                const meta = await executor.getRepoMetadata(cwd, sessionId);
+                if (meta?.nameWithOwner) {
+                    repoTarget = meta.nameWithOwner;
+                }
+            }
+            if (!repoTarget && !isOrgScope) {
+                throw new Error('未能自动识别当前工作区关联的 GitHub 仓库。请通过 `repo` 参数显式指定目标仓库 [owner/repo]，或改用 `org` 参数操作组织级密钥。');
+            }
+            const runOpts = { cwd, sessionId };
+            // org/env/app 三类作用域标志对所有动作通用；仓库作用域时三项均不追加
+            const scopeFlags = [];
+            if (args.org) {
+                scopeFlags.push('--org', args.org);
+                if (args.visibility)
+                    scopeFlags.push('--visibility', args.visibility);
+            }
+            else if (args.env) {
+                scopeFlags.push('--env', args.env);
+            }
+            if (args.app)
+                scopeFlags.push('--app', args.app);
+            const targetArgs = isOrgScope ? [] : ['-R', repoTarget];
+            switch (args.action) {
+                case 'list': {
+                    const res = await executor.run(['secret', 'list', ...targetArgs, ...scopeFlags, '--json', 'name,updatedAt,visibility'], runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'set': {
+                    if (!args.name)
+                        throw new Error('set 操作必须提供 name（密钥名称）');
+                    if (typeof args.value !== 'string' || args.value.length === 0) {
+                        throw new Error('set 操作必须提供 value（密钥明文），且不允许为空字符串');
+                    }
+                    // 安全红线：密文只走 stdin。严禁退化为 -b <value> —— 那会把明文
+                    // 留在进程列表与 shell 历史里，等于密钥泄漏。gh 本地会用仓库公钥
+                    // 加密后才上传，明文不落盘、不出本机。
+                    const res = await executor.run(['secret', 'set', args.name, ...targetArgs, ...scopeFlags], { ...runOpts, stdin: args.value });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `Secret「${args.name}」已更新（值不回显）` };
+                }
+                case 'delete': {
+                    if (!args.name)
+                        throw new Error('delete 操作必须提供 name');
+                    if (args.confirm !== true) {
+                        return {
+                            status: 'AWAITING_CONFIRMATION',
+                            warning: `⚠️ 高危操作拦截：你即将删除 Secret「${args.name}」${args.org ? `（组织 ${args.org}）` : ''}。`,
+                            impact: '删除后所有引用该密钥的 CI/CD 工作流将立即无法取到值，运行中的构建会失败。',
+                            requiredAction: '如确认删除，请向用户核实并附加 `confirm: true` 重新调用。',
+                        };
+                    }
+                    const res = await executor.run(['secret', 'delete', args.name, ...targetArgs, ...scopeFlags], runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `Secret「${args.name}」已删除` };
+                }
+                default:
+                    throw new Error(`未知的 Secret 操作: ${args.action}`);
+            }
+        },
+    };
+}

package/lib/tools/skill.d.ts

@@ -0,0 +1,63 @@
+import type { GhExecutor } from '../executor.js';
+export declare function createSkillTool(executor: GhExecutor): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            query: {
+                type: string;
+                description: string;
+            };
+            owner: {
+                type: string;
+                description: string;
+            };
+            repository: {
+                type: string;
+                description: string;
+            };
+            skill_name: {
+                type: string;
+                description: string;
+            };
+            agent: {
+                type: string;
+                description: string;
+            };
+            scope: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            all: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            confirm: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    output: {
+        schema: {
+            type: string;
+        };
+        render(args: any, value: any): {
+            type: string;
+            text: string;
+        }[];
+    };
+    execute(args: any, execContext: any): Promise<Record<string, any>>;
+};

package/lib/tools/skill.js

@@ -0,0 +1,146 @@
+import { renderSkillMarkdown } from '../renderers/markdown.js';
+function normalizeOutput(data) {
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return { items: data, count: data.length };
+    }
+    return { result: data !== undefined && data !== null ? data : '' };
+}
+export function createSkillTool(executor) {
+    return {
+        name: 'github_skill',
+        description: '通过 GitHub CLI 官方生态发现与管理 Agent Skills：跨仓库检索开源 Skills、预览 SKILL.md 内容、安装到本地 Agent 宿主（Claude Code / Cursor / Copilot 等）、查看已安装列表。install 会写入本地磁盘，需 confirm: true。基于 gh CLI preview 特性（需 gh >= 2.9x）。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['search', 'preview', 'install', 'list'],
+                    description: 'Skill 操作类型。',
+                },
+                query: {
+                    type: 'string',
+                    description: '搜索关键词（search 动作使用，如 "python"、"devops"、"markdown"）。',
+                },
+                owner: {
+                    type: 'string',
+                    description: '限定作者或组织（search 动作可选，映射 --owner）。',
+                },
+                repository: {
+                    type: 'string',
+                    description: '目标仓库全名 [owner/repo]（preview/install 动作使用，如 "github/awesome-copilot"）。',
+                },
+                skill_name: {
+                    type: 'string',
+                    description: 'Skill 名称（preview/install 动作可选）。支持 "name"、"author/name" 命名空间形式或 "name@version" 锁定版本。',
+                },
+                agent: {
+                    type: 'string',
+                    description: '安装到的目标 Agent 宿主（install 动作可选，如 "claude-code"、"cursor"、"github-copilot"；省略时 gh 会按环境探测）。',
+                },
+                scope: {
+                    type: 'string',
+                    enum: ['project', 'user'],
+                    description: '安装范围（install 动作可选，默认 project：安装进当前 git 仓库；user：安装到用户主目录全局可用）。',
+                },
+                all: {
+                    type: 'boolean',
+                    description: '安装仓库内全部 Skills 而非逐个选择（install 动作可选，映射 --all）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '搜索返回数量上限（search 动作使用，默认 15）。',
+                },
+                confirm: {
+                    type: 'boolean',
+                    description: '安装操作确认标志。install 会向本地磁盘写入文件，未传 true 时仅输出将要执行的安装预览。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: renderSkillMarkdown(args, value) }];
+            },
+        },
+        async execute(args, execContext) {
+            const cwd = execContext?.cwd || process.cwd();
+            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            // skill 工具天然面向跨仓库生态（search/preview 均以显式 repository 为目标），
+            // 不做当前工作区仓库自动识别——识别失败反而会误导调用方。
+            const runOpts = { cwd, sessionId };
+            switch (args.action) {
+                case 'search': {
+                    if (!args.query)
+                        throw new Error('search 操作必须提供 query（搜索关键词）');
+                    // 显式 limit 优先；缺省回退 executor.defaultListLimit（上限 50，gh skill 默认 15）
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(args.limit, 50) : Math.min(executor.defaultListLimit ?? 15, 50);
+                    const searchCmd = [
+                        'skill', 'search', args.query,
+                        '-L', String(limit),
+                        // 字段名以 gh 2.96.0 实测为准；preview 特性字段可能随版本演进，
+                        // 渲染层已对缺失字段做回退，这里不做多余防御
+                        '--json', 'skillName,repo,description,namespace,stars',
+                    ];
+                    if (args.owner)
+                        searchCmd.push('--owner', args.owner);
+                    const res = await executor.run(searchCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'preview': {
+                    if (!args.repository)
+                        throw new Error('preview 操作必须提供 repository [owner/repo]');
+                    const previewCmd = ['skill', 'preview', args.repository];
+                    if (args.skill_name)
+                        previewCmd.push(args.skill_name);
+                    // SKILL.md 是长篇 Markdown 文档，套 JSON 反而破坏可读性
+                    const res = await executor.run(previewCmd, { ...runOpts, rawText: true, timeoutMs: 60_000 });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { result: res.rawOutput || '未找到该 Skill 的内容' };
+                }
+                case 'install': {
+                    if (!args.repository)
+                        throw new Error('install 操作必须提供 repository [owner/repo]');
+                    if (args.confirm !== true) {
+                        return {
+                            status: 'AWAITING_CONFIRMATION',
+                            warning: `⚠️ 安装确认拦截：你即将从仓库「${args.repository}」安装 Skill${args.skill_name ? `「${args.skill_name}」` : ''}到本地${args.scope === 'user' ? '用户主目录（全局）' : '当前项目'}。`,
+                            impact: '安装会在本地磁盘写入 SKILL.md 及附属文件，并可能影响目标 Agent 宿主的默认行为。',
+                            requiredAction: '如确认安装，请向用户核实并附加 `confirm: true` 重新调用。',
+                        };
+                    }
+                    const installCmd = ['skill', 'install', args.repository];
+                    if (args.skill_name)
+                        installCmd.push(args.skill_name);
+                    if (args.agent)
+                        installCmd.push('--agent', args.agent);
+                    if (args.scope)
+                        installCmd.push('--scope', args.scope);
+                    if (args.all === true)
+                        installCmd.push('--all');
+                    const res = await executor.run(installCmd, { ...runOpts, timeoutMs: 120_000 });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `Skill 安装成功（来源: ${args.repository}）`, output: res.rawOutput };
+                }
+                case 'list': {
+                    const listCmd = ['skill', 'list', '--json', 'skillName,sourceURL,scope,version,pinned,path'];
+                    if (args.scope)
+                        listCmd.push('--scope', args.scope);
+                    const res = await executor.run(listCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                default:
+                    throw new Error(`未知的 Skill 操作: ${args.action}`);
+            }
+        },
+    };
+}

package/lib/types.d.ts

@@ -14,12 +14,22 @@ export interface PluginConfig {
     cacheTtlMs?: number;
     /** 查询列表默认限制条数，默认 20 */
     defaultListLimit?: number;
-    /** 是否开启新版本自动检查提示，默认 true */
+    /**
+     * 是否开启新版本自动检查提示，默认 true。
+     * false 时熔断全部版本探测入口（Web 横幅/启动日志/概览数据），用户显式
+     * 请求升级（如一键升级按钮）不受此限制——关闭的是「提示」，不是「能力」。
+     */
     checkUpdate?: boolean;
     /** 检查更新间隔毫秒数，默认 86,400,000 (24小时) */
     updateCheckIntervalMs?: number;
     /** 自定义 npm Registry 镜像地址，留空则自动选用 npmmirror 与 npmjs */
     registryUrl?: string;
+    /**
+     * 代理地址预置默认值（如 "http://127.0.0.1:7890"）。
+     * 仅在用户未在驾驶舱保存过代理设置时生效；运行时 UI 保存的值优先级更高。
+     * 注意：放在 Cordis Config 意味着修改此项会触发插件 reload（静态默认值，可接受）。
+     */
+    proxyUrl?: string;
 }
 export interface GhExecutionOptions {
     /** 命令执行的工作目录，优先使用当前 Agent 会话所在的 Workspace 物理路径 */
@@ -32,6 +42,17 @@ export interface GhExecutionOptions {
     env?: NodeJS.ProcessEnv;
     /** 是否强制以纯文本形式返回，不进行 JSON 尝试解析 */
     rawText?: boolean;
+    /**
+     * 二进制输出模式：stdout 保持 Buffer 原样返回（不做 UTF-8 转换与截断）。
+     * 用于 gh api 下载图片/附件等字节流场景；GhResult.data 此时是 Buffer。
+     */
+    binary?: boolean;
+    /**
+     * 写入子进程标准输入的内容。
+     * 为什么需要：gh secret set 不带 -b 时从 stdin 读取密文，这是唯一不把敏感值
+     * 暴露在进程命令行（ps / 任务管理器 / 审计日志可见）的传入通道。
+     */
+    stdin?: string;
 }
 export interface GhResult<T = unknown> {
     ok: boolean;
@@ -40,6 +61,8 @@ export interface GhResult<T = unknown> {
     error?: string;
     /** 是否因超出安全阈值而被截断 */
     truncated?: boolean;
+    /** 二进制模式下的字节长度（data 为 Buffer 时存在） */
+    binaryBytes?: number;
 }
 export interface AuthInstallGuide {
     /** 推荐包管理器命令，例如 Windows 下 "winget install --id GitHub.cli" */

package/lib/update-settings.d.ts

@@ -0,0 +1,18 @@
+export type UpdateSourceMode = 'official' | 'mirror' | 'off';
+/** mode 白名单校验：持久化文件可能被手改成任意串，不能成为绕过校验的后门 */
+export declare function isValidUpdateMode(v: unknown): v is UpdateSourceMode;
+/**
+ * 读取持久化设置。容灾语义：文件不存在/损坏/mode 非法 → 返回默认 'official'，
+ * 绝不让设置读取失败阻断插件启动（默认值即官方源，与 UI 默认选中一致）。
+ */
+export declare function loadUpdateSettings(): UpdateSourceMode;
+/**
+ * 原子写（tmp + rename）：并发/崩溃不产生半截 JSON。写盘失败不抛出——
+ * 内存态已生效，仅丢失重启恢复能力（尽力持久化语义，同 proxy.ts persist）。
+ */
+export declare function saveUpdateSettings(mode: UpdateSourceMode): {
+    ok: boolean;
+    error?: string;
+};
+/** mode → 人类可读名（命令行输出与 UI 共用，避免文案漂移） */
+export declare function describeUpdateMode(mode: UpdateSourceMode): string;

package/lib/update-settings.js

@@ -0,0 +1,60 @@
+/**
+ * 更新源设置轻量 store（官方源 / 国内镜像 / 关闭检查）。
+ *
+ * 为什么独立于 Cordis Config：更新源变更若走 Loader 会触发插件全量 reload
+ * （工具注销重注册、面板断流），而它是高频试错型设置，必须保存即生效——
+ * 与 proxy.json 完全同范式：~/.dsh/data/dsh-github-flow/update-settings.json。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** 持久化路径：与 proxy.json 同目录（DSH 用户数据目录规范） */
+function resolveStorePath() {
+    return path.join(os.homedir(), '.dsh', 'data', 'dsh-github-flow', 'update-settings.json');
+}
+/** mode 白名单校验：持久化文件可能被手改成任意串，不能成为绕过校验的后门 */
+export function isValidUpdateMode(v) {
+    return v === 'official' || v === 'mirror' || v === 'off';
+}
+/**
+ * 读取持久化设置。容灾语义：文件不存在/损坏/mode 非法 → 返回默认 'official'，
+ * 绝不让设置读取失败阻断插件启动（默认值即官方源，与 UI 默认选中一致）。
+ */
+export function loadUpdateSettings() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(resolveStorePath(), 'utf8'));
+        const mode = (raw && typeof raw === 'object') ? raw.mode : undefined;
+        if (isValidUpdateMode(mode))
+            return mode;
+    }
+    catch { /* 不存在/坏 JSON → 默认值 */ }
+    return 'official';
+}
+/**
+ * 原子写（tmp + rename）：并发/崩溃不产生半截 JSON。写盘失败不抛出——
+ * 内存态已生效，仅丢失重启恢复能力（尽力持久化语义，同 proxy.ts persist）。
+ */
+export function saveUpdateSettings(mode) {
+    if (!isValidUpdateMode(mode))
+        return { ok: false, error: `非法更新源模式: ${String(mode)}` };
+    try {
+        const storePath = resolveStorePath();
+        fs.mkdirSync(path.dirname(storePath), { recursive: true });
+        const tmp = `${storePath}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify({ mode, savedAt: new Date().toISOString() }, null, 2), 'utf8');
+        fs.renameSync(tmp, storePath);
+        return { ok: true };
+    }
+    catch (e) {
+        console.warn(`[dsh-github-flow] 更新源设置写盘失败（本次会话仍生效）: ${e?.message || e}`);
+        return { ok: false, error: e?.message || String(e) };
+    }
+}
+/** mode → 人类可读名（命令行输出与 UI 共用，避免文案漂移） */
+export function describeUpdateMode(mode) {
+    if (mode === 'mirror')
+        return '国内镜像 (npmmirror)';
+    if (mode === 'off')
+        return '不检查更新';
+    return 'npm 官方源';
+}

package/lib/updater.d.ts

@@ -1,4 +1,16 @@
 import type { UpdateInfo } from './types.js';
+import type { UpdateSourceMode } from './update-settings.js';
+/**
+ * 检测当前 DSH 运行 profile 名（升级命令的 --profile 必填项，官方 CLI 语义：
+ * `dsh plugin --profile <name> add <pkg>` 在 profile 目录内转发给 pnpm）。
+ * 探测优先级（从权威到兜底，不瞎猜）：
+ * 1. DSH_PROFILE 环境变量——launcher 启动时固定注入（桌面版=desktop，
+ *    `dsh --profile web` 启动的 Web 版=web），是运行进程对自身 profile 的事实源；
+ * 2. DSH_PROFILE_DIR 路径含 desktop 时判定 desktop；
+ * 3. 兜底探测 ~/.dsh/profiles 下实际存在的 profile 目录（web > default 顺序），
+ *    两者皆无才回落 'default'（dsh CLI 的默认 profile 名）。
+ */
+export declare function detectProfileName(): string;
 /**
  * 极简语义化版本大小比较函数 (latest > current 时返回 true)
  *
@@ -21,12 +33,39 @@ export declare class UpdateChecker {
     private inFlightPromise;
     private readonly intervalMs;
     private readonly customRegistry?;
+    /** 配置总开关（checkUpdate: false 时的自动探测熔断），见 check() 内注释 */
+    private readonly enabled;
+    /**
+     * 当前更新源模式。null = 未初始化（走 legacy 双源竞速，兼容 store 不存在
+     * 且无 Cordis registryUrl 的老安装）；一旦 UI 保存过任何 mode 即为权威。
+     */
+    private sourceMode;
     constructor(options?: {
         intervalMs?: number;
         customRegistry?: string;
+        enabled?: boolean;
     });
     /**
-     * 同步获取当前已知的版本状态（0ms 纯内存读取，绝不发外网请求）
+     * 应用代理到 npm 探测的 fetch 链路。
+     * 由 main.ts 在 ProxyManager 初始化/变更后调用：undici dispatcher 是进程级全局，
+     * 这里只做一次转发，真正的缓存/重建逻辑在 ProxyManager.applyFetchDispatcher 内。
+     */
+    applyProxy(manager: {
+        applyFetchDispatcher(): boolean;
+    } | null): void;
+    /**
+     * 运行时切换更新源（UI 保存即调用，无需插件 reload）。
+     * 为什么必须失效缓存：24h 缓存里存的是旧源的结果，用户切源后若不清缓存，
+     * 首次 check() 仍返回旧源的 latestVersion——用户感知「切换无效」。
+     * 'off' 与 enabled 熔断独立并存：enabled 来自 Cordis 静态配置（缺省 true），
+     * off 来自 UI 持久化设置；任一为「关」都熔断自动探测。
+     */
+    applySettings(mode: UpdateSourceMode): void;
+    /** 当前生效的更新源模式（供命令行/升级链路展示与对齐） */
+    getSourceMode(): UpdateSourceMode | null;
+    /**
+     * 同步获取当前已知的版本状态（0ms 纯内存读取，绝不发外网请求）。
+     * 兜底命令同样按当前 profile 生成：网络探测失败时复制命令也必须开箱可用。
      */
     getQuickStatus(): UpdateInfo;
     /**