EMHASS开发者指南:从环境搭建到贡献PR提交的完整流程

原创2026-11-01 22:32:541,834 阅读

EMHASS开发者指南:从环境搭建到贡献PR提交的完整流程

EMHASS(Energy Management for Home Assistant)是一个为 Home Assistant 提供家庭能源优化调度的 Python 模块,它通过线性规划求解光伏、电池与电价数据,输出每日能源优化计划。本篇 EMHASS 开发者指南将带你完整走一遍开发流程:Fork 仓库、三种环境搭建方式、本地运行与单元测试、新增参数的正确姿势,直到提交一个合格的 Pull Request。

EMHASS能源优化模式时序图:完美优化、日前优化与MPC优化的预测窗口示意

一、动手前:先看懂 EMHASS 的代码地图

EMHASS 采用标准 Python 项目布局,核心代码都在 src/emhass/ 目录中,理解分工后开发效率会高很多:

文件 职责
src/emhass/command_line.py 三种优化模式的入口与数据发布
src/emhass/optimization.py 核心:构建并求解线性规划问题
src/emhass/forecast.py 光伏/负荷/电价预测
src/emhass/web_server.py Web 服务与配置页面
src/emhass/utils.py 参数构建等工具函数
tests/ pytest 测试套件

EMHASS 提供三种优化模式:Perfect Optimization(完美预测回测)、Day-ahead Optimization(日前优化)和 Naive MPC(滚动模型预测控制),上图中展示了它们在时间轴上的预测窗口关系。开发新功能时,建议从 docs/study_cases/ 中的示例场景入手理解业务逻辑。

EMHASS光伏出力与家庭负荷功率曲线:用于理解优化问题的输入数据形态

二、环境搭建:三种方式任选其一

第 1 步:Fork 并克隆仓库

先用你喜欢的 Git 工具把 EMHASS Fork 到自己账户,再克隆到本地,并添加上游远程便于同步更新:

git clone https://gitcode.com/gh_mirrors/em/emhass
cd emhass
git remote add upstream https://gitcode.com/gh_mirrors/em/emhass

第 2 步(方式一):Python 虚拟环境(推荐新手)

项目要求 Python ≥ 3.11(见 pyproject.toml 的 requires-python 字段)。使用 uv 一条命令即可装好含测试依赖的开发环境:

uv sync --extra test
source .venv/bin/activate   # Windows 用 .venv\Scripts\activate.bat

接着设置路径环境变量,并复制 secrets_emhass(example).yaml.yaml) 为 secrets_emhass.yaml 填入自己的密钥。更多细节见 docs/develop.md。

第 3 步(方式二):VS Code Dev Container

用 VS Code 打开克隆后的 emhass 文件夹,选择"在 Dev Container 中打开",即可获得与生产 Docker 镜像几乎一致的环境:编辑代码后按 Ctrl+Shift+P 执行 EMHASS Install 任务重新编译,再用 Run and Debug 面板调试,体验最接近正式发布形态。

第 4 步(方式三):Docker 完整验证

如果你改动了构建相关代码,建议用 Docker 跑一次"生产级"验证:

docker build -t emhass/test .
docker run -it -p 5000:5000 --name emhass-test \
  -v ./options.json:/app/options.json emhass/test

⚠️ 两个常见坑:

  • 改代码后必须重新 build(卷挂载 -v 的文件除外)
  • ARM 设备构建报 TARGETARCH 错误时,手动指定架构:--build-arg TARGETARCH=armhf --build-arg os_version=raspbian

三、本地运行:验证你的改动

两种方式任选:

# 方式A:启动 Web 服务(浏览器访问 http://localhost:5000)
python3 ./src/emhass/web_server.py

# 方式B:命令行直接跑一次日前优化
emhass --action 'dayahead-optim' --config ./config.json \
  --root ./src/emhass --costfun 'profit' --data ./data

运行成功后,可在 data/ 目录看到 opt_res_latest.csv 等结果文件。下图是不同成本函数(cost / profit / selfcons)的总目标值对比柱状图,来自 scripts/optim_results_analysis.py 的结果可视化,方便你快速确认改动是否符合预期:

EMHASS优化结果成本函数对比柱状图:cost、profit与selfcons三种目标的总值

四、提交前必做:测试与代码规范

单元测试——在仓库根目录执行:

pytest

CI 会跑同一套测试,本地失败等于 CI 失败,等于浪费一轮 Review。

Lint 检查——项目用 ruff 做检查与格式化,建议安装 prek 本地钩子,与 CI 保持一致:

prek install        # 安装一次,之后提交自动触发
uvx ruff check .    # 手动检查

注意 prek.toml 中还有一个自动同步 openapi.json 的钩子:只要你修改了 src/emhass/static/data/param_definitions.json 或 API schema 文件,提交时会自动重新生成规范文件。

五、进阶任务:如何正确新增一个参数

这是 EMHASS 贡献中最容易踩坑的环节,完整四步流程见 docs/develop.md 的 "Adding a parameter" 章节:

  1. 登记参数类别:在 src/emhass/data/associations.csv 追加一行,让 build_params() 知道参数属于哪个配置类别;
  2. 设置默认值:在 src/emhass/data/config_defaults.json 中追加默认值(供无 GUI 的 Docker 部署回退使用);
  3. 更新 Web UI 定义:在 param_definitions.json 中追加 friendly_name、Description、input 等字段,配置页面会自动渲染出输入控件;
  4. 检查优化缓存键:若参数影响优化问题的数学结构,确认它会触发缓存失效。通常 plant_conf / optim_conf 的结构性参数已被哈希自动覆盖,无需重复添加字段,但要补一个"值变化则 key 变化"的测试。

下图是 Web 配置页中列表型参数的渲染效果(每个 deferrable load 一项),你的新参数也会以同样方式出现在这里:

EMHASS插件配置界面中可延迟负载列表参数的配置表单截图

🔍 小贴士:修改已有参数的默认值时,param_definitions.json 才是默认值的"事实来源",务必与 config_defaults.json 保持同步,否则 GUI 与无头部署会出现"静默默认值漂移"。

六、提交 PR:先 Issue 还是直接提?

EMHASS 的社区约定非常清晰(详见 CONTRIBUTING.md 与 docs/develop_ai_coders.md):

  • 纯文档 / 错别字 / 小于 10 行且不改变行为的小修复 → 直接提 PR
  • 行为变更、新功能、新参数 → 先开 Issue 讨论方向,再提 PR
  • 重构超过 50 行 → 先开 Issue

PR 前自检清单:

  • [ ] pytest tests/ 本地通过
  • [ ] uvx ruff check . 干净无告警
  • [ ] 一个 PR 只解决一个问题(scope 纪律)
  • [ ] PR 描述中链接对应 Issue,行为变更附上复现步骤
  • [ ] 提交信息使用 fix / feat / docs / chore 前缀

完成后把 commit push 到你的 Fork,向 master 分支发起 Pull Request 即可。🎉

参考资料

登录后查看全文
emhass