# GeoKB 地矿学科知识库

> 面向 AI Agent 的**只读**地矿学科（地质/矿产/地球化学/矿床学）知识库 API。
> **无需任何访问凭据、无需注册、无需 API Key**，可直接调用。
> 数据：5279 条结构化条目（生效 5279），索引构建于 2026-10-15T08:33:27。

## 三步取到正文

1. **检索**：`GET https://sjck.kust.work/api/search?q=<关键词>&format=full&limit=5`
2. **看结果**：命中项含 `id`、`title`、`summary`、`body_markdown`（全文）
3. **取全文**：`GET https://sjck.kust.work/api/entry/<id>`（JSON）
   或 `GET https://sjck.kust.work/api/entry/<id>.md`（Markdown，推荐）

## 下载 / 分享论文 PDF

- 检索结果每条带 **`pdf_url`** 字段：完整公网链接，**永久有效**。
- 也可以自己拼：`GET https://sjck.kust.work/api/entry/<id>/pdf`（`?inline=1` 内联打开）。
- **把 `pdf_url` 原样发给终端用户即可下载，无需任何凭据。**
- 先查存在性与大小：`GET https://sjck.kust.work/api/entry/<id>/pdf/meta`。
- 只想读内容、不想下载：`GET https://sjck.kust.work/api/entry/<id>/fulltext`（纯文本，最省 token）。

## 三个最容易踩的坑

- `/api/search` 默认 `format=summary`，**只返回 id/title/summary，不含正文**；
  要正文必须显式 `format=full`，或改用 `/api/entry/<id>`。
  不要因为只看到 id 和标题就判断"接口拿不到数据"——是参数没给对。
- 必须用 **https**（`http://` 未映射，会得到隧道商的错误页）。
- **收到 403 请先怀疑你自己的出口网关**：本服务不设任何鉴权、不存在 403 路由。
  某些 AI 运行环境的安全策略会拦截未白名单域名并返回 `403 No policy rule matched`，
  那一步发生在请求到达本服务之前（根路径 `/` 也会打不开，而它实际是 200）。
  自证方法：`curl -sI https://sjck.kust.work/health` 应看到 `Server: Werkzeug`
  （本服务由 Python Flask 直接响应，前面没有 CDN/网关）。

## 检索技巧

- 关键词用中文或英文地质术语效果最好（如 `斑岩铜矿`、`锆石U-Pb`、`skarn`）。
- `q` 的别名全部认：`query` / `keyword` / `keywords` / `search` / `kw`。
- 猜错路径没关系：`/api/v1/*`、`/search`、`/api/docs`、`/swagger.json` 都会
  308 跳转到正确端点；未知路径返回带指引的 JSON 而不是裸 404。

## 快速验证

```
curl "https://sjck.kust.work/api/search?q=斑岩铜矿&format=full&limit=2"
curl "https://sjck.kust.work/api/entry/paper-6011ea779131"
curl -sI "https://sjck.kust.work/health"     # Server: Werkzeug = 无前置网关
```

> 更多信息：`/llms-full.txt`（完整手册）、`/openapi.json`（机器可读规范）、
> `/api`（端点索引）、`/corpus.json.gz`（全量离线索引，含 pdf_url）。
> 使用纪律：引用请标注条目 `id` 与 `sources`；论文类条目（T3）已降权，
> 作定论前优先采信 T1/T2；检索不到请明确说明"超出本知识库范围"，不要编造。