@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/motioncraft/references/qa.md

@@ -1,53 +0,0 @@
-# QA
-
-Nothing goes to the user until all of these pass.
-
-## 1. Automatic checks
-
-```bash
-node <skill-dir>/scripts/motioncraft.mjs qa overlap --comp Main
-node <skill-dir>/scripts/motioncraft.mjs qa all out/final.mp4 --comp Main --maxMb 16
-node <skill-dir>/scripts/motioncraft.mjs qa pixels out/final.mp4 --board storyboard.json --dir .
-```
-
-`qa overlap` flags only registered debug boxes and cannot prove that the final pixels are collision-free. `qa pixels` samples the actual exported video at scene starts, ends and preview frames, makes a contact sheet, and runs heuristic OCR checks for tiny or cropped text. Inspect every flagged frame at full size and a phone-sized version, then watch the full video.
-
-`qa overlap` renders the composition in debug mode at 1/4 size. Every `McBox kind="text"` is painted light red, every `McBox kind="block"` light green, and the content is hidden. It then scans every frame:
-
-| Flag | Meaning | Usual fix |
-|---|---|---|
-| `textOverlapPx` | two text boxes stacked (dark red) | put them in different zones, exit the old one first, shorten the text |
-| `blockOverlapPx` | two cards stacked (dark green) | spread them out, or stagger their entry/exit |
-| `textInMarginPx` | text inside the safe margin | move it in, reduce size, or reduce camera zoom in that range |
-
-Screenshots of each problem range land in `out/qa-overlap/`. During the debug pass, scene crossfades switch at the midpoint, so the intended blurred crossfade is not reported. A sticker that is meant to sit on a card can use `allowOverlap`, but use it rarely.
-
-Only boxes wrapped in `McBox` are checked. If you add a new text element, wrap it.
-
-`qa all` also checks:
-- file: size limit, audio stream present, audio and video length match
-- audio: -14 LUFS (±1), true peak <= -1 dBTP, no long silences
-- sheet: 24 frames tiled into `out/qa/sheet.jpg`
-
-## 2. Look at it yourself
-
-Open the sheet and at least 3 full-size frames. Check:
-
-- [ ] One focus per frame. Your eye knows where to look within half a second.
-- [ ] Headline readable at phone size (h1 >= 64 px at 1080p).
-- [ ] At most one accent word per sentence.
-- [ ] Nothing cut off at the edges, nothing hidden behind platform UI (9:16: bottom 20%, right 12%).
-- [ ] No leftover placeholder text, lorem, or "Example data" credits.
-- [ ] Numbers and names match the research sources.
-- [ ] Every third-party logo/screenshot has a credit.
-
-## 3. Listen
-
-- [ ] Every name and brand word is said correctly (read the word timings, then listen to those spots).
-- [ ] Music never covers the voice.
-- [ ] Big visual moments land on a beat or the drop.
-- [ ] SFX are sparse; no sound without a visual reason.
-
-## 4. Watch once at full speed
-
-Anything that feels rushed, dead, or jumpy gets fixed before sending. Holds should be at least `0.8 s + 0.25 s per word`.

package/skills/motioncraft/references/reference-analysis.md

@@ -1,37 +0,0 @@
-# Reference analysis
-
-Use this when the user sends a video and says "make it like this".
-
-```bash
-node <skill-dir>/scripts/motioncraft.mjs ref get <url-or-file> --dir ref   # downloads with yt-dlp, or copies a local file
-node <skill-dir>/scripts/motioncraft.mjs ref report --dir ref               # writes ref/ref_report.md
-node <skill-dir>/scripts/motioncraft.mjs ref text --dir ref                 # optional, needs tesseract
-```
-
-If yt-dlp is missing or the site blocks it, ask the user to download the video and pass the file.
-
-## What the report gives you and how to use it
-
-| Report part | Read it as | Turn it into |
-|---|---|---|
-| Cuts (times) | pace. Many cuts per minute = energetic | `--energy` knob, scene lengths |
-| Motion per second | how much moves on screen | `--energy`, camera `still/smooth/active` |
-| Palette | background, ink, accent colors | `color` tokens (keep one accent) |
-| Music: BPM, key, LUFS, drop | tempo and where the peak is | `music make --bpm --drop`, pick a preset with a similar feel |
-| Contact sheet | layout, type, density, 3D or flat | zones, font level choice, `--density`, `--depth` |
-
-The key estimate is rough; treat it as a hint. BPM and loudness are reliable.
-
-## Also look yourself
-
-Open the contact sheet and a few frames and write down in plain words:
-
-- How text enters (blur, slide, type-on, scale)
-- How many words are on screen at once
-- Font feel (geometric sans, serif, mono) - find a free font with that feel
-- What the hero visuals are (UI mockups, 3D objects, photos, icons)
-- How scenes change (cut, crossfade, camera move)
-
-## Copy the feel, not the video
-
-Never reuse the reference's footage, logos, music, or exact layouts. Build the same *feel* with the style tokens and your own content. If you want to show part of the reference on screen (for example in a "look at this" moment), credit it with `<Credit>`.

package/skills/narrator-ai-cli/SKILL.md

@@ -1,256 +0,0 @@
----
-name: narrator-ai-cli
-description: "narrator-ai-cli — AI Video Narration CLI Skill: the method the original skill taught, run as an AICUT film — pages that draw any moment t, cut on tracks. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "NarratorAI-Studio/narrator-ai-cli-skill"
----
-
-# narrator-ai-cli — AI Video Narration CLI Skill
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-CLI client for [Narrator AI](https://openapi.jieshuo.cn) video narration API. Designed for AI agents and developers.
-
-- **CLI repo**: https://github.com/NarratorAI-Studio/narrator-ai-cli
-- **Resources preview** (BGM / dubbing / templates): https://ceex7z9m67.feishu.cn/wiki/WLPnwBysairenFkZDbicZOfKnbc
-
-## Reference Index
-
-This file covers decision flow, the common workflow, and pointers. Detailed lookups live in `references/`:
-
-| Topic | File |
-|---|---|
-| Resource selection (material / BGM / dubbing / templates) — list commands, response formats, field mapping | `references/resources.md` |
-| Full workflow steps with parameter tables and JSON examples (Fast Path + Standard Path) | `references/workflows.md` |
-| Magic Video — optional visual template step (catalog, params, language rules) | `references/magic-video.md` |
-| Polling pattern, task types, file ops, user account, error codes | `references/operations.md` |
-
-## Pipeline at a Glance
-
-```
-┌─── Fast Path (原创文案, cheaper) ───┐
-                    │   fast-writing → fast-clip-data     │
-  Source material ──┤              ↓                      ├──→ video-composing ──→ (magic-video)
-  (material list /  │   [video-composing keys off         │   final MP4 URL       optional visual
-   search-movie /   │    fast-clip-data.task_order_num]   │                        template pass
-   file upload)     └─────────────────────────────────────┘
-                    ┌─── Standard Path (二创文案) ────────┐
-                    │   popular-learning → generate-      │
-                    │   writing → clip-data               │
-                    │              ↓                      │
-                    │   [video-composing keys off         │
-                    │    generate-writing.task_order_num] │
-                    └─────────────────────────────────────┘
-```
-
-## Agent Rules (mandatory — apply across all steps)
-
-> **Always:**
-> - **Confirm before acting.** Every resource (source, BGM, dubbing, template) and every `magic-video` submission requires explicit user approval. Never auto-select, never auto-submit.
-> - **Source data, never invent.** Construct `confirmed_movie_json` from `material list` fields or `task search-movie` output. If neither yields it, ask the user — do not fabricate.
-> - **Honor the language chain.** The dubbing voice's language defines the writing task `language` param AND every `magic-video` text param. All three must match. → `references/magic-video.md` § Language Awareness
-> - **Paginate `material list` to exhaustion, search programmatically.** Fetch all pages until `total` is consumed, then `grep -i` or `python3 -c` on the JSON. Never trust truncated terminal display.
-> - **Poll with the canonical `while` loop at 5-second intervals.** Never use a fixed-iteration `for` loop. → `references/operations.md` § Task Polling
->
-> **Never:**
-> - **Submit `magic-video` without showing the full request body** (templates + every `template_params` value) and getting user confirmation. The cost is 30 pts/minute and irreversible.
-> - **Submit Chinese default values for `magic-video` text params when narration language is non-Chinese.** The defaults are hardcoded Chinese and will appear as Chinese text in a non-Chinese video.
-> - **Submit `.task_id` (32-char hex) as `order_num`.** Downstream tasks want `.task_order_num` (the prefixed string like `generate_writing_xxxxx`), not `.task_id`. Submitting the hex returns `10001 任务关联记录数据异常`. The other look-alike — `.results.order_info.order_num` (`script_xxxxx`) — is also wrong; see `references/operations.md` § Task Query Response Shape.
-> - **Auto-switch paths after a failure.** If a step fails, surface the error to the user and ask explicitly: retry the same path, switch to the other path, or abort. Never infer a path switch on the agent's own initiative.
-
-## Prerequisites
-
-This skill assumes the `narrator-ai-cli` binary is installed and configured with a valid `NARRATOR_APP_KEY`. See [README.md`README.md` for install / setup. Agents can verify with `narrator-ai-cli user balance`.
-
-## Core Concepts
-
-| Concept | Description |
-|---|---|
-| **file_id** | 32-char hex string for uploaded files. Via `file upload` or task results |
-| **task_id** | 32-char hex string returned on task creation. Poll with `task query` |
-| **task_order_num** | Assigned after task creation. Used as `order_num` for downstream tasks |
-| **files[]** | Output files in the completed task response (flat, top-level array). Each entry has `file_id`, `file_path`, `suffix`. Read `.files[0].file_id` for the next step's input |
-| **learning_model_id** | Narration style model — from a pre-built template (90+) or `popular-learning` result |
-| **learning_srt** | Reference SRT file_id. **Mutually exclusive** with `learning_model_id` |
-
-## Conversation Initiation
-
-> ⚠️ **Agent behavior — first message of a session**: Before asking the user for a movie title or workflow path, **proactively orient them** about what the skill offers. Most users assume they need to upload their own video + SRT and don't realize a pre-built material library ships with the skill. Skipping this step often results in unnecessary uploads or aborted sessions.
-
-**Required opening (adapt to the conversation language):**
-
-1. **Lead with the pre-built material library.** Mention upfront that ~100 ready-to-use movies are available with video + SRT already loaded — no upload needed in most cases.
-2. **Offer three concrete entry points** (let the user pick one):
-   - "I have a specific movie in mind" → take the title, search materials first, fall back to `task search-movie` only if not found
-   - "Show me what's available" → run `material list --json` and present 5–8 titles spanning varied genres; offer to filter by genre on request
-   - "I'll upload my own video + SRT" → guide through `file upload`
-3. **Defer the Fast vs Standard path question** until source material is confirmed. Asking both at once forces a decision the user has no context for yet.
-4. **Optionally share the visual resources preview link** (BGM / dubbing / templates browsable visually): https://ceex7z9m67.feishu.cn/wiki/WLPnwBysairenFkZDbicZOfKnbc — but only if the user wants to browse, not as a wall of links upfront.
-
-**Example opening (Chinese conversation):**
-
-> 你好，欢迎使用 AI 解说大师。这个技能可以帮你生成电影/短剧解说视频。我这边内置了约 100 部电影素材（视频 + 字幕都是现成的），所以大多数情况你**不需要自己上传任何文件**。
->
-> 你想怎么开始？
-> 1. **直接告诉我片名** — 我先查内置素材库，没有再去外部搜
-> 2. **让我列一些内置素材** — 你可以按类型挑（喜剧 / 动作 / 悬疑 / 科幻…）
-> 3. **自己上传视频 + 字幕** — 我引导你完成上传流程
-
-After source material is confirmed, walk the user through the **decision sequence below — one question per turn, in order**. Do NOT collapse multiple decisions into one message; users cannot reason about `target_mode` before they've picked a path.
-
-**Decision sequence** (each step waits for explicit user confirmation):
-
-1. **Source material** — covered above.
-2. **Workflow path** — Fast (原创文案) or Standard (二创文案). See "Two Workflow Paths" below.
-3. **`target_mode`** — *only ask if path = Fast*. Choose mode 1 / 2 / 3 (see "Fast Path internal: `target_mode`" below). If path = Standard, **skip this question entirely** — Standard Path has no `target_mode`.
-4. **BGM** → **Dubbing voice** → **Narration template** — see "Resource Selection Protocol".
-
-> ⚠️ **Anti-pattern (do NOT do this)**:
-> Asking "① 解说模式 (纯解说/原声混剪) ② 制作路线 (快速/标准)" in the same message.
-> `纯解说` and `原声混剪` are **Fast Path internal modes** (target_mode 1 vs 2). They do not exist in Standard Path. Asking them alongside the path choice forces the user to make decisions in the wrong order and conflates two layers of the decision tree.
-
-## Two Workflow Paths
-
-Two end-to-end paths produce a finished narrated video. Choose with the user before starting.
-
-| | **Fast Path** (原创文案, recommended) | **Standard Path** (二创文案) |
-|---|---|---|
-| Pipeline | material → fast-writing → fast-clip-data → video-composing → magic-video* | material → popular-learning** → generate-writing → clip-data → video-composing → magic-video* |
-| Cost / speed | Faster, cheaper | Higher quality narration |
-| When to use | Default unless user wants adapted-style narration | When user wants narration learned from a reference style |
-
-\* magic-video is optional; only on explicit user request.
-\*\* popular-learning is skippable when using a pre-built template (recommended).
-
-> ⚠️ **Path is a standalone decision** — ask the user "Fast or Standard?" by itself, in its own message. Do not auto-select. Do not bundle it with `target_mode` or any other follow-up question.
->
-> ⚠️ **Path choice is per-movie, evaluated fresh each time.** If the user switched paths for a previous movie in the same session (e.g. from Fast to Standard due to a failure), that choice has no bearing on the current movie. Always ask the path question anew for each new movie — do not carry over or infer the prior session's path.
-
-### Fast Path internal: `target_mode` (ask only after path=Fast is confirmed)
-
-> Skip this section entirely if the user picked Standard Path — `target_mode` only exists inside fast-writing.
-
-| Mode | Use when | Required input |
-|---|---|---|
-| `"1"` 热门影视 (纯解说) | Known movie, narration from plot only | `confirmed_movie_json`; **no `episodes_data`** |
-| `"2"` 原声混剪 (Original Mix) | Known movie + you have its SRT | `confirmed_movie_json` + `episodes_data[{srt_oss_key, num}]` |
-| `"3"` 冷门/新剧 (New Drama) | Obscure/new content | `episodes_data[{srt_oss_key, num}]`; `confirmed_movie_json` optional |
-
-## Resource Selection Protocol
-
-Before any task, gather these resources **in this order, with explicit user confirmation at each step**:
-
-1. **Source files** (video + SRT) — from `material list` or via `file upload`
-2. **BGM** — from `bgm list`
-3. **Dubbing voice** — from `dubbing list`
-4. **Narration style template** — from `task narration-styles`
-
-Detailed list commands, response shapes, and field mappings live in `references/resources.md`.
-
-> ⚠️ **Universal rules — apply at every resource step:**
-> 1. **Pre-filter by context.** Use the per-resource filter flag where supported: `bgm list --search`, `dubbing list --lang`, `task narration-styles --genre`. **`material list` does NOT accept these flags** — paginate the JSON and search programmatically with `grep -i` / `python3 -c`.
-> 2. **Default presentation: 5–8 options** with the resource ID and key descriptive fields.
-> 3. **If the user has no preference**: present **3 recommendations** with a one-line reason for each. Still wait for confirmation.
-> 4. **Confirm one resource at a time.** Do not advance until the current one is confirmed.
-
-> ⚠️ **Dubbing → writing `language` mismatch check**: if the user pre-specified a `language` value that conflicts with the chosen voice, surface the mismatch and ask before proceeding. (The general language-chain rule lives in Agent Rules above.)
-
-## Fast Path — High-Level Flow
-
-> Detailed parameter tables, all `target_mode` cases, and full JSON examples live in `references/workflows.md`.
-
-**Step 0 — Find source material & determine `target_mode`:**
-
-1. List materials: `narrator-ai-cli material list --json --page 1 --size 100`. Search programmatically with `grep -i` or `python3 -c` on the JSON output — do **NOT** rely on the terminal display (may be truncated). Paginate (`--page 2`, etc.) until exhausted if `total > 100`.
-2. **Found in materials** → ask user: pure narration (`target_mode=1`) or original mix (`target_mode=2`)? Construct `confirmed_movie_json` from material fields (mapping in `references/resources.md`).
-3. **Not found, known title** → `task search-movie "<name>" --json` → `target_mode=1` (or `target_mode=2` if user uploads SRT). May take 60+ seconds (Gradio backend, results cached 24h).
-4. **Obscure / new content** → `target_mode=3` with user's uploaded SRT. `confirmed_movie_json` optional.
-
-**Step 1 — fast-writing**: pass `learning_model_id`, `target_mode`, `playlet_name`, `confirmed_movie_json` and/or `episodes_data`, `model` (pricing: 纯解说文案 `flash` 5pts/1k-chars or `pro` 15pts/1k-chars; 原片混剪解说文案 `flash` 12pts/1k-chars or `pro` 40pts/1k-chars). Save `task_id` from the **creation response**, then poll until top-level `.status=2` and save `.files[0].file_id` from the completed task.
-
-**Step 2 — fast-clip-data**: pass `task_id` + `file_id` from Step 1, plus `bgm`, `dubbing`, `dubbing_type`, and `episodes_data` with `video_oss_key` / `srt_oss_key` / `negative_oss_key`. Poll until top-level `.status=2`; read top-level `.task_order_num` from the response.
-
-**Step 3 — video-composing**: pass `order_num: <.task_order_num from Step 2>` only. Poll → `.results.tasks[0].video_url` is the finished MP4.
-
-**Step 4 (optional) — magic-video**: only on explicit user request. See `references/magic-video.md`.
-
-## Standard Path — High-Level Flow
-
-> Detailed parameter tables and JSON examples live in `references/workflows.md`.
-
-**Step 0 — Source material**: same material/upload flow as Fast Path. Use `video_file_id` as `video_oss_key` and `negative_oss_key`, and `srt_file_id` as `srt_oss_key` in `episodes_data`.
-
-**Step 1 — popular-learning** (skip if using a pre-built template): pass `video_srt_path`, `narrator_type`, `model_version`. Poll until top-level `.status=2`, then parse `.results.tasks[0].task_result` JSON → `agent_unique_code` is the `learning_model_id`. Or use a pre-built template `id` from `task narration-styles --json` directly.
-
-**Step 2 — generate-writing**: pass `learning_model_id`, `playlet_name`, `playlet_num`, `episodes_data`, plus three additional required fields — `target_platform` (e.g. `"douyin"`), `vendor_requirements` (`""` if none), and `target_character_name` (`""` if not applicable). Omitting any of these returns `10001 ... Field required`. Full param table in `references/workflows.md`. Save `task_id` from the creation response.
-
-**Step 3 — clip-data**: pass `order_num` (= top-level `.task_order_num` from Step 2's polled task record, e.g. `generate_writing_xxxxx`), plus `bgm`, `dubbing`, `dubbing_type`. ⚠️ **Different from Fast Path's fast-clip-data**, which takes `task_id` — clip-data takes `order_num` instead. Poll until top-level `.status=2` (required prerequisite for Step 4) — but **do not** use clip-data's own `task_order_num` for video-composing; Step 4 keys off `generate-writing`'s instead.
-
-**Step 4 — video-composing**: pass `order_num` + `bgm` + `dubbing` + `dubbing_type` (all four required — re-pass the BGM/voice values from Step 3; the API does not inherit them, and submitting only `order_num` returns `10001 查询解说工程任务结果失败`). ⚠️ **Standard Path keys off `generate-writing`'s `task_order_num`** (`generate_writing_xxxxx`), **NOT** clip-data's. clip-data must reach top-level `.status=2` first as a prerequisite, but its own `task_order_num` (`generate_clip_data_xxxxx`) returns `10001 任务关联记录信息缺失` when submitted. This is opposite to Fast Path (where fast-clip-data is the right anchor) — see Important Notes #4. Poll → `.results.tasks[0].video_url` is the finished MP4.
-
-**Step 5 (optional) — magic-video**: only on explicit user request. See `references/magic-video.md`.
-
-## Standalone Tasks
-
-# Voice clone — input audio_file_id, returns voice_id
-narrator-ai-cli task create voice-clone --json -d '{"audio_file_id": "<file_id>"}'
-
-# Text to speech — input voice_id + audio_text
-narrator-ai-cli task create tts --json -d '{"voice_id": "<voice_id>", "audio_text": "Text to speak"}'
-```
-Both accept optional `clone_model` (default: `pro`).
-```
-
-## Important Notes
-
-1. **`confirmed_movie_json` is required** for `target_mode=1` and `2`, optional for `3`. Construct from material fields when found in pre-built materials; use `search-movie` otherwise.
-2. **`file_id` always comes from `file list` or `material list`.** Never guess.
-3. **`search-movie` may take 60+ seconds** (Gradio backend, results cached 24h).
-4. **`video-composing.order_num` is path-asymmetric** — which upstream task's `task_order_num` to use **differs by path** (the field-name rule — use `task_order_num`, not the hex `order_num` — is in Agent Rules above):
-   - **Fast Path** → use **`fast-clip-data`'s** `task_order_num` (format: `fast_writing_clip_data_xxxxx`).
-   - **Standard Path** → use **`generate-writing`'s** `task_order_num` (format: `generate_writing_xxxxx`). The clip-data step's own `task_order_num` (`generate_clip_data_xxxxx`) returns `10001 任务关联记录信息缺失`. clip-data must still complete first as a prerequisite — but its order is not what video-composing keys off.
-5. **Prefer pre-built templates** over `popular-learning`. List with `task narration-styles --json`; preview at the resources URL above.
-6. **Use `-d @file.json`** for large request bodies to avoid shell quoting issues.
-7. **Use `task verify`** before expensive tasks to catch missing/invalid materials early; **`task budget`** to estimate point cost.
-
-## Data & Privacy
-
-- **API endpoint**: All requests go to `https://openapi.jieshuo.cn`. No third-party services.
-- **File upload**: presigned URL → OSS PUT → callback. Files are bound to your account, not public.
-- **Credentials**: `NARRATOR_APP_KEY` stored at `~/.narrator-ai/config.yaml`. Keep private; do not commit.
-- **Scope**: this skill only orchestrates the CLI; it does not access files outside what you explicitly pass as input.
-
-## Source
-
-Rewritten for AICUT from [`NarratorAI-Studio/narrator-ai-cli-skill`](https://github.com/NarratorAI-Studio/narrator-ai-cli-skill)
-(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/narrator-ai-cli/references/magic-video.md

@@ -1,205 +0,0 @@
-# Magic Video — Visual Templates (Optional Step)
-
-> ← Back to [SKILL.md](../SKILL.md)
-
-> ⚠️ **Agent restriction**: Do NOT auto-create magic-video tasks. Only create when the user **explicitly requests** a visual template. Present the catalog, explain options, let the user choose. Multiple templates can be selected — each produces a separate output video.
-
-Magic Video is a value-added service applied **after** video-composing:
-
-- Adds professional subtitle styles and branded layouts to the finished video
-- Multiple templates may be selected simultaneously (one output video per template)
-- **Pricing: 30 points/minute** (based on output video duration)
-
-**Input**: the `task_id` returned from `video-composing`.
-
----
-
-## Template Catalog
-
-List templates with name + price + description via the CLI:
-
-```bash
-narrator-ai-cli task templates --json
-```
-
-> ⚠️ The CLI list does **not** include per-template `params` schemas (e.g. `main_title`, `segment_count`, `bottom_disclaimer_text`). Use the static catalog below for params, or hit the raw endpoint when you need authoritative real-time param defaults:
->
-> ```bash
-> curl -X GET "https://openapi.jieshuo.cn/v2/task/commentary/get_magic_template_info" \
->     -H "app-key: $NARRATOR_APP_KEY"
-> ```
-
-Templates are organized by distribution platform and aspect ratio.
-
-### 油管 (YouTube)
-
-| Aspect Ratio | Template Name | Configurable Params |
-|---|---|---|
-| 9:16 垂直 | 竖屏·合规剧集 | `main_title`, `bottom_disclaimer_text`, `vertical_text_content`, `segment_count` |
-| 9:16 垂直 | 竖屏·柔光剧集 | `segment_count` |
-| 9:16 垂直 | 竖屏·模糊剧集 | `main_title`, `segment_count` |
-| 9:16 垂直 | 竖屏·简约剧集 | `segment_count` |
-| 9:16 垂直 | 竖屏·黑金剧集 | `main_title`, `sub_title`, `segment_count` |
-| 16:9 水平 | 横屏·沉浸剧集 | `segment_count` |
-| 16:9 水平 | 横屏·电影剧集 | `main_title`, `sub_title`, `segment_count` |
-| 16:9 水平 | 横屏·简约剧集 | `segment_count` |
-
-### 抖音 (TikTok / Douyin)
-
-| Aspect Ratio | Template Name | Configurable Params |
-|---|---|---|
-| 1:1 矩形 | 方屏·简约剧集 | `main_title`, `watermark_text`, `segment_count` |
-| 1:1 矩形 | 方屏·雅致剧集 | `main_title`, `segment_count` |
-| 9:16 垂直 | 竖屏·流光剧集 | `slogan`, `vertical_text_content`, `segment_count` |
-
-### 油管短视频 (YouTube Shorts)
-
-| Aspect Ratio | Template Name | Configurable Params |
-|---|---|---|
-| 9:16 垂直 | 竖屏·精准剧集 | `segment_count` |
-| 9:16 垂直 | 竖屏·重磅剧集 | `sub_title` ⚠️, `segment_count` |
-
----
-
-## Language Awareness (Critical)
-
-> All text params (`main_title`, `sub_title`, `bottom_disclaimer_text`, `vertical_text_content`, `watermark_text`, `slogan`) have **Chinese default values hardcoded in the template** and do NOT auto-adapt to the target language.
-
-When the narration target language is **not Chinese**, the agent MUST:
-
-1. **Never submit Chinese default values.** Submitting Chinese defaults will produce Chinese text in a non-Chinese video — always wrong.
-2. **Proactively provide localized values for every text param.** Do not ask the user whether they want localization — assume yes and act on it.
-3. **Translate the standard defaults to the target language and confirm with the user before submitting.** Required translations:
-   - `bottom_disclaimer_text` default `本故事纯属虚构 请勿模仿` → e.g. English: `This story is purely fictional. Do not imitate.`
-   - `vertical_text_content` default `影视效果 请勿模仿 合理安排生活` → e.g. English: `Cinematic effects only. Do not imitate. Manage your life wisely.`
-   - `main_title`, `sub_title`, `watermark_text`, `slogan` — if left empty, AI may still generate Chinese; proactively ask for user input or suggest a translated value.
-4. **This rule applies even when the user does not mention language.** The pipeline language is a single chain (dubbing → writing `language` → magic-video text params) — see SKILL.md § Agent Rules ("Honor the language chain"). Never treat the three steps as independent.
-5. **Ask all user-facing questions in the same language as the ongoing conversation.** Do not default to Chinese if the conversation is in another language.
-6. **Scope**: this rule governs magic-video template text params only. The narration-script `language` param is handled at the writing step (`fast-writing` / `generate-writing`).
-
----
-
-## Param Reference
-
-> ⚠️ **Agent behavior**: When the user picks a template, walk through each of its configurable params, explain what it controls, and ask for a value. Only submit once every param is confirmed or explicitly left at default.
-
-All params are optional — omitting them lets AI auto-generate where supported.
-
-### `segment_count` — 分集设置 (`int`, in all templates)
-
-Controls how the video is split into episodes:
-
-| Value | Behavior | When to use |
-|---|---|---|
-| `0` (default) | AI auto-determines episode count based on content length | Recommended for most cases |
-| `-1` | No splitting — output as a single video | Source is short, or user wants one file |
-| `1`, `2`, `3`… | Force exactly N episodes | User has a specific series structure in mind |
-
-> Ask: "要分集吗？留 `0` 让 AI 自动判断，指定集数，还是 `-1` 不分集？"
-
-### `main_title` — 主标题 (`string`)
-
-Templates: 竖屏·合规剧集, 竖屏·模糊剧集, 竖屏·黑金剧集, 横屏·电影剧集, 方屏·简约剧集, 方屏·雅致剧集.
-
-Primary title displayed prominently on screen.
-
-- **Leave empty (recommended)**: AI generates the most fitting title from content
-- **Fill in**: when the user wants a custom series name, channel brand, or overrides the AI-generated title
-- **Format tip**: keep under 10–12 chars for vertical layouts; under 16 for horizontal. Avoid layout-breaking punctuation
-- ⚠️ **Non-Chinese narration**: leaving empty may cause AI to generate a Chinese title. See Language Awareness above
-
-> Ask whether the user wants a custom title or prefers AI-generated. (In the conversation language.)
-
-### `sub_title` — 副标题 (`string`)
-
-Templates: 竖屏·黑金剧集, 横屏·电影剧集, 竖屏·重磅剧集.
-
-Secondary text displayed near the main title.
-
-- **Leave empty (recommended)**: AI auto-generates a short tagline
-- **Fill in**: when user wants a specific promotional slogan or episode label
-- ⚠️ **Special behavior in 竖屏·重磅剧集**: filling `sub_title` will **completely override the main title display** — the value entered replaces whatever would appear as main title. Only fill if the user specifically wants to override
-- ⚠️ **Non-Chinese narration**: leaving empty may cause AI to generate a Chinese tagline
-
-> Ask whether the user wants a custom subtitle. For 竖屏·重磅剧集, warn that filling will override main title.
-
-### `bottom_disclaimer_text` — 底部免责文案 (`string`)
-
-Template: 竖屏·合规剧集 only.
-
-Disclaimer pinned to the bottom of the screen — required for compliance on many platforms.
-
-- **Chinese narration — keep default**: `本故事纯属虚构 请勿模仿` covers standard platform compliance
-- **Non-Chinese narration — MUST translate**: default is Chinese and would display as Chinese in a non-Chinese video. Translate to target language (e.g. English: `This story is purely fictional. Do not imitate.`) and confirm before submitting. **Do NOT submit the Chinese default for non-Chinese narration.**
-- **Customize**: when user has a specific legal disclaimer or platform requires different wording
-- **Do not leave blank**: empty value removes the disclaimer, which may cause compliance issues
-
-> Chinese narration: "底部免责文案保留默认「本故事纯属虚构 请勿模仿」就好，有特殊合规需求才需要改。"
-> Non-Chinese narration: translate default → show translated value → ask for confirmation/edits.
-
-### `vertical_text_content` — 侧边警示语 / 侧边文案 (`string`)
-
-Templates: 竖屏·合规剧集, 竖屏·流光剧集.
-
-Vertical text displayed along the side edge.
-
-- **Chinese narration — keep default**: `影视效果 请勿模仿 合理安排生活` is standard compliance phrasing
-- **Non-Chinese narration — MUST translate**: default is Chinese (e.g. English: `Cinematic effects only. Do not imitate. Manage your life wisely.`). Confirm before submitting. **Do NOT submit the Chinese default for non-Chinese narration.**
-- **Customize**: channel-specific watermark phrase or branded vertical tagline
-- **Format tip**: keep concise — text renders vertically, shorter phrases look cleaner
-
-> Same prompts as `bottom_disclaimer_text` above.
-
-### `watermark_text` — 水印文案 (`string`)
-
-Template: 方屏·简约剧集 only.
-
-Copyright/brand text that roams randomly across the frame as a floating watermark.
-
-- **Leave empty**: no watermark displayed
-- **Fill in**: copyright protection or channel branding (e.g. `@ChannelName`, `© Studio Name`)
-- **Format tip**: short phrases work best (under 15 chars) — long text looks cluttered as it moves
-- ⚠️ **Non-Chinese narration**: value must be in the target language
-
-> Ask if the user wants a watermark. If yes, ask for the text.
-
-### `slogan` — 顶部标语 (`string`)
-
-Template: 竖屏·流光剧集 only.
-
-Custom text that fills the entire top title bar, overriding whatever the AI would generate.
-
-- **Leave empty (recommended)**: AI auto-generates a contextually appropriate top title
-- **Fill in**: only when the user has a fixed brand slogan or exclusive tagline. Once filled, AI title generation for this slot is bypassed
-- ⚠️ **Non-Chinese narration**: leaving empty may cause AI to generate a Chinese slogan
-
-> Ask if the user wants a fixed top slogan.
-
----
-
-## Creating a Magic Video
-
-> ⚠️ **Agent behavior — mandatory pre-submission confirmation**: Before running any `magic-video` create command, the agent MUST display the full request parameters to the user in a readable format (templates selected, all `template_params` values for each template), then explicitly ask for confirmation. Do NOT submit until the user confirms. This applies **every time** a `magic-video` task is created — including multiple calls within the same session. Ask in the conversation language.
-
-```bash
-# Without custom params (AI handles all defaults)
-narrator-ai-cli task create magic-video --json -d '{
-  "task_id": "<task_id from video-composing>",
-  "template_name": ["竖屏·黑金剧集", "横屏·电影剧集"]
-}'
-
-# With custom params — key is template name, value is params dict
-narrator-ai-cli task create magic-video --json -d '{
-  "task_id": "<task_id from video-composing>",
-  "template_name": ["竖屏·合规剧集"],
-  "template_params": {
-    "竖屏·合规剧集": {
-      "segment_count": 0,
-      "bottom_disclaimer_text": "本故事纯属虚构 请勿模仿",
-      "vertical_text_content": "影视效果 请勿模仿 合理安排生活"
-    }
-  }
-}'
-```
-
-**Output**: `sub_tasks` array — one entry per template, each with a rendered video URL.