Development Workflow

中文 | English

开发工作流

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

本页概述 EnerOS 的开发工作流：Workspace 组织 / 添加新 Agent / 添加新协议 / 添加新插件 / 调试技巧。完整开发者文档请参阅主仓库 docs/developer-guide.md 与 CONTRIBUTING.md。

Workspace 组织

EnerOS 使用 Cargo workspace 组织 79 个成员：56 库 + 23 二进制 + 3 SDK/宏。完整索引请参阅本 wiki Crate 索引 页。

依赖严格自上而下，禁止反向依赖与循环依赖（详见 分层依赖）。

开发环境

项	要求
Rust	1.75+，edition 2021
平台	Linux x86_64/aarch64（生产）/ Windows & macOS（核心库开发）
推荐组件	rustfmt / clippy / rust-src
IDE	VS Code + rust-analyzer

rustup component add rustfmt clippy rust-src

Windows/macOS 编译核心库（排除 eneros-installer）：

cargo build --workspace --exclude eneros-installer

添加新 Agent

1. 实现 Agent 逻辑：在 crates/eneros-agent/src/agents/ 下新建模块，实现决策循环与消息处理
2. 创建二进制入口：在 crates/eneros-agent/bins/ 下新建目录，包含 Cargo.toml 和 src/main.rs
3. 注册到 workspace：在根 Cargo.toml 的 members 中添加路径
4. 配置 init.toml：在 os/rootfs/files/etc/eneros/init.toml 中添加启动配置（二进制路径 / 启动参数 / 资源配额）
5. 编译验证：

cargo build -p my-agent
cargo test -p eneros-agent

详见主仓库 docs/developer-guide.md §4。

添加新协议适配器

1. 创建适配器模块：在 crates/eneros-device/src/adapters/ 下新建目录
2. 实现 DeviceAdapter trait：参考 crates/eneros-device/src/adapter.rs 中的 trait 定义
3. 注册到 DeviceManager：在 crates/eneros-device/src/adapters/mod.rs 中声明
4. 协议一致性测试：在 tests/protocol_conformance/ 下添加测试用例
5. Fuzz 目标（可选）：在 fuzz/ 下添加 fuzz target

详见主仓库 docs/developer-guide.md §5。

添加新插件

详见本 wiki 运维与插件 页与主仓库 docs/plugin-development.md。

简述：

1. 创建 cdylib crate
2. 实现 Plugin trait + 对应的 ProtocolPlugin / AgentPlugin / AnalysisPlugin trait
3. 用 #[eneros_plugin] 宏自动生成 C ABI 入口
4. 编写 manifest.toml 清单
5. Ed25519 签名
6. 部署到 ~/.eneros/plugins/

调试技巧

rust-analyzer 配置

{
  "rust-analyzer.checkOnSave.command": "clippy",
  "rust-analyzer.cargo.features": "all"
}

LLDB 调试 eneros-api

{
  "type": "lldb",
  "request": "launch",
  "name": "debug eneros-api",
  "cargo": {
    "args": ["build", "--package", "eneros-api"],
    "filter": { "kind": "bin" }
  },
  "args": ["run", "--config", "eneros.toml"],
  "cwd": "${workspaceFolder}"
}

日志级别动态调整

ENEROS_OBSERVABILITY__LOG_LEVEL=debug ./target/release/eneros-api run

或运行时通过 API：

curl -X POST http://localhost:8080/api/config/reload

性能分析

# 生成火焰图
cargo flamegraph --bin eneros-api -- run --config eneros.toml

# 基准测试
cargo bench --workspace

质量门禁

每次 PR 自动执行：

门禁	命令	失败处理
格式化	cargo fmt --all -- --check	阻塞合并
Lint	cargo clippy --workspace --all-targets -- -D warnings	阻塞合并
构建	cargo build --workspace	阻塞合并
测试	cargo test --workspace	阻塞合并
文档	cargo doc --workspace --no-deps	警告
依赖	cargo deny check	阻塞合并
覆盖率	llvm-cov	阈值检查

详见本 wiki 测试策略 页。

提交规范

遵循 CONTRIBUTING.md：

• 提交信息使用 conventional commits（feat: / fix: / docs: / refactor: / test: / chore:）
• 每次 PR 必须更新 CHANGELOG.md 对应版本节
• 新版本发布时将 ROADMAP.md 完成项移到 CHANGELOG.md
• 重大架构决策必须新增 ADR

相关文档

• 主仓库 docs/developer-guide.md — 完整开发者指南
• 主仓库 CONTRIBUTING.md — 贡献指南
• 本 wiki Crate 索引 — 79 个成员清单
• 本 wiki 分层依赖 — 依赖方向规则
• 本 wiki 测试策略 — 测试与质量门禁
• 本 wiki 运维与插件 — 插件开发详情