dsh-github-flow 0.2.0 → 0.3.0

package/lib/tools/pr.js

@@ -1,4 +1,5 @@
 import { renderPrMarkdown } from '../renderers/markdown.js';
+import { extractImageUrls, downloadImages, buildImageBlocks, filterRequestedUrls } from './image-utils.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -17,8 +18,8 @@ export function createPrTool(executor) {
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['list', 'view', 'create', 'diff', 'checks', 'review', 'merge', 'checkout', 'status'],
-                    description: 'PR 操作类型。新增 checkout (检出 PR 到本地分支)、status (检测当前分支 PR 冲突与状态)。',
+                    enum: ['list', 'view', 'create', 'diff', 'checks', 'review', 'merge', 'checkout', 'status', 'view_images', 'ready', 'revert', 'update_branch'],
+                    description: 'PR 操作类型。view_images 下载正文与评论中的图片（UI 变更对比图、复现截图等）到本地并以图片内容块返回，供 Agent 审查时直接查看。merge/revert 需 confirm: true（revert 在远端创建反向提交与新 PR）。',
                 },
                 pr_number: {
                     type: 'number',
@@ -60,7 +61,11 @@ export function createPrTool(executor) {
                 },
                 delete_branch: {
                     type: 'boolean',
-                    description: '合并后是否删除源分支（merge 操作时使用，默认 false）。删除分支不可撤销，只在确认该分支已无用后再开启。',
+                    description: '合并/revert 后是否删除源分支（merge、revert 操作时使用，默认 false）。删除分支不可撤销，只在确认该分支已无用后再开启。',
+                },
+                undo: {
+                    type: 'boolean',
+                    description: 'ready 动作可选：反向操作，把 PR 转回 Draft（gh 原生 --undo）。',
                 },
                 state: {
                     type: 'string',
@@ -87,13 +92,18 @@ export function createPrTool(executor) {
                     type: 'boolean',
                     description: '是否只预演不真正创建（create 操作时使用，默认 false）。透传 gh --dry-run：打印将要创建的 PR 详情而不落库，用于提交前确认 head/base/title 是否正确。',
                 },
+                image_urls: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'view_images 可选：仅下载指定 URL 的图片（从 view 返回的 images 清单中选取，不在清单内的会被拒绝）。留空下载全部（正文+评论）。',
+                },
             },
             required: ['action'],
         },
         output: {
             schema: { type: 'object' },
             render(args, value) {
-                return [{ type: 'text', text: renderPrMarkdown(args, value) }];
+                return [{ type: 'text', text: renderPrMarkdown(args, value) }, ...buildImageBlocks(value)];
             },
         },
         async execute(args, execContext) {
@@ -130,14 +140,82 @@ export function createPrTool(executor) {
                 }
                 case 'view': {
                     const target = args.pr_number ? [String(args.pr_number)] : [];
-                    const res = await executor.run(['pr', 'view', ...target, ...repoArgs, '--json', 'number,title,body,state,author,labels,assignees,reviewDecision,mergeable,statusCheckRollup,url'], runOpts);
+                    const res = await executor.run(['pr', 'view', ...target, ...repoArgs, '--json', 'number,title,body,state,author,labels,assignees,reviewDecision,mergeable,statusCheckRollup,url,comments'], runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
-                    return normalizeOutput(res.data || res.rawOutput);
+                    const out = normalizeOutput(res.data || res.rawOutput);
+                    // 附带图片 URL 清单（正文+评论，与 view_images 提取范围同源）：
+                    // Agent 按正文里的原始 URL 决策，需要看图时用 image_urls 精准选取
+                    const bodies = [typeof out.body === 'string' ? out.body : ''];
+                    if (Array.isArray(out.comments)) {
+                        for (const c of out.comments) {
+                            if (c && typeof c.body === 'string')
+                                bodies.push(c.body);
+                        }
+                    }
+                    out.images = Array.from(new Set(bodies.flatMap((b) => extractImageUrls(b))));
+                    return out;
+                }
+                case 'view_images': {
+                    if (!args.pr_number)
+                        throw new Error('view_images 操作必须提供 pr_number');
+                    // PR 与 Issue 图片机制同构；评论走同一 issues-comments API（实测 PR 评论
+                    // 的 <img> 形态与 issue 完全一致），正文 + 评论合并提取一次覆盖全部
+                    const detail = await executor.run(['pr', 'view', String(args.pr_number), ...repoArgs, '--json', 'body,comments'], runOpts);
+                    if (!detail.ok)
+                        throw new Error(detail.error);
+                    const d = detail.data && typeof detail.data === 'object' ? detail.data : {};
+                    const bodies = [];
+                    if (typeof d.body === 'string')
+                        bodies.push(d.body);
+                    if (Array.isArray(d.comments)) {
+                        for (const c of d.comments) {
+                            if (c && typeof c.body === 'string')
+                                bodies.push(c.body);
+                        }
+                    }
+                    // 多来源合并去重（Set 语义由 extractImageUrls 内部保证）
+                    const extracted = Array.from(new Set(bodies.flatMap((b) => extractImageUrls(b))));
+                    if (extracted.length === 0) {
+                        return { message: `PR #${args.pr_number} 正文与评论中未发现图片附件。` };
+                    }
+                    // 目标选择：不传 image_urls 下载全部；传入则与清单严格交集
+                    //（防幻觉/诱导的任意 URL 下载），空数组视为误传明确报错
+                    let targets = extracted;
+                    const rejections = [];
+                    if (args.image_urls !== undefined) {
+                        if (!Array.isArray(args.image_urls) || args.image_urls.length === 0) {
+                            throw new Error('image_urls 为空数组：如需下载全部请省略该参数，如需指定请传入 view 返回清单中的 URL。');
+                        }
+                        const filtered = filterRequestedUrls(args.image_urls, extracted);
+                        targets = filtered.matched;
+                        for (const bad of filtered.rejected) {
+                            rejections.push(`${String(bad).slice(-24)}: 不在本 PR 图片清单中，已拒绝（防任意下载）`);
+                        }
+                    }
+                    const { images, failures: dlFailures, remaining } = await downloadImages(targets, (url) => executor.run(['api', url], { ...runOpts, binary: true, timeoutMs: 30_000 }));
+                    const failures = [...rejections, ...dlFailures];
+                    if (images.length === 0 && rejections.length === 0 && !remaining) {
+                        return { message: `PR #${args.pr_number} 的图片全部下载失败：`, failures };
+                    }
+                    if (images.length === 0) {
+                        return { message: `PR #${args.pr_number} 未能获取任何图片（请求 ${targets.length} 张，被拒 ${rejections.length} 张）`, failures, remaining };
+                    }
+                    return {
+                        message: `PR #${args.pr_number} 成功获取 ${images.length} 张图片（正文+评论）${failures.length ? `（${failures.length} 条失败/提示）` : ''}：`,
+                        images,
+                        failures: failures.length ? failures : undefined,
+                        // 续传清单：触顶时 Agent 直接 image_urls: remaining 发起下一批
+                        remaining,
+                    };
                 }
                 case 'checks': {
                     const target = args.pr_number ? [String(args.pr_number)] : [];
-                    const res = await executor.run(['pr', 'checks', ...target, ...repoArgs, '--json', 'name,state,conclusion,detailsUrl'], runOpts);
+                    // 字段集为 gh pr checks 的合法九字段子集（v2.50.0 引入 --json 起从未变更）。
+                    // 旧字段集的 conclusion/detailsUrl 是 REST API 字段名，pr checks 从未支持——
+                    // 初版误搬导致该 action 在所有 gh 版本上必然报 Unknown JSON field（Issue #3）。
+                    // bucket 是 state 的分类视图（pass/fail/pending/skipping/cancel），link 即详情页。
+                    const res = await executor.run(['pr', 'checks', ...target, ...repoArgs, '--json', 'name,state,bucket,link,workflow,startedAt,completedAt'], runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
                     return normalizeOutput(res.data || res.rawOutput);
@@ -229,6 +307,49 @@ export function createPrTool(executor) {
                         throw new Error(res.error);
                     return { message: 'PR 合并完成', output: res.rawOutput };
                 }
+                // ---- 变更面新增（S3）----
+                case 'ready': {
+                    if (!args.pr_number)
+                        throw new Error('ready 操作必须提供 pr_number');
+                    // Draft→Ready；gh 原生支持 --undo 反向（转回 draft），完整可逆，免 confirm
+                    const cmd = ['pr', 'ready', String(args.pr_number), ...repoArgs];
+                    if (args.undo === true)
+                        cmd.push('--undo');
+                    const res = await executor.run(cmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `PR #${args.pr_number} 已${args.undo === true ? '转回 Draft' : '从 Draft 转为 Ready（进入正式评审）'}` };
+                }
+                case 'revert': {
+                    if (!args.pr_number)
+                        throw new Error('revert 操作必须提供 pr_number');
+                    // revert 在远端创建反向提交与新 PR——虽不碰原 PR，但产生新实体，按 merge 级 confirm（D5）
+                    if (args.confirm !== true) {
+                        return {
+                            status: 'AWAITING_CONFIRMATION',
+                            warning: `⚠️ 高危操作拦截：你即将对 PR #${args.pr_number} 创建反向提交（revert）。`,
+                            impact: '将在远端创建反向提交并生成新的 revert PR——这是新增远端实体，不是本地操作。',
+                            requiredAction: '如确认执行，请向用户明确确认并附加 `confirm: true` 重新调用。',
+                        };
+                    }
+                    const revertCmd = ['pr', 'revert', String(args.pr_number), ...repoArgs];
+                    if (args.delete_branch === true)
+                        revertCmd.push('--delete-branch');
+                    const res = await executor.run(revertCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `PR #${args.pr_number} 的反向提交已创建`, url: res.rawOutput };
+                }
+                case 'update_branch': {
+                    if (!args.pr_number)
+                        throw new Error('update_branch 操作必须提供 pr_number');
+                    // 等价 repo sync 的单 PR 版（push merge commit 到 PR 分支）；恰是「分支落后」
+                    // 的自愈动作，confirm 摩擦会阻碍 Agent 自愈闭环（D6），输出同步摘要即可
+                    const res = await executor.run(['pr', 'update-branch', String(args.pr_number), ...repoArgs], runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `PR #${args.pr_number} 分支已从基准分支同步更新`, output: res.rawOutput };
+                }
                 default:
                     throw new Error(`未知的 PR 操作: ${args.action}`);
             }

package/lib/tools/repo.d.ts

@@ -14,10 +14,29 @@ export declare function createRepoTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            image_urls: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            include_badges: {
+                type: string;
+                description: string;
+            };
             query: {
                 type: string;
                 description: string;
             };
+            path: {
+                type: string;
+                description: string;
+            };
+            ref: {
+                type: string;
+                description: string;
+            };
             limit: {
                 type: string;
                 description: string;
@@ -41,10 +60,7 @@ export declare function createRepoTool(executor: GhExecutor): {
         schema: {
             type: string;
         };
-        render(args: any, value: any): {
-            type: string;
-            text: string;
-        }[];
+        render(args: any, value: any): any[];
     };
     execute(args: any, execContext: any): Promise<Record<string, any>>;
 };

package/lib/tools/repo.js

@@ -1,4 +1,5 @@
 import { renderRepoMarkdown } from '../renderers/markdown.js';
+import { extractReadmeImageUrls, downloadImages, buildImageBlocks, filterRequestedUrls } from './image-utils.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -17,16 +18,33 @@ export function createRepoTool(executor) {
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['view', 'search_code', 'search_repos', 'sync'],
-                    description: '仓库操作类型。新增 sync (一键拉平 Fork 仓库与上游主干)。',
+                    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',
                     description: '目标仓库 [owner/repo]，留空则识别当前仓库。',
                 },
+                image_urls: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'readme 可选：仅下载指定 URL 的图片（从 readme 返回的 images 清单中选取）。留空下载全部。',
+                },
+                include_badges: {
+                    type: 'boolean',
+                    description: 'readme 可选：保留徽章类小图标（shields.io 等，默认过滤）。需要检查徽章状态时开启。',
+                },
                 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',
@@ -50,7 +68,7 @@ export function createRepoTool(executor) {
         output: {
             schema: { type: 'object' },
             render(args, value) {
-                return [{ type: 'text', text: renderRepoMarkdown(args, value) }];
+                return [{ type: 'text', text: renderRepoMarkdown(args, value) }, ...buildImageBlocks(value)];
             },
         },
         async execute(args, execContext) {
@@ -80,6 +98,64 @@ export function createRepoTool(executor) {
                     }
                     return normalizeOutput(res.data || res.rawOutput);
                 }
+                case 'readme': {
+                    let repoTarget = args.repo;
+                    if (!repoTarget) {
+                        const meta = await executor.getRepoMetadata(cwd, sessionId);
+                        if (meta?.nameWithOwner)
+                            repoTarget = meta.nameWithOwner;
+                    }
+                    if (!repoTarget)
+                        throw new Error('readme 操作必须提供 repo [owner/repo]，或在关联 Git 远程的工作区运行');
+                    const [owner, repoName] = repoTarget.split('/');
+                    if (!owner || !repoName)
+                        throw new Error(`readme 需要 [owner/repo] 形式的仓库名（实际: ${repoTarget}）`);
+                    // ① 取 README 原文（raw 头与 github_api 的 raw 模式同款技术，输出纯 Markdown）
+                    const rawRes = await executor.run(['api', `repos/${owner}/${repoName}/readme`, '-H', 'Accept: application/vnd.github.raw'], { ...runOpts, rawText: true, timeoutMs: 20_000 });
+                    if (!rawRes.ok)
+                        throw new Error(rawRes.error);
+                    const readmeText = rawRes.rawOutput || '';
+                    // ② 默认分支：先本地 view 元数据拿（一次 API），失败兜底 main
+                    let branch = 'main';
+                    const metaRes = await executor.run(['repo', 'view', repoTarget, '--json', 'defaultBranchRef'], runOpts);
+                    if (metaRes.ok && metaRes.data?.defaultBranchRef?.name) {
+                        branch = metaRes.data.defaultBranchRef.name;
+                    }
+                    // ③ 提取图片：绝对 URL + 相对路径解析为 raw URL，默认滤徽章
+                    const { urls: extracted, relativeResolved, badgeFiltered } = extractReadmeImageUrls(readmeText, {
+                        owner, repo: repoName, branch, includeBadges: args.include_badges === true,
+                    });
+                    // 不带 image_urls：返回文本（截断保护）+ 清单，Agent 按需再取图
+                    if (args.image_urls === undefined) {
+                        return {
+                            message: `已获取 ${repoTarget} 的 README（${readmeText.length} 字符${badgeFiltered ? `，过滤 ${badgeFiltered} 个徽章图标` : ''}${relativeResolved ? `，解析 ${relativeResolved} 个仓库内相对路径图片` : ''}）`,
+                            readme: readmeText.length > 6000 ? readmeText.slice(0, 6000) + '\n\n…(已截断，完整内容见仓库)' : readmeText,
+                            images: extracted,
+                            branch,
+                        };
+                    }
+                    // ④ 带 image_urls：交集校验 + 下载（语义与 issue/pr view_images 完全一致）
+                    if (!Array.isArray(args.image_urls) || args.image_urls.length === 0) {
+                        throw new Error('image_urls 为空数组：如需下载全部请省略该参数，如需指定请传入 readme 返回清单中的 URL。');
+                    }
+                    if (extracted.length === 0) {
+                        return { message: `${repoTarget} 的 README 中未发现图片附件（徽章已过滤，可用 include_badges: true 保留）。` };
+                    }
+                    const filtered = filterRequestedUrls(args.image_urls, extracted);
+                    const targets = filtered.matched;
+                    const rejections = filtered.rejected.map((b) => `${String(b).slice(-24)}: 不在 README 图片清单中，已拒绝（防任意下载）`);
+                    const { images, failures: dlFailures, remaining } = await downloadImages(targets, (url) => executor.run(['api', url], { ...runOpts, binary: true, timeoutMs: 30_000 }));
+                    const failures = [...rejections, ...dlFailures];
+                    if (images.length === 0) {
+                        return { message: `${repoTarget} README 图片未能获取（请求 ${targets.length} 张，被拒 ${rejections.length} 张）`, failures, remaining };
+                    }
+                    return {
+                        message: `${repoTarget} README 成功获取 ${images.length} 张图片${failures.length ? `（${failures.length} 条失败/提示）` : ''}：`,
+                        images,
+                        failures: failures.length ? failures : undefined,
+                        remaining,
+                    };
+                }
                 case 'search_code': {
                     if (!args.query)
                         throw new Error('search_code 必须提供 query');
@@ -97,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/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;