Craft Repository README
将仓库转变为清晰、可信的登录页面。所有声明、命令、徽章和链接都必须基于实际项目；视觉美化绝不能超越准确性。
选择操作模式
- 当用户仅要求反馈时使用 审计 模式。检查并报告；不编辑也不发布。
- 当用户要求创建或改进 README 时使用 构建 模式。编辑仓库并验证结果。
- 仅当用户要求提交、推送、创建拉取请求或更新仓库设置时使用 发布 模式。遵循仓库正常的 Git 工作流。
1. 检查实际项目
在起草之前，请检查：
- 现有的
README*、贡献、安全、许可证、变更日志和部署文档。 - 包清单、入口点、示例环境文件、测试命令、截图、徽标和公开 URL。
- Git 远程仓库、默认分支、发布标签、CI 工作流和托管配置。
- 仓库级别的指示文件，如
AGENTS.md或CONTRIBUTING.md。
从证据中推导出产品名称、一句话价值主张、目标受众、支持的平台、安装命令、运行命令和部署方式。如果某个重要事实无法验证，则省略它或明确标记为计划中。
2. 进行公开范围和安全检查
将 README 工作视为发布审查。在暴露细节之前：
- 搜索已跟踪的文件和暂存的更改，查找 API 密钥、私钥、令牌、密码、Cookie、内部主机名、私有 IP 和个人路径。
- 切勿从本地配置、聊天历史、shell 历史或部署文件中粘贴密钥。
- 链接到
.env.example；绝不复制.env中的值。 - 确认截图、二维码、名称和联系方式是故意公开的。
- 保留许可证、商标、署名和第三方资产声明。
如果发布会暴露敏感材料，立即停下并明确告知用户具体阻塞点。
3. 先设计故事，再装饰
按以下顺序编写 README：
- 识别 — 名称、徽标、简洁的承诺。
- 信任 — 少量真实的徽章和真实的产品视觉效果。
- 理解 — 它的作用、目标用户及其关键区别。
- 尝试 — 从克隆到工作结果的最短可验证路径。
- 采用 — 配置、部署、架构、限制和支持。
- 参与 — 贡献、安全、许可证、赞助者和社区。
在重新构建 README 布局或选择徽章之前，请先阅读 references/readme-patterns.md。
4. 构建紧凑的品牌头部
当项目具备相关资产时，请按以下顺序组织：
- 带有描述性替代文本和适当显示大小的链接徽标。
- 项目名称和一行价值主张。
- 四到八个有意义的徽章。
- 主要链接，如在线演示、文档、问题跟踪器或下载地址。
- 针对长篇 README 的可选页面内导航。
- 一张有说服力的英雄图片、产品截图或简短演示。
优先使用仓库自有资产，路径稳定在 docs/、.github/ 或 assets/ 下。在生成新徽标之前，先重用现有徽标。如果用户请求新的视觉效果，并且有可用的图像生成技能，请使用它，然后优化结果以适合仓库展示。
不要使用虚假的构建徽章、占位符指标、巨大的徽章墙、装饰性计数器或项目不控制的外部热链接资产。
5. 仅选择有用的章节
一个紧凑的项目通常需要：
- 它是什么以及为什么存在。
- 基于已实现行为的功能亮点。
- 带有可复制、已测试命令的快速入门。
- 使用安全占位符的配置。
- 截图或演示（当视觉证明确实有帮助时）。
- 部署或生产说明（当项目可部署时）。
- 贡献、安全、许可证和致谢链接（当这些文件存在时）。
仅当项目确实需要时才添加架构、API 参考、兼容性、路线图、FAQ 或故障排除。不要创建空的样板章节。
对于中文项目，首先使用自然的中文，并保留技术标识符的原始形式。仅在用户要求或仓库本身已维护英文版本时才添加英文版本。
6. 添加赞助信息而不干扰产品故事
当用户提供并授权赞助图片或二维码时：
- 将其复制到仓库拥有的稳定资产路径中。
- 使用清晰的标题，如
支持项目或Sponsor，放置在 README 靠下的位置。 - 添加替代文本、合理的宽度和一句解释赞助资金用途的话。
- 除非明确要求，否则不得更改、解码或重新生成支付二维码。
不要让赞助信息超过快速入门、文档或安全信息的重要性。
7. 将 README 作为可执行文档进行验证
在可行的情况下，运行项目相关的构建、测试、lint 或冒烟命令。然后运行捆绑的检查器：
python3 craft-repository-readme/scripts/validate_readme.py \
--repo-root . \
--readme README.md
当相应元素是必需的时，添加严格标志：
python3 craft-repository-readme/scripts/validate_readme.py \
--repo-root . \
--readme README.md \
--require-logo --require-badges --require-hero --require-sponsor
还要手动验证：
- 每个安装和运行命令都与仓库匹配。
- 相对图像和文档链接在 GitHub 的区分大小写路径下能够正确解析。
- 外部链接使用预期的规范域名。
- 标题锚点和目录链接有效。
- 图像具有描述性的替代文本和合理的尺寸。
- README 在桌面和窄屏上都能良好渲染。
- 没有残留的秘密、占位符、本地绝对路径或未经验证的声明。
8. 谨慎发布
当发布在范围内时：
- 查看
git diff，确保无关更改不进入提交。 - 使用重点突出的消息进行提交，并通过仓库的正常工作流推送。
- 当分支保护或协作实践需要时，优先使用拉取请求。
- 仅当用户请求了仓库设置更改且这些值已验证时，才更新 GitHub 描述、主页、主题和社交预览。
- 发布后，在 GitHub 上重新打开渲染后的 README，检查图像、徽章、链接和移动端布局。
完成标准
- 首页传达了名称、用途、信任信号和主要下一步操作。
- 所有突出的声明和命令都已针对仓库验证。
- 徽标、英雄图、徽章和赞助内容是有意的而不是装饰性的。
- 链接和本地资产能够正确解析。
- 没有暴露秘密或私有环境细节。
- 验证通过，并且请求的发布步骤已完成。