跳转到内容

后端 web-contracts-src-extension-services: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[];
};

关联类型: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;
};