首次运行 Symphony

文档状态: draft
文档 Owner: DOC
事实源: canonical-docs
更新: 2026/10/16

这条路径使用官方 Elixir 参考实现 + Linear，从准备工作流到观察一个小任务。已有 AutoDev 自用实例的使用者直接进入首次任务，无需再启动服务或先阅读 Plane 工程合同。

适用版本与核对范围

命令和配置依据官方 be10a1b79df723d6d7612b5651c8522704dafb2e 的 Elixir README、mise.toml和 CLI。本文完成源码核对，未在目标环境安装、启动或跑通真实任务；不宣称团队部署正在使用此版本。上游将其标为工程预览 / 评估用原型。

1. 准备一个明确范围

准备已经授权的 Linear 项目、一个可供小任务修改的仓库，以及已有有效来源凭据。首次示例只生成文件，不要求提交、推送、合并或发布。

前提	要确认什么
执行环境	以下按 POSIX shell 编写，未核对 Windows 原生运行。安装 Git、mise；固定仓库要求 Erlang 28 与 Elixir 1.19.5-otp-28
Codex	`codex` 在服务进程 PATH 中，支持 app-server，已经具备有效认证
Linear	既有凭据能读取所选项目；示例状态为 `Todo`、`In Progress`、`Done`、`Canceled`、`Duplicate`，名称不同须修改 YAML
目标仓库	宿主可以 clone；已有仓库指令与工作授权
实例范围	没有另一服务同时领取该项目同一范围，避免跨实例重复执行

服务从宿主环境读取 LINEAR_API_KEY，不要把真实 token 写入 WORKFLOW、任务描述或站点，也不要打印凭据值。本文不创建账号、凭据或权限，使用环境已有批准的认证和网络配置。

2. 获取固定实现并准备二进制

在独立目录操作官方参考实现；以下不是本知识库仓库的构建命令：

git clone https://github.com/openai/symphony.git symphony-reference
cd symphony-reference
git checkout --detach be10a1b79df723d6d7612b5651c8522704dafb2e
cd elixir
mise trust
mise install
mise exec -- elixir --version
mise exec -- mix setup
mise exec -- mix build

预期结果是依赖和构建完成，生成 ./bin/symphony；版本输出与仓库要求一致。实际输出随宿主和依赖变化，本文不提供虚构成功日志。mise trust 意味着信任此 checkout 的工具配置，应先读取再执行。

3. 写一个最小 WORKFLOW

保存为当前 elixir 目录内的 FIRST-RUN-WORKFLOW.md。先把 YOUR_PROJECT_SLUG 替换为 Linear 项目 URL 中的 slug，它不是项目显示名或凭空生成的 ID；再在服务环境设置 SOURCE_REPO_URL 为已授权目标仓库的 clone URL。

---
tracker:
  kind: linear
  provider:
    project_slug: YOUR_PROJECT_SLUG
    api_key: $LINEAR_API_KEY
  active_states: [Todo, In Progress]
  terminal_states: [Done, Canceled, Duplicate]
polling:
  interval_ms: 10000
workspace:
  root: ~/code/symphony-first-run-workspaces
hooks:
  after_create: |
    git clone "$SOURCE_REPO_URL" .
agent:
  max_concurrent_agents: 1
  max_turns: 1
codex:
  command: codex app-server
---

Process the authorized Linear issue {{ issue.identifier }}.
Title: {{ issue.title }}
Description: {{ issue.description }}

Read the repository instructions before acting. Work only in this task workspace.
Create or verify SYMPHONY-FIRST-RUN.md as requested by this first-run exercise.
Do not commit, push, merge, publish, change credentials, or change tracker state.
If the file already satisfies the issue, verify it without appending duplicates.
Report the file path, verification result, and blockers. Do not claim business acceptance.

例如，在 shell 中设置仓库地址，不在 URL 中嵌入 token：

export SOURCE_REPO_URL='https://github.com/YOUR_ORG/YOUR_SANDBOX_REPO.git'

单并发、单次一轮是本文的演示值。max_turns: 1 不会永久停止任务：来源仍活跃时，调度器可以再安排后续会话。 本例不自动改状态，由操作者核对成果后按第 6 步结束任务。审批与 sandbox 保持该版本默认值；遇输入或审批请求应处理阻塞，不为跑通示例降低策略。

示例未设置 required_labels，所选项目内所有符合活跃状态等条件的任务都可能成为候选。不要指向已有大量待执行任务的共享项目。进一步说明见配置与扩展边界。

4. 准备并启动首次任务

在指定 Linear 项目内先查重，再准备小任务：

标题：验证 Symphony 首次工作空间执行
目标：在目标仓库的任务工作空间创建 SYMPHONY-FIRST-RUN.md。
范围：只修改该文件，不改应用、依赖或配置，不提交、不推送、不发布。
验收：文件包含当前 issue 标识和一段“这是首次执行验证”的说明；已有合格文件则只核对。
交付：报告目录、文件路径与核对结果；不自动迁移原生任务状态。

确认范围后，把它置于示例配置的活跃状态 Todo。这是独立参考实例的显式配置；AutoDev 自用实例的 Backlog 准入另见首次任务，不能套用本例绕过团队规则。

从官方参考实现的 elixir 目录启动：

mise exec -- ./bin/symphony \
  --i-understand-that-this-will-be-running-without-the-usual-guardrails \
  --port 4000 \
  ./FIRST-RUN-WORKFLOW.md

长参数由此版本 CLI 强制要求，表示接受其工程预览运行提示，不是关闭额外安全策略的建议。README 简短启动例未列此参数，这里按 CLI 检查补齐。--port 4000 开启该版本可选观测面板与 JSON API；端口占用时选择可用端口并同步下面的读取地址。

5. 观察三个信号

阶段	预期可观察结果	判断边界
服务启动	没有启动退出错误，面板或 API 可访问	不证明任务已派发
对应任务派发	状态 / 日志出现相同 issue 标识、worker / 会话与目录	空目录不证明 Agent 完成
Agent 执行	任务目录存在合格文件，报告与内容相符	自述不替代文件核对或验收

只读查询状态：

curl --fail http://127.0.0.1:4000/api/v1/state
curl --fail http://127.0.0.1:4000/api/v1/YOUR-ISSUE-IDENTIFIER

第二条先替换真实任务标识；面板在 http://127.0.0.1:4000/。状态可包含运行、重试、blocked 和会话信息；一次采样没有 running 不表示从未执行。未知任务返回 404 时先核对实例、标识、最近记录与日志，不创建重复任务。接口是执行观测面，不用于创建业务任务。

6. 核对结果并结束本次演示

读取状态报告的目录，核对文件内容、范围与原生 issue 标识，保存所需证据。达到本任务的验收条件后，由有权操作者把原生任务移入配置终态，再确认对应执行停止。终态会触发目录清理，所需成果和记录须提前保存。 未达到验收时，先按项目方式移出活跃范围并确认停止，再处理缺口，避免持续重跑。

最后按宿主进程管理方式停止独立演示服务。一次验证通过，只说明这个版本、环境、来源和任务路径完成验证，不能证明生产可用、所有来源已接入或代码已发布。

常见错误

现象	先查什么
工程预览确认横幅后退出	是否包含该版本要求的长确认参数
`Workflow file not found` 或 YAML 解析错误	当前目录、文件绝对路径、映射结构与缩进
tracker token / project scope 错误	服务环境变量、项目 slug 与既有凭据权限；不要打印 token
无候选或不派发	状态拼写、scope、assignee / blocker、标签、认领与容量
clone 失败	服务是否继承 `SOURCE_REPO_URL`，宿主 Git 认证是否有效
Agent 无法启动或 blocked	Codex PATH、认证、app-server 版本及输入 / 审批请求
一轮后继续运行	来源仍活跃；`max_turns` 不限制整项任务的总会话数
文件消失	是否因来源进入终态触发了目录清理

继续阅读：核心执行循环 · 任务跟进 · 失败与恢复。

1. 准备一个明确范围​

2. 获取固定实现并准备二进制​

3. 写一个最小 WORKFLOW​

4. 准备并启动首次任务​

5. 观察三个信号​

6. 核对结果并结束本次演示​

常见错误​