free-short-video 5.7.4 → 6.1.0

package/README.md

@@ -1,15 +1,40 @@
 ---
 
-# What's New in v5.7.4
+# What's New in v6.1.0
 
 ## What's New
 
-### Bug Fixes
+### Retry-First Guidance on Task Failure
 
-- **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.
+The failed-task panel now gives you a clear action path instead of a dead-end error line:
 
----
+- **Retry Task button** — resumes the task from the failed step via the existing checkpoint resume (no new backend endpoint, no full resubmit).
+- **Retry count tracking** — retries are counted per task and persist across refreshes; the count resets when the task succeeds.
+- **Transient-failure copy** — the panel explains that most failures come from temporary rate limiting / network timeouts / model-service fluctuation and are worth retrying before reporting.
+
+### One-Click Issue Feedback with Progressive Expansion
+
+When retries don't help, the feedback area helps you report efficiently:
+
+- **Progressive expansion** — the feedback area stays a low-key hint line under the retry guidance; after **2 failed retries** it auto-expands, switching the copy to "still failing after N retries, please report with diagnostic info." You can open it manually at any time (your choice is remembered per task).
+- **Deterministic-failure pre-screen** — parameter/content errors (HTTP 400, content policy, invalid API key) are detected from the error text, skip the retry guidance, and expand the feedback area directly with a "retrying may not help" hint and a de-emphasized retry button.
+- **Diagnostic info preview** — a collapsible structured report: app version, task type, mode, failed step, error message, retry count, and key generation configs (no prompt text included).
+- **Copy diagnostic info** — one click copies the full report for pasting anywhere.
+- **Check the FAQ first** — a direct link to the official FAQ page for self-service troubleshooting.
+- **Open a GitHub Issue** — jumps to the project issue tracker with title and body pre-filled from the diagnostic report (long bodies are safely truncated); a bug-report issue template is available in the repo.
+
+### Diagnostics Endpoint (Phase 2)
 
+- **`GET /api/tasks/{id}/diagnostics`** — returns a task summary plus the model-call error details associated with that task (exact task match first, time-window fallback), sourced from the existing `error_logs/` collector.
+- **Task-linked error collection** — model errors are now written with their `task_id`, so a failure can be traced back to the exact API calls that caused it.
+- **Privacy by design** — the endpoint never returns prompt text, response bodies, or system prompts; error messages are truncated. The feedback report is fully client-side and **nothing is uploaded automatically**.
+
+### Other Features & Improvements
+
+- **App version in diagnostics** — `APP_VERSION` is now exposed via `GET /api/config`, so every report carries the exact version that failed (kept in sync by the release process).
+- **Official FAQ updated** — new entries explain what to do when generation fails (retry first, then report with diagnostic info) and how to get help / report issues; synced across the official site and wiki.
+
+---
 
 ---
 

package/core/api/error_collector.py

@@ -18,6 +18,7 @@
 import json
 import logging
 import os
+from contextvars import ContextVar
 from datetime import datetime
 from pathlib import Path
 from typing import Optional
@@ -28,6 +29,10 @@ logger = logging.getLogger(__name__)
 
 _WORKSPACE_ROOT: Optional[Path] = None
 
+# v6.1 二期：当前任务 ID 上下文（BasePipeline 执行入口 set，record 时落盘 task_id）。
+# 用 contextvar 而非逐层传参，将改动面收敛到 API 模块内部（PRD FR9）。
+_TASK_ID_CTX: ContextVar[str] = ContextVar("error_collector_task_id", default="")
+
 
 def set_workspace_root(path: str) -> None:
     """设置错误日志存储的根目录（通常为激活的工作空间路径）。
@@ -66,6 +71,15 @@ def _get_log_dir() -> Path:
     return log_dir
 
 
+def set_error_task_id(task_id: str) -> None:
+    """设置当前上下文的 task_id（v6.1 二期，诊断关联用）。
+
+    由流水线执行入口（``web/deps.run_pipeline``）调用，使后续 ``collect_error``
+    落盘时带上 task_id。通过 contextvar 传递，避免逐层向 API 模块传参。
+    """
+    _TASK_ID_CTX.set(task_id or "")
+
+
 def _extract_from_http_error(exc: Exception) -> tuple[Optional[int], str, str]:
     """从 HTTPError 异常中提取状态码、响应体、以及 API 级错误详情。
 
@@ -147,6 +161,8 @@ def collect_error(
         # 限制字段长度，避免日志文件过大
         error_data = {
             "timestamp": now.isoformat(),
+            # v6.1 二期：任务关联（诊断端点精确匹配用；无则留空串）
+            "task_id": _TASK_ID_CTX.get(),
             "model_type": model_type,
             "api_method": api_method,
             "prompt": prompt[:5000] if prompt else "",

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,

package/core/config.py

@@ -15,6 +15,11 @@ logger = logging.getLogger(__name__)
 CONFIG_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), ".agnes_config")
 CONFIG_FILE = os.path.join(CONFIG_DIR, "config.json")
 
+# ═══════════════════════════════════════════════════
+# 应用版本号（v6.1 新增：发版时同步更新，见 docs/dev/release_process.md）
+# ═══════════════════════════════════════════════════
+APP_VERSION = "6.1.0"
+
 # 未配置 API Key 时的统一报错文案（含免费获取与在线体验兜底，全站路由共用）
 API_KEY_MISSING_MSG = (
     "请先配置 API Key。免费获取：https://platform.agnes-ai.com ｜ "