跳转到内容

签名关联类型: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 — pass false: 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;
};

关联类型:PreparedModelResource

成员说明:

  • release:Optional ownership-specific resource cleanup, including discarded late results.

NodeResourceContext

export type NodeResourceContext = NodeCapabilityContext & {
modelResourceKey: string | null;
assetContentKey: string | null;
};

关联类型:NodeCapabilityContext

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;只作为圆点角标提示,不改变选中/当前语义。