symphony-setup

Symphony 设置

设置 Symphony——OpenAI 的编排器，可通过自主 Codex Agent 将 Linear 工单转化为拉取请求。

前置检查

先运行以下检查，如果任何一项失败，请停止——解决问题后再继续：

1. codex——运行 codex --version。必须已安装并完成身份验证。
2. mise——运行 mise --version。用于管理 Elixir/Erlang 版本。
3. gh——运行 gh auth status。必须已安装并完成身份验证。Agent 会使用 gh 创建 PR 并关闭孤立的 PR。缺少它时操作会静默失败。
4. LINEAR_API_KEY——运行 test -n "$LINEAR_API_KEY" && echo "set" || echo "missing"。必须在不同会话间持续有效（写入 shell 配置，而不只是运行 export）。
5. Linear MCP——确认 Linear MCP 可用。如果不可用，请进行设置：
   • Claude Code：claude mcp add --transport http linear https://mcp.linear.app/mcp
   • Codex：codex mcp add linear --url https://mcp.linear.app/mcp
   • 其他客户端：参见 Linear MCP 文档
6. Git 克隆身份验证——after_create 钩子会在无人值守时运行 git clone。确认用户的仓库克隆 URL 可以在非交互模式下使用：git clone --depth 1 <url> /tmp/test-clone && rm -rf /tmp/test-clone。需要输入密码的 HTTPS 会静默失败。请使用 SSH 密钥（无密码短语），或使用带凭据助手／令牌的 HTTPS。

继续之前，先向用户报告检查结果。

构建 Symphony

使用 分支版本——更容易上手：

git clone https://github.com/odysseus0/symphony
cd symphony/elixir
mise trust && mise install
mise exec -- mix setup
mise exec -- mix build

注意：如果平台提供预编译版本，mise install 会下载预编译的 Erlang/Elixir；否则会从源代码编译，这可能需要 10-20 分钟。开始前请告知用户。

准备用户的仓库

尽可能多地自动检测。只在需要确认或补充信息时询问用户。

自动检测仓库信息

• 仓库路径——在当前目录运行 git rev-parse --show-toplevel。如果当前目录不在 Git 仓库中，请询问用户。
• 克隆 URL——运行 git remote get-url origin。确认其可在非交互模式下使用：git clone --depth 1 <url> /tmp/test-clone && rm -rf /tmp/test-clone。
• 设置命令——根据锁文件／清单推断，并与用户确认。

自动发现 Linear 项目

使用 Linear MCP 列出项目。展示列表并让用户选择。slugId 是要填入 WORKFLOW.md 中 tracker.project_slug 的值。

自动检查并创建工作流状态

用户选择项目后，使用 Linear MCP 检查团队的工作流状态。必须有三个自定义状态。如果缺少任何状态，请通过 curl 创建：

curl -s -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  -d '{"query": "mutation($input: WorkflowStateCreateInput!) { workflowStateCreate(input: $input) { success workflowState { id name } } }", "variables": {"input": {"teamId": "<team-id>", "name": "<name>", "type": "started", "color": "<color>"}}}'

名称	颜色
返工	#db6e1f
人工审核	#da8b0d
合并中	#0f783c

创建前请与用户确认。

自动检测应用／UI

询问前，先检查项目是否有可启动的 UI：

• package.json 依赖中有 electron 或 electron-builder → Electron 应用
• 依赖中有 react-scripts、next、vite、nuxt → 带开发服务器的 Web 应用
• package.json 中有 start 或 dev 脚本 → 可能有开发服务器
• Procfile、docker-compose.yml → 带运行时的服务

如果检测到 UI，请根据检测结果（框架、启动脚本、默认端口）提出一个 launch-app 技能方案。与用户确认并按需调整。如果没有检测到任何内容，请询问是否有 UI——对于纯库／CLI／API 项目，请跳过启动技能。

安装技能和工作流

从 Symphony 向用户的仓库安装两项内容：

1. 技能——通过 skills.sh 安装（Agent 需要在其工作区克隆中使用这些技能）：

   cd <user's repo>
   npx skills add odysseus0/symphony -a codex -s linear land commit push pull debug --copy -y
   

   必须使用 --copy 标志——符号链接在工作区克隆中会失效。-s 标志会排除 symphony-setup（元技能，工作者不需要）。
2. elixir/WORKFLOW.md——复制整个文件，包括 Markdown 正文。提示词正文包含状态机、规划协议和验证策略，这些内容能让 Agent 高效工作。

修补 WORKFLOW.md 前言

两项修改：

1. 项目 slug

tracker:
  project_slug: "<user's project slug>"

2. after_create 钩子

完全替换——默认配置会克隆 Symphony 仓库本身：

hooks:
  after_create: |
    git clone --depth 1 <user's repo clone URL> .
    <user's setup commands, if any>

其他内容一律保持不变。 分支环境、approval_policy、轮询间隔和并发设置在分叉版本中都有合适的默认值。

应用启动技能（如适用）

如果用户的项目有需要进行运行时测试的 UI 或应用，请在其仓库中创建 .agents/skills/launch-app/SKILL.md：

---
name: launch-app
description: Launch the app for runtime validation and testing.
---

# Launch App

<launch command and any setup steps specific to the user's project>
<how to verify the app is running>
<how to connect for testing — e.g., agent-browser URL, localhost port>

WORKFLOW.md 提示词会要求 Agent 对涉及应用的更改“运行时验证”。如果没有此技能，Agent 就不知道如何启动应用。对于非应用类仓库（库、CLI、API），请跳过此步骤。

提交并推送

将 .agents/skills/、WORKFLOW.md 和 launch-app 技能（如果已创建）提交到用户的仓库并推送。推送至关重要——Agent 会从远程仓库克隆，因此未推送的更改对工作进程不可见。

推送后进行验证：git log origin/$(git branch --show-current) --oneline -1 应显示你的提交。

启动前：检查活动工单

启动 Symphony 前，使用 Linear MCP 列出所有处于活动状态（Todo、In Progress、Rework）的工单。Symphony 会立即为每个活动工单分派 Agent，不只是新工单。

向用户展示列表，并询问他们是否愿意让这些工单全部开始处理。对于他们尚未准备好移交的工单，将其移回 Backlog。

运行

cd <symphony-path>/elixir
mise exec -- ./bin/symphony <repo-path>/WORKFLOW.md \
  --i-understand-that-this-will-be-running-without-the-usual-guardrails

必须启用 guardrails 标志——Symphony 使用 danger-full-access 沙箱运行 Codex Agent。

添加 --port <port> 以启用 Phoenix Web 仪表板。

验证

让用户在 Linear 中将一个测试工单推送到 Todo。观察第一个工作进程是否认领该工单。如果失败，请运行以下检查清单：

• 运行 Symphony 的 Shell 中是否有 LINEAR_API_KEY？
• codex 是否已通过身份验证？
• gh auth status 是否通过？
• 是否可以通过非交互方式使用仓库克隆 URL？
• .agents/skills/ 和 WORKFLOW.md 是否已推送到远程仓库？
• 是否已添加自定义 Linear 状态（Rework、Human Review、Merging）？

设置完成后开始使用

Symphony 运行后，帮助用户开始处理他们的首批工作流：

将功能拆分为工单

用户有一个大型功能构想。使用 Linear MCP 将其拆分为工单。对于每个工单：

• 标题和描述应清晰，并包含验收标准
• 在顺序重要时设置阻塞关系
• 将工单分配到 Symphony 项目，以便 Agent 可以领取
• 从 Todo 中没有阻塞项的工单开始

首次运行

将几个工单推送到 Todo，然后观察运行情况。向用户说明预期情况：

• 空闲的 Agent 会在几秒内认领工单
• 每个 Agent 都会在实施前以 Linear 评论的形式编写计划
• GitHub 上会出现带有 symphony 标签的 PR
• 随着 Agent 推动工单流转，Linear 看板也会更新

随时调整

WORKFLOW.md 会在约 1 秒内热重载，无需重启。常见调整项：

• agent.max_concurrent_agents——根据 API 限制或仓库复杂度增加或减少并发量
• agent.max_turns——复杂工单可调高此值，若要限制令牌开销则可调低
• polling.interval_ms——Symphony 检查新工单或变更工单的频率