openapi: 3.0.3 info: title: Sciverse Agent Tools description: | Sciverse 开放平台面向 AI Agent 的检索能力 API。 所有接口均需 Bearer Token 鉴权（来自 platform-console 控制台）。 x-en-description: | Sciverse open platform retrieval API for AI agents. All endpoints require Bearer Token authentication (obtain one from https://sciverse.space). The platform indexes academic papers (titles, authors, abstracts, full-text chunks) for citation-grade RAG. version: 0.14.0 x-sciverse-tools-version: 0.14.0 tags: - name: search description: 检索类操作（结构化元数据 + 语义检索） - name: content description: 原文读取类操作 - name: introspection description: 字段 catalog / schema introspection - name: resource description: 文献附属资源（图片等） servers: - url: https://api.sciverse.space description: 生产环境 paths: /meta-search: post: tags: [search] summary: 按结构化条件检索学术文献元数据 operationId: search_papers description: | 按结构化条件检索学术文献元数据（标题、作者、期刊、年份、摘要等）。 适用：「查找 Hinton 在 2020-2023 年发表的论文」「找 Nature 上关于 CRISPR 的近期文献」。 不适用：自然语言问答检索 → 用 semantic_search；查全文片段 → 用 read_content。 返回：论文元数据列表，每条含 unique_id（始终存在）、doc_id（仅当有全文）、title、author、abstract、publication_venue_name_unified、publication_published_year 等。 x-en-summary: Search academic papers by structured filters x-en-description: | Search academic papers by structured filters (title, authors, journal, year, subjects, etc.). Use when: "find Hinton's papers from 2020-2023", "Nature papers on CRISPR". Not for: natural-language Q&A retrieval (use semantic_search) or full-text snippets (use read_content). Returns: list of papers; each entry has unique_id (always present), doc_id (only when full text exists), title, author, abstract, publication_venue_name_unified, publication_published_year. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchPapersRequest' responses: '200': description: 检索结果 content: application/json: schema: $ref: '#/components/schemas/SearchPapersResponse' '400': { $ref: '#/components/responses/BadRequest' } '401': { $ref: '#/components/responses/Unauthorized' } '502': { $ref: '#/components/responses/BadGateway' } /agentic-search: post: tags: [search] summary: 自然语言语义检索（RAG 用） operationId: semantic_search description: | 自然语言语义检索，返回相关文献片段（chunk）用于 RAG 回答。 适用：「Transformer 注意力机制如何工作？」「最新的蛋白质折叠预测方法有哪些？」 不适用：精确字段过滤 → search_papers；取完整原文 → read_content。 返回：相关 chunk 列表，每条含 chunk_id/doc_id/abstract/chunk/score/title/offset。 典型链路：semantic_search → 选取 chunk → read_content(doc_id, offset)。 x-en-summary: Semantic search over academic papers (for RAG) x-en-description: | Natural-language semantic search returning relevant paper chunks for RAG-style answering. Use when: "How does Transformer attention work?", "What are recent methods for protein structure prediction?". Not for: precise field filtering (use search_papers) or fetching full original text (use read_content). Returns: list of chunks; each entry has chunk_id, doc_id, abstract, chunk, score, title, offset. Typical chain: semantic_search → pick chunk → read_content(doc_id, offset). requestBody: required: true content: application/json: schema: { $ref: '#/components/schemas/SemanticSearchRequest' } responses: '200': description: 检索结果 content: application/json: schema: { $ref: '#/components/schemas/SemanticSearchResponse' } '400': { $ref: '#/components/responses/BadRequest' } '401': { $ref: '#/components/responses/Unauthorized' } '502': { $ref: '#/components/responses/BadGateway' } '503': description: 嵌入或检索后端暂不可用 content: application/json: schema: { $ref: '#/components/schemas/ApiError' } /meta-catalog: get: tags: [introspection] summary: 列出所有可用字段、能否过滤/排序、枚举值样本 operationId: list_catalog description: | 返回 search_papers 所有可用字段的 catalog：字段名、类型、能否过滤/排序、 是否默认返回、字段说明、FilterOperator 清单等。 适用：「我该用哪个字段过滤 DOI?」「access_oa_status 有哪些可能值？」 「`metadata_type` 的合法取值是？」 不适用：实际查询文献，那是 search_papers / semantic_search 的事。 典型用法：Agent 第一次接触 Sciverse 或碰到模糊字段需求时先调一次本接口， 把 schema 装进 working memory，后续精确构造 search_papers 的 filters。 include_sample_values=true 时返回枚举值样本（OpenSearch terms agg，缓存 24h）。 x-en-summary: List available fields, filterability, and sample values x-en-description: | Returns the schema catalog for search_papers: every field name, type, whether it's filterable / sortable, default-return status, human description, and applicable FilterOperators. Use when: "Which field do I filter by DOI?", "What values can access_oa_status take?", "What's the right enum for metadata_type?". Not for: actually searching papers (use search_papers / semantic_search). Typical pattern: call once when first encountering Sciverse or facing an ambiguous field need, then construct precise search_papers filters from the returned schema. Pass include_sample_values=true to also fetch top-20 values for enum-like fields (OpenSearch terms aggregation, 24h cached). parameters: - name: collection in: query required: false schema: { type: string, enum: [papers, authors, sources], default: papers } description: 字段 catalog 所属实体集合。papers（默认）/ authors / sources，各 collection 字段不同。 - name: include_sample_values in: query required: false schema: { type: boolean, default: false } description: 是否拉取 enum-like 字段的取值样本。false 仅返回静态 schema（毫秒级）；true 触发 OpenSearch terms agg（首次几百毫秒，之后 24h 走缓存）。 - name: include_field_stats in: query required: false schema: { type: boolean, default: false } description: 是否返回字段统计（keyword 字段基数 + 数值字段 min/max/avg/p50/p95）。触发 OpenSearch 聚合，缓存 24h。 responses: '200': description: catalog content: application/json: schema: { $ref: '#/components/schemas/CatalogResponse' } '401': { $ref: '#/components/responses/Unauthorized' } '502': { $ref: '#/components/responses/BadGateway' } /meta-paper-relations: post: tags: [search] summary: 分页查一篇论文的引用/被引/相关工作列表 operationId: list_paper_relations description: | 分页返回某篇论文的引用关系完整列表。citations/references/related_works 是无界数组 （单篇最大 34 万条），在 search_papers 中**不可投影**，取这些列表只能用本接口。 适用：「论文 X 引用了哪些文献」（relation=REFERENCES）、「哪些文献引用了论文 X」 （relation=CITATIONS）、「与论文 X 相关的工作」（relation=RELATED_WORKS）。 注意：CITATIONS（被引：谁引用了我）与 REFERENCES（参考文献：我引用了谁）方向相反。 典型链路：先 search_papers / semantic_search 拿到 unique_id，再用本接口按 relation 分页。 两个上限（仅 CITATIONS 可能触发；REFERENCES/RELATED_WORKS 实测最大 11833/20 条）： 关系数超 10000 返回 429；page×page_size 超 10000 返回 400。两种情况都改用 search_papers 的 filters_advanced 传 references_unique_id 反查——可深翻页并任意排序。 total_count 为库内命中数（不含指向库外论文的边），与论文自身 citation_count 可能有 ±1% 差异。 x-en-summary: Paginate a paper's citations / references / related works x-en-description: | Paginate the full relation list of a paper. citations/references/related_works are unbounded arrays (up to 340k entries for a single paper) and are NOT projectable in search_papers, so this endpoint is the only way to read them. Use when: "What does paper X cite?" (relation=REFERENCES), "Which papers cite paper X?" (relation=CITATIONS), "Works related to paper X" (relation=RELATED_WORKS). Note: CITATIONS (incoming: who cites me) and REFERENCES (outgoing: who I cite) are opposite directions. Typical chain: get unique_id from search_papers / semantic_search, then paginate here by relation. Two limits (CITATIONS only; REFERENCES/RELATED_WORKS max out at 11833/20 in practice): more than 10000 relations returns 429; page*page_size above 10000 returns 400. In both cases switch to search_papers with filters_advanced on references_unique_id — it supports deep paging and arbitrary sorting. total_count counts in-corpus matches only, so it can differ from the paper's own citation_count by about 1%. requestBody: required: true content: application/json: schema: type: object required: [unique_id, relation] properties: unique_id: type: string description: 目标论文 unique_id（如 paper:10.1038/xxx），来自 search_papers / semantic_search；勿传 doc_id。 relation: type: string enum: [CITATIONS, REFERENCES, RELATED_WORKS] description: 关系类型。CITATIONS=被引（谁引用了我）；REFERENCES=参考文献（我引用了谁）；RELATED_WORKS=相关工作。 page: type: integer default: 1 minimum: 1 page_size: type: integer default: 25 minimum: 1 maximum: 200 responses: '200': description: 关系列表 content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: { type: string } id_type: { type: string } title: { type: string } total_count: { type: integer } page: { type: integer } page_size: { type: integer } total_pages: { type: integer } '400': { $ref: '#/components/responses/BadRequest' } '401': { $ref: '#/components/responses/Unauthorized' } '404': description: unique_id 对应文档不存在 content: application/json: schema: { $ref: '#/components/schemas/ApiError' } '502': { $ref: '#/components/responses/BadGateway' } /content: get: tags: [content] summary: 按字节区间读取文献原文片段 operationId: read_content description: | 按字节区间读取文献原文片段。通常配合 semantic_search 返回的 doc_id/offset 使用， 用于扩展上下文（往前/往后读更多字节）。 返回：UTF-8 文本片段、bytes_returned、next_offset、是否还有后续。 x-en-summary: Read paper content by byte range x-en-description: | Read a UTF-8 byte range of a paper's original text. Typically used with a doc_id/offset returned by semantic_search to expand context (read more bytes before or after a chunk). Returns: text fragment, bytes_returned, next_offset, more (boolean). parameters: - name: doc_id in: query required: true schema: { type: string } description: 文献 ID（来自 search_papers / semantic_search）。 - name: offset in: query required: false schema: { type: integer, format: int64, default: 0 } - name: limit in: query required: false schema: { type: integer, format: int64, default: 4096, maximum: 16384 } responses: '200': description: 内容片段 content: application/json: schema: { $ref: '#/components/schemas/ReadContentResponse' } '400': { $ref: '#/components/responses/BadRequest' } '401': { $ref: '#/components/responses/Unauthorized' } '502': { $ref: '#/components/responses/BadGateway' } /resource: get: tags: [resource] summary: 取文献附属图片（论文中的 Figure / Table 等） operationId: get_resource description: | 按文件名取文献中嵌入的图片字节流（PNG / JPG 等）。 触发场景：read_content 返回的 Markdown 中含 `![alt](file_name)` 形式的图片占位， agent 需要把图给用户看时调本接口。 入参 file_name 来自 markdown 内的 url 段（相对路径，禁止 `\\` 或 `..`）。 返回：HTTP 二进制流 + image/* Content-Type。 SDK / MCP server 包装层会做 base64 + mime 转换以便 agent 多模态使用。 x-en-summary: Fetch a paper-embedded image by file name x-en-description: | Returns the binary bytes of a paper figure / table image referenced inside read_content's Markdown via `![alt](file_name)` placeholders. Use when the user asks to see / display / describe a figure and read_content output contains an image reference. Input file_name comes from the Markdown URL part (relative path, no `\\` or `..`). Returns: raw image stream + image/* Content-Type. The SDK / MCP server wraps the bytes as base64 + mimeType so Claude (multimodal) can read the image directly. parameters: - name: file_name in: query required: true schema: { type: string } description: 图片相对路径，来自 read_content Markdown 中的 `![alt](file_name)` 占位。禁止 `\\` 与 `..`，不能以 `/` 开头。 responses: '200': description: 图片二进制流 content: image/png: { schema: { type: string, format: binary } } image/jpeg: { schema: { type: string, format: binary } } image/*: { schema: { type: string, format: binary } } '400': { $ref: '#/components/responses/BadRequest' } '401': { $ref: '#/components/responses/Unauthorized' } '502': { $ref: '#/components/responses/BadGateway' } components: securitySchemes: bearerAuth: type: http scheme: bearer schemas: SearchPapersRequest: type: object properties: collection: type: string enum: [papers, authors, sources] default: papers description: >- 检索的实体集合。papers（默认，论文）/ authors（作者）/ sources（来源期刊）。 各 collection 字段集不同，用 list_catalog（collection=）学习对应 schema。 注意：本工具的便捷字段（authors/journals/year_from/subjects 等）只对 papers 有意义； 查 authors/sources 时改用 filters_advanced + 该 collection 的字段名（如 authors 的 summary_stats.h_index / orcid，sources 的 issn / is_oa）。authors 用 orcid、 sources 用 issn 与论文检索结果关联。 x-en-description: >- Entity collection to search. papers (default) / authors / sources. Each collection has its own field schema — call list_catalog(collection=). The convenience fields (authors/journals/year_from/subjects) apply to papers only; for authors/sources use filters_advanced with that collection's field names. query: type: string description: BM25 全文关键词，匹配标题/摘要/期刊名/关键词字段。留空则纯靠结构化过滤。 title_contains: type: string description: 标题中必须包含的词（仅匹配 title 字段）。 abstract_contains: type: string description: 摘要中必须包含的词（仅匹配 abstract 字段）。 authors: type: array items: { type: string } description: 作者名（任一命中即可）。SDK 内部映射到后端 `author` 字段（FILTER_OP_IN）。 year_from: type: integer description: 起始发表年（含）。 year_to: type: integer description: 结束发表年（含）。 journals: type: array items: { type: string } description: 期刊名（任一命中即可）。SDK 内部映射到后端 `publication_venue_name_unified` 字段（FILTER_OP_IN，规范化后的载体名）。 subjects: type: array items: { type: string } description: 学科分类，如 "computer science"、"biology"。 filters_advanced: type: array description: | 高级过滤逃生舱（仅当上述字段不够用时使用）。可用字段见 get_field_catalog。 引文反查（常用）：field="references_unique_id" 查「谁引用了某篇论文」， value 填目标论文的 unique_id。相比 list_paper_relations 的 CITATIONS， 它支持深翻页与任意排序，适合超高被引论文。可叠加条件， 例如「引用了 ResNet 且 2023 年后发表」： [{"field":"references_unique_id","value":"paper:10.1109/cvpr.2016.90"}, {"field":"publication_published_year","operator":"FILTER_OP_GTE","value":2023}] 该字段仅支持过滤，不能排序/聚合，也不能放进 fields 返回。 items: type: object required: [field, value] properties: field: { type: string } operator: type: string description: >- 过滤操作符。MATCH（分词模糊）适用于 author、keywords（输入 "Hinton" 命中 "Geoffrey Hinton"）； MATCH_PHRASE（短语模糊）适用于 publication_venue_name_unified，整词连续匹配（"Nature" 命中 "Nature Communications"；非前缀匹配，"Nature Comm" 不会命中）； doi 用 EQ，服务端归一化（去 doi.org 前缀+转小写）后精确匹配。MATCH/MATCH_PHRASE 仅对配了 text 子字段的字段有效。 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] default: FILTER_OP_EQ value: {} sort_advanced: type: array description: >- 高级排序逃生舱（按任意可排序字段）。papers 用 sort_by_year 即可； authors/sources 想按 h-index / 被引 / works_count 排序时用本字段。 与 query 互斥（query 走相关性排序）。 items: type: object required: [field, order] properties: field: { type: string } order: type: string enum: [SORT_ORDER_DESC, SORT_ORDER_ASC] default: SORT_ORDER_DESC sort_by_year: type: string enum: [auto, desc, asc, none] default: auto description: | 按发表年份排序。默认 auto：传了 query（或 sort_advanced）时不加年份排序 ——保留 BM25 相关性排序，且 freshness/impact/language_affinity 软加权可用； 纯结构化筛选（无 query）时按年份降序（否则后端默认序是 unique_id，实质乱序）。 ⚠️ 不要用 query + desc 求「最相关且最新」：显式排序会让 query 退化为命中 过滤（OR 语义、无相关性排序）、三个软加权全部失效——返回的是「含任一关键词 的最新文档」。要「相关且偏新」请用 freshness_boost。 freshness_boost: type: string enum: [NONE, MILD, STRONG] default: NONE description: | 模糊搜索新鲜度加权：结果偏向新文献（仅 query 非空时生效；传排序 （sort_by_year 非 none / sort_advanced）时被忽略，硬排优先）。 MILD: 近 10 年加权，适合日常查文献；STRONG: 近 3 年加权，适合跟踪 研究方向 / 追最新进展。与 impact_boost / language_affinity 可叠加 （均为乘法因子）。boost 生效时为浅翻页：不产 next_cursor、不支持 cursor 深翻页。 impact_boost: type: string enum: [NONE, MILD, STRONG] default: NONE description: | 模糊搜索影响力加权：高被引文献在保留相关性的前提下上浮（仅 query 非空时生效；传排序时被忽略）。MILD: 轻度上浮，相关性仍主导； STRONG: 明显偏向高被引。引用因子有界、零被引中性（不会归零）。 与 freshness_boost / language_affinity 可叠加；boost 生效时为浅翻页。 language_affinity: type: string enum: [NONE, MILD, STRONG] default: NONE description: | 模糊搜索语言亲和加权：非 query 语言的结果降序、但不排除（仅 query 非空时生效；传排序时被忽略）。目标语言由服务端从 query 文本判定 （假名→ja / 谚文→ko / 汉字→zh / 拉丁→en，其他书写系统不生效）； 语言未知的文献保持中性不降权。MILD: 非目标语言 ×0.5，跨语言强相关 结果仍可上浮；STRONG: ×0.2，几乎只看目标语言。与 freshness_boost / impact_boost 可叠加；boost 生效时为浅翻页。要硬排除某语言请改用 filters_advanced 的 language 字段（如 {"field":"language","value":"en"}， 软硬两层语义不同：本参数只调序，filter 直接排除）。 page: type: integer default: 1 minimum: 1 page_size: type: integer default: 10 minimum: 1 maximum: 50 SearchPapersResponse: type: object required: [results, total_count, page, page_size] properties: results: type: array items: { $ref: '#/components/schemas/PaperMetadata' } description: 命中论文列表（后端字段名为 results，非 hits）。 total_count: type: integer description: 命中总数；超过 10000 会被截断为 10000，需精确值时改用深翻页/计数。 page: { type: integer } page_size: { type: integer } total_pages: type: integer description: 总页数。 next_cursor: type: string description: 深翻页游标，为空表示无更多。page*page_size>10000 时必须改用 cursor（把此值回填到请求的 cursor）。 search_time_ms: type: number format: float description: 检索耗时（毫秒）。 request_tokens: type: integer description: 输入 query 的 token 数。 response_tokens: type: integer description: 输出结果文本字段的 token 数。 PaperMetadata: type: object required: [unique_id, title] description: | 文献元数据。字段名与 metadata-service 后端 `fields.py` 的真实字段一致， SDK 不做响应转换。 --- 系统标识符两个分层（按需选用）: - `unique_id`: 元数据记录的全局唯一 ID。任何记录都有，与是否存在 全文无关；适合做引用、去重、跨服务关联、引用图谱节点。 - `doc_id`: 全文 artifact 的内容哈希（sha256）。仅在文档存在 全文时返回；元数据-only 记录无此字段。要拉全文走 `read_content` 接口必须用 doc_id。 前端展示稳定 ID 用 unique_id；跨接口取全文用 doc_id。 properties: unique_id: type: string description: 元数据记录的全局唯一 ID（任何记录都有，与是否有全文无关）。 doc_id: type: string description: 全文 artifact 的内容哈希（sha256）。仅当文档存在全文时返回；元数据-only 记录无此字段，且无法用 doc_id 过滤命中。 is_content_accessible: type: boolean description: 正文对当前调用方是否可见 = 文档有全文（后端 access_xinghe_repository_process_status==1）且调用方被授权读全文 artifact。true 时可用 doc_id 调 read_content 取正文；false 表示无全文或无读取权限。服务端注入，不受 fields 投影影响。 title: { type: string } author: type: array items: type: object properties: name: { type: string } orcid: { type: string } description: 作者列表（OS object 数组，子字段 name/orcid）。按作者名检索：精确走 author.name.keyword、模糊 MATCH 走 author.name；对外过滤仍传 field "author"。 abstract: { type: string } publication_venue_name_unified: type: string description: 发表载体名称（期刊/会议；规范化形式——消除缩写/大小写/标点噪声，适合精确匹配/分组聚合）。 publication_published_year: { type: integer } subjects: type: array items: { type: string } keywords: type: array items: { type: string } doi: { type: string } SemanticSearchRequest: type: object required: [query] properties: query: type: string minLength: 1 maxLength: 4096 description: 自然语言查询，1-200 字最佳。 top_k: type: integer default: 10 minimum: 1 maximum: 100 description: | 返回命中条数上限，合法 1-100（服务端校验，超出报 400）。 实际条数还受 mode 影响：balanced 单路混合召回在服务端固定截到约 50 条， top_k 超过 50 时多出的部分不会返回；fast 与 quality 可取到 top_k。 另外同一篇论文最多返回约 3 个 chunk，因此高 top_k 需要命中足够多的不同论文。 source_types: type: array items: { type: string, enum: [web, pdf] } filters: type: object description: | 结构化过滤（可选）。在召回阶段与语义检索同时生效（ES+Milvus 双引擎下推， 不是结果后过滤）；多个字段之间 AND，同一字段传数组时数组内 OR。 ⚠️ 宽松（软）语义：chunk 侧元数据缺失的文档不会被排除——例如按年份过滤时， 缺年份信息的 chunk 仍可能返回。需要严格范围保证时勿当硬约束使用， 表述结论时注明范围为"近似过滤"。 数值/日期字段支持区间：{"gte":2020,"lte":2025} 或 [min,max]（null 表示一侧不限）； 日期接受 YYYY / YYYY-MM / YYYY-MM-DD。 实际可用字段受账号字段权限约束；未知字段服务端返回 400。 例：{"author":["Hinton"],"publication_published_year":{"gte":2023}, "topics":{"dimensions":{"primary_topic_domain":"Health Sciences"}}} properties: lang: description: 语言代码，如 "en"、"zh"；也接受别名 language。 metadata_type: description: 资源类型，仅单值："paper" 或 "ebook"。 author: description: 作者名，string 或 string[]（数组=任一命中）。 publication_venue_name_unified: description: 发表载体名称（期刊/会议，规范化名，适合精确匹配）。 publication_venue_type: description: 载体类型："journal"、"conference"、"repository"、"book series"、"ebook platform"、"metadata"、"raidRegistry"、"igsnCatalog"、"other"（不区分大小写）。 publication_published_year: description: 发表年份，单值或区间（{"gte":..,"lte":..} / [min,max]）。 publication_published_date: description: 发表日期，"YYYY[-MM[-DD]]" 单值或区间。 citation_count: description: 被引次数，单值或区间。 influential_citation_count: description: 高影响力被引次数，单值或区间。 title: description: 标题精确匹配（标题检索一般更适合 search_papers）。 topics: description: 主题组合过滤：{"logic":"and|or","dimensions":{"primary_topic":"...","primary_topic_domain":"Physical Sciences|Social Sciences|Health Sciences|Life Sciences"}}；logic 省略默认 or。 doc_id: description: | 唯一的硬约束字段（其余字段均为软语义）：命中绝不越出给定集合。 值为 64 位小写 hex sha256（即 search_papers 返回的 doc_id；仅有全文的论文才有）， string 或 string[]，仅 eq/in。去重后上限默认 1000，超限返回 400 SCOPE_TOO_LARGE； 显式传空数组返回 200 空 hits（候选集为空，不退化为全局检索）。 典型用法：先 search_papers 圈定候选集合，再在集合内做受限语义检索。 mode: type: string enum: [fast, balanced, quality] default: balanced description: | fast = 仅关键词召回 (~200ms)；balanced = 混合检索 (~600ms)；quality = LLM 改写 + 混合 (~2-4s)。 SemanticSearchResponse: type: object required: [hits] properties: hits: type: array items: { $ref: '#/components/schemas/SearchChunk' } SearchChunk: type: object required: [chunk_id, doc_id, score, title, offset] properties: chunk_id: { type: string } doc_id: { type: string } title: { type: string } abstract: { type: string } chunk: { type: string } score: { type: number, format: float } offset: type: integer format: int64 description: chunk 在原文中的字节偏移，可直接传给 read_content。 page_no: { type: integer } source_type: { type: string } ReadContentResponse: type: object required: [text, bytes_returned, next_offset, more] properties: text: { type: string } bytes_returned: { type: integer } next_offset: { type: integer, format: int64 } more: type: boolean description: 为 true 表示可能还有后续字节，可用 next_offset 继续请求。 CatalogResponse: type: object required: [fields, default_fields, filter_operators] properties: fields: type: array items: { $ref: '#/components/schemas/FieldCatalogEntry' } default_fields: type: array items: { type: string } description: search_papers 不传 fields 时默认返回的字段名清单。 filter_operators: type: array items: { type: string } description: 支持的 FilterOperator 名（不带 FILTER_OP_ 前缀，如 "EQ" / "IN" / "CONTAINS"）。 FieldCatalogEntry: type: object required: [name, type, filterable, sortable, searchable, default_returned] properties: name: type: string description: 字段名（与 search_papers 的 filters[].field 一致）。 type: type: string description: 业务类型，如 String / Integer / Boolean / Float / List[string] / List[object] / Object。 filterable: { type: boolean } sortable: { type: boolean } searchable: type: boolean description: 是否参与 query（BM25 全文搜索）。 default_returned: type: boolean description: 未指定 fields 时是否默认返回。 description: type: string description: 人类可读的字段说明（中文）。 sample_values: type: array items: { type: string } description: 该字段的取值样本（仅 enum-like 字段；高 cardinality 字段为空）。 operators: type: array items: { type: string } description: 适用的 FilterOperator 名（参考性，后端不强校验）。 ApiError: type: object required: [code, message] properties: code: { type: string } message: { type: string } request_id: { type: string } responses: BadRequest: description: 请求参数错误 content: application/json: schema: { $ref: '#/components/schemas/ApiError' } Unauthorized: description: Bearer Token 缺失或无效 content: application/json: schema: { $ref: '#/components/schemas/ApiError' } BadGateway: description: 上游服务不可用 content: application/json: schema: { $ref: '#/components/schemas/ApiError' } security: - bearerAuth: []