Layered Dependencies

中文 | English

Layered Dependencies / 分层依赖规则

维护版本：v0.51.2 ｜ 最后更新：2026-07-06

EnerOS 严格遵循单向依赖：下层不依赖上层，禁止反向依赖与循环依赖。这是项目硬约束之一（见 project memory 的"Hard Constraints"）。

详见 docs/developer-guide.md §1.3。

---

依赖方向图

L0 基础层（无内部依赖或仅依赖 eneros-core）
  ↑
L1 内核层 / 协议层（依赖 L0）
  ↑
L2 能力层（依赖 L0、L1）
  ↑
L3 编排层（依赖 L0、L1、L2）
  ↑
L3 应用层（依赖全部下层）

---

各层依赖关系

eneros-core ◄── eneros-topology
             ◄── eneros-powerflow
             ◄── eneros-constraint
             ◄── eneros-equipment
             ◄── eneros-timeseries
             ◄── eneros-eventbus
             ◄── eneros-memory
             ◄── eneros-tenant
             ◄── eneros-tool
             ◄── eneros-reasoning
             ◄── eneros-os

eneros-core + eneros-eventbus ◄── eneros-device
eneros-core + eneros-equipment ◄── eneros-bridge
eneros-core + eneros-topology + eneros-powerflow + eneros-equipment ◄── eneros-network
eneros-core + eneros-device ◄── eneros-scada
eneros-powerflow + eneros-equipment ◄── eneros-analysis
eneros-core + eneros-os ◄── eneros-gateway
eneros-gateway + eneros-agent + eneros-reasoning + eneros-tool ◄── eneros-api
eneros-gateway + eneros-agent + eneros-constraint ◄── eneros-dashboard

---

特殊处理：避免循环依赖

1. eneros-plugin 独立

eneros-plugin 独立于 eneros-device/eneros-agent/eneros-analysis，通过镜像类型避免循环依赖。第三方插件通过 eneros-sdk 调用，eneros-sdk 封装常用类型。

2. eneros-network::conversion 模块

eneros-network 同时依赖 eneros-topology + eneros-powerflow + eneros-equipment。在 v0.50.0 引入 GridSimulator::from_ieee14() → power_network_to_topology() 转换函数时，将该函数放在 eneros-network::conversion 模块中，避免 eneros-powerflow 反向依赖 eneros-network。

3. eneros-nl 的 NlDataProvider trait

eneros-nl（L9 自然语言查询层）需要查询拓扑/时序/告警等数据，但不能依赖 eneros-topology/eneros-timeseries/eneros-scada（避免反向依赖）。通过 NlDataProvider trait 依赖注入，由调用方（eneros-api）实现 trait 提供数据。

4. eneros-sdk 镜像类型

eneros-sdk 暴露给第三方插件开发者的类型，与 eneros-plugin 内部类型保持镜像关系（同名 + 同结构），避免插件编译时直接依赖 eneros-plugin 内部模块。

---

依赖管理工具

# 检查循环依赖
cargo tree --workspace --duplicate

# 检查重复版本
cargo deny check bans

# 检查许可证
cargo deny check licenses

# 检查安全公告
cargo audit

CI 在 .github/workflows/ci.yml + security.yml 中强制运行上述检查。新增依赖必须满足：

• MIT 兼容许可证
• 通过 cargo audit 与 cargo deny
• 必要且最小化
• 不得 GPL/AGPL 或含未修复 RUSTSEC 漏洞

---

新增 crate 流程

新增 crate 需：

1. 确定层级（L0/L1/L2/L3）
2. 仅依赖同层或下层 crate
3. 在 Cargo.toml workspace members 添加
4. 更新 Crate Index 与 docs/developer-guide.md
5. 结构变更需 /spec + ADR + 全文档同步（见 记忆系统.md 第四部分矩阵）

---

下一步

• Crate Index — 完整 56 crates 索引
• Architecture Overview — 各层职责
• Development Workflow — 新增 crate 完整流程
• docs/developer-guide.md §1.3 — 完整依赖规则