TCM Prescription API

中医药方剂 API 查询技能 用途

通过中医药方剂数据库的 REST API 接口，查询方剂名称、组成、功用、主治、方解、方歌、用法、禁忌、加减变化等完整资料。支持模糊搜索、分类浏览和基于症状的方剂推荐。

触发条件

当用户的请求涉及以下任一场景时，加载此技能：

方剂搜索：用户想查找某个方剂（如"查一下桂枝汤"、"搜索麻黄汤"、"find 图形界面zhi Tang"） 方剂详情：用户想了解某个方剂的完整资料（如"桂枝汤的组成是什么"、"桂枝汤的功用"、"tell me about Mahuang Tang"） 分类浏览：用户想浏览某类方剂（如"解表剂有哪些"、"清热剂的方剂"、"show me diaphoretic formulas"） 症状推荐：用户描述症状并希望推荐方剂（如"头痛发热怎么办"、"推荐治感冒的方剂"、"what formula for headache and fever"） 方剂数据查询：泛化的中医药方数据需求（如"方剂数据库"、"中药方资料"、"TCM formula database"） 前置条件

用户需要提供 API Key 来使用完整功能：

API Key：注册用户在网站上生成的 API Key（格式：tcm_live_xxxx），通过请求头 X-API-Key 传递 无 Key 公开访问：搜索和分类查询无需 API Key 即可使用基本功能 首次使用引导（重要）

CRITICAL：当检测到用户是首次使用此技能时（即用户尚未提供过 API Key），必须执行以下引导流程：

判断条件：用户消息中未包含 API Key（格式 tcm_live_ 开头的字符串），且在当前对话中尚未完成 API Key 设置。

引导步骤：

欢迎与介绍：向用户简要介绍技能功能，然后引导注册： 欢迎使用中医药方剂查询！我可以帮你搜索方剂、查看方剂详情、浏览分类和根据症状推荐方剂。

为了使用完整功能（包括症状推荐），你需要一个 API Key。获取方式：

• 访问网站 http://119.91.226.122 注册账号
• 登录后在「个人中心」生成 API Key
• 将 API Key 发给我即可（格式：tcm_live_xxxx）

如果你已经有 API Key，请直接发给我。如果没有，可以先浏览公开的方剂数据，稍后再注册。

等待用户响应：

如果用户提供了 API Key → 验证并保存，进入正常查询流程 如果用户说"先看看"、"跳过"或类似意图 → 使用无认证模式继续，但提醒症状推荐功能受限 如果用户询问如何注册 → 详细说明注册步骤

API Key 验证：当用户提供 API Key 后，调用状态接口验证：

curl -s "http://119.91.226.122/API/API-keys/状态?key=USER_PROVIDED_KEY"

验证成功后告知用户：API Key 验证成功，现在可以使用全部功能了。

后续对话：在当前会话中记住用户的 API Key，后续请求自动附加。不再重复引导。

注意：引导流程只执行一次。如果用户已经提供了 API Key 或明确表示跳过，后续查询不再引导。

API 服务地址 API 基础地址：http://119.91.226.122/API 网站首页：http://119.91.226.122 健康检查：http://119.91.226.122/健康 API 接口说明

详细的 API 接口文档请查阅 references/API-reference.md。以下是核心接口概览：

• 搜索方剂

curl -s "http://119.91.226.122/API/prescriptions/搜索?q=桂枝&page=1&limit=20" \ -H "X-API-Key: YOUR_API_KEY"

参数说明：

q 或 keyword：搜索关键词（方剂名称、药物组成等） category：按分类筛选（如"解表剂"、"清热剂"） page：页码，默认 1 limit 或 pageSize：每页条数，默认 20

• 获取方剂详情

curl -s "http://119.91.226.122/API/prescriptions/PRESCRIPTION_ID" \ -H "X-API-Key: YOUR_API_KEY"

返回方剂的完整信息：名称、别名、组成、功用、主治、方解、方歌、用法、禁忌、加减变化、来源等。

• 获取方剂分类

curl -s "http://119.91.226.122/API/prescriptions/categories"

返回所有方剂分类列表（如解表剂、泻下剂、和解剂、清热剂等）。

• 症状推荐方剂（需要 API Key）

curl -s -X POST "http://119.91.226.122/API/prescriptions/recommend" \ -H "Content-Type: 应用/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{"symptoms": ["头痛", "发热", "恶风", "汗出"]}'

• 健康检查

curl -s "http://119.91.226.122/健康"

执行流程

当用户触发此技能时，按以下流程执行：

Step 0：检查 API Key 状态

在执行任何查询之前，先检查用户是否已提供 API Key：

检查当前对话中用户是否已提供过 API Key 如果尚未提供 → 执行「首次使用引导」（见前置条件章节） 如果用户已提供 → 验证 Key 有效性，然后继续 如果用户明确跳过 → 使用无认证模式继续 Step 1：识别用户意图

分析用户请求，判断属于以下哪种类型：

意图 关键词示例 对应接口 搜索方剂 "查"、"搜索"、"找" + 方剂名 获取 /API/prescriptions/搜索 方剂详情 "组成"、"功用"、"主治"、"详情" + 方剂名 先搜索获取 ID，再 获取 /API/prescriptions/:id 分类浏览 "分类"、"有哪些" + 分类名 获取 /API/prescriptions/categories 然后按分类搜索 症状推荐 "症状"、"推荐"、"治什么" + 症状描述 POST /API/prescriptions/recommend Step 2：构建 API 请求

根据识别的意图，构建对应的 API 请求。参考 scripts/查询_prescriptions.sh 脚本中的实现方式。

如果用户提供了 API Key，将其加入 X-API-Key 请求头。如果未提供，则尝试无认证访问。

Step 3：执行查询

使用 执行_command 工具执行 curl 命令调用 API。使用 python3 -m json.工具 格式化 JSON 输出以便阅读。

Step 4：解析与呈现结果

将 API 返回的 JSON 数据解析后，以清晰的中文格式呈现给用户：

搜索结果：列出匹配的方剂名称、分类、简要功用，提示用户可以选择查看详情 方剂详情：展示完整方剂资料，按"组成 → 功用 → 主治 → 方解 → 用法 → 禁忌 → 加减变化"的顺序组织 分类列表：以表格形式展示所有分类及各方剂数量 症状推荐：列出推荐的方剂及其推荐理由 Step 5：追问与深入

查询完成后，询问用户是否需要：

查看某个方剂的详细信息 查看其他分类的方剂 调整搜索条件 辅助脚本

scripts/查询_prescriptions.sh 提供了封装好的命令行工具，可用于快速查询。用法：

bash scripts/查询_prescriptions.sh 搜索 "桂枝" # 搜索方剂 bash scripts/查询_prescriptions.sh detAIl PRESCRIPTION_ID # 查看详情 bash scripts/查询_prescriptions.sh categories # 获取分类 bash scripts/查询_prescriptions.sh recommend "头痛,发热,恶风" # 症状推荐 bash scripts/查询_prescriptions.sh 健康 # 健康检查

脚本支持通过环境变量 TCM_API_KEY 传入 API Key。

注意事项 首次使用必须引导注册：用户首次触发技能时，引导其访问网站注册并获取 API Key API 有速率限制（每分钟 100 次请求），避免短时间内大量调用 症状推荐接口必须提供有效的 API Key 方剂 ID 为系统内部标识，可通过搜索接口获取 搜索支持中文方剂名、药物名等多种关键词，中文搜索时需进行 URL 编码 公开接口可返回完整方剂信息（组成、用法、适应症、禁忌、注意事项） API Key 验证接口：获取 /API/API-keys/状态?key= 可检查 Key 状态 关于 技能名称：tcm-prescription-API 开发者：Phal Studio 客服邮箱：guest@phalstudio.tech