Branch Video Script Builder

Build BranchVideo content as structured executable graphs and carry it through the full path:

• idea → node graph
• asset plan → produced asset URLs
• V3 JSON or AIHub import payload
• import into BranchVideo on bv.new.ndhy.com
• when the deliverable is a finished V3 script, save/publish it through branch-video-agent-cli and return a playable link

Companion skill

For project save, publish, version query, production status, or playUrl return, treat branch-video-agent-cli as the single source of truth.

• Do not duplicate its install policy, CLI command syntax, fallback strategy, or playUrl construction rules here.
• When the task reaches “create/update/publish this finished V3 script in BranchVideo”, immediately load branch-video-agent-cli and follow that skill for execution.
• If branch-video-agent-cli is not available in the current installed/local skills, install/add that skill first, then continue the handoff.
• Do not assume the agent already knows what branch-video-agent-cli means just because its name appears here; explicitly switch to that skill before execution.
• Keep this skill focused on graph authoring, asset mapping, import-shape correctness, and delivery handoff.
• If the task is only about script design or JSON generation, you do not need the CLI skill yet.

Quick workflow

1. Identify the requested target artifact first:
   • Playable BranchVideo v3 script JSON → read references/branch-video-v3-model.md
   • Need copyable node templates (avg, blank_fill, logic_chain, score_settlement, mask story_choice) → read references/authoring-examples.md
   • AIHub import / regeneration / conversion logic → read references/aihub-node-mapping.md
   • Asset production or import to site/editor → read references/asset-production-and-import.md
   • End-to-end delivery → read all relevant references above, then keep the final answer focused on the requested deliverable
2. Turn the idea into a graph:
   • define entry, key beats, endings
   • define player actions and branch targets
   • define variables/items/cards/resources up front
3. Fill asset gaps deliberately:
   • decide which media must exist before the script is usable
   • produce or request asset URLs through AIHub workflows on https://bv.new.ndhy.com/api/agent/aihub
   • wire outputs back into V3 assets.* or AIHub node interaction.config
4. Choose the import path:
   • Direct authored V3 JSON → hand off to branch-video-agent-cli to create/save/publish a BranchVideo project and return playUrl
   • AIHub 3-layer payload (global_context / script_body / result_script) → use AIHub import path
5. Validate IDs, reachability, asset refs, fallbacks, and importability before claiming done.

Operating rules

• Treat the script as an execution graph: nodes, triggers, actions, resources, state changes.
• Prefer small deterministic nodes over giant overloaded nodes.
• Keep IDs stable and machine-friendly: start_1, A1_1, A1_1_loop, A1_1_choice, end_1.
• Every interactive node needs explicit success/failure/default behavior.
• Always provide a reachable end path.
• Do not invent unsupported runtime or importer features. If a requested mechanic is not represented by the current schema, say so and propose the nearest supported pattern.
• Do not treat asset production as separate fluff. Missing assets are often the difference between a valid script and an unusable one.

Runtime/editor support vs AIHub import support

Do not mix these up.

Runtime/editor-supported interaction families

The project runtime/editor supports these interactive types:

• story_choice
• single_choice
• multi_choice
• judge
• blank_fill
• input_fill
• logic_chain
• external
• score_settlement
• voice exists in enums but is not fully implemented in the current UI path

Current AIHub import coverage

aiHubConvert.ts currently converts these source node types into V3 nodes:

• AIGC视频
• AIGC视频按钮决策
• 视频物件选择
• AVG立绘对话
• 结算评价
• 其他：AI自生成互动
• 选词填空

If the user asks how this repo constructs scripts, anchor the explanation in the conversion pipeline above. If the user asks to author a new gameplay script directly, you may use the richer V3 runtime model directly.

Asset production policy

When the requested script lacks usable media:

• derive an explicit asset list first: background videos, loop videos, mask images, background stills, character art, speech audio, BGM, settlement media
• prefer generating assets through the AIHub workflow gateway on bv.new.ndhy.com
• keep token handling out of the skill body; assume environment-based auth
• map every produced URL back into a concrete field:
  • V3 authored scripts → assets.videos/images/audios/speeches
  • AIHub import payloads → source node interaction.config.* fields like video_url, loop_video_url, mask_image, scene_background
• if a workflow returns temporary URLs, say so and recommend stable storage/upload if the project needs permanence

Import policy

Support both import modes.

Mode A — direct V3 project import

Use when you already have a V3 script object and want it editable in BranchVideo.

Default Agent flow:

1. finalize the V3 script object in this skill
2. ensure branch-video-agent-cli skill is available; if not, install/add it first
3. load branch-video-agent-cli
4. use branch-video-agent-cli to project create or project update
5. if the script should be playable immediately, use version publish
6. return at least projectId, version, and playUrl

Conceptual API equivalent:

1. POST /api/branch-video
2. PUT /api/branch-video/:id with script, optional productionData, basePublishedVersion
3. optionally POST /api/branch-video/:id/publish

Use the API-equivalent notes above only to understand backend shape. For actual Agent execution in repeated workflows, prefer the CLI companion skill instead of hand-assembling HTTP requests here.

Mode B — AIHub payload import

Use when you have:

• global_context_str
• script_body_str
• result_script_str
• workflow_run_id

Then import through:

• POST /api/branch-video/import/aihub
• host/domain: bv.new.ndhy.com

This path creates or overwrites a public project/v1 snapshot according to the backend import rules.

Current note:

• branch-video-agent-cli is the preferred execution path for direct V3 create/update/publish.
• The AIHub 3-layer importer above is still a separate import path; do not pretend it is currently replaced by the CLI skill unless that CLI skill is explicitly expanded to cover it.

Default deliverable shape

Unless the user asks for raw JSON only, structure the answer like this:

1. 目标交付物
   • V3 脚本 / AIHub 导入包 / 资产生产计划 / 导入操作说明
2. 玩法结构摘要
   • premise
   • player goal
   • core branches
   • fail/win endings
3. 资产清单
   • required assets
   • generation workflow suggestions
   • resulting field mapping
4. 节点设计表
   • node id
   • node type
   • purpose
   • trigger / interaction
   • next targets
   • state updates
5. Script artifact
   • V3 JSON snippet, patch, full object, or AIHub import payload
6. Import/run instructions
   • for V3 scripts: instruct the agent to ensure branch-video-agent-cli is installed/available, then load it, execute create/update/publish, and return playUrl
   • for AIHub import payloads: exact endpoint or UI path on bv.new.ndhy.com
7. Validation checklist
   • asset refs exist
   • entry node valid
   • every branch has target/fallback
   • split-node cases handled when relevant
   • end path reachable

Required checks before finalizing

Always check:

• graph.entryNodeId exists in graph.nodes
• every goto target exists
• every assetRef exists in the correct asset bucket
• every interaction option/blank/chain item uses stable IDs
• fallback.onTimeout and fallback.onDefault are defined for interactions
• variable/item/card references exist in resources
• split-node patterns are preserved when using imported AIHub source
• import mode matches artifact shape:
  • V3 JSON should not be shoved into the AIHub 3-layer importer
  • AIHub source payload should not be described as if it were already final V3 runtime JSON
• when using advanced authored interactions (avg, blank_fill, logic_chain, score_settlement, mask choice), prefer templates from references/authoring-examples.md instead of inventing field shapes from memory
• if you are not fully certain about a when expression, say so explicitly and mark it as a high-confidence template pending live runtime verification

High-value pitfalls

• AIGC视频按钮决策 may split into {nid} + {nid}_loop
• 视频物件选择 may split into {nid} + {nid}_choice
• node regeneration works at the original result_script node granularity, not arbitrary split child nodes
• imported AIHub source has three related layers: Global_Context, Script_Body, result_script; if one changes, dependent layers must stay consistent
• branchConfig and interaction branches are different mechanisms; choose the one that matches the node/event style
• 选词填空 import becomes runtime blank_fill
• web interactions route through message triggers and messageMapping
• generated media URLs are useless unless they are actually mapped into the script or import payload
• direct V3 import and AIHub import are two different paths; do not mix request bodies
• for direct V3 delivery, avoid copying CLI install/command details from memory; invoke branch-video-agent-cli as the companion execution skill instead

When to load references

• Load references/branch-video-v3-model.md when building or editing V3 script JSON directly.
• Load references/authoring-examples.md when you need copyable node templates for authored runtime JSON, especially avg, blank_fill, logic_chain, score_settlement, or mask-based story_choice.
• Load references/aihub-node-mapping.md when explaining the existing project pipeline, converting AIHub output, or handling node regeneration/import behavior.
• Load references/asset-production-and-import.md when the task involves missing media assets, AIHub workflow asset generation, importing the final result into BranchVideo on bv.new.ndhy.com, or needing concrete API request examples.
• Load branch-video-agent-cli when the task has crossed from “author the script” into “create/update/publish the BranchVideo project and return a playable link”.
• If branch-video-agent-cli is not installed/available yet, install/add that skill first, then switch to it instead of improvising the publish flow here.

Response style

Be concrete. Prefer:

• actual node IDs
• actual trigger/branch examples
• explicit variable updates
• explicit fallback behavior
• explicit asset field mappings
• explicit import endpoint or page path
• explicit handoff to branch-video-agent-cli when the deliverable is ready for project create/update/publish
• explicit note when the companion skill must be installed/added before the handoff can happen
• minimal request bodies when recommending API-based import/save flows
• a short “confidence note” when some live runtime field shape may still need verification

Avoid vague advice like “add some branches”, “generate some assets”, or “import it into the platform”. Translate ideas into graph-ready structures and runnable/importable steps.