Helionyx

Helionyx

与 AI 助手对话，即可规划混合能源系统容量。 Helionyx 是一个开源的 Model Context Protocol（MCP）服务，可为太阳能光伏、风能、电池储能、柴油 发电机和并网系统规划容量。它采用经典的技术经济工作流：

1. 对每个候选设计进行全年逐小时模拟；
2. 淘汰不符合约束条件的设计；
3. 按净现值成本（NPC）对其余方案排名，同时提供投资回收期、平准化能源成本（LCOE）、电费和排放数据。

助手绝不会凭空捏造数据。它会询问范围界定问题，调用确定性工具并解释结果；每个数值都来自带有运行 ID 的求解器运行，任何人都可以复现。可将其用于预可行性研究、客户方案、农村电气化规划、教学以及与其他工具交叉验证。

Helionyx 的优势

• 有据可依的回答： 每个数值都由求解器生成；助手只负责解释。
• 完整方法： 逐小时调度（负载跟踪、循环充电、分时电价电网策略）、全生命周期经济性、支持分时电价、需量电费和上网方案的电价，以及电网停电情况。
• 不止于单一答案： 敏感性分析网格、成本、CO₂ 排放和可靠性之间的帕累托权衡，以及结合分阶段扩容的多年负载增长分析。
• 交叉验证： 使用同一情景与 REopt、MicroGridsPy 和 SAMA 进行比较。
• 开放且本地运行： Apache-2.0 许可，可在你的设备上运行，借助内置数据离线工作，并可导出 HOMER 就绪的时间序列和 Excel 报告。

开始使用

选择你使用 AI 工具的方式。每种方式大约只需一分钟。

客户端	安装方式
Claude Code	claude mcp add helionyx -- uvx helionyx serve
Claude Desktop	从最新发行版下载 helionyx-…-claude-desktop.mcpb 并打开
Smithery	smithery.ai/servers/gitdevjay/helionyx
任意 MCP 客户端（stdio）	命令 uvx，参数 helionyx serve（需要 uv）
Python	pip install helionyx，然后运行 helionyx serve

然后可以这样提问：

为尼甘布一家有 60 间客房的酒店规划一套光伏和电池系统，采用 CEB 酒店电价。我们有 大约 1,200 m² 可用屋顶面积。

快速入门指南将带你在不到十分钟内完成首次研究。

Helionyx 的查找位置

位置	链接
源代码和发布版本	github.com/Jayzilva/helionyx · 发布版本
PyPI	pypi.org/project/helionyx
Smithery	smithery.ai/servers/gitdevjay/helionyx
官方 MCP 注册表	io.github.Jayzilva/helionyx（注册表条目，JSON）

数据和准确性

Helionyx 内置斯里兰卡国家数据包（lk）：CEB 和 LECO 的电价结构与上网方案、按 Asia/Colombo 时间对齐的天气数据、斯里兰卡电网停电模式，以及建筑负荷特征。引擎本身与国家无关；新国家通过数据包添加（数据包指南）。

lk 数据包中的电价、组件成本、燃料价格、折现率和排放因子均为未经验证的占位值。 在数据验证之前，请使用结果来了解工具和比较选项，不要将其用于实际决策。validate_scenario 会针对每个未经验证的电价发出警告 HNX-W001。请参阅免责声明。

发布版本和变更记录列于更新日志。支持 Microsoft Entra ID 登录的托管模式和 OpenTelemetry 监控正在为 1.0 版本开发中。

架构

flowchart LR
    U([User]) <--> C["MCP client<br/>Claude Code · Claude Desktop<br/>Copilot Studio · custom agent"]
    C <-->|"stdio or<br/>Streamable HTTP"| S

    subgraph H["Helionyx (local-first, deterministic)"]
        S["MCP server<br/>22 tools · 9 resources · 6 prompts"]
        S --> SV["Services<br/>scenario · run · sensitivity · results · export"]
        SV --> K["Engine<br/>Numba dispatch kernel · pvlib · economics · billing"]
        SV --> ST[("SQLite metadata<br/>Parquet artefacts")]
        SV --> P["Country packs<br/>tariffs · components · archetypes"]
    end

    SV -.->|"HTTPS, cached"| W["NASA POWER · PVGIS"]
    SV -.->|"cross-check"| R["REopt v3 API"]
    SV -.->|"JSON subprocess"| X["helionyx-microgridspy (EUPL)<br/>helionyx-sama (AGPL)"]

服务不会调用大模型。Copyleft 求解器作为独立进程运行，因此核心部分保持 Apache-2.0 许可。

一段容量规划对话

sequenceDiagram
    autonumber
    actor User
    participant AI as AI assistant
    participant HX as Helionyx tools
    User->>AI: "Size PV and a battery for my 60-room hotel in Negombo"
    AI->>HX: create_site, fetch_resource, synthesize_load
    AI->>HX: list_tariffs, compute_bill (baseline)
    AI->>HX: create_scenario, validate_scenario
    HX-->>AI: assumptions and warnings
    AI->>User: confirm assumptions?
    User->>AI: yes
    AI->>HX: run_optimization → get_job_status
    AI->>HX: get_results, explain_run, get_monthly_summary
    HX-->>AI: ranked designs, NPC, bills, run ID
    AI->>User: top three designs, every number cited to the run

求解器

求解器	方法	适用场景	许可和安装
native	全枚举，按 8,760 小时进行调度	默认选项；搜索空间中的精确最优解	内置
heuristic	带种子的多起点模式搜索	超过枚举上限的空间：最多 5,000 万个候选项，在 50 到 50,000 次评估的预算内采样（默认 4,000 次）	内置
reopt	具有完美预见的 MILP（NREL REopt v3）	交叉验证并网设计	需要 API 密钥；负荷数据会离开本机
microgridspy	使用 HiGHS 的 LP	交叉验证离网设计	helionyx-microgridspy，EUPL-1.2
sama	粒子群	交叉验证离网设计	helionyx-sama，AGPL-3.0

compare_runs 会并排展示结果。多年期场景仅使用 native 和 heuristic 运行。

多年分析

在场景中添加 multi_year，即可增加负荷并搜索分阶段投资方案：

multi_year:
  load_growth_rate: 0.03        # year y load = year-1 load × 1.03^(y−1)
  sample_every_years: 5         # plus each stage boundary and the last year
  expansion:
    - year: 10
      pv_add_kwp: [0, 50, 100]
      bess_add_kwh: [0, 150]

扩建规模会成为额外的搜索维度。各阶段资本支出会在对应年份计入现金流，并计算各自的更换成本和残值；可靠性约束必须在每个采样年份均得到满足。每个候选项都会在 multi_year.years 下报告其采样年份。请参阅方法说明（决策 D20）。

功能

• **资源数据：**来自 NASA POWER（以及覆盖区域内的 PVGIS）的每小时 GHI、温度和风力数据，支持 CSV 导入、磁盘缓存、离线模式、UTC → 本地民用时间对齐、移除闰日和填补数据缺口。内置斯里兰卡三个站点的 NASA POWER 2023 年数据，因此参考案例可离线运行。
• **负载曲线：**11 种合成典型负载，支持带随机种子的随机变化、按 12 个月账单校准、复合负载以及实测负载导入（15/30/60 分钟）。
• **费率与账单：**版本化 YAML 费率，支持固定、分段和 TOU 电量费用、固定费用、需量费用和最低费用、附加费，以及净计量、净结算和净计量加上电量上网方案。
• **场景构建器：**采用国家配置包中的默认值，提供完整的假设审计（记录每个值的来源、出处和日期）、校验规则、SHA-256 场景哈希、版本管理和 YAML 往返转换。支持定时和随机电网停电。
• **仿真与优化：**使用 Numba 的 8,760 小时调度内核（通过 pvlib 计算 PV、风力功率曲线、理想化电池、支持负载跟随或循环充电的柴油发电机、并网 TOU 策略）、并行枚举搜索、HOMER 风格经济性分析（NPC、LCOE、设备更换、残值、回收期、IRR）和排放分析。
• **搜索：**支持完整枚举，或针对最多 5,000 万个候选方案的带种子启发式模式搜索；生成 NPC、CO₂ 和容量短缺的帕累托前沿。
• **多年分析：**支持负载逐年增长和最多三个容量扩展阶段，并与初始系统一同搜索，按年计算成本。
• **敏感性分析：**支持单变量扫描和带重新优化的双变量网格，为每种情况确定最优架构并计算 NPC 弹性。
• **有依据的说明：**提供结构化成本明细、成本驱动因素、约束瓶颈、调度统计数据和对比结果，并为每项结果注明出处和免责声明。
• **导出：**可导入 HOMER 的序列及参数表、Markdown 和 Excel 报告、每小时时间序列和场景 YAML。
• 交叉校验求解器通过 compare_runs 进行对比：REopt v3（需要 API 密钥），以及作为单独授权附加包的 MicroGridsPy 和 SAMA（参见 docs/adapters.md）。
• **HOMER 对等性工具包：**协议、结果模板和 helionyx parity compare。
• 用于引导式工作流的 Claude 技能和 MCP 提示词，以及依据核查器。

从源代码安装

用于开发（Python 3.11–3.13）：

git clone https://github.com/Jayzilva/helionyx.git
cd helionyx
uv venv
uv pip install -e ".[dev]"      # or: python -m venv .venv, then pip install -e ".[dev]"

有关提交拉取请求前要运行的检查，请参见 CONTRIBUTING。

命令行快速入门

从命令行运行参考案例（可离线运行）：

helionyx run reference_cases/rc2_hotel_negombo.yaml

该命令会为尼甘布一座拥有 60 间客房的酒店配置 PV 和电池，采用 CEB 酒店 TOU 费率，并打印 NPC 最低的五种设计及仅使用电网的基准方案。首次运行时，Numba 编译调度内核需要稍长时间。

完整操作指南请参见 docs/quickstart.md。

连接到 AI 助手

Claude Code

claude mcp add helionyx -- uvx helionyx serve

Claude Desktop

从最新版本下载 .mcpb 捆绑包并打开；Claude Desktop 会安装 Helionyx，并询问是否配置可选设置（工作区文件夹、离线模式、 REopt API 密钥）。或者，将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "helionyx": {
      "command": "uvx",
      "args": ["helionyx", "serve"]
    }
  }
}

Streamable HTTP（仅用于本地测试）

helionyx serve --transport http --port 8080

这会在 http://127.0.0.1:8080/mcp 提供 MCP 服务，并在 /healthz 提供健康检查。设置 HNX_API_KEY 以要求提供 Authorization: Bearer <key>（开发级别的保护；CLI 不允许在未设置该密钥时绑定到非本地地址）。OAuth 2.1 与 Microsoft Entra ID 将随 v1.0 的托管模式推出。

Claude skill

复制该 skill，让 Claude 遵循 Helionyx 工作流和依据规则：

cp -r skills/helionyx ~/.claude/skills/

不支持 skill 的客户端可以改用下方列出的 MCP 提示词。请参阅 docs/skill-guide.md。

MCP 工具

#	工具	用途
1	create_site	注册站点（位置、时区、国家包）
2	fetch_resource	从 NASA POWER 或 PVGIS 获取按当地时间对齐的逐小时 GHI、温度和风速
3	import_timeseries	从 CSV 导入实测负荷或资源序列；将 4 周或更长时间的负荷数据延展至一年
4	synthesize_load	根据原型构建负荷，可选择依据月度账单进行校准
5	list_tariffs	浏览费率包
6	get_tariff	费率、电价时段、上网电价方案和过时警告
7	compute_bill	计算负荷的基准账单，或根据购电／上网电量序列计算账单
8	list_components	浏览组件库
9	create_scenario	将所有输入和搜索空间组合成一个场景
10	validate_scenario	错误、警告和完整的假设审计
11	run_optimization	启动异步任务：native（枚举）、heuristic、reopt、microgridspy 或 sama
12	get_job_status	查询任务（状态、进度、预计时间、运行 ID）
13	cancel_job	取消任务
14	get_results	排名后的设计、基准方案、搜索方法、来源信息和免责声明
14b	get_pareto_front	按 NPC、CO₂ 和容量短缺量展示非支配设计
15	explain_run	对某项设计进行结构化说明
16	get_monthly_summary	改造前后的月度能量流和账单
17	run_sensitivity	单变量扫描或双变量网格，并重新优化（异步）
18	get_sensitivity_results	各取值对应的最优设计及 NPC 弹性
19	compare_runs	并排比较多次运行（例如 native 与 REopt）
20	export_homer_csv	可导入 HOMER 的序列和参数表
21	export_report	以 Markdown 或 Excel 格式生成客户端报告

run_optimization、run_sensitivity 和 get_job_status 接受 wait_seconds（0–20）。 设为 0 时会立即返回；否则会等待并发送进度通知。

资源

URI	内容
hnx://packs/{country}/tariffs/{tariff_id}	费率定义（JSON）
hnx://packs/{country}/components/{type}	组件库条目（JSON）
hnx://packs/{country}/archetypes/{archetype}	负荷原型定义（JSON）
hnx://datasets/{dataset_id}.csv	逐小时资源或负荷序列
hnx://scenarios/{scenario_id}	规范化解析后的场景（JSON）
hnx://runs/{run_id}/results.csv	包含每个候选方案的容量、指标和可行性
hnx://runs/{run_id}/candidates/{rank}/timeseries.csv	候选方案的逐小时能量流
hnx://runs/{run_id}/report.md	生成的报告
hnx://docs/methodology	方程及与 HOMER 的差异说明

提示词

提示词	用途
size_cni_rooftop_tou	TOU 费率下的工商业屋顶光伏 + 电池系统 sizing
size_offgrid_village	离网村庄微电网
diesel_replacement_island	混合改造现有柴油系统
explain_for_client	面向技术或管理层受众的、有依据的说明
homer_crosscheck	引导导出至 HOMER Pro，并提供对比检查清单
teach_me	通过小型示例运行进行辅导

命令行界面

命令	用途
helionyx serve [--transport stdio|http] [--host] [--port]	启动 MCP 服务
helionyx run <study.yaml> [--solver native] [--top 5] [--sort-by npc]	运行研究或场景文件
helionyx results <run_id> [--top 10]	打印结果
helionyx export homer <scenario_id> <dir>	写入 HOMER 文件
helionyx export report <run_id> [--format md] [--output path]	写入报告
helionyx pack validate <path>	验证数据包
helionyx pack build <path> <out_dir>	构建发布归档和校验和清单（维护者）
helionyx pack update [--country lk] [--manifest URL]	安装更新的、经过校验和验证的数据包发布版本
helionyx parity compare <homer.csv> [--output report.md]	比较 HOMER Pro 与 Helionyx 在 RC-1…RC-3 上的结果
helionyx eval grounding <transcripts_dir> [--threshold 0.95]	运行事实依据检查器
helionyx version	打印版本

配置

复制 .env.example，或设置以下环境变量：

变量	默认值	含义
HNX_WORKSPACE	~/.helionyx	数据库、构件、缓存和导出的工作区。不接受此目录之外的文件路径。
HNX_OFFLINE	0	1 表示仅使用缓存和内置数据；不进行网络调用
HNX_MAX_JOBS	2	每位用户可同时运行的最大作业数
HNX_JOB_TIMEOUT_S	900	作业时限，单位为秒
HNX_REOPT_API_KEY	—	REopt API 密钥（developer.nlr.gov）
HNX_REOPT_FIXTURE	—	重放记录的 REopt 响应，而不是调用 API（测试用）
HNX_REOPT_URL	https://developer.nlr.gov/api/reopt/stable	REopt 基础 URL
HNX_LOG_LEVEL	INFO	日志级别
HNX_API_KEY	—	HTTP 模式所需的 Bearer 密钥（仅用于开发）；绑定到非本地地址时必需
HNX_MICROGRIDSPY_CMD	helionyx-microgridspy	MicroGridsPy 适配器包的命令
HNX_SAMA_CMD	helionyx-sama	SAMA 适配器包的命令

仓库布局

src/helionyx/
  api/            MCP server, CLI, Streamable HTTP host, output schemas
  services/       site/resource, load, tariff, scenario, run, sensitivity, results, export, study
  core/           Pydantic models, engine (PV, wind, dispatch kernel, outages), economics, billing
  adapters/       solver adapter interface and REopt v3 adapter
  infra/          settings, SQLite store, Parquet artefact store, HTTP cache, jobs, pack loader
  packs/lk/       Sri Lanka country pack (tariffs, components, archetypes, emissions, defaults, samples)
  templates/      report and HOMER parameter templates, methodology
packages/         separately licensed solver adapters (helionyx-microgridspy, helionyx-sama)
skills/helionyx/  Claude skill
reference_cases/  RC-1 to RC-3 study files
evals/grounding/  grounding evaluation prompt set
scripts/          maintainer scripts (refresh bundled samples)
tests/            unit, property, contract and regression tests
docs/             quickstart, methodology, data-pack guide, skill guide, solver adapters, assets/ (graphics)

文档

• 快速入门
• 方法论
• 数据包指南
• 技能指南
• 求解器适配器
• 发布版本
• 参与贡献 · 变更日志

许可证

• 代码：Apache License 2.0。
• **数据包：**CC BY 4.0，须注明每条记录的原始来源。
• Copyleft 求解器作为独立包提供，并以子进程方式运行：helionyx-microgridspy （EUPL-1.2）和 helionyx-sama（AGPL-3.0）。核心程序不会导入它们。

免责声明

Helionyx 的结果是预可行性估算，基于简化模型、合成数据或用户提供的数据，以及过时且未经验证的占位电价和成本假设。这些结果并非工程设计、可融资的发电量评估、财务建议或电网合规研究，也不能替代特许工程师的审查。本软件按“原样”提供，不提供任何保证，也不承担任何责任（Apache-2.0 §7–8）。Helionyx 是一个独立项目，与 HOMER Energy / UL Solutions、NREL、NASA、EC JRC、CEB、LECO 或 Anthropic 均无关联，也未获其认可；商标归其所有者所有。某些功能会将站点或负荷数据发送给第三方服务。使用前请阅读完整的免责声明。