[Bug] 删除附件对象后会话每个请求都失败，并被误报为 "DeepSeek Messages transport failed"（附修复补丁）

[shujie2015-a11y]

Summary

会话历史里引用的图片附件对象一旦在磁盘上缺失（例如 $DSH_HOME/attachments/v1/objects/ 下的对象被用户清理或误删），该会话此后每一个模型请求都会失败，报 DeepSeek Messages transport failed（code: TRANSPORT），默认重试策略再退避重试 5 次且每次同样失败——会话彻底无法继续发消息。

除了"会话砖掉"，这个报错还会把排查带偏：真实原因是本地附件缺失，与网络无关，但错误指向传输层（本次实测 HTTP 请求数为 0）。

Reproduction

1. 在一个会话里让模型读过图（附件复制进 $DSH_HOME/attachments/v1/objects/<sha256 前两位>/<sha256>，会话历史以 attachmentId 引用）。
2. 删除这些对象文件。
3. 在同一会话里继续发消息。

结果：请求在本地准备阶段就抛错，turn/end 的 reason 为 {"kind":"error","error":{"code":"TRANSPORT","message":"DeepSeek Messages transport failed"}}；每个失败 step 在会话日志里留下 5 条 llm/retry（0.5s→8s 退避），而没有任何 HTTP 请求发出。

Current behavior

• 真实抛错点：packages/attachment/attachment-local/src/store.ts:443 → AttachmentError('Attachment object is missing.', 'ATTACHMENT_NOT_FOUND')。
• 该错误被 packages/llm/llm-deepseek/src/adapter.ts:66 的兜底 catch 包成 TRANSPORT（兜底把请求准备阶段的非 LlmError 一律当作传输失败）。
• packages/llm/llm-deepseek/src/images.ts 的 prepareImages 每次请求都要重读会话里的全部图片，所以一个缺失对象会让该会话的每个请求都失败（新会话不受影响，因为它不引用这些附件）。
• 可观测特征：每次尝试 6–20ms 即失败（纯本地错误，无网络往返），但仍被重试 5 次。

Expected behavior

附件缺失应按其自身身份上报：保留 ATTACHMENT_NOT_FOUND（该 code 不在默认重试集合内，本就不应重试），并在消息里点名是哪个附件；不要伪装成 TRANSPORT。

Environment

dsh-v0.1.7-rc.2（master commit 477b4f4205），macOS，provider deepseek-official。

Proposed fix（本地补丁，已跑测试）

在读取点翻译附件失败，保留附件自己的 code 并点名附件：

diff --git a/packages/llm/llm-deepseek/src/images.ts b/packages/llm/llm-deepseek/src/images.ts
index 9d72f4c5dc..01c8a654cc 100644
--- a/packages/llm/llm-deepseek/src/images.ts
+++ b/packages/llm/llm-deepseek/src/images.ts
@@ -1,6 +1,7 @@
 /** Deterministic Messages image preparation for Files references and bounded inline fallback. */
 
-import type { AttachmentStore, ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
+import { AttachmentError } from '@deepseek-ai/dsh-attachment'
+import type { AttachmentStore, ImageAttachmentRef, ImageRequestTarget, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
 import { contentHasImage, IMAGE_OFFLOAD_REQUIRED_CODE, LlmError, offloadedImageText, projectOffloadedImages, requiredImageOffload } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, ImageAttachmentAccessResolver, RequestMessage } from '@deepseek-ai/dsh-llm'
 import type { DeepSeekConnectionOptions as Connection } from './types.ts'
@@ -26,6 +27,22 @@ function* imageRefs(blocks: readonly ContentBlock[]): Generator<ImageAttachmentR
   }
 }
 
+/** Read one retained image version, keeping an attachment failure's own code and naming its object. */
+async function readRequestImage(
+  attachments: AttachmentStore, ref: ImageAttachmentRef, target: ImageRequestTarget, signal: AbortSignal,
+): Promise<RequestImageAttachment> {
+  try {
+    return await attachments.readImageRequest(ref, target, signal)
+  } catch (error) {
+    if (!(error instanceof AttachmentError)) throw error
+    throw new LlmError(
+      `DeepSeek Messages could not prepare image attachment ${ref.name ?? String(ref.attachmentId)}: ${error.message}`,
+      error.code,
+      { cause: error },
+    )
+  }
+}
+
 /** Normalize retained image references before converting Messages content.
  * @param history - durable history; never mutated.
  * @param connection - request-local image budgets.
@@ -52,7 +69,8 @@ export async function prepareImages(
   for (const message of messages) {
     for (const ref of imageRefs(message.content)) {
       if (!versions.has(ref.attachmentId)) {
-        versions.set(ref.attachmentId, await attachments.readImageRequest(ref, resolveRequestImageTarget(model, ref), signal))
+        const target = resolveRequestImageTarget(model, ref)
+        versions.set(ref.attachmentId, await readRequestImage(attachments, ref, target, signal))
       }
     }
   }
diff --git a/packages/llm/llm-deepseek/tests/runtime.spec.ts b/packages/llm/llm-deepseek/tests/runtime.spec.ts
index 4c505e1fe2..310837ddc5 100644
--- a/packages/llm/llm-deepseek/tests/runtime.spec.ts
+++ b/packages/llm/llm-deepseek/tests/runtime.spec.ts
@@ -4,7 +4,7 @@ import { mkdtempSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Context } from '@deepseek-ai/cordis'
-import { AttachmentId, ImageVariantId } from '@deepseek-ai/dsh-attachment'
+import { AttachmentError, AttachmentId, ImageVariantId } from '@deepseek-ai/dsh-attachment'
 import type { AttachmentStore, ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
 import { createLaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment'
 import LlmRuntime, { ToolCallId, createUserMessage,
@@ -444,6 +444,31 @@ describe('DeepSeekAdapter against a mock server', () => {
     expect(server.requests).toHaveLength(0)
   })
 
+  it('reports an unavailable image attachment by its own code and name', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const missing = new AttachmentError('Attachment object is missing.', 'ATTACHMENT_NOT_FOUND')
+    const attachments = attachmentStoreOf(() => Promise.reject(missing))
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments.store)
+
+    const rejected = await drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({ source: { kind: 'user' }, content: [
+        { type: 'image', attachment: { ...imageRef, name: '111111.png' } },
+      ] })],
+    })).catch((error: unknown) => error)
+
+    expect(rejected).toMatchObject({
+      code: 'ATTACHMENT_NOT_FOUND',
+      message: 'DeepSeek Messages could not prepare image attachment 111111.png: Attachment object is missing.',
+    })
+    expect((rejected as LlmError).cause).toBe(missing)
+    expect(server.requests).toHaveLength(0)
+  })
+
   it('falls back to one all-base64 request when Files API resolution fails', async () => {
     const server = await mockServer([{ kind: 'sse', events: textEvents }])
     const secondRef = { ...imageRef, attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`) }

验证（均在 477b4f4205 之上）：

• vitest run packages/llm/llm-deepseek/tests/runtime.spec.ts packages/llm/llm-deepseek/tests/files.spec.ts → 171 passed。新增用例断言：code 为 ATTACHMENT_NOT_FOUND、消息含附件名、cause 链保留原 AttachmentError，且 provider 未收到任何请求。
• vitest run packages/attachment/attachment-local/tests/store.spec.ts → 12 passed。
• tsc -b packages/llm/llm-deepseek 与 tsc -b tsconfig.host.json 均为 0 error。

补充：CONTRIBUTING 说明当前暂不接受外部 PR，所以先以 Discussion 形式反馈；如果之后开放外部贡献，我们可以直接提供分支/PR。

[shujie2015-a11y]

补充建议：把"附件不可用"降级成文本占位，而不是让整轮请求失败

上面的补丁让失败报得准，但没有改变行为：只要会话历史里引用的某个附件对象不在了，prepareImages 仍然抛错，该会话的每个请求都会失败（resume 旧会话同样挂）。也就是说，"附件库里少一个对象 = 引用它的活跃会话报废"。

更彻底的做法是复用仓库里现成的"图片卸载成文本"机制，把不可用的那张图投影成一行占位文字，其余图片照常处理：

• 现成机制：packages/llm/llm/src/content.ts:108 的 offloadedImageText(ref, access?)（占位文案形如 [image omitted to fit request image limits; <identity>. …]）与 :251 的 projectOffloadedImages(messages, placeholder)。
• 落点：packages/llm/llm-deepseek/src/images.ts 的 prepareImages——当 readImageRequest 抛出"对象不存在／读取失败"这类 AttachmentError 时不再上抛，改为把该 ref 投影成占位文本（可记一条 warn，指明这张图已失效），其余图片照常读取。
• 边界：只在附件不可用时降级；真正的错误（例如该 provider 不支持图片投影、超出限额）仍照抛，避免把真故障一起吞掉。
• 效果：删除附件对象最多让那张图变成一行文字说明，不会砖掉整个会话；附件库清理也不再带"删了就废活跃会话"的隐藏后果。

说明：我们本机只落地了上面那条报错补丁（小改动）；这条降级属于行为改变，交给维护者判断是否值得做。

[shujie2015-a11y]

已按上面的思路落地：附件不可用降级为占位文本（附实现补丁与验证）

我们把这条件议在本机实现了，做法就是复用"图片卸载成文本"的投影机制，不新造机制：

• packages/llm/llm/src/content.ts
  • 新增 unavailableImageText(ref)：稳定占位文案，点名附件并提示重新附图（[image unavailable: its stored attachment object cannot be read; "name" (sha256:…). Ask the user to attach it again if needed.]）。
  • 新增 projectUnavailableImages(messages, unavailable, placeholder)：只替换 unavailable 集合里那些 attachmentId 的出现位置，其余内容与消息对象保持原样（无不可用项时按原引用返回）。
• packages/llm/llm-deepseek/src/images.ts
  • 读取点把"读不出存储字节"的失败（ATTACHMENT_NOT_FOUND / ATTACHMENT_READ_FAILED / ATTACHMENT_CORRUPT）视作不可用、返回 undefined；循环里同一附件只尝试一次；收集完统一投影。
  • 其余附件错误仍以自身的 code 失败并在消息里点名附件（例如 INVALID_ATTACHMENT_REF），不会降级。

边界与性质：

• 只在"存储字节产不出来"时降级；provider 不支持投影、超出限额等仍照抛，避免把真故障吞掉。
• 投影是请求内的：会话日志保留原始引用（与 text-only 模型的 projectImagesForTextModel 同一性质），不是持久改写。

验证：

• vitest run packages/llm/llm/tests/content.spec.ts packages/llm/llm-deepseek/tests/runtime.spec.ts packages/llm/llm-deepseek/tests/files.spec.ts → 全绿（36 / 159 / 13）。
• 新增用例断言：不可用附件被替换为占位文本、请求照常发出（无 Files 请求）、INVALID_ATTACHMENT_REF 仍以自身 code 失败且 HTTP 请求数为 0。
• tsc -b packages/llm/llm packages/llm/llm-deepseek 与 tsc -b tsconfig.host.json → 0 error；oxlint 0 警告。
• 运行态产物重建后自证：llm/lib/index.js 含 image unavailable 与 projectUnavailableImages，sha256 由 9132c8a8… 变为 7eac2052…；llm-deepseek/lib/index.js 含 ATTACHMENT_NOT_FOUND，sha256 由 c729db70… 变为 b65bb2d1…；两份产物 node --check 通过。

效果：删除附件对象最多让那张图在请求里变成一行说明文字，会话继续可用；不再出现"一个对象缺失 → 引用它的活跃会话报废"。

diff --git a/packages/llm/llm-deepseek/src/images.ts b/packages/llm/llm-deepseek/src/images.ts
index 01c8a654cc..fbae9f2ec8 100644
--- a/packages/llm/llm-deepseek/src/images.ts
+++ b/packages/llm/llm-deepseek/src/images.ts
@@ -1,8 +1,8 @@
 /** Deterministic Messages image preparation for Files references and bounded inline fallback. */
 
 import { AttachmentError } from '@deepseek-ai/dsh-attachment'
-import type { AttachmentStore, ImageAttachmentRef, ImageRequestTarget, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
-import { contentHasImage, IMAGE_OFFLOAD_REQUIRED_CODE, LlmError, offloadedImageText, projectOffloadedImages, requiredImageOffload } from '@deepseek-ai/dsh-llm'
+import type { AttachmentErrorCode, AttachmentStore, ImageAttachmentRef, ImageRequestTarget, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
+import { contentHasImage, IMAGE_OFFLOAD_REQUIRED_CODE, LlmError, offloadedImageText, projectOffloadedImages, projectUnavailableImages, requiredImageOffload, unavailableImageText } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, ImageAttachmentAccessResolver, RequestMessage } from '@deepseek-ai/dsh-llm'
 import type { DeepSeekConnectionOptions as Connection } from './types.ts'
 import { resolveRequestImageTarget } from './request-pricing.ts'
@@ -27,14 +27,28 @@ function* imageRefs(blocks: readonly ContentBlock[]): Generator<ImageAttachmentR
   }
 }
 
-/** Read one retained image version, keeping an attachment failure's own code and naming its object. */
+/** Attachment codes naming stored bytes this request cannot produce, so the occurrence degrades to text. */
+const UNAVAILABLE_ATTACHMENT_CODES: ReadonlySet<AttachmentErrorCode> = new Set([
+  'ATTACHMENT_NOT_FOUND',
+  'ATTACHMENT_READ_FAILED',
+  'ATTACHMENT_CORRUPT',
+])
+
+/** Read one retained image version; unreadable stored bytes yield undefined so the remaining request still sends.
+ * @param attachments - mounted attachment store.
+ * @param ref - durable normalized attachment for this occurrence.
+ * @param target - request-image dimensions and byte budget for this occurrence.
+ * @param signal - request cancellation.
+ * @returns the prepared version, or undefined when its stored object cannot be read.
+ */
 async function readRequestImage(
   attachments: AttachmentStore, ref: ImageAttachmentRef, target: ImageRequestTarget, signal: AbortSignal,
-): Promise<RequestImageAttachment> {
+): Promise<RequestImageAttachment | undefined> {
   try {
     return await attachments.readImageRequest(ref, target, signal)
   } catch (error) {
     if (!(error instanceof AttachmentError)) throw error
+    if (UNAVAILABLE_ATTACHMENT_CODES.has(error.code)) return undefined
     throw new LlmError(
       `DeepSeek Messages could not prepare image attachment ${ref.name ?? String(ref.attachmentId)}: ${error.message}`,
       error.code,
@@ -66,16 +80,19 @@ export async function prepareImages(
   if (messages.some(message => message.role !== 'user' && message.role !== 'tool' && contentHasImage(message.content))) {
     throw new LlmError('DeepSeek Messages supports images only in user messages and tool results', 'UNSUPPORTED_CONTENT')
   }
+  const unavailable = new Set<ImageAttachmentRef['attachmentId']>()
   for (const message of messages) {
     for (const ref of imageRefs(message.content)) {
-      if (!versions.has(ref.attachmentId)) {
-        const target = resolveRequestImageTarget(model, ref)
-        versions.set(ref.attachmentId, await readRequestImage(attachments, ref, target, signal))
-      }
+      if (versions.has(ref.attachmentId) || unavailable.has(ref.attachmentId)) continue
+      const target = resolveRequestImageTarget(model, ref)
+      const version = await readRequestImage(attachments, ref, target, signal)
+      if (version === undefined) unavailable.add(ref.attachmentId)
+      else versions.set(ref.attachmentId, version)
     }
   }
-  assertImagesFit(messages, versions, connection, 'raw')
-  return { messages, versions }
+  const retained = projectUnavailableImages(messages, unavailable, unavailableImageText)
+  assertImagesFit(retained, versions, connection, 'raw')
+  return { messages: retained, versions }
 }
 
 /** Require logged offload before retrying images that exceed the inline budget.
diff --git a/packages/llm/llm/src/content.ts b/packages/llm/llm/src/content.ts
index cecbfba938..c8e2712fea 100644
--- a/packages/llm/llm/src/content.ts
+++ b/packages/llm/llm/src/content.ts
@@ -116,6 +116,15 @@ export function offloadedImageText(
   return `[${identity}${normalizedAccessText(ref, access)}]`
 }
 
+/**
+ * Stable per-image placeholder for an attachment whose stored object cannot be read.
+ * @param ref - durable normalized attachment whose bytes this request cannot produce.
+ * @returns deterministic identity and the recovery instruction for the user.
+ */
+export function unavailableImageText(ref: ImageAttachmentRef): string {
+  return `[image unavailable: its stored attachment object cannot be read; ${imageIdentity(ref)}. Ask the user to attach it again if needed.]`
+}
+
 /**
  * True when typed model content contains an image block. This is the one image
  * walk shared by every image policy (capability gating, text-only
@@ -240,6 +249,45 @@ function replaceOffloadedImages(
   return next ?? blocks as ContentBlock[]
 }
 
+/** Replace every occurrence whose stored bytes are unavailable with its placeholder. */
+function replaceUnavailableImages(
+  blocks: readonly ContentBlock[],
+  unavailable: ReadonlySet<ImageAttachmentRef['attachmentId']>,
+  placeholder: (ref: ImageAttachmentRef) => string,
+): ContentBlock[] {
+  let next: ContentBlock[] | undefined
+  for (const [index, block] of blocks.entries()) {
+    if (block.type === 'image' && unavailable.has(block.attachment.attachmentId)) {
+      next ??= blocks.slice(0, index)
+      next.push({ type: 'text', text: placeholder(block.attachment) })
+      continue
+    }
+    next?.push(block)
+  }
+  return next ?? blocks as ContentBlock[]
+}
+
+/**
+ * Project occurrences whose stored bytes are unavailable into deterministic
+ * text for one request. The unavailable set is request-local: the durable
+ * history keeps its reference, and only this request's content is projected.
+ * @param messages - derived request history.
+ * @param unavailable - attachment ids whose stored object this request cannot read.
+ * @param placeholder - build the model-visible replacement for one unavailable attachment.
+ * @returns the original list when nothing is unavailable, otherwise shallow message copies with placeholders.
+ */
+export function projectUnavailableImages(
+  messages: readonly RequestMessage[],
+  unavailable: ReadonlySet<ImageAttachmentRef['attachmentId']>,
+  placeholder: (ref: ImageAttachmentRef) => string,
+): readonly RequestMessage[] {
+  if (unavailable.size === 0) return messages
+  return messages.map((message) => {
+    const content = replaceUnavailableImages(message.content, unavailable, placeholder)
+    return content === message.content ? message : { ...message, content }
+  })
+}
+
 /**
  * Project the surface's offloaded occurrences into deterministic text for one
  * request. The offloaded set is a durable surface fact, so every route sends

[PerryLink]

你给的两个位置我都在当前最新版上核到了——逐字一致

1. 真实抛错点与误报点

// packages/attachment/attachment-local/src/store.ts:443
if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
  throw new AttachmentError('Attachment object is missing.', 'ATTACHMENT_NOT_FOUND')

// packages/llm/llm-deepseek/src/adapter.ts:66
throw new LlmError('DeepSeek Messages transport failed', 'TRANSPORT', { cause: error })

⇒ 你写的"真实原因是本地附件缺失、却被包成 TRANSPORT"完全成立。而且 cause 被保留了（{ cause: error }）——也就是说 ATTACHMENT_NOT_FOUND 并没有丢，只是没有出现在用户可见的那一层。这既是问题所在，也是最小修法的落点：把 cause 的 code 透出来（或对本地准备阶段的失败用一个独立的码），就不会再把排查往网络上引。

2. 你"HTTP 请求数为 0"这条证据很关键

它把"是不是网络问题"一步排掉了。建议放在正文最前面——否则 TRANSPORT 这个名字会先入为主。

同时请保留"重试也白费"这一点：TRANSPORT 在默认可重试集合里，于是每个失败 step 会退避重试 5 次、每次都必然失败（你实测的 llm/retry 0.5s→8s 那条链正是它）。对一个"本地文件不存在"的错误重试 5 次，是纯粹的延迟。

3. 两点建议

1. 报告里补一句"会话砖化"的后果：附件是内容寻址（objects/<sha256 前两位>/<sha256>），一旦被删且无备份，用户无法自行重建，该会话将永久无法再发消息。这是严重度论证的关键，比"报错难懂"重要得多；
2. 提一个自助出口：既然 cause 里已经有 ATTACHMENT_NOT_FOUND，可以据此明确告知"哪个附件丢了"并允许丢弃该引用后继续，而不是让整个会话不可用。

4. 版本提醒

你在 0.1.7-rc.2（含桌面端内置运行时）上复现——那就是当前最新，所以无需先升级。⚠️ 只是别把核换成 npm 的 latest（仍停在 0.1.5-rc.3，更旧）：

npm i -g @deepseek-ai/dsh@next

一条边界

我确认的是这两处代码在最新版上的现状（抛错点、包装点、cause 被保留）。你那套"删附件即砖化"的完整复现与实测数据以你为准——我没有实际删过对象文件来跑一遍。