支持布尔操作按帧范围执行

- 区域合并和重叠区域去除新增“按帧范围选择”，复用底部时间轴范围选择并在执行前二次确认

- 布尔操作范围只处理所选帧内存在对应传播链的区域，范围外传播 mask 保持不变

- 自动传播范围选择时在顶栏显示传播权重，以及相对参考帧的向前/向后传播帧数

- Canvas 将传播链布尔操作委托给工作区统一处理范围选择，同时保留当前帧/所有传播帧快捷操作

- 增加 CanvasArea、VideoWorkspace 回归测试，覆盖布尔操作范围选择、范围执行和自动传播方向摘要

- 更新 AGENTS 与前端审计、需求冻结、设计冻结、测试计划文档

AGENTS.md

@@ -244,9 +244,9 @@ uvicorn main:app --host 0.0.0.0 --port 8000 --reload
 5. 生成帧入队：用户在项目库点击“生成帧”，选择目标 FPS 后前端调用 `/api/media/parse`；后端创建 `ProcessingTask` 并投递 Celery，接口支持 `parse_fps`、`max_frames` 和 `target_width` 标准帧序列参数；项目库和模板库的成功/失败短反馈使用非阻塞 `TransientNotice`，会自动消失。
 6. worker 执行：Celery worker 用 FFmpeg 优先拆视频帧，失败后用 OpenCV fallback，DICOM 使用 pydicom；worker 下载和读取 DICOM 时也按文件名自然顺序排序；视频/DICOM 解析完成后都按 `frame_%06d.jpg` 连续生成项目帧序列，并记录 `timestamp_ms`、`source_frame_number` 和任务 `frame_sequence` 元数据，后续工作区、时间轴、AI 传播、标注和导出共用同一套帧序列逻辑。
 7. 帧展示：`VideoWorkspace.tsx` 调用 `/api/projects/{id}/frames`，`CanvasArea.tsx` 和 `FrameTimeline.tsx` 显示当前帧与时间轴缩略图；`CanvasArea` 会按容器和帧尺寸默认居中放大底图并保留边距；`FrameTimeline` 会根据已保存标注回显到 `Mask.metadata` 的传播来源，把自动传播生成的帧在视频处理进度条显示为蓝色区段，人工/AI 标注帧显示红色竖线；每次自动传播成功处理帧后，`VideoWorkspace` 会把本次传播范围作为当前会话历史片段传给 `FrameTimeline`，在视频处理进度条上叠加同一蓝色系、最新传播最亮、旧传播逐次变暗且第 5 次及更早统一为阈值旧记录色的纯色条；传播历史条只显示当前仍有自动传播 mask 的帧，删除 mask 或清空范围后会按剩余传播 mask 自动裁剪，空帧不保留红/蓝颜色；视频处理进度条和红/蓝标识可点击跳转到对应帧；底部缩略图中人工/AI 标注帧用红色边框、自动传播/推理帧用蓝色边框，同一帧同时具备两种状态时红色标注边框优先保留，蓝色传播状态以内描边表达；当前帧仍以青色外框高亮优先；若当前帧同时是人工/AI 标注帧，则在青色外框内增加红色内描边，固定为外层当前帧、内层人工/AI 标注；进入自动传播、清空遮罩或特定范围帧导出选择模式时，播放进度条和视频处理进度条会显示黄色范围框，并可点击/拖拽选择起止帧；前端 `Frame` 会保留后端返回的帧序列时间戳和源帧号。
-8. 手工标注：`CanvasArea.tsx` 支持多边形、矩形、圆、画笔和橡皮擦生成/编辑 polygon mask；多边形可按 Enter 或点击首节点闭合；画笔/橡皮擦可在左侧工具栏调整大小，画笔要求右侧语义分类树已有选中类别，画出的圆形连续笔触会在鼠标松开时一次性 union 成 mask，若与当前选中 mask 连通则自动合并到该 mask，橡皮擦要求已选中 mask 并在松开时从该 mask 中 difference 扣除；普通 mask 和导入 mask 都不显示黄色 seed point，也不提供 seed point 拖动；未选中特定 mask 时，Canvas 会按右侧语义分类树拖拽得到的内部覆盖优先级从低到高渲染 mask，使高优先级类别显示在上层；Canvas 左上角工具上下文提示会在切换工具或操作状态变化时短暂显示，数秒后自动隐藏，避免长期遮挡底图；工具栏有“调整多边形”入口，左侧 `ToolsPalette` 使用紧凑垂直布局并在高度不足时自身滚动，基础绘制、画笔/橡皮擦、布尔/删除、导入/AI 入口之间用浅灰分隔线区分；布尔/删除组包含区域合并、重叠区域去除、`DEL` 和“清空遮罩”，其后通过 `data-testid="tool-group-separator"` 分隔紫色“导入 GT Mask”和 AI 智能分割入口；清空遮罩优先作用于当前帧选中 mask，没有选中时作用于当前帧全部 mask；无传播链结果时直接清当前帧，存在传播链结果时弹窗选择只清当前帧、清空所有传播帧、按帧范围选择或取消；按帧范围选择进入时间轴范围模式，并提供清空全部/保留人工AI；Canvas 右下角不再提供旧的“清空遮罩”或“应用分类”按钮，分类改由右侧语义分类树点击完成；工作区左侧工具栏不展示 AI 页的正向选点、反向选点和边界框选，也不重复放置撤销/重做；点击 mask 后可按住顶点直接拖动并实时更新 polygon，顶点拖拽结束不会触发 Stage 平移或重置 Canvas 视口；也可删除 polygon 顶点、通过边中点或双击边界插入新顶点；多 polygon/分离区域组成的同一 mask 进入编辑时所有子区域都会显示顶点和插点手柄，同帧同传播链的分散 mask 点选时会联动高亮；带中空洞的 mask 会用 `metadata.polygonRingCounts` 记录外圈与内圈的 ring 分组，调整多边形时外圈和内洞都显示可编辑顶点和插点手柄，保存时把内洞拆到 `mask_data.holes`；选中整块 mask 可用 Delete/Backspace 或左侧 `DEL` 删除，已保存 mask 删除前会预检当前后端 annotation id，只对仍存在的 id 调用后端删除，避免陈旧本地 id 产生 DELETE 404；删除传播 seed 或任一传播结果时会扩展删除同一传播链上的自动传播 mask，但保留其他帧独立 AI 推理或人工标注 mask；区域合并/去除会隐藏编辑手柄并显示已选数量，第一个选中的主区域用黄色实线轮廓，后续参与合并/扣除的区域用红色虚线轮廓，使用 `polygon-clipping` 做 union/difference，若存在传播帧对应 mask 会先弹窗选择只处理当前帧或处理所有传播帧，并通过 `source_annotation_id`、`source_mask_id` 和 `propagation_seed_key` 把同一布尔操作同步到其它传播帧的对应主区域和参与区域；同步后的传播 mask 保留原 `source`/lineage metadata，只进入 dirty 状态等待保存，不会在时间轴上变成人工/AI 标注帧；内含去除结果用 even-odd 规则渲染 hole；Zustand 维护 `maskHistory/maskFuture` 支持撤销/重做。
+8. 手工标注：`CanvasArea.tsx` 支持多边形、矩形、圆、画笔和橡皮擦生成/编辑 polygon mask；多边形可按 Enter 或点击首节点闭合；画笔/橡皮擦可在左侧工具栏调整大小，画笔要求右侧语义分类树已有选中类别，画出的圆形连续笔触会在鼠标松开时一次性 union 成 mask，若与当前选中 mask 连通则自动合并到该 mask，橡皮擦要求已选中 mask 并在松开时从该 mask 中 difference 扣除；普通 mask 和导入 mask 都不显示黄色 seed point，也不提供 seed point 拖动；未选中特定 mask 时，Canvas 会按右侧语义分类树拖拽得到的内部覆盖优先级从低到高渲染 mask，使高优先级类别显示在上层；Canvas 左上角工具上下文提示会在切换工具或操作状态变化时短暂显示，数秒后自动隐藏，避免长期遮挡底图；工具栏有“调整多边形”入口，左侧 `ToolsPalette` 使用紧凑垂直布局并在高度不足时自身滚动，基础绘制、画笔/橡皮擦、布尔/删除、导入/AI 入口之间用浅灰分隔线区分；布尔/删除组包含区域合并、重叠区域去除、`DEL` 和“清空遮罩”，其后通过 `data-testid="tool-group-separator"` 分隔紫色“导入 GT Mask”和 AI 智能分割入口；清空遮罩优先作用于当前帧选中 mask，没有选中时作用于当前帧全部 mask；无传播链结果时直接清当前帧，存在传播链结果时弹窗选择只清当前帧、清空所有传播帧、按帧范围选择或取消；按帧范围选择进入时间轴范围模式，并提供清空全部/保留人工AI；Canvas 右下角不再提供旧的“清空遮罩”或“应用分类”按钮，分类改由右侧语义分类树点击完成；工作区左侧工具栏不展示 AI 页的正向选点、反向选点和边界框选，也不重复放置撤销/重做；点击 mask 后可按住顶点直接拖动并实时更新 polygon，顶点拖拽结束不会触发 Stage 平移或重置 Canvas 视口；也可删除 polygon 顶点、通过边中点或双击边界插入新顶点；多 polygon/分离区域组成的同一 mask 进入编辑时所有子区域都会显示顶点和插点手柄，同帧同传播链的分散 mask 点选时会联动高亮；带中空洞的 mask 会用 `metadata.polygonRingCounts` 记录外圈与内圈的 ring 分组，调整多边形时外圈和内洞都显示可编辑顶点和插点手柄，保存时把内洞拆到 `mask_data.holes`；选中整块 mask 可用 Delete/Backspace 或左侧 `DEL` 删除，已保存 mask 删除前会预检当前后端 annotation id，只对仍存在的 id 调用后端删除，避免陈旧本地 id 产生 DELETE 404；删除传播 seed 或任一传播结果时会扩展删除同一传播链上的自动传播 mask，但保留其他帧独立 AI 推理或人工标注 mask；区域合并/去除会隐藏编辑手柄并显示已选数量，第一个选中的主区域用黄色实线轮廓，后续参与合并/扣除的区域用红色虚线轮廓，使用 `polygon-clipping` 做 union/difference，若存在传播帧对应 mask 会先弹窗选择只处理当前帧、处理所有传播帧或按帧范围选择；按帧范围选择会进入时间轴范围选择并二次确认，只把同一布尔操作同步到所选范围内具备对应关系的传播帧；同步后的传播 mask 保留原 `source`/lineage metadata，只进入 dirty 状态等待保存，不会在时间轴上变成人工/AI 标注帧；内含去除结果用 even-odd 规则渲染 hole；Zustand 维护 `maskHistory/maskFuture` 支持撤销/重做。
 9. AI 分割：侧栏和工作区工具栏的 AI 智能分割入口使用 Bot + Sparkles 组合图标强化 AI 识别；前端工具包括 SAM 2.1 变体选择、正向点、反向点和框选；AI 画布会按容器和当前帧尺寸默认居中放大底图并保留边距；工作区和 AI 页面都可点击已有提示点删除单点，AI 页面也可删除最近锚点、删除选中候选或清空本页锚点；这些删除入口会限制在当前提示点/本页 AI 候选范围内，避免误删工作区已有 mask。SAM 2.1 框选会建立候选 mask，后续正/反点通过 `interactive` prompt 携带原始框和累计点细化同一个候选 mask；AI 页面框选会先固化 `promptBox`，执行分割时只框选发送 `box` prompt，框选后继续加正/反点发送 `interactive` prompt；重复执行高精度分割会替换上一次 AI 页候选，只保留最新一个候选。包含反向点时工作区会传 `options.auto_filter_background=true` 和 `min_score=0.05`，如果后端过滤为空则移除旧候选 mask。后端 `ai.py` 期望按 `image_id`、`prompt_type`、`prompt_data`、`model` 和可选 `options` 调用 SAM registry。当前 registry 暴露 `sam2.1_hiera_tiny`、`sam2.1_hiera_small`、`sam2.1_hiera_base_plus`、`sam2.1_hiera_large`，并兼容 `sam2` 作为 tiny 别名；`model=sam3` 会被拒绝，`semantic` 文本提示也被禁用。SAM 2.1 支持点/框/interactive/自动分割和 video predictor 传播；多候选默认只采用最高分区域，避免重叠候选同时显示；AI 页面只渲染本页最新生成的候选 mask，不会把工作区已有 mask 带入 AI 画布；AI 页面生成的 mask 会写入全局 `masks` 并自动选中，右侧分类树可直接改标签，推送到工作区会切到“调整多边形”并保留选择和当前帧视角。`options.crop_to_prompt` 可对点/框/interactive prompt 做局部裁剪推理并回映射，`options.auto_filter_background` 可按分数和负向点过滤结果。
-10. 视频片段传播：工作区以当前打开帧作为参考帧，使用该帧全部 mask 作为 seed，并用传播起始帧和传播结束帧指定追踪范围；如果当前参考帧没有 mask，点击开始传播会提示“当前参考帧无遮罩”，不会提交任务或保存其它帧标注；用户可直接修改数字框，也可点击“自动传播”进入时间轴范围选择模式，在播放进度条或视频处理进度条上点击/拖拽选择范围，再点击“开始传播”。工作区顶栏有独立“传播权重”选择器，可为本次传播二次选择 SAM 2.1 tiny/small/base+/large 权重，不提供 SAM2/SAM3 家族切换，也不影响 AI 单帧分割权重；前端提交传播前只保存当前参考帧中的 draft/dirty mask，使 seed 优先带稳定的后端 `source_annotation_id`，再按传播权重 id、seed mask、seed 来源 id 和前/后方向组装 `steps` 并调用 `POST /api/ai/propagate/task` 创建 `propagate_masks` 后台任务；中空 seed 会携带和 `polygons` 对齐的 `holes`，后端注入 SAM 2 video predictor 前会先填充外圈再扣除内洞，避免以实心 mask 传播；后端入队时会规范化/校验权重 id 并把规范化后的 id 写入任务 payload/result；Celery worker 顺序执行各 step，避免多个视频 tracker 并发抢占 GPU；每个 step 会根据 seed 来源 id、方向和包含 `holes` 的 seed 签名做幂等判断，同权重且未改变的 seed 直接跳过，已改变或换用其他权重的 seed 会先删除同源旧自动传播标注再重传；旧版本用前端临时 `source_mask_id` 生成的传播标注会按同一参考帧、方向和语义信息兼容清理；中间帧人工新增/修改同一物体后重新传播时，后端会在写入目标帧新结果前按语义和空间重叠清理旧传播结果，且写入前清理不受旧结果传播方向限制；后端按项目帧序列下载片段帧，当前使用所选 SAM 2.1 权重变体的 `SAM2VideoPredictor.add_new_mask()` + `propagate_in_video()`，并把后续帧结果保存为 `Annotation`，传播结果轮廓用 CCOMP 层级提取并把内洞写入 `mask_data.holes`；若历史或外部 seed 仍带 `geometry_smoothing`，forward/backward 两个方向的传播结果保存前仍会应用同一参数；当前工作区平滑按钮应用后会直接改写实际 polygon，后续传播以新几何参与签名和追踪。工作区轮询 `GET /api/tasks/{task_id}` 展示进度并刷新标注，Dashboard 也能显示/取消/重试传播任务。
+10. 视频片段传播：工作区以当前打开帧作为参考帧，使用该帧全部 mask 作为 seed，并用传播起始帧和传播结束帧指定追踪范围；如果当前参考帧没有 mask，点击开始传播会提示“当前参考帧无遮罩”，不会提交任务或保存其它帧标注；用户可直接修改数字框，也可点击“自动传播”进入时间轴范围选择模式，在播放进度条或视频处理进度条上点击/拖拽选择范围，再点击“开始传播”。工作区顶栏有独立“传播权重”选择器，可为本次传播二次选择 SAM 2.1 tiny/small/base+/large 权重，不提供 SAM2/SAM3 家族切换，也不影响 AI 单帧分割权重；进入自动传播范围选择时，顶栏会显示当前传播权重以及相对参考帧的向前/向后帧数；前端提交传播前只保存当前参考帧中的 draft/dirty mask，使 seed 优先带稳定的后端 `source_annotation_id`，再按传播权重 id、seed mask、seed 来源 id 和前/后方向组装 `steps` 并调用 `POST /api/ai/propagate/task` 创建 `propagate_masks` 后台任务；中空 seed 会携带和 `polygons` 对齐的 `holes`，后端注入 SAM 2 video predictor 前会先填充外圈再扣除内洞，避免以实心 mask 传播；后端入队时会规范化/校验权重 id 并把规范化后的 id 写入任务 payload/result；Celery worker 顺序执行各 step，避免多个视频 tracker 并发抢占 GPU；每个 step 会根据 seed 来源 id、方向和包含 `holes` 的 seed 签名做幂等判断，同权重且未改变的 seed 直接跳过，已改变或换用其他权重的 seed 会先删除同源旧自动传播标注再重传；旧版本用前端临时 `source_mask_id` 生成的传播标注会按同一参考帧、方向和语义信息兼容清理；中间帧人工新增/修改同一物体后重新传播时，后端会在写入目标帧新结果前按语义和空间重叠清理旧传播结果，且写入前清理不受旧结果传播方向限制；后端按项目帧序列下载片段帧，当前使用所选 SAM 2.1 权重变体的 `SAM2VideoPredictor.add_new_mask()` + `propagate_in_video()`，并把后续帧结果保存为 `Annotation`，传播结果轮廓用 CCOMP 层级提取并把内洞写入 `mask_data.holes`；若历史或外部 seed 仍带 `geometry_smoothing`，forward/backward 两个方向的传播结果保存前仍会应用同一参数；当前工作区平滑按钮应用后会直接改写实际 polygon，后续传播以新几何参与签名和追踪。工作区轮询 `GET /api/tasks/{task_id}` 展示进度并刷新标注，Dashboard 也能显示/取消/重试传播任务。
 11. GT 导入：工作区左侧工具栏“导入 GT Mask”调用 `/api/ai/import-gt-mask`；选择文件后前端会显示导入结果预览，并让用户决定未知 maskid 处理方式，可舍弃未知类别，也可导入为“未定义类别”等待重新命名。后端用 `cv2.IMREAD_UNCHANGED` 读取 mask 并校验 dtype；GT 图片必须是 8-bit 灰度 maskid 图，或 8-bit RGB 三通道完全相同的 `[X,X,X]` maskid 图，0 为背景、X 为 1-255 的 maskid，16-bit/uint16 GT_label、普通彩色类别图和全背景 0 图都会返回明确错误；全背景图错误信息固定为“GT Mask 图片中没有非背景 maskid 区域。”；灰度/RGB 等通道图按模板 `maskId` 匹配类别，超出现有类别时按 `unknown_color_policy` 处理；如果 mask 图片尺寸和当前帧不同，会按当前帧长宽最近邻拉伸后再提取区域；每个连通域用高精度 contour 生成 polygon 标注，保留更多边界点并设置点数上限避免拖慢前端；导入结果与普通 mask 共用拓扑锚点统计、边缘平滑、顶点编辑、分类和保存链路；后端仍可写入 distance transform seed point 供数据兼容，但前端不显示或拖动 seed point。
 12. 模板管理：`TemplateRegistry.tsx` 管理分类、颜色、maskid 和内部覆盖顺序；所有新建、复制、批量导入和后端返回的模板都会归一化包含黑色 `[0,0,0]`、`maskid: 0` 的“待分类”保留类，该类固定在语义分类树最后，不能删除，也不能拖拽到更高层级；批量导入 JSON 支持 `[[colors], [names]]` 和 `{colors, names}` 两种格式，也兼容带“批量导入分类：”前缀、代码块、未加引号 keys、单引号、中文逗号/冒号和尾随逗号的粘贴内容，会先预览分类数量、maskid 分配起点和缺失颜色提示，语法或结构错误以内联错误展示；系统默认模板包括“腹腔镜胆囊切除术”和“头颈部CT分割”，头颈部 CT 默认分类名使用纯中文（肿瘤/结节、下颌骨、甲状腺、气管、颈椎、颈动脉、颈静脉、腮腺、下颌下腺、舌骨），恢复演示出厂设置只删除用户私有模板，并会重建缺失的系统默认模板、覆盖恢复被修改或删减的默认语义分类树；模板库“生效中模板架构清单”里的每个模板卡片支持鼠标点击复制，复制会创建当前用户私有副本并保留分类名称、颜色、maskid、内部层级和规则，同时重建类别内部 id；模板库详情页的分类区标题为“语义分类树（拖拽调层级）”，右上角提供带 Edit 图标的“编辑模板”按钮，每个分类行右侧用垃圾桶图标删除该 label，不再展示“未分类/批量导入/模板名”等来源标签；编辑模板弹窗点击分类后只编辑分类名称，不展示或编辑旧 `category` 来源元信息；如果项目中的已保存 mask 引用了当前模板里已被删除的类别，工作区打开项目回显时会把该 mask 降级为 `maskid: 0` 的“待分类”mask 并标记为待保存；项目已有任意 mask 时，用户在右侧本体面板修改激活模板必须先确认，确认后删除当前项目所有已有 mask/后端标注再切换；项目没有任何 mask 时可直接切换；模板库详情页和编辑弹窗都支持拖拽调整语义类别层级顺序，拖拽会重算 `zIndex` 并保存到后端，保存后当前详情页会立刻刷新；`OntologyInspector.tsx` 在工作区显示当前模板分类树，也支持拖拽调整内部覆盖顺序。maskid 只作为 GT_label/类别 ID，不参与排序。
 13. 导出：工作区使用统一“分割结果导出”入口，导出前先保存待归档 mask；用户可选择整体视频、特定范围帧或当前图片，默认导出范围为当前图片，并勾选分开二值 mask、GT_label 黑白图、Pro_label 彩色图和 Mix_label 原图叠加图。选择特定范围帧时，可直接修改起止帧输入框，也可在播放进度条或视频处理进度条上点击/拖拽选择导出范围；选择 Mix_label 时可调透明度，默认 0.3，并显示当前/待导出第一帧预览。下载 ZIP 文件名使用 `{项目库项目名}_seg_T_{起始时间戳}-{结束时间戳}_P_{起始项目帧序号}-{结束项目帧序号}.zip`，项目名来自 `Project.name` 并替换文件系统不安全字符，时间戳格式为 `0h00m00s000ms`，帧号使用项目抽帧后的 1-based 顺序而非原视频帧号。后端保留兼容的 COCO JSON 和 PNG mask ZIP 接口，同时新增统一结果 ZIP；统一 ZIP 固定包含 `annotations_coco.json`、`maskid_GT像素值_类别映射.json` 和 `原始图片/`；导出时 GT_label 固定写 8-bit uint8 PNG，像素值使用类别真实 `maskid`，其中 `maskid: 0` 的“待分类”与背景同为 0，Pro_label 中也与背景同为黑色 `[0,0,0]`，缺失 `maskid` 的旧标注才补下一个可用值，正整数 maskid 超出 1-255 会拒绝导出，保证导出的 GT_label 可按同一模板再导入；选择分开 mask 时输出 `分开Mask分割结果/{视频名称_时间戳_项目帧序号}_分别导出/{视频名称_时间戳_项目帧序号}_{类别名称}_maskid{maskid}.png`，同一帧同一类别合并为一张图；选择 GT_label/Pro_label/Mix_label 时分别输出 `GT_label图/{视频名称_时间戳_项目帧序号}.png`、`Pro_label彩色分割结果/{视频名称_时间戳_项目帧序号}.png`、`Mix_label重叠覆盖彩色分割结果/{视频名称_时间戳_项目帧序号}.png`。maskid 不参与覆盖排序，GT_label/Pro_label/Mix_label 重叠区域覆盖顺序由内部拖拽排序字段决定，并与未选中状态下的 Canvas 显示顺序一致。
@@ -259,13 +259,13 @@ uvicorn main:app --host 0.0.0.0 --port 8000 --reload
 - 前端 `predictMask()` 已按后端 `PredictRequest` 发送 `image_id`、`prompt_type`、`prompt_data`、`model`，并将后端 `polygons` 转成 Konva 可渲染的 `pathData`。
 - 手工绘制工具会生成可保存的 `Mask.segmentation`；撤销/重做通过 `maskHistory/maskFuture` 工作，工作区在 window capture 阶段处理 `Ctrl/Cmd+Z`、`Ctrl/Cmd+Shift+Z` 和 `Ctrl/Cmd+Y`，并通过 `src/lib/keyboardShortcuts.ts` 兼容 `event.key` 与 `event.code=KeyZ/KeyY`。
 - Polygon 顶点编辑和新增顶点会重算 `pathData/segmentation/bbox/area`；多 polygon/分离区域和中空 mask 的外圈、内洞都可显示顶点与插点手柄，保存时通过 `mask_data.holes` 和 `metadata.polygonRingCounts` 保留 ring 分组；已保存 mask 进入 dirty 状态后复用归档 PATCH 链路。
-- 区域合并/去除会重算主 mask 的几何；合并已保存的次级 mask 时会通过工作区回调删除对应后端标注；若主区域和参与区域存在传播链对应 mask，会先弹窗选择当前帧或所有传播帧，处理所有传播帧时同一布尔操作会同步应用到其它传播帧的对应主区域和参与区域，保留传播来源 metadata，避免时间轴帧属性变色。
+- 区域合并/去除会重算主 mask 的几何；合并已保存的次级 mask 时会通过工作区回调删除对应后端标注；若主区域和参与区域存在传播链对应 mask，会先弹窗选择当前帧、所有传播帧或按帧范围选择；按帧范围选择复用工作区时间轴范围选择和确认弹窗，处理时同一布尔操作只同步应用到所选范围内的对应主区域和参与区域，保留传播来源 metadata，避免时间轴帧属性变色。
 - 前端 `importGtMask()` 已对齐后端 `/api/ai/import-gt-mask`；工作区左侧工具栏“导入 GT Mask”会在上传前显示导入结果预览并选择未知 maskid 策略，后端仅支持 8-bit 二值/灰度 maskid 图和 8-bit RGB 三通道完全相同的 `[X,X,X]` maskid 图，不再按彩色 RGB 类别图做颜色匹配，也不接受 16-bit/uint16 GT_label；尺寸不同的 mask 会最近邻拉伸到当前帧，导入后回显多类别高精度 polygon 标注，不显示黄色 seed point，并能直接使用普通 mask 的拓扑统计、边缘平滑、编辑和保存能力。
 - 前端 `exportCoco()` 已对齐后端 `/api/export/{project_id}/coco`；前端 `exportMasks()` 已对齐后端 `/api/export/{project_id}/masks`；前端 `exportSegmentationResults()` 已对齐后端 `/api/export/{project_id}/results`；工作区“分割结果导出”按钮会先保存当前待归档 mask，再按所选范围、outputs 和 Mix_label 透明度下载统一 ZIP；特定范围帧导出可用帧号输入框或时间轴拖拽选择范围；下载文件名按项目库项目名、导出范围首尾时间戳和首尾项目帧序号生成；统一 ZIP 包含 maskid/GT 像素值映射 JSON、原始图片文件夹、按帧/类别合并的分开 Mask 文件夹、GT_label 图文件夹、Pro_label 彩色图文件夹和 Mix_label 叠加图文件夹；GT_label 固定为 uint8 PNG，像素值使用类别真实 `maskid` 并跨图一致。
 - 右侧语义分类树点击分类会把分类变更同步到同一传播链前后帧对应 mask；识别依据为 `source_annotation_id`、`source_mask_id` 和 `propagation_seed_key`，被同步更新的已保存 mask 会进入 dirty 状态，等待工作区归档保存 PATCH 到后端；保存 dirty mask 时会保留 `source`、传播 seed 和来源 id 等 metadata，避免传播帧在时间轴上变成人工/AI 标注帧。
 - 工作区保存状态按钮会按当前项目待保存数量显示“保存 X 个改动”或“已全部保存”，并已接入 `POST /api/ai/annotate` 和 `PATCH /api/ai/annotations/{id}`；dirty mask 更新前会预检后端标注 id，已知缺失的本地旧 annotationId 直接用 `POST` 重新创建；如果预检后 `PATCH` 仍返回 404，前端也会保留同一几何、分类和传播 lineage metadata，改用 `POST` 重新创建并在回显时替换本地旧 id，避免保存或开始传播被陈旧 annotationId 中断；加载工作区时会通过 `GET /api/ai/annotations` 回显已保存标注。
 - 右侧实例属性面板“边缘平滑强度/应用边缘平滑”已接入 `POST /api/ai/smooth-mask`；滑杆会即时更新数值，但后端预览请求有短防抖，避免拖动时连续请求卡顿；预览不写入撤销历史也不标 dirty；点击应用后会把返回 polygon 作为新的实际 mask 几何写入当前 mask 和同传播链前后对应 mask，整次应用作为一个撤销/重做历史步骤，相关 mask 标记为 dirty/draft，平滑强度重置为 0，用户可继续用 polygon 编辑工具调整新多边形。
-- 工作区“自动传播”按钮已接入 `POST /api/ai/propagate/task`；若用户尚未显式设置范围，第一次点击会进入时间轴范围选择模式，第二次点击“开始传播”才提交后台任务；当前启用所选 SAM 2.1 变体的视频 predictor 后台任务，运行中轮询任务进度，完成后刷新后端已保存标注；中空 seed 会把内洞传给后端，SAM 2 seed mask 栅格化时扣除内洞，传播结果保存时也会保留 `holes`；工作区顶栏模型状态用紧凑 GPU/CPU 徽标，具体 SAM 2.1 传播权重由旁边下拉选择；同步 `POST /api/ai/propagate` 仍作为单 seed 兼容接口保留。
+- 工作区“自动传播”按钮已接入 `POST /api/ai/propagate/task`；若用户尚未显式设置范围，第一次点击会进入时间轴范围选择模式，顶栏显示传播权重和向前/向后帧数，第二次点击“开始传播”才提交后台任务；当前启用所选 SAM 2.1 变体的视频 predictor 后台任务，运行中轮询任务进度，完成后刷新后端已保存标注；中空 seed 会把内洞传给后端，SAM 2 seed mask 栅格化时扣除内洞，传播结果保存时也会保留 `holes`；工作区顶栏模型状态用紧凑 GPU/CPU 徽标，具体 SAM 2.1 传播权重由旁边下拉选择；同步 `POST /api/ai/propagate` 仍作为单 seed 兼容接口保留。
 - 工作区顶栏短状态会自动消失；保存、导出、导入 GT、传播进行中和无帧项目提示会保留到状态变化。
 - 工作区“清空遮罩”和左侧 `DEL` 删除只从左侧工具栏或键盘触发，会在删除已保存标注前预检当前项目仍存在的 annotation id，只对存在的 id 调用 `DELETE /api/ai/annotations/{id}`；如果当前帧有选中 mask 则优先清/删选中 mask，没有选中时清当前帧全部 mask；如果对象没关联其它传播帧则直接处理当前帧，如果存在传播链结果则弹窗选择只处理当前帧、清空所有传播帧、按帧范围选择或取消；按帧范围选择复用清空片段遮罩范围模式，并提供清空全部/保留人工AI；不会删除其它帧独立 AI 推理或人工标注 mask。
 - 项目状态已统一为 `pending`、`parsing`、`ready`、`error`；前端 `src/lib/api.ts` 会兼容归一化旧库中可能存在的 `Ready`、`Parsing`、`Error`。

doc/03-frontend-element-audit.md

@@ -80,7 +80,7 @@
 | 已保存标注回显 | 真实可用 | 加载工作区帧后调用 `GET /api/ai/annotations` 并渲染已保存 mask；回显时保留当前项目帧里尚未保存的 AI/手工 draft mask，避免从 AI 页推送的候选被覆盖 |
 | “分割结果导出”按钮 | 真实可用 | 原“导出 JSON 标注集”和“导出 PNG Mask ZIP”已合并为一个入口；点击后可选择整体视频、特定范围帧或当前图片，默认导出范围为当前图片，并勾选导出分开二值 mask、GT_label 黑白图、Pro_label 彩色图和 Mix_label 原图叠加图；选择“特定范围帧”后会进入和自动传播、清空遮罩一致的时间轴范围选择模式，可在播放进度条或视频处理进度条上点击/拖拽选择导出起止帧，也可直接修改起止帧输入框；选择 Mix_label 时可调透明度，默认 0.3，并显示当前/待导出第一帧预览；提交前会保存未归档 mask，然后调用 `GET /api/export/{project_id}/results` 下载 ZIP；浏览器下载名和后端 `Content-Disposition` 均使用 `{项目库项目名}_seg_T_{起始时间戳}-{结束时间戳}_P_{起始项目帧序号}-{结束项目帧序号}.zip`；时间戳格式为 `0h00m00s000ms`，帧序号来自项目抽帧后的 1-based 顺序，不使用原视频帧号；包内固定包含 `annotations_coco.json`、`maskid_GT像素值_类别映射.json` 和 `原始图片/`；选择分开 mask 时包含按帧子目录组织且同类合并的 `分开Mask分割结果/`，选择 GT_label/Pro_label/Mix_label 时分别包含 `GT_label图/`、`Pro_label彩色分割结果/`、`Mix_label重叠覆盖彩色分割结果/`。GT_label 图固定为 8-bit uint8 PNG，背景为 0，语义类别值使用类别真实 maskid，`maskid: 0` 的“待分类”与背景同为 0，Pro_label 中也与背景同为黑色 `[0,0,0]`，缺失 maskid 的旧标注才补下一个可用正整数，正整数 maskid 超出 1-255 会拒绝导出 |
 | “导入 GT Mask”按钮 | 真实可用 | 入口已从工作区顶栏移动到左侧工具栏“重叠区域去除”之后，使用紫色图标底色；选择图片后先弹出导入结果预览和未知 maskid 策略选择，可舍弃未知类别或导入为未定义类别；随后调用 `POST /api/ai/import-gt-mask`，后端仅支持 8-bit 二值/灰度 maskid 图和 8-bit RGB 三通道完全相同的 `[X,X,X]` maskid 图，不符合 8-bit 灰度/maskid 图要求时返回错误，16-bit/uint16 GT_label 会被拒绝；尺寸不同会自动最近邻拉伸到当前帧，再按类别/连通域生成高精度 polygon 标注，最后回显到工作区；导入 mask 与普通 mask 一样不显示黄色 seed point，并共用拓扑锚点统计、边缘平滑、编辑、分类和保存链路 |
-| 参考帧/起止帧/传播权重/自动传播 | 真实可用 | 当前打开帧即参考帧，前端会使用该帧全部 mask 作为 seed；工作区顶栏有独立“传播权重”下拉，可在传播前二次选择 SAM 2.1 tiny/small/base+/large 权重，不提供 SAM2/SAM3 家族切换，不影响 AI 智能分割页的单帧推理权重选择；传播权重下拉使用深色背景和青色文字，避免默认灰底白字不可读；如果用户尚未显式设置范围，点击“自动传播”会先进入时间轴范围选择模式，播放进度条和视频处理进度条都可点击/拖拽回填传播起始帧和传播结束帧，再点击“开始传播”提交；用户也可直接改数字框后点击按钮传播。提交后前端把传播权重 id、seed mask、seed 来源 id、未编辑传播结果的原始 seed 签名和前/后方向步骤提交到 `POST /api/ai/propagate/task`，后端先规范化/校验权重 id，再创建 `processing_tasks` 并由 Celery 执行对应 SAM 2.1 video predictor；worker 会在本次目标帧段内按 seed 来源和几何/语义签名做幂等判断，未改变且目标帧已有结果的 seed 直接跳过，已改变、目标帧只部分覆盖或换权重时会先删除本次目标帧段内同源旧自动传播标注再重新传播；历史或外部 seed 若仍带边缘平滑参数，后端仍按完整签名兼容处理；当前前端平滑应用会直接改写 polygon，因此传播以新几何参与签名；中间帧人工新增/修改同一物体后重新传播时，后端会按语义和目标帧空间重叠清理旧传播结果，写入前清理不受旧结果 `propagation_direction` 限制，避免 backward 重传时与旧 forward mask 重叠；传播中顶栏显示任务进度、已处理帧次、删除旧区域数和已保存区域数，前端轮询 `GET /api/tasks/{task_id}` 并刷新已保存标注；任务可取消，若完成后 0 个新区域会明确提示没有生成新 mask 或已跳过未改变 mask |
+| 参考帧/起止帧/传播权重/自动传播 | 真实可用 | 当前打开帧即参考帧，前端会使用该帧全部 mask 作为 seed；工作区顶栏有独立“传播权重”下拉，可在传播前二次选择 SAM 2.1 tiny/small/base+/large 权重，不提供 SAM2/SAM3 家族切换，不影响 AI 智能分割页的单帧推理权重选择；传播权重下拉使用深色背景和青色文字，避免默认灰底白字不可读；如果用户尚未显式设置范围，点击“自动传播”会先进入时间轴范围选择模式，播放进度条和视频处理进度条都可点击/拖拽回填传播起始帧和传播结束帧，顶栏会显示当前传播权重以及相对参考帧的向前/向后帧数，再点击“开始传播”提交；用户也可直接改数字框后点击按钮传播。提交后前端把传播权重 id、seed mask、seed 来源 id、未编辑传播结果的原始 seed 签名和前/后方向步骤提交到 `POST /api/ai/propagate/task`，后端先规范化/校验权重 id，再创建 `processing_tasks` 并由 Celery 执行对应 SAM 2.1 video predictor；worker 会在本次目标帧段内按 seed 来源和几何/语义签名做幂等判断，未改变且目标帧已有结果的 seed 直接跳过，已改变、目标帧只部分覆盖或换权重时会先删除本次目标帧段内同源旧自动传播标注再重新传播；历史或外部 seed 若仍带边缘平滑参数，后端仍按完整签名兼容处理；当前前端平滑应用会直接改写 polygon，因此传播以新几何参与签名；中间帧人工新增/修改同一物体后重新传播时，后端会按语义和目标帧空间重叠清理旧传播结果，写入前清理不受旧结果 `propagation_direction` 限制，避免 backward 重传时与旧 forward mask 重叠；传播中顶栏显示任务进度、已处理帧次、删除旧区域数和已保存区域数，前端轮询 `GET /api/tasks/{task_id}` 并刷新已保存标注；任务可取消，若完成后 0 个新区域会明确提示没有生成新 mask 或已跳过未改变 mask |
 | 清空片段遮罩 | 真实可用 | 点击“清空片段遮罩”后会进入和自动传播一致的时间轴范围选择模式，用户可在播放进度条或视频处理进度条上点击/拖拽选择起止帧；顶栏提供“清空全部”和“保留人工/AI”两种模式，默认清空全部以保持旧行为；“清空全部”会删除该帧段内所有本地 draft mask，并对已保存 mask 调用 `DELETE /api/ai/annotations/{annotation_id}`，若范围内存在人工绘制或 AI 智能分割生成的红色“人工/AI 标注帧”会先弹出确认；“保留人工/AI”只删除自动传播/推理 mask，不弹出人工帧确认，人工/AI 标注帧、范围外 mask 和未被清空的选区会保留；同时按清空范围裁剪当前会话的自动传播历史条，避免已清空片段仍显示最近传播进度 |
 | 保存状态按钮 | 真实可用 | 顶栏按钮按当前项目待保存数量显示为“保存 X 个改动”或“已全部保存”；未保存 mask 写入 `POST /api/ai/annotate`，dirty mask 写入 `PATCH /api/ai/annotations/{id}`；保存成功后会重新拉取后端标注，并用 saved annotation 替换本次提交的 draft mask，避免仍显示未保存 |
 
@@ -114,7 +114,7 @@
 | 拖拽/选择 | 真实可用 | 控制 Canvas 是否可拖拽 |
 | 调整多边形 | 真实可用 | 选中 polygon mask 后显示顶点和边中点；支持按住顶点直接拖动、点击边中点插点、双击边界按位置插点 |
 | 多边形/矩形/圆/画笔/橡皮擦 | 真实可用 | 切换 activeTool 后由 `CanvasArea` 生成或编辑可保存的 polygon mask；画笔/橡皮擦在工具栏显示尺寸滑杆 |
-| 区域合并/去除 | 真实可用 | 选择工具后点击多个 mask，右下角显示已选数量和操作按钮；合并/去除模式会隐藏 polygon 编辑手柄，避免手柄抢占多选点击；布尔选择态中第一个选中的主区域用黄色实线轮廓，后续参与合并/扣除的区域用红色虚线轮廓，避免主区域和扣除区域看起来像随机阴影差异；使用 `polygon-clipping` 做 union / difference；若选中的主区域和参与区域存在传播帧对应 mask，会先弹窗选择只处理当前帧或处理所有传播帧；合并会保留主 mask 并移除被合并 mask，且移除次级 mask 时会同步删除其同链自动传播结果；去除会从主 mask 扣除后续选中 mask；内含扣除会保留 hole ring 并用 even-odd 规则渲染 |
+| 区域合并/去除 | 真实可用 | 选择工具后点击多个 mask，右下角显示已选数量和操作按钮；合并/去除模式会隐藏 polygon 编辑手柄，避免手柄抢占多选点击；布尔选择态中第一个选中的主区域用黄色实线轮廓，后续参与合并/扣除的区域用红色虚线轮廓，避免主区域和扣除区域看起来像随机阴影差异；使用 `polygon-clipping` 做 union / difference；若选中的主区域和参与区域存在传播帧对应 mask，会先弹窗选择只处理当前帧、处理所有传播帧或按帧范围选择；按帧范围选择会进入和清空/传播一致的时间轴范围选择，点击顶栏确认后再弹最终确认，只处理范围内存在对应传播链的帧；合并会保留主 mask 并移除被合并 mask，且移除次级 mask 时会同步删除其同链自动传播结果；去除会从主 mask 扣除后续选中 mask；内含扣除会保留 hole ring 并用 even-odd 规则渲染 |
 | 导入 GT Mask | 真实可用 | 位于“重叠区域去除”之后，点击后打开文件选择器，并在上传前选择未知类别处理策略；该入口不切换 activeTool |
 | AI 智能分割跳转入口 | 真实可用 | 切到 AI 智能分割页；不是直接执行推理 |
 | AI 正向选点/反向选点/框选 | 不在工作区工具栏显示 | 这些是 AI 智能分割页功能，工作区左侧工具栏不再提供正向选点、反向选点和边界框选按钮 |

doc/07-current-requirements-freeze.md

@@ -90,8 +90,8 @@
 - 多 polygon 或分离区域组成的同一个 mask 进入“调整多边形”后，所有分离 polygon 都应显示可拖动顶点与边中点插入手柄，不能只显示第一个主区域。
 - 选中整个 mask 且未选中具体顶点时，Delete/Backspace 删除该 mask；左侧 `DEL` 按钮复用同一删除链路。删除已保存 mask 前，前端必须用当前后端标注列表预检 `annotationId`，只对仍存在的 id 发送 `DELETE /api/ai/annotations/{id}`，避免本地陈旧 id 导致浏览器控制台出现 404 红字；如果删除对象属于自动传播链或是传播 seed，应同步删除同一传播链上的自动传播 mask，但不能删除其他帧独立 AI 推理或人工标注 mask。
 - 撤销、重做绑定全局 `maskHistory/maskFuture`，工作区支持顶栏按钮和全局快捷键 `Ctrl/Cmd+Z`、`Ctrl/Cmd+Shift+Z`、`Ctrl/Cmd+Y`；快捷键监听应在 capture 阶段处理，并在 `event.key` 不可靠时兼容 `event.code=KeyZ/KeyY`，但输入框、文本域、下拉框和可编辑文本聚焦时不能拦截；AI 页支持自己的按钮；左侧工具栏不重复放置撤销/重做入口。
-- 区域合并工具支持多选当前帧 mask，并使用 polygon union 生成合并后的主 mask；若主区域和参与区域存在同一传播链上的对应 mask，合并前必须弹出范围选择，让用户选择只处理当前帧或处理所有传播帧；选择所有传播帧时，同一次合并必须同步应用到其它传播帧中对应的主区域和参与区域，只删除每个已同步帧里的参与合并 mask，不能把未参与本次同步的同链对象整链误删。
+- 区域合并工具支持多选当前帧 mask，并使用 polygon union 生成合并后的主 mask；若主区域和参与区域存在同一传播链上的对应 mask，合并前必须弹出范围选择，让用户选择只处理当前帧、处理所有传播帧或按帧范围选择；按帧范围选择进入和自动传播/清空一致的时间轴范围选择，点击确认后再弹出最终确认。选择所有传播帧或范围帧时，同一次合并必须同步应用到对应传播帧中的主区域和参与区域，只删除每个已同步帧里的参与合并 mask，不能把未参与本次同步或范围外的同链对象整链误删。
-- 区域去除工具支持多选当前帧 mask，并从第一个选中的主 mask 中扣除后续选中 mask；若主区域和参与区域存在同一传播链上的对应 mask，去除前必须弹出范围选择，让用户选择只处理当前帧或处理所有传播帧；选择所有传播帧时，同一次去除必须同步应用到其它传播帧中对应的主区域和参与区域，参与扣除的 mask 本身保留。
+- 区域去除工具支持多选当前帧 mask，并从第一个选中的主 mask 中扣除后续选中 mask；若主区域和参与区域存在同一传播链上的对应 mask，去除前必须弹出范围选择，让用户选择只处理当前帧、处理所有传播帧或按帧范围选择；按帧范围选择进入和自动传播/清空一致的时间轴范围选择，点击确认后再弹出最终确认。选择所有传播帧或范围帧时，同一次去除必须同步应用到对应传播帧中的主区域和参与区域，参与扣除的 mask 本身保留。
 - 区域合并/去除同步到传播帧时必须保留传播 mask 原有 `source`、`source_annotation_id`、`source_mask_id`、`propagation_seed_key` 等 lineage metadata；这些帧可以进入 dirty 待保存状态，但不能因为几何同步在时间轴上从自动传播帧变成人工/AI 标注帧。
 - 区域合并/去除模式显示已选数量，并隐藏 polygon 编辑手柄以避免手柄抢占多选点击；第一个选中的主区域使用黄色实线轮廓，后续参与合并/扣除的区域使用红色虚线轮廓。
 - 区域去除结果包含内洞时，前端保留 hole ring 并用 even-odd 规则渲染，保存时把外圈写入 `mask_data.polygons`、把每个外圈对应内洞写入 `mask_data.holes`，并用 `metadata.polygonRingCounts` 支撑前端 ring 回显。
@@ -127,6 +127,7 @@
 - 工作区传播功能以当前打开帧作为参考帧，并使用该帧全部 mask 作为 seed；用户不再选择“选中区域/当前帧全部”传播对象。
 - 工作区传播功能允许设置传播起始帧和传播结束帧；前端以当前参考帧为 seed，只向起止范围内位于参考帧之前和之后的帧传播，源帧不重复保存。
 - 工作区只保留一个“自动传播”按钮，点击后在指定范围内按前向/后向自动生成 mask。
+- 工作区进入自动传播范围选择时，顶栏必须显示本次传播权重以及按当前参考帧计算的向前/向后传播帧数，避免用户只看到起止帧而不清楚实际传播方向。
 - 当前参考帧没有 mask 时，点击“开始传播”必须提示“当前参考帧无遮罩”，且不得提交传播任务或保存其它帧标注。
 - 自动传播提交前，前端必须只保存当前参考帧中的 draft/dirty mask；参考帧 seed 优先使用后端 `annotation_id` 作为稳定来源，避免第一次用前端临时 id 传播、后续保存后无法替换旧传播结果；其它帧的脏标注不能在传播准备阶段触发无关后端更新。
 - 前端会把多个 seed 或双向范围拆成 `steps`，通过 `POST /api/ai/propagate/task` 创建 `propagate_masks` 后台任务，避免长 HTTP 请求卡在浏览器侧，同时避免并发抢占 GPU。

doc/08-current-design-freeze.md

@@ -131,7 +131,7 @@
 12. 右侧面板不再显示“本体论与属性分类管理树”固定说明栏，直接展示实际可操作内容。
 13. 右侧“遮罩透明度”滑杆写入 Zustand `maskPreviewOpacity`，`CanvasArea` 和 `AISegmentation` 都用该值计算 mask group opacity；选中 mask 在基础透明度上加亮或按基础透明度显示，方便保留选中反馈。
 14. Canvas 点击 mask 后，全局 `selectedMaskIds` 会同步到 `OntologyInspector`；本体面板按选中 mask 的 `classId`、`className/label` 和颜色匹配模板分类，自动设置 active class，并把分类按钮滚动/聚焦到可见区域。
-15. 工作区顶栏“清空片段遮罩”和“自动传播”共用时间轴范围选择交互；第一次点击“清空片段遮罩”会进入范围选择模式，按钮变为“确认清空”，用户可在播放进度条或视频处理进度条上点击/拖拽选择起止帧；进入清空模式后顶栏显示“清空全部 / 保留人工/AI”两段式模式选择，默认“清空全部”。“清空全部”会对范围内已保存 mask 调用 `DELETE /api/ai/annotations/{id}`，同时移除范围内本地 draft mask、被清空的选区和与清空范围重叠的本地传播历史条；若范围内存在非自动传播来源的 mask，也就是时间轴红色“人工/AI 标注帧”，执行前会显示站内确认弹窗，取消则不删除任何 mask。“保留人工/AI”只删除范围内自动传播/推理 mask，不删除人工绘制或 AI 智能分割生成的红色标注帧，不弹出人工帧确认；范围外 mask 和传播历史片段保持不变。
+15. 工作区顶栏“清空片段遮罩”、“自动传播”和传播链布尔操作共用时间轴范围选择交互；第一次点击“清空片段遮罩”会进入范围选择模式，按钮变为“确认清空”，用户可在播放进度条或视频处理进度条上点击/拖拽选择起止帧；进入清空模式后顶栏显示“清空全部 / 保留人工/AI”两段式模式选择，默认“清空全部”。“清空全部”会对范围内已保存 mask 调用 `DELETE /api/ai/annotations/{id}`，同时移除范围内本地 draft mask、被清空的选区和与清空范围重叠的本地传播历史条；若范围内存在非自动传播来源的 mask，也就是时间轴红色“人工/AI 标注帧”，执行前会显示站内确认弹窗，取消则不删除任何 mask。“保留人工/AI”只删除范围内自动传播/推理 mask，不删除人工绘制或 AI 智能分割生成的红色标注帧，不弹出人工帧确认；范围外 mask 和传播历史片段保持不变。自动传播范围选择时，传播权重下拉旁显示当前权重和相对参考帧的向前/向后帧数；布尔操作范围选择时，顶栏按钮变为“确认区域合并”或“确认重叠区域去除”，点击后弹出最终确认，再只对范围内存在对应传播链的帧执行。
 
 ### AI 点/框推理
 
@@ -207,8 +207,8 @@
 3. Canvas 左上角提示布尔选择顺序：第一个选中的是主区域，后续区域参与合并或扣除。
 4. 布尔选择态按选择顺序区分角色：第一个选中的主区域使用黄色实线轮廓，后续参与合并/扣除的区域使用红色虚线轮廓；所有已选区域填充透明度保持一致，避免被误解为阴影模式异常。
 5. `CanvasArea` 把 `Mask.segmentation` 转为 `polygon-clipping` 的 MultiPolygon。
-6. `area_merge` 使用 union，更新第一个选中的主 mask，并从前端 store 移除后续被合并 mask；如果被移除 mask 已保存，会调用工作区传入的删除回调删除后端标注。执行前会按 `source_annotation_id`、`source_mask_id` 和 `propagation_seed_key` 计算可同步的传播帧；若存在其它传播帧，先弹出范围选择，让用户选择只处理当前帧或处理所有传播帧。处理所有传播帧时，在每个具备对应关系的帧上执行同一次 union；只删除该帧参与合并的次级 mask，避免把同链但未参与同步的区域整链误删。
+6. `area_merge` 使用 union，更新第一个选中的主 mask，并从前端 store 移除后续被合并 mask；如果被移除 mask 已保存，会调用工作区传入的删除回调删除后端标注。执行前会按 `source_annotation_id`、`source_mask_id` 和 `propagation_seed_key` 计算可同步的传播帧；若存在其它传播帧，先弹出范围选择，让用户选择只处理当前帧、处理所有传播帧或按帧范围选择。按帧范围选择会把本次布尔操作交给 `VideoWorkspace`，复用底部时间轴范围选择和最终确认弹窗；确认后只在范围内且具备对应关系的帧上执行同一次 union，只删除该帧参与合并的次级 mask，避免把同链但未参与同步或范围外的区域整链误删。
-7. `area_remove` 使用 difference，从第一个选中的主 mask 中扣除后续选中 mask，扣除对象本身保留；同样会在执行前计算可同步的传播帧并弹出当前帧/所有传播帧选择。处理所有传播帧时，会在其它传播帧中找到对应主区域和扣除区域并执行 difference，扣除区域本身继续保留；如果 difference 产生内洞，`segmentation` 保留外圈和 hole ring，`metadata.polygonRingCounts` 记录每个 polygon 的 ring 数，渲染时使用 even-odd fill。
+7. `area_remove` 使用 difference，从第一个选中的主 mask 中扣除后续选中 mask，扣除对象本身保留；同样会在执行前计算可同步的传播帧并弹出当前帧/所有传播帧/按帧范围选择。按帧范围选择确认后，会在范围内其它传播帧中找到对应主区域和扣除区域并执行 difference，扣除区域本身继续保留；如果 difference 产生内洞，`segmentation` 保留外圈和 hole ring，`metadata.polygonRingCounts` 记录每个 polygon 的 ring 数，渲染时使用 even-odd fill。
 8. 结果会重算 `pathData`、`segmentation`、`bbox`、`area`，已保存主 mask 会进入 dirty 状态并复用归档 PATCH 链路；同步到传播帧时保留传播来源和 lineage metadata，避免自动传播帧在时间轴上变成人工/AI 标注帧；带洞结果的面积按外圈减内洞计算；进入调整多边形时，外圈和内洞 ring 都会显示顶点和边中点插入手柄，内洞拖动、插点、保存与回显继续保持中空结构。
 
 ### GT Mask 导入
@@ -297,7 +297,7 @@
 以下能力属于当前冻结版本的占位或半可用功能：
 
 - Dashboard 初始快照来自 `GET /api/dashboard/overview`；任务进度区由 `processing_tasks` queued/running/success/failed/cancelled 任务生成，处理中统计只计算 queued/running。
-- 已保存标注支持通过右侧语义分类树换标签、polygon 顶点拖动/删除、边中点插入、多 polygon 子区域编辑、中空 mask 内洞 ring 编辑和区域合并/去除进入 dirty 状态并归档更新；多 polygon/分离区域选中后所有子区域都显示编辑手柄，同帧同传播链的分散 mask 会联动高亮；Canvas 右下角不再提供旧的“应用分类”按钮，避免没选区时误改整帧；区域合并/去除会在存在传播帧时弹窗选择当前帧或所有传播帧，并保留传播帧来源 metadata；选中整块 mask 可用 Delete/Backspace 或左侧 `DEL` 删除，同步后端前会预检 id，同传播链自动传播结果会随传播 seed/传播结果删除而一并清理，独立 AI 推理/人工 mask 保留。
+- 已保存标注支持通过右侧语义分类树换标签、polygon 顶点拖动/删除、边中点插入、多 polygon 子区域编辑、中空 mask 内洞 ring 编辑和区域合并/去除进入 dirty 状态并归档更新；多 polygon/分离区域选中后所有子区域都显示编辑手柄，同帧同传播链的分散 mask 会联动高亮；Canvas 右下角不再提供旧的“应用分类”按钮，避免没选区时误改整帧；区域合并/去除会在存在传播帧时弹窗选择当前帧、所有传播帧或按帧范围选择，范围选择复用时间轴和确认弹窗，并保留传播帧来源 metadata；选中整块 mask 可用 Delete/Backspace 或左侧 `DEL` 删除，同步后端前会预检 id，同传播链自动传播结果会随传播 seed/传播结果删除而一并清理，独立 AI 推理/人工 mask 保留。
 - SAM 3 文本语义分割已从当前产品路径中禁用；相关源码保留，恢复时需要重新接入前端入口、registry、状态接口和测试。
 - 自定义分类通过 `PATCH /api/templates/{id}` 写入当前激活模板的 `mapping_rules.classes`。
 - 选中 mask 后，本体面板的“特定目标实例属性追踪”标题值来自当前 mask 的 `className/label`，不使用全局 active class；面板不再展示长期为 1 的“当前选中区域”计数；面板调用 `POST /api/ai/analyze-mask` 自动显示拓扑锚点数量等属性，`topology_anchor_count` 是真实 polygon 顶点数量，`topology_anchors` 只保留最多 64 个抽样点用于调试展示；`OntologyInspector` 会为分析请求维护递增序号，旧请求返回时不再回写状态，并静默忽略 Axios abort/cancel 错误，避免快速切换、平滑预览或组件卸载时把正常中止误报成失败；不再提供“重新提取拓扑锚点”调试按钮；“边缘平滑强度”滑杆会即时更新数值，但 `POST /api/ai/smooth-mask` 预览请求经过约 220ms 防抖后才发送，返回 polygon 作为临时预览写入当前 mask 显示，预览不改变保存状态；点击“应用边缘平滑”后，前端把平滑 polygon 作为新的实际几何写入当前 mask，并按传播 lineage 同步写入传播链前后对应 mask，相关 mask 标记为 dirty/draft，整次操作通过一次 `setMasks()` 进入撤销/重做历史；应用后不保留 `geometry_smoothing` 参数，平滑强度重置为 0。前端不再展示“后端模型置信度”。

doc/09-test-plan.md

@@ -17,8 +17,8 @@
 | R1 登录与会话 | `src/components/Login.test.tsx`, `src/components/Sidebar.test.tsx`, `src/components/UserAdmin.test.tsx`, `src/store/useStore.test.ts`, `backend/tests/test_auth.py`, `backend/tests/test_admin.py` | 成功登录、JWT/token 写入、当前用户写入、刷新恢复基础状态、失败提示、登录输入 autocomplete、后端 401、`/api/auth/me`、管理员入口、用户 CRUD、角色权限、审计日志、viewer 读写权限边界、改密码/删除用户站内确认、演示出厂设置站内二次确认和重置结果 |
 | R2 项目管理 | `src/lib/api.test.ts`, `src/components/ProjectLibrary.test.tsx`, `backend/tests/test_projects.py` | 前端字段映射、PATCH 更新、项目卡片复制/删除、修改项目名称时隐藏生成帧、DICOM 项目不显示生成帧、复制项目 reset/full 契约、DELETE 契约、后端 CRUD、删除级联、帧列表、项目按当前 JWT 用户隔离 |
 | R3 媒体上传与拆帧 | `src/components/ProjectLibrary.test.tsx`, `src/components/TransientNotice.test.tsx`, `backend/tests/test_media.py`, `backend/tests/test_tasks.py` | 视频导入不自动拆帧、视频/DICOM 上传进度可视化、DICOM 导入显示有效文件数量并在上传后持续显示解析任务进度、显式生成帧 FPS 选择、项目卡片显示目标 parse_fps 而非原视频 FPS、扩展名校验、自动建项目、关联项目、创建异步任务、非阻塞自动消失操作提示、标准帧序列参数、帧时间戳/源帧号、任务序列元数据、worker 注册帧、取消任务、重试任务、取消后 worker 停止 |
-| R4 工作区与帧浏览 | `src/components/VideoWorkspace.test.tsx`, `src/components/FrameTimeline.test.tsx` | 加载帧、无帧项目不自动解析并提示生成帧、工作区短状态自动消失、工作区/AI 画布底图默认居中且保留边距、工作区 mask 透明度、回显已保存标注时保留本地未保存 draft mask、选中 mask 后跨帧自动跟随同一传播链结果、左侧工具栏清空遮罩优先作用于当前帧选中 mask/无选中时作用于当前帧全部 mask、无传播链时直接执行、有传播链时可选只清当前帧/清空所有传播帧/按帧范围选择/取消、清空片段遮罩进入时间轴范围选择并按选区批量清空、清空全部模式、保留人工/AI 模式只清传播 mask、清空人工/AI 标注帧前二次确认、取消确认不删除、仅自动传播帧不确认、清空/删除前预检后端 annotation id 并跳过本地陈旧 id、清空后裁剪/移除重叠传播历史条、删除单个传播 mask 后空帧不保留传播历史颜色、传播权重下拉深色可读配色、缩略图/range/视频处理进度条、视频处理进度条点击跳帧、人工/AI 标注帧红色竖线和标识点击跳帧、自动传播帧通过 source/lineage metadata 识别为蓝色区段和标识点击跳帧、最近自动传播历史片段同一蓝色系按新旧递进纯色显示，旧记录第 5 次后统一阈值色、当前帧白色贯穿线、传播/清空范围洋红/黄绿色边界贯穿线、缩略图红/蓝边框、人工/AI 标注帧叠加传播状态时红框优先保留并显示蓝色内描边、当前人工/AI 标注帧青色外框加红色内描边、普通状态不显示传播范围黄色选区、播放进度条和视频处理进度条选择传播/清空范围、左右方向键切帧、播放、按项目 FPS 显示当前/总时长 |
+| R4 工作区与帧浏览 | `src/components/VideoWorkspace.test.tsx`, `src/components/FrameTimeline.test.tsx` | 加载帧、无帧项目不自动解析并提示生成帧、工作区短状态自动消失、工作区/AI 画布底图默认居中且保留边距、工作区 mask 透明度、回显已保存标注时保留本地未保存 draft mask、选中 mask 后跨帧自动跟随同一传播链结果、左侧工具栏清空遮罩优先作用于当前帧选中 mask/无选中时作用于当前帧全部 mask、无传播链时直接执行、有传播链时可选只清当前帧/清空所有传播帧/按帧范围选择/取消、清空片段遮罩进入时间轴范围选择并按选区批量清空、传播链布尔操作按帧范围选择并二次确认、清空全部模式、保留人工/AI 模式只清传播 mask、清空人工/AI 标注帧前二次确认、取消确认不删除、仅自动传播帧不确认、清空/删除前预检后端 annotation id 并跳过本地陈旧 id、清空后裁剪/移除重叠传播历史条、删除单个传播 mask 后空帧不保留传播历史颜色、传播权重下拉深色可读配色、自动传播范围选择时显示传播权重和向前/向后帧数、缩略图/range/视频处理进度条、视频处理进度条点击跳帧、人工/AI 标注帧红色竖线和标识点击跳帧、自动传播帧通过 source/lineage metadata 识别为蓝色区段和标识点击跳帧、最近自动传播历史片段同一蓝色系按新旧递进纯色显示，旧记录第 5 次后统一阈值色、当前帧白色贯穿线、传播/清空/布尔范围洋红/黄绿色边界贯穿线、缩略图红/蓝边框、人工/AI 标注帧叠加传播状态时红框优先保留并显示蓝色内描边、当前人工/AI 标注帧青色外框加红色内描边、普通状态不显示传播范围黄色选区、播放进度条和视频处理进度条选择传播/清空/布尔范围、左右方向键切帧、播放、按项目 FPS 显示当前/总时长 |
-| R5 工具栏 | `src/components/ToolsPalette.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/components/VideoWorkspace.test.tsx`, `src/lib/keyboardShortcuts.test.ts`, `src/store/useStore.test.ts` | 工具切换、工具栏紧凑垂直布局和高度不足时滚动、工具栏低对比滚动条、工具栏外扩滚动条槽位不挤占按钮列、调整多边形工具、AI 跳转、清空遮罩唯一左侧工具栏入口、清空遮罩上方 DEL 删除按钮、Canvas 右下角不再重复显示清空遮罩或应用分类按钮、GT Mask 导入位于清空遮罩分隔线之后且使用紫色底色、工具栏分隔线位于创建圆后、橡皮擦后和清空遮罩后、GT Mask 未知类别导入策略选择、工作区工具栏不展示 AI 正/反点和框选、左侧工具栏不重复撤销/重做、左侧工具栏不展示创建点/创建线段、矩形/圆/多边形手工 mask 绘制、普通/导入 polygon mask 不显示黄色 seed point、画笔/橡皮擦尺寸控制、画笔新建当前类别 mask、画笔与选中 mask 连通时自动合并、橡皮擦从选中 mask 扣除、未选中 mask 时画布按语义分类树内部优先级渲染、多边形 Enter/首节点闭合、上下文提示提示 Enter/Esc/首节点闭合且数秒后自动隐藏、polygon 顶点直接拖动/删除、顶点拖拽结束不改变 Canvas 视口、边中点插点、双击边界按位置插点、多 polygon/分离区域全部显示编辑顶点、中空 mask 内洞 ring 顶点和插点可编辑、整块 mask 删除、DEL 和 Delete/Backspace 删除共用传播链范围确认、同帧传播链分散 mask 点选联动高亮、传播链自动传播 mask 随 seed/传播结果删除、独立 AI 推理 mask 不被误删、区域合并/去除存在传播帧时弹窗选择当前帧或所有传播帧、区域合并/去除同步到对应传播帧且保留传播 metadata、布尔选择主区域/扣除区域视觉区分和选择顺序提示、内含去除 hole 渲染和 ring 分组保存、合并模式隐藏编辑手柄、工作区顶栏撤销/重做按钮、顶栏撤销/重做图标强调色、撤销/重做快捷键 Ctrl/Cmd+Z、Ctrl/Cmd+Shift+Z、Ctrl/Cmd+Y、物理键码 fallback 和输入框快捷键跳过、撤销/重做历史栈 |
+| R5 工具栏 | `src/components/ToolsPalette.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/components/VideoWorkspace.test.tsx`, `src/lib/keyboardShortcuts.test.ts`, `src/store/useStore.test.ts` | 工具切换、工具栏紧凑垂直布局和高度不足时滚动、工具栏低对比滚动条、工具栏外扩滚动条槽位不挤占按钮列、调整多边形工具、AI 跳转、清空遮罩唯一左侧工具栏入口、清空遮罩上方 DEL 删除按钮、Canvas 右下角不再重复显示清空遮罩或应用分类按钮、GT Mask 导入位于清空遮罩分隔线之后且使用紫色底色、工具栏分隔线位于创建圆后、橡皮擦后和清空遮罩后、GT Mask 未知类别导入策略选择、工作区工具栏不展示 AI 正/反点和框选、左侧工具栏不重复撤销/重做、左侧工具栏不展示创建点/创建线段、矩形/圆/多边形手工 mask 绘制、普通/导入 polygon mask 不显示黄色 seed point、画笔/橡皮擦尺寸控制、画笔新建当前类别 mask、画笔与选中 mask 连通时自动合并、橡皮擦从选中 mask 扣除、未选中 mask 时画布按语义分类树内部优先级渲染、多边形 Enter/首节点闭合、上下文提示提示 Enter/Esc/首节点闭合且数秒后自动隐藏、polygon 顶点直接拖动/删除、顶点拖拽结束不改变 Canvas 视口、边中点插点、双击边界按位置插点、多 polygon/分离区域全部显示编辑顶点、中空 mask 内洞 ring 顶点和插点可编辑、整块 mask 删除、DEL 和 Delete/Backspace 删除共用传播链范围确认、同帧传播链分散 mask 点选联动高亮、传播链自动传播 mask 随 seed/传播结果删除、独立 AI 推理 mask 不被误删、区域合并/去除存在传播帧时弹窗选择当前帧/所有传播帧/按帧范围选择、区域合并/去除按帧范围同步到对应传播帧且保留传播 metadata、布尔选择主区域/扣除区域视觉区分和选择顺序提示、内含去除 hole 渲染和 ring 分组保存、合并模式隐藏编辑手柄、工作区顶栏撤销/重做按钮、顶栏撤销/重做图标强调色、撤销/重做快捷键 Ctrl/Cmd+Z、Ctrl/Cmd+Shift+Z、Ctrl/Cmd+Y、物理键码 fallback 和输入框快捷键跳过、撤销/重做历史栈 |
 | R6 AI 推理 | `src/lib/api.test.ts`, `src/components/CanvasArea.test.tsx`, `src/components/AISegmentation.test.tsx`, `src/components/VideoWorkspace.test.tsx`, `src/components/ModelStatusBadge.test.tsx`, `backend/tests/test_ai.py`, `backend/tests/test_sam2_engine.py` | SAM 2.1 变体选择、点/框/interactive 契约、semantic 禁用、SAM 3 入口隐藏和后端拒绝、SAM 2.1 最高分候选去重、SAM 2.1 框选后正负点细化同一候选 mask、AI 页框选发送 box prompt、AI 页框选后加点发送 interactive prompt、AI 页提示工具上下文提示、AI 页重复执行替换旧候选、SAM 2.1 反向点启用背景过滤且空结果移除旧候选、AI 页不渲染工作区已有 mask、AI 页可在候选 mask 上继续添加正/反点、AI 页可单点删除提示点并删除最近锚点、AI 页可删除选中候选且不删除工作区 mask、AI 页清空只移除本页候选、AI 页参数开关可读性文案且 options 字段不变、AI 页/右侧共享遮罩透明度只改预览 opacity、AI 页生成 mask 自动选中并可通过分类树换标签、AI 页无语义候选禁止推送到工作区并用 error toast 提示、离开 AI 页时清理未分类候选、AI 页推送到工作区编辑保留选择和当前帧、SAM 2.1 视频以当前参考帧全部 mask 和起止帧范围自动传播、当前参考帧无遮罩提示、传播前只保存参考帧 draft/dirty seed mask、传播前独立选择 SAM 2.1 tiny/small/base+/large 权重、自动传播创建 Celery 任务、传播入队权重 id 规范化/拒绝不支持 id、传播 seed 来源 id/签名和历史平滑 metadata 兼容、中空传播 seed 扣除 holes 后注入 SAM 2 且传播结果保留 holes、历史平滑 seed 保存前对 forward/backward polygon 实际应用边缘平滑并减少密集轮廓点、边缘平滑强度缓入递进曲线、未编辑传播结果作为 seed 时继承原始签名并跳过重复传播、已编辑传播结果保留 lineage 但重算签名并清理旧结果、中间帧人工新增替代 seed 时清理下游同物体旧传播结果、中间帧 backward 传播清理旧 forward 结果、换权重传播先清理旧结果、旧临时 seed id 传播结果兼容清理、传播中轮询任务进度、传播任务取消/重试、传播来源 metadata 回显、空提示/空结果反馈、GPU/SAM2.1 状态、AI 参数 options、局部裁剪推理、背景过滤、状态徽标、坐标归一化、正负点 labels、polygons 转 path、后端 fake registry |
 | R7 标注保存 | `src/components/VideoWorkspace.test.tsx`, `src/components/CanvasArea.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_ai.py` | 保存状态按钮“保存 X 个改动/已全部保存”、保存标注、保存后用后端 saved annotation 替换已提交 draft、加载回显、更新 dirty 标注、dirty 本地旧 annotationId 预检缺失时直接重新 POST 创建、预检后 PATCH 404 时重新 POST 创建并回显替换、中空 mask 保存为 `polygons` + `holes` 并可回显为 ring 分组、清空删除已保存标注、GT mask 多类别导入、高精度 GT contour、导入 mask 可直接拓扑统计和边缘平滑、后端 seed point 归一化兼容但前端不显示或拖动、缺失 seed point 的普通 polygon 保存时自动写入代表点、项目不存在、帧不存在 |
 | R8 模板库 | `src/components/TemplateRegistry.test.tsx`, `src/components/TransientNotice.test.tsx`, `src/lib/api.test.ts`, `backend/tests/test_templates.py` | 前端模板加载/新建/编辑/删除、删除模板站内确认、鼠标复制模板为私有副本、所有模板归一化包含黑色 `maskid:0`“待分类”保留类、保留类固定最后且不可删除/拖拽上移、详情页“语义分类树（拖拽调层级）”标题、详情页“编辑模板”按钮和编辑图标、详情页垃圾桶删除 label 且不显示来源标签、编辑弹窗分类编辑不显示旧 category 来源元信息、编辑后详情页刷新、详情页和编辑弹窗拖拽语义层级顺序、拖拽保存 `zIndex` 且不改变 maskid、JSON 分类导入预览、`[[colors],[names]]` 数组格式、`{colors,names}` 对象格式、带前缀/宽松 keys/中文标点粘贴格式、JSON 错误内联提示、保存错误非阻塞提示、mapping_rules 解包/打包、后端模板 CRUD |
@@ -66,7 +66,7 @@
 - R6：补充传播去重回归测试，验证前端传播前会先保存 draft seed mask 并用稳定 `source_annotation_id` 入队；后端在 seed 来源由前端临时 id 迁移到后端 annotation id、用户换用其他 SAM 2.1 权重、未编辑传播结果再次作为 seed、已编辑传播结果重新作为 seed、中间帧人工新增替代 seed 时，会分别跳过或清理旧传播标注再保存新结果。
 - R5/R6/R7：补充中空 mask 回归测试，验证保存时拆分 `polygons`/`holes` 并回显为 ring 分组，调整多边形时内洞显示可编辑顶点，以及 SAM 2 seed mask 会扣除 holes、传播结果轮廓提取会保留 holes。
 - R7：补充 dirty 本地旧 annotationId 回归测试，验证后端标注 id 预检已缺失时会跳过失败 PATCH、直接 `POST /api/ai/annotate` 重新创建；同时验证预检后 `PATCH /api/ai/annotations/{id}` 返回 404 时，保存链路也会改用 `POST` 重新创建并用回显标注替换本地旧 mask。
-- R4/R5/R8/R9：补充模板切换、工具栏清空入口和传播链布尔操作回归测试，验证已有 mask 切换模板需确认清空，模板详情按钮改为“编辑模板”，当前帧清空会在传播链存在时提供只清当前帧/清空所有传播帧/按帧范围选择/取消，区域合并/去除会在存在传播帧时先选择当前帧或所有传播帧并保留传播 metadata。
+- R4/R5/R8/R9：补充模板切换、工具栏清空入口和传播链布尔操作回归测试，验证已有 mask 切换模板需确认清空，模板详情按钮改为“编辑模板”，当前帧清空会在传播链存在时提供只清当前帧/清空所有传播帧/按帧范围选择/取消，区域合并/去除会在存在传播帧时先选择当前帧/所有传播帧/按帧范围选择并保留传播 metadata。
 - R6：`backend/tests/test_sam3_engine.py` 已标记跳过，仅作为历史保留实现的参考测试，不计入当前产品功能覆盖。
 - R3：补充 `parseMedia()` 查询参数和后端拆帧任务 payload 测试，验证 `parse_fps`、`max_frames`、`target_width` 会进入任务。
 - R3：补充 `ProjectLibrary.test.tsx` 和 `api.test.ts` 中上传进度测试，验证视频/DICOM 上传通过 Axios `onUploadProgress` 回调更新项目库导入进度条，并显示 DICOM 文件数量和解析任务轮询进度。

src/components/CanvasArea.test.tsx

@@ -993,6 +993,68 @@ describe('CanvasArea', () => {
     }));
   });
 
+  it('can hand propagated boolean operations to the workspace frame range selector', () => {
+    const onRequestBooleanFrameRange = vi.fn();
+    useStore.setState({
+      masks: [
+        {
+          id: 'annotation-1',
+          annotationId: '1',
+          frameId: 'frame-1',
+          pathData: 'M 10 10 L 60 10 L 60 60 L 10 60 Z',
+          label: 'A',
+          color: '#06b6d4',
+          segmentation: [[10, 10, 60, 10, 60, 60, 10, 60]],
+        },
+        {
+          id: 'annotation-2',
+          annotationId: '2',
+          frameId: 'frame-1',
+          pathData: 'M 50 50 L 100 50 L 100 100 L 50 100 Z',
+          label: 'A',
+          color: '#06b6d4',
+          segmentation: [[50, 50, 100, 50, 100, 100, 50, 100]],
+        },
+        {
+          id: 'annotation-10',
+          annotationId: '10',
+          frameId: 'frame-2',
+          pathData: 'M 12 12 L 62 12 L 62 62 L 12 62 Z',
+          label: 'A',
+          color: '#06b6d4',
+          segmentation: [[12, 12, 62, 12, 62, 62, 12, 62]],
+          metadata: { source: 'sam2.1_hiera_tiny_propagation', source_annotation_id: 1, propagation_seed_key: 'annotation:1' },
+        },
+        {
+          id: 'annotation-20',
+          annotationId: '20',
+          frameId: 'frame-2',
+          pathData: 'M 52 52 L 102 52 L 102 102 L 52 102 Z',
+          label: 'A',
+          color: '#06b6d4',
+          segmentation: [[52, 52, 102, 52, 102, 102, 52, 102]],
+          metadata: { source: 'sam2.1_hiera_tiny_propagation', source_annotation_id: 2, propagation_seed_key: 'annotation:2' },
+        },
+      ],
+    });
+
+    render(<CanvasArea activeTool="area_merge" frame={frame} onRequestBooleanFrameRange={onRequestBooleanFrameRange} />);
+    const paths = screen.getAllByTestId('konva-path');
+    fireEvent.click(paths[0]);
+    fireEvent.click(paths[1]);
+    fireEvent.click(screen.getByRole('button', { name: '合并选中' }));
+    fireEvent.click(screen.getByRole('button', { name: '按帧范围选择' }));
+
+    expect(onRequestBooleanFrameRange).toHaveBeenCalledWith(expect.objectContaining({
+      operation: 'area_merge',
+      currentFrameId: 'frame-1',
+      candidateFrameIds: expect.arrayContaining(['frame-1', 'frame-2']),
+      selectedMaskIds: ['annotation-1', 'annotation-2'],
+      execute: expect.any(Function),
+    }));
+    expect(useStore.getState().masks.map((mask) => mask.id).sort()).toEqual(['annotation-1', 'annotation-10', 'annotation-2', 'annotation-20']);
+  });
+
   it('removes overlap from the primary selected mask with polygon difference', () => {
     useStore.setState({
       masks: [

src/components/CanvasArea.tsx

@@ -6,10 +6,21 @@ import { useStore } from '../store/useStore';
 import { predictMask } from '../lib/api';
 import type { Frame, Mask } from '../store/useStore';
 
+type BooleanOperationTool = 'area_merge' | 'area_remove';
+
+export interface BooleanFrameRangeRequest {
+  operation: BooleanOperationTool;
+  currentFrameId: string;
+  candidateFrameIds: string[];
+  selectedMaskIds: string[];
+  execute: (targetFrameIds: Set<string>) => Promise<void> | void;
+}
+
 interface CanvasAreaProps {
   activeTool: string;
   frame: Frame | null;
   onRequestDeleteMasks?: (maskIds: string[]) => void;
+  onRequestBooleanFrameRange?: (request: BooleanFrameRangeRequest) => void;
   onDeleteMaskAnnotations?: (annotationIds: string[]) => Promise<void> | void;
 }
 
@@ -417,7 +428,7 @@ function geometriesOverlap(first: MultiPolygon, second: MultiPolygon): boolean {
   return polygonClipping.intersection(first, second).length > 0;
 }
 
-export function CanvasArea({ activeTool, frame, onRequestDeleteMasks, onDeleteMaskAnnotations }: CanvasAreaProps) {
+export function CanvasArea({ activeTool, frame, onRequestDeleteMasks, onRequestBooleanFrameRange, onDeleteMaskAnnotations }: CanvasAreaProps) {
   const containerRef = useRef<HTMLDivElement>(null);
   const [stageSize, setStageSize] = useState({ width: 800, height: 600 });
   const [scale, setScale] = useState(1);
@@ -1801,6 +1812,24 @@ export function CanvasArea({ activeTool, frame, onRequestDeleteMasks, onDeleteMa
                >
                  取消
                </button>
+               {onRequestBooleanFrameRange && (effectiveTool === 'area_merge' || effectiveTool === 'area_remove') && (
+                 <button
+                   type="button"
+                   onClick={() => {
+                     onRequestBooleanFrameRange({
+                       operation: effectiveTool,
+                       currentFrameId: String(frame.id),
+                       candidateFrameIds: pendingBooleanFrameIds,
+                       selectedMaskIds: booleanSelectedMasks.map((mask) => mask.id),
+                       execute: runBooleanOperation,
+                     });
+                     setPendingBooleanFrameIds(null);
+                   }}
+                   className="rounded border border-amber-400/30 bg-amber-500/10 px-3 py-1.5 text-xs font-semibold text-amber-100 hover:bg-amber-500/20"
+                 >
+                   按帧范围选择
+                 </button>
+               )}
                <button
                  type="button"
                  onClick={() => void runBooleanOperation(new Set([String(frame.id)]))}

src/components/VideoWorkspace.test.tsx

@@ -1187,9 +1187,134 @@ describe('VideoWorkspace', () => {
     fireEvent.click(screen.getByRole('button', { name: '自动传播' }));
 
     expect(screen.getByText('请在播放进度条或视频处理进度条上点击/拖拽选择传播起止帧，再点击“开始传播”')).toBeInTheDocument();
+    expect(screen.getAllByText('SAM 2.1 Tiny').length).toBeGreaterThan(0);
+    expect(screen.getByText('向前 0 帧')).toBeInTheDocument();
+    expect(screen.getByText('向后 2 帧')).toBeInTheDocument();
     expect(apiMock.queuePropagationTask).not.toHaveBeenCalled();
   });
 
+  it('uses the timeline frame range selector for propagated boolean operations', async () => {
+    apiMock.getProjectFrames.mockResolvedValueOnce([
+      { id: 10, project_id: 1, frame_index: 0, image_url: '/frame-0.jpg', width: 640, height: 360 },
+      { id: 11, project_id: 1, frame_index: 1, image_url: '/frame-1.jpg', width: 640, height: 360 },
+      { id: 12, project_id: 1, frame_index: 2, image_url: '/frame-2.jpg', width: 640, height: 360 },
+    ]);
+
+    render(<VideoWorkspace />);
+    await waitFor(() => expect(useStore.getState().frames).toHaveLength(3));
+    act(() => {
+      useStore.setState({
+        masks: [
+          {
+            id: 'annotation-1',
+            annotationId: '1',
+            frameId: '10',
+            pathData: 'M 10 10 L 60 10 L 60 60 L 10 60 Z',
+            label: 'A',
+            color: '#06b6d4',
+            segmentation: [[10, 10, 60, 10, 60, 60, 10, 60]],
+            saved: true,
+            saveStatus: 'saved',
+          },
+          {
+            id: 'annotation-2',
+            annotationId: '2',
+            frameId: '10',
+            pathData: 'M 50 50 L 100 50 L 100 100 L 50 100 Z',
+            label: 'A',
+            color: '#06b6d4',
+            segmentation: [[50, 50, 100, 50, 100, 100, 50, 100]],
+            saved: true,
+            saveStatus: 'saved',
+          },
+          {
+            id: 'annotation-10',
+            annotationId: '10',
+            frameId: '11',
+            pathData: 'M 12 12 L 62 12 L 62 62 L 12 62 Z',
+            label: 'A',
+            color: '#06b6d4',
+            segmentation: [[12, 12, 62, 12, 62, 62, 12, 62]],
+            saved: true,
+            saveStatus: 'saved',
+            metadata: { source: 'sam2.1_hiera_tiny_propagation', source_annotation_id: 1, source_mask_id: 'annotation-1', propagation_seed_key: 'annotation:1' },
+          },
+          {
+            id: 'annotation-20',
+            annotationId: '20',
+            frameId: '11',
+            pathData: 'M 52 52 L 102 52 L 102 102 L 52 102 Z',
+            label: 'A',
+            color: '#06b6d4',
+            segmentation: [[52, 52, 102, 52, 102, 102, 52, 102]],
+            saved: true,
+            saveStatus: 'saved',
+            metadata: { source: 'sam2.1_hiera_tiny_propagation', source_annotation_id: 2, source_mask_id: 'annotation-2', propagation_seed_key: 'annotation:2' },
+          },
+          {
+            id: 'annotation-11',
+            annotationId: '11',
+            frameId: '12',
+            pathData: 'M 14 14 L 64 14 L 64 64 L 14 64 Z',
+            label: 'A',
+            color: '#06b6d4',
+            segmentation: [[14, 14, 64, 14, 64, 64, 14, 64]],
+            saved: true,
+            saveStatus: 'saved',
+            metadata: { source: 'sam2.1_hiera_tiny_propagation', source_annotation_id: 1, source_mask_id: 'annotation-1', propagation_seed_key: 'annotation:1' },
+          },
+          {
+            id: 'annotation-21',
+            annotationId: '21',
+            frameId: '12',
+            pathData: 'M 54 54 L 104 54 L 104 104 L 54 104 Z',
+            label: 'A',
+            color: '#06b6d4',
+            segmentation: [[54, 54, 104, 54, 104, 104, 54, 104]],
+            saved: true,
+            saveStatus: 'saved',
+            metadata: { source: 'sam2.1_hiera_tiny_propagation', source_annotation_id: 2, source_mask_id: 'annotation-2', propagation_seed_key: 'annotation:2' },
+          },
+        ],
+        activeTool: 'area_merge',
+      });
+    });
+    apiMock.getProjectAnnotations.mockResolvedValue([
+      { id: 1, frame_id: 10 },
+      { id: 2, frame_id: 10 },
+      { id: 10, frame_id: 11 },
+      { id: 20, frame_id: 11 },
+      { id: 11, frame_id: 12 },
+      { id: 21, frame_id: 12 },
+    ]);
+
+    const paths = await screen.findAllByTestId('konva-path');
+    fireEvent.click(paths[0]);
+    fireEvent.click(paths[1]);
+    fireEvent.click(screen.getByRole('button', { name: '合并选中' }));
+    fireEvent.click(screen.getByRole('button', { name: '按帧范围选择' }));
+
+    expect(screen.getByText('请选择区域合并帧范围，再点击“确认区域合并”')).toBeInTheDocument();
+    expect(screen.getAllByTestId('propagation-range-overlay')).toHaveLength(2);
+    fireEvent.change(screen.getByLabelText('传播结束帧'), { target: { value: '2' } });
+    fireEvent.click(screen.getByRole('button', { name: '确认区域合并' }));
+    expect(screen.getByText(/对 2 帧存在对应传播链的区域执行区域合并/)).toBeInTheDocument();
+    const confirmButtons = screen.getAllByRole('button', { name: '确认区域合并' });
+    fireEvent.click(confirmButtons[confirmButtons.length - 1]);
+
+    await waitFor(() => {
+      const ids = useStore.getState().masks.map((mask) => mask.id).sort();
+      expect(ids).toEqual(['annotation-1', 'annotation-10', 'annotation-11', 'annotation-21']);
+    });
+    expect(apiMock.deleteAnnotation).toHaveBeenCalledWith('2');
+    expect(apiMock.deleteAnnotation).toHaveBeenCalledWith('20');
+    expect(apiMock.deleteAnnotation).not.toHaveBeenCalledWith('21');
+    expect(useStore.getState().masks.find((mask) => mask.id === 'annotation-10')).toEqual(expect.objectContaining({
+      saveStatus: 'dirty',
+      metadata: expect.objectContaining({ source: 'sam2.1_hiera_tiny_propagation' }),
+    }));
+  });
+
   it('exports only the current frame when current image scope is selected', async () => {
     apiMock.getProjectFrames.mockResolvedValueOnce([
       { id: 10, project_id: 1, frame_index: 0, image_url: '/frame-0.jpg', width: 640, height: 360 },

src/components/VideoWorkspace.tsx

@@ -17,7 +17,7 @@ import {
   type SegmentationExportOutput,
   updateAnnotation,
 } from '../lib/api';
-import { CanvasArea } from './CanvasArea';
+import { CanvasArea, type BooleanFrameRangeRequest } from './CanvasArea';
 import { ToolsPalette } from './ToolsPalette';
 import { OntologyInspector } from './OntologyInspector';
 import { FrameTimeline } from './FrameTimeline';
@@ -43,7 +43,7 @@ type PropagationHistorySegment = {
   colorIndex: number;
   label: string;
 };
-type RangeSelectionMode = 'propagation' | 'clear' | 'export' | null;
+type RangeSelectionMode = 'propagation' | 'clear' | 'export' | 'boolean' | null;
 type ClearRangeMode = 'all' | 'propagated_only';
 type ClearRangeConfirmState = {
   frameIdsToClear: string[];
@@ -61,6 +61,12 @@ type CurrentClearConfirmState = {
   currentMaskCount: number;
   propagatedMaskCount: number;
 };
+type BooleanRangeConfirmState = {
+  request: BooleanFrameRangeRequest;
+  targetFrameIds: string[];
+  rangeStartIndex: number;
+  rangeEndIndex: number;
+};
 type GtUnknownPolicy = 'discard' | 'undefined';
 type ExportScope = 'all' | 'range' | 'current';
 type ExportPreviewPolygon = {
@@ -344,6 +350,10 @@ const expandedPropagationDeletionMaskIds = (selectedIds: string[], allMasks: Mas
   );
 };
 
+const booleanOperationLabel = (operation: BooleanFrameRangeRequest['operation']) => (
+  operation === 'area_merge' ? '区域合并' : '重叠区域去除'
+);
+
 const persistentMaskMetadata = (metadata?: Record<string, unknown>) => {
   if (!metadata) return {};
   const {
@@ -511,6 +521,8 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
   const [clearRangeMode, setClearRangeMode] = useState<ClearRangeMode>('all');
   const [pendingClearRangeConfirm, setPendingClearRangeConfirm] = useState<ClearRangeConfirmState | null>(null);
   const [pendingCurrentClearConfirm, setPendingCurrentClearConfirm] = useState<CurrentClearConfirmState | null>(null);
+  const [pendingBooleanRangeRequest, setPendingBooleanRangeRequest] = useState<BooleanFrameRangeRequest | null>(null);
+  const [pendingBooleanRangeConfirm, setPendingBooleanRangeConfirm] = useState<BooleanRangeConfirmState | null>(null);
   const [hasExplicitPropagationRange, setHasExplicitPropagationRange] = useState(false);
   const [propagationProgress, setPropagationProgress] = useState<PropagationProgress>(null);
   const [propagationTaskId, setPropagationTaskId] = useState<number | null>(null);
@@ -660,6 +672,7 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
     normalizeClassMaskIds(activeTemplateForGt?.classes || [])
   ), [activeTemplateForGt?.classes]);
   const frameById = useMemo(() => new Map(frames.map((frame) => [frame.id, frame])), [frames]);
+  const frameNumberById = useMemo(() => new Map(frames.map((frame, index) => [String(frame.id), index + 1])), [frames]);
   const projectFrameIds = useMemo(() => new Set(frames.map((frame) => frame.id)), [frames]);
   const currentFrameNumber = currentFrameIndex + 1;
   const pendingAnnotationChangeCount = useMemo(() => (
@@ -687,7 +700,6 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
 
   useEffect(() => {
     if (propagationHistory.length === 0 || frames.length === 0) return;
-    const frameNumberById = new Map(frames.map((frame, index) => [String(frame.id), index + 1]));
     const activePropagatedFrameNumbers = new Set<number>();
     masks.forEach((mask) => {
       if (!isPropagatedMask(mask)) return;
@@ -702,7 +714,7 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
     if (!propagationHistoryEqual(propagationHistory, nextHistory)) {
       setPropagationHistory(nextHistory);
     }
-  }, [frames, masks, propagationHistory, totalFrames]);
+  }, [frameNumberById, frames.length, masks, propagationHistory, totalFrames]);
 
   useEffect(() => {
     if (!statusMessage || isWorkspaceBusy || totalFrames === 0) return undefined;
@@ -724,6 +736,8 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
     setExportEndFrame(Math.min(totalFrames, currentFrameNumber + 29));
     setIsPropagationRangeSelecting(false);
     setRangeSelectionMode(null);
+    setPendingBooleanRangeRequest(null);
+    setPendingBooleanRangeConfirm(null);
     setHasExplicitPropagationRange(false);
   }, [currentFrameNumber, totalFrames]);
 
@@ -1018,6 +1032,76 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
     await executeClearFrameRange(request);
   }, [clearRangeMode, executeClearFrameRange, frames, masks, propagationEndFrame, propagationStartFrame, rangeSelectionMode, totalFrames]);
 
+  const handleBooleanFrameRangeRequest = useCallback((request: BooleanFrameRangeRequest) => {
+    const candidateFrameNumbers = request.candidateFrameIds
+      .map((frameId) => frameNumberById.get(String(frameId)))
+      .filter((frameNumber): frameNumber is number => Boolean(frameNumber));
+    if (candidateFrameNumbers.length === 0) {
+      setStatusMessage(`${booleanOperationLabel(request.operation)}没有可按范围处理的传播帧`);
+      return;
+    }
+    const startFrame = Math.min(...candidateFrameNumbers);
+    const endFrame = Math.max(...candidateFrameNumbers);
+    setPendingBooleanRangeRequest(request);
+    setPendingBooleanRangeConfirm(null);
+    setPropagationStartFrame(startFrame);
+    setPropagationEndFrame(endFrame);
+    setHasExplicitPropagationRange(true);
+    setIsPropagationRangeSelecting(true);
+    setRangeSelectionMode('boolean');
+    setStatusMessage(`请选择${booleanOperationLabel(request.operation)}帧范围，再点击“确认${booleanOperationLabel(request.operation)}”`);
+  }, [frameNumberById]);
+
+  const handleConfirmBooleanFrameRangeOperation = useCallback(() => {
+    if (!pendingBooleanRangeRequest || frames.length === 0) return;
+    const clampRangeFrameNumber = (value: number) => {
+      if (totalFrames <= 0) return 1;
+      return Math.min(Math.max(value, 1), totalFrames);
+    };
+    const startFrameNumber = clampRangeFrameNumber(propagationStartFrame);
+    const endFrameNumber = clampRangeFrameNumber(propagationEndFrame);
+    const rangeStartIndex = Math.min(startFrameNumber, endFrameNumber) - 1;
+    const rangeEndIndex = Math.max(startFrameNumber, endFrameNumber) - 1;
+    const rangeFrameIds = new Set(
+      frames.slice(rangeStartIndex, rangeEndIndex + 1).map((frame) => String(frame.id)),
+    );
+    const targetFrameIds = pendingBooleanRangeRequest.candidateFrameIds
+      .filter((frameId) => rangeFrameIds.has(String(frameId)))
+      .sort((a, b) => (frameNumberById.get(String(a)) || 0) - (frameNumberById.get(String(b)) || 0));
+
+    if (targetFrameIds.length === 0) {
+      setStatusMessage(`第 ${rangeStartIndex + 1}-${rangeEndIndex + 1} 帧没有可执行${booleanOperationLabel(pendingBooleanRangeRequest.operation)}的对应传播区域`);
+      return;
+    }
+
+    setPendingBooleanRangeConfirm({
+      request: pendingBooleanRangeRequest,
+      targetFrameIds,
+      rangeStartIndex,
+      rangeEndIndex,
+    });
+  }, [frameNumberById, frames, pendingBooleanRangeRequest, propagationEndFrame, propagationStartFrame, totalFrames]);
+
+  const executeBooleanFrameRangeOperation = useCallback(async (confirmState: BooleanRangeConfirmState) => {
+    const label = booleanOperationLabel(confirmState.request.operation);
+    setIsSaving(true);
+    setStatusMessage(`正在对第 ${confirmState.rangeStartIndex + 1}-${confirmState.rangeEndIndex + 1} 帧执行${label}...`);
+    try {
+      await confirmState.request.execute(new Set(confirmState.targetFrameIds));
+      setPendingBooleanRangeConfirm(null);
+      setPendingBooleanRangeRequest(null);
+      setIsPropagationRangeSelecting(false);
+      setRangeSelectionMode(null);
+      setHasExplicitPropagationRange(false);
+      setStatusMessage(`已对第 ${confirmState.rangeStartIndex + 1}-${confirmState.rangeEndIndex + 1} 帧内 ${confirmState.targetFrameIds.length} 帧执行${label}`);
+    } catch (err) {
+      console.error('Boolean frame range operation failed:', err);
+      setStatusMessage(`${label}失败，请检查后端服务`);
+    } finally {
+      setIsSaving(false);
+    }
+  }, []);
+
   const handleDeleteMaskAnnotations = useCallback(async (annotationIds: string[]) => {
     if (annotationIds.length === 0) return;
     try {
@@ -1332,7 +1416,11 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
     setPropagationStartFrame(nextStart);
     setPropagationEndFrame(nextEnd);
     setHasExplicitPropagationRange(true);
-    const actionLabel = rangeSelectionMode === 'clear' ? '清空范围' : '自动传播范围';
+    const actionLabel = rangeSelectionMode === 'clear'
+      ? '清空范围'
+      : rangeSelectionMode === 'boolean'
+        ? '布尔操作范围'
+        : '自动传播范围';
     setStatusMessage(`已选择${actionLabel}：第 ${Math.min(nextStart, nextEnd)}-${Math.max(nextStart, nextEnd)} 帧`);
   }, [clampFrameNumber, rangeSelectionMode]);
 
@@ -1542,6 +1630,8 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
     const previousMode = rangeSelectionMode;
     setIsPropagationRangeSelecting(false);
     setRangeSelectionMode(null);
+    setPendingBooleanRangeRequest(null);
+    setPendingBooleanRangeConfirm(null);
     setHasExplicitPropagationRange(false);
     setPropagationStartFrame(currentFrameNumber || 1);
     setPropagationEndFrame(Math.min(Math.max(totalFrames, 1), (currentFrameNumber || 1) + 29));
@@ -1549,7 +1639,15 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
       setStatusMessage('已取消导出范围选择');
       return;
     }
-    setStatusMessage(previousMode === 'clear' ? '已取消清空片段范围选择' : '已取消自动传播范围选择');
+    if (previousMode === 'clear') {
+      setStatusMessage('已取消清空片段范围选择');
+      return;
+    }
+    if (previousMode === 'boolean') {
+      setStatusMessage('已取消布尔操作范围选择');
+      return;
+    }
+    setStatusMessage('已取消自动传播范围选择');
   };
 
   const visibleTimelineRange = rangeSelectionMode === 'export'
@@ -1576,6 +1674,10 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
   const propagationPercent = propagationProgress
     ? Math.round((propagationProgress.completedSteps / Math.max(propagationProgress.totalSteps, 1)) * 100)
     : 0;
+  const selectedRangeStartFrame = Math.min(propagationStartFrame, propagationEndFrame);
+  const selectedRangeEndFrame = Math.max(propagationStartFrame, propagationEndFrame);
+  const propagationBackwardFrameCount = Math.max(0, currentFrameNumber - selectedRangeStartFrame);
+  const propagationForwardFrameCount = Math.max(0, selectedRangeEndFrame - currentFrameNumber);
 
   return (
     <div className="w-full h-full flex flex-col bg-[#0a0a0a]">
@@ -1654,6 +1756,17 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
               ))}
             </select>
           </div>
+          {rangeSelectionMode === 'propagation' && (
+            <div
+              className="flex items-center gap-2 rounded-md border border-cyan-500/20 bg-cyan-500/[0.06] px-2 py-1 text-[10px] text-cyan-100"
+              title="向前表示更早帧，向后表示更晚帧"
+            >
+              <span className="font-semibold">{propagationWeightLabel}</span>
+              <span className="text-gray-500">|</span>
+              <span>向前 {propagationBackwardFrameCount} 帧</span>
+              <span>向后 {propagationForwardFrameCount} 帧</span>
+            </div>
+          )}
           <input
             ref={gtMaskInputRef}
             type="file"
@@ -1777,6 +1890,16 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
               className="h-6 w-14 rounded bg-black/20 border border-white/10 px-1 text-[10px] text-gray-300 outline-none focus:border-cyan-500/50 disabled:opacity-40"
             />
           </div>
+          {rangeSelectionMode === 'boolean' && pendingBooleanRangeRequest ? (
+            <button
+              onClick={handleConfirmBooleanFrameRangeOperation}
+              disabled={frames.length === 0 || isSaving || isExporting || isImportingGt || isPropagating}
+              title={`按当前起止帧执行${booleanOperationLabel(pendingBooleanRangeRequest.operation)}`}
+              className="px-3 py-1.5 bg-emerald-500/10 hover:bg-emerald-500/20 border border-emerald-500/25 rounded-md text-xs transition-colors text-emerald-200 disabled:opacity-40 disabled:cursor-not-allowed"
+            >
+              确认{booleanOperationLabel(pendingBooleanRangeRequest.operation)}
+            </button>
+          ) : (
             <button
               onClick={handleClearFrameRangeMasks}
               disabled={frames.length === 0 || isSaving || isExporting || isImportingGt || isPropagating}
@@ -1785,6 +1908,7 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
             >
               {rangeSelectionMode === 'clear' ? '确认清空' : '清空片段遮罩'}
             </button>
+          )}
           {rangeSelectionMode === 'clear' && (
             <div className="flex items-center gap-1 rounded-md border border-red-500/20 bg-red-500/[0.04] px-1 py-1">
               <button
@@ -2038,6 +2162,7 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
               activeTool={activeTool}
               frame={currentFrame}
               onRequestDeleteMasks={(maskIds) => void handleDeleteSelectedMasks(maskIds)}
+              onRequestBooleanFrameRange={handleBooleanFrameRangeRequest}
               onDeleteMaskAnnotations={handleDeleteMaskAnnotations}
             />
           </div>
@@ -2134,6 +2259,39 @@ export function VideoWorkspace({ onNavigateToAI }: { onNavigateToAI?: () => void
         </div>
       )}
 
+      {pendingBooleanRangeConfirm && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/70 px-4">
+          <div className="w-full max-w-md rounded-lg border border-emerald-400/25 bg-[#151515] p-5 shadow-2xl">
+            <h2 className="text-lg font-semibold text-white">确认{booleanOperationLabel(pendingBooleanRangeConfirm.request.operation)}</h2>
+            <p className="mt-2 text-sm leading-relaxed text-gray-300">
+              将在第 {pendingBooleanRangeConfirm.rangeStartIndex + 1}-{pendingBooleanRangeConfirm.rangeEndIndex + 1} 帧范围内，
+              对 {pendingBooleanRangeConfirm.targetFrameIds.length} 帧存在对应传播链的区域执行{booleanOperationLabel(pendingBooleanRangeConfirm.request.operation)}。
+            </p>
+            <p className="mt-2 text-xs leading-relaxed text-emerald-100/70">
+              本操作会保留传播帧原有来源属性，只把几何结果标记为待保存。
+            </p>
+            <div className="mt-5 flex justify-end gap-2">
+              <button
+                type="button"
+                onClick={() => setPendingBooleanRangeConfirm(null)}
+                disabled={isSaving}
+                className="rounded border border-white/10 px-3 py-2 text-xs text-gray-300 hover:bg-white/5 disabled:opacity-50"
+              >
+                取消
+              </button>
+              <button
+                type="button"
+                onClick={() => void executeBooleanFrameRangeOperation(pendingBooleanRangeConfirm)}
+                disabled={isSaving}
+                className="rounded bg-emerald-500 px-3 py-2 text-xs font-semibold text-white hover:bg-emerald-400 disabled:cursor-wait disabled:opacity-50"
+              >
+                确认{booleanOperationLabel(pendingBooleanRangeConfirm.request.operation)}
+              </button>
+            </div>
+          </div>
+        </div>
+      )}
+
       {/* Bottom Timeline */}
       <FrameTimeline
         propagationRange={visibleTimelineRange}