RepoCover 是做什么的?
创建仓库特定的社交预览图,确保在缩略图大小时依然清晰可读。优先采用确定性的、可编辑的组合方式,而非通用生成的横幅。
产品不变量
- 输出精确的
1280×640光栅图,通常为 PNG 格式,体积小于1,000,000字节。 - 在光栅图旁保留可编辑的源文件,通常为 SVG 格式。
- 所有可见声明、指标、截图和证据均基于仓库实际内容。
- 保留仓库的独特性,而非强加某种统一风格。
- 在浅色和深色背景下验证完整尺寸及
320×160缩略图效果。 - 将图像创建与 GitHub 上传视为独立的授权边界。
- 不暗示与 GitHub 有关联或背书。
加载正确的参考资料
每张封面都需要读取以下两个文件:
references/common-quality.md通用组合规则与否决标准。references/design-ledger-template.md证据、设计与验证记录模板。
然后根据实际情况,仅读取适用的路径:
- 当仓库存在屏幕截图、运行时捕获、Logo、插图、SVG、精灵图、纹理或其他有意义的视觉元素时,读取
references/source-material.md。 - 当没有可用的屏幕截图、运行时捕获、品牌标志或仓库自有的主要视觉元素时,读取
references/cold-start.md。 - 当刷新现有封面、比较候选方案或生成批量版本时,读取
references/version-regression.md。
不要仅仅因为某个路径存在就加载不相关的参考资料。references/design-recipes.md 仅作为旧版提示词的兼容索引。
工作流程
1. 检查并界定证据范围
读取适用的 AGENTS.md 文件、README、包元数据、有意义的源代码路径、视觉资源以及任何现有的社交预览图。确定:
- 仓库名称和主要用户任务;
- 一个具体的价值主张;
- 最多三个证据点;
- 最有力的产品证据;
- 已建立的视觉风格和需要排除的次要事实;
- 证据模式:
remote-static、local-static、build-tested或runtime-tested。
切勿在仅检查静态证据时,暗示已执行构建、运行时、场景或测试。如果 GitHub 的图像要求可能已变更,请根据官方 GitHub 文档进行验证。
对于远程仓库,使用可用的公共或经过身份验证的 GitHub 证据来检查其 README、目录树、清单文件、有意义的源代码、当前预览图以及最强的视觉资源。将输出保存在持久的用户可访问目录中,并记录源 URL 和声明边界。如果无法访问运行时或代表性界面,应说明此限制,而非假装远程证据等同于可工作的本地预览。可预览的本地项目(尤其是带有现有界面的 Web 项目)通常能提供最丰富的视觉证据。
2. 编写台账并选择路径
在开始绘图之前,根据附带的模板创建设计台账。至少记录:
- 承诺、证据、排除项;
- 证据模式及声明边界;
- 源材料诊断或冷启动语义骨架;
- 选择的生产路径和解释路径;
- 素材、资产角色、布局和线条决策;
- 输出版本、验证及推广判定(如适用)。
选择能保留仓库特色且规模最小的生产路径:
- 代码原生 SVG(首选): 适用于开发者工具、图表、Logo、库和推断出的视觉系统。
- 截图或源码混合: 仅当诊断后,自包含的源制品仍是最清晰的证据时才使用。
- 插画混合: 仅当插画是仓库身份的核心时使用;生成不包含重要文字的插画,并在 SVG 中叠加精确的文本。
不要为了模仿已有的矢量系统而调用图像生成。
3. 构建并版本化可编辑源文件
默认输出路径为 docs/social-preview.svg 和 docs/social-preview.png,除非仓库有明确的资产约定或用户指定了其他目录。
- 使用
1280 640的 viewBox 和全画布背景。 - 将关键内容保持在约 72 像素的外部安全区域内。
- 将文案、产品证据、说明和签名划分为不重叠的区域。
- 使用系统字体,除非仓库提供了合适的授权字体。
- 嵌入本地证据或使用确定的 SVG 基元再现;避免外部运行时依赖。
- 将图表、截图、重复标记和波形图裁剪到其所属区域内。
- 除非明确要求替换,否则保留现有封面并创建带版本号的姊妹文件。
4. 机械渲染与验证
当 Sharp 可用时,使用附带的脚本进行渲染:
node <skill-directory>/scripts/render_svg.mjs <source.svg> <output.png>
仅在明确要求替换命名输出时使用 --force。在 Codex Desktop 中,加载工作区依赖项,并通过 NODE_PATH 使用返回的 Node 可执行文件和包路径;未经许可不得安装依赖项。
验证 PNG 和 SVG:
python <skill-directory>/scripts/validate_preview.py <output.png> --svg <source.svg>
创建标准缩略图检查表:
node <skill-directory>/scripts/create_review_sheet.mjs <preview.png> <review.png>
在 Windows 旧版代码页上,为读取 UTF-8 源码的工具设置 PYTHONUTF8=1。
5. 视觉验证
以完整尺寸检查光栅图,并检查生成的检查表。确认:
- 仓库名称和价值主张在
320×160尺寸下仍然可读; - 产品证据可识别且技术准确;
- 文字、标记、裁剪、面板和装饰元素不重叠或裁切;
- 布局在浅色和深色背景下均表现良好;
- 每个可见元素都与承诺或证据对应;
- 设计通过每一条适用的路径特定否决条件。
从左到右、从上到下扫描,每次修复一个命名的缺陷,重新渲染并重新验证。切勿将已知缺陷遗留下去。
对于批量生成,创建联系表并检查是否存在意外共享模板导致的偏差,然后再推广候选方案。
6. 仅在请求时上传
创建资产不代表授权更改 GitHub 设置。当用户明确请求上传时,打开:
https://github.com/<owner>/<repo>/settings
使用 社交预览 → 编辑 → 上传图片… 并遵循当前 UI 确认策略。上传后,获取公开仓库页面并验证 og:image 是否解析为新的 1280×640 图像。不要仅凭设置页面的缩略图报告成功。
移交
展示最终图像并报告:
- 可编辑源文件路径;
- 光栅图路径、格式、尺寸和字节大小;
- 一句话设计理由;
- 验证和版本推广状态;
- 上传状态:未请求、待处理或已公开验证。
不要将项目特定的输出仅保留在临时或模型拥有的目录中。