Symphony 使用教程

📖 项目简介

Symphony 是 OpenAI 官方开源的"AI 编程编排框架"，定位是 把项目工作变成隔离、自主的实施任务，让团队从"监督编码 Agent"升级到"管理工作"。

它会持续监控 Linear 看板，自动 spawn 一个 Codex Agent 处理工单：从规划、写代码、跑 CI、自我纠错，到提交 PR 并附带走查视频、复杂度分析、PR review 反馈等"工作证明"。工程师只需要在看板派活、最后点合并即可——不用再盯着 AI 写代码。

💡

GitHub 地址： https://github.com/openai/symphony
官方文章： openai.com · Open-source Codex orchestration: Symphony
SPEC 文档： SPEC.md（核心规范，可让任意 Agent 帮你重新实现）

⚠️

官方提示：Symphony 当前是低调发布的工程预览版（engineering preview），建议在受信任的环境里测试，先不要直接用于核心生产仓库。

✨ 核心亮点

📋

Linear 自动接单

监控 Linear 工单看板，发现新任务自动 spawn 一个 Codex Agent 接活，工程师只管派活

🧊

隔离实施运行

每个 Agent 跑在独立的工作空间里，互不干扰、可并行多任务，避免上下文污染

🎬

走查视频汇报

PR 自带视频 walkthrough、CI 状态、复杂度分析、PR review 反馈四类"工作证明"

✅

PR 安全落地

通过审核的 PR 由 Agent 自主合并，不通过则修复重提，实现端到端闭环

🛠️

harness 工程友好

官方推荐与 harness engineering 实践配合，自动化测试与代码审查越完善，效果越好

🏛️

OpenAI 官方背书

官方仓库 23.7K Star，Apache 2.0 协议，参考实现使用 Elixir，长期生态可期

🚀 如何使用

Symphony 提供两种上手方式，均不需要"从零造轮子"：

方式一：让 AI 编程助手按 SPEC 帮你实现

把这句话发给你最常用的 AI 编程助手（Codex / Cursor / Claude Code 等）：

                        Prompt
Implement Symphony according to the following spec:
https://github.com/openai/symphony/blob/main/SPEC.md
                    

AI 会基于 SPEC.md 用你偏好的语言（Python / TypeScript / Go 等）生成一份私有定制实现，适合想深度定制工作流的团队。

方式二：使用官方 Elixir 参考实现（推荐先体验）

官方仓库的 elixir/ 目录是可直接运行的参考实现。把这句话丢给 AI 助手，让它帮你完成环境配置：

                        Prompt
Set up Symphony for my repository based on
https://github.com/openai/symphony/blob/main/elixir/README.md
                    

或者手动按下面命令拉代码：

                        bash
git clone https://github.com/openai/symphony.git
cd symphony/elixir
# 按目录下的 README.md 配置 Linear API Key、Codex 凭据等
cat README.md
                    

配置 Linear 集成与 Codex 凭据

Symphony 的工单源是 Linear，编码引擎是 OpenAI Codex CLI。因此你需要准备：

Linear API Key（Personal API Key 或 OAuth）
Linear 项目 / 团队 ID（Symphony 监控哪个看板）
OpenAI API Key 或 ChatGPT 登录凭据（供 Codex Agent 使用）
目标代码仓库的 Git 凭据（让 Agent 能 push 分支、开 PR）

启动 Symphony 守护进程

在 elixir/ 目录下按 README 启动服务（一般是 mix deps.get + mix run --no-halt 或类似命令）。启动后，Symphony 会以后台守护进程的方式持续轮询 Linear。

✅

启动成功的标志：日志中出现"watching Linear team / project"字样，派一个测试工单到看板，Symphony 会拉起一个独立 Agent 进程并打印任务 ID。

派活 → 验收

在 Linear 上正常创建工单（按团队约定填好标题、描述、验收标准）。Symphony 监听到后自动接单：

独立隔离工作区拉代码、装依赖
Codex Agent 写代码 + 跑测试 + 自我纠错
提 PR，附带 CI 状态、PR review、复杂度分析、走查视频
你只在 GitHub 点 Approve / 合并即可，不通过会自动修复重提

🎯 适合谁用

👤

一人公司 / 超级个体

把零散需求丢进看板，AI 自动消化，自己专注产品方向和市场

👥

小团队工程负责人

把重复性、模板化任务（CRUD、bug fix、依赖升级）交给 Symphony，团队聚焦核心架构

🧪

harness 实验先驱

已有完善 CI / 自动化测试 / PR review 机器人的团队，落地效果最佳

❓ 常见问题

Q: Symphony 和 Codex / Cursor / Claude Code 是什么关系？

它们不是同一层东西。Codex / Cursor / Claude Code 是编码助手（写代码工具），而 Symphony 是编排框架（管工作的工具），它会调用 Codex 这类底层 Agent 干活。可以理解为 Symphony = "AI 工程项目经理"，Codex = "AI 程序员"。

Q: 必须用 Linear 吗？能换成 Jira / GitHub Issues 吗？

官方 Elixir 实现目前以 Linear 为一等公民。如果想换源，可以参考 SPEC.md 的工单接入抽象，让 AI 编程助手帮你写一个 Jira / GitHub Issues 的适配层；这也是官方推荐的"自己实现一份"路径。

Q: 能用在生产关键仓库吗？

官方明确警告 Symphony 当前是 engineering preview，建议先在受信任的小型仓库 / 内部项目试水。对外营业的核心代码库务必先做好 CI / PR review / 权限隔离，再引入 Symphony。

Q: 必须懂 Elixir 才能用吗？

不需要。即使完全不会 Elixir，让 AI 助手按 README 帮你装环境就行；如果想深度改造，也可以让 AI 按 SPEC.md 用 Python / TypeScript 重写一份，效果一样。