From fb31114feeaf3ae6de7c285b64fcd071c197ba24 Mon Sep 17 00:00:00 2001
From: xyh202131 <246811510+xyh202131@users.noreply.github.com>
Date: Tue, 4 Aug 2026 10:53:24 +0800
Subject: [PATCH 1/2] feat(export-package): add asset packaging plan and export
 panel

---
 .../export-package/asset-export.test.ts       | 181 +++++++++
 .../features/export-package/asset-export.ts   | 366 ++++++++++++++++++
 .../export-package/export-panel.test.tsx      | 120 ++++++
 .../features/export-package/export-panel.tsx  | 122 ++++++
 frontend/src/features/export-package/index.ts |  10 +
 frontend/src/features/export-package/model.ts |  32 ++
 6 files changed, 831 insertions(+)
 create mode 100644 frontend/src/features/export-package/asset-export.test.ts
 create mode 100644 frontend/src/features/export-package/asset-export.ts
 create mode 100644 frontend/src/features/export-package/export-panel.test.tsx
 create mode 100644 frontend/src/features/export-package/export-panel.tsx
 create mode 100644 frontend/src/features/export-package/index.ts
 create mode 100644 frontend/src/features/export-package/model.ts

diff --git a/frontend/src/features/export-package/asset-export.test.ts b/frontend/src/features/export-package/asset-export.test.ts
new file mode 100644
index 0000000..d9cfeb8
--- /dev/null
+++ b/frontend/src/features/export-package/asset-export.test.ts
@@ -0,0 +1,181 @@
+/** @vitest-environment jsdom */
+import { describe, expect, it, vi } from 'vitest'
+
+import type {
+  ExportAction as PreviewAction,
+  ExportFrame as PreviewFrame,
+  ExportPackageModel as PlaytestPreviewModel,
+} from './model'
+import { createAssetExportPlan, exportGameAssets, type AssetExportRuntime } from './asset-export'
+
+function frame(index: number): PreviewFrame {
+  return {
+    imageUrl: `/frames/walk-${index}.png`,
+    durationMs: 100 + index,
+    rootMotion: { dx: index, dy: 0 },
+    keyFrame: index === 0,
+  }
+}
+
+function action(frameCount = 9): PreviewAction {
+  return {
+    id: 'walk-abcdef12',
+    name: 'Walk / Forward',
+    type: 'walk',
+    fps: 10,
+    sequences: [
+      {
+        direction: 'south',
+        frames: Array.from({ length: frameCount }, (_, index) => frame(index)),
+      },
+    ],
+  }
+}
+
+const model: PlaytestPreviewModel = {
+  characterId: 'character-1',
+  characterName: 'Aster',
+  outfitId: 'outfit-1',
+  outfitName: 'Explorer',
+  characterTemplateUrl: null,
+  baseFrameCount: 0,
+  actions: [action(), action(0)],
+}
+
+async function readStoredZip(blob: Blob): Promise<Map<string, Uint8Array>> {
+  const bytes = new Uint8Array(await blob.arrayBuffer())
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  const decoder = new TextDecoder()
+  const entries = new Map<string, Uint8Array>()
+  let offset = 0
+
+  while (offset + 4 <= bytes.length && view.getUint32(offset, true) === 0x04034b50) {
+    const compressedSize = view.getUint32(offset + 18, true)
+    const nameLength = view.getUint16(offset + 26, true)
+    const extraLength = view.getUint16(offset + 28, true)
+    const nameStart = offset + 30
+    const dataStart = nameStart + nameLength + extraLength
+    const name = decoder.decode(bytes.slice(nameStart, nameStart + nameLength))
+    entries.set(name, bytes.slice(dataStart, dataStart + compressedSize))
+    offset = dataStart + compressedSize
+  }
+  return entries
+}
+
+function runtime(failingUrl: string | null = null): AssetExportRuntime {
+  return {
+    fetchFrame: vi.fn(async (url) => {
+      if (url === failingUrl) throw new Error('missing')
+      return new Blob([`original:${url}`], { type: 'image/png' })
+    }),
+    decodeFrame: vi.fn(async (blob) => ({
+      source: {} as CanvasImageSource,
+      width: blob.size % 2 === 0 ? 32 : 24,
+      height: 40,
+      close: vi.fn(),
+    })),
+    createCanvas: vi.fn((width, height) => {
+      const canvas = document.createElement('canvas')
+      canvas.width = width
+      canvas.height = height
+      Object.defineProperty(canvas, 'getContext', {
+        value: () => ({ clearRect: vi.fn(), drawImage: vi.fn() }),
+      })
+      Object.defineProperty(canvas, 'toBlob', {
+        value: (callback: BlobCallback) => callback(new Blob(['sheet'], { type: 'image/png' })),
+      })
+      return canvas
+    }),
+  }
+}
+
+describe('asset export', () => {
+  it('plans non-empty sequences and wraps after eight columns', () => {
+    const plan = createAssetExportPlan(model)
+
+    expect(plan).toHaveLength(1)
+    expect(plan[0]).toMatchObject({
+      columns: 8,
+      rows: 2,
+      folder: 'actions/Walk-Forward-abcdef12/south',
+    })
+    expect(plan[0]?.frames.map((item) => item.filename)).toEqual([
+      '000.png',
+      '001.png',
+      '002.png',
+      '003.png',
+      '004.png',
+      '005.png',
+      '006.png',
+      '007.png',
+      '008.png',
+    ])
+  })
+
+  it('creates a zip containing only original frames, a sprite sheet and animation json', async () => {
+    const phases: string[] = []
+    const result = await exportGameAssets(model, runtime(), (phase) => phases.push(phase))
+    const entries = await readStoredZip(result.blob)
+    const names = [...entries.keys()]
+
+    expect(result).toMatchObject({ filename: 'windup-Aster-Explorer.zip', incomplete: false })
+    expect(phases).toEqual(['collecting', 'rendering', 'packing'])
+    expect(names).toContain('actions/Walk-Forward-abcdef12/south/sprite-sheet.png')
+    expect(names).toContain('actions/Walk-Forward-abcdef12/south/animation.json')
+    expect(names.filter((name) => name.includes('/frames/'))).toHaveLength(9)
+    expect(names.some((name) => /manifest|audit/i.test(name))).toBe(false)
+
+    const jsonBytes = entries.get('actions/Walk-Forward-abcdef12/south/animation.json')
+    const animation = JSON.parse(new TextDecoder().decode(jsonBytes))
+    expect(animation.spriteSheet).toMatchObject({ columns: 8, rows: 2 })
+    expect(animation.frames[0]).toMatchObject({
+      index: 0,
+      source: 'frames/000.png',
+      available: true,
+      durationMs: 100,
+      keyFrame: true,
+    })
+  })
+
+  it('keeps a transparent cell and marks a failed original frame unavailable', async () => {
+    const result = await exportGameAssets(model, runtime('/frames/walk-4.png'))
+    const entries = await readStoredZip(result.blob)
+    const animation = JSON.parse(
+      new TextDecoder().decode(entries.get('actions/Walk-Forward-abcdef12/south/animation.json')),
+    )
+
+    expect(result.incomplete).toBe(true)
+    expect(entries.has('actions/Walk-Forward-abcdef12/south/frames/004.png')).toBe(false)
+    expect(animation.frames[4]).toMatchObject({
+      index: 4,
+      source: 'frames/004.png',
+      available: false,
+    })
+  })
+
+  it('releases decoded images when sprite-sheet rendering fails', async () => {
+    const baseRuntime = runtime()
+    const closes: Array<ReturnType<typeof vi.fn>> = []
+    const failingRuntime: AssetExportRuntime = {
+      ...baseRuntime,
+      decodeFrame: vi.fn(async () => {
+        const close = vi.fn()
+        closes.push(close)
+        return { source: {} as CanvasImageSource, width: 24, height: 40, close }
+      }),
+      createCanvas: vi.fn((width, height) => {
+        const canvas = document.createElement('canvas')
+        canvas.width = width
+        canvas.height = height
+        Object.defineProperty(canvas, 'getContext', { value: () => null })
+        return canvas
+      }),
+    }
+
+    await expect(exportGameAssets(model, failingRuntime)).rejects.toThrow(
+      '浏览器无法创建 Sprite Sheet',
+    )
+    expect(closes).toHaveLength(9)
+    expect(closes.every((close) => close.mock.calls.length === 1)).toBe(true)
+  })
+})
diff --git a/frontend/src/features/export-package/asset-export.ts b/frontend/src/features/export-package/asset-export.ts
new file mode 100644
index 0000000..4310c6c
--- /dev/null
+++ b/frontend/src/features/export-package/asset-export.ts
@@ -0,0 +1,366 @@
+import type { ExportAction, ExportFrame, ExportPackageModel, ExportSequence } from './model'
+
+export type AssetExportPhase = 'collecting' | 'rendering' | 'packing'
+
+export interface AssetExportResult {
+  blob: Blob
+  filename: string
+  incomplete: boolean
+}
+
+export interface DecodedFrame {
+  source: CanvasImageSource
+  width: number
+  height: number
+  close(): void
+}
+
+export interface AssetExportRuntime {
+  fetchFrame(url: string): Promise<Blob>
+  decodeFrame(blob: Blob): Promise<DecodedFrame>
+  createCanvas(width: number, height: number): HTMLCanvasElement
+}
+
+export interface PlannedFrame {
+  frame: ExportFrame
+  index: number
+  filename: string
+}
+
+export interface PlannedSequence {
+  action: ExportAction
+  sequence: ExportSequence
+  folder: string
+  columns: number
+  rows: number
+  frames: readonly PlannedFrame[]
+}
+
+interface LoadedFrame extends PlannedFrame {
+  blob: Blob | null
+  decoded: DecodedFrame | null
+  sourceFilename: string
+}
+
+interface ZipEntry {
+  name: string
+  data: Uint8Array
+}
+
+function safeSegment(value: string, fallback: string): string {
+  const normalized = value
+    .normalize('NFKC')
+    .replace(/[^\p{L}\p{N}]+/gu, '-')
+    .replace(/^-+|-+$/g, '')
+  return normalized || fallback
+}
+
+function idSuffix(id: string): string {
+  return safeSegment(id, 'id').slice(-8) || 'id'
+}
+
+function extensionFromUrl(imageUrl: string): string {
+  const match = imageUrl.split(/[?#]/, 1)[0]?.match(/\.([a-zA-Z0-9]{2,5})$/)
+  return match?.[1]?.toLowerCase() ?? 'png'
+}
+
+function extensionForBlob(blob: Blob, imageUrl: string): string {
+  const byMime: Readonly<Record<string, string>> = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/webp': 'webp',
+    'image/gif': 'gif',
+    'image/avif': 'avif',
+  }
+  return byMime[blob.type.toLowerCase()] ?? extensionFromUrl(imageUrl)
+}
+
+export function createAssetExportPlan(model: ExportPackageModel): readonly PlannedSequence[] {
+  return model.actions.flatMap((action) => {
+    const actionFolder = `${safeSegment(action.name, 'action')}-${idSuffix(action.id)}`
+    return action.sequences.flatMap((sequence) => {
+      if (sequence.frames.length === 0) return []
+      const columns = Math.min(8, sequence.frames.length)
+      return [
+        {
+          action,
+          sequence,
+          folder: `actions/${actionFolder}/${safeSegment(sequence.direction, 'default')}`,
+          columns,
+          rows: Math.ceil(sequence.frames.length / columns),
+          frames: sequence.frames.map((currentFrame, index) => ({
+            frame: currentFrame,
+            index,
+            filename: `${String(index).padStart(3, '0')}.${extensionFromUrl(currentFrame.imageUrl)}`,
+          })),
+        },
+      ]
+    })
+  })
+}
+
+const defaultRuntime: AssetExportRuntime = {
+  async fetchFrame(url) {
+    const response = await fetch(url)
+    if (!response.ok) throw new Error(`图片读取失败：${response.status}`)
+    return response.blob()
+  },
+  async decodeFrame(blob) {
+    const bitmap = await createImageBitmap(blob)
+    return {
+      source: bitmap,
+      width: bitmap.width,
+      height: bitmap.height,
+      close: () => bitmap.close(),
+    }
+  },
+  createCanvas(width, height) {
+    const canvas = document.createElement('canvas')
+    canvas.width = width
+    canvas.height = height
+    return canvas
+  },
+}
+
+function canvasPng(canvas: HTMLCanvasElement): Promise<Blob> {
+  return new Promise((resolve, reject) => {
+    canvas.toBlob((blob) => {
+      if (blob === null) reject(new Error('Sprite Sheet 编码失败'))
+      else resolve(blob)
+    }, 'image/png')
+  })
+}
+
+async function bytes(data: Blob | string): Promise<Uint8Array> {
+  if (typeof data === 'string') return new TextEncoder().encode(data)
+  return new Uint8Array(await data.arrayBuffer())
+}
+
+function uint32Table(): Uint32Array {
+  const table = new Uint32Array(256)
+  for (let value = 0; value < 256; value += 1) {
+    let current = value
+    for (let bit = 0; bit < 8; bit += 1) {
+      current = (current & 1) !== 0 ? 0xedb88320 ^ (current >>> 1) : current >>> 1
+    }
+    table[value] = current >>> 0
+  }
+  return table
+}
+
+const CRC32_TABLE = uint32Table()
+
+function crc32(data: Uint8Array): number {
+  let crc = 0xffffffff
+  for (const value of data) crc = (crc >>> 8) ^ (CRC32_TABLE[(crc ^ value) & 0xff] ?? 0)
+  return (crc ^ 0xffffffff) >>> 0
+}
+
+function dosDateTime(date: Date): { date: number; time: number } {
+  const year = Math.max(1980, date.getFullYear())
+  return {
+    date: ((year - 1980) << 9) | ((date.getMonth() + 1) << 5) | date.getDate(),
+    time: (date.getHours() << 11) | (date.getMinutes() << 5) | Math.floor(date.getSeconds() / 2),
+  }
+}
+
+function concat(chunks: readonly Uint8Array[]): Uint8Array {
+  const output = new Uint8Array(chunks.reduce((total, chunk) => total + chunk.length, 0))
+  let offset = 0
+  for (const chunk of chunks) {
+    output.set(chunk, offset)
+    offset += chunk.length
+  }
+  return output
+}
+
+function storedZip(entries: readonly ZipEntry[]): Blob {
+  const localChunks: Uint8Array[] = []
+  const centralChunks: Uint8Array[] = []
+  const encoder = new TextEncoder()
+  const timestamp = dosDateTime(new Date())
+  let localOffset = 0
+
+  for (const entry of entries) {
+    const name = encoder.encode(entry.name)
+    const checksum = crc32(entry.data)
+    const local = new Uint8Array(30 + name.length)
+    const localView = new DataView(local.buffer)
+    localView.setUint32(0, 0x04034b50, true)
+    localView.setUint16(4, 20, true)
+    localView.setUint16(6, 0x0800, true)
+    localView.setUint16(8, 0, true)
+    localView.setUint16(10, timestamp.time, true)
+    localView.setUint16(12, timestamp.date, true)
+    localView.setUint32(14, checksum, true)
+    localView.setUint32(18, entry.data.length, true)
+    localView.setUint32(22, entry.data.length, true)
+    localView.setUint16(26, name.length, true)
+    local.set(name, 30)
+    localChunks.push(local, entry.data)
+
+    const central = new Uint8Array(46 + name.length)
+    const centralView = new DataView(central.buffer)
+    centralView.setUint32(0, 0x02014b50, true)
+    centralView.setUint16(4, 20, true)
+    centralView.setUint16(6, 20, true)
+    centralView.setUint16(8, 0x0800, true)
+    centralView.setUint16(10, 0, true)
+    centralView.setUint16(12, timestamp.time, true)
+    centralView.setUint16(14, timestamp.date, true)
+    centralView.setUint32(16, checksum, true)
+    centralView.setUint32(20, entry.data.length, true)
+    centralView.setUint32(24, entry.data.length, true)
+    centralView.setUint16(28, name.length, true)
+    centralView.setUint32(42, localOffset, true)
+    central.set(name, 46)
+    centralChunks.push(central)
+    localOffset += local.length + entry.data.length
+  }
+
+  const centralDirectory = concat(centralChunks)
+  const end = new Uint8Array(22)
+  const endView = new DataView(end.buffer)
+  endView.setUint32(0, 0x06054b50, true)
+  endView.setUint16(8, entries.length, true)
+  endView.setUint16(10, entries.length, true)
+  endView.setUint32(12, centralDirectory.length, true)
+  endView.setUint32(16, localOffset, true)
+  const output = concat([...localChunks, centralDirectory, end])
+  const arrayBuffer = new ArrayBuffer(output.length)
+  new Uint8Array(arrayBuffer).set(output)
+  return new Blob([arrayBuffer], { type: 'application/zip' })
+}
+
+export async function exportGameAssets(
+  model: ExportPackageModel,
+  runtime: AssetExportRuntime = defaultRuntime,
+  onPhase?: (phase: AssetExportPhase) => void,
+): Promise<AssetExportResult> {
+  const plan = createAssetExportPlan(model)
+  onPhase?.('collecting')
+  const blobCache = new Map<string, Promise<Blob>>()
+  let incomplete = false
+
+  const loaded = await Promise.all(
+    plan.map(async (item) => ({
+      item,
+      frames: await Promise.all(
+        item.frames.map(async (planned): Promise<LoadedFrame> => {
+          try {
+            let pending = blobCache.get(planned.frame.imageUrl)
+            if (pending === undefined) {
+              pending = runtime.fetchFrame(planned.frame.imageUrl)
+              blobCache.set(planned.frame.imageUrl, pending)
+            }
+            const blob = await pending
+            const decoded = await runtime.decodeFrame(blob)
+            const extension = extensionForBlob(blob, planned.frame.imageUrl)
+            return {
+              ...planned,
+              blob,
+              decoded,
+              sourceFilename: `${String(planned.index).padStart(3, '0')}.${extension}`,
+            }
+          } catch {
+            incomplete = true
+            return { ...planned, blob: null, decoded: null, sourceFilename: planned.filename }
+          }
+        }),
+      ),
+    })),
+  )
+
+  onPhase?.('rendering')
+  const zipEntries: ZipEntry[] = []
+  try {
+    for (const { item, frames } of loaded) {
+      const cellWidth = Math.max(1, ...frames.map((current) => current.decoded?.width ?? 0))
+      const cellHeight = Math.max(1, ...frames.map((current) => current.decoded?.height ?? 0))
+      const canvas = runtime.createCanvas(cellWidth * item.columns, cellHeight * item.rows)
+      const context = canvas.getContext('2d')
+      if (context === null) throw new Error('浏览器无法创建 Sprite Sheet')
+      context.clearRect(0, 0, canvas.width, canvas.height)
+
+      const animationFrames = frames.map((current) => {
+        const column = current.index % item.columns
+        const row = Math.floor(current.index / item.columns)
+        const width = current.decoded?.width ?? 0
+        const height = current.decoded?.height ?? 0
+        const offsetX = Math.floor((cellWidth - width) / 2)
+        const offsetY = Math.floor((cellHeight - height) / 2)
+        if (current.decoded !== null) {
+          context.drawImage(
+            current.decoded.source,
+            column * cellWidth + offsetX,
+            row * cellHeight + offsetY,
+          )
+        }
+        return {
+          index: current.index,
+          source: `frames/${current.sourceFilename}`,
+          available: current.blob !== null,
+          x: column * cellWidth + offsetX,
+          y: row * cellHeight + offsetY,
+          width,
+          height,
+          originalWidth: width,
+          originalHeight: height,
+          offsetX,
+          offsetY,
+          durationMs: current.frame.durationMs,
+          keyFrame: current.frame.keyFrame,
+          rootMotion: current.frame.rootMotion,
+        }
+      })
+
+      const sheet = await canvasPng(canvas)
+      zipEntries.push({ name: `${item.folder}/sprite-sheet.png`, data: await bytes(sheet) })
+      for (const current of frames) {
+        if (current.blob === null) continue
+        zipEntries.push({
+          name: `${item.folder}/frames/${current.sourceFilename}`,
+          data: await bytes(current.blob),
+        })
+      }
+      zipEntries.push({
+        name: `${item.folder}/animation.json`,
+        data: await bytes(
+          JSON.stringify(
+            {
+              schemaVersion: 1,
+              action: {
+                id: item.action.id,
+                name: item.action.name,
+                type: item.action.type,
+              },
+              direction: item.sequence.direction,
+              fps: item.action.fps,
+              spriteSheet: {
+                file: 'sprite-sheet.png',
+                width: canvas.width,
+                height: canvas.height,
+                columns: item.columns,
+                rows: item.rows,
+                cellWidth,
+                cellHeight,
+              },
+              frames: animationFrames,
+            },
+            null,
+            2,
+          ),
+        ),
+      })
+    }
+  } finally {
+    loaded.forEach(({ frames }) => frames.forEach((current) => current.decoded?.close()))
+  }
+
+  onPhase?.('packing')
+  return {
+    blob: storedZip(zipEntries),
+    filename: `windup-${safeSegment(model.characterName, 'character')}-${safeSegment(model.outfitName, 'outfit')}.zip`,
+    incomplete,
+  }
+}
diff --git a/frontend/src/features/export-package/export-panel.test.tsx b/frontend/src/features/export-package/export-panel.test.tsx
new file mode 100644
index 0000000..56d07a4
--- /dev/null
+++ b/frontend/src/features/export-package/export-panel.test.tsx
@@ -0,0 +1,120 @@
+/** @vitest-environment jsdom */
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import type { ExportPackageModel as PlaytestPreviewModel } from './model'
+import { ExportPanel } from './export-panel'
+
+const model = {
+  characterId: 'character-1',
+  characterName: 'Aster',
+  outfitId: 'outfit-1',
+  outfitName: 'Explorer',
+  characterTemplateUrl: null,
+  baseFrameCount: 0,
+  actions: [
+    {
+      id: 'walk-abcdef12',
+      name: 'Walk',
+      type: 'walk',
+      fps: 10,
+      sequences: [
+        {
+          direction: 'south',
+          frames: [
+            {
+              imageUrl: '/walk.png',
+              durationMs: 100,
+              rootMotion: null,
+              keyFrame: true,
+            },
+          ],
+        },
+      ],
+    },
+  ],
+} satisfies PlaytestPreviewModel
+
+afterEach(() => {
+  cleanup()
+  vi.restoreAllMocks()
+})
+
+describe('ExportPanel', () => {
+  it('warns about current quality issues without blocking export', () => {
+    render(<ExportPanel model={model} qualityIssueCount={3} />)
+
+    expect(screen.getByText('当前核验存在 3 项质量问题，仍可导出')).toBeTruthy()
+    expect(
+      (screen.getByRole('button', { name: '导出游戏资产包' }) as HTMLButtonElement).disabled,
+    ).toBe(false)
+  })
+
+  it('shows progress, prevents duplicate export, downloads and revokes the object url', async () => {
+    let resolveExport: (value: {
+      blob: Blob
+      filename: string
+      incomplete: boolean
+    }) => void = () => {
+      throw new Error('export promise was not initialized')
+    }
+    const exporter = vi.fn(
+      (
+        _model: PlaytestPreviewModel,
+        onPhase?: (phase: 'collecting' | 'rendering' | 'packing') => void,
+      ) => {
+        onPhase?.('rendering')
+        return new Promise<{ blob: Blob; filename: string; incomplete: boolean }>((resolve) => {
+          resolveExport = resolve
+        })
+      },
+    )
+    const createObjectURL = vi.fn(() => 'blob:asset-package')
+    const revokeObjectURL = vi.fn()
+    Object.defineProperty(URL, 'createObjectURL', { configurable: true, value: createObjectURL })
+    Object.defineProperty(URL, 'revokeObjectURL', { configurable: true, value: revokeObjectURL })
+    const click = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => undefined)
+
+    render(<ExportPanel model={model} exporter={exporter} />)
+    const button = screen.getByRole('button', { name: '导出游戏资产包' })
+    fireEvent.click(button)
+    fireEvent.click(button)
+    expect(screen.getByText('正在生成图片')).toBeTruthy()
+    expect(exporter).toHaveBeenCalledTimes(1)
+
+    resolveExport({
+      blob: new Blob(['zip'], { type: 'application/zip' }),
+      filename: 'windup-Aster-Explorer.zip',
+      incomplete: false,
+    })
+    await waitFor(() => expect(screen.getByText('下载完成')).toBeTruthy())
+    expect(createObjectURL).toHaveBeenCalledTimes(1)
+    expect(click).toHaveBeenCalledTimes(1)
+    expect(revokeObjectURL).toHaveBeenCalledWith('blob:asset-package')
+    click.mockRestore()
+  })
+
+  it('warns for incomplete packages and allows retry after failure', async () => {
+    const exporter = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('pack failed'))
+      .mockResolvedValueOnce({
+        blob: new Blob(['zip'], { type: 'application/zip' }),
+        filename: 'windup-Aster-Explorer.zip',
+        incomplete: true,
+      })
+    Object.defineProperty(URL, 'createObjectURL', {
+      configurable: true,
+      value: vi.fn(() => 'blob:retry'),
+    })
+    Object.defineProperty(URL, 'revokeObjectURL', { configurable: true, value: vi.fn() })
+    vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => undefined)
+
+    render(<ExportPanel model={model} exporter={exporter} />)
+    fireEvent.click(screen.getByRole('button', { name: '导出游戏资产包' }))
+    await waitFor(() => expect(screen.getByText('导出失败，可重试')).toBeTruthy())
+    fireEvent.click(screen.getByRole('button', { name: '重新导出' }))
+    await waitFor(() => expect(screen.getByText('导出不完整，缺失图片已保留透明占位')).toBeTruthy())
+    expect(exporter).toHaveBeenCalledTimes(2)
+  })
+})
diff --git a/frontend/src/features/export-package/export-panel.tsx b/frontend/src/features/export-package/export-panel.tsx
new file mode 100644
index 0000000..cea311a
--- /dev/null
+++ b/frontend/src/features/export-package/export-panel.tsx
@@ -0,0 +1,122 @@
+import { useState } from 'react'
+
+import type { ExportPackageModel } from './model'
+import {
+  createAssetExportPlan,
+  exportGameAssets,
+  type AssetExportPhase,
+  type AssetExportResult,
+} from './asset-export'
+
+export type AssetExporter = (
+  model: ExportPackageModel,
+  onPhase?: (phase: AssetExportPhase) => void,
+) => Promise<AssetExportResult>
+
+export interface ExportPanelProps {
+  model: ExportPackageModel
+  qualityIssueCount?: number
+  exporter?: AssetExporter
+}
+
+type ExportState =
+  | { status: 'idle' }
+  | { status: 'working'; phase: AssetExportPhase }
+  | { status: 'success'; incomplete: boolean }
+  | { status: 'failure' }
+
+const PHASE_LABELS: Readonly<Record<AssetExportPhase, string>> = {
+  collecting: '正在整理素材',
+  rendering: '正在生成图片',
+  packing: '正在打包',
+}
+
+const defaultExporter: AssetExporter = (model, onPhase) =>
+  exportGameAssets(model, undefined, onPhase)
+
+export function ExportPanel({
+  model,
+  qualityIssueCount = 0,
+  exporter = defaultExporter,
+}: ExportPanelProps) {
+  const [state, setState] = useState<ExportState>({ status: 'idle' })
+  const plan = createAssetExportPlan(model)
+  const working = state.status === 'working'
+
+  const startExport = async () => {
+    if (working) return
+    setState({ status: 'working', phase: 'collecting' })
+    try {
+      const result = await exporter(model, (phase) => setState({ status: 'working', phase }))
+      const url = URL.createObjectURL(result.blob)
+      const anchor = document.createElement('a')
+      anchor.href = url
+      anchor.download = result.filename
+      anchor.click()
+      URL.revokeObjectURL(url)
+      setState({ status: 'success', incomplete: result.incomplete })
+    } catch {
+      setState({ status: 'failure' })
+    }
+  }
+
+  return (
+    <section
+      aria-label="资产导出"
+      aria-busy={working}
+      className="space-y-4 rounded-xl border border-slate-200 bg-white p-4 shadow-sm"
+    >
+      <header>
+        <p className="text-[10px] font-semibold tracking-[0.18em] text-slate-400">GAME ASSETS</p>
+        <h2 className="mt-1 text-sm font-semibold text-slate-900">资产导出</h2>
+        <p className="mt-1 text-[11px] text-slate-500">逐帧原图、Sprite Sheet 与动画 JSON</p>
+      </header>
+
+      <dl className="grid grid-cols-[auto_1fr] gap-x-3 gap-y-2 text-xs">
+        <dt className="text-slate-500">动作方向</dt>
+        <dd className="font-medium text-slate-900">{plan.length} 组</dd>
+        <dt className="text-slate-500">逐帧原图</dt>
+        <dd className="font-medium text-slate-900">
+          {plan.reduce((total, item) => total + item.frames.length, 0)} 张
+        </dd>
+        <dt className="text-slate-500">每行上限</dt>
+        <dd className="font-medium text-slate-900">8 帧</dd>
+      </dl>
+
+      {qualityIssueCount > 0 ? (
+        <p className="rounded-lg bg-amber-50 px-3 py-2 text-xs text-amber-900">
+          当前核验存在 {qualityIssueCount} 项质量问题，仍可导出
+        </p>
+      ) : null}
+
+      {state.status === 'working' ? (
+        <p role="status" className="rounded-lg bg-slate-50 px-3 py-2 text-xs text-slate-700">
+          {PHASE_LABELS[state.phase]}
+        </p>
+      ) : state.status === 'failure' ? (
+        <p role="alert" className="rounded-lg bg-rose-50 px-3 py-2 text-xs text-rose-800">
+          导出失败，可重试
+        </p>
+      ) : state.status === 'success' ? (
+        <div className="space-y-2">
+          <p className="rounded-lg bg-emerald-50 px-3 py-2 text-xs text-emerald-800">下载完成</p>
+          {state.incomplete ? (
+            <p className="rounded-lg bg-amber-50 px-3 py-2 text-xs text-amber-900">
+              导出不完整，缺失图片已保留透明占位
+            </p>
+          ) : null}
+        </div>
+      ) : null}
+
+      <button
+        type="button"
+        disabled={working || plan.length === 0}
+        onClick={() => void startExport()}
+        className="w-full rounded-lg bg-orange-500 px-3 py-2 text-xs font-semibold text-white hover:bg-orange-600 disabled:cursor-not-allowed disabled:opacity-40"
+      >
+        {state.status === 'failure' ? '重新导出' : '导出游戏资产包'}
+      </button>
+      {plan.length === 0 ? <p className="text-xs text-slate-500">没有可导出的已确认动作</p> : null}
+    </section>
+  )
+}
diff --git a/frontend/src/features/export-package/index.ts b/frontend/src/features/export-package/index.ts
new file mode 100644
index 0000000..43dc84d
--- /dev/null
+++ b/frontend/src/features/export-package/index.ts
@@ -0,0 +1,10 @@
+/** 将预览台当前角色资产打包下载；与发布到资产库是两件事。 */
+export { ExportPanel } from './export-panel'
+export type { ExportPackageModel } from './model'
+export {
+  createAssetExportPlan,
+  exportGameAssets,
+  type AssetExportPhase,
+  type AssetExportResult,
+  type AssetExportRuntime,
+} from './asset-export'
diff --git a/frontend/src/features/export-package/model.ts b/frontend/src/features/export-package/model.ts
new file mode 100644
index 0000000..28577bd
--- /dev/null
+++ b/frontend/src/features/export-package/model.ts
@@ -0,0 +1,32 @@
+import type { ActionType, Frame } from '@/entities'
+
+/** 导出功能只依赖这份只读模型，不依赖 Playtest 页面内部实现。 */
+export interface ExportFrame {
+  imageUrl: string
+  durationMs: number
+  rootMotion: Frame['rootMotion']
+  keyFrame: boolean
+}
+
+export interface ExportSequence {
+  direction: string
+  frames: readonly ExportFrame[]
+}
+
+export interface ExportAction {
+  id: string
+  name: string
+  type: ActionType | 'crouch'
+  fps: number
+  sequences: readonly ExportSequence[]
+}
+
+export interface ExportPackageModel {
+  characterId: string
+  characterName: string
+  outfitId: string
+  outfitName: string
+  characterTemplateUrl: string | null
+  baseFrameCount: number
+  actions: readonly ExportAction[]
+}

From 3cbfbc9eb12292c128aaaa8036b765039532112d Mon Sep 17 00:00:00 2001
From: xyh202131 <246811510+xyh202131@users.noreply.github.com>
Date: Tue, 4 Aug 2026 14:34:17 +0800
Subject: [PATCH 2/2] feat(export-package): enforce complete asset contracts

---
 frontend/package-lock.json                    |  56 ++
 frontend/package.json                         |   2 +
 .../src/features/export-package/README.md     |  48 ++
 .../export-package/asset-export.test.ts       | 226 +++++---
 .../features/export-package/asset-export.ts   | 507 ++++++++++++------
 .../features/export-package/cocos-target.ts   |  15 +
 .../src/features/export-package/contract.ts   | 116 ++++
 .../export-package/export-package.schema.json | 100 ++++
 .../export-package/export-panel.test.tsx      |  45 +-
 .../features/export-package/export-panel.tsx  |  38 +-
 .../src/features/export-package/gifenc.d.ts   |  33 ++
 frontend/src/features/export-package/index.ts |  21 +-
 frontend/src/features/export-package/model.ts |  33 +-
 13 files changed, 978 insertions(+), 262 deletions(-)
 create mode 100644 frontend/src/features/export-package/README.md
 create mode 100644 frontend/src/features/export-package/cocos-target.ts
 create mode 100644 frontend/src/features/export-package/contract.ts
 create mode 100644 frontend/src/features/export-package/export-package.schema.json
 create mode 100644 frontend/src/features/export-package/gifenc.d.ts

diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index d513d30..2e5a572 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -8,6 +8,7 @@
       "name": "windup-frontend",
       "version": "0.0.0",
       "dependencies": {
+        "gifenc": "^1.0.3",
         "react": "^19.2.7",
         "react-dom": "^19.2.7",
         "react-router": "^8.3.0"
@@ -19,6 +20,7 @@
         "@types/react": "^19.2.17",
         "@types/react-dom": "^19.2.3",
         "@vitejs/plugin-react": "^6.0.3",
+        "ajv": "^8.20.0",
         "jsdom": "^29.1.1",
         "oxfmt": "^0.61.0",
         "oxlint": "^1.71.0",
@@ -2202,6 +2204,23 @@
         "url": "https://opencollective.com/vitest"
       }
     },
+    "node_modules/ajv": {
+      "version": "8.20.0",
+      "resolved": "https://registry.npmmirror.com/ajv/-/ajv-8.20.0.tgz",
+      "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
     "node_modules/ansi-regex": {
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
@@ -2406,6 +2425,30 @@
         "node": ">=12.0.0"
       }
     },
+    "node_modules/fast-deep-equal": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmmirror.com/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/fast-uri": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmmirror.com/fast-uri/-/fast-uri-3.1.5.tgz",
+      "integrity": "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
     "node_modules/fdir": {
       "version": "6.5.0",
       "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
@@ -2439,6 +2482,12 @@
         "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
       }
     },
+    "node_modules/gifenc": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmmirror.com/gifenc/-/gifenc-1.0.3.tgz",
+      "integrity": "sha512-xdr6AdrfGBcfzncONUOlXMBuc5wJDtOueE3c5rdG0oNgtINLD+f2iFZltrBRZYzACRbKr+mSVU/x98zv2u3jmw==",
+      "license": "MIT"
+    },
     "node_modules/graceful-fs": {
       "version": "4.2.11",
       "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
@@ -2525,6 +2574,13 @@
         }
       }
     },
+    "node_modules/json-schema-traverse": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmmirror.com/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/lightningcss": {
       "version": "1.33.0",
       "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.33.0.tgz",
diff --git a/frontend/package.json b/frontend/package.json
index 0a845f7..4edb565 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -14,6 +14,7 @@
     "typecheck": "tsc -b"
   },
   "dependencies": {
+    "gifenc": "^1.0.3",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "react-router": "^8.3.0"
@@ -25,6 +26,7 @@
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.3",
+    "ajv": "^8.20.0",
     "jsdom": "^29.1.1",
     "oxfmt": "^0.61.0",
     "oxlint": "^1.71.0",
diff --git a/frontend/src/features/export-package/README.md b/frontend/src/features/export-package/README.md
new file mode 100644
index 0000000..95c61e3
--- /dev/null
+++ b/frontend/src/features/export-package/README.md
@@ -0,0 +1,48 @@
+# Export Package 模块
+
+本模块把已经通过质量检测的角色动作整理为可下载 ZIP。它不负责生成图片、保存历史记录或发布资产，只负责验证和导出。
+
+## 数据怎么走
+
+1. Playtest 或接口适配器组装 `ExportPackageModel`。
+2. `validateExportPackageModel` 检查角色、画布、生成记录、帧数、质量状态、锚点和脚底线。
+3. `createAssetExportPlan` 为每个动作方向生成稳定目录与三位连续帧名。
+4. `exportGameAssets` 读取透明 PNG，并检查图片尺寸是否与统一画布一致。
+5. 浏览器生成图集和 GIF，最后写入 `meta.json`、`schema.json`、README 与 ZIP。
+6. 可选 target 只在 `targets/<target-id>/` 下追加引擎文件，不修改通用层。
+
+## 导出结构
+
+```text
+Aster-character-1/
+  meta.json
+  schema.json
+  README.md
+  preview/Walk-south.gif
+  frames/Walk-south/Walk-south_000.png
+  atlas/Walk-south.png
+  targets/<target-id>/...
+```
+
+`meta.json` 的坐标原点在左上角，y 轴向下。`anchor` 是 0-1 归一化坐标，`foot_y` 是从画布顶部开始计算的像素值。
+
+## 为什么缺一帧就全部失败
+
+`expectedFrameCount` 表示后端声明的完整帧数，不能用 `frames.length` 自己推算。两者不同、图片读取失败、PNG 无透明信息、尺寸不一致或 `qualityStatus` 不是 `passed` 时，导出立即失败，不会用透明占位掩盖问题，也不会下载残缺包。
+
+## Cocos Creator 边界
+
+Issue #94 要求先用真实 Cocos Creator 3.x 验证图集切分数据、`.anim`、`.meta`、UUID 与小版本差异。当前仓库没有该实测结论，因此本模块只落地已确定的通用层和 target 扩展接口，不伪造 Cocos 原生文件。
+
+Cocos 坐标转换规则已经明确：通用锚点 `(x, y)` 转成 Creator 锚点 `(x, 1-y)`。等实测字段回填后，只需新增一个 `AssetExportTarget`，不改 `meta.json` 与通用打包逻辑。
+
+## 验证
+
+```bash
+npm test -- src/features/export-package
+npm run typecheck
+npm run lint
+npm run build
+```
+
+测试覆盖 Schema 校验、连续命名、GIF/图集输出、缺帧失败、质量门禁、图片释放和空 target 扩展。
diff --git a/frontend/src/features/export-package/asset-export.test.ts b/frontend/src/features/export-package/asset-export.test.ts
index d9cfeb8..225ca58 100644
--- a/frontend/src/features/export-package/asset-export.test.ts
+++ b/frontend/src/features/export-package/asset-export.test.ts
@@ -1,23 +1,27 @@
 /** @vitest-environment jsdom */
+import Ajv2020 from 'ajv/dist/2020.js'
 import { describe, expect, it, vi } from 'vitest'
 
-import type {
-  ExportAction as PreviewAction,
-  ExportFrame as PreviewFrame,
-  ExportPackageModel as PlaytestPreviewModel,
-} from './model'
-import { createAssetExportPlan, exportGameAssets, type AssetExportRuntime } from './asset-export'
+import {
+  createAssetExportPlan,
+  exportGameAssets,
+  type AssetExportRuntime,
+  type AssetExportTarget,
+} from './asset-export'
+import { COCOS_TARGET_READINESS, toCocosAnchor } from './cocos-target'
+import { EXPORT_PACKAGE_JSON_SCHEMA_TEXT } from './contract'
+import type { ExportAction, ExportFrame, ExportPackageModel } from './model'
 
-function frame(index: number): PreviewFrame {
+function frame(index: number): ExportFrame {
   return {
     imageUrl: `/frames/walk-${index}.png`,
-    durationMs: 100 + index,
+    durationMs: 100,
     rootMotion: { dx: index, dy: 0 },
     keyFrame: index === 0,
   }
 }
 
-function action(frameCount = 9): PreviewAction {
+function action(frameCount = 9): ExportAction {
   return {
     id: 'walk-abcdef12',
     name: 'Walk / Forward',
@@ -26,37 +30,54 @@ function action(frameCount = 9): PreviewAction {
     sequences: [
       {
         direction: 'south',
+        expectedFrameCount: frameCount,
+        loop: true,
+        anchor: { x: 0.5, y: 0.9 },
+        footY: 36,
+        qualityStatus: 'passed',
         frames: Array.from({ length: frameCount }, (_, index) => frame(index)),
       },
     ],
   }
 }
 
-const model: PlaytestPreviewModel = {
+const model: ExportPackageModel = {
   characterId: 'character-1',
   characterName: 'Aster',
   outfitId: 'outfit-1',
   outfitName: 'Explorer',
   characterTemplateUrl: null,
   baseFrameCount: 0,
-  actions: [action(), action(0)],
+  canvas: { width: 32, height: 40 },
+  source: { workflowRunId: 'run-1', generationIds: ['generation-1'] },
+  actions: [action()],
+}
+
+/** 构造足够让契约检查识别为 RGBA PNG 的文件头，解码由测试运行时接管。 */
+function rgbaPng(): Blob {
+  const data = new Uint8Array(33)
+  data.set([137, 80, 78, 71, 13, 10, 26, 10], 0)
+  new DataView(data.buffer).setUint32(8, 13, false)
+  data.set([73, 72, 68, 82], 12)
+  data[25] = 6
+  return new Blob([data], { type: 'image/png' })
 }
 
 async function readStoredZip(blob: Blob): Promise<Map<string, Uint8Array>> {
-  const bytes = new Uint8Array(await blob.arrayBuffer())
-  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  const data = new Uint8Array(await blob.arrayBuffer())
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
   const decoder = new TextDecoder()
   const entries = new Map<string, Uint8Array>()
   let offset = 0
 
-  while (offset + 4 <= bytes.length && view.getUint32(offset, true) === 0x04034b50) {
+  while (offset + 4 <= data.length && view.getUint32(offset, true) === 0x04034b50) {
     const compressedSize = view.getUint32(offset + 18, true)
     const nameLength = view.getUint16(offset + 26, true)
     const extraLength = view.getUint16(offset + 28, true)
     const nameStart = offset + 30
     const dataStart = nameStart + nameLength + extraLength
-    const name = decoder.decode(bytes.slice(nameStart, nameStart + nameLength))
-    entries.set(name, bytes.slice(dataStart, dataStart + compressedSize))
+    const name = decoder.decode(data.slice(nameStart, nameStart + nameLength))
+    entries.set(name, data.slice(dataStart, dataStart + compressedSize))
     offset = dataStart + compressedSize
   }
   return entries
@@ -66,11 +87,11 @@ function runtime(failingUrl: string | null = null): AssetExportRuntime {
   return {
     fetchFrame: vi.fn(async (url) => {
       if (url === failingUrl) throw new Error('missing')
-      return new Blob([`original:${url}`], { type: 'image/png' })
+      return rgbaPng()
     }),
-    decodeFrame: vi.fn(async (blob) => ({
+    decodeFrame: vi.fn(async () => ({
       source: {} as CanvasImageSource,
-      width: blob.size % 2 === 0 ? 32 : 24,
+      width: 32,
       height: 40,
       close: vi.fn(),
     })),
@@ -79,10 +100,14 @@ function runtime(failingUrl: string | null = null): AssetExportRuntime {
       canvas.width = width
       canvas.height = height
       Object.defineProperty(canvas, 'getContext', {
-        value: () => ({ clearRect: vi.fn(), drawImage: vi.fn() }),
+        value: () => ({
+          clearRect: vi.fn(),
+          drawImage: vi.fn(),
+          getImageData: vi.fn(() => ({ data: new Uint8ClampedArray(width * height * 4) })),
+        }),
       })
       Object.defineProperty(canvas, 'toBlob', {
-        value: (callback: BlobCallback) => callback(new Blob(['sheet'], { type: 'image/png' })),
+        value: (callback: BlobCallback) => callback(new Blob(['atlas'], { type: 'image/png' })),
       })
       return canvas
     }),
@@ -90,70 +115,137 @@ function runtime(failingUrl: string | null = null): AssetExportRuntime {
 }
 
 describe('asset export', () => {
-  it('plans non-empty sequences and wraps after eight columns', () => {
+  it('明确 Cocos 尚未就绪，并只落地已确认的锚点坐标转换', () => {
+    expect(COCOS_TARGET_READINESS.ready).toBe(false)
+    const anchor = toCocosAnchor({ x: 0.5, y: 0.9 })
+    expect(anchor.x).toBe(0.5)
+    expect(anchor.y).toBeCloseTo(0.1)
+  })
+
+  it('按动作名和方向生成连续三位帧名，并按八列排列图集', () => {
     const plan = createAssetExportPlan(model)
 
     expect(plan).toHaveLength(1)
     expect(plan[0]).toMatchObject({
+      exportName: 'Walk-Forward-south',
+      framesFolder: 'frames/Walk-Forward-south',
+      atlasFile: 'atlas/Walk-Forward-south.png',
+      previewFile: 'preview/Walk-Forward-south.gif',
       columns: 8,
       rows: 2,
-      folder: 'actions/Walk-Forward-abcdef12/south',
     })
-    expect(plan[0]?.frames.map((item) => item.filename)).toEqual([
-      '000.png',
-      '001.png',
-      '002.png',
-      '003.png',
-      '004.png',
-      '005.png',
-      '006.png',
-      '007.png',
-      '008.png',
-    ])
+    expect(plan[0]?.frames[0]?.filename).toBe('Walk-Forward-south_000.png')
+    expect(plan[0]?.frames[8]?.filename).toBe('Walk-Forward-south_008.png')
   })
 
-  it('creates a zip containing only original frames, a sprite sheet and animation json', async () => {
+  it('生成通用目录、透明 PNG、图集、GIF、README、Schema 和可校验的 meta.json', async () => {
     const phases: string[] = []
-    const result = await exportGameAssets(model, runtime(), (phase) => phases.push(phase))
+    const result = await exportGameAssets(model, {
+      runtime: runtime(),
+      onPhase: (phase) => phases.push(phase),
+    })
     const entries = await readStoredZip(result.blob)
+    const root = 'Aster-character-1'
     const names = [...entries.keys()]
 
-    expect(result).toMatchObject({ filename: 'windup-Aster-Explorer.zip', incomplete: false })
-    expect(phases).toEqual(['collecting', 'rendering', 'packing'])
-    expect(names).toContain('actions/Walk-Forward-abcdef12/south/sprite-sheet.png')
-    expect(names).toContain('actions/Walk-Forward-abcdef12/south/animation.json')
+    expect(result.filename).toBe('windup-Aster-character-1.zip')
+    expect(phases).toEqual(['validating', 'collecting', 'rendering', 'packing'])
+    expect(names).toContain(`${root}/meta.json`)
+    expect(names).toContain(`${root}/schema.json`)
+    expect(names).toContain(`${root}/README.md`)
+    expect(names).toContain(`${root}/atlas/Walk-Forward-south.png`)
+    expect(names).toContain(`${root}/preview/Walk-Forward-south.gif`)
     expect(names.filter((name) => name.includes('/frames/'))).toHaveLength(9)
-    expect(names.some((name) => /manifest|audit/i.test(name))).toBe(false)
-
-    const jsonBytes = entries.get('actions/Walk-Forward-abcdef12/south/animation.json')
-    const animation = JSON.parse(new TextDecoder().decode(jsonBytes))
-    expect(animation.spriteSheet).toMatchObject({ columns: 8, rows: 2 })
-    expect(animation.frames[0]).toMatchObject({
-      index: 0,
-      source: 'frames/000.png',
-      available: true,
-      durationMs: 100,
-      keyFrame: true,
+
+    const meta = JSON.parse(new TextDecoder().decode(entries.get(`${root}/meta.json`)))
+    const schema = JSON.parse(EXPORT_PACKAGE_JSON_SCHEMA_TEXT)
+    const validate = new Ajv2020().compile(schema)
+    expect(validate(meta), JSON.stringify(validate.errors)).toBe(true)
+    expect(meta).toMatchObject({
+      schema_version: '1.0.0',
+      character: { id: 'character-1', name: 'Aster' },
+      canvas: { w: 32, h: 40 },
+      source: { workflow_run_id: 'run-1', generation_ids: ['generation-1'] },
     })
+    expect(meta.actions[0]).toMatchObject({
+      name: 'Walk-Forward-south',
+      fps: 10,
+      loop: true,
+      anchor: { x: 0.5, y: 0.9 },
+      foot_y: 36,
+      atlas: { cols: 8, rows: 2, cell: { w: 32, h: 40 } },
+    })
+    expect(
+      new TextDecoder().decode(entries.get(`${root}/preview/Walk-Forward-south.gif`)).slice(0, 6),
+    ).toBe('GIF89a')
   })
 
-  it('keeps a transparent cell and marks a failed original frame unavailable', async () => {
-    const result = await exportGameAssets(model, runtime('/frames/walk-4.png'))
-    const entries = await readStoredZip(result.blob)
-    const animation = JSON.parse(
-      new TextDecoder().decode(entries.get('actions/Walk-Forward-abcdef12/south/animation.json')),
+  it('声明帧数与实际帧数不一致时，在读取图片前拒绝导出', async () => {
+    const badModel: ExportPackageModel = {
+      ...model,
+      actions: [
+        {
+          ...action(),
+          sequences: [{ ...action().sequences[0]!, expectedFrameCount: 10 }],
+        },
+      ],
+    }
+    const testRuntime = runtime()
+
+    await expect(exportGameAssets(badModel, { runtime: testRuntime })).rejects.toThrow(
+      'actions[0].sequences[0].frames: 缺帧，期望 10 帧，实际 9 帧',
     )
+    expect(testRuntime.fetchFrame).not.toHaveBeenCalled()
+  })
 
-    expect(result.incomplete).toBe(true)
-    expect(entries.has('actions/Walk-Forward-abcdef12/south/frames/004.png')).toBe(false)
-    expect(animation.frames[4]).toMatchObject({
-      index: 4,
-      source: 'frames/004.png',
-      available: false,
-    })
+  it('任一原图读取失败时拒绝整个导出，不再生成透明占位包', async () => {
+    await expect(
+      exportGameAssets(model, { runtime: runtime('/frames/walk-4.png') }),
+    ).rejects.toThrow('frames/Walk-Forward-south/Walk-Forward-south_004.png: 图片读取失败')
+  })
+
+  it('质量状态未通过时禁止导出', async () => {
+    const badModel: ExportPackageModel = {
+      ...model,
+      actions: [
+        {
+          ...action(),
+          sequences: [{ ...action().sequences[0]!, qualityStatus: 'pending' }],
+        },
+      ],
+    }
+
+    await expect(exportGameAssets(badModel, { runtime: runtime() })).rejects.toThrow(
+      'actions[0].sequences[0].qualityStatus: 质量检测未通过，禁止导出',
+    )
+  })
+
+  it('空 target 不改变通用层，新增 target 文件只进入自己的目录', async () => {
+    const emptyTarget: AssetExportTarget = {
+      id: 'empty',
+      createFiles: vi.fn(async () => []),
+    }
+    const cocosProbe: AssetExportTarget = {
+      id: 'cocos-probe',
+      createFiles: vi.fn(async ({ metadata }) => [
+        { path: 'anchor-map.json', data: JSON.stringify({ source: metadata.actions[0]?.anchor }) },
+      ]),
+    }
+    const common = await readStoredZip((await exportGameAssets(model, { runtime: runtime() })).blob)
+    const extended = await readStoredZip(
+      (await exportGameAssets(model, { runtime: runtime(), targets: [emptyTarget, cocosProbe] }))
+        .blob,
+    )
+    const targetPath = 'Aster-character-1/targets/cocos-probe/anchor-map.json'
+
+    expect([...extended.keys()].filter((name) => !name.includes('/targets/'))).toEqual([
+      ...common.keys(),
+    ])
+    expect(extended.has(targetPath)).toBe(true)
+    expect(emptyTarget.createFiles).toHaveBeenCalledTimes(1)
   })
 
-  it('releases decoded images when sprite-sheet rendering fails', async () => {
+  it('渲染失败时释放已经解码的全部图片', async () => {
     const baseRuntime = runtime()
     const closes: Array<ReturnType<typeof vi.fn>> = []
     const failingRuntime: AssetExportRuntime = {
@@ -161,7 +253,7 @@ describe('asset export', () => {
       decodeFrame: vi.fn(async () => {
         const close = vi.fn()
         closes.push(close)
-        return { source: {} as CanvasImageSource, width: 24, height: 40, close }
+        return { source: {} as CanvasImageSource, width: 32, height: 40, close }
       }),
       createCanvas: vi.fn((width, height) => {
         const canvas = document.createElement('canvas')
@@ -172,8 +264,8 @@ describe('asset export', () => {
       }),
     }
 
-    await expect(exportGameAssets(model, failingRuntime)).rejects.toThrow(
-      '浏览器无法创建 Sprite Sheet',
+    await expect(exportGameAssets(model, { runtime: failingRuntime })).rejects.toThrow(
+      'atlas/Walk-Forward-south.png: 浏览器无法创建 2D 画布',
     )
     expect(closes).toHaveLength(9)
     expect(closes.every((close) => close.mock.calls.length === 1)).toBe(true)
diff --git a/frontend/src/features/export-package/asset-export.ts b/frontend/src/features/export-package/asset-export.ts
index 4310c6c..51532a2 100644
--- a/frontend/src/features/export-package/asset-export.ts
+++ b/frontend/src/features/export-package/asset-export.ts
@@ -1,11 +1,18 @@
+import { GIFEncoder, applyPalette, quantize } from 'gifenc'
+
+import {
+  EXPORT_PACKAGE_JSON_SCHEMA_TEXT,
+  EXPORT_PACKAGE_SCHEMA_VERSION,
+  type GenericExportMetadata,
+  validateExportPackageModel,
+} from './contract'
 import type { ExportAction, ExportFrame, ExportPackageModel, ExportSequence } from './model'
 
-export type AssetExportPhase = 'collecting' | 'rendering' | 'packing'
+export type AssetExportPhase = 'validating' | 'collecting' | 'rendering' | 'packing'
 
 export interface AssetExportResult {
   blob: Blob
   filename: string
-  incomplete: boolean
 }
 
 export interface DecodedFrame {
@@ -25,21 +32,53 @@ export interface PlannedFrame {
   frame: ExportFrame
   index: number
   filename: string
+  relativeFile: string
 }
 
 export interface PlannedSequence {
   action: ExportAction
   sequence: ExportSequence
-  folder: string
+  exportName: string
+  framesFolder: string
+  atlasFile: string
+  previewFile: string
   columns: number
   rows: number
   frames: readonly PlannedFrame[]
 }
 
+export interface AssetExportTargetFile {
+  /** 相对于 targets/<target-id>/ 的路径。 */
+  path: string
+  data: Blob | string | Uint8Array
+}
+
+export interface AssetExportTargetContext {
+  model: ExportPackageModel
+  metadata: GenericExportMetadata
+  plan: readonly PlannedSequence[]
+}
+
+/** 新引擎只实现 target，不应修改通用 meta.json、frames、atlas 与 preview。 */
+export interface AssetExportTarget {
+  id: string
+  createFiles(context: AssetExportTargetContext): Promise<readonly AssetExportTargetFile[]>
+}
+
+export interface ExportGameAssetsOptions {
+  runtime?: AssetExportRuntime
+  targets?: readonly AssetExportTarget[]
+  onPhase?: (phase: AssetExportPhase) => void
+}
+
 interface LoadedFrame extends PlannedFrame {
-  blob: Blob | null
-  decoded: DecodedFrame | null
-  sourceFilename: string
+  data: Uint8Array
+  decoded: DecodedFrame
+}
+
+interface LoadedSequence {
+  item: PlannedSequence
+  frames: readonly LoadedFrame[]
 }
 
 interface ZipEntry {
@@ -59,50 +98,60 @@ function idSuffix(id: string): string {
   return safeSegment(id, 'id').slice(-8) || 'id'
 }
 
-function extensionFromUrl(imageUrl: string): string {
-  const match = imageUrl.split(/[?#]/, 1)[0]?.match(/\.([a-zA-Z0-9]{2,5})$/)
-  return match?.[1]?.toLowerCase() ?? 'png'
+function packageRoot(model: ExportPackageModel): string {
+  return `${safeSegment(model.characterName, 'character')}-${safeSegment(model.characterId, 'id')}`
 }
 
-function extensionForBlob(blob: Blob, imageUrl: string): string {
-  const byMime: Readonly<Record<string, string>> = {
-    'image/png': 'png',
-    'image/jpeg': 'jpg',
-    'image/webp': 'webp',
-    'image/gif': 'gif',
-    'image/avif': 'avif',
-  }
-  return byMime[blob.type.toLowerCase()] ?? extensionFromUrl(imageUrl)
+function uniqueActionName(
+  action: ExportAction,
+  sequence: ExportSequence,
+  usedNames: Set<string>,
+): string {
+  const baseName = safeSegment(action.name, 'action')
+  const direction = safeSegment(sequence.direction, 'default')
+  const candidate = direction === 'default' ? baseName : `${baseName}-${direction}`
+  const unique = usedNames.has(candidate) ? `${candidate}-${idSuffix(action.id)}` : candidate
+  if (usedNames.has(unique)) throw new Error(`actions.name: 导出动作名重复：${unique}`)
+  usedNames.add(unique)
+  return unique
 }
 
 export function createAssetExportPlan(model: ExportPackageModel): readonly PlannedSequence[] {
-  return model.actions.flatMap((action) => {
-    const actionFolder = `${safeSegment(action.name, 'action')}-${idSuffix(action.id)}`
-    return action.sequences.flatMap((sequence) => {
+  const usedNames = new Set<string>()
+  return model.actions.flatMap((action) =>
+    action.sequences.flatMap((sequence) => {
       if (sequence.frames.length === 0) return []
+      const exportName = uniqueActionName(action, sequence, usedNames)
       const columns = Math.min(8, sequence.frames.length)
       return [
         {
           action,
           sequence,
-          folder: `actions/${actionFolder}/${safeSegment(sequence.direction, 'default')}`,
+          exportName,
+          framesFolder: `frames/${exportName}`,
+          atlasFile: `atlas/${exportName}.png`,
+          previewFile: `preview/${exportName}.gif`,
           columns,
           rows: Math.ceil(sequence.frames.length / columns),
-          frames: sequence.frames.map((currentFrame, index) => ({
-            frame: currentFrame,
-            index,
-            filename: `${String(index).padStart(3, '0')}.${extensionFromUrl(currentFrame.imageUrl)}`,
-          })),
+          frames: sequence.frames.map((currentFrame, index) => {
+            const filename = `${exportName}_${String(index).padStart(3, '0')}.png`
+            return {
+              frame: currentFrame,
+              index,
+              filename,
+              relativeFile: `frames/${exportName}/${filename}`,
+            }
+          }),
         },
       ]
-    })
-  })
+    }),
+  )
 }
 
 const defaultRuntime: AssetExportRuntime = {
   async fetchFrame(url) {
     const response = await fetch(url)
-    if (!response.ok) throw new Error(`图片读取失败：${response.status}`)
+    if (!response.ok) throw new Error(`HTTP ${response.status}`)
     return response.blob()
   },
   async decodeFrame(blob) {
@@ -125,17 +174,242 @@ const defaultRuntime: AssetExportRuntime = {
 function canvasPng(canvas: HTMLCanvasElement): Promise<Blob> {
   return new Promise((resolve, reject) => {
     canvas.toBlob((blob) => {
-      if (blob === null) reject(new Error('Sprite Sheet 编码失败'))
+      if (blob === null) reject(new Error('atlas: PNG 编码失败'))
       else resolve(blob)
     }, 'image/png')
   })
 }
 
-async function bytes(data: Blob | string): Promise<Uint8Array> {
+async function bytes(data: Blob | string | Uint8Array): Promise<Uint8Array> {
   if (typeof data === 'string') return new TextEncoder().encode(data)
+  if (data instanceof Uint8Array) return data
   return new Uint8Array(await data.arrayBuffer())
 }
 
+function hasPngSignature(data: Uint8Array): boolean {
+  const signature = [137, 80, 78, 71, 13, 10, 26, 10]
+  return signature.every((value, index) => data[index] === value)
+}
+
+/**
+ * MIME 只能说明“服务端声称是 PNG”，不能证明文件真的可用或带透明信息。
+ * 因此这里读取 PNG 头，并兼容 RGBA、灰度 Alpha 与带 tRNS 块的索引 PNG。
+ */
+function assertPngWithAlpha(data: Uint8Array, field: string): void {
+  if (data.length < 33 || !hasPngSignature(data)) throw new Error(`${field}: 必须是有效 PNG`)
+  const colorType = data[25]
+  if (colorType === 4 || colorType === 6) return
+
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
+  let offset = 8
+  while (offset + 12 <= data.length) {
+    const chunkLength = view.getUint32(offset, false)
+    const chunkEnd = offset + 12 + chunkLength
+    if (chunkEnd > data.length) break
+    const chunkName = String.fromCharCode(...data.slice(offset + 4, offset + 8))
+    if (chunkName === 'tRNS') return
+    if (chunkName === 'IEND') break
+    offset = chunkEnd
+  }
+  throw new Error(`${field}: PNG 必须包含 Alpha 透明通道`)
+}
+
+async function loadFrame(
+  planned: PlannedFrame,
+  runtime: AssetExportRuntime,
+  cache: Map<string, Promise<Blob>>,
+): Promise<LoadedFrame> {
+  const field = `${planned.relativeFile}`
+  let pending = cache.get(planned.frame.imageUrl)
+  if (pending === undefined) {
+    pending = runtime.fetchFrame(planned.frame.imageUrl)
+    cache.set(planned.frame.imageUrl, pending)
+  }
+
+  let blob: Blob
+  try {
+    blob = await pending
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : '未知错误'
+    throw new Error(`${field}: 图片读取失败（${reason}）`)
+  }
+  if (blob.type.toLowerCase() !== 'image/png') throw new Error(`${field}: 文件类型必须是 image/png`)
+  const data = await bytes(blob)
+  assertPngWithAlpha(data, field)
+
+  let decoded: DecodedFrame
+  try {
+    decoded = await runtime.decodeFrame(blob)
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : '未知错误'
+    throw new Error(`${field}: PNG 解码失败（${reason}）`)
+  }
+  return { ...planned, data, decoded }
+}
+
+async function loadAllFrames(
+  plan: readonly PlannedSequence[],
+  model: ExportPackageModel,
+  runtime: AssetExportRuntime,
+): Promise<readonly LoadedSequence[]> {
+  const cache = new Map<string, Promise<Blob>>()
+  const references = plan.flatMap((item) => item.frames.map((frame) => ({ item, frame })))
+  const settled = await Promise.allSettled(
+    references.map(async ({ item, frame }) => {
+      const loaded = await loadFrame(frame, runtime, cache)
+      if (
+        loaded.decoded.width !== model.canvas.width ||
+        loaded.decoded.height !== model.canvas.height
+      ) {
+        loaded.decoded.close()
+        throw new Error(
+          `${frame.relativeFile}: 画布应为 ${model.canvas.width}x${model.canvas.height}，实际为 ${loaded.decoded.width}x${loaded.decoded.height}`,
+        )
+      }
+      return { item, loaded }
+    }),
+  )
+
+  const fulfilled = settled.flatMap((result) =>
+    result.status === 'fulfilled' ? [result.value] : [],
+  )
+  const failure = settled.find((result) => result.status === 'rejected')
+  if (failure?.status === 'rejected') {
+    fulfilled.forEach(({ loaded }) => loaded.decoded.close())
+    throw failure.reason
+  }
+
+  return plan.map((item) => ({
+    item,
+    frames: fulfilled.filter((result) => result.item === item).map((result) => result.loaded),
+  }))
+}
+
+function context2d(canvas: HTMLCanvasElement, field: string): CanvasRenderingContext2D {
+  const context = canvas.getContext('2d', { willReadFrequently: true })
+  if (context === null) throw new Error(`${field}: 浏览器无法创建 2D 画布`)
+  return context
+}
+
+async function renderAtlas(
+  loaded: LoadedSequence,
+  model: ExportPackageModel,
+  runtime: AssetExportRuntime,
+): Promise<Blob> {
+  const canvas = runtime.createCanvas(
+    model.canvas.width * loaded.item.columns,
+    model.canvas.height * loaded.item.rows,
+  )
+  const context = context2d(canvas, loaded.item.atlasFile)
+  context.clearRect(0, 0, canvas.width, canvas.height)
+  loaded.frames.forEach((frame) => {
+    const column = frame.index % loaded.item.columns
+    const row = Math.floor(frame.index / loaded.item.columns)
+    context.drawImage(frame.decoded.source, column * model.canvas.width, row * model.canvas.height)
+  })
+  return canvasPng(canvas)
+}
+
+function renderGif(
+  loaded: LoadedSequence,
+  model: ExportPackageModel,
+  runtime: AssetExportRuntime,
+): Blob {
+  const canvas = runtime.createCanvas(model.canvas.width, model.canvas.height)
+  const context = context2d(canvas, loaded.item.previewFile)
+  const gif = GIFEncoder()
+
+  loaded.frames.forEach((frame) => {
+    context.clearRect(0, 0, canvas.width, canvas.height)
+    context.drawImage(frame.decoded.source, 0, 0)
+    const rgba = context.getImageData(0, 0, canvas.width, canvas.height).data
+    const palette = quantize(rgba, 256, { format: 'rgba4444', oneBitAlpha: true })
+    const indexed = applyPalette(rgba, palette, 'rgba4444')
+    const transparentIndex = palette.findIndex((color) => color[3] === 0)
+    gif.writeFrame(indexed, canvas.width, canvas.height, {
+      palette,
+      delay: frame.frame.durationMs,
+      repeat: loaded.item.sequence.loop ? 0 : -1,
+      transparent: transparentIndex >= 0,
+      transparentIndex: Math.max(0, transparentIndex),
+      dispose: 2,
+    })
+  })
+  gif.finish()
+  const output = gif.bytes()
+  const buffer = new ArrayBuffer(output.length)
+  new Uint8Array(buffer).set(output)
+  return new Blob([buffer], { type: 'image/gif' })
+}
+
+function createMetadata(
+  model: ExportPackageModel,
+  plan: readonly PlannedSequence[],
+): GenericExportMetadata {
+  return {
+    schema_version: EXPORT_PACKAGE_SCHEMA_VERSION,
+    character: { id: model.characterId, name: model.characterName },
+    canvas: { w: model.canvas.width, h: model.canvas.height },
+    actions: plan.map((item) => ({
+      name: item.exportName,
+      fps: item.action.fps,
+      loop: item.sequence.loop,
+      frames: item.frames.map((frame) => ({ index: frame.index, file: frame.filename })),
+      anchor: { ...item.sequence.anchor },
+      foot_y: item.sequence.footY,
+      atlas: {
+        file: item.atlasFile,
+        cols: item.columns,
+        rows: item.rows,
+        cell: { w: model.canvas.width, h: model.canvas.height },
+      },
+      preview: item.previewFile,
+    })),
+    source: {
+      workflow_run_id: model.source.workflowRunId,
+      generation_ids: [...model.source.generationIds],
+    },
+  }
+}
+
+function createReadme(model: ExportPackageModel): string {
+  return `# ${model.characterName} 导出包
+
+这是 Windup 通用资产包，契约版本为 ${EXPORT_PACKAGE_SCHEMA_VERSION}。
+
+## 内容
+
+- \`meta.json\`: 动作、帧率、循环、画布、锚点、脚底线、图集与生成记录。
+- \`frames/<action>/\`: 连续编号的透明 PNG 原始帧。
+- \`atlas/<action>.png\`: 按 \`meta.json\` 中 cols、rows 和 cell 切分的图集。
+- \`preview/<action>.gif\`: 动作预览。
+- \`schema.json\`: 校验 \`meta.json\` 的 JSON Schema。
+- \`targets/<target>/\`: 可选引擎适配器产生的原生文件。
+
+## 坐标
+
+通用层原点在画布左上角，y 轴向下；anchor 的 x/y 都是 0 到 1。
+引擎 target 负责坐标换算。例如 Cocos Creator 使用左下角原点，需要换算为 (x, 1-y)。
+
+## Cocos Creator 状态
+
+本包没有伪造 .anim 或 .meta。Issue #94 要求先在真实 Creator 3.x 中确认图集切分、UUID 和版本格式；
+验证完成前只能使用通用 frames、atlas 和 meta.json，不能声称“拖入即播放”。
+`
+}
+
+function safeTargetPath(targetId: string, path: string, index: number): string {
+  const normalized = path.replace(/\\/g, '/')
+  if (
+    normalized.length === 0 ||
+    normalized.startsWith('/') ||
+    normalized.split('/').some((segment) => segment === '..' || segment === '')
+  ) {
+    throw new Error(`targets.${targetId}.files[${index}].path: 必须是安全的相对路径`)
+  }
+  return `targets/${safeSegment(targetId, 'target')}/${normalized}`
+}
+
 function uint32Table(): Uint32Array {
   const table = new Uint32Array(256)
   for (let value = 0; value < 256; value += 1) {
@@ -227,140 +501,73 @@ function storedZip(entries: readonly ZipEntry[]): Blob {
   endView.setUint32(12, centralDirectory.length, true)
   endView.setUint32(16, localOffset, true)
   const output = concat([...localChunks, centralDirectory, end])
-  const arrayBuffer = new ArrayBuffer(output.length)
-  new Uint8Array(arrayBuffer).set(output)
-  return new Blob([arrayBuffer], { type: 'application/zip' })
+  const buffer = new ArrayBuffer(output.length)
+  new Uint8Array(buffer).set(output)
+  return new Blob([buffer], { type: 'application/zip' })
 }
 
 export async function exportGameAssets(
   model: ExportPackageModel,
-  runtime: AssetExportRuntime = defaultRuntime,
-  onPhase?: (phase: AssetExportPhase) => void,
+  options: ExportGameAssetsOptions = {},
 ): Promise<AssetExportResult> {
+  const runtime = options.runtime ?? defaultRuntime
+  options.onPhase?.('validating')
+  validateExportPackageModel(model)
   const plan = createAssetExportPlan(model)
-  onPhase?.('collecting')
-  const blobCache = new Map<string, Promise<Blob>>()
-  let incomplete = false
-
-  const loaded = await Promise.all(
-    plan.map(async (item) => ({
-      item,
-      frames: await Promise.all(
-        item.frames.map(async (planned): Promise<LoadedFrame> => {
-          try {
-            let pending = blobCache.get(planned.frame.imageUrl)
-            if (pending === undefined) {
-              pending = runtime.fetchFrame(planned.frame.imageUrl)
-              blobCache.set(planned.frame.imageUrl, pending)
-            }
-            const blob = await pending
-            const decoded = await runtime.decodeFrame(blob)
-            const extension = extensionForBlob(blob, planned.frame.imageUrl)
-            return {
-              ...planned,
-              blob,
-              decoded,
-              sourceFilename: `${String(planned.index).padStart(3, '0')}.${extension}`,
-            }
-          } catch {
-            incomplete = true
-            return { ...planned, blob: null, decoded: null, sourceFilename: planned.filename }
-          }
-        }),
-      ),
-    })),
-  )
+  const metadata = createMetadata(model, plan)
+
+  options.onPhase?.('collecting')
+  const loaded = await loadAllFrames(plan, model, runtime)
+  const root = packageRoot(model)
+  const entries: ZipEntry[] = []
 
-  onPhase?.('rendering')
-  const zipEntries: ZipEntry[] = []
   try {
-    for (const { item, frames } of loaded) {
-      const cellWidth = Math.max(1, ...frames.map((current) => current.decoded?.width ?? 0))
-      const cellHeight = Math.max(1, ...frames.map((current) => current.decoded?.height ?? 0))
-      const canvas = runtime.createCanvas(cellWidth * item.columns, cellHeight * item.rows)
-      const context = canvas.getContext('2d')
-      if (context === null) throw new Error('浏览器无法创建 Sprite Sheet')
-      context.clearRect(0, 0, canvas.width, canvas.height)
-
-      const animationFrames = frames.map((current) => {
-        const column = current.index % item.columns
-        const row = Math.floor(current.index / item.columns)
-        const width = current.decoded?.width ?? 0
-        const height = current.decoded?.height ?? 0
-        const offsetX = Math.floor((cellWidth - width) / 2)
-        const offsetY = Math.floor((cellHeight - height) / 2)
-        if (current.decoded !== null) {
-          context.drawImage(
-            current.decoded.source,
-            column * cellWidth + offsetX,
-            row * cellHeight + offsetY,
-          )
-        }
-        return {
-          index: current.index,
-          source: `frames/${current.sourceFilename}`,
-          available: current.blob !== null,
-          x: column * cellWidth + offsetX,
-          y: row * cellHeight + offsetY,
-          width,
-          height,
-          originalWidth: width,
-          originalHeight: height,
-          offsetX,
-          offsetY,
-          durationMs: current.frame.durationMs,
-          keyFrame: current.frame.keyFrame,
-          rootMotion: current.frame.rootMotion,
-        }
+    options.onPhase?.('rendering')
+    for (const current of loaded) {
+      for (const frame of current.frames) {
+        entries.push({ name: `${root}/${frame.relativeFile}`, data: frame.data })
+      }
+      entries.push({
+        name: `${root}/${current.item.atlasFile}`,
+        data: await bytes(await renderAtlas(current, model, runtime)),
+      })
+      entries.push({
+        name: `${root}/${current.item.previewFile}`,
+        data: await bytes(renderGif(current, model, runtime)),
       })
+    }
+
+    entries.push(
+      {
+        name: `${root}/meta.json`,
+        data: await bytes(JSON.stringify(metadata, null, 2)),
+      },
+      { name: `${root}/schema.json`, data: await bytes(EXPORT_PACKAGE_JSON_SCHEMA_TEXT) },
+      { name: `${root}/README.md`, data: await bytes(createReadme(model)) },
+    )
 
-      const sheet = await canvasPng(canvas)
-      zipEntries.push({ name: `${item.folder}/sprite-sheet.png`, data: await bytes(sheet) })
-      for (const current of frames) {
-        if (current.blob === null) continue
-        zipEntries.push({
-          name: `${item.folder}/frames/${current.sourceFilename}`,
-          data: await bytes(current.blob),
+    for (const target of options.targets ?? []) {
+      const targetId = safeSegment(target.id, 'target')
+      const files = await target.createFiles({ model, metadata, plan })
+      for (const [index, file] of files.entries()) {
+        entries.push({
+          name: `${root}/${safeTargetPath(targetId, file.path, index)}`,
+          data: await bytes(file.data),
         })
       }
-      zipEntries.push({
-        name: `${item.folder}/animation.json`,
-        data: await bytes(
-          JSON.stringify(
-            {
-              schemaVersion: 1,
-              action: {
-                id: item.action.id,
-                name: item.action.name,
-                type: item.action.type,
-              },
-              direction: item.sequence.direction,
-              fps: item.action.fps,
-              spriteSheet: {
-                file: 'sprite-sheet.png',
-                width: canvas.width,
-                height: canvas.height,
-                columns: item.columns,
-                rows: item.rows,
-                cellWidth,
-                cellHeight,
-              },
-              frames: animationFrames,
-            },
-            null,
-            2,
-          ),
-        ),
-      })
     }
   } finally {
-    loaded.forEach(({ frames }) => frames.forEach((current) => current.decoded?.close()))
+    loaded.forEach(({ frames }) => frames.forEach((frame) => frame.decoded.close()))
   }
 
-  onPhase?.('packing')
+  const duplicate = entries.find(
+    (entry, index) => entries.findIndex((item) => item.name === entry.name) !== index,
+  )
+  if (duplicate !== undefined) throw new Error(`package.files: 文件路径重复：${duplicate.name}`)
+
+  options.onPhase?.('packing')
   return {
-    blob: storedZip(zipEntries),
-    filename: `windup-${safeSegment(model.characterName, 'character')}-${safeSegment(model.outfitName, 'outfit')}.zip`,
-    incomplete,
+    blob: storedZip(entries),
+    filename: `windup-${root}.zip`,
   }
 }
diff --git a/frontend/src/features/export-package/cocos-target.ts b/frontend/src/features/export-package/cocos-target.ts
new file mode 100644
index 0000000..5085f2a
--- /dev/null
+++ b/frontend/src/features/export-package/cocos-target.ts
@@ -0,0 +1,15 @@
+import type { ExportAnchor } from './model'
+
+/**
+ * Issue #94 的 Cocos 原生文件格式仍等待真实 Creator 3.x 实测。
+ * 这里公开状态，避免页面或调用方把通用包误标成“Cocos 拖入即用包”。
+ */
+export const COCOS_TARGET_READINESS = {
+  ready: false,
+  reason: '等待真实 Cocos Creator 3.x 验证 .anim、.meta、UUID 与图集切分格式',
+} as const
+
+/** 通用层左上原点转为 Cocos Creator 左下原点；x 不变，y 上下翻转。 */
+export function toCocosAnchor(anchor: ExportAnchor): ExportAnchor {
+  return { x: anchor.x, y: 1 - anchor.y }
+}
diff --git a/frontend/src/features/export-package/contract.ts b/frontend/src/features/export-package/contract.ts
new file mode 100644
index 0000000..b7d5378
--- /dev/null
+++ b/frontend/src/features/export-package/contract.ts
@@ -0,0 +1,116 @@
+import exportSchemaText from './export-package.schema.json?raw'
+import type { ExportPackageModel } from './model'
+
+export const EXPORT_PACKAGE_SCHEMA_VERSION = '1.0.0'
+export const EXPORT_PACKAGE_JSON_SCHEMA_TEXT = exportSchemaText
+
+export interface GenericExportFrame {
+  index: number
+  file: string
+}
+
+export interface GenericExportAction {
+  name: string
+  fps: number
+  loop: boolean
+  frames: readonly GenericExportFrame[]
+  anchor: { x: number; y: number }
+  foot_y: number
+  atlas: {
+    file: string
+    cols: number
+    rows: number
+    cell: { w: number; h: number }
+  }
+  preview: string
+}
+
+export interface GenericExportMetadata {
+  schema_version: typeof EXPORT_PACKAGE_SCHEMA_VERSION
+  character: { id: string; name: string }
+  canvas: { w: number; h: number }
+  actions: readonly GenericExportAction[]
+  source: {
+    workflow_run_id: string
+    generation_ids: readonly string[]
+  }
+}
+
+function fail(field: string, reason: string): never {
+  throw new Error(`${field}: ${reason}`)
+}
+
+function requireText(field: string, value: string): void {
+  if (typeof value !== 'string' || value.trim().length === 0) fail(field, '必须是非空字符串')
+}
+
+function requirePositiveInteger(field: string, value: number): void {
+  if (!Number.isInteger(value) || value < 1) fail(field, '必须是大于 0 的整数')
+}
+
+function requireUnitNumber(field: string, value: number): void {
+  if (!Number.isFinite(value) || value < 0 || value > 1) fail(field, '必须是 0 到 1 的数值')
+}
+
+/**
+ * 在读取任何图片前完成结构与质量门禁。
+ * 报错路径使用 meta.json 对应字段名，方便调用方直接定位坏数据。
+ */
+export function validateExportPackageModel(model: ExportPackageModel): void {
+  requireText('character.id', model.characterId)
+  requireText('character.name', model.characterName)
+  requireText('outfit.id', model.outfitId)
+  requireText('outfit.name', model.outfitName)
+  requirePositiveInteger('canvas.w', model.canvas.width)
+  requirePositiveInteger('canvas.h', model.canvas.height)
+  requireText('source.workflow_run_id', model.source.workflowRunId)
+
+  if (model.source.generationIds.length === 0) {
+    fail('source.generation_ids', '至少需要一条生成记录')
+  }
+  const generationIds = new Set<string>()
+  model.source.generationIds.forEach((id, index) => {
+    requireText(`source.generation_ids[${index}]`, id)
+    if (generationIds.has(id)) fail(`source.generation_ids[${index}]`, '生成记录不能重复')
+    generationIds.add(id)
+  })
+
+  if (model.actions.length === 0) fail('actions', '至少需要一个动作')
+  model.actions.forEach((action, actionIndex) => {
+    const actionField = `actions[${actionIndex}]`
+    requireText(`${actionField}.name`, action.name)
+    requirePositiveInteger(`${actionField}.fps`, action.fps)
+    if (action.sequences.length === 0) fail(`${actionField}.sequences`, '至少需要一个动作方向')
+
+    action.sequences.forEach((sequence, sequenceIndex) => {
+      const sequenceField = `${actionField}.sequences[${sequenceIndex}]`
+      requireText(`${sequenceField}.direction`, sequence.direction)
+      requirePositiveInteger(`${sequenceField}.expectedFrameCount`, sequence.expectedFrameCount)
+      requireUnitNumber(`${sequenceField}.anchor.x`, sequence.anchor.x)
+      requireUnitNumber(`${sequenceField}.anchor.y`, sequence.anchor.y)
+      if (
+        !Number.isInteger(sequence.footY) ||
+        sequence.footY < 0 ||
+        sequence.footY > model.canvas.height
+      ) {
+        fail(`${sequenceField}.footY`, `必须是 0 到 ${model.canvas.height} 的整数像素值`)
+      }
+      if (sequence.qualityStatus !== 'passed') {
+        fail(`${sequenceField}.qualityStatus`, '质量检测未通过，禁止导出')
+      }
+      if (sequence.frames.length !== sequence.expectedFrameCount) {
+        fail(
+          `${sequenceField}.frames`,
+          `缺帧，期望 ${sequence.expectedFrameCount} 帧，实际 ${sequence.frames.length} 帧`,
+        )
+      }
+      sequence.frames.forEach((frame, frameIndex) => {
+        requireText(`${sequenceField}.frames[${frameIndex}].imageUrl`, frame.imageUrl)
+        requirePositiveInteger(
+          `${sequenceField}.frames[${frameIndex}].durationMs`,
+          frame.durationMs,
+        )
+      })
+    })
+  })
+}
diff --git a/frontend/src/features/export-package/export-package.schema.json b/frontend/src/features/export-package/export-package.schema.json
new file mode 100644
index 0000000..fb75d07
--- /dev/null
+++ b/frontend/src/features/export-package/export-package.schema.json
@@ -0,0 +1,100 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://windup.local/schemas/export-package-1.0.0.json",
+  "title": "Windup Generic Export Package",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "character", "canvas", "actions", "source"],
+  "properties": {
+    "schema_version": { "const": "1.0.0" },
+    "character": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 }
+      }
+    },
+    "canvas": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["w", "h"],
+      "properties": {
+        "w": { "type": "integer", "minimum": 1 },
+        "h": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "actions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "fps", "loop", "frames", "anchor", "foot_y", "atlas", "preview"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "fps": { "type": "integer", "minimum": 1 },
+          "loop": { "type": "boolean" },
+          "frames": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["index", "file"],
+              "properties": {
+                "index": { "type": "integer", "minimum": 0 },
+                "file": { "type": "string", "pattern": "^[^/]+_[0-9]{3}\\.png$" }
+              }
+            }
+          },
+          "anchor": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["x", "y"],
+            "properties": {
+              "x": { "type": "number", "minimum": 0, "maximum": 1 },
+              "y": { "type": "number", "minimum": 0, "maximum": 1 }
+            }
+          },
+          "foot_y": { "type": "integer", "minimum": 0 },
+          "atlas": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["file", "cols", "rows", "cell"],
+            "properties": {
+              "file": { "type": "string", "pattern": "^atlas/.+\\.png$" },
+              "cols": { "type": "integer", "minimum": 1 },
+              "rows": { "type": "integer", "minimum": 1 },
+              "cell": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["w", "h"],
+                "properties": {
+                  "w": { "type": "integer", "minimum": 1 },
+                  "h": { "type": "integer", "minimum": 1 }
+                }
+              }
+            }
+          },
+          "preview": { "type": "string", "pattern": "^preview/.+\\.gif$" }
+        }
+      }
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["workflow_run_id", "generation_ids"],
+      "properties": {
+        "workflow_run_id": { "type": "string", "minLength": 1 },
+        "generation_ids": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}
diff --git a/frontend/src/features/export-package/export-panel.test.tsx b/frontend/src/features/export-package/export-panel.test.tsx
index 56d07a4..fe37af0 100644
--- a/frontend/src/features/export-package/export-panel.test.tsx
+++ b/frontend/src/features/export-package/export-panel.test.tsx
@@ -2,7 +2,7 @@
 import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
-import type { ExportPackageModel as PlaytestPreviewModel } from './model'
+import type { ExportPackageModel } from './model'
 import { ExportPanel } from './export-panel'
 
 const model = {
@@ -12,6 +12,8 @@ const model = {
   outfitName: 'Explorer',
   characterTemplateUrl: null,
   baseFrameCount: 0,
+  canvas: { width: 32, height: 40 },
+  source: { workflowRunId: 'run-1', generationIds: ['generation-1'] },
   actions: [
     {
       id: 'walk-abcdef12',
@@ -21,6 +23,11 @@ const model = {
       sequences: [
         {
           direction: 'south',
+          expectedFrameCount: 1,
+          loop: true,
+          anchor: { x: 0.5, y: 0.9 },
+          footY: 36,
+          qualityStatus: 'passed',
           frames: [
             {
               imageUrl: '/walk.png',
@@ -33,7 +40,7 @@ const model = {
       ],
     },
   ],
-} satisfies PlaytestPreviewModel
+} satisfies ExportPackageModel
 
 afterEach(() => {
   cleanup()
@@ -41,30 +48,26 @@ afterEach(() => {
 })
 
 describe('ExportPanel', () => {
-  it('warns about current quality issues without blocking export', () => {
+  it('质量问题会阻止导出，而不是只显示警告', () => {
     render(<ExportPanel model={model} qualityIssueCount={3} />)
 
-    expect(screen.getByText('当前核验存在 3 项质量问题，仍可导出')).toBeTruthy()
+    expect(screen.getByText('当前有 3 项质量问题，全部通过后才能导出')).toBeTruthy()
     expect(
       (screen.getByRole('button', { name: '导出游戏资产包' }) as HTMLButtonElement).disabled,
-    ).toBe(false)
+    ).toBe(true)
   })
 
-  it('shows progress, prevents duplicate export, downloads and revokes the object url', async () => {
-    let resolveExport: (value: {
-      blob: Blob
-      filename: string
-      incomplete: boolean
-    }) => void = () => {
+  it('显示进度、阻止重复点击、下载后释放临时地址', async () => {
+    let resolveExport: (value: { blob: Blob; filename: string }) => void = () => {
       throw new Error('export promise was not initialized')
     }
     const exporter = vi.fn(
       (
-        _model: PlaytestPreviewModel,
-        onPhase?: (phase: 'collecting' | 'rendering' | 'packing') => void,
+        _model: ExportPackageModel,
+        onPhase?: (phase: 'validating' | 'collecting' | 'rendering' | 'packing') => void,
       ) => {
         onPhase?.('rendering')
-        return new Promise<{ blob: Blob; filename: string; incomplete: boolean }>((resolve) => {
+        return new Promise<{ blob: Blob; filename: string }>((resolve) => {
           resolveExport = resolve
         })
       },
@@ -84,8 +87,7 @@ describe('ExportPanel', () => {
 
     resolveExport({
       blob: new Blob(['zip'], { type: 'application/zip' }),
-      filename: 'windup-Aster-Explorer.zip',
-      incomplete: false,
+      filename: 'windup-Aster-character-1.zip',
     })
     await waitFor(() => expect(screen.getByText('下载完成')).toBeTruthy())
     expect(createObjectURL).toHaveBeenCalledTimes(1)
@@ -94,14 +96,13 @@ describe('ExportPanel', () => {
     click.mockRestore()
   })
 
-  it('warns for incomplete packages and allows retry after failure', async () => {
+  it('展示具体错误字段，并允许修复后重试', async () => {
     const exporter = vi
       .fn()
-      .mockRejectedValueOnce(new Error('pack failed'))
+      .mockRejectedValueOnce(new Error('actions[0].frames: 缺帧'))
       .mockResolvedValueOnce({
         blob: new Blob(['zip'], { type: 'application/zip' }),
-        filename: 'windup-Aster-Explorer.zip',
-        incomplete: true,
+        filename: 'windup-Aster-character-1.zip',
       })
     Object.defineProperty(URL, 'createObjectURL', {
       configurable: true,
@@ -112,9 +113,9 @@ describe('ExportPanel', () => {
 
     render(<ExportPanel model={model} exporter={exporter} />)
     fireEvent.click(screen.getByRole('button', { name: '导出游戏资产包' }))
-    await waitFor(() => expect(screen.getByText('导出失败，可重试')).toBeTruthy())
+    await waitFor(() => expect(screen.getByText('导出失败：actions[0].frames: 缺帧')).toBeTruthy())
     fireEvent.click(screen.getByRole('button', { name: '重新导出' }))
-    await waitFor(() => expect(screen.getByText('导出不完整，缺失图片已保留透明占位')).toBeTruthy())
+    await waitFor(() => expect(screen.getByText('下载完成')).toBeTruthy())
     expect(exporter).toHaveBeenCalledTimes(2)
   })
 })
diff --git a/frontend/src/features/export-package/export-panel.tsx b/frontend/src/features/export-package/export-panel.tsx
index cea311a..76be6b0 100644
--- a/frontend/src/features/export-package/export-panel.tsx
+++ b/frontend/src/features/export-package/export-panel.tsx
@@ -22,17 +22,17 @@ export interface ExportPanelProps {
 type ExportState =
   | { status: 'idle' }
   | { status: 'working'; phase: AssetExportPhase }
-  | { status: 'success'; incomplete: boolean }
-  | { status: 'failure' }
+  | { status: 'success' }
+  | { status: 'failure'; message: string }
 
 const PHASE_LABELS: Readonly<Record<AssetExportPhase, string>> = {
+  validating: '正在检查导出条件',
   collecting: '正在整理素材',
   rendering: '正在生成图片',
   packing: '正在打包',
 }
 
-const defaultExporter: AssetExporter = (model, onPhase) =>
-  exportGameAssets(model, undefined, onPhase)
+const defaultExporter: AssetExporter = (model, onPhase) => exportGameAssets(model, { onPhase })
 
 export function ExportPanel({
   model,
@@ -45,7 +45,7 @@ export function ExportPanel({
 
   const startExport = async () => {
     if (working) return
-    setState({ status: 'working', phase: 'collecting' })
+    setState({ status: 'working', phase: 'validating' })
     try {
       const result = await exporter(model, (phase) => setState({ status: 'working', phase }))
       const url = URL.createObjectURL(result.blob)
@@ -54,9 +54,12 @@ export function ExportPanel({
       anchor.download = result.filename
       anchor.click()
       URL.revokeObjectURL(url)
-      setState({ status: 'success', incomplete: result.incomplete })
-    } catch {
-      setState({ status: 'failure' })
+      setState({ status: 'success' })
+    } catch (error) {
+      setState({
+        status: 'failure',
+        message: error instanceof Error ? error.message : '未知错误',
+      })
     }
   }
 
@@ -69,7 +72,7 @@ export function ExportPanel({
       <header>
         <p className="text-[10px] font-semibold tracking-[0.18em] text-slate-400">GAME ASSETS</p>
         <h2 className="mt-1 text-sm font-semibold text-slate-900">资产导出</h2>
-        <p className="mt-1 text-[11px] text-slate-500">逐帧原图、Sprite Sheet 与动画 JSON</p>
+        <p className="mt-1 text-[11px] text-slate-500">透明 PNG、图集、GIF 与通用元数据</p>
       </header>
 
       <dl className="grid grid-cols-[auto_1fr] gap-x-3 gap-y-2 text-xs">
@@ -84,8 +87,8 @@ export function ExportPanel({
       </dl>
 
       {qualityIssueCount > 0 ? (
-        <p className="rounded-lg bg-amber-50 px-3 py-2 text-xs text-amber-900">
-          当前核验存在 {qualityIssueCount} 项质量问题，仍可导出
+        <p role="alert" className="rounded-lg bg-rose-50 px-3 py-2 text-xs text-rose-800">
+          当前有 {qualityIssueCount} 项质量问题，全部通过后才能导出
         </p>
       ) : null}
 
@@ -95,22 +98,15 @@ export function ExportPanel({
         </p>
       ) : state.status === 'failure' ? (
         <p role="alert" className="rounded-lg bg-rose-50 px-3 py-2 text-xs text-rose-800">
-          导出失败，可重试
+          导出失败：{state.message}
         </p>
       ) : state.status === 'success' ? (
-        <div className="space-y-2">
-          <p className="rounded-lg bg-emerald-50 px-3 py-2 text-xs text-emerald-800">下载完成</p>
-          {state.incomplete ? (
-            <p className="rounded-lg bg-amber-50 px-3 py-2 text-xs text-amber-900">
-              导出不完整，缺失图片已保留透明占位
-            </p>
-          ) : null}
-        </div>
+        <p className="rounded-lg bg-emerald-50 px-3 py-2 text-xs text-emerald-800">下载完成</p>
       ) : null}
 
       <button
         type="button"
-        disabled={working || plan.length === 0}
+        disabled={working || plan.length === 0 || qualityIssueCount > 0}
         onClick={() => void startExport()}
         className="w-full rounded-lg bg-orange-500 px-3 py-2 text-xs font-semibold text-white hover:bg-orange-600 disabled:cursor-not-allowed disabled:opacity-40"
       >
diff --git a/frontend/src/features/export-package/gifenc.d.ts b/frontend/src/features/export-package/gifenc.d.ts
new file mode 100644
index 0000000..48467e8
--- /dev/null
+++ b/frontend/src/features/export-package/gifenc.d.ts
@@ -0,0 +1,33 @@
+declare module 'gifenc' {
+  export type GifPalette = number[][]
+
+  export interface GifFrameOptions {
+    palette?: GifPalette
+    transparent?: boolean
+    transparentIndex?: number
+    delay?: number
+    repeat?: number
+    dispose?: number
+  }
+
+  export interface GifEncoderInstance {
+    writeFrame(index: Uint8Array, width: number, height: number, options?: GifFrameOptions): void
+    finish(): void
+    bytes(): Uint8Array
+  }
+
+  export function GIFEncoder(options?: {
+    auto?: boolean
+    initialCapacity?: number
+  }): GifEncoderInstance
+  export function quantize(
+    rgba: Uint8Array | Uint8ClampedArray,
+    maxColors: number,
+    options?: { format?: 'rgb565' | 'rgb444' | 'rgba4444'; oneBitAlpha?: boolean | number },
+  ): GifPalette
+  export function applyPalette(
+    rgba: Uint8Array | Uint8ClampedArray,
+    palette: GifPalette,
+    format?: 'rgb565' | 'rgb444' | 'rgba4444',
+  ): Uint8Array
+}
diff --git a/frontend/src/features/export-package/index.ts b/frontend/src/features/export-package/index.ts
index 43dc84d..82f2ab3 100644
--- a/frontend/src/features/export-package/index.ts
+++ b/frontend/src/features/export-package/index.ts
@@ -1,10 +1,29 @@
 /** 将预览台当前角色资产打包下载；与发布到资产库是两件事。 */
 export { ExportPanel } from './export-panel'
-export type { ExportPackageModel } from './model'
+export type {
+  ExportAction,
+  ExportAnchor,
+  ExportFrame,
+  ExportPackageModel,
+  ExportQualityStatus,
+  ExportSequence,
+  ExportSourceReference,
+} from './model'
+export {
+  EXPORT_PACKAGE_JSON_SCHEMA_TEXT,
+  EXPORT_PACKAGE_SCHEMA_VERSION,
+  validateExportPackageModel,
+  type GenericExportMetadata,
+} from './contract'
+export { COCOS_TARGET_READINESS, toCocosAnchor } from './cocos-target'
 export {
   createAssetExportPlan,
   exportGameAssets,
+  type AssetExportTarget,
+  type AssetExportTargetContext,
+  type AssetExportTargetFile,
   type AssetExportPhase,
   type AssetExportResult,
   type AssetExportRuntime,
+  type ExportGameAssetsOptions,
 } from './asset-export'
diff --git a/frontend/src/features/export-package/model.ts b/frontend/src/features/export-package/model.ts
index 28577bd..f954a3d 100644
--- a/frontend/src/features/export-package/model.ts
+++ b/frontend/src/features/export-package/model.ts
@@ -1,6 +1,9 @@
 import type { ActionType, Frame } from '@/entities'
 
-/** 导出功能只依赖这份只读模型，不依赖 Playtest 页面内部实现。 */
+/**
+ * 导出模块只读取这份模型，不直接读取 Playtest 页面状态。
+ * 页面或后端适配器负责把当前角色、动作和生成记录整理成该模型。
+ */
 export interface ExportFrame {
   imageUrl: string
   durationMs: number
@@ -8,8 +11,24 @@ export interface ExportFrame {
   keyFrame: boolean
 }
 
+/** 通用契约使用左上角为原点、y 轴向下的 0-1 归一化坐标。 */
+export interface ExportAnchor {
+  x: number
+  y: number
+}
+
+export type ExportQualityStatus = 'passed' | 'pending' | 'failed'
+
 export interface ExportSequence {
   direction: string
+  /** 后端声明的完整帧数；不能用 frames.length 代替，否则无法发现缺帧。 */
+  expectedFrameCount: number
+  loop: boolean
+  anchor: ExportAnchor
+  /** 脚底线距离画布顶部的像素值。 */
+  footY: number
+  /** 只有 passed 的动作序列可以进入正式导出包。 */
+  qualityStatus: ExportQualityStatus
   frames: readonly ExportFrame[]
 }
 
@@ -21,6 +40,11 @@ export interface ExportAction {
   sequences: readonly ExportSequence[]
 }
 
+export interface ExportSourceReference {
+  workflowRunId: string
+  generationIds: readonly string[]
+}
+
 export interface ExportPackageModel {
   characterId: string
   characterName: string
@@ -28,5 +52,12 @@ export interface ExportPackageModel {
   outfitName: string
   characterTemplateUrl: string | null
   baseFrameCount: number
+  /** 同一导出包内所有帧必须使用相同画布尺寸。 */
+  canvas: {
+    width: number
+    height: number
+  }
+  /** 生成链路引用，用于从导出物追溯到 WorkflowRun 与生成任务。 */
+  source: ExportSourceReference
   actions: readonly ExportAction[]
 }