# 第九阶段 · 模块九 · 第一节：多模态能力
Claude Code 如何处理图像？图像处理的限制是什么？多模态功能的实现原理是什么？
Claude Code 全局架构
┌─────────────────────────────────────────────────────────────────────┐
│ 高级主题 │
│ │
│ 多模态能力 ← 本节 │
│ ├── 图像处理 ──> imageResizer.ts │
│ ├── 图像验证 ──> imageValidation.ts │
│ └── API 限制 ──> apiLimits.ts │
└─────────────────────────────────────────────────────────────────────┘
多模态 = 多种模态的输入/输出
Claude Code 支持：
┌─────────────────────────────────────────────────────────────────────┐
│ 文本 ──> 支持 │
│ 图像 ──> 支持 │
│ 音频 ──> 部分支持 │
│ 视频 ──> 未来支持 │
└─────────────────────────────────────────────────────────────────────┘
Claude Code 可以：
- 读取图像文件
- 处理截图
- 分析图表
- 理解 UI 界面
问 1：Claude Code 能生成图像吗？
// 不能
// Claude Code 是 CLI 工具，不是图像生成模型
// 图像生成需要使用专门的模型（如 DALL-E）
// Claude Code 可以调用图像生成工具
源码位置：`src/utils/imageResizer.ts`
用户粘贴/拖拽图像
│
▼
验证图像格式
│
▼
检查图像大小
│
▼
调整图像尺寸（如果需要）
│
▼
转换为 base64
│
▼
发送给 API
源码位置：`src/utils/imageResizer.ts` 第 29 行
type ImageMediaType =
| 'image/png'
| 'image/jpeg'
| 'image/gif'
| 'image/webp'
源码位置：`src/constants/apiLimits.ts`
// API 限制
API_IMAGE_MAX_BASE64_SIZE = 5MB // base64 编码后最大 5MB
IMAGE_MAX_WIDTH = 1568 // 最大宽度
IMAGE_MAX_HEIGHT = 1568 // 最大高度
IMAGE_TARGET_RAW_SIZE = 400KB // 目标原始大小
问 1：为什么需要调整图像大小？
// 问题：
// 1. API 有 5MB base64 大小限制
// 2. 大图像传输慢、费用高
// 3. 视觉模型有分辨率限制
// 解决方案：
// Claude Code 使用 Sharp 库调整图像大小
// 确保图像在限制范围内
源码位置：`src/utils/imageValidation.ts`
export function validateImagesForAPI(messages: unknown[]): void {
// 1. 检查每张图像的大小
// 2. 如果超过限制，抛出 ImageSizeError
// 3. 用户需要先调整图像大小
}
export class ImageSizeError extends Error {
constructor(oversizedImages: OversizedImage[], maxSize: number) {
const message =
`Image base64 size exceeds API limit. ` +
`Please resize the image before sending.`;
super(message);
}
}
// 注意：API 的 5MB 限制适用于 base64 编码后的字符串长度
// 不是解码后的原始字节
// 计算：
// base64_size ≈ raw_bytes * 4 / 3
// 所以 5MB base64 ≈ 3.75MB 原始图像
问 1：如何处理过大的图像？
// Claude Code 会自动处理：
// 1. 检查图像大小
if (image.size > API_IMAGE_MAX_BASE64_SIZE) {
// 2. 使用 Sharp 调整大小
const resized = await sharp(image.buffer)
.resize(IMAGE_MAX_WIDTH, IMAGE_MAX_HEIGHT, { fit: 'inside' })
.toBuffer();
// 3. 如果还是太大，继续压缩质量
if (resized.length > TARGET_RAW_SIZE) {
return sharp(resized).jpeg({ quality: 80 }).toBuffer();
}
}
源码位置：`src/tools/FileReadTool/imageProcessor.ts`
import { getImageProcessor, type SharpFunction } from '../FileReadTool/imageProcessor.js'
// 获取 Sharp 实例
const sharp = getImageProcessor();
// 调整图像大小
async function resizeImage(
buffer: Buffer,
maxWidth: number,
maxHeight: number
): Promise<Buffer> {
return sharp(buffer)
.resize(maxWidth, maxHeight, {
fit: 'inside', // 保持比例
withoutEnlargement: false, // 允许放大
})
.toBuffer();
}
// 错误类型
const ERROR_TYPE_MODULE_LOAD = 1 // 模块加载失败
const ERROR_TYPE_PROCESSING = 2 // 处理失败
const ERROR_TYPE_PIXEL_LIMIT = 4 // 像素限制
const ERROR_TYPE_MEMORY = 5 // 内存不足
const ERROR_TYPE_TIMEOUT = 6 // 处理超时
const ERROR_TYPE_VIPS = 7 // VIPS 库错误
const ERROR_TYPE_PERMISSION = 8 // 权限错误
// 抛出错误
export class ImageResizeError extends Error {
constructor(message: string) {
super(message);
this.name = 'ImageResizeError';
}
}
问 1：Sharp 是什么？
// Sharp 是 Node.js 的图像处理库
// 基于 libvips，性能高效
// 支持：
// - 调整大小
// - 格式转换
// - 质量调整
// - 裁剪、旋转、翻转
// 用户可以：
// 1. 粘贴剪贴板中的图像
// 2. 拖拽图像文件到终端
// 3. 使用 /screenshot 命令
// Claude Code 自动处理图像
// 用户无需手动调整
// 图像在消息中表示为 image 块
{
type: 'image',
source: {
type: 'base64',
media_type: 'image/png',
data: 'iVBORw0KGgoAAAANSUhEUgAAAAE...'
}
}
问 1：图像会被缓存吗？
// 会的
// Claude Code 会缓存已处理的图像
// 减少重复处理
// 缓存策略：
// - 基于图像 hash
// - 缓存大小有限制
// - LRU 淘汰策略
// 图像处理的性能成本：
// - CPU：调整大小、格式转换
// - 内存：加载大图像
// - 网络：传输 base64 数据
// 建议：
// 1. 使用较小的图像
// 2. 优先使用 PNG（无损）
// 3. 避免发送重复的大图像
// API 成本按 token 计费
// 图像转换为 token 取决于：
// 1. 图像尺寸
// 2. 图像复杂度
// 3. 压缩质量
// 估算：1MB 图像 ≈ 1000-2000 tokens
问 1：如何减少图像处理的成本？
// 方法：
// 1. 减小图像尺寸
// - 调整到 800x600 通常足够
// - 避免使用原始截图
// 2. 降低图像质量
// - JPEG quality=80 通常足够清晰
// - 避免使用 PNG（无损但大）
// 3. 裁剪到感兴趣区域
// - 只发送需要分析的部分
答案：
// 主要原因：
// 1. API 限制
// - Anthropic API 对图像大小有限制
// - base64 编码后最大 5MB
// 2. 性能考虑
// - 大图像传输慢
// - 处理成本高
// 3. 视觉模型限制
// - 过高分辨率不会提升效果
// - 反而增加成本
答案：
// Claude Code 支持的格式：
// - PNG
// - JPEG
// - GIF
// - WebP
// 不支持的格式需要转换：
// 1. 使用 ImageMagick 转换
convert input.heic output.png
// 2. 使用在线工具
// 3. 截图时选择支持的格式
答案：
// 常见错误：
// 1. Sharp 模块加载失败
// - 解决方案：重新安装 Claude Code
// 2. 图像格式不支持
// - 解决方案：转换为支持的格式
// 3. 内存不足
// - 解决方案：使用更小的图像
// 4. 权限错误
// - 解决方案：检查文件权限
| 文件 | 核心内容 |
| `src/utils/imageResizer.ts` | 图像调整大小 |
| `src/utils/imageValidation.ts` | 图像验证 |
| `src/constants/apiLimits.ts` | API 限制常量 |
下一节我们将深入 思维链提示：
- thinking mode 的原理
- 思维过程的可视化
- 如何利用思维链提升效果
*- 第一轮：□ 事实准确性*
*- 第二轮：□ 深度与洞见*
*- 第三轮：□ 可读性与价值*