dsh-github-flow 0.1.7 → 0.2.0

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,6 +14,18 @@ export interface PluginConfig {
     cacheTtlMs?: number;
     /** 查询列表默认限制条数，默认 20 */
     defaultListLimit?: number;
+    /** 是否开启新版本自动检查提示，默认 true */
+    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 物理路径 */
@@ -26,6 +38,12 @@ export interface GhExecutionOptions {
     env?: NodeJS.ProcessEnv;
     /** 是否强制以纯文本形式返回，不进行 JSON 尝试解析 */
     rawText?: boolean;
+    /**
+     * 写入子进程标准输入的内容。
+     * 为什么需要：gh secret set 不带 -b 时从 stdin 读取密文，这是唯一不把敏感值
+     * 暴露在进程命令行（ps / 任务管理器 / 审计日志可见）的传入通道。
+     */
+    stdin?: string;
 }
 export interface GhResult<T = unknown> {
     ok: boolean;
@@ -139,6 +157,8 @@ export interface GitHubOverviewData {
     runs: WorkflowRunItem[];
     lastUpdated: string;
     error?: string;
+    /** 插件版本与升级信息（由内存缓存快速读取，不阻塞首屏业务） */
+    updateInfo?: UpdateInfo;
 }
 export interface UserRepoItem {
     name: string;
@@ -199,4 +219,41 @@ export interface GlobalOverviewData {
     error?: string;
     /** 工作区矩阵读取失败的原因。区分「没有工作区」与「读不到工作区」，避免把故障显示成空状态 */
     workspaceError?: string;
+    /** 插件版本与升级信息（由内存缓存快速读取，不阻塞首屏业务） */
+    updateInfo?: UpdateInfo;
+}
+/**
+ * 插件版本检查信息
+ */
+export interface UpdateInfo {
+    currentVersion: string;
+    latestVersion?: string;
+    hasUpdate: boolean;
+    upgradeCommand: string;
+    allCommands: {
+        dshCli: string;
+        profile: string;
+        pnpm: string;
+        npm: string;
+    };
+    releaseNotesUrl: string;
+    checkedAt: number;
+}
+export type UpgradeState = 'idle' | 'upgrading' | 'success' | 'failed';
+export interface UpgradeStatusResult {
+    state: UpgradeState;
+    targetVersion?: string;
+    message?: string;
+    log?: string;
+    startedAt?: number;
+    completedAt?: number;
+    /** 识别到的宿主环境类型：desktop 为桌面版，web 为网页/CLI版 */
+    environment?: 'desktop' | 'web';
+}
+export interface UpgradeExecutionResult {
+    ok: boolean;
+    message: string;
+    needRestart: boolean;
+    log?: string;
+    environment?: 'desktop' | 'web';
 }

package/lib/updater.d.ts

@@ -0,0 +1,49 @@
+import type { UpdateInfo } from './types.js';
+/**
+ * 极简语义化版本大小比较函数 (latest > current 时返回 true)
+ *
+ * 为什么自研而不引入 semver npm 依赖：
+ * 避免为了简单的 x.y.z 比对而引入数十个传递子依赖，保持 DSH 插件轻量纯净与零运行期依赖负担。
+ * 约束条件：标准处理 x.y.z 形式，自动过滤前导 'v' 或 '^' 等非数字字符，忽略 pre-release 标签后续对比。
+ */
+export declare function isNewerVersion(current: string, latest: string): boolean;
+/**
+ * 插件版本检测引擎
+ *
+ * 架构约束与为什么这样设计：
+ * 1. 业务解耦：getQuickStatus 同步读取内存缓存，耗时 0ms，供主业务路由无感调用；
+ * 2. 闲时触发：check() 异步外网探测，首选淘宝镜像加速 (npmmirror.com)，官方 npmjs 兜底；
+ * 3. 避免击穿：通过 inFlightPromise 合并并发调用，防止多处同时触发重复请求；
+ * 4. 彻底容灾：任何网络或解析异常 100% 内部吸收，返回 hasUpdate: false，绝不影响主流程。
+ */
+export declare class UpdateChecker {
+    private cachedInfo;
+    private inFlightPromise;
+    private readonly intervalMs;
+    private readonly customRegistry?;
+    constructor(options?: {
+        intervalMs?: number;
+        customRegistry?: string;
+    });
+    /**
+     * 应用代理到 npm 探测的 fetch 链路。
+     * 由 main.ts 在 ProxyManager 初始化/变更后调用：undici dispatcher 是进程级全局，
+     * 这里只做一次转发，真正的缓存/重建逻辑在 ProxyManager.applyFetchDispatcher 内。
+     */
+    applyProxy(manager: {
+        applyFetchDispatcher(): boolean;
+    } | null): void;
+    /**
+     * 同步获取当前已知的版本状态（0ms 纯内存读取，绝不发外网请求）
+     */
+    getQuickStatus(): UpdateInfo;
+    /**
+     * 异步触发版本检测
+     * @param force 是否忽略 24h 缓存强制穿透探测
+     */
+    check(force?: boolean): Promise<UpdateInfo>;
+    /**
+     * 内部双 Registry 竞速/降级探测
+     */
+    private performCheck;
+}