基于大语言模型的建筑能耗仿真全自动化 Agent
用自然语言描述建筑，自动完成 EnergyPlus 建模、仿真与能耗分析报告生成。
建筑能耗仿真是绿色建筑设计、节能改造的核心手段，但传统流程门槛极高：工程师需手动填写数百个 EnergyPlus 参数、编写 IDF 文件、排查仿真错误，往往非常耗时。
EPlus-Agent 将这一流程完全自动化——
- 用户只需用自然语言描述建筑（"深圳市 5 层办公楼，建筑面积 2000 m²......"）。
- Agent 自动完成意图理解 → 参数配置文件生成 → IDF 建模 → EnergyPlus 仿真 → 能耗报告撰写 → 参数敏感性分析。遇到错误时 LLM 自动诊断并修复。
| 模块 | 语言 | 职责 |
|---|---|---|
EPlus-Agent（Go，cmd/ / internal/） |
Go | LLM 编排、业务流程、会话管理、报告生成 |
| pytools/（内嵌 Python CLI） | Python | EnergyPlus 工具（YAML→IDF 转换、仿真执行、IDF 读写） |
Note
本项目旨在探索 LLM Agent 在建筑能耗仿真领域的一种落地路径，结合 ReAct 推理、多 Agent 协作与自愈修复等技术，提供一套可参考的实现思路。Agent 驱动仿真的方式并不唯一，欢迎基于此思路探索更多变体。
当前版本需要继续进行系统性量化验证，引入标准测试集，并开展多 LLM 对比实验，以提供更客观的参考依据。
pytools/的转换器代码来源于 EnergyPlus-Agent，整合时仅保留 CLI 工具部分，去除了 MCP 协议服务器。
所有 LLM 智能行为均基于统一的 react.Agent 底层，以 ReAct 推理框架为核心驱动力，将规划、工具调用与自愈能力贯穿仿真全流程。
| 分类 | 特性 / 模式 | 说明 | |
|---|---|---|---|
| Agent 推理模式 |
🔄 | ReAct（思考 → 行动 → 观察） | 核心模式，贯穿 Phase 1 / 4 / 6；同一推理引擎，工具集按阶段独立配置 |
| 🧩 | Planner + 并发 Workers | 已实现，用于 Phase 6；Planner 负责规划变体方案，多 Worker 并发执行仿真 | |
| 🔀 | Plan-Execute-Replan | 可接入；执行中动态重规划，适用于方案需在执行时动态调整的复杂场景，例如报告生成场景 | |
| 端到端 自动化 |
🏗️ | 自然语言驱动建模 | 以自然语言描述建筑需求，Agent 多轮对话补全参数，自动生成完整 EnergyPlus IDF 文件，无需任何专业软件操作经验 |
| 📋 | 国家规范合规校验 | 内置 GB 55015-2021《建筑节能与可再生能源利用通用规范》知识库，意图收集阶段自动核验围护结构传热系数、窗墙比、照明及设备功率密度等关键参数的合规性 | |
| 📊 | 智能能耗报告生成 | 仿真完成后自动解析 CSV/ESO 结果，提取年度能耗指标，LLM 生成包含数据摘要与专业分析解读的 Markdown 报告 | |
| 鲁棒性与 自愈能力 |
🔧 | 多层自愈修复 | YAML 生成、IDF 转换、仿真执行三个阶段均内置独立的 LLM 修复循环，可配置每一阶段自动重试的次数 |
| 🛡️ | 错误分类与死循环防护 | 区分环境错误（不可修复）和内容错误（LLM 可修），避免在无效路径上浪费重试；连续 3 次相同错误自动终止，防止无限循环 | |
| RAG 问答 |
📚 | 混合检索问答 | 独立 cmd/ragqa CLI，基于 EnergyPlus Input-Output Reference 文档，混合检索（向量余弦 + BM25 + RRF 融合），支持 HyDE 双路增强与多轮追问上下文复用 |
| 参数分析与 工程设计 |
⚡ | 并发参数敏感性分析 | Planner Agent 先探查 IDF 真实对象名与字段值，再规划多个参数变体；多 Worker 并发仿真（默认 3 路），汇总输出含对比表格与 AI 解读的分析报告 |
| 🔌 | 灵活入口与断点续传 | 支持从任意阶段切入（UserInput / YAML / IDF / 仿真目录），会话状态逐阶段持久化，通过 -resume 无缝恢复中断会话 |
|
| 🔍 | 全流程可观测 | 每阶段 ReAct 推理步骤（思考→工具调用→观察）以结构化 Markdown 完整留存，Token 消耗按阶段统计，行为完全可追溯。例如：output/react_logs/...planner.md |
用户自然语言输入
│
▼
┌───────────────────────────────────────────────────────────┐
│ EPlus-Agent (Go) │
│ │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │Phase 1 │→ │Phase 2 │→ │Phase 3 │→ │Phase 4 │→ ... │
│ │意图收集│ │YAML 生成│ │IDF 转换│ │EPlus 仿真│ │
│ └────────┘ └────────┘ └────────┘ └────────┘ │
│ │
│ ┌────────┐ ┌────────┐ │
│ │Phase 5 │→ │Phase 6 │ │
│ │报告生成│ │参数分析│ │
│ └────────┘ └────────┘ │
│ │
│ 核心引擎：ReAct Agent ＋ Tools Registry ＋ SessionState │
└───────────────────────────────────────────────────────────┘
│ │
▼ ▼
LLM API pytools/（内嵌 Python CLI）
(OpenAI 兼容) │
▼
EnergyPlus 仿真引擎
| 层面 | 实现机制 | 作用 |
|---|---|---|
| 流程管理 | PhaseModule 接口 + Orchestrator |
六阶段统一编排，shouldRunPhase 判断跳过/续传，各模块解耦 |
| 上下文管理 | IntentSummary 跨阶段注入 System Prompt |
Phase 1 生成建筑自然语言摘要后注入 Phase 2～6，LLM 全程持有建筑语义，无需重复询问 |
| 状态管理 | SessionState 逐阶段 JSON 持久化 |
单一数据对象贯穿全流程，记录产物路径、Token 消耗、IDF 快照历史，支持跨进程恢复 |
- 自然语言多轮对话建筑意图解析（Phase 1）
- BuildingIntent 结构化数据提取（建筑信息、几何参数、围护结构、窗户、负荷、进度表、仿真设置）
- GB 55015-2021 建筑节能规范动态查询（Skills 知识库：传热系数、窗墙比、照明/设备功率密度、人员密度、换气次数等 11 张参数表）
- LLM 驱动的 EnergyPlus YAML 配置生成（Phase 2）
- YAML 语法错误自愈修复循环（最多 5 次）
- YAML → EnergyPlus IDF 自动转换（Phase 3）
- IDF 转换失败时 LLM 自动修复 YAML 并重试（最多 8 次）
- EnergyPlus 仿真自动执行（Phase 4）
- 仿真失败时 LLM 读取错误日志、修复 IDF 并重试（最多 10 次）
- 仿真结果 CSV/ESO 解析与指标提取（Phase 5）
- LLM 生成 Markdown 能耗分析报告
- 参数变体规划（Planner ReAct Agent）（Phase 6）
- 并发多变体仿真（信号量控制，默认最多 3 Worker）
- LLM 生成多变体对比分析报告
- 灵活入口：支持从 UserInput / YAML / IDF / SimOutDir 任意阶段切入
- 会话检查点持久化与续传（
-resume <session_id>） - 错误分类系统（环境错误 vs. 内容错误 vs. 仿真错误 vs. 瞬时错误）
-
SameErrorGuard检测 ReAct 死循环（连续 3 次相同错误即终止） - 双输出日志（彩色控制台 + JSON 文件）
- ReAct 推理步骤完整 Markdown 记录
- 按阶段统计 LLM Token 消耗
- Ctrl+C 优雅退出（ctx 感知信号量）
- 可跳过可选阶段（
-skip-report、-skip-param）
- 外墙 / 屋顶材料（Material.Thickness）
- 窗户 U 值（WindowMaterial:SimpleGlazingSystem.UFactor）
- 窗户太阳得热系数 SHGC
- 照明功率密度（Lights.Watts_per_Zone_Floor_Area）
- 设备功率密度（ElectricEquipment.Watts_per_Zone_Floor_Area）
- RAG扩展文档覆盖 — 接入完整 EnergyPlus 文档与工程师参考手册
- 多气候区天气文件 — 内置主要城市 EPW，支持一键切换气候区对比
- 建筑类型模板 — 预置办公、住宅、商业、学校等典型建筑基础模板
- Web UI — 提供浏览器端可视化界面，展示仿真进度与报告
- 报告可视化 — 在 Markdown 报告中嵌入能耗图表（SVG/PNG）
- IDF 几何可视化 — 生成建筑三维几何预览
| 依赖 | 版本 | 说明 |
|---|---|---|
| Go | 1.22+ | 主程序编译运行 |
| Python | 3.12+ | pytools/ CLI 工具 |
| uv | 最新 | Python 依赖管理（pip install uv） |
| EnergyPlus | 25.1.0 | 仿真引擎（需加入 PATH） |
| LLM API | — | 兼容 OpenAI Chat Completions 格式 |
# 安装 Python 依赖
cd pytools && uv sync && cd ..
# 复制并填写配置
cp configs/config.yaml.example configs/config.yaml
# 编辑 configs/config.yaml，填入 LLM API Key 和本地路径
# 运行
go run cmd/main.go -input "深圳 5 层办公楼"| 依赖 | 版本 | 说明 |
|---|---|---|
| Docker | 20.10+ | 容器运行时 |
| Docker Compose | v2+ | 编排工具 |
| LLM API | — | 兼容 OpenAI Chat Completions 格式 |
# 1. 准备气象文件（放入 weather/ 目录）
mkdir -p weather
# 将 Shenzhen.epw 等 EPW 文件复制到 weather/
# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，填入 LLM_API_KEY 和 SESSION_EPW_PATH
# 3. 构建并运行
docker compose run --rm eplus-agent -input "深圳 5 层办公楼"# 完整流程（交互输入建筑描述）
go run cmd/main.go
# 指定建筑描述（跳过交互询问）
go run cmd/main.go -input "深圳市 3 层住宅，400 平方米"
# 同时指定参数分析目标
go run cmd/main.go -input "北京办公楼" -analysis-goal "对比外墙保温 3/5/8 cm"
# 从已有 YAML 文件开始（跳过 Phase 1-2）
go run cmd/main.go -yaml output/yaml/model.yaml
# 从已有 IDF 文件开始（跳过 Phase 1-3）
go run cmd/main.go -idf output/idf/model.idf
# 从已有仿真结果开始（直接生成报告）
go run cmd/main.go -sim-dir output/model/v1
# 续传中断的会话
go run cmd/main.go -resume session_20260323_141945
# 跳过报告生成
go run cmd/main.go -input "..." -skip-report
# 跳过参数分析
go run cmd/main.go -input "..." -skip-param
# 指定 EPW 气象文件
go run cmd/main.go -input "..." -epw /path/to/Beijing.epwoutput/
├── session/
│ └── <session_id>.json # 会话状态快照（每阶段后持久化）
├── yaml/
│ └── <building_name>.yaml # Phase 2 生成的 EnergyPlus 配置
├── idf/
│ └── <building_name>.idf # Phase 3 生成的 IDF 文件
├── <building_name>/
│ ├── v1/ # Phase 4 仿真结果（第 1 次尝试）
│ ├── v2/ # Phase 4 仿真结果（修复后第 2 次）
│ └── ...
├── reports/
│ ├── <building_name>_report.md # Phase 5 能耗分析报告
│ └── <building_name>_param_analysis.md # Phase 6 参数对比报告
├── param_analysis/
│ └── <session_id>/<timestamp>/
│ ├── baseline/sim/ # 基线仿真结果
│ ├── wall_ins_5cm/sim/ # 变体 1 仿真结果
│ └── wall_ins_8cm/sim/ # 变体 2 仿真结果
└── react_logs/
├── <session>_intent.md # Phase 1 ReAct 推理记录
├── <session>_sim_repair.md # Phase 4 修复推理记录
└── <session>_paramanalysis_planner.md # Phase 6 Planner 推理记录
EPlus-Agent/
├── cmd/
│ ├── main.go # CLI 入口，flag 解析
│ └── ragqa/ # 独立 RAG 问答 CLI
├── configs/
│ ├── config.yaml.example # 配置模板（安全，可提交）
│ └── config.yaml # 本地配置（含密钥，已 gitignore）
├── internal/
│ ├── config/ # 配置加载与环境变量覆盖
│ ├── intent/ # Phase 1-2：意图收集与 YAML 生成
│ ├── idfconvert/ # Phase 3：YAML → IDF 转换
│ ├── simulation/ # Phase 4：EnergyPlus 仿真与修复
│ ├── report/ # Phase 5：报告解析与生成
│ ├── paramanalysis/ # Phase 6：参数变体规划与并发仿真
│ ├── react/ # 通用 ReAct Agent（思考→工具→观察）
│ ├── tools/ # LLM 工具注册表
│ ├── orchestrator/ # 主流程编排
│ ├── session/ # 会话状态与 PhaseModule 接口
│ ├── rag/ # RAG 问答（向量检索、BM25、HyDE、RRF）
│ ├── llm/ # LLM 客户端（OpenAI 兼容 + SSE 流）
│ ├── eplusrun/ # pytools 子进程封装
│ ├── fault/ # 错误分类与重试策略
│ ├── logger/ # 双输出结构化日志
│ └── ui/ # 终端交互与彩色输出
├── pytools/ # 内嵌 Python 工具（YAML→IDF、仿真、IDF 读写）
│ ├── main.py # CLI 入口（typer）
│ ├── pyproject.toml # Python 依赖声明
│ └── src/
│ ├── converter_manager.py # 转换流程编排
│ ├── converters/ # 各 EnergyPlus 对象转换器（12 个）
│ ├── runner/ # EnergyPlus 仿真执行器
│ ├── validator/ # Pydantic 数据模型与校验
│ └── utils/ # 日志工具
├── Dockerfile # 多阶段 Docker 构建
├── docker-compose.yml # Docker Compose 部署配置
├── .env.example # 环境变量模板（含 LLM 和 EPW 配置）
└── output/ # 生成文件（gitignore）
pytools/ 是项目内嵌的 Python 工具集，提供以下 CLI 子命令（由 Go 通过子进程调用）：
| 命令 | 功能 |
|---|---|
convert-idf |
将 YAML 配置转换为 EnergyPlus IDF 文件 |
run-simulation |
调用 EnergyPlus 执行仿真 |
edit-idf |
修改 IDF 对象字段（基于 eppy） |
read-idf |
读取 IDF 对象字段（基于 eppy） |
validate-idf |
IDF 合法性验证 |
Go 端通过 internal/eplusrun/runner.go 以子进程方式调用 pytools/main.py，结果经 stdout 标记行（如 IDF_OUTPUT: <path>）传递。