EnerOS v0.44.0 版本说明

• 发布日期：2026-06-29
• 版本代号：Docs
• 支持状态：稳定（Stable）
• Crate 总数：53
• 测试用例数：6850+
• 贡献者：22 人

版本概述

EnerOS v0.44.0 是「成熟优化」阶段的第四个版本，聚焦文档系统的全面重构与升级。文档是开源项目与开发者之间的桥梁，优秀的文档体系能将学习曲线从数周缩短到数天。本版本对文档站点进行了彻底重构，引入交互式教程、增强型 API 文档与系统化示例库，构建了一套从入门到精通的完整学习路径。

在 v0.43.0 提升开发者体验的基础上，本版本进一步补齐了「知识传递」这一环。新增的交互式教程允许开发者在浏览器中直接运行 Rust 代码片段，无需本地安装即可体验 EnerOS 的核心能力。API 文档从简单的 rustdoc 升级为带有调用关系图、跨引用导航与在线试运行的增强版。示例库按业务场景组织，每个示例都是一个可独立运行的完整项目。

文档站点基于 Astro + Starlight 框架重构，支持中文与英文双语、全文搜索、暗色模式与响应式布局。所有文档源文件纳入版本控制，与代码同步发布，确保文档与代码的一致性。

关键数据

新特性

1. 文档站点重构

文档站点从原有的 Docusaurus 迁移至 Astro + Starlight，获得更好的性能、更灵活的组件定制与更优秀的 SEO 表现。新站点采用三栏布局（导航 / 正文 / 目录），支持中文与英文双语切换、全文搜索、暗色模式与移动端响应式适配。

站点架构

eneros-web/
├── src/
│   ├── content/
│   │   ├── docs/           # 核心文档
│   │   │   ├── quick-start/    # 快速开始
│   │   │   ├── concepts/       # 核心概念
│   │   │   ├── architecture/   # 架构设计
│   │   │   ├── capabilities/   # 能力详解
│   │   │   ├── development/    # 开发指南
│   │   │   ├── security/       # 安全指南
│   │   │   ├── compliance/     # 合规指南
│   │   │   └── releases/       # 版本说明
│   │   ├── tutorials/      # 交互式教程
│   │   ├── examples/       # 示例库
│   │   └── api/            # API 文档
│   ├── components/         # 自定义组件
│   │   ├── CodeRunner.tsx     # 在线代码运行
│   │   ├── ApiReference.tsx   # API 参考
│   │   └── TopologyViewer.tsx # 拓扑可视化
│   └── styles/             # 全局样式
├── astro.config.mjs
└── package.json

文档 frontmatter 规范

---
title: "约束即法律"
description: "EnerOS 物理约束引擎的设计哲学与实现原理"
category: "核心概念"
order: 3
---

多语言配置

// astro.config.mjs
import starlight from '@astrojs/starlight';

export default {
  integrations: [
    starlight({
      title: 'EnerOS',
      defaultLocale: 'zh',
      locales: {
        zh: { label: '简体中文', lang: 'zh-CN' },
        en: { label: 'English', lang: 'en-US' },
      },
      sidebar: [
        { label: '快速开始', link: '/quick-start' },
        { label: '核心概念', link: '/concepts' },
        { label: '架构设计', link: '/architecture' },
        { label: '能力详解', link: '/capabilities' },
        { label: '版本说明', link: '/releases' },
      ],
      search: {
        engine: 'pagefind',
        options: { fuzzy: true },
      },
    }),
  ],
};

2. 交互式教程

新增 24 节交互式教程，覆盖从环境搭建到高级特性的完整学习路径。每节教程包含可运行的代码片段，开发者在浏览器中即可编辑并运行 Rust 代码，实时查看结果。教程基于 WebAssembly 在浏览器中运行 Rust，无需本地安装。

教程目录

在线代码运行组件

// 交互式教程中的可运行代码
use eneros_topology::{NetworkGraph, Bus, BusType, Voltage};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut network = NetworkGraph::new();

    // 添加母线
    network.add_bus(Bus::new(1, BusType::Slack, Voltage::new(1.05, 0.0)))?;
    network.add_bus(Bus::new(2, BusType::PQ, Voltage::new(1.0, 0.0)))?;

    // 查看拓扑
    println!("母线数: {}", network.bus_count());
    println!("岛屿数: {}", network.topology().find_islands().len());

    Ok(())
}

教程页面中的代码块附带「运行」按钮，点击后在浏览器中通过 WebAssembly 执行，输出结果实时显示在代码块下方。

3. API 文档增强

API 文档从标准 rustdoc 升级为增强版，新增调用关系图、跨引用导航、参数说明与在线试运行。所有公共 API 自动生成文档，并与源码同步更新。

增强特性

API 文档生成

use eneros_docs::api::{ApiDocGenerator, DocConfig};

let generator = ApiDocGenerator::new(DocConfig {
    input: "src/",
    output: "docs/api/",
    include_private: false,
    generate_call_graph: true,
    generate_examples: true,
    cross_reference: true,
});

generator.generate().await?;

API 文档结构示例

## `NetworkGraph::add_bus`

添加一条母线到电网拓扑中。

### 签名

```rust
pub fn add_bus(&mut self, bus: Bus) -> Result<BusId, TopologyError>

参数

返回值

返回新分配的母线 ID。若母线 ID 已存在，返回 TopologyError::DuplicateBus。

示例

let bus = Bus::new(1, BusType::PQ, Voltage::new(1.0, 0.0));
let bus_id = network.add_bus(bus)?;

自

v0.40.0

### 4. 示例库

示例库按业务场景组织，包含 36 个可独立运行的完整项目。每个示例包含完整的源码、测试用例、部署配置与说明文档，开发者可直接作为项目起点。

#### 示例分类

| 分类 | 示例数 | 典型示例 |
|------|--------|---------|
| 基础示例 | 8 | 拓扑操作、潮流计算、约束校验 |
| Agent 示例 | 10 | 调度 Agent、预测 Agent、诊断 Agent |
| 协议接入 | 6 | IEC 104、Modbus、MQTT、CoAP |
| 行业方案 | 7 | 微电网、需求响应、新能源、充电桩 |
| 集成示例 | 5 | Prometheus、Grafana、Kafka、Hadoop |

```bash
# 克隆示例库
eneros-cli project new my-project --example economic-dispatch

# 或直接运行示例
cd examples/economic-dispatch
eneros-cli dev run

改进优化

全文搜索

文档站点集成 Pagefind 全文搜索引擎，支持模糊匹配、中文分词与搜索结果高亮。搜索索引在构建时自动生成，无需服务端支持。

文档版本化

每个版本的文档独立保存，支持版本切换。开发者可查看任意版本的文档，了解 API 在不同版本间的差异。

代码示例测试

所有文档中的代码示例纳入 CI 测试，确保代码示例始终可编译、可运行。使用 mdbook-test 或 rustdoc 的 doctest 机制。

# 运行文档测试
cargo test --doc
eneros-cli docs test

暗色模式

文档站点默认跟随系统主题，支持明暗模式切换。代码块在暗色模式下采用深色背景与语法高亮。

Bug 修复

• BG-501：文档站点在移动端目录溢出，已修复响应式布局
• BG-505：中文搜索分词不准确，已切换至 jieba 分词器
• BG-509：API 文档的调用关系图在大项目中渲染过慢，已改为懒加载
• BG-513：交互式教程在 Safari 下 WebAssembly 加载失败，已修复
• BG-517：示例库的部分依赖版本与主项目不一致，已统一对齐

破坏性变更

BC-231：文档 URL 结构变更

文档站点 URL 从 /docs/v0.43/xxx 变更为 /docs/xxx（最新版本）与 /docs/v0.43/xxx（历史版本）。旧 URL 自动重定向。

BC-232：eneros-docs 工具链 API 重构

文档生成工具的 Rust API 进行了重构，自定义文档生成器需适配新接口。

依赖升级

升级指南

从 v0.43.0 升级

本版本无运行时破坏性变更，升级只需更新文档工具链：

cargo update
cd eneros-web && npm install
npm run build

更新本地文档依赖：

[dev-dependencies]
eneros-docs = "0.44"

相关文档

• 文档编写指南 - 文档贡献规范
• 交互式教程 - 在线学习中心
• API 参考 - 完整 API 文档
• 示例库 - 代码示例索引