前言¶
在 Agent 里做眼底图像分析，常见做法是手写 HTTP 客户端、自己拼 HMAC 签名、再维护上传与轮询两套接口。流程长、字段多，还容易把左右眼编码和查询结果里的 eyeCategory 搞混。下面介绍 SkillHub 上的 @tencent-adm/fundus-images-ai-analysis：把腾讯健康觅影眼底 AI 的上传、查询与结果整理写进 SKILL.md，Agent 按步骤调用即可。
这是什么¶
Fundus Images AI Analysis（中文名：腾讯健康-觅影-基于45°眼底彩照的多病种 AI 分析）是面向 45° 眼底彩照的多病种 AI 分析 Skill，坐标 @tencent-adm/fundus-images-ai-analysis，当前版本 1.0.4，来源为 enterprise，分类 professional，由腾讯健康觅影团队发布。
Skill 封装对 pacs.qq.com 第三方接口的调用（HMAC-SHA256 鉴权），覆盖：眼底图像上传、AI 结果轮询查询，以及青光眼与多病种结论的结构化输出。适用场景是用户要在对话里完成「眼底诊断、眼底分析、眼底图片、AI 诊断眼底、查眼底」等意图时，由 Agent 自动走完整流程。
SkillHub 页面显示评分 100000，下载 960 次，安装 10 次；标签含 requires_api_key=true（正式环境需向腾讯申请凭证，Skill 内亦提供试用 APP-ID / APP-TOKEN）。
核心功能¶
以下能力均来自 Skill 包内 SKILL.md 与参考文档，可与官方页面简介交叉核对。
- 图像上传：支持 JPEG、PNG、DICOM；单文件不超过 5MB；一次检查
images数组 1～20 张，可左右眼合并上传。图片以 Base64 放入 JSON（不含data:image/...;base64,前缀）。 - AI 分析类型：查询时
aiType可取0（青光眼 + 多病种，推荐）、1（仅青光眼）、2（仅多病种）。多病种范围包括糖尿病性视网膜病变（DR）、年龄相关性黄斑变性（AMD）、视网膜静脉阻塞、屈光间质混浊、高血压眼底病变、豹纹状眼底、高度近视眼底改变等。 - 结果查询：上传成功后用自定义
studyId轮询；处理中返回code = 30008，建议每 10 秒查询一次，最长约 3 分钟（18 次）。 - 报告输出：
needReport = 1时可获得 PDF 报告链接（data.reportUrl）；Skill 规定从glaucomaResultList、multipleDiseasesResultList中解析status = 200的条目并格式化展示。
底层接口（正式环境）：
- 上传：
POST https://pacs.qq.com/thirdparty/studyupload/v2/{appId} - 查询：
POST https://pacs.qq.com/thirdparty/queryEyeAIResult/{appId}
安装与启用¶
安装 SkillHub CLI¶
若尚未安装 CLI，可先检查版本；未安装时按 SkillHub 安装文档执行完整安装脚本。
command -v skillhub && skillhub --version
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安装本 Skill¶
安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被识别。
skillhub install fundus-images-ai-analysis --namespace tencent-adm --dir <你的 skills 目录>
常见路径（以 SkillHub 安装文档为准）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
也可在对话中让 Agent 按 SkillHub 安装说明 安装 @tencent-adm/fundus-images-ai-analysis。
鉴权与试用凭证¶
所有请求需在 Header 携带 appId、signature、timestamp（毫秒字符串）。签名算法：
signature = HMAC-SHA256(key=token, message=appId + timestamp)
Skill 文档提供的试用凭证（调用次数与并发有限）：
| 项目 | 值 |
|---|---|
| APP-ID | 12708 |
| APP-TOKEN | 69842f96c5b14c0ca8042fc309f3f087 |
| hospitalId | 12708（与 APP-ID 相同） |
长期使用需联系 miying@tencent.com，或访问 腾讯健康官网。
典型用法¶
Skill 要求 Agent 严格按顺序执行：上传 → 轮询查询 → 格式化输出。
Step 1：上传图片，记下 studyId¶
自行生成 studyId（如 study_ + 短 UUID），studyType 固定为 2（眼底），并为每张图设置 descPosition："1" 左眼、"2" 右眼、"0" 未知。文件名含 OD/OS、_R/_L 等时可按 Skill 规则推断眼位。
签名与上传的 Python 示例（摘自 Skill 文档，将 image_path 换为本地眼底图路径）：
import hmac, hashlib, time, json, base64, uuid, urllib.request
app_id = "12708"
token = "69842f96c5b14c0ca8042fc309f3f087"
image_path = "/path/to/image.jpg"
timestamp = str(int(time.time() * 1000))
signature = hmac.new(token.encode(), (app_id + timestamp).encode(), hashlib.sha256).hexdigest()
with open(image_path, "rb") as f:
image_b64 = base64.b64encode(f.read()).decode()
study_id = "study_" + uuid.uuid4().hex[:12]
body = {
"studyId": study_id,
"studyName": "眼底检查",
"studyDate": int(time.time()),
"studyType": 2,
"images": [{
"imageId": "img_" + uuid.uuid4().hex[:8],
"content": image_b64,
"descPosition": "2"
}]
}
url = f"https://pacs.qq.com/thirdparty/studyupload/v2/{app_id}"
req = urllib.request.Request(url, data=json.dumps(body).encode(), method="POST")
req.add_header("appId", app_id)
req.add_header("signature", signature)
req.add_header("timestamp", timestamp)
req.add_header("Content-Type", "application/json; charset=utf-8")
with urllib.request.urlopen(req, timeout=60) as resp:
result = json.loads(resp.read().decode())
响应 code = 0 表示上传成功；后续查询使用请求体里的 studyId，而非响应里的新 ID。
Step 2：轮询诊断结果¶
body = {
"hospitalId": "12708",
"studyId": study_id,
"aiType": 0,
"needReport": 1
}
轮询 POST https://pacs.qq.com/thirdparty/queryEyeAIResult/12708，code = 30008 时等待 10 秒继续，直到 code = 0 且 data 非空，或达到约 3 分钟上限。
Step 3：在对话中呈现结果¶
从 data 提取青光眼与多病种列表，仅处理 status = 200 的条目；注意查询结果里 eyeCategory（0=左、1=右）与上传时 descPosition（1=左、2=右）编码不同。输出应包含形态学指标、病变检测、疾病诊断小结及 PDF 链接，并附带「AI 辅助、非临床确诊」类免责声明（Skill 模板中有完整字段表）。
试用样例图可从 Skill 文档给出的网盘获取（提取码 KZY7）。
在已安装 Skill 的 Agent 中，用户只需用自然语言描述需求并附上图片路径，例如：「请用眼底分析 Skill 看一下这张右眼彩照」，并带上触发词「眼底分析」「查眼底」等，Agent 会按 SKILL.md 执行上述三步。
适用场景与注意¶
适合谁
- 医疗健康、眼科信息化、体检筛查等需要在 Agent 内对接眼底 AI 的开发者或集成方。
- 希望在 Cursor、Claude Code、Codex 等环境中用统一 Skill 约束调用顺序与输出格式，而不是每次临时查 API 文档的团队。
限制与注意
- 图像格式与大小：JPEG / PNG / DICOM，单文件 ≤ 5MB；参考文档还要求单次检查图片总大小 ≤ 5MB。
- 上传接口因 Base64 体积较大，建议超时 60 秒；查询接口 30 秒即可。
- 每次上传应使用新的
studyId，避免与历史检查冲突。 - 参考文档中
patientId在上传接口为必填；Skill 内 Python 示例未展示该字段，生产集成应以 API 参考文档为准补全患者标识。 - 输出仅供辅助参考，不能替代执业医师诊断；合规与隐私（患者信息、影像存储）需自行满足业务与法规要求。
- 试用凭证有次数与并发限制；正式上线需申请正式
appId/token。
结尾¶
@tencent-adm/fundus-images-ai-analysis 把 45° 眼底彩照的多病种 AI 能力收敛成 Agent 可执行的固定流程：上传、轮询、结构化解读，并对接腾讯健康觅影正式 API。若你要在 Skill 生态里接入眼底 AI，可从 SkillHub 安装该包并按文档配置鉴权。
- SkillHub 页面：https://www.skillhub.cn/skills/tencent-adm/fundus-images-ai-analysis
- API 技能地址：https://api.skillhub.cn/tencent-adm/fundus-images-ai-analysis
