yy-create-readme

name	yy-create-readme
description	创建或更新项目根目录下的 README.md 文件。自动分析项目结构， 生成专业、清晰的 README 文档，包含项目描述、技术栈、安装使用、特性等核心内容。 不用于创建 AGENTS.md、规则文件、API 文档或子目录下的 README。

yy-create-readme

描述

自动分析项目结构，创建或更新根目录下的 README.md，帮助用户展示项目核心价值，回答"是什么、为什么、怎么用"三个核心问题。

使用场景

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

不应触发：

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

指令

步骤 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

情况 A：README.md 不存在 — 记录为新建 README。

情况 B：README.md 已存在 — 读取现有内容，分析现有结构。默认采用"补充+优化"策略：保留现有内容，补充缺失部分，优化表达和结构，更正错误内容。若用户明确要求"完全重写"，则覆盖生成。

步骤 3. 确认方案与计划

完成 README 状态判断后，必须先确认方案与计划，收到用户确认后才可继续收集信息、生成内容或写入文件。

• 若当前环境可用 yy-mode-plan：优先直接使用该技能创建方案方向和计划，并等待用户确认
• 若当前环境不可用 yy-mode-plan：使用以下本地最小确认流程
  • 方向不明确时：先展示方案方向，等用户确认方向正确后，再展示计划
  • 方向明确时：直接展示计划
  • 展示计划后，必须等用户确认才可继续后续步骤
  • 展示方案方向时，至少包含以下内容：
    • 目标：一句话说明将要完成的内容
    • 方法：高层策略（1-3 句）
    • 涉及范围：将要修改的文件、目录或文档章节
    • 待确认点：仍需用户决策的关键选择（如有）
  • 方案方向结尾必须明确提示用户确认方向是否正确，或提出调整意见
• 计划中至少说明 README 状态、目标文件路径、内容生成策略、信息来源和影响范围

步骤 4. 收集项目信息

根据项目类型从配置文件自动收集：

• 基本信息：项目名称、描述、版本号
• 技术信息：主要技术栈和框架、运行环境要求、主要依赖项
• 使用信息：安装方式、启动命令、配置说明
• 环境与资源：.env.example、.env.sample 等环境变量示例文件；assets/、screenshots/、public/ 等资源占位目录
• 其他信息：开源协议、作者/维护者信息、是否有截图/GIF 演示

无法从文件确定的信息再主动询问用户。

步骤 5. 引导用户完善描述

如果项目描述不明确，使用以下核心问题引导：

1. 项目是什么？ — 一句话描述核心功能
2. 为什么开发？ — 开发动机、解决什么问题
3. 有什么特点？ — 与同类项目的差异点

如果用户在请求中说"直接写"、"无需确认"等，跳过此步骤。

步骤 6. 生成 README.md 内容

参考 templates/readme-template.md 的结构生成文档，遵循以下原则：

• 回答三个核心问题：What、Why、How
• 结构清晰：使用合理的标题层级（最多 3 级），重要信息放在前面
• 示例完整：代码示例可直接复制运行，标注代码块语言类型
• 视觉友好：有 UI 的项目添加截图或 GIF，并提供描述性 alt 文本；列表项使用适当的 emoji 表情增强视觉效果
• 语言规范：中文项目使用中文，专有名词保留英文（如 Vue、TypeScript）

Emoji 使用规范：

• 特性列表：使用 ⭐、🚀、💡、🎯、⚡ 等表情
• 技术栈分类：使用 🖥️（前端）、⚙️（后端）、🗄️（数据库）、🧰（工具）等表情
• 环境要求：使用 📦 表情
• 协议部分：使用 📄 表情
• 保持一致性：同类项目使用相同的 emoji 表情
• 适度使用：避免过度使用 emoji，保持文档专业性

常见编写问题参考 resources/readme-writing-guide.md。

步骤 7. 写入文件

根据已确认的计划生成并写入 README.md，告知用户文件路径。如需调整，可继续提出修改意见。

输出约定

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

必要内容（必须有）：

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

推荐内容（强烈建议）：

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

可选内容（按需添加）：

• 界面展示：有 UI 的项目
• 配置说明：需要配置的项目
• 环境变量示例和资源占位说明：依赖 .env 或外部资源的项目
• 开发指南：开源项目
• 贡献指南：接受贡献的项目
• 变更日志：持续维护的项目
• 致谢：有依赖或参考的项目

相关资源

• templates/readme-template.md：README 结构模板
• resources/readme-writing-guide.md：常见问题与注意事项