dsh-github-flow 0.2.0 → 0.3.0

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')
@@ -66,6 +73,17 @@ export function formatConflictBadge(status) {
         return '⛔ BLOCKED';
     return s;
 }
+/**
+ * 降级链路可见标注（runGuarded 契约的渲染兑现）。
+ * 为什么必须可见：降级若是静默的，Agent 就无法感知能力边界（同一 action 在
+ * 不同 gh 版本上走不同链路）；一条 blockquote 注释成本一行，换链路透明。
+ */
+export function appendDegradedNote(value) {
+    if (value && value.degraded === true && value.degradedReason) {
+        return `\n\n> ⚠️ ${value.degradedReason}`;
+    }
+    return '';
+}
 // -------------------------------------------------------------
 // 1. PR 渲染器
 // -------------------------------------------------------------
@@ -112,14 +130,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 +250,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');
     }
     // 兜底降级
@@ -265,7 +291,34 @@ export function renderRunMarkdown(args, value) {
             ...rows,
         ].join('\n');
     }
-    // 3.2 Run View 详情
+    // 3.2 Workflow 清单（字段集为 gh 2.96 实测合法全集 4 个）
+    if (Array.isArray(value.items) && args?.action === 'workflow_list') {
+        const list = value.items.filter(Boolean);
+        if (list.length === 0)
+            return args?.all === true ? '📭 该仓库没有任何工作流。' : '📭 暂无 active 工作流（可能全部 disabled，传 all: true 查看）。';
+        const rows = list.map((w) => {
+            const badge = w.state === 'active' ? '🟢 active' : (w.state === 'disabled' ? '🔴 disabled' : String(w.state || '-'));
+            return `| \`${w.id}\` | ${sanitizeCell(w.name, 40)} | ${badge} | \`${sanitizeCell(w.path, 45)}\` |`;
+        });
+        return [
+            `**工作流清单 (${list.length} 个${args?.all === true ? '，含 disabled' : ''}):**\n`,
+            '| ID | 名称 | 状态 | 文件 |',
+            '| :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 3.3 Workflow 详情（gh 无 --json，头部结构化 + Recent runs 原文引用块——D4 决策）
+    if (args?.action === 'workflow_view' && value.workflow) {
+        const lines = [
+            `### 🔄 ${value.workflow}`,
+            `- **ID**: \`${value.id || '-'}\`${value.totalRuns ? ` | **累计运行**: ${value.totalRuns} 次` : ''}`,
+        ];
+        if (value.recentRuns) {
+            lines.push('', '**最近运行:**', '```', value.recentRuns, '```');
+        }
+        return lines.join('\n');
+    }
+    // 3.4 Run View 详情
     if (args?.action === 'view' && value.databaseId) {
         const idLink = value.url ? `[${value.databaseId}](${value.url})` : `\`${value.databaseId}\``;
         const badge = formatCiBadge(value.status, value.conclusion);
@@ -292,6 +345,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\`\`\`` : '');
     }
@@ -303,7 +368,7 @@ export function renderRepoMarkdown(args, value) {
         const branch = value.defaultBranchRef?.name || value.defaultBranch || 'main';
         const lines = [
             `### 📦 ${link}`,
-            `> ⭐ **Stars**: ${stars} | 🍴 **Forks**: ${forks} | 🌿 **默认分支**: \`${branch}\``,
+            `> ⭐ **Stars**: ${stars} | 🍴 **Forks**: ${forks} | ⎇ **默认分支**: \`${branch}\``,
             value.description ? `\n${value.description}\n` : '',
         ];
         if (value.licenseInfo?.name || value.licenseInfo?.key) {
@@ -348,6 +413,75 @@ export function renderRepoMarkdown(args, value) {
             ...rows,
         ].join('\n');
     }
+    // 4.4 Issue/PR 搜索列表（search_issues / search_prs 共用，字段同构）
+    if (Array.isArray(value.items) && (args?.action === 'search_issues' || args?.action === 'search_prs')) {
+        if (value.items.length === 0)
+            return '未找到匹配的结果。';
+        const kind = args.action === 'search_prs' ? 'PR' : 'Issue';
+        const rows = value.items.map((it) => {
+            const num = it.number ?? '-';
+            const repo = it.repository?.nameWithOwner || it.repository?.fullName || '-';
+            const link = it.url ? `[#${num}](${it.url})` : `#${num}`;
+            const badge = formatStateBadge(it.state, it.isDraft);
+            const author = it.author?.login || '-';
+            const date = it.updatedAt ? String(it.updatedAt).slice(0, 10) : '-';
+            return `| ${link} | ${sanitizeCell(it.title, 45)} | ${badge} | ${repo} | ${author} | ${date} |`;
+        });
+        return [
+            `**${kind} 检索结果 (${value.items.length} 条):**\n`,
+            '| 编号 | 标题 | 状态 | 仓库 | 作者 | 更新日期 |',
+            '| :--- | :--- | :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 4.5 Commit 搜索列表（嵌套 commit.commit.message 取首行）
+    if (Array.isArray(value.items) && args?.action === 'search_commits') {
+        if (value.items.length === 0)
+            return '未找到匹配的提交。';
+        const rows = value.items.map((c) => {
+            const sha = `\`${String(c.sha || '').slice(0, 7)}\``;
+            const msg = sanitizeCell(String(c.commit?.message || '').split('\n')[0], 50);
+            const author = c.commit?.author?.name || c.author?.login || '-';
+            const repo = c.repository?.fullName || '-';
+            return `| ${sha} | ${msg} | ${author} | ${repo} |`;
+        });
+        return [
+            `**提交检索结果 (${value.items.length} 条):**\n`,
+            '| SHA | 提交信息 | 作者 | 仓库 |',
+            '| :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 4.6 目录清单（read_dir：dir 置顶 + size 人性化；mode 八进制是 Git 内部语义不展示）
+    if (args?.action === 'read_dir' && Array.isArray(value.items)) {
+        if (value.items.length === 0)
+            return `**${value.path || '/'}** 为空目录。` + appendDegradedNote(value);
+        const sorted = [...value.items].sort((a, b) => (a.type === b.type ? String(a.name).localeCompare(String(b.name)) : a.type === 'dir' ? -1 : 1));
+        const rows = sorted.map((e) => {
+            const icon = e.type === 'dir' ? '📁' : '📄';
+            const size = e.type === 'dir' ? '-' : (typeof e.size === 'number' ? (e.size > 1024 ? `${(e.size / 1024).toFixed(1)}KB` : `${e.size}B`) : '-');
+            return `| ${icon} \`${sanitizeCell(e.name, 60)}\` | ${size} |`;
+        });
+        return [
+            `**目录 ${value.path || '/'}（${value.items.length} 项）:**\n`,
+            '| 名称 | 大小 |',
+            '| :--- | :--- |',
+            ...rows,
+            appendDegradedNote(value),
+        ].filter((l) => l !== '').join('\n');
+    }
+    // 4.7 文件内容（read_file：代码块 + 元信息行）
+    if (args?.action === 'read_file' && typeof value.content === 'string') {
+        const ext = (value.path || '').split('.').pop() || '';
+        const size = typeof value.size === 'number' ? (value.size > 1024 ? `${(value.size / 1024).toFixed(1)}KB` : `${value.size}B`) : '-';
+        return [
+            `**📄 \`${value.path}\`** (${size}${value.ref ? ` @ ${value.ref}` : ''})\n`,
+            '```' + ext,
+            value.content,
+            '```',
+            appendDegradedNote(value),
+        ].filter((l) => l !== '').join('\n');
+    }
     // 兜底降级
     return JSON.stringify(value, null, 2);
 }

package/lib/tools/help.js

@@ -7,18 +7,22 @@ const KNOWLEDGE_BASE = {
 | :--- | :--- | :--- |
 | \`github_pr\` | Pull Request 管理、审查与本地检出 | 查看 PR 列表/详情、比对 diff、本地检出代码验证、检查 CI 状态、执行带确认合并 |
 | \`github_issue\` | Issue 任务追踪与分支开发关联 | 筛选待办议题、追加评论、编辑标题/标签、从 Issue 一键切出关联开发分支 |
-| \`github_run\` | GitHub Actions 构建排查与工作流管理 | 查看构建列表、提取失败日志 (log_failed)、重新触发、手动触发 workflow_dispatch |
-| \`github_repo\` | 仓库元数据、Fork 同步与全局检索 | 查看仓库与 topics、一键拉平 Fork 仓库 (sync)、检索全局代码与仓库 |
+| \`github_run\` | Actions 构建排查与工作流管理 | 查看构建列表、提取失败日志 (log_failed)、重新触发、手动触发 workflow_dispatch、启停工作流、下载构建产物 |
+| \`github_repo\` | 仓库元数据、Fork 同步与全局检索 | 查看仓库与 topics、一键拉平 Fork (sync)、检索代码/仓库/Issue/PR/提交、免 clone 读取任意文件与目录 |
 | \`github_api\` | 原生 GitHub REST/GraphQL 逃生门 | 调用任意端点、获取原始文件字节 (raw)、支持自动翻页 (paginate) |
 | \`github_release\` | 版本发布与构建资产交付 | 查看发版历史、自动生成 Release Notes、上传 .tgz 等构建产物 |
-| \`github_secret\` | CI/CD 部署密钥安全管理 | 查看 NPM_TOKEN 等密钥清单、经 stdin 安全写入密文、删除密钥 |
+| \`github_secret\` | CI/CD 密钥与变量管理 | 查看 NPM_TOKEN 等密钥清单、经 stdin 安全写入密文、删除密钥；kind:'variable' 管理明文变量（set/get/delete） |
 | \`github_skill\` | 跨 Agent 开源 Skills 生态发现 | 检索/预览/安装 GitHub 上的 Agent Skills (gh preview 特性) |
 | \`github_help\` | 路由导航、官方语法速查与故障自愈 | 遇到不确定的操作、搜索语法或接口报错时查询用法与诊断配方 |
 
-💡 **使用准则**：优先调用高层语义工具（pr / issue / run / repo / release / secret）；当高层工具无法满足特殊接口需求时，再降级使用 \`github_api\`。`,
+💡 **使用准则**：优先调用高层语义工具（pr / issue / run / repo / release / secret）；当高层工具无法满足特殊接口需求时，再降级使用 \`github_api\`。
+🗺️ **命令对照**：不确定某 gh 命令对应哪个工具？\`github_help(topic: 'mapping')\` 查询完整映射表（含未覆盖域的 API 引导）。`,
     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)\`
@@ -26,16 +30,35 @@ const KNOWLEDGE_BASE = {
 - **检查冲突状态**: \`github_pr(action: 'status')\`
   - 查看当前分支关联 PR 的 merge conflict 状态。
 - **安全合并**: \`github_pr(action: 'merge', pr_number: 123, confirm: true, merge_method: 'squash', delete_branch: false)\`
-  - 高危操作必须显式附带 \`confirm: true\`；若未传将返回拦截警告与待合并影响报告。`,
+  - 高危操作必须显式附带 \`confirm: true\`；若未传将返回拦截警告与待合并影响报告。
+- **Draft 切换**: \`github_pr(action: 'ready', pr_number: 123)\`；反向转回 Draft 附加 \`undo: true\`
+- **反向提交**: \`github_pr(action: 'revert', pr_number: 123, confirm: true)\`
+  - 在远端创建反向提交与新 PR（非本地操作），需 confirm。
+- **分支落后自愈**: \`github_pr(action: 'update_branch', pr_number: 123)\`
+  - 将基准分支最新提交同步进 PR 分支，解决「分支落后需更新」的 CI 门禁失败。`,
     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'])\`
 - **追加讨论**: \`github_issue(action: 'comment', issue_number: 42, body: '定位到问题原因...')\`
 - **安全关闭**: \`github_issue(action: 'close', issue_number: 42, confirm: true)\`
-  - 关闭操作必须附带 \`confirm: true\`。`,
+  - 关闭操作必须附带 \`confirm: true\`。
+- **物理删除**: \`github_issue(action: 'delete', issue_number: 42, confirm: true)\`
+  - 与 close 有本质区别：编号永久消失、评论湮灭、GraphQL 层无法恢复——拦截级别高于 close。
+- **跨仓库迁移**: \`github_issue(action: 'transfer', issue_number: 42, target_repo: 'other/repo', confirm: true)\`
+  - 原 URL 301 重定向，归属改变不可静默撤回。
+- **置顶**: \`github_issue(action: 'pin'/'unpin', issue_number: 42)\`（可逆状态位）
+- **锁定对话**: \`github_issue(action: 'lock', issue_number: 42, lock_reason: 'resolved')\`
+  - reason 合法值：off_topic / resolved / spam / too_heated；解锁用 \`action: 'unlock'\`（独立命令）。
+- **我的分配议题**: \`github_issue(action: 'status')\`（账号维度面板）`,
     run: `### 🚀 github_run 详细操作指南
 
 - **过滤构建记录**: \`github_run(action: 'list', branch: 'main', status: 'failure', limit: 10)\`
@@ -44,14 +67,30 @@ const KNOWLEDGE_BASE = {
   - 专为 Agent 优化的失败信息提取能力，直接定位报错位置；若无失败步骤则优雅提示。
 - **主动触发工作流**: \`github_run(action: 'trigger', workflow: 'pr-check.yml', ref: 'main', inputs: { env: 'staging' })\`
   - 提交代码修复后，主动触发远端 CI/CD 验证。
-- **重新执行失败任务**: \`github_run(action: 'rerun', run_id: '12345678')\``,
+- **重新执行失败任务**: \`github_run(action: 'rerun', run_id: '12345678')\`
+- **工作流查询**: \`github_run(action: 'workflow_list', all: true)\`
+  - 默认仅 active；\`all: true\` 含 disabled（排查「工作流为何不跑」时 disabled 本身就是答案）。
+- **工作流详情**: \`github_run(action: 'workflow_view', workflow: 'npm-publish.yml')\`（名称/ID/文件名均可定位）
+- **启停工作流**: \`github_run(action: 'workflow_enable'/'workflow_disable', workflow: '…')\`
+  - disable 后 trigger 将静默失败，直至重新 enable——输出会显式警告这一点。
+- **下载构建产物**: \`github_run(action: 'download', run_id: '12345678', name: '构建产物名'?)\`
+  - 落盘目录由插件固定管理（\`~/.dsh/data/dsh-github-flow/artifacts/\` 下按仓库与 run 隔离），返回文件清单。`,
     repo: `### 📦 github_repo 详细操作指南
 
 - **查看元数据与标签**: \`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')\``,
+- **代码检索**: \`github_repo(action: 'search_code', query: 'filename:package.json dsh.bundle')\`
+- **Issue/PR/Commit 检索**: \`github_repo(action: 'search_issues'/'search_prs'/'search_commits', query: 'repo:o/r state:open')\`
+  - 限定符直接写进 query（gh 惯例）；注意 commits 必须含搜索文本，纯限定符会被 gh 拒绝。
+- **免 clone 读单文件**: \`github_repo(action: 'read_file', path: 'src/index.ts', ref: 'dev'?)\`
+  - gh ≥2.95 直连；低版本自动降级 contents API（输出带降级标注）。二进制文件会被拒绝并引导 github_api。
+- **免 clone 列目录**: \`github_repo(action: 'read_dir', path: '.github/workflows'?)\`
+  - 返回目录清单（dir 置顶 + 大小），降级链路同上。`,
     api: `### ⚡ github_api 底层逃生门指南
 
 - **标准 GET 请求带参数**:
@@ -77,7 +116,9 @@ const KNOWLEDGE_BASE = {
 - **下载资产**: \`github_release(action: 'download', tag: 'v0.1.9', pattern: '*.tgz', dir: './dist')\`
 - **删除 Release**: \`github_release(action: 'delete', tag: 'v0.1.9', confirm: true)\`
   - 高危不可逆操作，必须显式确认。`,
-    secret: `### 🔐 github_secret 部署密钥管理指南
+    secret: `### 🔐 github_secret 密钥与变量管理指南
+
+支持两类对象（kind 分流）：**Secret**（密文，默认）与 **Variable**（CI 明文变量）。
 
 - **查看密钥清单**: \`github_secret(action: 'list')\`
   - 仅返回名称、可见性与更新时间；GitHub API 设计上就不允许读取密文。
@@ -87,7 +128,11 @@ const KNOWLEDGE_BASE = {
   - gh 在本地用仓库公钥加密后才上传，明文不落盘。
 - **组织/环境级密钥**: 附加 \`org: 'my-org'\` 或 \`env: 'production'\` 参数切换作用域。
 - **删除密钥**: \`github_secret(action: 'delete', name: 'NPM_TOKEN', confirm: true)\`
-  - 删除后引用该密钥的 CI 工作流会立即失败，务必先确认无工作流依赖。`,
+  - 删除后引用该密钥的 CI 工作流会立即失败，务必先确认无工作流依赖。
+- **变量操作（CI 明文）**: 附加 \`kind: 'variable'\`
+  - \`github_secret(action: 'set', kind: 'variable', name: 'DEPLOY_ENV', value: 'staging')\`——经 -b 直传（明文无 stdin 红线）。
+  - \`github_secret(action: 'get', kind: 'variable', name: 'DEPLOY_ENV')\`——可回显值（这正是变量与密钥的设计区别：secret 写入后 GitHub 侧加密，物理不可读取）。
+  - list/delete 与 secret 同形（delete 需 confirm）。`,
     skill: `### 🧠 github_skill Agent Skills 生态指南
 
 基于 GitHub CLI 的 \`gh skill\` preview 特性（需 gh >= 2.9x），跨仓库发现与安装开源 Agent Skills：
@@ -102,6 +147,93 @@ const KNOWLEDGE_BASE = {
   - 支持的 agent 值：claude-code / cursor / github-copilot / codex / gemini-cli 等。
 - **查看已安装**: \`github_skill(action: 'list')\`
 - ⚠️ 若报「unknown command」，说明宿主机 gh 版本过低，需升级到 2.9x 以上。`,
+    mapping: `### 🗺️ gh 命令 ↔ 插件工具映射总表
+
+#### 一、已覆盖域映射（语义化 action 精确对照）
+
+**PR（github_pr，13 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh pr list/view/create/diff/edit/comment\` | \`github_pr(action:'list'/'view'/'create'/'diff'/'edit'/'comment')\` | 高频基础操作 |
+| \`gh pr close\` | 暂无专用 action——用 \`github_pr(action:'edit')\` 或 \`github_api(endpoint:'repos/{o}/{r}/pulls/{n}', method:'PATCH', fields:{state:'closed'})\` | 插件侧未覆盖 |
+| \`gh pr checks\` | \`github_pr(action:'checks', pr_number:n)\` | CI 状态药丸 |
+| \`gh pr review\` | \`github_pr(action:'review', review_decision:'APPROVE'…)\` | |
+| \`gh pr merge\` | \`github_pr(action:'merge', confirm:true)\` | 高危确认 |
+| \`gh pr checkout\` | \`github_pr(action:'checkout')\` | 本地检出 |
+| \`gh pr status\` | \`github_pr(action:'status')\` | 当前分支关联 PR |
+| \`gh pr ready [--undo]\` | \`github_pr(action:'ready', undo:true?)\` | Draft↔Ready 可逆 |
+| \`gh pr revert\` | \`github_pr(action:'revert', confirm:true)\` | 远端创建反向 PR |
+| \`gh pr update-branch\` | \`github_pr(action:'update_branch')\` | 分支落后自愈 |
+
+**Issue（github_issue，16 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh issue list/view/create/comment/close/reopen/edit\` | \`github_issue(action:…)\` | 基础操作 |
+| \`gh issue develop\` | \`github_issue(action:'develop', branch_name:…)\` | 关联开发分支 |
+| \`gh issue delete\` | \`github_issue(action:'delete', confirm:true)\` | 物理删除（非 close） |
+| \`gh issue transfer\` | \`github_issue(action:'transfer', target_repo:…, confirm:true)\` | 跨仓库迁移 |
+| \`gh issue pin/unpin\` | \`github_issue(action:'pin'/'unpin')\` | 置顶状态位 |
+| \`gh issue lock/unlock\` | \`github_issue(action:'lock', lock_reason:'resolved'…)\` | reason 四枚举 |
+| \`gh issue status\` | \`github_issue(action:'status')\` | 我的分配议题面板 |
+
+**Actions（github_run，11 action）——注意 workflow 域也在此工具**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh run list/view/rerun/cancel\` | \`github_run(action:…)\` | |
+| \`gh run view --log-failed\` | \`github_run(action:'log_failed', run_id:…)\` | 失败日志提取 |
+| \`gh run download\` | \`github_run(action:'download', run_id:…)\` | 落盘插件管理目录 |
+| \`gh workflow run\` | \`github_run(action:'trigger', workflow:…)\` | workflow_dispatch |
+| \`gh workflow list/view\` | \`github_run(action:'workflow_list'/'workflow_view')\` | all:true 含 disabled |
+| \`gh workflow enable/disable\` | \`github_run(action:'workflow_enable'/'workflow_disable')\` | disable 后 trigger 静默失败 |
+
+**Repo（github_repo，10 action）——注意 search 域也在此工具**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh repo view\` | \`github_repo(action:'view')\` | 元数据 |
+| （README 读取，gh 无专用命令） | \`github_repo(action:'readme', repo:…)\` | 原文 + 图片清单/下载（插件独有） |
+| \`gh repo sync\` | \`github_repo(action:'sync', force:true?)\` | Fork 对齐 |
+| \`gh repo read-file\` | \`github_repo(action:'read_file', path:…)\` | 免 clone 读文件，gh<2.95 自动降级 API |
+| \`gh repo read-dir\` | \`github_repo(action:'read_dir', path:?)\` | 目录清单，同上降级 |
+| \`gh search code/repos\` | \`github_repo(action:'search_code'/'search_repos')\` | |
+| \`gh search issues/prs/commits\` | \`github_repo(action:'search_issues'/'search_prs'/'search_commits')\` | 限定符写进 query |
+
+**Release（github_release，6 action）**
+\`gh release list/view/create/upload/download/delete\` → \`github_release(action:…)\`；delete/clobber 需 confirm。
+
+**Secret 与 Variable（github_secret，kind 分流）——注意 variable 域也在此工具**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh secret list/set/delete\` | \`github_secret(action:…)\` | 密文走 stdin，永不回显 |
+| \`gh variable list/set/get/delete\` | \`github_secret(action:…, kind:'variable')\` | CI 明文：-b 直传、get 可回显 |
+| （gh secret get 不存在） | — | GitHub 侧加密存储，物理不可读取 |
+
+**Skill（github_skill，4 action）**
+\`gh skill search/preview/install/list\` → \`github_skill(action:…)\`；install 需 confirm（写磁盘）。
+
+#### 二、归属提示（命令域与工具名不同构）
+
+- \`gh workflow …\` / \`gh search …\` / \`gh variable …\` 分别归 **github_run / github_repo / github_secret**（不是独立工具）
+- \`gh api\` 的等价物是 \`github_api\`（全端点逃生门，支持 raw/paginate/jq）
+- 图片查看：\`github_issue\`/\`github_pr\` 的 \`view_images\`、\`github_repo\` 的 \`readme\` + image_urls（插件独有能力，gh 无对应命令）
+
+#### 三、未覆盖域引导（经 github_api 调用）
+
+| gh 域 | 用途 | 推荐 REST 端点 |
+| :--- | :--- | :--- |
+| \`gh label\` | 标签管理 | \`repos/{o}/{r}/labels\` |
+| \`gh cache\` | Actions 缓存 | \`repos/{o}/{r}/actions/caches\` |
+| \`gh gist\` | 代码片段 | \`gists\` |
+| \`gh ruleset\` | 分支保护规则 | \`repos/{o}/{r}/rulesets\` |
+| \`gh project\` | Projects v2 | \`graphql\`（Projects API 仅 GraphQL） |
+| \`gh discussion\` | 讨论 | \`graphql\`（需仓库开启 discussions） |
+| \`gh codespace\` | 云端开发环境 | \`user/codespaces\` |
+| \`gh org\` | 组织信息 | \`orgs/{org}\` |
+| \`gh auth/config/extension/alias\` | 本机配置类 | 多数无需 API（本机文件/命令） |
+| \`gh browse\` | 打开浏览器 | 直接给用户 URL 即可 |
+| \`gh attestation/gpg-key/ssh-key\` | 签名与密钥 | \`repos/{o}/{r}/attestations\` 等 |
+| \`gh agent-task\` | Copilot 会话 | \`graphql\`（需 Copilot 授权） |
+
+> 用法示例：\`github_api(endpoint: 'repos/owner/repo/labels', method: 'POST', fields: { name: 'bug', color: 'ff0000' })\``,
     search_syntax: `### 🔍 GitHub 官方高级检索语法速查手册
 
 在 \`github_repo\`、\`github_api\` 或搜索场景中，请严格遵守 GitHub 官方搜索语法：
@@ -154,10 +286,11 @@ export function createHelpTool(executor) {
                         'release',
                         'secret',
                         'skill',
+                        'mapping',
                         'search_syntax',
                         'troubleshooting',
                     ],
-                    description: '帮助主题分类。留空则返回全局工具箱导航。',
+                    description: '帮助主题分类。mapping 提供 gh 命令与插件工具的完整对照表（不确定某 gh 命令对应哪个工具时查询）。留空则返回全局工具箱导航。',
                 },
                 gh_command: {
                     type: 'string',

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[];