lingjian-video

lingjian (lingjian-video) general-purpose Agent publish-ready short-video Skill

lingjian is a general-purpose publish-ready Chinese short-video production Skill that can run in any AI Agent capable of running commands (via lj CLI). The user only states the goal and provides copy/materials/recording or authorization; the host agent is responsible for installing dependencies, detecting and inheriting capabilities, guiding the completion of publish-ready TTS and visual capabilities, and then orchestrating "materials → script → voiceover → visuals → bottom subtitles → rendering → QA → export." The CLI is the underlying execution engine, not the primary entry point for ordinary users.

Honest premise: lingjian only guarantees that the process is reproducible and the gates are auditable; it does not promise finished-video quality or "viral hits."

lingjian's exclusive differentiation (its lifeblood, don't lose it)

The market's AI video "one-sentence video generation" is a black box: roll the dice once, spit out one video, and you can't change it. lingjian is the opposite—one sentence in, and script / storyboard / voiceover / visuals / music / subtitles / sound effects are all automatic,but every gate can be reviewed. Five differentiators; lose any one and lingjian degenerates into just another black box:

Blueprint first:A film is governed by a single blueprint running through the whole film (energy curve + motif + the artifacts and gates for each gate), rather than each shot doing its own thing. (Note: automatically generating the whole-film energy curve from pipeline artifacts is still being integrated into the mainline; the current CLI does not yet produce it automatically, so do not claim to users that it is already fully automatically generated.)
Local director console (director-board):Each gate opens on the local machine localhost a readable, interactive director board that lays out this gate's candidates item by item for the user to see. See the red lines in the next section.
Research throughout:Research is not only at the beginning; it continues at every gate—absorb top-tier evidence → internalize the baseline → drive the output; if it fails, supplement it rather than making do.
Gate confirmation, give candidates rather than yes/no:At each gate, do not ask "is this okay"; instead, give candidates for the user to choose from and modify, and only proceed to the next gate after the user nods.
Auditable:Each gate's artifacts, gates, and evidence are traceable and reviewable (results.json + report + evidence log); gates are bound to artifacts, and content changes automatically invalidate them.

Local director console (director-board) · hard rules

The console = a local machine service, never remote. Each gate's director board opens only at localhost / local static service (within the repository director-board/ within render.js + board.schema.json + standalone.html)。nevertreat any cloud / deployment / tunnel / development-debug address (vercel, trycloudflare, ngrok, the author's private preview page, etc.) as the user console for display, and never write it into any user-facing or externally published artifact. Every step the user takes opens, on the right, a page on their own machine.
Data contract:Each gate produces something conforming to board.schema.json the board.json(meta + shots[], each shot energy/script/signature/beats/transitions), and the renderer displays shot by shot + a shot-by-shot "confirm" button;handle.allConfirmed() only when all are green is it allowed to proceed to the next gate.
The same renderer cuts across every gate:The style gate / script gate / voiceover gate / visual gate only change meta Copy and card fields are reused; do not rewrite them for each level.
Determinism: disabled Date.now / not seeded random, the storyboard can be reproduced; pure native JS + SVG, no third-party libraries, no network requests (except reading local data).

Ordinary User Workflow Guidelines (Highest Priority)

Do not dump CLI, provider matrices, JSON, or environment variable blocks on ordinary users. The host agent handles installation, detection, running commands, and interpreting results; users only need to state goals, confirm content, drag in assets/recordings, or authorize.
Have the user do only one shortest action at a time. Do not present a pile of choices at once; first inherit and detect automatically according to default priority, and only ask about what is missing.
The fixed release-level shortest path is: install/initialize → capability checkup → fill required resources → script review → voice audition/selection → voice director confirmation → voice audition review → visual review → render → QA → export.
Use capabilities that can be automatically inherited directly; when they cannot be inherited, first ask the user whether they have existing resources. For voice, first ask for the user's recorded voiceover audio; only when there is no recording guide them to enable one recommended TTS. For visuals, first ask for real video assets for each shot or a true video generation plugin; do not treat images, template motion effects, or single-image loops as release-level visuals.
When release-level capabilities are missing, you must stop and use one plain sentence to explain what is missing and what the user needs to provide next. Do not continue generating a low-quality release, and do not call a sample a publishable final cut.
Address users with actions like “Please drag in the voiceover audio,” “Please drag in the video asset for each shot,” or “I'll help you check whether the host plugin is available”; do not make users understand doctor --json、export VOLCENGINE_... or provider configuration details themselves.
When showing local files, review artifacts, audio, video, screenshots, export packages, or evidence logs to users, you must use clickable Markdown file links and absolute paths; include line numbers when necessary. Do not give only relative paths or plain-text paths. Example:[voice_plan.json](/Users/.../artifacts/voice_plan.json)、[full.wav](/Users/.../artifacts/voice_segments/full.wav)。
When the user has no recording, by default guide them through only one Chinese release-level TTS path: open the Volcano Doubao new console activation page https://console.volcengine.com/speech/new/setting/activate?projectName=default to activate the service/claim the promotion, then open the API Key management page https://console.volcengine.com/speech/new/setting/apikeys?projectName=default to create an API Key. Ordinary users only need the API Key; use Lingjian defaults for Resource ID and Voice Type, and do not make users find the old APP ID, Access Token, Cluster ID, or Voice Type.
After the user gets the API Key, give one standard save command for their system (docs/ONBOARDING.md is the only standard, copy it verbatim): on macOS use security to save it in Keychain, on Linux use secret-tool to save it in Secret Service (both service = account = lingjian:<NAME>, the prefix cannot be omitted, otherwise Lingjian cannot read it), on Windows useuser environment variable(SetEnvironmentVariable(...,"User") or current session $env:). After saving, Lingjian automatically injects on startup (inject_stored_credentials read back), no need to manually export each time. Use the command withsingle stty -echo+IFS= read -r read-in (do not use security -w confirm twice, pasting a long key twice will definitely report passwords don't match), when pasting without echo, clearly state “it is normal that you cannot see the characters.” You must state “paste the original text directly, do not add double quotes, and do not send it to chat”; the key only goes into local secure storage, is not uploaded, and does not connect to the internet.
The user-facing entry point exposes only one Chinese sentence and two optional convergence parameters:--style controls the unified style,--profile controls the platform + audience preset. Do not make users pile up a bunch of aspect ratio, pacing, subtitle, and BGM flags; by default use --style clean_product --profile douyin_product。
Available style:4 implemented style libraries(For the full methodology, see styles/<key>.md)——vox_cut(Vox editorial silhouette · orange-black halftone),dark_keynote(dark-scene launch · epic),cinematic(realistic cinematic feel · Chinese-style humanities),neue_sachlichkeit(New Objectivity · physical archive); plus a general convergence preset clean_product、bold_news、warm_lifestyle、tech_minimal。After choosing a style, you must read styles/<key>.md use its palette/typography/texture/animation/prompt constraints to guide Seedance/image generation, don't just treat it as a label. Switching styles = reusing cross-cutting capabilities, reskinning and rearranging, not redoing. Available profile: product_intro、open_source_project_intro、tutorial_guide、review_comparison、ecommerce_sales、knowledge_explainer、douyin_product、xiaohongshu_life、shipinhao_knowledge. These only converge the director contract and prompts; they do not promise a viral hit.
For the content type Profile, the required_evidence must enter every shot's director storyboard confirmation sheet,visual_plan.json、render_manifest.json and QA; it cannot remain only in prompts or documents.--release --strict Under this, when the materials/evidence required by the Profile do not enter each shot's expected_real_evidence / asset_strategy_v2 , it must block.

Video requirements clarification stage (must be done first)

When an ordinary user triggers Lingjian for the first time, first collect the minimum requirements in plain language; do not directly enter provider, CLI, JSON, or environment variable explanations. The following 7 items must be confirmed:

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

Execution rules:

When the user has already provided all this information, do not repeat the questions; first restate it as a clear production goal, then enter the capability consultation.
When the user only gives the platform, do not silently infer Douyin/Xiaohongshu as 9:16 by default and continue. You must first let the user choose the aspect ratio: 9:16, 16:9, 3:4, 4:3, 1:1; you may explain the platform-recommended default, and only when the user does not choose may you use the default and state it clearly in the goal confirmation.
When the user only gives a topic and no content basis, do not directly make up a complete script. You must first ask the user, "What content should this video be based on?" and have the user provide whichever is most convenient: a one-sentence description, Markdown, PDF, PPT, Word, web link, GitHub repository, product introduction copy, existing script, or screenshot. Only when the user authorizes use of the current repository/README/GitHub link may it be used as the content basis.
After the user confirms the content basis, first ingest/extract or read that content, then enter script generation. You must not use model common sense to make up product details, feature boundaries, pricing, licensing, or effect promises for the user.
When the user lacks video materials, do not directly run publication-grade generation. You must first break down from the script a list of "what real dynamic video materials/generated assets are needed for each shot," then have the user provide materials, authorize the host agent to collect screenshots/screen recordings of the target object on their behalf, or enable a real video generation plugin in the host agent. Screenshots/screen recordings must only capture content of the target object, such as the current project README, Skill, CLI, QA, export package, Codex operations, or terminal output; when the current screen is involved, privacy safety must first be confirmed, and if the user does not authorize it, you may only provide the fallback of manually importing mp4.
When an open-source project introduction needs terminal/QA/export package evidence, the host agent may run on behalf of the user lj ingest command --command ... save the command output as terminal text evidence within the project; this is only terminal replay material, not screen recording. If the user/host has already configured LINGJIAN_TERMINAL_RECORD_CLI, you may add --record to capture a real terminal screen recording; if it is not configured or fails, you must truthfully notify the user and must not fake a screen recording. For Codex operation screen recording, you may use lj ingest codex --scene-id ...; by default it only logs the screen recording task and will not record the current screen. Only after the user confirms that the current screen can be recorded and contains no private content may you add --allow-screen-recording to trigger macOS screencapture or LINGJIAN_CODEX_RECORD_CLI; if screen recording fails or cannot be verified, it still must not be faked as captured.
When a user gap is playing audio, first check whether a publish-level TTS key already exists; only if not, guide them along one recommended path. Do not offer multiple TTS choices at the same time.
When a publish-level TTS key already exists, do not hide which voice is being used. First generate 5 short auditions based on the provider's genuinely available voices, by default prioritizing 2 female voices + 3 male voices, and let the user choose one; if the list cannot be fetched or the account permissions are insufficient, only show voices that have actually passed synthesis, and do not fabricate the "top 5 popular" or unplayable options. If the current account has only actually synthesized 1 voice successfully, you must explicitly say "the current account has only 1 verified available voice", and show the voice name,voice_id and the audition file.
Before the user selects a voice or confirms using a recording, you must show the "voice director confirmation sheet" and have the user confirm the tone, emotion, speaking rate, pauses, stress, and the expression approach for each shot. Before the user approves, do not formally call paid/publish-level TTS to generate the full-film voiceover.
Only have the user fill one shortest action at a time. For example, solve the voiceover first, then the visuals; do not press all gaps on the user at once.

Content input guidance script:

接下来先确定内容依据。你可以直接给我:
1. 一段文字/Markdown;
2. 一个网页或 GitHub 链接;
3. PDF、PPT、Word 文档;
4. 已有脚本/产品介绍/截图。

如果你只是给了主题,我会先问你是否允许我使用当前仓库 README / GitHub 页面作为依据,确认后再写脚本。

The three reviews of voiceover must include a tone and emotion confirmation sheet

Voiceover is not "pick a voice and generate directly". After the script is approved and before formally calling publish-level TTS or connecting the user's recording, you must first show the user the "voice director confirmation sheet". This step is mandatory and cannot be omitted.

For each video, confirm at least:

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

Execution rules:

When there is a user recording, first confirm whether the recording meets the target listening feel; if it is not suitable, remind the user to re-record or switch to publish-level TTS, and do not silently continue.
When using publish-level TTS such as Volcano Doubao/OpenAI-compatible, first show the voice director confirmation sheet, and after obtaining the user's confirmation, generate the formal audio track. Before calling paid TTS, still comply with the cost/account prompts.
When the provider's official "voice instructions/tags/SSML" can be used, integrate only according to fields confirmed in the official documentation; when fields are unconfirmed, do not invent API parameters out of thin air. You may first improve naturalness through rewriting the spoken script, punctuation, pauses, and segment-by-segment synthesis according to the storyboard.
For product introduction videos, the default tone is "clear, friendly, trustworthy, with a product-launch feel"; a slight suspense at the beginning, more empathy at the pain points, stable and clear at the solution, slower at the proof, and more of a sense of action at the CTA.
After the voiceover is generated, you must still audition it and have the user approve voice_plan.json or the audition audio; when the user says "unnatural / wrong emotion / the voice changed", first adjust the voice director's script or fix the same voice parameters, and do not go directly into the visuals.
After the voiceover audition, you must give the user a clear feedback entry point, for example: "If you are satisfied, please say 'approve voiceover'; if you think it is too slow, please say 'compress to 45 seconds'; if the tone is wrong, please directly say 'make it more passionate / more like a product launch / friendlier / more rousing CTA'." Do not just ask "is it okay".

The three reviews of visuals must be a director storyboard confirmation sheet

The three reviews of visuals are not about having the user confirm "the narration corresponds to a shot", but about confirming "what exactly will be seen in this shot, how it moves, how it transitions, how the subtitles avoid it, and how the sound cooperates". Without a director storyboard confirmation sheet, do not enter visual generation or approve visuals.

Occurrence position:

visual_plan.json After generation and before calling lj approve visuals , you must immediately fully expand the director storyboard confirmation sheet in the conversation.
You may simultaneously provide [visual_plan.json](绝对路径) clickable links, but links can only serve as a supplement and cannot replace display in the main text.
You must not only give the shot file path, must not only say "please open visual_plan.json to view", and must not only summarize it as "visuals/motion/transitions/sound effects". If the complete confirmation sheet has not been fully displayed in the chat, you must not ask about or execute "approve the visual storyboard".
If the user directly says "approve the visual storyboard", but the complete confirmation sheet has not yet been displayed in this round, you must first stop and display it, then have the user confirm once more; you must not treat this sentence directly as valid approval.
In the ordinary user interface, display a "compressed but specific" storyboard confirmation sheet by default; do not only have the user open director_review_sheet.md. Each time, first display the full-film style lock: overall color tone, primary/secondary/background colors, fonts/materials, light-dark and motion temperament. For each shot, display at least: shot goal/voiceover, what will be seen on screen, asset strategy and status, composition, motion keyframes, transitions, subtitles, sound effects, and what to check before approval. The complete long version is still kept in director_review_sheet.md and visual_plan.json ; links can only be supplementary.
The chat display can be shorter than the full Markdown, but it must not be vague. Do not only write "motion graphics + transitions + subtitles", and do not compress assets, composition, transitions, and sound effects into a document without displaying them; do not pile all 13 fields verbatim onto the screen. The goal is to let ordinary users judge, without opening files, whether each shot is shot correctly, whether assets need to be supplemented, and whether it can be approved.

Referring to the mature practices of HyperFrames / motion-graphics, Lingjian's three visual reviews must comply with:

Asset-first: first determine whether this shot needs real assets, interface screen recording, motion graphics, data visualization, product footage, or abstract motion effects; when there are no assets, first explain what needs to be generated/supplemented, and do not pad the count with static images or template flickering.
Layout before animation: first lock the main subject area, text area, bottom subtitle safe area, platform UI avoidance area, and visual focus, then decide on animation; the subject, CTA, and subtitles must not obscure one another.
Beat planning: each shot must have at least 3 visual beats: opening / middle / closing, clearly marking the approximate time points and changes; it must not freeze after entering.
Motion variety: adjacent shots must not have the same layout, same motion, and same rhythm; the whole film must switch among different visual blueprints such as kinetic title, interface slide-in, data focus, split-screen comparison, card expansion, and deep push-in under a unified style.
Reuse-first, not template-loop: mature blocks, caption, chart, callout, and transition capabilities from HyperFrames/Remotion may be reused, but you must not just change the text and loop the same template.
Design system lock: color, font tone, light and shadow, strokes, rounded corners, materials, and spatial whitespace must be unified; "cool" comes from motion design and visual hierarchy, not random flashing, icon piling, and meaningless effects.
Keyframe evidence: the generation specification for each shot must be able to land on keyframes/state changes, for example 0.0s subject appears, 1.2s data grows, 3.0s card flips, ending leaves CTA; do not only write "dynamic display".
Audio-aware motion: transitions must not cut in the middle of a word; BGM is 16dB lower than the voice; when necessary, mark click sounds, notification sounds, data growth sounds, and transition whooshes, but sound effects must not overpower the voiceover.
Inspect and repair: after rendering, use ffprobe, frame extraction, and render_manifest to check real motion, subtitle safe area, contrast, template reuse, and static images; if they do not meet the standard, fix them first, and do not let LLM self-evaluation pass them.

The "director's storyboard confirmation sheet" shown to the user for each shot must contain at least:

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

This confirmation sheet must be presented to the user in plain language, not by dumping raw JSON. When presenting to the user, all of the above core items must be listed in full, and must not be simplified into a few summary items such as "visuals/motion/transitions/sound effects", nor may the material strategy, composition focus, keyframes, subtitle strategy, color atmosphere, prohibitions, and acceptance points be omitted. After the user approves, the same content is then written into visual_plan.json structured fields for HyperFrames/Remotion/external generators to execute and for QA review.

Display format requirements:

Each shot must be numbered separately and list in full: shot goal, visual content, material strategy, composition and focus, visual elements, motion and camera movement, keyframe rhythm, transition design, subtitle strategy, color and atmosphere, music and sound effects, prohibitions, and acceptance points.
Below each shot, a clear "what you need to look at before approving this shot" conclusion must be provided.
Finally, give the user a feedback entry point: "Approve storyboard / Revise a shot / Add materials / Redo storyboard". Do not just ask "Is this okay?".
In conversation, the ordinary-user display version may merge fields. It is recommended to first give 4-6 lines of whole-film style lock, then 5-7 lines per shot: goal and voiceover, visuals and composition, material strategy and status, motion keyframes, transitions/subtitles/sound effects, pre-approval check. If the user asks to "expand/more detail", then fill in the complete fields per shot; if the user only wants a quick review, do not force the full long version into the conversation.

visual_plan.json The authoritative user review entry point in director_review_sheet_v2.scenes[]. Each shot must also include asset_diagnosis, clarifying material status, whether it can serve as a publish-grade dynamic video, and the next completion action. If asset_diagnosis_summary.non_publish_grade_count > 0, show the user only asset_diagnosis_summary.single_next_action_zh as the current shortest action, and do not simultaneously throw out a pile of plugin/key/material options.

From P1 onward,visual_plan.json must also include director_knowledge_base_v1 and director_router_summary. Each shot must display engine_policy、route_reason、asset_strategy_v2、expected_real_evidence、director_knowledge_refs and caption_contract, so the user can understand why this shot uses HyperFrames/Remotion/user video/materials to be added, and what real evidence footage is needed. Ordinary users do not need to manually choose the engine; the host agent only needs to explain the routing rationale and gap actions clearly.

Director Router must not only write good-looking explanatory fields. Each shot's engine_policy.generator、engine_policy.selected_engine must be consistent with the actual generator/material type: a HyperFrames shot is hyperframes, a Remotion shot is remotion, user dynamic video is user_video, images/missing materials are needs_video_asset or reference materials. Do not change the Router copy to publish-grade just to pass review while it actually still uses images, fallback, or another generator;--release --strict will block this inconsistency.

If a shot is routed to Remotion, you must first explain to the user the boundaries of Node/Chrome Headless and the Remotion commercial license, and after user confirmation write engine_policy.license_confirmation.status=confirmed or an equivalent confirmation field into the artifact. Writing only "Remotion requires a license" is not enough;--release --strict will block Remotion shots with unconfirmed licenses.

Hard constraints for video production (measure, do not assume · auditable at every gate)

Hard rules hardened from pitfalls; violation means rework. The core sentence:Do not treat "I set this value" as "this thing happened".

Measure, do not assume

All time points must be measured from the material, not estimated: voiceover pauses are measured with silencedetect , beat points are measured with whisper word-by-word alignment, and sound-effect contact points are measured frame by frame from the source footage. Estimating cut points by word count will definitely be wrong.
What is measured must be the "final signal", not an intermediate quantity: whether a sound effect is loud is measured according to the real gain after the final cut (not by measuring the original file); loudness is measured according to the final cut's loudnorm Re-test.
Don't verify yourself with tautology: place an event at T, then go look it up at T — it always passes — that's not verification. The checker and the fixer must not share the same judgment; switch to a different ruler, or read the artifact directly to confirm.
Don't force-invent numbers for concepts you haven't thought through and use them as gates: only criteria verified by the user's ears/eyes deserve to be hard gates; self-invented metrics should first be downgraded to hints, and must not block a film that's about to be released.

Half-changed = not changed

If you change one place that's referenced, you must change the other: change a clip name and you must change the SFX mapping table; change a crop and you must change the filename. "Changed half, left the other half in place, then carried on with the impression that 'I already changed it'" is the root cause of repeated crashes.
Lock it down with reconciliation gates (assertions): every shot in the artifact must be in the mapping table, every crop window must actually contain sound, and one event must not be given sound twice by two tables. Assertion failure means stop; do not let it through.

Audio

Synthesize the voiceover as one continuous whole in a single pass; sentence-by-sentence splicing is forbidden: independent per-sentence synthesis + per-sentence speed change then splicing = choppy pitch shifts; rhythm comes from the text + natural intonation + picture beat points, and duration is measured by silencedetect reverse-test.
No-narration mode (for films in the new objectivism vein and similar, where "the author exits and lets the object speak for itself"):lj run/voice --no-voiceover — do not synthesize voiceover; text cards (on_screen_text) take over the narration's narrative role, shot duration is set by the text card reading time, and audio = BGM + SFX (if neither exists, a pure silent base track). QA recognizes voiceover=false does not require real voiceover, and subtitles recognize text cards. Suitable for styles like physical archives / cyanotypes where "the demonstration doesn't argue" — don't force narration in.
Timbre must be screened using a full-text listen-through; you cannot extrapolate from two short sentences. AI can't hear, so it has no business screening timbre on the user's behalf.
Subtitles = the voiceover's original text word for word, not one word omitted, and with no punctuation at all (use spaces to break); the picture must echo the objects mentioned in the narration.
SFX library files often "cram a dozen independent events into one file" — don't treat them as one continuous sound to cut; if a "loud—quiet—loud" appears in the crop window, you've cut into two events, redo it. If there's nothing suitable, don't force it in (better to have none than something unsuitable).
BGM stays at a fixed low volume as a bed; avoid ducking pumping that causes it to swell and shrink; coexistence with SFX relies on carving out frequency-band notches, not on one giving way to the other. No dynamic compression at the final stage (it would push back the tall transients).
Hard standard for finished-film loudness:overall loudness −14 LUFS, true peak ≤ −1 dBTP(common to Douyin / Bilibili / YouTube); dialogue is the main body, normalized to −14~−16 LUFS, and when there is voice, the BGM (music bed) is pushed toabout 15–20dB below the dialogue(voice effortless, music perceptible but not masking the words).
★Hard continuity rule (music + voiceover; move it and it breaks apart): music keeps a fixed volume and fixed rhythm throughout, and absolutely never changes volume or rhythm with emotion / section — no sidechain, no ducking, no "breathing", no mid-way tempo change or track swap. Emotional matching relies only on "choosing a track with suitable emotion + aligning its own climax with the picture's climax (time alignment)", not on moving volume or rhythm. Same for voiceover: synthesized as one whole in a single pass, fixed baseline speaking rate, natural intonation, absolutely no per-sentence speed changes / per-sentence tuning. When there is no voice at the head and tail of the film, the music is naturally clearer — that's the natural result of a fixed bed, not actively raising or lowering it.
Music/SFX sources: royalty-free BGM/SFX obtained from Pixabay (SFX require no attribution) — Pixabay has no public music/SFX API, so the host agent uses browser capabilities (Chrome use / computer use) to search by emotion and download, or the user brings their own audio. After obtaining the files, run them through lj ingest audio --kind bgm(or --kind sfx)Mount and render auto-mixing (BGM defaults to 16dB below vocals). The BGM's character is chosen by the user through audition; do not decide it on your own.

Visuals (video-first, not webpages/PPT)

The Seedance first frame determines success or failure: whether the action can be completed is determined by the geometry of the first frame — if the first frame locks in the unavoidable physical constraints (e.g., the blade passing vertically through the thing to be cut), the model has no room to make things up; just writing a fierce prompt won't work.
Real video as the mainstay + code-based graphics overlays: where Seedance should be used to generate real video, don't make do with single-image motion effects; use code for text/precise graphics, and leave vitality/atmosphere to video generation.
Each shot's video must be ≥ the voiceover duration; if it's not enough, pad with a freeze on the final frame (tpad), don't use -shortest to cut off the audio tail.
For ready-made real materials, prioritize searching for and downloading from real sources and cite the source (logos/products/historical materials); don't have AI generate them out of thin air; only generate images to fill in when you truly can't find them. Don't be overly anxious about copyright (public brand assets can be used as long as the source is cited).
Image generation capability lives in Codex (built-in Image gen); Lingjian itself does not generate images, it only consumes the produced PNGs as references/sample frames. Cross-agent invocation paradigm:Codex hostUse the built-in image generation directly;non-Codex hosts (Claude / Gemini / Cursor, etc.) invoke Codex via CLI for image generation —— codex exec -s workspace-write --skip-git-repo-check "用生图能力生成<画面描述>,保存为 <路径>.png"(the images for this project's sample video were all generated this way inside Claude). Pre-check the environment for codex CLI availability (lj setup codex_cli already detected); for Chinese subject matter, lock in East Asian faces + strict era, leave blank space on covers/keyframes for titles, and compose according to the target aspect ratio.
Hands are not off-limits: if you need human action, shoot the hands head-on and clearly; the only red line is not letting "hands without a body" float into the frame out of nowhere.
Restrained aesthetics, don't gild the lily: external effects like glows/halos/particles are not added by default — the wow factor comes from composition, lighting, rhythm, and texture themselves; graphic annotations only mark verifiable true facts, not "looks technical" gibberish (pretending to have a scholarly feel is the same disease as a blade not matching the fracture).
Division of labor between rendering engines (each plays to its strengths, not either-or):HyperFrames is the main force for visual execution(HTML+CSS+GSAP, agent-generation friendly, Apache-2.0 free at any scale, covering typography/subtitles/graphics/big text/3D (Three.js)/GPU (TypeGPU)/Lottie/data-driven batching/cloud rendering);Remotion plays to its unique strengths——<Player> real-time parameter-tuning preview within the webpage (feeding Lingjian's "console real-time display"), mature AWS Lambda large-scale cloud rendering, React data-driven personalized batching.Remotion is source-available; for-profit use with >3 people requires payment: shots routed to Remotion must first pass a license confirmation gate (see the mainline workflow,--release --strict blocks unconfirmed ones); the compliance approach (free for ≤3 people / license verification / treating it as the output of an independent pipeline as material) is decided by the user.
Delivery pitfalls (must follow): embedded browser block video(autoplay / multiple <video> switching all fail) → the final film must ffmpeg be server-side composited into a single mp4 for embedded playback; don't throw multiple video tags at the frontend.

Solidified capabilities = hard constraints (must invoke `capabilities/`, not a reference decoration)

Lingjian's differentiating core lies in capabilities/; the host agent must at every stepinvokethem, not treat them as optional references — otherwise it degenerates into yet another "one-click black box":

sound effects must follow capabilities/sfx-strategy/SFX_STRATEGY.md Five iron rules + 21 action→sound-effect mapping table: each sound effect corresponds to a clear on-screen action (motivated); if no corresponding on-screen action can be found,delete; fast-paced cuts are shortened to remove trailing tails, climaxes keep a lingering aftertaste,gentle endings don't need low-frequency trailing tails; follow-along soft sounds don't steal from the voiceover; volume relies onfixed gainlayering (no sidechain / no ducking); timing uses cadence for precise beat-syncing. ★The sound-effect mp3 library is not packaged with the release repo (it comes from the hyperframes-media skill); users need to provide their own royalty-free mp3s, or use sfx_mix.py <full.mp4> <hits.json> <out.mp4> <你的音效目录>(the 4th positional argument specifies the sound-effect directory), see SFX_STRATEGY.md"Library source".
Transitions must pass through capabilities/transition-library content matcher (match.js: recommends transitions based on adjacent-shot energy difference ΔE + semantics + motif + style) + scarcity guard(strong transitions default to ≤3 for the whole film; over-quota ones are automatically downgraded to invisible hard cuts / match cuts); anti-cheap guardrails (90% invisible hard cuts, flash-white/flash-black ≤3 times per second). Default is hard cuts; strong transitions are used only at 2–3 energy inflection points.
Beat-syncing On-screen word slams/reveals/sound effects must use capabilities/cadence/cadence.py(silencedetect measures voiceover pauses→speech segment start points,noise=-30dB d=0.05): on-screen event start must never be earlier thanthe corresponding word start point (can be −0.05~0.1s to let accelerated segments come earlier, with the peak pressing exactly on the word). The main line voice_plan.voice_cadence is already automatically measured by the same logic.
Layout Subtitles/large-text layout follows capabilities/layout-safety/TYPOGRAPHY_RULES.md, preventing large text from pressing on labels, going out of bounds, and other glyph-level overflow that inspect cannot catch.
Console For each stage's candidates use lj console <项目> [--gate auto/voice/script/board] --json to start the local director board: it automatically generates candidate pages based on the current stage (voiceover stage = voice cards + player; script/storyboard stage =render.js energy curve board + per-shot confirmation), prints http://127.0.0.1:<port>/, the host agent opens it in the browser on the right, and the user confirms item by item (written back to console_state.json)。Don't dump candidates into the conversation as files anymore —— use the console (see the red lines above). These capabilities are fully ratio-agnostic and style-agnostic: changing ratio/changing style meansreusing them with a new skin and rearrangement, not redoing them。

General rules

Don't generalize a single incident into a permanent ban: models are improving, and hardcoded capability assumptions will expire (e.g., early on "AI-generated hands will break" → now it's not a problem, and "banning hands" again would actually be wrong). Red lines should be narrow and aimed at the real failure modes.

When to use / when not applicable

Suitable for: given copy/links/images and wanting to make a vertical short video; wanting an auditable process with step-by-step approval; first producing a preview version (zero configuration) or a release version once real capabilities are available; exporting a distribution package. Not suitable / clarify first: wanting complex motion effects/timeline/template marketplace/AI image generation and video generation/digital humans (none of these are in M1); wanting "guaranteed to go viral" (not promised); only wanting to chat about operations and topic selection (not the core main line, can only be an explicitly marked optional follow-up).

Capability prerequisites and self-check (run first, don't assume)

The ordinary user path starts by talking with the host agent: first run lj setup and explain in plain language "already inherited / already available / must be filled in / optional enhancement".doctor --json Only for the host agent/audit script's internal judgment; don't let ordinary users directly interpret the JSON.

uv sync
uv run lj setup          # 能力仪表盘:优先继承已登录 CLI / 本机能力
uv run lj doctor --json  # 逐项体检;required 缺失时 exit code 非 0

lj setup prioritizes inheriting the already-logged-in official CLI (claude/codex as the LLM). For release-grade TTS, by default prioritize user recordings/cloud TTS; Kokoro/Piper Chinese local TTS counts only as zero-key sample audio, and macOS say and espeak-ng count only as preview-grade, none of which may masquerade as release-grade dubbing by default. Piper is a user-installed GPL local TTS; Lingjian only invokes it as a subprocess.
When doctor is not ready, do not proceed to release.
For the ordinary creator path, see docs/CREATOR_QUICKSTART.md; for capability boundaries, see docs/CAPABILITY_MATRIX.md。

Visual capabilities:

visuals generates a storyboard per scene, with fields including generator, visual_prompt, motion_spec, brief, expected_asset_path, duration_sec, asset_path, subtitle_burn.
Release-grade generator priority: hyperframes/remotion/external video generators -> user-asset video -> fallback_solid. image-gen produces only static reference images and cannot serve as a release-grade video capability.
The currently verified zero-key visual sample path is HyperFrames: when npx hyperframes is detected, lj generates mp4 per shot to expected_asset_paththrough a thin subprocess adapter; this only proves the dynamic sample workflow and cannot automatically count as release-grade visuals. Release-grade must use the user's real video assets per shot, or a host plugin/external generator that has been explicitly verified to generate content-relevant dynamic video assets. lj does not import or bundle the Remotion/HyperFrames SDK; it only delegates to the CLI or consumes assets written to disk and assembles them with FFmpeg.
If the host agent user has already installed/enabled HyperFrames/Remotion or another video generation plugin/skill, the host agent can follow the storyboard's visual_prompt and motion_spec to render richer per-shot video outputs to expected_asset_path; providing your own per-shot mp4/mov/m4v is the release-grade stable fallback. imagegen/images may only be used as samples/references. When a plugin is missing, first guide the user to install/enable it through the host agent's plugin/skill installation entry, or have the user provide video assets; only if it is still missing should you fall back to fallback_solid, and it may only be called a preview/placeholder.
Remotion may only be used as an opt-in precision executor; before enabling it, the user must confirm the license, and the confirmation must be written into engine_policy. Without confirmation, release-grade strict export cannot proceed.

Two modes:

Preview mode (zero config): --provider mock outputs script/dubbing, and render defaults to preview. Mock outputs are preview only and must not be treated as release quality.
Release mode (requires the minimal set to be complete): ① real LLM (inherit claude/codex, or OpenAI-compatible/key/CLI); ② user-recorded voiceover, cloud TTS, or a real TTS CLI confirmed by the user to be natural; ③ real dynamic video visuals (video assets output by HyperFrames/Remotion/external generators, or the user's per-shot mp4/mov/m4v); ④ FFmpeg/ffprobe with drawtext/libfreetype/AAC support; ⑤ Chinese subtitles within the bottom safe area. Kokoro/Piper/say/espeak-ng, static images, imagegen PNGs, fallback_solid, and built-in sample templates can only be preview/sample,--strict --release will block.

Real provider environment variables (read only from the environment, not written into artifacts/logs/release packages):

export LINGJIAN_LLM_CLI=your-llm-command
export LINGJIAN_TTS_CLI=your-tts-command
export OPENAI_BASE_URL=... OPENAI_API_KEY=... OPENAI_MODEL=...
export OPENAI_TTS_BASE_URL=... OPENAI_TTS_API_KEY=... OPENAI_TTS_MODEL=...
export VOLCENGINE_TTS_API_KEY=...

★ Script/content generation: host agent self-production takes priority (do not fork an external CLI)

Lingjian is a general-purpose agent skill, and the host agent (Claude / Codex / Gemini / Cursor…)is itself that LLM. For content such as scripts, narration, and storyboard copy that 「requires intelligent creation」,the first priority is for the host agent to produce it directly, then hand it to lj for structuring / validation / gating — do notuse --script-provider auto/claude/codex Go to the shell and call an external claude -p / codex exec subprocess. You are running inside Claude, and forking another headless claude is completely the wrong approach: an extra layer, prone to timeouts, and often fails due to not being logged in.

The LLM host (you yourself are an LLM) takes this path by default:

# 1) 导出创作契约(钩子库 / 风格锁 / 素材摘要),你按它创作,才对得上风格
uv run lj script ./projects/demo --type product --platform douyin --language zh-CN --ratio 9:16 --duration 45 --style vox_cut --profile product_intro --emit-contract --json
#    读 artifacts/script_contract.json → 你(宿主 agent)按顶级脚本方法论 + 契约,直接创作脚本
#    写成 {"scenes":[{"id":"s1","narration_text":"…"}, …]} 存成 authored.json
# 2) 回填(provider 记为 host_authored,非 mock)
uv run lj script ./projects/demo --type product --platform douyin --language zh-CN --ratio 9:16 --duration 45 --style vox_cut --profile product_intro --from-file authored.json --json

The aggregate command works the same way:lj run ... --script-provider host up to the script checkpoint willexport the contract and pause(status: awaiting_host_authoring), wait for your self-produced script --from-file to be filled back in, then continue lj run。

--script-provider auto/claude/codex/openai is reserved only for scenarios where "the host is not an LLM": only for pure automation / CI / being driven by non-intelligent programs, or when the host agent has no creative capability, should you delegate to an external LLM CLI or an OpenAI-compatible API as a fallback.mock only produces a placeholder skeleton, for preview only, and must not be treated as release quality.

Mainline workflow (by real commands)

The current CLI supports lj run aggregate commands. By default it stops at the three review checkpoints of script / voice / visuals; explicit --yes is only for CI or automatic approval explicitly authorized by the user. Add --json to all commands; the prefix is uniformly uv run lj; ⏸ is the three-review pause point, and you must stop and wait for user confirmation before approving.Script checkpoint: the LLM host follows the previous section's "host self-production" (--script-provider host or lj script --emit-contract/--from-file), do not fork an external CLI.

When showing the artifact to the user at each pause point, you must also provide a clickable file link. For example, for script review give [script.json](绝对路径), for voiceover review give [voice_plan.json](绝对路径) and [full.wav](绝对路径), for visual review give [visual_plan.json](绝对路径), and after export give [video.mp4](绝对路径) and the export package directory link.

uv run lj run ./projects/demo --name "演示项目" --input-file examples/product_intro_zh.txt --script-provider host --voice-provider auto --json
# ⏸ 审阅 artifacts/script.json 后:
uv run lj approve script ./projects/demo --approved-by '你的名字' --json
# ⏸ 先展示配音导演确认单:整体口播定位、语气情绪、语速、停顿、重音、每镜表达。用户确认后才生成正式配音。
uv run lj run ./projects/demo --json
# ⏸ 审阅 artifacts/voice_plan.json 后:
#   必须给用户三个反馈入口:批准配音 / 压到目标时长 / 调整语气情绪。
uv run lj approve voice ./projects/demo --approved-by '你的名字' --json
uv run lj run ./projects/demo --json
# ⏸ 审阅 artifacts/visual_plan.json 后:
uv run lj approve visuals ./projects/demo --approved-by '你的名字' --json
uv run lj run ./projects/demo --json

When actually producing content, the script checkpoint followsthe host's own LLM self-production(--script-provider host, see the "host self-production" section above), do not default to mock, and do not fork an external claude/codex CLI:

uv run lj run ./projects/demo --name "演示项目" --input-file examples/product_intro_zh.txt --script-provider host --voice-provider auto --json

If using Volcano Doubao TTS and the user has not yet chosen a voice,lj run you must first stop at the voice_options stage, generate artifacts/voice_options.json and the default 5 audition audio clips, prioritizing 2 female voices + 3 male voices. After the user auditions them, use the selected voice_id to continue the formal voiceover; do not hide the voices by default and synthesize directly. If there are actually fewer than 5 available auditions, clearly tell the user that the current account has only verified these available voices, and do not make it appear as though the system omitted other voices.

After the voice is selected, do not immediately generate the voiceover for the whole video. You must first generate a voiceover director confirmation sheet based on the script, listing in plain language the overall narration positioning, the tone and emotion for each shot, speaking rate, pauses, emphasis, and CTA expression; only after the user approves it should you call the formal TTS. If the user requests a "product introduction feel", by default adopt a clear, friendly, trustworthy expression with a product-launch feel, but still show it to the user for confirmation.

When there is already recorded voiceover audio:

uv run lj run ./projects/demo --name "演示项目" --input-file examples/product_intro_zh.txt --script-provider host --voice-audio-file narration.m4a --json

Command-by-command alternatives:

uv run lj setup && uv run lj doctor --json
uv run lj init ./projects/demo --name "演示项目" --json
uv run lj ingest text  ./projects/demo --file examples/product_intro_zh.txt --json
#   或 ingest url  ./projects/demo --url '粘贴网页链接' --screenshot --json
#   或 ingest command ./projects/demo --command "uv run lj doctor --json" --role terminal --json
#   或 ingest codex ./projects/demo --task "展示 lingjian-video 进入分镜三审" --json
#      默认只登记 Codex 操作录屏任务。确认当前屏幕可录且无隐私内容后,
#      才可加 --allow-screen-recording 触发 macOS screencapture 默认适配器或
#      LINGJIAN_CODEX_RECORD_CLI;也可手动拖入 mp4。只有 ffprobe 确认视频流后,
#      才会成为 Codex 操作录屏证据。失败时只记录任务,不伪造录屏。
#   或 ingest image ./projects/demo --file '图片文件路径' --role cover --json
uv run lj extract ./projects/demo --json
# LLM 宿主:--emit-contract 拿契约 → 自产 → --from-file 回填(见上「宿主自产」节);下行 mock 仅零配置预览
uv run lj script ./projects/demo --type product --platform douyin --language zh-CN --ratio 9:16 --duration 45 --provider mock --json
uv run lj approve script ./projects/demo --approved-by '你的名字' --json
uv run lj voice ./projects/demo --provider mock --voice test-voice --json
# 或者用用户录好的口播音频:
uv run lj voice ./projects/demo --provider auto --voice user --audio-file narration.m4a --json
uv run lj approve voice ./projects/demo --approved-by '你的名字' --json
uv run lj visuals ./projects/demo --engine ffmpeg_card --template product --json
# 审阅 artifacts/visual_plan.json:确认每镜 generator、visual_prompt、motion_spec、expected_asset_path。
# 宿主启用了 HyperFrames/Remotion/imagegen 时,按 expected_asset_path 生成 mp4 等动态视频资产;图片只可做样片/参考。缺宿主能力时先引导安装/启用插件或 skill,允许用户放自有视频素材,最后才回落卡片。
uv run lj approve visuals ./projects/demo --approved-by '你的名字' --json
uv run lj render ./projects/demo --platform douyin --language zh-CN --ratio 9:16 --json   # 发布档追加 --release
uv run lj qa ./projects/demo --json                                                       # 发布前:qa --release --platform douyin
uv run lj export ./projects/demo --platform douyin --language zh-CN --ratio 9:16 --json   # 全平台:--all-platforms;发布包:--release

Auxiliary: uv run lj status|reindex ./projects/demo --json; uv run lj credentials status|forget --json.

Platform parameters (honest): --platform is a free-form string. In M1, youtube additionally produces extra files such as thumbnails/descriptions/chapters; other platforms are exported with a generic structure. For vertical screens, --ratio 9:16 is commonly used.

Guardrails (hard rules, cannot be bypassed)

Do not bypass the approval gate: the three reviews must be approved before render; stop at the pause point, ask the user to confirm, and do not approve on the user's behalf.
mock cannot be released: mock artifacts are for preview only; --release requires a real LLM + real TTS and doctor ready.
If capability is missing, stop honestly: when doctor is not ready (FFmpeg without drawtext, no real TTS/LLM, etc.), do not force it, do not write fake artifacts, tell them what is missing, then stop.
Never write real keys into repositories/logs/export packages; doctor only outputs redacted status; do not echo the full key in conversations.
QA before release: when qa --release has hard_failures, do not export the release package.
Do not fake dynamic footage: when the host generator fails, the artifact does not exist, the same asset loops repeatedly, or only built-in sample templates are used, you must tell the user this is not release-grade real video; for strict release use --strict to block.
Do not fake release-grade voiceover: Kokoro/Piper/say/espeak-ng are sample/preview-grade real speech; for strict release use --strict to block and report RELEASE_AUDIO_IS_PREVIEW_VOICE. For commercial release, prefer user recordings or natural Chinese cloud TTS.
Do not force your way through when voiceover is missing: first guide the user to provide already-recorded spoken audio and use --voice-audio-file to integrate it; if there is no recording, then guide them to configure a release-grade TTS API. Kokoro can only be used for free sample previews.
Do not skip voice director confirmation: after the script is approved and before formal TTS generation, you must confirm tone and emotion, speaking rate, pauses, stress, and the expression for each shot; do not let the user spend TTS quota to generate the whole video just by choosing a voice.
Volcano Doubao TTS guidance must give the new direct entry points: first open https://console.volcengine.com/speech/new/setting/activate?projectName=default to activate the service/claim the promotion, then open https://console.volcengine.com/speech/new/setting/apikeys?projectName=default to create an API Key. Remind the user not to send the full key in chat; configure it only in the local environment VOLCENGINE_TTS_API_KEY。
Seedance text-to-video (when the user has no per-shot video material and wants AI dynamic footage) guidance: first open Volcano Ark "Activation Management" https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement and check only the required Seedance models (do not click select all);Seedance 2.0 series activation hard threshold = account balance > 200 yuan(official; if the balance is insufficient it reports BalanceNotEnough), the threshold is a reservation, not a charge, and after activation it is pay-as-you-go. Then open "API Key Management" https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey to create a Key (ARK keys are in UUID form, measured length 46, with no sk-/ak- prefix). After obtaining it, follow docs/ONBOARDING.md standard commands to store it in secure storage (service=account=lingjian:VOLCENGINE_ARK_API_KEY). Real human face reference images are prohibited; recognize the official Volcano Ark entry point, and do not download name-squatting repositories.
Volcano voice selection must be honest: use actual synthesis probing (trial synthesis voice by voice) to obtain the voices currently available to the account, and provide at most 5 previews; do not write old/unavailable voices as selectable options, and do not claim "officially popular" unless there is an official ranking basis.
Configure keys according to docs/ONBOARDING.md three-platform standard commands (service=account=lingjian:<NAME>, the prefix must not be omitted): macOS printf+stty -echo+IFS= read -r+security(do not use read -s -p, do not use -w twice for confirmation), Linux secret-tool store, Windows user environment variable/$env:. After storage, Lingjian automatically injects it at startup, with no need to manually export again.
Generation instructions for HyperFrames/Remotion must include deterministic rules: prohibit Date.now, unseeded random, use setTimeout for render timing, network requests during rendering,repeat:-1 infinite loops; use frame-driven or paused master timeline; fixed width/height/fps; subtitles overlaid last and located in the bottom safe area; 30ms fade in/out at cut points, do not cut in the middle of a word; BGM 16dB lower than the voice.

Honesty (must be followed)

Never fabricate artifacts/statistics/successful results: anything that has not actually been run may not be written as "completed".
Run real commands to verify, rather than looking at file existence: rely on the command --json return (ok/status/release_ready/exit code).
No promise of final video quality, no promise of viral hits: only a guarantee that the process is reproducible and the gates are auditable.
Capabilities are determined by doctor: the sole authority on whether it can be released is doctor's ready and each item's status.
Do not exaggerate parts that are not implemented (see below).

Do-NOT

Do not silently degrade to solid-color cards, static images, Ken Burns, single-image loops, or built-in sample templates and then continue to call it release-grade.
Do not silently switch a zero-key engine to a paid engine; before calling paid/account-based capabilities such as Volcano, fal, picsart, etc., first explain the cost/account prerequisites and obtain user confirmation.
Do not treat LLM self-evaluation as a quality gate. Release quality conclusions must come from real commands, render_manifest, ffprobe/frame extraction, and QA hard gate.
Do not describe say, fallback_solid, imagegen PNG, static images, or Kokoro/Piper sample audio as commercial release-grade results.
Do not bypass the three reviews, and do not approve the script/voiceover/visuals on the user's behalf.

Should / ShouldNot Trigger Examples

Should: "Use Lingjian to turn this copy into a 45-second Douyin e-commerce short video, with a clean product-explanation style."
Should: "Run lingjian-video; I have voiceover audio and per-shot video assets, please help me review the script, add subtitles, and export after QA."
Should: "Use --style tech_minimal --profile shipinhao_knowledge to make a knowledge-style vertical video."
ShouldNot: "Just generate me a video I can post; if assets are missing, use one image and animate it a bit." This must first explain the release-grade visual requirements.
ShouldNot: "No need for my confirmation, just enable paid generation for me." This must stop and have the user confirm the account and costs.

Known Boundaries (Inform the User Truthfully)

mock is preview only, not release quality.
HyperFrames/Remotion/imagegen are provided via delegation by the host agent or the local CLI; the Lingjian core does not build them in, does not bundle them, and does not import the SDK.
Host agent users can install/enable the HyperFrames/Remotion/imagegen plugin or skill; when missing, guide installation first, rather than directly treating the fallback as real visuals.
ffmpeg_card/fallback_solid is a fallback card path, not a dynamic visual quality promise.
Subscriptions usually do not include TTS; LLM can inherit claude/codex, while TTS generally requires local or separate configuration.
For Chinese commercial release TTS, the first choice is user recordings or Volcano Doubao, the second choice is OpenAI-compatible/other cloud TTS; Kokoro is the zero-key Chinese default and does not promise voice quality. Piper is a GPL user-installed path.
say is macOS only; espeak-ng is preview-grade local TTS and is not part of the release-grade minimum set.
The default Homebrew FFmpeg may lack drawtext; render --release will hard fail, and doctor is authoritative.
Local director console:lj console <项目> implemented (v1.1.0) — start local localhost service + automatically generate candidate pages for the current gate (voiceover gate = voice cards + inline player; script/storyboard gate =render.js energy curve director board + "confirm" for each shot) + /confirm write back to artifacts/console_state.json; the host agent opens the printed URL in the browser on the right, and the user confirms item by item. Renderer render.js + contract board.schema.json are released with the repository.Still in progress (do not claim it is done): visual gate (visual_plan.json) dedicated view, confirmation write-back automatically converting to lj approve、lj run automatically invoking console at each gate.apps/web(Next.js) is still a skeleton, not the current console path.
MCP is not yet implemented (packages/mcp_server only has a README), so MCP cannot be claimed as available externally.
Platform knowledge packages/viral algorithms are not core and can only serve as clearly labeled optional follow-ups.