Codex App 并行工作台深度解析：多线程、多项目与可审查吞吐

Codex App 并行工作台深度解析：多线程、多项目与可审查吞吐

TL;DR

Codex App 的定位不是“桌面版聊天框”。官方 App 文档把它描述为面向 Codex threads 的桌面工作台，支持并行处理线程，并内置 worktree、automations 和 Git 功能。对工程团队来说，它的关键价值是把多个候选任务、多个项目、多个后台线程和审查结果放到一个可管理界面里。

并行不是越多越好。Codex App 提高的是任务吞吐和候选方案探索能力，瓶颈会转移到任务拆分、上下文管理、diff 审查和验证。一个 Tech Lead 用 App 的成熟标志，不是同时开多少线程，而是能否让每个线程只做一件事、每个 diff 都能独立验证、每个结果都能被保留或丢弃。

读者定位

本文面向已经能稳定使用 Codex CLI 或 Web 的中高级开发者、Tech Lead、开源维护者和多仓库负责人。你应该熟悉 PR review、Git worktree、测试矩阵和任务拆分。本文不讲 App 的按钮位置，而是讲如何把 App 当成工程调度台使用。

如果你现在还在用一个模糊 prompt 让 Codex 大范围改动，先不要追求并行。并行会放大任务不清晰的问题。一个线程改偏了只是一个 diff；五个线程同时改偏，会变成五份审查债。

问题：并行之后，真正稀缺的是审查能力

CLI 的常见使用方式是线性的：给一个任务，等待执行，看结果，继续追问或结束。App 改变了这个节奏。你可以在一个桌面工作台里管理多个项目和线程，也可以要求 Codex 在本地项目或 worktree 中管理线程。官方 Features 文档提到，当能力可用时，你可以让 Codex 找相关线程、继续已有线程、固定或归档线程，也可以明确要求它在 worktree 中创建后台线程。

这带来一个直接后果：等待时间减少，审查压力增加。

过去你等待一个 agent 跑完时，脑子里仍然保留任务上下文。现在你可能同时委派四个任务：一个修测试，一个补文档，一个 review PR，一个探索性能问题。等结果回来时，每个线程都有自己的假设、命令输出、diff 和剩余风险。你要判断它们是否互相冲突，是否改了公共文件，是否值得合并。

很多团队把 App 用坏，不是因为不会点按钮，而是因为没有并行策略。典型失败包括：

• 多个线程同时修改 package.json、lockfile、shared types、路由表或数据库 schema。
• 每个线程都拿到“修复模块问题”这种大任务，最后产出跨目录 diff。
• 没有为 best-of-N 设定不同策略，多个 agent 做出相似但都不够好的方案。
• 审查线程也被允许改文件，把 review 变成第二轮无边界重构。
• 完成后只看最终回复，不看实际 diff 和测试输出。

App 的并行能力要求你从“写 prompt”升级到“设计任务队列”。

心智模型：App 是工程调度台

可以把 Codex App 看成四个对象的组合。

第一，项目。项目对应一个工作目录或仓库范围。官方 Features 文档把 project 类比为在特定目录里启动一次 CLI session。如果一个 monorepo 里有多个独立应用或包，应拆成多个 App project，这样 sandbox 只覆盖对应项目文件，减少误改范围。

第二，线程。线程是任务的执行上下文，有自己的历史、目标和结果。线程不应该承担多个互相独立的目标。一个线程只解决一个问题，才能在结果回来后被审查。

第三，worktree。worktree 是后台隔离工作区。官方 Worktrees 文档把 Local 比作前台，把 Worktree 比作后台；Handoff 可以在线程的 Local 与 Worktree 之间移动。并行改代码时，worktree 负责隔离文件状态。

第四，审查面板与 Git 结果。App 的价值不在于让 agent 忙起来，而在于让人能看到候选结果、比较 diff、创建分支、提交、推送或丢弃。

这个模型可以转成一句规则：线程负责目标，worktree 负责隔离，Git 负责保存，review 负责筛选。

详细机制：何时用项目、线程、chat、worktree

项目边界

项目边界决定 Codex 看到哪些文件。一个大型 monorepo 如果只建一个 App project，Codex 每次都有机会扫描和修改整个仓库。对跨团队仓库，这会增加误改风险。更好的做法是按 ownership 或包边界拆 project，例如 apps/web、apps/admin、packages/auth、packages/billing。每个 project 有自己的指导文件、测试命令和安全约束。

线程边界

线程适合承载一个可验收任务。不要在一个线程里连续塞入三个互不相关的需求。线程历史会影响后续判断，越长越容易带入旧假设。App 支持继续线程，但继续应服务同一目标，例如“刚才的测试失败了，继续修同一问题”。如果换目标，开新线程。

Chat 与项目线程

官方 Features 文档区分 chats：当任务不需要特定项目目录或 Git 仓库时，可以用 chat 进行研究、triage、规划、插件密集工作流和其他对话。它们默认在 Codex home 下的 managed threads 目录工作。工程实践上，代码改动任务应进 project 线程；架构讨论、需求拆分、PR 风险归类可以先用 chat。

worktree 与 Local

Local 是你当前前台 checkout，适合需要本地 IDE、已有 dev server、人工调试的任务。Worktree 适合后台运行、候选实现、低耦合修复。官方 Worktrees 文档说明，线程可以从 Worktree hand off 到 Local，也可以从 Local hand off 到 Worktree；Codex 会处理移动线程需要的 Git 操作。

Skills 与团队能力

官方 Features 文档提到 Codex App 支持与 CLI、IDE Extension 相同的 agent skills，并能查看团队创建的技能。对团队来说，这意味着 App 可以承载可复用流程，例如“安全 review”“文档链接检查”“发布说明生成”。但技能不该替代任务边界。技能是流程模板，不是授权它改所有文件。

真实工作流案例：一次并行修复周

假设团队维护一个 SaaS monorepo，本周目标是减少小型 bug backlog。你可以这样用 App。

先准备任务池：

T1: 修复 date-range 工具在跨年区间上的边界测试失败。
T2: 补齐 currency formatter 对 JPY、KRW、零值的测试。
T3: 审查最近 auth PR 是否有权限回归，只报告 P0/P1。
T4: 研究 report export 变慢的可能原因，只输出诊断，不改代码。

再为每个线程限定路径：

目标：修复 `src/utils/date-range.ts` 的跨年区间边界问题。

允许修改：
- `src/utils/date-range.ts`
- `src/utils/date-range.test.ts`

禁止修改：
- `package.json`
- `pnpm-lock.yaml`
- `src/utils/index.ts`
- 任意 API 层代码

验证：
- 运行 date-range 相关测试。
- 如果发现实现没有 bug，只补测试并说明理由。

对 review 线程，给只读任务：

只审查当前 PR diff，不修改文件。

关注：
- 认证绕过
- PII 日志
- 权限校验缺失
- 缺少阻塞级测试

忽略：
- 主观命名偏好
- 纯格式问题
- 无明确影响的重构建议

输出：
- 只列 P0/P1 findings。
- 每条包含文件位置、影响、修复建议。

对诊断线程，明确不改代码：

分析 report export 变慢的可能原因。不要修改文件。

请读取相关代码、最近提交和测试结构，输出：
- 可能瓶颈列表
- 需要补充的观测数据
- 可拆分的后续任务
- 不确定点

这样做的收益是，每个线程都能独立评估。T1 和 T2 可以并行改不同文件；T3 不产生 diff；T4 只产生报告。你不会在一天结束时面对四个互相冲突的候选 PR。

best-of-N：并行探索不是重复劳动

best-of-N 适合设计空间明确但策略不确定的问题。例如“这个慢查询怎么修”。不要让三个 agent 都自由发挥，否则它们可能给出相似方案。要给不同策略：

同一问题开三个候选线程：

A：只调整 SQL 查询，不引入缓存，不改 API。
B：允许增加只读缓存，但不改响应结构。
C：只做诊断报告，不改代码，列出性能证据缺口。

比较标准：
- 正确性风险
- 回滚成本
- 运行时复杂度
- 测试覆盖
- 对调用方兼容性

比较时不要只看最终文本。要看 diff 大小、改动层级、验证命令、失败解释和维护成本。best-of-N 的目标不是选“看起来最聪明”的方案，而是选团队能长期维护的方案。

操作清单

拆任务前：

• 每个线程是否只做一件事。
• 是否能独立验收。
• 是否限定允许和禁止修改路径。
• 是否识别公共文件：lockfile、schema、shared types、路由、配置。
• 是否需要 worktree 隔离。
• 是否有只读研究或 review 任务，避免不必要 diff。

运行中：

• 是否超过个人可审查并发数。多数人同时管理 3 到 4 个线程已经足够。
• 是否有多个线程开始修改同一公共层。
• 是否有线程偏离目标，应及时停止或重写任务。
• 是否记录每个线程的假设和验证命令。

合并前：

• 逐个看 diff，不只看总结。
• 检查测试输出是否与改动范围匹配。
• 确认没有把一个候选方案的未验证假设带入另一个方案。
• 对最终保留方案创建分支或 PR。
• 丢弃不合格 worktree，避免长期堆积。

权衡与风险

App 最大收益是把等待时间换成审查时间。对个人开发者，这能加速小任务处理；对团队负责人，这能并行探索方案、清理 backlog、让 review 更早发生。代价是需要更强的调度纪律。

第一个风险是审查债。未审查的 diff 会堆积，并且随着线程数量增加而快速失控。不要把“线程完成”当成“任务完成”。完成意味着有人审过、验证过，并决定保留或丢弃。

第二个风险是上下文错配。一个线程的目标和约束可能不适合另一个线程。复制 prompt 时尤其容易遗留错误路径或旧限制。App 让复制任务变方便，也让复制错误变方便。

第三个风险是公共层冲突。多个 worktree 可以隔离文件状态，但无法消除合并冲突。公共类型、包版本、schema、权限模型这类改动应串行推进，或者先做一个基础 PR，再让其他线程基于它继续。

第四个风险是自动化过度。App 的 automations 和后台线程适合可重复、可低风险验证的任务。不适合把大范围架构迁移交给无人值守流程。

常见误区

误区一：把 App 当成“开更多 agent”的按钮。并行能力的上限由人类审查能力决定。你能认真审几个 diff，就开几个会产出 diff 的线程。

误区二：每个线程都给全仓库权限。项目边界和路径约束是并行的基础。没有边界的并行，只会提高混乱速度。

误区三：审查线程也能改文件。review 线程应只输出 findings。需要修复时另开 fix 线程，并把 finding 作为输入。

误区四：把 chat 里的规划直接当代码任务。规划可以在 chat 里做，执行要落到 project 线程，并附上文件范围和验证命令。

误区五：长期保留所有 worktree。候选实验应及时归档、转分支或丢弃。长期堆积会让环境状态变旧，也会增加误用旧结果的概率。

并行调度策略：把任务队列设计成可审查系统

使用 App 一段时间后，团队会发现真正困难的不是让 Codex 运行，而是决定哪些任务可以同时运行。可以把任务队列分成四类。

第一类是可并行执行任务。它们改动不同文件或不同包，验证命令互不依赖，失败后可直接丢弃。例如给三个纯函数补测试、更新三篇互不引用的文档、修三个独立组件的样式 bug。

第二类是可并行研究任务。它们不改文件，只输出分析报告。例如让一个线程分析性能瓶颈，一个线程梳理安全风险，一个线程评估测试缺口。这类任务很适合并行，因为产物是判断材料，不会造成 merge 冲突。

第三类是必须串行任务。它们改公共层，例如 shared types、数据库 schema、认证中间件、包版本、路由表、构建配置。公共层变动会影响其他线程，应该先完成基础 PR，再让后续任务基于新基础继续。

第四类是禁止无人值守任务。它们涉及生产凭据、真实客户数据、部署、合规判断、不可逆迁移。App 可以用于只读分析，但不能直接让后台线程执行写操作。

调度时可以用一个小表格记录每个线程：

| Thread | Goal | Writes | Verification | Risk | Decision |
| --- | --- | --- | --- | --- | --- |
| T1 | 补 date-range 测试 | utils/date-range* | package test | low | 可并行 |
| T2 | 诊断 export 变慢 | none | report only | medium | 可并行研究 |
| T3 | 改 shared auth type | packages/auth/types | full typecheck | high | 串行 |

这个表格不需要复杂工具。它让维护者在开线程前就看到冲突点。

审查队列：把 Codex 输出当候选，不当结论

并行线程完成后，App 里会出现多个结果。审查顺序应该先看高风险，再看低风险；先看改公共层的，再看局部改动；先看失败解释，再看通过结果。失败解释常常暴露环境缺口，比一个小修复本身更值得处理。

对每个线程，可以用同一套审查问题：

• 这个线程是否完成了原目标，还是顺手做了别的事。
• diff 是否只在允许路径内。
• 是否修改了公共接口、依赖、锁文件或配置。
• 验证命令是否匹配改动风险。
• 失败是否被诚实报告。
• 输出是否留下不确定点。
• 这个结果是否应该保留为分支、继续追问、转人工，还是丢弃。

不要让 App 里的“完成”状态影响判断。Codex 完成的是执行，不是工程验收。一个线程可能成功跑完，但产出不值得保留；也可能因为环境缺失失败，但给出了准确诊断。两者都需要人判断。

多项目工作台：monorepo 的边界设计

App 支持多个 project，这对 monorepo 很重要。一个仓库里可能有 Web、Admin、API、SDK、Docs、Infra。若都放在一个 project 中，Codex 每次都能看到并可能修改大量无关文件。更稳妥的做法是按实际 ownership 拆项目。

拆项目时看三件事。

第一，构建命令是否不同。如果 apps/web 用 pnpm，services/api 用 Python，最好拆开。不同 setup 放在同一个项目里，会让 Codex 在任务中花时间猜命令。

第二，权限风险是否不同。计费、认证、后台管理、基础设施脚本应有更严格规则。它们可以有更近的 AGENTS.md，也可以作为单独 project 管理。

第三，审查人员是否不同。如果 Web 团队不维护 API，App project 也应反映这个边界。否则 Codex 产出的 PR 会跨越 ownership，让 review 变慢。

拆项目不是把仓库割裂。跨项目变更仍然可以做，但要显式写成高风险任务，并说明影响面和验证矩阵。默认任务应尽量待在一个 project 内。

线程命名与记录：减少上下文遗失

并行多了之后，线程名称和记录会决定后续能否追踪。不要让线程都叫“修 bug”或“review PR”。命名应包含目标、范围和策略，例如：

• auth-login-safari-loading-ui-state
• billing-discount-review-readonly
• export-performance-diagnosis-no-write
• date-range-tests-boundary-cases

每个线程开始时写清假设，结束时要求输出决策材料。对复杂任务，可以在最终回复里要求固定格式：

## Result
完成了什么。

## Files changed
列出主要文件。

## Verification
运行了哪些命令，结果如何。

## Risks
哪些行为未覆盖，哪些判断需要人确认。

## Next step
建议保留、继续、转人工或丢弃。

这不是形式主义。并行时，人很容易忘记某个线程为什么存在。固定输出能降低重读整段对话的成本。

自动化与人工节奏

App 的 automations 适合周期性、低风险、可验证任务，例如定期检查文档链接、生成依赖升级报告、扫描最近 PR 的高风险模式。它不适合自动进行大范围代码修改。任何会写代码、开 PR 或触发外部服务的 automation，都要有触发条件、权限边界和人工 review。

一个合理节奏是：自动化负责发现和排队，人工决定是否执行，Codex 负责候选实现，人工负责合并。比如每天自动生成“可能缺测试的 PR 列表”，维护者选其中两个让 App 线程补测试。不要让自动化直接把所有列表项变成 PR，否则审查队列会失控。

衡量效果：不要只看节省了多少时间

App 引入团队后，可以跟踪几类指标。

第一，候选产出合并率。很多线程完成但很少合并，说明任务拆分、环境或规则有问题。

第二，平均 diff 大小。diff 越大，review 越慢。好的 App 使用方式应让候选改动更小、更集中。

第三，验证覆盖率。每个写代码线程是否都运行了匹配验证，还是大量结果只靠解释。

第四，越权率。线程是否经常改禁止文件、引入依赖、修改公共接口。越权率高说明 prompt 和 AGENTS.md 不够清楚。

第五，人类审查延迟。并行任务如果让 review backlog 增长，吞吐没有真正提升。需要减少并发或改善任务粒度。

个人工作法：一天内怎样安排 App

个人使用 App 时，可以把一天分成三个节奏。早上开只读线程，让 Codex 分析 backlog、归类 CI 失败、审查过夜 PR。只读线程产出判断材料，不会制造大量 diff。

中午前后开少量写代码线程，数量控制在自己下午能审完的范围内。每个线程都要有明确范围和验证命令。不要在会议前一次性开十个修复线程，否则下午只会面对一堆缺乏上下文的候选结果。

下午集中审查。先看高风险任务，再看低风险任务。能合并的转 PR，值得继续的追问，价值低的归档。每天结束前清理未处理线程，记录哪些任务需要明天继续。这样 App 会成为工作台，而不是未完成任务仓库。

团队协作：避免多个成员委派同一类任务

团队多人同时使用 App 时，还要防止重复委派。两个成员可能分别让 Codex 修同一个 CI 失败，或者同时补同一个模块测试。解决方式不是限制使用，而是让任务来源可见。

可以在 Issue 上加状态标签，例如 codex-running、codex-reviewing、codex-result-ready。也可以在团队频道记录正在运行的线程摘要。对高风险任务，要求先认领再委派。对低风险文档或测试任务，可以宽松一些。

多人协作还要统一输出格式。若每个人要求 Codex 用不同格式汇报，后续 review 成本会增加。团队可以约定所有写代码线程都输出结果、文件、验证、风险、下一步。只读线程输出事实、假设、建议任务和不确定点。

App 的并行能力只有和团队可见性结合，才不会变成重复劳动。

落地问答：什么时候该停线程

问：线程已经跑偏，但还在产出内容，要不要继续追问？答：先看是否越过边界。如果已经改了禁止文件、引入依赖或偏离目标，通常应停止并重开。继续追问会在错误上下文上叠加更多修改。

问：线程结果只有一半可用，是否手工捡出来？答：小范围可以。若可用部分很清楚，可以由人提取到新分支；若 diff 混杂，重开任务往往更便宜。App 的价值之一就是让失败候选可丢弃，不要舍不得。

问：并行线程之间发现同一根因怎么办？答：选择证据更完整、diff 更小、验证更好的一个继续。另一个归档。不要把两个实现混在一起，除非人明确做合并设计。

问：可以让一个线程专门审其他线程吗？答：可以，但要明确只读。审查线程输出 findings 和比较意见，不修改文件。若它也写代码，就会把审查变成新的实现线程。

问：什么时候用 App，什么时候用 CLI？答：单一任务、需要贴近终端、需要快速交互时，CLI 更直接。多个候选、多个项目、后台执行、审查队列管理时，App 更合适。

延伸阅读

• Codex App
• Codex App Features
• Codex App Worktrees
• Codex App Automations
• Custom instructions with AGENTS.md

---

GitHub 原文：26-codex-app-parallel-workbench.md