open-index/open-npm huggingface dataset:
npm package: @gthanks/moviespec
Description: Specification-driven consistency framework for AI image and video generation
Author: gthanks
Latest version: 0.1.5

# MovieSpec

MovieSpec 是一套面向 AI 图片/视频生成的「规范先行」工作方式：先把世界观、角色、视觉风格、镜头语言与分镜结构写成可机读/可复用的规范文档，再从这些规范稳定编译出 Prompt 与参数，并将每次生成的输入与输出写入 manifest 以便复现与排查一致性漂移。

## 目录结构

- `bin/`：CLI 入口
- `schema/`：可机读 schema（类型、路径、依赖、编译规则）
- `templates/`：各类规范文档模板（Markdown + YAML front matter）

## 文档生成规则

- 所有规范文档默认使用中文撰写
- 模板 front matter 默认带 `language: zh-CN`
- `moviespec init` 生成的 `config.yaml` 默认写入中文文档策略

## 文档步骤编号规则

- `schema/moviespec.schema.yaml` 为每种文档类型定义统一的 `step`
- `schema/moviespec.schema.yaml` 的 `defaultPath` 默认采用编号目录：`specs/NN_<typeId>`（例如 `specs/01_visual_decode`）
- `moviespec new <type> <name>` 默认生成带步骤前缀的文件名，例如 `specs/01_visual_decode/01_poem_adaptation.md`
- 模板生成时会自动补充 `step` front matter，并在一级标题前附加步骤号
- 对于 `characters` 这类会被分镜引用的类型，校验逻辑会自动忽略文件名前缀，因此分镜中仍然写原始角色名即可，例如 `lixunhuan`

## 安装

如果你想在全局使用该命令，可以通过 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` 的默认路径读取与写入上述目录。

## 完整流程教程

- 详细教程：[`docs/text-to-video-workflow.md`](./docs/text-to-video-workflow.md)
- 最小示例：[`examples/basic/README.md`](./examples/basic/README.md)

## 核心规范文档类型

- `01 visual_decode`：视觉解译
- `02 script`：剧本
- `03 world_bible`：世界观
- `04 characters`：人物设定
- `05 visual_style`：视觉风格
- `06 look_book`：视觉风格圣经
- `07 cinematography`：镜头语言
- `08 shot_list`：镜头清单
- `09 shot_template`：分镜模板
- `10 prompt_bible`：Prompt 圣经
- `11 prompt_guide`：Prompt 规范
- `12 consistency_system`：视觉一致性系统
- `13 hero_shot_pilot`：关键镜头测试
- `14 keyframe_sheet`：关键帧制作单
- `15 video_generation_sheet`：视频生成单
- `16 sound_design`：声音设计
- `17 edit_plan`：剪辑计划
- `18 grading_guide`：调色指南
- `19 delivery_manifest`：交付清单

## 最小命令集（v1）

- `moviespec init`
- `moviespec list types`
- `moviespec list-aesthetics` (查看有哪些内置的经典电影美学)
- `moviespec apply <name>` (将内置美学套用到当前项目的视觉风格中，并按步骤号写入 `visual_style`)
- `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）

## 快速开始

```bash
moviespec init
moviespec list types
moviespec new visual_decode poem_adaptation
moviespec new script short_film
moviespec new characters lixunhuan
moviespec apply 胡金铨风
moviespec new look_book rain_noir
moviespec compile-prompts --shots storyboard/shots.yaml
moviespec validate --shots storyboard/shots.yaml
moviespec generate sequence --shots storyboard/shots.yaml
```

说明：当前 `compile-prompts` 在 v1 中仍以 `storyboard/shots.yaml` 为直接输入，以上规范文档已经可以帮助你按完整流程组织项目，并参与依赖指纹校验；后续版本可继续将更多规范文档内容编译进最终 Prompt。