错误、取消与并发

返回结果还是抛出错误

情况	表达方式
上传或访问不需要处理	check 返回 noop，或 process 返回 pass
不支持当前图片格式	check 返回 unsupported，由步骤策略决定跳过或中止
业务规则拒绝本次上传或访问	process 返回 reject 和原因
保存后建议屏蔽或删除	execute 返回 block/delete，可附详情
无法正常完成操作	抛出 PluginError

例如审核正常完成但发现违规内容，应返回处置结果；审核服务超时才是执行错误。

PluginError 的三个字段

throw new PluginError("NETWORK", "Upload timed out", true);

字段	含义	默认值
code	通用错误原因	必填
message	不含敏感信息的错误说明	必填
retryable	是否允许宿主按任务规则重试	false

失败表示未确认成功，超时或连接中断后远端操作可能已经完成。retryable 只控制是否允许重试，不表达远端结果。写入重试直接再次调用 write，可能创建重复对象；插件可以使用 operationId 避免重复，核心不要求提供这一保证。

通用错误码

错误码	含义
INVALID_CONFIG	持久配置无效
INVALID_INPUT	本次输入或参数无效
ACCESS_DENIED	认证或权限失败
NOT_FOUND	所需资源不存在
CONFLICT	当前资源状态冲突
RESOURCE_LIMIT	大小、容量或配额超限
RATE_LIMITED	请求频率或并发受限
UNSUPPORTED	不支持该操作或格式
NETWORK	网络连接、传输或超时
IO	其他本地读写失败
INVALID_DATA	内容损坏或响应不符合协议
SERVICE	其他上游服务失败
FAILED	未分类失败

核心映射为 PLUGIN_ 前缀错误码，未知外部码归一为 PLUGIN_FAILED。将供应商错误映射到这些通用原因，不需要核心认识插件专属错误码。

重试与幂等

retryable: true 是允许重试，不是保证重试。后台任务还受尝试次数、当前处置和手动重试规则约束；上传和访问也不会因此自动变成后台重试任务。

写入、删除和保存后调用提供 operationId，保存后步骤的标识与任务及步骤关联。用它识别同一次操作的重复调用，不要假设“响应失败”意味着“远端没有执行”。

保存后失败可能重试整条流水线，不是只重试抛错步骤。已经发送的通知可能重复，应结合接收端的幂等能力决定是否允许重试。具体累计处置规则见 保存后处理。

取消与资源释放

将取消信号传给网络请求，在耗时操作之间检查取消，并等待自己启动的工作结束。例如运行方法中的请求片段：

signal.throwIfAborted();
const response = await fetch(url, { signal });

流和连接需要在完成、失败、取消三种情况下释放。SDK 的 withAbortSignal 可在取消时销毁支持 destroy() 的资源；缩放示例 展示了与 Sharp 配合的方式。

插件在主进程运行，取消依赖插件配合。超时不会强制终止不响应信号的调用，也不能立即删除它仍在使用的临时文件。不要启动未等待、未受管理的后台工作。

并发调用与实例生命周期

同一实例可能同时处理多个文件。实例闭包适合保存只读配置和可并发使用的客户端，不适合保存“当前文件”“当前请求”等变量；这些数据应放在方法局部。

持久状态更新使用版本检查，见 密钥与运行状态。不要为方便而将所有文件处理串行化；只保护确实需要互斥的共享资源。

dispose：释放实例

所有运行对象均可选实现此方法，定义在 createInstance 返回的对象上，而不是插件定义顶层。

dispose?(): void | Promise<void>;

无输入参数、无返回数据；可同步释放，也可返回 Promise 等待异步关闭。用于关闭实例持有的连接池等长期资源，不删除用户图片或持久配置。

宿主关闭或替换实例时触发释放；旧实例仍有在途引用时，会延后调用。不要假设保存配置会立刻停止旧调用。单次请求创建的流和临时资源应在该调用内释放，不能全部积攒到 dispose。

验证重点

按插件能力选择必要场景：路径插件检查路径合法性和冲突风险；处理插件验证不适用、输出与取消；有远端副作用的插件验证重复调用，以及明确未生效和结果不确定的失败。

同实例并发调用时，检查文件、参数和状态是否串扰。示例用于理解接口，不能替代目标服务的故障验证。