SAM 二次开发知识体系 / SAM Secondary Development Knowledge System

📅 创建时间：2026-07-23
🏷️ 标签：#SAM #Python2 #C++ #Qt插件 #参数化建模 #Agent
📚 定位：SAM V2026 二次开发系列总目录
⚠️ 原则：实测、SDK 源码和失败记录分级保存；禁止根据 Abaqus 同名接口猜测 SAM 参数。

---

系列目标

这一组文档不把所有内容堆在一篇里，而是按“先理解架构，再掌握接口，最后建设 Agent 工具链”的顺序组织。每篇只回答一个核心问题。

推荐学习顺序

00 总览与证据分级
   ↓
01 Qt Toolset：P0 → P5
   ↓
02 PYD 与 Fragment 注册
   ├──────────────┐
   ↓              ↓
03 Python 2 API   04 C++ SDK
   └──────┬───────┘
          ↓
05 参数化构件建模
          ↓
06 Agent 插件架构
          ↓
07 API 验证工作流
          ↓
08 真实案例与路线图
   ↓
09 架构总览与系列索引
   ↓
10 GUI、Toolset 与交互类 API
   ↓
11 命令桥、Python 与 PYD 扩展 API
   ↓
12 数据模型、Part 与 Mesh API
   ↓
13 场景、显示表示与渲染 API
   ↓
14 插件编译、部署与故障排查

SAM 二次开发的五层结构

GUI and Toolset
  -> Command and Python bridge
  -> PYD module and Fragment
  -> Model / Part / Mesh domain objects
  -> Scene and rendering representation

每层解决不同问题。

GUI 层收集用户意图，管理菜单、Mode、Form 和 Dialog。 它不应直接成为模型数据所有者。

Command 层把用户意图转换为可验证参数，并进入脚本或原生调用。 它负责调用边界、错误和必要的撤销语义。

PYD 与 Fragment 层把 C++ 能力注册到 Python 和目标对象。 模块名、初始化入口、对象挂载位置和回收顺序都属于协议。

数据模型层拥有 Model、Part、Feature、Mesh 和结果对象。 修改必须维护稳定引用、版本和持久化。

Scene 层只维护显示表示。 模型成功但显示未刷新，与模型本身失败是不同问题。

证据分级

SAM 接口结论按来源和验证深度记录。

Documentation
  -> matching headers / source examples
  -> GUI replay record
  -> runtime inspection
  -> minimal invocation
  -> save and reopen
  -> export and solver verification

文档和源码确认设计意图与静态接口。 它们不一定与当前安装二进制完全匹配。

GUI 重放日志证明界面尝试了命令。 如果操作随后失败，日志不能证明 API 可用。

运行时 dir() 证明成员可见。 它不能证明参数正确、修改有效或能够保存。

最小调用、状态差异、保存重开和下游求解逐步提高证据强度。

证据记录模板

每条验证记录应包含：

• SAM 版本与构建；
• 操作系统；
• 插件提交和二进制哈希；
• Python 版本；
• 模型副本；
• 对象路径和运行时类型；
• 输入参数；
• 调用前后状态；
• 异常和日志；
• 已通过的 Gate；
• 已知失败和限制；
• 验证日期。

没有环境和对象状态的“成功”无法复现。

最小探针原则

探索未知接口时：

1. 使用模型副本；
2. 默认不覆盖保存；
3. 一次只改变一个参数；
4. 先只读再修改；
5. 保存调用前摘要；
6. 捕获异常类型和消息；
7. 比较对象数量与属性；
8. 记录失败参数；
9. 高风险调用放在可重启进程；
10. 通过内存验证后再进入持久化。

探针的目标是产生可反驳证据，不是尽快找到一个不报错的写法。

Python 2 约束

本系列涉及嵌入式 Python 2 环境。

开发时必须确认：

• 解释器具体版本；
• 字节字符串与 Unicode；
• 扩展模块初始化入口；
• 编译器与运行库；
• GIL 和线程；
• 异常边界；
• 中文路径；
• 模块清理顺序。

Python 3 示例不能直接改名后套用。

C++ SDK 约束

C++ SDK 需要处理：

• 头文件与二进制版本；
• ABI；
• 对象所有权；
• 指针生命周期；
• Repository 和稳定 ID；
• 错误与异常；
• GUI 线程边界；
• 插件加载与卸载；
• Debug/Release 与位数；
• 部署依赖。

头文件编译通过只是静态证据。 最终包仍要在干净环境真实加载。

插件生命周期

discover DLL / PYD
  -> validate package and dependencies
  -> load module
  -> register GUI and Python capabilities
  -> execute commands and tasks
  -> stop callbacks and workers
  -> unregister
  -> unload

加载只是生命周期的一小部分。 卸载前必须确认对象、回调、线程和函数指针全部失效。

无法证明静止时，宁可延迟卸载或重启应用，也不要强制关闭模块。

Model 与 Part 选择

Model 级能力适合：

• 多 Part 协调；
• 导入导出；
• Step 和全局工况；
• ODB/VTK；
• 模型级批处理。

Part 级能力适合：

• 节点和单元；
• 局部几何；
• 参数化构件；
• Mesh 修改；
• Part 集合和属性。

能力应挂在语义所有者上，避免反复传递名称和模糊生命周期。

模型修改事务

参数化、修复和批量修改不能逐步污染当前模型。

validate input
  -> freeze model revision
  -> build candidate change
  -> validate candidate
  -> commit atomically
  -> refresh scene

失败时撤销本次全部新增。 后台结果携带输入 revision，旧结果不能覆盖新模型。

显示刷新边界

Scene、Representation 和 GPU 资源是模型的派生显示状态。

模型修改成功后，通过变更事件触发场景重建。 显示失败不应破坏领域模型。

排查“模型改了但界面没变化”时，分开验证：

1. Model/Part 状态；
2. Mesh 数据；
3. Scene 对象；
4. Representation；
5. Renderer 和 Viewport；
6. GPU 资源。

七级验收门

Gate 1: call succeeds
Gate 2: in-memory state is correct
Gate 3: save succeeds
Gate 4: reopen preserves objects
Gate 5: references remain correct
Gate 6: export is complete
Gate 7: solver accepts and runs

不涉及求解的能力可以明确停在相应 Gate。 不能因为任务只需要显示，就虚构已经通过求解验证。

Agent 工具化原则

Agent 只能调用经过验证的白名单工具。

每个工具定义：

• 名称和用途；
• JSON Schema；
• 权限；
• 前置对象状态；
• 是否有副作用；
• 是否需要确认；
• 幂等性；
• 超时和取消；
• 结果摘要；
• 审计字段。

模型提出意图，确定性执行器校验并调用 SAM。 不能让模型任意执行脚本或拼接命令。

构建与部署

发布前检查：

• Qt 和 SAM SDK 版本；
• 编译器与运行库；
• x64/x86；
• Debug/Release；
• DLL/PYD 导出符号；
• 传递依赖；
• 搜索路径；
• 插件清单；
• 干净机器加载；
• 版本回滚。

“本机能加载”不能替代最终包验证。

回归策略

快速回归覆盖模块加载、对象发现和最小调用。 每日回归覆盖保存重开和导出。 发布回归覆盖真实模型、求解与部署矩阵。

失败记录保留最小模型、脚本、日志和环境。

文档使用规则

• 先读总览确认证据等级；
• 再按任务选择对象层；
• 复制示例前检查版本；
• 未验证参数不得写成事实；
• 成功与失败都进入记录；
• 新证据更新对应专题；
• 总目录只维护导航和共同规则。

系列完成标准

完成本系列后应能：

• 解释 SAM 混合架构；
• 编译和部署最小插件；
• 注册 PYD 与 Fragment；
• 安全访问 Model、Part 和 Mesh；
• 设计参数化 Command；
• 区分模型和显示状态；
• 建立七级 API 证据；
• 将验证能力包装为 Agent 工具；
• 诊断加载、调用、保存和显示故障；
• 建立可持续回归。

文档目录

编号	文档	解决的问题
00	00-overview-and-evidence	SAM 为什么是 Qt DLL、Python 2 与 C++ PYD 的混合系统；证据如何分级
01	01-plugin-p0-p5	7231 中 P0～P5 如何逐步完成菜单、信号槽、参数窗体和 Part 调用
02	02-pyd-registration-and-fragments	pyoModule、ptsKModelFragment、ptsKPartFragment 如何注册
03	03-python2-verified-api	哪些 Python 2 SAM API 已在真实模型成功，哪些写法已明确失败
04	04-cpp-sdk-mesh-api	如何通过 C++ SDK 访问 Model、Part、节点、单元、网格和 ODB
05	05-parametric-modeling	如何把二维参数轮廓映射到三维平面并增量写入 SAM 网格
06	06-agent-plugin-architecture	Agent 如何以白名单工具方式进入 SAM，而不是任意执行脚本
07	07-api-validation-workflow	如何用探针、另存、重开、INP 和求解建立端到端验证
08	08-validated-cases-and-roadmap	1338_repaired_v01.sam 等成果、当前限制和下一步工作
09	09-sam-secondary-development-guide	从启动流程、插件加载和底层数据主链理解 SAM 二次开发整体架构
10	10-sam-gui-and-interaction-api	掌握应用、主窗口、Module、Toolset、菜单、Mode、Form 与 Dialog API
11	11-sam-command-python-pyd-api	理解命令投递、Python 用户层、PYD 绑定值体系和模块注册流程
12	12-sam-data-model-and-mesh-api	使用数据库、Model、Part、Feature、Mesh 与重网格 API 修改模型数据
13	13-sam-scene-rendering-api	区分模型与显示数据，使用 Scene、Editor、Renderer 和几何类型刷新显示
14	14-sam-build-deployment-troubleshooting	完成 GUI DLL/PYD 编译部署，并定位加载、调用、模型和显示问题

两条阅读路径

建模开发路径

00 → 01 → 02 → 04 → 05 → 07 → 08 → 09 → 10 → 11 → 12 → 13 → 14

适合准备编译 C++ 插件、开发肘板/吊耳/孔边构件等参数化工具。

Agent 工具化路径

00 → 03 → 04 → 06 → 07 → 08 → 09 → 11 → 12 → 13 → 14

适合把已经验证的 Python 2 与 C++ 能力注册成 Agent 白名单工具。

当前最重要的基准

• 人工认可度最高的修复模型：D:\wx702\1338\1338_repaired_v01.sam
• Python 2 成功数据：49,398 个壳单元与 484 个 B31 单元完成 Section 分配，剩余未分配为 0
• C++ SDK 证据来源：7231、VTKIO-Source、LiftingLug
• 总纵参考点 Set、自由边自动修复和胶囊孔重构仍属于未完成的端到端项目

---

学习状态：🟡 已建立分层知识体系，进入最小插件编译与工具回归阶段