EMHASS开发者指南:从环境搭建到贡献PR提交的完整流程
EMHASS开发者指南:从环境搭建到贡献PR提交的完整流程
EMHASS(Energy Management for Home Assistant)是一个为 Home Assistant 提供家庭能源优化调度的 Python 模块,它通过线性规划求解光伏、电池与电价数据,输出每日能源优化计划。本篇 EMHASS 开发者指南将带你完整走一遍开发流程:Fork 仓库、三种环境搭建方式、本地运行与单元测试、新增参数的正确姿势,直到提交一个合格的 Pull Request。
一、动手前:先看懂 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/ 中的示例场景入手理解业务逻辑。
二、环境搭建:三种方式任选其一
第 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 的结果可视化,方便你快速确认改动是否符合预期:
四、提交前必做:测试与代码规范
单元测试——在仓库根目录执行:
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" 章节:
- 登记参数类别:在 src/emhass/data/associations.csv 追加一行,让
build_params()知道参数属于哪个配置类别; - 设置默认值:在 src/emhass/data/config_defaults.json 中追加默认值(供无 GUI 的 Docker 部署回退使用);
- 更新 Web UI 定义:在
param_definitions.json中追加friendly_name、Description、input等字段,配置页面会自动渲染出输入控件; - 检查优化缓存键:若参数影响优化问题的数学结构,确认它会触发缓存失效。通常
plant_conf/optim_conf的结构性参数已被哈希自动覆盖,无需重复添加字段,但要补一个"值变化则 key 变化"的测试。
下图是 Web 配置页中列表型参数的渲染效果(每个 deferrable load 一项),你的新参数也会以同样方式出现在这里:
🔍 小贴士:修改已有参数的默认值时,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 即可。🎉
参考资料
- 开发主文档:docs/develop.md
- AI 编码代理规则:AGENTS.md(含五条"勿动"不变量,改动核心代码前必读)
- AI 辅助贡献者指南:docs/develop_ai_coders.md
- 场景示例库:docs/study_cases/
- 项目贡献须知:CONTRIBUTING.md



