caremax-records
# CareMax Medical Records
> **Requires `caremax-auth` as a sibling directory** (`../caremax-auth/`). If missing, tell the user to install caremax-auth first (e.g. `npx skills add KittenYang/caremax-skills`).
## Prerequisites — Auto-Auth (MANDATORY)
```bash
APICALL="bash ../caremax-auth/scripts/api-call.sh"
```
If `api-call.sh` returns `{"error":"no_credentials",...}` → **immediately run `bash ../caremax-auth/scripts/auth-flow.sh [base_url]`** (from this skill’s root).
## Smart Search (Recommended)
Use `searchText` for natural language queries. Backend runs 4-layer search:
1. LLM keyword extraction (maps "喝酒" → "ALDH2 酒精代谢")
2. LIKE search on report titles, summaries, sections, indicators
3. Semantic vector search (BGE-M3 → Zilliz)
4. RAG: DeepSeek-V3.2 generates natural language answer with citations
```bash
$APICALL POST /api/skill/records/query '{"searchText":"我有哪个基因不能喝酒"}'
$APICALL POST /api/skill/records/query '{"searchText":"我猝死的概率大吗"}'
$APICALL POST /api/skill/records/query '{"searchText":"降压药建议"}'
$APICALL POST /api/skill/records/query '{"searchText":"MTHFR"}'
```
Response:
```json
{
"type": "search",
"query": "...",
"data": [...], // matched records (enriched)
"totalCount": 1,
"semanticHits": [ // vector similarity top-10
{"text": "...", "score": 0.61, "recordId": "xxx"}
],
"rag": { // AI natural language answer
"answer": "根据您的基因检测报告...[来源1][来源2]",
"citations": [
{"index": 1, "source": "脑梗塞风险评估", "relevance": "高"}
]
}
}
```
**Display the `rag.answer` to the user.** It contains the direct answer with citation references.
## Structured Query
```bash
# By date range
$APICALL POST /api/skill/records/query '{"dateRange":["2025-01-01","2025-12-31"]}'
# By indicator name
$APICALL POST /api/skill/records/query '{"indicatorName":"血红蛋白"}'
# By report title
$APICALL POST /api/skill/records/query '{"reportTitle":"血常规"}'
# By record ID (single record detail)
$APICALL POST /api/skill/records/query '{"recordId":"uuid"}'
# By member + pagination
$APICALL POST /api/skill/records/query '{"memberId":"member-uuid","page":1,"limit":20}'
```
## Report Types
The system handles multiple report types:
- **lab**: Standard lab reports (indicators with name/value/unit/reference_range)
- **genetic**: Gene testing reports (sections with gene/SNP/genotype/risk_level)
- **imaging**: Radiology reports (sections with location/finding/impression)
- **pathology**: Pathology reports (sections with tissue/grade/staging)
- **other**: Any other medical document
Non-lab reports have `report_type`, `summary`, and `sections[]` fields instead of `indicators[]`.
## AI 对话（推荐）
使用 `/api/skill/chat` 进行 AI 对话。所有对话自动保存到历史记录。
```bash
# 提问（自动搜索 + RAG + 保存历史）
$APICALL POST /api/skill/chat '{"question":"我有哪个基因不能喝酒"}'
$APICALL POST /api/skill/chat '{"question":"我的降压药应该怎么吃"}'
# 针对某份报告提问
$APICALL POST /api/skill/chat '{"question":"这份报告有什么建议","recordId":"uuid"}'
```
Response:
```json
{
"id": "chat-uuid",
"question": "...",
"answer": "根据您的报告...[来源1]",
"citations": [{"index":1,"source":"...","relevance":"高","quote":"原文..."}],
"recordId": null,
"created_at": "..."
}
```
**Display the `answer` to the user.** Citations contain original report text.
```bash
# 获取历史记录
$APICALL GET /api/skill/chat/history
# 删除单条
$APICALL DELETE /api/skill/chat/<chat_id>
# 清空所有
$APICALL DELETE /api/skill/chat
```
## Recommended Workflow
User: "我的基因检测报告说了什么"
```bash
$APICALL POST /api/skill/chat '{"question":"我的基因检测报告说了什么"}'
```
User: "show my recent check-up results"
```bash
$APICALL POST /api/skill/records/query '{"dateRange":["2025-01-01","2025-06-30"]}'
```
User: "我的降压药应该怎么吃"
```bash
$APICALL POST /api/skill/chat '{"question":"我的降压药应该怎么吃"}'
```
标签
skill
ai
