后端 web-contracts-src-extension-plugin
本页由当前 SDK 声明自动生成。 导入入口:@woohaa3/contracts。
AnyExtensionPlugin · ExtensionPlugin · HostConfigField · HostConfigFields · HostConfigSchema · HostConfigValues · defineConfigSchema
AnyExtensionPlugin
export type AnyExtensionPlugin = ExtensionPlugin<any>;关联类型:ExtensionPlugin
成员说明:
directory:宿主扫描到的插件绝对目录,仅用于展示。icon:设置页插件卡片上的图标:语义图形名(PLUGIN_ICON_NAMES)或品牌图形路径;缺省显示通用插件图标。website:服务商网站,由扩展声明;缺省不提供网站跳转。modelTypes:Provider 适配器支持的输出类型,用于配置前的能力标签;不代表账号已有模型或授权。setupOrder:添加提供商列表的展示顺序;未声明时排在推荐入口之后。modelRefresh:模型目录刷新入口声明:设置页据此显示「可用模型」一节(说明 + 刷新按钮)。path由插件自己注册并鉴权:用@woohaa3/provider-sdk的registerModelRefreshRoute(鉴权与响应形状统一),或自行用ctx.webServer.registerHttp/registerRawHttp。 扩展可见的服务面里没有gateway,不要按ctx.gateway.route写。 宿主只把声明透传给设置面,MUST NOT 在管理面硬编码具体 Provider(见 application-extension-runtime 规范)。inject:Cordis 的依赖注入声明(与ExtensionPlugin同形)。 两种形态:string[]表示全部必需;对象形态可以区分必需与可选—— 宿主能力(webServer/capabilities/services/diagnostics)在最小装配里可能缺席, 插件应声明为可选,缺席时按能力分支而不是装载失败。health:插件自报健康:返回undefined表示健康,返回 degraded 表示「已装载但能力没就绪」 (例如生成 Provider 还没配 API Key)。 每次状态查询都会用当前配置调用它,所以补上凭据后不用重启插件,站点状态就回到 active。 只有受站点开关管理的插件需要实现;未实现时一律按健康处理。 用方法签名而不是属性签名:属性上的函数类型在 strictFunctionTypes 下按逆变检查,会让ExtensionPlugin<具体 F>不再能赋给AnyExtensionPlugin(ExtensionPlugin<any>); 方法签名保持双变(与apply一致),AnyExtensionPlugin才继续成立。testConnection:连接与凭据测试(不落盘):用候选配置验证 API Key 与服务地址是否可用。
ExtensionPlugin
扩展插件:Cordis 对象插件加上宿主装载所需的元数据。
宿主从配置段 configPrefix 读取值、按 Config 校验后调用 apply;label 是设置页分组名。
export type ExtensionPlugin<F extends HostConfigFields = HostConfigFields> = { readonly name: string; readonly label: string; readonly directory?: string; readonly icon?: PluginIcon; readonly website?: string; readonly modelTypes?: readonly CanvasTaskModelType[]; readonly setupOrder?: number; readonly modelRefresh?: { readonly path: string; readonly hint: string; }; readonly configPrefix: string; readonly inject: readonly string[] | { readonly required?: readonly string[]; readonly optional?: readonly string[]; }; readonly Config: HostConfigSchema<F>; health?(config: HostConfigValues<F>): ApplicationBackendExtensionHealth | undefined; testConnection?(config: HostConfigValues<F>): Promise<{ readonly ok: boolean; readonly message?: string; }>; apply(ctx: HostExtensionContext, config: HostConfigValues<F>): void | Promise<void>;};关联类型:HostConfigFields · PluginIcon · CanvasTaskModelType · HostConfigSchema · HostConfigValues · ApplicationBackendExtensionHealth · HostExtensionContext
成员说明:
directory:宿主扫描到的插件绝对目录,仅用于展示。icon:设置页插件卡片上的图标:语义图形名(PLUGIN_ICON_NAMES)或品牌图形路径;缺省显示通用插件图标。website:服务商网站,由扩展声明;缺省不提供网站跳转。modelTypes:Provider 适配器支持的输出类型,用于配置前的能力标签;不代表账号已有模型或授权。setupOrder:添加提供商列表的展示顺序;未声明时排在推荐入口之后。modelRefresh:模型目录刷新入口声明:设置页据此显示「可用模型」一节(说明 + 刷新按钮)。path由插件自己注册并鉴权:用@woohaa3/provider-sdk的registerModelRefreshRoute(鉴权与响应形状统一),或自行用ctx.webServer.registerHttp/registerRawHttp。 扩展可见的服务面里没有gateway,不要按ctx.gateway.route写。 宿主只把声明透传给设置面,MUST NOT 在管理面硬编码具体 Provider(见 application-extension-runtime 规范)。inject:Cordis 的依赖注入声明(与ExtensionPlugin同形)。 两种形态:string[]表示全部必需;对象形态可以区分必需与可选—— 宿主能力(webServer/capabilities/services/diagnostics)在最小装配里可能缺席, 插件应声明为可选,缺席时按能力分支而不是装载失败。health:插件自报健康:返回undefined表示健康,返回 degraded 表示「已装载但能力没就绪」 (例如生成 Provider 还没配 API Key)。 每次状态查询都会用当前配置调用它,所以补上凭据后不用重启插件,站点状态就回到 active。 只有受站点开关管理的插件需要实现;未实现时一律按健康处理。 用方法签名而不是属性签名:属性上的函数类型在 strictFunctionTypes 下按逆变检查,会让ExtensionPlugin<具体 F>不再能赋给AnyExtensionPlugin(ExtensionPlugin<any>); 方法签名保持双变(与apply一致),AnyExtensionPlugin才继续成立。testConnection:连接与凭据测试(不落盘):用候选配置验证 API Key 与服务地址是否可用。
HostConfigField
export type HostConfigField = SettingDefinition extends infer D ? (D extends unknown ? Omit<D, "group" | "ownerExtensionId"> : never) : never;关联类型:SettingDefinition
成员说明:
label:设置页上的名称。reload:hot:运行中生效;restart:写入后需要重启进程。legacyEnv:过渡期兼容的旧环境变量名;新配置项不要再声明。
HostConfigFields
export type HostConfigFields = Readonly<Record<string, HostConfigField>>;关联类型:HostConfigField
HostConfigSchema
结构上满足 Standard Schema v1,可直接作为 Cordis 插件的 Config。
export type HostConfigSchema<F extends HostConfigFields = HostConfigFields> = { readonly fields: F; readonly "~standard": { readonly version: 1; readonly vendor: "woohaa3"; readonly validate: (value: unknown) => { readonly value: HostConfigValues<F>; } | { readonly issues: ReadonlyArray<ConfigIssue>; }; readonly types?: { readonly input: unknown; readonly output: HostConfigValues<F>; }; };};关联类型:HostConfigFields · HostConfigValues · ConfigIssue
HostConfigValues
有默认值的字段必有值,其余可缺省。
export type HostConfigValues<F extends HostConfigFields> = { -readonly [K in keyof F as HasDefault<F[K]> extends true ? K : never]: FieldValue<F[K]>;} & { -readonly [K in keyof F as HasDefault<F[K]> extends true ? never : K]?: FieldValue<F[K]>;};关联类型:HostConfigFields · HasDefault · FieldValue
defineConfigSchema
export function defineConfigSchema<const F extends HostConfigFields>(fields: F): HostConfigSchema<F>;关联类型:HostConfigFields · HostConfigSchema