feat: 完善 STEP 一级参数化编辑识别与关系式建模

README.md

@@ -41,6 +41,12 @@ python-occt
 │   ├── features.py
 │   │   └── 特征识别和编辑计划，比如孔、槽、凸台、圆角、壳体、解析曲面
 │   │
+│   ├── recognition_graph.py
+│   │   └── 内部 Face 几何图和通孔拆面识别缓存，记录平面/圆柱、邻接、共面、平行、垂直、同轴等基础关系
+│   │
+│   ├── asitus_bridge.py
+│   │   └── Analysis Situs 孔组识别 CLI 桥接，把外部识别到的孔 Face 组映射回 Python/Qt Face 编号
+│   │
 │   ├── operations.py
 │   │   └── 真正的几何编辑实现，比如拉伸/切除、孔径、孔深、边长、圆角、倒角
 │   │
@@ -75,6 +81,44 @@ python-occt
     └── 仓库自带测试 STEP 模型
 ```
 
+## Analysis Situs 接入状态
+
+一句话状态：还没有全量接完；当前已经完成“孔组识别桥接 + AAG 轻量关系摘要 + 几何关系摘要”这一步，能把 Analysis Situs 识别出的拆面圆柱孔组用于整孔高亮、参数表和一级关系计划，也能把外部 AAG 的 Face、邻接、角度类型、共面、同轴、平行、垂直和相切摘要缓存到 `StepModel`，并作为 `recognition_graph.py` 的 `external_*` 关系证据；但还没有把它的完整 AAG/特征分析能力接成通用识别引擎。
+
+当前已完成：
+
+- `[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 关系图作为主识别数据源；现在已经消费孔组、AAG 邻接/角度摘要和基础几何关系摘要，并用它们增强孔、槽、凸台、圆角候选的置信度和排序，但编辑计划的主判断仍以本项目现有 `StepModel` / `recognition_graph.py` 为准。
+- `[ ]` 还没有用 Analysis Situs 直接识别倒角、壳体、阵列孔或装配约束；槽、凸台和圆角当前只是辅助识别提示，不等同于外部特征引擎直接给出的可编辑特征。
+- `[ ]` 还没有让 Analysis Situs 的共面、同轴、平行、垂直、相切关系直接驱动一级/二级编辑计划；目前它们只作为外部证据增强识别图和置信度，真正能不能改仍由现有 `StepModel`、`recognition_graph.py`、编辑计划和结果守门共同决定。
+- `[ ]` 还没有把 Analysis Situs CLI 编译产物纳入打包流程；本地没有 `recognize_holes.exe` 时，程序只走内部识别，不会报错退出。
+- `[ ]` 还没有做 pybind11 直连；当前是 Python 调外部 CLI，优点是隔离稳定，缺点是启动和 JSON 交换有额外开销。
+
+下一步接入顺序：
+
+1. 把 `tools/asitus_probe` 的构建步骤写入 Windows 打包流程，让交付包能自带可用的 `recognize_holes.exe` 或明确跳过外部识别。
+2. 继续扩展倒角、壳体、阵列孔等候选的辅助识别提示，仍然只参与“识别和排序”，不直接绕过一级编辑守门。
+3. 最后再评估是否需要 pybind11 直连；在稳定性没证明之前，CLI 隔离比直接把 C++ 库塞进主进程更安全。
+
 ## 怎么运行
 
 你第一次配置或运行这个项目时，可以按下面步骤来。命令默认在 Windows PowerShell 里执行。
@@ -284,8 +328,12 @@ STEP/B-Rep 参数化编辑主线
 │   │   └── 孔壁消失，孔口补面有效，结果保持单 Solid。
 │   ├── [x] [锥孔/沉孔 -> 局部重切或提前阻止]
 │   │   └── 简单圆锥解析重建，嵌入式锥孔/沉孔优先局部重切；复杂浅锥、螺纹孔和组合孔提前解释为受限能力。
-│   └── [x] [孔编辑范围 -> 单个稳定孔特征]
-│       └── 当前只承诺单个孔/锥孔/沉孔的一级关系修改；孔组、阵列和同尺寸孔联动放到第 8 阶段。
+│   ├── [x] [孔编辑范围 -> 单个稳定孔特征]
+│   │   └── 单孔、锥孔、沉孔的一级关系修改已经作为孔阶段基线。
+│   ├── [~] [Ctrl 多选完整孔 -> 批量孔径 / 位置偏移]
+│   │   └── 第一版支持多个完整圆柱孔统一改孔径或按同一偏移移动；等距、阵列、同尺寸联动关系式仍放到第 8 阶段。
+│   └── [~] [关系式 -> FaceID.参数 = 表达式]
+│       └── 第一版先把关系式作为“目标值生成器”：用户输入 `Face87.直径 = Face85.直径` 或 `Face87.位置 = Face85.位置 + (0, 0, -3.5)`，程序先计算并回填当前参数表目标值，再复用现有一级编辑执行；跨对象批量队列、等距/阵列/同尺寸联动和持久约束求解后续再扩展。
 │
 ├── 3. 槽 / 长圆孔，从孔扩展到组合切除特征
 │   ├── [x] [槽宽 -> 改槽宽]
@@ -398,6 +446,19 @@ STEP/B-Rep 参数化编辑主线
         └── 当二级/三级关系互相冲突时，列出冲突原因，允许只执行一级或扩展传播，不强行硬改。
 ```
 
+## 关系式实现流程
+
+当前关系式先按“可见公式 + 目标值生成器”推进，不把第一版伪装成完整 CAD 约束求解器。
+
+1. `[~]` 公式输入与显示：左侧 `特征参数` 下方增加 `关系式` 区域，只提供 `添加公式` 和已有公式列表。公式面向用户显示为 `Face87.直径 = Face85.直径`、`Face87.位置 = Face85.位置 + (0, 0, -3.5)` 这类通用 `对象ID.参数` 形式，不使用“孔1/孔2”这类临时命名。
+2. `[~]` 公式补全：输入 `Face87.` 后，按当前选中对象、当前多选对象和可见参数表提供参数候选；第一版优先覆盖 `直径`、`半径`、`位置`、`位置X/Y/Z`、`偏移`、`面内长度`、`面内宽度`、`长度` 等已经能稳定显示或计算的参数。
+3. `[~]` 公式计算：点击 `参数化建模` 时，先计算启用的关系式，把结果回填到当前可见参数表目标值；随后继续走现有单参数或多参数批量建模执行链路。第一版不直接跨多个未显示对象开新编辑任务。
+4. `[~]` 简单 Face ID 追踪：公式保存时记录引用 Face 的逻辑 ID 和轻量几何签名；编辑成功后，如果旧 `Face87` 在新模型中能唯一映射到新 `Face90`，就自动把公式显示更新为 `Face90.参数`。如果找不到、找到多个、Face 被拆分/合并或参数不再存在，则把公式标为失效，提示用户重新选择。
+5. `[ ]` 跨对象批量执行：后续把多个公式目标拆成执行队列，例如先算 `Face87.直径`、`Face92.直径`，再按对象逐个切换选择并执行已有建模动作；失败时停在明确对象和原因。
+6. `[ ]` 循环依赖和冲突处理：后续检查 `A = B`、`B = A`、同一目标被多个公式覆盖、同一参数既手工改又被公式驱动等冲突，给出可读提示。
+7. `[ ]` 持久化：后续把公式、对象签名、目标参数、建模意图和失效状态保存到项目配置或组件配置里，重新打开模型后能尝试恢复。
+8. `[ ]` 复杂拓扑追踪：后续再处理 `原 Face -> 多个新 Face`、`多个原 Face -> 一个新 Face`、特征删除、阵列孔重编号、装配 occurrence 等情况。
+
 ## 几何修改语义原则
 
 所有可修改参数都要先明确“这次修改到底代表什么”，不能只因为程序能算出一个结果就直接放行。这个原则适用于 Face、Edge、孔、槽、凸台、圆角、Solid 和整件特征，不是 Edge 专属。比如修改 Face 可能代表 Face 拉伸/切除、局部补料、局部切削、平移所属对象或整体缩放；修改孔/槽可能代表重切侧壁、移动轴心、调整端面深度或重新配对长圆槽端部；修改圆角可能代表移除旧圆角后重建；修改 Edge 可能代表只动这条边、移动相关端面，或者高风险地缩放所属几何。
@@ -1248,6 +1309,8 @@ 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   # 当前默认测试模型
@@ -1298,6 +1361,7 @@ pythonocc-step-editor/
     verify_property_editor_specs.py # 验证属性表不会把通用 Face 编辑混入孔/槽/凸台/圆角/解析曲面特征
     verify_property_card_editor_ui.py # 验证参数表 UI 能构建、检测目标值修改并展开完整参数
     verify_parametric_component_export.py # 验证导出参数会生成嵌入参数列表的组件 main.py，组件目录不额外写 data.json
+    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 并验证槽宽/槽深/弧长/弧角/半圆槽轴心/长圆槽轴心/总长度/中心距修改
@@ -1453,7 +1517,8 @@ git diff --check
 - `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 拆成两片的同域圆柱孔会按整孔高亮、按整孔生成孔径计划，并能通过隔离 worker 完成 `0.5 -> 0.3` 的孔径缩小；模型文件不存在时自动跳过。
+- `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 操作计划会延后完整几何计划，避免按钮点击阶段先卡住主界面。