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

# 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 六层抽象 | 层级 | 职责 | 例子 | |---|---|---| | **Policy Layer** (repo-defined) | 业务规则、prompt 模板、handoff 逻辑 | `WORKFLOW.md` 里的 Markdown body | | **Configuration Layer** | 类型化的运行时设置、env var 解析、默认值 | YAML front matter → typed getters | | **Coordination Layer** | 轮询、issue eligibility、并发控制、重试、对账 | Orchestrator 状态机 | | **Execution Layer** | 文件系统生命周期、workspace 准备、agent 协议 | Workspace Manager + Agent Runner | | **Integration Layer** | Issue tracker API 适配、数据规范化 | Linear adapter (GraphQL) | | **Observability Layer** | 结构化日志、状态 surface、token 统计 | Logging + 可选 Status Surface | **设计意图**：每层有明确边界。想移植 Symphony 到另一个语言？只需要逐层重写，层间接口不变。OpenAI 用 Codex 在 6 种语言里验证了这个假设。 ### 2.2 七大核心组件 | 组件 | 功能 | |---|---| | **Workflow Loader** | 读取 `WORKFLOW.md`，解析 YAML front matter + Markdown prompt body | | **Config Layer** | 类型化 getter，处理 env var 间接引用（`$VAR_NAME`），运行时动态重载 | | **Issue Tracker Client** | 轮询 tracker API，拉 candidate issues，规范化数据结构 | | **Orchestrator** | 唯一可变调度状态的权威。poll tick、分派、重试、对账 | | **Workspace Manager** | 映射 issue identifier → workspace path，创建/复用/清理 | | **Agent Runner** | 启动 app-server 子进程，JSON-RPC 协议握手，流式处理 turn | | **Status Surface** (可选) | 人类可读的状态输出（终端、dashboard） | ### 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 文件： ```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 交互。协议握手： ```json {"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 (OpenAI) | Agent Orchestrator (Composio) | |---|---|---| | **核心哲学** | Spec-first，SPEC.md 是唯一真实来源 | Product-first，TypeScript 实现 + 插件生态 | | **代码量** | SPEC.md ~1000 行 + Elixir ref impl | ~40,000 行 TypeScript + 17 插件 | | **控制平面** | Linear ticket board | Web dashboard + terminal | | **Agent 支持** | 仅 Codex (app-server) | Claude Code, Aider, Codex, OpenCode 等 | | **Issue Tracker** | Linear (目前) | GitHub, Linear | | **自改进** | 无 | 有（ao-52，记录 prompt 效果、CI 模式） | | **Reactions** | 无（agent 自己用 linear_graphql 写 ticket） | 有（ci-failed, changes-requested 自动响应） | | **Workspace 隔离** | 目录隔离（无 VCS 强制） | Git worktree | | **并发规模** | 未公开上限（内部使用） | 峰值 30 | | **维护承诺** | "不维护为独立产品" | 积极维护 | **关键差异**： - 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驱动开发 #工程规范 #费曼视角 #小凯