后端认证鉴权前端【免费下载链接】hexclaveThe user infrastructure platform. You choose the frontend, backend, and database. Hexclave handles everything else.项目地址https://gitcode.com/gh_mirrors/stack/hexclave点击查看免费下载导读视觉证据是代码评审中最有说服力的沟通形式而一张结构清晰、可复现的截图对比表比一段文字描述更能让评审者快速理解「这次改动改了什么」。本文以 Hexclave 仓库中.agents/skills/pr-visual-writeup技能内置的 PR 正文模板为骨架完整讲解视觉密集型 GitHub PR 描述的撰写方法从 Summary、Scope 到旗舰页的 Light/Dark × Before/After 二维截图矩阵再到长尾页面的紧凑表格、alt text 与配对规则。读完本文你将掌握一套可直接落地的「截图 → 托管 → 排版 → 提交」流水线并了解其背后的并行捕获、红框标注、滚动 GIF 与 gist 托管实现。模板在整体工作流中的定位该模板并非孤立文档而是pr-visual-writeup技能流水线中「撰写与提交」阶段Phase 5的骨架。整个技能把一次视觉化 PR 写作用划分为六个阶段Scope——确定 PR 号、仓库、改动的 UI 路由、开发服务器端口、登录方式、新增 UI 的选择器以及基线分支Capture——先对 head 分支做「after」并行捕获页面 × 主题 × 视口再切换到 base 分支做「before」捕获Process——并行把滚动视频 WebM 转成可内联播放的 GIFUpload——用 PAT 将全部素材推入一个公开 gist取得 raw URLCompose set——按本模板编写 Markdown 正文用gh pr edit --body-file写回 PRRestore——恢复用户的原始分支与 stash让工作区回到原状。模板对应的references/目录下共有三个配套文档pr-body-template.md正文结构、capture-patterns.md截图捕获配方、gist-upload.md素材托管配方另有三个可直接调用的脚本detect_dev_server.sh、convert_clips.sh、upload_gist.sh。模板开篇就声明了它的性质「Markdown structure for a visual-heavy PR description. Adapt freely — these are patterns, not a rigid form.」——这是一套可自由改编的「模式」而非必须逐字照抄的「表单」。正文顶部模板Summary 与截图矩阵Summary 段落正文第一块是 Summary要求用12 段话说明这个 PR 做了什么、为什么做而不是罗列 commit 列表。紧接着给出两条结构化信息**Base:** base → **Head:** head **Scope:** N files, ~Mk additionsBase → Head用一条箭头交代分支流向例如dev→feature/xxx评审者一眼就能看出 diff 的方向Scope文件数与新增代码量用于快速评估 PR 体积属于纯信息性指标无需展开解释。Screenshots 区块的完整骨架模板给出了从头部到滚动行为节的完整 Markdown 骨架## Screenshots Captured from the local dev server (viewport: **W×H** standard, **W2×H2** widescreen). Assets hosted in this gist. Red outlines on the after shots mark the new or changed UI introduced by this PR. ### Flagship page 1 — short descriptor | | Before | After | | --- | --- | --- | | Light | page-before-light | page-after-light | | Dark | page-before-dark | page-after-dark | Widescreen: | | Before | After | | --- | --- | --- | | Light | page-before-light-wide | page-after-light-wide | | Dark | page-before-dark-wide | page-after-dark-wide | ### Flagship page 2 ...same before/after pattern... ### Other migrated surfaces (after only) | Page | Light | Dark | | --- | --- | --- | | name | page-after-light | page-after-dark | | name | page-after-light | page-after-dark | ### Optional: scroll behaviour / sticky header / interactions | Page | Light | Dark | | --- | --- | --- | | name | page-scroll-light | page-scroll-dark |拆开来看这个骨架由四层信息构成来源与图例声明截图来自本地开发服务器、标准视口与宽屏视口的尺寸并标注素材托管位置随后的引用块说明after 图上的红色轮廓标记本次 PR 新增/改动的 UI旗舰页Flagship每个旗舰页独占一个 H3 小节内含标准视口下的 2×2 表格行 Light/Dark列 Before/After以及单独的宽屏表格长尾页Long-tail以「Page | Light | Dark」紧凑表格汇总仅放 after 图可选交互节适合表格、长列表、吸顶 header 等需要展示滚动行为的页面用 Light/Dark 两张 GIF 呈现。在 Hexclave 的具体实践中文件名与表格单元格一一对应after 截图文件名形如route-after-light.png/route-after-dark[-wide].pngbefore 截图形如route-before-light[-wide].png参见SKILL.md中 Phase 2 的文件名约定这意味着只要命名规范表格里的图片 URL 几乎可以机械地从截图目录生成无需人工一一对应。视觉之外不可省略的三段常规内容模板特别强调视觉内容之后必须补上常规 PR 应有的全部内容——Whats new、Notes for reviewers、Test plan。原文档给出了非常明确的告诫Everything normal for a PR body:Whats new,Notes for reviewers,Test plan. Dont skip these — the visuals sell the PR but reviewers still need a map of the code.翻译成实操要求就是截图负责「说服」文字负责「指路」。一个 90% 是截图、10% 是文字的 PR 正文读起来像营销文案而不是工程沟通评审者需要知道改了什么、哪些地方需要重点看、以及如何验证。旗舰页与长尾页的选择标准模板给出了一套非常实用的「分配资源」策略旗舰页Flagship待遇——独立小节、附带宽屏变体、可选滚动 GIF本次 PR 中内容最丰富的页面评审者最可能第一时间打开的页面通常控制在35 个以内——超过这个数量正文就会变得嘈杂。长尾页Long-tail待遇——在「Other surfaces」表格中占一行同模式页面截图里大部分是既有 dashboard 骨架chrome空状态或近乎空白的页面seed 数据未能填充。这套取舍的核心是信息密度的控制把最「有戏」的页面做成大图展示把「没差别」的页面压缩进表格让 PR 正文在可读性与完整度之间取得平衡。Alt text 规则文件名即描述模板规定 alt text直接使用基础文件名例如users-after-light可搜索greppable、一致性高图片加载失败时仍能显示有意义的文字before/after标记至关重要如果 gist 被清空评审者仍能凭 broken-image 的 alt 分辨表格中每个单元格对应的是改动前还是改动后。这一规则与前述文件名约定形成闭环捕获阶段的命名规范直接决定了 PR 正文阶段 alt text 的质量。Before/After 配对规则配对是整张截图矩阵的逻辑基石模板给出了三条硬规则每个旗舰节的 after 图必须配对同一主题、同一视口的 before 图——保证 Light/Dark、标准/宽屏四个维度上「改动前后」严格可比没有 before 的情况全新路由使用单行「After only」表格并在下方注明*New route — no base equivalent.*全新路由——没有基线对等物长尾页 before/after 像素级一致的情况纯重构、未触及该表面直接把这页从正文里删掉不要用无意义的空对填充。这三条规则的共同目的是杜绝「为了凑数而配对」——截图矩阵的每一格都应当携带评审者需要的新信息。不要这样做四条反模式模板的「Dont do these」清单是实践中最容易踩的坑逐条展开不要内嵌 20 张图片UI 页面多时应该分成少数几个旗舰页 一个长尾表而不是铺一面图片墙不要混用托管源如果一部分图片放在user-attachments、另一部分放在 gist评审者无法理解原因且混用显得草率。选定一种托管方式并保持一致不要忘记非视觉部分90% 截图 10% 文字 营销文案不是工程沟通不要用 HTMLvideo或details嵌视频GitHub 对两者都会做清理除非视频放在user-attachments。正确做法是使用GIF以图片形式内联渲染。截图捕获流水线模板背后的实现模板假设你手上已经有一批高质量的截图而pr-visual-writeup技能在capture-patterns.md中给出了产出这批截图的具体配方。理解这些配方才能让 PR 正文里的表格真正「可复制、可复现」。并行捕获矩阵捕获阶段按主题 × 视口拆成多个并行子代理各自持有独立的--session-name浏览器会话after-light-standard/after-dark-standard1920×1200红色边框标注开启after-light-wide/after-dark-wide2560×1440仅旗舰页。关键约束是并行发生在子代理之间而不是单个会话之内——一个agent-browser会话只有一个导航上下文无法并发打开两个 URL。文件名后缀统一为-before-theme[-wide].png与-after-theme[-wide].png供 Phase 5 配对使用。等待页面真正就绪在 Next.js 开发模式下networkidle不足以判断页面可截图——按需编译on-demand compiler和骨架占位skeleton都在 networkidle 之后才完成。wait-for-ready配方给出了一个 30 秒硬上限的轮询门控逐项检查document.readyState completeNext.js 编译指示器#__next-build-watcher、[data-nextjs-dialog]不存在正文不匹配^Compiling\b|building...无加载占位[data-loadingtrue]、[aria-busytrue]、.skeleton无 Tailwindanimate-pulseHexclave dashboard 中加载行的主力骨架信号连续两次 250ms 轮询读取到的 body HTML 长度一致——单次 ready 闪烁可能落在骨架消失与真实内容换入之间两次连续稳定读取才能确认 DOM 真正稳定。wait-for-ready返回ok后还需再睡约 300ms让滑入、淡入等最终动画落到静止帧。另外正式捕获前每个子代理都要对自己的路由做一次warm-up 遍历把按需编译的成本支付给一次「炮灰」访问第二次访问才能截出干净画面。红色边框标注pr-visual-highlight 注入器after 截图要标出新增 UI注入器通过一段页面内脚本完成const selectors $SELECTORS_JSON; // e.g. [[data-testidfoo], section:has( h2)] document.getElementById(pr-visual-highlight)?.remove(); const style document.createElement(style); style.id pr-visual-highlight; style.textContent selectors.map(s ${s} { outline: 3px solid #ef4444 !important; outline-offset: 2px !important; border-radius: 6px; box-shadow: 0 0 0 1px rgba(239,68,68,0.25) !important; }).join(\n); document.head.appendChild(style); return Array.from(document.querySelectorAll(selectors.join(,))).length;设计细节值得注意用outline而不是border——border会改变布局、破坏与 before 图的像素对齐outline绘制在盒子外部亮红#ef4444Tailwindred-500在深浅两套主题下都可读不随主题切换颜色保证一致性优先于对比度微调!important覆盖应用自身在 focus/hover 时设置的 outline注入器返回匹配元素数量若返回0说明选择器已失效应记录告警并为该路由跳过高亮而不是发一张与 before 毫无差别的 after 图路由间必须移除style idpr-visual-highlight避免样式经缓存泄漏到下一页。主题切换与视口设置优先点击应用内的主题切换按钮用agent-browser snapshot -i | grep -i theme定位再用document.documentElement.className验证期望的 class 已生效直接改 class 可能无法触发应用级主题水合rehydration导致下次导航时闪烁。视口通过agent-browser set viewport 1920 1200标准与agent-browser set viewport 2560 1440宽屏设置且必须在登录之后设置——部分登录流程在宽视口下会有不同的响应式渲染。滚动动画逐帧截图 ffmpeg 拼接不要使用agent-browser record——它创建全新的浏览器上下文会丢失开发模式的登录态。正确做法是先定位 dashboard 布局内的内部滚动容器侧栏 固定 header 可滚动主区通常不能直接滚动windowagent-browser eval (() { const el Array.from(document.querySelectorAll(*)).find(x { const s getComputedStyle(x); return (s.overflowY auto || s.overflowY scroll) x.scrollHeight x.clientHeight 100 x.clientHeight 400; }); window.__SCROLL_EL__ el; if (el) el.scrollTop 0; return !!el; })()window.__SCROLL_EL__被暂存后后续滚动调用变成一行命令按0, 100, ..., 900步进滚动 → 每步睡 150ms → 截图一帧 → 再反向滚回最后用 ffmpeg 拼接ffmpeg -y -framerate 8 -i /tmp/frames/frame-%03d.png \ -c:v libvpx-vp9 -crf 32 -b:v 0 /tmp/pr-N-visuals/clips/name-scroll-theme.webm滚动动画只挑 23 个最有代表性的页面做而不是每页都做。素材托管gist PAT全程不碰浏览器 Cookie截图与 GIF 的托管方式决定了正文里的图片能否内联渲染。.agents/skills/pr-visual-writeup/references/gist-upload.md给出了完整的 PAT-only 方案核心权衡是GitHub 的user-attachments端点拖拽上传图片时会用到需要浏览器会话 Cookie其权限范围比 PAT 更宽除非用户明确同意不应使用gist 托管只需 PATgh gist create只需要gistscopegit push只需 PATgist.githubusercontent.com/user/id/raw/file形式的 URL 能在 PR 正文中内联渲染为图片/GIF。完整上传流程gist 的 raw URL 可直接作为正文表格里的url# 1. 创建公开 gist GIST_URL$(gh gist create --public --desc PR #N screenshots scroll clips \ -f README.md - PR #N assets | tail -1) GIST_ID$(basename $GIST_URL) # 2. 本地克隆 git clone https://gist.github.com/$GIST_ID.git gist-$GIST_ID # 3. 拷贝全部素材并提交 cp /tmp/pr-N-visuals/shots/*.png /tmp/pr-N-visuals/clips/*.gif ./ git add -A git -c user.emailnoreplygithub.com -c user.nameyour-username \ commit -m Add PR N visuals # 4. 用 credential helper 喂 PAT 推送 TOKEN$(gh auth token) git -c credential.helper \ -c credential.helper!f() { echo usernameyour-username; echo password$TOKEN; }; f \ push其中credential.helper先清空既有 helper再用自定义 helper 喂入 PAT避免把 token 写进~/.gitconfig或凭据存储。仓库里的upload_gist.sh脚本把以上流程封装为一行upload_gist.sh PR #1338 visuals /tmp/pr-1338-visuals/shots /tmp/pr-1338-visuals/clips输出每行basename\traw-url并把 gist id 存到./gist-id.txt供后续重推。上传后应当使用不带 commit SHA 的 raw URL——/raw/file始终解析到最新版本这意味着更新某张截图后无需改动 PR 正文。嵌入前用curl -sI -L raw-url抽查一个资源确认返回HTTP/2 200且 content-type 为image/png或image/gif。文件大小红线gist 单文件上限为 10 MB总量控制在 10 MB 左右比较稳妥GIF 膨胀极快应通过fps8、scale960、时长 5 秒把单支 GIF 压在 100400 KB——这正对应convert_clips.sh的默认参数其 ffmpeg 命令还使用palettegen/paletteuse双通道调色板来优化 GIF 画质。gist 清理用gh gist delete $GIST_ID但删除会破坏 PR 正文中的所有图片链接通常落地后保留即可。落库gh pr edit与工作区布局正文组合完成后通过以下命令写回 PRgh pr edit N --body-file path-to-md若 PR 位于公开仓库推入前需与用户确认这是共享状态操作个人 fork 或 draft PR 可直接执行。整个流程的中间产物统一放在/tmp/pr-N-visuals/工作区/tmp/pr-N-visuals/ ├── scope.md # Phase 1 输出 ├── shots/ # 捕获的 PNG ├── clips/ # webm gif 滚动动画 ├── body.md # 组合好的 PR 描述 ├── gist-id.txt # 后续追加截图时重推用 ├── urls.txt # 每个文件的 raw URL ├── orig-branch.txt # Phase 1.5 记录的原分支 └── stash-ref.txt # Phase 1.5 记录的 stash refPR 正文设置完成后PNG/GIF 永久保存在 gist 中本地副本可删可留——如果想迭代重拍保留更稳妥。结合 Hexclave 仓库的落地要点把模板落进 Hexclave 的实际 PR 流程时有几个仓库特有的注意点路由识别Phase 1 用gh pr diff N --name-only过滤出页面文件Next.js 项目关注**/page*.tsx/**/*page-client.tsx再按 App Router 约定映射 URL 路径只改后端/共享组件且没有明显 UI 表面的改动直接忽略骨架信号Hexclave dashboard 大量使用 Tailwind.animate-pulse作为加载行占位——这是wait-for-ready选择器列表中信号最强的一项实际使用时还应结合本次 diff 补充项目特有加载标记如Spinner组件类名开发服务器定位detect_dev_server.sh遍历 node 监听的端口并读取页面title输出port\ttitle\turl帮助你在 dashboard、API、docs、mock-OAuth 多个并行进程中准确选出要截图的那一个并行登录的边界若 mock-OAuth 服务器串行处理登录或总共只有 12 个页面就不值得做并行扇出——按原样串行执行即可。总结pr-body-template.md的价值不在于它是一份「标准表单」而在于它把「如何让评审者高效理解一次 UI 改动」抽象成了一组可复用模式Summary Base/Head Scope 的头部三要素、旗舰页 2×2 截图矩阵 宽屏变体、长尾页紧凑表、可选滚动 GIF 节以及 alt text、before/after 配对与反模式清单。配合capture-patterns.md的捕获配方与gist-upload.md的 PAT-only 托管方案它形成了一条从「diff 到截图、从截图到正文、从正文到 PR」的完整链路。实际写作时记住三条底线每个表格单元格都要携带新信息宁缺毋滥、每张 after 图都要有可比的 before 基线新路由要显式标注、每个 PR 都不能只有图而没有文字地图。赞分享后端认证鉴权前端【免费下载链接】hexclaveThe user infrastructure platform. You choose the frontend, backend, and database. Hexclave handles everything else.项目地址https://gitcode.com/gh_mirrors/stack/hexclave点击查看免费下载相关推荐Hexclave PR 可视化撰写基于 GitHub Gist 与 PAT 的截图/GIF 托管方案Hexclave PR 可视化撰写基于 GitHub Gist 与 PAT 的截图/GIF 托管方案 在 Hexclave 仓库的 pr visual wri后端认证鉴权前端为 GitHub PR 添加 before/after 视觉证据Sanity 仓库 before-and-after Skill 与 format.mjs 实战指南为 GitHub PR 添加 before/after 视觉证据Sanity 仓库 before and after Skill 与 format.mjs 实CMS前端GitBook 开源仓库 PR 描述写作指南基于 write-pr-description Skill 的规范与实践GitBook 开源仓库 PR 描述写作指南基于 write pr description Skill 的规范与实践 本指南围绕 GitBook 开源仓库G前端后端知识管理上一篇【亲测免费】 探索神奇宝贝世界的宝藏——Pokedex.org下一篇探索数据库管理新维度Visual Studio Code 的强力工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考