分镜表进去，成片出来。中间那些会翻车的地方，都已经写死在脚本里了。
h3-lan-batch 是一个 AI Agent Skill（工作技能包），把 MiniMax H3 视频生成从"一条条手点"变成"配置一交、盯进度、逐镜核验"的批量流水线。它对接本机 3210 工作台（H3 LAN Studio）——一个把云端 GPU 编排封装成本地 HTTP 接口的局域网服务。
shots 配置 JSON（prompt + 参考图 + 声线锚）
→ 素材上传（对象数组 assetRefs，图片/音频各自独立编号）
→ 批量提交 Ref2VA 任务（幂等键防重，返工自动换键）
→ GPU 售罄（226604）自动重试
→ 出片自动下载 + 抽帧 + 提音频
→ 声线锚基频核验 → 逐镜验收
零第三方 Python 依赖：所有脚本只用标准库，不需要 pip install。
在支持 Skill 的 AI Agent（如 WorkBuddy / Claude Code）中安装后，直接说：
- "用 3210 工作台批量生成这组镜头"
- "把这些分镜提交到 H3 本地部署"
- "GPU 售罄了，自动重试直到出片"
- "出片了，下载下来抽帧核验"
这些全是实战付过学费的，脚本里已经处理：
| 坑 | 表现 | 已处理 |
|---|---|---|
assetRefs 传了字符串数组 |
409「素材不存在」 | 内置对象数组 |
| 把 HTTP 201 当失败 | 重复提交、同一镜扣两次费 | 200/201 都判成功 |
| 音频标签编号 | 400「引用了不存在的 Audio 2」 | 按本镜实际携带自动重编号 |
| 返工用了同一个幂等键 | 静默返回旧任务，你以为重跑了 | take +1 自动换键 |
retry 漏带 body.clientId |
403，误以为是 cookie 问题 | 客户端已带齐双头 |
| GPU 售罄只打印不重试 | 白等数小时 | 识别 226604 自动重试 |
| 售罄与显存不足混为一谈 | 无脑重试永远好不了 | 分开识别，显存不足直接提示改参数 |
| 收工忘了关机 | 实例空转烧钱 | 收尾核对 hostState: stopped |
装完先跑预检，别直接提交。 预检是只读的——不装软件、不写文件、不产生任何费用：
python3 scripts/preflight.py --write-config # 生成 ~/.h3-lan-batch/config.json（只需一次）
python3 scripts/preflight.py # 四层体检
python3 scripts/preflight.py --json # 机器可读非交互环境（脚本 / CI / AI 代理）一行配好，不会卡在交互提示上：
python3 scripts/preflight.py --write-config --client-id my-laptop-001它检查四层：运行时（Python / 标准库）、媒体工具链（ffmpeg / ffprobe）、配置（clientId）、工作台连通性。 工作台不可达时它会继续往下钻，定位到底卡在哪一层（云凭证 / GPU 实例 / h3-cloud CLI / 3210 服务），并单独列出「需要你做的事」。
只有一个，而且它不是密钥：
| 项 | 环境变量 | 何时必需 | 从哪里拿 |
|---|---|---|---|
clientId |
H3_LAN_CLIENT_ID |
总是 | 自定义一个稳定标识（如 my-laptop-001）。工作台用它认身份，retry 权限绑定它，定了别改 |
工作台地址 baseUrl |
H3_LAN_BASE |
一般不用 | 默认 http://127.0.0.1:3210 |
ffmpeg / ffprobe 路径 |
H3_FFMPEG / H3_FFPROBE |
不在 PATH 时 | which ffmpeg |
云端 GPU 的 API Key 不经过本 skill。 它由优云智算官方 CLI 的隐藏输入录入本机 profile，skill 全程不读取、不回显、不入库。
取值优先级：命令行参数 > --config > 环境变量 > ~/.h3-lan-batch/config.json > 内置默认。模板见 config.example.json。
本 skill 在最上层。下面三层需要一次性配好，逐层验证：
第 3 层 本 skill（h3-lan-batch） ← 批量提交 / 监控 / 核验
第 2 层 H3 LAN Studio（本机 :3210） ← 队列 / 素材 / 任务 / 产物
第 1 层 h3-cloud CLI（编排器） ← 启停 GPU / 提交 / 下载 / 关机
第 0 层 优云智算账号 + API Key ← 云端 GPU
逐层安装步骤、依赖版本、GPU 规格选型、排障对照表 → references/setup.md
联调建议先用 dry-run（H3_DRY_RUN=1）跑通全链路，零花费验证队列、上传、产物预览与自动关机，再切真实模式。
SKILL.md 技能主文档（预检 + 五步流程 + 契约 + 成本纪律）
README.md 本文件
config.example.json 运行配置模板（复制到 ~/.h3-lan-batch/config.json）
.gitignore 预置配置与生成物忽略规则
scripts/
├── preflight.py 安装预检：四层体检 + --write-config（只读、零费用）
├── h3_config.py 配置解析（命令行 > --config > 环境变量 > 用户配置 > 默认）
├── h3_client.py API 客户端：health / runtime / 素材 / 提交 / 重试 / 下载
├── submit_shots.py 批量提交：素材上传、音频标签重编号、幂等、售罄自愈、--dry-run
├── watch_jobs.py 监控出片：售罄自动重试、下载、抽帧、提音频、成本核对
└── pitch_check.py 声线锚基频核验（纯标准库自相关 F0）
references/
├── setup.md 全新机器配置指南（四层链路 + 云端 GPU + 排障表）
├── api-contract.md API 契约与 11 条踩坑录
└── verification.md 出片核验清单 + 症状→提示词改法速查
examples/
└── shots.example.json shots 配置示例（双人/单人/无
6E51
频三种情形）
# 0. 预检并生成配置
python3 scripts/preflight.py --write-config
python3 scripts/preflight.py
# 1. 照 examples/shots.example.json 写自己的 shots.json
# 2. 零费用校验（检查素材与配置，不提交）
python3 scripts/submit_shots.py --config my-shots.json --dry-run
# 3. 提交
python3 scripts/submit_shots.py --config my-shots.json --out submitted_jobs.json
# 4. 监控到出片（售罄自动重试；出片自动下载+抽帧+提音频）
python3 scripts/watch_jobs.py --map submitted_jobs.json --outdir out
# 5. 声线核验
python3 scripts/pitch_check.py out/s01_audio.wav --anchor 296 --role 小满
python3 scripts/pitch_check.py out/s02_audio.wav --fmin 70 --fmax 400 --anchor 101 --role 王阳明# 只提交部分镜头 / 单轮检查（便于外部调度）
python3 scripts/submit_shots.py --config my-shots.json --only s01,s03
python3 scripts/watch_jobs.py --map submitted_jobs.json --outdir out --once- 提示词写法：h3-prompt-writing（Ref2VA 六段式、参考图与声线锚声明规范）
- 本 skill 只负责「提交 → 监控 → 核验」，不含提示词工程