用途
pr-artifact-explorer 是一个画布(canvas),用于向用户展示 Pull Request、Issue、工作流运行、Actions 制品以及网页。它把 GitHub 上的这些对象集中到一个可交互的面板中查看、分享和预览。
主要能力
- 打开目标:支持 GitHub PR/Issue 的 URL 或 owner/repo#123 形式(Issue 仅显示详情);支持 Actions 链接与无需 PR 的请求,例如 https://github.com/<owner>/<repo>/actions(含 ?query=event%3Aschedule、/actions/workflows/<file>.yml)、https://github.com/<owner>/<repo>/actions/runs/<run>、owner/repo actions、owner/repo run 123、show scheduled runs in owner/repo。
- 制品:支持真实制品永久链接(https://github.com/<owner>/<repo>/actions/runs/<run>/artifacts/<id>)、带仓库的制品 ID,或共享的 explorer 链接/路由,如 #/docs、#/artifact/owner%2Frepo/0/456?file=index.html、#/browser?v=...。
- 网页预览:支持 http(s):// 与 localhost URL 的浏览器预览。
- 自然语言:接受有界自然语言,例如 open PR 123 in owner/repo、show localhost:3000 on mobile、go back、zoom 150%、tablet、1280x720、screenshot。
- 分享:share 动作可生成链接、路由和文本交给用户;制品分享保留仓库/制品/文件身份(而非预览端口),接收者将其粘贴到画布或 open_target 中。
- 无 PR 的工作流运行:许多运行没有 PR,如 schedule(cron)、workflow_dispatch、push、release、workflow_run 等。可用 open_runs { repository, event?, status?, branch?, workflow?, excludePullRequests?, hasArtifacts? } 打开仓库的 Workflow runs 列表(例如 event: "schedule" 查看 cron 运行;excludePullRequests 与 hasArtifacts 默认为 true,传 false 可包含 PR 运行或无制品运行),用 open_run { repository, runId } 打开单个运行及其制品。制品预览、Browser 视图、分享与 Re-run 行为相同;从运行打开的制品保留 ?run=<id> 路由,便于面包屑返回该运行。运行行显示懒加载的制品数量;分支过滤器自动补全真实分支。路由使用 nopr=0 和 artifacts=0 关闭这些默认值。
- 制品检查:inspect_artifact { repository, artifactId } 启动后台任务。下载可超过软限制;达到限制时提示用户设置更大值(set_limit { kind, value },值必须不小于实时进度)。用 job_status 检查状态;中断或失败后用 retry_job(已完成的 ZIP 会被复用),仅在要求时用 cancel_job。绝不执行制品中的程序或构建脚本:制品仅作为静态站点和文件被检查或预览。
- 重新运行:重新运行产生制品的工作流是仅限 UI、需用户确认的操作(制品行或运行页上的 Re-run 按钮)。不要自行尝试或调用其 API;若用户想要新制品,告知其使用该按钮。它复用原始 commit、ref 和 actor,限制为 30 天和 50 次重跑,且只请求一次运行,不保证制品就绪。
- 浏览器预览:navigate_browser { url, preset?, zoom? } 打开 http(s) URL(含 localhost);set_viewport { preset: native | mobile | tablet | desktop | custom, width?, height?, orientation? } 设置模拟页面尺寸;set_zoom { zoom, fit? } 缩放视图而不改变视口;screenshot { mode?: "fresh" | "controlled", url?, preset?, width?, height?, fullPage? } 生成真实 Chromium PNG,保存在会话的 files/artifact-explorer-screenshots 文件夹。fresh(默认)重新渲染 URL 并标记为 fresh-render;controlled 捕获实时隔离的 Chromium 页面(controlled-current)。controlled_navigate { url, preset?, ... }、controlled_back、controlled_forward、controlled_refresh、controlled_close 驱动一个隔离的 Chromium(内存配置文件,无登录状态)并具有真实历史;用于阻止 iframe 的站点。导航失败以错误返回,绝不返回空白页。若缺少 Playwright 或 Chromium,将返回的设置说明转达给用户(包括针对已弃用 PR_ARTIFACT_EXPLORER_PLAYWRIGHT 变量的 playwright_config_unsupported 错误);绝不静默安装。禁止框架的页面(X-Frame-Options / CSP)会被报告,不会被绕过。
- 文件预览:上下文 Browser view 动作仅对静态站点 HTML 制品出现在预览工具栏,不是全局导航项。可直接用 open_target / navigate_browser 或 #/browser?v=... 路由打开 URL。.webm、.mp4 和 .mov 使用原生 <video controls> 并支持范围跳转(整个条目先做一次 CRC/大小校验,之后复用)。编解码支持取决于浏览器(WebM VP8/VP9 最可靠;H.264 MP4/MOV 可能无法播放),失败时显示说明并提供下载回退。每个文件在 Download 旁有紧凑的 Preview / Raw 切换(路由中为 &view=raw)。Raw 对文本显示精确源码,对二进制显示有界、带标签的部分十六进制+ASCII 视图;不安全/加密条目会解释原因并保留 ZIP 下载。
- 主题:浏览器外壳和自有制品 HTML 遵循继承的画布主题(初始和实时变化);受控 Chromium 和截图遵循当前配色方案。外部站点保留自己的主题。
- 在默认浏览器中打开(Sharing and help 菜单)会在操作系统浏览器中启动当前 http(s) 目标。自有制品站点由本画布的 loopback 服务器提供,画布关闭时停止。
- JUnit XML(testsuites/testsuite 根)渲染原生报告,含总计、状态过滤、搜索以及失败/错误/跳过/stdout/stderr 详情;XML 源码和下载仍可用。格式错误的报告回退到源码并显示错误;其他 XML 使用通用查看器。
使用方式
以下动作名(open_target、share 等)是画布动作,不是独立工具。始终:
- 调用 list_canvas_capabilities { canvasId: "pr-artifact-explorer" } 发现动作及其结构。
- 调用 open_canvas { canvasId: "pr-artifact-explorer", instanceId: "<你选择的句柄>" } 打开或聚焦面板。
- 用同一 instanceId 调用 invoke_canvas_action { instanceId, actionName, input }。
打开目标:用 open_target { input }(或 open 输入 repository、pullNumber、runId、artifactId、url、route、view: "runs" 配合运行过滤器,以及 preset/width/height/zoom)。
恢复
若画布行为异常,调用 restart_canvas:它保留端口、令牌和正在运行的任务。用 docs 打开内置 Docs 标签页,其中也列出键盘快捷键(按 ?)。
适用场景与限制
适用于查看和分享 GitHub PR、Issue、工作流运行与 Actions 制品,以及预览本地或 HTTP(S) 网页、生成截图、查看 JUnit XML 报告。限制包括:制品仅作静态检查或预览,绝不执行其中的程序或构建脚本;重新运行工作流只能由用户在 UI 中确认,且限制为 30 天和 50 次重跑;禁止框架的页面不会被绕过;视频编解码支持取决于浏览器;缺少 Playwright 或 Chromium 时不会静默安装。