{ "openapi": "3.0.3", "info": { "title": "SciVerse Public Developer API", "version": "v1.0.0", "description": "SciVerse（穹宇）开放平台对外开发者 API。本文档包含公开开放的 6 个接口：语义检索、原文内容读取、资源下载、元数据字段目录、元数据检索和论文引用关系分页查询。" }, "servers": [ { "url": "https://api.sciverse.space", "description": "生产环境" }, { "url": "https://api-dev.sciverse.space", "description": "开发环境" } ], "tags": [ { "name": "search", "description": "语义检索与元数据检索" }, { "name": "content", "description": "原文内容与资源文件" }, { "name": "meta", "description": "元数据字段目录" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/agentic-search": { "post": { "tags": [ "search" ], "summary": "语义检索", "operationId": "agenticSearch", "description": "提交自然语言问题后返回相关文献片段（chunk）列表。每条命中带原文定位字段，可继续传给 /content 读取上下文。", "parameters": [ { "$ref": "#/components/parameters/XSciverseSource" }, { "$ref": "#/components/parameters/XRequestID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgenticSearchRequest" }, "examples": { "basic": { "summary": "基础语义检索", "value": { "query": "扩散模型在蛋白质设计中的应用", "top_k": 5, "retrieval": "hybrid", "sub_queries": 3 } }, "withFilters": { "summary": "带结构化过滤", "value": { "query": "transformer", "top_k": 10, "filters": { "lang": "en", "publication_published_year": { "gte": 2020, "lte": 2025 }, "citation_count": { "gte": 100 }, "topics": { "logic": "and", "dimensions": { "primary_topic": "Machine Learning", "primary_topic_domain": "Physical Sciences" } } } } } } } } }, "responses": { "200": { "description": "检索成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgenticSearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "507": { "description": "向量化或依赖资源不足。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/content": { "get": { "tags": [ "content" ], "summary": "读取原文全文或分页片段", "operationId": "getContent", "description": "按 doc_id 优先读取结构化全文，或按 source 回退读取原始对象。未传 offset 时返回整段全文；传入 offset（含 0）时按 Unicode 码点分页读取。", "parameters": [ { "$ref": "#/components/parameters/XSciverseSource" }, { "$ref": "#/components/parameters/XRequestID" }, { "name": "doc_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "not": { "pattern": "(\\.\\.|\\\\)" } }, "description": "文档标识。与 source 至少传一个；首选链路会按 doc_id 读取结构化全文。不得包含 .. 或反斜杠。" }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "http(s):// 或 s3:// 地址。首选链路失败或未配置时作为回退；与 doc_id 至少传一个。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "省略时返回整段全文。传入时为分页模式的起始 Unicode 码点偏移。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 524288, "default": 700 }, "description": "仅分页模式生效：从 offset 起最多返回的 Unicode 码点数。未传 offset 时会被忽略。" } ], "responses": { "200": { "description": "正文读取成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/resource": { "get": { "tags": [ "content" ], "summary": "下载文献资源文件", "operationId": "getResource", "description": "按资源对象相对路径下载图片等二进制附件。file_name 通常来自 /content 返回 Markdown 正文中的资源占位。", "parameters": [ { "$ref": "#/components/parameters/XSciverseSource" }, { "$ref": "#/components/parameters/XRequestID" }, { "name": "file_name", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "not": { "pattern": "(^/|\\.\\.|\\\\)" }, "example": "dt=2025-06-19/ht=18/a928e83b53ff898daee52afad471c896f6b4478c99a1d7085e82b6e8032398ed.jpg" }, "description": "资源对象相对路径；不得以 / 开头，不得包含 .. 或反斜杠。" } ], "responses": { "200": { "description": "资源文件流。", "headers": { "Content-Type": { "description": "文件 MIME 类型；未知类型回落为 application/octet-stream。", "schema": { "type": "string" } }, "Content-Disposition": { "description": "附件下载头。", "schema": { "type": "string" } }, "Cache-Control": { "description": "缓存策略，通常为 private, no-store。", "schema": { "type": "string" } }, "X-Request-ID": { "description": "请求链路 ID。", "schema": { "type": "string" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/meta-catalog": { "get": { "tags": [ "meta" ], "summary": "查看元数据字段目录", "operationId": "getMetaCatalog", "description": "返回当前 Token 可访问的 meta-search 字段、字段类型、过滤/排序/投影能力、默认返回字段和过滤操作符清单。可按需包含枚举样本和字段统计。", "parameters": [ { "$ref": "#/components/parameters/XSciverseSource" }, { "$ref": "#/components/parameters/XRequestID" }, { "name": "include_sample_values", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "是否拉取 enum-like 字段的取值样本。" }, { "name": "include_field_stats", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "是否拉取 keyword 字段基数估算，以及数值字段 min/max/avg/p50/p95 统计。" } ], "responses": { "200": { "description": "字段目录返回成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaCatalogResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/DeadlineExceeded" } } } }, "/meta-search": { "post": { "tags": [ "search" ], "summary": "结构化元数据检索", "operationId": "metaSearch", "description": "按字段过滤、全文模糊检索、排序、字段投影、分页和 facets 聚合检索元数据。字段能力与权限以 /meta-catalog 的运行时返回为准。", "parameters": [ { "$ref": "#/components/parameters/XSciverseSource" }, { "$ref": "#/components/parameters/XRequestID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaSearchRequest" }, "examples": { "query": { "summary": "全文模糊检索", "value": { "query": "attention mechanism", "page": 1, "page_size": 10 } }, "filterAndSort": { "summary": "字段过滤和排序", "value": { "filters": [ { "field": "language", "value": "en" }, { "field": "publication_published_year", "operator": "FILTER_OP_GTE", "value": 2023 } ], "sort": [ { "field": "publication_published_year", "order": "SORT_ORDER_DESC" } ], "page": 1, "page_size": 10 } } } } } }, "responses": { "200": { "description": "检索成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaSearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/DeadlineExceeded" } } } }, "/meta-paper-relations": { "post": { "tags": [ "search" ], "summary": "论文引用关系分页查询", "operationId": "getMetaPaperRelations", "description": "分页返回某篇论文的引用、被引或相关工作完整列表。先通过 /meta-search 或 /agentic-search 获取论文 unique_id，再按 relation 分页查询；适合读取 meta-search 中被截断的 citations / references / related_works 关系数组。", "parameters": [ { "$ref": "#/components/parameters/XSciverseSource" }, { "$ref": "#/components/parameters/XRequestID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaPaperRelationsRequest" }, "examples": { "citations": { "summary": "查询引用该论文的文献", "value": { "unique_id": "paper:10.1038/s41586-021-03819-2", "relation": "CITATIONS", "page": 1, "page_size": 25 } } } } } }, "responses": { "200": { "description": "论文关系分页返回成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaPaperRelationsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/DeadlineExceeded" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API token", "description": "通过开放平台控制台申请的 API Token，格式为 Authorization: Bearer YOUR_API_TOKEN。" } }, "parameters": { "XSciverseSource": { "name": "X-Sciverse-Source", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "minLength": 1, "maxLength": 64 }, "description": "调用来源标识。合法值会在响应头原样回写；不合法值会被静默忽略。" }, "XRequestID": { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "type": "string" }, "description": "请求链路 ID。反馈问题时建议提供；未传时由服务端生成。" } }, "responses": { "BadRequest": { "description": "请求参数错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "鉴权失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "无权访问请求的字段、原文或资源。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "请求的资源不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "MethodNotAllowed": { "description": "请求方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "超过限流额度。", "headers": { "Retry-After": { "description": "建议等待秒数。", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "RATE_LIMITED", "message": "请求过于频繁，请稍后再试", "request_id": "req_abc123", "details": { "retry_after": 5 } } } } }, "InternalError": { "description": "服务内部错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UpstreamUnavailable": { "description": "上游服务不可用，或代理未能获得上游 HTTP 响应。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ServiceUnavailable": { "description": "服务暂不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "DeadlineExceeded": { "description": "请求超时。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "机器可读错误码。", "example": "INVALID_REQUEST" }, "message": { "type": "string", "description": "人类可读错误信息。", "example": "请求参数错误" }, "request_id": { "type": "string", "description": "请求链路 ID。", "example": "req_abc123" }, "details": { "nullable": true, "description": "可选结构化补充信息，例如限流 retry_after。", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "AgenticSearchRequest": { "type": "object", "additionalProperties": false, "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "检索问题文本，去除首尾空白后不能为空。" }, "top_k": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "返回命中条数上限。" }, "retrieval": { "type": "string", "enum": [ "hybrid", "milvus", "es" ], "default": "hybrid", "description": "召回方式：hybrid 为向量+关键词融合，milvus 为纯向量，es 为纯关键词。" }, "sub_queries": { "type": "integer", "minimum": 0, "maximum": 4, "default": 0, "description": "LLM 子查询改写路数；0 或省略表示仅使用原始 query。" }, "filters": { "$ref": "#/components/schemas/AgenticSearchFilters" }, "source_types": { "type": "array", "items": { "type": "string", "enum": [ "web", "pdf" ] }, "description": "限定来源类型。" } } }, "AgenticSearchFilters": { "type": "object", "additionalProperties": false, "description": "语义检索结构化过滤。不传或传空对象表示不过滤；多个字段之间为 AND，同一字段数组值通常按 OR。", "properties": { "lang": { "type": "string", "description": "语言，如 en、zh。" }, "language": { "type": "string", "description": "lang 的兼容别名。" }, "title": { "type": "string", "description": "标题精确匹配。" }, "author": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "作者名；数组表示任一作者命中。" }, "publication_venue_name_unified": { "type": "string", "description": "发表载体名称。" }, "publication_venue_type": { "type": "string", "enum": [ "journal", "conference", "repository", "book series", "ebook platform", "metadata", "raidRegistry", "igsnCatalog", "other" ], "description": "发表载体类型，不区分大小写。" }, "publication_published_date": { "$ref": "#/components/schemas/DateFilterValue" }, "publication_published_year": { "$ref": "#/components/schemas/NumberFilterValue" }, "citation_count": { "$ref": "#/components/schemas/NumberFilterValue" }, "influential_citation_count": { "$ref": "#/components/schemas/NumberFilterValue" }, "topics": { "$ref": "#/components/schemas/TopicFilter" } } }, "NumberFilterValue": { "oneOf": [ { "type": "number" }, { "$ref": "#/components/schemas/RangeFilter" }, { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number", "nullable": true } } ] }, "DateFilterValue": { "oneOf": [ { "type": "string", "pattern": "^\\d{4}(-\\d{2})?(-\\d{2})?$" }, { "$ref": "#/components/schemas/RangeFilter" }, { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string", "nullable": true, "pattern": "^\\d{4}(-\\d{2})?(-\\d{2})?$" } } ] }, "RangeFilter": { "type": "object", "additionalProperties": false, "properties": { "gt": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "gte": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "lt": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "lte": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } } }, "TopicFilter": { "type": "object", "additionalProperties": false, "properties": { "logic": { "type": "string", "enum": [ "and", "or" ], "default": "or" }, "dimensions": { "type": "object", "additionalProperties": false, "properties": { "primary_topic": { "type": "string" }, "primary_topic_domain": { "type": "string", "enum": [ "Physical Sciences", "Social Sciences", "Health Sciences", "Life Sciences" ] } } } } }, "AgenticSearchResponse": { "type": "object", "required": [ "hits" ], "properties": { "hits": { "type": "array", "items": { "$ref": "#/components/schemas/AgenticSearchHit" } }, "request_tokens": { "type": "integer", "minimum": 0, "description": "请求侧 token 估算值；上游返回时存在。" }, "response_tokens": { "type": "integer", "minimum": 0, "description": "响应侧 token 估算值；上游返回时存在。" } }, "additionalProperties": true }, "AgenticSearchHit": { "type": "object", "additionalProperties": true, "properties": { "chunk_id": { "type": "string" }, "chunk": { "type": "string" }, "doc_id": { "type": "string", "description": "文档 ID，可交给 /content 取全文。" }, "title": { "type": "string" }, "abstract": { "type": "string" }, "score": { "type": "number", "format": "float" }, "recall_source": { "type": "string", "enum": [ "milvus", "es", "milvus|es" ] }, "origin_es_score": { "type": "number", "format": "float", "nullable": true }, "origin_milvus_score": { "type": "number", "format": "float", "nullable": true }, "source_type": { "type": "string", "enum": [ "pdf", "web" ] }, "source": { "type": "string", "description": "可作为 /content 的 source。" }, "offset": { "type": "integer", "format": "int64", "minimum": 0, "description": "chunk 在逻辑全文中的 Unicode 码点起始位置。" }, "chunk_no": { "type": "integer" }, "page_no": { "type": "integer" }, "model_name": { "type": "string" }, "model_version": { "type": "string" }, "lang": { "type": "string" }, "metadata_type": { "type": "string", "enum": [ "paper", "ebook" ] }, "author": { "type": "array", "items": { "type": "string" } }, "publication_venue_name_unified": { "type": "string" }, "publication_venue_type": { "type": "string" }, "publication_published_date": { "type": "string" }, "publication_published_year": { "type": "integer" }, "citation_count": { "type": "integer" }, "influential_citation_count": { "type": "integer" }, "primary_topic": { "type": "string" }, "primary_topic_domain": { "type": "string" } } }, "ContentResponse": { "type": "object", "additionalProperties": false, "required": [ "text", "bytes_returned", "text_length", "next_offset", "more" ], "properties": { "text": { "type": "string", "description": "返回正文（全文或分页片段）。" }, "bytes_returned": { "type": "integer", "minimum": 0, "description": "本次返回 text 的 UTF-8 字节长度。" }, "text_length": { "type": "integer", "format": "int64", "minimum": 0, "description": "全文 Unicode 码点数。" }, "next_offset": { "type": "integer", "format": "int64", "minimum": 0, "description": "分页模式下为下次请求 offset；全文模式下等于全文码点总数。" }, "more": { "type": "boolean", "description": "分页模式下 true 表示仍有后续；全文模式恒为 false。" } } }, "MetaCatalogResponse": { "type": "object", "additionalProperties": false, "required": [ "fields", "default_fields", "filter_operators" ], "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/MetaCatalogField" } }, "default_fields": { "type": "array", "items": { "type": "string" }, "description": "未显式传 fields 时默认返回的字段。" }, "filter_operators": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogFilterOperator" }, "description": "字段目录中使用短名；/meta-search 请求体中使用 FILTER_OP_ 前缀全名。" } } }, "MetaCatalogField": { "type": "object", "additionalProperties": false, "required": [ "name", "type", "filterable", "sortable", "searchable", "default_returned", "projectable", "description", "operators" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "String", "Integer", "Boolean", "Float", "Date", "List[string]", "List[object]", "Object" ] }, "filterable": { "type": "boolean" }, "sortable": { "type": "boolean" }, "searchable": { "type": "boolean" }, "default_returned": { "type": "boolean" }, "projectable": { "type": "boolean" }, "description": { "type": "string" }, "sample_values": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" } ] }, "description": "include_sample_values=true 且字段适合枚举展示时返回。" }, "operators": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogFilterOperator" } }, "cardinality_estimate": { "type": "integer", "format": "int64", "minimum": 0, "description": "include_field_stats=true 且字段适用时返回。" }, "numeric_stats": { "$ref": "#/components/schemas/NumericStats" } } }, "CatalogFilterOperator": { "type": "string", "enum": [ "EQ", "NE", "GT", "GTE", "LT", "LTE", "IN", "NIN", "CONTAINS", "MATCH", "MATCH_PHRASE" ] }, "NumericStats": { "type": "object", "additionalProperties": false, "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "avg": { "type": "number" }, "p50": { "type": "number" }, "p95": { "type": "number" } } }, "MetaSearchRequest": { "type": "object", "additionalProperties": false, "properties": { "query": { "type": "string", "default": "", "description": "全文模糊搜索关键词；为空则不做全文检索。" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/FieldFilterItem" }, "default": [] }, "sort": { "type": "array", "items": { "$ref": "#/components/schemas/SortFieldItem" }, "default": [], "description": "排序条件。query 非空时不能同时传 sort。" }, "fields": { "type": "array", "items": { "type": "string" }, "default": [], "description": "返回字段投影；为空返回默认字段集。" }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "页码，从 1 开始；page * page_size 不能超过 10000。" }, "page_size": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 }, "cursor": { "type": "string", "default": "", "description": "深翻页 cursor；与 page > 1 互斥。" }, "facets": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/FacetItem" }, "default": [] }, "freshness_boost": { "$ref": "#/components/schemas/FreshnessBoost" } } }, "FieldFilterItem": { "type": "object", "additionalProperties": false, "required": [ "field", "value" ], "properties": { "field": { "type": "string", "description": "过滤字段名，须在当前 Token 可访问范围内。" }, "operator": { "$ref": "#/components/schemas/FilterOperator" }, "value": { "description": "过滤值；IN/NIN 使用数组，其它操作符通常使用标量。", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": true } ] } } }, "FilterOperator": { "type": "string", "default": "FILTER_OP_EQ", "enum": [ "FILTER_OP_EQ", "FILTER_OP_NE", "FILTER_OP_GT", "FILTER_OP_GTE", "FILTER_OP_LT", "FILTER_OP_LTE", "FILTER_OP_IN", "FILTER_OP_NIN", "FILTER_OP_CONTAINS", "FILTER_OP_MATCH", "FILTER_OP_MATCH_PHRASE" ] }, "SortFieldItem": { "type": "object", "additionalProperties": false, "required": [ "field" ], "properties": { "field": { "type": "string", "description": "排序字段名；建议以 /meta-catalog 返回 sortable=true 字段为准。" }, "order": { "$ref": "#/components/schemas/SortOrder" } } }, "SortOrder": { "type": "string", "default": "SORT_ORDER_DESC", "enum": [ "SORT_ORDER_DESC", "SORT_ORDER_ASC" ] }, "FacetItem": { "type": "object", "additionalProperties": false, "required": [ "field" ], "properties": { "field": { "type": "string", "description": "聚合字段名，须 filterable=true。" }, "size": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } }, "FreshnessBoost": { "type": "string", "default": "NONE", "enum": [ "NONE", "MILD", "STRONG" ], "description": "模糊搜索新鲜度加权；仅 query 非空时生效。" }, "MetaPaperRelationsRequest": { "type": "object", "additionalProperties": false, "required": [ "unique_id", "relation" ], "properties": { "unique_id": { "type": "string", "minLength": 1, "description": "目标论文 unique_id，来自 /meta-search 或 /agentic-search；不要传 doc_id。" }, "relation": { "$ref": "#/components/schemas/MetaPaperRelationType" }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "页码，从 1 开始。" }, "page_size": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25, "description": "每页数量。" } } }, "MetaPaperRelationType": { "type": "string", "enum": [ "CITATIONS", "REFERENCES", "RELATED_WORKS" ], "description": "关系类型。CITATIONS=被引（谁引用了目标论文）；REFERENCES=参考文献（目标论文引用了谁）；RELATED_WORKS=相关工作。" }, "MetaPaperRelationsResponse": { "type": "object", "additionalProperties": false, "required": [ "items", "total_count", "page", "page_size", "total_pages", "code", "message", "biz_code" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MetaPaperRelationItem" } }, "total_count": { "type": "integer", "minimum": 0 }, "page": { "type": "integer", "minimum": 1 }, "page_size": { "type": "integer", "minimum": 1, "maximum": 200 }, "total_pages": { "type": "integer", "minimum": 0 }, "code": { "type": "string", "example": "SUCCESS" }, "message": { "type": "string", "example": "成功" }, "biz_code": { "type": "integer", "example": 0 } } }, "MetaPaperRelationItem": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "关系论文标识，如 DOI、OpenAlex ID 或内部 ID。" }, "id_type": { "type": "string", "description": "id 类型。" }, "title": { "type": "string", "description": "关系论文标题。" } } }, "MetaSearchResponse": { "type": "object", "additionalProperties": false, "required": [ "results", "total_count", "page", "page_size", "total_pages", "search_time_ms" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/MetaSearchRecord" } }, "total_count": { "oneOf": [ { "type": "integer", "format": "int64" }, { "type": "string" } ], "description": "匹配总数；最大 10000，触顶表示大于等于 10000。protobuf JSON 中 int64 可能序列化为字符串。" }, "page": { "type": "integer", "minimum": 1 }, "page_size": { "type": "integer", "minimum": 1, "maximum": 200 }, "total_pages": { "type": "integer", "minimum": 0 }, "search_time_ms": { "type": "number" }, "next_cursor": { "type": "string", "description": "深翻页游标；空字符串表示无更多结果。" }, "facets": { "type": "array", "items": { "$ref": "#/components/schemas/FacetResult" }, "default": [] } } }, "MetaSearchRecord": { "type": "object", "additionalProperties": true, "properties": { "doc_id": { "type": "string", "description": "全文 artifact 内容哈希；仅当文档有全文时存在，可传给 /content。" }, "unique_id": { "type": "string", "description": "元数据记录全局唯一 ID。" }, "title": { "type": "string" }, "abstract": { "type": "string" }, "doi": { "type": "string" }, "author": { "type": "array", "items": { "type": "string" } }, "publication_published_year": { "type": "integer" }, "publication_published_date": { "type": "string" }, "publication_venue_name_unified": { "type": "string" }, "publication_venue_type": { "type": "string" }, "citation_count": { "type": "integer" }, "influential_citation_count": { "type": "integer" }, "metadata_type": { "type": "string" }, "language": { "type": "string" }, "lang": { "type": "string" } }, "description": "元数据记录。实际字段由 fields 投影、默认字段集和 Token 字段权限共同决定；protobuf JSON 会省略零值字段。" }, "FacetResult": { "type": "object", "additionalProperties": true, "properties": { "field": { "type": "string" }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/FacetBucket" } } } }, "FacetBucket": { "type": "object", "additionalProperties": true, "properties": { "key": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" } ] }, "doc_count": { "oneOf": [ { "type": "integer", "format": "int64" }, { "type": "string" } ], "description": "protobuf JSON 中 int64 可能序列化为字符串。" } } } } } }