pythonocc-step-editor/README.md

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

这是一个基于 Python、pythonocc-core/OCCT、VTK 和 PySide6/Qt 的 STEP 模型查看、选择、局部编辑与导出原型。

仓库里的 `assets/models/geom_extract.step` 是常用测试模型。程序入口是 `main.py`。

## 快速读懂

- 这是一个 STEP B-Rep 结果几何查看和受限局部编辑工具，不是完整参数化 CAD 内核。
- 主入口是 `python main.py`；无参数启动会快速进入空场景，不默认读取 STEP。常用测试模型是 `assets/models/geom_extract.step`；立方体测试模型是 `assets/models/cube_10mm.step`。
- 左侧操作面板当前优先保留最小建模链路：STEP 文件、选择模式 / 按 ID 选择、当前选中对象、编辑、参数化建模和导出模型；部分辅助面板暂时收起，后续需要时再放回。
- 局部编辑会先做计划、风险提示、预览和后台执行；失败时会尽量回滚，成功后进入撤销/重做历史。
- 当前统一走 `SCDM-first` 主线：能由 SpaceClaim/SCDM 识别和修改的特征，优先调用 SCDM 脚本接口；本软件不再重复造完整特征识别和直接建模内核，只负责 UI、缓存、脚本生成、校验、回滚、结果映射、参数导出和关系式管理。
- 当前开发顺序按一条路线闭环：SCDM 识别与缓存 -> 能力字典和参数表 -> 参数化建模任务 -> 结果校验和 ID 续接 -> 按 Face、孔、槽、凸台、圆角/倒角、阵列、壳体逐项适配；本地 OCCT / Analysis Situs 只作为兜底和对照。
- 新开 Codex 聊天框继续开发时，只需要 Codex 阅读 README 末尾的“Codex 项目记忆”；普通开发者可以忽略那一节。

## 软件整体架构

当前项目大致是这样分层的。行数按当前 Git 跟踪的可读源码/脚本统计，排除 README、STEP 模型、图标、`.git`、`local`、`third_party` 和临时文件。

```text
python-occt（源码/脚本 84,740 行）
├── main.py（7 行）
│   └── 程序入口，支持普通启动、烟测、隔离子进程 worker 入口
│
├── step_editor/（62,303 行）
│   ├── app.py（1,976 行）
│   │   └── 主窗口初始化、左侧操作面板、按钮和布局
│   │
│   ├── window_core.py（4,171 行）
│   │   └── STEP 加载、VTK 视图、模型显示、拾取、高亮、坐标轴、FPS、显示刷新
│   │
│   ├── window_actions.py（9,677 行）
│   │   └── 导出、参数化建模动作、后台任务、隔离子进程、操作历史
│   │
│   ├── window_state.py（10,169 行）
│   │   └── 选择状态、参数表状态、按钮启用/禁用、撤销/重做、历史定位
│   │
│   ├── model.py（5,713 行）
│   │   └── StepModel 核心对象，保存 shape、Face、Edge、Solid、拓扑缓存和 mixin 组合
│   │
│   ├── features.py（3,591 行）
│   │   └── 特征识别和编辑计划，比如孔、槽、凸台、圆角、壳体、解析曲面
│   │
│   ├── recognition_graph.py（539 行）
│   │   └── 内部 Face 几何图和通孔拆面识别缓存，记录平面/圆柱、邻接、共面、平行、垂直、同轴等基础关系
│   │
│   ├── asitus_bridge.py（308 行）
│   │   └── Analysis Situs 孔组识别 CLI 桥接，把外部识别到的孔 Face 组映射回 Python/Qt Face 编号
│   │
│   ├── scdm_backend.py（623 行）
│   │   └── SCDM 后端发现和缓存底座，负责自动发现并缓存 SpaceClaim.exe，生成 /RunScript 命令并做最小烟测
│   │
│   ├── scdm_probe.py（680 行）
│   │   └── SCDM probe 任务生成和脚本生成，负责写 scdm_probe_job.json、临时 RunScript 脚本和 raw 识别输出约定
│   │
│   ├── scdm_edit_runner.py（1,145 行）
│   │   └── SCDM 修改任务执行器，负责写 scdm_edit_job.json、临时修改脚本、result.step、result.json 和 error.json
│   │
│   ├── scdm_result_validator.py（770 行）
│   │   └── SCDM 结果校验和 ID 续接工具，负责输出文件检查、目标值回测、旧对象到新对象的唯一匹配和关系式 ID 重写
│   │
│   ├── scdm_schema.py / scdm_capabilities.py / scdm_feature_mapper.py / scdm_property_specs.py（1,821 行）
│   │   └── SCDM raw 结果、产品能力字典、scdm_feature_cache.json 映射和参数表 spec 转换层，避免把 SCDM 原始技术对象直接暴露给 UI
│   │
│   ├── operations.py（14,604 行）
│   │   └── 真正的几何编辑实现，比如拉伸/切除、孔径、孔深、边长、圆角、倒角
│   │
│   ├── geometry_utils.py（1,427 行）
│   │   └── 通用 OCCT 几何工具、布尔结果处理、B-Rep 校验、拓扑辅助
│   │
│   ├── polydata.py（425 行）
│   │   └── 把 OCCT Shape / Face / Edge 转成 VTK polydata，用于显示和拾取
│   │
│   ├── step_io.py（160 行）
│   │   └── STEP/XCAF 读取、STEP 导出、内部 BREP 临时交换
│   │
│   ├── export.py（179 行）
│   │   └── 导出完整模型、零件、Solid、Face、Edge，以及质量检查
│   │
│   ├── isolated_edit_worker.py（238 行）
│   │   └── 高风险几何编辑的隔离子进程入口
│   │
│   ├── workers.py（51 行）
│   │   └── Qt 后台任务 worker，避免主界面被计算堵死
│   │
│   ├── ui_helpers.py / widgets.py / info_panel.py（1,682 行）
│   │   └── UI 辅助函数、自定义控件、属性信息显示
│   │
│   └── recognition_priority.py（238 行）
│       └── 特征识别优先级，让常用、稳定、语义清楚的特征排前面
│
├── scripts/（21,988 行）
│   └── 各类专项验证脚本和一级编辑总回归入口
│
├── tools/asitus_probe/（386 行）
│   └── Analysis Situs probe 的 C++ 源码和 CMake 配置
│
├── environment.yml / .gitignore（56 行）
│   └── Conda 环境和 Git 忽略规则
│
└── assets/models/
    └── 仓库自带测试 STEP 模型
```

## SCDM-first 主路线

本阶段开始，README 里过去分散写的 SCDM 后端、开源辅助识别、参数化编辑和关系式内容统一收敛成一条 SCDM-first 路线，不再并行推进多套方案。

统一主线是：SCDM 负责识别和执行它能稳定处理的直接建模能力；本软件负责显示、选择、能力映射、参数表、关系式、任务生成、异步执行、结果校验、回滚、ID 续接和参数导出。Analysis Situs 和本地 OCCT 识别不再作为主路线和 SCDM 抢“谁说了算”，只作为兜底、对照验证和轻量几何关系辅助。SCDM 不接管本软件 UI，也不把 SCDM 原始界面文字直接展示给客户。

交付判断不是“调用了 SCDM”，而是下面这条闭环能稳定跑通：

```text
导入 STEP
-> 自动找到可用的 SpaceClaim.exe，并缓存路径、来源、版本和验证结果
-> 本软件显示模型并建立当前 Face / Edge / Solid 基础索引
-> 本软件把“请识别这个 STEP”的任务写给 SCDM，并用 /RunScript 启动 SpaceClaim
-> SCDM 在后台打开 STEP，识别可编辑对象、参数、命令候选和限制原因，并把结果写回给本软件
-> 本软件把 SCDM 结果翻译成能力字典和中文参数，并缓存起来，后续点击对象直接查缓存
-> 用户点击对象时，参数表只显示已经产品化、可执行、可校验的参数
-> 用户修改目标值后，本软件把“改哪个对象、改成多少、失败怎么回滚”的修改任务写给 SCDM
-> SpaceClaim.exe /RunScript 在后台执行修改，成功写出新的 STEP，失败写出错误原因
-> 本软件用 OCCT 重新读取新的 STEP，做 B-Rep 校验、目标值回测和非预期变形检查
-> 校验通过后替换当前模型，重新让 SCDM 识别并刷新缓存
-> 用新缓存更新 Face / Edge / 特征 ID 映射和关系式引用
```

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

本软件不是把 SCDM 界面嵌进来，也不是让客户写脚本。客户看到的仍然是本软件：导入 STEP、点击 Face/Feature、修改“偏移、孔径、位置、阵列间距”等中文参数，然后点击“参数化建模”。SCDM 只是在后台作为几何编辑后端运行。

两边的沟通方式是“文件中转 + 命令启动”，不是网络接口，也不是共享内存。`RunScript` 不是我们生成的文件名，而是 SpaceClaim 的启动参数；本软件真正生成的是临时脚本文件，然后用类似下面的命令把脚本交给 SCDM 执行：

```powershell
SpaceClaim.exe /RunScript=local\scdm\<模型名>_<指纹>\scdm_probe.py
SpaceClaim.exe /RunScript=local\scdm\<模型名>_<指纹>\edit\scdm_edit.py
```

这两个脚本文件由本软件自动生成。第一个脚本负责“识别这个 STEP 能改什么”，第二个脚本负责“按用户输入修改模型”。脚本旁边会有一份任务 JSON，里面写着要打开哪个 STEP、要识别或修改哪个对象、目标值是多少、结果写到哪里。

```text
识别阶段：
本软件写识别任务 JSON + 识别脚本 scdm_probe.py
-> 用 SpaceClaim.exe /RunScript=scdm_probe.py 启动 SCDM
-> SCDM 打开 STEP，并把“识别到什么、哪些参数可改、有哪些限制”写回 JSON
-> 本软件读取结果，翻译成中文能力和参数表，并缓存起来

修改阶段：
本软件写修改任务 JSON + 修改脚本 scdm_edit.py
-> 用 SpaceClaim.exe /RunScript=scdm_edit.py 启动 SCDM
-> SCDM 按任务修改模型，并输出新的 STEP 或失败原因
-> 本软件读取新 STEP，校验通过才替换当前模型；失败就回滚
```

这些中转文件都放在项目的 `local/scdm/` 工作目录里，只用于本软件和 SCDM 后台沟通、调试和失败回放；清掉后可以重新生成，不提交到 Git。以 `ICEPAK-NATURAL.stp` 为例，当前本机路径类似：

```text
local/scdm/ICEPAK-NATURAL_19ff9d1ede49/
├── scdm_probe.py          # 本软件生成，喂给 SCDM 做识别
├── scdm_probe_job.json    # 本软件生成，告诉识别脚本要打开哪个 STEP、结果写哪
├── scdm_raw_features.json # SCDM 写回，原始识别结果
├── scdm_feature_cache.json# 本软件生成，翻译后的中文参数和能力缓存
└── edit/
    ├── scdm_edit.py       # 本软件生成，喂给 SCDM 做修改
    ├── scdm_edit_job.json # 本软件生成，告诉修改脚本改哪个对象、目标值是多少
    ├── result.step        # SCDM 修改成功后输出的新 STEP
    └── error.json         # SCDM 修改失败时输出的错误原因
```

模型文件变更后会重新计算指纹，目录名也会变，旧识别结果不会误用到新模型上。`导出参数` 生成的外部流程组件是另一条链路，不属于本软件和 SCDM 的后台通信。

这里说的“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 内部如何处理相邻面、圆角链、二级/三级拓扑传播，交给 SCDM。本软件不再把手写一级、二级、三级传播当成新增能力主线，只负责把 SCDM 能力适配成可见参数、可执行任务和可校验结果；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]
│   ├── [~] [probe 深度 -> Face / Edge / Body 已稳定遍历，Hole / Round API 真实样例继续补]
│   └── [x] [不能产品化的 raw 结果 -> 只进诊断，不进客户参数表]
│
├── 2. 能力字典、参数表和用户入口
│   ├── [x] [capability key -> 中文名、单位、输入类型、建模意图、后端命令和 postCheck]
│   ├── [x] [参数表 -> 只显示已产品化、可执行、可校验的参数]
│   ├── [x] [不可改 -> UI 阶段直接说明是未实现、命令不可用、识别不完整还是风险过高]
│   ├── [x] [参数化建模 -> 多个目标值统一提交，不再每行一个操作按钮]
│   ├── [x] [导出参数 -> 勾选输入参数后生成组件目录 main.py 和参数 schema]
│   └── [~] [关系式 -> 作为参数表上游输入，计算后回填目标值，已阻止自引用/重复目标/循环依赖]
│
├── 3. 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 已接，真实样例待补]
│
├── 4. 结果校验、回滚和 ID 续接
│   ├── [x] [OCCT 回读 result.step -> 检查输出文件、B-Rep 和基础模型规模]
│   ├── [~] [目标回测 -> 已覆盖数值目标、位置目标、目标特征消失和未编辑对象漂移]
│   ├── [~] [ID 续接 -> 简单唯一匹配已接，歧义/拆分/合并样例继续补]
│   ├── [~] [关系式刷新 -> 修改后按新 cache 重写 Face / Edge / 特征 ID]
│   └── [x] [失败 -> 回滚原模型并给出明确原因]
│
├── 5. 当前已开放或正在开放的 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 间距”修改相邻段；已支持固定前项移动后侧、固定后项移动前侧、两侧均分保持中心]
│
├── 6. 下一批只按 SCDM 能力适配
│   ├── [ ] [阵列实例位置 -> pattern.instance_position]
│   └── [~] [壳体厚度 -> shell.thickness，薄壁候选配对已进 cache，真实命令和 STEP 回测待补]
│
└── 7. 交付与兜底边界
    ├── [x] [软件进度 -> 只展示能识别、不能识别、能修改、不能修改]
    ├── [x] [日志 -> 记录本次使用 SCDM / OCCT / Analysis Situs 哪个后端]
    ├── [x] [Analysis Situs -> 只做辅助定位、兜底识别和开源对照]
    ├── [x] [本地 OCCT -> 只保留已验证兜底能力，不再作为新主线扩展]
    ├── [ ] [商业 SCDM -> 不打包进本软件，只检测客户本机安装和许可证]
    └── [ ] [SCDM 之外的新能力 -> 等 SCDM 能力适配完再评估]
```

短期开发只做第一批能力，不追求把 SCDM 识别到的所有候选都立即开放。`scdm_raw_features.json` 保留 SCDM 发现的全部结构化候选，供后续扩展；`scdm_feature_cache.json` 只保存已经映射到能力字典、能执行、能校验、能解释失败原因的产品化能力。`geometry_candidate_hints` 只表示“有几何证据值得继续分类”，不能当作可编辑参数展示给客户。`软件进度` 弹窗只展示客户关心的能力边界：哪些能识别、哪些不能稳定识别、哪些能修改、哪些暂不能修改；cache 数量、probe 证据、Runner 开放数等后台细节留在日志和开发诊断里。这样既能利用 SCDM 的专业识别和直接建模能力，也不会把未验证的内部候选暴露给客户。

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

一句话状态：Analysis Situs 不再作为当前主识别路线继续接入；它保留为 SCDM-first 路线里的辅助定位、兜底识别和开源对照验证。当前已经完成“孔组识别桥接 + AAG 轻量关系摘要 + 几何关系摘要”，能把拆面圆柱孔组用于整孔高亮、参数表兜底和一级关系计划，也能把外部 AAG 的 Face、邻接、角度类型、共面、同轴、平行、垂直和相切摘要缓存到 `StepModel`，并作为 `recognition_graph.py` 的 `external_*` 关系证据。

当前已完成：

- `[x]` 本地 CLI 桥接：`step_editor/asitus_bridge.py` 会优先查找 `third_party/asitus_probe_tools_build/*/recognize_holes.exe`，再兜底查找旧的 `third_party/asitus_probe_build/*/recognize_holes.exe`，也支持通过 `STEP_EDITOR_ASITUS_RECOGNIZE_HOLES` 指定路径；找不到时不会影响主程序，会退回内部识别。
- `[x]` 可提交 probe 源码：`tools/asitus_probe/` 是当前 Analysis Situs probe 的受控源码，构建输出仍放在被忽略的 `third_party/asitus_probe_tools_build/`。
- `[x]` JSON 解析：支持读取 Analysis Situs 输出的 `holes[].faceIds` / `holeFaceIds`，并去重成孔组。
- `[x]` Face 编号映射：Analysis Situs AAG Face 通常是 1-based，程序会映射回 Python/Qt 里使用的 0-based Face 编号。
- `[x]` UI/模型使用：加载 STEP 后会后台预识别孔组；识别完成后，点击半片圆柱 Face 可以按完整孔组高亮和生成参数。
- `[x]` 缓存与回退：`StepModel` 会缓存外部孔组结果；如果外部 CLI 不存在或失败，会使用 `recognition_graph.py` 的内部 Face 几何图做通孔拆面识别兜底。
- `[x]` AAG 轻量关系摘要：新 probe 会输出 `faces`、`adjacency`、`surfaceSummary` 和 `angleSummary`；Python 会缓存每个 Face 的外部邻接 Face、曲面类型和邻接角度类型，作为识别证据和后续关系增强入口。
- `[x]` 几何关系摘要：新 probe 会输出 `geometricRelations`、`geometricRelationSummary` 和 `geometricRelationMode`，当前覆盖 `coplanar`、`parallel`、`perpendicular`、`coaxial`、`parallel_axis` 和基于 AAG smooth 角度的 `tangent`；Python 会映射回本软件 Face 编号，并在 `recognition_graph.py` 中作为 `external_*` 关系参与统计、拆分圆柱合组和通孔置信度加权。为避免大 STEP 生成巨大 JSON，超过当前阈值时会从全量 pair 扫描降级为只保留 AAG smooth/tangent 关系。
- `[x]` 候选置信度和排序增强：`recognition_priority.py` 会按 `coaxial/tangent/coplanar/parallel/perpendicular/parallel_axis` 给外部关系加权；候选扫描会把 Analysis Situs 关系摘要带到候选行里，同一类特征内部优先显示外部关系证据更强的候选。
- `[x]` 槽 / 凸台 / 圆角辅助识别：`StepModel` 会把 AAG 角度和几何关系汇总成 `analysis_situs_feature_hint_*`，用于提示外部关系更支持槽、凸台还是圆角；这只影响识别摘要、候选置信度和排序，不直接开放新的编辑执行路径。
- `[x]` 回归守门：`scripts/verify_asitus_hole_bridge.py` 已加入 `--quick`，验证孔组 JSON 解析、Face 编号映射、异步安装结果和整孔选择。

本地重新编译 probe：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\build_asitus_probe.ps1
```

当前不再作为主线推进的内容：

- `[ ]` 不再把 Analysis Situs 的完整 AAG 关系图接成主识别数据源；主识别和主修改优先走 SCDM，Analysis Situs 只增强孔、槽、凸台、圆角候选的置信度和排序。
- `[ ]` 不再优先用 Analysis Situs 直接识别倒角、壳体、阵列孔或装配约束；这些高频能力按 SCDM capability 字典逐项产品化。
- `[ ]` 不再让 Analysis Situs 的共面、同轴、平行、垂直、相切关系直接驱动一级/二级编辑计划；它们只作为外部证据，真正能不能改由 SCDM cache、能力字典、编辑计划和结果守门共同决定。
- `[ ]` 还没有把 Analysis Situs CLI 编译产物纳入打包流程；本地没有 `recognize_holes.exe` 时，程序只走内部识别，不会报错退出。
- `[ ]` 暂不做 pybind11 直连；当前 Python 调外部 CLI 的方式更适合作为兜底工具，避免把开源 C++ 分析库直接塞进主 GUI 进程。

后续只在两种情况下继续动 Analysis Situs：

1. SCDM 不可用，需要无商业后端兜底识别孔组或轻量关系。
2. 需要开源结果和 SCDM probe 结果做对照，帮助判断 SCDM 识别是否漏掉明显几何关系。

## 怎么运行

你第一次配置或运行这个项目时，可以按下面步骤来。命令默认在 Windows PowerShell 里执行。

1. 进入项目目录。如果你的仓库不在这个路径，把命令里的路径换成你的实际目录：

```powershell
cd C:\Users\admin\Desktop\python-occt
```

2. 如果你已经有 `pyocc` 环境，直接激活：

```powershell
conda activate pyocc
```

3. 如果你是第一次配置环境，先用仓库里的 `environment.yml` 创建环境，再激活：

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

4. 先跑一次烟测，确认入口和依赖能正常加载。这个命令不会进入交互窗口：

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

5. 快速启动程序。此时不读取默认模型，窗口会先进入空场景：

```powershell
python main.py
```

6. 启动时直接打开指定 STEP 文件。只有显式传入路径时，程序才会启动后自动读取该模型：

```powershell
python main.py path\to\model.step
```

7. 也可以先启动程序，在左侧 `STEP文件` 区域点击 `导入几何模型` 选择 `.step` / `.stp` 文件；选择后会立即读取模型。`读取模型` 用于按当前路径重新加载。

8. 打开仓库自带的简单立方体测试模型：

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

9. 重新生成简单立方体测试模型：

```powershell
python scripts\generate_cube_step.py
```

10. 验证几何修改基线。当前主线按 SCDM capability 适配推进；下面这个入口仍保留历史 OCCT/一级编辑回归，用来证明本地兜底能力、UI 和文档守门没有退化：

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

只想先跑轻量检查时：

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

`--quick` 会检查 smoke test、属性表规格、参数表 UI、参数导出组件生成、SCDM 后端发现底座、SCDM 状态摘要、SCDM probe/cache 假数据管线、SCDM edit job/runner 协议、SCDM result validator、ICEPAK 真实 STEP 同域圆柱孔、特征识别优先级、一级事实图、关联探测、显示网格预算，以及 README 里的一级验收口径是否仍和脚本入口一致。

只验证某个阶段时，例如 Edge：

```powershell
python scripts\verify_first_level_edit_suites.py --stage edge
```

也可以按阶段手动运行：

```powershell
python scripts\verify_face_edit_suite.py
python scripts\verify_isolated_face_edit.py
python scripts\verify_hole_slot_edit_suite.py
python scripts\verify_edge_edit_suite.py
python scripts\verify_edge_isolated_edit.py
python scripts\verify_boss_edit_suite.py
python scripts\verify_round_chamfer_edit_suite.py
python scripts\verify_shell_edit_suite.py
python scripts\verify_analytic_surface_resize.py
python scripts\verify_boss_resize.py
python scripts\verify_hole_resize.py
python scripts\verify_slot_resize.py
python scripts\verify_hole_slot_isolated_edit.py
python scripts\verify_cylindrical_first_level_topology.py
```

11. 如果当前 PowerShell 没识别 `conda`，你可以直接使用完整路径运行：

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

如果用 `conda run` 跑验证脚本时出现 Conda 自身的 `UnicodeEncodeError`，先设置 UTF-8 输出再重跑：

```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
```

## Windows 文件夹版打包

如果你要把软件发给没有 Python 环境的人，当前先打包成文件夹版。推荐先激活 `pyocc`，再运行打包脚本：

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

脚本会先跑源码烟测，再用 PyInstaller 生成 `dist\GeometryParametric\main.exe`，并自动把仓库自带 STEP 模型复制到 `dist\GeometryParametric\model\`。如果本机存在 `local\几何参数化测试说明.txt`，打包后的文件夹里也会带同名说明文档，方便模型工程师直接按说明测试。

最终压缩包固定生成在：

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

这个 `dist` 目录和 zip 包是本地构建产物，默认不提交到 Git。

开发时常用的本地检查：

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

## 最终要实现什么

最终目标是做一个面向 STEP 模型的交互式工具：

- 加载 `.step` / `.stp` 模型文件。
- 展示三维模型，支持旋转、缩放、平移。
- 读取 STEP 中的零件、装配、Solid 等结构。
- 用户可以选择零件、Solid、Face、Edge 和几何特征。
- 用户可以做基础测量，例如把两个拾取点或对象中心设为 A/B 并计算距离。
- 程序可以识别孔、圆角、凸台、槽、壳体局部区域等候选特征。
- 识别结果会区分 `当前可改`、`当前受限修改`、`识别限制` 和 `受限能力`：比如一个通孔可以改孔径，但盲孔深度属于受限能力；一个带内孔的平面可以拉伸/切除，但“局部重建尺寸/偏移”会被标成受限修改。
- 用户可以修改可控的特征，比如 Face 的偏移、稳定矩形/简单全平面 Face 的面内长度和面内宽度、壳体厚度，并通过 `建模意图` 选择拉伸/切除、局部重建、移动特征或缩放特征；面积是结果变量，放在诊断信息里查看，不作为特征参数表里的驱动变量。Face/直线 Edge 的 `中心` 移动后端能力暂时保留，但不在特征参数表开放。还可以做孔径/半径调整、孔/槽轴心并通过 `建模意图` 选择移动局部特征或移动特征、槽宽/槽深/弧长并通过 `建模意图` 选择局部重建或整体缩放、弧角、开口角和槽孔总长度调整、盲孔/盲槽深度(局部切补或整体缩放)、壳体厚度(局部拉伸/切除或整体缩放)、凸台直径/半径/高度/轴心并通过 `建模意图` 选择局部修改或整体调整、普通完整圆柱高度兜底修改、已有圆角半径/圆弧长度、简单等半径圆角链半径/弧长并通过 `建模意图` 选择重建圆角或整体调整、已有等距倒角距离、圆锥参考半径/直径/半角(简单圆锥解析重建，嵌入式锥孔优先局部重切)、球面半径/直径(缩放特征)、环面主/小半径或直径(缩放特征)、Edge倒圆、Edge倒角、圆Edge半径/直径并通过 `建模意图` 选择自动/相邻圆柱/缩放所属、修改Edge长度并通过 `建模意图` 选择自动/只改当前Edge/移动端面/相邻圆柱/缩放所属，以及直线Edge起点/终点坐标。
- 用户可以撤销/重做修改，避免一步编辑做坏。
- 用户可以导出修改后的完整模型。
- 如果 STEP 文件里存在多个互不关联的零件，用户可以只导出选中的某个零件。

需要注意：STEP 文件通常是 B-Rep 几何数据，不是带完整建模历史的参数化 CAD 原文件。所以“随便选一条边改长度”不一定能稳定实现，实际会转化成更可靠的操作，比如移动某个面、重切某个孔、调整某个圆角等。

## 几何修改语义原则

所有可修改参数都要先明确“这次修改到底代表什么”，不能只因为程序能算出一个结果就直接放行。这个原则适用于 Face、Edge、孔、槽、凸台、圆角、Solid 和整件特征，不是 Edge 专属。比如修改 Face 可能代表 Face 拉伸/切除、局部补料、局部切削、平移所属对象或整体缩放；修改孔/槽可能代表重切侧壁、移动轴心、调整端面深度或重新配对长圆槽端部；修改圆角可能代表移除旧圆角后重建；修改 Edge 可能代表只动这条边、移动相关端面，或者高风险地缩放所属几何。

所以每个可编辑行都应尽量说明本次采用的建模意图、执行影响和风险；当同一个目标值有多种合理语义时，应逐步做成用户可选择的策略，而不是程序悄悄替用户决定。高风险 fallback 必须提示用户确认，不能把整体尺寸变化、局部形变、Face 拉伸/切除、切削补料、对象平移、对象缩放和特征重建混成一个简单的“修改成功”。

Creo 资料的参考价值不只是统一术语，还要用来组织功能入口和操作流程。界面不应优先暴露底层 B-Rep 字段，而应先把选中对象映射到 CAD 用户熟悉的建模形式，例如拉伸/切除、偏移、孔、槽、倒圆角、倒角、抽壳、拔模、移动几何和缩放特征；只有当识别结果足够稳定，才把对应的可改尺寸放出来。

当前 Face 参数化修改已经接入隔离子进程执行，特征参数表面向用户开放 `拉伸/切除`、`偏移(局部重建/移动特征)`、`面内长度/面内宽度(局部重建或缩放特征)`、`壳体厚度(拉伸/切除或缩放特征)`、普通圆柱高度、圆柱凸台高度，以及圆锥参考半径/直径/半角、球面半径/直径、环面主/小半径或直径；`中心` 移动后端能力暂时保留但不在特征参数表开放。面积仍作为诊断和校验结果保留，但不再作为表格里的可编辑驱动参数。主程序和 helper 进程之间优先使用内部 BREP 临时文件传递当前 B-Rep，避免每次参数化建模都先做一轮 STEP 导出/导入；对外导入和导出仍然保持 STEP。helper 进程负责执行危险 OCCT 计算并写回结果文件，再由主程序加载成功结果；如果 helper 卡死、超时或崩溃，主界面进程和原模型保持不变。关闭窗口时如果正在运行隔离子进程，主程序会请求终止该子进程，避免用户被长时间计算锁住。打包后的 `main.exe` 也会通过 `--isolated-edit-worker` 进入同一条 worker 通道，避免子进程误打开第二个 GUI。无法识别为简单圆锥或锥孔/沉孔的复杂圆锥/拔模面参考半径、参考直径和半角暂不开放，不再退回整体径向缩放；复杂浅锥/拔模面会在计划阶段快速阻止，避免界面线程长时间等待或生成无效 B-Rep。仍未归类到明确 Face、孔槽或 Edge 语义的复杂 fallback 会继续被稳定性保护阻止，后续按特征逐步开放。

孔/槽一级关系的主要布尔/重建入口也开始复用同一条隔离执行通道，包括孔径、圆柱尺寸缩放、孔轴心、孔封堵、盲孔/盲槽深度、槽/半孔轴心、槽宽、槽深、圆弧长度、圆弧角度、长圆槽总长度和中心距。这样即使孔/槽局部重切在复杂 STEP 上失败、超时或触发 OCCT 崩溃，主界面和原模型也应保持不变。圆柱直径整体缩放和盲孔/盲槽深度整体缩放会在模型层做结果校验；如果结果虽然是有效 B-Rep，但已经丢失目标圆柱/盲孔语义，会自动回滚并提示原因。

Edge 一级关系的主要高风险入口也接入同一条隔离执行通道，包括修改 Edge 长度、直线 Edge 起点/中心/终点移动、圆形 Edge 相邻轴心移动、椭圆 Edge 主/小半径、已有圆角半径/弧长、简单等半径圆角链半径/弧长、已有简单倒角距离、直线 Edge 新增圆角、对称倒角、不等距倒角和距离+角度倒角。Edge 操作仍然不是通用 CAD 历史特征编辑；复杂曲线、变半径圆角链、复杂倒角链、无法确认一级邻域或 OCCT 倒圆/倒角失败时会回滚或提示失败，但这些危险计算不应再拖垮主界面进程。

Face 编辑失败、超时或被稳定性保护阻止时，弹窗不应只显示底层 OCCT 异常。当前会尽量附带诊断信息：操作对象、Face 类型、目标值/目标位置、一级边界 Edge/Vertex、共享边相邻 Face、内孔/内边界数量、已识别的端盖专用路径，以及是否可能因为孔壁、槽底、台阶终点等二级/三级关系暂未传播而失败。

复杂大 STEP 里的多边界平面端盖不再在 UI 线程同步生成完整 `push_pull_plan`。界面只做轻量预检查并标记高风险，然后把完整一级关系识别、解析重建或快速阻止放到后台隔离进程里执行，避免用户点击 `参数化建模` 后先卡住几秒到几十秒。

如果轻量预检查已经能判断出风险不可接受，比如复杂大模型里的多内孔端盖向内切除已经接近切穿，或需要判断孔底、槽底、台阶背后的二级关系，界面会直接阻止并说明原因，不再提交隔离子进程等待失败返回。浅范围内的多内孔端盖向内收缩会走后台/隔离子进程里的一级边界侧壁重建。

复杂大 STEP 中带内孔/内边界的平面 Face，如果用户选择 `面内长度/面内宽度(局部重建)`、`中心(局部重建)` 或 `偏移(局部重建)` 这类“只改当前 Face 顶点并重建相邻面”的局部变形语义，UI 会在轻量预检查阶段直接阻止并说明原因，不再先进入完整局部重建计划。`壳体厚度(拉伸/切除)` 在这类复杂面上会先标记为后台高风险计划，把相对面识别和拉伸/切除距离计算放进隔离进程，避免主界面等待复杂拓扑扫描。

普通平面 Face 的核心修改路径现在还会在模型层做结果守门：执行后必须通过 B-Rep 校验、能重新找到目标 Face 的目标值，并且能重新识别该 Face 的一级共享边邻域。矩形、多边形 Face 会检查边界 Edge 和 Vertex；圆形端盖这类解析边界会允许 1 条闭合圆 Edge。圆锥参考半径/半角、球面半径、环面半径这类解析 Face 也会强制校验目标值和 B-Rep。若目标值没达到、一级邻域丢失或 B-Rep 无效，模型层会恢复操作前 shape，不把坏结果交给界面或导出流程。

`拉伸/切除` 对一次性较大的向外拉伸不会按绝对距离一刀切阻止；如果距离相对当前 Face 或所属实体跨度较大，会标为高风险并走隔离子进程执行。这样可以允许用户做类似 CAD 里的大距离拉伸，同时如果 OCCT 布尔失败、超时或返回无效 B-Rep，主程序和原模型仍保持不变。

实心圆柱或同轴空心筒体的端盖拉伸/切除会优先走解析/局部重建：选中圆柱上/下底面或环形端面时，程序会识别相邻外圆柱面、内孔圆柱面和端盖一级关系。纯简单圆柱/筒体会直接重建新的完整高度；如果同一 Solid 上还有不碰端盖边界的侧向缺口、台阶等额外特征，向外拉伸会只生成旧端盖到新端盖之间的局部延长段去补料，向内切除会只切除旧端盖到新端盖之间的局部段，避免拿整根新圆柱/新筒体或通用平面 prism 和原模型做大范围布尔。同轴阶梯/盲孔式环形端盖允许内外圆柱侧面的旧深度不同；向外拉伸时会保留旧侧面的复杂底部裁剪，只删除旧端盖，并补上旧端盖到新端盖之间的侧面段和新端盖，结果校验会优先检查新增端盖而不是全模型扫描。如果端盖边界本身连接了槽、缺口或台阶等额外一级相邻 Face，向外拉伸会改用当前端盖真实轮廓拉伸，让这些开口边界跟随延长；向内切除如果没有越过这些开口的内侧终点，会改用当前端盖真实轮廓切削，让开口边界跟随缩短；如果越过槽底/台阶内侧终点，会快速阻止并说明原因。无法确认同轴圆柱/筒体一级关系时，才退回隔离子进程里的通用拉伸/切除和回滚保护。

带多个内孔/内边界的大平面端盖如果不能归类成同轴圆柱/筒体端盖，会优先改走 `boundary-shell-rebuild`：移动当前端面，并把该端面的一级边界 Edge 沿拉伸/切除方向重建侧壁后局部缝合，避免复杂 STEP 退回 180s 通用布尔慢路径。向外拉伸会生成延长侧壁；浅范围向内收缩会重建缩短后的侧壁并保留内孔线圈；如果向内距离接近切穿，或需要判断槽底、台阶终点、孔壁背后的二级/三级关系，会快速阻止并把原因写清楚。

选中普通完整圆柱侧面修改 `高度` 时，局部语义会换算成端盖拉伸/切除：执行后必须重新检测到同轴、同半径、目标高度的圆柱侧面，并且圆柱一级边界/相邻 Face 关系没有丢失，否则自动回滚。`缩放特征` 语义会沿圆柱轴向缩放所属特征或 Solid，执行后按轴向跨度校验目标高度；这条语义可能影响同一对象上的孔距、台阶位置和其它轴向尺寸。

产品目标里必须明确保留“用户选择建模意图”的能力。以正方体改一条 Edge 为例，用户应该能区分并选择：只拉长这一条 Edge 让相邻面自然变斜、移动相关端面让正方体变成长方体、保持某些面垂直、固定某些边/点不动，或者让某些相邻边跟随变化。这个原则不是 Edge 专属，Face、孔、槽、凸台、圆角、Solid 和整件特征也一样：当一个目标值存在多种合理 CAD 语义时，界面应让用户选择“改法、约束、影响对象和哪些几何跟随变化”，不能无脑套用一个默认结果。当前 Edge 的 `移动端面/保持垂直` 就是这类语义：它不是只拉歪一条边，而是让端面和相关边跟随移动，使相邻平面尽量保持垂直。

设计上优先把选择做成当前选中对象里的清晰属性行或策略控件，而不是弹出一堆工程术语。每个可选策略都要用用户能看懂的话说明结果，例如“只改当前边，邻面会变斜”“移动端面，整体变成长方体”“缩放所属对象，所有尺寸同比例变化”“重切孔壁，只改孔径”。默认策略可以存在，但必须可见、可解释、可切换。

界面里的 `特征参数` 只显示能直接修改的输入参数，不再混入 `建模形式`、`推荐操作`、`一级关系`、`关联探测` 这类诊断说明。程序内部仍会计算这些信息，用来决定哪些参数可显示、哪些操作要阻止，以及失败时该给出什么原因。对于同一个尺寸存在多种语义的情况，例如圆柱直径/半径，用户仍通过 `建模意图` 明确选择“重切/重建局部特征”还是“按目标尺寸比例均匀缩放所属特征或 Solid”。

## 开源复用原则

三维几何计算要优先复用成熟开源库和几何内核，不要自己从零实现已经可靠存在的底层能力。当前项目已经通过 `pythonocc` 复用 OpenCascade，用它处理 STEP 读写、B-Rep 拓扑、布尔、倒角/圆角、曲面和基础几何计算；后续如果发现合适的开源库，也可以接入用于网格、约束求解、几何分析或文件格式转换。

但不能直接从 GitHub 随便复制功能代码。引入外部项目之前必须先看许可证、维护状态、依赖体积、Windows/Conda 兼容性，以及它是否能接进本项目的选择状态、属性表、确认窗口、后台执行、失败回滚、操作历史和验证脚本。MIT/BSD/Apache 这类宽松许可证通常更容易复用；GPL/AGPL 代码要非常谨慎，避免影响整个项目授权。优先原则是“复用库和算法能力，少复制产品代码；能通过依赖调用就不要粘贴实现”。

## 最小系统先实现什么

最小系统目标是先把完整工作链路打通：

- 能打开 STEP。
- 能显示模型。
- 能读取 STEP 中的零件/装配标签。
- 能选择零件、Solid、Face、Edge 和特征。
- 能显示选中对象的基本属性。
- 能高亮选中对象。
- 能导出整个当前模型。
- 能导出选中的零件。
- 能撤销/重做编辑。
- 先实现少量可控编辑操作，用于验证后续特征编辑路线。
- 当前开发顺序固定按上面的 `SCDM-first 主路线` 推进：先打通 SCDM 识别、能力字典、参数表、执行、校验和 ID 续接闭环，再按 SCDM 已能结构化表达的 Face、孔、槽、凸台、圆角/倒角、阵列、壳体能力逐项适配。历史 OCCT/一级编辑套件继续作为兜底回归，不再作为新增能力主线。

## 能改哪些，一分钟版

如果你只想快速判断一个 STEP 模型现在能不能改，先看这张表；更细的参数和风险在下一节。

| 对象 | 现在能改哪些 | 程序大概怎么改 | 暂时还不能稳定改 |
| --- | --- | --- | --- |
| Edge / 边 | 直线边的长度、起点、终点；直线边新增圆角/倒角；圆形或圆弧边的半径/直径、圆心/相邻轴心；椭圆边的主半径/小半径。 | 简单模型优先局部重建当前边和相邻面；圆边可复用相邻圆柱改孔/槽/凸台直径或轴心；椭圆边可沿主轴或小轴单轴缩放所属特征。 | 任意复杂曲线边、B-spline 边、需要复杂约束跟随的边；直线 Edge 中心移动暂不在参数表开放。 |
| Face / 面 | 偏移、壳体厚度；稳定矩形/简单全平面 Face 的面内长度、面内宽度；圆柱端盖或完整圆柱侧面的高度。面积作为诊断结果只读展示。 | 拉伸/切除当前平面或圆柱端盖；稳定矩形特征按尺寸局部重建相邻面；或缩放所属特征。 | 自由曲面会明确识别为只读，不开放伪参数化修改；Face 中心移动暂不在参数表开放；带复杂内孔的面、普通曲面、复杂壳体局部区域、非完整圆柱侧面高度。 |
| 孔 / 圆柱孔 | 规则孔的直径/半径、完整孔轴心、完整孔封堵、可识别盲孔/盲槽深度。 | 改孔径时同轴重切孔壁；移动孔时先补旧孔再切新孔；改深度时切削或补料孔底。 | 螺纹孔、锥孔、复杂孔组、底面识别不可靠的盲孔。 |
| 槽 / 半孔 | 槽宽、槽深、弧长、弧角、开口角、简单轴心、长圆槽总长度/中心距；规则矩形槽/口袋的长宽和深度。 | 按圆柱槽、长圆槽胶囊区域或矩形切除包络，先补旧槽，再切出新槽。 | 复杂草图槽、非圆柱槽、多槽联动、跨复杂面的槽；矩形槽中心移动暂不在参数表开放。 |
| 凸台 / 外圆 | 圆柱凸台的直径/半径、高度、轴心；规则矩形凸台/口袋的长度、宽度、高度/深度；多台阶矩形凸台的顶层规则台阶。 | 移除旧特征包络后重建；或拉伸/切除端盖、轴向缩放；多台阶中间过渡面会识别为受限并快速阻止。 | 异形凸台、多台阶凸台整组联动、复杂相邻拓扑；矩形中心移动暂不在参数表开放。 |
| 圆角 / 倒角 | 部分已有圆角的半径/弧长；简单等半径圆角链半径/弧长；直线边新增圆角或倒角；变半径/复杂圆角链可识别并快速阻止。 | 已有简单圆角和简单等半径圆角链先移除再重建；新增圆角/倒角调用 OCCT 的圆角/倒角算法；变半径圆角链和复杂 blend 不进入危险重建。 | 大链式 blend、变半径圆角稳定重建、复杂角部补面、支撑面不明确的圆角。 |
| Solid / 整体特征 | 平移、旋转、包围盒尺寸、体积、表面积整体缩放。 | 对所属 Solid / 特征做整体变换。 | 装配约束、零件间关联约束、原 CAD 建模历史恢复。 |

## 当前可修改范围

这张表描述的是当前版本已经接入到界面或编辑链路里的能力。它们都是基于 STEP 的 B-Rep 结果几何做局部重建，不等于原 CAD 软件里的完整建模历史参数。

| 对象 / 特征 | 现在可以修改 | 暂不能保证或还不能修改 |
| --- | --- | --- |
| Face | 平面 Face 总是优先开放 `偏移`；只有识别为稳定矩形凸台/口袋或简单全平面实体时，才显示 `面内长度` 和 `面内宽度`。这些行会在 `建模意图` 里选择 `局部重建`、`拉伸/切除`、`移动特征` 或 `缩放特征`。面积是结果变量，只在诊断信息里展示。识别到相对平面时还可以改 `壳体厚度`，并通过 `建模意图` 选择 `拉伸/切除` 或 `缩放特征`。圆柱上/下端盖、同轴空心圆柱的环形端面可以通过 `拉伸/切除` 改高度；选中完整圆柱侧面时，也可以把 `高度` 换算成端盖拉伸/切除，或者选择沿轴向 `缩放特征`。简单端盖会解析重建，复杂同轴筒体会优先只处理旧端盖到新端盖之间的局部段，端盖边界上有槽口/缺口时会按真实端盖轮廓向外拉伸或在安全范围内向内切削。 | `面内长度/面内宽度` 是矩形平面特征在两个主方向上的驱动尺寸，不是任意曲面尺寸，不是面积，也不是模型高度；不满足稳定识别时这两行不会出现在特征参数表里。`偏移` 是沿当前面垂直方向测到的位置，不再单独显示容易混淆的额外的“本次移动量”提示。`拉伸/切除` 会加料或切削；`局部重建` 会重建当前矩形特征，相邻面按新边界更新；`缩放特征` 会缩放所属特征或 Solid 并影响其它尺寸；`中心` 移动后端能力暂时保留，但客户参数表不开放；自由曲面会显示为只读受限对象，不把面积、中心、包围盒或底层 UV 参数伪装成可修改尺寸；复杂壳体局部区域、非完整圆柱侧面、非同轴多孔环形端面、端盖边界本身连着槽/缺口/台阶且向内切除越过槽底/台阶终点的面和其它带复杂边界的面仍不能稳定做局部尺寸编辑，界面会禁用或快速阻止并在提示里说明具体原因，建议改用孔/槽专门入口、`拉伸/切除` 的简单端盖路径或整体调整。 |
| 圆柱孔 / 圆柱面 | 孔或圆柱的 `直径`、`半径`，并通过 `建模意图` 选择 `只改孔/槽壁` 或 `缩放特征`；完整圆柱孔可以改轴心坐标；完整孔可以尝试封堵。普通孔径语义是同轴圆柱重切，孔轴心语义是先填旧孔再切新孔。 | 复杂孔、螺纹孔、锥孔、不完整圆柱孔和拓扑不稳定的孔可能失败并回滚；`缩放特征` 会影响同一对象上的高度、厚度和其它尺寸，不适合只想改孔壁的场景。 |
| 盲孔 / 盲槽 | 识别到疑似底面 Face 时，可以改 `盲孔/盲槽深度`，并通过 `建模意图` 选择 `改底面深度` 或 `缩放特征`。`改底面深度` 加深会沿开口到底面方向切削，变浅会从新底面到旧底面补料；`缩放特征` 会沿孔/槽轴向缩放所属特征或 Solid。 | STEP 不保存真实孔深历史；找不到可靠底面或底面被复杂拓扑切碎时，深度只能只读或需要手动辅助；`缩放特征` 会影响同一对象上的壁厚、孔距和其它轴向尺寸，不适合只想改孔底位置的场景。 |
| 槽 / 半孔 | 可以改槽宽、槽深、弧长、弧角、开口角和简单局部轴心；槽宽、槽深和弧长会在 `建模意图` 里选择 `只改槽壁` 或 `缩放特征`。长圆槽的轴心、总长度和中心距会在点击修改时自动尝试配对另一个半圆端，也可以手动填写配对端 Face ID。规则矩形槽/口袋可以改长宽和深度。复杂/交叉槽会识别为受限，不暴露伪可改槽参数。 | 轴心仍是受限的局部扇形槽/胶囊槽重建；复杂草图槽、非圆柱槽、多槽关联迁移、链式槽和跨多个不规则面的槽还不是稳定能力。矩形槽/口袋会局部重建矩形切除包络，但长宽方向交换和中心移动暂不在参数表开放。`只改槽壁` 会局部重建槽，`缩放特征` 会缩放所属对象并影响其它尺寸；如果结果真的把一个 Solid 拆成多个 Solid，会自动回滚。 |
| 圆柱凸台 / 外圆 | 完整圆柱凸台可以改直径、半径、高度和轴心；普通完整圆柱也有高度兜底修改。凸台的 `直径`、`半径`、`高度` 和 `轴心` 会在 `建模意图` 里选择 `只改凸台`、`拉伸/切除端盖`、`移动凸台`、`缩放特征` 或 `移动特征`。多台阶矩形凸台的顶层规则台阶可以独立修改；中间过渡面会识别为复杂多台阶凸台并禁用伪可改参数。 | 复杂凸台、异形凸台、多台阶凸台整组联动和不完整外圆不能保证稳定重建；`缩放特征` 会连带改变同一对象上的高度、厚度和其它尺寸，不能当作单独重建凸台包络或只移动端盖使用。 |
| 已有圆角 / 倒圆面 / 简单倒角面 | 部分规则圆柱倒圆面可以改 `圆角半径` 或 `圆角弧长`，简单等半径圆角链可以改整链半径/弧长，并通过 `建模意图` 选择 `重建圆角` 或 `缩放特征`。`重建圆角` 会先移除旧圆角面或链上圆角面，再重建新圆角；`缩放特征` 会把目标值换算为圆柱直径比例，再整体缩放所属特征或 Solid。选中简单等距倒角斜面时可以改 `倒角距离`，当前同样走“移除旧斜面 -> 恢复锐边 -> 重新倒角”。相邻不同半径圆角 Face 会被标成变半径圆角链，计划阶段直接提示暂未实现稳定重建。 | 大链式 blend、复杂角部补面、支撑面不明确、变半径圆角稳定重建、复杂倒角链、不等距已有倒角或恢复锐边失败时会阻止或回滚；`缩放特征` 会影响同一对象上的其它尺寸，不适合只想改圆角本身的场景。 |
| Edge | 直线 Edge 可以尝试改目标长度、起点坐标和终点坐标；直线 Edge 可以加倒圆、对称倒角、不等距倒角和距离+角度倒角；圆形/圆弧 Edge 可以尝试改半径、直径和 `圆心/轴心`，其中圆心移动会把圆边移动量转成相邻孔/槽/凸台的轴心移动；椭圆 Edge 可以改 `椭圆主半径` 或 `椭圆小半径`，分别沿主轴或小轴单轴缩放所属对象。 | “通用任意 Edge”仍未作为稳定能力开放；复杂曲线、B-spline、Bezier 和无法确定局部变形区域的 Edge 不会在扫描列表或参数表里显示为可改长度入口；直线 Edge 中心坐标后端保留但参数表暂不开放；圆Edge轴心移动需要找到稳定相邻圆柱特征；椭圆单轴缩放会影响同一对象上同方向的其它几何，不是恢复 CAD 草图约束。 |
| 圆锥 / 球 / 环面 | 圆锥可以改 `参考半径`、`参考直径` 或 `半角`：简单圆锥会解析重建，嵌入式锥孔/沉孔会优先局部重切；选中圆锥特征时会显示可识别的小端半径、大端半径、锥孔高度和半角，便于判断真实修改对象。球面可以改 `半径(缩放特征)` 或 `直径(缩放特征)`；环面可以改 `主半径(缩放特征)`、`主直径(缩放特征)`、`小半径(缩放特征)` 或 `小直径(缩放特征)`。 | B-Rep 里的 Face 可以是平面、圆柱面、圆锥面等；半角属于圆锥面属性，1° 左右的浅锥/拔模面看起来会很像平面。圆锥局部重切主要覆盖可识别的双圆边界锥孔；复杂圆锥/拔模面的参考半径、参考直径和半角暂不开放，会提前禁用或快速阻止，而不是进入危险整体缩放或布尔计算。解析曲面的识别评分过低、置信度低或存在识别限制时，属性会保留当前值展示，但修改按钮会变为不可用并显示原因。其它复杂球面和环面仍可能几何缩放所属特征或 Solid，不是恢复原 CAD 历史参数，复杂相邻拓扑可能失败或回滚。 |
| Solid / 特征整体 | 可以对选中 Solid 或当前单一模型做平移、旋转和按包围盒尺寸 / 体积 / 表面积的缩放类修改。 | 还没有装配约束、零件间关联约束或完整多零件装配编辑。 |
| 只读信息 | 面积、体积、包围盒、曲面类型、相邻关系、候选特征说明等会展示出来帮助判断。 | 标成只读的值不会被 `参数化建模` 修改；显示、测量和导出不是建模操作。 |

## 现在已经实现了什么

当前已经实现：

- 启动后默认进入空场景，不自动读取 `assets/models/geom_extract.step`；用户点击“导入几何模型”后才加载模型，避免客户打开软件时被大 STEP 阻塞。
- 支持打开其他 `.step` / `.stp` 文件。
- 打开 STEP 时会在 `LoadWorker` 后台线程里完成读取和首屏显示网格生成；失败时当前模型保持不变。大模型不会再把 STEP 读取、B-Rep 网格生成和 VTK polydata 构建直接压在 UI 主线程上，并且默认只先显示面片，几千条 Edge 边线会在切到 Edge 选择或显式请求时再后台生成。
- 使用 XCAF 读取 STEP 中的零件 / Assembly 标签；代码内部仍沿用 `PartNode` / `part_id` 作为结构名。
- 模型结构树会用中文显示 STEP 里的装配、零件和实体层级，并在对应零件下面列出实体子节点。
- 点击模型结构树中的实体子节点，可以直接选中、高亮、查看属性并用于导出该实体。
- 使用 OCCT 读取真实 B-Rep 拓扑。
- 使用 VTK 显示模型，并通过 PySide6/Qt 承载桌面界面。
- 左侧操作面板按功能模块分组显示，并使用四边同色的轻量彩色边框和标题层级区分文件、模型树、选择、编辑、导出、显示、测量、候选、历史和属性信息。
- 支持选择模式：
  - Part
  - Solid
  - Face
  - Edge
  - Feature
- 鼠标悬停对象会以红色预高亮，真正选中后会以黄色高亮。
- 普通 Face / 特征点选优先走轻量选择：只高亮命中的对象并显示基础参数，避免旋转、悬停、点选时触发同域面、端盖、底面等重计算；大模型会关闭鼠标悬停拾取高亮，只保留点击选择；真正执行编辑计划、扫描候选或历史定位时才做更深识别。
- 大模型的 VTK 显示网格带有预算保护：即使编辑后请求较细的显示 deflection，也不会对上千个 Face 的 STEP 无限制生成百万级圆柱三角面；B-Rep 几何编辑和结果校验仍使用真实拓扑，显示网格只负责渲染和拾取。只显示少量 Face 或隔离选中对象时仍可局部细化这些 Face，不会触发全模型超细重网格。
- SCDM 识别 cache 的本地 Face 映射现在使用轻量几何签名，只读取曲面类型、平面法向/偏移、圆柱轴线/半径等必要信息；不再为每个 Face 调完整 `quick_face_info()`，且签名生成放在后台 worker 内执行，不会在启动 SCDM probe 前卡住 UI。在 `geom_extract.step` 上，这一步从约 83 秒降到约 0.06 秒。
- 拉伸/切除后程序会尽量保留侧壁面区域的 `逻辑 Face ID`：即使 OCCT 把原来的一个侧壁拓扑Face重建成上下两段，新旧两段也会绑定回拉伸/切除前那片侧壁的逻辑 ID。属性表会同时显示 `逻辑 Face ID` 和 `拓扑 Face ID`；前者面向用户选择和按 ID 定位，后者用于调试当前 B-Rep 拓扑。
- 操作历史会记录 `target_logical_id` 和当时的拓扑Face ID。点击历史记录定位Face / 特征时，会优先用逻辑 ID 找回当前模型中的整片面区域；撤销/重做快照也会保留这层逻辑 ID 映射。
- 鼠标选择会按当前模式做就近映射；例如 `Edge` 模式点到面时，会自动选择鼠标附近的边界Edge。
- 支持按当前选择模式输入 ID 直接选择零件 / Solid / Face / Edge / 特征。
- Face / 特征按 ID 选择会优先解析 `逻辑 Face ID`。例如拉伸/切除前侧壁是 558，拉伸/切除后当前拓扑里变成 1556 和 1802，只要它们被绑定到逻辑 558，输入 558 就会选中这片面区域。
- Face / 特征的 `复制 ID` 也优先复制 `逻辑 Face ID`，属性区会同时显示 `逻辑选择 ID` 和 `当前拓扑 Face ID`；这样编辑后拓扑编号变化时，用户仍能用原来的逻辑 ID 回到同一个面区域。
- `鼠标选择模式` 下拉框关闭时会把鼠标滚轮交还给左侧滚动面板，避免鼠标经过时误切换模式；打开下拉列表后仍可用滚轮滚动选项。
- `按 ID 选择` 会在输入框和 `选择` 按钮之间同步显示当前鼠标选择模式。
- `Feature` 模式现在会把点到的Face解释为几何特征候选：
  - 平面会识别为可拉伸/切除平面候选。
  - 平面会尝试查找同一Solid内投影重叠的相对平面，用于估算壳体局部区域厚度。
  - 圆柱面会识别为圆柱孔候选、槽/半孔候选、圆角/倒圆候选、凸台/外圆候选或未明确圆柱特征。
  - 圆柱特征会先把同一实体内同轴、同半径且轴向连续/重叠的完整圆柱Face当作同一侧壁区域，再尝试找出边界Edge、相邻Face、端面Face、开口端相邻Face和疑似底面 Face，并一起高亮相关局部区域。
  - 槽/半孔候选会额外显示槽宽、圆弧长度、槽深估算和槽边界相邻Face。
  - 圆角/倒圆候选会额外显示已有圆角半径估算、圆弧角度、圆弧长度和相邻支撑Face；如果共享边连通的同半径圆角 Face 形成 2 到 4 个面的简单小链，会标出链内 Face 并尝试整链半径/弧长重建；变半径或复杂长链会快速阻止。
- `特征探测级别` 切到 `探测相邻特征` 或 `探测二级特征` 后，关联孔、槽、凸台等可改尺寸可以作为 `关联 Face` 参数行合并到同一张参数表里；`关联探测` 本身属于诊断信息，不占用特征参数表。
- 当前选中对象表使用四列表格：`尺寸参数`、`当前值`、`建模意图` 和 `目标值`。表格只放可作为建模输入的尺寸，面积、识别摘要、一级关系、关联探测和其它只读诊断放在下方 `诊断信息（高级）` 中；用户改完目标值后统一点击 `参数化建模`，不再保留逐行执行入口。
- 属性面板会统一显示 `识别摘要`、`识别候选`、`识别置信度`、`识别风险`、`识别评分`、`识别结论`、`识别依据`、`识别限制` 和 `受限能力`。这些字段来自当前已知的 B-Rep 几何事实、一级拓扑关系、同域区域、材料采样和阻止原因，用来说明程序为什么把对象当作某类候选，而不是把猜测隐藏在代码里。`识别限制` 表示这个候选整体不能稳定编辑；`受限能力` 表示对象本身可识别、某些修改可用，但另一些子能力暂不开放。低置信解析曲面不会开放可编辑按钮，避免把“底层曲面类型像圆锥/球/环面”误当成稳定 CAD 设计参数。
- 模型层提供统一的一级拓扑事实包 `face_first_level_facts()`：它把当前主体 Face 区域、边界 Edge、边界 Vertex、共享边直接相邻 Face、角色分组和暂不传播的二/三级关系整理成同一份事实证据。当前 Face、孔、槽等编辑计划也会携带这份事实包；`只改当前 Face` 这类局部重建计划会在执行前先检查一级事实图是否 ready，若无法确认当前 Face、边界 Edge/Vertex 和共享边相邻 Face，会直接 blocked 并说明原因。Face 编辑成功后还会重建目标 Face 的一级事实图做结果校验，若目标值虽然达到但一级事实图不再成立，会自动回滚。后续孔、槽、凸台、圆角等候选识别应优先使用这份事实包，再叠加各自的语义判断和置信度。
- Edge 阶段新增统一的一级拓扑事实包 `edge_first_level_topology()` / `edge_first_level_facts()`：它把当前 Edge、端点 Vertex、共享端点的相邻 Edge、直接包含该 Edge 的相邻 Face、角色分组和暂不传播的二/三级关系整理成同一份事实证据。当前 Edge 长度、起点/中心/终点坐标、圆角、倒角、圆边轴心和椭圆半径等编辑计划会携带这份事实包，后续 Edge 一级策略应优先用它判断“只改当前边、移动端面、相邻圆柱或缩放所属对象”的执行影响。
- 支持显示选中对象信息，并提供 `属性表` / `原始文本` 两种查看方式：
  - 零件名称
  - Solid 数量
  - Face 数量
  - Edge 数量
  - 面类型
  - 面面积
  - 平面法向
  - 圆柱面半径/直径
  - 边类型
  - 边长度
  - 圆边半径/直径
- 属性面板现在还会显示更多几何调试信息：
  - 零件 / Solid 的包围盒、尺寸、体积、重心、表面积。
  - Face 的方向、面积中心、UV 参数范围、边界边数量、包围盒。
  - 平面Face的几何法向和按拓扑方向修正后的法向。
  - 平面Face的拉伸/切除向外方向、向内方向和方向判断置信度。
  - 圆柱Face的轴线点、轴方向、半径、直径、角度跨度、估算高度和是否接近完整圆柱。
  - Edge 的参数范围、起点、终点、长度中心、包围盒。
  - 直线Edge的方向，圆弧Edge的圆心、轴线、半径和直径。
- 属性面板支持复制当前对象 ID、拾取坐标和完整信息。
- 面/边属性查询带缓存；重复选择同一个对象会复用上次计算结果，模型编辑、撤销、重做或重新加载后缓存会自动清空。
- 支持高亮选中的零件、Solid、Face、Edge或特征候选，并在鼠标悬停时用红色预览当前可选对象；普通 Face / 特征点选现在优先使用轻量信息，避免一次点击就扫描同域面、端盖和底面，当前选中对象表会先显示可安全快速得到的参数，点击具体修改或手动扫描时再生成完整编辑计划。
- 模型边线默认渲染会隐藏同一平面或同一圆柱面内部的拓扑分割边，也会隐藏同域区域里几何位置重复的拼接边，减少布尔拉伸/切除后新旧侧壁交界处看起来像“两块拼起来”的视觉伤疤；`显示` 面板里的 `显示同域内部边` 可以临时打开完整拓扑边线。如果按 ID 或 Edge 模式专门选中这类内部Edge，仍然可以单独高亮查看。
- 支持只显示当前选中对象、对准当前选中对象，并可一键恢复显示完整模型。
- 支持两点测量：
  - 可以把当前选中对象的拾取点设为 A 或 B；如果没有拾取点，会退回使用对象中心、面积中心、长度中心、重心或包围盒中心。
  - 设置 A/B 后会显示两点距离和 X/Y/Z 方向差值。
  - 3D 视图中会显示一条青色测量线；测量结果可以复制，加载新模型时会自动清除旧测量。
- 特征模式会先显示特征来源Face、基础几何参数和当前可用的快速编辑入口；侧壁Face、同域圆柱范围、端面Face、疑似底面 Face、开口端相邻Face和边界Edge等深层信息会在扫描候选、执行编辑计划或历史定位时再计算。
- 支持导出当前完整模型为 STEP。
- 支持导出选中的零件为 STEP。
- 支持导出选中的Solid为 STEP。
- 支持导出选中的Face为 STEP；如果当前编辑计划、扫描候选或历史定位已经解析出明确特征区域，也可以导出这片相关区域。
- 支持导出选中特征区域为 STEP。
- 支持导出选中的Edge为 STEP。
- 支持导出质量检查：导出前会检查 B-Rep 有效性、Solid / Face / Edge 数量、体积和包围盒；如果发现风险，会先弹窗确认。
- 支持一键修复当前模型或选中零件/Solid：执行 ShapeFix 和同域面/边合并，修复会进入后台编辑流程，并支持撤销/重做。
- 导出完整模型、零件或 Solid 前，会先尝试执行 ShapeFix 和同域面/边合并，减少外部 CAD 打开时出现碎面、坏体或明显拼接痕迹的概率。
- 编辑按钮会根据当前选中对象自动启用或禁用，并通过悬停提示说明为什么当前操作不可用，减少 Face、Edge、孔、凸台、盲孔等对象混用导致的误操作。
- 支持扫描可编辑对象：
  - 默认扫描优先保证界面响应速度，会列出一组有代表性的候选。
  - `深度扫描` 会尝试列出更多候选，适合默认列表里没有找到目标对象时使用。
  - 可拉伸/切除的平面Face。
  - 可调整孔径的圆柱Face候选。
  - 可调整槽/半孔宽度、深度、圆弧长度和轴心坐标的局部圆柱孔/槽候选。
  - 可调整盲孔/盲槽深度的圆柱Face候选。
  - 可调整圆柱凸台直径和高度的凸台候选。
  - 可添加新圆角的直线Edge候选。
  - 可添加倒角的直线Edge候选。
  - 可尝试直接调整长度的直线Edge候选，简单平面多面体会优先局部边形变。
  - 可调整圆Edge半径/直径的圆形或圆弧Edge候选。
  - 表格会显示当前值、状态、风险、置信度和说明。
  - 盲孔/盲槽深度候选会在列表阶段先确认疑似底面，列表里的深度值优先使用底面 Face轴向位置计算。
  - 点击表格行会直接选中对应Face或Edge，方便继续执行拉伸/切除、孔径调整、槽/半孔宽度/深度/圆弧长度调整、凸台高度调整、盲孔/盲槽深度调整、Edge倒圆、Edge倒角或修改Edge长度。
- 支持列出圆柱面候选特征。
- 圆柱面候选会显示在表格中，点击候选行可以直接选中并高亮对应 Face。
- 圆柱面候选可以按类型筛选：全部、孔/槽候选、圆角候选、凸柱/外圆候选、未明确分类。
- 圆柱面候选的类型下拉框关闭时会把鼠标滚轮交还给左侧滚动面板，避免滚动面板时误改筛选条件。
- 圆柱面候选表格会显示初步分类：
  - `hole/groove candidate`：孔/槽一类的凹向圆柱面候选。
  - `round/fillet candidate`：小半径局部圆柱面，可能是圆角/倒圆。
  - `boss/outer-round candidate`：凸柱/外圆角一类的外向圆柱面候选。
  - `cylindrical face`：暂时无法明确分类的圆柱面。
- 圆柱面候选表格会显示直径、角度跨度、估算高度和置信度。
- 圆柱面候选表格会显示 `risk`，用于提示调整圆柱孔径的风险。
- 圆柱面候选表默认列出前 60 个候选，以避免打开大模型时刷新过慢。
- 当前版本支持平面Face拉伸/切除。
- 平面拉伸/切除会自动判断面两侧的 inside / outside，输入正数表示向外加料，输入负数表示向内切削。
- 拉伸/切除平面会先显示半透明预览体，表示拉伸/切除方向和大致范围，然后在后台执行真实 OCCT 布尔计算。
- 拉伸/切除平面现在会从选中Face出发，自动查找共面且相接/重叠的相邻Face，并把它们作为同一片平面区域一起拉伸/切除。
- 这可以减少 STEP 碎面导致的“只推了一小块，导出后像贴上去一块，中间有伤疤”的情况。
- 如果选中的平面被识别为完整圆柱端盖，并且是向外拉长，程序会优先使用“完整旧段 + 新段圆柱”的专用 Fuse 路线，而不是只把一个短圆柱 prism 拼到端面上。简单圆柱场景下，这会让拉长结果保持为一个连续圆柱侧面，减少新旧圆柱段拼接痕迹。
- 拉伸/切除加料时，工具体会向原实体内部保留一个很小的重叠量，再执行 Fuse，避免只靠两个面贴合导致导出后像“原模型 + 新增块”叠在一起。
- Fuse/Cut 完成后会执行更强的拉伸/切除结果清理：按模型尺寸设置小容差，显式禁止保留 internal edges，并多轮执行 OCCT 同域面/边合并，减少第三方 CAD 中出现不必要共面分割线的概率。
- 布尔计算前会启用 OCCT glue/fuzzy 选项，布尔后会调用 `SimplifyResult` 和同域合并；但某些 CAD/OCCT 场景仍可能保留拓扑分割边。当前程序会先在选择层把同域平面/圆柱区域作为整体高亮，并在默认边线渲染中隐藏同域内部拓扑边和几何重复拼接边；真正从 STEP/B-Rep 拓扑里消除这类分割边，还需要后续做更专门的局部圆柱/侧壁重建。
- 如果拉伸/切除本身产生了真实台阶边界，第三方 CAD 仍会显示这条几何边；清理只能减少不必要的共面残留边，不能消除真实形状边界。
- 拉伸/切除平面会先生成操作计划：检查距离是否为 0、方向置信度和相对Face尺寸的风险；能拉伸/切除时直接执行，不能拉伸/切除时会提示阻止原因。
- 调整圆柱孔径也会先显示半透明预览体：红色表示切削 cutter，绿色表示缩小孔径时的补料范围；如果圆柱侧壁被拆成多段同域Face，工具范围会优先覆盖整段同域圆柱。
- 当前版本支持盲孔/盲槽深度调整：
  - 只对 `hole/groove candidate` 且端部类型为 `blind`、并识别到疑似底面 Face 的圆柱面候选开放。
  - 目标深度大于当前估算深度时，会沿开口到疑似底面方向用有限长度 cutter 加深切削。
  - 目标深度小于当前估算深度时，会从目标新底面到旧底面方向补料，让孔变浅。
  - 调整盲孔深度会先显示半透明预览体：红色表示加深切削范围，绿色表示变浅补料范围。
  - 孔深调整计划会记录当前深度、目标深度、变化比例、疑似底面、开口端和工具参数。
  - 当前深度会优先使用疑似底面 Face在圆柱轴线上的位置计算；如果相邻端面找不到底面，会额外扫描同一Solid内轴线附近的平面圆盘候选。
- 当前版本支持槽/半孔候选结构化识别：
  - 对局部圆柱形 `hole/groove candidate`，会标记为 `partial-cylindrical-groove`。
  - 会估算槽宽、圆弧长度和槽深。
  - 会识别槽圆柱Face和槽边界相邻Face，并在特征模式下一起高亮。
  - 这些仍是 B-Rep 几何估算，不是 CAD 历史里的槽特征参数。
- 当前版本支持槽/半孔宽度调整：
  - 只对已识别为 `partial-cylindrical-groove` 的部分圆柱孔/槽候选开放。
  - 输入目标槽宽后，会按当前圆弧角度把槽宽换算为目标圆柱直径，再复用圆柱孔/槽重建路线执行。
  - 这不是完整 CAD 槽参数编辑；复杂槽、非圆柱槽或圆弧角度不稳定时仍可能失败并回滚。
- 当前版本支持槽/半孔深度调整：
  - 只对已识别为 `partial-cylindrical-groove` 的部分圆柱孔/槽候选开放。
  - 输入目标槽深后，会按当前圆弧角度把槽深换算为目标圆柱直径，再复用圆柱孔/槽重建路线执行。
  - 这仍是 B-Rep 几何近似，不是完整 CAD 槽深参数编辑。
- 当前版本支持槽/半孔圆弧长度调整：
  - 只对已识别为 `partial-cylindrical-groove` 的部分圆柱孔/槽候选开放。
  - 输入目标圆弧长度后，会按当前圆弧角度把圆弧长度换算为目标圆柱直径，再复用圆柱孔/槽重建路线执行。
  - 这仍是 B-Rep 几何近似，不是完整 CAD 槽参数编辑。
- 当前版本支持槽/半孔圆弧角度和开口角度调整：
  - 只对已识别为 `partial-cylindrical-groove` 的部分圆柱孔/槽候选开放。
  - 输入目标圆弧角度时，程序会保持当前圆柱半径，先补旧扇形槽，再按目标角度重切局部扇形槽。
  - 输入目标开口角度时，会先换算为 `2π - 开口角` 的圆弧角度后执行。
  - 如果检测到成对长圆槽端，当前角度修改仍只重建所选局部扇形槽。
- 当前版本支持长圆槽/槽孔总长度和中心距调整：
  - 你可以直接在当前选中对象表里修改 `槽孔总长度` 或 `槽孔中心距`，不需要先填写配对端 Face ID。
  - 点击修改时，程序会自动寻找另一个半圆槽端；识别成功后保持槽宽不变，先补旧长圆槽体，再切出目标总长度。
  - 如果自动配对失败，可以在当前选中对象表中填写 `槽孔配对端 Face ID`，后续槽宽、槽深、圆弧长度、总长度和中心距调整会优先尝试使用这个手动配对端。
- 当前版本支持壳体厚度调整：
  - 对已找到投影重叠相对平面的平面候选开放。
  - 输入目标厚度后，程序会把厚度变化换算成当前平面区域的拉伸/切除距离，保留相对平面不动。
  - 会先显示半透明拉伸/切除预览，并记录当前厚度、目标厚度、相对平面Face、重叠率和拉伸/切除距离。
  - 这是局部 B-Rep 平面拉伸/切除近似，不是 CAD 壳命令或完整壳体参数编辑。
  - 当前选中对象表的 `壳体厚度` 会通过 `建模意图` 选择 `拉伸/切除` 或 `缩放特征`；后者会沿厚度方向缩放所属特征或 Solid，让厚度接近目标值，同一对象上的其它厚度方向尺寸也会跟随变化。
  - 对简单全平面薄板/盒体，`缩放特征` 会优先用平面重建路线，避免把原本的平面 Face 变成 B-spline 曲面，并保持原选中 Face 的逻辑 ID 继续指向修改后的面。
  - 对开口薄壁盒、槽腔这类上下文，程序会把 `完整抽壳/开口面编辑` 显示为受限能力；局部壁厚仍可尝试修改，但不会伪装成 CAD 的完整抽壳历史或开口面特征级重建。
- 当前版本支持已有圆角/倒圆候选结构化识别：
  - 对局部小半径圆柱面，会标记为 `round/fillet candidate`。
  - 会估算已有圆角半径、圆弧角度和圆弧长度。
  - 会识别已有圆角Face和相邻支撑Face，并在特征模式下一起高亮。
  - `可编辑对象` 会把已有圆角候选单独列为 `修改已有圆角半径/弧长` 或 `修改已有圆角链半径/弧长`，点击后会选中该圆角 Face，并把圆角半径/圆角弧长输入框预填为当前估算值的参考目标值。
  - 选中已有圆角候选时，不会再误把它填入 `孔直径`，避免把圆角当孔径修改。
  - 当前版本的已有圆角半径修改会先尝试移除圆角Face或简单等半径圆角链，再在恢复出的锐边上重新倒圆；也可以在当前选中对象表中输入已有圆角圆弧长度，程序会按当前圆弧角度换算成目标半径。只对较规整的圆柱圆角候选和 2 到 4 个共享边连通面的简单等半径链开放，复杂 blend 或更长圆角链会提前阻止或回滚。
  - 当前选中对象表的 `圆角半径` / `圆角弧长` 会通过 `建模意图` 选择 `重建圆角` 或 `缩放特征`。后者不会移除并重建圆角，而是按目标半径或弧长比例整体缩放所属特征或 Solid，同一对象上的其它尺寸也会变化。
- 当前版本支持圆柱孔封堵：
  - 只对 `hole/groove candidate` 且角度跨度接近完整圆柱的孔开放。
  - 不对半孔/槽开放，避免用完整圆柱补料时把不该补的位置也补上。
  - 封堵会用略带半径重叠的圆柱补料体执行 Fuse。
  - 绿色半透明预览表示即将补上的材料范围。
  - 当前常用测试模型可能不会在默认可编辑对象列表里显示封堵候选；其他包含完整圆柱孔的 STEP 文件可以使用这个能力。
- 当前版本支持圆柱凸台直径调整：
  - 只对 `boss/outer-round candidate` 且角度跨度接近完整圆柱的凸台开放。
  - 不处理局部外圆角、圆角面或未明确圆柱面，避免把圆角当凸台修改。
  - 目标直径变大时，会在同域圆柱侧壁范围内生成目标直径圆柱并 Fuse。
  - 目标直径变小时，会先用旧外形包络体移除原凸台范围，再 Fuse 目标直径圆柱重建，避免环形 cutter 在部分场景下把实体切空。
  - 当前选中对象表的 `直径` / `半径` 会通过 `建模意图` 选择 `只改凸台` 或 `缩放特征`；后者用于按目标尺寸比例均匀缩放所属特征或 Solid，不是凸台包络重建，会连带影响其它尺寸。
  - 会先显示半透明预览：绿色表示扩大/重建补料范围，红色表示缩小移除范围。
  - 当前常用测试模型可能没有明确凸台候选；包含完整圆柱凸台的 STEP 文件可以使用这个能力。
- 当前版本支持圆柱凸台高度和轴心坐标调整：
  - 只对已识别为完整圆柱凸台、并找到可拉伸/切除端盖 Face 的候选开放。
  - 输入目标高度后，程序会选择凸台端盖并把高度变化换算成端盖拉伸/切除距离。
  - 输入目标轴心坐标后，程序会先移除旧凸台包络，再按同直径在目标轴心补出凸台。
  - 这不是 CAD 历史里的拉伸特征高度参数；端盖识别不稳定或拉伸/切除计划被阻止时会拒绝执行。
- 当前版本支持直线Edge添加圆角：
  - 只对直线Edge开放。
  - 会先检查边长、相邻Face数量和目标半径相对边长的比例。
  - 蓝色半透明预览表示目标Edge和输入半径的大致范围。
  - 真实编辑使用 OCCT `BRepFilletAPI_MakeFillet` 在后台执行。
  - 这一步是“给直线边添加新圆角”，还不是“修改已有圆角半径”。
  - STEP 没有建模历史，某些看起来像直线边的对象仍可能被 OCCT 拒绝；失败时会自动尝试恢复编辑前状态。
- 当前版本支持直线Edge添加倒角：
  - 只对直线Edge开放。
  - 会先检查边长、相邻Face数量和倒角距离相对边长的比例。
  - 当前选中对象表支持 `新增倒角距离` 的对称距离倒角、`新增不等距倒角D1/D2` 的两侧不同距离倒角，以及 `新增距离+角度倒角D/角度`。
  - 橙色半透明预览表示目标Edge和输入倒角距离的大致范围。
  - 真实编辑使用 OCCT `BRepFilletAPI_MakeChamfer` 在后台执行。
  - STEP 没有建模历史，某些边仍可能被 OCCT 拒绝；失败时会自动尝试恢复编辑前状态。
- 当前版本支持修改Edge长度：
  - 选中Edge后，`长度` 会自动填入当前Edge长度。
  - 对圆形/圆弧Edge，当前选中对象表会额外提供圆边半径和圆边直径可编辑行，内部会换算为等比例Edge长度，并通过 `建模意图` 选择自动、相邻圆柱或缩放所属。
  - `长度基准` 行可以选择自动、中心、固定起点、固定终点。
  - `长度` 行的 `建模意图` 可以选择 `自动`、`只改当前Edge`、`移动端面`、`相邻圆柱`、`缩放所属`。
  - `只改当前Edge` 会强制使用局部边形变；如果当前Edge不满足简单全平面多面体条件，会直接阻止，不会偷偷改成整体缩放。
  - `移动端面` 会强制找端点附近、方向匹配的平面端面并做端面拉伸/切除；对正方体这类模型，会得到更像“变成长方体”的结果。计划阶段会确认直接相邻面和移动端面能形成可验证的垂直关系；如果找不到端面拉伸/切除路径或关系不可验证，会直接阻止。
  - `缩放所属` 会强制对所属特征或 Solid 做轴向/整体缩放，是高风险兜底语义，会影响其它尺寸。
  - 对直线Edge，当前选中对象表会额外提供 `起点`、`中心` 和 `终点`，可以直接输入目标 X/Y/Z 坐标来移动单个端点或整条边。
  - 对正方体这类全平面多面体，直线Edge会优先走“局部边形变”：只移动被选Edge的一个端点或两个端点，并重建周边平面。
  - 局部边形变不会把整个端面拉走，因此正方体不会默认变成长方体；相邻面会按被移动的边自然变形，四点非平面面会优先重建成连续曲面，避免从面中间出现对角折线。
  - 直线Edge端点/中心坐标修改复用同一套局部边形变；当前只对简单全平面多面体开放，复杂曲面、带内孔Face或大型复杂Solid会阻止执行。
  - `自动` 默认固定起点、移动终点；`固定起点` / `固定终点` 会明确控制哪一端不动；`中心` 会让两端各移动一半。
  - 如果模型不是简单全平面多面体，直线Edge会继续尝试寻找端点附近、方向匹配的平面端面，并把“改边长”转换成该端面的平面拉伸/切除操作。
  - 圆形/圆弧Edge会优先检查相邻圆柱面；如果能复用孔/槽或凸台直径编辑，就把Edge长度按比例换算成目标圆柱直径再执行局部编辑。
  - 圆边没有可复用圆柱面时，会优先围绕圆边轴线做径向缩放，尽量只改半径方向并保留轴向尺寸；这类一般仿射可能把解析圆/圆锥/圆柱几何转换为 B-spline。
  - 椭圆 Edge 的 `椭圆主半径` / `椭圆小半径` 是单独的属性行：主半径会沿椭圆主轴方向单轴缩放，小半径会沿小轴方向单轴缩放；另一个半径方向尽量不动。
  - 椭圆 Edge 不再把通用 `长度` 作为默认可改入口；界面只开放语义更清楚的主半径/小半径。B-spline / Bezier 等复杂曲线 Edge 暂不在参数表里显示可改长度，避免把实验性 fallback 误当成稳定 CAD 参数。
  - 几何缩放 fallback 会先只预变换目标Edge来估算结果长度，并在必要时微调缩放比例，让实际边长更接近输入值；这条路径保留作内部回归和后备，不作为复杂曲线Edge的稳定界面入口。
  - `中心`、没有明确端面、或非圆边没有更明确局部路径时，后端仍可能进入整体/轴向几何缩放 fallback，但当前参数表会优先隐藏未稳定的复杂曲线长度入口。
  - 该 fallback 会影响所属零件/Solid的其它尺寸，因此必须按高风险处理，并依赖失败回滚/撤销兜底。
  - 这仍不是通用参数化边长编辑；复杂拓扑、斜面过渡、圆角链或布尔失败场景仍可能不能稳定修改。
- 支持零件 / Solid 级平移：
  - 输入 X/Y/Z 平移量后，可以平移当前选中零件。
  - 选中Solid、或选中属于某个Solid的Face/Edge后，可以平移当前Solid。
  - 单Solid零件中平移Solid实际等同于移动整个零件 shape，程序会按中风险提示。
  - 平移操作会写入历史记录，并支持撤销/重做。
- 支持零件 / Solid 级旋转：
  - 选择 X/Y/Z 旋转轴并输入角度后，可以旋转当前选中零件或Solid。
  - 当前版本的旋转中心取目标对象的包围盒中心。
  - 单Solid零件中旋转Solid实际等同于旋转整个零件 shape，程序会按中风险提示。
  - 旋转操作会写入历史记录，并支持撤销/重做。
- 后台编辑计算时不再弹出模态进度框，也不再把主界面整体置灰；UI 线程只负责渲染和响应基础视图交互，真实 B-Rep 编辑在后台线程执行。
- 编辑计算期间，半透明预览会继续在 3D 视图里渲染，用户可以旋转或缩放查看；会改变模型状态的操作仍会暂时禁用，避免同一模型被多个后台编辑同时修改。
- 首次加载默认使用中等清晰度显示网格，避免长期停留在粗网格预览；B-Rep 编辑和结果校验仍使用真实拓扑，显示网格只负责渲染和拾取。
- 旋转/平移/缩放相机时保持边线和静态画质一致；渲染优先使用较轻的 FXAA 抗锯齿，环境不支持时回退到 2x MSAA，减少复杂 STEP 查看时的帧率抖动。
- 鼠标悬停高亮做了节流和移动阈值；大模型会直接关闭悬停拾取高亮，避免鼠标路过复杂面片时触发 VTK CellPicker 卡顿。
- 后台编辑成功后会尽量在后台一并生成刷新用的模型/边线显示数据，减少编辑完成瞬间的主线程冻结。
- 可编辑对象和圆柱面候选扫描已经在 `StepModel` 层做参数化缓存；同一模型、同一扫描范围重复打开候选列表时会直接复用结果，编辑、撤销/重做或重新加载模型后缓存会随拓扑刷新清空。
- 真实 B-Rep 结果会在布尔计算完成后一次性刷新；半透明预览不等于最终几何结果。
- 如果后台编辑失败，程序会自动尝试恢复到编辑前快照，避免出现“提示失败但模型已经被部分改动”的状态。
- 当前版本支持圆柱孔/圆柱面扩大切削。
- 当前版本支持圆柱孔/圆柱面缩小孔径：先补料，再用目标直径重切。
- 当前版本支持完整圆柱孔轴心坐标修改：在当前选中对象表里修改 `轴心`，并把 `建模意图` 设为 `移动孔` 时，程序会先补旧孔，再按同直径在目标轴心位置重切新孔；半孔/开放槽会走 `移动槽/半孔` 语义，避免整圆柱工具误补材料。把 `建模意图` 设为 `移动特征` 时，会平移所属特征或 Solid。
- 当前版本支持孔/槽 `直径` / `半径` 的 `缩放特征` 建模意图：
  - 这条路线不会重切孔壁，而是按目标直径或半径与当前值的比例均匀缩放所属特征或 Solid。
  - 高度、厚度和同一对象上的其它尺寸会同比例变化。
  - 如果你只想让孔径变大/变小，优先在 `直径` 或 `半径` 行把 `建模意图` 设为 `只改孔/槽壁`；如果你的建模意图是让所属圆柱区域整体缩放，再设为 `缩放特征`。
- 圆柱孔/圆柱面孔径调整现在会先生成切削计划：
  - 目标直径必须大于 0；如果目标直径与当前直径几乎相同，会直接阻止。
  - 会计算直径变化比例；变化超过当前直径 35% 会提高到中风险，超过 100% 会提高到高风险。
  - 会比较目标直径和圆柱面估算高度；比例异常时会提高风险等级。
  - 候选不是 `hole/groove candidate` 时会标为高风险并要求确认。
  - 圆角/倒圆候选会标为高风险，避免误切圆角。
  - 缩小孔径当前版本只对 `hole/groove candidate` 开放，其他圆柱面会直接阻止。
  - 选中Face或实际切削计划会使用多点材料采样，比候选表里的快速分类更谨慎。
  - 实际切削优先使用有限长度 cutter，按选中圆柱面的 V 参数范围加少量余量生成，不再默认贯穿整个零件。
  - 会沿圆柱轴线采样两端材料状态，初步区分通孔/开口端、盲孔和封闭端。
  - 会把圆柱相邻平面按轴线位置分成起点端/终点端，并结合端部采样标记疑似盲孔底面；相邻端面缺失时，会尝试扫描轴线附近的平面圆盘候选作为兜底。
  - 孔径修改计划会记录疑似底面 Face、开口端相邻Face和 cutter 底面保护状态。
  - 对盲孔/封闭端，有限长度 cutter 会使用更小的端部余量，降低切深变长的风险。
- 支持撤销/重做编辑。
- 撤销/重做会先确认模型恢复成功，再移动历史栈；如果恢复失败，会尽量回到操作前状态。
- 支持操作历史面板，显示当前已经成功执行的编辑。
- 操作历史详情会显示编辑类型、目标对象、参数、执行结果和拓扑数量变化。
- 操作历史详情会额外显示目标零件自身的 Solid / Face / Edge 数量变化。
- 如果一次局部编辑导致目标零件 Solid 数异常变化，历史详情会显示质量警告，状态栏也会提示先检查结果。
- 操作历史详情会显示编辑前后的几何差异摘要：
  - 体积变化。
  - 表面积变化。
  - 包围盒尺寸变化。
  - 包围盒对角线变化。
- 点击操作历史记录时，会显示三维差异叠加预览：
  - 红色半透明表示编辑前模型。
  - 绿色半透明表示编辑后模型。
  - 编辑后模型上会覆盖距离热力图，蓝色接近无变化，黄色/红色表示变化更大。
  - 右下角会显示 `distance` 色带。
  - 可以点击 `清除差异预览` 关闭叠加显示。
- 支持导出选中操作历史的差异报告，报告会包含操作参数、拓扑变化、几何变化和热力图统计。
- 鼠标拾取模型时会显示三维拾取点坐标。
- 编辑历史会记录目标对象和当时的拾取点。
- 支持把本软件加载后的编辑历史导出为 JSON v2；除摘要和详情外，也会保存 `operation_name`、`target`、`parameters` 和 `result_message`，为后续安全复放做准备。
- 点击操作历史记录时，程序会尝试重新高亮目标对象，并在详情里保留当时的拾取点坐标；3D 视图里不会再额外显示拾取点小球。
- 对非 `hole/groove candidate` 的圆柱切削会先弹出确认，避免误切外圆角或凸柱。
- 提供 `--smoke-test` 启动检查，用于验证 Qt + VTK 窗口组件能正常初始化。

当前 `assets/models/geom_extract.step` 的读取结果是：

```text
part: 2001-LOWER_HOUSING
parts: 1
solids: 1
faces: 1800
edges: 4982
vertices: 3262
```

所以当前测试文件大概率是单个零件，不是多零件装配。Face、Edge、圆柱面、孔、槽和圆角等，是这个零件里的几何特征；代码也按“将来可能有多个零件/装配”的方式组织。

## 还没有实现什么

这里分成两类看，不然容易误解为“完全没有推进”。

已经有当前版本的初步实现，但还需要继续稳定和完善：

- 复杂特征识别：已经有平面、圆柱、边、孔/槽候选、槽/半孔候选、已有圆角候选、圆柱凸台候选等基础候选列表，但还不是完整 CAD 语义级识别。
- 盲孔/盲槽深度：已经能对部分可识别候选做深度估算和编辑，并会优先使用疑似底面 Face的轴向位置计算当前深度；但还不能保证所有模型都能恢复真实 CAD 语义深度。
- 槽、凸台、壳体局部区域：已经有圆柱孔、槽/半孔候选结构化识别、槽/半孔宽度/深度/圆弧长度/圆弧角度/开口角度调整、槽宽/槽深/弧长的整体缩放所属对象语义、长圆槽总长度/中心距执行时自动配对和手动配对端 Face ID、完整圆柱凸台直径/半径/高度/轴心坐标修改、规则矩形凸台/口袋长度/宽度/中心/高度/深度局部重建、多台阶矩形凸台顶层规则台阶独立编辑、多台阶中间过渡面识别和快速阻止、普通完整圆柱高度兜底拉伸/切除或通过 `建模意图` 做轴向整体缩放，以及平面壳体相对面厚度估算、局部厚度拉伸/切除和通过 `建模意图` 做厚度方向整体缩放；复杂槽、复杂凸台整体联动和完整壳体区域仍需要继续做。
- 已有圆角/倒圆面半径/弧长：已经有当前版本的受限修改实现，使用 defeature + refillet 路线；2 到 4 个共享边连通面的简单等半径圆角链会作为高风险候选开放整链半径/弧长修改，变半径圆角链和更长复杂链会在识别层标成受限能力并在计划阶段说明暂未实现稳定重建；复杂 blend、支撑面不明确或恢复锐边失败时仍会阻止或回滚。
- 局部偏差分析：已经有编辑前后体积、面积、包围盒、距离热力图和差异报告，但还不是工程公差级的局部区域偏差报告。
- 错误恢复和模型修复：已经有编辑前快照、失败回滚、基础 B-Rep 校验、同域面合并、布尔结果自动修复，以及一键修复当前模型或选中零件/solid，但还不是完整的模型修复流水线。
- 多零件装配：已经有装配/零件树和单独导出入口，但还没有做大规模、多来源 STEP 装配测试。

仍基本没有实现，或者 STEP 本身不一定能可靠支持：

- 参数化建模历史恢复。STEP 通常只保存结果几何/拓扑，不能稳定还原原 CAD 软件里的建模历史；当前只能在本程序里记录并导出后续编辑历史，或做近似的特征语义识别。
- 所有场景都稳定的复杂特征识别。

## 下一步要实现什么

当前已经有按阶段跑通的本地一级编辑基线，但这还不等于 CAD 级完成。后续按上面的 `SCDM-first 主路线` 继续推进：`[x]` 项保持回归和真实 STEP 验证，`[~]` 项优先补 SCDM API 细节、守门、失败解释和更多真实模型样例，`[ ]` 项不能提前在 UI 里伪装成稳定能力。新增能力优先看 SCDM 能否返回结构化对象、当前值、可用命令和可校验结果；本地 OCCT 只作为兜底和已验证快路径保留。

当前整体验证基线：

- 2026-08-06，在 `pyocc` 环境下已通过 `python scripts\verify_first_level_edit_suites.py --stage face`，覆盖 Face 专项套件和 Face isolated worker。
- 2026-08-11，在 `pyocc` 环境下已通过 `python scripts\verify_first_level_edit_suites.py --stage face`，覆盖 R1 Face 专项套件、Face isolated worker、保持关系隔离契约和 Face 阶段收口口径。
- 2026-08-06，在 `pyocc` 环境下已通过 `python scripts\verify_first_level_edit_suites.py --stage hole-slot`，覆盖孔/槽一级拓扑、局部重建和 isolated worker。
- 2026-08-11，在 `pyocc` 环境下已通过 `python scripts\verify_first_level_edit_suites.py --stage hole-slot`，覆盖 R2/R3 孔槽专项套件、隔离执行、逻辑 Face ID 保持和孔槽阶段收口口径。
- 2026-08-06，在 `pyocc` 环境下已通过 `python scripts\verify_first_level_edit_suites.py --stage edge`，覆盖 Edge 一级拓扑、长度建模意图、坐标修改、圆角/倒角、椭圆 Edge 和 isolated worker。
- 2026-08-06，在 `pyocc` 环境下已通过 `python scripts\verify_first_level_edit_suites.py --stage boss --stage round-chamfer --stage shell --stage analytic`，覆盖凸台、圆角/倒角、壳体厚度和解析曲面。
- 2026-08-06，在 `pyocc` 环境下已通过 `python scripts\verify_first_level_edit_suites.py --quick`，覆盖 smoke test、属性表规格、参数表 UI、特征识别优先级、一级事实图、关联探测、显示网格预算和一级验收文档一致性。
- 2026-08-18，新增 `python scripts\verify_scdm_backend.py`、`python scripts\verify_scdm_status.py`、`python scripts\verify_scdm_probe_pipeline.py`、`python scripts\verify_scdm_edit_runner.py` 和 `python scripts\verify_scdm_result_validator.py`，覆盖 SCDM 后端发现、缓存、禁用开关、/RunScript 命令生成、左侧状态摘要、probe job/script 生成、raw->cache 映射、edit job/script/result/error 执行协议，以及结果文件检查、目标值回测、ID 映射和关系式重写；已接入 `--quick`。
- 2026-08-18，本机 `D:\softwaresInstallDir\ANSYS Inc\v222\SCDM\SpaceClaim.exe` 已通过真实 `/RunScript` smoke；对 `assets/models/ICEPAK-NATURAL.stp` 的真实 probe 可打开模型并输出 13 个 Body、158 个 Face、396 条 Edge，396 条 Edge 均可回传长度、起终点和相邻 Face 数，其中 160 条圆弧/圆边可回传半径和圆心。当前 `StandardHoles.GetHoleFaces` 对该 STEP 返回 0 个标准孔面，因此已改为按同中心/同轴/同半径聚合圆柱碎片；真实 SCDM 已验证 face.offset、孔径和孔位置，输出 STEP 均可被 SCDM probe 回读。

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

- 已验收：平面 Face 的 `偏移`，稳定矩形/简单全平面 Face 的 `面内长度`、`面内宽度`，以及壳体厚度、圆柱端盖/圆柱侧面高度这类挂在 Face 入口上的高频编辑；支持 `局部重建`、`拉伸/切除`、`移动特征`、`缩放特征` 和受限的 `保持关系`。`中心` 移动后端保留，但特征参数表暂不开放。
- 已验收：Face 的 `一级关系` 定义为选中 Face 本身、必要的同域/共面碎片 Face、这些 Face 的边界 Edge/Vertex，以及与该区域共享边的直接相邻 Face。只共享顶点的对象、相邻 Face 再连出去的 Face 都不作为 R1 自动传播范围。
- 已验收：选中平面 Face 时，程序会生成 `一级关系` 事实包，记录当前 Face 区域、同域/共面碎片、一级平行/垂直关系、一级同轴圆柱事实、边界 Edge/Vertex、共享边相邻 Face，并明确二级、三级关系暂不自动传播；这些事实用于计划、校验和诊断，不再作为特征参数行显示。
- 可用但受限：带内孔平面、曲面 Solid 上的平面、自由曲面、非矩形面、复杂端盖、接近切穿的内切等场景会按明确守门执行；能稳定改就走隔离/回滚，不能稳定改就提前 blocked 并说明原因。
- 未实现/不承诺：原 CAD 历史恢复、任意复杂 Face 的通用局部重建、手写孔底/槽底/台阶等二级/三级传播、跨特征约束求解和特征组联动；这些不再作为 SCDM-first 近期主线，不算 Face 兜底基线未完成项。
- `python scripts\verify_first_level_edit_suites.py --stage face` 必须通过，集中运行 R1 Face 专项套件和 Face isolated worker。
- `python scripts\verify_face_edit_suite.py` 必须通过，集中覆盖面内长度/面内宽度、中心、偏移、保持关系、壳体厚度、拉伸/切除、局部变形禁用、目标值保护、属性回读、逻辑 Face ID 保持，以及 UI 里标题/复制 ID/按 ID 选择是否优先使用逻辑 Face ID。
- `python scripts\verify_property_editor_specs.py` 必须通过，确保平面 Face 的特征参数表使用 `面内长度`、`面内宽度`、`偏移` 这些用户可理解的名称，暂时隐藏 `中心`，且不把面积暴露成可编辑驱动参数，并递归检查提示文字里不再出现容易误解的旧词。
- `python scripts\verify_face_first_level_topology.py` 必须通过，确保普通正方体 Face 的一级关系能识别 4 条边界 Edge、4 个边界 Vertex、4 个共享边相邻 Face，并证明局部移动后目标 Face 的边界 Vertex 与共享边 Edge 已到新位置、一级侧面跟随重建、二级底面不跟随移动。

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

- 已验收：圆柱孔/盲孔的 `直径`、`半径`、`轴心`、`盲孔深度` 和 `封堵/删除孔`。孔径按同轴重切孔壁执行，轴心移动会先补旧孔再切新孔，盲孔深度会按加深切削或变浅补料处理，结果必须仍能回读目标孔特征。
- 已验收：槽/半孔/长圆槽的 `槽宽`、`槽深`、`圆弧长度`、`圆弧角度`、`开口角度`、`轴心`、`总长度` 和 `中心距`。普通半圆槽按局部圆柱槽重切，长圆槽按两端圆弧配对后重建，修改后必须仍能识别为目标槽或半孔。
- 已验收：孔/槽的 `一级关系` 定义为当前圆柱侧壁或槽端 Face、边界 Edge/Vertex、共享边直接相邻 Face，以及开口面、底面、槽边界面等一跳角色；孔/槽计划会明确二级、三级关系暂不自动传播。
- 已验收：孔/槽局部布尔和重建会走隔离 worker，修改后会校验 B-Rep、单 Solid、目标几何回读和逻辑 Face ID 保持；失败时回滚，不破坏原模型。
- 可用但受限：当前只承诺单个稳定孔、单个盲孔、单个半圆槽和可稳定配对的长圆槽；锥孔/沉孔只处理简单解析或局部重切路径，复杂浅锥、螺纹孔、组合孔、底面识别不可靠的盲孔会提前阻止。
- 可用但受限：复杂槽、交叉槽、多槽端配对不唯一时，只做识别和快速阻止，不在参数表暴露槽宽、槽深、弧长、弧角或轴心这些伪可改入口。
- 未实现/不承诺：孔组、阵列孔、同尺寸孔联动、多槽组联动、螺纹孔语义编辑、任意草图槽、跨复杂面槽、手写孔底/槽底带动台阶的二级/三级传播；这些不再作为 SCDM-first 近期主线，不算孔/槽兜底基线未完成项。
- `python scripts\verify_first_level_edit_suites.py --stage hole-slot` 必须通过，集中运行 R2/R3 孔槽专项套件。
- `python scripts\verify_hole_slot_edit_suite.py` 必须通过，覆盖孔/槽一级圆柱拓扑、通孔/盲孔局部重建、半圆槽/长圆槽局部重建、隔离 worker、逻辑 Face ID 保持、识别摘要、一级事实图和属性表分组。
- `python scripts\verify_cylindrical_first_level_topology.py` 必须通过，确保孔/槽类圆柱特征会暴露侧壁、边界 Edge/Vertex、直接相邻 Face、底面/开口面/槽边界面，并明确二级、三级关系暂不自动传播。
- `python scripts\verify_hole_slot_isolated_edit.py` 必须通过，确保孔径、孔径缩放特征、孔轴心、孔封堵、盲孔深度、槽宽、槽宽缩放特征、槽深、弧长、弧角、槽轴心、长圆槽总长度和中心距都能通过隔离执行通道验证。

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

- R2/R3 孔槽已经拆成独立验收口径；后续只在真实 STEP 失败项上补识别、补守门、补局部重建。孔组、阵列孔、多槽组联动是否开放，改由上面的 SCDM capability 路线判断。
- `python scripts\verify_first_level_edit_suites.py --stage edge` 覆盖 Edge 一级拓扑、长度建模意图、坐标修改、圆角/倒角、椭圆 Edge 和 isolated worker。任意曲线 Edge 通用约束编辑仍未开放。
- `python scripts\verify_first_level_edit_suites.py --stage boss --stage round-chamfer --stage shell --stage analytic` 覆盖凸台、圆角/倒角、壳体厚度和解析曲面当前可用范围。复杂链式特征、通用抽壳历史恢复和跨特征传播仍不承诺。
- 这些阶段后续只作为本地兜底能力维护；新增客户入口优先从 SCDM capability 路线开放。

## 怎么使用

打开程序后，右侧是 3D 模型窗口，左侧是操作面板。

3D 窗口基本操作：

- 鼠标左键拖动：旋转模型。
- 鼠标滚轮：缩放模型。
- 鼠标中键或组合拖动：平移模型，具体取决于 VTK 默认交互方式。
- 只有明确单击模型时才会选择对象；左键拖动旋转后即使释放点落在某个 Face 上，也不会自动改选。

左侧操作面板按功能分区排列，每个模块都有四边同色的独立边框和颜色提示，顺序大致按工作流排列：先打开和选择模型，再做编辑或导出，然后进行显示控制和测量，后面继续放可编辑对象、圆柱面候选、操作历史和对象信息。

左侧 `选择模式` 用来切换鼠标选择模式：

- `Part`：选择整个零件。
- `Solid`：选择实体。
- `Face`：选择面。
- `Edge`：选择边。
- `Feature`：按几何特征候选方式选择。平面会识别为可拉伸/切除平面候选；圆柱面会进一步识别为圆柱孔、槽/半孔、圆角/倒圆、凸台/外圆等候选。
  圆柱面候选会额外显示侧壁 Face、端面 Face、疑似底面 Face、开口端相邻 Face 和边界 Edge。
- 鼠标悬停时，当前模式下将要选中的对象会显示为红色；真正选中后会显示为黄色。
- 如果当前模式是 `Edge`，即使鼠标点到的是面，程序也会从这个面的边界里选取距离鼠标拾取点最近的Edge。
- `选择模式` 下拉框关闭时不会吃掉滚轮，鼠标停在上面滚动会继续滚动左侧面板；点击打开下拉列表后，滚轮才用于滚动选项。

左侧 `模型结构树` 会显示 STEP 里的装配、零件和实体层级；如果某个零件下有实体，会展开显示 `实体 0`、`实体 1` 这样的子节点。点击实体子节点会自动切换到 `Solid` 选择，并高亮对应实体。

普通单零件 STEP 通常会显示成类似：

```text
零件 1：2001-LOWER_HOUSING    零件 | 实体 1 个 | 面 1800 个 | 边 4982 条
  实体 0                     面 1800 个 | 边 4982 条
```

如果 STEP 是多零件装配，树里可能会先出现 `装配` 节点，下面再挂多个 `零件` 节点；装配可以理解为“多个零件组成的一组结构”。

左侧 `按 ID 选择` 可以直接输入编号选择对象：

- 按 ID 选择会复用上方 `选择模式` 的当前类型；先切换模式，再输入 ID，点击 `选择`。
- 输入框右侧会同步显示当前类型，例如 `Face`、`Edge` 或 `Solid`，用于确认这个 ID 会按哪类对象解释。
- `零件` 的 ID 从 1 开始。
- `Solid`、`Face`、`Edge`、`特征` 的 ID 从 0 开始；`特征` 使用来源Face的 ID。
- 这个功能适合配合圆柱面候选表格、操作历史和属性面板使用。

左侧 `显示` 用来临时缩小三维视图范围：

- `只显示选中`：只显示当前选中的零件、Solid、Face、Edge 或特征区域。
- Face 模式下 `只显示选中` 会优先隔离当前命中的 Face，避免普通点选时触发同域面重计算；如果当前选择来自编辑计划、扫描候选或历史定位，并且已经解析出特征区域，则会使用这片已知区域。
- `对准选中`：不改变显示范围，只把相机对准当前选中的零件、Solid、Face、Edge 或特征，适合快速查看小孔、小边和局部特征。
- `显示全部`：恢复显示完整模型。
- `显示同域内部边`：默认关闭，用来隐藏同一平面/同一圆柱面内部的拓扑分割边和几何重复拼接边；打开后可以查看完整 B-Rep 拓扑边线，适合调试布尔拉伸/切除后的分面情况。
- `导出选中面区域` 会导出当前选中 Face；如果当前选择已经带有明确的特征区域或同域区域信息，则导出这片已知区域。
- Solid / Edge 的显示查询已经使用拓扑索引，避免每次隔离或高亮时反复全模型查找。
- 这是视图操作，不会修改 STEP 几何，也不会写入操作历史。

左侧 `测量` 用来做最基础的点到点距离检查：

- 先在模型中点击一个对象或具体位置，然后点击 `设为 A`。
- 再点击另一个对象或位置，然后点击 `设为 B`。
- 如果选择来自鼠标点击，测量会优先使用实际拾取点；如果是从结构树或 ID 选择，程序会使用对象中心、面积中心、长度中心、重心或包围盒中心。
- 设置 A/B 后会显示两点距离和 `ΔX/ΔY/ΔZ`。
- 3D 视图里会显示一条青色测量线，方便确认测量方向。
- `复制测量` 会复制当前测量结果；`清除测量` 会清空 A/B 和测量线。
- 测量不会修改模型，也不会写入操作历史。

左侧 `可编辑对象` 是当前 MVP 的主要入口：

- 点击 `扫描对象` 会列出当前版本能尝试编辑的对象。
- 点击 `深度扫描` 会用更高上限重新扫描，可能需要等待更久。
- 为了避免打开大模型时界面卡住，程序不会在加载 STEP 时自动扫描；需要编辑时再手动点击扫描。
- 当前默认显示一批代表性的可编辑对象，详细几何判断会尽量延后到选中对象或执行编辑前，避免扫描过慢。
- `拉伸/切除平面` 行表示这个Face是平面；当前主要在 `当前选中对象` 的 `偏移` 行里把 `建模意图` 选为 `拉伸/切除` 来执行。
- `调整圆柱孔径` 行表示这个 Face 是圆柱面候选，可以配合 `孔直径` 和 `调整圆柱孔径` 使用。
- `调整槽/半孔宽度` / `调整槽/半孔深度` / `调整槽/半孔圆弧长度` 行表示这个Face是槽/半孔候选，可以在当前选中对象表里修改槽宽、槽深或圆弧长度。
- `调整圆柱凸台直径` / `调整圆柱凸台高度` 行表示这个Face是较明确的完整圆柱凸台候选，可以在当前选中对象表里修改凸台直径、半径、高度或轴心坐标。
- `封堵圆柱孔` 行表示这个Face是接近完整圆柱的孔候选，可以点击后直接使用 `封堵圆柱孔`。
- `调整盲孔/盲槽深度` 行表示这个Face是较明确的盲孔/盲槽候选，可以在当前选中对象表里修改盲孔/盲槽深度。
- `给Edge添加圆角` 行表示这个对象是直线Edge，可以配合 `圆角半径` 和 `给Edge添加圆角` 使用。
- `给Edge添加倒角` 行表示这个对象是直线Edge，可以配合 `倒角距离` 和 `给Edge添加倒角` 使用。
- `修改已有圆角半径/弧长` / `修改已有圆角链半径/弧长` 行表示这个Face是已有圆角/倒圆候选或简单等半径圆角链候选，点击后会切到 `特征` 模式并预填圆角半径/圆角弧长参考值；真正执行需要在特征参数表里改目标值，再点击 `参数化建模`。
- `状态` 为 `ready` 表示比较适合尝试，`caution` 表示可以尝试但风险更高，`blocked` 表示当前参数或对象不适合执行。
- `风险` 越高越应该谨慎，尤其是圆角、凸柱或未明确圆柱面，不要直接当孔修改。
- 点击任意一行会自动选中并高亮对应Face或Edge。

选择对象后：

- 鼠标经过对象时会出现红色预高亮；被选对象会显示为黄色高亮。
- 在 `Face` 模式下，普通点选只做轻量拾取和单个对象高亮，保证旋转、悬停和选中更流畅；同域面、端盖、底面和槽端配对等深层识别会延后到扫描候选、执行编辑计划或历史定位时进行。
- 如果处于 `特征` 模式，普通点选会先高亮命中的基础对象；扫描候选、执行编辑计划或历史定位时，程序会尽量解析并高亮这个特征相关的局部区域，例如圆柱侧壁、相邻端面和槽边界相邻面。
- 对槽/半孔候选，属性表会显示 `槽宽估算`、`槽圆弧长度估算`、`槽深估算` 和 `槽边界相邻 Face`。
- 对圆角/倒圆候选，属性表会显示 `已有圆角半径估算`、`已有圆角圆弧角度`、`已有圆角圆弧长度估算` 和 `已有圆角支撑 Face`。
- 对盲孔/槽候选，属性表中的 `疑似底面 Face` 是根据圆柱端部 inside / outside 采样和相邻平面位置推断的，不等于 CAD 原始建模历史里的孔深参数。
- 下方 `选中对象信息` 会显示属性。
- `属性表` 页签会把属性分成身份、拓扑、测量、位置、方向/轴线、参数、特征判断等分组。
- `原始文本` 页签会显示同一份信息的纯文本版本，也用于显示候选列表、操作历史详情和普通提示。
- `复制 ID` 会复制当前选中对象，例如 `face 2`。
- `复制坐标` 会复制当前拾取点坐标。
- `复制信息` 会复制当前信息面板里的完整文本。
- 用鼠标在模型上选择时，`选中对象信息` 和窗口底部状态栏会显示 `pick_position`，也就是拾取点的三维坐标。
- 如果选中圆柱面，会自动给 `Hole diameter` 填一个略大的建议直径。
- 如果选中直线Edge，会自动给 `圆角半径` 和 `倒角距离` 填一个保守的建议值，并把 `长度` 填成当前Edge长度。

圆柱面候选：

- 点击 `扫描圆柱面` 会刷新候选表格。
- 圆柱面候选也是手动扫描，避免加载模型和普通选择操作被候选识别拖慢。
- 可以通过候选表格上方的类型下拉框筛选候选；筛选只过滤已经扫描出的缓存结果，不会重新做几何识别。
- 类型下拉框关闭时不会吃掉滚轮，鼠标停在上面滚动会继续滚动左侧面板；点击打开下拉列表后，滚轮才用于滚动选项。
- 当前默认显示前 60 个圆柱面候选；如果模型很复杂，扫描仍可能需要等待一会儿，但扫描过程中界面会尽量保持响应。
- 表格里的每一行对应一个圆柱面候选。
- 点击候选行会自动切到 `特征` 模式，并选中对应Face。
- `guess` 列是程序通过几何采样得到的初步判断，不是 STEP 文件里自带的 CAD 历史特征。
- `round/fillet candidate` 是圆角/倒圆候选；部分规整圆柱圆角可以通过 `修改已有圆角半径` 进行当前版本受限修改。
- `diameter` 是圆柱直径。
- `span` 是圆柱面的角度跨度，接近 `6.283` 表示接近完整圆柱，接近 `3.142` 表示半圆柱。
- `height` 是根据圆柱面积估算出来的高度。
- `confidence` 是当前猜测置信度。
- 这些候选可能是孔、柱、圆角或其他圆柱面，目前还不是稳定的“孔识别”。

编辑：

- 编辑按钮会根据当前选择自动启用或禁用。例如未选中平面时不能点击 `拉伸/切除平面`，未选中直线Edge时不能点击 `给Edge添加圆角` / `给Edge添加倒角`，未选中明确孔/凸台/盲孔候选时对应圆柱编辑按钮会禁用。
- `偏移`：
  - 先选择一个平面 Face。
  - 在当前选中对象表里修改 `偏移`，再用 `建模意图` 选择改法。
  - `偏移` 是沿程序判定的材料外侧法向测到的位置，不是面积，不是移动距离，也不是 X/Y/Z 坐标；它不一定等同于 STEP 原始拓扑法向坐标。
  - `拉伸/切除` 会把目标位置换算成这次要移动的距离，然后沿判定的材料外侧法向加料或切削，适合改变厚度、拉出凸起或切入凹槽。
  - `局部重建` 会把当前 Face 移到目标位置，并重建相邻平面；相邻面可能变斜。
  - `移动特征` 会沿当前面垂直方向平移所属特征或 Solid；形状和内部尺寸不变。
  - 如果选中Face周围有共面且相接/重叠的碎面，`拉伸/切除` 会自动把这些Face合成同一片拉伸/切除区域，属性表和历史记录会显示 `拉伸/切除共面区域 Face 数`。
  - 当前拉伸/切除方向判断通过Solid的 inside / outside 采样得到；如果采样不明确，会退回到拓扑方向法向，并在属性里显示低置信度说明。
- `面内长度` / `面内宽度`：
  - 这两个参数只在稳定矩形凸台/口袋或简单全平面实体上显示；普通曲面、复杂平面和带内孔平面不会把它们伪装成可改参数。
  - 在当前选中对象表里修改目标值，再用 `建模意图` 选择改法。
  - `局部重建` 会在当前矩形平面特征内移动边界并重建周边相邻平面；当前只对稳定矩形特征或简单全平面实体开放。
  - `缩放特征` 会缩放所属特征或 Solid；同一对象上的孔、槽、凸台、厚度和其它间距会跟着变化。
  - `面内长度` / `面内宽度` 是矩形平面特征在自身平面内两个稳定方向上的驱动尺寸，不是面积，不是任意曲面的通用尺寸，不是模型整体高度，也不是全局 X/Y/Z 包围盒尺寸。面积会在诊断信息中作为结果值展示。
- `中心`：
  - 后端保留了 Face 中心移动能力和回归基线，但模型工程师认为当前作用不大，特征参数表暂时不开放这一行。
- `孔直径` + `调整圆柱孔径`：
  - 先选择一个圆柱面。
  - 输入新的直径。
  - 目标直径大于当前直径时，会使用有限长度 cutter 扩大切削。
  - 目标直径小于当前直径时，会先在原圆柱面范围内补料，再按目标直径重切。
  - 点击 `调整圆柱孔径` 后，会先显示半透明预览；红色是切削范围，绿色是缩小孔径时的补料范围。
  - 程序会先生成切削计划，检查当前直径、目标直径、候选类型、材料投票和风险。
  - 切削计划会显示直径变化量、直径变化比例，以及目标直径相对圆柱面估算高度的比例。
  - 切削计划会显示端部类型、深度估算、起点端状态和终点端状态。
  - 切削计划会显示疑似底面 Face、开口端相邻Face和底面保护说明；这些信息会写入操作历史。
  - 如果目标直径小于等于 0，或几乎等于当前直径，程序会直接阻止。
  - 如果目标直径变化过大，或者目标直径相对圆柱估算高度明显异常，程序会提高风险并要求确认。
  - 缩小孔径当前版本只对 `hole/groove candidate` 开放；圆角、凸柱或未明确圆柱面会被直接阻止。
  - 缩小孔径属于高风险实验功能，因为它依赖“补料 + 重切”的布尔近似，不是 CAD 历史参数修改。
  - 如果当前 Face的猜测类型不是 `hole/groove candidate`，或风险不是低风险，程序会先弹窗确认。
  - 切削计划会显示 cutter 策略、高度和余量；当前优先使用有限长度 cutter，减少误切其他区域。
  - 缩小孔径时，操作历史会额外记录补料策略、补料半径和补料高度。
  - 端部类型是通过轴线端部 inside / outside 采样得到的估算，不等于 CAD 原始建模历史里的“孔深”参数。
  - 如果选到的圆柱面不是孔，而是柱或圆角，结果可能不是你想要的，所以它目前仍是实验功能。
- `直径` / `半径` 的 `缩放特征`：
  - 先选择一个圆柱 Face，然后在当前选中对象表里修改 `直径` 或 `半径`，并把 `建模意图` 设为 `缩放特征`。
  - 它会按目标直径或半径比例均匀缩放所属特征或 Solid，适合“整个所属对象一起放大/缩小”的意图。
  - 它不适合只想改孔壁的场景，因为高度、厚度和同一对象上的其它尺寸会一起变化。
- `槽/半孔宽度` + `调整槽/半孔宽度`：
  - 先切换到 `Feature` 选择模式并选择一个槽/半孔候选 Face，或从圆柱面候选表中选择局部圆柱形 `hole/groove candidate`。
  - 选中符合条件的槽/半孔后，`槽/半孔宽度` 会自动填入一个比当前槽宽估算略大的建议值。
  - 输入目标槽宽后点击 `调整槽/半孔宽度`。
  - 程序会用当前圆弧角度把目标槽宽换算成目标圆柱直径，再复用圆柱孔/槽调整流程。
  - 这一步仍是 B-Rep 几何近似；复杂槽、非圆柱槽或圆弧角度不稳定时可能失败并回滚。
- `槽/半孔深度`：
  - 先选择一个槽/半孔候选 Face。
  - 在特征参数表里修改 `槽/半孔深度`，然后点击 `参数化建模`。
  - 程序会按当前圆弧角度把目标槽深换算成目标圆柱直径，再复用圆柱孔/槽调整流程。
- `槽/半孔圆弧长度`：
  - 先选择一个槽/半孔候选 Face。
  - 在特征参数表里修改 `槽/半孔圆弧长度`，然后点击 `参数化建模`。
  - 程序会按当前圆弧角度把目标圆弧长度换算成目标圆柱直径，再复用圆柱孔/槽调整流程。
- `槽宽` / `槽深` / `弧长` 的 `缩放特征`：
  - 先选择一个槽/半孔候选 Face。
  - 在当前选中对象表里修改对应属性，并把 `建模意图` 设为 `缩放特征`。
  - 程序会把目标槽宽、槽深或弧长换算成目标圆柱直径，然后按比例整体缩放所属特征或 Solid。
  - 这不是局部重切槽；同一所属对象上的高度、厚度和其它尺寸也会跟随变化。
- `槽/半孔圆弧角度` / `槽/半孔开口角度`：
  - 先选择一个槽/半孔候选 Face。
  - 在当前选中对象表里修改角度值，角度输入单位是度。
  - 圆弧角度会直接换算成局部扇形槽目标角度；开口角度会换算成 `2π - 开口角`。
  - 程序会保持当前圆柱半径，先补旧扇形槽，再按目标角度重切局部扇形槽。
- `轴心` 的 `移动槽/半孔`：
  - 先选择一个槽/半孔候选 Face。
  - 在当前选中对象表里修改目标坐标，格式是 `X, Y, Z`，并把 `建模意图` 设为 `移动槽/半孔`。
  - 程序会先填充旧的局部扇形槽，再在目标轴心位置按同宽度、同圆弧角度切出新槽。
  - 这一步只移动选中的局部扇形槽面，不等于完整 CAD 草图里的槽整体迁移；长圆槽、链式槽和复杂槽需要确认结果，失败会回滚。
- `轴心` 的 `移动特征`：
  - 同样输入目标 X, Y, Z 坐标。
  - 把 `建模意图` 设为 `移动特征`。
  - 程序会把目标轴心换算成平移向量，并平移所属特征或 Solid；不会填旧槽，也不会切新槽。
  - 这适合“整个对象搬动到新位置”的意图，不适合只想移动槽本身的场景。
- `槽孔配对端 Face ID` / `槽孔总长度` / `槽孔中心距`：
  - 对长圆槽或成对半圆槽，程序会在点击修改时自动寻找另一个槽端，避免选择对象时扫描过重。
  - 如果自动配对失败，可以先在 `槽孔配对端 Face ID` 行填入另一个半圆端的 Face ID 并点击 `设置`。
  - 修改 `槽孔总长度` 或 `槽孔中心距` 时，会保持槽宽不变并重建完整长圆槽体。
- `壳体厚度` 的 `拉伸/切除`：
  - 先选择一个已识别到相对平面的壳体平面 Face。
  - 在当前选中对象表里修改 `壳体厚度`，并把 `建模意图` 设为 `拉伸/切除`。
  - 输入目标厚度后点击 `参数化建模`。
  - 程序会移动当前平面区域，让它和相对平面的距离接近目标厚度；相对平面保持不动。
  - 如果相对平面重叠率低、厚度变化过大或拉伸/切除方向不稳定，会提高风险或阻止执行。
  - 这一步仍是局部 B-Rep 平面拉伸/切除近似，不是完整 CAD 壳体特征参数编辑。
- `壳体厚度` 的 `缩放特征`：
  - 先选择一个已识别到相对平面的壳体平面 Face。
  - 在当前选中对象表里修改 `壳体厚度`，并把 `建模意图` 设为 `缩放特征`。
  - 程序会沿壳体厚度方向缩放所属特征或 Solid，让估算厚度接近目标值。
  - 这不是拉伸/切除；同一对象上的孔距、台阶位置和其它厚度方向尺寸也会跟随变化。
- `凸台直径` + `调整圆柱凸台直径`：
  - 先选择一个完整圆柱凸台 Face，建议从 `可编辑对象` 中点击 `调整圆柱凸台直径` 行进入。
  - 只有接近完整圆柱的 `boss/outer-round candidate` 会放行；局部外圆角、圆角面、孔/槽和未明确圆柱面会被阻止。
  - 目标直径大于当前直径时，会在同域圆柱侧壁范围内生成目标直径圆柱并 Fuse。
  - 目标直径小于当前直径时，会先用旧外形包络体移除原凸台范围，再 Fuse 目标直径圆柱重建。
  - 点击后会显示半透明预览：绿色表示扩大/重建补料范围，红色表示缩小移除范围。
  - 这不是 CAD 历史里的“修改凸台特征参数”，而是基于当前 B-Rep 的受限几何布尔编辑。
- `直径` / `半径` 的 `缩放特征`：
  - 先选择一个圆柱凸台 Face，然后在当前选中对象表里修改这一行。
  - 把 `建模意图` 设为 `缩放特征`。
  - 它会按目标直径或半径比例均匀缩放所属特征或 Solid，不走凸台包络移除/重建路线。
  - 这会连带影响所属对象上的高度、厚度和其它尺寸，需要确认这正是你的建模意图。
- `凸台高度`：
  - 先选择一个完整圆柱凸台 Face。
  - 在当前选中对象表里修改 `高度`，并把 `建模意图` 设为 `拉伸/切除端盖`，然后点击 `参数化建模`。
  - 程序会尝试找到凸台外端盖 Face，并通过拉伸/切除端盖改变高度。
- `高度` 的 `缩放特征`：
  - 先选择一个完整圆柱凸台或普通完整圆柱 Face。
  - 在当前选中对象表里修改 `高度`，并把 `建模意图` 设为 `缩放特征`。
  - 程序会沿圆柱轴向缩放所属特征或 Solid，让圆柱高度接近目标值。
  - 这不是端盖拉伸/切除；同一对象上的孔距、台阶位置和其它轴向尺寸也会跟随变化。
- `轴心`：
  - 先选择一个完整圆柱凸台 Face。
  - 在当前选中对象表里修改 `轴心`，并把 `建模意图` 设为 `移动凸台`，然后点击 `参数化建模`。
  - 程序会切掉旧凸台包络，再按原直径和原高度范围在目标轴心位置补出新凸台；目标位置离基体太远时风险会升高。
- `轴心` 的 `移动特征`：
  - 同样输入目标 X, Y, Z 坐标。
  - 把 `建模意图` 设为 `移动特征`。
  - 程序会整体平移凸台所属特征或 Solid；不会移除旧凸台，也不会补新凸台。
  - 这适合移动整个所属对象，不适合只改凸台相对基体的位置。
- `轴心` 的 `移动孔`：
  - 先选择一个完整圆柱孔 Face。
  - 在当前选中对象表里修改目标 X, Y, Z 坐标，并把 `建模意图` 设为 `移动孔`。
  - 程序会先填补旧孔，再按同直径在目标轴心位置切出新孔。
- `轴心` 的 `移动特征`：
  - 同样输入目标 X, Y, Z 坐标。
  - 把 `建模意图` 设为 `移动特征`。
  - 程序会整体平移孔所属特征或 Solid；不会填旧孔，也不会切新孔。
  - 这适合移动整个所属对象，不适合只改孔相对基体的位置。
- `封堵圆柱孔`：
  - 先选择一个完整圆柱孔 Face，建议从 `可编辑对象` 中点击 `封堵圆柱孔` 行进入。
  - 点击 `封堵圆柱孔` 后，程序会先生成补料计划。
  - 只有接近完整圆柱的 `hole/groove candidate` 会放行；半孔/槽、圆角、凸柱、未明确圆柱面会被阻止。
  - 通过检查后，会显示绿色半透明补料体预览。
  - 真实编辑会把补料体和当前零件 Fuse，并尝试合并同域面/边。
  - 这个功能适合封堵通孔或盲孔，但仍是基于 B-Rep 几何的受限补料，不是 CAD 历史里的“删除孔特征”。
- `盲孔/盲槽深度` 的 `改底面深度`：
  - 先选择一个盲孔或盲槽的圆柱面，建议从 `可编辑对象` 中点击 `调整盲孔深度` 行进入。
  - 在当前选中对象表里修改 `盲孔/盲槽深度`，并把 `建模意图` 设为 `改底面深度`。
  - 输入目标深度后点击 `参数化建模`。
  - 目标深度大于当前估算深度时，程序会用有限长度 cutter 沿孔方向加深切削，预览显示为红色。
  - 目标深度小于当前估算深度时，程序会在旧底面方向补料，让孔变浅，预览显示为绿色。
  - 目标深度必须大于 0；如果和当前估算深度几乎相同，会直接阻止。
  - 当前只支持 `hole/groove candidate`、端部类型为 `blind`、并且已经识别到 `疑似底面 Face` 的对象。
  - 通孔、封闭内腔、圆角、凸柱和未明确圆柱面会被阻止，避免误切。
  - 这个深度来自圆柱面 V 参数范围和端部 inside / outside 采样，是几何估算，不是 CAD 历史参数。
  - 操作历史会记录当前深度、目标深度、深度变化比例、底面 Face、开口端 Face和工具参数。
- `盲孔/盲槽深度` 的 `缩放特征`：
  - 先选择一个已经识别出底面的盲孔或盲槽圆柱面；自动底面不准时，可以先填写 `底面 Face`。
  - 在当前选中对象表里修改 `盲孔/盲槽深度`，并把 `建模意图` 设为 `缩放特征`。
  - 程序会沿孔/槽轴向缩放所属特征或 Solid，让深度接近目标值。
  - 这不是加深切削，也不是变浅补料；同一对象上的壁厚、孔距和其它轴向尺寸会跟随变化。
- `圆角半径` + `给Edge添加圆角`：
  - 先切换到 `Edge` 选择模式并选择一条直线Edge，或从 `可编辑对象` 中点击 `给Edge添加圆角` 行进入。
  - 选中直线Edge后，`圆角半径` 会自动填入一个较小的建议半径。
  - 输入目标圆角半径后点击 `给Edge添加圆角`。
  - 程序会先检查半径是否大于 0、是否相对边长过大，以及该Edge是否检测到至少两个相邻Face。
  - 点击后会显示蓝色半透明圆管预览，用于提示目标边和半径范围。
  - 真实编辑会在后台调用 OCCT 倒圆 API，完成后刷新模型。
  - 这是“给直线边添加新圆角”，不是修改已有圆角面。
  - 由于 STEP 不带建模历史，某些边会被 OCCT 判断为不适合倒圆；失败时程序会提示并尝试恢复编辑前状态。
- `圆角半径` / `圆角弧长` 的 `重建圆角`：
  - 先切换到 `Feature` 选择模式并选择一个已有圆角/倒圆候选 Face，或从 `可编辑对象` 中点击 `修改已有圆角半径` 行进入。
  - 在当前选中对象表里修改 `圆角半径` 或 `圆角弧长`，并把 `建模意图` 设为 `重建圆角`。
  - 输入目标值后点击 `参数化建模`。
  - 程序会先检查该Face是否为 `round/fillet candidate`、是否识别到至少两个支撑Face、目标半径是否有效，以及当前零件是否为单Solid。
  - 通过检查后，会显示蓝色半透明预览，表示将尝试移除并重建的已有圆角面；简单等半径圆角链会把链上圆角面一起纳入重建计划。
  - 真实编辑会先用 OCCT defeaturing 移除已有圆角面或链上圆角面，再从恢复出的候选锐边中寻找可重新倒圆的边并调用 OCCT 倒圆 API。
  - 这是 B-Rep 几何重建，不是 CAD 历史圆角参数编辑；复杂 blend、支撑面不明确或恢复锐边失败时会失败并回滚。
- `圆角半径` / `圆角弧长` 的 `缩放特征`：
  - 先选择一个已有圆角/倒圆候选 Face。
  - 在当前选中对象表里修改 `圆角半径` 或 `圆角弧长`，并把 `建模意图` 设为 `缩放特征`。
  - 程序会按目标圆角半径或圆弧长度换算出的比例整体缩放所属特征或 Solid，不会移除旧圆角再重建。
  - 这会连带改变同一对象上的其它尺寸。
- `倒角距离` + `给Edge添加倒角`：
  - 先切换到 `Edge` 选择模式并选择一条直线Edge，或从 `可编辑对象` 中点击 `给Edge添加倒角` 行进入。
  - 选中直线Edge后，`倒角距离` 会自动填入一个较小的建议距离。
  - 输入目标倒角距离后点击 `给Edge添加倒角`。
  - 如果需要两侧不同距离，在当前选中对象表里填写 `新增不等距倒角D1/D2`，格式为 `D1, D2`。
  - 如果需要距离+角度倒角，在当前选中对象表里填写 `新增距离+角度倒角D/角度`，格式为 `距离, 角度`，角度单位是度。
  - `倒角参考Face ID` 决定 D1/D2 的方向；默认使用当前Edge的第一个相邻Face，也可以改成另一个相邻Face后点击 `设置`。
  - 程序会先检查倒角距离是否大于 0、是否相对边长过大，以及该Edge是否检测到至少两个相邻Face。
  - 点击后会显示橙色半透明圆管预览，用于提示目标边和倒角距离范围。
  - 真实编辑会在后台调用 OCCT 倒角 API，完成后刷新模型。
  - 当前支持对称距离倒角、两侧不同距离倒角和距离+角度倒角。
  - 由于 STEP 不带建模历史，某些边会被 OCCT 判断为不适合倒角；失败时程序会提示并尝试恢复编辑前状态。
- `长度` + `建模意图`：
  - 先切换到 `Edge` 选择模式并选择一条Edge，或从 `可编辑对象` 中点击Edge长度相关行进入。
  - 选中Edge后，`长度` 会自动填入当前Edge长度。
  - 当前选中对象表中的 `长度基准` 行可以选择 `自动`、`中心`、`固定起点` 或 `固定终点`。
  - `长度` 行的 `建模意图` 下拉框可以选择 `自动`、`只改当前Edge`、`移动端面`、`相邻圆柱` 或 `缩放所属`。
  - 把 `长度` 改成目标值后点击 `参数化建模`。
  - 如果选中的是直线Edge，也可以在当前选中对象表中直接修改 `起点`、`中心` 或 `终点`，格式是 `X, Y, Z`，然后点击 `参数化建模`。
  - 修改 `中心` 会保持这条直线Edge长度不变，两个端点一起移动；修改起点或终点则只移动对应端点。
  - 对 `assets/models/cube_10mm.step` 这类全平面多面体，选择 `只改当前Edge` 时会只移动被选Edge的端点并重建周边面。这时正方体不会变成长方体；相邻面会跟着被移动的边自然变形，四点非平面面会优先重建成连续曲面，不再默认拆出面内对角线。
  - 对同一个正方体，选择 `移动端面` 时会把改边长转成端面拉伸/切除，相关平行边会一起变化，结果更像从正方体变成长方体；执行后会反查目标 Edge、相邻侧面和移动端面仍满足一级平面关系。
  - 如果确认窗口里的策略是 `local-edge-only-deform`，说明走的就是“只改这条边”的局部形变路径。
  - 如果确认窗口里的策略是 `local-edge-endpoint-deform`，说明走的是“移动起点/终点坐标”的局部形变路径。
  - 如果确认窗口里的策略是 `local-edge-center-deform`，说明走的是“移动整条Edge中心”的局部形变路径。
  - 如果模型不是简单全平面多面体，直线Edge会继续尝试端面拉伸/切除后备路径，并计算需要移动的端面Face和拉伸/切除距离。
  - 圆形/圆弧Edge会优先尝试复用相邻圆柱面的孔/槽或凸台直径编辑，并在确认窗口显示换算出来的目标直径。
  - 如果圆边没有可复用圆柱面，但能读取圆心和轴线，会走 `围绕圆边轴线径向缩放` 后备策略，尽量不改变轴向厚度/高度；执行后部分解析几何可能变成 B-spline。
  - 椭圆边优先通过 `椭圆主半径` / `椭圆小半径` 修改；B-spline / Bezier 等复杂曲线边暂不作为界面里的稳定长度修改入口。
  - `固定起点` 会让起点不动、移动终点；`固定终点` 相反；`中心` 会让两端各移动一半，只有进入缩放 fallback 时才会变成以Edge中心为基准缩放。
  - 如果没有明确端面或可复用圆柱面，程序会按所选基准尝试整体/轴向几何缩放 fallback；这会影响所属零件/Solid的其它尺寸，因此会弹出高风险确认。
  - 执行成功后会做后置边长校验：在刷新后的零件/Solid范围内寻找最接近目标长度的Edge，并把实际最近边长、误差和相对误差写入操作结果。
  - 通过检查后，会显示蓝绿色半透明预览，表示将要移动或缩放的范围。
  - 真实编辑在后台执行，失败时会回滚到编辑前状态。
  - 这是当前版本的 B-Rep 结果几何修改，不是任意边参数化改长。
- `平移 X/Y/Z` + `平移选中零件` / `平移选中Solid`：
  - 输入 X、Y、Z 三个方向的平移量。
  - 选择 `零件` 后点击 `平移选中零件`，会移动整个零件。
  - 选择 `Solid`，或选择属于某个Solid的Face/Edge后，点击 `平移选中Solid`，会移动当前Solid。
  - 如果当前零件只有一个Solid，平移Solid实际会移动整个零件 shape，程序会提示中风险。
  - 平移向量为 0 会直接阻止。
  - 如果平移距离相对对象包围盒过大，程序会提高风险并要求确认。
  - 平移属于真实 B-Rep 变换，会写入操作历史，可以撤销/重做。
- `旋转轴/角度` + `旋转选中零件` / `旋转选中Solid`：
  - 选择 X、Y 或 Z 旋转轴。
  - 输入旋转角度，单位是度。
  - 选择 `零件` 后点击 `旋转选中零件`，会绕该零件的包围盒中心旋转整个零件。
  - 选择 `Solid`，或选择属于某个Solid的Face/Edge后，点击 `旋转选中Solid`，会绕该Solid的包围盒中心旋转当前Solid。
  - 如果当前零件只有一个Solid，旋转Solid实际会旋转整个零件 shape，程序会提示中风险。
  - 旋转角度为 0 会直接阻止；角度超过 360 度会提高风险并要求确认。
  - 旋转属于真实 B-Rep 变换，会写入操作历史，可以撤销/重做。
- `撤销`：
  - 撤销上一次成功的编辑。
- `重做`：
  - 重做刚刚撤销的编辑。
- `操作历史`：
  - 显示当前模型已经成功执行的编辑。
  - 点击某条历史记录，会在 `选中对象信息` 中显示该次编辑的目标、参数、执行结果和拓扑数量变化。
  - 历史详情也会显示几何差异摘要，包括体积、表面积、包围盒尺寸和包围盒对角线的前后变化。
  - 点击某条历史记录时，3D 窗口会显示红/绿半透明差异叠加预览：红色表示编辑前，绿色表示编辑后。
  - 编辑后模型会覆盖距离热力图：蓝色接近无变化，黄色/红色表示变化更大。
  - 历史详情会显示热力图统计，包括最大距离、平均距离和发生明显变化的采样点比例。
  - `清除差异预览` 可以关闭红/绿叠加显示。
  - `导出差异报告` 会把当前选中的历史记录导出为 `.txt`，里面包含操作详情、拓扑变化、几何变化和热力图统计。
  - `导出编辑历史` 会把当前会话中的本软件编辑记录导出为 `.json`，用于留档和后续复盘；当前格式是 `step-editor-operation-history-v2`，包含机器可读的动作名、目标和参数。
  - 当前热力图是“编辑后模型顶点到编辑前模型表面”的距离估算，不是完整 CAD 公差报告。
  - 点击某条历史记录时，程序也会尝试重新高亮当时编辑的目标Face，并在详情里显示当时的拾取位置；3D 视图里不会额外画拾取点小球。
  - 由于布尔编辑后拓扑 ID 可能重新分配，历史里的Face ID只能作为定位参考，不能视为稳定的 CAD 建模历史 ID。
  - 撤销后对应记录会从列表里退回。
  - 重做后对应记录会重新显示。

导出：

- `导出模型`：导出当前完整模型。
- `导出选中零件`：导出当前选中的零件。
- `导出选中Solid`：先选中一个Solid，再导出该Solid。
- `导出选中面区域`：先切换到 `Face` 选择模式并选中一个Face，再导出该Face；如果当前选择已经带有特征区域信息，则会导出这片已知区域。
- `导出选中特征区域`：先切换到 `Feature` 选择模式并选中特征，再导出当前特征高亮的Face集合。
- `导出选中Edge`：先切换到 `Edge` 选择模式并选中一个Edge，再导出该Edge。
- `导出参数`：在 `特征参数` 表的 `输入参数` 列勾选需要外部驱动的尺寸行后，点击按钮会在项目根目录写出 `data.json`，并在 `nodes/` 下生成一个 FlowEditor 风格的参数化组件 `main.py`。组件脚本会把勾选的输入参数直接嵌入 `INPUT_PARAMETERS`，通过 `PARAMETERS / NODE_INFO` 暴露给节点设计器，并提供 `execute(inputs, params, context)` 调用入口；组件目录里不会额外生成 `data.json` 或 `step_edit_config.json`。执行后返回 `output_step`，指向修改后的 STEP 文件。
- `检查导出质量`：检查当前选中对象；如果没有选中对象，就检查当前完整模型。
- `修复当前模型`：对当前完整模型执行 ShapeFix 和同域面/边合并，完成后会刷新显示并写入操作历史；如果修复失败，会尝试回滚到修复前状态。
- `修复选中零件/Solid`：优先修复当前选中对象所属Solid；如果当前对象没有Solid，则修复所属零件。Face或Edge被选中时，也会按其所属Solid/零件执行局部修复。
- 导出按钮会根据当前选中对象自动启用或禁用，避免选中Face时误点 `导出选中Edge` 这类不匹配的操作。
- 所有导出按钮都会先做质量检查。发现 B-Rep 无效、没有Solid、零件包含多个Solid、体积接近 0 等风险时，会先弹窗确认是否继续导出。

## 目录结构

当前整理后的项目结构是：

```text
pythonocc-step-editor/
  main.py                 # 程序入口，保持 python main.py 启动
  data.json               # 导出参数生成的本地流程参数文件，默认不提交
  nodes/                  # 导出参数生成的本地组件目录，组件参数会嵌入 main.py，默认不提交
  tools/
    asitus_probe/         # 可提交的 Analysis Situs probe 源码，构建输出放到 third_party/asitus_probe_tools_build
  assets/
    models/
      geom_extract.step   # 当前默认测试模型
      cube_10mm.step      # 简单立方体测试模型，用于验证边长修改等基础操作
    screenshots/          # 调试截图和问题截图，默认不提交
  local/                  # 本机自用说明和教学文档，默认不提交
  scripts/
    GeometryParametric.spec # PyInstaller 文件夹版打包配置
    package_windows.ps1   # 生成 dist/GeometryParametric 和 dist/GeometryParametric_windows_x64.zip
    generate_cube_step.py # 生成 assets/models/cube_10mm.step 的小工具
    verify_first_level_acceptance_docs.py # 验证 README 的一级验收口径和阶段验证入口保持一致
    verify_first_level_edit_suites.py # 按 Face、孔/槽、Edge、凸台、圆角/倒角、壳体阶段串起一级编辑回归
    verify_analytic_surface_resize.py # 临时生成圆锥/球/环面 STEP 并验证简单圆锥解析重建和曲面整体缩放
    verify_cone_semi_angle_isolation.py # 验证圆锥半角/参考半径隔离执行和嵌入式锥孔局部重切
    verify_boss_edit_suite.py # 一键运行凸台专项修改验证
    verify_boss_first_level_topology.py # 临时生成圆柱凸台 STEP 并验证凸台一级共边拓扑字段
    verify_boss_resize.py # 临时生成圆柱凸台 STEP 并验证凸台直径/高度/轴心修改
    verify_edge_edit_suite.py # 一键运行 Edge 专项修改验证
    verify_edge_first_level_topology.py # 验证 Edge 一级端点/相邻边/相邻 Face 事实包和编辑计划携带情况
    verify_edge_coordinate_edit.py # 验证直线 Edge 起点/中心/终点坐标局部修改
    verify_edge_target_guards.py # 验证 Edge 目标值不变、0/负数、退化或过大参数会在计划阶段阻止
    verify_edge_intent_specs.py # 验证 Edge 长度建模意图下拉项和底层策略映射一致
    verify_ellipse_edge_resize.py # 临时生成椭圆 STEP 并验证椭圆主半径/小半径单轴缩放
    verify_edge_length_resize.py # 验证立方体 Edge 长度局部形变基线
    verify_edge_round_chamfer.py # 临时生成盒子/已有圆角/圆角链 STEP 并验证 Edge 圆角、倒角、已有圆角修改、简单等半径圆角链/四面连通链重建和变半径链守门
    verify_round_chamfer_edit_suite.py # 一键运行圆角/倒角专项修改验证
    verify_edge_isolated_edit.py # 通过 isolated worker 真实验证 Edge 一级编辑隔离执行
    verify_face_coplanar_push_pull.py # 验证共面碎面会作为一个 Face 区域一起拉伸/切除
    verify_face_complex_boundary_guard.py # 验证带内孔平面 Face 会禁用局部重建的局部变形，但保留向外拉伸和向内切削
    verify_face_edit_suite.py # 一键运行 Face 专项修改验证
    verify_face_extreme_target_guards.py # 验证 Face 面内尺寸、偏移和壳体厚度不能输入过大或过小的极端目标值
    verify_face_freeform_guard.py # 验证 B-spline 等自由曲面 Face 只显示只读限制说明，不暴露伪参数化编辑入口
    verify_face_invalid_target_guards.py # 验证 Face 面内尺寸和壳体厚度不能输入非数字、0 或负数
    verify_large_stepped_cap_push_pull.py # 验证大 STEP 里的同轴阶梯环形端盖拉伸/切除走局部 shell 重建而不是 180s 布尔慢路径
    verify_face_logical_selection_retention.py # 验证 Face 修改后逻辑 ID 仍指向被编辑的新面
    verify_face_mixed_surface_guard.py # 验证圆柱端盖这类平面 Face 会禁用局部变形，但保留拉伸/切除；保持关系会因非平面一级邻域阻止
    verify_face_nonrectangular_local_edit.py # 验证三角平面 Face 的局部/整体中心、面内尺寸、偏移和拉伸/切除；斜交一级邻域会阻止保持关系
    verify_face_noop_guards.py # 验证 Face 目标值不变时会被阻止
    verify_first_level_fact_graph.py # 验证平面、孔、槽会输出统一一级拓扑事实包，且编辑计划会携带这份事实
    verify_feature_recognition_summary.py # 验证平面、孔、槽、凸台候选会输出统一识别摘要、常用优先级、置信度、风险和证据
    verify_face_property_readback.py # 验证 Face 编辑完成后属性表当前值和目标值会刷新到新几何
    verify_face_push_pull_limits.py # 验证 Face 向内切除不会允许切穿实体厚度
    verify_face_ui_isolation_contract.py # 验证 Face UI 入口和 isolated worker 的隔离操作列表一致
    verify_face_rectangular_axes.py # 验证矩形 Face 的面内长度和面内宽度方向不会混淆
    verify_face_resize_semantics.py # 验证 Face 当前面/整体尺寸编辑语义
    verify_hole_slot_edit_suite.py # 一键运行孔/槽专项修改验证
    verify_hole_resize.py # 临时生成通孔/盲孔 STEP 并验证孔径/孔轴心/盲孔深度修改
    verify_property_editor_specs.py # 验证属性表不会把通用 Face 编辑混入孔/槽/凸台/圆角/解析曲面特征
    verify_property_card_editor_ui.py # 验证参数表 UI 能构建、检测目标值修改并展开完整参数
    verify_relation_formula_rules.py # 验证关系式自引用、重复目标和循环依赖会在添加阶段阻止
    verify_parametric_component_export.py # 验证导出参数会生成嵌入参数列表的组件 main.py，组件目录不额外写 data.json
    verify_scdm_backend.py # 验证 SCDM 后端发现、缓存、禁用开关和 /RunScript 烟测命令生成
    verify_scdm_status.py # 验证 SCDM 左侧状态摘要、后端来源、识别缓存计数和 OCCT/Analysis Situs 兜底说明
    verify_scdm_probe_pipeline.py # 验证 SCDM probe job/script 生成和 raw 识别结果到产品化 cache 的映射
    verify_scdm_edit_runner.py # 验证 SCDM edit job/script/result/error 执行协议
    verify_scdm_result_validator.py # 验证 SCDM 结果文件检查、目标值回测、全局摘要漂移、ID 映射和关系式重写
    verify_asitus_hole_bridge.py # 验证 Analysis Situs 孔组识别结果会映射回 Python Face 编号和 UI 整孔选择
    verify_shell_edit_suite.py # 一键运行壳体厚度专项修改验证
    verify_shell_thickness_resize.py # 临时生成薄板 STEP 并验证壳体厚度局部/整体修改
    verify_slot_resize.py # 临时生成槽 STEP 并验证槽宽/槽深/弧长/弧角/半圆槽轴心/长圆槽轴心/总长度/中心距修改
    verify_cylindrical_first_level_topology.py # 临时生成孔/槽 STEP 并验证圆柱孔、盲孔、半圆槽、长圆槽的一级共边拓扑字段
  step_editor/
    __init__.py           # 包导出
    app.py                # 主窗口初始化、UI 搭建和程序启动
    constants.py          # OCCT 曲面、曲线和方向类型常量映射
    export.py             # 导出、导出质量检查和面区域导出逻辑
    features.py           # 平面、圆柱、孔、槽、凸台、圆角等候选识别和编辑计划
    geometry_utils.py     # OCC 几何、拓扑、布尔修复、向量和形状工具函数
    info_panel.py         # 属性面板、信息树和复制信息逻辑
    model.py              # StepModel 核心状态、拓扑索引、基础属性和 mixin 组合
    model_types.py        # PartNode、TopologyStats 等模型数据结构
    operations.py         # 拉伸/切除、孔径、孔深、圆角、倒角、边长等实际编辑操作
    polydata.py           # OCC Shape / Edge / Face 到 VTK polydata 的显示数据生成
    records.py            # 操作历史记录数据结构
    step_io.py            # STEP/XCAF 读取、产品名解析、STEP 写出和内部 BREP 临时交换
    transforms.py         # 零件 / Solid 平移和旋转
    ui_helpers.py         # UI 常量、格式化函数和 VTK 显示小工具
    widgets.py            # 自定义 Qt 小组件
    window_actions.py     # 导出、编辑按钮、扫描、后台编辑调度等窗口动作
    window_core.py        # 文件加载、结构树、VTK 视图、选择、拾取、高亮和预览
    window_state.py       # 选择状态、按钮状态、撤销/重做和历史定位
    workers.py            # 后台编辑和后台扫描 worker
  environment.yml         # Conda 环境说明，用于安装 pythonocc-core、VTK、PySide6 等依赖
  README.md               # 项目说明和使用说明
```

这次整理把根目录收窄到入口、环境配置和说明文档；仓库自带 STEP 测试模型放到 `assets/models/`，问题截图和调试截图放到 `assets/screenshots/`，本机自用的 `教学.txt` 和 `几何参数化测试说明.txt` 放到 `local/`。`environment.yml` 保留在根目录，方便 Conda 用户直接发现并运行 `conda env create -f environment.yml`。后端和窗口层都按 mixin / 工具模块拆开，尽量不改变功能行为。

`step_editor/model.py` 现在主要保留 StepModel 的核心状态、拓扑缓存、基础属性查询和 mixin 组合；具体能力分散到 `features.py`、`operations.py`、`export.py`、`transforms.py`、`polydata.py`、`step_io.py` 和 `geometry_utils.py`。

`step_editor/app.py` 现在主要保留主窗口初始化、左侧操作面板搭建和程序入口；VTK 视图、选择高亮、编辑动作、扫描、撤销/重做和属性面板逻辑已经拆到 `window_core.py`、`window_actions.py`、`window_state.py`、`info_panel.py` 和 `ui_helpers.py`。

其他文件说明：

- `.gitignore`：Git 忽略规则，避免提交 Python 缓存、临时文件和导出的 STEP 文件。
- `*_edited.step`、`*_export.step`、`*_diff_*.txt`、`*_operation_history.json`：运行或导出时产生的结果文件，默认不提交。
- `assets/models/`：仓库自带的 STEP 测试模型，可以提交；运行时导出的 STEP 结果仍然默认忽略。
- `assets/screenshots/`：调试截图和问题截图，例如第三方软件显示效果、模型结构树截图等，默认不提交。
- `local/`：本机自用文档目录，例如 `教学.txt` 和 `几何参数化测试说明.txt`，默认不提交；打包脚本会把 `local/几何参数化测试说明.txt` 复制到 `main.exe` 同级目录。

## 当前版本边界

这一版重点是验证整体链路，不是最终 CAD 编辑器。

模型显示、选择、属性查看、撤销/重做和导出是当前主要能力。局部编辑已经接入，但仍属于受限 B-Rep 能力。复杂 STEP 几何上的布尔操作可能失败；失败时程序会弹窗提示，不会静默覆盖原始文件。

## Codex 项目记忆（开发者可忽略）

这一节只给后续重新打开的 Codex 聊天框使用，普通开发者不需要阅读。Codex 接手时先读这里，再读本 README 的“目录结构”和“当前版本边界”。

### 项目目标

本项目是一个基于 Python、pythonocc-core/OCCT、VTK 和 PySide6/Qt 的 STEP 查看与局部编辑原型。它处理的是 STEP 里的 B-Rep 结果几何，不是原 CAD 软件的完整参数化建模历史。

最小系统目标是打通：加载 STEP、显示模型、选择零件/Solid/Face/Edge/特征、查看属性、识别初步候选特征、执行受限局部编辑、撤销/重做、质量检查和导出。

当前开发节奏必须分阶段闭环：先把 Face 修改能力做完整并集中测试，再做孔/槽；孔/槽通过后再做 Edge；Edge 通过后再做凸台、圆角、倒角、壳体和解析曲面。不要每个对象只做一点就切换方向。

截至 2026-08-06，一级编辑总验证入口 `scripts/verify_first_level_edit_suites.py` 已在 `pyocc` 环境下按阶段通过：Face、孔/槽、Edge、凸台、圆角/倒角、壳体和解析曲面，以及 `--quick` 轻量回归。后续不要把这些阶段当作“完全没做”；应在现有基线上根据真实 STEP 失败项继续补识别、补风险守门、补局部重建和性能稳定性。

### 运行方式

常用命令：

```powershell
conda activate pyocc
python main.py
python main.py assets\models\cube_10mm.step
python scripts\generate_cube_step.py
python scripts\verify_first_level_edit_suites.py --quick
python scripts\verify_first_level_edit_suites.py
python scripts\verify_face_edit_suite.py
python scripts\verify_isolated_face_edit.py
python scripts\verify_hole_slot_edit_suite.py
python scripts\verify_edge_edit_suite.py
python scripts\verify_edge_isolated_edit.py
python scripts\verify_boss_edit_suite.py
python scripts\verify_round_chamfer_edit_suite.py
python scripts\verify_shell_edit_suite.py
python scripts\verify_analytic_surface_resize.py
python scripts\verify_slot_resize.py
python main.py --smoke-test
```

如果 shell 里没有 `conda`，用户机器上之前可用的方式是：

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

在 Windows PowerShell 里用 `conda run` 跑输出较多的验证脚本时，如果遇到 Conda 自身的 `UnicodeEncodeError`，通常不是几何测试失败，而是外层 Conda 打印子进程日志时被系统编码绊住。可以先设置 UTF-8 输出再运行：

```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 --stage face
```

当前 Codex 沙盒环境可能没有 VTK/pythonocc，因此 GUI 和 smoke test 可能报 `ModuleNotFoundError: vtk`。能做的本地验证至少包括：

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

### 项目结构提示

- `main.py`：入口，保持 `python main.py` 可启动。
- `assets/models/`：仓库自带 STEP 测试模型，可以提交。常用测试模型是 `geom_extract.step`，简单边长测试模型是 `cube_10mm.step`。
- `assets/screenshots/`：调试截图和问题截图，默认忽略，不提交。
- `scripts/generate_cube_step.py`：生成 `assets/models/cube_10mm.step`。
- `scripts/verify_first_level_acceptance_docs.py`：验证 README 里声明的一级验收口径、阶段命令和脚本清单仍然能对上 `verify_first_level_edit_suites.py`，避免目标文档和实际验证入口脱节。
- `scripts/verify_first_level_edit_suites.py`：一级编辑总验证入口。默认按 Face、孔/槽、Edge、凸台、圆角/倒角、壳体和解析曲面阶段串起现有专项套件；`--quick` 跑烟测、属性表、参数表 UI、关系式规则、SCDM 后端发现底座、SCDM 状态摘要、SCDM probe/cache 假数据管线、SCDM edit job/runner 协议、SCDM result validator、ICEPAK 真实 STEP 同域圆柱孔、一级事实图、关联探测、显示网格预算和验收文档一致性；`--stage edge` 这类参数可只跑某个阶段。
- `scripts/verify_scdm_backend.py`：纯 Python 检查 SCDM 后端发现和缓存逻辑，不依赖 OCC；覆盖环境变量、常见安装目录、`local/scdm_backend.json`、禁用开关和 `/RunScript` 命令生成。
- `scripts/verify_scdm_status.py`：纯 Python 检查 SCDM 运行状态摘要，不依赖 OCC；覆盖未配置、已配置、后台识别中、识别成功、识别失败、cache 失效和缓存来源显示。
- `scripts/verify_scdm_probe_pipeline.py`：纯 Python 检查 SCDM probe job、RunScript 脚本生成、raw 识别结果到产品化 cache 的映射；覆盖第一批 `hole.diameter`、`hole.position` 和 `face.offset` 能力。
- `scripts/verify_scdm_edit_runner.py`：纯 Python 检查 SCDM edit job、临时修改脚本、成功 result.step/result.json、失败 error.json 和缺输出回滚判定；不依赖 OCC，也不需要真实 SCDM。
- `scripts/verify_scdm_result_validator.py`：纯 Python 检查 SCDM 修改结果的输出 STEP 存在性、目标值回测、raw summary 全局规模漂移、旧对象到新对象的唯一匹配、Face ID 映射、关系式 ID 重写和歧义匹配拒绝。
- `scripts/verify_analytic_surface_resize.py`：临时生成圆锥、球面和环面 STEP，验证简单圆锥参考半径/半角解析重建，以及球面半径、环面主半径和环面小半径整体缩放。
- `scripts/verify_cone_semi_angle_isolation.py`：临时生成简单圆锥、旋转圆锥、嵌入式沉头锥孔和带圆柱通孔的沉头锥孔，验证圆锥半角/参考半径的大参数修改会走解析重建或锥孔局部重切；同时覆盖非端面参考半径的局部重切推导、圆锥特征的小端/大端/高度/半角信息、真实模型复杂浅锥大幅半角修改的提前阻断、`1499.5 -> 1700` 这类参考半径修改的快速阻止，以及隔离子进程保护主界面。
- `scripts/verify_boss_resize.py`：临时生成底板加圆柱凸台 STEP，验证凸台直径扩大、直径缩小、高度修改和轴心移动的局部重建链路，并断言不会把单 Solid 拆成多个 Solid。
- `scripts/verify_boss_first_level_topology.py`：临时生成底板加圆柱凸台 STEP，验证凸台直径、高度、轴心和圆 Edge 代理轴心计划都会暴露一级共边拓扑关系，并验证凸台直径执行后会反查目标 Face 和一级关系。
- `scripts/verify_boss_edit_suite.py`：集中运行当前凸台阶段验证，串起凸台一级拓扑、凸台直径/高度/轴心局部重建、圆 Edge 代理轴心移动和属性表分组。
- `scripts/verify_round_chamfer_edit_suite.py`：集中运行圆角/倒角阶段验证，串起直线 Edge 新增圆角、对称倒角、不等距倒角、距离+角度倒角、已有圆角半径/弧长重建、简单等半径圆角链半径/弧长重建、四面连通圆角链重建、复杂同半径长链和变半径链守门、已有简单倒角距离重建、结果反查和属性表分组。
- `scripts/verify_edge_edit_suite.py`：集中运行当前 Edge 阶段验证，覆盖 Edge 一级拓扑事实包、直线 Edge 长度的自动策略、只改当前 Edge、移动端面/保持垂直、缩放所属对象，以及固定起点、固定终点、固定中心三类锚点；同时串起 Edge 建模意图 UI 映射、直线 Edge 起点/中心/终点坐标修改、Edge 圆角/倒角/已有圆角和简单等半径圆角链修改、椭圆 Edge 主/小半径修改。
- `scripts/verify_edge_first_level_topology.py`：加载 `cube_10mm.step`，验证一条正方体 Edge 的一级关系包含当前 Edge、2 个端点 Vertex、4 条共享端点相邻 Edge 和 2 个直接相邻 Face，并确认边长、端点/中心坐标、圆角和倒角计划都会携带这份一级事实包。
- `scripts/verify_edge_coordinate_edit.py`：加载 `cube_10mm.step`，分别验证直线 Edge 起点、中心和终点坐标修改，确认局部重建后仍能找到目标端点位置的直线 Edge，并保持单 Solid。
- `scripts/verify_edge_target_guards.py`：验证 Edge 长度、端点、中心、圆角、倒角、椭圆半径和圆 Edge 轴心这几类参数在目标值等于当前值、0/负数、退化或明显过大时会直接返回 blocked，并给出阻止原因，不进入真实几何计算。
- `scripts/verify_edge_intent_specs.py`：验证当前选中对象表里 Edge `长度` 行的 `自动`、`只改当前Edge`、`移动端面`、`相邻圆柱`、`缩放所属` 五种建模意图都能正确同步到底层 `strategy_mode`，并确认计划摘要会解释“邻面变斜”“端面跟随/类似长方体”“其它尺寸跟随”等执行影响。
- `scripts/verify_edge_length_resize.py`：加载 `cube_10mm.step`，把一条 10mm 直线 Edge 改到 15mm，并断言策略、目标边长和形态分布都正确：局部变形只应有 1 条目标长度边；移动端面或缩放所属应让同向 4 条边一起变成目标长度；移动端面还会检查相邻侧面和移动端面保持可验证的垂直/平行关系。
- `scripts/verify_edge_round_chamfer.py`：临时生成盒子、已有圆角盒子、已有倒角盒子和圆角链盒子 STEP，验证直线 Edge 新增圆角、对称倒角、不等距倒角、距离+角度倒角、已有圆角半径/弧长修改、简单等半径圆角链半径/弧长修改、四面连通圆角链修改、已有简单倒角距离修改，以及复杂同半径长链和变半径圆角链会在识别/计划阶段阻止。
- `scripts/verify_edge_isolated_edit.py`：通过 `python -m step_editor.isolated_edit_worker` 的真实 worker 入口验证 Edge 长度、直线 Edge 起点/中心移动、圆形 Edge 相邻轴心移动、椭圆 Edge 主半径、直线 Edge 新增圆角、三类倒角、已有圆角半径、简单等半径圆角链半径和已有简单倒角距离修改可以在隔离执行通道里完成，输出 STEP 能重新加载并保持目标几何语义。
- `scripts/verify_face_edit_suite.py`：集中运行当前 Face 阶段验证，覆盖 Face 一级共享边拓扑、面内长度/面内宽度、矩形 Face 两个面内方向区分、中心、偏移、共面碎面一起拉伸/切除/切削、向内切除切穿保护、带内孔平面 Face 的局部变形保护、圆柱端盖这类含曲面 Solid 的平面 Face 局部变形保护、B-spline 自由曲面只读守卫、大 STEP 同轴阶梯环形端盖局部 shell 拉伸/切除、非矩形平面 Face 局部编辑、编辑后属性值回读、修改后逻辑 Face ID 仍指向被编辑的新面、壳体厚度增厚/减厚、目标值等于当前值时必须阻止修改，以及面内尺寸/偏移/壳体厚度目标值为非数字、0、负数或极端过大/过小时必须阻止修改。面积相关后端回归仍保留作结果校验，不作为特征参数表里的可编辑行。
- `scripts/verify_face_edit_integrity_guards.py`：验证 Face 编辑结果不能丢 Solid、不能新增无效 B-Rep、不能只达到目标数值却破坏一级拓扑；若目标检查、一级拓扑计数或一级事实图校验失败，模型层会恢复编辑前快照。
- `scripts/verify_face_first_level_topology.py`：加载 `cube_10mm.step`，验证正方体上表面 Face 的一级关系只包含当前 Face、4 条边界 Edge、4 个边界 Vertex 和 4 个共享边相邻侧面；局部移动上表面后，目标 Face 的边界 Vertex 与共享边 Edge 会到达新高度，4 个一级侧面会跟随重建，二级底面保持不动。
- `scripts/verify_face_coplanar_push_pull.py`：临时生成顶部被拆成两片共面 Face 的单 Solid，验证选中其中一片时会把整片共面区域作为一个 profile 拉伸/切除，并确认拉伸/切除后原逻辑 Face ID 会定位到新生成的整片顶面。
- `scripts/verify_face_complex_boundary_guard.py`：临时生成带通孔板件，验证带内孔的平面 Face 会报告边界环数量，并禁用 `局部重建` 的面内长度/面内宽度、中心和偏移计划；同时确认 `拉伸/切除` 的向外补料和向内切削都仍可用并保持单 Solid，且同一 Solid 的局部变形可用性判断会复用缓存。
- `scripts/verify_face_mixed_surface_guard.py`：临时生成简单圆柱，验证圆柱端盖这个平面 Face 会因为所属 Solid 含有曲面而禁用 `局部重建` 的中心和偏移计划，属性提示会说明具体原因；同时确认 `拉伸/切除` 仍可用并让圆柱高度增加，`保持关系` 会因一级相邻含非平面/曲面而在 UI 和计划阶段阻止。

- `scripts/verify_face_freeform_guard.py`：临时生成 B-spline 自由曲面 STEP，验证它会被识别为只读受限 Face，识别风险为 blocked；属性表只显示限制说明和只读诊断，不暴露面积、中心、偏移、半径、半角等伪参数化编辑入口。
- `scripts/verify_face_invalid_target_guards.py`：验证 Face 面内尺寸和壳体厚度的局部/整体计划在目标值为非数字、0 或负数时都会返回 blocked，并提示目标值必须是有效正数；历史面积路径只作为后端守门回归保留。
- `scripts/verify_face_extreme_target_guards.py`：验证 Face 面内尺寸、偏移和壳体厚度的局部/整体计划在目标值会把几何缩到当前 5% 以下、放大到当前 5 倍以上，或把偏移移动到远超模型尺寸时都会返回 blocked，避免退化面、拉穿相邻几何或长时间无效计算。
- `scripts/verify_face_logical_selection_retention.py`：验证 Face 的局部/整体面内尺寸、局部/整体中心、局部/整体偏移和拉伸/切除正负方向完成后，原逻辑 Face ID 会排他地指向被编辑后的新 Face，避免 UI 改完参数后选中跑到别的面；历史面积路径只作为后端结果绑定回归保留。
- `scripts/verify_selection_identity_ui.py`：验证编辑后当前拓扑 Face ID 改变时，Face / 特征标题会显示 `逻辑 Face ID（拓扑 Face ID）`，复制 ID 会优先复制可再次选择的逻辑 Face ID，避免把用户带到重建后的临时拓扑编号上。
- `scripts/verify_face_feature_parameter_consistency.py`：加载常用测试模型 Face 594，验证轻量 `当前特征` 选择在 full feature 缓存前后都显示同一组基础 Face 参数，避免先改其它对象或触发深层识别后，同一个 Face 的属性列表突然缩水或膨胀。
- `scripts/verify_face_nonrectangular_local_edit.py`：临时生成三角柱 STEP，验证非矩形平面 Face 的 `局部重建`、`缩放特征`、`移动特征`、`拉伸/切除` 语义，在中心、面内尺寸和偏移场景下都能保持单 Solid；同时生成斜顶楔块，验证斜交一级相邻平面会提前阻止 `保持关系`。
- `scripts/verify_face_resize_semantics.py`：加载 `cube_10mm.step`，验证 Face 的面内长度/面内宽度、中心坐标和偏移在 `当前面` 局部编辑、`整体` 所属对象编辑、`拉伸/切除` 与 `保持关系` 之间不会互相混淆；面积路径只作为后端缩放语义回归保留。
- `scripts/verify_face_noop_guards.py`：验证 Face 的拉伸/切除、偏移、中心、面内尺寸和壳体厚度在目标值等于当前值时都会返回 blocked，并给出“不需要修改”的说明。
- `scripts/verify_first_level_fact_graph.py`：验证正方体平面 Face、拆分共面 Face、空心圆柱端盖、通孔圆柱面和槽/半孔候选都会输出统一一级拓扑事实包，包含主体 Face、同域/共面碎片、一级同轴圆柱关系、边界 Edge/Vertex、共享边一级相邻 Face、角色分组，以及明确不自动传播的二级/三级关系；同时验证 Face 拉伸/切除/面积/中心移动、孔径修改和槽宽修改的编辑计划都会携带这份事实。
- `scripts/verify_feature_recognition_summary.py`：验证平面 Face、带内孔平面 Face、通孔圆柱面、槽/半孔和凸台候选都会输出统一的 `识别摘要`、候选类型、常用优先级、置信度、风险、证据项、`当前可改` 和 `当前受限修改`；全局可编辑对象扫描也会按 Face、孔、槽、凸台、圆角/倒角、壳体、Edge 的常用顺序排序。
- `scripts/verify_face_property_readback.py`：验证 Face 的面内尺寸、中心和偏移编辑完成后，当前选中对象表里的当前值和目标值会重新读到新几何；特别覆盖 `偏移` 的 `局部重建`、`移动特征` 和 `拉伸/切除` 三种语义。面积读回只作为诊断结果验证。
- `scripts/verify_face_push_pull_limits.py`：验证平面 Face 向内切除时会估算当前面背后的材料厚度；浅范围切除允许执行，接近切穿会标为高风险，达到或超过材料厚度会直接 blocked；向外一次性拉伸/切除较大时会标为高风险并通过隔离子进程执行，而不是按绝对距离直接拒绝。
- `scripts/verify_face_ui_isolation_contract.py`：验证 Face、孔槽和 Edge 阶段使用的隔离操作集合、`WindowActionMixin._isolation_for_plan()` 的 UI 隔离列表，以及 `isolated_edit_worker` 真正支持的 worker 操作完全一致；脚本还会反向追踪属性表暴露的 Face 修改动作、孔槽入口和 Edge 入口是否最终进入隔离 worker，防止后续新增参数行时忘记接入后台隔离执行，导致 UI 卡死或主进程被危险 OCCT 计算拖崩。没有 pyocc 时可以先运行 `python scripts\verify_face_ui_isolation_contract.py --static-only` 做 AST 级契约检查。
- `scripts/verify_face_rectangular_axes.py`：临时生成 20 x 10 x 6 的矩形盒子，验证 10 x 20 的矩形 Face 在 `面内长度` 和 `面内宽度` 两个方向上可以分别做 `局部重建` 与 `缩放特征`，另一个方向不会被误改，属性表也会读回新值。
- `scripts/verify_cylindrical_height_resize.py`：临时生成简单圆柱、同轴空心圆柱、多孔圆柱和顶端带缺口圆柱，验证选中圆柱侧面修改高度时会走端盖拉伸/切除并校验目标高度、半径和一级拓扑；同时覆盖 isolated worker 子进程路径，确认这些高频 Face 修改不会把主界面拖进危险计算；`缩放特征` 的轴向缩放会按轴向跨度校验结果。
- `scripts/verify_large_stepped_cap_push_pull.py`：加载 `assets/models/geom_extract.step`，自动找到 y=-39 的同轴阶梯环形端盖和 y=-57.5 的多内孔大平面端盖，分别验证 `-39 -> 50` 走 `local-shell-rebuild`、`57.5 -> 92` 走 `boundary-shell-rebuild`，并验证多内孔大端面浅范围向内收缩也走 `boundary-shell-rebuild`，深向内切除会快速阻止且说明材料厚度或二级关系原因；成功路径保持单 Solid，原逻辑 Face ID 会继续指向移动后的新端面，一级边界 Edge/Vertex、共享边相邻 Face 和内孔线圈数量不能丢，并同时覆盖隔离子进程路径，避免 UI 操作退回 180s 布尔/全模型结果扫描慢路径。
- `scripts/verify_hole_slot_edit_suite.py`：集中运行当前孔/槽阶段验证，串起孔/槽一级圆柱拓扑、通孔/盲孔局部重建、半圆槽/长圆槽局部重建、隔离 worker 执行、逻辑 Face ID 保持、识别摘要、一级事实图和属性表分组。后续孔/槽能力新增或重构时优先跑这个套件，而不是只跑单个孔径或槽宽脚本。
- `scripts/verify_icepak_cylindrical_region_selection.py`：加载本地 `assets/models/ICEPAK-NATURAL.stp` 时，验证 Face87/94 这类被 STEP 拆成两片的同域圆柱孔会按整孔高亮、按整孔生成孔径计划，Face85/Face87 可以进入 Ctrl 多选孔参数面板，并能通过隔离 worker 完成 `0.5 -> 0.3` 的孔径缩小；模型文件不存在时自动跳过。
- `scripts/verify_asitus_hole_bridge.py`：验证 Analysis Situs `recognize_holes` 输出的 1-based AAG Face 组会先映射成 Python/Qt 里的 Face 编号，再作为整孔区域参与高亮、参数表和一级关系计划；本地 C++ CLI 不存在时只验证解析和映射逻辑。
- `scripts/verify_hole_resize.py`：临时生成通孔和盲孔 STEP，验证孔径扩大、孔径缩小、通孔轴心移动、完整通孔封堵、盲孔加深和盲孔变浅的局部重建链路；盲孔/盲槽深度修改现在会在操作内部确认目标深度和一级邻域，失败会回滚。
- `scripts/verify_hole_slot_isolated_edit.py`：临时生成通孔、盲孔、半圆槽和长圆槽 STEP，通过 `python -m step_editor.isolated_edit_worker` 的真实 worker 入口验证孔径、孔径缩放特征、孔轴心、孔封堵、盲孔深度、槽宽、槽宽缩放特征、槽深、弧长、弧角、槽轴心、长圆槽总长度和中心距可以在隔离执行通道里完成，输出 STEP 能重新加载并达到目标值；同时验证会破坏盲孔圆柱语义的整体缩放会被干净拒绝并回滚。窗口侧会额外验证孔径、孔轴心、槽宽、槽轴心、盲孔/盲槽深度、长圆槽总长度和长圆槽轴心隔离任务不会被误套用通用 Face 参数校验，并会把原逻辑 Face ID 继续绑定到修改后的孔壁、槽壁或长圆槽端部 Face。
- `scripts/verify_isolated_face_edit.py`：验证 high-risk Face 的偏移、面内尺寸、中心和壳体厚度局部/整体修改可以在隔离子进程里执行，子进程导出结果 STEP 后主流程仍能加载出单 Solid；面积路径保留为后端隔离守门回归。同时验证复杂大 STEP 多内孔端面的 UI 操作计划不会退回通用慢路径，避免按钮点击阶段长时间卡住主界面。
- `scripts/verify_property_editor_specs.py`：轻量验证当前选中对象表的规格生成逻辑，确保平面 Face 显示面内长度、面内宽度、中心和偏移，而孔、槽、凸台、已有圆角、圆锥、球面和环面不会混入通用 Face 编辑；同时验证面积不会作为特征参数表驱动变量出现，目标值等于当前值时不会误判为需要修改，带内孔 Face 禁用 `局部重建` 时会把具体原因写进提示，并确认 UI 不再单独暴露容易混淆的额外 `移动量` 行。
- `scripts/verify_property_card_editor_ui.py`：Qt-only 轻量验证当前选中对象表的参数表显示层，确认四列表格、目标值输入、建模意图下拉框、统一 `参数化建模` 按钮和展开完整参数都能正常工作，且诊断行不会混入特征参数表；同时守住普通 OCCT 操作历史里的 backend / execution / recognition 来源记录。
- `scripts/verify_associated_features.py`：验证 `探测相邻特征` 能在共享边拓扑范围内找到关联孔/凸台，把它们的可改尺寸以 `关联 Face` 行合并到当前特征参数表；`关联探测` 本身保留为诊断信息，不再混入参数表。同时验证大模型全量显示网格不会退回百万级三角面，而单个圆柱 Face 仍可局部细化，防止用户误以为探测级别切换没有生效或加载显示卡住。
- `scripts/verify_shell_edit_suite.py`：集中运行壳体厚度阶段验证，串起壳体厚度局部拉伸/切除、缩放特征、Face 一级事实图、结果校验和属性表分组。
- `scripts/verify_shell_thickness_resize.py`：临时生成薄板 STEP，验证壳体厚度局部拉伸/切除和整体调整两种语义，目标厚度可以大于或小于当前厚度；同时确认修改后原逻辑 Face ID 仍指向被编辑后的平面 Face，简单全平面薄板不会被整体调整变成 B-spline 曲面。脚本还会生成开口薄壁盒，验证完整抽壳/开口面编辑会被列为受限能力，而局部壳体厚度仍保留可用计划。
- `scripts/verify_slot_resize.py`：临时生成半圆槽和长圆槽 STEP，验证槽宽、槽深、弧长、弧角、半圆槽局部轴心、长圆槽整槽轴心、槽孔总长度和两端中心距的局部重建链路。

- `scripts/verify_cylindrical_first_level_topology.py`：临时生成通孔、盲孔、半圆槽和长圆槽 STEP，验证孔/槽类圆柱特征的修改计划会暴露一级共边拓扑关系，包括圆柱侧壁、边界 Edge、边界 Vertex、直接相邻 Face、底面/开口面/槽边界面，并明确二级、三级关系暂不自动传播。
- `environment.yml`：保留在根目录，方便 Conda 用户直接创建环境。
- `step_editor/app.py`：主窗口初始化、左侧操作面板和入口。
- `step_editor/window_core.py`：文件加载、结构树、VTK、拾取、高亮、预览和首次/精细加载。
- `step_editor/window_actions.py`：导出按钮、编辑动作、后台任务、扫描、操作历史记录生成。
- `step_editor/window_state.py`：选择状态、按钮启用/禁用、撤销/重做和历史定位。
- `step_editor/model.py`：`StepModel` 核心状态和 mixin 组合。
- `step_editor/features.py`：可编辑对象和圆柱面/孔/槽/凸台/圆角等识别计划。
- `step_editor/operations.py`：拉伸/切除、孔径、孔深、圆角、倒角、壳体、边长等真实几何编辑。
- `step_editor/export.py`：STEP 导出和质量检查。
- `step_editor/polydata.py`：OCCT shape/face/edge 到 VTK polydata。
- `step_editor/widgets.py`：Qt 自定义小控件，例如不误吃滚轮的下拉框。

### 左侧面板工作流

左侧面板前半段按用户指定顺序排列：STEP 文件、模型结构树、鼠标选择模式、按 ID 选择、编辑、导出、显示、测量。后半段继续放可编辑对象、圆柱面候选、操作历史和对象信息。

下拉框关闭时不能吃掉滚轮，鼠标停在下拉框上滚动应继续滚动左侧面板；只有打开下拉列表后，滚轮才用于滚动选项。

控件悬停提示必须面向普通用户说明“这个控件是干什么的、什么时候可用、失败后会怎样”，不要只写内部名词。

### 当前关键能力

- STEP 显示：默认使用中等清晰度网格，避免粗网格长期显示导致画质发糊；复杂模型旋转时保持边线和静态画质一致，并可隐藏同域内部边。
- 模型展示区域右上角会显示最近渲染窗口的 `FPS`，用于观察旋转、缩放和复杂模型查看时的实际渲染帧率；静止后会用一次性 idle 刷新归零，不会持续空转重绘。
- 模型展示区域左下角会显示 CAD 风格的 view cube + 彩色 `XYZ` 方向标；主视图前景层会在 STEP 文件真实全局原点 `(0,0,0)` 显示一组 `XYZ` 坐标基准，带原点球、粗箭头、负方向短轴和 3D 标签，且不参与拾取或初始相机适配，避免打开模型时被坐标轴拉远缩小。
- 选择：支持零件、Solid、Face、Edge、特征。鼠标悬停红色预高亮，选中黄色高亮；左键拖动旋转不会触发选择；悬停和普通点选只做轻量拾取，不触发完整特征识别。
- 同域面：同域合并仍用于编辑计划、扫描候选、历史定位和必要的模型修复；普通交互不再实时扫描整片同域区域。
- 编辑：偏移、面内长度/面内宽度、中心、孔径/半径、孔/槽轴心、槽宽、槽深、弧长、弧角、开口角、总长度和中心距、盲孔/盲槽深度、凸台直径/半径/高度/轴心、普通完整圆柱高度、已有圆角半径/圆弧长度、简单等半径圆角链半径/圆弧长度、已有等距倒角距离、圆锥参考半径/直径/半角、球面半径/直径(缩放特征)、环面主/小半径或直径(缩放特征)、Edge圆角、Edge倒角、圆Edge半径/直径、椭圆Edge主半径/小半径、壳体厚度、修改Edge长度、直线Edge起点/中心/终点坐标、零件/Solid 平移和旋转。Face 面积作为诊断结果只读展示。
- 编辑语义：Face 的偏移、面内长度/面内宽度和中心通过 `建模意图` 选择“拉伸/切除”“局部重建”“移动特征”或“缩放特征”；面积不作为特征参数表里的驱动变量。圆锥 Face 会优先区分简单圆锥解析重建、嵌入式锥孔局部重切和复杂兜底整体缩放；孔/槽、凸台、盲孔/盲槽、壳体、圆角和 Edge 长度也会通过 `建模意图` 或计划策略说明本次修改会局部重建、拉伸/切除、移动还是整体缩放。
- 恢复：编辑前快照、后台执行、失败回滚、撤销/重做、差异预览、热力图和差异报告。
- 导出：完整模型、零件、Solid、Face、特征区域和 Edge，导出前做基础质量检查。

### 编辑语义

所有几何参数修改都必须先明确语义、建模意图、执行影响和风险。修改 Face、孔、槽、圆角、凸台、Solid 或 Edge 时，都不能只看“目标值能不能算出来”；要区分 Face 拉伸/切除、切削补料、特征重建、局部形变、端面移动、对象平移、整体缩放等不同策略，并在确认窗口、属性提示或操作历史里尽量说明本次采用的策略。Edge 的 `长度` 行已经通过 `建模意图` 提供显式改法选择；Face 当前把 `偏移`、`面内长度`、`面内宽度` 和 `中心` 显示为单行属性，并通过 `建模意图` 下拉框表达“拉伸/切除”“局部重建”“移动特征”或“缩放特征”；面积只作为诊断结果展示。孔/槽直径和半径也通过 `建模意图` 区分“局部重切/重建孔壁”和“缩放所属对象”；凸台直径、半径、高度和轴心也通过 `建模意图` 区分“局部重建/端盖拉伸/切除/移动凸台”和“整体缩放/移动所属对象”；普通完整圆柱的直径、半径和高度也通过 `建模意图` 区分“兜底重切/端盖拉伸/切除”和“整体缩放所属对象”；槽宽、槽深和弧长也通过 `建模意图` 区分“局部重建槽”和“缩放所属对象”；盲孔/盲槽深度也通过 `建模意图` 区分“局部切削/补料”和“轴向缩放所属对象”；壳体厚度也通过 `建模意图` 区分“局部拉伸/切除当前壳体平面”和“沿厚度方向缩放所属对象”；已有圆角半径/弧长和简单等半径圆角链半径/弧长也通过 `建模意图` 区分“移除并重建圆角”和“整体缩放所属对象”；孔、槽的轴心坐标已经开始区分“移动/重建局部特征”和“平移所属对象”；孔、槽、凸台、盲孔/盲槽深度、壳体厚度现在会显示并记录当前采用的建模意图，后续还要继续把更多多语义场景做成用户可选策略。

必须记住：用户不是只要“数值改掉”，而是要选择建模意图。正方体改一条 Edge 只是例子，实际要求覆盖所有对象：用户应该能选择只改当前边、移动端面/保持垂直、固定某些边/点、让哪些相邻几何跟随变化，或整体缩放/重建所属对象。Face、孔、槽、凸台和圆角也要按同样思路设计。当多种结果都合理时，不要让程序暗自决定；要把“改法、约束、影响对象、跟随关系”做成当前选中对象里的策略行、下拉框或清晰按钮，并用普通用户能理解的话解释。

### 修改Edge长度

这是当前继续深入的功能，但仍是 B-Rep 结果几何编辑，不是参数化历史恢复。

当前支持的长度修改策略：

1. `auto`：自动策略。按局部边形变、端面拉伸/切除、相邻圆柱直径、几何缩放的顺序寻找可用路径。
2. `local-edge-only-deform`：只改当前Edge。直线Edge位于简单全平面多面体时，只移动被选Edge的端点并重建所属Solid/特征。对立方体测试模型，默认固定起点移动终点；如果 `长度基准` 选择 `中心`，才会两端各移动一半以保持 Edge 中心不动。相邻面会自然变形，四点非平面面会优先重建成连续曲面，而不是把整个正方体缩放成长方体，也不会默认拆出面内对角线。
3. `move-edge-end-plane-by-push-pull`：移动端面/保持垂直。尝试找端点附近、方向匹配的平面端面，把改边长转成端面拉伸/切除；端面和相关边跟随移动。计划阶段会确认当前 Edge 的直接相邻面和移动端面都是可验证平面，执行后会反查侧面与端面仍保持垂直、侧面之间的平行/垂直关系没有丢失；对正方体会更像变成长方体。
4. `resize-adjacent-cylinder-from-circular-edge-length`：圆形/圆弧Edge尝试复用相邻圆柱孔/槽或凸台直径编辑。
5. `scale-owning-shape-from-edge`：缩放所属对象。当前界面主要对直线Edge和圆Edge开放该长度语义；圆边会优先用相邻圆柱或径向缩放处理。椭圆边改用主半径/小半径入口，B-spline / Bezier 等复杂曲线边暂不作为稳定长度入口，避免高风险 fallback 误导用户。

直线Edge起点/终点/中心坐标编辑是另一类显式语义：`local-edge-endpoint-deform` 和 `local-edge-center-deform` 会在简单全平面多面体上移动端点或整条Edge，并重建周边平面。

确认窗口和操作历史里要尽量记录策略、目标范围、目标Edge长度、基准、移动端点、重建面数和风险，方便用户判断结果是否符合预期。

最近一次基线验证：在 `assets/models/cube_10mm.step` 上选第一条直线Edge，将 10mm 改为 15mm，计划策略为 `local-edge-only-deform`，内存执行成功。执行后边长分布为 `10:9, 11.1803:2, 15:1`，Face 数保持 `6 -> 6`，Edge 数保持 `12 -> 12`，说明没有整体拉成长方体，也没有再把非平面四边面拆成两张三角半面。

移动端面基线验证：在同一个立方体模型上将第一条 10mm 直线 Edge 改为 15mm，并强制选择 `move-edge-end-plane-by-push-pull`、`keep-start`，内存执行成功。执行后 Face 数仍为 6、Edge 数仍为 12，边长分布为 `10:8, 15:4`，并通过 `Planar relation check: ok` 反查侧面、端面和目标 Edge 的一级平面关系，说明相关端面和同向边一起移动，结果更接近长方体语义。

Face 局部移动基线验证：在 `assets/models/cube_10mm.step` 上选上表面 Face，将中心从 `(5, 5, 10)` 移到 `(7, 5, 13)`，计划策略为 `local-face-only-deform`，内存执行成功。执行后仍是 1 个 Solid、6 个 Face、12 条 Edge、8 个 Vertex，说明只移动了当前 Face 的 4 个顶点并重建相邻平面，不是平移整个所属对象。

Face 一级关系基线验证：在 `assets/models/cube_10mm.step` 上选上表面 Face，`face_first_level_topology()` 会返回 `topology_relation_depth=1`、4 条边界 Edge、4 个边界 Vertex、4 个共享边相邻 Face，并明确二级/三级关系暂不递归传播。将上表面中心沿 Z 方向从 `10` 移到 `12` 后，4 个一级侧面中心 Z 从 `5` 变为 `6`，二级底面中心 Z 仍为 `0`，说明当前局部 Face 编辑只处理一级共享边拓扑。

Face 偏移基线验证：在 `assets/models/cube_10mm.step` 上选一个平面 Face，将 `偏移` 正向或负向改变 `1mm`。`局部重建` 会走 `local-face-plane-offset-deform`，移动当前 Face 顶点并重建相邻面；`移动特征` 会走 `translate-owning-shape-from-plane-offset`，整体平移所属对象且所有面尺寸保持不变；`拉伸/切除` 会走 `push-pull-planar-face`，正向执行加料，负向执行切削；`保持关系` 会走受限的 `push-pull-planar-face-keep-relations`，要求一级相邻平面关系在执行前可验证、执行后可反查。四条路径都会验证目标平面中心位置，但结果形态不同，不能混为一个“偏移”操作。

Face 面积后端基线验证：面积是结果变量，不再显示为特征参数表里的驱动行；后端仍保留 `local-face-area-only-deform` 等历史回归，用来确认旧路径不会破坏 B-Rep、逻辑 ID 和结果校验。

Face 局部面内长度/面内宽度基线验证：在 `assets/models/cube_10mm.step` 上选一个 10mm x 10mm 平面 Face，将 `面内长度` 或 `面内宽度` 的建模意图设为 `局部重建` 并从 `10` 改为 `15`，计划策略分别为 `local-face-width-only-deform` / `local-face-height-only-deform`，内存执行成功。执行后能检测到目标尺寸的平面 Face，说明它只沿当前 Face 的一个平面内方向缩放顶点，不是整体拉成长方体。

Face 整体面内长度/面内宽度基线验证：在 `assets/models/cube_10mm.step` 上选一个 10mm x 10mm 平面 Face，将 `面内长度` 或 `面内宽度` 的建模意图设为 `缩放特征` 并从 `10` 改为 `15`，计划策略分别为 `axis-scale-owning-shape-from-face-width` / `axis-scale-owning-shape-from-face-height`，简单全平面实体优先使用 `planar-rebuild`。内存执行成功后仍是 1 个 Solid、6 个 Face、12 条 Edge、8 个 Vertex，并能检测到多个面积 `150` 的平面 Face，说明所属特征沿该面内方向整体跟随变化，同时避免通用仿射把平面盒子变成样条面。

Face 面积结果校验：表格不再要求用户输入目标面积；面积用于诊断信息、历史差异和后端结果校验，避免把结果变量伪装成直接可控的设计参数。

Face 中心基线验证：在 `assets/models/cube_10mm.step` 上选一个平面 Face，将中心按 `(2, 0, 3)` 偏移。`局部重建` 会走 `local-face-only-deform`，当前 Face 被移到目标中心并重建相邻面，Face 自身尺寸保持约 10mm x 10mm；`移动特征` 会走 `translate-part`，整个所属特征平移，所有面尺寸保持 10mm x 10mm。

孔/盲孔局部重建基线验证：`scripts/verify_hole_resize.py` 会临时生成一个通孔板件和一个盲孔块体。当前验证通过六条孔修改路线：通孔孔径 `6 -> 8`、通孔孔径 `6 -> 4`、通孔轴心偏移 `2mm`、完整通孔封堵、盲孔深度 `6 -> 8`、盲孔深度 `6 -> 4`。封堵会检查补料后仍是单 Solid、孔候选消失，并且体积接近完整板件；孔径缩小、孔轴心移动、封堵和盲孔变浅都会先补旧孔/旧底部再重切或补料；这些孔内补料 Fuse 必须关闭 OCCT glue，否则可能只生成一个插在孔里的独立圆柱 Solid，而不是和主体真正合并。

圆柱凸台局部重建基线验证：`scripts/verify_boss_resize.py` 会临时生成一个底板加圆柱凸台的 STEP。当前验证通过四条凸台修改路线：凸台直径 `6 -> 8`、凸台直径 `6 -> 4`、凸台高度 `5 -> 7`、凸台轴心偏移 `2mm`。直径缩小和轴心移动会先移除旧凸台包络，再按目标直径或目标轴心补新凸台；凸台补料/重建 Fuse 和旧包络 Cut 都必须显式关闭 OCCT glue，否则旧凸台可能没切掉，或补出的凸台变成独立 Solid。验证脚本会断言修改后仍是单 Solid，并且直径/轴心修改不会顺手改变凸台高度。

槽/半孔局部重建基线验证：`scripts/verify_slot_resize.py` 会临时生成一个 30 x 20 x 10 的块体并在上表面切出半径 3 的半圆槽，还会生成一个 40 x 24 x 6 的长圆槽板件。当前验证通过八条局部槽修改路线：槽宽 `6 -> 8`、槽深 `3 -> 4`、弧长 `9.42478 -> 12`、弧角 `180° -> 126.051°`、半圆槽轴心偏移 `1mm`、长圆槽整槽轴心偏移 `1mm`、槽孔总长度 `16 -> 20`、两端中心距 `10 -> 14`。槽宽/槽深/弧长会保持当前圆弧角度并换算目标圆柱直径；弧角会先补旧扇形槽，再按目标角度重切；半圆槽轴心会先填旧槽再按同尺寸切新槽，并丢弃极小布尔毛刺；长圆槽轴心会填旧胶囊槽再整体切到新位置；槽孔总长度和中心距会保持槽宽不变并调整两端中心距。槽扇形和长圆槽胶囊工具体必须使用真实圆弧边拉伸，不能用多边形近似，否则结果会变成小平面，后续识别不到目标圆柱槽面。

Edge 圆角/倒角基线验证：`scripts/verify_edge_round_chamfer.py` 会临时生成普通盒子、已有圆角盒子、已有倒角盒子和圆角链盒子。当前验证通过十二条路线：直线 Edge 新增圆角半径 `1`、对称倒角距离 `1`、不等距倒角 `0.8 / 1.2`、距离+角度倒角 `1 / 45°`、已有圆角半径 `1 -> 1.5`、已有圆角弧长 `2.35619`、已有等距倒角距离 `1.5 -> 2.0`、简单等半径圆角链半径 `1 -> 1.5`、简单等半径圆角链弧长 `2.35619`、四面连通同半径圆角链半径 `1 -> 1.5`、五面同半径复杂长链识别/计划阶段阻止、变半径圆角链识别/计划阶段阻止。已有简单圆角和简单等半径圆角链修改走 defeature + refillet；已有简单倒角修改走 defeature + rechamfer；圆角弧长会按当前圆弧角换算成目标半径；普通 90° 圆角恢复出的锐边距离圆角轴线约 `sqrt(2) * R`，候选搜索半径需要覆盖这个距离；复杂同半径长链、变半径圆角链、大链式 blend 和复杂角部补面暂不尝试重建，避免进入高风险 blend 计算。

Edge 隔离执行基线验证：`scripts/verify_edge_isolated_edit.py` 会通过真实 isolated worker 请求覆盖 Edge 长度、端点/中心移动、圆形 Edge 相邻轴心移动、椭圆 Edge 主半径、Edge 圆角、三类倒角、已有圆角半径、简单等半径圆角链半径和已有简单倒角距离修改。这个脚本的目标不是替代内存执行套件，而是确认 UI 交给 worker 的操作名和参数能在子进程里独立完成，避免危险 OCCT 倒圆、倒角或局部重建卡死主程序。

壳体厚度基线验证：`scripts/verify_shell_thickness_resize.py` 会临时生成 `30 x 20 x 2` 的薄板。当前验证通过局部和整体两种路线，并在 Face 专项套件里同时覆盖厚度 `2 -> 3` 和 `2 -> 1`。`拉伸/切除` 会保持相对面不动，`缩放特征` 会保持厚度中心基本不动。

解析曲面基线验证：`scripts/verify_analytic_surface_resize.py` 会临时生成圆锥、球和环面。当前验证通过五条路线：简单圆锥参考半径 `4 -> 5`、简单圆锥半角 `11.3099° -> 16°`、球面半径 `5 -> 6.25`、环面主半径 `8 -> 10`、环面小半径 `2 -> 3`。球面和环面缩放后仍能识别为解析面；简单圆锥优先解析重建，嵌入式锥孔/沉孔的半角和参考半径由 `scripts/verify_cone_semi_angle_isolation.py` 覆盖局部重切与隔离执行；常用测试模型里的复杂浅锥/拔模面 `1° -> 10°` 和 `1° -> 50°` 会被提前禁用或阻断，避免生成无效 B-Rep。

椭圆Edge基线验证：`scripts/verify_ellipse_edge_resize.py` 会临时生成一个 5 x 2 的椭圆面。当前验证通过两条路线：主半径 `5 -> 7.5` 时小半径保持约 `2`，小半径 `2 -> 3` 时主半径保持约 `5`。执行路径为 `ellipse-edge-major-axis-affine` 或 `ellipse-edge-minor-axis-affine`；刷新后 OCCT 可能把解析 ellipse 变成 B-spline，所以脚本用主/小轴采样半径校验几何结果。

内部后备基线验证：历史套件仍保留椭圆Edge通用长度缩放和圆边变换后 B-spline 长度缩放的几何回归，用来约束后端 fallback 不退化；但这不代表界面把椭圆长度或 B-spline 长度作为当前稳定参数开放，用户入口仍以椭圆主/小半径和明确的直线/圆Edge语义为准。

后置校验基线：修改Edge长度完成后，结果消息会包含 `match`、`nearest_edge`、`nearest_length`、`target_error`、`relative_error`、`endpoint_error` 和校验范围；局部边形变、端面拉伸/切除和几何缩放会优先按预期端点匹配目标Edge，长度匹配只作为兜底。操作历史摘要也会带上 `actual_length` 和 `target_error`，用于提醒用户真实 B-Rep 刷新后的最近Edge长度是否贴近目标值。

### 当前边界

- STEP 通常不包含可稳定恢复的 CAD 建模历史；不要承诺“任意场景都能像原 CAD 参数一样修改”。
- 复杂槽、复杂凸台、复杂圆角链、带内孔Face、曲面混合拓扑和大装配仍可能失败。
- 布尔和 ShapeFix 可能耗时或失败，编辑动作应继续走后台 worker、预览和失败回滚。
- 操作历史是本软件加载后的编辑留档，不是 STEP 原始建模历史。

### 提交与忽略

- `assets/models/*.step` 中用于测试的模型可以提交。
- `assets/screenshots/` 默认忽略。
- 运行导出的 `*_edited.step`、`*_export.step`、`*_diff_*.txt`、`*_operation_history.json` 默认不提交。
- 不要把 `environment.yml` 移进子目录，它留在根目录更符合 Conda 用户预期。
- 工作区可能有用户改动，不能随意 `git checkout --`、`git reset --hard` 或回滚不相关文件。

### 2026-08-18 geom_extract.step 性能记录

- `ICEPAK-NATURAL.stp` 速度快不是因为有原 CAD 建模历史；它仍是 STEP/B-Rep 结果几何。`geom_extract.step` 慢的主要原因是模型规模更大，约 1800 个 Face、近 5000 条 Edge，且 Face594 是带多个内孔的大平面端盖，一级边界和相邻面更多。
- 大模型点选阶段必须保持轻量：当前 Face / Feature 选择只生成快速一级边界摘要，完整一级关系事实图放到编辑计划或后台任务中计算，避免点一个 Face 就同步深扫全模型。圆柱面 quick 选择只合并直接相接的同圆柱碎面，不触发 Analysis Situs 或内部孔组识别图；超过 1000 个 Face 的模型默认不在 UI 选择路径同步构建内部全模型识别图。即使用户把“特征探测级别”切到相邻/二级，大模型点击选择也会先按“只识别当前特征”处理，深层识别必须走显式扫描或后台任务。
- Face594 `偏移 57.5 -> 70` 的基线：`face_info` 从约 10.5s 降到约 0.9s，`push_pull_plan` 从约 9.5s 降到约 1.5s，内存 `push_pull_face` 约 3.5s-5.5s；即使 SCDM cache 识别出 `face.offset`，这类大模型多内孔平面位置调整也会优先使用本软件已验证的本地 OCCT 一级边界重建，避免退回 100s 级别的外部后端/导出/启动/回读慢路径。2026-08-18 复测：Face594 核心 UI job 约 9.1s，其中快照/统计约 2.0s、几何计算约 3.7s、校验约 2.2s、面显示约 1.2s；独立后台几何进程单次约 12.6s，但旋转查看更不容易被 Python/OCCT worker 抢占。
- 大模型编辑后的逻辑 Face ID 保持必须走结果消息快路径：如果子进程返回 `nearest_face` / `verified_face` 且该 Face 通过目标位置回测，直接把旧逻辑 ID 绑定到这个结果 Face；不要再同步扫描全模型寻找同平面候选。2026-08-18 发现 Face594 isolated UI job 曾有约 75s 花在结果 Face 映射兜底扫描，修复后同一路径总耗时约 11.8s，`result_face_mapping` 约 0.013s。
- 大模型显示阶段：先后台读取主面片，默认跳过全量 Edge overlay；超过 1000 个 Face 或 2500 条 Edge 的模型首屏和编辑后显示会使用交互网格预算，`geom_extract.step` 主显示三角面从约 11 万降到约 4.7 万，旋转和点选优先流畅，局部几何校验仍使用 OCCT B-Rep 而不是显示网格。编辑完成后的操作历史定位优先读取结果消息中的 `verified_face` / `nearest_face`，fallback 只做轻量平面位置查询，不再在 UI 主线程逐个 Face 调完整 `face_info()`；Face594 定位从 120s 级超时降到 0s 级。普通导入大模型后会延后 SCDM/Analysis Situs 全模型预热，优先保证旋转和点选；SCDM 修改结果回读校验仍会强制刷新 cache。旋转相机时仍会临时隐藏已有边线 overlay，停止后恢复，保证画质不降的同时减少交互卡顿。
- 大模型交互阶段不再把所有 UI 辅助工作绑到点选上：关系式补全只在公式输入框获得焦点或正在输入时刷新，避免每次点 Face 都重建数千个 Face/Edge 候选；左键按下会记录按下位置的对象，背景开始拖动/旋转后即使松手落在模型上也不会误选；旋转期间会临时隐藏选择高亮和拾取点覆盖层，松手后恢复，减少透明 overlay 对帧率的影响。

### 2026-08-03 工程师返还代码合并记录

- 已合并特征参数策略：Feature 模式优先显示可靠的独立尺寸，不再把面积、中心、包围盒、底层曲面参数直接伪装成设计特征。
- 已合并矩形平面轮廓识别：规则四直边平面可以识别为矩形平面、矩形棱柱、矩形口袋或矩形凸台候选，并估算长度、宽度、中心和高度/深度；规则矩形凸台/口袋已开放长度、宽度、中心和高度/深度修改，多台阶矩形凸台的顶层规则台阶也可按独立矩形凸台编辑，中间过渡面会识别为复杂多台阶凸台并快速阻止。长宽和中心移动会局部重建矩形包络，当前不在一次编辑中交换长宽方向，也不把中心沿高度/深度方向移动。
- 已合并关联特征扫描：选中一个 Face 时，可在有限共享边拓扑范围内关联附近孔、槽、凸台、圆角、圆锥/球/环面等候选特征，并把关联特征的可改尺寸显示到当前特征参数表中。
- 已合并显示质量修复：精细网格只重点细化解析曲面；法线平滑不再合并不同 B-Rep Face 的边界点，减少平面被相邻曲面污染后发黑的问题。
- 新增验证脚本：`scripts/verify_feature_parameter_policy.py`、`scripts/verify_prismatic_feature.py`、`scripts/verify_associated_features.py`；其中 `verify_prismatic_feature.py` 会同时覆盖矩形凸台/口袋长度/宽度、中心、高度/深度、多台阶矩形凸台顶层台阶编辑和中间过渡面快速阻止。