dososo/blcaptain-lingjian-video/blcaptain-lingjian-video

灵剪 (lingjian-video) 通用 Agent 发布级短视频 Skill

灵剪是一个通用的发布级中文短视频生产 Skill,可在任意能跑命令的 AI Agent 里运行(经 lj CLI)。用户只说目标、给文案/素材/录音或授权,宿主 agent 负责安装依赖、检测并继承能力、引导补齐发布级 TTS 与画面能力,再编排"素材 → 脚本 → 配音 → 画面 → 底部字幕 → 渲染 → QA → 导出"。CLI 是底层执行引擎,不是普通用户主入口。

诚实前提:灵剪只保证流程可复跑、门禁可审计,不承诺成片质量或"爆款"。

灵剪的独家差异化(命根子,别丢)

市面 AI 视频"一句话出片"是黑箱:骰子摇一次,吐一条,你没法改。灵剪反过来 —— 一句话进,脚本 / 分镜 / 配音 / 画面 / 配乐 / 字幕 / 音效全自动,但每一关,都能审。五条差异化,任何一条丢了灵剪就退化成又一个黑箱:

1. 蓝图先行:一部片由一张贯穿全片的蓝图统领(能量曲线 + 母题 + 每关产物与门禁),不是逐镜各自为政。(注:从流水线产物自动生成整片能量曲线仍在接入主线,当前 CLI 尚不自动产出,别对用户宣称已全自动生成。)
2. 本地导演控制台(director-board):每一关在本机 localhost 打开一个可读、可交互的导演板,把这一关的候选逐项摆给用户看。见下节红线。
3. 调研贯穿始终:调研不是只在开头,而是每一关持续 —— 吸收顶级证据 → 内化基线 → 牵引产出;失败要补不凑。
4. 关卡确认,给候选不给 yes/no:每一关不是问"行不行",而是给出候选让用户挑、让用户改,用户点头才进下一关。
5. 可审计:每一关的产物、门禁、证据都可追溯复核(results.json + 报告 + evidence 日志);门禁绑 artifact,内容变更自动失效。

本地导演控制台(director-board)· 硬规则

• 控制台 = 本机服务,永不远程。 每关的导演板只在 localhost / 本地静态服务打开(仓库 director-board/ 内 render.js + board.schema.json + standalone.html)。绝不把任何云端 / 部署 / 隧道 / 开发调试地址(vercel、trycloudflare、ngrok、作者私有预览页等)当作用户控制台展示,也绝不写进任何面向用户或对外发布的产物。用户走的每一步,右侧打开的都是他自己机器上的页面。
• 数据契约:每关产出符合 board.schema.json 的 board.json(meta + shots[],每镜 energy/script/signature/beats/transitions),渲染器逐镜展示 + 逐镜"确认"按钮;handle.allConfirmed() 全绿才允许进下一关。
• 同一渲染器横切每关:风格关 / 脚本关 / 配音关 / 画面关只换 meta 文案与卡片字段复用,不为每关重写。
• 确定性:禁 Date.now / 未播种 random,导演板可复现;纯原生 JS + SVG,无第三方库、无网络请求(读本地数据除外)。

普通用户工作流纲领(最高优先级)

• 不把 CLI、provider 矩阵、JSON、环境变量块甩给普通用户。宿主 agent 负责安装、检测、运行命令和解释结果;用户只需要说目标、确认内容、拖入素材/录音或授权。
• 每次只让用户做一个最短动作。不要同时给一堆选择;先按默认优先级自动继承和检测,缺什么再问什么。
• 发布级最短路径固定为:安装/初始化 → 能力门诊 → 补齐必需资源 → 脚本审阅 → 音色试听/选择 → 配音导演确认 → 配音试听审阅 → 画面审阅 → 渲染 → QA → 导出。
• 能自动继承的能力直接用;不能继承时,先问用户是否有现成资源。配音先要用户录好的口播音频;没有录音时才引导开通一个推荐 TTS。画面先要每镜真实视频素材或真正视频生成插件;不要把图片、模板动效、单图循环当发布级画面。
• 缺发布级能力时必须停下,用一句人话说明缺什么和下一步要用户提供什么。不要继续生成低质量 release,不要把样片说成可发布成片。
• 面向用户说“请拖入口播音频”“请拖入每镜视频素材”“我来帮你检查宿主插件是否可用”这类动作;不要让用户自己理解 doctor --json、export VOLCENGINE_... 或 provider 配置细节。
• 面向用户展示本地文件、审核 artifact、音频、视频、截图、导出包或证据日志时,必须使用可点击 Markdown 文件链接,并使用绝对路径;必要时带行号。不要只给相对路径或纯文本路径。示例:[voice_plan.json](/Users/.../artifacts/voice_plan.json)、[full.wav](/Users/.../artifacts/voice_segments/full.wav)。
• 用户没有录音时,默认只引导一个中文发布级 TTS 路径:打开火山豆包新版控制台开通页 https://console.volcengine.com/speech/new/setting/activate?projectName=default 开通服务/领取活动,再打开 API Key 管理页 https://console.volcengine.com/speech/new/setting/apikeys?projectName=default 创建 API Key。普通用户只需要 API Key;Resource ID 与 Voice Type 用灵剪默认值,不要让用户找旧版 APP ID、Access Token、Cluster ID、Voice Type。
• 用户拿到 API Key 后,按其系统给一条标准保存命令(docs/ONBOARDING.md 是唯一标准,逐字照搬):macOS 用 security 存进 Keychain、Linux 用 secret-tool 存进 Secret Service(两者 service = account = `lingjian:<NAME>`,前缀不能少,否则灵剪读不到)、Windows 用用户环境变量(SetEnvironmentVariable(...,"User") 或当前会话 $env:)。存后灵剪启动自动注入(inject_stored_credentials 读回),无需每次手动 export。命令用单次 stty -echo+IFS= read -r 读入(不用 security -w 两次确认,长 key 粘两遍必报 passwords don't match),粘贴时不回显要明说“看不到字符是正常的”。必须说明“直接粘贴原文,不要加双引号,不要发到聊天里”;key 只进本机安全存储,不上传、不联网。
• 用户侧入口只暴露一句中文和两个可选收敛参数:--style 控制统一风格,--profile 控制平台+受众预设。不要让用户堆一堆比例、节奏、字幕、BGM flag;缺省用 --style clean_product --profile douyin_product。
• 可用 style:4 套已实现风格库(完整方法论见 styles/<key>.md)——vox_cut(Vox 编辑剪影·橙黑半调)、dark_keynote(暗场发布·史诗)、cinematic(写实电影感·国风人文)、neue_sachlichkeit(新客观主义·实物档案);另有通用收敛预设 clean_product、bold_news、warm_lifestyle、tech_minimal。选风格后,必须读 `styles/<key>.md` 用它的色板/字体/质感/动画/prompt 约束去指导 Seedance/生图,别只当标签。换风格 = 复用横切能力换皮重排,不重做。可用 profile: product_intro、open_source_project_intro、tutorial_guide、review_comparison、ecommerce_sales、knowledge_explainer、douyin_product、xiaohongshu_life、shipinhao_knowledge。这些只收敛导演契约和提示,不承诺爆款。
• 内容类型 Profile 的 required_evidence 必须进入每镜导演分镜确认单、visual_plan.json、render_manifest.json 和 QA;不能只停留在提示词或文档里。--release --strict 下,Profile 要求的素材/证据没有进入每镜 expected_real_evidence / asset_strategy_v2 时必须阻断。

视频需求澄清阶段(必须先做)

普通用户第一次触发灵剪时,先用人话收集最小需求,不要直接进入 provider、CLI、JSON 或环境变量说明。必须确认以下 7 项:

我要做一条【平台】短视频,主题是【主题/产品/观点】。
画幅比例选择【9:16 / 16:9 / 3:4 / 4:3 / 1:1】,如果不确定,我会按平台推荐默认值。
内容依据是【一句话说明 / Markdown / 文档 / PDF / PPT / 网页链接 / GitHub 仓库 / 已有文案 / 其他素材】。
目标用户是【谁】。
希望观众看完后【下单/关注/咨询/理解某个观点】。
我现在有/没有现成视频素材。
我现在有/没有录好的口播音频。

执行规则:

• 用户已经给齐这些信息时,不要重复提问;先复述成一段清楚的制作目标,再进入能力门诊。
• 用户只给平台时,不能静默把抖音/小红书默认推断成 9:16 并继续。必须先让用户选择画幅比例:9:16、16:9、3:4、4:3、1:1;可以说明平台推荐默认值,用户不选时才采用默认值并在目标确认里明说。
• 用户只给主题、没有给内容依据时,不要直接编完整脚本。必须先问用户“这条视频要基于哪份内容做?”并让用户提供最方便的一种:一句话说明、Markdown、PDF、PPT、Word、网页链接、GitHub 仓库、产品介绍文案、已有脚本或截图。用户授权使用当前仓库/README/GitHub 链接时,才可把它作为内容依据。
• 用户确认内容依据后,先 ingest/extract 或读取该内容,再进入脚本生成。不能凭模型常识替用户编产品细节、功能边界、价格、授权或效果承诺。
• 用户缺视频素材时,不能直接跑发布级生成。必须先基于脚本拆出“每镜需要什么真实动态视频素材/生成资产”的清单,再让用户提供素材、授权宿主 agent 代采目标对象截图/录屏、或启用宿主 agent 中真正的视频生成插件。截图/录屏必须只采集目标对象内容,例如当前项目 README、Skill、CLI、QA、导出包、Codex 操作或终端输出;涉及当前屏幕时必须先确认隐私安全,用户不授权时只能给手动导入 mp4 的兜底。
• 开源项目介绍需要终端/QA/导出包证据时,宿主 agent 可以代跑 lj ingest command --command ... 把命令输出保存为项目内终端文本证据;这只是终端回放素材,不是屏幕录制。若用户/宿主已配置 LINGJIAN_TERMINAL_RECORD_CLI,可加 --record 采集真实终端录屏;未配置或失败时必须如实提示,不得伪造录屏。Codex 操作录屏可用 lj ingest codex --scene-id ...;默认只登记录屏任务,不会录当前屏幕。只有用户确认当前屏幕可录且无隐私内容后,才可加 --allow-screen-recording 触发 macOS screencapture 或 LINGJIAN_CODEX_RECORD_CLI;录屏失败或不可验证仍不能伪造成 captured。
• 用户缺口播音频时,先检查是否已有发布级 TTS key;没有才引导一个推荐路径。不要同时给多家 TTS 选择。
• 已有发布级 TTS key 时,不要隐藏使用哪个音色。先基于 provider 真实可用音色生成 5 个短试听,默认优先覆盖 2 个女声 + 3 个男声,让用户选一个;无法拉到列表或账号权限不足时只展示真实合成通过的音色,不要编造“热门前 5”或不可播放选项。如果当前账号只实际合成通过 1 个音色,必须明确说“当前账号只验证到 1 个可用音色”,并展示音色名称、voice_id 和试听文件。
• 用户选定音色或确认使用录音前,必须展示“配音导演确认单”,让用户确认语气、情绪、语速、停顿、重音和每镜表达方式。用户批准前,不要正式调用付费/发布级 TTS 生成全片配音。
• 每次只让用户补一个最短动作。例如先解决配音,再解决画面,不要把所有缺口一次性压给用户。

内容输入引导话术:

接下来先确定内容依据。你可以直接给我:
1. 一段文字/Markdown;
2. 一个网页或 GitHub 链接;
3. PDF、PPT、Word 文档;
4. 已有脚本/产品介绍/截图。
 
如果你只是给了主题,我会先问你是否允许我使用当前仓库 README / GitHub 页面作为依据,确认后再写脚本。

配音三审必须包含语气情绪确认单

配音不是“选一个音色后直接生成”。脚本批准后、正式调用发布级 TTS 或接入用户录音前,必须先给用户看“配音导演确认单”。这一步是必经环节,不能省略。

每条视频至少确认:

整体口播定位:产品介绍 / 教程说明 / 带货转化 / 知识科普 / 活动预告等。
目标听感:亲和、清晰、可信、兴奋、沉稳、专业或生活化。
语速策略:开头抓人、中段说明、证明处放慢、CTA 稍有行动感。
情绪曲线:每镜从 Hook、痛点、方案、证明到 CTA 的情绪变化。
停顿与重音:哪些词要强调,哪里需要短停顿,哪里不能连读。
分镜表达:每镜的语气、节奏、重读词、停顿点和结尾收束。
禁忌:不要广告腔、不要机器人腔、不要全程同一情绪、不要夸张吼叫。
试听策略:先用短句或第一镜试听;用户满意后再生成全片。
验收点:用户听完应觉得自然、像产品介绍、能听清价值和行动号召。

执行规则:

• 有用户录音时,先确认录音是否满足目标听感;不合适时提醒用户重录或改用发布级 TTS,不要静默继续。
• 使用火山豆包/OpenAI-compatible 等发布级 TTS 时,先展示配音导演确认单,得到用户确认后再生成正式音轨。调用付费 TTS 前仍要遵守成本/账号提示。
• 能用 provider 官方“语音指令/标签/SSML”时,只按官方文档已确认字段接入;字段未确认时,不要凭空编 API 参数。可先通过口播稿改写、标点、停顿和分镜逐段合成提升自然度。
• 对产品介绍视频,默认口径是“清晰、亲和、可信、有产品发布感”;开头略有悬念,痛点处更有共情,方案处稳定清楚,证明处放慢,CTA 处更有行动感。
• 配音生成后,仍要试听并让用户批准 voice_plan.json 或试听音频;用户说“不自然/情绪不对/声音变了”时,先调整配音导演稿或固定同一音色参数,不要直接进入画面。
• 配音试听后,必须给用户明确的反馈入口,例如:“如果满意,请说‘批准配音’;如果觉得太慢,请说‘压到 45 秒’;如果语气不对,请直接说‘更有激情一点 / 更像产品发布 / 更亲切 / CTA 更有号召力’。”不要只问“可以吗”。

画面三审必须是导演分镜确认单

画面三审不是让用户确认“旁白对应一个镜头”,而是确认“这一镜到底会看到什么、怎么动、怎么转场、字幕如何避让、声音如何配合”。没有导演分镜确认单,不要进入画面生成或批准 visuals。

出现位置:

• visual_plan.json 生成后、调用 lj approve visuals 前,必须立刻在对话里完整展开导演分镜确认单。
• 可以同时给 [visual_plan.json](绝对路径) 可点击链接,但链接只能作为补充,不能替代正文展示。
• 不能只给镜头文件路径、不能只说“请打开 visual_plan.json 查看”、不能只摘要成“画面/动效/转场/音效”。如果没有在聊天里完整展示确认单,就不得询问或执行“批准画面分镜”。
• 如果用户直接说“批准画面分镜”,但此前本轮还没有展示完整确认单,必须先停下补展示,再让用户确认一次;不能把这句话直接当作有效审批。
• 普通用户界面里默认展示“压缩但具体”的分镜确认单,不要只让用户打开 director_review_sheet.md。每次先展示全片风格锁:整体色调、主色/辅助色/背景色、字体/材质、明暗与运动气质。每镜至少展示:镜头目标/口播、画面会看到什么、素材策略与状态、构图、动效关键帧、转场、字幕、音效、批准前要看什么。完整长版仍保留在 director_review_sheet.md 和 visual_plan.json 里,链接只能作补充。
• 对话展示可以比完整 Markdown 短,但不能空泛。不要只写“动态图形 + 转场 + 字幕”,也不能把素材、构图、转场、音效压到文档里不展示;不要把 13 个字段逐字堆满屏。目标是让普通用户不打开文件也能判断每一镜是否拍对、是否需要补素材、是否可以批准。

参考 HyperFrames / motion-graphics 的成熟做法,灵剪画面三审必须遵守:

• Asset-first:先判断这一镜需要真实素材、界面录屏、动态图形、数据可视化、产品画面还是抽象动效;没有素材时先说明要生成/补齐什么,不能用静态图片或模板闪动凑数。
• Layout before animation:先锁主体区、文字区、底部字幕安全区、平台 UI 避让区、视觉焦点,再决定动画;主体、CTA 和字幕不能互相遮挡。
• Beat planning:每镜至少有开场 / 中段 / 收束 3 个视觉 beat,标清大致时间点和变化,不能入场后冻结。
• Motion variety:相邻镜头不得同版式、同运动、同节奏;全片要在统一风格下切换 kinetic title、界面滑入、数据聚焦、分屏对比、卡片展开、深度推近等不同视觉蓝图。
• Reuse-first, not template-loop:可复用 HyperFrames/Remotion 的成熟 block、caption、chart、callout、transition 能力,但不能只换文字循环同一个模板。
• Design system lock:色彩、字体语气、光影、描边、圆角、材质、空间留白必须统一;“酷炫”来自运动设计和视觉层次,不是随机闪光、图标堆砌和无意义特效。
• Keyframe evidence:每镜生成规格要能落到关键帧/状态变化,例如 0.0s 主体出现、1.2s 数据增长、3.0s 卡片翻转、结尾留 CTA;不能只写“动态展示”。
• Audio-aware motion:转场不要切在词中;BGM 比人声低 16dB;必要时标注点击音、提示音、数据增长音、转场 whoosh,但音效不能抢口播。
• Inspect and repair:渲染后要用 ffprobe、抽帧和 render_manifest 检查真实运动、字幕安全区、对比度、模板复用和静态图;不达标先修,不能用 LLM 自评放行。

每一镜给用户看的“导演分镜确认单”至少包含:

镜头目标:这一镜承担 Hook / 痛点 / 方案 / 证明 / CTA 哪个叙事功能。
画面内容:具体出现什么主体、场景、产品/界面/数据/人物/素材。
素材策略:使用用户视频、宿主生成视频、界面录屏、动态图形或待补素材;图片只能作参考。
构图与焦点:主体位置、视觉焦点、前中后景、底部字幕和平台 UI 避让。
视觉元素:短标题、数据、图标、按钮、箭头、界面卡片、背景材质;哪些必须出现,哪些禁止。
动效与镜头运动:主运动、次运动、镜头推进/横移/缩放/遮罩/视差/卡片展开等。
关键帧节奏:按时间点列开场、中段、结尾状态,确保全时长都有发展。
转场设计:入场、出场、与前后镜头衔接方式,避免无意义闪白和乱跳。
字幕策略:底部安全区、每行字数、拆句、字号、描边/底色/遮罩、主体避让。
颜色与氛围:主色、辅助色、明暗、质感、统一 style_lock。
音乐与音效:BGM 情绪、提示音/点击音/转场音、音量关系。
禁止项:静态图放几秒、Ken Burns 冒充视频、模板循环、大段文字复读旁白、中心字幕遮挡主体。
验收点:用户看这一镜时应该能判断哪些东西必须生成出来。

这份确认单要用人话展示给用户,不要直接甩 JSON。展示给用户时必须完整列出上述所有核心项,不得简化成“画面/动效/转场/音效”等少数摘要项,也不得省略素材策略、构图焦点、关键帧、字幕策略、色彩氛围、禁止项和验收点。用户批准后,同一内容再写入 visual_plan.json 的结构化字段,供 HyperFrames/Remotion/外部生成器执行与 QA 复核。

展示格式要求:

• 每镜都要单独编号,并完整列出:镜头目标、画面内容、素材策略、构图与焦点、视觉元素、动效与镜头运动、关键帧节奏、转场设计、字幕策略、颜色与氛围、音乐与音效、禁止项、验收点。
• 每镜下面必须给一个清晰的“这一镜批准前你要看什么”结论。
• 最后再给用户反馈入口:“批准画面分镜 / 修改某一镜 / 补充素材 / 重做分镜”。不要只问“可以吗”。
• 对话里的普通用户展示版可以合并字段,推荐先给 4-6 行全片风格锁,再每镜 5-7 行:目标与口播、画面与构图、素材策略与状态、动效关键帧、转场/字幕/音效、批准前检查。若用户要求“展开/更细”,再按镜头补齐完整字段;若用户只想快速审阅,不要把完整长版硬塞到对话里。

visual_plan.json 中的权威用户审阅入口是 director_review_sheet_v2.scenes[]。每镜还必须包含 asset_diagnosis,明确素材状态、是否可作为发布级动态视频、下一步补齐动作。若 asset_diagnosis_summary.non_publish_grade_count > 0,给用户只展示 asset_diagnosis_summary.single_next_action_zh 作为当前最短动作,不要同时抛出一堆插件/key/素材选项。

P1 起,visual_plan.json 还必须包含 director_knowledge_base_v1 与 director_router_summary。每镜要展示 engine_policy、route_reason、asset_strategy_v2、expected_real_evidence、director_knowledge_refs 和 caption_contract,让用户能看懂这一镜为什么用 HyperFrames/Remotion/用户视频/待补素材,以及需要哪些真实证据画面。普通用户不需要手选引擎;宿主 agent 只把路由理由和缺口动作讲清楚。

Director Router 不能只写好看的解释字段。每镜 engine_policy.generator、engine_policy.selected_engine 必须和实际 generator/素材类型一致:HyperFrames 镜头就是 hyperframes,Remotion 镜头就是 remotion,用户动态视频就是 user_video,图片/缺素材就是 needs_video_asset 或参考素材。不要为了通过审核把 Router 文案改成发布级,但实际仍走图片、fallback 或其它生成器;--release --strict 会阻断这种不一致。

如果某镜路由到 Remotion,必须先向用户说明 Node/Chrome Headless 与 Remotion 商用 license 边界,并在用户确认后把 engine_policy.license_confirmation.status=confirmed 或等价确认字段写入产物。只写”Remotion 需要 license”不够;--release --strict 会阻断未确认 license 的 Remotion 镜头。

视频生产硬约束(测量不假设 · 每关可审)

踩坑固化的硬规则,违反即返工。核心一句:别把”我设了这个值”当成”这件事发生了”。

测量,不假设

• 一切时间点从素材测出来,不许估:配音停顿用 silencedetect 测、卡点用 whisper 逐字对齐测、音效接触点从源片逐帧测。字数估切点必错。
• 量的必须是”最终信号”,不是中间量:音效响不响,按成片真实增益后量(不是量原始文件);响度按成片 loudnorm 复测。
• 别用同义反复验证自己:在 T 放一个事件、又去 T 查它,永远通过——这不是验证。检查器和修复器不能共用同一个判断;换一把尺子,或直接读产物确认。
• 别给没想清楚的概念硬造数字当门禁:只有用户耳朵/眼睛验过的判据才配当硬门;自造指标先降级成提示,不许拦路一部要发布的片子。

改一半 = 没改

• 改了引用的一处,必须改另一处:改了片段名要改音效映射表、改了裁切要改文件名。”改了一半,另一半留在原地,然后拿着'我改过了'的印象往下走”是反复翻车的根因。
• 用对账门(断言)锁死:产物里每个镜头都要在映射表里、每个裁切窗口里必须真有声音、一个事件不许被两张表重复上声。断言失败即停,不放行。