Deploymentcenter BotandClaude Opus 5
a8b9f6f7c9
Bisher musste ein Agent, der eine Anbindung aktualisiert, die gesamte Historie lesen - oder er las gar nichts und uebersah eine brechende Aenderung. Beides schlecht. - public/docs/changelog.json ist die einzige Quelle. Je Fassung eine Zusammenfassung, je Aenderung Bereich, ein "breaking"-Kennzeichen und vor allem ein Feld "action" mit dem, was konkret zu tun ist. Steht dort null, ist nichts zu tun - das ist die haeufigste und nuetzlichste Antwort. - GET /api/updateservice/v1/changelog?since=2.2.0 liefert nur die neueren Fassungen, dazu die Anzahl der Punkte mit Handlungsbedarf und der brechenden Aenderungen. count:0 heisst "du bist auf Stand" - dann muss gar nichts gelesen werden. Optional nach Bereich filterbar (?area=packager). - /docs/changelog.php rendert dieselbe Datei fuer Menschen, mit Eingabefeld fuer die eigene Fassung. Bewusst dieselbe Quelle: zwei Fassungen zu pflegen hiesse, sie auseinanderlaufen zu lassen. - DeploymentcenterSdk.Version im SDK ist der Bezugspunkt. Damit muss die Fassung nicht abgetippt werden. - AGENT_PROMPT_TEMPLATE.md verpflichtet dazu, sie in der AGENTS.md des Projekts festzuhalten und vor jeder Aenderung an der Anbindung den Unterschied abzufragen. Auch in der Kurzfassung fuer knappe Prompt-Budgets. Die Historie ist rueckwirkend bis 2.0.0 gefuellt: 6 Fassungen, 25 Punkte mit Handlungsbedarf, 13 brechende Aenderungen. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
95 lines
4.4 KiB
Markdown
95 lines
4.4 KiB
Markdown
# Deploymentcenter — Entwickler- und Agenten-Dokumentation
|
|
|
|
Zentrale Plattform für Lizenzverwaltung, Software-Updates, Infrastruktur-
|
|
Monitoring und einen Bugtracker, den Coding-Agenten selbständig bedienen.
|
|
|
|
---
|
|
|
|
## Zuerst lesen
|
|
|
|
| Dokument | Wofür |
|
|
|---|---|
|
|
| **[UPGRADE.md](./UPGRADE.md)** | **Ablaufplan für die Umstellung auf 2.0.** Enthält Pflichtschritte: Zugangsdaten wechseln, Migration, Evaluator-Cron. |
|
|
| **[Änderungen](../public/docs/changelog.json)** | Was sich je Fassung geändert hat und was zu tun ist. Öffentlich unter `/docs/changelog.php`, maschinenlesbar über `GET /api/updateservice/v1/changelog?since=X` |
|
|
| **[Release-Anleitung für Agenten](../public/docs/release.md)** | Ein Projekt veröffentlichungsfähig machen: Vorlage kopieren, konfigurieren, ausliefern |
|
|
| [Agent-Prompt-Vorlage](./AGENT_PROMPT_TEMPLATE.md) | Textbaustein für `CLAUDE.md` / `AGENTS.md` eines Projekts |
|
|
| [Agenten-Handbuch](../public/docs/bugtracker.md) | Vollständige Beschreibung des Bugtracker-Workflows, öffentlich unter `/docs/` |
|
|
|
|
## Modul-Handbücher
|
|
|
|
- **[Lizenzsystem (Hardware-ID v2)](./LICENSE_INTEGRATION_GUIDE.md)** — Hardware-Anbindung, Schlüsselvalidierung, Offline-Cache, CLI, Windows und Linux/Docker
|
|
- **[Watchdog (Heartbeat & Telemetrie)](./WATCHDOG_INTEGRATION_GUIDE.md)** — Überwachung von Anwendungen, Diensten und Infrastruktur
|
|
- **[UpdateService](./UPDATESERVICE_INTEGRATION_GUIDE.md)** — Release-Verteilung und Update-Prüfung
|
|
- **[Erstinstallation](./SETUP_INTEGRATION_GUIDE.md)** — `setup.json`, Installationskonto, `update-agent --action install`
|
|
- **[Bugtracker](./BUGTRACKER_INTEGRATION_GUIDE.md)** — Anbindung aus Anwendungen heraus
|
|
|
|
---
|
|
|
|
## Modulübersicht
|
|
|
|
| Modul | Aufgabe | Endpunkte | Authentifizierung |
|
|
|---|---|---|---|
|
|
| **Bugtracker** | Fehler, Feature Requests und Ideen; Agenten-Workflow mit Claim/Lease | `/api/bugtracker/v1/report`<br>`/api/bugtracker/v1/projects`<br>`/api/bugtracker/v1/manage` | Token mit `bugtracker:*` |
|
|
| **UpdateService** | Release-Verteilung, semantischer Versionsvergleich | `/api/updateservice/v1/check`<br>`/api/updateservice/v1/publish` | Lesen offen, Publish braucht `updateservice:publish` |
|
|
| **Watchdog** | Heartbeat-Monitoring, Zustandsbewertung, Alarmierung | `/api/watchdog/v1/ping`<br>`/api/watchdog/v1/evaluate` | Token mit `watchdog:ping` |
|
|
| **Lizenzen** | Lizenzprüfung, Hardware-ID v2, Offline-Cache | `/api/license/v1/validate`<br>`/api/license/v1/deactivate` | Validierung offen, Deaktivierung authentifiziert |
|
|
| **Tokens** | Selbst-Provisionierung von Sub-Tokens | `/api/tokens/v1/provision` | Master-Token |
|
|
| **Setup** | Erstinstallation: Anmeldung, Katalog, Anwendungstoken | `/api/setup/v1/login`<br>`/api/setup/v1/catalog`<br>`/api/setup/v1/token` | Login offen, Rest `setup:*` |
|
|
| **System** | Verfügbarkeit, Schema-Status, Schnittstellenbeschreibung | `/api/health`<br>`/api/openapi.json` | Health optional, OpenAPI offen |
|
|
|
|
---
|
|
|
|
## Schnittstelle maschinenlesbar
|
|
|
|
```
|
|
GET https://dc.mhdf.de/api/openapi.json
|
|
```
|
|
|
|
Ein Agent kann sich daran selbst orientieren — der früher fest im WebUI
|
|
hinterlegte Textblock entfällt damit.
|
|
|
|
---
|
|
|
|
## Antwortformat
|
|
|
|
Alle JSON-Endpunkte antworten einheitlich:
|
|
|
|
```json
|
|
{ "status": "success", "…": "…" }
|
|
```
|
|
|
|
```json
|
|
{ "status": "error", "error": { "code": "already_claimed", "message": "…" } }
|
|
```
|
|
|
|
Der `code` ist stabil und für Programme gedacht; die `message` richtet sich an
|
|
Menschen und kann sich ändern.
|
|
|
|
---
|
|
|
|
## Betrieb
|
|
|
|
| Aufgabe | Befehl |
|
|
|---|---|
|
|
| Deployment | `python scripts/deploy.py` |
|
|
| Migration | `php public/install_db.php` oder WebUI → System → DB-Migration |
|
|
| Evaluator (Cron, minütlich) | `curl -fsS -H "Authorization: Bearer <SHARED_KEY>" https://dc.mhdf.de/api/watchdog/v1/evaluate` |
|
|
| Zustand prüfen | `curl https://dc.mhdf.de/api/health` |
|
|
| Logs | `var/log/dc-<datum>.log` auf dem Server |
|
|
|
|
## Aufbau
|
|
|
|
```
|
|
config/ Zugangsdaten (nicht versioniert), Vorlage in config.example.php
|
|
src/ Anwendungscode, PSR-4 unter dem Namensraum Deploymentcenter\
|
|
Core/ Bootstrap, Konfiguration, DB, Auth, CSRF, HTTP, Tokens, Migrator
|
|
Modules/ Bugtracker, License, UpdateService, Watchdog, Notify
|
|
public/ Webroot-Inhalte: WebUI, API-Endpunkte, öffentliche Dokumentation
|
|
sql/ Schema und Migrationen (fortlaufend nummeriert)
|
|
var/log/ Laufzeitprotokolle
|
|
scripts/ Deployment
|
|
```
|
|
|
|
Neue Klassen werden automatisch geladen, sobald sie dem Namensraum-Pfad
|
|
entsprechen — eine `require`-Zeile ist nicht mehr nötig.
|