@lightcone-ai/daemon 0.14.0 → 0.14.2

package/mcp-servers/official/video-narration-planner/core.js

@@ -0,0 +1,1436 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const VISUAL_ACTION_TYPES = Object.freeze([
+  'scroll_to_dwell',
+  'linear_scroll_during',
+  'cursor_focus',
+  'scroll_back',
+]);
+
+const VISUAL_ACTION_SET = new Set(VISUAL_ACTION_TYPES);
+const DEFAULT_OUTRO_VIDEO_ID = 'outro-default-zh';
+const SENTENCE_MIN_CHARS = 100;
+const SENTENCE_MAX_CHARS = 150;
+
+const PLATFORM_PROFILES = Object.freeze({
+  xiaohongshu: Object.freeze({
+    id: 'xiaohongshu',
+    aliases: ['xhs', 'redbook', 'xiaohongshu', '小红书'],
+    duration_range_s: [30, 45],
+    default_total_duration_s: 36,
+    hook_duration_s: 6,
+    cta_duration_s: 6,
+    min_highlight_duration_s: 8,
+    tone: '种草型、亲切、讲重点',
+    voice_preset: 'warm_female_zh_01',
+    speed: 1.06,
+  }),
+  douyin: Object.freeze({
+    id: 'douyin',
+    aliases: ['douyin', '抖音', 'tiktok_cn'],
+    duration_range_s: [25, 40],
+    default_total_duration_s: 32,
+    hook_duration_s: 5,
+    cta_duration_s: 5,
+    min_highlight_duration_s: 7,
+    tone: '快节奏、结论先行、行动明确',
+    voice_preset: 'news_male_zh_01',
+    speed: 1.14,
+  }),
+  wechat_video: Object.freeze({
+    id: 'wechat_video',
+    aliases: ['wechat_video', 'wechat-video', 'video_channel', '视频号', 'wechat', '公众号视频号'],
+    duration_range_s: [35, 60],
+    default_total_duration_s: 46,
+    hook_duration_s: 7,
+    cta_duration_s: 7,
+    min_highlight_duration_s: 9,
+    tone: '稳健讲解、信息完整、可信表达',
+    voice_preset: 'warm_male_zh_01',
+    speed: 0.98,
+  }),
+});
+
+const PLATFORM_LOOKUP = (() => {
+  const map = new Map();
+  for (const profile of Object.values(PLATFORM_PROFILES)) {
+    map.set(profile.id, profile.id);
+    for (const alias of profile.aliases) {
+      map.set(String(alias).trim().toLowerCase(), profile.id);
+    }
+  }
+  return map;
+})();
+
+const SENTENCE_FILLERS = Object.freeze([
+  '你可以把这段信息理解成筛选效率的核心杠杆，它决定了你后续要不要投入更多时间。',
+  '我会只保留对决策真正有帮助的线索，避免你被页面里的装饰信息分散注意力。',
+  '看完这一段后，你应该能立刻得到一个可执行判断，而不是停留在模糊印象。',
+  '如果这部分与你的目标不匹配，建议立刻止损切换，不要把精力耗在低价值信息上。',
+  '把它和你自己的标准逐条对照，会比完整通读页面更快得到可靠结论。',
+]);
+
+const SEMANTIC_SLOT_KEYS = Object.freeze([
+  'company',
+  'published_at',
+  'recruitment_type',
+  'cohort',
+  'job_directions',
+  'locations',
+  'target_or_requirements',
+  'process',
+  'entry_or_cta',
+]);
+
+const NARRATION_MODES = Object.freeze([
+  'job_intel_broadcast',
+  'job_alert',
+  'info_summary',
+  'refuse_auto_broadcast',
+]);
+
+const NARRATION_MODE_SET = new Set(NARRATION_MODES);
+const SLOT_STATUS_SET = new Set(['present', 'missing']);
+
+const RECRUITMENT_KEYWORDS = /招聘|校招|实习|职位|岗位|career|jobs|intern|campus/i;
+
+const RECRUITMENT_TYPE_LABELS = Object.freeze({
+  campus: '校园招聘',
+  intern: '实习招聘',
+  experienced: '社会招聘',
+  job_posting_unknown: '岗位招聘信息',
+});
+
+const SLOT_LABELS = Object.freeze({
+  company: '公司',
+  published_at: '发布时间',
+  recruitment_type: '招聘类型',
+  cohort: '届别',
+  job_directions: '岗位方向',
+  locations: '工作城市',
+  target_or_requirements: '对象与要求',
+  process: '招聘流程',
+  entry_or_cta: '投递入口',
+});
+
+const MODE_SEVERITY = Object.freeze({
+  job_intel_broadcast: 4,
+  job_alert: 3,
+  info_summary: 2,
+  refuse_auto_broadcast: 1,
+});
+
+const MODE_MIN_CONFIDENCE = Object.freeze({
+  strong: 0.6,
+  support: 0.52,
+  weakSignal: 0.42,
+  floor: 0.36,
+});
+
+const RECRUITMENT_FAIL_CLOSED_GROUPS = Object.freeze([
+  Object.freeze({
+    id: 'company+published_at+recruitment_type',
+    keys: Object.freeze(['company', 'published_at', 'recruitment_type']),
+  }),
+  Object.freeze({
+    id: 'company+cohort+job_directions',
+    keys: Object.freeze(['company', 'cohort', 'job_directions']),
+  }),
+  Object.freeze({
+    id: 'company+recruitment_type+locations',
+    keys: Object.freeze(['company', 'recruitment_type', 'locations']),
+  }),
+]);
+
+function clampNumber(value, min, max, fallback) {
+  const num = Number(value);
+  if (!Number.isFinite(num)) return fallback;
+  return Math.max(min, Math.min(max, num));
+}
+
+function clampInt(value, min, max, fallback) {
+  return Math.round(clampNumber(value, min, max, fallback));
+}
+
+function toSafeString(value) {
+  if (value == null) return '';
+  return String(value).trim();
+}
+
+function toFiniteNumber(value) {
+  const num = Number(value);
+  return Number.isFinite(num) ? num : null;
+}
+
+function toCharLength(text) {
+  return Array.from(String(text ?? '')).length;
+}
+
+function trimToChars(text, maxChars) {
+  const chars = Array.from(String(text ?? ''));
+  if (chars.length <= maxChars) return chars.join('');
+  return chars.slice(0, maxChars).join('');
+}
+
+function withSentencePunctuation(text) {
+  const value = toSafeString(text);
+  if (!value) return value;
+  if (/[。！？!?]$/.test(value)) return value;
+  return `${value}。`;
+}
+
+function ensureSentenceLength(text, minChars = SENTENCE_MIN_CHARS, maxChars = SENTENCE_MAX_CHARS) {
+  let output = withSentencePunctuation(text);
+  let pointer = 0;
+  while (toCharLength(output) < minChars) {
+    const filler = SENTENCE_FILLERS[pointer % SENTENCE_FILLERS.length];
+    output = withSentencePunctuation(`${output}${filler}`);
+    pointer += 1;
+  }
+
+  if (toCharLength(output) > maxChars) {
+    output = trimToChars(output, maxChars);
+    output = output.replace(/[，,；;：:]?[^，。！？!?]*$/, '');
+    if (!output) {
+      output = trimToChars(text, maxChars);
+    }
+    output = withSentencePunctuation(output);
+  }
+
+  return output;
+}
+
+function normalizeTargetPlatform(value) {
+  const raw = toSafeString(value).toLowerCase();
+  if (!raw) return 'xiaohongshu';
+  return PLATFORM_LOOKUP.get(raw) ?? 'xiaohongshu';
+}
+
+function getPlatformProfile(platform) {
+  const normalized = normalizeTargetPlatform(platform);
+  return PLATFORM_PROFILES[normalized] ?? PLATFORM_PROFILES.xiaohongshu;
+}
+
+function normalizeYRange(value) {
+  if (!Array.isArray(value) || value.length < 2) return null;
+  const start = toFiniteNumber(value[0]);
+  const end = toFiniteNumber(value[1]);
+  if (start == null || end == null) return null;
+  const low = Math.min(start, end);
+  const high = Math.max(start, end);
+  return [Math.round(low), Math.round(high)];
+}
+
+function midpoint(range, fallback = 0) {
+  if (!Array.isArray(range) || range.length < 2) return fallback;
+  return Math.round((Number(range[0]) + Number(range[1])) / 2);
+}
+
+function coerceRangeByY(centerY, span = 220) {
+  const center = toFiniteNumber(centerY);
+  if (center == null) return null;
+  const half = Math.max(60, Math.round(span / 2));
+  return [Math.round(center - half), Math.round(center + half)];
+}
+
+function inAnyRange(y, ranges = []) {
+  return ranges.some(([start, end]) => y >= start && y <= end);
+}
+
+function normalizeModeHint(value) {
+  const mode = toSafeString(value);
+  return NARRATION_MODE_SET.has(mode) ? mode : null;
+}
+
+function normalizeSlotValue(value) {
+  if (Array.isArray(value)) {
+    const output = [];
+    const seen = new Set();
+    for (const item of value) {
+      const text = toSafeString(item);
+      if (!text) continue;
+      const key = text.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      output.push(text);
+    }
+    return output.length > 0 ? output : null;
+  }
+  const text = toSafeString(value);
+  return text || null;
+}
+
+function normalizeSemanticSlot(rawSlot = {}) {
+  const value = normalizeSlotValue(rawSlot?.value);
+  const statusRaw = toSafeString(rawSlot?.status);
+  const status = SLOT_STATUS_SET.has(statusRaw) ? statusRaw : (value == null ? 'missing' : 'present');
+  return {
+    value,
+    status,
+    confidence: Number(clampNumber(rawSlot?.confidence, 0, 1, 0).toFixed(2)),
+    focus_region: normalizeYRange(rawSlot?.focus_region ?? rawSlot?.focusRegion),
+    source_type: toSafeString(rawSlot?.source_type || rawSlot?.sourceType || 'heuristic') || 'heuristic',
+  };
+}
+
+function collectSemanticSlots(understanding = {}) {
+  const raw = understanding?.semantic_slots;
+  const source = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+  const slots = {};
+  for (const key of SEMANTIC_SLOT_KEYS) {
+    slots[key] = normalizeSemanticSlot(source[key]);
+  }
+  return slots;
+}
+
+function slotHasValue(slot) {
+  if (!slot || slot.status === 'missing') return false;
+  if (Array.isArray(slot.value)) return slot.value.length > 0;
+  return Boolean(toSafeString(slot.value));
+}
+
+function slotConfidence(slot) {
+  const confidence = Number(slot?.confidence);
+  if (!Number.isFinite(confidence)) return 0;
+  return Math.max(0, Math.min(1, confidence));
+}
+
+function slotHasMinConfidence(slot, min = 0) {
+  return slotHasValue(slot) && slotConfidence(slot) >= min;
+}
+
+function slotValueToText(slot, { maxItems = 3 } = {}) {
+  if (!slotHasValue(slot)) return '';
+  if (!Array.isArray(slot.value)) return toSafeString(slot.value);
+  const picked = slot.value.slice(0, maxItems).map(item => toSafeString(item)).filter(Boolean);
+  if (picked.length <= 0) return '';
+  if (slot.value.length > picked.length) return `${picked.join('、')}等`;
+  return picked.join('、');
+}
+
+function slotLabel(key) {
+  return SLOT_LABELS[key] || key;
+}
+
+function formatRecruitmentType(slot) {
+  const raw = toSafeString(Array.isArray(slot?.value) ? slot.value[0] : slot?.value).toLowerCase();
+  if (!raw) return '';
+  return RECRUITMENT_TYPE_LABELS[raw] || raw;
+}
+
+function averageSlotConfidence(slots = []) {
+  const values = slots
+    .map(slot => Number(slot?.confidence))
+    .filter(value => Number.isFinite(value) && value > 0);
+  if (values.length <= 0) return 0;
+  return Number((values.reduce((sum, value) => sum + value, 0) / values.length).toFixed(2));
+}
+
+function hasAnySemanticSlot(slots = {}) {
+  return SEMANTIC_SLOT_KEYS.some(key => slotHasValue(slots[key]));
+}
+
+function detectRecruitmentRelated({ understanding = {}, slots = {} } = {}) {
+  const pageType = toSafeString(understanding?.page_type || understanding?.pageType).toLowerCase();
+  if (pageType === 'job_detail') return true;
+
+  const url = toSafeString(understanding?.url);
+  if (RECRUITMENT_KEYWORDS.test(url)) return true;
+
+  const coreMessage = toSafeString(understanding?.core_message || understanding?.coreMessage || understanding?.title);
+  if (RECRUITMENT_KEYWORDS.test(coreMessage)) return true;
+
+  return ['company', 'recruitment_type', 'job_directions', 'locations', 'process']
+    .some(key => slotHasValue(slots[key]));
+}
+
+function shouldApplyRecruitmentFailClosed(understanding = {}) {
+  const pageType = toSafeString(understanding?.page_type || understanding?.pageType).toLowerCase();
+  if (pageType === 'job_detail') return true;
+
+  const url = toSafeString(understanding?.url);
+  if (RECRUITMENT_KEYWORDS.test(url)) return true;
+
+  const headline = toSafeString(understanding?.core_message || understanding?.coreMessage || understanding?.title);
+  if (RECRUITMENT_KEYWORDS.test(headline)) return true;
+
+  return false;
+}
+
+function deriveModeFromSlots({ understanding = {}, slots = {} } = {}) {
+  const recruitmentRelated = detectRecruitmentRelated({ understanding, slots });
+
+  const companyStrong = slotHasMinConfidence(slots.company, MODE_MIN_CONFIDENCE.strong);
+  const publishedStrong = slotHasMinConfidence(slots.published_at, MODE_MIN_CONFIDENCE.strong);
+  const cohortSupport = slotHasMinConfidence(slots.cohort, MODE_MIN_CONFIDENCE.support);
+  const jobDirectionsSupport = slotHasMinConfidence(slots.job_directions, MODE_MIN_CONFIDENCE.support);
+  const locationsSupport = slotHasMinConfidence(slots.locations, MODE_MIN_CONFIDENCE.support);
+  const processSignal = slotHasMinConfidence(slots.process, MODE_MIN_CONFIDENCE.weakSignal);
+  const recruitmentTypeValue = toSafeString(Array.isArray(slots.recruitment_type?.value)
+    ? slots.recruitment_type.value[0]
+    : slots.recruitment_type?.value);
+  const recruitmentTypeKnown = ['campus', 'intern', 'experienced'].includes(recruitmentTypeValue);
+  const recruitmentTypePresent = recruitmentTypeKnown || recruitmentTypeValue === 'job_posting_unknown';
+  const recruitmentTypeStrong = recruitmentTypeKnown
+    && slotHasMinConfidence(slots.recruitment_type, MODE_MIN_CONFIDENCE.strong);
+  const recruitmentTypeSignal = recruitmentTypePresent
+    && slotHasMinConfidence(slots.recruitment_type, MODE_MIN_CONFIDENCE.weakSignal);
+
+  const keySlots = [slots.company, slots.published_at, slots.recruitment_type, slots.job_directions, slots.locations, slots.process];
+  const confidence = averageSlotConfidence(keySlots);
+  const reliableSignalCount = [
+    companyStrong,
+    publishedStrong,
+    recruitmentTypeSignal,
+    jobDirectionsSupport,
+    locationsSupport,
+    processSignal,
+  ].filter(Boolean).length;
+
+  if (companyStrong && ((publishedStrong && recruitmentTypeStrong) || (cohortSupport && jobDirectionsSupport) || (recruitmentTypeStrong && locationsSupport))) {
+    return { mode: 'job_intel_broadcast', confidence: Number(Math.max(0.7, confidence).toFixed(2)) };
+  }
+
+  if (companyStrong && publishedStrong && recruitmentTypeSignal) {
+    return { mode: 'job_alert', confidence: Number(Math.max(0.6, confidence).toFixed(2)) };
+  }
+
+  if (recruitmentRelated
+    && reliableSignalCount > 0
+    && confidence >= MODE_MIN_CONFIDENCE.floor) {
+    return { mode: 'info_summary', confidence: Number(Math.max(0.42, confidence).toFixed(2)) };
+  }
+
+  return { mode: 'refuse_auto_broadcast', confidence: Number(Math.max(0.2, confidence * 0.6).toFixed(2)) };
+}
+
+function evaluateRecruitmentFailClosed(slots = {}) {
+  const checks = {
+    company: slotHasMinConfidence(slots.company, MODE_MIN_CONFIDENCE.strong),
+    published_at: slotHasMinConfidence(slots.published_at, MODE_MIN_CONFIDENCE.support),
+    recruitment_type: slotHasMinConfidence(slots.recruitment_type, MODE_MIN_CONFIDENCE.weakSignal),
+    cohort: slotHasMinConfidence(slots.cohort, MODE_MIN_CONFIDENCE.support),
+    job_directions: slotHasMinConfidence(slots.job_directions, MODE_MIN_CONFIDENCE.support),
+    locations: slotHasMinConfidence(slots.locations, MODE_MIN_CONFIDENCE.support),
+  };
+
+  let bestGroup = null;
+  for (const group of RECRUITMENT_FAIL_CLOSED_GROUPS) {
+    const hitCount = group.keys.filter(key => checks[key]).length;
+    if (!bestGroup || hitCount > bestGroup.hitCount) {
+      bestGroup = { ...group, hitCount };
+    }
+    if (hitCount === group.keys.length) {
+      return {
+        passed: true,
+        matched_group: group.id,
+        missing_keys: [],
+      };
+    }
+  }
+
+  const missingKeys = bestGroup
+    ? bestGroup.keys.filter(key => !checks[key])
+    : ['company', 'published_at', 'recruitment_type'];
+
+  return {
+    passed: false,
+    matched_group: null,
+    missing_keys: missingKeys,
+    required_groups: RECRUITMENT_FAIL_CLOSED_GROUPS.map(group => [...group.keys]),
+  };
+}
+
+function resolveNarrationMode({ understanding = {}, slots = {} } = {}) {
+  const hintMode = normalizeModeHint(understanding?.mode_hint ?? understanding?.modeHint);
+  const hintConfidence = Number(clampNumber(understanding?.mode_hint_confidence ?? understanding?.modeHintConfidence, 0, 1, 0));
+  const derived = deriveModeFromSlots({ understanding, slots });
+
+  if (!hintMode) {
+    return {
+      mode: derived.mode,
+      confidence: derived.confidence,
+      source: 'derived',
+    };
+  }
+
+  if (hintMode === derived.mode) {
+    return {
+      mode: hintMode,
+      confidence: Number(Math.max(hintConfidence, derived.confidence).toFixed(2)),
+      source: 'hint+derived',
+    };
+  }
+
+  const hintedScore = MODE_SEVERITY[hintMode] ?? 1;
+  const derivedScore = MODE_SEVERITY[derived.mode] ?? 1;
+  const conservativeMode = hintedScore <= derivedScore ? hintMode : derived.mode;
+  const conservativeConfidence = conservativeMode === hintMode ? hintConfidence : derived.confidence;
+  return {
+    mode: conservativeMode,
+    confidence: Number(conservativeConfidence.toFixed(2)),
+    source: 'conservative_merge',
+    hinted_mode: hintMode,
+    derived_mode: derived.mode,
+  };
+}
+
+function focusRegionToHighlight({ focusRegion, fallbackY, id, text, confidence = 0.5 }) {
+  const yRange = normalizeYRange(focusRegion) ?? coerceRangeByY(fallbackY, 260);
+  if (!yRange) return null;
+  return {
+    id,
+    text: toSafeString(text) || null,
+    y_range: yRange,
+    target_y: midpoint(yRange, fallbackY ?? 0),
+    confidence: Number(clampNumber(confidence, 0, 1, 0).toFixed(2)),
+    type: 'semantic_slot',
+  };
+}
+
+function parseHotspot(raw, index = 0) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+
+  const id = toSafeString(raw.id || raw.hotspot_id || raw.name) || `hotspot_${index + 1}`;
+  const text = toSafeString(raw.text_excerpt || raw.textExcerpt || raw.text || raw.reason || raw.label);
+  const weight = clampNumber(raw.weight ?? raw.score ?? raw.priority ?? raw.rank ?? 1, 0, 10, 1);
+
+  let yRange = normalizeYRange(raw.y_range ?? raw.yRange ?? raw.range);
+  if (!yRange) {
+    const center = raw.y_center ?? raw.yCenter ?? raw.target_y ?? raw.targetY ?? raw.y;
+    yRange = coerceRangeByY(center);
+  }
+
+  if (!yRange) return null;
+  const targetY = midpoint(yRange, 0);
+
+  return {
+    id,
+    text,
+    weight,
+    y_range: yRange,
+    target_y: targetY,
+    type: toSafeString(raw.type || raw.kind) || null,
+  };
+}
+
+function collectHotspots(understanding = {}) {
+  const pools = [
+    understanding.visual_hotspots,
+    understanding.visualHotspots,
+    understanding.hotspots,
+    understanding.candidate_hotspots,
+    understanding.candidateHotspots,
+    understanding.highlights,
+  ];
+
+  const rows = [];
+  for (const pool of pools) {
+    if (!Array.isArray(pool)) continue;
+    for (const item of pool) {
+      rows.push(item);
+    }
+  }
+
+  return rows
+    .map((item, index) => parseHotspot(item, index))
+    .filter(Boolean);
+}
+
+function collectSkipZones(understanding = {}) {
+  const pools = [
+    understanding.skip_zones,
+    understanding.skipZones,
+    understanding.ignore_zones,
+    understanding.ignoreZones,
+  ];
+
+  const ranges = [];
+  for (const pool of pools) {
+    if (!Array.isArray(pool)) continue;
+    for (const item of pool) {
+      const range = normalizeYRange(item?.y_range ?? item?.yRange ?? item?.range ?? item);
+      if (range) ranges.push(range);
+    }
+  }
+  return ranges;
+}
+
+function resolveCoreRange(understanding = {}, hotspots = []) {
+  const direct = normalizeYRange(understanding.core_y_range ?? understanding.coreYRange);
+  if (direct) return direct;
+
+  if (hotspots.length > 0) {
+    const ys = hotspots.flatMap(item => item.y_range);
+    const minY = Math.min(...ys);
+    const maxY = Math.max(...ys);
+    if (Number.isFinite(minY) && Number.isFinite(maxY) && maxY > minY) {
+      return [Math.max(0, Math.round(minY - 120)), Math.round(maxY + 120)];
+    }
+  }
+
+  const totalHeight = clampInt(understanding.total_height_px ?? understanding.totalHeightPx ?? 2400, 1200, 12000, 2400);
+  return [0, totalHeight];
+}
+
+function pickHighlightHotspots({ hotspots, skipZones, coreRange, maxHighlights = 3 }) {
+  const [coreStart, coreEnd] = coreRange;
+  const candidates = hotspots
+    .filter((item) => item.target_y >= coreStart && item.target_y <= coreEnd)
+    .filter((item) => !inAnyRange(item.target_y, skipZones))
+    .sort((a, b) => {
+      if (b.weight !== a.weight) return b.weight - a.weight;
+      return a.target_y - b.target_y;
+    });
+
+  const picked = [];
+  for (const candidate of candidates) {
+    if (picked.length >= maxHighlights) break;
+    const tooClose = picked.some(existing => Math.abs(existing.target_y - candidate.target_y) < 260);
+    if (tooClose) continue;
+    picked.push(candidate);
+  }
+
+  if (picked.length > 0) return picked;
+
+  const fallbackY = clampInt((coreStart + coreEnd) / 2, coreStart, coreEnd, coreStart);
+  return [{
+    id: 'fallback_center',
+    text: '核心信息总览',
+    weight: 1,
+    y_range: coerceRangeByY(fallbackY, 240) ?? [fallbackY - 120, fallbackY + 120],
+    target_y: fallbackY,
+    type: 'fallback',
+  }];
+}
+
+function roundDuration(value) {
+  return Number(clampNumber(value, 1, 120, 1).toFixed(1));
+}
+
+function roundSpeed(value) {
+  return Number(clampNumber(value, 0.5, 2.0, 1).toFixed(2));
+}
+
+function computeTotalDuration({ requestedDuration, understanding, profile }) {
+  const [minS, maxS] = profile.duration_range_s;
+
+  const direct = toFiniteNumber(requestedDuration ?? understanding?.target_duration_s ?? understanding?.targetDurationS);
+  if (direct != null) return clampInt(direct, minS, maxS, profile.default_total_duration_s);
+
+  const recommended = understanding?.recommended_duration_s ?? understanding?.recommendedDurationS;
+  const range = normalizeYRange(recommended);
+  if (range) {
+    const mid = Math.round((range[0] + range[1]) / 2);
+    return clampInt(mid, minS, maxS, profile.default_total_duration_s);
+  }
+
+  const recommendedSingle = toFiniteNumber(recommended);
+  if (recommendedSingle != null) {
+    return clampInt(recommendedSingle, minS, maxS, profile.default_total_duration_s);
+  }
+
+  return profile.default_total_duration_s;
+}
+
+function distributeHighlightDurations({ totalDuration, profile, highlightCount }) {
+  const hook = profile.hook_duration_s;
+  const cta = profile.cta_duration_s;
+
+  if (highlightCount <= 0) {
+    return {
+      hook,
+      cta: Math.max(profile.cta_duration_s, totalDuration - hook),
+      highlights: [],
+    };
+  }
+
+  const remaining = Math.max(totalDuration - hook - cta, profile.min_highlight_duration_s * highlightCount);
+  const rawEach = remaining / highlightCount;
+  const each = Math.max(profile.min_highlight_duration_s, rawEach);
+  const highlights = new Array(highlightCount).fill(0).map(() => roundDuration(each));
+
+  const consumed = hook + cta + highlights.reduce((sum, item) => sum + item, 0);
+  const delta = roundDuration(totalDuration - consumed);
+  if (Math.abs(delta) >= 0.1 && highlights.length > 0) {
+    highlights[highlights.length - 1] = roundDuration(highlights[highlights.length - 1] + delta);
+  }
+
+  return { hook, cta, highlights };
+}
+
+function buildHookAction({ coreRange, firstHighlight }) {
+  if (firstHighlight?.id) {
+    return {
+      type: 'cursor_focus',
+      target_hotspot: firstHighlight.id,
+      target_y: firstHighlight.target_y,
+      reason: '聚焦第一关键点，建立开场锚点',
+    };
+  }
+  return {
+    type: 'scroll_to_dwell',
+    target_y: coreRange[0],
+    transition_ms: 700,
+    reason: '无显式热点时先定位核心区起点',
+  };
+}
+
+function buildHighlightAction({ highlight, index, previousY }) {
+  const currentY = highlight.target_y;
+
+  if (index === 0 || previousY == null) {
+    return {
+      type: 'scroll_to_dwell',
+      target_hotspot: highlight.id,
+      target_y: currentY,
+      transition_ms: 800,
+    };
+  }
+
+  const distance = Math.abs(currentY - previousY);
+  if (distance >= 420) {
+    return {
+      type: 'linear_scroll_during',
+      target_hotspot: highlight.id,
+      from_y: previousY,
+      to_y: currentY,
+    };
+  }
+
+  return {
+    type: 'cursor_focus',
+    target_hotspot: highlight.id,
+    target_y: currentY,
+  };
+}
+
+function buildCtaAction({ coreRange }) {
+  return {
+    type: 'scroll_back',
+    target_y: coreRange[0],
+    transition_ms: 900,
+    reason: '收尾回到核心起点，承接 CTA',
+  };
+}
+
+function buildNarrativeArc(highlights = []) {
+  return [
+    'hook',
+    ...highlights.map((_, index) => `highlight_${index + 1}`),
+    'cta',
+  ];
+}
+
+function resolveFallbackY({ coreRange, hotspots, index = 0 }) {
+  if (Array.isArray(hotspots) && hotspots[index]?.target_y != null) {
+    return hotspots[index].target_y;
+  }
+  return midpoint(coreRange, coreRange[0] ?? 0);
+}
+
+function pickFirstAvailableSlot(slots, keys = []) {
+  for (const key of keys) {
+    if (slotHasValue(slots[key])) return key;
+  }
+  return null;
+}
+
+function pickSlotKeysForMode({ mode, slots }) {
+  if (mode === 'job_intel_broadcast') {
+    const ordered = ['job_directions', 'locations', 'process', 'target_or_requirements', 'cohort'];
+    return ordered.filter(key => slotHasValue(slots[key])).slice(0, 3);
+  }
+  if (mode === 'job_alert') {
+    const ordered = ['job_directions', 'locations', 'cohort', 'entry_or_cta'];
+    return ordered.filter(key => slotHasValue(slots[key])).slice(0, 1);
+  }
+  if (mode === 'info_summary') {
+    const ordered = ['target_or_requirements', 'process', 'job_directions'];
+    return ordered.filter(key => slotHasValue(slots[key])).slice(0, 1);
+  }
+  return [];
+}
+
+function buildSlotBackedHighlights({
+  slots,
+  slotKeys = [],
+  hotspots = [],
+  coreRange = [0, 0],
+}) {
+  const highlights = [];
+  const usedTargets = [];
+  for (let i = 0; i < slotKeys.length; i += 1) {
+    const key = slotKeys[i];
+    const slot = slots[key];
+    const fallbackY = resolveFallbackY({ coreRange, hotspots, index: i });
+    const text = key === 'recruitment_type'
+      ? formatRecruitmentType(slot)
+      : slotValueToText(slot);
+    const base = focusRegionToHighlight({
+      focusRegion: slot?.focus_region,
+      fallbackY,
+      id: `slot_${key}`,
+      text: text || `${slotLabel(key)}线索`,
+      confidence: slot?.confidence ?? 0.5,
+    });
+    if (!base) continue;
+    const tooClose = usedTargets.some(target => Math.abs(target - base.target_y) < 220);
+    if (tooClose) continue;
+    highlights.push({
+      ...base,
+      semantic_slot: key,
+      slot_confidence: Number(clampNumber(slot?.confidence, 0, 1, 0).toFixed(2)),
+    });
+    usedTargets.push(base.target_y);
+  }
+  return highlights;
+}
+
+function buildSemanticSummary(slots = {}) {
+  return {
+    company: slotValueToText(slots.company),
+    published_at: slotValueToText(slots.published_at),
+    recruitment_type: formatRecruitmentType(slots.recruitment_type) || slotValueToText(slots.recruitment_type),
+    cohort: slotValueToText(slots.cohort),
+    job_directions: slotValueToText(slots.job_directions),
+    locations: slotValueToText(slots.locations),
+    target_or_requirements: slotValueToText(slots.target_or_requirements),
+    process: slotValueToText(slots.process),
+    entry_or_cta: slotValueToText(slots.entry_or_cta),
+  };
+}
+
+function describeCameraMotion(actionType) {
+  if (actionType === 'linear_scroll_during') return 'narrated_pan';
+  if (actionType === 'cursor_focus') return 'cursor_focus';
+  if (actionType === 'scroll_back') return 'return_anchor';
+  return 'focus_hold';
+}
+
+export function planVideo({
+  understanding = {},
+  persona = '',
+  target_platform = 'xiaohongshu',
+  total_duration_s = null,
+} = {}) {
+  const profile = getPlatformProfile(target_platform);
+  const normalizedPersona = toSafeString(persona || understanding?.persona || '目标受众');
+  const coreMessage = toSafeString(understanding?.core_message || understanding?.coreMessage || understanding?.title) || '本页价值点概览';
+
+  const hotspots = collectHotspots(understanding);
+  const skipZones = collectSkipZones(understanding);
+  const coreRange = resolveCoreRange(understanding, hotspots);
+  const semanticSlots = collectSemanticSlots(understanding);
+  const recruitmentFailClosedEnabled = shouldApplyRecruitmentFailClosed(understanding);
+  const failClosedGate = evaluateRecruitmentFailClosed(semanticSlots);
+  if (recruitmentFailClosedEnabled && !failClosedGate.passed) {
+    const missingLabels = failClosedGate.missing_keys
+      .map(key => slotLabel(key))
+      .filter(Boolean);
+    const requiredLabels = RECRUITMENT_FAIL_CLOSED_GROUPS
+      .map(group => group.keys.map(key => slotLabel(key)).join('+'))
+      .join(' | ');
+    throw new Error(
+      `recruitment_fail_closed:missing=${missingLabels.join('、') || '关键槽位'};required_any_of=${requiredLabels}`
+    );
+  }
+  const hasSemanticSlots = hasAnySemanticSlot(semanticSlots);
+  const modeInfo = resolveNarrationMode({ understanding, slots: semanticSlots });
+  const semanticSummary = buildSemanticSummary(semanticSlots);
+
+  const hotspotHighlights = pickHighlightHotspots({
+    hotspots,
+    skipZones,
+    coreRange,
+    maxHighlights: 3,
+  }).slice(0, 3);
+
+  const totalDuration = computeTotalDuration({
+    requestedDuration: total_duration_s,
+    understanding,
+    profile,
+  });
+
+  const maxHighlightsByBudget = Math.max(
+    1,
+    Math.floor(
+      Math.max(totalDuration - profile.hook_duration_s - profile.cta_duration_s, profile.min_highlight_duration_s)
+      / profile.min_highlight_duration_s
+    )
+  );
+  const semanticHighlightKeys = pickSlotKeysForMode({
+    mode: modeInfo.mode,
+    slots: semanticSlots,
+  });
+  const semanticHighlights = buildSlotBackedHighlights({
+    slots: semanticSlots,
+    slotKeys: semanticHighlightKeys,
+    hotspots: hotspotHighlights,
+    coreRange,
+  });
+
+  let normalizedHighlights = semanticHighlights;
+  if (!hasSemanticSlots || normalizedHighlights.length === 0) {
+    normalizedHighlights = hotspotHighlights.map(item => ({
+      ...item,
+      semantic_slot: null,
+      slot_confidence: null,
+    }));
+  }
+
+  const expectedHighlights = modeInfo.mode === 'refuse_auto_broadcast'
+    ? 0
+    : Math.max(1, Math.min(3, maxHighlightsByBudget));
+  normalizedHighlights = normalizedHighlights.slice(0, expectedHighlights);
+
+  const allocation = distributeHighlightDurations({
+    totalDuration,
+    profile,
+    highlightCount: normalizedHighlights.length,
+  });
+
+  const phasePlan = [];
+  const hookSlotKey = pickFirstAvailableSlot(semanticSlots, ['company', 'published_at', 'recruitment_type', 'cohort']);
+  const hookSlot = hookSlotKey ? semanticSlots[hookSlotKey] : null;
+  const hookAnchor = focusRegionToHighlight({
+    focusRegion: hookSlot?.focus_region,
+    fallbackY: resolveFallbackY({ coreRange, hotspots: hotspotHighlights, index: 0 }),
+    id: hookSlotKey ? `slot_${hookSlotKey}` : 'hook_anchor',
+    text: hookSlotKey === 'recruitment_type'
+      ? (formatRecruitmentType(hookSlot) || slotLabel(hookSlotKey))
+      : (slotValueToText(hookSlot) || slotLabel(hookSlotKey || 'company')),
+    confidence: hookSlot?.confidence ?? 0.4,
+  });
+
+  phasePlan.push({
+    phase_id: 'hook',
+    role: 'hook',
+    duration_s: roundDuration(allocation.hook),
+    visual_action: buildHookAction({
+      coreRange,
+      firstHighlight: hookAnchor ?? normalizedHighlights[0],
+    }),
+    semantic_slot: hookSlotKey,
+    focus_region: hookAnchor?.y_range ?? null,
+    confidence: hookSlot ? Number(clampNumber(hookSlot.confidence, 0, 1, 0).toFixed(2)) : null,
+    guidance: `开场先说结论，语气为${profile.tone}`,
+  });
+
+  let previousY = hookAnchor?.target_y ?? null;
+  for (let i = 0; i < normalizedHighlights.length; i += 1) {
+    const highlight = normalizedHighlights[i];
+    const phaseId = `highlight_${i + 1}`;
+    phasePlan.push({
+      phase_id: phaseId,
+      role: 'highlight',
+      highlight_index: i + 1,
+      duration_s: roundDuration(allocation.highlights[i] ?? profile.min_highlight_duration_s),
+      visual_action: buildHighlightAction({
+        highlight,
+        index: i,
+        previousY,
+      }),
+      highlight: {
+        id: highlight.id,
+        text: highlight.text || null,
+        y_range: highlight.y_range,
+        target_y: highlight.target_y,
+      },
+      semantic_slot: toSafeString(highlight.semantic_slot) || null,
+      focus_region: normalizeYRange(highlight.y_range),
+      confidence: highlight.slot_confidence == null
+        ? Number(clampNumber(highlight.confidence, 0, 1, 0).toFixed(2))
+        : Number(clampNumber(highlight.slot_confidence, 0, 1, 0).toFixed(2)),
+      guidance: '讲清这段信息的结论、证据与行动意义',
+    });
+    previousY = highlight.target_y;
+  }
+
+  const ctaSlotKey = pickFirstAvailableSlot(semanticSlots, ['entry_or_cta', 'process', 'company']);
+  const ctaSlot = ctaSlotKey ? semanticSlots[ctaSlotKey] : null;
+  const ctaAnchor = focusRegionToHighlight({
+    focusRegion: ctaSlot?.focus_region,
+    fallbackY: resolveFallbackY({ coreRange, hotspots: hotspotHighlights, index: 2 }),
+    id: ctaSlotKey ? `slot_${ctaSlotKey}` : 'cta_anchor',
+    text: ctaSlotKey ? (slotValueToText(ctaSlot) || slotLabel(ctaSlotKey)) : '收尾行动',
+    confidence: ctaSlot?.confidence ?? 0.38,
+  });
+  const ctaAction = ctaAnchor && modeInfo.mode !== 'refuse_auto_broadcast'
+    ? {
+      type: 'scroll_to_dwell',
+      target_hotspot: ctaAnchor.id,
+      target_y: ctaAnchor.target_y,
+      transition_ms: 900,
+      reason: '收尾聚焦投递入口或行动提示',
+    }
+    : buildCtaAction({ coreRange });
+
+  phasePlan.push({
+    phase_id: 'cta',
+    role: 'cta',
+    duration_s: roundDuration(allocation.cta),
+    visual_action: ctaAction,
+    semantic_slot: ctaSlotKey,
+    focus_region: ctaAnchor?.y_range ?? null,
+    confidence: ctaSlot ? Number(clampNumber(ctaSlot.confidence, 0, 1, 0).toFixed(2)) : null,
+    guidance: '收尾给出下一步动作，避免空泛口号',
+  });
+
+  const cappedPlan = phasePlan.slice(0, 5);
+  const highlightPhases = cappedPlan.filter(item => item.role === 'highlight');
+
+  return {
+    version: 'video-narration-plan/v1',
+    target_platform: profile.id,
+    persona: normalizedPersona,
+    core_message: coreMessage,
+    narrative_arc: buildNarrativeArc(highlightPhases),
+    narration_mode: modeInfo.mode,
+    narration_mode_confidence: modeInfo.confidence,
+    narration_mode_source: modeInfo.source,
+    semantic_slots: semanticSlots,
+    semantic_summary: semanticSummary,
+    duration_range_s: profile.duration_range_s,
+    total_duration_s: roundDuration(
+      cappedPlan.reduce((sum, phase) => sum + Number(phase.duration_s || 0), 0)
+    ),
+    phase_plan: cappedPlan,
+    constraints: {
+      max_phases: 5,
+      max_highlights: 3,
+      phase_count: cappedPlan.length,
+      highlight_count: highlightPhases.length,
+    },
+    context: {
+      page_type: toSafeString(understanding?.page_type || understanding?.pageType) || null,
+      url: toSafeString(understanding?.url) || null,
+      hotspot_count: hotspots.length,
+      skip_zone_count: skipZones.length,
+      core_y_range: coreRange,
+      has_semantic_slots: hasSemanticSlots,
+      mode_hint: normalizeModeHint(understanding?.mode_hint ?? understanding?.modeHint),
+      mode_hint_confidence: Number(clampNumber(understanding?.mode_hint_confidence ?? understanding?.modeHintConfidence, 0, 1, 0).toFixed(2)),
+    },
+  };
+}
+
+function resolveVoiceForPhase({ profile, role, index = 0 }) {
+  const baseSpeed = profile.speed;
+
+  if (role === 'hook') {
+    return {
+      voice_preset: profile.voice_preset,
+      speed: roundSpeed(baseSpeed + 0.03),
+    };
+  }
+
+  if (role === 'cta') {
+    const delta = profile.id === 'douyin' ? -0.02 : -0.04;
+    return {
+      voice_preset: profile.voice_preset,
+      speed: roundSpeed(baseSpeed + delta),
+    };
+  }
+
+  const modulation = index % 2 === 0 ? 0 : -0.01;
+  return {
+    voice_preset: profile.voice_preset,
+    speed: roundSpeed(baseSpeed + modulation),
+  };
+}
+
+function resolveSummaryValue(strategy = {}, slotKey) {
+  const summary = toSafeString(strategy?.semantic_summary?.[slotKey]);
+  if (summary) return summary;
+  const slot = strategy?.semantic_slots?.[slotKey];
+  if (!slot) return '';
+  if (slotKey === 'recruitment_type') return formatRecruitmentType(slot) || slotValueToText(slot);
+  return slotValueToText(slot);
+}
+
+function describeHighlightFocus(phase) {
+  const semanticLabel = slotLabel(toSafeString(phase?.semantic_slot));
+  const text = toSafeString(phase?.highlight?.text || phase?.highlight?.id || semanticLabel || phase?.visual_action?.target_hotspot);
+  if (!text) return '页面核心信息';
+  return text;
+}
+
+function buildPhaseSentence({ phase, strategy, phaseIndex }) {
+  const role = toSafeString(phase?.role || '').toLowerCase() || (phase?.phase_id === 'cta' ? 'cta' : 'highlight');
+  const mode = normalizeModeHint(strategy?.narration_mode) || 'info_summary';
+  const slotKey = toSafeString(phase?.semantic_slot);
+  const slotText = resolveSummaryValue(strategy, slotKey);
+  const slotTextOrFallback = slotText || describeHighlightFocus(phase);
+  const company = resolveSummaryValue(strategy, 'company') || '该公司';
+  const publishedAt = resolveSummaryValue(strategy, 'published_at') || '近期';
+  const recruitmentType = resolveSummaryValue(strategy, 'recruitment_type') || '招聘信息';
+  const cohort = resolveSummaryValue(strategy, 'cohort');
+  const entry = resolveSummaryValue(strategy, 'entry_or_cta') || '官方岗位入口';
+  const locations = resolveSummaryValue(strategy, 'locations');
+  const jobDirections = resolveSummaryValue(strategy, 'job_directions');
+  const process = resolveSummaryValue(strategy, 'process');
+  const targetOrRequirements = resolveSummaryValue(strategy, 'target_or_requirements');
+
+  if (role === 'hook') {
+    if (mode === 'job_intel_broadcast') {
+      const cohortPart = cohort ? `${cohort} ` : '';
+      return ensureSentenceLength(
+        `岗位情报先划重点：${company}在${publishedAt}发布了${cohortPart}${recruitmentType}。接下来我会按岗位方向、城市和流程三块快速过一遍，只保留能直接支持投递判断的信息。`
+      );
+    }
+
+    if (mode === 'job_alert') {
+      return ensureSentenceLength(
+        `这是一条岗位提醒：${company}在${publishedAt}发布了${recruitmentType}。当前页面细节不完整，我只说已经能确认的事实，帮你先判断要不要继续花时间深挖。`
+      );
+    }
+
+    if (mode === 'refuse_auto_broadcast') {
+      return ensureSentenceLength(
+        '当前页面缺少稳定的公司、岗位或发布时间线索，我不能直接生成岗位情报式结论。为了避免误导，下面仅给你保守处理建议。'
+      );
+    }
+
+    return ensureSentenceLength(
+      '这条链接和招聘信息相关，但更像资讯或公告汇总。下面我只提可核验线索，帮助你快速决定是否跳转到官方岗位页继续确认。'
+    );
+  }
+
+  if (role === 'cta') {
+    if (mode === 'job_intel_broadcast') {
+      return ensureSentenceLength(
+        `最后给行动建议：如果你对这次机会感兴趣，优先去${entry}核对截止时间、岗位要求和投递方式，再决定是否马上投递；如果与你目标不匹配，就按同一口径快速跳过。`
+      );
+    }
+
+    if (mode === 'job_alert') {
+      return ensureSentenceLength(
+        `建议先把这条提醒收藏，然后去${entry}逐项核对岗位方向、城市和流程细节。确认信息完整后再投递，会比凭单条资讯直接判断更稳妥。`
+      );
+    }
+
+    if (mode === 'refuse_auto_broadcast') {
+      return ensureSentenceLength(
+        '建议补充官方招聘链接，或提供包含公司、岗位、发布时间的清晰页面截图后再自动播报。信息完整度上来后，系统才能给出可执行的投递判断。'
+      );
+    }
+
+    return ensureSentenceLength(
+      `把它当作招聘资讯线索更合适：最终请以${entry}的原始岗位说明为准，尤其是城市、要求和截止时间，避免被二次转述或摘要信息带偏判断。`
+    );
+  }
+
+  if (mode === 'job_intel_broadcast') {
+    if (slotKey === 'job_directions') {
+      return ensureSentenceLength(
+        `岗位方向目前可确认为${slotTextOrFallback}。这直接决定你是否值得继续投入，建议先对照自己的专业或技能栈做第一轮筛选，再看后续细节。`
+      );
+    }
+    if (slotKey === 'locations') {
+      return ensureSentenceLength(
+        `工作城市线索是${slotTextOrFallback}。这一步主要用于判断通勤与生活成本是否可接受，先把城市匹配度过一遍，能明显减少后续无效投递。`
+      );
+    }
+    if (slotKey === 'process') {
+      return ensureSentenceLength(
+        `招聘流程可读到${slotTextOrFallback}。你可以按这个顺序预留时间准备简历、测评和面试节点，避免临近截止才发现准备节奏不够。`
+      );
+    }
+    if (slotKey === 'target_or_requirements') {
+      return ensureSentenceLength(
+        `任职对象与要求显示为${slotTextOrFallback}。这一段最适合做硬性条件核对，先看是否满足门槛，再决定要不要继续投入申请材料。`
+      );
+    }
+    return ensureSentenceLength(
+      `补充一个关键信息：${slotLabel(slotKey) || '重点线索'}是${slotTextOrFallback}。这条信息能帮助你更快判断岗位匹配度，避免被页面里次要内容分散注意力。`
+    );
+  }
+
+  if (mode === 'job_alert') {
+    return ensureSentenceLength(
+      `目前页面能稳定识别的${slotLabel(slotKey) || '线索'}是${slotTextOrFallback}。其余细节暂不充足，建议你把它当作提醒信号，再回到原文逐条核验。`
+    );
+  }
+
+  if (mode === 'refuse_auto_broadcast') {
+    return ensureSentenceLength(
+      `这一段的${slotLabel(slotKey) || '线索'}置信度仍然偏低，我不会把“${slotTextOrFallback}”当成可直接投递依据。先补充权威来源，再做下一步判断更安全。`
+    );
+  }
+
+  const summaryPieces = [jobDirections, locations, process, targetOrRequirements].filter(Boolean).slice(0, 2);
+  return ensureSentenceLength(
+    `第${phaseIndex + 1}个可核验线索是${slotTextOrFallback}。目前它更适合作为招聘资讯摘要，${summaryPieces.length > 0 ? `可结合${summaryPieces.join('、')}交叉判断` : `建议与官方岗位页交叉核对`}，不要直接当成完整岗位说明。`
+  );
+}
+
+function estimateDurationMs(text, speed = 1) {
+  const chars = Math.max(1, toCharLength(text));
+  const cps = clampNumber(28 * Number(speed || 1), 12, 48, 28);
+  return Math.max(1500, Math.round((chars / cps) * 1000));
+}
+
+function resolveAudioId(payload = {}, fallbackPrefix = 'audio') {
+  const direct = toSafeString(payload.audio_id || payload.audioId);
+  if (direct) return direct;
+
+  const audioPath = toSafeString(payload.audio_path || payload.audioPath);
+  if (audioPath) {
+    const base = path.basename(audioPath, path.extname(audioPath));
+    if (base) return base;
+  }
+
+  const audioUrl = toSafeString(payload.audio_url || payload.audioUrl);
+  if (audioUrl) {
+    try {
+      const parsed = new URL(audioUrl);
+      const base = path.posix.basename(parsed.pathname || '', path.posix.extname(parsed.pathname || ''));
+      if (base) return base;
+    } catch {
+      // ignore URL parse failure
+    }
+  }
+
+  return `${fallbackPrefix}-${randomUUID().slice(0, 8)}`;
+}
+
+async function callGenerateVoiceover({
+  env,
+  fetchFn,
+  workspaceId,
+  text,
+  voicePreset,
+  speed,
+  format,
+  credentialId,
+}) {
+  const serverUrl = toSafeString(env?.SERVER_URL);
+  const machineApiKey = toSafeString(env?.MACHINE_API_KEY);
+  const agentId = toSafeString(env?.AGENT_ID);
+
+  if (!serverUrl || !machineApiKey || !agentId) {
+    throw new Error('tts_runtime_env_missing');
+  }
+
+  const targetWorkspaceId = toSafeString(workspaceId || env?.WORKSPACE_ID);
+  if (!targetWorkspaceId) {
+    throw new Error('tts_workspace_id_missing');
+  }
+
+  const payload = {
+    workspace_id: targetWorkspaceId,
+    text,
+    voice_preset: voicePreset,
+    speed,
+    format,
+  };
+  if (credentialId) payload.credential_id = credentialId;
+
+  const url = `${serverUrl.replace(/\/+$/, '')}/internal/agent/${encodeURIComponent(agentId)}/tts/voiceover`;
+  const response = await fetchFn(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${machineApiKey}`,
+    },
+    body: JSON.stringify(payload),
+  });
+
+  const textBody = await response.text();
+  let data = null;
+  try {
+    data = JSON.parse(textBody);
+  } catch {
+    data = null;
+  }
+
+  if (!response.ok) {
+    const errorText = toSafeString(data?.error || textBody).slice(0, 240);
+    throw new Error(`tts_http_${response.status}:${errorText || 'unknown_error'}`);
+  }
+
+  const duration = toFiniteNumber(data?.duration_ms);
+  if (duration == null || duration <= 0) {
+    throw new Error('tts_duration_missing');
+  }
+
+  return {
+    audio_id: resolveAudioId(data, 'voiceover'),
+    duration_ms: Math.round(duration),
+    audio_url: toSafeString(data?.audio_url) || null,
+    audio_path: toSafeString(data?.audio_path) || null,
+    provider: toSafeString(data?.provider) || null,
+    format: toSafeString(data?.format) || format,
+    voice_preset: toSafeString(data?.voice_preset) || voicePreset,
+  };
+}
+
+function normalizePhaseList(strategy = {}) {
+  const phases = Array.isArray(strategy?.phase_plan) ? strategy.phase_plan : [];
+  if (phases.length > 0) return phases.slice(0, 5);
+
+  return [
+    {
+      phase_id: 'hook',
+      role: 'hook',
+      duration_s: 6,
+      visual_action: { type: 'scroll_to_dwell', target_y: 0 },
+    },
+    {
+      phase_id: 'cta',
+      role: 'cta',
+      duration_s: 6,
+      visual_action: { type: 'scroll_back', target_y: 0 },
+    },
+  ];
+}
+
+function normalizeVisualAction(rawAction = {}, fallbackType = 'scroll_to_dwell') {
+  const typeRaw = toSafeString(rawAction?.type).toLowerCase();
+  const type = VISUAL_ACTION_SET.has(typeRaw) ? typeRaw : fallbackType;
+  return {
+    ...rawAction,
+    type,
+  };
+}
+
+function shouldTryTts({ env, workspaceId }) {
+  const serverUrl = toSafeString(env?.SERVER_URL);
+  const machineApiKey = toSafeString(env?.MACHINE_API_KEY);
+  const agentId = toSafeString(env?.AGENT_ID);
+  const targetWorkspaceId = toSafeString(workspaceId || env?.WORKSPACE_ID);
+  return Boolean(serverUrl && machineApiKey && agentId && targetWorkspaceId);
+}
+
+export async function detailSections({
+  strategy = {},
+  workspace_id = null,
+  credential_id = null,
+  format = 'mp3',
+  strict_tts = false,
+} = {}, {
+  env = process.env,
+  fetchFn = globalThis.fetch,
+} = {}) {
+  const profile = getPlatformProfile(strategy?.target_platform);
+  const phases = normalizePhaseList(strategy);
+
+  const sections = [];
+  const ttsErrors = [];
+  let usedLiveTts = false;
+
+  for (let i = 0; i < phases.length; i += 1) {
+    const phase = phases[i];
+    const role = toSafeString(phase?.role).toLowerCase() || (phase?.phase_id === 'cta' ? 'cta' : (phase?.phase_id === 'hook' ? 'hook' : 'highlight'));
+
+    const sentence = buildPhaseSentence({
+      phase,
+      strategy,
+      phaseIndex: i,
+    });
+
+    const voice = resolveVoiceForPhase({ profile, role, index: i });
+    const phaseBudgetMs = clampInt((toFiniteNumber(phase?.duration_s) ?? 6) * 1000, 1000, 180000, 6000);
+
+    let audio = null;
+    const tryTts = shouldTryTts({ env, workspaceId: workspace_id });
+
+    if (tryTts) {
+      try {
+        audio = await callGenerateVoiceover({
+          env,
+          fetchFn,
+          workspaceId: workspace_id,
+          text: sentence,
+          voicePreset: voice.voice_preset,
+          speed: voice.speed,
+          format: toSafeString(format).toLowerCase() || 'mp3',
+          credentialId: toSafeString(credential_id) || null,
+        });
+        usedLiveTts = true;
+      } catch (error) {
+        const message = toSafeString(error?.message) || 'tts_call_failed';
+        ttsErrors.push({ phase_id: phase.phase_id, error: message });
+        if (strict_tts) {
+          throw new Error(`detail_sections_tts_failed:${phase.phase_id}:${message}`);
+        }
+      }
+    }
+
+    if (!audio) {
+      const estimatedDuration = estimateDurationMs(sentence, voice.speed);
+      audio = {
+        audio_id: `estimated-${phase.phase_id || `p${i + 1}`}`,
+        duration_ms: estimatedDuration,
+        audio_url: null,
+        audio_path: null,
+        provider: 'estimated',
+        format: toSafeString(format).toLowerCase() || 'mp3',
+        voice_preset: voice.voice_preset,
+      };
+    }
+
+    const durationMs = clampInt(audio.duration_ms, 300, 180000, phaseBudgetMs);
+    const dwellMs = Math.max(durationMs, phaseBudgetMs);
+
+    const visualAction = normalizeVisualAction(phase.visual_action, role === 'cta' ? 'scroll_back' : 'scroll_to_dwell');
+    const phaseFocusRegion = normalizeYRange(
+      phase.focus_region
+      ?? phase.highlight?.y_range
+      ?? phase.semantic_focus_region
+      ?? phase.semanticFocusRegion
+    );
+
+    sections.push({
+      phase_id: toSafeString(phase.phase_id) || `phase_${i + 1}`,
+      visual_action: visualAction,
+      sentence,
+      voice_preset: voice.voice_preset,
+      speed: voice.speed,
+      audio_id: audio.audio_id,
+      duration_ms: durationMs,
+      dwell_ms: dwellMs,
+      audio_url: audio.audio_url,
+      audio_path: audio.audio_path,
+      semantic_slot: toSafeString(phase.semantic_slot) || null,
+      focus_region: phaseFocusRegion,
+      confidence: toFiniteNumber(phase.confidence) != null
+        ? Number(clampNumber(phase.confidence, 0, 1, 0).toFixed(2))
+        : null,
+      camera_motion: describeCameraMotion(visualAction.type),
+    });
+  }
+
+  const totalDurationMs = sections.reduce((sum, item) => sum + item.dwell_ms, 0);
+
+  return {
+    sections,
+    outro_video_id: toSafeString(strategy?.outro_video_id || strategy?.outroVideoId) || DEFAULT_OUTRO_VIDEO_ID,
+    total_duration_ms: totalDurationMs,
+    constraints: {
+      sections_count: sections.length,
+      max_sections: 5,
+      dwell_covers_audio: sections.every(item => item.dwell_ms >= item.duration_ms),
+      sentence_char_range: [SENTENCE_MIN_CHARS, SENTENCE_MAX_CHARS],
+    },
+    meta: {
+      target_platform: profile.id,
+      tts_mode: usedLiveTts ? 'live_or_partial_live' : 'estimated',
+      tts_errors: ttsErrors,
+    },
+  };
+}
+
+export function createVideoNarrationPlanner(runtime = {}) {
+  const env = runtime.env ?? process.env;
+  const fetchFn = runtime.fetchFn ?? globalThis.fetch;
+
+  return {
+    planVideo: (input = {}) => planVideo(input),
+    detailSections: (input = {}) => detailSections(input, { env, fetchFn }),
+  };
+}
+
+export { normalizeTargetPlatform, getPlatformProfile, ensureSentenceLength };