QinghongLin/data2story-skill

Data Journalist Agent (Data2Story)

Verwandle $ARGUMENTS in einen Blog. Orchestriert die folgenden Rollen nacheinander.

Einrichtung

Löse Pfade auf, bevor du etwas tust:

• Hartcodiere niemals maschinenlokale Pfade und bitte den Benutzer nicht, Pfadvariablen zu exportieren.
• Löse SKILL_DIR auf = das Verzeichnis, das diese SKILL.md enthält (.../skills/data2story)
• Löse ARCHIVE_DIR auf = das übergeordnete Verzeichnis, das skills/ enthält (zwei Ebenen über SKILL_DIR, d.h. SKILL_DIR/../..)
• Löse DATA2STORY_ROOT auf = das Elternverzeichnis von ARCHIVE_DIR
• Die folgenden Befehle verwenden symbolische Platzhalter wie ARCHIVE_DIR; ersetze sie vor dem Ausführen von Bash durch aufgelöste, in Anführungszeichen gesetzte Pfade.
• DATA_NAME = der Name des Datensatzordners (z.B. pick_a_card)
• DATA_DIR = wenn $ARGUMENTS ein vorhandener Pfad ist, verwende diesen Pfad; andernfalls verwende DATA2STORY_ROOT/data/{DATA_NAME}
• TIMESTAMP = aktuelle Zeit formatiert als MMDD_HHMM (z.B. 0401_1618): date +%m%d_%H%M (in bash ausführen)
• PROJECT_DIR = DATA2STORY_ROOT/project/{DATA_NAME}/blog_{MODEL}_{TIMESTAMP}
• Erstelle PROJECT_DIR/, PROJECT_DIR/assets/, PROJECT_DIR/code/

Archivierung

Direkt nach der Erstellung von PROJECT_DIR einen Snapshot der aktuellen Skills erstellen:

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

Dies bewahrt die genauen Skill-Versionen, die für diesen Lauf verwendet wurden.

Verfügbare Werkzeuge

Alle Medienwerkzeuge werden über OpenRouter geleitet. Setze OPENROUTER_API_KEY vor jedem Generierungsaufruf.

Die Mediengenerierung ist die Aufgabe des Designers, daher befinden sich die Medienwerkzeuge (text2image, text2video, image2video, text2music, embeddings) unter SKILL_DIR/designer/scripts/openrouter-*/. Die vollständige Liste – Standardmodelle und exakte python3 ...-Aufrufe – befindet sich in designer/references/tools.json; die vollständige Dokumentation pro Tool befindet sich in der eigenen SKILL.md jedes Tools unter SKILL_DIR/designer/scripts/openrouter-*/.

Pipeline-Überblick

Die Pipeline ist eine einzige lineare Sequenz, die aus Rohdaten einen nachvollziehbaren HTML-Blog erzeugt:

DATA → Detective → Analyst → Editor → Designer → Programmer → Auditor → Inspector → final index.html + viewer.html

Führe jede Stufe der Reihe nach aus. Jede Stufe liest das/die vorherige(n) Artefakt(e), bevor sie beginnt. Fahre erst mit der nächsten Stufe fort, wenn das aktuelle Artefakt vollständig ist.

Stufe 1 — Detective

Eingabe: DATA_DIR Ausgabe: PROJECT_DIR/detective.json Was: Recherchiert externen Kontext – Hintergrundwissen, Domänengeschichte, verwandte Erkenntnisse, warum diese Daten wichtig sind. Jede Erkenntnis erhält eine det_xx-ID.

Stufe 2 — Analyst

Eingabe: DATA_DIR, PROJECT_DIR/detective.json Ausgabe: PROJECT_DIR/code/*.py, PROJECT_DIR/analyst.json Was: Erschöpfende quantitative Analyse der Daten, basierend auf dem Kontext des Detectives. Der gesamte Code wird als ausführbare Skripte in code/ gespeichert. Jede Erkenntnis erhält eine ana_xx-ID mit calculation (Datei + Zeilen + Ausgabe) und data_table (diagrammbereite Daten).

Stufe 3 — Editor

Eingabe: PROJECT_DIR/detective.json, PROJECT_DIR/analyst.json Ausgabe: PROJECT_DIR/editor.md, PROJECT_DIR/editor.json Was: Redaktionelle Entscheidungen – welche Erkenntnisse wichtig sind, was der erzählerische Bogen ist, was der Blog argumentiert. Jeder Abschnitt erhält eine edt_xx-ID mit expliziten Verweisen auf ana_xx-Erkenntnisse und det_xx-Kontext. Kein visuelles Design.

Stufe 4 — Designer

Eingabe: PROJECT_DIR/editor.md, PROJECT_DIR/editor.json, PROJECT_DIR/analyst.json Ausgabe: PROJECT_DIR/designer.json, PROJECT_DIR/assets/* Was: Datengesteuerte kreative visuelle Entscheidungen – wie jeder Punkt präsentiert wird, unter Verwendung von Diagrammen, Bildern, Video, Audio, Karten, interaktiven Elementen, Statistikhinweisen, Instanzen oder nur Textbehandlung, wo angemessen. Die Medienmischung sollte aus den Eigenschaften des Datensatzes hervorgehen, nicht aus einer festen Checkliste. Die Seite sollte standardmäßig multimedia-reich sein: Entlehne die visuelle Sprache aus dem gemeinsamen frontend-design-Skill und verwende alle fünf Kanäle (Diagramm, Bild, Video, Audio, interaktiv/Karte), es sei denn, der dokumentierte Fallback eines Kanals wäre erfunden oder rein dekorativ. Jedes visuelle Element erhält eine des_xx-ID mit data_source, das auf ana_xx data_tables zeigt, wenn datengesteuert. Generiert ausgewählte Assets. Kein HTML.

Stufe 5 — Programmierer

Eingabe: PROJECT_DIR/editor.md, PROJECT_DIR/editor.json, PROJECT_DIR/analyst.json, PROJECT_DIR/designer.json Ausgabe: PROJECT_DIR/index.html Was: Implementiert den finalen Blog in HTML. Wendet das in designer.json page_rhythm aufgezeichnete Design/Farbschema an und entlehnt Komponenten- und Token-Rezepte aus dem frontend-design-Skill. Löst Diagrammdaten aus den analyst.json data_tables auf (KEIN Zugriff auf Rohdaten). Versieht jedes Element mit data-edt, data-ana, data-det, data-des-Attributen für die Nachvollziehbarkeit.

Stufe 6 — Auditor

Eingabe: PROJECT_DIR/index.html Ausgabe: PROJECT_DIR/index.html (modifiziert), PROJECT_DIR/auditor.json Was: Erkennt und behebt Layoutprobleme (Überlappung, Abstände, Ausrichtung), ohne Inhalt oder Designabsicht zu ändern. Wird automatisch nach dem Programmierer ausgeführt, um sicherzustellen, dass visuelle Elemente ordnungsgemäß umschlossen und beabstandet sind.

Aufruf: Skill auditor PROJECT_DIR

Stufe 7 — Inspector

Eingabe: PROJECT_DIR/index.html, alle JSON-Dateien Ausgabe: PROJECT_DIR/inspector.json, PROJECT_DIR/viewer.html Was: Führt eine Überprüfung der Nachvollziehbarkeit auf Satzebene durch und generiert einen interaktiven Viewer. Zwei Schritte:

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

Schritt 1 erzeugt inspector.json (Satz→Beleg-Zuordnung). Schritt 2 erzeugt viewer.html (eigenständig, funktioniert mit file:// – kein Server erforderlich). Siehe inspector/SKILL.md für Details.

Nachvollziehbarkeit: ID-Fluss durch die 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)
         └────────────────────────────────────┘

Jeder Wert im finalen HTML ist zurückverfolgbar: HTML data-des="des_01" → designer.json des_01.data_source="ana_01" → analyst.json ana_01.calculation.code → überprüfbar.

Übergaberegeln

• Jedes Artefakt muss vollständig sein, bevor die nächste Stufe beginnt.
• Fehlen in einem Artefakt erforderliche Abschnitte, repariere es, bevor du fortfährst.
• Medienreichhaltigkeits-Gate (nach Designer, vor Programmierer): designer.json sollte alle fünf Kanäle (Diagramm, Bild, Video, Audio, interaktiv_oder_Karte) nutzen. Für jeden als used:false markierten Kanal bestätige, dass sein dokumentierter Fallback tatsächlich versucht wurde und ein datenbasierter Grund in meta.media_decisions aufgezeichnet wurde. Wurde ein Kanal aus Bequemlichkeit übersprungen und nicht, weil die Daten ihn nicht unterstützen, sende ihn zurück an den Designer, bevor der Programmierer läuft.
• Alle generierten Assets gehen nur in PROJECT_DIR/assets/.
• Finale Liefergegenstände: 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.