后端 web-contracts-src-extension-service:AgentAuthoringToolContribution – ApplicationExtensionMediaResourcesFacade
本页由当前 SDK 声明自动生成。 导入入口:@woohaa3/contracts。
AgentAuthoringToolContribution · AgentAuthoringToolRegistrar · AgentConversationActiveTurn · AgentConversationResult · AgentConversationService · AgentConversationSnapshotView · AgentConversationSubmitInput · AgentConversationSubmitResult · AgentConversationView · ApplicationBackendDiagnosticEntry · ApplicationBackendDiagnostics · ApplicationBackendHandlerRegistration · ApplicationBackendHttpHandlerRegistration · ApplicationBackendRawHttpHandlerRegistration · ApplicationExtensionAgentRoleFacade · ApplicationExtensionAgentRolePrepareRequest · ApplicationExtensionAgentRolePrepareResult · ApplicationExtensionAssistantFacade · ApplicationExtensionCanvasAccessFacade · ApplicationExtensionCanvasFacade · ApplicationExtensionExecutorFacade · ApplicationExtensionHandlerResult · ApplicationExtensionMediaFacade · ApplicationExtensionMediaResourcesFacade
AgentAuthoringToolContribution
export type AgentAuthoringToolContribution = { id: string; available?: () => boolean; register(registrar: AgentAuthoringToolRegistrar, context: McpToolRegistrationContext): void;};关联类型:AgentAuthoringToolRegistrar · McpToolRegistrationContext
AgentAuthoringToolRegistrar
Director-area MCP tools contributed by a trusted backend extension.
The registrar is deliberately transport-neutral: the MCP service supplies the real server and its grant wrapper, while extensions only provide schemas and callbacks. A contribution never receives an owner/canvas from tool args.
export type AgentAuthoringToolRegistrar = { register(name: string, config: Record<string, unknown>, handler: (args: Record<string, unknown>) => Promise<unknown>): void;};AgentConversationActiveTurn
宿主会话读模型快照(生成面板与详情共用)。
active 是最后一次提交/查询得到的对话身份,用于状态区摘要与详情定位;detail 是详情面板
打开的权威快照(未打开时 null)。前端只持读模型,事实源在后端。
export type AgentConversationActiveTurn = { conversationId: string; requestId: string; turn: ConversationTurn;};关联类型:ConversationTurn
AgentConversationResult
会话操作结果:失败携带稳定错误码与可读原因。
export type AgentConversationResult<T> = { ok: true; value: T;} | { ok: false; code: string; error: string;};AgentConversationService
宿主会话服务(前端 capability)。
前端只持有草稿/展开/滚动;会话事实源在后端。所有方法只读或显式接受回合,打开/查询/ 关闭绝不重新 accept 或 dispatch。
export type AgentConversationService = AgentConversationView & { serviceConnectionDirectory?: () => Promise<AgentConversationResult<ServiceConnectionDirectory>>; manageServiceConnection?: (input: ServiceConnectionManagement) => Promise<AgentConversationResult<ServiceConnectionView>>; listServiceConnections?: () => Promise<AgentConversationResult<ServiceConnectionView[]>>; getDataScopeId?: () => string | null; invalidateDirectory: () => void; catalog: (adapterId?: string) => Promise<AgentConversationResult<AgentCatalogResponse>>; mcpStatus: () => Promise<AgentConversationResult<AgentMcpStatusResponse>>; listConversations: (canvasId: string) => Promise<AgentConversationResult<ConversationSummary[]>>; findConversationForTarget: (input: { contextKey?: string; canvasId: string; nodeId: string; connectionId?: string; }) => Promise<AgentConversationResult<{ conversation: ConversationSummary | null; }>>; clearContext: (input: { canvasId: string; nodeId: string; }) => Promise<AgentConversationResult<{ cleared: number; }>>; listConnections: (adapterId?: string) => Promise<AgentConversationResult<AgentConnectionView[]>>; switchConnection: (input: { canvasId: string; nodeId: string; connectionId: string; }) => Promise<AgentConversationResult<{ cleared: number; }>>; readConversation: (conversationId: string, cursor?: number) => Promise<AgentConversationResult<ConversationSnapshot>>; submitTurn: (input: AgentConversationSubmitInput & { requestId: string; }) => Promise<AgentConversationResult<AgentConversationSubmitResult>>; submitImageDirectorScene?: (input: AgentConversationSubmitInput & { requestId: string; }) => Promise<AgentConversationResult<AgentConversationSubmitResult>>; queryTurn: (requestId: string) => Promise<AgentConversationResult<{ conversation: ConversationSummary; turn: ConversationTurn; snapshot: ConversationSnapshot; }>>; locateTurnByRun: (runId: string) => Promise<AgentConversationResult<{ conversation: ConversationSummary; turn: ConversationTurn; snapshot: ConversationSnapshot; }>>; retryTextSave?: (requestId: string) => Promise<AgentConversationResult<{ turn: ConversationTurn; }>>; cancelTurn: (requestId: string) => Promise<AgentConversationResult<{ ok: true; }>>; linkRun: (requestId: string, input: { runId?: string; taskId?: string; }) => Promise<AgentConversationResult<{ turn: ConversationTurn; }>>; skillStep: (input: { canvasId: string; nodeId: string; }) => Promise<AgentConversationResult<{ step: SkillMediaStepView | null; }>>; skillSteps: (input: { canvasId: string; limit?: number; }) => Promise<AgentConversationResult<{ steps: SkillMediaStepView[]; }>>; skillStepDetail: (input: { canvasId: string; skillRunId: string; stepId: string; after?: number; }) => Promise<AgentConversationResult<{ step: SkillMediaStepView; events: Array<SkillStepUpdatedEvent & { sequence: number; }>; cursor: number; resetRequired: boolean; }>>; cancelSkillStep: (input: { canvasId: string; skillRunId: string; stepId: string; }) => Promise<AgentConversationResult<{ step: SkillMediaStepView; state: "cancel-requested" | "already-terminal"; }>>; regenerateSkillStep: (input: { canvasId: string; skillRunId: string; stepId: string; requestId: string; prompt?: string; modelKey?: string; parameters?: Record<string, unknown>; }) => Promise<AgentConversationResult<{ step: SkillMediaStepView; runId: string; }>>;};关联类型:AgentConversationView · AgentConversationResult · ServiceConnectionDirectory · ServiceConnectionManagement · ServiceConnectionView · AgentCatalogResponse · AgentMcpStatusResponse · ConversationSummary · AgentConnectionView · ConversationSnapshot · AgentConversationSubmitInput · AgentConversationSubmitResult · ConversationTurn · SkillMediaStepView · SkillStepUpdatedEvent
成员说明:
invalidateDirectory:配置保存后清除连接/模型目录请求缓存;不改变会话事实或草稿。catalog:读取 adapter 授权/能力/账户目录(真实状态,不自动换模型)。mcpStatus:内置 MCP 真实发现 + 外部连接指引(宿主投影) 。builtin.ready只来自后端 executed initialize/源码声明;external只是当前 origin 的 Streamable HTTP URL,复制地址不等于外部客户端已连接。listConversations:当前画布的会话列表(有界)。findConversationForTarget:按生成目标节点查找该节点当前会话(一个节点复用一条;design D8)。只读。 无则conversation: null(调用方据此新建);不改变导航或读模型。connectionId提供时只返回该来源连接下的会话。clearContext:清空节点上下文:解除该节点与当前会话的关联(归档旧会话,不删除历史;design D8)。 随后该节点提交将新建会话;同时清理本地读模型中该会话的 active/detail。listConnections:该 owner 可见的来源连接。只读。 宿主据此渲染来源/连接选择;按数据空间缓存成功结果及在途请求,失败保留原选择。switchConnection:显式切换来源连接:解除目标关联、归档旧会话(保留历史),下一次提交建立新来源会话。 活动回合由后端拒绝;成功后清理本地读模型并自增contextRevision,让宿主重新解析节点会话。readConversation:读取会话权威快照(消息/回合/事件),用于详情面板。submitTurn:从生成面板提交首轮:确保会话存在、接受回合并异步执行。 相同requestId(由调用方提供稳定身份)命中既有回合时返回reused: true,不再推理。queryTurn:按确切 requestId 查询回合与快照(断流/unknown 恢复;不重新 dispatch)。locateTurnByRun:按领域运行关联定位确切回合(活动/历史 Agent 记录 → 确切 request/run) 。 只匹配宿主已显式关联的 runId,绝不按 nodeId 跳到最近会话;只读,不 accept/dispatch。 无关联返回not-found,调用方据此保留原任务详情(不伪造对话)。retryTextSave:取消在途回合(不撤销已提交领域动作)。linkRun:由宿主领域链在 run/task 接受后显式关联(不从节点 active run 反推)。skillStep:按节点读取 Skill 步骤快照(无步骤时 step=null;轮询/刷新复用同一读入口)。skillSteps:画布内最近 Skill 步骤(活动面板投影;有界)。skillStepDetail:按步骤身份读取快照 + 事件重放(面板打开/断线恢复)。cancelSkillStep:用户停止:只请求取消当前尝试,不伪造已取消。regenerateSkillStep:用户改提示词并重新生成:创建递增 attempt,旧尝试保留可核对历史。
AgentConversationSnapshotView
export type AgentConversationSnapshotView = { pendingSubmissions?: Readonly<Record<string, AgentEntryIntent>>; turnsByRequest?: Readonly<Record<string, AgentConversationActiveTurn>>; conversations: ConversationSummary[]; active: AgentConversationActiveTurn | null; detail: ConversationSnapshot | null; mcp: AgentMcpStatusResponse | null; loading: boolean; error: string | null; contextRevision: number;};关联类型:AgentEntryIntent · AgentConversationActiveTurn · ConversationSummary · ConversationSnapshot · AgentMcpStatusResponse
成员说明:
pendingSubmissions:Local requests awaiting acceptance; never operation records or persisted history.turnsByRequest:Exact request index; active is retained only for legacy consumers.mcp:内置 MCP 真实发现 + 外部连接指引(最近一次查询;未查询为 null)。contextRevision:上下文版本:清空上下文成功后自增,供宿主重新解析节点会话(design D8)。
AgentConversationSubmitInput
生成面板提交首轮时需要的最小目标身份(与 AuthoringGenerationProps 对齐,不复制路由)。
export type AgentConversationSubmitInput = { canvasId: string; adapterId?: string; conversationId?: string; connectionId?: string; entry: AgentEntryIntent;};关联类型:AgentEntryIntent
成员说明:
adapterId:adapter id(缺省由宿主选择首个可用 public adapter)。conversationId:已存在的会话(同一生成目标重复提交时复用,避免每次新会话)。connectionId:选定来源连接。entry:目标动作 intent;discuss只读。
AgentConversationSubmitResult
提交结果:建立/复用会话并接受一个回合(异步执行由后端 dispatch)。
export type AgentConversationSubmitResult = { conversationId: string; requestId: string; turn: ConversationTurn; reused: boolean;};关联类型:ConversationTurn
成员说明:
reused:true 表示相同 requestId+输入命中既有回合,未重复推理。
AgentConversationView
只读订阅视图:生成面板据此展示权威状态与详情入口。
export type AgentConversationView = { getSnapshot: () => AgentConversationSnapshotView; subscribe: (listener: () => void) => () => void;};关联类型:AgentConversationSnapshotView
ApplicationBackendDiagnosticEntry
本机宿主诊断日志的一条记录(已脱敏、有界)。
只由宿主写入:category 是模块标识,event 是稳定事件名,message 是短说明,
attributes 是有界的键值细节。不含令牌、请求体、响应正文、媒体字节或任意资源名。
浏览器只读,不能伪造或清空。
export type ApplicationBackendDiagnosticEntry = { id: string; seq: number; time: number; level: "debug" | "info" | "warn" | "error"; category: string; event: string; code?: string; message?: string; attributes?: Record<string, string>;};成员说明:
id:条目自身的稳定标识(UUID v4),记录那一刻生成、此后不再变。 它是上报的幂等键:同一条目被重复上报(扩展重载、重试、并发点击、多批重发)时, 服务端按「主体 + id」只落一条。seq只是进程内的读取游标——它随进程重建归零, 也不被服务端看见,因此不能拿它当去重依据。seq:单调递增序号,供增量读取。time:采集时刻(epoch 毫秒)。category:模块标识(例如remote-server、canvas)。event:稳定事件名(例如remote-probe-ok)。code:稳定结果/错误码;没有时不出现。message:已脱敏的短说明(人类可读主文本,例如失败原因);没有时不出现。attributes:有界、已脱敏的键值细节(例如status=502、server=host:port、phase=probe),用来补充message说不清的结构化事实;没有合法细节时不出现。 这不是任意载荷或原始日志行:键形状、值长度与条数都由宿主投影保证(键[a-z][a-z0-9._-]{0,31}、值单行 ≤256 字符、≤16 对),令牌式片段已脱敏。管理端按这些 键展示与搜索,因此键必须稳定;新增键等同扩展展示口径,不能由事件字段临时拼出。
ApplicationBackendDiagnostics
宿主诊断缓冲的只读视图(交给可信后端扩展)。
export type ApplicationBackendDiagnostics = { snapshot(input?: { since?: number; limit?: number; }): ApplicationBackendDiagnosticEntry[];};关联类型:ApplicationBackendDiagnosticEntry
成员说明:
snapshot:读取最近的诊断条目(按seq升序)。since只返回序号大于它的条目;limit截取最新的若干条(有上限,调用方不能要求全量)。
ApplicationBackendHandlerRegistration
插件注册的受控请求处理(命名空间下相对路由;宿主统一分派)。
purpose 区分新工作与在途控制(design D4/D6):draining 拒绝 new-work/auth-transaction
的新准入,但保留 work-control/read 的 owner/version-bound 访问。
export type ApplicationBackendHandlerRegistration = { route: string; auth: ApplicationExtensionAuthLevel; requiredActions?: readonly AccessAction[]; purpose?: ApplicationExtensionHandlerPurpose; handle: (input: { body: unknown; context: ApplicationExtensionRequestContext; }) => Promise<ApplicationExtensionHandlerResult> | ApplicationExtensionHandlerResult;};关联类型:ApplicationExtensionAuthLevel · AccessAction · ApplicationExtensionHandlerPurpose · ApplicationExtensionRequestContext · ApplicationExtensionHandlerResult
成员说明:
route:相对路由(不含宿主 base path);/之外不允许空。auth:最低认证等级;插件不能弱化。requiredActions:具名站点 action。宿主在进入插件逻辑前用 SiteAccessPolicy 逐项校验;缺失/未知 action 默认拒绝。purpose:请求用途;缺省按new-work(保守:draining 会拒绝)。
ApplicationBackendHttpHandlerRegistration
插件注册的受控 HTTP handler(server-only;design D4)。
与纯 DTO handler 并存:HTTP handler 取得 method/query/headers/Cookie 与受控响应,用于 OAuth callback、Set-Cookie、HTML、redirect 与有界流式响应。宿主仍在进入前完成认证、 Origin/CSRF、体积与预算校验,并在超时/断连时向执行层发出取消信号。
export type ApplicationBackendHttpHandlerRegistration = { route: string; method: ApplicationExtensionHttpMethod; auth: ApplicationExtensionAuthLevel; requiredActions?: readonly AccessAction[]; purpose: ApplicationExtensionHandlerPurpose; stream?: boolean; streamBudget?: Partial<ApplicationExtensionStreamBudget>; handle: ApplicationExtensionHttpHandler;};关联类型:ApplicationExtensionHttpMethod · ApplicationExtensionAuthLevel · AccessAction · ApplicationExtensionHandlerPurpose · ApplicationExtensionStreamBudget · ApplicationExtensionHttpHandler
成员说明:
requiredActions:具名站点 action(同 DTO handler;宿主在进入前校验)。stream:声明流式(SSE);宿主按streamBudget执行 heartbeat/deadline/预算。
ApplicationBackendRawHttpHandlerRegistration
受控原始 HTTP handler 注册(server-only;design D4 允许“原始 req/res 访问或等价 facade”)。
请求/响应用结构化形状(ApplicationExtensionRawRequest/Response,不 import node:http),
使 contracts 保持浏览器安全;后端入口契约把它与真实 Node 实现对接。宿主在进入前完成认证、
Origin/CSRF 与预算校验,并把可信 dispatch 上下文作为第三参注入;插件不得自报身份。
用于 OAuth 回调、Cookie、HTML、redirect 与 SSE,允许复用既有 Node handler 实现。
export type ApplicationBackendRawHttpHandlerRegistration = { route: string; method: ApplicationExtensionHttpMethod; auth: ApplicationExtensionAuthLevel; requiredActions?: readonly AccessAction[]; purpose: ApplicationExtensionHandlerPurpose; stream?: boolean; streamBudget?: Partial<ApplicationExtensionStreamBudget>; handle: (req: ApplicationExtensionRawRequest, res: ApplicationExtensionRawResponse, context: ApplicationExtensionRequestContext) => Promise<void>;};关联类型:ApplicationExtensionHttpMethod · ApplicationExtensionAuthLevel · AccessAction · ApplicationExtensionHandlerPurpose · ApplicationExtensionStreamBudget · ApplicationExtensionRawRequest · ApplicationExtensionRawResponse · ApplicationExtensionRequestContext
成员说明:
requiredActions:具名站点 action(同 DTO handler;宿主在进入前校验)。
ApplicationExtensionAgentRoleFacade
受信后端扩展可用的角色准备面(不穿过浏览器边界)。
export type ApplicationExtensionAgentRoleFacade = { prepare(input: ApplicationExtensionAgentRolePrepareRequest): ApplicationExtensionAgentRolePrepareResult; list(): readonly AgentRoleDescriptor[]; availability(namespacedId: string): { available: boolean; reason?: string; };};关联类型:ApplicationExtensionAgentRolePrepareRequest · ApplicationExtensionAgentRolePrepareResult · AgentRoleDescriptor
ApplicationExtensionAgentRolePrepareRequest
export type ApplicationExtensionAgentRolePrepareRequest = { roleId: string; input: unknown; context: unknown; target: AgentRoleTargetRef; requestId: string; expectedContentHash?: string; channel: AgentRoleChannelCapabilities; requestedTools?: readonly string[]; attachments?: readonly unknown[];};关联类型:AgentRoleTargetRef · AgentRoleChannelCapabilities
成员说明:
roleId:完整命名空间角色 id(<extensionId>/<roleId>)。context:领域入口准备好的权威上下文;调用方必须是受信后端扩展。requestId:本回合稳定 requestId(业务入口自己的幂等身份)。expectedContentHash:领域冻结的内容前置条件(若有)。channel:所选执行通道/模型的真实能力。requestedTools:业务入口显式收窄(只能是角色声明的子集)。attachments:附件身份摘要(字节沿原附件通道传递,不进入角色定义)。
ApplicationExtensionAgentRolePrepareResult
export type ApplicationExtensionAgentRolePrepareResult = { ok: true; turn: PreparedAgentRoleTurn;} | AgentRoleFailure;关联类型:PreparedAgentRoleTurn · AgentRoleFailure
ApplicationExtensionAssistantFacade
Structured assistant work uses the host conversation ledger and configured assistant connections.
export type ApplicationExtensionAssistantFacade = { query(input: { subject: string; canvasId: string; nodeId: string; requestId: string; }): Promise<{ state: string; text?: string; error?: { code: string; message: string; }; conversation?: { conversationId: string; requestId: string; }; } | null>; cancel(input: { subject: string; canvasId: string; nodeId: string; requestId: string; }): Promise<void>; submitRole(input: { subject: string; canvasId: string; nodeId: string; requestId: string; connection: AgentConnectionBinding; roleId: string; roleInput: unknown; roleContext: unknown; model?: string; reasoningEffort?: AgentReasoningEffort; references?: readonly { storageKey: string; checksum: string; }[]; }): Promise<{ ok: true; conversation?: { conversationId: string; requestId: string; }; } | { ok: false; code: string; message: string; }>;};关联类型:AgentConnectionBinding · AgentReasoningEffort
成员说明:
submitRole:角色/输入形式的新提交。 业务扩展只提交显式角色 id 与输入;宿主负责解析、能力匹配与 prepare。
ApplicationExtensionCanvasAccessFacade
项目读/写权限授权 facade。
受控 DTO handler 不能只凭浏览器自报的 canvasId/nodeId 放行:宿主注入本 facade,插件用
可信 principal.subject 按画布读写权限判定。与 extensionNodes 不同,这里不读取/加载
画布 room,只做权威授权判定,因此适用于不返回画布内容的项目元数据 handler。
未配置该能力的宿主下插件 MUST 按能力拒绝(fail closed),不得退回“知道 id 即可写”。
export type ApplicationExtensionCanvasAccessFacade = { authorize(input: { subject: string; canvasId: string; permission: "read" | "write"; }): Promise<{ ok: true; } | { ok: false; code: string; message: string; }>;};ApplicationExtensionCanvasFacade
插件可调用的 Canvas facade:画布节点的 run/cancel 仍由 Canvas 生成权威 run identity。
export type ApplicationExtensionCanvasFacade = { requestNodeRun(input: { canvasId: string; nodeId: string; modelKey: string; prompt: string; parameters: Record<string, unknown>; }): Promise<{ ok: true; runId: string; } | { ok: false; code: string; message: string; }>; requestNodeCancel(input: { canvasId: string; nodeId: string; runId: string; }): Promise<{ ok: true; } | { ok: false; code: string; message: string; }>; refreshSyncUpstream?(): Promise<void>; syncCanvasMedia?(canvasId: string): void;};成员说明:
refreshSyncUpstream:通知宿主重新解析画布同步上游凭据(canvas-upstream:<id>capability)。 能力交接面只提供resolve(),宿主不会轮询扩展会话;因此扩展在登录 / 登出 / 会话变化 后必须显式调用一次,否则宿主仍连着旧上游(或继续纯本地)。宿主侧解析幂等:同一份会话 重复触发不会重建连接。 可选:未实现的宿主下扩展按能力降级(画布仍按静态配置或纯本地同步),不得把缺失当失败。syncCanvasMedia:显式启动一次画布媒体字节补传(「同步远端」动作在文档链路建立后调用)。 与refreshSyncUpstream同一件事的两个面:那个把文档接到中继,这个把画布引用的存量资产 对账到服务端托管存储。缺失时插件按能力降级(只同步文档),不得当作失败。
ApplicationExtensionExecutorFacade
Bound to the actual activation owner. Secrets and host callbacks never enter the daemon journal.
export type ApplicationExtensionExecutorFacade = { query(input: { executor: string; owner: string; requestId: string; }): Promise<ExtensionExecutorOutcome | null>; cancel(input: { executor: string; owner: string; requestId: string; }): Promise<void>; run(input: { executor: string; owner: string; requestId: string; prepared: PreparedAgentRoleTurn; payload?: unknown; signal?: AbortSignal; onEvent?: (event: ExtensionExecutorEvent, cursor?: number) => void; since?: number | "head"; hostCall?: (method: string, params: unknown) => Promise<unknown>; hostMethods?: readonly string[]; }): Promise<ExtensionExecutorOutcome>;};关联类型:ExtensionExecutorOutcome · PreparedAgentRoleTurn · ExtensionExecutorEvent
ApplicationExtensionHandlerResult
handler 返回:body 必须是有界 JSON;宿主负责序列化与状态码。
export type ApplicationExtensionHandlerResult = { status?: number; body: unknown;};ApplicationExtensionMediaFacade
插件可调用的 Media facade:只构造稳定引用/上传结果,不接触 COS 凭据。
export type ApplicationExtensionMediaFacade = { resources?: ApplicationExtensionMediaResourcesFacade; stat(storageKey: string): Promise<{ exists: boolean; contentType?: string; size?: number; }>; verify?(storageKey: string, canvasId?: string): Promise<ApplicationExtensionMediaVerifyResult>;};关联类型:ApplicationExtensionMediaResourcesFacade · ApplicationExtensionMediaVerifyResult
成员说明:
verify:完整核验。 返回真实 size/checksum/contentType 或{ exists: false };只读,不接触 COS 凭据。 可选:未实现的宿主下插件 MUST 按能力降级(不得用 stat 冒充已具备完整 metadata)。
ApplicationExtensionMediaResourcesFacade
export type ApplicationExtensionMediaResourcesFacade = { read(storageKey: string, canvasId?: string): Promise<{ bytes: Uint8Array; contentType: string; }>; write(input: { bytes: Uint8Array; contentType: string; canvasId?: string; }): Promise<MediaMetadata>; openRead?(storageKey: string, canvasId?: string): Promise<{ bytes: AsyncIterable<Uint8Array>; contentType: string; size: number; cancel(): void; }>; writeStream?(input: { bytes: AsyncIterable<Uint8Array>; contentType: string; maxBytes?: number; signal?: AbortSignal; canvasId?: string; }): Promise<MediaMetadata>;};关联类型:MediaMetadata
成员说明:
read:读取稳定资源字节。canvasId可选,但能确定所属画布时必须传:远端画布的媒体字节只存在服务端托管存储 (键布局<canvasId>/media/<key>),本地主存储里没有;省略作用域会按media/<key>去 读主存储,把一张存在的远端素材报成 404。省略表示「与画布无关」(扩展素材、独立页), 保持历史行为。write:写入内容寻址的稳定资源。canvasId语义同read:属于远端画布时必须带,否则字节只落本机主存储,其他协作者 与换机后的自己都读不到;省略表示与画布无关。