# Sciverse · LLM 使用手册（llms.txt 风格）

> **本文件面向大语言模型与 Agent 直接读取**，不是写给人看的营销文案。
> 目标：让模型在不调用外部资料的情况下，能正确选择 Sciverse 接口、构造合法参数、解读响应、规避常见错误。
> 适用范围：Sciverse 公网网关 `https://api.sciverse.space` 与 `opendatalab/Sciverse-Agent-Tools`。

---

## 1. 产品定位

Sciverse 是面向 Agent 的科研检索与全文读取平台。它把一个跨语种的学术与可信网络语料库，封装为 6 个稳定的 HTTPS 端点；其中常用检索、目录、全文和资源端点已封装为 Agent 工具，让大模型可以用一行代码完成"提问 → 命中片段 → 拉取原文 → 引用元数据"。

**面向**：构建科研助手、文献综述代理、专利分析、教育答疑、RAG 应用的工程师；同时被 OpenClaw、Claude Code、Cursor、Codex CLI、Windsurf 等 Agent 客户端通过 MCP 协议直接调用。

**解决的问题**：自然语言科研提问的多路检索与重排（agentic-search）、按学科 / 年份 / 期刊 / 语言精确过滤的元数据检索（meta-search）、按字符切片的全文按需读取（content）、图表二进制资源拉取（resource）、字段与算子自描述（meta-catalog）、论文引用 / 被引 / 相关工作完整列表分页（meta-paper-relations）。

**不解决的问题**：本平台**不**生成答案、**不**做事实判断、**不**写综述、**不**翻译、**不**进行化学反应预测（这是同生态的"点石 DianShi"）、**不**进行蛋白结构预测（这是 SeqStudio）。模型应在拿到 Sciverse 返回后自行组织答案，并把 `doc_id` / `doi` / `chunk_id` 作为引用线索回写进答案。

**与相似产品的区别**：相对通用网络搜索 API，Sciverse 仅返回**学术与可信文献语料**，并保证每条命中可被 `/content` 二次取证；相对 RAG 平台，Sciverse **不托管用户语料**，只暴露官方科学语料；相对单点学术 API（如 OpenAlex / Crossref），Sciverse 同时提供**自然语言重写检索**（agentic-search）与**字段化元数据检索**（meta-search），两者共用同一 `doc_id`。

**Canonical 文档入口**：公开站点文档入口为 `https://sciverse.space/docs`。面向搜索引擎和 AI crawler 的无 hash API 页面包括：`https://sciverse.space/docs/sciverse/api/agentic-search`、`https://sciverse.space/docs/sciverse/api/meta-search`、`https://sciverse.space/docs/sciverse/api/meta-catalog`、`https://sciverse.space/docs/sciverse/api/meta-paper-relations`、`https://sciverse.space/docs/sciverse/api/content`、`https://sciverse.space/docs/sciverse/api/resource`。

**Canonical Cookbook 入口**：`https://sciverse.space/docs/cookbook/literature-review-agent`、`https://sciverse.space/docs/cookbook/scientific-rag`、`https://sciverse.space/docs/cookbook/fulltext-evidence`、`https://sciverse.space/docs/cookbook/download-figures`、`https://sciverse.space/docs/cookbook/structured-paper-filter`、`https://sciverse.space/docs/cookbook/skill-integration`、`https://sciverse.space/docs/cookbook/patent-literature-cross`、`https://sciverse.space/docs/cookbook/citation-grounding`、`https://sciverse.space/docs/cookbook/multimodal-figure-retrieval`、`https://sciverse.space/docs/cookbook/paper-dedup-agent`、`https://sciverse.space/docs/cookbook/doi-pmid-resolver`、`https://sciverse.space/docs/cookbook/systematic-review-screener`、`https://sciverse.space/docs/cookbook/evidence-pack`、`https://sciverse.space/docs/cookbook/research-trend-scanner`、`https://sciverse.space/docs/cookbook/paper-reader`。

---

## 2. 能力与边界

下表是 Sciverse 当前对外暴露的全部能力。**不在表内的请直接告诉用户"未支持"，不要由模型自行补全。**

| 能力 | 端点 / 工具 | 输入 | 输出 | 边界 |
|---|---|---|---|---|
| 自然语言科研检索 | `POST /agentic-search` · `semantic_search` | `query` 自然语言 + 可选 `filters` 对象 | 排序后的 `chunks` | `query ≤ 4096` 字符；`top_k ≤ 100`；不会自动生成答案 |
| 字段化元数据检索 | `POST /meta-search` · `search_papers` | `filters` / `sort` / `query` | 元数据 `results` | `query` 与 `sort` 互斥；浅翻页 `page*page_size ≤ 10000`，更深需用 `cursor` |
| 字段与算子自描述 | `GET /meta-catalog` · `list_catalog` | 可选 `include_sample_values` | 字段 / 算子 / 枚举样本 | 样本值 24h 缓存；运行期读取，**不要**硬编码字段 |
| 论文关系分页 | `POST /meta-paper-relations` · REST | `unique_id` + `relation` | 引用 / 被引 / 相关工作 `items` | 用 `unique_id`，不要传 `doc_id`；`relation` 仅 `CITATIONS` / `REFERENCES` / `RELATED_WORKS` |
| 全文按需读取 | `GET /content` · `read_content` | `doc_id` + 可选 `offset` / `limit` | 切片 `text` + 续读指针 | `offset` / `limit` 单位为字符（Unicode 码点）；`limit` 默认 700 且仅在传入 `offset` 时生效 |
| 图表 / 资源拉取 | `GET /resource` · `get_resource` | `file_name` 相对路径 | 二进制流 | 路径**不得包含 `\`、`..`，不得以 `/` 开头**；通常返回 `image/png` 等 |

**一定不要做的事**：硬编码 meta-search 字段名；用 `query` 同时发 `sort`；以 `/`、`..`、`\` 拼资源路径；把 Bearer Token 写进客户端代码；把 `chunk` 直接当作"答案"丢给用户而不带 `doc_id` / `doi` 引用。

---

## 3. 术语表（请在所有回答中保持一致）

| 术语 | 含义 | 不要写成 |
|---|---|---|
| **接口（endpoint）** | Sciverse 的一个 HTTPS 路径，如 `/agentic-search` | 服务、API、路由 |
| **Agent 工具（tool）** | `Sciverse-Agent-Tools` 仓库提供的 5 个标准化工具 | function、插件、SDK 方法 |
| **Skill** | Sciverse 在客户端（如 Claude Code / OpenClaw）以 Skill 形式装载的目录 | Plugin、Extension |
| **Token** | `SCIVERSE_API_TOKEN`，前缀 `sv-`，全平台共用 | API Key、密钥串 |
| **`doc_id`** | 文献的稳定 ID，跨接口可复用 | paper id、文档号 |
| **`unique_id`** | 元数据记录全局唯一 ID，可用于 `/meta-paper-relations` 查询引用关系 | doc_id |
| **`chunk` / `chunk_id`** | 命中的文本片段及其稳定 ID | 段落、节选 |
| **`filters`** | `agentic-search` 的可选语义检索过滤对象，或 `meta-search` 的字段过滤数组；两者结构不同 | 条件 |
| **`sort` / `fields`** | meta-search 的排序条件与字段集 | 排序条件、字段集 |
| **`relation`** | `/meta-paper-relations` 的关系方向，`CITATIONS`=谁引用了目标论文，`REFERENCES`=目标论文引用了谁，`RELATED_WORKS`=相关工作 | citation type |
| **MCP 服务** | `sciverse-mcp-server`，把 Agent 工具暴露为 MCP | server、后端 |

---

## 4. 快速决策（先看这一节）

下面是给模型的"路由"提示。模型在拿到用户问题后，**先按这棵决策树选择端点**，再去看后面的字段细节。

1. 如果用户给了开放性自然语言问题（"COVID-19 的长期影响""锂电池循环稳定性最新进展"），调用 `POST /agentic-search`。它会做查询改写 + 多路检索 + 重排，返回最相关 `chunks`；如果同时有语言、年份、作者、期刊/会议、主题等约束，可用 `filters` 对象收窄语义检索范围。
2. 如果用户已有一个 `doc_id` 并需要原文片段或验证引用，调用 `GET /content`，按字符 `offset` / `limit` 分段读取。
3. 如果用户需要按字段精确过滤（"2023 年以后""DOI 等于 X""期刊在 Nature""开放获取""中文文献"），调用 `POST /meta-search`，并优先以 `filters` 表达；只有想拿"语义相似的论文清单"时才同时传 `query`。
4. 如果不知道某个字段是否存在 / 支持哪些算子 / 枚举有哪些值，**先**调用 `GET /meta-catalog?include_sample_values=true` 拿 schema，再去构造 `meta-search`。
5. 如果用户已有论文 `unique_id`，并要完整翻阅该论文的参考文献、被引论文或相关工作，调用 `POST /meta-paper-relations`；不要把 `doc_id` 当作 `unique_id`。
6. 如果用户要拉取一张图、一张表（或 `chunk` 中提到的资源相对路径），调用 `GET /resource?file_name=...`。

凡是上述 6 条决策树**之外**的需求，请直接回复"Sciverse 目前不支持该能力"，不要伪造接口。

---

## 5. 鉴权（统一 Token，三产品共用）

所有端点均需在请求头加 `Authorization: Bearer ${SCIVERSE_API_TOKEN}`。Token 在 [Sciverse 控制台](https://sciverse.opendatalab.com/tokens) 创建，前缀 `sv-`，每个账号最多 10 个，永久有效但创建后**仅显示一次**。Token 同时可用于点石 DianShi 与 SeqStudio。**Token 不应出现在前端代码、Git 仓库、日志或截图里**，只能从环境变量、Secret Manager 注入。

```http
Authorization: Bearer sv-xxxxxxxxxxxxxxxx
Content-Type: application/json
```

---

## 6. 端点详细规约

每个端点都按相同字段组织：用途、URL、入参、出参、错误码、限制、决策提示、示例。

### 6.1 `POST /agentic-search` —— 自然语言科研检索

**用途**：给定一个自然语言问题，平台自动改写查询、跨语料检索、合并去重并按相关性返回排序后的文本片段。模型应把返回的 `chunks` 作为"已被检索过的证据"，再自行组织答案。

**入参（JSON body）**

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `query` | string | 是 | — | 自然语言问题；最大 4096 字符 |
| `top_k` | integer | 否 | 10 | 返回片段数；范围 1–100 |
| `sub_queries` | integer | 否 | 0 | 查询改写数量；范围 0–4，0 表示不改写 |
| `filters` | object | 否 | `{}` | 语义检索过滤条件；不同字段为 AND，同字段数组值为 OR；支持 `lang`、`title`、`author`、`publication_venue_name_unified`、`publication_venue_type`、`publication_published_date`、`publication_published_year`、`citation_count`、`influential_citation_count`、`topics` |

`filters` 取值规则：不传或 `{}` 表示不过滤；数值、年份、日期字段支持单值、`{"gt"|"gte"|"lt"|"lte": value}` 区间对象或 `[min, max]` 二元数组；`topics` 结构为 `{"logic":"and|or","dimensions":{...}}`，当前对外开放 `primary_topic`、`primary_topic_domain`，其中 `primary_topic_domain` 可取 `Physical Sciences`、`Social Sciences`、`Health Sciences`、`Life Sciences`。

**出参**：`hits[]` 排序数组。常用字段：`chunk_id`（片段 ID，稳定）、`chunk`（片段正文）、`doc_id`（用于 `/content` 续读）、`title`、`abstract`、`score`（越大越相关）、`source_type ∈ {pdf, web}`、`offset`（片段在原文中的字符偏移）、`page_no` / `pdf_page`。过滤相关元数据可能直接挂在 hit 顶层，如 `lang`、`metadata_type`、`author`、`publication_venue_name_unified`、`publication_venue_type`、`publication_published_date`、`publication_published_year`、`citation_count`、`influential_citation_count`、`primary_topic`、`primary_topic_domain`；字段会按账号权限裁剪，调用方需容忍缺失。

**错误码**：`400 INVALID_REQUEST` / `401 UNAUTHORIZED` / `429 RATE_LIMITED` / `500 INTERNAL_ERROR` / `502|503 UPSTREAM_UNAVAILABLE`。

**限制 / 重试**：默认 30 次/分钟；建议重试 502/503/504，**不要**重试 400/401；429 等待窗口恢复。

**给 LLM 的提示**：把 `chunk` 当作可引用文本时，**必须**同时写出 `doc_id` 或 `doi` 作为来源标记；如果用户继续追问"这段话的全文"，下一步应改用 `/content` 而不是再次调用 `/agentic-search`。

```bash
curl -X POST https://api.sciverse.space/agentic-search \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"query":"graphene battery cycle stability","top_k":10,"sub_queries":2,"filters":{"lang":"en","publication_published_year":{"gte":2020},"topics":{"logic":"and","dimensions":{"primary_topic_domain":"Physical Sciences"}}}}'
```

### 6.2 `GET /content` —— 全文按字符切片读取

**用途**：根据 `agentic-search` / `meta-search` 返回的 `doc_id`，按字符切片读取原始全文。适用于详情页、引用核验、增量加载。

**入参（URL query）**

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `doc_id` | string | 是 | — | 文献 ID |
| `offset` | integer | 否 | — | 字符偏移（Unicode 码点），未传时返回全文 |
| `limit` | integer | 否 | 700 | 单次最大字符数（Unicode 码点），仅在传入 `offset` 时生效 |

**出参**：`text`（UTF-8 字符串，可能为 Markdown）、`bytes_returned`（实际返回字符数）、`next_offset`（下一段偏移）、`more`（是否仍有续读）。

**错误码**：`400 INVALID_REQUEST`（`doc_id` 缺失或非法）、`401 UNAUTHORIZED`、`404 NOT_FOUND`、`405 METHOD_NOT_ALLOWED`、`429 RATE_LIMITED`、`502|503 UPSTREAM_UNAVAILABLE`。

**分页协议**：①调用 `?doc_id=...&offset=0&limit=700`；②读取 `text`；③若 `more=true`，把上一次 `next_offset` 作为新的 `offset` 再次调用；④`more=false` 时停止。该协议保证不会因为切到 Unicode 码点中间而乱码。

**给 LLM 的提示**：`/content` 返回的是**原文**，不要把它当作答案直接回给用户；引用时给出 `doc_id` 与切片 `offset` 范围以方便人工复核。

### 6.3 `POST /meta-search` —— 字段化元数据检索

**用途**：按学科、年份、期刊、DOI、语言、开放获取状态等结构化字段过滤与排序。当用户的问题主要是"筛选 / 排序 / 翻页"，优先选这个端点；当主要是"语义相似论文清单"，可同时传 `query`。

**入参（JSON body）**

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `query` | string | 否 | — | 全文模糊词；与 `sort` 互斥（带 `query` 时按相关性排序） |
| `filters` | `FieldFilter[]` | 否 | `[]` | 字段过滤数组 |
| `sort` | `SortField[]` | 否 | `[]` | 排序数组；可排序字段以 `meta-catalog` 返回为准 |
| `fields` | `string[]` | 否 | `[]` | 投影字段；空集走默认；`doc_id` 始终返回 |
| `page` | integer | 否 | 1 | 页码；最小 1 |
| `page_size` | integer | 否 | 25 | 页大小；1–200 |
| `cursor` | string | 否 | — | 深翻页游标；与 `page>1` 互斥 |

`FieldFilter = { field: string, operator?: FilterOperator, value: scalar | array }`，`operator` 默认 `FILTER_OP_EQ`，全集为 `FILTER_OP_EQ / NE / GT / GTE / LT / LTE / IN / NIN / CONTAINS`。

`SortField = { field: string, order?: SORT_ORDER_DESC | SORT_ORDER_ASC }`，可排序字段仅 `publication_published_year` / `publication_published_date` / `reference_count` / `citation_count` / `influential_citation_count` / `fwci`。

**出参**：`results`（命中元数据数组，`doc_id` 必返）、`total_count`、`page`、`page_size`、`total_pages`、`search_time_ms`、`next_cursor`。

**错误码**：`400 INVALID_REQUEST / INVALID_ARGUMENT`、`401 UNAUTHORIZED / UNAUTHENTICATED`、`403 PERMISSION_DENIED`（字段无权）、`429 RATE_LIMITED`、`500/502/503/504 UPSTREAM_UNAVAILABLE`。

**限制 / 翻页**：`page * page_size ≤ 10000` 走 `page` 翻页；超过时**必须**改用 `cursor`；`cursor` 与 `page>1` 互斥。

**关键约束（避免幻觉）**：所有 `filters[*].field` / `sort[*].field` / `fields[*]` **必须**与 `meta-catalog` 返回的字段名完全一致，禁止自行组合或重命名。如果用户描述的字段在 schema 中不存在，**回复字段不支持**，不要伪造。

**典型构造模式**

```jsonc
// 2023 年以来的开放获取英文论文，按年降序，仅返回标题/DOI/年份/期刊
{
  "filters": [
    { "field": "language", "value": "en" },
    { "field": "publication_published_year", "operator": "FILTER_OP_GTE", "value": 2023 },
    { "field": "access_oa_status", "operator": "FILTER_OP_NE, "value": "closed" }
  ],
  "sort": [{ "field": "publication_published_year", "order": "SORT_ORDER_DESC" }],
  "fields": ["title", "doi", "publication_published_year", "publication_venue_name_unified"],
  "page": 1, "page_size": 25
}
```

### 6.4 `GET /meta-catalog` —— 字段与算子自描述

**用途**：在运行期发现 meta-search 当前可用字段、各字段的能力（是否可 filter / sort / facet）、合法算子集合、枚举字段的样本值。**模型在构造 meta-search 之前应先调用一次本接口**，并将结果在会话内缓存。

**入参（URL query）**

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `include_sample_values` | bool | 否 | false | 是否返回枚举字段的样本值（24h 缓存） |

**出参**：`fields[*]`（`name / type / filterable / sortable / searchable / default_returned / description / sample_values / operators`）、`default_fields`、`filter_operators`（全局算子集合）。

**错误码**：`401 UNAUTHORIZED`、`429 RATE_LIMITED`、`502/503/504 UPSTREAM_UNAVAILABLE`。

### 6.5 `POST /meta-paper-relations` —— 论文引用关系分页

**用途**：按 `unique_id` 分页返回某篇论文的引用、被引或相关工作完整列表。`citations` / `references` / `related_works` 是无界数组，高被引论文可能有数千条关系；`meta-search` 只内联截断少量条目，要翻完整列表用本接口。

**入参（JSON body）**

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `unique_id` | string | 是 | — | 目标论文的元数据全局唯一 ID，来自 `/meta-search` 或 `/agentic-search`；不要传 `doc_id` |
| `relation` | string | 是 | — | `CITATIONS`（被引：谁引用了目标论文）/ `REFERENCES`（参考文献：目标论文引用了谁）/ `RELATED_WORKS`（相关工作） |
| `page` | integer | 否 | 1 | 页码；最小 1 |
| `page_size` | integer | 否 | 25 | 页大小；1–200 |

**出参**：`items`（关系条目数组，常见字段 `id` / `id_type` / `title`）、`total_count`、`page`、`page_size`、`total_pages`，并带统一成功信封 `code` / `message` / `biz_code`。

**错误码**：`400 INVALID_ARGUMENT`（`unique_id` 为空或 `relation` 非法）、`401 UNAUTHORIZED`、`403 PERMISSION_DENIED`（无关系字段权限）、`404 NOT_FOUND`、`429 RATE_LIMITED`、`502/503/504 UPSTREAM_UNAVAILABLE`。

**给 LLM 的提示**：当用户问"这篇论文引用了哪些文献""哪些论文引用了它""相关工作有哪些"时，先用 `/meta-search` 定位论文并取 `unique_id`，再调用本接口分页。不要用 `/content` 或 `/resource` 解决引用图谱问题。

```bash
curl -X POST https://api.sciverse.space/meta-paper-relations \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"unique_id":"paper:10.1038/s41586-021-03819-2","relation":"CITATIONS","page":1,"page_size":25}'
```

### 6.6 `GET /resource` —— 图表 / 二进制资源拉取

**用途**：根据 `chunk` 或 Markdown 中给出的资源相对路径下载图、表、PDF。

**入参（URL query）**

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `file_name` | string | 是 | 资源相对路径；**不得包含 `\`、`..`，不得以 `/` 开头** |

**出参**：二进制流；常见 Content-Type：`image/jpeg`、`image/png`、`application/pdf`；响应头含 `Content-Disposition` 与 `X-Request-ID`。

**错误码**：`400 INVALID_REQUEST`（路径非法）、`401 UNAUTHORIZED`、`404 NOT_FOUND`、`429 RATE_LIMITED`、`500/502/503 UPSTREAM_UNAVAILABLE`。

---

## 7. Agent 工具（Sciverse-Agent-Tools）

`opendatalab/Sciverse-Agent-Tools` 仓库当前把常用 HTTPS 端点封装为 5 个标准化 Agent 工具，并提供 Python / TypeScript SDK、MCP server、Claude Skill、ClawHub Skill 五种装载路径。`/meta-paper-relations` 是公开 REST 端点；若当前工具包未暴露对应工具，应直接按 REST 协议调用。模型应优先通过工具名调用已封装能力，除非环境不支持工具调用或目标端点尚未封装。

| Tool | 对应端点 | 用途 |
|---|---|---|
| `list_catalog` | `/meta-catalog` | 发现可用字段、算子、枚举样本 |
| `search_papers` | `/meta-search` | 结构化检索（作者 / 年份 / 期刊 / 学科） |
| `semantic_search` | `/agentic-search` | 自然语言语义检索（RAG 命中片段） |
| `read_content` | `/content` | 按字符切片读取原文（扩展 RAG 上下文） |
| `get_resource` | `/resource` | 抓取 `read_content` Markdown 中引用的图表二进制 |

**装载路径**（推荐顺序）

1. `npx skills add https://sciverse.space`，随后 `export SCIVERSE_API_TOKEN=sv-...`。这是 Codex / Claude Code / Cursor / Codex CLI / Windsurf 等支持 `npx skills` 的 Agent 客户端推荐方式。
2. `clawhub install sciverse`（OpenClaw 兼容客户端）。
3. `claude /plugin marketplace add https://github.com/opendatalab/Sciverse-Agent-Tools && claude /plugin install sciverse`，并 `npm install -g sciverse-mcp-server`。
4. 手动 Skill：`git clone` 后将 `skill-claude-code/` 拷至 `~/.claude/skills/sciverse/`，同样需要 `sciverse-mcp-server` 与 Token。
5. SDK：`pip install sciverse` 或 `npm install sciverse`，已封装工具的 schema 与 ANTHROPIC_TOOLS / OPENAI_TOOLS 保持一致。

---

## 8. 常见错误与处置

| 状态码 | 典型 `code` | 含义 | 处置 |
|---|---|---|---|
| 400 | `INVALID_REQUEST` / `INVALID_ARGUMENT` | 字段名 / 算子 / 取值非法；`query` 与 `sort` 同传；`cursor` 与 `page>1` 同传 | 调用 `/meta-catalog` 重核字段；`query` 与 `sort` 二选一 |
| 401 | `UNAUTHORIZED` / `UNAUTHENTICATED` / `TOKEN_INVALID` | Token 缺失 / 失效 | 不要重试；提示用户重新创建 Token |
| 403 | `PERMISSION_DENIED` | 字段或资源无权 | 移除字段或换具备权限的 Token |
| 404 | `NOT_FOUND` | `doc_id` / 资源路径不存在 | 不要重试；改用 `/meta-search` 重新定位 |
| 405 | `METHOD_NOT_ALLOWED` | 请求方法错 | 改用接口指定的方法 |
| 429 | `RATE_LIMITED` | 命中默认 30/min 或 Token 配额 | 退避重试；缩小 `top_k` / `page_size` |
| 500/502/503/504 | `INTERNAL_ERROR` / `UPSTREAM_UNAVAILABLE` / `UPSTREAM_TIMEOUT` | 网关或上游异常 | 指数退避重试，建议至多 3 次 |

---

## 9. 端到端工作流（给 Agent 的 4 个范式）

**A. 开放问答 RAG**：①`semantic_search(query)` → ②取若干 `chunk_id` / `doc_id` 写进答案上下文 → ③对关键引用调用 `read_content(doc_id, offset, limit=700)` 续读 → ④回答时给出 `doc_id` / `doi` 与片段位置。

**B. 字段化筛选 + 排序**：①若不确定字段，先 `list_catalog(include_sample_values=true)` → ②`search_papers({filters, sort, fields, page_size})` → ③需要详情时再走 `read_content`。

**C. 已知 DOI / `doc_id` 取证**：①`search_papers({filters:[{field:"doi", value:"..."}], page_size:1})` 拿元数据 → ②`read_content(doc_id, offset, limit)` 抽片段 → ③把元数据 + 片段拼成"权威引用"。

**D. 引用关系展开**：①`search_papers` 定位目标论文并取得 `unique_id` → ②`POST /meta-paper-relations` 按 `CITATIONS` / `REFERENCES` / `RELATED_WORKS` 分页 → ③必要时对返回条目再用 `search_papers` 或 `semantic_search` 深挖。

**E. 图表抽取**：①`semantic_search` 或 `search_papers` 拿到 `doc_id` → ②`read_content` 拿 Markdown → ③在 Markdown 里发现图表相对路径 → ④`get_resource(file_name=...)` 抓 PNG / PDF。

---

## 10. 写答时的硬约束（请严格遵守）

引用必须可回溯：每条直接引用都要给出 `doc_id` 或 `doi`，最好附加 `chunk_id`；不允许只给标题。语料范围内可答：如果 `agentic-search` 与 `meta-search` 都没有命中，请回复"在 Sciverse 中未检索到匹配资料"，不要靠模型先验补全；时间口径以 `publication_published_year` 为准；语言口径以 `lang` 字段为准。模型不要自行拼接 `/agentic-search` 的请求体里出现非文档化字段（例如 `source_types`、`request_id` 这些非公开字段）；正式对外参数为 `query` / `top_k` / `sub_queries` / `filters`。

---

## 附录 A · 最小可运行示例（Python）

```python
import os, requests
BASE = "https://api.sciverse.space"
H = {"Authorization": f"Bearer {os.environ['SCIVERSE_API_TOKEN']}",
     "Content-Type": "application/json"}

# 1) 自然语言检索
hits = requests.post(f"{BASE}/agentic-search", headers=H,
    json={"query": "graphene battery cycle stability", "top_k": 5}).json()["hits"]

# 2) 续读首条命中的原文
doc_id = hits[0]["doc_id"]
offset, more, buf = 0, True, []
while more:
    r = requests.get(f"{BASE}/content", headers=H,
        params={"doc_id": doc_id, "offset": offset, "limit": 700}).json()
    buf.append(r["text"]); offset, more = r["next_offset"], r["more"]
fulltext = "".join(buf)

# 3) 元数据补全
meta = requests.post(f"{BASE}/meta-search", headers=H, json={
    "filters":[{"field":"doc_id","operator":"FILTER_OP_EQ","value":doc_id}],
    "fields":["title","doi","publication_published_year","publication_venue_name_unified"]
}).json()["results"][0]

print(meta["title"], meta["doi"], len(fulltext))
```

## 附录 B · References

[1] Sciverse 开发者文档 — 字段表与错误码定义。
[2] `opendatalab/Sciverse-Agent-Tools` README — 5 工具 schema 与装载路径。
[3] Sciverse Token 管理页：<https://sciverse.opendatalab.com/tokens>。
[4] ClawHub Skill 页：<https://clawhub.ai/sciverse/academic-retrieval>。