后端 web-contracts-src-extension-services: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:直接读写 Nodereq/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。