SAM API 验证工作流：禁止猜测与七级验收门 / A Seven-Gate SAM API Validation Workflow Without Guesswork

📅 创建时间：2026-07-23
🏷️ 标签：#SAM #API验证 #回归测试 #调试 #INP
📚 前置知识：03-python2-verified-api
📖 系列导航：总目录 · 上一篇：06-agent-plugin-architecture · 下一篇：08-validated-cases-and-roadmap

第10部分：禁止猜测 API 的开发流程

10.1 接口证据优先级

text

1. 当前版本 SAM 用户手册
2. 老师发布的 7231 / Example / VTKIO / LiftingLug 源码
3. sam.rpy 操作记录
4. 当前对象的 dir() 只读探针
5. 最小不保存调用探针
6. 保存并重新打开
7. 导出 INP / 求解验证

sam.rpy 只能证明 GUI 尝试过某条命令。若 GUI 操作随后报错，该命令不能被列为可用 API。

证据等级的意义，是把“看起来像”与“已经证明”分开。文档或源码可以确认名称和设计意图，却可能属于其他版本；运行时 dir() 能确认成员存在，但不能说明参数、返回值或副作用；一次调用不抛异常，也可能什么都没有写入。只有状态、持久化、导出和求解逐层通过，才能扩大结论范围。

10.2 标准探针模板

python

def attempt(name, func):
    try:
        value = func()
        print('%s: PASS repr=%r' % (name, value))
        return True
    except Exception as error:
        print('%s: FAIL type=%r message=%s' %
              (name, type(error), error))
        return False

探针规则：

使用模型副本
默认不保存
一次只测试一个参数差异
打印对象类型、仓库键和数量变化
不以 repr() 好看为成功标准
失败参数进入禁用清单

探针必须记录 SAM 版本、模型副本标识、目标对象完整路径、调用参数、异常类型和调用前后差异。一次只改变一个变量，才能把结果归因到具体参数。会删除数据、启动求解或覆盖文件的接口不适合直接探测，应先寻找只读查询、dry-run 或独立临时目录。

text

声明：某接口在对象 X 上接受参数 P
  -> 静态证据：手册/头文件/示例
  -> 运行证据：成员存在且最小调用成功
  -> 状态证据：对象图发生预期变化
  -> 持久化证据：保存、重开后仍存在
  -> 交换证据：INP/ODB/VTK 引用完整
  -> 业务证据：下游求解或显示正确

每通过一层，只能声明对应强度的结论。例如只读探针通过时，可以写“当前对象暴露此名称”，不能写“该方法可用于生产建模”。

10.3 正式修改的验收门

text

Gate 1：调用成功
Gate 2：内存对象数量与属性正确
Gate 3：另存成功
Gate 4：重新打开后对象仍存在
Gate 5：Set/Section/连接关系仍正确
Gate 6：导出 INP 引用完整
Gate 7：求解器能够读入并运行

七级门之间为什么不能跳跃

调用成功只是语法和入口成立。内存对象检查用于发现静默失败、错误挂载或数量异常；另存与重开验证序列化协议；集合、Section 和连接关系检查确保引用没有丢失；导出验证平台模型能转换为求解器语义；最终读入运行才覆盖下游契约。某个任务如果不涉及求解，也要明确最后适用的 Gate，而不是假装通过全部七级。

失败后应保留最小复现：原始模型副本、探针脚本、控制台输出和差异摘要。对于会崩溃宿主的调用，在独立进程和可恢复环境中验证，并记录为高风险禁用项。不要在同一个已被失败调用污染的会话里继续得出结论。

回归与版本迁移

已验证 API 需要形成小型回归集。升级 SAM、编译器或插件后，先运行只读和内存 Gate，再逐步进行保存、导出和求解，避免高成本测试掩盖基础加载错误。测试结果按版本保存，不能因为新版本通过就改写旧版本事实。

当接口变化时，适配层负责把稳定的内部命令转换为具体 SAM 调用。业务代码不应到处散布未经验证的对象路径和参数组合。这样失败能够集中诊断，已知禁用项也能在调用前阻止。

完成验证的定义是证据可复现：另一位开发者拿到相同版本、模型和脚本，能够得到相同对象差异与下游结果。只在个人机器上“点过一次没报错”不构成 API 合同。

团队证据台账

团队应为每个关键接口维护简洁台账：接口名称、对象路径、SAM 版本、证据来源、已通过 Gate、已知失败、最小脚本和最后验证日期。台账不是把运行日志全部粘贴进文档，而是让开发者能找到产生结论的原始证据，并知道结论能否迁移到当前环境。

当两次结果冲突时，先检查版本、模型状态、插件组合和调用前置条件，不应简单用较新的记录覆盖旧记录。若原因尚未确定，两种结果都要保留并降低可信等级。这样可以防止偶然成功被传播为稳定 API，也避免一个环境中的失败被误判为所有版本均不支持。

自动化回归应从风险和成本排序：模块导入、符号发现和只读探针可以每次构建运行；保存重开适合每日或发布前运行；完整导出与求解可能进入较慢的验收流水线。每一级失败都应阻止后续更昂贵测试，并给出最接近根因的诊断。

对于 GUI 才能触发的能力，可以通过录制操作发现候选命令，但最终仍要抽离为最小脚本，去掉时间、路径和随机状态依赖。只有可独立重复的探针，才能成为升级时的兼容性契约。

SAM API 验证工作流：禁止猜测与七级验收门 / A Seven-Gate SAM API Validation Workflow Without Guesswork ​

第10部分：禁止猜测 API 的开发流程 ​

10.1 接口证据优先级 ​

10.2 标准探针模板 ​

10.3 正式修改的验收门 ​

七级门之间为什么不能跳跃 ​

回归与版本迁移 ​

团队证据台账 ​

SAM API 验证工作流：禁止猜测与七级验收门 / A Seven-Gate SAM API Validation Workflow Without Guesswork

第10部分：禁止猜测 API 的开发流程

10.1 接口证据优先级

10.2 标准探针模板

10.3 正式修改的验收门

七级门之间为什么不能跳跃

回归与版本迁移

团队证据台账