Cherry Studio AI Core (1): Architecture Shift to AI SDK and Plugins

Models layer

The models layer does two things: it resolves model IDs (namespaced or plain) and it wraps the resulting model with middlewares when needed. That means the runtime always receives a LanguageModelV2 that is already normalized.

Runtime layer

The runtime layer is the execution boundary. I kept it small on purpose (streamText/generateText/streamObject/generateObject/generateImage), and pushed cross-cutting concerns into plugins so behavior stays predictable.

Plugin layer

Plugins are now the primary extension surface. Logging, tool use, web search transforms, and future agent extensions live here. The hook model makes ordering explicit and cuts down hidden coupling.

Provider system

Providers are centralized in aiCore. The registry and factory isolate provider-specific configuration, so the rest of the pipeline can operate on unified interfaces. This is what makes the runtime reusable and future provider additions less invasive.

models/ (model resolution is not runtime logic)

Models are the compatibility layer. The key decision here: the runtime never resolves providers or model IDs. That logic lives in ModelResolver, which handles both namespaced and traditional model IDs, and only then wraps the model with middlewares.

if (modelId.includes(DEFAULT_SEPARATOR)) {
  model = this.resolveNamespacedModel(modelId)
} else {
  model = this.resolveTraditionalModel(finalProviderId, modelId)
}

if (middlewares && middlewares.length > 0) {
  model = wrapModelWithMiddlewares(model, middlewares)
}

File: packages/aiCore/src/core/models/ModelResolver.ts

Why this split works: adding a provider changes how models are built, not how the runtime behaves.

runtime/ (Executor + PluginEngine, one execution path)

Runtime is where I keep the execution surface stable. It is basically two things:

• RuntimeExecutor: the user-facing API that exposes streamText/generateText/streamObject/generateObject/generateImage.
• PluginEngine: the internal pipeline that runs hooks, resolves the model, transforms params/results, and emits lifecycle events.

The key decision: every call goes through PluginEngine, even when model resolution is needed. The resolver still lives in models/, and it is responsible for returning a LanguageModelV2. PluginEngine just wires it into the execution flow so all calls share the same ordering and context setup.

this.pluginEngine.usePlugins([
  this.createResolveModelPlugin(options?.middlewares),
  this.createConfigureContextPlugin()
])

File: packages/aiCore/src/core/runtime/executor.ts

PluginEngine itself makes the flow explicit:

await this.pluginManager.executeConfigureContext(context)
await this.pluginManager.executeParallel('onRequestStart', context)
const resolved = await this.pluginManager.executeFirst('resolveModel', modelId, context)
const transformedParams = await this.pluginManager.executeSequential('transformParams', params, context)
const result = await executor(resolvedModel, transformedParams)
const transformedResult = await this.pluginManager.executeSequential('transformResult', result, context)
await this.pluginManager.executeParallel('onRequestEnd', context, transformedResult)

File: packages/aiCore/src/core/runtime/pluginEngine.ts

I also like to summarize the hook lifecycle as a simple sequence:

sequenceDiagram
  participant Executor as RuntimeExecutor
  participant Engine as PluginEngine
  participant SDK as AI SDK
  Executor->>Engine: configureContext
  Engine-->>Engine: onRequestStart
  Engine-->>Engine: resolveModel
  Engine-->>Engine: transformParams
  Engine->>SDK: execute(model, params)
  SDK-->>Engine: result/stream
  Engine-->>Engine: transformResult
  Engine-->>Engine: onRequestEnd/onError

This is why runtime stays small but still powerful: it is a thin API layer on top of a deterministic plugin pipeline.

plugins/ (a real hook system, not a bag of helpers)

The plugin system is structured, not ad-hoc. I separated hooks into First / Sequential / Parallel / Stream stages, and enforce pre/normal/post ordering. This made it possible to add tool-use, logging, and web search as plugins without creating hard dependencies.

// pre -> normal -> post
private sortPlugins(plugins: AiPlugin[]): AiPlugin[] { /* ... */ }

async executeFirst(hookName, arg, context) {
  for (const plugin of this.plugins) {
    const result = await hook?.(arg, context)
    if (result != null) return result
  }
  return null
}

File: packages/aiCore/src/core/plugins/manager.ts

The runtime itself only knows how to execute; plugins decide how to transform and observe.

providers/ (registry + aliases + provider-specific quirks)

Providers are centralized in a registry to keep the rest of the system clean. I also added alias support and provider-specific handling (OpenAI chat vs responses, Azure variants) at the registry layer so the rest of the pipeline does not need to know these details.

if (providerId === 'openai') {
  globalRegistryManagement.registerProvider(providerId, provider, aliases)
  const openaiChatProvider = customProvider({ fallbackProvider: { ...provider, languageModel: (id) => provider.chat(id) } })
  globalRegistryManagement.registerProvider(`${providerId}-chat`, openaiChatProvider)
}

File: packages/aiCore/src/core/providers/registry.ts

middleware/ (SDK-level seam, not app-level behavior)

AI SDK already has a middleware concept. I kept it separate from plugins so SDK-level behavior stays distinct from app-level behavior. That prevents plugins from accidentally becoming “SDK middleware by another name.”

File: packages/aiCore/src/core/middleware/manager.ts

options/ (normalize messy provider options in one place)

Provider options are messy by nature. I isolated them and added deep-merge helpers so options can be composed without leaking into runtime. This is where provider-specific flags (like streaming metadata) are normalized.

export function mergeProviderOptions(...optionsMap: Partial<TypedProviderOptions>[]): TypedProviderOptions {
  return optionsMap.reduce((acc, options) => {
    // deep merge
  }, {} as TypedProviderOptions)
}

File: packages/aiCore/src/core/options/factory.ts

How I think about the dependency graph

graph TD
  Options --> Providers
  Providers --> Models
  Middleware --> Models
  Models --> Runtime
  Plugins --> Runtime

Tradeoffs I accepted

• More files and folders up front.
• A clean but strict boundary between middleware and plugins.

The payoff is worth it: each module can evolve without turning runtime into a ball of conditionals.