---
name: battery-anomaly-detection
description: "储能设备告警与故障异常检测。仅当用户明确询问蓄电池【告警记录、故障记录、异常检测、故障趋势、设备离线、故障代码、故障级别】时激活本技能。Do NOT use for 蓄电池组列表、实时运行状态、充放电统计 — handled by sql-report-generator."
compatibility: Requires Python 3.x and access to battery fault database
metadata:
  author: Battery_Ops_Team
  version: 1.3.0
---

# 储能设备异常检测 / Battery Anomaly Detection

负责查询蓄电池异常告警记录，并通过可视化 HTML 报告呈现结果。适用于告警记录、故障统计、设备离线等异常类问题。

---

## ⚠️ 关键约束 / Critical Rules

- MUST: 每次执行前先向用户发送进度消息
- MUST: 每步执行时，必须将实际调用的完整脚本命令（含所有参数）输出给用户
- MUST: 按顺序执行所有三个步骤，不可跳过报告生成步骤
- MUST: 根据用户问题从参数表中选择合适参数组合后再执行脚本
- MUST: 所有三步执行完毕后，必须执行命令记录步骤，将本次完整调用写入 commands.txt
- NEVER: 直接在对话中回答故障数据，必须执行脚本获取真实数据
- NEVER: 伪造或猜测脚本输出结果
- NEVER: 只回复"报告已生成"，必须真正分析数据内容

---

## When to Use / 触发范围

### 本技能处理

- 查询蓄电池告警记录、故障记录
- 查询某个故障代码（如电芯过压、组内温差过大）的发生次数
- 查询蓄电池异常趋势、故障统计
- 查询设备离线记录
- 查询某时间段内的故障明细

### 本技能不处理（移交其他技能）

- "有多少蓄电池组"、"蓄电池组列表"、"有哪些蓄电池组" → 交给 `sql-report-generator`
- "蓄电池组实时状态"、"SOC 是多少"、"电压电流" → 交给 `sql-report-generator`
- "蓄电池日充放电量"、"循环次数"、"充放电统计" → 交给 `sql-report-generator`
- "蓄电池组可用率"、"转换效率" → 交给 `sql-report-generator`
- 任何不涉及"告警/故障/异常/离线"的蓄电池数据查询 → 交给 `sql-report-generator`

---

## How to Execute / 执行流程

> 按顺序执行以下三个步骤，每步必须先发送进度消息再执行命令。

### Step 1: Select Template

**FIRST**, send this message to the user:

`【开始分析】正在理解需求，匹配数据视图与展示模板...`

**THEN**, output the exact command to the user in a code block, then run:

```bash
cd /workspace/skills/report-generator && \
python3 scripts/step1_select.py --query "{{USER_QUERY}}" --data "{}"
```

*Replace `{{USER_QUERY}}` with the user's original question.*

Output example:

```json
{
  "status": "success",
  "template_name": "dataTable",
  "reason": "故障记录明细适合用表格形式展示"
}
```

Pass to next step: `template_name` → `--template` in Step 3.

---

### Step 2: Query Battery Fault Records

**FIRST**, send this message to the user:

`【查询数据】已根据问题匹配查询参数，正在执行蓄电池异常数据查询...`

**THEN**, output the exact command to the user in a code block, then run:

```bash
cd /home/admin/.openclaw/workspace-agent-200/skills/battery_anomaly_detector && \
python3 scripts/query_faults.py [参数]
```

*Replace `[参数]` with the appropriate combination from the parameter table below based on the user's query.*

Output example:

```json
{
  "status": "success",
  "query_type": "detail",
  "total": 10,
  "data": [...],
  "message": "共查询到 10 条记录。"
}
```

**After Step 2, MUST immediately show the user:**
- 查询到的记录总数（`total` 字段）
- 查询类型（明细 `detail` 或统计聚合）

Pass to next step: 完整 JSON 输出 → `--data` in Step 3.

---

### Step 3: Render HTML Report

**FIRST**, send this message to the user:

`【报告生成】正在将结果渲染为可视化报告...`

**THEN**, output the exact command to the user in a code block, then run:

```bash
cd /workspace/skills/report-generator && \
python3 scripts/step2_render.py \
  --query "{{USER_QUERY}}" \
  --template "{{template_name from Step 1}}" \
  --data "{{Output JSON data from Step 2}}"
```

Output example:

```json
{
  "status": "success",
  "message": "Report generated successfully",
  "template": "dataTable",
  "address": "/skills/report-generator/output/report_1773642266.html",
  "summary": "共查询到 10 条异常记录，其中 CRITICAL 级别 3 条，WARNING 级别 7 条，故障类型以电芯过压（CELL_OV）为主。"
}
```

---

### Step 4: Log Commands

After all three steps complete, run the following command to append this execution record to commands.txt.
Replace all `{{...}}` placeholders with the actual values used in Steps 1–3.

```bash
cat >> /home/admin/.openclaw/workspace-agent-200/skills/battery_anomaly_detector/commands/commands.txt << 'EOF'
## [{{YYYY-MM-DD HH:MM:SS}}] {{USER_QUERY}}
```bash
# Step 1
cd /workspace/skills/report-generator && python3 scripts/step1_select.py --query "{{USER_QUERY}}" --data "{}"
# Step 2
cd /home/admin/.openclaw/workspace-agent-200/skills/battery_anomaly_detector && python3 scripts/query_faults.py {{actual_params}}
# Step 3
cd /workspace/skills/report-generator && python3 scripts/step2_render.py --query "{{USER_QUERY}}" --template "{{template_name}}" --data "{{step2_output_json}}"
```
EOF
```

---

## Parameters / 参数表

| 参数 | 类型 | 说明 |
|------|------|------|
| `--battery_id` | int | 电池组 ID，按组过滤 |
| `--fault_code` | str | 故障代码，见下方故障代码表 |
| `--fault_level` | str | 故障级别：`WARNING` 或 `CRITICAL` |
| `--start_time` | str | 起始时间，格式 `YYYY-MM-DD` 或 `YYYY-MM-DD HH:MM:SS` |
| `--end_time` | str | 结束时间，格式 `YYYY-MM-DD` 或 `YYYY-MM-DD HH:MM:SS` |
| `--granularity` | str | 时间聚合粒度：`minute` / `hour` / `day` / `month` / `year`，指定后返回统计数据而非明细 |
| `--limit` | int | 返回条数，默认 100 |

### 故障代码表

| fault_code | 故障名称 |
|------------|----------|
| CELL_OV | 电芯过压 |
| CELL_UV | 电芯欠压 |
| CELL_OT | 单体过温 |
| GROUP_TD | 组内温差过大 |
| CELL_VD | 单体电压一致性差 |
| CELL_RI | 单体内阻老化 |
| CELL_OD | 深度放电风险 |
| DEV_OFFLINE | 设备离线 |

---

## Final Reply Format / 最终回复格式

最终回复必须包含以下三个部分：

**Part 1 — 数据分析摘要（必须，不可省略）**
基于 Step 3 输出的 `summary` 字段，用中文撰写真实的数据分析内容。
优先展示：设备ID/名称、故障名称、故障级别、实际观测值、处置建议。
**禁止**只写"报告已生成"，必须真正分析数据内容。
⚠️ CRITICAL: 每次都必须重新撰写分析，**禁止复用上一次回复的文字**。

**Part 2 — Address Tag（倒数第二行，格式固定）**
```
@@@@@/skills/report-generator/output/report_1773642266.html@@@@@
```
⚠️ 从脚本输出的 `address` 字段原样复制，`@@@@@` 两侧不加空格。

**Part 3 — Suggestions Tag（最后一行，格式固定）**
```
#####%查看详细数据%￥点击上方链接查看完整的数据分析报告￥ %继续深入分析%￥基于当前数据进行更深度的挖掘￥ %导出报告%￥将当前报告导出为PDF或图片格式￥#####
```

---

## Bundled Resources / 附带资源

- `scripts/query_faults.py` — 执行故障查询，返回 JSON 格式的告警记录
- `references/battery_fault_knowledge.txt` — 故障知识库，仅在调试或需要补充故障说明时查阅

> Read these files only when debugging. Normal execution does not require manual inspection.

---

## Error Handling / 异常处理

- `"status": "error"` → 告知用户"查询服务暂时不可用，请稍后重试"，输出 `message` 字段内容。
- Empty result (`total = 0`) → 告知用户"未发现符合条件的异常记录"。
- Step 3 渲染失败 → 告知用户"报告生成失败，以下为原始查询结果"，并直接展示 Step 2 的数据。