Änderungen vornehmen
Wie du ein Werkzeug hinzufügst, eine Seite änderst, einen Prompt hinzufügst und eine Änderung innerhalb des öffentlichen Vertrags hältst. Die Seite ist für Mitwirkende, die das Repository eingerichtet haben (Mitwirken); wie du eine Änderung testest, steht unter Testen.
Bevor du anfängst
Lies zuerst Architektur: Dort stehen die Schichten (Werkzeuge → Domäne → sevDesk-Client), die Modulübersicht und der Lebenszyklus eines Werkzeugaufrufs. Werkzeuge rufen HTTP nie direkt auf.
Handgeschriebene zod-Schemas sind die maßgebliche Quelle für sevDesk-Payloads, weil die offizielle OpenAPI-Spezifikation unvollständig und stellenweise falsch ist. Jede bekannte Abweichung steht in spec/deviations.md und hat einen Test.
Ein Werkzeug hinzufügen
- Wähle die Werkzeuggruppe (
src/tools/<toolset>/) und die Stufe:read,write(umkehrbar),commit(rechtlich bindend oder nicht umkehrbar) oderexternal(erreicht Dritte). Im Zweifel nimm die höhere Stufe. - Definiere es mit
defineTool: Name, Titel, Beschreibung (nenne deutsche Begriffe wie Rechnung, Beleg), zod-Schemas für Ein- und Ausgabe und alle vier Annotationen (readOnlyHint,destructiveHint,idempotentHint,openWorldHint). Sonst schlägt der Metadaten-Lint-Test fehl. - Implementiere den Handler über die Domänenschicht. Gib kompakte DTOs zurück, nie rohe
sevDesk-Payloads. Ein Werkzeug der Stufe
commitoderexternalschreibt seine Vorschau für die Bestätigung auf Englisch und auf Deutsch, weil ein Mensch sie auf der Freigabeseite liest: Baue beide mitbothPreviewsaus denselben Daten (src/domain/preview-text.ts; ohne die deutsche kompiliert das Werkzeug nicht). Halte dieselben Fakten und Warnungen in derselben Reihenfolge und verwende sevDesks eigene deutsche Begriffe (Rechnung, Beleg, festschreiben). - Ergänze Fixtures und Tests: Normalfall, Fehlerfälle und die Sperre nach Stufe. Aktualisiere den
Snapshot von
tools/list(pnpm test -u) und prüfe den Diff. Für ein Werkzeug mit deutscher Vorschau ergänze einen Fall intest/write-cases/und lies dessen deutschen Text im Snapshot vontest/integration/write-previews-de.test.ts. - Erzeuge die Werkzeugreferenz mit
pnpm docs:toolsneu und committedocs/tools.md(ein Test schlägt fehl, wenn sie veraltet ist).
Neue Werkzeuge erscheinen von selbst im Manifest der Claude-Desktop-Erweiterung; der Build erzeugt ihre Werkzeugliste.
Eine Seite ändern
Die Seiten, die ein Mensch sieht (Freigabe, Postfach, Anmeldung, Zustimmung, Upload), teilen sich
src/pages/: Das Template-Tag markup maskiert jeden Wert, die Texte liegen in
src/pages/text/en.ts und de.ts, und ein einziges Stylesheet (theme.ts) gestaltet sie alle. Es
gibt kein Skript, kein style=""-Attribut und nichts, was von außerhalb von /assets/ geladen
wird; ein Test rendert jede Seite in jedem Zustand und beiden Sprachen und schlägt bei jedem
dieser Punkte fehl.
pnpm pages:preview # http://127.0.0.1:4173: jeder Seitenzustand, en/de, hell/dunkel, echte Headerpnpm pages:assets # nach einer Änderung an einer Datei in assets/: die eingebettete Kopie neu erzeugenTrage einen neuen Zustand in test/helpers/page-gallery.ts ein, damit die Vorschau und die Tests
ihn abdecken. Die Seite /texts der Vorschau zeigt jeden Text in beiden Sprachen nebeneinander.
Einen Prompt hinzufügen
Prompts sind Buchhaltungsabläufe, die der Benutzer im Client auswählt. Sie erzeugen nur Text und rufen sevDesk nie auf.
- Trage den Prompt mit
definePromptinsrc/prompts/catalog.tsein: einnamein snake_case ohne Präfixsevdesk_(Clients ordnen Prompts je Server in einen eigenen Namensraum), Titel, Beschreibung, die Werkzeuge, die er zum Erscheinen voraussetzt (requires), und seine Schritte. Halte ihn im Einklang mit dem passenden Ablauf inplugin/skills/sevdesk-bookkeeping/references/workflows.md. - Jeder Schritt führt in
toolsjedes Werkzeug auf, das sein Text nennt (in Backticks); der Schritt erscheint nur, wenn alle registriert sind. Gib einenfallbackan (was übersprungen wird, ohne ein Werkzeug zu nennen), wenn der Benutzer erfahren soll, dass eine Einstellung den Schritt freischalten würde; welche, ergänzt der Renderer. - Argumente sind optionale Strings mit einer Muster- oder Längenprüfung. Zeige ein rohes Argument
nur über
fenceInline, nie im vertrauenswürdigen Text. - Führe
test/unit/prompts/undtest/integration/prompts-list.test.tsaus: Der Lint rendert jeden Prompt in vielen Konfigurationen und schlägt fehl, wenn ein Schritt ein Werkzeug nennt, das diese Konfiguration nicht registriert. Aktualisiere den Snapshot vonprompts/list(pnpm test test/integration/prompts-list.test.ts -u) und prüfe den Diff, danachpnpm docs:tools.
Kompatibilität
Ab 1.0 ist die öffentliche Oberfläche ein Vertrag (Werkzeugnamen, Argumente, Ausgaben, Werkzeuggruppen, Stufen, Prompts, Variablen, Befehle, Routen, Ressourcen, Felder des Audit-Logs, die Einstellungsschlüssel der Erweiterung); die vollständige Liste und die Regeln für Abkündigungen stehen auf der Seite Kompatibilität. So bleibst du darin:
- Frei hinzufügen: neue Werkzeuge, optionale Argumente, Ausgabefelder, Variablen.
- Zum Umbenennen oder Entfernen folge den Regeln für Abkündigungen und führe die Abkündigung im PR auf.
- Ein PR, der den Vertrag trotzdem bricht, markiert seinen Titel mit
!(feat(invoices)!: …) und erklärt den Bruch in seiner Beschreibung. - Beschreibungen, Ergebnistexte, Fehlermeldungen und Logs gehören nicht zum Vertrag; verbessere sie frei, aber nimm die Evals neu auf, wenn du änderst, was Modelle lesen (Evals zur Werkzeugauswahl).
Bericht „Tool surface“
Der PR-Workflow Tool surface vergleicht den Basis-Commit des Ereignisses mit dem PR, gemergt in
diese Basis (GitHubs Test-Merge-Commit); ein Branch, der hinter main liegt, zeigt also nur seine
eigenen Änderungen. Ein angehefteter Kommentar beginnt mit Tokens im Modellkontext und
Tokens der Antworten, Basis → Head mit vorzeichenbehaftetem Δ:
- Der Modellkontext ist die Sicht eines Claude-Clients aus der Zeit von 2025:
name,descriptionundinput_schemader Werkzeuge und die Server-Anweisungen als System-Prompt, wie intest/evals/tools.ts. Achte darauf, wenn du Werkzeuge hinzufügst oder Beschreibungen und Eingabeschemas wachsen lässt. Gemessen wird in vier Konfigurationen: read, write, alle Werkzeuggruppen und Stufen (einschließlich advanced) und alles über HTTP mit OAuth und Dateiübertragung. - Die Kosten der Antworten misst der Bericht, indem er ein Invoice-Get, eine Rechnungsübersicht
nach Monat und Kontakt-, Kontoumsatz-, Beleg- und Rechnungslisten mit Standardlimit durch den
echten Server auf aufgezeichneten Fixtures schickt.
transactions_list,vouchers_listundinvoices_listlaufen zusätzlich mitdetail: "summary";invoices_listläuft außerdem mit beiden Detailstufen beilimit: 100. Jede aufgezeichnete Liste wird deterministisch auf 100 Einträge erweitert, indem ihre bereinigten Zeilenformen mit eigenen IDs wiederholt werden (die ursprüngliche Gesamtzahl von sevDesk wird verworfen); Aufrufe mit Standardlimit liefern derzeit 25 Zeilen. Tests prüfen diese Anzahlen, vergleichen volle und zusammengefasste Antworten (jede Zeile der Zusammenfassung direkt nach ihrem vollen Gegenstück) und prüfen, dass eine Senkung des Standards auf 10 die gemessenen Kosten ändert. Beide Revisionen verwenden denselben erzeugten Bestand; gemessen werden also Änderungen an Seitengröße und Formatierung, keine repräsentative Stichprobe echter Dokumente. Die Uhr steht fest auf 2026-11-13, damit Überfälligkeitsmarken nicht wandern. Ein fehlendes oder fehlschlagendes Werkzeug oder eine solche Fixture-Route lässt nur diese Antwort bein/a; selbst ein Fehler beim Aufbau des Bestands behält die Werkzeuge, Prompts, Anweisungen und den Kompatibilitäts-Diff. - Das vollständige moderne
tools/list, einschließlich der Ausgabeschemas, ist zweitrangig und mit not in model context for Claude clients beschriftet; es wird in Unicode-Zeichen angegeben, nicht in Modell-Tokens. Der Kompatibilitäts-Diff deckt weiterhin vollständige Werkzeuge, Prompts und Anweisungen ab. Prüfe Namen und Schemas selbst: Der Bericht entscheidet nicht, welche Versionsanhebung nötig ist.
Lokale und PR-Zählungen sind als estimated beschriftet: Unicode-Zeichen ÷ 2,3, auf ganze
Tokens gerundet (das Verhältnis wurde in
#61 gemessen). Der vertrauenswürdige
Publisher kann den vollständigen Vergleich auf exact-Zählungen mit messages.countTokens für
claude-opus-5-5 hochstufen, über Workload Identity Federation (WIF). Zählungen des Modellkontexts
ziehen die ganze Kalibrierungsnachricht ab; Zählungen der Antworten ziehen nur deren Rahmen ab und
behalten die Nutzlast (der Kalibrierungstext x ist ein Token). Der Modellkontext zählt die
Werkzeugform der Messages API plus Systemtext; Antworten enthalten die tatsächlichen Textblöcke im
alten Format, Zusammenfassungen und Code-Zäune. Nachrichtenhüllen des Clients, gerenderte
Prompt-Texte und das verzögerte Laden von Werkzeugen liegen außerhalb dieses Vergleichs. Fehlende
Erfassungen in älteren Dumps zeigen n/a, auch beim Delta, statt null; der Publisher schließt
unbekannte Antwort-IDs aus, damit unterschiedliche Vokabulare von Harness und Publisher den Bericht
nicht brechen. Die CI kopiert das aktuelle Harness in die Basis; eine Basis, die
detail: "summary" schon unterstützt, erfasst diese Aufrufe also auch; ältere Werkzeuge, die
detail ablehnen, lassen sie bei n/a.
Lokal erfassen, vergleichen oder neu zählen, ohne Zugangsdaten und ohne Netzwerk:
node --import tsx scripts/tool-surface.ts dump /tmp/head-surface.jsonnode --import tsx scripts/tool-surface.ts diff /tmp/base-surface.json /tmp/head-surface.jsonnode --import tsx scripts/tool-surface.ts report /tmp/base-surface.json /tmp/head-surface.json /tmp/pr-event.json /tmp/report.jsonnode scripts/tool-surface-tokens.ts /tmp/base-surface.json /tmp/head-surface.json /tmp/report.jsonDer Bericht nimmt ein JSON-Ereignis eines GitHub-PRs (number, pull_request.base.sha,
pull_request.head.sha). Dumps der Version 1 tragen optional modelContext je Konfiguration und
responses; Berichte ergänzen tokenCost mit der Methode, dem festen Modell und Zählungen für
Basis und Head, die null sein dürfen, und behalten contextCost (Zeichenzahlen des Protokolls)
für ältere Verbraucher. Die Serialisierung des Modellkontexts erhält die Schlüsselreihenfolge des
Clients bei Werkzeugen und Schemas; nur der Protokollkatalog wird kanonisiert.
Der Workflow ist per Pfadfilter auf relevanten Code, Fixtures und Workflows beschränkt und
überspringt Dependabot. Er führt PR-Code ohne Secrets und ohne Identitätsberechtigungen aus, auch
bei Forks: Die CI kopiert scripts/tool-surface*.ts und den aufgezeichneten Bestand in den
Checkout der Basis, beide Revisionen installieren ihre eigenen eingefrorenen Abhängigkeiten, und
das Artefakt tool-surface-report enthält report.json, base.json und head.json für sieben
Tage (lange Kommentare verlinken dorthin und sagen, wenn sie gekürzt sind).
Nur der workflow_run-Job Tool surface comment des Standard-Branches kann Zugangsdaten
bekommen (die Umgebung token-count, id-token: write auf Job-Ebene, Rechte zum Lesen von
Artefakten und zum Kommentieren von PRs). Er checkt keinen Code aus, installiert nichts und führt
keinen Inhalt eines Artefakts aus. Er prüft die Herkunft und die aktuellen Commits des PRs, lehnt
Behauptungen exakter Zählungen im Artefakt ab, validiert die Formen von Werkzeugen, System und
Antworten, begrenzt den Bericht auf 300 KB, jede Erfassung auf 20 MB und jeden gezählten Kontext
und jede gezählte Antwort auf 2 Millionen Zeichen, und liest Dateien über ein einziges offenes
Handle, ohne symbolischen Links zu folgen; Beschriftungen kommen nur vom Publisher. Nur die
validierten Werkzeugdefinitionen, System-Strings und Antworttexte gehen an den Zähl-Endpunkt. Sein
Inline-Skript tauscht ein frisches GitHub-OIDC-Token für https://api.anthropic.com (maskiert,
im Speicher, keine Token-Datei) bei /v1/oauth/token gegen ein kurzlebiges Bearer-Token und ruft
dann /v1/messages/count_tokens mit demselben Zähler und derselben Kalibrierung für Basis und
Head auf: natives fetch, feste Origins, keine Weiterleitungen, höchstens 90 Sekunden, und keine
Zugangsdaten und kein Fehler des Anbieters werden je geloggt oder hochgeladen.
Fehlende Repository-Variablen oder ein Fehler beim Tausch oder Zählen veröffentlichen den gesamten geschätzten Vergleich. Exakte Zählungen ersetzen Schätzungen erst, wenn jede verfügbare Erfassung gelungen ist; eine späte Schätzung ersetzt nie einen exakten Kommentar für dieselbe Basis und denselben Head. Veraltete Berichte werden übersprungen, und Diff-Text steht in Code-Zäunen. Weder ein echtes sevDesk-Konto noch ein Cache für Abhängigkeiten wird verwendet. Änderungen am Publisher laufen erst, wenn sie auf dem Standard-Branch gelandet sind; prüfe bis dahin die Artefakte des PRs.
Maintainer-Einrichtung für exakte Zählungen
Ein API-Schlüssel als Secret ist nicht nötig. Das Zählen von Tokens ist kostenlos und ratenbegrenzt. Folge der WIF-Einrichtung von Anthropic für GitHub Actions:
- Vor dem Merge legst du die GitHub-Umgebung
token-countan, beschränkst die Deployment-Branches aufmainund setzt keine Pflicht-Reviewer. Lass nicht den ersten Lauf eine unbeschränkte Umgebung automatisch anlegen. - In der Claude Console → Workload identity → Connect workload → GitHub Actions setzt du:
- Issuer:
https://token.actions.githubusercontent.com, mit Discovery. - Exaktes Subject:
repo:jaylann@61842101/mcp-server-sevdesk@1449574146:environment:token-count, ohne*am Ende. - Audience:
https://api.anthropic.com. - Exakte Claims:
repository_owner: jaylann,repository_owner_id: 61842101,repository: jaylann/mcp-server-sevdesk,repository_id: 1449574146,event_name: workflow_runundworkflow_ref: jaylann/mcp-server-sevdesk/.github/workflows/tool-surface-comment.yml@refs/heads/main. Nimmworkflow_reffür diesen Workflow der obersten Ebene, nicht den Claimjob_workflow_reffür wiederverwendbare Workflows. - Ziel: ein neues Service-Konto, dem nur der eigene Workspace ausdrücklich hinzugefügt ist, mit dem niedrigsten verfügbaren Ausgabelimit. Binde die Regel und das getauschte Token nur an diesen Workspace; wegen Anthropics impliziter Mitgliedschaft im Default Workspace ist eine Mitgliedschaft allein keine Isolation.
- Scope: der engste angebotene (Standard des Assistenten
workspace:developer); Laufzeit 600 Sekunden.
- Issuer:
- Setze diese vier Repository-Variablen mit den IDs aus der Console:
ANTHROPIC_FEDERATION_RULE_ID,ANTHROPIC_ORGANIZATION_ID,ANTHROPIC_SERVICE_ACCOUNT_ID,ANTHROPIC_WORKSPACE_ID. - Nach dem Merge und dem ersten relevanten PR-Lauf prüfst du in der
Authentifizierungshistorie der Console das tatsächliche Subject, die Audience und alle
obigen Claim-Strings. Prüfe einen
gelungenen Tausch und einen Exact-Kommentar; ein Estimated-Kommentar belegt nur den
Rückfall. Prüfe unabhängig davon, dass
xfürclaude-opus-5-5ein Token Nutzlast ist, wiebaseline - 1annimmt.
Dieses Repository verwendet GitHubs
unveränderliche Subject-Claims.
Bis die Federation eingerichtet ist, bleiben der echte Tausch, der Abgleich der Claims und die
Annahme der Ein-Token-Kalibrierung ungeprüft; der erste eingerichtete Lauf von main prüft sie.