@xneog/dsh-attachment

English | 中文

持久附件服务边界。ctx.attachments 校验并持久提交不可变图片字节，随后返回可序列化的 ImageAttachmentRef；消费方绝不会在会话事件中持久保存浏览器路径、对象 URL、提供方 URL 或 base64。

未发送的输入区图片仍是由浏览器持有的临时草稿。validateImage 运行相同的准入策略，但不执行持久化。saveImages 负责批次图片数量和总字节限制，先校验全部成员，再按顺序提交，并且只在完整批次成功后返回引用。后续存储失败不会返回部分引用，但较早写入的不可变内容寻址对象可能保持不可达，直至具备按引用感知的垃圾回收。AttachmentError.code 使用封闭的 AttachmentErrorCode 字符串联合类型。其 ImageAdmissionErrorCode 子集标记可由调用方修正的图片输入失败；isImageAdmissionError 在运行时识别该子集，使每个协议适配器可以映射自己的错误词汇。saveImage 会在发布任何模型可见的会话事件前提交一张已接受的图片，readImage 则根据已记录的元数据校验内容寻址对象。调用方可以取消 readImage；实现会在后端读取与校验工作的边界观察取消，并保留取消语义，而不会将其转换为存储失败。

模型体验

该包通过角色无关的核心 ImageBlock，以及解析其持久引用的提供方适配器，间接影响模型。

KV 缓存影响

添加图片会改变提供方请求，因此会使受影响的请求后缀失效。

已知限制与待完成工作

• 第一版仅接受 PNG、JPEG、WebP 和 GIF。
• 保留策略与垃圾回收尚未实现，因为恢复和 fork 后的会话可能共享不可变对象。
• 通用文件、音频、视频和持久的未发送草稿需要单独的生命周期与提供方契约。