内容
# 生态循环建筑代理
**一个用于EnergyPlus建筑的、受保护的、开源的本地LLM监管控制器。**
生态循环连接EnergyPlus 26.1.0的遥测数据到一个持久的SQLite总线，暴露出通过官方模型上下文协议SDK的狭窄的建筑控制工具，使用本地Ollama模型选择评估的设定点候选，验证每个决策通过一个独立的确定性安全层，并应用支持的恒温器调度执行器通过PyEnergyPlus。
<!-- BEGIN VERIFIED_EVALUATION_STATUS -->
> 证据状态：执行器证明，一天的闭环接受测试，以及匹配的七天EnergyPlus 26.1.0比较已经验证。在配置的芝加哥周，生态循环将占用温度合规性从67.77%提高到90.31%，但增加了10.52%的设施电力，并提高了5.32%的峰值需求。结果是测量的舒适度/能源权衡，而不是节能声明。
<!-- END VERIFIED_EVALUATION_STATUS -->
规范的运行身份，测量的值和发布状态位于 [`docs/results.md`](docs/results.md)。实现和测试历史位于 [`docs/progress.md`](docs/progress.md)。
## 为什么这很重要
传统的调度程序无法响应占用率、天气、舒适度、关税、碳强度或需求的快速变化。直接将语言模型置于控制循环中是不安全且难以审计的。生态循环将灵活的候选人选择与确定性约束、有界能力、持久的证据和自动故障保护控制分开。
## 架构
```mermaid
flowchart LR
E[EnergyPlus Runtime API] -->|telemetry| B[(SQLite WAL bus)]
B --> M[FastMCP stdio tools]
M <--> O[Local Ollama host]
M --> S[Safety validator]
S -->|fresh validated action| B
B -->|schedule actuator| E
E --> R[Official output parser]
R --> D[Dashboard and reports]
```
[Rendered SVG architecture](docs/diagrams/system-architecture.svg) ·
[Rendered PNG architecture](docs/diagrams/system-architecture.png)
完整的回调、协议、安全、重放和安全设计在 [`docs/architecture.md`](docs/architecture.md)。
## 证据一览
- **执行器证明：** 一个真实的EnergyPlus接受运行改变了主动恒温器调度执行器，并记录了后来的物理响应。它不是作为代理-能量比较呈现的。
- **闭环证明：** 一个真实的一天运行锻炼了EnergyPlus、SQLite、MCP_stdio、本地推理、确定性验证、执行和后续遥测。其测量的舒适度/能源权衡被报告，而不是将其转化为节能声明。
- **头条评估：** 匹配的代表性周通过了官方的EnergyPlus输出、遥测和出处检查。它发现了22.54个百分点的舒适度合规性增益，同时伴随着10.52%更高的电力，确定了下一个控制策略迭代必须消除的能源惩罚。
## 快速入门
先决条件：
- Python 3.11
- EnergyPlus 26.1.0单独安装
- Ollama与`qwen3:8b`（或其他工具 capable 本地模型）
- 授权的EPW天气文件
### Windows依赖设置
安装Python、`uv`和Ollama：
```powershell
winget install --id Python.Python.3.11 --exact
winget install --id astral-sh.uv --exact
winget install --id Ollama.Ollama --exact
```
下载官方EnergyPlus 26.1.0 Windows存档并在提取前验证固定的摘要：
```powershell
$archive = "$env:TEMP\EnergyPlus-26.1.0-Windows-x86_64.zip"
Invoke-WebRequest `
"https://github.com/NatLabRockies/EnergyPlus/releases/download/v26.1.0/EnergyPlus-26.1.0-6f2e40d102-Windows-x86_64.zip" `
-OutFile $archive
(Get-FileHash $archive -Algorithm SHA256).Hash.ToLower()
# Expected:
# 0bb6932d277eed62f996b625f37c533b8c35f9af0c53710d961d8442fc4e70b3
Expand-Archive $archive -DestinationPath $env:USERPROFILE
$env:ENERGYPLUS_HOME = `
"$env:USERPROFILE\EnergyPlus-26.1.0-6f2e40d102-Windows-x86_64"
```
从该发行版安装检查和默认的芝加哥TMY3天气文件（或将`ECOLOOP_WEATHER_PATH`设置为另一个经过验证的EPW）：
```powershell
py -3.11 scripts/install_weather.py --energyplus-home "$env:ENERGYPLUS_HOME"
```
安装程序还可以检索确切的固定版本存档本身：
```powershell
py -3.11 scripts/install_weather.py --download
```
启动Ollama并安装默认的本地模型：
```powershell
ollama serve
ollama pull qwen3:8b
```
EnergyPlus在Linux和macOS上单独安装，从官方的EnergyPlus发布页面上的匹配26.1.0资产。验证平台资产与发布的校验和，设置`ENERGYPLUS_HOME`为提取的安装目录，并运行相同的天气安装程序。
### 项目设置
```powershell
py -3.11 -m pip install uv
uv sync --extra dev --locked
Copy-Item .env.example .env
uv run python -m ecoloop doctor
uv run python -m ecoloop prepare-model
uv run python -m ecoloop demo
```
Pip兼容安装：
```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m ecoloop doctor
```
Linux/macOS Pip兼容设置：
```bash
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
cp .env.example .env
python -m ecoloop doctor
```
医生命令在任何真正的演示开始之前验证EnergyPlus构建、本地模型、天气、模型和可写工件路径。
`python -m ecoloop demo` 永远不会启用假模式。它运行预飞行检查，重用或创建经过验证的演示周期基线，启动仪表板，启动真正的受控过程，打印两个运行ID和本地URL，并将受控ID写入 `runs/current_run.txt`。仪表板在干净运行后保持可用，直到Ctrl+C关闭其子进程。
以不改变模拟时间或计算能量的方式记录友好节奏：
```powershell
uv run python -m ecoloop demo --display-delay-seconds 0.15
```
## 命令
```text
python -m ecoloop doctor
python -m ecoloop prepare-model
python -m ecoloop run baseline --period smoke
python -m ecoloop run rule --period smoke
python -m ecoloop run agent --period smoke
python -m ecoloop compare BASELINE_RUN_ID AGENT_RUN_ID
python -m ecoloop dashboard
python -m ecoloop demo
python -m ecoloop replay RUN_ID
python -m ecoloop export RUN_ID
python -m ecoloop package-submission
```
## 检查MCP服务器
生产服务器使用stdio并仅公开有界的生态循环工具。从存储库根目录运行官方的 [MCP Inspector](https://github.com/modelcontextprotocol/inspector)：
```powershell
npx @modelcontextprotocol/inspector -- .\.venv\Scripts\python.exe -m ecoloop.mcp.server
```
在Linux或macOS上：
```bash
npx @modelcontextprotocol/inspector -- .venv/bin/python -m ecoloop.mcp.server
```
打开Inspector打印的本地URL，选择stdio，列出工具，并调用具有现有运行ID的只读工具 `get_last_energyplus_errors`。控制影响的调用将被验证并写入SQLite审计总线。
## 真实数据策略
默认命令永远不会伪造遥测、能量、舒适度或节省。仅在显式 `--fake` 标志用于测试和CI时才提供合成操作，并相应地标记。失败或不完整的EnergyPlus运行无法产生节能声明。
## 存储库布局
```text
src/ecoloop/ 控制器、MCP、EnergyPlus、存储、CLI、仪表板
tests/ 单元、协议集成和依赖感知真实测试
models/base/ 版本匹配的源模型和出处
models/generated/ 可重复的基线、受控和重放模型
config/ 版本控制的默认值
docs/ 架构、方法论、操作和结果
presentation/ 提供的模板和完成的幻灯片
runs/ 本地SQLite总线和EnergyPlus运行工件
submission/ 可重复的提交包
```
## 截图
存储库保留文件名稳定，以便可以替换提交截图而不更改文档链接：
- `docs/images/live-operations.png`：捕获 **实时操作**，并显示所选证据运行ID、周期、状态、模拟时钟、活动设定点和最新提议/应用操作可见。
- `docs/images/baseline-vs-agent.png`：仅在仪表板显示 `兼容的已完成真实运行` 时捕获 **基线 vs 代理**，并保持两个运行选择器和兼容性横幅可见。
- `docs/images/decision-trace.png`：捕获 **代理决策**，并显示所选操作、提议值与应用值、安全结果、原因代码、延迟和MCP跟踪可见。
- `docs/images/reliability.png`：捕获 **可靠性和错误**，并显示超时、故障保护、钳位和EnergyPlus严重性计数可见。
不要裁剪运行身份或 `REAL RUN REPLAY` 横幅。如果匹配的周不完整，请显示仪表板的诚实不完整状态，而不是用假数据或无关的周期替换。
## 评估
基线是具有未占用回退的可靠固定占用调度。基线和受控案例必须使用相同的模型、天气、日期、时间步长和内部负载。官方能源总额从EnergyPlus输出CSV或SQLite中解析，并与运行时遥测进行交叉检查。舒适度、可靠性、延迟、成本、碳和独立燃料指标在相同的周期状态门控下报告。参见 [`docs/methodology.md`](docs/methodology.md)。
## 限制
EnergyPlus和天气是外部资产；没有它们就无法验证真实集成。可选执行器在发现之前被禁用。候选人评分者是透明的有界启发式/预测评分，而不是完整的模型预测控制器。参见 [`docs/limitations.md`](docs/limitations.md)。
## 许可
生态循环源代码在MIT许可下。EnergyPlus、示例模型、天气数据、Ollama和本地模型权重保留其自身的许可。参见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。
