@gthanks/moviespec 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# MovieSpec
+
+MovieSpec 是一套面向 AI 图片/视频生成的「规范先行」工作方式：先把世界观、角色、视觉风格、镜头语言与分镜结构写成可机读/可复用的规范文档，再从这些规范稳定编译出 Prompt 与参数，并将每次生成的输入与输出写入 manifest 以便复现与排查一致性漂移。
+
+## 目录结构
+
+- `bin/`：CLI 入口
+- `schema/`：可机读 schema（类型、路径、依赖、编译规则）
+- `templates/`：各类规范文档模板（Markdown + YAML front matter）
+
+## 安装
+
+如果你想在全局使用该命令，可以通过 NPM 安装：
+
+```bash
+npm install -g @gthanks/moviespec@latest
+```
+
+## 用户项目最小目录结构（与工具仓库分离）
+
+MovieSpec 工具仓库是本目录（`moviespec/`）。用户实际制作项目建议使用独立工作目录（任意路径），并满足最小结构：
+
+- `config.yaml`
+- `specs/`
+- `storyboard/`
+- `prompts/`（由 `compile-prompts` 生成）
+- `output/`（由 `generate` 生成）
+
+你可以在用户项目目录下执行：
+
+```bash
+moviespec init
+```
+
+CLI 将按 `schema/moviespec.schema.yaml` 的默认路径读取与写入上述目录。
+
+## 最小命令集（v1）
+
+- `moviespec init`
+- `moviespec list types`
+- `moviespec new <type> <name>`
+- `moviespec compile-prompts --shots <file>`
+- `moviespec validate` / `moviespec check`
+- `moviespec generate image --shot <id>`（stub）
+- `moviespec generate sequence --shots <file>`（stub）

package/bin/moviespec.js

@@ -0,0 +1,525 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import chalk from 'chalk';
+import { Command } from 'commander';
+import fg from 'fast-glob';
+import YAML from 'yaml';
+
+function toPosix(p) {
+  return p.split(path.sep).join(path.posix.sep);
+}
+
+async function pathExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureDir(p) {
+  await fs.mkdir(p, { recursive: true });
+}
+
+async function readYamlFile(filePath) {
+  const raw = await fs.readFile(filePath, 'utf8');
+  return YAML.parse(raw);
+}
+
+async function writeYamlFile(filePath, data) {
+  const raw = YAML.stringify(data);
+  await fs.writeFile(filePath, raw, 'utf8');
+}
+
+async function readJsonFile(filePath) {
+  const raw = await fs.readFile(filePath, 'utf8');
+  return JSON.parse(raw);
+}
+
+async function writeJsonFile(filePath, data) {
+  const raw = JSON.stringify(data, null, 2) + '\n';
+  await fs.writeFile(filePath, raw, 'utf8');
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((v) => stableStringify(v)).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
+}
+
+async function sha256Hex(str) {
+  const crypto = await import('node:crypto');
+  return crypto.createHash('sha256').update(str, 'utf8').digest('hex');
+}
+
+async function loadMovieSpecSchema() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const schemaPath = path.resolve(here, '..', 'schema', 'moviespec.schema.yaml');
+  return readYamlFile(schemaPath);
+}
+
+function resolveProjectRoot(projectRoot) {
+  return path.resolve(projectRoot ?? process.cwd());
+}
+
+async function readProjectConfig(projectRoot, schema) {
+  const configPath = path.join(projectRoot, schema.project?.config ?? 'config.yaml');
+  if (!(await pathExists(configPath))) return null;
+  return readYamlFile(configPath);
+}
+
+async function listTypes(schema) {
+  return Object.keys(schema.types ?? {});
+}
+
+function defaultTypePath(schema, typeId) {
+  const type = schema.types?.[typeId];
+  if (!type) throw new Error(`Unknown type: ${typeId}`);
+  return type.defaultPath;
+}
+
+async function cmdInit(projectRoot) {
+  const schema = await loadMovieSpecSchema();
+  const root = resolveProjectRoot(projectRoot);
+
+  const dirs = [
+    schema.project?.specsDir ?? 'specs',
+    schema.project?.storyboardDir ?? 'storyboard',
+    schema.project?.promptsDir ?? 'prompts',
+    schema.project?.outputDir ?? 'output',
+    path.join(schema.project?.outputDir ?? 'output', schema.project?.manifestsDir ?? 'manifests'),
+    path.join(schema.project?.outputDir ?? 'output', schema.project?.shotsDir ?? 'shots')
+  ];
+
+  for (const d of dirs) {
+    await ensureDir(path.join(root, d));
+  }
+
+  const configPath = path.join(root, schema.project?.config ?? 'config.yaml');
+  if (!(await pathExists(configPath))) {
+    const defaultConfig = {
+      moviespec_version: schema.version,
+      media: {
+        resolution: '1920x1080',
+        aspect_ratio: '16:9',
+        fps: 24
+      },
+      lora: {
+        characters: {},
+        styles: {}
+      },
+      backend: {
+        id: 'stub'
+      }
+    };
+    await writeYamlFile(configPath, defaultConfig);
+  }
+
+  console.log(chalk.green(`Initialized MovieSpec project at: ${root}`));
+
+  try {
+    const prompts = await import('@inquirer/prompts');
+    const selectedAgents = await prompts.checkbox({
+      message: 'Select AI agents to configure for this MovieSpec project:',
+      choices: [
+        { name: 'Cursor', value: 'cursor' },
+        { name: 'Windsurf', value: 'windsurf' },
+        { name: 'Antigravity', value: 'antigravity' }
+      ]
+    });
+
+    if (selectedAgents.length > 0) {
+      const here = path.dirname(fileURLToPath(import.meta.url));
+      const templatesDir = path.resolve(here, '..', 'templates', 'agents');
+      
+      const agentFiles = {
+        cursor: '.cursorrules',
+        windsurf: '.windsurfrules',
+        antigravity: 'AGENTS.md'
+      };
+
+      for (const agent of selectedAgents) {
+        const sourceFile = path.join(templatesDir, `${agent}.md`);
+        const targetFile = path.join(root, agentFiles[agent]);
+        
+        if (await pathExists(sourceFile)) {
+          const content = await fs.readFile(sourceFile, 'utf8');
+          await fs.writeFile(targetFile, content, 'utf8');
+          console.log(chalk.blue(`Configured rules for ${agent}: ${agentFiles[agent]}`));
+        } else {
+          console.log(chalk.yellow(`Warning: Template for ${agent} not found at ${sourceFile}`));
+        }
+      }
+    }
+  } catch (err) {
+    // If the prompt is cancelled or in non-interactive environment, just ignore safely
+    if (err.name !== 'ExitPromptError') {
+      console.log(chalk.yellow(`Could not run interactive agent setup: ${err.message}`));
+    }
+  }
+}
+
+async function cmdListTypes() {
+  const schema = await loadMovieSpecSchema();
+  const types = await listTypes(schema);
+  for (const t of types) {
+    const desc = schema.types?.[t]?.description ?? '';
+    console.log(`${t}${desc ? `\t${desc}` : ''}`);
+  }
+}
+
+async function cmdNew(typeId, name, { projectRoot }) {
+  const schema = await loadMovieSpecSchema();
+  const root = resolveProjectRoot(projectRoot);
+
+  const templateRel = schema.types?.[typeId]?.template;
+  if (!templateRel) throw new Error(`Unknown type or missing template: ${typeId}`);
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const templateAbs = path.resolve(here, '..', templateRel);
+
+  const targetRel = defaultTypePath(schema, typeId);
+  const targetDir = path.join(root, targetRel);
+  await ensureDir(targetDir);
+
+  const filename = `${name}.md`;
+  const targetPath = path.join(targetDir, filename);
+  if (await pathExists(targetPath)) throw new Error(`File already exists: ${targetPath}`);
+
+  const template = await fs.readFile(templateAbs, 'utf8');
+  const rendered = template
+    .replaceAll('{{name}}', name)
+    .replaceAll('{{type}}', typeId);
+
+  await fs.writeFile(targetPath, rendered, 'utf8');
+  console.log(chalk.green(`Created ${typeId}: ${toPosix(path.relative(root, targetPath))}`));
+}
+
+async function readAllSpecInputs(projectRoot, schema) {
+  const root = resolveProjectRoot(projectRoot);
+  const specsRoot = path.join(root, schema.project?.specsDir ?? 'specs');
+
+  const inputs = {};
+  for (const typeId of await listTypes(schema)) {
+    const rel = defaultTypePath(schema, typeId);
+    const abs = path.join(root, rel);
+    const files = await fg(['**/*.md', '**/*.yaml', '**/*.yml', '**/*.json'], { cwd: abs, dot: false, onlyFiles: true, suppressErrors: true });
+    inputs[typeId] = {
+      baseDir: abs,
+      files: files.map((f) => path.join(abs, f))
+    };
+  }
+
+  const storyboardDir = path.join(root, schema.project?.storyboardDir ?? 'storyboard');
+  const storyboardFiles = await fg(['**/*.yaml', '**/*.yml', '**/*.json'], { cwd: storyboardDir, dot: false, onlyFiles: true, suppressErrors: true });
+
+  return {
+    root,
+    specsRoot,
+    storyboardDir,
+    storyboardFiles: storyboardFiles.map((f) => path.join(storyboardDir, f)),
+    inputs
+  };
+}
+
+async function readStoryboardShots(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.json') return readJsonFile(filePath);
+  return readYamlFile(filePath);
+}
+
+function normalizeShots(data) {
+  if (!data) return [];
+  if (Array.isArray(data)) return data;
+  if (Array.isArray(data.shots)) return data.shots;
+  return [];
+}
+
+function buildPromptParts({ shot, config }) {
+  const parts = [];
+  if (shot?.prompt?.positive) parts.push(String(shot.prompt.positive));
+  if (shot?.action) parts.push(String(shot.action));
+  if (shot?.scene) parts.push(String(shot.scene));
+  if (shot?.composition) parts.push(String(shot.composition));
+
+  if (config?.media?.resolution) parts.push(`resolution:${config.media.resolution}`);
+  if (config?.media?.aspect_ratio) parts.push(`aspect_ratio:${config.media.aspect_ratio}`);
+  if (typeof config?.media?.fps !== 'undefined') parts.push(`fps:${config.media.fps}`);
+
+  return parts.filter(Boolean);
+}
+
+async function cmdCompilePrompts({ shots, projectRoot }) {
+  const schema = await loadMovieSpecSchema();
+  const root = resolveProjectRoot(projectRoot);
+  const config = await readProjectConfig(root, schema);
+  if (!config) throw new Error(`Missing config file: ${path.join(root, schema.project?.config ?? 'config.yaml')}`);
+
+  const storyboardPath = path.resolve(root, shots);
+  const storyboardData = await readStoryboardShots(storyboardPath);
+  const shotList = normalizeShots(storyboardData);
+
+  const promptsDir = path.join(root, schema.project?.promptsDir ?? 'prompts');
+  await ensureDir(promptsDir);
+
+  const context = await readAllSpecInputs(root, schema);
+  const depFingerprints = {};
+  for (const [typeId, info] of Object.entries(context.inputs)) {
+    const hashes = [];
+    for (const f of info.files) {
+      const raw = await fs.readFile(f, 'utf8');
+      hashes.push(await sha256Hex(raw));
+    }
+    depFingerprints[typeId] = await sha256Hex(stableStringify(hashes.sort()));
+  }
+
+  const compiled = [];
+  for (const s of shotList) {
+    const shotId = s.id ?? s.shot_id;
+    if (!shotId) throw new Error('Each shot must have an id (id or shot_id)');
+
+    const mergedMedia = {
+      resolution: s.media?.resolution ?? config.media?.resolution,
+      aspect_ratio: s.media?.aspect_ratio ?? config.media?.aspect_ratio,
+      fps: typeof s.media?.fps !== 'undefined' ? s.media.fps : config.media?.fps
+    };
+
+    const promptParts = buildPromptParts({ shot: s, config: { ...config, media: mergedMedia } });
+    const positive = promptParts.join(', ');
+    const negative = (s.prompt?.negative ?? '').toString();
+
+    const out = {
+      shot_id: shotId,
+      prompt: {
+        positive,
+        negative
+      },
+      media: mergedMedia,
+      deps: depFingerprints
+    };
+
+    compiled.push(out);
+    await writeJsonFile(path.join(promptsDir, `${shotId}.prompt.json`), out);
+  }
+
+  console.log(chalk.green(`Compiled ${compiled.length} shot prompt(s) to ${toPosix(path.relative(root, promptsDir))}`));
+}
+
+async function cmdValidate({ projectRoot, shots }) {
+  const schema = await loadMovieSpecSchema();
+  const root = resolveProjectRoot(projectRoot);
+
+  const configPath = path.join(root, schema.project?.config ?? 'config.yaml');
+  if (!(await pathExists(configPath))) throw new Error(`Missing config file: ${configPath}`);
+
+  const config = await readProjectConfig(root, schema);
+  if (!config?.moviespec_version) throw new Error('config.yaml missing moviespec_version');
+
+  const context = await readAllSpecInputs(root, schema);
+
+  const currentDepFingerprints = {};
+  for (const [typeId, info] of Object.entries(context.inputs)) {
+    const hashes = [];
+    for (const f of info.files) {
+      const raw = await fs.readFile(f, 'utf8');
+      hashes.push(await sha256Hex(raw));
+    }
+    currentDepFingerprints[typeId] = await sha256Hex(stableStringify(hashes.sort()));
+  }
+
+  const storyboardPath = shots ? path.resolve(root, shots) : null;
+  if (storyboardPath) {
+    if (!(await pathExists(storyboardPath))) throw new Error(`Shots file not found: ${storyboardPath}`);
+
+    const data = await readStoryboardShots(storyboardPath);
+    const shotList = normalizeShots(data);
+
+    const characterDirRel = defaultTypePath(schema, 'characters');
+    const characterDirAbs = path.join(root, characterDirRel);
+    const characterFiles = await fg(['**/*.md', '**/*.yaml', '**/*.yml', '**/*.json'], { cwd: characterDirAbs, onlyFiles: true, suppressErrors: true });
+    const characterNames = new Set(characterFiles.map((f) => path.parse(f).name));
+
+    for (const s of shotList) {
+      const shotId = s.id ?? s.shot_id ?? '(unknown)';
+      const roles = Array.isArray(s.characters) ? s.characters : [];
+      for (const r of roles) {
+        if (!characterNames.has(String(r))) {
+          throw new Error(`Storyboard shot ${shotId} references missing character: ${r}`);
+        }
+      }
+    }
+
+    const promptsDir = path.join(root, schema.project?.promptsDir ?? 'prompts');
+    const dirty = [];
+    for (const s of shotList) {
+      const shotId = s.id ?? s.shot_id;
+      if (!shotId) continue;
+      const promptPath = path.join(promptsDir, `${shotId}.prompt.json`);
+      if (!(await pathExists(promptPath))) continue;
+      const compiled = await readJsonFile(promptPath);
+      const previousDeps = compiled?.deps ?? {};
+      if (stableStringify(previousDeps) !== stableStringify(currentDepFingerprints)) {
+        dirty.push(String(shotId));
+      }
+    }
+    if (dirty.length > 0) {
+      console.log(chalk.yellow(`Out-of-sync/Dirty shots detected: ${dirty.join(', ')}`));
+      console.log(chalk.yellow('Re-run compile-prompts (and re-generate if needed).'));
+    }
+  }
+
+  const requiredDirs = [
+    schema.project?.specsDir ?? 'specs',
+    schema.project?.storyboardDir ?? 'storyboard',
+    schema.project?.promptsDir ?? 'prompts',
+    schema.project?.outputDir ?? 'output'
+  ];
+
+  for (const d of requiredDirs) {
+    if (!(await pathExists(path.join(root, d)))) {
+      throw new Error(`Missing required directory: ${path.join(root, d)}`);
+    }
+  }
+
+  console.log(chalk.green('Validation passed (dry-run).'));
+}
+
+async function cmdGenerateImage({ projectRoot, shot }) {
+  const schema = await loadMovieSpecSchema();
+  const root = resolveProjectRoot(projectRoot);
+  const config = await readProjectConfig(root, schema);
+  if (!config) throw new Error('Missing config.yaml');
+
+  const promptsDir = path.join(root, schema.project?.promptsDir ?? 'prompts');
+  const promptPath = path.join(promptsDir, `${shot}.prompt.json`);
+  if (!(await pathExists(promptPath))) {
+    throw new Error(`Missing compiled prompt for shot ${shot}. Run compile-prompts first.`);
+  }
+
+  const compiled = await readJsonFile(promptPath);
+
+  const outputRoot = path.join(root, schema.project?.outputDir ?? 'output');
+  const shotsDir = path.join(outputRoot, schema.project?.shotsDir ?? 'shots');
+  await ensureDir(shotsDir);
+
+  const runId = new Date().toISOString().replace(/[:.]/g, '-');
+  const shotRunDir = path.join(shotsDir, String(shot), `run_${runId}`);
+  await ensureDir(shotRunDir);
+
+  const manifest = {
+    shot_id: shot,
+    backend: config.backend ?? { id: 'stub' },
+    tool: { id: 'moviespec', version: '0.1.0' },
+    created_at: new Date().toISOString(),
+    prompt: compiled.prompt,
+    media: compiled.media,
+    deps: compiled.deps,
+    lora: config.lora ?? { characters: {}, styles: {} },
+    outputs: {
+      placeholder: 'stub'
+    }
+  };
+
+  await writeJsonFile(path.join(shotRunDir, 'manifest.json'), manifest);
+  await fs.writeFile(path.join(shotRunDir, 'OUTPUT_STUB.txt'), 'stub output\n', 'utf8');
+
+  console.log(chalk.green(`Generated stub output for shot ${shot}: ${toPosix(path.relative(root, shotRunDir))}`));
+}
+
+async function cmdGenerateSequence({ projectRoot, shots }) {
+  const schema = await loadMovieSpecSchema();
+  const root = resolveProjectRoot(projectRoot);
+  const storyboardPath = path.resolve(root, shots);
+  if (!(await pathExists(storyboardPath))) throw new Error(`Shots file not found: ${storyboardPath}`);
+
+  const data = await readStoryboardShots(storyboardPath);
+  const shotList = normalizeShots(data);
+  let count = 0;
+  for (const s of shotList) {
+    const shotId = s.id ?? s.shot_id;
+    if (!shotId) continue;
+    await cmdGenerateImage({ projectRoot: root, shot: String(shotId) });
+    count += 1;
+  }
+  console.log(chalk.green(`Generated stub sequence for ${count} shot(s).`));
+}
+
+const program = new Command();
+program.name('moviespec').description('MovieSpec CLI').version('0.1.0');
+
+program
+  .command('init')
+  .option('-C, --project-root <path>', 'Project root (default: cwd)')
+  .action(async (opts) => {
+    await cmdInit(opts.projectRoot);
+  });
+
+program
+  .command('list')
+  .description('List resources')
+  .command('types')
+  .action(async () => {
+    await cmdListTypes();
+  });
+
+program
+  .command('new')
+  .argument('<type>', 'Type id')
+  .argument('<name>', 'Document name')
+  .option('-C, --project-root <path>', 'Project root (default: cwd)')
+  .action(async (type, name, opts) => {
+    await cmdNew(type, name, { projectRoot: opts.projectRoot });
+  });
+
+program
+  .command('compile-prompts')
+  .requiredOption('--shots <file>', 'Storyboard shots file (yaml/json)')
+  .option('-C, --project-root <path>', 'Project root (default: cwd)')
+  .action(async (opts) => {
+    await cmdCompilePrompts({ shots: opts.shots, projectRoot: opts.projectRoot });
+  });
+
+program
+  .command('validate')
+  .option('--shots <file>', 'Storyboard shots file (optional)')
+  .option('-C, --project-root <path>', 'Project root (default: cwd)')
+  .action(async (opts) => {
+    await cmdValidate({ projectRoot: opts.projectRoot, shots: opts.shots });
+  });
+
+program
+  .command('check')
+  .option('--shots <file>', 'Storyboard shots file (optional)')
+  .option('-C, --project-root <path>', 'Project root (default: cwd)')
+  .action(async (opts) => {
+    await cmdValidate({ projectRoot: opts.projectRoot, shots: opts.shots });
+  });
+
+const generate = program.command('generate').description('Generate assets');
+
+generate
+  .command('image')
+  .requiredOption('--shot <id>', 'Shot id')
+  .option('-C, --project-root <path>', 'Project root (default: cwd)')
+  .action(async (opts) => {
+    await cmdGenerateImage({ projectRoot: opts.projectRoot, shot: opts.shot });
+  });
+
+generate
+  .command('sequence')
+  .requiredOption('--shots <file>', 'Storyboard shots file (yaml/json)')
+  .option('-C, --project-root <path>', 'Project root (default: cwd)')
+  .action(async (opts) => {
+    await cmdGenerateSequence({ projectRoot: opts.projectRoot, shots: opts.shots });
+  });
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(chalk.red(err?.message ?? String(err)));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@gthanks/moviespec",
+  "version": "0.1.0",
+  "description": "Specification-driven consistency framework for AI image and video generation",
+  "author": "gthanks",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "schema",
+    "templates"
+  ],
+  "type": "module",
+  "bin": {
+    "moviespec": "./bin/moviespec.js"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "chalk": "^5.5.0",
+    "commander": "^14.0.0",
+    "fast-glob": "^3.3.3",
+    "yaml": "^2.8.2"
+  }
+}

package/schema/manifest.schema.yaml

@@ -0,0 +1,55 @@
+version: 0.1.0
+id: manifest
+format: json
+required:
+  - shot_id
+  - created_at
+  - backend
+  - tool
+  - prompt
+  - media
+  - deps
+properties:
+  shot_id:
+    type: string
+  created_at:
+    type: string
+  backend:
+    type: object
+    required: [id]
+    properties:
+      id: { type: string }
+      params: { type: object }
+  tool:
+    type: object
+    required: [id, version]
+    properties:
+      id: { type: string }
+      version: { type: string }
+  prompt:
+    type: object
+    required: [positive, negative]
+    properties:
+      positive: { type: string }
+      negative: { type: string }
+  media:
+    type: object
+    properties:
+      resolution: { type: string }
+      aspect_ratio: { type: string }
+      fps: { type: number }
+  deps:
+    type: object
+  lora:
+    type: object
+    properties:
+      characters: { type: object }
+      styles: { type: object }
+  sources:
+    type: object
+    properties:
+      compiled_prompt: { type: string }
+      storyboard: { type: string }
+      specs: { type: object }
+  outputs:
+    type: object

package/schema/moviespec.schema.yaml

@@ -0,0 +1,56 @@
+version: 0.1.0
+project:
+  config: config.yaml
+  specsDir: specs
+  storyboardDir: storyboard
+  promptsDir: prompts
+  outputDir: output
+  manifestsDir: manifests
+  shotsDir: shots
+types:
+  world_bible:
+    description: 世界观
+    defaultPath: specs/world_bible
+    template: templates/world_bible.md
+    dependsOn: []
+  characters:
+    description: 人物设定
+    defaultPath: specs/characters
+    template: templates/characters.md
+    dependsOn: []
+  visual_style:
+    description: 视觉风格
+    defaultPath: specs/visual_style
+    template: templates/visual_style.md
+    dependsOn: []
+  cinematography:
+    description: 镜头语言
+    defaultPath: specs/cinematography
+    template: templates/cinematography.md
+    dependsOn: []
+  shot_template:
+    description: 分镜模板
+    defaultPath: specs/shot_template
+    template: templates/shot_template.md
+    dependsOn:
+      - characters
+      - visual_style
+      - cinematography
+  prompt_guide:
+    description: AI Prompt 规范
+    defaultPath: specs/prompt_guide
+    template: templates/prompt_guide.md
+    dependsOn:
+      - world_bible
+      - visual_style
+compile:
+  prompt:
+    priority:
+      - shot
+      - characters
+      - cinematography
+      - visual_style
+      - world_bible
+      - prompt_guide
+    maxTokens:
+      stub: null

package/schema/requirements.schema.yaml

@@ -0,0 +1,25 @@
+version: 0.1.0
+id: requirements
+format: yaml
+required:
+  - project
+  - logline
+properties:
+  project: { type: string }
+  logline: { type: string }
+  style_keywords:
+    type: array
+    items: { type: string }
+  characters:
+    type: array
+    items:
+      type: object
+      required: [name]
+      properties:
+        name: { type: string }
+        description: { type: string }
+  constraints:
+    type: object
+    properties:
+      language: { type: string }
+      target: { type: string }

package/schema/storyboard.schema.yaml

@@ -0,0 +1,37 @@
+version: 0.1.0
+id: storyboard
+format: yaml_or_json
+shots:
+  required:
+    - id
+  properties:
+    id: { type: string }
+    characters:
+      type: array
+      items: { type: string }
+    scene: { type: string }
+    scene_context:
+      type: object
+      properties:
+        camera: { type: string, description: "摄像机运动，如 Dolly, Pan, Tilt" }
+        lighting: { type: string, description: "环境光效" }
+    assets:
+      type: object
+      properties:
+        seed: { type: integer, description: "一致性种子" }
+        face_id: { type: string, description: "角色面部特征 ID" }
+        reference_image: { type: string, description: "参考图 URL 或路径" }
+    action: { type: string }
+    composition: { type: string }
+    duration_s: { type: number }
+    media:
+      type: object
+      properties:
+        resolution: { type: string }
+        aspect_ratio: { type: string }
+        fps: { type: number }
+    prompt:
+      type: object
+      properties:
+        positive: { type: string }
+        negative: { type: string }

package/schema/validator.contract.yaml

@@ -0,0 +1,23 @@
+version: 0.1.0
+id: validator_contract
+input:
+  required:
+    - manifest
+  properties:
+    manifest:
+      type: object
+    references:
+      type: object
+      description: Optional references such as spec snapshots or reference images.
+    rules:
+      type: array
+      items: { type: string }
+      description: Specific evaluation rules or VQA prompts for the multi-modal LLM to check.
+output:
+  required:
+    - ok
+    - report
+  properties:
+    ok: { type: boolean }
+    score: { type: number }
+    report: { type: object }

package/templates/agents/antigravity.md

@@ -0,0 +1,11 @@
+---
+description: Assistant guidelines for working with MovieSpec projects
+---
+
+# MovieSpec Guidelines
+
+You are Antigravity, and you are operating within a MovieSpec project workspace. MovieSpec projects enforce a specific architecture to guarantee consistency across AI image and video generation tasks.
+
+- **Schemas and Templates**: Always adhere to the project's YAML schemas. When generating markdown for characters or shots, include the required YAML frontmatter (like `seed`, `face_id`, `reference_image`).
+- **Consistency**: Maintain continuity of `scene_context` across sequences of shots.
+- **Workflow Tools**: You have access to `moviespec` CLI commands. If you modify a storyboard, run `moviespec compile-prompts --shots <your_file.yaml>`.

package/templates/agents/cursor.md

@@ -0,0 +1,7 @@
+# MovieSpec Guidelines
+
+You are assisting with a MovieSpec project. MovieSpec enforces consistency in AI image and video generation through predictable YAML schemas.
+
+1. **Schemas and Templates**: When the user wants to create a new character, shot, or world bible, DO NOT do it arbitrarily. Read the corresponding schema in `schema/` or use the templates in `templates/` to guide your outputs. Structure everything in valid YAML or Markdown with YAML frontmatter.
+2. **Shot Consistency**: When creating a `storyboard.schema.yaml` or a `.prompt.json` shot, always ensure `assets` (seed, face_id, reference_image) and `scene_context` (camera, lighting) are maintained and passed between related shots to ensure visual consistency.
+3. **Compilation**: After saving or modifying a storyboard, remind the user to run `moviespec compile-prompts --shots <file>` to regenerate prompt outputs.

package/templates/agents/windsurf.md

@@ -0,0 +1,7 @@
+# MovieSpec Guidelines
+
+You are an AI agent operating in a MovieSpec project workspace. Your primary task is to generate and maintain consistent AI video generation documents.
+
+1. **Schemas and Templates**: When the user wants to create a new character, shot, or world bible, DO NOT do it arbitrarily. Read the corresponding schema in `schema/` or use the templates in `templates/` to guide your outputs. Structure everything in valid YAML or Markdown with YAML frontmatter.
+2. **Shot Consistency**: When creating a `storyboard.schema.yaml` or a `.prompt.json` shot, always ensure `assets` (seed, face_id, reference_image) and `scene_context` (camera, lighting) are maintained and passed between related shots to ensure visual consistency.
+3. **Compilation**: After saving or modifying a storyboard, automatically run `moviespec compile-prompts --shots <file>` for the user if necessary.

package/templates/characters.md

@@ -0,0 +1,19 @@
+---
+type: characters
+name: "{{name}}"
+seed: 
+face_id: ""
+reference_image: ""
+---
+
+# 角色：{{name}}
+
+## 外观
+
+## 服饰与配色
+
+## 性格与动机
+
+## 关键标识
+
+## LoRA（可选）

package/templates/cinematography.md

@@ -0,0 +1,14 @@
+---
+type: cinematography
+name: "{{name}}"
+---
+
+# 镜头语言：{{name}}
+
+## 景别
+
+## 镜头运动
+
+## 构图原则
+
+## 节奏与剪辑偏好

package/templates/prompt_guide.md

@@ -0,0 +1,12 @@
+---
+type: prompt_guide
+name: "{{name}}"
+---
+
+# Prompt 规范：{{name}}
+
+## 组装优先级
+
+## 长度控制策略
+
+## 通用负面词（可选）

package/templates/shot_template.md

@@ -0,0 +1,18 @@
+---
+type: shot_template
+name: "{{name}}"
+---
+
+# 分镜模板：{{name}}
+
+## 每镜字段建议
+
+- id
+- characters
+- scene
+- scene_context (camera/lighting)
+- action
+- composition
+- assets (seed/face_id/reference_image)
+- media (resolution/aspect_ratio/fps 可选覆盖)
+- prompt (positive/negative)

package/templates/visual_style.md

@@ -0,0 +1,14 @@
+---
+type: visual_style
+name: "{{name}}"
+---
+
+# 视觉风格：{{name}}
+
+## 参考风格关键词
+
+## 光影与色彩
+
+## 材质与细节
+
+## 禁用元素

package/templates/world_bible.md

@@ -0,0 +1,14 @@
+---
+type: world_bible
+name: "{{name}}"
+---
+
+# 世界观：{{name}}
+
+## 核心设定
+
+## 时代与地域
+
+## 规则与禁忌
+
+## 关键道具/势力