Files
deepseek-harness/docs/subsystems/attachment.md
T
pku-xht 84cbec28e9 Merge remote-tracking branch 'origin/master' into codex/localized-chinese-doc-links
# Conflicts:
#	.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.i18n.yaml
#	.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.zh.md
#	.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
#	.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
#	.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
#	.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.i18n.yaml
#	.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.zh.md
#	.agents/notes/implemented/bug-fix/2026-08-18-request-image-payload-bound.i18n.yaml
#	.agents/notes/implemented/bug-fix/2026-08-18-request-image-payload-bound.zh.md
#	.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
#	.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
#	.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
#	.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
#	.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
#	.agents/notes/implemented/feature/2026-07-22-web-multimodal-image-input-and-durable-attachments.i18n.yaml
#	.agents/notes/implemented/feature/2026-07-22-web-multimodal-image-input-and-durable-attachments.zh.md
#	.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
#	.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml
#	.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
#	.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
#	.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
#	.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
#	.agents/notes/implemented/feature/2026-08-05-agent-teams.i18n.yaml
#	.agents/notes/implemented/feature/2026-08-05-agent-teams.zh.md
#	.agents/notes/implemented/feature/2026-08-11-workspace-sidebar-order-and-folding.i18n.yaml
#	.agents/notes/implemented/feature/2026-08-15-product-subagent-noninteractive-permissions.i18n.yaml
#	.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
#	.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
#	.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml
#	.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md
#	.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
#	.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
#	.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
#	.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
#	.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.i18n.yaml
#	.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md
#	.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
#	README.i18n.yaml
#	README.zh.md
#	docs/architecture.i18n.yaml
#	docs/architecture.zh.md
#	docs/development.i18n.yaml
#	docs/development.zh.md
#	docs/persistence-catalog.i18n.yaml
#	docs/persistence-catalog.zh.md
#	docs/subsystems/README.i18n.yaml
#	docs/subsystems/README.zh.md
#	docs/subsystems/agent-team.i18n.yaml
#	docs/subsystems/agent-team.zh.md
#	docs/subsystems/client-modules.i18n.yaml
#	docs/subsystems/client-modules.zh.md
#	docs/subsystems/commands.i18n.yaml
#	docs/subsystems/commands.zh.md
#	docs/subsystems/persistence.i18n.yaml
#	docs/subsystems/persistence.zh.md
#	docs/subsystems/session-reference.i18n.yaml
#	docs/tool-catalog.i18n.yaml
#	docs/tool-catalog.zh.md
#	docs/user/guide/providers.i18n.yaml
#	docs/user/guide/providers.zh.md
#	packages/README.i18n.yaml
#	packages/README.zh.md
#	packages/bundle/web-app/README.i18n.yaml
#	packages/bundle/web-app/README.zh.md
#	packages/client/README.i18n.yaml
#	packages/client/README.zh.md
#	packages/client/connection/README.i18n.yaml
#	packages/client/connection/README.zh.md
#	packages/client/ui-conversation/README.i18n.yaml
#	packages/client/ui-conversation/README.zh.md
#	packages/client/ui-primitives/README.i18n.yaml
#	packages/client/ui-primitives/README.zh.md
#	packages/client/ui-sidebar/README.i18n.yaml
#	packages/client/ui-sidebar/README.zh.md
#	packages/client/ui-workspace/README.i18n.yaml
#	packages/client/ui-workspace/README.zh.md
#	packages/context/README.i18n.yaml
#	packages/context/README.zh.md
#	packages/core/agent-loop/README.i18n.yaml
#	packages/credentials/README.i18n.yaml
#	packages/credentials/README.zh.md
#	packages/experimental/agent-team/README.i18n.yaml
#	packages/experimental/agent-team/README.zh.md
#	packages/experimental/tool-agent-team/README.i18n.yaml
#	packages/experimental/tool-agent-team/README.zh.md
#	packages/host/frontend-static/README.i18n.yaml
#	packages/host/frontend-static/README.zh.md
#	packages/host/webserver/README.i18n.yaml
#	packages/host/webserver/README.zh.md
#	packages/interaction/commands/README.i18n.yaml
#	packages/interaction/commands/README.zh.md
#	packages/plan/plan-mode/README.i18n.yaml
#	packages/plan/plan-mode/README.zh.md
#	packages/sandbox/sandbox-local/README.i18n.yaml
#	packages/sandbox/sandbox-local/README.zh.md
#	packages/session/README.i18n.yaml
#	packages/session/README.zh.md
#	packages/session/session-persistence-sqlite/README.i18n.yaml
#	packages/session/session-persistence-sqlite/README.zh.md
#	packages/session/session-projection-cache/README.i18n.yaml
#	packages/session/session-projection-cache/README.zh.md
#	packages/shell/tool-pwsh/README.i18n.yaml
#	packages/shell/tool-pwsh/README.zh.md
#	packages/subagent/subagent-codex/README.i18n.yaml
#	packages/subagent/subagent-codex/README.zh.md
#	packages/subagent/subagent/README.i18n.yaml
#	packages/subagent/subagent/README.zh.md
#	packages/web/tool-web/README.i18n.yaml
#	packages/web/tool-web/README.zh.md
#	scripts/snapshots/translation-prompt-v4/request-response.expected.json
2026-08-20 19:15:33 +08:00

6.8 KiB

Durable Image Attachments

English | 中文

The attachment seam separates binary image ownership from the session log. A producer gives validated encoded bytes to ctx.attachments; the service publishes an immutable content-addressed reference only after the object is durable. Session events and model-visible ImageBlocks contain that reference and metadata, never a browser object URL, host temporary path, provider URL, or base64 payload.

Unsent browser drafts may stay in memory and native clients may stage them in operating-system temporary storage. Once the host accepts a user message, its images move below <DSH_HOME>/attachments/v1 before the user event is appended. Structured model image output follows the same persist-before-event rule.

Source: packages/attachment/attachment/src/types.ts

Identity and verified metadata

AttachmentId is a branded opaque string. The local backend currently emits sha256:<digest>, but consumers must neither parse that representation nor derive a filesystem path from it.

/** Raster image formats accepted by the version-one attachment path. */
type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif'
/** Durable, serializable metadata for one immutable image object. */
interface ImageAttachmentRef {
  /** Opaque storage identifier; never a filesystem path or bearer URL. */
  attachmentId: AttachmentId
  /** Media type verified from the stored bytes. */
  mediaType: ImageMediaType
  /** Exact encoded byte length. */
  bytes: number
  /** Intrinsic encoded width in pixels. */
  width: number
  /** Intrinsic encoded height in pixels. */
  height: number
  /** Optional display name stripped of local path information. */
  name?: string
}
/** Deployment-resolved limits used by upload admission and request buffering. */
interface ImageAttachmentLimits {
  maxImageBytes: number
  maxImagesPerMessage: number
  maxMessageImageBytes: number
  maxImagePixels: number
  /** Maximum intrinsic width and maximum intrinsic height in pixels for one image. */
  maxImageDimension: number
  mediaTypes: readonly ImageMediaType[]
}

The reference records intrinsic dimensions and encoded length so clients can lay out history without decoding first, while every authoritative read still re-checks digest, media signature, dimensions, and metadata against the object.

Commit and verified-read payloads

/** Base64-encoded image upload accompanying one wire request. */
interface EncodedImageAttachment {
  /** Declared media type, verified against the decoded bytes during admission. */
  mediaType: ImageMediaType
  /** Canonical base64 encoding of the image bytes. */
  data: string
  /** Optional display name; it is never interpreted as a path. */
  name?: string
}
/** Request to validate and durably commit one image. */
interface SaveImageAttachment {
  data: Uint8Array
  /** Caller-declared media type, checked against fully decoded bytes. */
  mediaType: ImageMediaType
  /** Optional browser/provider display name; it is never interpreted as a path. */
  name?: string
}
/** Stored image bytes returned after reference and digest verification. */
interface StoredImageAttachment {
  ref: ImageAttachmentRef
  data: Uint8Array
}

saveImage() validates bytes and atomically commits one object before returning its reference. validateImage() runs the same admission checks without persisting anything; batch callers validate every member through it before saving any member, so validation rejection leaves no partial objects behind. admitEncodedImages() is the wire entry for base64 uploads: it enforces canonical base64, then delegates batch admission to saveImages(), which owns the count and aggregate-byte limits and the validate-all-before-save order. readImage() accepts a reference from an authorized session path and returns bytes only after integrity verification. The service is deliberately retention-neutral: resumed and forked sessions may share objects, so reference-aware garbage collection is deferred rather than tied to any one session's deletion.

Cordis API

Generated from source by scripts/gen-cordis-catalog.ts (verified fresh by pnpm run verify-cordis-catalog in doc-sync; regenerate with pnpm run gen-cordis-catalog) — the language sides differ only in locale-specific paired document paths. Signature blocks use a ts cordis-catalog fence and keep the original source JSDoc; dispatch modes are defined in the primer, and the framework-inherited ctx API lives in cordis-api/inherited.md.

ctx.attachments — AttachmentStore (abstract seam)

Immutable binary attachment service. Implementations validate bytes before publishing a reference.

/**
 * Validate one image without persisting it.
 * Batch callers validate every member before saving any member.
 * @param input - encoded bytes, declared media type, and optional display name.
 * @returns completion after the encoded raster has been fully decoded.
 */
abstract validateImage(input: SaveImageAttachment): Promise<void>

/**
 * Validate one ordered image batch before committing any member.
 * Validation failures start no writes; storage failures return no partial
 * references, although already published content-addressed objects may stay
 * unreachable until a future retention policy collects them.
 * @param inputs - encoded images in their owning message order.
 * @returns durable references in the exact input order.
 */
async saveImages(inputs: readonly SaveImageAttachment[]): Promise<readonly ImageAttachmentRef[]>

/**
 * Validate and durably commit one image before its owning session event is appended.
 * @param input - encoded bytes, declared media type, and optional display name.
 * @returns a durable content-addressed reference.
 */
abstract saveImage(input: SaveImageAttachment): Promise<ImageAttachmentRef>

/**
 * Read one image and verify that bytes still match the recorded reference.
 * @param ref - durable reference from the session log.
 * @param signal - optional cancellation for backend read and verification work.
 * @returns the verified bytes and canonical reference.
 * @throws the signal reason when aborted, or a storage error when verification fails.
 */
abstract readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>

Source: packages/attachment/attachment/src/index.ts:33