错误与诊断
CadFlow 通过两种方式报告失败：当调用契约无法完成时抛出异常；对于可以检查和修复的预检、验证、求解或分析状态，返回结构化诊断。
异常边界
| 失败类型 | 常见原因 | 调用方操作 |
|---|---|---|
ValueError | 范围、向量、枚举、Session 兼容性或领域状态无效 | 修正输入，不要原样重试 |
TypeError | Python 类型或调用形式不受支持 | 修正调用点或 Schema 转换 |
NativeError | 原生库加载或 C ABI 操作失败 | 检查消息、操作、环境与输入几何 |
FileNotFoundError / OSError | 输入缺失、路径拒绝或外部 I/O 失败 | 修正路径或准备资源 |
| 领域异常 | Scene 契约、柔性原生转换或重放等领域失败 | 使用领域验证报告和异常页 |
只捕获能够修复的最窄异常。不要用一个 except Exception 包住整个建模流程，否则会丢失操作边界和诊断上下文。
结构化诊断
Diagnostic 包含：
| 字段 | 含义 |
|---|---|
severity | 可供程序分支的级别，常见为 error、warning 或信息级别 |
code | 用于测试和自动修复的稳定诊断键 |
message | 面向人的说明 |
hint | 可选修复建议 |
data | 额外 JSON-safe 证据 |
程序应按 code 分支，不要解析 message 文本。
OperationReport 记录操作、状态、输出元数据、诊断和归一化参数，ok 是受支持的成功判断。OperationResult 把返回值与报告组合在一起。
result = model.apply("fillet", body, radius=2.0, edges=(0, 4))
if not result.report.ok:
for item in result.report.diagnostics:
print(item.code, item.message, item.hint)
else:
body = result.value
预检与执行
Model.preflight(operation, *args, **kwargs) 在不执行原生几何的情况下检查已知操作、必要参数、常见调用错误与能力状态。Model.apply(...) 先预检再执行，并同时返回值和报告。
预检不是几何证明。即使报告为 ready，原生构造、拓扑、文件 I/O 或求解仍可能失败。
验证报告
验证具有领域边界：
Shape.validate()检查原生测量与基本拓扑状态；- Sketch 报告区分 solved、underconstrained 与 failed；
- Assembly 报告提供残差和未满足约束；
- Physical 与 Simulation 报告包含类型化问题与交叉引用检查；
- Scene 验证覆盖 Manifest、资源、Schema、限制与包结构。
构建和修复阶段可用非严格模式收集证据；发布边界应使用严格重放或严格下沉，让无效状态立即终止流程。
恢复模式
- 构造领域对象前验证外部 Schema。
- 动态操作先检查能力并执行预检。
- 每次执行一个边界清晰的操作。
- 保留诊断代码、归一化参数和相关产物路径。
- 只修复调用方明确理解的错误，其余错误连同原始原因上报。
- 独立验证最终几何或产物，不把中间步骤成功视为最终正确。