内容
# Aspen-MCP：面向 Aspen Plus 的基于模式约束的工具调用
一个 [MCP](https://modelcontextprotocol.io) 服务器，提供**类型化、基于模式约束的工具**，用于通过 COM 自动化驱动 [Aspen Plus](https://www.aspentech.com/)，使得语言模型可以**无需编写原始 `win32com` 代码**，即可查询、指定、构建、运行和优化流程图。该项目附带了一个声明式的空白流程图构建工具和一个评估框架，用于基准测试基于模式约束的工具调用与原始代码生成。
> 本研究的代码附带我们在使用本地开放权重的大型语言模型驱动化学过程模拟器方面的研究。有关主要结果背后的故障分析，请参见 [`evaluation/E6_failure_taxonomy.md`](evaluation/E6_failure_taxonomy.md)。
## 为什么
Aspen COM 树无法从预训练中学习，因此要求大型语言模型编写 `win32com` 代码时，会大量产生幻觉变量路径（`Tree.FindNode(...)` 返回 `None`）。类型化工具层消除了这种完全的故障模式：模型调用 `get_stream_data`、`set_block_conditions`、`build_flowsheet_from_spec` 等，模式负责其余部分。
## 内容
| 路径 | 描述 |
|------|-----------|
| `src/aspen_mcp_server.py` | MCP 服务器 — 42 个基于 Aspen COM API 的类型化工具（在 stdio 和 HTTP 传输上具有相同的工具表面） |
| `src/flowsheet_builder.py`、`src/flowsheet_spec.py`、`src/flowsheet_normalize.py`、`src/flowsheet_bkp.py` | 声明式规范 → 可模拟的 `.bkp` 构建工具 |
| `src/com_funnel.py` | 将所有 COM 调用序列化到一个拥有线程（多代理安全） |
| `src/eo_bridge.py`、`src/tea_bridge.py` | 方程导向优化 + 技术经济分析桥（仅编排 - 它们驱动外部 AspenEO/TEA 框架包，不包含在内；参见 `requirements.txt`） |
| `src/Configurations/`、`src/Extract/`、`src/aspen_simulator.py`、`src/utils.py` | 支持 COM/配置层 |
| `evaluation/` | 基准测试框架：代码生成与工具调用、自主合成、路由和 SPEC_OPT 消融（+ `results/` 中的精选结果日志） |
| `demos/` | 独立构建演示 + `showcase.py`，端到端演示（提示 → 构建和收敛的环己烷过程 → 流表） |
| `tests/` | 集成测试（COM 漏斗、MCP 构建、优先级工具套件） |
| `docs/TOOLS.md` | 每个 MCP 工具的参考 |
| `Aspen_Flowsheet/` | 空白模板（`Template file.bkp`）+ 示例过程 |
> 从存储库根目录运行所有命令 — 数据路径（`Aspen_Flowsheet/`、`results/`）相对于它解析。演示、测试和评估包会自动定位 `src/`。
## 要求
- **Windows**，已安装 **Aspen Plus**（COM 自动化；基于 Aspen Plus V14 开发）。
- **Python 3.10+**
- **OpenAI 兼容的 LLM 端点**（本地 vLLM 等），用于工具调用/评估路径。
```bash
pip install -r requirements.txt
```
> ⚠️ **可重复性：** Aspen Plus 是专有的，因此无法在没有 Aspen 许可证 + Windows 的情况下重现实时模拟路径。`results/*.jsonl` 中的精选日志允许您在不运行 Aspen 的情况下检查和重新绘制论文中的数字。
## 验证您的安装（无需 Aspen）
三个自测试套件在没有 Aspen Plus 或 LLM 端点的情况下运行 — 每个都应以 `ALL ... TESTS PASSED` 行结尾：
```bash
python src/flowsheet_normalize.py # 规范化层：别名、SPEC_OPT 推断、名称清理
python tests/test_com_funnel.py # COM 漏斗：单所有者线程序列化、重入、错误
python -m evaluation.test_sandbox_mock # 代码生成沙盒 + 模拟 Aspen 上的故障分类
```
它们一起锻炼了规范化层、并发机制和评估框架的评分路径 — 因此，在将 Aspen 或模型端点引入循环之前，绿色运行意味着存储库已正确连接。
## 快速入门
**1. 运行 MCP 服务器**（有关 stdio 与 HTTP 选项，请参见 `src/aspen_mcp_server.py` 的顶部），并将您的 MCP 客户端（Claude Desktop、OpenClaw 等）指向它。对于 HTTP 传输，请通过 `ASPEN_MCP_TOKEN` 设置可选的承载令牌（请参见 `.env.example`）：
```bash
python src/aspen_mcp_server.py --transport http --host 127.0.0.1 --port 8765
```
**2. 尝试构建工具**（无需 LLM）：
```bash
python demos/demo_build_flowsheet.py # 规范 -> 空白 -> 可模拟的流程图
python demos/demo_build_reaction_spec.py # 一个化学计量反应器流程图
```
**3. 在您的 LLM 端点上运行评估框架：
```bash
export ASPEN_EVAL_LLM_BASE_URL=http://localhost:8000/v1 # 您的 OpenAI 兼容端点
python -m evaluation.check_env # 连接性检查
python -m evaluation.run_2x2 --help # 代码生成与工具调用，每个模型
```
有关完整的框架，请参见 [`evaluation/README.md`](evaluation/README.md)。
**4. 自主合成演示** — 本地模型从一个简短的介绍中设计、构建和运行一个过程：
```bash
python demos/showcase.py # 模型构建了一个环己烷反应器->闪蒸过程，并运行到收敛
```
## 结果与可重复性
该框架产生了论文的发现；`results/` 中的精选日志允许您在没有 Aspen 许可证的情况下检查它们：
- **基于模式约束的工具 >> 代码生成。** 幻觉的 COM 变量路径主导了代码生成的失败；类型化工具层将它们转换为成功或一类更小的*推理*错误。故障分类：[`evaluation/E6_failure_taxonomy.md`](evaluation/E6_failure_taxonomy.md)；权威日志：`results/e3_final_v2.jsonl`（+ 运行历史重复`results/e3_2x2*.jsonl`，`results/e3_rep4_steps16.jsonl`），代码生成：`results/e0_codegen_k*.jsonl`。
- **自主概念合成** — 从一行简短的介绍中构建一个*收敛*的流程图（通过重新打开持久化的工件进行验证）。框架：`evaluation/run_synthesis_bench.py`；日志：`results/synthesis_bench3.jsonl`。
- **SPEC_OPT 消融** — 一个有测量的干预：一个切换隔离一个标准化器修复，以测试它是否移动小型模型。预注册 + 方法 + 结果在 [`evaluation/SPEC_OPT_ABLATION.md`](evaluation/SPEC_OPT_ABLATION.md)；日志：`results/syn_specopt_*.jsonl`。重现：`python -m evaluation.run_specopt_ablation && python -m evaluation.print_specopt_ablation`。
- **异构路由** — 一个静态的读取→小/写入→大策略在较低的令牌和壁钟成本下保留了大部分大型模型的成功。`evaluation/run_routing.py`。
- **技术经济分析** — `run_tea` 自动将任意块名称映射到成本命名法，并计算任何收敛流程图的 CAPEX / OPEX / 年化利润。验证：[`results/tea_validation.md`](results/tea_validation.md)。
## 引用
- **此存储库/ MCP 工具调用研究** — 请参见 [`CITATION.cff`](CITATION.cff)（GitHub 的“引用此存储库”按钮），或引用预印本：
> Son, Y. W., Kim, C., Pak, J. H., Kim, D. W., Lee, K., & Lee, J. M. (2026). 自主流程合成、模拟和分析与本地部署的语言模型代理：Aspen Plus 的开放标准接口。 *ChemRxiv*。 https://doi.org/10.26434/chemrxiv.15006587/v1
```bibtex
@article{Son_Kim_Pak_Kim_Lee_Lee_2026,
title={自主流程合成、模拟和分析与本地部署的语言模型代理：Aspen Plus 的开放标准接口},
DOI={10.26434/chemrxiv.15006587/v1},
author={Son, Yeong Woo and Kim, Chan and Pak, Ji Hun and Kim, Dong Woo and Lee, Kyoungmin and Lee, Jong Min},
year={2026}
}
```
- **Aspen Plus COM 自动化层**（`src/utils.py`、`src/Configurations/`、`src/Extract/`、`src/aspen_simulator.py` — 即，如果您在工具下使用 win32com 框架），请引用：
> Son, Y. W., Kim, C., Pak, J. H., Lee, H., & Lee, J. M. (2026). 基于 transformer 的双环模拟和优化的自动生成过程合成。 *AIChE Journal*，e70489。 https://doi.org/10.1002/aic.70489
```bibtex
@article{son2026automated,
author = {Son, Yeong Woo and Kim, Chan and Pak, Ji Hun and Lee, Hain and Lee, Jong Min},
title = {基于 transformer 的双环模拟和优化的自动生成过程合成},
journal = {AIChE Journal},
year = {2026},
pages = {e70489},
doi = {10.1002/aic.70489}
}
```
- **TEA 方法论**（成本核算框架 `src/tea_bridge.py` 协调） — 手稿正在审查中；其引用将在发布后添加。在此之前，请引用上述框架论文和此存储库。
## 许可证
[MIT](LICENSE)。
