跳转到内容

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

关联类型:TaskNotificationChannel

TaskNotificationPermission

系统通知权限的真实状态(与用户意愿分开)。

export type TaskNotificationPermission = "unknown" | "prompt" | "granted" | "denied" | "unsupported";