@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/narrator-ai-cli/references/operations.md

@@ -1,230 +0,0 @@
-# Operations — Polling, Files, Account, Errors
-
-> ← Back to [SKILL.md](../SKILL.md)
-
-Reference for task polling, task management commands, file operations, user/account commands, and the full error code table.
-
----
-
-## Task Query Response Shape
-
-`narrator-ai-cli task query <task_id> --json` returns a **flat** object. The top level is the task envelope; `results.tasks[]` is a nested array of sub-tasks with a different status code system. Reading the wrong path is the #1 cause of silent infinite polling.
-
-| Path | Type | What it is |
-|---|---|---|
-| `.status` | int (0–4) | **Task-level status — what polling reads.** See "Task status codes" below |
-| `.task_id` | str (32-char hex) | Same id you passed to `task query` |
-| `.task_order_num` | str (prefixed, e.g. `generate_writing_xxxxx`) | **Pass this as `order_num` to downstream tasks.** Never pass `.task_id` (hex) instead |
-| `.completed_at` | str / null | ISO timestamp once `status=2` |
-| `.consumed_points` | float | Billing amount actually charged |
-| `.files[]` | list | Output files. Each entry: `{file_id, file_path, file_name, suffix, ...}` |
-| `.files[0].file_id` | str | **The output `file_id` to pass to the next step** (e.g. fast-writing's narration script → fast-clip-data) |
-| `.results.tasks[0].video_url` | str | Finished MP4 URL (video-composing only) |
-| `.results.tasks[0].task_result` | str | Output path or JSON string. For writing tasks: narration script path. For popular-learning: JSON containing `agent_unique_code` |
-| `.results.tasks[0].status` | int (different system, e.g. `9`) | **Sub-task status. Do NOT poll on this — it uses a different code system from `.status`** |
-| `.results.order_info.order_num` | str (e.g. `script_xxxxx`) | Billing-side identifier. **NOT** what downstream tasks accept — submitting it returns `10001` |
-
-> ⚠️ **Two `status` fields exist.** Top-level `.status` (0–4) is what polling watches. Nested `.results.tasks[0].status` uses a different code system (e.g. `9` on success). Polling against the nested one returns nonsense values and loops forever.
->
-> ⚠️ **Two `order_num`-shaped fields exist.** Top-level `.task_order_num` (prefixed string like `generate_writing_xxxxx` / `fast_writing_clip_data_xxxxx`) is what downstream tasks accept. Nested `.results.order_info.order_num` (`script_xxxxx`) is a billing-side id and is rejected. Also: `.task_id` is a 32-char hex string — never submit it as `order_num`, returns `10001 任务关联记录数据异常`.
-
----
-
-## Task Polling
-
-> ⚠️ **Agent behavior — standard polling pattern**: Always use the `while` loop below when monitoring a task. **Never** use a `for` loop with a fixed iteration count — it may exhaust before the task finishes. The loop runs until status `2` (success) or `3` (failed) and cannot be silently interrupted mid-run.
-
-```bash
-# Standard polling loop — use this every time a task needs to be monitored
-# NOTE: variable is named `task_status`, not `status` — `$status` is a
-# read-only built-in in zsh (alias for $?), so plain `status=...` will
-# error with "read-only variable: status" on macOS default shell.
-TASK_ID="<task_id>"
-empty_streak=0
-iter=0
-MAX_EMPTY=12        # ~1 min of consecutive parse failures → bail out
-MAX_ITERATIONS=720  # ~1 hour absolute cap → bail out regardless of status
-while [ "$iter" -lt "$MAX_ITERATIONS" ]; do
-  iter=$((iter + 1))
-  result=$(narrator-ai-cli task query "$TASK_ID" --json 2>&1)
-  task_status=$(echo "$result" | python3 -c "
-import json, sys
-try:
-    d = json.load(sys.stdin)
-    print(d.get('status', ''))   # top-level field — see 'Task Query Response Shape' above
-except Exception:
-    print('')
-" 2>/dev/null)
-  echo "[$(date '+%H:%M:%S')] iter=$iter task=$TASK_ID status=$task_status"
-  [ "$task_status" = "2" ] && echo "Done." && break
-  [ "$task_status" = "3" ] && echo "Failed:" && echo "$result" && break
-  if [ -z "$task_status" ]; then
-    empty_streak=$((empty_streak + 1))
-    if [ "$empty_streak" -ge "$MAX_EMPTY" ]; then
-      echo "Aborting: $MAX_EMPTY consecutive unparseable responses. Last response:" && echo "$result"
-      break
-    fi
-  else
-    empty_streak=0
-  fi
-  sleep 5
-done
-[ "$iter" -ge "$MAX_ITERATIONS" ] && echo "Aborting: hit MAX_ITERATIONS=$MAX_ITERATIONS (~1h). Last response:" && echo "$result"
-```
-
-> ⚠️ **Why `task_status`, not `status`**: in zsh (macOS default shell) `$status` is a read-only built-in (alias for `$?`). Assigning to it errors out with `read-only variable: status` and the loop never starts. Use a different variable name.
-
-> ⚠️ **Why the empty-status guard**: `task query` may return non-JSON (network error, auth failure, CLI traceback). Without the guard, an empty `task_status` neither triggers success nor failure, and the loop runs forever. After `MAX_EMPTY` consecutive unparseable responses (~1 min at 5 s intervals), the loop bails out with the last raw response so the agent can diagnose.
-
-> ⚠️ **Why the absolute iteration cap**: `MAX_ITERATIONS=720` (~1 hour) is a belt-and-suspenders ceiling for the case where `task_status` parses cleanly to a value that is neither `"2"` nor `"3"` (e.g., the API adds a new status code, returns `"running"`, or the task is genuinely stuck in `1`). The empty-status guard does NOT catch this — non-empty parses reset `empty_streak` to 0. Without the cap, such a response loops forever. Tune `MAX_ITERATIONS` upward only for genuinely long-running tasks.
-
-> ⚠️ **If you write your own polling in Python instead of bash**: the API returns task `status` as an **integer** (`2`, `3`, etc.). Compare with `int` (`if s == 2`) **or** coerce both sides to string (`if str(s) == "2"`) — but be consistent. Using `if s == "2"` against an integer response (or vice versa) will silently never match and the loop will run forever.
-
-### Resuming after the loop bails out
-
-**Bailing out (`MAX_EMPTY` or `MAX_ITERATIONS` triggered) does NOT cancel the task** — the loop only stops local polling. The server-side task continues running independently. To resume:
-
-1. **Spot-check current status** with a single query (no loop):
-   ```bash
-   narrator-ai-cli task query "$TASK_ID" --json | python3 -m json.tool
-   ```
-   If top-level `.status` is already `2`, the task finished while you weren't watching — read the result fields (`.task_order_num`, `.files[0].file_id`, `.results.tasks[0].video_url`, etc. — see "Task Query Response Shape" above) directly and continue to the next step. No need to re-poll.
-
-2. **Re-enter the loop** with the same `TASK_ID` if status is still `0` or `1`. The API has no notion of "who is polling" — re-querying simply returns the latest state.
-
-3. **Lost the `TASK_ID`?** List in-progress tasks (status `1`) and pick yours by type or recency:
-   ```bash
-   narrator-ai-cli task list --status 1 --json            # all in-progress
-   narrator-ai-cli task list --status 1 --type 9 --json   # in-progress fast-writing only
-   ```
-   See "Task type IDs" below for the `--type` mapping.
-
-**Polling rules:**
-- Poll every **5 seconds**. Faster polling adds API load without benefit.
-- Most tasks complete in 30 seconds to several minutes.
-- `search-movie` may take 60+ seconds (Gradio backend, results cached 24h).
-
-**Task status codes:**
-
-| Code | Meaning |
-|---|---|
-| 0 | init |
-| 1 | in_progress |
-| 2 | success |
-| 3 | failed |
-| 4 | cancelled |
-
----
-
-## Task Management Commands
-
-```bash
-# Single query (spot-checks only — do not use in automated polling)
-narrator-ai-cli task query <task_id> --json
-
-# List tasks with filters
-narrator-ai-cli task list --json
-narrator-ai-cli task list --status 2 --type 9 --json     # completed fast-writing
-narrator-ai-cli task list --category commentary --json
-
-# Estimate point cost before creating
-narrator-ai-cli task budget --json -d '{
-  "learning_model_id": "<id>",
-  "native_video": "<video_file_id>",
-  "native_srt": "<srt_file_id>"
-}'
-# Returns: viral_learning_points, commentary_generation_points,
-#          video_synthesis_points, visual_template_points, total_consume_points
-
-# Verify materials before task creation
-narrator-ai-cli task verify --json -d '{
-  "bgm": "<bgm_id>",
-  "dubbing_id": "<voice_id>",
-  "native_video": "<video_file_id>",
-  "native_srt": "<srt_file_id>"
-}'
-# Returns: is_valid (bool), errors (list), warnings (list)
-
-# Retrieve / save narration scripts
-narrator-ai-cli task get-writing --json
-narrator-ai-cli task save-writing -d '{...}'
-narrator-ai-cli task save-clip -d '{...}'
-
-# List task types with details
-narrator-ai-cli task types -V
-```
-
-**Task type IDs** (for the `--type` filter on `task list`):
-
-| ID | Type |
-|---|---|
-| 1 | popular_learning |
-| 2 | generate_writing |
-| 3 | video_composing |
-| 4 | voice_clone |
-| 5 | tts |
-| 6 | clip_data |
-| 7 | magic_video |
-| 8 | subsync |
-| 9 | fast_writing |
-| 10 | fast_clip_data |
-
----
-
-## File Operations
-
-```bash
-narrator-ai-cli file upload ./video.mp4 --json           # 3-step: presigned → OSS → callback
-narrator-ai-cli file transfer --link "<url>" --json       # import by HTTP/Baidu/PikPak link
-narrator-ai-cli file list --json                          # pagination, --search filter
-narrator-ai-cli file info <file_id> --json                # name, path, size, category, timestamps
-narrator-ai-cli file download <file_id> --json            # returns time-limited presigned URL
-narrator-ai-cli file storage --json                       # used_size, max_size, usage_percentage
-narrator-ai-cli file delete <file_id> --json              # irreversible
-```
-
-**File categories**: 1 = video, 2 = audio, 3 = image, 4 = doc, 5 = torrent, 6 = other.
-
-**Supported formats**: `.mp4`, `.mkv`, `.mov`, `.mp3`, `.m4a`, `.wav`, `.srt`, `.jpg`, `.jpeg`, `.png`.
-
----
-
-## User & Account
-
-```bash
-narrator-ai-cli user balance --json                       # account points balance
-narrator-ai-cli user login --json                         # login with username/password
-narrator-ai-cli user keys --json                          # list sub API keys
-narrator-ai-cli user create-key --json                    # create a new sub API key
-```
-
----
-
-## Error Codes
-
-> **Support contact** (for balance/billing, app_key issues — including obtaining, renewing, or troubleshooting API keys): WeChat `gezimufeng`, or email `merlinyang@gridltd.com`.
-
-| Code | Meaning | Action |
-|---|---|---|
-| `10000` | Success | - |
-| `10001` | Failed | Check params |
-| `10002` | App key expired | Contact support to renew |
-| `10003` | Sign expired | Check timestamp |
-| `10004` | Invalid app key | Run `config show` to verify; contact support if invalid |
-| `10005` | Invalid sign | Check `app_key` config; contact support if persists |
-| `10006` | Invalid timestamp | Check clock sync |
-| `10007` | Not found | Check resource ID |
-| `10008` | Invalid method | Check HTTP method |
-| `10009` | Insufficient balance | Contact support to top up |
-| `10010` | Task not found | Verify `task_id` |
-| `10011` | Task create failed | Retry or check params |
-| `10012` | Task type not found | Use `task types` to list valid types |
-| `10013` | Insufficient balance (key) | Contact support to top up sub-key quota |
-| `40000` | Gradio timeout | Retry (backend overloaded) |
-| `50000` | Unauthorized | Check `app_key` config; contact support |
-| `50001` | Database error | Retry later |
-| `50002` | System busy | Retry later |
-| `50003` | System error | Contact support |
-| `60000` | Retryable error | Safe to retry |
-
-CLI exits with code `1` on any error and prints to stderr.

package/skills/narrator-ai-cli/references/resources.md

@@ -1,126 +0,0 @@
-# Resources — Materials, BGM, Dubbing, Templates
-
-> ← Back to [SKILL.md](../SKILL.md)
-
-Detailed list commands, response formats, and field mappings for the four resource types selected before any task. The selection rules (never auto-select, present 5–8 options, etc.) live in **SKILL.md § Resource Selection Protocol**.
-
----
-
-## 1. Source Files (Video + SRT)
-
-> ⚠️ **Agent behavior**: Use `material list --json --page 1 --size 100` to fetch pre-built materials. Check the `total` field — if `total > 100`, fetch additional pages until all items are retrieved. **Search programmatically using `grep -i` or `python3 -c` piped from the JSON output — do NOT rely on the terminal display, which may be truncated and miss items.** Present **all matching results** (usually ≤ 3) — show title, year, genre, summary. Wait for the user to pick one. If the user wants to upload their own files, guide them through `file upload` for both video and SRT. Do NOT proceed to writing until `video_file_id` and `srt_file_id` are confirmed.
-
-### Option A: Pre-built materials (recommended)
-
-```bash
-narrator-ai-cli material list --json --page 1 --size 100
-# If total > 100, fetch more pages: --page 2 --size 100, etc.
-```
-
-**Response structure:**
-
-```json
-{
-  "total": 101,
-  "page": 1,
-  "size": 100,
-  "items": [
-    {
-      "id": "<material_id>",
-      "name": "极限职业",
-      "title": "Extreme Job",
-      "year": "2019",
-      "type": "喜剧片",
-      "story_info": "...",
-      "character_name": "[柳承龙 (Ryu Seung-ryong), 李荷妮 (Lee Ha-nee), ...]",
-      "cover": "https://...",
-      "video_file_id": "<video_file_id>",
-      "srt_file_id": "<srt_file_id>"
-    }
-  ]
-}
-```
-
-**Programmatic search** (case-insensitive):
-
-```bash
-narrator-ai-cli material list --json --page 1 --size 100 | grep -i "飞驰人生"
-
-narrator-ai-cli material list --json --page 1 --size 100 \
-  | python3 -c "import json, sys; items = json.load(sys.stdin).get('items', []); \
-[print(json.dumps(i, ensure_ascii=False)) for i in items if '飞驰' in i.get('name','') or '飞驰' in i.get('title','')]"
-```
-
-**Material → `confirmed_movie_json` field mapping** (construct locally — no `search-movie` needed when the material is found):
-
-| Material field | `confirmed_movie_json` field | Notes |
-|---|---|---|
-| `name` | `local_title` | Chinese title |
-| `title` | `title` | English title |
-| `year` | `year` | |
-| `type` | `genre` | e.g. `喜剧片` |
-| `story_info` | `summary` | |
-| `character_name` | `stars` | Parse JSON array string |
-| (not in material) | `director` | Omit if unavailable |
-
-### Option B: Upload your own
-
-```bash
-narrator-ai-cli file upload ./movie.mp4 --json           # returns file_id
-narrator-ai-cli file upload ./subtitles.srt --json
-narrator-ai-cli file transfer --link "<url>" --json       # transfer by HTTP/Baidu/PikPak link
-```
-
-Supported formats: `.mp4`, `.mkv`, `.mov`, `.mp3`, `.m4a`, `.wav`, `.srt`, `.jpg`, `.jpeg`, `.png`.
-
-Full file ops (list, info, download, storage, delete) live in `operations.md`.
-
----
-
-## 2. BGM (Background Music)
-
-> ⚠️ **Agent behavior**: Infer the mood/genre from context, then use `bgm list --search "<keyword>"` to pre-filter. Present **5–8 tracks** (agent decides which fields best represent each — typically name + style). If the user has no preference, recommend **3 tracks** with a one-line reason for each (e.g., "matches the film's fast-paced action tone"). Wait for confirmation. Do NOT use a `bgm` ID in any task until the user confirms.
-
-```bash
-narrator-ai-cli bgm list --json                          # all tracks (146 currently)
-narrator-ai-cli bgm list --search "单车" --json
-```
-
-The `id` field is what you pass as the `bgm` param when creating clip-data / fast-clip-data tasks.
-
----
-
-## 3. Dubbing Voice
-
-> ⚠️ **Agent behavior**: Infer the target language from context; if ambiguous, **ask the user** before listing. Run `dubbing list --lang <language>` to filter, then present **all matching voices** (typically < 15 per language) — include name and tags. If the user has no preference, recommend **3 voices** with reasoning (e.g., "neutral tone fits documentary narration"). Wait for confirmation. Do NOT use a dubbing `id` or `dubbing_type` in any task until the user confirms both.
-
-```bash
-narrator-ai-cli dubbing list --json                      # 63 voices, 11 languages
-narrator-ai-cli dubbing list --lang 普通话 --json
-narrator-ai-cli dubbing list --tag 喜剧 --json
-narrator-ai-cli dubbing languages --json
-narrator-ai-cli dubbing tags --json
-```
-
-Each voice exposes `id` (= `dubbing` param) and `type` (= `dubbing_type` param) — both are required when creating clip tasks.
-
-**Languages available**: 普通话 (39), English (4), 日语 (3), 韩语 (2), Spanish (3), Portuguese (2), German (2), French (2), Arabic (2), Thai (2), Indonesian (2).
-
-> ⚠️ **Language linkage** (recap from SKILL.md): If the chosen voice is non-Chinese, the writing task's `language` param **must** be set to the matching language, and magic-video template text params must also be in the matching language. See `magic-video.md` for the template-text rules.
-
----
-
-## 4. Narration Style Templates (90+, 12 genres)
-
-> ⚠️ **Agent behavior**: Infer the content genre from context and run `task narration-styles --genre <genre>` to pre-filter. Present **3–5 templates** (agent decides best representative fields). Also share the visual preview link to help the user browse:
-> https://ceex7z9m67.feishu.cn/wiki/WLPnwBysairenFkZDbicZOfKnbc
-> If the user has no preference, recommend **3 templates** with a brief style description and reasoning. Wait for confirmation. Do NOT use a `learning_model_id` until the user confirms.
-
-```bash
-narrator-ai-cli task narration-styles --json
-narrator-ai-cli task narration-styles --genre 爆笑喜剧 --json
-```
-
-**Genres**: 热血动作, 烧脑悬疑, 励志成长, 爆笑喜剧, 灾难求生, 悬疑惊悚, 惊悚恐怖, 东方奇谈, 家庭伦理, 情感人生, 奇幻科幻, 传奇人物.
-
-Use the template's `id` directly as `learning_model_id` — **no `popular-learning` step needed**.