free-short-video 6.3.0 → 6.4.0

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,34 @@
 ---
 
-# What's New in v6.3.0
+# What's New in v6.4.0
 
 ## 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.
+- **Preview ("dry-run") endpoints for creative and manuscript tasks** — `POST /api/creative/preview-script` and `POST /api/manuscript/preview-split` let you inspect the generated script or manuscript segments before submitting a full task. Synchronous, no task created. Preview calls share the Chat API rate limiter and have a lightweight in-process concurrency cap (429 + Retry-After) to prevent abuse. (Credit: @Khaled97Sho, PR #33)
+- **Arabic tashkeel for TTS narration** — creative and manuscript pipelines now automatically apply Arabic diacritic marks (harakat) to narration text before TTS synthesis, improving pronunciation quality. Tashkeel only affects TTS input; subtitle text and `narration.txt` remain clean. (Credit: @Khaled97Sho, PR #33)
+- **Manuscript reference images** — per-segment reference images for manuscript tasks are now supported via `reference_images` + `reference_images_map` parameters, matching the same feature used in creative pipelines. (Credit: @Khaled97Sho, PR #33)
+- **Language-aware narration budget** — narration length for non-CJK languages now uses a language-specific characters-per-second rate (Arabic: 4.0, CJK: 5.0, others: 12.0), fixing the "narration too short for non-CJK text" issue. (Credit: @Khaled97Sho, PR #33)
+- **Configurable CORS origins** — the `AGNES_CORS_ORIGINS` environment variable (comma-separated) allows any companion tool to call the core API cross-origin. `AGNES_CORS_ENABLED` can force-enable or disable; auto-detects when origins are set.
+- **China domestic API domain** — the `cn` domain in `AGNES_DOMAIN_MAP` now correctly points to `api.agnes-ai.cn` (the official China service endpoint), updated from the incorrect `apihub.agnes-ai.cn` (international-site fallback). The frontend domain picker reflects the correct hostname.
 
 ### 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.
+- **`split_manuscript_text()` extracted as a public utility** — the manuscript-splitting algorithm is now available as a standalone function, used by both the manuscript pipeline and the new preview-split endpoint.
 
 ### 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 rate-limiter live-lock** — a rare synchronous acquire path race condition could stall all pipelines indefinitely. The token bucket's async path is now the primary path, with the sync path hardened to prevent the live-lock. (Credit: @Khaled97Sho, PR #33)
+- **Fixed image save not persisting** — `POST /api/images/generations` now `await`s the image download, ensuring the generated image is actually written to disk before the response.
+- **Fixed GitHub CodeQL alerts #43 and #47** — path-injection and information-disclosure security alerts resolved.
+- **Fixed PBKDF2-HMAC-SHA256 for config key IDs** — config key IDs are now hashed with a proper key-derivation function instead of weaker hashing.
+- **Fixed Docker Hub Cloudflare WAF blocking** — the Docker Hub overview update script now strips `<script>` blocks and escapes `<` in the JSON payload to bypass the WAF XSS rule.
+- **Fixed China domestic site domain** — `AGNES_DOMAIN_MAP["cn"]` corrected to `api.agnes-ai.cn` per the official Agnes model catalog. (Issue #37)
 
 ---
 
-No configuration changes are required. Existing tasks remain resumable; task state files are unchanged in format.
+**Compatibility notes**: The `core/audio/tashkeel.py` module adds a new optional dependency (`mishkal`). It is installed by default via `requirements.txt`; if missing, tashkeel silently falls back to the original text. Existing task state files are forward-compatible; no migration needed.
 
 ---
 

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/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.0"
 
 # 未配置 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"

package/core/pipelines/creative/pipeline.py

@@ -69,13 +69,35 @@ class CreativeVideoPipeline(
         """
         super().__init__(api_key, task_id, dir_name, progress_callback, shutdown_event)
 
-        self.screenwriter = Screenwriter(api_key=api_key, model=chat_model)
+        # PRD 1.4：Screenwriter language pinning——默认 en、尊重显式配置。
+        # 默认中文系统提示词会让模型倾向于输出中文（即使提示词写明"跟随输入语言"），
+        # 实测英文/阿拉伯文 idea 在中文提示词下偶发被错误写成中文故事/旁白。
+        # 仅当用户未显式设置 PROMPT_LANGUAGE（使用默认 zh）时固定 language="en"；
+        # 显式配置代表用户知情选择，以用户配置为准（language=None 走 PROMPT_LANGUAGE）。
+        # 补充（2026-08-31 实测）：英文系统提示词下模型仍会因 user prompt 内的中文章节
+        # 片段把非中文 idea 写成中文——流水线三处 LLM 调用（故事/脚本/旁白）额外前置
+        # 显式语言指令（_style_with_language_directive），与 preview 端点同机制。
+        from core.screenwriter import is_prompt_language_explicit
+
+        _sw_language = None if is_prompt_language_explicit() else "en"
+        self.screenwriter = Screenwriter(api_key=api_key, model=chat_model, language=_sw_language)
         self.image_generator = AgnesImageAPI(api_key=api_key, model=image_model)
         self.video_generator = AgnesVideoAPI(api_key=api_key, model=video_model)
         self.video_generator.shutdown_event = shutdown_event
 
         self._state: Optional[CreativeVideoTask] = None
 
+    def _style_with_language_directive(self) -> str:
+        """用户 style 前置基于 idea 文字体系的显式语言指令。
+
+        idea 为非中文脚本时返回「指令 + style」，中文 idea 原样返回 style
+        （指令为空串）。指令确保故事/旁白跟随输入语言，同时保留"场景视觉提示词
+        用英文"的既有约定。
+        """
+        from core.screenwriter import build_input_language_directive
+
+        return build_input_language_directive(self._state.idea) + self._state.style
+
     # ------------------------------------------------------------------
     # Properties
     # ------------------------------------------------------------------

package/core/pipelines/creative/steps_audio.py

@@ -6,6 +6,7 @@ import os
 import re
 from typing import Optional
 
+from core.audio.voices import estimate_chars_per_sec
 from core.compositor.concatenator import VideoConcatenator
 from core.screenwriter import clean_narration_text
 from models.task import StepStatus
@@ -13,7 +14,6 @@ from models.task import StepStatus
 logger = logging.getLogger(__name__)
 
 
-_CHARS_PER_SEC = 4.0
 _SENTENCE_BOUNDARY_RE = re.compile(r"(?<=[。！？.!?])")
 
 # 音频/字幕阶段起始进度（阶段内线性插值）
@@ -120,15 +120,16 @@ class AudioStepsMixin:
         # On resume, re-trim existing narrations (old untrimmed data may persist)
         if self._state.narrations:
             _scenes = self._state.scenes
+            _cps = estimate_chars_per_sec(story)
             needs_update = any(
-                len(n) > max(int((_scenes[i].duration if i < len(_scenes) else self._state.video_duration) * _CHARS_PER_SEC), 20)
+                len(n) > max(int((_scenes[i].duration if i < len(_scenes) else self._state.video_duration) * _cps), 20)
                 for i, n in enumerate(self._state.narrations)
             )
             if needs_update:
                 self._state.narrations = [
                     _trim_to_sentence(
                         n,
-                        max(int((_scenes[i].duration if i < len(_scenes) else self._state.video_duration) * _CHARS_PER_SEC), 20),
+                        max(int((_scenes[i].duration if i < len(_scenes) else self._state.video_duration) * _cps), 20),
                     )
                     for i, n in enumerate(self._state.narrations)
                 ]
@@ -155,12 +156,13 @@ class AudioStepsMixin:
             narrations.append("\n".join(narrative_paras[idx : idx + count]))
             idx += count
 
-        # Trim each narration to fit within its scene's duration * 4 chars/sec speaking rate
+        # Trim each narration to fit within its scene's duration * estimated speaking rate
         _scenes = self._state.scenes
+        _cps = estimate_chars_per_sec(story)
         narrations = [
             _trim_to_sentence(
                 n,
-                max(int((_scenes[i].duration if i < len(_scenes) else self._state.video_duration) * _CHARS_PER_SEC), 20),
+                max(int((_scenes[i].duration if i < len(_scenes) else self._state.video_duration) * _cps), 20),
             )
             for i, n in enumerate(narrations)
         ]
@@ -202,12 +204,12 @@ class AudioStepsMixin:
             story,
             scenes,
             total_duration,
-            self._state.style,
+            self._style_with_language_directive(),
         )
 
         if not narration or len(narration) < 5:
             logger.warning("[Pipeline] LLM returned empty/short narration, using cleaned story fallback")
-            max_chars = max(int(total_duration * _CHARS_PER_SEC), 40)
+            max_chars = max(int(total_duration * estimate_chars_per_sec(story)), 40)
             narration = clean_narration_text(_trim_to_sentence(story, max_chars)) if story else ""
 
         self._state.narrations = [narration]
@@ -257,13 +259,28 @@ class AudioStepsMixin:
         # v5.x 产物规范前置：导出旁白纯文本（供外部 Agent/工具处理）
         narration_text = self._state.narrations[0] if self._state.narrations else ""
         self._save_narration_txt(narration_text, combined_audio)
+
+        # PRD 1.2a：tashkeel 只作用于送入 TTS 的文本，字幕/旁白导出产物用 plain 版本。
+        # state.narrations 始终保留无变音符号文本（字幕与 narration.txt 由此生成），
+        # 仅 narration_tts 加 tashkeel 送 TTS（含续传重采 cues）。
+        narration_tts = narration_text
+        if self._state.audio_config.add_tashkeel:
+            from core.audio.tashkeel import add_tashkeel_safe
+
+            narration_tts = add_tashkeel_safe(narration_text)
+            if narration_tts != narration_text:
+                logger.info(
+                    "[Pipeline] Step audio: tashkeel applied "
+                    "(plain kept for subtitles/export, %d chars)", len(narration_text),
+                )
+
         if os.path.exists(combined_audio) and os.path.getsize(combined_audio) > 0:
             logger.info("[Pipeline] Step audio: SKIP (file exists)")
             self._state.step_audio = StepStatus.COMPLETED
             self.task_manager.update_step("step_audio", StepStatus.COMPLETED)
             # 续传：音频已存在则仅重采 cues，避免字幕退回 legacy 启发式
             return await self._recover_sub_maker(
-                narration_text,
+                narration_tts,
                 self._state.audio_config, self._state.subtitle_config,
                 combined_audio,
             )
@@ -283,7 +300,7 @@ class AudioStepsMixin:
 
         sub_maker = await self._generate_audio_with_fallback(
             output_path=combined_audio,
-            text=narration_text,
+            text=narration_tts,
             audio_config=self._state.audio_config,
             subtitle_config=self._state.subtitle_config,
             duration_sec=total_duration,

package/core/pipelines/creative/steps_script.py

@@ -254,7 +254,7 @@ class ScriptStepsMixin:
             self.screenwriter.develop_story,
             self._state.idea,
             "",
-            self._state.style,
+            self._style_with_language_directive(),
             image_context,
             self._state.scene_count,
             self._state.scene_durations,
@@ -377,7 +377,7 @@ class ScriptStepsMixin:
         await self._emit("script", "running", "正在编写脚本...", _PROGRESS_SCRIPT_START)
         scenes = await asyncio.to_thread(
             self.screenwriter.write_script, story, "",
-            self._state.style,
+            self._style_with_language_directive(),
             self._state.scene_count,
             self._state.scene_durations,
         )