Deploymentcenter BotandClaude Opus 5
5f9b0c5596
Watchdog-Anleitung vollständig überarbeitet - Alle drei Codebeispiele trugen das geseedete Demo-Token fest im Quelltext. Es ist an die Source "srv-db-01" gebunden — wer es übernommen hätte, wäre für jeden anderen Dienst abgewiesen worden. Jetzt Umgebungsvariable und eine Anleitung, wie man ein eigenes Token erzeugt. - Der Ratschlag "sende beim Beenden einen Ping mit Status stopped" beschrieb etwas, das die API nicht konnte. Statt die Anleitung an die Lücke anzupassen, ist die Lücke geschlossen: status akzeptiert jetzt "stopped" und "maintenance". Der Evaluator lässt solche Monitore in Ruhe, statt wenige Minuten nach jedem sauberen Shutdown einen Fehlalarm zu erzeugen. - Neu dokumentiert: checks (Gesundheitszustand per Push, ohne offene Ports), metrics samt Verlauf und Abweichungsvergleich, Alarmunterdrückung über die Hierarchie, die Schwellen des Evaluators (2x warning, 4x down) und der erforderliche Cron-Job. Lizenz-Anleitung - Neuer Abschnitt zum Antwortformat. Die Lizenz-Endpunkte antworten bewusst ohne den status/error-Umschlag der übrigen API; das Feld status auf oberster Ebene trägt den Lizenzzustand. Genau diese Besonderheit hatte ich beim Umbau übersehen, weshalb sie jetzt ausdrücklich festgehalten ist — samt Tabelle aller Zustände. - Ergänzt: Deaktivierung braucht den shared_key, mit Beispiel für den .NET- Client und curl. Verhalten bei Ratenbegrenzung. UpdateService-Anleitung - Prüf-Endpunkte dokumentiert (check, latest, releases) samt Antwortformat. - Tabelle zum Versionsvergleich mit den Fällen, die vorher falsch liefen. - Auto-Resolve beim Veröffentlichen beschrieben. Agent-Prompt-Vorlage - Fehler-Schnittstelle ergänzt, inklusive Hinweis auf "ignored": true, damit ein Agent bekannte Fehler nicht untersucht. Alle in der Dokumentation genannten API-Pfade und Scopes wurden maschinell gegen Routing und TokenManager abgeglichen. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
146 lines
4.5 KiB
Markdown
146 lines
4.5 KiB
Markdown
# Agent-Prompt-Vorlage
|
|
|
|
Diesen Abschnitt in `CLAUDE.md`, `AGENTS.md` oder `.cursorrules` des jeweiligen
|
|
Projekts einfügen.
|
|
|
|
---
|
|
|
|
```markdown
|
|
## Zentraler Bugtracker — Deployment Center
|
|
|
|
Erfasse unbehandelte Fehler, geplante Verbesserungen und Ideen im zentralen
|
|
Deployment Center. Basis-URL: `https://dc.mhdf.de`
|
|
|
|
### Zugang
|
|
Token steht in der Umgebungsvariable `DC_TOKEN`.
|
|
Header: `Authorization: Bearer $DC_TOKEN`
|
|
|
|
Die vollständige Schnittstellenbeschreibung liegt maschinenlesbar unter
|
|
`GET /api/openapi.json`, das Handbuch unter `/docs/`.
|
|
|
|
### Projekt bestimmen
|
|
`GET /api/bugtracker/v1/projects` liefert alle Slugs.
|
|
Bekannt: `deploymentcenter`, `myapp`, `polytrader`, `predictalytics`.
|
|
Fällt dir ein Fehler im Deployment Center selbst auf, melde ihn unter
|
|
`deploymentcenter`.
|
|
|
|
### Etwas melden
|
|
`POST /api/bugtracker/v1/report`
|
|
|
|
```json
|
|
{
|
|
"project_slug": "myapp",
|
|
"type": "bug",
|
|
"title": "Kurze, aussagekräftige Zusammenfassung",
|
|
"description": "Unter welchen Bedingungen tritt es auf?",
|
|
"error_message": "Exakte Fehlermeldung",
|
|
"stack_trace": "Vollständiger Stacktrace",
|
|
"severity": "high",
|
|
"environment": "production",
|
|
"build_version": "v1.4.2",
|
|
"repo_url": "https://git.example.com/me/myapp.git",
|
|
"git_branch": "main",
|
|
"commit_sha": "a21536f",
|
|
"file_path": "src/Core/UserAuthService.cs",
|
|
"line_no": 42,
|
|
"client_ref": "eindeutige-id-dieses-laufs"
|
|
}
|
|
```
|
|
|
|
**Setze immer `client_ref`** — ein wiederholter Aufruf mit demselben Wert legt
|
|
kein Duplikat an. Gib nach Möglichkeit `file_path` und `line_no` an; das spart
|
|
dem nächsten Agenten das Parsen des Stacktrace.
|
|
|
|
Schweregrade: `idea` (Gedanke für später), `wishlist` (Backlog),
|
|
`low`, `medium`, `high`, `critical`.
|
|
|
|
### Laufzeitfehler automatisch melden
|
|
Für den globalen Exception-Handler einer Anwendung gibt es einen schlankeren
|
|
Eingang — Titel und Dringlichkeit leitet der Server ab:
|
|
|
|
`POST /api/errors/v1/report`
|
|
|
|
```json
|
|
{
|
|
"project_slug": "myapp",
|
|
"exception": "PDOException",
|
|
"message": "Exakte Fehlermeldung",
|
|
"stack_trace": "...",
|
|
"level": "error",
|
|
"build": "v1.4.2",
|
|
"environment": "production",
|
|
"file": "src/Core/Service.php",
|
|
"line": 42
|
|
}
|
|
```
|
|
|
|
`level`: `fatal` (Prozess beendet), `error` (Vorgang fehlgeschlagen, Programm
|
|
läuft weiter), `warning`.
|
|
|
|
Gleiche Fehler werden zu einer Gruppe zusammengefasst und hochgezählt;
|
|
veränderliche Anteile wie Schlüsselwerte, Adressen und Zeitstempel werden dabei
|
|
ausgeblendet. Kommt `"ignored": true` zurück, ist der Fehler als bekannt und
|
|
harmlos eingestuft — dann nicht weiter untersuchen, sondern nur zählen lassen.
|
|
|
|
### Arbeit übernehmen
|
|
Bevor du an einem Item arbeitest, übernimm es — sonst arbeiten zwei Agenten
|
|
parallel am selben Problem:
|
|
|
|
```
|
|
POST /api/bugtracker/v1/manage?action=next
|
|
Body: {"project_slug": "myapp", "limit": 1}
|
|
```
|
|
|
|
Antwortet der Server mit `409 already_claimed`, nimm das nächste Item.
|
|
|
|
### Fortschritt festhalten
|
|
```
|
|
POST /api/bugtracker/v1/manage?action=comment&id=<ID>
|
|
Body: {"comment": "Was du herausgefunden hast", "action_taken": "investigated"}
|
|
```
|
|
|
|
`action_taken`: `investigated`, `fix_proposed`, `pr_opened`, `needs_human`,
|
|
`blocked`.
|
|
|
|
### Abschließen
|
|
```
|
|
POST /api/bugtracker/v1/manage?action=resolve&id=<ID>
|
|
Body: {"resolved_in_build": "v1.4.3", "resolution_notes": "Was geändert wurde"}
|
|
```
|
|
|
|
Kommst du nicht weiter, gib das Item zurück statt es blockieren zu lassen:
|
|
```
|
|
POST /api/bugtracker/v1/manage?action=release&id=<ID>
|
|
Body: {"note": "Grund"}
|
|
```
|
|
|
|
### Release melden
|
|
Nach einem Release schließen sich Items mit passendem `resolved_in_build`
|
|
automatisch:
|
|
```
|
|
POST /api/updateservice/v1/publish
|
|
Body: {"product_slug": "myapp", "version": "1.4.3",
|
|
"download_url": "...", "sha256_hash": "...", "git_commit": "..."}
|
|
```
|
|
|
|
### Fehlerbehandlung
|
|
Antworten haben die Form `{"status":"error","error":{"code":"…"}}`.
|
|
Reagiere auf `code`, nicht auf den Text:
|
|
- `401 unauthorized` — Token prüfen, nicht wiederholen
|
|
- `409 already_claimed` — nächstes Item nehmen
|
|
- `429 rate_limited` — Intervall verdoppeln, später erneut
|
|
```
|
|
|
|
---
|
|
|
|
## Kurzfassung für knappe Prompt-Budgets
|
|
|
|
```markdown
|
|
Melde Fehler und Ideen an https://dc.mhdf.de/api/bugtracker/v1/report
|
|
(Header `Authorization: Bearer $DC_TOKEN`, JSON mit project_slug, type, title,
|
|
description, error_message, stack_trace, severity, file_path, line_no,
|
|
client_ref). Vor der Arbeit an einem Item: POST .../manage?action=next zum
|
|
Übernehmen. Danach ?action=resolve mit resolved_in_build.
|
|
Vollständige Beschreibung: https://dc.mhdf.de/api/openapi.json
|
|
```
|