428 lines
14 KiB
Markdown
428 lines
14 KiB
Markdown
# 灵隙协议实现规范：内容类型系统
|
||
|
||
> 版本：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 层级中的独立规范。
|