跳转到内容

后端 web-contracts-src-backend:BackendAgentCanvasPort – ChatGptProgressEvent

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

返回接口索引

BackendAgentCanvasPort · BackendCanvasMcpPort · BackendMediaPort · BackendModule · BackendTaskPort · BackendWorldAuthoringPort · CHATGPT_AUTH_STATES · CHATGPT_GENERATION_MODES · CHATGPT_REASONING_EFFORTS · CHATGPT_ROUTES · CanvasAuthority · CanvasAuthorityResult · ChatGptAccountView · ChatGptAuthSnapshot · ChatGptAuthState · ChatGptAuthorizeCompleteResponse · ChatGptAuthorizeStartResponse · ChatGptGenerateAccepted · ChatGptGenerateRequest · ChatGptGenerationMode · ChatGptGenerationReceipt · ChatGptModelView · ChatGptModelsSnapshot · ChatGptProgressEvent

BackendAgentCanvasPort

MCP -> Canvas Agent authoring 进程内契约(替代 AgentCanvasClient 的网络实现)。

方法体为稳定的结构化输入/输出;具体 DTO 由 Canvas agent-authoring 面在 contracts 中声明, 调用方按已知形状窄化。

export type BackendAgentCanvasPort = {
listCanvases(input: {
canvasId?: string;
cursor?: string;
limit?: number;
}): Promise<unknown>;
getGraph(input: {
canvasId?: string;
nodeIds?: readonly string[];
aroundNodeId?: string;
depth?: number;
includePrompt?: boolean;
limit?: number;
cursor?: string;
}): Promise<unknown>;
getChanges(input: {
canvasId?: string;
sinceRevision: number;
limit?: number;
}): Promise<unknown>;
applyPlan(input: unknown): Promise<unknown>;
runNode?(input: unknown): Promise<unknown>;
getRun?(input: {
canvasId?: string;
nodeId: string;
runId: string;
waitMs?: number;
}): Promise<unknown>;
cancelRun?(input: {
canvasId?: string;
nodeId: string;
runId: string;
}): Promise<unknown>;
getOutput?(input: {
canvasId?: string;
nodeId: string;
runId: string;
}): Promise<unknown>;
};

BackendCanvasMcpPort

MCP -> Canvas 进程内契约(替代 CanvasMcpClient 的网络实现)。

结果类型由 Canvas MCP 面在 contracts 中声明;这里只保留最小方法集,避免把 Canvas 实现 导入 MCP 模块。具体结果类型用 unknown 别名在此模块由调用方窄化(调用方知道期望形状)。

export type BackendCanvasMcpPort = {
listModelNodes(input: {
canvasId?: string;
}): Promise<unknown>;
getModelNode(input: {
canvasId: string;
nodeId: string;
}): Promise<unknown>;
submitScript(input: {
canvasId: string;
nodeId: string;
source: string;
version?: number;
}): Promise<unknown>;
renderPreview(input: {
canvasId: string;
nodeId: string;
width?: number;
height?: number;
background?: string;
cameraPreset?: string;
}): Promise<unknown>;
applyCommands(input: {
canvasId: string;
commandId: string;
baseRevision: number;
commands: readonly unknown[];
}): Promise<unknown>;
mutateCameras(input: {
canvasId: string;
nodeId: string;
requestId: string;
mutation: unknown;
}): Promise<unknown>;
ready(): Promise<{
ready: boolean;
reason?: string;
}>;
};

BackendMediaPort

Canvas/Task -> Media 进程内契约(替代 Media client 的网络实现)。

export type BackendMediaPort = {
resources?: ApplicationExtensionMediaResourcesFacade;
verify(storageKey: string, expected?: Partial<Omit<MediaMetadata, "storageKey">>, scope?: MediaStorageScope): Promise<{
exists: boolean;
matches: boolean;
metadata?: MediaMetadata;
}>;
sign(storageKey: string, expiresSeconds?: number, scope?: MediaStorageScope): Promise<string>;
importFromUrl(input: {
url: string;
contentType?: string;
maxBytes?: number;
canvasId?: string;
}): Promise<MediaMetadata>;
importBytes(input: {
bytesBase64: string;
contentType: string;
maxBytes?: number;
canvasId?: string;
}): Promise<MediaMetadata>;
importFromLocator(input: {
locator: MediaLocator;
canvasId?: string;
contentType?: string;
maxBytes?: number;
expected?: {
contentType?: string;
size?: number;
checksum?: string;
};
}): Promise<MediaMetadata>;
};

关联类型:ApplicationExtensionMediaResourcesFacade · MediaMetadata · MediaStorageScope · MediaLocator

成员说明:

  • resources:有界、内容寻址的进程内资源读写;不暴露存储驱动。
  • verify:核验稳定对象是否存在且 metadata 一致。 scope 用于把「属于哪张画布」透传给存储层:远端画布的资产可能只在服务端托管存储里, 不带作用域会退化成只查主存储。省略时保持旧行为(只看主存储)。
  • importFromLocator:按 locator 导入:字节可能在任何后端(含服务端),由存储层内部取数并落到目标位置。 幂等(内容寻址去重);失败必须显式失败,不得回落成签名地址下载——那会把一个 根因报成两个不相干的错误。

BackendModule

一个后端模块对统一进程暴露的最小契约(生命周期 + HTTP 面)。

export type BackendModule = {
handle: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse) => Promise<boolean>;
readiness: () => Promise<{
ready: boolean;
reason?: string;
}>;
close: () => Promise<void>;
};

BackendTaskPort

Canvas -> Task 进程内契约(替代 CanvasTaskClient 的网络实现)。

export type BackendTaskPort = {
extensionTasks?: (extensionId: string, configVersion: number) => ApplicationExtensionTaskFacade;
submit(request: TaskSubmitRequest): Promise<TaskSubmitResponse>;
cancel(workerTaskKey: string): Promise<void>;
status(workerTaskKey: string): Promise<TaskExecutionDetail | null>;
history(query: {
after?: number;
limit?: number;
}): Promise<{
items: TaskExecutionDetail[];
cursor: number;
}>;
canvasActivity(canvasId: string, query?: {
cursor?: string;
limit?: number;
}): Promise<CanvasTaskActivitySnapshot>;
canvasActivitySince(canvasId: string, after: number, limit?: number): Promise<CanvasTaskActivityEventBatch>;
canvasActivityChanges(canvasId: string, after: number, limit?: number): Promise<CanvasTaskActivityEventBatch>;
};

关联类型:ApplicationExtensionTaskFacade · TaskSubmitRequest · TaskSubmitResponse · TaskExecutionDetail · CanvasTaskActivitySnapshot · CanvasTaskActivityEventBatch

成员说明:

  • extensionTasks:按可信扩展及不可变配置版本裁剪的非画布任务端口。

BackendWorldAuthoringPort

Scene-area authority port (T06).

Every write method runs through the real CanvasRoom serial queue; preparation only reads the canonical projection. issueContext returns the public WorldToolContext while the process-local write capability stays in the host.

export type BackendWorldAuthoringPort = {
prepare(input: {
canvasId: string;
areaId: string;
}, options?: {
signal?: AbortSignal;
}): Promise<WorldAuthoringPrepareOutcome>;
issueContext(input: WorldToolContextRequest, options?: {
signal?: AbortSignal;
}): Promise<WorldToolContextOutcome>;
revokeContext(input: WorldToolContextRevokeInput): Promise<void>;
execute(input: WorldAuthoringExecuteInput, options?: {
authorize?: () => Promise<boolean>;
signal?: AbortSignal;
}): Promise<WorldAuthoringExecuteOutcome>;
listResourceEdits(input: {
canvasId: string;
runId: string;
}): Promise<{
ok: true;
commands: Array<{
commandId: string;
revision: number;
}>;
} | WorldAuthoringFailure>;
replayResourceEdit(input: {
canvasId: string;
sourceCommandId: string;
previousCommandId: string;
operationId: string;
direction: "undo" | "redo";
}, options?: {
authorize?: () => Promise<boolean>;
signal?: AbortSignal;
}): Promise<{
ok: true;
commandId: string;
revision: number;
duplicate: boolean;
} | WorldAuthoringFailure>;
undo(input: WorldAuthoringHistoryInput, options?: {
authorize?: () => Promise<boolean>;
signal?: AbortSignal;
}): Promise<WorldAuthoringHistoryOutcome>;
redo(input: WorldAuthoringHistoryInput, options?: {
authorize?: () => Promise<boolean>;
signal?: AbortSignal;
}): Promise<WorldAuthoringHistoryOutcome>;
};

关联类型:WorldAuthoringPrepareOutcome · WorldToolContextRequest · WorldToolContextOutcome · WorldToolContextRevokeInput · WorldAuthoringExecuteInput · WorldAuthoringExecuteOutcome · WorldAuthoringFailure · WorldAuthoringHistoryInput · WorldAuthoringHistoryOutcome

CHATGPT_AUTH_STATES

个人授权状态机(design D3)。

  • disconnected:没有凭据;
  • authorizing:存在未完成事务;
  • connected-without-plan:身份已登录但缺少订阅使用 scope,生成不可用;
  • ready:有效 access token 且含订阅 scope,可生成;
  • reauthorization-required:续期失败/权限缺失/主体变化,需重新授权。
export const CHATGPT_AUTH_STATES: readonly ["disconnected", "authorizing", "connected-without-plan", "ready", "reauthorization-required"];

CHATGPT_GENERATION_MODES

生成目标模式(片场与模型镜头生成已下线)。

export const CHATGPT_GENERATION_MODES: readonly ["model3d"];

CHATGPT_REASONING_EFFORTS

应用支持的思考强度;省略参数时沿用模型默认配置。

export const CHATGPT_REASONING_EFFORTS: readonly ["low", "medium", "high", "xhigh", "max", "ultra"];

CHATGPT_ROUTES

同源路由后缀(相对 base path)。

export const CHATGPT_ROUTES: { readonly status: "status"; readonly authorizeStart: "authorize/start"; readonly authorizeCancel: "authorize/cancel"; readonly authorizeComplete: "authorize/complete"; readonly disconnect: "disconnect"; readonly models: "models"; readonly generate: "generate"; readonly cancel: "cancel"; readonly events: "events"; };

CanvasAuthority

export type CanvasAuthority = {
exportCanvas(): {
ok: true;
canvas: ServerCanvas;
} | {
ok: false;
message: string;
};
submit(batch: CanvasCommandBatch): Promise<CanvasAuthorityResult>;
submitDerived(input: {
commandId: string;
derive(canvas: ServerCanvas): {
ok: true;
batch: CanvasCommandBatch;
} | {
ok: false;
code: string;
message: string;
};
}): Promise<CanvasAuthorityResult>;
};

关联类型:ServerCanvas · CanvasCommandBatch · CanvasAuthorityResult

CanvasAuthorityResult

export type CanvasAuthorityResult = {
ok: true;
status: "accepted" | "duplicate";
commandId: string;
revision: number;
noop: boolean;
} | {
ok: false;
code: string;
message: string;
};

ChatGptAccountView

展示用账户信息:绝不包含 token。

export type ChatGptAccountView = {
email?: string;
subject?: string;
connectedAt?: string;
};

成员说明:

  • subject:经过验证的 ChatGPT subject;仅用于展示/核验,不用于选择 owner。

ChatGptAuthSnapshot

授权状态快照(公开面:绝不含 token)。

export type ChatGptAuthSnapshot = {
state: ChatGptAuthState;
planEnabled: boolean;
account?: ChatGptAccountView;
localSession: boolean;
ownerKind: "principal" | "local-session";
message?: string;
};

关联类型:ChatGptAuthState · ChatGptAccountView

成员说明:

  • localSession:本地开发会话模式(无应用登录);用于文案提示,不改变 owner 选择规则。
  • ownerKind:当前生效的授权场景:应用用户或本地会话。
  • message:可读的最近错误(不含 token)。

ChatGptAuthState

export type ChatGptAuthState = (typeof CHATGPT_AUTH_STATES)[number];

关联类型:CHATGPT_AUTH_STATES

ChatGptAuthorizeCompleteResponse

授权回执:只含可刷新状态的结果,绝不携带 token。

export type ChatGptAuthorizeCompleteResponse = ChatGptAuthSnapshot;

关联类型:ChatGptAuthSnapshot

成员说明:

  • localSession:本地开发会话模式(无应用登录);用于文案提示,不改变 owner 选择规则。
  • ownerKind:当前生效的授权场景:应用用户或本地会话。
  • message:可读的最近错误(不含 token)。

ChatGptAuthorizeStartResponse

export type ChatGptAuthorizeStartResponse = {
url: string;
expiresAt: number;
};

成员说明:

  • url:服务端构造的授权 URL;前端只负责同源弹窗打开。
  • expiresAt:事务有效期(毫秒)。

ChatGptGenerateAccepted

export type ChatGptGenerateAccepted = {
requestId: string;
accepted: true;
};

成员说明:

  • accepted:已受理(推理进行中);真实成功以权威提交回执为准。

ChatGptGenerateRequest

生成请求:稳定 requestId 关联推理与权威提交(design D4/D5)。

export type ChatGptGenerateRequest = {
requestId: string;
canvasId: string;
nodeId: string;
mode: ChatGptGenerationMode;
model: string;
prompt: string;
reasoningEffort?: ChatGptReasoningEffort;
expectedContentHash?: string;
selectedCameraId?: string;
clipId?: string;
itemId?: string;
roleId: string;
};

关联类型:ChatGptGenerationMode · ChatGptReasoningEffort

成员说明:

  • reasoningEffort:不提供时使用模型默认思考强度。
  • expectedContentHash:目标并发 precondition:模型内容哈希 / 完整动画 snapshotHash(按模式)。
  • selectedCameraId:提交时选中的稳定镜头 id(仅 camera 模式)。
  • roleId:业务入口显式选择的角色。 浏览器只提交角色 id;prepared turn 由宿主在入口内准备,绝不从请求体接收。

ChatGptGenerationMode

export type ChatGptGenerationMode = (typeof CHATGPT_GENERATION_MODES)[number];

关联类型:CHATGPT_GENERATION_MODES

ChatGptGenerationReceipt

requestId 查询回执:重连/重试使用同一结果,不重复推理计费。

export type ChatGptGenerationReceipt = {
llmOutput?: string;
clipId?: string;
} & ({
status: "running";
requestId: string;
stage: string;
} | {
status: "succeeded";
requestId: string;
mode: ChatGptGenerationMode;
canvasId: string;
nodeId: string;
commandId: string;
revision?: number;
} | {
status: "partial";
requestId: string;
mode: ChatGptGenerationMode;
canvasId: string;
nodeId: string;
applied: string[];
failed: Array<{
part: string;
code: string;
message: string;
}>;
} | {
status: "failed";
requestId: string;
mode: ChatGptGenerationMode;
code: string;
message: string;
} | {
status: "cancelled";
requestId: string;
mode: ChatGptGenerationMode;
} | {
status: "unknown";
requestId: string;
});

关联类型:ChatGptGenerationMode

ChatGptModelView

个人账户模型目录项(使用账户实际返回的 slug/displayName)。

export type ChatGptModelView = {
id: string;
label: string;
};

ChatGptModelsSnapshot

export type ChatGptModelsSnapshot = {
models: ChatGptModelView[];
error?: string;
};

关联类型:ChatGptModelView

成员说明:

  • error:目录读取失败时的可读原因(不掩盖实际调用失败)。

ChatGptProgressEvent

同源进度事件(SSE event: progress / event: result)。

export type ChatGptProgressEvent = {
requestId: string;
stage: string;
detail?: string;
};