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
# 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 Intent | CN Keywords | EN Keywords | CLI Mode |
|---|
| Single-lead signal | 单导联、单导、1导联 | 1-lead, single lead, one lead | 1-lead |
| 12-lead signal | 十二导联、12导联、多导联 | 12-lead, twelve lead | 12-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 Value |
|---|
| Chinese (中文) | zh (default) |
| English | en |
Then respond entirely in that language throughout the session.
Workflow
- Agent detects analysis type (1-lead / 12-lead) from user message keywords. If ambiguous, ask.
- Agent detects user language (zh / en) from the message.
- Agent extracts file path from the user message.
- Agent runs the CLI script with explicit arguments:
python3 scripts/call_api.py <mode> --json_path <path> --lang <lang>.
- Agent parses the structured JSON output from stdout.
- Agent presents the result as a natural-language report in the user's language.
Script Commands
# 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:
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
{
"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.
| Field | Type | Required | Description |
|---|
ecgData | number[] | Yes | Sample value array — integers or floats, converted to mV via the formula above |
ecgSampleRate | number | Yes | Sampling rate in Hz (e.g. 500) |
adcGain | number | Yes | Sample units per 1 mV |
adcZero | number | Yes | Sample value corresponding to 0 mV baseline |
12-lead 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).
| Field | Type | Required | Description |
|---|
dataI … dataV6 | number[] | Yes | 12 lead sample arrays (I, II, III, aVR, aVL, aVF, V1–V6) — integers or floats, converted to mV via the formula above |
ecgSampleRate | number | Yes | Sampling rate in Hz |
adcGain | number | Yes | Sample units per 1 mV — shared across all 12 leads |
adcZero | number | Yes | Sample 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
| Field | Type | Description |
|---|
status | string | "success" or "error" |
summary | string | Natural-language summary in requested language |
diagnosis | string[] | Label list, e.g. ["SN"] |
possible_diagnosis | string[] | Possible labels list |
is_abnormal | boolean | Whether abnormal rhythm detected |
is_reverse | boolean | Whether lead reversal detected |
sq_grade | string | Signal quality score, e.g. "0.95" |
avg_hr | number | Average heart rate (bpm) |
avg_qrs | number | QRS duration (ms) |
pr_interval | number | PR interval (ms) |
avg_qt | number | QT interval (ms) |
avg_p | number | P wave duration (ms) |
avg_qtc | number | Corrected QT interval (ms) |
pac_count | number | Atrial premature beat count |
pvc_count | number | Ventricular premature beat count |
12-lead response fields
| Field | Type | Description |
|---|
status | string | "success" or "error" |
analysis_state | boolean | Whether analysis succeeded |
summary | string | Natural-language summary in requested language |
diagnoses | object[] | Array of {"label", "result", "description"} |
diagnosis_results | string[] | Flat list of result strings |
risk_level | number | Risk level — 0 = normal |
HR | number | Heart rate (bpm) |
atrial_rate | number | Atrial rate (bpm) |
ventricular_rate | number | Ventricular rate (bpm) |
P / PR / QRS / QT / QTc / T | number | Intervals (ms) |
QRS_axis / P_axis / T_axis | number | Electrical axes (degrees) |
SV1 / SV2 / SV5 / RV1 / RV2 / RV5 / RV6 | number | Wave amplitudes (mV) |
Examples
Example 1 — Chinese user, single-lead
用户：请帮我分析这个单导联信号，数据放在 data/ecg_data.json 里
Agent runs:
python3 scripts/call_api.py 1-lead --json_path data/ecg_data.json --lang zh
Output:
{
"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:
python3 scripts/call_api.py 12-lead --json_path records/12lead.json --lang en
Output:
{
"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
| Situation | Action |
|---|
| File not found | Report the exact path; ask user for the correct path |
| Missing JSON fields | List the missing required fields by name |
HEARTVOICE_API_KEY not set | Tell the user to visit https://www.heartvoice.com.cn/aiCloud to obtain an API Key and set it as the HEARTVOICE_API_KEY environment variable |
| HTTP error from API | Show status code and error message from the response |
API business error (errorCode != 0) | Show the error message returned by the API |
| File too large (> 5 MB) | Tell the user the file exceeds the 5 MB limit |
| Ambiguous intent | Ask 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:
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")
