第 20 卷
/review
Codex会检查整个项目的代码,找出类型错误、未使用的导入、不一致的命名等问题。比较典型的问题有:
| 常见问题 | 原因 | 解法 |
|---|---|---|
| 类型不匹配 | 前端期望的字段名和后端返回的不一样 | 以AGENTS.md中的接口约定为准,统一修改 |
| 导入路径错误 | agent各自创建了不同的目录结构 | 统一目录结构后修改导入 |
| 环境变量缺失 | 后端agent用了硬编码的测试Key | 改成process.env.OPENAI_API_KEY |
| 数据库连接重复 | API层和数据库层都创建了连接实例 | 统一用数据库层暴露的实例 |
逐个修复。每修一个问题,验证一下是否影响其他地方。等所有TypeScript编译错误都消除了,再做一次完整测试:
帮我做一次端到端测试:
- 启动dev server
- 调用POST /api/summarize,传入一个真实的文章URL
- 检查返回的摘要是否正确
- 调用GET /api/history,检查是否有刚才的记录
- 检查前端页面能否正常展示
测试通过后,commit并打tag:
git add . -& git commit -m "feat: integrate all modules - frontend + api + database"
git tag v0.1.0
阶段五:优化和部署
核心功能跑通了,但还有一些收尾工作。这些任务适合丢给云端Codex异步处理:
在网页或桌面App里新建任务,选Work in > Cloud,用这个仓库建好并发布的环境(§07),创建几个任务:
【任务1】给项目写README.md,包括:
- 项目简介
- 功能截图占位
- 安装和运行步骤
- 环境变量配置说明
- 部署到Vercel的步骤
【任务2】优化错误处理:
- API路由统一的错误响应格式
- 前端的错误提示UI
- 文章抓取失败时的降级方案
- OpenAI API调用超时的重试逻辑
【任务3】添加SEO和性能优化:
- 页面metadata
- OG图片
- 摘要结果页面的SSG
- 图片和字体优化
云端Codex的好处是这些任务可以同时跑,每个在独立的沙盒环境里执行,完成后给你提PR。你审查、合并就行。
部署到Vercel:把代码推到GitHub,在Vercel控制台导入项目,配置环境变量,点Deploy。Next.js项目Vercel 会自动识别构建配置,通常不需要额外设置。
要注意的是SQLite。Vercel的Serverless函数没有持久的文件系统,SQLite文件存不住,生产环境换成Turso这类托管数据库。让Codex做这个迁移:
把数据库从本地SQLite迁移到Turso(libSQL的云端版本)。
要求:
- 本地开发仍然用SQLite文件
- 生产环境用Turso
- 通过环境变量DATABASE_URL区分
常见陷阱和解决方案
用Codex做这类多agent并行的项目,常见的坑有这些:
| 陷阱 | 现象 | 解决方案 |
|---|---|---|
| agent改了不该 | 让agent改前端,它顺手把 | 用worktree隔离。每个agent只在自己的分支上操作,合并时人 |
| 改的文件 | 数据库schema也改了 | 工审查 |
| 多agent的修改 | 两个agent都改了同一个配 | 分清依赖关系,先合并基础模块。共享配置文件只由一个agent |
| 互相冲突 | 置文件 | 负责 |
| 云端任务执行失 | 提交到云端Codex的任务跑 | 发布环境前看设置报告,确认依赖装齐、测试能在环境里跑通 |
| 败 | 不起来 | (§07) |
| 上下文太长导致 | agent干了很多事之后,回 | 用/compact压缩上下文,或者干脆开一个新session。把已完 |
| 质量下降 | 答变得不精准 | 成的工作commit后,新session只需要知道当前状态 |
| 接口约定不一致 | 前端调的接口和后端实现的 | 在AGENTS.md中定义接口契约,所有agent都读同一份约定 |
对不上
| 忘记处理边界情 | URL格式错误、文章内容为 | 在初始prompt里就列出要处理的异常情况 |
|---|---|---|
| 况 | 空、API超时 | |
| 不commit就并 | 三个agent同时改代码,改 | 每个里程碑都commit。骨架搭好commit,每个agent完成 |
| 行开发 | 崩了没法回退 | commit,合并后commit |
| 测试只看能不能 | 页面能打开就算完成,不测 | 写一个端到端测试清单,让Codex逐项验证。包括正常流程和异 |
| 跑 | 边界 | 常流程 |
三条原则
不要一次给AI太大的任务。「帮我做一个AI文章摘要工具」太大。「帮我实现POST /api/summarize路由,接收 URL参数,抓取正文,调用gpt-6-luna生成三种长度的摘要」就具体得多。任务越具体,输出越可控。
每一步都验证。骨架搭好,验证一次;数据库建好,跑一遍测试;API写好,curl测一下;前端做好,打开浏览器看一眼。每一步验证的成本很低,攒到最后一起查,成本就高了。
自己判断输出好不好。AI生成的代码读起来总是很有道理,它很少主动说「我不确定这样做对不对」。这个数据库Schema合理吗?错误处理够不够?API设计后面好扩展吗?这些要你来判断。
花叔的经验:我不写代码,小猫补光灯从第一行到最后一行都是AI写的。我花时间的地方是想清楚要做什么、不做什么,以及每一版做出来以后,用起来到底对不对。