SAM 二次开发总览与证据分级 / SAM Secondary Development Overview and Evidence Levels
📅 创建时间：2026-07-23
🏷️ 标签：#SAM #二次开发 #架构 #API验证
📚 前置知识：Python、C++/Qt、有限元基础
📖 系列导航：总目录 · 下一篇：01-plugin-p0-p5
📋 文档目标
本文档建立 SAM V2026 二次开发的完整心智模型，重点解决以下问题：
- SAM 为什么同时使用 Python 2、C++、Qt DLL 和
.pyd - 插件如何自动进入 SAM 菜单并调用参数化建模算法
- Python 2 与 C++ 各自适合承担什么工作
- 如何把 C++ 方法挂载到
mdb.models[...]或parts[...]对象 - 如何读取、创建和增量修改 SAM 网格
- 哪些 Python 2 API 已经在真实模型中验证成功
- 哪些 Abaqus 风格写法在 SAM 中已经明确失败
- 如何把 Agent 作为插件接入 SAM，并只调用白名单建模工具
- 如何建立“不猜 API”的验证与回归流程
证据分级：先区分“能调用”和“真正可用”
SAM 与 Abaqus 的 Python 对象外观相似，但底层绑定不同。本文使用四级证据：
| 等级 | 含义 | 可以如何使用 |
|---|---|---|
| A：端到端验证 | 已在 SAM V2026 中执行，保存新 .sam，重新检查结果或完成后续计算 | 可作为正式工具基础 |
| B：运行时验证 | API 调用成功，模型对象或文件能够保存，但下游求解链尚未完全通过 | 可用，但必须保留后验验证 |
| C：官方源码证据 | 出现在老师发布的 SDK、7231 手册或官方示例源码 | 可用于 C++ 插件开发，仍需在本机版本做最小探针 |
| X：明确失败 | SAM 已返回 TypeError、AttributeError、RuntimeError，或输出模型恶化 | 禁止继续按该写法使用 |
核心规则：
dir()中出现一个方法，只能证明“名称存在”；调用未报错只能证明“对象接受了调用”；保存成功也不代表导出的 INP 和求解器一定有效。
第1部分：SAM 二次开发的真实架构
1.1 SAM 不是单语言系统
SAM 的扩展结构可以概括为：
text
┌─────────────────────────────────────────────────────────────────────┐
│ SAM 主程序 │
├─────────────────────────────────────────────────────────────────────┤
│ customApp.py │
│ └─ 创建主窗口，注册 Part / Property / ShipTools 等模块 │
│ │
│ Qt Toolset DLL │
│ └─ SAM.Pre.*Toolset.dll：菜单、工具栏、对话框、视口选择控件 │
│ │
│ Python 2.7 │
│ └─ mdb / session / Set / Section / Step / Load / 保存与导出 │
│ │
│ C++ Kernel PYD │
│ └─ *.pyd：几何算法、网格处理、结果读取、Part/Model 扩展方法 │
│ │
│ 本地 Agent 服务（建议独立进程） │
│ └─ 自然语言理解、工具选择、任务状态；不直接任意执行 SAM 代码 │
└─────────────────────────────────────────────────────────────────────┘当前安装环境已经确认：
text
SAM 安装目录：D:\Program Files\SAM
Python： 2.7.18，64 bit
插件目录： D:\Program Files\SAM\Release\FilePlugin
Python 模块： D:\Program Files\SAM\Python271.2 两个二进制产物承担不同职责
一个完整的 SAM 专业插件通常包含两个产物：
text
SAM.Pre.MyToolset.dll ← GUI 插件
MyKernel.pyd ← C++ 内核 / Python 2 扩展GUI DLL 负责：
- 自动注册菜单和工具栏
- 显示
SAMForm/SAMDataDialog - 获取文本参数和视口选择对象
- 构造
omuArguments - 通过 SAM 命令系统调用 Python 2 或
.pyd
内核 PYD 负责：
- 读取当前模型和 Part
- 执行复杂几何、网格与拓扑算法
- 把方法注册到 Python 模块、Model 或 Part 对象
- 返回计算结果或增量写入模型
1.3 为什么已有插件能运行，但当前仓库不一定能重新编译
7231/SAM二次开发手册.doc 明确说明，完整 SAMSDK 应包含：
text
SAMSDK/
├── include/ # SAM C++ 接口头文件
├── include/guiProject/ # GUI 接口头文件
├── libs/ # Debug / Release 链接库
└── ThridPartys/ # Qt、OrientCommon、TCMalloc、CM2 等当前 OpenOLTranSim-main/SDK.zip 只看到 .lib/.dll，没有完整头文件和第三方开发目录。这意味着：
- 已经编译好的
.dll/.pyd仍可运行，因为运行期不需要头文件； - 从源码重新编译时，仍需要老师所述的完整 SAMSDK；
- 示例 CMake 中的
LIBS_SAMSDK_ROOT是编译期开发包路径，不是 SAM 安装目录。