dsh-github-flow 0.2.0 → 0.3.0

package/lib/tools/secret.js

@@ -45,17 +45,63 @@ function renderSecretOutput(args, value) {
     }
     return JSON.stringify(value, null, 2);
 }
+/**
+ * 渲染 variable 工具输出——与 renderSecretOutput 物理分离（S3 D1 决策）。
+ * 为什么必须独立函数而非同一渲染器的分支：variable 的 value 是 CI 明文（可回显，
+ * 这正是 get action 的用途），secret 的 value 永不显示。若共用渲染逻辑再
+ * 「选择性放开」，未来任一侧的重构都可能意外污染另一侧的安全假设——
+ * 两个函数的边界比一个函数的分支更可审。
+ */
+function renderVariableOutput(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 '📭 当前作用域尚未配置任何 Variable。';
+        const rows = list.map((v) => {
+            const name = `\`${String(v.name || '-')}\``;
+            const date = v.createdAt ? String(v.createdAt).slice(0, 10) : '-';
+            return `| ${name} | ${date} |`;
+        });
+        return [
+            `**当前已配置 ${list.length} 个 Variable（值为 CI 明文，可经 get 查看）:**\n`,
+            '| 变量名 | 创建日期 |',
+            '| :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    if (typeof value.result === 'string') {
+        return value.result;
+    }
+    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。',
+        description: '管理 GitHub Actions 仓库密钥 (Secrets) 与变量 (Variables)：查看名称清单、设置/更新/删除值。Secret 密文经标准输入安全传递，绝不出现在命令行参数或输出中；Variable 为 CI 明文，可经 get 查看值。Secret 删除需 confirm: true。',
         parameters: {
             type: 'object',
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['list', 'set', 'delete'],
-                    description: 'Secret 操作类型。',
+                    enum: ['list', 'get', 'set', 'delete'],
+                    description: '操作类型。get 仅 kind=variable 可用（secret 值写入后 GitHub 侧加密存储，物理不可读取）。',
+                },
+                kind: {
+                    type: 'string',
+                    enum: ['secret', 'variable'],
+                    description: '操作对象类型，默认 secret（向后兼容）。variable 为 Actions 明文变量：set 走 -b 直传、get 可回显值；secret 走 stdin 密文通道且永不回显。',
                 },
                 repo: {
                     type: 'string',
@@ -63,33 +109,33 @@ export function createSecretTool(executor) {
                 },
                 name: {
                     type: 'string',
-                    description: '密钥名称（set/delete 动作使用，如 "NPM_TOKEN"、"DOCKER_PASSWORD"）。',
+                    description: '名称（set/get/delete 动作使用，如 "NPM_TOKEN"、"DEPLOY_ENV"）。',
                 },
                 value: {
                     type: 'string',
-                    description: '密钥明文内容（set 动作使用）。内部通过子进程标准输入传递，避免在进程命令行被 ps/任务管理器窃取。',
+                    description: '值内容（set 动作使用）。secret：经子进程标准输入传递（防进程列表窃取）；variable：经 -b 参数直传（CI 明文，无 stdin 红线）。',
                 },
                 org: {
                     type: 'string',
-                    description: '组织级密钥的所属组织名（可选，映射 --org）。',
+                    description: '组织级作用域的组织名（可选，映射 --org）。',
                 },
                 env: {
                     type: 'string',
-                    description: '环境级密钥的部署环境名（可选，映射 --env）。',
+                    description: '环境级作用域的部署环境名（可选，映射 --env）。',
                 },
                 app: {
                     type: 'string',
                     enum: ['actions', 'agents', 'codespaces', 'dependabot'],
-                    description: '密钥归属的应用（可选，映射 --app，默认 actions）。',
+                    description: '密钥归属的应用（可选，仅 secret 的 --app，默认 actions；variable 无此维度）。',
                 },
                 visibility: {
                     type: 'string',
                     enum: ['all', 'private', 'selected'],
-                    description: '组织级密钥的可见范围（可选，仅 org 场景有意义）。',
+                    description: '组织级密钥的可见范围（可选，仅 secret + org 场景有意义）。',
                 },
                 confirm: {
                     type: 'boolean',
-                    description: '删除密钥时的确认标志。删除不可逆，未传 true 时仅输出影响评估。',
+                    description: '删除操作的确认标志。删除不可逆，未传 true 时仅输出影响评估。',
                 },
             },
             required: ['action'],
@@ -97,13 +143,16 @@ export function createSecretTool(executor) {
         output: {
             schema: { type: 'object' },
             render(args, value) {
-                return [{ type: 'text', text: renderSecretOutput(args, value) }];
+                // 渲染分流即安全边界：variable 与 secret 永不共享渲染路径（见函数注释）
+                const renderer = args?.kind === 'variable' ? renderVariableOutput : renderSecretOutput;
+                return [{ type: 'text', text: renderer(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 作用域的密钥挂在组织上，与具体仓库无关：既不需要仓库识别，
+            const isVariable = args.kind === 'variable';
+            // org 作用域挂在组织上，与具体仓库无关：既不需要仓库识别，
             // 也不能把 -R 与 --org 同时传给 gh（两者语义冲突，gh 会报错）。
             const isOrgScope = Boolean(args.org);
             let repoTarget = args.repo;
@@ -114,34 +163,67 @@ export function createSecretTool(executor) {
                 }
             }
             if (!repoTarget && !isOrgScope) {
-                throw new Error('未能自动识别当前工作区关联的 GitHub 仓库。请通过 `repo` 参数显式指定目标仓库 [owner/repo]，或改用 `org` 参数操作组织级密钥。');
+                throw new Error('未能自动识别当前工作区关联的 GitHub 仓库。请通过 `repo` 参数显式指定目标仓库 [owner/repo]，或改用 `org` 参数操作组织级作用域。');
+            }
+            // app 限定符仅 secret 域存在（variable 命令无 --app）；误传时明确报错而非静默忽略
+            if (isVariable && args.app) {
+                throw new Error("variable 无 --app 维度（app 仅 secret 域支持），请移除 app 参数。");
+            }
+            if (isVariable && args.visibility) {
+                throw new Error("variable 无 --visibility 维度（visibility 仅组织级 secret 支持），请移除 visibility 参数。");
             }
             const runOpts = { cwd, sessionId };
             // org/env/app 三类作用域标志对所有动作通用；仓库作用域时三项均不追加
             const scopeFlags = [];
             if (args.org) {
                 scopeFlags.push('--org', args.org);
-                if (args.visibility)
+                if (!isVariable && args.visibility)
                     scopeFlags.push('--visibility', args.visibility);
             }
             else if (args.env) {
                 scopeFlags.push('--env', args.env);
             }
-            if (args.app)
+            if (!isVariable && args.app)
                 scopeFlags.push('--app', args.app);
             const targetArgs = isOrgScope ? [] : ['-R', repoTarget];
+            // gh 命令域分流：secret → gh secret …；variable → gh variable …
+            // （两级分流：域前缀 + 每个分支内的行为差异——stdin vs -b、get 可用性）
+            const domain = isVariable ? 'variable' : 'secret';
             switch (args.action) {
                 case 'list': {
-                    const res = await executor.run(['secret', 'list', ...targetArgs, ...scopeFlags, '--json', 'name,updatedAt,visibility'], runOpts);
+                    // 字段集各自实测钉死：secret 有 updatedAt/visibility；variable 仅 4 字段
+                    // （createdAt,name,numSelectedRepos,selectedReposURL——无 value，get 才返回）
+                    const fields = isVariable ? 'name,createdAt,numSelectedRepos' : 'name,updatedAt,visibility';
+                    const res = await executor.run([domain, 'list', ...targetArgs, ...scopeFlags, '--json', fields], runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
                     return normalizeOutput(res.data || res.rawOutput);
                 }
+                case 'get': {
+                    if (!args.name)
+                        throw new Error('get 操作必须提供 name');
+                    if (!isVariable) {
+                        throw new Error('secret 的值写入后由 GitHub 侧加密存储，物理上不可读取（这正是 secret 与 variable 的设计区别）。请改用 kind: \'variable\' 或直接 set 覆盖。');
+                    }
+                    // gh variable get 输出变量值（纯文本，无 --json）
+                    const res = await executor.run(['variable', 'get', args.name, ...targetArgs, ...scopeFlags], { ...runOpts, rawText: true });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { name: args.name, value: res.rawOutput || '' };
+                }
                 case 'set': {
                     if (!args.name)
-                        throw new Error('set 操作必须提供 name（密钥名称）');
+                        throw new Error('set 操作必须提供 name');
                     if (typeof args.value !== 'string' || args.value.length === 0) {
-                        throw new Error('set 操作必须提供 value（密钥明文），且不允许为空字符串');
+                        throw new Error('set 操作必须提供 value，且不允许为空字符串');
+                    }
+                    if (isVariable) {
+                        // variable 是 CI 明文（workflow 中 env 直接引用可见），无 secret 的
+                        // stdin 红线；gh variable set 原生支持 -b 直传（实测 help）。
+                        const res = await executor.run(['variable', 'set', args.name, '--body', args.value, ...targetArgs, ...scopeFlags], runOpts);
+                        if (!res.ok)
+                            throw new Error(res.error);
+                        return { message: `Variable「${args.name}」已更新（值: ${args.value}）` };
                     }
                     // 安全红线：密文只走 stdin。严禁退化为 -b <value> —— 那会把明文
                     // 留在进程列表与 shell 历史里，等于密钥泄漏。gh 本地会用仓库公钥
@@ -154,21 +236,24 @@ export function createSecretTool(executor) {
                 case 'delete': {
                     if (!args.name)
                         throw new Error('delete 操作必须提供 name');
+                    const kindLabel = isVariable ? 'Variable' : 'Secret';
                     if (args.confirm !== true) {
                         return {
                             status: 'AWAITING_CONFIRMATION',
-                            warning: `⚠️ 高危操作拦截：你即将删除 Secret「${args.name}」${args.org ? `（组织 ${args.org}）` : ''}。`,
-                            impact: '删除后所有引用该密钥的 CI/CD 工作流将立即无法取到值，运行中的构建会失败。',
+                            warning: `⚠️ 高危操作拦截：你即将删除 ${kindLabel}「${args.name}」${args.org ? `（组织 ${args.org}）` : ''}。`,
+                            impact: isVariable
+                                ? '删除后所有引用该变量的工作流将取不到值，运行中的构建立即失败。'
+                                : '删除后所有引用该密钥的 CI/CD 工作流将立即无法取到值，运行中的构建会失败。',
                             requiredAction: '如确认删除，请向用户核实并附加 `confirm: true` 重新调用。',
                         };
                     }
-                    const res = await executor.run(['secret', 'delete', args.name, ...targetArgs, ...scopeFlags], runOpts);
+                    const res = await executor.run([domain, 'delete', args.name, ...targetArgs, ...scopeFlags], runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
-                    return { message: `Secret「${args.name}」已删除` };
+                    return { message: `${kindLabel}「${args.name}」已删除` };
                 }
                 default:
-                    throw new Error(`未知的 Secret 操作: ${args.action}`);
+                    throw new Error(`未知的 Secret/Variable 操作: ${args.action}（kind: ${args.kind || 'secret'}）`);
             }
         },
     };

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;
+    /**
+     * 是否向 gh 子进程注入 AI_AGENT='dsh' 环境变量，默认 true。
+     * gh ≥2.99 检测该变量后切换 agent 专属行为（text-only spinner、误用时打印完整 help）；
+     * 关闭后恢复 gh 原生行为（用于对照实验或偏好原生输出的场景）。
+     */
+    agentEnvInjection?: boolean;
     /**
      * 代理地址预置默认值（如 "http://127.0.0.1:7890"）。
      * 仅在用户未在驾驶舱保存过代理设置时生效；运行时 UI 保存的值优先级更高。
@@ -38,6 +48,11 @@ 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 读取密文，这是唯一不把敏感值
@@ -52,6 +67,8 @@ export interface GhResult<T = unknown> {
     error?: string;
     /** 是否因超出安全阈值而被截断 */
     truncated?: boolean;
+    /** 二进制模式下的字节长度（data 为 Buffer 时存在） */
+    binaryBytes?: number;
 }
 export interface AuthInstallGuide {
     /** 推荐包管理器命令，例如 Windows 下 "winget install --id GitHub.cli" */
@@ -85,6 +102,52 @@ export interface RepoMetadata {
     isPrivate?: boolean;
     url?: string;
 }
+/**
+ * 本地 Git 工作区状态快照（ahead/behind 是 remote-tracking ref 的「上次 fetch」视图，
+ * 非实时网络状态——UI 渲染时必须带上这一语义提示，否则会误导用户）。
+ */
+export interface GitLocalStatus {
+    branch: string;
+    /** 领先远程的提交数；无 upstream 时为 -1（未知） */
+    ahead: number;
+    /** 落后远程的提交数；无 upstream 时为 -1（未知） */
+    behind: number;
+    /** 未提交变更文件数（含 untracked） */
+    dirtyCount: number;
+    hasUpstream: boolean;
+    /** 未提交文件清单（porcelain 解析，截断前 20 条防快照膨胀） */
+    dirtyFiles: Array<{
+        status: string;
+        path: string;
+    }>;
+}
+/** 单条提交记录（结构化解析） */
+export interface GitCommitEntry {
+    sha: string;
+    fullSha?: string;
+    author: string;
+    email?: string;
+    date?: string;
+    /** git 的相对时间原文（如 "2 hours ago"）——本地化由渲染层处理 */
+    relative: string;
+    subject: string;
+    body?: string;
+    stat?: string;
+}
+/**
+ * 本地 Git 提交记录三段视图（与 GitLocalStatus 的 ahead/behind 计数同口径，
+ * 均为 remote-tracking 快照）。
+ */
+export interface GitCommitLog {
+    /** 本地领先远程的提交（待 push） */
+    aheadCommits: GitCommitEntry[];
+    /** 远程领先本地的提交（待 pull，快照口径） */
+    behindCommits: GitCommitEntry[];
+    /** 最近提交（默认 15 条，支持下滚分页） */
+    recent: GitCommitEntry[];
+    /** 仓库总提交数（rev-list --count HEAD） */
+    totalCount?: number;
+}
 export interface PrItem {
     number: number;
     title: string;
@@ -159,6 +222,25 @@ export interface GitHubOverviewData {
     error?: string;
     /** 插件版本与升级信息（由内存缓存快速读取，不阻塞首屏业务） */
     updateInfo?: UpdateInfo;
+    /** 本地 Git 状态（ahead/behind/dirty，remote-tracking 快照语义）；非 Git 工作区为 undefined */
+    gitStatus?: GitLocalStatus | null;
+    /** 提交记录三段（本地领先/远程领先/最近）；探测失败为 undefined */
+    commitLog?: GitCommitLog | null;
+    /** 最新 Release 锚定（已过滤 Draft）；无 Release 仓库为 null */
+    releaseInfo?: {
+        tagName: string;
+        isPrerelease?: boolean;
+        publishedAt?: string;
+        url?: string;
+    } | null;
+    /** 当前分支关联的 PR；无 PR 分支为 null */
+    branchPr?: {
+        number: number;
+        title: string;
+        state?: string;
+        url?: string;
+        isDraft?: boolean;
+    } | null;
 }
 export interface UserRepoItem {
     name: string;
@@ -177,6 +259,8 @@ export interface WorkspaceMatrixItem {
     hasGit: boolean;
     repo?: RepoMetadata;
     sessionCount: number;
+    /** 本地 Git 状态摘要（可选——探测失败/非 Git 工作区不携带） */
+    gitStatus?: GitLocalStatus;
 }
 export interface GlobalIssueItem {
     number: number;

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,9 +33,17 @@ 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;
     });
     /**
      * 应用代理到 npm 探测的 fetch 链路。
@@ -34,7 +54,18 @@ export declare class UpdateChecker {
         applyFetchDispatcher(): boolean;
     } | null): void;
     /**
-     * 同步获取当前已知的版本状态（0ms 纯内存读取，绝不发外网请求）
+     * 运行时切换更新源（UI 保存即调用，无需插件 reload）。
+     * 为什么必须失效缓存：24h 缓存里存的是旧源的结果，用户切源后若不清缓存，
+     * 首次 check() 仍返回旧源的 latestVersion——用户感知「切换无效」。
+     * 'off' 与 enabled 熔断独立并存：enabled 来自 Cordis 静态配置（缺省 true），
+     * off 来自 UI 持久化设置；任一为「关」都熔断自动探测。
+     */
+    applySettings(mode: UpdateSourceMode): void;
+    /** 当前生效的更新源模式（供命令行/升级链路展示与对齐） */
+    getSourceMode(): UpdateSourceMode | null;
+    /**
+     * 同步获取当前已知的版本状态（0ms 纯内存读取，绝不发外网请求）。
+     * 兜底命令同样按当前 profile 生成：网络探测失败时复制命令也必须开箱可用。
      */
     getQuickStatus(): UpdateInfo;
     /**