ScriptWeaver

题目三：AI 小说转剧本工具

ScriptWeaver 是一款面向小说作者的 Schema-Guided Novel-to-Script Studio。它支持输入 3 章以上小说，通过多阶段 AI 工作流把多章节叙事改编成可编辑、可校验、可扩展的 YAML 剧本初稿。

核心能力：

• 输入 3 章以上小说，而不是只支持固定短文本 Demo。
• 支持复制粘贴小说文本，也支持上传 .txt / .md 纯文本章节文件。
• 多阶段 AI 工作流：章节解析 -> Story Bible -> Scene Plan -> Scene Beats -> YAML。
• 输出可编辑、可校验、可扩展的 YAML 剧本，作者可以继续打磨。
• 使用 YAML Schema 保证结果稳定、可检查、可扩展。
• 支持真实 API + mock fallback：默认可用 mock 稳定演示；配置 OpenAI-compatible API 后走真实模型；长剧本 YAML 采用分场景真实生成；单场景失败时局部 fallback，并通过 validation_notes 和接口 warning 暴露。

题目对齐

本项目对应 XEngineer 议题三：AI 小说转剧本工具。

• 支持 3 个章节及以上的小说文本输入。
• 将多章节叙事内容转换为结构化 YAML 剧本。
• 提供 YAML Schema，并用文档说明字段设计原因。
• 生成结果可在前端编辑，并可重新进行 Schema 校验。
• 通过分阶段工作流展示从小说到剧本的改编过程。

评审入口

• Demo 视频：Bilibili 在线观看
• Demo 指南：docs/demo-guide.md
• 项目亮点与隐藏评分点：docs/project-highlights.md
• YAML Schema 设计文档：docs/yaml-schema-design.md
• 示例小说输入：examples/sample_novel.md
• 示例 YAML 剧本：examples/sample_script.yaml

五阶段工作流

1. Chapter Intake
2. Story Bible
3. Scene Plan
4. YAML Script
5. Validate & Export

前端 Chapter Intake 页面提供“加载示例小说”按钮，评审可以直接载入 4 章原创样例。样例每章保留数百字叙事、人物行动、关键道具和冲突转折，用于展示系统处理真实章节文本的效果。

用户也可以上传 .txt 或 .md 小说文件，前端会读取纯文本并填入输入框，再复用同一套章节解析流程。当前不支持 .docx、.pdf、.epub 等复杂格式，避免把文件解析复杂度混入比赛核心链路。

技术栈

• 前端：Vue 3、Vite、JavaScript、Element Plus、Tailwind CSS、Monaco Editor。
• 后端：FastAPI、PyYAML、jsonschema、pytest。
• AI 接入：默认 mock 模式，也支持通过 .env 切换到 OpenAI-compatible API。

本地启动

后端

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r backend\requirements.txt
.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --app-dir backend

前端

cd frontend
npm.cmd install --cache ..\.npm-cache
npm.cmd run dev

前端默认地址：

http://localhost:5173/
http://127.0.0.1:5173

AI 配置

当前项目默认使用 mock 模式，因此没有 API Key 也可以跑通完整 Demo（演示视频中使用的是 Real 模式，可自行接入大语言模型 API）。 前端请求不强制指定模式，后端会根据 .env 中的 API_MODE 决定使用 mock 还是真实 OpenAI-compatible API。

如需接入真实模型，可在项目根目录创建或编辑 .env：

API_MODE=real
OPENAI_API_KEY= key
OPENAI_BASE_URL= base_url
OPENAI_MODEL= model

字段说明：

• API_MODE=mock：默认模式，不调用外部 API，适合稳定演示和本地开发。
• API_MODE=real：尝试调用 OpenAI-compatible API，适合展示真实模型生成效果。
• OPENAI_API_KEY：真实 API Key。
• OPENAI_BASE_URL：可选，兼容 OpenAI API 格式的服务地址。
• OPENAI_MODEL：模型名称。

当 API_MODE=real 但真实 API 调用失败时，后端会自动降级到 mock 结果，并在返回数据中附带 warning：

{
  "code": "ai_fallback_to_mock",
  "message": "OpenAI-compatible API failed; returned mock result instead. Detail: ..."
}

这样即使 API Key 缺失、网络异常或模型输出异常，项目仍能完成端到端 Demo。

Schema 与示例

• Schema 文件：backend/app/schemas/script_schema.json
• Schema 设计文档：docs/yaml-schema-design.md
• 示例小说输入：examples/sample_novel.md
• 示例 YAML 剧本：examples/sample_script.yaml

示例小说使用 4 个章节，每章至少 500 个非空白字符，证明系统不是只支持固定 3 章或极短冒烟文本。前端“加载示例小说”按钮直接读取同一份 examples/sample_novel.md，避免页面内置样例和仓库示例不一致。示例 YAML 会被后端测试读取并通过当前 Schema 校验。