SAM 二次开发旧入口 / Legacy Entry for SAM Secondary Development

本页是系列入口。完整内容已拆分为十五篇专题文档，不再堆叠在单一长文中。

1. 为什么 SAM 接口必须证据优先

工业平台的脚本和 C++ 接口经常与其他产品使用相似名称。 名称相似不能证明参数、返回值、生命周期和持久化行为相同。

SAM 还可能存在：

• 不同发布版本；
• Python 2 与原生扩展边界；
• GUI 命令与底层对象方法差异；
• 仅在特定对象状态下存在的方法；
• 头文件声明但未在当前包导出的符号；
• 调用成功但没有持久化的临时对象；
• 文档、示例和实际二进制版本不一致。

因此每个结论都要附带证据等级和适用环境。

2. 七层证据梯度

Level 1: current official documentation
Level 2: matching-version headers and source examples
Level 3: GUI-generated replay log
Level 4: runtime object inspection
Level 5: minimal controlled invocation
Level 6: save and reopen verification
Level 7: export and downstream solver verification

证据层级不是简单的“数字越大越权威”。 不同层回答不同问题。

文档解释设计意图和公共用法。 头文件确认类型、符号和静态签名。

重放日志证明 GUI 尝试发出了什么命令。 如果 GUI 随后报错，日志不能证明命令可用。

运行时检查证明当前对象暴露了成员。 它不证明参数正确或副作用会保存。

最小调用证明某一组环境和输入下能够执行。 保存重开证明对象进入持久化模型。

导出与求解验证证明下游语义仍然完整。

3. 每条结论的记录格式

建议使用统一证据记录：

Claim:
  ptsKPartFragment exposes method X

Environment:
  SAM version / build
  operating system
  plugin build hash
  Python version

Target:
  object path and runtime type

Evidence:
  source path / probe script / saved model

Passed gates:
  runtime, state, reopen, export, solver

Known limits:
  model state, parameters, failure cases

没有环境信息的结论无法用于版本迁移。

4. 安全探针环境

所有探索使用模型副本和独立输出目录。 高风险原生调用还应在可重启进程中执行。

探针准备包括：

• 记录 SAM 版本和构建号；
• 复制最小工程；
• 固定插件集合；
• 清理旧输出；
• 保存调用前对象摘要；
• 限制一次只改变一个参数；
• 捕获控制台和异常；
• 调用后比较对象图；
• 默认不覆盖原文件。

baseline copy
  -> read-only inspection
  -> one minimal mutation
  -> compare state
  -> save as new file
  -> reopen in clean session

5. 只读检查

只读检查先确认对象路径和类型。

model = mdb.models['Model-1']
print(type(model))
print(sorted(dir(model)))

输出需要限制大小，并关注预期成员而不是复制整个对象到日志。

dir() 结果可能包含动态绑定和内部方法。 成员存在不等于稳定公共 API。

可以进一步检查：

• Repository Key；
• 对象数量；
• 只读属性；
• 父子路径；
• 当前 Step 或 Part；
• Mesh 是否存在；
• 当前 Viewport 与 Document 状态。

6. 最小调用探针

探针包装器记录名称、结果和异常类型。

def attempt(name, action):
    try:
        before = snapshot_state()
        value = action()
        after = snapshot_state()
        print('%s PASS result=%r diff=%r' %
              (name, value, diff(before, after)))
        return True
    except Exception as error:
        print('%s FAIL type=%r message=%s' %
              (name, type(error), error))
        return False

成功标准不是没有异常。 状态差异必须符合预期，且不能产生无关对象或破坏引用。

7. 参数探索

一次只改变一个参数维度：

• 参数是否存在；
• 位置参数或命名参数；
• 标量类型；
• 字符串编码；
• 对象句柄；
• Repository Key；
• 可选值；
• 空集合；
• 边界数量；
• 非法值。

失败参数组合进入负面证据清单。 不能只保存最终成功调用而丢失失败边界。

8. Python 2 边界

旧版 SAM 环境可能嵌入 Python 2。 不能直接套用 Python 3 的模块初始化、字符串和扩展 ABI。

需要确认：

• 解释器完整版本；
• Unicode 与字节字符串规则；
• PYD 初始化入口；
• 编译器和运行库；
• GIL 与线程；
• 异常转换；
• 模块清理顺序。

中文路径和非 ASCII 参数必须在目标环境真实测试。 在现代 Python 中正常的代码，不代表嵌入式 Python 2 中行为一致。

9. PYD 注册链

SAM loads PYD
  -> Python module entry
  -> registrar receives initialize/finalize
  -> pyoModule created
  -> Model / Part Fragment registered
  -> script sees method on target object

注册和回收必须对称。 Finalize 前要确保 Python 引用、回调和后台任务不再访问模块代码。

模块名、导出入口、位数和依赖 DLL 任一不匹配，都可能表现为导入失败。

10. Model Fragment 与 Part Fragment

Model Fragment 适合跨 Part、分析步、导入导出和模型级能力。 Part Fragment 适合局部节点、单元、几何和参数化构件。

能力应挂在语义所有者上。 把 Part 操作放在 Model 层会迫使调用者重复传入 Part，并模糊生命周期。

验证 Fragment 时记录：

• 挂载对象完整路径；
• 运行时类型；
• 方法签名；
• 对象状态前置条件；
• 创建和销毁责任；
• 保存后的持久化位置。

11. 保存与重新打开

内存状态正确后，另存为新文件。 关闭当前会话，在干净进程中重新打开。

检查：

• 对象数量；
• 名称和稳定 ID；
• Set 与 Section；
• 节点与单元连接；
• 材料和方向；
• 插件私有数据；
• 视图表示；
• 警告和迁移日志。

只在同一会话读取对象，无法证明序列化正确。

12. 导出与求解验证

平台对象存在不代表求解器输入完整。

导出后检查：

• 关键字；
• 节点和单元引用；
• 集合；
• 材料与 Section；
• 载荷与约束；
• 分析步；
• 编码和路径；
• 求解器诊断。

必要时运行最小求解，检查读入、收敛和结果字段。

13. 负面证据

负面证据包括：

• 明确不存在的成员；
• 参数类型错误；
• 仅特定对象状态支持；
• 保存后消失；
• 导出缺少引用；
• 会导致崩溃的组合；
• 版本间行为差异；
• 已知不支持的编码或路径。

记录失败可以避免后来者重复踩坑。 失败结论同样限定版本和环境。

14. 回归集

已验证能力应进入分层回归：

1. 模块导入；
2. 对象发现；
3. 最小调用；
4. 内存状态；
5. 保存重开；
6. 导出；
7. 求解；
8. 失败输入；
9. 插件卸载；
10. 版本升级。

快速测试每次构建运行，完整求解可在每日或发布流水线运行。

15. 发布结论的规则

文档中的每个 API 示例应标明已达到的最高 Gate。 没有通过持久化时，不能写成完整建模能力。

推测可以保留，但必须显式标注并与已验证内容分开。 禁止用其他软件的同名接口补齐未知参数。

开始阅读

• SAM 二次开发知识体系总目录
• 第 00 篇：总览与证据分级
• 第 03 篇：已验证 Python 2 API
• 第 04 篇：C++ SDK 与网格接口
• 第 06 篇：Agent 插件架构
• 第 09 篇：架构总览与系列索引
• 第 10 篇：GUI、Toolset 与交互类 API
• 第 11 篇：命令桥、Python 与 PYD 扩展 API
• 第 12 篇：数据模型、Part 与 Mesh API
• 第 13 篇：场景、显示表示与渲染 API
• 第 14 篇：插件编译、部署与故障排查

核心原则

SAM API 必须区分真实模型实测、对象级验证、官方源码证据和明确失败四种状态；不得根据 Abaqus 同名接口推断 SAM 的参数和行为。

为什么拆分而不是保留一篇长文

SAM 二次开发横跨插件装载、Python 2 解释器、PYD 扩展、模型对象、网格接口、场景渲染和部署。把它们堆在一个文件中，会把证据强弱不同的内容混在一起，也难以指出某条 API 适用于哪个版本和对象状态。拆分后的每篇文章围绕一个可验证边界展开，旧入口只负责解释全貌和兼容历史链接。

插件 P0～P5 生命周期
       -> Python/PYD 注册
       -> Model / Part Fragment
       -> 领域对象与 Mesh API
       -> Scene / Representation
       -> 构建、部署和回归验证

这条链路包含两个方向：能力从底层 C++ 注册到脚本与 GUI，用户命令再从界面经过参数对象进入领域模型。任一层名称相似，都不能证明调用约定相同。必须从当前版本头文件、示例源码、运行时探针和保存后的模型结果建立证据链。

证据分级怎样使用

官方源码能够证明类型、符号或调用路径存在，但不一定证明某组参数在真实模型上可用。dir() 可以发现对象暴露了哪些成员，却不能证明调用会持久化。sam.rpy 记录 GUI 发出的命令，但 GUI 随后报错时，该记录只证明“尝试过”。最强证据是最小调用成功后，对象状态正确，模型另存并重新打开仍保留结果，导出文件引用完整，必要时求解器也能读入。

负面证据同样重要。明确失败的参数组合、崩溃条件和版本限制应进入禁用清单，避免后来者再次根据其他软件的同名 API 猜测。尚未验证的能力应标为假设，不能为了教程连贯而补写虚构签名。

建议阅读方式

第一次接触时先读总览与证据分级，再理解插件生命周期和 Python 2/PYD 注册；随后根据任务进入模型、网格、场景或部署专题。进行真实开发时，每次只验证一个接口差异，始终使用模型副本，并记录软件版本、对象类型、输入参数和持久化结果。

本页不会继续承载具体 API 清单。它的职责是把旧链接导向当前专题，并提醒读者：SAM 二次开发的第一原则不是记住更多命令，而是建立一条可以复现和反驳的证据链。

只有证据等级、适用版本和失败边界同时明确，专题中的代码才可以被当作工程参考。

维护旧链接时也要避免复制新专题正文。入口页只描述课程关系和验证原则，具体接口由对应专题维护；否则同一签名在两处演进，很快会产生互相冲突的版本。发现外部链接仍落到本页时，应保留稳定入口并提供清晰导航，而不是删除文件造成断链。

因此本页的验收重点是可定位性：读者能够判断自己的任务属于插件、脚本、模型、网格、场景还是部署，能够找到相应证据等级，并知道在修改真实工程前必须完成哪些验证。