heartvoice ECG Analysis Skill#

Analyze ECG data via the heartvoice (心之声) cloud API. The agent is responsible for detecting user intent (1-lead vs 12-lead) and language (Chinese vs English), then passing the appropriate explicit flags to the CLI script. The script itself requires explicit --mode and --lang parameters — all "automatic" behavior lives in the agent layer, not the script.

When to Activate#

• User wants to analyze ECG / heart rhythm / electrocardiogram data
• User provides a JSON file containing ECG signal data
• Code or conversation mentions 心电图, ECG, 心电分析, 心律分析
• Keywords: 单导联, 十二导联, 1-lead, 12-lead, single lead, twelve lead
• User asks about arrhythmia detection, QRS/QT intervals, or signal quality
• User says "analyze ECG", "分析心电", "ecg diagnosis", or similar

Environment Setup#

bash

# Required — get your key at https://www.heartvoice.com.cn/aiCloud
export HEARTVOICE_API_KEY="your_api_key"

# Install dependencies
pip install requests

Never hardcode API keys. Always use environment variables or .env files.

Agent Responsibilities#

The agent (not the CLI script) is responsible for two kinds of detection:

1. Detect analysis type → pass as CLI mode#

Scan the user message for keywords and map to the explicit CLI mode argument:

User IntentCN KeywordsEN KeywordsCLI ModeSingle-lead signal单导联、单导、1导联1-lead, single lead, one lead1-lead12-lead signal十二导联、12导联、多导联12-lead, twelve lead12-lead

If the user does not specify a type, ask before running the script:

• Chinese: "请问您要分析的是单导联信号还是十二导联信号？"
• English: "Would you like to analyze a single-lead or 12-lead signal?"

2. Detect user language → pass as --lang flag#

Detect the language the user writes in and pass it as the --lang CLI flag:

User Language--lang ValueChinese (中文)zh (default)Englishen

Then respond entirely in that language throughout the session.

Workflow#

1. Agent detects analysis type (1-lead / 12-lead) from user message keywords. If ambiguous, ask.
2. Agent detects user language (zh / en) from the message.
3. Agent extracts file path from the user message.
4. Agent runs the CLI script with explicit arguments: python3 scripts/call_api.py <mode> --json_path <path> --lang <lang>.
5. Agent parses the structured JSON output from stdout.
6. Agent presents the result as a natural-language report in the user's language.

Script Commands#

bash

# 1-lead signal analysis (Chinese output)
python3 scripts/call_api.py 1-lead --json_path <path/to/file.json>

# 1-lead signal analysis (English output)
python3 scripts/call_api.py 1-lead --json_path <path/to/file.json> --lang en

# 12-lead signal analysis (Chinese output)
python3 scripts/call_api.py 12-lead --json_path <path/to/file.json>

# 12-lead signal analysis (English output)
python3 scripts/call_api.py 12-lead --json_path <path/to/file.json> --lang en

Set --lang zh (default) or --lang en based on the language the user writes in.

Input File Formats#

ADC Conversion Formula#

The data arrays contain raw sample values from your recording device (integers or floats, depending on the device). The API internally converts them to millivolts (mV) using:

text

voltage_mV = (sampleValue - adcZero) / adcGain

• adcZero — the sample value that corresponds to 0 mV (baseline offset)
• adcGain — the number of sample units per 1 mV

Example 1 (integer samples): adcGain = 1000, adcZero = 0, sample = 512 → voltage = (512 - 0) / 1000 = 0.512 mV.

Example 2 (float samples, already in mV): if your device outputs values already in millivolts (e.g. 0.512), set adcGain = 1.0 and adcZero = 0.0 so the formula becomes a no-op: voltage = (0.512 - 0) / 1 = 0.512 mV.

These two parameters must match your recording device's output configuration; incorrect values will produce wrong voltage readings and unreliable diagnoses.

1-lead JSON#

json

{
  "ecgData": [0.512, 0.515, 0.520, 0.518, 0.525, 0.530, 0.528, 0.535],
  "ecgSampleRate": 500,
  "adcGain": 1.0,
  "adcZero": 0.0
}

In this example, values are already in mV, so adcGain = 1.0 and adcZero = 0.0 (identity conversion). If your device outputs raw integer ADC values instead, adjust adcGain and adcZero accordingly.

FieldTypeRequiredDescriptionecgDatanumber[]YesSample value array — integers or floats, converted to mV via the formula aboveecgSampleRatenumberYesSampling rate in Hz (e.g. 500)adcGainnumberYesSample units per 1 mVadcZeronumberYesSample value corresponding to 0 mV baseline

12-lead JSON#

json

{
  "dataI":   [...], "dataII":  [...], "dataIII": [...],
  "dataAVR": [...], "dataAVL": [...], "dataAVF": [...],
  "dataV1":  [...], "dataV2":  [...], "dataV3":  [...],
  "dataV4":  [...], "dataV5":  [...], "dataV6":  [...],
  "ecgSampleRate": 500,
  "adcGain": 1000.0,
  "adcZero": 0.0
}

In this example, values are raw integer ADC samples with adcGain = 1000 (1000 units = 1 mV).

FieldTypeRequiredDescriptiondataI … dataV6number[]Yes12 lead sample arrays (I, II, III, aVR, aVL, aVF, V1–V6) — integers or floats, converted to mV via the formula aboveecgSampleRatenumberYesSampling rate in HzadcGainnumberYesSample units per 1 mV — shared across all 12 leadsadcZeronumberYesSample value corresponding to 0 mV baseline

Response Format#

The fields below are the script's output (printed to stdout as JSON). The script normalizes the API's camelCase field names (e.g. avgHr, avgQrs, isAbnormal) to snake_case (e.g. avg_hr, avg_qrs, is_abnormal) for consistency. When reading the script output, always use the snake_case names listed here.

1-lead response fields#

FieldTypeDescriptionstatusstring"success" or "error"``summarystringNatural-language summary in requested languagediagnosisstring[]Label list, e.g. ["SN"]``possible_diagnosisstring[]Possible labels listis_abnormalbooleanWhether abnormal rhythm detectedis_reversebooleanWhether lead reversal detectedsq_gradestringSignal quality score, e.g. "0.95"``avg_hrnumberAverage heart rate (bpm)avg_qrsnumberQRS duration (ms)pr_intervalnumberPR interval (ms)avg_qtnumberQT interval (ms)avg_pnumberP wave duration (ms)avg_qtcnumberCorrected QT interval (ms)pac_countnumberAtrial premature beat countpvc_countnumberVentricular premature beat count

12-lead response fields#

FieldTypeDescriptionstatusstring"success" or "error"``analysis_statebooleanWhether analysis succeededsummarystringNatural-language summary in requested languagediagnosesobject[]Array of {"label", "result", "description"}``diagnosis_resultsstring[]Flat list of result stringsrisk_levelnumberRisk level — 0 = normalHRnumberHeart rate (bpm)atrial_ratenumberAtrial rate (bpm)ventricular_ratenumberVentricular rate (bpm)P / PR / QRS / QT / QTc / TnumberIntervals (ms)QRS_axis / P_axis / T_axisnumberElectrical axes (degrees)SV1 / SV2 / SV5 / RV1 / RV2 / RV5 / RV6numberWave amplitudes (mV)

Examples#

Example 1 — Chinese user, single-lead#

用户：请帮我分析这个单导联信号，数据放在 data/ecg_data.json 里

Agent runs:

bash

python3 scripts/call_api.py 1-lead --json_path data/ecg_data.json --lang zh

Output:

json

{
  "status": "success",
  "summary": "检测到：窦性心律。平均心率 72 次/分钟，QRS 宽度 86 毫秒，PR 间期 156 毫秒，QT 间期 380 毫秒，QTc 412 毫秒，P 波宽度 102 毫秒。信号质量 0.95。房性早搏 0 次，室性早搏 0 次。",
  "diagnosis": ["SN"],
  "possible_diagnosis": [],
  "is_abnormal": false,
  "avg_hr": 72,
  "sq_grade": "0.95"
}

Agent responds:

分析完成。该心电信号显示 窦性心律，平均心率 72 次/分钟，各项参数均在正常范围内。信号质量评分 0.95（优秀），未检测到房性或室性早搏。

Example 2 — English user, 12-lead#

User: Analyze my 12-lead ECG data from records/12lead.json

Agent runs:

bash

python3 scripts/call_api.py 12-lead --json_path records/12lead.json --lang en

Output:

json

{
  "status": "success",
  "summary": "Detected: Sinus Rhythm. Heart rate 75 bpm, QRS duration 88 ms, PR interval 160 ms, QT interval 376 ms, QTc 420 ms, P wave 100 ms, T wave 180 ms. Risk assessment: normal.",
  "diagnoses": [{"label": "SN", "result": "Sinus Rhythm", "description": "Normal sinus rhythm"}],
  "risk_level": 0,
  "HR": 75
}

Agent responds:

Analysis complete. The 12-lead ECG shows Sinus Rhythm with a heart rate of 75 bpm. All intervals are within normal range. Risk level: normal (0).

Example 3 — Ambiguous intent#

User: Can you analyze this ECG for me? The file is at data/signal.json

Agent asks:

Would you like to analyze a single-lead (1-lead) or 12-lead signal?

Error Handling#

SituationActionFile not foundReport the exact path; ask user for the correct pathMissing JSON fieldsList the missing required fields by nameHEARTVOICE_API_KEY not setTell the user to visit https://www.heartvoice.com.cn/aiCloud to obtain an API Key and set it as the HEARTVOICE_API_KEY environment variableHTTP error from APIShow status code and error message from the responseAPI business error ( errorCode != 0)Show the error message returned by the APIFile too large (> 5 MB)Tell the user the file exceeds the 5 MB limitAmbiguous intentAsk whether the data is 1-lead or 12-lead

Security & Privacy#

Data flow: This skill reads a user-specified local JSON file and sends its contents (ECG signal data, sample rate, ADC parameters) over HTTPS to the heartvoice cloud API ( api.heartvoice.com.cn) for analysis. The user should be aware that their ECG data leaves the local machine. No other files or environment variables beyond HEARTVOICE_API_KEY are accessed.

• Never hardcode API keys in scripts or commit them to version control
• ECG data is sensitive medical data — do not log or store raw signal data unnecessarily; inform the user before transmitting
• Always use HTTPS (the API endpoint enforces TLS)
• Add .env to .gitignore if using dotenv files
• The skill only reads the file path explicitly provided by the user — it does not scan or access other files
• This tool provides AI-assisted analysis only; it is NOT a substitute for professional medical diagnosis

Tips#

• Signal quality ( sq_grade) below 0.6 usually indicates noisy data — suggest the user re-record or check electrode contact
• For 12-lead analysis, all 12 lead arrays must be present; partial data will fail field validation
• The adcGain and adcZero values must match your recording device's ADC configuration — see the ADC Conversion Formula section for how they translate raw samples to millivolts
• JSON file size limit is 5 MB
• Typical ecgSampleRate values: 250, 500, 1000 Hz — check your device specs
• Use the example files in data/ to verify your setup before analyzing real signals

Programmatic Usage#

You can also import the script functions directly in Python:

python

import os
from scripts.call_api import load_json, build_1lead_payload, call_api, format_1lead_result

api_key = os.environ["HEARTVOICE_API_KEY"]
data = load_json("data/example_1lead.json")
payload = build_1lead_payload(data)
raw_result = call_api(
    "https://api.heartvoice.com.cn/api/v1/basic/ecg/1-lead/analyze",
    payload, api_key
)
output = format_1lead_result(raw_result)
print(output["summary"])
print(f"Heart rate: {output['avg_hr']} bpm")