前言¶
在 DeepSeek Harness（DSH）里跑带图会话时，若本地附件库里的对象文件被删或丢失，同一条会话可能每一轮都在发请求前就失败，界面反复出现 执行出错 · DeepSeek Messages transport failed（code TRANSPORT）。换网络、代理或 API Key 往往无效，同机其它会话却正常——这是因为错误发生在请求准备阶段读附件，与网络无关。手动改 zstd 会话日志或只能新开对话，成本高且易误操作。下面介绍社区插件 dsh-fix-attachments（维护者 xuzhunzhi）：在 agent 请求失败时自动把读不出来的图片降级为占位文本并重试，另提供离线 CLI 做批量扫描与修复。
这是什么¶
dsh-fix-attachments 是面向 DSH 桌面使用场景的社区插件（MIT，npm 包名 dsh-fix-attachments，当前 package 版本 0.1.0）。它针对「内容寻址附件对象不在 <DSH_HOME>/attachments/v1/objects/<sha256前2位>/<sha256> → prepareImages 抛 ATTACHMENT_NOT_FOUND → 适配器兜底包成 TRANSPORT」这条链路做止血：不恢复已丢失的图片字节，但让该会话可以继续发消息。
插件形态与离线 CLI 共用同一套「视图上是否真有读不出的图」判定；平时推荐装进 profile，进程内自愈，无需每次手改日志。
怎么判断是不是这个问题¶
对照 README 中的特征，若高度吻合即可考虑安装：
- 某条会话每轮失败，文案为
DeepSeek Messages transport failed（TRANSPORT）。 - 失败很快（约 20–60 毫秒），尚未发出 HTTP 请求——这是与真网络故障区分的关键。
- DSH 自动退避重试若干次仍失败，而同机其它会话正常。
- 该会话历史里曾读图、传图；对象文件可能已被清理或丢失。
核心功能¶
进程内插件（推荐）¶
插件挂在 agent loop 的 agent/request-error waterfall（与官方上下文溢出恢复、图片预算 offload 同类扩展点）。请求失败时：
- 检查失败码是否为
TRANSPORT/ATTACHMENT_NOT_FOUND。 - 扫描当前视图
session.surface.nodes（已被 compaction 阴影的老消息排除），逐个检查图片引用对应对象是否存在；已标记 offloaded 的跳过。 - 对缺失对象调用官方机制
session.append('image/offload', { targets })，将图片换成占位文本；随后await ctx.sessions.flush(session)做持久化。 - 返回
{ kind: 'retry' }，让该轮立即重试（不消耗 provider 重试预算，也不记llm/retry）。 - 若无缺图可修，则
next()，把真实网络错误交给下游。
设计要点：依据「视图上是否真有读不出的图」而非猜测错误链，避免掩盖真网络故障；同一轮修复次数受 maxRepairsPerTurn 上限约束，修过的图变为 offloaded 后不会反复触发。
离线 CLI¶
DSH 无法启动，或需要对所有会话做体检时，可使用包内 CLI（需 Node ≥ 22.15）：
node cli/bin/dsh-fix-attachments.mjs scan
node cli/bin/dsh-fix-attachments.mjs fix --apply
node cli/bin/dsh-fix-attachments.mjs backups --session <id>
node cli/bin/dsh-fix-attachments.mjs restore --session <id> --apply
CLI 逐帧解压 session.vN.jsonl.zstd，自行计算 compaction 阴影集，追加带 checksum 的 image/offload 帧；写前备份、写后复核。运行中若 DSH 仍在跑、日志末尾撕裂、或会话格式版本不支持，会拒绝写入（CLI 仅认会话格式 v4）。
安装与启用¶
通过 DSH 插件命令安装到 desktop profile（npm 已发布，也可在插件中心一键装）：
dsh plugin --profile desktop add dsh-fix-attachments
若不走 npm，资料中给出的源码安装方式为：
dsh plugin --profile desktop add github:xuzhunzhi/dsh-fix-attachments
装完重启 DSH 即可，无其它必填配置。资料明确：不要为安装手写 profile 的 package.json 或 patch 里的 insert 行；安装只走 dsh plugin ... add，由包内 cordis.patch.yml 声明 entry。
可选配置在 profile 的 cordis.patch.yml 中按 entry id 覆盖（config 为整体替换）：
- id: dsh-fix-attachments
config:
objectsRoot: 'D:\other-dsh-home\attachments\v1\objects'
maxRepairsPerTurn: 3
确认插件已加载：查看留痕文件（每次修复会更新计数）：
cat ~/.dsh/storages/dsh-fix-attachments-state.json
mountedAt 有值表示已挂载；repairs / lastRepair 反映实际修复次数与涉及的 seq。
典型用法与边界¶
日常：安装插件并保持启用。某轮因缺图触发 TRANSPORT 时，用户侧往往只感到「卡了一下」，同一会话可继续对话。
批量或 DSH 起不来：先退出 DSH，再 scan 看影响范围，fix --apply 写入前务必理解 CLI 会改会话日志；需要时用 restore --apply 回滚。
务必知晓的边界（来自上游 README）：
- 图片不会回来；对象字节丢失无法还原，只是让会话可继续。
- 不修根因；附件对象仍可能再次消失，长期仍建议保持插件启用。
- 只处理图片块；
file等类型不参与prepareImages，不在修复范围。 - 插件在当前 DSH 进程权限下运行，安装前请自行审阅 GitHub 源码 与 MIT 许可证；社区项目与 DeepSeek AI 无隶属关系。
兼容性（资料记载）：DSH 0.2.1-rc.5 实测可用；Windows / macOS / Linux；同一缺陷在上游 discussions 中仍有报告，本插件属于社区侧止血方案。
结尾¶
若你遇到「单会话每轮 DeepSeek Messages transport failed、毫秒级失败且历史含图」这一类问题，dsh-fix-attachments 提供进程内自动 offload 重试与离线修复两套手段，避免只能弃用会话或手改 zstd 日志。
