eternityspring/shuohao-skills

novel-script

Écriture de scénarios pour mini-séries IA. Principe fondamental : le scénario gère le récit, le storyboard gère la réalisation — « l'impact émotionnel » et « comment filmer » sont deux rythmes d'itération distincts. Les répliques doivent être retravaillées en profondeur à plusieurs reprises ; les lier à un découpage en plans signifierait réorganiser chaque plan à chaque modification. Ainsi, cette couche ne contient que des épisodes, des scènes et un flux de beats — pas de numéros de plans. Les plans, les prompts d'image clé et les lots de génération relèvent du prochain skill de storyboard.

Mais une règle est absolue : les répliques doivent être des données structurées, pas de la prose. Chaque réplique est un élément indépendant (locuteur + texte + ton), et les actions sont des beats indépendants — c'est le fondement de tous les contrôles qualité déterministes :

Livrable	Problème résolu
Budget temps par épisode	Un épisode de trois minutes fait exactement trois minutes : les répliques sont calculées selon le débit de parole, les actions selon une durée estimée par beat. Tout dépassement ou sous-utilisation est détecté immédiatement, pas au moment de la génération
Flux de beats (action ⇄ réplique)	Les répliques sont directement envoyées au TTS pour génération phrase par phrase ; les beats d'action décrivent ce qui se passe à l'écran. Si tout est mélangé en prose, rien n'est utilisable dans le pipeline
Au moins un beat d'action par scène	Une scène sans action est une pièce radiophonique — l'IA n'aurait rien à montrer visuellement
Crochet d'ouverture + suspense de fin	Ligne de vie de la mini-série, chaque épisode doit les avoir explicitement ; le crochet n'est pas une étiquette, c'est le premier beat — hookBeat identifie sa position concrète, dans les 3 premiers beats de tout l'épisode (ouverture à froid)
Revendication des moments forts	Si le résumé d'épisode mentionne un grand moment fort, le script doit l'incarner — pour éviter de le perdre en cours de réécriture
Cohérence amont	Les scènes/éclairages/accessoires sont vérifiés par rapport à art.json, les personnages par rapport à outline.json ; tout état d'éclairage non enregistré est signalé

{baseDir} = répertoire contenant ce fichier. Le script {baseDir}/scripts/novel-script.mjs, sans dépendance, s'exécute avec node.

Limites (ce qui n'est pas fait) : pas de découpage en plans, pas de numéros de plans, pas de prompts de génération d'images, pas d'export d'images, pas de composition musicale — rien qui relève du storyboard. Pas de modification de la structure de l'outline (fusion de lignes narratives relève de novel-outline) ; pas de création de personnages ou de décors (c'est le travail de novel-characters / novel-art).

---

Étape 0 — Définir l'entrée et le périmètre

outline.json est le fournisseur amont direct du script (résumés d'épisodes, emplacements des moments forts, durée des épisodes — tout y est). Le flux standard part de là. S'il n'existe pas, demander d'abord à l'utilisateur s'il faut exécuter novel-outline ; s'il insiste pour écrire directement, demander le nombre d'épisodes et leur durée en minutes, créer le squelette manuellement, et les contrôles de cohérence indiqueront clairement ce qui est sauté.

Combien d'épisodes à la fois : par défaut, lot ≤ 3 épisodes. Le script est la couche la plus remaniée de tout le pipeline ; produire par petits lots, valider rapidement, puis passer à la suite. Si l'utilisateur veut toute la série, elle est produite par lots, chaque lot subissant la validation.

Ajouter en option (si fournis, ils permettent la cohérence et l'affichage des noms) :

• --outline : cohérence des références aux personnages + vérification de la revendication des moments forts + les noms des personnages (C01) s'affichent en toutes lettres dans le rapport
• --art : cohérence des décors/états d'éclairage/accessoires + les noms des décors (S01) s'affichent dans le rapport

Étape 1 — Squelette seed

node {baseDir}/scripts/novel-script.mjs seed <outline.json> --eps 1-3 > <workdir>/script.json

Transfert déterministe : durée cible (minutes de l'épisode × 60), crochet, suspense, revendication des moments forts de l'épisode, décors et personnages candidats (dans seedNote). Ces faits ne doivent pas être repensés par le modèle. scenes reste vide — c'est le travail d'écriture.

Étape 2 — Écrire épisode par épisode

Chaque épisode est une tâche, exécutées en parallèle si possible. Chaque tâche reçoit :

• {baseDir}/references/script-pass.md et {baseDir}/references/schema.md (les lire et les suivre)
• Le squelette seed de cet épisode + le résumé/moment fort/plan de groupe de personnages de l'outline pour cet épisode
• Les fiches de décors utilisées dans cet épisode (ancres dans art.json, états d'éclairage) et les informations sur les personnages (tempérament, manière de parler — idéalement avec cast.json)
• Le suspense de fin de l'épisode précédent (l'ouverture de celui-ci doit s'y raccorder)

Les exigences principales sont dans script-pass.md. Les quatre plus importantes : Les beats d'action ne décrivent que des actions courantes (porter un fardeau, monter dans un bateau, poser une charge — des actions que l'IA a vues des millions de fois ; un geste délicat comme « tendre la perche pour bloquer » ou « frémissement de cils » provoquera des erreurs de génération) ; le budget temps prime sur tout (un épisode de trois minutes fait environ 50 beats, après rédaction exécuter validate pour vérifier les secondes) ; les répliques doivent être orales, tenir en une seule respiration, chaque personnage parle comme lui (avec cast.json, utiliser le tempérament et la manière de parler) ; le premier beat de chaque épisode est une ouverture à froid qui concrétise le crochet (hookBeat l'identifie, le contrôle vérifie sa position), et le dernier beat doit être le suspense.

Une fois écrit, supprimer seedNote.

Étape 3 — Validation ⛔ ne pas sauter

node {baseDir}/scripts/novel-script.mjs validate <script.json> \
  --outline <outline.json> --art <art.json>

Les 10 contrôles qualité sont tous codés : durée de chaque épisode dans la tolérance ±15% de la cible (répliques à 4.5 caractères/seconde, actions à 2.5 secondes/beat, params ajustables), réplique ≤ 35 caractères, locuteur présent dans les personnages de la scène ou marqué VO, crochet et suspense présents dans chaque épisode, crochet concret réalisé dans les 3 premiers beats (hookBeat l'identifie, params.hookWindow ajustable), au moins un beat d'action par scène, action en récit pur sans guillemets de réplique, revendication des moments forts, cohérence des personnages, cohérence des décors/éclairages/accessoires.

Corriger chaque violation une par une, puis relancer la validation jusqu'à succès. Si la durée dépasse, réduire d'abord les beats d'action, puis les répliques ; si elle est insuffisante, ajouter du contenu sans remplissage — ajouter du conflit, pas des banalités. Si un état d'éclairage non enregistré dans art.json est nécessaire, le rajouter dans art.json d'abord, puis revenir — ne pas contourner le contrôle.

Étape 4 — Sortie et rapport

cd <répertoire de sortie>
node {baseDir}/scripts/novel-script.mjs render <nom-série>-script.json --md \
  --outline <outline.json> --art <art.json> > <nom-série>-script.md
node {baseDir}/scripts/novel-script.mjs render <nom-série>-script.json --html \
  --outline <outline.json> --art <art.json> --cast <cast.json> > script-report.html
# Interface anglaise : ajouter --lang en (par défaut chinois, peut aussi suivre le champ lang du script.json)

Le rapport contient : KPI (avec proportion de répliques), tableau de bord des durées (barre par épisode dans la bande cible, dépassement/sous-utilisation en rouge), script par épisode (deux épisodes par ligne, informations de scène masquées après 300px avec défilement, clic pour développer), tableau des scènes, livret de répliques (deux par ligne, regroupées par personnage, hauteur de liste limitée à 6 lignes avec défilement, copie groupée ; avec --cast, chaque groupe de personnage a un bouton indice de timbre vocal — répliques et timbre sur une même page pour lancer directement le TTS), panneau des contrôles qualité, export JSON (télécharge le script.json original).

Le rapport résume en une phrase : nombre d'épisodes/scènes/répliques, durée totale estimée vs cible, épisodes proches des tolérances, chemin du rapport ; les contrôles non passés sont clairement mentionnés.

Livraison finale :

<répertoire de sortie>/
├── <nom-série>-script.json
├── <nom-série>-script.md
└── script-report.html             ← ouvrable en double-clic

---

Relais des quatre compétences

novel-outline    → outline.json (quoi : structure et épisodes)
novel-characters → cast.json    (qui : assets personnages)
novel-art        → art.json     (où + objets tenus : assets artistiques)
novel-script     → script.json  (récit : scènes, beats, répliques)

seed utilise outline.json ; --outline et --art de validate/render gèrent la cohérence et l'affichage des noms. Les quatre fichiers JSON ont leurs propres rapports avec bouton d'export, et chaque modification peut être réinjectée dans leur render/validate respectif. La couche suivante est le storyboard : numéros de plans, durée par plan, prompts d'image clé, lots de génération.

Limites

• Interface du rapport bilingue chinois/anglais (--lang, défaut chinois, ou suit le champ lang du script.json) ; la langue des répliques suit la série
• La durée est une estimation, pas un chronomètre — la tolérance ±15% est prévue à cet effet ; params.charsPerSecond est ajustable selon le débit du doublage
• VO est le marqueur uniforme pour la voix off ; l'identité de la pensée est indiquée dans delivery ; dans le livret de répliques, VO forme un groupe séparé
• Pas de limite du nombre de scènes par épisode — l'IA peut changer de décor sans coût, le nombre de changements est seulement compté dans les KPI sans validation bloquante

Auto-test

node {baseDir}/scripts/selftest.mjs

154 assertions, sans appeler de modèle, sans coût. Les 10 contrôles qualité ont chacun des cas de test qui les brisent. Exécuter ce test après toute modification du script.

Exemple fourni

{baseDir}/examples/渡口-script.json : Script complet des 6 épisodes de « Le Bac » (9 scènes, 123 répliques, chaque épisode commence par une ouverture à froid avec crochet, tous dans les 120 secondes ±15%). Passe tous les contrôles qualité en correspondance avec les exemples de novel-outline et novel-art. Sert de référence qualité et de fixture d'auto-test.