跳转到内容

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

关联类型:ApplicationDisposeReason

成员说明:

  • 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;

关联类型:ApplicationExtensionAuthLevel