🎬 Story Studio · 故事工坊

📖 项目简介

Story Studio（故事工坊） 是专为 AI Agent（如 Claude Code、Codex、Cursor 等支持 Skill 的智能体）打造的一站式短视频内容创作技能包。

做历史或人物故事类短视频，往往要在找选题、查史料、磨开头钩子、写口播稿、配音、对齐时间轴、拆分数十个分镜、保持AI生图画风一致、以及在剪映里一帧帧打关键帧做推拉运镜之间反复横跳。

Story Studio 把这一整套工业化流水线装进了一个 Skill 里：

flowchart LR
    A[💡 选题与黄金钩子] --> B[✍️ 口播文案定稿]
    B --> C[🎙️ 豆包语音大模型 / 自备配音]
    C --> D[⏱️ Coli 本地转录对齐]
    D --> E[🎨 3大画风分镜与配图]
    E --> F[🎞️ 剪映专业版草稿导出]

• 不需要从头拼凑多个散装 Skill：内部已深度整合写作、配音、语音识别、视觉分镜与剪映工程生成。
• 随时中断与接力：你可以只让它写稿改钩子；也可以丢给它一篇现成文稿和一段你自己录好的 MP3 放进文件夹，让 Agent 直接读取并接力完成后续的字幕时间戳对齐、配图和剪映草稿编排。

✨ 核心亮点

• 🧠 内置双王牌写作 Skill + 370+ 篇爆款对标文案库：拒绝 AI 味大纲文！内置经过深度蒸馏的「历史叙事」与「真实人物故事/女性传奇」两套完整 Writing-DNA，涵盖选题策略、黄金 3 秒开头钩子库、句式节奏与史实核查机制。
• 🎨 三套成熟配图画风 + 内置成品参考图库：支持 历史写实风、厚涂历史漫画风、黑白纪实叙事风。内置高水准正文与封面参考图（Reference Images），生图时自动对照材质与光影，告别跨镜头画风漂移与年代穿帮。
• 🎙️ 双路径灵活配音 + 本地高精度时间戳对齐：推荐直接接入 豆包语音大模型（V3 双向流式） 一键合成高表现力旁白；也支持将自己提前准备好的配音 MP3 放入项目文件夹让 Agent 直接读取。配合本地 Coli（基于 sherpa-onnx） 离线识别生成精准到字句的 SRT 时间轴，绝不按字数瞎猜时间。
• 🎞️ 真正可二次编辑的剪映专业版草稿：基于 pyJianYingDraft 直接生成剪映工程文件。自动将 9:16 竖屏图片、完整配音铺上时间轴，并自动写入覆盖全镜的慢推拉关键帧与切点冲击缩放（Punch Zoom），打开剪映即可预览微调并导出成片。
• ⚡ 零门槛自动环境初始化：无需手动折腾 Python、Node.js、FFmpeg 或语音识别环境。首次调用时，告诉 Agent 一键配置，即可在用户独立数据目录完成便携环境搭建。

🛠️ 四大核心模块详解

1️⃣ 文稿创作：双风格 Writing-DNA + 370+ 篇对标文案库

不只是简单地让大模型“写篇故事”，Story Studio 内置了两个完整的专业级写作子模块，提炼自数百篇视频号与短视频平台的高赞爆款逐字稿：

💡 写作模块能帮你做什么细节优化？

• 爆款选题策划：不知道发什么？指定朝代或人物方向，Agent 结合 370+ 篇对标库为你策划具备戏剧张力的选题卡与切入角度。
• 黄金开头钩子打磨：觉得开头不够抓人？让 Agent 按「数字连排」「宿命定格」「反常画面」「结局前置」「历史时刻」等内置钩子 DNA，一口气产出 3~5 版不同切口的开头供你挑选。
• 史实优先与事实核查：内置严格的《事实与风格优先级》规范——先建事实表与时间线，区分正史、争议与演义，绝不为了凑模板或押韵凭空捏造数字、引语和苦难情节。
• 精准字数控制与洗稿改稿：支持按目标字数（默认正负 5% 内）严格扩写、缩写、续写或调整口播呼吸感。

2️⃣ 视觉分镜与配图：三大专属画风 + 时代考据与参考图库

配图模块将文字转化为贴合口播节奏的视觉画面，支持 「只拆镜出提示词（交给其他工具生图）」「完善现有分镜」「直接调用生图工具出图」 三种模式。

🎨 内置三种高辨识度配图画风

🔍 为什么它生成的配图不违和、不穿帮？

1. 先音频后分镜（Audio-First）：绝不把文稿机械均分！先根据真实配音的 SRT 时间戳，按约 8 秒/图的叙事节奏规划镜头切点，确保第一句话从第 0 帧就有对应画面，且画面严格匹配当前正在讲的句子。
2. 逐镜时代与人物年龄阶段考据：自动识别每一镜所处的朝代、地域与人物年龄阶段（如青年、中年、晚年），将衣冠发式、建筑形制、器物货币落实到独立提示词中；近现代真实人物支持按时期检索对标历史原照。
3. 参考图锚定机制：生图时自动读取并传入内置同画风参考图（Reference Image），首图核验笔触与色调后再批量生成，大幅降低多镜头画风漂移。
4. 片头动态视频首尾帧设计（可选）：首次生图时可选择额外生成黄金前 6 秒的「首帧 + 尾帧 + 图生视频运镜提示词」，方便你用视频大模型制作极具吸引力的动态片头。

3️⃣ 配音与字幕对齐：豆包语音大模型 / 自备音频双通道

配音是连接「好文案」与「精准画面节奏」的核心桥梁。Story Studio 提供两条极其顺畅的配音路径：

路径 A：推荐配置「豆包语音大模型」，由 Agent 全自动合成

• 基于火山引擎豆包语音 V3 双向流式 WebSocket 协议，支持最新的 seed-tts-2.0（2.0通用高表现力音色）与 seed-icl-2.0（声音复刻2.0音色）。
• 安全省心：你只需在豆包语音控制台获取 API Key、speaker ID（音色ID） 和 resource_id。API Key 支持通过系统加密存储（Windows DPAPI / macOS & Linux 0600 权限文件）或环境变量保存，绝不写入代码仓库或项目明文。
• 防重复扣费与完整性核验：合成前确认音色与语速，合成后自动通过 ffprobe/ffmpeg 校验音频完整性，并记录文本与音频哈希，同稿同音色绝不重复发起收费请求。

路径 B：提前准备好配音 MP3，放入文件夹让 Agent 直接读取

• 如果你习惯使用剪映克隆音色、其他 TTS 软件，或者真人自己录好音，只需将最终的 .mp3 音频文件丢进项目文件夹，告诉 Agent：“配音我已经放进文件夹了，直接用这个音频继续做分镜和剪映草稿”。
• Agent 会自动读取你的音频文件，跳过云端合成，直接进入下一步的本地字幕对齐。

⏱️ Coli 本地离线语音识别与音文核验

• 无论采用哪种配音方式，Agent 都会调用本地 Coli（基于 sherpa-onnx） 离线生成带精准时间戳的 .srt 字幕，并自动对照你的定稿原文核对人名、地名与专有名词，为后续分镜提供毫秒级的时间依据。

4️⃣ 剪映专业版草稿导出：推拉运镜与时间轴一键成型

所有素材就绪后，Story Studio 会直接生成剪映专业版（JianYing Pro）可识别的本地草稿工程：

• 语义对齐核验（Semantic Alignment）：导出前自动执行 check_handoff.py 与逐镜语义核查，确保每一张图片出现的时间段，正好对应口播里讲到的那个人物和事件。
• 电影感动态运镜（拒绝死板静帧）：
  • 全镜缓入缓出慢推拉：每张图从切入到切出，自动计算平滑的推拉幅度（默认约 16~20 秒走完 12% 幅度，根据镜长智能自适应，远景与人物贴边分别优化），全程流动不停滞。
  • 切点冲击缩放（Cut Punch）：在常规镜头切换处自动写入慢速出镜推近（1.28x）与进镜拉回（1.50x）关键帧，既保留视觉呼吸感与冲击力，又避免了剪映自带转场容易出现的闪黑帧问题。
• 防素材丢失与纯净交付：所有图片与音频自动复制进剪映草稿目录，默认 1080×1920（9:16 竖屏）、30fps、铺满整段配音；默认不强制上屏字幕（需要时只需说一句“加上可编辑字幕”）。
• 可选本地 FFmpeg 渲染：如果你不需要进剪映微调，也可以明确要求使用内置的高精度亚像素仿射变换脚本，直接在本地渲染输出 final.mp4。

🚀 快速开始

第一步：一键安装 Skill（提供三种超简便方式）

你可以根据自己的使用习惯，选择以下任意一种方式进行一键安装：

方式 A（最推荐·零操作）：在 AI 对话框中发一句话，让 Agent 自动安装

如果你的 Agent（如 Codex、Claude Code、Cursor 等）拥有终端执行权限，你连命令行都不用打开，直接在任意对话框中发送：

请帮我把这个 GitHub 仓库克隆安装到你的 skills 目录，并完成依赖环境检查：
https://github.com/konlu/story-studio
Agent 会自动识别自身 skills 目录（如 `~/.codex/skills/story-studio`），自动拉取并完成接入！

---

#### 方式 B（极客·一行命令直达）：终端一条命令克隆
打开终端（Terminal 或 PowerShell），粘贴对应系统的一行命令即可：

```powershell
# Windows (PowerShell)
git clone https://github.com/konlu/story-studio.git "$HOME\.codex\skills\story-studio"

# macOS / Linux
git clone https://github.com/konlu/story-studio.git ~/.codex/skills/story-studio

💡 注：若使用 Claude Code 或其他 Agent，只需将路径中的 .codex 替换为 .claude 或 .agents 即可。

方式 C（下载 Zip 用户）：双击一键安装器

如果你是从 GitHub 下载的 Release 压缩包（.zip），解压后无需手动翻找系统隐藏目录：

• Windows：直接双击运行文件夹内的 install.bat
• macOS / Linux：终端进入该文件夹后运行 ./install.sh

脚本会自动探测系统中可用的 Agent 技能目录并自动部署到位。

第二步：一句话让 Agent 自动配置环境

无需自己手动折腾 Python、Node.js、FFmpeg 或配置剪映路径！安装后直接对 Agent 发送：

使用 $story-studio，帮我一键检查并自动配置全部运行环境。

💡 智能按需初始化：如果你只用它写文案，它不会安装任何多媒体组件；当需要配音、转录和导出剪映草稿时，原生启动器（bootstrap.ps1 / bootstrap.sh）会自动在用户独立数据目录配置好 Python 3.11 (uv)、Node.js LTS、Coli、FFmpeg、pyJianYingDraft 等全部依赖。

第三步：开始你的创作！

你可以直接用大白话告诉 Agent 你想做什么。下面看看最常用的几种姿势 👇

🎛️ 灵活的工作流开关

Story Studio 内部通过 写作（write）、配图（illustrate）、剪映草稿（draft） 三个主开关控制边界，配音与转录作为无缝衔接步骤按需触发。

你不需要写任何配置文件，直接用自然语言指挥，或者显式声明开关状态：

💬 常用提示词示例

场景 1：全流程一条龙制作（从选题文案到剪映草稿）

使用 $story-studio，制作一期关于「张居正考成法改革」的历史短视频。
1. 写作：采用历史叙事风，约 1800 字，先给我 3 个不同切入角度的开头钩子让我选，定稿后再继续。
2. 配音：定稿后使用我配置好的豆包语音生成 MP3（如果还没配置请引导我）。
3. 配图：用 Coli 对齐时间轴后拆成 20 镜，采用「厚涂历史漫画风」，9:16 竖屏生成配图，并带 3:4 和 4:3 封面。
4. 草稿：生成 1080x1920 的剪映专业版草稿，加入慢推拉运镜，默认不显示字幕。

场景 2：使用「人物故事风」写女性传奇口播稿

使用 $story-studio，只写一篇关于「林巧稚」的人物故事口播稿。
采用人物故事风，单集约 1600 字。
请先核实她的生平关键时间节点与真实数字，使用“数字连排”或“反常画面”做开头钩子，只交付文稿和事实核查表。

场景 3：自己准备好配音放在文件夹中，让 Agent 读取并完成后期

使用 $story-studio，继续当前文件夹里的项目。
我已经把定稿文案 `script.md` 和我自己录好的配音 `voice.mp3` 放进这个文件夹了。
请直接读取我的配音文件，用本地 Coli 生成字幕对齐时间轴，按「黑白叙事风」拆 18 个分镜并生成配图，最后直接导出到我的剪映草稿箱。

场景 4：只拆解分镜与生图提示词（交给外部 Midjourney / 即梦 等工具生图）

使用 $story-studio，写作关、配图开、剪映草稿关。
读取文件夹里的定稿和 MP3 配音，先做音文时间对齐，然后按「历史写实风」拆解 22 个分镜。
注意：这次只输出带时间戳的 STORYBOARD.md 分镜表和每镜独立的完整中文生图提示词，不要实际调用生图工具。

场景 5：单镜精准返工与版本迭代

使用 $story-studio，继续这个项目。
文案、配音和前面生成的图片都保持不变，只重做第 8 镜和第 15 镜的配图（第 8 镜人物年龄改成晚年阶段），然后用新图片重新导出一版带可编辑字幕的剪映草稿，保留旧草稿别覆盖。

📂 项目目录结构与交付产物

仓库结构一览

story-studio/
├── SKILL.md                        # AI Agent 核心总控指令与路由规则
├── README.md                       # 项目说明文档
├── install.bat / .ps1 / .sh        # 跨平台一键安装脚本（自动寻路部署）
├── scripts/                        # 跨平台环境自动初始化、豆包TTS、交接核验等核心脚本
│   ├── bootstrap.ps1 / .sh         # Windows / macOS / Linux 零依赖启动器
│   ├── doubao_tts.py               # 豆包语音 V3 双向 WebSocket 合成客户端
│   ├── voice_settings.py           # 音色配置与本地加密凭据管理
│   └── check_handoff.py            # 剪映导出前的音图语义与时间轴一致性检查
├── references/                     # 事实核查原则、豆包配置指南、扩展赛道说明等
└── modules/                        # 内置四大专业子模块
    ├── history-writing/            # 【历史叙事模块】含 DNA 规则 + 57 篇高赞原稿与钩子分析
    ├── characterstory-writing/     # 【人物故事模块】含人物故事 DNA + 300+ 篇爆款对标语料库
    ├── history-image/              # 【分镜配图模块】含 3 套画风规则 + 12 张正文参考图 + 封面参考
    └── render-history-video/       # 【剪映草稿模块】含时间轴对齐、缓入缓出推拉运镜与草稿导出

每次创作你会得到什么交付物？

所有创作产物均干净地保存在你自己的工作区项目目录中，绝不污染 Skill 源码：

📦 依赖与隐私说明

1. 自动管理的运行环境

Story Studio 内置的启动器会在技能目录之外的用户数据目录（Windows 下为 %LOCALAPPDATA%\story-studio，macOS/Linux 为 ~/.local/share/story-studio）自动按需配置：

• Python 3.11（通过 uv 自动管理独立虚拟环境，安装 websockets==15.0.1、pyJianYingDraft==0.3.1、Pillow、NumPy、pymediainfo 等）
• Node.js 20+ LTS & Coli：用于本地离线语音转字幕（基于 sherpa-onnx），无需调用任何收费云端字幕 API
• FFmpeg & ffprobe：用于音频完整性解码校验与可选的本地视频渲染
• 剪映专业版：Windows 下支持一键检测草稿目录，缺失时可协助通过 WinGet 安装

2. 账号安全与隐私保护边界

• 零私人信息残留：本开源仓库的源码、示例与语料索引均经过脱敏与哈希化处理，不包含任何个人电脑路径、账户信息或密钥。
• 密钥安全存储：豆包语音 API Key 仅从环境变量 DOUBAO_TTS_API_KEY 或系统级安全凭据文件读取（Windows 采用当前用户 DPAPI 加密，macOS/Linux 采用 0600 权限私密文件），绝不写入对话日志、项目 JSON 或 Git 仓库。
• 费用透明可控：Skill 本身完全免费开源。豆包语音合成（TTS）与宿主环境中的 AI 生图工具可能产生对应服务商的 API 费用；Agent 在首次合成或批量生图前均会征求确认，绝不在后台静默发起循环重试扣费。

🙏 致谢 (Acknowledgements)

Story Studio 的诞生离不开以下优秀开源项目与基础设施的支持，特此向相关作者与维护者致敬：

• GuanYixuan / pyJianYingDraft (Apache-2.0)：提供强大的剪映专业版草稿数据结构、轨道、关键帧与工程生成能力。
• MarsWave / Coli & k2-fsa / sherpa-onnx：提供快速、精准的本地离线语音识别 CLI 与底层推理引擎。
• OpenAI / imagegen：提供图像生成工作流协作参考。
• Astral / uv、Node.js、FFmpeg、python-websockets、Pillow、NumPy：提供坚实的跨平台环境管理与多媒体处理底座。
• 火山引擎 / 豆包语音大模型：提供自然流畅的中文语音合成服务支持。

📄 开源许可证与声明

• 代码与技能规范：本项目基于 MIT License 协议开源，欢迎自由使用、二次开发与衍生创作。
• 内容与语料说明：本项目内置的对标文案语料库仅用于叙事结构、开头钩子与写作技法学习研究，不直接作为已核实的历史事实依据；AI 生成的画风参考图与封面样例亦非历史原照。
• 第三方生态：第三方依赖库（如 pyJianYingDraft、Coli、websockets 等）均遵循其各自的开源许可证分发，本仓库不内嵌或重新分发上述外部库源码。