后端 web-contracts-src-extension-service:ExtensionExecutorModule – HostExtensionContext
本页由当前 SDK 声明自动生成。 导入入口:@woohaa3/contracts。
ExtensionExecutorModule · ExtensionExecutorOutcome · GenerationCancelCapability · GenerationModelDefinition · GenerationModelDescription · GenerationModelPolicyRow · GenerationModelPolicySnapshot · GenerationPrepareInput · GenerationProvider · GenerationProviderHandle · GenerationReference · GenerationReferenceUpload · GenerationReferenceUploadInput · GenerationReferenceUploadResult · GenerationResolveModelInput · GenerationStableMediaResult · GenerationTaskReference · HOST_SERVICE_ABI · HostAgentAuthoringToolService · HostAgentRoleService · HostCapabilityService · HostConfigReader · HostExposerService · HostExtensionContext
ExtensionExecutorModule
An installed extension contributes a separately loadable daemon module. Paths are resolved by the loader.
export type ExtensionExecutorModule = { id: string; module: string; export: string;};ExtensionExecutorOutcome
export type ExtensionExecutorOutcome = { status: "succeeded"; result?: unknown;} | { status: "failed"; error: { code: string; message: string; }; result?: unknown;} | { status: "cancelled"; error?: { code: string; message: string; }; result?: unknown;};GenerationCancelCapability
模型级取消能力:区分本地取消与远端取消。
export type GenerationCancelCapability = "local" | "remote" | "unsupported";GenerationModelDefinition
模型定义(资源定义 + 运营身份;不含秘密)。
export type GenerationModelDefinition = { providerId: string; providerModelId: string; modelType: CanvasTaskModelType; operation?: string; title?: string; inputSchema?: Record<string, unknown>; defaultInput?: Record<string, unknown>; promptRequirement?: PromptRequirement; interaction?: ModelInteractionDescriptor; cancel?: GenerationCancelCapability; executable?: boolean; taskTimeoutMs?: number; notice?: string; capabilities?: Record<string, unknown>; capabilityFacts?: GenerationModelCapabilityFacts;};关联类型:CanvasTaskModelType · PromptRequirement · ModelInteractionDescriptor · GenerationCancelCapability · GenerationModelCapabilityFacts
成员说明:
promptRequirement:模型级 prompt 要求;缺省 required(保持既有语义)。interaction:受信任 interaction identity;缺省由生成模块回落到 generic。cancel:取消能力;缺省 local。executable:该模型当前能否执行。缺省表示跟随 Provider 的available。 Provider 已就绪但这个模型还缺自己的配置(例如方舟接入点)时为 false:设置页仍列出,任务目录不收录。notice:模型行上的一枚短标签(设置页「生成的模型」列表里显示,例如「站点在售」)。 只用于「这个模型的身份/来源需要额外解释」的场景(当前只有 RunningHub 保留的 公开清单未收录模型)。缺省 = 不显示。capabilities:参考输入声明(role/mediaKind/binding 等);结构由生成模块校验。capabilityFacts:模型事实能力。 只承载 inputSchema/bindings 表达不了的事实(本期为 reasoning);参考媒体输入 仍由 inputSchema 的 bindings 表达。缺省 = 未声明(消费者按不支持处理)。
GenerationModelDescription
Provider 对单个模型的动态描述(catalog 用;身份仍由注册表固定)。
export type GenerationModelDescription = { providerId?: string; modelId?: string; modelType?: string; title?: string; inputSchema?: Record<string, unknown>; defaultInput?: Record<string, unknown>; capabilities?: Record<string, unknown>; capabilityFacts?: GenerationModelCapabilityFacts; promptRequirement?: PromptRequirement; cancel?: GenerationCancelCapability;};关联类型:GenerationModelCapabilityFacts · PromptRequirement · GenerationCancelCapability
成员说明:
capabilityFacts:模型事实能力;缺省 = 未声明(消费者按不支持处理)。
GenerationModelPolicyRow
一条模型启停策略事实(与设置页「生成的模型」同源)。
export type GenerationModelPolicyRow = { modelKey: string; enabled: boolean; tombstone?: boolean;};成员说明:
modelKey:<providerId>:<providerModelId>。tombstone:已被移除的模型:即使 enabled 为真也不该出现在任何可选列表里。
GenerationModelPolicySnapshot
策略快照。initialized=false 表示库是空的,调用方按全部可用处理。
export type GenerationModelPolicySnapshot = { initialized: boolean; models: readonly GenerationModelPolicyRow[];};GenerationPrepareInput
生成模块交给插件 prepareInput 的规范输入。
export type GenerationPrepareInput = { providerModelId: string; modelType: "language" | "image" | "video" | "audio" | "motion"; prompt: string; parameters: Record<string, unknown>; references: ReadonlyArray<GenerationTaskReference>; canvasId?: string; taskKey?: string; runId?: string; endpoint?: string;};成员说明:
references:稳定参考输入(顺序与提交一致)。canvasId:这次执行属于哪张画布(远端 ACL 与对象键作用域都需要)。taskKey:客户端幂等执行键(通常等于 workerTaskKey)。endpoint:插件在resolveProviderModel中选出的具体 endpoint(合并模型路由结果)。
GenerationProvider
一个可执行的生成 Provider 注册。
provider 是 pptask PptaskProvider 的不透明句柄(契约层不引入其类型)。
生成模块负责把它交给 worker 运行时。
export type GenerationProvider = { serviceConnectionFactory?: { protocols: readonly ServiceConnectionProtocol[]; assistantProtocol?: ServiceConnectionProtocol; endpoints?: Partial<Record<ServiceConnectionProtocol, string>>; upstreamModelId?: (modelId: string) => string; create(input: { secret: string; endpoint: string; validate: () => Promise<void>; fetch?: typeof globalThis.fetch; }): GenerationProviderHandle; }; languageCapabilities?: (providerModelId: string) => { tools?: boolean; imageInput?: boolean; streaming?: boolean; } | undefined; extensionId: string; providerId: string; available: boolean; selectionAuthority?: "local" | "server"; catalogRevision?: number; credentialEpoch?: number; provider: GenerationProviderHandle; models: GenerationModelDefinition[]; describe?: (providerModelId: string) => GenerationModelDefinition | undefined; prepareInput?: (input: GenerationPrepareInput) => Record<string, unknown> | Promise<Record<string, unknown>>; uploadReference?: GenerationReferenceUpload; describeModel?: (input: { providerModelId: string; modelType: "language" | "image" | "video" | "audio" | "motion"; }) => Promise<GenerationModelDescription | undefined> | GenerationModelDescription | undefined; resolveProviderModel?: (input: GenerationResolveModelInput) => string | Promise<string>;};关联类型:ServiceConnectionProtocol · GenerationProviderHandle · GenerationModelDefinition · GenerationPrepareInput · GenerationReferenceUpload · GenerationModelDescription · GenerationResolveModelInput
成员说明:
serviceConnectionFactory:Explicit per-source execution. Omitted Providers reject personal source bindings.languageCapabilities:语言模型逐模型能力证据(图片输入/流式)。 文本模型统一视为支持工具调用;tools仅保留为目录展示信息,不再作为 Agent 工具回合门槛。 缺省或某个模型没有图片输入证据时,消费者 MUST 按不支持处理;不得从提供商品牌或媒体模型推测。available:该 Provider 当前是否可执行(凭据/配置就绪)。selectionAuthority:模型启用集合的权威来源。 缺省local:按站点运营策略过滤;server:Provider 自己的目录(例如远端托管生成) 就是权威,模型直接进入 catalog,本地策略 MUST NOT 过滤,也不因此改写策略存储。catalogRevision:目录版本(可选,单调)。Provider 只改 schema/能力、不改模型 id 集合时,用它参与 生成签名,使 catalog 失效重算;缺省不参与。credentialEpoch:凭据修订(可选,单调;只放不可逆摘要,绝不放明文密钥)。 Task 侧 registry 按签名缓存 provider 实例,签名只含模型/能力事实时,换 key 不会失效: 任务继续用缓存里那个持旧 key 的实例,配置显示已保存、testConnection也通过(它现读配置), 但真实生成持续失败,只有重启进程才恢复(2026-11-16 现场:RunningHub 同 key 重启前后 一失败一成功,中间从未换过 key)。把凭据修订纳入签名即可让换 key 立刻重建实例。 缺省不参与签名(从不换凭据的 Provider 无需实现)。provider:不透明执行句柄。models:模型注册表 + 静态描述(describe 不发网络请求)。describe:按 providerModelId 取模型定义。prepareInput:把已校验参数与稳定参考输入编译成 Provider 真正需要的输入 。 缺省时生成模块使用通用prompt + parameters + urls/videoUrls/audioUrls形状。 RunningHub 之类需要providerOptions.<providerId>.input的 Provider 提供本钩子。 输入只含稳定引用与已校验参数,不含凭据或任意 URL。uploadReference:Provider 自带上传参考素材(设计稿 storage-extension-point 的生成链路 ①)。 提交时 Task 先问 Provider:有本钩子且能把参考字节读出来,就交给它自己上传(返回的地址 直接进参考输入);返回空或没实现时才走存储的expose签出地址。凭据不出插件。describeModel:动态描述一个模型(含inputSchema/defaultInput/capabilities),用于构建 catalog。 Provider 自己的describe是参数 schema 的权威(litellm 图像走 OpenAI Images 字段、 runninghub 的 params 都在此);缺省时 catalog 只用注册时声明的静态inputSchema。 返回的 providerId/modelId MUST NOT 覆盖注册表身份(生成模块只取描述字段)。resolveProviderModel:逻辑模型 → 具体执行 endpoint 的路由。合并模型(如 t2i/i2i 合并)在提交时按输入选择具体 providerModelId; 缺省时执行身份仍是 catalog 的 providerModelId。 两个钩子都允许返回 Promise:隔离在 Extension Host 子进程里的受管 Provider 只能异步应答 。
GenerationProviderHandle
生成 Provider 的不透明句柄:由插件提供,生成模块原样交给运行时执行。
export type GenerationProviderHandle = unknown;GenerationReference
稳定参考输入(url 模式下的形状,顺序与提交一致)。
export type GenerationReference = { role: string; mediaKind?: string; mediaType: string; url: string;};GenerationReferenceUpload
export type GenerationReferenceUpload = (input: GenerationReferenceUploadInput) => Promise<GenerationReferenceUploadResult | undefined> | GenerationReferenceUploadResult | undefined;关联类型:GenerationReferenceUploadInput · GenerationReferenceUploadResult
GenerationReferenceUploadInput
Provider 自带上传的输入(设计稿 storage-extension-point 的生成链路 ①)。
有 uploadReference 的 Provider 先自己把参考素材传到它的素材服务,返回可直接传给生成
API 的地址/句柄;返回空表示这次不做,由宿主按存储的 expose 解析顺序签出地址。
凭据不出插件。
export type GenerationReferenceUploadInput = { reference: { role: string; mediaKind?: string; mediaType: string; }; bytes: Uint8Array; contentType: string; canvasId?: string; storageKey?: string;};成员说明:
canvasId:这次提交属于哪张画布。 只用于选择落点(画布命名空间 vs 主体命名空间),不是读取凭据: 上传成功后由 Provider 返回 locator,提交体只带 locator。 本机 Provider 忽略它。storageKey:素材在本机的稳定键(诊断与去重可用;远端 Provider 用它对齐提交键)。
GenerationReferenceUploadResult
Provider 上传参考素材的结果:二选一,都表达「上游怎么拿到这堆字节」。
locator:写进了本部署存储,交给生成服务端按位置读;url:写进了 Provider 自己的素材服务,上游直接拉。
export type GenerationReferenceUploadResult = { locator?: MediaLocator; url?: string;};关联类型:MediaLocator
GenerationResolveModelInput
生成模块交给插件 resolveProviderModel 的规范输入。
export type GenerationResolveModelInput = { providerModelId: string; modelType: "language" | "image" | "video" | "audio" | "motion"; prompt: string; parameters: Record<string, unknown>; references: ReadonlyArray<GenerationTaskReference>; canvasId?: string; taskKey?: string; runId?: string;};GenerationStableMediaResult
已被服务端持久化的稳定媒体结果。
Provider(典型是远端托管生成)可直接返回这种形状;Task worker 会先用 Media verify
按画布作用域确认对象可读,再写 TaskResultSummary,不再搬运字节。顺序:主媒体在前,
poster 只用于视频。MUST NOT 包含签名 URL 或字节。
export type GenerationStableMediaResult = { media: { storageKey: string; locator?: MediaLocator; contentType: string; size: number; checksum?: string; durationSeconds?: number; fps?: number; motion?: SomaMotionMetadata; poster?: { storageKey?: string; locator?: MediaLocator; contentType: string; size: number; checksum?: string; }; };};关联类型:MediaLocator · SomaMotionMetadata
GenerationTaskReference
交给 Provider 的稳定参考输入:位置 + 原始稳定身份。
三种形态只表达同一件事——「字节在哪」:
locator:本部署存储里的不透明位置(Task 调uploadReference之后由存储给);url:Provider 自己的素材服务地址(它自己上传的,或存储 expose 签出的);storageKey:本机媒体命名空间内的逻辑键,只在没有上两者时可用(本机 Provider)。 Provider 按自己的能力挑一个,不得把一种当成另一种来解析。
export type GenerationTaskReference = { role: string; mediaKind?: string; mediaType: string; url?: string; assetId?: string; storageKey?: string; locator?: MediaLocator;};关联类型:MediaLocator
成员说明:
url:执行期地址(url模式必有;storage-key模式缺省)。storageKey:media namespace 内的稳定键;storage-key模式下是唯一传递凭据。locator:字节的不透明定位符。 Provider 把它原样交给自己的上游(远端托管生成提交的就是它);调用方不解析。
HOST_SERVICE_ABI
宿主当前提供的服务面版本。
键必须与 HostExtensionContext 上的服务面属性一一对应;新增服务面时同时在这里登记,
否则插件无从声明对它的依赖(host-service-abi.test.ts 守着这条一致性)。
export const HOST_SERVICE_ABI: Readonly<{ readonly log: 1; readonly config: 1; readonly generation: 1; readonly storage: 1; readonly exposer: 1; readonly marketplace: 1; readonly webServer: 1; readonly services: 1; readonly telemetry: 1; readonly capabilities: 1; readonly mediaFormats: 1; readonly agentRoles: 1; readonly executors: 1; }>;成员说明:
log:ctx.log:结构化日志。config:ctx.config:宿主配置读取(可选面)。generation:ctx.generation:模型 Provider 注册与策略。storage:ctx.storage:字节存储后端注册。exposer:ctx.exposer:对外地址提供者。marketplace:ctx.marketplace:扩展市场来源注册。webServer:ctx.webServer:受控 HTTP 路由(可选面)。services:ctx.services:领域服务 facade(可选面)。telemetry:ctx.telemetry:遥测核心。capabilities:ctx.capabilities:能力注册表(可选面)。mediaFormats:ctx.mediaFormats:可编辑媒体格式注册(可选面)。agentRoles:ctx.agentRoles:Agent 角色注册(可选面)。executors:ctx.executors:独立执行模块注册(可选面)。
HostAgentAuthoringToolService
export type HostAgentAuthoringToolService = { register(contribution: AgentAuthoringToolContribution): () => void; list(): readonly AgentAuthoringToolContribution[];};关联类型:AgentAuthoringToolContribution
HostAgentRoleService
export type HostAgentRoleService = { register(implementation: AgentRoleImplementation): () => void; list(): readonly AgentRoleDescriptor[]; availability(namespacedId: string): { available: boolean; reason?: string; };};关联类型:AgentRoleImplementation · AgentRoleDescriptor
成员说明:
register:注册本插件实现的角色;返回幂等注销。重复完整身份由宿主拒绝并回滚激活。list:本插件已注册角色(只读、无准备副作用)。availability:读取某角色的可用性(缺失工具/通道能力时给出真实原因)。
HostCapabilityService
export type HostCapabilityService = { register(registration: CapabilityRegistration): () => void;};成员说明:
register:注册一个能力对象;返回注销函数。 同一id+version重复注册抛错(不同插件不能抢同一个能力);同一id的其它version不受影响。
HostConfigReader
扩展可读的配置面:只暴露按段读取,不把 SettingsService 写进公共契约。
export type HostConfigReader = { section(prefix: string): Readonly<Record<string, string | number | boolean>>;};HostExposerService
ctx.exposer:地址提供者注册面与解析入口。
export type HostExposerService = { register(exposer: StorageExposer): () => void; unregister(exposerId: string): void; list(): readonly StorageExposer[]; resolve(exposerId: string): StorageExposer | undefined; selectedId(): string | undefined; available(namespace: string, scope?: StorageScope, request?: StorageExposeRequest): boolean; expose(input: StorageExposeInput): Promise<string>; temporaryHosting(query?: TemporaryHostingQuery): TemporaryHostingRouteView;};关联类型:StorageExposer · StorageScope · StorageExposeRequest · StorageExposeInput · TemporaryHostingQuery · TemporaryHostingRouteView
成员说明:
register:注册提供者;返回注销函数(插件放进ctx.effect,卸载时自动注销)。list:可选的提供者:注册过的,加上「后端自带presign」的隐式提供者(id 即 backendId)。 隐式项让 cos / server 这类能就地签名的后端不必再写一份 exposer,也让设置页的下拉值 与exposer.primary的历史配置保持一致。selectedId:显式选中的地址提供者 id(exposer.primary,旧键storage.expose);自动模式为空。available:这一次请求能不能拿到地址(同步只看配置面;请求约束在真实 expose 时复核)。expose:取外部地址的解析顺序: ① 画布覆盖:指定 id 只用该来源;空串表示禁用。 ② 全局显式来源:只用该来源。 ③ 自动:按用户保存顺序(未列出的按扩展优先级 / ID 追加)选择合格来源。 可恢复失败时按同一顺序尝试下一个合格来源,每个来源最多一次。temporaryHosting:能力中心读取的权威路由快照;只读,不上传、不生成、不改配置。
HostExtensionContext
export type HostExtensionContext = Context & { readonly log: HostLogService; readonly config?: HostConfigReader; readonly generation: HostGenerationService; readonly storage: HostStorageService; readonly exposer: HostExposerService; readonly marketplace: HostMarketplaceService; readonly webServer?: HostWebServerService; readonly services?: ApplicationExtensionServices; readonly telemetry: HostTelemetryService; readonly deployment?: { readonly basePath: string; }; readonly capabilities?: HostCapabilityService; readonly mediaFormats?: HostMediaFormatService; readonly agentRoles?: HostAgentRoleService; readonly authoringTools?: HostAgentAuthoringToolService; readonly diagnostics?: ApplicationBackendDiagnostics;};关联类型:Context · HostLogService · HostConfigReader · HostGenerationService · HostStorageService · HostExposerService · HostMarketplaceService · HostWebServerService · ApplicationExtensionServices · HostTelemetryService · HostCapabilityService · HostMediaFormatService · HostAgentRoleService · HostAgentAuthoringToolService · ApplicationBackendDiagnostics
成员说明:
currentUser:App scope 的身份与权限快照,独立管理页面共用。applicationRemote:Application Remote:站点插件状态/管理 + Application 健康。canvasEdit:页面级画布编辑历史(撤销/重做、参数条目、冲突跳过) 。pageLeave:页面离开守卫(编辑扩展工作区,design D6)。 多文档工作区注册自己的未结算文档与串行结算;切换画布 / 离开页面先问它。canvasCommands:通用扩展画布命令提交能力。 扩展经此提交通用语义画布命令;只读会话拒绝。编辑扩展“添加到画布”用它提交 工程资产 + 输出资产 + 带工程的图片节点这一原子批次。canvasLocate:统一定位服务。canvasScope:当前 Canvas scope 身份。 只在 Canvas page scope 提供;extension 用它确定目标画布,不假定默认画布。hoverState:受控只读画布 facade。 只读 canonical/working 快照与订阅;MUST NOT import 宿主内部 canvas store。log:结构化日志出口。 前端实现只写 console:不落盘、不上报、不缓冲。宿主侧同名服务由源码声明提供;两者共用 contracts 的信封与脱敏表。extensionFaults:扩展渲染故障与会话内熔断。canvasNavigation:Canvas presentation navigation。 只在 Canvas page scope 提供。appRouter:应用级顶层页面 Router(App scope 提供)。canvasCatalog:多画布目录读模型。 跨 Canvas page transition 存活;不创建任何画布运行资源。canvasSelection:最近画布选择(App scope;用于缺省 canvasId 解析)。canvasPreparation:首次打开准备读模型。 跨 Canvas page transition 存活;不创建任何画布运行资源。canvasRecovery:显式不支持画布的恢复页(recovery page scope 提供)。canvasPreparationView:旧 ID 迁移准备态视图(preparation page scope 提供) 。theme:页面级唯一主题 owner。snippetCatalog:feature-owned 片段目录 capability(由 prompt-snippets extension 提供)。focusExit:图片/模型聚焦编辑的异步退出协调器 。modelInteractions:Canvas page scope 的模型交互注册表。extensionManager:插件管理 capability。 只暴露投影后的快照,不暴露底层 browser-local 原始配置。applicationExtensionStatus:站点应用插件状态读模型(Canvas page scope 提供) 。generationModelsStatus:生成模型状态读模型(Canvas page scope 提供) 。settingsRemote:宿主统一配置 remote(Canvas page scope / 画布壳 scope 提供) 。/api/settings的唯一读取出口;设置页、助手生成服务与画布引导都复用同一实例, 不各自新建 fetch 或轮询。agentConversationService:宿主 Agent 会话 service(Canvas page scope 提供) 。生成面板提交首轮与详情读模型共用; 业务生成扩展只消费它,不自行持久化会话。settingsOpen:画布内设置的打开能力。 左下角入口、旧/settings兼容意图与其它指路操作都经它打开同一 singleton 弹窗; 不涉及 App Router/页面导航。渲染失败/空壳的恢复页 scope 也提供同一能力。runState:统一生成运行状态(Canvas page scope 提供) 。taskNotifications:App 级任务结果通知服务 。 唯一实例,归 App scope:关闭设置、释放 Canvas page、切到历史页都不停止它; 设置「通知」分区只订阅 snapshot 并调用具名操作。config:宿主统一配置(可选):需要读其它插件配置段时使用(例如公开桶复用 COS 凭据)。 大多数扩展只用自己的第二参config,不应把这里当默认入口。exposer:对外地址提供者注册面(ctx.exposer)。 与storage分开是两个生命周期的结果:存储缺失宿主不可用;对外地址缺失只影响 「把 URL 交给远端」的任务,所以它不参与启动就绪。marketplace:扩展市场来源注册面。 只有内置根扩展可以注册来源;受管根 / 可写根扩展调用register会被宿主拒绝。webServer:受控 HTTP 路由(可选:最小装配/测试里可能没有 gateway)。 与generation/storage同级:它是公共基础设施,不是某类插件的专属特权。 声明它是可选的原因:纯 provider 插件不需要它,宿主在无 gateway 的组合里也不提供。services:宿主注入的领域服务 facade(documents / canvas / media / task 等)。 可选:最小装配里没有。插件按存在与否决定能力,不要假定一定注入。telemetry:遥测核心:emit/query/registerExport在同一服务上(core 层必备)。deployment:只读部署上下文(basePath等)。 插件据此把应用逻辑路径解析为公开 URL,不在插件内自持可变部署配置。capabilities:能力注册表(可选):插件把能力对象交给宿主,由核心层按需解析。mediaFormats:媒体格式注册面(可选):拥有可编辑媒体格式的站点插件在这里注册校验器。 与capabilities同级:注册按 extensionId 记账,插件停用/回滚时由宿主自动注销。agentRoles:Agent 角色注册面。 注册按实际装载 owner 记账,插件停用/回滚时宿主自动注销;插件不能自报其他扩展身份。authoringTools:Director-area MCP tools contributed by the active extension.diagnostics:宿主诊断缓冲(可选):只读投影,用于排障面板。