Cernion Grid Intelligence
Cernion 能源工具
能源市场微服务代理系统
一个基于 Moleculer 构建的模块化、可扩展微服务平台,用于开发具有 AI 集成(Google Gemini)和 MCP(模型上下文协议)支持的能源市场应用程序。
功能特性
🚀 Moleculer 微服务框架 — 快速、现代且强大的微服务框架
🌐 API 网关 — 具有自动路由生成的 HTTP REST API
🤖 AI 代理 — 由 Google Gemini 驱动的自然语言查询规划器:用纯文本描述您的能源数据需求,代理会自动生成、执行并解释多步骤微服务计划
🏢 内部数据源 — 在公共能源工具之外,注册、推断、缓存并发现内部公用事业数据集(CSV、REST、GeoJSON、XLSX、DOCX、爬虫)
🧩 研究 Web 应用 — 内置于
/app的单页应用程序,用于 AI 代理的交互式浏览器测试 — 无需单独的工具📥 实时 CSV 导出 — 每个代理结果都公开一个参数化的 GET 端点 (
/api/agent/session/:id/csv?param=value),以便与 Microsoft Power Automate、Excel Power Query 或 cron 任务等自动化工具进行零配置集成💾 数据点 — 由嵌入式 PouchDB 支持的命名、版本化、健康监控数据源。将任何代理会话提升为托管数据点,跟踪刷新历史和模式稳定性,并通过
/api/datapoints以 JSON 或 CSV 格式检索实时数据。查看 健康概览 获取所有已注册数据点的仪表板。📸 快照 — 使用 SHA-256 来源哈希将一组数据点密封为一个一致的单元。通过
/api/datapoints/snapshot*创建、验证(漂移检测)、列出和删除快照 (v0.13)🌍 OSM 地理图层 — 通过 OpenStreetMap/Overpass 进行电网基础设施分析:VNB 分配验证、周边基础设施、变电站库存和电网拓扑 (v0.10)
🌐 OEP 连接器 — 通过
/api/oep/*对开放能源平台(场景数据、NEP 参考、研究数据集)的只读访问 (v0.12)🔌 并网验证 — 确定性的 6 步 Netzanschluss 流程 (
POST /api/grid-connection/validate):库存 → 增量 → 容量 → EWK 基准 → 通过/不通过决策 → 审计追踪。非 LLM — 相同的输入,相同的结论。报告使用 PouchDB 快照密封,以符合欧盟 AI 法案第 12 条的要求 (v0.14)🤝 能源共享验证 — 确定性的 6 步 § 42c EnWG 流程 (
POST /api/energy-sharing/validate):发电商/消费者资格、MaLo 验证、份额总和检查、DV 验证。监管截止日期:2026 年 6 月 1 日 (v0.15)📊 MaStR 数据质量审计 — 8 步投资组合质量审计 (
POST /api/mastr-quality/audit):注册完整性、容量合理性、NAP/MeLo 连接性、重复检测、地理抽查。跨 5 个维度进行 0–100 的加权评分 (v0.17)⚡ Redispatch 事后审计 — 7 步 Redispatch 2.0 结算准备情况审计 (
POST /api/redispatch/audit):投资组合组装 (Weg A/B)、NAP/MeLo/DV 检查、限电数据、财务风险评分 (v0.18)🗂️ 仪表板 API — 带有 4 个复合端点的只读 UI 聚合器 (
GET /api/dashboard/*):VNB 概览、市场快照、质量摘要、发现代码参考。所有上游调用通过Promise.allSettled并行执行,支持优雅降级,5–15 分钟缓存 (v0.19)🧠 OEO / OEMetadata — 所有 45+ 个 REST 端点上的开放能源本体注释,OEMetadata v2.0 导出,可选 JSON Schema 验证 (v0.11.4–v0.12)
🔐 数据来源 — 每个数据点刷新时进行 SHA-256 来源哈希处理,以符合欧盟 AI 法案第 12 条的要求,并提供代理修正的可解释性日志 (v0.11.5)
🧹 提示词清理器 — 在将数据发送到外部 LLM 之前,进行字段级 PII 屏蔽和能源领域白名单过滤 (v0.11.5)
🔌 MCP 支持 — 模型上下文协议 SDK 集成
📝 OpenAPI 文档 —
/api/docs处的自动 API 文档🧭 DSO/VNB 查询 — VNBdigital 搜索/查询和 BDEW → MaStR 解析
🛠️ CLI 工具 — 用于调用微服务的命令行界面
📦 服务模板 — 即用型骨架服务模板
🔄 热重载 — 开发期间自动重新加载服务
🎯 最佳实践 — ESLint、Prettier 和结构化的项目布局
Related MCP server: Energy Grid MCP Server
文档
CHANGELOG.md - 发行说明和重大变更
MCP_SERVICES.md - 微服务到工具的映射
BEARER_TOKEN_AUTHENTICATION.md - 身份验证指南
docs/BACKEND_CONTEXT.md - 后端架构参考(服务、PouchDB、发现代码、身份验证)
llm.txt - 生成的 LLM 上下文工件(架构 + 领域知识 + 食谱 + OpenAPI)
docs/ui-contracts/ - 前端 ↔ 后端 API 合约 (v0.20, 14 个文档)
docs/MAINTENANCE_MILESTONE_CHECKLIST.md - 里程碑前质量/安全门检查清单
SECURITY.md - 安全策略和披露
CODE_OF_CONDUCT.md - 社区准则
CI/CD 与透明度
对
main分支的拉取请求和推送会运行自动质量检查(lint、构建、单元覆盖率门控、集成发现健全性、OpenAPI 审计、安全审计)。安全分析通过 CodeQL 持续强制执行。
版本标签 (
v*) 会触发发布流水线 (release:check+ 构建 + GitHub Release)。llm.txt在发布检查中进行验证,并通过npm run generate:llm从事实来源文件重新生成。在维护 CI 中,当
CHANGELOG.md发生变化时,会严格检查llm.txt的同步情况。覆盖率报告通过 Codecov 上传并公开可见。
推荐的仓库设置:在
main上启用分支保护,并在合并前要求通过Maintenance CI+CodeQL检查。
快速入门
先决条件
Node.js 18+
npm 或 yarn
安装
# Clone the repository
git clone https://github.com/energychain/cernion-energy-tools.git
cd cernion-energy-tools
# Install dependencies
npm install
# Copy environment variables
cp .env.example .env
# Edit .env and add your API keys (see Configuration section)
nano .env运行服务
# Start all services
npm start
# Or use development mode with hot reload
npm run devAPI 网关默认将在 http://localhost:3000 启动。
URL | 描述 |
| 研究 Web 应用 — 用于交互式测试的 AI 代理 UI |
| Swagger UI — 完整的 OpenAPI 文档 |
| 原始 OpenAPI 规范 |
使用 CLI
# Call a microservice action
npm run cli -- skeleton.hello --name=John
# Health check
npm run cli -- skeleton.health
# Get help
npm run cli -- --help研究 Web 应用
内置于 /app 的 Web 应用程序允许您使用纯文本自然语言探索所有微服务 — 无需 curl,无需 Swagger 表单,无需编码。
工作流程
描述您的问题 — 用简单的英语或德语输入,例如 "Alle PV-Anlagen im Netz der Enercity in Hannover"
审查计划 — AI 将问题分解为编号的微服务调用序列,并向您准确展示将调用哪些服务以及使用哪些参数。
调整参数 — 从您的查询中提取的具体值(日期、邮政编码、MeLo ID、运营商名称等)显示为预填充的可编辑表单字段。无需重新生成计划即可更改任何值。
运行与探索 — 结果显示在可排序、可过滤的表格中。每一步的原始 JSON 都可用于调试。
共享或自动化 — 自动生成可共享的 URL 和 实时 CSV 链接(见下文)。
用于自动化的实时 CSV
每次完成的分析都会公开一个参数化的 CSV 端点:
GET /api/agent/session/<id>/csv?param1=value1¶m2=value2查询每次被调用时都会针对真实数据源实时重新运行 — 数据永不过期。
GET 参数会覆盖保存的值,因此相同的会话 URL 可以重复使用,并带有不同的日期、区域或标识符。
当您更改任何表单字段时,CSV URL 会在 UI 中实时更新。
Power Automate / Excel Power Query 示例:
http://10.0.0.8:3900/api/agent/session/2a70e478-90ce-4fa5-b996-6f98efdba7cf/csv?startDate=2026-03-01将 HTTP → 获取文件 操作或 Power Query Web 数据源指向此 URL。更改 startDate 参数以获取不同的报告期 — 无需重新分析。
其他自动化模式:
安排 cron 任务 / GitHub Action 每天拉取最新的 CSV
在 Jupyter Notebook 中直接输入 pandas
read_csv(url)用作 Grafana、Power BI 或任何接受 CSV URL 的工具中的数据源
创建新服务
使用服务创建器
# Create a new service interactively
npm run create
# Or specify a name directly
npm run create -- my-service这会从骨架模板在 custom-services/ 中创建一个新服务,并在 custom-tests/ 中生成相应的测试。
自定义服务仅限本地,并被 git 忽略。项目附带的核心服务位于 services/ 中。
手动创建服务
复制骨架模板:
cp templates/skeleton.service.js custom-services/my-service.service.js编辑服务 — 更改
name属性,添加操作、事件和方法。重启服务:
npm start
自定义服务与测试
自定义服务位于
custom-services/中,并在启动时加载。自定义测试位于
custom-tests/中,并从发布覆盖率中排除。在没有全局覆盖率阈值的情况下运行自定义测试:
npm run test:custom -- my-service.service.test.js
项目结构
cernion-energy-tools/
├── services/ # Core microservices (shipped with release)
│ ├── api.service.js # API Gateway + Swagger UI
│ ├── agent.service.js # AI agent — plan/execute/export
│ ├── assets.service.js # MaStR installation assets
│ ├── datapoint.service.js # Named datapoints + snapshots (v0.11–v0.13)
│ ├── osm-geo.service.js # OSM geo layer (v0.10)
│ ├── oep.service.js # Open Energy Platform (v0.12)
│ ├── datasource-registry.service.js
│ ├── datasource-connector.service.js
│ ├── datasource-cache.service.js
│ ├── datasource-discovery.service.js
│ ├── forecast.service.js
│ ├── gas-storage.service.js
│ ├── german-grid.service.js
│ ├── grid-operations.service.js
│ └── ... # See services/ for full list
├── src/
│ ├── app.html # Research Web App (single-page)
│ ├── connectors/ # Built-in datasource connector plugins
│ ├── mcp-client.js # Centralised MCP tool caller
│ ├── async-job-poller.js # Async job polling
│ ├── prompt-scrubber.js # PII masking for LLM prompts
│ ├── oeo-mappings.js # OEO class mappings (~150 entries)
│ ├── validation-findings.js # Grid connection finding constants (v0.14)
│ └── oemetadata-builder.js # OEMetadata v2.0 builder
├── custom-services/ # Local/custom services (git-ignored)
├── custom-connectors/ # Local/custom datasource plugins (git-ignored)
├── custom-tests/ # Local/custom tests (git-ignored)
├── templates/
│ └── skeleton.service.js
├── tests/ # Core test suite
├── scripts/ # Build / audit scripts
├── index.js # Main entry point
├── cli.js # CLI tool
├── create-service.js # Interactive service creator
├── moleculer.config.js # Moleculer configuration
├── .env.example # Environment variables template
└── package.json配置
环境变量
将 .env.example 复制到 .env 并编辑:
变量 | 默认值 | 描述 |
|
| API 网关端口 |
|
| 日志级别 ( |
| — | Google Gemini API 密钥(AI 代理必需) |
|
| Gemini 模型名称 |
| — | MCP 服务器 URL |
| — | Cernion MCP 令牌 (在此申请 或发送电子邮件至 dev@stromdao.com) |
| — | 用于服务隔离的 Moleculer 命名空间 |
| — | 消息传输器 (NATS, Redis, MQTT, …) |
|
| 代理请求超时(毫秒) |
|
| 启用代理级重试以处理可重试错误 |
|
| 启用断路器保护 |
|
| 启用舱壁并发保护 |
|
| 启用 Moleculer 指标收集 |
|
| 启用 Moleculer 追踪 |
|
| 启用详细的异步作业轮询器调试日志 |
|
| 轮询器调试有效负载片段的最大字符数 |
|
| 数据源定义的集合名称 |
|
| 缓存数据源行的集合名称 |
|
| 隐私/审计记录的集合名称 |
|
| 内置数据源连接器目录 |
|
| 自定义数据源连接器目录 |
|
| 用于模式推断的最大样本行数 |
|
| 爬虫连接器页面加载超时 |
|
| 数据源读取的默认隐私模式 |
|
| 用于 Netzanschluss 验证报告的 PouchDB 路径 (v0.14) |
有关完整的操作选项(重试退避、断路器阈值、舱壁队列限制),请参阅 .env.example。
内部数据源 (v0.9)
v0.9 数据源层在 MCP 支持的公共能源工具旁边添加了第二个数据平面:内部公用事业和电网运营商数据。
服务
datasource-registry— 用于源定义、缓存策略、数据字典、字典版本历史和模式推断草稿的 CRUDdatasource-connector— 用于通过内置或自定义连接器读取异构源的插件运行时datasource-cache— 具有隐私意识的缓存行访问、状态检查、刷新、失效和 DSGVO 审计追踪datasource-discovery— 为代理和未来的逻辑构建器集成准备的 AI 就绪内部源描述符
内置连接器插件
csv— 来自磁盘的定界文件,包括
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
Live US power market prices, load, generation, weather and permits for AI agents.
Real-time electricity price signals for AI agents. Spot prices, cheapest hours, and contract recommendations. 31 countries across Europe and Oceania. No authentication required.
Real-time electricity prices for AI agents. 40+ countries, 100+ zones. No auth required.
Related MCP Servers
- AlicenseBqualityDmaintenanceConnects AI agents to energy infrastructure with 30+ tools for managing sites, assets, dispatch, settlements, compliance, and carbon tracking.3450 npm1MIT
- AlicenseAqualityDmaintenanceProvides real-time electricity grid data including CO2 intensity, power mix, and wholesale prices, plus optimal green time windows for energy-intensive AI tasks. Supports UK, Germany, and global regions with optional API keys.9MIT

Voltcast MCP Serverofficial
AlicenseNot gradedqualityDmaintenanceEnables access to European electricity data including day-ahead prices, probabilistic forecasts, carbon intensity, and cheapest-window optimization for 43 bidding zones.MIT- FlicenseNot gradedqualityDmaintenanceProvides real-time electricity prices, cheapest hours, and contract comparison for 40+ countries, enabling AI agents to make energy-aware decisions.5-