Merge pull request #249 from opentiny/server-add-materials

feat(genui-sdk-server): support custom materialsMeta at startup

Author: rhlin

docs/src/components/server/api.md

@@ -20,23 +20,33 @@ interface IStartServerOptions {
   port?: number;
   /** 端口被占用时的最大尝试次数，默认 10 */
   maxAttempts?: number;
+  /**
+   * 启动时固定的物料元数据；传入后用于生成 system prompt。
+   * 不传则按请求 tinygenui.framework 选择内置物料：
+   * - Vue → `@opentiny/genui-sdk-materials-vue-opentiny-vue`
+   * - Angular → `@opentiny/genui-sdk-materials-angular-opentiny-ng`
+   * - 其他 / 未传 framework → 默认 Vue 物料
+   */
+  materialsMeta?: IMaterialsMeta;
 }
 ```
 
 - **详细信息**
 
-创建一个 Express 应用并启用 CORS，自动注册对话路由（`/chat/completions`）。如果指定端口被占用，会自动尝试下一个端口（最多尝试 `maxAttempts` 次）。启动成功后会在控制台输出服务器地址。
+创建一个 Express 应用并启用 CORS，自动注册对话路由（`/chat/completions`）。如果指定端口被占用，会自动尝试下一个端口（最多尝试 `maxAttempts` 次）。启动成功后会在控制台输出服务器地址。物料在启动时通过 `materialsMeta` 固定，请求侧无法切换；未配置时按请求 `framework` 映射内置物料（Vue → OpenTiny Vue，Angular → OpenTiny Angular）。
 
 - **示例**
 
 ```typescript
 import { startServer } from '@opentiny/genui-sdk-server';
+import { materialsMeta } from '@opentiny/genui-sdk-materials-vue-element-plus/meta';
 
 startServer({
   port: 3100,
   baseURL: 'https://api.openai.com/v1',
   apiKey: '',
   maxAttempts: 10,
+  materialsMeta,
 });
 ```
 
@@ -59,25 +69,35 @@ interface IEquipChatCompletionsOptions {
   apiKey: string;
   /** API 基础 URL */
   baseURL: string;
+  /**
+   * 启动时固定的物料元数据；传入后用于生成 system prompt。
+   * 不传则按请求 tinygenui.framework 选择内置物料：
+   * - Vue → `@opentiny/genui-sdk-materials-vue-opentiny-vue`
+   * - Angular → `@opentiny/genui-sdk-materials-angular-opentiny-ng`
+   * - 其他 / 未传 framework → 默认 Vue 物料
+   */
+  materialsMeta?: IMaterialsMeta;
 }
 ```
 
 - **详细信息**
 
-创建一个对话请求的实例，创建请求处理器，并将处理器注册到指定的路由路径（POST 方法）。
+创建一个对话请求的实例，创建请求处理器，并将处理器注册到指定的路由路径（POST 方法）。物料在装备路由时通过 `materialsMeta` 固定；未配置时按请求 `framework` 映射内置物料（Vue → OpenTiny Vue，Angular → OpenTiny Angular）。
 
 - **示例**
 
 ```typescript
 import express from 'express';
 import { equipChatCompletions } from '@opentiny/genui-sdk-server';
+import { materialsMeta } from '@opentiny/genui-sdk-materials-vue-element-plus/meta';
 
 const app = express();
 
 equipChatCompletions(app, {
   route: '/chat/completions',
   apiKey: '',
   baseURL: 'https://api.openai.com/v1',
+  materialsMeta,
 });
 
 app.listen(3000);

docs/src/en/components/server/api.md

@@ -20,23 +20,33 @@ interface IStartServerOptions {
   port?: number;
   /** Max attempts when port is in use, default 10 */
   maxAttempts?: number;
+  /**
+   * Materials metadata fixed at startup for system prompt generation.
+   * If omitted, built-in materials are selected by request tinygenui.framework:
+   * - Vue → `@opentiny/genui-sdk-materials-vue-opentiny-vue`
+   * - Angular → `@opentiny/genui-sdk-materials-angular-opentiny-ng`
+   * - Other / missing framework → Vue materials by default
+   */
+  materialsMeta?: IMaterialsMeta;
 }
 ```
 
 - **Details**
 
-Creates an Express app with CORS enabled and registers the chat route (`/chat/completions`). If the specified port is in use, it automatically tries the next port (up to `maxAttempts` times). On success, the server address is printed to the console.
+Creates an Express app with CORS enabled and registers the chat route (`/chat/completions`). If the specified port is in use, it automatically tries the next port (up to `maxAttempts` times). On success, the server address is printed to the console. Materials are fixed at startup via `materialsMeta` and cannot be switched per request. When omitted, they follow the request `framework` mapping (Vue → OpenTiny Vue, Angular → OpenTiny Angular).
 
 - **Example**
 
 ```typescript
 import { startServer } from '@opentiny/genui-sdk-server';
+import { materialsMeta } from '@opentiny/genui-sdk-materials-vue-element-plus/meta';
 
 startServer({
   port: 3100,
   baseURL: 'https://api.openai.com/v1',
   apiKey: '',
   maxAttempts: 10,
+  materialsMeta,
 });
 ```
 
@@ -59,25 +69,35 @@ interface IEquipChatCompletionsOptions {
   apiKey: string;
   /** API base URL */
   baseURL: string;
+  /**
+   * Materials metadata fixed when equipping the route for system prompt generation.
+   * If omitted, built-in materials are selected by request tinygenui.framework:
+   * - Vue → `@opentiny/genui-sdk-materials-vue-opentiny-vue`
+   * - Angular → `@opentiny/genui-sdk-materials-angular-opentiny-ng`
+   * - Other / missing framework → Vue materials by default
+   */
+  materialsMeta?: IMaterialsMeta;
 }
 ```
 
 - **Details**
 
-Creates a chat completion request instance, builds a request handler, and registers it on the specified route (POST).
+Creates a chat completion request instance, builds a request handler, and registers it on the specified route (POST). Materials are fixed via `materialsMeta` when equipping the route. When omitted, they follow the request `framework` mapping (Vue → OpenTiny Vue, Angular → OpenTiny Angular).
 
 - **Example**
 
 ```typescript
 import express from 'express';
 import { equipChatCompletions } from '@opentiny/genui-sdk-server';
+import { materialsMeta } from '@opentiny/genui-sdk-materials-vue-element-plus/meta';
 
 const app = express();
 
 equipChatCompletions(app, {
   route: '/chat/completions',
   apiKey: '',
   baseURL: 'https://api.openai.com/v1',
+  materialsMeta,
 });
 
 app.listen(3000);

docs/src/en/guide/server-usage.md

@@ -72,12 +72,14 @@ export API_KEY= BASE_URL=https://your-llm-server.com/api && npx genui-sdk-server
 
 ```typescript
 import { startServer } from '@opentiny/genui-sdk-server';
+import { materialsMeta } from '@opentiny/genui-sdk-materials-vue-element-plus/meta';
 
 startServer({
   port: 3100,
   baseURL: 'https://api.openai.com/v1',
   apiKey: '',
   maxAttempts: 10, // Max retries when port is in use
+  materialsMeta,
 });
 ```
 
@@ -86,6 +88,7 @@ startServer({
 ```typescript
 import express from 'express';
 import { equipChatCompletions } from '@opentiny/genui-sdk-server';
+import { materialsMeta } from '@opentiny/genui-sdk-materials-vue-element-plus/meta';
 import cors from 'cors';
 
 const app = express();
@@ -95,6 +98,7 @@ equipChatCompletions(app, {
   route: '/chat/completions',
   apiKey: '',
   baseURL: 'https://api.openai.com/v1',
+  materialsMeta, // If omitted, default materials are selected by request framework (Vue → OpenTiny Vue, Angular → OpenTiny Angular)
 });
 
 app.listen(3000);

docs/src/guide/server-usage.md

@@ -72,12 +72,14 @@ export API_KEY= BASE_URL=https://your-llm-server.com/api && npx genui-sdk-server
 
 ```typescript
 import { startServer } from '@opentiny/genui-sdk-server';
+import { materialsMeta } from '@opentiny/genui-sdk-materials-vue-element-plus/meta';
 
 startServer({
   port: 3100,
   baseURL: 'https://api.openai.com/v1',
   apiKey: '',
   maxAttempts: 10, // 端口冲突时最大尝试次数
+  materialsMeta,
 });
 ```
 
@@ -86,6 +88,7 @@ startServer({
 ```typescript
 import express from 'express';
 import { equipChatCompletions } from '@opentiny/genui-sdk-server';
+import { materialsMeta } from '@opentiny/genui-sdk-materials-vue-element-plus/meta';
 import cors from 'cors';
 
 const app = express();
@@ -95,6 +98,7 @@ equipChatCompletions(app, {
   route: '/chat/completions',
   apiKey: '',
   baseURL: 'https://api.openai.com/v1',
+  materialsMeta, // 不传则根据请求的 framework 取默认物料（Vue → OpenTiny Vue，Angular → OpenTiny Angular）
 });
 
 app.listen(3000);

packages/chat-completions/src/ai-sdk-chat/ai-sdk-chat-completion.ts

@@ -3,7 +3,7 @@ import { createOpenAI, type OpenAIProvider } from '@ai-sdk/openai';
 import { createAnthropic, type AnthropicProvider } from '@ai-sdk/anthropic';
 import { createDeepSeek, type DeepSeekProvider } from '@ai-sdk/deepseek';
 import type { ChatCompletionCreateParamsBase } from 'openai/resources/chat/completions';
-import type { AsyncIterableStream, ChatCompletionChunk, IRequestOptions } from '../types';
+import type { AsyncIterableStream, ChatCompletionChunk, IChatCompletionsConfig, IRequestOptions } from '../types';
 import { openaiCompatibleTransformChunk } from './openai-compatible-transform';
 import { ChatCompletions } from '../chat-completions';
 import { createAsyncIterableStream } from './async-iterable-stream';
@@ -34,8 +34,8 @@ export class AiSdkChatCompletions extends ChatCompletions<AsyncIterableStream<Te
   protected readonly providerInstance: ProviderInstance;
   protected modelInstance: LanguageModel;
 
-  constructor({ apiKey, baseURL, provider }: { apiKey: string; baseURL: string; provider: ProviderType }) {
-    super();
+  constructor({ apiKey, baseURL, provider, materialsMeta }: IDefaultModelProviderConfig & { baseURL: string } & IChatCompletionsConfig) {
+    super({ materialsMeta });
     const providerCreator = providerMap[provider];
     this.providerInstance = providerCreator({
       apiKey,

packages/chat-completions/src/chat-completions.ts

@@ -2,13 +2,20 @@ import type {
   ChatCompletionResponse,
   ChatCompletionCreateParamsBase,
   IChatCompletionCreateParams,
+  IChatCompletionsConfig,
   IRequestOptions,
 } from "./types";
 import { requestTransform } from "./request-transform";
 
 export abstract class ChatCompletions<T = ChatCompletionResponse, R = ChatCompletionResponse> {
+  protected readonly materialsMeta?: IChatCompletionsConfig['materialsMeta'];
+
+  constructor(config?: IChatCompletionsConfig) {
+    this.materialsMeta = config?.materialsMeta;
+  }
+
   protected async preTransform(params: IChatCompletionCreateParams): Promise<ChatCompletionCreateParamsBase> {
-    return requestTransform(params);
+    return requestTransform(params, { materialsMeta: this.materialsMeta });
   }
   protected async postTransform(response: T): Promise<R> {
     return response as unknown as R;
@@ -33,4 +40,3 @@ export abstract class ChatCompletions<T = ChatCompletionResponse, R = ChatComple
     options?: IRequestOptions
   ): Promise<T>;
 }
-

packages/chat-completions/src/fetch-chat-completions.ts

@@ -1,6 +1,7 @@
 import { ChatCompletions } from "./chat-completions";
 import type {
   ChatCompletionCreateParamsBase,
+  IChatCompletionsConfig,
   IRequestOptions,
   ChatCompletionResponse
 } from "./types";
@@ -9,8 +10,8 @@ export class FetchChatCompletions extends ChatCompletions<Response, ChatCompleti
   protected readonly apiKey: string;
   protected readonly baseURL: string;
 
-  constructor(config: { apiKey: string; baseURL: string }) {
-    super();
+  constructor(config: { apiKey: string; baseURL: string } & IChatCompletionsConfig) {
+    super(config);
     this.apiKey = config.apiKey;
     this.baseURL = config.baseURL.replace(/\/$/, '');
   }

packages/chat-completions/src/request-transform.ts

@@ -1,7 +1,12 @@
 import { genPrompt, type IMaterialsMeta } from '@opentiny/genui-sdk-core';
 import { materialsMeta } from '@opentiny/genui-sdk-materials-vue-opentiny-vue/meta';
 import { materialsMeta as ngMaterialsMeta } from '@opentiny/genui-sdk-materials-angular-opentiny-ng/meta';
-import { IChatCompletionCreateParams, ChatCompletionCreateParamsBase, type IGenPromptConfig } from './types';
+import {
+  IChatCompletionCreateParams,
+  ChatCompletionCreateParamsBase,
+  type IChatCompletionsConfig,
+  type IGenPromptConfig,
+} from './types';
 
 
 type IFrameworkKey = 'Vue' | 'Angular';
@@ -27,7 +32,8 @@ function mergePrompt(
 }
 
 export function requestTransform(
-  params: IChatCompletionCreateParams
+  params: IChatCompletionCreateParams,
+  config?: IChatCompletionsConfig,
 ): ChatCompletionCreateParamsBase {
   const newParams = structuredClone(params);
 
@@ -43,10 +49,10 @@ export function requestTransform(
 
   const { framework = 'Vue', strategy = 'append', ...promptConfig } = tgCustomConfig;
 
-  const materialsMetaForFramework =
-    metaMap[framework] ?? materialsMeta;
+  const resolvedMaterialsMeta =
+    config?.materialsMeta ?? metaMap[framework as IFrameworkKey] ?? materialsMeta;
   const systemMessages = newParams.messages?.find((message) => message.role === 'system');
-  const prompt = genPrompt(framework, materialsMetaForFramework, promptConfig);
+  const prompt = genPrompt(framework, resolvedMaterialsMeta, promptConfig);
   if (systemMessages) {
     systemMessages.content = mergePrompt(systemMessages.content as string, prompt, strategy);
   } else {

packages/chat-completions/src/types.ts

@@ -1,12 +1,16 @@
 import type { ChatCompletionChunk } from "openai/resources/chat/completions";
 import type { ChatCompletionCreateParamsBase } from "openai/resources/chat/completions";
-import type { IGenPromptCustomConfig } from "@opentiny/genui-sdk-core";
+import type { IGenPromptCustomConfig, IMaterialsMeta } from "@opentiny/genui-sdk-core";
 
 export interface IGenPromptConfig extends IGenPromptCustomConfig {
   framework?: 'Vue' | 'Angular' | string;
   strategy?: 'append' | 'override' | 'prepend';
 }
 
+export interface IChatCompletionsConfig {
+  materialsMeta?: IMaterialsMeta;
+}
+
 declare global {
   export type JsonSerialized<T> = string & {
     __json_serialized: T;

packages/server/README.md

@@ -30,13 +30,15 @@ npx genui-sdk-server -e .env.production
 
 ```typescript
 import { startServer, equipChatCompletions } from '@opentiny/genui-sdk-server';
+import { materialsMeta } from '@opentiny/genui-sdk-materials-vue-element-plus/meta';
 import express from 'express';
 
 // Option 1: Use startServer (includes default route /chat/completions)
 startServer({
   port: 3100,
   baseURL: 'https://api.openai.com/v1',
   apiKey: 'your-api-key',
+  materialsMeta, // optional: fix materials at startup
 });
 
 // Option 2: Custom Express app
@@ -45,6 +47,7 @@ equipChatCompletions(app, {
   route: '/api/chat',
   baseURL: 'https://api.openai.com/v1',
   apiKey: 'your-api-key',
+  materialsMeta,
 });
 app.listen(3100);
 ```