readme-wizard

README 向导

扫描代码仓库，并根据真实的项目数据生成或改进项目 README，打造精良、专业的效果。

工作流

1. 扫描项目

运行 scripts/scan_project.sh <project-directory>，收集结构化的 JSON 元数据：

• 项目名称和描述
• 许可证类型
• Git 远程仓库（所有者和仓库名称）
• 包管理器（npm、yarn、pnpm、pip、cargo、go 等）
• CI 设置（提供方和工作流文件）
• 社交链接（YouTube、Discord、Twitter、LinkedIn、Bluesky、Twitch）
• 目录结构（前 2 层）

参考脚本会先检查本地文件，然后使用 GitHub API 查询主页 URL，并爬取该主页以获取更多社交链接。你自己的初版可以只检查本地文件，之后再根据需要添加这项扩展。

**处理缺失数据：**对于未找到的数据，扫描结果会返回空字符串。切勿编造元数据——如果某个字段为空，就跳过相关章节或徽章。例如：没有 CI 工作流就不添加构建徽章；没有社交链接就不添加社交章节。

2. 阅读最佳实践指南

开始撰写前，先阅读 references/readme-best-practices.md。其中介绍了结构、语气、如何根据项目类型调整内容，以及常见问题。了解这些背景能显著提升输出质量——指南会解释各章节背后的原因，让你写出的 README 有明确目的，而不是套用公式。

3. 构建 README

以 assets/readme-template.md 为基础结构。将 {{PLACEHOLDER}} 标记替换为扫描得到的实际项目数据。

呈现项目目录树时，应贴合人们浏览代码仓库的习惯：目录列在文件之前，每组内部按字母排序，目录末尾加上 / 标记。

**灵活调整，不要照搬。**模板只是起点。删去不适用的章节（例如，个人笔记仓库无需「贡献」章节），并调整语气以适应项目：

• 库/框架：重点介绍安装、API 和示例
• 应用程序：重点介绍设置、配置和截图
• 文档/学习类仓库：重点介绍结构和导航
• 小型工具/脚本：保持简短——简介、功能说明和用法就足够了

4. 添加徽章

阅读 assets/badges.json，查看按类别（状态、社交、其他）整理的完整徽章目录，其中包含动态值的 {{PLACEHOLDER}} 标记。所有徽章都使用 style=for-the-badge。

**基本原则：**只添加确实存在的内容对应的徽章。为不存在的 CI 工作流或猜测的 npm 包添加徽章，还不如不加。

5. 验证输出

根据 evals/evals.json 中的断言检查生成的 README。确认：

• 没有遗留占位文本（{{PROJECT_NAME}}、TODO 等）
• 所有徽章都指向真实的 shields.io URL，且对应的内容确实存在
• 各章节篇幅与项目规模相称——简单脚本不需要 200 行的 README
• 只有扫描发现社交链接时，才添加社交徽章
• 语气简洁直接，不堆砌营销辞藻

6. 可选：添加图表

只有当项目包含多个组件或有明确的数据流（API、monorepo、内容管道）时，才阅读 assets/diagrams.md。简单项目完全跳过此步骤。根据项目的实际结构生成图表——文件中的模板只是可调整的起点，不要照搬。