electricity-bill

让 AI Agent 读懂你家的电表 —— 一个零常驻、纯 Python 的 WorkBuddy Skill

Query household electricity usage & cost from a PostgreSQL database. No daemon, no framework, pure Python.

用自然语言查询家庭电费：账户余额、月度账单、年度账单、逐日用电明细，以及按居民阶梯电价逐日结算的电费估算与可视化报告。

零常驻：不使用 MCP，不启动任何后台服务，脚本即用即走。

它能做什么

| 能力 | 脚本 | 说明 | |------|------|------| | 账户余额 / 欠费 | query_electricity.py | 取最新一条余额流水 | | 本月 / 本年用电量与电费 | query_electricity.py | 含峰 / 尖 / 平 / 谷分时段构成 | | 近 N 日用电明细 | query_electricity.py | 可指定天数 | | 逐日电费 + 可视化报告 | daily_report.py | 按居民阶梯电价逐日结算，产出自包含 HTML（含图表 + 明细表） |

两个脚本的分工：数据库里没有"每日电费"这一列，只有每日电量与分时段电量。query_electricity.py 用"最近出账月均价 × 电量"做粗估（实测偏差可达 28%）；daily_report.py 按真实电价结构逐日结算（实测偏差 0.33%）。要准确数字就用后者。

用于 AI Agent 时，说一句「这个月电费多少」「今天用了多少电」即可自动触发。

⚠️ 前置条件（重要）

本项目不包含任何数据，也不提供数据采集功能。使用前你需要自备：

一个 PostgreSQL 数据库，表结构需符合 references/schema.md 的定义。核心是 5 张表：users、balance_log、monthly_usage、yearly_usage、daily_usage （另有可选的 step_usage）。数据来源由你自己决定——本项目只读，不关心数据如何写入。数据采集可参考开源项目 sgcc_electricity，它需单独部署，用于拉取本户电费数据并写入上述表结构。
Python 3.10+（本项目自身只用标准库 + psycopg2）。
仅当使用 daily_report.py 时，需要四川地区居民阶梯电价参数匹配（见电价估算模型）；其它地区需自行替换 daily_report.py 顶部的电价常量。

若你不在四川、或你的电表不是"一户一表"居民电价，请勿直接套用 daily_report.py 的计价结果——模型参数具地域性。

安装

1. 放置 Skill 目录

| 系统 | 路径 | |------|------| | Windows | %USERPROFILE%\.workbuddy\skills\electricity-bill\ | | macOS / Linux | ~/.workbuddy/skills/electricity-bill/ |

若需团队共享，可放到项目的 .workbuddy/skills/ 下。

2. 准备 Python 环境

使用引导脚本自动创建隔离虚拟环境并安装 psycopg2-binary（幂等，可重复执行）：

python scripts/bootstrap.py

脚本会依次尝试：环境变量 ELECTRICITY_BASE_PYTHON 指定的解释器 → WorkBuddy 托管运行时 → 当前解释器。也可用环境变量 ELECTRICITY_VENV 自定义虚拟环境位置。

校验是否就绪（不安装）：

python scripts/bootstrap.py --check

脚本自身不硬编码任何机器特定路径，换环境无需改动代码。

3. 配置数据库连接

cp config.example.json config.json

然后编辑 config.json，填入你的连接串（见下一节）。

配置

本 Skill 自包含：所有连接信息集中在 skill 根目录的 config.json，不读取、不依赖任何外部文件或其它项目。

配置文件只有一个键：

{
  "dsn": "postgresql://用户名:口令@主机:5432/sgcc"
}

| 键 | 必填 | 作用 | |----|------|------| | dsn | 是 | PostgreSQL 连接串，格式 postgresql://用户名:口令@主机:端口/库名 |

连接串解析顺序

按以下优先级解析，命中即停：

命令行 --dsn
环境变量 SGCC_POSTGRES_URI
config.json 的 dsn ← 常规方式
--env-file 或环境变量 SGCC_ENV_FILE 指定的 .env 文件
config.json 的 env_files 数组（默认不用）
skill 目录下的 .env

没有内置兜底——代码内不含任何默认凭据。所有来源均失效时报 no_dsn（退出码 2）。

⚠️ 安全提示

config.json 含数据库口令，已被 .gitignore 拦截，切勿提交到公开仓库。仓库里只应存在 config.example.json（占位符版本）。

若 JSON 写坏，脚本不会静默放过——会返回 config_error 字段，指出第几行第几列出错。

重新生成模板（默认不覆盖已存在文件，加 --force 才覆盖）：

python scripts/query_electricity.py --init-config

使用

1. 基础查询

# 人类可读（对齐表格）
python scripts/query_electricity.py --format text

# 结构化 JSON（默认，便于程序消费）
python scripts/query_electricity.py

# 近 14 日明细
python scripts/query_electricity.py --days 14 --format text

# 指定历史月份 / 年份
python scripts/query_electricity.py --month 2026-07 --format text
python scripts/query_electricity.py --year 2026 --format text

| 参数 | 默认 | 说明 | |------|------|------| | --format | json | json / text | | --days | 7 | 近日明细条数 | | --month | 当月 | 账单月份 YYYY-MM | | --year | 本年 | 账单年份 YYYY | | --with-user | 关 | 额外返回户号与户名（见隐私设计） | | --show-dsn-source | 关 | 打印连接串来源（隐藏口令），仅排障用 | | --init-config / --force | 关 | 生成 / 覆盖配置模板 |

2. 月度日报与图表

python scripts/daily_report.py --month 2026-09 --out report.html
python scripts/daily_report.py --month 2026-09 --format json

产出：KPI 卡片（累计电量 / 电费、日均、谷电占比、余额、余额可用天数）+ 堆叠柱状图（峰 / 尖 / 平 / 谷）+ 电费折线 + 逐日明细表 + 计价口径说明。

HTML 为纯内联 SVG，无 CDN 依赖，离线可看，配色跟随系统深浅色。

3. 作为工具接入自己的 Agent

本质就是执行一条命令，任何语言均可：

import subprocess, json
out = subprocess.run(
    ["python", "scripts/query_electricity.py", "--format", "json"],
    capture_output=True, text=True, encoding="utf-8"
).stdout
data = json.loads(out)
print(data["balance"]["balance"])

电价估算模型（四川）

daily_report.py 内置四川居民"一户一表"阶梯电价模型，依据《四川省电网居民生活电价表》。关键结构：

| 阶梯 | 月用电量（7–9 月） | 月用电量（其它月份） | 高峰·平段（7:00–23:00） | 低谷（23:00–次日 7:00，丰水期） | |------|------------------|--------------------|----------------------|------------------------------| | 一档 | ≤ 260 kWh | ≤ 180 kWh | 0.5224 | 0.175 | | 二档 | 261–460 kWh | 181–280 kWh | 0.6224 | 0.275 | | 三档 | > 460 kWh | > 280 kWh | 0.8224 | 0.475 |

两条关键性质（模型的基础）：

峰段与平段同价，只有谷段享受优惠 → 数据库的 peak / tip / flat 三列在计价时合并为「非谷电量」。
每档的谷优惠幅度恒定：丰水期（6–10 月）恒为 0.3474，枯/平水期恒为 0.2689。于是可简化为：

电费 = Σ(各档电量 × 对应基础电价) − δ × 谷电量

精度：在唯一同时具备分时段电量与实收电费的样本上，模型预测与实际出账电费的偏差为 0.33%。同一月份改用"最近出账月均价"口径估算，结果偏高约 4.5%；谷电占比高的单日偏高可达 28%。

推导过程、验证数据与使用注意详见 references/tariff.md。

本模型为估算，非电网结算金额。电价政策会调整，使用前建议核对当年度的本地电价表。

隐私设计

默认情况下脚本不查询、不输出任何身份信息，只返回用电量与电费数据：

不返回户号 user_id、户名 user_name——users 表默认根本不参与查询（不是"查出后过滤"，而是压根不执行该 SQL）
不返回 dsn_source——数据库主机与路径属基础设施信息

仅在用户明确要求查看身份信息时才附加 --with-user。以下表述视为明确要求：

「我的户号 / 户名是什么」「查一下户主」「这个账户是谁的」

以下情形不得启用：

只问电费、余额、欠费、用电量、用电趋势
要求「分析用电情况」「生成账单卡片」「预估还能用多久」

其它安全基线：

脚本只读，不写入、不修改任何数据
代码内不含任何凭据、主机地址或外部绝对路径
驱动异常消息在输出前经 _scrub() 抹除 用户名:口令 段（保留主机名与库名以便排障）

数据库结构

完整字段定义、约束与常用 SQL 见 references/schema.md。五个核心表：

| 表 | 内容 | 关键说明 | |----|------|---------| | users | 户号 / 户名 / 手机号 | 身份信息来源，默认不查询 | | balance_log | 余额流水 | 取 ORDER BY as_of DESC LIMIT 1 为最新余额 | | monthly_usage | 月度账单 | month 是 varchar（YYYY-MM），不是 date | | yearly_usage | 年度账单 | 分时段四列可能全为 0（数据源未回传） | | daily_usage | 逐日用电 | 含分时段列；无电费列——这是引入 daily_report.py 的唯一原因 | | step_usage | 阶梯用量（可选） | 本 skill 未使用；需要"阶梯剩余额度"时可启用 |

已在代码中处理的口径细节：分时段四列之和可能略小于 total_usage（数据源舍入）。差额不摊回任何单一时段（否则会污染"峰"列，与电网月报口径不符），仅在计价时按 总电量 − 谷电量 计入非谷电量。

故障排查

| 现象 | 原因与处置 | |------|-----------| | missing_dependency | 缺少 psycopg2；执行 python scripts/bootstrap.py | | no_dsn | 未找到连接串；在 config.json 的 dsn 填入，或用 --init-config 重建模板 | | db_connect_failed | 数据库不可达或凭据错误；加 --show-dsn-source 查看目标库与来源 | | 结果含 config_error | config.json 的 JSON 写坏，该字段会指出第几行第几列 | | total_charge 为 null | 当月尚未出账，非故障 | | this_year.breakdown 全为 0 | 电网侧未回传分时段数据，属数据源限制 | | 某段落进入 errors 数组 | 该段查询失败，其余段落仍有效；核对 references/schema.md 的列名 |

退出码：0 成功（errors 可能非空）/ 2 未找到连接串 / 3 依赖缺失或连接失败。

项目结构

electricity-bill/
├── SKILL.md                  # AI Agent 的触发与操作说明
├── README.md                 # 本文档
├── LICENSE
├── config.example.json       # 配置模板（提交到仓库）
├── config.json               # 真实配置（.gitignore 已拦截，不提交）
├── requirements.txt
├── .gitignore
├── scripts/
│   ├── bootstrap.py          # 幂等环境引导
│   ├── query_electricity.py  # 余额 / 月账单 / 年账单 / 近日明细
│   └── daily_report.py       # 逐日电费结算 + 自包含 HTML 报告
└── references/
    ├── schema.md             # 库表结构与常用 SQL
    └── tariff.md             # 居民阶梯电价模型与验证

设计说明

零常驻：仅执行本地脚本，无后台进程、无端口占用。
脱离框架：不依赖 MCP / FastMCP，任何能执行命令的程序都能调用。
局部容错：单段查询失败不影响整体，错误记入 errors 数组，其余数据照常返回。
配置与代码分离：凭据只存在于 config.json，代码零硬编码。
自包含输出：报告为单文件 HTML（内联 SVG），无外部资源。
编码兼容：针对中文 Windows 做了 UTF-8 / GBK 双解码与 stdout 重定向。

免责声明

本项目只读，不采集、不上传任何数据。
daily_report.py 的电费为估算值，非电网结算金额；电价政策与阶梯界线可能随时调整，以电网正式账单为准。
本项目与国家电网、小米公司等任何企业均无关联。
使用本项目产生的任何后果由使用者自行承担。

electricity-bill

electricity-bill

目录

它能做什么

⚠️ 前置条件（重要）

安装

1. 放置 Skill 目录

2. 准备 Python 环境

3. 配置数据库连接

配置

连接串解析顺序

⚠️ 安全提示

使用

1. 基础查询

2. 月度日报与图表

3. 作为工具接入自己的 Agent

电价估算模型（四川）

隐私设计

数据库结构

故障排查

项目结构

设计说明

免责声明

许可证