feat: 建立 SAM2 标注闭环基线

- 打通工作区真实标注闭环：支持手工多边形、矩形、圆形、点区域和线段生成 mask，并可保存、回显、更新和删除后端 annotation。

- 增强 polygon 编辑器：支持顶点拖动、顶点删除、边中点插入、多 polygon 子区域选择编辑，以及区域合并和区域去除。

- 接入 GT mask 导入：后端支持二值/多类别 mask 拆分、contour 转 polygon、distance transform seed point，前端支持导入、回显和 seed point 拖动编辑。

- 完善导出能力：COCO JSON 导出对齐前端，PNG mask ZIP 同时包含单标注 mask、按 zIndex 融合的 semantic_frame 和 semantic_classes.json。

- 打通异步任务管理：新增任务取消、重试、失败详情接口与 Dashboard 控件，worker 支持取消状态检查并通过 Redis/WebSocket 推送 cancelled 事件。

- 对接 Dashboard 后端数据：概览统计、解析队列和实时流转记录从 FastAPI 聚合接口与 WebSocket 更新。

- 增强 AI 推理参数：前端发送 crop_to_prompt、auto_filter_background 和 min_score，后端支持点/框 prompt 局部裁剪推理、结果回映射和负向点/低分过滤。

- 接入 SAM3 基础设施：新增独立 Python 3.12 sam3 环境安装脚本、外部 worker helper、后端桥接和真实 Python/CUDA/包/HF checkpoint access 状态检测。

- 保留 SAM3 授权边界：当前官方 facebook/sam3 gated 权重未授权时状态接口会返回不可用，不伪装成可推理。

- 增强前端状态管理：新增 mask undo/redo 历史栈、AI 模型选择状态、保存状态 dirty/draft/saved 流转和项目状态归一化。

- 更新前端 API 封装：补充 annotation CRUD、GT mask import、mask ZIP export、task cancel/retry/detail、AI runtime status 和 prediction options。

- 更新 UI 控件：ToolsPalette、AISegmentation、VideoWorkspace 和 CanvasArea 接入真实操作、导入导出、撤销重做、任务控制和模型状态。

- 新增 polygon-clipping 依赖，用于前端区域 union/difference 几何运算。

- 完善后端 schemas/status/progress：补充 AI 模型外部状态字段、任务 cancelled 状态和进度事件 payload。

- 补充测试覆盖：新增后端任务控制、SAM3 桥接、GT mask、导出融合、AI options 测试；补充前端 Canvas、Dashboard、VideoWorkspace、ToolsPalette、API 和 store 测试。

- 更新 README、AGENTS 和 doc 文档：冻结当前需求/设计/测试计划，标注真实功能、剩余 Mock、SAM3 授权边界和后续实施顺序。

src/components/VideoWorkspace.test.tsx

@@ -14,6 +14,8 @@ const apiMock = vi.hoisted(() => ({
   updateAnnotation: vi.fn(),
   deleteAnnotation: vi.fn(),
   exportCoco: vi.fn(),
+  exportMasks: vi.fn(),
+  importGtMask: vi.fn(),
   annotationToMask: vi.fn(),
   buildAnnotationPayload: vi.fn(),
   getAiModelStatus: vi.fn(),
@@ -29,6 +31,8 @@ vi.mock('../lib/api', () => ({
   updateAnnotation: apiMock.updateAnnotation,
   deleteAnnotation: apiMock.deleteAnnotation,
   exportCoco: apiMock.exportCoco,
+  exportMasks: apiMock.exportMasks,
+  importGtMask: apiMock.importGtMask,
   annotationToMask: apiMock.annotationToMask,
   buildAnnotationPayload: apiMock.buildAnnotationPayload,
   getAiModelStatus: apiMock.getAiModelStatus,
@@ -256,4 +260,64 @@ describe('VideoWorkspace', () => {
     await waitFor(() => expect(apiMock.saveAnnotation).toHaveBeenCalled());
     expect(apiMock.exportCoco).toHaveBeenCalledWith('1');
   });
+
+  it('auto-saves pending masks before exporting PNG masks', async () => {
+    apiMock.getProjectFrames.mockResolvedValueOnce([
+      { id: 10, project_id: 1, frame_index: 0, image_url: '/frame.jpg', width: 640, height: 360 },
+    ]);
+    apiMock.buildAnnotationPayload.mockReturnValueOnce({ project_id: 1, frame_id: 10, mask_data: { polygons: [] } });
+    apiMock.saveAnnotation.mockResolvedValueOnce({ id: 5 });
+    apiMock.exportMasks.mockResolvedValueOnce(new Blob(['zip'], { type: 'application/zip' }));
+
+    render(<VideoWorkspace />);
+    await waitFor(() => expect(useStore.getState().frames).toHaveLength(1));
+    act(() => {
+      useStore.setState({
+        masks: [{
+          id: 'mask-1',
+          frameId: '10',
+          pathData: 'M 0 0 Z',
+          label: 'AI Mask',
+          color: '#06b6d4',
+          segmentation: [[0, 0, 10, 0, 10, 10]],
+        }],
+      });
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '导出 PNG Mask ZIP' }));
+
+    await waitFor(() => expect(apiMock.saveAnnotation).toHaveBeenCalled());
+    expect(apiMock.exportMasks).toHaveBeenCalledWith('1');
+  });
+
+  it('imports a GT mask for the current frame and hydrates saved annotations', async () => {
+    apiMock.getProjectFrames.mockResolvedValueOnce([
+      { id: 10, project_id: 1, frame_index: 0, image_url: '/frame.jpg', width: 640, height: 360 },
+    ]);
+    apiMock.importGtMask.mockResolvedValueOnce([{ id: 88, frame_id: 10 }]);
+    apiMock.getProjectAnnotations
+      .mockResolvedValueOnce([])
+      .mockResolvedValueOnce([{ id: 88, frame_id: 10 }]);
+    apiMock.annotationToMask.mockReturnValueOnce({
+      id: 'annotation-88',
+      annotationId: '88',
+      frameId: '10',
+      saved: true,
+      pathData: 'M 0 0 Z',
+      label: 'GT Mask',
+      color: '#22c55e',
+    });
+
+    render(<VideoWorkspace />);
+    await waitFor(() => expect(useStore.getState().frames).toHaveLength(1));
+
+    const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
+    const file = new File(['mask'], 'mask.png', { type: 'image/png' });
+    fireEvent.change(fileInput, { target: { files: [file] } });
+
+    await waitFor(() => expect(apiMock.importGtMask).toHaveBeenCalledWith(file, '1', '10'));
+    await waitFor(() => expect(useStore.getState().masks).toEqual([
+      expect.objectContaining({ id: 'annotation-88', label: 'GT Mask' }),
+    ]));
+  });
 });