tapcanvas-api

TapCanvas API

协议诊断或离线 Agent 评估需要直接测试已启用文本模型时，终端通过 llmChat endpoint 调用现有 /agents/llm/v1/chat/completions 用户鉴权代理，显式提供 model/messages 和所需协议字段。该调用不创建用户画布产物，也不自动执行返回的工具调用；不能作为一键成片的平行生产链。真实推理会正常计费，不切换模型或绕过自有网关。

TapCanvas 对外 API 的唯一 skill：统一入口、统一凭据、明确失败（不静默降级、不猜默认接口、不切旧 skill）。

用户只要视频节点时，在装配工作流调用中显式传 triggerPayload.onlyVideoNodes=true；该参数优先于章节默认设置。保留全章生产与真实素材链，验收视频节点、完整提示词和引用已持久化，不提交视频生成。

工作流恢复

当前新执行冻结 workflowMediaDeliveryPolicy.maxRetries=0：图片或视频供应商失败后保留精确回执和成功兄弟资产，不自动重提付费任务；已受理任务仍按原 taskId 对账。历史已冻结 maxRetries=1 的执行按原快照解释，不能把新策略倒灌到旧回执。需要再次生成失败项时，必须取得用户对精确失败项的明确授权，再使用下述 mediaRetries；不重复启动整条工作流。集合查询断连保留 waiting_external 与观察失败证据，由后台继续对账。

用户已授权重试失败图片时，executionResume 可传 mediaRetries:[{nodeId,itemId,taskId}]，三项必须取自同一次 executionNodeRuns 的精确失败图片回执。服务端验证旧项 failed、旧 taskId 一致、没有产物及下游已受理副作用，再沿原执行族创建独立幂等的新图片尝试；旧失败节点和成功兄弟项保留。普通空对象 resume 不授权重复提交媒体。正在执行、已成功、身份不符或已有资产的项不能重试；不得通过新建完整工作流绕过。该模式与其他 resume 修订模式互斥，不修改模型、提示词或来源。

引用被判为废弃但公开删除清单没有对应节点时，用 chapterCanvasMembership --chapterId <真实章节ID> 读取只读归属诊断（需管理员身份并核对章节权限）；核对精确节点/任务 ID、可见性、明确删除、执行脱离与保留事实。此接口不恢复节点、不允许据诊断自行复活用户已删除素材。

本地运维诊断已生成图片的读取/解码故障，可运行本 skill 的 scripts/inspect-execution-image-resources.mjs --profile local --execution-id <真实 executionId> --node-id <真实图片集合节点> --container <本地执行器容器名>。脚本仅通过正式 CLI executionNodeRuns 取得 asset-bindings，在指定执行器中探测原图片 HTTP 响应并解码，输出身份、状态码、MIME、字节数、哈希、尺寸及具体异常；不输出 URL/图片正文，不调用理解模型、不生成或回写资产。这是网络和解码事实，不是视觉语义理解。

已确认未提交媒体的计划结构错误，可用同族 tapcanvas_workflow_resume 的 planningRevision={nodeId,instruction,refreshAssetIds:[]} 交回精确作者修订。空列表明确表示保留全部冻结素材与观察，不刷新资产；修复指令依据本次真实失败证据，不更改用户目标、来源或模型。背景计划同 assetId 必须对应同一份完整计划，若作者需要不同背景状态则由作者赋予不同 ID，不由本地选择、合并提示词或覆盖旧结果。

带背景站位图沿正式图片工具先生成场景 Skill 编写的俯视底图，再调用 tapcanvas_render_blocking_diagram。新图传结构化 characters/compositionContract 和 backgroundNodeId；旧图新增背景版本传 sourceDiagramNodeId + backgroundNodeId。工具直接持久化并回读新节点，返回 nodeId/状态/构图来源，不返回图片 URL。底图和源图必须属于当前授权画布，原图与下游引用不改写。

若历史 BeatSheet 在同一字段的添加/删除间反复重试，先核对 Agent 提交 schema、Agent 校验和宿主校验实际加载的共享 clip-reference-selection 合同。字段缺失只修订同一候选；修复部署后沿原持久执行继续，不新建工作流、不复制输入素材、不把仍在修订说成供应商生成中。