Imported from zhengxn1/readflow-studio (
AGENTS.md). Install upstream withnpx skills add zhengxn1/readflow-studio. Copyright stays with the author.
ReadFlow Studio Agent Guide
ReadFlow Studio 的唯一默认目标是：使用 Obsidian 阅读资料、用户确认的正文 MP3 和 SRT，生成可继续修改的剪映草稿。旧版 Whisper、ASR、HyperFrames 直接渲染文件只在本机保留，不属于公开仓库，也不得自动选择。
启动
- 用
git rev-parse --show-toplevel定位当前仓库，不硬编码旧目录名。 - 首次使用运行
npm run init。主流程只强制要求 Node.js 22+、FFmpeg 和 FFprobe；生成剪映草稿还需要uv与 CapCut Mate。 - 本机路径使用
.readflow.local.json。旧.book-video.local.json可自动兼容迁移，但新文档和新输出不得继续使用旧名称。 - 不要求 Whisper 模型，不自动安装 Whisper，不为主流程运行 ASR。
- 私密路径、用户书籍、音频、字幕、生成图片和每期输出不得提交。
制作关卡
- 选书并核对书名、作者和版本；优先读取 Obsidian 微信读书笔记、划线和个人笔记。
- 生成一版可直接配音的文案并等待用户确认。文案未确认，不生成分镜图片和剪映草稿。
- 用户提供正文 MP3 和中文 SRT；系统可根据中文生成逐条英文 SRT。
- 运行
workflow:prepare，生成素材清单、字幕偏移、分镜表和图片提示词。 storyboard.md是画面和剪辑的唯一时间真源。用户确认分镜后才生成或放置图片。- 图片齐全后先运行
workflow:draft -- --dry-run，再生成并安装正式草稿。 - 新草稿必须使用新名称；不得覆盖用户已有剪映草稿。
如果用户明确要求全自动完成，本期可以跳过分镜确认，但仍必须生成分镜表并完成QA。
文案规则
- 短视频开头先给价值和适用人群，迅速说明这本书能解决什么问题。
- 不写生硬说教、空泛道理、机械排比和高高在上的指令。
- 行动必须具体可执行，情绪必须通过空间、动作、声音、光线和身体感受展开。
- 书籍是情绪与观点的支点，不照搬长段划线、整篇书评或受版权保护的正文。
- 第一行是书名，正文 MP3 和中文 SRT 第一条也必须朗读并显示书名。
字幕规则
- 用户的中文 SRT 是唯一时间真源，时间从0开始。
- 所有正文字幕和正文音频统一增加“封面出现时间”的偏移，不增加到完整片头结束时间。
- 第一条中文字幕必须与目标书名一致；不一致时停止并要求修正，不能猜测切换点。
- 英文字幕必须与中文逐条对应；英文文本沿用中文的开始和结束时间。
- 中文和英文使用独立轨道。英文默认字号5，置于中文下方并保留清晰间距。
- 字幕不得早于对应语音；至少检查开头、中段和结尾。
分镜和配图规则
- 一分镜一张图，不是一句话一张图；每镜原则上覆盖5～10条正文字幕。
- 分镜数量由文案和字幕数量决定，不固定为7张。
- 使用
generated/image-prompts.json和storyboard.md记录视觉风格、画面方案、素材状态和修改意见。 - 同一期尽量至少使用4种视觉风格；场景在地点、时间、主体和构图上必须明显不同。
- 禁止真人近景和清晰五官。人物只能是远景、背影或剪影，面积不超过画面10%。
- 至少2镜为纯景物或象征物；内容足够时至少2镜允许极小人物。
- 禁止文字卡片、水印、机甲、战争、血腥和无意义的夸张史诗构图。
- 图片必须按目标画幅生成并保持宽高比，禁止非等比拉伸。
固定时间线
今天我们要分享的是.mov从0秒开始，与片头语音同步；不显示片头字幕，不播放机械音效。- MOV结束后开始快闪素材，同时播放机械音效。
- 快闪结束后出现全画幅书封，以“水滴遮罩”入场并播放完整水滴音效；正文 MP3 和书名字幕同时开始。
- 书名朗读结束后的第一句正文开始时，切换正文分镜图；缩小书封以“点开”动画进入，同时播放
正文开头音效.mp3。 - 书名和作者从书名朗读结束后持续到视频结束。
- BGM从0秒开始，固定音效从各自事件点开始。替换同名音效后，新草稿必须读取新文件并复制到草稿资产目录。
画幅和排版
- 默认
3:4（720×960），另支持9:16（1080×1920）和4:3（960×720）。 - 字体、字号、缩放和位置在
templates/jianying-draft/layouts.json管理。 - 书名、作者、中英文字幕按画布高度比例定位，切换画幅必须重新计算，不得复用固定像素位置。
- 当前纵向锚点：书名约49%、作者约36%、中文约-38%、英文约-50%。
- 任何画幅下都要检查标题与正文、中文与英文没有拥挤或重叠。
封面和素材
- 封面优先读取 Obsidian 笔记的
cover字段；找不到时允许用户或 Agent 提供已确认的本地封面文件。 - 全画幅封面必须生成目标视频比例的适配图，原封面本体保持比例，空余区域可用同封面柔化背景补齐；正文小封面使用原始封面并保持比例。
- 固定素材包括片头 MOV、片头语音、快闪素材、机械音效、水滴音效、正文开头音效和 BGM。
- 素材路径必须复制并重写到安装草稿自己的
assets/，避免剪映显示“暂无访问权限”。
剪映草稿
- 草稿保持视频、图片、正文旁白、BGM、片头语音、三类音效、中英文字幕、书名、作者、昵称和来源说明为独立可编辑轨道。
- 未提供剪映草稿库路径时必须主动向用户索要，禁止猜测或扫描私人目录。
- 安装前检查目标草稿名是否存在；存在时生成新名称，不覆盖旧草稿。
- 建议用户完全退出并重新打开剪映，以刷新新草稿和素材权限缓存。
QA
运行 npm run check，并对正式草稿确认：
- 画布比例、总时长和音频时长正确。
- 片头无字幕，机械、水滴和正文开头音效事件正确。
- 书名有正文人声，不被机械音效替代。
- 中英文字幕条数一致、时间一致、位置有间距。
- 每镜5～10条字幕，一镜一图，图片不拉伸。
- 全屏封面“水滴遮罩”和小封面“点开”动画存在。
- 书名和作者从书名结束持续到视频结束。
- 已安装草稿不再引用项目工作目录或
.tools中的临时素材路径。
项目变更完成后更新 .ai/project.md，默认使用中文记录。
