---
name: xrd-cif
description: 粉末 XRD 谱图物相检索与 CIF 晶体结构查询。用户提供 XRD 谱（XY 两列数据、峰位列表）或 2θ 峰位时，调用 XRD-CIF API 检索匹配的晶体结构，返回物相判定、化学式、空间群、匹配分数与峰位对照报告。适用于物相分析、未知峰归属、结构相似度检索。
---

# XRD-CIF 检索 Skill

粉末 XRD 谱图 ↔ CIF 结构检索服务。API 基址：`https://www.xrdcif.com`

## 鉴权（首次使用必须先完成）

1. 让用户在 https://www.xrdcif.com 注册账户并完成邮箱确认
2. 「账户与额度」页 → Skill Token → 生成 Token（**明文只显示一次**，让用户保存好）
3. 之后所有请求带请求头：`X-API-Key: <token>`

## 计费规则

- 每次检索调用扣 1 次解析额度；每账户每日有免费额度（默认 30 次，UTC 0 点重置）
- 每个计费响应都带 `billing` 字段：`{request_id, action, credits, source, balance_after}`——据此向用户播报本次扣费与余额
- HTTP 402 = 额度用尽：引导用户到 `https://www.xrdcif.com/pricing` **自助领取扩容额度（每日一次，免费）** 或自愿捐助
- 接口执行失败会自动全额退额（`billing.balance_after` 已回冲），无需人工对账
- 查询余额（不扣费）：`GET /api/v1/quota`

## 核心接口：物相检索

`POST /api/v1/search`

```json
{"pattern": {"kind": "...", ...}, "k": 5, "verify_top": 10, "composition": "NaCl"}
```

`pattern` 支持四种输入：

| kind | 字段 | 说明 |
|---|---|---|
| `peaks` | `peaks: [[2θ, 相对强度], ...]` 或 `text: "27.36 100\n31.7 55"` | **推荐**。只有峰位列表时用 `peaks: [[27.36, 100], ...]`（强度可估 100） |
| `xy` | `text: "2θ 强度\n..."` 两列数字，`#` 开头为注释行 | 完整连续谱（diffractogram 导出） |
| `grid` | `tth: [...]`, `intensity: [...]` | 等长数组、至少 10 点 |
| `simulate` | `structure_id` | 对库内结构仿真谱（测试用） |

- 不确定时用 `peaks`：从谱图提取主要峰位（2θ° + 相对强度）最稳
- `composition`（化学式，如 `"CaCO3"`）可选，可显著改善排序
- `k`（1–20，默认 5）返回候选数；`verify_top` 复核深度默认 10

### 响应解读（直接播报给用户）

- `result.decision.status`：`ANSWER`（给出物相结论）/ `ABSTAIN`（证据不足，保留意见）
- `result.candidates[]`：每条含 `structure_id`、`formula`（化学式）、`space_group`（空间群）、`score`、
  `verdict`（support / shortlist / reject）、`verification`（理论峰 vs 观测峰对照）、`render`（**人读报告文本，可直接引用**）
- `result.pattern.meta.warning`：输入口径警告（欠采样、波长不一致等）——有就转告用户
- 响应里还有 `billing`（本次扣费）与 `quota`（余额），按计费规则播报

## 其他接口

- `POST /api/v1/reverse` — `{"structure_id": "NaCl-rocksalt", "k": 3}`：库内结构 → 相似结构
- `GET /api/v1/history/<id>` — 检索响应中的 `history_id` 对应的完整运行记录
- `GET /api/v1/account` — 账户、额度、Token 列表汇总
- `/api/v1/eval`、`/api/v1/workflow` 是内部基准测试接口，单次调用昂贵，**Skill 不要主动调用**

## 最小示例

```bash
curl -s https://www.xrdcif.com/api/v1/search \
  -H "X-API-Key: $XRD_API_KEY" -H "Content-Type: application/json" \
  -d '{"pattern":{"kind":"peaks","peaks":[[27.36,100],[31.7,55],[45.4,12],[53.8,9],[56.4,7],[66.2,6]]},"k":5}'
```

## 口径提醒

服务端 2θ 使用冻结口径（波长见响应 `meta.wavelength_A`）。用户的谱若用其他波长
（如 CuKα 加权 1.54184 Å）直接给峰位会系统性偏移；`xy`/`grid` 输入会被自动重采样到冻结口径，
`peaks` 输入则按峰形合成。波长明显不符时先提醒用户换算。
