1 line
109 KiB
JSON
1 line
109 KiB
JSON
{"repo": "ailakala/script-tool", "files": {"README.md": {"fed82c49a37084585bc4f3370dbb56af13d529a1": {"t": 1785746436.1073709, "n": 18101, "h": "d318b3647b7fdc88", "c": "视频介绍：\n【七牛云☁竞赛视频-哔哩哔哩】 https://b23.tv/AqzOm9g\n七牛云☁竞赛视频 # 七牛云 # aicoding... https://v.douyin.com/09iMpaV-8JA/\n\n# 🎬 AI 剧本创作工具\n\n将小说文本（≥3 章）自动转换为**结构化 YAML 剧本**和**行业标准格式剧本**，支持电影、电视剧、舞台剧、动画等多种类型。\n\n---\n\n## 目录\n\n- [功能概览](#功能概览)\n- [项目架构](#项目架构)\n- [环境搭建](#环境搭建)\n- [API Key 配置详解](#api-key-配置详解)\n- [使用指南](#使用指南)\n- [6 阶段流水线详解](#6-阶段流水线详解)\n- [功能模块说明](#功能模块说明)\n- [API 接口文档](#api-接口文档)\n- [常见问题](#常见问题)\n- [开发指南](#开发指南)\n\n---\n\n## 功能概览\n\n### 核心功能\n\n| 模块 | 说明 |\n|------|------|\n| 📂 **文件导入** | 支持 `.txt` / `.docx` / `.md` 格式上传，或直接粘贴小说文本（最多 50 万字） |\n| ⚡ **一键生成** | 6 阶段全自动流水线，从文本解析到剧本导出全程 AI 驱动 |\n| 📋 **分步生成** | 逐阶段执行，每步可暂停审查 AI 中间结果（人物、情节、场景结构） |\n| 🕸 **场景编排看板** | Stage 3 完成后提供拖拽式场景看板，自由增删合并拆分场景 |\n| 📝 **在线编辑** | 生成的剧本支持在线预览和编辑，实时保存 |\n| ⬇ **多格式导出** | 支持 YAML（结构化数据）和 PDF（行业标准排版）双格式导出 |\n| 💬 **AI 助手** | 右下角聊天面板，支持翻译、润色、摘要等快捷操作，5 种模型自由切换 |\n| 🔄 **断点续传** | 每阶段结果自动缓存，重新开始或切换模型后已完成阶段无需重跑 |\n\n### 支持的剧本类型\n\n- 电影剧本（Film）\n- 电视剧剧本（TV Series）— 支持多集场景编排\n- 动画剧本（Animation）\n- 舞台剧剧本（Stage Play）\n- 自定义（Custom）\n\n---\n\n## 项目架构\n\n```\nscript-tool/\n├── app/\n│ ├── main.py # FastAPI 入口，挂载静态文件与路由\n│ ├── config.py # 配置中心：环境变量加载、路径管理\n│ ├── models.py # 数据模型：Project / PipelineRun / StageCache\n│ ├── db.py # SQLite 数据库引擎与会话管理\n│ │\n│ ├── ai/ # AI 后端抽象层（5 种 Provider）\n│ │ ├── interface.py # AIProvider 抽象接口\n│ │ ├── factory.py # Provider 工厂函数\n│ │ ├── claude.py # Anthropic Claude API\n│ │ ├── openai.py # OpenAI GPT (兼容自定义 base_url)\n│ │ ├── deepseek.py # DeepSeek (OpenAI 兼容协议)\n│ │ ├── gemini.py # Google Gemini\n│ │ └── local.py # 本地模型 (LM Studio / Ollama)\n│ │\n│ ├── pipeline/ # 6 阶段流水线引擎\n│ │ ├── executor.py # 流水线调度器（含缓存、进度、重试逻辑）\n│ │ ├── stage0_preprocess.py # Stage 0: 文本预处理（章节拆分）\n│ │ ├── stage1_chapter_analysis.py # Stage 1: 分章节分析\n│ │ ├── stage2_cross_chapter_synthesis.py # Stage 2: 跨章节综合\n│ │ ├── stage3_script_structure.py # Stage 3: 剧本结构设计\n│ │ ├── stage4_scene_generation.py # Stage 4: 逐场内容生成\n│ │ ├── stage5_assembly.py # Stage 5: YAML 组装 & 标准格式转换\n│ │ ├── pdf_export.py # PDF 导出（行业标准排版）\n│ │ └── utils.py # JSON 提取等工具函数\n│ │\n│ ├── routes/ # HTTP 路由层\n│ │ ├── pages.py # 页面路由（Jinja2 SSR）\n│ │ ├── api.py # REST API + SSE 流式接口\n│ │ └── chat.py # AI 助手聊天接口\n│ │\n│ └── templates/ # Jinja2 模板\n│ ├── base.html # 基础布局（导航栏、粒子背景）\n│ ├── index.html # 首页（项目列表）\n│ ├── project_new.html # 新建项目\n│ ├── project.html # 项目工作台（核心页面）\n│ ├── stage_review.html # 中间结果审查\n│ ├── stage3_kanban.html # 场景编排看板\n│ ├── character_graph.html # 人物关系图谱\n│ └── script_view.html # 在线剧本查看/编辑\n│\n├── static/\n│ ├── css/style.css # 全局样式（暗色科技主题）\n│ ├── js/\n│ │ ├── htmx.min.js # HTMX 前端交互库\n│ │ └── particles.js # 粒子背景动画\n│ └── img/\n│ └── logo.svg # 品牌 Logo\n│\n├── storage/ # 运行时数据（自动创建）\n│ ├── texts/ # 上传的文本文件\n│ ├── cache/ # 流水线缓存\n│ └── db.sqlite # SQLite 数据库\n│\n├── requirements.txt # Python 依赖\n├── .env.example # 配置文件模板\n├── start.sh # 一键启动脚本\n└── README.md\n```\n\n### 技术栈\n\n| 层级 | 技术 |\n|------|------|\n| **Web 框架** | FastAPI + Uvicorn (ASGI) |\n| **模板引擎** | Jinja2 (SSR 渲染) |\n| **前端交互** | HTMX 2.0 (无刷新局部更新) + 原生 JavaScript |\n| **数据库** | SQLite + SQLAlchemy ORM |\n| **AI 后端** | Claude / GPT / DeepSeek / Gemini / 本地模型 |\n| **PDF 生成** | fpdf2 (Courier 12pt + SimSun 中文字体) |\n| **文件解析** | python-docx + markdown |\n| **异步** | Python asyncio (流式 SSE 推送) |\n\n---\n\n## 环境搭建\n\n### 前置要求\n\n- **Python 3.10+**（推荐 3.12）\n- **pip**（Python 包管理器）\n- **Git**（可选，用于克隆仓库）\n\n### 步骤 1：克隆项目\n\n```bash\ngit clone https://github.com/ailakala/script-tool.git\ncd script-tool\n```\n\n如果不想用 Git，也可以直接下载 ZIP 包解压。\n\n### 步骤 2：创建虚拟环境（推荐）\n\n```bash\n# Windows (PowerShell)\npython -m venv venv\n.\\venv\\Scripts\\activate\n\n# macOS / Linux\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n> 虚拟环境可以隔离项目依赖，避免与系统 Python 包冲突。如果不想用虚拟环境，可以跳过此步。\n\n### 步骤 3：安装依赖\n\n```bash\npip install -r requirements.txt\n```\n\n如果安装较慢，可以使用国内镜像：\n\n```bash\npip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/\n```\n\n<details>\n<summary>完整依赖列表（点击展开）</summary>\n\n| 包名 | 版本 | 用途 |\n|------|------|------|\n| `fastapi` | 0.115 | Web 框架 |\n| `uvicorn[standard]` | 0.30 | ASGI 服务器 |\n| `sqlalchemy` | 2.0 | ORM 数据库 |\n| `jinja2` | 3.1 | 模板引擎 |\n| `python-multipart` | 0.0.12 | 文件上传 |\n| `anthropic` | 0.40 | Claude API SDK |\n| `openai` | 1.60 | OpenAI/DeepSeek 兼容 SDK |\n| `google-genai` | 1.14 | Gemini API SDK |\n| `python-docx` | 1.1 | Word 文档解析 |\n| `markdown` | 3.7 | Markdown 解析 |\n| `pyyaml` | 6.0 | YAML 序列化 |\n| `fpdf2` | 2.8 | PDF 生成 |\n| `python-dotenv` | 1.1 | 环境变量管理 |\n| `pytest` | 8.3 | 测试框架 |\n| `httpx` | 0.28 | HTTP 测试客户端 |\n\n</details>\n\n### 步骤 4：配置环境变量\n\n```bash\n# 从模板创建配置文件\ncp .env.example .env\n```\n\n编辑 `.env` 文件，至少需要配置一个 AI 后端的 API Key。详细说明见下一节。\n\n### 步骤 5：启动服务\n\n**方式一：一键启动脚本**\n\n```bash\nbash start.sh\n```\n\n脚本会自动：\n1. 检测首次运行 → 提示编辑 `.env`\n2. 检测跨文件系统环境（WSL / Git Bash）→ 自动重定向数据库路径\n3. 安装缺失的依赖\n4. 启动 Uvicorn 服务器\n\n**方式二：手动启动**\n\n```bash\nuvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n# 访问 http://localhost:8000\n```\n\n**方式三：开发模式启动（支持热重载）**\n\n```bash\n# Windows\npython -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n\n# macOS / Linux\npython3 -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n```\n\n打开浏览器访问 **http://localhost:8000**。\n\n### 各系统特别注意\n\n<details>\n<summary>🪟 Windows 用户</summary>\n\n- 推荐使用 **PowerShell** 或 **Git Bash**\n- 如果使用 Git Bash，启动脚本会自动检测环境，将 SQLite 数据库重定向到 `C:/Users/<用户名>/script_tool.db`\n- 如果手动启动遇到 `database is locked` 错误，请在 `.env` 中设置：\n ```\n SCRIPT_TOOL_DATABASE_URL=sqlite:///C:/Users/你的用户名/script_tool.db\n ```\n\n</details>\n\n<details>\n<summary>🐧 WSL (Windows Subsystem for Linux) 用户</summary>\n\nWSL 跨文件系统访问 Windows 路径时，SQLite 无法正常加锁。解决方案：\n\n1. **方式一**：在 `.env` 中设置 Windows 本机路径\n ```\n SCRIPT_TOOL_DATABASE_URL=sqlite:///C:/Users/你的用户名/script_tool.db\n ```\n2. **方式二**：使用 `start.sh` 启动，脚本自动检测并配置\n\n</details>\n\n<details>\n<summary>🍎 macOS 用户</summary>\n\n- macOS 自带 Python 可能版本较旧，建议用 Homebrew 安装：\n ```bash\n brew install python@3.12\n ```\n- 如果 PDF 生成缺少中文字体，可安装：\n ```bash\n brew install --cask font-simsun\n ```\n\n</details>\n\n---\n\n## API Key 配置详解\n\n整个项目的 AI 能力依赖于 **两大块配置**：流水线剧本生成 和 AI 助手聊天。两者**共用同一套 API Key**，但可以独立配置不同模型。\n\n### 配置文件的加载机制\n\n1. 项目启动时，`app/config.py` 自动读取项目根目录的 `.env` 文件\n2. 所有配置通过环境变量注入，不硬编码在代码中\n3. 环境变量名统一前缀 `SCRIPT_TOOL_` 避免与其他应用冲突\n\n### 一、流水线剧本生成的 API Key\n\n流水线是**自动化的 6 阶段 AI 流程**，每次调用消耗大量 tokens。通过以下两个核心变量控制：\n\n```\nSCRIPT_TOOL_AI_PROVIDER=claude # 选择哪个 AI 后端\nSCRIPT_TOOL_AI_MODEL=claude-sonnet-4-6 # 具体模型名\n```\n\n然后根据你选择的 `SCRIPT_TOOL_AI_PROVIDER`，配置对应的 API Key：\n\n#### 方案 A：Claude API（推荐）\n\n最推荐的选择，中文理解和创意写作能力最强，剧本质量最高。\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=claude\nSCRIPT_TOOL_AI_MODEL=claude-sonnet-4-6\nSCRIPT_TOOL_ANTHROPIC_API_KEY=sk-ant-api03-你的密钥\n```\n\n| 获取地址 | 费用参考 |\n|---------|---------|\n| [console.anthropic.com](https://console.anthropic.com/settings/keys) | $2-5/次完整生成 |\n\n> **模型选择建议**：\n> - `claude-sonnet-4-6`：性价比最优，推荐日常使用\n> - `claude-opus-4-8`：最强质量，长篇小说或复杂剧本\n> - `claude-haiku-4-5`：最快速度，用于测试或简单任务\n\n#### 方案 B：OpenAI GPT\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=openai\nSCRIPT_TOOL_AI_MODEL=gpt-4o\nSCRIPT_TOOL_OPENAI_API_KEY=sk-proj-你的密钥\n```\n\n| 获取地址 | 费用参考 |\n|---------|---------|\n| [platform.openai.com/api-keys](https://platform.openai.com/api-keys) | $0.5-1/次完整生成 |\n\n> 如果你的 OpenAI Key 是通过**第三方代理/中转服务**获取的，需要额外设置：\n> ```bash\n> SCRIPT_TOOL_OPENAI_BASE_URL=https://你的代理地址/v1\n> ```\n> 这个配置也适用于任何 OpenAI 兼容接口（如 Azure OpenAI、OneAPI 等）。\n\n#### 方案 C：DeepSeek（性价比之选）\n\n中文优秀，价格极低，国内网络直连。\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=deepseek\nSCRIPT_TOOL_AI_MODEL=deepseek-chat\nSCRIPT_TOOL_DEEPSEEK_API_KEY=sk-你的密钥\n```\n\n| 获取地址 | 费用参考 |\n|---------|---------|\n| [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys) | ¥0.5-1/次完整生成 |\n\n> 可选模型：`deepseek-chat`（通用）、`deepseek-reasoner`（推理增强，创意写作更佳）。通过 `SCRIPT_TOOL_DEEPSEEK_MODEL` 切换。\n\n#### 方案 D：Google Gemini\n\n免费额度友好，适合测试和轻度使用。\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=gemini\nSCRIPT_TOOL_AI_MODEL=gemini-2.5-flash\nSCRIPT_TOOL_GEMINI_API_KEY=你的密钥\n```\n\n| 获取地址 | 费用参考 |\n|---------|---------|\n| [aistudio.google.com/apikey](https://aistudio.google.com/apikey) | 免费/接近免费 |\n\n> 可选模型：`gemini-2.5-pro`（最强）、`gemini-2.5-flash`（快速推荐）。通过 `SCRIPT_TOOL_GEMINI_MODEL` 切换。\n\n#### 方案 E：本地模型（免费，完全离线）\n\n支持 LM Studio 和 Ollama，数据完全本地处理。\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=local\nSCRIPT_TOOL_AI_MODEL=qwen2.5-7b-instruct\n```\n\n| 工具 | 下载地址 | 推荐模型 |\n|------|---------|---------|\n| LM Studio | [lmstudio.ai](https://lmstudio.ai) | Qwen 2.5 7B / 14B |\n| Ollama | [ollama.com](https://ollama.com) | qwen2.5:7b / deepseek-r1:7b |\n\n> LM Studio 设置：加载模型 → Developer 标签 → Start Server（默认端口 1234），无需额外配置。\n>\n> Ollama 用户需修改端口：\n> ```bash\n> SCRIPT_TOOL_LOCAL_LLM_URL=http://localhost:11434/v1\n> ```\n\n---\n\n### 二、AI 助手的 API Key\n\n项目页面右下角的 💬 **AI 助手聊天面板**支持 5 种模型**实时切换**，无需重启服务。\n\n它的 API Key 配置与流水线使用**同一套环境变量**——只要你配置了哪个 Provider 的 Key，聊天面板中切换过去就能用。\n\n```bash\n# Claude — 和流水线共用这个 Key\nSCRIPT_TOOL_ANTHROPIC_API_KEY=sk-ant-api03-你的密钥\n\n# GPT (OpenAI) — 和流水线共用这个 Key\nSCRIPT_TOOL_OPENAI_API_KEY=sk-proj-你的密钥\n# 可选：自定义 API 地址（如中转/代理）\nSCRIPT_TOOL_OPENAI_BASE_URL=https://你的代理地址/v1\n\n# DeepSeek — 和流水线共用这个 Key\nSCRIPT_TOOL_DEEPSEEK_API_KEY=sk-你的密钥\n\n# Gemini — 和流水线共用这个 Key\nSCRIPT_TOOL_GEMINI_API_KEY=你的密钥\n\n# 本地模型 — LM Studio 端口 1234 已预设\nSCRIPT_TOOL_LOCAL_LLM_URL=http://localhost:1234/v1\nSCRIPT_TOOL_LOCAL_LLM_API_KEY=not-needed\n```\n\n#### AI 助手的快捷功能\n\n聊天面板预设了 4 个快捷操作按钮：\n\n| 按钮 | 功能 |\n|------|------|\n| 中译英 | 将剧本内容翻译成英文 |\n| 英译中 | 将英文内容翻译成中文 |\n| 润色 | 优化文本表达，提升流畅度 |\n| 摘要 | 用简洁语言总结内容 |\n\n#### AI 助手的项目感知能力\n\nAI 助手**自动读取当前项目的流水线数据**作为对话上下文，包括：\n- 项目基本信息（名称、原著、作者、剧本类型）\n- 各 Stage 完成状态\n- 人物列表（姓名、角色定位、描述）\n- 人物关系网络\n- 主线与支线情节\n- 场景结构列表\n- 已生成的剧本内容（前 3000 字符预览）\n\n这意味着你可以直接问 AI 助手：\n- \"主角在第 3 场戏里说了什么？\"\n- \"帮我把第 2 集的场景列表翻译成英文\"\n- \"女配角和男主角是什么关系？\"\n- \"帮我润色 scene_005 的对白\"\n\n#### AI 助手密钥验证\n\n切换模型时，系统会检查对应的环境变量是否已配置。如果未配置，聊天面板会显示错误提示，告诉你需要设置哪个环境变量。\n\n---\n\n### 三、完整 .env 配置示例\n\n以下是一个同时配置了 DeepSeek（流水线）和 Claude（AI 助手）的完整示例：\n\n```bash\n# ═══ 流水线（用 DeepSeek） ═══\nSCRIPT_TOOL_AI_PROVIDER=deepseek\nSCRIPT_TOOL_AI_MODEL=deepseek-chat\nSCRIPT_TOOL_DEEPSEEK_API_KEY=sk-da0c92f36581481cb1321e1cf3c5bf70\n\n# ═══ AI 助手（额外启用 Claude） ═══\nSCRIPT_TOOL_ANTHROPIC_API_KEY=sk-ant-api03-你的claude密钥\n\n# ═══ 可选 ═══\nSCRIPT_TOOL_DATABASE_URL=sqlite:///C:/Users/lenovo/script_tool.db\n```\n\n这样配置后：\n- **流水线**使用 DeepSeek 生成剧本（省钱）\n- **AI 助手**可以在 DeepSeek 和 Claude 之间切换\n- 如果想在 AI 助手中使用 GPT 聊天，再加一行 `SCRIPT_TOOL_OPENAI_API_KEY=...`\n\n---\n\n### 四、API Key 安全建议\n\n1. **❌ 不要把 `.env` 提交到 Git**（已在 `.gitignore` 中排除）\n2. **✅** 生产环境直接设置系统环境变量，不使用 `.env` 文件\n3. **✅** 定期更换 API Key，尤其是在公共网络环境下使用时\n4. **✅** 在 API 平台设置使用额度限制，防止意外超支\n\n---\n\n## 使用指南\n\n### 快速上手（3 步）\n\n1. **新建项目** → 填写项目名称、原著信息、选择剧本类型\n2. **导入小说** → 上传 `.txt` / `.docx` / `.md` 文件，或直接粘贴文本（至少 3 章）\n3. **一键生成** → 6 个阶段自动完成，生成剧本\n\n### 一键生成 vs 分步生成\n\n| 模式 | 特点 | 适用场景 |\n|------|------|---------|\n| 🚀 **一键生成** | 6 阶段全自动，一次完成 | 快速出稿、对 AI 结果有信心 |\n| 📋 **分步生成** | 每阶段可暂停审查 | 需要精细控制、人物众多的长篇小说 |\n\n分步生成模式下，以下阶段完成后会**自动暂停**供你审查：\n\n| 暂停点 | 可审查内容 | 可做什么 |\n|--------|-----------|---------|\n| Stage 1 完成后 | 每章人物、地点、情节 | 检查是否有漏人或错认 |\n| Stage 2 完成后 | 综合人物表、关系图 | 调整关系、修改角色定位 |\n| Stage 3 完成后 | 剧本场景列表 | **拖拽编排场景、增删合并拆分** |\n\n### 场景编排看板（Stage 3）\n\nStage 3 完成后会出现 📋 **编排场景** 链接，点击进入看板：\n\n- **按集分组**：场景自动分集显示，每集一列\n- **拖拽排序**：拖拽场景卡片调整顺序\n- **编辑场景**：点击编辑按钮修改地点、时间、人物、摘要\n- **拆分场景**：长场景可拆分为两场\n- **合并场景**：选中两个场景合并为一个\n- **新增场景**：在任意集末尾添加新场景\n- **自动编号**：保存时自动重新编号（scene_001, scene_002…）\n- **触发 Stage 4**：编排满意后，从看板直接开始生成场景内容\n\n### 查看和导出结果\n\n流水线完成后：\n\n- 📝 **查看/编辑剧本** — 在线预览标准格式剧本，支持编辑保存\n- ⬇ **下载 YAML** — 导出结构化 YAML 数据（机器可读，含完整元数据）\n- ⬇ **下载 PDF** — 导出行业标准排版 PDF（Courier 12pt，适合打印/提交）\n\n---\n\n## 6 阶段流水线详解\n\n```\nStage 0 → Stage 1 → Stage 2 → 🛑暂停 → Stage 3 → 🛑暂停 → Stage 4 → Stage 5\n 5% 30% 10% 10% 40% 5%\n```\n\n### Stage 0 — 文本预处理（权重 5%）\n\n- **输入**：原始小说文本\n- **处理**：正则匹配章节标题（\"第一章\" / \"Chapter 1\" 等），自动拆分章节\n- **输出**：`PreprocessResult`（标题、章节列表、总字数）\n- **支持格式**：`.txt`、`.docx`（自动提取正文）、`.md`（自动转纯文本）\n- **限制**：至少 3 章，最多 50 万字\n\n### Stage 1 — 分章节分析（权重 30%）\n\n- **输入**：Stage 0 输出的章节列表\n- **处理**：N 个章节**并行**调用 AI，逐章提取人物、地点、情节、台词\n- **输出**：`ChapterAnalysis[]`（每章的 new_characters、locations、plot_events、dialogue_excerpts）\n- **进度**：实时显示 \"章节分析 X/N\"\n\n### Stage 2 — 跨章节综合（权重 10%）🛑暂停点\n\n- **输入**：Stage 1 输出的所有章节分析结果\n- **处理**：AI 综合去重，合并同名人物、建立关系网络、梳理主线支线\n- **输出**：`GlobalAnalysis`\n - `characters`：综合人物表（姓名、别名、定位、性格标签、首次出场章节）\n - `relationships`：人物关系网络（A → B，关系类型，描述）\n - `locations`：场景目录\n - `main_plot`：主线情节概述\n - `subplots`：支线列表\n\n### Stage 3 — 剧本结构设计（权重 10%）🛑暂停点\n\n- **输入**：Stage 2 输出的综合人物与情节分析\n- **处理**：AI 设计场景列表，规划每场的地点、时间、出场人物、内容概要\n- **输出**：`ScriptStructure`\n - `scenes`：场景计划列表（含 act/episode/sequence/location/characters/summary）\n - `episode_summaries`：集摘要（电视剧模式）\n - `beat_sheet`：节拍表（电影编剧术语）\n\n### Stage 4 — 逐场内容生成（权重 40%）\n\n- **输入**：Stage 3 输出的场景计划 + Stage 2 人物表 + Stage 0 原始章节文本\n- **处理**：M 个场景**并行**调用 AI，生成完整的动作描写、对白、旁白、转场\n- **输出**：`GeneratedScene[]`（标准剧本格式：scene_heading + content[]，含多类型内容元素）\n- **容错**：空场景自动跳过，不中断流水线\n- **进度**：实时显示 \"场景生成 X/M\"\n\n### Stage 5 — 组装 & 校验（权重 5%）\n\n- **输入**：所有前序阶段的输出\n- **处理**：\n 1. 构建标准人物表（含 id、name、role、traits）\n 2. 组装 YAML 结构化输出（meta + config + characters + scenes）\n 3. 转换为**行业标准中文剧本格式**（角色名对齐、场次标题、动作/对白/旁白分离）\n- **输出**：`AssemblyResult`（yaml_text + screenplay_text + warnings）\n- **校验**：检查必填字段完整性，输出警告信息\n\n---\n\n## 功能模块说明\n\n### 文件导入模块（Stage 0 预处理）\n\n| 格式 | 解析方式 | 说明 |\n|------|---------|------|\n| `.txt` | 正则拆分章节 | 中文（\"第X章\"）和英文（\"Chapter X\"）模式均支持 |\n| `.docx` | python-docx 提取 | 自动提取所有段落文本，处理 Word 特殊格式 |\n| `.md` | markdown 转纯文本 | 先转 HTML 再去除标签，保留纯文本内容 |\n| 直接粘贴 | 同 `.txt` | 最长 50 万字限制，textarea 粘贴即可 |\n\n### 缓存与断点续传\n\n每阶段结果自动以 **input_hash** 为键缓存到 SQLite：\n- 同一内容的同一阶段不重复调用 AI（节省时间和费用）\n- 重置缓存后重新运行会重新生成\n- 分步模式暂停期间，已完成阶段不受影响\n\n### 安全机制\n\n| 机制 | 说明 |\n|------|------|\n| 心跳检测 | SSE 连接 30 秒无响应自动断连 |\n| 自动重试 | Stage 4 场景生成失败自动重试（最多 2 次） |\n| 空场景跳过 | AI 返回空内容的场景自动过滤，带警告提示 |\n| 速率限制 | 并发 AI 调用自动限流（asyncio.Semaphore） |\n\n---\n\n## API 接口文档\n\n### 页面路由（Pages）\n\n| 路由 | 说明 |\n|------|------|\n| `GET /` | 首页，项目列表 |\n| `GET /projects/new` | 新建项目页面 |\n| `GET /projects/{id}` | 项目工作台 |\n| `GET /projects/{id}/stage/{n}` | Stage N 中间结果审查 |\n| `GET /projects/{id}/stage3/kanban` | 场景编排看板 |\n| `GET /projects/{id}/characters` | 人物关系图谱 |\n| `GET /projects/{id}/script` | 在线剧本查看/编辑 |\n\n### REST API\n\n| 方法 | 路由 | 说明 |\n|------|------|------|\n| `POST` | `/api/projects` | 创建项目 |\n| `POST` | `/api/projects/{id}/upload` | 上传小说文件 |\n| `POST` | `/api/projects/{id}/paste` | 粘贴小说文本 |\n| `GET` | `/api/projects/{id}/text` | 获取已保存的文本 |\n| `POST` | `/api/projects/{id}/run` | **一键生成**（SSE 流式） |\n| `POST` | `/api/projects/{id}/run-stage/{n}` | **分步生成**单阶段（SSE 流式） |\n| `GET` | `/api/projects/{id}/stage/{n}` | 获取阶段缓存数据 |\n| `PUT` | `/api/projects/{id}/stage/5` | 保存编辑后的剧本 |\n| `POST` | `/api/projects/{id}/clear-cache` | 清除缓存（`?stage=N` 可选） |\n| `DELETE` | `/api/projects/{id}` | 删除项目 |\n| `GET` | `/api/projects/{id}/script.yaml` | 下载 YAML |\n| `GET` | `/api/projects/{id}/script.pdf` | 下载 PDF |\n| `GET` | `/api/projects/{id}/character-graph` | 人物关系图谱数据 |\n| `GET` | `/api/projects/{id}/scenes` | 获取场景列表（看板用） |\n| `PUT` | `/api/projects/{id}/scenes` | 保存场景列表（看板用） |\n| `POST` | `/api/projects/{id}/scenes/split/{scene_id}` | 拆分场景 |\n| `POST` | `/api/projects/{id}/scenes/merge` | 合并场景 |\n| `POST` | `/api/projects/{id}/chat` | AI 助手聊天（SSE 流式） |\n\n### SSE 事件格式\n\n所有流式接口（`/run`、`/run-stage`、`/chat`）均使用以下格式：\n\n```\ndata: {\"message\": \"正在分析...\", \"percent\": 15, \"current_stage\": 1, \"stage_status\": {...}}\ndata: {\"status\": \"complete\", \"yaml_text\": \"...\", \"screenplay_text\": \"...\"}\n```\n\n前端通过 `EventSource` / `fetch + ReadableStream` 消费事件流，实时更新进度条和阶段状态。\n\n---\n\n## 常见问题\n\n### 启动与连接\n\n**Q: 启动后浏览器打不开 http://localhost:8000？**\n\nA: 检查以下项目：\n1. 确认 Uvicorn 已正常启动（终端有 `Uvicorn running on http://0.0.0.0:8000` 提示）\n2. 确认端口 8000 未被占用：`netstat -ano | findstr 8000`（Windows）/ `lsof -i :8000`（macOS/Linux）\n3. 尝试换端口：`--port 8001`\n\n**Q: WSL / Git Bash 启动报 `database is locked`？**\n\nA: 这是跨文件系统 SQLite 锁问题，解决方案：\n1. 在 `.env` 中设置 Windows 路径：`SCRIPT_TOOL_DATABASE_URL=sqlite:///C:/Users/你的用户名/script_tool.db`\n2. 或使用 `start.sh` 启动，脚本会自动处理\n\n### AI 配置\n\n**Q: 一键生成报错 \"API Key 无效\"？**\n\nA: 检查 `.env` 文件中的 API Key 是否正确：\n- Claude：以 `sk-ant-api03-` 开头\n- OpenAI：以 `sk-proj-` 或 `sk-` 开头\n- DeepSeek：以 `sk-` 开头\n- Gemini：无固定前缀\n\n**Q: 本地模型（LM Studio）连接失败？**\n\nA: 检查：\n1. LM Studio → Developer 标签 → **Start Server** 是否已启动\n2. 端口是否为 **1234**（默认不要改）\n3. 模型名是否与 LM Studio 中加载的一致\n\n**Q: 能不能流水线用 DeepSeek，AI 助手用 Claude？**\n\nA: 完全可以。同时配置两者的 API Key：\n```bash\nSCRIPT_TOOL_AI_PROVIDER=deepseek\nSCRIPT_TOOL_DEEPSEEK_API_KEY=sk-xxx\nSCRIPT_TOOL_ANTHROPIC_API_KEY=sk-ant-api03-xxx\n```\n流水线使用 DeepSeek，AI 助手下拉菜单选择 Claude 即可。\n\n### 剧本生成\n\n**Q: 一次能处理多长的小说？**\n\nA: 建议 20 章以内、50 万字以内。更长的小说可以：\n1. 分成多个项目分批处理\n2. 减少 Stage 3 的场景数（在看板中手动精简）\n\n**Q: Stage 4 场景内容为空怎么办？**\n\nA: 系统已内置自动跳过机制——空场景会被过滤并显示警告，不会中断流水线。如果大量场景为空：\n1. 尝试换用其他 AI 模型\n2. 在 Stage 3 看板中减少场景复杂度\n3. 清除 Stage 4 缓存后重试\n\n**Q: 生成过程很慢？**\n\nA: Stage 1 和 Stage 4 是并行处理的，耗时取决于 AI API 响应速度和并发数。建议：\n- 使用 DeepSeek 或本地模型（响应速度更快）\n- 减少场景数（在 Stage 3 看板中精简）\n\n### 数据\n\n**Q: 数据存在哪里？**\n\nA: 所有数据存储在 `storage/` 目录：\n- `storage/db.sqlite` — SQLite 数据库（项目、缓存、运行记录）\n- `storage/texts/` — 上传的文本文件\n- 支持通过 `SCRIPT_TOOL_DATABASE_URL` 自定义数据库路径\n\n**Q: 如何备份数据？**\n\nA: 复制整个 `storage/` 目录即可，包含所有项目数据、缓存和文本文件。\n\n---\n\n## 开发指南\n\n### 运行测试\n\n```bash\npytest tests/ -v\n# 35+ 测试用例，覆盖核心流水线和 API\n```\n\n### 代码规范\n\n- Python 3.10+ 类型注解（`dataclass` 数据模型）\n- FastAPI 依赖注入（`Depends(get_db)` 数据库会话）\n- AI Provider 统一 `async` 接口（`generate` + `generate_stream`）\n- 前端使用 HTMX + 原生 JavaScript（无框架依赖）\n\n### 添加新的 AI Provider\n\n1. 在 `app/ai/` 下创建新文件，继承 `AIProvider` 接口\n2. 实现 `generate()`、`generate_stream()`、`model_name()` 三个方法\n3. 在 `app/config.py` 添加对应的环境变量\n4. 在 `app/ai/factory.py` 的 `create_ai_provider()` 中添加分支\n5. 在 `app/routes/chat.py` 的 `PROVIDER_KEY_MAP` 中注册密钥检查\n\n### 项目配置\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `MAX_UPLOAD_BYTES` | 10 MB | 文件上传大小限制 |\n| `MAX_PASTE_CHARS` | 500,000 | 粘贴文本字数限制 |\n| `DATABASE_URL` | 自动检测 | SQLite 数据库路径 |\n\n---\n\n## 许可证\n\nMIT License\n"}, "9c834b9d0264f84acedafe25e362a31ca9c93b8b": {"t": 1785764188.0833359, "n": 18154, "h": "a3eb69c3e6a0e07c", "c": "视频介绍：1.51 复制打开抖音，看看【用户7344779806406的作品】七牛云☁竞赛视频 # 七牛云 # aicoding... https://v.douyin.com/09iMpaV-8JA/ :9pm 08/24 E@u.SY KJv:/ \nhttps://v.douyin.com/09iMpaV-8JA/\n\n# 🎬 AI 剧本创作工具\n\n将小说文本（≥3 章）自动转换为**结构化 YAML 剧本**和**行业标准格式剧本**，支持电影、电视剧、舞台剧、动画等多种类型。\n\n---\n\n## 目录\n\n- [功能概览](#功能概览)\n- [项目架构](#项目架构)\n- [环境搭建](#环境搭建)\n- [API Key 配置详解](#api-key-配置详解)\n- [使用指南](#使用指南)\n- [6 阶段流水线详解](#6-阶段流水线详解)\n- [功能模块说明](#功能模块说明)\n- [API 接口文档](#api-接口文档)\n- [常见问题](#常见问题)\n- [开发指南](#开发指南)\n\n---\n\n## 功能概览\n\n### 核心功能\n\n| 模块 | 说明 |\n|------|------|\n| 📂 **文件导入** | 支持 `.txt` / `.docx` / `.md` 格式上传，或直接粘贴小说文本（最多 50 万字） |\n| ⚡ **一键生成** | 6 阶段全自动流水线，从文本解析到剧本导出全程 AI 驱动 |\n| 📋 **分步生成** | 逐阶段执行，每步可暂停审查 AI 中间结果（人物、情节、场景结构） |\n| 🕸 **场景编排看板** | Stage 3 完成后提供拖拽式场景看板，自由增删合并拆分场景 |\n| 📝 **在线编辑** | 生成的剧本支持在线预览和编辑，实时保存 |\n| ⬇ **多格式导出** | 支持 YAML（结构化数据）和 PDF（行业标准排版）双格式导出 |\n| 💬 **AI 助手** | 右下角聊天面板，支持翻译、润色、摘要等快捷操作，5 种模型自由切换 |\n| 🔄 **断点续传** | 每阶段结果自动缓存，重新开始或切换模型后已完成阶段无需重跑 |\n\n### 支持的剧本类型\n\n- 电影剧本（Film）\n- 电视剧剧本（TV Series）— 支持多集场景编排\n- 动画剧本（Animation）\n- 舞台剧剧本（Stage Play）\n- 自定义（Custom）\n\n---\n\n## 项目架构\n\n```\nscript-tool/\n├── app/\n│ ├── main.py # FastAPI 入口，挂载静态文件与路由\n│ ├── config.py # 配置中心：环境变量加载、路径管理\n│ ├── models.py # 数据模型：Project / PipelineRun / StageCache\n│ ├── db.py # SQLite 数据库引擎与会话管理\n│ │\n│ ├── ai/ # AI 后端抽象层（5 种 Provider）\n│ │ ├── interface.py # AIProvider 抽象接口\n│ │ ├── factory.py # Provider 工厂函数\n│ │ ├── claude.py # Anthropic Claude API\n│ │ ├── openai.py # OpenAI GPT (兼容自定义 base_url)\n│ │ ├── deepseek.py # DeepSeek (OpenAI 兼容协议)\n│ │ ├── gemini.py # Google Gemini\n│ │ └── local.py # 本地模型 (LM Studio / Ollama)\n│ │\n│ ├── pipeline/ # 6 阶段流水线引擎\n│ │ ├── executor.py # 流水线调度器（含缓存、进度、重试逻辑）\n│ │ ├── stage0_preprocess.py # Stage 0: 文本预处理（章节拆分）\n│ │ ├── stage1_chapter_analysis.py # Stage 1: 分章节分析\n│ │ ├── stage2_cross_chapter_synthesis.py # Stage 2: 跨章节综合\n│ │ ├── stage3_script_structure.py # Stage 3: 剧本结构设计\n│ │ ├── stage4_scene_generation.py # Stage 4: 逐场内容生成\n│ │ ├── stage5_assembly.py # Stage 5: YAML 组装 & 标准格式转换\n│ │ ├── pdf_export.py # PDF 导出（行业标准排版）\n│ │ └── utils.py # JSON 提取等工具函数\n│ │\n│ ├── routes/ # HTTP 路由层\n│ │ ├── pages.py # 页面路由（Jinja2 SSR）\n│ │ ├── api.py # REST API + SSE 流式接口\n│ │ └── chat.py # AI 助手聊天接口\n│ │\n│ └── templates/ # Jinja2 模板\n│ ├── base.html # 基础布局（导航栏、粒子背景）\n│ ├── index.html # 首页（项目列表）\n│ ├── project_new.html # 新建项目\n│ ├── project.html # 项目工作台（核心页面）\n│ ├── stage_review.html # 中间结果审查\n│ ├── stage3_kanban.html # 场景编排看板\n│ ├── character_graph.html # 人物关系图谱\n│ └── script_view.html # 在线剧本查看/编辑\n│\n├── static/\n│ ├── css/style.css # 全局样式（暗色科技主题）\n│ ├── js/\n│ │ ├── htmx.min.js # HTMX 前端交互库\n│ │ └── particles.js # 粒子背景动画\n│ └── img/\n│ └── logo.svg # 品牌 Logo\n│\n├── storage/ # 运行时数据（自动创建）\n│ ├── texts/ # 上传的文本文件\n│ ├── cache/ # 流水线缓存\n│ └── db.sqlite # SQLite 数据库\n│\n├── requirements.txt # Python 依赖\n├── .env.example # 配置文件模板\n├── start.sh # 一键启动脚本\n└── README.md\n```\n\n### 技术栈\n\n| 层级 | 技术 |\n|------|------|\n| **Web 框架** | FastAPI + Uvicorn (ASGI) |\n| **模板引擎** | Jinja2 (SSR 渲染) |\n| **前端交互** | HTMX 2.0 (无刷新局部更新) + 原生 JavaScript |\n| **数据库** | SQLite + SQLAlchemy ORM |\n| **AI 后端** | Claude / GPT / DeepSeek / Gemini / 本地模型 |\n| **PDF 生成** | fpdf2 (Courier 12pt + SimSun 中文字体) |\n| **文件解析** | python-docx + markdown |\n| **异步** | Python asyncio (流式 SSE 推送) |\n\n---\n\n## 环境搭建\n\n### 前置要求\n\n- **Python 3.10+**（推荐 3.12）\n- **pip**（Python 包管理器）\n- **Git**（可选，用于克隆仓库）\n\n### 步骤 1：克隆项目\n\n```bash\ngit clone https://github.com/ailakala/script-tool.git\ncd script-tool\n```\n\n如果不想用 Git，也可以直接下载 ZIP 包解压。\n\n### 步骤 2：创建虚拟环境（推荐）\n\n```bash\n# Windows (PowerShell)\npython -m venv venv\n.\\venv\\Scripts\\activate\n\n# macOS / Linux\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n> 虚拟环境可以隔离项目依赖，避免与系统 Python 包冲突。如果不想用虚拟环境，可以跳过此步。\n\n### 步骤 3：安装依赖\n\n```bash\npip install -r requirements.txt\n```\n\n如果安装较慢，可以使用国内镜像：\n\n```bash\npip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/\n```\n\n<details>\n<summary>完整依赖列表（点击展开）</summary>\n\n| 包名 | 版本 | 用途 |\n|------|------|------|\n| `fastapi` | 0.115 | Web 框架 |\n| `uvicorn[standard]` | 0.30 | ASGI 服务器 |\n| `sqlalchemy` | 2.0 | ORM 数据库 |\n| `jinja2` | 3.1 | 模板引擎 |\n| `python-multipart` | 0.0.12 | 文件上传 |\n| `anthropic` | 0.40 | Claude API SDK |\n| `openai` | 1.60 | OpenAI/DeepSeek 兼容 SDK |\n| `google-genai` | 1.14 | Gemini API SDK |\n| `python-docx` | 1.1 | Word 文档解析 |\n| `markdown` | 3.7 | Markdown 解析 |\n| `pyyaml` | 6.0 | YAML 序列化 |\n| `fpdf2` | 2.8 | PDF 生成 |\n| `python-dotenv` | 1.1 | 环境变量管理 |\n| `pytest` | 8.3 | 测试框架 |\n| `httpx` | 0.28 | HTTP 测试客户端 |\n\n</details>\n\n### 步骤 4：配置环境变量\n\n```bash\n# 从模板创建配置文件\ncp .env.example .env\n```\n\n编辑 `.env` 文件，至少需要配置一个 AI 后端的 API Key。详细说明见下一节。\n\n### 步骤 5：启动服务\n\n**方式一：一键启动脚本**\n\n```bash\nbash start.sh\n```\n\n脚本会自动：\n1. 检测首次运行 → 提示编辑 `.env`\n2. 检测跨文件系统环境（WSL / Git Bash）→ 自动重定向数据库路径\n3. 安装缺失的依赖\n4. 启动 Uvicorn 服务器\n\n**方式二：手动启动**\n\n```bash\nuvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n# 访问 http://localhost:8000\n```\n\n**方式三：开发模式启动（支持热重载）**\n\n```bash\n# Windows\npython -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n\n# macOS / Linux\npython3 -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n```\n\n打开浏览器访问 **http://localhost:8000**。\n\n### 各系统特别注意\n\n<details>\n<summary>🪟 Windows 用户</summary>\n\n- 推荐使用 **PowerShell** 或 **Git Bash**\n- 如果使用 Git Bash，启动脚本会自动检测环境，将 SQLite 数据库重定向到 `C:/Users/<用户名>/script_tool.db`\n- 如果手动启动遇到 `database is locked` 错误，请在 `.env` 中设置：\n ```\n SCRIPT_TOOL_DATABASE_URL=sqlite:///C:/Users/你的用户名/script_tool.db\n ```\n\n</details>\n\n<details>\n<summary>🐧 WSL (Windows Subsystem for Linux) 用户</summary>\n\nWSL 跨文件系统访问 Windows 路径时，SQLite 无法正常加锁。解决方案：\n\n1. **方式一**：在 `.env` 中设置 Windows 本机路径\n ```\n SCRIPT_TOOL_DATABASE_URL=sqlite:///C:/Users/你的用户名/script_tool.db\n ```\n2. **方式二**：使用 `start.sh` 启动，脚本自动检测并配置\n\n</details>\n\n<details>\n<summary>🍎 macOS 用户</summary>\n\n- macOS 自带 Python 可能版本较旧，建议用 Homebrew 安装：\n ```bash\n brew install python@3.12\n ```\n- 如果 PDF 生成缺少中文字体，可安装：\n ```bash\n brew install --cask font-simsun\n ```\n\n</details>\n\n---\n\n## API Key 配置详解\n\n整个项目的 AI 能力依赖于 **两大块配置**：流水线剧本生成 和 AI 助手聊天。两者**共用同一套 API Key**，但可以独立配置不同模型。\n\n### 配置文件的加载机制\n\n1. 项目启动时，`app/config.py` 自动读取项目根目录的 `.env` 文件\n2. 所有配置通过环境变量注入，不硬编码在代码中\n3. 环境变量名统一前缀 `SCRIPT_TOOL_` 避免与其他应用冲突\n\n### 一、流水线剧本生成的 API Key\n\n流水线是**自动化的 6 阶段 AI 流程**，每次调用消耗大量 tokens。通过以下两个核心变量控制：\n\n```\nSCRIPT_TOOL_AI_PROVIDER=claude # 选择哪个 AI 后端\nSCRIPT_TOOL_AI_MODEL=claude-sonnet-4-6 # 具体模型名\n```\n\n然后根据你选择的 `SCRIPT_TOOL_AI_PROVIDER`，配置对应的 API Key：\n\n#### 方案 A：Claude API（推荐）\n\n最推荐的选择，中文理解和创意写作能力最强，剧本质量最高。\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=claude\nSCRIPT_TOOL_AI_MODEL=claude-sonnet-4-6\nSCRIPT_TOOL_ANTHROPIC_API_KEY=sk-ant-api03-你的密钥\n```\n\n| 获取地址 | 费用参考 |\n|---------|---------|\n| [console.anthropic.com](https://console.anthropic.com/settings/keys) | $2-5/次完整生成 |\n\n> **模型选择建议**：\n> - `claude-sonnet-4-6`：性价比最优，推荐日常使用\n> - `claude-opus-4-8`：最强质量，长篇小说或复杂剧本\n> - `claude-haiku-4-5`：最快速度，用于测试或简单任务\n\n#### 方案 B：OpenAI GPT\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=openai\nSCRIPT_TOOL_AI_MODEL=gpt-4o\nSCRIPT_TOOL_OPENAI_API_KEY=sk-proj-你的密钥\n```\n\n| 获取地址 | 费用参考 |\n|---------|---------|\n| [platform.openai.com/api-keys](https://platform.openai.com/api-keys) | $0.5-1/次完整生成 |\n\n> 如果你的 OpenAI Key 是通过**第三方代理/中转服务**获取的，需要额外设置：\n> ```bash\n> SCRIPT_TOOL_OPENAI_BASE_URL=https://你的代理地址/v1\n> ```\n> 这个配置也适用于任何 OpenAI 兼容接口（如 Azure OpenAI、OneAPI 等）。\n\n#### 方案 C：DeepSeek（性价比之选）\n\n中文优秀，价格极低，国内网络直连。\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=deepseek\nSCRIPT_TOOL_AI_MODEL=deepseek-chat\nSCRIPT_TOOL_DEEPSEEK_API_KEY=sk-你的密钥\n```\n\n| 获取地址 | 费用参考 |\n|---------|---------|\n| [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys) | ¥0.5-1/次完整生成 |\n\n> 可选模型：`deepseek-chat`（通用）、`deepseek-reasoner`（推理增强，创意写作更佳）。通过 `SCRIPT_TOOL_DEEPSEEK_MODEL` 切换。\n\n#### 方案 D：Google Gemini\n\n免费额度友好，适合测试和轻度使用。\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=gemini\nSCRIPT_TOOL_AI_MODEL=gemini-2.5-flash\nSCRIPT_TOOL_GEMINI_API_KEY=你的密钥\n```\n\n| 获取地址 | 费用参考 |\n|---------|---------|\n| [aistudio.google.com/apikey](https://aistudio.google.com/apikey) | 免费/接近免费 |\n\n> 可选模型：`gemini-2.5-pro`（最强）、`gemini-2.5-flash`（快速推荐）。通过 `SCRIPT_TOOL_GEMINI_MODEL` 切换。\n\n#### 方案 E：本地模型（免费，完全离线）\n\n支持 LM Studio 和 Ollama，数据完全本地处理。\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=local\nSCRIPT_TOOL_AI_MODEL=qwen2.5-7b-instruct\n```\n\n| 工具 | 下载地址 | 推荐模型 |\n|------|---------|---------|\n| LM Studio | [lmstudio.ai](https://lmstudio.ai) | Qwen 2.5 7B / 14B |\n| Ollama | [ollama.com](https://ollama.com) | qwen2.5:7b / deepseek-r1:7b |\n\n> LM Studio 设置：加载模型 → Developer 标签 → Start Server（默认端口 1234），无需额外配置。\n>\n> Ollama 用户需修改端口：\n> ```bash\n> SCRIPT_TOOL_LOCAL_LLM_URL=http://localhost:11434/v1\n> ```\n\n---\n\n### 二、AI 助手的 API Key\n\n项目页面右下角的 💬 **AI 助手聊天面板**支持 5 种模型**实时切换**，无需重启服务。\n\n它的 API Key 配置与流水线使用**同一套环境变量**——只要你配置了哪个 Provider 的 Key，聊天面板中切换过去就能用。\n\n```bash\n# Claude — 和流水线共用这个 Key\nSCRIPT_TOOL_ANTHROPIC_API_KEY=sk-ant-api03-你的密钥\n\n# GPT (OpenAI) — 和流水线共用这个 Key\nSCRIPT_TOOL_OPENAI_API_KEY=sk-proj-你的密钥\n# 可选：自定义 API 地址（如中转/代理）\nSCRIPT_TOOL_OPENAI_BASE_URL=https://你的代理地址/v1\n\n# DeepSeek — 和流水线共用这个 Key\nSCRIPT_TOOL_DEEPSEEK_API_KEY=sk-你的密钥\n\n# Gemini — 和流水线共用这个 Key\nSCRIPT_TOOL_GEMINI_API_KEY=你的密钥\n\n# 本地模型 — LM Studio 端口 1234 已预设\nSCRIPT_TOOL_LOCAL_LLM_URL=http://localhost:1234/v1\nSCRIPT_TOOL_LOCAL_LLM_API_KEY=not-needed\n```\n\n#### AI 助手的快捷功能\n\n聊天面板预设了 4 个快捷操作按钮：\n\n| 按钮 | 功能 |\n|------|------|\n| 中译英 | 将剧本内容翻译成英文 |\n| 英译中 | 将英文内容翻译成中文 |\n| 润色 | 优化文本表达，提升流畅度 |\n| 摘要 | 用简洁语言总结内容 |\n\n#### AI 助手的项目感知能力\n\nAI 助手**自动读取当前项目的流水线数据**作为对话上下文，包括：\n- 项目基本信息（名称、原著、作者、剧本类型）\n- 各 Stage 完成状态\n- 人物列表（姓名、角色定位、描述）\n- 人物关系网络\n- 主线与支线情节\n- 场景结构列表\n- 已生成的剧本内容（前 3000 字符预览）\n\n这意味着你可以直接问 AI 助手：\n- \"主角在第 3 场戏里说了什么？\"\n- \"帮我把第 2 集的场景列表翻译成英文\"\n- \"女配角和男主角是什么关系？\"\n- \"帮我润色 scene_005 的对白\"\n\n#### AI 助手密钥验证\n\n切换模型时，系统会检查对应的环境变量是否已配置。如果未配置，聊天面板会显示错误提示，告诉你需要设置哪个环境变量。\n\n---\n\n### 三、完整 .env 配置示例\n\n以下是一个同时配置了 DeepSeek（流水线）和 Claude（AI 助手）的完整示例：\n\n```bash\n# ═══ 流水线（用 DeepSeek） ═══\nSCRIPT_TOOL_AI_PROVIDER=deepseek\nSCRIPT_TOOL_AI_MODEL=deepseek-chat\nSCRIPT_TOOL_DEEPSEEK_API_KEY=sk-da0c92f36581481cb1321e1cf3c5bf70\n\n# ═══ AI 助手（额外启用 Claude） ═══\nSCRIPT_TOOL_ANTHROPIC_API_KEY=sk-ant-api03-你的claude密钥\n\n# ═══ 可选 ═══\nSCRIPT_TOOL_DATABASE_URL=sqlite:///C:/Users/lenovo/script_tool.db\n```\n\n这样配置后：\n- **流水线**使用 DeepSeek 生成剧本（省钱）\n- **AI 助手**可以在 DeepSeek 和 Claude 之间切换\n- 如果想在 AI 助手中使用 GPT 聊天，再加一行 `SCRIPT_TOOL_OPENAI_API_KEY=...`\n\n---\n\n### 四、API Key 安全建议\n\n1. **❌ 不要把 `.env` 提交到 Git**（已在 `.gitignore` 中排除）\n2. **✅** 生产环境直接设置系统环境变量，不使用 `.env` 文件\n3. **✅** 定期更换 API Key，尤其是在公共网络环境下使用时\n4. **✅** 在 API 平台设置使用额度限制，防止意外超支\n\n---\n\n## 使用指南\n\n### 快速上手（3 步）\n\n1. **新建项目** → 填写项目名称、原著信息、选择剧本类型\n2. **导入小说** → 上传 `.txt` / `.docx` / `.md` 文件，或直接粘贴文本（至少 3 章）\n3. **一键生成** → 6 个阶段自动完成，生成剧本\n\n### 一键生成 vs 分步生成\n\n| 模式 | 特点 | 适用场景 |\n|------|------|---------|\n| 🚀 **一键生成** | 6 阶段全自动，一次完成 | 快速出稿、对 AI 结果有信心 |\n| 📋 **分步生成** | 每阶段可暂停审查 | 需要精细控制、人物众多的长篇小说 |\n\n分步生成模式下，以下阶段完成后会**自动暂停**供你审查：\n\n| 暂停点 | 可审查内容 | 可做什么 |\n|--------|-----------|---------|\n| Stage 1 完成后 | 每章人物、地点、情节 | 检查是否有漏人或错认 |\n| Stage 2 完成后 | 综合人物表、关系图 | 调整关系、修改角色定位 |\n| Stage 3 完成后 | 剧本场景列表 | **拖拽编排场景、增删合并拆分** |\n\n### 场景编排看板（Stage 3）\n\nStage 3 完成后会出现 📋 **编排场景** 链接，点击进入看板：\n\n- **按集分组**：场景自动分集显示，每集一列\n- **拖拽排序**：拖拽场景卡片调整顺序\n- **编辑场景**：点击编辑按钮修改地点、时间、人物、摘要\n- **拆分场景**：长场景可拆分为两场\n- **合并场景**：选中两个场景合并为一个\n- **新增场景**：在任意集末尾添加新场景\n- **自动编号**：保存时自动重新编号（scene_001, scene_002…）\n- **触发 Stage 4**：编排满意后，从看板直接开始生成场景内容\n\n### 查看和导出结果\n\n流水线完成后：\n\n- 📝 **查看/编辑剧本** — 在线预览标准格式剧本，支持编辑保存\n- ⬇ **下载 YAML** — 导出结构化 YAML 数据（机器可读，含完整元数据）\n- ⬇ **下载 PDF** — 导出行业标准排版 PDF（Courier 12pt，适合打印/提交）\n\n---\n\n## 6 阶段流水线详解\n\n```\nStage 0 → Stage 1 → Stage 2 → 🛑暂停 → Stage 3 → 🛑暂停 → Stage 4 → Stage 5\n 5% 30% 10% 10% 40% 5%\n```\n\n### Stage 0 — 文本预处理（权重 5%）\n\n- **输入**：原始小说文本\n- **处理**：正则匹配章节标题（\"第一章\" / \"Chapter 1\" 等），自动拆分章节\n- **输出**：`PreprocessResult`（标题、章节列表、总字数）\n- **支持格式**：`.txt`、`.docx`（自动提取正文）、`.md`（自动转纯文本）\n- **限制**：至少 3 章，最多 50 万字\n\n### Stage 1 — 分章节分析（权重 30%）\n\n- **输入**：Stage 0 输出的章节列表\n- **处理**：N 个章节**并行**调用 AI，逐章提取人物、地点、情节、台词\n- **输出**：`ChapterAnalysis[]`（每章的 new_characters、locations、plot_events、dialogue_excerpts）\n- **进度**：实时显示 \"章节分析 X/N\"\n\n### Stage 2 — 跨章节综合（权重 10%）🛑暂停点\n\n- **输入**：Stage 1 输出的所有章节分析结果\n- **处理**：AI 综合去重，合并同名人物、建立关系网络、梳理主线支线\n- **输出**：`GlobalAnalysis`\n - `characters`：综合人物表（姓名、别名、定位、性格标签、首次出场章节）\n - `relationships`：人物关系网络（A → B，关系类型，描述）\n - `locations`：场景目录\n - `main_plot`：主线情节概述\n - `subplots`：支线列表\n\n### Stage 3 — 剧本结构设计（权重 10%）🛑暂停点\n\n- **输入**：Stage 2 输出的综合人物与情节分析\n- **处理**：AI 设计场景列表，规划每场的地点、时间、出场人物、内容概要\n- **输出**：`ScriptStructure`\n - `scenes`：场景计划列表（含 act/episode/sequence/location/characters/summary）\n - `episode_summaries`：集摘要（电视剧模式）\n - `beat_sheet`：节拍表（电影编剧术语）\n\n### Stage 4 — 逐场内容生成（权重 40%）\n\n- **输入**：Stage 3 输出的场景计划 + Stage 2 人物表 + Stage 0 原始章节文本\n- **处理**：M 个场景**并行**调用 AI，生成完整的动作描写、对白、旁白、转场\n- **输出**：`GeneratedScene[]`（标准剧本格式：scene_heading + content[]，含多类型内容元素）\n- **容错**：空场景自动跳过，不中断流水线\n- **进度**：实时显示 \"场景生成 X/M\"\n\n### Stage 5 — 组装 & 校验（权重 5%）\n\n- **输入**：所有前序阶段的输出\n- **处理**：\n 1. 构建标准人物表（含 id、name、role、traits）\n 2. 组装 YAML 结构化输出（meta + config + characters + scenes）\n 3. 转换为**行业标准中文剧本格式**（角色名对齐、场次标题、动作/对白/旁白分离）\n- **输出**：`AssemblyResult`（yaml_text + screenplay_text + warnings）\n- **校验**：检查必填字段完整性，输出警告信息\n\n---\n\n## 功能模块说明\n\n### 文件导入模块（Stage 0 预处理）\n\n| 格式 | 解析方式 | 说明 |\n|------|---------|------|\n| `.txt` | 正则拆分章节 | 中文（\"第X章\"）和英文（\"Chapter X\"）模式均支持 |\n| `.docx` | python-docx 提取 | 自动提取所有段落文本，处理 Word 特殊格式 |\n| `.md` | markdown 转纯文本 | 先转 HTML 再去除标签，保留纯文本内容 |\n| 直接粘贴 | 同 `.txt` | 最长 50 万字限制，textarea 粘贴即可 |\n\n### 缓存与断点续传\n\n每阶段结果自动以 **input_hash** 为键缓存到 SQLite：\n- 同一内容的同一阶段不重复调用 AI（节省时间和费用）\n- 重置缓存后重新运行会重新生成\n- 分步模式暂停期间，已完成阶段不受影响\n\n### 安全机制\n\n| 机制 | 说明 |\n|------|------|\n| 心跳检测 | SSE 连接 30 秒无响应自动断连 |\n| 自动重试 | Stage 4 场景生成失败自动重试（最多 2 次） |\n| 空场景跳过 | AI 返回空内容的场景自动过滤，带警告提示 |\n| 速率限制 | 并发 AI 调用自动限流（asyncio.Semaphore） |\n\n---\n\n## API 接口文档\n\n### 页面路由（Pages）\n\n| 路由 | 说明 |\n|------|------|\n| `GET /` | 首页，项目列表 |\n| `GET /projects/new` | 新建项目页面 |\n| `GET /projects/{id}` | 项目工作台 |\n| `GET /projects/{id}/stage/{n}` | Stage N 中间结果审查 |\n| `GET /projects/{id}/stage3/kanban` | 场景编排看板 |\n| `GET /projects/{id}/characters` | 人物关系图谱 |\n| `GET /projects/{id}/script` | 在线剧本查看/编辑 |\n\n### REST API\n\n| 方法 | 路由 | 说明 |\n|------|------|------|\n| `POST` | `/api/projects` | 创建项目 |\n| `POST` | `/api/projects/{id}/upload` | 上传小说文件 |\n| `POST` | `/api/projects/{id}/paste` | 粘贴小说文本 |\n| `GET` | `/api/projects/{id}/text` | 获取已保存的文本 |\n| `POST` | `/api/projects/{id}/run` | **一键生成**（SSE 流式） |\n| `POST` | `/api/projects/{id}/run-stage/{n}` | **分步生成**单阶段（SSE 流式） |\n| `GET` | `/api/projects/{id}/stage/{n}` | 获取阶段缓存数据 |\n| `PUT` | `/api/projects/{id}/stage/5` | 保存编辑后的剧本 |\n| `POST` | `/api/projects/{id}/clear-cache` | 清除缓存（`?stage=N` 可选） |\n| `DELETE` | `/api/projects/{id}` | 删除项目 |\n| `GET` | `/api/projects/{id}/script.yaml` | 下载 YAML |\n| `GET` | `/api/projects/{id}/script.pdf` | 下载 PDF |\n| `GET` | `/api/projects/{id}/character-graph` | 人物关系图谱数据 |\n| `GET` | `/api/projects/{id}/scenes` | 获取场景列表（看板用） |\n| `PUT` | `/api/projects/{id}/scenes` | 保存场景列表（看板用） |\n| `POST` | `/api/projects/{id}/scenes/split/{scene_id}` | 拆分场景 |\n| `POST` | `/api/projects/{id}/scenes/merge` | 合并场景 |\n| `POST` | `/api/projects/{id}/chat` | AI 助手聊天（SSE 流式） |\n\n### SSE 事件格式\n\n所有流式接口（`/run`、`/run-stage`、`/chat`）均使用以下格式：\n\n```\ndata: {\"message\": \"正在分析...\", \"percent\": 15, \"current_stage\": 1, \"stage_status\": {...}}\ndata: {\"status\": \"complete\", \"yaml_text\": \"...\", \"screenplay_text\": \"...\"}\n```\n\n前端通过 `EventSource` / `fetch + ReadableStream` 消费事件流，实时更新进度条和阶段状态。\n\n---\n\n## 常见问题\n\n### 启动与连接\n\n**Q: 启动后浏览器打不开 http://localhost:8000？**\n\nA: 检查以下项目：\n1. 确认 Uvicorn 已正常启动（终端有 `Uvicorn running on http://0.0.0.0:8000` 提示）\n2. 确认端口 8000 未被占用：`netstat -ano | findstr 8000`（Windows）/ `lsof -i :8000`（macOS/Linux）\n3. 尝试换端口：`--port 8001`\n\n**Q: WSL / Git Bash 启动报 `database is locked`？**\n\nA: 这是跨文件系统 SQLite 锁问题，解决方案：\n1. 在 `.env` 中设置 Windows 路径：`SCRIPT_TOOL_DATABASE_URL=sqlite:///C:/Users/你的用户名/script_tool.db`\n2. 或使用 `start.sh` 启动，脚本会自动处理\n\n### AI 配置\n\n**Q: 一键生成报错 \"API Key 无效\"？**\n\nA: 检查 `.env` 文件中的 API Key 是否正确：\n- Claude：以 `sk-ant-api03-` 开头\n- OpenAI：以 `sk-proj-` 或 `sk-` 开头\n- DeepSeek：以 `sk-` 开头\n- Gemini：无固定前缀\n\n**Q: 本地模型（LM Studio）连接失败？**\n\nA: 检查：\n1. LM Studio → Developer 标签 → **Start Server** 是否已启动\n2. 端口是否为 **1234**（默认不要改）\n3. 模型名是否与 LM Studio 中加载的一致\n\n**Q: 能不能流水线用 DeepSeek，AI 助手用 Claude？**\n\nA: 完全可以。同时配置两者的 API Key：\n```bash\nSCRIPT_TOOL_AI_PROVIDER=deepseek\nSCRIPT_TOOL_DEEPSEEK_API_KEY=sk-xxx\nSCRIPT_TOOL_ANTHROPIC_API_KEY=sk-ant-api03-xxx\n```\n流水线使用 DeepSeek，AI 助手下拉菜单选择 Claude 即可。\n\n### 剧本生成\n\n**Q: 一次能处理多长的小说？**\n\nA: 建议 20 章以内、50 万字以内。更长的小说可以：\n1. 分成多个项目分批处理\n2. 减少 Stage 3 的场景数（在看板中手动精简）\n\n**Q: Stage 4 场景内容为空怎么办？**\n\nA: 系统已内置自动跳过机制——空场景会被过滤并显示警告，不会中断流水线。如果大量场景为空：\n1. 尝试换用其他 AI 模型\n2. 在 Stage 3 看板中减少场景复杂度\n3. 清除 Stage 4 缓存后重试\n\n**Q: 生成过程很慢？**\n\nA: Stage 1 和 Stage 4 是并行处理的，耗时取决于 AI API 响应速度和并发数。建议：\n- 使用 DeepSeek 或本地模型（响应速度更快）\n- 减少场景数（在 Stage 3 看板中精简）\n\n### 数据\n\n**Q: 数据存在哪里？**\n\nA: 所有数据存储在 `storage/` 目录：\n- `storage/db.sqlite` — SQLite 数据库（项目、缓存、运行记录）\n- `storage/texts/` — 上传的文本文件\n- 支持通过 `SCRIPT_TOOL_DATABASE_URL` 自定义数据库路径\n\n**Q: 如何备份数据？**\n\nA: 复制整个 `storage/` 目录即可，包含所有项目数据、缓存和文本文件。\n\n---\n\n## 开发指南\n\n### 运行测试\n\n```bash\npytest tests/ -v\n# 35+ 测试用例，覆盖核心流水线和 API\n```\n\n### 代码规范\n\n- Python 3.10+ 类型注解（`dataclass` 数据模型）\n- FastAPI 依赖注入（`Depends(get_db)` 数据库会话）\n- AI Provider 统一 `async` 接口（`generate` + `generate_stream`）\n- 前端使用 HTMX + 原生 JavaScript（无框架依赖）\n\n### 添加新的 AI Provider\n\n1. 在 `app/ai/` 下创建新文件，继承 `AIProvider` 接口\n2. 实现 `generate()`、`generate_stream()`、`model_name()` 三个方法\n3. 在 `app/config.py` 添加对应的环境变量\n4. 在 `app/ai/factory.py` 的 `create_ai_provider()` 中添加分支\n5. 在 `app/routes/chat.py` 的 `PROVIDER_KEY_MAP` 中注册密钥检查\n\n### 项目配置\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `MAX_UPLOAD_BYTES` | 10 MB | 文件上传大小限制 |\n| `MAX_PASTE_CHARS` | 500,000 | 粘贴文本字数限制 |\n| `DATABASE_URL` | 自动检测 | SQLite 数据库路径 |\n\n---\n\n## 许可证\n\nMIT License\n"}, "b98fbcee70e9391f687222eb13dd99d3e22431a6": {"t": 1785764189.750682, "n": 17992, "h": "e616fdbe38a121dc", "c": "# 🎬 AI 剧本创作工具\n\n将小说文本（≥3 章）自动转换为**结构化 YAML 剧本**和**行业标准格式剧本**，支持电影、电视剧、舞台剧、动画等多种类型。\n\n---\n\n## 目录\n\n- [功能概览](#功能概览)\n- [项目架构](#项目架构)\n- [环境搭建](#环境搭建)\n- [API Key 配置详解](#api-key-配置详解)\n- [使用指南](#使用指南)\n- [6 阶段流水线详解](#6-阶段流水线详解)\n- [功能模块说明](#功能模块说明)\n- [API 接口文档](#api-接口文档)\n- [常见问题](#常见问题)\n- [开发指南](#开发指南)\n\n---\n\n## 功能概览\n\n### 核心功能\n\n| 模块 | 说明 |\n|------|------|\n| 📂 **文件导入** | 支持 `.txt` / `.docx` / `.md` 格式上传，或直接粘贴小说文本（最多 50 万字） |\n| ⚡ **一键生成** | 6 阶段全自动流水线，从文本解析到剧本导出全程 AI 驱动 |\n| 📋 **分步生成** | 逐阶段执行，每步可暂停审查 AI 中间结果（人物、情节、场景结构） |\n| 🕸 **场景编排看板** | Stage 3 完成后提供拖拽式场景看板，自由增删合并拆分场景 |\n| 📝 **在线编辑** | 生成的剧本支持在线预览和编辑，实时保存 |\n| ⬇ **多格式导出** | 支持 YAML（结构化数据）和 PDF（行业标准排版）双格式导出 |\n| 💬 **AI 助手** | 右下角聊天面板，支持翻译、润色、摘要等快捷操作，5 种模型自由切换 |\n| 🔄 **断点续传** | 每阶段结果自动缓存，重新开始或切换模型后已完成阶段无需重跑 |\n\n### 支持的剧本类型\n\n- 电影剧本（Film）\n- 电视剧剧本（TV Series）— 支持多集场景编排\n- 动画剧本（Animation）\n- 舞台剧剧本（Stage Play）\n- 自定义（Custom）\n\n---\n\n## 项目架构\n\n```\nscript-tool/\n├── app/\n│ ├── main.py # FastAPI 入口，挂载静态文件与路由\n│ ├── config.py # 配置中心：环境变量加载、路径管理\n│ ├── models.py # 数据模型：Project / PipelineRun / StageCache\n│ ├── db.py # SQLite 数据库引擎与会话管理\n│ │\n│ ├── ai/ # AI 后端抽象层（5 种 Provider）\n│ │ ├── interface.py # AIProvider 抽象接口\n│ │ ├── factory.py # Provider 工厂函数\n│ │ ├── claude.py # Anthropic Claude API\n│ │ ├── openai.py # OpenAI GPT (兼容自定义 base_url)\n│ │ ├── deepseek.py # DeepSeek (OpenAI 兼容协议)\n│ │ ├── gemini.py # Google Gemini\n│ │ └── local.py # 本地模型 (LM Studio / Ollama)\n│ │\n│ ├── pipeline/ # 6 阶段流水线引擎\n│ │ ├── executor.py # 流水线调度器（含缓存、进度、重试逻辑）\n│ │ ├── stage0_preprocess.py # Stage 0: 文本预处理（章节拆分）\n│ │ ├── stage1_chapter_analysis.py # Stage 1: 分章节分析\n│ │ ├── stage2_cross_chapter_synthesis.py # Stage 2: 跨章节综合\n│ │ ├── stage3_script_structure.py # Stage 3: 剧本结构设计\n│ │ ├── stage4_scene_generation.py # Stage 4: 逐场内容生成\n│ │ ├── stage5_assembly.py # Stage 5: YAML 组装 & 标准格式转换\n│ │ ├── pdf_export.py # PDF 导出（行业标准排版）\n│ │ └── utils.py # JSON 提取等工具函数\n│ │\n│ ├── routes/ # HTTP 路由层\n│ │ ├── pages.py # 页面路由（Jinja2 SSR）\n│ │ ├── api.py # REST API + SSE 流式接口\n│ │ └── chat.py # AI 助手聊天接口\n│ │\n│ └── templates/ # Jinja2 模板\n│ ├── base.html # 基础布局（导航栏、粒子背景）\n│ ├── index.html # 首页（项目列表）\n│ ├── project_new.html # 新建项目\n│ ├── project.html # 项目工作台（核心页面）\n│ ├── stage_review.html # 中间结果审查\n│ ├── stage3_kanban.html # 场景编排看板\n│ ├── character_graph.html # 人物关系图谱\n│ └── script_view.html # 在线剧本查看/编辑\n│\n├── static/\n│ ├── css/style.css # 全局样式（暗色科技主题）\n│ ├── js/\n│ │ ├── htmx.min.js # HTMX 前端交互库\n│ │ └── particles.js # 粒子背景动画\n│ └── img/\n│ └── logo.svg # 品牌 Logo\n│\n├── storage/ # 运行时数据（自动创建）\n│ ├── texts/ # 上传的文本文件\n│ ├── cache/ # 流水线缓存\n│ └── db.sqlite # SQLite 数据库\n│\n├── requirements.txt # Python 依赖\n├── .env.example # 配置文件模板\n├── start.sh # 一键启动脚本\n└── README.md\n```\n\n### 技术栈\n\n| 层级 | 技术 |\n|------|------|\n| **Web 框架** | FastAPI + Uvicorn (ASGI) |\n| **模板引擎** | Jinja2 (SSR 渲染) |\n| **前端交互** | HTMX 2.0 (无刷新局部更新) + 原生 JavaScript |\n| **数据库** | SQLite + SQLAlchemy ORM |\n| **AI 后端** | Claude / GPT / DeepSeek / Gemini / 本地模型 |\n| **PDF 生成** | fpdf2 (Courier 12pt + SimSun 中文字体) |\n| **文件解析** | python-docx + markdown |\n| **异步** | Python asyncio (流式 SSE 推送) |\n\n---\n\n## 环境搭建\n\n### 前置要求\n\n- **Python 3.10+**（推荐 3.12）\n- **pip**（Python 包管理器）\n- **Git**（可选，用于克隆仓库）\n\n### 步骤 1：克隆项目\n\n```bash\ngit clone https://github.com/ailakala/script-tool.git\ncd script-tool\n```\n\n如果不想用 Git，也可以直接下载 ZIP 包解压。\n\n### 步骤 2：创建虚拟环境（推荐）\n\n```bash\n# Windows (PowerShell)\npython -m venv venv\n.\\venv\\Scripts\\activate\n\n# macOS / Linux\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n> 虚拟环境可以隔离项目依赖，避免与系统 Python 包冲突。如果不想用虚拟环境，可以跳过此步。\n\n### 步骤 3：安装依赖\n\n```bash\npip install -r requirements.txt\n```\n\n如果安装较慢，可以使用国内镜像：\n\n```bash\npip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/\n```\n\n<details>\n<summary>完整依赖列表（点击展开）</summary>\n\n| 包名 | 版本 | 用途 |\n|------|------|------|\n| `fastapi` | 0.115 | Web 框架 |\n| `uvicorn[standard]` | 0.30 | ASGI 服务器 |\n| `sqlalchemy` | 2.0 | ORM 数据库 |\n| `jinja2` | 3.1 | 模板引擎 |\n| `python-multipart` | 0.0.12 | 文件上传 |\n| `anthropic` | 0.40 | Claude API SDK |\n| `openai` | 1.60 | OpenAI/DeepSeek 兼容 SDK |\n| `google-genai` | 1.14 | Gemini API SDK |\n| `python-docx` | 1.1 | Word 文档解析 |\n| `markdown` | 3.7 | Markdown 解析 |\n| `pyyaml` | 6.0 | YAML 序列化 |\n| `fpdf2` | 2.8 | PDF 生成 |\n| `python-dotenv` | 1.1 | 环境变量管理 |\n| `pytest` | 8.3 | 测试框架 |\n| `httpx` | 0.28 | HTTP 测试客户端 |\n\n</details>\n\n### 步骤 4：配置环境变量\n\n```bash\n# 从模板创建配置文件\ncp .env.example .env\n```\n\n编辑 `.env` 文件，至少需要配置一个 AI 后端的 API Key。详细说明见下一节。\n\n### 步骤 5：启动服务\n\n**方式一：一键启动脚本**\n\n```bash\nbash start.sh\n```\n\n脚本会自动：\n1. 检测首次运行 → 提示编辑 `.env`\n2. 检测跨文件系统环境（WSL / Git Bash）→ 自动重定向数据库路径\n3. 安装缺失的依赖\n4. 启动 Uvicorn 服务器\n\n**方式二：手动启动**\n\n```bash\nuvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n# 访问 http://localhost:8000\n```\n\n**方式三：开发模式启动（支持热重载）**\n\n```bash\n# Windows\npython -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n\n# macOS / Linux\npython3 -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n```\n\n打开浏览器访问 **http://localhost:8000**。\n\n### 各系统特别注意\n\n<details>\n<summary>🪟 Windows 用户</summary>\n\n- 推荐使用 **PowerShell** 或 **Git Bash**\n- 如果使用 Git Bash，启动脚本会自动检测环境，将 SQLite 数据库重定向到 `C:/Users/<用户名>/script_tool.db`\n- 如果手动启动遇到 `database is locked` 错误，请在 `.env` 中设置：\n ```\n SCRIPT_TOOL_DATABASE_URL=sqlite:///C:/Users/你的用户名/script_tool.db\n ```\n\n</details>\n\n<details>\n<summary>🐧 WSL (Windows Subsystem for Linux) 用户</summary>\n\nWSL 跨文件系统访问 Windows 路径时，SQLite 无法正常加锁。解决方案：\n\n1. **方式一**：在 `.env` 中设置 Windows 本机路径\n ```\n SCRIPT_TOOL_DATABASE_URL=sqlite:///C:/Users/你的用户名/script_tool.db\n ```\n2. **方式二**：使用 `start.sh` 启动，脚本自动检测并配置\n\n</details>\n\n<details>\n<summary>🍎 macOS 用户</summary>\n\n- macOS 自带 Python 可能版本较旧，建议用 Homebrew 安装：\n ```bash\n brew install python@3.12\n ```\n- 如果 PDF 生成缺少中文字体，可安装：\n ```bash\n brew install --cask font-simsun\n ```\n\n</details>\n\n---\n\n## API Key 配置详解\n\n整个项目的 AI 能力依赖于 **两大块配置**：流水线剧本生成 和 AI 助手聊天。两者**共用同一套 API Key**，但可以独立配置不同模型。\n\n### 配置文件的加载机制\n\n1. 项目启动时，`app/config.py` 自动读取项目根目录的 `.env` 文件\n2. 所有配置通过环境变量注入，不硬编码在代码中\n3. 环境变量名统一前缀 `SCRIPT_TOOL_` 避免与其他应用冲突\n\n### 一、流水线剧本生成的 API Key\n\n流水线是**自动化的 6 阶段 AI 流程**，每次调用消耗大量 tokens。通过以下两个核心变量控制：\n\n```\nSCRIPT_TOOL_AI_PROVIDER=claude # 选择哪个 AI 后端\nSCRIPT_TOOL_AI_MODEL=claude-sonnet-4-6 # 具体模型名\n```\n\n然后根据你选择的 `SCRIPT_TOOL_AI_PROVIDER`，配置对应的 API Key：\n\n#### 方案 A：Claude API（推荐）\n\n最推荐的选择，中文理解和创意写作能力最强，剧本质量最高。\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=claude\nSCRIPT_TOOL_AI_MODEL=claude-sonnet-4-6\nSCRIPT_TOOL_ANTHROPIC_API_KEY=sk-ant-api03-你的密钥\n```\n\n| 获取地址 | 费用参考 |\n|---------|---------|\n| [console.anthropic.com](https://console.anthropic.com/settings/keys) | $2-5/次完整生成 |\n\n> **模型选择建议**：\n> - `claude-sonnet-4-6`：性价比最优，推荐日常使用\n> - `claude-opus-4-8`：最强质量，长篇小说或复杂剧本\n> - `claude-haiku-4-5`：最快速度，用于测试或简单任务\n\n#### 方案 B：OpenAI GPT\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=openai\nSCRIPT_TOOL_AI_MODEL=gpt-4o\nSCRIPT_TOOL_OPENAI_API_KEY=sk-proj-你的密钥\n```\n\n| 获取地址 | 费用参考 |\n|---------|---------|\n| [platform.openai.com/api-keys](https://platform.openai.com/api-keys) | $0.5-1/次完整生成 |\n\n> 如果你的 OpenAI Key 是通过**第三方代理/中转服务**获取的，需要额外设置：\n> ```bash\n> SCRIPT_TOOL_OPENAI_BASE_URL=https://你的代理地址/v1\n> ```\n> 这个配置也适用于任何 OpenAI 兼容接口（如 Azure OpenAI、OneAPI 等）。\n\n#### 方案 C：DeepSeek（性价比之选）\n\n中文优秀，价格极低，国内网络直连。\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=deepseek\nSCRIPT_TOOL_AI_MODEL=deepseek-chat\nSCRIPT_TOOL_DEEPSEEK_API_KEY=sk-你的密钥\n```\n\n| 获取地址 | 费用参考 |\n|---------|---------|\n| [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys) | ¥0.5-1/次完整生成 |\n\n> 可选模型：`deepseek-chat`（通用）、`deepseek-reasoner`（推理增强，创意写作更佳）。通过 `SCRIPT_TOOL_DEEPSEEK_MODEL` 切换。\n\n#### 方案 D：Google Gemini\n\n免费额度友好，适合测试和轻度使用。\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=gemini\nSCRIPT_TOOL_AI_MODEL=gemini-2.5-flash\nSCRIPT_TOOL_GEMINI_API_KEY=你的密钥\n```\n\n| 获取地址 | 费用参考 |\n|---------|---------|\n| [aistudio.google.com/apikey](https://aistudio.google.com/apikey) | 免费/接近免费 |\n\n> 可选模型：`gemini-2.5-pro`（最强）、`gemini-2.5-flash`（快速推荐）。通过 `SCRIPT_TOOL_GEMINI_MODEL` 切换。\n\n#### 方案 E：本地模型（免费，完全离线）\n\n支持 LM Studio 和 Ollama，数据完全本地处理。\n\n```bash\nSCRIPT_TOOL_AI_PROVIDER=local\nSCRIPT_TOOL_AI_MODEL=qwen2.5-7b-instruct\n```\n\n| 工具 | 下载地址 | 推荐模型 |\n|------|---------|---------|\n| LM Studio | [lmstudio.ai](https://lmstudio.ai) | Qwen 2.5 7B / 14B |\n| Ollama | [ollama.com](https://ollama.com) | qwen2.5:7b / deepseek-r1:7b |\n\n> LM Studio 设置：加载模型 → Developer 标签 → Start Server（默认端口 1234），无需额外配置。\n>\n> Ollama 用户需修改端口：\n> ```bash\n> SCRIPT_TOOL_LOCAL_LLM_URL=http://localhost:11434/v1\n> ```\n\n---\n\n### 二、AI 助手的 API Key\n\n项目页面右下角的 💬 **AI 助手聊天面板**支持 5 种模型**实时切换**，无需重启服务。\n\n它的 API Key 配置与流水线使用**同一套环境变量**——只要你配置了哪个 Provider 的 Key，聊天面板中切换过去就能用。\n\n```bash\n# Claude — 和流水线共用这个 Key\nSCRIPT_TOOL_ANTHROPIC_API_KEY=sk-ant-api03-你的密钥\n\n# GPT (OpenAI) — 和流水线共用这个 Key\nSCRIPT_TOOL_OPENAI_API_KEY=sk-proj-你的密钥\n# 可选：自定义 API 地址（如中转/代理）\nSCRIPT_TOOL_OPENAI_BASE_URL=https://你的代理地址/v1\n\n# DeepSeek — 和流水线共用这个 Key\nSCRIPT_TOOL_DEEPSEEK_API_KEY=sk-你的密钥\n\n# Gemini — 和流水线共用这个 Key\nSCRIPT_TOOL_GEMINI_API_KEY=你的密钥\n\n# 本地模型 — LM Studio 端口 1234 已预设\nSCRIPT_TOOL_LOCAL_LLM_URL=http://localhost:1234/v1\nSCRIPT_TOOL_LOCAL_LLM_API_KEY=not-needed\n```\n\n#### AI 助手的快捷功能\n\n聊天面板预设了 4 个快捷操作按钮：\n\n| 按钮 | 功能 |\n|------|------|\n| 中译英 | 将剧本内容翻译成英文 |\n| 英译中 | 将英文内容翻译成中文 |\n| 润色 | 优化文本表达，提升流畅度 |\n| 摘要 | 用简洁语言总结内容 |\n\n#### AI 助手的项目感知能力\n\nAI 助手**自动读取当前项目的流水线数据**作为对话上下文，包括：\n- 项目基本信息（名称、原著、作者、剧本类型）\n- 各 Stage 完成状态\n- 人物列表（姓名、角色定位、描述）\n- 人物关系网络\n- 主线与支线情节\n- 场景结构列表\n- 已生成的剧本内容（前 3000 字符预览）\n\n这意味着你可以直接问 AI 助手：\n- \"主角在第 3 场戏里说了什么？\"\n- \"帮我把第 2 集的场景列表翻译成英文\"\n- \"女配角和男主角是什么关系？\"\n- \"帮我润色 scene_005 的对白\"\n\n#### AI 助手密钥验证\n\n切换模型时，系统会检查对应的环境变量是否已配置。如果未配置，聊天面板会显示错误提示，告诉你需要设置哪个环境变量。\n\n---\n\n### 三、完整 .env 配置示例\n\n以下是一个同时配置了 DeepSeek（流水线）和 Claude（AI 助手）的完整示例：\n\n```bash\n# ═══ 流水线（用 DeepSeek） ═══\nSCRIPT_TOOL_AI_PROVIDER=deepseek\nSCRIPT_TOOL_AI_MODEL=deepseek-chat\nSCRIPT_TOOL_DEEPSEEK_API_KEY=sk-da0c92f36581481cb1321e1cf3c5bf70\n\n# ═══ AI 助手（额外启用 Claude） ═══\nSCRIPT_TOOL_ANTHROPIC_API_KEY=sk-ant-api03-你的claude密钥\n\n# ═══ 可选 ═══\nSCRIPT_TOOL_DATABASE_URL=sqlite:///C:/Users/lenovo/script_tool.db\n```\n\n这样配置后：\n- **流水线**使用 DeepSeek 生成剧本（省钱）\n- **AI 助手**可以在 DeepSeek 和 Claude 之间切换\n- 如果想在 AI 助手中使用 GPT 聊天，再加一行 `SCRIPT_TOOL_OPENAI_API_KEY=...`\n\n---\n\n### 四、API Key 安全建议\n\n1. **❌ 不要把 `.env` 提交到 Git**（已在 `.gitignore` 中排除）\n2. **✅** 生产环境直接设置系统环境变量，不使用 `.env` 文件\n3. **✅** 定期更换 API Key，尤其是在公共网络环境下使用时\n4. **✅** 在 API 平台设置使用额度限制，防止意外超支\n\n---\n\n## 使用指南\n\n### 快速上手（3 步）\n\n1. **新建项目** → 填写项目名称、原著信息、选择剧本类型\n2. **导入小说** → 上传 `.txt` / `.docx` / `.md` 文件，或直接粘贴文本（至少 3 章）\n3. **一键生成** → 6 个阶段自动完成，生成剧本\n\n### 一键生成 vs 分步生成\n\n| 模式 | 特点 | 适用场景 |\n|------|------|---------|\n| 🚀 **一键生成** | 6 阶段全自动，一次完成 | 快速出稿、对 AI 结果有信心 |\n| 📋 **分步生成** | 每阶段可暂停审查 | 需要精细控制、人物众多的长篇小说 |\n\n分步生成模式下，以下阶段完成后会**自动暂停**供你审查：\n\n| 暂停点 | 可审查内容 | 可做什么 |\n|--------|-----------|---------|\n| Stage 1 完成后 | 每章人物、地点、情节 | 检查是否有漏人或错认 |\n| Stage 2 完成后 | 综合人物表、关系图 | 调整关系、修改角色定位 |\n| Stage 3 完成后 | 剧本场景列表 | **拖拽编排场景、增删合并拆分** |\n\n### 场景编排看板（Stage 3）\n\nStage 3 完成后会出现 📋 **编排场景** 链接，点击进入看板：\n\n- **按集分组**：场景自动分集显示，每集一列\n- **拖拽排序**：拖拽场景卡片调整顺序\n- **编辑场景**：点击编辑按钮修改地点、时间、人物、摘要\n- **拆分场景**：长场景可拆分为两场\n- **合并场景**：选中两个场景合并为一个\n- **新增场景**：在任意集末尾添加新场景\n- **自动编号**：保存时自动重新编号（scene_001, scene_002…）\n- **触发 Stage 4**：编排满意后，从看板直接开始生成场景内容\n\n### 查看和导出结果\n\n流水线完成后：\n\n- 📝 **查看/编辑剧本** — 在线预览标准格式剧本，支持编辑保存\n- ⬇ **下载 YAML** — 导出结构化 YAML 数据（机器可读，含完整元数据）\n- ⬇ **下载 PDF** — 导出行业标准排版 PDF（Courier 12pt，适合打印/提交）\n\n---\n\n## 6 阶段流水线详解\n\n```\nStage 0 → Stage 1 → Stage 2 → 🛑暂停 → Stage 3 → 🛑暂停 → Stage 4 → Stage 5\n 5% 30% 10% 10% 40% 5%\n```\n\n### Stage 0 — 文本预处理（权重 5%）\n\n- **输入**：原始小说文本\n- **处理**：正则匹配章节标题（\"第一章\" / \"Chapter 1\" 等），自动拆分章节\n- **输出**：`PreprocessResult`（标题、章节列表、总字数）\n- **支持格式**：`.txt`、`.docx`（自动提取正文）、`.md`（自动转纯文本）\n- **限制**：至少 3 章，最多 50 万字\n\n### Stage 1 — 分章节分析（权重 30%）\n\n- **输入**：Stage 0 输出的章节列表\n- **处理**：N 个章节**并行**调用 AI，逐章提取人物、地点、情节、台词\n- **输出**：`ChapterAnalysis[]`（每章的 new_characters、locations、plot_events、dialogue_excerpts）\n- **进度**：实时显示 \"章节分析 X/N\"\n\n### Stage 2 — 跨章节综合（权重 10%）🛑暂停点\n\n- **输入**：Stage 1 输出的所有章节分析结果\n- **处理**：AI 综合去重，合并同名人物、建立关系网络、梳理主线支线\n- **输出**：`GlobalAnalysis`\n - `characters`：综合人物表（姓名、别名、定位、性格标签、首次出场章节）\n - `relationships`：人物关系网络（A → B，关系类型，描述）\n - `locations`：场景目录\n - `main_plot`：主线情节概述\n - `subplots`：支线列表\n\n### Stage 3 — 剧本结构设计（权重 10%）🛑暂停点\n\n- **输入**：Stage 2 输出的综合人物与情节分析\n- **处理**：AI 设计场景列表，规划每场的地点、时间、出场人物、内容概要\n- **输出**：`ScriptStructure`\n - `scenes`：场景计划列表（含 act/episode/sequence/location/characters/summary）\n - `episode_summaries`：集摘要（电视剧模式）\n - `beat_sheet`：节拍表（电影编剧术语）\n\n### Stage 4 — 逐场内容生成（权重 40%）\n\n- **输入**：Stage 3 输出的场景计划 + Stage 2 人物表 + Stage 0 原始章节文本\n- **处理**：M 个场景**并行**调用 AI，生成完整的动作描写、对白、旁白、转场\n- **输出**：`GeneratedScene[]`（标准剧本格式：scene_heading + content[]，含多类型内容元素）\n- **容错**：空场景自动跳过，不中断流水线\n- **进度**：实时显示 \"场景生成 X/M\"\n\n### Stage 5 — 组装 & 校验（权重 5%）\n\n- **输入**：所有前序阶段的输出\n- **处理**：\n 1. 构建标准人物表（含 id、name、role、traits）\n 2. 组装 YAML 结构化输出（meta + config + characters + scenes）\n 3. 转换为**行业标准中文剧本格式**（角色名对齐、场次标题、动作/对白/旁白分离）\n- **输出**：`AssemblyResult`（yaml_text + screenplay_text + warnings）\n- **校验**：检查必填字段完整性，输出警告信息\n\n---\n\n## 功能模块说明\n\n### 文件导入模块（Stage 0 预处理）\n\n| 格式 | 解析方式 | 说明 |\n|------|---------|------|\n| `.txt` | 正则拆分章节 | 中文（\"第X章\"）和英文（\"Chapter X\"）模式均支持 |\n| `.docx` | python-docx 提取 | 自动提取所有段落文本，处理 Word 特殊格式 |\n| `.md` | markdown 转纯文本 | 先转 HTML 再去除标签，保留纯文本内容 |\n| 直接粘贴 | 同 `.txt` | 最长 50 万字限制，textarea 粘贴即可 |\n\n### 缓存与断点续传\n\n每阶段结果自动以 **input_hash** 为键缓存到 SQLite：\n- 同一内容的同一阶段不重复调用 AI（节省时间和费用）\n- 重置缓存后重新运行会重新生成\n- 分步模式暂停期间，已完成阶段不受影响\n\n### 安全机制\n\n| 机制 | 说明 |\n|------|------|\n| 心跳检测 | SSE 连接 30 秒无响应自动断连 |\n| 自动重试 | Stage 4 场景生成失败自动重试（最多 2 次） |\n| 空场景跳过 | AI 返回空内容的场景自动过滤，带警告提示 |\n| 速率限制 | 并发 AI 调用自动限流（asyncio.Semaphore） |\n\n---\n\n## API 接口文档\n\n### 页面路由（Pages）\n\n| 路由 | 说明 |\n|------|------|\n| `GET /` | 首页，项目列表 |\n| `GET /projects/new` | 新建项目页面 |\n| `GET /projects/{id}` | 项目工作台 |\n| `GET /projects/{id}/stage/{n}` | Stage N 中间结果审查 |\n| `GET /projects/{id}/stage3/kanban` | 场景编排看板 |\n| `GET /projects/{id}/characters` | 人物关系图谱 |\n| `GET /projects/{id}/script` | 在线剧本查看/编辑 |\n\n### REST API\n\n| 方法 | 路由 | 说明 |\n|------|------|------|\n| `POST` | `/api/projects` | 创建项目 |\n| `POST` | `/api/projects/{id}/upload` | 上传小说文件 |\n| `POST` | `/api/projects/{id}/paste` | 粘贴小说文本 |\n| `GET` | `/api/projects/{id}/text` | 获取已保存的文本 |\n| `POST` | `/api/projects/{id}/run` | **一键生成**（SSE 流式） |\n| `POST` | `/api/projects/{id}/run-stage/{n}` | **分步生成**单阶段（SSE 流式） |\n| `GET` | `/api/projects/{id}/stage/{n}` | 获取阶段缓存数据 |\n| `PUT` | `/api/projects/{id}/stage/5` | 保存编辑后的剧本 |\n| `POST` | `/api/projects/{id}/clear-cache` | 清除缓存（`?stage=N` 可选） |\n| `DELETE` | `/api/projects/{id}` | 删除项目 |\n| `GET` | `/api/projects/{id}/script.yaml` | 下载 YAML |\n| `GET` | `/api/projects/{id}/script.pdf` | 下载 PDF |\n| `GET` | `/api/projects/{id}/character-graph` | 人物关系图谱数据 |\n| `GET` | `/api/projects/{id}/scenes` | 获取场景列表（看板用） |\n| `PUT` | `/api/projects/{id}/scenes` | 保存场景列表（看板用） |\n| `POST` | `/api/projects/{id}/scenes/split/{scene_id}` | 拆分场景 |\n| `POST` | `/api/projects/{id}/scenes/merge` | 合并场景 |\n| `POST` | `/api/projects/{id}/chat` | AI 助手聊天（SSE 流式） |\n\n### SSE 事件格式\n\n所有流式接口（`/run`、`/run-stage`、`/chat`）均使用以下格式：\n\n```\ndata: {\"message\": \"正在分析...\", \"percent\": 15, \"current_stage\": 1, \"stage_status\": {...}}\ndata: {\"status\": \"complete\", \"yaml_text\": \"...\", \"screenplay_text\": \"...\"}\n```\n\n前端通过 `EventSource` / `fetch + ReadableStream` 消费事件流，实时更新进度条和阶段状态。\n\n---\n\n## 常见问题\n\n### 启动与连接\n\n**Q: 启动后浏览器打不开 http://localhost:8000？**\n\nA: 检查以下项目：\n1. 确认 Uvicorn 已正常启动（终端有 `Uvicorn running on http://0.0.0.0:8000` 提示）\n2. 确认端口 8000 未被占用：`netstat -ano | findstr 8000`（Windows）/ `lsof -i :8000`（macOS/Linux）\n3. 尝试换端口：`--port 8001`\n\n**Q: WSL / Git Bash 启动报 `database is locked`？**\n\nA: 这是跨文件系统 SQLite 锁问题，解决方案：\n1. 在 `.env` 中设置 Windows 路径：`SCRIPT_TOOL_DATABASE_URL=sqlite:///C:/Users/你的用户名/script_tool.db`\n2. 或使用 `start.sh` 启动，脚本会自动处理\n\n### AI 配置\n\n**Q: 一键生成报错 \"API Key 无效\"？**\n\nA: 检查 `.env` 文件中的 API Key 是否正确：\n- Claude：以 `sk-ant-api03-` 开头\n- OpenAI：以 `sk-proj-` 或 `sk-` 开头\n- DeepSeek：以 `sk-` 开头\n- Gemini：无固定前缀\n\n**Q: 本地模型（LM Studio）连接失败？**\n\nA: 检查：\n1. LM Studio → Developer 标签 → **Start Server** 是否已启动\n2. 端口是否为 **1234**（默认不要改）\n3. 模型名是否与 LM Studio 中加载的一致\n\n**Q: 能不能流水线用 DeepSeek，AI 助手用 Claude？**\n\nA: 完全可以。同时配置两者的 API Key：\n```bash\nSCRIPT_TOOL_AI_PROVIDER=deepseek\nSCRIPT_TOOL_DEEPSEEK_API_KEY=sk-xxx\nSCRIPT_TOOL_ANTHROPIC_API_KEY=sk-ant-api03-xxx\n```\n流水线使用 DeepSeek，AI 助手下拉菜单选择 Claude 即可。\n\n### 剧本生成\n\n**Q: 一次能处理多长的小说？**\n\nA: 建议 20 章以内、50 万字以内。更长的小说可以：\n1. 分成多个项目分批处理\n2. 减少 Stage 3 的场景数（在看板中手动精简）\n\n**Q: Stage 4 场景内容为空怎么办？**\n\nA: 系统已内置自动跳过机制——空场景会被过滤并显示警告，不会中断流水线。如果大量场景为空：\n1. 尝试换用其他 AI 模型\n2. 在 Stage 3 看板中减少场景复杂度\n3. 清除 Stage 4 缓存后重试\n\n**Q: 生成过程很慢？**\n\nA: Stage 1 和 Stage 4 是并行处理的，耗时取决于 AI API 响应速度和并发数。建议：\n- 使用 DeepSeek 或本地模型（响应速度更快）\n- 减少场景数（在 Stage 3 看板中精简）\n\n### 数据\n\n**Q: 数据存在哪里？**\n\nA: 所有数据存储在 `storage/` 目录：\n- `storage/db.sqlite` — SQLite 数据库（项目、缓存、运行记录）\n- `storage/texts/` — 上传的文本文件\n- 支持通过 `SCRIPT_TOOL_DATABASE_URL` 自定义数据库路径\n\n**Q: 如何备份数据？**\n\nA: 复制整个 `storage/` 目录即可，包含所有项目数据、缓存和文本文件。\n\n---\n\n## 开发指南\n\n### 运行测试\n\n```bash\npytest tests/ -v\n# 35+ 测试用例，覆盖核心流水线和 API\n```\n\n### 代码规范\n\n- Python 3.10+ 类型注解（`dataclass` 数据模型）\n- FastAPI 依赖注入（`Depends(get_db)` 数据库会话）\n- AI Provider 统一 `async` 接口（`generate` + `generate_stream`）\n- 前端使用 HTMX + 原生 JavaScript（无框架依赖）\n\n### 添加新的 AI Provider\n\n1. 在 `app/ai/` 下创建新文件，继承 `AIProvider` 接口\n2. 实现 `generate()`、`generate_stream()`、`model_name()` 三个方法\n3. 在 `app/config.py` 添加对应的环境变量\n4. 在 `app/ai/factory.py` 的 `create_ai_provider()` 中添加分支\n5. 在 `app/routes/chat.py` 的 `PROVIDER_KEY_MAP` 中注册密钥检查\n\n### 项目配置\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `MAX_UPLOAD_BYTES` | 10 MB | 文件上传大小限制 |\n| `MAX_PASTE_CHARS` | 500,000 | 粘贴文本字数限制 |\n| `DATABASE_URL` | 自动检测 | SQLite 数据库路径 |\n\n---\n\n## 许可证\n\nMIT License\n"}, "2698e1fadade95e6ac35005f7b0a643114002fff": {"t": 1785764191.0410469, "n": 3820, "h": "53e5b0735c6afa08", "c": "# AI 辅助剧本创作工具\n\n将小说文本（≥3 章）自动转换为结构化 YAML 剧本，支持电影、电视剧、舞台剧、动画。\n\n## 三步上手\n\n### 1. 安装 & 配置\n\n```bash\n# 克隆项目\ngit clone https://github.com/ailakala/script-tool.git\ncd script-tool\n\n# 复制配置文件\ncp .env.example .env\n```\n\n编辑 `.env` 文件，选择 AI 后端并填入 Key：\n\n**流水线用哪个？**\n\n| 方案 | 效果 | 花费 |\n|------|------|------|\n| **Claude API**（推荐） | 最好，中文理解强 | $2-5/次 |\n| **OpenAI GPT** | 好 | $0.5-1/次 |\n| **DeepSeek**（推荐性价比） | 好，中文优秀 | ¥0.5-1/次 |\n| **Gemini**（Google） | 好，免费额度友好 | $0-0.5/次 |\n| **LM Studio / Ollama** | 中等，看本地模型质量 | 免费 |\n\n> `.env` 里每种方案都有写好的模板，取消对应注释即可。\n\n### 2. 启动\n\n```bash\nbash start.sh\n```\n\n打开浏览器访问 **http://localhost:8000**。\n\n> `start.sh` 会自动安装依赖、检查配置。首次运行会提示你编辑 `.env`。\n\n### 3. 使用\n\n1. 点 **新建项目** → 填项目名、选剧本类型\n2. 上传 `.txt` / `.docx` 文件，或直接粘贴小说文本（至少要有\"第一章\"\"第二章\"\"第三章\"）\n3. 点 **一键生成**（全自动），或 **分步生成**（每阶段可审查修改）\n\n---\n\n## 使用流程\n\n进入首页后，从左到右三步走：\n\n### 新建项目 → 导入小说 → 生成剧本\n\n1. 点 **新建项目**，填项目名、选择剧本类型（电影/电视剧/动画等）\n2. 在项目工作台上传 `.txt` / `.docx` / `.md` 文件，或直接粘贴小说文本（至少要有 3 章，比如\"第一章\"\"第二章\"\"第三章\"）\n3. 点 **一键生成**（6 个阶段自动跑完），或点 **分步生成**（每个阶段完成后暂停，可以审查 AI 的中间结果再继续）\n\n### 分步生成模式\n\n分步模式下，Stage 1/2/3 完成后会自动暂停，展示 AI 识别的人物、情节、场景结构：\n\n- **Stage 1** — 每章识别出哪些人物、地点、情节事件 → 检查有没有漏人或认错角色\n- **Stage 2** — 跨章节合并去重，整理人物关系图 → 调整关系、补充遗漏\n- **Stage 3** — 设计剧本场景列表 → 调整场景划分，增删合并场景\n\n审查满意后点 **继续** 进入下一阶段。也可以点 **跳过审查，直接完成** 让剩余阶段自动跑完。\n\n### 查看结果\n\n流水线跑完后，结果面板会出现生成的 YAML 剧本。可以：\n- 点 **查看/编辑剧本** 在线预览\n- 点 **下载 YAML** 保存到本地\n\n---\n\n## 配置参考\n\n### 流水线 AI 后端\n\n所有配置都通过环境变量，不设就用默认值：\n\n| 变量 | 默认值 | 作用 |\n|------|--------|------|\n| `SCRIPT_TOOL_AI_PROVIDER` | `claude` | 选哪个 AI：`claude` / `openai` / `deepseek` / `gemini` / `local` |\n| `SCRIPT_TOOL_AI_MODEL` | `claude-sonnet-4-6` | 模型名 |\n| `SCRIPT_TOOL_ANTHROPIC_API_KEY` | — | Claude API Key |\n| `SCRIPT_TOOL_OPENAI_API_KEY` | — | OpenAI API Key |\n| `SCRIPT_TOOL_OPENAI_BASE_URL` | — | OpenAI 自定义 API 地址（如中转服务） |\n| `SCRIPT_TOOL_DEEPSEEK_API_KEY` | — | DeepSeek API Key |\n| `SCRIPT_TOOL_DEEPSEEK_MODEL` | `deepseek-chat` | DeepSeek 模型名 |\n| `SCRIPT_TOOL_GEMINI_API_KEY` | — | Gemini API Key |\n| `SCRIPT_TOOL_GEMINI_MODEL` | `gemini-2.5-flash` | Gemini 模型名 |\n| `SCRIPT_TOOL_LOCAL_LLM_URL` | `http://localhost:1234/v1` | 本地模型 API 地址 |\n| `SCRIPT_TOOL_LOCAL_LLM_API_KEY` | `not-needed` | 本地模型 API Key（LM Studio 不验证） |\n| `SCRIPT_TOOL_DATABASE_URL` | `sqlite:///storage/db.sqlite` | 数据库位置 |\n\n### AI 助手（右下角聊天面板）\n\n项目页面右下角的 AI 助手支持 **5 种模型** 切换，无需重启。启用方式：\n\n1. **Claude** — 设置 `SCRIPT_TOOL_ANTHROPIC_API_KEY`\n2. **GPT (OpenAI)** — 设置 `SCRIPT_TOOL_OPENAI_API_KEY`，可选设置 `SCRIPT_TOOL_OPENAI_BASE_URL` 使用中转 API\n3. **DeepSeek** — 设置 `SCRIPT_TOOL_DEEPSEEK_API_KEY`，可选设置 `SCRIPT_TOOL_DEEPSEEK_MODEL`（默认 `deepseek-chat`）\n4. **Gemini (Google)** — 设置 `SCRIPT_TOOL_GEMINI_API_KEY`，可选设置 `SCRIPT_TOOL_GEMINI_MODEL`（默认 `gemini-2.5-flash`）\n5. **本地模型** — 启动 LM Studio / Ollama，设置 `SCRIPT_TOOL_LOCAL_LLM_URL`（默认 `http://localhost:1234/v1`）\n\n> **提示**：API Key 只需配置你想用的模型对应的那个。未配置的模型在切换后会返回错误提示。\n\n### 获取 API Key\n\n| 模型 | 获取地址 | 免费额度 |\n|------|---------|---------|\n| Claude | [console.anthropic.com](https://console.anthropic.com) | 无 |\n| GPT (OpenAI) | [platform.openai.com](https://platform.openai.com) | 新用户 $5 |\n| DeepSeek | [platform.deepseek.com](https://platform.deepseek.com) | 新用户送 500 万 tokens |\n| Gemini | [aistudio.google.com](https://aistudio.google.com) | 免费额度（速率限制） |\n| 本地模型 | [lmstudio.ai](https://lmstudio.ai) / [ollama.com](https://ollama.com) | 免费 |\n\n---\n\n## 常见问题\n\n**Q: WSL / Git Bash 下启动后数据库报错 \"database is locked\"？**\nA: 此问题已自动处理。`config.py` 启动时会检测运行环境，自动将数据库重定向到 Windows 本机路径（`C:/Users/<用户名>/script_tool.db`），无需手动配置。\n```\n\n**Q: 用 LM Studio 时提示连接失败？**\nA: 检查三个点：\n1. LM Studio 的 Server 是否已启动（Developer 标签 → Start Server）\n2. 端口默认 1234，不要改\n3. 模型名要和 LM Studio 里加载的一致\n\n**Q: 一键生成跑到一半报错了？**\nA: 切到分步模式重试——分步模式每步都有缓存，之前已完成的不需要重新跑。\n\n**Q: 分步模式下 Stage 1/2/3 显示 \"请先运行 Stage X\"？**\nA: 按顺序来，先跑 Stage 0，再跑 Stage 1，以此类推。\n\n**Q: 一次能处理多长的小说？**\nA: 建议 20 章以内、50 万字以内。超长的建议分成多个项目分批处理。\n"}, "1257921fd384504f831ba027e45f7c8360bd749f": {"t": 1785764192.2947893, "n": 2352, "h": "9b8f9d7b7c99f2e3", "c": "# AI 辅助剧本创作工具\n\n将小说文本（≥3 章）自动转换为结构化 YAML 剧本，支持电影、电视剧、舞台剧、动画。\n\n## 三步上手\n\n### 1. 安装 & 配置\n\n```bash\n# 克隆项目\ngit clone https://github.com/ailakala/script-tool.git\ncd script-tool\n\n# 复制配置文件\ncp .env.example .env\n```\n\n编辑 `.env` 文件，选择 AI 后端并填入 Key：\n\n**我该选哪个？**\n\n| 方案 | 效果 | 花费 |\n|------|------|------|\n| **Claude API**（推荐） | 最好，中文理解强 | $2-5/次 |\n| **LM Studio** | 中等，看本地模型质量 | 免费 |\n| **OpenAI GPT** | 好 | $0.5-1/次 |\n\n> `.env` 里每种方案都有写好的模板，取消对应注释即可。\n\n### 2. 启动\n\n```bash\nbash start.sh\n```\n\n打开浏览器访问 **http://localhost:8000**。\n\n> `start.sh` 会自动安装依赖、检查配置。首次运行会提示你编辑 `.env`。\n\n### 3. 使用\n\n1. 点 **新建项目** → 填项目名、选剧本类型\n2. 上传 `.txt` / `.docx` 文件，或直接粘贴小说文本（至少要有\"第一章\"\"第二章\"\"第三章\"）\n3. 点 **一键生成**（全自动），或 **分步生成**（每阶段可审查修改）\n\n---\n\n## 使用流程\n\n进入首页后，从左到右三步走：\n\n### 新建项目 → 导入小说 → 生成剧本\n\n1. 点 **新建项目**，填项目名、选择剧本类型（电影/电视剧/动画等）\n2. 在项目工作台上传 `.txt` / `.docx` / `.md` 文件，或直接粘贴小说文本（至少要有 3 章，比如\"第一章\"\"第二章\"\"第三章\"）\n3. 点 **一键生成**（6 个阶段自动跑完），或点 **分步生成**（每个阶段完成后暂停，可以审查 AI 的中间结果再继续）\n\n### 分步生成模式\n\n分步模式下，Stage 1/2/3 完成后会自动暂停，展示 AI 识别的人物、情节、场景结构：\n\n- **Stage 1** — 每章识别出哪些人物、地点、情节事件 → 检查有没有漏人或认错角色\n- **Stage 2** — 跨章节合并去重，整理人物关系图 → 调整关系、补充遗漏\n- **Stage 3** — 设计剧本场景列表 → 调整场景划分，增删合并场景\n\n审查满意后点 **继续** 进入下一阶段。也可以点 **跳过审查，直接完成** 让剩余阶段自动跑完。\n\n### 查看结果\n\n流水线跑完后，结果面板会出现生成的 YAML 剧本。可以：\n- 点 **查看/编辑剧本** 在线预览\n- 点 **下载 YAML** 保存到本地\n\n---\n\n## 配置参考\n\n所有配置都通过环境变量，不设就用默认值：\n\n| 变量 | 默认值 | 作用 |\n|------|--------|------|\n| `SCRIPT_TOOL_AI_PROVIDER` | `claude` | 选哪个 AI：`claude` / `openai` / `local` |\n| `SCRIPT_TOOL_AI_MODEL` | `claude-sonnet-4-6` | 模型名（用 local 时改成 LM Studio 里加载的模型） |\n| `SCRIPT_TOOL_ANTHROPIC_API_KEY` | — | Claude API Key |\n| `SCRIPT_TOOL_OPENAI_API_KEY` | — | OpenAI API Key |\n| `SCRIPT_TOOL_LOCAL_LLM_URL` | `http://localhost:1234/v1` | 本地模型 API 地址 |\n| `SCRIPT_TOOL_LOCAL_LLM_API_KEY` | `not-needed` | 本地模型 API Key（LM Studio 不验证） |\n| `SCRIPT_TOOL_DATABASE_URL` | `sqlite:///storage/db.sqlite` | 数据库位置 |\n\n---\n\n## 常见问题\n\n**Q: WSL / Git Bash 下启动后数据库报错 \"database is locked\"？**\nA: 此问题已自动处理。`config.py` 启动时会检测运行环境，自动将数据库重定向到 Windows 本机路径（`C:/Users/<用户名>/script_tool.db`），无需手动配置。\n```\n\n**Q: 用 LM Studio 时提示连接失败？**\nA: 检查三个点：\n1. LM Studio 的 Server 是否已启动（Developer 标签 → Start Server）\n2. 端口默认 1234，不要改\n3. 模型名要和 LM Studio 里加载的一致\n\n**Q: 一键生成跑到一半报错了？**\nA: 切到分步模式重试——分步模式每步都有缓存，之前已完成的不需要重新跑。\n\n**Q: 分步模式下 Stage 1/2/3 显示 \"请先运行 Stage X\"？**\nA: 按顺序来，先跑 Stage 0，再跑 Stage 1，以此类推。\n\n**Q: 一次能处理多长的小说？**\nA: 建议 20 章以内、50 万字以内。超长的建议分成多个项目分批处理。\n"}, "e1efa5be30a1c81370b693147104e8bbd19c96e8": {"t": 1785764194.2999527, "n": 2351, "h": "f673d85509b4431c", "c": "# AI 辅助剧本创作工具\n\n将小说文本（≥3 章）自动转换为结构化 YAML 剧本，支持电影、电视剧、舞台剧、动画。\n\n## 三步上手\n\n### 1. 安装 & 配置\n\n```bash\n# 克隆项目\ngit clone https://github.com/ailakala/script-tool.git\ncd script-tool\n\n# 复制配置文件\ncp .env.example .env\n```\n\n编辑 `.env` 文件，选择 AI 后端并填入 Key：\n\n**我该选哪个？**\n\n| 方案 | 效果 | 花费 |\n|------|------|------|\n| **Claude API**（推荐） | 最好，中文理解强 | $2-5/次 |\n| **LM Studio** | 中等，看本地模型质量 | 免费 |\n| **OpenAI GPT** | 好 | $0.5-1/次 |\n\n> `.env` 里每种方案都有写好的模板，取消对应注释即可。\n\n### 2. 启动\n\n```bash\nbash start.sh\n```\n\n打开浏览器访问 **http://localhost:8000**。\n\n> `start.sh` 会自动安装依赖、检查配置。首次运行会提示你编辑 `.env`。\n\n### 3. 使用\n\n1. 点 **新建项目** → 填项目名、选剧本类型\n2. 上传 `.txt` / `.docx` 文件，或直接粘贴小说文本（至少要有\"第一章\"\"第二章\"\"第三章\"）\n3. 点 **一键生成**（全自动），或 **分步生成**（每阶段可审查修改）\n\n---\n\n## 使用流程\n\n进入首页后，从左到右三步走：\n\n### 新建项目 → 导入小说 → 生成剧本\n\n1. 点 **新建项目**，填项目名、选择剧本类型（电影/电视剧/动画等）\n2. 在项目工作台上传 `.txt` / `.docx` / `.md` 文件，或直接粘贴小说文本（至少要有 3 章，比如\"第一章\"\"第二章\"\"第三章\"）\n3. 点 **一键生成**（6 个阶段自动跑完），或点 **分步生成**（每个阶段完成后暂停，可以审查 AI 的中间结果再继续）\n\n### 分步生成模式\n\n分步模式下，Stage 1/2/3 完成后会自动暂停，展示 AI 识别的人物、情节、场景结构：\n\n- **Stage 1** — 每章识别出哪些人物、地点、情节事件 → 检查有没有漏人或认错角色\n- **Stage 2** — 跨章节合并去重，整理人物关系图 → 调整关系、补充遗漏\n- **Stage 3** — 设计剧本场景列表 → 调整场景划分，增删合并场景\n\n审查满意后点 **继续** 进入下一阶段。也可以点 **跳过审查，直接完成** 让剩余阶段自动跑完。\n\n### 查看结果\n\n流水线跑完后，结果面板会出现生成的 YAML 剧本。可以：\n- 点 **查看/编辑剧本** 在线预览\n- 点 **下载 YAML** 保存到本地\n\n---\n\n## 配置参考\n\n所有配置都通过环境变量，不设就用默认值：\n\n| 变量 | 默认值 | 作用 |\n|------|--------|------|\n| `SCRIPT_TOOL_AI_PROVIDER` | `claude` | 选哪个 AI：`claude` / `openai` / `local` |\n| `SCRIPT_TOOL_AI_MODEL` | `claude-sonnet-4-6` | 模型名（用 local 时改成 LM Studio 里加载的模型） |\n| `SCRIPT_TOOL_ANTHROPIC_API_KEY` | — | Claude API Key |\n| `SCRIPT_TOOL_OPENAI_API_KEY` | — | OpenAI API Key |\n| `SCRIPT_TOOL_LOCAL_LLM_URL` | `http://localhost:1234/v1` | 本地模型 API 地址 |\n| `SCRIPT_TOOL_LOCAL_LLM_API_KEY` | `not-needed` | 本地模型 API Key（LM Studio 不验证） |\n| `SCRIPT_TOOL_DATABASE_URL` | `sqlite:///storage/db.sqlite` | 数据库位置 |\n\n---\n\n## 常见问题\n\n**Q: WSL 下启动后数据库报错 \"database is locked\"？**\nA: 设置数据库路径到 Windows 本机目录：\n```bash\nexport SCRIPT_TOOL_DATABASE_URL=\"sqlite:///C:/Users/<你的用户名>/script_tool.db\"\n```\n\n**Q: 用 LM Studio 时提示连接失败？**\nA: 检查三个点：\n1. LM Studio 的 Server 是否已启动（Developer 标签 → Start Server）\n2. 端口默认 1234，不要改\n3. 模型名要和 LM Studio 里加载的一致\n\n**Q: 一键生成跑到一半报错了？**\nA: 切到分步模式重试——分步模式每步都有缓存，之前已完成的不需要重新跑。\n\n**Q: 分步模式下 Stage 1/2/3 显示 \"请先运行 Stage X\"？**\nA: 按顺序来，先跑 Stage 0，再跑 Stage 1，以此类推。\n\n**Q: 一次能处理多长的小说？**\nA: 建议 20 章以内、50 万字以内。超长的建议分成多个项目分批处理。\n"}, "461e9b67805e89c5ed4dba29236baeec1a99a3ca": {"t": 1785764195.7094333, "n": 2968, "h": "56c837c2515c0dea", "c": "# AI 辅助剧本创作工具\n\n将小说文本（≥3 章）自动转换为结构化 YAML 剧本，支持电影、电视剧、舞台剧、动画。\n\n## 三步上手\n\n### 1. 安装依赖\n\n```bash\npip install -r requirements.txt\n```\n\n### 2. 选择 AI 后端（三选一）\n\n**我该选哪个？**\n\n| 方案 | 效果 | 需要什么 | 花费 |\n|------|------|----------|------|\n| **Claude API**（推荐） | 最好，中文理解强 | 申请 API Key | $2-5/次 |\n| **LM Studio**（免费） | 中等，受本地模型影响 | 安装 LM Studio + 下载模型 | 免费 |\n| **OpenAI GPT** | 好 | 申请 API Key | $0.5-1/次 |\n\n#### 方案 A：Claude API（推荐，效果最好）\n\n```bash\nexport SCRIPT_TOOL_ANTHROPIC_API_KEY=\"sk-ant-...\"\n# 其余用默认值，无需额外设置\n```\n\nAPI Key 在 [console.anthropic.com](https://console.anthropic.com) 申请。\n\n#### 方案 B：LM Studio（免费，本地运行）\n\n1. 下载安装 [LM Studio](https://lmstudio.ai)\n2. 在 LM Studio 里搜索下载一个中文好的模型，比如 **Qwen3-14B** 或 **Qwen2.5-7B-Instruct**\n3. 加载模型后，切到 **Developer** 标签，点 **Start Server**（默认端口 1234）\n\n```bash\nexport SCRIPT_TOOL_AI_PROVIDER=local\nexport SCRIPT_TOOL_AI_MODEL=qwen2.5-7b-instruct # 改成你加载的模型名\n```\n\n> LM Studio 默认在 `localhost:1234` 提供 API，项目已预设此地址。\n\n#### 方案 C：OpenAI GPT\n\n```bash\nexport SCRIPT_TOOL_OPENAI_API_KEY=\"sk-...\"\nexport SCRIPT_TOOL_AI_PROVIDER=openai\nexport SCRIPT_TOOL_AI_MODEL=gpt-4o\n```\n\n### 3. 启动\n\n```bash\n# Windows / WSL 用户先设置数据库路径（重要！）\nexport SCRIPT_TOOL_DATABASE_URL=\"sqlite:///C:/Users/<你的用户名>/script_tool.db\"\n\nuvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n```\n\n打开浏览器访问 **http://localhost:8000**。\n\n---\n\n## 使用流程\n\n进入首页后，从左到右三步走：\n\n### 新建项目 → 导入小说 → 生成剧本\n\n1. 点 **新建项目**，填项目名、选择剧本类型（电影/电视剧/动画等）\n2. 在项目工作台上传 `.txt` / `.docx` / `.md` 文件，或直接粘贴小说文本（至少要有 3 章，比如\"第一章\"\"第二章\"\"第三章\"）\n3. 点 **一键生成**（6 个阶段自动跑完），或点 **分步生成**（每个阶段完成后暂停，可以审查 AI 的中间结果再继续）\n\n### 分步生成模式\n\n分步模式下，Stage 1/2/3 完成后会自动暂停，展示 AI 识别的人物、情节、场景结构：\n\n- **Stage 1** — 每章识别出哪些人物、地点、情节事件 → 检查有没有漏人或认错角色\n- **Stage 2** — 跨章节合并去重，整理人物关系图 → 调整关系、补充遗漏\n- **Stage 3** — 设计剧本场景列表 → 调整场景划分，增删合并场景\n\n审查满意后点 **继续** 进入下一阶段。也可以点 **跳过审查，直接完成** 让剩余阶段自动跑完。\n\n### 查看结果\n\n流水线跑完后，结果面板会出现生成的 YAML 剧本。可以：\n- 点 **查看/编辑剧本** 在线预览\n- 点 **下载 YAML** 保存到本地\n\n---\n\n## 配置参考\n\n所有配置都通过环境变量，不设就用默认值：\n\n| 变量 | 默认值 | 作用 |\n|------|--------|------|\n| `SCRIPT_TOOL_AI_PROVIDER` | `claude` | 选哪个 AI：`claude` / `openai` / `local` |\n| `SCRIPT_TOOL_AI_MODEL` | `claude-sonnet-4-6` | 模型名（用 local 时改成 LM Studio 里加载的模型） |\n| `SCRIPT_TOOL_ANTHROPIC_API_KEY` | — | Claude API Key |\n| `SCRIPT_TOOL_OPENAI_API_KEY` | — | OpenAI API Key |\n| `SCRIPT_TOOL_LOCAL_LLM_URL` | `http://localhost:1234/v1` | 本地模型 API 地址 |\n| `SCRIPT_TOOL_LOCAL_LLM_API_KEY` | `not-needed` | 本地模型 API Key（LM Studio 不验证） |\n| `SCRIPT_TOOL_DATABASE_URL` | `sqlite:///storage/db.sqlite` | 数据库位置 |\n\n---\n\n## 常见问题\n\n**Q: WSL 下启动后数据库报错 \"database is locked\"？**\nA: 设置数据库路径到 Windows 本机目录：\n```bash\nexport SCRIPT_TOOL_DATABASE_URL=\"sqlite:///C:/Users/<你的用户名>/script_tool.db\"\n```\n\n**Q: 用 LM Studio 时提示连接失败？**\nA: 检查三个点：\n1. LM Studio 的 Server 是否已启动（Developer 标签 → Start Server）\n2. 端口默认 1234，不要改\n3. 模型名要和 LM Studio 里加载的一致\n\n**Q: 一键生成跑到一半报错了？**\nA: 切到分步模式重试——分步模式每步都有缓存，之前已完成的不需要重新跑。\n\n**Q: 分步模式下 Stage 1/2/3 显示 \"请先运行 Stage X\"？**\nA: 按顺序来，先跑 Stage 0，再跑 Stage 1，以此类推。\n\n**Q: 一次能处理多长的小说？**\nA: 建议 20 章以内、50 万字以内。超长的建议分成多个项目分批处理。\n"}, "76c4a6622d46112a36b1eea60bed53f409e365cd": {"t": 1785764197.320114, "n": 2806, "h": "02200a310ca82bce", "c": "# AI 辅助剧本创作工具\n\n将 3 章以上小说文本自动转换为结构化剧本（YAML 格式），降低改编门槛，提升效率。\n\n## 快速开始\n\n```bash\n# 安装依赖\npip install -r requirements.txt\n\n# 设置 AI API Key（至少选一个）\nexport SCRIPT_TOOL_ANTHROPIC_API_KEY=\"sk-ant-...\" # Claude\nexport SCRIPT_TOOL_OPENAI_API_KEY=\"sk-...\" # GPT\n# 或使用本地模型\nexport SCRIPT_TOOL_AI_PROVIDER=\"local\"\nexport SCRIPT_TOOL_LOCAL_LLM_URL=\"http://localhost:8000/v1\"\nexport SCRIPT_TOOL_LOCAL_LLM_API_KEY=\"your-key\" # 可选\n\n# 启动\nuvicorn app.main:app --reload\n```\n\n访问 http://localhost:8000\n\n## 使用流程\n\n1. **新建项目** → 填写剧本元信息（标题、来源、剧本类型）\n2. **导入小说** → 上传 .txt/.docx/.md 文件，或直接粘贴文本（需 ≥ 3 章）\n3. **一键生成** → AI 自动完成 6 阶段流水线转化\n4. **查看结果** → 在线预览 YAML 剧本，支持下载\n\n## 中间结果干预\n\nAI 流水线在以下阶段支持暂停和人工介入：\n\n| Stage | 内容 | 可干预 |\n|-------|------|--------|\n| 0 | 文本预处理（章节拆分） | — |\n| 1 | 分章节分析（人物、地点、情节） | 审核 AI 识别结果 |\n| 2 | 跨章节综合（去重、关系图） | 调整人物关系和情节线 |\n| 3 | 剧本结构设计（场景列表） | 调整场景划分和结构 |\n| 4 | 逐场内容生成 | — |\n| 5 | YAML 组装 & 校验 | — |\n\n## 剧本 YAML Schema\n\n输出剧本遵循 [YAML Schema 规范](docs/script-yaml-schema.md)，包含：\n- `meta` — 元数据\n- `config` — 生成配置\n- `characters` — 人物表（ID 体系、关系图）\n- `scenes` — 场景列表（扁平结构、结构化 content 数组）\n- `extensions` — 类型特定扩展（TV 分集大纲、电影节拍表等）\n\n## 项目结构\n\n```\napp/\n├── main.py # FastAPI 入口\n├── config.py # 配置（环境变量驱动）\n├── db.py # 数据库连接\n├── models.py # ORM 模型（Project, PipelineRun, StageCache）\n├── routes/\n│ ├── pages.py # SSR 页面路由\n│ └── api.py # REST API + SSE 流式\n├── pipeline/\n│ ├── executor.py # 流水线调度器\n│ ├── stage0_preprocess.py # 文本预处理\n│ ├── stage1_chapter_analysis.py # 分章节分析\n│ ├── stage2_cross_chapter_synthesis.py # 跨章节综合\n│ ├── stage3_script_structure.py # 剧本结构设计\n│ ├── stage4_scene_generation.py # 逐场内容生成\n│ └── stage5_assembly.py # YAML 组装校验\n├── ai/\n│ ├── interface.py # AI Provider 抽象接口\n│ ├── claude.py # Claude API\n│ ├── openai.py # OpenAI API\n│ ├── local.py # 本地模型（OpenAI 兼容）\n│ └── factory.py # 工厂函数\n└── templates/ # Jinja2 模板\n```\n\n## 技术栈\n\n- **Web**: FastAPI + Jinja2 SSR + HTMX\n- **数据库**: SQLite (SQLAlchemy ORM)\n- **AI**: Claude / GPT / 本地模型（通过统一接口切换）\n- **测试**: pytest (35 tests)\n\n## 测试\n\n```bash\npytest tests/ -v # 运行全部 35 个测试\n```\n\n## 配置\n\n所有配置通过环境变量：\n\n| 变量 | 默认 | 说明 |\n|------|------|------|\n| `SCRIPT_TOOL_AI_PROVIDER` | `claude` | AI 后端（claude/openai/local） |\n| `SCRIPT_TOOL_AI_MODEL` | `claude-sonnet-4-6` | 模型名称 |\n| `SCRIPT_TOOL_ANTHROPIC_API_KEY` | — | Claude API Key |\n| `SCRIPT_TOOL_OPENAI_API_KEY` | — | OpenAI API Key |\n| `SCRIPT_TOOL_LOCAL_LLM_URL` | `http://localhost:8000/v1` | 本地模型地址 |\n| `SCRIPT_TOOL_LOCAL_LLM_API_KEY` | `not-needed` | 本地模型 API Key |\n| `SCRIPT_TOOL_DATABASE_URL` | `sqlite:///storage/db.sqlite` | 数据库连接 |\n\n## 限制\n\n- 一次性处理上限: 20 章、50 万字\n- 上传文件: 10MB\n- 在线粘贴: 50 万字符\n- 单次转换 LLM 成本: ~$2-5 (Claude) / ~$0.5-1 (GPT-4o)\n"}}}} |