fix(config): unify RPA runtime reads through config.get* (v1.0.16)

Route OPENCLAW_BROWSER_HEADLESS, OPENCLAW_PLAYWRIGHT_STEALTH, OPENCLAW_ARTIFACTS_ON_FAILURE, and OPENCLAW_RECORD_VIDEO (health diagnostics) through jiangchang_skill_core.config.get_bool so user .env and .env.example share the same three-tier priority as the rest of the skill stack.

Co-authored-by: Cursor <cursoragent@cursor.com>

.github/workflows/publish.yml

@@ -4,9 +4,6 @@ on:
   push:
     branches:
       - main
-    tags:
-      - "v*"
-  workflow_dispatch:
 
 jobs:
   publish:
@@ -25,13 +22,6 @@ jobs:
     steps:
       - uses: https://git.jc2009.com/admin/actions-checkout@v4
 
-      - name: Resolve and patch package version
-        env:
-          GITHUB_REF: ${{ github.ref }}
-          GITHUB_RUN_NUMBER: ${{ github.run_number }}
-          GITHUB_RUN_ID: ${{ github.run_id }}
-        run: python3.12 tools/ci_set_package_version.py
-
       - name: Install build tools
         run: python3.12 -m pip install --upgrade build twine --break-system-packages
 

.github/workflows/reusable-release-skill.yaml

@@ -108,6 +108,13 @@ jobs:
             '        shutil.copytree(src, dst, ignore=ignore_fn, dirs_exist_ok=True)' \
             '' \
             "shutil.copy2('SKILL.md', os.path.join(PACKAGE, 'SKILL.md'))" \
+            "readme_src = os.path.abspath('README.md')" \
+            "readme_dst = os.path.join(PACKAGE, 'README.md')" \
+            'if os.path.isfile(readme_src):' \
+            "    shutil.copy2(readme_src, readme_dst)" \
+            "    print('Copied README.md')" \
+            'if os.path.isfile(readme_src) and not os.path.isfile(readme_dst):' \
+            "    raise RuntimeError('README.md exists in skill root but was not packaged')" \
             "copy_dir('references', os.path.join(PACKAGE, 'references'), references_ignore)" \
             "copy_dir('assets', os.path.join(PACKAGE, 'assets'), common_ignore)" \
             "copy_dir('tests', os.path.join(PACKAGE, 'tests'), common_ignore)" \
@@ -144,7 +151,7 @@ jobs:
           skill_readme_md = (post.content or '').strip()
           skill_description = metadata.get('description')
           metadata['readme_md'] = skill_readme_md
-          readme_path = os.path.join('references', 'README.md')
+          readme_path = 'README.md'
           if os.path.isfile(readme_path):
               try:
                   readme_post = frontmatter.load(readme_path)

README.md

@@ -86,15 +86,39 @@ send_prompt_via_composer(page, "第一行\n第二行")
 
 读取背景音乐、字体、水印和 ffmpeg 工具。
 
-如果目录不存在，会优先通过 ZIP 下载公开仓库：
+如果目录不存在，会优先下载稳定 release bundle（不依赖用户电脑安装 Git）：
 
-`https://git.jc2009.com/client-commons/media-assets/archive/main.zip`
+`https://git.jc2009.com/client-commons/media-assets/releases/download/vlatest/media-assets.zip`
 
-这不依赖用户电脑安装 Git。
+bundle 内含背景音乐、字体与水印；**不包含** ffmpeg 二进制。ffmpeg / ffprobe 仍由 bundle 内 `manifest.json` 的 `tools.ffmpeg` 下载源单独拉取。
 
 可通过环境变量覆盖：
 
-`MEDIA_ASSETS_ROOT=/path/to/custom/media-assets`
+- `MEDIA_ASSETS_ROOT=/path/to/custom/media-assets` — 本地资源目录
+- `MEDIA_ASSETS_BUNDLE_URL=https://example.com/media-assets.zip` — bundle 下载地址
+
+### Runtime diagnostics（统一 health 诊断）
+
+`jiangchang_skill_core.runtime_diagnostics` 提供各 Skill 共用的 Runtime / media-assets / ffmpeg 探测，避免每个技能各自复制检查逻辑。Skill 的 `health` 命令可调用：
+
+```python
+from jiangchang_skill_core import (
+    collect_runtime_diagnostics,
+    format_runtime_health_lines,
+    runtime_diagnostics_dict,
+)
+
+diag = collect_runtime_diagnostics(
+    skill_slug="my-skill",
+    platform_kit_min_version="1.0.10",  # 可选；省略则只报告当前版本
+    skill_root="/path/to/my-skill",     # 可选；用于检测 vendored jiangchang_skill_core
+)
+for line in format_runtime_health_lines(diag):
+    print(line)
+print(runtime_diagnostics_dict(diag))  # 可 JSON 序列化
+```
+
+诊断只读探测本地状态，不会触发 media-assets 下载。
 
 ### 录屏合成（`screencast`）
 
@@ -118,17 +142,18 @@ run_screencast(
 
 ## 5. 发版流程（维护者）
 
-### main 分支自动预发布
+### 发布规则
 
-每次推送到 `main` 会触发 `.github/workflows/publish.yml`，自动构建并发布 **post 预发布版本**（仅供 CI 流水线内部使用，**不是**正式版本线）。
-
-正式版本线使用 **1.0.x** semver，通过 git tag 发布。
+- jiangchang-platform-kit **只发布正式版本**。
+- 每次需要发布公共能力时，先 bump `pyproject.toml` 的 `version`（例如 `1.0.10` → `1.0.11`）。
+- 推送 `main` 后，`.github/workflows/publish.yml` 会构建并上传该正式版本到 Gitea PyPI。
+- 发布包版本必须等于 `pyproject.toml` 中的 `version`；若该版本已存在，上传会失败，需继续 bump 版本号后再推送。
 
 ```bash
 git push origin main
 ```
 
-测试人员升级安装（始终安装当前正式 tag 对应的版本，例如 `1.0.9`）：
+升级安装：
 
 ```bash
 python -m pip install --upgrade \
@@ -137,15 +162,6 @@ python -m pip install --upgrade \
   jiangchang-platform-kit
 ```
 
-### 正式版本（tag）
-
-打 tag 并推送后，发布 **去掉 `v` 前缀** 的正式版本号（例如 `v1.0.9` → PyPI 包 `1.0.9`）：
-
-```bash
-git tag v1.0.9
-git push origin v1.0.9
-```
-
 ### 安装后验证
 
 ```bash

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "jiangchang-platform-kit"
-version = "1.0.10"
+version = "1.0.16"
 description = "匠厂平台共享组件:Skill 实体 SDK + 桌面应用自动化 SDK"
 readme = "README.md"
 requires-python = ">=3.10"

src/jiangchang_desktop_sdk/__init__.py

@@ -23,7 +23,7 @@ __all__ = [
     "LaunchError",
     "GatewayDownError",
 ]
-__version__ = "1.0.9"
+__version__ = "1.0.13"
 
 
 def __getattr__(name: str):

src/jiangchang_skill_core/__init__.py

@@ -25,7 +25,10 @@ from .media_assets import (
     MediaAssetsStatus,
     background_music_issue,
     ensure_media_assets,
+    is_git_lfs_pointer,
+    is_usable_audio_file,
     pick_background_music,
+    probe_background_music,
     probe_ffmpeg,
     probe_media_assets,
     resolve_ffmpeg,
@@ -33,6 +36,15 @@ from .media_assets import (
     resolve_media_assets_root,
     resolve_music_dir,
 )
+from .runtime_diagnostics import (
+    RuntimeDiagnostics,
+    RuntimeIssue,
+    collect_runtime_diagnostics,
+    format_runtime_health_lines,
+    is_jiangchang_skill_core_from_skill_tree,
+    runtime_diagnostics_dict,
+    version_ge,
+)
 
 try:
     from . import rpa
@@ -46,8 +58,16 @@ __all__ = [
     "EntitlementResult",
     "EntitlementServiceError",
     "MediaAssetsStatus",
+    "RuntimeDiagnostics",
+    "RuntimeIssue",
     "background_music_issue",
+    "collect_runtime_diagnostics",
     "ensure_media_assets",
+    "format_runtime_health_lines",
+    "is_git_lfs_pointer",
+    "is_jiangchang_skill_core_from_skill_tree",
+    "is_usable_audio_file",
+    "probe_background_music",
     "probe_ffmpeg",
     "probe_media_assets",
     "pick_background_music",
@@ -55,6 +75,8 @@ __all__ = [
     "resolve_ffprobe",
     "resolve_media_assets_root",
     "resolve_music_dir",
+    "runtime_diagnostics_dict",
+    "version_ge",
     "apply_cli_local_defaults",
     "attach_unified_file_handler",
     "ensure_env_file",

src/jiangchang_skill_core/media_assets.py

@@ -16,11 +16,12 @@ import zipfile
 from dataclasses import dataclass, field
 from datetime import datetime
 from pathlib import Path
-from typing import Optional
+from typing import Any, Mapping, Optional
 
-MEDIA_ASSETS_ZIP_URL = (
-    "https://git.jc2009.com/client-commons/media-assets/archive/main.zip"
+MEDIA_ASSETS_BUNDLE_URL = (
+    "https://git.jc2009.com/client-commons/media-assets/releases/download/vlatest/media-assets.zip"
 )
+MEDIA_ASSETS_ZIP_URL = MEDIA_ASSETS_BUNDLE_URL
 MEDIA_ASSETS_GIT_URL = "https://git.jc2009.com/client-commons/media-assets"
 
 _WIN_DEFAULT_DATA_ROOT = Path(r"D:\jiangchang-data")
@@ -28,17 +29,20 @@ _NON_WIN_DEFAULT_DATA_ROOT = Path.home() / ".jiangchang"
 
 _AUDIO_EXTENSIONS = {".mp3", ".wav", ".m4a", ".aac"}
 _GIT_LFS_POINTER_PREFIX = b"version https://git-lfs.github.com/spec/v1"
-_MIN_AUDIO_BYTES = 128
+_MIN_AUDIO_BYTES = 1024
 
 
-def _is_git_lfs_pointer(path: Path) -> bool:
+def is_git_lfs_pointer(path: str | Path) -> bool:
     try:
-        head = path.read_bytes()[:256]
+        head = Path(path).read_bytes()[:256]
     except OSError:
         return False
     return head.startswith(_GIT_LFS_POINTER_PREFIX)
 
 
+_is_git_lfs_pointer = is_git_lfs_pointer
+
+
 def _enumerate_audio_like(music_dir: Path) -> list[Path]:
     return [
         path
@@ -75,21 +79,25 @@ def _needs_music_content_repair(status: MediaAssetsStatus) -> bool:
     )
 
 
-def _is_usable_audio_file(path: Path) -> bool:
-    if not path.is_file():
+def is_usable_audio_file(path: str | Path, *, min_bytes: int = _MIN_AUDIO_BYTES) -> bool:
+    p = Path(path)
+    if not p.is_file():
         return False
-    if path.suffix.lower() not in _AUDIO_EXTENSIONS:
+    if p.suffix.lower() not in _AUDIO_EXTENSIONS:
         return False
-    if _is_git_lfs_pointer(path):
+    if is_git_lfs_pointer(p):
         return False
     try:
-        if path.stat().st_size < _MIN_AUDIO_BYTES:
+        if p.stat().st_size < min_bytes:
             return False
     except OSError:
         return False
     return True
 
 
+_is_usable_audio_file = is_usable_audio_file
+
+
 @dataclass
 class MediaAssetsStatus:
     root: Path
@@ -109,6 +117,12 @@ def _env_dict(env: dict[str, str] | None) -> dict[str, str]:
     return env if env is not None else dict(os.environ)
 
 
+def _media_assets_bundle_url(env: dict[str, str] | None = None) -> str:
+    env_map = _env_dict(env)
+    override = (env_map.get("MEDIA_ASSETS_BUNDLE_URL") or "").strip()
+    return override or MEDIA_ASSETS_BUNDLE_URL
+
+
 def _resolve_jiangchang_data_root(
     data_root: str | Path | None = None,
     env: dict[str, str] | None = None,
@@ -474,12 +488,16 @@ def _try_download_via_zip(
     shared: Path,
     target: Path,
     warnings: list[str],
+    *,
+    env: dict[str, str] | None = None,
+    url: str | None = None,
 ) -> bool:
     download_root = _download_dir(shared)
     download_root.mkdir(parents=True, exist_ok=True)
     zip_path = download_root / "media-assets.zip"
     extracted = download_root / "extracted"
     staging = download_root / "staging"
+    bundle_url = url or _media_assets_bundle_url(env)
 
     try:
         if staging.exists():
@@ -487,7 +505,7 @@ def _try_download_via_zip(
         if extracted.exists():
             shutil.rmtree(extracted, ignore_errors=True)
 
-        _download_zip(MEDIA_ASSETS_ZIP_URL, zip_path)
+        _download_zip(bundle_url, zip_path)
         _extract_zip(zip_path, extracted)
 
         found = _find_media_assets_root_in_tree(extracted)
@@ -565,10 +583,15 @@ def _needs_media_repo_content(status: MediaAssetsStatus) -> bool:
     )
 
 
-def _maybe_repair_music_content(root: Path, status: MediaAssetsStatus) -> MediaAssetsStatus:
+def _maybe_repair_music_content(
+    root: Path,
+    status: MediaAssetsStatus,
+    *,
+    env: dict[str, str] | None = None,
+) -> MediaAssetsStatus:
     if not _needs_music_content_repair(status):
         return status
-    if _media_assets_root_overridden(None):
+    if _media_assets_root_overridden(env):
         return status
 
     warnings: list[str] = []
@@ -581,7 +604,7 @@ def _maybe_repair_music_content(root: Path, status: MediaAssetsStatus) -> MediaA
             return _maybe_ensure_ffmpeg_tools(root, refreshed)
 
     shared = _shared_parent(root)
-    if _try_download_via_zip(shared, root, warnings):
+    if _try_download_via_zip(shared, root, warnings, env=env):
         refreshed = _inspect_media_assets(root, source="zip")
         for warning in warnings:
             if warning not in refreshed.warnings:
@@ -631,12 +654,13 @@ def ensure_media_assets(
     shared.mkdir(parents=True, exist_ok=True)
     warnings: list[str] = []
 
-    if _try_download_via_zip(shared, root, warnings):
+    if _try_download_via_zip(shared, root, warnings, env=env_map):
         return _maybe_ensure_ffmpeg_tools(
             root,
             _maybe_repair_music_content(
                 root,
                 _inspect_media_assets(root, source="zip"),
+                env=env_map,
             ),
         )
 
@@ -650,6 +674,7 @@ def ensure_media_assets(
                     root,
                     source="git" if _is_git_repo(root) else "local",
                 ),
+                env=env_map,
             ),
         )
 
@@ -657,7 +682,7 @@ def ensure_media_assets(
     for warning in warnings:
         if warning not in final.warnings:
             final.warnings.append(warning)
-    repaired = _maybe_repair_music_content(root, final)
+    repaired = _maybe_repair_music_content(root, final, env=env_map)
     for warning in warnings:
         if warning not in repaired.warnings:
             repaired.warnings.append(warning)
@@ -706,6 +731,46 @@ def resolve_music_dir(
     return status.music_dir
 
 
+def probe_background_music(
+    root: str | Path | None = None,
+    *,
+    env: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    """只读探测背景音乐目录，不触发 media-assets 下载。"""
+    env_map = _env_dict(dict(env) if env is not None else None)
+    if root is not None:
+        music_dir = Path(root) / "music"
+        if not music_dir.is_dir():
+            music_dir = Path(root) if Path(root).is_dir() else None
+    else:
+        data_root = (env_map.get("JIANGCHANG_DATA_ROOT") or env_map.get("CLAW_DATA_ROOT") or "").strip()
+        assets_root = resolve_media_assets_root(data_root or None, env_map)
+        status = _inspect_media_assets(assets_root, source="local")
+        music_dir = status.music_dir
+
+    music_root = str(music_dir) if music_dir is not None else None
+    if music_dir is None or not music_dir.is_dir():
+        return {
+            "music_root": music_root,
+            "mp3_count": 0,
+            "usable_count": 0,
+            "sample_path": None,
+            "issue": "music_dir_missing",
+        }
+
+    mp3_files = [path for path in music_dir.rglob("*.mp3") if path.is_file()]
+    usable = [path for path in music_dir.rglob("*") if is_usable_audio_file(path)]
+    issue = _music_content_issue(music_dir)
+    sample = str(sorted(usable, key=lambda p: str(p).lower())[0]) if usable else None
+    return {
+        "music_root": music_root,
+        "mp3_count": len(mp3_files),
+        "usable_count": len(usable),
+        "sample_path": sample,
+        "issue": issue,
+    }
+
+
 def background_music_issue(
     data_root: str | Path | None = None,
     env: dict[str, str] | None = None,

src/jiangchang_skill_core/rpa/artifacts.py

@@ -5,10 +5,11 @@ from __future__ import annotations
 import os
 from datetime import datetime
 
+from .. import config
+
 
 def _artifacts_enabled() -> bool:
-    v = (os.environ.get("OPENCLAW_ARTIFACTS_ON_FAILURE") or "1").strip().lower()
-    return v not in ("0", "false", "no", "off")
+    return config.get_bool("OPENCLAW_ARTIFACTS_ON_FAILURE", default=True)
 
 
 def artifact_path(data_dir: str, batch_id: str, tag: str, ext: str = "png") -> str:

src/jiangchang_skill_core/rpa/browser.py

@@ -2,9 +2,9 @@
 
 from __future__ import annotations
 
-import os
 from typing import TYPE_CHECKING
 
+from .. import config
 from ..runtime_env import find_chrome_executable
 from .stealth import (
     STEALTH_INIT_SCRIPT,
@@ -31,8 +31,7 @@ async def launch_persistent_browser(
     录屏由 RpaVideoSession（ffmpeg）负责，本函数不向 Playwright 传递任何录屏参数。
     """
     if headless is None:
-        v = (os.environ.get("OPENCLAW_BROWSER_HEADLESS") or "0").strip().lower()
-        headless = v in ("1", "true", "yes", "on")
+        headless = config.get_bool("OPENCLAW_BROWSER_HEADLESS", default=False)
 
     chrome = executable_path or find_chrome_executable()
     if not chrome:

src/jiangchang_skill_core/rpa/stealth.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-import os
+from .. import config
 
 STEALTH_INIT_SCRIPT = """
 (() => {
@@ -48,8 +48,7 @@ STEALTH_INIT_SCRIPT = """
 
 
 def stealth_enabled() -> bool:
-    v = (os.environ.get("OPENCLAW_PLAYWRIGHT_STEALTH") or "1").strip().lower()
-    return v not in ("0", "false", "no", "off")
+    return config.get_bool("OPENCLAW_PLAYWRIGHT_STEALTH", default=True)
 
 
 def persistent_context_launch_parts(

src/jiangchang_skill_core/rpa/video_session.py

@@ -1,9 +1,14 @@
-"""RPA 运行录屏会话：ffmpeg 桌面录制 → 字幕 + 背景音乐 → 最终 MP4。"""
+"""RPA 运行录屏会话：ffmpeg 桌面录制 → 字幕 + 旁白 + 背景音乐 → 最终 MP4。
+
+背景音乐默认循环铺满录屏时长并在结尾淡出；旁白使用 Windows 本地 SAPI 合成，
+失败时静默降级，不影响视频生成。Skill 无需额外配置。
+"""
 
 from __future__ import annotations
 
 import asyncio
 import os
+import re
 import subprocess
 import sys
 import time
@@ -18,6 +23,7 @@ from ..media_assets import (
     ensure_media_assets,
     pick_background_music,
     resolve_ffmpeg,
+    resolve_ffprobe,
 )
 
 _JIANGCHANG_SUBTITLE_STYLE = (
@@ -28,6 +34,54 @@ _JIANGCHANG_SUBTITLE_STYLE = (
 
 _CAPTURE_FRAMERATE = 15
 
+# 背景音乐循环 + 结尾淡出（默认策略，非 env 配置）
+_MUSIC_VOLUME = 0.12
+_VOICE_VOLUME = 1.0
+_MUSIC_FADE_OUT_SECONDS = 3.0
+_MIN_MUSIC_FADE_OUT_SECONDS = 1.0
+_SHORT_VIDEO_FADE_RATIO = 0.25
+
+_VOICEOVER_MAX_CHARS = 60
+_VOICEOVER_DEDUP_SECONDS = 10.0
+_VOICEOVER_MIN_GAP_SECONDS = 2.0
+
+_INTRO_BUFFER_SECONDS = 5.0
+_INTRO_STABILIZE_SECONDS = 1.0
+_OUTRO_BUFFER_SECONDS = 5.0
+
+_VOICEOVER_SKIP_SUBSTRINGS = (
+    "等待 1-5s",
+    "跳过重复",
+    "写入联系人库",
+    "探针模式",
+    "异常",
+    "失败",
+)
+
+_VOICEOVER_IMPORTANT_SUBSTRINGS = (
+    "开始",
+    "打开",
+    "启动",
+    "定位",
+    "输入",
+    "点击",
+    "搜索",
+    "等待搜索结果",
+    "检查登录状态",
+    "处理验证码",
+    "等待人工验证",
+    "解析",
+    "提取",
+    "采集完成",
+    "部分完成",
+    "完成",
+)
+
+# 明显技术日志：时间戳前缀、纯数字进度等
+_TECH_LOG_RE = re.compile(
+    r"^\d{4}-\d{2}-\d{2}|^\[\w+\]|^DEBUG:|^INFO:|^WARN:|^ERROR:"
+)
+
 
 def _record_video_enabled() -> bool:
     return config.get_bool("OPENCLAW_RECORD_VIDEO", default=False)
@@ -41,6 +95,68 @@ def _resolve_ffmpeg_exe() -> Optional[Path]:
     return path if path.is_file() else None
 
 
+def _resolve_ffprobe_exe() -> Optional[Path]:
+    """定位 ffprobe；优先 media_assets bundle，否则尝试 ffmpeg 同目录。"""
+    ffprobe = resolve_ffprobe()
+    if ffprobe is not None:
+        path = Path(ffprobe)
+        if path.is_file():
+            return path
+    ffmpeg = _resolve_ffmpeg_exe()
+    if ffmpeg is not None:
+        sibling = ffmpeg.parent / ("ffprobe.exe" if sys.platform == "win32" else "ffprobe")
+        if sibling.is_file():
+            return sibling
+    return None
+
+
+def _probe_media_duration_seconds(
+    ffprobe_exe: Optional[Path], media_path: Path
+) -> Optional[float]:
+    if ffprobe_exe is None or not media_path.is_file():
+        return None
+    try:
+        result = subprocess.run(
+            [
+                str(ffprobe_exe),
+                "-v",
+                "error",
+                "-show_entries",
+                "format=duration",
+                "-of",
+                "default=nk=1:nw=1",
+                str(media_path),
+            ],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=30,
+        )
+        if result.returncode != 0:
+            return None
+        raw = (result.stdout or "").strip()
+        if not raw:
+            return None
+        value = float(raw)
+        return value if value > 0 else None
+    except Exception:
+        return None
+
+
+def _music_fade_params(
+    duration_seconds: Optional[float],
+) -> tuple[Optional[float], Optional[float]]:
+    if duration_seconds is None or duration_seconds <= 0:
+        return (None, None)
+    fade = min(
+        _MUSIC_FADE_OUT_SECONDS,
+        max(_MIN_MUSIC_FADE_OUT_SECONDS, duration_seconds * _SHORT_VIDEO_FADE_RATIO),
+    )
+    fade_start = max(0.0, duration_seconds - fade)
+    return (fade_start, fade)
+
+
 def _resolve_music_file(warnings: List[str]) -> Optional[Path]:
     music = pick_background_music()
     if music is not None:
@@ -59,6 +175,183 @@ class _StepEntry:
     duration: float = 4.0
 
 
+@dataclass
+class _VoiceClip:
+    path: Path
+    delay_ms: int
+
+
+def _voiceover_text_for_step(text: str) -> Optional[str]:
+    """过滤适合朗读的步骤文本；噪音/技术日志返回 None。"""
+    cleaned = (text or "").strip()
+    if not cleaned:
+        return None
+    if _TECH_LOG_RE.search(cleaned):
+        return None
+    for skip in _VOICEOVER_SKIP_SUBSTRINGS:
+        if skip in cleaned:
+            return None
+    if len(cleaned) > _VOICEOVER_MAX_CHARS:
+        cleaned = cleaned[:_VOICEOVER_MAX_CHARS]
+    return cleaned
+
+
+def _is_important_voiceover(text: str) -> bool:
+    for important in _VOICEOVER_IMPORTANT_SUBSTRINGS:
+        if important in text:
+            return True
+    return False
+
+
+def _select_voiceover_clips(
+    entries: List[_StepEntry],
+) -> List[tuple[_StepEntry, str]]:
+    """按时间排序，去重并保证旁白间隔；关键动作可绕过最小间隔。"""
+    result: List[tuple[_StepEntry, str]] = []
+    last_text_at: Dict[str, float] = {}
+    last_spoken_at = -_VOICEOVER_MIN_GAP_SECONDS
+
+    for entry in sorted(entries, key=lambda e: e.start):
+        spoken = _voiceover_text_for_step(entry.text)
+        if not spoken:
+            continue
+        prev = last_text_at.get(spoken)
+        if prev is not None and entry.start - prev < _VOICEOVER_DEDUP_SECONDS:
+            continue
+        if (
+            not _is_important_voiceover(spoken)
+            and entry.start - last_spoken_at < _VOICEOVER_MIN_GAP_SECONDS
+        ):
+            continue
+        last_text_at[spoken] = entry.start
+        last_spoken_at = entry.start
+        result.append((entry, spoken))
+    return result
+
+
+def _tts_available() -> bool:
+    return sys.platform == "win32"
+
+
+def _sapi_synthesize_wav(text: str, output_wav: Path) -> bool:
+    if not _tts_available():
+        return False
+    output_wav.parent.mkdir(parents=True, exist_ok=True)
+    out_str = str(output_wav.resolve()).replace("'", "''")
+    text_esc = text.replace("'", "''")
+    ps_script = (
+        "Add-Type -AssemblyName System.Speech; "
+        "$s = New-Object System.Speech.Synthesis.SpeechSynthesizer; "
+        f"$s.SetOutputToWaveFile('{out_str}'); "
+        f"$s.Speak('{text_esc}'); "
+        "$s.Dispose()"
+    )
+    try:
+        result = subprocess.run(
+            ["powershell", "-NoProfile", "-NonInteractive", "-Command", ps_script],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=120,
+        )
+        return (
+            result.returncode == 0
+            and output_wav.is_file()
+            and output_wav.stat().st_size > 0
+        )
+    except Exception:
+        return False
+
+
+def _mix_voice_clips(
+    ffmpeg_exe: Path, clips: List[_VoiceClip], output_wav: Path
+) -> bool:
+    if not clips:
+        return False
+    output_wav.parent.mkdir(parents=True, exist_ok=True)
+
+    filter_parts: List[str] = []
+    mix_labels: List[str] = []
+    cmd_inputs: List[str] = []
+
+    for i, clip in enumerate(clips):
+        cmd_inputs.extend(["-i", str(clip.path)])
+        label = f"v{i}"
+        filter_parts.append(
+            f"[{i}:a]adelay={clip.delay_ms}|{clip.delay_ms},"
+            f"volume={_VOICE_VOLUME}[{label}]"
+        )
+        mix_labels.append(f"[{label}]")
+
+    if len(clips) == 1:
+        filter_complex = filter_parts[0].replace(f"[v0]", "[out]")
+        # single clip: relabel output
+        filter_complex = (
+            f"[0:a]adelay={clips[0].delay_ms}|{clips[0].delay_ms},"
+            f"volume={_VOICE_VOLUME}[out]"
+        )
+    else:
+        filter_complex = (
+            ";".join(filter_parts)
+            + ";"
+            + "".join(mix_labels)
+            + f"amix=inputs={len(clips)}:duration=longest:dropout_transition=0:normalize=0[out]"
+        )
+
+    cmd_tail = [
+        "-y",
+        *cmd_inputs,
+        "-filter_complex",
+        filter_complex,
+        "-map",
+        "[out]",
+        str(output_wav),
+    ]
+    ok, _ = _run_ffmpeg(ffmpeg_exe, cmd_tail)
+    return ok and output_wav.is_file()
+
+
+def _synthesize_step_voiceover(
+    entries: List[_StepEntry],
+    output_wav: Path,
+    warnings: List[str],
+    *,
+    ffmpeg_exe: Optional[Path] = None,
+) -> Optional[Path]:
+    """本地 Windows SAPI 逐条合成旁白并按步骤 start 时间对齐；失败返回 None。"""
+    if not _tts_available():
+        warnings.append("tts_unsupported_platform")
+        return None
+
+    clips_to_speak = _select_voiceover_clips(entries)
+    if not clips_to_speak:
+        return None
+
+    voice_dir = output_wav.parent
+    voice_dir.mkdir(parents=True, exist_ok=True)
+    temp_clips: List[_VoiceClip] = []
+
+    for i, (entry, spoken) in enumerate(clips_to_speak):
+        clip_path = voice_dir / f"voice_{i:03d}.wav"
+        if not _sapi_synthesize_wav(spoken, clip_path):
+            warnings.append("tts_synthesis_failed")
+            return None
+        delay_ms = max(0, int(entry.start * 1000))
+        temp_clips.append(_VoiceClip(path=clip_path, delay_ms=delay_ms))
+
+    if ffmpeg_exe is None:
+        ffmpeg_exe = _resolve_ffmpeg_exe()
+    if ffmpeg_exe is None:
+        warnings.append("tts_mix_ffmpeg_missing")
+        return None
+
+    if not _mix_voice_clips(ffmpeg_exe, temp_clips, output_wav):
+        warnings.append("tts_mix_failed")
+        return None
+    return output_wav
+
+
 def _generate_srt(entries: List[_StepEntry], output_path: str) -> None:
     MIN_DURATION = 1.0
     GAP = 0.1
@@ -117,27 +410,16 @@ def _run_ffmpeg(ffmpeg_exe: Path, cmd_tail: List[str]) -> tuple[bool, str]:
     return True, ""
 
 
-def _build_desktop_record_cmd(ffmpeg_exe: Path, capture_path: str) -> Optional[List[str]]:
-    """Windows gdigrab 全桌面录制；非 Windows 返回 None。"""
-    if sys.platform != "win32":
-        return None
-    return _ffmpeg_cmd(
-        ffmpeg_exe,
-        "-y",
-        "-f",
-        "gdigrab",
-        "-framerate",
-        str(_CAPTURE_FRAMERATE),
-        "-i",
-        "desktop",
-        "-c:v",
-        "libx264",
-        "-preset",
-        "ultrafast",
-        "-pix_fmt",
-        "yuv420p",
-        capture_path,
-    )
+def _build_music_filter(
+    audio_input_idx: int,
+    fade_start: Optional[float],
+    fade_duration: Optional[float],
+    output_label: str = "music",
+) -> str:
+    filt = f"[{audio_input_idx}:a]volume={_MUSIC_VOLUME}"
+    if fade_start is not None and fade_duration is not None:
+        filt += f",afade=t=out:st={fade_start}:d={fade_duration}"
+    return filt + f"[{output_label}]"
 
 
 def _compose_capture_mp4(
@@ -147,7 +429,8 @@ def _compose_capture_mp4(
     output_path: Path,
     *,
     music_file: Optional[Path] = None,
-    music_volume: float = 0.15,
+    voiceover_file: Optional[Path] = None,
+    warnings: Optional[List[str]] = None,
 ) -> tuple[bool, str]:
     output_path.parent.mkdir(parents=True, exist_ok=True)
     srt_esc = _escape_srt_path(str(srt_path.resolve()))
@@ -156,38 +439,77 @@ def _compose_capture_mp4(
         f":force_style='{_JIANGCHANG_SUBTITLE_STYLE}'"
     )
 
-    if music_file and music_file.is_file():
-        filter_complex = (
-            f"[0:v]{subtitle_filter}[vout];"
-            f"[1:a]volume={music_volume},apad[aout]"
+    has_music = music_file is not None and music_file.is_file()
+    has_voice = voiceover_file is not None and voiceover_file.is_file()
+
+    fade_start: Optional[float] = None
+    fade_duration: Optional[float] = None
+    if has_music:
+        ffprobe = _resolve_ffprobe_exe()
+        duration = _probe_media_duration_seconds(ffprobe, capture_path)
+        fade_start, fade_duration = _music_fade_params(duration)
+        if fade_start is None and warnings is not None:
+            warnings.append("video_duration_probe_failed_for_music_fade")
+
+    if has_music or has_voice:
+        cmd_tail: List[str] = ["-y", "-i", str(capture_path)]
+        input_idx = 1
+        filter_parts: List[str] = [f"[0:v]{subtitle_filter}[vout]"]
+        audio_labels: List[str] = []
+
+        if has_music:
+            cmd_tail.extend(["-stream_loop", "-1", "-i", str(music_file)])
+            music_label = "aout" if not has_voice else "music"
+            filter_parts.append(
+                _build_music_filter(input_idx, fade_start, fade_duration, music_label)
+            )
+            if has_voice:
+                audio_labels.append(f"[{music_label}]")
+            input_idx += 1
+
+        if has_voice:
+            cmd_tail.extend(["-i", str(voiceover_file)])
+            if has_music:
+                filter_parts.append(
+                    f"[{input_idx}:a]volume={_VOICE_VOLUME}[voice]"
+                )
+                audio_labels.append("[voice]")
+            else:
+                # voice-only：apad 补静音，避免 -shortest 按旁白长度截短视频
+                filter_parts.append(
+                    f"[{input_idx}:a]volume={_VOICE_VOLUME},apad[aout]"
+                )
+            input_idx += 1
+
+        if len(audio_labels) == 2:
+            filter_parts.append(
+                "".join(audio_labels) + "amix=inputs=2:normalize=0[aout]"
+            )
+
+        cmd_tail.extend(
+            [
+                "-filter_complex",
+                ";".join(filter_parts),
+                "-map",
+                "[vout]",
+                "-map",
+                "[aout]",
+                "-c:v",
+                "libx264",
+                "-preset",
+                "fast",
+                "-crf",
+                "23",
+                "-c:a",
+                "aac",
+                "-b:a",
+                "128k",
+                "-shortest",
+                "-pix_fmt",
+                "yuv420p",
+                str(output_path),
+            ]
         )
-        cmd_tail = [
-            "-y",
-            "-i",
-            str(capture_path),
-            "-i",
-            str(music_file),
-            "-filter_complex",
-            filter_complex,
-            "-map",
-            "[vout]",
-            "-map",
-            "[aout]",
-            "-c:v",
-            "libx264",
-            "-preset",
-            "fast",
-            "-crf",
-            "23",
-            "-c:a",
-            "aac",
-            "-b:a",
-            "128k",
-            "-shortest",
-            "-pix_fmt",
-            "yuv420p",
-            str(output_path),
-        ]
     else:
         cmd_tail = [
             "-y",
@@ -212,6 +534,29 @@ def _compose_capture_mp4(
     return _run_ffmpeg(ffmpeg_exe, cmd_tail)
 
 
+def _build_desktop_record_cmd(ffmpeg_exe: Path, capture_path: str) -> Optional[List[str]]:
+    """Windows gdigrab 全桌面录制；非 Windows 返回 None。"""
+    if sys.platform != "win32":
+        return None
+    return _ffmpeg_cmd(
+        ffmpeg_exe,
+        "-y",
+        "-f",
+        "gdigrab",
+        "-framerate",
+        str(_CAPTURE_FRAMERATE),
+        "-i",
+        "desktop",
+        "-c:v",
+        "libx264",
+        "-preset",
+        "ultrafast",
+        "-pix_fmt",
+        "yuv420p",
+        capture_path,
+    )
+
+
 class RpaVideoSession:
     """Service/RPA 层统一 ffmpeg 桌面录屏；OPENCLAW_RECORD_VIDEO=1 时启用成片流程。"""
 
@@ -222,11 +567,13 @@ class RpaVideoSession:
         skill_data_dir: str,
         batch_id: str,
         title: str = "",
+        closing_title: str = "",
     ) -> None:
         self.skill_slug = skill_slug
         self.skill_data_dir = os.path.abspath(skill_data_dir)
         self.batch_id = batch_id
         self.title = title
+        self.closing_title = closing_title
         self.enabled = _record_video_enabled()
         self.warnings: List[str] = []
         self.output_video_path: Optional[str] = None
@@ -242,12 +589,17 @@ class RpaVideoSession:
             self.skill_data_dir, "rpa-artifacts", batch_id
         )
         self._subtitles_dir = os.path.join(self._artifact_root, "subtitles")
+        self._voiceover_dir = os.path.join(self._artifact_root, "voiceover")
         self._logs_dir = os.path.join(self._artifact_root, "logs")
         self._ffmpeg_record_log_path = os.path.join(self._logs_dir, "ffmpeg-record.log")
         self._capture_path = os.path.join(self._artifact_root, "capture.mp4")
         self._srt_path = os.path.join(self._subtitles_dir, f"{self._video_stem}.srt")
+        self._voiceover_path = os.path.join(self._voiceover_dir, "voiceover.wav")
         self._planned_output = os.path.join(self._videos_dir, f"{self._video_stem}.mp4")
 
+        self._music_path: Optional[str] = None
+        self._voiceover_output: Optional[str] = None
+
         self._steps: List[_StepEntry] = []
         self._t0: Optional[float] = None
         self._ffmpeg_proc: Optional[subprocess.Popen] = None
@@ -256,6 +608,7 @@ class RpaVideoSession:
         if self.enabled:
             os.makedirs(self._videos_dir, exist_ok=True)
             os.makedirs(self._subtitles_dir, exist_ok=True)
+            os.makedirs(self._voiceover_dir, exist_ok=True)
             os.makedirs(self._logs_dir, exist_ok=True)
             os.makedirs(self._artifact_root, exist_ok=True)
 
@@ -366,19 +719,80 @@ class RpaVideoSession:
         self._close_ffmpeg_record_log()
         time.sleep(0.3)
 
+    async def _safe_add_step(self, text: str, *, duration: float = 4.0) -> None:
+        try:
+            self.add_step(text, duration=duration)
+        except Exception:
+            pass
+
     async def __aenter__(self) -> "RpaVideoSession":
         if self.enabled:
             self._t0 = time.monotonic()
-            if self.title:
-                self.add_step(self.title, duration=3.0)
             self._start_ffmpeg_capture()
+            await asyncio.sleep(_INTRO_STABILIZE_SECONDS)
+            if self.title:
+                await self._safe_add_step(self.title, duration=4.0)
+            intro_wait = _INTRO_BUFFER_SECONDS - _INTRO_STABILIZE_SECONDS
+            if intro_wait > 0:
+                await asyncio.sleep(intro_wait)
         return self
 
     async def __aexit__(self, exc_type, exc, tb) -> None:
         if self.enabled:
+            if self.closing_title:
+                await self._safe_add_step(self.closing_title, duration=4.0)
+            await asyncio.sleep(_OUTRO_BUFFER_SECONDS)
             self._stop_ffmpeg_capture()
             await self.finalize()
 
+    def _try_compose_variants(
+        self,
+        ffmpeg_exe: Path,
+        capture: Path,
+        srt_file: Path,
+        output: Path,
+        *,
+        music: Optional[Path],
+        voiceover: Optional[Path],
+        use_srt: bool,
+    ) -> tuple[bool, str]:
+        """按 music/voice 组合尝试合成，失败时逐级降级。"""
+        srt = srt_file if use_srt else Path(self._srt_path)
+        variants: List[tuple[Optional[Path], Optional[Path]]] = [
+            (music, voiceover),
+        ]
+        if music and voiceover:
+            variants.append((None, voiceover))
+        if music:
+            variants.append((music, None))
+        variants.append((None, None))
+
+        seen: set[tuple[Optional[str], Optional[str]]] = set()
+        last_err = ""
+        for m, v in variants:
+            key = (str(m) if m else None, str(v) if v else None)
+            if key in seen:
+                continue
+            seen.add(key)
+            ok, err = _compose_capture_mp4(
+                ffmpeg_exe,
+                capture,
+                srt,
+                output,
+                music_file=m,
+                voiceover_file=v,
+                warnings=self.warnings,
+            )
+            if ok:
+                return True, ""
+            last_err = err
+            if m is not None and v is not None:
+                self.warnings.append(f"ffmpeg_with_music_and_voice_failed: {err}")
+            elif m is not None:
+                self.warnings.append(f"ffmpeg_with_music_failed: {err}")
+
+        return False, last_err
+
     async def finalize(self) -> None:
         """停止录制后合成最终 MP4；失败只记 warning，不抛异常。"""
         if not self.enabled:
@@ -406,7 +820,12 @@ class RpaVideoSession:
                 self.warnings.append(f"subtitle_write_failed: {exc}")
 
             music = _resolve_music_file(self.warnings)
-            if music is None and "background_music_lfs_pointer_only" not in self.warnings and "background_music_invalid" not in self.warnings:
+            if music is not None:
+                self._music_path = str(music.resolve())
+            elif (
+                "background_music_lfs_pointer_only" not in self.warnings
+                and "background_music_invalid" not in self.warnings
+            ):
                 self.warnings.append("background_music_missing")
 
             ffmpeg_exe = _resolve_ffmpeg_exe()
@@ -415,25 +834,32 @@ class RpaVideoSession:
                 self.artifacts = self.summary()
                 return
 
+            voiceover: Optional[Path] = None
+            try:
+                vo = _synthesize_step_voiceover(
+                    entries,
+                    Path(self._voiceover_path),
+                    self.warnings,
+                    ffmpeg_exe=ffmpeg_exe,
+                )
+                if vo is not None:
+                    voiceover = vo
+                    self._voiceover_output = str(vo.resolve())
+            except Exception as exc:
+                self.warnings.append(f"tts_unexpected_error: {exc}")
+
             srt_file = Path(self._srt_path)
             use_srt = srt_file.is_file() and srt_file.stat().st_size > 0
 
-            ok, err = _compose_capture_mp4(
+            ok, err = self._try_compose_variants(
                 ffmpeg_exe,
                 capture,
-                srt_file if use_srt else Path(self._srt_path),
+                srt_file,
                 Path(self._planned_output),
-                music_file=music,
+                music=music,
+                voiceover=voiceover,
+                use_srt=use_srt,
             )
-            if not ok and music is not None:
-                self.warnings.append(f"ffmpeg_with_music_failed: {err}")
-                ok, err = _compose_capture_mp4(
-                    ffmpeg_exe,
-                    capture,
-                    srt_file if use_srt else Path(self._srt_path),
-                    Path(self._planned_output),
-                    music_file=None,
-                )
             if not ok and not use_srt:
                 ok, err = _run_ffmpeg(
                     ffmpeg_exe,
@@ -469,12 +895,28 @@ class RpaVideoSession:
             if self.enabled and self._ffmpeg_record_log_path
             else None
         )
+        audio_warnings = [
+            w
+            for w in self.warnings
+            if w.startswith(
+                (
+                    "tts_",
+                    "video_duration_probe_failed",
+                    "ffmpeg_with_music",
+                    "background_music_",
+                )
+            )
+            or w == "background_music_missing"
+        ]
         return {
             "enabled": self.enabled,
             "path": self.output_video_path,
             "capture_path": self.capture_path,
             "record_log_path": record_log,
             "warnings": list(self.warnings),
+            "voiceover_path": self._voiceover_output,
+            "music_path": self._music_path,
+            "audio_warnings": audio_warnings,
         }
 
     def to_artifact_dict(self) -> Dict[str, Any]:

src/jiangchang_skill_core/runtime_diagnostics.py

@@ -0,0 +1,343 @@
+"""共享 Runtime 诊断：health 输出与 media-assets / ffmpeg 探测。"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import logging
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+import jiangchang_skill_core
+from . import config
+from .media_assets import probe_background_music, probe_media_assets, resolve_media_assets_root
+from .runtime_env import platform_default_data_root
+
+_SHARED_CORE_HINT = (
+    "jiangchang_skill_core is loaded from the skill tree; expected the shared "
+    "jiangchang-platform-kit installed in the host Python runtime."
+)
+
+
+@dataclass(frozen=True)
+class RuntimeIssue:
+    code: str
+    message: str
+    severity: str = "warning"
+
+
+@dataclass(frozen=True)
+class RuntimeDiagnostics:
+    skill_slug: str
+    python_executable: str
+    platform_kit_version: str | None
+    platform_kit_min_version: str | None
+    platform_kit_version_ok: bool | None
+    jiangchang_skill_core_file: str | None
+
+    claw_data_root: str | None
+    jiangchang_data_root: str | None
+    resolved_data_root: str | None
+
+    media_assets_root: str | None
+    ffmpeg_available: bool
+    ffmpeg_path: str | None
+
+    background_music_mp3_count: int
+    background_music_usable_count: int
+    background_music_issue: str | None
+    background_music_sample_path: str | None
+
+    record_video_enabled: bool
+    issues: tuple[RuntimeIssue, ...]
+
+    @property
+    def has_fatal_issues(self) -> bool:
+        return any(issue.severity == "error" for issue in self.issues)
+
+    def issue_codes(self) -> list[str]:
+        return [issue.code for issue in self.issues]
+
+
+def _env_dict(env: Mapping[str, str] | None) -> dict[str, str]:
+    return dict(env) if env is not None else dict(os.environ)
+
+
+def _resolve_data_root(env: Mapping[str, str]) -> str:
+    root = (env.get("CLAW_DATA_ROOT") or env.get("JIANGCHANG_DATA_ROOT") or "").strip()
+    if root:
+        return root
+    return platform_default_data_root()
+
+
+def _parse_version(version: str) -> tuple[int, int, int, int]:
+    """Parse major.minor.patch[.postN] into (major, minor, patch, post)."""
+    text = version.strip()
+    post = 0
+    if ".post" in text:
+        base, _, post_part = text.partition(".post")
+        post_digits = ""
+        for ch in post_part:
+            if ch.isdigit():
+                post_digits += ch
+            else:
+                break
+        post = int(post_digits) if post_digits else 0
+        text = base
+
+    parts: list[int] = []
+    for piece in text.split("."):
+        digits = ""
+        for ch in piece:
+            if ch.isdigit():
+                digits += ch
+            else:
+                break
+        if digits:
+            parts.append(int(digits))
+
+    while len(parts) < 3:
+        parts.append(0)
+
+    return parts[0], parts[1], parts[2], post
+
+
+def version_ge(installed: str, required: str) -> bool:
+    """Compare semver-like versions without external deps (supports legacy .postN)."""
+    return _parse_version(installed) >= _parse_version(required)
+
+
+def _path_under(parent: str | Path, child: str | Path) -> bool:
+    try:
+        parent_path = Path(parent).resolve()
+        child_path = Path(child).resolve()
+        if sys.platform == "win32":
+            parent_norm = os.path.normcase(str(parent_path))
+            child_norm = os.path.normcase(str(child_path))
+            common = os.path.commonpath([parent_norm, child_norm])
+            return common == parent_norm
+        return os.path.commonpath([str(parent_path), str(child_path)]) == str(parent_path)
+    except (OSError, ValueError):
+        return False
+
+
+def is_jiangchang_skill_core_from_skill_tree(
+    *,
+    skill_root: str | Path,
+    core_file: str | Path | None = None,
+) -> bool:
+    """Return True when jiangchang_skill_core is loaded from inside skill_root."""
+    try:
+        root = Path(skill_root)
+        if not str(root).strip():
+            return False
+        core = Path(core_file) if core_file is not None else Path(jiangchang_skill_core.__file__)
+        return _path_under(root, core)
+    except (OSError, TypeError, ValueError):
+        return False
+
+
+def _platform_kit_version() -> str | None:
+    try:
+        return importlib.metadata.version("jiangchang-platform-kit")
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def _bool_from_env(env: Mapping[str, str], key: str, default: bool = False) -> bool:
+    val = env.get(key)
+    if val is None or val == "":
+        return default
+    return str(val).strip().lower() in ("1", "true", "yes", "on")
+
+
+def collect_runtime_diagnostics(
+    *,
+    skill_slug: str,
+    platform_kit_min_version: str | None = None,
+    skill_root: str | Path | None = None,
+    record_video: bool | None = None,
+    env: Mapping[str, str] | None = None,
+) -> RuntimeDiagnostics:
+    env_map = _env_dict(env)
+    issues: list[RuntimeIssue] = []
+
+    claw_data_root = env_map.get("CLAW_DATA_ROOT")
+    jiangchang_data_root = env_map.get("JIANGCHANG_DATA_ROOT")
+    resolved_data_root = _resolve_data_root(env_map)
+
+    media_root_path = resolve_media_assets_root(resolved_data_root, env_map)
+    media_status = probe_media_assets(resolved_data_root, env_map)
+    ffmpeg_path_obj = media_status.ffmpeg_path
+    ffmpeg_ok = ffmpeg_path_obj is not None and ffmpeg_path_obj.is_file()
+
+    music_probe = probe_background_music(media_root_path, env=env_map)
+    mp3_count = int(music_probe["mp3_count"])
+    usable_count = int(music_probe["usable_count"])
+    music_issue = music_probe.get("issue")
+    music_sample = music_probe.get("sample_path")
+
+    if music_issue is None and not media_status.music_ready and media_status.warnings:
+        for warning in media_status.warnings:
+            if warning.startswith("background_music") or warning == "music_dir_missing":
+                music_issue = warning
+                break
+
+    platform_version = _platform_kit_version()
+    platform_ok: bool | None
+    if platform_kit_min_version is None:
+        platform_ok = None
+    elif platform_version is None:
+        platform_ok = False
+    else:
+        platform_ok = version_ge(platform_version, platform_kit_min_version)
+
+    if platform_version is None:
+        issues.append(
+            RuntimeIssue(
+                code="platform_kit_not_installed",
+                message="jiangchang-platform-kit package metadata not found",
+                severity="error",
+            )
+        )
+    elif platform_kit_min_version is not None and not platform_ok:
+        issues.append(
+            RuntimeIssue(
+                code="platform_kit_version_low",
+                message=(
+                    f"jiangchang-platform-kit version {platform_version} "
+                    f"is below required {platform_kit_min_version}"
+                ),
+                severity="error",
+            )
+        )
+
+    core_file: str | None
+    try:
+        core_file = os.path.abspath(jiangchang_skill_core.__file__)
+    except (OSError, TypeError, ValueError):
+        core_file = None
+
+    if skill_root is not None and core_file is not None:
+        if is_jiangchang_skill_core_from_skill_tree(skill_root=skill_root, core_file=core_file):
+            issues.append(
+                RuntimeIssue(
+                    code="jiangchang_skill_core_loaded_from_skill_tree",
+                    message=_SHARED_CORE_HINT,
+                    severity="warning",
+                )
+            )
+
+    if record_video is None:
+        if env is not None:
+            record_video_enabled = _bool_from_env(env_map, "OPENCLAW_RECORD_VIDEO", False)
+        else:
+            record_video_enabled = config.get_bool("OPENCLAW_RECORD_VIDEO", default=False)
+    else:
+        record_video_enabled = record_video
+
+    if not ffmpeg_ok:
+        severity = "warning"
+        message = "ffmpeg not available"
+        if record_video_enabled:
+            message = "OPENCLAW_RECORD_VIDEO enabled but ffmpeg is not available"
+        issues.append(
+            RuntimeIssue(
+                code="ffmpeg_unavailable",
+                message=message,
+                severity=severity,
+            )
+        )
+
+    if record_video_enabled and music_issue:
+        issues.append(
+            RuntimeIssue(
+                code="background_music_unavailable",
+                message=f"background music unavailable: {music_issue}",
+                severity="warning",
+            )
+        )
+
+    return RuntimeDiagnostics(
+        skill_slug=skill_slug,
+        python_executable=sys.executable,
+        platform_kit_version=platform_version,
+        platform_kit_min_version=platform_kit_min_version,
+        platform_kit_version_ok=platform_ok,
+        jiangchang_skill_core_file=core_file,
+        claw_data_root=claw_data_root,
+        jiangchang_data_root=jiangchang_data_root,
+        resolved_data_root=resolved_data_root,
+        media_assets_root=str(media_root_path),
+        ffmpeg_available=ffmpeg_ok,
+        ffmpeg_path=str(ffmpeg_path_obj) if ffmpeg_path_obj else None,
+        background_music_mp3_count=mp3_count,
+        background_music_usable_count=usable_count,
+        background_music_issue=str(music_issue) if music_issue else None,
+        background_music_sample_path=str(music_sample) if music_sample else None,
+        record_video_enabled=record_video_enabled,
+        issues=tuple(issues),
+    )
+
+
+def format_runtime_health_lines(diagnostics: RuntimeDiagnostics) -> list[str]:
+    lines = [
+        f"skill_slug: {diagnostics.skill_slug}",
+        f"python_executable: {diagnostics.python_executable}",
+        f"platform_kit_version: {diagnostics.platform_kit_version or ''}",
+        f"platform_kit_min_version: {diagnostics.platform_kit_min_version or ''}",
+        f"platform_kit_version_ok: {diagnostics.platform_kit_version_ok}",
+        f"jiangchang_skill_core_file: {diagnostics.jiangchang_skill_core_file or ''}",
+        f"CLAW_DATA_ROOT: {diagnostics.claw_data_root or ''}",
+        f"JIANGCHANG_DATA_ROOT: {diagnostics.jiangchang_data_root or ''}",
+        f"resolved_data_root: {diagnostics.resolved_data_root or ''}",
+        f"media_assets_root: {diagnostics.media_assets_root or ''}",
+        f"ffmpeg_available: {diagnostics.ffmpeg_available}",
+        f"ffmpeg_path: {diagnostics.ffmpeg_path or ''}",
+        f"background_music_mp3_count: {diagnostics.background_music_mp3_count}",
+        f"background_music_usable_count: {diagnostics.background_music_usable_count}",
+        f"background_music_issue: {diagnostics.background_music_issue or ''}",
+        f"background_music_sample_path: {diagnostics.background_music_sample_path or ''}",
+        f"record_video_enabled: {diagnostics.record_video_enabled}",
+    ]
+    for issue in diagnostics.issues:
+        lines.append(f"runtime_issue[{issue.severity}]: {issue.code} - {issue.message}")
+    return lines
+
+
+def runtime_diagnostics_dict(diagnostics: RuntimeDiagnostics) -> dict[str, Any]:
+    return {
+        "skill_slug": diagnostics.skill_slug,
+        "python_executable": diagnostics.python_executable,
+        "platform_kit_version": diagnostics.platform_kit_version,
+        "platform_kit_min_version": diagnostics.platform_kit_min_version,
+        "platform_kit_version_ok": diagnostics.platform_kit_version_ok,
+        "jiangchang_skill_core_file": diagnostics.jiangchang_skill_core_file,
+        "CLAW_DATA_ROOT": diagnostics.claw_data_root,
+        "JIANGCHANG_DATA_ROOT": diagnostics.jiangchang_data_root,
+        "resolved_data_root": diagnostics.resolved_data_root,
+        "media_assets_root": diagnostics.media_assets_root,
+        "ffmpeg_available": diagnostics.ffmpeg_available,
+        "ffmpeg_path": diagnostics.ffmpeg_path,
+        "background_music_mp3_count": diagnostics.background_music_mp3_count,
+        "background_music_usable_count": diagnostics.background_music_usable_count,
+        "background_music_issue": diagnostics.background_music_issue,
+        "background_music_sample_path": diagnostics.background_music_sample_path,
+        "record_video_enabled": diagnostics.record_video_enabled,
+        "runtime_issues": [
+            {"code": issue.code, "message": issue.message, "severity": issue.severity}
+            for issue in diagnostics.issues
+        ],
+    }
+
+
+def log_runtime_diagnostics(
+    diagnostics: RuntimeDiagnostics,
+    logger: logging.Logger | None = None,
+    level: int = logging.INFO,
+) -> None:
+    log = logger or logging.getLogger("jiangchang_skill_core.runtime_diagnostics")
+    for line in format_runtime_health_lines(diagnostics):
+        log.log(level, line)

tests/test_media_assets.py

@@ -15,7 +15,7 @@ from jiangchang_skill_core import media_assets as ma
 
 def _make_complete_assets(root: Path, *, with_ffmpeg: bool = True, with_ffprobe: bool = True) -> None:
     (root / "music" / "calm").mkdir(parents=True)
-    (root / "music" / "calm" / "track.mp3").write_bytes(b"x" * 256)
+    (root / "music" / "calm" / "track.mp3").write_bytes(b"x" * 1024)
     (root / "fonts").mkdir(parents=True)
     (root / "watermark").mkdir(parents=True)
     bin_key = ma._platform_bin_key()
@@ -58,6 +58,56 @@ def _install_tools_from_manifest(root: Path, warnings: list[str]) -> bool:
     return True
 
 
+def _build_archive_zip(dest: Path, inner_name: str) -> None:
+    manifest = _sample_manifest()
+    with zipfile.ZipFile(dest, "w") as zf:
+        zf.writestr(f"{inner_name}/README.md", "# media-assets\n")
+        zf.writestr(f"{inner_name}/manifest.json", json.dumps(manifest, ensure_ascii=False))
+        zf.writestr(f"{inner_name}/music/calm/track.mp3", b"x" * 1024)
+        zf.writestr(f"{inner_name}/fonts/.keep", "")
+        zf.writestr(f"{inner_name}/watermark/.keep", "")
+
+
+def test_default_bundle_url_is_release() -> None:
+    url = ma._media_assets_bundle_url()
+    assert url == ma.MEDIA_ASSETS_BUNDLE_URL
+    assert url.endswith("/releases/download/vlatest/media-assets.zip")
+    assert "/archive/main.zip" not in url
+
+
+def test_bundle_url_env_override() -> None:
+    override = "https://example.com/media-assets.zip"
+    assert ma._media_assets_bundle_url(env={"MEDIA_ASSETS_BUNDLE_URL": override}) == override
+
+
+def test_zip_download_uses_bundle_url_override(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    data_root = tmp_path / "data"
+    shared = data_root / "shared"
+    target = shared / "media-assets"
+    archive = tmp_path / "media-assets.zip"
+    override = "https://example.com/media-assets.zip"
+
+    _build_archive_zip(archive, "media-assets")
+    captured_urls: list[str] = []
+
+    def _fake_download(url: str, dest: Path) -> None:
+        captured_urls.append(url)
+        dest.write_bytes(archive.read_bytes())
+
+    monkeypatch.setattr(ma, "_download_zip", _fake_download)
+    monkeypatch.setattr(ma, "_find_git_executable", lambda: None)
+    monkeypatch.setattr(ma, "_try_download_ffmpeg_tools", _install_tools_from_manifest)
+
+    env = {
+        "JIANGCHANG_DATA_ROOT": str(data_root),
+        "MEDIA_ASSETS_BUNDLE_URL": override,
+    }
+    status = ma.ensure_media_assets(env=env)
+    assert captured_urls == [override]
+    assert target.is_dir()
+    assert status.ready is True
+
+
 def test_media_assets_root_env_priority(tmp_path: Path) -> None:
     custom = tmp_path / "custom-media"
     custom.mkdir()
@@ -118,9 +168,9 @@ def test_pick_background_music_stable_first(tmp_path: Path, monkeypatch: pytest.
     root = tmp_path / "data" / "shared" / "media-assets"
     _make_complete_assets(root)
     music = root / "music"
-    (music / "b-upbeat.mp3").write_bytes(b"x" * 256)
-    (music / "calm" / "a-calm.mp3").write_bytes(b"x" * 256)
-    (music / "z-last.wav").write_bytes(b"x" * 256)
+    (music / "b-upbeat.mp3").write_bytes(b"x" * 1024)
+    (music / "calm" / "a-calm.mp3").write_bytes(b"x" * 1024)
+    (music / "z-last.wav").write_bytes(b"x" * 1024)
 
     monkeypatch.setattr(
         ma,
@@ -132,23 +182,18 @@ def test_pick_background_music_stable_first(tmp_path: Path, monkeypatch: pytest.
     assert picked == music / "b-upbeat.mp3"
 
 
-def _build_archive_zip(dest: Path, inner_name: str) -> None:
-    manifest = _sample_manifest()
-    with zipfile.ZipFile(dest, "w") as zf:
-        zf.writestr(f"{inner_name}/README.md", "# media-assets\n")
-        zf.writestr(f"{inner_name}/manifest.json", json.dumps(manifest, ensure_ascii=False))
-        zf.writestr(f"{inner_name}/music/calm/track.mp3", b"x" * 256)
-        zf.writestr(f"{inner_name}/fonts/.keep", "")
-        zf.writestr(f"{inner_name}/watermark/.keep", "")
-
-
-def test_zip_wrapper_layout_detected(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+@pytest.mark.parametrize("inner_name", ["media-assets", "media-assets-main"])
+def test_zip_wrapper_layout_detected(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    inner_name: str,
+) -> None:
     data_root = tmp_path / "data"
     shared = data_root / "shared"
     target = shared / "media-assets"
     archive = tmp_path / "media-assets.zip"
 
-    _build_archive_zip(archive, "media-assets-main")
+    _build_archive_zip(archive, inner_name)
 
     def _fake_download(url: str, dest: Path) -> None:
         dest.write_bytes(archive.read_bytes())
@@ -226,12 +271,33 @@ def test_probe_media_assets_does_not_download(tmp_path: Path, monkeypatch: pytes
     assert status.ffmpeg_path is None
 
 
+def test_lfs_pointer_warning_in_probe_and_ensure(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    root = tmp_path / "data" / "shared" / "media-assets"
+    _make_complete_assets(root)
+    music = root / "music"
+    (music / "calm" / "track.mp3").unlink()
+    (music / "lfs-only.mp3").write_text(
+        "version https://git-lfs.github.com/spec/v1\noid sha256:abc\nsize 123\n"
+    )
+
+    monkeypatch.setattr(ma, "_try_download_via_zip", lambda *a, **k: False)
+    monkeypatch.setattr(ma, "_try_download_via_git", lambda *a, **k: False)
+
+    probed = ma.probe_media_assets(env={"JIANGCHANG_DATA_ROOT": str(tmp_path / "data")})
+    assert "background_music_lfs_pointer_only" in probed.warnings
+    assert probed.music_ready is False
+
+    ensured = ma.ensure_media_assets(env={"JIANGCHANG_DATA_ROOT": str(tmp_path / "data")})
+    assert "background_music_lfs_pointer_only" in ensured.warnings
+    assert ensured.ready is False
+
+
 def test_pick_background_music_skips_lfs_pointer(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
     root = tmp_path / "data" / "shared" / "media-assets"
     _make_complete_assets(root, with_ffmpeg=True, with_ffprobe=True)
     music = root / "music"
     (music / "calm" / "track.mp3").unlink()
-    (music / "real.mp3").write_bytes(b"x" * 256)
+    (music / "real.mp3").write_bytes(b"x" * 1024)
     lfs = music / "lfs-only.mp3"
     lfs.write_text("version https://git-lfs.github.com/spec/v1\noid sha256:abc\nsize 123\n")
 
@@ -324,7 +390,7 @@ def test_video_finalize_without_music_fallback(tmp_path: Path, monkeypatch: pyte
 def test_manifest_ffmpeg_download(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
     root = tmp_path / "data" / "shared" / "media-assets"
     (root / "music" / "calm").mkdir(parents=True)
-    (root / "music" / "calm" / "track.mp3").write_bytes(b"x" * 256)
+    (root / "music" / "calm" / "track.mp3").write_bytes(b"x" * 1024)
     (root / "fonts").mkdir(parents=True)
     (root / "watermark").mkdir(parents=True)
     (root / "manifest.json").write_text(
@@ -340,3 +406,32 @@ def test_manifest_ffmpeg_download(tmp_path: Path, monkeypatch: pytest.MonkeyPatc
     assert status.ready is True
     assert status.ffmpeg_path is not None
     assert status.ffprobe_path is not None
+
+
+def test_is_usable_audio_file_rejects_small_and_lfs(tmp_path: Path) -> None:
+    small = tmp_path / "small.mp3"
+    small.write_bytes(b"x" * 512)
+    assert ma.is_usable_audio_file(small) is False
+
+    ok = tmp_path / "ok.mp3"
+    ok.write_bytes(b"x" * 1024)
+    assert ma.is_usable_audio_file(ok) is True
+
+    lfs = tmp_path / "lfs.mp3"
+    lfs.write_text("version https://git-lfs.github.com/spec/v1\noid sha256:abc\nsize 123\n")
+    assert ma.is_usable_audio_file(lfs) is False
+    assert ma.is_git_lfs_pointer(lfs) is True
+
+
+def test_probe_background_music_structure(tmp_path: Path) -> None:
+    root = tmp_path / "media-assets"
+    music = root / "music" / "calm"
+    music.mkdir(parents=True)
+    (music / "track.mp3").write_bytes(b"x" * 1024)
+
+    probe = ma.probe_background_music(root)
+    assert probe["music_root"] == str(root / "music")
+    assert probe["mp3_count"] == 1
+    assert probe["usable_count"] == 1
+    assert probe["issue"] is None
+    assert probe["sample_path"] == str(music / "track.mp3")

tests/test_release_workflow.py

@@ -1,4 +1,4 @@
-"""Text-level checks that reusable-release-skill packages .env.example at package root."""
+"""Text-level checks for release-related GitHub Actions workflows."""
 
 from __future__ import annotations
 
@@ -8,17 +8,52 @@ import re
 import pytest
 
 _REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
-_WORKFLOW_PATH = os.path.join(
+_SKILL_WORKFLOW_PATH = os.path.join(
     _REPO_ROOT, ".github", "workflows", "reusable-release-skill.yaml"
 )
+_PUBLISH_WORKFLOW_PATH = os.path.join(
+    _REPO_ROOT, ".github", "workflows", "publish.yml"
+)
 
 
 @pytest.fixture(scope="module")
 def workflow_text() -> str:
-    with open(_WORKFLOW_PATH, encoding="utf-8") as f:
+    with open(_SKILL_WORKFLOW_PATH, encoding="utf-8") as f:
         return f.read()
 
 
+@pytest.fixture(scope="module")
+def publish_workflow_text() -> str:
+    with open(_PUBLISH_WORKFLOW_PATH, encoding="utf-8") as f:
+        return f.read()
+
+
+def test_workflow_packages_readme_at_root(workflow_text: str) -> None:
+    assert "readme_src = os.path.abspath('README.md')" in workflow_text
+    assert "readme_dst = os.path.join(PACKAGE, 'README.md')" in workflow_text
+    assert "Copied README.md" in workflow_text
+    assert (
+        "raise RuntimeError('README.md exists in skill root but was not packaged')"
+        in workflow_text
+    )
+
+
+def test_workflow_metadata_reads_root_readme(workflow_text: str) -> None:
+    assert "readme_path = 'README.md'" in workflow_text
+    assert "frontmatter.load(readme_path)" in workflow_text
+    assert "metadata['readme_md'] = body" in workflow_text
+
+
+def test_workflow_does_not_use_references_readme_for_marketplace(
+    workflow_text: str,
+) -> None:
+    assert "os.path.join('references', 'README.md')" not in workflow_text
+    assert not re.search(
+        r"frontmatter\.load\([^)]*references[^)]*README",
+        workflow_text,
+    )
+
+
 def test_workflow_packages_env_example_at_root(workflow_text: str) -> None:
     assert ".env.example" in workflow_text
     assert "Copied .env.example" in workflow_text
@@ -40,3 +75,18 @@ def test_workflow_does_not_package_dot_env(workflow_text: str) -> None:
         r"os\.path\.join\(PACKAGE,\s*['\"]\.env['\"]\)",
         workflow_text,
     )
+
+
+def test_publish_workflow_triggers_on_main_only(publish_workflow_text: str) -> None:
+    assert "branches:" in publish_workflow_text
+    assert "- main" in publish_workflow_text
+    assert "tags:" not in publish_workflow_text
+
+
+def test_publish_workflow_uses_pyproject_version_only(publish_workflow_text: str) -> None:
+    assert "ci_set_package_version" not in publish_workflow_text
+    assert "GITHUB_RUN_NUMBER" not in publish_workflow_text
+    assert "GITHUB_RUN_ID" not in publish_workflow_text
+    assert ".post" not in publish_workflow_text
+    assert "python3.12 -m build" in publish_workflow_text
+    assert "twine upload" in publish_workflow_text

tests/test_runtime_diagnostics.py

@@ -0,0 +1,347 @@
+# -*- coding: utf-8 -*-
+"""runtime_diagnostics 公共 Runtime / media-assets 诊断测试。"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+import jiangchang_skill_core
+from jiangchang_skill_core import media_assets as ma
+from jiangchang_skill_core.runtime_diagnostics import (
+    RuntimeDiagnostics,
+    RuntimeIssue,
+    collect_runtime_diagnostics,
+    format_runtime_health_lines,
+    is_jiangchang_skill_core_from_skill_tree,
+    runtime_diagnostics_dict,
+    version_ge,
+)
+
+
+def test_version_ge_post_release() -> None:
+    assert version_ge("1.0.10.post23", "1.0.10") is True
+    assert version_ge("1.0.10", "1.0.10") is True
+    assert version_ge("1.0.9.post19", "1.0.10") is False
+    assert version_ge("1.0.10.post23", "1.0.10.post21") is True
+    assert version_ge("1.0.10.post21", "1.0.10.post23") is False
+    assert version_ge("1.0.10", "1.0.10.post1") is False
+    assert version_ge("1.0.11", "1.0.10.post99") is True
+    assert version_ge("1.0.11", "1.0.10") is True
+
+
+def test_is_jiangchang_skill_core_from_skill_tree(tmp_path: Path) -> None:
+    skill_root = tmp_path / "my-skill"
+    inside = skill_root / "scripts" / "jiangchang_skill_core" / "__init__.py"
+    inside.parent.mkdir(parents=True)
+    inside.write_text("# vendored\n", encoding="utf-8")
+    outside = tmp_path / "site-packages" / "jiangchang_skill_core" / "__init__.py"
+    outside.parent.mkdir(parents=True)
+    outside.write_text("# shared\n", encoding="utf-8")
+
+    assert is_jiangchang_skill_core_from_skill_tree(
+        skill_root=skill_root,
+        core_file=inside,
+    ) is True
+    assert is_jiangchang_skill_core_from_skill_tree(
+        skill_root=skill_root,
+        core_file=outside,
+    ) is False
+
+
+def test_collect_runtime_diagnostics_json_serializable(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    data_root = tmp_path / "data"
+    env = {
+        "CLAW_DATA_ROOT": str(data_root),
+        "OPENCLAW_RECORD_VIDEO": "0",
+    }
+    media_root = data_root / "shared" / "media-assets"
+    (media_root / "music").mkdir(parents=True)
+
+    def _fake_probe_media_assets(data_root_arg=None, env_arg=None):
+        return ma.MediaAssetsStatus(
+            root=media_root,
+            exists=True,
+            ready=False,
+            source="local",
+            warnings=["ffmpeg_missing"],
+            ffmpeg_path=None,
+            music_dir=media_root / "music",
+            music_ready=False,
+        )
+
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics.probe_media_assets",
+        _fake_probe_media_assets,
+    )
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics.probe_background_music",
+        lambda *a, **k: {
+            "music_root": str(media_root / "music"),
+            "mp3_count": 0,
+            "usable_count": 0,
+            "sample_path": None,
+            "issue": "background_music_dir_empty",
+        },
+    )
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics._platform_kit_version",
+        lambda: "1.0.10",
+    )
+
+    diag = collect_runtime_diagnostics(
+        skill_slug="my-skill",
+        platform_kit_min_version="1.0.9",
+        env=env,
+    )
+    payload = runtime_diagnostics_dict(diag)
+    json.dumps(payload)
+    assert payload["skill_slug"] == "my-skill"
+    assert payload["resolved_data_root"] == str(data_root)
+    assert payload["platform_kit_version_ok"] is True
+
+
+def test_platform_kit_min_version_none_skips_version_issue(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    env = {"CLAW_DATA_ROOT": str(tmp_path / "data")}
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics.probe_media_assets",
+        lambda *a, **k: ma.MediaAssetsStatus(
+            root=tmp_path,
+            exists=False,
+            ready=False,
+            source="local",
+        ),
+    )
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics.probe_background_music",
+        lambda *a, **k: {
+            "music_root": None,
+            "mp3_count": 0,
+            "usable_count": 0,
+            "sample_path": None,
+            "issue": "music_dir_missing",
+        },
+    )
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics._platform_kit_version",
+        lambda: "1.0.8",
+    )
+
+    diag = collect_runtime_diagnostics(skill_slug="my-skill", env=env)
+    assert diag.platform_kit_version_ok is None
+    assert "platform_kit_version_low" not in diag.issue_codes()
+
+
+def test_platform_kit_missing_records_issue(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    env = {"CLAW_DATA_ROOT": str(tmp_path / "data")}
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics.probe_media_assets",
+        lambda *a, **k: ma.MediaAssetsStatus(
+            root=tmp_path,
+            exists=False,
+            ready=False,
+            source="local",
+        ),
+    )
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics.probe_background_music",
+        lambda *a, **k: {
+            "music_root": None,
+            "mp3_count": 0,
+            "usable_count": 0,
+            "sample_path": None,
+            "issue": None,
+        },
+    )
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics._platform_kit_version",
+        lambda: None,
+    )
+
+    diag = collect_runtime_diagnostics(
+        skill_slug="my-skill",
+        platform_kit_min_version="1.0.10",
+        env=env,
+    )
+    assert "platform_kit_not_installed" in diag.issue_codes()
+
+
+def test_record_video_ffmpeg_and_music_warnings_not_fatal(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    media_root = tmp_path / "shared" / "media-assets"
+    env = {"CLAW_DATA_ROOT": str(tmp_path), "OPENCLAW_RECORD_VIDEO": "1"}
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics.probe_media_assets",
+        lambda *a, **k: ma.MediaAssetsStatus(
+            root=media_root,
+            exists=True,
+            ready=False,
+            source="local",
+            warnings=["ffmpeg_missing", "music_dir_missing"],
+            ffmpeg_path=None,
+            music_dir=None,
+        ),
+    )
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics.probe_background_music",
+        lambda *a, **k: {
+            "music_root": None,
+            "mp3_count": 0,
+            "usable_count": 0,
+            "sample_path": None,
+            "issue": "music_dir_missing",
+        },
+    )
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics._platform_kit_version",
+        lambda: "1.0.10",
+    )
+
+    diag = collect_runtime_diagnostics(skill_slug="my-skill", env=env)
+    codes = diag.issue_codes()
+    assert "ffmpeg_unavailable" in codes
+    assert "background_music_unavailable" in codes
+    assert diag.has_fatal_issues is False
+    ffmpeg_issue = next(i for i in diag.issues if i.code == "ffmpeg_unavailable")
+    assert ffmpeg_issue.severity == "warning"
+
+
+def test_skill_tree_core_issue_when_skill_root_given(tmp_path: Path) -> None:
+    skill_root = tmp_path / "my-skill"
+    fake_core = skill_root / "scripts" / "jiangchang_skill_core" / "__init__.py"
+    fake_core.parent.mkdir(parents=True)
+    fake_core.write_text("# vendored\n", encoding="utf-8")
+
+    env = {"CLAW_DATA_ROOT": str(tmp_path / "data")}
+    with patch.object(jiangchang_skill_core, "__file__", str(fake_core)):
+        diag = collect_runtime_diagnostics(
+            skill_slug="my-skill",
+            skill_root=skill_root,
+            record_video=False,
+            env=env,
+        )
+    assert "jiangchang_skill_core_loaded_from_skill_tree" in diag.issue_codes()
+
+
+def test_format_runtime_health_lines_core_fields(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    env = {"CLAW_DATA_ROOT": str(tmp_path / "data")}
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics.probe_media_assets",
+        lambda *a, **k: ma.MediaAssetsStatus(
+            root=tmp_path,
+            exists=False,
+            ready=False,
+            source="local",
+        ),
+    )
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics.probe_background_music",
+        lambda *a, **k: {
+            "music_root": None,
+            "mp3_count": 0,
+            "usable_count": 0,
+            "sample_path": None,
+            "issue": None,
+        },
+    )
+    monkeypatch.setattr(
+        "jiangchang_skill_core.runtime_diagnostics._platform_kit_version",
+        lambda: "1.0.10",
+    )
+
+    diag = collect_runtime_diagnostics(skill_slug="my-skill", env=env)
+    text = "\n".join(format_runtime_health_lines(diag))
+    for marker in (
+        "python_executable:",
+        "platform_kit_version:",
+        "resolved_data_root:",
+        "media_assets_root:",
+        "ffmpeg_available:",
+        "background_music_mp3_count:",
+    ):
+        assert marker in text
+
+
+def test_background_music_lfs_and_size_rules(tmp_path: Path) -> None:
+    music = tmp_path / "music"
+    music.mkdir()
+    (music / "tiny.mp3").write_bytes(b"x" * 512)
+    (music / "lfs.mp3").write_text(
+        "version https://git-lfs.github.com/spec/v1\noid sha256:abc\nsize 123\n"
+    )
+    (music / "ok.mp3").write_bytes(b"x" * 1024)
+
+    probe = ma.probe_background_music(tmp_path)
+    assert probe["mp3_count"] == 3
+    assert probe["usable_count"] == 1
+    assert probe["sample_path"] == str(music / "ok.mp3")
+
+
+def test_runtime_diagnostics_frozen_dataclass() -> None:
+    diag = RuntimeDiagnostics(
+        skill_slug="x",
+        python_executable="python",
+        platform_kit_version="1.0.10",
+        platform_kit_min_version=None,
+        platform_kit_version_ok=None,
+        jiangchang_skill_core_file=None,
+        claw_data_root=None,
+        jiangchang_data_root=None,
+        resolved_data_root="/tmp",
+        media_assets_root="/tmp/media",
+        ffmpeg_available=False,
+        ffmpeg_path=None,
+        background_music_mp3_count=0,
+        background_music_usable_count=0,
+        background_music_issue=None,
+        background_music_sample_path=None,
+        record_video_enabled=False,
+        issues=(RuntimeIssue(code="ffmpeg_unavailable", message="no ffmpeg"),),
+    )
+    assert diag.has_fatal_issues is False
+    assert diag.issue_codes() == ["ffmpeg_unavailable"]
+
+
+def test_format_runtime_health_lines_issue_separator_ascii() -> None:
+    diag = RuntimeDiagnostics(
+        skill_slug="x",
+        python_executable="python",
+        platform_kit_version="1.0.11",
+        platform_kit_min_version=None,
+        platform_kit_version_ok=None,
+        jiangchang_skill_core_file=None,
+        claw_data_root=None,
+        jiangchang_data_root=None,
+        resolved_data_root="/tmp",
+        media_assets_root="/tmp/media",
+        ffmpeg_available=False,
+        ffmpeg_path=None,
+        background_music_mp3_count=0,
+        background_music_usable_count=0,
+        background_music_issue=None,
+        background_music_sample_path=None,
+        record_video_enabled=False,
+        issues=(RuntimeIssue(code="ffmpeg_unavailable", message="no ffmpeg"),),
+    )
+    lines = format_runtime_health_lines(diag)
+    issue_lines = [line for line in lines if line.startswith("runtime_issue[")]
+    assert len(issue_lines) == 1
+    assert " - " in issue_lines[0]
+    assert "\u2014" not in issue_lines[0]
+    assert "\u2013" not in issue_lines[0]

tests/test_video_session.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""RpaVideoSession：ffmpeg 桌面录屏。"""
+"""RpaVideoSession：ffmpeg 桌面录屏、背景音乐循环淡出、旁白混音。"""
 from __future__ import annotations
 
 import asyncio
@@ -8,9 +8,21 @@ import sys
 import tempfile
 import unittest
 from pathlib import Path
-from unittest.mock import MagicMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
+
 from jiangchang_skill_core import config
-from jiangchang_skill_core.rpa.video_session import RpaVideoSession
+from jiangchang_skill_core.rpa import video_session as vs
+from jiangchang_skill_core.rpa.video_session import (
+    RpaVideoSession,
+    _StepEntry,
+    _INTRO_BUFFER_SECONDS,
+    _INTRO_STABILIZE_SECONDS,
+    _OUTRO_BUFFER_SECONDS,
+    _compose_capture_mp4,
+    _music_fade_params,
+    _select_voiceover_clips,
+    _voiceover_text_for_step,
+)
 
 
 class TestRpaVideoSession(unittest.TestCase):
@@ -33,6 +45,8 @@ class TestRpaVideoSession(unittest.TestCase):
                 self.assertIsNone(summ["path"])
                 self.assertIsNone(summ["capture_path"])
                 self.assertIsNone(summ["record_log_path"])
+                self.assertIsNone(summ["voiceover_path"])
+                self.assertIsNone(summ["music_path"])
         finally:
             if old is not None:
                 os.environ["OPENCLAW_RECORD_VIDEO"] = old
@@ -60,6 +74,11 @@ class TestRpaVideoSession(unittest.TestCase):
                         "/rpa-artifacts/exmail_20260602_120000/logs/ffmpeg-record.log"
                     )
                 )
+                self.assertTrue(
+                    session._voiceover_path.replace("\\", "/").endswith(
+                        "/rpa-artifacts/exmail_20260602_120000/voiceover/voiceover.wav"
+                    )
+                )
                 self.assertTrue(
                     session._planned_output.replace("\\", "/").startswith(
                         tmp.replace("\\", "/") + "/videos/"
@@ -144,5 +163,413 @@ class TestRpaVideoSession(unittest.TestCase):
             config.reset_cache()
 
 
+class TestMusicFadeParams(unittest.TestCase):
+    def test_normal_duration(self) -> None:
+        start, dur = _music_fade_params(20.0)
+        self.assertAlmostEqual(start, 17.0)
+        self.assertAlmostEqual(dur, 3.0)
+
+    def test_short_video(self) -> None:
+        start, dur = _music_fade_params(4.0)
+        self.assertAlmostEqual(dur, 1.0)
+        self.assertAlmostEqual(start, 3.0)
+
+    def test_invalid_duration(self) -> None:
+        self.assertEqual(_music_fade_params(None), (None, None))
+        self.assertEqual(_music_fade_params(0), (None, None))
+        self.assertEqual(_music_fade_params(-1), (None, None))
+
+
+class TestVoiceoverTextFilter(unittest.TestCase):
+    def test_keeps_meaningful_steps(self) -> None:
+        for text in (
+            "开始采集",
+            "获取1688账号",
+            "启动浏览器",
+            "检查登录状态",
+            "搜索关键词：螺丝",
+            "解析第 1 页店铺列表",
+            "打开店铺联系方式页",
+            "提取联系人信息",
+            "采集完成",
+        ):
+            self.assertIsNotNone(_voiceover_text_for_step(text), msg=text)
+
+    def test_skips_noise(self) -> None:
+        for text in (
+            "等待 1-5s",
+            "跳过重复店铺",
+            "写入联系人库",
+            "探针模式",
+            "操作异常",
+            "登录失败",
+            "2024-01-01 12:00:00 INFO: debug",
+            "",
+            "   ",
+        ):
+            self.assertIsNone(_voiceover_text_for_step(text), msg=text)
+
+    def test_truncates_long_text(self) -> None:
+        long_text = "开" * 80
+        result = _voiceover_text_for_step(long_text)
+        self.assertIsNotNone(result)
+        assert result is not None
+        self.assertEqual(len(result), 60)
+
+    def test_dedup_within_ten_seconds(self) -> None:
+        entries = [
+            _StepEntry(0.0, "启动浏览器"),
+            _StepEntry(5.0, "启动浏览器"),
+            _StepEntry(12.0, "启动浏览器"),
+        ]
+        clips = _select_voiceover_clips(entries)
+        texts = [t for _, t in clips]
+        self.assertEqual(texts.count("启动浏览器"), 2)
+
+    def test_min_gap_two_seconds(self) -> None:
+        entries = [
+            _StepEntry(0.0, "获取1688账号"),
+            _StepEntry(1.0, "连接CDP"),
+            _StepEntry(3.0, "检查登录状态"),
+        ]
+        clips = _select_voiceover_clips(entries)
+        self.assertEqual(len(clips), 2)
+        self.assertEqual(clips[0][1], "获取1688账号")
+        self.assertEqual(clips[1][1], "检查登录状态")
+
+    def test_important_bypasses_min_gap(self) -> None:
+        entries = [
+            _StepEntry(0.0, "定位搜索框"),
+            _StepEntry(0.5, "输入关键词：宁德电池"),
+            _StepEntry(1.0, "点击搜索"),
+            _StepEntry(1.5, "等待搜索结果"),
+        ]
+        clips = _select_voiceover_clips(entries)
+        texts = [t for _, t in clips]
+        self.assertEqual(len(clips), 4)
+        self.assertIn("输入关键词：宁德电池", texts)
+        self.assertIn("点击搜索", texts)
+
+    def test_noise_still_skipped_with_important_nearby(self) -> None:
+        entries = [
+            _StepEntry(0.0, "点击搜索"),
+            _StepEntry(0.5, "跳过重复店铺"),
+            _StepEntry(1.0, "写入联系人库"),
+        ]
+        clips = _select_voiceover_clips(entries)
+        texts = [t for _, t in clips]
+        self.assertEqual(texts, ["点击搜索"])
+
+
+class TestComposeCaptureMp4(unittest.TestCase):
+    def setUp(self) -> None:
+        self.ffmpeg = Path(r"C:\ffmpeg\ffmpeg.exe")
+        self.capture = Path(r"C:\tmp\capture.mp4")
+        self.srt = Path(r"C:\tmp\sub.srt")
+        self.output = Path(r"C:\tmp\out.mp4")
+        self.music = Path(r"C:\tmp\music.mp3")
+        self.voice = Path(r"C:\tmp\voiceover.wav")
+
+    def _run_compose(self, **kwargs) -> list[str]:
+        captured: list[str] = []
+
+        def fake_run(_exe: Path, cmd_tail: list[str]) -> tuple[bool, str]:
+            captured.extend(cmd_tail)
+            return True, ""
+
+        with (
+            patch.object(vs, "_run_ffmpeg", side_effect=fake_run),
+            patch.object(vs, "_resolve_ffprobe_exe", return_value=Path(r"C:\ffmpeg\ffprobe.exe")),
+            patch.object(vs, "_probe_media_duration_seconds", return_value=kwargs.pop("duration", 20.0)),
+            patch.object(Path, "is_file", return_value=True),
+        ):
+            _compose_capture_mp4(
+                self.ffmpeg,
+                self.capture,
+                self.srt,
+                self.output,
+                music_file=kwargs.get("music_file"),
+                voiceover_file=kwargs.get("voiceover_file"),
+                warnings=kwargs.get("warnings"),
+            )
+        return captured
+
+    def test_music_loop_params(self) -> None:
+        cmd = self._run_compose(music_file=self.music)
+        cmd_str = " ".join(cmd)
+        loop_idx = cmd.index("-stream_loop")
+        minus_one_idx = cmd.index("-1", loop_idx)
+        music_i_idx = cmd.index("-i", minus_one_idx)
+        self.assertEqual(cmd[music_i_idx + 1], str(self.music))
+        self.assertIn("-shortest", cmd)
+        filter_idx = cmd.index("-filter_complex")
+        filt = cmd[filter_idx + 1]
+        self.assertNotIn("apad", filt)
+
+    def test_music_fade_filter_long_video(self) -> None:
+        cmd = self._run_compose(music_file=self.music, duration=20.0)
+        filt = cmd[cmd.index("-filter_complex") + 1]
+        self.assertIn("afade=t=out:st=17", filt)
+        self.assertIn("d=3", filt)
+        self.assertIn(f"volume={vs._MUSIC_VOLUME}", filt)
+
+    def test_music_fade_filter_short_video(self) -> None:
+        cmd = self._run_compose(music_file=self.music, duration=4.0)
+        filt = cmd[cmd.index("-filter_complex") + 1]
+        self.assertIn("afade=t=out:st=3", filt)
+        self.assertIn("d=1", filt)
+
+    def test_duration_probe_failed_no_afade(self) -> None:
+        warnings: list[str] = []
+        captured: list[str] = []
+
+        def fake_run(_exe: Path, cmd_tail: list[str]) -> tuple[bool, str]:
+            captured.extend(cmd_tail)
+            return True, ""
+
+        with (
+            patch.object(vs, "_run_ffmpeg", side_effect=fake_run),
+            patch.object(vs, "_resolve_ffprobe_exe", return_value=None),
+            patch.object(vs, "_probe_media_duration_seconds", return_value=None),
+            patch.object(Path, "is_file", return_value=True),
+        ):
+            ok, _ = _compose_capture_mp4(
+                self.ffmpeg,
+                self.capture,
+                self.srt,
+                self.output,
+                music_file=self.music,
+                warnings=warnings,
+            )
+        self.assertTrue(ok)
+        self.assertIn("video_duration_probe_failed_for_music_fade", warnings)
+        filt = captured[captured.index("-filter_complex") + 1]
+        self.assertNotIn("afade", filt)
+        self.assertIn("-stream_loop", captured)
+
+    def test_music_and_voice_amix(self) -> None:
+        cmd = self._run_compose(music_file=self.music, voiceover_file=self.voice)
+        filt = cmd[cmd.index("-filter_complex") + 1]
+        self.assertIn("amix", filt)
+        self.assertIn(f"volume={vs._MUSIC_VOLUME}", filt)
+        self.assertIn(f"volume={vs._VOICE_VOLUME}", filt)
+        self.assertLess(vs._MUSIC_VOLUME, vs._VOICE_VOLUME)
+        self.assertIn("afade", filt)
+        self.assertNotIn("apad", filt)
+        self.assertIn("-stream_loop", cmd)
+        self.assertIn("-shortest", cmd)
+
+    def test_voice_only_no_amix(self) -> None:
+        cmd = self._run_compose(voiceover_file=self.voice)
+        filt = cmd[cmd.index("-filter_complex") + 1]
+        self.assertNotIn("amix", filt)
+        self.assertIn(f"volume={vs._VOICE_VOLUME}", filt)
+        self.assertIn("apad", filt)
+        self.assertIn("-shortest", cmd)
+        self.assertNotIn("-stream_loop", cmd)
+
+
+class TestVideoSessionLifecycle(unittest.TestCase):
+    def setUp(self) -> None:
+        config.reset_cache()
+
+    def tearDown(self) -> None:
+        os.environ.pop("OPENCLAW_RECORD_VIDEO", None)
+        config.reset_cache()
+
+    @patch("jiangchang_skill_core.rpa.video_session.asyncio.sleep", new_callable=AsyncMock)
+    @patch.object(RpaVideoSession, "_start_ffmpeg_capture")
+    @patch.object(RpaVideoSession, "_stop_ffmpeg_capture")
+    @patch.object(RpaVideoSession, "finalize", new_callable=AsyncMock)
+    def test_enter_starts_capture_before_title(
+        self,
+        mock_finalize: AsyncMock,
+        mock_stop: MagicMock,
+        mock_start: MagicMock,
+        mock_sleep: AsyncMock,
+    ) -> None:
+        os.environ["OPENCLAW_RECORD_VIDEO"] = "1"
+        call_order: list[str] = []
+        mock_start.side_effect = lambda: call_order.append("start_capture")
+
+        with tempfile.TemporaryDirectory() as tmp:
+            config.reset_cache()
+            session = RpaVideoSession(
+                skill_slug="test",
+                skill_data_dir=tmp,
+                batch_id="batch_intro",
+                title="开始执行测试",
+            )
+            original_add = session.add_step
+
+            def _track_add(text: str, *, duration: float = 4.0) -> None:
+                call_order.append(f"add_step:{text}")
+                original_add(text, duration=duration)
+
+            with patch.object(session, "add_step", side_effect=_track_add):
+                asyncio.run(session.__aenter__())
+
+        self.assertEqual(call_order[0], "start_capture")
+        self.assertIn("add_step:开始执行测试", call_order)
+        mock_sleep.assert_awaited()
+        total_sleep = sum(c.args[0] for c in mock_sleep.await_args_list if c.args)
+        self.assertAlmostEqual(total_sleep, _INTRO_BUFFER_SECONDS)
+
+    @patch("jiangchang_skill_core.rpa.video_session.asyncio.sleep", new_callable=AsyncMock)
+    @patch.object(RpaVideoSession, "_start_ffmpeg_capture")
+    def test_enter_no_title_still_buffers(
+        self,
+        mock_start: MagicMock,
+        mock_sleep: AsyncMock,
+    ) -> None:
+        os.environ["OPENCLAW_RECORD_VIDEO"] = "1"
+        with tempfile.TemporaryDirectory() as tmp:
+            config.reset_cache()
+            session = RpaVideoSession(
+                skill_slug="test",
+                skill_data_dir=tmp,
+                batch_id="batch_no_title",
+            )
+            with patch.object(session, "add_step") as mock_add:
+                asyncio.run(session.__aenter__())
+            mock_start.assert_called_once()
+            mock_add.assert_not_called()
+            total_sleep = sum(c.args[0] for c in mock_sleep.await_args_list if c.args)
+            self.assertAlmostEqual(total_sleep, _INTRO_BUFFER_SECONDS)
+
+    @patch("jiangchang_skill_core.rpa.video_session.asyncio.sleep", new_callable=AsyncMock)
+    @patch.object(RpaVideoSession, "_stop_ffmpeg_capture")
+    @patch.object(RpaVideoSession, "finalize", new_callable=AsyncMock)
+    def test_exit_closing_title_before_stop(
+        self,
+        mock_finalize: AsyncMock,
+        mock_stop: MagicMock,
+        mock_sleep: AsyncMock,
+    ) -> None:
+        os.environ["OPENCLAW_RECORD_VIDEO"] = "1"
+        call_order: list[str] = []
+        mock_stop.side_effect = lambda: call_order.append("stop_capture")
+
+        with tempfile.TemporaryDirectory() as tmp:
+            config.reset_cache()
+            session = RpaVideoSession(
+                skill_slug="test",
+                skill_data_dir=tmp,
+                batch_id="batch_outro",
+                closing_title="任务已完成",
+            )
+            original_add = session.add_step
+
+            def _track_add(text: str, *, duration: float = 4.0) -> None:
+                call_order.append(f"add_step:{text}")
+                original_add(text, duration=duration)
+
+            with patch.object(session, "add_step", side_effect=_track_add):
+                asyncio.run(session.__aexit__(None, None, None))
+
+        self.assertIn("add_step:任务已完成", call_order)
+        self.assertEqual(call_order[-1], "stop_capture")
+        total_sleep = sum(c.args[0] for c in mock_sleep.await_args_list if c.args)
+        self.assertAlmostEqual(total_sleep, _OUTRO_BUFFER_SECONDS)
+
+    @patch("jiangchang_skill_core.rpa.video_session.asyncio.sleep", new_callable=AsyncMock)
+    @patch.object(RpaVideoSession, "_stop_ffmpeg_capture")
+    @patch.object(RpaVideoSession, "finalize", new_callable=AsyncMock)
+    def test_exit_no_closing_title_still_outro_buffer(
+        self,
+        mock_finalize: AsyncMock,
+        mock_stop: MagicMock,
+        mock_sleep: AsyncMock,
+    ) -> None:
+        os.environ["OPENCLAW_RECORD_VIDEO"] = "1"
+        with tempfile.TemporaryDirectory() as tmp:
+            config.reset_cache()
+            session = RpaVideoSession(
+                skill_slug="test",
+                skill_data_dir=tmp,
+                batch_id="batch_outro_empty",
+            )
+            with patch.object(session, "add_step") as mock_add:
+                asyncio.run(session.__aexit__(None, None, None))
+            mock_add.assert_not_called()
+            mock_stop.assert_called_once()
+            total_sleep = sum(c.args[0] for c in mock_sleep.await_args_list if c.args)
+            self.assertAlmostEqual(total_sleep, _OUTRO_BUFFER_SECONDS)
+
+
+class TestFinalizeDegradation(unittest.TestCase):
+    def setUp(self) -> None:
+        config.reset_cache()
+
+    def tearDown(self) -> None:
+        os.environ.pop("OPENCLAW_RECORD_VIDEO", None)
+        config.reset_cache()
+
+    @patch("jiangchang_skill_core.rpa.video_session._resolve_ffmpeg_exe")
+    @patch("jiangchang_skill_core.rpa.video_session._resolve_music_file")
+    @patch("jiangchang_skill_core.rpa.video_session._synthesize_step_voiceover")
+    @patch("jiangchang_skill_core.rpa.video_session._compose_capture_mp4")
+    def test_tts_failure_still_composes(
+        self,
+        mock_compose: MagicMock,
+        mock_tts: MagicMock,
+        mock_music: MagicMock,
+        mock_ffmpeg: MagicMock,
+    ) -> None:
+        os.environ["OPENCLAW_RECORD_VIDEO"] = "1"
+        mock_ffmpeg.return_value = Path(r"C:\ffmpeg\ffmpeg.exe")
+        mock_music.return_value = Path(r"C:\tmp\music.mp3")
+        mock_tts.return_value = None
+        mock_compose.return_value = (True, "")
+
+        with tempfile.TemporaryDirectory() as tmp:
+            capture = Path(tmp) / "rpa-artifacts" / "batch" / "capture.mp4"
+            capture.parent.mkdir(parents=True)
+            capture.write_bytes(b"fake")
+
+            session = RpaVideoSession(
+                skill_slug="test",
+                skill_data_dir=tmp,
+                batch_id="batch",
+            )
+            session.add_step("启动浏览器")
+            asyncio.run(session.finalize())
+
+        self.assertTrue(mock_compose.called)
+        self.assertIsNotNone(session.output_video_path)
+
+    @patch("jiangchang_skill_core.rpa.video_session._resolve_ffmpeg_exe")
+    @patch("jiangchang_skill_core.rpa.video_session._resolve_music_file")
+    @patch("jiangchang_skill_core.rpa.video_session._synthesize_step_voiceover")
+    @patch("jiangchang_skill_core.rpa.video_session._compose_capture_mp4")
+    def test_compose_fallback_without_music(
+        self,
+        mock_compose: MagicMock,
+        mock_tts: MagicMock,
+        mock_music: MagicMock,
+        mock_ffmpeg: MagicMock,
+    ) -> None:
+        os.environ["OPENCLAW_RECORD_VIDEO"] = "1"
+        mock_ffmpeg.return_value = Path(r"C:\ffmpeg\ffmpeg.exe")
+        mock_music.return_value = Path(r"C:\tmp\music.mp3")
+        mock_tts.return_value = None
+        mock_compose.side_effect = [(False, "music err"), (True, "")]
+
+        with tempfile.TemporaryDirectory() as tmp:
+            capture = Path(tmp) / "rpa-artifacts" / "batch" / "capture.mp4"
+            capture.parent.mkdir(parents=True)
+            capture.write_bytes(b"fake")
+
+            session = RpaVideoSession(
+                skill_slug="test",
+                skill_data_dir=tmp,
+                batch_id="batch",
+            )
+            asyncio.run(session.finalize())
+
+        self.assertEqual(mock_compose.call_count, 2)
+        self.assertTrue(any("ffmpeg_with_music_failed" in w for w in session.warnings))
+
+
 if __name__ == "__main__":
     unittest.main()

tools/ci_set_package_version.py

@@ -1,79 +0,0 @@
-"""Patch pyproject.toml and __init__.py version for CI builds (not committed)."""
-from __future__ import annotations
-
-import os
-import re
-import sys
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent
-
-
-def _read_base_version() -> str:
-    text = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
-    match = re.search(r'^version\s*=\s*"([^"]+)"', text, re.MULTILINE)
-    if not match:
-        raise SystemExit("ERROR: version not found in pyproject.toml")
-    base = match.group(1)
-    return re.sub(r"\.post\d+$", "", base)
-
-
-def resolve_version() -> str:
-    ref = os.environ.get("GITHUB_REF", "")
-    if ref.startswith("refs/tags/v"):
-        return ref.removeprefix("refs/tags/v")
-    if ref.startswith("refs/tags/"):
-        return ref.removeprefix("refs/tags/")
-
-    run_number = (
-        os.environ.get("GITHUB_RUN_NUMBER")
-        or os.environ.get("GITHUB_RUN_ID")
-        or "0"
-    )
-    base = _read_base_version()
-    return f"{base}.post{run_number}"
-
-
-def patch_version(version: str) -> None:
-    pyproject = ROOT / "pyproject.toml"
-    py_text = pyproject.read_text(encoding="utf-8")
-    py_text, n = re.subn(
-        r'^version\s*=\s*"[^"]*"',
-        f'version = "{version}"',
-        py_text,
-        count=1,
-        flags=re.MULTILINE,
-    )
-    if n != 1:
-        raise SystemExit("ERROR: failed to patch version in pyproject.toml")
-    pyproject.write_text(py_text, encoding="utf-8")
-
-    init_py = ROOT / "src" / "jiangchang_desktop_sdk" / "__init__.py"
-    init_text = init_py.read_text(encoding="utf-8")
-    init_text, n = re.subn(
-        r'^__version__\s*=\s*"[^"]*"',
-        f'__version__ = "{version}"',
-        init_text,
-        count=1,
-        flags=re.MULTILINE,
-    )
-    if n != 1:
-        raise SystemExit("ERROR: failed to patch __version__ in __init__.py")
-    init_py.write_text(init_text, encoding="utf-8")
-
-
-def main() -> None:
-    version = resolve_version()
-    print(f"Resolved package version: {version}")
-    patch_version(version)
-    if os.environ.get("GITHUB_OUTPUT"):
-        with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as fh:
-            fh.write(f"package_version={version}\n")
-
-
-if __name__ == "__main__":
-    try:
-        main()
-    except SystemExit as exc:
-        print(exc, file=sys.stderr)
-        raise

tools/release.ps1

@@ -28,6 +28,7 @@
   加密与 ZIP 内容由 CI 工作流 reusable-release-skill.yaml 的「Encrypt Source Code」步骤执行。CI 会：
   - 加密 scripts/（递归 PyArmor -r，输出到包内 scripts/，与源码目录树一致）
   - 复制 SKILL.md
+  - 若根目录存在 README.md，则复制到包根（明文，用于技能市场用户说明）
   - 复制 references/（排除 REQUIREMENTS.md）
   - 复制 assets/
   - 复制 tests/

uv.lock

@@ -116,6 +116,92 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/db/8f/61959034484a4a7c527811f4721e75d02d653a35afb0b6054474d8185d4c/charset_normalizer-3.4.7-py3-none-any.whl", hash = "sha256:3dce51d0f5e7951f8bb4900c257dad282f49190fdbebecd4ba99bcc41fef404d", size = 61958, upload-time = "2026-04-02T09:28:37.794Z" },
 ]
 
+[[package]]
+name = "greenlet"
+version = "3.5.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e2/f1/fbbfef6af0bad0548f09bc28948ea3c275b4edb19e17fc5ca9900a6a634d/greenlet-3.5.3.tar.gz", hash = "sha256:a61efc018fd3eb317eeca31aba90ee9e7f26f22884a79b6c6ec715bf71bb62f1", size = 200270, upload-time = "2026-06-26T19:28:24.832Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f5/a1/1f7f0c555f5858fd2906fe9f7b0a3554fddb85cb70df7a6aaec41dc292c2/greenlet-3.5.3-cp310-cp310-macosx_11_0_universal2.whl", hash = "sha256:c180d22d325fb613956b443c3c6f4406eb70e6defc70d3974da2a7b59e06f48c", size = 285838, upload-time = "2026-06-26T18:21:05.167Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/29/be9f43ed61677a5759b38c8a9389248133c8c731bbfc0574ecdff66c99fc/greenlet-3.5.3-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:483d08c11181c83a6ce1a7a61df0f624a208ec40817a3bb2302714592eee4f04", size = 602342, upload-time = "2026-06-26T19:07:06.908Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/42/ba41c97ec36aa4b3ec25e5aa691d79561254805fad7f2f826dd6770587e2/greenlet-3.5.3-cp310-cp310-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:1dae6e0091eae084317e411f047f0b7cb241c6db570f7c45fd6b900a274914ce", size = 615541, upload-time = "2026-06-26T19:10:04.909Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/8c/231ca675b0df779816950ca66b40b1fa14dbff4a0ed9814a9a29ec399140/greenlet-3.5.3-cp310-cp310-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:0f6ff50ff8dbd51fae9b37f4101648b04ea0df19b3f50ab2beb5061e7716a5c8", size = 622473, upload-time = "2026-06-26T19:24:12.786Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/c7/28747042e1df8a9cd120a1ebe15529fc4be3b486e13e8d551ff307a82412/greenlet-3.5.3-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9bcd2d72ccd70a1ec68ba6ef93e7fbb4420ef9997dabc7010d893bd4015e0bec", size = 615675, upload-time = "2026-06-26T18:32:14.444Z" },
+    { url = "https://files.pythonhosted.org/packages/81/fe/dd97c483a3ff82849196ccd07851600edd3ac9de74669ca8a6022ada9ea1/greenlet-3.5.3-cp310-cp310-manylinux_2_39_riscv64.whl", hash = "sha256:37bf9c538f5ae6e63d643f88dec37c0c83bdf0e2ebc62961dedcf458822f7b71", size = 418421, upload-time = "2026-06-26T19:25:34.503Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/a8/b85525a6c8fba9f009a5f7c8df1545de8fb0f0bf3e0179194ef4e500317f/greenlet-3.5.3-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:73f152c895e09907e0dbe24f6c2db37beb085cd63db91c3825a0fcd0064124a8", size = 1575057, upload-time = "2026-06-26T19:09:00.264Z" },
+    { url = "https://files.pythonhosted.org/packages/03/79/fb76edb218fe6735ab0edeba176c7ab80df9618f7c02ce4208979f3ae7db/greenlet-3.5.3-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:8bdb43e1a1d1873721acab2be99c5befd4d2044ddfd52e4d610801019880a702", size = 1641692, upload-time = "2026-06-26T18:31:41.454Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/79/86fe3ee50ed55d9b3907eecd3208b5c3fe8a79515519aae98b4753c3fa1d/greenlet-3.5.3-cp310-cp310-win_amd64.whl", hash = "sha256:0909f9355a9f24845d3299f3112e266a06afb68302041989fd26bd68894933db", size = 238742, upload-time = "2026-06-26T18:20:40.758Z" },
+    { url = "https://files.pythonhosted.org/packages/51/58/5404031044f55afad7aad1aff8be3f22b1bed03e237cfeabbc7e5c8cfde0/greenlet-3.5.3-cp311-cp311-macosx_11_0_universal2.whl", hash = "sha256:aca9b4ce85b152b5524ef7d88170efdff80dc0032aa8b75f9aaf7f3479ea95b4", size = 287424, upload-time = "2026-06-26T18:20:31.469Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/bf/1c65e9b94a54d547068fa5b5a8a06f221f3316b48908e08668d29c77cb50/greenlet-3.5.3-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0f71be4920368fe1fabeeaa53d1e3548337e2b223d9565f8ad5e392a75ba23fc", size = 606523, upload-time = "2026-06-26T19:07:08.859Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/c7/b66baacc95775ad511287acb0137b95574a9ce5491902372b7564799d790/greenlet-3.5.3-cp311-cp311-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:4d77e67f65f98449e3fb83f795b5d0a8437aead2f874ca89c96576caf4be3af6", size = 618315, upload-time = "2026-06-26T19:10:06.055Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/a0/68afd1ebad40db87dac0a28ffa120726b98bf9c7c40c481b0f63c105d298/greenlet-3.5.3-cp311-cp311-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:e18619ba655ac05d78d80fc83cac4ba892bd6927b99e3b8237aee861aaacc8bb", size = 626155, upload-time = "2026-06-26T19:24:14.44Z" },
+    { url = "https://files.pythonhosted.org/packages/78/2b/28ed29463522fdbe4c15b1f63922041626a7478316b34ab4adda3f0a4aba/greenlet-3.5.3-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8540f1e6205bd13ca0ce685581037219ca54a1b41a0a15d228c6c9b8ad5903d7", size = 617381, upload-time = "2026-06-26T18:32:16.077Z" },
+    { url = "https://files.pythonhosted.org/packages/07/7f/e327d912239ec4b3b49999e3967389bcf1ee8722b9ee9194d2752ecd558a/greenlet-3.5.3-cp311-cp311-manylinux_2_39_riscv64.whl", hash = "sha256:d27c0c653a60d9535f690226474a5cc1036a8b0d7b57504d1c4f89c44a07a80c", size = 421083, upload-time = "2026-06-26T19:25:35.804Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/7b/ad04e9d1337fc04965dc9fc616b6a72cb65a24b800a014c011ec812f5489/greenlet-3.5.3-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:7ef56fe650f50575bf843acde967b9c567687f3c22340941a899b7bc56e956a8", size = 1577771, upload-time = "2026-06-26T19:09:01.537Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/33/6c87ab7ba663f70ca21f3022aad1ffe56d3f3e0521e836c2415e13abcc3c/greenlet-3.5.3-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:5121af01cf911e70056c00d4b46d5e9b5d1415550038573d744138bacb59e6b8", size = 1644048, upload-time = "2026-06-26T18:31:42.996Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/35/f0d8ee998b422cf8693b270f098e55d8d4ec8006b061b333f54f177d28d9/greenlet-3.5.3-cp311-cp311-win_amd64.whl", hash = "sha256:0f41e4a05a3c0cb31b17023eff28dd111e1d16bf7d7d00406cd7df23f31398a7", size = 239137, upload-time = "2026-06-26T18:23:21.664Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/96/b9820295576ef18c9edc404f10e260ae7215ceaf3781a54b720ed2627862/greenlet-3.5.3-cp311-cp311-win_arm64.whl", hash = "sha256:ec6f1af59f6b5f3fc9678e2ea062d8377d22ac644f7844cb7a292910cf12ff44", size = 237630, upload-time = "2026-06-26T18:24:00.281Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/6e/4c37d51a2b7f82d2ff11bb6b5f7d766d9a011726624af255e843727627a3/greenlet-3.5.3-cp312-cp312-macosx_11_0_universal2.whl", hash = "sha256:719757059f5a53fd0dde23f78cffeafcdd97b21c850ddb7ca684a3c1a1f122e2", size = 288685, upload-time = "2026-06-26T18:22:08.977Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/73/815dd90131c1b71ebdf53dbc7c276cafec2a1173b97559f97aba72724a87/greenlet-3.5.3-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:efa9f765dd09f9d0cdac651ffdf631ee59ec5dc6ee7a73e0c012ba9c52fbdf5b", size = 604761, upload-time = "2026-06-26T19:07:10.114Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/57/079cfe76bcef36b153b25607ee91c6fcb58f17f8b23c86bbbeabe0c88d72/greenlet-3.5.3-cp312-cp312-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:7faba15ac005376e02a0384504e0243be3370ce010296a44a820feb342b505ab", size = 617044, upload-time = "2026-06-26T19:10:07.25Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/fb/d97dc261209c80744b7c8132693a30d70ec6e7315e632cb0a10b3fec94dd/greenlet-3.5.3-cp312-cp312-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5795cd1101371140551c645f2d408b8d3c01a5a29cf8a9bce6e759c983682d23", size = 622351, upload-time = "2026-06-26T19:24:16.32Z" },
+    { url = "https://files.pythonhosted.org/packages/37/87/b4d095775a3fb1bcafbb483fc206b27ebb785724c83051447737085dc54e/greenlet-3.5.3-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:87142215824be6ac05e2e8e2786eec307ccbc27c36723c3881959df654af6861", size = 614244, upload-time = "2026-06-26T18:32:17.594Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/ac/e5fee13cbbd0e8de312d9a146584b8a51891c68847330ef9dc8b5109d23f/greenlet-3.5.3-cp312-cp312-manylinux_2_39_riscv64.whl", hash = "sha256:af4923b3096e26a36d7e9cf24ab88083a20f97d191e3b97f253731ce9b41b28c", size = 425395, upload-time = "2026-06-26T19:25:37.144Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/70/7559b609683650fa2b95b8ab84b4ab0b26556a635d19675e12aa832d826d/greenlet-3.5.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:215275b1b49320987352e6c1b054acca0064f965a2c66992bed9a6f7d913f149", size = 1574210, upload-time = "2026-06-26T19:09:03.077Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/73/be55392074c60fc37655ca40fa6022457bfbf6718e9e342a7b0b41f96dd2/greenlet-3.5.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:6b1b0eed82364b0e32c4ea0f221452d33e6bb17ae094d9f72aed9851812747ea", size = 1638627, upload-time = "2026-06-26T18:31:44.748Z" },
+    { url = "https://files.pythonhosted.org/packages/14/40/c57489acf8e37d74e2913d4eff63aa0dba17acccc4bdeef874dde2dbbec9/greenlet-3.5.3-cp312-cp312-win_amd64.whl", hash = "sha256:cde8adafa2365676f74a979744629589999093bc86e2484214f58e61df08902c", size = 239882, upload-time = "2026-06-26T18:23:27.518Z" },
+    { url = "https://files.pythonhosted.org/packages/71/fd/6fea0e3d6600f785069481ee637e09378dd4118acdfd38ad88ae2db31c98/greenlet-3.5.3-cp312-cp312-win_arm64.whl", hash = "sha256:c4e7b79d83805475f0102008843f6eb45fd3bb0b2e88c774adab5fbaab27117d", size = 238211, upload-time = "2026-06-26T18:22:37.671Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/ff/a620267401db30a50cc8450ee90730e2d4a85658c055c0e760d4ed47fb13/greenlet-3.5.3-cp313-cp313-macosx_11_0_universal2.whl", hash = "sha256:c8d87c2134d871df96ecdea9cec7cbaab286dadab0f56476e57aaf9e8ac11550", size = 287609, upload-time = "2026-06-26T18:21:14.724Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/fa/5401ac78021c826a25b6dde0c705e0a8f29b617509f9185a31dac15fbe1b/greenlet-3.5.3-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a2d185dd1621757e70c3861cceffd5317ab4e7ed7eb09c82994828468527ade5", size = 607435, upload-time = "2026-06-26T19:07:11.412Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/76/1dc144a2e56e65d36405078ed774224375ea520a1870a6e46e08bb4ac7bf/greenlet-3.5.3-cp313-cp313-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:1c514a468149bf8fbbab874188a3535cd8a48a3e353eb53a3d424296f8dbacd3", size = 619787, upload-time = "2026-06-26T19:10:08.396Z" },
+    { url = "https://files.pythonhosted.org/packages/57/61/2f5b1adf256d039f5dab8005de8d3d7ad2b0070a3219c0e036b3fbfeb440/greenlet-3.5.3-cp313-cp313-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:9ad04dd75458c6300b047c61b8639092433d205a25a14e310d6582a480efcca1", size = 625580, upload-time = "2026-06-26T19:24:18.344Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/87/c298cee62df1de4ad7fec32abda73526cff347fd143a6ed4ac369246668a/greenlet-3.5.3-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:915f887cf2682b66419b879423a2e072634aa7b7dce6f3ada4957cfced3f1e9a", size = 616786, upload-time = "2026-06-26T18:32:19.128Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/d9/ab7fc9e543e44d6879b0a6ef9a4b2188940fd180cc65d6f646883ddf7201/greenlet-3.5.3-cp313-cp313-manylinux_2_39_riscv64.whl", hash = "sha256:afaabdd554cd7ae9bbb3ca070b0d7fdfd207dbf1d16865f7233837709d354bda", size = 427933, upload-time = "2026-06-26T19:25:38.219Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/2e/e6f009885ed0705ccf33fe0583c117cfd03cde77e31a596dd5785a30762b/greenlet-3.5.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:766cfd421c13e450feb340cd472a3ed9957d438727b7b4593ad7c76c5d2b0deb", size = 1574316, upload-time = "2026-06-26T19:09:04.273Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/fe/43fd110b01e40da0adb7c90ac7ea744bef2d43dca00de5095fd2351c2a68/greenlet-3.5.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:2ecda9ec22edf38fa389369eaed8c3d37c05f3c54e69f69438dbb2cc1de1458b", size = 1638614, upload-time = "2026-06-26T18:31:46.297Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/7c/062447147a61f8b4337b156fe70d32a165fcf2f89d7ca6255e572806705c/greenlet-3.5.3-cp313-cp313-win_amd64.whl", hash = "sha256:c82304750f057167ff60d188df1d0cc1764ce9567eadf03e6a7443bcedd0b30b", size = 239850, upload-time = "2026-06-26T18:21:54.613Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/7e/220a7f5824a64a60443fc03b39dfac4ea63a7fb6d481efa27eafa928e7f4/greenlet-3.5.3-cp313-cp313-win_arm64.whl", hash = "sha256:dc133a1569ee667b2a6ef56ce551084aeefd87a5acbc4736d336d1e2edc6cfc4", size = 238141, upload-time = "2026-06-26T18:22:48.507Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/93/43e116ee114b28737ba7e12952a0d4e2f55944d0f84e42bc91ba7192a3c9/greenlet-3.5.3-cp314-cp314-macosx_11_0_universal2.whl", hash = "sha256:fd2e02fa07485778536a036222d616ab957b1d533f36b3ed98ce725d9c9d3117", size = 288202, upload-time = "2026-06-26T18:23:49.604Z" },
+    { url = "https://files.pythonhosted.org/packages/82/2f/146d218299046a43d1f029fd544b3d110d0f175a09c715c7e8da4a4a345d/greenlet-3.5.3-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:df0a0628d1597eb0897b62f55d1343f772405fd25f3b2a796c76874b0c2e22e8", size = 654096, upload-time = "2026-06-26T19:07:12.71Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/cc/04738cafb3f45fa991ea44f9de94c47dcec964f5a972300988a6751f49d9/greenlet-3.5.3-cp314-cp314-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:ebd933a6adabc298bab47731a130fe6bfb888bd934eee37810f151159544540d", size = 666304, upload-time = "2026-06-26T19:10:09.503Z" },
+    { url = "https://files.pythonhosted.org/packages/86/a9/73fa62893d5b84b4205544e6b673c654cc43aa5b9899bac00f04d64af73d/greenlet-3.5.3-cp314-cp314-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:8d19fe6c39ebff9259f07bcc685d3290f8fa4ea2278e51dd0008e4d6b0f2d814", size = 670657, upload-time = "2026-06-26T19:24:19.967Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/aa/4e0dad5e605c270c784ab911c43da6adb136ccd4d81180f763ca429a723d/greenlet-3.5.3-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4b9d501b40e80b70e32323c799dd9b420a5577a9601469d362ae1ffb690f3a7c", size = 663635, upload-time = "2026-06-26T18:32:20.802Z" },
+    { url = "https://files.pythonhosted.org/packages/29/7e/2ffce64929fb3cab7b65d5a0b20aaf9764e227681d731b041077fc9a525a/greenlet-3.5.3-cp314-cp314-manylinux_2_39_riscv64.whl", hash = "sha256:962c5df2db8cb446da51edf1ca5296c389d93b99c9d8aa2ee4c7d0d8f1218260", size = 473497, upload-time = "2026-06-26T19:25:39.421Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/50/13efdbea246fe3d3b735e191fec08fb50809f53cd2383ebe123d0809e44b/greenlet-3.5.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:a1fad1d11e7d6aab184107baa8e4ece11ccba3ec9599cd7efa5ff4d70d43256a", size = 1621252, upload-time = "2026-06-26T19:09:05.647Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/22/c0a336ae4a1410fd5f5121098e5bfbf1865f64c5ef80b4b5412886c4a332/greenlet-3.5.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:fad5aec764399f1b5cc347ad250a59660f20c8f8888ea6bae1f93b769cce1154", size = 1684824, upload-time = "2026-06-26T18:31:47.738Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/94/91aec0030bea75c4b3244251d0de60a1f3432d1ecb53ab6c437fb5c3ba61/greenlet-3.5.3-cp314-cp314-win_amd64.whl", hash = "sha256:7669aa24cf2a1041d6f7899575b494a3ab4cf68bfcc8609b1dc0be7272db835e", size = 240754, upload-time = "2026-06-26T18:22:15.669Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/06/68d0983e79e02138f64b4d303c500c27ddb48e5e77f3debb80888a921eae/greenlet-3.5.3-cp314-cp314-win_arm64.whl", hash = "sha256:5b4807c4082c9d1b6d9eed56fcd041863e37f2228106eef24c30ca096e238605", size = 239549, upload-time = "2026-06-26T18:22:42.996Z" },
+    { url = "https://files.pythonhosted.org/packages/91/95/3e161213d7f1d378d15aa9e792093e9bfe01844680d04b7fd6e0107c9098/greenlet-3.5.3-cp314-cp314t-macosx_11_0_universal2.whl", hash = "sha256:271a8ea7c1024e8a0d7dd2be66dd66dda8a07193f41a17b9e924f7600f5b62be", size = 296389, upload-time = "2026-06-26T18:22:20.657Z" },
+    { url = "https://files.pythonhosted.org/packages/00/92/715c44721abe2b4d1ae9abde4179411868a5bff312479f54e105d372f131/greenlet-3.5.3-cp314-cp314t-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:19131729ae0ddc3c2e1ef85e650169b5e37ee32e400f215f78b94d7b0d567310", size = 653382, upload-time = "2026-06-26T19:07:14.209Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/83/37a10372a1090a6624cca8e74c12df1a36c2dc36429ed0255b7fb1aeee23/greenlet-3.5.3-cp314-cp314t-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:1540dd8e5fc2a5aec40fbb98ef8e149fa47c89a4b4a1cf2575a14d3d1869d7a8", size = 659401, upload-time = "2026-06-26T19:10:10.876Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/73/8faec206b851c22b1733545fda900829a1f3f5b1c78ae7e0fb3dba57d9f4/greenlet-3.5.3-cp314-cp314t-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b897d97759425953f69a9c0fac67f8fe333ec0ce7377ef186fb2b0c3ad5e354d", size = 659582, upload-time = "2026-06-26T19:24:21.357Z" },
+    { url = "https://files.pythonhosted.org/packages/db/e2/d1509cad4207da559cc42986ecdd8fc67ad0d1bba2bf03023c467fd5e0f3/greenlet-3.5.3-cp314-cp314t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e81fa194a1d20967877bdf9c7794db2bc99063e5be36aee710c08f04c5bb087f", size = 656969, upload-time = "2026-06-26T18:32:22.272Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/55/50c19e49f8045834ada71ef12f8ad048eba8517c6aa41161bed676328fae/greenlet-3.5.3-cp314-cp314t-manylinux_2_39_riscv64.whl", hash = "sha256:3236754d423955ea08e9bb5f6c04a7895f9e22c290b66aa7653fcb922d839eb0", size = 491037, upload-time = "2026-06-26T19:25:40.672Z" },
+    { url = "https://files.pythonhosted.org/packages/86/7d/eaf70de20aadca3a5884aec58362861c64ce45e7b277f47ed026926a3b89/greenlet-3.5.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:55cf4d777485d43110e47133cbba6d74a8885a87ec1227ef0267f9ee80c5aa21", size = 1617822, upload-time = "2026-06-26T19:09:06.893Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/f9/414d38fc400ae4350d4185eaad1827676f7cf5287b9136e0ed1cbbe20a7f/greenlet-3.5.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:12a248ba75f6a9a236375f52296c498c89ff1d8badf32deb9eca7abd5853f7da", size = 1677983, upload-time = "2026-06-26T18:31:49.396Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/15/7edb977e08f9bff702fe42d6c902702786ff6b9694058b4e6a2a6ac90e57/greenlet-3.5.3-cp314-cp314t-win_amd64.whl", hash = "sha256:efc6bd60ea02e085862c74a3ef64b147ffc6f1a5ea7d9f26e7a939943f68c1e3", size = 243626, upload-time = "2026-06-26T18:24:41.485Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/8a/93928dce91e6b3598b5e779e8d1fd6576a504640c58e78627077f6a7a91a/greenlet-3.5.3-cp315-cp315-macosx_11_0_universal2.whl", hash = "sha256:ea03f2f04367845d6b58eeed276e1e56e51f0b97d8ad5a88a7d20a91dc9056cc", size = 288860, upload-time = "2026-06-26T18:22:48.07Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/ca/69db42d447a1378043e2c8f19c09cbbd1263371505053c496b49066d3d16/greenlet-3.5.3-cp315-cp315-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:78dbef602fda6d97d957eb7937f70c9ce9e9527330347f8f6b6f9e554a9e7a47", size = 659747, upload-time = "2026-06-26T19:07:15.565Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/0b/af7ac2ef8dd41e3da1a40dda6305c23b9a03e13ba975ec916357b50f8575/greenlet-3.5.3-cp315-cp315-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:6f73857adb8fee13fa56c172bd11262f888c0c648f9fea113e777bb2c7904a81", size = 670419, upload-time = "2026-06-26T19:10:12.293Z" },
+    { url = "https://files.pythonhosted.org/packages/25/aa/952cf28c2ff949a8c971134fb43854dd7eaa737218723aaef758f8c9aead/greenlet-3.5.3-cp315-cp315-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:cefa9cef4b371f9844c6053db71f1138bc6807bab1578b0dae5149c1f1141357", size = 674261, upload-time = "2026-06-26T19:24:22.79Z" },
+    { url = "https://files.pythonhosted.org/packages/51/1e/1d51640cacbfc455dbe9f9a9f594c49e4e244f63b9971a2f4764e46cc53d/greenlet-3.5.3-cp315-cp315-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:232fec92e823addaf02d9472cf7381e24a1d046a6ced1103c5caa4c21b9dfc1d", size = 668787, upload-time = "2026-06-26T18:32:24.298Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/f2/b00d6f5e63e531a93562b2ec1a4c320fbee91f580fc42e6417af69d706e5/greenlet-3.5.3-cp315-cp315-manylinux_2_39_riscv64.whl", hash = "sha256:6219b6d04dbf6ba6084d77dc609e8473060dc55f759cbf626d512122781fa128", size = 480322, upload-time = "2026-06-26T19:25:41.852Z" },
+    { url = "https://files.pythonhosted.org/packages/21/66/4030d5b0b5894500023f003bb054d9bb354dfbd1e186c3a296759172f5f5/greenlet-3.5.3-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:2421c3564da9429d5586d46ca31ebb26516b5498a802cf65c041a8e8a8980d34", size = 1626305, upload-time = "2026-06-26T19:09:08.281Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/50/5221371c7550108dfa3c378debc41d032aa9c78e89abb01d8011cfc93289/greenlet-3.5.3-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:e0f0d160f0b2e558e6c75f7930967183255dc9735e5f5b8cae58ee09c9576d8b", size = 1688631, upload-time = "2026-06-26T18:31:51.278Z" },
+    { url = "https://files.pythonhosted.org/packages/68/5d/00d469daae3c65d2bf620b10eee82eb022127d483c6bc8c69fae6f3fbf17/greenlet-3.5.3-cp315-cp315-win_amd64.whl", hash = "sha256:dd99329bbc15ca78dcc583dba05d0b1b0bae01ab6c2174989f5aaee3e41ac930", size = 241027, upload-time = "2026-06-26T18:22:38.203Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/e8/883785b44c5780ed71e83d3e4437e710470be17a2e181e8b601e2da0dc4a/greenlet-3.5.3-cp315-cp315-win_arm64.whl", hash = "sha256:499fef2acede88c1864a57bb586b4bf533c81e1b82df7ab93451cdb47dfec227", size = 240085, upload-time = "2026-06-26T18:23:54.217Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/da/4f4a8450962fad137c1c8981a3f1b8919d06c829993d4d476f9c525d5173/greenlet-3.5.3-cp315-cp315t-macosx_11_0_universal2.whl", hash = "sha256:176bc16a721fa5fc294d70b87b4dfa5fbdd251b3da5d5372735ecef9bd7d6d0c", size = 297221, upload-time = "2026-06-26T18:23:27.176Z" },
+    { url = "https://files.pythonhosted.org/packages/57/66/b3bfae3e220a9b63ea539a0eea681800c69ab1aada757eae8789f183e7ce/greenlet-3.5.3-cp315-cp315t-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:629b614d2b786e89c50440e246f33eea78f58a962d0bdbbcc809e6d13605903f", size = 657221, upload-time = "2026-06-26T19:07:16.973Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/81/b6d4d73a709684fc77e7fa034d7c2fe82cffa9fc920fadcaa659c2626213/greenlet-3.5.3-cp315-cp315t-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:2b2e857ae16f5f72142edf75f9f176fe7526ba19a2841df1420516f83831c9f2", size = 663226, upload-time = "2026-06-26T19:10:13.723Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/39/0e0938a75115b939d42733a2a12e1d349653c9531fe6fe563e8a681f04e6/greenlet-3.5.3-cp315-cp315t-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:16d192579ed281051396dddd7f7754dac6259e6b1fb26378c87b66622f8e3f91", size = 663706, upload-time = "2026-06-26T19:24:24.312Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/07/e210b02b589f16e74ff48b730690e4a34ffe984219fce4f3c1a0e7ec8545/greenlet-3.5.3-cp315-cp315t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e515757e2e36bcbf1fad09a46e1557e8b1ae1797d4b44d09da7deed88ad28608", size = 660802, upload-time = "2026-06-26T18:32:26.081Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/41/35d1c678cdb3c3b9e6bee691728e563cfb294202b23c7a4c3c2ccc343589/greenlet-3.5.3-cp315-cp315t-manylinux_2_39_riscv64.whl", hash = "sha256:4399eb8d041f20b68d943918bc55502a93d6fdc0a37c14da7881c04139acee9d", size = 498803, upload-time = "2026-06-26T19:25:43.063Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/2e/5303eb3fa06bca089060f479707182a93e360683bc252acf846c3090d34e/greenlet-3.5.3-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:b363d46ed1ea431825fdb01471bb024fc08399bad1572a616e853c7684415adb", size = 1622157, upload-time = "2026-06-26T19:09:09.527Z" },
+    { url = "https://files.pythonhosted.org/packages/54/70/50de47a488f14df260b50ae34fb5d56016e308b098eab02c878b5223c26a/greenlet-3.5.3-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:e44da2f5bbdaabaf7d80b73dbb430c7035771e9f244e3c8b769715c9d8fa0a16", size = 1681159, upload-time = "2026-06-26T18:31:52.986Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/13/1055e1dda7882073eda533e2b96c62e55bbd2db7fda6d5ece992febc7071/greenlet-3.5.3-cp315-cp315t-win_amd64.whl", hash = "sha256:8ff8bed3e3baa20a3ea261ce00526f1898ad4801d4886fd2220580ee0ad8fadf", size = 244007, upload-time = "2026-06-26T18:22:04.353Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/0d/ca7d15afbdc397e3401134c9e1800d51d12b829661786187a4ad08fe484f/greenlet-3.5.3-cp315-cp315t-win_arm64.whl", hash = "sha256:b7068bd09f761f3f5b4d214c2bed063186b2a86148c740b3873e3f56d79bac31", size = 242586, upload-time = "2026-06-26T18:23:37.93Z" },
+]
+
 [[package]]
 name = "idna"
 version = "3.13"
@@ -127,14 +213,60 @@ wheels = [
 
 [[package]]
 name = "jiangchang-platform-kit"
-version = "0.1.0"
+version = "1.0.15"
 source = { editable = "." }
 dependencies = [
+    { name = "mss" },
+    { name = "playwright" },
     { name = "requests" },
 ]
 
 [package.metadata]
-requires-dist = [{ name = "requests", specifier = ">=2.31.0" }]
+requires-dist = [
+    { name = "mss", specifier = ">=9.0.1" },
+    { name = "playwright", specifier = ">=1.42.0" },
+    { name = "requests", specifier = ">=2.31.0" },
+]
+
+[[package]]
+name = "mss"
+version = "10.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e5/5d/eee782a6d674f562c946ae6a026f4c595ea2b7b031f290bf9fbf60da09b5/mss-10.2.0.tar.gz", hash = "sha256:ab271860775545e62f29d7b11f82f279ac1048f5bbdd26cfad84830208dbd393", size = 200317, upload-time = "2026-04-23T10:44:57.305Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f2/c3/313e14f245c79b4c05bd0f3a84a4813aa26fa10f8993aebd91d04c5fad3f/mss-10.2.0-py3-none-any.whl", hash = "sha256:e79f428899280e7e64e38365b5bfed683851ebea807eeaeadaf06eb8e0d67197", size = 67106, upload-time = "2026-04-23T10:44:56.266Z" },
+]
+
+[[package]]
+name = "playwright"
+version = "1.60.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "greenlet" },
+    { name = "pyee" },
+]
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/21/f0/832bd9677194908da118064eef20082f2791e3d18215cc6d9391ee2c5a67/playwright-1.60.0-py3-none-macosx_10_13_x86_64.whl", hash = "sha256:6a8cd0fec171fb3089e95e898c8bc8a6f35dea0b78b399e12fcc19427e91b1d7", size = 43474635, upload-time = "2026-05-18T12:00:31.969Z" },
+    { url = "https://files.pythonhosted.org/packages/59/7b/e1d32ae8a3ed937ec2be3721c5f728b13d731a0b7c6442e0b3bec5094ac0/playwright-1.60.0-py3-none-macosx_11_0_arm64.whl", hash = "sha256:39b5420ba6145045b69ced4c5c47d4d9fe5bddfc8ff816c518913afcb25ec7a5", size = 42261327, upload-time = "2026-05-18T12:00:35.638Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/bc/23de499ded6411c188a20c5a0dea6f0cd4ed5d2b3cc6042a5dbd3ed609aa/playwright-1.60.0-py3-none-macosx_11_0_universal2.whl", hash = "sha256:2581d0e6a3392c71f91b27460c7fd093356818dc430f48153896c8aeeaef7705", size = 43474636, upload-time = "2026-05-18T12:00:39.294Z" },
+    { url = "https://files.pythonhosted.org/packages/22/7b/1d679f4fced4ea94efadd17103856d8c565384f68382a1681264e46f5925/playwright-1.60.0-py3-none-manylinux1_x86_64.whl", hash = "sha256:1c2bfae7884fb3fb05b853290eab8f343d524e5016f2f1def702acbbdf14c93e", size = 47467220, upload-time = "2026-05-18T12:00:43.179Z" },
+    { url = "https://files.pythonhosted.org/packages/84/c2/1528d267d4442bd2c6b8eaeab819dd52c2030bf80e89293f0ba1f687473b/playwright-1.60.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:43e66564125ee31b07a58cefb21e256d62d67d8d1713e6858df7a3019d8ed353", size = 47154856, upload-time = "2026-05-18T12:00:46.715Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/4e/b008b6440a7a1624378041da94829956d4b8f7ab9ef5aad22d0dc3f2e26d/playwright-1.60.0-py3-none-win32.whl", hash = "sha256:ec94e416ea320711e0ad4bf185dcbf41833672961e90773e1885255d7db7b7e7", size = 37902157, upload-time = "2026-05-18T12:00:50.374Z" },
+    { url = "https://files.pythonhosted.org/packages/55/f0/0541524133104f9cc20bf900870ff4a736b76a23483f3a55295ddfa58409/playwright-1.60.0-py3-none-win_amd64.whl", hash = "sha256:9566821ce6030a1f9e7146a24e19355ab0d98805fd0f9be50bb3d8fef1750c02", size = 37902159, upload-time = "2026-05-18T12:00:53.728Z" },
+    { url = "https://files.pythonhosted.org/packages/80/c8/210f282d278e4709cdd71b12a31af45a30a22ab3207b387e29b37e478713/playwright-1.60.0-py3-none-win_arm64.whl", hash = "sha256:6e4f6700a4c2250efff8e690a81d66e3855754fb587b6b87cf5c784014f91537", size = 34037981, upload-time = "2026-05-18T12:00:57.584Z" },
+]
+
+[[package]]
+name = "pyee"
+version = "13.0.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8b/04/e7c1fe4dc78a6fdbfd6c337b1c3732ff543b8a397683ab38378447baa331/pyee-13.0.1.tar.gz", hash = "sha256:0b931f7c14535667ed4c7e0d531716368715e860b988770fc7eb8578d1f67fc8", size = 31655, upload-time = "2026-02-14T21:12:28.044Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a0/c4/b4d4827c93ef43c01f599ef31453ccc1c132b353284fc6c87d535c233129/pyee-13.0.1-py3-none-any.whl", hash = "sha256:af2f8fede4171ef667dfded53f96e2ed0d6e6bd7ee3bb46437f77e3b57689228", size = 15659, upload-time = "2026-02-14T21:12:26.263Z" },
+]
 
 [[package]]
 name = "requests"
@@ -151,6 +283,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d7/8e/7540e8a2036f79a125c1d2ebadf69ed7901608859186c856fa0388ef4197/requests-2.33.1-py3-none-any.whl", hash = "sha256:4e6d1ef462f3626a1f0a0a9c42dd93c63bad33f9f1c1937509b8c5c8718ab56a", size = 64947, upload-time = "2026-03-30T16:09:13.83Z" },
 ]
 
+[[package]]
+name = "typing-extensions"
+version = "4.15.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/94/1a15dd82efb362ac84269196e94cf00f187f7ed21c242792a923cdb1c61f/typing_extensions-4.15.0.tar.gz", hash = "sha256:0cea48d173cc12fa28ecabc3b837ea3cf6f38c6d1136f85cbaaf598984861466", size = 109391, upload-time = "2025-08-25T13:49:26.313Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl", hash = "sha256:f0fa19c6845758ab08074a0cfa8b7aecb71c999ca73d62883bc25cc018c4e548", size = 44614, upload-time = "2025-08-25T13:49:24.86Z" },
+]
+
 [[package]]
 name = "urllib3"
 version = "2.6.3"