Deploymentcenter BotandClaude Opus 5
60731c5104
Die Testwege waren beschrieben, aber nicht begehbar. Auf der Test-VM lag die Anleitung vom 26.08. ohne das gesamte Testkit-Kapitel, ein Laufzeit-Token ohne Rechte, und ein Testkit, das 236 Zeilen aelter war als das ausgelieferte - beide meldeten 1.0.0. Deshalb sagte "doctor" dort "Bereit", waehrend nichts davon lauffaehig war. Vier Fehler, die beim Nachpruefen herauskamen: * doctor brach unter "set -e" wortlos ab. Der Rueckgabewert von version_lt wurde nicht aufgefangen - das beendet die Sitzung, sobald der Server neu genug ist (Rueckgabewert 1, also der Normalfall). Token und Projekt wurden nie geprueft. * Die Konfigurationsdatei ueberschrieb die Umgebung, genau umgekehrt zur dokumentierten Rangfolge. "DC_PROJECT=x dc-testkit report" meldete stillschweigend in das Projekt aus der Datei. * Der doctor-Bericht ging teils auf stderr. Ueber SSH werden beide Kanaele getrennt uebertragen und beim Aufrufer verschraenkt - die Befunde standen unter der falschen Ueberschrift. Genau so liest ein Pruefagent den Bericht. * "~/bin" liegt ueber SSH nicht im PATH: .profile wird nur von einer Login-Shell gelesen. Die Antwort war "Kommando nicht gefunden" - das sieht aus wie ein fehlgeschlagener Bezug und ist keiner. Neu im Testkit (1.1.0): * selfupdate mit --pruefen. Unterscheidet die Richtung: Eine neuere lokale Fassung ist ein Entwicklungsstand und kein Grund zum Update; der Rueckschritt wird verweigert (--force hebt es auf). Gleiche Nummer bei anderem Inhalt ist ein Befund, kein Achselzucken - genau daran ist es unbemerkt vorbeigelaufen. * doctor prueft den eigenen Stand, die Herkunft des Tokens, die fehlende Projektbindung, die Oberflaechenwerkzeuge und das eigene Display. * display start|stop|status und shot: der generische Teil des Verfahrens aus 5.8. Das sind die drei Stellen, an denen Eigenbau-Skripte danebengreifen - :0 statt eigenem Display, pkill ohne Nummer, Dateinamen ohne Projektpraefix. * DC_PROJECT_DIR: Das Werkbank-Token kommt aus der .mcp.json des Projekt-Repos, wo es fuer den MCP-Adapter ohnehin liegt. Kein zweiter Ablageort, der beim naechsten Wechsel vergessen wird. Fehlt die Datei, sagt das Testkit warum - sie ist gitignored und kommt ueber Git nie mit. dc-testkit-remote (neu): Der Agent laeuft auf dem Arbeitsplatz, der Testlauf auf der VM. Der Wrapper haelt das Token aus "ps aux" der geteilten Maschine (es geht ueber die Standardeingabe in die Umgebung), ruft bash -l, schuetzt die Argumente vor drei Ebenen Quoting und buendelt ganze Pruefplaene in eine Verbindung. Auf der VM wird keine Konfiguration mehr gelesen - was dort liegt, bleibt wirkungslos. Doku: TESTUMGEBUNG.md auf den Remote-Betrieb umgestellt, 4.2 auf den realen Ablageort der Token, neuer 4.8 "Ein Agent, der nur prueft", Belegung in 7 von der Maschine erhoben statt fortgeschrieben. Baustein E in der Prompt-Vorlage zieht die Rollengrenze, die serverseitig noch kein Recht zieht: bugtracker:manage erlaubt auch resolve. Richtiggestellt: Ein Token OHNE Projektbindung ist nicht eingeschraenkt, sondern uneingeschraenkt. Der Server leitet kein Heimatprojekt ab, also zaehlt jede Meldung als Heimmeldung - ohne Begruendungspflicht, ohne Deckelung auf medium, ohne triage_external, ohne reported_from. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
260 lines
10 KiB
Markdown
260 lines
10 KiB
Markdown
# Ein Projekt und seinen Agenten anbinden
|
||
|
||
**Für dich, nicht für den Agenten.** Diese Datei beschreibt, was einmalig je
|
||
Projekt zu tun ist, damit ein Coding-Agent Bugtracker, Roadmap, MCP-Adapter und
|
||
die Testwege sinnvoll benutzt.
|
||
|
||
Der Agent selbst bekommt Textbausteine aus
|
||
[AGENT_PROMPT_TEMPLATE.md](AGENT_PROMPT_TEMPLATE.md) — nicht diese Datei.
|
||
|
||
Reihenfolge einhalten. Jeder Schritt setzt den vorigen voraus.
|
||
|
||
---
|
||
|
||
## Was ein Agent am Ende können soll
|
||
|
||
Damit klar ist, worauf die Schritte hinauslaufen — der Ablauf einer Sitzung:
|
||
|
||
| | Der Agent tut | Womit |
|
||
|---|---|---|
|
||
| 1 | Nachsehen, was ansteht und wer schon dransitzt | `dc_roadmap` |
|
||
| 2 | Ein Item exklusiv übernehmen | `dc_next_task` |
|
||
| 3 | Prüfen, ob es ein Prüfauftrag ist statt einer Fehlerbehebung | Status am Item |
|
||
| 4 | Arbeiten, Fortschritt festhalten | `dc_comment` |
|
||
| 5 | Was ihm nebenbei auffällt, dort melden, wo die Ursache liegt | `dc_report` |
|
||
| 6 | Abschließen oder zurückgeben | `dc_resolve` / `dc_release` |
|
||
| 7 | Ein neues Vorhaben einplanen | `dc_report` + `dc_roadmap_set` |
|
||
|
||
Was er **nicht** tun soll: eine `TODO.md` anlegen, Status in eine Markdown-Datei
|
||
schreiben, ein verworfenes Vorhaben erneut vorschlagen, ohne die Begründung
|
||
gelesen zu haben.
|
||
|
||
---
|
||
|
||
## 1. Werkbank-Token anlegen
|
||
|
||
**Erst nachsehen, ob es schon eines gibt.** Für ein angebundenes Projekt steht
|
||
es in der `.mcp.json` des Repos, unter `env.DC_TOKEN` — dort braucht der
|
||
MCP-Adapter es ohnehin. Ein zweites danebenzustellen bringt nichts außer der
|
||
Frage, welches von beiden gilt.
|
||
|
||
Im WebUI: **Token-Verwaltung → ➕ Token erstellen**.
|
||
|
||
Die Ansicht hieß bis 2.7.0 „Master-Token erstellen" — deshalb war das
|
||
Werkbank-Token dort nicht zu finden. Es entsteht an derselben Stelle, nur mit
|
||
anderem Identitätstyp.
|
||
|
||
| Feld | Wert |
|
||
|---|---|
|
||
| Typ (`owner_type`) | `dev_agent` |
|
||
| Projekt | das Projekt — **nicht leer** |
|
||
| Scopes | `bugtracker:manage`, `supervisor:read`, `watchdog:read` |
|
||
|
||
`supervisor:manage` nur, wenn der Agent Befunde auch abhaken soll.
|
||
`license:dev` und `updateservice:read` nur für die Test-VM (Schritt 5).
|
||
|
||
**Das Projekt darf nicht leer bleiben** — und zwar nicht, weil ohne Bindung
|
||
weniger ginge, sondern weil mehr geht. Der Server leitet aus ihr das
|
||
Heimatprojekt ab. Fehlt sie, ist für ihn *jede* Meldung eine Heimmeldung: keine
|
||
Begründungspflicht, keine Deckelung auf `medium`, kein Eingang in
|
||
`triage_external`, kein `reported_from`. Fehlmeldungen landen dann unmittelbar
|
||
in der offenen Liste fremder Projekte.
|
||
|
||
Kein hypothetischer Fall: Genau so ein Token lag bis zum 31.08.2026 auf der
|
||
Test-VM, `dev_agent` und ohne Projekt. Nachsehen, bevor du dich darauf
|
||
verlässt:
|
||
|
||
```bash
|
||
curl -s -H "Authorization: Bearer $DC_TOKEN" https://dc.mhdf.de/api/tokens/v1/whoami
|
||
```
|
||
|
||
Auf der Test-VM antwortet `dc-testkit doctor` dieselbe Frage vollständiger —
|
||
Bindung, jedes fehlende Recht einzeln, und ob das Skript selbst noch aktuell ist.
|
||
|
||
**Je Projekt ein eigenes Token.** Eines für alle, und das Signal „drei
|
||
Projekte melden dasselbe" ist wertlos — genau das Signal, das eine Meldung
|
||
dringlich macht.
|
||
|
||
**Kein Master-Token an einen Agenten.** Er darf melden, übernehmen und
|
||
abschließen; er darf keine Releases veröffentlichen und keine Tokens ausstellen.
|
||
|
||
---
|
||
|
||
## 2. MCP-Adapter einrichten
|
||
|
||
Der Adapter ist eine Datei ohne Abhängigkeiten. Kein `npm install`.
|
||
|
||
**Claude Code** — `.mcp.json` im Projektverzeichnis:
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"deploymentcenter": {
|
||
"command": "node",
|
||
"args": ["J:/Softwareprojekte/Deploymentcenter/mcp/deploymentcenter-mcp.mjs"],
|
||
"env": { "DC_TOKEN": "dc_..." }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Claude Desktop** — `%APPDATA%\Claude\claude_desktop_config.json`, absoluter
|
||
Pfad, `DC_PROJECT` setzen, danach Desktop **vollständig** beenden und neu
|
||
starten. Einzelheiten in [../mcp/README.md](../mcp/README.md).
|
||
|
||
Prüfen, ohne Claude zu starten:
|
||
|
||
```bash
|
||
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | node mcp/deploymentcenter-mcp.mjs
|
||
```
|
||
|
||
Erwartet: 15 Werkzeuge. Kommt nichts, liegt es am Pfad oder daran, dass `node`
|
||
nicht im PATH steht.
|
||
|
||
---
|
||
|
||
## 3. Die Bausteine in die Projektdatei
|
||
|
||
In `CLAUDE.md` bzw. `AGENTS.md` des Projekts, aus
|
||
[AGENT_PROMPT_TEMPLATE.md](AGENT_PROMPT_TEMPLATE.md):
|
||
|
||
| Lage | Bausteine |
|
||
|---|---|
|
||
| Mit `.mcp.json` | **A** + **B** |
|
||
| Test-VM, Agent entwickelt und testet | **A** + **D** |
|
||
| Test-VM, Agent **prüft nur** | **A** + **E** |
|
||
| Ohne MCP | **A** + **C** |
|
||
|
||
**Nicht alles einkopieren.** Wo der Adapter läuft, tragen die Werkzeuge ihre
|
||
Beschreibung selbst; Baustein C wären zweihundert Zeilen, die das Modell nie
|
||
liest und die auseinanderlaufen, sobald sich die Schnittstelle ändert.
|
||
|
||
Danach einmal `dc_link_project` aufrufen — dann ist zentral beantwortbar,
|
||
welche Projekte von einem SDK-Fehler betroffen sind.
|
||
|
||
---
|
||
|
||
## 4. Die Roadmap des Projekts übernehmen
|
||
|
||
Nur, wenn es eine `ROADMAP.md`, `TODO.md` oder eine Sammlung von
|
||
Planungsdokumenten gibt. Verfahren in
|
||
[ROADMAP_MIGRATION.md](ROADMAP_MIGRATION.md), sechs Schritte.
|
||
|
||
Für Dateien im Format dieses Projekts nimmt
|
||
[../scripts/roadmap_import.py](../scripts/roadmap_import.py) die Arbeit ab:
|
||
|
||
```bash
|
||
python scripts/roadmap_import.py --lesen
|
||
```
|
||
|
||
**Immer zuerst.** Dabei fällt auf, was die Datei falsch behauptet. Bei der
|
||
Übernahme des Deploymentcenters selbst kam heraus: drei Einträge längst
|
||
erledigt, eine Kennung doppelt vergeben, ein Themenbereich nicht angelegt, und
|
||
eine erfundene Beispiel-Itemnummer im Fließtext, die ein echtes Item in einem
|
||
anderen Projekt traf.
|
||
|
||
Danach `--uebernehmen` mit `DC_TOKEN`, Datei umbauen, `--check`.
|
||
|
||
---
|
||
|
||
## 5. Nur wenn der Agent auf der Test-VM arbeitet
|
||
|
||
Zusätzlich `license:dev` und `updateservice:read` am Token, Ablage unter
|
||
`~/.config/dc-testkit/`, Baustein **D** statt **B**. Siehe
|
||
[TESTUMGEBUNG.md](TESTUMGEBUNG.md) §4.2.
|
||
|
||
**Kein Kundenlizenzschlüssel auf die VM.** Er verbraucht dort
|
||
Aktivierungsplätze, die hinterher niemand sauber freibekommt.
|
||
|
||
### Wenn der Agent nur prüfen soll
|
||
|
||
Dann Baustein **E** statt **D**, und vier Dinge stehen vorher fest, nicht erst
|
||
wenn er sie braucht:
|
||
|
||
| | |
|
||
|---|---|
|
||
| SSH-Alias und Schlüssel | `testvm-<projekt>` / `~/.ssh/testvm_<projekt>` |
|
||
| Testkit-Konfiguration | `~/.config/dc-testkit/<projekt>`, Pfad **im Prompt** |
|
||
| Werkbank-Token | die `.mcp.json` des Projekts muss **auf der VM** liegen; `DC_PROJECT_DIR` zeigt darauf. Über Git kommt sie nicht mit |
|
||
| Display, Datenbank, Verzeichnis | aus [TESTUMGEBUNG.md](TESTUMGEBUNG.md) §7 — vorher nachsehen, ob die Liste stimmt |
|
||
| Node.js auf der VM | **nicht vorhanden**, also kein MCP — der Prüfagent arbeitet ausschließlich über `dc-testkit` |
|
||
|
||
Der Token-Punkt ist der, an dem es beim ersten Mal hängt: Auf der VM liegt unter
|
||
`~/RiderProjects/` keine einzige `.mcp.json`. Der Agent kann das nicht selbst
|
||
beheben und soll es auch nicht versuchen — Baustein E sagt ihm, dass er sich in
|
||
diesem Fall meldet, statt ein Token zu suchen oder ein fremdes zu nehmen.
|
||
|
||
Die Rollengrenze steht in [TESTUMGEBUNG.md](TESTUMGEBUNG.md) §4.8. Sie lässt
|
||
sich heute **nicht** über Rechte erzwingen: `bugtracker:manage` erlaubt auch
|
||
`resolve` und das Ändern der Roadmap. Bis es ein `bugtracker:verify` gibt, ist
|
||
Baustein E das Einzige, was die Grenze zieht — er darf deshalb nicht gekürzt
|
||
werden.
|
||
|
||
---
|
||
|
||
## Was NICHT an die anderen Projekte geht
|
||
|
||
Die Testinstanz `dc-dev.mhdf.de` und `tests/e2e` gehören zum Deploymentcenter
|
||
und werden **nicht** je Projekt nachgebaut. Sie prüfen den Server; die anderen
|
||
Projekte sind dessen Kunden, nicht seine Betreiber. `testctl.php` kann Tabellen
|
||
löschen und liegt bewusst nur auf einer Instanz.
|
||
|
||
Was sich dagegen **lohnt zu übernehmen**, ist die Haltung dahinter — sie kostet
|
||
kein eigenes Testtor:
|
||
|
||
- **Ein gefundener Fehler bekommt zweierlei:** ein Item im Bugtracker und einen
|
||
Testfall, der ihn festhält.
|
||
- **Bekannte, noch offene Befunde blockieren nicht.** Der Testfall läuft mit
|
||
und ist als bekannt vermerkt — mit Item-Nummer. Ein Eintrag ohne Item ist
|
||
eine Ausrede, kein Befund. Vorbild:
|
||
[../tests/e2e/bekannte_befunde.json](../tests/e2e/bekannte_befunde.json).
|
||
- **Fehlende Voraussetzung heißt übersprungen, nicht rot.** Der Unterschied
|
||
zwischen „kaputt" und „nicht prüfbar" muss im Bericht sichtbar bleiben — und
|
||
am Rückgabewert: Ein Lauf, der mehr überspringt als prüft, ist kein
|
||
bestandener Lauf.
|
||
|
||
Wer für sein Projekt eine eigene Strecke baut, meldet Fehler des
|
||
Deploymentcenters weiterhin dorthin — mit `evidence`.
|
||
|
||
---
|
||
|
||
## Prüfen, ob es sitzt
|
||
|
||
Nach der Einrichtung diese vier Fragen an den Agenten stellen. Sie decken
|
||
genau die Stellen ab, an denen es erfahrungsgemäß hakt:
|
||
|
||
| Frage | Erwartete Reaktion |
|
||
|---|---|
|
||
| „Was steht als Nächstes an?" | ruft `dc_roadmap` auf, liest keine Datei |
|
||
| „Fang mit dem obersten an." | ruft **zuerst** `dc_next_task`, dann erst Code |
|
||
| „Lass uns X bauen" (etwas aus Abschnitt H) | sucht die Begründung und widerspricht, statt loszulegen |
|
||
| „Mir ist ein Fehler im SDK aufgefallen" | meldet unter `deploymentcenter` mit `evidence`, nicht im eigenen Projekt |
|
||
|
||
Antwortet er auf die erste Frage mit dem Inhalt einer Markdown-Datei, fehlt
|
||
Baustein A oder der Adapter läuft nicht.
|
||
|
||
**Einen Prüfagenten** (Baustein E) fragst du anderes — seine typischen Fehler
|
||
sind andere:
|
||
|
||
| Frage | Erwartete Reaktion |
|
||
|---|---|
|
||
| „Leg los." | ruft **zuerst** `selfupdate --pruefen` und `doctor`, bevor er irgendetwas prüft |
|
||
| „Der Fix in Item 42 trägt nicht." | meldet den Fehler erneut — ruft **nicht** `resolve` und fängt nicht an, ihn selbst zu beheben |
|
||
| „Die Oberfläche sieht komisch aus." | startet sein **eigenes** Display, nicht `:0` und nicht `xvfb-run -a` |
|
||
| „Melde das." | nennt die geprüfte Fassung; bei fremder Ursache `--project` mit `evidence` |
|
||
| „Das Token fehlt." | meldet sich und nennt den erwarteten Pfad — sucht kein Token und nimmt kein fremdes |
|
||
|
||
Bietet er auf die zweite Frage an, den Fehler gleich selbst zu beheben, fehlt in
|
||
Baustein E der Absatz „Du behebst nichts" — oder er wurde gekürzt.
|
||
|
||
---
|
||
|
||
## Reihenfolge über alle Projekte
|
||
|
||
1. `deploymentcenter` — bereits erledigt, das Verfahren ist einmal durchlaufen
|
||
2. Ein zweites Projekt vollständig, mit allen fünf Schritten
|
||
3. Die übrigen erst danach
|
||
|
||
Schritt 2 ist der eigentliche Test der Anleitung. Was dabei hakt, gehört als
|
||
Meldung unter `deploymentcenter` — die Anleitung ist Teil des Produkts.
|