短剧导演实战百宝箱

付费调用契约（Pay Skill）

本技能为 Pay Skill，按次计费，单价 2.68 元/次。每次被调用时，必须先执行付费闸口校验：

python scripts/payment_gate.py

• 若脚本返回 402 Payment-Needed，说明当前用户尚未付费。此时立即停止后续任何操作，向用户说明：「本技能为付费技能，请先完成支付，支付成功后平台会自动重试本次调用。」
• 若平台已携带 Payment-Proof 注入环境变量（X_PAYMENT_PROOF / PAYMENT_PROOF），脚本会校验并放行，然后继续执行主流程。
• 付费状态会缓存在 .pay_cache/state.json，同一用户 24h 内无需重复付费。

重要：SkillHub 上架表单里填写的「单次调用价格」必须是 2.68 元/次，与计费设置保持一致；否则用户支付会失败。

现金流调用套路：

用户调用 → 平台 probe → 未付费：脚本返回 402 Payment-Needed → 支付宝 pay → complete → 平台注入 Payment-Proof → 脚本 ack 验签 → 放行主流程

本契约由 SkillHUB 平台调度层解析；脚本本地只处理 402 / 验签 / 持久化三环节，付费本体交给支付宝。

全流程 SOP（按顺序执行）

第 -1 步：付费闸口（不可跳过）

任何实际产出之前，先运行 scripts/payment_gate.py 进行付费校验。未付费则停止并提示用户支付，已付费或携带有效 Payment-Proof 再进入第 0 步。

从「剧本改稿」到「AI 分镜 PDF + 顺场表」的全流程可复用工具链，源自真实短剧项目全流程实战验证（项目信息已脱敏，示例均为虚构通用数据）。

何时用

• 剧本收到外部修改意见（AI 建议 / 演员语音），要落地成新版本
• 拿到新剧本要先做整体质量诊断（剧本医生评估），定位问题再决定怎么改
• 演员对词困难，需要好莱坞标准格式剧本
• 剧本定了，要拆分镜（分镜表 xlsx + AI 生图分镜 PDF）
• 单日拍摄要排顺场表（妆造连续性 / 转场 / 黄金时刻）
• 拍摄前要去实景堪景（28 字段记录单 + 拍照动线 SOP）
• 新项目要建人物小传档案，或剧本医生诊断出人物问题需要重做人物

导演审美红线（动手前必读，详见 references/taste-and-judgment.md）

这些是用户用返工换来的判断标准，不是流程步骤：

0. 剧本是灵魂（最高纲领）：剧本剧本，一剧之本。内容质量不过关，流程玩得再溜做出来的也是垃圾——先改内容后谈流程，分镜/顺场表/排版全是剧本的下游
1. 分镜 = 导演一眼看懂。抽象示意图（火柴人/剪影）会被打回，直接 AI 逐镜生图
2. 批量生成先样张后批量（3 张验风格，用户拍板再跑全部），成本先报总预算
3. 台词量平衡 = 结构健康度：主要角色连续两集没台词，先怀疑结构问题，不要辩解
4. 排版为第一读者服务：剧本给演员对词（cue/台词缩进栏分离），不是给自己看；"看着累"就是打回理由
5. 外部意见逐条核对（AI 建议/演员语音逐条标 ✓/✗），不是整体参考着改
6. 发现 BUG 停下游先修上游：逻辑自洽确认后才继续产出下游文档
7. 归档只留头尾（原始版+最终版），过程文件删了不可惜；用户说删了就是删了，不要自我怀疑

全流程 SOP（按顺序执行）

第 0 步：读判断手册（强制，不可跳过）

动手做任何事之前，先完整阅读 references/taste-and-judgment.md（内容审美与判断手册，24+ 条用户实战纠偏记录）。本文件顶部 8 条红线只是摘要，手册才是全量——跳过它 = 丢掉这个技能一半的价值。

第 1 步：剧本改稿落地

改前先诊断：新剧本/大改前先跑剧本医生评估（框架见 references/script-doctor.md：5 大类 23 条四级评分 + 100 分总评 + 七维修改意见），问题清单经用户确认后再动笔——打分只管定位，改稿顺序按诊断走（结构低分先修结构，台词问题后修）。
人物类低分项（动机矛盾/工具人/降智）→ 用 references/character-sheet.md（59 项三维人物问卷：体貌/心理/社会）重做人物小传，「过去的决定性时刻」一项就是主线动机唯一性的答案来源。

原则：只加台词、微调措辞，不动机位动线（机位动线牵一发动全身）。
外部意见逐条核对现有剧本：已满足 → 标✓；未满足 → 嵌入原有镜头加台词。
改完用双向核验：正向（剧本每句台词→分镜表能找到）+ 反向（分镜表台词列→剧本原文能找到）。

第 2 步：好莱坞格式剧本 docx

排版规范（完整规格书见 references/hollywood-format.md：六元素判定规则 + 美标几何对照 + 退化模式清单，参数为用户认可定稿的实测反推）：六类元素靠缩进栏区分，绝不整页居中对白——场景标题 12pt 加粗顶格；动作行顶格；人物名 cue 左缩进 150pt（before8/after2 与台词粘块）；台词 left=70pt / right=60pt 窄栏；括号情绪注并入 cue 行；转场右对齐；行距 1.3（line=312）；正文黑体五号，US Letter 纸型（612×792pt）。

格式验收（每轮改版式后必跑，PASS 才交付）：scripts/verify_format.py——对排版后的 PDF 导出件逐行校验缩进桶（顶格/70/150 ±3pt）与转场右对齐，未匹配行逐一报告。格式会退化（实战教训），每次改完重新全量验收，不能只查改动处。

docx 工具链（走 tencent-local-office-edit 技能的 edsdk.py）：

open_file → 拿 file_id
create_doc → 新文档 file_id
doc_insert_markdown file_id=xxx idx=0 markdown=file://<md路径>   # file:// 方式传长文，避免命令行中文/转义问题
doc_resolve_document_structure mode=full limit=0 → 段落 start_index/end_index（GCP 坐标，半开区间）
doc_modify_paragraph --json-file <参数文件>   # {file_id, jc, ranges:[{begin,end}]}；indent/spacing 与 jc 互斥不能同包，分多次调用
doc_update_text_property --json-file <参数文件>  # {file_id, bold, font_size, ranges}
doc_delete_paragraph file_id=xxx idx=<GCP>    # 删整段放最后执行（前面的样式操作不改坐标）
save_file file_id=xxx file_path=<输出路径>

坑点：
- 结构 JSON 节点字段是 text_preview / start_index / end_index，有的节点无 text_preview 要做空值保护
- 分类段落时 cue 的下一行（台词）要标记已消费，否则会被动作行分支重复套段距
- 批量对齐参数 JSON 别漏 jc 属性本身
- doc_to_image 云端渲染对中文文件名报 file not found，复制成 ASCII 名再用；"服务繁忙"重试一次不行就放弃（结构核验 + 预览面板兜底）
- 文件被预览面板锁定无法覆盖 → 另存新文件名
- bash -c 里 python 字符串的中文反引号/反斜杠会被 shell 吃掉 → 写临时 .py 文件跑，或用 Edit 工具改文件

第 3 步：拆分镜 → shots.json 中间数据

shots.json 是全流程质量枢纽：分镜表/AI 生图/AI 板/顺场表四个下游全吃它（结构见 references/shots-schema.md）。AI 生图的 prompt 唯一来源 = shots.json，禁止跳过拆镜、直接从剧本文本生图——AI 自己从文学文本猜镜头，会全画成中景、没有切分逻辑、丢失导演意图（本技能红线）。

按剧本颗粒度分两档拆镜：
- 剧本自带分镜/动作提示（高颗粒度输入）：拆镜 = 结构化提取 + 景别/运镜设计，逐镜画面直接从剧本动作描述提炼
- 纯文学剧本（只有叙述和对白）：拆镜前先做镜头化转译——逐场把叙述段拆成 beats，逐 beat 定景别/运镜/画面构成/台词归属；转译结果（分镜设计）先给导演过目确认，认可后再固化进 shots.json——相当于把样张确认提前到数据层，避免批量生图后才发现切分不合意图

人物视觉锚定：剧本自带服装提示 → 直接写死进固定风格前缀；外观素材的规范采集源 = references/character-sheet.md 体貌层面（服装风格/头发/体格/首饰/伤疤五项组合）；纯文学剧本缺视觉设定 → 先出 2-3 张人物设定图给导演确认，把确认后的外观描述写死进前缀。人物一致性靠前缀锚定，不靠 AI 自觉。

先从分镜模板 xlsx 提取表头/合并单元格/样式（openpyxl 读模板），1:1 复刻格式生成。
自校验：镜号连续无重、时长合计=各幕预估和、集切点镜号与剧本切黑点一一对应。

第 4 步：AI 手绘分镜生图（用户认可的最优方案）

程序绘制（火柴人/简笔剪影）会被导演否——直接 AI 逐镜生图，质感要求"手绘漫画电影分镜"。

流程：
1. 先出 3 张样张验风格（特写/中景/远景各一，景别控制是最大风险），用户拍板再批量
2. prompt 模板见 references/shots-schema.md：固定风格前缀 + 第0NN镜： 前缀 + 逐镜景别/人物/光影/情绪——逐镜要素从 shots.json 取，不从剧本原文现编
3. 尺寸 1536x1024，quality=medium（约 6 积分/张，按镜数先向用户报总预算再开跑）
4. 生成完统一改名 shot_NN.png，校验张数零缺失
5. 后期镜（片头/片名/片尾）不生图，组装时做黑底说明格

第 5 步：组装 AI 分镜 PDF

用 scripts/assemble_ai_board.py（改顶部 CONFIG 区：图片目录/shots.json/输出路径/项目名/总镜数/起始镜号/后期镜说明）。
自动完成：中心裁 1.85:1 画幅（人脸偏上 y 偏移 35%）、运镜记号叠加（蓝=推/跟/环绕/正反打/定格/慢镜/特效/主观记号，红=快切）、集切点标注、Cadrage 版式（Letter 300dpi、每页 8 格、框下注释两行、页眉场次范围）。
依赖：pillow + pymupdf（pip install --target D:/WorkBuddy/_py）。

第 6 步：顺场表（单日拍摄）

用 scripts/build_schedule.py（数据段 BLOCKS/CHECK/SCENE_MAP + 末尾断言值（总镜数/时长/切点块）需按新项目重填，逻辑通用）。

核心原则（实战踩坑得出）：
- 妆造单向流动：每个妆造状态在时间轴上必须是连续区间，切换只发生在转场/餐休窗口。伤妆只做 1 次卸 1 次——否则穿帮或重做 2 次妆救不回来（实战项目 v1 顺场表就死在这）
- "受伤前剧情"绝不能排进带伤时段；翌日剧情（伤愈）统一不戴伤，才能和前一天的戏共享妆造
- 转场时间的可靠来源 = 勘景数据（references/scouting.md：路况/器材运输/方位朝向/亮化时段）；未堪景才退化为保守 30min 独立预留 + 机动兜底块
- 日落黄金时刻查当地日落时间，倒排换装窗口（换装紧时用替身远景顶）
- 特效镜头多拍景别（全景/手部/特写/空镜）——片头闪前靠反接特效素材，拍少了后期没米下锅
- 自校验：全镜号覆盖无重复、切点镜落在对应块、妆造逐块判定 ✓

目录结构

scripts/assemble_ai_board.py   # AI 分镜图 → Cadrage 版式 PDF（CONFIG 区参数化）
scripts/build_schedule.py      # 单日顺场表 + 妆造连续性核对 + 场次映射（数据段需重填）
scripts/verify_format.py       # 好莱坞格式自动验收器（PDF 逐行缩进桶校验，PASS 才交付）
references/hollywood-format.md # 好莱坞格式规格书（定稿实测参数 + 美标对照 + 退化模式）
references/script-doctor.md    # 剧本医生评估框架（改前诊断：23 条四级评分 + 七维修改意见）
references/character-sheet.md  # 人物设计表（59 项三维问卷：剧本医生修复脚手架 + AI 生图锚定素材单）
references/scouting.md         # 勘景工具包（28 字段记录单 + 前/中/后 SOP，顺场表转场时间的上游数据源）
references/shots-schema.md     # shots.json 结构 + AI 生图 prompt 模板 + docx 排版参数速查
references/taste-and-judgment.md  # 内容审美与判断手册（用户实战纠偏记录，动手前必读）
LICENSE                         # 版权与使用许可声明（新菁年影视 · 分层授权）
README.md                       # 英文说明（GitHub 发布用）
README_zh-CN.md                 # 中文说明（SkillHub 发布用）

版权与许可

本技能包版权归 南京新菁年影视科技有限责任公司（新菁年影视） 所有，分层授权、非开源：

• 文档 / 知识内容（SKILL.md、references/*）：CC BY-NC-ND 4.0——署名可学习参考，禁止商用、禁止改编后传播
• 代码（scripts/）：专有授权，禁止直接代码级复用*——复制/修改/再分发/嵌入其他项目均需版权人书面授权

完整条款见根目录 LICENSE。

环境依赖

• python: <用户目录>/.workbuddy/binaries/python/versions/<版本号>/python.exe（本机会话按 binaries 实际路径）
• pillow / pymupdf / openpyxl 装在 D:/WorkBuddy/_py（sys.path.insert(0, r'D:/WorkBuddy/_py')；依赖目录按本机实际调整）
• 中文字体：C:/Windows/Fonts/msyh.ttc / msyhbd.ttc（Windows 系统自带）
• docx 操作走 tencent-local-office-edit 技能（edsdk.py）