README + 一条命令运行
你有了干净的结构和真正的测试。最后一公里是审阅者实际上最先碰到的部分:README,以及运行它的那一条命令。一个要猜上十分钟才能启动的项目,即使能用也让人觉得是坏的。一个克隆下来一行命令就能运行的项目,即使很小也让人觉得很专业。同样的代码,给人的印象天差地别。
README 是一份契约。读者从上到下扫读,并期待一个可预测的形状:项目名作为标题,然后是怎么安装,然后是怎么使用,然后是怎么测试。具体来说,一份好的 README 有一行顶层标题(# Something),然后按这个顺序是这些部分:
# Triage Copilot
## Setup
pip install -e . # editable install
cp .env.example .env # then paste your real key into .env
## Usage
python -m triage # the one-command run
## Tests
pytest
顺序很重要,因为读者会把它当作步骤来跟。先写 Usage 再写 Setup 会让人困惑:你没法使用还没安装的东西。所以你要写一个检查器 validate_readme(text),只有当出现了 # 标题,后面依次跟着 ## Setup、## Usage、## Tests,并且每一个都在前一个之后时,才返回 True。缺少某个部分,或者各部分顺序错乱,都返回 False。诀窍是:把所有行走一遍,保留一个记录你当前位置的"光标",并要求每个部分都出现在光标之后的位置。
一条命令运行。注意上面的 ## Usage 那一行就是一条命令。这正是 Makefile 或 justfile 里像 make run 这样的目标要达到的:一条好记的命令就能启动项目,这样就没人需要记住完整的调用方式。写 make_run(name),为一个项目返回那条命令字符串,例如 python -m triage(或 make run)。它必须嵌入项目名,并以与包目录相同的方式规范化,这样不同的项目会得到不同的命令。
关于真实仓库的两条诚实的、不评分的说明。第一,机密:cp .env.example .env 这一步之所以存在,是因为你真正的 API 密钥放在 .env 里,你把它加进 .gitignore,并且永远不要提交它。你只提交 .env.example,也就是带占位值的配置形状。把密钥泄露到公开仓库,是作品集项目的经典错误。第二,部署它:要把它放到网上,你会写一个小的 Dockerfile(复制仓库,pip install,把运行命令设为入口点),然后推送到像 Render、Railway 或 Fly 这样的 PaaS。那一部分无法在你的浏览器里运行或评分:等你发布时由你自己来做。按 Run 验证一份完整的 README 并打印运行命令。
写出一份好 README 的两个确定性部分。validate_readme(text) 当且仅当出现一个顶层 # 标题,然后依次是 ## Setup、## Usage、## Tests,并且每一个都在前一个之后时,才返回 True(缺少某个部分或顺序错乱 -> False)。make_run(name) 返回一条命令运行的字符串(例如 python -m <pkg> 或 make run),其中嵌入项目名,并像包目录那样规范化,这样不同的名字会得到不同的命令。
这个练习即将开放
完成它前面的那一课,这一课就会解锁。整门课程免费,无需账号,而且你现在就可以阅读这节课。
这个浏览器屏蔽了 learn.floati.life 的 Cookie,所以你在这里完成的课程无法按顺序打开。请允许这个网站使用 Cookie,然后重新加载。