chanjing-one-click-video-creation

一键式视频渲染器

功能说明

一键调用 Chanjing API 完成口播 TTS、数字人合成、文生视频与本地封装；集成 ffmpeg / ffprobe 做拼接、转码与轨对齐。编排与安全细则见 §3–§8 与 templates/；成片命令见 §5。

运行依赖

必须可用的二进制或等价封装（具体调用方式见 §5、run_render.py）：

• ffmpeg：拼接、转码、封装
• ffprobe：时长、分辨率、旋转等元数据（与数字人轨对齐）
• chan-skill（或同仓库下直接 python 调用子技能脚本）：驱动 chanjing-tts、chanjing-video-compose、chanjing-ai-creation 等 CLI

环境变量与机器可读声明

• 环境变量键名与说明：manifest.yaml（environment 段）及本文
• 键名、默认值、凭据模型、二进制、合规 permissions、clientPermissions、agentPolicy：manifest.yaml

§3.2 表格为配合 run_render.py 阅读的说明；若与 manifest.yaml 冲突，以 manifest.yaml 为准。

使用命令

• ClawHub（slug 以注册表为准，常与技能包名一致）：clawhub run chanjing-one-click-video-creation
• 本仓库直连：python scripts/run_render.py --input workflow.json --output-dir ./outputs/run1（在技能目录或配合 SKILLS_DIR / CHANJING_ONE_CLICK_VIDEO_SKILLS_ROOT / CHAN_SKILLS_DIR 使用）

---

速查

内容	位置
工作流、duration_sec、null/合并、选题校验	§4.1
切段、奇偶镜、scenes[]、scene_count/video_type；首镜 voiceover ≤20 字（硬）	storyboard_prompt.md 篇首「文本切段」；script_prompt.md 首镜口播；video_brief_plan.md
渲染技术、状态、partial/success、硬约束	render_rules.md §1–§4；§7、§8
ref_prompt / 文生提示词	storyboard_prompt.md + history_storyboard_prompt.md；§4.2 指针
请求体字段与默认	§6
run_render.py、子进程 CLI	§5
安全、凭据、信任边界、策略	manifest.yaml + §3.1（§3.1 不重复 manifest 表格）
环境变量、二进制、副作用、落盘	§3.2

冲突：渲染实现以 render_rules.md 为准；ref_prompt 条文以 storyboard_prompt.md / history_storyboard_prompt.md 为准（§4.2 汇总指针）。run_render.py 只实现 §5 + render_rules.md，不增业务规则。执行：手工编排子 skill、仅 run_render、或混用。

---

1. 做什么

1. 选题或全文 → video_plan、口播全文、分镜
2. TTS：整段优先；超长按分镜少批合并（细则与字数见 render_rules.md §3·C.4）
3. 按镜切音频
4. 数字人分镜：chanjing-video-compose（音频驱动）
5. AI 分镜：ref_prompt → chanjing-ai-creation → 与镜内音频合成
6. 封装：对齐公共数字人轨 → ffmpeg concat → 本地 mp4

---

2. 何时用 / 何时不用

适合	要成片；口播与画面混剪；用户明确要生成短视频
不适合	仅文案/标题；未要视频；只剪已有素材

---

3. 前置条件

• 鉴权：chanjing-credentials-guard；凭据路径与字段见 manifest.yaml、§3.1；无凭证时子进程可 open_login_page.py
• Plan/Script/分镜：本地 Agent 逻辑，无需外部 LLM API key（本 skill 必选路径不依赖外部 LLM）
• 本机二进制与仓库布局：§3.2（ffmpeg / ffprobe、SKILLS_DIR 等）
• 数字人与音色：勿用环境变量或仓库内缓存文件保存跨任务的「默认」audio_man / person_id / figure_type。每次任务在 workflow.json 根级显式填写；由 Agent 按 video_plan（如 video_type）、口播人设与选题语义，调用 list_voices.py 与 list_figures.py（--source 取 common / customised 等与本次任务一致）选型后写入；audio_man 宜与所选形象的 audio_man_id 一致。
• 公共数字人选型（禁止「只取列表前几项」）：须用 list_figures.py --source common --json 拉取候选（必要时增大 --page-size 或翻页，覆盖足够条目），在候选内逐项对比后再定稿：name、figures[].type（→ figure_type）、figures[].width/height（画幅与 D.1c 一致）、audio_man_id、audio_name（若有）与 video_plan/口播人设（性别、气质、行业、年龄感）是否匹配。默认偏好年轻、有活力的形象：名称或 audio_name 中含青年/少女/小哥哥/小姐姐/学生/元气/青春/年轻等正向信号时优先；仅当选题或用户明确要求成熟、权威、中老年等气质时，再选对应人设。定制源 customised 同样对比 name、width/height、audio_man_id 等，勿未经比较直接取页首。

3.1 安全、凭据与信任边界

环境变量与二进制以 manifest.yaml 与 §3.2 为据。审阅时可对照 description 与 manifest.yaml（含 agentPolicy）。

• 能力与管道：步骤级说明见 §1；run_render 职责与子进程见 §5（不在此重复链路）。
• 主凭据 / 路径 / primaryEnv：见 manifest.yaml；路径与写回行为另见 §3.2 持久性表「凭据状态」及 CHANJING_OPENAPI_CREDENTIALS_DIR（兼容 CHANJING_CONFIG_DIR）。
• 敏感与合规：勿回显完整密钥、勿将 credentials.json 提交版本库；权限建议 0700 / 0600（配置脚本尽量设置）。
• 信任与出站行为：HTTPS、按返回 URL 拉取媒体、--output-dir 落盘等细节见 §3.2「典型副作用」与持久性表；须自行判断是否信任蝉镜主机与链接。
• 浏览器：缺凭证时的 webbrowser.open / open_login_page.py 见 §3.2 同表。
• Agent 策略：manifest.yaml 中 agentPolicy（非 always、不改其它 skill）。

3.2 ランタイム契約（環境変数、バイナリ、副作用、書き込み先）

scripts/run_render.py および同じリポジトリ内の子スキルの動作に合わせています。冒頭の YAML および manifest.yaml と一致します。他の製品ドキュメントと併記する場合は、このリポジトリのソースコード、manifest.yaml、本文を優先してください。

環境変数（一般的なもの）

命名はリポジトリのルートにある 合规规则.md §3 に準拠します。以下の推奨名はコードで有効です。旧名も引き続き使用できます（manifest.yaml および各子スキルの説明を参照）。

変数	必須性	デフォルト／説明
CHANJING_OPENAPI_BASE_URL	任意	デフォルトは https://open-api.chanjing.cc。CHANJING_API_BASE も使用できます。
CHANJING_OPENAPI_CREDENTIALS_DIR	任意	デフォルトは ~/.chanjing。credentials.json の保存先ディレクトリです。CHANJING_CONFIG_DIR も使用できます。
SKILLS_DIR	レイアウトによる	プラットフォーム予約済み。skills/chanjing-tts などを含むリポジトリのルートです。未設定の場合は、CHANJING_ONE_CLICK_VIDEO_SKILLS_ROOT、CHAN_SKILLS_DIR の順に試し、その後 run_render.py のスクリプトパスから4階層上を推定します。
CHANJING_ONE_CLICK_VIDEO_REF_PROMPT_MAX_CHARS	任意	デフォルトは 8000。ref_prompt 全体の上限です。AI_VIDEO_PROMPT_MAX_CHARS も使用できます。
CHANJING_ONE_CLICK_VIDEO_CREATION_MODEL_CODE	任意	テキストから動画を生成する場合のデフォルトの model_code です。AI_VIDEO_MODEL も使用できます。

注：一部の外部ドキュメントに記載されている FIRST_DIGITAL_HUMAN_MAX_CHARS（最初のデジタルヒューマンの絵コンテにおける voiceover の文字数上限）などの変数は、現在、このリポジトリの run_render.py では読み込まれていません。今後、ソースコードに対応する os.environ が追加された場合は、この表も更新してください。

外部バイナリ

バイナリ	必須性	用途
ffmpeg	ワンクリック動画生成で run_render.py を実行する場合に必須	動画の結合、トランスコード、音声・動画の多重化など。純粋な API のみをオーケストレーションし、このレンダリングスクリプトを実行しない場合はインストール不要です。
ffprobe	同上	メディアの解像度、長さ、回転メタデータなどを読み取り、デジタルヒューマンのトラックと位置を合わせます。

スクリプト実行時によくある副作用（種類別）

種類	説明
アウトバウンド HTTPS	蝉镜 Open API（CHANJING_OPENAPI_BASE_URL／互換名 CHANJING_API_BASE）、および API／CDN から返される video_url／音声 URL などの素材の取得。
ローカルファイル	run_render.py --output-dir の下によく作成されるファイル：final_one_click.mp4、workflow_result.json、work/（中間音声、分割動画、concat リストなど）。詳細は実行するコマンドと templates/render_rules.md に従います。
子プロセス	ffmpeg／ffprobe。run_render は subprocess を介して、同じリポジトリ内の skills/chanjing-tts、chanjing-video-compose、chanjing-ai-creation などのディレクトリにある Python CLI を呼び出します。
ブラウザー	認証情報がない場合やログインを案内する場合、認証フローで webbrowser.open を呼び出すか、chanjing-credentials-guard の open_login_page.py を実行することがあります（各スキルの _auth.py と同様の動作です）。

永続的な変更の範囲とユーザーによる制御

以下は、このスキルにおいて想定内の副作用です。パスと環境変数で書き込み先を制御でき、無関係なディレクトリが暗黙に汚染されることはありません。

カテゴリ	書き込まれるもの	典型的な場所	ユーザーによる制御方法
認証情報の状態	設定を通じて書き込まれる app_id／secret_key、更新後の access_token、 expire_in など	CHANJING_OPENAPI_CREDENTIALS_DIR/credentials.json（デフォルトは ~/.chanjing/credentials.json。互換名は CHANJING_CONFIG_DIR）	推奨名または旧名を設定します。または、このファイルを移動／削除します。シークレットキーをバージョン管理リポジトリにコミットしないでください。
ワンクリック動画生成の成果物	final_one_click.mp4、workflow_result.json、work/ など	run_render.py --output-dir で指定（一般的には、個々のタスクの outputs/<任务名>/）	明示的に --output-dir を指定します。タスク完了後、必要に応じてそのディレクトリを保持または削除します。
その他のダウンロード用スクリプト（子スキル）	合成結果などのローカル保存	各スキルの download_result.py など。デフォルトでは現在の作業ディレクトリ下の outputs/<产品线>/ が多く、または --output で絶対パスを指定します。	想定した cwd で実行するか、必ず --output を渡します。詳細は該当スキルの SKILL.md を参照してください。
一時ファイル／処理中ファイル	TTS の結合、分割、アップロード前のキャッシュなど	多くは上記の output-dir 下の work/ またはスクリプトで定められたサブディレクトリ	出力ディレクトリとあわせて管理します。

認証情報ファイル：パスと読み書きの仕様は上表の 認証情報の状態 の行を参照してください。初回設定については skills/chanjing-credentials-guard/SKILL.md を参照してください。

---

4. ルールのまとめ

4.1 工作流编排

合并：null = 不覆盖。顺序：默认铺底 → 非 null 覆盖 → 布尔/整数校正。字段默认见 §6；未在表中展开的缺省由 run_render.py（及子进程）按实现与环境变量读取（不含音色/数字人：audio_man、person_id/avatar_id、figure_type 仅来自 workflow.json，见 §3）。

duration_sec：策划参考，非 ffmpeg 上限。成片时长以 TTS+ffprobe 为准。scene_count 见 video_brief_plan.md；切段与 AI 条数依实测与字幕轴（render_rules.md §3·C.5）。禁止为凑时长裁已定稿口播（除非用户要求）。

选题：去空白 <5 字、占位串（如「你好」「test」）拒收；可扩写；严格模式模糊则失败。

步骤：1) Plan → video_brief_plan（败则全败；模板见 video_brief_plan.md）2) Script（hook / 首段与首镜对齐：≤20 字硬上限，见 script_prompt.md）3) Storyboard：语义切分；storyboard_prompt.md（首个分镜 voiceover 同上硬上限）；非当代 history_storyboard_prompt.md；DH chanjing-video-compose，AI chanjing-ai-creation；TTS/多段 AI/mux render_rules.md §3、§5 4) Render：render_rules.md §3（含 §3·C.6）、§4（表 4–6）；ref_prompt 质检见 storyboard_prompt.md / history_storyboard_prompt.md（§4.2）；重试/partial render_rules.md §1 5) 成功：render_rules.md §1

仅渲染：run_render.py + full_script + scenes[]。顺序：Plan → Script → Storyboard → Render（各阶段用哪份模板见上列步骤）。

---

4.2 文生视频提示词（ref_prompt）— 指针

唯一条文真值（修订以模板为准，本文不重复 D.1–D.4 表文）：

范围	模板
当代向、D.0 语境缺省与文明圈推断、D.1 长度、D.1a、D.1b（易幻觉，全 skill 共用）、D.2 当代、手工 visual_prompt、D.3、D.4 当代装配与 7 要素 / 题材簇 / 单镜拼装 / 自检	templates/storyboard_prompt.md → 「文生视频提示词（当代向真值）」
D.2 非当代路由、历史流程层、文明圈与国别自洽、占位符纪律、与 D.3/D.4 衔接说明	templates/history_storyboard_prompt.md
族裔、历史/非当代中式造型与出现人物时的英文短语	templates/visual_prompt_people_constraint.md（显式族裔锚定、历史 / 非当代节；兼 render_rules.md §4 表 4–6）

仍仅在此处索引：长音频多段 render_rules.md §3·C.6；字数上限 CHANJING_ONE_CLICK_VIDEO_REF_PROMPT_MAX_CHARS（兼容 AI_VIDEO_PROMPT_MAX_CHARS）。模板与 render_rules.md 实现冲突时以 render_rules.md 为准。

---

5. 自动化编排（run_render.py）

依赖：鉴权；SKILLS_DIR / CHANJING_ONE_CLICK_VIDEO_SKILLS_ROOT / CHAN_SKILLS_DIR（§3）；chanjing-tts / chanjing-video-compose / chanjing-ai-creation

职责：① TTS+audio_task_state；批合并与单批字数上限见 render_rules.md §3·C.4（TTS_BATCH_MAX）② 切段（render_rules.md §3·C.5）③ 有 AI 镜时先完成首条数字人并 ffprobe（含 rotate）→ 再按映射提交文生 aspect_ratio/clarity（见 render_rules.md §3·C.6、debug.ai_video_submit_params）④ 与其余 DH/AI 并行 poll ⑤ AI 轨对齐该参照 ffprobe ⑥ ffmpeg concat ⑦ 多段文生在 ref_prompt 后追加英文分层；总长由 CHANJING_ONE_CLICK_VIDEO_REF_PROMPT_MAX_CHARS（兼容 AI_VIDEO_PROMPT_MAX_CHARS）约束

不做：不产 plan/script/storyboard；不自动非当代/当代；不用 list_tasks.py 当代次（render_rules.md §4 表项 8）

手工编排：仍须满足 render_rules.md §3、§4 与 §5；§3 细化（如 silencedetect、minterpolate、参照轨码率、同套切段音频换形象、TTS 批间静音等）全部保留。

输入 MVP

字段	必填	说明
full_script	是	与各镜 voiceover 按 scene_id 拼，norm 一致
scenes	是	scene_id（整数或纯数字字符串，按数值升序）、voiceover、use_avatar；AI 镜 ref_prompt（storyboard_prompt.md / history_storyboard_prompt.md；§4.2）；可选 subtitle
audio_man	是	宜与所选数字人形象的 audio_man_id 一致
person_id/avatar_id	条件	有 DH 镜必填
figure_type	否	与当次 list_figures.py 所选形象行的 figure_type 一致（公共多形态时必填）
subtitle_required	否	默认 false；为 true 时数字人镜烧录字幕（--subtitle show）
speed/pitch	否	默认 1/1
ai_video_duration_sec	否	5 或 10，默认 10
model_code	否	默认 CHANJING_ONE_CLICK_VIDEO_CREATION_MODEL_CODE（兼容 AI_VIDEO_MODEL）或 minmax-h3-t2v；creation_type=4；不传 ref_img_url
max_retry_per_step	否	默认 1（§6）

python scripts/run_render.py --input workflow.json --output-dir ./outputs/run1

输出：final_one_click.mp4；workflow_result.json；work/

---

6. 输入（请求体）

norm：去 \r、首尾空白；空→空串；与 run_render.py 一致。口播：先 full_script，再 script→copy_text→input_script→content 首个非空。无 topic：首句代选题（40 字内遇句末标点截，否则 24 字）。null/合并 §4.1。

字段	必填	说明
topic	条件	无则见首句规则；建议 ≥5 字
industry/platform/style	否	industry 空；platform/style：DEFAULT_* 或 douyin/观点型口播
duration_sec	否	DEFAULT_DURATION 或 60；策划参考
use_avatar	否	默认 true
avatar_id/voice_id	否	空；不得用环境变量兜底音色或数字人；须在 workflow.json 写明 audio_man/person_id（及有 DH 镜时的 figure_type），由 Agent 按当次任务调用 list_voices.py 与 list_figures.py（来源与 video_plan / 用户指定一致）对比 name、形态、画幅、audio_name 等后选型；禁止未比较即取列表最前几条；默认偏好年轻数字人（见 §3）
subtitle_required	否	默认 false（数字人成片不烧录字幕；run_render 传 hide）
cover_required	否	默认 true
strict_validation/allow_auto_expand_topic/max_retry_per_step	否	true/false/1
full_script	否	默认空
script_title/script_hook/script_cta	否	默认空
script/…	否	见上文口播顺序

---

7. 输出 JSON

键	含义
status	success / partial / failed
video_plan	Plan
script_result	title、hook、full_script、cta
storyboard_result.scenes[]	scene_id、duration_sec、voiceover、subtitle、visual_prompt、use_avatar
render_result	video_file、scene_video_urls、render_path、degrade_log
其它	error、debug…

渲染无降级：任一步失败即中断，不自动改为仅 DH 或仅 AI 成片。partial：未成 success（如 run_render 异常仍写 workflow_result.json）；不表示允许上述降级，不免 storyboard_prompt.md·D.1b 类质检。成功 degrade_log=[]；失败尽量保留已产出文案与分镜。

---

8. 硬性约束

表在 templates/render_rules.md §4；与 ref_prompt 交叉见 storyboard_prompt.md / history_storyboard_prompt.md（§4.2 指针）。本节为锚点。

---

9. 限制

• 本地 mp4；不上传
• AI 单段常 5–10s；长口播多段
• 成片时长=TTS 总轨；可与 duration_sec 不符
• TTS：整轨优先、超长少批合并；单批上限与合并策略（含 TTS_BATCH_MAX）以 render_rules.md §3·C.4 为准
• 文生失败可能为平台/模型；试增 max_retry_per_step、短 ref_prompt、拆镜；查 workflow_result.json