academic-retrieval

Sciverse 学术论文检索：支持结构化元数据搜索、面向 RAG 的语义分块检索，以及按字节范围读取原文内容。适用于需要引用级科学文献的智能体工作流。

适用场景

当用户请求涉及以下任一情况时，触发该技能：

• 根据结构化条件（作者、年份、期刊、学科等）定位学术论文
• 基于论文片段生成答案（RAG / 引用支撑）
• 围绕已知 doc_id 扩展原始文本（在某一分块前后读取更多字节）

认证方式

该技能需配置环境变量 SCIVERSE_API_TOKEN（请从 https://sciverse.space 获取）。可选设置 SCIVERSE_BASE_URL 以覆盖默认 API 基地址。

工具列表

search_papers

基于结构化筛选条件（标题、作者、期刊、年份、学科等）搜索学术论文。
适用场景示例：“查找 Hinton 在 2020–2023 年发表的论文”、“查找《Nature》上关于 CRISPR 的论文”。
不适用于：自然语言问答式检索（请使用 semantic_search）或获取全文片段（请使用 read_content）。
返回值：论文列表；每项包含 unique_id（始终存在）、doc_id（仅当存在全文时提供）、title、author、abstract、publication_venue_name_unified、publication_published_year。

调用方式：node scripts/search_papers.mjs ''

semantic_search

自然语言语义搜索，返回适用于 RAG 式问答的相关论文分块。
适用场景示例：“Transformer 的注意力机制如何工作？”、“近期蛋白质结构预测有哪些方法？”
不适用于：精确字段过滤（请使用 search_papers）或获取完整原文（请使用 read_content）。
返回值：分块列表；每项包含 chunk_id、doc_id、abstract、chunk、score、title、offset。
典型链路：semantic_search → 选取分块 → read_content(doc_id, offset)。

调用方式：node scripts/semantic_search.mjs ''

list_catalog

返回 search_papers 的 Schema 目录：包括所有字段名、类型、是否可过滤 / 可排序、是否默认返回、人工描述，以及适用的 FilterOperators。
适用场景示例：“哪个字段用于按 DOI 过滤？”、“access_oa_status 可取哪些值？”、“metadata_type 对应的正确枚举是什么？”
不适用于：实际执行论文搜索（请使用 search_papers 或 semantic_search）。
典型用法：首次接触 Sciverse 或遇到字段含义模糊时调用一次，随后依据返回的 Schema 构建精准的 search_papers 过滤器。
传入 include_sample_values=true 可额外获取类枚举字段的 Top-20 样本值（基于 OpenSearch terms 聚合，缓存 24 小时）。

调用方式：node scripts/list_catalog.mjs ''

list_paper_relations

分页获取某篇论文的完整关系列表。citations / references / related_works 是无界数组（高被引论文可能拥有数千条），而 search_papers 仅内联少量截断结果，因此需通过此接口获取完整列表。
适用场景示例：“论文 X 引用了哪些文献？”（relation=REFERENCES）、“哪些论文引用了论文 X？”（relation=CITATIONS）、“与论文 X 相关的研究成果有哪些？”（relation=RELATED_WORKS）。
注意：CITATIONS（入向引用：谁引用了我）与 REFERENCES（出向引用：我引用了谁）方向相反。
典型链路：先通过 search_papers / semantic_search 获取 unique_id，再按 relation 分页调用本接口。

调用方式：node scripts/list_paper_relations.mjs ''

read_content

读取论文原文 UTF-8 编码字节范围的内容。通常配合 semantic_search 返回的 doc_id / offset 使用，以扩展上下文（在某一分块前后读取更多字节）。
返回值：text fragment、bytes_returned、next_offset、more（布尔值）。

调用方式：node scripts/read_content.mjs ''

get_resource

返回由 read_content 输出的 Markdown 中通过 ![alt](file_name) 占位符所引用的论文图表 / 表格图像的原始二进制数据。
适用场景：当用户要求查看 / 展示 / 描述某张图，且 read_content 输出中包含图像引用时。
输入参数 file_name 来自 Markdown 中 URL 部分（相对路径，不含 \ 或 ..）。
返回值：原始图像流 + image/* Content-Type。SDK / MCP server 会将字节封装为 base64 + mimeType，以便 Claude（多模态模型）直接解析图像。

调用方式：node scripts/get_resource.mjs ''

启动指南：优先学习 Schema

若不确定可用字段或某枚举类型的取值范围（例如 metadata_type、language、access_oa_status），请在开始前调用一次 list_catalog。低基数字段将返回样本值。请勿猜测字段名——猜测会浪费调用轮次。

list_catalog(include_sample_values=true)
    └─▶ fields[].name + sample_values  →  构建精准过滤器

常用模式

RAG 流程（自然语言问答）：

semantic_search(query=...) → hits[i].doc_id, hits[i].offset
    └─▶ read_content(doc_id, offset)

按 DOI 查找：

search_papers(filters_advanced=[{field: "doi", value: "10.1038/..."}])

开放获取 + 年份过滤：

search_papers(
    year_from=2024,
    filters_advanced=[{field: "access_is_oa", value: "true"}]
)

结构化 + 语义混合检索：

search_papers(authors=[...], year_from=2020) → doc_ids
semantic_search(query=...) → 客户端按 doc_ids 过滤 hits

倾向近期成果的模糊搜索（新鲜度增强）：

设置 freshness_boost 参数，使结果按发表日期加权（高斯衰减）。仅当 query 非空时生效，且与 sort_by_year 互斥。

search_papers(query="large language model", freshness_boost="STRONG")
    # STRONG：3 年衰减周期，适用于追踪研究动向
search_papers(query="protein folding", freshness_boost="MILD")
    # MILD：10 年衰减周期，适用于日常文献检索

检索作者或期刊（集合）：

将 collection 设为 authors 或 sources（默认为 papers）即可检索对应实体。各集合拥有独立字段集——请先调用 list_catalog(collection="authors")；filters_advanced 和 sort_advanced 支持全部字段，但 papers 的便捷字段仅对 papers 生效。

search_papers(collection="authors",
    filters_advanced=[{field: "summary_stats.h_index", operator: "FILTER_OP_GTE", value: 50}],
    sort_advanced=[{field: "cited_by_count", order: "SORT_ORDER_DESC"}])

获取论文图表 / 图像：

当 read_content 返回的 Markdown 中包含 ![alt](file_name) 时，使用该 file_name 调用 get_resource 获取图像二进制数据。

read_content(doc_id, offset) → markdown ![Figure 3](dt=xxx/p/f3.png)
    └─▶ get_resource(file_name="dt=xxx/p/f3.png")

读取全文（请先检查）：

每个 search_papers 结果均携带 is_content_accessible（布尔值）：仅当论文存在全文且调用方具备权限时为 true。在调用 read_content(doc_id, ...) 前务必检查该字段——false 表示无全文或无读取权限。

退出码说明

• 0 — 成功；标准输出为 JSON 响应
• 1 — HTTP 4xx/5xx 错误；标准错误输出包含状态码及响应体
• 2 — 参数错误（缺失 token、JSON 格式错误、必填字段缺失）