鸿蒙HarmonyOS 多模态输入实战 —— 图片与文档输入智谱/DeepSeek

一、前言：多模态的"三个难题"

假设你让 Agent 接收用户拍的烘焙成品照片，分析烘焙效果。你查了智谱 API 文档，发现它支持image_url。你写了：

const message = new AgentMessage(MessageRole.user, [ ContentPart.image(base64Data) // 希望发送图片 ])

但你很快遇到三个难题：

1. 怎么构造图片 ContentPart？ContentPart没有公开的image()工厂。直接 new 吗？data 字段填什么？需要加data:image/jpeg;base64,前缀吗？

2. DeepSeek 不支持图片怎么办？如果用户选了 DeepSeek Provider 但发了图片，你要在什么时候拦截——发请求前？还是等 Provider 报错？

3. 文档输入怎么处理？PDF 文件的 base64 直接发给 Provider 吗？智谱和 DeepSeek 的文档格式一样吗？

这些问题涉及从领域模型、Provider 差异、到安全校验的完整链路。ArkAgent 用 ContentPart + MediaContent + Provider Profile + ContentCapabilityGuard 解决这些问题。

二、ContentPart：多模态内容的基本单位

2.1 ContentKind 五种类型

export enum ContentKind { text = 'text', image = 'image', audio = 'audio', video = 'video', document = 'document', unknown = 'unknown' // 未知类型保留 rawKind }

audio和video在 1.0 是保留类型——领域模型里有定义（序列化兼容），但 Provider 在网络调用前明确拒绝。ADR-0014 记录了这条决策："Domain 中既有 audio/video 类型为序列化兼容保留，1.0 Provider 必须在网络调用前明确拒绝。"

2.2 ContentPart 字段

export class ContentPart { readonly kind: ContentKind readonly rawKind?: string // 未知类型保留原始字符串 readonly text?: string readonly data?: string // base64 编码数据 readonly uri?: string // HTTPS URI readonly mimeType?: string readonly metadata?: JsonObject }

只有ContentPart.text()是公开静态工厂。图片和文档必须通过MediaContent工厂创建——因为它们需要额外校验（MIME 类型、大小限制、base64 合法性）。

2.3 rawKind：未知类型的 raw fallback

和 JSON 体系的"未知枚举保留 raw value"一致，ContentKind.unknown+rawKind保证了 Provider 升级新增内容类型时不会崩溃。

三、图片输入：Base64 与 data URL

3.1 MediaContent 工厂

// 图片工厂 MediaContent.imageFromBase64(base64Data, mimeType)

工厂内部做了两件事：

1. stripDataUrlPrefix：如果用户传的 base64 带data:image/jpeg;base64,前缀，先去掉前缀，只保留纯 base64 数据存在data字段。

2. metadata 记录 byteLengthEstimate：估算解码后字节大小，用于大小校验。

stripDataUrlPrefix的逻辑（domain/Media.ets）：

static stripDataUrlPrefix(source: string): string { const lower = source.substring(0, 5).toLowerCase() if (lower === 'data:') { const commaIdx = source.indexOf(',') if (commaIdx >= 0) { return source.substring(commaIdx + 1) // 去掉 "data:xxx;base64," 前缀 } } return source // 不含前缀，原样返回 }

这个函数的设计原则是"宽容输入，严格存储"——用户可能传带前缀的、也可能传不带的，工厂都接受，但data字段最终只存纯 base64。Wire 编码时再用buildDataUrl拼回完整格式。

buildDataUrl是stripDataUrlPrefix的逆操作：

static buildDataUrl(base64Data: string, mimeType: string): string { return `data:${mimeType};base64,${base64Data}` }

3.2 图片使用示例

import { ContentPart, MediaContent } from '@arkagent/core' // 方式一：从 base64 创建图片 Part const imagePart = MediaContent.imageFromBase64( 'iVBORw0KGgoAAAANSUhEUgAA...', // 纯 base64（无前缀） 'image/png' ) // 方式二：从 HTTPS URI 创建 const uriPart = ContentPart.imageFromUri( 'https://example.com/photo.jpg', 'image/jpeg' ) // 组装成消息 const message = new AgentMessage(MessageRole.user, [ ContentPart.text('分析这张烘焙成品照片'), imagePart ])

注意：imageFromUri只接受 HTTPS URI——和UrlUtil.ensureHttps的安全约束一致。

3.2 Provider 编码：image_url

智谱 VLM 模型接受 OpenAI 格式的image_url：

// ZhipuProviderProfile.encodeContentPart if (part.kind === ContentKind.image) { const caps = this.resolveModelCapability(modelId) if (!caps.supportsImageInput) { return Result.failure(ArkAgentError.config('unsupported_content', `Model ${modelId} does not support image input`)) } let url: string if (part.uri !== undefined && part.uri.length > 0) { url = part.uri // HTTPS URI 直接用 } else if (part.data !== undefined && part.data.length > 0) { url = MediaContent.buildDataUrl(part.data, part.mimeType ?? 'image/jpeg') // buildDataUrl 重新拼回 data URL 格式 } return Result.success(new JsonObject() .set('type', JsonValue.string('image_url')) .set('image_url', JsonValue.object(new JsonObject().set('url', JsonValue.string(url))))) }

关键：data字段存的是纯 base64（无前缀），Wire 编码时才用buildDataUrl拼回完整 data URL。这保证了存储格式和传输格式的分离。

3.3 持久化脱敏

图片的 base64 数据很大，持久化到 AgentState 会产生巨大的状态文件。MediaContent.redactForPersistence在 State encode 时剥离 base64：

// 持久化时 // 剥离 data 字段，记录 dataRedacted=true + dataChars + byteLengthEstimate // URI 经 sanitizeUriForPersistence 去掉 data: scheme、userinfo、query、fragment // 无可发载荷时返回 text 占位（toOmittedMediaPlaceholder）

为什么要去掉 URI 的 query？因为 CDN/OSS 的签名 token 藏在 query 参数里（?Signature=xxx&Expires=yyy）。如果原样持久化，签名 token 就泄漏到文件了。

3.4 sanitizeUriForPersistence 的处理

sanitizeUriForPersistence（domain/Media.ets）对 URI 做了四重清理：

// 1. 去掉 data: scheme（base64 数据不应在 URI 里持久化） // 2. 去掉 userinfo（https://user:pass@host 的 user:pass 部分） // 3. 去掉 query（?Signature=xxx&Expires=yyy 等签名参数） // 4. 去掉 fragment（#anchor）

清理后只保留scheme://host/path——足够标识"这是哪个资源"，但不泄漏任何凭据信息。

3.5 toOmittedMediaPlaceholder：无可发载荷时的占位

如果图片/文档既没有 data 也没有合法 uri（比如持久化后被脱敏了），redactForPersistence会生成一个 text 占位：

static toOmittedMediaPlaceholder(part: ContentPart): ContentPart { // 生成类似 "[image omitted: dataChars=12345 mime=image/png]" 的 text return ContentPart.text( `[${part.kind} omitted: dataChars=${part.data?.length ?? 0} mime=${part.mimeType ?? 'unknown'}]` ) }

关键设计：占位是 text block，不是带 metadata 标记的 image block。阶段 8 的踩坑告诉我们——带 metadata 标记的占位可以被伪造（伪造dataRedacted=true绕过校验），所以干脆用纯 text，让 Wire 层无从"信任"。

四、文档输入：三种策略

不同 Provider 对文档的支持差异巨大。ArkAgent 定义了三种DocumentWireStrategy：

export enum DocumentWireStrategy { native = 'native', // 原生 file_url（Provider 直接读取 HTTPS 文档） host_text = 'host_text', // 宿主提取文本（App 自己解析文档，发送纯文本） reject = 'reject' // 拒绝（不支持文档） }

4.1 智谱：native file_url

智谱 VLM 模型支持file_url：

// ZhipuProviderProfile — document + DocumentWireStrategy.native if (part.uri !== undefined && part.uri.length > 0) { return Result.success(new JsonObject() .set('type', JsonValue.string('file_url')) .set('file_url', JsonValue.object(new JsonObject() .set('url', JsonValue.string(part.uri))))) }

需要 HTTPS URI——智谱服务器直接读取这个 URL 的文档内容。

4.2 DeepSeek：host_text

DeepSeek 不支持原生文档输入，只接受宿主提取的文本：

// DeepSeekProviderProfile — document + DocumentWireStrategy.host_text // 拒绝 binary base64 if (part.data !== undefined && part.data.length > 0) { return Result.failure(ArkAgentError.config('unsupported_content', 'DeepSeek requires host-extracted text documents; binary base64 rejected')) } // 只接受纯文本，编码为带标签的 text block const labeled = `[document:${name};mime=${part.mimeType ?? 'text/plain'}]\n${part.text}` return Result.success(new JsonObject() .set('type', JsonValue.string('text')) .set('text', JsonValue.string(labeled)))

App 自己负责把 PDF/Word 解析成文本，然后以[document:name;mime=xxx]\n文本内容的格式发给 DeepSeek。

4.3 策略对照

4.4 智谱模型能力矩阵

智谱的模型按视觉能力分两类（docsCheckedAt: 2026-07-13）：

关键设计：未知模型默认 text-only（textOnlyCapability），不做名称启发式猜测。注释写得很明确："unknown zhipu model; text-only until listed in capability matrix"。新模型必须显式添加到能力矩阵和 Profile 测试里，不能靠模型名"猜"它支持什么。

DeepSeek 模型矩阵更简单——全部不支持图片，文档统一用 host_text：

五、⚠️ 踩坑一：DeepSeek 不支持图片

5.1 症状

用户选了 DeepSeek Provider，发了一张图片。如果直接发给 Provider，DeepSeek 返回错误——API 文档不记录图片输入能力。

5.2 修复：pre-call 拒绝

DeepSeek Profile 的encodeContentPart对图片直接返回 config error：

if (part.kind === ContentKind.image) { return Result.failure(ArkAgentError.config('unsupported_content', `DeepSeek model ${modelId} does not support image input per official API docs (2026-07-13)`)) }

错误在调用前（config 层）就拒绝，不浪费网络请求。错误信息注明了 API 文档验证日期（2026-07-13），方便后续复验。

5.3 教训

Provider 的能力差异必须在 Profile 里显式声明，不能"发了再说"。pre-call 校验比 Provider 报错体验好得多——用户能立即知道"这个 Provider 不支持图片"，而不是等了几秒后看到 Provider 的 400 错误。

六、ContentCapabilityGuard：不信任 public DTO

6.1 为什么不信任 public DTO

ContentPart是 public 类型，任何人都能构造——包括恶意的或错误的。比如有人构造了一个ContentPart(kind=image)但data是空的，或者mimeType是伪造的。如果 Wire 层直接信任这些字段，可能发出非法请求。

6.2 ContentCapabilityGuard

/** * Shared pre-call content validation used by OpenAIWireCodec. * Re-validates all media DTOs (do not trust public ContentPart constructors). */ export class ContentCapabilityGuard { static validateRequest(request: ModelRequest, profile: ProviderProfile, mediaLimits?: MediaLimits): Result<void, ArkAgentError> { // 对每个 message 的每个 part 做工厂等价复验 // 统计 imageCount / documentCount，超过 MediaLimits 报错 } }

Guard 在 Wire 编码前对每个 ContentPart 做"工厂等价复验"——用MediaContent.revalidateImagePart/revalidateDocumentPart重新校验，确保 data 合法、mimeType 在白名单内、大小不超限。

6.3 MediaLimits

export class MediaLimits { // base64 上限 7_000_000 字符（≈5 MiB 解码后） // 文档纯文本上限 200_000 字符 // 单请求最多 8 张图片 // 单请求最多 4 个文档 }

6.4 MIME 白名单

image: png / jpeg / jpg / webp / gif binary doc: application/pdf text doc: text/plain / markdown / csv / json / html

不在白名单的 MIME 类型直接拒绝。

七、⚠️ 踩坑二：伪造 metadata 绕过校验

7.1 症状

阶段 8 报告记录的踩坑：公共 metadata 布尔值被当作 provenance——有人伪造了dataRedacted: true标记，绕过了empty_media校验（Guard 看到dataRedacted=true就以为"数据已被合理省略"，实际数据从未存在过）。

7.2 修复

• 删除 Wire 侧的占位转换（不信任 metadata 标记）

• State encode 直接写 text 占位（不依赖标记）

• decode 用专用的recoverPartsAfterStateLoad

• 伪造标记零 HTTP 测试：构造dataRedacted=true但 data 为空的 ContentPart，断言它被拒绝且 HTTP=0

八、HeaderPolicy：敏感头脱敏

8.1 RESERVED headers

export class HeaderPolicy { static readonly RESERVED: string[] = [ 'authorization', 'content-type', 'accept', 'host', 'content-length', 'transfer-encoding', 'connection', 'proxy-authorization' ] }

RESERVED headers 不可被 custom headers 覆盖——如果业务试图设置这些 header，返回reserved_header错误（不静默丢弃）。

8.2 SENSITIVE 脱敏

static readonly SENSITIVE_NAME_HINTS: string[] = [ 'authorization', 'api-key', 'apikey', 'x-api-key', 'token', 'secret', 'password', 'cookie', 'set-cookie' ] static redactHeadersForLog(headers: HttpHeaders): JsonObject { // 敏感头的值输出为 *** }

所有日志输出的 header 都经过redactHeadersForLog脱敏——Authorization、Cookie、API Key 等一律变成***。

九、为什么 1.0 不做音视频

ADR-0014 的决策：

"用户于 2026-07-13 明确要求暂不支持 Responses、Gemini、Claude、Bedrock、音频和视频。"

"不为范围外能力创建空壳实现。Domain 中既有 audio/video 类型为序列化兼容保留，1.0 Provider 必须在网络调用前明确拒绝。"

这个决策的原则是不为范围外能力留空壳——空壳 API 容易被误用，不如明确拒绝。audio/video 在 Domain 里有定义（序列化兼容），但 Provider 层在网络调用前直接返回unsupported_content。

十、最佳实践清单

• ✅ 图片通过MediaContent.imageFromBase64工厂创建（有校验）。

• ✅data字段存纯 base64（无前缀），Wire 编码时拼 data URL。

• ✅ 持久化时剥离 base64（redactForPersistence）。

• ✅ 文档根据 Provider 策略选择编码方式（native file_url / host_text）。

• ✅ DeepSeek 文档用 host_text（带标签 text block）。

• ✅ 不支持的 content kind 在 pre-call（config 层）拒绝。

• ✅ Wire 编码前用ContentCapabilityGuard复验（不信任 public DTO）。

• ✅ RESERVED headers 不可被 custom headers 覆盖。

• ✅ 日志输出的 header 经redactHeadersForLog脱敏。

• ❌ 不信任 metadata 布尔标记作为 provenance。

• ❌ 不直接 new ContentPart（用工厂）。

十一、常见错误对照表

十二、验证清单

• 智谱 VLM 接受图片（image_url + data URL）

• 智谱 VLM 接受文档（file_url + HTTPS URI）

• 智谱文本模型拒绝图片（pre-call config error）

• DeepSeek 拒绝图片（pre-call config error）

• DeepSeek 文档用 host_text（带标签 text block）

• DeepSeek 文档拒绝 binary base64

• 图片超过 7M base64 被拒

• 单请求超过 8 图 / 4 文档被拒

• 非白名单 MIME 被拒

• 伪造 dataRedacted 被复验拦截（HTTP=0）

• 持久化后图片 base64 被剥离

• RESERVED headers 不可覆盖

• 日志 header 脱敏

• audio/video pre-call 拒绝

十三、构建验证

NODE_HOME=/Applications/DevEco-Studio.app/Contents/tools/node \ DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \ /Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw assembleHar --no-daemon

CompileArkTS passed BUILD SUCCESSFUL

测试覆盖：Phase8Multimodal.test.ets（audio/video 零 HTTP、forged dataRedacted、mixed_media_unsupported、host_text persist），覆盖 303 个用例。

十四、写在最后

图片走工厂加校验，base64 存纯不带缀。 持久化把数据剥，URI 去 query 防 token 漏。 文档三策看 Provider，native file_url 或 host_text。 DeepSeek 不吃图也不吃 PDF，宿主提取文本才靠谱。 Guard 不信 public DTO，工厂复验才放行。 metadata 标记可伪造，provenance 不能靠它定。 RESERVED 头不可盖，敏感头日志打星号。 audio video 1.0 不做，pre-call 拒绝不留壳。