氢元脑 HydroMind —— 氢能园区多智能体协商调度 Demo

AI×未来能源黑客松参赛作品（自命题）。核心理念：园区内每台设备 （光伏 / 电解槽 / 储氢罐 / 加氢站 / 燃料电池车队）都是一个 AI 智能体， 通过结构化协商协议自主完成能源调度，替代"人盯屏幕 + 静态规则"。

运行步骤

# 1. 激活项目根目录的 venv（本仓库上层已建好，含 numpy）
#    Windows Git Bash:
source ../../.venv/Scripts/activate
#    Windows CMD:
..\\..\\.venv\\Scripts\\activate.bat

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动界面
streamlit run app.py

# 4. 跑测试（可选，无头、无网络、约 1 秒）
pytest tests/ -q

浏览器自动打开 http://localhost:8501，五个页签： ①调度大屏 ②智能体协商日志 ③氢路通 ④氢述者 ⑤氢讯通。

功能清单

模块	内容	位置
M1 氢元脑·协商调度（核心）	自研 15 分钟步长离散事件仿真（光伏→电解→储氢→加氢站→车队，24–72h）；光照/分时电价/随机订单全固定种子可复现；基线规则调度 vs 5 设备 Agent + 1 协调者的小时级协商（结构化提案 + 仲裁 + 中文决策纪要）；KPI 对照（满足率/综合成本/弃光率/碳排放/等待时长）；自然语言干预转场景事件并触发重协商	sim/、agents/
M2 氢路通	8 座模拟加氢站，贪心搜索"出发时刻 × 站点"最小化 氢费+时间成本，Plotly 模拟地图	modules/m2_fleet.py
M3 氢述者	从仿真取一批氢，核算绿电占比与碳足迹，模板引擎生成约 300 字中英双语"这克氢的旅程"，LLM 可润色	modules/m3_story.py
M4 氢讯通	4 份自编写合成手册（电解槽/储氢罐/加氢机/压缩机），关键词+二元组检索，模板回答；中文提问英文答、英文提问中文答	modules/m4_assistant.py、data/manuals.py

模式说明（LLM / 演示）

• 所有 LLM 调用封装在 agents/llm_client.py（OpenAI 兼容接口）： 读环境变量 MOONSHOT_API_KEY 或 OPENAI_API_KEY， LLM_BASE_URL 可覆盖（默认 https://api.moonshot.cn/v1），LLM_MODEL 可换模型。
• 检测不到 Key 或调用失败时自动降级为内置启发式"模拟脑"（规则提案 + 模板话术）， Demo 任何时候都能完整运行；侧边栏实时显示"LLM 模式 / 演示模式"。
• 核心仿真与协商从不依赖 LLM，保证评审现场可复现；LLM 仅用于 M3 故事润色与 M4 问答增强。
• 数据全部本地合成，除可选 LLM 外不访问任何外部网络。

测试结果（pytest）

5 passed in 0.68s
tests/test_smoke.py::test_sim_24h_runs_and_is_deterministic   # 24h 跑通 + 同种子逐点复现
tests/test_smoke.py::test_smart_beats_baseline_on_kpi         # 智能体 KPI 改善 ≥5%
tests/test_smoke.py::test_negotiation_log_is_nonempty_and_structured
tests/test_smoke.py::test_intervention_parser_and_event_sim   # NL 干预 → 事件 → 重协商
tests/test_smoke.py::test_runtime_budget                      # 性能预算

24h 晴天场景（seed=42）实测 KPI 对照：

指标	基线调度	智能体调度	改善
综合成本（元，电费−收入）	−31,642	−36,386	+15.0%
弃光率	78%	36%	−53.8%
碳排放（kg CO₂）	14,472	6,946	−52.0%
氢需求满足率	100%	100%	持平

智能体优势来源：低价窗口提前补氢 + 白天用富余光伏制氢（基线规则只在谷电时段开机，白天弃光严重）。 改善来自确定性规则与固定种子，可复现，非碰运气。

目录结构

hydromind/
├── app.py                 # Streamlit 入口（五页签）
├── requirements.txt
├── README.md
├── sim/                   # M1 仿真核心：scenario / engine / models / kpi
├── agents/                # baseline 基线、smart 智能体协商、llm_client、intervene 干预解析
├── modules/               # m2_fleet / m3_story / m4_assistant
├── data/                  # manuals.py 合成设备手册（中英双语）
└── tests/                 # test_smoke.py 冒烟测试

已知取舍

• 智能体的需求/光照"预测"使用场景画像函数（理想预测），未做预测误差建模；
• 协商为单轮提案+仲裁（含反对与妥协话术），未实现多轮博弈；
• 电解槽启停成本、衰减、压缩机动态未建模；碳排放只计电网电环节；
• M2 地图为虚拟网格坐标，未接真实地理数据。