媒体编排层 orchestral-media/orchestral

Orchestral

面向媒体生成的 TypeScript 编排层——文生图、图生视频、文本转语音、语音识别——为本地优先、BYOK 应用打造：能力路由、按需开启的语义回退，以及资源句柄协议。

你只需描述某个步骤需要什么（text-to-image、image-to-video、automatic-speech-recognition……），不用指定调用哪个模型。Orchestral 把这项能力路由到你提供的模型，在路由器内部重试，还知道当某项能力没有模型可用时，可以降级走哪些语义等价路径（默认只在失败时报告；自动改道需要手动开启），并在步骤之间以不透明句柄的形式传递生成的媒体，由宿主解析。它不附带任何服务商 SDK，也不带 API 密钥——调用模型就是你写的一段约 15 行的适配器，架在你已经在用的任意 SDK 之上。一切都在你的进程里运行，没有托管控制平面。

与 AI SDK / LangChain 的关系

它们处在不同层，Orchestral 期望你继续使用另外两者：

- 服务商 SDK（Vercel AI SDK、官方厂商 SDK）负责单次模型调用——认证、请求结构、流式传输、传输层重试。你的 Orchestral call 适配器通常就是架在其中之一上的十几行代码；这里的示例用的是 AI SDK 的 generateImage。
- 智能体框架（LangChain / LangGraph、AI SDK 自带的工具循环）负责通用工具循环——规划、记忆、步骤图。Orchestral 的智能体模式把循环交给由你注入的那一个。
- Orchestral 负责两者都没覆盖的媒体部分：路由能力而不是模型 id，声明语义等价的回退路径，以备没有模型提供该能力时使用，并在步骤之间以句柄而非原始 id 传递生成的资源。

快速开始

npm install @orchestral/core @orchestral/runtime @orchestral/patterns zod

上面还有三个可选包：@orchestral/plan（把流水线写成数据——schema、校验、解释器和预检；随 catalog 传递依赖即可获得，也可以直接安装，自己构建或预检计划）、@orchestral/discovery（find_pattern 工具背后的 BM25 搜索——运行时向宿主请求检索，而不是依赖某个具体实现，所以装上它就能给智能体循环一个 find_pattern 工具）以及 @orchestral/agent（编排器智能体模式）。
它们都不引入服务商 SDK。第四个包 @orchestral/adapters-ai-sdk 是唯一引入的：它把 Vercel AI SDK 的模型实例包装成现成的 ModelCapability，这样已经在用 AI SDK 的宿主就不用再写调用适配器。它是叶子节点——@orchestral/ 里没有任何东西依赖它。

zod v4（>=4.3 <5）是 peer 依赖：模式的输入/输出 schema 都是 zod 公共 API 上的 schema，所以你的应用和 Orchestral 必须共用一个 zod 实例。

这个仓库里有六个可直接运行的宿主：

- examples/atomic-hello-world — 一次原子 text-to-image 派发，整个服务商桥接都在 src/ai-sdk-wiring.ts 里。
- examples/agent-hello-world — 一次 agent 类派发：一个 LLM 工具循环，负责挑选并运行 pattern。
- examples/consented-fallback — 一个目录里没有 image-to-image 模型：路由器解释这次未命中，运行时拒绝执行并指出声明的回退方案以及会失去什么，一个 meta 在采用前先询问用户，而 alternatives: 'auto' 则按请求采用它。在 mock 模型上离线运行。
- examples/incremental-rerun — 一个三步 meta，改动一个输入后重新提交：未改动的步骤按原来的子任务 id 从 JobStore 返回，只有改动的那一步及其下游重新运行。Mock 模型，无需 key。
- examples/plan-short-clip — 同样的三步流水线，用 JSON 而不是 compose() 编写，由 planToMeta 作为普通 meta 加载。插入一个步骤后重新提交，未受影响的步骤仍从 JobStore 返回：plan 按步骤名而不是位置来索引各行。Mock 模型，无需 key。
- examples/long-form-video — 参考实现：小说 → 多事件视频流水线（五个规划 meta 和一个导演 agent），作为源码留在示例里而不是作为 API 发布，注册在完整目录旁边。它的 README 说明了成本概况以及它期望的 concat_videos 宿主工具。无需 key：测试在 mock 上运行。

pnpm install
pnpm --filter atomic-hello-world start # needs OPENAI_API_KEY
pnpm --filter atomic-hello-world test # no key: same wiring, mock model
pnpm --filter consented-fallback start # no key: the fallback narrative on mocks
pnpm --filter incremental-rerun start # no key: content-addressed re-run, mock models
pnpm --filter plan-short-clip start # no key: the same pipeline as data, re-run after an edit
pnpm --filter long-form-video start # no key: registers the long-form catalog and prints it

最小示例

注册表、模型桥接、路由器、运行时、一次派发 —— 这就是全部接口：

import {
PatternRegistry,
type DispatchContext,
type DispatchResult,
type ModelCapability,
} from '@orchestral/core'
import { InMemoryJobStore } from '@orchestral/core/memory'
import { createDefaultCapabilityRouter } from '@orchestral/core/routing'
import { InlineRuntime } from '@orchestral/runtime'
import { createTextToImagePattern } from '@orchestral/patterns'
import { generateImage } from 'ai'
import { openai } from '@ai-sdk/openai'

const registry = new PatternRegistry()
registry.register(createTextToImagePattern())
// 你写的接缝：把服务商 SDK 包进 ModelCapability 信封。

const model: ModelCapability = {
capabilities: ['text-to-image'],
provider: 'openai',
modelId: 'gpt-image-1',
inputs: ['text'],
outputs: ['image'],
tags: [],
source: 'user',
async call(input: I, ctx: DispatchContext): Promise<DispatchResult<O>> {
const startedAt = Date.now()
const { images } = await generateImage({
model: openai.image('gpt-image-1'),
prompt: (input as { prompt: string }).prompt,
abortSignal: ctx.signal,
})
const assets = images.map((img, i) => ({
assetId: img-${i},
modality: 'image' as const,
url: data:${img.mediaType ?? 'image/png'};base64,${img.base64},
}))
const output = {
modality: 'image' as const,
assets,
// the AI SDK does not report image cost; null = unknown, never 0
cost: null,
latencyMs: Date.now() - startedAt,
model: 'openai:gpt-image-1',
provider: 'openai',
}
return { output: output as O }
},
}

const runtime = new InlineRuntime({
store: new InMemoryJobStore(),
registry,
router: createDefaultCapabilityRouter({
getModels: (cap) => (cap === 'text-to-image' ? [model] : []),
}),
})

const job = await runtime.submitJob({
patternId: 'text-to-image',
input: { prompt: 'a watercolour fox in a misty forest' },
})
console.log(job.status, job.output) // 'done' { modality: 'image', assets: [...] }

或者，用 AI SDK 的话，可以省掉手写适配器： @orchestral/adapters-ai-sdk 里的
fromImageModel(openai.image('gpt-image-1')) 会返回同一个信封。

同一套接线的带注释版本在 packages/orchestral-core/README.md。

开箱内容

@orchestral/patterns 提供 19 个模式：10 个原子模式（每个能力一个—— text-to-image、image-to-video、text-to-speech、 automatic-speech-recognition、……），以及 9 个元流水线，提示词都内联在里面（best-of-N 图像筛选、分镜、脚本转视频、产品广告、UGC 证言、讲解短片、产品图包、caption → 重渲染的图像编辑兜底，还有 meta_plan —— 把 LLM 写好的步骤列表当成一个任务跑的一次性模式）。智能体模式（编排器）放在可选的 @orchestral/agent 包里。长篇小说的视频化流水线两边都不在：它保持可运行，放在 examples/long-form-video。

完整表格 —— 类型、输入槽、输出，以及每个模式期望你提供的主机操作 ——由构建后的包生成：模式目录。

三个接缝

主机要接入 Orchestral，只需满足三个注入点。两个是你替换的实现；第三个是调用适配器：

| 接缝 | 它决定什么 | 自带什么 |
| JobStore | 任务行存放的位置 | 开发/测试用 InMemoryJobStore（来自 @orchestral/core/memory）；生产环境请自备持久化实现（例如基于 SQLite） |
| CapabilityRouter | 由哪个模型来响应某项能力 | createDefaultCapabilityRouter（来自 @orchestral/core/routing）；你注入 getModels 和可选的启用开关 |
| ModelCapability.call | 真正调用服务商 | 无需提供——这是你基于自己的 SDK 写的约 15 行适配层（如果用 Vercel AI SDK，则用 @orchestral/adapters-ai-sdk 自带的那份） |

智能体模式会引入第四个接缝 AgentRunImpl，它驱动内层的 LLM 工具循环。它处于 @alpha 阶段，而且和 ModelCapability.call 一样不附带任何实现：选哪个智能体框架由宿主决定。examples/agent-hello-world 在 AI SDK 的工具循环之上接了约 150 行——复制它，换成你已经在跑的循环即可。

包

| 包 | 是什么 |
| @orchestral/core | 词汇与契约：Pattern / ModelCapability / Alternative、Job / JobStore / Runtime，以及模式注册表。不含执行引擎，不含服务商 SDK。现成实现放在下一层，各自独立入口：@orchestral/core/memory（三个 InMemory 存储）和 @orchestral/core/routing（默认能力路由器）。 |
| @orchestral/patterns | 官方模式目录：每项能力对应一个原子模式，外加元流水线（分镜、脚本转视频、best-of-N 选择、短视频交付物……），提示词内联其中。 |
| @orchestral/runtime | InlineRuntime，core 的 Runtime 的进程内参考实现：提交任务、经路由器分发、处理重试、可选的跨模式回退与幂等。没有持久化队列——每个任务的生命周期由宿主掌控。 |
| @orchestral/plan | 以数据形式编写的流水线：模型填写的传输格式 schema、validatePlan（在 DAG 花掉任何成本之前先找出所有问题）、planToMeta（把 DAG 当作普通 meta 执行）和 preflightPlan（每个步骤都完成路由，但不实际运行）。只依赖 core，别无其他。 |
| @orchestral/discovery | 可选。LLM 发现层：BM25 PatternSearchIndex、find_pattern 工具处理器，以及 createPatternSearch——core 的 PatternSearch 接缝的现成实现，@orchestral/runtime 以 patternSearch 接收它。core 保留输入契约；搜索由这个包负责，且没有任何东西依赖它。 |
| @orchestral/agent | 可选。编排器智能体模式。只是一份声明——运行它的工具循环是你注入的 AgentRunImpl。 |
| @orchestral/adapters-ai-sdk | 可选。基于 Vercel AI SDK 的模型实例，提供现成的 ModelCapability 封装——fromLanguageModel / fromVisionModel / fromImageModel / fromSpeechModel / fromTranscriptionModel，覆盖 text-generation、image-to-text、text-to-image、text-to-speech 和 automatic-speech-recognition——适合已经在用 AI SDK 的宿主。叶子包：它依赖 core 和 ai，没有别的包依赖它。 |
| @orchestral/dsh-plugin | 实验性。一个 deepseek-harness 插件，把已注册的 pattern 暴露为 dsh 智能体工具。叶子包，走自己的版本线——dsh 还是 dev preview，出问题也只影响这座桥。 |

所有包均为 Apache-2.0。@orchestral/ 系列包在同一条版本线上一起发布；@orchestral/dsh-plugin 独立版本化。

坦率的局限

这还是 0.x。每个包的 README 都会写明自己的边界，而不是藏着掖着：

- 智能体恢复是有损的。 转录记录存的是步骤投影，不是服务商原始消息：恢复时 tool_use 配对和推理块都会丢失—— runtime § Resume fidelity。
- 没有持久化队列。 InlineRuntime 在调用方的 tick 里跑任务，abandonOrphanedJobs() 把死进程留下的任务标为 stale；ctx.askUser 只停在内存里—— runtime § Runtime semantics worth knowing。
- 交付物 meta 需要你自己提供多媒体后端。 六个 MetaCommonDeps 操作（ffmpeg 形态：拼接、字幕、背景音……）只定义了规格，这里没有实现—— patterns § Deliverable metas。
- 只附带一个 fallback，而且要不要用由你决定。 image-to-image → caption → 重新渲染是第一方目录里唯一的 Alternative，InlineRuntime 默认直接失败并列出可用路径，而不是走这些路径重定向（alternatives: 'auto' 才会开启重定向）—— runtime § Alternative fallback is opt-in， core § Semantic fallback。

想了解这个库为什么有意省略某些东西，见 DESIGN.md。

版本策略

0.x：minor 版本可能包含破坏性变更，patch 版本绝不包含。@orchestral/ 系列包共用一条版本线，一起发布——请锁定你测试过的确切版本组合。@orchestral/dsh-plugin 相对它的 dev-preview 宿主独立版本化。1.0 线将严格遵循 semver。

仓库结构

packages/orchestral-core/ @orchestral/core
packages/orchestral-discovery/ @orchestral/discovery
packages/orchestral-patterns/ @orchestral/patterns
packages/orchestral-runtime/ @orchestral/runtime
packages/orchestral-plan/ @orchestral/plan
packages/orchestral-agent/ @orchestral/agent
packages/orchestral-adapters-ai-sdk/ @orchestral/adapters-ai-sdk（叶子包：AI SDK model → ModelCapability） packages/orchestral-dsh-plugin/ @orchestral/dsh-plugin（独立版本线） examples/ 可运行的宿主，每个约 50 行 scripts/smoke-dist.mjs 端到端执行构建产物 dist bundle

开发 sh
pnpm install
pnpm build # tsdown bundle + tsc declarations + api-extractor rollup
pnpm test # vitest, all packages and examples
pnpm typecheck
pnpm api:check # public .d.ts surface vs the committed etc/*.api.md report
pnpm smoke:dist # build, then run the published dist bundles end to end
pnpm docs:catalog # regenerate the pattern catalog table from the built dist

pnpm api:check 失败，说明公开 API 变了。先看 diff，再跑 pnpm api:update，然后把更新后的报告和这次改动一起提交。

协议

Apache-2.0 —— 见 LICENSE 和 NOTICE。

@orchestral/patterns 里有部分提示词文本来自第三方 MIT 项目；受影响的常量和上游协议文本都列在 packages/orchestral-patterns/CREDITS.md。

贡献与安全

见 CONTRIBUTING.md。发现漏洞，请走 SECURITY.md 里的私密渠道，不要开公开 issue。