# Jev 结构化决策

> 通用

提交一次 Jev 结构化决策请求。`model` 为平台模型名（如 `jev-1.13.0`），用于选路；
`state` 为待分析内容，`questions` 为题目集合。
每道题按 `type` 返回对应的结构化答案，一次性返回，非流式。

## 请求地址

`POST https://api.modelverse.cn/v1/systemone`

## 请求体

## 响应

- **200** — Jev 原生结构化决策结果（额外注入 `u_trace_id` 便于平台侧反查）。
- **default** — 错误响应（网关侧参数/鉴权错误或上游非 200）。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "Jev 结构化决策接口文档",
    "version": "1.0.0",
    "description": "这是 ModelVerse 上 **TypeSafe Jev（System One 结构化决策模型）** 的接口文档。\n统一入口 `POST /v1/systemone`，通过请求体中的 `model` 字段选路。\n其余字段为 Jev 原生参数，**原样透传、原样返回，不做归一化**。响应为非流式，一次性返回 JSON。\n\nJev 不是聊天模型：你给它一段 `state`（待分析的文本/结构化数据）和一组 `questions`（每题声明\n`type`/`instructions`/`criteria`），它对每道题返回一个类型安全的结构化答案（`noul` 概率、\n`choice` 选项、`score` 分级），不生成自由文本。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint."
    }
  ],
  "tags": [
    {
      "name": "System One",
      "description": "TypeSafe Jev 结构化决策。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/systemone": {
      "post": {
        "tags": [
          "System One"
        ],
        "operationId": "createSystemOneDecision",
        "summary": "Jev 结构化决策",
        "description": "提交一次 Jev 结构化决策请求。`model` 为平台模型名（如 `jev-1.13.0`），用于选路；\n`state` 为待分析内容，`questions` 为题目集合。\n每道题按 `type` 返回对应的结构化答案，一次性返回，非流式。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SystemOneRequest"
              },
              "examples": {
                "customerTicket": {
                  "summary": "对一条客服工单同时做三类判定",
                  "value": {
                    "model": "jev-1.13.0",
                    "state": "我今早的年度套餐被重复扣款了两次，请今天就退掉其中一笔。",
                    "questions": {
                      "wants_refund": {
                        "type": "noul",
                        "instructions": "客户是否在要求退款？"
                      },
                      "queue": {
                        "type": "choice",
                        "instructions": "这条工单应转给哪个队列？",
                        "criteria": {
                          "billing": "账单部门",
                          "technical": "技术支持",
                          "sales": "销售团队"
                        }
                      },
                      "urgency": {
                        "type": "score",
                        "instructions": "该问题的紧急程度？",
                        "criteria": [
                          "可以等一周",
                          "本周内处理",
                          "今天就得回复"
                        ]
                      }
                    }
                  }
                },
                "noulOnly": {
                  "summary": "仅做一个 noul（是否要退款）判定",
                  "value": {
                    "model": "jev-1.13.0",
                    "state": "我今早的年度套餐被重复扣款了两次，请今天就退掉其中一笔。",
                    "questions": {
                      "wants_refund": {
                        "type": "noul",
                        "instructions": "客户是否在要求退款？"
                      }
                    }
                  }
                },
                "choiceOnly": {
                  "summary": "仅做一个 choice（转派队列）判定",
                  "value": {
                    "model": "jev-1.13.0",
                    "state": "我今早的年度套餐被重复扣款了两次，请今天就退掉其中一笔。",
                    "questions": {
                      "queue": {
                        "type": "choice",
                        "instructions": "这条工单应转给哪个队列？",
                        "criteria": {
                          "billing": "账单部门",
                          "technical": "技术支持",
                          "sales": "销售团队"
                        }
                      }
                    }
                  }
                },
                "scoreOnly": {
                  "summary": "仅做一个 score（紧急程度）判定",
                  "value": {
                    "model": "jev-1.13.0",
                    "state": "我今早的年度套餐被重复扣款了两次，请今天就退掉其中一笔。",
                    "questions": {
                      "urgency": {
                        "type": "score",
                        "instructions": "该问题的紧急程度？",
                        "criteria": [
                          "可以等一周",
                          "本周内处理",
                          "今天就得回复"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Jev 原生结构化决策结果（额外注入 `u_trace_id` 便于平台侧反查）。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemOneResponse"
                },
                "examples": {
                  "decision": {
                    "summary": "三道题的结构化答案 + 用量",
                    "value": {
                      "id": "gen-dec-1789895482-0mFbIsogyPVPcm4CVgIe",
                      "model": "typesafe/jev-1.13-20260917",
                      "provider": "TypeSafe",
                      "answers": {
                        "wants_refund": {
                          "type": "noul",
                          "noul": 0.99
                        },
                        "queue": {
                          "type": "choice",
                          "choice": "billing",
                          "confidence": 1,
                          "probabilities": {
                            "sales": 0,
                            "billing": 1,
                            "technical": 0
                          }
                        },
                        "urgency": {
                          "type": "score",
                          "score": 2,
                          "confidence": 1,
                          "legend": {
                            "0": "可以等一周",
                            "1": "本周内处理",
                            "2": "今天就得回复"
                          },
                          "probabilities": {
                            "0": 0,
                            "1": 0,
                            "2": 1
                          }
                        }
                      },
                      "usage": {
                        "input_tokens": 388,
                        "output_tokens": 59,
                        "cost": 0.000016296
                      },
                      "u_trace_id": "3f6a1c9e-...-platform-trace"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应（网关侧参数/鉴权错误或上游非 200）。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemOneErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/SystemOneError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "平台下发的 API Key，通过 `Authorization: Bearer <API Key>` 传入。"
      }
    },
    "schemas": {
      "SystemOneRequest": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "model",
          "state",
          "questions"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "平台模型名（如 `jev-1.13.0`），用于选路。",
            "examples": [
              "jev-1.13.0"
            ]
          },
          "state": {
            "description": "待分析的内容，可为字符串、JSON 对象或数组。",
            "oneOf": [
              {
                "type": "string",
                "title": "string"
              },
              {
                "type": "object",
                "additionalProperties": true,
                "title": "object"
              },
              {
                "type": "array",
                "items": {},
                "title": "array"
              }
            ]
          },
          "questions": {
            "type": "object",
            "description": "题目集合，key 为题目 ID，value 为题目对象。",
            "additionalProperties": {
              "$ref": "#/components/schemas/Question"
            }
          }
        }
      },
      "Question": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "instructions"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "noul",
              "choice",
              "score"
            ],
            "description": "题型：\n- `noul`：返回 0~1 概率；`criteria` 可选（`{true, false}` 描述）。\n- `choice`：从若干选项中选一个；`criteria` 必填，为「选项名→描述」映射（最多 255 个选项）。\n- `score`：分级打分；`criteria` 必填，为从低到高有序的等级描述数组。\n"
          },
          "instructions": {
            "type": "string",
            "description": "评估说明，描述这道题要判断什么。"
          },
          "criteria": {
            "description": "判定标准，形态随 `type` 而定：`choice` 为对象（选项名→描述），`score` 为字符串数组（有序等级），\n`noul` 可为对象（`true`/`false` 语义描述）或省略。\n",
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "title": "object"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "title": "array"
              }
            ]
          }
        }
      },
      "SystemOneResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "id": {
            "type": "string",
            "description": "上游决策 ID（`gen-dec-` 前缀），可用于反查。"
          },
          "model": {
            "type": "string",
            "description": "实际作答的上游模型版本。"
          },
          "provider": {
            "type": "string",
            "description": "上游 provider，固定为 `TypeSafe`。"
          },
          "answers": {
            "type": "object",
            "description": "每道题的结构化答案，key 与请求 `questions` 一致。",
            "additionalProperties": {
              "$ref": "#/components/schemas/Answer"
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          },
          "u_trace_id": {
            "type": "string",
            "description": "平台注入的 trace ID，仅出现在返回给客户端的响应体中，用于按平台 trace 反查。"
          }
        }
      },
      "Answer": {
        "description": "结构化答案，字段随 `type` 而定（`noul` / `choice` / `score`）。",
        "oneOf": [
          {
            "$ref": "#/components/schemas/NoulAnswer"
          },
          {
            "$ref": "#/components/schemas/ChoiceAnswer"
          },
          {
            "$ref": "#/components/schemas/ScoreAnswer"
          }
        ]
      },
      "NoulAnswer": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "type": {
            "type": "string",
            "const": "noul"
          },
          "noul": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "0~1 的概率信号（无单独 confidence 字段，概率本身即信号）。"
          }
        }
      },
      "ChoiceAnswer": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "type": {
            "type": "string",
            "const": "choice"
          },
          "choice": {
            "type": "string",
            "description": "选中的选项名（对应请求 `criteria` 的 key）。"
          },
          "confidence": {
            "type": "number",
            "description": "置信度。"
          },
          "probabilities": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "各选项的概率分布。"
          }
        }
      },
      "ScoreAnswer": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "type": {
            "type": "string",
            "const": "score"
          },
          "score": {
            "type": "integer",
            "description": "选中的等级下标（从 0 开始，对应请求 `criteria` 数组）。"
          },
          "confidence": {
            "type": "number",
            "description": "置信度。"
          },
          "legend": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "等级下标→等级描述的映射。"
          },
          "probabilities": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "各等级的概率分布。"
          }
        }
      },
      "Usage": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "input_tokens": {
            "type": "integer",
            "description": "输入 token 数。"
          },
          "output_tokens": {
            "type": "integer",
            "description": "输出 token 数。"
          },
          "cost": {
            "type": "number",
            "description": "上游侧成本（仅供参考，平台计费以自有价目表为准）。"
          }
        }
      },
      "SystemOneErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/SystemOneError"
          }
        }
      },
      "SystemOneError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message",
          "type",
          "code",
          "param"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "错误说明。"
          },
          "type": {
            "type": "string",
            "description": "错误类型。",
            "examples": [
              "invalid_request_error"
            ]
          },
          "code": {
            "type": "string",
            "description": "机器可读的错误码。",
            "examples": [
              "error_code"
            ]
          },
          "param": {
            "type": "string",
            "description": "请求 ID，用于反馈或排查错误原因。"
          }
        }
      }
    },
    "examples": {
      "SystemOneError": {
        "summary": "标准 JSON 错误响应",
        "value": {
          "error": {
            "message": "错误描述信息",
            "type": "invalid_request_error",
            "code": "error_code",
            "param": "<请求 ID，用于反馈或排查错误原因>"
          }
        }
      }
    }
  }
}
```