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: EnergyAtIt MCP Server

文档

• CHANGELOG.md - 发行说明和重大变更

• MCP_TOOLS.md - MCP 工具参考

• 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 dev

API 网关默认将在 http://localhost:3000 启动。

使用 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 表单，无需编码。

工作流程

1. 描述您的问题 — 用简单的英语或德语输入，例如 "Alle PV-Anlagen im Netz der Enercity in Hannover"

2. 审查计划 — AI 将问题分解为编号的微服务调用序列，并向您准确展示将调用哪些服务以及使用哪些参数。

3. 调整参数 — 从您的查询中提取的具体值（日期、邮政编码、MeLo ID、运营商名称等）显示为预填充的可编辑表单字段。无需重新生成计划即可更改任何值。

4. 运行与探索 — 结果显示在可排序、可过滤的表格中。每一步的原始 JSON 都可用于调试。

5. 共享或自动化 — 自动生成可共享的 URL 和 实时 CSV 链接（见下文）。

用于自动化的实时 CSV

每次完成的分析都会公开一个参数化的 CSV 端点：

GET /api/agent/session/<id>/csv?param1=value1&param2=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/ 中。

手动创建服务

1. 复制骨架模板：

   cp templates/skeleton.service.js custom-services/my-service.service.js

2. 编辑服务 — 更改 name 属性，添加操作、事件和方法。

3. 重启服务：

   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 并编辑：

有关完整的操作选项（重试退避、断路器阈值、舱壁队列限制），请参阅 .env.example。

内部数据源 (v0.9)

v0.9 数据源层在 MCP 支持的公共能源工具旁边添加了第二个数据平面：内部公用事业和电网运营商数据。

服务

• datasource-registry — 用于源定义、缓存策略、数据字典、字典版本历史和模式推断草稿的 CRUD

• datasource-connector — 用于通过内置或自定义连接器读取异构源的插件运行时

• datasource-cache — 具有隐私意识的缓存行访问、状态检查、刷新、失效和 DSGVO 审计追踪

• datasource-discovery — 为代理和未来的逻辑构建器集成准备的 AI 就绪内部源描述符

内置连接器插件

• csv — 来自磁盘的定界文件，包括