feat: 完善 STEP 编辑器最小系统和稳定性

README.md

@@ -2,7 +2,15 @@
 
 这是一个基于 Python、pythonocc-core/OCCT、VTK 和 PySide6/Qt 的 STEP 模型查看、选择、局部编辑与导出原型。
 
-当前项目目录下的 `geom_extract.step` 是默认测试模型。程序入口是 `main.py`。
+仓库里的 `assets/models/geom_extract.step` 是默认测试模型。程序入口是 `main.py`。
+
+## 快速读懂
+
+- 这是一个 STEP B-Rep 结果几何查看和受限局部编辑工具，不是完整参数化 CAD 内核。
+- 主入口是 `python main.py`；默认模型是 `assets/models/geom_extract.step`；立方体测试模型是 `assets/models/cube_10mm.step`。
+- 左侧操作面板按工作流排列：STEP 文件、模型结构树、鼠标选择模式、按 ID 选择、编辑、导出、显示、测量、可编辑对象、圆柱面候选、操作历史和对象信息。
+- 局部编辑会先做计划、风险提示、预览和后台执行；失败时会尽量回滚，成功后进入撤销/重做历史。
+- 新开 Codex 聊天框继续开发时，只需要 Codex 阅读 README 末尾的“Codex 项目记忆”；普通开发者可以忽略那一节。
 
 ## 最终要实现什么
 
@@ -10,45 +18,45 @@
 
 - 加载 `.step` / `.stp` 模型文件。
 - 展示三维模型，支持旋转、缩放、平移。
-- 读取 STEP 中的零件、装配、solid 等结构。
-- 用户可以选择零件、solid、面、边和局部几何特征。
+- 读取 STEP 中的零件、装配、Solid 等结构。
+- 用户可以选择零件、Solid、Face、Edge 和局部几何特征。
 - 用户可以做基础测量，例如把两个拾取点或对象中心设为 A/B 并计算距离。
 - 程序可以识别孔、圆角、凸台、槽、壳体局部区域等候选特征。
-- 用户可以修改可控的局部特征，比如平面推拉、孔径调整、槽/半孔宽度调整、盲孔深度调整、凸台直径调整、边倒圆、边倒角和第一版直接边长调整。
-- 用户可以撤销/重做修改，避免实验性编辑一步做坏。
+- 用户可以修改可控的局部特征，比如平面推拉、孔径调整、槽/半孔宽度调整、盲孔深度调整、凸台直径调整、Edge倒圆、Edge倒角和修改Edge长度。
+- 用户可以撤销/重做修改，避免一步编辑做坏。
 - 用户可以导出修改后的完整模型。
 - 如果 STEP 文件里存在多个零件，用户可以只导出选中的某个零件。
 
 需要注意：STEP 文件通常是 B-Rep 几何数据，不是带完整建模历史的参数化 CAD 原文件。所以“随便选一条边改长度”不一定能稳定实现，实际会转化成更可靠的操作，比如移动某个面、重切某个孔、调整某个圆角等。
 
-## 第一版先实现什么
+## 最小系统先实现什么
 
-第一版目标是先把完整工作链路打通：
+最小系统目标是先把完整工作链路打通：
 
 - 能打开 STEP。
 - 能显示模型。
 - 能读取 STEP 中的零件/装配标签。
-- 能选择 part、solid、face、edge。
+- 能选择 Part、Solid、Face、Edge。
 - 能显示选中对象的基本属性。
 - 能高亮选中对象。
 - 能导出整个当前模型。
 - 能导出选中的零件。
-- 能撤销/重做实验性编辑。
+- 能撤销/重做编辑。
 - 先实现少量可控编辑操作，用于验证后续特征编辑路线。
 
 ## 现在已经实现了什么
 
 当前已经实现：
 
-- 默认加载 `geom_extract.step`。
+- 默认加载 `assets/models/geom_extract.step`。
 - 支持打开其他 `.step` / `.stp` 文件。
 - 打开 STEP 时会先在临时模型里完成读取和显示网格生成；失败时当前模型保持不变。
-- 使用 XCAF 读取 STEP 中的 part / assembly 标签。
+- 使用 XCAF 读取 STEP 中的 Part / Assembly 标签。
 - 模型结构树会用中文显示 STEP 里的装配、零件和实体层级，并在对应零件下面列出实体子节点。
 - 点击模型结构树中的实体子节点，可以直接选中、高亮、查看属性并用于导出该实体。
 - 使用 OCCT 读取真实 B-Rep 拓扑。
 - 使用 VTK 显示模型，并通过 PySide6/Qt 承载桌面界面。
-- 左侧操作面板按功能模块分组显示，并使用四边同色的轻量彩色边框和标题层级区分文件、选择、显示、导出、编辑、候选、历史和属性信息。
+- 左侧操作面板按功能模块分组显示，并使用四边同色的轻量彩色边框和标题层级区分文件、模型树、选择、编辑、导出、显示、测量、候选、历史和属性信息。
 - 支持选择模式：
   - Part
   - Solid
@@ -56,26 +64,26 @@
   - Edge
   - Feature
 - 鼠标悬停对象会以红色预高亮，真正选中后会以黄色高亮。
-- `Face` 模式会把属于同一几何面的连续区域一起高亮；平面会按共面且投影范围相接/重叠查找，圆柱面会按同一实体内同轴、同半径且轴向连续/重叠查找，不再要求旧段和新段必须共享同一条拓扑 edge。例如推拉后侧壁被 OCCT 拆成上下多段 face，点击任意一段时都会把整片同域区域一起高亮。
-- 推拉后程序会尽量保留侧壁面区域的 `逻辑 Face ID`：即使 OCCT 把原来的一个侧壁拓扑 face 重建成上下两段，新旧两段也会绑定回推拉前那片侧壁的逻辑 ID。属性表会同时显示 `逻辑 Face ID` 和 `拓扑 Face ID`；前者面向用户选择和按 ID 定位，后者用于调试当前 B-Rep 拓扑。
-- 操作历史会记录 `target_logical_id` 和当时的拓扑 face id。点击历史记录定位 face / feature 时，会优先用逻辑 ID 找回当前模型中的整片面区域；撤销/重做快照也会保留这层逻辑 ID 映射。
-- 鼠标选择会按当前模式做就近映射；例如 `Edge` 模式点到面时，会自动选择鼠标附近的边界 edge。
+- `Face` 模式会把属于同一几何面的连续区域一起高亮；平面会按共面且投影范围相接/重叠查找，圆柱面会按同一实体内同轴、同半径且轴向连续/重叠查找，不再要求旧段和新段必须共享同一条拓扑Edge。例如推拉后侧壁被 OCCT 拆成上下多段Face，点击任意一段时都会把整片同域区域一起高亮。
+- 推拉后程序会尽量保留侧壁面区域的 `逻辑 Face ID`：即使 OCCT 把原来的一个侧壁拓扑Face重建成上下两段，新旧两段也会绑定回推拉前那片侧壁的逻辑 ID。属性表会同时显示 `逻辑 Face ID` 和 `拓扑 Face ID`；前者面向用户选择和按 ID 定位，后者用于调试当前 B-Rep 拓扑。
+- 操作历史会记录 `target_logical_id` 和当时的拓扑Face ID。点击历史记录定位Face / Feature时，会优先用逻辑 ID 找回当前模型中的整片面区域；撤销/重做快照也会保留这层逻辑 ID 映射。
+- 鼠标选择会按当前模式做就近映射；例如 `Edge` 模式点到面时，会自动选择鼠标附近的边界Edge。
 - 支持按当前选择模式输入 ID 直接选择 Part / Solid / Face / Edge / Feature。
 - Face / Feature 按 ID 选择会优先解析 `逻辑 Face ID`。例如推拉前侧壁是 558，推拉后当前拓扑里变成 1556 和 1802，只要它们被绑定到逻辑 558，输入 558 就会选中这片面区域。
-- `鼠标选择模式` 下拉框不会响应鼠标滚轮，避免鼠标经过时误切换模式；需要点击后手动选择。
+- `鼠标选择模式` 下拉框关闭时会把鼠标滚轮交还给左侧滚动面板，避免鼠标经过时误切换模式；打开下拉列表后仍可用滚轮滚动选项。
 - `按 ID 选择` 会在输入框和 `选择` 按钮之间同步显示当前鼠标选择模式。
-- `Feature` 模式现在会把点到的 face 解释为局部几何特征候选：
+- `Feature` 模式现在会把点到的Face解释为局部几何特征候选：
   - 平面会识别为可推拉平面候选。
-  - 平面会尝试查找同一 solid 内投影重叠的相对平面，用于估算薄壁/壳体局部区域厚度。
+  - 平面会尝试查找同一Solid内投影重叠的相对平面，用于估算薄壁/壳体局部区域厚度。
   - 圆柱面会识别为圆柱孔候选、槽/半孔候选、圆角/倒圆候选、凸台/外圆候选或未明确圆柱特征。
-  - 圆柱特征会先把同一实体内同轴、同半径且轴向连续/重叠的完整圆柱 face 当作同一侧壁区域，再尝试找出边界 edge、相邻 face、端面 face、开口端相邻 face 和疑似底面 face，并一起高亮相关局部区域。
-  - 槽/半孔候选会额外显示槽宽、圆弧长度、槽深估算和槽边界相邻 face。
-  - 圆角/倒圆候选会额外显示已有圆角半径估算、圆弧角度、圆弧长度和相邻支撑 face。
+  - 圆柱特征会先把同一实体内同轴、同半径且轴向连续/重叠的完整圆柱Face当作同一侧壁区域，再尝试找出边界Edge、相邻Face、端面Face、开口端相邻Face和疑似底面Face，并一起高亮相关局部区域。
+  - 槽/半孔候选会额外显示槽宽、圆弧长度、槽深估算和槽边界相邻Face。
+  - 圆角/倒圆候选会额外显示已有圆角半径估算、圆弧角度、圆弧长度和相邻支撑Face。
 - 支持显示选中对象信息，并提供 `属性表` / `原始文本` 两种查看方式：
   - 零件名称
-  - solid 数量
-  - face 数量
-  - edge 数量
+  - Solid 数量
+  - Face 数量
+  - Edge 数量
   - 面类型
   - 面面积
   - 平面法向
@@ -84,163 +92,176 @@
   - 边长度
   - 圆边半径/直径
 - 属性面板现在还会显示更多几何调试信息：
-  - part / solid 的包围盒、尺寸、体积、重心、表面积。
-  - face 的方向、面积中心、UV 参数范围、边界边数量、包围盒。
-  - 平面 face 的几何法向和按拓扑方向修正后的法向。
-  - 平面 face 的推拉向外方向、向内方向和方向判断置信度。
-  - 圆柱 face 的轴线点、轴方向、半径、直径、角度跨度、估算高度和是否接近完整圆柱。
-  - edge 的参数范围、起点、终点、长度中心、包围盒。
-  - 直线 edge 的方向，圆弧 edge 的圆心、轴线、半径和直径。
+  - Part / Solid 的包围盒、尺寸、体积、重心、表面积。
+  - Face 的方向、面积中心、UV 参数范围、边界边数量、包围盒。
+  - 平面Face的几何法向和按拓扑方向修正后的法向。
+  - 平面Face的推拉向外方向、向内方向和方向判断置信度。
+  - 圆柱Face的轴线点、轴方向、半径、直径、角度跨度、估算高度和是否接近完整圆柱。
+  - Edge 的参数范围、起点、终点、长度中心、包围盒。
+  - 直线Edge的方向，圆弧Edge的圆心、轴线、半径和直径。
 - 属性面板支持复制当前对象 ID、拾取坐标和完整信息。
 - 面/边属性查询带缓存；重复选择同一个对象会复用上次计算结果，模型编辑、撤销、重做或重新加载后缓存会自动清空。
-- 支持高亮选中的零件、solid、面、边或局部特征候选，并在鼠标悬停时用红色预览当前可选对象；普通 Face 选择会对共面平面和同轴同半径圆柱面做同域区域高亮。
-- 默认模型边线渲染会隐藏同一平面或同一圆柱面内部的拓扑分割边，也会隐藏同域区域里几何位置重复的拼接边，减少布尔推拉后新旧侧壁交界处看起来像“两块拼起来”的视觉伤疤；`显示` 面板里的 `显示同域内部边` 可以临时打开完整拓扑边线。如果按 ID 或 Edge 模式专门选中这类内部 edge，仍然可以单独高亮查看。
+- 支持高亮选中的零件、Solid、Face、Edge或局部特征候选，并在鼠标悬停时用红色预览当前可选对象；普通 Face 选择会对共面平面和同轴同半径圆柱面做同域区域高亮。
+- 默认模型边线渲染会隐藏同一平面或同一圆柱面内部的拓扑分割边，也会隐藏同域区域里几何位置重复的拼接边，减少布尔推拉后新旧侧壁交界处看起来像“两块拼起来”的视觉伤疤；`显示` 面板里的 `显示同域内部边` 可以临时打开完整拓扑边线。如果按 ID 或 Edge 模式专门选中这类内部Edge，仍然可以单独高亮查看。
 - 支持只显示当前选中对象、对准当前选中对象，并可一键恢复显示完整模型。
 - 支持两点测量：
   - 可以把当前选中对象的拾取点设为 A 或 B；如果没有拾取点，会退回使用对象中心、面积中心、长度中心、重心或包围盒中心。
   - 设置 A/B 后会显示两点距离和 X/Y/Z 方向差值。
   - 3D 视图中会显示一条青色测量线；测量结果可以复制，加载新模型时会自动清除旧测量。
-- Feature 模式会在属性表里显示特征来源 face、侧壁 face、同域圆柱范围、端面 face、疑似底面 face、开口端相邻 face、边界 edge 和当前可用操作。
+- Feature 模式会在属性表里显示特征来源Face、侧壁Face、同域圆柱范围、端面Face、疑似底面Face、开口端相邻Face、边界Edge和当前可用操作。
 - 支持导出当前完整模型为 STEP。
-- 支持导出选中的 part 为 STEP。
-- 支持导出选中的 solid 为 STEP。
-- 支持导出选中的 face / 同域面区域为 STEP；如果当前 face 与共面或同轴同半径的相邻面一起高亮，导出也会包含整片黄色区域。
+- 支持导出选中的Part为 STEP。
+- 支持导出选中的Solid为 STEP。
+- 支持导出选中的Face / 同域面区域为 STEP；如果当前Face与共面或同轴同半径的相邻面一起高亮，导出也会包含整片黄色区域。
 - 支持导出选中特征区域为 STEP。
-- 支持导出选中的 edge 为 STEP。
-- 支持导出质量检查：导出前会检查 B-Rep 有效性、solid / face / edge 数量、体积和包围盒；如果发现风险，会先弹窗确认。
-- 支持一键修复当前模型或选中零件/solid：执行 ShapeFix 和同域面/边合并，修复会进入后台编辑流程，并支持撤销/重做。
-- 导出完整模型、part 或 solid 前，会先尝试执行 ShapeFix 和同域面/边合并，减少外部 CAD 打开时出现碎面、坏体或明显拼接痕迹的概率。
-- 实验性编辑按钮会根据当前选中对象自动启用或禁用，并通过悬停提示说明为什么当前操作不可用，减少 face、edge、孔、凸台、盲孔等对象混用导致的误操作。
-- 支持扫描第一版可编辑对象：
+- 支持导出选中的Edge为 STEP。
+- 支持导出质量检查：导出前会检查 B-Rep 有效性、Solid / Face / Edge 数量、体积和包围盒；如果发现风险，会先弹窗确认。
+- 支持一键修复当前模型或选中零件/Solid：执行 ShapeFix 和同域面/边合并，修复会进入后台编辑流程，并支持撤销/重做。
+- 导出完整模型、Part 或 Solid 前，会先尝试执行 ShapeFix 和同域面/边合并，减少外部 CAD 打开时出现碎面、坏体或明显拼接痕迹的概率。
+- 编辑按钮会根据当前选中对象自动启用或禁用，并通过悬停提示说明为什么当前操作不可用，减少 Face、Edge、孔、凸台、盲孔等对象混用导致的误操作。
+- 支持扫描可编辑对象：
   - 默认扫描优先保证界面响应速度，会列出一组有代表性的候选。
   - `深度扫描` 会尝试列出更多候选，适合默认列表里没有找到目标对象时使用。
-  - 可推拉的平面 face。
-  - 可调整孔径的圆柱 face 候选。
+  - 可推拉的平面Face。
+  - 可调整孔径的圆柱Face候选。
   - 可调整槽/半孔宽度的局部圆柱孔/槽候选。
-  - 可调整盲孔深度的圆柱 face 候选。
-  - 可添加新圆角的直线 edge 候选。
-  - 可添加倒角的直线 edge 候选。
-  - 可尝试通过端面推拉调整长度的直线 edge 候选。
+  - 可调整盲孔深度的圆柱Face候选。
+  - 可添加新圆角的直线Edge候选。
+  - 可添加倒角的直线Edge候选。
+  - 可尝试直接调整长度的直线Edge候选，简单平面多面体会优先局部边形变。
   - 表格会显示当前值、状态、风险、置信度和说明。
-  - 盲孔深度候选会在列表阶段先确认疑似底面，列表里的深度值优先使用底面 face 轴向位置计算。
-  - 点击表格行会直接选中对应 face 或 edge，方便继续执行推拉、孔径调整、槽/半孔宽度调整、盲孔深度调整、边倒圆、边倒角或直接边长调整。
+  - 盲孔深度候选会在列表阶段先确认疑似底面，列表里的深度值优先使用底面Face轴向位置计算。
+  - 点击表格行会直接选中对应Face或Edge，方便继续执行推拉、孔径调整、槽/半孔宽度调整、盲孔深度调整、Edge倒圆、Edge倒角或修改Edge长度。
 - 支持列出圆柱面候选特征。
-- 圆柱候选会显示在表格中，点击候选行可以直接选中并高亮对应 face。
-- 圆柱候选可以按类型筛选：全部、孔/槽候选、圆角候选、凸柱/外圆候选、未明确分类。
-- 圆柱候选的类型下拉框不会响应鼠标滚轮，避免滚动左侧面板时误改筛选条件。
-- 圆柱候选表格会显示初步分类：
-  - `hole/groove candidate`：孔/槽一类的凹向圆柱候选。
+- 圆柱面候选会显示在表格中，点击候选行可以直接选中并高亮对应 Face。
+- 圆柱面候选可以按类型筛选：全部、孔/槽候选、圆角候选、凸柱/外圆候选、未明确分类。
+- 圆柱面候选的类型下拉框关闭时会把鼠标滚轮交还给左侧滚动面板，避免滚动面板时误改筛选条件。
+- 圆柱面候选表格会显示初步分类：
+  - `hole/groove candidate`：孔/槽一类的凹向圆柱面候选。
   - `round/fillet candidate`：小半径局部圆柱面，可能是圆角/倒圆。
-  - `boss/outer-round candidate`：凸柱/外圆角一类的外向圆柱候选。
+  - `boss/outer-round candidate`：凸柱/外圆角一类的外向圆柱面候选。
   - `cylindrical face`：暂时无法明确分类的圆柱面。
-- 圆柱候选表格会显示直径、角度跨度、估算高度和置信度。
-- 圆柱候选表格会显示 `risk`，用于提示调整圆柱孔径的风险。
-- 圆柱候选表默认列出前 60 个候选，以避免打开大模型时刷新过慢。
-- 实验性支持平面 face 推拉。
+- 圆柱面候选表格会显示直径、角度跨度、估算高度和置信度。
+- 圆柱面候选表格会显示 `risk`，用于提示调整圆柱孔径的风险。
+- 圆柱面候选表默认列出前 60 个候选，以避免打开大模型时刷新过慢。
+- 当前版本支持平面Face推拉。
 - 平面推拉会自动判断面两侧的 inside / outside，输入正数表示向外加料，输入负数表示向内切削。
 - 推拉平面会先显示半透明预览体，表示推拉方向和大致范围，然后在后台执行真实 OCCT 布尔计算。
-- 推拉平面现在会从选中 face 出发，自动查找共面且相接/重叠的相邻 face，并把它们作为同一片平面区域一起推拉。
+- 推拉平面现在会从选中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 的圆柱候选开放。
+- 推拉平面会先生成操作计划：检查距离是否为 0、方向置信度和相对Face尺寸的风险；能推拉时直接执行，不能推拉时会提示阻止原因。
+- 调整圆柱孔径也会先显示半透明预览体：红色表示切削 cutter，绿色表示缩小孔径时的补料范围；如果圆柱侧壁被拆成多段同域Face，工具范围会优先覆盖整段同域圆柱。
+- 当前版本支持盲孔/盲槽深度调整：
+  - 只对 `hole/groove candidate` 且端部类型为 `blind`、并识别到疑似底面 Face 的圆柱面候选开放。
   - 目标深度大于当前估算深度时，会沿开口到疑似底面方向用有限长度 cutter 加深切削。
   - 目标深度小于当前估算深度时，会从目标新底面到旧底面方向补料，让孔变浅。
   - 调整盲孔深度会先显示半透明预览体：红色表示加深切削范围，绿色表示变浅补料范围。
   - 孔深调整计划会记录当前深度、目标深度、变化比例、疑似底面、开口端和工具参数。
-  - 当前深度会优先使用疑似底面 face 在圆柱轴线上的位置计算；如果相邻端面找不到底面，会额外扫描同一 solid 内轴线附近的平面圆盘候选。
-- 支持第一版槽/半孔候选结构化识别：
+  - 当前深度会优先使用疑似底面Face在圆柱轴线上的位置计算；如果相邻端面找不到底面，会额外扫描同一Solid内轴线附近的平面圆盘候选。
+- 当前版本支持槽/半孔候选结构化识别：
   - 对局部圆柱形 `hole/groove candidate`，会标记为 `partial-cylindrical-groove`。
   - 会估算槽宽、圆弧长度和槽深。
-  - 会识别槽圆柱 face 和槽边界相邻 face，并在 Feature 模式下一起高亮。
+  - 会识别槽圆柱Face和槽边界相邻Face，并在 Feature 模式下一起高亮。
   - 这些仍是 B-Rep 几何估算，不是 CAD 历史里的槽特征参数。
-- 支持第一版槽/半孔宽度调整：
+- 当前版本支持槽/半孔宽度调整：
   - 只对已识别为 `partial-cylindrical-groove` 的部分圆柱孔/槽候选开放。
   - 输入目标槽宽后，会按当前圆弧角度把槽宽换算为目标圆柱直径，再复用圆柱孔/槽重建路线执行。
   - 这不是完整 CAD 槽参数编辑；复杂槽、非圆柱槽或圆弧角度不稳定时仍可能失败并回滚。
-- 支持第一版已有圆角/倒圆候选结构化识别：
+- 当前版本支持薄壁/壳体局部厚度调整：
+  - 对已找到投影重叠相对平面的平面候选开放。
+  - 输入目标厚度后，程序会把厚度变化换算成当前平面区域的推拉距离，保留相对平面不动。
+  - 会先显示半透明推拉预览，并记录当前厚度、目标厚度、相对平面Face、重叠率和推拉距离。
+  - 这是局部 B-Rep 平面推拉近似，不是 CAD 壳命令或完整壳体参数编辑。
+- 当前版本支持已有圆角/倒圆候选结构化识别：
   - 对局部小半径圆柱面，会标记为 `round/fillet candidate`。
   - 会估算已有圆角半径、圆弧角度和圆弧长度。
-  - 会识别已有圆角 face 和相邻支撑 face，并在 Feature 模式下一起高亮。
-  - `第一版可编辑对象` 会把已有圆角候选单独列为 `修改已有圆角半径`，点击后会选中该圆角 face，并把圆角半径输入框预填为当前估算半径的参考目标值。
+  - 会识别已有圆角Face和相邻支撑Face，并在 Feature 模式下一起高亮。
+  - `可编辑对象` 会把已有圆角候选单独列为 `修改已有圆角半径`，点击后会选中该圆角 Face，并把圆角半径输入框预填为当前估算半径的参考目标值。
   - 选中已有圆角候选时，不会再误把它填入 `孔直径`，避免把圆角当孔径修改。
-  - 第一版已有圆角半径修改会先尝试移除圆角 face，再在恢复出的锐边上重新倒圆；只对较规整的圆柱圆角候选开放，复杂 blend 可能失败并回滚。
-- 支持第一版圆柱孔封堵：
+  - 当前版本的已有圆角半径修改会先尝试移除圆角Face，再在恢复出的锐边上重新倒圆；只对较规整的圆柱圆角候选开放，复杂 blend 可能失败并回滚。
+- 当前版本支持圆柱孔封堵：
   - 只对 `hole/groove candidate` 且角度跨度接近完整圆柱的孔开放。
   - 不对半孔/槽开放，避免用完整圆柱补料时把不该补的位置也补上。
   - 封堵会用略带半径重叠的圆柱补料体执行 Fuse。
   - 绿色半透明预览表示即将补上的材料范围。
   - 当前默认模型可能不会在默认可编辑对象列表里显示封堵候选；其他包含完整圆柱孔的 STEP 文件可以使用这个能力。
-- 支持第一版圆柱凸台直径调整：
+- 当前版本支持圆柱凸台直径调整：
   - 只对 `boss/outer-round candidate` 且角度跨度接近完整圆柱的凸台开放。
   - 不处理局部外圆角、圆角面或未明确圆柱面，避免把圆角当凸台修改。
   - 目标直径变大时，会在同域圆柱侧壁范围内生成目标直径圆柱并 Fuse。
   - 目标直径变小时，会先用旧外形包络体移除原凸台范围，再 Fuse 目标直径圆柱重建，避免环形 cutter 在部分场景下把实体切空。
   - 会先显示半透明预览：绿色表示扩大/重建补料范围，红色表示缩小移除范围。
   - 当前默认模型可能没有明确凸台候选；包含完整圆柱凸台的 STEP 文件可以使用这个能力。
-- 支持第一版直线边添加圆角：
-  - 只对直线 edge 开放。
-  - 会先检查边长、相邻 face 数量和目标半径相对边长的比例。
-  - 蓝色半透明预览表示目标 edge 和输入半径的大致范围。
+- 当前版本支持直线Edge添加圆角：
+  - 只对直线Edge开放。
+  - 会先检查边长、相邻Face数量和目标半径相对边长的比例。
+  - 蓝色半透明预览表示目标Edge和输入半径的大致范围。
   - 真实编辑使用 OCCT `BRepFilletAPI_MakeFillet` 在后台执行。
   - 这一步是“给直线边添加新圆角”，还不是“修改已有圆角半径”。
   - STEP 没有建模历史，某些看起来像直线边的对象仍可能被 OCCT 拒绝；失败时会自动尝试恢复编辑前状态。
-- 支持第一版直线边添加倒角：
-  - 只对直线 edge 开放。
-  - 会先检查边长、相邻 face 数量和倒角距离相对边长的比例。
-  - 橙色半透明预览表示目标 edge 和输入倒角距离的大致范围。
+- 当前版本支持直线Edge添加倒角：
+  - 只对直线Edge开放。
+  - 会先检查边长、相邻Face数量和倒角距离相对边长的比例。
+  - 橙色半透明预览表示目标Edge和输入倒角距离的大致范围。
   - 真实编辑使用 OCCT `BRepFilletAPI_MakeChamfer` 在后台执行。
   - STEP 没有建模历史，某些边仍可能被 OCCT 拒绝；失败时会自动尝试恢复编辑前状态。
-- 支持第一版直接边长调整：
-  - 选中 edge 后，`边目标长度` 会自动填入当前边长。
-  - 可以选择边长基准：自动、中心、固定起点、固定终点。
-  - 直线 edge 会优先尝试寻找端点附近、方向匹配的平面端面，并把“改边长”转换成该端面的平面推拉操作。
-  - `自动` 会优先选择可局部推拉的端面；`固定起点` / `固定终点` 会优先尝试移动另一端端面。
-  - 圆形/圆弧 edge 会优先检查相邻圆柱面；如果能复用孔/槽或凸台直径编辑，就把目标边长按比例换算成目标圆柱直径再执行局部编辑。
-  - `中心`、没有明确端面、或圆边没有可复用圆柱面时，会尝试整体/轴向几何缩放 fallback，以覆盖更多任意 edge 的最小可用场景。
-  - 该 fallback 会影响所属 part/solid 的其它尺寸，因此会按高风险确认，并依赖失败回滚/撤销兜底。
+- 当前版本支持修改Edge长度：
+  - 选中Edge后，`Edge目标长度` 会自动填入当前Edge长度。
+  - 可以选择Edge长度基准：自动、中心、固定起点、固定终点。
+  - 对正方体这类全平面多面体，直线Edge会优先走“局部边形变”：只移动被选Edge的一个端点或两个端点，并重建周边平面。
+  - 局部边形变不会把整个端面拉走，因此正方体不会默认变成长方体；相邻面会按被移动的边自然变成梯形或拆成三角面。
+  - `自动` 默认固定起点、移动终点；`固定起点` / `固定终点` 会明确控制哪一端不动；`中心` 会让两端各移动一半。
+  - 如果模型不是简单全平面多面体，直线Edge会继续尝试寻找端点附近、方向匹配的平面端面，并把“改边长”转换成该端面的平面推拉操作。
+  - 圆形/圆弧Edge会优先检查相邻圆柱面；如果能复用孔/槽或凸台直径编辑，就把Edge目标长度按比例换算成目标圆柱直径再执行局部编辑。
+  - 圆边没有可复用圆柱面时，会优先围绕圆边轴线做径向缩放，尽量只改半径方向并保留轴向尺寸；这类一般仿射可能把解析圆/圆锥/圆柱几何转换为 B-spline。
+  - 椭圆边和可稳定采样为平面的 B-spline / Bezier 等非直线边，也会尝试围绕曲线所在平面法向做径向缩放；如果采样点不够平面，会退回更保守的缩放 fallback。
+  - 几何缩放 fallback 会先只预变换目标Edge来估算结果长度，并在必要时微调缩放比例，让实际边长更接近输入值。
+  - `中心`、没有明确端面、或非圆边没有更明确局部路径时，会尝试整体/轴向几何缩放 fallback，以覆盖更多任意Edge的最小可用场景。
+  - 该 fallback 会影响所属Part/Solid的其它尺寸，因此会按高风险确认，并依赖失败回滚/撤销兜底。
   - 这仍不是通用参数化边长编辑；复杂拓扑、斜面过渡、圆角链或布尔失败场景仍可能不能稳定修改。
-- 支持 part / solid 级平移：
+- 支持 Part / Solid 级平移：
   - 输入 X/Y/Z 平移量后，可以平移当前选中零件。
-  - 选中 solid、或选中属于某个 solid 的 face/edge 后，可以平移当前 solid。
-  - 单 solid 零件中平移 solid 实际等同于移动整个 part shape，程序会按中风险提示。
+  - 选中Solid、或选中属于某个Solid的Face/Edge后，可以平移当前Solid。
+  - 单Solid零件中平移Solid实际等同于移动整个Part shape，程序会按中风险提示。
   - 平移操作会写入历史记录，并支持撤销/重做。
-- 支持 part / solid 级旋转：
-  - 选择 X/Y/Z 旋转轴并输入角度后，可以旋转当前选中零件或 solid。
-  - 第一版旋转中心取目标对象的包围盒中心。
-  - 单 solid 零件中旋转 solid 实际等同于旋转整个 part shape，程序会按中风险提示。
+- 支持 Part / Solid 级旋转：
+  - 选择 X/Y/Z 旋转轴并输入角度后，可以旋转当前选中零件或Solid。
+  - 当前版本的旋转中心取目标对象的包围盒中心。
+  - 单Solid零件中旋转Solid实际等同于旋转整个Part shape，程序会按中风险提示。
   - 旋转操作会写入历史记录，并支持撤销/重做。
 - 后台编辑计算时不再弹出模态进度框，也不再把主界面整体置灰；UI 线程只负责渲染和响应基础视图交互，真实 B-Rep 编辑在后台线程执行。
 - 编辑计算期间，半透明预览会继续在 3D 视图里渲染，用户可以旋转或缩放查看；会改变模型状态的操作仍会暂时禁用，避免同一模型被多个后台编辑同时修改。
+- 首次加载会先在后台生成粗显示数据并快速显示，随后再后台生成精细显示数据并替换到视图里。
+- 鼠标悬停高亮做了节流和移动阈值，减少复杂模型上连续拾取造成的卡顿。
+- 后台编辑成功后会尽量在后台一并生成刷新用的模型/边线显示数据，减少编辑完成瞬间的主线程冻结。
 - 真实 B-Rep 结果会在布尔计算完成后一次性刷新；半透明预览不等于最终几何结果。
 - 如果后台编辑失败，程序会自动尝试恢复到编辑前快照，避免出现“提示失败但模型已经被部分改动”的状态。
-- 实验性支持圆柱孔/圆柱面扩大切削。
-- 实验性支持圆柱孔/圆柱面缩小孔径：先补料，再用目标直径重切。
+- 当前版本支持圆柱孔/圆柱面扩大切削。
+- 当前版本支持圆柱孔/圆柱面缩小孔径：先补料，再用目标直径重切。
 - 圆柱孔/圆柱面孔径调整现在会先生成切削计划：
   - 目标直径必须大于 0；如果目标直径与当前直径几乎相同，会直接阻止。
   - 会计算直径变化比例；变化超过当前直径 35% 会提高到中风险，超过 100% 会提高到高风险。
   - 会比较目标直径和圆柱面估算高度；比例异常时会提高风险等级。
   - 候选不是 `hole/groove candidate` 时会标为高风险并要求确认。
   - 圆角/倒圆候选会标为高风险，避免误切圆角。
-  - 缩小孔径第一版只对 `hole/groove candidate` 开放，其他圆柱面会直接阻止。
-  - 选中 face 或实际切削计划会使用多点材料采样，比候选表里的快速分类更谨慎。
+  - 缩小孔径当前版本只对 `hole/groove candidate` 开放，其他圆柱面会直接阻止。
+  - 选中Face或实际切削计划会使用多点材料采样，比候选表里的快速分类更谨慎。
   - 实际切削优先使用有限长度 cutter，按选中圆柱面的 V 参数范围加少量余量生成，不再默认贯穿整个零件。
   - 会沿圆柱轴线采样两端材料状态，初步区分通孔/开口端、盲孔和封闭端。
   - 会把圆柱相邻平面按轴线位置分成起点端/终点端，并结合端部采样标记疑似盲孔底面；相邻端面缺失时，会尝试扫描轴线附近的平面圆盘候选作为兜底。
-  - 孔径修改计划会记录疑似底面 face、开口端相邻 face 和 cutter 底面保护状态。
+  - 孔径修改计划会记录疑似底面Face、开口端相邻Face和 cutter 底面保护状态。
   - 对盲孔/封闭端，有限长度 cutter 会使用更小的端部余量，降低切深变长的风险。
-- 支持撤销/重做实验性编辑。
+- 支持撤销/重做编辑。
 - 撤销/重做会先确认模型恢复成功，再移动历史栈；如果恢复失败，会尽量回到操作前状态。
 - 支持操作历史面板，显示当前已经成功执行的编辑。
 - 操作历史详情会显示编辑类型、目标对象、参数、执行结果和拓扑数量变化。
-- 操作历史详情会额外显示目标零件自身的 solid / face / edge 数量变化。
-- 如果一次局部编辑导致目标零件 solid 数异常变化，历史详情会显示质量警告，状态栏也会提示先检查结果。
+- 操作历史详情会额外显示目标零件自身的 Solid / Face / Edge 数量变化。
+- 如果一次局部编辑导致目标零件 Solid 数异常变化，历史详情会显示质量警告，状态栏也会提示先检查结果。
 - 操作历史详情会显示编辑前后的几何差异摘要：
   - 体积变化。
   - 表面积变化。
@@ -254,13 +275,13 @@
   - 可以点击 `清除差异预览` 关闭叠加显示。
 - 支持导出选中操作历史的差异报告，报告会包含操作参数、拓扑变化、几何变化和热力图统计。
 - 鼠标拾取模型时会显示三维拾取点坐标。
-- 实验性编辑历史会记录目标对象和当时的拾取点。
-- 支持把本软件加载后的编辑历史导出为 JSON；这不是 STEP 原始 CAD 建模历史，而是后续操作留档。
+- 编辑历史会记录目标对象和当时的拾取点。
+- 支持把本软件加载后的编辑历史导出为 JSON v2；除摘要和详情外，也会保存 `operation_name`、`target`、`parameters` 和 `result_message`，为后续安全复放做准备。
 - 点击操作历史记录时，程序会尝试重新高亮目标对象，并显示当时的拾取点标记。
 - 对非 `hole/groove candidate` 的圆柱切削会先弹出确认，避免误切外圆角或凸柱。
 - 提供 `--smoke-test` 启动检查，用于验证 Qt + VTK 窗口组件能正常初始化。
 
-当前 `geom_extract.step` 的读取结果是：
+当前 `assets/models/geom_extract.step` 的读取结果是：
 
 ```text
 part: 2001-LOWER_HOUSING
@@ -277,12 +298,12 @@ vertices: 3262
 
 这里分成两类看，不然容易误解为“完全没有推进”。
 
-已经有第一版，但还需要继续稳定和完善：
+已经有当前版本的初步实现，但还需要继续稳定和完善：
 
 - 复杂特征识别：已经有平面、圆柱、边、孔/槽候选、槽/半孔候选、已有圆角候选、圆柱凸台候选等基础候选列表，但还不是完整 CAD 语义级识别。
-- 盲孔/盲槽深度：已经能对部分可识别候选做深度估算和编辑，并会优先使用疑似底面 face 的轴向位置计算当前深度；但还不能保证所有模型都能恢复真实 CAD 语义深度。
-- 槽、凸台、壳体局部区域：已经有圆柱孔、槽/半孔候选结构化识别、槽/半孔宽度调整、完整圆柱凸台直径修改和平面薄壁/壳体相对面厚度估算；复杂槽、复杂凸台和完整壳体区域仍需要继续做。
-- 已有圆角/倒圆面半径：已经有第一版受限修改实现，使用 defeature + refillet 路线，但复杂 blend、支撑面不明确或恢复锐边失败时仍会阻止或回滚。
+- 盲孔/盲槽深度：已经能对部分可识别候选做深度估算和编辑，并会优先使用疑似底面Face的轴向位置计算当前深度；但还不能保证所有模型都能恢复真实 CAD 语义深度。
+- 槽、凸台、壳体局部区域：已经有圆柱孔、槽/半孔候选结构化识别、槽/半孔宽度调整、完整圆柱凸台直径修改，以及平面薄壁/壳体相对面厚度估算和当前版本厚度调整；复杂槽、复杂凸台和完整壳体区域仍需要继续做。
+- 已有圆角/倒圆面半径：已经有当前版本的受限修改实现，使用 defeature + refillet 路线，但复杂 blend、支撑面不明确或恢复锐边失败时仍会阻止或回滚。
 - 局部偏差分析：已经有编辑前后体积、面积、包围盒、距离热力图和差异报告，但还不是工程公差级的局部区域偏差报告。
 - 错误恢复和模型修复：已经有编辑前快照、失败回滚、基础 B-Rep 校验、同域面合并、布尔结果自动修复，以及一键修复当前模型或选中零件/solid，但还不是完整的模型修复流水线。
 - 多零件装配：已经有装配/零件树和单独导出入口，但还没有做大规模、多来源 STEP 装配测试。
@@ -296,12 +317,12 @@ vertices: 3262
 
 建议下一步按这个顺序推进：
 
-1. 继续补齐更多最小可用特征入口，优先覆盖复杂槽、复杂凸台、局部薄壁/壳体区域和装配用例。
-2. 继续验证平面推拉、孔径调整、槽/半孔宽度调整、盲孔/盲槽深度调整、圆柱凸台直径调整和直接边长调整，记录哪些对象稳定、哪些对象会失败。
-3. 改进盲孔/槽底面识别，减少“看起来像 blind 但找不到可靠底面 face”的候选。
+1. 继续补齐更多最小可用特征入口，优先覆盖复杂槽、复杂凸台、完整壳体区域和装配用例。
+2. 继续验证平面推拉、孔径调整、槽/半孔宽度调整、薄壁厚度调整、盲孔/盲槽深度调整、圆柱凸台直径调整和直接边长调整，记录哪些对象稳定、哪些对象会失败。
+3. 改进盲孔/槽底面识别，减少“看起来像 blind 但找不到可靠底面Face”的候选。
 4. 继续加固已有圆角半径修改：扩大可成功场景，记录哪些圆角能 defeature + refillet，哪些需要更复杂的重建策略。
-5. 完善本软件编辑历史的导入/复放能力，让后续编辑不只是导出 JSON 留档。
-6. 最后集中做性能和稳定性优化，包括首次加载后台精细化、扫描节流和高风险 OCC 操作隔离。
+5. 完善本软件编辑历史的导入/复放能力；当前 JSON v2 已保存机器可读的动作名和参数，但自动复放还需要按操作类型逐步加安全规则。
+6. 继续做性能和稳定性优化，重点是扫描分批刷新、局部显示重建缓存，以及高风险 OCC 操作隔离。
 
 ## 怎么运行
 
@@ -336,6 +357,18 @@ python main.py
 python main.py path\to\model.step
 ```
 
+打开简单立方体测试模型：
+
+```powershell
+python main.py assets\models\cube_10mm.step
+```
+
+重新生成简单立方体测试模型：
+
+```powershell
+python scripts\generate_cube_step.py
+```
+
 如果当前 PowerShell 没识别 `conda`，可以直接使用完整路径运行：
 
 ```powershell
@@ -348,6 +381,12 @@ C:\Users\admin\miniforge3\Scripts\conda.exe run -n pyocc python main.py
 python main.py --smoke-test
 ```
 
+验证立方体上的“只改一条 Edge 长度”基线：
+
+```powershell
+python scripts\verify_edge_length_resize.py
+```
+
 ## 怎么使用
 
 打开程序后，右侧是 3D 模型窗口，左侧是操作面板。
@@ -358,7 +397,7 @@ python main.py --smoke-test
 - 鼠标滚轮：缩放模型。
 - 鼠标中键或组合拖动：平移模型，具体取决于 VTK 默认交互方式。
 
-左侧操作面板按功能分区排列，每个模块都有四边同色的独立边框和颜色提示，方便快速区分文件、模型结构树、选择、显示、导出、编辑、候选列表、历史记录和对象信息。
+左侧操作面板按功能分区排列，每个模块都有四边同色的独立边框和颜色提示，顺序大致按工作流排列：先打开和选择模型，再做编辑或导出，然后进行显示控制和测量，后面继续放可编辑对象、圆柱面候选、操作历史和对象信息。
 
 左侧 `鼠标选择模式` 用来切换选择模式：
 
@@ -367,10 +406,10 @@ python main.py --smoke-test
 - `Face`：选择面。
 - `Edge`：选择边。
 - `Feature`：按局部特征候选方式选择。平面会识别为可推拉平面候选；圆柱面会进一步识别为圆柱孔、槽/半孔、圆角/倒圆、凸台/外圆等候选。
-  圆柱候选会额外显示侧壁 face、端面 face、疑似底面 face、开口端相邻 face 和边界 edge。
+  圆柱面候选会额外显示侧壁 Face、端面 Face、疑似底面 Face、开口端相邻 Face 和边界 Edge。
 - 鼠标悬停时，当前模式下将要选中的对象会显示为红色；真正选中后会显示为黄色。
-- 如果当前模式是 `Edge`，即使鼠标点到的是面，程序也会从这个面的边界里选取距离鼠标拾取点最近的 edge。
-- `鼠标选择模式` 下拉框不响应鼠标滚轮，鼠标停在上面滚动时不会自动切换选项；需要点击下拉框后手动选择。
+- 如果当前模式是 `Edge`，即使鼠标点到的是面，程序也会从这个面的边界里选取距离鼠标拾取点最近的Edge。
+- `鼠标选择模式` 下拉框关闭时不会吃掉滚轮，鼠标停在上面滚动会继续滚动左侧面板；点击打开下拉列表后，滚轮才用于滚动选项。
 
 左侧 `模型结构树` 会显示 STEP 里的装配、零件和实体层级；如果某个零件下有实体，会展开显示 `实体 0`、`实体 1` 这样的子节点。点击实体子节点会自动切换到 `Solid` 选择，并高亮对应实体。
 
@@ -388,18 +427,18 @@ python main.py --smoke-test
 - 按 ID 选择会复用上方 `鼠标选择模式` 的当前类型；先切换模式，再输入 ID，点击 `选择`。
 - 输入框右侧会同步显示当前类型，例如 `Face`、`Edge` 或 `Solid`，用于确认这个 ID 会按哪类对象解释。
 - `Part` 的 ID 从 1 开始。
-- `Solid`、`Face`、`Edge`、`Feature` 的 ID 从 0 开始；`Feature` 使用来源 face 的 ID。
-- 这个功能适合配合圆柱候选表格、操作历史和属性面板使用。
+- `Solid`、`Face`、`Edge`、`Feature` 的 ID 从 0 开始；`Feature` 使用来源Face的 ID。
+- 这个功能适合配合圆柱面候选表格、操作历史和属性面板使用。
 
 左侧 `显示` 用来临时缩小三维视图范围：
 
-- `只显示选中`：只显示当前选中的 part、solid、face、edge 或 feature 区域。
-- Face 模式下 `只显示选中` 会隔离当前黄色同域面区域，并显示这片区域的外边界 edge。
-- `对准选中`：不改变显示范围，只把相机对准当前选中的 part、solid、face、edge 或 feature，适合快速查看小孔、小边和局部特征。
+- `只显示选中`：只显示当前选中的 Part、Solid、Face、Edge 或 Feature 区域。
+- Face 模式下 `只显示选中` 会隔离当前黄色同域面区域，并显示这片区域的外边界Edge。
+- `对准选中`：不改变显示范围，只把相机对准当前选中的 Part、Solid、Face、Edge 或 Feature，适合快速查看小孔、小边和局部特征。
 - `显示全部`：恢复显示完整模型。
 - `显示同域内部边`：默认关闭，用来隐藏同一平面/同一圆柱面内部的拓扑分割边和几何重复拼接边；打开后可以查看完整 B-Rep 拓扑边线，适合调试布尔推拉后的分面情况。
-- `导出选中面区域` 会导出当前 Face 模式黄色高亮的同域面区域，而不是只导出鼠标点到的单个拓扑 face。
-- solid / edge 的显示查询已经使用拓扑索引，避免每次隔离或高亮时反复全模型查找。
+- `导出选中面区域` 会导出当前 Face 模式黄色高亮的同域面区域，而不是只导出鼠标点到的单个拓扑Face。
+- Solid / Edge 的显示查询已经使用拓扑索引，避免每次隔离或高亮时反复全模型查找。
 - 这是视图操作，不会修改 STEP 几何，也不会写入操作历史。
 
 左侧 `测量` 用来做最基础的点到点距离检查：
@@ -412,29 +451,29 @@ python main.py --smoke-test
 - `复制测量` 会复制当前测量结果；`清除测量` 会清空 A/B 和测量线。
 - 测量不会修改模型，也不会写入操作历史。
 
-左侧 `第一版可编辑对象` 是当前 MVP 的主要入口：
+左侧 `可编辑对象` 是当前 MVP 的主要入口：
 
-- 点击 `扫描可编辑对象` 会列出当前第一版能尝试编辑的对象。
+- 点击 `扫描对象` 会列出当前版本能尝试编辑的对象。
 - 点击 `深度扫描` 会用更高上限重新扫描，可能需要等待更久。
 - 为了避免打开大模型时界面卡住，程序不会在加载 STEP 时自动扫描；需要编辑时再手动点击扫描。
-- 当前默认显示一批代表性的可编辑候选，详细几何判断会尽量延后到选中对象或执行编辑前，避免扫描过慢。
-- `推拉平面` 行表示这个 face 是平面，可以配合 `面偏移` 和 `推拉平面` 使用。
-- `调整圆柱孔径` 行表示这个 face 是圆柱候选，可以配合 `孔直径` 和 `调整圆柱孔径` 使用。
-- `调整槽/半孔宽度` 行表示这个 face 是槽/半孔候选，可以配合 `槽/半孔宽度` 和 `调整槽/半孔宽度` 使用。
-- `调整圆柱凸台直径` 行表示这个 face 是较明确的完整圆柱凸台候选，可以配合 `凸台直径` 和 `调整圆柱凸台直径` 使用。
-- `封堵圆柱孔` 行表示这个 face 是接近完整圆柱的孔候选，可以点击后直接使用 `封堵圆柱孔`。
-- `调整盲孔深度` 行表示这个 face 是较明确的盲孔/盲槽候选，可以配合 `孔深度` 和 `调整盲孔深度` 使用。
-- `给边添加圆角` 行表示这个对象是直线 edge，可以配合 `圆角半径` 和 `给边添加圆角` 使用。
-- `给边添加倒角` 行表示这个对象是直线 edge，可以配合 `倒角距离` 和 `给边添加倒角` 使用。
-- `修改已有圆角半径` 行表示这个 face 是已有圆角/倒圆候选，点击后会切到 `Feature` 模式并预填圆角半径参考值；真正执行需要再点击编辑区里的 `修改已有圆角半径` 按钮并确认。
+- 当前默认显示一批代表性的可编辑对象，详细几何判断会尽量延后到选中对象或执行编辑前，避免扫描过慢。
+- `推拉平面` 行表示这个Face是平面，可以配合 `Face偏移` 和 `推拉平面` 使用。
+- `调整圆柱孔径` 行表示这个 Face 是圆柱面候选，可以配合 `孔直径` 和 `调整圆柱孔径` 使用。
+- `调整槽/半孔宽度` 行表示这个Face是槽/半孔候选，可以配合 `槽/半孔宽度` 和 `调整槽/半孔宽度` 使用。
+- `调整圆柱凸台直径` 行表示这个Face是较明确的完整圆柱凸台候选，可以配合 `凸台直径` 和 `调整圆柱凸台直径` 使用。
+- `封堵圆柱孔` 行表示这个Face是接近完整圆柱的孔候选，可以点击后直接使用 `封堵圆柱孔`。
+- `调整盲孔深度` 行表示这个Face是较明确的盲孔/盲槽候选，可以配合 `孔深度` 和 `调整盲孔深度` 使用。
+- `给Edge添加圆角` 行表示这个对象是直线Edge，可以配合 `圆角半径` 和 `给Edge添加圆角` 使用。
+- `给Edge添加倒角` 行表示这个对象是直线Edge，可以配合 `倒角距离` 和 `给Edge添加倒角` 使用。
+- `修改已有圆角半径` 行表示这个Face是已有圆角/倒圆候选，点击后会切到 `Feature` 模式并预填圆角半径参考值；真正执行需要再点击编辑区里的 `修改已有圆角半径` 按钮并确认。
 - `状态` 为 `ready` 表示比较适合尝试，`caution` 表示可以尝试但风险更高，`blocked` 表示当前参数或对象不适合执行。
 - `风险` 越高越应该谨慎，尤其是圆角、凸柱或未明确圆柱面，不要直接当孔修改。
-- 点击任意一行会自动选中并高亮对应 face 或 edge。
+- 点击任意一行会自动选中并高亮对应Face或Edge。
 
 选择对象后：
 
 - 鼠标经过对象时会出现红色预高亮；被选对象会显示为黄色高亮。
-- 在 `Face` 模式下，如果相邻 face 属于同一几何面，并且投影范围或轴向范围相接/重叠，程序会把它们作为同域区域一起红色预高亮和黄色选中高亮；这主要用于缓解平面/圆柱推拉后视觉上被拓扑边分成多段的问题。
+- 在 `Face` 模式下，如果相邻Face属于同一几何面，并且投影范围或轴向范围相接/重叠，程序会把它们作为同域区域一起红色预高亮和黄色选中高亮；这主要用于缓解平面/圆柱推拉后视觉上被拓扑边分成多段的问题。
 - 如果处于 `Feature` 模式，程序会尽量高亮这个特征相关的局部区域，例如圆柱侧壁、相邻端面和槽边界相邻面。
 - 对槽/半孔候选，属性表会显示 `槽宽估算`、`槽圆弧长度估算`、`槽深估算` 和 `槽边界相邻 Face`。
 - 对圆角/倒圆候选，属性表会显示 `已有圆角半径估算`、`已有圆角圆弧角度`、`已有圆角圆弧长度估算` 和 `已有圆角支撑 Face`。
@@ -447,54 +486,40 @@ python main.py --smoke-test
 - `复制信息` 会复制当前信息面板里的完整文本。
 - 用鼠标在模型上选择时，`选中对象信息` 和窗口底部状态栏会显示 `pick_position`，也就是拾取点的三维坐标。
 - 如果选中圆柱面，会自动给 `Hole diameter` 填一个略大的建议直径。
-- 如果选中直线 edge，会自动给 `圆角半径` 和 `倒角距离` 填一个保守的建议值，并把 `边目标长度` 填成当前边长。
+- 如果选中直线Edge，会自动给 `圆角半径` 和 `倒角距离` 填一个保守的建议值，并把 `Edge目标长度` 填成当前Edge长度。
 
-圆柱候选：
+圆柱面候选：
 
-- 点击 `列出圆柱候选` 会刷新候选表格。
-- 圆柱候选也是手动扫描，避免加载模型和普通选择操作被候选识别拖慢。
+- 点击 `扫描圆柱面` 会刷新候选表格。
+- 圆柱面候选也是手动扫描，避免加载模型和普通选择操作被候选识别拖慢。
 - 可以通过候选表格上方的类型下拉框筛选候选；筛选只过滤已经扫描出的缓存结果，不会重新做几何识别。
-- 类型下拉框不响应鼠标滚轮，避免鼠标经过时误切换筛选条件。
-- 当前默认显示前 60 个圆柱候选；如果模型很复杂，扫描仍可能需要等待一会儿，但扫描过程中界面会尽量保持响应。
+- 类型下拉框关闭时不会吃掉滚轮，鼠标停在上面滚动会继续滚动左侧面板；点击打开下拉列表后，滚轮才用于滚动选项。
+- 当前默认显示前 60 个圆柱面候选；如果模型很复杂，扫描仍可能需要等待一会儿，但扫描过程中界面会尽量保持响应。
 - 表格里的每一行对应一个圆柱面候选。
-- 点击候选行会自动切到 `Feature` 模式，并选中对应 face。
+- 点击候选行会自动切到 `Feature` 模式，并选中对应Face。
 - `guess` 列是程序通过几何采样得到的初步判断，不是 STEP 文件里自带的 CAD 历史特征。
-- `round/fillet candidate` 是圆角/倒圆候选；部分规整圆柱圆角可以通过 `修改已有圆角半径` 进行第一版受限修改。
+- `round/fillet candidate` 是圆角/倒圆候选；部分规整圆柱圆角可以通过 `修改已有圆角半径` 进行当前版本受限修改。
 - `diameter` 是圆柱直径。
 - `span` 是圆柱面的角度跨度，接近 `6.283` 表示接近完整圆柱，接近 `3.142` 表示半圆柱。
 - `height` 是根据圆柱面积估算出来的高度。
 - `confidence` 是当前猜测置信度。
 - 这些候选可能是孔、柱、圆角或其他圆柱面，目前还不是稳定的“孔识别”。
 
-导出：
+编辑：
 
-- `导出当前完整 STEP`：导出当前完整模型。
-- `导出选中零件`：导出当前选中的零件。
-- `导出选中 solid`：先选中一个 solid，再导出该 solid。
-- `导出选中 face`：先切换到 `Face` 选择模式并选中一个 face，再导出该 face。
-- `导出选中特征区域`：先切换到 `Feature` 选择模式并选中局部特征，再导出当前特征高亮的 face 集合。
-- `导出选中 edge`：先切换到 `Edge` 选择模式并选中一个 edge，再导出该 edge。
-- `检查导出质量`：检查当前选中对象；如果没有选中对象，就检查当前完整模型。
-- `修复当前模型`：对当前完整模型执行 ShapeFix 和同域面/边合并，完成后会刷新显示并写入操作历史；如果修复失败，会尝试回滚到修复前状态。
-- `修复选中零件/solid`：优先修复当前选中对象所属 solid；如果当前对象没有 solid，则修复所属零件。face 或 edge 被选中时，也会按其所属 solid/零件执行局部修复。
-- 导出按钮会根据当前选中对象自动启用或禁用，避免选中 face 时误点 `导出选中 edge` 这类不匹配的操作。
-- 所有导出按钮都会先做质量检查。发现 B-Rep 无效、没有 solid、零件包含多个 solid、体积接近 0 等风险时，会先弹窗确认是否继续导出。
-
-实验性编辑：
-
-- 编辑按钮会根据当前选择自动启用或禁用。例如未选中平面时不能点击 `推拉平面`，未选中直线 edge 时不能点击 `给边添加圆角` / `给边添加倒角`，未选中明确孔/凸台/盲孔候选时对应圆柱编辑按钮会禁用。
-- `面偏移` + `推拉平面`：
-  - 先选择一个平面 face。
+- 编辑按钮会根据当前选择自动启用或禁用。例如未选中平面时不能点击 `推拉平面`，未选中直线Edge时不能点击 `给Edge添加圆角` / `给Edge添加倒角`，未选中明确孔/凸台/盲孔候选时对应圆柱编辑按钮会禁用。
+- `Face偏移` + `推拉平面`：
+  - 先选择一个平面Face。
   - 输入偏移距离。
   - 正数表示沿程序判断的外法向加料。
   - 负数表示沿内侧方向切削。
   - 点击 `推拉平面` 后，会先出现半透明预览体；绿色表示向外加料方向，红色表示向内切削方向。
-  - 如果距离为 0 会直接阻止；如果方向置信度低或距离相对 face 尺寸偏大，会先弹窗确认。
-  - 如果选中 face 周围有共面且相接/重叠的碎面，程序会自动把这些 face 合成同一片推拉区域，属性表和历史记录会显示 `推拉共面区域 Face 数`。
+  - 如果距离为 0 会直接阻止；如果方向置信度低或距离相对Face尺寸偏大，会先弹窗确认。
+  - 如果选中Face周围有共面且相接/重叠的碎面，程序会自动把这些Face合成同一片推拉区域，属性表和历史记录会显示 `推拉共面区域 Face 数`。
   - 加料时程序会让拉伸体和原实体产生极小重叠，并在布尔后尝试合并同域面/边，使导出的 STEP 更像一个整体实体。
   - 程序随后在后台执行真实布尔运算，完成后再刷新为真正修改后的模型。
-  - 选中平面 face 后，可以在 `属性表` 的方向/轴线分组里查看 `推拉向外方向`、`推拉向内方向` 和 `推拉方向置信度`。
-  - 当前方向判断通过 solid 的 inside / outside 采样得到；如果采样不明确，会退回到拓扑方向法向，并在属性里显示低置信度说明。
+  - 选中平面Face后，可以在 `属性表` 的方向/轴线分组里查看 `推拉向外方向`、`推拉向内方向` 和 `推拉方向置信度`。
+  - 当前方向判断通过Solid的 inside / outside 采样得到；如果采样不明确，会退回到拓扑方向法向，并在属性里显示低置信度说明。
   - 当前实现仍使用布尔加/减验证推拉路线。
 - `孔直径` + `调整圆柱孔径`：
   - 先选择一个圆柱面。
@@ -505,38 +530,45 @@ python main.py --smoke-test
   - 程序会先生成切削计划，检查当前直径、目标直径、候选类型、材料投票和风险。
   - 切削计划会显示直径变化量、直径变化比例，以及目标直径相对圆柱面估算高度的比例。
   - 切削计划会显示端部类型、深度估算、起点端状态和终点端状态。
-  - 切削计划会显示疑似底面 face、开口端相邻 face 和底面保护说明；这些信息会写入操作历史。
+  - 切削计划会显示疑似底面Face、开口端相邻Face和底面保护说明；这些信息会写入操作历史。
   - 如果目标直径小于等于 0，或几乎等于当前直径，程序会直接阻止。
   - 如果目标直径变化过大，或者目标直径相对圆柱估算高度明显异常，程序会提高风险并要求确认。
-  - 缩小孔径第一版只对 `hole/groove candidate` 开放；圆角、凸柱或未明确圆柱面会被直接阻止。
+  - 缩小孔径当前版本只对 `hole/groove candidate` 开放；圆角、凸柱或未明确圆柱面会被直接阻止。
   - 缩小孔径属于高风险实验功能，因为它依赖“补料 + 重切”的布尔近似，不是 CAD 历史参数修改。
-  - 如果当前 face 的猜测类型不是 `hole/groove candidate`，或风险不是低风险，程序会先弹窗确认。
+  - 如果当前Face的猜测类型不是 `hole/groove candidate`，或风险不是低风险，程序会先弹窗确认。
   - 切削计划会显示 cutter 策略、高度和余量；当前优先使用有限长度 cutter，减少误切其他区域。
   - 缩小孔径时，操作历史会额外记录补料策略、补料半径和补料高度。
   - 端部类型是通过轴线端部 inside / outside 采样得到的估算，不等于 CAD 原始建模历史里的“孔深”参数。
   - 如果选到的圆柱面不是孔，而是柱或圆角，结果可能不是你想要的，所以它目前仍是实验功能。
 - `槽/半孔宽度` + `调整槽/半孔宽度`：
-  - 先切换到 `Feature` 选择模式并选择一个槽/半孔候选 face，或从圆柱候选表中选择局部圆柱形 `hole/groove candidate`。
+  - 先切换到 `Feature` 选择模式并选择一个槽/半孔候选 Face，或从圆柱面候选表中选择局部圆柱形 `hole/groove candidate`。
   - 选中符合条件的槽/半孔后，`槽/半孔宽度` 会自动填入一个比当前槽宽估算略大的建议值。
   - 输入目标槽宽后点击 `调整槽/半孔宽度`。
   - 程序会用当前圆弧角度把目标槽宽换算成目标圆柱直径，再复用圆柱孔/槽调整流程。
   - 这一步仍是 B-Rep 几何近似；复杂槽、非圆柱槽或圆弧角度不稳定时可能失败并回滚。
+- `薄壁厚度` + `调整薄壁厚度`：
+  - 先选择一个平面 Face，建议从 `可编辑对象` 中点击 `调整薄壁厚度` 行进入。
+  - 选中符合条件的薄壁/壳体平面后，`薄壁厚度` 会自动填入一个比当前估算厚度略大的建议值。
+  - 输入目标厚度后点击 `调整薄壁厚度`。
+  - 程序会移动当前平面区域，让它和相对平面的距离接近目标厚度；相对平面保持不动。
+  - 如果相对平面重叠率低、厚度变化过大或推拉方向不稳定，会提高风险或阻止执行。
+  - 这一步仍是局部 B-Rep 平面推拉近似，不是完整 CAD 壳体/薄壁特征参数编辑。
 - `凸台直径` + `调整圆柱凸台直径`：
-  - 先选择一个完整圆柱凸台 face，建议从 `第一版可编辑对象` 中点击 `调整圆柱凸台直径` 行进入。
+  - 先选择一个完整圆柱凸台 Face，建议从 `可编辑对象` 中点击 `调整圆柱凸台直径` 行进入。
   - 只有接近完整圆柱的 `boss/outer-round candidate` 会放行；局部外圆角、圆角面、孔/槽和未明确圆柱面会被阻止。
   - 目标直径大于当前直径时，会在同域圆柱侧壁范围内生成目标直径圆柱并 Fuse。
   - 目标直径小于当前直径时，会先用旧外形包络体移除原凸台范围，再 Fuse 目标直径圆柱重建。
   - 点击后会显示半透明预览：绿色表示扩大/重建补料范围，红色表示缩小移除范围。
   - 这不是 CAD 历史里的“修改凸台特征参数”，而是基于当前 B-Rep 的受限几何布尔编辑。
 - `封堵圆柱孔`：
-  - 先选择一个完整圆柱孔 face，建议从 `第一版可编辑对象` 中点击 `封堵圆柱孔` 行进入。
+  - 先选择一个完整圆柱孔 Face，建议从 `可编辑对象` 中点击 `封堵圆柱孔` 行进入。
   - 点击 `封堵圆柱孔` 后，程序会先生成补料计划。
   - 只有接近完整圆柱的 `hole/groove candidate` 会放行；半孔/槽、圆角、凸柱、未明确圆柱面会被阻止。
   - 通过检查后，会显示绿色半透明补料体预览。
   - 真实编辑会把补料体和当前零件 Fuse，并尝试合并同域面/边。
-  - 这个功能适合封堵通孔或盲孔，但仍是基于 B-Rep 几何的实验性补料，不是 CAD 历史里的“删除孔特征”。
+  - 这个功能适合封堵通孔或盲孔，但仍是基于 B-Rep 几何的受限补料，不是 CAD 历史里的“删除孔特征”。
 - `孔深度` + `调整盲孔深度`：
-  - 先选择一个盲孔或盲槽的圆柱面，建议从 `第一版可编辑对象` 中点击 `调整盲孔深度` 行进入。
+  - 先选择一个盲孔或盲槽的圆柱面，建议从 `可编辑对象` 中点击 `调整盲孔深度` 行进入。
   - 选中符合条件的盲孔/盲槽后，`孔深度` 会自动填入一个比当前估算深度略大的建议值。
   - 输入目标深度后点击 `调整盲孔深度`。
   - 目标深度大于当前估算深度时，程序会用有限长度 cutter 沿孔方向加深切削，预览显示为红色。
@@ -545,67 +577,73 @@ python main.py --smoke-test
   - 当前只支持 `hole/groove candidate`、端部类型为 `blind`、并且已经识别到 `疑似底面 Face` 的对象。
   - 通孔、封闭内腔、圆角、凸柱和未明确圆柱面会被阻止，避免误切。
   - 这个深度来自圆柱面 V 参数范围和端部 inside / outside 采样，是几何估算，不是 CAD 历史参数。
-  - 操作历史会记录当前深度、目标深度、深度变化比例、底面 face、开口端 face 和工具参数。
-- `圆角半径` + `给边添加圆角`：
-  - 先切换到 `Edge` 选择模式并选择一条直线 edge，或从 `第一版可编辑对象` 中点击 `给边添加圆角` 行进入。
-  - 选中直线 edge 后，`圆角半径` 会自动填入一个较小的建议半径。
-  - 输入目标圆角半径后点击 `给边添加圆角`。
-  - 程序会先检查半径是否大于 0、是否相对边长过大，以及该 edge 是否检测到至少两个相邻 face。
+  - 操作历史会记录当前深度、目标深度、深度变化比例、底面Face、开口端Face和工具参数。
+- `圆角半径` + `给Edge添加圆角`：
+  - 先切换到 `Edge` 选择模式并选择一条直线Edge，或从 `可编辑对象` 中点击 `给Edge添加圆角` 行进入。
+  - 选中直线Edge后，`圆角半径` 会自动填入一个较小的建议半径。
+  - 输入目标圆角半径后点击 `给Edge添加圆角`。
+  - 程序会先检查半径是否大于 0、是否相对边长过大，以及该Edge是否检测到至少两个相邻Face。
   - 点击后会显示蓝色半透明圆管预览，用于提示目标边和半径范围。
   - 真实编辑会在后台调用 OCCT 倒圆 API，完成后刷新模型。
   - 这是“给直线边添加新圆角”，不是修改已有圆角面。
   - 由于 STEP 不带建模历史，某些边会被 OCCT 判断为不适合倒圆；失败时程序会提示并尝试恢复编辑前状态。
 - `圆角半径` + `修改已有圆角半径`：
-  - 先切换到 `Feature` 选择模式并选择一个已有圆角/倒圆候选 face，或从 `第一版可编辑对象` 中点击 `修改已有圆角半径` 行进入。
+  - 先切换到 `Feature` 选择模式并选择一个已有圆角/倒圆候选 Face，或从 `可编辑对象` 中点击 `修改已有圆角半径` 行进入。
   - 选中已有圆角候选后，`圆角半径` 会自动填入一个基于当前估算半径的参考目标值。
   - 输入目标半径后点击 `修改已有圆角半径`。
-  - 程序会先检查该 face 是否为 `round/fillet candidate`、是否识别到至少两个支撑 face、目标半径是否有效，以及当前零件是否为单 solid。
+  - 程序会先检查该Face是否为 `round/fillet candidate`、是否识别到至少两个支撑Face、目标半径是否有效，以及当前零件是否为单Solid。
   - 通过检查后，会显示蓝色半透明预览，表示将尝试移除并重建的已有圆角面。
   - 真实编辑会先用 OCCT defeaturing 移除已有圆角面，再从恢复出的候选锐边中寻找可重新倒圆的边并调用 OCCT 倒圆 API。
   - 这是 B-Rep 几何重建，不是 CAD 历史圆角参数编辑；复杂 blend、支撑面不明确或恢复锐边失败时会失败并回滚。
-- `倒角距离` + `给边添加倒角`：
-  - 先切换到 `Edge` 选择模式并选择一条直线 edge，或从 `第一版可编辑对象` 中点击 `给边添加倒角` 行进入。
-  - 选中直线 edge 后，`倒角距离` 会自动填入一个较小的建议距离。
-  - 输入目标倒角距离后点击 `给边添加倒角`。
-  - 程序会先检查倒角距离是否大于 0、是否相对边长过大，以及该 edge 是否检测到至少两个相邻 face。
+- `倒角距离` + `给Edge添加倒角`：
+  - 先切换到 `Edge` 选择模式并选择一条直线Edge，或从 `可编辑对象` 中点击 `给Edge添加倒角` 行进入。
+  - 选中直线Edge后，`倒角距离` 会自动填入一个较小的建议距离。
+  - 输入目标倒角距离后点击 `给Edge添加倒角`。
+  - 程序会先检查倒角距离是否大于 0、是否相对边长过大，以及该Edge是否检测到至少两个相邻Face。
   - 点击后会显示橙色半透明圆管预览，用于提示目标边和倒角距离范围。
   - 真实编辑会在后台调用 OCCT 倒角 API，完成后刷新模型。
   - 当前只支持对称距离倒角，不支持两侧不同距离或距离+角度倒角。
   - 由于 STEP 不带建模历史，某些边会被 OCCT 判断为不适合倒角；失败时程序会提示并尝试恢复编辑前状态。
-- `边目标长度` + `直接修改边长`：
-  - 先切换到 `Edge` 选择模式并选择一条 edge，或从 `第一版可编辑对象` 中点击边长相关行进入。
-  - 选中 edge 后，`边目标长度` 会自动填入当前边长。
-  - 右侧边长基准下拉框可以选择 `自动`、`中心`、`固定起点` 或 `固定终点`。
-  - 把它改成目标长度后点击 `直接修改边长`。
-  - 直线 edge 会优先查找端点附近是否有可推拉的平面端面，并计算需要移动的端面 face 和推拉距离。
-  - 圆形/圆弧 edge 会优先尝试复用相邻圆柱面的孔/槽或凸台直径编辑，并在确认窗口显示换算出来的目标直径。
-  - `固定起点` 会尽量让起点不动、移动终点侧；`固定终点` 相反；`中心` 会让缩放 fallback 以 edge 中心为基准。
-  - 如果没有明确端面或可复用圆柱面，程序会按所选基准尝试整体/轴向几何缩放 fallback；这会影响所属 part/solid 的其它尺寸，因此会弹出高风险确认。
+- `Edge目标长度` + `修改Edge长度`：
+  - 先切换到 `Edge` 选择模式并选择一条Edge，或从 `可编辑对象` 中点击Edge长度相关行进入。
+  - 选中Edge后，`Edge目标长度` 会自动填入当前Edge长度。
+  - 右侧Edge长度基准下拉框可以选择 `自动`、`中心`、`固定起点` 或 `固定终点`。
+  - 把它改成目标长度后点击 `修改Edge长度`。
+  - 对 `assets/models/cube_10mm.step` 这类全平面多面体，直线Edge会优先只移动被选Edge的端点并重建周边平面。
+  - 这时正方体不会默认变成长方体；相邻面会跟着被移动的边自然变成梯形，必要时非共面的面会拆成三角面。
+  - 如果确认窗口里的策略是 `local-edge-only-deform`，说明走的就是“只变这条边”的局部形变路径。
+  - 如果模型不是简单全平面多面体，直线Edge会继续尝试端面推拉后备路径，并计算需要移动的端面Face和推拉距离。
+  - 圆形/圆弧Edge会优先尝试复用相邻圆柱面的孔/槽或凸台直径编辑，并在确认窗口显示换算出来的目标直径。
+  - 如果圆边没有可复用圆柱面，但能读取圆心和轴线，会走 `围绕圆边轴线径向缩放` 后备策略，尽量不改变轴向厚度/高度；执行后部分解析几何可能变成 B-spline。
+  - 椭圆边、平面 B-spline / Bezier 边会尝试走 `围绕平面曲线法向径向缩放`；确认窗口会显示平面采样偏差，偏差不稳定时会回退到更保守的缩放 fallback。
+  - `固定起点` 会让起点不动、移动终点；`固定终点` 相反；`中心` 会让两端各移动一半，只有进入缩放 fallback 时才会变成以Edge中心为基准缩放。
+  - 如果没有明确端面或可复用圆柱面，程序会按所选基准尝试整体/轴向几何缩放 fallback；这会影响所属Part/Solid的其它尺寸，因此会弹出高风险确认。
+  - 执行成功后会做后置边长校验：在刷新后的Part/Solid范围内寻找最接近目标长度的Edge，并把实际最近边长、误差和相对误差写入操作结果。
   - 通过检查后，会显示蓝绿色半透明预览，表示将要移动或缩放的范围。
   - 真实编辑在后台执行，失败时会回滚到编辑前状态。
-  - 这是第一版 B-Rep 结果几何修改，不是任意边参数化改长。
-- `平移 X/Y/Z` + `平移选中零件` / `平移选中 solid`：
+  - 这是当前版本的 B-Rep 结果几何修改，不是任意边参数化改长。
+- `平移 X/Y/Z` + `平移选中零件` / `平移选中Solid`：
   - 输入 X、Y、Z 三个方向的平移量。
-  - 选择 `Part` 后点击 `平移选中零件`，会移动整个 part。
-  - 选择 `Solid`，或选择属于某个 solid 的 face/edge 后，点击 `平移选中 solid`，会移动当前 solid。
-  - 如果当前 part 只有一个 solid，平移 solid 实际会移动整个 part shape，程序会提示中风险。
+  - 选择 `Part` 后点击 `平移选中零件`，会移动整个Part。
+  - 选择 `Solid`，或选择属于某个Solid的Face/Edge后，点击 `平移选中Solid`，会移动当前Solid。
+  - 如果当前Part只有一个Solid，平移Solid实际会移动整个Part shape，程序会提示中风险。
   - 平移向量为 0 会直接阻止。
   - 如果平移距离相对对象包围盒过大，程序会提高风险并要求确认。
   - 平移属于真实 B-Rep 变换，会写入操作历史，可以撤销/重做。
-- `旋转轴/角度` + `旋转选中零件` / `旋转选中 solid`：
+- `旋转轴/角度` + `旋转选中零件` / `旋转选中Solid`：
   - 选择 X、Y 或 Z 旋转轴。
   - 输入旋转角度，单位是度。
-  - 选择 `Part` 后点击 `旋转选中零件`，会绕该 part 的包围盒中心旋转整个 part。
-  - 选择 `Solid`，或选择属于某个 solid 的 face/edge 后，点击 `旋转选中 solid`，会绕该 solid 的包围盒中心旋转当前 solid。
-  - 如果当前 part 只有一个 solid，旋转 solid 实际会旋转整个 part shape，程序会提示中风险。
+  - 选择 `Part` 后点击 `旋转选中零件`，会绕该Part的包围盒中心旋转整个Part。
+  - 选择 `Solid`，或选择属于某个Solid的Face/Edge后，点击 `旋转选中Solid`，会绕该Solid的包围盒中心旋转当前Solid。
+  - 如果当前Part只有一个Solid，旋转Solid实际会旋转整个Part shape，程序会提示中风险。
   - 旋转角度为 0 会直接阻止；角度超过 360 度会提高风险并要求确认。
   - 旋转属于真实 B-Rep 变换，会写入操作历史，可以撤销/重做。
 - `撤销`：
-  - 撤销上一次成功的实验性编辑。
+  - 撤销上一次成功的编辑。
 - `重做`：
-  - 重做刚刚撤销的实验性编辑。
+  - 重做刚刚撤销的编辑。
 - `操作历史`：
-  - 显示当前模型已经成功执行的实验性编辑。
+  - 显示当前模型已经成功执行的编辑。
   - 点击某条历史记录，会在 `选中对象信息` 中显示该次编辑的目标、参数、执行结果和拓扑数量变化。
   - 历史详情也会显示几何差异摘要，包括体积、表面积、包围盒尺寸和包围盒对角线的前后变化。
   - 点击某条历史记录时，3D 窗口会显示红/绿半透明差异叠加预览：红色表示编辑前，绿色表示编辑后。
@@ -613,13 +651,27 @@ python main.py --smoke-test
   - 历史详情会显示热力图统计，包括最大距离、平均距离和发生明显变化的采样点比例。
   - `清除差异预览` 可以关闭红/绿叠加显示。
   - `导出差异报告` 会把当前选中的历史记录导出为 `.txt`，里面包含操作详情、拓扑变化、几何变化和热力图统计。
-  - `导出编辑历史` 会把当前会话中的本软件编辑记录导出为 `.json`，用于留档和后续复盘。
+  - `导出编辑历史` 会把当前会话中的本软件编辑记录导出为 `.json`，用于留档和后续复盘；当前格式是 `step-editor-operation-history-v2`，包含机器可读的动作名、目标和参数。
   - 当前热力图是“编辑后模型顶点到编辑前模型表面”的距离估算，不是完整 CAD 公差报告。
-  - 点击某条历史记录时，程序也会尝试重新高亮当时编辑的目标 face，并用青色小点标出当时的拾取位置。
-  - 由于布尔编辑后拓扑 ID 可能重新分配，历史里的 face ID 只能作为定位参考，不能视为稳定的 CAD 建模历史 ID。
+  - 点击某条历史记录时，程序也会尝试重新高亮当时编辑的目标Face，并用青色小点标出当时的拾取位置。
+  - 由于布尔编辑后拓扑 ID 可能重新分配，历史里的Face ID只能作为定位参考，不能视为稳定的 CAD 建模历史 ID。
   - 撤销后对应记录会从列表里退回。
   - 重做后对应记录会重新显示。
 
+导出：
+
+- `导出当前完整 STEP`：导出当前完整模型。
+- `导出选中零件`：导出当前选中的零件。
+- `导出选中Solid`：先选中一个Solid，再导出该Solid。
+- `导出选中面区域`：先切换到 `Face` 选择模式并选中一个Face，再导出该Face或同域面区域。
+- `导出选中特征区域`：先切换到 `Feature` 选择模式并选中局部特征，再导出当前特征高亮的Face集合。
+- `导出选中Edge`：先切换到 `Edge` 选择模式并选中一个Edge，再导出该Edge。
+- `检查导出质量`：检查当前选中对象；如果没有选中对象，就检查当前完整模型。
+- `修复当前模型`：对当前完整模型执行 ShapeFix 和同域面/边合并，完成后会刷新显示并写入操作历史；如果修复失败，会尝试回滚到修复前状态。
+- `修复选中零件/Solid`：优先修复当前选中对象所属Solid；如果当前对象没有Solid，则修复所属零件。Face或Edge被选中时，也会按其所属Solid/零件执行局部修复。
+- 导出按钮会根据当前选中对象自动启用或禁用，避免选中Face时误点 `导出选中Edge` 这类不匹配的操作。
+- 所有导出按钮都会先做质量检查。发现 B-Rep 无效、没有Solid、零件包含多个Solid、体积接近 0 等风险时，会先弹窗确认是否继续导出。
+
 ## 目录结构
 
 当前整理后的项目结构是：
@@ -627,8 +679,14 @@ python main.py --smoke-test
 ```text
 pythonocc-step-editor/
   main.py                 # 程序入口，保持 python main.py 启动
-  docs/
-    screenshots/          # 调试截图和问题截图
+  assets/
+    models/
+      geom_extract.step   # 当前默认测试模型
+      cube_10mm.step      # 简单立方体测试模型，用于验证边长修改等基础操作
+    screenshots/          # 调试截图和问题截图，默认不提交
+  scripts/
+    generate_cube_step.py # 生成 assets/models/cube_10mm.step 的小工具
+    verify_edge_length_resize.py # 验证立方体 Edge 长度局部形变基线
   step_editor/
     __init__.py           # 包导出
     app.py                # 主窗口初始化、UI 搭建和程序启动
@@ -640,10 +698,10 @@ pythonocc-step-editor/
     model.py              # StepModel 核心状态、拓扑索引、基础属性和 mixin 组合
     model_types.py        # PartNode、TopologyStats 等模型数据结构
     operations.py         # 推拉、孔径、孔深、圆角、倒角、边长等实际编辑操作
-    polydata.py           # OCC shape / edge / face 到 VTK polydata 的显示数据生成
+    polydata.py           # OCC Shape / Edge / Face 到 VTK polydata 的显示数据生成
     records.py            # 操作历史记录数据结构
     step_io.py            # STEP/XCAF 读取、产品名解析和 STEP 写出
-    transforms.py         # part / solid 平移和旋转
+    transforms.py         # Part / Solid 平移和旋转
     ui_helpers.py         # UI 常量、格式化函数和 VTK 显示小工具
     widgets.py            # 自定义 Qt 小组件
     window_actions.py     # 导出、编辑按钮、扫描、后台编辑调度等窗口动作
@@ -651,11 +709,10 @@ pythonocc-step-editor/
     window_state.py       # 选择状态、按钮状态、撤销/重做和历史定位
     workers.py            # 后台编辑和后台扫描 worker
   environment.yml         # Conda 环境说明，用于安装 pythonocc-core、VTK、PySide6 等依赖
-  geom_extract.step       # 当前默认测试模型
   README.md               # 项目说明和使用说明
 ```
 
-这次整理把根目录收窄到入口、环境配置、默认模型和文档，主要代码放到 `step_editor/` 包里；问题截图和调试截图放到 `docs/screenshots/`。后端和窗口层都按 mixin / 工具模块拆开，尽量不改变功能行为。
+这次整理把根目录收窄到入口、环境配置和说明文档；仓库自带 STEP 测试模型放到 `assets/models/`，问题截图和调试截图放到 `assets/screenshots/`。`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`。
 
@@ -665,10 +722,117 @@ pythonocc-step-editor/
 
 - `.gitignore`：Git 忽略规则，避免提交 Python 缓存、临时文件和导出的 STEP 文件。
 - `*_edited.step`、`*_export.step`、`*_diff_*.txt`、`*_operation_history.json`：运行或导出时产生的结果文件，默认不提交。
-- `docs/screenshots/`：调试截图和问题截图，例如第三方软件显示效果、模型结构树截图等。
+- `assets/models/`：仓库自带的 STEP 测试模型，可以提交；运行时导出的 STEP 结果仍然默认忽略。
+- `assets/screenshots/`：调试截图和问题截图，例如第三方软件显示效果、模型结构树截图等，默认不提交。
 
 ## 当前版本边界
 
 这一版重点是验证整体链路，不是最终 CAD 编辑器。
 
-模型显示、选择、属性查看、撤销/重做和导出是当前主要能力。局部编辑已经接入，但仍属于实验性能力。复杂 STEP 几何上的布尔操作可能失败；失败时程序会弹窗提示，不会静默覆盖原始文件。
+模型显示、选择、属性查看、撤销/重做和导出是当前主要能力。局部编辑已经接入，但仍属于受限 B-Rep 能力。复杂 STEP 几何上的布尔操作可能失败；失败时程序会弹窗提示，不会静默覆盖原始文件。
+
+## Codex 项目记忆（开发者可忽略）
+
+这一节只给后续重新打开的 Codex 聊天框使用，普通开发者不需要阅读。Codex 接手时先读这里，再读本 README 的“目录结构”和“当前版本边界”。
+
+### 项目目标
+
+本项目是一个基于 Python、pythonocc-core/OCCT、VTK 和 PySide6/Qt 的 STEP 查看与局部编辑原型。它处理的是 STEP 里的 B-Rep 结果几何，不是原 CAD 软件的完整参数化建模历史。
+
+最小系统目标是打通：加载 STEP、显示模型、选择 Part/Solid/Face/Edge/Feature、查看属性、识别初步候选特征、执行受限局部编辑、撤销/重做、质量检查和导出。
+
+### 运行方式
+
+常用命令：
+
+```powershell
+conda activate pyocc
+python main.py
+python main.py assets\models\cube_10mm.step
+python scripts\generate_cube_step.py
+python scripts\verify_edge_length_resize.py
+python main.py --smoke-test
+```
+
+如果 shell 里没有 `conda`，用户机器上之前可用的方式是：
+
+```powershell
+C:\Users\admin\miniforge3\Scripts\conda.exe run -n pyocc python main.py
+```
+
+当前 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_edge_length_resize.py`：加载 `cube_10mm.step`，把一条 10mm 直线 Edge 改到 15mm，并断言策略是 `local-edge-only-deform`、目标边长误差在容差内。
+- `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 后台加载：首次先显示粗略网格，再异步切到精细显示，并可隐藏同域内部边。
+- 选择：支持 Part、Solid、Face、Edge、Feature。鼠标悬停红色预高亮，选中黄色高亮。
+- 同域面：Face/Feature 会尽量把共面或同轴同半径的连续碎面合成逻辑区域。
+- 编辑：平面推拉、孔径、槽/半孔宽度、盲孔/盲槽深度、凸台直径、已有圆角半径当前版本修改、Edge圆角、Edge倒角、薄壁厚度、修改Edge长度、Part/Solid 平移和旋转。
+- 恢复：编辑前快照、后台执行、失败回滚、撤销/重做、差异预览、热力图和差异报告。
+- 导出：完整模型、Part、Solid、Face、Feature 区域和 Edge，导出前做基础质量检查。
+
+### 修改Edge长度
+
+这是当前继续深入的功能，但仍是 B-Rep 结果几何编辑，不是参数化历史恢复。
+
+当前策略顺序：
+
+1. `local-edge-only-deform`：直线Edge位于简单全平面多面体时，优先只移动被选Edge的端点并重建所属Solid/Part。对立方体测试模型，默认固定起点移动终点；相邻面会自然变成梯形，必要时非共面四边面拆三角面，而不是把整个正方体缩放成长方体。
+2. `move-edge-end-plane-by-push-pull`：如果不适合局部形变，尝试找端点附近、方向匹配的平面端面，把改边长转成端面推拉。
+3. `resize-adjacent-cylinder-from-circular-edge-length`：圆形/圆弧Edge尝试复用相邻圆柱孔/槽或凸台直径编辑。
+4. `scale-owning-shape-from-edge`：圆边、椭圆边和可采样为平面的非直线Edge会优先用 `radial-affine` 围绕曲线平面法向做径向缩放；其他无明确局部路径的Edge才按Edge轴向或整体做几何缩放 fallback，风险高，会影响其它尺寸。
+
+确认窗口和操作历史里要尽量记录策略、目标范围、目标Edge长度、基准、移动端点、重建面数和风险，方便用户判断结果是否符合预期。
+
+最近一次基线验证：在 `assets/models/cube_10mm.step` 上选第一条直线Edge，将 10mm 改为 15mm，计划策略为 `local-edge-only-deform`，内存执行成功。执行后边长分布为 `10:9, 11.1803:2, 14.1421:1, 15:1`，Face数从 6 变 7，说明没有整体拉成长方体，而是局部重建并拆分了一个非共面面。
+
+新增基线验证：内存构造椭圆Edge，将长度放大 1.25 倍，计划策略为 `radial-affine`，通过预变换Edge长度把缩放比例从 `1.25` 微调到约 `1.25354`，结果边长贴合目标。另一个圆锥圆边先径向缩放后会变成 B-spline，再选这个平面 B-spline Edge 放大 1.1 倍，计划会走 `sampled edge best-fit plane`，采样偏差约 `3.6e-15`，结果边长贴合目标。
+
+后置校验基线：修改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` 或回滚不相关文件。