konlu/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 内置了两个完整的专业级写作子模块，提炼自数百篇视频号与短视频平台的高赞爆款逐字稿：

| 内置写作风格 | 适用赛道与特点 | 内置语料与 DNA 武器库 | | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 📜 历史叙事风
historical-narrative | 把历史中值得追问的一件事讲透
• 开头抛出具体历史反常或核心问题
• 正文以人物行动、制度条件与连锁后果推进
• 结尾严密兑现开头悬念，拒绝空泛升华 | • 57 篇 头部爆款历史叙事逐字稿与结构拆解
• 9 类黄金开头钩子机制（逐篇前几秒文字窗口分析）
• 内置《选题库》《史实与素材核验》《字数与查重工具》 | | 👩 人物故事风
yuling-characterstory | 真实历史人物与传奇女性连载/单集
• 经典节奏：钩子先行 → 巅峰数字 → 可谁也没想到 → 磨难场景 → 金句收尾
• 极具感染力的情感锚点（「您说……怎么会……」与精确数字节点）
• 支持单集深度人物传记或 2~3 集连续剧式排期 | • 300+ 篇 头部爆款逐字稿深度蒸馏全套人物写作 DNA
• 覆盖民国名媛、巾帼英雄、时代先驱、传奇母亲等多赛道高赞对标库
• A/B/C/D/E 五大类开头钩子模板 + 选题策略 DNA + 情绪升华与金句模板 |

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

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

---

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

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

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

| 画风名称 (style_id) | 视觉特征与适用氛围 | 内置参考图与封面策略 | | :--------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | | 🖌️ 厚涂历史漫画风
historical-comic | 强烈叙事张力与雕塑块面感
可见厚涂破碎笔触、赭金与焦褐色调、冷暖对比强烈、极具戏剧张力与电影镜头感 | • 内置 6 张 正文风格基准图 (HC01~HC06)
• 默认附带 3:4 竖版 + 4:3 横版 两张厚涂金箔榜书标题封面 | | 📷 黑白纪实叙事风
monochrome-narrative | 克制、厚重的近现代人物传记感
纯正黑白灰阶、胶片摄影质感、细腻的面部年龄纹理与时代光影，情绪深沉克制 | • 内置 6 张 正文黑白摄影基准图 (MN01~MN06)
• 默认纯享无字正文图；可选配专属「黑白人物金红书法封面」 | | 🏞️ 历史写实风
historical-realism | 自然沉稳的传统历史解说质感
自然人物比例与真实光照、细腻柔和的写实绘画质感、克制的冷暖色彩关系 | • 内置完整时代考据与细节密度样例
• 默认附带 3:4 竖版 + 4:3 横版 两张同画风标题封面 |

🔍 为什么它生成的配图不违和、不穿帮？ 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"

bash

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 发送：

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

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

第三步：开始你的创作！
你可以直接用大白话告诉 Agent 你想做什么。下面看看最常用的几种姿势 👇
---
🎛️ 灵活的工作流开关
Story Studio 内部通过 写作（write）、配图（illustrate）、剪映草稿（draft） 三个主开关控制边界，配音与转录作为无缝衔接步骤按需触发。
你不需要写任何配置文件，直接用自然语言指挥，或者显式声明开关状态：
| 你的使用场景                               | 写作  | 配图  | 剪映草稿 | 说明                                             |
| :----------------------------------------- | :---: | :---: | :------: | :----------------------------------------------- |
| 只找选题 / 写口播稿 / 改开头钩子       | ✅ 开  | ❌ 关  |   ❌ 关   | 纯文本创作，绝不乱调收费生图或配音接口           |
| 文稿已写好，拆解分镜并生成配图         | ❌ 关  | ✅ 开  |   ❌ 关   | 支持只出分镜提示词，或直接调用生图工具出图       |
| 文件夹里已有配音和图片，直接排剪映草稿 | ❌ 关  | ❌ 关  |   ✅ 开   | 自动用 Coli 跑时间轴对齐、加推拉运镜并写入剪映   |
| 从 0 到 1 全流程一条龙制作             | ✅ 开  | ✅ 开  |   ✅ 开   | 选题写稿 → 确认定稿 → 配音转录 → 生图 → 剪映草稿 |
---
💬 常用提示词示例
场景 1：全流程一条龙制作（从选题文案到剪映草稿）

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

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

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

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

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

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

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

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

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

---
📂 项目目录结构与交付产物
仓库结构一览

text 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 源码：

| 阶段 | 交付文件与产物 | | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ✍️ 写作阶段 | 纯口播正文稿、标题备选、事实核查表与时间线记录、参考来源说明 | | 🎙️ 配音与转录 | narration.mp3（最终配音）、配音参数与哈希校验记录、Coli 本地识别 .srt 字幕与核对文件 | | 🎨 分镜与配图 | STORYBOARD.md & STORYBOARD.json（含时间戳、原文锚点、逐镜独立提示词）、按镜号命名的正文图片、COVER_3x4.png / COVER_4x3.png 封面图、（可选）片头首尾帧与视频提示词 | | 🎞️ 剪映草稿 | 直接写入剪映专业版草稿目录的可编辑工程、plan.json 时间轴与运镜计划、semantic_alignment.json 语义核验记录、（可选）final.mp4 本地渲染成片 |

---

📦 依赖与隐私说明

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：提供坚实的跨平台环境管理与多媒体处理底座。
• 火山引擎 / 豆包语音大模型：提供自然流畅的中文语音合成服务支持。

---

☕ 赞赏支持 (Sponsor)

如果你觉得 Story Studio 对你的短视频创作、自媒体运营或 AI Agent 工作流有所帮助，欢迎赞赏支持！

特别声明：本项目所有的赞赏将会全部捐献给山区儿童以及重病患者，用于公益助学与医疗救助。感谢每一位支持者的善意与温度！

---

📬 联系方式 (Contact)

欢迎自媒体创作者、独立开发者、AI 爱好者一起交流探索新玩法：

• 微信咨询：添加个人微信：muyu1888（请备注：Story Studio 或 自媒体创作）
• 电子邮箱：[email protected]
• 问题反馈：欢迎在 GitHub Issues 提交 Bug 反馈与新功能建议

---

📄 开源许可证与声明

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