Orchestra

orchestra 是对 docs/SPEC.md 中 Orchestra 规范的 Go 实现。 Orchestra 是一个受 Symphony 启发、但并非其逐字移植的系统: 它以代码平台 webhook 事件为主要入口，将 issue、pull/merge request、push、tag、release 等外部信号归一化为可调度工作，并以 Codex 作为统一的 agent 执行基础设施。 编码任务是当前最重要的使用场景，但同一套运行时也面向 CI/CD 与仓库自动化。

当前实现已经转向 Kubernetes 控制面模型: 由 controller manager 监听 Workflow、WorkflowTemplate、Tracker、Agent 等 CRD，并以 Pod 作为 Codex agent 的执行载体。

当前架构

• serve 启动 Kubernetes controller manager，并暴露共享 HTTP ingress 用于 webhook 与 API 访问
• Tracker 负责外部事件的连接、认证、归一化，以及必要时的轮询补偿
• WorkflowTemplate 承接可复用的工作流模板，并支持 webhook 命中后实例化
• Workflow CR 承接运行配置与工作流实例状态，而不仅限于单一 issue 任务
• Workflow.status 暴露运行中、重试中与最近错误的运行摘要
• 运行结果可沉淀为 Proof of Work，例如状态变迁、日志、agent 事件与工作区产物
• worker Pod 通过隐藏命令 run-once 执行单次 agent 尝试
• 仍保留本地 validate-config / print-config，用于调试 legacy YAML 配置

运行要求

• Go 1.25+
• Kubernetes 集群访问权限
• 可访问的代码平台 HTTP API / webhook 来源，当前主要围绕 issue 流程，也支持扩展到 GitHub / GitLab 的 PR/MR、push、tag、release 等事件
• worker 镜像内可执行 orchestra 与 codex app-server
• 如果继续使用 SSH 模式:
  • controller Pod 所在环境可通过 ssh 连接目标 host
  • 远端 host 具备 bash、codex app-server 及所需认证环境

Kubernetes 快速开始

1. 安装默认部署清单:

kubectl apply -k config/default

2. 创建 tracker token secret:

kubectl create namespace orchestra-system
kubectl -n orchestra-system create secret generic github-token --from-literal=token="$GITHUB_TOKEN"

3. 参考 config/samples/orchestra_v1alpha1_workflow.yaml 创建 Workflow:

kubectl apply -f config/samples/orchestra_v1alpha1_workflow.yaml

4. 如果你在本地调试 manager，也可以直接启动:

go run ./cmd/orchestra serve --namespace orchestra-system

serve 在启动 manager 之前会先同步二进制内置的 CRD 清单:

• 集群里不存在时自动安装
• 已存在时按仓库中的 config/crd/bases/*.yaml 自动更新

因此运行账号需要具备 CustomResourceDefinition 的读写权限。

常用启动参数:

go run ./cmd/orchestra serve \
  --namespace orchestra-system \
  --leader-elect=true \
  --port 8080 \
  --metrics-bind-address :8081

serve 默认在 :8080 暴露共享 HTTP 入口:

• /api/v1/* API
• /api/v1/webhooks/:provider webhook 入口，当前支持 github / gitlab
• /healthz
• /readyz

当前内置的资源型 API 包括:

• /api/v1/workflows
• /api/v1/workflowtemplates
• /api/v1/trackers
• /api/v1/namespaces
• /api/v1/secrets
• /api/v1/configmaps

其中:

• workflows、workflowtemplates、trackers、secrets、configmaps 提供列表 / 查询 / 创建 / 替换更新 / merge patch / 删除
• namespaces 提供集群级列表 / 查询 / 创建 / 替换更新 / merge patch / 删除
• secrets 与 configmaps 的列表接口支持 ?namespace=<ns> 过滤

指标端点默认单独监听 :8081。

如果是在集群外调试，可显式指定 kubeconfig:

go run ./cmd/orchestra serve --kubeconfig ~/.kube/config

仓库中的 Kubernetes 落地清单位于:

• config/default/kustomization.yaml
• config/manager/deployment.yaml
• config/manager/namespace.yaml
• config/rbac/service_account.yaml
• config/rbac/role.yaml
• config/rbac/role_binding.yaml

Workflow 配置模型

Workflow.spec 目前覆盖以下主要配置块:

• tracker
• polling
• workspace
• worker
• hooks
• agent
• codex
• server
• prompt

当前 tracker 已统一为 kind: http 的通用 HTTP / webhook 模型。 legacy YAML 中通过 tracker.http.auth.value 配置认证；CRD 中通过 tracker.spec.http.auth.secretFrom 引用 Secret 注入。

worker.mode 支持:

• local: 直接在 controller 所在环境启动执行
• ssh: 按 worker.ssh_hosts 选择远端 host
• kubernetes: 创建 worker Pod 执行单次任务

Kubernetes 模式下，常用字段位于 worker.kubernetes:

• namespace
• image
• serviceAccountName
• imagePullPolicy
• podLabels
• podAnnotations

Tracker webhook 与 WorkflowTemplate

Tracker.spec 现在同时覆盖 webhook 驱动入口与主动轮询补偿两类入口。 产品设计上以 webhook 为主，轮询主要用于 provider 能力不足、刷新补偿或回填。

当前最完整的默认流程仍然是 issue 触发编码任务，但统一事件模型也面向:

• pull / merge request 跟进
• push / tag 触发的仓库自动化
• release 流程与其他 CI/CD 风格任务

主要字段包括:

• kind: http: 通用 HTTP tracker
• http.endpoint / http.headers / http.auth: HTTP 连接和认证
• issue.path / issue.method / issue.query / issue.headers: issue 类入口的拉取请求定义
• issue.fields.*: 从 HTTP JSON 响应提取统一 issue 字段的路径定义
• issue.activeStates / issue.terminalStates: issue 类调度状态判定
• polling.intervalMilliseconds: 主动抓取或补偿刷新周期
• webhook.enabled: 是否启用 webhook 匹配
• webhook.provider: webhook 来源提供方，当前支持 github / gitlab
• webhook.port: 记录期望的 webhook 端口配置
• webhook.secretFrom: 引用 webhook 验签 Secret
• webhook.resourceTypes / webhook.actions: 允许的统一资源事件和动作
• webhook.sources: 允许的来源标识，如 owner/repo 或 group/project

WorkflowTemplate 用于声明 webhook 命中后的实例模板:

• spec: 与 Workflow.spec 结构一致，定义模板的 trackers 与 dag

Webhook 处理链路如下:

1. 外部系统向 /api/v1/webhooks/:provider 发送 GitHub 或 GitLab 事件
2. Tracker 根据 provider、签名、source、resourceType、action 完成匹配
3. 命中的 WorkflowTemplate 被实例化为新的 Workflow
4. 新实例会进入现有 Workflow reconciler 的调度、重试与状态收敛流程

Legacy YAML 调试

仓库仍保留 legacy YAML 示例，位于:

• config/config.yaml
• config/github.yaml
• config/gitlab.yaml

这些示例现在都使用统一的 HTTP tracker 结构，可继续用来验证配置转换逻辑:

go run ./cmd/orchestra validate-config --config ./config/config.yaml
go run ./cmd/orchestra print-config --config ./config/config.yaml

日志与状态

orchestra 使用 github.com/charmbracelet/log 输出结构化日志。 可通过 --log-level 和 --log-format 控制输出格式。

Workflow.status 当前会暴露:

• conditions
• observedGeneration
• runningCount
• retryingCount
• running[]
• retrying[]
• lastConfigError
• lastTrackerError

常用验证

go test ./...

Controller 集成测试基于 envtest，首次运行会自动下载 apiserver/etcd 测试二进制到本机的 envtest 缓存目录。

说明

• docs/SPEC.md 是规范来源
• config/crd/bases/orchestra.zhubby.dev_{trackers,agents,workflows,workflowtemplates}.yaml 是当前 CRD 契约
• config/config.yaml 及其同级示例主要用于 legacy 配置调试
• 当前设计目标是 webhook-first 的通用 Codex agent 基础设施，而非 Linear-only 或 polling-first 的 issue scheduler
• CLI 基于 Cobra；Kubernetes 运行时基于 controller-runtime