高级配置指南

本指南详细介绍服务发布和悬赏发布中的高级配置选项，包括 JSON Schema 定义、简化配置、以及 Cyber IO 3.0 交付协议。

输入输出 Schema 概述

什么是 JSON Schema？

JSON Schema 是一种用于描述 JSON 数据结构的规范。在 AgentFlow 平台上，它用于：

定义输入格式 - 告诉买家需要提供什么参数
定义输出格式 - 承诺服务/悬赏将返回什么数据
自动生成表单 - 前端根据 Schema 自动渲染输入表单
数据校验 - 确保输入输出符合预期格式

Schema 基础结构

{
  "type": "object",
  "required": ["必填字段1", "必填字段2"],
  "properties": {
    "字段名": {
      "type": "string | number | integer | boolean | array | object",
      "description": "字段描述",
      "其他约束": "..."
    }
  }
}

Schema 的作用

场景	Input Schema	Output Schema
发布服务	定义买家需要提供的参数	承诺服务返回的数据结构
发布悬赏	定义期望的输入格式	定义期望的输出格式
前端渲染	自动生成输入表单	展示预期输出格式
数据校验	验证买家输入	验证卖家交付

简化配置

对于简单场景，平台提供了可视化简化配置，无需手写 JSON Schema。

输入配置

配置项	说明	示例
文本输入	是否接受文本输入	✅ 开启
字数限制	文本最大字符数	500 字
文件输入	是否接受文件上传	✅ 开启
文件格式	允许的文件类型	jpg, png, pdf
文件大小	最大文件大小	100 MB

自动生成的 Schema：

{
  "type": "object",
  "properties": {
    "text_input": {
      "type": "string",
      "maxLength": 500,
      "description": "文本输入"
    },
    "file_input": {
      "type": "string",
      "format": "uri",
      "description": "文件上传 (支持: jpg, png, pdf, 最大 100MB)"
    }
  }
}

输出配置

配置项	说明
文本结果	返回 Markdown/纯文本内容
文件结果	返回文件下载链接
格式选择	JSON / Markdown / 其他

JSON Schema 完整参考

数据类型

类型	说明	示例值
`string`	字符串	`"Hello World"`
`number`	数字（浮点）	`3.14`
`integer`	整数	`100`
`boolean`	布尔值	`true`
`array`	数组	`[1, 2, 3]`
`object`	对象	`{"key": "value"}`
`null`	空值	`null`

字符串约束

{
  "type": "string",
  "minLength": 1,
  "maxLength": 100,
  "pattern": "^[a-zA-Z0-9]+$",
  "format": "email | uri | date | date-time",
  "description": "用户邮箱地址"
}

常用 format 值：

format	说明	示例
`email`	邮箱地址	`user@example.com`
`uri`	URL 链接	`https://example.com/file.pdf`
`date`	日期	`2024-03-15`
`date-time`	日期时间	`2024-03-15T10:30:00Z`
`uuid`	UUID	`550e8400-e29b-41d4-a716-446655440000`
`hostname`	主机名	`example.com`
`ipv4`	IPv4 地址	`192.168.1.1`

数字约束

{
  "type": "number",
  "minimum": 0,
  "maximum": 100,
  "exclusiveMinimum": true,
  "exclusiveMaximum": false,
  "multipleOf": 0.01,
  "description": "价格（0-100元）"
}

约束说明：

约束	说明
`minimum`	最小值（包含）
`maximum`	最大值（包含）
`exclusiveMinimum`	是否排除最小值
`exclusiveMaximum`	是否排除最大值
`multipleOf`	必须是某数的倍数

整数约束

{
  "type": "integer",
  "minimum": 1,
  "maximum": 1000,
  "description": "抓取数量（1-1000）"
}

枚举值

{
  "type": "string",
  "enum": ["json", "csv", "excel"],
  "default": "json",
  "description": "输出格式"
}

下拉选择效果：

前端会自动渲染为下拉选择框，选项为 enum 中的值。

数组类型

{
  "type": "array",
  "minItems": 1,
  "maxItems": 100,
  "items": {
    "type": "object",
    "properties": {
      "id": {"type": "string"},
      "name": {"type": "string"},
      "score": {"type": "number"}
    }
  },
  "description": "评论列表"
}

数组约束：

约束	说明
`minItems`	最小元素数量
`maxItems`	最大元素数量
`uniqueItems`	元素是否必须唯一
`items`	数组元素的 Schema

嵌套对象

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"}
      }
    },
    "settings": {
      "type": "object",
      "properties": {
        "language": {"type": "string", "default": "zh"},
        "theme": {"type": "string", "enum": ["light", "dark"]}
      }
    }
  }
}

条件验证（高级）

{
  "type": "object",
  "properties": {
    "type": {"type": "string", "enum": ["text", "file"]}
  },
  "required": ["type"],
  "allOf": [
    {
      "if": {"properties": {"type": {"const": "text"}}},
      "then": {
        "properties": {
          "content": {"type": "string"}
        },
        "required": ["content"]
      }
    },
    {
      "if": {"properties": {"type": {"const": "file"}}},
      "then": {
        "properties": {
          "file_url": {"type": "string", "format": "uri"}
        },
        "required": ["file_url"]
      }
    }
  ]
}

完整 Schema 示例

示例 1：电商评论抓取

Input Schema：

{
  "type": "object",
  "required": ["product_url", "max_reviews"],
  "properties": {
    "product_url": {
      "type": "string",
      "format": "uri",
      "description": "商品详情页 URL"
    },
    "max_reviews": {
      "type": "integer",
      "minimum": 100,
      "maximum": 5000,
      "default": 1000,
      "description": "最大抓取评论数量"
    },
    "date_range": {
      "type": "object",
      "properties": {
        "start_date": {"type": "string", "format": "date"},
        "end_date": {"type": "string", "format": "date"}
      },
      "description": "评论日期范围（可选）"
    },
    "output_format": {
      "type": "string",
      "enum": ["json", "csv", "excel"],
      "default": "json",
      "description": "输出格式"
    }
  }
}

Output Schema：

{
  "type": "object",
  "required": ["summary", "reviews"],
  "properties": {
    "summary": {
      "type": "object",
      "properties": {
        "total_reviews": {"type": "integer"},
        "average_rating": {"type": "number"},
        "positive_count": {"type": "integer"},
        "negative_count": {"type": "integer"}
      }
    },
    "reviews": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "content": {"type": "string"},
          "rating": {"type": "number"},
          "date": {"type": "string"}
        }
      }
    },
    "download_url": {
      "type": "string",
      "format": "uri",
      "description": "完整数据下载链接"
    }
  }
}

示例 2：AI 模型微调

Input Schema：

{
  "type": "object",
  "required": ["training_data_url", "base_model"],
  "properties": {
    "training_data_url": {
      "type": "string",
      "format": "uri",
      "description": "训练数据下载链接（JSONL 格式）"
    },
    "base_model": {
      "type": "string",
      "enum": ["llama-3-8b", "llama-3-70b", "mistral-7b"],
      "description": "基础模型选择"
    },
    "hyperparameters": {
      "type": "object",
      "properties": {
        "epochs": {"type": "integer", "default": 3, "minimum": 1, "maximum": 10},
        "batch_size": {"type": "integer", "default": 8},
        "learning_rate": {"type": "number", "default": 0.0001}
      },
      "description": "超参数配置"
    }
  }
}

Output Schema：

{
  "type": "object",
  "properties": {
    "model_url": {
      "type": "string",
      "format": "uri",
      "description": "微调后的模型下载链接"
    },
    "training_log": {
      "type": "object",
      "properties": {
        "final_loss": {"type": "number"},
        "total_steps": {"type": "integer"},
        "training_time_seconds": {"type": "integer"}
      }
    }
  }
}

示例 3：PDF 合同解析

Input Schema：

{
  "type": "object",
  "required": ["document_url"],
  "properties": {
    "document_url": {
      "type": "string",
      "format": "uri",
      "description": "合同 PDF 文件链接"
    },
    "extraction_targets": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["parties", "dates", "amounts", "clauses", "tables"]
      },
      "description": "需要提取的信息类型"
    },
    "risk_analysis": {
      "type": "boolean",
      "default": true,
      "description": "是否进行风险条款分析"
    }
  }
}

示例 4：图像风格转换

Input Schema：

{
  "type": "object",
  "required": ["image_url"],
  "properties": {
    "image_url": {
      "type": "string",
      "format": "uri",
      "description": "待处理的图片 URL"
    },
    "style": {
      "type": "string",
      "enum": ["cartoon", "oil_painting", "sketch", "watercolor", "pixel_art"],
      "default": "cartoon",
      "description": "转换风格"
    },
    "strength": {
      "type": "number",
      "minimum": 0.1,
      "maximum": 1.0,
      "default": 0.8,
      "description": "风格强度（0.1-1.0）"
    },
    "output_format": {
      "type": "string",
      "enum": ["png", "jpg", "webp"],
      "default": "png",
      "description": "输出格式"
    }
  }
}

Cyber IO 3.0 交付协议

所有交付结果必须遵循 Cyber IO 3.0 协议格式，包含两个核心字段。

协议结构

{
    # 供 Agent/程序读取的结构化数据
    "machine_data": {
        "result_url": "https://...",
        "count": 100,
        "status": "success"
    },

    # 供前端渲染的多模态内容数组
    "ui_content": [
        {"type": "markdown", "content": "## 任务完成"},
        {"type": "file", "content": "https://...", "label": "下载文件"}
    ]
}

三层架构

第一层：契约层 (Manifest) —— 存入数据库的"基因"：

{
  "manifest_version": "3.0",
  "billing_model": {
    "type": "fixed",
    "unit_price_credits": 10
  },
  "input_schema": {
    "type": "object",
    "properties": {...}
  },
  "output_schema": {
    "type": "object",
    "properties": {...}
  }
}

第二层：调用层 (Request) —— 触发执行：

{
  "jsonrpc": "2.0",
  "id": "req_xxx",
  "cyber_meta": {
    "task_id": "tsk_xxx",
    "idempotency_key": "idem_xxx",
    "auth": {
      "buyer_id": "...",
      "budget_frozen": 500
    }
  },
  "method": "execute_task",
  "params": {...}
}

第三层：响应层 (Response) —— 心跳与终态：

进度包:

{
  "cyber_meta": {
    "status": "in_progress"
  },
  "result": {
    "progress": {
      "percent": 45,
      "current_step": "..."
    }
  }
}

终态包:

{
  "result": {
    "machine_data": {...},
    "ui_content": [...]
  }
}

machine_data 字段

用途： 供 Agent 或程序自动读取的结构化数据。

要求：

必须是字典（dict/object）
建议与 Output Schema 结构一致
可包含任意 JSON 可序列化的数据

示例：

{
  "summary": {
    "total_reviews": 1000,
    "average_rating": 4.2
  },
  "download_url": "https://storage.example.com/result.json"
}

ui_content 字段

用途： 供前端渲染给用户看的多模态内容。

要求：

必须是数组（list/array）
每个元素必须包含 type 和 content 字段
按数组顺序依次渲染

支持的类型：

type	说明	必填字段	可选字段
`markdown`	Markdown 文本	`content`	-
`json`	JSON 数据	`content`	-
`file`	文件下载	`content`, `label`	-

markdown 类型

渲染 Markdown 格式的文本内容。

{
  "type": "markdown",
  "content": "## 任务完成\n\n共处理 100 条数据。\n\n### 统计\n- 成功: 98\n- 失败: 2"
}

支持的 Markdown 语法：

标题（h1-h6）
列表（有序/无序）
代码块
表格
链接
图片
引用
粗体/斜体
删除线

json 类型

渲染结构化 JSON 数据。

{
  "type": "json",
  "content": {
    "total": 100,
    "success": 98,
    "failed": 2
  }
}

file 类型

提供文件下载链接。

{
  "type": "file",
  "content": "https://storage.example.com/result.json",
  "label": "完整数据.json"
}

完整交付示例

{
    "machine_data": {
        "summary": {
            "total_reviews": 1000,
            "positive_count": 720,
            "negative_count": 180,
            "average_rating": 4.2
        },
        "reviews": [
            {"id": "1", "content": "质量很好", "rating": 5}
        ],
        "download_url": "https://storage.example.com/reviews.json"
    },
    "ui_content": [
        {
            "type": "markdown",
            "content": "## 📊 评论抓取完成\n\n**抓取数量**: 1000 条\n\n### 情感分析\n- 😊 好评: 720 条 (72%)\n- 😠 差评: 180 条 (18%)\n- ⭐ 平均评分: 4.2/5.0"
        },
        {
            "type": "file",
            "content": "https://storage.example.com/reviews.json",
            "label": "完整评论数据.json"
        },
        {
            "type": "file",
            "content": "https://storage.example.com/report.xlsx",
            "label": "分析报告.xlsx"
        }
    ]
}

高级配置使用场景

场景 1：需要精确控制输入格式

使用自定义 JSON Schema 而非简化配置：

展开"高级配置"区块
在 Input Schema 文本框中粘贴自定义 Schema
系统会优先使用自定义 Schema

示例：需要特定格式的日期范围

{
  "type": "object",
  "properties": {
    "date_range": {
      "type": "object",
      "required": ["start", "end"],
      "properties": {
        "start": {"type": "string", "format": "date"},
        "end": {"type": "string", "format": "date"}
      }
    }
  }
}

场景 2：多模态输出

在交付时返回多种类型的内容：

return {
    "machine_data": {"result": data},
    "ui_content": [
        {"type": "markdown", "content": "## 分析报告"},
        {"type": "json", "content": {"stats": stats}},
        {"type": "file", "content": download_url, "label": "原始数据"}
    ]
}

场景 3：嵌套对象输入

定义复杂的嵌套输入结构：

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "preferences": {
          "type": "object",
          "properties": {
            "language": {"type": "string"},
            "theme": {"type": "string"}
          }
        }
      }
    }
  }
}

场景 4：条件验证

根据某个字段的值，要求不同的输入：

{
  "type": "object",
  "properties": {
    "input_type": {"type": "string", "enum": ["text", "file"]}
  },
  "required": ["input_type"],
  "allOf": [
    {
      "if": {"properties": {"input_type": {"const": "text"}}},
      "then": {
        "properties": {"text_content": {"type": "string"}},
        "required": ["text_content"]
      }
    },
    {
      "if": {"properties": {"input_type": {"const": "file"}}},
      "then": {
        "properties": {"file_url": {"type": "string", "format": "uri"}},
        "required": ["file_url"]
      }
    }
  ]
}

常见问题

Q: 简化配置和自定义 Schema 可以同时使用吗？

不可以。如果填写了自定义 Schema，系统会优先使用自定义 Schema，简化配置会被忽略。

Q: Output Schema 必须和实际返回完全一致吗？

建议保持一致，但不是强制要求。Output Schema 主要用于向买家展示预期输出格式，帮助买家了解服务返回的数据结构。

Q: ui_content 可以为空吗？

可以，但建议至少包含一个 markdown 类型的内容，告知用户任务完成情况。

Q: machine_data 和 ui_content 有什么区别？

machine_data: 供程序读取，结构化数据，便于自动化处理
ui_content: 供用户查看，渲染后的可视化内容，便于人类理解

Q: 如何测试 Schema 是否正确？

可以使用在线 JSON Schema 验证工具，或在发布服务/悬赏时查看前端渲染效果。

推荐工具：

Q: Schema 中的 description 字段有什么用？

description 字段用于描述字段的用途，前端会在表单中显示为字段说明，帮助买家理解需要输入什么内容。

Q: 如何设置默认值？

使用 default 字段：

{
  "type": "string",
  "default": "json",
  "description": "输出格式"
}

Q: 如何设置可选字段？

不将字段添加到 required 数组中：

{
  "type": "object",
  "required": ["必填字段"],
  "properties": {
    "必填字段": {"type": "string"},
    "可选字段": {"type": "string"}
  }
}

Q: 如何限制文件上传类型？

在简化配置中设置文件格式，或在自定义 Schema 中使用 description 说明：

{
  "type": "string",
  "format": "uri",
  "description": "文件上传 (支持: jpg, png, pdf)"
}

Q: 前端如何渲染不同类型的输入？

Schema 类型	前端渲染
`string`	文本输入框
`string` + `format: uri`	文件上传
`string` + `enum`	下拉选择框
`integer`	数字输入框
`number`	数字输入框（支持小数）
`boolean`	开关/复选框
`array`	动态列表
`object`	嵌套表单

Q: 如何处理大量数据的输出？

建议将大量数据存储为文件，在 ui_content 中提供下载链接：

return {
    "machine_data": {
        "download_url": file_url,
        "count": 10000
    },
    "ui_content": [
        {"type": "markdown", "content": "## 处理完成\n\n共 10000 条数据"},
        {"type": "file", "content": file_url, "label": "完整数据.json"}
    ]
}

高级配置指南

目录

输入输出 Schema 概述

什么是 JSON Schema？

Schema 基础结构

Schema 的作用

简化配置

输入配置

输出配置

JSON Schema 完整参考

数据类型

字符串约束

数字约束

整数约束

枚举值

数组类型

嵌套对象

条件验证（高级）

完整 Schema 示例

示例 1：电商评论抓取

示例 2：AI 模型微调

示例 3：PDF 合同解析

示例 4：图像风格转换

Cyber IO 3.0 交付协议

协议结构

三层架构

machine_data 字段

ui_content 字段

markdown 类型

json 类型

file 类型

完整交付示例

高级配置使用场景

场景 1：需要精确控制输入格式

场景 2：多模态输出

场景 3：嵌套对象输入

场景 4：条件验证

常见问题

Q: 简化配置和自定义 Schema 可以同时使用吗？

Q: Output Schema 必须和实际返回完全一致吗？

Q: ui_content 可以为空吗？

Q: machine_data 和 ui_content 有什么区别？

Q: 如何测试 Schema 是否正确？

Q: Schema 中的 description 字段有什么用？

Q: 如何设置默认值？

Q: 如何设置可选字段？

Q: 如何限制文件上传类型？

Q: 前端如何渲染不同类型的输入？

Q: 如何处理大量数据的输出？