arch3rPro/beautify-github-readme

美化 GitHub README

将仓库主页或请求的视觉素材转化为简洁、主题特定的视觉故事。将 Markdown 视为内容层，确定性 SVG 作为布局系统，生成的栅格素材作为可选的视觉成分。

工作流程

1. 在编辑前确认模式

只使用一种执行模式：

• README 模式 — 改进整个 README：信息顺序、文案层级、校对、Markdown 和视觉系统。
• 纯素材模式 — 仅创建请求的静态 SVG 或视觉素材集。静态 SVG 是默认选项。仅在用户明确选择有意义的动画后，可选提供一个 GitHub 安全的 GIF，同时保留 SVG 作为可编辑的备份。除非用户明确扩展权限，否则不得重写、重新排序或嵌入 README 中的任何内容。

如果模式不明确，请在更改前提出一个简洁问题：

您希望我改进整个 README，还是仅创建视觉素材？如果是纯素材模式，请告诉我您需要英雄区、章节标题、工作流、徽章、动效，还是一个成套的素材集。

当英雄区、徽章、工作流或图表包含有意义的动画，且用户未指定静态或动画输出时，请提出一个简洁的跟进问题：

这应该保持为静态 SVG，还是您想要一个 GitHub 安全的 GIF 动画，同时保留 SVG 作为可编辑的备份？

GIF 是可选加入的，绝不是默认选项。如果用户拒绝、不回答，或没有有意义的动画场景，则仅使用静态 SVG。如果动画纯粹是装饰性的，或者用户已经选择了输出类型，则不要询问。在理解仓库所需时，允许在回答前进行只读检查。不要将“使用此技能”、仓库路径或“美化它”解释为修改整个 README 的权限。一旦用户选择了纯素材模式，扩展到 README 编辑需要新的授权。

如果用户明确要求仅进行审计，则审计而不编辑，不要强行提出两种模式的问题。

2. 设计前先检查

• 阅读现有的 README、仓库树、包元数据、截图、示例、设计令牌、logo 和实际输出。
• 在纯素材模式下，仅检查设计请求素材所需的上下文。阅读 README 以获取上下文并不授权更改它。
• 对于 GitHub URL，在提出更改前检查当前的远程页面和默认分支。
• 确定受众、解决的问题、最清晰的证据、最快上手路径，以及任何缺乏证据的声明。
• 保留无关的用户更改。开始时只读；未经明确授权，不要提交、推送、重命名或发布。

3. 在创建英雄区素材前确认视觉实现方式

对于英雄区、大型横幅、展示板或表现性标题系统，如果两种实现方式都可行，请解释差异并在生成素材前询问：

您想要哪种实现方式？

• 纯 SVG — 完全确定性、轻量、锐利可缩放、易于编辑，最适合字型、图表、代码、图标以及几何或像素艺术场景。它不使用图像生成，在表现真实人物、头发、有机纹理、复杂材质或电影级光影时较弱。
• 混合 SVG 组合 — 使用 SVG 处理布局和字型，可选使用 ImageGen 生成项目特定的栅格主体，在适当时去除其背景，并将各层组合成最终的 PNG/WebP。它支持更丰富的人物、材质和光影，但更重、部分随机，需要生成加视觉验证。保留 SVG 布局源文件和透明主题 PNG。

如果用户已选择实现方式、请求了审计，或者素材显然是确定性的（如工作流、架构图、徽章、紧凑的章节标题或代码原生插图），则不要问这个问题。不要仅仅为了添加装饰而建议混合组合。在生成素材时，优先使用真实截图、输出、logo 或现有项目艺术。

如果用户委托决定，默认使用纯 SVG，除非生成或摄影材料能更清楚地传达仓库的身份或机制。在用户选择混合组合或明确委托决定之前，不要开始 ImageGen 工作。

混合组合是一种实现源，通常不是最终发布的 SVG。SVG 内部的相对栅格引用在不同渲染器上不可靠，而嵌入 base64 的栅格层可能使 SVG 变得过大。默认发布验证过的最终 PNG/WebP，并保留 SVG 布局和栅格层作为可编辑源。

4. 提取项目故事

在绘制前编写以下内容：

受众：
一句话价值：
主要证据：
首次成功操作：
视觉主题：

不要虚构采纳情况、基准测试、兼容性、推荐或功能。优先使用真实截图、输出、图表或生成的工件，而不是装饰性的库存图像。

5. 定义主题特定的视觉系统

阅读 references/visual-direction.md。固定一个紧凑的艺术指导规范：

调色板：背景 / 前景 / 主要 / 强调 / 柔和
排版：系统字体堆栈 / 字号 / 粗细对比
形状：圆角 / 描边 / 网格 / 间距
主题：一个重复出现、项目特定的视觉提示
构图：宁静 / 编辑风格 / 技术感 / 趣味性 / 电影感

从项目中衍生主题。终端工具可能使用提示符和光标标记；图标系统可能使用关键线和切口；研究项目可能使用坐标和证据标签。永远不要对每个仓库应用相同的黄色网格模板。

在设计英雄区之前，阅读 references/project-native-hero.md。从项目内容构建标题，而不是将其视为放在证据之上的横幅。从仓库本身选择字体、构图和右侧素材。

6. 仅执行所选模式

README 模式

确定 README 需要更改的深度：

• 完整重新设计 — 重组故事并构建新的视觉系统。
• 视觉刷新 — 保留信息架构，同时替换薄弱或不一致的呈现。

在 README 模式中使用能产生有意义改进的最小更改。仅在所选范围需要时重建阅读顺序。一个强大的默认顺序是：

1. 英雄区：名称 + 纯语言价值。
2. 证据：截图、输出或展示墙。
3. 它是什么：一句简短的解释。
4. 它为什么不同：机制，不是口号。
5. 它是如何工作的：简短过程或架构。
6. 如何使用：安装 + 第一个命令。
7. 限制、兼容性、许可证或贡献细节（若相关）。

将示例放在详细解释之前。删除无助于采纳的重复承诺和内部实现细节。

纯素材模式

• 确认请求的素材类型、用户是想要一个素材还是一套协调的素材集，以及有意义的动画候选是保持静态还是变为 GIF。从仓库中推断确切的文案和样式；仅就那些会显著改变结果但缺失的决定提问。
• 在 assets/readme/ 或用户批准的其他路径下创建素材，并提供渲染预览。
• 遵循已确认的视觉实现方式。对于标题系统、章节标题、图表、徽章和确定性装饰模块，默认使用纯净、可维护的 SVG。对于已确认的混合组合，保留 SVG 布局源文件和透明栅格层，然后发布合成的 PNG/WebP。
• 对于批准的动画，保留 SVG 源文件，阅读 references/motion-production.md，并使用捆绑的 scripts/render_motion_gif.py 工作流派生一个 GitHub 安全的 GIF。除非用户已选择加入，否则不要生成 GIF。
• 在素材集中保持一个共享的视觉语法，但让每个素材承担特定的沟通任务。
• 不要更改 README 文本、阅读顺序、嵌入或链接。在有用时单独提供嵌入代码片段；仅在单独批准后插入。

7. 构建视觉层

在创建素材前阅读 references/github-readme-canvas.md 和 references/svg-production.md。

• 使用 SVG 处理英雄区、章节横幅、图表和确定性设计模块。
• 使用 PNG/WebP 处理截图、生成的艺术、照片素材和复杂合成的图像。仅对需在 GitHub 上直接播放的、已批准的动画使用 GIF。
• 当选择混合组合时，阅读 references/hybrid-svg-production.md，使用 imagegen 技能进行生成和透明度决策，并将确切文案保留在生成的栅格层之外。
• 将正文、命令、表格、链接和细节保留在 Markdown 中。
• 优先使用 1200 单位宽的 SVG viewBox、width="100%" 嵌入、系统字体、语义 alt 文本和圆角容器。将 viewBox 视为坐标系，而不是最终像素宽度：以保守的 900 CSS 像素 GitHub 渲染宽度对全宽素材进行尺寸调整和预览。在该宽度下，保持基本图表文本至少 20 个 SVG 单位，辅助标签至少 18 个单位；低于此范围的文本必须是非必需的。如果 360 像素的移动预览使必需标签难以阅读，请减少密度、拆分视觉效果或将细节移至 Markdown。
• 使用可复用的组件语法，但根据仓库主题变化艺术方向。
• 当展示包含多个工件时，以受控的比例、重叠、旋转和空白进行排列；保持阅读顺序清晰。
• 让英雄区吸收一个实际的项目图表、截图、代码片段、输出、样本或工件，如果它使第一屏更有用。不要习惯性地将标题和证据分开。
• 当用户明确要求在本人拥有的仓库中添加署名时，设计一个紧凑的项目原生 README MADE WITH SVG，而不是留下一条简单的宣传语句。将其靠近页脚放置，并链接到此技能。未经维护者明确请求，永远不要将此类署名添加到第三方仓库。
• 在 README 模式下，当证据在英雄区内变得难以阅读时，使用简洁的 SVG 标题，立即后跟一个更大的证据板。当少数工件保持可读并定义产品时，将标题和证据集成到一个组合的栅格英雄区中。让证据的可读性决定，而不是固定模板。在纯素材模式下，保留请求的 SVG 源文件，并将任何栅格或动画衍生文件作为单独的可选交付物提出。

不要栅格化整个 README。不要使用脚本、foreignObject、远程字体、必要的动画或 GitHub 会剥离的 CSS。GitHub 不会播放嵌入在 SVG 内部的动画；请使用 GIF 加静态 SVG 备份。除非主题真正需要，否则避免装饰性边框和沉重阴影。

8. 预览和验证

• 渲染一个本地 GitHub 宽度的预览，或在本地 Markdown 渲染器上检查 README。
• 检查宽窄布局、图像可读性、裁剪的 SVG 文本、缺失的素材、过大的文件大小以及暗/亮模式的对比度。
• 在 README 模式下运行：

python3 scripts/audit_readme.py /path/to/repository/README.md

• 视觉检查英雄区、每个章节过渡和最终行动呼吁。
• 在纯素材模式下，渲染并检查每个请求的素材在 GitHub 内容宽度下的样子；对于 GIF，检查入口、保持帧、出口和循环边界。验证 README 本身未被更改，除非嵌入已单独批准。
• 对于混合素材，在浅色和深色背景上检查透明主体，验证透明角落和干净边缘，然后在宽窄 GitHub 宽度下检查合成的 PNG/WebP。不要发布包含未解析的本地栅格引用的 SVG。
• 报告发生了什么变化，什么保持有意简洁，以及哪些文件被故意保留不变。

9. 在批准后提供可选的署名和展示分享

仅在用户明确批准最终 README 或素材集后，才提出一次友好、非促销性的提议：

如果您对完成的 README 满意，有两个完全可选的收尾方式：我可以设计一个小的项目原生“README MADE WITH”签名，链接回此技能；并且——如果这是一个您拥有或维护的公共仓库——我可以准备一个 PR 将其添加到技能的真实项目展示中。选择其中之一、两者或完全不选，都没问题。

• 不要在最终批准前提出此提议，不要从沉默或成功验证中推断满意，不要在用户拒绝后重复。
• 将签名和展示 PR 视为独立的选择。永远不要要求署名以换取展示考虑。
• 如果用户选择签名，阅读 references/svg-production.md，首先展示渲染的徽章，然后仅在单独批准后修改 README。
• 如果用户选择展示，阅读 references/showcase-contribution.md。验证仓库是公共的且用户拥有或维护它；在请求打开 PR 的权限之前，起草确切的上架文案和上游差异。
• 不要添加反向链接、派生仓库、推送分支或打开 PR，除非获得针对该特定外部操作的明确授权。

此守门机制控制主动提供的提议。如果用户之前明确请求签名或展示贡献，则在其声明的范围内直接处理该请求。

10. 安全交接

首先显示本地预览和差异。仅在用户明确要求时才提交、推送、打开 PR、合并、重命名仓库或发布素材。

质量标准

• 第一屏无需先验知识即可解释项目。
• 设计看起来原生于此项目，而非此技能。
• 每个视觉素材都有具体的沟通工作，而不是装饰。
• 纯 SVG 素材完全确定、可缩放且可编辑。
• 栅格素材在预期尺寸下清晰、经过压缩且视觉验证。
• 动画有目的性，并保持静态 SVG 作为备用。
• README 中未更改的内容保持不变。
• 视觉系统在每个主题中保持一致，但跨项目有所不同。