lanshu-create-ai-presenter-video
制作 AI 主持人视频的 Codex Skill，根据脚本和已获授权的人像组织生成与验证流程，接口不绑定单一供应商。
中文简介经编辑校订 · ai-video / codex / codex-skill / digital-human / video-generation
README / 项目原文
lanshu-create-ai-presenter-video
English | 简体中文
Turn a topic or script into a verified, publish-ready explainer video — presented by a digital human from one authorized portrait, or acted out on screen in one of twelve explainer styles — driven by the coding agent you already use.
lanshu-create-ai-presenter-video is an Agent Skill that takes an AI agent through the full production of an explainer video. On the presenter route that means script, narration, presenter generation, lip-sync, captions and keyword motion graphics, editing, rendering, and quality assurance. On the styled route the narration is performed scene by scene in one of twelve styles (nine visual, three narrative), from a word-timed story to a rendered film. Every stage is gated by evidence on disk, and nothing is delivered until the output passes decode and loudness checks.
Highlights
- Harness-neutral. A standard
SKILL.mdthat loads in Claude Code, Codex, Gemini CLI, Cursor, OpenCode, GitHub Copilot, and other Agent Skills clients. Any agent that can read files and run shell commands can follow it directly. - Provider-neutral. On the presenter route, voice, presenter video, lip-sync, and speech recognition are selected by capability at run time; each job records the provider, model, parameters, and task IDs it actually used. The styled route voices with MiniMax (word timestamps come from the voice engine) or takes narration you voiced or recorded elsewhere.
- Twelve performed explainer styles. Nine visual styles — editorial, tech HUD, notebook, paper pop-up, pop comic, 3D one-take, drafting sheet, chalkboard, and clay town — plus three narrative styles: derivation, casefile, and life-scene sitcom. Each has a reusable kit, starter, and example project.
- Audio-locked timeline. The approved narration is the master clock for presenter motion, captions, cuts, and final duration, which keeps lip-sync and scene boundaries aligned.
- Evidence-gated workflow. Eight production states, from
intaketoverified, computed from artifacts instead of declared by hand. - Cost guardrails. Pilot-first generation, an explicit billing statement before the first paid call, retry ceilings, and task-ID recovery to avoid duplicate charges.
- Verified delivery. Master and share encodes are fully decoded and loudness-checked before any file is published.
Two routes
| Route | The video | You provide | Paid generation | Format |
|---|---|---|---|---|
| Presenter | A digital human presents; captions and keyword graphics support it | Topic or script + authorized portrait | Voice + presenter video | Any; 9:16 by default |
| Styled explainer | No presenter: every narrated phrase is acted out on screen in one of twelve styles (nine visual, three narrative) | Topic or script (or your own recorded narration) | Voice only (none with your own narration) | 16:9 |
The agent infers the route from your request or asks once, with the style gallery. All styles share one contract — word-timed captions, chapter chips, a performed closing line, a one-frame recap. Nine are visual styles that differ in how ideas are acted out: editorial paper, tech HUD, notebook and pen, paper pop-up book, pop comic, 3D one-take, drafting sheet, chalkboard, and a clay town. Below is the same moment of the bundled KV cache explainer in all nine:
Three are narrative styles, where the look comes with a way of telling and the script can draw on its suggested arc: 推演 (derive it on one canvas, formulas and geometry bound by colour), 案卷 (investigate it on an evidence board, from the anomaly to the closed case) and 小剧场 (a life-scene sitcom: a misconception, a bill or a queue that shows the cause, one sentence that maps the analogy to the real term). Below is the same KV cache topic told the three ways:
A new topic becomes a playable draft in any style in a few commands — narration, word timing, captions, chapters,
closing line, recap, and sound are generated; the agent then performs each line's scene. See
explainer/STYLES.md to choose a style and
references/styled-explainer.md for the workflow — including an optional method for
bringing your digital human into a styled film.
What you provide
| Input | Required | Notes |
|---|---|---|
| Topic or finished script | Yes | A topic becomes a 45–75 second script; a supplied script keeps its natural length. |
| Presenter image | Presenter routes | One clear adult presenter, with confirmed rights to use the image. Not needed for the styled explainer. |
| Voice sample | No | Used only with explicit cloning authorization; otherwise a stock voice is selected and recorded. |
| Supporting media | No | Screen recordings, images, B-roll, or brand assets, used where they prove or clarify a spoken point. |
| Delivery preferences | No | Platform, duration, aspect ratio, style, watermark, music, and call to action. |
How it works
Presenter route:
Topic or script + authorized portrait
│
▼
Lock script and full narration ──► narration becomes the master clock
│
▼
Low-cost presenter pilot
│
▼
Presenter generation (split at real pauses when a provider caps duration)
│
▼
Audio-driven edit: captions, keyword graphics, cover, close
│
▼
Technical and visual QA
│
▼
Master, share copy, contact sheet, and delivery report
Styled route:
Topic or script ──► choose a style (menu + galleries, or drafts in the nine visual styles)
│
▼
Script written for the style ──► voice with word timestamps (or your own narration)
│
▼
Draft film from the style's starter: captions, chapters, closing line, recap, sound
│
▼
Storyboard ──► every line performed on screen, on its words
│
▼
QA (check, stillness, cover) ──► render ──► master, share copy, subtitles, delivery report
Each state requires evidence before a job may advance. check_state.py computes the state from the job's artifacts:
| State | Evidence required |
|---|---|
intake |
Job created |
content_locked |
Passing preflight report, script, beat sheet |
audio_locked |
Decodable final narration, ASR report |
visual_plan_locked |
Timeline, storyboard, approved plan |
presenter_generated |
Recorded presenter capability, selected video, visual review |
composition_checked |
Composition report |
rendered |
Decodable render with video and audio |
verified |
Master, share copy, and a delivery report with passing output loudness |
On the styled route, audio_locked also needs a voiced story.json (a --dry draft never counts), and
presenter_generated is reached by the performed film and its visual review instead of a presenter video.
Requirements
- An Agent Skills harness, or any coding agent that can read files and run shell commands.
- Python 3.9+, FFmpeg with
ffprobe, Bash,jq,awk, andsed. - For the presenter route: access to at least one voice synthesis, presenter video generation, and lip-sync capability — a cloud CLI, an API, or a local model — and optionally a deterministic timeline compositor such as HyperFrames for captions, motion graphics, and final rendering.
- For the styled explainer: Node.js (HyperFrames runs with
npx),rsync, Python withnumpy(sound bed; pointPYTHONat it), and a MiniMax API key (MINIMAX_API_KEY) for the voice and its word timestamps — or your own recorded narration.
Installation
The repository directory is the skill. Clone it into your harness's skills directory and keep the folder name lanshu-create-ai-presenter-video, which the Agent Skills specification requires to match the skill name.
| Harness | Skills directory | Explicit invocation |
|---|---|---|
| Claude Code | ~/.claude/skills/ or project-level .claude/skills/ |
/lanshu-create-ai-presenter-video |
| Codex | ~/.codex/skills/ |
$lanshu-create-ai-presenter-video |
| Other Agent Skills clients | See the client's documentation, linked from the client list | Client-specific |
For example, with Claude Code:
git clone https://github.com/cclank/lanshu-create-ai-presenter-video.git \
~/.claude/skills/lanshu-create-ai-presenter-video
Run git pull in the installed directory to update. If you use several harnesses, clone once into each skills directory.
Tagged versions and a ready-to-extract skill ZIP are available in Releases. See CHANGELOG.md for version history.
Agents without Agent Skills support. Clone the repository anywhere, then start the session with:
Read /path/to/lanshu-create-ai-presenter-video/SKILL.md and follow its workflow exactly.
Quick start
Most harnesses select the skill automatically from its description, so you can describe the video you want:
Turn this script and portrait into a 30-second 16:9 presenter video with live captions.
For a styled explainer you don't need to know the styles yet — ask, and the agent shows the twelve with pictures and recommends a few for your topic:
Make a 40-second explainer about RAG, no presenter. Which styles are there?
Use the explicit invocation from the table above to guarantee selection. The skill works in the language of your request.
The agent runs the bundled scripts itself. To set up a job manually, point SKILL_DIR at your installation:
SKILL_DIR=~/.claude/skills/lanshu-create-ai-presenter-video
python3 "$SKILL_DIR/scripts/init_job.py" \
--job-dir ~/Videos/my-presenter-video \
--presenter-image ~/Pictures/presenter.png \
--topic "Context engineering in one minute" \
--duration 60 \
--aspect 9:16 \
--rights-confirmed \
--adult-presenter-confirmed
Complete the manual review and upload approvals in job.json, then run preflight:
python3 "$SKILL_DIR/scripts/preflight.py" ~/Videos/my-presenter-video/job.json
After each stage, record its artifacts in job.json and let the checker compute the state:
python3 "$SKILL_DIR/scripts/check_state.py" ~/Videos/my-presenter-video/job.json --write
A styled explainer by hand, from a job directory (X=$SKILL_DIR/explainer):
python3 "$SKILL_DIR/scripts/init_job.py" --job-dir . --route styled --explainer-style v8-chalkboard --topic "RAG in 40 seconds"
python3 "$X/tools/story.py" story # story/script.md → voice + word times → story/story.json
bash "$X/tools/new_film.sh" v8-chalkboard story film # a playable draft; perform each line in film/beats.js
python3 "$X/tools/qa.py" film qa/film # check, stillness, snapshots, cover
bash "$X/tools/render.sh" film rag outputs # master, share copy, subtitles
Scripts
| Script | Purpose |
|---|---|
init_job.py |
Creates a self-contained job directory, copies all inputs into it, and records job-relative paths. |
preflight.py |
Validates inputs, manual review, and approvals; separates local errors from remote-generation blockers. |
plan_segments.py |
Splits the locked narration at real ASR pauses when a provider caps request or reference-audio duration. |
check_state.py |
Computes the evidence-backed production state and exits non-zero when the recorded state overclaims. |
finalize_delivery.sh |
Builds master and share encodes, verifies full decode, delivered loudness, and black or frozen frames, then publishes them with a contact sheet and report. |
Explainer tools
Under explainer/tools/, used on the styled route:
| Tool | Purpose |
|---|---|
story.py |
script.md → MiniMax voice per line with the engine's word timestamps → story.json; --audio for your own narration, --dry for a silent draft, --check for the plan and estimated length. |
new_film.sh / new_topic.sh |
A playable film from a style's starter (or drafts in the nine visual styles at once). |
docs.py |
Script, beat sheet, timeline, and a storyboard table from the story. |
qa.py |
hyperframes check, snapshots at every chapter, stillness pairs, a cover frame, and a composition report. |
render.sh |
Render, finalize with finalize_delivery.sh, write subtitles (SRT); DRAFT=1 makes a 720p review copy for a phone. |
srt.py, still_grid.py, fonts.py, sync.sh, stamp.py |
Subtitles, a 3×3 style comparison still, font subsets, and project plumbing. |
Reference guides
The agent loads each guide only when it reaches the matching stage, which keeps context usage low.
| Guide | Covers |
|---|---|
generation.md |
Intake, script and narration, capability selection, billing gates, segment planning, presenter prompts |
editing.md |
Timeline contract, segment seams, openings and closes, captions, keyword graphics, preview and export |
qa-recovery.md |
Acceptance gates and recovery playbooks for lip-sync, identity, seams, loudness, and remote tasks |
styled-explainer.md |
The styled explainer route: story pipeline, style starters, performing scenes, and an optional method for adding a digital human |
explainer/STYLES.md |
The style menu and gallery, common words → styles, and how to write the narration for each style |
explainer/KITS.md |
The kit contract, the aesthetic baseline, the starters, and the tools |
explainer/GOTCHAS.md |
HyperFrames pitfalls met while building the styles |
Repository layout
lanshu-create-ai-presenter-video/
├── SKILL.md # Skill entry point: metadata and workflow
├── README.md
├── README.zh-CN.md
├── agents/
│ └── openai.yaml # Codex display metadata; other harnesses ignore it
├── assets/
│ └── job.template.json # Job manifest template
├── references/ # Stage guides loaded on demand
├── scripts/ # Job setup, gates, segment planning, delivery
├── explainer/ # Styled explainer engine: core runtime, twelve style kits + starters, tools, examples
│ ├── STYLES.md # Style chooser with the gallery
│ ├── KITS.md # The kit contract and tools
│ ├── kits/<style>/ # One look per style, and starter/ = the film minus the topic
│ ├── stories/ # Example scripts (KV cache) and a draft test story
│ ├── examples/kv-cache/ # The finished KV cache film in each style
│ └── tools/ # story.py, new_film.sh, qa.py, render.sh, srt.py, …
└── tests/
├── smoke.sh # End-to-end test with synthetic media
└── explainer_smoke.sh # Styled route: intake, story, starter sync, state
Defaults
| Setting | Default |
|---|---|
| Format | 9:16, 1080×1920, 30 fps (styled explainer: 16:9, 1920×1080, 30 fps) |
| Duration | 45–75 seconds from a topic; natural length for a supplied script |
| Voice | Stock voice unless an authorized sample is provided; styled route: MiniMax Chinese (Mandarin)_Reliable_Executive, speed set per style |
| Structure | Hook, 2–4 content beats, concise close |
| Music and call to action | Off unless requested |
| Loudness | −16 LUFS ±0.5 LU, true peak ≤ −1 dBTP; override with PROGRAM_LUFS |
Safety and cost controls
- Image rights and adult-presenter status are confirmed before any upload.
- Voice cloning requires explicit authorization, and a voice is never inferred from an image.
- Before the first paid call, the agent states the uploads, requested seconds, known price, pilot size, and retry ceiling.
- When a provider caps duration, the quote uses the total requested seconds from the segment plan.
- Interrupted remote tasks are polled by their saved task ID before any resubmission.
- Work stops after three rejected paid candidates, with a summary of the recurring failure and remaining options.
- On the styled route the only paid call is the voice — one call per line, cached, so an edit re-voices only that line; drafts in the nine visual styles cost nothing more.
Privacy
- The repository contains no API keys, access tokens, signed URLs, or user media.
- Provider request records are stored without credentials or expiring URLs.
- Preflight and delivery reports store file names or job-relative paths only, never absolute machine paths.
- The styled explainer downloads font subsets from Google Fonts and jsDelivr (only the characters used); word timing
comes from the voice provider's own timestamps, so no speech model is installed; snapshots are taken with
--describe false, so frames stay local.
Testing
The smoke test drives a synthetic job from intake to verified without calling any remote service. It requires FFmpeg, jq, and Python 3.9+:
bash tests/smoke.sh
bash tests/explainer_smoke.sh # styled explainer; also needs Node.js and rsync
CI runs metadata validation, a portability check, syntax checks for the explainer engine, and both smoke tests on every push and pull request.
Contributing
Issues and pull requests are welcome. Reports from different harnesses and providers are especially valuable, as are improvements to the workflow, compatibility, and quality checks. To add another explainer style, follow the kit contract in explainer/KITS.md and the starter brief in explainer/STARTER-BRIEF.md.
Author
Created and maintained by 岚叔 (Lanshu). Follow on X for updates and new AI video workflows:
License
Released under the MIT License. Fonts, libraries, and services the explainer engine uses are listed in explainer/THIRD_PARTY.md.
lanshu-create-ai-presenter-video
English | 简体中文
一个主题或一份文案，交给你正在用的 AI agent，产出一条经过验收、可直接发布的讲解视频：可以由数字人出镜讲解（需要一张授权人物图），也可以用十二种讲解风格之一把内容“演”出来。
lanshu-create-ai-presenter-video 是一个 Agent Skill（岚叔 · 通用数字人与讲解视频制作），带领 AI agent 走完讲解视频的全流程。数字人路线包括文案、配音、人物生成、口型同步、字幕与关键词动效、剪辑、渲染和质量验收；风格化路线从逐字对时的讲稿出发，用十二种风格之一（九种画风、三种讲法）把每句讲解演成画面，一直到渲染成片。每个阶段都以磁盘上的产物为准入证据，成片在通过完整解码和响度检查之前不会交付。
核心特性
- 不绑定 harness：标准
SKILL.md，可在 Claude Code、Codex、Gemini CLI、Cursor、OpenCode、GitHub Copilot 等支持 Agent Skills 的工具中直接加载；任何能读文件、执行 shell 命令的 agent 也能照着执行。 - 不绑定服务商：数字人路线的配音、数字人视频、口型同步和语音识别都按能力在运行时选型，每个任务记录实际使用的服务商、模型、参数和任务 ID。风格化路线用 MiniMax 配音（逐字时间直接取自配音引擎），也可以用你在别处配好或自己录的配音。
- 十二种可演绎的讲解风格：九种画风（设计师留白、科技感信号、手帐、纸艺立体书、波普漫画、3D 一镜到底、图纸与注脚、黑板报、黏土小城）加三种讲法（推演、案卷、小剧场）。每种都是可复用的风格包和起步模板，换一个题目几条命令就能完整播放，讲稿也按所选风格来写。
- 配音锁定时间轴：审定后的完整配音是人物动作、字幕、剪辑点和成片时长的统一时钟，保证口型与段落边界对齐。
- 证据驱动的阶段：从
intake到verified共八个阶段，状态由产物计算得出，而不是手工声明。 - 成本护栏：先做低成本试片；首次付费调用前明确报价；设置重试上限；任务中断时凭任务 ID 恢复，避免重复扣费。
- 交付前验证：母版与分享版先完成完整解码和响度检查，全部通过才发布。
两条路线
| 路线 | 成片 | 你提供 | 付费生成 | 画幅 |
|---|---|---|---|---|
| 数字人讲解 | 数字人出镜讲解，字幕和关键词动效辅助 | 主题或文案 + 授权人物图 | 配音 + 数字人视频 | 任意，默认 9:16 竖屏 |
| 风格化讲解 | 不用数字人：每一句讲解都用画面“演”出来，十二种风格可选（九种画风 + 三种讲法） | 主题或文案（也可以用你自己录好的配音） | 只有配音（自带配音则不花钱） | 16:9 横屏 |
agent 会根据你的需求判断路线；拿不准时会带着风格图只问一次。所有风格共用一套接口（逐字字幕、章节条、结尾金句、一帧复习图）。其中九种是画风，区别在于用什么画面把内容演出来：设计师留白、科技感信号、手帐、纸艺立体书、波普漫画、3D 一镜到底、图纸与注脚、黑板报、黏土小城。下图是仓库自带的 KV cache 讲解片在九种画风里的同一时刻：
另外三种是讲法，画面自带一种讲述方式，写稿时可以参考并调整它的叙事结构：推演（在一张画布上把图形和公式一步步推出来，颜色把符号和图形绑在一起）、案卷（在调查板上从一起异常查到结案）、小剧场（生活场景小剧场：角色遇到误区，用账单、队列或实物对照找到原因，一句话把比喻对上真名）。下图是同一个 KV cache 难题用三种讲法讲：
换一个新题目，几条命令就能在任一风格里得到一版能完整播放的初稿：配音、逐字时间、字幕、章节、结尾金句、复习页和音效都自动生成，agent 再把每句话的画面演绎出来。选风格看 explainer/STYLES.md，完整流程看 references/styled-explainer.md，里面也写了想把自己的数字人融进风格片时的做法（可选）。
需要提供什么
| 输入 | 必需 | 说明 |
|---|---|---|
| 主题或完整文案 | 是 | 主题会写成 45–75 秒的文案；自带文案保持自然时长。 |
| 人物图 | 数字人路线需要 | 包含一位清晰的成年人物，并已确认使用权。风格化讲解不需要。 |
| 声音样本 | 否 | 仅在明确授权克隆时使用，否则选用库存声音并记录。 |
| 辅助素材 | 否 | 屏幕录制、图片、B-roll 或品牌素材，只用在能证明或说明口播内容的地方。 |
| 交付偏好 | 否 | 目标平台、时长、画幅、风格、水印、音乐和结尾引导。 |
工作方式
数字人路线：
主题或文案 + 授权人物图
│
▼
锁定文案与完整配音 ──► 配音成为全片时钟
│
▼
低成本人物试片
│
▼
生成数字人素材（服务商有时长上限时，按真实停顿分段）
│
▼
按音频时间轴剪辑：字幕、关键词动效、封面、结尾
│
▼
技术验收与画面验收
│
▼
母版、分享版、九宫格与交付报告
风格化路线：
主题或文案 ──► 选风格（风格菜单 + 效果图，或九种画风都出草稿再挑）
│
▼
按风格写讲稿 ──► 配音并取得逐字时间（或用你自己的配音）
│
▼
用风格起步模板出初稿：字幕、章节、结尾金句、复习页、音效
│
▼
分镜 ──► 每一句都按字演成画面
│
▼
验收（检查、静止检测、封面）──► 渲染 ──► 母版、分享版、字幕、交付报告
任务必须具备相应证据才能进入下一阶段，由 check_state.py 根据产物计算：
| 阶段 | 所需证据 |
|---|---|
intake |
任务已创建 |
content_locked |
通过的预检报告、文案、节拍表 |
audio_locked |
可解码的最终配音、ASR 报告 |
visual_plan_locked |
时间轴、分镜、已审批的计划 |
presenter_generated |
已记录的数字人能力、选定视频、画面审核 |
composition_checked |
合成检查报告 |
rendered |
同时含音视频、可解码的渲染文件 |
verified |
母版、分享版，以及输出响度达标的交付报告 |
风格化路线的 audio_locked 还要求已配音的 story.json（--dry 草稿不算）；presenter_generated 由完成演绎的成片及其画面审核达成，而不是数字人视频。
运行环境
- 支持 Agent Skills 的 harness，或任何能读文件、执行 shell 命令的 coding agent。
- Python 3.9+、FFmpeg 与
ffprobe、Bash、jq、awk、sed。 - 数字人路线：至少一种可调用的配音、数字人视频生成与口型同步能力，云服务 CLI、API 或本地模型均可；可选 HyperFrames 等确定性时间轴合成器，用于字幕、动效和成片渲染。
- 风格化讲解另需：Node.js（HyperFrames 通过
npx运行）、rsync、装有numpy的 Python（生成音效，用PYTHON指定），以及 MiniMax API Key（MINIMAX_API_KEY，用于配音和逐字时间戳），或者你自己录好的配音。
安装
仓库目录本身就是 Skill。把它克隆到所用 harness 的 skills 目录，目录名保持 lanshu-create-ai-presenter-video（Agent Skills 规范要求与 Skill 的 name 一致）。
| Harness | Skills 目录 | 显式调用 |
|---|---|---|
| Claude Code | ~/.claude/skills/，或项目内 .claude/skills/ |
/lanshu-create-ai-presenter-video |
| Codex | ~/.codex/skills/ |
$lanshu-create-ai-presenter-video |
| 其他支持 Agent Skills 的工具 | 见该工具文档，客户端列表附有各家说明链接 | 按该工具的方式 |
以 Claude Code 为例：
git clone https://github.com/cclank/lanshu-create-ai-presenter-video.git \
~/.claude/skills/lanshu-create-ai-presenter-video
在安装目录执行 git pull 即可更新。同时使用多个 harness 时，每个 skills 目录各克隆一份。
版本标签和可直接解压到 skills 目录的安装 ZIP 见 Releases，版本记录见 CHANGELOG.md。
不支持 Agent Skills 的 agent：把仓库克隆到任意位置，在对话开头告诉它：
先阅读 /path/to/lanshu-create-ai-presenter-video/SKILL.md，并严格按其中的流程工作。
快速开始
多数 harness 会根据 Skill 的描述自动选中它，直接描述想要的视频即可：
把这份文案和人物图做成一条 16:9、30 秒、有实时字幕的数字人讲解视频。
做风格化讲解时不用先知道有哪些风格，直接问就行，agent 会带着效果图列出十二种风格，并推荐适合你题目的几种：
不要真人，做一个 40 秒讲 RAG 的讲解视频，有哪些风格可以选？
想确保命中时，使用上表中的显式调用方式。Skill 会沿用你提问所用的语言。
Agent 会自行调用内置脚本。如需手动建立任务，把 SKILL_DIR 指向安装目录：
SKILL_DIR=~/.claude/skills/lanshu-create-ai-presenter-video
python3 "$SKILL_DIR/scripts/init_job.py" \
--job-dir ~/Videos/my-presenter-video \
--presenter-image ~/Pictures/presenter.png \
--topic "用一分钟讲清楚上下文工程" \
--duration 60 \
--aspect 9:16 \
--rights-confirmed \
--adult-presenter-confirmed
在 job.json 中补全人工检查与远程上传许可，然后运行预检：
python3 "$SKILL_DIR/scripts/preflight.py" ~/Videos/my-presenter-video/job.json
每完成一个阶段，在 job.json 中登记产物，由检查器计算任务状态：
python3 "$SKILL_DIR/scripts/check_state.py" ~/Videos/my-presenter-video/job.json --write
手动做一条风格化讲解（在任务目录里运行，X=$SKILL_DIR/explainer）：
python3 "$SKILL_DIR/scripts/init_job.py" --job-dir . --route styled --explainer-style v8-chalkboard --topic "40 秒讲清楚 RAG"
python3 "$X/tools/story.py" story # story/script.md → 配音与逐字时间 → story/story.json
bash "$X/tools/new_film.sh" v8-chalkboard story film # 能完整播放的初稿；在 film/beats.js 里逐句演绎
python3 "$X/tools/qa.py" film qa/film # 检查、静止检测、截图、封面
bash "$X/tools/render.sh" film rag outputs # 母版、分享版、字幕
脚本
| 脚本 | 用途 |
|---|---|
init_job.py |
创建自包含的任务目录，把全部输入复制进来，并只记录任务内相对路径。 |
preflight.py |
校验素材、人工检查与授权，区分本地错误和远程生成前的阻塞项。 |
plan_segments.py |
服务商限制单次请求或参考音频时长时，按锁定配音的 ASR 真实停顿规划分段。 |
check_state.py |
根据证据计算任务所处阶段；声明的状态超出证据时返回非零。 |
finalize_delivery.sh |
生成母版与分享版，验证完整解码、交付响度、黑帧与冻帧，全部通过后连同九宫格和报告一起发布。 |
讲解工具
位于 explainer/tools/，用于风格化路线：
| 工具 | 用途 |
|---|---|
story.py |
script.md → MiniMax 逐句配音并取得引擎返回的逐字时间 → story.json；--audio 使用你自己的配音，--dry 生成无声草稿，--check 查看结构与预计时长。 |
new_film.sh / new_topic.sh |
用风格起步模板生成能完整播放的片子（或一次生成九种画风的草稿）。 |
docs.py |
从讲稿生成文案、节拍表、时间轴和分镜表。 |
qa.py |
运行 hyperframes check，截取每章画面，做静止检测，导出封面图和合成报告。 |
render.sh |
渲染，调用 finalize_delivery.sh 交付，生成 SRT 字幕；DRAFT=1 输出可发到手机上看的 720p 审片版。 |
srt.py、still_grid.py、fonts.py、sync.sh、stamp.py |
字幕、风格对比图、字体子集，以及工程同步。 |
参考文档
Agent 只在进入对应阶段时加载相应文档，减少上下文占用。
| 文档 | 内容 |
|---|---|
generation.md |
输入检查、文案与配音、能力选型、付费闸门、分段规划、人物提示词 |
editing.md |
时间轴约定、分段接缝、开场与结尾、字幕、关键词动效、预览与导出 |
qa-recovery.md |
验收标准，以及口型、人物一致性、接缝、响度和远程任务的故障修复 |
styled-explainer.md |
风格化讲解路线：讲稿流水线、风格起步模板、画面演绎，以及融入数字人的可选做法 |
explainer/STYLES.md |
风格菜单与效果图、常见说法对应的风格、按风格写稿要点 |
explainer/KITS.md |
风格包接口、美学基线、起步模板与工具 |
explainer/GOTCHAS.md |
制作风格过程中踩过的 HyperFrames 坑 |
目录结构
lanshu-create-ai-presenter-video/
├── SKILL.md # Skill 入口：元数据与工作流
├── README.md
├── README.zh-CN.md
├── agents/
│ └── openai.yaml # Codex 界面显示信息，其他 harness 会忽略
├── assets/
│ └── job.template.json # 任务清单模板
├── references/ # 按阶段加载的参考文档
├── scripts/ # 任务初始化、闸门、分段规划与交付
├── explainer/ # 风格化讲解引擎：核心运行时、十二种风格包与起步模板、工具、示例
│ ├── STYLES.md # 风格选择指南（含效果图）
│ ├── KITS.md # 风格包接口与工具
│ ├── kits/<style>/ # 每种风格的视觉，starter/ 是去掉题目的起步模板
│ ├── stories/ # 示例讲稿（KV cache）与草稿测试稿
│ ├── examples/kv-cache/ # 每种风格的 KV cache 成片工程
│ └── tools/ # story.py、new_film.sh、qa.py、render.sh、srt.py 等
└── tests/
├── smoke.sh # 基于合成素材的端到端测试
└── explainer_smoke.sh # 风格化路线：建任务、讲稿、模板同步、状态
默认设置
| 设置 | 默认值 |
|---|---|
| 画幅 | 9:16、1080×1920、30 fps（风格化路线：16:9、1920×1080、30 fps） |
| 时长 | 主题生成 45–75 秒；自带文案保持自然时长 |
| 声音 | 无授权样本时使用库存声音；风格化路线默认 MiniMax Chinese (Mandarin)_Reliable_Executive，语速按风格设定 |
| 结构 | 开场钩子、2–4 个内容节拍、简洁结尾 |
| 音乐与结尾引导 | 默认不加，按需添加 |
| 响度 | −16 LUFS ±0.5 LU，真峰值 ≤ −1 dBTP；可用 PROGRAM_LUFS 覆盖 |
安全与成本控制
- 任何上传前，先确认图片使用权和人物已成年。
- 克隆声音需要明确授权，绝不根据图片推断声音。
- 首次付费调用前，agent 会说明上传内容、请求时长、已知价格、试片规模和重试上限。
- 服务商有时长上限时，按分段计划的总请求秒数报价。
- 远程任务中断后，先用已保存的任务 ID 查询，再考虑重新提交。
- 连续三个付费候选被否决后停止，并总结反复出现的问题和剩余选项。
- 风格化路线唯一的付费调用是配音：每句一次并缓存，改一句只重配那一句；九种画风的草稿不会产生额外费用。
隐私
- 仓库不包含 API 密钥、访问令牌、签名下载地址或用户素材。
- 服务商请求记录去除凭据与临时 URL 后再保存。
- 预检与交付报告只记录文件名或任务内相对路径，不写入本机绝对路径。
- 风格化路线会从 Google Fonts 和 jsDelivr 下载字体子集（只含用到的字）；逐字时间直接取自配音服务返回的时间戳，不需要安装任何语音识别模型；截帧检查一律带
--describe false，画面不外传。
测试
冒烟测试用合成素材把一个任务从 intake 推进到 verified，不调用任何远程服务。需要 FFmpeg、jq 与 Python 3.9+：
bash tests/smoke.sh
bash tests/explainer_smoke.sh # 风格化路线；还需要 Node.js 和 rsync
每次推送和 Pull Request 都会在 CI 中运行元数据校验、可移植性检查、讲解引擎的语法检查和两组冒烟测试。
参与贡献
欢迎提交 Issue 和 Pull Request。特别欢迎反馈在不同 harness、不同服务商下的使用情况，以及对工作流、兼容性和质量检查的改进。想新增讲解风格，请参照 explainer/KITS.md 的风格包接口和 explainer/STARTER-BRIEF.md 的起步模板说明。
作者
由 岚叔 创建并维护。欢迎在 X 上关注，获取更新与更多 AI 视频工作流：
许可证
基于 MIT License 发布。讲解引擎用到的字体、库和服务见 explainer/THIRD_PARTY.md。