video-job-manager

name	video-job-manager
description	Tạo và quản lý các video job sản xuất biệt lập, gồm metadata yêu cầu, asset đầu vào, artifact theo stage, status, theo dõi stale, và path chuẩn cho pipeline video.

Video Job Manager

Quy tắc đầu ra (BẮT BUỘC)

• Mọi nội dung do AI/LLM sinh ra (brief, title, lý do stale, ghi chú trong todo) bắt buộc viết bằng tiếng Việt CÓ DẤU.
• Cấm asciify (vd KHÔNG được viết "stale do voice thay doi").
• job.id, tên stage (creative_plan, render...), enum status (pending, running, done, failed, stale), key TOML, CLI flag, file path giữ nguyên tiếng Anh — không dịch.
• Khi tạo job, đặt --title bằng tiếng Việt có dấu để lưu trong job.toml; phần tên trong job.id/directory phải là tiếng Việt không dấu, lowercase, nối bằng gạch ngang. Script create tự bỏ dấu từ --title (vd Tư duy làm giàu -> 2026-04-25_001_tu-duy-lam-giau).
• Nếu truyền --job-id thủ công, bắt buộc dùng tiếng Việt không dấu/lowercase với ký tự [a-z0-9_-]; không dùng dấu tiếng Việt, khoảng trắng, chữ hoa, emoji, hoặc tên tiếng Anh cho phần mô tả job.

Mục tiêu

Quản lý mọi thứ thuộc về 1 yêu cầu sinh video như 1 job có thể tái lập.

Skill này không tự tạo nội dung video. Nó tạo và bảo trì job workspace để các skill video khác đọc và ghi vào.

Quy tắc môi trường script

Trước khi chạy bất kỳ script nào của skill này, đọc file .env ở repo-root trước. File này nằm cạnh jobs/, skills/, và env.example. Chỉ kiểm tra các key cần thiết có tồn tại không; tuyệt đối không in giá trị secret. Chỉ dùng --env-file không phải repo-root khi user yêu cầu rõ ràng.

Khi nào dùng

Dùng skill này khi user bắt đầu yêu cầu video mới, thêm reference/input asset, hỏi status job, rerun một phần pipeline, hoặc cần tìm artifact của một yêu cầu video cụ thể.

Layout mặc định

.env
env.example
jobs/
  <job_id>/
    job.toml
    input/
      reference/
      raw_assets/
      audio/
      brand/
    source/
      vds.md
      creative_plan.toml
      voice_selection.toml
      voice.wav
      transcript_word_level.toml
      asset_semantics.toml
      semantic_mapping.toml
      render_plan.toml
    remotion/
      node_modules -> ../../../node_modules
      package.json
      remotion.config.ts
      tsconfig.json
      src/
      public/
        assets/
    output/
      preview.mp4
      final_video.mp4
      thumbnail.jpg
      render_report.toml
    logs/
      render.log
      validation.log
      pipeline_status.toml
      todo.toml

Trách nhiệm

1. Tạo directory duy nhất jobs/<job_id>.
2. Lưu yêu cầu gốc trong job.toml.
3. Đăng ký reference video, raw asset, audio, file brand.
4. Track path artifact chuẩn cho mọi stage.
5. Đánh dấu stage pipeline là pending, running, done, failed, hoặc stale.
6. Đánh dấu stage downstream stale khi input thay đổi.
7. Cung cấp path để các skill khác sử dụng.
8. Bảo trì logs/todo.toml như danh sách todo luôn cập nhật cho job.

Remotion dependency reuse

Khi tạo job mới, remotion/node_modules phải là symlink về repo root ../../../node_modules. Không chạy npm install trong từng job; nếu thiếu dependency, chạy npm install một lần ở repo root.

Thứ tự stage

request
reference_style
creative_plan
voice
transcript
asset_semantics
semantic_mapping
render_plan
render

Script tiện ích

Dùng script đi kèm để quản lý state job deterministic:

python skills/video-job-manager/scripts/manage_job.py create \
  --title "Quảng cáo thói quen buổi sáng" \
  --brief "Tạo TikTok 45s phong cách reflective..." \
  --platform tiktok \
  --language vi \
  --target-duration 45

python skills/video-job-manager/scripts/manage_job.py register-input \
  --job jobs/2026-04-25_001_quang-cao-thoi-quen-buoi-sang \
  --kind raw_assets \
  --path /path/to/clip.mp4 \
  --copy

python skills/video-job-manager/scripts/manage_job.py mark-stage \
  --job jobs/2026-04-25_001_quang-cao-thoi-quen-buoi-sang \
  --stage creative_plan \
  --status done \
  --output source/creative_plan.toml

python skills/video-job-manager/scripts/manage_job.py stale-from \
  --job jobs/2026-04-25_001_quang-cao-thoi-quen-buoi-sang \
  --stage voice \
  --reason "audio voice đã thay đổi"

python skills/video-job-manager/scripts/manage_job.py status \
  --job jobs/2026-04-25_001_quang-cao-thoi-quen-buoi-sang

python skills/video-job-manager/scripts/manage_job.py todo \
  --job jobs/2026-04-25_001_quang-cao-thoi-quen-buoi-sang

Hợp đồng TOML

job.toml phải có:

[job]
id = "2026-04-25_001_quang-cao-thoi-quen-buoi-sang"
title = "Quảng cáo thói quen buổi sáng"
status = "created"
created_at = "2026-04-25T10:00:00+07:00"
updated_at = "2026-04-25T10:00:00+07:00"

[request]
brief = "..."
platform = "tiktok"
language = "vi"
target_duration_seconds = 45

[paths]
job_dir = "jobs/2026-04-25_001_morning-routine-ad"
input_dir = "input"
reference_dir = "input/reference"
raw_assets_dir = "input/raw_assets"
source_dir = "source"
remotion_dir = "remotion"
output_dir = "output"

[[inputs]]
kind = "raw_assets"
path = "input/raw_assets/clip01.mp4"
original_path = "/path/to/clip01.mp4"

[[stages]]
name = "creative_plan"
status = "done"
output = "source/creative_plan.toml"
updated_at = "..."
reason = ""

logs/todo.toml phải đồng bộ với state stage:

[[todos]]
id = "TODO_003"
stage = "creative_plan"
title = "Tạo script, scene intents và overlay plan"
status = "done"
output = "source/creative_plan.toml"
updated_at = "..."
reason = ""

Mapping todo status:

pending -> todo
running -> doing
done -> done
failed -> blocked
stale -> todo

Quy tắc chất lượng

• Không bao giờ dùng source/ chung cho 1 video job thật khi đã có job directory.
• Không ghi đè artifact của job khác.
• Đăng ký input thay đổi trước khi rerun stage pipeline.
• Khi input của 1 stage thay đổi, đánh dấu các stage downstream stale thay vì giả vờ chúng vẫn hợp lệ.
• Giữ mọi path trong job.toml tương đối so với job directory khi có thể.
• Mọi lệnh thay đổi state phải refresh logs/todo.toml.