中医药方剂 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 用于访问完整功能（如症状推荐）。推荐通过环境变量安全配置：
- 访问网站 https://119.91.226.122 注册账号并生成 API Key
- 将 API Key 配置为环境变量：
export TCM_API_KEY=<your_key> - 技能将自动从环境变量读取，无需在对话中输入
无 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. 搜索方剂
curl -s "https://119.91.226.122/api/prescriptions/search?q=桂枝&page=1&limit=20"
参数说明：
q或keyword：搜索关键词（方剂名称、药物组成等）category：按分类筛选（如"解表剂"、"清热剂"）page：页码，默认 1limit或pageSize：每页条数，默认 20
2. 获取方剂详情
curl -s "https://119.91.226.122/api/prescriptions/PRESCRIPTION_ID"
返回方剂的完整信息：名称、别名、组成、功用、主治、方解、方歌、用法、禁忌、加减变化、来源等。
3. 获取方剂分类
curl -s "https://119.91.226.122/api/prescriptions/categories"
返回所有方剂分类列表（如解表剂、泻下剂、和解剂、清热剂等）。
4. 症状推荐方剂（需要 API Key）
系统同时对 indications（主治）和 description（功用）字段进行关键词匹配，按匹配症状数量排序返回。
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. 健康检查
curl -s "https://119.91.226.122/health"
执行流程
当用户触发此技能时，按以下流程执行：
Step 0：检查 API Key 状态
在执行任何查询之前，先检查环境变量中是否配置了 API Key：
- 检查环境变量
TCM_API_KEY是否已设置 - 如果已设置 → 在需要认证的请求中自动附加
- 如果未设置 → 提示用户配置环境变量，或使用无认证模式继续
重要：不要要求用户在对话中直接粘贴 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 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，无需在命令行参数中传递。
注意事项
- API 有速率限制（每分钟 100 次请求），避免短时间内大量调用
- 症状推荐接口需要有效的 API Key（通过环境变量
TCM_API_KEY配置） - 方剂 ID 为系统内部标识，可通过搜索接口获取
- 搜索支持中文方剂名、药物名等多种关键词，中文搜索时需进行 URL 编码
- 公开接口可返回完整方剂信息（组成、用法、适应症、禁忌、注意事项）
关于
- 技能名称：tcm-prescription-api
- 开发者：Phal Studio
- 客服邮箱：guest@phalstudio.tech