yy-create-readme

创建或更新项目根目录下的 README.md 文件，帮助用户展示项目的核心价值。

When to use

• 用户要求创建 README.md 文件
• 用户要求更新或完善 README.md
• 项目缺少文档说明时
• 用户说"帮我写个 README"

Don't use when

• 用户要求创建其他文档（如 CHANGELOG、CONTRIBUTING 等）
• 简单的文件读取操作
• 用户要求修改代码
• 用户只是想查看 README 内容

Steps

步骤 1：分析项目结构

扫描项目根目录，识别关键文件和目录：

• 包管理文件：package.json、pom.xml、build.gradle、requirements.txt、Cargo.toml、go.mod 等
• 配置文件：tsconfig.json、.eslintrc、pyproject.toml 等
• 源码目录：src/、lib/、app/、main/ 等
• 文档目录：docs/、examples/ 等
• 测试目录：test/、tests/、__tests__/ 等
• 协议文件：LICENSE、LICENSE.txt 等
• 截图/资源目录：screenshots/、assets/、images/ 等

根据识别的文件判断项目类型：

• Node.js/前端项目
• Python 项目
• Java 项目
• Go 项目
• Rust 项目
• 其他类型

步骤 2：检查现有 README.md

检查项目根目录下是否已存在 README.md 文件：

情况 A：README.md 不存在

• 直接进入步骤 3 收集项目信息
• 准备创建新的 README.md

情况 B：README.md 已存在

• 读取现有 README.md 内容
• 分析现有结构和内容
• 询问用户更新策略：
  1. 覆盖：完全重新生成
  2. 补充：保留现有内容，补充缺失部分
  3. 优化：优化现有内容的结构和表达

步骤 3：收集项目信息

根据项目类型收集以下信息：

基本信息：

• 项目名称（从 package.json、目录名等获取）
• 项目描述（从配置文件或询问用户）
• 版本号（从配置文件获取）

技术信息：

• 主要技术栈和框架
• 运行环境要求（Node 版本、Python 版本等）
• 依赖项（主要依赖，不需要列出全部）

使用信息：

• 安装方式
• 使用方法/启动命令
• 配置说明（如有必要）

其他信息：

• 开源协议（从 LICENSE 文件获取）
• 作者/维护者信息
• 贡献指南（如有）

视觉素材（可选）：

• 是否有界面截图或 GIF 演示
• 是否有架构图或流程图

步骤 4：引导用户完善描述

使用以下引导性问题帮助用户明确项目定位：

1. 项目是什么？ - 一句话描述项目的核心功能
2. 为什么开发？ - 开发动机、解决什么问题
3. 有什么特点？ - 与同类项目的差异点
4. 学到了什么？ - 开发过程中的收获（可选）

这些问题帮助生成更有说服力的项目描述，让 README 回答"what、why、how"。

步骤 5：生成或更新 README.md

根据收集的信息生成 README.md 内容。参考 templates/readme-template.md 的结构生成文档。

编写原则：

1. 回答三个核心问题：

   • What：项目是什么
   • Why：为什么需要它、解决什么问题
   • How：如何使用

2. 结构清晰：

   • 使用合理的标题层级（最多 3 级）
   • 重要信息放在前面
   • 每个章节职责单一

3. 示例完整：

   • 代码示例要可直接复制运行
   • 包含必要的注释说明
   • 标注代码块语言类型

4. 视觉友好：

   • 适当使用截图或 GIF 展示界面
   • 终端应用可用 GIF 演示操作流程
   • 图片添加描述性 alt 文本

5. 语言规范：

   • 中文项目使用中文
   • 专有名词保留英文（如 Vue、TypeScript、API）
   • 保持术语一致性

6. Markdown 格式建议：

   • 使用 **粗体** 强调关键词
   • 使用 *斜体* 表示术语或强调
   • 列表项保持简洁，每项一行
   • 链接使用 [文本](URL "可选标题") 格式

步骤 6：确认并写入

1. 向用户展示生成的 README.md 内容预览
2. 询问用户是否满意，是否需要调整
3. 根据用户反馈进行修改
4. 确认后写入文件

Output contract

生成的 README.md 文件应包含：

必要内容（必须有）

内容	说明
项目名称	清晰的标题
项目描述	回答"是什么、为什么"
安装方式	可执行的安装命令
使用方法	基本的启动/运行命令

推荐内容（强烈建议）

内容	说明
环境要求	运行所需的版本要求
特性列表	3-5 个核心特性
技术栈	主要技术和框架
开源协议	许可证信息

可选内容（按需添加）

内容	适用场景
界面展示	有 UI 的项目
配置说明	需要配置的项目
开发指南	开源项目
贡献指南	接受贡献的项目
变更日志	持续维护的项目
致谢	有依赖或参考的项目

输出示例

📄 正在分析项目结构...

检测到项目类型：Node.js
发现关键文件：
- package.json
- tsconfig.json
- src/

📄 检查现有 README.md...
README.md 不存在，将创建新文件

📄 收集项目信息...
- 项目名称：my-project
- 版本：1.0.0
- 描述：一个示例项目
- 主要依赖：express, typescript

📄 引导完善描述...
请回答以下问题帮助完善 README：
1. 这个项目解决什么问题？
2. 与同类项目相比有什么特点？

📄 生成 README.md 内容...

[显示生成的 README.md 内容预览]

✓ README.md 已创建：/path/to/README.md

常见问题

1. 描述太泛泛

问题：描述像"一个 XX 管理系统"，没有说明价值。

改进：说明解决的具体问题，如"帮助团队追踪任务进度，支持看板视图和甘特图"。

2. 缺少技术栈

问题：没有列出技术栈，读者需要翻 package.json。

改进：单独列出技术栈章节，分类展示前端、后端、数据库等。

3. 安装命令不完整

问题：只写 npm install，缺少克隆、进入目录等步骤。

改进：提供从零开始的完整命令序列。

4. 没有界面展示

问题：有 UI 的项目缺少截图。

改进：添加截图或 GIF，让读者快速了解项目外观。

5. 特性列表空洞

问题：特性写"功能强大"、"易于使用"等空话。

改进：写具体功能，如"支持 Markdown 语法"、"提供暗色主题"。

注意事项

• 使用正斜杠作为路径分隔符，路径包含空格时使用引号包裹，以确保跨平台兼容性和正确解析
• 不要假设项目使用未发现的框架或工具
• 如果无法确定某些信息，主动询问用户
• 保持 README 的简洁性，详细文档可放在 docs/ 目录
• 尊重用户现有的 README 结构偏好
• 对于部署的项目，建议提供在线访问链接
• 生成 README 时可参考 templates/readme-template.md 的结构