后端 web-contracts-src-extension-service:ApplicationExtensionMediaVerifyResult – ExtensionExecutorEvent
本页由当前 SDK 声明自动生成。 导入入口:@woohaa3/contracts。
ApplicationExtensionMediaVerifyResult · ApplicationExtensionNodeFacade · ApplicationExtensionRequestContext · ApplicationExtensionServices · ApplicationExtensionTaskAssociation · ApplicationExtensionTaskFacade · ApplicationExtensionTaskResult · ApplicationExtensionTaskSubmitResult · CanvasCatalogCreateResult · CanvasCatalogDeleteResult · CanvasCatalogListResult · CanvasCatalogRemote · CanvasCatalogService · CanvasCatalogState · CanvasCatalogSummaryResult · CanvasPreparationRemote · CanvasPreparationService · CanvasPreparationState · CanvasRecoveryService · CanvasSelectionService · CapabilityRegistration · DEFAULT_TASK_NOTIFICATION_PREFERENCES · ExtensionEngines · ExtensionExecutorEvent
ApplicationExtensionMediaVerifyResult
完整媒体核验结果。
与 stat 的区别:stat 只回存在性与 contentType 的粗粒度探测;verify 回完整
稳定 metadata(含真实 size 与 checksum),供来源迁移在目标同存储复用时核验,不得凭 key
推断 size 或填 0。
export type ApplicationExtensionMediaVerifyResult = { exists: false;} | { exists: true; metadata: MediaMetadata;};关联类型:MediaMetadata
ApplicationExtensionNodeFacade
仅操作通用 extension3d 节点,使用 Canvas 现有授权、CAS 与命令提交。
export type ApplicationExtensionNodeFacade = { read(input: { subject: string; canvasId: string; permission: "read" | "write"; }): Promise<ServerCanvas>; commit(input: { subject: string; canvasId: string; nodeId: string; requestId: string; expectedRevision: number; value: Record<string, unknown>; create?: { position: { x: number; y: number; }; }; }): Promise<{ revision: number; }>;};关联类型:ServerCanvas
ApplicationExtensionRequestContext
受控请求上下文:由宿主认证后注入,插件不得自报身份。
export type ApplicationExtensionRequestContext = { extensionId: string; authLevel: ApplicationExtensionAuthLevel; actor?: string; correlationId?: string; principal?: PrincipalContext; accessControl?: boolean; dataScope?: DataScope; sessionId?: string; signal?: AbortSignal;};关联类型:ApplicationExtensionAuthLevel · PrincipalContext · DataScope
成员说明:
actor:可信操作者标识(仅审计;不参与授权决策)。principal:可信应用用户主体。 由宿主 identity provider 建立并冻结;个人凭据与资源权限的 owner 只来自principal.subject。 个人插件不得以 authLevel、actor 或请求体 userId 代替。不含isAdmin/管理员角色。accessControl:宿主固定的访问控制装配状态与数据归属;不能由请求自报。sessionId:会话绑定(本地会话或登录会话);OAuth 事务用它绑定 owner。signal:取消信号。 宿主在 client 断连或 deadline 到达时 abort;流式 handler MUST 据此停止等待并收尾。
ApplicationExtensionServices
公共 Context 暴露给插件的受限服务集合;核心 Context 不属于可关闭插件集合。
export type ApplicationExtensionServices = { authoringTools?: HostAgentAuthoringToolService; executor?: ApplicationExtensionExecutorFacade; serviceConnections?: ApplicationServiceConnectionFacade; assistants?: ApplicationExtensionAssistantFacade; extensionNodes?: ApplicationExtensionNodeFacade; tasks: ApplicationExtensionTaskFacade; media: ApplicationExtensionMediaFacade; canvas: ApplicationExtensionCanvasFacade; canvasAccess?: ApplicationExtensionCanvasAccessFacade; authoring?: ApplicationAuthoringServices; secrets?: ApplicationExtensionSecretStore; personalGeneration?: ApplicationPersonalGenerationFacade; documents?: ExtensionDocumentStore; taskInspection?: TaskInspectionFacade; agentRoles?: ApplicationExtensionAgentRoleFacade;};关联类型:HostAgentAuthoringToolService · ApplicationExtensionExecutorFacade · ApplicationServiceConnectionFacade · ApplicationExtensionAssistantFacade · ApplicationExtensionNodeFacade · ApplicationExtensionTaskFacade · ApplicationExtensionMediaFacade · ApplicationExtensionCanvasFacade · ApplicationExtensionCanvasAccessFacade · ApplicationAuthoringServices · ApplicationExtensionSecretStore · ApplicationPersonalGenerationFacade · ExtensionDocumentStore · TaskInspectionFacade · ApplicationExtensionAgentRoleFacade
成员说明:
authoringTools:Director-area MCP tool contribution registry, scoped to the active extension.canvasAccess:项目读/写权限授权(design D13;任务 6.2)。 可选:未配置的宿主不提供,插件 MUST fail closed,不得仅凭 canvasId/nodeId 放行。authoring:受用户委托约束的 authoring/工具/个人生成端口(design D7/D8)。 可选:未配置的宿主不提供,插件须按能力声明回退。secrets:按 plugin/owner/purpose 隔离的加密秘密仓库(design D5)。personalGeneration:个人生成能力(账户模型目录/可执行性;design D8)。documents:owner-scoped 隔离通用数据存储。owner 来自可信 registration(extensionId),不来自请求体;facade 拒绝跨 owner 访问。taskInspection:受限任务监控 facade:要求tasks.inspect并在 repository 查询前校验;只交给声明该 action 的 extension。agentRoles:Agent 角色准备面。 只交给受信后端扩展的业务入口;浏览器不可达。缺失时扩展必须按能力拒绝,不回退自带模板。
ApplicationExtensionTaskAssociation
插件任务关联 DTO:Task 侧持久化的恢复与查询依据(不含秘密与配置正文)。
export type ApplicationExtensionTaskAssociation = { extensionId: string; configVersion: number; workerTaskKey: string;};成员说明:
workerTaskKey:稳定幂等 key;同一逻辑工作重试复用。
ApplicationExtensionTaskFacade
插件可调用的 Task facade:只提交/查询/取消自己拥有的非画布任务。
export type ApplicationExtensionTaskFacade = { submit(input: { workerTaskKey: string; modelType: string; modelKey: string; prompt: string; parameters: Record<string, unknown>; inputs?: readonly { assetId: string; role: string; storageKey: string; mediaType: string; mediaKind?: string; }[]; }): Promise<ApplicationExtensionTaskSubmitResult>; result?(workerTaskKey: string): Promise<ApplicationExtensionTaskResult | null>; status(workerTaskKey: string): Promise<{ workerTaskKey: string; state: string; } | null>; cancel(workerTaskKey: string): Promise<{ workerTaskKey: string; state: string; } | null>;};关联类型:ApplicationExtensionTaskSubmitResult · ApplicationExtensionTaskResult
ApplicationExtensionTaskResult
export type ApplicationExtensionTaskResult = { workerTaskKey: string; state: string; result?: TaskResultSummary; error?: TaskErrorSummary;};关联类型:TaskResultSummary · TaskErrorSummary
成员说明:
error:已由 Task 历史白名单裁剪的失败摘要,供扩展给出可操作的错误。
ApplicationExtensionTaskSubmitResult
非画布插件任务提交结果(accepted 不等待 provider 终态)。
export type ApplicationExtensionTaskSubmitResult = { ok: true; workerTaskKey: string; reused: boolean; state: string;} | { ok: false; code: "unauthorized" | "unavailable" | "unsupported" | "key-reused" | "storage-failed"; message: string;};CanvasCatalogCreateResult
export type CanvasCatalogCreateResult = { ok: true; canvasId: string; revision: number; title: string;} | { ok: false; code: string; error: string;};CanvasCatalogDeleteResult
删除画布结果。
删除是破坏性动作:调用方必须先让用户确认。expectedRevision 是本地权威内容的 CAS 版本,
与创建/重命名不同,删除没有可回显的对象,因此只有成功/失败两态。
export type CanvasCatalogDeleteResult = { ok: true;} | { ok: false; code: string; error: string;};CanvasCatalogListResult
export type CanvasCatalogListResult = { ok: true; entries: CanvasSummary[]; total: number; offset: number; limit: number;} | { ok: false; code: string; error: string;};关联类型:CanvasSummary
CanvasCatalogRemote
Catalog 远端 adapter:所有目录 HTTP 协议的唯一浏览器出口。
export interface CanvasCatalogRemote { list(input: { offset: number; limit: number; }): Promise<CanvasCatalogListResult>; get(canvasId: string): Promise<CanvasCatalogSummaryResult>; create(input: { canvasId?: string; title?: string; }): Promise<CanvasCatalogCreateResult>; delete(canvasId: string, expectedRevision: number): Promise<CanvasCatalogDeleteResult>;}关联类型:CanvasCatalogListResult · CanvasCatalogSummaryResult · CanvasCatalogCreateResult · CanvasCatalogDeleteResult
成员说明:
delete:删除画布(DELETE /api/canvases/:id?expectedRevision=N)。
CanvasCatalogService
export interface CanvasCatalogService { getState(): CanvasCatalogState; subscribe(listener: () => void): () => void; load(force?: boolean): Promise<CanvasCatalogListResult>; loadMore(): Promise<void>; create(input?: { title?: string; }): Promise<CanvasCatalogCreateResult>; delete(canvasId: string, expectedRevision?: number): Promise<CanvasCatalogDeleteResult>; get(canvasId: string): Promise<CanvasCatalogSummaryResult>; invalidate(): void; dispose(): void;}关联类型:CanvasCatalogState · CanvasCatalogListResult · CanvasCatalogCreateResult · CanvasCatalogDeleteResult · CanvasCatalogSummaryResult
成员说明:
load:加载第一页(默认缓存命中直接返回;force 强制刷新)。loadMore:追加下一页。create:创建画布,成功后失效并刷新目录。delete:删除画布,成功后失效并刷新目录。 版本号缺省取当前目录条目的revision;条目不在当前页时必须显式给出。get:按 ID 读取摘要(用于校验显式 canvasId 是否存在/展示当前标题)。invalidate:失效缓存,使下一次load()重新请求。
CanvasCatalogState
目录 store 的原子 snapshot。
export type CanvasCatalogState = { status: "idle" | "loading" | "ready" | "error"; entries: CanvasSummary[]; total: number; offset: number; limit: number; loadingMore: boolean; error: string | null;};关联类型:CanvasSummary
CanvasCatalogSummaryResult
export type CanvasCatalogSummaryResult = { ok: true; summary: CanvasDetailSummary;} | { ok: false; code: string; error: string;};关联类型:CanvasDetailSummary
CanvasPreparationRemote
来源目录 remote:浏览器访问 /api/canvas-sources 的唯一出口。
export interface CanvasPreparationRemote { listSources(): Promise<{ ok: true; sources: CanvasSourceCatalogEntry[]; } | { ok: false; code: string; error: string; }>; listAccessible(input: { sourceId: string; cursor: string | null; limit?: number; }): Promise<{ ok: true; page: CanvasSourceListPage; } | { ok: false; code: string; error: string; }>; status(canvasId: string): Promise<{ ok: true; state: PreparationState; } | { ok: false; code: string; error: string; conflict?: boolean; }>; prepare(input: { canvasId: string; sourceId?: string; }): Promise<{ ok: true; state: PreparationState; } | { ok: false; code: string; error: string; status: number; }>;}关联类型:CanvasSourceCatalogEntry · CanvasSourceListPage · PreparationState
成员说明:
listSources:活动来源目录(受认证)。listAccessible:某来源下主体可访问的来源作品分页(受认证)。status:无创建副作用的准备态查询。prepare:幂等触发在线迁移(显式用户动作)。
CanvasPreparationService
export interface CanvasPreparationService { getState(): CanvasPreparationState; subscribe(listener: () => void): () => void; listSources(force?: boolean): Promise<void>; listAccessible(input: { sourceId: string; cursor: string | null; limit?: number; }): Promise<{ items: SourceCanvasSummary[]; nextCursor: string | null; }>; prepare(input: { canvasId: string; sourceId?: string; }): Promise<void>; observe(input: { canvasId: string; signal?: AbortSignal; }): Promise<PreparationState>; dispose(): void;}关联类型:CanvasPreparationState · SourceCanvasSummary · PreparationState
成员说明:
listAccessible:某来源下主体可访问的来源作品分页(受认证;供切换器来源分区)。prepare:显式准备:POST prepare 并进入轮询(幂等)。observe:观察一个 canvasId 的准备态:先 GET status,未 ready 时按 pollAfterMs 轮询。 传入 generation/AbortSignal 以隔离迟到响应;dispose/切换后不再发布。
CanvasPreparationState
单 owner 轮询的准备态视图(App scope;切换画布时创建独立实例)。
export type CanvasPreparationState = { status: "idle" | "loading" | "preparing" | "ready" | "failed" | "deleted"; canvasId: string | null; jobId: string | null; phase: string | null; completedMedia: number; totalMedia: number; pollAfterMs: number; error: string | null; code: string | null; retryable: boolean; sources: CanvasSourceCatalogEntry[];};成员说明:
sources:已加载的来源目录(list 成功后)。
CanvasRecoveryService
显式 canvasId 不存在(或目录解析失败)时的恢复入口状态 。
只由 Canvas recovery page scope 提供:该 scope 不创建 Canvas Session/socket/Bevy, 仅展示稳定错误与「选择/创建画布」动作。
export type CanvasRecoveryService = { canvasId: string | null; code: string; error: string;};成员说明:
canvasId:用户显式请求但不存在/解析失败的 canvasId;目录解析失败时为 null。
CanvasSelectionService
最近画布选择(本地持久化,用于缺省 location 解析)。
export interface CanvasSelectionService { getRecentCanvasId(): string | null; setRecentCanvasId(canvasId: string | null): void;}CapabilityRegistration
一次能力注册。value 的形状由该 id + version 共同约定。
export type CapabilityRegistration = { id: string; version: number; value: unknown;};成员说明:
id:能力标识(kebab 或namespace:name形式,由各自的领域约定)。version:该能力对象的形状版本。同 id 不同 version 并存。value:能力对象本身;形状由消费方按 id + version 解释。
DEFAULT_TASK_NOTIFICATION_PREFERENCES
export const DEFAULT_TASK_NOTIFICATION_PREFERENCES: TaskNotificationPreferences;关联类型:TaskNotificationPreferences
成员说明:
titleEnabled:Web 标题渠道(默认开)。systemEnabled:Tauri 系统通知渠道(默认关;开启时才申请权限)。
ExtensionEngines
扩展声明的运行环境要求(extension.json 的 engines)。
export type ExtensionEngines = { readonly hostAbi: string; readonly sdkAbi: string; readonly protocolVersion: number;};成员说明:
hostAbi:宿主后端 SDK ABI 的 semver range。sdkAbi:浏览器 SDK ABI 的 semver range,与 browser artifact manifest 的sdkAbi对齐。
ExtensionExecutorEvent
export type ExtensionExecutorEvent = { type: string; payload?: unknown;};