后端 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];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;});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;};