chaos/hack
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
68a9071cf1e339707f28c350f9274678723e2028
hack/tools/scripts/llm-key-hunter/results/_cache/content/ailakala_script-tool.json
T
OpenCode 68a9071cf1 feat: reconcile local master with origin (exa/hot-platform hunters, leaks ledger, latest results) 
Local branch had diverged from origin/master (sibling commits on the same base). Rewrote local history linearly on top of origin/master, folding in all local content: exa/hot-platform discovery hunters, leaks ledger, nightly sweep orchestrator, updated .gitignore and skill docs, plus the latest hunt output and vault state. Remote-only files (vault keys, channel scripts) were restored rather than dropped, so the resulting tree is a full union of both sides.
2026-08-07 12:53:47 +08:00

1 line
112 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{"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"}}, ".env.example": {"fed82c49a37084585bc4f3370dbb56af13d529a1": {"t": 1786068544.6037292, "n": 1884, "h": "5be8e1299e54e439", "c": "# AI 剧本创作工具 — 配置文件\n# 复制此文件为 .env 并填入你的配置\n\n# ═══════════════════════════════════════════════════════════════\n# 流水线 AI 后端（用于剧本生成流水线，选一个）\n# ═══════════════════════════════════════════════════════════════\n\n# 方案 A：Claude API（推荐，中文理解最强）\nSCRIPT_TOOL_AI_PROVIDER=claude\nSCRIPT_TOOL_AI_MODEL=claude-sonnet-4-6\n# SCRIPT_TOOL_ANTHROPIC_API_KEY=sk-ant-你的key\n\n# 方案 B：OpenAI GPT\n# SCRIPT_TOOL_AI_PROVIDER=openai\n# SCRIPT_TOOL_AI_MODEL=gpt-4o\n# SCRIPT_TOOL_OPENAI_API_KEY=sk-你的key\n\n# 方案 C：DeepSeek（推荐性价比，中文优秀）\n# SCRIPT_TOOL_AI_PROVIDER=deepseek\n# SCRIPT_TOOL_AI_MODEL=deepseek-chat\n# SCRIPT_TOOL_DEEPSEEK_API_KEY=sk-你的key\n\n# 方案 D：Gemini（Google，免费额度友好）\n# SCRIPT_TOOL_AI_PROVIDER=gemini\n# SCRIPT_TOOL_AI_MODEL=gemini-2.5-flash\n# SCRIPT_TOOL_GEMINI_API_KEY=你的key\n\n# 方案 E：LM Studio / Ollama（免费本地运行）\n# SCRIPT_TOOL_AI_PROVIDER=local\n# SCRIPT_TOOL_AI_MODEL=qwen2.5-7b-instruct\n# (端口 1234 已预设)\n\n# ═══════════════════════════════════════════════════════════════\n# AI 助手聊天配置（项目页面右下角 AI 助手）\n# ═══════════════════════════════════════════════════════════════\n#\n# AI 助手支持 5 种模型，在页面下拉菜单中切换。\n# 你需要为你想用的模型配置对应的 API Key：\n\n# Claude：\n# SCRIPT_TOOL_ANTHROPIC_API_KEY=sk-ant-你的key\n\n# GPT (OpenAI)：\n# SCRIPT_TOOL_OPENAI_API_KEY=sk-你的key\n# 可选：自定义 API 地址（如使用中转服务）\n# SCRIPT_TOOL_OPENAI_BASE_URL=https://你的代理地址/v1\n\n# DeepSeek：\n# SCRIPT_TOOL_DEEPSEEK_API_KEY=sk-你的key\n# SCRIPT_TOOL_DEEPSEEK_MODEL=deepseek-chat # 可选，默认 deepseek-chat\n\n# Gemini (Google)：\n# SCRIPT_TOOL_GEMINI_API_KEY=你的key\n# SCRIPT_TOOL_GEMINI_MODEL=gemini-2.5-flash # 可选，默认 gemini-2.5-flash\n\n# 本地模型（LM Studio / Ollama）：\n# SCRIPT_TOOL_LOCAL_LLM_URL=http://localhost:1234/v1\n# SCRIPT_TOOL_LOCAL_LLM_API_KEY=not-needed\n\n# ═══════════════════════════════════════════════════════════════\n# 其他可选配置\n# ═══════════════════════════════════════════════════════════════\n\n# 数据库路径（Windows / WSL 用户建议设置）\n# SCRIPT_TOOL_DATABASE_URL=sqlite:///C:/Users/你的用户名/script_tool.db\n"}}}}
Reference in new issue View Git Blame Copy Permalink