Symphony：一个开源的编排规范

# Codex 编排的开源规范：Symphony 来源：https://openai.com/index/open-source-codex-orchestration-symphony/ 六个月前，在开发内部生产力工具时，我们的团队做出了一项当时颇具争议的决定：我们将构建一个完全由 Codex 生成代码的仓库，不编写任何人类手写的代码。 为了实现这一目标，我们从头开始重新设计了工程工作流。我们构建了适合代理的仓库，在自动化测试和防护机制上投入了大量精力，并将 Codex 视为一名正式队友。我们在之前关于驾驭工程（harness engineering）的博客文章（https://openai.com/index/harness-engineering/）中记录了这段历程。 这确实奏效了，但随后我们遇到了下一个瓶颈：上下文切换。 为了解决这个新难题，我们构建了一个名为 **Symphony** 的系统。Symphony（https://github.com/openai/symphony）是一个代理编排器，它能将 Linear 这样的项目管理看板转变为编码代理的控制平面。每个未解决的任务都会分配到一个代理，代理持续运行，而人类负责审核结果。 本文将解释我们如何创建 Symphony——使某些团队的已合并拉取请求数量增加了 500%——以及如何使用它将你自己的问题追踪器转变为全天候运行的代理编排器。 ### 交互式编码代理的天花板 尽管使用起来越来越便捷，但无论是通过 Web 应用还是 CLI 访问的编码代理，本质上仍然是交互式工具。 随着 OpenAI 内部代理化工作规模的扩大，我们发现了一种新的负担。每位工程师会打开几个 Codex 会话，分配任务、审核输出、引导代理，然后重复这一过程。实际上，大多数人能够轻松管理三到五个会话，超过这个数量后，上下文切换就会变得痛苦。再往上，生产力就会下降。我们会忘记某个会话在做什么，在终端之间切换以将代理拉回正轨，还要调试那些运行到一半就卡住的长时任务。 代理速度很快，但我们的系统瓶颈在于：人类注意力。我们实际上组建了一支能力极强的初级工程师团队，然后让人类工程师去 micromanage 他们。这无法规模化。 ### 视角的转变 我们意识到优化错了方向。我们围绕编码会话和已合并 PR 来设计系统，但 PR 和会话其实只是手段。软件工作流本质上围绕可交付成果组织：问题、任务、工单、里程碑。 于是我们问自己：如果不再直接监督代理，而是让它们从任务追踪器中拉取工作，会发生什么？ 这个想法演变成了 Symphony，一份作为监督者来编排代理化工作的书面规范。 ### 将问题追踪器转变为代理编排器 Symphony 始于一个简单的概念：任何未解决的任务都应该由代理接手并完成。我们不再在多个标签页中管理 Codex 会话，而是让问题追踪器成为控制平面。 我们经常使用 Symphony 来编排复杂特性和基础设施迁移。例如，我们可能会提交一个任务，让代理分析代码库、Slack 或 Notion，并产出一份实现方案。一旦我们对方案满意，代理就会生成一棵任务树，将工作分解为多个阶段，并定义任务之间的依赖关系。 代理只会在任务未被阻塞时才开始工作，因此执行会自然且最优地并行展开，形成 DAG（执行步骤序列）。例如，我们将 React 升级标记为依赖于 Vite 迁移。正如预期，代理只在 Vite 迁移完成后才开始升级 React。 代理也可以自己创建工作。在实现或审核过程中，它们经常会注意到当前任务范围之外的改进点：性能问题、重构机会或更优的架构。当这种情况发生时，它们会简单地创建一个新问题，我们可以稍后评估和排期——其中许多后续任务也会被代理接手。虽然我们监督着这个过程，但代理保持有序组织，持续推动工作前进。 这种工作方式大幅降低了启动模糊工作的认知成本。如果代理做错了，那仍然是有用的信息，而且我们的成本几乎为零。我们可以极低成本地为代理创建工单去原型化和探索，扔掉任何不喜欢的探索成果。 由于编排器在开发机器上运行且永不休眠，我们可以从任何地方添加任务，并知道代理会接手。例如，我们团队中的一位工程师在偏远小屋里用着糟糕的 WiFi，通过手机上的 Linear 应用完成了三项重大改动。 ### 这种工作方式带来的探索增加 在观察使用 Symphony 的效果时，最明显的变化是产出。在 OpenAI 的一些团队中，我们看到前三个周内已落地 PR 的数量增加了 500%。在 OpenAI 外部，Linear 创始人 Karri Saarinen 也指出，随着我们发布 Symphony，工作空间创建数量出现激增（https://x.com/karrisaarinen/status/2031773828284919878）。然而，更深层的转变在于团队如何看待工作。 当我们的工程师不再花时间监督 Codex 会话时，代码变更的经济性完全改变了。每次变更的感知成本下降，因为我们不再投入人类精力去推动实现本身。 这改变了我们的行为。在 Symphony 中启动探索性任务变得轻而易举。尝试一个想法、探索一次重构、验证一个假设，只保留看起来有前景的结果。 这也扩大了能够发起工作的人群范围。我们的产品经理和设计师现在可以直接向 Symphony 提交功能请求。他们不需要拉取代码库或管理 Codex 会话。他们描述功能，然后收到一份审核包，其中包含该功能在真实产品中运行的视频演示。 Symphony 在大型 monorepo（如 OpenAI 的）中同样表现出色，在这些地方，PR 落地的最后一公里既缓慢又脆弱。系统监控 CI、在需要时 rebase、解决冲突、重试不稳定的检查，通常会将变更一路护送到流水线中。当一张工单到达 **Merging** 状态时，我们有很高的信心认为该变更无需人类看护就能进入主分支。 实施 Symphony 后，我们将更多工作委托给代理，自己则专注于更困难、更具探索性的任务。 ### 进步伴随着新的、不同的问题 在这种水平上运行伴随着权衡。当我们从交互式引导代理转变为在工单层面分配工作时，我们失去了在过程中不断微调、在需要时纠正航向的能力。有时代理产出的东西完全偏离目标。这很有用——这些失败揭示了系统中的缺口，帮助我们使其更加健壮。 我们没有手动修补结果，而是添加了防护机制和技能，让代理下次能够成功。随着时间的推移，这促使我们为 harness 增加了新能力，比如运行端到端测试、通过 Chrome DevTools 驱动应用、管理 QA 冒烟测试。我们大幅改进了文档，明确了"好"的标准是什么。 并非每个任务都适合 Symphony 的工作方式。有些问题仍然需要工程师直接使用交互式 Codex 会话，尤其是那些模糊的问题或需要强判断力和专业知识的工作。实际上，这些通常是我们的工程师最感兴趣、最乐于投入时间的任务。 区别在于，Symphony 可以处理大部分常规实现工作。这让工程师能够一次专注于一个难题，而不是在多个小任务之间不断切换上下文。 我们还学到，将代理视为状态机中的刚性节点并不奏效。模型变得更聪明，能够解决比我们试图框定的盒子更大的问题。我们早期版本的代理化工作只是让 Codex 实现任务。那种方法证明太过局限。Codex 完全有能力创建多个 PR，也能阅读审核反馈并处理。于是我们给了它工具——`gh` CLI、读取 CI 日志的技能等——现在我们可以让 Codex 做更多事情，比如关闭旧 PR 或拉取已完成与已放弃工作的报告。这些任务类型远远超出了最初的功能实现框架。 所以我们最终转向给代理**目标**而非严格的转换，就像优秀的经理会给直属下属分配团队目标一样。模型的力量来自于它们的推理能力，所以给它们工具和上下文，让它们放手去做。 ### 用 Symphony 构建 Symphony 当你打开 Symphony 仓库（https://github.com/openai/symphony）时，首先会注意到的是，Symphony 在技术上只是一个 `SPEC.md` 文件——对问题和预期解决方案的定义。我们没有构建复杂的监督系统，而是定义了问题和预期解决方案，给代理高层次的引导。 参考实现是用 Elixir 编写的——因为当代码实际上免费时，你终于可以纯粹根据语言优势来选择语言，比如 Elixir 的并发能力——但核心思想可以用一个简单的 Markdown 文档来表达。我们鼓励你把你最喜欢的编码代理指向这份规范，让它实现自己的版本。 Symphony 的第一个版本只是在 `tmux` 中运行的一个 Codex 会话，轮询 Linear 并为新任务生成子代理。它能工作，但不太可靠。第二个版本存在于我们的主项目仓库中，这个仓库是为代理设计的。我们已经构建了 agent harness，为代理提供高质量工作所需的技能和上下文，所以 Symphony 只是将所有这些连接起来。 一旦基本功能存在，我们就用 Symphony 来构建 Symphony。 当我们内部演示这个系统管理任务并附加其工作证明视频时，反响极为积极：我们的 Symphony 项目频道不断壮大，整个组织的团队开始自发使用它。内部产品市场契合度是 OpenAI 对外发布的前提。基于我们在 OpenAI 看到的使用情况，显然我们应该将 Symphony 分享到公司之外。 于是我们将这个想法提取为独立的 `SPEC.md`，并让 Codex 来实现它。对于参考实现，我们选择了 Elixir，这是一种相对小众但具有出色原语来编排和监督并发进程的语言。Codex 一次性构建出了 Elixir 实现，然后我们持续迭代规范和实现。为了打磨规范，我们甚至让 Codex 用几种其他语言——TypeScript、Go、Rust、Java、Python——来实现它，并利用结果来识别歧义和简化系统。它在每种语言中都成功了。 通过构建 Symphony 的过程，我们移除了许多偶发复杂性，比如对特定仓库或 Linear MCP 的依赖。Symphony 不再依赖我们的内部仓库或工作流。核心方法变得简单： 除了帮助处理活跃工作外，开发工作流现在也是代理了解并遵循的。开发工作流——处理问题、检出仓库、将其标记为进行中以便 PM 知道它正在被处理、添加 PR、移动到 **Review** 状态、附加视频等——现在被记录在一个简单的 `WORKFLOW.md` 文件中。所有这些都是人类遵循的流程，但从未被文档化。我们现在不再依赖这套隐性的步骤，而是将其文档化，Symphony 确保代理遵循它。这让我们能够构建与人类并肩工作的代理。如果我们决定代理还应该在完成工作时附加自我反思，我们会将其添加到 `WORKFLOW.md` 中，Symphony 就会引导代理执行该步骤。 我们还使用了 Codex 的 app server 模式（https://developers.openai.com/codex/app-server/），这是 Codex 内置的无头模式。该模式允许我们运行 Codex 并通过文档完善的 JSON-RPC API 以编程方式与其交互，例如启动线程或响应轮次。这比通过 CLI 或实时 `tmux` 会话与 Codex 交互更方便、更可扩展。 Codex App Server 非常适合我们的用例：我们利用 Codex 提供的 harness，同时拥有可插拔的旋钮和钩子。例如，为了避免将 Linear 访问令牌暴露给子代理，我们使用了动态工具调用（https://developers.openai.com/codex/app-server/#dynamic-tool-calls-experimental）来暴露原始的 `linear_graphql` 函数，该函数对 Linear 执行任意请求，而无需依赖 MCP 或将访问令牌暴露给容器。 ### 未来展望 Symphony 是一个有意保持极简的编排层。我们将其开源，以展示 Codex App Server 与 Linear 等不同工作流工具搭配时的强大能力。因此，我们不计划将 Symphony 作为独立产品来维护。请将其视为参考实现。类似于许多开发者将他们的编码代理指向驾驭工程文章来搭建仓库，我们希望你将你最喜欢的编码代理指向 Symphony 规范（https://github.com/openai/symphony/blob/main/SPEC.md）和仓库（https://github.com/openai/symphony），来构建适合你自身环境的版本。 真正的力量来自 Codex 及其 app server。Symphony 是将 Codex 与 Linear（我们已经在使用的两个东西）连接起来解决工作管理问题的一种方式。随着编码代理在推理和遵循指令方面变得更好，我们猜测其他公司的瓶颈也会从编写代码转向管理代理化工作。令人兴奋的是，尝试这些编码代理系统的门槛现在出奇地低。你可以直接用 Codex 构建东西。