记录、序列化与重放

声明式工作流在 GraphSession 中记录公共兼容操作。与紧凑原生 Graph 相比，它保留类型化操作节点、结果 Root、语义数据和外部来源信息。

@model

import cadflow as cad

@cad.model(graph_id="bracket")
def bracket(width: float, height: float):
    base = cad.make_box_rsolid(width, 30.0, 4.0)
    rib = cad.make_box_rsolid(4.0, 30.0, height)
    return cad.union_rsolid(base, rib)

result = bracket(60.0, 25.0)
shape = result.value
model_json = result.model_json

装饰器为每次调用持有一个 Graph Session，把返回的 Graph-backed 值记录为结果节点，并返回 ModelResult。设置 export_dir 后还会写出配置的产物，并在 artifact_paths 中提供路径。

ModelResult

字段	含义
value	原函数返回值
session	已完成的记录 Session
result_node_ids	显式终端 Graph Root
model_json	可移植 Model 文档
session_json	面向诊断的 Session 文档
artifact_paths	装饰器写出的文件

函数返回值决定 Graph Root。所有需要保持可达的结果都应返回；规范导出可能省略不可达中间节点。

导出与导入

export_model_json(session, indent=2, result_node_ids=None) 序列化规范 Model 文档；import_model_json(json_str) 解析并验证为结构化数据。Graph/Session JSON 辅助函数服务于更底层工具，不能在需要完整 Model 契约时替代 Model JSON。

Model JSON 保存操作与依赖，不保存任意可执行 Python。导入源文件和外部资源仍是显式依赖，必须按预期策略提供。

严格重放

values = cad.replay_model_json(model_json, strict=True)

严格重放会拒绝不支持的操作、无效 Schema、非规范依赖、Graph 所有权错误与其他契约违规。非严格重放适合受控检查或迁移，但不能静默成为发布默认值。

重放成功只代表 Graph 已执行。需要证明等价时，应对比终端几何、拓扑、尺寸、语义分配与导出产物元数据。

确定性规则

• 为 Graph、Part、Component、Connector 与语义实体设置稳定 ID。
• 显式传递参数，不依赖环境状态。
• 保持源资源可寻址；重现性重要时记录 Hash。
• 随交付产物记录 CadFlow 版本与 Capability 数据。
• 只通过公共序列化函数规范化 JSON。
• 重放前验证并限制不可信输入。

完整函数与 Graph 数据类型见 Graph/重放目录。