后端 web-contracts-src-extension-host-runtime
本页由当前 SDK 声明自动生成。 导入入口:@woohaa3/contracts。
AUTH_LEVEL_RANK · ApplicationBackendActivation · ApplicationBackendCapabilityRegistration · ApplicationBackendConfigFacade · ApplicationBackendExtensionDefinition · ApplicationBackendExtensionHealth · ApplicationBackendHost · ApplicationBackendProviderHost · ApplicationBackendResource · ApplicationBackendWorkAdmission · ApplicationBackendWorkFacade · ApplicationBackendWorkHandle · ApplicationDisposeReason · ApplicationExtensionMcpTool · ApplicationExtensionPrincipal · isAuthLevelAtLeast
AUTH_LEVEL_RANK
认证等级强弱:插件不能弱化宿主要求(design D2)。
等级。旧 auth: admin 迁移为 authenticated + 具名 requiredActions;核心 MUST NOT
依赖管理员等级放行。
export const AUTH_LEVEL_RANK: Readonly<Record<"public" | "authenticated", number>>;ApplicationBackendActivation
插件激活返回的可回收贡献。
首版不强制插件使用 Cordis;dispose 让宿主统一按 owner 反序释放;资源也可通过
host.registerResource 登记(二者都会被幂等释放)。
export type ApplicationBackendActivation = { dispose?: () => Promise<void> | void;};ApplicationBackendCapabilityRegistration
插件注册的 typed capability(供同宿主其它模块按 id 解析)。
export type ApplicationBackendCapabilityRegistration = { id: string; version: number; value: unknown;};成员说明:
version:能力对象的形状版本。 同id的不同version并存,互不覆盖;消费方按自己需要的版本解析。破坏性变更抬版本, 纯增量不抬(规则与HOST_SERVICE_ABI一致)。value:capability 实现;具体形状由 capability owner 约定。
ApplicationBackendConfigFacade
宿主提供的配置读写 facade(只读已提交配置;不暴露秘密)。
export type ApplicationBackendConfigFacade = { configVersion: () => number | null; values: () => Record<string, unknown>; secretRefs: () => readonly string[]; desiredEnabled: () => boolean;};成员说明:
configVersion:当前插件已提交的配置版本;未配置时为 null。values:当前插件非秘密配置值快照。secretRefs:秘密引用列表(无秘密值)。desiredEnabled:目标是否启用(真实工作中以它为准)。
ApplicationBackendExtensionDefinition
后端插件定义(构建时静态登记;宿主 activation 前解析依赖)。
export type ApplicationBackendExtensionDefinition = { extensionId: string; executors?: readonly ExtensionExecutorModule[]; publicRoutes?: readonly ApplicationExtensionPublicRouteMapping[]; mcpTools?: readonly ApplicationExtensionMcpTool[]; requiredDependencies?: readonly string[]; health?: () => ApplicationBackendExtensionHealth | undefined; activate: (host: ApplicationBackendHost) => ApplicationBackendActivation | void | Promise<ApplicationBackendActivation | void>;};关联类型:ExtensionExecutorModule · ApplicationExtensionPublicRouteMapping · ApplicationExtensionMcpTool · ApplicationBackendExtensionHealth · ApplicationBackendHost · ApplicationBackendActivation
成员说明:
executors:Trusted module paths resolved from extension.json by the extension loader.requiredDependencies:必需依赖的 capability/service id;缺失时不得产生部分可用贡献。health:当前健康状态:undefined表示健康(状态投影为active)。 只在插件已装载时返回 degraded;未装载(配置中/已停用)由状态投影自己判断,本钩子不参与。 宿主必须容忍它抛错(按健康处理并记日志),因为它会被状态查询同步调用。
ApplicationBackendExtensionHealth
后端插件自报的健康状态:已装载但能力没就绪。
activation 成功只说明插件进程内装载完成(fiber 起来了、贡献注册了),不代表它的能力当下可用:
生成 Provider 缺凭据时仍要注册(否则管理面看不到它、也无法预填配置),但模型进不了 catalog。
这种「装着但用不了」的稳态用 degraded 表达,避免把它混成 activation 失败,也避免伪称「运行中」。
健康状态必须按需重读(health())而不是 activation 时快照:管理员补上凭据后,插件本身不用
重启,状态应随之回到 active。
export type ApplicationBackendExtensionHealth = { state: "degraded"; diagnostics: readonly ApplicationExtensionSafeDiagnostic[];};关联类型:ApplicationExtensionSafeDiagnostic
成员说明:
diagnostics:公开安全诊断(不得包含秘密)。degraded 时不得为空。
ApplicationBackendHost
宿主注入给插件的运行时接口。
export type ApplicationBackendHost = { extensionId: string; host: ApplicationExtensionHostIdentity; deployment?: { basePath: string; }; config: ApplicationBackendConfigFacade; work: ApplicationBackendWorkFacade; services: ApplicationExtensionServices; registerCapability: (registration: ApplicationBackendCapabilityRegistration) => void; registerHandler: (registration: ApplicationBackendHandlerRegistration) => void; registerHttpHandler?: (registration: ApplicationBackendHttpHandlerRegistration) => void; registerRawHttpHandler?: (registration: ApplicationBackendRawHttpHandlerRegistration) => void; registerResource: (resource: ApplicationBackendResource) => void; registerGeneration?: (provider: GenerationProvider) => void; unregisterGeneration?: (providerId: string) => void; registerMediaFormat?: (format: MediaFormatValidator) => void; registerAgentRole?: (implementation: AgentRoleImplementation) => () => void; registerStorage?: (backend: StorageBackend) => void; unregisterStorage?: (backendId: string) => void; registerExposer?: (exposer: StorageExposer) => void; unregisterExposer?: (exposerId: string) => void; registerTelemetryExport?: (provider: TelemetryExport) => void; unregisterTelemetryExport?: (exportId: string) => void; registerMarketplaceSource?: (source: MarketplaceSource) => void; unregisterMarketplaceSource?: (sourceId: string) => void; providers?: ApplicationBackendProviderHost; diagnostics?: ApplicationBackendDiagnostics; logger: (event: Record<string, unknown>) => void;};关联类型:ApplicationExtensionHostIdentity · ApplicationBackendConfigFacade · ApplicationBackendWorkFacade · ApplicationExtensionServices · ApplicationBackendCapabilityRegistration · ApplicationBackendHandlerRegistration · ApplicationBackendHttpHandlerRegistration · ApplicationBackendRawHttpHandlerRegistration · ApplicationBackendResource · GenerationProvider · MediaFormatValidator · AgentRoleImplementation · StorageBackend · StorageExposer · TelemetryExport · MarketplaceSource · ApplicationBackendProviderHost · ApplicationBackendDiagnostics
成员说明:
host:宿主 identity:站点插件生产宿主为 application。deployment:只读部署上下文。 插件据此把应用逻辑路径解析为公开 URL(如第三方扩展入口/CSP 作用域), 不在插件内自持可变的部署配置。work:受控在途工作 facade(admission / 恢复);停用后 admit 立即被拒绝。services:受限服务 facade(按声明能力裁剪)。registerCapability:注册一个 typed capability;重复 id 抛错。registerHandler:注册一个受控 handler;重复 route 抛错。registerHttpHandler:注册一个受控 HTTP handler(server-only;design D4);重复 (method, route) 抛错。registerRawHttpHandler:注册一个受控原始 HTTP handler(server-only;design D4);重复 (method, route) 抛错。registerResource:注册后台资源;activation 回滚时按反序 stop。registerGeneration:注册一个生成 Provider。 只有后端生成能力宿主提供;重复 providerId 抛错。unregisterGeneration:注销一个生成 Provider。 凭据变更后插件失效/重激活时用于释放旧注册。registerMediaFormat:Register a custom media validator; activation cleanup always releases its registration.registerAgentRole:注册一个 Agent 角色实现。 归属由宿主按本次 activation 的 extensionId 记账,插件不能自报其他扩展身份;停用/回滚时 宿主自动注销,重复完整角色 id 会让本次激活失败并回滚。unregisterStorage:注销一个存储后端(按backendId)。 扩展卸载/停用必须注销(宿主也会替它按反序调用)。实现须幂等:重复注销同一 id 不算错误, 因为「现在没有这个后端」正是调用方想要的终态。registerExposer:注册一个对外地址提供者(可选能力)。 与registerStorage同形:谁注册谁收回,宿主按 owner 记 id 并在停用/回滚时反序注销。 与存储分成两个接缝的原因见HostExposerService:地址能力可以独立于字节驻留存在 (例如 CDN 回源签名),缺少它不该让存储注册失败,反之亦然。unregisterExposer:注销一个地址提供者(按exposerId)。实现须幂等。registerTelemetryExport:注册一个遥测出口。 与registerStorage同形:谁注册谁收回,宿主按 owner 记 id 并在停用/回滚时反序注销。 为什么必须有这条接缝:「发到哪、用什么凭据」是出口自己的能力(部署地址、会话、令牌), core 只回答“发不发”。core 若能自己枚举目的地,就等于要知道具体扩展身份,还会造出一个 “配了 id 却没人读”的死设置——所以出口只能由扩展在运行期注册进来。 缺失表示宿主没有遥测能力(纯本地宿主/旧版本):扩展必须记日志跳过, 不得把「宿主没这个能力」当成激活失败。unregisterTelemetryExport:注销一个遥测出口(按exportId;实现须幂等)。registerMarketplaceSource:注册一个扩展市场来源。 与registerStorage同形:谁注册谁收回,宿主按 owner 记sourceId并在停用 / 回滚时反序注销。 宿主按本扩展的扫描来源(内置根 / 可写根 / 受管根)断言:只有内置根扩展可以注册来源,其余抛EXTENSION_MARKETPLACE_SOURCE_UNTRUSTED_ROOT。来源只交付字节,签名信任仍由本机信任根决定。 缺失表示宿主没有市场扩展点:扩展必须记日志跳过,不得把它当成激活失败。unregisterMarketplaceSource:注销一个市场来源(按sourceId;实现须幂等)。providers:基础提供者注册面。只有后端宿主提供; 同一 slot 的重复 owner 在开放入口前拒绝。diagnostics:只读诊断缓冲(可选):宿主把已脱敏的服务端接入/同步事件投影给可信扩展。 缺失表示该宿主没有诊断能力(纯本地宿主/旧版本),扩展必须把调试窗口显示为 「不可用」,而不是伪造一份空日志。
ApplicationBackendProviderHost
基础提供者注册面。
扩展通过它登记类型化 identity/site/resource/lifecycle provider;宿主在开放受保护入口前 按可信 profile 校验「每个 slot 恰有一个 owner」。这不是无类型字符串 capability。
export type ApplicationBackendProviderHost = { registerIdentityProvider(provider: IdentityProvider): void; registerSiteAccessPolicy(policy: SiteAccessPolicy): void; registerResourceAccessPolicy(policy: ResourceAccessPolicy): void; registerResourceLifecyclePolicy(policy: ResourceLifecyclePolicy): void; registerResourceDirectory(directory: ResourceDirectory): void;};关联类型:IdentityProvider · SiteAccessPolicy · ResourceAccessPolicy · ResourceLifecyclePolicy · ResourceDirectory
成员说明:
registerResourceDirectory:可选:资源发现目录(Access);缺失时不进入必需 profile,消费方 fail closed。
ApplicationBackendResource
export type ApplicationBackendResource = { id: string; start?: () => Promise<void> | void; stop: (reason?: ApplicationDisposeReason) => Promise<void> | void;};成员说明:
stop:幂等停止;activation 回滚与停用都调用它,并携带释放原因。
ApplicationBackendWorkAdmission
export type ApplicationBackendWorkAdmission = { ok: true; workId: string; configVersion: number;} | { ok: false; reason: "disabled" | "not-ready" | "version-mismatch";};ApplicationBackendWorkFacade
export type ApplicationBackendWorkFacade = { admit: () => ApplicationBackendWorkAdmission; resume: (workId: string) => ApplicationBackendWorkHandle | null; activeWorkCount: () => number;};关联类型:ApplicationBackendWorkAdmission · ApplicationBackendWorkHandle
ApplicationBackendWorkHandle
一条已受理工作的 handle(版本化;draining 期间仍可恢复/终态化)。
export type ApplicationBackendWorkHandle = { workId: string; configVersion: number; markRunning: () => void; settle: (state: "succeeded" | "failed" | "cancelled") => void;};ApplicationDisposeReason
释放原因: 宿主优雅关闭/热重载只 detach;停用/升级/卸载才 cancel 并排空。
export type ApplicationDisposeReason = "shutdown" | "reload" | "disable" | "upgrade" | "uninstall";ApplicationExtensionMcpTool
扩展自有 MCP 工具声明;宿主负责认证、schema 与 handler 分派。
export type ApplicationExtensionMcpTool = { name: string; description: string; route: string; permission: "read" | "write"; newWork?: boolean; parameters?: Record<string, { type: "string" | "strings" | "object"; optional?: boolean; maxLength?: number; description?: string; }>;};ApplicationExtensionPrincipal
插件收到的可信 delegated principal 与能力范围(design D3)。
这是宿主注入的不可伪造身份:下游服务据此检查插件身份与操作权限。插件不能改写它, 也不获得原始服务令牌。
export type ApplicationExtensionPrincipal = { extensionId: string; configVersion: number; delegatedActor?: string; capabilities: readonly string[];};成员说明:
extensionId:可信插件 identity(由宿主配置,不接受调用者自报)。configVersion:不可变配置版本(工作准入时绑定)。delegatedActor:委托主体(管理员/系统);用于下游审计,不用于无限授权。capabilities:声明能力范围(例如 “tasks:submit”);facade 在越权时拒绝。
isAuthLevelAtLeast
export function isAuthLevelAtLeast(actual: ApplicationExtensionAuthLevel, required: ApplicationExtensionAuthLevel): boolean;