OpenAI Symphony：当一个 Markdown 文件成为整个系统的唯一真实来源

"Symphony is technically just a SPEC.md file." — Alex Kotliarskyi, OpenAI

一个激进的实验

2026 年 4 月，OpenAI 开源了 Symphony。这个项目最出格的地方不是它做了什么——agent orchestration 已经有 Composio 的 Agent Orchestrator、Claude Squad、Bernstein 等竞品——而是它的存在形式。

当你打开 Symphony 的 GitHub repo，里面没有 40,000 行 TypeScript。只有一个 SPEC.md 文件，和一份用 Elixir 写的参考实现。

OpenAI 团队的做法是：把 SPEC.md 扔给 Codex，说"按这个实现"。Codex 用 Elixir 一次性写出了参考实现。然后他们为了验证 spec 的清晰度，又把它扔给 Codex 分别用 TypeScript、Go、Rust、Java、Python 各实现了一遍。全部成功。

费曼会问：这意味着什么？

这意味着 specification 本身成为了系统的唯一真实来源。不是代码，不是架构图，是一个 Markdown 文件。代码成了可丢弃的——只要能通过 spec 验证，用任何语言写都行。

一、核心问题：人类注意力是 bottleneck

OpenAI 团队内部的起点和 Composio 的 pkarnal 惊人地相似：

"Each engineer would open a few Codex sessions... most people could comfortably manage three to five sessions at a time before context switching became painful."

他们发现自己不是在管理代码，而是在微管理一群非常能干的实习生——跳终端窗口、看 CI、处理 agent 卡住、转发 review comments。Agent 能写代码，但人类成了瓶颈。

Symphony 的解法是：把 issue tracker（Linear）变成控制平面。不是人类去管理 agent session，而是 agent 自己去 ticket board 领任务、干活、交卷。

二、架构：SPEC.md 里长出的六层系统

Symphony 的架构文档非常完整——因为 SPEC.md 本身就是完整的架构文档。核心六层：

2.1 六层抽象

设计意图：每层有明确边界。想移植 Symphony 到另一个语言？只需要逐层重写，层间接口不变。OpenAI 用 Codex 在 6 种语言里验证了这个假设。

2.2 七大核心组件

2.3 状态机：5 个 claim states + 11 个 run phases

Orchestrator 内部有严格的 claim 状态机：

Unclaimed → Claimed → Running → RetryQueued → Released

• Unclaimed：没在跑，没 retry
• Claimed：已预留，防止重复 dispatch
• Running：worker 在执行
• RetryQueued：worker 停了，但 retry timer 在等
• Released：issue 到 terminal state，或 retry 完成但没 re-dispatch

Run Attempt 的生命周期更细：

PreparingWorkspace → BuildingPrompt → LaunchingAgentProcess → 
InitializingSession → StreamingTurn → Finishing → 
Succeeded | Failed | TimedOut | Stalled | CanceledByReconciliation

关键设计：continuation turns 复用同一个 threadId。一个 worker 可以在同一会话里跑多轮 turn（最多 max_turns，默认 20），每轮 turn 结束后重新检查 issue state。只有 issue 仍在 active state 时才继续。

三、WORKFLOW.md：把团队规则版本化

这是 Symphony 最有工程智慧的设计。

WORKFLOW.md 是一个放在 repo 根目录的 Markdown 文件：

---
tracker:
  kind: linear
  project_slug: my-project
  active_states: ["Todo", "In Progress"]
agent:
  max_concurrent_agents: 10
  max_turns: 20
codex:
  turn_timeout_ms: 3600000
---

You are working on issue {{issue.identifier}}: {{issue.title}}.
{% if attempt %}
This is a retry (attempt {{attempt}}). Focus on fixing the previous failure.
{% endif %}

Steps:
1. Check out the repo in the workspace
2. Implement the fix
3. Run tests locally
4. Create a PR with description

三个工程化决策：

1. Repo-owned：和代码一起版本控制。git history 就是 prompt evolution history。
2. Hot-reload：文件改了不用重启 service，下次 poll tick 自动生效。
3. Strict template engine：用 Liquid 语义，unknown variable/filter 直接 fail rendering——不让 agent 拿到残缺或错误的 prompt。

OpenAI 的原话：

"The development workflow... was never documented. Rather than relying on this implicit set of steps, we now document it, and Symphony ensures agents follow it."

四、安全不变式：三条不可违背的底线

SPEC.md 里最硬核的部分是安全 invariant：

Invariant 1：Agent 进程必须在 workspace_path 内执行。启动前校验 cwd == workspace_path。

Invariant 2：workspace_path 必须是 workspace_root 的合法子目录。用绝对路径规范化后做前缀检查，拒绝任何 path traversal。

Invariant 3：Workspace 目录名只能包含 [A-Za-z0-9._-]，其他字符替换为 _。

这些不是"建议"，是 conformance 要求。任何实现如果不满足，就不是合法的 Symphony 实现。

五、Codex App Server：为什么不用 CLI 或 tmux？

Symphony 选择 Codex App Server（headless JSON-RPC over stdio）而非 CLI/tmux 交互。协议握手：

{"id":1,"method":"initialize","params":{"clientInfo":{"name":"symphony","version":"1.0"}}}
{"method":"initialized","params":{}}
{"id":2,"method":"thread/start","params":{"approvalPolicy":"auto","cwd":"/workspace"}}
{"id":3,"method":"turn/start","params":{"threadId":"...","input":[{"type":"text","text":"..."}]}}

好处：

• 程序化控制：不用 parse terminal 输出，直接读 JSON 事件
• 结构化遥测：token 用量、rate limit、turn count 都是 machine-readable
• 动态 tool calls：可以在运行时给 agent 暴露 linear_graphql 等工具，不依赖 MCP，也不把 token 暴露给 agent 容器

六、数据：500% PR 增长的真相与边界

6.1 声称的数据

• 某些团队 landed PR 增长 500%（前 3 周）
• GitHub stars 15,000+（截至 4 月 23 日）
• 一位工程师在 cabin 用 Linear mobile app 提交了 3 个任务，agent 自动完成

6.2 费曼式审视

"500%"意味着什么？

如果原来一个工程师一周 land 2 个 PR，现在 land 10 个。但这 10 个里有多少是：

• 探索性任务（试了扔掉）
• 小 refactor（不需要人类 review）
• agent 自己创建的问题（scope creep）

OpenAI 自己也说：

"We can very cheaply file tickets for the agent to go prototype and explore, and throw away any explorations we don't like."

500% 里的很多可能是"disposable PRs"。真正需要 human review 的复杂 PR，增长可能没有 500%。

Cabin 工程师的故事

这很浪漫，但要注意条件：

• 代码库已经是 "agent-friendly"（有 harness engineering 基础）
• 有完善的 CI 和 guardrails
• 任务已经拆得够细
• 不需要人类 mid-flight 纠正

不是"任何任务都可以丢给 agent 然后去 cabin"。是"已经 setup 好的流水线可以在你不在时继续跑"。

七、与 Composio Agent Orchestrator 的对比

既然今天刚写了 Agent Orchestrator 的拆解，直接对比：

关键差异：

• Symphony 是 minimal spec，演示 Codex App Server 的可能性。OpenAI 明确说不会维护为产品。
• Agent Orchestrator 是 productized platform，有 dashboard、自改进、多 agent 支持。
• Symphony 的 WORKFLOW.md 让 prompt 版本化；Agent Orchestrator 的 ao.config.yaml 让配置模块化。

八、费曼式终极审视：这到底是魔法还是工程？

8.1 "SPEC.md 是唯一真实来源"

这个说法很 radical，但需要拆开：

• SPEC.md 定义了接口契约、状态机、配置 schema、安全不变式
• 但 SPEC.md 不能运行。运行的是 Elixir/TypeScript/Python 实现
• 实现和 spec 之间的 gap 需要测试来 bridge

所以真实来源不是 SPEC.md 本身，而是 "能通过 spec 验证的实现"。SPEC.md 是宪法，实现是政府。没有司法（测试），宪法只是一张纸。

8.2 "Codex 实现了 6 种语言版本"

这证明了 spec 的清晰度，但不证明 spec 的正确性。一个 spec 可以是清晰的（unambiguous）但错误的（wrong）。OpenAI 没有公开说"6 个实现的所有测试都通过了"。

费曼会问："你把 spec 扔给 Codex，它写出来了。但你有没有写一个独立于实现的测试集，去验证这 6 个实现的行为一致性？" 如果没有，那"6 种语言"更多是 marketing，不是 engineering。

8.3 "我们不维护为独立产品"

OpenAI 的诚实令人意外。但也暴露了一个问题：如果 Symphony 是 reference implementation 而非 product，企业团队想 adoption 时，谁来保证长期维护？

答案可能是：Symphony 的真正价值不是让你直接用，而是让你用 Codex 照着 spec 写一个适合自己环境的版本。这是一个 meta-pattern：

1. 写 spec
2. 扔给 Codex
3. 获得定制化实现
4. 迭代 spec

但这也假设了你已经有 Codex + 能验证实现正确性的能力。对大多数团队，这个门槛不低。

8.4 "Harness Engineering 是前提"

OpenAI 反复强调 Symphony 需要先有 harness engineering：

• 测试能在本地独立运行
• 文档机器可读
• 架构模块化

费曼会说："这不就是在说，Symphony 不是魔法药水——它只在已经健康的代码库上工作？" 是的。Symphony 是放大器，不是转换器。它能让好的工程实践产生 5x 输出，但不能让烂代码库变好。

九、核心结论

Symphony 真正重要的不是它的 Elixir 代码，不是 500% PR 增长，不是 15K GitHub stars。

真正重要的是它验证了一个假设：当代码生成成本趋近于零时，系统的价值从"代码本身"转向"定义代码行为的规范"。

SPEC.md 就是这个规范的载体。它把 prompt engineering 从"散落在各处的手艺"变成了"可版本化、可 review、可回滚的工程 artifact"。

这和一个趋势一脉相承：

• Claude Code 的 .claude/ 目录
• Cursor 的 .cursorrules
• Agent Orchestrator 的 ao.config.yaml
• 以及 Symphony 的 WORKFLOW.md

整个行业正在从"每个 session 从零开始"进化到"每个 repo 有自己的 agent 行为契约"。

Symphony 的贡献，是用一个完整的开源 spec 把这个趋势推到了极致：

不是 agent 管理代码，而是规范管理 agent。

参考链接

• 官方博客: https://openai.com/index/open-source-codex-orchestration-symphony/
• GitHub: https://github.com/openai/symphony
• SPEC.md: https://github.com/openai/symphony/blob/main/SPEC.md
• Codex App Server 文档: https://developers.openai.com/codex/app-server/
• Harness Engineering 博客: https://openai.com/index/harness-engineering/

#Symphony #OpenAI #Codex #AgentOrchestration #SPEC驱动开发 #工程规范 #费曼视角 #小凯