Zum Hauptinhalt springen

ZeroClaw erweitern und dazu beitragen

1. Beginne mit der kleinsten Erweiterungsoberfläche​

Die Upstream-Architekturdokumentation und der Contribution-Guide legen stark nahe, dass du nicht damit beginnen solltest, die Runtime-Schleife direkt zu patchen. Beginne mit der schmalsten Oberfläche, die bereits existiert.

In der Praxis fällt die meiste Arbeit in einen dieser Bereiche:

ZielErste Anlaufstelle
Eine neue Modellfamilie oder ein Wire-Protokoll hinzufĂĽgencrates/zeroclaw-providers/
Eine neue Chat- oder Ingress-Plattform hinzufĂĽgencrates/zeroclaw-channels/
Eine neue Agent-Aktion hinzufĂĽgencrates/zeroclaw-tools/
Das Verhalten der Betreiber-Konfiguration verbesserncrates/zeroclaw-config/
Die Terminal-UX verbessernzerocode/
Prosa-Dokumentation aktualisierendocs/book/src/ im Upstream-Repo

Dieses Muster existiert aus einem Grund: Das Projekt will fähigkeitsspezifische Logik am Rand, nicht Sonderfälle vergraben in der Runtime.

2. Lerne den Trait-Vertrag vor der Implementierung​

Die wichtigsten öffentlichen Verträge leben in zeroclaw-api. Selbst wenn du nur eine konkrete Integration änderst, hilft es zu verstehen, ob du es zu tun hast mit:

  • einem Provider-Trait-Vertrag,
  • einem Channel-Trait-Vertrag,
  • einem Tool-Trait-Vertrag.

Wenn du diesen Schritt überspringst, ist es leicht, Code zu schreiben, der lokal funktioniert, aber gegen die Architektur ankämpft.

3. First-Party-Erweiterungsleitfaden​

Die offizielle First-Party-Erweiterungsdokumentation trifft eine nĂĽtzliche Unterscheidung:

  • eingebaute Fähigkeiten gehören in Core-Crates, wenn sie Teil des Baseline-Vertrags von ZeroClaw sind oder eine enge Sicherheits-/Runtime-Integration brauchen,
  • externe Integrationen sind möglicherweise besser als Plugins, Skills, MCP-Server oder CLI-gestĂĽtzte Workflows aufgehoben.

Das ist eine wichtige Denkweise für Beitragende. Nicht jede neue Fähigkeit sollte zu einem dauerhaften Built-in werden.

4. Was Beitragende lesen sollen​

Der Upstream-Contribution-Guide weist Beitragende ausdrĂĽcklich an, Folgendes zu lesen:

  • die AGENTS.md im Repo-Root,
  • die Architektur-/Contribution-Karte,
  • den RFC-Prozess fĂĽr größere Ă„nderungen.

Das ist ein starkes Signal dafĂĽr, dass ZeroClaw Contribution-Disziplin als Teil der Architektur behandelt, nicht als Projekt-Trivia.

5. Erwartungen an Tests und Codequalität​

Der Contribution-Guide nennt diese Erwartungen:

  • cargo fmt sauber
  • cargo clippy -D warnings sauber
  • kein unwrap() oder expect() in Produktionspfaden, es sei denn, die Invariante ist gerechtfertigt
  • minimale Abhängigkeiten
  • Trait-first-Design
  • Security-by-Default
  • Inline-Unit-Tests und breitere Integrationsabdeckung, wo angebracht

Der dokumentierte Workspace-Test-Befehl ist:

cargo nextest run --locked --workspace --exclude zeroclaw-desktop

FĂĽr Dokumentation und generierte Referenzen merkt der Upstream-Guide auĂźerdem an, dass einige Referenzseiten generiert werden und nicht von Hand bearbeitet werden sollten.

6. Disziplin bei Dokumentation und generierten Referenzen​

Wenn du zur Upstream-Dokumentation beiträgst, zieht der Guide eine Grenze zwischen:

  • Prosa-Dokumentation in docs/book/src/**/*.md
  • generierten Referenzseiten fĂĽr CLI und Konfiguration

Das ist wichtig, weil "die Docs fixen" zwei sehr unterschiedliche Workflows bedeuten kann:

  • das Bearbeiten einer handgeschriebenen Konzeptseite,
  • das Neugenerieren der Referenzausgabe aus der Codebase.

FĂĽr den zweiten Fall verweist der Guide auf:

cargo mdbook refs

7. PR-Workflow und Review-Erwartungen​

Der Upstream-Contribution-Guide dokumentiert einen konventionellen Ablauf:

fork -> branch -> commit -> push -> open PR -> review -> merge

Ein paar Review-Erwartungen stechen hervor:

  • PRs zielen auf master
  • das PR-Template ist wichtig
  • Validierungsnachweise sind erforderlich
  • größere Ă„nderungen brauchen möglicherweise zuerst einen RFC
  • Reviewer nutzen eine explizite Taxonomie fĂĽr blockierende Probleme, Warnungen, Vorschläge und gelöste Findings

Das ist hilfreicher Kontext, wenn du an lockerere OSS-Repos gewöhnt bist. ZeroClaw präsentiert sich als Projekt mit einer echten Betriebsdisziplin.

8. Beste erste Beiträge​

Wenn du einen produktiven Weg in die Codebase suchst, schlägt die offizielle Dokumentation Bereiche vor wie:

  • neue Channel-Arbeit
  • neue Provider-Arbeit
  • Dokumentation
  • Ăśbersetzungen
  • Hardware-UnterstĂĽtzung

In der Praxis sind die einfachsten Einstiege meist:

  1. Dokumentation,
  2. eine fokussierte Provider- oder Channel-Verbesserung,
  3. eine eng abgegrenzte Tool- oder Config-Erweiterung.

Direkt in runtime-weite Refactorings zu springen, ist meist der langsamste Weg zu einem erfolgreichen ersten PR.

9. Ein praktischer Contributor-Workflow​

FĂĽr eine erste ernsthafte Upstream-Ă„nderung ist eine gute Sequenz:

  1. lies den ArchitekturĂĽberblick,
  2. lies den Contribution-Guide und die RFC-Erwartungen,
  3. finde den kleinsten zuständigen Crate,
  4. kopiere das Muster einer benachbarten bestehenden Implementierung,
  5. halte den PR schmal,
  6. fĂĽge echte Validierungsnachweise bei.

Das passt dazu, wie das Projekt heute dokumentiert und reviewt wird.