Agent2API 协作与发版规范

Agent2API Kollaborations- und Release-Standards

Deckt zwei Arbeitsbereiche ab: Tägliche Zusammenarbeit (Branch-Wahl, PR-Signatur, Issue-Abschluss, Abschnitte 1–3) und Release-Prozess (Versionierung, Changelog, Tag, Release, Validierung, Abschnitte 4–7), Fehlerbehebung siehe Abschnitt 8.

0. Zwei menschliche rote Linien (müssen anhalten und warten auf Bestätigung)

Die folgenden zwei Dinge müssen von einem Menschen zuerst geprüft und ausdrücklich bestätigt werden, bevor ein Agent fortfahren darf; Entwürfe können vorbereitet, Argumente können aufgelistet werden, aber es darf nicht selbstständig entschieden werden:

1. Release: Bevor der Release-Prozess begonnen wird (Änderung der Versionsnummer, Erstellung des Release-Commits, Pushen von main / beta, Erstellung von Tags, Erstellung von Releases), muss die Versionsnummer und „was dieses Release enthalten soll“ klar kommuniziert werden und auf die Bestätigung des Benutzers gewartet werden. Ohne Bestätigung darf kein Branch oder Tag gepusht werden – sobald ein Tag gepusht ist, werden Builds ausgelöst, die öffentliche Installationspakete und Images erzeugen, die nicht rückgängig gemacht werden können.
2. Changelog: Das geschriebene Changelog (die Commit-Nachricht des Release-Commits, die auch der GitHub-Release-Text ist) muss dem Benutzer zuerst Punkt für Punkt zur Durchsicht vorgelegt werden. Wenn der Benutzer Änderungen an Formulierungen, das Hinzufügen/Löschen von Einträgen oder das Anpassen von Kategorie-Präfixen wünscht, muss nach der Änderung erneut bestätigt werden; es darf nicht mit der Begründung „es wurde nicht viel geändert“ direkt committet werden.

Bei einem Release gelten beide roten Linien gleichzeitig: Es wird sowohl eine Bestätigung der Versionsnummer als auch eine Bestätigung des Changelogs benötigt; erst nachdem der Benutzer „weiter“ sagt, wird gehandelt.

1. Branch-Wahl: Täglich nur beta, Release nur auf main

Branch	Rolle	Wann wird er bearbeitet
beta	Integrations-Branch (Standard-Ziel)	Tägliche Änderungen, Mergen von PRs, Konfliktlösung – immer zuerst hierher
main	Release-Branch	Nur beim Release: Zu main wechseln, beta mergen, Tag erstellen

• Beim Mergen eines PRs beta als Base wählen, nicht main. Ein Merge in main würde noch nicht veröffentlichte Änderungen vorzeitig in den Release-Branch einbringen; später müsste man main zurück in beta mergen, was einen zusätzlichen Merge-Commit und eine zusätzliche Konfliktmöglichkeit schafft. Wenn ein PR bereits mit base=main erstellt wurde, muss die Base auf der PR-Seite zuerst auf beta geändert werden, bevor er gemergt wird.
• Lokale Änderungen werden ebenfalls an beta committet (Code schreiben, Dokumentation ändern, Konflikte lösen alles), und an origin/beta gepusht; die Überprüfung von Merge-Ergebnissen und Selbsttests werden auf beta durchgeführt.
• Nur für offizielle Releases wird zu main gewechselt: git switch main → beta mergen → Release-Commit schreiben, main pushen, Tag erstellen; der Tag muss auf main liegen. Nach dem Release wird main zurück in beta gemergt, um beide konsistent zu halten.
• Nicht eigenmächtig den Ziel-Branch wählen: Wenn der Benutzer kein Release erwähnt hat, darf nicht nach main committet oder gepusht werden, und die Base von PRs darf nicht auf main geändert werden.
• Beta-Versionen (Pre-Releases) sind die einzige Ausnahme: Es wird nicht zu main gewechselt, der Tag wird direkt auf dem beta-Branch selbst gesetzt (siehe Abschnitt 6).

2. Mergen von PRs: Beitragende korrekt kennzeichnen

Beim Mergen eines PRs eines Beitragenden muss der Commit-Autor (author) die beitragende Person selbst sein – dies entscheidet direkt, ob die Person in die Contributors-Liste auf der Repository-Startseite aufgenommen wird und ob der Beitrag im Beitragsdiagramm erscheint. Die Autorenangabe ist ein verdienter Teil des Beitrags und sollte nicht durch die Merge-Methode verloren gehen.

Die GitHub-Zuordnungsregel ist einfach: Wenn die Author-E-Mail im Commit-Kopf in der Liste der verifizierten E-Mails eines Kontos erscheint, wird dieser Commit diesem Konto zugeordnet; andernfalls wird er als anonymer Eintrag geführt und nicht in die Contributors aufgenommen. Zwei weitere Bedingungen: Die Statistik zählt nur für den Standard-Branch (hier main), Merge-Commits und leere Commits werden nicht gezählt.

• Standardmäßig den Merge-Button auf GitHub verwenden (Merge pull request / Squash and merge / Rebase and merge): Alle drei behalten den Original-Autor als Author; bei Squash werden mehrere Autoren im PR in die Co-Author-Liste aufgenommen.
• „Lokales Extrahieren und Neu-Einreichen“ ist verboten: Die Änderungen des anderen zu kopieren und selbst zu committen (lokales git merge --squash, dann selbst committen, die Änderungen neu abtippen oder den Author ändern und neu committen) ist nicht erlaubt – in diesem Fall ist der Author derjenige, der merged, und der Beitrag des Autors ist auf GitHub-Seite völlig unsichtbar. Dies ist im Repository bereits vorgekommen; nicht wiederholen.
• Wenn lokale Bearbeitung erforderlich ist (Konflikte müssen gelöst werden, oder es müssen zusätzliche Anpassungen vorgenommen werden), muss der Author korrekt gesetzt werden: Für einen einzelnen Original-Autor git commit --author="Original-Autor <Original-Autor-E-Mail>"; wenn mehrere Personen an einem Commit gearbeitet haben, am Ende der Commit-Nachricht einen Trailer Co-authored-by: Name <E-Mail> hinzufügen.
• Entfernen von AI-Co-Author-Trailern: Trailer wie Co-Authored-By: Claude Code <…> am Ende von Commit-Nachrichten von Beitragenden müssen beim Mergen entfernt werden – GitHub würde sie als Co-Autoren rendern und sie würden nach dem Einfügen in main in der Contributors-Liste erscheinen, aber AI ist kein Beitragender. Nur die Trailer-Zeile selbst wird entfernt; der Author und der Rest der Commit-Nachricht bleiben wortwörtlich erhalten; technische Erwähnungen von AI-Produkten im Text („Unterstützt Claude Code Client“, „Claude-kompatible Endpunkte“ o.ä.) sind davon nicht betroffen und bleiben unverändert. Die Entfernung betrifft die Historie des bereits gemergten Branches; es sollte frühzeitig nach dem Merge und vor dem Release durchgeführt werden (git filter-branch --msg-filter Entfernung der Zeile, dann force-push); wenn es bis nach dem Release verzögert wird, muss main neu geschrieben werden.
• Die E-Mail muss mit einem Konto verknüpft werden können: Die verifizierte Adresse aus dem GitHub-Konto des anderen verwenden; wenn der andere die Privatsphäre wahren möchte, kann die von GitHub bereitgestellte [email protected] verwendet werden (in den E-Mail-Einstellungen des Kontos des anderen einsehbar). Interne Adressen, user@hostname-E-Mails usw. können niemals mit einem Konto verknüpft werden; die Commits werden als anonym aufgezeichnet.
• Nach dem Merge kurz überprüfen: git log --format='%an <%ae>' -1 <Merge-Commit> oder auf der PR-Seite prüfen, ob der Avatar neben dem Commit auf den Original-Autor verweist.

3. Antworten auf Issues/PRs: AI-Quelle angeben

Jede Issue/PR-Antwort (auch verfasste), die von einem AI-Agenten stammt, muss am Ende in einer eigenen Zeile die Quelle angeben. Der Empfänger hat das Recht zu wissen, mit wem er spricht – das folgt dem gleichen Prinzip wie Abschnitt 2: Schreibe, wer spricht.

Feste Signatur, wortwörtlich verwenden (nicht umschreiben in vage Formulierungen wie „Roboter“ oder „Assistent“):

🤖 Diese Antwort wurde von einem AI-Agenten generiert

• Position: In der letzten Zeile der gesamten Antwort, als eigener Absatz (durch eine Leerzeile vom Rest getrennt); nicht in Textabsätze, Listen, Zitate oder Code-Blöcke einfügen – beim Zitieren der Aussage eines anderen, die Signatur nach den eigenen Worten platzieren.
• Englischer Kontext (PR/Issue von externen Beitragenden) unter der chinesischen Zeile eine weitere Zeile Generated by an AI agent. hinzufügen; es beschreibt dasselbe, keiner der Teile wird weggelassen.
• Vom Agenten selbst erstellte Issues/PRs, die Signatur ebenfalls am Ende des Texts hinzufügen.
• Auch verfasste Antworten zählen: Wenn eine Person den Agenten bittet, eine Nachricht zu übermitteln (auch wortwörtlich), wird die Signatur trotzdem hinzugefügt – sie beschreibt „von wem diese Antwort gesendet wurde“, nicht „wer sie erdacht hat“.
• Bezieht sich nur auf Issue/PR-Antworten (Kommentare, Review-Kommentare, Schließen/Zusammenführen-Beschreibungen). Commit-Nachrichten erhalten diese Zeile nicht; die Signatur-Regelung für Commits siehe Abschnitt 2.

4. Versionsnummer

• Die Versionsnummer hat das Format X.Y.Z (z.B. 2.7.2); eine tägliche Nebenversionserhöhung „um 0.01“ bedeutet +1 für die letzte Stelle (z.B. 2.7.8 → 2.7.9).
• Die Erhöhungsgröße richtet sich nach den Anforderungen des Benutzers: Standardmäßig wird die obige „Erhöhung um 0.01“ verwendet; wenn der Benutzer eine andere Anforderung hat (z.B. „diesmal um 0.1 erhöhen“), wird immer auf den Benutzer gehört, die neue Versionsnummer nach der angegebenen Größe berechnet und nicht eigenmächtig die Standardgröße angewendet.
• Die Versionsnummer muss an 5 Stellen synchron geändert werden (wenn eine Stelle fehlt, kann die Installationspaket-Version nicht mit der angezeigten Version übereinstimmen):
  1. package.json (Stammverzeichnis)
  2. desktop-tauri/package.json
  3. desktop-tauri/src-tauri/Cargo.toml
  4. desktop-tauri/src-tauri/tauri.conf.json
  5. desktop-tauri/src-tauri/server/Cargo.toml
• Die App-interne „Über“- und Update-Prüfung liest env!("CARGO_PKG_VERSION") (Stelle 5); nach der Änderung einmal cargo check ausführen, damit Cargo.lock aktualisiert wird.
• Installationsdokumentation kurz durchgehen: Die Installationsanleitung wurde bereits aus der README in docs/install.md verschoben (die README enthält nur eine Kurzübersicht + einen Link); es gibt zusätzlich 5 Übersetzungen docs/install.{en,zh-Hant,ja,ko,pt-BR}.md; alle sechs Dokumente müssen inhaltlich übereinstimmen. Wenn diese Änderung Installations-/Upgrade-/Deinstallation-Schritte, Produktdateinamen, Standard-Ports, Umgebungsvariablen oder Parameter des Installationsskripts betrifft, müssen alle sechs synchron geändert werden; wenn die Kurzübersicht in der README betroffen ist, wird sie ebenfalls geändert.

5. Ablauf für offizielle Releases

In der angegebenen Reihenfolge ausführen; die beiden roten Linien aus Abschnitt 0 gelten während des gesamten Prozesses.

# 1. Arbeitsbereich bereinigen (der Code im Tag ist der Code, der veröffentlicht wird)
git status --short        # Muss leer sein; bei Änderungen zuerst committen oder bereinigen
cargo check               # Oder bei Frontend-Änderungen einen Build-Selbsttest durchführen

# 2. Zu main wechseln und beta mergen
git switch main && git pull
git merge beta

# 3. Versionsnummer an 5 Stellen gleichzeitig ändern (Standard: letzte Stelle +1, Größe nach Benutzer); nach der Änderung Cargo.lock aktualisieren
cargo check

# 4. Release-Commit schreiben: Commit-Nachricht = Changelog
git commit -am "…Changelog…"

# 5. main pushen, Tag erstellen, Tag pushen (ein v* Tag löst alle Builds aus)
git push origin main
git tag vX.Y.Z
git push origin vX.Y.Z

# 6. Nachdem die beiden Workflows abgeschlossen sind, GitHub Release anhängen
gh run list --limit 4       # Vor manuellem gh-Lauf zuerst Proxy einrichten, siehe Abschnitt 8
bash scripts/release.sh vX.Y.Z

Die Commit-Nachricht des Release-Commits = das Changelog, da das Release-Endskript beim Erstellen/Aktualisieren des Releases den Text aus der Commit-Nachricht des Tags bezieht (git log -1 --format=%B).

• Format folgt der nummerierten Liste historischer Versionen, ein Eintrag pro Zeile, mit Kategorie-Präfix: Neu: / Optimierung: / Fix: / Aktualisierung: / Entfernt:, der letzte Eintrag ist fest Version: X.Y.Z → X.Y.Z+1;
• Inhalt wird aus allen Commits seit dem letzten Tag zusammengefasst (git log vX.Y.Z..HEAD --oneline), reine CI-/temporäre Debug-Commits werden zu einer prozessualen Beschreibung zusammengefasst;
• Wenn es keine Code-Änderungen gibt, einen leeren Commit verwenden: git commit --allow-empty -F Changelog.txt;
• Changelog-Entwürfe und historische Release-Notizen werden einheitlich in docs/release-notes/<Versionsnummer>.md geschrieben (z.B. docs/release-notes/2.9.2.md); im Stammverzeichnis des Projekts keine neuen .release-notes-*.md-Dateien erstellen – docs/release-notes/ ist bereits in der Ignore-Liste (nur dieses Verzeichnis wird ignoriert; andere Dokumente in docs/ werden normal versioniert); neue Dateien müssen keine zusätzlichen Ignore-Regeln hinzugefügt werden.

Das Pushen eines v*-Tags löst gleichzeitig zwei Workflows aus (in .github/workflows/):

Workflow	Ausgabe	Beschreibung
build.yml (build)	Desktop-Installationspakete für drei Plattformen + Linux-Server-Paket	Vier Jobs: macos (dmg) / windows (NSIS exe) / linux-desktop (deb + AppImage) / linux-server (tar.gz für Container-Updates). Die Artefakte für macOS und Linux-Desktop können nur auf ihren jeweiligen Plattformen erstellt werden, nicht per Cross-Compilation von Windows; alle Artefakte werden nur als Artifacts bereitgestellt, GitHub Release wird vom lokalen Skript erstellt
docker.yml (docker)	Docker Hub aimodcc/agent2api:<Version> + :latest (amd64 / arm64 Dual-Architektur)	Bei manuellem workflow_dispatch nur :dev-Test-Tag, keine offiziellen Tags; Beta-Tags (Version mit -) nur <Version>, :latest wird nicht verschoben

Fortschritt verfolgen:

gh run list --limit 4
gh run watch <run-id> --exit-status

Release-Abschluss: GitHub Release wird nicht von CI erstellt (Releases werden nicht automatisch erstellt), sondern durch ein lokales Skript in einem Schritt angehängt:

bash scripts/release.sh vX.Y.Z            # Automatisch den erfolgreichen Build-Run für den Tag finden
bash scripts/release.sh vX.Y.Z <run-id>   # Oder explizit den Run angeben

Das Skript macht drei Dinge: Build-Installationspaket-Artifacts herunterladen nach dist/ → GitHub Release mit der Tag-Commit-Nachricht (= Changelog) erstellen/aktualisieren und Anhänge hinzufügen → Validierungshinweis ausgeben. Idempotent und wiederholbar (--clobber überschreibt Anhänge).

6. Beta-Version (Pre-Release)

Die App verfügt über einen Schalter „Einstellungen → Software-Updates → Update-Einstellungen → Beta-Programm beitreten“: Personen, die ihn aktiviert haben, erhalten Beta-Updates; Personen, die ihn nicht aktiviert haben, sehen nur offizielle Veröffentlichungen.

Eine Beta-Version ist keine separate Pipeline, sondern eine Variante des Prozesses aus Abschnitt 5 – der einzige strukturelle Unterschied ist, dass der Tag mit einem Pre-Release-Suffix vom beta-Branch aus erstellt wird; Commit, Tag, Release und Validierung bleiben wortwörtlich gleich. Die beiden roten Linien aus Abschnitt 0 gelten ebenfalls.

# 1. Auf dem beta-Branch arbeiten (Beta-Version berührt kein main)
git switch beta && git pull
git status --short          # Muss leer sein

# 2. Versionsnummer an 5 Stellen gleichzeitig auf die Form „wortwörtlich identisch mit dem Tag“ ändern:
#    Tag ist v3.1.0-beta.1 → alle 5 Stellen schreiben 3.1.0-beta.1 (Liste siehe Abschnitt 4)
cargo check                 # Cargo.lock gleichzeitig aktualisieren

# 3. Committen und beta-Branch pushen (Commit-Nachricht = Changelog dieser Beta, Format wie Abschnitt 5)
git commit -am "…Beta-Changelog…"
git push origin beta

# 4. Tag erstellen und pushen: Tag liegt auf dem Commit des beta-Branches
git tag v3.1.0-beta.1
git push origin v3.1.0-beta.1

# 5. Nachdem die beiden Workflows abgeschlossen sind, Release anhängen (Skript erkennt `-` im Tag und markiert automatisch als Pre-Release)
gh run list --limit 4
bash scripts/release.sh v3.1.0-beta.1

Die Validierung umfasst nur drei Punkte: Release zeigt Prerelease an, exe / dmg / deb / AppImage-Anhänge sind vollständig, und die Pushed-Zeit von :latest auf Docker Hub hat sich nicht geändert (vollständige Liste siehe Abschnitt 7).

Drei Dinge dürfen nicht falsch sein, jedes mit klaren Symptomen:

1. Versionsnummer an den 5 Stellen ohne Suffix (geschrieben als 3.1.0): Der Vergleich erfolgt semantisch; die laufende Version 3.1.0 wird gegen den Online-Tag 3.1.0-beta.1 als „aktuell neuer als online“ bewertet, Beta-Benutzer erhalten nie ein Update. Alle fünf Dateien akzeptieren Versionen mit Suffix (Cargo / npm / tauri.conf.json erkennen sie), einfach nach Tag abschreiben.
2. Release nicht als Pre-Release markiert: Die Markierung ist die Grenze des Schalters – der offizielle Kanal geht über /releases/latest von GitHub, der Pre-Releases ausschließt; nur Personen mit aktiviertem Schalter sehen die Beta in der /releases-Liste. Fehlende Markierung = Beta wird von allen offiziellen Benutzern als offizielles Update empfangen. scripts/release.sh markiert automatisch basierend auf „Tag enthält -“, und beim erneuten Ausführen des Abschlussskripts wird die Markierung korrigiert – wenn das Skript verwendet wird, muss man sich keine Sorgen machen.
3. Tag auf main erstellt: Beta ist der Integrations-Branch; eine Beta-Version benötigt seinen Snapshot. Ein Tag auf main enthält entweder nicht die neuen Änderungen des beta-Branches (verschwendeter Test) oder bedeutet, dass noch nicht veröffentlichte Änderungen vorzeitig in main gebracht werden.

:latest von Docker wird nicht durch Beta-Tags verschoben (.github/workflows/docker.yml); die Images werden weiterhin mit dem Version-Tag 3.1.0-beta.1 erstellt; wer sie ausprobieren möchte, zieht sie nach Versionsnummer.

Drei häufige Folgeschritte:

• Weitere Beta veröffentlichen: Kernnummer unverändert, laufende Nummer erhöhen (3.1.0-beta.2, alle 5 Stellen ändern, die obigen Befehle wiederholen). Pre-Release-Nummern haben eine Reihenfolge (beta.2 > beta.1); diejenigen, die bereits auf der Beta sind, erhalten trotzdem das Update – daher muss auch zwischen Betas „Tag und Versionsnummer wortwörtlich identisch“ sein.
• Offiziell machen (Version 3.1.0 offiziell veröffentlichen): Nach Abschnitt 5 auf main vorgehen, Versionsnummer an den 5 Stellen ohne Suffix. Beta-Benutzer wechseln nicht automatisch zurück zur offiziellen Version: Personen mit aktiviertem Schalter sehen nur Pre-Release-Versionen (die Filterung pick_listed_release prüft, „ob die aktuell laufende Version eine Beta ist oder nicht“); die offizielle 3.1.0 ist für sie kein Update – diejenigen, die im Beta-Kanal bleiben möchten, warten auf die nächste Beta (3.2.0-beta.1 erscheint und sie erhalten sie); wer zur offiziellen Version zurückkehren möchte, schaltet den Schalter selbst aus; nach dem Ausschalten erhält er nur dann ein Update, wenn eine offizielle Version mit einer höheren Versionsnummer als die laufende Beta veröffentlicht wird (3.1.0 > 3.1.0-beta.1, aber eine ältere 3.0.9 wird ihn nicht downgraden).
• „Aktiviert, aber keine Reaktion“: Wenn es im Repository noch kein Pre-Release gibt, zeigt das Aktivieren des Schalters nur die offizielle Version – erst nach der ersten Beta-Ausgabe zeigt er Wirkung.

7. Validierungs-Checkliste

• GitHub Release: gh release view vX.Y.Z (vor manuellem gh-Lauf Proxy einrichten, siehe Abschnitt 8) – Changelog ist vollständig, alle vier Desktop-Anhänge sind vorhanden: Windows Agent2API_<Version>_x64-setup.exe, macOS Agent2API_<Version>_universal.dmg, Linux Agent2API_<Version>_amd64.deb und Agent2API_<Version>_amd64.AppImage (zusätzlich zwei agent2api-server-linux-*.tar.gz + .sha256, das sind Container-Update-Pakete, siehe Abschnitt 5);
• Linux-Desktop: Installation des deb (oder chmod +x und Ausführen des AppImage) startet die App, und das Panel „Einstellungen → Software-Updates“ kann die Version erkennen und den entsprechenden Installationseinstieg für das Paketformat anbieten (deb → Systeminstaller, AppImage → Datei ersetzen);
• Docker Hub: Die Tags-Seite von aimodcc/agent2api zeigt <Version> und latest an, die Pushed-Zeiten sind identisch;
• Die Versionsnummer auf der „Über“-Seite des Installationspakets stimmt mit dem Tag überein;
• Die Installationsdokumentation stimmt mit dem tatsächlichen Produkt überein: docs/install.md und die 5 Übersetzungen haben die gleichen Produktdateinamen, Ports, Befehle, Umgebungsvariablen wie dieses Release (die Kurzübersichten in der README ebenfalls);
• Bei Beta-Versionen zusätzlich: Release zeigt Prerelease an, und latest auf Docker Hub hat sich nicht bewegt.

8. Bekannte Fallstricke und Fehlerbehebung

• GHCR neue Pakete standardmäßig privat: Falls Images in Zukunft zu GHCR verschoben werden, muss nach dem ersten Push die Paket-Einstellung manuell auf Public geändert werden (aktuell wird Docker Hub verwendet, kein Problem).

• gh liest keine git-Proxy-Konfiguration; vor gh-Ausführung Proxy-Umgebungsvariablen setzen: gh ist ein Go-Programm, liest nicht die http(s).proxy-Einstellung in ~/.gitconfig und nicht den Windows-System-Proxy (WinINET); es erkennt nur die Umgebungsvariablen HTTPS_PROXY / HTTP_PROXY. Wenn die direkte Verbindung zu GitHub zeitweise funktioniert und zeitweise nicht, vor der manuellen Ausführung von gh-Befehlen den Proxy setzen:

  export HTTPS_PROXY=$(git config --get-urlmatch http.proxy https://github.com || git config --get https.proxy)
  

  Nur HTTPS_PROXY zu setzen reicht aus (gh-Anfragen sind alle HTTPS, Tests zeigen, dass HTTP_PROXY nicht gelesen wird). scripts/release.sh enthält diesen Schritt bereits (liest aus der git-Konfiguration und führt ihn an gh weiter); bei Verwendung des Skripts für Releases muss der Proxy nicht manuell gesetzt werden. Wenn der Proxy nicht läuft, meldet gh sofort proxyconnect tcp: ... connection refused und fällt nicht auf eine direkte Verbindung zurück – das Verhalten ist identisch mit git push.