内容
# 费率手册
适用于电气化家庭的开放式费率引擎 — 一个开放许可的美国电费数据库，一个开源费率计算引擎，以及一个MCP服务器，因此任何应用程序、设备或代理都可以回答“这千瓦时电费我多少钱，什么时候充电合适？”
[](LICENSE)
[](LICENSE-DATA)
[](https://www.python.org/)
[](https://github.com/cbetz/ratebook/actions/workflows/ci.yml)
<sub>↑ 浏览器中运行的实时引擎。自己试试：[`demo/demo.html`](demo/demo.html).</sub>
> **状态：预发布。** 目前有效的内容：一个确定性的费率引擎（Python + TypeScript端口按字节保持一致），与NREL的PySAM进行交叉验证，并显示在提供其组件的情况下可以重现实际账单总额；一个LLM管道，从公用事业PDF中提取费率结构；一个MCP服务器；以及一个Home Assistant集成。仍在进行中的工作：广泛的公用事业覆盖、自动化更新以及可复制的公共准确性记分卡。参见[`docs/ROADMAP.md`](docs/ROADMAP.md)。
## 快速开始
引擎没有I/O，也不需要下载数据 — 几行代码即可估算费率：
```sh
git clone https://github.com/cbetz/ratebook && cd ratebook
uv sync
uv run python quickstart.py # 或将以下代码粘贴到 `uv run python` 中
```
```python
from datetime import date
from decimal import Decimal
from ratebook import (
Tariff, TariffIdentity, Sector, EnergyRateStructure, EnergyPeriod, EnergyTier,
Schedule, FixedCharge, FixedChargeUnit, Usage, BillingWindow, estimate_bill,
)
# 一个简单的住宅费率：$0.10276/kWh + $11.30/月（PECO Rate R 分销）。
no_tou = tuple(tuple(0 for _ in range(24)) for _ in range(12)) # 12个月 × 24小时，一个时段
tariff = Tariff(
energy=EnergyRateStructure(periods=(EnergyPeriod(tiers=(EnergyTier(rate=Decimal("0.10276")),)),)),
schedule=Schedule(weekday=no_tou, weekend=no_tou),
identity=TariffIdentity(plan_code="R", plan_name="示例固定住宅费率", sector=Sector.RESIDENTIAL),
fixed_charges=(FixedCharge(Decimal("11.30"), FixedChargeUnit.PER_MONTH),),
)
bill = estimate_bill(tariff, Usage.aggregate(1244), BillingWindow(date(2026, 4, 28), 30))
print(f"ok={bill.ok} total=${bill.total}") # ok=True total=$139.13344 → 1244 kWh × $0.10276 + $11.30
```
实际费率通过`Tariff.from_json(...)`循环转换为JSON。要使用语料库数据，请加载URDB种子集（`uv run ratebook-data urdb`）或运行MCP服务器（`uv run ratebook-mcp`），并询问代理`lookup_tariff` / `estimate_bill` / `compare_plans` / `best_charge_window`。
## 开发
Python 3.12+，[uv](https://docs.astral.sh/uv/) 工作区，包含以下软件包：
`packages/ratebook`（费率引擎），`packages/ratebook-data`（数据工厂），
`packages/ratebook-mcp`（MCP服务器），`packages/ratebook-ts`（TypeScript引擎端口 —
pnpm + vitest，与Python引擎通过共享的JSON测试向量保持一致），以及
`packages/ratebook-homeassistant`（Home Assistant自定义集成：电价 +
最便宜的充电窗口传感器）。
```sh
uv sync # 安装所有工作区软件包 + 开发工具
uv run pytest # Python测试
uv run ruff check . # 校验
uv run ratebook-data urdb # 下载URDB批量CSV → data/raw/，加载到data/ratebook.duckdb
uv run ratebook-mcp # 运行MCP服务器（标准输入/输出）
pnpm -C packages/ratebook-ts install && pnpm -C packages/ratebook-ts test # TypeScript引擎 + 向量
```
PySAM交叉验证在CI中针对已提交的费率固定运行（`uv sync --group validation`安装预言机）。MCP工具测试还需要构建的语料库，并在本地运行（`uv run ratebook-data urdb`）；否则跳过。两个引擎必须永远不会
发散：两者都重现`packages/ratebook/tests/vectors/v0_bills.json` 按字节。重新生成
它与`uv run python packages/ratebook/tests/generate_vectors.py`。
参见[`CONTRIBUTING.md`](CONTRIBUTING.md) — 最有价值的贡献是**费率纠正**（报告错误的费率或过时的费率及其来源PDF）。
## 许可证
代码在[Apache-2.0](LICENSE)下获得许可。发布的数据库在[CC0-1.0](LICENSE-DATA)下奉献给公共领域。种子语料库源自
[美国公用事业费率数据库](https://apps.openei.org/USURDB/)（CC0）。
