Agent Skills › thetahealth/mirobody › standardize-health-data

standardize-health-data

GitHub

将原始健康数据(如化验单、Apple Health导出、症状描述)标准化为LOINC、UCUM、ICPC-3代码及FHIR观测值。支持离线解析与多格式文档读取,确保数据准确映射至标准词汇表,适用于医疗数据处理流水线。

skills/standardize-health-data/SKILL.md thetahealth/mirobody

触发场景

需要标准化健康数据字段名称和单位 解析PDF或图片格式的体检报告 将症状或诊断转换为ICPC-3编码 处理Apple Health导出数据

安装

npx skills add thetahealth/mirobody --skill standardize-health-data -g -y
更多选项

不安装直接使用

npx skills use thetahealth/mirobody@standardize-health-data

指定 Agent (Claude Code)

npx skills add thetahealth/mirobody --skill standardize-health-data -a claude-code -g -y

安装 repo 全部 skill

npx skills add thetahealth/mirobody --all -g -y

预览 repo 内 skill

npx skills add thetahealth/mirobody --list

SKILL.md

Frontmatter
{
    "name": "standardize-health-data",
    "license": "Apache-2.0",
    "metadata": {
        "author": "thetahealth",
        "homepage": "https:\/\/github.com\/thetahealth\/mirobody"
    },
    "description": "Turn raw health data into standardized data, and read a lab report without guessing. A lab report PDF, photo, spreadsheet or CSV becomes readings with LOINC codes and UCUM units; an Apple Health export becomes JSON lines; a symptom or diagnosis in any language becomes an ICPC-3 code; any reading becomes a FHIR Observation. Use whenever health data must be standardized for a pipeline, dataset or app, and whenever a blood test, lab report or checkup result is shared and each row must be identified from the vocabulary rather than from memory. Resolution is offline and needs no key; parsing a document needs one model key."
}

Standardize health data

Health data arrives under whatever name the source used. Last year's checkup wrote A1c, this year's HbA1c, the clinic Glycated Hemoglobin; a Chinese report prints 血红蛋白 for what an English one calls hemoglobin. One test, several names, nothing to compare until each lands on one code. And a model reading a report is fluent about the rows it got wrong: the failure is never "I don't know", it is a confident paragraph about the wrong analyte.

This skill is the offline standardizer for both problems: names to LOINC, units to UCUM, complaints and diagnoses to ICPC-3, a FHIR Observation for the result. The codes come from the vocabulary, never from you. When the vocabulary does not know a term the answer is a refusal, and a refusal is an output to report, not a gap to fill from memory.

Setup

pip install mirobody              # resolution, units, ICPC-3, Apple export: no key, no network
pip install 'mirobody[parse]'     # adds document parsing, which needs one model key

The first is two packages, numpy and this one; the vocabulary ships inside the wheel and the first call loads it in a few seconds. It needs Python 3.12 or newer: on an older interpreter pip quietly installs a release from before 1.2, which has no mirobody resolve. Install into a virtual environment (python3.12 -m venv .venv), never into the user's system Python. With uvx, no install: uvx --python 3.12 mirobody resolve 血红蛋白 (uv fetches that Python if it is missing). For parsing, put ONE key in the environment or a .env in the working directory (OPENROUTER_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY or DASHSCOPE_API_KEY). The model reads the document into rows; the codes still come from the offline resolver.

No key, no search. If neither the environment nor the working directory's .env has a key, do not look for one anywhere else: no find ~, no reading another project's .env or ~/.config. Read the document yourself, then resolve every row with resolve_reading(name, value, unit), which needs no key. Ask the user for a key only if they want mirobody parse itself.

Which command, by what you were given

You have Do
Names, values and units already extracted resolve_reading(name, value, unit) in Python, or mirobody resolve for names alone
A document: PDF, photo, Excel, Word, PowerPoint, CSV, text mirobody parse <file>
An Apple Health export.zip or export.xml mirobody import apple <path> --out facts.jsonl
A symptom or a diagnosis in words resolve_symptom(text) / resolve_condition(text)
A unit to normalize or convert mirobody.units
A FHIR Observation for another system standardize_reading(name, value, unit)
A report to explain to the person it belongs to Sections 1 and 8
Garmin, Oura or WHOOP data Connect the device to a running Mirobody (the mirobody skill); there is no standalone export reader

1. Names to codes, and why the unit travels with the name

mirobody resolve "LDL cholesterol" 血红蛋白 ヘモグロビン "空腹血糖(GLU)" 血脂
  LDL cholesterol  LOINC 13457-7   Cholesterol in LDL [Mass/volume] in Serum or Plasma by calculation
  血红蛋白          LOINC 718-7     Hemoglobin [Mass/volume] in Blood
  ヘモグロビン      LOINC 718-7     Hemoglobin [Mass/volume] in Blood
  空腹血糖(GLU)     LOINC 1558-6    Fasting glucose [Mass/volume] in Serum or Plasma
  血脂             unresolved: not in the lexical index, ...

Two languages, one code. 血脂 (lipids) is a category, not one observation, so it resolves to nothing rather than to a guess. Pass every name in one call; the canonical name that comes back, not your memory, is what the row measures.

LOINC encodes the unit and the result type into the identity, so the same name is two codes depending on what was measured. Pass the value and unit whenever the source prints them:

from mirobody.engine import resolve, resolve_reading

resolve("total cholesterol").loinc                          # '2093-3'   [Mass/volume], the common default
resolve_reading("total cholesterol", "5.0", "mmol/L").loinc  # '14647-2'  [Moles/volume]: the unit picked the code
resolve_reading("中性粒细胞", "62", "%").loinc                 # '26511-6'  a percentage
resolve_reading("中性粒细胞", "4.2", "10*9/L").loinc           # '26499-4'  an absolute count

On the checkup shipped at demo/upload/you_annual_checkup_2026-05.pdf, nine printed rows resolve 9/9, and five of the nine codes are different when the unit is passed: every mmol/L row moves from the mass code to the molar one. Resolving names alone files those five under the wrong code, and the percentage-versus-count pair is the single most common misreading of a CBC.

The result carries the decision, not just the code:

r = resolve_reading("Glycated Hemoglobin-HbA1c", "5.2", "%")
r.resolved, r.loinc, r.canonical     # True, '4548-4', 'Hemoglobin A1c/Hemoglobin.total in Blood'
r.method                             # 'lexical'

2. A document to rows

mirobody parse demo/upload/you_annual_checkup_2026-05.pdf
  Glycated Hemoglobin-HbA1  5.2 %             LOINC 4548-4     Hemoglobin A1c/Hemoglobin.total in Blood
  Fasting Blood Glucose-FB  4.9 mmol/L        LOINC 14771-0    Fasting glucose [Moles/volume] in Serum or Plasma
  Total Cholesterol-TC      4.45 mmol/L       LOINC 14647-2    Cholesterol [Moles/volume] in Serum or Plasma
  ...
9 readings · 9 resolved to standard codes · offline lexical index
collected 2026-05-06, as the document prints it

A PDF with a text layer, a spreadsheet or a Word file is read locally and only the row extraction goes to the model; a scanned page or a photo goes to the model as an image, which is why the key's model must be multimodal. In Python, parse_file(path) returns the same readings as objects, each with name, value, unit, collected and a resolution. --no-resolve returns the rows as extracted, without codes.

3. An Apple Health export to JSON lines

mirobody import apple export.zip --out facts.jsonl     # export.xml or the unpacked folder also work
  heartRates        1 readings   62 … 62
  steps             1 readings   1834 … 1834
5 readings · 5 indicators · 2026-09-29 … 2026-09-29
Facts written to facts.jsonl

One line per record, keyed by Mirobody's standard device indicator (heartRates, steps, bodyMasss, systolicPressures, bloodGlucoses, 316 in all), with the value, the unit as Apple wrote it, and the effective window in epoch milliseconds:

{"metric_key": "heartRates", "value_num": 62.0, "effective_start_ms": 1790665200000, "effective_end_ms": 1790665205000, "unit": "count/min", "modality": "sensed", ...}

No key, no database; the file is streamed, so a multi-year export of a few hundred megabytes is fine. Apple records carry their own UTC offset; --tz is only the fallback for the few that do not.

4. A symptom or a diagnosis to ICPC-3

Complaints and diagnoses are not lab analytes and never go through resolve: a fever is not a fever-virus assay. They have their own axis, with the same refusal rule.

from mirobody.standardize import resolve_symptom, resolve_condition

resolve_symptom("头疼").code            # 'NS01'        Headache; 'headache' and 'головная боль' answer the same
resolve_symptom("疼").outcome          # 'refused'     too broad: r.reason == 'icpc3:too-broad'
resolve_condition("2型糖尿病").code     # 'TD72'        Type 2 diabetes mellitus
resolve_condition("糖尿病").outcome     # 'needs-input' which type? r.reason == 'icpc3:ambiguous'
resolve_condition("hypertension").code # 'KD73'        Hypertension, uncomplicated

Three outcomes, each an instruction: coded gives code and display; refused means keep the words and do not code; needs-input means it cannot be coded as given, and reason says why. icpc3:ambiguous asks which one (the source or the user has to say); icpc3:no-match means the text is not one complaint or diagnosis on this axis: split a sentence into its terms first, and send a diagnosis to resolve_condition, not resolve_symptom.

5. Units

from mirobody.units import normalize_unit, unit_family, convert_value, parse_value_unit

normalize_unit("mmol/l")                 # 'mmol/L'    UCUM spelling
normalize_unit("10^9/L")                 # '10*9/L'
normalize_unit("µmol/L")                 # 'umol/L'
unit_family("mg/dL")                     # 'MCnc'      mass concentration
parse_value_unit("<0.5 ng/mL")           # ParsedQuantity(comparator='<', value=0.5, unit='ng/mL')

convert_value(100, "mg/dL", "mmol/L", loinc_code="2339-0")    # 5.55   glucose, by its molar mass
convert_value(1.0, "mg/dL", "umol/L", loinc_code="2160-0")    # 88.4   creatinine
convert_value(62, "%", "10*9/L", loinc_code="26511-6")        # None   a percentage is not a count: refused

A mass-to-molar conversion needs the analyte, which is why loinc_code is the argument: the bridge is the molar mass of what that code measures.

6. A FHIR Observation

from mirobody.engine import standardize_reading
standardize_reading("血红蛋白", "13.5", "g/dL")
{"resourceType": "Observation", "status": "final",
 "code": {"text": "血红蛋白",
          "coding": [{"system": "http://loinc.org", "code": "718-7", "display": "Hemoglobin [Mass/volume] in Blood"}]},
 "valueQuantity": {"value": 13.5, "unit": "g/dL", "system": "http://unitsofmeasure.org", "code": "g/dL"},
 "extension": [{"url": "https://mirobody.ai/fhir/StructureDefinition/coding-decision", "extension": [
    {"url": "method", "valueString": "lexical"}, {"url": "evidence", "valueString": "name"}, ...]}]}

code.text keeps the name as the source wrote it; the coding-decision extension records how the code was chosen, so a reviewer can audit the row.

7. The same functions over MCP, without the server

uvx --python 3.12 mirobody mcp

Serves six tools over stdio. Five are offline and need no key: resolve_indicator, normalize_unit, convert_unit, standardize_reading and standardize_complaint. The sixth, standardize_report, reads a whole document with a model, so it needs uvx --python 3.12 --from 'mirobody[parse]' mirobody mcp and one model key; without them it answers with that instruction. Point Claude Code, Codex, Cursor, Claude Desktop or any MCP client at the command when the agent should call the resolver as a tool rather than through Python.

Rules that keep the output honest

  • Keep the name as printed beside the code. Total Cholesterol-TC stays Total Cholesterol-TC; the resolver already tries the hyphen-stripped and parenthesis-stripped spellings and resolves both halves of 名称(缩写), so do not pre-clean, translate or expand abbreviations.
  • A panel in the canonical name is a heading, not a value. 肝功能 resolves to 24325-3 Hepatic function 2000 panel - Serum or Plasma; the rows under it get their own codes, the heading gets none.
  • A refusal is a row with no code, not a dropped row. Write the name, the value and the unit, leave the code empty, and say why: unresolved, refused (too broad), or needs-input (ambiguous).
  • Treat a suspiciously specific match as unresolved. The resolver now refuses the category surfaces 免疫, stool, 重金属, heavy metals, 激素 and enzymes; it must not turn a category or specimen word into one named assay. If a new term has the same shape, do not use its code and report the term: a wrong term is the highest-leverage bug this project takes.
  • Reference ranges are not in this skill. Carry the range the source printed; never supply one.

reference.md holds the confusion tables: the unit pairs, adjacent names that are not the same test, category headings that abstain, the deliberately unresolved category surfaces, the extractor shapes worth a retry, and the demo report row by row.

8. Reading a report to the person it belongs to

The same resolver, one more rule: explain nothing you have not resolved.

  1. Read the original document, not a summary. Layout carries the panels, the H/L flags and the printed reference range beside each row.
  2. Extract every row verbatim: name, value, unit, printed range.
  3. Resolve every name in one call before saying what any row measures. Pass the unit. The canonical name is what the row is.
  4. A name the resolver does not know stays unknown, and you say so. Check first whether it is a panel heading or a mangled spelling.
  5. Flag against the printed range only. A row with no printed range has no range; do not supply one.
  6. Three sentences per flagged item: what it measures (from the canonical name), how far and which way it moved, what commonly influences it, named as possibilities. Out-of-range first, borderline second, normals in one line.

Boundaries: no diagnosis and no treatment advice ("ALT is twice the upper limit" is a fact, "you have liver disease" is a diagnosis; point at what to raise with a clinician, by name). Never invent a value, a unit or a range. Keep the report's language for indicator names, with a translation in parentheses when the conversation is in another one. Do not print codes unless asked; they are your evidence, not the answer.

Out of range (2): LDL cholesterol 4.2 mmol/L (ref < 3.4), 24% above the limit and up from 3.8 in March; ALT 68 U/L (ref 7–56), mildly elevated. Borderline (1): fasting glucose 5.9 mmol/L (ref 3.9–6.1), drifting up across three reports. Normal (12): CBC, kidney, thyroid, vitamins. Could not identify (1): 肿瘤标志物 is a category heading; the markers under it resolved and are covered above. Worth raising with your clinician: the LDL trend and the ALT, together with the triglycerides.

What a clean row looks like

name (as printed) value unit (UCUM) system code display method source
Total Cholesterol-TC 4.45 mmol/L LOINC 14647-2 Cholesterol [Moles/volume] in Serum or Plasma lexical checkup.pdf p.1
血脂 unresolved report.jpg p.2
头疼 ICPC-3 NS01 Headache coded journal 2026-09-29

Everything in the table came from the source or the vocabulary. Nothing in it came from memory.

Scope

Storing, charting, and Garmin, Oura or WHOOP data are the running application, one ./deploy.sh away and covered by the mirobody skill. Coverage is 347/347 on the tests an ordinary checkup prints, in English, Chinese (Simplified and Traditional), Japanese, Russian, Estonian and Turkish, against bundle loinc-2.83+2026.10.27-126ecba69782. Beyond those panels, expect gaps, and prefer a reported gap to a confident guess.

版本历史

  • 8f021af 当前 2026-11-21 03:49

同 Skill 集合

skills/mirobody/SKILL.md

元信息

文件数
0
版本
8f021af
Hash
9e9e3be3
收录时间
2026-11-21 03:49

首页 - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-21 05:03
浙ICP备14020137号-1