dsh-github-flow 0.2.0 → 0.2.1

package/lib/commands/gh.js

@@ -1,4 +1,5 @@
 import { CURRENT_PLUGIN_VERSION, PLUGIN_PACKAGE_NAME, NPM_PACKAGE_URL } from '../version.js';
+import { loadUpdateSettings, describeUpdateMode } from '../update-settings.js';
 export function registerGhCommand(commandsService, executor, updateChecker) {
     if (!commandsService || typeof commandsService.register !== 'function')
         return;
@@ -53,12 +54,20 @@ export function registerGhCommand(commandsService, executor, updateChecker) {
                 const platformName = isMac ? 'macOS' : isWin ? 'Windows' : 'Linux';
                 let md = `### 🚀 ${PLUGIN_PACKAGE_NAME} 插件升级指南\n\n`;
                 md += `- **当前运行版本**: \`v${curVer}\`\n`;
+                // 当前更新源：排查「查不到新版」时（镜像同步滞后）用户需可见自己在用哪个源。
+                // 优先读 checker 内存态（store 写盘失败时磁盘是旧值，活实例才是事实源），
+                // 无 checker 或未初始化（sourceMode=null 的 legacy 路径）回落磁盘 store。
+                const liveMode = updateChecker?.getSourceMode?.() ?? null;
+                const effectiveMode = liveMode ?? loadUpdateSettings();
+                md += `- **当前更新源**: ${describeUpdateMode(effectiveMode)}\n`;
                 md += `- **官方最新版本**: \`v${latestVer}\` ${hasUpdate ? '🔥 (有可用更新)' : '✅ (已是最新)'}\n`;
                 md += `- **操作系统环境**: \`${platformName} (${process.platform})\`\n`;
                 md += `- **npm 仓库地址**: [${NPM_PACKAGE_URL}](${NPM_PACKAGE_URL})\n\n`;
                 md += `#### 请根据你的 DSH 安装环境选择适用的升级方式：\n\n`;
-                md += `1. **DSH 官方标准工程升级（推荐）**:\n\`\`\`bash\npnpm dsh plugin add ${PLUGIN_PACKAGE_NAME}@latest\n\`\`\`\n\n`;
-                md += `2. **DSH 桌面版 Profile 环境升级**:\n\`\`\`bash\ndsh plugin --profile desktop add ${PLUGIN_PACKAGE_NAME}@latest\n\`\`\`\n`;
+                // 官方 CLI 语义：--profile 为必填参数（dsh plugin --profile <name> add <pkg>），
+                // 任何不带 --profile 的形态（含 pnpm dsh plugin add）都会直接报 required option 错误。
+                md += `1. **DSH 桌面版 Profile 环境升级（推荐）**:\n\`\`\`bash\ndsh plugin --profile desktop add ${PLUGIN_PACKAGE_NAME}@latest\n\`\`\`\n\n`;
+                md += `2. **DSH Web / CLI 环境**（profile 名按实际环境填写）:\n\`\`\`bash\ndsh plugin --profile web add ${PLUGIN_PACKAGE_NAME}@latest\n\`\`\`\n`;
                 if (isMac) {
                     md += `> 💡 *macOS 提示*：若在终端找不到 \`dsh\` 命令，可直接在桌面端目录更新：\n\`\`\`bash\ncd ~/.dsh/profiles/desktop && npm install ${PLUGIN_PACKAGE_NAME}@latest --save\n\`\`\`\n\n`;
                 }

package/lib/executor.js

@@ -1,9 +1,87 @@
-import { execFile } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import fs from 'node:fs';
 import path from 'node:path';
 import { findMostRecentWorkspacePath, findWorkspacePathBySession, hasGitDir } from './workspace.js';
 const execFileAsync = promisify(execFile);
+/**
+ * spawn 形态的执行通道（stdin 可选注入）。
+ *
+ * 为什么存在：execFile 的 input 选项在本机（node 22.18.0 + Windows）实测从不写入
+ * 子进程 stdin——既无数据也无 EOF，管道永久悬空（gh secret set 等需要 stdin 的
+ * 命令会一直等到超时）。最小复现：execFile+input 对 `cmd /c more` 与 node 子进程
+ * 均挂起；而 spawn + stdin.end(data) 全部正常。此函数即为后者的工程化封装，
+ * 仅在调用方显式传入 stdin 时使用，其余路径保持 execFileAsync 零改动。
+ *
+ * 为什么超时要自己管：spawn 无 timeout 选项，用 kill + SIGTERM 兜底；
+ * 输出按 maxBuffer 手工聚合（上限与 execFile 路径一致，15MB）。
+ */
+function spawnWithStdin(ghPath, args, opts) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(ghPath, args, {
+            cwd: opts.cwd,
+            env: opts.env,
+            windowsHide: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const outChunks = [];
+        const errChunks = [];
+        let totalBytes = 0;
+        let killed = false;
+        let settled = false;
+        const timer = setTimeout(() => {
+            killed = true;
+            child.kill();
+        }, opts.timeout);
+        const settle = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (err)
+                reject(err);
+            else
+                resolve({ stdout: Buffer.concat(outChunks), stderr: Buffer.concat(errChunks), killed });
+        };
+        // 聚合上限：超出即杀（与 execFile maxBuffer 语义一致；gh 正常输出远小于此）
+        const MAX_BYTES = 15 * 1024 * 1024;
+        child.stdout?.on('data', (d) => {
+            totalBytes += d.length;
+            outChunks.push(d);
+            if (totalBytes > MAX_BYTES) {
+                killed = true;
+                child.kill();
+            }
+        });
+        child.stderr?.on('data', (d) => { errChunks.push(d); });
+        child.on('error', (err) => {
+            // spawn 失败（如 ENOENT）对齐 execFile 的错误形状：code 保留在 Error 上
+            const e = Object.assign(new Error(err.message), { code: err.code });
+            settle(e);
+        });
+        child.on('close', (code, signal) => {
+            if (killed) {
+                // 超时/超量被杀：对齐 execFile 的 Timeout 错误形状（err.killed + signal）
+                const e = Object.assign(new Error(`Command timed out after ${opts.timeout}ms`), { killed: true, signal: signal || 'SIGTERM' });
+                settle(e);
+                return;
+            }
+            if (code !== 0) {
+                const e = Object.assign(new Error(`Command failed with exit code ${code}`), { code, stderr: Buffer.concat(errChunks).toString('utf8').slice(0, 800) });
+                settle(e);
+                return;
+            }
+            settle();
+        });
+        // stdin 注入：end(data) 半关闭（写完即 EOF），子进程流式读取或一次性读取均可
+        child.stdin?.end(opts.stdin, (err) => {
+            if (err && !settled) {
+                const e = Object.assign(new Error(`stdin write failed: ${err.message}`), { code: 'EPIPE' });
+                settle(e);
+            }
+        });
+    });
+}
 /** 认证状态缓存时长。用户手动 `gh auth login/logout` 后最多 30 秒内面板才会反映，属可接受代价 */
 const AUTH_CACHE_TTL_MS = 30_000;
 /**
@@ -185,11 +263,16 @@ export class GhExecutor {
     async run(args, options = {}) {
         const cwd = this.resolveWorkspaceCwd(options.cwd, options.sessionId);
         const timeout = options.timeoutMs || this.defaultTimeoutMs;
+        // 二进制模式（如 gh api 下载图片字节流）：stdout 保持 Buffer，绕过 UTF-8
+        // 字符串转换（PNG 等二进制经 utf8 解码必然损坏），也不做截断（截断只面向
+        // 文本 Token 预算）。显式开启才生效，既有调用方零感知。
+        const binary = options.binary === true;
         try {
-            const { stdout, stderr } = await execFileAsync(this.ghPath, args, {
+            // stdin 显式传入时走 spawn 通道：execFile 的 input 选项在本机从不真正写入
+            // （详见 spawnWithStdin 注释），gh secret set 等命令会挂到超时。其余调用
+            // 保持 execFileAsync 原路径零改动。
+            const commonOpts = {
                 cwd,
-                timeout,
-                maxBuffer: 15 * 1024 * 1024, // 15MB 进程缓冲
                 env: {
                     ...process.env,
                     GH_NO_UPDATE_NOTIFIER: '1', // 禁用 CLI 版本更新检查，避免污染 stdout
@@ -199,14 +282,41 @@ export class GhExecutor {
                     ...(this.proxyManager?.getEnv('gh') || {}),
                     ...options.env,
                 },
-                // 仅在显式传入 stdin 时附加 input 键：promisified execFile 会把 input
-                // 写入子进程 stdin 后立即结束流。不传则保持既有行为（继承/null 句柄），
-                // 确保对全部既有调用方零破坏。
-                ...(options.stdin !== undefined ? { input: options.stdin } : {}),
-            });
-            let rawOutput = (stdout || '').trim();
-            if (!rawOutput && stderr) {
-                rawOutput = stderr.trim();
+            };
+            let stdout;
+            let stderr;
+            if (options.stdin !== undefined) {
+                const r = await spawnWithStdin(this.ghPath, args, { ...commonOpts, timeout, stdin: options.stdin });
+                stdout = r.stdout;
+                stderr = r.stderr;
+            }
+            else {
+                const r = await execFileAsync(this.ghPath, args, {
+                    ...commonOpts,
+                    timeout,
+                    maxBuffer: 15 * 1024 * 1024, // 15MB 进程缓冲
+                    ...(binary ? { encoding: 'buffer' } : {}),
+                });
+                stdout = r.stdout;
+                stderr = r.stderr;
+            }
+            // 二进制通道：Buffer 原样返回（调用方自行写文件/校验魔数），stderr 仅作
+            // 错误线索不做输出回退——把错误提示字节当图片保存毫无意义。
+            // TS 无法从 options 展开的 encoding 键收窄 stdout 类型，这里显式归一化。
+            if (binary) {
+                const buf = Buffer.isBuffer(stdout) ? stdout : Buffer.from(String(stdout ?? ''));
+                const errBuf = Buffer.isBuffer(stderr) ? stderr : (stderr ? Buffer.from(String(stderr)) : null);
+                if (!buf.length) {
+                    const errMsg = errBuf ? errBuf.toString('utf8').trim() : '';
+                    return { ok: false, error: errMsg || '二进制输出为空' };
+                }
+                return { ok: true, data: buf, binaryBytes: buf.length, truncated: false };
+            }
+            const outText = Buffer.isBuffer(stdout) ? stdout.toString('utf8') : String(stdout ?? '');
+            const errText = Buffer.isBuffer(stderr) ? stderr.toString('utf8') : String(stderr ?? '');
+            let rawOutput = outText.trim();
+            if (!rawOutput && errText) {
+                rawOutput = errText.trim();
             }
             const outcome = truncateOutput(rawOutput, this.maxOutputChars, this.maxOutputBytes);
             rawOutput = outcome.text;

package/lib/main.js

@@ -14,6 +14,7 @@ import { UpdateChecker } from './updater.js';
 import { UpgradeManager } from './upgrade-manager.js';
 import { ProxyManager } from './proxy.js';
 import { NPM_PACKAGE_URL } from './version.js';
+import { loadUpdateSettings } from './update-settings.js';
 // 引用即生效：加载本模块以挂上 declare module '@deepseek-ai/cordis' 的 ctx.github 类型声明，
 // 并随下面 `export * from './github-service.js'` 一起传给消费方。
 import './github-service.js';
@@ -62,10 +63,18 @@ export function apply(ctx, config = {}) {
     const updateChecker = new UpdateChecker({
         intervalMs: config.updateCheckIntervalMs,
         customRegistry: config.registryUrl,
+        // checkUpdate: false 熔断全部探测入口（路由/命令/启动横幅共用此实例）
+        enabled: config.checkUpdate !== false,
     });
+    // 更新源设置（UI 持久化 store 优先于 Cordis 静态配置）：
+    // 启动时读取并应用到 checker；UI 保存时经路由直接调 applySettings 热切换。
+    const updateMode = loadUpdateSettings();
+    updateChecker.applySettings(updateMode);
     updateChecker.applyProxy(proxyManager);
     const upgradeManager = new UpgradeManager();
     upgradeManager.attachProxyManager(proxyManager);
+    // 注入查询函数而非静态值：用户切源后，下一次一键升级的 registry 实时跟随
+    upgradeManager.attachUpdateModeQuery(() => updateChecker.getSourceMode());
     // 1. 兑现生态服务契约：将 GitHub 执行引擎作为服务暴露给其他 DSH 插件 (ctx.github)
     if (ctx.provide && typeof ctx.provide === 'function') {
         ctx.provide('github', executor);

package/lib/renderers/markdown.d.ts

@@ -11,7 +11,12 @@
 export declare function sanitizeCell(text: any, maxLen?: number): string;
 /** 格式化 PR / Issue 状态药丸徽章 */
 export declare function formatStateBadge(state?: string, isDraft?: boolean): string;
-/** 格式化 CI 工作流状态徽章 */
+/**
+ * 格式化 CI 工作流状态徽章。
+ * 第二参数按调用域语义不同：run 域传 conclusion（success/failure/cancelled/skipped），
+ * pr checks 域传 bucket（pass/fail/pending/skipping/cancel）——取值族不同但映射到
+ * 同一组徽章；state 参数兜底（in_progress/queued 等进行中态）。
+ */
 export declare function formatCiBadge(status?: string, conclusion?: string): string;
 /** 格式化合并冲突状态 */
 export declare function formatConflictBadge(status?: string): string;

package/lib/renderers/markdown.js

@@ -35,18 +35,25 @@ export function formatStateBadge(state, isDraft) {
         return '🔴 CLOSED';
     return s;
 }
-/** 格式化 CI 工作流状态徽章 */
+/**
+ * 格式化 CI 工作流状态徽章。
+ * 第二参数按调用域语义不同：run 域传 conclusion（success/failure/cancelled/skipped），
+ * pr checks 域传 bucket（pass/fail/pending/skipping/cancel）——取值族不同但映射到
+ * 同一组徽章；state 参数兜底（in_progress/queued 等进行中态）。
+ */
 export function formatCiBadge(status, conclusion) {
     const conc = (conclusion || '').toLowerCase();
     const st = (status || '').toLowerCase();
-    if (conc === 'success')
-        return '✅ success';
-    if (conc === 'failure')
-        return '❌ failure';
-    if (conc === 'cancelled')
-        return '🚫 cancelled';
-    if (conc === 'skipped')
-        return '⏭️ skipped';
+    if (conc === 'success' || conc === 'pass')
+        return '✅ ' + conc;
+    if (conc === 'failure' || conc === 'fail')
+        return '❌ ' + conc;
+    if (conc === 'cancelled' || conc === 'cancel')
+        return '🚫 ' + conc;
+    if (conc === 'skipped' || conc === 'skipping')
+        return '⏭️ ' + conc;
+    if (conc === 'pending')
+        return '⏳ pending';
     if (st === 'in_progress')
         return '⏳ running';
     if (st === 'queued')
@@ -112,14 +119,18 @@ export function renderPrMarkdown(args, value) {
             return '当前 PR 暂无 CI Checks 运行记录。';
         const rows = list.map((c) => {
             const name = sanitizeCell(c.name, 40);
-            const badge = formatCiBadge(c.state, c.conclusion);
-            const url = c.detailsUrl ? `[查看详情](${c.detailsUrl})` : '-';
-            return `| ${name} | ${badge} | ${url} |`;
+            // bucket 是 gh pr checks 的分类字段（pass/fail/pending/skipping/cancel），
+            // 优先于 state 呈现；state（SUCCESS/FAILURE/...）作为兜底——渲染器同步
+            // Issue #3 修复：旧 conclusion/detailsUrl 字段在 gh 中不存在。
+            const badge = formatCiBadge(c.state, c.bucket);
+            const url = c.link ? `[查看详情](${c.link})` : '-';
+            const wf = c.workflow ? sanitizeCell(c.workflow, 24) : '-';
+            return `| ${name} | ${badge} | ${wf} | ${url} |`;
         });
         return [
             `**CI 检查结果 (${list.length} 项):**\n`,
-            '| 检查项名称 | 结论 / 状态 | 详情链接 |',
-            '| :--- | :--- | :--- |',
+            '| 检查项名称 | 结论 / 状态 | 工作流 | 详情链接 |',
+            '| :--- | :--- | :--- | :--- |',
             ...rows,
         ].join('\n');
     }
@@ -228,6 +239,10 @@ export function renderIssueMarkdown(args, value) {
         if (value.body) {
             lines.push('\n**议题正文:**\n```markdown\n' + sanitizeCell(value.body, 300) + '\n```');
         }
+        // 图片附件清单（view 附带 URL 清单，view_images 按需下载查看）
+        if (Array.isArray(value.images) && value.images.length > 0) {
+            lines.push(`- **📎 图片附件 (${value.images.length}):** 调用 \`github_issue(action: 'view_images', issue_number: ${value.number})\` 可下载查看`);
+        }
         return lines.join('\n');
     }
     // 兜底降级
@@ -292,6 +307,18 @@ export function renderRepoMarkdown(args, value) {
         return '无返回内容';
     if (typeof value.result === 'string')
         return value.result;
+    // 4.0 README 预览（文本截断版 + 图片清单）——必须在 message 早退分支之前：
+    // readme 返回同时带 message 与 readme 字段，先判 readme 才能渲染预览而非一行摘要
+    if (args?.action === 'readme' && typeof value.readme === 'string') {
+        const lines = [`### 📖 README 预览`, '', '```markdown', value.readme, '```'];
+        if (Array.isArray(value.images) && value.images.length > 0) {
+            lines.push('', `**📎 图片清单 (${value.images.length}):** 可用 \`image_urls\` 参数下载指定图片（留空下载全部）`);
+            value.images.slice(0, 8).forEach((u, i) => lines.push(`${i + 1}. ${u}`));
+            if (value.images.length > 8)
+                lines.push(`…共 ${value.images.length} 个`);
+        }
+        return lines.join('\n');
+    }
     if (typeof value.message === 'string' && !value.items) {
         return `**${value.message}**` + (value.output ? `\n\`\`\`\n${value.output}\n\`\`\`` : '');
     }

package/lib/tools/help.js

@@ -19,6 +19,9 @@ const KNOWLEDGE_BASE = {
     pr: `### 🔀 github_pr 详细操作指南
 
 - **查看列表**: \`github_pr(action: 'list', state: 'open' | 'closed' | 'merged' | 'all', limit: 20, author: '@me')\`
+- **下载并查看 PR 图片**: \`github_pr(action: 'view_images', pr_number: 123)\`
+  - 提取范围覆盖 PR 正文 + 评论，经 gh api 下载（UI 变更对比图、复现截图等）到本地并以图片内容块返回，Agent 审查时可直接看图；魔数校验 + 字节护栏与 Issue 侧一致。
+  - **按 URL 精准获取**: 附加 \`image_urls: [...]\` 只下载指定图片；触达目录上限时返回 remaining 清单可分批续传（与 Issue 侧用法完全一致）。
 - **本地检出代码**: \`github_pr(action: 'checkout', pr_number: 123)\`
   - 自动切换到本地分支并拉取最新提交，非常适用于 Agent 在本地沙箱中跑单元测试验证 PR 改动。
 - **差异比对**: \`github_pr(action: 'diff', pr_number: 123, stat_only: true)\`
@@ -30,6 +33,12 @@ const KNOWLEDGE_BASE = {
     issue: `### 🎯 github_issue 详细操作指南
 
 - **筛选 Issue**: \`github_issue(action: 'list', state: 'open' | 'closed' | 'all', labels: ['bug'], assignees: ['octocat'], limit: 20)\`
+- **查看 Issue 附带截图**: \`github_issue(action: 'view', issue_number: 42)\`
+  - 返回正文中的图片 URL 清单（用户拖拽上传的报障截图等）；需要"看图"时执行下方 view_images。
+- **下载并查看 Issue 图片**: \`github_issue(action: 'view_images', issue_number: 42)\`
+  - 经 gh api 下载正文+评论图片到本地（~/.dsh/data/dsh-github-flow/images/，内容寻址去重），以图片内容块返回，Agent 可直接查看用户报障截图；魔数校验 + 字节护栏（单图 5MB、目录 15MB）。
+  - **按 URL 精准获取**: 附加 \`image_urls: ['<view 返回清单中的 URL>']\` 只下载指定图片（可单张可批量）；传入 URL 必须在清单内（防任意下载）。
+  - 触达目录上限时返回 \`remaining\` 结构化清单，直接作为下一批 image_urls 续传即可。
 - **关联开发分支**: \`github_issue(action: 'develop', issue_number: 42, branch_name: 'fix-login-bug')\`
   - 自动在远端和本地创建带有官方关联关系的开发分支并切换过去，实现“读需求 -> 开分支写代码”的无缝衔接。
 - **编辑 Issue**: \`github_issue(action: 'edit', issue_number: 42, title: '新标题', add_labels: ['p1'], remove_labels: ['triage'])\`
@@ -49,6 +58,9 @@ const KNOWLEDGE_BASE = {
 
 - **查看元数据与标签**: \`github_repo(action: 'view')\`
   - 返回仓库基本信息、默认分支、Star 计数、许可证以及 \`repositoryTopics\`（用于 DSH 插件合规审查）。
+- **读取 README 及截图**: \`github_repo(action: 'readme', repo: 'owner/repo')\`
+  - 返回 README 原文与图片 URL 清单（仓库内相对路径自动解析为 raw 链接；默认过滤徽章小图标，\`include_badges: true\` 保留）。
+  - **下载图片查看**: 附加 \`image_urls: [...]\` 精准下载指定图（留空下载全部截图）；护栏与 Issue/PR 图片一致，触顶返回 remaining 可续传。
 - **一键拉平 Fork 主干 (防止 Stale)**: \`github_repo(action: 'sync', branch: 'main')\`
   - 解决开源项目贡献中因本地 Fork 落后导致上游 CI 门禁失败的顽疾。
 - **代码检索**: \`github_repo(action: 'search_code', query: 'filename:package.json dsh.bundle')\``,

package/lib/tools/image-utils.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 把 README 中的仓库内相对图片路径解析为 raw.githubusercontent 绝对 URL。
+ * 强制落在 raw 域名模板内——不存在拼出任意域名的可能（SSRF 白名单天然覆盖）。
+ * 路径以 ./ ../ /docs/ 等形态出现；URL 编码空格等字符；无效形态返回 null。
+ */
+export declare function resolveRelativeImageUrl(rel: string, owner: string, repo: string, branch: string): string | null;
+/**
+ * 判断 URL 是否为徽章类小图标（shields.io / badge 类 svg）。
+ * README 图片场景默认过滤：用户要看的是截图/架构图，版本徽章是排版噪音；
+ * include_badges=true 时保留（有人确实要查徽章状态）。
+ */
+export declare function isBadgeImageUrl(url: string): boolean;
+/**
+ * 从正文（Issue/PR body 或评论）提取图片 URL。
+ * 域名白名单 + https 扩展名双条件：
+ * - GitHub 四资产域名直接放行（用户上传/旧版上传/仓库引用/camo 代理）；
+ * - 外链强制 https 且带图片扩展名——关闭恶意正文诱导访问内网元数据端点
+ *   （169.254.169.254）等 SSRF 面，file:/// 与 http:// 一律拒绝。
+ */
+export declare function extractImageUrls(body: unknown): string[];
+/**
+ * README 专用提取：绝对 URL 走通用提取器；仓库内相对路径解析为 raw URL。
+ * 默认过滤徽章小图标（isBadgeImageUrl），include_badges 开关保留。
+ */
+export declare function extractReadmeImageUrls(body: unknown, ctx: {
+    owner: string;
+    repo: string;
+    branch: string;
+    includeBadges?: boolean;
+}): {
+    urls: string[];
+    relativeResolved: number;
+    badgeFiltered: number;
+};
+/** 从魔数推断图片 MIME（下载内容才是事实源——URL 扩展名可伪造） */
+export declare function sniffImageMime(buf: Buffer): string | null;
+/** 图片下载护栏：按真实资源消耗计算——单图字节与目录总量，无张数截断 */
+export declare const IMG_MAX_BYTES: number;
+export declare const IMG_DIR_MAX_BYTES: number;
+export interface DownloadedImage {
+    file: string;
+    mimeType: string;
+    url: string;
+    bytes: number;
+}
+export interface ImageBatchResult {
+    images: DownloadedImage[];
+    failures: string[];
+    /**
+     * 因目录总量护栏触顶而未处理的 URL（结构化续传清单）。
+     * Agent 可直接 image_urls: result.remaining 发起下一批——remaining 中的
+     * URL 本就来自正文合法清单，交集校验天然通过，分批获取无需清理目录。
+     */
+    remaining?: string[];
+}
+/**
+ * 交集过滤：把调用方请求的 URL 硬约束在正文实际提取的合法清单内。
+ * 为什么必须交集而非直接信任传入：image_urls 来自模型生成参数，存在幻觉或
+ * 被诱导传入任意 URL 的可能——交集把下载目标限定在本条 Issue/PR 引用过的
+ * 图片范围，SSRF 防线（提取阶段的 https+域名白名单）自动覆盖全部下载目标。
+ * 返回 { matched, rejected }：matched 保持请求顺序（Agent 按自己的关注顺序拿结果）。
+ */
+export declare function filterRequestedUrls(requested: unknown, extracted: string[]): {
+    matched: string[];
+    rejected: string[];
+};
+/**
+ * 批量下载图片并落盘（Issue/PR 的 view_images 共用执行体）。
+ * 每张经 executor 的二进制通道（gh api），魔数校验 + 三重护栏 + 内容寻址；
+ * 权威目录不可写时降级系统临时目录（只损失跨会话去重）。
+ * 单张失败不中断批次——failures 记录原因由调用方透传给 Agent。
+ */
+export declare function downloadImages(urls: string[], run: (url: string) => Promise<{
+    ok: boolean;
+    data?: unknown;
+    error?: string;
+}>): Promise<ImageBatchResult>;
+/** render 的 image 内容块构造（text 块由调用方自行拼）：仅双合法字段才产出块 */
+export declare function buildImageBlocks(value: any): any[];