dsh-github-flow 0.2.0 → 0.2.1

package/lib/tools/image-utils.js

@@ -0,0 +1,247 @@
+/**
+ * Issue / PR 共享的图片附件工具链。
+ *
+ * 为什么从 issue.ts 抽出：PR 与 Issue 的图片机制完全同构（同样的
+ * user-attachments 域名、<img>/![]() 双语法、同一评论 API），view_images
+ * 在两侧落地时共享提取/嗅探/护栏/落盘全部逻辑，避免两份拷贝漂移。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+/**
+ * 把 README 中的仓库内相对图片路径解析为 raw.githubusercontent 绝对 URL。
+ * 强制落在 raw 域名模板内——不存在拼出任意域名的可能（SSRF 白名单天然覆盖）。
+ * 路径以 ./ ../ /docs/ 等形态出现；URL 编码空格等字符；无效形态返回 null。
+ */
+export function resolveRelativeImageUrl(rel, owner, repo, branch) {
+    if (typeof rel !== 'string' || !rel || rel.startsWith('#'))
+        return null;
+    // 任何带 scheme 的（http/javascript/data/file）与 Windows 盘符/UNC 路径都不是
+    // 仓库内相对路径——统一拒绝，只接受纯 POSIX 相对形态
+    if (/^[a-z][a-z0-9+.-]*:/i.test(rel))
+        return null;
+    if (/^[a-z]:[\\/]/i.test(rel) || rel.startsWith('\\\\') || rel.includes('\\'))
+        return null;
+    // 去掉 ./ 前缀；拒绝越出仓库的绝对路径与查询串
+    let p = rel.replace(/^\.\//, '');
+    if (p.startsWith('/') || p.includes('..') || p.includes('?') || p.includes('#'))
+        return null;
+    // 只放行仓库路径的合法字符集（字母数字、CJK/Unicode 文件名、._/- 空格），
+    // 从根上挡住把控制字符/协议残留拼进 raw URL 的畸形输入
+    if (!/^[\w\-. /\u0080-\uffff]+$/u.test(p))
+        return null;
+    try {
+        const encoded = p.split('/').map(encodeURIComponent).join('/');
+        return `https://raw.githubusercontent.com/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${encodeURIComponent(branch)}/${encoded}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 判断 URL 是否为徽章类小图标（shields.io / badge 类 svg）。
+ * README 图片场景默认过滤：用户要看的是截图/架构图，版本徽章是排版噪音；
+ * include_badges=true 时保留（有人确实要查徽章状态）。
+ */
+export function isBadgeImageUrl(url) {
+    return /img\.shields\.io|badgen\.net|badge|\/svg\?style=/i.test(url);
+}
+/**
+ * 从正文（Issue/PR body 或评论）提取图片 URL。
+ * 域名白名单 + https 扩展名双条件：
+ * - GitHub 四资产域名直接放行（用户上传/旧版上传/仓库引用/camo 代理）；
+ * - 外链强制 https 且带图片扩展名——关闭恶意正文诱导访问内网元数据端点
+ *   （169.254.169.254）等 SSRF 面，file:/// 与 http:// 一律拒绝。
+ */
+export function extractImageUrls(body) {
+    if (typeof body !== 'string' || !body)
+        return [];
+    const urls = new Set();
+    // HTML <img src="..."> 与 Markdown ![alt](url) 两种形态
+    const pattern = /(?:<img[^>]+src="([^"]+)"|!\[[^\]]*\]\(([^)\s]+)[^)]*\))/gi;
+    let m;
+    while ((m = pattern.exec(body)) !== null) {
+        const url = m[1] || m[2];
+        if (!url)
+            continue;
+        const isGithubAsset = url.startsWith('https://github.com/user-attachments/') ||
+            url.startsWith('https://user-images.githubusercontent.com/') ||
+            url.startsWith('https://raw.githubusercontent.com/') ||
+            url.startsWith('https://camo.githubusercontent.com/');
+        const looksLikeImage = url.startsWith('https://') &&
+            /\.(png|jpe?g|gif|webp|bmp|svg)([?#]|$)/i.test(url);
+        if (isGithubAsset || looksLikeImage)
+            urls.add(url);
+    }
+    return Array.from(urls);
+}
+/**
+ * README 专用提取：绝对 URL 走通用提取器；仓库内相对路径解析为 raw URL。
+ * 默认过滤徽章小图标（isBadgeImageUrl），include_badges 开关保留。
+ */
+export function extractReadmeImageUrls(body, ctx) {
+    if (typeof body !== 'string' || !body)
+        return { urls: [], relativeResolved: 0, badgeFiltered: 0 };
+    const absolute = extractImageUrls(body);
+    const result = [];
+    let badgeFiltered = 0;
+    const keep = (u) => {
+        if (!ctx.includeBadges && isBadgeImageUrl(u)) {
+            badgeFiltered++;
+            return;
+        }
+        result.push(u);
+    };
+    for (const u of absolute)
+        keep(u);
+    // 相对路径：同一正则源头重新扫，取原始 src 再解析（绝对 URL 的正则会漏掉 ./docs/x.png）
+    let relativeResolved = 0;
+    const pattern = /(?:<img[^>]+src="([^"]+)"|!\[[^\]]*\]\(([^)\s]+)[^)]*\))/gi;
+    let m;
+    while ((m = pattern.exec(body)) !== null) {
+        const raw = m[1] || m[2];
+        if (!raw || /^[a-z]+:\/\//i.test(raw))
+            continue; // 只处理相对路径
+        const resolved = resolveRelativeImageUrl(raw, ctx.owner, ctx.repo, ctx.branch);
+        if (resolved) {
+            keep(resolved);
+            relativeResolved++;
+        }
+    }
+    return { urls: Array.from(new Set(result)), relativeResolved, badgeFiltered };
+}
+/** 从魔数推断图片 MIME（下载内容才是事实源——URL 扩展名可伪造） */
+export function sniffImageMime(buf) {
+    // 长度下限只挡二进制格式（PNG/JPEG/GIF/WEBP 均有 ≥12 字节头）；SVG 是文本，
+    // 无固定头长度——短到 4 字节的 '<svg' 也合法，必须在长度检查之前判定
+    if (buf.slice(0, 4).toString('ascii').toLowerCase() === '<svg')
+        return 'image/svg+xml';
+    if (buf.length < 12)
+        return null;
+    if (buf[0] === 0x89 && buf[1] === 0x50)
+        return 'image/png'; // PNG
+    if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff)
+        return 'image/jpeg'; // JPEG
+    if (buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46)
+        return 'image/gif'; // GIF
+    if (buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50)
+        return 'image/webp'; // RIFF....WEBP
+    return null;
+}
+/** 图片下载护栏：按真实资源消耗计算——单图字节与目录总量，无张数截断 */
+export const IMG_MAX_BYTES = 5 * 1024 * 1024; // 单图 5MB
+export const IMG_DIR_MAX_BYTES = 15 * 1024 * 1024; // 图片缓存目录总量 15MB
+/** 图片落盘目录（按内容寻址命名，重复下载天然去重） */
+function imageStoreDir() {
+    return path.join(os.homedir(), '.dsh', 'data', 'dsh-github-flow', 'images');
+}
+/** 粗略统计图片目录现有总量（遍历一次，文件数有护栏上限不会失控） */
+function imageDirSize(dir) {
+    let total = 0;
+    try {
+        for (const f of fs.readdirSync(dir)) {
+            try {
+                total += fs.statSync(path.join(dir, f)).size;
+            }
+            catch { }
+        }
+    }
+    catch { }
+    return total;
+}
+/**
+ * 交集过滤：把调用方请求的 URL 硬约束在正文实际提取的合法清单内。
+ * 为什么必须交集而非直接信任传入：image_urls 来自模型生成参数，存在幻觉或
+ * 被诱导传入任意 URL 的可能——交集把下载目标限定在本条 Issue/PR 引用过的
+ * 图片范围，SSRF 防线（提取阶段的 https+域名白名单）自动覆盖全部下载目标。
+ * 返回 { matched, rejected }：matched 保持请求顺序（Agent 按自己的关注顺序拿结果）。
+ */
+export function filterRequestedUrls(requested, extracted) {
+    const matched = [];
+    const rejected = [];
+    const allow = new Set(extracted);
+    for (const u of Array.isArray(requested) ? requested : []) {
+        if (typeof u === 'string' && u && allow.has(u)) {
+            matched.push(u);
+        }
+        else {
+            rejected.push(typeof u === 'string' && u ? u : JSON.stringify(u));
+        }
+    }
+    return { matched, rejected };
+}
+/**
+ * 批量下载图片并落盘（Issue/PR 的 view_images 共用执行体）。
+ * 每张经 executor 的二进制通道（gh api），魔数校验 + 三重护栏 + 内容寻址；
+ * 权威目录不可写时降级系统临时目录（只损失跨会话去重）。
+ * 单张失败不中断批次——failures 记录原因由调用方透传给 Agent。
+ */
+export async function downloadImages(urls, run) {
+    let dir = imageStoreDir();
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        dir = path.join(os.tmpdir(), 'dsh-github-flow-images');
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    let dirSize = imageDirSize(dir);
+    const images = [];
+    const failures = [];
+    const remaining = [];
+    let budgetExhausted = false;
+    // 无张数截断：字节护栏按真实资源消耗逐张判定。触顶后仍继续遍历——
+    // 剩余 URL 全部收进 remaining 供 Agent 分批续传，而非静默丢弃。
+    for (const url of urls) {
+        if (budgetExhausted) {
+            remaining.push(url);
+            continue;
+        }
+        const res = await run(url);
+        const buf = res.ok && Buffer.isBuffer(res.data) ? res.data : null;
+        if (!buf) {
+            failures.push(`${url.slice(-24)}: ${res.error || '非二进制响应'}`);
+            continue;
+        }
+        if (buf.length > IMG_MAX_BYTES) {
+            failures.push(`${url.slice(-24)}: 超过单图 5MB 上限（${(buf.length / 1024 / 1024).toFixed(1)}MB）`);
+            continue;
+        }
+        const mime = sniffImageMime(buf);
+        if (!mime) {
+            failures.push(`${url.slice(-24)}: 内容不是图片（魔数校验失败）`);
+            continue;
+        }
+        if (dirSize + buf.length > IMG_DIR_MAX_BYTES) {
+            budgetExhausted = true;
+            remaining.push(url);
+            continue;
+        }
+        // 内容寻址（sha256 前 16 位）+ 扩展名：重复下载同一图去重，文件名可读
+        const ext = mime.includes('svg') ? 'svg' : mime.split('/')[1].replace('jpeg', 'jpg');
+        const file = path.join(dir, `${crypto.createHash('sha256').update(buf).digest('hex').slice(0, 16)}.${ext}`);
+        fs.writeFileSync(file, buf);
+        // 累计已写入量：下张图的总量护栏判定必须基于最新值（否则多图可突破上限）
+        dirSize += buf.length;
+        images.push({ file, mimeType: mime, url, bytes: buf.length });
+    }
+    // 触顶反馈（用户裁定的续传闭环）：已获取 N/M + 结构化剩余清单，
+    // Agent 直接 image_urls: remaining 续传，无需从文本里解析 URL
+    if (remaining.length > 0) {
+        failures.push(`图片缓存目录达 15MB 上限：本次获取 ${images.length}/${urls.length} 张，剩余 ${remaining.length} 张未下载（可分批续传）`);
+    }
+    return { images, failures, remaining: remaining.length ? remaining : undefined };
+}
+/** render 的 image 内容块构造（text 块由调用方自行拼）：仅双合法字段才产出块 */
+export function buildImageBlocks(value) {
+    const blocks = [];
+    if (Array.isArray(value?.images)) {
+        for (const img of value.images) {
+            if (img && typeof img.file === 'string' && typeof img.mimeType === 'string') {
+                blocks.push({ type: 'image', path: img.file, mimeType: img.mimeType });
+            }
+        }
+    }
+    return blocks;
+}

package/lib/tools/issue.d.ts

@@ -1,4 +1,5 @@
 import type { GhExecutor } from '../executor.js';
+export { extractImageUrls as extractIssueImageUrls } from './image-utils.js';
 export declare function createIssueTool(executor: GhExecutor): {
     name: string;
     description: string;
@@ -71,6 +72,13 @@ export declare function createIssueTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            image_urls: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
         };
         required: string[];
     };
@@ -78,10 +86,7 @@ export declare function createIssueTool(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/issue.js

@@ -1,4 +1,5 @@
 import { renderIssueMarkdown } 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;
@@ -8,6 +9,8 @@ function normalizeOutput(data) {
     }
     return { result: data !== undefined && data !== null ? data : '' };
 }
+// 共享图片工具链的同名再导出：phase8 测试直接 import 本模块，保持路径稳定
+export { extractImageUrls as extractIssueImageUrls } from './image-utils.js';
 export function createIssueTool(executor) {
     return {
         name: 'github_issue',
@@ -17,8 +20,8 @@ export function createIssueTool(executor) {
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['list', 'view', 'create', 'comment', 'close', 'reopen', 'edit', 'develop'],
-                    description: 'Issue 操作类型。',
+                    enum: ['list', 'view', 'create', 'comment', 'close', 'reopen', 'edit', 'develop', 'view_images'],
+                    description: 'Issue 操作类型。view_images 下载正文内的图片到本地并返回可渲染的图片内容块（Agent 可直接"看"用户报障截图）。',
                 },
                 issue_number: {
                     type: 'number',
@@ -73,13 +76,20 @@ export function createIssueTool(executor) {
                     type: 'boolean',
                     description: '高危破坏性操作确认标志（close 动作必需）。若为 false 则仅输出待关闭警告。',
                 },
+                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: renderIssueMarkdown(args, value) }];
+                // view_images 的图片以宿主 image 内容块输出：模型与人类都能直接看到图，
+                // base64 会污染上下文（一张截图 ~88KB），引用落盘文件由宿主按需加载
+                return [{ type: 'text', text: renderIssueMarkdown(args, value) }, ...buildImageBlocks(value)];
             },
         },
         async execute(args, execContext) {
@@ -126,7 +136,68 @@ export function createIssueTool(executor) {
                     const res = await executor.run(['issue', 'view', String(args.issue_number), ...repoArgs, '--json', 'number,title,body,state,author,labels,assignees,comments,url'], 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.issue_number)
+                        throw new Error('view_images 操作必须提供 issue_number');
+                    // 第一步：取正文+评论提取图片 URL（与 view 清单同源）
+                    const detail = await executor.run(['issue', 'view', String(args.issue_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 = [typeof d.body === 'string' ? d.body : ''];
+                    if (Array.isArray(d.comments)) {
+                        for (const c of d.comments) {
+                            if (c && typeof c.body === 'string')
+                                bodies.push(c.body);
+                        }
+                    }
+                    const extracted = Array.from(new Set(bodies.flatMap((b) => extractImageUrls(b))));
+                    if (extracted.length === 0) {
+                        return { message: `Issue #${args.issue_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)}: 不在本 Issue 图片清单中，已拒绝（防任意下载）`);
+                        }
+                    }
+                    // 第三步：共享下载执行体（gh api 二进制通道 + 魔数校验 + 字节护栏 + 内容寻址落盘）
+                    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: `Issue #${args.issue_number} 的图片全部下载失败：`, failures };
+                    }
+                    if (images.length === 0) {
+                        return { message: `Issue #${args.issue_number} 未能获取任何图片（请求 ${targets.length} 张，被拒 ${rejections.length} 张）`, failures, remaining };
+                    }
+                    return {
+                        message: `Issue #${args.issue_number} 成功获取 ${images.length} 张图片${failures.length ? `（${failures.length} 条失败/提示）` : ''}：`,
+                        images,
+                        failures: failures.length ? failures : undefined,
+                        // 续传清单：触顶时 Agent 直接 image_urls: remaining 发起下一批
+                        remaining,
+                    };
                 }
                 case 'create': {
                     const cmd = ['issue', 'create', ...repoArgs, '--title', args.title || '', '--body', args.body || ''];

package/lib/tools/pr.d.ts

@@ -77,6 +77,13 @@ export declare function createPrTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            image_urls: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
         };
         required: string[];
     };
@@ -84,10 +91,7 @@ export declare function createPrTool(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/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'],
+                    description: 'PR 操作类型。view_images 下载正文与评论中的图片（UI 变更对比图、复现截图等）到本地并以图片内容块返回，供 Agent 审查时直接查看。',
                 },
                 pr_number: {
                     type: 'number',
@@ -87,13 +88,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 +136,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);

package/lib/tools/repo.d.ts

@@ -14,6 +14,17 @@ 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;
@@ -41,10 +52,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>>;
 };