back
loading skill details...
中医药方剂API查询技能。通过HTTP API查询中医药方剂数据库中的方剂资料。支持方剂搜索、方剂详情查看、分类浏览、症状推荐等功能。This skill should be used when the user mentions: 查方剂、搜索方剂、方剂详情、中药方、方剂分类、症状推荐方剂、中医药方查询、方剂数...
---
name: tcm-prescription-api
version: 1.0.1
license: MIT-0
description: "中医药方剂API查询技能。通过HTTP API查询中医药方剂数据库中的方剂资料。支持方剂搜索、方剂详情查看、分类浏览、症状推荐等功能。This skill should be used when the user mentions: 查方剂、搜索方剂、方剂详情、中药方、方剂分类、症状推荐方剂、中医药方查询、方剂数据、prescription search、herb formula、TCM prescription、查询中药、方剂API、方剂数据库。"
metadata:
openclaw:
emoji: "\U0001F9E8"
category: api
clawdbot:
emoji: "\U0001F9E8"
requires:
bins: ["curl", "python3"]
envs: ["TCM_API_KEY"]
install: []
---
# 中医药方剂 API 查询技能
## 用途
通过中医药方剂数据库的 REST API 接口,查询方剂名称、组成、功用、主治、方解、方歌、用法、禁忌、加减变化等完整资料。支持模糊搜索、分类浏览和基于症状的方剂推荐。
## 触发条件
当用户的请求涉及以下任一场景时,加载此技能:
- **方剂搜索**:用户想查找某个方剂(如"查一下桂枝汤"、"搜索麻黄汤"、"find Guizhi Tang")
- **方剂详情**:用户想了解某个方剂的完整资料(如"桂枝汤的组成是什么"、"桂枝汤的功用"、"tell me about Mahuang Tang")
- **分类浏览**:用户想浏览某类方剂(如"解表剂有哪些"、"清热剂的方剂"、"show me diaphoretic formulas")
- **症状推荐**:用户描述症状并希望推荐方剂(如"头痛发热怎么办"、"推荐治感冒的方剂"、"what formula for headache and fever")
- **方剂数据查询**:泛化的中医药方数据需求(如"方剂数据库"、"中药方资料"、"TCM formula database")
## 前置条件
### API Key 配置(推荐通过环境变量)
API Key 用于访问完整功能(如症状推荐)。推荐通过环境变量安全配置:
1. 访问网站 https://119.91.226.122 注册账号并生成 API Key
2. 将 API Key 配置为环境变量:`export TCM_API_KEY=<your_key>`
3. 技能将自动从环境变量读取,无需在对话中输入
无 API Key 也可使用基本功能(搜索、分类浏览、方剂详情)。
## API 服务地址
- **API 基础地址**:`https://119.91.226.122/api`
- **网站首页**:`https://119.91.226.122`
- **健康检查**:`https://119.91.226.122/health`
## API 接口说明
详细的 API 接口文档请查阅 `references/api-reference.md`。以下是核心接口概览:
### 1. 搜索方剂
```bash
curl -s "https://119.91.226.122/api/prescriptions/search?q=桂枝&page=1&limit=20"
```
参数说明:
- `q` 或 `keyword`:搜索关键词(方剂名称、药物组成等)
- `category`:按分类筛选(如"解表剂"、"清热剂")
- `page`:页码,默认 1
- `limit` 或 `pageSize`:每页条数,默认 20
### 2. 获取方剂详情
```bash
curl -s "https://119.91.226.122/api/prescriptions/PRESCRIPTION_ID"
```
返回方剂的完整信息:名称、别名、组成、功用、主治、方解、方歌、用法、禁忌、加减变化、来源等。
### 3. 获取方剂分类
```bash
curl -s "https://119.91.226.122/api/prescriptions/categories"
```
返回所有方剂分类列表(如解表剂、泻下剂、和解剂、清热剂等)。
### 4. 症状推荐方剂(需要 API Key)
系统同时对 `indications`(主治)和 `description`(功用)字段进行关键词匹配,按匹配症状数量排序返回。
```bash
curl -s -X POST "https://119.91.226.122/api/prescriptions/recommend" \
-H "Content-Type: application/json" \
-H "X-API-Key: $TCM_API_KEY" \
-d '{"symptoms": ["头痛", "发热", "恶风", "汗出"]}'
```
返回的每条推荐结果包含 `matchScore`(匹配症状数),分数越高越相关。
### 5. 健康检查
```bash
curl -s "https://119.91.226.122/health"
```
## 执行流程
当用户触发此技能时,按以下流程执行:
### Step 0:检查 API Key 状态
在执行任何查询之前,先检查环境变量中是否配置了 API Key:
1. 检查环境变量 `TCM_API_KEY` 是否已设置
2. 如果已设置 → 在需要认证的请求中自动附加
3. 如果未设置 → 提示用户配置环境变量,或使用无认证模式继续
**重要**:不要要求用户在对话中直接粘贴 API Key。始终引导用户通过环境变量配置。
### Step 1:识别用户意图
分析用户请求,判断属于以下哪种类型:
| 意图 | 关键词示例 | 对应接口 |
|------|-----------|---------|
| 搜索方剂 | "查"、"搜索"、"找" + 方剂名 | `GET /api/prescriptions/search` |
| 方剂详情 | "组成"、"功用"、"主治"、"详情" + 方剂名 | 先搜索获取 ID,再 `GET /api/prescriptions/:id` |
| 分类浏览 | "分类"、"有哪些" + 分类名 | `GET /api/prescriptions/categories` 然后按分类搜索 |
| 症状推荐 | "症状"、"推荐"、"治什么" + 症状描述 | `POST /api/prescriptions/recommend` |
### Step 2:构建 API 请求
根据识别的意图,构建对应的 API 请求。参考 `scripts/query_prescriptions.sh` 脚本中的实现方式。
如果环境变量 `TCM_API_KEY` 已设置,将其加入 `X-API-Key` 请求头。如果未设置,则尝试无认证访问。
### Step 3:执行查询
使用 `execute_command` 工具执行 `curl` 命令调用 API。使用 `python3 -m json.tool` 格式化 JSON 输出以便阅读。
### Step 4:解析与呈现结果
将 API 返回的 JSON 数据解析后,以清晰的中文格式呈现给用户:
- **搜索结果**:列出匹配的方剂名称、分类、简要功用,提示用户可以选择查看详情
- **方剂详情**:展示完整方剂资料,按"组成 → 功用 → 主治 → 方解 → 用法 → 禁忌 → 加减变化"的顺序组织
- **分类列表**:以表格形式展示所有分类及各方剂数量
- **症状推荐**:列出推荐的方剂及其推荐理由
### Step 5:追问与深入
查询完成后,询问用户是否需要:
- 查看某个方剂的详细信息
- 查看其他分类的方剂
- 调整搜索条件
## 辅助脚本
`scripts/query_prescriptions.sh` 提供了封装好的命令行工具,可用于快速查询。用法:
```bash
bash scripts/query_prescriptions.sh search "桂枝" # 搜索方剂
bash scripts/query_prescriptions.sh detail PRESCRIPTION_ID # 查看详情
bash scripts/query_prescriptions.sh categories # 获取分类
bash scripts/query_prescriptions.sh recommend "头痛,发热,恶风" # 症状推荐
bash scripts/query_prescriptions.sh health # 健康检查
```
脚本通过环境变量 `TCM_API_KEY` 读取 API Key,无需在命令行参数中传递。
## 注意事项
1. API 有速率限制(每分钟 100 次请求),避免短时间内大量调用
2. 症状推荐接口需要有效的 API Key(通过环境变量 `TCM_API_KEY` 配置)
3. 方剂 ID 为系统内部标识,可通过搜索接口获取
4. 搜索支持中文方剂名、药物名等多种关键词,中文搜索时需进行 URL 编码
5. 公开接口可返回完整方剂信息(组成、用法、适应症、禁忌、注意事项)
## 关于
- **技能名称**:tcm-prescription-api
- **开发者**:Phal Studio
- **客服邮箱**:guest@phalstudio.tech
don't have the plugin yet? install it then click "run inline in claude" again.