orchestral-media/orchestral

Orchestral

License: Apache-2.0

一个用于媒体生成的 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 传递性地获得它，也可以直接安装它来自己构建或预检一个 plan）、@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 (input: I, ctx: DispatchContext): Promise> {
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,
// AI SDK 不报告图像成本；null = 未知，永远不是 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 证言、讲解短片、产品照片包、
字幕 → 重新渲染的图像编辑回退，以及 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 自带的那一个） |

Agent 模式增加了第四个接缝，AgentRunImpl，它驱动内部的 LLM
工具循环。它处于 @alpha 阶段，并且和
ModelCapability.call 一样不附带任何实现：选择 agent 框架是宿主的决定。
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 | 以数据形式编写的流水线：模型填充的 wire schema、validatePlan（在 DAG 中任何部分消耗资源之前先找出所有问题）、planToMeta（将 DAG 作为普通 meta 执行）和 preflightPlan（每个步骤都已路由，但不运行任何内容）。仅依赖 core，别无其他。 |
| @orchestral/discovery | 可选。LLM 发现层：BM25 PatternSearchIndex、find_pattern 工具处理器，以及 createPatternSearch——core 的 PatternSearch 接缝的现成实现，@orchestral/runtime 将其作为 patternSearch 接收。Core 保留输入契约；此包负责搜索，且没有任何东西依赖它。 |
| @orchestral/agent | 可选。编排器 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 agent 工具。一个独立版本线上的叶子包——dsh 是开发预览版，因此破坏性变更止步于桥接层。 |

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

诚实的局限性

这是 0.x 版本。每个包的 README 都陈述了自身的边界，而非隐藏它们：

- Agent 恢复是有损的。 转录存储的是步骤投影，而非原始 provider 消息：tool_use 配对和推理块在恢复时丢失——
runtime § Resume fidelity。
- 没有持久化队列。 InlineRuntime 在调用者的 tick 中运行作业，而
abandonOrphanedJobs() 将死进程遗留的作业标记为 stale；
ctx.askUser 仅驻留在内存中——
runtime § Runtime semantics worth knowing。
- 可交付元数据需要你提供多媒体后端。 六个
MetaCommonDeps 操作（ffmpeg 形态：拼接、字幕、背景
音频……）已定义但未在此实现——
patterns § Deliverable metas。
- 仅附带一个回退方案，且采用它是可选的。 image-to-image → caption
→ 重新渲染是第一方目录中唯一的 Alternative，而
InlineRuntime 默认以列出适用路径的方式失败，而非通过它们重定向
（alternatives: 'auto' 开启重定向）——
runtime § Alternative fallback is opt-in，
core § Semantic fallback。

关于该库有意省略某些内容的理由，请参见 DESIGN.md。

版本管理

0.x：次要版本可能包含破坏性变更，补丁版本绝不会。@orchestral/ 包共享同一条版本线并一起发布——请固定你测试过的确切版本集。@orchestral/dsh-plugin 针对其开发预览版宿主独立版本化。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 模型 → ModelCapability）
packages/orchestral-dsh-plugin/  @orchestral/dsh-plugin（独立版本线）
examples/                        可运行宿主，每个约 50 行
scripts/smoke-dist.mjs           端到端执行构建后的 dist 包

开发
sh
pnpm install
pnpm build        # tsdown 打包 + tsc 声明 + api-extractor 汇总
pnpm test         # vitest，所有包和示例
pnpm typecheck
pnpm api:check    # 公共 .d.ts 接口与已提交的 etc/*.api.md 报告对比
pnpm smoke:dist   # 构建，然后端到端运行已发布的 dist 包
pnpm docs:catalog # 从构建后的 dist 重新生成模式目录表

pnpm api:check 失败意味着公共 API 发生了变化。请审查差异，运行
pnpm api:update，并将更新后的报告与变更一起提交。

许可证

Apache-2.0 — 参见 LICENSE 和 NOTICE。

@orchestral/patterns 包含源自第三方 MIT 项目的提示文本；
受影响的常量和上游许可证文本列在
packages/orchestral-patterns/CREDITS.md 中。

贡献与安全

参见 CONTRIBUTING.md。如需报告漏洞，请使用
SECURITY.md 中的私密渠道，而非公开 issue。