feat: 完善分割工作区传播与交互闭环

功能增加：新增后端传播任务执行器，支持异步自动传播、传播进度、结果统计、取消/重试状态同步。

功能增加：传播请求支持指定 SAM2.1 tiny/small/base+/large 权重，并记录 seed mask、source annotation 和传播范围。

功能增加：传播逻辑增加 seed 签名，未变化的 mask 二次传播会跳过，已变化的 mask 会先清理旧自动传播结果再重新生成，避免重复重叠。

功能增加：工作区增加传播范围二次选择、传播进度提示、人工/AI 标注帧红色标识、自动传播帧蓝色标识和当前帧双层边框。

功能增加：新增临时提示组件，让工具操作提示自动消失且不阻塞后续操作。

功能增加：补充项目删除、模板删除、任务失败详情、任务取消/重试等前后端联动状态。

功能增加：新增安装部署文档，补充当前需求冻结、设计冻结、接口契约、测试计划和 AGENTS/README 项目说明。

Bugfix：修复自动传播接口 404、传播后看不到任务进度、传播结果重复堆叠和已编辑帧提示不清晰的问题。

Bugfix：修复 AI 分割框选/点选交互、单候选 mask、删除选点、工作区保存与候选 mask 推送相关问题。

Bugfix：修复 Canvas 多边形顶点拖动告警、工具栏提示缺失、项目库 FPS 展示和若干 UI 文案/可用性问题。

测试：补充 AI 分割、Canvas、Dashboard、FrameTimeline、ProjectLibrary、TemplateRegistry、ToolsPalette、VideoWorkspace、API 和后端任务/AI/dashboard 测试。

验证：npm run lint；npm run test:run；python -m pytest backend/tests -q。

backend/tests/test_ai.py

@@ -1,5 +1,8 @@
 import numpy as np
 import cv2
+from pathlib import Path
+from models import Annotation, ProcessingTask
+from services.propagation_task_runner import run_propagate_project_task
 
 
 def _create_project_and_frame(client):
@@ -294,6 +297,245 @@ def test_propagate_saves_tracked_annotations(client, monkeypatch):
     assert len(listing.json()) == 1
 
 
+def test_queue_propagation_task_creates_processing_task(client, monkeypatch):
+    project = client.post("/api/projects", json={"name": "Queued Propagation"}).json()
+    frame = client.post(f"/api/projects/{project['id']}/frames", json={
+        "project_id": project["id"],
+        "frame_index": 0,
+        "image_url": "frames/0.jpg",
+        "width": 640,
+        "height": 360,
+    }).json()
+
+    class FakeAsyncResult:
+        id = "celery-propagate-1"
+
+    queued = []
+    monkeypatch.setattr("routers.ai.propagate_project_masks.delay", lambda task_id: queued.append(task_id) or FakeAsyncResult())
+    monkeypatch.setattr("routers.ai.publish_task_progress_event", lambda task: None)
+
+    response = client.post("/api/ai/propagate/task", json={
+        "project_id": project["id"],
+        "frame_id": frame["id"],
+        "model": "sam2.1_hiera_tiny",
+        "steps": [{
+            "direction": "forward",
+            "max_frames": 2,
+            "seed": {
+                "polygons": [[[0.1, 0.1], [0.2, 0.1], [0.2, 0.2]]],
+                "label": "胆囊",
+            },
+        }],
+    })
+
+    assert response.status_code == 202
+    body = response.json()
+    assert body["task_type"] == "propagate_masks"
+    assert body["status"] == "queued"
+    assert body["celery_task_id"] == "celery-propagate-1"
+    assert body["payload"]["model"] == "sam2.1_hiera_tiny"
+    assert body["payload"]["steps"][0]["seed"]["label"] == "胆囊"
+    assert queued == [body["id"]]
+
+
+def test_queue_propagation_task_normalizes_model_and_rejects_unsupported(client, monkeypatch):
+    project = client.post("/api/projects", json={"name": "Propagation Model"}).json()
+    frame = client.post(f"/api/projects/{project['id']}/frames", json={
+        "project_id": project["id"],
+        "frame_index": 0,
+        "image_url": "frames/0.jpg",
+        "width": 640,
+        "height": 360,
+    }).json()
+
+    class FakeAsyncResult:
+        id = "celery-propagate-model"
+
+    monkeypatch.setattr("routers.ai.propagate_project_masks.delay", lambda task_id: FakeAsyncResult())
+    monkeypatch.setattr("routers.ai.publish_task_progress_event", lambda task: None)
+
+    response = client.post("/api/ai/propagate/task", json={
+        "project_id": project["id"],
+        "frame_id": frame["id"],
+        "model": "sam2",
+        "steps": [{
+            "direction": "forward",
+            "max_frames": 2,
+            "seed": {
+                "polygons": [[[0.1, 0.1], [0.2, 0.1], [0.2, 0.2]]],
+            },
+        }],
+    })
+
+    assert response.status_code == 202
+    assert response.json()["payload"]["model"] == "sam2.1_hiera_tiny"
+
+    unsupported = client.post("/api/ai/propagate/task", json={
+        "project_id": project["id"],
+        "frame_id": frame["id"],
+        "model": "sam3",
+        "steps": [{
+            "direction": "forward",
+            "max_frames": 2,
+            "seed": {
+                "polygons": [[[0.1, 0.1], [0.2, 0.1], [0.2, 0.2]]],
+            },
+        }],
+    })
+
+    assert unsupported.status_code == 400
+    assert "Unsupported model" in unsupported.json()["detail"]
+
+
+def test_propagation_task_runner_saves_annotations_and_progress(client, db_session, monkeypatch):
+    project = client.post("/api/projects", json={"name": "Propagation Worker"}).json()
+    frames = [
+        client.post(f"/api/projects/{project['id']}/frames", json={
+            "project_id": project["id"],
+            "frame_index": idx,
+            "image_url": f"frames/{idx}.jpg",
+            "width": 640,
+            "height": 360,
+        }).json()
+        for idx in range(2)
+    ]
+    task = ProcessingTask(
+        task_type="propagate_masks",
+        status="queued",
+        progress=0,
+        project_id=project["id"],
+        payload={
+            "project_id": project["id"],
+            "frame_id": frames[0]["id"],
+            "model": "sam2.1_hiera_tiny",
+            "include_source": False,
+            "save_annotations": True,
+            "steps": [{
+                "direction": "forward",
+                "max_frames": 2,
+                "seed": {
+                    "polygons": [[[0.1, 0.1], [0.2, 0.1], [0.2, 0.2]]],
+                    "label": "胆囊",
+                    "color": "#ff0000",
+                    "class_metadata": {"id": "c1", "name": "胆囊"},
+                },
+            }],
+        },
+    )
+    db_session.add(task)
+    db_session.commit()
+    db_session.refresh(task)
+
+    published = []
+    monkeypatch.setattr("services.propagation_task_runner.download_file", lambda object_name: b"jpeg")
+    monkeypatch.setattr("services.propagation_task_runner.publish_task_progress_event", lambda event_task: published.append((event_task.status, event_task.progress)))
+    def fake_propagate_video(model, frame_paths, source_frame_index, seed, direction, max_frames):
+        assert [Path(path).name for path in frame_paths] == ["000000.jpg", "000001.jpg"]
+        return [
+            {"frame_index": 0, "polygons": [[[0.1, 0.1], [0.2, 0.1], [0.2, 0.2]]], "scores": [0.9]},
+            {"frame_index": 1, "polygons": [[[0.15, 0.15], [0.25, 0.15], [0.25, 0.25]]], "scores": [0.8]},
+        ]
+
+    monkeypatch.setattr("services.propagation_task_runner.sam_registry.propagate_video", fake_propagate_video)
+
+    result = run_propagate_project_task(db_session, task.id)
+
+    db_session.refresh(task)
+    assert task.status == "success"
+    assert task.progress == 100
+    assert task.result["model"] == "sam2.1_hiera_tiny"
+    assert task.result["steps"][0]["model"] == "sam2.1_hiera_tiny"
+    assert result["created_annotation_count"] == 1
+    assert result["processed_frame_count"] == 2
+    assert published[0][0] == "running"
+    assert published[-1] == ("success", 100)
+    listing = client.get(f"/api/ai/annotations?project_id={project['id']}")
+    assert listing.json()[0]["frame_id"] == frames[1]["id"]
+    assert listing.json()[0]["mask_data"]["source"] == "sam2.1_hiera_tiny_propagation"
+
+
+def test_propagation_task_runner_skips_unchanged_seed_and_replaces_changed_seed(client, db_session, monkeypatch):
+    project = client.post("/api/projects", json={"name": "Propagation Dedupe"}).json()
+    frames = [
+        client.post(f"/api/projects/{project['id']}/frames", json={
+            "project_id": project["id"],
+            "frame_index": idx,
+            "image_url": f"frames/{idx}.jpg",
+            "width": 640,
+            "height": 360,
+        }).json()
+        for idx in range(2)
+    ]
+
+    def make_task(seed_polygon):
+        task = ProcessingTask(
+            task_type="propagate_masks",
+            status="queued",
+            progress=0,
+            project_id=project["id"],
+            payload={
+                "project_id": project["id"],
+                "frame_id": frames[0]["id"],
+                "model": "sam2.1_hiera_tiny",
+                "include_source": False,
+                "save_annotations": True,
+                "steps": [{
+                    "direction": "forward",
+                    "max_frames": 2,
+                    "seed": {
+                        "polygons": [seed_polygon],
+                        "label": "胆囊",
+                        "color": "#ff0000",
+                        "source_annotation_id": 7,
+                        "source_mask_id": "annotation-7",
+                    },
+                }],
+            },
+        )
+        db_session.add(task)
+        db_session.commit()
+        db_session.refresh(task)
+        return task
+
+    seed_polygon = [[0.1, 0.1], [0.2, 0.1], [0.2, 0.2]]
+    first_output_polygon = [[0.15, 0.15], [0.25, 0.15], [0.25, 0.25]]
+    changed_seed_polygon = [[0.2, 0.2], [0.3, 0.2], [0.3, 0.3]]
+    replacement_output_polygon = [[0.22, 0.22], [0.32, 0.22], [0.32, 0.32]]
+
+    monkeypatch.setattr("services.propagation_task_runner.download_file", lambda object_name: b"jpeg")
+    monkeypatch.setattr("services.propagation_task_runner.publish_task_progress_event", lambda event_task: None)
+    propagate_calls = []
+
+    def fake_propagate_video(model, frame_paths, source_frame_index, seed, direction, max_frames):
+        propagate_calls.append(seed["polygons"][0])
+        output_polygon = replacement_output_polygon if seed["polygons"][0] == changed_seed_polygon else first_output_polygon
+        return [
+            {"frame_index": 0, "polygons": [seed["polygons"][0]], "scores": [0.9]},
+            {"frame_index": 1, "polygons": [output_polygon], "scores": [0.8]},
+        ]
+
+    monkeypatch.setattr("services.propagation_task_runner.sam_registry.propagate_video", fake_propagate_video)
+
+    first_result = run_propagate_project_task(db_session, make_task(seed_polygon).id)
+    assert first_result["created_annotation_count"] == 1
+    assert len(propagate_calls) == 1
+
+    unchanged_result = run_propagate_project_task(db_session, make_task(seed_polygon).id)
+    assert unchanged_result["created_annotation_count"] == 0
+    assert unchanged_result["skipped_seed_count"] == 1
+    assert len(propagate_calls) == 1
+    assert db_session.query(Annotation).filter(Annotation.project_id == project["id"]).count() == 1
+
+    changed_result = run_propagate_project_task(db_session, make_task(changed_seed_polygon).id)
+    assert changed_result["created_annotation_count"] == 1
+    assert changed_result["deleted_annotation_count"] == 1
+    assert len(propagate_calls) == 2
+    annotations = db_session.query(Annotation).filter(Annotation.project_id == project["id"]).all()
+    assert len(annotations) == 1
+    assert annotations[0].mask_data["polygons"] == [replacement_output_polygon]
+    assert annotations[0].mask_data["source_annotation_id"] == 7
+
+
 def test_predict_validation_errors(client, monkeypatch):
     project, _, _ = _create_project_and_frame(client)
 

backend/tests/test_dashboard.py

@@ -110,3 +110,31 @@ def test_dashboard_overview_keeps_recent_success_tasks_in_progress_list(client,
             "updated_at": body["tasks"][0]["updated_at"],
         },
     ]
+
+
+def test_dashboard_overview_uses_processed_frame_count_for_propagation_tasks(client, db_session):
+    from models import ProcessingTask
+
+    project = client.post("/api/projects", json={
+        "name": "Propagation Project",
+        "status": "ready",
+    }).json()
+    task = ProcessingTask(
+        task_type="propagate_masks",
+        status="running",
+        progress=45,
+        message="向后传播 胆囊 (1/2)",
+        project_id=project["id"],
+        payload={"project_id": project["id"]},
+        result={"processed_frame_count": 8, "created_annotation_count": 3},
+    )
+    db_session.add(task)
+    db_session.commit()
+    db_session.refresh(task)
+
+    response = client.get("/api/dashboard/overview")
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["tasks"][0]["task_id"] == task.id
+    assert body["tasks"][0]["frame_count"] == 8

backend/tests/test_tasks.py

@@ -84,6 +84,42 @@ def test_retry_task_creates_fresh_parse_task(client, db_session, monkeypatch):
     assert client.get(f"/api/projects/{project['id']}").json()["status"] == "parsing"
 
 
+def test_retry_task_dispatches_propagation_worker_without_media_requirement(client, db_session, monkeypatch):
+    project = client.post("/api/projects", json={"name": "Retry Propagation"}).json()
+    task = ProcessingTask(
+        task_type="propagate_masks",
+        status="failed",
+        progress=100,
+        message="自动传播失败",
+        error="model unavailable",
+        project_id=project["id"],
+        payload={
+            "project_id": project["id"],
+            "frame_id": 1,
+            "steps": [],
+        },
+    )
+    db_session.add(task)
+    db_session.commit()
+    db_session.refresh(task)
+
+    class FakeAsyncResult:
+        id = "celery-propagation-retry"
+
+    queued = []
+    monkeypatch.setattr("routers.tasks.propagate_project_masks.delay", lambda task_id: queued.append(task_id) or FakeAsyncResult())
+    monkeypatch.setattr("routers.tasks.publish_task_progress_event", lambda event_task: None)
+
+    response = client.post(f"/api/tasks/{task.id}/retry")
+
+    assert response.status_code == 202
+    body = response.json()
+    assert body["task_type"] == "propagate_masks"
+    assert body["celery_task_id"] == "celery-propagation-retry"
+    assert queued == [body["id"]]
+    assert client.get(f"/api/projects/{project['id']}").json()["status"] == "pending"
+
+
 def test_task_actions_reject_invalid_states(client, db_session):
     project = client.post("/api/projects", json={
         "name": "Done",