dsh-github-flow 0.2.1 → 0.4.0

package/lib/tools/repo.js

@@ -18,8 +18,8 @@ export function createRepoTool(executor) {
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['view', 'readme', 'search_code', 'search_repos', 'sync'],
-                    description: '仓库操作类型。readme 读取 README 原文并附带图片清单（可选 image_urls 下载指定图片，不传下载全部截图；默认过滤徽章小图标）。',
+                    enum: ['view', 'readme', 'search_code', 'search_repos', 'search_issues', 'search_prs', 'search_commits', 'read_file', 'read_dir', 'sync'],
+                    description: '仓库操作类型。readme 读取 README 原文并附带图片清单（可选 image_urls 下载指定图片，不传下载全部截图；默认过滤徽章小图标）。read_file/read_dir 免 clone 读取任意路径文件与目录（gh ≥2.95，低版本自动降级 API 链路）。',
                 },
                 repo: {
                     type: 'string',
@@ -36,7 +36,15 @@ export function createRepoTool(executor) {
                 },
                 query: {
                     type: 'string',
-                    description: '检索关键词（search_code 或 search_repos 时使用）。',
+                    description: '检索关键词（search_* 动作使用）。限定符直接写进 query（gh 惯例）：如 "repo:owner/name state:open label:bug"。注意 search_code/search_commits 必须包含搜索文本，纯限定符查询（如仅 "repo:x"）会被 gh 拒绝。',
+                },
+                path: {
+                    type: 'string',
+                    description: 'read_file 必填 / read_dir 可选（默认仓库根目录）：目标文件或目录路径（如 "src/tools/pr.ts"、".github/workflows"）。',
+                },
+                ref: {
+                    type: 'string',
+                    description: 'read_file/read_dir 可选：从指定分支/tag/commit 读取（默认默认分支）。',
                 },
                 limit: {
                     type: 'number',
@@ -165,6 +173,122 @@ export function createRepoTool(executor) {
                         throw new Error(res.error);
                     return normalizeOutput(res.data || res.rawOutput);
                 }
+                case 'search_issues':
+                case 'search_prs': {
+                    if (!args.query)
+                        throw new Error(`${args.action} 必须提供 query`);
+                    // 限定符（repo:/state:/label: 等）直接写进 query 本体（gh search 惯例），
+                    // 不做独立参数——参数爆炸 + 与 gh 手册心智模型分叉（D3 决策）。
+                    // prs 比 issues 多 isDraft 字段（实测合法集 18 vs 17）。
+                    const repoArgs = args.repo ? ['--repo', args.repo] : [];
+                    const fields = args.action === 'search_prs'
+                        ? 'number,title,state,author,labels,isDraft,updatedAt,url'
+                        : 'number,title,state,author,labels,updatedAt,url';
+                    const res = await executor.run(['search', args.action === 'search_prs' ? 'prs' : 'issues', args.query, ...repoArgs, '--json', fields, '-L', limitStr], runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'search_commits': {
+                    if (!args.query)
+                        throw new Error('search_commits 必须提供 query');
+                    const repoArgs = args.repo ? ['--repo', args.repo] : [];
+                    const res = await executor.run(['search', 'commits', args.query, ...repoArgs, '--json', 'sha,commit,author,repository,url', '-L', limitStr], runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'read_file': {
+                    if (!args.path)
+                        throw new Error('read_file 必须提供 path（目标文件路径，如 "package.json"）');
+                    let repoTarget = args.repo;
+                    if (!repoTarget) {
+                        const meta = await executor.getRepoMetadata(cwd, sessionId);
+                        if (meta?.nameWithOwner)
+                            repoTarget = meta.nameWithOwner;
+                    }
+                    if (!repoTarget)
+                        throw new Error('read_file 必须提供 repo [owner/repo]，或在关联 Git 远程的工作区运行');
+                    const [owner, repoName] = repoTarget.split('/');
+                    if (!owner || !repoName)
+                        throw new Error(`read_file 需要 [owner/repo] 形式的仓库名（实际: ${repoTarget}）`);
+                    // 主链路走管道直出（无 --json）：gh 把原始内容写 stdout，executor 的
+                    // 24KB 截断与 UTF-8 处理免费复用；--json 模式 content 是 base64，
+                    // 中段截断即废且需解码 dance，弃用。
+                    const refArgs = args.ref ? ['--ref', args.ref] : [];
+                    const res = await executor.runGuarded(['repo', 'read-file', args.path, '-R', repoTarget, ...refArgs], {
+                        ...runOpts,
+                        rawText: true,
+                        timeoutMs: 20_000,
+                        minVersion: '2.95.0',
+                        capability: 'gh repo read-file',
+                        // 降级链：contents 端点 raw Accept（readme 同款技术），与主链路输出同构。
+                        // ref 必须走 URL query 而非 -f：gh api 在带 -f 时会把 GET 隐式改写为
+                        // POST（api.ts:66 同坑），contents 端点 POST 直接 404。
+                        fallback: async () => {
+                            const encoded = args.path.split('/').map(encodeURIComponent).join('/');
+                            const refQuery = args.ref ? `?ref=${encodeURIComponent(args.ref)}` : '';
+                            return executor.run(['api', `repos/${owner}/${repoName}/contents/${encoded}${refQuery}`, '-H', 'Accept: application/vnd.github.raw'], { cwd, sessionId, rawText: true, timeoutMs: 20_000 });
+                        },
+                    });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    const content = res.rawOutput || '';
+                    // 二进制防线：NUL 字节是文本内容的可靠否定信号（UTF-8 合法文本不含 NUL）。
+                    // 不做 base64 直返——那会撑爆 Token 预算，引导 github_api binary channel。
+                    if (content.includes('\0')) {
+                        throw new Error(`「${args.path}」是二进制文件（检测到 NUL 字节），不适合文本读取。请改用 github_api(endpoint: 'repos/${owner}/${repoName}/contents/${args.path.split('/').map(encodeURIComponent).join('/')}', raw: true, binary 场景自行落盘) 获取字节流。`);
+                    }
+                    return { path: args.path, ref: args.ref, content, size: content.length, ...(res.degraded ? { degraded: res.degraded, degradedReason: res.degradedReason } : {}) };
+                }
+                case 'read_dir': {
+                    let repoTarget = args.repo;
+                    if (!repoTarget) {
+                        const meta = await executor.getRepoMetadata(cwd, sessionId);
+                        if (meta?.nameWithOwner)
+                            repoTarget = meta.nameWithOwner;
+                    }
+                    if (!repoTarget)
+                        throw new Error('read_dir 必须提供 repo [owner/repo]，或在关联 Git 远程的工作区运行');
+                    const [owner, repoName] = repoTarget.split('/');
+                    if (!owner || !repoName)
+                        throw new Error(`read_dir 需要 [owner/repo] 形式的仓库名（实际: ${repoTarget}）`);
+                    const refArgs = args.ref ? ['--ref', args.ref] : [];
+                    const dirPath = args.path || '';
+                    const res = await executor.runGuarded(['repo', 'read-dir', ...(dirPath ? [dirPath] : []), '-R', repoTarget, ...refArgs], {
+                        ...runOpts,
+                        rawText: true,
+                        timeoutMs: 20_000,
+                        minVersion: '2.95.0',
+                        capability: 'gh repo read-dir',
+                        // 降级链：contents 端点返回 JSON 数组（dir 为含 type 字段的对象）。
+                        // ref 同样走 URL query（-f 会把 GET 改写成 POST，见 read_file 注释）
+                        fallback: async () => {
+                            const encoded = dirPath.split('/').filter(Boolean).map(encodeURIComponent).join('/');
+                            const refQuery = args.ref ? `?ref=${encodeURIComponent(args.ref)}` : '';
+                            return executor.run(['api', `repos/${owner}/${repoName}/contents/${encoded}${refQuery}`], { cwd, sessionId, timeoutMs: 20_000 });
+                        },
+                    });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    // 双链路归一为 items 数组：
+                    // 主链路是 TSV 四列（type/name/mode/size），降级链 data 是 contents JSON 数组
+                    let items;
+                    if (res.degraded && Array.isArray(res.data)) {
+                        items = res.data.map((e) => ({ type: String(e.type || 'file'), name: String(e.name || ''), mode: '-', size: typeof e.size === 'number' ? e.size : undefined }));
+                    }
+                    else {
+                        const tsv = (res.rawOutput || '').trim();
+                        if (!tsv) {
+                            return { message: `「${dirPath || '/'}」是空目录或不存在`, items: [], count: 0, ...(res.degraded ? { degraded: res.degraded, degradedReason: res.degradedReason } : {}) };
+                        }
+                        items = tsv.split('\n').map((line) => {
+                            const cols = line.split('\t');
+                            return { type: cols[0] || 'file', name: cols[1] || '', mode: cols[2] || '-', size: Number(cols[3]) || 0 };
+                        });
+                    }
+                    return { path: dirPath || '/', items, count: items.length, ...(res.degraded ? { degraded: res.degraded, degradedReason: res.degradedReason } : {}) };
+                }
                 case 'sync': {
                     let repoTarget = args.repo;
                     if (!repoTarget) {

package/lib/tools/ruleset.d.ts

@@ -0,0 +1,80 @@
+import type { GhExecutor } from '../executor.js';
+export interface ParsedRule {
+    name: string;
+    params: string;
+    source: string;
+}
+export interface ParsedRulesetCheck {
+    ruleCount: number;
+    branch: string;
+    repo: string;
+    rules: ParsedRule[];
+    rawText: string;
+}
+/**
+ * 解析 gh ruleset check 的纯文本输出，提取适用规则数、分支、仓库以及具体规则详情
+ */
+export declare function parseRulesetCheckOutput(output: string): ParsedRulesetCheck;
+export declare function createRulesetTool(executor: GhExecutor): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            repo: {
+                type: string;
+                description: string;
+            };
+            branch: {
+                type: string;
+                description: string;
+            };
+            default_branch: {
+                type: string;
+                description: string;
+            };
+            ruleset_id: {
+                type: string;
+                description: string;
+            };
+            org: {
+                type: string;
+                description: string;
+            };
+            no_parents: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                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<ParsedRulesetCheck | {
+        rawText: string;
+        org: any;
+        repo: string;
+        ruleset_id?: undefined;
+    } | {
+        ruleset_id: string;
+        rawText: string;
+        org: any;
+        repo: string;
+    }>;
+};

package/lib/tools/ruleset.js

@@ -0,0 +1,177 @@
+import { renderRulesetMarkdown } from '../renderers/markdown.js';
+/**
+ * 解析 gh ruleset check 的纯文本输出，提取适用规则数、分支、仓库以及具体规则详情
+ */
+export function parseRulesetCheckOutput(output) {
+    const trimmed = (output || '').trim();
+    const result = {
+        ruleCount: 0,
+        branch: '',
+        repo: '',
+        rules: [],
+        rawText: trimmed,
+    };
+    if (!trimmed)
+        return result;
+    // 1. 匹配首行: "N rules apply to branch <branch> in repo <repo>"
+    const firstLineMatch = trimmed.match(/^(\d+)\s+rules?\s+apply\s+to\s+branch\s+(\S+)\s+in\s+repo\s+(\S+)/i);
+    if (firstLineMatch) {
+        result.ruleCount = parseInt(firstLineMatch[1], 10);
+        result.branch = firstLineMatch[2];
+        result.repo = firstLineMatch[3];
+    }
+    // 2. 匹配具体规则明细项：形如 "- <name>: <params>\n    (configured in <source>)"
+    const rulePattern = /-\s*([a-zA-Z0-9_-]+):\s*([^\n\r]+)(?:[\r\n]+\s*\((configured in [^)]+)\))?/g;
+    let match;
+    while ((match = rulePattern.exec(trimmed)) !== null) {
+        result.rules.push({
+            name: match[1],
+            params: (match[2] || '').trim(),
+            source: (match[3] || '').trim(),
+        });
+    }
+    // 若首行未声明数量但解析到了规则列表，自动校正
+    if (result.rules.length > 0 && result.ruleCount === 0) {
+        result.ruleCount = result.rules.length;
+    }
+    return result;
+}
+export function createRulesetTool(executor) {
+    return {
+        name: 'github_ruleset',
+        description: '查看与诊断 GitHub 仓库/组织规则集 (Rulesets)：检查分支适用的合并策略规则 (check)、查看规则集列表 (list) 与详情 (view)。是诊断“PR 为什么不能合并”的权威规则策略视角。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'view', 'check'],
+                    description: 'Ruleset 操作类型。check 检查分支规则约束（策略排障核心）、list 查看规则集列表、view 查看规则集详情。',
+                },
+                repo: {
+                    type: 'string',
+                    description: '目标仓库 [owner/repo]，留空则识别当前工作区仓库。',
+                },
+                branch: {
+                    type: 'string',
+                    description: '要检查的分支名称（check 动作使用，缺省为当前分支）。',
+                },
+                default_branch: {
+                    type: 'boolean',
+                    description: '是否直接检查目标仓库默认分支的规则约束（check 动作可选，映射 --default）。',
+                },
+                ruleset_id: {
+                    type: 'string',
+                    description: '规则集 ID（view 动作必需，避免交互式选择挂起）。',
+                },
+                org: {
+                    type: 'string',
+                    description: '组织名称（list, view 动作可选，查看组织级规则集；需 admin:org 权限）。',
+                },
+                no_parents: {
+                    type: 'boolean',
+                    description: '是否排除上级组织配置的继承规则集（list, view 动作可选，默认包含上级继承；true 时仅看当前层级）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回规则集数量上限（list 动作使用，默认 30）。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: renderRulesetMarkdown(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 且需要 repo 维度）
+            const resolveRepoTarget = async () => {
+                if (args.repo)
+                    return args.repo;
+                const meta = await executor.getRepoMetadata(cwd, sessionId);
+                if (meta?.nameWithOwner)
+                    return meta.nameWithOwner;
+                throw new Error('未能自动识别当前工作区关联的 GitHub 仓库。请通过 `repo` 参数显式指定目标仓库 [owner/repo]（例如: "ItQianChen/dsh-github-flow"），或在当前工作区目录下关联 Git 远程仓库。');
+            };
+            const runOpts = { cwd, sessionId };
+            switch (args.action) {
+                case 'check': {
+                    const repoTarget = await resolveRepoTarget();
+                    const checkCmd = ['ruleset', 'check'];
+                    if (args.branch) {
+                        checkCmd.push(args.branch);
+                    }
+                    if (args.default_branch) {
+                        checkCmd.push('--default');
+                    }
+                    checkCmd.push('-R', repoTarget);
+                    const res = await executor.run(checkCmd, { ...runOpts, rawText: true });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    const parsed = parseRulesetCheckOutput(res.rawOutput || '');
+                    if (!parsed.repo)
+                        parsed.repo = repoTarget;
+                    if (!parsed.branch && args.branch)
+                        parsed.branch = args.branch;
+                    return parsed;
+                }
+                case 'list': {
+                    const listCmd = ['ruleset', 'list'];
+                    let repoTarget = '';
+                    if (args.org) {
+                        listCmd.push('--org', args.org);
+                    }
+                    else {
+                        repoTarget = await resolveRepoTarget();
+                        listCmd.push('-R', repoTarget);
+                    }
+                    if (args.no_parents) {
+                        listCmd.push('--no-parents');
+                    }
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 30;
+                    listCmd.push('-L', String(limit));
+                    const res = await executor.run(listCmd, { ...runOpts, rawText: true });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        rawText: (res.rawOutput || '').trim(),
+                        org: args.org,
+                        repo: repoTarget,
+                    };
+                }
+                case 'view': {
+                    if (args.ruleset_id === undefined || args.ruleset_id === null || String(args.ruleset_id).trim() === '') {
+                        throw new Error('查看规则集详情时 `ruleset_id` 参数为必填项（输入规则集数字 ID，如 "4898070"）。');
+                    }
+                    const viewCmd = ['ruleset', 'view', String(args.ruleset_id)];
+                    let repoTarget = '';
+                    if (args.org) {
+                        viewCmd.push('--org', args.org);
+                    }
+                    else {
+                        repoTarget = await resolveRepoTarget();
+                        viewCmd.push('-R', repoTarget);
+                    }
+                    if (args.no_parents) {
+                        viewCmd.push('--no-parents');
+                    }
+                    const res = await executor.run(viewCmd, { ...runOpts, rawText: true });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        ruleset_id: String(args.ruleset_id),
+                        rawText: (res.rawOutput || '').trim(),
+                        org: args.org,
+                        repo: repoTarget,
+                    };
+                }
+                default:
+                    throw new Error(`不支持的 ruleset 操作: "${args.action}"。可选值: check, list, view。`);
+            }
+        },
+    };
+}

package/lib/tools/run.d.ts

@@ -35,6 +35,14 @@ export declare function createRunTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            all: {
+                type: string;
+                description: string;
+            };
+            name: {
+                type: string;
+                description: string;
+            };
             ref: {
                 type: string;
                 description: string;

package/lib/tools/run.js

@@ -1,4 +1,8 @@
+import { compareGhVersions } from '../executor.js';
 import { renderRunMarkdown } from '../renderers/markdown.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -17,8 +21,8 @@ export function createRunTool(executor) {
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['list', 'view', 'log_failed', 'rerun', 'cancel', 'trigger'],
-                    description: 'Actions 操作类型。新增 trigger (主动触发 workflow_dispatch)。',
+                    enum: ['list', 'view', 'log_failed', 'rerun', 'cancel', 'trigger', 'workflow_list', 'workflow_view', 'workflow_enable', 'workflow_disable', 'download'],
+                    description: 'Actions 操作类型。trigger 主动触发 workflow_dispatch；workflow_* 查询与启停工作流；download 下载构建产物（落盘插件管理目录）。',
                 },
                 run_id: {
                     type: 'string',
@@ -43,7 +47,15 @@ export function createRunTool(executor) {
                 },
                 workflow: {
                     type: 'string',
-                    description: '工作流名称或文件名（trigger 动作使用，例如 "pr-check.yml" 或 "CI"）。',
+                    description: '工作流名称、ID 或文件名（trigger/workflow_view 动作使用，例如 "pr-check.yml"、"CI" 或 "374382120"）。',
+                },
+                all: {
+                    type: 'boolean',
+                    description: 'workflow_list 可选：列出全部工作流（含 disabled）。默认仅 active——排查「工作流为何不跑」时 disabled 状态本身就是答案，排障建议开启。',
+                },
+                name: {
+                    type: 'string',
+                    description: 'download 可选：仅下载指定名称的 artifact（可多次过滤，这里取单个名称）。',
                 },
                 ref: {
                     type: 'string',
@@ -132,6 +144,95 @@ export function createRunTool(executor) {
                     }
                     return { result: res.rawOutput || '未找到失败步骤的日志' };
                 }
+                case 'workflow_list': {
+                    // 字段集为 gh 2.96 实测合法全集（仅 4 个，无 updatedAt——勘误 E1）。
+                    // --all 暴露 disabled（排障语义：默认 active-only 对 Agent 是陷阱，D6 决策）。
+                    const listCmd = ['workflow', 'list', ...repoArgs, '--json', 'id,name,path,state', '-L', String(typeof args.limit === 'number' && args.limit > 0 ? args.limit : Math.min(executor.defaultListLimit ?? 10, 50))];
+                    if (args.all === true)
+                        listCmd.push('--all');
+                    const res = await executor.run(listCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'workflow_view': {
+                    if (!args.workflow)
+                        throw new Error('workflow_view 必须提供 workflow（工作流名称、ID 或文件名）');
+                    // gh workflow view 不支持 --json（勘误 E2，实测 unknown flag）——rawText 直通，
+                    // 仅头部三行结构化抽取；Recent runs 表保留原文（那是 run list 的投影，
+                    // Agent 要结构化运行数据走 github_run action:'list'，工具各司其职，D4 决策）。
+                    const res = await executor.run(['workflow', 'view', args.workflow, ...repoArgs], { ...runOpts, rawText: true, timeoutMs: 20_000 });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    const text = res.rawOutput || '';
+                    const idMatch = /^ID:\s*(\S+)/m.exec(text);
+                    const totalMatch = /^Total runs\s+(\S+)/m.exec(text);
+                    // 首行是「名称 - 文件名」组合行（实测形态），整行保留作 workflow 标识
+                    const firstLine = text.split('\n', 1)[0]?.trim() || args.workflow;
+                    const recentIdx = text.indexOf('Recent runs');
+                    return {
+                        workflow: firstLine,
+                        id: idMatch ? idMatch[1] : undefined,
+                        totalRuns: totalMatch ? totalMatch[1] : undefined,
+                        recentRuns: recentIdx >= 0 ? text.slice(recentIdx).trim() : text.trim(),
+                    };
+                }
+                case 'workflow_enable':
+                case 'workflow_disable': {
+                    if (!args.workflow)
+                        throw new Error(`${args.action} 必须提供 workflow（工作流名称、ID 或文件名）`);
+                    // 可逆状态开关免 confirm（S3 方案 D4），但 disable 的后果（trigger 静默失败）
+                    // 必须写进返回——Agent 不知情会把 CI 故障误判为代码问题
+                    const res = await executor.run(['workflow', args.action === 'workflow_enable' ? 'enable' : 'disable', args.workflow, ...repoArgs], runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return args.action === 'workflow_disable'
+                        ? { message: `工作流「${args.workflow}」已禁用。注意：下次 trigger 将静默失败，直至重新 enable（workflow_enable）。` }
+                        : { message: `工作流「${args.workflow}」已启用，恢复可触发状态。` };
+                }
+                case 'download': {
+                    if (!args.run_id)
+                        throw new Error('download 操作必须提供 run_id');
+                    if (args.name && typeof args.name !== 'string')
+                        throw new Error('name 必须是字符串（artifact 名称过滤）');
+                    // GHSA-39wj-f2f4-978v（gh<2.102 符号链接路径穿越）防线：落盘目录由插件
+                    // 固定派生（owner/repo/run_id 三级），不暴露 dir 参数给用户——攻击面
+                    // 收敛到一个 mkdirSync 调用点；用户无法注入 ../ 或符号链接目标。
+                    const artifactsRoot = path.join(os.homedir(), '.dsh', 'data', 'dsh-github-flow', 'artifacts', ...repoTarget.split('/'), String(args.run_id));
+                    fs.mkdirSync(artifactsRoot, { recursive: true });
+                    const dlCmd = ['run', 'download', String(args.run_id), ...repoArgs, '-D', artifactsRoot];
+                    if (args.name) {
+                        dlCmd.push('-n', args.name);
+                    }
+                    const res = await executor.run(dlCmd, { ...runOpts, timeoutMs: 120_000 });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    // 落盘清单：递归枚举产物文件（相对路径+大小），供 Agent 直接引用
+                    const files = [];
+                    const walk = (dir, prefix) => {
+                        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                            const full = path.join(dir, entry.name);
+                            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+                            if (entry.isDirectory())
+                                walk(full, rel);
+                            else
+                                files.push({ file: rel, size: fs.statSync(full).size });
+                        }
+                    };
+                    walk(artifactsRoot, '');
+                    // GHSA-39wj-f2f4-978v：2.102.0 修复符号链接路径穿越。低版本不硬拒绝
+                    // （受控仓库下载是合理需求），但安全提示必须进返回值引导升级。
+                    const ghVersion = await executor.getGhVersion();
+                    const securityNote = ghVersion && compareGhVersions(ghVersion, '2.102.0') < 0
+                        ? `安全提示：当前 gh ${ghVersion} 低于 2.102.0（修复 GHSA-39wj-f2f4-978v 符号链接路径穿越）。建议升级 gh（Windows: winget upgrade GitHub.cli / macOS: brew upgrade gh）。`
+                        : undefined;
+                    return {
+                        message: `Run #${args.run_id} 产物已下载 ${files.length} 个文件${args.name ? `（过滤: ${args.name}）` : ''}`,
+                        directory: artifactsRoot,
+                        files,
+                        ...(securityNote ? { securityNote } : {}),
+                    };
+                }
                 case 'trigger': {
                     if (!args.workflow)
                         throw new Error('trigger 操作必须提供 workflow（工作流名称或文件名，例如 "pr-check.yml"）');

package/lib/tools/secret.d.ts

@@ -10,6 +10,11 @@ export declare function createSecretTool(executor: GhExecutor): {
                 enum: string[];
                 description: string;
             };
+            kind: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
             repo: {
                 type: string;
                 description: string;