Cernion Energy Tools

Система микросервисных агентов для энергетических рынков

Модульная масштабируемая платформа микросервисов, построенная на Moleculer, для разработки приложений энергетического рынка с поддержкой ИИ (Google Gemini) и MCP (Model Context Protocol).

Функции

• 🚀 Фреймворк микросервисов Moleculer — быстрый, современный и мощный фреймворк для микросервисов

• 🌐 API Gateway — HTTP REST API с автоматической генерацией маршрутов

• 🤖 ИИ-агент — планировщик запросов на естественном языке на базе Google Gemini: опишите свою потребность в энергетических данных простым текстом, и агент автоматически создаст, выполнит и интерпретирует многошаговый план микросервисов

• 🏢 Внутренние источники данных — регистрация, вывод, кэширование и обнаружение внутренних наборов данных коммунальных служб (CSV, REST, GeoJSON, XLSX, DOCX, парсеры) наряду с публичными энергетическими инструментами

• 🧩 Исследовательское веб-приложение — встроенное одностраничное приложение по адресу /app для интерактивного тестирования ИИ-агента в браузере — отдельные инструменты не требуются

• 📥 Live CSV Export — каждый результат работы агента предоставляет параметризованную GET-конечную точку (/api/agent/session/:id/csv?param=value) для интеграции без настройки с инструментами автоматизации, такими как Microsoft Power Automate, Excel Power Query или задания cron

• 💾 Точки данных (Datapoints) — именованные, версионированные источники данных с мониторингом состояния на базе встроенной PouchDB. Превратите любую сессию агента в управляемую точку данных, отслеживайте историю обновлений и стабильность схемы, а также получайте «живые» данные в формате JSON или CSV через /api/datapoints. См. обзор состояния для дашборда всех зарегистрированных точек данных.

• 📸 Снимки (Snapshots) — зафиксируйте группу точек данных как единое целое с помощью хеширования происхождения SHA-256. Создавайте, проверяйте (обнаружение дрейфа), перечисляйте и удаляйте снимки через /api/datapoints/snapshot* (v0.13)

• 🌍 Геослой OSM — анализ инфраструктуры энергосети через OpenStreetMap/Overpass: проверка назначения VNB, близлежащая инфраструктура, инвентаризация подстанций и топология сети (v0.10)

• 🌐 Коннектор OEP — доступ только для чтения к Open Energy Platform (данные сценариев, ссылки NEP, исследовательские наборы данных) через /api/oep/* (v0.12)

• 🔌 Проверка подключения к сети — детерминированный 6-шаговый конвейер Netzanschluss (POST /api/grid-connection/validate): инвентаризация → дельта → мощность → бенчмарк EWK → решение Go/No-Go → аудиторский след. Без LLM — идентичные входные данные, идентичные результаты. Отчеты запечатаны снимками PouchDB для соответствия ст. 12 Закона ЕС об ИИ (v0.14)

• 🤝 Проверка совместного использования энергии — детерминированный 6-шаговый конвейер § 42c EnWG (POST /api/energy-sharing/validate): право на участие генератора/потребителя, проверка MaLo, проверка суммы долей, проверка DV. Регуляторный дедлайн: 01.06.2026 (v0.15)

• 📊 Аудит качества данных MaStR — 8-шаговый аудит качества портфеля (POST /api/mastr-quality/audit): полнота регистрации, правдоподобность мощности, связность NAP/MeLo, обнаружение дубликатов, выборочная проверка геоданных. Взвешенная оценка 0–100 по 5 измерениям (v0.17)

• ⚡ Аудит Redispatch Ex-Post — 7-шаговый аудит готовности к расчетам Redispatch 2.0 (POST /api/redispatch/audit): сборка портфеля (Weg A/B), проверки NAP/MeLo/DV, данные об ограничении мощности, оценка финансовых рисков (v0.18)

• 🗂️ API дашборда — агрегатор UI только для чтения с 4 составными конечными точками (GET /api/dashboard/*): обзор VNB, рыночный снимок, сводка качества, справочник кодов находок. Все восходящие вызовы выполняются параллельно через Promise.allSettled, с изящной деградацией и кэшем 5–15 минут (v0.19)

• 🧠 OEO / OEMetadata — аннотации Open Energy Ontology на всех 45+ REST-конечных точках, экспорт OEMetadata v2.0 с опциональной проверкой JSON Schema (v0.11.4–v0.12)

• 🔐 Происхождение данных — хеширование происхождения SHA-256 при каждом обновлении точки данных для соответствия ст. 12 Закона ЕС об ИИ, плюс журнал объяснимости для исправлений агента (v0.11.5)

• 🧹 Очиститель промптов — маскирование PII на уровне полей с белым списком энергетического домена перед отправкой данных внешним LLM (v0.11.5)

• 🔌 Поддержка MCP — интеграция SDK Model Context Protocol

• 📝 Документация OpenAPI — автоматическая документация API по адресу /api/docs

• 🧭 Поиск DSO/VNB — поиск/просмотр VNBdigital и разрешение BDEW → MaStR

• 🛠️ CLI-инструмент — интерфейс командной строки для вызова микросервисов

• 📦 Шаблоны сервисов — готовый к использованию шаблон скелета сервиса

• 🔄 Hot Reload — автоматическая перезагрузка сервисов во время разработки

• 🎯 Лучшие практики — 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 и прозрачность

• Pull-запросы и пуши в main запускают автоматические проверки качества (lint, сборка, пороги покрытия модулей, проверка интеграции, аудит OpenAPI, аудиты безопасности).

• Анализ безопасности непрерывно обеспечивается с помощью CodeQL.

• Теги версий (v*) запускают конвейер выпуска (release:check + сборка + GitHub Release).

• llm.txt проверяется при проверках выпуска и перегенерируется из файлов-источников истины через npm run generate:llm.

• В CI обслуживания синхронизация llm.txt проверяется строго при изменении CHANGELOG.md.

• Отчеты о покрытии загружаются и публично видны через 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 Gateway запустится по адресу 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

Исследовательское веб-приложение

Встроенное веб-приложение по адресу /app позволяет исследовать все микросервисы, используя естественный язык — без curl, без форм Swagger, без кодирования.

Рабочий процесс

1. Опишите свой вопрос — введите на простом английском или немецком, например: "Alle PV-Anlagen im Netz der Enercity in Hannover"

2. Просмотрите план — ИИ декомпозирует вопрос в пронумерованную последовательность вызовов микросервисов и покажет вам, какие именно сервисы будут вызваны и с какими параметрами.

3. Настройте параметры — конкретные значения, извлеченные из вашего запроса (даты, почтовые индексы, идентификаторы MeLo, имена операторов, …), появятся в виде предварительно заполненных редактируемых полей формы. Измените любое значение без повторной генерации плана.

4. Запустите и исследуйте — результаты появятся в сортируемой, фильтруемой таблице. Исходный JSON с каждого шага доступен для отладки.

5. Поделитесь или автоматизируйте — общая ссылка и ссылка на Live CSV генерируются автоматически (см. ниже).

Live CSV для автоматизации

Каждый завершенный анализ предоставляет параметризованную CSV-конечную точку:

GET /api/agent/session/<id>/csv?param1=value1&param2=value2

• Запрос перезапускается в реальном времени по отношению к реальным источникам данных каждый раз при вызове — данные никогда не устаревают.

• GET-параметры переопределяют сохраненные значения, поэтому одну и ту же ссылку сессии можно использовать повторно с разными датами, регионами или идентификаторами.

• Ссылка на CSV обновляется в реальном времени в 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 → Get file или источник данных Power Query Web на этот URL. Измените параметр startDate, чтобы получить другой отчетный период — повторный анализ не требуется.

Другие шаблоны автоматизации:

• Запланируйте задание cron / GitHub Action для ежедневной загрузки свежих CSV

• Подавайте напрямую в pandas read_csv(url) в блокноте Jupyter

• Используйте как источник данных в Grafana, Power BI или любом инструменте, принимающем URL CSV

Создание новых сервисов

Использование создателя сервисов

# 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 и отредактируйте: