2026.04.20技术

Codex Subagents 实战：批量生成测试、检查兼容性、翻译注释

场景是这样的：你有 30 个工具函数文件，每个都需要写单元测试。以前只能一个个来，一天可能都搞不完。现在，30 个文件可以同时跑，总时间和处理 1 个文件差不多。

核心机制：一个 CSV，启动一批 agent

你不需要理解底层怎么运作，只需要记住这个用法模式：

你准备一个 CSV（每行 = 一个任务）
        ↓
Codex 读取 CSV，每行启动一个独立 agent
        ↓
所有 agent 同时并行工作
        ↓
结果汇总写回输出 CSV

你的工作是：准备好 CSV，写清楚每个 agent 要做什么。剩下的交给 Codex。

场景一：给整个项目批量生成单元测试

痛点

项目里有几十个工具函数，一个个手写单元测试要花一整天，而且写到后面质量越来越低。

第一步：生成任务清单

让 Codex 扫描项目，把要处理的文件整理成 CSV：

扫描 src/utils/ 目录下所有 .ts 文件，
生成一个 CSV 文件 utils-list.csv，
列：file_path, function_count（该文件里导出的函数数量）

几秒钟你就拿到一份清单，列出所有待处理文件。

第二步：并行生成测试

使用 spawn_agents_on_csv 读取 utils-list.csv，
对每个文件路径启动一个 agent，执行以下任务：
- 读取 {file_path} 中的所有导出函数
- 为每个函数生成对应的 Jest 单元测试
- 测试文件保存到 __tests__/{file_path对应路径}.test.ts
- 覆盖所有正常输入、边界值、异常输入的 case
完成后输出结果到 test-generation-results.csv，
包含：file_path, tests_generated, status

30 个文件并行跑，总耗时和跑 1 个文件接近。手工一天的活，变成等几分钟。

status 字段的价值不要忽略：哪些文件成功、哪些失败，一眼看清楚。失败的可以单独重跑，不用全部重来。

场景二：批量检查 API 兼容性

痛点

把 React Query 从 v4 升级到 v5，breaking changes 非常多——useQuery 参数结构变了、isLoading 行为变了、cacheTime 改名了……项目里几十个文件都用了，一个个排查根本不现实。

第一步：找出所有受影响的文件

用 grep 找出项目中所有 import 了 @tanstack/react-query 的文件，
生成 rq-files.csv，列：file_path

第二步：并行检查每个文件

使用 spawn_agents_on_csv 读取 rq-files.csv，
对每个文件启动一个 agent：
- 检查该文件中 React Query 的所有用法
- 对照 v5 的 breaking changes 列表，标出不兼容的用法
  （重点检查：useQuery 参数结构、isLoading→isPending、cacheTime→gcTime）
- 给出具体修改建议

结果输出到 compat-check.csv：
file_path, incompatible_count, issues（JSON格式）, suggested_fix

跑完你会得到一份完整的兼容性报告。incompatible_count 为 0 的文件不用动，有问题的直接看 suggested_fix，改起来有的放矢。

小贴士：issues 用 JSON 格式存，是为了方便后续再让 Codex 读这份 CSV、自动批量修复——可以接着再跑一轮 spawn_agents_on_csv。

场景三：批量翻译注释

痛点

接手了一个全英文注释的老项目，领导要求全部汉化。文件几十个，手动翻译是不可能的。

这类任务用两步 prompt 就能搞定：

生成 files-to-translate.csv，扫描 src/ 下所有有英文注释的文件。

然后用 spawn_agents_on_csv：
- 读取每个文件
- 将所有英文注释翻译成中文（保持代码不变）
- 直接写回原文件
- 输出：file_path, comments_translated, status

代码逻辑一行不动，注释全部换成中文。这类机械性批量操作，正是这个模式最适合的场景。

三个使用建议

第一：不占你本机资源。 所有 agent 跑在 OpenAI 的云端沙盒里，不是你的电脑上。CSV 有 100 行也不会同时起 100 个进程把内存撑爆——系统会按并发上限排队执行，你的机器只是发了个指令，剩下的在云上跑。

第二：先小批量测试。 第一次跑新任务，先在 CSV 里只放 3 到 5 行，确认输出格式和质量没问题，再全量跑。全量跑之前发现问题，代价是调一下 prompt；全量跑完才发现问题，代价是重跑全部。

第三：status 字段必须要。 每个 agent 汇报自己的完成状态，是这个模式的核心价值之一。没有这个字段，你不知道哪些成功、哪些失败，出了问题只能全部重来。

小贴士：输出 CSV 里除了 status，建议也加一列时间戳或错误信息（比如 error_message），方便定位具体是哪一步出了问题。