iPolloWork Video-Komponentenentwicklungsspezifikation
Geliefert wird eine Komponente, die in ein Video eingefügt, über ein gemeinsames Formular angepasst, dem Projektthema folgt und von KI verarbeitet werden kann. Erstelle keinen separaten Editor, kein Parameterpanel, keinen Renderer und kein Host-Plugin für eine einzelne Komponente.
1. Vor Beginn: Der aktuelle Code-Vertrag ist maßgeblich
Lies im Stammverzeichnis des iPolloWork-Repositorys die Datei AGENTS.md und die Wartungsspezifikationen. Suche zuerst nach ähnlichen Komponenten und entscheide dann, ob du sie erweiterst oder eine neue erstellst. Die folgenden Pfade beziehen sich auf das Stammverzeichnis des Repositorys:
vendor/hyperframes/registry/blocks/world-map/: Referenz für Karten, Themenvererbung und strukturierte Daten.vendor/hyperframes/registry/blocks/metric-signal/: Referenz für Datenanzeige und optionale Animationsrezepte.vendor/hyperframes/packages/core/src/registry/types.ts: Komponentenkategorien und Manifest-Verträge.vendor/hyperframes/packages/core/src/registry/componentData.ts: Gemeinsame Datenstrukturen und Parsing-Regeln.vendor/hyperframes/packages/core/schemas/registry-item.json,packages/types/src/hyperframes.ts: Registrierungselemente und Host-Validierungsverträge.vendor/hyperframes/packages/studio/src/utils/blockInstaller.ts: Tatsächliche Installation, Theme- und Variableinbindung.
Kopiere diese Schemas nicht und erstelle keinen weiteren Datensatzprotokoll. Wenn die Spezifikation vom Code abweicht, überprüfe zuerst die aktuellen Konsumenten und rate nicht anhand alter Beispiele auf die Schnittstellen.
2. Minimale Lieferstruktur
In der Regel reicht es, unter vendor/hyperframes/registry/blocks/<slug>/ abzulegen:
registry-item.json # Metainformationen, Variablen, Kategorien, Dateien und Fähigkeitsdeklarationen
<slug>.html # Darstellung und Animation
Füge bei Bedarf lokale Bilder, Schriftarten, Daten oder Vorschaudateien hinzu; alle für die Installation erforderlichen Dateien müssen in files deklariert werden, wobei der Pfad relativ zum Paket bleibt. Registriere dich in der bestehenden Datei vendor/hyperframes/registry/registry.json und erstelle keinen separaten Komponentenverzeichnisdienst.
Im Produkt werden sie allgemein als „Komponenten" bezeichnet, aber der zugrunde liegende Typ muss korrekt sein: Karten, Ranglisten usw. mit eigener Leinwand und Dauer sind normalerweise hyperframes:block; Fragmente, die in eine vorhandene Szene eingefügt werden, sind hyperframes:component. Vollständige Projektvorlagen sind eine andere Art der Lieferung und werden nicht vermischt.
3. Variablen: Wenig und nützlich, gemeinsames Formular
- Deklariere im Manifest unter
variablesstabileids, verständlichelabels, Typen und Standardwerte, die mit dem HTML-data-composition-variablesübereinstimmen. - Verwende die vorhandenen Typen
string / number / color / boolean / enum; gib für Zahlen sinnvolle Bereiche, für Enums Optionen und für lange Texte Längenbeschränkungen an. Füge keine Objekttypen eigenmächtig hinzu. - Lege nur Inhalte, Daten, Hervorhebungen und notwendige Layout-Entscheidungen des Benutzers offen; mache nicht jeden CSS-Wert zu einem Parameter. Farben stammen standardmäßig aus dem Design und der Benutzer sollte nicht gezwungen sein, sie einzeln anzupassen.
- Verwende
update: livenur für Parameter, die sofort aktualisiert werden können; verwende für Änderungen an der Struktur oder Animation den bestehenden Mechanismusrebuild / reload; die Deklaration muss mit dem tatsächlichen Verhalten übereinstimmen. - Verwende den vorhandenen Variablenaktualisierungsmechanismus; nach einer Aktualisierung sollten DOM und Animation die neuen Werte widerspiegeln und die aktuelle Wiedergabeposition des Hosts beibehalten. Ändere nicht nur den Text, während die Zeitleiste noch auf das alte Element zeigt.
- Verwende gemeinsame Variablenformulare und Datentabellen; schreibe kein neues Panel für eine einzelne Komponente. Systemsteuerungsfelder wie
motionCueTimesundmotionStylewerden nicht als normale Benutzerparameter behandelt.
4. Daten: Struktur für KI, Tabelle für Benutzer
Datenkomponenten wie Karten, Routen, Diagramme und Ranglisten verwenden visualComponent.data, um Spalten, Semantik, Zeilen-IDs, Zeilenbeschränkungen und Bindungen zu deklarieren. Verwende die vorhandenen Typen category-value / region-value / point-value / route-value / series-value und wähle den Typ, der wirklich zu den Daten passt.
Die Standarddaten für KI sind:
{
"version": 1,
"kind": "region-value",
"rows": [
{ "region": "China", "value": 96 },
{ "region": "Japan", "value": 77 }
]
}
Die Spaltennamen werden von columns dieser Komponente bestimmt; nicht alle Komponenten verwenden fest region. rowId ist stabil und eindeutig, Zahlen bleiben als Zahlentyp; Einheiten, Genauigkeit, Hervorhebung und Ersetzungs-/Überschreibungssemantik werden gemäß dem bestehenden Vertrag deklariert.
binding.variable muss einer echten Variable entsprechen. Intern können die vorhandenen Kodierungen json / key-value-list / route-value-list / label-detail-list verwendet werden, aber sie werden von einer gemeinsamen Adapterschicht konvertiert; der Benutzer muss keine Kommas, Doppelpunkte oder ähnliche Zeichenfolgen von Hand eingeben. Erstelle keinen weiteren, nicht synchronisierten JSON-Status. Gib bei ungültigen Daten klare Hinweise; unterdrücke keine Zeilen stillschweigend und generiere keine fiktiven Werte.
5. Design & Kategorisierung
- Deklariere
visualComponent.version: 1,themeMode: inheritund füllesurfacesentsprechend den Fähigkeiten aus; bevorzugevideo; behaupte keine Unterstützung für PPT oder Web, bevor es nicht verifiziert ist. - Verwende die aktuellen
VISUAL_COMPONENT_CATEGORIES, z. B. Kartenmaps, Datendata, Architektur/Pyramidendiagrams. Für Ein- und Ausblendungen kann auch der vorhandenelibrarySectionverwendet werden; erstelle kein eigenes Kategorie-Baumsystem. - Verwende vorhandene Design-Variablen, z. B.
--ipw-color-bg,--ipw-color-surface,--ipw-color-text,--ipw-color-primary,--ipw-color-border,--ipw-font-display,--ipw-font-body,--ipw-card-radius. - Erlaube Fallback-Werte für die unabhängige Vorschau, aber überschreibe nicht das vom Host übergebene Design. Nach einem Designwechsel sollten Hintergrund, Text, Grafiken, Rahmen und Schriftarten harmonisch wechseln; Ausnahmen für semantische Farben von Daten müssen einen klaren Grund haben.
- Halte die Hierarchie klar, die Abstände angemessen und die Lesbarkeit in chinesischer Sprache gegeben. Verwende bei Bedarf dezente Farbverläufe oder Glas-Effekte, aber ersetze keine Informationsdarstellung durch Effekte.
6. Animation & Zeitleiste
- Standard: HTML + CSS + GSAP; bevorzuge die Wiederverwendung vorhandener Grafiken und lokaler SVGs. Ziehe Three.js nur in Betracht, wenn eindeutig echtes 3D benötigt wird; füge keine schweren Abhängigkeiten für einfache Karten hinzu.
- Verwende den bestehenden Mechanismus für den composition-Root-Knoten, die Größe, die Dauer und die Installation; registriere dich in der angehaltenen GSAP-Zeitleiste unter
window.__timelines[compositionId], die von HyperFrames für Play, Pause und Seek gesteuert wird. - Selektoren, Status und Zeitleisten jeder Instanz beeinflussen nur sich selbst. Bereinige alte Animationen beim Neuerstellen und überschreibe keine anderen Instanzen.
- Zum gleichen Zeitpunkt muss das gleiche Bild angezeigt werden: Verwende keine unabhängigen Timer, automatisch abspielenden Schleifen, nicht fixierten Zufallszahlen oder CSS-Auto-Animationen für Schlüsselinhalte. Echte Bilder, Audio und Video folgen der vorhandenen Medienzeitsynchronisation.
- Animationen dienen der Erklärungsreihenfolge: Klar erscheinen, hervorheben, verweilen, ausgehen; Text und Daten lassen genügend Lesezeit. Vermeide für alle Komponenten die gleiche Eingangsanimation und vermeide auch Dauerbewegungen um der Effekte willen.
- Normale Komponenten müssen kein
motionRecipehinzufügen. Verwende es nur, wenn die KI Animationsrezepte basierend auf dem Voice-Over aufrufen soll; dann folge den unterstützten Rezeptverträgen; Ereignisse, Cue-Bindungen und tatsächliche Elemente müssen übereinstimmen; Kapazitäts- und Textbeschränkungen müssen realistisch sein; erfinde keine Sprachaufnahmezeiten.
7. KI-Bearbeitungsraum
Verwende visualComponent.ai.slots, um stabile bearbeitbare Bereiche zu deklarieren und füge im HTML an den entsprechenden Stellen data-ipw-ai-slot hinzu. instructions erklären kurz den Zweck, die Eingaberegeln und die zu erhaltende Struktur.
Unterstütze KI beim Ersetzen von Inhalten, Anpassen des Layouts, Verkleinern einer Karte und Hinzufügen von Erläuterungen daneben; behalte Variablen-IDs, Datenbindungen, Designvererbung und Zeitleistenintegration bei. Erzwinge nicht, dass alle Bearbeitungen zu Formularparametern werden, und pflege keine separate Darstellung für KI.
Externer Text wird als Text behandelt und nicht in ausführbares HTML eingefügt; führe keine Skripte in Eingabedaten aus und bette keine Schlüssel ein. Bei referenzierten Ressourcen wie Karten, Schriftarten und Bildern müssen Quelle und Lizenz erhalten bleiben; fehlende Materialien werden klar angegeben, ohne stillschweigend online ersetzt zu werden.
8. Abnahme & Lieferung
- Manifest, HTML-Variablen, KI-Slots, Datenbindungen und Installationspfade sind konsistent und bestehen die entsprechende Validierung im aktuellen Repository sowie die betroffenen Tests.
- Die Komponente kann im vorhandenen Studio installiert werden; das gemeinsame Formular kann die tatsächliche Darstellung ändern; die Datentabelle kann gültige Zeilen hinzufügen, bearbeiten und löschen.
- Prüfe Standard-, Grenz-, Null-, lange chinesische, fehlerhafte Daten und beide Designs; mehrere Instanzen beeinflussen sich nicht gegenseitig.
- Prüfe Wiedergabe von Anfang an, Seek in der Mitte, Zurückspulen zum Start und Seek nach Parameteraktualisierung; Darstellung und Zeitleiste müssen übereinstimmen.
- Exportiere mit echtem Material ein kurzes Video und bestätige, dass die Browser-Vorschau mit der Ausgabe übereinstimmt; bestehe den Test nicht nur mit einem Screenshot.
- Liefere die Komponentendateien, notwendige Ressourcen mit Quellen, Parameter-/Datenbeispiele, tatsächliche Testergebnisse und nicht verifizierte Punkte. Kopiere nicht das Studio, ändere nicht das Verhalten bestehender Vorlagen und hinterlasse keine alternativen Implementierungen.
Diese Spezifikation dient nur der Komponentenentwicklung. Die Veröffentlichung auf npm, das Ändern von Host-Plugins, das Einreichen von PRs oder das Hochladen in den Komponenten-Markt muss gemäß der Benutzerautorisierung und den vorhandenen Veröffentlichungsprozessen separat behandelt werden.