# 灵隙协议实现规范：内容类型系统 > 版本：1.0.0 | 层级：实现层 根据 [v0/06-implementation-details.md](../v0/06-implementation-details.md) 的第2章内容，本文档定义 Synapse 协议内容类型系统的完整规范，涵盖传输模式、内容编码、结构化内容类型定义及 MIME 类型常量。 --- ## 1. 传输模式 传输模式决定内容数据在 Agent 之间的传递方式，根据数据大小和实时性需求选择最佳模式。 ```go type TransferMode string const ( TransferInline TransferMode = "inline" // 内嵌传输（base64 编码） TransferURL TransferMode = "url" // URL 引用传输 TransferStreaming TransferMode = "streaming" // 流式传输 TransferMultipart TransferMode = "multipart" // Multipart 表单传输 ) ``` ### 1.1 文件大小阈值 | 模式 | 适用范围 | 说明 | |------|---------|------| | `inline` | ≤ 1MB | 数据直接嵌入消息体，适用于小文件 | | `url` | > 1MB | 通过 URL 引用下载，适用于中等文件 | | `streaming` | > 1MB | 流式分片传输，适用于大文件或实时数据流 | | `multipart` | 任意大小 | 表单形式上传，适用于文件上传场景 | ``` // 文件大小阈值判定逻辑 // size <= 1MB → inline // size > 1MB → url 或 streaming ``` ### 1.2 ContentBase 所有内容类型共享的基础结构： ```go type ContentBase struct { Type TransferMode `json:"type"` ContentType string `json:"content_type"` // MIME 类型 Encoding ContentEncoding `json:"encoding,omitempty"` // 内容编码 Size int64 `json:"size,omitempty"` // 原始大小（字节） EncodedSize int64 `json:"encoded_size,omitempty"` // 编码后大小（字节） Checksum string `json:"checksum,omitempty"` // SHA-256 校验和 Metadata map[string]any `json:"metadata,omitempty"` // 扩展元数据 } ``` --- ## 2. 内容编码 内容编码定义了原始数据在传输前的编码/压缩方式。 ```go type ContentEncoding string const ( EncodingNone ContentEncoding = "none" // 无编码 EncodingBase64 ContentEncoding = "base64" // Base64 编码 EncodingGzip ContentEncoding = "gzip" // Gzip 压缩 EncodingDeflate ContentEncoding = "deflate" // Deflate 压缩 ) ``` | 编码 | 适用场景 | 说明 | |------|---------|------| | `none` | 纯文本、JSON | 无需额外编码，直接传输原始数据 | | `base64` | 二进制数据 inline 传输 | 将二进制数据编码为 ASCII 字符串 | | `gzip` | 大文本、代码、JSON | 高压缩比，适合网络传输 | | `deflate` | 通用压缩场景 | 基于 DEFLATE 算法，兼容性好 | --- ## 3. 内容类型定义 ### 3.1 文本内容（TextContent） 纯文本内容，支持字符集和语言声明。 ```go type TextContent struct { ContentBase Charset string `json:"charset"` // 字符集（默认 "utf-8"） Language string `json:"language,omitempty"` // 语言代码（如 "zh-CN", "en-US"） Data string `json:"data"` // 文本数据 } ``` | 字段 | 类型 | 必填 | 说明 | |------|------|:----:|------| | `charset` | string | ✓ | 字符集编码，默认 `"utf-8"` | | `language` | string | - | 语言代码，遵循 BCP 47 标准 | | `data` | string | ✓ | 文本内容数据 | **示例**： ```json { "type": "inline", "content_type": "text/plain", "encoding": "none", "charset": "utf-8", "language": "zh-CN", "data": "你好，世界！" } ``` --- ### 3.2 JSON 内容（JSONContent） 结构化 JSON 数据，支持 Schema 验证。 ```go type JSONContent struct { ContentBase Schema string `json:"schema,omitempty"` // Schema 标识（如 JSON Schema URI） SchemaURL string `json:"schema_url,omitempty"` // Schema 外部引用 URL Data any `json:"data"` // JSON 数据（任意合法 JSON 值） } ``` | 字段 | 类型 | 必填 | 说明 | |------|------|:----:|------| | `schema` | string | - | Schema 标识符，用于接收方识别数据结构 | | `schema_url` | string | - | Schema 的外部访问地址，可在线获取 Schema 定义 | | `data` | any | ✓ | 任意合法的 JSON 值（object、array、string、number、boolean） | **示例**： ```json { "type": "inline", "content_type": "application/json", "encoding": "none", "schema": "https://schema.synapse.com/v1/agent-info", "data": { "agent_id": "agent-001", "name": "智能助手", "version": "1.2.0" } } ``` --- ### 3.3 代码内容（CodeContent） 源代码或脚本内容，支持多文件依赖声明。 ```go type CodeContent struct { ContentBase Language string `json:"language"` // 编程语言（如 "go", "python", "javascript"） Version string `json:"version,omitempty"` // 语言版本（如 "3.11", "1.21"） Dependencies []string `json:"dependencies,omitempty"` // 依赖列表（包名或模块名） Data string `json:"data"` // 源代码内容 } ``` | 字段 | 类型 | 必填 | 说明 | |------|------|:----:|------| | `language` | string | ✓ | 编程语言标识 | | `version` | string | - | 语言运行时版本 | | `dependencies` | array[string] | - | 外部依赖列表，辅助接收方环境准备 | | `data` | string | ✓ | 源代码文本 | **示例**： ```json { "type": "inline", "content_type": "text/plain", "encoding": "none", "language": "python", "version": "3.11", "dependencies": ["requests>=2.28", "pydantic>=2.0"], "data": "def hello(name: str) -> str:\n return f\"Hello, {name}!\"" } ``` --- ### 3.4 文件内容（FileContent） 通用文件内容，支持 inline、url、streaming 三种传输模式。 ```go type FileContent struct { ContentBase // 文件标识 Name string `json:"name"` // 文件名（含扩展名） Role string `json:"role,omitempty"` // 角色（"reference", "result", "attachment"） Description string `json:"description,omitempty"` // 文件描述 // Inline 传输（≤ 1MB） Data string `json:"data,omitempty"` // base64 编码的文件数据 // URL 传输（> 1MB） URL string `json:"url,omitempty"` // 文件下载 URL URLExpiresAt *Timestamp `json:"url_expires_at,omitempty"` // URL 过期时间 DownloadMethod string `json:"download_method,omitempty"` // 下载方法（GET / POST / signed_url） RangeSupported bool `json:"range_supported,omitempty"` // 是否支持 HTTP Range 请求 // 流式传输 StreamingSessionID string `json:"streaming_session_id,omitempty"` // 流式会话 ID TotalChunks int64 `json:"total_chunks,omitempty"` // 总块数 ChunkSize int64 `json:"chunk_size,omitempty"` // 每块大小 // 元数据 Width int `json:"width,omitempty"` // 宽度（图片/视频，单位：像素） Height int `json:"height,omitempty"` // 高度（图片/视频，单位：像素） Duration float64 `json:"duration,omitempty"` // 时长（音视频，单位：秒） Resolution string `json:"resolution,omitempty"` // 分辨率描述（如 "1920x1080"） ThumbnailURL string `json:"thumbnail_url,omitempty"` // 缩略图 URL } ``` **角色定义**： | 角色 | 说明 | |------|------| | `reference` | 参考材料，辅助执行方理解上下文 | | `result` | 执行结果输出文件 | | `attachment` | 附件，与任务相关但不参与核心逻辑的文件 | **传输模式选择**： | 模式 | 条件 | 填充字段 | |------|------|---------| | `inline` | 文件大小 ≤ 1MB | `data`（base64 编码） | | `url` | 文件大小 > 1MB | `url` + `url_expires_at` + `download_method` + `range_supported` | | `streaming` | 大文件或实时流 | `streaming_session_id` + `total_chunks` + `chunk_size` | **示例（inline 传输）**： ```json { "type": "inline", "content_type": "image/png", "encoding": "base64", "size": 524288, "name": "screenshot.png", "role": "reference", "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==" } ``` **示例（url 传输）**： ```json { "type": "url", "content_type": "video/mp4", "encoding": "none", "size": 15728640, "name": "demo.mp4", "role": "result", "url": "https://storage.synapse.com/files/demo.mp4", "url_expires_at": "2026-06-30T23:59:59Z", "download_method": "GET", "range_supported": true, "width": 1920, "height": 1080, "duration": 30.5, "resolution": "1920x1080" } ``` --- ### 3.5 内容包（ContentBundle + ContentBundleItem） 用于传输多个相关联的内容对象，支持分组和角色标注。 ```go type ContentBundle struct { ID string `json:"id"` // 包唯一标识 Name string `json:"name,omitempty"` // 包名称 Description string `json:"description,omitempty"` // 包描述 Items []ContentBundleItem `json:"items"` // 内容项列表 TotalSize int64 `json:"total_size,omitempty"` // 总大小（字节） CreatedAt Timestamp `json:"created_at"` // 创建时间 } type ContentBundleItem struct { ID string `json:"id"` // 项唯一标识 Role string `json:"role"` // 角色（"main", "reference", "attachment", "thumbnail"） Content any `json:"content"` // 内容对象（TextContent / JSONContent / CodeContent / FileContent 之一） } ``` **项角色定义**： | 角色 | 说明 | |------|------| | `main` | 主要内容项，通常为任务的主输出 | | `reference` | 参考材料项，辅助理解上下文 | | `attachment` | 附件项，补充信息 | | `thumbnail` | 缩略图项，用于预览展示 | **示例**： ```json { "id": "bundle-001", "name": "分析报告", "description": "包含分析结果、图表和原始数据", "items": [ { "id": "item-001", "role": "main", "content": { "type": "inline", "content_type": "text/markdown", "encoding": "none", "charset": "utf-8", "language": "zh-CN", "data": "# 分析报告\n\n本次分析共发现 **3** 个关键问题..." } }, { "id": "item-002", "role": "reference", "content": { "type": "url", "content_type": "image/png", "encoding": "none", "size": 204800, "name": "chart.png", "role": "reference", "url": "https://storage.synapse.com/reports/chart.png" } }, { "id": "item-003", "role": "attachment", "content": { "type": "url", "content_type": "application/json", "encoding": "gzip", "size": 1048576, "name": "raw_data.json.gz", "role": "attachment", "url": "https://storage.synapse.com/reports/raw_data.json.gz" } } ], "total_size": 1253376, "created_at": "2026-06-28T10:00:00Z" } ``` --- ## 4. MIME 类型常量表 ```go const ( // 文本类型 MIMETextPlain = "text/plain" // 纯文本 MIMETextMarkdown = "text/markdown" // Markdown 文档 MIMETextHTML = "text/html" // HTML 文档 MIMETextCSV = "text/csv" // CSV 表格数据 MIMETextCSS = "text/css" // 样式表 MIMETextXML = "text/xml" // XML 文本 // 应用程序类型 MIMEJSON = "application/json" // JSON 数据 MIMEXML = "application/xml" // XML 数据 MIMEPDF = "application/pdf" // PDF 文档 MIMEZip = "application/zip" // ZIP 压缩包 MIMEGZip = "application/gzip" // GZip 压缩文件 MIMEOctetStream = "application/octet-stream" // 二进制流（通用） MIMEMultipartForm = "multipart/form-data" // Multipart 表单数据 // 图片类型 MIMEImageJPEG = "image/jpeg" // JPEG 图片 MIMEImagePNG = "image/png" // PNG 图片 MIMEImageWebP = "image/webp" // WebP 图片 MIMEImageGIF = "image/gif" // GIF 图片 MIMEImageSVG = "image/svg+xml" // SVG 矢量图 MIMEImageBMP = "image/bmp" // BMP 位图 MIMEImageTIFF = "image/tiff" // TIFF 图片 MIMEImageICO = "image/x-icon" // 图标文件 // 视频类型 MIMEVideoMP4 = "video/mp4" // MP4 视频 MIMEVideoWebM = "video/webm" // WebM 视频 MIMEVideoAVI = "video/x-msvideo" // AVI 视频 MIMEVideoMOV = "video/quicktime" // MOV 视频 MIMEVideoMKV = "video/x-matroska" // MKV 视频 // 音频类型 MIMEAudioMP3 = "audio/mpeg" // MP3 音频 MIMEAudioWAV = "audio/wav" // WAV 音频 MIMEAudioAAC = "audio/aac" // AAC 音频 MIMEAudioOGG = "audio/ogg" // OGG 音频 MIMEAudioFLAC = "audio/flac" // FLAC 无损音频 MIMEAudioWebM = "audio/webm" // WebM 音频 ) ``` ### 分类汇总 | 类别 | 数量 | 常量列表 | |------|:----:|---------| | 文本类型 | 6 | `MIMETextPlain`, `MIMETextMarkdown`, `MIMETextHTML`, `MIMETextCSV`, `MIMETextCSS`, `MIMETextXML` | | 应用程序类型 | 7 | `MIMEJSON`, `MIMEXML`, `MIMEPDF`, `MIMEZip`, `MIMEGZip`, `MIMEOctetStream`, `MIMEMultipartForm` | | 图片类型 | 8 | `MIMEImageJPEG`, `MIMEImagePNG`, `MIMEImageWebP`, `MIMEImageGIF`, `MIMEImageSVG`, `MIMEImageBMP`, `MIMEImageTIFF`, `MIMEImageICO` | | 视频类型 | 5 | `MIMEVideoMP4`, `MIMEVideoWebM`, `MIMEVideoAVI`, `MIMEVideoMOV`, `MIMEVideoMKV` | | 音频类型 | 6 | `MIMEAudioMP3`, `MIMEAudioWAV`, `MIMEAudioAAC`, `MIMEAudioOGG`, `MIMEAudioFLAC`, `MIMEAudioWebM` | --- **文档结束** > 本文档对应 v0/06-implementation-details.md 第2章「内容类型系统」， > 是 Synapse 协议内容子系统在 v1 层级中的独立规范。