pythonocc-step-editor/README.md

# STEP 零件与特征查看编辑原型

这是一个基于 Python、pythonocc-core/OCCT、VTK、PySide6/Qt 和 SpaceClaim/SCDM 的 STEP 模型查看、选择、受限参数化编辑与导出原型。程序入口是 `main.py`。

## 快速读懂

- 本软件处理的是 STEP 里的 B-Rep 结果几何，不恢复原 CAD 软件的完整建模历史，也不等于 CAD 级完成。
- 当前统一走 `SCDM-first` 主线：SCDM 负责识别和执行它能稳定处理的直接建模能力；本软件负责 UI、选择、能力字典、参数表、关系式、任务 JSON、`/RunScript` 脚本生成、后台执行、结果校验、失败回滚、ID 续接、参数导出和本地 OCCT 兜底。
- SCDM 能人工修改很多内容，不代表本软件可以立刻全部开放。只有能拿到结构化对象、当前值、可用命令和结果校验方式的能力，才会进入客户参数表。
- 本软件不是给成千上万个 Face/Edge/一级/二级/三级情况各写一套代码，而是走 `capability key -> 中文参数 -> scdm_edit_job.json -> SCDM 脚本模板 -> 结果校验`。新增能力通常补一类能力模板，不补某个 Face ID 特判。
- Analysis Situs 和本地 OCCT 现在只做辅助定位、兜底识别、对照验证和历史回归，不再作为新增能力主线。
- 启动 `python main.py` 会快速进入空场景，不默认读取大 STEP；点击“导入几何模型”后才加载模型。
- README 的阅读顺序：先看 `SCDM-first 主路线`、`本软件与 SCDM 如何交互`、`怎么运行` 和 `验证`。后面的本地 OCCT 口径只是兜底基线。

## 软件整体架构

行数是本次交付前刷新过的源码/脚本文本统计值。统计口径包含 `.py`、`.md`、`.json`、`.ps1` 等文本文件，不包含 `.git`、`local/`、`dist/`、第三方参考目录、截图和二进制 STEP 模型。

```text
python-occt（92597 行）
├── main.py（7 行）
│   └── 程序入口，支持普通启动、烟测、隔离子进程 worker 入口
│
├── step_editor/（66988 行）
│   ├── app.py（2007 行）
│   │   └── 主窗口初始化、左侧操作面板、按钮和布局
│   ├── window_core.py（4369 行）
│   │   └── STEP 加载、VTK 视图、模型显示、拾取、高亮、坐标轴、FPS、显示刷新
│   ├── window_actions.py（9677 行）
│   │   └── 导出、参数化建模动作、后台任务、隔离子进程、操作历史
│   ├── window_state.py（10613 行）
│   │   └── 选择状态、参数表状态、按钮启用/禁用、撤销/重做、历史定位
│   ├── model.py（5796 行）
│   │   └── StepModel 核心对象，保存 shape、Face、Edge、Solid、拓扑缓存和 mixin 组合
│   ├── scdm_backend.py（623 行）
│   │   └── 自动发现并缓存 SpaceClaim.exe，生成 `/RunScript` 命令并做最小烟测
│   ├── scdm_probe.py（972 行）
│   │   └── 生成 SCDM 识别任务和 probe 脚本，约定 raw 识别输出
│   ├── scdm_feature_mapper.py（2389 行）
│   │   └── 把 SCDM raw 结果映射成 UI 可用的特征、参数和对象 locator
│   ├── scdm_capabilities.py（380 行） / scdm_property_specs.py（814 行） / scdm_schema.py（122 行）
│   │   └── 把 SCDM raw 结果翻译成产品化能力、中文参数和参数表 spec
│   ├── scdm_edit_runner.py（2503 行）
│   │   └── 生成 SCDM 修改任务、修改脚本、结果 STEP 和错误 JSON
│   ├── scdm_result_validator.py（1086 行）
│   │   └── 结果文件检查、目标值回测、对象漂移守门、ID 续接和关系式重写
│   ├── scdm_status.py（568 行）
│   │   └── SCDM 可用性、cache 状态和软件进度摘要
│   ├── relation_formulas.py（307 行）
│   │   └── 关系式解析、补全、求值、依赖检查和单位字面量
│   ├── parametric_component.py（609 行）
│   │   └── 导出参数 schema 和组件目录 main.py
│   ├── recognition_graph.py（539 行） / asitus_bridge.py（308 行） / recognition_priority.py（240 行）
│   │   └── 本地几何图、Analysis Situs 辅助桥接和兜底识别排序
│   ├── features.py（3591 行） / operations.py（14604 行） / geometry_utils.py（1427 行）
│   │   └── 本地 OCCT 兜底识别、计划和几何编辑实现
│   ├── polydata.py（425 行） / step_io.py（160 行） / export.py（179 行）
│   │   └── OCCT 与 VTK 显示数据转换、STEP 读写和导出
│   ├── workers.py（51 行） / widgets.py（11 行） / ui_helpers.py（1401 行） / info_panel.py（284 行）
│   │   └── Qt worker、自定义控件和 UI 辅助
│   └── 其它小模块：transforms.py（565 行）、isolated_edit_worker.py（238 行）、records.py（20 行）、model_types.py（25 行）、constants.py（70 行）
│
├── scripts/（24721 行）
│   └── 自动化验证脚本和 `verify_first_level_edit_suites.py` 总入口
│
├── tools/asitus_probe/（47 行）
│   └── Analysis Situs probe 的 C++ 源码，构建产物不提交
│
└── assets/models/
    └── 仓库自带 STEP 测试模型
```

## SCDM-first 主路线

本阶段只有一条主线：SCDM 负责识别和执行它能稳定处理的直接建模能力；本软件负责 UI、选择、参数表、关系式、任务生成、后台执行、校验、回滚、ID 续接和参数导出。SCDM 内部如何处理相邻面、圆角链、二级/三级拓扑传播，交给 SCDM。本软件不再把手写一级、二级、三级传播当成新增能力主线。

### 模型树和 cache

SCDM 界面里的模型树主要表达装配和显示层级，比如 `Design -> Pattern -> Component -> Geom -> Solid`。它对阵列、组件、实体定位很有价值，但它不是本软件可以直接展示给客户的参数 cache。

本软件仍然需要自己的 `scdm_feature_cache.json`，原因有四个：

- 要把 SCDM 对象映射回当前 UI 里的 `Face`、`Edge`、`Solid`、`Feature` ID。
- 要把 SCDM 原始对象翻译成客户看得懂的参数，例如 `偏移`、`直径`、`位置`、`阵列间距`。
- 要知道每个参数应该生成哪类 SCDM 修改脚本，以及失败时怎么解释。
- 要在修改后用新 STEP、新 cache 和 OCCT 校验结果，并续接关系式里的对象 ID。

所以正确关系是：SCDM 模型树和 raw 识别结果是证据来源；本软件 cache 是 UI、脚本生成、校验和回滚的中间表示。

### 本软件与 SCDM 如何交互

本软件不是把 SCDM 界面嵌进来，也不是让客户写脚本。客户看到的仍然是本软件：导入 STEP、点击对象、修改中文参数、点击“参数化建模”。SCDM 只在后台作为几何编辑后端运行。

两边通过“文件中转 + 命令启动”交互。`RunScript` 不是我们生成的文件名，而是 SpaceClaim 的启动参数；本软件真正生成的是临时 Python 脚本和任务 JSON，然后用 `/RunScript` 交给 SCDM 执行。

```text
导入 STEP
-> 本软件显示模型并建立 Face / Edge / Solid 基础索引
-> 本软件自动找到 SpaceClaim.exe，并缓存路径、来源、版本和验证结果
-> 本软件写 scdm_probe_job.json，说明要打开哪个 STEP、输出写到哪里
-> 本软件生成 scdm_probe.py，并用 SpaceClaim.exe /RunScript=scdm_probe.py 启动 SCDM
-> SCDM 打开 STEP，识别对象、参数、命令候选、模型树和限制原因
-> SCDM 写回 scdm_raw_features.json
-> 本软件读取 raw 结果，翻译为 scdm_feature_cache.json 并缓存，以便点击对象时直接查
-> 用户在参数表修改目标值并点击“参数化建模”
-> 本软件写 scdm_edit_job.json 和 scdm_edit.py
-> SpaceClaim.exe /RunScript=scdm_edit.py 在后台执行修改
-> SCDM 输出 result.step 或 error.json
-> 本软件用 OCCT 回读 result.step，做 B-Rep 校验、目标值回测、对象漂移检查和失败回滚
-> 校验通过后替换当前模型，重新 probe，刷新 cache、ID 映射和关系式引用
```

中转文件放在 `local/scdm/<模型名>_<模型指纹>/`，不提交 Git，删掉后可以重新生成。典型目录如下：

```text
local/scdm/ICEPAK-NATURAL_19ff9d1ede49/
├── scdm_probe.py           # 本软件生成，喂给 SCDM 做识别
├── scdm_probe_job.json     # 本软件生成，说明识别任务
├── scdm_raw_features.json  # SCDM 写回的原始识别结果
├── scdm_feature_cache.json # 本软件生成的产品化能力缓存
└── edit/
    ├── scdm_edit.py        # 本软件生成，喂给 SCDM 做修改
    ├── scdm_edit_job.json  # 本软件生成，说明修改任务
    ├── result.step         # SCDM 修改成功后输出
    └── error.json          # SCDM 修改失败时输出
```

模型文件变更后会重新计算指纹；mapper 版本变化后旧 cache 也会丢弃，避免旧识别结果误用到新模型或新规则上。

### 能力开放规则

这里说的“SCDM 能做”，不是指 SCDM 界面里人工能点的所有按钮，而是指本软件能通过脚本拿到下面四类证据：

1. SCDM 返回了结构化对象或可定位几何，比如 Face、Hole、Slot、Boss、Round、Chamfer、Pattern、Shell。
2. SCDM 返回或脚本环境确认了可用命令，比如 `OffsetFaces`、`Move`、`Fill`、`Delete`、`Chamfer`、`ConstantRound`。
3. 当前对象有可用的当前值或定位信息，比如直径、位置、半径、Face locator、实例中心。
4. 修改后能用新 STEP、新 cache、目标值回测或“目标特征消失”证明结果是对的。

不满足这四点的内容，只能进入诊断、日志或待适配能力，不能直接展示成客户可修改参数。

大模型上的歧义圆柱面要优先等 SCDM cache。比如 `assets/models/geom_extract.step` 的 Face1722，SCDM raw 识别为 `round`，不是普通圆柱孔；本地 OCCT 快速兜底曾经会把它误猜成孔/槽候选。当前策略是：SCDM cache 未就绪时，先不开放这类圆柱孔/槽参数；cache 就绪后按 SCDM 的结构化对象决定展示圆角、槽、孔或只读诊断。

状态标记：

- `[x]` 已适配：已有能力字典、参数表/命令入口、edit job、runner 或 UI gate、结果校验和回归测试。
- `[~]` 部分适配：已有识别、cache、脚本入口或假 runner，但真实 STEP 样例、命令细节或结果守门还要继续补。
- `[ ]` 待适配：SCDM 可能能做，但本软件还没有完成结构化识别、命令脚本和结果校验闭环。

核心路线只保留下面这一棵树。前半段是 SCDM 后端闭环，中间是参数表和关系式入口，后半段是按客户高频和 SCDM 可验证能力开放参数：

```text
SCDM-first 主路线
├── 0. 后端发现与可用性
│   ├── [x] [自动发现 SpaceClaim.exe -> 缓存路径、来源、版本和验证结果]
│   ├── [x] [发现顺序 -> 缓存、注册表、环境变量、ANSYS 常见目录、PATH]
│   ├── [x] [找不到 -> 导入模型后弹出路径选择，用户选中后写回缓存]
│   └── [x] [SCDM 不可用 -> 软件仍可查看、导出并使用本地兜底能力]
│
├── 1. SCDM 识别与缓存
│   ├── [x] [scdm_probe_job.json -> /RunScript 扫描 STEP]
│   ├── [x] [scdm_raw_features.json -> 保存 SCDM 结构化对象、几何属性、模型树、命令候选和限制原因]
│   ├── [x] [scdm_feature_cache.json -> 映射为本软件能力字典和中文参数]
│   ├── [x] [cache 命中 -> 点击对象只查缓存，不重复启动 SCDM]
│   ├── [x] [cache 守门 -> 模型指纹或 mapperRevision 不匹配就丢弃，避免旧缓存把圆角/槽误当孔]
│   ├── [~] [SCDM 模型树 -> 已读取 Pattern / Component / Solid 层级证据；下一步用于阵列和组件参数定位]
│   └── [x] [不能产品化的 raw 结果 -> 只进诊断，不进客户参数表]
│
├── 2. 能力字典、参数表和用户入口
│   ├── [x] [capability key -> 中文名、单位、输入类型、建模意图、后端命令和 postCheck]
│   ├── [x] [参数表 -> 只显示已产品化、可执行、可校验的参数]
│   ├── [x] [不可改 -> UI 阶段直接说明是未实现、命令不可用、识别不完整还是风险过高]
│   ├── [x] [参数化建模 -> 多个目标值统一提交，不再每行一个操作按钮]
│   ├── [x] [导出参数 -> 勾选输入参数后生成组件目录 main.py 和参数 schema]
│   └── [x] [参数变更收集 -> 用户可一次修改多个目标值，统一交给执行层]
│
├── 3. 关系式与参数联动
│   ├── [x] [公式输入 -> 支持 Face85.直径 = Face87.半径 这类对象.参数表达式和补全]
│   ├── [x] [添加守门 -> 阻止自引用、重复目标、循环依赖和当前无可执行参数的公式]
│   ├── [~] [公式求值 -> 添加公式后立即计算目标值并触发 SCDM 修改；启停/删除公式后按公式快照回滚或按剩余启用公式重算，真实 SCDM 多公式样例待补]
│   ├── [~] [批量联动 -> 多条公式先求值成一组目标参数，再合并为一个参数化建模任务]
│   ├── [~] [ID 续接 -> 修改后按新 cache 重写公式里的 Face / Edge / 特征 ID；复杂拆分/合并需要提示重新选择]
│   └── [~] [关系式管理 -> 公式启停、删除回滚、基础单位字面量 mm/cm/m、JSON 导入/导出已接；优先级和更细错误定位待补]
│
├── 4. SCDM 参数化建模执行
│   ├── [x] [scdm_edit_job.json -> 记录模型、对象签名、能力、目标值、输出路径和超时]
│   ├── [x] [/RunScript 后台执行 -> 成功写 result.step/result.json，失败写 error.json]
│   ├── [x] [face.offset / hole.diameter / hole.position -> ICEPAK 真实 SCDM 回测通过]
│   ├── [~] [slot.width / slot.depth / slot.position / boss.diameter / boss.height / boss.position -> runner、UI gate 和目标校验已接，真实样例待补]
│   └── [~] [round.radius / chamfer.distance / feature.fill / feature.delete_round_or_chamfer -> 脚本和假 runner 已接，真实样例待补]
│
├── 5. 结果校验、回滚和 ID 续接
│   ├── [x] [OCCT 回读 result.step -> 检查输出文件、B-Rep 和基础模型规模]
│   ├── [~] [目标回测 -> 已覆盖数值目标、位置目标、目标特征消失和未编辑对象漂移]
│   ├── [~] [ID 续接 -> 简单唯一匹配已接，歧义/拆分/合并样例继续补]
│   ├── [~] [关系式刷新 -> 修改后按新 cache 重写 Face / Edge / 特征 ID]
│   └── [x] [失败 -> 回滚原模型并给出明确原因]
│
├── 6. 当前已开放或正在开放的 SCDM 能力
│   ├── [x] [Face 偏移 -> face.offset / OffsetFaces]
│   ├── [x] [孔直径 -> hole.diameter / StandardHoles 或同轴 OffsetFaces]
│   ├── [x] [孔位置 -> hole.position / Move]
│   ├── [x] [填孔/删除小特征 -> feature.fill / Fill 或 Delete]
│   ├── [~] [槽宽 -> slot.width / OffsetFaces，真实 STEP 回测待补]
│   ├── [~] [槽深 -> slot.depth / Move 或 OffsetFaces，只开放 SCDM 返回槽深、槽底面和深度方向证据的槽]
│   ├── [x] [槽位置 -> slot.position / Move]
│   ├── [~] [凸台直径 -> boss.diameter / OffsetFaces，真实 STEP 回测待补]
│   ├── [~] [凸台高度 -> boss.height / Move 或 OffsetFaces，真实 STEP 回测待补]
│   ├── [x] [凸台位置 -> boss.position / Move]
│   ├── [~] [圆角半径 -> round.radius / ConstantRound，只开放 SCDM 明确返回等半径证据的圆角]
│   ├── [~] [倒角距离 -> chamfer.distance / Chamfer，只开放 SCDM 明确返回等距倒角证据的倒角]
│   ├── [~] [删除圆角/倒角 -> feature.delete_round_or_chamfer / Fill 或 Delete，真实 STEP 回测待补]
│   ├── [x] [阵列间距 -> pattern.spacing / Move，整体阵列保持中心不变并等距重排；安全范围由支撑面动态计算，不针对 Face92 写死]
│   ├── [~] [局部间距 -> pattern.segment_spacing / Move，按“FaceA-FaceB 间距”或“零件A-零件B 间距”修改相邻段；已支持固定前项移动后侧、固定后项移动前侧、两侧均分保持中心、只移动前项、只移动后项]
│   ├── [~] [阵列实例位置 -> pattern.instance_position / Move，只移动当前阵列成员；不自动保持整体阵列等距，真实 STEP 回测待补]
│   └── [~] [壳体厚度 -> shell.thickness / Move，薄壁两平面配对后固定一侧、移动另一侧；真实 STEP 回测待补]
│
├── 7. 下一批只按 SCDM 能力适配
│   └── [ ] [SCDM 之外的新能力 -> 等 SCDM 能力适配完再评估]
│
└── 8. 交付与兜底边界
    ├── [x] [软件进度 -> 只展示能识别、不能识别、能修改、不能修改]
    ├── [x] [日志 -> 记录本次使用 SCDM / OCCT / Analysis Situs 哪个后端]
    ├── [x] [Analysis Situs -> 只做辅助定位、兜底识别和开源对照]
    ├── [x] [本地 OCCT -> 只保留已验证兜底能力，不再作为新主线扩展]
    ├── [ ] [商业 SCDM -> 不打包进本软件，只检测客户本机安装和许可证]
    └── [ ] [SCDM 之外的新能力 -> 等 SCDM 能力适配完再评估]
```

## 关系式实现流程

关系式是 SCDM-first 的上层参数驱动入口，不绕过 SCDM 手写几何。公式只负责把 `Face87.直径 = Face85.半径`、`Face92.位置 = Face85.位置 + (0, 0, -3.5)` 这类用户意图求值成一组目标参数；真正改模型仍然生成 `scdm_edit_job.json`，交给 SCDM 执行，再由本软件做校验、回滚和 ID 续接。

当前策略：

- 输入框与选择模式解耦，关系式可以引用当前模型里任意已知 `Face`、`Edge`、`Solid` 或能力对象。
- 补全只补对象和参数名，不要求用户理解底层 capability key。
- 添加公式后会立即求值并尝试执行；失败时公式保留原因，模型不被破坏。
- 修改后若对象 ID 能唯一续接，公式文本会自动改成新 ID；若发生拆分、合并或歧义匹配，会提示重新选择。
- 已支持公式启停、删除后按启用公式重算或恢复公式基准；公式数字可写 `mm`、`cm`、`m` 或“毫米/厘米/米”并统一换算为当前参数表使用的毫米值；可把当前公式组导出为 JSON，也可从 JSON 批量导入并整组重算；后续要补更细错误定位和多公式优先级。

## 交互稳定性和大模型策略

大模型上最容易出问题的不是单一计算慢，而是显示 actor 更新、后台线程结束、SCDM cache 刷新和 VTK 相机旋转同时发生。当前守门原则：

- STEP 读取和显示网格生成走 `LoadWorker` 后台线程，导入失败不替换当前模型。
- 大模型首屏优先显示面片，默认延后全量边线和全量识别预热。
- 鼠标旋转时不做自动选择；悬停和普通点选只做轻量拾取。
- 边线 overlay、局部 actor 替换和后台显示刷新会在相机交互结束后再装入场景，降低“导入后旋转一下偶发闪退”的概率。
- SCDM probe 对大模型按需启动：用户点击对象后才补识别；识别完成前不把本地圆柱兜底猜测当成已确认孔/槽能力。

如果仍出现偶发闪退，优先收集：模型路径、导入后是否立刻旋转、是否正在补边线、是否正在 SCDM probe、控制台输出和 `local/scdm/` 对应目录。

## Analysis Situs 辅助定位（非主线后端）

Analysis Situs 不再作为当前主识别路线继续接入；它保留为辅助定位、兜底识别和开源对照验证。当前已经完成孔组识别桥接、AAG 轻量关系摘要和基础几何关系摘要，可用于整孔高亮、参数表兜底、候选置信度和 SCDM 结果对照。

边界很明确：

- `[x]` 可读取外部孔组 JSON，并把 1-based AAG Face 映射成本软件 0-based Face。
- `[x]` 可缓存邻接、曲面类型、共面、同轴、平行、垂直和相切摘要。
- `[x]` 可作为 `recognition_graph.py` 的外部证据，提高孔、槽、凸台、圆角候选排序。
- `[ ]` 不把 Analysis Situs 的完整 AAG 图接成主识别数据源。
- `[ ]` 不让 Analysis Situs 直接驱动一级/二级/三级编辑计划。
- `[ ]` 不把 C++ CLI 编译产物纳入当前打包；找不到 CLI 时主程序不报错退出。

## 本地 OCCT 兜底能力的当前基线

本地 OCCT 兜底能力继续保留，用来在没有 SCDM 或 SCDM 失败时处理已经验证过的少量快路径，也用于自动化回归。它不再代表新增能力主线。

| 对象 | 本地兜底现在能做 | 主要边界 |
| --- | --- | --- |
| Face | 平面 Face 的 `偏移`、部分矩形/简单全平面 Face 的面内长度和面内宽度、壳体厚度、圆柱端盖/完整圆柱侧面高度。 | 自由曲面、复杂内孔面、非矩形复杂局部重建、二级/三级传播不承诺。 |
| 孔/槽 | 规则圆柱孔直径/半径/位置、盲孔/盲槽深度、槽宽、槽深、弧长、弧角、长圆槽总长度和中心距。 | 螺纹孔、复杂槽、多槽联动、孔组阵列联动不走本地新扩展。 |
| Edge | 直线 Edge 长度/端点、圆边半径/相邻轴心、椭圆主/小半径、部分圆角/倒角。 | 任意复杂曲线 Edge、复杂链式圆角/倒角不承诺。 |
| 凸台/圆角/壳体/解析面 | 有专项回归覆盖的简单样例。 | 新客户入口优先等 SCDM capability 适配。 |

Face 阶段的当前验收口径（本地 OCCT 兜底基线，R1 已收口）：

- 已验收：平面 Face 的 `偏移`，稳定矩形/简单全平面 Face 的 `面内长度`、`面内宽度`，以及壳体厚度、圆柱端盖/圆柱侧面高度这类挂在 Face 入口上的高频编辑。
- 已验收：Face 的一级关系定义为选中 Face 本身、必要的同域/共面碎片 Face、这些 Face 的边界 Edge/Vertex，以及与该区域共享边的直接相邻 Face。
- 未实现/不承诺：原 CAD 历史恢复、任意复杂 Face 的通用局部重建、手写孔底/槽底/台阶等二级/三级传播、跨特征约束求解和特征组联动。

孔/槽阶段的当前验收口径（本地 OCCT 兜底基线，R2/R3 已收口）：

- 已验收：圆柱孔/盲孔的 `直径`、`半径`、`轴心`、`盲孔深度` 和 `封堵/删除孔`。
- 已验收：槽/半孔/长圆槽的 `槽宽`、`槽深`、`圆弧长度`、`圆弧角度`、`开口角度`、`轴心`、`总长度` 和 `中心距`。
- 未实现/不承诺：孔组、阵列孔、同尺寸孔联动、多槽组联动、螺纹孔语义编辑、任意草图槽、跨复杂面槽、手写孔底/槽底带动台阶的二级/三级传播。

## 怎么运行

Windows PowerShell：

```powershell
cd C:\Users\admin\Desktop\python-occt
conda activate pyocc
python main.py
```

第一次配置环境：

```powershell
conda env create -f environment.yml
conda activate pyocc
```

烟测：

```powershell
python main.py --smoke-test
```

直接打开指定 STEP：

```powershell
python main.py assets\models\cube_10mm.step
python main.py assets\models\geom_extract.step
```

如果当前 shell 里没有 `conda`：

```powershell
C:\Users\admin\miniforge3\Scripts\conda.exe run -n pyocc python main.py
```

如果 `conda run` 输出中文时报 `UnicodeEncodeError`：

```powershell
$env:PYTHONIOENCODING='utf-8'
$env:PYTHONUTF8='1'
C:\Users\admin\miniforge3\Scripts\conda.exe run -n pyocc python scripts\verify_first_level_edit_suites.py --quick
```

## 验证

当前整体验证基线：

- `python scripts\verify_first_level_edit_suites.py --quick` 是一级编辑总验证入口的轻量回归，覆盖 smoke test、属性表规格、参数表 UI、关系式规则、参数导出组件生成、SCDM 后端发现、SCDM 状态、SCDM probe/cache、SCDM edit runner、SCDM result validator、Analysis Situs 孔组桥接、ICEPAK 同域圆柱孔、特征识别优先级、一级事实图、关联探测、显示网格预算和 README 守门。
- `python scripts\verify_first_level_edit_suites.py --stage face` 覆盖 Face 阶段兜底基线。
- `python scripts\verify_first_level_edit_suites.py --stage hole-slot` 覆盖孔/槽阶段兜底基线。2026-08-11，在 `pyocc` 环境下已通过 `python scripts\verify_first_level_edit_suites.py --stage hole-slot`，覆盖 R2/R3 孔槽专项套件、隔离执行、逻辑 Face ID 保持和孔槽阶段收口口径。
- `python scripts\verify_first_level_edit_suites.py --stage edge` 覆盖 Edge 阶段兜底基线。
- `python scripts\verify_first_level_edit_suites.py --stage boss --stage round-chamfer --stage shell --stage analytic` 覆盖凸台、圆角/倒角、壳体和解析曲面兜底基线。

`--quick` 直接或间接检查的脚本：

```text
main.py --smoke-test
verify_property_editor_specs.py
verify_property_card_editor_ui.py
verify_relation_formula_rules.py
verify_parametric_component_export.py
verify_scdm_backend.py
verify_scdm_status.py
verify_scdm_probe_pipeline.py
verify_scdm_edit_runner.py
verify_scdm_result_validator.py
verify_asitus_hole_bridge.py
verify_icepak_cylindrical_region_selection.py
verify_feature_recognition_summary.py
verify_first_level_fact_graph.py
verify_associated_features.py
verify_first_level_acceptance_docs.py
```

完整阶段脚本：

```text
verify_face_edit_suite.py
verify_isolated_face_edit.py
verify_hole_slot_edit_suite.py
verify_edge_edit_suite.py
verify_edge_isolated_edit.py
verify_boss_edit_suite.py
verify_round_chamfer_edit_suite.py
verify_shell_edit_suite.py
verify_analytic_surface_resize.py
verify_cone_semi_angle_isolation.py
```

真实 STEP 失败项要优先补到对应 SCDM 或本地兜底回归里，不能只靠手动操作说明“这次能过”。

开发时常用静态检查：

```powershell
python -m compileall -q main.py step_editor scripts
git diff --check
```

## 怎么使用

- 右侧是 3D 模型窗口，左侧是操作面板。
- 鼠标左键拖动旋转，滚轮缩放，中键或 VTK 默认组合平移。
- 只有明确单击模型才选择对象；拖动旋转后鼠标落到某个 Face 上不会自动改选。
- 选择模式使用英文：`Part`、`Solid`、`Face`、`Edge`、`Feature`。
- `Feature` 表示把点到的对象交给 SCDM/cache/兜底识别去解释成孔、槽、凸台、圆角、阵列、壳体等候选；它不是说 STEP 文件里原本带有 CAD 历史特征。
- `特征参数` 只显示可修改输入参数；面积、识别摘要、一级关系、关联探测和其它诊断不混入参数表。
- 用户可一次修改多个目标值，统一点击“参数化建模”。
- “软件进度”只显示客户关心的能识别、不能识别、能改、不能改；SCDM cache 数、probe 细节和内部对象数量留在日志。

## 当前版本边界

- 不恢复原 CAD 历史树。
- 不把 SCDM/SpaceClaim 商业内核打包进本软件；只检测客户本机安装和许可证。
- 不承诺 SCDM 人工界面里能做的所有操作都已经产品化到本软件。
- 不把 SCDM raw 技术名直接暴露给客户；必须先进入能力字典并有中文参数、脚本和校验。
- 不把 Analysis Situs 或本地 OCCT 继续扩成主识别/主编辑后端。
- 复杂 STEP 上仍可能出现 SCDM 命令失败、对象 ID 无法唯一续接、关系式目标歧义或结果漂移；此时必须回滚并说明原因。

## 交付检查清单

交付前先确认四件事：

1. 本地运行入口正常：

```powershell
conda activate pyocc
python main.py --smoke-test
```

2. 轻量回归通过：

```powershell
python scripts\verify_first_level_edit_suites.py --quick
```

3. Git diff 没有空白错误，CRLF 提示可以接受但不要出现真实 whitespace error：

```powershell
git diff --check
```

4. 只提交源码、脚本、README 和明确需要交付的测试模型：

```powershell
git status --short
```

不提交 `local/`、`dist/`、`third_party/`、`assets/screenshots/`、临时截图、临时 markdown、第三方参考项目、SCDM 运行中转文件和本地打包产物。

## Windows 文件夹版打包

```powershell
conda activate pyocc
powershell -ExecutionPolicy Bypass -File .\scripts\package_windows.ps1
```

输出：

```text
dist\GeometryParametric_windows_x64.zip
```

`dist` 是本地构建产物，默认不提交 Git。

## 提交与忽略

- `local/`、`dist/`、`third_party/`、`assets/screenshots/`、临时截图、临时 markdown 和第三方参考项目不提交。
- 仓库自带可复现测试 STEP 可以提交，例如 `assets/models/ICEPAK-NATURAL.stp`。
- 本次 SCDM-first 交付版建议提交命令：

```powershell
python scripts\verify_first_level_edit_suites.py --quick
git diff --check
git status --short
git add README.md step_editor scripts
git status --short
git commit -m "feat: 完善 SCDM-first 参数化编辑交付版"
```

## 后续开发备注

这一节给后续开发交接使用，普通试用人员可以跳过。

- 当前主线是 `SCDM-first 主路线`。继续开发时先读这条路线，不要回到“自己手写 Face 一级、孔槽、Edge、凸台、圆角、壳体、二级三级传播”的旧路线。
- 新增客户入口必须先有 SCDM raw 证据、capability key、中文参数、SCDM edit job/脚本、postCheck 校验、失败解释和回归脚本。
- 本地 OCCT 和 Analysis Situs 只作为兜底、对照和历史回归基线。
- 大模型交互稳定性优先：导入、旋转、边线补充、SCDM probe、参数表刷新和 actor 替换不能在 UI 线程互相抢。
- `geom_extract.step` 的 Face1722 是重要误识别样例：SCDM raw 标为 `round`，本地兜底不能在 cache 未就绪时把它当普通圆柱孔开放。
- 当前需要继续补的主线问题：SCDM 模型树用于 Pattern/Component/Solid 定位、阵列局部间距真实 STEP 回测、槽/凸台/圆角/壳体真实 SCDM 样例、关系式优先级/更细错误定位、复杂 ID 续接歧义提示、偶发 VTK 旋转闪退复现。