| name | pneumonia-ai-diagnosis |
| description | 调用肺炎AI辅助诊断模型API，支持提交胸部CT DICOM压缩包进行异步分析、查询分析结果、以及自动轮询等待结果完成。采用HMAC-SHA256签名鉴权。触发词：肺炎检测、肺炎AI、胸部CT分析、pneumonia、DICOM、肺炎查询。 |
| description_zh | 肺炎AI辅助诊断 |
| description_en | Pneumonia AI Diagnosis |
| disable | false |
| agent_created | true |
肺炎AI辅助诊断
肺炎医疗影像AI辅助诊断模型调用Skill。基于肺炎AI模型接口，支持异步提交胸部CT DICOM压缩包进行分析，查询/轮询获取肺炎检测结果。
特别说明：以下模型能力均仅限中国大陆地区科研用途售卖和使用，不得直接用于临床检测与诊疗等目的。
一、触发条件
- 用户需要提交胸部CT DICOM压缩包进行肺炎AI分析
- 用户需要查询已有的肺炎AI分析任务结果
- 用户需要自动轮询等待肺炎AI分析结果
- 用户提及"肺炎检测"、"肺炎AI"、"胸部CT分析"、"DICOM分析"等关键词
二、鉴权方式
2.1 签名算法
采用 HMAC-SHA256 签名算法，计算公式如下：
signature = HMAC-SHA256(token, appId + timestamp)
| 参数 | 说明 | 备注 |
|---|
appId | 合作方 ID | 由系统分配 |
token | 密钥 | 由系统分配，需妥善保管 |
timestamp | 时间戳 | 当前时间的秒级时间戳 |
signature | 签名 | 根据上述公式计算得出 |
2.2 请求头参数
| Header 字段 | 必填 | 说明 |
|---|
appId | 是 | 合作方 ID |
timestamp | 是 | 秒级时间戳，服务器允许一定误差 |
signature | 是 | 根据 2.1 计算出的签名 |
2.3 首次使用
用户首次使用时需提供 appId 和 token，如缺失则主动询问：
请提供以下参数以使用肺炎AI诊断接口：
1. appId（合作方ID）
2. token（密钥）
安全提示：token 不得出现在前端、日志或客户端代码中，仅在服务端参与签名计算。
三、接口说明
3.1 肺炎 AI 提交接口
- 接口路径：
https://pacs.qq.com/openapi/pneumoniaSubmit
- 请求方式：
POST
- Content-Type：
multipart/form-data
- 数据要求：胸部 CT 序列 DICOM 文件压缩包（ZIP 格式），最大 300MB
默认使用正式环境地址 https://pacs.qq.com，如需切换环境请通过 --host 参数指定。
请求参数
通过 multipart/form-data 表单提交：
| 字段 | 类型 | 必填 | 说明 |
|---|
studyId | string | 是 | 检查 ID，唯一标识一次检查 |
dicomFile | file | 是 | DICOM 文件压缩包（ZIP 格式），最大 300MB |
studyDate | string | 否 | 检查时间的秒级时间戳（为空时使用服务器当前时间） |
needReport | string | 否 | 是否需要输出报告：0 不需要（默认），1 需要 |
patientId | string | 否 | 患者 ID |
patientName | string | 否 | 患者姓名（用于报告） |
patientGender | string | 否 | 患者性别：0 未知，1 男，2 女 |
patientAge | string | 否 | 患者年龄（整数） |
studyName | string | 否 | 检查项目（如"胸部CT"），为空时使用 DICOM 中的 StudyDescription |
响应字段
| 字段 | 类型 | 说明 |
|---|
head | object | 通用响应头。code=0 表示提交成功，head.taskId 为后续查询所用（格式：{studyId}_{毫秒时间戳}） |
head.code | int | 业务状态码：0 成功，非 0 失败（详见 3.4） |
head.message | string | 状态描述 |
head.resourceRemaining | int | 剩余可用配额次数 |
head.requestId | string | 请求唯一标识（格式：req_{appId}_{纳秒时间戳}） |
head.taskId | string | 任务 ID（格式：{studyId}_{毫秒时间戳}） |
head.studyInstanceUID | string | 从 DICOM 文件中读取的 Study UID |
head.seriesInstanceUID | string | 从 DICOM 文件中读取的 Series UID |
调用方式
使用 Bash 工具执行脚本 @scripts/pneumonia_submit.py：
python3 {SKILL_DIR}/scripts/pneumonia_submit.py \
--app_id "{appId}" \
--token "{token}" \
--study_id "{studyId}" \
--dicom_file "{zip文件绝对路径}" \
[--study_date "{检查时间戳}"] \
[--need_report "1"] \
[--patient_id "{患者ID}"] \
[--patient_name "{患者姓名}"] \
[--patient_gender "{1或2}"] \
[--patient_age "{年龄}"] \
[--study_name "{检查项目}"]
{SKILL_DIR} 为本Skill的安装目录，执行时替换为实际路径。
3.2 肺炎 AI 查询接口
- 接口路径：
https://pacs.qq.com/openapi/pneumoniaQuery
- 请求方式：
POST
- Content-Type：
application/json
请求参数（Body，JSON）
| 字段 | 类型 | 必填 | 说明 |
|---|
taskId | string | 是 | 提交时返回的 head.taskId（支持多个 taskId 以英文分号 ; 分隔） |
studyId | string | 否 | 检查唯一标识（可选） |
needReport | string | 否 | 是否需要报告：0 不需要，1 需要 |
响应字段
| 字段 | 类型 | 说明 |
|---|
head | object | 通用响应头 |
studyId | string | 任务标识（与 taskId 一致） |
status | string | AI 分析状态（见下表） |
pneumoniaSign | string | AI 肺炎表征结果（仅处理完成时返回，格式：肺炎表征 : XX.X%） |
pneumoniaAnalysis | string | AI 肺炎分析结果，格式化的病灶详情文本（仅处理完成时返回） |
reportUrl | string | AI 分析 PDF 报告 URL（仅 needReport=1 且处理完成时返回） |
status 状态值
| status | 含义 | 说明 |
|---|
| 待处理 | 任务已接收，尚未开始处理 | 请稍后重试查询 |
| 处理中 | AI 正在分析中 | 请稍后重试查询 |
| 处理完成 | 分析成功，已返回结果 | 读取 pneumoniaSign 和 pneumoniaAnalysis |
| 处理失败 | 分析失败或 taskId 无效 | 不计费，head.message 为 "taskId无效或任务不存在" |
调用方式
使用 Bash 工具执行脚本 @scripts/pneumonia_query.py：
python3 {SKILL_DIR}/scripts/pneumonia_query.py \
--app_id "{appId}" \
--token "{token}" \
--task_id "{taskId}" \
[--need_report "1"]
3.3 自动轮询等待结果
提交成功后自动轮询查询接口，直到任务完成或失败。脚本会持续输出轮询进度，便于实时反馈给用户。
调用方式
使用 Bash 工具执行脚本 @scripts/pneumonia_poll.py：
python3 {SKILL_DIR}/scripts/pneumonia_poll.py \
--app_id "{appId}" \
--token "{token}" \
--task_id "{taskId}" \
[--need_report "1"] \
[--initial_wait 30] \
[--interval 10] \
[--max_attempts 300]
参数说明：
| 参数 | 默认值 | 说明 |
|---|
--initial_wait | 30 | 首次查询前等待秒数 |
--interval | 10 | 轮询间隔秒数 |
--max_attempts | 300 | 最大轮询次数 |
持续反馈：轮询脚本所有进度信息均带 flush=True 输出，支持后台运行时实时捕获。建议将脚本放入后台执行（run_in_background），再通过 TaskOutput 定期检查输出并向用户反馈最新进度，不要在轮询期间停止反馈。
3.4 业务状态码（head.code）
| code | 枚举名 | 含义 | 处理方式 |
|---|
0 | SUCCESS | 成功 | 正常展示结果 |
1 | PARAM_ERROR | 参数错误（如 studyId 为空、dicomFile 缺失、multipart 解析失败） | 检查请求参数是否完整 |
10001 | DB_ERROR | 数据库错误 | 稍后重试或联系服务方 |
10002 | QUOTA_INSUFFICIENT | 剩余配额不足或资源已过期 | 提醒用户续费 |
10003 | INVALID_TOKEN | Token 失效或签名错误 | 检查 appId/token/时间戳是否正确 |
10004 | INVALID_SIGNATURE | 签名验证失败或资源配置未找到 | 检查 appId/token/时间戳是否正确 |
10005 | CUSTOMER_CLOSED | 客户状态已关闭 | 联系服务方 |
90001 | DATA_FORMAT_ERROR | 数据格式错误（如 ZIP 解压失败、无有效 DICOM 文件、未找到有效图像） | 检查ZIP包和DICOM文件格式 |
90002 | AI_INFERENCE_ERROR | AI 引擎调用失败（上传失败、taskId 无效或任务不存在） | 检查taskId是否有效 |
四、结果展示
将分析结果结构化展示给用户：
- 肺炎表征概率：
pneumoniaSign 值（如 "肺炎表征 : 97.5%"）
- 感染摘要：全肺/左肺/右肺感染占比
- 病灶详情：每处病灶的肺叶位置、层号范围、体积、体积占比、平均CT值
- 报告链接：如
needReport=1，提供 PDF 报告 URL
pneumoniaAnalysis 格式说明：
第一部分：全肺感染比例摘要
占全肺6.2%; 左肺 肺炎占3.1%; 右肺 肺炎占9.3%
若无感染则为：该患者无肺炎感染
第二部分：病灶详情列表
共3处肺炎感染:
（1）右肺上叶【99 / 182】，体积77657mm³，占右肺体积6.6%，平均CT值-603HU
（2）右肺下叶【157 / 210】，体积49177mm³，占右肺体积4.2%，平均CT值-511HU
（3）右肺中叶【181 / 206】，体积4668mm³，占右肺体积0.4%，平均CT值-495HU
各字段含义：
占全肺X.X%：全肺感染体积占比左肺 肺炎占X.X%：左肺感染体积占比右肺 肺炎占X.X%：右肺感染体积占比（N）：病灶序号[位置]：病灶所在肺叶（左肺上叶/左肺下叶/右肺上叶/右肺中叶/右肺下叶）【起始层 / 结束层】：病灶在 CT 序列中的层号范围体积Xmm³：病灶体积占[左/右]肺体积X.X%：病灶占对应侧肺的体积比平均CT值XHU：病灶区域的平均 CT 值
五、注意事项
- 密钥安全：
token 不得出现在前端、日志或客户端代码中；仅在服务端参与签名。
- 时间戳对齐：本地时钟需与 NTP 同步，时间戳与服务器偏差过大将导致鉴权失败。
- 文件格式：DICOM 文件需打包为 ZIP 格式上传，ZIP 内不应包含非 DICOM 文件（如
__MACOSX、隐藏文件等）。
- 文件大小：ZIP 包不超过 300 MB（服务端 multipart 限制）。
- 序列要求：ZIP 包中至少需包含一个图像数量 > 10 张的 CT 序列，否则系统将回退到使用全部图像。
- 并发控制：请根据签约并发阈值控制 QPS，避免触发限流。
- 配额监控：请关注
resourceRemaining，及时续费。配额在 AI 分析完成后由后台异步扣减，提交时的 resourceRemaining 值可能略有延迟。
- 处理时间：肺炎 AI 分析需要较长时间（3~10 分钟），请勿在提交后立即查询，建议等待 30 秒后开始轮询。
- 持续反馈：轮询期间应持续向用户反馈进度（如轮询次数、已等待时长、当前状态），不要在轮询过程中停止反馈。建议后台运行轮询脚本并定期检查输出。
- 僵尸任务清理：超过 24 小时未完成的任务将被系统自动标记为失败并移除，不计费。
- taskId 格式：提交成功后返回的
taskId 格式为 {studyId}_{毫秒时间戳}，查询时需使用完整 taskId。
- 多 taskId 查询：查询接口支持分号分隔的多个 taskId，聚合规则为：任一未完成则整体返回"处理中"。
- 重复计费：相同文件用不同 studyId 多次提交会生成不同 taskId，按多次计费。
六、试用与正式使用
正式环境凭证
当前提供的正式环境凭证（默认环境）：
| 项目 | 值 |
|---|
| 接口地址 | https://pacs.qq.com |
| APP-ID | 100002 |
| APP-TOKEN | ca27d176-d317-475f-8d1f-9cb54032a905 |
三个脚本默认 host 均为正式环境地址 https://pacs.qq.com，无需额外指定即可使用。如需切换环境请通过 --host 参数指定。
如需 sample 肺炎CT数据：可查询访问公开数据集，建议CT层厚＜2mm。
正式使用
如需长期使用，请联系 miying@tencent.com 或访问腾讯健康官网。
七、技术支持
遇到问题时请提供以下信息：
appId、requestId、taskId- 调用时间（含时区）
- 请求头与请求参数
- 错误响应体完整内容
八、验证
- 提交任务后检查返回
head.code 是否为 0，且 head.taskId 非空
- 查询任务后检查
status 字段是否为"处理完成"或"处理失败"
- 处理完成时验证
pneumoniaSign 和 pneumoniaAnalysis 非空
- 签名错误时检查系统时间是否与NTP同步
Reference
- 完整API文档：@references/api_pneumonia.md
