跳转到内容

后端 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:属于远端画布时必须带,否则字节只落本机主存储,其他协作者 与换机后的自己都读不到;省略表示与画布无关。