14 KiB
14 KiB
灵隙协议实现规范：内容类型系统
版本：1.0.0 | 层级：实现层
根据 v0/06-implementation-details.md 的第2章内容，本文档定义 Synapse 协议内容类型系统的完整规范，涵盖传输模式、内容编码、结构化内容类型定义及 MIME 类型常量。
1. 传输模式
传输模式决定内容数据在 Agent 之间的传递方式，根据数据大小和实时性需求选择最佳模式。
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
所有内容类型共享的基础结构：
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. 内容编码
内容编码定义了原始数据在传输前的编码/压缩方式。
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）
纯文本内容，支持字符集和语言声明。
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 | ✓ | 文本内容数据 |
示例：
{
"type": "inline",
"content_type": "text/plain",
"encoding": "none",
"charset": "utf-8",
"language": "zh-CN",
"data": "你好，世界！"
}
3.2 JSON 内容（JSONContent）
结构化 JSON 数据，支持 Schema 验证。
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） |
示例：
{
"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）
源代码或脚本内容，支持多文件依赖声明。
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 | ✓ | 源代码文本 |
示例：
{
"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 三种传输模式。
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 传输）：
{
"type": "inline",
"content_type": "image/png",
"encoding": "base64",
"size": 524288,
"name": "screenshot.png",
"role": "reference",
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}
示例（url 传输）：
{
"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）
用于传输多个相关联的内容对象，支持分组和角色标注。
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 |
缩略图项，用于预览展示 |
示例：
{
"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 类型常量表
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 层级中的独立规范。