能卖货的README
README不是文档。它是一个恰好存放在Git仓库里的着陆页。
访客大约在15秒内决定是加星、试用还是离开。折叠线以上的所有内容都必须赢得那颗星。文档放在折叠线以下或 docs/ 中。
15秒测试
在动笔前，请用一句话回答以下问题。如果你做不到，README也做不到。
- 这是什么？ 一句话，没有形容词。“用Zig编写的AI代理无头浏览器。”
- 为什么存在？ 它消除了用户的痛苦，用用户的话说。“Chrome每个标签页消耗500 MB内存；代理需要50个标签页。”
- 它有效的证据。 一个演示GIF、一个基准测试数字，或一个前后对比。不是功能列表。
- 如何用一个命令试用？
npx ...、pip install ...、curl ... | sh、docker run ...。
结构（按此顺序，没有例外）
# 项目名称
一句话Pitch。（什么 + 为谁 + 卖点）
[演示GIF或截图——10秒以内，展示结果，而不是安装过程]
## 安装 ← 一条命令，可直接复制粘贴，没有隐藏前提条件
## 为什么 ← 3–5行：痛点、现有替代方案、本项目不同之处
## 用法 ← 最常见的用例，可运行的示例
## 功能 ← 可选，简短，项目符号列表，没有营销形容词
## 工作原理 ← 可选，一段文字或一个图表
## 对比 ← 可选，与2–3个替代方案的表格，如实说明权衡
## 贡献 / 许可证
规则
- Pitch行： ≤ 15个词。指明类别和差异化因素。避免“极快”“强大”“简单而优雅”。如果有数字，就用数字：“大幅减少Claude Code的token使用量达40%。”
- 演示优先，文字其次。 GIF或截图直接放在Pitch行下方。如果还没有演示，在发布前先制作一个（参见
demo-gif技能）。不带演示的README转化率要低好几个数量级。 - 安装是一整个代码块，一条命令。 如果需要API密钥或配置文件，也一并展示在同一个代码块中。隐藏前提条件是克隆后用户离开的第一大原因。
- “为什么”是为已有解决方案的人写的。 指出替代方案。说明它们做得好的地方。然后说本项目做了哪些它们没做的。读者会信任对标 competitor 公平的README。
- 标题中不要用表情符号，除非项目本身刻意诙谐。Pitch上方不要有徽章（一长串徽章是访客第一个滚动略过的内容）。Pitch下方放两三个徽章即可：构建状态、版本、许可证。
- 一个真实的例子胜过十个功能点。 展示输入 → 输出。让读者能够实际运行它。
- 说明它不是什么。 一行诚实的范围说明（“不是Playwright的替代品；暂不支持JS渲染”）可以预先挡住Hacker News上的第一条恶评。
- 链接你拥有的社交证据。 “被X使用”、基准测试、Show HN帖子。不要捏造任何内容。
- 保持顶部60行不包含任何首次访客不需要的内容。 架构、路线图、常见问题、变更日志：全部放在下面或其他地方。
破坏转化的反模式
- 以一段背景或历史开头。
- 目录作为页面上的第一项。
- “功能”放在“安装”之前。
- 安装说明以“首先，克隆仓库”开头，对于一个供使用而非开发的项目来说。
- 展示配置文件的截图而不是结果的截图。
- 营销语气（“革命性”“下一代”“毫不费力”）。
- 死占位符（“TODO：添加演示”）。
流程
- 阅读当前README（如果有）和代码的入口点。从15秒测试中提取四个答案。
- 撰写Pitch行。写三个变体；选择具体名词最多、形容词最少的那一个。
- 先写安装，再写用法，最后写为什么。运行安装中的每一条命令，确认它能在空目录中正常工作。
- 在Pitch下方插入演示。如果没有，添加一个
TODO(demo)标记，并告知用户这会阻塞发布。 - 删除折叠线以上所有不符合“陌生人是否需要用这个来做决定？”的内容。
- 站在怀疑的工程师角度阅读顶部60行。修复第一个会导致他们关闭标签页的问题。
输出
返回完整的README.md。然后，用不超过5个要点列出你更改了什么以及用户仍需提供什么（演示GIF、基准测试数字、真实用户评价）。