极致专业 README 编写器

你创建的 README 应该看起来像高级落地页，而不是文档。将 README 视为碰巧用 Markdown 编写的视觉产品展示。你的 README 应该让人们停止滚动并感叹“哇，这个项目看起来真专业”。

请研读本技能目录下 references/visual-patterns.md 中的视觉模式参考资料，获取可以根据项目调整的、可直接复制粘贴的 SVG 和 HTML 示例。

标准

看看开源项目中最好的 README：Bun、Astro、shadcn/ui、Deno、Tauri。它们不仅结构良好，还拥有视觉标识、动画元素、数据可视化和交互式导航感。这就是你的目标。

一个“结构良好、带有徽章和项目符号列表”的 README 只能得 C+。你需要交付 A+ 品质。

关键规则

这些规则之所以存在，是因为过去的迭代暴露了真实的失败模式。请严格遵守。

规则 1：绝不丢失内容

在改进现有 README 时，你的任务是在现有内容之上增加视觉震撼效果，而不是将其简化、扁平化或重新格式化为不够详细的内容。

具体的内容保留规则：

效果好的块引用 → 保留为块引用。 不要将每个块引用部分转换成 Markdown 表格。带有表情符号标题（如> **✂️ 滚动截取**）的块引用视觉上更强、更易扫描——Markdown 表格行往往是降级。只有转换后能真正提高可读性时才改为表格。
详细的代码块 → 保持原样。 CLI --help 输出、配置示例、shell 命令——完全按照原样保留。
代码行数、文件数、技术数据 → 核实并保留。 如果原文说“118 个文件，14,250 行代码”，那么你的版本必须说同样的数字。如果数字对不上（例如，徽章显示约 40k 行，但文件结构只占约 22k 行），请在注释中标记差异，而不是默默忽略。
架构图 → 绝不简化。 如果原文有一个包含 50 个类的类图，你的版本必须保留每一个类和关系。围绕它添加视觉增强（可折叠包装、摘要标题），但绝不减少细节。
原文中的可折叠部分 → 保留它们。 不要将 <details> 块展开为内联内容。

规则 2：绝不重复信息

过去的输出中，统计数据出现 2-3 次、安装说明重复三次、英雄图片重复。这看起来马虎且浪费读者注意力。

具体的反重复规则：

一个数据点只出现一次。 如果测试数量（例如 412）出现在徽章中，就不应该再出现在文章和饼图标题中。选择视觉上最有影响力的位置，仅在那里使用。其他地方可以说“参见测试”。
导航徽章和目录是替代品，不是两者都要。 使用“for-the-badge”导航 CTA 或 Markdown 目录——不要同时使用。徽章本身就是导航。
一个英雄，不要两个。 不要堆叠 capsule-render 横幅和自定义英雄 SVG 和 <picture> 元素。选择最佳的单英雄处理方式。如果你使用 capsule-render 作为横幅，就不要添加功能相同英雄 SVG。
安装只出现在一个部分。 如果安装有多种方式（brew、cargo、二进制），将它们全部放在一个可折叠部分中，使用子标题。不要在“快速入门”、“安装”和单独的下载部分重复安装命令。

规则 3：增加创造性价值——不要只重新格式化

先前输出的最大差距：该技能重新格式化了现有内容，但没有添加任何新的创意章节。仅重新格式化是不够的。对于你生成的每个 README，至少添加 2-3 个以下内容：

使用场景演练 — 用户能感同身受的具体、真实场景。不是抽象的功能描述，而是“你处于这种情况，以下是该工具如何解决”：

### 💡 真实场景

<details>
<summary><strong>🐞 提交 Bug 报告</strong></summary>

1. 使用一个快捷键截取问题屏幕
2. 模糊客户姓名，圈出错误
3. 将链接粘贴到工单中
4. 在页面重新加载完成前完成

</details>

前后对比场景 — 展示没有该工具的问题和用该工具后的解决方案。这非常有说服力，而且没人这么做：

### 前后对比

| 没有该工具 | 使用该工具 |
|:---|:---|
| ❌ 截屏堆满桌面 | ✅ 每个截取几秒内获得链接 |
| ❌ 打开编辑器模糊一个名字 | ✅ 原地模糊和标注 |
| ❌ 将文件拖入每个工单 | ✅ 粘贴链接 |

竞品对比矩阵 — 如果项目有替代方案，展示可视化比较。不是“我们更好”的文章，而是诚实、数据驱动的表格：

### 对比

| 功能 | 本项目 | 替代方案 A | 替代方案 B |
|:---|:---:|:---:|:---:|
| 滚动截取 | ✅ | ❌ | ✅ |
| 上传前标注 | ✅ | ❌ | ❌ |
| 开源 | ✅ | ✅ | ❌ |

用户旅程图 — 展示实际用户体验流程及满意度的 Mermaid 旅程图：

journey
    title 用户体验
    section 入门
      安装: 5: 用户
      授予权限: 3: 用户
      查看菜单栏: 5: 用户
    section 日常使用
      截取窗口: 5: 用户
      分享链接: 5: 用户

故障排除决策树 — 代替扁平表格的 Mermaid 流程图，用于常见问题：

flowchart TD
    A[问题?] --> B{截取为黑色?}
    B -->|是| C[检查屏幕录制权限]
    B -->|否| D{快捷键不触发?}
    D -->|是| E[检查冲突的快捷键]

规则 4：必须始终生成 SVG 文件

当 README 引用 SVG 文件（./hero.svg、./gauge.svg 等）时，你必须实际创建该文件并将其与 README 一起保存。引用不存在的文件会在 GitHub 上产生损坏的图片——这比根本没有图片更糟糕。

如果你在 README 中引用 ./performance-gauge.svg，请创建包含有效动画内容的实际 SVG 文件。如果创建暗/亮变体（hero-dark.svg、hero-light.svg），请创建两个文件。没有例外。

规则 5：尊重原文的视觉选择

如果原始 README 已经使用了强有力的视觉模式（块引用功能卡片、HTML 表格网格、Unicode 进度条），除非你的模式明显更好，否则不要用功能相同的不同模式替换它。在现有基础上增强，而不是横向替换。

例如，如果原文对功能使用此模式：

> **✂️ 滚动截取**
>
> 将整个页面截取为一张图片。拼接在设备上完成，在你同意之前不会上传任何内容。

保留它。不要将其转换为 Markdown 表格行——块引用版本在视觉上更突出。相反，增强周围上下文：在其上方添加 capsule-render 部分分隔线，在功能之后添加视觉比较表，在下方添加用户旅程图。

如何处理任何 README 任务

理解输入

现有代码库/仓库 — 探索项目结构，阅读关键文件，推断目的、技术栈、架构和受众。

需要改进的现有 README — 彻底阅读。识别已经强大的部分（保留它）。识别过时或缺失的部分（修复它）。你的价值增值来自：动画横幅、SVG 数据可视化、创意新章节（使用场景、前后对比、比较）以及多样化的 Mermaid 图表。而不是重新格式化已经有效的内容。

用户描述 — 如有必要，提出针对性问题，然后生成完整的 README。

确定项目类型

项目类型	视觉优先级
移动应用	截图、设备模型、应用商店徽章、旅程图
后端服务	架构时序图、API 流程、部署徽章、性能仪表盘
SDK / 库	代码片段英雄、API 表格、包管理器徽章、基准 SVG 图表
AI/ML 项目	指标 SVG 仪表盘、基准柱状图、训练流程图表
CLI 工具	终端 SVG 模型、命令参考、安装矩阵
Web 应用	在线演示徽章、截图、技术栈徽章、捆绑包饼图

处理大型/复杂项目

对于拥有大型代码库（10k+ 行、多个模块、广泛测试套件）的项目：

验证所有数字。 汇总组件代码行数，并核实它们与所述总数一致。如果不一致，添加注释说明差异（例如，“剩余代码行包括生成的代码、测试夹具和配置文件”）。
添加摘要统计信息。 在详细分解之后，添加高层次摘要：“3 层，11 个服务，5 个界面。”
积极使用可折叠部分。 大型项目有很多细节。将深入内容（类图、文件树、API 参考）包装在 <details> 块中。主流程应在 30 秒内可扫描。
创建视觉统计仪表板。 对于拥有丰富数据（测试数量、覆盖率、代码行数）的项目，创建一个显示 2-3 个关键指标的、带有动画仪表盘的 SVG。

视觉工具包

这些是不可协商的。每个 README 都必须使用它们。

1. 动态渐变动画横幅

使用 capsule-render 作为页眉和页脚：

页眉：

<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,12,20&height=180&section=header&text=ProjectName&fontSize=42&fontColor=fff&animation=fadeIn&fontAlignY=36&desc=Your%20tagline&descAlignY=56&descSize=18" />

页脚：

<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,12,20&height=120&section=footer" />

根据项目标识自定义 customColorList。

2. 自定义 SVG 资产

每个 README 至少创建一个 .svg 文件。选择适合该项目的：

性能仪表盘 — 显示关键指标（速度、覆盖率、准确性）的动画弧线
终端模型 — 类似于终端应用窗口、包含命令和输出样式的 SVG
基准柱状图 — 展示本项目与替代方案对比的动画增长条形图
带暗/亮变体的英雄图片 — 通过 <picture> 实现主题感知渲染

有关完整、可复制粘贴的 SVG 代码，请参见 references/visual-patterns.md。

记住规则 4：如果你引用了它，就必须创建它。

3. 功能展示 — 选择最佳格式

对于 3-6 个功能： 使用带有表情符号图标和简短描述的 HTML 表格网格：

<table>
<tr>
<td align="center" width="33%">

### ⚡ 闪电般快速
亚毫秒级启动。零运行时开销。

</td>
<td align="center" width="33%">

### 🔄 实时重载
文件更改时自动刷新。零配置。

</td>
<td align="center" width="33%">

### 🌐 内置 CORS
开箱即用的跨域支持。

</td>
</tr>
</table>

对于 8 个以上详细功能： 在 2 列 HTML 表格中使用块引用卡片。这可以更好地扩展以应对丰富的功能描述：

<table>
<tr>
<td width="50%" valign="top">

> **📸 功能名称**
>
> 包含技术细节的详细描述。以利益为导向——解释为什么这很重要，而不仅仅是它做什么。

> **✂️ 另一个功能**
>
> 更多详情。

</td>
<td width="50%" valign="top">

> **🔗 第三个功能**
>
> 描述。

</td>
</tr>
</table>

绝不为功能使用纯项目符号列表。 这是懒散 README 的头号标志。

4. Mermaid 图表 — 至少 2 种不同类型

超越基本流程图。从以下中选择至少两个：pie、gantt、journey、sequenceDiagram、stateDiagram、mindmap、timeline、classDiagram、gitGraph。

选择能增加真正洞察力的图表类型：

pie → 代码组成、测试分布、预算分解
gantt / timeline → 路线图（取代无聊的复选框列表）
journey → 带有满意度分数的用户体验流程
sequenceDiagram → API 流程、架构交互
mindmap → 设计决策、技术栈概述
stateDiagram → 生命周期、状态机、工作流

5. Unicode 可视化元素

对于不需要单独 SVG 的内联数据：

覆盖率    ███████░░░  71%
测试      ██████████  412 通过
内存      ████░░░░░░  24 MB

与表格一起使用，而不是替代表格。适用于覆盖率分解、性能比较和语言完成百分比。

6. “For-the-Badge” 导航 CTA

<p align="center">
  <a href="#-快速入门"><img src="https://img.shields.io/badge/⚡_快速入门-2ea44f?style=for-the-badge" /></a>&nbsp;
  <a href="#-功能"><img src="https://img.shields.io/badge/✨_功能-6366f1?style=for-the-badge" /></a>&nbsp;
  <a href="#-基准测试"><img src="https://img.shields.io/badge/📊_基准测试-f59e0b?style=for-the-badge" /></a>&nbsp;
</p>

这些取代了传统的目录——不要同时使用两者。

7. 可折叠部分

将次要内容包装在 <details> 块中：安装变体、高级配置、完整 API 文档、项目结构树、故障排除。主流程应在 30 秒内可扫描。

8. 带有视觉指示的数据表

| 功能 | 本项目 | 替代方案 A | 替代方案 B |
|:---|:---:|:---:|:---:|
| 功能 X | ✅ | ❌ | ⚠️ |

README 结构

根据项目进行调整。并非每个部分都适用，但可视化元素是不可协商的。

 1. 动画页眉横幅（capsule-render）

 2. 居中的英雄区域
    - 带表情符号的标题
    - 标语
    - For-the-badge 导航 CTA（这些取代了目录）
    - 元数据徽章（版本、CI、许可证、平台）

 3. 价值主张（2-3 句话——为何存在）

 4. 功能（HTML 网格或块引用卡片——绝不用项目符号列表）

 5. 快速入门（带表情符号的编号步骤 1️⃣ 2️⃣ 3️⃣ 以及预期输出）

 6. 真实使用场景（创意场景——见规则 3）

 7. 基准测试/数据（SVG 仪表盘 + Unicode 条形图 + 比较表 ✅❌）

 8. 前后对比（可选但非常有说服力）

 9. 对比表格（如果有竞品）

10. 架构/设计（Mermaid 图表——序列图、流程图等）

11. 安装（可折叠，包含所有方法）

12. 使用指南（带输出示例的详细命令）

13. 贡献指南（如果适用）

14. 可选：路线图（Mermaid 时间线或甘特图）

15. 可选：故障排除（Mermaid 决策树）

16. 许可信息

17. 动画页脚横幅（capsule-render）

你需要知道的参考资料

此技能目录包含：

references/visual-patterns.md —— 完整、可复制粘贴的 SVG 代码、HTML 表格模式和高级 Markdown 布局示例

在使用此技能之前阅读该文件。它包含针对每种 README 情景的视觉模式。

质量检查清单

在完成之前，检查以下每一项：

Sa74/readme-writer

readme-writer 是什么？

在你喜欢的 AI 中提问

预览

文档