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

CODEBLOCK0

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	INLINECODE3
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	INLINECODE7 Value
Chinese (中文)	INLINECODE8 (default)
English

en |

Then respond entirely in that language throughout the session.

Workflow

1. 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

CODEBLOCK1

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:

CODEBLOCK2

• - adcZero — the sample value that corresponds to 0 mV (baseline offset)
• INLINECODE14 — 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

CODEBLOCK3

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
INLINECODE27	number[]	Yes	Sample value array — integers or floats, converted to mV via the formula above
INLINECODE28

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

CODEBLOCK4

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

Field	Type	Required	Description
INLINECODE32 … INLINECODE33	number[]	Yes	12 lead sample arrays (I, II, III, aVR, aVL, aVF, V1–V6) — integers or floats, converted to mV via the formula above
INLINECODE34

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 snakecase (e.g. avg_hr, avg_qrs, is_abnormal) for consistency. When reading the script output, always use the snakecase names listed here.

1-lead response fields

Field	Type	Description
INLINECODE43	string	INLINECODE44 or INLINECODE45
INLINECODE46

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
INLINECODE62	string	INLINECODE63 or INLINECODE64
INLINECODE65

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:

CODEBLOCK5

Output:

CODEBLOCK6

Agent responds:

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

Example 2 — English user, 12-lead

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

Agent runs:

CODEBLOCK7

Output:

CODEBLOCK8

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:

CODEBLOCK9