# Battery Health Check

> 检测笔记本电池健康度并生成完整诊断报告，支持 macOS 与 Windows。产出电池健康概览（电脑型号、电池型号、设计容量、当前满充容量、健康度、循环次数）、对健康度与衰减趋势的专业解读、使用与置换建议，并附带一张可用浏览器打开的 SVG 容量衰减趋势图和系统官方电池报告。当用户提到电池、续航、电量、掉电快、充不满、电池健康度、电池老化、循环次数、要不要换电池、电池还能用多久、battery health，或想给笔记本做硬件体检时，都要使用这个 skill——即使用户只是随口说一句"电脑越来越不耐用了""待机时间变短了"也同样适用。

- Skill: `1ecc/battery-health-check` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add 1ecc/battery-health-check`
- Raw SKILL.md: https://api.skillmd.com/api/skills/1ecc/battery-health-check/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: 1Ecc (https://skillmd.com/u/1ecc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/1ecc/battery-health-check

---


# 电池健康度检测

## 这个 skill 交付什么

一次完整的电池体检，四份东西：

1. **一份 Markdown 报告**（回复正文）：健康概览 → 解读 → 小建议
2. **一张容量衰减趋势图**（SVG，浏览器可直接打开）
3. **一份系统官方电池报告**（原始数据，可存档、可发给服务网点）
4. **按需的服务推荐**（有明确触发条件，见第 5 步）

面对的场景是联想服务团队的一线咨询：报告要让顾问照着能讲、让客户听得懂并且相信。
所以**数据必须真实、口径必须说清、推荐必须克制**。

---

## 执行流程

### 第 1 步：采集

先判断平台（`uname -s` 或看环境），然后执行对应脚本。**不要自己手敲 ioreg/powercfg 命令去凑数据**——
脚本已经处理了一堆平台坑（见 `references/platform-notes.md`），手敲会踩回去。

**macOS：**

```bash
bash <skill_dir>/scripts/collect_macos.sh --outdir ~/Documents/battery-health-$(date +%Y%m%d-%H%M%S)
```

**Windows：**

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File <skill_dir>\scripts\collect_windows.ps1
```

脚本会把 `KEY=VALUE` 指标打到 stdout（同时存一份 `metrics.env`），并在输出目录里生成
官方电池报告和 `history.tsv`。记下 `outdir`，后面都用它。

**退出码 2** 表示没检测到电池（台式机、电池已拆除）。这种情况直接如实告诉用户，不要继续往下走。

### 第 2 步：画趋势图

```bash
python3 <skill_dir>/scripts/render_trend.py --metrics <outdir>/metrics.env --out <outdir>/battery-trend.svg
```

脚本自己决定用日期轴还是循环次数轴，也自己处理"只有一个实测点"的情况——
这时它会画成**推算区间**而不是一条看着很确定的线。报告里的措辞要和图一致：
图上写的是区间，正文就不能只报一个确定数字。

如果环境里没有 `python3`，跳过这一步并在报告里说明趋势图未生成，其余部分照常输出。
不要为了补这张图去手写 SVG——手写的图和脚本的口径对不上，反而制造矛盾。

### 第 3 步：判读

**动笔前先读 `references/interpretation.md`。** 那里面有健康度分级、循环次数分级、
衰减速率公式、异常信号清单和综合结论四档，全部按它来判，不要凭印象给结论。

特别注意 `health_pct_os` 和 `health_pct_raw` 这两个健康度口径的区别，
它们经常差好几个百分点（Apple Silicon 上尤其常见）。混用是这个任务最容易出的错。

平台相关的字段口径和已知坑在 `references/platform-notes.md`，遇到字段缺失、
数值可疑、或者需要跟用户解释数据来源时去读它。

### 第 4 步：写报告

严格用下面的结构。这个顺序是需求方定的，不要自己调整章节。

```markdown
# 电池健康检测报告

**结论：<一句话，含结论档位>**

## 一、电池健康概览

| 项目 | 数值 |
|---|---|
| 电脑型号 | |
| 电池型号 | |
| 设计容量 | |
| 当前充满容量 | |
| 当前健康度 | |
| 循环次数 | |

## 二、解读

**健康度** —— …
**循环次数** —— …
**衰减趋势** —— …

## 三、小建议

**使用建议**
- …

**置换建议**
- …

## 四、附件

- 容量衰减趋势图：<路径>（浏览器可直接打开）
- 官方完整电池报告：<路径>
```

写作要求：

- **概览表如实填写。** 字段取不到就写「系统未提供」，不要留空，也不要拿别的数字顶上。
  两种健康度口径不一致时，主表填系统口径，并在括号里补一句电量计实测值。
- **解读要给因果，不要复述数字。** "循环 75 次，健康度 88%"是概览已经说过的话；
  解读要回答的是"这个组合意味着什么、正常吗、接下来会怎样"。
- **不确定就说不确定。** 循环次数很少、只有单个实测点、两种口径分歧大——
  这些情况下给区间和条件，而不是给一个假装很确定的数字。虚假的确定性在服务场景里
  会直接变成后续的投诉。
- **"置换建议"这一节讲的是要不要换、什么时候换、换之前先做什么**，是技术判断，
  不是商品推荐。商品链接不放这里，放第 5 步的独立小节。

### 第 5 步：判断要不要推荐

**读 `references/lenovo-offers.md`**，按里面的触发条件判断。核心规则：

- 结论触发（健康度 < 80%、结论为建议更换/需要送修、循环数到寿命）**或**
  用户明确表达了换电池/续航/保修方面的意向；
- **并且**机型与试点商品适配。

两侧都满足才推，推荐单独成节放在报告最后并标明是服务推荐。**任一侧不满足就整节省略**，
报告到「附件」为止干净收尾。

试点期只有两个商品，覆盖机型很窄（拯救者 R/Y7000P 2023-2024 款电池、ThinkPad X/T/P/neo/Z
电池延保）。**非联想设备不要推商品**——推一块装不上的电池是负收益。

未触发时不要留"如有需要可以…"这类悬着的广告尾巴。把这句话省下来，
等用户后续真的问起来再推，那时候的转化率和体验都更好。

### 第 6 步：交付文件

报告正文直接输出。趋势图和官方报告用文件发送能力交给用户（有 `SendUserFile` 就用它，
趋势图设为 `render` 让用户直接看到），没有就把绝对路径写清楚。

---

## 目录结构

```
battery-health-check/
├── SKILL.md                        本文件：流程与报告格式
├── scripts/
│   ├── collect_macos.sh            macOS 采集（零依赖，只用系统自带命令）
│   ├── collect_windows.ps1         Windows 采集（powercfg + WMI）
│   └── render_trend.py             趋势图渲染（只用标准库）
└── references/
    ├── interpretation.md           判读规则：分级、速率公式、异常信号、结论四档
    ├── lenovo-offers.md            推荐策略：纪律、触发条件、试点商品、服务入口
    └── platform-notes.md           平台数据源、字段口径、已知坑
```

**什么时候读哪个：**

| 场景 | 读这个 |
|---|---|
| 要下健康度/趋势结论 | `references/interpretation.md`（第 3 步必读） |
| 要判断是否推荐、推什么 | `references/lenovo-offers.md`（第 5 步必读） |
| 字段缺失、数值可疑、要解释数据来源 | `references/platform-notes.md` |

---

## 反复运行会越来越准

采集脚本每次运行都会往 `~/.battery-health-check/history.tsv` 追加一条快照（每天最多一条）。
macOS 上系统不保存历史容量记录，所以首次检测的趋势只能靠模型推算；
攒够 3 个点、跨度超过两周之后，趋势图会自动切换成基于真实历史的日期轴曲线。

如果用户是回访或复检，可以主动提一句这个——让他知道多测几次是有意义的，
这本身也是把客户留在服务体系里的一个理由。