项目结构

EnerOS 仓库采用 Cargo workspace 组织 56 个 Rust crate，遵循”关注点分离、单一职责、最小依赖”的模块组织原则。仓库根目录包含 crates/、os/、docs/、examples/、tests/、tools/、scripts/ 等顶层目录。

完整目录树

eneros/
├── crates/                       # 56 个 Rust crate（库 + 二进制）
│   ├── eneros-core/              # L0 核心类型与错误
│   ├── eneros-linalg/            # L0 稀疏线性代数
│   ├── eneros-perf/              # L1 性能优化（arena/pool/ring）
│   ├── eneros-audit/             # L2 审计日志（HMAC + WORM）
│   ├── eneros-topology/          # L3 电网拓扑引擎
│   ├── eneros-powerflow/         # L3 潮流计算
│   ├── eneros-constraint/        # L3 安全约束引擎
│   ├── eneros-equipment/         # L3 设备模型库
│   ├── eneros-cnpower/           # L3 中国配网设备与标准
│   ├── eneros-timeseries/        # L3 时序存储
│   ├── eneros-eventbus/          # L3 事件总线
│   │   └── bins/broker/          # 事件代理二进制
│   ├── eneros-gateway/           # L2 安全网关
│   │   └── bins/gateway/         # 网关二进制
│   ├── eneros-device/            # L1 设备管理与协议适配
│   ├── eneros-api/               # L1 REST/GraphQL/SSE API
│   ├── eneros-runtime/           # L1 顶层运行时组合
│   ├── eneros-bridge/            # L3 外部系统桥接
│   ├── eneros-network/           # L3 CIM 网络模型
│   ├── eneros-memory/            # L4 记忆系统
│   ├── eneros-tenant/            # L1 多租户隔离
│   ├── eneros-tool/              # L4 工具引擎
│   ├── eneros-reasoning/         # L4 推理引擎
│   ├── eneros-agent/             # L4 Agent 运行时
│   │   └── bins/                 # Agent 二进制
│   │       ├── dispatch-agent/   # 智能调度 Agent
│   │       ├── forecast-agent/   # 负荷预测 Agent
│   │       ├── operation-agent/  # 智能运维 Agent
│   │       ├── self-healing-agent/ # 故障自愈 Agent
│   │       ├── planning-agent/   # 配网规划 Agent
│   │       └── trading-agent/    # 电力交易 Agent
│   ├── eneros-test-utils/        # L1 测试工具
│   ├── eneros-scada/             # L1 SCADA 数据采集
│   ├── eneros-twin/              # L4 数字孪生
│   ├── eneros-graphql/           # L1 GraphQL schema
│   ├── eneros-ai/                # L4 AI/ML 集成
│   ├── eneros-aiops/             # L4 AIOps
│   ├── eneros-edge/              # L5 边缘智能
│   ├── eneros-protocol-iec103/   # L1 IEC 103 协议
│   ├── eneros-protocol-cdt/      # L1 CDT 协议
│   ├── eneros-protocol-pmu/      # L1 PMU 协议
│   ├── eneros-protocol-iccp/     # L1 ICCP 协议
│   ├── eneros-protocol-mqtt/     # L1 MQTT 协议
│   ├── eneros-protocol-coap/     # L1 CoAP 协议
│   ├── eneros-protocol-lwm2m/    # L1 LwM2M 协议
│   ├── eneros-protocol-dlt698/   # L1 DLT 698 协议
│   ├── eneros-analysis/          # L3 高级分析
│   ├── eneros-dashboard/         # L5 Web 可视化
│   ├── eneros-simulator/         # L3 场景仿真器
│   ├── eneros-slo/               # L1 SLO/SLI 评估
│   ├── eneros-plugin/            # L1 插件系统
│   │   └── bins/plugin-daemon/   # 插件守护进程
│   ├── eneros-plugin-macros/     # L1 插件派生宏
│   ├── eneros-sdk/               # L1 多语言 SDK
│   │   └── bindings/
│   │       ├── c/                # C 绑定
│   │       └── python/           # Python 绑定
│   ├── eneros-ops/               # L1 运维自动化
│   ├── eneros-os/                # L1 OS 服务
│   │   └── bins/
│   │       ├── eneros-init/      # 系统初始化
│   │       ├── eneros-ha/        # 高可用守护
│   │       ├── eneros-timesync/  # 时间同步
│   │       ├── enerosctl/        # 管理命令行
│   │       ├── eneros-installer/ # 安装器
│   │       ├── eneros-autoscaler/ # 自动扩缩容
│   │       ├── eneros-backup/    # 备份工具
│   │       ├── eneros-oncall/    # 值班管理
│   │       ├── eneros-dr-orchestrator/ # 灾备编排
│   │       └── eneros-upgrader/  # OTA 升级器
│   ├── eneros-market/            # L5 电力市场
│   │   └── bins/market-server/   # 市场服务器
│   ├── eneros-ids/               # L2 入侵检测
│   ├── eneros-compliance/        # L2 合规检查
│   ├── eneros-trust/             # L2 零信任 mTLS
│   ├── eneros-multiregion/       # L1 多区域复制
│   ├── eneros-emtp/              # L3 电磁暂态仿真
│   ├── eneros-iot-hub/           # L1 IoT 接入枢纽
│   ├── eneros-nl/                # L5 自然语言交互
│   ├── eneros-3d/                # L3 3D 可视化场景
│   ├── eneros-report/            # L5 报表生成
│   └── eneros-i18n/              # L1 国际化
├── os/                           # OS 层（系统级服务与镜像）
│   ├── boot/                     # 启动配置
│   │   ├── grub.cfg              # GRUB 配置
│   │   ├── secure-boot.sh        # 安全启动脚本
│   │   ├── build-initramfs.sh    # 构建 initramfs
│   │   └── systemd-boot.conf     # systemd-boot 配置
│   ├── kernel/                   # 内核配置与补丁
│   │   ├── patches/              # 内核补丁
│   │   ├── config-x86_64         # x86_64 内核配置
│   │   ├── config-aarch64        # aarch64 内核配置
│   │   └── build.sh              # 内核构建脚本
│   ├── rootfs/                   # 根文件系统
│   │   ├── files/
│   │   │   └── etc/eneros/       # EnerOS 配置文件
│   │   │       ├── init.toml     # 初始化配置
│   │   │       ├── ha.toml       # 高可用配置
│   │   │       ├── audit.toml    # 审计配置
│   │   │       ├── network.toml  # 网络配置
│   │   │       ├── plugin.toml   # 插件配置
│   │   │       └── syslog.toml   # 系统日志配置
│   │   └── build.sh              # rootfs 构建脚本
│   ├── image-builder/            # 系统镜像构建
│   │   ├── build.sh              # 镜像构建脚本
│   │   ├── create-partitions.sh  # 分区创建
│   │   ├── inject-config.sh      # 配置注入
│   │   └── install-bootloader.sh # 引导加载器安装
│   └── tests/                    # OS 启动测试
│       ├── boot_test.rs          # 启动测试
│       └── boot_params_test.rs   # 启动参数测试
├── docs/                         # 项目文档
│   ├── adr/                      # 架构决策记录
│   │   ├── 0002-power-native-agentos.md
│   │   ├── 0007-zero-trust-mtls.md
│   │   ├── 0008-ops-automation.md
│   │   ├── 0009-ha-enhancement.md
│   │   ├── 0010-agent-intelligence.md
│   │   ├── 0012-iot-ubiquitous-access.md
│   │   ├── 0013-visualization-stack.md
│   │   └── 0014-i18n-compliance.md
│   ├── compliance/               # 合规文档
│   │   ├── gdpr-pipl-ccpa.md     # 数据保护合规
│   │   ├── iec-62443-4-1-sdlc.md # IEC 62443 SDLC
│   │   ├── nerc-cip-005.md       # NERC CIP-005
│   │   ├── nerc-cip-007.md       # NERC CIP-007
│   │   └── nerc-cip-010.md       # NERC CIP-010
│   ├── deployment.md             # 部署文档
│   ├── developer-guide.md        # 开发者指南
│   ├── plugin-development.md     # 插件开发指南
│   └── user-manual.md            # 用户手册
├── locales/                      # 国际化资源
│   ├── en-US.ftl                 # 英语
│   ├── zh-CN.ftl                 # 简体中文
│   ├── ja-JP.ftl                 # 日语
│   └── es-ES.ftl                 # 西班牙语
├── tests/                        # 集成测试
│   ├── e2e/                      # 端到端测试
│   │   ├── scenarios/            # 测试场景
│   │   │   ├── ha_failover.rs    # 高可用故障转移
│   │   │   └── startup.rs        # 启动测试
│   │   └── tests/e2e_tests.rs    # E2E 测试入口
│   ├── protocol_conformance/     # 协议一致性测试
│   ├── security/                 # 安全测试
│   │   ├── owasp/                # OWASP Top 10
│   │   └── tests/security_tests.rs
├── benches/                      # 性能基准测试
│   ├── benches/
│   │   ├── agent_bench.rs        # Agent 性能
│   │   ├── ai_bench.rs           # AI 推理性能
│   │   ├── api_bench.rs          # API 性能
│   │   ├── grid_analysis_bench.rs # 电网分析性能
│   │   ├── ha_bench.rs           # 高可用性能
│   │   ├── iot_bench.rs          # IoT 性能
│   │   ├── perf_bench.rs         # 通用性能
│   │   ├── powerflow_bench.rs    # 潮流计算性能
│   │   ├── scada_bench.rs        # SCADA 性能
│   │   ├── twin_bench.rs         # 数字孪生性能
│   │   └── visualization_bench.rs # 可视化性能
│   └── baseline.json             # 性能基线
├── templates/                    # 代码模板
│   └── plugin-ci-cd/             # 插件 CI/CD 模板
├── deploy/                       # 部署配置
│   ├── docker/
│   │   ├── Dockerfile            # 容器镜像
│   │   └── docker-compose.yml    # 编排配置
│   ├── scripts/
│   │   ├── build.sh              # 构建脚本
│   │   ├── dev.sh                # 开发脚本
│   │   └── healthcheck.sh        # 健康检查
│   └── prometheus.yml            # Prometheus 监控配置
├── third_party/                  # 第三方依赖
│   ├── cnpower/                  # 中国配网参考库
│   └── pandapower/               # pandapower 参考库
├── .github/                      # GitHub 配置
│   └── workflows/                # CI/CD 流水线
│       ├── ci.yml                # 持续集成
│       ├── e2e.yml               # 端到端测试
│       ├── security.yml          # 安全扫描
│       ├── benchmark.yml         # 性能基准
│       ├── coverage.yml          # 覆盖率
│       ├── conformance.yml       # 协议一致性
│       ├── release.yml           # 发布流水线
│       └── deploy-web.yml        # 文档站部署
├── Cargo.toml                    # Workspace 配置
├── Cargo.lock                    # 依赖锁定
├── deny.toml                     # cargo-deny 配置
├── eneros.toml                   # 运行时默认配置
├── README.md                     # 项目说明（中文）
├── README_en.md                  # 项目说明（英文）
├── CHANGELOG.md                  # 变更日志
├── ROADMAP.md                    # 路线图
└── CONTRIBUTING.md               # 贡献指南

顶层目录说明

目录	用途	提交到 GitHub	说明
`crates/`	56 个 Rust crate	✅	库 + 二进制，可被其他项目依赖
`os/`	OS 系统层	✅	启动、内核配置、rootfs、镜像构建
`docs/`	项目文档	✅	ADR、合规、部署、开发指南
`locales/`	国际化资源	✅	Fluent 翻译文件（.ftl）
`tests/`	集成测试	✅	E2E、协议一致性、安全测试
`benches/`	性能基准	✅	criterion 基准测试
`templates/`	代码模板	✅	插件 CI/CD 等模板
`deploy/`	部署配置	✅	Docker、脚本、监控
`third_party/`	第三方参考库	✅	cnpower、pandapower 子模块
`.github/`	CI/CD 配置	✅	GitHub Actions 工作流
`.trae/`	AI 开发文件	❌	本地 spec/rules，不上传
`DEVGUIDE.md`	AI 开发手册	❌	本地架构地图，gitignore
`target/`	构建产物	❌	cargo 构建缓存

crates/ vs os/

目录	用途	构建产物	示例
`crates/`	Rust 库 crate（可被依赖）	.rlib / .so / .exe	eneros-core, eneros-powerflow
`crates/*/bins/`	Rust 二进制 crate	可执行文件	dispatch-agent, enerosctl
`os/`	OS 系统层（非 Rust）	配置/脚本/镜像	grub.cfg, rootfs, kernel config

Cargo Workspace 配置

核心配置

# Cargo.toml (workspace 根)
[workspace]
resolver = "2"
members = [
    "crates/eneros-core",
    "crates/eneros-linalg",
    "crates/eneros-perf",
    "crates/eneros-audit",
    "crates/eneros-topology",
    "crates/eneros-powerflow",
    "crates/eneros-constraint",
    "crates/eneros-equipment",
    "crates/eneros-cnpower",
    "crates/eneros-timeseries",
    "crates/eneros-eventbus",
    "crates/eneros-eventbus/bins/broker",
    "crates/eneros-gateway",
    "crates/eneros-gateway/bins/gateway",
    "crates/eneros-device",
    "crates/eneros-api",
    "crates/eneros-runtime",
    "crates/eneros-bridge",
    "crates/eneros-network",
    "crates/eneros-memory",
    "crates/eneros-tenant",
    "crates/eneros-tool",
    "crates/eneros-reasoning",
    "crates/eneros-agent",
    "crates/eneros-agent/bins/dispatch-agent",
    "crates/eneros-agent/bins/forecast-agent",
    "crates/eneros-agent/bins/operation-agent",
    "crates/eneros-agent/bins/self-healing-agent",
    "crates/eneros-agent/bins/planning-agent",
    "crates/eneros-agent/bins/trading-agent",
    "crates/eneros-test-utils",
    "crates/eneros-scada",
    "crates/eneros-twin",
    "crates/eneros-graphql",
    "crates/eneros-ai",
    "crates/eneros-aiops",
    "crates/eneros-edge",
    "crates/eneros-protocol-iec103",
    "crates/eneros-protocol-cdt",
    "crates/eneros-protocol-pmu",
    "crates/eneros-protocol-iccp",
    "crates/eneros-analysis",
    "crates/eneros-dashboard",
    "crates/eneros-simulator",
    "crates/eneros-slo",
    "crates/eneros-plugin",
    "crates/eneros-plugin/bins/plugin-daemon",
    "crates/eneros-plugin-macros",
    "crates/eneros-sdk",
    "crates/eneros-sdk/bindings/c",
    "crates/eneros-sdk/bindings/python",
    "crates/eneros-ops",
    "crates/eneros-os",
    "crates/eneros-os/bins/eneros-init",
    "crates/eneros-os/bins/eneros-ha",
    "crates/eneros-os/bins/eneros-timesync",
    "crates/eneros-os/bins/enerosctl",
    "crates/eneros-os/bins/eneros-installer",
    "crates/eneros-os/bins/eneros-autoscaler",
    "crates/eneros-os/bins/eneros-backup",
    "crates/eneros-os/bins/eneros-oncall",
    "crates/eneros-os/bins/eneros-dr-orchestrator",
    "crates/eneros-os/bins/eneros-upgrader",
    "crates/eneros-market",
    "crates/eneros-market/bins/market-server",
    "crates/eneros-ids",
    "crates/eneros-compliance",
    "crates/eneros-trust",
    "crates/eneros-multiregion",
    "crates/eneros-emtp",
    "crates/eneros-protocol-mqtt",
    "crates/eneros-protocol-coap",
    "crates/eneros-protocol-lwm2m",
    "crates/eneros-protocol-dlt698",
    "crates/eneros-iot-hub",
    "crates/eneros-nl",
    "crates/eneros-3d",
    "crates/eneros-report",
    "crates/eneros-i18n",
    "os/tests",
    "tests/e2e",
    "tests/protocol_conformance",
    "tests/security",
    "benches",
]

[workspace.package]
version = "0.44.0"
edition = "2021"
authors = ["GAWG-AI"]
license = "MIT"
description = "EnerOS - Power-Native Agent Operating System"

[workspace.dependencies]
# 异步运行时
tokio = { version = "1", features = ["full"] }
async-trait = "0.1"
futures = "0.3"

# 序列化
serde = { version = "1", features = ["derive"] }
serde_json = "1"
bincode = "1"

# 日志与追踪
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["json", "env-filter"] }

# 错误处理
thiserror = "1"
anyhow = "1"

# 数据结构
dashmap = "5"
parking_lot = "0.12"
uuid = { version = "1", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }

# 数学与科学计算
ndarray = { version = "0.15", features = ["serde"] }
num-complex = { version = "0.4", features = ["serde"] }
sprs = "0.11"

# 安全
jsonwebtoken = "9"
sha2 = "0.10"
hmac = "0.12"
aes-gcm = "0.10"
ed25519-dalek = { version = "2", features = ["rand_core"] }
zeroize = { version = "1", features = ["derive", "serde", "alloc"] }
libseccomp = "0.4"

# TLS
tokio-rustls = "0.26"
rustls = { version = "0.23", default-features = false, features = ["ring", "std"] }

# 内部 crate（path 依赖）
eneros-core = { path = "crates/eneros-core" }
eneros-linalg = { path = "crates/eneros-linalg" }
# ... 其余内部 crate 同样以 path 声明

单个 crate 的 Cargo.toml 示例

# crates/eneros-powerflow/Cargo.toml
[package]
name = "eneros-powerflow"
version.workspace = true
edition.workspace = true
authors.workspace = true
license.workspace = true
description = "EnerOS power flow solver (Newton-Raphson)"

[dependencies]
# EnerOS 内部依赖
eneros-core = { workspace = true }
eneros-linalg = { workspace = true }
eneros-topology = { workspace = true }

# 第三方依赖
tokio = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
tracing = { workspace = true }
thiserror = { workspace = true }
ndarray = { workspace = true }
sprs = { workspace = true }

[dev-dependencies]
eneros-test-utils = { workspace = true }
criterion = { workspace = true }

[[bench]]
name = "powerflow_bench"
harness = false

关键文件说明

根目录文件

文件	用途	同步触发
`Cargo.toml`	Workspace 配置（members + 依赖）	新增/移除 crate
`Cargo.lock`	依赖版本锁定	cargo build 自动更新
`deny.toml`	cargo-deny 配置（许可/重复依赖）	依赖变更
`eneros.toml`	运行时默认配置	配置项变更
`README.md`	项目说明（中文）	版本/功能/架构变更
`README_en.md`	项目说明（英文）	与 README.md 同步
`CHANGELOG.md`	变更日志	每次代码变更
`ROADMAP.md`	路线图	版本发布时更新
`CONTRIBUTING.md`	贡献指南	流程变更时

OS 层配置文件

文件	路径	用途
`init.toml`	`os/rootfs/files/etc/eneros/`	系统初始化配置
`ha.toml`	`os/rootfs/files/etc/eneros/`	高可用配置
`audit.toml`	`os/rootfs/files/etc/eneros/`	审计配置
`network.toml`	`os/rootfs/files/etc/eneros/`	网络配置
`plugin.toml`	`os/rootfs/files/etc/eneros/`	插件配置
`syslog.toml`	`os/rootfs/files/etc/eneros/`	系统日志配置
`grub.cfg`	`os/boot/`	GRUB 引导配置
`config-x86_64`	`os/kernel/`	x86_64 内核配置
`config-aarch64`	`os/kernel/`	aarch64 内核配置

eneros.toml 运行时配置

# eneros.toml - 运行时默认配置
[server]
host = "0.0.0.0"
port = 8080
workers = 4

[realtime]
cpus = [2, 3]
priority = 80
lock_memory = true
use_huge_pages = true

[database]
path = "./data/eneros.db"
timeseries_path = "./data/ts"

[security]
mtls_enabled = true
ca_cert_path = "./certs/ca.pem"
server_cert_path = "./certs/server.pem"
server_key_path = "./certs/server.key"

[audit]
storage_path = "./audit"
hmac_key = "change-me-in-production-32-bytes"
worm_enabled = true

[ha]
enabled = false
peers = []
heartbeat_interval_ms = 1000
failover_timeout_ms = 5000

[multiregion]
local_region = "default"
peer_regions = []
replication_mode = "async_wal"

模块组织原则

1. 单一职责

每个 crate 只负责一个明确的职责：

// ✅ 正确：eneros-topology 只负责拓扑
crate eneros-topology {
    mod graph;      // 图数据结构
    mod engine;     // 拓扑引擎
    mod search;     // 搜索算法
}

// ❌ 错误：在 eneros-topology 中混入潮流计算
crate eneros-topology {
    mod graph;
    mod powerflow;  // 应该放在 eneros-powerflow
}

2. 接口与实现分离

通过 trait 暴露接口，impl 模块隐藏实现：

// crates/eneros-powerflow/src/lib.rs
pub mod solver;      // 暴露 PowerflowSolver trait
pub mod result;      // 暴露 PowerflowResult 类型
mod matrix;          // 内部矩阵工具（不暴露）
mod ieee;            // 内部 IEEE 标准实现（不暴露）

// 公共 API
pub use solver::{PowerflowSolver, NewtonRaphsonSolver};
pub use result::PowerflowResult;

3. 测试组织

测试类型	位置	命名	运行命令
单元测试	`src/*.rs` 内 `#[cfg(test)] mod tests`	`test_*`	`cargo test -p <crate>`
集成测试	`tests/*.rs`	`*_test.rs`	`cargo test --test <name>`
端到端测试	`tests/e2e/`	`e2e_*.rs`	`cargo test --package e2e`
协议一致性	`tests/protocol_conformance/`	—	`cargo test --package protocol_conformance`
安全测试	`tests/security/`	—	`cargo test --package security`
OS 启动测试	`os/tests/`	`*_test.rs`	`cargo test --package os-tests`
性能基准	`benches/benches/`	`*_bench.rs`	`cargo bench`

4. 模块命名规范

命名对象	规范	示例
Crate	`eneros-<domain>`	`eneros-topology`, `eneros-powerflow`
二进制	`eneros-<service>` 或 `<domain>-agent`	`enerosctl`, `dispatch-agent`
模块	`<domain>` 或 `<feature>`	`topology`, `powerflow`, `gateway`
Trait	大驼峰，名词	`TopologyEngine`, `SafetyGateway`
函数	蛇形小写，动词开头	`find_islands`, `solve_powerflow`
类型	大驼峰，名词	`Bus`, `Branch`, `Command`
常量	蛇形大写	`MAX_HISTORY`, `SHM_MAGIC`

代码组织规范

目录结构规范

每个 crate 遵循统一的目录结构：

crates/eneros-<name>/
├── Cargo.toml          # crate 配置
├── README.md           # crate 说明（可选）
├── src/
│   ├── lib.rs          # 库入口（公共 API）
│   ├── error.rs        # 错误类型
│   ├── types.rs        # 核心类型
│   ├── <module>.rs     # 业务模块
│   └── tests/          # 集成测试（可选）
├── tests/
│   └── <test>.rs       # 集成测试
└── benches/
    └── <bench>.rs      # 性能基准（可选）

二进制 crate 结构

crates/eneros-<name>/bins/<binary>/
├── Cargo.toml          # 二进制配置
└── src/
    └── main.rs         # 入口

示例：eneros-os crate 结构

crates/eneros-os/
├── Cargo.toml
├── src/
│   ├── lib.rs              # 公共 API 入口
│   ├── init/               # 系统初始化
│   │   ├── mod.rs
│   │   ├── manager.rs      # init 管理器
│   │   ├── config.rs       # 配置加载
│   │   ├── service.rs      # 服务管理
│   │   └── supervisor.rs   # 进程监督
│   ├── rt/                 # 实时运行时
│   │   ├── mod.rs
│   │   ├── runtime.rs      # RtRuntime
│   │   ├── ipc.rs          # 无锁 SPSC 队列
│   │   ├── shm.rs          # 共享内存通道
│   │   └── watchdog.rs     # 看门狗
│   ├── agentos/            # Agent OS 服务
│   │   ├── mod.rs
│   │   ├── ipc.rs          # Agent IPC
│   │   ├── quota.rs        # 资源配额
│   │   └── seccomp.rs      # seccomp 沙箱
│   ├── ha/                 # 高可用
│   │   ├── mod.rs
│   │   ├── cluster.rs      # 集群管理
│   │   ├── failover.rs     # 故障转移
│   │   ├── fencing.rs      # 脑裂防护
│   │   ├── heartbeat.rs    # 心跳检测
│   │   └── replication.rs  # 状态复制
│   ├── hal/                # 硬件抽象层
│   │   ├── mod.rs
│   │   ├── linux_hal.rs    # Linux HAL
│   │   └── sensor.rs       # 传感器接口
│   ├── netcfg/             # 网络配置
│   ├── syslog/             # 系统日志
│   │   ├── mod.rs
│   │   └── rotate.rs       # 日志轮转
│   ├── timesync/           # 时间同步
│   │   ├── mod.rs
│   │   ├── ntp.rs          # NTP 客户端
│   │   └── ptp.rs          # PTP（精确时间协议）
│   ├── security/           # 安全模块
│   ├── devmgr/             # 设备管理
│   │   ├── mod.rs
│   │   └── hotplug.rs      # 热插拔
│   └── update/             # OTA 升级
│       ├── mod.rs
│       ├── ota.rs          # OTA 主逻辑
│       ├── manifest.rs     # 升级清单
│       └── signer.rs       # 签名验证
├── tests/
│   └── init_test.rs        # 初始化测试
└── bins/                   # 二进制
    ├── eneros-init/        # 系统初始化守护
    ├── eneros-ha/          # 高可用守护
    ├── eneros-timesync/    # 时间同步守护
    ├── enerosctl/          # 管理命令行
    ├── eneros-installer/   # 安装器
    ├── eneros-autoscaler/  # 自动扩缩容
    ├── eneros-backup/      # 备份工具
    ├── eneros-oncall/      # 值班管理
    ├── eneros-dr-orchestrator/ # 灾备编排
    └── eneros-upgrader/    # OTA 升级器

构建与测试

构建命令

# 构建所有 crate
cargo build --release

# 构建特定 crate
cargo build -p eneros-powerflow

# 构建特定二进制
cargo build -p enerosctl

# 构建 eneros-init（带 OS 特性）
cargo build -p eneros-init --features os

# 构建 WORM 审计（带审计特性）
cargo build -p eneros-audit --features worm

测试命令

# 运行所有测试
cargo test

# 运行特定 crate 测试
cargo test -p eneros-powerflow

# 运行端到端测试
cargo test --package e2e

# 运行安全测试
cargo test --package security

# 运行协议一致性测试
cargo test --package protocol_conformance

# 运行性能基准
cargo bench

代码质量

# 代码格式化
cargo fmt --all

# 静态检查
cargo clippy --all -- -D warnings

# 依赖审计
cargo deny check

# 重复依赖检测
cargo tree -d

# 覆盖率
cargo tarpaulin --out Html

CI/CD 流水线

CI/CD 配置位于 .github/workflows/，包含以下流水线：

流水线	文件	触发条件	说明
持续集成	`ci.yml`	push/PR	构建 + 单元测试 + clippy
端到端测试	`e2e.yml`	push to main	E2E 测试
安全扫描	`security.yml`	push/PR	SAST + 依赖审计
性能基准	`benchmark.yml`	push to main	性能回归检测
覆盖率	`coverage.yml`	push to main	代码覆盖率上报
协议一致性	`conformance.yml`	push/PR	电力协议一致性
发布	`release.yml`	tag	发布到 crates.io + GitHub Release
文档站	`deploy-web.yml`	push to main	部署文档站到 GitHub Pages

开发工作流

添加新 crate

mkdir -p crates/eneros-newfeature/src

创建 Cargo.toml：

[package]
name = "eneros-newfeature"
version.workspace = true
edition.workspace = true
authors.workspace = true
license.workspace = true
description = "EnerOS new feature"

[dependencies]
eneros-core = { workspace = true }
# 其他依赖

创建 src/lib.rs：

//! EnerOS new feature module

pub mod error;
pub mod types;

pub use error::{NewFeatureError, Result};
pub use types::NewFeature;

在根 Cargo.toml 的 members 中添加：

members = [
    # ...
    "crates/eneros-newfeature",
]

在 [workspace.dependencies] 中添加 path 依赖：

eneros-newfeature = { path = "crates/eneros-newfeature" }

同步文档：
- 更新 CHANGELOG.md
- 更新 DEVGUIDE.md（如存在）
- 更新 docs/developer-guide.md
- 必要时新增 docs/adr/000N-*.md

开发环境准备

# 1. 安装 Rust 工具链
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default stable

# 2. 安装组件
rustup component add rustfmt clippy
cargo install cargo-deny cargo-tarpaulin cargo-audit

# 3. 克隆仓库
git clone https://github.com/Gawg-AI/EnerOS.git
cd EnerOS

# 4. 构建验证
cargo build
cargo test
cargo clippy -- -D warnings

项目结构

项目结构

完整目录树

顶层目录说明

crates/ vs os/

Cargo Workspace 配置

核心配置

单个 crate 的 Cargo.toml 示例

关键文件说明

根目录文件

OS 层配置文件

eneros.toml 运行时配置

模块组织原则

1. 单一职责

2. 接口与实现分离

3. 测试组织

4. 模块命名规范

代码组织规范

目录结构规范

二进制 crate 结构

示例：eneros-os crate 结构

构建与测试

构建命令

测试命令

代码质量

CI/CD 流水线

开发工作流

添加新 crate

开发环境准备

相关文档