free-short-video 6.3.0 → 6.4.1

package/.env.example

@@ -77,3 +77,13 @@ PORT=8765
 
 # 提示词语言（zh/en，影响 LLM meta-prompt 语言）
 # PROMPT_LANGUAGE=zh
+
+
+# ── 7. CORS 跨源白名单（可选，供独立本地伴侣工具调用本服务 API）──────────
+# 场景：本地跑一个独立的简化前端（如 agnes-simple-ui，监听 :8787），
+# 从浏览器直接调用本服务的 /api/* 接口。设置后服务仅允许列出的源跨源调用。
+# 默认空 = 不启用 CORS（攻击面不变）；同源页面不受影响。
+# AGNES_CORS_ORIGINS=http://localhost:8787,http://127.0.0.1:3000
+#
+# 显式禁用（即使设置了 origins 也不启用中间件）：
+# AGNES_CORS_ENABLED=false

package/README.md

@@ -1,36 +1,13 @@
 ---
 
-# What's New in v6.3.0
+# What's New in v6.4.1
 
 ## What's New
 
-### Features & Improvements
-
-- **Complete v6 optimization roadmap (29/29 items)** — every batch of the v6 roadmap is now shipped:
-  - **Performance (batch 2)**: the final compositing chain is now ffmpeg-based — identical-parameter scene concatenation uses `-c copy`, audio alignment/volume/silence-padding merge into a single filter pass, and subtitles render through the ASS path with per-entry styles (`AGNES_SUBTITLE_ASS`, with automatic fallback to the moviepy path). Poetry videos compose all scenes in one pass instead of re-encoding per scene. A dedicated encoding thread pool isolates heavy ffmpeg/moviepy work from API requests, and the token-bucket rate limiter gained a native async path so stopping a task during rate-limit waits is instant.
-  - **Reliability & engineering (batch 1)**: task state follows a single-writer principle with per-task locking, resume supports persisted word-level TTS cues (no re-synthesis on resume), video polling is adaptive and multi-scene waits run concurrently, task listing is indexed with `limit/offset/status` pagination, stale artifacts/error logs are governed, and the frontend stops polling in background tabs with exponential backoff and a connection-loss banner.
-  - **Frontend & i18n**: translations are split into per-language lazy-loaded chunks — the first-screen JS bundle drops from ~721 kB to ~305 kB (gzip 226 kB → 97 kB, **-58%**). Form submission/confirm/toast flows were unified into shared composables, mobile layout, focus-trap modals, `prefers-reduced-motion` and form drafts were added.
-  - **Observability & ops (batch 3)**: new `GET /api/health` and `GET /api/metrics` endpoints, optional rotating file logging (`AGNES_LOG_FILE`), and a Docker `HEALTHCHECK`. Runtime settings are now converged through typed `pydantic-settings` (with `.env` support) so concurrency limits scale dynamically with API-key count.
-  - **Immediate defect fixes (batch 0)**: stop now cancels instantly without retry backoff, event-loop blocking (watermark re-encode, sync downloads) is moved off the loop, multi-key delete works correctly, a frontend `v-html` XSS vector is closed, and image generation got a duplicate-submit guard.
-- **Full 22-language support incl. Arabic** — the UI already had 22 languages; this release completes the voice catalog for all of them. Arabic UI is fully supported (PR #32), and 8 UI languages (Turkish, Vietnamese, Thai, Tagalog, Hindi, Persian, Bengali, Urdu) now have edge_tts voice groupings with native-voice name display, script-detection regexes (Thai/Devanagari/Bengali) and per-script subtitle font fallback (new bundled Noto fonts; Persian/Urdu reuse the Arabic reshape+bidi pipeline).
-- **Transparent analytics disclosure & privacy controls** — the settings panel now shows a clear, collapsible privacy card listing exactly what usage statistics are reported (and what is never uploaded: prompts, manuscripts, poems, API keys and reference images are redacted before reporting). Analytics can be turned off entirely from the panel.
-- **Complete error tracebacks in the feedback report** — pipeline failures now persist the full `traceback` into the task state; the diagnostics endpoint and the in-app feedback report include it, so you can paste complete error details (e.g. environment-level `[WinError 2]`) into GitHub issues without checking the server console.
-
-### Refactoring & Optimizations
-
-- **ffmpeg-first compositing chain** — the final assembly path for creative/manuscript/anchor/poetry videos was reworked from 3-4 full re-encodes into copy-concat + a single filter pass (with graceful fallback to the previous moviepy path). This is the largest performance win in the v6 line, cutting final-assembly time by roughly 3-10x on typical outputs.
-- **Asynchronous rate limiting with dedicated encoding thread pool** — the token bucket now offers a native async acquire path (stop-aware), and heavy encoding runs on a dedicated executor so long encoding jobs no longer starve the request path.
-
 ### Bug Fixes
 
-- **Fixed stopping behavior** — cancelling a task no longer triggers retry backoff (up to ~2 minutes) and no longer deletes a resumable `video_id`.
-- **Fixed multi-Key configuration** — key IDs are now hashed from the actual key so deleting one Key from multiple configured Keys removes exactly that Key.
-- **Fixed event-loop freezes** — watermark re-encoding and synchronous downloads no longer block the whole service; a semaphore release bug that could permanently break the concurrency cap under low-rate-limit configurations is fixed.
-- **Fixed frontend issues** — a stored-XSS vector via unescaped `v-html` is closed, duplicate image-submit without guard is prevented, and fetch errors now surface readable backend messages instead of silent failures.
-
----
+* **Fixed "ffmpeg not found" failure (`FileNotFoundError`) during video composition** — on Windows or systems where `ffmpeg` is not on the `PATH`, creative / manuscript / anchor / poetry composition (concatenation, audio overlay, watermark) could fail at the composition step with `[WinError 2]`. The server now automatically falls back to the static ffmpeg binary bundled with `imageio-ffmpeg`, so no manual ffmpeg installation is required. A non-blocking startup check logs which ffmpeg source is being used. (Issues #35, #36)
 
-No configuration changes are required. Existing tasks remain resumable; task state files are unchanged in format.
 
 ---
 

package/core/api/rate_limiter.py

@@ -167,14 +167,19 @@ class AgnesRateLimiter:
     def acquire(self) -> None:
         """阻塞式获取一个令牌（同步场景 / 脚本 / 测试用）。
 
-        如果桶中有令牌，立即消耗并返回；否则 ``time.sleep()`` 直到令牌可用。
+        如果桶中有令牌，立即消耗并返回；否则 ``time.sleep()`` 等待令牌可用。
+
+        ⚠️ 修复（回归活锁）：此处采用与 ``acquire_async`` 一致的**预支语义**——
+        ``_try_acquire`` 已把 ``last_refill`` 预留到 ``now + wait_time`` 并清空令牌，
+        sleep 期间令牌尚未重新累积，再次循环调用 ``_try_acquire`` 会算出 ``elapsed≈0``
+        而**永远不足 1 个令牌**，导致令牌永不补充、等待者永久卡死（多并发时逐个推挤
+        ``last_refill`` 还使 wait_time 越滚越大）。因此 sleep 完成后直接视为已获取。
         """
-        while True:
-            wait_time = self._try_acquire()
-            if wait_time is None:
-                return
-            self._record_wait(wait_time)
-            time.sleep(wait_time)
+        wait_time = self._try_acquire()
+        if wait_time is None:
+            return
+        self._record_wait(wait_time)
+        time.sleep(wait_time)
 
     async def acquire_async(self, stop_event: asyncio.Event | None = None) -> None:
         """异步原生获取令牌（优化路线图 2.3）。

package/core/audio/subtitle/generator.py

@@ -253,6 +253,14 @@ class SubtitleSrtMixin:
             if text:
                 items.append((start_s, end_s, text))
 
+        # PRD 1.2a：TTS 若送入了加 tashkeel 的阿拉伯语文本，cues 文本会连带
+        # 变音符号——字幕显示前统一剥离（仅阿拉伯语变音符号，其他语言无副作用）。
+        from core.audio.tashkeel import strip_diacritics
+
+        items = [(s, e, strip_diacritics(t)) for s, e, t in items]
+        if not items:
+            return ""
+
         if not items:
             return ""
 
@@ -594,6 +602,13 @@ class SubtitleSrtMixin:
         if not items:
             return ""
 
+        # PRD 1.2a：TTS 若送入了加 tashkeel 的阿拉伯语文本，cues 文本会连带
+        # 变音符号——字幕显示前统一剥离（仅阿拉伯语变音符号，其他语言无副作用）。
+        # 剥离后再做归一化对齐，保证与 plain 的 segment_texts 策略 A 字符区间匹配。
+        from core.audio.tashkeel import strip_diacritics
+
+        items = [(s, e, strip_diacritics(t)) for s, e, t in items]
+
         # 残余归一化：把最后一条 cue 的 end 钳到实际音频时长（避免尾差留白未覆盖）
         if audio_duration and audio_duration > 0 and items[-1][1] > audio_duration:
             items[-1] = (items[-1][0], audio_duration, items[-1][2])

package/core/audio/tashkeel.py

@@ -0,0 +1,117 @@
+"""阿拉伯语变音符号（tashkeel/harakat）自动标注，供 TTS 更准确地朗读。
+
+使用 mishkal（基于规则的阿拉伯语形态分析库）而非 LLM 来生成变音符号：
+LLM 方案实测不可靠——即使明确要求"只加符号、不改字母"，模型仍会偶发替换
+借词拼写（如 فيديو -> ويديو）或替换同义连词（如 إذا -> إن），这对旁白配音
+是不可接受的（读出的内容会与原文不同）。mishkal 只做形态学标注，天然不会
+引入新字母，因此改用"取 mishkal 的变音符号 + 保留原文逐字符结构"的合并算法，
+以程序方式保证结果与原文在去除变音符号后完全一致。
+
+依赖模式：**optional-dependency**（与 json-repair 相同的"缺失自动降级"模式）。
+本模块在导入时不加载 mishkal（``_get_vocalizer`` 内延迟导入），因此即使
+mishkal 未安装，``strip_diacritics`` 等公共函数仍可用；``add_tashkeel_safe``
+在 mishkal 缺失时静默回退原文。``requirements.txt`` 默认安装 mishkal 保证
+开箱即用。
+
+Port: PR #33 by @Khaled97Sho（新增公共 ``strip_diacritics`` 供字幕隔离复用）。
+"""
+from __future__ import annotations
+
+import logging
+import re
+
+logger = logging.getLogger(__name__)
+
+# 阿拉伯字母（U+0621–U+064A）
+_ARABIC_LETTER_RE = re.compile(r"[ء-ي]")
+# 阿拉伯语变音符号（harakat/tashkeel，U+064B–U+0670）：fatha/damma/kasra 等，
+# 仅标注发音、不产生语音时长。字幕与旁白导出产物必须剥离，避免污染显示。
+_DIACRITIC_RE = re.compile(r"[ً-ْٰ]")
+
+_vocalizer = None
+
+
+def strip_diacritics(text: str) -> str:
+    """去除文本中的阿拉伯语变音符号（tashkeel/harakat）。
+
+    用于字幕 / 旁白导出产物：加 tashkeel 的文本只应送入 TTS，字幕显示与
+    ``narration.txt`` 必须使用剥离变音符号的干净版本（PRD 1.2a）。
+    对不含变音符号的文本（其他语言）为无副作用操作。
+
+    Args:
+        text: 原始文本（可为空）。
+
+    Returns:
+        剥离阿拉伯语变音符号后的文本。
+    """
+    if not text:
+        return text
+    return _DIACRITIC_RE.sub("", text)
+
+
+def _get_vocalizer():
+    global _vocalizer
+    if _vocalizer is None:
+        from mishkal.tashkeel import TashkeelClass
+
+        _vocalizer = TashkeelClass()
+    return _vocalizer
+
+
+def _merge_tashkeel(original: str, diacritized: str) -> str:
+    """按原文逐字符重建结果：阿拉伯字母取自 mishkal 输出（含其变音符号），
+    其余字符（标点、空格、数字等）严格保留原文，不采用 mishkal 对它们的改写。
+    """
+    d_tokens: list[tuple[str, str]] = []
+    i = 0
+    while i < len(diacritized):
+        ch = diacritized[i]
+        if _ARABIC_LETTER_RE.match(ch):
+            j = i + 1
+            diac = ""
+            while j < len(diacritized) and _DIACRITIC_RE.match(diacritized[j]):
+                diac += diacritized[j]
+                j += 1
+            d_tokens.append((ch, diac))
+            i = j
+        else:
+            i += 1
+
+    out = []
+    ti = 0
+    for ch in original:
+        if _ARABIC_LETTER_RE.match(ch):
+            if ti < len(d_tokens):
+                letter, diac = d_tokens[ti]
+                out.append(letter + diac)
+                ti += 1
+            else:
+                out.append(ch)
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
+def add_tashkeel_safe(text: str) -> str:
+    """为阿拉伯文文本添加变音符号，失败或校验不通过时原样返回。
+
+    校验：合并结果去除变音符号后必须与输入（同样去除变音符号后）逐字符相等，
+    否则说明 mishkal 内部出现异常输出，这种情况下放弃标注、返回原文，
+    避免把错误内容送入 TTS。
+    """
+    if not text or not _ARABIC_LETTER_RE.search(text):
+        return text
+
+    base_text = strip_diacritics(text)
+    try:
+        vocalizer = _get_vocalizer()
+        raw_result = vocalizer.tashkeel(base_text)
+    except Exception as e:
+        logger.warning(f"[Tashkeel] mishkal failed, returning original text: {e}")
+        return text
+
+    merged = _merge_tashkeel(base_text, raw_result)
+    if strip_diacritics(merged) != base_text:
+        logger.warning("[Tashkeel] validation failed (letters changed), returning original text")
+        return text
+    return merged

package/core/audio/voices.py

@@ -180,6 +180,65 @@ def detect_text_script(text: str) -> str:
     return "unknown"
 
 
+# ═══════════════════════════════════════════════════
+# 语速估算（PR #33 吸收：跨脚本朗读速率差异 + 变音符号剥离）
+# ═══════════════════════════════════════════════════
+# 单一公共实现（PRD 1.3a）：story.py / manuscript_video.py / preview_routes
+# 均从本模块导入，消除此前两处 4.0/13.0 常量与脚本判断的重复副本。
+
+# CJK 字符密度高（一字近一音节），约 4 字/秒（实测 zh-CN-Xiaoxiao ≈ 4.7，取保守值）
+_CHARS_PER_SEC_CJK = 4.0
+# 阿拉伯文（2026-08-31 实测校准：ar-SA-Hamed/Zariyah ≈ 10.4-10.6、ar-EG-Shakir ≈ 12.0
+# 字符/秒，真实旁白含句间停顿更低，取 10.5；PR #33 原沿用的统一 13 偏快，会导致
+# 旁白比画面长出约 40%，视频被迫定格等待旁白结束）
+_CHARS_PER_SEC_ARABIC = 10.5
+# 其余字母文字（拉丁/西里尔/泰文/天城文/孟加拉文等）统一 13 字符/秒
+# （英文实测 15.7-16.8 偏快、法/西/俄未实测，13 为折中保守值，后续可分档校准）
+_CHARS_PER_SEC_ALPHABETIC = 13.0
+
+
+def estimate_chars_per_sec(text: str) -> float:
+    """按文本主要文字体系估算朗读语速（字符/秒）。
+
+    中文/日文/韩文按 CJK 速率（4.0 字/秒）；阿拉伯文按实测速率（10.5 字符/秒，
+    见 ``_CHARS_PER_SEC_ARABIC`` 校准记录）；其余脚本（拉丁/西里尔/泰文/
+    天城文/孟加拉文等）统一按字母文字速率（13.0 字符/秒，泰文等未实测脚本
+    先用统一值，后续可校准）。
+
+    Args:
+        text: 待估算朗读时长的文本。
+
+    Returns:
+        语速（字符/秒）。
+    """
+    script = detect_text_script(text)
+    if script in ("zh", "ja", "ko"):
+        return _CHARS_PER_SEC_CJK
+    if script == "arabic":
+        return _CHARS_PER_SEC_ARABIC
+    return _CHARS_PER_SEC_ALPHABETIC
+
+
+def duration_len(text: str) -> int:
+    """用于时长估算的字符数（剥离阿拉伯语变音符号后计数）。
+
+    阿拉伯语变音符号（harakat/tashkeel）只标注发音、不产生语音时长，
+    估算前必须剥离，否则加全变音符号的文本（codepoint 增加 40-60%）
+    会让时长估算严重偏长，导致生成视频尾部大片静音/定格。
+
+    Args:
+        text: 原始文本（可为空）。
+
+    Returns:
+        剥离变音符号后的字符数。
+    """
+    if not text:
+        return 0
+    from core.audio.tashkeel import strip_diacritics
+
+    return len(strip_diacritics(text))
+
+
 # edge-tts voice id 前缀 → 项目语言 code 映射。
 # 例外：Tagalog 音色在 edge-tts 中用 ISO 639-3 代码 `fil`（如 fil-PH-AngeloNeural），
 # 而项目/前端 UI 用 ISO 639-1 `tl`，故需显式归一。

package/core/compositor/concatenator/audio_overlay.py

@@ -13,6 +13,7 @@ from typing import List, Optional, Tuple
 import srt as srt_lib
 from moviepy import AudioFileClip, CompositeVideoClip, VideoFileClip
 
+from core.compositor.ffmpeg_tool import resolve_binary
 from models.task import SubtitleStyle
 
 from .concat import _AUDIO_BITRATE, _AUDIO_CODEC, _AUDIO_FPS, _VIDEO_FPS
@@ -137,7 +138,7 @@ class AudioOverlayMixin:
             tmp_files.append(extend_path)
             pad_dur = final_dur - video_dur
             VideoConcatenator._run_ffmpeg(
-                ["ffmpeg", "-y",
+                [resolve_binary("ffmpeg"), "-y",
                  "-i", silent_path,
                  "-vf", f"tpad=stop_mode=clone:stop_duration={pad_dur:.2f}",
                  "-c:v", "libx264", "-pix_fmt", "yuv420p",
@@ -154,7 +155,7 @@ class AudioOverlayMixin:
             tmp_files.append(apad_path)
             pad_dur = final_dur - audio_dur
             VideoConcatenator._run_ffmpeg(
-                ["ffmpeg", "-y",
+                [resolve_binary("ffmpeg"), "-y",
                  "-i", audio_path,
                  "-af", f"apad=pad_dur={pad_dur:.2f},volume=1.5",
                  "-c:a", "libmp3lame", "-q:a", "2",
@@ -167,7 +168,7 @@ class AudioOverlayMixin:
             vol_path = audio_path.replace(".mp3", "_vol.mp3")
             tmp_files.append(vol_path)
             VideoConcatenator._run_ffmpeg(
-                ["ffmpeg", "-y",
+                [resolve_binary("ffmpeg"), "-y",
                  "-i", audio_path,
                  "-af", "volume=1.5",
                  "-c:a", "libmp3lame", "-q:a", "2",
@@ -290,7 +291,7 @@ class AudioOverlayMixin:
         else:
             v_chain = f"[0:v]tpad=stop_mode=clone:stop_duration={final_dur:.2f}[v]"
         cmd = [
-            "ffmpeg", "-y",
+            resolve_binary("ffmpeg"), "-y",
             "-i", silent_path,
             "-i", audio_path,
             "-filter_complex",
@@ -315,7 +316,7 @@ class AudioOverlayMixin:
         """ffprobe 获取视频宽高，失败回退 (768, 1152)。"""
         try:
             r = subprocess.run(
-                ["ffprobe", "-v", "error", "-select_streams", "v:0",
+                [resolve_binary("ffprobe"), "-v", "error", "-select_streams", "v:0",
                  "-show_entries", "stream=width,height",
                  "-of", "csv=s=x:p=0", video_path],
                 stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=15,
@@ -706,7 +707,7 @@ class AudioOverlayMixin:
         """
         try:
             n = len(audio_paths)
-            cmd = ["ffmpeg", "-y"]
+            cmd = [resolve_binary("ffmpeg"), "-y"]
             for ap in audio_paths:
                 cmd += ["-i", ap]
             filters = []
@@ -811,7 +812,7 @@ class AudioOverlayMixin:
 
         # Step 1: Get clip duration
         probe = subprocess.run(
-            ["ffprobe", "-v", "error", "-show_entries", "format=duration",
+            [resolve_binary("ffprobe"), "-v", "error", "-show_entries", "format=duration",
              "-of", "csv=p=0", clip_path],
             stdin=subprocess.DEVNULL,
             capture_output=True, text=True, timeout=15,
@@ -836,7 +837,7 @@ class AudioOverlayMixin:
         # Step 4: Concatenate with xfade cross-fade transitions
         try:
             subprocess.run(
-                ["ffmpeg", "-y", "-f", "concat", "-safe", "0",
+                [resolve_binary("ffmpeg"), "-y", "-f", "concat", "-safe", "0",
                  "-i", concat_file,
                  "-c", "copy",
                  "-t", str(needed),
@@ -850,7 +851,7 @@ class AudioOverlayMixin:
             # xfade filter 构建已由上方 trim 循环拼接替代（死代码，3.3 清理）
 
             subprocess.run(
-                ["ffmpeg", "-y",
+                [resolve_binary("ffmpeg"), "-y",
                  "-stream_loop", str(n - 1), "-i", clip_path,
                  "-filter_complex",
                  f"[0:v]trim=duration={needed}[v]",

package/core/compositor/concatenator/concat.py

@@ -11,6 +11,7 @@ from typing import List, Optional
 import srt as srt_lib
 from moviepy import VideoFileClip, concatenate_videoclips
 
+from core.compositor.ffmpeg_tool import resolve_binary
 from models.task import SubtitleStyle
 
 logger = logging.getLogger(__name__)
@@ -114,7 +115,7 @@ class ConcatMixin:
             sigs = set()
             for p in video_paths:
                 r = subprocess.run(
-                    ["ffprobe", "-v", "error", "-select_streams", "v:0",
+                    [resolve_binary("ffprobe"), "-v", "error", "-select_streams", "v:0",
                      "-show_entries", "stream=width,height,avg_frame_rate",
                      "-of", "csv=s=x:p=0", p],
                     stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=15,
@@ -137,7 +138,7 @@ class ConcatMixin:
                     f.write(f"file '{esc}'\n")
             try:
                 r = subprocess.run(
-                    ["ffmpeg", "-y", "-f", "concat", "-safe", "0",
+                    [resolve_binary("ffmpeg"), "-y", "-f", "concat", "-safe", "0",
                      "-i", concat_file, "-c", "copy", output_path],
                     stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=600,
                 )
@@ -383,7 +384,7 @@ class ConcatMixin:
         """用 ffprobe 获取媒体文件时长（秒）。"""
         try:
             r = subprocess.run(
-                ["ffprobe", "-v", "error", "-show_entries", "format=duration",
+                [resolve_binary("ffprobe"), "-v", "error", "-show_entries", "format=duration",
                  "-of", "csv=p=0", path],
                 stdin=subprocess.DEVNULL,
                 capture_output=True, text=True, timeout=15,
@@ -396,6 +397,12 @@ class ConcatMixin:
     def _run_ffmpeg(cmd: list, desc: str = "") -> None:
         """执行 ffmpeg 命令，失败时抛 RuntimeError。"""
         logger.info(f"[Compositor] ffmpeg: {desc}")
+        if not cmd or cmd[0] is None:
+            raise RuntimeError(
+                "ffmpeg not available (no system PATH ffmpeg nor builtin "
+                "imageio-ffmpeg). Please install ffmpeg or verify imageio-ffmpeg "
+                "is installed."
+            )
         try:
             r = subprocess.run(
                 cmd, stdin=subprocess.DEVNULL,

package/core/compositor/ffmpeg_tool.py

@@ -0,0 +1,102 @@
+"""core.compositor.ffmpeg_tool — ffmpeg / ffprobe 可执行文件统一解析。
+
+背景：此前所有 ffmpeg/ffprobe 调用都用裸命令字符串经 ``subprocess.run`` 执行，
+依赖系统 PATH 搜索可执行文件。Windows 未安装 ffmpeg 时 ``CreateProcess`` 抛
+``[WinError 2] The system cannot find the file specified``，且发生在任务运行到
+拼接步骤而非启动时（见 Issue #36 的完整 traceback）。
+
+解析优先级（推荐，但不强制用户安装系统 ffmpeg）：
+  1. 环境变量显式指定：``FFMPEG_BINARY`` / ``FFPROBE_BINARY`` —— 尊重用户意图
+  2. 系统 PATH（``shutil.which``）—— 已安装则用之，绝不覆盖
+  3. ``imageio-ffmpeg`` 内置静态二进制兜底 —— wheel 自带，无需用户操作
+
+结果带进程级缓存；全部不可用时返回 None，由启动检测 / 调用方给出清晰指引
+而非裸的 ``[WinError 2]``。
+"""
+import logging
+import os
+import shutil
+
+logger = logging.getLogger(__name__)
+
+# 二进制名 → 覆盖环境变量名
+_EXE_OVERRIDE = {"ffmpeg": "FFMPEG_BINARY", "ffprobe": "FFPROBE_BINARY"}
+_cache: "dict[str, str | None]" = {}
+
+
+def resolve_binary(name: str) -> "str | None":
+    """按优先级解析 ffmpeg/ffprobe 可执行文件绝对路径，进程内缓存。
+
+    Args:
+        name: ``"ffmpeg"`` 或 ``"ffprobe"``。
+
+    Returns:
+        可用可执行文件绝对路径；全部不可用时返回 None。
+    """
+    if name not in _EXE_OVERRIDE:
+        raise ValueError(f"unknown binary: {name}")
+    if name in _cache:
+        return _cache[name]
+    path = _resolve(name)
+    _cache[name] = path
+    return path
+
+
+def resolve_ffmpeg() -> "str | None":
+    """便捷：解析 ffmpeg。"""
+    return resolve_binary("ffmpeg")
+
+
+def resolve_ffprobe() -> "str | None":
+    """便捷：解析 ffprobe（可能为 None，仅时长/尺寸探测用，调用方自带兜底）。"""
+    return resolve_binary("ffprobe")
+
+
+def _resolve(name: str) -> "str | None":
+    # 1) 显式指定
+    override = os.environ.get(_EXE_OVERRIDE[name])
+    if override and os.path.exists(override):
+        logger.info(f"[Compositor] {name}: explicit {override}")
+        return override
+
+    # 2) 系统 PATH
+    found = shutil.which(name)
+    if found:
+        logger.info(f"[Compositor] {name}: system {found}")
+        return found
+
+    # 3) imageio-ffmpeg 内置（仅自带 ffmpeg；ffprobe 从同目录推导）
+    base = _cache.get("ffmpeg") or _resolve_builtin_ffmpeg()
+    if base:
+        if name == "ffmpeg":
+            return base
+        probe = _sibling(base, "ffprobe")
+        if probe:
+            logger.info(f"[Compositor] {name}: builtin {probe}")
+            return probe
+
+    logger.warning(f"[Compositor] {name}: not found (no system PATH nor builtin)")
+    return None
+
+
+def _resolve_builtin_ffmpeg() -> "str | None":
+    """取 imageio-ffmpeg 内置静态二进制；加载/失败时记录并返回 None。"""
+    try:
+        import imageio_ffmpeg
+
+        exe = imageio_ffmpeg.get_ffmpeg_exe()
+    except Exception as e:  # 加载失败 / 内置缺失 / 首次下载失败
+        logger.warning(f"[Compositor] builtin ffmpeg unavailable: {e}")
+        return None
+    if exe and os.path.exists(exe):
+        logger.info(f"[Compositor] ffmpeg: builtin {exe}")
+        return exe
+    return None
+
+
+def _sibling(exe: str, stem: str) -> "str | None":
+    """由可执行文件路径推导同目录兄弟程序（Windows 补 .exe）。"""
+    candidate = os.path.join(
+        os.path.dirname(exe), stem + (".exe" if os.name == "nt" else "")
+    )
+    return candidate if os.path.exists(candidate) else None

package/core/compositor/processor.py

@@ -6,6 +6,8 @@
 import logging
 import os
 
+from core.compositor.ffmpeg_tool import resolve_binary
+
 logger = logging.getLogger(__name__)
 
 
@@ -20,7 +22,7 @@ class VideoProcessor:
 
         import subprocess
         subprocess.run([
-            "ffmpeg", "-y", "-i", input_path,
+            resolve_binary("ffmpeg"), "-y", "-i", input_path,
             "-vf", f"scale={width}:{height}:force_original_aspect_ratio=decrease,"
                     f"pad={width}:{height}:(ow-iw)/2:(oh-ih)/2",
             "-c:v", "libx264", "-preset", "fast",
@@ -37,7 +39,7 @@ class VideoProcessor:
 
         import subprocess
         subprocess.run([
-            "ffmpeg", "-y",
+            resolve_binary("ffmpeg"), "-y",
             "-sseof", "-1",
             "-i", video_path,
             "-frames:v", "1",
@@ -55,7 +57,7 @@ class VideoProcessor:
 
         import subprocess
         subprocess.run([
-            "ffmpeg", "-y",
+            resolve_binary("ffmpeg"), "-y",
             "-f", "lavfi",
             "-i", "anullsrc=r=44100:cl=mono",
             "-t", str(duration_sec),
@@ -87,7 +89,7 @@ class VideoProcessor:
         # 注意：勿再用 -t {freeze_duration}，那会把整个输出截断成只剩冻结段。
         try:
             subprocess.run([
-                "ffmpeg", "-y",
+                resolve_binary("ffmpeg"), "-y",
                 "-i", video_path,
                 "-vf", f"tpad=stop_mode=clone:stop_duration={freeze_duration}",
                 "-c:v", "libx264", "-preset", "fast",

package/core/compositor/watermark.py

@@ -11,6 +11,7 @@ import subprocess
 import tempfile
 from typing import NamedTuple, Optional
 
+from core.compositor.ffmpeg_tool import resolve_binary
 from core.config import resolve_font_path
 
 logger = logging.getLogger(__name__)
@@ -194,7 +195,7 @@ def add_watermark(
 
         # ffmpeg overlay: 将水印 PNG 叠加到视频上，无损流式拷贝
         cmd = [
-            "ffmpeg", "-y",
+            resolve_binary("ffmpeg"), "-y",
             "-i", input_path,
             "-i", wm_png_path,
             "-filter_complex", f"[0:v][1:v]overlay={layout.pos_x}:{layout.pos_y}[v]",

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 = "6.3.0"
+APP_VERSION = "6.4.1"
 
 # 未配置 API Key 时的统一报错文案（含免费获取与在线体验兜底，全站路由共用）
 API_KEY_MISSING_MSG = (
@@ -202,6 +202,13 @@ try:
         agnes_subtitle_ass: bool = True          # 2.1c 字幕 ASS 单链灰度开关
         agnes_video_poll_timeout: int = 1800     # 1.2 视频轮询总超时
 
+        # ── CORS（PR #33 吸收 Phase 2：可配置跨源白名单）──
+        # 供独立本地伴侣工具（如 agnes-simple-ui）从浏览器跨源调用本服务 API。
+        # agnes_cors_origins: 逗号分隔的允许源列表，空 = 不启用 CORS（默认，攻击面不变）。
+        # agnes_cors_enabled: None=auto（设置了 origins 才启用）；显式 "false" 即使设置了 origins 也禁用。
+        agnes_cors_origins: str = ""
+        agnes_cors_enabled: bool | None = None
+
         # ── 运维 ──
         agnes_log_file: str = ""
         agnes_sweep_age_days: int | None = None
@@ -235,6 +242,14 @@ except ImportError:  # pragma: no cover - pydantic-settings 为必备依赖，
                 "0", "false", "off",
             )
             self.agnes_video_poll_timeout = int(os.environ.get("AGNES_VIDEO_POLL_TIMEOUT", "1800"))
+            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"):
+                self.agnes_cors_enabled = False
+            elif _cors_enabled in ("1", "true", "on"):
+                self.agnes_cors_enabled = True
+            else:
+                self.agnes_cors_enabled = None
             self.agnes_log_file = os.environ.get("AGNES_LOG_FILE", "")
             self.agnes_sweep_age_days = _env_int("AGNES_SWEEP_AGE_DAYS")
             self.agnes_config_id_hmac_key = os.environ.get(
@@ -951,9 +966,12 @@ def get_video_model_capabilities() -> dict:
 # ═══════════════════════════════════════════════════
 
 # 可用域名映射
+# 注：Agnes 官方域名划分（来源：AgnesAI-Labs skills 的 model_catalog 参考值）：
+#   - com 国际站（主）：apihub.agnes-ai.com
+#   - cn  国内站（中国站）：api.agnes-ai.cn（apihub.agnes-ai.cn 仅作国际站备用，非国内站）
 AGNES_DOMAIN_MAP = {
     "com": "https://apihub.agnes-ai.com",
-    "cn": "https://apihub.agnes-ai.cn",
+    "cn": "https://api.agnes-ai.cn",
 }
 
 _DEFAULT_DOMAIN = "com"