dsh-drawai 0.3.4 → 0.4.1

package/lib/motion-core.js

@@ -0,0 +1,238 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+import { isShotCardNode } from './shotcard-core.js'
+import { isMgStyleNode } from './mgstyle-core.js'
+/* Serializable motion documents shared by the host and canvas. Scene sources are rendered only by the worker. */
+export const MOTION_VERSION = 1
+export const MOTION_ROLES = ['material', 'copy', 'instruction', 'style', 'layout', 'shotcard', 'mgstyle', 'audio']
+const motionClone = (value) => JSON.parse(JSON.stringify(value))
+const motionStable = (value) => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+  ? Object.fromEntries(Object.keys(item).sort().map((key) => [key, item[key]])) : item)
+
+export function motionSettings(raw = {}) {
+  const integer = (value, fallback, min, max) => {
+    const n = value === undefined ? fallback : Number(value)
+    if (!Number.isInteger(n) || n < min || n > max) throw new Error('无效的动效尺寸、帧率或时长')
+    return n
+  }
+  if (raw.mode !== undefined && raw.mode !== 'scene') throw new Error('仅支持 Shotcraft 场景创作')
+  if (raw.preferredCards !== undefined && (!Array.isArray(raw.preferredCards) || raw.preferredCards.length > 6 || raw.preferredCards.some((id) => typeof id !== 'string' || !/^[a-z0-9-]+$/.test(id)))) throw new Error('最多选择 6 张镜头参考卡')
+  const fps = integer(raw.fps, 30, 12, 30)
+  const duration = Number(raw.duration ?? 12)
+  if (!Number.isFinite(duration) || duration < 2 || duration > 60) throw new Error('无效的动效尺寸、帧率或时长')
+  if(raw.audioMode!==undefined&&!['auto','manual','off'].includes(raw.audioMode))throw new Error('未知声音制作模式')
+  if(raw.audioPlan!==undefined&&(!raw.audioPlan||typeof raw.audioPlan!=='object'||Array.isArray(raw.audioPlan)||JSON.stringify(raw.audioPlan).length>100000))throw new Error('声音时间表无效或过大')
+  return { prompt: String(raw.prompt || '').trim().slice(0, 12000), mode: 'scene',
+    ...(raw.audioMode?{audioMode:raw.audioMode}:{}),...(raw.audioPrompt!==undefined?{audioPrompt:String(raw.audioPrompt).slice(0,5000)}:{}),...(raw.audioPlan?{audioPlan:motionClone(raw.audioPlan)}:{}),
+    ...(raw.preferredCards ? { preferredCards: [...new Set(raw.preferredCards)] } : {}),
+    width: integer(raw.width, 1280, 256, 1920), height: integer(raw.height, 720, 256, 1920),
+    fps, duration: Math.round(duration * fps) / fps }
+}
+
+// Explicit tool settings override stored values; rendering always uses whole frames.
+export function mergeMotionSettings(current, patch = {}) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new Error('settings 必须是设置对象')
+  if (Object.keys(patch).some((key) => !['width', 'height', 'fps', 'duration', 'totalFrames', 'audioMode', 'audioPrompt', 'audioPlan'].includes(key))) throw new Error('未知视频设置字段')
+  const { totalFrames, ...values } = patch
+  const next = motionSettings({ ...current, ...values })
+  if (totalFrames !== undefined) {
+    if (!Number.isInteger(totalFrames) || totalFrames < next.fps * 2 || totalFrames > next.fps * 60) throw new Error('totalFrames 必须为 2–60 秒范围内的整数帧数')
+    if (patch.duration !== undefined && Math.round(Number(patch.duration) * next.fps) !== totalFrames) throw new Error('duration 与 totalFrames 冲突')
+    next.duration = totalFrames / next.fps
+  }
+  return { ...current, ...next }
+}
+
+export function isMotionNode(node) { return node?.data?.drawaiMotion === '1' }
+export function isAudioNode(node) { return node?.data?.drawaiAudio === '1' }
+export function audioNodeData(role = 'sfx') {
+  if (!['sfx','bgm','voice'].includes(role)) throw new Error('未知音频用途')
+  return { drawaiAudio:'1',audioRole:role,audioGainDb:role==='bgm'?'-14':'0',audioTrimStart:'0',audioTrimEnd:'0',audioAt:'0',audioFadeIn:role==='bgm'?'0.3':'0',audioFadeOut:role==='bgm'?'0.5':'0',audioLoop:'0' }
+}
+export function audioNodeSettings(data) {
+  const number=(key,fallback,min,max)=>{const value=Number(data[key]??fallback);if(!Number.isFinite(value)||value<min||value>max)throw new Error('无效音频设置：'+key);return value}
+  const role=data.audioRole||'sfx'
+  if(!['sfx','bgm','voice'].includes(role))throw new Error('未知音频用途')
+  const settings={role,gainDb:number('audioGainDb',role==='bgm'?-14:0,-60,18),trimStart:number('audioTrimStart',0,0,600),trimEnd:number('audioTrimEnd',0,0,600),
+    at:number('audioAt',0,0,60),fadeIn:number('audioFadeIn',0,0,60),fadeOut:number('audioFadeOut',0,0,60),loop:data.audioLoop==='1'}
+  if(settings.trimEnd && settings.trimEnd<=settings.trimStart)throw new Error('音频裁切结束必须晚于开始')
+  return settings
+}
+
+export function validateAudioTimeline(raw,composition,input) {
+  if(!raw)return {version:1,cues:[],notes:[]}
+  if(!Array.isArray(raw.cues)||raw.cues.length>64)throw new Error('声音时间表最多64条')
+  const fps=composition.fps,total=composition.durationFrames
+  const cues=raw.cues.map((cue,index)=>{
+    const ref=input.refs.find(ref=>ref.id===cue.referenceId&&ref.role==='audio')
+    if(!ref)throw new Error('音频来源不存在：'+cue.referenceId)
+    const node=ref.nodes.find(isAudioNode),defaults=audioNodeSettings(node?.data||{})
+    const shot=cue.shotId?composition.shots.find(shot=>shot.id===cue.shotId):null
+    if(cue.shotId&&!shot)throw new Error('音频引用未知镜头')
+    const offset=Number(cue.offsetFrames??0),from=(shot?.startFrame||0)+offset
+    const duration=Number(cue.durationFrames??Math.min(total-from,shot?.durationFrames||total))
+    const gainDb=Number(cue.gainDb??defaults.gainDb),trimStart=Number(cue.trimStart??defaults.trimStart)
+    const fadeIn=Number(cue.fadeIn??defaults.fadeIn),fadeOut=Number(cue.fadeOut??defaults.fadeOut)
+    if(!Number.isInteger(offset)||offset<0||!Number.isInteger(duration)||duration<1||from+duration>total||from>=total||!Number.isFinite(gainDb)||gainDb< -60||gainDb>18||!Number.isFinite(trimStart)||trimStart<0||trimStart>600||![fadeIn,fadeOut].every(value=>Number.isFinite(value)&&value>=0&&value<=duration/fps))throw new Error('音频时间、增益或淡入淡出无效：'+(index+1))
+    return {id:'cue-'+(index+1),referenceId:ref.id,role:defaults.role,...(shot?{shotId:shot.id}:{}),offsetFrames:offset,from,durationFrames:duration,
+      trimStart,gainDb,fadeIn,fadeOut,loop:cue.loop===undefined?defaults.loop:cue.loop===true,action:String(cue.action||'').slice(0,600)}
+  })
+  return {version:1,cues,notes:Array.isArray(raw.notes)?raw.notes.map(String).slice(0,12):[]}
+}
+export function motionNodeData() {
+  return { drawaiMedia: '1', drawaiMotion: '1', motion: { version: MOTION_VERSION, ...motionSettings(), mode: 'scene', results: [] } }
+}
+
+// Incoming canvas arrows are the reference connections, including existing untagged edges.
+export function motionReferenceEdges(doc, nodeId) {
+  const seen = new Set()
+  return doc.edges.filter((edge) => {
+    if (edge.to !== nodeId || seen.has(edge.from)) return false
+    seen.add(edge.from)
+    return true
+  })
+}
+
+export function motionReferenceRole(doc, edge) {
+  if (isAudioNode(doc.nodes.find((item) => item.id === edge.from))) return 'audio'
+  if (isShotCardNode(doc.nodes.find((item) => item.id === edge.from))) return 'shotcard'
+  if (isMgStyleNode(doc.nodes.find((item) => item.id === edge.from))) return 'mgstyle'
+  if (edge.data?.motionReference?.role !== undefined) return edge.data.motionReference.role
+  const node = doc.nodes.find((item) => item.id === edge.from)
+  const style = node?.style || ''
+  if (/(?:^|;)text(?:=[^;]*)?(?:;|$)/.test(style)) return 'copy'
+  if (/(?:^|;)(?:group(?:=[^;]*)?|container=1)(?:;|$)/.test(style) || doc.nodes.some((item) => item.parent === edge.from)) return 'layout'
+  return 'material'
+}
+
+// 没连到任何视频节点的镜头卡。连线同时是「参考关系」和「排期依据」：
+// 断连的卡既不会进 assets，也不会进 timeline——多数时候是漏了 addEdge，不是有意为之。
+export function unlinkedShotCards(doc) {
+  const linked = new Set()
+  for (const edge of doc.edges || []) {
+    if (isMotionNode(doc.nodes.find((node) => node.id === edge.to))) linked.add(edge.from)
+  }
+  return (doc.nodes || [])
+    .filter((node) => isShotCardNode(node) && !linked.has(node.id))
+    .map((node) => ({ nodeId: node.id, cardId: node.data?.shotCardId, label: node.label || '' }))
+}
+
+export function bindMotionReference(doc, sourceId, targetId, role = 'material', edgeId) {
+  const source = doc.nodes.find((node) => node.id === sourceId), target = doc.nodes.find((node) => node.id === targetId)
+  if (!source || !isMotionNode(target) || sourceId === targetId) throw new Error('请选择有效的来源和目标视频节点')
+  assertMotionEditable(doc, targetId)
+  if (!MOTION_ROLES.includes(role)) throw new Error('未知参考用途')
+  const seen = new Set()
+  function reaches(id) {
+    if (id === sourceId) return true
+    if (seen.has(id)) return false
+    seen.add(id)
+    return doc.edges.some((edge) => (edge.data?.motionReference || isMotionNode(doc.nodes.find((item) => item.id === edge.to))) && edge.from === id && reaches(edge.to))
+  }
+  if (reaches(targetId)) throw new Error('生成参考不能形成循环')
+  const existing = doc.edges.find((edge) => edge.from === sourceId && edge.to === targetId && edge.data?.motionReference)
+  if (existing) { existing.data.motionReference.role = role; return existing }
+  if (!edgeId || doc.nodes.concat(doc.edges, doc.layers || []).some((item) => item.id === edgeId)) throw new Error('参考连线 ID 无效或冲突')
+  const edge = { id: edgeId, from: sourceId, to: targetId, label: '',
+    style: 'dashed=1;strokeColor=#7c6df2;endArrow=open;', data: { motionReference: { role } } }
+  if (target.layer || doc.layers?.[0]?.id) edge.layer = target.layer || doc.layers[0].id
+  doc.edges.push(edge)
+  if (Array.isArray(doc.drawOrder)) doc.drawOrder.unshift(edge.id)
+  return edge
+}
+
+export function motionInput(doc, nodeId) {
+  const node = doc.nodes.find((item) => item.id === nodeId)
+  if (!isMotionNode(node)) throw new Error('目标不是动效视频节点')
+  const settings = motionSettings(node.data.motion)
+  if (!settings.prompt) throw new Error('请先描述要生成的视频')
+  const visiting = new Set(), visited = new Set()
+  function visit(id) {
+    if (visiting.has(id)) throw new Error('生成参考不能形成循环')
+    if (visited.has(id)) return
+    visiting.add(id)
+    for (const edge of motionReferenceEdges(doc, id)) if (isMotionNode(doc.nodes.find((item) => item.id === id)) || edge.data?.motionReference) visit(edge.from)
+    visiting.delete(id); visited.add(id)
+  }
+  visit(nodeId)
+  const refs = motionReferenceEdges(doc, nodeId).map((edge) => {
+    const root = doc.nodes.find((item) => item.id === edge.from)
+    if (!root) throw new Error('参考素材已删除')
+    const role = motionReferenceRole(doc, edge)
+    if (!MOTION_ROLES.includes(role)) throw new Error('参考用途无效')
+    const ids = new Set([root.id])
+    for (let i = 0; i < doc.nodes.length; i++) for (const item of doc.nodes) if (ids.has(item.parent)) ids.add(item.id)
+    if (ids.has(nodeId)) throw new Error('参考分组不能包含目标视频')
+    const nodes = doc.nodes.filter((item) => ids.has(item.id)).map((item) => {
+      const data = { ...(item.data || {}) }; delete data.motion
+      return { id: item.id, label: item.label || '', style: item.style || '', x: item.x, y: item.y, w: item.w, h: item.h, parent: item.parent, data }
+    })
+    return { id: root.id, role, nodes, edges: doc.edges.filter((item) => ids.has(item.from) && ids.has(item.to) && !item.data?.motionReference) }
+  })
+  if (refs.length > 24 || refs.reduce((n, ref) => n + ref.nodes.length, 0) > 200) throw new Error('每次最多使用 24 组参考、200 个元素')
+  return { version: MOTION_VERSION, nodeId, settings, refs }
+}
+
+export function motionInputKey(input) {
+  const text = motionStable(input), words = [0x811c9dc5, 0x9e3779b9, 0x85ebca6b, 0xc2b2ae35]
+  for (let i = 0; i < text.length; i++) for (let n = 0; n < words.length; n++) words[n] = Math.imul(words[n] ^ text.charCodeAt(i), 16777619 + n * 2) >>> 0
+  return words.map((word) => word.toString(16).padStart(8, '0')).join('')
+}
+
+export function validateMotionPlan(raw, input) {
+  if (!raw || !Array.isArray(raw.shots) || !raw.shots.length || raw.shots.length > 24) throw new Error('分镜需要 1–24 个镜头')
+  const total = Math.round(input.settings.fps * input.settings.duration), ids = new Set(input.refs.map((ref) => ref.id))
+  const color = (value, fallback) => /^#[0-9a-f]{6}$/i.test(value || '') ? value : fallback
+  const shots = raw.shots.map((shot, index) => {
+    if (shot.recipeId !== 'scene') throw new Error('不支持的场景类型：' + shot.recipeId)
+    if (shot.recipeId === 'scene' && (typeof shot.sceneSource !== 'string' || shot.sceneSource.length < 20 || shot.sceneSource.length > 100000)) throw new Error('场景源码需要 20–100000 字符')
+    if (shot.sceneComponents !== undefined && (!Array.isArray(shot.sceneComponents) || shot.sceneComponents.length > 12)) throw new Error('每个镜头最多 12 个场景组件')
+    const componentIds = new Set()
+    const sceneComponents = (shot.sceneComponents || []).map((component) => {
+      if (!component || !/^[A-Z][A-Za-z0-9]{0,47}$/.test(component.id) || componentIds.has(component.id)) throw new Error('场景组件名称无效或重复')
+      if (typeof component.source !== 'string' || component.source.length < 20 || component.source.length > 100000) throw new Error('组件源码需要 20–100000 字符')
+      componentIds.add(component.id)
+      return { id: component.id, description: String(component.description || '').slice(0, 4000), source: component.source }
+    })
+    const start = Number(shot.startFrame), duration = Number(shot.durationFrames)
+    if (!Number.isInteger(start) || !Number.isInteger(duration) || start < 0 || duration < 1 || start + duration > total) throw new Error('镜头时间超出成片范围')
+    // A linked shot card is a motion constraint, never an image asset. Recover
+    // this unambiguous director mistake while still rejecting fabricated IDs.
+    const refs = (Array.isArray(shot.referenceIds) ? [...new Set(shot.referenceIds)] : [])
+      .filter((id) => !['shotcard','audio'].includes(input.refs.find((ref) => ref.id === id)?.role))
+    if (refs.some((id) => !ids.has(id) || !['material', 'layout'].includes(input.refs.find((ref) => ref.id === id).role))) throw new Error('镜头引用了不存在或仅供参考的素材')
+    return { id: 'shot-' + (index + 1), recipeId: shot.recipeId, recipeVersion: 1, startFrame: start, durationFrames: duration,
+      ...(shot.recipeId === 'scene' ? { sceneSource: shot.sceneSource, ...(sceneComponents.length ? { sceneComponents } : {}), cardId: String(shot.cardId || ''), demo: String(shot.demo || ''), motionCards: Array.isArray(shot.motionCards) ? motionClone(shot.motionCards) : [], fidelity: Array.isArray(shot.fidelity) ? motionClone(shot.fidelity) : [], description: String(shot.description || '').slice(0, 2000) } : {}),
+      referenceIds: refs, title: String(shot.title || '').slice(0, 300), subtitle: String(shot.subtitle || '').slice(0, 600),
+      background: color(shot.background, '#101827'), color: color(shot.color, '#ffffff'), accent: color(shot.accent, '#8b9dff') }
+  }).sort((a, b) => a.startFrame - b.startFrame)
+  let end = 0
+  for (const shot of shots) { if (shot.startFrame !== end) throw new Error('分镜必须连续且不能重叠'); end += shot.durationFrames }
+  if (end !== total) throw new Error('分镜总时长必须等于视频时长')
+  if (raw.production && (typeof raw.production !== 'object' || Array.isArray(raw.production) || JSON.stringify(raw.production).length > 100000)) throw new Error('制作记录无效或过大')
+  return { version: MOTION_VERSION, ...(raw.production ? { production: motionClone(raw.production) } : {}), width: input.settings.width, height: input.settings.height,
+    fps: input.settings.fps, durationFrames: total, shots,...(raw.audio?{audio:validateAudioTimeline(raw.audio,{fps:input.settings.fps,durationFrames:total,shots},input)}:{}) }
+}
+
+export function assertMotionEditable(doc, nodeId) {
+  const node = doc.nodes.find((item) => item.id === nodeId)
+  if (!node) throw new Error('目标视频已删除，成片保留在任务历史')
+  const seen = new Set()
+  for (let item = node; item; item = doc.nodes.find((n) => n.id === item.parent)) {
+    if (seen.has(item.id)) throw new Error('分组结构无效')
+    seen.add(item.id)
+    if (item.locked || /(?:^|;)locked=1(?:;|$)/.test(item.style || '') || (doc.layers || []).find((layer) => layer.id === (item.layer || doc.layers?.[0]?.id))?.locked) throw new Error('节点或图层已锁定，成片保留在任务历史')
+  }
+  return node
+}
+
+export function applyMotionResult(doc, job, result) {
+  const node = assertMotionEditable(doc, job.nodeId)
+  if (node.data.motion?.lastJobId === job.id) return node
+  if (node.data.motion?.requestId !== job.id || motionInputKey(motionInput(doc, node.id)) !== job.inputKey) throw new Error('描述或参考已变化，成片保留在任务历史')
+  const motion = node.data.motion
+  node.data = { ...node.data, ...result.data, motion: { ...motion, lastJobId: job.id,
+    composition: motionClone(result.composition), inputKey: job.inputKey,
+    results: [{ jobId: job.id, clip: result.data.mediaClip }, ...(Array.isArray(motion.results) ? motion.results : [])].slice(0, 12) } }
+  node.style = result.style
+  return node
+}

package/lib/motion-film-review.js

@@ -0,0 +1,71 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+import {mkdirSync,readFileSync,readdirSync,writeFileSync} from 'node:fs'
+import {join} from 'node:path'
+import {execFile} from 'node:child_process'
+import {promisify} from 'node:util'
+import {ensureFfmpeg} from './ffmpeg-manager.js'
+import {agentHash,agentAtomicJson} from './motion-agent-files.js'
+import {streamAgentTurn,agentMessage} from './motion-agent-protocol.js'
+const exec=promisify(execFile)
+const run=async(args,signal)=>{const binary=await ensureFfmpeg({signal});return exec(binary,['-hide_banner','-nostdin',...args],{windowsHide:true,signal,timeout:180000,maxBuffer:8*1024*1024})}
+
+// Decode the actual delivered file, including its final mixed audio. Visual
+// semantics use ordered contact sheets; listening is a separate human verdict.
+export async function inspectMotionFilm({packDir,composition,signal,reviewSequence,expectedAudio=false,previousMotion}){
+  const source=join(packDir,'source.mp4'),sha256=agentHash(readFileSync(source)),directory=join(packDir,'film-review',sha256.slice(0,16))
+  mkdirSync(directory,{recursive:true})
+  const decoded=await run(['-xerror','-i',source,'-map','0:v:0','-vf','blackdetect=d=0.12:pix_th=0.02,freezedetect=n=-50dB:d=0.35','-an','-progress','pipe:1','-f','null','-'],signal)
+  const log=decoded.stderr,frames=Number([...decoded.stdout.matchAll(/^frame=(\d+)/gm)].at(-1)?.[1])
+  const durationMatch=/Duration:\s*(\d+):(\d+):([\d.]+)/.exec(log)
+  if(!durationMatch||!frames)throw Error('成片无法完整解码')
+  const duration=Number(durationMatch[1])*3600+Number(durationMatch[2])*60+Number(durationMatch[3]),expected=composition.durationFrames/composition.fps
+  if(Math.abs(duration-expected)>Math.max(.12,2/composition.fps)||Math.abs(frames-composition.durationFrames)>1)throw Error('成片时长或帧数与工程不一致')
+  const warnings=[]
+  for(const match of log.matchAll(/black_start:([\d.]+) black_end:([\d.]+) black_duration:([\d.]+)/g))warnings.push({kind:'black',from:Number(match[1]),to:Number(match[2]),note:'可能为设计留黑，需结合画面判断'})
+  for(const match of log.matchAll(/freeze_start: ([\d.]+)/g))warnings.push({kind:'freeze',from:Number(match[1]),note:'可能为有意停留，需结合分镜判断'})
+  let audio={hasAudio:/Stream .*Audio:/.test(log),listening:'not-performed'}
+  if(expectedAudio&&!audio.hasAudio)throw Error('声音时间表非空，但最终视频缺少音轨')
+  if(audio.hasAudio){
+    const measured=await run(['-i',source,'-map','0:a:0','-vn','-af','ebur128=peak=true,silencedetect=noise=-50dB:d=0.4','-f','null','-'],signal)
+    const summary=measured.stderr.slice(measured.stderr.lastIndexOf('Summary:'))
+    const value=(pattern)=>{const text=pattern.exec(summary)?.[1];return text&&Number.isFinite(Number(text))?Number(text):null}
+    audio={...audio,integratedLufs:value(/I:\s*(-?[\d.]+) LUFS/),truePeakDb:value(/Peak:\s*(-?[\d.]+) dBFS/),
+      silence:[...measured.stderr.matchAll(/silence_start: ([\d.]+)/g)].map(m=>Number(m[1]))}
+    if(audio.truePeakDb!==null&&audio.truePeakDb>-.1)warnings.push({kind:'audio-peak',note:'真峰值接近或超过0 dBFS，请试听失真'})
+    if(audio.integratedLufs!==null&&audio.integratedLufs<-50)warnings.push({kind:'audio-silence',note:'整片音轨近乎静音，请核对声音需求'})
+    writeFileSync(join(directory,'audio-analysis.log'),measured.stderr)
+  }
+  const samplingFps=6,panelSeconds=12/samplingFps
+  await run(['-y','-i',source,'-an','-vf',`fps=${samplingFps},scale=320:-2,tile=4x3:padding=2:margin=2`,'-fps_mode','vfr',join(directory,'sequence-%03d.png')],signal)
+  const sheets=readdirSync(directory).filter(name=>/^sequence-\d+\.png$/.test(name)).sort().map((filename,index)=>({filename,from:index*panelSeconds,to:Math.min(duration,(index+1)*panelSeconds),
+    times:Array.from({length:Math.min(12,Math.ceil((duration-index*panelSeconds)*samplingFps))},(_,j)=>(index*12+j)/samplingFps)}))
+  const sequences=[]
+  for(const sheet of sheets){
+    signal?.throwIfAborted()
+    if(previousMotion||!reviewSequence){sequences.push({...sheet,status:'unavailable',reason:'未配置支持图片的时序审查模型'});continue}
+    try{
+      const result=await reviewSequence({file:join(directory,sheet.filename),sheet,composition,warnings:warnings.filter(w=>w.from===undefined||w.from>=sheet.from&&w.from<=sheet.to)})
+      if(!['passed','changes-requested','unavailable'].includes(result?.status))throw Error('时序审查响应状态无效')
+      sequences.push({...sheet,...result})
+    }catch(error){if(signal?.aborted)throw error;sequences.push({...sheet,status:'unavailable',reason:error.message})}
+  }
+  const motion=previousMotion||{status:sequences.some(s=>s.status==='changes-requested')?'changes-requested':sequences.some(s=>s.status!=='passed')?'unavailable':'passed',
+    coverage:'whole-film-ordered-samples',samplingFps,note:'覆盖全片的有序采样；不等于每帧运动或完整视频感知验收',sequences}
+  const result={version:1,sha256,duration,decodedFrames:frames,decode:'passed',motion,audio,warnings,
+    manual:{status:'pending',motion:'pending',sound:audio.hasAudio?'pending':'not-applicable'},directory,createdAt:new Date().toISOString()}
+  writeFileSync(join(directory,'decode.log'),log)
+  agentAtomicJson(join(directory,'report.json'),result)
+  return result
+}
+
+export function motionSequenceReviewer({llm,config,attachments,sessionId,signal}){
+  return async({file,sheet,composition,warnings})=>{
+    const attachment=await attachments.saveImage({data:readFileSync(file),mediaType:'image/png',name:sheet.filename})
+    const assistant=await streamAgentTurn({llm,config,sessionId,signal},[agentMessage('user',[{type:'text',text:JSON.stringify({sheet,shots:composition.shots.map(({sceneSource,sceneComponents,...shot})=>shot),warnings})},{type:'image',attachment}])],[],
+      '你是独立的视频时序审查员。图片每行从左到右、从上到下按times排列，每秒6帧。检查主体跳变、意外闪烁、跨镜头衔接、文字突然消失和停留节奏。区分有意切镜/静止和缺陷。只输出JSON {"status":"passed或changes-requested","issues":[{"time":秒,"reason":"具体可见问题"}]}。没有音频输入，不判断听感；不声称看到了采样之间的运动。')
+    const text=assistant.content.filter(b=>b.type==='text').map(b=>b.text).join('').trim().replace(/^```(?:json)?\s*/,'').replace(/\s*```$/,'')
+    const value=JSON.parse(text)
+    if(!['passed','changes-requested'].includes(value.status)||!Array.isArray(value.issues))throw Error('时序审查响应无效')
+    return {status:value.status,issues:value.issues.slice(0,12)}
+  }
+}

package/lib/motion-library.js

@@ -0,0 +1,210 @@
+/* 由 tools/build.mjs 生成 —— 请勿直接编辑；改 src/ 下的源文件。 */
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { posix } from 'node:path'
+import { parse } from '@babel/parser'
+import { resolveShotStyle, shotCardSelections } from './shotcard-core.js'
+import { mgStyleSelection, resolveMgStyle } from './mgstyle-core.js'
+export const shotCardCatalog = JSON.parse(readFileSync(new URL('./motion/shotcraft/catalog.json', import.meta.url), 'utf8'))
+const base = new URL('./motion/shotcraft/upstream/', import.meta.url)
+export const shotcraftLibrary = JSON.parse(readFileSync(new URL('manifest.json', base), 'utf8'))
+export function shotcraftFile(path) {
+  if (!Object.hasOwn(shotcraftLibrary.files, path)) throw new Error('未知 Shotcraft 源文件：' + path)
+  return readFileSync(new URL(path, base), 'utf8')
+}
+export function shotcraftCatalog() {
+  return shotCardCatalog.cards.map((card) => ({ ...card, demos: [...new Set(card.styles.map((style) => style.demo))] }))
+}
+export function shotcraftContext(shots) {
+  const chosen = new Set(), documents = []
+  function include(path) {
+    if (chosen.has(path)) return
+    chosen.add(path)
+    const source = shotcraftFile(path)
+    documents.push({ path, source })
+    if (!/\.(tsx?|jsx?)$/.test(path)) return
+    const ast = parse(source, { sourceType: 'module', plugins: ['typescript', 'jsx'] })
+    for (const node of ast.program.body) {
+      if (!['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration'].includes(node.type) || !node.source?.value.startsWith('.')) continue
+      const stem = posix.normalize(posix.join(posix.dirname(path), node.source.value))
+      const dependency = [stem, stem + '.tsx', stem + '.ts', stem + '.jsx', stem + '.js', stem + '/index.tsx', stem + '/index.ts'].find((candidate) => Object.hasOwn(shotcraftLibrary.files, candidate))
+      if (dependency) include(dependency)
+    }
+  }
+  for (const shot of shots) {
+    if (shot.motionCards?.length) {
+      for (const selection of shot.motionCards) {
+        const resolved = resolveShotStyle(shotCardCatalog, selection.cardId, selection.styleKey)
+        include(shotCardCatalog.cards.find((card) => card.id === resolved.cardId).source); include(resolved.demo)
+      }
+      continue
+    }
+    if (!shot.cardId) continue
+    const card = shotcraftLibrary.cards.find((card) => card.id === shot.cardId)
+    if (!card) throw new Error('未知镜头卡：' + shot.cardId)
+    if (shot.demo && !card.demos.includes(shot.demo)) throw new Error('镜头卡与参考源码不匹配')
+    for (const path of [card.source, ...(shot.demo ? [shot.demo] : card.demos.slice(0, 1))]) {
+      include(path)
+    }
+  }
+  const context = JSON.stringify(documents)
+  if (context.length > 300000) throw new Error('参考源码过多，请减少镜头或参考变体')
+  return documents
+}
+export function shotcraftModuleMap() {
+  return Object.fromEntries(Object.keys(shotcraftLibrary.files).filter((path) => /^(assets\/lib|demos)\/.+\.(tsx?|jsx?)$/.test(path))
+    .map((path) => ['@shotcraft/' + path.replace(/^assets\/lib\//, 'lib/').replace(/\.(tsx?|jsx?)$/, ''), new URL(path, base)]))
+}
+
+export function motionCardContract(selection) {
+  const resolved = resolveShotStyle(shotCardCatalog, selection.cardId, selection.styleKey)
+  const card = shotCardCatalog.cards.find((item) => item.id === resolved.cardId)
+  const recipe = shotcraftFile(card.source)
+  const protectedParameters = recipe.split(/(?=^## )/m).filter((section) => /^## (参数表|已知坑|动效核心)/.test(section))
+  return { ...resolved, protectedParameters, parametersSha256: createHash('sha256').update(protectedParameters.join('\n')).digest('hex'), cardSource: card.source, demoSha256: shotcraftLibrary.files[resolved.demo],
+    recipe, source: shotcraftFile(resolved.demo),
+    preservation: '参考准确 demo 的动作顺序、缓动、运镜、遮罩时机、错峰与停留，按需求自由适配源码与内容。30fps 时值按实际 fps 换算；改完用 motion_preview 看帧确认效果。' }
+}
+export function enforceMotionCards(composition, input) {
+  if (shotCardCatalog.commit !== shotcraftLibrary.commit) throw new Error('镜头样式索引与源码库版本不匹配')
+  const required = shotCardSelections(shotCardCatalog, input)
+  const used = new Set()
+  for (const shot of composition.shots) {
+    let selections = shot.motionCards || []
+    if (!selections.length && shot.cardId) {
+      const card = shotCardCatalog.cards.find((item) => item.id === shot.cardId)
+      if (!card) throw new Error('未知镜头卡：' + shot.cardId)
+      const candidates = card.styles.filter((style) => !shot.demo || style.demo === shot.demo)
+      if (candidates.length !== 1) throw new Error('镜头卡有多个样式，请指定 motionCards 的 styleKey：' + shot.cardId)
+      selections = [{ cardId: card.id, styleKey: candidates[0].key }]
+    }
+    if (selections.length > 8) throw new Error('单镜最多参考 8 个镜头样式')
+    const keys = new Set()
+    shot.motionCards = selections.map((item) => {
+      const resolved = resolveShotStyle(shotCardCatalog, item.cardId, item.styleKey)
+      if (item.demo && item.demo !== resolved.demo) throw new Error('样式与 demo 不匹配')
+      const key = resolved.cardId + ':' + resolved.styleKey
+      if (keys.has(key)) throw new Error('镜头内重复引用样式：' + key)
+      keys.add(key); used.add(key)
+      return resolved
+    })
+    if (shot.motionCards.length) { shot.cardId = shot.motionCards[0].cardId; shot.demo = shot.motionCards[0].demo }
+  }
+  for (const item of required) if (!used.has(item.cardId + ':' + item.styleKey)) throw new Error('分镜遗漏指定的镜头参考：' + item.label)
+  if (used.size) composition.production = { ...composition.production, motionContracts: [...new Map(composition.shots.flatMap((shot) => shot.motionCards)
+    .map((item) => [item.cardId + ':' + item.styleKey, motionCardContract(item)])).values()].map(({ source, recipe, protectedParameters, ...item }) => item) }
+  return composition
+}
+
+// ── mg-styles：14 种整片风格（不是单镜卡；上游 15 支里的 04-3d-render 已移除） ──
+// 上游是「HTML 页 + renderAt(t) + puppeteer 截帧」，这里是「提示词 + 移植 brief + 成片源码」，
+// 供 agent 在 Remotion 里照着写场景。源码只作阅读参考，不进 webpack（和镜头卡不同）。
+
+const mgRoot = new URL('./motion/mgstyles/', import.meta.url)
+const mgUpstream = new URL('upstream/', mgRoot)
+const mgReadCache = new Map()
+
+export const mgStyleCatalog = JSON.parse(readFileSync(new URL('catalog.json', mgRoot), 'utf8'))
+export const mgStyleLibrary = JSON.parse(readFileSync(new URL('manifest.json', mgUpstream), 'utf8'))
+
+function readMg(relative, base = mgUpstream) {
+  if (mgReadCache.has(relative)) return mgReadCache.get(relative)
+  const source = readFileSync(new URL(relative, base), 'utf8')
+  mgReadCache.set(relative, source)
+  return source
+}
+
+export function mgStyleFile(path) {
+  if (!Object.hasOwn(mgStyleLibrary.files, path)) throw new Error('未知 mg 风格源文件：' + path)
+  return readMg(path)
+}
+
+export function mgStyleFileSize(path) {
+  if (!Object.hasOwn(mgStyleLibrary.files, path)) throw new Error('未知 mg 风格源文件：' + path)
+  return statSync(new URL(path, mgUpstream)).size
+}
+
+export function mgStyleBrief(slug) {
+  const style = resolveMgStyle(mgStyleCatalog, slug)
+  let source
+  try { source = readMg(style.brief, mgRoot) } catch {
+    throw new Error('风格 ' + slug + ' 还没有移植 brief（' + style.brief + '），先读提示词与上游源码：' + style.prompt)
+  }
+  return { slug: style.slug, path: style.brief, source, sha256: createHash('sha256').update(source).digest('hex') }
+}
+
+export function mgStylePrompt(slug) {
+  const style = resolveMgStyle(mgStyleCatalog, slug)
+  const source = mgStyleFile(style.prompt)
+  return { slug: style.slug, path: style.prompt, source, sha256: createHash('sha256').update(source).digest('hex') }
+}
+
+/**
+ * 上游成片源码，按「最可能被抄的优先」排序：film.js / main.js / scene.js / index.html 先来，
+ * 其余 js 其次，json 最后。单文件截断 60k 字符，总量截断 200k —— brief 已经提炼过，
+ * 源码是补充细节用的，不该把上下文吃光。
+ */
+export function mgStyleSources(slug, { limit = 200000 } = {}) {
+  const style = resolveMgStyle(mgStyleCatalog, slug)
+  const rank = (path) => {
+    const name = posix.basename(path)
+    if (/^(film|main|scene|index)\.(m?js|html)$/.test(name)) return 0
+    if (/\.(m?js|html)$/.test(name)) return 1
+    if (/\.css$/.test(name)) return 2
+    return 3
+  }
+  const paths = Object.keys(mgStyleLibrary.files).filter((path) => path.startsWith('demos/' + slug + '/')).sort((a, b) => rank(a) - rank(b) || a.localeCompare(b))
+  const documents = []
+  let total = 0
+  for (const path of paths) {
+    if (total >= limit) break
+    const source = readMg(path)
+    const slice = source.length > 60000 ? source.slice(0, 60000) + '\n/* …截断：' + (source.length - 60000) + ' 字符未显示，需要时用 mg_style action:"read" files:["' + path + '"]… */' : source
+    documents.push({ path, chars: source.length, source: slice })
+    total += slice.length
+  }
+  return documents
+}
+
+/** 一个风格的完整「施工包」：判据 + 色板 + 字体 + 节奏 + 提示词 + brief。 */
+export function mgStyleKit(selection) {
+  const style = resolveMgStyle(mgStyleCatalog, selection.slug)
+  const brief = mgStyleBrief(selection.slug)
+  const prompt = mgStylePrompt(selection.slug)
+  return {
+    ...style,
+    brief: brief.source,
+    briefSha256: brief.sha256,
+    promptSource: prompt.source,
+    promptSha256: prompt.sha256,
+    demos: style.demos,
+    preservation: 'brief 是这个风格的移植说明书；引擎以 engines 为准 —— three.js / WebGL2 必须真跑同一套引擎，不许用 CSS 3D、div 层叠或 Canvas2D 渐变简化替代（motion_render 启动前会扫工程源码拦截）。判据（signature）比形容词重要：做不出判据就不算这个风格。',
+  }
+}
+
+/** 把选中的风格织进 composition：固定 palette/字体/节奏，并把 brief 摘要留在 production 里备查。 */
+export function enforceMgStyle(composition, input) {
+  if (mgStyleCatalog.commit !== mgStyleLibrary.commit) throw new Error('mg 风格索引与源码库版本不匹配')
+  const selection = mgStyleSelection(mgStyleCatalog, input)
+  if (!selection) return composition
+  const kit = mgStyleKit(selection)
+  composition.production = {
+    ...composition.production,
+    mgStyle: {
+      slug: kit.slug,
+      name: kit.name,
+      commit: kit.commit,
+      nodeId: selection.nodeId,
+      palette: kit.palette,
+      fonts: kit.fonts,
+      rhythm: kit.rhythm,
+      signature: kit.signature,
+      brief: kit.brief,
+      briefSha256: kit.briefSha256,
+      promptSha256: kit.promptSha256,
+      demos: kit.demos,
+      preservation: kit.preservation,
+    },
+  }
+  return composition
+}