QinghongLin/data2story-skill

Agent Journaliste de Données (Data2Story)

Transformez $ARGUMENTS en un blog. Orchestre les rôles ci-dessous en séquence.

Configuration

Résolvez les chemins avant toute action :

• Ne jamais coder en dur des chemins locaux de machine et ne jamais demander à l'utilisateur d'exporter des variables de chemin.
• Résoudre SKILL_DIR = le répertoire contenant ce SKILL.md (.../skills/data2story)
• Résoudre ARCHIVE_DIR = le répertoire ancêtre qui contient skills/ (deux niveaux au-dessus de SKILL_DIR, c'est-à-dire SKILL_DIR/../..)
• Résoudre DATA2STORY_ROOT = le parent de ARCHIVE_DIR
• Les commandes ci-dessous utilisent des espaces réservés symboliques comme ARCHIVE_DIR ; remplacez-les par des chemins résolus et entre guillemets avant d'exécuter Bash.
• DATA_NAME = le nom du dossier du jeu de données (par ex. pick_a_card)
• DATA_DIR = si $ARGUMENTS est un chemin existant, utilisez ce chemin ; sinon utilisez DATA2STORY_ROOT/data/{DATA_NAME}
• TIMESTAMP = l'heure actuelle formatée comme MMDD_HHMM (par ex. 0401_1618) : date +%m%d_%H%M (exécuté dans bash)
• PROJECT_DIR = DATA2STORY_ROOT/project/{DATA_NAME}/blog_{MODEL}_{TIMESTAMP}
• Créez PROJECT_DIR/, PROJECT_DIR/assets/, PROJECT_DIR/code/

Archivage

Immédiatement après avoir créé PROJECT_DIR, prenez un instantané des compétences actuelles :

mkdir -p PROJECT_DIR/archival
cp -r ARCHIVE_DIR/skills PROJECT_DIR/archival/skills

Cela préserve les versions exactes des compétences utilisées pour cette exécution.

Outils disponibles

Tous les outils multimédia passent par OpenRouter. Définissez OPENROUTER_API_KEY avant tout appel de génération.

La génération multimédia est le travail du Designer, donc les outils multimédia (text2image, text2video, image2video, text2music, embeddings) se trouvent sous SKILL_DIR/designer/scripts/openrouter-*/. La liste complète — modèles par défaut et invocations exactes de python3 ... — se trouve dans designer/references/tools.json ; la documentation complète par outil se trouve dans le propre SKILL.md de chaque outil sous SKILL_DIR/designer/scripts/openrouter-*/.

Aperçu du Pipeline

Le pipeline est une séquence linéaire unique qui produit un blog HTML traçable à partir de données brutes :

DATA → Détective → Analyste → Rédacteur → Designer → Programmeur → Auditeur → Inspecteur → final index.html + viewer.html

Exécutez chaque étape dans l'ordre. Chaque étape lit le ou les artéfacts précédents avant de commencer. Ne passez pas à l'étape suivante tant que l'artéfact actuel n'est pas complet.

Étape 1 — Détective

Entrée : DATA_DIR Sortie : PROJECT_DIR/detective.json Quoi : Recherche le contexte externe — connaissances générales, historique du domaine, résultats connexes, pourquoi ces données sont importantes. Chaque résultat reçoit un ID det_xx.

Étape 2 — Analyste

Entrée : DATA_DIR, PROJECT_DIR/detective.json Sortie : PROJECT_DIR/code/*.py, PROJECT_DIR/analyst.json Quoi : Analyse quantitative exhaustive des données, informée par le contexte du détective. Tout le code est enregistré dans code/ sous forme de scripts exécutables. Chaque résultat reçoit un ID ana_xx avec calculation (fichier + lignes + sortie) et data_table (données prêtes pour les graphiques).

Étape 3 — Rédacteur

Entrée : PROJECT_DIR/detective.json, PROJECT_DIR/analyst.json Sortie : PROJECT_DIR/editor.md, PROJECT_DIR/editor.json Quoi : Décisions éditoriales — quels résultats sont importants, quel est l'arc narratif, ce que le blog argumente. Chaque section reçoit un ID edt_xx avec des références explicites aux résultats ana_xx et au contexte det_xx. Pas de conception visuelle.

Étape 4 — Designer

Entrée : PROJECT_DIR/editor.md, PROJECT_DIR/editor.json, PROJECT_DIR/analyst.json Sortie : PROJECT_DIR/designer.json, PROJECT_DIR/assets/* Quoi : Décisions visuelles créatives basées sur les données — comment présenter chaque point en utilisant des graphiques, images, vidéos, audio, cartes, éléments interactifs, appels de statistiques, instances, ou un traitement textuel seul lorsque approprié. Le mix médiatique doit émerger des propriétés du jeu de données, pas d'une liste de contrôle fixe. La page doit être multimédia-riche par défaut : empruntez le langage visuel du skill frontend-design partagé et utilisez les cinq canaux (graphique, image, vidéo, audio, interactif/carte) à moins que le fallback documenté d'un canal ne soit fabriqué ou purement décoratif. Chaque visuel reçoit un ID des_xx avec data_source pointant vers les data_table de ana_xx lorsqu'il est basé sur les données. Génère les actifs sélectionnés. Pas de HTML.

Étape 5 — Programmeur

Entrée : PROJECT_DIR/editor.md, PROJECT_DIR/editor.json, PROJECT_DIR/analyst.json, PROJECT_DIR/designer.json Sortie : PROJECT_DIR/index.html Quoi : Implémente le blog final en HTML. Applique le thème/accent enregistré dans designer.json page_rhythm et emprunte des recettes de composants + tokens du skill frontend-design. Résout les données des graphiques à partir des data_tables de analyst.json (PAS d'accès aux données brutes). Étiquète chaque élément avec les attributs data-edt, data-ana, data-det, data-des pour la traçabilité.

Étape 6 — Auditeur

Entrée : PROJECT_DIR/index.html Sortie : PROJECT_DIR/index.html (modifié), PROJECT_DIR/auditor.json Quoi : Détecte et corrige les problèmes de mise en page (chevauchement, espacement, alignement) sans modifier le contenu ni l'intention de conception. S'exécute automatiquement après le Programmeur pour garantir que les éléments visuels sont correctement enveloppés et espacés.

Appel : Skill auditor PROJECT_DIR

Étape 7 — Inspecteur

Entrée : PROJECT_DIR/index.html, tous les fichiers JSON Sortie : PROJECT_DIR/inspector.json, PROJECT_DIR/viewer.html Quoi : Effectue une vérification de traçabilité au niveau des phrases et génère un visualiseur interactif. Deux étapes :

python3 SKILL_DIR/inspector/scripts/verify.py PROJECT_DIR --log-errors
python3 SKILL_DIR/inspector/scripts/generate_viewer.py PROJECT_DIR

L'étape 1 produit inspector.json (mappage phrase→preuve). L'étape 2 produit viewer.html (autonome, fonctionne sur file:// — aucun serveur nécessaire). Voir inspector/SKILL.md pour les détails.

Traçabilité : flux des IDs à travers le pipeline

det_01 ──┐
det_02 ──┤
         ├──▶ ana_01 (based_on: [det_02]) ──┐
         │    ana_02 (based_on: [])          ├──▶ edt_01 (findings: [ana_01, ana_02], context: [det_01]) ──▶ des_01 (section: edt_01, data_source: ana_01)
         │    ana_03 (based_on: [det_01])    │    edt_02 (findings: [ana_03], context: [det_02])         ──▶ des_02 (section: edt_02, data_source: ana_03)
         └────────────────────────────────────┘

Chaque valeur dans le HTML final peut être tracée : HTML data-des="des_01" → designer.json des_01.data_source="ana_01" → analyst.json ana_01.calculation.code → vérifiable.

Règles de transmission

• Chaque artéfact doit être complet avant que l'étape suivante ne commence.
• Si un artéfact manque de sections requises, corrigez-le avant de continuer.
• Passerelle de richesse médiatique (après le Designer, avant le Programmeur) : designer.json doit utiliser les cinq canaux (graphique, image, vidéo, audio, interactif_ou_carte). Pour tout canal marqué used:false, confirmez que son fallback documenté a été réellement essayé et qu'une raison basée sur les données a été enregistrée dans meta.media_decisions. Si un canal a été ignoré par commodité plutôt que parce que les données ne le supportent pas, renvoyez-le au Designer avant que le Programmeur ne s'exécute.
• Tous les actifs générés vont uniquement dans PROJECT_DIR/assets/.
• Livrables finaux : PROJECT_DIR/index.html, PROJECT_DIR/detective.json, PROJECT_DIR/analyst.json, PROJECT_DIR/code/*.py, PROJECT_DIR/editor.md, PROJECT_DIR/editor.json, PROJECT_DIR/designer.json, PROJECT_DIR/inspector.json, PROJECT_DIR/viewer.html.