Symphony-ts

本项目是 OpenAI Symphony 的非官方 TypeScript 实现。

Symphony-ts 将项目工作转化为隔离、自治的实现运行：它从你的任务跟踪工具中读取任务，为每个问题创建一个专用的工作空间，在该边界内运行编码代理，并为操作人员提供清晰的运行时可见性、重试和控制界面。

[!WARNING] Symphony 适用于受信任的环境。

运行 Symphony

要求

• Node.js >= 22
• 包含有效 WORKFLOW.md 文件的仓库
• 任务跟踪工具的凭据，例如 LINEAR_API_KEY
• 支持应用服务器模式的编码代理运行时，例如 codex app-server

安装

npm install -g symphony-ts

验证 CLI 是否可用：

symphony --help

快速入门

1. 前往你希望 Symphony 运行的仓库。
2. 在该仓库中创建 WORKFLOW.md 文件。
3. 导出 LINEAR_API_KEY。
4. 从该仓库根目录启动 Symphony。

cd /path/to/your-repo
export LINEAR_API_KEY=your-linear-token
symphony ./WORKFLOW.md --acknowledge-high-trust-preview --port 4321

如果你未指定路径，Symphony 默认使用 ./WORKFLOW.md：

symphony --acknowledge-high-trust-preview --port 4321

你也可以不进行全局安装而直接运行：

npx symphony-ts ./WORKFLOW.md --acknowledge-high-trust-preview --port 4321

Symphony 不会为你生成 WORKFLOW.md 文件。它期望仓库拥有自己的工作流文件，默认情况下会从当前工作目录读取 ./WORKFLOW.md。

在此仓库中设置并启动 Symphony。

要求：
- 为 Linear 创建或更新 WORKFLOW.md
- 使用环境中的 LINEAR_API_KEY，或明确告诉我缺少哪个变量
- 安装 symphony-ts 并以所需的 --acknowledge-high-trust-preview 标志启动 Symphony
- 如果启动失败，请停止并报告确切的失败步骤和命令

WORKFLOW.md 模板

---
tracker:
  kind: linear
  api_key: $LINEAR_API_KEY
  project_slug: your-linear-project-slug
workspace:
  root: ~/code/symphony-workspaces
codex:
  command: codex app-server
server:
  port: 4321
---

您正在处理 Linear 问题 {{ issue.identifier }}。
实现该任务，验证结果，并在达到所需的交接状态时停止。

这是你开始所需的所有 WORKFLOW.md 示例。将其复制到你的仓库根目录命名为 WORKFLOW.md，然后在启动 Symphony 之前更改以下字段：

• tracker.project_slug
• workspace.root
• codex.command

如果你想使用仪表板，请在工作流中保留 server.port，或者在 CLI 中传递 --port。Web 仪表板现在会以服务器渲染的快照打开，并通过服务器发送事件在浏览器中持续实时更新。

如果你的代理工作流需要访问启动 shell 中的环境变量，可以在 codex.command 中配置 Codex 继承这些变量，例如：

codex:
  command: codex --config shell_environment_policy.inherit=all app-server

如果你的代理在一次运行中必须推送分支、打开 PR 或调用外部 API，还应配置一个明确允许网络访问的运行沙盒策略，而不是依赖于最小化的 workspaceWrite 沙盒对象。

如果某个特定的外部 CLI 仍然无法在其环境中看到所需的凭据，请在启动 Symphony 之前通过环境变量为该工具提供凭据。

有关涵盖所有支持字段、默认值和内联文档的完整参考，请参阅 docs/WORKFLOW.template.md。

你能获得什么

一旦 Symphony 运行起来，它将：

• 定期轮询你的任务跟踪工具以查找符合条件的任务
• 为每个问题创建一个专用的工作空间
• 在该工作空间内运行你的编码代理
• 当设置了 --port 或 server.port 时，暴露本地仪表板和 JSON API
• 保持重试、协调和清理状态对操作人员可见

开发

要开发 Symphony 本身，你需要：

• Node.js >= 22
• pnpm >= 10
• 具备 codex app-server 支持的 Codex CLI

pnpm install
pnpm build
node dist/src/cli/main.js --help   # 验证构建是否成功

运行检查：

pnpm test           # 运行所有测试一次
pnpm test:watch     # 监视模式
pnpm typecheck      # 仅进行 TypeScript 类型检查
pnpm lint           # Biome 代码风格检查
pnpm format         # Biome 自动格式化

从源码运行

如果你正在开发 Symphony 本身，而不是使用已发布的 CLI：

pnpm install
pnpm build
node dist/src/cli/main.js --acknowledge-high-trust-preview

请参阅 docs/DEV_GUIDE.md，其中包含完整的操作指南，包括 Linear 设置、WORKFLOW.md 配置和故障排除。

路线图

如果你希望 Symphony 支持某个特定平台，请提交一个问题告诉我们。

Symphony 的作用

Symphony 是一种长期运行的服务，它：

• 监控你的任务跟踪工具以查找符合条件的任务
• 为每个问题创建确定性的专用工作空间
• 从 WORKFLOW.md 中渲染仓库拥有的工作流提示
• 在隔离的执行环境中运行编码代理
• 处理重试、协调和清理工作
• 暴露结构化日志和面向操作人员的状态界面

在典型的设置中，Symphony 会监视 Linear 看板，为准备就绪的问题分配代理运行，并让代理生成工作证明，例如 CI 状态、评审反馈和拉取请求。人工操作人员可以专注于实际工作，而不必监督每个代理的运行。

团队为何使用它

• 将任务跟踪工具中的问题转化为自治的实现运行
• 按问题隔离代理工作，而不是共享一个可变的目录
• 将工作流策略保留在仓库内部
• 在不丢失可观测性的前提下同时运行多个代理
• 引入更高层次的 AI 辅助工程运营模式

贡献

如果你正在扩展这个 TypeScript 实现，请确保更改与上游产品模型保持一致，具体请参阅 SPEC.upstream.md，并遵循仓库中记录的工作流程，详见 AGENTS.md。

许可证

本仓库采用 Apache-2.0 许可证。有关与上游 OpenAI Symphony 项目及此非官方 TypeScript 实现相关的署名信息，请参阅 NOTICE。

Symphony-ts 快速上手指南

Symphony-ts 是 OpenAI Symphony 的非官方 TypeScript 实现。它能将项目任务（如 Linear Issue）转化为独立的自动化编码运行：为每个问题创建专用工作区，在隔离环境中运行编码代理，并提供可视化的操作面板。

⚠️ 警告：Symphony 仅适用于受信任的开发环境。

1. 环境准备

在开始之前，请确保满足以下系统要求和前置依赖：

• Node.js: 版本 >= 22
• 代码仓库: 包含有效的 WORKFLOW.md 配置文件
• 任务追踪凭证: 例如 LINEAR_API_KEY (需先在 Linear 后台生成)
• 编码代理运行时: 支持 app-server 模式的代理，例如 codex app-server

2. 安装步骤

你可以通过 npm 全局安装，或使用 npx 直接运行。

方式一：全局安装（推荐）

npm install -g symphony-ts

验证安装是否成功：

symphony --help

方式二：临时运行（无需安装）

npx symphony-ts --help

3. 基本使用

第一步：配置工作流文件

在项目根目录下创建名为 WORKFLOW.md 的文件。Symphony 不会自动生成此文件，你需要根据以下模板进行修改：

---
tracker:
  kind: linear
  api_key: $LINEAR_API_KEY
  project_slug: your-linear-project-slug
workspace:
  root: ~/code/symphony-workspaces
codex:
  command: codex app-server
server:
  port: 4321
---

You are working on Linear issue {{ issue.identifier }}.
Implement the task, validate the result, and stop at the required handoff state.

必须修改的字段：

• tracker.project_slug: 你的 Linear 项目标识。
• workspace.root: 代理工作区的存储路径。
• codex.command: 根据你的代理工具调整命令（如需继承环境变量，可配置为 codex --config shell_environment_policy.inherit=all app-server）。

第二步：设置环境变量

导出你的 Linear API 密钥：

export LINEAR_API_KEY=your-linear-token

第三步：启动 Symphony

进入项目根目录并运行以下命令启动服务：

cd /path/to/your-repo
symphony ./WORKFLOW.md --acknowledge-high-trust-preview --port 4321

如果不指定文件路径，默认读取当前目录下的 ./WORKFLOW.md：

symphony --acknowledge-high-trust-preview --port 4321

第四步：查看运行状态

启动成功后：

1. Symphony 将开始轮询你的任务追踪器（如 Linear）。
2. 为符合条件的任务创建独立工作区并运行编码代理。
3. 打开浏览器访问 http://localhost:4321，即可看到实时更新的可视化仪表盘（Dashboard），监控任务执行、重试及清理状态。