Cernion Energy Tools MCP

Cernion Energy Tools

面向 Stadtwerke、DSO 和能源服务团队的 API 优先型 Agentic 能源运营层。 Cernion 将确定性的能源领域服务、精选能力路由、证据档案、VDMI 角色逻辑、HITL 边界和只读集成界面整合起来， 支持 REST、Sidecar、Microsoft Copilot、n8n、OpenWebUI 和 OpenClaw。

这个代码仓库是什么

Cernion Energy Tools 是 cernion.de 背后的后端运行时： 这是一个基于 Node.js/Moleculer 的服务平台，面向能源领域自动化、决策支持和 Agentic 流程编排。

它并非只是能源 API 的聊天前端。当前平台包含：

• services/ 中的 138 个 Moleculer 服务
• openapi-export.json 中的 1007 个 OpenAPI 路径
• tests/ 下的 304 个 JavaScript 测试文件
• 经过精选的 Copilot、Sidecar、OpenWebUI、n8n 和 OpenClaw 集成界面，仅开放后端中受治理的子集
• 用于路由、回执、档案、HITL、证据、重新验证和可观测性的 Agentic 运行时组件
• 持久化项目文件，支持租户范围内的数据导入、结构化表格、基于证据的关系图，以及带可见来源选择的版本化路由清单；API、来源信息、限制和清理说明请参阅 Projektakte

当前软件包/OpenAPI 版本：0.99.0

公开定位

Cernion 不会让聊天来做决定。该平台会梳理目标、可用数据、服务链、证据、缺口、风险和下一个安全关口。产出不是黑箱答案，而是可纳入档案的状态或决策就绪度视图，服务于 Stadtwerke、配电系统运营商和能源服务团队。

Cernion Energy Tools 并非自动合同决策、并网承诺、设备控制系统、MaKo 执行系统、计费/结算系统或资费变更机器。适用的集成范围包括 ask、plan、evidence、capability lookup 和 read-only status。类似写入或会产生重大影响的步骤会保持在 draft、prepare 或 pending confirmation 状态，并要求 HITL。

官方网站将 Cernion 介绍为服务于 Stadtwerke 的能源智能与决策平台：MaStR 分析、电网规划、§14a、Redispatch、Energy Sharing、客户服务自动化，以及与 Microsoft Copilot 的互补能力。本代码仓库则是这一产品叙述背后的深层技术系统。

公开发现链接

• 产品与主题中心：Cernion 主题集群
• 能力概览：Cernion 能力中心
• API 和 Agent 集成：MCP Tools & API 和 REST API
• 运营搜索意图页面：
  • 配电网运营商软件
  • Stadtwerke 流程自动化
  • §14a EnWG 证明档案
  • Redispatch 2.0 移动数据
  • 面向 Stadtwerke 和电网运营商的 AI

Cernion 为何具备 Agent 能力

Cernion 以 API 为先，但 API 只是集成层。Agent 能力体现在运行时行为中：

1. 理解能源领域目标 示例：验证电网接入场景、构建 VDMI 职责矩阵、评估 BESS 融资风险、识别 Energy Sharing 数据冲突。
2. 选择受治理的能力路径 capability-broker 会将意图映射到经过筛选的服务链，而不是向大模型暴露完整的工具目录。
3. 执行确定性微服务 能源领域的计算和法规检查仍由代码支持，且可复现。
4. 维护流程状态 个人 Agent 会话、回执、档案、HITL 项目和对象存储证据，让工作得以在单次聊天轮次之外继续进行。
5. 生成可审计的产物 输出不仅是自然语言回答，还包括档案、证据包、决策框架、验证报告、回执和跟踪记录。
6. 管理重新验证 新事实可以成为 Agent 的控制信号：如果 MaStR 资产、数据点或对象存储证据项发生变化，就可以识别并重新检查相关决策。

这就是问答机器人与 Agent 化能源运营平台之间的实际区别。

核心架构

External systems / humans / agents
        |
        v
REST API, Copilot API, OpenClaw Sidecar, MCP-like tool surfaces
        |
        v
Personal Agent / Capability Broker / Agent Receipts / Blueprints
        |
        v
Governed Moleculer services
        |
        v
Datapoints, Object Store, Knowledge RAG, Dossiers, Jobs, Observability

运行时层

层	组件	用途
服务总线	Moleculer、REST 网关、异步任务	确定性服务执行和 API 暴露
数据层	Object Store、Datapoints、DataSources、Knowledge RAG	内部数据、外部证据、租户记忆和源材料
Agent 路由	Personal Agent、Capability Broker、Blueprints、Agent Receipts	意图解析、工具链选择、持久化执行
治理	VDMI、HITL、Clarification Policy、Interface Placeholder、Evidence Revalidation	职责划分、缺失证据、人工决策、差距处理
集成	完整 OpenAPI、Copilot 子集、OpenClaw Sidecar、Webhooks、MCP 风格工具	供人员、副驾驶、Agent 和自动化系统安全使用
可观测性	指标、跟踪记录、审计记录、任务状态	运维、可审计性和支持

主要领域

该平台涵盖能源行业的多个工作领域。以下列表仅作示例； OpenAPI 导出内容才是准确信息的唯一来源。

领域	示例
电网接入和 fNAV	电网接入验证、灵活电网接入、接入拒绝证据
VDMI 治理	按流程步骤划分 Verantwortlich、Durchführend、Mitwirkend、Information；发现项、档案和证据
Zielnetzplanung（ZNP）	项目、假设、Layer 0/1/2 资产、组合分析、NOVA 决策
资产和数据质量	MaStR 质量、资产覆盖项、幽灵资产警报、数据源分类
Energy Sharing 和结算	§42c 风格的分配、结算检查、Redispatch 事后核对
EDM 和市场通信	MSCONS 导入、EDM 验证、虚拟电表、messkonzept 检查
预测和灵活性	预测引擎、剩余负荷、§14a 灵活性事件、SLP 曲线
财务和投资	财务 Agent、fNAV 经济分析、BESS 筛查、资本支出优先级排序
报告和 BI	报告治理、仪表板 API、VNB 监控、EWK 监控
知识和证据	Knowledge RAG、证据路由、档案、对象存储上下文

Agent 能力组件

Agentic Sitemap / AI Catalog

GET /.well-known/ai-catalog.json 和 GET /.well-known/ard.json 会在每次请求时，根据已加载的服务注册表和实时 OpenAPI 元数据生成并发布公开目录。每个已发布的 REST 服务都有一条目，包含操作／能力标记、代表性查询和内嵌的 OpenAPI 契约。目录还提供完整 OpenAPI 文档和 llm.txt 的链接。根路径的响应会通过 HTTP Link 标头公布这两种发现路径；条件请求支持 ETag。

无需手动维护 JSON，也无需调用 LLM。受保护／私有操作、服务设置和运行时数据均会排除在外。目录可见并不意味着获准调用操作。请参阅部署详情。

这些格式仍处于草案阶段：AI Catalog 和 Agentic Resource Discovery。ARD 现使用 ard.json；为使用前代路径的客户端保留了 ai-catalog.json。离线测试会根据固定版本的上游架构验证这两种格式；npm run sync:ai-catalog-schemas 会从同步脚本中固定的版本刷新这些测试样例（Apache-2.0）。

Personal Agent

services/personal-agent.service.js 是面向用户的编排层。它会维护对话状态、路由意图、调用确定性服务并综合结果，而不会将整个后端变成一个提示词。

关键概念：

• 分层上下文管理（“Zwiebelmodus”）
• 持久化执行状态和可恢复会话
• 文件和数据点接入
• 证据缺口处理
• 过程公开事件
• 感知呈现形式的最终产物

Capability Broker

services/capability-broker.service.js 和 src/capability-catalog.js 提供经过整理的能力路由。这是一个控制点，可防止 Agent 直接看到或选择整个后端功能面。

经过整理的能力示例包括：

• vdmi_role_boundary_governance
• vdmi_asset_validation_governance
• vdmi_grid_connection_decision_governance
• netzfahrplan_fnav_assessment
• znp_portfolio_assessment
• settlement_a96_reconciliation
• financier_due_diligence_assessment
• reporting_governance

Agent Receipts

services/agent-receipts.service.js 会将可重复的 Agent 工作流转化为带版本、可测试的配方。Receipts 描述匹配条件、必需输入、工具计划和知识计划。它们是从“Agent 给出了回答”走向“平台选择了受治理、可检查的工作流”的桥梁。

Dossiers 和 Decision Frames

Cernion 使用 dossiers 和 decision frames 来生成可审计的输出。结果可包含：

• 使用的事实
• 假设
• 证据缺口
• 风险
• 禁止采用的假设
• VDMI 职责
• 后续操作
• 人工审核要求

Agentic 治理和重新验证

GitHub issue 中记录了两条正在推进的架构路线：

• #275 Agent Governance Runtime: Bestandsanalyse vor Umsetzungsplan
• #276 Agentic Governance Layer: Faktenänderungen als Steuerungssignal für Agenten

目标方向是让发生变化的事实成为 Agent 的控制信号：

MaStR / datapoint / object-store change
        |
        v
Dependency and impact analysis
        |
        v
Revalidation queue
        |
        v
Agent receipt / capability flow rerun
        |
        v
Audit note, updated dossier, HITL item or exception case

这就是 Cernion 从一次性 API 分析迈向大宗能源流程 RPA+ 的方式：自动处理标准案例，并明确标示例外情况。

集成界面

完整 REST API

完整的 REST API 根据 Moleculer 服务元数据生成。

• Swagger UI：GET /api/docs
• OpenAPI JSON：GET /api/openapi.json
• 静态导出：openapi-export.json
• 供开发者和大模型发现的公共 API 使用指南：docs/public-api-recipes.md

这些使用指南仅使用合成示例、基于环境变量的令牌和确保租户隔离的演示标识符。文档说明了咨询、只读和待确认操作的边界，不是审批、计费、资费、设备控制、合同或生产环境变更演示。

重新生成并审查：

npm run export:openapi
npm run audit:openapi

Microsoft Copilot Bridge

Cernion 不会向 Microsoft Copilot 暴露全部 600 多个 API 路径。Copilot bridge 使用由 config/copilot-operations.json 维护的精选允许列表。

相关文件：

• docs/copilot-process-bridge.md
• docs/copilot-agent.json
• docs/copilot-plugin.json
• openapi-copilot.json

生成 Copilot 子集：

npm run export:openapi:copilot

面向 Copilot 的接口区分以下操作：

• 无副作用的 read 操作
• 用于准备建议的 draft 操作
• 需要确认的 prepare 操作
• 在明确纳入治理前仍处于阻止状态的重大操作

OpenClaw Sidecar

可通过公共 ClawHub 包 @cernion/openclaw-energy-tools-sidecar，在 OpenClaw 中使用 Cernion Energy Tools。 在 OpenClaw 中安装：

openclaw plugins install clawhub:@cernion/openclaw-energy-tools-sidecar

配套仓库 SmartEnergySolutions/cernion-openclaw-sidecar 提供适用于通用 Energy Sidecar 提供商的 OpenClaw 插件，Cernion 是首个提供商。

产品边界有意划分为两个部分：OpenClaw 是用于对话、工具编排、记忆和答案综合的 Agent 运行时。Cernion Energy Tools 则是位于答案背后的能源领域证据、策略、Knowledge RAG 和受 CET 治理的流程层，涵盖 MaStR 资产、电网背景、Redispatch、Zielnetzplanung、14a/14d EnWG 义务、流程受理、Domain Router 案例状态、Case Event Outbox/MWI 及运行状态。

Sidecar 使用 Cernion Sidecar 契约：

• GET /api/agent-sidecar/descriptor
• GET /api/agent-sidecar/mcp/tools
• POST /api/agent-sidecar/mcp/tools/:name/call
• POST /api/knowledge-rag/query
• POST /api/evidence-router/route
• POST /api/copilot-process/intents
• GET /api/_agent/capabilities[?domain=]
• GET /api/_agent/operations[?domain=]

边界规定如下：

• Sidecar 令牌用于标识租户、执行者和客户端上下文；CET 授权与治理构成权限边界。
• Domain Router 和 MWI 工具可更新 CET 内部的 PouchDB 状态，例如案例状态、事件交付状态和相关会话链接。
• 证据/数据补全查询和 Blueprint 计划在实际操作中保持只读。
• 流程受理使用独立的流程令牌，并且只创建 pending_confirmation 回执。
• 管理员、令牌、HITL 解决以及生产环境变更路径均被阻止。
• 领域路由始终在 Cernion 内部进行，不在 Sidecar 中进行。

MCP 风格工具

Cernion 还通过 llm.txt、能力解析端点以及 MCP/OpenClaw 风格的工具列表，发布便于 AI Agent 使用的工具描述。公共文档页面将其描述为一套可供 Stadtwerke 即用的能源工具。

快速入门

前置条件：Node.js 22+

git clone https://github.com/energychain/cernion-energy-tools.git
cd cernion-energy-tools
npm install
cp .env.example .env
npm start

本地默认端点：

• API：http://localhost:3000/api
• Swagger UI：http://localhost:3000/api/docs
• Web 应用：http://localhost:3000/app

完整设置指南：QUICKSTART.md

配置

从 .env.example 开始。常见变量：

变量	用途
CERNION_TOKEN	用于身份验证访问的 API 令牌
LLM_PROVIDER	大模型提供商（gemini、openai-compat、ollama）
LLM_MODEL	所选提供商的模型名称
LLM_API_KEY / GEMINI_API_KEY	按需提供的提供商凭据
API_URL	用于生成的 OpenAPI 服务和 CLI 分享链接的基准 URL
PORT	API 网关端口，默认为 3000
TRACING_ENABLED	启用 OpenTelemetry 跟踪
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP HTTP 跟踪目标
METRICS_PUBLIC	允许不使用完整访问令牌访问 /metrics

大模型健康状态：

GET /api/system/llm/health

可观测性：

• GET /metrics 返回兼容 Prometheus 的指标
• Grafana 示例：docs/observability/grafana/README.md

身份验证指南：BEARER_TOKEN_AUTHENTICATION.md

开发

npm test
npm run test:unit:ci
npm run test:tdd-matrix
npm run test:rest-usecases
npm run lint
npm run audit:openapi
npm run check:llm
npm run release:check
npm run release:gate

运行手册“执行发布门禁”介绍了使用合成多轮场景、评分标准和重复运行，对本地或 HTTP 测试实例进行实践评估的方式。release:gate 会在仓库检查之外增加这项验收。

常用生成命令：

npm run export:openapi
npm run export:openapi:copilot
npm run generate:llm
npm run blueprint:export

创建新的 Moleculer 服务：

npm run create

展示 Cernion

优秀的演示应展示Agent 式运行，而不只是聊天回答。

优秀的演示模式：

• VDMI：为每个流程步骤生成职责矩阵，并检测角色边界违规
• BESS：从电网接入、风险、收入假设和融资方证据等方面评估一个场址
• Energy Sharing：找出阻碍流程的 MaLo/MeLo、EDM 和结算冲突
• MaStR/Revalidation：展示外部资产更新如何触发对相关决策的重新检查
• Copilot/Sidecar：展示 Cernion 如何作为通用 Agent 背后受治理的能源领域后端

有用的 Agent 式运行轨迹应清晰展示以下内容：

User objective
  -> intent and capability
  -> selected receipt / blueprint
  -> service chain
  -> evidence used
  -> gaps and risks
  -> HITL / policy decision
  -> dossier or decision artifact
  -> audit trace

文档索引

文档	主题
docs/copilot-process-bridge.md	精选的 Microsoft Copilot API 子集
docs/v0.52-implementation-plans/personal-agent-v052-architecture-tdd.md	Personal Agent 架构和 TDD 契约
docs/v0.52-implementation-plans/v0.52.1-capability-broker.md	Capability Broker 实施计划
docs/observability/grafana/README.md	Grafana 仪表板
docs/DSFA_TEMPLATE.md	数据保护影响评估模板
docs/BACKEND_CONTEXT.md	UI/前端开发的后端上下文
CHANGELOG.md	发布历史
MCP_TOOLS.md	MCP/工具参考
docs/SHARED_SERVICE_JOURNAL.md	RC3 仅追加的 Shared Service Journal、确定性摘要和保留期限
docs/domain-router.md	CET Domain Router、类型化案例关联、自有/团队/租户可见性以及 Case Event Outbox / MWI
docs/tenant-memory.md	租户记忆：陈述、共享锚点、来源、更正和一次性提示
docs/open-webui-tenant-gateway.md	无需 AgentOS 即可访问 RC3 Open WebUI / Cernion Workbench 租户网关
llm.txt	机器可读的服务和能力上下文
SECURITY.md	安全策略

许可证与运营方背景

许可证：GPL-3.0。请参阅 LICENSE。

Cernion 由 STROMDAO GmbH 在 Cernion 能源智能平台背景下开发。

支持与产品反馈：

• GitHub Issues
• [email protected]

工作台：理解、回复、在后台创建案例

通过中央 LLM 门面，将实质性消息和插入的外部文本转换为态势概览。CET 会提供相关来源，并提出至多三个新的专业问题。具体工作任务会生成一个后台案例；“无案例”会撤回该案例。知识和状态问题不会生成案例。发送请求会触发提示，并在明确要求时生成内部草稿。来源映射和相关性阈值在 src/workbench-knowledge-sources.json 中配置。详情与限制请参阅 租户网关指南 和 #739 验收报告。

CET 会在整个租户范围内记录与组织相关的陈述，并通过“我记下了：……”确认一次。少量共享锚点会连接不同人员的陈述；检测到的相互影响会在对话中显示，并在其他人员下次联系时提示一次。每次访问都会遵守租户隔离和保密级别。详情请参阅 租户记忆指南。

租户数据目录

Open WebUI 中完整的 CSV/XLSX 文本表格会作为用户提供的信息存储在整个租户范围内，并通过 dataset.query 进行确定性分析。即使重新发送附件，相同内容也不会生成新版本或确认信息。 设置、限制和示例：租户数据目录。结构化消息和 EDIFACT：格式、校验与查询。

聊天中的原始文件（#790）

安装版本化 Open-WebUI 过滤器、签名下载、文件限制和保留期限：运维手册。未安装过滤器时，仍使用现有的文档文本处理流程。

RC3 邮件和文档入口热修复（#846）

表格识别要求表头至少包含两列，并且至少有两行列宽一致的数据。WORKBENCH_DATASET_MIN_TABLE_RATIO 用于设定表格块中所需的比例（默认值 0.75，有效范围：大于 0.5 且不超过 1）。常见解析器错误会回退到文本处理；针对实际识别出的表格，合理性拦截仍保持启用。文件、行和列预算仍然适用。只有明确识别出且无法无损还原的 Open-WebUI 拆分模式才会使用 WORKBENCH_DATASET_DAMAGED。

重新生成合成测试样例，并在本地检查回归：

node scripts/generate-conversation-fixtures.js
node scripts/generate-review-fixture.js
node scripts/generate-dataset-fixtures.js
npm test -- --runInBand tests/workbench-846.test.js tests/workbench-838.test.js

现有实时脚本还会检查邮件接收（1）、协议摘要（3）、与外部 INVOIC 数据集并存的邮件历史记录（5），以及明确指定的消息（6）。脚本会启动一个本地 Broker，使用相互隔离的临时数据库和合成验证租户。所有大模型调用都通过中央门面，并遵守现有的调用和令牌预算。只能使用非生产配置启动：

WORKBENCH_ENV_FILE=/path/to/nonproduction.env \
  WORKBENCH_VALIDATION_REPORT=/tmp/rc3-hotfix-846-live.json \
  LIVE_MAX_MODEL_CALLS=80 LIVE_MAX_TOKENS=1000000 \
  node scripts/validate-rc3-closeout-live.js

该扩展尚未进行实时运行。只有在单独的非生产环境运行后，实时报告才能作为验收凭据。