跳转到内容

后端 web-contracts-src-extension-service:HostGenerationService – MarketplaceSource

本页由当前 SDK 声明自动生成。 导入入口:@woohaa3/contracts。

返回接口索引

HostGenerationService · HostLog · HostLogService · HostMarketplaceService · HostMediaFormatService · HostServiceName · HostServiceRequirement · HostStorageService · HostTelemetryService · HostWebServerService · ImportAnchor · ImportBatchInput · ImportBatchResult · ImportItem · ImportItemStage · ImportService · ImportSource · ImportState · MarketplaceAvailability · MarketplaceDownload · MarketplaceListing · MarketplaceSearchPage · MarketplaceSearchQuery · MarketplaceSource

HostGenerationService

ctx.generation:生成 Provider 的注册面,Task 从这里读取。

服务形状在这里定义,本机宿主的生成模块实现注册表;Provider / 转换提供方契约与它同属这个 服务(见上),不再散落在后端目录里。

export type HostGenerationService = {
register(provider: GenerationProvider): () => void;
unregister(providerId: string): void;
list(): readonly GenerationProvider[];
resolve(providerId: string): GenerationProvider | undefined;
policySnapshot?(): GenerationModelPolicySnapshot;
};

关联类型:GenerationProvider · GenerationModelPolicySnapshot

成员说明:

  • register:注册 Provider;返回注销函数(插件放进 ctx.effect,卸载时自动注销)。
  • list:注册「转为片场」转换提供方;返回注销函数。
  • policySnapshot:本机模型启停策略的只读快照(可选能力)。 为什么扩展需要它:任何把上游模型目录投影给用户的地方(例如远端助手的连接视图) 都必须与设置页的启停开关给出同一个答案。只读上游 /v1/models 会让用户在下拉里 看到自己关掉的模型——那不是“目录不全”,而是两个界面说了相反的话。 只读且不初始化:返回 initialized=false 表示策略库还没有任何行,调用方按 「未初始化 = 全开」处理(与 catalog 同一语义)。旧宿主没有这个方法时同样按全开。

HostLog

ctx.log:结构化日志出口。

服务契约在这里定义,本机宿主(源码声明)实现并在装载时注入。扩展只依赖这份 类型,不 import 宿主实现;宿主侧的 log 服务必须满足这里的形状。

export type HostLog = (event: Record<string, unknown>) => void;

HostLogService

export type HostLogService = {
scope(module: string): HostLog;
};

关联类型:HostLog

成员说明:

  • scope:带 module 字段的结构化日志出口。

HostMarketplaceService

ctx.marketplace:市场来源注册面。

export type HostMarketplaceService = {
register(source: MarketplaceSource): () => void;
unregister(sourceId: string): void;
list(): readonly MarketplaceSource[];
resolve(sourceId: string): MarketplaceSource | undefined;
};

关联类型:MarketplaceSource

成员说明:

  • register:注册来源;重复 sourceId 抛错。返回注销函数。

HostMediaFormatService

扩展可用的媒体格式注册面(ctx.mediaFormats)。

与 MediaFormatRegistry 的区别:这是按 extensionId 记账的窄端口;宿主在插件停用/回滚时 自动注销注册,扩展不需要自己找 registry,也不能注销别的扩展的格式。

export type HostMediaFormatService = {
register(format: MediaFormatValidator): () => void;
};

关联类型:MediaFormatValidator

HostServiceName

export type HostServiceName = keyof typeof HOST_SERVICE_ABI;

关联类型:HOST_SERVICE_ABI

HostServiceRequirement

服务面名 → 所需(或宿主提供)的整数版本。

export type HostServiceRequirement = Readonly<Record<string, number>>;

HostStorageService

ctx.storage:存储后端的注册面与使用方入口。与 ctx.generation 同形。

export type HostStorageService = {
register(backend: StorageBackend): () => void;
unregister(backendId: string): void;
list(): readonly StorageBackend[];
resolve(backendId: string): StorageBackend | undefined;
bucket(namespace: string, scope?: StorageScope): StorageBucket;
current(namespace: string, scope?: StorageScope): StorageCurrentBackend;
replicate(namespace: string, key: string, options: {
targetBackendId: string;
scope?: StorageScope;
sourceBackendId?: string;
}): Promise<boolean>;
readLocator(locator: MediaLocator): Promise<StorageObject>;
primaryId(): string;
readiness(): {
ready: boolean;
reason?: string;
};
};

关联类型:StorageBackend · StorageScope · StorageBucket · StorageCurrentBackend · MediaLocator · StorageObject

成员说明:

  • register:注册后端;返回注销函数(插件放进 ctx.effect,卸载时自动注销)。
  • bucket:使用方入口:每次调用现查当前后端。 带 scope 时先按画布记录路由,未命中再回落主存储; 不带 scope 时行为与旧版一致(只看 storage.primary)。
  • current:当前作用域会落到哪个后端、能否就地签。 只给 ctx.exposer 用:它要决定「直接签」还是「复制到提供者再签」,但不该看到后端对象。 主存储未注册时抛与读写同一条错误。
  • replicate:把对象复制到指定后端(画布资产补传/回填用)。 目标已有同一对象时直接返回 false(内容寻址,复制幂等);来源与目标相同时也返回 false。仅当真的写入目标后端时返回 true。 sourceBackendId 缺省取「带 scope 时的路由后端、否则主存储」;回填存量资产时要显式给 主存储,因为路由到远端后它已经不含旧对象。
  • readLocator:按 locator 读字节:解析出 backendId,交给对应后端的 readLocator。 这是 locator 的唯一解析入口:使用方永远不该自己拆 media://...。 后端没实现或 locator 不属于任何已注册后端时报错(显式失败,不回落主存储)。
  • primaryId:设置 storage.primary 的值(缺省 local)。
  • readiness:就绪只看主存储:主存储后端没注册即未就绪。

HostTelemetryService

ctx.telemetry:采集、查询与复盘入口。

与 ctx.generation / ctx.storage 同形的注册面(register/unregister/list/resolve), 但没有 primaryId/exposeId/readiness:遥测不是“选一个目的地”,而是“本地一定记, 出口可以有零到多个”;它也不参与启动就绪(存储坏了业务仍必须可用)。

export type HostTelemetryService = {
emit(input: TelemetryEventInput): void;
query(filter?: TelemetryEventFilter): Promise<TelemetryEventPage>;
summary(window: TelemetryWindow, bucket?: TelemetryBucket, options?: TelemetryReadOptions): Promise<TelemetrySummary>;
anomalies(window: TelemetryWindow, options?: TelemetryReadOptions): Promise<readonly TelemetryAnomaly[]>;
registerExport(provider: TelemetryExport): () => void;
unregisterExport(exportId: string): void;
listExports(): readonly TelemetryExport[];
status(): Promise<TelemetryStatus>;
clear(): Promise<number>;
flush(): Promise<void>;
close(): void;
};

关联类型:TelemetryEventInput · TelemetryEventFilter · TelemetryEventPage · TelemetryWindow · TelemetryBucket · TelemetryReadOptions · TelemetrySummary · TelemetryAnomaly · TelemetryExport · TelemetryStatus

成员说明:

  • emit:发一条事实。同步入队后立即返回,绝不抛错、绝不阻塞。 非法输入被丢弃并计入 droppedInvalid;队列满时丢最旧并计入 droppedOverflow。调用点 可以无脑调用,不需要 try/catch,也不需要等待。
  • query:事件列表:最新在前、游标分页。
  • summary:窗口聚合:每个事件名的计数/结果分布/分位数/高频错误码,外加时间序列。 options.groupBy 给出时行变成「事件名 × 属性值」组,返回的 TelemetrySummary.groupBy 会带上 该键;分组行的计数与分位数只统计组内样本。options.attributeKey/attributeValue 是筛选, 用来把不同构建模式的样本分开算(spec:按 production 筛选的分布不含 dev 样本)。
  • anomalies:当前窗口命中的异常(确定性规则,见 design D6);groupBy 让规则按输入种类/阶段分组。
  • registerExport:注册一个出口;返回注销函数(站点扩展放进自己的回滚路径)。
  • status:复盘页与设置面用的只读状态快照。
  • clear:清空本地记录(保留期之外的清理不受影响);返回删除条数。
  • flush:把队列里的事件写盘。测试与进程退出时用;业务路径不应等待它。
  • close:关闭存储与定时器;由宿主 effect 在卸载时调用。

HostWebServerService

export type HostWebServerService = {
register(registration: ApplicationBackendHandlerRegistration): void;
registerHttp(registration: ApplicationBackendHttpHandlerRegistration): void;
registerRawHttp(registration: ApplicationBackendRawHttpHandlerRegistration): void;
};

关联类型:ApplicationBackendHandlerRegistration · ApplicationBackendHttpHandlerRegistration · ApplicationBackendRawHttpHandlerRegistration

成员说明:

  • register:受控 JSON handler:路由 + 处理函数,宿主统一分派并序列化结果。
  • registerHttp:HTTP handler:可设置状态码与响应头。
  • registerRawHttp:原始 HTTP handler:直接读写 Node req/res(重定向、HTML、SSE)。

ImportAnchor

本地文件导入 capability 契约(Media Import / Paste Import 提供)。 从 contracts.ts façade 拆分。

export type ImportAnchor = {
world: {
x: number;
y: number;
z?: number;
} | null;
connectFrom?: {
nodeId: string;
nodeType: string;
};
};

ImportBatchInput

一次批量导入请求:文件选择、paste、drop 复用同一 coordinator。

export type ImportBatchInput = {
files: readonly File[];
anchor: ImportAnchor;
source: ImportSource;
selectedNodeIds: readonly string[];
};

关联类型:ImportAnchor · ImportSource

ImportBatchResult

export type ImportBatchResult = {
ok: boolean;
succeeded: number;
failed: number;
items: readonly ImportItem[];
};

关联类型:ImportItem

ImportItem

export type ImportItem = {
id: string;
name: string;
kind: "image" | "video" | "audio" | "text" | "model3d" | null;
size: number;
stage: ImportItemStage;
error?: string;
nodeId?: string;
};

关联类型:ImportItemStage

成员说明:

  • id:稳定 item/operation identity;迟到异步结果据此忽略。
  • error:安全错误摘要(不含 URL、授权信息或完整正文)。
  • nodeId:提交成功后的新节点 ID。

ImportItemStage

逐文件导入阶段;失败阶段用于精确诊断。

export type ImportItemStage = "pending" | "reading" | "hashing" | "uploading" | "submitting" | "done" | "failed" | "cancelled";

ImportService

本地文件导入(feature-owned capability;复用 Media Remote 与 Canvas Session)。

export interface ImportService {
requestFile(anchor: ImportAnchor): void;
requestFiles(anchor: ImportAnchor): void;
importBatch(input: ImportBatchInput): Promise<ImportBatchResult>;
retryItem(itemId: string): Promise<{
ok: boolean;
error?: string;
}>;
replaceSelectedImage(input: {
file: File;
nodeId: string;
}): Promise<{
ok: boolean;
error?: string;
}>;
getState(): ImportState;
subscribe(listener: () => void): () => void;
}

关联类型:ImportAnchor · ImportBatchInput · ImportBatchResult · ImportState

成员说明:

  • requestFile:打开单选文件选择器;选中后走批量 coordinator。
  • requestFiles:打开可多选文件选择器;选中后走 importBatch。
  • importBatch:批量 coordinator:逐文件独立原子提交,允许部分成功。
  • retryItem:用当前页面存活期的 File 重试单个失败项。
  • replaceSelectedImage:单图替换:上传新图片后以一个批次 upsert 资产并 patch 目标节点。

ImportSource

导入入口来源(picker 右键上传 / clipboard paste / 拖放)。

export type ImportSource = "picker" | "paste" | "drop";

ImportState

export type ImportState = {
uploading: boolean;
error: string | null;
items: readonly ImportItem[];
};

关联类型:ImportItem

成员说明:

  • items:最近一次批量结果(逐项状态);无则为空数组。

MarketplaceAvailability

export type MarketplaceAvailability = {
readonly ok: true;
} | {
readonly ok: false;
readonly reason: string;
};

MarketplaceDownload

export type MarketplaceDownload = {
readonly stream: ReadableStream<Uint8Array>;
readonly size: number;
};

MarketplaceListing

export type MarketplaceListing = {
readonly extensionId: string;
readonly label: string;
readonly description?: string;
readonly latest: string;
readonly icon?: string;
readonly size?: number;
readonly publishedAt?: string;
readonly hotReload?: boolean;
};

成员说明:

  • size:最新版本大小(字节)。来源能给出时展示在卡片上;给不出就不显示,不估算。 GitHub Release 取最新版本的资产大小;本部署市场当前只在版本详情里给。
  • publishedAt:最新版本的发布时间(ISO 8601)。来源不提供时缺省,界面不猜测。
  • hotReload:安装后是否热加载(无需重启宿主)。只有来源明确声明时才带; 缺省表示未知,界面不显示该标签。

MarketplaceSearchPage

export type MarketplaceSearchPage = {
readonly items: readonly MarketplaceListing[];
readonly nextCursor?: string;
};

关联类型:MarketplaceListing

MarketplaceSearchQuery

export type MarketplaceSearchQuery = {
readonly text?: string;
readonly cursor?: string;
readonly limit?: number;
};

MarketplaceSource

一个市场来源。由内置根扩展在 apply 里经 ctx.marketplace.register 注册(放进 ctx.effect)。

export type MarketplaceSource = {
readonly sourceId: string;
readonly label: string;
available(): MarketplaceAvailability;
search(query: MarketplaceSearchQuery, signal: AbortSignal): Promise<MarketplaceSearchPage>;
resolve(extensionId: string, range: string, signal: AbortSignal): Promise<ReleaseRef | null>;
download(ref: ReleaseRef, signal: AbortSignal): Promise<MarketplaceDownload>;
};

关联类型:MarketplaceAvailability · MarketplaceSearchQuery · MarketplaceSearchPage · ReleaseRef · MarketplaceDownload

成员说明:

  • resolve:按 semver range 解析一个版本;没有匹配返回 null。