# Novel2Script

**Repository Path**: liu24322/novel2script

## Basic Information

- **Project Name**: Novel2Script
- **Description**: AI 小说转剧本工具，很多小说作者希望将自己的作品改编成剧本，该工具降低改编门槛，提升效率。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-06
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Novel2Script

AI 小说转剧本工具 MVP。项目面向小说作者与改编创作者，支持将 3 个章节以上的小说文本转换为结构化剧本 YAML，并提供 Schema 校验和 Markdown 导出下载能力。

## 项目亮点

- **小说转剧本初稿**：输入至少 3 章小说文本，自动生成结构化剧本 YAML。
- **结构化 YAML Schema**：用统一字段描述元数据、来源章节、角色、地点、场景、动作与对白。
- **可编辑工作台**：小说文本、剧本 YAML、校验与导出三栏并排，方便作者修改初稿。
- **Schema 校验**：支持重新校验 YAML，错误信息会显示字段路径。
- **Markdown 导出下载**：通过校验后可导出 Markdown 剧本，并直接下载 `.md` 文件。
- **本地可复现部署**：提供 Conda 环境部署文档，便于评审和演示。

## 技术栈

### 后端

- Python
- FastAPI
- PyYAML
- jsonschema
- pytest
- uvicorn

### 前端

- React
- Vite
- JavaScript
- CSS 毛玻璃风格界面
- Node.js 内置测试

## 目录结构

```text
Novel2Script/
├── backend/
│   ├── app/
│   │   ├── api/                  # FastAPI 路由
│   │   ├── schemas/              # 剧本 YAML Schema
│   │   ├── services/             # 小说解析、生成、校验、导出服务
│   │   └── main.py               # 后端入口
│   ├── tests/                    # 后端测试
│   └── requirements.txt
├── frontend/
│   ├── src/                      # React 前端源码
│   ├── tests/                    # 前端测试
│   ├── index.html
│   ├── package.json
│   └── package-lock.json
├── conda_deployment_guide.md     # Conda 部署说明
├── development_workflow.md       # 开发流程规划
├── project_design.md             # 产品设计文档
├── screenplay_yaml_schema_design.md
└── README.md
```

## 快速开始

推荐使用 Conda 管理 Python 和 Node.js 环境。

```powershell
cd F:\Project\Novel2Script
conda create -n novel2script python=3.11 nodejs=22 -c conda-forge -y
conda activate novel2script
```

安装后端依赖：

```powershell
cd F:\Project\Novel2Script\backend
python -m pip install -r requirements.txt
```

启动后端：

```powershell
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000
```

新开一个 PowerShell 窗口，安装并启动前端：

```powershell
conda activate novel2script
cd F:\Project\Novel2Script\frontend
npm ci
npm run dev -- --host 127.0.0.1 --port 5173
```

访问：

```text
http://127.0.0.1:5173
```

更完整的部署说明见：`conda_deployment_guide.md`。

## 测试

后端测试：

```powershell
cd F:\Project\Novel2Script\backend
python -m pytest -q
```

前端测试：

```powershell
cd F:\Project\Novel2Script\frontend
npm test
```

前端构建：

```powershell
cd F:\Project\Novel2Script\frontend
npm run build
```

## API 说明

后端默认运行在 `http://127.0.0.1:8000`。

| 接口 | 方法 | 说明 |
| --- | --- | --- |
| `/health` | GET | 健康检查 |
| `/generate` | POST | 根据小说文本生成剧本 YAML |
| `/validate` | POST | 校验 YAML 是否符合 Schema |
| `/export/markdown` | POST | 将 YAML 导出为 Markdown 剧本 |

## 剧本 YAML Schema

Schema 文件位于：

```text
backend/app/schemas/screenplay.schema.yaml
```

设计说明见：

```text
screenplay_yaml_schema_design.md
```

当前 Schema 覆盖 MVP 必填结构：

- `schema_version`
- `metadata`
- `source`
- `adaptation`
- `story_bible`
- `script.scenes`

## 演示流程

1. 打开前端工作台。
2. 粘贴至少 3 章小说文本。
3. 选择目标格式和风格。
4. 点击 `生成结构化剧本`。
5. 查看并编辑 YAML 初稿。
6. 点击 `重新校验`。
7. Schema 通过后点击 `导出 Markdown`。
8. 系统生成 Markdown 预览，并自动下载 `.md` 文件。

## 上传 Git 前建议

请只上传源码、测试、文档和依赖清单，不上传以下内容：

- `frontend/node_modules/`
- `frontend/dist/`
- `backend/.pytest_cache/`
- `__pycache__/`
- `.venv/`
- `.agents/`

本项目已提供 `.gitignore`，可以直接用于 Git 仓库。