AI 小说改编工作台 —— 把中文小说转换成结构化、可校验、可编辑的剧本初稿。
七牛云 AI 大模型暑期实训营 · 议题三「AI 小说转剧本」参赛作品。
演示视频：剧本工坊 Screenwright · 中文小说转结构化剧本 Demo
- 章节智能切分：按「第 X 章」自动分章，支持 3 章以上整部小说连续转换。
- DeepSeek 结构化生成：JSON 模式输出，严格对齐 Schema 数据契约。
- 双层校验：JSON Schema 结构校验 + 代码侧引用完整性校验（对白 ↔ 人物、人物 ↔ 场次的交叉引用）。
- 自动修复重试：模型输出非法时，把错误回传给模型让其自我修正。
- 跨章节人物归一：同一人物的多种叫法／别名归并到稳定
id，场次全局重新编号并同步引用。 - 三视图工作台：剧本预览（人类可读）／ YAML 源码（可编辑 + 实时校验）／ 人物表。
- 一键导出 YAML / Fountain，支持「撤销到上次合法版本」。
app.py ……………… Streamlit 三视图工作台（UI）
├─ converter.py … 转换引擎：章节切分 → DeepSeek → 校验修复 → JSON→YAML → 渲染预览
│ ├─ prompts.py … 模型输出的 JSON 契约（系统／用户／修复提示词）
│ └─ validator.py … 双层校验（Schema 结构 + 引用完整性）
│ └─ schema/screenplay.schema.json … 剧本数据契约【作品核心】
└─ fountain.py … Fountain 导出器（结构化剧本 → 标准纯文本剧本）
Windows 一键： 双击 setup.bat 安装依赖 → 复制 .env.example 为 .env 并填入密钥 → 双击 run.bat 启动。
手动：
pip install -r requirements.txt # 安装依赖
cp .env.example .env # 复制配置，填入 DEEPSEEK_API_KEY
streamlit run app.py # 启动工作台可选：.env 中的 DEEPSEEK_TIMEOUT_SECONDS 控制单次模型请求等待上限，默认 120 秒。
命令行校验任意剧本 YAML：
python validate_screenplay.py examples/last-ferry.screenplay.yaml命令行导出 Fountain：
python export_fountain.py examples/归途.screenplay.yaml| 库 | 版本 | 用途 |
|---|---|---|
| streamlit | 1.32.0 | Web 工作台 UI |
| openai | 1.14.0 | DeepSeek API 客户端（OpenAI 兼容协议） |
| pyyaml | 6.0.1 | JSON ↔ YAML 序列化 |
| jsonschema | 4.21.1 | Draft 2020-12 结构校验 |
| python-dotenv | 1.0.1 | 加载 .env 配置 |
| httpx | 0.27.2 | openai 的 HTTP 依赖（固定版本规避兼容问题） |
本作品自主完成、无抄袭。原创核心：
- 剧本 Schema 设计（
schema/+docs/schema-design.md）：层级化数据模型、"有序带类型的元素流"、人物身份归一化 —— 本作品的核心。 - 转换引擎（
converter.py）：章节切分、跨章节人物id归并、场次全局重编号与引用同步、JSON→YAML 代码侧序列化、修复重试。 - 提示词契约（
prompts.py）、双层校验器（validator.py）、Streamlit 工作台（app.py）。
上述第三方库仅作基础设施（UI 框架、API 客户端、序列化／校验工具），核心改编逻辑与数据模型均为原创。
一句话：剧本 = 文档 → 场次 → 有序的、带类型的元素流（动作／对白／转场／镜头）。设计理由详见 docs/schema-design.md。
screenwright/
├── app.py # Streamlit 工作台
├── converter.py # 转换引擎
├── fountain.py # Fountain 导出器
├── export_fountain.py # YAML → Fountain 命令行工具
├── prompts.py # 模型输出契约
├── validator.py # 双层校验器
├── validate_screenplay.py # 命令行校验工具
├── schema/ # 剧本数据契约（JSON Schema + 注释版 YAML）
├── examples/ # 示例小说与转换成果
├── tests/ # 测试与示例生成脚本（详见下）
└── docs/ # Schema 设计说明
tests/（一律从项目根目录运行）：
test_fixes.py— 离线单元测试（校验守卫 /finalize清洗 / 容错），无需 API key：python tests/test_fixes.pytest_client_config.py— DeepSeek 客户端超时与重试配置测试，无需 API key。test_progress.py— 多章节转换进度透传测试，无需 API key。test_retry_budget.py— 模型修复重试预算测试，无需 API key。test_schema_normalization.py— Schema 枚举兼容清洗测试，无需 API key。test_connection.py— DeepSeek 连接冒烟测试（需先在.env配置密钥）test_convert.py/test_novel.py— 单章 / 全本转换集成实测（需密钥，真实调用 API）save_example.py— 重新生成示例 YAML 的维护脚本（会覆写examples/，普通使用无需运行）
七牛云暑期实训营参赛作品 · 开发周期 2026-06-05 ~ 2026-06-07。