AI 应用后端工程化：从原型到可交付系统 · 第 18 篇 · 第五章 · 产品化接口
通过一轮文档新增、修正和更新，讨论 README 如何约束安装、配置、运行方式与维护入口。
README 常在项目快结束时才补，内容是“安装依赖、运行命令、欢迎 Star”。真正有用的 README 更像一份可执行契约：它告诉陌生人系统解决什么问题、需要哪些前提、如何验证启动成功、哪里可能失败，以及怎样参与维护。
文档写完后连续修正链接和内容并不丢人。相反，这说明文档也在接受和代码一样的反馈。危险的是文档与实现分开演进，命令早已失效却仍摆在首页。
读者的最短成功路径
flowchart LR
Visitor[第一次访问] --> Purpose[确认用途与边界]
Purpose --> Prereq[检查环境前提]
Prereq --> Configure[创建本地配置]
Configure --> Run[启动服务]
Run --> Verify[健康检查/测试]
Verify --> Explore[接口与架构入口]
Explore --> Contribute[问题反馈与贡献]
README 首屏应让读者快速判断项目是否适合自己，而不是先列二十个徽章。快速开始必须给出可验证结果，例如访问 /health 得到明确响应，或运行测试看到固定用例通过。“服务已启动”却没有下一步验证，用户仍不知道配置是否完整。
环境示例只保存形状
.env.example 应列出变量名、安全的示例格式和必要说明，不保存真实 Token。需要区分必填与可选、开发默认值与生产要求。
DATABASE_URL=postgresql://app:change-me@localhost:5432/app
REDIS_URL=redis://localhost:6379/0
MODEL_API_KEY=replace-with-your-own-key
LOG_LEVEL=INFO
示例值要明显不可用于生产。启动代码应校验必填项并给出变量名，不让读者运行到第一次模型调用才发现缺密钥。README 则解释如何获得凭证、它需要什么权限，以及不要提交本地 .env。
文档中的技术栈要解释理由
简单罗列 Flask、Celery、Redis 和向量数据库帮助不大。更有价值的是说明它们在系统中的角色：HTTP 框架承接请求，任务队列处理长任务，Redis 提供 Broker，关系库保存事实，向量引擎服务语义检索。读者因此知道某个组件是否可替换，也能理解启动时为什么需要它。
架构图不必覆盖每个文件。画出请求、后台任务和数据存储三条关键路径，再链接到深入文档。README 是导航，不是把全部设计文档压进一个超长页面。
联系方式也是契约
无效 Issues 链接会让用户无法报告问题。仓库迁移、组织名变化和默认分支调整都可能让文档链接失效。CI 可以定期检查站内链接、命令和示例配置。
问题模板应引导用户提供版本、环境、复现步骤和日志摘要，同时提醒删除密钥。公开联系方式不要要求用户在普通 Issue 粘贴安全漏洞细节，应提供私密报告渠道。
README 最常见的谎言
第一种是“开箱即用”，实际需要手工创建数据库、安装系统库和复制多个密钥。第二种是接口示例来自旧版本。第三种是写着支持某平台，却从未在 CI 测过。
修正文档时不要只改一句命令，还要找出为什么会漂移。可以把示例命令直接用于 CI smoke test，把环境变量列表从同一 Schema 生成，把版本号链接到发布流程。越能自动验证，契约越不容易腐烂。
文档版本与代码版本
默认分支 README 描述当前开发版本，已发布用户可能使用旧版本。发布说明应记录升级步骤和破坏性变化，稳定文档可以按版本部署。代码示例注明适用版本，避免搜索结果把旧方法带给新用户。
如果项目尚未成熟，也应诚实写出限制，例如“当前只适合单机开发”“删除操作尚未清理外部索引”。明确边界比宏大功能列表更能建立信任。
迁移到内部服务
即使仓库不公开，README 仍能降低团队交接成本。值班手册、服务目录和 API 文档都遵循同样原则：从读者任务出发，提供最短验证路径，明确所有者与失败处理。
练习：让一位没参与项目的同事仅根据 README 在全新目录启动服务，记录每次需要口头询问的地方。把问题转成文档或自动检查，再重复一次。成功标准不是“他最终跑起来”，而是第二次不需要额外解释。
三次文档提交为何值得单独观察
文档也有发现问题、修复和再校准的循环。把它纳入测试与评审，README 才会从宣传页变成长期可靠的系统入口。