Chemdb Search

---
name: chemdb_search
description: 用于检索化学物质详细信息的技能。当用户希望检索化学物质详细信息、查看化学物质详细信息、检索化学物质基础数据库等情况时触发。该技能通过输入化学分子式（必要参数）以及分页（可选参数）、分页大小（可选参数）调用外部化学物质基础数据库搜索服务，并按字段含义格式化展示查询结果以及SVG化学分子式结构。
compatibility:
  - python
  - requests

name_zh: 用于检索化学物质详细信息的技能算子
input_params:
  - name: text
    type: string
    required: true
    description: 化学分子式（如 C6H6、C12H12）

  - name: page
    type: int
    required: false
    default: 1
    description: 分页页码（从1开始）

  - name: page_size
    type: int
    required: false
    default: 10
    description: 每页返回的化学物质数量

output_params:
  - name: search_result
    type: json_file
    description: 化学物质详细信息JSON，包含化学物质列表、分子结构（SVG）等
tag: 科学计算
publisher: COMMUNITY
---

# chemdb_search 技能

## 功能说明

该技能用于调用化学物质基础数据库搜索服务，根据用户输入的化学分子式检索并返回对应的化学物质详细信息，展示时按json字段含义格式化展示并将`image`字段的 SVG 数据可直接渲染为分子结构示意图，便于直观查看物质结构。

## 触发条件

当用户希望：
- 检索化学物质详细信息
- 查看化学物质详细信息
- 检索化学物质基础数据库
- 查询特定化学分子式的物质信息
- 获取化学物质的详细属性

## 调用服务说明

### 化学物质基础数据库搜索服务

该接口来自 **化学物质基础数据库（[chemdb.csdb.cn](https://chemdb.csdb.cn)）**，核心功能是**根据输入的化学分子式（如 C6H6、C12H12），检索并返回对应的化学物质详细信息**，支持分页查询。

### 接口核心信息

#### 1. 基础配置

- 服务名称：化学物质分子式检索服务
- 接口地址：`http://www.chemdb.csdb.cn/chemdb_backend/search/text_search`
- 请求方式：GET
- 响应状态：成功返回 200，message 为 "success"

#### 2. 请求参数（URL 参数）

| 参数名    | 说明                         | 示例值 | 必填 |
| :-------- | :--------------------------- | :----- | :--- |
| text      | 检索关键词（需为化学分子式） | C6H6   | 是   |
| page      | 分页页码（从 1 开始）        | 1      | 否   |
| page_size | 每页返回的化学物质数量       | 10     | 否   |

#### 3. 响应数据结构（核心字段说明）

响应为 JSON 格式，核心包含`data`（化学物质列表）和分页相关字段：

| 一级字段 | 说明                           |
| :------- | :----------------------------- |
| data     | 化学物质详细信息列表（数组）   |
| page_all | 总页数                         |
| total    | 匹配的化学物质总数量           |
| code     | 响应状态码（200 = 成功）       |
| message  | 响应信息（成功返回 "success"） |

##### `data`数组中单个化学物质的关键字段

| 字段名     | 说明                                 | 示例值                                 |
| :--------- | :----------------------------------- | :------------------------------------- |
| Formula    | 化学分子式（与检索关键词一致）       | C6H6                                   |
| MolWeight  | 分子量                               | 78.11184                               |
| Alias_en   | 英文别名                             | 1,4-Hexadiyne                          |
| CAS        | CAS 编号（化学物质唯一标识）         | 10420-91-4                             |
| SMILES     | 简化分子线性输入规范（分子结构编码） | C#CCC#CC                               |
| IUPAC_Name | IUPAC 标准命名                       | hexa-1,4-diyne                         |
| InChI      | 国际化学标识符（分子结构唯一标识）   | InChI=1S/C6H6/c1-3-5-6-4-2/h1H,5H2,2H3 |
| InChiKey   | InChI 的哈希值（便于检索）           | NJXXWBJAOFKNIR-UHFFFAOYSA-N            |
| image      | 分子结构示意图（SVG 格式）           | 包含 SVG 标签的矢量图数据              |

## 使用方法

1. 调用 `scripts/chemdb_search.py` 脚本
2. 提供必要参数 `text`（化学分子式）
3. 可选择提供参数 `page`（分页页码）和 `page_size`（每页大小）
4. 脚本将返回接口的完整 JSON 响应

## 输出格式

按查询结果json的每一条字段的含义属性格式化展示查询结果，并将`image`字段的 SVG 数据可直接渲染为分子结构示意图，便于直观查看物质结构。

## 补充说明

1. 检索范围：仅支持**化学分子式**检索（如 C6H6、C12H12），输入其他类型关键词可能无匹配结果；
2. 数据完整性：返回的化学物质信息涵盖分子结构、命名、标识、分子量等核心属性，满足化学研究、物质识别等场景需求；
3. 分页机制：通过`page`和`page_size`控制返回数量，示例中检索 C6H6 共匹配 1244 条结果，分 125 页展示；
4. 分子结构可视化：`image`字段的 SVG 数据可直接渲染为分子结构示意图，便于直观查看物质结构。

## 示例

### 示例 1：检索 C6H6 的化学物质信息

```bash
python scripts/chemdb_search.py --text C6H6
```

### 示例 2：检索 C12H12 的化学物质信息，指定分页参数

```bash
python scripts/chemdb_search.py --text C12H12 --page 2 --page_size 20
```

## 错误处理

- 如果未提供必要参数 `text`，脚本将提示错误并退出
- 如果接口调用失败，脚本将返回错误信息
- 如果网络连接失败，脚本将提示网络错误