free-short-video 7.0.2 → 7.0.4

package/README.md

@@ -1,23 +1,25 @@
 ---
 
-# What's New in v7.0.2
+# What's New in v7.0.4
 
 ## 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.
+* **Upstream API error trends.** Errors that carry an HTTP status code are now aggregated per task — by status code, model type (chat / image / video) and API method — and returned by the task detail API. The frontend reports them anonymously as `api_error` events, and task-failure / creation-failure events now carry the extracted status code as well, so recurring upstream failures (for example `503 video_queue_full`) can be tracked as a trend over time instead of being seen as unrelated single errors. The aggregation lives in memory for the lifetime of the task and is cleared with it; `error_logs/` remains the offline source of truth.
+* **Honest "not ready yet" state while polling.** A transient `404` while waiting for a submitted video is now an expected intermediate state rather than an error. It no longer consumes the consecutive-failure budget and no longer gets flushed into `error_logs`, so the failure panel and the logs stop reporting failures for tasks that were in fact still queued upstream.
+
+### Refactoring & Optimizations
+
+* Regression coverage for the upstream error-handling path: consecutive `404`s followed by a successful completion, and a permanent `404` that correctly falls back to the overall polling timeout.
 
 ### 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.
+* Fixed video tasks failing with a spurious error when the upstream gateway had not made the task record visible yet — a state observed for 420s and even 1100s+ under peak load. The overall polling timeout stays as the final backstop, and it keeps the `video_id` so the task can be resumed rather than reported as a server-confirmed failure.
 
 ---
 
-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 a task still fails, the failure panel now shows the real upstream reason with its HTTP status code, and repeated upstream errors of the same kind become visible as a trend.
 
 ---
 

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:
@@ -298,6 +461,12 @@ class AgnesVideoAPI:
         last_status = ""
         poll_count = 0
         consecutive_failures = 0
+        # U9（v7.0.4）：提交返回的是网关路由键，任务记录入库可见有延迟——
+        # 轮询侧 404 "task not found" 是「任务还没准备好」的中间态而非错误
+        # （实测上游高峰期可见性延迟可从历史 ~20s 劣化到 10min+），单独计数、
+        # 只做周期性 info 日志，不进 error_logs、不消耗连续失败配额；
+        # 最终兜底是循环顶部的 max_poll_duration 整体超时。
+        not_found_count = 0
         start_time = asyncio.get_event_loop().time()
         # 2.5 系列查询需带 model_name（text 模式可省略，但带上更通用）
         model_param = f"&model_name={self.model}" if is_v25_video_model(self.model) else ""
@@ -348,9 +517,24 @@ class AgnesVideoAPI:
                         logger.warning("[KeyRotation] HTTP 429 on poll, 换 Key 立即重试")
                         continue
                     break
+                # U9：404（task not found）= 记录尚未在网关任务库可见，中间态
+                if resp.status_code == 404:
+                    not_found_count += 1
+                    poll_count += 1  # 计入自适应间隔与周期日志的推进
+                    if not_found_count == 1 or not_found_count % 10 == 0:
+                        logger.info(
+                            f"[AgnesVideo] Video {video_id[:16]}... not yet visible "
+                            f"(404 task not found), poll #{not_found_count}, "
+                            f"elapsed {elapsed:.0f}s"
+                        )
+                    await asyncio.sleep(_adaptive_poll_interval(interval, poll_count))
+                    continue
                 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 +550,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 +597,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 +666,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 +856,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 +870,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 +882,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 +924,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 +946,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 +999,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 +1026,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/api/error_collector.py

@@ -33,6 +33,63 @@ _WORKSPACE_ROOT: Optional[Path] = None
 # 用 contextvar 而非逐层传参，将改动面收敛到 API 模块内部（PRD FR9）。
 _TASK_ID_CTX: ContextVar[str] = ContextVar("error_collector_task_id", default="")
 
+# ── GA 埋点：上游接口报错聚合（内存态，按 task_id 分组）──
+# 结构：{task_id: {"{status_code}|{model_type}|{api_method}": {
+#     "status_code": int, "model_type": str, "api_method": str,
+#     "count": int, "first_ts": iso, "last_ts": iso}}}
+#
+# 设计说明：故意**不写入 task_state.json**——流水线持有自己的 TaskManager
+# 缓存实例，每次 update_state 都会拿缓存快照整份覆盖落盘，error_collector
+# 若单独写盘会被下一次流水线落盘冲掉。改为内存聚合 +
+# GET /api/tasks/{id}（web/routes/task_routes.py）读取时合并下发，
+# 前端轮询到新增量即上报 GA `api_error` 事件（503 趋势分析用）。
+# 进程重启后内存聚合清零属预期：前端埋点本身只覆盖"页面开着"的窗口，
+# 完整离线趋势仍以 error_logs/ 落盘文件为准。
+_TASK_ERROR_AGG: dict = {}
+_MAX_AGG_ENTRIES_PER_TASK = 32  # 按维度聚合后条目数上限，防异常状态码刷爆
+
+
+def _bump_upstream_error(task_id: str, status_code: int, model_type: str, api_method: str) -> None:
+    """累加一次带 HTTP 状态码的上游报错（内存聚合，失败静默不影响主流程）。"""
+    try:
+        now = datetime.now().isoformat(timespec="seconds")
+        per_task = _TASK_ERROR_AGG.setdefault(task_id, {})
+        key = f"{status_code}|{model_type}|{api_method}"
+        entry = per_task.get(key)
+        if entry is None:
+            if len(per_task) >= _MAX_AGG_ENTRIES_PER_TASK:
+                logger.warning(
+                    f"[ErrorCollector] Upstream error agg cap "
+                    f"({_MAX_AGG_ENTRIES_PER_TASK}) reached for task {task_id}, dropping"
+                )
+                return
+            per_task[key] = {
+                "status_code": status_code,
+                "model_type": model_type,
+                "api_method": api_method,
+                "count": 1,
+                "first_ts": now,
+                "last_ts": now,
+            }
+        else:
+            entry["count"] += 1
+            entry["last_ts"] = now
+    except Exception as e:
+        logger.debug(f"[ErrorCollector] Failed to bump upstream error agg: {e}")
+
+
+def get_task_upstream_errors(task_id: str) -> list:
+    """返回某任务聚合后的上游报错列表（按首次发生时间排序，供任务详情端点合并下发）。"""
+    per_task = _TASK_ERROR_AGG.get(task_id or "")
+    if not per_task:
+        return []
+    return sorted(per_task.values(), key=lambda e: e.get("first_ts", ""))
+
+
+def clear_task_upstream_errors(task_id: str) -> None:
+    """任务删除时清理对应聚合（防内存缓慢增长）。"""
+    _TASK_ERROR_AGG.pop(task_id or "", None)
+
 
 def set_workspace_root(path: str) -> None:
     """设置错误日志存储的根目录（通常为激活的工作空间路径）。
@@ -198,6 +255,12 @@ def collect_error(
         with open(filepath, "w", encoding="utf-8") as f:
             json.dump(error_data, f, ensure_ascii=False, indent=2)
 
+        # GA 埋点：带 HTTP 状态码的报错同步累加进任务级内存聚合
+        if status_code and error_data["task_id"]:
+            _bump_upstream_error(
+                error_data["task_id"], status_code, model_type, api_method
+            )
+
         # 优化路线图 1.5b：按数量轮转，防止 error_logs 无限膨胀
         _rotate_error_logs(log_dir)
 

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.4"
 
 # 未配置 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",