后端 web-contracts-src-extension-services:MediaFormatRegistry – TaskNotificationPermission
本页由当前 SDK 声明自动生成。 导入入口:@woohaa3/contracts。
MediaFormatRegistry · MediaFormatValidator · PROMPT_REQUIREMENTS · PromptRequirement · ReleaseRef · StorageBackend · StorageBucket · StorageCurrentBackend · StorageExposeInput · StorageExposeRequest · StorageExposeUnavailableError · StorageExposer · StorageObject · StorageObjectNotFoundError · StorageObjectStat · StorageObjectStream · StorageProfile · StorageScope · TaskNotificationActions · TaskNotificationCategories · TaskNotificationChannel · TaskNotificationChannelState · TaskNotificationDelivery · TaskNotificationPermission
MediaFormatRegistry
export type MediaFormatRegistry = { register(format: MediaFormatValidator): () => void; get(contentType: string): MediaFormatValidator | undefined;};关联类型:MediaFormatValidator
MediaFormatValidator
A custom editable-media format is owned and verified by its installed extension.
export type MediaFormatValidator = { contentType: string; maxBytes: number; validate(bytes: Uint8Array, options: { maxBytes: number; }): Promise<void>;};PROMPT_REQUIREMENTS
模型级 prompt 要求(design D4):required 保持既有规则,optional/none 允许纯素材工作流。
export const PROMPT_REQUIREMENTS: readonly ["required", "optional", "none"];PromptRequirement
export type PromptRequirement = (typeof PROMPT_REQUIREMENTS)[number];关联类型:PROMPT_REQUIREMENTS
ReleaseRef
来源解析出的一个可安装版本。字段即后续 WooHaa3-server proto ResolveRelease 需要的最小集合。
export type ReleaseRef = { readonly sourceId: string; readonly extensionId: string; readonly version: string; readonly engines: ExtensionEngines; readonly packageDigest: string; readonly size: number; readonly dependencies?: Readonly<Record<string, string>>;};关联类型:ExtensionEngines
成员说明:
packageDigest:sha256:<hex>:整个.wxt包的摘要。来源的声明,下载后由 Manager 复核。dependencies:extensionId → semver range。
StorageBackend
export type StorageBackend = { readonly backendId: string; readonly label?: string; readonly ownerExtensionId?: string; readonly canvasScoped?: boolean; head(key: string, scope?: StorageScope): Promise<StorageObjectStat | null>; get(key: string, scope?: StorageScope): Promise<StorageObject>; openRead?(key: string, range?: { start: number; end: number; }, scope?: StorageScope): Promise<StorageObjectStream>; put(key: string, bytes: Uint8Array, contentType: string, scope?: StorageScope): Promise<void>; delete?(key: string, scope?: StorageScope): Promise<void>; presign?(key: string, options?: { expiresSeconds?: number; }, scope?: StorageScope): Promise<string>; putStream?(key: string, bytes: AsyncIterable<Uint8Array>, contentType: string, options: { size: number; signal?: AbortSignal; }, scope?: StorageScope): Promise<void>; readLocator?(locator: MediaLocator): Promise<StorageObject>; locatorOf?(key: string, scope?: StorageScope): Promise<MediaLocator | undefined>;};关联类型:StorageScope · StorageObjectStat · StorageObject · StorageObjectStream · MediaLocator
成员说明:
backendId:设置在storage.primary/storage.expose里引用的 id。label:设置页与日志里的显示名。ownerExtensionId:提供这个后端的插件 id(宿主扩展或站点扩展)。 设置页用它在「选哪个后端」旁边给出「打开该后端配置」的跳转;缺省时设置页只能按配置前缀猜, 站点扩展(没有配置前缀)会退化成「未找到提供者」。canvasScoped:声明这个后端承载画布托管存储(至多一个)。 归属远端的画布,字节就写在这个后端里;core 的路由不再硬编码任何后端 id, 只问「这张画布是否由画布托管后端承载」并在这里找到承载者——接入扩展换 id、 换实现都不用改 core。多个后端同时声明时按注册顺序取第一个并记告警; 都不声明时画布读写一律走高主存储(纯本地部署)。head:scope由 core 透传;不感知画布的后端可以忽略它。presign:就地产出外部地址(存量能力)。 存在即表示「这个后端自己能签」:ctx.exposer会先用它,不复制、不换后端。 不能就地签的后端不要实现它——需要异地转发的场景由ctx.exposer注册地址提供者。readLocator:按 locator 读字节(可跨后端)。 locator 是不透明串:只有产出它的后端知道怎么解析,实现内部完成授权与取数。 未实现表示该部署不支持按 locator 读取。locatorOf:给出某个稳定键对应的 locator(写完之后把「新位置」交回调用方)。 实现不了时返回 undefined:调用方据此知道结果不带定位符,而不是自己拼一个前缀。
StorageBucket
namespace 视图:使用方给 key,core 拼上 namespace,后端再加自己的前缀。
export type StorageBucket = { readonly namespace: string; readonly scope?: StorageScope; backendId(): string; head(key: string): Promise<StorageObjectStat | null>; get(key: string): Promise<StorageObject>; openRead?(key: string, range?: { start: number; end: number; }): Promise<StorageObjectStream>; put(key: string, bytes: Uint8Array, contentType: string): Promise<void>; putStream?(key: string, bytes: AsyncIterable<Uint8Array>, contentType: string, options: { size: number; signal?: AbortSignal; }): Promise<void>; delete?(key: string): Promise<void>;};关联类型:StorageScope · StorageObjectStat · StorageObject · StorageObjectStream
成员说明:
scope:视图绑定的画布作用域(缺省为无画布)。backendId:当前生效的后端 id;每次调用现查,画布路由与主存储切换后立即反映。
StorageCurrentBackend
当前作用域解析到的后端,以及它就地签名的能力(没有 presign 时为 undefined)。
export type StorageCurrentBackend = { readonly backendId: string; readonly presign?: (key: string, options?: { expiresSeconds?: number; }, scope?: StorageScope) => Promise<string>; readonly exposure?: string;};关联类型:StorageScope
成员说明:
exposure:画布记录里的地址提供者覆盖(未配置时为 undefined)。exposer用它决定这次用哪个提供者:有覆盖就用覆盖(空串表示这张画布明确不对外), 没有才回落部署默认。存储不解释这个值——它只回答「这张画布记了什么」。
StorageExposeInput
一次取地址请求:namespace 与 key 由使用方给,core 拼成对象键。
export type StorageExposeInput = { readonly namespace: string; readonly key: string; readonly scope?: StorageScope; readonly expiresSeconds?: number; readonly request?: StorageExposeRequest;};关联类型:StorageScope · StorageExposeRequest
成员说明:
request:本次请求的素材约束;自动路由据此排除不支持当前素材的临时图床。
StorageExposeRequest
一次请求的素材事实与有效窗口要求。
export type StorageExposeRequest = { readonly mediaKind?: string; readonly contentType?: string; readonly sizeBytes?: number; readonly requiredValiditySeconds?: number; readonly signal?: AbortSignal;};成员说明:
mediaKind:image/video/audio;缺省时由 contentType 推断。contentType:素材 MIME;缺省时由存储对象补齐。sizeBytes:素材字节数;缺省时由存储对象补齐。requiredValiditySeconds:外部任务还需要多久能读到该地址;无法满足时明确失败。signal:请求取消;已取消的请求直接失效,不参与回退。
StorageExposeUnavailableError
没有可用的对外地址:当前后端不能就地签名,也没有配置能出地址的提供者。
export class StorageExposeUnavailableError { constructor(message?: string); code: "STORAGE_EXPOSE_UNAVAILABLE"; name: string; message: string; stack?: string | undefined; cause?: unknown;}StorageExposer
一个对外地址提供者(扩展层插件注册)。
requiresReplica 是唯一的形态判据:
true:字节必须先落在targetBackendId(云端对象存储、服务端托管存储); core 在调用expose之前完成复制,缺对象时从来源读一次(内容寻址,复制幂等)。false:core 不复制,提供者自己把字节弄到该去的地方再给地址——它拿到的是 namespace/key/scope,可以自己去ctx.storage读。两种典型:CDN 回源签名(字节不动), 以及「公开临时桶」这类由提供者推送的目标。
没有临时图床声明的提供者只能被手动选择(兼容旧的 CDN / 服务端签名能力),自动模式不会 把它们排在提供商或内置临时图床前面。
export type StorageExposer = { readonly exposerId: string; readonly label?: string; readonly ownerExtensionId?: string; readonly requiresReplica: boolean; readonly targetBackendId?: string; readonly temporaryHosting?: TemporaryHostingDeclaration; expose(input: StorageExposeInput): Promise<string>;};关联类型:TemporaryHostingDeclaration · StorageExposeInput
成员说明:
exposerId:设置在exposer.primary(以及画布级exposure)里引用的 id。label:设置页与日志里的显示名。ownerExtensionId:提供这个提供者的插件 id(设置页据此跳转到它的配置)。requiresReplica:字节是否必须先在targetBackendId落地(判据见类型说明)。targetBackendId:requiresReplica为 true 时要复制到哪个后端;缺省与exposerId同名。temporaryHosting:临时图床声明;缺省表示只能手动选择。
StorageObject
export type StorageObject = { bytes: Uint8Array; contentType?: string;};StorageObjectNotFoundError
存储对象 not-found。与 MediaObjectNotFoundError 一样按字符串判定(跨 bundle 无法用 instanceof)。
export class StorageObjectNotFoundError { constructor(key: string); code: "STORAGE_OBJECT_NOT_FOUND"; key: string; name: string; message: string; stack?: string | undefined; cause?: unknown;}StorageObjectStat
export type StorageObjectStat = { size: number; contentType?: string;};StorageObjectStream
export type StorageObjectStream = { bytes: AsyncIterable<Uint8Array>; cancel(): void;};StorageProfile
一张画布的存储形态(画布记录级覆盖,字段级回落到部署默认)。
为什么按画布而不是按部署:同一台机器上可以既有纯本地画布、又有已转换到远端的画布。
为什么带默认值:绝大多数画布不写任何字段,直接继承 storage.primary / storage.expose;
只有确实需要的画布才留下一条覆盖记录。
export type StorageProfile = { readonly residency?: "primary" | "canvas-hosted"; readonly exposure?: string;};成员说明:
residency:字节落点角色。缺省继承部署主存储(storage.primary)。canvas-hosted由声明了canvasScoped的后端兑现——转换流程写入它,界面不提供「取消」: 一旦有字节写进托管存储,它就是事实,撤销要靠迁移而不是改配置。exposure:地址提供者 id(ctx.exposer的exposerId)。缺省继承storage.expose; 空串表示这张画布明确不对外。
StorageScope
画布作用域:一次读写属于哪张画布。
只有需要画布维度的后端会用它(服务端托管存储按 <canvasId>/<...> 拼键并按画布判权);
local / cos 忽略它,键布局与已存对象保持不变。使用方拿不到作用域语义,只负责把
「这次读写发生在哪张画布」透传下来。
export type StorageScope = { readonly canvasId: string;};TaskNotificationActions
具名操作(设置分区只调用这些,不直接改内部状态)。
export type TaskNotificationActions = { setCategory(category: keyof TaskNotificationCategories, enabled: boolean): void; setChannel(channel: TaskNotificationChannel, enabled: boolean): Promise<void>; requestPermission(): Promise<void>; sendTestNotification(): Promise<{ ok: true; } | { ok: false; error: string; }>; refreshPermission(): Promise<void>; clearPending(): void;};关联类型:TaskNotificationCategories · TaskNotificationChannel
成员说明:
requestPermission:用户主动申请 OS 通知权限(只在开启系统通知且未询问时调用)。sendTestNotification:用户主动发送测试通知(允许前台;不写入任务事实)。refreshPermission:重新读取外部权限变化(应用聚焦/重新进入分区)。clearPending:前台恢复:清除标题计数与未发送批次(不改变任务面板未读)。
TaskNotificationCategories
事件类别开关(成功 / 失败分开)。
export type TaskNotificationCategories = { succeeded: boolean; failed: boolean;};TaskNotificationChannel
平台呈现渠道。
export type TaskNotificationChannel = "title" | "system";TaskNotificationChannelState
渠道的运行状态(是否真的能发送,以及原因)。
export type TaskNotificationChannelState = { enabled: boolean; status: "ready" | "blocked" | "unsupported"; reason: string | null;};成员说明:
enabled:用户意愿开关。status:实际可用性:权限/平台能力。reason:面向用户的安全原因;ready 时为 null。
TaskNotificationDelivery
证据/诊断所需的最近一次提醒记录(有界,不含明文内容)。
export type TaskNotificationDelivery = { taskKey: string; state: "succeeded" | "failed"; attempt: number | null; channel: TaskNotificationChannel; at: number;};TaskNotificationPermission
系统通知权限的真实状态(与用户意愿分开)。
export type TaskNotificationPermission = "unknown" | "prompt" | "granted" | "denied" | "unsupported";