跳转到内容

后端 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