free-short-video 5.7.4 → 6.0.0

package/README.md

@@ -1,15 +1,68 @@
 ---
 
-# What's New in v5.7.4
+# What's New in v6.0.0
 
 ## What's New
 
+### Manual Mode (Human-in-the-Loop Checkpoints)
+
+Manual Mode pauses your pipeline at the checkpoints you choose, so you can confirm, modify, or regenerate each intermediate artifact before continuing — "auto for vibe, manual for precise output."
+
+- **Checkpoint pausing** — the pipeline stops at a checkpoint after the artifacts are produced, waits for your action, and continues from the last confirmed stage.
+- **Fine-grained pause points (creative)** — up to 10 stages: image analysis, story, script & narration, character reference, end-frame prompts, end-frame generation, videos, audio, subtitle, and final composite.
+- **Standard pause points (manuscript / poetry / anchor)** — 6 stages: scenes, references, videos, audio, subtitle, and final.
+- **Pre-filled default pause points** — filled in automatically per task type at creation (editable; unchecked checkpoints pass through automatically).
+- **Not supported** — simple (single-shot) video and simple image tasks only show the artifact list on completion.
+
+### Four Ways to Refine Artifacts
+
+At each paused checkpoint you can pick any of these ways to handle the current artifacts:
+
+- 🤖 **AI-assisted editing** — describe your change (e.g. "make scene 2 more cinematic") and the built-in model rewrites the artifact; review the diff before applying.
+- ✏️ **Edit locally** — copy the artifact path and edit the file directly (JSON / SRT / images / videos), then click "modified, continue".
+- 🤝 **External Agent** — copy a ready-made collaboration prompt and hand the artifact to a more capable local Agent (e.g. opencode / CodeBuddy CLI / ffmpeg / PIL), then fill the result back in.
+- 💻 **Online editing** — edit text artifacts (script / narration / subtitles) in an in-page dialog with side-by-side comparison against the original.
+
+### Artifact-Level Dependency Graph (Rerun Only What Changed)
+
+After any modification, the system computes affected downstream artifacts precisely and reruns only those — the rest are kept untouched:
+
+- Edit narration → reruns audio / subtitle / final only.
+- Edit scene descriptions → reruns reference images / videos / final only.
+- A "before-modification" prompt lists exactly which artifacts will be regenerated vs. retained.
+
+### Switch Between Auto and Manual Anytime
+
+- Switch an **auto** task to manual while running — it pauses at the next safe checkpoint.
+- Switch a **manual** task back to auto while paused — pause points are cleared and it runs straight to completion.
+
+### Other Features & Improvements
+
+- **Dedicated task progress page** — a focused, full-page progress view with step timeline and live status.
+- **Task detail page** — opens in a new tab with official-site links and support guidance.
+- **Project card pinning** — pin a task card to the top of the list; artifact previews auto-expand.
+- **"Continue without changes" button** at every pause point — skip review on any channel.
+- **Bilingual startup scripts** — prompts adapt to the system locale.
+- **Full 22-language i18n** — missing translations completed, plus a new language-completeness checker used as a release regression gate and a language switcher in the task progress header.
+
+### Refactoring & Optimizations
+
+- **Unified checkpoint mechanism across pipelines** — the same MultiScenePipeline checkpoint system now powers creative, manuscript, poetry, and anchor tasks, with per-type artifact matrices.
+- **Standalone artifact dependency graph** — `core/dependency_graph.py` is a pure, declarative edge-table module (product-level + parameter-level) shared by impact prediction, approve handling, and frontend highlighting; fully unit-tested.
+- **Standardized artifact manifests** — per-checkpoint `checkpoint.json` lists and task-directory `MANIFEST.md` make every intermediate artifact discoverable, readable, and refillable.
+- **Resume skips completed scene-building steps** — avoids duplicate LLM calls when Creative / Anchor / Poetry tasks resume.
+
 ### Bug Fixes
 
-- **Blank page after v5.7.3 upgrade fixed** — during the merge of the analytics changes into `master`, git auto-merge treated the new minified JS bundle as a rename of the old one and injected `<<<<<<<<` / `>>>>>>>>` conflict markers into the shipped bundle. Browsers failed to parse the file with `SyntaxError: Unexpected end of input`, leaving a white screen. The production bundle is now restored byte-for-byte from the original build output, and the page renders normally.
+- Fixed an un-clickable "open edit window" button caused by checkpoint artifact field-name mismatch.
+- Fixed multi-PID port-in-use hints so the kill command is emitted as a single copyable line.
+- Progress control-flow fixes — pause UI cleared immediately after resume, and queued/running tasks now show real-time progress messages.
+- Character reference image generation moved into the references stage for correct ordering.
+- Manual-mode UI polish — visible disabled states, artifact filter compatibility, auto-collapse of earlier stages, and resume for inactive unfinished tasks.
 
 ---
 
+**Learn more about Manual Mode:** [Manual Mode Guide](https://video.lichuanyang.top/guides/manual-mode) and the in-repo `docs/public/manual_mode_guide.md`.
 
 ---
 

package/core/artifacts.py

@@ -25,6 +25,7 @@ from models.task import (
     BaseTaskState,
     CreativeVideoTask,
     ManuscriptVideoTask,
+    PoetryVideoTask,
     StepStatus,
 )
 
@@ -115,6 +116,16 @@ _ANCHOR_STEPS_MODEL = [
     ("step_clip_generation", "clip_gen"),
 ]
 
+# Poetry 步骤序列（v6.0 P3：与 multi_scene 模板方法步骤对齐）
+_POETRY_STEPS = [
+    ("step_build_scenes", "build_scenes"),
+    ("step_reference_images", "reference_images"),
+    ("step_video_generation", "video_gen"),
+    ("step_audio", "audio"),
+    ("step_subtitle", "subtitle"),
+    ("step_concatenation", "concatenate"),
+]
+
 
 # ═══════════════════════════════════════════════════════════════
 # 产物定义（每种模式的产物模板）
@@ -183,6 +194,31 @@ def _manuscript_artifact_defs() -> list[dict]:
     ]
 
 
+def _poetry_artifact_defs() -> list[dict]:
+    """Poetry 模式的产物定义模板（v6.0 P3）。
+
+    诗词视频逐场景产物：scene_{i}/video.mp4、scene_{i}/narration.mp3、
+    scene_{i}/subtitle.srt。无参考图阶段（空实现跳过）。
+    """
+    return [
+        # 场景级：视频 / 配音 / 字幕
+        {"type": "video", "step_key": "video_gen", "label": "artVideo",
+         "category": "video", "scope": "scene", "file": "scene_{i}/video.mp4",
+         "scene_fields": ["video_file", "video_id"],
+         "extra_files": ["scene_{i}/task.json", "scene_{i}/curl.sh"]},
+        {"type": "audio", "step_key": "audio", "label": "artAudio",
+         "category": "audio", "scope": "scene", "file": "scene_{i}/narration.mp3",
+         "scene_fields": ["narration_audio"]},
+        {"type": "subtitle", "step_key": "subtitle", "label": "artSubtitle",
+         "category": "subtitle", "scope": "scene", "file": "scene_{i}/subtitle.srt",
+         "scene_fields": ["subtitle_srt"]},
+        # 任务级：成片
+        {"type": "final_video", "step_key": "concatenate", "label": "artFinalVideo",
+         "category": "video", "scope": "task", "file": "final_video.mp4",
+         "fields": ["final_video_file"]},
+    ]
+
+
 def _anchor_artifact_defs(is_model_mode: bool) -> list[dict]:
     """Anchor 模式的产物定义模板。"""
     artifacts = [
@@ -228,6 +264,8 @@ def _get_steps_for_state(state: BaseTaskState) -> list[tuple[Optional[str], str]
         if state.audio_source == "model":
             return _ANCHOR_STEPS_MODEL
         return _ANCHOR_STEPS_POST_STITCH
+    elif isinstance(state, PoetryVideoTask):
+        return _POETRY_STEPS
     return []
 
 
@@ -254,6 +292,8 @@ _SCHEMA_HINTS = {
     "anchor_image": "数字人形象 PNG。可替换后影响数字人视频。",
     "clip_prompts": "数字人视频 prompt JSON（prompts.json）。",
     "clip": "数字人循环视频 MP4。",
+    "narration_audio": "诗词场景朗诵音频 MP3（scene_{i}/narration.mp3）。逐场景修改后重跑该场景字幕与成片。",
+    "subtitle_srt": "诗词场景字幕 SRT（scene_{i}/subtitle.srt）。",
 }
 
 
@@ -270,6 +310,8 @@ def _get_artifact_defs(state: BaseTaskState) -> list[dict]:
         return _manuscript_artifact_defs()
     elif isinstance(state, AnchorVideoTask):
         return _anchor_artifact_defs(state.audio_source == "model")
+    elif isinstance(state, PoetryVideoTask):
+        return _poetry_artifact_defs()
     return []
 
 
@@ -324,6 +366,8 @@ def list_artifacts(state: BaseTaskState, task_dir: str) -> list[ArtifactDescript
         scope_count = len(state.paragraphs)
     elif isinstance(state, AnchorVideoTask):
         scope_count = len(state.paragraphs) if state.paragraphs else 0
+    elif isinstance(state, PoetryVideoTask):
+        scope_count = len(state.scenes)
     else:
         scope_count = 0
 
@@ -611,6 +655,25 @@ def apply_cascade_plan(state: BaseTaskState, plan: CascadePlan) -> dict:
     state.status = StepStatus.PENDING
     update_kwargs["status"] = StepStatus.PENDING
 
+    # 6. v6.1：删除前置环节产物后，重置受影响检查点的"已批准"状态
+    #    级联重置了某检查点对应步骤 → 该检查点不再视为已确认，
+    #    恢复执行时 _maybe_pause 会重新在此暂停等待用户（否则会静默跳过）。
+    mc = getattr(state, "manual_config", None)
+    if mc is not None:
+        approved = list(mc.approved_checkpoints or [])
+        removed: list[str] = []
+        for cp in list(approved):
+            step_field = _checkpoint_to_step_field(cp, state)
+            if step_field and step_field in plan.steps_to_reset:
+                approved.remove(cp)
+                removed.append(cp)
+        if removed:
+            mc.approved_checkpoints = approved
+            update_kwargs["manual_config"] = mc
+            logger.info(
+                "[Artifacts] Cascade reset un-approved checkpoints: %s", removed
+            )
+
     return update_kwargs
 
 
@@ -698,7 +761,177 @@ def sweep_stale_tasks(age_days: int = 7,
 # ═══════════════════════════════════════════════════════════════
 
 # 清单自身文件名（扫描文件树时排除）
-_MANIFEST_FILES = {"manifest.json", "MANIFEST.md", "task_state.json"}
+_MANIFEST_FILES = {"manifest.json", "MANIFEST.md", "task_state.json", "checkpoint.json"}
+
+
+# ═══════════════════════════════════════════════════════════════
+# v6.0 检查点分组（PRD §4.3 产物矩阵）
+# ═══════════════════════════════════════════════════════════════
+
+# 产物 type → 检查点名（与 dependency_graph._TYPE_TO_CHECKPOINT 语义一致）
+# creative：细粒度检查点（每个有产物的环节独立，v6.1）
+_ARTIFACT_TO_CHECKPOINT_FINE: dict[str, str] = {
+    "image_analysis": "image_analysis",
+    "story": "story",
+    "script": "script",
+    "character_ref": "character_ref",
+    "end_frame_prompts": "end_frame_prompts",
+    "end_frame": "end_frame_gen",
+    "video": "videos",
+    "audio": "audio",
+    "subtitle": "subtitle",
+    "final_video": "final",
+}
+# 非 creative（manuscript/poetry/anchor）：粗粒度合并检查点
+_ARTIFACT_TO_CHECKPOINT_COARSE: dict[str, str] = {
+    "story": "scenes",
+    "script": "scenes",
+    "end_frame_prompts": "scenes",
+    "character_ref": "references",
+    "end_frame": "references",
+    "video": "videos",
+    "audio": "audio",
+    "subtitle": "subtitle",
+    "final_video": "final",
+    "scene_prompts": "scenes",
+    "anchor_image": "references",
+    "clip_prompts": "scenes",
+    "clip": "videos",
+}
+
+# 检查点展示顺序（creative 细粒度；其余粗粒度）
+_CHECKPOINT_ORDER_FINE = [
+    "image_analysis", "story", "script", "character_ref",
+    "end_frame_prompts", "end_frame_gen", "videos", "audio", "subtitle", "final",
+]
+_CHECKPOINT_ORDER = ["scenes", "references", "videos", "audio", "subtitle", "final"]
+
+
+def _checkpoint_order_for(state: BaseTaskState) -> list[str]:
+    """按任务类型返回检查点展示顺序。"""
+    if isinstance(state, CreativeVideoTask):
+        return _CHECKPOINT_ORDER_FINE
+    return _CHECKPOINT_ORDER
+
+
+def checkpoint_for_artifact(artifact_id: str, task_type: Optional[str] = None) -> str:
+    """返回产物 id 所属检查点名（未知产物 → "other"）。
+
+    Args:
+        artifact_id: 产物 id（含任务类型前缀，如 ``creative:script``）。
+        task_type: 任务类型（缺省时从产物 id 前缀解析）。
+    """
+    parts = artifact_id.split(":")
+    if len(parts) >= 2:
+        t = task_type or parts[0]
+        mapping = _ARTIFACT_TO_CHECKPOINT_FINE if t == "creative" else _ARTIFACT_TO_CHECKPOINT_COARSE
+        return mapping.get(parts[1], "other")
+    return "other"
+
+
+def build_checkpoint_manifest(state: BaseTaskState, task_dir: str) -> dict:
+    """构建检查点级产物清单（checkpoint.json 数据）。
+
+    按检查点分组展示产物（PRD §4.3 / §4.8），供手动模式检查点等待页
+    与外部 Agent 使用。每组含该检查点的产物列表（复用 manifest 的产物条目）。
+
+    Returns:
+        {
+          "format_version": "1.0",
+          "task_id": ...,
+          "task_type": ...,
+          "current_checkpoint": ...,
+          "checkpoints": {
+              "scenes":  { "artifacts": [ ...产物条目... ], "status": "completed|pending" },
+              "videos":  { "artifacts": [ ... ], "status": ... },
+              ...
+          }
+        }
+    """
+    task_dir = safe_join(get_working_dir(), task_dir)
+    manifest = build_manifest(state, task_dir)
+    order = _checkpoint_order_for(state)
+
+    groups: dict[str, dict] = {cp: {"artifacts": []} for cp in order}
+    for a in manifest.get("artifacts", []):
+        cp = checkpoint_for_artifact(a["artifact_id"], state.task_type.value)
+        if cp in groups:
+            groups[cp]["artifacts"].append(a)
+
+    # 状态：检查点对应的 step 字段状态（复用 step 状态）
+    for cp in order:
+        step_field = _checkpoint_to_step_field(cp, state)
+        status = "pending"
+        if step_field:
+            val = getattr(state, step_field, None)
+            if val is not None:
+                status = val.value
+        groups[cp]["status"] = status
+
+    current = ""
+    manual_cfg = getattr(state, "manual_config", None)
+    if manual_cfg is not None:
+        current = manual_cfg.current_checkpoint or ""
+
+    return {
+        "format_version": "1.0",
+        "task_id": state.task_id,
+        "task_type": state.task_type.value,
+        "current_checkpoint": current,
+        "checkpoints": groups,
+        "files": manifest.get("files", []),
+    }
+
+
+def _checkpoint_to_step_field(checkpoint: str, state: BaseTaskState) -> Optional[str]:
+    """检查点名 → 步骤字段名（按任务类型）。"""
+    if isinstance(state, CreativeVideoTask):
+        mapping = {
+            "image_analysis": "step_image_analysis",
+            "story": "step_story",
+            "script": "step_script",
+            "character_ref": "step_character_ref",
+            "end_frame_prompts": "step_end_frame_prompts",
+            "end_frame_gen": "step_end_frame_generation",
+            "videos": "step_video_generation",
+            "audio": "step_audio",
+            "subtitle": "step_subtitle",
+            "final": "step_concatenation",
+        }
+        return mapping.get(checkpoint)
+    if isinstance(state, ManuscriptVideoTask):
+        mapping = {
+            "scenes": "step_scene_prompts",
+            "videos": "step_video_generation",
+            "audio": "step_audio",
+            "subtitle": "step_subtitle",
+            "final": "step_concatenation",
+        }
+        return mapping.get(checkpoint)
+    if isinstance(state, AnchorVideoTask):
+        mapping = {
+            "scenes": "step_generate_anchor",
+            "references": "step_generate_anchor",
+            "videos": "step_clip_generation",
+            "audio": "step_audio",
+            "subtitle": "step_subtitle",
+            "final": "step_concatenation",
+        }
+        return mapping.get(checkpoint)
+    return None
+
+
+def write_checkpoint_manifest(state: BaseTaskState, task_dir: str) -> str:
+    """将检查点清单落盘为 ``checkpoint.json``，返回路径；失败返回空串。"""
+    try:
+        manifest = build_checkpoint_manifest(state, task_dir)
+        path = os.path.join(task_dir, "checkpoint.json")
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(manifest, f, ensure_ascii=False, indent=2)
+        return path
+    except Exception as e:
+        logger.warning("[Artifacts] failed to write checkpoint.json: %s", e)
+        return ""
 
 
 def _scan_task_files(task_dir: str) -> list[dict]:
@@ -759,11 +992,24 @@ def build_manifest(state: BaseTaskState, task_dir: str) -> dict:
             ),
         })
 
+    # v6.0 手动模式：暴露执行模式与当前检查点（供前端判断暂停态 / 渲染依赖图）
+    manual_cfg = getattr(state, "manual_config", None)
+    current_checkpoint = ""
+    current_mode = "auto"
+    if manual_cfg is not None:
+        current_mode = "manual" if manual_cfg.enabled else "auto"
+        current_checkpoint = manual_cfg.current_checkpoint or ""
+
     return {
         "format_version": "1.0",
         "task_id": state.task_id,
         "task_type": state.task_type.value,
         "task_status": state.status.value if state.status else "pending",
+        "current_mode": current_mode,
+        "current_checkpoint": current_checkpoint,
+        "manual_config": (
+            manual_cfg.model_dump() if manual_cfg is not None else {}
+        ),
         "dir_name": os.path.basename(task_dir.rstrip(os.sep)),
         "working_dir": task_dir,
         "artifacts": artifacts,