free-short-video 6.2.1 → 6.3.0

package/.env.example

@@ -7,29 +7,73 @@
 #   3. 重启服务生效（需已安装 python-dotenv；未安装时跳过 .env 读取，
 #      Key 仍可通过环境变量或 Web 设置页 POST /api/config/keys 配置）
 #
-# 完整多 Key / 限速说明见 docs/plans/v5.0/optimization_roadmap.md §1
+# 说明：
+#   - 系统环境变量优先级高于 .env（同名时覆盖 .env 中的值）
+#   - 注释掉（以 # 开头）的项表示「使用代码内默认值」，无需取消注释
+#   - 完整部署方式见 docs/public/getting-started.md
 # ═══════════════════════════════════════════════════════════════════
 
-# Agnes AI API Key（必填）
+
+# ── 1. API Key（必填）──────────────────────────────────────────────
 # 从 https://platform.agnes-ai.com 获取免费 Key
 AGNES_API_KEY=your-api-key-here
 
-# 多 Key 轮询（可选，见 optimization_roadmap §1.3）
-# 每个 Key 的配额独立，总量 ≈ 20 × Key 数 / 分钟
+
+# ── 2. 多 Key 轮询（可选，推荐）────────────────────────────────────
+# 每个 Key 的配额独立，总量 ≈ 20 × Key 数 / 分钟。
+# 命名规则：AGNES_API_KEY_2、AGNES_API_KEY_3 ... 序号依次递增，中间不可断号
+# （断号之后的 Key 不会被加载）。
+# 遇到 429 会自动轮换到下一个 Key；限速配额与并发上限随 Key 数线性放大。
 # AGNES_API_KEY_2=your-second-api-key
 # AGNES_API_KEY_3=your-third-api-key
 
-# 限速配额覆盖（次/分钟，默认 = 20 × Key 数 × 0.8 安全系数）
+
+# ── 3. 服务地址 ────────────────────────────────────────────────────
+HOST=0.0.0.0
+PORT=8765
+
+
+# ── 4. 限速（可选）─────────────────────────────────────────────────
+# 共享桶：Chat / 图片生成 / 图片上传 / 结果轮询 共用
+# 默认 = 20 × Key 数 × 0.8 安全系数；仍频繁 429 时可适当调低
 # AGNES_RATE_LIMIT=160
 
-# 桶容量覆盖（默认 = 4 × Key 数；仅需调节突发并发时使用）
+# 共享桶容量（默认 = 4 × Key 数；仅需调节突发并发时使用）
 # AGNES_RATE_BURST=32
 
-# 视频提交独立限速（次/分钟，默认 = 1 × Key 数；服务端为全局 1/min 时设 =1）
+# 视频提交独立桶（默认 = 1 × Key 数）
+# 若服务端对视频提交是「全局限 1/min」而非 per-Key，显式设为 1
 # AGNES_VIDEO_RATE_LIMIT=8
 # AGNES_VIDEO_RATE_BURST=8
 
-# 可选端点/模型覆盖
-# AGNES_BASE_URL=https://apihub.agnes-ai.com/v1
-# AGNES_IMAGE_MODEL=agnes-image-2.1-flash
-# AGNES_VIDEO_MODEL=agnes-video-v2.0
+# ⚠️ 与并发的联动：任务并发权重上限 = AGNES_RATE_LIMIT // 2（默认 10）
+#    各任务类型权重：简单视频 1 / 创意视频 3 / 稿件视频 4 / 数字人 2 / 诗词 3
+#    若把 AGNES_RATE_LIMIT 调得过低（例如 6），并发上限降到 3，
+#    权重为 4 的稿件类任务会因「权重超过并发上限」而无法启动。
+#    此时请调高该值，或配置多个 API Key。
+
+
+# ── 5. 图生图模型（可选）───────────────────────────────────────────
+# i2i 默认与 t2i 同模型（agnes-image-2.1-flash）；如需回退到 2.0：
+# AGNES_IMAGE_I2I_MODEL=agnes-image-2.0
+#
+# 注：视频 / 图片主模型请通过 Web UI 或 POST /api/config 选择，
+#     不再通过环境变量配置（AGNES_VIDEO_MODEL、AGNES_IMAGE_MODEL、
+#     AGNES_BASE_URL 均已废弃，代码中不再读取）。
+
+
+# ── 6. 运维（可选）─────────────────────────────────────────────────
+# 启动时清理 N 天前的僵尸任务目录（不设置则不执行清理）
+# AGNES_SWEEP_AGE_DAYS=7
+
+# 多 Key 管理接口生成 Key id 所用的哈希盐，一般无需修改
+# AGNES_CONFIG_ID_HMAC_KEY=agnes-config-keys-id-v1
+
+# 视频任务轮询总超时（秒，默认 1800）
+# AGNES_VIDEO_POLL_TIMEOUT=1800
+
+# 字幕合成：=0 关闭 ffmpeg ASS 单链（回退 moviepy 词级动效路径），默认开启
+# AGNES_SUBTITLE_ASS=1
+
+# 提示词语言（zh/en，影响 LLM meta-prompt 语言）
+# PROMPT_LANGUAGE=zh

package/README.md

@@ -1,12 +1,36 @@
 ---
 
-# What's New in v6.2.1
+# What's New in v6.3.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.
+
+### 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
 
-- **Localized feedback & diagnostic report** — the diagnostic report header, field names and the generated issue (GitHub) template are no longer hard-coded in Chinese. They now respect your UI language (22 languages), so fields, titles and truncation hints in the feedback panel render correctly for non-Chinese users.
+- **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.
+
+---
+
+No configuration changes are required. Existing tasks remain resumable; task state files are unchanged in format.
 
 ---
 
@@ -35,6 +59,49 @@ free-short-video
 [![Docker Hub](https://img.shields.io/docker/pulls/lcy362/free-short-video?label=docker%20pulls)](https://hub.docker.com/r/lcy362/free-short-video)
 [![npm](https://img.shields.io/npm/v/free-short-video?label=npm)](https://www.npmjs.com/package/free-short-video)
 
+<p align="center">
+  <img src="images/home.png" alt="Agnes Video Generator — Free AI Video Generator" width="720">
+</p>
+
+<!--
+schema.org structured data for SEO/GEO indexing. GitHub does not execute this script, but the raw JSON-LD is visible to search engines and AI engines that scan repository READMEs.
+-->
+<!--
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "SoftwareApplication",
+  "name": "Agnes Video Generator",
+  "alternateName": "Free AI Video Generator",
+  "applicationCategory": "MultimediaApplication",
+  "operatingSystem": "Linux, macOS, Windows",
+  "description": "A completely free, open-source AI video generator. No subscription, no high-end GPU, no usage limits — type a text idea and get narrated, auto-subtitled multi-scene AI videos. Supports text-to-video, image-to-video, keyframes animation, digital anchor and manuscript-to-video.",
+  "url": "https://github.com/lcy362/agnes-video-generator",
+  "downloadUrl": "https://github.com/lcy362/agnes-video-generator",
+  "softwareVersion": "1.0.0",
+  "license": "https://opensource.org/licenses/MIT",
+  "keywords": "free AI video generator, AI video generation, text to video, AI video creator, open source video generator, AI narration, auto subtitles, multi-scene video, Runway alternative, Pika alternative",
+  "offers": {
+    "@type": "Offer",
+    "price": "0",
+    "priceCurrency": "USD"
+  },
+  "author": {
+    "@type": "Person",
+    "@id": "https://lichuanyang.top/#author",
+    "name": "SandGrid",
+    "alternateName": "lcy362",
+    "url": "https://lichuanyang.top/",
+    "sameAs": [
+      "https://github.com/lcy362",
+      "https://gitee.com/sandgrid/agnes-video-generator",
+      "https://video.lichuanyang.top/"
+    ]
+  }
+}
+</script>
+-->
+
 > **🌏 Mirror Notice / 镜像说明**
 > This project is also mirrored on [Gitee](https://gitee.com/sandgrid/agnes-video-generator) for faster access in mainland China. The **GitHub repository is the primary home** of this project — issues, PRs, and stars are managed there.
 > 本项目在国内 Gitee 设有镜像仓库，便于国内访问加速；**GitHub 为项目主仓库**，Issue / PR / Star 均在 GitHub 提交。
@@ -121,6 +188,20 @@ To be honest, Agnes's video model isn't perfect yet. The generated frames are so
 | **Watermark** | No watermark | Built-in watermark | Built-in watermark | C2PA metadata | Built-in watermark |
 | **Usage Limit** | No limit (16 req/min rate limit) | Billed by compute | Billed by generation | Billed by generation | Billed by generation |
 
+## ⚙️ Configuration
+
+Everything is configured through environment variables — no config file is required. To start from a documented template:
+
+```bash
+cp .env.example .env    # then edit AGNES_API_KEY inside
+```
+
+[`.env.example`](.env.example) lists every supported variable with its default value: API key, multi-key rotation, rate limits, port, model overrides, and maintenance options.
+
+> **Have more than one API key?** Set `AGNES_API_KEY`, `AGNES_API_KEY_2`, `AGNES_API_KEY_3` … (numbering must be contiguous). Rate-limit quotas scale with your key count, a `429` automatically rotates to the next key, and the concurrency limit scales along with it.
+
+Full walkthrough: [Getting Started → Configure API Key](docs/public/getting-started.md).
+
 ## 📚 Documentation
 
 - **[Features](docs/public/features.md)** — Creation modes, the completely free AI model chain, AI narration & smart subtitles, flexible creative controls, production-grade reliability, and the multilingual Web UI.

package/core/__init__.py

@@ -3,15 +3,15 @@
 导出所有子包的核心类和工具函数。
 """
 
-from core.api import AgnesImageAPI, AgnesVideoAPI, AgnesChatAPI
+from core.api import AgnesChatAPI, AgnesImageAPI, AgnesVideoAPI
 from core.audio import EdgeTTSEngine, SilentTTSEngine, SubtitleGenerator
 from core.compositor import VideoConcatenator, VideoProcessor
 from core.pipelines import (
     BasePipeline,
-    PipelineShutdown,
-    SimpleVideoPipeline,
     CreativeVideoPipeline,
     ManuscriptVideoPipeline,
+    PipelineShutdown,
+    SimpleVideoPipeline,
 )
 
 __all__ = [

package/core/api/__init__.py

@@ -1,7 +1,7 @@
 """core.api — Agnes AI API 调用层"""
 
+from core.api.agnes_chat import AgnesChatAPI
 from core.api.agnes_image import AgnesImageAPI, ImageOutput
 from core.api.agnes_video import AgnesVideoAPI, VideoOutput
-from core.api.agnes_chat import AgnesChatAPI
 
 __all__ = ["AgnesImageAPI", "ImageOutput", "AgnesVideoAPI", "VideoOutput", "AgnesChatAPI"]

package/core/api/agnes_chat.py

@@ -10,7 +10,6 @@ import logging
 import mimetypes
 import os
 import re
-import time
 from typing import List
 
 import requests

package/core/api/agnes_image.py

@@ -5,7 +5,6 @@ import base64
 import logging
 import mimetypes
 import os
-import time
 from typing import List, Optional
 
 import requests
@@ -29,7 +28,16 @@ class ImageOutput:
         self.ext = ext
         self.data = data
 
-    def save(self, path: str) -> None:
+    async def save(self, path: str) -> None:
+        """保存图片到 path（异步）。
+
+        优化路线图 0.3：URL 下载为同步 requests 流式读取，协程中直接调用会
+        阻塞事件循环；整体下沉到线程池执行。
+        """
+        await asyncio.to_thread(self._save_sync, path)
+
+    def _save_sync(self, path: str) -> None:
+        """同步保存实现（供线程池调用；同步上下文可直接使用）。"""
         if self.fmt == "url":
             download_image(self.data, path)
         else:
@@ -59,7 +67,8 @@ class AgnesImageAPI:
         self.api_key = api_key
         self.model = model
         # i2i 默认与 t2i 同模型（官方 2.1 同时支持 t2i/i2i）；环境变量可回退到 2.0。
-        env_i2i = os.environ.get("AGNES_IMAGE_I2I_MODEL")
+        from core.config import get_settings
+        env_i2i = get_settings().agnes_image_i2i_model
         self.i2i_model = i2i_model or env_i2i or model
         # 基础 headers（不含 Authorization）：每次请求前经 _auth_headers() 注入当前 Key
         self._base_headers = {
@@ -143,8 +152,8 @@ class AgnesImageAPI:
         max_rotations = len(ring) * max_retries
         while attempt < max_retries:
             try:
-                # 全局限速：在发起 HTTP 请求前获取令牌
-                await asyncio.to_thread(get_rate_limiter().acquire)
+                # 全局限速：在发起 HTTP 请求前获取令牌（2.3 异步原生）
+                await get_rate_limiter().acquire_async()
                 # 动态超时：第一次 120s，后续逐步增加（图像生成较慢，放宽读超时）
                 read_timeout = _READ_TIMEOUT_BASE_SECONDS * (attempt + 1)
                 resp = await asyncio.to_thread(
@@ -175,7 +184,7 @@ class AgnesImageAPI:
                             "image", "generate_single_image",
                             prompt=prompt,
                             error_type="RateLimit429",
-                            error_message=f"HTTP 429: rate limited",
+                            error_message="HTTP 429: rate limited",
                             status_code=429,
                             response_body=resp.text,
                             retry_count=attempt + 1,
@@ -188,7 +197,7 @@ class AgnesImageAPI:
                         "image", "generate_single_image",
                         prompt=prompt,
                         error_type="RateLimit429",
-                        error_message=f"HTTP 429: retries exhausted",
+                        error_message="HTTP 429: retries exhausted",
                         status_code=429,
                         response_body=resp.text,
                         retry_count=max_retries,

package/core/api/agnes_models.py

@@ -9,8 +9,8 @@ import logging
 import requests
 
 from core.config import (
-    DEFAULT_TEXT_MODEL,
     DEFAULT_IMAGE_MODEL,
+    DEFAULT_TEXT_MODEL,
     DEFAULT_VIDEO_MODEL,
     get_agnes_base_url,
 )

package/core/api/agnes_video.py

@@ -37,13 +37,56 @@ DURATION_PRESETS = {
 _UPLOAD_RETRY_BASE_DELAY_SECONDS = 30
 
 
+def _adaptive_poll_interval(interval: int, poll_count: int) -> int:
+    """优化路线图 1.3：自适应轮询间隔。
+
+    此前固定 ``interval``（默认 60s），每个视频平均多等 ~30s 检测延迟。
+    现改为 20s 起步，每 5 次轮询 +5s，上限为调用方 ``interval``；
+    调用方传小间隔（<20，如测试）时保持原样。
+    """
+    if interval < 20:
+        return interval
+    return min(interval, 20 + (poll_count // 5) * 5)
+
+
+class VideoTaskCancelled(RuntimeError):
+    """用户停止任务导致的取消（优化路线图 0.2）。
+
+    继承 RuntimeError 以保持向后兼容，但语义上区别于可重试的临时错误
+    （超时 / 网络 / 5xx）：停止必须立即穿透上层重试循环，否则用户点停止后
+    仍要经历 20s/40s 退避才真正停下。
+    """
+
+
+def is_remote_video_failure(exc: BaseException) -> bool:
+    """判断是否为「服务端已确认失败」——只有这种情况才可安全丢弃 video_id。
+
+    仅当服务端明确返回 ``status=failed``（异常信息含 "Video generation failed:"）
+    时为 True。超时、用户取消、网络中断时服务端任务**可能仍在运行**，必须返回
+    False 以保留 video_id 供续传，避免重复提交浪费视频配额（1 次/分钟/Key）。
+
+    优化路线图 0.2：此前流水线在任何异常下都删除 task.json，导致超时/取消后
+    续传只能重新提交。
+    """
+    return "Video generation failed:" in str(exc)
+
+
 class VideoOutput:
     def __init__(self, fmt: str, ext: str, data: str):
         self.fmt = fmt
         self.ext = ext
         self.data = data
 
-    def save(self, path: str) -> None:
+    async def save(self, path: str) -> None:
+        """保存视频到 path（异步）。
+
+        优化路线图 0.3：URL 下载为同步 requests 流式读取，耗时 5~30s+，
+        此前在协程中直接调用会阻塞事件循环；整体下沉到线程池执行。
+        """
+        await asyncio.to_thread(self._save_sync, path)
+
+    def _save_sync(self, path: str) -> None:
+        """同步保存实现（供线程池调用；同步上下文可直接使用）。"""
         if self.fmt == "url":
             download_video(self.data, path)
         else:
@@ -158,7 +201,7 @@ class AgnesVideoAPI:
                     },
                 }
                 logger.info(f"[AgnesVideo] Uploading image to hosted URL (attempt {attempt + 1}/{retries})...")
-                await asyncio.to_thread(get_rate_limiter().acquire)
+                await get_rate_limiter().acquire_async(self.shutdown_event)
                 resp = await asyncio.to_thread(
                     requests.post,
                     f"{get_agnes_base_url()}/images/generations",
@@ -250,7 +293,7 @@ class AgnesVideoAPI:
         while True:
             # M2: 每次轮询前检查停止信号
             if self.shutdown_event and self.shutdown_event.is_set():
-                raise RuntimeError("Video generation cancelled by user")
+                raise VideoTaskCancelled("Video generation cancelled by user")
 
             elapsed = asyncio.get_event_loop().time() - start_time
             if elapsed > max_poll_duration:
@@ -270,8 +313,8 @@ class AgnesVideoAPI:
             try:
                 if poll_count % 10 == 0:
                     logger.info(f"[AgnesVideo] Polling video {video_id[:16]}... (poll #{poll_count + 1}, elapsed {elapsed:.0f}s)")
-                # 全局限速：每次轮询都消耗一个令牌
-                await asyncio.to_thread(get_rate_limiter().acquire)
+                # 全局限速：每次轮询都消耗一个令牌（2.3 异步原生，停止可打断）
+                await get_rate_limiter().acquire_async(self.shutdown_event)
                 # M2: 用 wait_for 包裹以支持取消；429 换 Key 立即重试（轮询也轮转 Key 分摊配额）
                 poll_attempts = 0
                 while True:
@@ -344,7 +387,8 @@ class AgnesVideoAPI:
                     )
                     raise RuntimeError(error_msg)
 
-            await asyncio.sleep(interval)
+            # 优化路线图 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:
         frame_reductions_left = 2  # allow up to 2 frame-count reductions on 400
@@ -354,11 +398,12 @@ class AgnesVideoAPI:
         max_rotations = len(ring) * self.max_retries
         while attempt < self.max_retries:
             if self.shutdown_event and self.shutdown_event.is_set():
-                raise RuntimeError("Video generation cancelled by user")
+                raise VideoTaskCancelled("Video generation cancelled by user")
             try:
                 logger.info(f"[AgnesVideo] Submitting {mode_desc} (attempt {attempt + 1}/{self.max_retries})...")
-                # 视频提交独立限速桶（服务端 1/min 硬限制，不与 chat/image 共享配额）
-                await asyncio.to_thread(get_video_submit_limiter().acquire)
+                # 视频提交独立限速桶（服务端 1/min 硬限制，不与 chat/image 共享配额；
+                # 2.3 异步原生，停止可打断）
+                await get_video_submit_limiter().acquire_async(self.shutdown_event)
                 # M2: 缩短读超时从 180s 到 60s，使 stop() 更快生效
                 resp = await asyncio.wait_for(
                     asyncio.to_thread(
@@ -671,7 +716,13 @@ class AgnesVideoAPI:
         return video_id
 
     async def wait_for_video(self, video_id: str, progress_callback=None) -> VideoOutput:
-        final = await self._poll_task(video_id, progress_callback=progress_callback)
+        # 1.2：轮询总超时可经 AGNES_VIDEO_POLL_TIMEOUT 配置（3.5 RuntimeSettings 收敛）
+        from core.config import get_settings
+        poll_timeout = get_settings().agnes_video_poll_timeout
+        final = await self._poll_task(
+            video_id, progress_callback=progress_callback,
+            max_poll_duration=poll_timeout,
+        )
 
         video_url = (
             final.get("remixed_from_video_id")

package/core/api/error_collector.py

@@ -71,6 +71,25 @@ def _get_log_dir() -> Path:
     return log_dir
 
 
+# 优化路线图 1.5b：error_logs 按数量轮转，超过上限后删除最旧文件，
+# 防止长期运行的工作区无限膨胀（诊断端点 _iter_error_logs 全量读取也受影响）。
+_MAX_ERROR_LOGS = 500
+
+
+def _rotate_error_logs(log_dir: Path) -> None:
+    """超过 _MAX_ERROR_LOGS 个文件时，按 mtime 删除最旧的超量文件。"""
+    try:
+        files = [p for p in log_dir.glob("*.json") if p.is_file()]
+        if len(files) <= _MAX_ERROR_LOGS:
+            return
+        files.sort(key=lambda p: p.stat().st_mtime)  # 最旧在前
+        for p in files[: len(files) - _MAX_ERROR_LOGS]:
+            p.unlink(missing_ok=True)
+            logger.info(f"[ErrorCollector] Rotated old error log → {p.name}")
+    except OSError:
+        pass
+
+
 def set_error_task_id(task_id: str) -> None:
     """设置当前上下文的 task_id（v6.1 二期，诊断关联用）。
 
@@ -179,6 +198,9 @@ def collect_error(
         with open(filepath, "w", encoding="utf-8") as f:
             json.dump(error_data, f, ensure_ascii=False, indent=2)
 
+        # 优化路线图 1.5b：按数量轮转，防止 error_logs 无限膨胀
+        _rotate_error_logs(log_dir)
+
         logger.info(f"[ErrorCollector] Error saved → {filepath}")
         return str(filepath)
 

package/core/api/key_manager.py

@@ -16,6 +16,7 @@
 import itertools
 import logging
 import threading
+from typing import Optional
 
 from core.config import get_api_keys
 
@@ -29,15 +30,30 @@ class KeyRing:
         self._keys = list(keys)
         self._count = itertools.count()
         self._lock = threading.Lock()
+        # rotate() 钉住的下一个 Key 索引：rotate 后紧接的 next() 必须返回该 Key
+        # （此前 rotate 与 next 共享递增计数，rotate 消费一个序号后 next 取模
+        #  又回到原 Key，导致 429 换 Key 重试实际仍用旧 Key）
+        self._force_next: Optional[int] = None
 
     def next(self) -> str:
         """轮转取下一个 Key（普通请求调用，均匀分摊）。"""
-        return self._keys[next(self._count) % len(self._keys)]
+        with self._lock:
+            if self._force_next is not None:
+                idx = self._force_next
+                self._force_next = None
+                return self._keys[idx]
+            return self._keys[next(self._count) % len(self._keys)]
 
     def rotate(self) -> str:
-        """强制切换到下一个 Key（429 换 Key 重试调用）。"""
+        """强制切换到下一个 Key（429 换 Key 重试调用）。
+
+        递增计数返回下一个 Key，并记录为 ``_force_next``，确保紧随其后的
+        ``next()``（即重试请求的 ``_auth_headers()``）真的使用新 Key，
+        之后恢复正常 round-robin。
+        """
         with self._lock:
             idx = next(self._count) % len(self._keys)
+            self._force_next = idx
             return self._keys[idx]
 
     @property

package/core/api/rate_limiter.py

@@ -28,9 +28,9 @@
 
 import asyncio
 import logging
-import os
 import threading
 import time
+from typing import Optional
 
 from core.api.key_manager import get_key_ring
 
@@ -55,7 +55,10 @@ def _key_count() -> int:
 
 def _effective_rate() -> float:
     """共享桶有效速率 = 单 Key 配额 × Key 数 × 安全系数。"""
-    limit = int(os.environ.get("AGNES_RATE_LIMIT", str(_KEY_BASE_RATE * _key_count())))
+    from core.config import get_settings
+    limit = get_settings().agnes_rate_limit
+    if limit is None or limit <= 0:
+        limit = _KEY_BASE_RATE * _key_count()
     return limit * _SAFETY_FACTOR
 
 
@@ -65,18 +68,29 @@ def _video_submit_rate() -> float:
     注：若服务端对视频提交是全局限 1/min（而非 per-Key），
     设置 AGNES_VIDEO_RATE_LIMIT=1 即可，无需改代码。
     """
-    limit = int(os.environ.get("AGNES_VIDEO_RATE_LIMIT", str(_VIDEO_SUBMIT_RATE * _key_count())))
+    from core.config import get_settings
+    limit = get_settings().agnes_video_rate_limit
+    if limit is None or limit <= 0:
+        limit = _VIDEO_SUBMIT_RATE * _key_count()
     return limit * _VIDEO_SAFETY_FACTOR
 
 
 def _max_burst() -> int:
     """共享桶容量随 Key 数上调：4 × Key 数，否则高并发被突发容量卡住。"""
-    return int(os.environ.get("AGNES_RATE_BURST", str(4 * _key_count())))
+    from core.config import get_settings
+    burst = get_settings().agnes_rate_burst
+    if burst is None or burst <= 0:
+        burst = 4 * _key_count()
+    return burst
 
 
 def _video_max_burst() -> int:
     """视频提交桶容量 = 1 × Key 数：允许每 Key 立即提交一次，随后受 1/min 限制。"""
-    return int(os.environ.get("AGNES_VIDEO_RATE_BURST", str(_key_count())))
+    from core.config import get_settings
+    burst = get_settings().agnes_video_rate_burst
+    if burst is None or burst <= 0:
+        burst = _key_count()
+    return burst
 
 
 class AgnesRateLimiter:
@@ -111,12 +125,15 @@ class AgnesRateLimiter:
         self._total_waits = 0
         self._total_wait_seconds = 0.0
 
-    def acquire(self) -> None:
-        """阻塞式获取一个令牌。
+    def _try_acquire(self) -> Optional[float]:
+        """尝试获取令牌（线程安全）。返回 None=成功；否则返回需等待秒数。
 
-        如果桶中有令牌，立即消耗并返回。
-        否则计算等待时间并 ``time.sleep()`` 直到令牌可用。
+        优化路线图 2.3：等待计算与阻塞解耦，供同步 ``acquire`` 与异步
+        ``acquire_async`` 共用；速率 ≤ 0（如 ``AGNES_RATE_LIMIT=0``）时直接
+        放行，避免此前 ``wait_time = 1/0`` 除零崩溃。
         """
+        if self.refill_rate <= 0:
+            return None
         with self._lock:
             now = time.monotonic()
             elapsed = now - self.last_refill
@@ -128,15 +145,16 @@ class AgnesRateLimiter:
 
             if self.tokens >= 1.0:
                 self.tokens -= 1.0
-                return
+                return None
 
             # 需要等待的时间
             wait_time = (1.0 - self.tokens) / self.refill_rate
             self.tokens = 0.0
             # 更新 refill 时间基准，防止 sleep 期间令牌被其他线程"偷走"
             self.last_refill = now + wait_time
+            return wait_time
 
-        # sleep 在锁外执行，避免阻塞其他线程的 refill 计算
+    def _record_wait(self, wait_time: float) -> None:
         if wait_time > 0.05:
             self._total_waits += 1
             self._total_wait_seconds += wait_time
@@ -145,11 +163,40 @@ class AgnesRateLimiter:
                 f"(累计等待 {self._total_waits} 次, "
                 f"{self._total_wait_seconds:.0f}s)"
             )
+
+    def acquire(self) -> None:
+        """阻塞式获取一个令牌（同步场景 / 脚本 / 测试用）。
+
+        如果桶中有令牌，立即消耗并返回；否则 ``time.sleep()`` 直到令牌可用。
+        """
+        while True:
+            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) -> None:
-        """异步获取令牌（内部使用 ``asyncio.to_thread``）。"""
-        await asyncio.to_thread(self.acquire)
+    async def acquire_async(self, stop_event: asyncio.Event | None = None) -> None:
+        """异步原生获取令牌（优化路线图 2.3）。
+
+        等待在事件循环中执行（不再占线程池）；可被任务取消打断，或经
+        ``stop_event`` 提前放行（停止后调用方不会再发请求，无需令牌）。
+        """
+        while True:
+            wait_time = self._try_acquire()
+            if wait_time is None:
+                return
+            self._record_wait(wait_time)
+            remaining = wait_time
+            while remaining > 0:
+                if stop_event is not None and stop_event.is_set():
+                    return
+                await asyncio.sleep(min(0.1, remaining))
+                remaining -= 0.1
+            # 预支语义（与同步 acquire 一致）：等待完成即视为已获取令牌。
+            # 注意不能再调用 _try_acquire()——last_refill 已被推进到
+            # now+wait_time，再次计算会因 elapsed≈0 而永远不足。
+            return
 
     @property
     def stats(self) -> dict: