Zur HagiTask-Community beitragen

Für wen: Beitragende und Verantwortliche für HagiTask-Community-Aufgaben.

Voraussetzungen:

Sie haben hagitask-community-packages geklont und Node.js/npm eingerichtet.
Sie können den verschachtelten hagitask-Checkout dieses Repositorys initialisieren.
Sie sind mit JSON, Markdown und Git-Pull-Requests vertraut.

Diese Seite enthält die vollständige Anleitung für Beitragende. Das README von Community Packages beschränkt sich auf Zuständigkeiten des Repositorys sowie Verzeichnis- und Befehlsreferenzen.

Zuständigkeiten der Repositorys und Veröffentlichungsablauf

Community Packages ist die maßgebliche Quelle für Community-Aufgabendefinitionen. Beitragende bearbeiten data/<taskId>/; HagiTask verwaltet das gemeinsame Paketschema. HagiTask Site liest einen festgelegten Commit von Community Packages, normalisiert die Daten und erzeugt:

/index.json: einen kompakten Katalog zum Entdecken von Aufgaben.
/tasks/<taskId>.json: Detaildokumente mit vollständigen Ressourcen und Kompatibilitätsinformationen.
/packages/<taskId>.zip: Archive zur Installation durch die Anwendung.

Diese JSON- und ZIP-Dateien sind generierte Artefakte. Erstellen oder bearbeiten Sie sie nicht von Hand in Community Packages. Das Archiv enthält das gesamte Verzeichnis data/<taskId>/, sodass neue Ressourcen in diesem Verzeichnis mit dem Paket veröffentlicht werden.

1. Schema und Repository vorbereiten

Führen Sie im Repository Community Packages Folgendes aus:

git submodule update --init --recursive
npm install

Die maßgebliche Quelle für das gemeinsame Paketschema liegt unter repos/hagitask/schemas/task-preset-plugin/. Community Packages nutzt sie über einen verschachtelten Checkout. Kopieren oder ändern Sie das Schema nicht in Community Packages oder HagiTask Site.

2. Aufgabenpaket erstellen

Legen Sie neue Aufgaben unter data/<taskId>/ ab. Die taskId muss eindeutig, dauerhaft und in kleingeschriebener Kebab-Case-Schreibweise sein. Sie muss stets exakt mit taskPresetId in manifest.json übereinstimmen. Wird das Verzeichnis umbenannt, ändern sich auch die veröffentlichten URLs für Details und Archiv.

Zu den derzeit veröffentlichten kanonischen IDs gehören:

Anzeigename	`taskId`
UI Master	`ui-master`
AgentsMD	`claude-md-update`
Last 30 Days	`last30days`
Ponytail	`ponytail`
Goal	`goal`
OpenSpec Spec Compress	`openspec-spec-compress`

agentsmd und portytail sind lediglich geläufige Aliasnamen, keine Aufgaben-IDs des Protokolls.

data/<taskId>/
  manifest.json
  frontend/
    panel.json
    commands.json                 # nur erforderlich, wenn ein Befehlsverzeichnis angeboten wird
  backend/
    task-preset.json
    prompts.json
    templates/<locale>/
      system.md
      user.hbs
  locales/
    en-US.json
    zh-CN.json
  store-page/
    index.en-US.md
    index.zh-CN.md

Erforderlich sind manifest.json, frontend/panel.json, backend/task-preset.json, backend/prompts.json, die englischen und chinesischen Locale-Dateien, beide Store-Seiten sowie Prompt-Vorlagen für jede deklarierte Sprache. Fügen Sie commands.json nur hinzu, wenn das Paket tatsächlich ein Befehlsverzeichnis bereitstellt.

Wie Dateien den Katalog beeinflussen

Quelldatei	Veröffentlichtes Ergebnis
`version` in `manifest.json`	Version in Katalog und Details
`owner` in `manifest.json`	Herausgeber
`localization` in `manifest.json`	Vom Client geladenes Locale-Bundle
`requirements` in `backend/task-preset.json`	Aufgabenanforderungen und daraus abgeleitete Kompatibilitätsinformationen
`title` / `summary` der Store-Seite	Mehrsprachiger Name, Zusammenfassung und Beschreibung
`catalog` / `tags` der englischen Store-Seite	Kategorie und Tags

Fehlt catalog auf der englischen Seite, wird für die Kategorie zunächst das erste Tag und danach General verwendet. Für die Erzeugung der Katalogkategorien und Tags werden nur catalog und tags der englischen Seite berücksichtigt.

3. Schema referenzieren und Ressourcen ausfüllen

Behalten Sie in jeder JSON-Datei den passenden $schema-Eintrag mit der öffentlichen Schema-URL bei:

https://tasks.hagicode.com/schemas/task-preset-plugin/<schema>.schema.json

Welche Datei welches Schema verwendet, ist unter hagitask/schemas/task-preset-plugin/ festgelegt. In manifest.json müssen Aufgaben-ID, Version, Herausgeber, Lokalisierungs-Bundle sowie Pfade zu Frontend- und Backend-Ressourcen deklariert sein. Die Locale-Dateien müssen denselben Satz an Schlüsseln enthalten.

store-page/index.en-US.md und index.zh-CN.md benötigen mindestens die Frontmatter-Felder locale, slug, title und summary. Tragen Sie catalog und tags auf der englischen Seite ein, da die Veröffentlichungswebsite daraus Kategorien und Tags erzeugt.

4. Versionierung und Validierung

Ändern Sie bei jeder Änderung an bereits veröffentlichten Inhalten die version in manifest.json gemäß semantischer Versionierung. Verwenden Sie keine frühere Versionsnummer erneut, da sonst Katalogmetadaten und Paketprüfsumme nicht mehr eindeutig zugeordnet werden können.

Führen Sie die vorhandene Validierung aus:

npm run validate

Der Validator prüft kanonische IDs, Schema, Ressourcendeklarationen, Lokalisierungsabdeckung, Prompt-Vorlagen und die Frontmatter der Store-Seiten. Beheben Sie Fehler in den Quelldateien unter data/<taskId>/. Bearbeiten Sie weder /index.json noch /tasks/<taskId>.json oder /packages/<taskId>.zip: Diese Artefakte werden bei jeder Veröffentlichung von HagiTask Site erzeugt.

Der Validierungsworkflow läuft bei Pull Requests mit Änderungen am Paketinhalt sowie bei Pushes auf main. Schlägt die Validierung fehl, kann das Paket nicht zusammengeführt werden.

Um den Veröffentlichungsvertrag zusätzlich zu prüfen, können Sie im hagitask-site-Checkout Folgendes ausführen:

npm install
npm run typecheck
npm run build
npm run stage:schemas
npm run verify

Beim Website-Build werden die Daten erneut normalisiert und gegen die Veröffentlichungsschemas geprüft. Ein erfolgreicher Build bedeutet, dass der generierte Katalog und die Details die Verträge community-index-v1 und community-task-detail-v1 erfüllen.

5. Pull Request einreichen

Reichen Sie den Pull Request in hagitask-community-packages ein, nicht in hagitask-site oder hagitask. Nach dem Zusammenführen aktualisiert HagiTask Site den referenzierten Commit von Community Packages und generiert Katalog, Details und ZIP-Archive erneut.

hagitask ist für das gemeinsame Schema und die integrierten Vorlagen verantwortlich. Wenn der Paketformatvertrag selbst geändert werden muss, schlagen Sie die Schemaänderung separat im HagiTask-Repository vor. Community Packages pflegt nur die Quelldaten unter data/; die Website veröffentlicht nur die generierten Ergebnisse.

Bei fehlgeschlagener Validierung

Beheben Sie den gemeldeten Fehler in den Quelldateien unter data/<taskId>/:

Fehler im Paketschema: Korrigieren Sie die betreffende JSON-Datei; entfernen Sie $schema nicht und lockern Sie die Validierung nicht.
Fehlende Ressourcen oder Locale-Dateien: Stimmen Sie Manifest, Locale-Dateien, Prompt-Vorlagen oder Store-Seiten mit den deklarierten und tatsächlich vorhandenen Dateien ab.
Schemafehler bei Katalogdetails oder Archiv: Prüfen Sie das Quellpaket und die Eingabedaten für die Normalisierung auf der Website, statt generierte JSON-Dateien zu korrigieren.

Liegt der Fehler im Schemavertrag selbst, schlagen Sie eine Vertragsänderung im HagiTask-Repository vor, statt das Schema in diesem Repository zu duplizieren.

Nächster Schritt: HagiTask installieren oder HagiTask verwenden.