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

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

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

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

但你很快遇到三个难题：

这些问题涉及从领域模型、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)

工厂内部做了两件事：

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 策略对照

Provider

图片

文档策略

文档编码

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 拒绝不留壳。