Skip to content
剧本文档与版本

剧本文档与版本

本文属于“当前架构”文档,描述 P3 / C5 已落地的剧本文档基础设施。 AI 解析、统一审核与差异分析见 剧本结构化解析与统一审核。

两类文档

类型doc_type关联
世界观与人物设定worldbuilding项目级,chapter_id = NULL
每集完整剧本episode必须绑定一个 Chapter

一集对应一个 ScriptDocument;重复上传会创建新版本,不创建新文档。

数据模型

script_documents
  id / project_id / chapter_id / doc_type / title
  current_version_id   ← 最近上传版本(候选或生效)
  active_version_id    ← 当前生效版本
script_document_versions
  id / document_id / version_no
  file_id              ← 原始上传文件(files.type = document)
  file_name / file_type / content_hash
  raw_text / text_length
  status               ← candidate / active / superseded
  parse_status         ← not_parsed / parsing / parsed / failed
  metadata             ← 提取告警、表格/图片统计

current_version_id 与 active_version_id 分离的原因:

  • 上传新文件只更新 current,旧 active 继续作为正式内容;
  • 世界观首次上传可直接成为 active;
  • 每集剧本首次上传仍是 candidate,用户显式“启用版本”或 C6 审核确认后才成为 active;
  • 历史版本永不删除,可回看与追溯。

chapters.raw_text 仍是正式章节正文。只有启用版本时才会同步, 上传和解析阶段不会覆盖它。

文件解析

支持:

  • .docx:python-docx 按 body 顺序读取段落与表格;Word 标题样式转成 Markdown #;
  • .md / .markdown:UTF-8 解码,统一换行为 \n。

服务端校验:

  • 扩展名白名单;
  • 单文件 ≤ 10MB;
  • DOCX 必须是含 word/document.xml 的 ZIP;
  • Markdown 不允许 NUL 字节,必须是 UTF-8;
  • 空正文拒绝创建版本;
  • 表格/图片提取不完整时写入 metadata.warnings,不静默丢弃正文。

DOCX 宏、外部引用不会执行;只读取文档 XML。

重复上传

同一文档下 content_hash 相同视为重复上传,返回已有版本,created=false, 不会新增版本行。

API

方法路径
GET/api/v1/studio/projects/{id}/script-documents
POST/api/v1/studio/projects/{id}/script-documents/worldbuilding
POST/api/v1/studio/projects/{id}/chapters/{cid}/script-document
GET/api/v1/studio/script-documents/{id}
GET/api/v1/studio/script-documents/{id}/versions/{vid}
POST/api/v1/studio/script-documents/{id}/versions/{vid}/activate

上传为 multipart,字段 file,可选 title。原始文件写入 files(type=document), 并通过 file_usages(usage_kind=script_document) 关联项目/章节。

当前边界

  • 文件上传/版本管理本身不自动解析;AI 解析是独立任务(见 剧本结构化解析与统一审核);
  • 上传不自动覆盖章节正文、分镜或资产;只有启用版本或解析确认后同步;
  • 不创建场次实体(P5);
  • 文件大小上限 10MB;更大的剧本需拆分或后续调整。