@starreel/mcp 0.1.41 → 0.1.42

package/SKILL.md

@@ -283,6 +283,18 @@ refund on failure); you never compensate manually.
   `generate_bgm`, `replace_shot_dialogue`
 - **Finish**: `compose_episode`, `get_final_cut`, `get_export`,
   `generate_episode_poster`, `generate_cover`
+- **Assemble it yourself**: `export_handoff_pack`, `get_handoff_toolchain` —
+  download the per-shot raw clips, dialogue tracks, SFX, BGM and subtitles, then
+  decide transitions and assemble the cut on your own side. Use this instead of
+  `compose_episode` when you want to judge each seam yourself; use
+  `compose_episode` when you want the platform's finishing pipeline (pre-flight
+  checks, A/V duration parity, loudness mastering). Three facts that will bite you:
+  `audio_contract.mode="tts"` means the raw clips have **no voice** (dialogue ships
+  separately — skip it and the episode is silent); every shot must be cut to
+  `trim_head_ms`/`duration_ms` or you splice in frames the platform already QC'd out;
+  and all subtitle/dialogue/SFX offsets are relative to **each shot's own trimmed
+  start**, not to the final timeline — add whatever overlapping transitions you like
+  and let `compile_timeline.py` expand them, never hand-compute the shift.
 - **Edit**: `edit_video_shot`, `regenerate_shot_video`, `split_shot`,
   `trim_shot`, `rerender_episode`
 - **Read back (all free)**: `list_dramas`, `get_drama`, `get_characters`,

package/assets/handoff/assemble.sh

@@ -0,0 +1,340 @@
+#!/usr/bin/env bash
+# assemble.sh — 素材交接包装配参考实现 v0.1（硬切基线）
+#
+# 先跑通这个基线，再去改转场。它证明素材包是完整的：拼接、对白、音效、配乐、
+# 字幕、响度六件事全部到位，音画同步。转场是唯一留给你改的东西。
+#
+# 用法:
+#   ./assemble.sh <包目录> [输出文件] [转场计划.json]
+#
+# 依赖: ffmpeg (≥4.4), ffprobe, jq, python3
+set -euo pipefail
+
+PACK="${1:?用法: assemble.sh <包目录> [输出文件] [转场计划.json]}"
+OUT="${2:-episode_out.mp4}"
+PLAN="${3:-}"
+BUILD="${PACK}/build"
+TMP="${BUILD}/tmp"
+mkdir -p "${TMP}"
+
+for bin in ffmpeg ffprobe jq python3; do
+  command -v "${bin}" >/dev/null || { echo "缺少依赖: ${bin}" >&2; exit 1; }
+done
+
+# 字幕烧录需要 ffmpeg 编译时启用 libass。很多发行版/homebrew 的 ffmpeg 没带，
+# 且缺失时 subtitles 滤镜直接不存在 —— 必须在这里查，不能等跑完四阶段转码才崩。
+if ffmpeg -hide_banner -filters 2>/dev/null | grep -qE '[[:space:]]subtitles[[:space:]]'; then
+  HAS_LIBASS=1
+else
+  HAS_LIBASS=0
+  echo "注意: 本机 ffmpeg 未启用 libass（无 subtitles 滤镜），字幕将以软字幕轨输出而非烧录。" >&2
+  echo "      要烧录字幕请装带 libass 的 ffmpeg：brew install ffmpeg 或自行 --enable-libass 编译。" >&2
+fi
+
+# ── 阶段 1：编译时间轴（镜相对锚点 → 绝对时间码）────────────────────────────
+echo "==> [1/6] 编译时间轴"
+if [ -n "${PLAN}" ]; then
+  python3 "$(dirname "$0")/compile_timeline.py" "${PACK}" --transitions "${PLAN}" --outdir "${BUILD}"
+else
+  python3 "$(dirname "$0")/compile_timeline.py" "${PACK}" --outdir "${BUILD}"
+fi
+OFF="${BUILD}/offsets.json"
+
+W=$(jq -r '.render_target.width'  "${OFF}")
+H=$(jq -r '.render_target.height' "${OFF}")
+FPS=$(jq -r '.render_target.fps'  "${OFF}")
+VB=$(jq -r '.render_target.video_bitrate' "${OFF}")
+AB=$(jq -r '.render_target.audio_bitrate' "${OFF}")
+MODE=$(jq -r '.audio_contract.mode' "${OFF}")
+LN_I=$(jq -r '.audio_contract.loudnorm.I'   "${OFF}")
+LN_TP=$(jq -r '.audio_contract.loudnorm.TP' "${OFF}")
+LN_LRA=$(jq -r '.audio_contract.loudnorm.LRA' "${OFF}")
+TOTAL_MS=$(jq -r '.total_ms' "${OFF}")
+# 调色查找表：平台的 LUT 在终拼时施加，裸片是未调色的。有它就在规范化这一步顺手烤进去，
+# 成片色彩才与平台一致。用 filter_complex 的真实输入而不是 movie= —— 后者要对路径里的
+# 空格/冒号做转义，包目录一旦带空格就会静默失败。
+LUT_REL=$(jq -r '.render_target.color_lut.file // empty' "${OFF}")
+LUT_FILE=""
+if [ -n "${LUT_REL}" ] && [ -f "${PACK}/${LUT_REL}" ]; then
+  LUT_FILE="${PACK}/${LUT_REL}"
+  echo "  调色查找表: ${LUT_REL}"
+fi
+NSHOTS=$(jq -r '.shots | length' "${OFF}")
+
+# 有无重叠决定阶段 3 走哪条路：全硬切走 concat demuxer 快路径（-c copy，秒级）；
+# 一旦有重叠就必须整图 filter_complex 重编码。
+MAXOV=$(jq -r '[.shots[].overlap_ms] | max' "${OFF}")
+[ "${MAXOV}" = "null" ] && MAXOV=0
+
+ms2s() { awk -v m="$1" 'BEGIN{printf "%.3f", m/1000}'; }
+
+# ── 阶段 2：逐镜规范化（trim + 统一编码 + 组装该镜音轨）─────────────────────
+echo "==> [2/6] 规范化 ${NSHOTS} 个镜头"
+: > "${TMP}/concat.txt"
+for i in $(seq 0 $((NSHOTS - 1))); do
+  S=$(jq -c ".shots[${i}]" "${OFF}")
+  N=$(jq -r '.shot_number' <<<"${S}")
+  SRC="${PACK}/$(jq -r '.file' <<<"${S}")"
+  SS=$(ms2s "$(jq -r '.trim_head_ms' <<<"${S}")")
+  DUR=$(ms2s "$(jq -r '.duration_ms' <<<"${S}")")
+  BAKED=$(jq -r '.has_baked_audio' <<<"${S}")
+  DST="${TMP}/shot_$(printf '%03d' "${N}").mkv"
+
+  # 中间产物一律 mkv + pcm_s16le：aac 每段都带 ~21ms(1024 samples) 编码器 priming
+  # delay，走 adelay/amix 时每镜音频会整体提前约半帧，重叠转场下误差还会叠加。
+  # 只在阶段 4 最后一次编 aac。
+  # 视频：先 trim 再统一到目标画布/帧率。scale+pad 保证不同源尺寸也能拼。
+  VF="scale=${W}:${H}:force_original_aspect_ratio=decrease,pad=${W}:${H}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=${FPS}"
+
+  # baked-cut（闪白/闪黑）：硬切 + 本镜片头快速过曝/压黑，**不重叠**。
+  # 平台实测：这类效果走 xfade 会变成双重闪 + 130ms 重叠 + 口型/音频瞬断，
+  # 所以它烤在片头、不进 xfade 链。
+  RENDER=$(jq -r '.transition.render // "cut"' <<<"${S}")
+  if [ "${RENDER}" = "baked-cut" ]; then
+    FLASH=$(jq -r '.transition.flash // "white"' <<<"${S}")
+    FMS=$(jq -r '.transition.duration_ms // 130' <<<"${S}")
+    VF="${VF},fade=t=in:st=0:d=$(ms2s "${FMS}"):color=${FLASH}"
+  fi
+
+  INPUTS=(-ss "${SS}" -t "${DUR}" -i "${SRC}")
+  if [ "${MODE}" = "clip" ] && [ "${BAKED}" = "true" ]; then
+    # 裸片自带人声：直接用它的音轨，绝不再叠对白（叠了就是双声）
+    if [ -n "${LUT_FILE}" ]; then
+      ffmpeg -hide_banner -loglevel error -y "${INPUTS[@]}" -i "${LUT_FILE}" \
+        -filter_complex "[0:v]${VF}[g];[g][1:v]haldclut[v]" \
+        -map "[v]" -map 0:a:0? \
+        -c:v libx264 -b:v "${VB}" -pix_fmt yuv420p -c:a pcm_s16le -ar 48000 -ac 2 \
+        -shortest "${DST}"
+    else
+      ffmpeg -hide_banner -loglevel error -y "${INPUTS[@]}" \
+        -vf "${VF}" -map 0:v:0 -map 0:a:0? \
+        -c:v libx264 -b:v "${VB}" -pix_fmt yuv420p -c:a pcm_s16le -ar 48000 -ac 2 \
+        -shortest "${DST}"
+    fi
+  else
+    # TTS 模式：裸片无人声。静音底 + 对白 + 音效，全部按镜内 offset 落位。
+    # 输入索引是固定契约：0=静音底  1=视频  2..=对白/音效（按下面的追加顺序）
+    INPUTS=(-f lavfi -t "${DUR}" -i "anullsrc=r=48000:cl=stereo"
+            -ss "${SS}" -t "${DUR}" -i "${SRC}")
+    FILTER=""; LABELS="[0:a]"; IDX=2
+
+    DLG=$(jq -c '.dialogue // empty' <<<"${S}")
+    if [ -n "${DLG}" ] && [ "${DLG}" != "null" ]; then
+      DOFF=$(jq -r '.offset_ms // 0' <<<"${DLG}")
+      DGAIN=$(jq -r '.gain_db // 0' <<<"${DLG}")
+      INPUTS+=(-i "${PACK}/$(jq -r '.file' <<<"${DLG}")")
+      FILTER+="[${IDX}:a]adelay=${DOFF}|${DOFF},volume=${DGAIN}dB[d];"
+      LABELS+="[d]"; IDX=$((IDX + 1))
+    fi
+
+    NSFX=$(jq -r '.sfx | length' <<<"${S}")
+    for ((j = 0; j < NSFX; j++)); do
+      X=$(jq -c ".sfx[${j}]" <<<"${S}")
+      XOFF=$(jq -r '.offset_ms // 0' <<<"${X}")
+      XGAIN=$(jq -r '.gain_db // 0' <<<"${X}")
+      INPUTS+=(-i "${PACK}/$(jq -r '.file' <<<"${X}")")
+      FILTER+="[${IDX}:a]adelay=${XOFF}|${XOFF},volume=${XGAIN}dB[x${j}];"
+      LABELS+="[x${j}]"; IDX=$((IDX + 1))
+    done
+
+    # 混入静音底：amix 的 inputs = 底轨 + 对白 + 音效，normalize=0 保住各自增益
+    NMIX=$((IDX - 1))
+    FILTER+="${LABELS}amix=inputs=${NMIX}:normalize=0:dropout_transition=0[aout]"
+
+    if [ -n "${LUT_FILE}" ]; then
+      INPUTS+=(-i "${LUT_FILE}")
+      ffmpeg -hide_banner -loglevel error -y "${INPUTS[@]}" \
+        -filter_complex "${FILTER};[1:v]${VF}[g];[g][${IDX}:v]haldclut[v]" \
+        -map "[v]" -map "[aout]" -t "${DUR}" \
+        -c:v libx264 -b:v "${VB}" -pix_fmt yuv420p -c:a pcm_s16le -ar 48000 -ac 2 \
+        "${DST}"
+    else
+      ffmpeg -hide_banner -loglevel error -y "${INPUTS[@]}" \
+        -filter_complex "${FILTER}" \
+        -map 1:v:0 -vf "${VF}" -map "[aout]" -t "${DUR}" \
+        -c:v libx264 -b:v "${VB}" -pix_fmt yuv420p -c:a pcm_s16le -ar 48000 -ac 2 \
+        "${DST}"
+    fi
+  fi
+  echo "file '$(cd "$(dirname "${DST}")" && pwd)/$(basename "${DST}")'" >> "${TMP}/concat.txt"
+done
+
+# ── 阶段 3：拼接 ───────────────────────────────────────────────────────────
+if [ "${MAXOV}" = "0" ]; then
+  echo "==> [3/6] 拼接（全硬切，concat 快路径）"
+  ffmpeg -hide_banner -loglevel error -y -f concat -safe 0 -i "${TMP}/concat.txt" \
+    -c copy "${TMP}/cut.mkv"
+else
+  echo "==> [3/6] 拼接（含重叠转场，xfade 链）"
+  # 视频：xfade 链。**offset 直接取编译好的 in_ms，绝不手算累加** —— 每个重叠都会
+  # 让其后所有镜前移，手算的累积误差是这条路最常见的翻车原因。
+  # 音频：不做 crossfade，每镜音轨 adelay 到自己的 in_ms 再 amix。这样音频时间轴
+  # 与 xfade 后的视频天然一致；重叠量若落在上一镜镜末静音内，对白完全不受影响。
+  VIN=(); VPRE=""; VCHAIN=""; ACHAIN=""; ALABELS=""; CUR="[p0]"
+  for i in $(seq 0 $((NSHOTS - 1))); do
+    S=$(jq -c ".shots[${i}]" "${OFF}")
+    N=$(jq -r '.shot_number' <<<"${S}")
+    VIN+=(-i "${TMP}/shot_$(printf '%03d' "${N}").mkv")
+    IN_MS=$(jq -r '.in_ms' <<<"${S}")
+    # settb=AVTB 是 xfade 的硬前提：xfade 要求两路输入 timebase 完全一致，而
+    # concat filter 输出 1/1000000、解码器给的常是 1/12288 —— 不统一直接报
+    # "timebase do not match"。★顺序不能反：fps 滤镜会把 timebase 重设成 1/fps，
+    # 写成 settb,fps 等于白设，必须 fps 在前、settb 收尾。
+    VPRE+="[${i}:v]fps=${FPS},format=yuv420p,settb=AVTB[p${i}];"
+    ACHAIN+="[${i}:a]adelay=${IN_MS}|${IN_MS}[a${i}];"
+    ALABELS+="[a${i}]"
+    [ "${i}" -eq 0 ] && continue
+    OV=$(jq -r '.overlap_ms' <<<"${S}")
+    if [ "${OV}" -gt 0 ]; then
+      XF=$(jq -r '.transition.xfade // "fade"' <<<"${S}")
+      VCHAIN+="${CUR}[p${i}]xfade=transition=${XF}:duration=$(ms2s "${OV}"):offset=$(ms2s "${IN_MS}")[v${i}];"
+    else
+      VCHAIN+="${CUR}[p${i}]concat=n=2:v=1:a=0[v${i}];"
+    fi
+    CUR="[v${i}]"
+  done
+  ACHAIN+="${ALABELS}amix=inputs=${NSHOTS}:normalize=0:dropout_transition=0[aout]"
+  ffmpeg -hide_banner -loglevel error -y "${VIN[@]}" \
+    -filter_complex "${VPRE}${VCHAIN}${ACHAIN}" \
+    -map "${CUR}" -map "[aout]" \
+    -c:v libx264 -b:v "${VB}" -pix_fmt yuv420p -c:a pcm_s16le -ar 48000 -ac 2 \
+    "${TMP}/cut.mkv"
+fi
+
+# ── 阶段 4：配乐 + 侧链避让 + 响度 ─────────────────────────────────────────
+echo "==> [4/6] 配乐与混音"
+# 限幅阈值 = 10^(TP/20)，与母带的 TP 目标同一个数
+LIMIT=$(awk -v tp="${LN_TP}" 'BEGIN{printf "%.4f", 10 ^ (tp/20)}')
+NBGM=$(jq -r '.bgm | length' "${OFF}")
+if [ "${NBGM}" -gt 0 ]; then
+  BI=(); BF=""; BL=""
+  for i in $(seq 0 $((NBGM - 1))); do
+    B=$(jq -c ".bgm[${i}]" "${OFF}")
+    BI+=(-i "${PACK}/$(jq -r '.file' <<<"${B}")")
+    BOFF=$(jq -r '.in_ms' <<<"${B}")
+    BGAIN=$(jq -r '.gain_db' <<<"${B}")
+    IDX=$((i + 1))
+    BF+="[${IDX}:a]adelay=${BOFF}|${BOFF},volume=${BGAIN}dB[b${i}];"
+    BL+="[b${i}]"
+  done
+  BF+="${BL}amix=inputs=${NBGM}:normalize=0[bgm];"
+  # 侧链源必须是**只有人声的总线**，不能用前景总轨。音效混在 sidechain 里会
+  # 让打击音/环境音也把 BGM 压下去，成片听感是配乐一惊一乍。平台侧链的 key
+  # 取自 voicebus（对白+旁白），这里照做：直接用包里的对白 wav 另拼一条 key 轨。
+  TH=$(jq -r '.audio_contract.ducking.threshold // 0.06' "${OFF}")
+  RT=$(jq -r '.audio_contract.ducking.ratio // 6' "${OFF}")
+  AT=$(jq -r '.audio_contract.ducking.attack_ms // 20' "${OFF}")
+  RL=$(jq -r '.audio_contract.ducking.release_ms // 350' "${OFF}")
+  MU=$(jq -r '.audio_contract.ducking.makeup // 1' "${OFF}")
+  DUCK_ARGS="threshold=${TH}:ratio=${RT}:attack=${AT}:release=${RL}:makeup=${MU}"
+
+  # 对白 key 轨：每条对白 adelay 到「本镜入点 + 镜内 offset」。
+  KEY_IN=(); KEYF=""; KEYL=""; KN=0
+  KIDX=$((NBGM + 1))   # 输入 0 是拼好的画面，1..NBGM 是配乐，对白从这里接着排
+  for i in $(seq 0 $((NSHOTS - 1))); do
+    S=$(jq -c ".shots[${i}]" "${OFF}")
+    DF=$(jq -r '.dialogue.file // empty' <<<"${S}")
+    [ -z "${DF}" ] && continue
+    DABS=$(( $(jq -r '.in_ms' <<<"${S}") + $(jq -r '.dialogue.offset_ms // 0' <<<"${S}") ))
+    KEY_IN+=(-i "${PACK}/${DF}")
+    KEYF+="[${KIDX}:a]adelay=${DABS}|${DABS}[k${KN}];"
+    KEYL+="[k${KN}]"; KN=$((KN + 1)); KIDX=$((KIDX + 1))
+  done
+
+  if [ "${KN}" -gt 0 ]; then
+    BF+="${KEYF}${KEYL}amix=inputs=${KN}:normalize=0[voicekey];"
+    BF+="[bgm][voicekey]sidechaincompress=${DUCK_ARGS}[duck];"
+    BF+="[0:a][duck]amix=inputs=2:normalize=0[mix];"
+  else
+    # 原声（clip）模式：人声烤在画面音轨里，拆不出独立 key —— 只能拿前景总轨当
+    # sidechain，音效会误触发避让。要精确避让就得回平台侧终拼。
+    BF+="[0:a]asplit=2[fg][sc];"
+    BF+="[bgm][sc]sidechaincompress=${DUCK_ARGS}[duck];"
+    BF+="[fg][duck]amix=inputs=2:normalize=0[mix];"
+  fi
+  # 这里**不做 loudnorm**。单 pass loudnorm 是动态归一化：对白间隙里 BGM 成了
+  # 唯一能量源，会被逐段上提到目标响度，把混音里刻意压低的 BGM"补偿"回可闻——
+  # 平台生产实锤过"BGM 增益 -45 和 -57 出来一样响、调几轮没变化"。响度统一交给
+  # 阶段 6 的两 pass 线性母带（全片恒定增益、轨间比例保持）。这里只削峰防削波。
+  BF+="[mix]alimiter=limit=${LIMIT}:level=0[amaster]"
+  ffmpeg -hide_banner -loglevel error -y -i "${TMP}/cut.mkv" "${BI[@]}" ${KEY_IN[@]+"${KEY_IN[@]}"} \
+    -filter_complex "${BF}" -map 0:v -map "[amaster]" \
+    -c:v copy -c:a aac -b:a "${AB}" -shortest "${TMP}/mixed.mp4"
+else
+  ffmpeg -hide_banner -loglevel error -y -i "${TMP}/cut.mkv" \
+    -af "alimiter=limit=${LIMIT}:level=0" \
+    -c:v copy -c:a aac -b:a "${AB}" "${TMP}/mixed.mp4"
+fi
+
+# ── 阶段 5：字幕烧录 ───────────────────────────────────────────────────────
+echo "==> [5/6] 字幕"
+SRT="${BUILD}/episode.srt"
+if [ ! -s "${SRT}" ]; then
+  cp "${TMP}/mixed.mp4" "${TMP}/subbed.mp4"
+elif [ "${HAS_LIBASS}" = "1" ]; then
+  FONTDIR="${PACK}/fonts"
+  MARGIN=$(jq -r '.subtitle_contract.margin_v // 80' "${PACK}/manifest.json")
+  # 字体必须来自包内 fonts/ —— 你的机器上没有我方字体时会静默退回默认字体，
+  # 成片字幕观感与预期不符，且不会报错。
+  ffmpeg -hide_banner -loglevel error -y -i "${TMP}/mixed.mp4" \
+    -vf "subtitles=${SRT}:fontsdir=${FONTDIR}:force_style='MarginV=${MARGIN}'" \
+    -c:v libx264 -b:v "${VB}" -pix_fmt yuv420p -c:a copy "${TMP}/subbed.mp4"
+else
+  # 降级：软字幕轨。播放器能开关，但不是发布用的烧录版 —— 竖屏平台一律要烧录。
+  ffmpeg -hide_banner -loglevel error -y -i "${TMP}/mixed.mp4" -i "${SRT}" \
+    -map 0 -map 1 -c copy -c:s mov_text "${TMP}/subbed.mp4"
+  echo "  ⚠️ 字幕以软轨输出（本机无 libass），发布前需在带 libass 的机器上重跑烧录。" >&2
+fi
+
+# ── 阶段 6：两 pass 线性母带 ────────────────────────────────────────────────
+echo "==> [6/6] 响度母带"
+# pass1 只测量，pass2 带 measured_* + linear=true 施加**恒定**增益。
+# LRA 用 7（交付母带刻意比逐镜混音的 11 收窄动态），与平台终拼一致。
+# 测量失败就回退单 pass 动态模式 —— 有瑕疵但不阻塞交付，与平台行为一致。
+MASTER_LRA=7
+STATS=$(ffmpeg -hide_banner -nostats -i "${TMP}/subbed.mp4" -vn \
+  -af "loudnorm=I=${LN_I}:TP=${LN_TP}:LRA=${MASTER_LRA}:print_format=json" \
+  -f null /dev/null 2>&1 | sed -n '/^{/,/^}/p')
+
+if [ -n "${STATS}" ] && jq -e '.input_i' >/dev/null 2>&1 <<<"${STATS}"; then
+  MI=$(jq -r '.input_i'      <<<"${STATS}")
+  MTP=$(jq -r '.input_tp'    <<<"${STATS}")
+  MLRA=$(jq -r '.input_lra'  <<<"${STATS}")
+  MTH=$(jq -r '.input_thresh'<<<"${STATS}")
+  MOFF=$(jq -r '.target_offset' <<<"${STATS}")
+  MASTER_AF="loudnorm=I=${LN_I}:TP=${LN_TP}:LRA=${MASTER_LRA}:measured_I=${MI}:measured_TP=${MTP}:measured_LRA=${MLRA}:measured_thresh=${MTH}:offset=${MOFF}:linear=true"
+  echo "  测得 I=${MI} TP=${MTP} LRA=${MLRA} → 线性归一到 ${LN_I} LUFS"
+else
+  MASTER_AF="loudnorm=I=${LN_I}:TP=${LN_TP}:LRA=${MASTER_LRA}"
+  echo "  ⚠️ pass1 测量失败，回退单 pass 动态模式（BGM 相对响度可能被上提）" >&2
+fi
+
+# +faststart 必须带：本 pass 是最终写盘者，不带会把 moov 甩回文件尾，
+# 浏览器流播开播慢/卡顿。
+ffmpeg -hide_banner -loglevel error -y -i "${TMP}/subbed.mp4" \
+  -c:v copy -af "${MASTER_AF}" -c:a aac -b:a "${AB}" -ar 48000 \
+  -movflags +faststart "${OUT}"
+
+# ── 自检 ───────────────────────────────────────────────────────────────────
+VD=$(ffprobe -v error -select_streams v:0 -show_entries stream=duration -of csv=p=0 "${OUT}")
+AD=$(ffprobe -v error -select_streams a:0 -show_entries stream=duration -of csv=p=0 "${OUT}")
+echo "完成: ${OUT}"
+echo "  预期 $(ms2s "${TOTAL_MS}")s · 视频 ${VD}s · 音频 ${AD}s"
+awk -v v="${VD}" -v a="${AD}" 'BEGIN{ d=v-a; if(d<0)d=-d; if(d>0.5){print "  ⚠️ 音画时长差 " d "s（>0.5s 视为不同步，检查 trim 与 offset 换算）"; exit 1} }'
+
+# ═══════════════════════════════════════════════════════════════════════════
+# 加转场：写一份 plan.json 作为第三参数传进来。
+#
+#   { "transitions": [
+#       { "before_shot": 3, "type": "fade" },                  // 用预设规范时长
+#       { "before_shot": 7, "type": "flash_white" },           // baked-cut，自动不重叠
+#       { "before_shot": 9, "type": "whip_pan", "overlap_ms": 160 }  // 显式覆盖时长
+#   ] }
+#
+# type 接受三种写法：预设 id（fade / flash_white / whip_pan …）、导演语义键
+# （match_cut / smash_cut / cross_dissolve …）、或直接给 ffmpeg xfade 名。
+# 未知值退回 fade 而不是报错。
+#
+# 编译器会自动处理：其后所有镜的入点前移、字幕/音效/BGM 同步偏移、重叠超预算钳制、
+# 重叠压到对白时告警、下架转场（长叠化卡壳）告警。你不需要手算任何时间。
+# ═══════════════════════════════════════════════════════════════════════════

package/assets/handoff/compile_timeline.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""
+compile_timeline.py — 镜相对锚点 → 绝对时间码 编译器（参考实现 v0.1）
+
+素材包里的字幕/对白/音效时间全部是「相对该镜 trim 后起点」的。第三方自己拼片、
+自己加转场后，用本脚本把它们展开成自己时间轴上的绝对时间码。
+
+核心公式（唯一真相，改转场只改这里）：
+    in_ms[0] = 0
+    in_ms[i] = in_ms[i-1] + duration_ms[i-1] - overlap_ms[i]
+其中 overlap_ms[i] = 第 i 镜与上一镜的画面重叠量（硬切=0，叠化=转场时长）。
+重叠会让其后每一镜整体提前，误差累积——所以绝不要手算，交给这个脚本。
+
+用法:
+    python3 compile_timeline.py <包目录> [--transitions plan.json] [--outdir build]
+
+转场计划 plan.json（可选，不给则全片硬切）:
+    { "transitions": [ { "before_shot": 3, "type": "dissolve", "overlap_ms": 300 } ] }
+    before_shot = 该镜与它上一镜之间的转场；overlap_ms 只对重叠式转场 > 0。
+
+产物:
+    build/offsets.json   每镜绝对入点 + 总时长 + BGM 入点（assemble.sh 消费）
+    build/episode.srt    整集字幕（已按各镜入点偏移合并）
+"""
+import argparse, json, os, re, sys
+
+# ── 转场预设表 ─────────────────────────────────────────────────────────────
+# 与平台 services/timeline/transition-presets.ts 保持一致。改平台那份时同步这里。
+#   xfade  = ffmpeg xfade transition 名
+#   render = "xfade"（两镜重叠）| "baked-cut"（硬切 + 入场闪光，**不重叠**）
+PRESETS = {
+    "cut":          {"xfade": None,         "ms": 0,   "render": "cut"},
+    "fade":         {"xfade": "fade",       "ms": 500, "render": "xfade"},
+    "dissolve":     {"xfade": "dissolve",   "ms": 700, "render": "xfade"},
+    "fade_black":   {"xfade": "fadeblack",  "ms": 600, "render": "xfade"},
+    "wipe_left":    {"xfade": "wipeleft",   "ms": 500, "render": "xfade"},
+    "circle_open":  {"xfade": "circleopen", "ms": 600, "render": "xfade"},
+    "flash_white":  {"xfade": "fadewhite",  "ms": 130, "render": "baked-cut", "flash": "white"},
+    "flash_black":  {"xfade": "fadeblack",  "ms": 130, "render": "baked-cut", "flash": "black"},
+    "zoom_punch":   {"xfade": "zoomin",     "ms": 350, "render": "xfade"},
+    "whip_pan":     {"xfade": "hrwind",     "ms": 130, "render": "xfade"},
+    "glass_shatter":{"xfade": "distance",   "ms": 500, "render": "xfade"},
+    "swirl":        {"xfade": "radial",     "ms": 700, "render": "xfade"},
+    "invert_flash": {"xfade": "fadeblack",  "ms": 320, "render": "xfade"},
+    "radial_open":  {"xfade": "radial",     "ms": 650, "render": "xfade"},
+}
+
+# Wave11 导演语义键 → 预设 id。j_cut / l_cut 是纯音轨编辑，视觉上就是硬切。
+W11_TO_PRESET = {
+    "hard_cut": "cut", "j_cut": "cut", "l_cut": "cut",
+    "match_cut": "dissolve", "graphic_match": "dissolve", "cross_dissolve": "dissolve",
+    "whip_pan_trans": "whip_pan", "smash_cut": "flash_white",
+    "iris_in": "circle_open", "time_lapse_in": "dissolve",
+}
+
+# 平台 v0.9.81 下架：叠化 ≥600ms 的 xfade 类在**有对白的接缝**会做长音频交叉淡化 →
+# 卡壳（客户实测确认）。这里不禁用，但会警告并给出安全等价替代。
+DEPRECATED = {"dissolve", "fade_black", "circle_open", "swirl", "radial_open"}
+SAFE_REPLACEMENT = {
+    "dissolve": "fade", "circle_open": "fade",
+    "swirl": "flash_black", "fade_black": "flash_black", "radial_open": "flash_black",
+}
+
+
+def resolve_preset(name):
+    """转场名（预设 id / Wave11 语义键 / 裸 xfade 名）→ 预设。未知退 fade。"""
+    k = str(name or "").strip().lower()
+    if not k:
+        return "cut", PRESETS["cut"]
+    if k in W11_TO_PRESET:
+        k = W11_TO_PRESET[k]
+    if k in PRESETS:
+        return k, PRESETS[k]
+    for pid, p in PRESETS.items():          # 允许直接给 ffmpeg xfade 名
+        if p["xfade"] == k:
+            return pid, p
+    return "fade", PRESETS["fade"]
+
+
+# ── SRT ────────────────────────────────────────────────────────────────────
+TS = re.compile(r"(\d+):(\d{2}):(\d{2})[,.](\d{3})")
+
+
+def parse_srt(path):
+    """→ [(start_ms, end_ms, text)]。时间码基准 = 该镜 trim 后的第 0 毫秒。"""
+    if not path or not os.path.exists(path):
+        return []
+    blocks = re.split(r"\n\s*\n", open(path, encoding="utf-8-sig").read().strip())
+    cues = []
+    for b in blocks:
+        lines = [l for l in b.splitlines() if l.strip()]
+        if len(lines) < 2:
+            continue
+        arrow = next((l for l in lines if "-->" in l), None)
+        if not arrow:
+            continue
+        stamps = TS.findall(arrow)
+        if len(stamps) != 2:
+            continue
+        to_ms = lambda t: (int(t[0]) * 3600 + int(t[1]) * 60 + int(t[2])) * 1000 + int(t[3])
+        text = "\n".join(lines[lines.index(arrow) + 1:])
+        cues.append((to_ms(stamps[0]), to_ms(stamps[1]), text))
+    return cues
+
+
+def fmt_ms(ms):
+    ms = max(0, int(ms))
+    h, ms = divmod(ms, 3600000)
+    m, ms = divmod(ms, 60000)
+    s, ms = divmod(ms, 1000)
+    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
+
+
+def write_srt(path, cues):
+    with open(path, "w", encoding="utf-8") as f:
+        for i, (a, b, t) in enumerate(cues, 1):
+            f.write(f"{i}\n{fmt_ms(a)} --> {fmt_ms(b)}\n{t}\n\n")
+
+
+# ── 编译 ───────────────────────────────────────────────────────────────────
+def compile_timeline(pack_dir, plan_path=None, outdir=None):
+    manifest = json.load(open(os.path.join(pack_dir, "manifest.json"), encoding="utf-8"))
+    if manifest.get("manifest_version") != "0.1":
+        sys.exit(f"不认识的 manifest_version: {manifest.get('manifest_version')!r}，拒绝猜测")
+
+    overlaps, trans = {}, {}
+    if plan_path:
+        plan = json.load(open(plan_path, encoding="utf-8"))
+        for t in plan.get("transitions", []):
+            n = int(t["before_shot"])
+            pid, p = resolve_preset(t.get("type"))
+            # overlap 缺省取预设的规范时长；baked-cut 强制 0（硬切 + 入场闪光）
+            ov = int(t["overlap_ms"]) if t.get("overlap_ms") is not None else p["ms"]
+            if p["render"] != "xfade":
+                ov = 0
+            overlaps[n] = max(0, ov)
+            trans[n] = {
+                "preset_id": pid, "xfade": p["xfade"],
+                "render": p["render"], "flash": p.get("flash"),
+            }
+
+    rules = manifest.get("assembly_rules", {})
+    cap = int(rules.get("transition_budget_ms_max", 400))
+    floor = int(rules.get("min_shot_duration_ms", 800))
+
+    shots, cursor, cues, warnings = [], 0, [], []
+    prev_dur = None
+    for sh in manifest["shots"]:
+        n = int(sh["shot_number"])
+        dur = int(sh["clip"]["duration_ms"])
+        ov = overlaps.get(n, 0)
+
+        if prev_dur is not None and ov:
+            # 重叠不得超过预算，也不得吃掉相邻任一镜的最短时长
+            limit = min(cap, prev_dur - floor, dur - floor)
+            if ov > max(0, limit):
+                warnings.append(f"镜 {n}: 重叠 {ov}ms 超限，钳到 {max(0, limit)}ms")
+                ov = max(0, limit)
+            # 可借冗余 = 上一镜的「镜末静音留白 + 被掐掉的尾部」。
+            # ★ silence_after_ms 默认是 0（authoring 字段，只有 AI 填过或项目设了
+            #   pacing_curve 才非零），所以真正能借的通常是 trim_tail_ms 那 250ms。
+            #   重叠超出这个预算 = 重叠期压在对白上，声画归属模糊。
+            prev = shots[-1]
+            budget = int(prev.get("silence_after_ms", 0)) + int(prev.get("trim_tail_ms", 0))
+            if ov > budget:
+                warnings.append(
+                    f"镜 {n}: 重叠 {ov}ms 超出上一镜可借冗余 {budget}ms"
+                    f"(静音留白 {prev.get('silence_after_ms', 0)} + 掐掉的尾部 {prev.get('trim_tail_ms', 0)})，"
+                    f"重叠期会压到对白，建议降到 {budget}ms 或改硬切")
+            cursor -= ov
+
+        in_ms = cursor if prev_dur is not None else 0
+        tr = dict(trans.get(n) or {"preset_id": "cut", "xfade": None, "render": "cut", "flash": None})
+        if tr["preset_id"] in DEPRECATED:
+            warnings.append(
+                f"镜 {n}: 转场 {tr['preset_id']} 已在平台下架（长叠化在有对白接缝会卡壳），"
+                f"建议改用 {SAFE_REPLACEMENT.get(tr['preset_id'], 'fade')}")
+        tr["duration_ms"] = ov if tr["render"] == "xfade" else (
+            PRESETS[tr["preset_id"]]["ms"] if tr["render"] == "baked-cut" else 0)
+
+        shots.append({
+            "shot_number": n,
+            "transition": tr,
+            "file": sh["clip"]["file"],
+            "trim_head_ms": int(sh["clip"].get("trim_head_ms", 0)),
+            "trim_tail_ms": int(sh["clip"].get("trim_tail_ms", 0)),
+            "duration_ms": dur,
+            "in_ms": in_ms,
+            "overlap_ms": ov,
+            "has_baked_audio": bool(sh["clip"].get("has_baked_audio")),
+            "silence_after_ms": int(sh.get("padding", {}).get("silence_after_ms", 0)),
+            "dialogue": sh.get("dialogue_audio"),
+            "sfx": sh.get("sfx", []),
+        })
+
+        # 字幕：镜内相对 → 绝对。一次加法，位移问题在此消失。
+        sub = (sh.get("subtitle") or {}).get("file")
+        for a, b, t in parse_srt(os.path.join(pack_dir, sub) if sub else None):
+            cues.append((in_ms + a, in_ms + b, t))
+
+        cursor = in_ms + dur
+        prev_dur = dur
+
+    total = cursor
+    by_n = {s["shot_number"]: s for s in shots}
+    bgm = []
+    for b in manifest.get("bgm", []):
+        anchor = by_n.get(int(b.get("anchor_shot", 1)))
+        if not anchor:
+            warnings.append(f"BGM {b.get('file')}: anchor_shot 不存在，按 0 处理")
+        bgm.append({
+            "file": b["file"],
+            "in_ms": (anchor["in_ms"] if anchor else 0) + int(b.get("anchor_offset_ms", 0)),
+            "gain_db": float(b.get("gain_db", -16)),
+            "fade_in_ms": int(b.get("fade_in_ms", 0)),
+            "fade_out_ms": int(b.get("fade_out_ms", 0)),
+            "loop": bool(b.get("loop", True)),
+        })
+
+    out = {
+        "total_ms": total,
+        "render_target": manifest["render_target"],
+        "audio_contract": manifest["audio_contract"],
+        "shots": shots,
+        "bgm": bgm,
+        "warnings": warnings,
+    }
+    outdir = outdir or os.path.join(pack_dir, "build")
+    os.makedirs(outdir, exist_ok=True)
+    json.dump(out, open(os.path.join(outdir, "offsets.json"), "w", encoding="utf-8"),
+              ensure_ascii=False, indent=2)
+    write_srt(os.path.join(outdir, "episode.srt"), sorted(cues, key=lambda c: c[0]))
+
+    print(f"总时长 {total/1000:.2f}s · {len(shots)} 镜 · {len(cues)} 条字幕 → {outdir}")
+    for w in warnings:
+        print("  ⚠️ " + w, file=sys.stderr)
+    return out
+
+
+if __name__ == "__main__":
+    ap = argparse.ArgumentParser()
+    ap.add_argument("pack_dir")
+    ap.add_argument("--transitions")
+    ap.add_argument("--outdir")
+    a = ap.parse_args()
+    compile_timeline(a.pack_dir, a.transitions, a.outdir)

package/assets/handoff/fetch_pack.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""
+fetch_pack.py — 把 export_handoff_pack 返回的 manifest 拉成一个本地素材包目录。
+
+平台返回的 manifest 是「URL + 内联字幕」，而 compile_timeline.py / assemble.sh 要的是
+「本地文件」。本脚本负责这一步适配：下载全部素材、把内联 cues 落成逐镜 SRT、
+把 manifest 里的 url 字段改写成包内相对路径。
+
+用法:
+    # manifest 存成文件后
+    python3 fetch_pack.py manifest.json -o ./pack
+    # 或直接从 stdin
+    cat manifest.json | python3 fetch_pack.py - -o ./pack
+
+产物:
+    pack/manifest.json          # 已改写成本地相对路径，可直接喂给 compile_timeline.py
+    pack/clips/shot_001.mp4 …
+    pack/audio/dialogue/…  pack/audio/sfx/…  pack/audio/bgm/…
+    pack/subs/shot_001.srt …
+    pack/lut/haldclut.png       # 有调色时才有
+
+之后:
+    python3 compile_timeline.py ./pack [--transitions plan.json]
+    ./assemble.sh ./pack out.mp4 [plan.json]
+
+只用标准库，无第三方依赖。
+"""
+import argparse
+import json
+import os
+import sys
+import urllib.request
+import urllib.error
+from concurrent.futures import ThreadPoolExecutor
+
+DOWNLOAD_TIMEOUT_SEC = 120
+RETRIES = 3
+
+
+def fetch(url: str, dest: str) -> str:
+    """下载到 dest。已存在且非空则跳过（断点续跑友好）。返回 dest。"""
+    if os.path.exists(dest) and os.path.getsize(dest) > 0:
+        return dest
+    os.makedirs(os.path.dirname(dest), exist_ok=True)
+    tmp = dest + ".part"
+    last = None
+    for attempt in range(1, RETRIES + 1):
+        try:
+            with urllib.request.urlopen(url, timeout=DOWNLOAD_TIMEOUT_SEC) as r, open(tmp, "wb") as f:
+                while True:
+                    chunk = r.read(1 << 20)
+                    if not chunk:
+                        break
+                    f.write(chunk)
+            os.replace(tmp, dest)      # 原子落位，中断不会留下半个文件冒充成品
+            return dest
+        except (urllib.error.URLError, urllib.error.HTTPError, OSError) as e:
+            last = e
+            if os.path.exists(tmp):
+                os.unlink(tmp)
+    raise RuntimeError(f"下载失败({RETRIES} 次): {url}\n  {last}")
+
+
+def fmt_ms(ms: int) -> str:
+    ms = max(0, int(ms))
+    h, ms = divmod(ms, 3600000)
+    m, ms = divmod(ms, 60000)
+    s, ms = divmod(ms, 1000)
+    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
+
+
+def write_srt(path: str, cues) -> int:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    n = 0
+    with open(path, "w", encoding="utf-8") as f:
+        for c in cues:
+            text = str(c.get("text", "")).strip()
+            if not text:
+                continue
+            n += 1
+            f.write(f"{n}\n{fmt_ms(c['start_ms'])} --> {fmt_ms(c['end_ms'])}\n{text}\n\n")
+    return n
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("manifest", help="manifest.json 路径，或 - 表示从 stdin 读")
+    ap.add_argument("-o", "--outdir", default="./pack")
+    ap.add_argument("-j", "--jobs", type=int, default=4, help="并发下载数（默认 4）")
+    a = ap.parse_args()
+
+    raw = sys.stdin.read() if a.manifest == "-" else open(a.manifest, encoding="utf-8").read()
+    m = json.loads(raw)
+    # MCP 工具可能把 manifest 包在 data 里返回，两种都认
+    m = m.get("data", m) if isinstance(m.get("data"), dict) else m
+
+    if m.get("manifest_version") != "0.1":
+        sys.exit(f"不认识的 manifest_version: {m.get('manifest_version')!r}，拒绝猜测")
+
+    out = a.outdir
+    os.makedirs(out, exist_ok=True)
+    jobs = []            # (url, 包内相对路径)
+
+    for i, sh in enumerate(m.get("shots", [])):
+        n = int(sh["shot_number"])
+        tag = f"{n:03d}"
+        clip = sh.get("clip") or {}
+        if clip.get("url"):
+            rel = f"clips/shot_{tag}.mp4"
+            jobs.append((clip.pop("url"), rel))
+            clip["file"] = rel
+
+        dlg = sh.get("dialogue_audio")
+        if dlg and dlg.get("url"):
+            rel = f"audio/dialogue/shot_{tag}.wav"
+            jobs.append((dlg.pop("url"), rel))
+            dlg["file"] = rel
+
+        for k, fx in enumerate(sh.get("sfx") or []):
+            if not fx.get("url"):
+                continue
+            rel = f"audio/sfx/shot_{tag}_{k}.wav"
+            jobs.append((fx.pop("url"), rel))
+            fx["file"] = rel
+
+        # 内联 cues → 逐镜 SRT（时间码基准仍是「该镜 trim 后的第 0 毫秒」，不做任何平移）
+        cues = ((sh.get("subtitle") or {}).get("cues")) or []
+        if cues:
+            rel = f"subs/shot_{tag}.srt"
+            cnt = write_srt(os.path.join(out, rel), cues)
+            sh["subtitle"] = {"file": rel, "cue_count": cnt}
+        else:
+            sh["subtitle"] = {"file": None, "cue_count": 0}
+
+    for k, b in enumerate(m.get("bgm") or []):
+        if not b.get("url"):
+            continue
+        rel = f"audio/bgm/track_{k}.wav"
+        jobs.append((b.pop("url"), rel))
+        b["file"] = rel
+
+    lut = (m.get("render_target") or {}).get("color_lut")
+    if isinstance(lut, dict) and lut.get("haldclut_url"):
+        rel = "lut/haldclut.png"
+        jobs.append((lut.pop("haldclut_url"), rel))
+        lut["file"] = rel
+
+    if not jobs:
+        sys.exit("manifest 里没有任何可下载资源（URL 可能已过期，重新调 export_handoff_pack）")
+
+    print(f"下载 {len(jobs)} 个文件 → {out}")
+    errors = []
+
+    def one(job):
+        url, rel = job
+        try:
+            fetch(url, os.path.join(out, rel))
+        except Exception as e:            # 单个失败不中断整批，最后一起报
+            errors.append(f"{rel}: {e}")
+
+    with ThreadPoolExecutor(max_workers=max(1, a.jobs)) as ex:
+        list(ex.map(one, jobs))
+
+    with open(os.path.join(out, "manifest.json"), "w", encoding="utf-8") as f:
+        json.dump(m, f, ensure_ascii=False, indent=2)
+
+    if errors:
+        print(f"\n{len(errors)} 个文件下载失败：", file=sys.stderr)
+        for e in errors[:20]:
+            print("  " + e, file=sys.stderr)
+        print("URL 有有效期，过期就重新调 export_handoff_pack 拿新的 manifest。", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"完成。下一步：\n  python3 compile_timeline.py {out}\n  ./assemble.sh {out} out.mp4")
+
+
+if __name__ == "__main__":
+    main()

package/dist/path-guard.js

@@ -43,3 +43,42 @@ export function assertSafeLocalMediaPath(filePath, kind, resolve = realpathSync)
     }
     return real;
 }
+/** 允许落盘的工具链文件名白名单——目标文件名由我们定，不接受调用方指定。 */
+export const TOOLCHAIN_FILENAMES = ['fetch_pack.py', 'compile_timeline.py', 'assemble.sh'];
+/** 写文件比读文件更危险：这些前缀下一律不落盘（覆盖系统/可执行文件路径的后果不可逆）。 */
+const WRITE_DENY_PREFIXES = [
+    '/etc/', '/private/etc/', '/proc/', '/sys/', '/bin/', '/sbin/',
+    '/usr/', '/System/', '/Library/', '/boot/', '/dev/',
+];
+/**
+ * 校验「把工具链脚本写到哪个目录」。
+ *
+ * 与上传守卫同源但更严：上传只是读别人的文件，写盘则可能覆盖掉目标位置已有的东西。
+ * 三条规则：
+ *   ① 必须是绝对路径 —— 相对路径在 MCP 进程里解析基准不明（进程 cwd 未必是调用方以为的目录）；
+ *   ② realpath 后不得含以 '.' 开头的路径段（~/.ssh、~/.config、.git 全部命中）；
+ *   ③ 不得落在系统/可执行目录前缀下。
+ * 文件名不由调用方决定（见 TOOLCHAIN_FILENAMES），所以不存在 ../ 穿越写任意文件的路径。
+ */
+export function assertSafeToolchainDir(dirPath, resolve = realpathSync) {
+    if (!dirPath || !dirPath.startsWith('/')) {
+        throw new Error(`dir 必须是绝对路径(收到 "${dirPath}")。MCP 进程的工作目录与你的不一定相同,`
+            + '相对路径会写到意料之外的地方。');
+    }
+    let real;
+    try {
+        real = resolve(dirPath);
+    }
+    catch {
+        throw new Error(`dir 不存在:${dirPath}。请先创建该目录再重试(本工具不递归建目录)。`);
+    }
+    const segments = real.split(sep);
+    if (segments.some(s => s.startsWith('.') && s.length > 1)) {
+        throw new Error(`dir 位于隐藏目录(${real}),已拒绝——不向 ~/.ssh、~/.config、.git 这类目录写文件。`
+            + '换一个普通工作目录。');
+    }
+    if (WRITE_DENY_PREFIXES.some(p => real.startsWith(p))) {
+        throw new Error(`dir 位于系统目录(${real}),已拒绝写入。换一个你自己的工作目录。`);
+    }
+    return real;
+}

package/dist/tools/produce.js

@@ -11,6 +11,27 @@
  * 用 get_storyboards / get_episode_status 轮询到完成。下载链接只发我方 COS 链接。
  */
 import { z } from 'zod';
+import { readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertSafeToolchainDir, TOOLCHAIN_FILENAMES } from '../path-guard.js';
+const TOOLCHAIN_USAGE = [
+    '1. 三个脚本放同一目录(assemble.sh 需可执行位)。',
+    '2. 把 export_handoff_pack 的返回体存成 manifest.json。',
+    '3. python3 fetch_pack.py manifest.json -o ./pack   # 下载素材 + 内联字幕落成逐镜 SRT + 改写成本地路径',
+    '4. python3 compile_timeline.py ./pack [--transitions plan.json]   # 展开时间轴',
+    '5. ./assemble.sh ./pack out.mp4 [plan.json]   # 装配成片',
+];
+const TOOLCHAIN_NOTE = 'assemble.sh 会先自检 ffmpeg 是否带 libass;不带则字幕以软字幕轨输出而非烧录(竖屏发布必须烧录)。' +
+    '包里若带 render_target.color_lut,fetch_pack.py 会把调色查找表一并下载,assemble.sh 自动施加——' +
+    '不施加的话你的成片与平台成片会有色差。';
+/**
+ * 随包发布的装配工具链目录。本文件编译后在 dist/tools/produce.js，
+ * assets/ 在包根，所以要上两级 —— 少一级会静默解析到 dist/assets（不存在），
+ * 而 get_handoff_toolchain 里 catch 掉读取异常，坏结果不会崩、只会悄悄发给第三方。
+ * release-check 里有一条闸钉住这个路径。
+ */
+export const HANDOFF_ASSETS = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'assets', 'handoff');
 function jsonResult(data) {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 }
@@ -592,13 +613,19 @@ export function registerProduceTools(server, client) {
         physical_size_hint: z.string().optional().describe('物理尺寸提示'),
         episode_id: z.number().int().positive().optional(),
     }, async ({ drama_id, ...fields }) => jsonResult(await client.producePost(`/props`, { drama_id, ...fields })));
-    server.tool('update_prop', '改道具(名称/类型/描述/prompt/尺寸)。免费。', {
+    server.tool('update_prop', '改道具(名称/类型/描述/prompt/尺寸/多视角参考图)。免费。', {
         prop_id: z.number().int().positive(),
         name: z.string().optional(),
         type: z.string().optional(),
         description: z.string().optional(),
         prompt: z.string().optional(),
         physical_size_hint: z.string().optional(),
+        // v0.9.976 — 多视角/细节参考图（整份覆盖；传 [] 清空，最多 6 张 http(s) 图）。
+        // 与主图分工：主图锁「这是什么」，多视角锁「截面与部件怎么装配」——单张白底图
+        // 和文字都表达不了这个（生产实证：形制文本已送达，锤头仍画成被禁的形状）。
+        // 正视 / 侧视 / 端面各一张最有效，端面是截面形状唯一能说清的方式。
+        reference_images: z.array(z.string().url()).max(6).optional()
+            .describe('多视角参考图 URL 数组，整份覆盖；建议正视/侧视/端面各一张'),
     }, async ({ prop_id, ...fields }) => jsonResult(await client.producePut(`/props/${prop_id}`, fields)));
     server.tool('delete_prop', '删一个道具。免费。', { prop_id: z.number().int().positive() }, async ({ prop_id }) => jsonResult(await client.produceDelete(`/props/${prop_id}`)));
     server.tool('mark_signature_prop', '标记/取消「招牌道具」(会在多镜复现的关键道具,加强一致性追踪)。signature=false 取消。免费。', { prop_id: z.number().int().positive(), signature: z.boolean().optional().describe('默认 true 标记;false 取消') }, async ({ prop_id, signature }) => jsonResult(await client.producePost(`/props/${prop_id}/signature`, { signature: signature !== false })));
@@ -670,4 +697,91 @@ export function registerProduceTools(server, client) {
         character_id: z.number().int().positive(),
         voice_id: z.string().describe('来自 clone_voice / list_voices 的 voice_id(形如 lib:12)'),
     }, async ({ character_id, voice_id }) => jsonResult(await client.producePost(`/characters/${character_id}/voice`, { voice_id })));
+    // ── 素材交接包：客户自己拼片的通道 ──────────────────────────────────────
+    // 与 compose_episode 的分工：compose_episode = 「平台替你拼」；本组工具 = 「素材给你，
+    // 你自己决定转场、自己拼」。两条路都不丢客户的对白/音效/配乐/字幕成果。
+    server.tool('export_handoff_pack', '导出本集「素材交接包」清单:逐镜裸片 + 对白音轨 + 音效 + 配乐 + 字幕的可下载 URL,' +
+        '交给你在**自己那边**完成转场决策、拼接、混音、烧字幕——平台不参与终拼。免费,零扣费。\n' +
+        '\n【推荐流程】① 调本工具拿 manifest;② 按 clips[].url 把裸片下载到本地;' +
+        '③ 你自己看片判断每个接缝该用什么转场(manifest 给了 scene_boundary 场景边界作判据),' +
+        '写一份 plan.json;④ 用 get_handoff_toolchain 拿到 compile_timeline.py 展开时间轴、' +
+        'assemble.sh 装配出成片。工具链已经把「加了重叠转场之后字幕/对白/音效怎么跟着位移」算好了。\n' +
+        '\n【三个不看就会翻车的事实】\n' +
+        '① audio_contract.mode="tts" 时**裸片里没有人声**,对白在 dialogue_audio 里;不铺就是整集没台词。' +
+        'mode="clip" 时人声已烤在裸片音轨里,反过来**不要**再叠。\n' +
+        '② 每镜必须按 trim_head_ms / duration_ms 裁剪再用;直接拼整条裸片会把平台已经 QC 掉的' +
+        '首尾形变帧一起拼进去。\n' +
+        '③ 字幕 cue、dialogue_audio.offset_ms、sfx[].offset_ms 的基准都是「该镜 trim 之后的第 0 毫秒」,' +
+        '不是成片绝对时间。你加多少重叠转场都不用改它们——交给 compile_timeline.py 展开,别手算累加。\n' +
+        '\n想让平台代拼、要平台级质量闸(终拼预检/音画等长/响度母带),改用 compose_episode。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => {
+        const manifest = await client.produceGet(`/episodes/${episode_id}/handoff-pack`);
+        return jsonResult({
+            ...manifest,
+            assembly_guide: {
+                step_1_download: '按 shots[].clip.url / dialogue_audio.url / sfx[].url / bgm[].url 下载素材。' +
+                    'URL 到 expires_at 失效,过期重新调本工具。',
+                step_2_decide_transitions: '自己分析画面决定每个接缝的转场。scene_boundary="start" 是换场(适合给转场),' +
+                    '"continue" 是同场景(平台默认硬切——同场景逐镜叠化是"幻灯片拼凑感"的主因)。' +
+                    'transition_hint 是平台建议,你可以覆盖。',
+                step_3_plan_json: '写 plan.json:{"transitions":[{"before_shot":3,"type":"fade","overlap_ms":300}]}。' +
+                    'type 接受预设 id(fade/flash_white/whip_pan…)、导演语义键' +
+                    '(match_cut/smash_cut/cross_dissolve…)、或直接给 ffmpeg xfade 名。' +
+                    'overlap_ms 不填就用该预设的规范时长。',
+                step_4_assemble: 'save_handoff_toolchain 把三个脚本落到本地目录,然后:\n' +
+                    '  python3 fetch_pack.py manifest.json -o ./pack   # 下载素材 + 内联字幕落成 SRT\n' +
+                    '  python3 compile_timeline.py ./pack --transitions plan.json\n' +
+                    '  ./assemble.sh ./pack out.mp4 plan.json',
+                gotchas: [
+                    'clip.duration_source="authored" 的镜是 probe 失败退回声明时长的,请自行 ffprobe 校正,否则拼接有累积误差。',
+                    'render_target.color_lut 非 null 时,裸片是**未调色**的:必须施加随包的 haldclut 查找表,' +
+                        '否则你的成片与平台成片有色差。fetch_pack.py 会下载它、assemble.sh 会自动施加。',
+                    '重叠转场会让其后所有镜整体前移且误差累积——用 compile_timeline.py 算,不要手算。',
+                    '闪白/闪黑(flash_white/flash_black)是硬切+片头闪光,不能走 xfade,否则双重闪且破坏口型。工具链已处理。',
+                    '响度必须两 pass 线性母带;单 pass 动态 loudnorm 会把对白间隙的 BGM 上提,让配乐增益调了等于没调。',
+                    '侧链避让的 key 必须是纯人声轨,混进音效会让打击音也把 BGM 压下去,听感是配乐一惊一乍。',
+                ],
+                toolchain: 'save_handoff_toolchain 直接把工具链写到你的工作目录(推荐);或 get_handoff_toolchain 拿源码自己保存。',
+            },
+        });
+    });
+    server.tool('get_handoff_toolchain', '拿到素材交接包的装配工具链源码(compile_timeline.py 时间轴编译器 / assemble.sh ffmpeg 装配脚本)。' +
+        '免费。本工具只返回源码文本,**不会**在你机器上写文件——请自行保存到工作目录再执行。\n' +
+        'compile_timeline.py 负责把「镜相对」的字幕/对白/音效锚点展开成你自己时间轴上的绝对时间码,' +
+        '并处理重叠转场引起的整体位移;assemble.sh 是从裸片到成片的完整 ffmpeg 装配基线' +
+        '(裁剪→规范化→拼接/xfade→配乐侧链→字幕→两 pass 母带)。' +
+        '依赖 ffmpeg(烧字幕需带 libass)、ffprobe、jq、python3。', {
+        script: z.enum([...TOOLCHAIN_FILENAMES, 'all']).optional().describe('要哪个;缺省 all'),
+    }, async ({ script }) => {
+        const want = script && script !== 'all' ? [script] : [...TOOLCHAIN_FILENAMES];
+        const files = {};
+        for (const f of want) {
+            try {
+                files[f] = readFileSync(join(HANDOFF_ASSETS, f), 'utf8');
+            }
+            catch (e) {
+                files[f] = `// 读取失败: ${e?.message || e}`;
+            }
+        }
+        return jsonResult({ files, usage: TOOLCHAIN_USAGE, note: TOOLCHAIN_NOTE });
+    });
+    server.tool('save_handoff_toolchain', '把装配工具链(fetch_pack.py / compile_timeline.py / assemble.sh)直接写到你本地的一个目录,' +
+        '省掉自己复制粘贴。免费。目录必须**已存在**且是绝对路径;文件名固定,不接受自定义。\n' +
+        '拒绝写入隐藏目录(~/.ssh、~/.config、.git…)与系统目录——这是写盘不是读盘,覆盖错地方不可逆。\n' +
+        '落盘后完整流程:\n' +
+        '  python3 fetch_pack.py manifest.json -o ./pack   # 下载素材、内联字幕落成 SRT\n' +
+        '  python3 compile_timeline.py ./pack [--transitions plan.json]\n' +
+        '  ./assemble.sh ./pack out.mp4 [plan.json]', { dir: z.string().describe('已存在的绝对路径目录,如 /Users/me/work/starreel-pack') }, async ({ dir }) => {
+        const safe = assertSafeToolchainDir(dir);
+        const written = [];
+        for (const f of TOOLCHAIN_FILENAMES) {
+            const body = readFileSync(join(HANDOFF_ASSETS, f), 'utf8');
+            const dest = join(safe, f);
+            writeFileSync(dest, body, 'utf8');
+            // .sh 要可执行,否则第三方还得自己 chmod 一次才跑得起来
+            if (f.endsWith('.sh'))
+                chmodSync(dest, 0o755);
+            written.push({ file: dest, bytes: Buffer.byteLength(body), mode: f.endsWith('.sh') ? '0755' : '0644' });
+        }
+        return jsonResult({ written, usage: TOOLCHAIN_USAGE, note: TOOLCHAIN_NOTE });
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "mcpName": "ai.starreel/starreel",
   "description": "StarReel MCP server — drive the AI short-drama production pipeline (script → storyboards → frames → video → final cut) from Claude, Cursor, or any MCP client",
   "license": "MIT",
@@ -12,7 +12,8 @@
     "dist",
     "README.md",
     "SKILL.md",
-    "server.json"
+    "server.json",
+    "assets"
   ],
   "scripts": {
     "build": "tsc",
@@ -40,4 +41,4 @@
     "localization",
     "short-drama"
   ]
-}
+}

package/server.json

@@ -2,13 +2,13 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "ai.starreel/starreel",
   "description": "Turn a script into a finished, downloadable short-drama episode — via MCP or REST.",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.41",
+      "version": "0.1.42",
       "transport": { "type": "stdio" },
       "environmentVariables": [
         {