签名关联类型:NodeActionActivation – NodeRunStateProjection
本页由当前 SDK 声明自动生成。
NodeActionActivation · NodeActionContext · NodeActionContribution · NodeActionDescriptor · NodeActionSettingsProps · NodeCapabilities · NodeCapabilityContext · NodeCapabilityResolver · NodeGenerationHistoryDetail · NodeGenerationHistoryListItem · NodeGenerationHistoryListPage · NodeGenerationKind · NodeHistoryFailurePayload · NodeHistoryImageEditBaseMetadata · NodeHistoryKindCounts · NodeHistoryModelPlacement · NodeHistoryOutcome · NodeHistoryPreview · NodeHistoryPreviewEntry · NodeHistorySourceSummary · NodeModelPreparation · NodePreparationResult · NodeResourceContext · NodeRunStateProjection
NodeActionActivation
命中上下文:在显示上下文之上标明命中的是本体还是独立设置箭头,并提供宿主设置弹窗开启器。
横条与设置弹窗由 Web 宿主统一渲染(扩展自身的 <Popover> 只在聚焦
标题栏挂载)。因此贡献在一次点击无法直接开始、需要打开就近设置时 MUST 调用
requestSettings(),由宿主在节点锚点打开本贡献的 settings 弹窗;只写扩展内部瞬态
settingsOpen 在横条模式下没有任何渲染者。
export type NodeActionActivation = NodeActionContext & { menu: boolean; requestSettings: () => void;};关联类型:NodeActionContext
成员说明:
writable:单选节点当前是否可写(来自会话权限)。requestSettings:请求宿主打开本贡献的设置弹窗(menu: true命中已由宿主直接打开,无需再次调用)。
NodeActionContext
通用「选中节点操作」横条的贡献契约 。
横条由 Web 宿主统一渲染 DOM 按钮,runtime 提供 accepted 节点锚点。贡献提供:
describe:给出纯数据动作描述(文案、可用性、是否带设置箭头、模型名摘要);activate:命中后派发(menu: true表示命中独立设置箭头);settings(可选):点击设置箭头后在横条锚点打开的DOM 弹窗(复杂 UI 走 DOM)。
宿主只做通用描述收集、Web 渲染、动作派发与弹窗锚定,MUST NOT import 任何具体扩展实现
或按 film-set ID 分支。下载由宿主自己贡献(order: 0);film-set 通过同一 slot 贡献转换。
export type NodeActionContext = { nodeId: string; nodeType: string; writable: boolean;};成员说明:
writable:单选节点当前是否可写(来自会话权限)。
NodeActionContribution
export type NodeActionContribution = { id: string; owner: string; order: number; available?: (context: NodeActionContext) => boolean; describe: (context: NodeActionContext) => NodeActionDescriptor | null; activate: (activation: NodeActionActivation) => void; settings?: import("react").ComponentType<NodeActionSettingsProps>;};关联类型:NodeActionContext · NodeActionDescriptor · NodeActionActivation · NodeActionSettingsProps
成员说明:
id:贡献稳定 ID;同一 slot 内重复会启动失败。owner:拥有者(诊断用)。order:从左到右顺序。available:贡献是否在本节点可用;false 时不呈现。describe:纯数据动作描述;返回 null 表示本节点不呈现。activate:命中派发;menu为真表示命中独立设置箭头。settings:设置箭头的 DOM 弹窗内容(复杂 UI 走 DOM);缺省则menu动作不打开弹窗。
NodeActionDescriptor
一个动作的纯数据描述;null 表示当前不呈现该动作。
export type NodeActionDescriptor = { tone?: "primary" | "neutral"; icon?: "download" | "edit" | "box" | "arrange-horizontal" | "arrange-vertical" | "arrange-grid" | "arrange-diagonal-up" | "arrange-diagonal-down" | "collapse-groups" | "expand-groups" | "rotate-clockwise"; iconOnly?: boolean; label: string; enabled: boolean; reason?: string; menu?: boolean; summary?: string | null;};成员说明:
tone:通用动作强调与图标呈现。label:按钮文案(中文)。enabled:是否可用;false 时 Web 主按钮禁用,独立设置箭头仍可打开设置。reason:不可用原因(供 tooltip/诊断;无障碍不适用,仅用于呈现)。menu:是否在按钮后附加独立设置箭头(点击派发menu: true)。summary:横条左侧的节点摘要(可选)。
NodeActionSettingsProps
export type NodeActionSettingsProps = { nodeId: string; nodeType: string; writable: boolean; onClose: () => void;};成员说明:
nodeId:固定来源节点(激活时锁定,不随 selection 变化)。onClose:关闭弹窗(宿主管理开关与锚点)。
NodeCapabilities
export type NodeCapabilities = { appearance?: Readonly<{ palette: BevyNodeKind; defaultSize: Readonly<{ width: number; height: number; }>; cardLabel?: string; }>; modelPreparation?: NodeModelPreparation; connections?: { endpoints(context: NodeCapabilityContext): 'ordinary' | 'none' | 'aggregate'; }; resources?: { channel: 'image' | 'video' | 'model'; contentKey(context: NodeResourceContext): string | null; }; focus?: { kind(context: NodeCapabilityContext): 'model' | 'extension' | null; }; resize?: { mode: 'rect' | 'scope'; minimum(context: NodeCapabilityContext): { width: number; height: number; }; }; actions?: { accepts(context: NodeCapabilityContext): boolean; };};关联类型:BevyNodeKind · NodeModelPreparation · NodeCapabilityContext · NodeResourceContext
NodeCapabilityContext
export type NodeCapabilityContext = { canvas: ServerCanvas; node: ServerCanvas['document']['nodes'][number]; data: CanvasNodeData | undefined;};关联类型:ServerCanvas · CanvasNodeData
NodeCapabilityResolver
export interface NodeCapabilityResolver { resolve(context: NodeCapabilityContext): ResolvedNodeCapabilities; getRevision(): number;}关联类型:NodeCapabilityContext · ResolvedNodeCapabilities
NodeGenerationHistoryDetail
详情:按 entryId 按需读取的完整内容。
export type NodeGenerationHistoryDetail = { entryId: string; kind: "text"; text: string;} | { entryId: string; kind: "image" | "video" | "audio" | "motion"; storageKey: string; checksum: string; contentType: string; size: number; durationSeconds?: number; fps?: number; motion?: SomaMotionMetadata; poster?: { storageKey: string; checksum: string; contentType: string; size: number; }; base?: NodeHistoryImageEditBaseMetadata; imageEdit?: ImageEditDocument; project?: ImageEditProjectObjectRef;} | { entryId: string; kind: "model"; modelScript: string; language: string; version: string; sourceHash: string; placement?: NodeHistoryModelPlacement;} | { entryId: string; kind: "failure"; outcome: Exclude<NodeHistoryOutcome, "succeeded">; failureKind: NodeGenerationKind; message: string; code?: string; inputSummary: string; baseline: NodeHistoryFailurePayload["baseline"];};关联类型:SomaMotionMetadata · NodeHistoryImageEditBaseMetadata · ImageEditDocument · ImageEditProjectObjectRef · NodeHistoryModelPlacement · NodeHistoryOutcome · NodeGenerationKind · NodeHistoryFailurePayload
NodeGenerationHistoryListItem
列表项:只含卡片所需的安全 metadata。
export type NodeGenerationHistoryListItem = { entryId: string; kind: NodeGenerationKind; createdAt: string; outcome?: NodeHistoryOutcome; current: boolean; recoverable: boolean; previewable: boolean; source: NodeHistorySourceSummary; preview: NodeHistoryPreview;};关联类型:NodeGenerationKind · NodeHistoryOutcome · NodeHistorySourceSummary · NodeHistoryPreview
成员说明:
outcome:版本结果语义。 缺省视为succeeded(兼容旧条目与既有 fixture)。current:是否与节点当前生效输出一致(由权威回流判定,绝不本地猜测)。失败记录恒为 false。recoverable:引用内容是否仍可解析(媒体缺失 / 脚本失效时为 false)。失败归档恒为 false。previewable:预览是否可用(缩略图/媒体缺失时为 false,不影响列表与恢复)。
NodeGenerationHistoryListPage
export type NodeGenerationHistoryListPage = { items: NodeGenerationHistoryListItem[]; nextCursor: string | null; total: number;};关联类型:NodeGenerationHistoryListItem
成员说明:
nextCursor:下一页 opaque cursor;null 表示已到末尾。
NodeGenerationKind
export type NodeGenerationKind = (typeof NODE_GENERATION_KINDS)[number];NodeHistoryFailurePayload
失败/取消/中断版本 payload 。
保留提交时的基线内容引用(用于“恢复执行前内容”)、安全输入摘要和失败详情。MUST NOT
包含伪造产物、错误对象或媒体 bytes。baseline.identity 为提交时节点当前内容 identity;
baseline.entryId(若有)指向对应的既有可恢复版本,供 UI 提供显式恢复。
export type NodeHistoryFailurePayload = { kind: "failure"; outcome: Exclude<NodeHistoryOutcome, "succeeded">; failureKind: NodeGenerationKind; message: string; code?: string; baseline: { identity: string; nodeType: string; entryId?: string; outputAssetId?: string; } | null; inputSummary: string;};关联类型:NodeHistoryOutcome · NodeGenerationKind
成员说明:
failureKind:该失败操作本应产生的历史种类。message:安全错误摘要(不含堆栈/凭据/本机路径)。code:稳定错误码(若有)。inputSummary:安全输入摘要(有界,不含完整 prompt/凭据)。
NodeHistoryImageEditBaseMetadata
图片编辑版本的原图稳定 metadata(不复制源像素)。
export type NodeHistoryImageEditBaseMetadata = { baseAssetId: string; storageKey: string; checksum: string; contentType: string; size: number; sourceWidth: number; sourceHeight: number;};NodeHistoryKindCounts
按内容种类的条目计数。
export type NodeHistoryKindCounts = Record<NodeGenerationKind, number>;关联类型:NodeGenerationKind
NodeHistoryModelPlacement
模型摆放(与 modelPlacement 同构);编辑历史留档用。
export type NodeHistoryModelPlacement = { offset: { x: number; y: number; z: number; }; scale: number; yaw: number;};NodeHistoryOutcome
export type NodeHistoryOutcome = (typeof NODE_HISTORY_OUTCOMES)[number];NodeHistoryPreview
受控预览引用。
图片/视频/音频只给条目作用域的受控 href;文本给安全截断摘要;模型给条目身份 ——模型缩略图由页面内同一 Bevy 运行时按权威脚本一次性离屏渲染 。
export type NodeHistoryPreview = { kind: "text"; excerpt: string;} | { kind: "image"; href: string;} | { kind: "video"; href: string; posterHref: string | null; durationSeconds: number | null;} | { kind: "audio"; href: string; durationSeconds: number | null;} | { kind: "motion"; href: string; durationSeconds: number | null; fps: number; motion: SomaMotionMetadata;} | { kind: "model"; entry: NodeHistoryPreviewEntry;} | { kind: "failure"; outcome: Exclude<NodeHistoryOutcome, "succeeded">; message: string;};关联类型:SomaMotionMetadata · NodeHistoryPreviewEntry · NodeHistoryOutcome
NodeHistoryPreviewEntry
模型预览的条目身份:渲染器按它读取权威脚本并缓存结果。
export type NodeHistoryPreviewEntry = { canvasId: string; nodeId: string; entryId: string;};NodeHistorySourceSummary
列表项里的安全来源摘要(不含正文/storageKey/完整脚本)。
export type NodeHistorySourceSummary = { label: string; runId?: string; taskKey?: string; providerTaskId?: string; modelId?: string; sourceHash?: string; durationSeconds?: number;};成员说明:
taskKey:这次生成对应的 Task worker key。 providerTaskId 历史上填的是 canvas jobId,语义容易误读;溯源一律以本字段为准。
NodeModelPreparation
export type NodeModelPreparation = { executionKey(context: NodeCapabilityContext): string | undefined; prepare(context: NodeCapabilityContext): NodePreparationResult | Promise<NodePreparationResult>; reportsStatus?: boolean;};关联类型:NodeCapabilityContext · NodePreparationResult
成员说明:
reportsStatus:Whether the outcome becomes canonical model-script status (modelScriptStatus). Presentation-only resources — such as a group’s own appearance — passfalse: they are never model tasks and must not write task state into nodeData.
NodePreparationResult
export type NodePreparationResult = { resource?: PreparedModelResource; diagnostic?: string; status: string; release?: () => void;};成员说明:
release:Optional ownership-specific resource cleanup, including discarded late results.
NodeResourceContext
export type NodeResourceContext = NodeCapabilityContext & { modelResourceKey: string | null; assetContentKey: string | null;};NodeRunStateProjection
投影输入(有界):每个节点一条摘要 + 每个操作一条记录 + 当前版本操作身份。
export type NodeRunStateProjection = { summaries: readonly CanvasNodeRunSummary[]; records: readonly CanvasOperationRecord[]; currentOperationByNode?: ReadonlyMap<string, string>; versionsByNode?: ReadonlyMap<string, readonly NodeGenerationHistoryListItem[]>; selectedByNode?: ReadonlyMap<string, string>; unseenByNode?: ReadonlyMap<string, ReadonlySet<string>>;};关联类型:CanvasNodeRunSummary · CanvasOperationRecord · NodeGenerationHistoryListItem
成员说明:
unseenByNode:nodeId → 尚未查看的历史 entryId;只作为圆点角标提示,不改变选中/当前语义。