# works

**Repository Path**: free1112/works

## Basic Information

- **Project Name**: works
- **Description**: 墨剧 Novel2Script 是一个面向小说改编场景的 Web 工作台，支持小说导入、章节解析、AI 剧本生成、低置信内容审核、场景编辑与 YAML 导出，帮助创作者把改编流程从原始文本处理推进到结构化生产。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 墨剧 / Novel2Script

一个把长篇小说文本拆章、识别角色与场景，并转换成结构化剧本的 Web 项目。仓库包含 Vue 3 前端、Spring Boot 后端、MySQL 持久化，以及基于 DeepSeek 的辅助转换能力。

## Demo 演示视频

> **立即观看：** [墨剧 Novel2Script：让小说改编进入结构化剧本工作流](https://www.bilibili.com/video/BV1gMEx6BE8y/?share_source=copy_web&vd_source=c3aaca785a0fcd4110be474a6b8936c2)
>
> 项目演示视频已发布，包含从小说导入、章节解析、剧本生成，到低置信审核、场景编辑与 YAML 导出的完整流程展示。

## 项目亮点

- 支持注册、登录与基于 JWT 的访问控制
- 支持粘贴小说正文或上传 `.txt`、`.text`、`.md` 文件
- 自动拆分章节，并统计章节数、段落数、字数信息
- 生成剧本时提供弹窗式加载反馈，并在完成后自动跳转工作台
- 提供剧本总览页、独立场景编辑页、低置信度修订页三段式工作流
- 支持逐场景编辑标题、地点、时间、出场角色、动作、对白与置信度
- 支持对低置信度对白/动作集中审核、标记已确认、跳转对应场景编辑
- 支持保存项目、重复打开、保存编辑结果和导出 YAML
- 已优化 YAML 下载链路：优先复用已保存结果，避免重复调用 AI

## 技术栈

### 前端

- Vue 3
- Vite
- Vue Router
- Pinia
- Element Plus
- Axios
- js-yaml
- CodeMirror

### 后端

- Java 17
- Spring Boot 3.2
- Spring Web
- Spring Data JPA
- Spring Security
- JWT
- MySQL 8
- SnakeYAML

### AI

- DeepSeek API
- 默认模型：`deepseek-v4-flash`

## 目录结构

```text
.
├─ backend/                                  # Spring Boot 后端
│  ├─ src/main/java/com/novel2script
│  │  ├─ config/                             # 安全、跨域、JWT 过滤器、异常处理
│  │  ├─ controller/                         # 认证、项目、解析、转换、保存、下载接口
│  │  ├─ entity/                             # JPA 实体
│  │  ├─ model/                              # 剧本结构模型与 DTO
│  │  ├─ repository/                         # 数据访问层
│  │  └─ service/                            # 拆章、场景检测、角色提取、AI 转换
│  └─ src/main/resources/
│     ├─ application.yml                     # 后端配置
│     └─ schema.sql                          # MySQL 初始化脚本
├─ frontend/                                 # Vue 3 前端
│  ├─ public/
│  │  └─ sample-novel.txt                    # 示例小说文本
│  └─ src/
│     ├─ api/                                # 接口封装
│     ├─ components/                         # 通用组件
│     ├─ router/                             # 路由配置
│     ├─ stores/                             # Pinia 状态
│     ├─ styles/                             # 全局样式
│     ├─ utils/                              # 剧本编辑与低置信度处理工具
│     └─ views/
│        ├─ LoginView.vue                    # 登录页
│        ├─ RegisterView.vue                 # 注册页
│        ├─ ProjectList.vue                  # 项目库
│        ├─ UploadView.vue                   # 导入与生成页
│        ├─ ScriptView.vue                   # 剧本工作台总览
│        ├─ SceneEditorView.vue              # 独立场景编辑页
│        └─ LowConfidenceReviewView.vue      # 低置信度修订页
├─ docs/
│  └─ schema.md                              # YAML 剧本 Schema 设计说明
├─ sample-novel.txt                          # 根目录示例文本
└─ README.md
```

## 核心流程

1. 用户登录后进入项目库。
2. 在导入页粘贴小说文本，或上传本地文本文件。
3. 后端拆分章节，返回章节数、段落数、总字数，并持久化为项目。
4. 用户确认章节后发起剧本生成，前端显示弹窗式加载状态。
5. 后端先提取角色，再检测场景，并基于“规则引擎 + 大模型”组装结构化剧本。
6. 生成完成后前端自动跳转到剧本工作台总览。
7. 用户可以继续进入独立场景编辑页，或在低置信度修订页优先处理需要人工确认的内容。
8. 编辑后的剧本可保存回数据库，并导出 YAML。

## 功能概览

### 已实现

- 用户注册、登录、登录态校验
- 项目列表查看与删除
- 小说章节解析与持久化
- 剧本生成与工作台总览
- 独立场景编辑
- 低置信度审核流
- 编辑结果保存
- YAML 导出

### 工作台说明

当前前端工作流分为三个主要页面：

- `剧本工作台总览`：查看场景索引、角色统计、章节对照、低置信条目数量、YAML 导出
- `独立场景编辑页`：专注编辑单个场景的元信息、动作、对白、角色出场和置信度
- `低置信度修订页`：集中处理 `confidence < 0.6` 的对白/动作，支持上一条、下一条、标记已确认、跳转场景编辑

### 上传与生成体验

导入页已经做了针对生成流程的交互优化：

- 章节解析前展示空状态与输入统计
- 生成剧本时显示居中弹窗 loading
- 弹窗展示阶段提示、等待时长、处理规模
- 生成成功后自动跳转到 `/script/:projectId`

### 下载优化

当前仓库已对下载链路做了两层优化：

- 后端下载接口优先读取数据库中已保存的 `yaml_content`
- 前端在工作台中优先使用当前已加载的剧本对象本地生成 YAML

这意味着已经转换过的项目，点击“下载 YAML”通常不再需要等待后端重新跑一遍 AI。

## 本地启动

### 1. 环境要求

- Node.js 18+
- npm 9+
- Java 17
- Maven 3.9+
- MySQL 8+

### 2. 初始化数据库

执行 [schema.sql](/D:/novel/backend/src/main/resources/schema.sql) 或先手动创建数据库：

```sql
CREATE DATABASE IF NOT EXISTS novel2script
  DEFAULT CHARACTER SET utf8mb4
  DEFAULT COLLATE utf8mb4_unicode_ci;
```

### 3. 配置后端

后端配置文件位于 [application.yml](/D:/novel/backend/src/main/resources/application.yml)。

建议使用环境变量覆盖敏感配置：

```powershell
$env:MYSQL_USER="root"
$env:MYSQL_PASSWORD="root"
$env:DEEPSEEK_API_KEY="your-deepseek-api-key"
$env:DEEPSEEK_MODEL="deepseek-v4-flash"
$env:JWT_SECRET="your-jwt-secret"
```

默认关键配置如下：

```yaml
server:
  port: 8080

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/novel2script?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai&createDatabaseIfNotExist=true
    username: ${MYSQL_USER:root}
    password: ${MYSQL_PASSWORD:root}

deepseek:
  api-key: ${DEEPSEEK_API_KEY:your-deepseek-api-key}
  model: ${DEEPSEEK_MODEL:deepseek-v4-flash}

jwt:
  secret: ${JWT_SECRET:your-jwt-secret}
```

### 4. 启动后端

```powershell
cd D:\novel\backend
mvn spring-boot:run
```

启动后默认监听 `http://localhost:8080`。

### 5. 启动前端

```powershell
cd D:\novel\frontend
npm install
npm run dev
```

前端默认监听 `http://localhost:3000`，并通过 Vite 代理把 `/api` 转发到后端。

## 主要页面

- `登录页`：账号登录
- `注册页`：新建账号
- `项目库`：查看历史项目、最近更新时间、转换状态
- `导入页`：粘贴或上传文本，解析章节并发起剧本生成
- `剧本工作台`：查看场景索引、角色信息、章节对照和 YAML
- `场景编辑页`：编辑单个场景的结构化内容
- `低置信度修订页`：优先处理 AI 低置信度条目

## 主要路由

- `/login`
- `/register`
- `/`
- `/upload`
- `/script/:projectId`
- `/script/:projectId/edit/:sceneId`
- `/script/:projectId/review`

## 主要接口

### 认证接口

- `POST /api/auth/register`
- `POST /api/auth/login`
- `GET /api/auth/me`

### 项目接口

- `GET /api/projects`
- `GET /api/projects/{id}`
- `DELETE /api/projects/{id}`

### 小说处理接口

- `POST /api/novel/parse`
- `POST /api/novel/upload`

### 剧本接口

- `POST /api/script/convert`
- `POST /api/script/save`
- `POST /api/script/download`
- `GET /api/health`

## 数据存储

MySQL 中主要包含以下表：

- `users`：用户信息
- `project`：原始小说项目与状态
- `chapter`：拆章结果
- `script`：转换后的 YAML / JSON 剧本结果

其中 `script` 表会保存：

- `yaml_content`
- `json_content`
- `meta_json`
- `scene_count`
- `char_count`

## 剧本 Schema

导出剧本以 YAML 为主，核心结构包含：

- `meta`
- `characters`
- `scenes`

完整设计说明见 [docs/schema.md](/D:/novel/docs/schema.md)。

## 快速体验

- 根目录提供 [sample-novel.txt](/D:/novel/sample-novel.txt)
- 前端静态资源目录提供 [frontend/public/sample-novel.txt](/D:/novel/frontend/public/sample-novel.txt)

你可以在导入页直接加载示例文本，快速验证以下流程：

1. 解析章节
2. 生成剧本
3. 自动跳转工作台
4. 进入场景编辑
5. 打开低置信度修订页
6. 导出 YAML

## 后续可继续增强

- 提高角色识别与对白归属准确率
- 补全场景标题、内外景、昼夜等字段
- 增加更细粒度的审核筛选与批量确认能力
- 增加自动化测试覆盖与更严格的权限校验