Hackathon README 构建器
黑客马拉松的 README 有一个普通项目 README 所没有的任务：它必须赢得比赛。 评委在几分钟内快速浏览几十个仓库，常常是在手机上，决定哪些值得打开。 README 是项目的第一印象，而且往往是评委在打分前阅读的唯一材料。 因此，目标不是“记录代码”——而是让忙碌、持怀疑态度的评委快速理解并相信项目， 并且让每一个声明都易于验证。
本技能生成丰富的提交风格 README，而非简略版本。
参考样式位于 references/readme-template.md —— 在编写之前请阅读它，
因为它编码了风格规范（居中的徽标行、演示徽标按钮、表格、基于真实文件的步骤、项目树、显式的“评委亮点”区块）。
references/badges.md 提供了可直接复制粘贴的 shields.io 代码片段。
请按顺序执行以下步骤，但保持对话语气——你是在帮助一位疲惫的开发者冲过终点线，而不是填写表格。
步骤 1 — 锚定评分标准（最先做这一步）
这是你能做的最有价值的事情，也是本技能存在的理由。 大多数 README 是按照通用模板编写的；优秀的 README 则是按照评分标准编写的。 在此之前，请先提问：
“你有该赛事的评分标准或打分表吗？（例如，‘创新性、技术难度、影响力、完成度’，或打分表/提交页面上的提示。）如果有，请粘贴过来——我会确保每一个标准都得到明确体现。如果没有，我会使用一个强大的默认标准。”
为什么先问：如果评分标准权重倾向于“现实影响力”，就用生动的案例和帮助的对象开头；如果权重倾向于“技术难度”，就把架构和难点放在前面。之后，在 README 末尾添加一个评委亮点部分，列出每个评分标准并指出项目如何满足它——这是评分标准可视化的体现，评委非常喜欢，因为它帮他们完成了工作。请保留一个检查清单：每个评分标准在 README 中都需要一个对应的位置。
如果他们没有评分标准，默认使用几乎所有赛事都使用的一些版本：创新性/原创性、技术执行、影响力/有用性、完成度/完整性。
同时评估赛事的风格，因为这会决定哪些可选部分需要包含（参见第 4 步）：
- 学术/研究/技术冲刺（例如 ACM 赛事）：通常奖励 AI 使用声明、伦理/数据保护说明、参考文献/引用，有时还包括联合国可持续发展目标对齐。请包含这些内容。
- 产品/创业/普通周末黑客松：保持简洁——除非项目涉及数据收集或需要证据支持的声明，否则跳过可持续发展目标、伦理和引用。
如果不确定，请提问，或者包含较精简的内容并提及其他内容可用。
步骤 2 — 扫描仓库以基于事实
当 README 描述的项目与代码不匹配，或者设置步骤无效时，评委立刻失去信任。 因此，在写作之前，先查看实际内容。风格规范参考了真实的文件路径，并展示了带有预期输出的真实命令——只有通过阅读仓库才能做到。
- 技术栈与语言：从清单文件中推断——
package.json、requirements.txt、pyproject.toml、go.mod、Cargo.toml、pom.xml、Gemfile。注意框架（React、Next、Vite、FastAPI、Flask、Three.js……）。这些直接映射到徽标行和技术栈表格。 - 如何运行：阅读
package.json中的scripts、Makefile、docker-compose.yml、Procfile、.env.example。运行部分必须与项目实际启动方式一致，包括环境变量和实际开发端口。如果可能，推断预期输出并展示——这表明项目是有效的。 - 结构与入口点：快速浏览顶层目录和主入口文件，使项目树和“工作原理”步骤引用真实文件（
src/lib/check.js、app/main.py），如示例所示。 - 已存在的内容：部分 README、许可证、
assets//docs//public/中的截图、配置中的部署 URL、CI 工作流程。请复用它们。
如果你没有仓库访问权限（用户仅描述项目），跳过扫描，依赖访谈，并说明——标出设置命令和文件路径是占位符，待验证，而不是发明确切的路径。
步骤 3 — 询问代码无法告诉你的信息
仓库提供事实；开发者提供故事和证据。一次友好地询问以下内容，并告知他们可以跳过任何内容：
- 一句话简介 → 成为标语引用块。
- 问题/灵感 → 具体、人性化，最好是某个特定时刻。
- 在线演示 + 视频 → 被点击最多的资源。将其放在顶部附近作为徽标按钮。如果没有视频，温和地指出一个 2 分钟的视频非常有帮助。
- 截图/GIF/吉祥物或标志 → 即使是一张图片也能提升感知的完成度；示例将吉祥物/预览图片居中放在顶部。
- 难点 → 技术上的难点或他们引以为豪的部分；技术执行评分和“工作原理”部分的黄金素材。
- 关键结果/指标 → 如果项目有测量结果，一个小型结果表格非常有说服力。
- 团队 → 团队成员表所需的姓名+角色（和链接）。
- 下一步计划 → 路线图/扩展展示愿景。
- 赛事附加信息（仅在步骤 1 中相关时） → 使用的 AI 工具、数据/同意细节、引用。
不要因为没得到答案而停滞。如果他们时间不够，使用明确标记的占位符如 <!-- TODO: 添加演示链接 --> 起草，以免重要内容被遗漏——切勿捏造演示 URL、指标或队友。
步骤 4 — 编写 README
在项目根目录（或用户指定的位置）生成一个 README.md，遵循 references/readme-template.md。完整的顺序骨架在那个文件中；以下是结构以及哪些部分是核心与可选的。
核心部分（几乎总是包含）：
- 标题 + 可选的居中标志/吉祥物图片
- 居中的技术徽标行（来自
references/badges.md） - 赛事/提交行 + 标语引用块
- 演示 + 视频作为徽标按钮（以及数据集/Colab 链接，如果有）
- 团队成员表
- 问题（或“为什么这很重要”）
- 解决方案 / 它做了什么
- 工作原理 — 引用真实文件的编号步骤
- 技术栈表格
- 本地运行 — 验证过的命令，尽可能包含预期输出
- 项目结构树
- 路线图 / 下一步计划
- 评委亮点 — 每个评分标准一个要点，将项目映射到该标准
- 许可证
可选部分（根据赛事风格和实际情况包含）：
- 在英雄区下方添加锚点链接导航栏（3–6 个关键部分）——将长滚动变为对手机快速浏览的评委的一个点击。
- 关键结果/指标表格 + 误差/分析表格（数据项目）；链接原始数据或可重现的命令，使数字可重新运行。
- 当项目改进了现状（更快、更便宜、步骤更少）时，使用前后对比 50/50 表格——它使优势可视化而非声明。
- 在英雄区下方为拥有一个关键数字的项目添加一个 ASCII 统计框。
- 使用
> [!IMPORTANT]/> [!NOTE]GitHub 警告引用块来突出显示一个快速浏览的评委不能错过的关键注意事项或事实（谨慎使用）。 - Mermaid 流程图（多阶段系统）
- 演示流程 / “离线工作”风格演示
- AI 使用声明（学术赛事）
- 数据保护/隐私/伦理（涉及人员或数据的项目）
- 联合国可持续发展目标对齐（注重影响力的学术赛事）
- 参考文献与引用、致谢
- 当前状态检查清单 + 打分前的完善待办事项
根据步骤 1 的评分标准调整重点和顺序：最重要的评分标准应出现在最前面。不要填充——每个部分都应该有存在的理由。一个精简的产品黑客松可能只使用核心部分；一个研究技术冲刺可能使用大部分可选部分。根据项目匹配，而不是按清单。
影响评委评判的风格要点：
- 以最强的点开头 —— 创新性、工程能力或影响力，哪个是吸引点就用哪个。
- 展示，而非告知 —— 一个演示徽标按钮、一个 GIF、一个命令设置和预期输出块胜过任何形容词。每个令人印象深刻的声明都应该是可验证的。前后对比表格、统计框或可重现的基准将声明转化为评委可以看到或重新运行的证据。
- 让英雄区域发挥作用 —— 居中的标题、可选的标志/吉祥物、徽标行和一句尖锐的标语应该让评委在滚动之前了解这是什么以及为什么好。把演示/视频按钮放在这里，也就是第一次点击的位置。
- 一切基于仓库 —— 真实文件路径、真实命令、真实开发端口。这是让 README 值得信赖的关键，也是示例风格的核心主线。
- 诚实 —— 不要声明不存在的功能；评委测试内容，一个虚假陈述造成的损失比缺失一个功能更大。将未完成的工作标记在“下一步计划”或状态检查清单下，而不是作为已完成。
- 保持易浏览 —— 短段落、有意义的标题、用表格代替冗长文字、在手机上从上到下两分钟内可读完。
步骤 5 — 对照评分标准闭环
在交付之前，对照步骤 1 中的每个评分标准，确认“评委亮点”部分（和正文）都涵盖了它；如果某个评分标准没有对应位置，添加它。然后告诉用户你做了什么——例如：“你的评分标准权重倾向于影响力和技术难度；我用问题开头强调影响力，在‘工作原理’下添加了‘为什么这很难’说明，而‘评委亮点’区块列出了所有四个标准。”最后，列出任何剩余的占位符（演示链接、截图、指标），以便他们知道在提交前需要填写什么。