free-short-video 7.0.2 → 7.0.3

package/README.md

@@ -1,23 +1,26 @@
 ---
 
-# What's New in v7.0.2
+# What's New in v7.0.3
 
 ## What's New
 
 ### Features & Improvements
 
-* **Clearer key/domain setup to prevent `401`.** The API Key panel now states, per source, that keys added in the web UI can be bound to their own domain (and are covered by *Auto-detect domains*), while `.env` / environment-variable keys always follow the single **global default domain** and cannot be bound individually. Each `.env` key now shows a neutral "follows global domain" badge with the resolved endpoint. A new **multi-key** note explains that a single mismatched or expired key makes tasks intermittently fail with `401` whenever that key is picked. Getting Started and the FAQ gained a "match the key to the right site" section, and `.env.example` now spells out the `.env`-key behavior — so single-site users set the domain and mixed-site users move keys into the web config page.
-* **True 16:9 landscape.** Landscape (16:9) video now renders at the correct aspect ratio, and the portrait / large-landscape resolution option labels were fixed so the listed size matches what is actually generated.
-* **Refreshed language switcher.** The native browser language dropdown was replaced with a site-styled language switcher, consistent with the rest of the UI across all 22 locales.
+* **Survive Agnes queue saturation.** When Agnes rejects submissions with `503 video_queue_full` (the free Video 2.5 Flash queue can stay full for 10+ minutes), the app now retries on a dedicated track — every 30–60s for up to 900s (`AGNES_VIDEO_QUEUE_RETRY_SECONDS`) — without consuming the normal retry budget, so you no longer get a premature "generation failed" while you were simply never queued. Nothing is consumed by a rejected submit. The progress panel shows it live: `Agnes 视频队列已满（HTTP 503 · video_queue_full），正在排队重试（第 N 次 / 已等 X 分钟）。建议错峰重试或稍后再试。`
+* **Honest error messages.** Upstream failures now surface the real reason instead of a generic `HTTP 503: server error` or a raw dict dump: the submitted error's `code` and `message` are kept end-to-end (e.g. `ComfyUI internal error: inference not finished after 15 minutes (code=500)`), so "queue full" and "queued but stuck" are no longer indistinguishable. `error_logs/` stores readable text plus the upstream code.
+* **Queue notices in your language (all 22 locales).** Queue-full progress and failure notices are now rendered by the frontend from structured i18n keys, so Japanese, Arabic, Russian, etc. users see their own language instead of a Chinese fallback. The raw upstream error (HTTP status, `video_queue_full`) is quoted untranslated, as it comes from the API.
+* **Config panels start collapsed.** All four configuration cards (provider management, model selection, workspace, privacy) now start collapsed instead of expanded; your manual expand/collapse preference is still remembered per browser.
+* **Know when a model is not adapted.** Video models that appear in the upstream model list but have no capability entry in your installed version are now marked with `⚠` plus an explicit notice, instead of being silently submitted with the old v2.0 pixel protocol. The app version is shown in the page footer and returned by `GET /api/models`.
 
 ### Bug Fixes
 
-* Fixed the config page recommending "bind a matching domain for each key" on `.env`-sourced keys, which have no domain dropdown and cannot be bound — the misleading hint that repeatedly sent users down the wrong path when chasing `401` errors. The *Auto-detect domains* tooltip now correctly states it only probes web-UI keys.
-* Corrected the Docker/compose image reference to the real flat GHCR namespace, so documented pull commands actually resolve.
+* **Switching the text model provider back to Agnes now works.** Previously the switch only changed the UI: the backend kept the previously selected third-party provider and kept calling its endpoint (an empty value was dropped by the form layer and treated as "no change"). The selection is now sent explicitly, and it persists when you click **Save**.
+* **Frontend no longer breaks after an update.** The app entry page is now served with `Cache-Control: no-cache`, so browsers can no longer keep a stale entry page that references deleted build assets — the "task list (or the whole app) silently stopped working after pulling a new version" failure mode is gone. After upgrading, do one hard refresh (`Cmd/Ctrl+Shift+R`); afterwards updates apply on normal reload.
+* Fixed the queue-full messaging to name Agnes, quote the raw upstream error, and include an actionable suggestion (retry off-peak), instead of the vague "upstream video queue is full".
 
 ---
 
-No action is required after upgrading. If you were hitting `401`, re-check your key against its site in the API Key panel or run *Auto-detect domains*.
+No action is required after upgrading. If your tasks sit at 0% for a long time, that is the Agnes free queue — the app now retries and tells you so; off-peak retries or switching to Video 2.0 (separate queue) remain the practical workarounds.
 
 ---
 

package/core/api/agnes_video.py

@@ -6,6 +6,8 @@ import json
 import logging
 import mimetypes
 import os
+import random
+import subprocess
 import time
 from typing import List, Optional
 
@@ -49,6 +51,105 @@ def _adaptive_poll_interval(interval: int, poll_count: int) -> int:
     return min(interval, 20 + (poll_count // 5) * 5)
 
 
+# ── v7.0 上游可靠性加固（docs/plans/v7.0/upstream_error_handling_plan.md）──
+
+# 提交侧「队列类」瞬时错误的 body code（U1）：走独立退避轨道，不消耗普通 5xx
+# 的重试配额。实测 video_queue_full 可持续 12 分钟以上（连续 25 次被拒），
+# 而普通 5xx 退避（5 次 × 30s 递增）约 5.5 分钟就会放弃。
+_QUEUE_FULL_CODES = {"video_queue_full", "fail_to_fetch_task"}
+
+# 队列满退避间隔（秒）：固定基数 + 随机抖动（模块级常量，便于测试缩小）
+_QUEUE_RETRY_BASE_DELAY = 30.0
+_QUEUE_RETRY_JITTER = 30.0
+
+
+def _upstream_error(body) -> tuple:
+    """U2：从上游响应体统一提取 ``(code, message)``。
+
+    兼容两种输入：已解析的 dict（轮询结果）或 ``requests.Response``（提交响应）。
+
+    - 提交侧 5xx：body 形如 ``{"code": "video_queue_full", "message": "..."}``
+    - 轮询侧 ``status=failed``：``error`` 字段是对象 ``{"code", "message"}``
+
+    提取失败返回 ``("", "")``，由调用方回退到通用文案。
+    """
+    data = body
+    if body is not None and hasattr(body, "json"):
+        try:
+            data = body.json()
+        except Exception:
+            return "", (getattr(body, "text", "") or "").strip()[:200]
+    if isinstance(data, dict):
+        code = str(data.get("code") or "")
+        message = str(data.get("message") or "")
+        err = data.get("error")
+        if isinstance(err, dict):
+            code = code or str(err.get("code") or "")
+            if not message:
+                message = str(err.get("message") or "")
+        return code, message
+    if data is None:
+        return "", ""
+    return "", str(data)[:200]
+
+
+def _needs_portrait_rotation_fix(perf_w, perf_h, cont_w, cont_h) -> bool:
+    """U3：判定 2.5 系列「容器竖、像素横」的竖屏躺倒缺陷签名。
+
+    低代价代理判定（docs/dev/agnes_video_upstream_behavior.md §5.2）：
+    推理内部尺寸（``perf_params``）为横屏而产物容器为竖屏 → 命中。
+    任一尺寸缺失 / 方向一致 → 不命中（保守：宁可漏判，不可误转）。
+    """
+    try:
+        pw, ph, cw, ch = int(perf_w), int(perf_h), int(cont_w), int(cont_h)
+    except (TypeError, ValueError):
+        return False
+    if pw <= 0 or ph <= 0 or cw <= 0 or ch <= 0:
+        return False
+    return pw > ph and ch > cw
+
+
+def _probe_video_size(path: str) -> tuple:
+    """ffprobe 读取视频容器宽高（U3 判定用；失败返回 ``(None, None)``）。"""
+    try:
+        from core.compositor.ffmpeg_tool import resolve_binary
+        ffprobe = resolve_binary("ffprobe")
+        if not ffprobe:
+            return None, None
+        result = subprocess.run(
+            [ffprobe, "-v", "error", "-select_streams", "v:0",
+             "-show_entries", "stream=width,height", "-of", "json", path],
+            capture_output=True, text=True, timeout=60,
+        )
+        streams = json.loads(result.stdout).get("streams") or []
+        if streams:
+            return streams[0].get("width"), streams[0].get("height")
+    except Exception as e:
+        logger.debug(f"[UpstreamRotate] ffprobe failed: {e}")
+    return None, None
+
+
+class AgnesQueueFullError(RuntimeError):
+    """U1（v7.0）：队列类 503 在预算内始终没排进队——**未产生任务、未消耗配额**。
+
+    消息体只放技术事实（日志/traceback 用）；用户可见文案交给 UI 层：
+    - 前端：按 ``i18n key = error.video.queue_full`` + 参数用 22 语言渲染；
+    - 后端兜底：``core.i18n_backend`` 的 zh/en（``utils.network.describe_queue_full_error``）。
+
+    注意：``is_remote_video_failure`` 对本类返回 False（提交阶段就被拒，
+    video_id 都不存在，自然不需要「服务端确认失败才丢弃 video_id」的判定）。
+    """
+
+    def __init__(self, status: int, code: str, waited_s: int):
+        super().__init__(
+            f"Agnes video queue full (HTTP {status} · {code}) after {waited_s}s "
+            f"of retrying; no job was created"
+        )
+        self.queue_full_status = status
+        self.queue_full_code = code
+        self.queue_full_waited_s = waited_s
+
+
 class VideoTaskCancelled(RuntimeError):
     """用户停止任务导致的取消（优化路线图 0.2）。
 
@@ -88,10 +189,16 @@ def _write_json_cache(path: str, data: dict) -> None:
 
 
 class VideoOutput:
-    def __init__(self, fmt: str, ext: str, data: str):
+    def __init__(self, fmt: str, ext: str, data: str,
+                 perf_params: Optional[dict] = None,
+                 fix_rotation: bool = False):
         self.fmt = fmt
         self.ext = ext
         self.data = data
+        # U3：perf_params 为上游推理内部尺寸（非产物尺寸，勿用于产物校验）；
+        # fix_rotation 开启时保存后探测「容器竖、像素横」签名并做方向校正
+        self.perf_params = perf_params or {}
+        self.fix_rotation = fix_rotation
 
     async def save(self, path: str) -> None:
         """保存视频到 path（异步）。
@@ -108,6 +215,62 @@ class VideoOutput:
         else:
             with open(path, "wb") as f:
                 f.write(self.data if isinstance(self.data, bytes) else self.data.encode())
+        if self.fix_rotation:
+            self._maybe_fix_rotation(path)
+
+    def _maybe_fix_rotation(self, path: str) -> None:
+        """U3：2.5 系列竖屏（9:16）上游躺倒缺陷的探测式校正（默认关闭）。
+
+        判定签名见 ``_needs_portrait_rotation_fix``（容器竖 + 推理内部横）；
+        校正 = ffmpeg ``transpose=2``（逆时针 90°，实测可还原正确构图）。
+        任何一步失败保留原片并告警，不影响主流程。
+        开关：``AGNES_FIX_V25_PORTRAIT_ROTATION``（默认关闭，见计划 §三）。
+        """
+        perf = self.perf_params or {}
+        perf_w, perf_h = perf.get("width"), perf.get("height")
+        if perf_w is None or perf_h is None:
+            return
+        try:
+            cont_w, cont_h = _probe_video_size(path)
+            if not _needs_portrait_rotation_fix(perf_w, perf_h, cont_w, cont_h):
+                return
+            from core.compositor.ffmpeg_tool import resolve_binary
+            ffmpeg = resolve_binary("ffmpeg")
+            if not ffmpeg:
+                logger.warning("[UpstreamRotate] ffmpeg unavailable, keep original video")
+                return
+            tmp_path = path + ".rotated.mp4"
+            cmd = [
+                ffmpeg, "-y", "-i", path,
+                "-vf", "transpose=2",
+                "-c:v", "libx264", "-crf", "18", "-preset", "fast",
+                "-c:a", "copy",
+                tmp_path,
+            ]
+            result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+            if result.returncode != 0:
+                logger.warning(
+                    f"[UpstreamRotate] ffmpeg failed (rc={result.returncode}): "
+                    f"{result.stderr[:300]}"
+                )
+                _silent_remove(tmp_path)
+                return
+            os.replace(tmp_path, path)
+            logger.info(
+                f"[UpstreamRotate] Fixed portrait rotation: perf={perf_w}x{perf_h} "
+                f"container={cont_w}x{cont_h} -> transposed {os.path.basename(path)}"
+            )
+        except Exception as e:
+            logger.warning(f"[UpstreamRotate] rotation fix skipped: {e}")
+
+
+def _silent_remove(path: str) -> None:
+    """尽力删除临时文件（失败静默，供 U3 校正失败清理）。"""
+    try:
+        if os.path.exists(path):
+            os.remove(path)
+    except OSError:
+        pass
 
 
 class AgnesVideoAPI:
@@ -351,6 +514,9 @@ class AgnesVideoAPI:
                 resp.raise_for_status()
                 result = resp.json()
                 status = result.get("status", "")
+                # U5：progress 与 internal_progress 实测互相矛盾（可 0 vs 100）、
+                # started_at 可为 null——仅作日志展示，任何逻辑不得依赖其数值
+                # （自适应间隔 _adaptive_poll_interval 也只按次数推进）。
                 progress = result.get("progress", 0)
                 poll_count += 1
                 consecutive_failures = 0  # reset on success
@@ -366,15 +532,23 @@ class AgnesVideoAPI:
                     return result
 
                 if status in ("failed", "FAILED"):
-                    err = result.get("error") or "unknown error"
-                    error_msg = f"Video generation failed: {err}"
+                    # U2：error 是对象 {code, message}，统一提取而非字面量化
+                    code, message = _upstream_error(result)
+                    if not message:
+                        message = str(result.get("error") or "unknown error")
+                    error_msg = f"Video generation failed: {message}"
+                    if code:
+                        error_msg += f" (code={code})"
                     collect_error(
                         "video", "poll_task",
                         prompt=curl_cmd,
                         error_type="VideoFailed",
-                        error_message=error_msg,
+                        error_message=message,
                         response_body=resp.text,
-                        extra={"video_id": video_id[:16], "status": status},
+                        extra={
+                            "video_id": video_id[:16], "status": status,
+                            "upstream_code": code,
+                        },
                     )
                     raise RuntimeError(error_msg)
             except (requests.exceptions.RequestException, asyncio.TimeoutError) as e:
@@ -405,12 +579,18 @@ class AgnesVideoAPI:
             # 优化路线图 1.3：自适应轮询间隔（20s 起步，每 5 次 +5s，上限 interval）
             await asyncio.sleep(_adaptive_poll_interval(interval, poll_count))
 
-    async def _submit_with_retry(self, payload: dict, mode_desc: str) -> str:
+    async def _submit_with_retry(self, payload: dict, mode_desc: str,
+                                 progress_callback=None) -> str:
         frame_reductions_left = 2  # allow up to 2 frame-count reductions on 400
         attempt = 0
         rotations = 0
         ring = get_key_ring()
         max_rotations = len(ring) * self.max_retries
+        # U1：队列类 503（video_queue_full / fail_to_fetch_task）独立退避轨道
+        # —— 不计入普通 5xx 的 max_retries 配额，预算单独可配
+        queue_started = None   # 首次命中时的时间戳（time.monotonic）
+        queue_deadline = None  # queue_started + 预算秒数
+        queue_retries = 0
         while attempt < self.max_retries:
             if self.shutdown_event and self.shutdown_event.is_set():
                 raise VideoTaskCancelled("Video generation cancelled by user")
@@ -468,20 +648,100 @@ class AgnesVideoAPI:
                     continue
 
                 if resp.status_code >= 500:
+                    # U2：解析响应体的 code/message（此前统一丢成 "server error"）
+                    code, message = _upstream_error(resp)
+
+                    # U1：队列满走独立退避轨道（不计入普通 5xx 配额）
+                    if code in _QUEUE_FULL_CODES:
+                        if queue_deadline is None:
+                            from core.config import get_settings
+                            budget = get_settings().agnes_video_queue_retry_seconds
+                            queue_started = time.monotonic()
+                            queue_deadline = queue_started + budget
+                            logger.warning(
+                                f"[AgnesVideo] {mode_desc}: Agnes video queue full "
+                                f"(HTTP {resp.status_code} · {code}), entering queue "
+                                f"retry track (budget {budget}s)"
+                            )
+                        waited = time.monotonic() - queue_started
+                        if time.monotonic() >= queue_deadline:
+                            collect_error(
+                                "video", "submit_video",
+                                prompt=payload.get("prompt", ""),
+                                error_type=f"QueueFull_{code}",
+                                error_message=message or f"HTTP {resp.status_code}: {code}",
+                                status_code=resp.status_code,
+                                response_body=resp.text,
+                                retry_count=queue_retries,
+                                extra={
+                                    "mode": mode_desc, "upstream_code": code,
+                                    "waited_s": int(waited),
+                                },
+                            )
+                            # 结构化异常：用户可见文案由 UI 层按 22 语言渲染，
+                            # 此处只保留技术事实（含 HTTP 码 / body code / 等待时长）
+                            raise AgnesQueueFullError(
+                                status=resp.status_code, code=code, waited_s=int(waited),
+                            )
+                        delay = _QUEUE_RETRY_BASE_DELAY + random.uniform(0, _QUEUE_RETRY_JITTER)
+                        queue_retries += 1
+                        logger.warning(
+                            f"[AgnesVideo] Agnes video queue full on {mode_desc} "
+                            f"(HTTP {resp.status_code} · {code}), queue retry "
+                            f"#{queue_retries} (waited {waited:.0f}s) in {delay:.0f}s..."
+                        )
+                        collect_error(
+                            "video", "submit_video",
+                            prompt=payload.get("prompt", ""),
+                            error_type=f"QueueFull_{code}",
+                            error_message=message or f"HTTP {resp.status_code}: {code}",
+                            status_code=resp.status_code,
+                            response_body=resp.text,
+                            retry_count=queue_retries,
+                            extra={
+                                "mode": mode_desc, "upstream_code": code,
+                                "waited_s": int(waited),
+                            },
+                        )
+                        if progress_callback:
+                            try:
+                                # (stage, payload)：payload 带原样报错（HTTP 码 + body code）
+                                # 与等待信息，供前端拼出「Agnes 队列已满 + 原始报错 + 错峰建议」
+                                progress_callback("queue_full", {
+                                    "attempt": queue_retries,
+                                    "waited_s": waited,
+                                    "status": resp.status_code,
+                                    "code": code,
+                                    "message": message,
+                                })
+                            except Exception:
+                                logger.debug(
+                                    "[AgnesVideo] queue progress callback failed",
+                                    exc_info=True,
+                                )
+                        await asyncio.sleep(delay)
+                        continue
+
+                    # 普通 5xx：沿用 5 次退避配额
                     delay = self.retry_base_delay * (attempt + 1)
                     logger.warning(
-                        f"[AgnesVideo] {resp.status_code} server error on {mode_desc}, "
+                        f"[AgnesVideo] {resp.status_code} server error on {mode_desc}"
+                        f"{f' (code={code})' if code else ''}, "
                         f"retry {attempt + 1}/{self.max_retries} in {delay:.0f}s..."
                     )
+                    error_message = (
+                        f"HTTP {resp.status_code}: {message}"
+                        if message else f"HTTP {resp.status_code}: server error"
+                    )
                     collect_error(
                         "video", "submit_video",
                         prompt=payload.get("prompt", ""),
                         error_type=f"HTTP{resp.status_code}",
-                        error_message=f"HTTP {resp.status_code}: server error",
+                        error_message=error_message,
                         status_code=resp.status_code,
                         response_body=resp.text,
                         retry_count=attempt + 1,
-                        extra={"mode": mode_desc},
+                        extra={"mode": mode_desc, "upstream_code": code},
                     )
                     await asyncio.sleep(delay)
                     attempt += 1
@@ -578,6 +838,7 @@ class AgnesVideoAPI:
             height=height,
             seed=seed,
             negative_prompt=negative_prompt,
+            progress_callback=progress_callback,
             **kwargs,
         )
         return await self.wait_for_video(video_id, progress_callback)
@@ -591,6 +852,7 @@ class AgnesVideoAPI:
         height: int = 720,
         seed: Optional[int] = None,
         negative_prompt: Optional[str] = None,
+        progress_callback=None,
         **kwargs,
     ) -> str:
         # 2.5 系列模型（v6.2）：新参数协议（mode/seconds/size/aspect_ratio）
@@ -602,6 +864,7 @@ class AgnesVideoAPI:
                 width=width,
                 height=height,
                 seed=seed,
+                progress_callback=progress_callback,
                 **kwargs,
             )
         num_frames, frame_rate = self._get_frame_config(duration, width, height)
@@ -643,7 +906,7 @@ class AgnesVideoAPI:
 
         logger.info(f"[AgnesVideo] {mode_desc}: {prompt[:80]}...")
 
-        video_id = await self._submit_with_retry(payload, mode_desc)
+        video_id = await self._submit_with_retry(payload, mode_desc, progress_callback)
         logger.info(f"[AgnesVideo] Video submitted: {video_id[:20]}...")
         return video_id
 
@@ -665,6 +928,7 @@ class AgnesVideoAPI:
         width: int = 1280,
         height: int = 720,
         seed: Optional[int] = None,
+        progress_callback=None,
         **kwargs,
     ) -> str:
         """2.5 / 2.5-flash 新协议提交：mode / seconds / size / aspect_ratio。
@@ -717,14 +981,15 @@ class AgnesVideoAPI:
             mode_desc = "text-to-video"
 
         logger.info(f"[AgnesVideo] {mode_desc}: {prompt[:80]}...")
-        video_id = await self._submit_with_retry(payload, mode_desc)
+        video_id = await self._submit_with_retry(payload, mode_desc, progress_callback)
         logger.info(f"[AgnesVideo] Video submitted: {video_id[:20]}...")
         return video_id
 
     async def wait_for_video(self, video_id: str, progress_callback=None) -> VideoOutput:
         # 1.2：轮询总超时可经 AGNES_VIDEO_POLL_TIMEOUT 配置（3.5 RuntimeSettings 收敛）
         from core.config import get_settings
-        poll_timeout = get_settings().agnes_video_poll_timeout
+        settings = get_settings()
+        poll_timeout = settings.agnes_video_poll_timeout
         final = await self._poll_task(
             video_id, progress_callback=progress_callback,
             max_poll_duration=poll_timeout,
@@ -743,4 +1008,14 @@ class AgnesVideoAPI:
                 raise RuntimeError(f"Agnes video: no URL in completed task: {final}")
 
         logger.info(f"[AgnesVideo] Done: {video_url[:80]}...")
-        return VideoOutput(fmt="url", ext="mp4", data=video_url)
+        # U3：携带推理内部尺寸 + 校正开关（默认关闭；仅 2.5 系列探测「容器竖、
+        # 像素横」签名后 ffmpeg transpose=2 校正，详见计划 §三）
+        fix_rotation = (
+            settings.agnes_fix_v25_portrait_rotation
+            and is_v25_video_model(self.model)
+        )
+        return VideoOutput(
+            fmt="url", ext="mp4", data=video_url,
+            perf_params=final.get("perf_params") or {},
+            fix_rotation=fix_rotation,
+        )

package/core/config.py

@@ -18,7 +18,7 @@ CONFIG_FILE = os.path.join(CONFIG_DIR, "config.json")
 # ═══════════════════════════════════════════════════
 # 应用版本号（v6.1 新增：发版时同步更新，见 docs/dev/release_process.md）
 # ═══════════════════════════════════════════════════
-APP_VERSION = "7.0.2"
+APP_VERSION = "7.0.3"
 
 # 未配置 API Key 时的统一报错文案（含免费获取与在线体验兜底，全站路由共用）
 #
@@ -252,6 +252,13 @@ try:
         agnes_subtitle_ass: bool = True          # 2.1c 字幕 ASS 单链灰度开关
         agnes_video_poll_timeout: int = 1800     # 1.2 视频轮询总超时
         agnes_chat_timeout: int = 300            # stability_hardening P1：chat 单次读超时（默认与 chat_multimodal 对齐）
+        # v7.0 U1：队列类 503（video_queue_full）独立重试预算（秒）。
+        # 实测队列饱和可持续 12 分钟以上，普通 5xx 退避（~5.5 分钟）会在排进队
+        # 前放弃；此轨道不计入普通配额，默认 900s。
+        agnes_video_queue_retry_seconds: int = 900
+        # v7.0 U3：2.5 系列竖屏（9:16）上游躺倒缺陷的探测式校正开关。
+        # 默认关闭——待真实竖屏任务验证后再定默认值（计划 §三建议路径）。
+        agnes_fix_v25_portrait_rotation: bool = False
 
         # ── CORS（PR #33 吸收 Phase 2：可配置跨源白名单）──
         # 供独立本地伴侣工具（如 agnes-simple-ui）从浏览器跨源调用本服务 API。
@@ -294,6 +301,12 @@ except ImportError:  # pragma: no cover - pydantic-settings 为必备依赖，
             )
             self.agnes_video_poll_timeout = int(os.environ.get("AGNES_VIDEO_POLL_TIMEOUT", "1800"))
             self.agnes_chat_timeout = int(os.environ.get("AGNES_CHAT_TIMEOUT", "300"))
+            self.agnes_video_queue_retry_seconds = int(
+                os.environ.get("AGNES_VIDEO_QUEUE_RETRY_SECONDS", "900")
+            )
+            self.agnes_fix_v25_portrait_rotation = os.environ.get(
+                "AGNES_FIX_V25_PORTRAIT_ROTATION", "0"
+            ).strip().lower() in ("1", "true", "on")
             self.agnes_cors_origins = os.environ.get("AGNES_CORS_ORIGINS", "")
             _cors_enabled = os.environ.get("AGNES_CORS_ENABLED", "").strip().lower()
             if _cors_enabled in ("0", "false", "off"):
@@ -1169,8 +1182,8 @@ VIDEO_MODEL_CAPABILITIES = {
         "max_ref_images": None,  # 不限
         "supports_ref_video": False,
         "desc": {
-            "zh": "免费旧版。支持任意像素分辨率、最长约 17 秒、多参考图关键帧；有负面提示词。",
-            "en": "Free legacy model. Arbitrary pixel resolution, up to ~17s, multi-image keyframes; supports negative prompt.",
+            "zh": "免费旧版。支持任意像素分辨率、最长约 17 秒、多参考图关键帧；有负面提示词。输出分辨率由上游按标准档归一（标准档保真，非标准档会被吸附）。",
+            "en": "Free legacy model. Arbitrary pixel resolution, up to ~17s, multi-image keyframes; supports negative prompt. Output resolution is normalized by upstream to standard tiers.",
         },
     },
     "agnes-video-2.5": {  # 付费模型
@@ -1218,8 +1231,8 @@ VIDEO_MODEL_CAPABILITIES = {
         "max_ref_images": 5,
         "supports_ref_video": False,
         "desc": {
-            "zh": "免费新版（限时免费）。固定 720P、4–12 秒、图片参考最多 5 张；不支持负面提示词与参考视频。",
-            "en": "Free new model (limited time). Fixed 720P, 4–12s, up to 5 ref images; no negative prompt or ref video.",
+            "zh": "免费新版（限时免费）。固定 720P、4–12 秒、图片参考最多 5 张；不支持负面提示词与参考视频。比例保真、绝对像素由上游按标准档归一（如 3:4 实际输出 834x1112）。",
+            "en": "Free new model (limited time). Fixed 720P, 4–12s, up to 5 ref images; no negative prompt or ref video. Aspect ratio preserved; absolute pixels normalized by upstream (e.g. 3:4 renders at 834x1112).",
         },
     },
 }

package/core/i18n_backend.py

@@ -380,6 +380,19 @@ CATALOG: Dict[str, Dict[str, str]] = {
         "zh": "等待视频生成 {vid}...",
         "en": "Waiting for video generation {vid}...",
     },
+    # U1（v7.0）：点名 Agnes + 原样报错（HTTP 码 / body code）+ 错峰重试建议。
+    # 参数：n 重试次序、waited 已等分钟、status HTTP 状态码、code 上游 body code
+    # 说明：这里是**后端兜底**（zh/en 双基线）；前端命中同名 key 时用前端
+    # 22 语言文案渲染，见 models/task.py 的 current_message_key。
+    "progress.video.queue_full": {
+        "zh": "Agnes 视频队列已满（HTTP {status} · {code}），正在排队重试（第 {n} 次 / 已等 {waited} 分钟）。建议错峰重试或稍后再试。",
+        "en": "Agnes video queue is full (HTTP {status} · {code}), retrying (attempt {n} / waited {waited} min). Please retry later, ideally off-peak.",
+    },
+    # 队列重试预算耗尽（未产生任务、未消耗配额）：同样点名 Agnes + 原样报错 + 可行动作
+    "error.video.queue_full": {
+        "zh": "Agnes 视频队列已满（HTTP {status} · {code}），重试 {waited} 分钟后仍未排进队，本次未生成任务（不消耗配额）。建议错峰重试或换用其他视频模型。",
+        "en": "Agnes video queue is full (HTTP {status} · {code}); after retrying for {waited} min the job still never entered the queue, so nothing was generated (no quota used). Please retry later, ideally off-peak, or switch to another video model.",
+    },
     "progress.simple.completed": {
         "zh": "视频生成完成",
         "en": "Video generation complete",

package/core/pipelines/__init__.py

@@ -217,6 +217,8 @@ class BasePipeline(ABC):
         data: dict = None,
         *,
         preserve_step: bool = False,
+        message_key: str = None,
+        message_params: dict = None,
     ):
         """更新进度并持久化到 state（轮询模式）。
 
@@ -226,13 +228,18 @@ class BasePipeline(ABC):
         Args:
             step: 步骤 key，写入 ``current_step`` 供前端与诊断报告定位环节。
             status: 步骤状态（running / completed / failed / awaiting_user）。
-            message: 面向用户的进度文案。
+            message: 面向用户的进度文案（后端按 ui_language 译好的兜底句）。
             progress: 进度比例 0.0 ~ 1.0。
             data: 附带数据（仅回调透传，不落盘）。
             preserve_step: True 时**不覆盖** ``current_step``，用于 ``error``
                 这类终态事件——它们表达的是「出了问题」而不是「在哪个环节」，
                 覆盖会把真实失败环节冲掉，使诊断报告归因失真（issue #56/#57
                 真实失败在视频下载，报告却显示 scene_config）。
+            message_key: 可选。结构化消息的 i18n key（如
+                ``"progress.video.queue_full"``），与 ``message_params`` 一并
+                落盘，供前端用其 22 语言文案渲染；省略时清空这两个字段，
+                避免上一次的结构化消息残留（旧前端仍读 ``current_message``）。
+            message_params: ``message_key`` 的插值参数（如 ``{"n": 3}``）。
 
         落盘策略（2.4 节流 + v6.4.8 终态强制）：
         - ``status == "running"`` 的高频进度更新按 0.5s 阈值合并落盘；
@@ -246,6 +253,8 @@ class BasePipeline(ABC):
             self._state.current_status = status
             self._state.current_progress = progress
             self._state.current_message = message
+            self._state.current_message_key = message_key or ""
+            self._state.current_message_params = dict(message_params or {})
             # 2.4：进度写盘节流——进度类字段高频更新时合并落盘（0.5s 阈值）。
             # 关键状态（video_id / scenes / paragraphs 等）不经本路径，不受影响。
             force_save = status != "running"
@@ -258,6 +267,8 @@ class BasePipeline(ABC):
                         "current_status": status,
                         "current_progress": progress,
                         "current_message": message,
+                        "current_message_key": message_key or "",
+                        "current_message_params": dict(message_params or {}),
                     }
                     if not preserve_step:
                         fields["current_step"] = step
@@ -377,6 +388,46 @@ class BasePipeline(ABC):
         """``translate(key, self._ui_lang(), **params)`` 的快捷方式。"""
         return translate(key, self._ui_lang(), **params)
 
+    def _submit_progress_callback(self, step: str, progress: float):
+        """U1（v7.0）：提交侧进度回调，供 ``AgnesVideoAPI.submit_video`` 使用。
+
+        队列类 503（``video_queue_full``）命中独立重试轨道时，经此回调把
+        「Agnes 视频队列已满 + 原样报错 + 错峰建议」实时推给前端（任务状态轮询读取）。
+        回调为同步函数（API 层在重试循环内直接调用），内部调度异步 ``_emit``。
+
+        Args（回调载荷 dict）：``attempt`` 重试次序、``waited_s`` 已等秒数、
+        ``status`` HTTP 状态码、``code`` 上游 body code、``message`` 上游原始文案。
+        """
+        def _cb(stage: str, data: dict) -> None:
+            if stage != "queue_full":
+                return
+            info = data or {}
+            waited = float(info.get("waited_s") or 0)
+            params = {
+                "n": int(info.get("attempt") or 1),
+                "waited": max(1, round(waited / 60)),
+                "status": info.get("status") or "",
+                "code": info.get("code") or "",
+            }
+            try:
+                asyncio.get_running_loop().create_task(self._emit(
+                    step, "running",
+                    # 兜底句仍按任务语言渲染（旧前端 / 前端未覆盖该 key 时使用）
+                    self._t("progress.video.queue_full", **params),
+                    progress,
+                    # 结构化 key + 参数：前端命中后用自己的 22 语言文案渲染
+                    message_key="progress.video.queue_full",
+                    message_params=params,
+                ))
+            except RuntimeError:
+                # 无运行中事件循环（理论不可达）：降级日志
+                logger.warning(
+                    f"[Pipeline] Agnes video queue full (HTTP {info.get('status')} · "
+                    f"{info.get('code')}), queue retry #{info.get('attempt')} "
+                    f"(waited {waited:.0f}s)"
+                )
+        return _cb
+
     @abstractmethod
     async def run(self, state: BaseTaskState) -> str:
         """执行流水线，返回最终视频路径。"""

package/core/pipelines/anchor_video.py

@@ -239,6 +239,8 @@ class AnchorPipeline(MultiScenePipeline):
                 duration=5,
                 width=vw,
                 height=vh,
+                # U1（v7.0）：队列满时实时向前端推「排队重试中」
+                progress_callback=self._submit_progress_callback("video_gen", 0.40),
             )
             self._save_task_json(clip_dir, {"video_id": video_id})