Aspen Custom Modeler 自动化（V11 COM 真机配方 v1.2.0）

v1.2.0（2026-10-04）：在 v1.1.0 全链路真机验证基础上，用 10 个真实模型案例全部复现，固化出 4 条新铁律（反斜杠路径、单实例孤儿清理、模式感知 Run、看门狗守护 Run），并修正了 v1.1.0 对 HeatedCube/FiveTank/NonIsothermalReactor "可 Run" 的误判——它们经此 COM 路径会挂起（已用看门狗安全收尾，属已知限制）。本文件是索引 + 铁律；详细配方见 references/v11_com_recipes.md；10 个可运行范本见 examples/case01..case10*.py（共用 examples/_acm_helper.py）。

0. 能不能用 Python 调 ACM？——能，已全链路真机验证

本机实测证据链（关键调用 + 真实返回值）：

# 连接（win32com 动态派发，非 comtypes）
app = win32com.client.dynamic.Dispatch(pythoncom.GetActiveObject(CLSID)
        .QueryInterface(pythoncom.IID_IDispatch))
app.Version                          -> '37.0'          # V11.0 内部版本号
app.Name                             -> 'Aspen Custom Modeler'
app.ActiveDocument                   -> 已打开的 .acmf
doc.Flowsheet.BOIL1.Q.Value          -> 4.0                     # 读变量（点号路径）
doc.Flowsheet.BOIL1.Q.Spec="fixed"; .Value=5.0 -> 回读 5.0      # 写变量
doc.Flowsheet.BOIL1.Q.Spec          -> 'Fixed'
app.Simulation.Run(True)             -> None; State='Paused'   # 稳态求解（收敛后暂停=成功）
app.Simulation.Tasks (via fs.Tasks)  -> Count/Name/Active      # 任务
app.Quit() + taskkill               -> 干净退出，无残留

注册表实测：ProgID ACM Application（CLSID {FDE14674-8E3D-0370-878A-2E97C127D967}），
LocalServer32 = D:\Aspen V11\AMSystem V11.0\Bin\AspenModeler.exe /acm /Automation。

⚡ 铁律（v1.2.0 本机真机踩出来的，照做即可）

1. ⚠️ COM 层用 win32com.client.dynamic（动态派发），不是 comtypes、也不是 win32com.genache/EnsureDispatch。
• comtypes：能连接、能读属性，但 Run 这种长调用会卡死/崩溃服务器——comtypes 不泵送 Windows 消息，ACM 在 Run 期间的事件回调无法投递 → 远程过程调用失败/RPC 服务器不可用，且会污染后续连接。不可用。
• win32com.client.gencache.EnsureDispatch("ACM Application")：直接报 This COM object can not automate the makepy process（ACM 类型库无标准 typelib，无法早绑定）。不可用。
• win32com.client.dynamic.Dispatch(obj) + 先 QueryInterface(pythoncom.IID_IDispatch)（因为 GetActiveObject 返回的是 PyIUnknown）：全链路可用，已逐节点验证。 这是本 skill 的唯一正确路线。
• 注：社区 ACM MCP Server 用 comtypes 并自行处理了消息泵/线程；对单脚本自动化，win32com.dynamic 最简单且本机验证可靠。
2. ⚠️ 打开文件用「子进程带 .acmf 启动 + GetActiveObject 挂载」。
3. Python 必须 64 位，与 ACM V11（64 位）位宽一致，否则 COM 连不上。
4. GetActiveObject 需轮询 + 等文档真正就绪：启动后约 8 秒 COM 服务器才就绪，循环 sleep 1s 最多 ~40 次；连上后还要轮询 ActiveDocument.Name 直到等于文件名，否则可能挂到空的 'Untitled' 文档上。
5. ⚠️ 变量用「点号路径」读/写（dynamic dot-notation，本机验证，核心差异点）：
• 读：val = doc.Flowsheet.B1.Tank.h.Value（等价 doc.Flowsheet.Blocks("B1").Tank.h.Value）
• 写（先固定再赋值）：doc.Flowsheet.B1.Q.Spec = "fixed" 然后 doc.Flowsheet.B1.Q.Value = 5.0
• ACM 没有 GetVariable/SetVariable 方法！ 变量是 Flowsheet 上按「块名 → 变量名」动态解析的属性（GetIDsOfNames）。doc.Variables/sim.Variables 只是整数计数，不是集合。
• 变量名从 ACM GUI 的 Variable Explorer 抄（点号路径如 B1.Tank.h）。
6. ⚠️ 仿真对象在 app.Simulation（不在 doc 上，也不在 doc.Simulation）。本机验证：
• app.Simulation.Run(True) 稳态、app.Simulation.Run(False) 动态
• app.Simulation.Reset() 复位
• app.Simulation.State（'Ready'/'Paused'/'Running'/...）、app.Simulation.RunMode（'Steady State'/'Dynamic'/'Optimization'/'Estimation'）
• doc.Run 也存在，但一律用 app.Simulation.Run 更稳。
7. ⚠️【新】文件路径必须反斜杠规范化（os.path.normpath）。
8. ⚠️【新】先杀干净单实例 + 等进程消失再启动。
9. 稳态运行 Run(True)：
• 干净稳态模型（SSMeth）：返回 None，State='Paused' → 求解收敛后暂停，视为成功。
• 部分稳态模型（BTXCDI / VAMReactor / Absorber）：抛 STS_F_Failure（COM 错误 189）但 State 仍到达 'Paused' —— 这是模型自身收敛状态（示例文件未必完全收敛），不是自动化故障。判定成功应以 State=='Paused' 为准，异常可容错捕获。
10. ⚠️【新】模式感知 Run（10 案例复现的关键修正）：
• 稳态：Run(True) → Paused（成功；可容忍 STS_F_Failure）。
• 可跑通动态 / 估算（Crystallizer、JacketedReactor、EUROKIN1）：Run(True)→Paused 锁初值，再 Run(False)→Running 进入动态。
• 挂起模型（HeatedCube、FiveTank、NonIsothermalReactor）：Run(True) 与 Run(False) 经此 COM 路径都会挂起不返回（bash timeout 杀掉，exit=124）。
11. 动态运行 + 阶跃扰动（仅对"可跑通动态"模型，见铁律 10）：
• 标准流程（与 ACM MCP Server 一致）：Run(True) 锁初值 → Run(False) 到极小时间（锁定状态变量）→ 再 set_variable（写变量）施加阶跃 → 继续 Run(False) 逐点读变量。
• 绝不能在第一次 Run(False) 之前 set_variable——否则 ACM 重初始化状态变量，看不到瞬态。
• 任务（动态靠 Task 激活）：doc.Flowsheet.Tasks.Count、doc.Flowsheet.Tasks.Item(i).Name、.Active（bool，激活：task.Active = True）。
12. ⚠️【新】Run 必须用看门狗守护，且不能在主线程裸等。
• 部分模型 Run 会永久挂起（铁律 10），若在主线程直接调用会卡死整个脚本。
• 做法（_acm_helper.run_sim）：把 Run 放进独立工作线程，线程内重新 GetActiveObject 挂载同一个 ACM 实例（COM 对象属于该线程，避开跨线程调用 <unknown>.Run 的坑），再用 t.join(timeout) 做看门狗：正常模型秒回，挂起模型到时后外部 taskkill 干净收尾，脚本绝不卡死。
• 普通顺序脚本（无看门狗）务必用 timeout 包一层（如 timeout 120 python caseXX.py），否则可能一直挂着。
13. ⚠️ 进程卫生：结束务必 app.Quit() + taskkill /F /IM AspenModeler.exe（同时清 Modeler.exe）；动态运行未停时 Quit 会 RPC 失败，需先 app.Simulation.Reset() 或 taskkill 兜底。残留进程会污染后续连接（连上但 ActiveDocument 指向旧/坏会话）。

📊 10 案例复现矩阵（v1.2.0 真机验证，全部连上且读值正确）

规律：稳态全部可 Run（容错 STS_F_Failure）；可跑通动态/估算走 Run(True)→Paused 再 Run(False)→Running；HeatedCube/FiveTank/NonIsothermalReactor 三类（纯动态含多 Task、多块动态、优化）经此 COM 路径会挂起，属已知限制。
⏱ 注意：Crystallizer / JacketedReactor 的稳态求解较慢（实测 Run(True) 约 60s+），看门狗超时须给到 ≥150s，否则会被误判为挂起（已在该两个案例脚本中设 timeout=150）。

环境

pip install pywin32        # 唯一需要的包（用 win32com.client.dynamic，不是 comtypes）

• 仅 Windows；ACM V11 为 64 位 → 必须 64 位 Python。本机验证环境：
• ACM 安装路径（本机）：D:\Aspen V11\Aspen Custom Modeler V11.0；exe =
• 随附示例（练手用）：D:\Aspen V11\Aspen Custom Modeler V11.0\Examples\

标准工作流（全部已真机验证）

第 1 步：连接（✅ 验证）

推荐直接用 _acm_helper.launch_and_attach()（已封装铁律 2/4/7/8：normpath + 杀残留 + 等就绪 + 等文档加载）：

import os, sys
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from _acm_helper import launch_and_attach, safe_quit

EXAMPLE = r"D:\Aspen V11\Aspen Custom Modeler V11.0\Examples\BTXCDI\btxcdi.acmf"
app = launch_and_attach(EXAMPLE)
if app is None:
    raise SystemExit("连接失败")
doc = app.ActiveDocument
sim = app.Simulation

完整可运行范本：examples/case01_connect_readwrite_btxcdi.py（本机真机通过：启动→挂载→读 23 块→读/写 BOIL1.Q 4.0→5.0→还原）。

第 2 步：读写变量（✅ 验证，点号路径）

```python
val = doc.Flowsheet.BOIL1.Q.Value # 读 -> 4.0
doc.Flowsheet.BOIL1.Q.Spec = "fixed" # 固定
doc.Flows