dsh-acp-enhanced 0.3.6 → 0.4.0

package/README-zh.md

@@ -16,6 +16,11 @@ ACP 线上。
   `agent_thought_chunk`），取消/重试不留半截输出
 - **完整遥测**：上下文用量环 + 缓存命中率 / TPS / 输入-输出-推理 token / 工具耗时 /
   轮次计数（`usage_update._meta` 携带全量明细）
+- **图片支持（多模态）**：当 dsh 组合挂载了附件存储（dsh 0.1.1-rc.2+，`dsh-base`
+  默认装配 `dsh-attachment-local`）时，会声明 `promptCapabilities.image` 并把粘贴/
+  上传的图片持久化进 harness 附件存储——支持视觉的模型（如 `deepseek-v4-flash-vision-exp`）
+  可按线序原生读取，图文交替不乱序。旧版栈（无附件存储）自动降级：不声明 image、
+  收到图片 prompt 明确报错。
 
 ### 模型与权限
 
@@ -211,11 +216,13 @@ node scripts/acp-client-tools.mjs     # 客户端工具测试（模拟 Zed 的 f
 node scripts/acp-mcp-test.mjs         # MCP 挂载测试（无模型调用）
 node scripts/acp-smoke-keyless.mjs    # keyless 冒烟（CI 用）
 node scripts/acp-resume-test.mjs      # 会话恢复测试
+node scripts/codec-image-test.mjs     # 图片编解码单元测试（无网络，假 store）
+node scripts/acp-image-e2e.mjs        # 图片能力端到端（vision 模型段需 API key）
 ```
 
 ## 已知限制
 
-仅 baseline prompt（无图片/音频附件）、文本按块粒度流式、每会话同时一个 in-flight
+不支持音频附件（不声明 audio 能力）、文本按块粒度流式、每会话同时一个 in-flight
 prompt。MCP 支持 stdio 与 streamable HTTP（不声明 legacy SSE / `acp` 传输）。
 `session/close` / `session/fork` / `session/resume` 未实现（不声明能力，合规客户端
 不会调用）；`session/delete` 因 dsh 持久化无官方删除 API，采用直接删除后端目录的方式。

package/README.md

@@ -18,6 +18,12 @@ over the ACP wire.
   torn output
 - **Full telemetry**: context usage ring plus cache hit rate / TPS / input-output-reasoning
   tokens / tool timing / turn counts (`usage_update._meta` carries the full breakdown)
+- **Image support (multimodal)**: when the dsh composition mounts an attachment store
+  (dsh 0.1.1-rc.2+ with `dsh-attachment-local`, the default in dsh-base), `promptCapabilities.image`
+  is advertised and pasted/uploaded images are ingested into the harness's durable attachment
+  store — a vision-capable model (e.g. `deepseek-v4-flash-vision-exp`) reads them natively,
+  in wire order with surrounding text. Older stacks (no attachment store) automatically
+  downgrade: image is not advertised and an image prompt is refused with a clear error.
 
 ### Model & permissions
 
@@ -229,13 +235,15 @@ node scripts/acp-client-tools.mjs     # client-tool tests (mocks Zed fs/terminal
 node scripts/acp-mcp-test.mjs         # MCP mount test (no model calls)
 node scripts/acp-smoke-keyless.mjs    # keyless boot smoke (CI)
 node scripts/acp-resume-test.mjs      # session resume test
+node scripts/codec-image-test.mjs     # image-codec unit tests (no network, fake store)
+node scripts/acp-image-e2e.mjs        # image capability e2e (vision-model leg needs an API key)
 ```
 
 ## Known limitations
 
-Baseline prompts only (no image/audio attachments), text streams at block granularity,
-one in-flight prompt per session. MCP supports stdio and streamable HTTP (legacy SSE /
-`acp` transports are not advertised).
+Audio attachments are not supported (audio capability is not advertised), text streams at
+block granularity, one in-flight prompt per session. MCP supports stdio and streamable HTTP
+(legacy SSE / `acp` transports are not advertised).
 `session/close` / `session/fork` / `session/resume` are not implemented (capabilities
 undeclared, compliant clients will not call them); `session/delete` removes the
 persisted directory directly because dsh persistence has no official delete API.

package/lib/codec.js

@@ -57,6 +57,191 @@ export function promptHasUnsupportedContent(prompt) {
   return prompt.some((block) => block.type !== 'text' && block.type !== 'resource_link')
 }
 
+/** Raster media types the harness attachment seam admits (dsh-attachment). */
+const IMAGE_MEDIA_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif'])
+
+/**
+ * Canonicalize an ACP image MIME type for the harness attachment store.
+ * @param mimeType - the client-declared type (may be `image/jpg`, which
+ *   the raster vocabulary spells `image/jpeg`).
+ * @returns the harness media type, or `undefined` when the value is not a
+ *   raster we ingest.
+ */
+export function canonicalImageMediaType(mimeType) {
+  const lower = String(mimeType ?? '').trim().toLowerCase()
+  const mapped = lower === 'image/jpg' ? 'image/jpeg' : lower
+  return IMAGE_MEDIA_TYPES.has(mapped) ? mapped : undefined
+}
+
+/** Error for prompt content this adapter does not advertise. */
+export class UnsupportedPromptContentError extends Error {
+  constructor(contentType) {
+    super(`unsupported prompt content type: ${contentType}`)
+    this.name = 'UnsupportedPromptContentError'
+  }
+}
+
+/** Error when an advertised image cannot be ingested (limits, decode, store). */
+export class PromptImageError extends Error {
+  constructor(message, options) {
+    super(message, options)
+    this.name = 'PromptImageError'
+  }
+}
+
+/**
+ * Narrow an unknown `ctx.attachments` value to the ingest surface used by
+ * {@link convertPrompt}. Capability detection instead of version detection:
+ * the service exists (with methods) on dsh 0.1.1-rc.2+, while the 0.1.0-rc.x
+ * seam is an empty shell without `validateImage`/`saveImage` — and a
+ * deployment without the attachment-local row has no service at all. All
+ * three fall back to `undefined` here, so the caller simply does not
+ * advertise image support.
+ * @param value - `ctx.get('attachments')` (or anything shaped like it).
+ * @returns the ingest surface, or `undefined` when absent/empty.
+ */
+export function attachmentIngestOf(value) {
+  if (value === null || typeof value !== 'object') return undefined
+  const candidate = value
+  if (typeof candidate.validateImage !== 'function' || typeof candidate.saveImage !== 'function') {
+    return undefined
+  }
+  const limits = candidate.imageLimits
+  if (limits === undefined
+    || typeof limits.maxImagesPerMessage !== 'number'
+    || typeof limits.maxMessageImageBytes !== 'number'
+    || typeof limits.maxImageBytes !== 'number') {
+    return undefined
+  }
+  return candidate
+}
+
+function decodeImageData(data) {
+  if (typeof data !== 'string' || data.length === 0) throw new PromptImageError('image data is empty')
+  const decoded = Buffer.from(data, 'base64')
+  if (decoded.byteLength === 0) throw new PromptImageError('image data is empty')
+  return new Uint8Array(decoded)
+}
+
+/** Display name from an image URI's leaf, with local path info stripped. */
+function imageName(uri) {
+  if (typeof uri !== 'string' || uri.length === 0) return undefined
+  let leaf
+  try {
+    leaf = new URL(uri).pathname.split('/').filter(Boolean).at(-1)
+  } catch {
+    leaf = uri.split(/[/\\]/).filter(Boolean).at(-1)
+  }
+  if (leaf === undefined || leaf.length === 0) return undefined
+  try {
+    return decodeURIComponent(leaf)
+  } catch {
+    return leaf
+  }
+}
+
+/** Flush accumulated text into the block list (keeps 图文交替 wire order). */
+function flushText(parts, blocks) {
+  const text = parts.join('')
+  parts.length = 0
+  if (text.length > 0) blocks.push({ type: 'text', text })
+}
+
+/**
+ * Convert an ACP prompt's content blocks into harness user-message content
+ * blocks. Text and resource links concatenate in wire order; when the
+ * composition provides an attachment ingest, ACP `image` blocks are decoded,
+ * admission-checked against the store limits, and durably committed with
+ * `saveImage`, keeping block order with surrounding text. Binary `resource`
+ * payloads and audio stay rejected — silently dropping them would be worse
+ * than refusing.
+ * @param prompt - ACP `session/prompt` content, in wire order.
+ * @param attachments - `ctx.attachments` ingest when the composition mounted
+ *   one; omit (or pass `undefined`) to refuse images.
+ * @returns `{ blocks, displayText }` ready for `createUserMessage` plus a
+ *   human-readable text rendering (used for titles, transcripts, commands).
+ * @throws UnsupportedPromptContentError for audio/binary blocks, or images
+ *   with no ingest; PromptImageError when advertised image bytes fail
+ *   admission.
+ */
+export async function convertPrompt(prompt, attachments) {
+  const preparedImages = []
+  for (const block of prompt) {
+    if (block?.type !== 'image') continue
+    if (attachments === undefined) throw new UnsupportedPromptContentError('image')
+    const mediaType = canonicalImageMediaType(block.mimeType)
+    if (mediaType === undefined) throw new PromptImageError(`unsupported image media type: ${block.mimeType}`)
+    const data = decodeImageData(block.data)
+    preparedImages.push({
+      data,
+      mediaType,
+      ...imageName(block.uri) === undefined ? {} : { name: imageName(block.uri) },
+    })
+  }
+
+  if (preparedImages.length > 0) {
+    const { maxImagesPerMessage, maxMessageImageBytes, maxImageBytes } = attachments.imageLimits
+    if (preparedImages.length > maxImagesPerMessage) {
+      throw new PromptImageError('prompt exceeds the configured image-count limit')
+    }
+    const totalBytes = preparedImages.reduce((sum, image) => sum + image.data.byteLength, 0)
+    if (totalBytes > maxMessageImageBytes) {
+      throw new PromptImageError('prompt exceeds the configured aggregate image-byte limit')
+    }
+    for (const image of preparedImages) {
+      if (image.data.byteLength > maxImageBytes) {
+        throw new PromptImageError('image exceeds the configured encoded-byte limit')
+      }
+      try {
+        await attachments.validateImage({ data: image.data, mediaType: image.mediaType, ...image.name === undefined ? {} : { name: image.name } })
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        throw new PromptImageError(`image validation failed: ${message}`, { cause: error })
+      }
+    }
+  }
+
+  const parts = []
+  const display = []
+  const blocks = []
+  let imageIndex = 0
+  for (const block of prompt) {
+    switch (block?.type) {
+      case 'text':
+        parts.push(block.text)
+        display.push(block.text)
+        break
+      case 'resource_link':
+        // Mirror the baseline bridge's textual reference so plain clients
+        // keep file mentions without the bridge dropping them.
+        parts.push(`\n[resource_link name=${JSON.stringify(block.name)} uri=${JSON.stringify(block.uri)}]\n`)
+        display.push(`@${block.name}`)
+        break
+      case 'image': {
+        if (attachments === undefined) throw new UnsupportedPromptContentError('image')
+        const prepared = preparedImages[imageIndex]
+        imageIndex += 1
+        if (prepared === undefined) throw new PromptImageError('image block was not prepared')
+        flushText(parts, blocks)
+        let attachment
+        try {
+          attachment = await attachments.saveImage(prepared)
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error)
+          throw new PromptImageError(message, { cause: error })
+        }
+        blocks.push({ type: 'image', attachment })
+        display.push(`[image${prepared.name === undefined ? '' : `: ${prepared.name}`}]`)
+        break
+      }
+      default:
+        throw new UnsupportedPromptContentError(block?.type ?? 'unknown')
+    }
+  }
+  flushText(parts, blocks)
+  return { blocks, displayText: display.join(' ').trim() }
+}
+
 /** Kramdown attribute-style inline markup (SiYuan exports), including
  *  truncation-damaged tails — titles are byte-budgeted upstream, so a cut
  *  can land mid-attribute (unterminated `"` or no closing `]`):

package/lib/index.js

@@ -47,7 +47,15 @@ import { createUserMessage, errorChain, ReasoningEffortId } from '@deepseek-ai/d
 import { installModelSelection } from '@deepseek-ai/dsh-agent'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { SessionId } from '@deepseek-ai/dsh-session'
-import { acpPromptToText, promptHasUnsupportedContent, sanitizeWireTitle, turnEndToStopReason, usageTelemetry } from './codec.js'
+import {
+  attachmentIngestOf,
+  convertPrompt,
+  PromptImageError,
+  sanitizeWireTitle,
+  turnEndToStopReason,
+  UnsupportedPromptContentError,
+  usageTelemetry,
+} from './codec.js'
 
 /** Agent version advertised on the ACP wire — read from package.json so the
  *  handshake can never drift from the released package version. */
@@ -560,6 +568,21 @@ export function apply(ctx, config) {
           // Final accounting when the adapter reported usage on the message
           // rather than as a stream chunk.
           if (event.data.usage !== undefined) emitUsage(record, event.data.usage, event)
+          // Model-produced image blocks never stream through the text chunk
+          // path; surface them as a wire placeholder so the reply is not
+          // silently missing a block (ACP clients render the text).
+          for (const block of event.data.message?.content ?? []) {
+            if (block?.type === 'image' && block.attachment?.attachmentId !== undefined) {
+              notify({
+                sessionId: session.header.id,
+                update: {
+                  sessionUpdate: 'agent_message_chunk',
+                  messageId: record.messageId,
+                  content: { type: 'text', text: `[image attachment ${block.attachment.attachmentId}]` },
+                },
+              })
+            }
+          }
           break
         case 'turn/start': {
           record.turnCount += 1
@@ -1585,6 +1608,11 @@ export function apply(ctx, config) {
     const parts = []
     for (const block of content ?? []) {
       if (block?.type === 'text' && typeof block.text === 'string') parts.push(block.text)
+      else if (block?.type === 'image' && block.attachment?.attachmentId !== undefined) {
+        // Model-produced images replay as a textual reference — the wire
+        // surface does not carry attachment bytes.
+        parts.push(`[image attachment ${block.attachment.attachmentId}]`)
+      }
     }
     return parts.join('\n')
   }
@@ -1689,7 +1717,15 @@ export function apply(ctx, config) {
             // workspace root on session/new / session/load instead of showing
             // the "doesn't currently support multi-root workspaces" callout).
             sessionCapabilities: { list: {}, delete: {}, additionalDirectories: {} },
-            promptCapabilities: { image: false, audio: false, embeddedContext: false },
+            // Image support is a live capability: the harness advertises
+            // `image: true` only when the composition mounted a working
+            // attachment store (duck-typed, so dsh 0.1.1-rc.2+ with
+            // dsh-attachment-local enables it and older stacks report false).
+            promptCapabilities: {
+              image: attachmentIngestOf(ctx.get('attachments')) !== undefined,
+              audio: false,
+              embeddedContext: false,
+            },
             // Stdio MCP servers always work; streamable HTTP maps onto
             // dsh-mcp-client's second transport. Legacy SSE does not.
             mcpCapabilities: { http: true, sse: false },
@@ -1810,10 +1846,28 @@ export function apply(ctx, config) {
         if (record.inflight !== undefined) {
           throw invalidParams('a prompt is already in flight for this session')
         }
-        if (promptHasUnsupportedContent(params.prompt)) {
-          throw invalidParams('only text and resource_link prompt content is supported')
+        // Capability-gated content conversion: text/resource_link always work;
+        // image blocks are ingested through the composition's attachment
+        // store when one is mounted (advertised on initialize). A client that
+        // sends unsupported content gets the exact failing kind — never a
+        // silent drop — and an image that fails admission (bad type, over
+        // limits, store rejection) surfaces its precise reason.
+        let blocks
+        let text
+        try {
+          const ingest = attachmentIngestOf(ctx.get('attachments'))
+          const converted = await convertPrompt(params.prompt, ingest)
+          blocks = converted.blocks
+          text = converted.displayText
+        } catch (error) {
+          if (error instanceof UnsupportedPromptContentError) {
+            throw invalidParams(error.message)
+          }
+          if (error instanceof PromptImageError) {
+            throw invalidParams(`image rejected: ${error.message}`)
+          }
+          throw error
         }
-        const text = acpPromptToText(params.prompt)
         if (text.trim().length === 0) throw invalidParams('empty prompt')
 
         // Insurance: by the first prompt the client is guaranteed to know the
@@ -1861,7 +1915,7 @@ export function apply(ctx, config) {
         if (ctx.agents.get(record.agent.id) !== record.agent) {
           throw internalError('prompt was not queued: the agent was disposed outside the bridge')
         }
-        const message = createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })
+        const message = createUserMessage({ content: blocks, source: { kind: 'user' } })
         if (process.env.ACP_DEBUG) process.stderr.write(`[acp-debug] followup queued, agent phase=${record.agent.phase?.kind} inboxPending=${record.agent.inbox?.hasPending}\n`)
         const stopReason = await new Promise((resolve, reject) => {
           const inflight = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-acp-enhanced",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Enhanced ACP server for DeepSeek Harness: block-level streaming, usage/stat telemetry (cache hit rate, token speed, input/output tokens, context length, turns, tool timing), model & reasoning-effort switching, and permission-preset control over the ACP wire (Zed-friendly)",
   "keywords": [
     "dsh",