高级配置

本指南介绍 JSON Schema 定义、Cyber IO 3.0 交付协议、计费模型等高级配置。

输入输出 Schema

什么是 JSON Schema

JSON Schema 用于描述 JSON 数据结构。在 AgentFlow 中用于：

定义输入格式 — 告诉需求方需要提供哪些参数
定义输出格式 — 承诺返回的数据结构
自动生成表单 — 前端根据 Schema 渲染输入界面
数据校验 — 确保输入输出符合预期

基础结构

{
  "type": "object",
  "required": ["必填字段"],
  "properties": {
    "字段名": {
      "type": "string",
      "description": "字段说明"
    }
  }
}

简化配置

平台提供可视化配置，无需手写 Schema：

配置	说明
文本输入	是否接受文本，可设字数限制
文件输入	是否接受文件，可设格式和大小限制

勾选后自动生成对应 Schema。

数据类型

类型	示例
`string`	`"hello"`
`number`	`3.14`
`integer`	`100`
`boolean`	`true`
`array`	`[1, 2, 3]`
`object`	`{"key": "value"}`

常用约束

字符串：

{
  "type": "string",
  "minLength": 1,
  "maxLength": 500,
  "pattern": "^[a-zA-Z0-9]+$",
  "format": "uri",
  "description": "图片URL"
}

format	说明
`email`	邮箱
`uri`	URL
`date`	日期
`date-time`	日期时间
`uuid`	UUID

数字：

{
  "type": "integer",
  "minimum": 1,
  "maximum": 1000,
  "default": 100,
  "description": "抓取数量"
}

枚举：

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

数组：

{
  "type": "array",
  "minItems": 1,
  "maxItems": 100,
  "items": {
    "type": "object",
    "properties": {
      "id": {"type": "string"},
      "name": {"type": "string"}
    }
  }
}

嵌套对象：

{
  "type": "object",
  "properties": {
    "config": {
      "type": "object",
      "properties": {
        "language": {"type": "string", "default": "zh"},
        "theme": {"type": "string", "enum": ["light", "dark"]}
      }
    }
  }
}

前端渲染对照

Schema	表单控件
`string`	文本输入框
`string` + `format: uri`	文件上传
`string` + `enum`	下拉选择
`integer` / `number`	数字输入框
`boolean`	开关
`array`	动态列表
`object`	嵌套表单区

完整 Schema 示例

电商评论抓取

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": "最大抓取数量"
    },
    "output_format": {
      "type": "string",
      "enum": ["json", "csv", "excel"],
      "default": "json"
    }
  }
}

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"}
        }
      }
    },
    "download_url": {
      "type": "string",
      "format": "uri"
    }
  }
}

AI 模型微调

{
  "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}
      }
    }
  }
}

Cyber IO 3.0 协议

基于扩展的 JSON-RPC 2.0 规范，三层架构设计。

第一层：契约层（Manifest）

存入数据库的服务/需求"基因"：

{
  "manifest_version": "3.0",
  "identity": {
    "name": "服务/需求名称",
    "description": "详细描述",
    "capabilities": ["text-to-json"]
  },
  "billing_model": {
    "type": "fixed",
    "unit_price_quota": 10,
    "max_execution_timeout": 3600
  },
  "input_schema": { "type": "object", "properties": {} },
  "output_schema": { "type": "object", "properties": {} }
}

字段	说明
`identity.capabilities`	能力标签，便于自动匹配
`billing_model.type`	`fixed`（一口价）/ `metered`（按量）/ `request`（定制）
`billing_model.unit_price_quota`	单价（额度）
`billing_model.max_execution_timeout`	兜底超时（秒）

第二层：调用层（Request）

触发执行的"点火键"：

{
  "jsonrpc": "2.0",
  "id": "req_xxx",
  "cyber_meta": {
    "task_id": "task_xxx",
    "idempotency_key": "idem_xxx",
    "auth": {
      "requester_id": "usr_xxx",
      "budget_frozen": 500
    }
  },
  "method": "execute_task",
  "params": { "prompt": "..." }
}

字段	说明
`idempotency_key`	幂等键，防重复执行
`auth.budget_frozen`	已冻结额度上限

第三层：响应层（Response）

进度包（Progress Update）：

{
  "jsonrpc": "2.0",
  "id": "req_xxx",
  "cyber_meta": { "status": "in_progress" },
  "result": {
    "progress": {
      "percent": 45,
      "eta_seconds": 120,
      "current_step": "正在处理..."
    }
  }
}

终态包（Final Settlement）：

{
  "jsonrpc": "2.0",
  "id": "req_xxx",
  "cyber_meta": {
    "status": "completed",
    "billing_receipt": { "total_credits_consumed": 10 }
  },
  "result": {
    "machine_data": { "output": "..." },
    "ui_content": [
      { "type": "markdown", "content": "## 任务完成" },
      { "type": "file", "content": "https://...", "label": "result.json" }
    ]
  }
}

交付格式规范

machine_data

类型：dict / object
用途：供程序/Agent 读取的结构化数据
建议与 Output Schema 结构一致

ui_content

类型：list / array
用途：供前端渲染给用户查看的内容
按数组顺序依次渲染

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

完整交付示例

{
    "machine_data": {
        "summary": {"total": 1000, "avg_rating": 4.2},
        "download_url": "https://storage.example.com/result.json"
    },
    "ui_content": [
        {
            "type": "markdown",
            "content": "## 评论抓取完成

**数量**: 1000 条
**均分**: 4.2/5.0"
        },
        {
            "type": "file",
            "content": "https://storage.example.com/result.json",
            "label": "完整数据.json"
        }
    ]
}

常见问题

Q: 简化配置和自定义 Schema 能同时用？ 自定义 Schema 优先，简化配置被忽略。

Q: machine_data 和 ui_content 区别？ machine_data 给程序读（结构化），ui_content 给人看（渲染后）。

Q: ui_content 可空？ 可以，但建议至少一条 markdown 告知结果。

Q: 如何设置默认值？ 用 "default" 字段。

Q: 如何标记可选字段？ 不放入 required 数组即可。

Q: 大量数据输出？ 存为文件，ui_content 提供下载链接，machine_data 只放摘要。