医疗报告解读

Overview

此 Skill 通过调用 ADP 平台的医疗报告解读 API（LLMReportInterpretation），帮助用户理解医疗检验/检查报告。支持传入报告文件（PDF/图片）或报告文本内容，AI 会识别关键异常值、解析医学术语，并生成易于理解的结构化解读报告。

重要说明

1. 本 Skill 调用的是 ADP 平台的插件 API，不是腾讯云 API（lke.tencentcloudapi.com），因此认证方式与其他 ADP 知识库系列 Skill 不同
2. 认证方式为 Bearer Token，密钥通过 ADP 平台的密钥管理页面获取
3. 响应格式为 SSE 流式（text/event-stream），按 Sort 字段顺序增量返回内容片段

触发条件

当满足以下任一条件时，应激活此 Skill：

1. 用户明确要求：用户要求使用医疗报告解读 Skill（如"帮我解读报告"、"看看我的体检报告"、"分析一下检验单"等）
2. 用户传入医疗报告文件：用户上传了图片（JPG/PNG 等）或 PDF 格式的医疗相关报告（检验单、检查单、体检报告等）
3. 用户提供医疗报告在线 URL：用户提供了指向医疗报告文件的在线链接（如 https://xxx.com/report.pdf）
4. 用户粘贴医疗报告文本：用户直接粘贴了报告文本内容（如化验指标、检查结果等数据）
5. 用户仅描述医疗问题：用户描述了与医疗健康相关的问题（如"血红蛋白偏低是什么意思？"、"肝功能异常怎么办？"）

参数收集

激活 Skill 后，需收集以下参数用于 API 调用：

⚠️ 注意：ReportFileUrl 和 ReportContent 如果同时传入，API 将优先使用 ReportFileUrl。

⚠️ 重要：DialogueId 虽然在接口文档中标注为非必填，但实测漏传会导致调用失败。脚本已内置自动生成逻辑，Agent 无需手动处理。

首次激活流程

⚠️ 必须先检查，严禁直接引导用户配置密钥。 多数情况下密钥已存在，跳过检查直接提醒是错误行为。

密钥检查（强制执行，不可跳过）

首次激活时，Agent 必须先执行以下检查，静默完成，不输出任何提示给用户：

# 步骤 1: 检查当前 shell 环境变量
echo $ADP_API_KEY

# 步骤 2: 如果为空，检查 /etc/environment 文件
grep "ADP_API_KEY" /etc/environment 2>/dev/null

检查结果分支：

• ✅ 找到密钥 → 流程结束，直接进入正常使用流程。 不输出任何关于密钥的提示。
• ❌ 未找到密钥 → 才进入下方「密钥获取流程」。

💡 脚本已内置 fallback：脚本会自动依次查找 os.environ → /etc/environment → ~/.env → .env，即使当前 shell 未加载变量，脚本也能找到密钥。但 Agent 在执行脚本前仍建议先 source /etc/environment，确保后续命令行操作也能使用该变量。

密钥获取流程（仅在上方检查未找到密钥时执行）

🚫 再次确认：如果上方检查已找到密钥，禁止执行本节。

主流程

引导用户按以下步骤操作：

1. 访问 ADP 密钥管理页面
2. 点击「新建密钥」
3. 保存密钥，发送给 agent

⚠️ 注意：密钥最多只能创建 2 个。如果提示已达上限，需要先删除旧的密钥再新建。

⚠️ 权限提示（必须展示）：如果用户无法访问该页面，说明当前账号权限不够，请联系管理员开通权限。

兜底流程（主流程链接未正常跳转时）

如果上述链接没有正常跳转到密钥管理页面，引导用户：

1. 访问 ADP 控制台
2. 点击「产品体验」按钮
3. 使用主账号登录
4. 点击右上角头像 → 「企业管理」 → 「密钥管理」
5. 点击「新建密钥」

密钥存储（仅在用户提供新密钥后执行）

用户提供密钥后，优先写入 /etc/environment（全局生效），如果没有 sudo 权限则兜底写入项目 .env 文件。

主方案：写入 /etc/environment（推荐）

# 写入 /etc/environment（需要 sudo 权限，对所有用户和 shell 生效）
echo 'ADP_API_KEY=用户提供的密钥' | sudo tee -a /etc/environment > /dev/null

写入后，重新加载使当前会话生效：

source /etc/environment

兜底方案：写入 .env 文件（无 sudo 权限时）

如果用户没有 sudo 权限，写入项目根目录的 .env 文件：

echo 'ADP_API_KEY=用户提供的密钥' >> .env

⚠️ 变量名必须为 ADP_API_KEY，完全一致，不可更改，否则会影响 ADP 平台上的业务逻辑。

存储完成后，告知用户密钥已保存。

核心工作流

工作流决策树

用户请求解读医疗报告
│
├─ 检查 ADP_API_KEY → 未设置 → 执行首次激活流程
│
├─ 分析用户输入类型
│   ├─ 用户提供了本地文件路径 → 上传至ADP文件服务获取COS URL → 调用API(带URL)
│   ├─ 用户提供了在线文件URL → 直接调用API(带URL)
│   ├─ 用户粘贴了报告文本内容 → 调用API(带ReportContent)
│   └─ 用户只描述了问题(无文件) → 调用API(仅Message)
│
├─ 调用 API 获取流式响应
│
└─ 整合输出结果
    ├─ 拼接 Content 字段（按 Sort 顺序）
    ├─ 提取引用资料 (ReferResourceItems)
    ├─ 提取猜你想问 (GuessQuestions)
    ├─ 提取高亮关键词 (HighlightWords)
    └─ 生成结构化解读报告

步骤 1：处理用户输入

分析用户提供的内容，确定调用方式：

场景 A：用户提供本地文件

API 要求入参为公开可访问的 URL，本地文件无法直接使用。通过 ADP 文件上传接口将本地文件转换为 COS URL：

1. 使用 scripts/upload_file.py 将本地文件上传至 ADP 文件服务，获取 COS 链接
2. 根据文件扩展名确定 ReportFileType：PDF 文件为 1，图片文件为 2
3. 将返回的 COS URL 作为 ReportFileUrl 参数

# 上传本地文件获取 COS URL
COS_URL=$(python {SKILL_DIR}/scripts/upload_file.py "/path/to/local/report.pdf")

文件上传接口说明

• 地址：https://adp.cloud.tencent.com/plugin/api/v1/9ebc029f-5567-493f-b823-0ad978a9bab1/b511190e-ab93-46ba-bee7-d852d53a28a9
• 方法：POST
• 认证：Authorization: Bearer （复用同一个密钥）
• 请求体：

• 响应：

场景 B：用户提供在线 URL

直接使用 URL 作为 ReportFileUrl 参数，根据 URL 后缀判断 ReportFileType。

场景 C：用户粘贴报告文本

将文本作为 ReportContent 参数传入。

场景 D：用户仅描述问题

仅使用 Message 参数，进行医疗咨询问答。

步骤 2：调用 API

参考 scripts/call_api.py 中的完整代码模板。

Agent 执行时将 QUERY、FILE_URL、FILE_TYPE、REPORT_CONTENT 填入脚本对应位置即可运行。DIALOGUE_ID 无需手动填写，脚本为空时会自动生成 UUID。

ReportInterpretation 接口

• 地址：https://adp.cloud.tencent.com/plugin/api/v1/2a1ef5fb-9c71-4b0f-99f1-6318bd948088/4c394fa7-113f-4c93-8f24-e495cc6feddb
• 方法：POST
• 认证：Authorization: Bearer
• 请求体：

详细的 API 参数说明和响应格式，参考 references/api_reference.md。

步骤 3：处理流式响应

API 返回流式 SSE 响应，处理要点：

1. 拼接回答内容：按 Sort 字段顺序拼接所有 Data.Content 字段
2. 缓存引用资料：ReferResourceItems 仅在首包返回
3. 检测结束标识：IsFinish=true 时流结束，此时获取 GuessQuestions
4. 收集高亮词：HighlightWords 在流式过程中返回
5. 异常检测：
   • Code != 0 → 输出 Msg 中的错误信息
   • IsSensitive=true → 提示内容触发敏感词过滤
   • IsSupportFile=false → 提示报告类型不支持，建议更换格式

步骤 4：整合输出

将所有流式返回的信息整合为一个结构化的解读报告，格式如下：

## 📋 报告解读结果

[拼接后的完整 Content 内容]

---

### 📚 参考资料
[列出 ReferResourceItems 中的引用，包含标题和链接]

### 🔍 相关问题
[列出 GuessQuestions 中的建议问题，方便用户进一步咨询]

输出要点：

• 将多个流式返回的 Content 片段拼接为完整连贯的回答
• 如有引用资料，以清晰的列表格式展示
• 如有猜你想问，作为延伸建议提供给用户
• 如有高亮关键词，在回答中对相关医学术语进行标注说明
• 如果 Think 字段有内容，可以选择性地展示 AI 的思考过程

支持的报告类型

• 检验报告：血常规、尿常规、肝功能、肾功能、血脂、血糖、甲状腺功能等
• 检查报告：B超、CT、MRI、X光、心电图等
• 体检报告：综合体检报告单
• 文件格式：PDF (ReportFileType=1)、图片 (ReportFileType=2)，包括 JPG/JPEG/PNG/BMP/TIFF 等

注意事项

• API 返回的是 AI 辅助解读，不能替代专业医生诊断，应提醒用户如有健康问题请及时就医
• 密钥最多 2 个，管理地址: https://adp.cloud.tencent.com/adp?#/key-manage?spaceId=default_space
• Message 最多 1000 字符，超长时需截断
• ReportFileUrl 必须是公开可访问的 URL，内网/需登录的链接无法使用。本地文件需先通过 upload_file.py 上传至 ADP 文件服务获取 COS URL
• 如果 ReportFileUrl 和 ReportContent 同时传入，优先使用 ReportFileUrl
• 多份报告建议分次调用，每次传入一份报告以获得更准确的解读

常见问题

配额不足处理

当接口返回配额不足错误（如 Code=3000003、响应消息包含 quota exceeded 等）时，说明当前套餐的调用额度已用完。引导用户前往 ADP 购买页面 购买套餐或增购包后重试。

脚本已内置配额不足检测逻辑，当检测到配额错误时会自动输出带购买链接的提示信息。

未覆盖场景

如遇到本 Skill 未覆盖的问题，建议查阅 ADP 官方文档。

Resources

scripts/

• call_api.py：调用医疗报告解读 API 的 Python 脚本，内置 _load_api_key() 多路径密钥加载、参数校验、流式响应解析、配额不足检测
• upload_file.py：本地文件上传工具，通过 ADP 文件上传接口将本地文件转换为公开可访问的 COS URL，内置 _load_api_key() 密钥加载、Base64 编码、参数校验、配额不足检测
• call_api.sh：（旧版）调用医疗报告解读 API 的 Bash 脚本，保留用于兼容
• upload_file.sh：本地文件上传工具（Bash 版），通过 ADP 官方文件上传接口将本地文件转换为公开可访问的 COS URL。与 upload_file.py 功能一致，纯 Bash 实现，无第三方依赖，数据仅经 ADP/COS 传输

references/

• api_reference.md：完整的 API 参数说明、请求/响应格式、错误码文档