QuickAI 漫剧分镜
用户提供一章小说。你负责读懂章节、改编成可拍的桥段、拆出人物和场景资产、设计分镜，写进计划文件。脚本负责校验计划、生成分镜网页和分镜脚本，并调用 QuickAI 出图：每个人物一张完整角色设定板，每个场景一张空镜，再按镜头顺序每 9 个镜头出一张 4:3 九宫格故事板。
出图规格是固定的，不需要也不能改：
- 人物设定图：完整角色设定板（半身主视觉、人物资料、配色、三视图、10 格表情、五官和服饰细节），3D 半写实国漫人物，画幅默认 16:9。
- 故事板：4:3 九宫格，3 行 × 3 列，每格也是 4:3。
本 Skill 只做漫剧（动画、漫画画风），不做真人短剧。分析、改编和分镜预览都不花积分，只有出图消耗积分。
下面命令中的路径都相对本 Skill 目录（本文件所在目录）。macOS / Linux 用 python3，Windows 用 python。需要 Python 3.8 及以上，无第三方依赖。
1. 收集信息
必需：
- 小说章节原文，一次一章，100–60000 字。用户给了多章时，先确认从哪一章开始，逐章处理。
可选，用户没说就用默认值：
- 场景和故事板的画风：默认
guoman-3d（3D 国漫），与人物设定图一致。运行python3 scripts/novel_storyboard.py catalog可查看画风、人物预设和词表；换成其他画风会和人物画风不一致，脚本会提醒。 - 成片画幅：默认
9:16竖屏，适合抖音、快手等竖屏漫剧；横屏用16:9。它写进分镜表和导出文件，供后续做视频，不影响故事板。 - 目标镜头数：默认 18 个（两张满格故事板），常用 9–36 个。取 9 的倍数时每张故事板都是满格，否则最后一张的剩余格子留白。
- 是否保留原文台词：默认尽量保留。
- 已有的人物或场景设定图（例如前几章生成的）：填进
asset_image直接复用，不再出图。
只处理用户自己写的或有权改编的作品。
2. 改编和拆解
先读 references/adaptation-guide.md；写人物前再读 references/character-sheet-template.md 的第一个示例。然后依次完成：
- 章节理解：主要人物、核心冲突、危机、爽点、转折和结尾悬念，自己记下即可。
- 拆桥段（
beats）：每段有明确冲突和可视化动作，台词短、狠、推动剧情。 - 人物资产（
characters）：有台词或反复出镜的人物才建条目。外貌和服装按模板的顺序和颗粒度写，脚本会按模板组装人物设定图的提示词。 - 场景资产（
locations）：同一地点合并成一个条目。 - 分镜（
scenes）：一个条目就是一个镜头，写清景别、机位、运镜、画面、台词和时长。
把 templates/storyboard.example.json 复制到用户的工作目录（不要写进本 Skill 目录），按上面的结果改写。
| 字段 | 说明 |
|---|---|
project.title / source |
作品或章节名；来源说明 |
project.genre |
类型，取 catalog 列出的 id，如 suspense、fantasy |
project.style / style_note |
场景和故事板的画风 id，默认 guoman-3d；画风补充（质感、色调）。都不用于人物设定图 |
project.visual_note |
整体色调、光线和氛围约束，只用于故事板；不写竖屏、横屏之类的要求 |
project.logline / synopsis / story_background |
一句话卖点、剧情梗概、故事背景 |
project.aspect_ratio |
成片画幅，默认 9:16，不影响故事板 |
project.target_duration_minutes |
可选，目标时长，偏差大时脚本会提醒 |
project.style_images |
可选，场景和故事板的画风参考图，最多 2 张；人物设定图不用 |
defaults |
quality（默认 low）、resolution（默认 1K）、model、board_references（默认 true）、sheet_size（人物设定图画幅，默认 16:9） |
beats[] |
桥段：title、scene_heading、action、dialogue、emotion、conflict |
characters[] |
name、role_type（主角/配角/反派/路人）、identity（身份）、age、appearance、costume、palette（角色配色）、board_background（设定板背景与边框）、details（细节方向）、personality；可选 preset、prompt、rendering、reference_images、asset_image |
locations[] |
name、description、atmosphere；可选 prompt、reference_images、asset_image |
scenes[] |
镜头：shot_size、camera_angle、camera_move、location_name、character_names、description、dialogue、sound、duration、transition；可选 beat、title、scene_type、video_prompt |
scenes[].character_names和台词的说话人必须与characters[].name完全一致，location_name必须与locations[].name完全一致。旁白写"旁白"，内心独白写"林烨（OS）"。description只写画面里看得见的内容，40–120 字；台词写进dialogue。- 镜号按
scenes的顺序自动编排。
3. 免费预览，请用户审稿
python3 scripts/novel_storyboard.py render --plan <计划文件>
不调用接口、不扣费。在计划文件旁生成 <标题>-storyboard/ 目录：
index.html：分镜网页，包含设定、人物、场景、故事板、分镜表和剧本。storyboard.md：Markdown 分镜脚本。shots.csv：分镜表，可用 Excel 打开。drama-project.json：按 QuickAI 短剧中心字段整理的项目文件，供以后导入。
把一句话卖点、人物和场景列表、镜头数和总时长告诉用户，请用户看 index.html 或 storyboard.md 审稿。用户要修改就改计划文件，再运行 render。输出里的 warnings 要处理或转告用户。
4. 出图前确认
python3 scripts/novel_storyboard.py check
python3 scripts/novel_storyboard.py generate --plan <计划文件> --dry-run
check 报告缺少 AccessKey 时，告诉用户：
- 登录 https://openclaw.aisupermarket.top/?page=access-keys ，创建一个带"图片生成"权限的 AccessKey。
- 任选一种方式配置：把
config.example.json复制为config.json并填入access_key；或设置环境变量QUICKAI_ACCESS_KEY；OpenClaw 用户也可以在openclaw.json的skills.entries.quickai-novel-storyboard.apiKey中填写。
不要在回复、日志或生成的文件中显示 AccessKey。
--dry-run 只校验计划，输出每张图的编号、尺寸、参考图、提示词和预计积分。它会读取平台公开价格，不提交任务、不扣费。编号规则：人物 C1、C2……，场景 L1……，故事板 B1……。
每张图都会单独消耗积分。开始生成前，把张数（人物设定图 N 张、场景空镜 M 张、故事板 K 张）、质量、分辨率和预计积分告诉用户，等用户确认。用户已经明确说"直接生成"时可以跳过确认。
质量默认 low、分辨率默认 1K，最省积分。只有用户明确要更好的画质时，才把 defaults.quality 调到 medium / high 或把分辨率调到 2K，并先说明会多消耗积分。
5. 生成
建议分两步，先确认人物和场景的样子，再出故事板：
python3 scripts/novel_storyboard.py generate --plan <计划文件> --stage assets
python3 scripts/novel_storyboard.py generate --plan <计划文件> --stage boards --resume
也可以一步完成：generate --plan <计划文件>，先出全部设定图，再出故事板。
- 故事板会带上本页出场人物的设定图和场景空镜作参考图，保持人物和场景一致。参考图超过上限时主角优先，其余人物按文字设定。
- 只想先看画风：加
--only C1只出第一个人物，满意后用--resume生成其余，已完成的不会重复生成。 - 修改某个人物或场景：改计划文件后运行
--resume，只重做改动过的设定图和用到它的故事板。 - 单次新生成超过 15 张会被拦下。向用户确认后加
--max-items N。 - 输出目录已有结果时，必须选择一种方式：
--resume只补生成未完成或改动过的图片；--force全部重新生成（会重新扣费）；或用--out换一个目录。 - 默认同时进行 3 个任务，单张最长等待 600 秒。进度输出到 stderr，最终结果 JSON 输出到 stdout。
退出码：0 表示全部完成，2 表示有图片未完成，1 表示配置、计划或参考图上传出错。
后续章节：把已生成的设定图路径填进对应人物和场景的 asset_image，名称和外貌描述保持不变，脚本会直接复用，不再出图。
6. 交付
回复用户时包含：
index.html的路径（用浏览器打开），以及storyboard.md、shots.csv、drama-project.json。- 每张图的编号、名称和状态。失败或跳过的图片说明出错阶段（
submit提交、generate生成、poll查询、download下载）、原因和下一步，如"充值后用--resume继续"。 - 累计消耗的积分（
summary.credits_charged，包含续跑前已完成的图片），返回了余额时一并说明。 - 提醒用户：故事板是分镜预览，单格分辨率不高；画格内容可能与描述有出入，需要时改对应镜头的描述再续跑。
drama-project.json已按短剧中心字段整理。短剧中心目前只能在网页登录后操作，还不能用 AccessKey 直接导入。
规则
- 只做漫剧。画风只用
catalog列出的漫剧画风，描述里不要写"真人、实拍、照片级"之类的要求；脚本发现这类词会给出警告。 - 不编造原文没有的关键人物和情节。为了可拍而做的改编（合并场景、删减心理描写、补动作）可以做，但要保留原作的人物关系和关键转折。
- 暴力、血腥、色情内容改为暗示表现（光影、反应镜头、遮挡），避免出图被内容审核拦下。
- 画面里不要出现文字。台词放在分镜表里，后期配字幕。
- 计划文件和输出目录放在用户的工作目录，不要写进本 Skill 目录。
- 接口细节和错误排查见
references/api.md。
