free-short-video 6.2.1 → 6.4.0

package/.env.example

@@ -7,29 +7,83 @@
 #   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
+
+
+# ── 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,12 +1,34 @@
 ---
 
-# What's New in v6.2.1
+# What's New in v6.4.0
 
 ## What's New
 
+### Features & Improvements
+
+- **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
+
+- **`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
 
-- **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 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)
+
+---
+
+**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.
 
 ---
 
@@ -35,6 +57,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 +186,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