PerryLink/dsh-plugin-guide

DeepSeek Harness Plugin-Entwicklung (dsh-plugin-guide)

Entwickeln Sie DeepSeek Harness-Plugins basierend auf offiziellen Unterlagen. Dieser Skill ist eine Arbeitsablauf- und Einschränkungsliste; Fakten beziehen sich stets auf den Originaltext der Wissensdatenbank und werden nicht aus dem Gedächtnis erfunden. Alle „muss/darf nicht“-Klauseln stammen aus den offiziellen Repositorys AGENTS.md, docs/ und der Dokumentationsseite; bei Konflikten gilt der offizielle Originaltext.

Speicherort der Wissensdatenbank (in dieser Reihenfolge suchen, den ersten vorhandenen verwenden)

Dieser Skill und die Wissensdatenbank werden im selben Verzeichnis ausgeliefert (das Verzeichnis, in dem sich diese SKILL.md befindet, ist das Wissensdatenbank-Root); alle Pfade sind relative Pfade. Wenn diese Datei separat kopiert wird, ohne dass guide/, references/ vorhanden sind, wird auf die Fallback-Pfade zurückgegriffen:

1. Gleiches Verzeichnis wie diese Datei: ./guide/ (umfassender Leitfaden + Schnellübersicht + Dokumentationslink-Index), ./references/ (Rechercheberichte und vollständige Kopien der offiziellen Dokumentation references/official-docs/docs/), ./downloads/ (Original-Downloads, optional)
2. Lokale Hauptkopie: D:\deepseek-harness\Project\Plugins\dsh-plugin-guide\ (Beispielpfad, je nach tatsächlichem Installationsort anpassen)
3. Offizielles Repository Checkout: D:\deepseek-harness\ (docs/, vendor/cordis/, packages/, examples/)
4. Online: https://github.com/deepseek-ai/deepseek-harness , https://deepseek-harness.github.io/deepseek-harness/develop/basic/ , https://github.com/cordiverse/cordis

Nachfolgende relative Pfade beziehen sich standardmäßig auf obigen Punkt 1 (das Verzeichnis, in dem sich diese Skill-Datei befindet).

Voraussetzungen für die Entwicklung (erster Schritt, zwingend erforderlich)

1. Wenn Sie Cordis-Konzepte noch nicht gelesen haben: Lesen Sie references/official-docs/docs/cordis-primer.md (5 Konzepte, 5 Minuten); zum praktischen Mitmachen führen Sie die Tutorials 01-07 in references/official-docs/docs/cordis-tutorial/ aus (kein API-Key erforderlich).
2. Öffnen Sie guide/quick-reference.md (Vertrags-Schnellübersicht) + guide/plugin-dev-guide.md (vollständiger Pfad). Die Zuordnung offizieller/Community-Dokumentations-URLs finden Sie in guide/links.md.
3. Bestätigen Sie die Zielerweiterungspunkte: Lesen Sie die Tabelle „Where new behavior goes“ in references/official-docs/docs/architecture.md und die Tabelle feature→mechanism in references/official-docs/docs/cookbook/extension-cookbook.md – Neues Verhalten MUSS an dokumentierte Erweiterungspunkte angehängt werden, der Agent-Loop DARF NICHT geändert werden.

Zwingend einzuhaltende Plugin-Verträge (offizielle rote Linien, Punkt für Punkt prüfen)

• Plugin = Modul exportiert name + apply(ctx, config) (+ optional inject: string[]); abhängige Dienste sind vor apply bereit; verschwindet ein abhängiger Dienst, wird automatisch deinstalliert und nach Wiederherstellung automatisch neu geladen.
• Registrierung ist Effekt: Jeder Beitrag erfolgt über ctx.effect() / ctx.on() / Dienst register() (gibt disposer zurück); NIEMALS manuell per removeListener/clearInterval aufräumen.
• Waterfall-Listener MÜSSEN next() aufrufen; unterlassen = absichtlicher Kurzschluss (Interceptions-Semantik). Die Semantik von emit/waterfall/parallel/serial/bail finden Sie in der Schnellübersicht.
• Modellsichtbar ⟺ Protokolliert: Alles, was in eine Modellanfrage eingeht, muss aus dem Sitzungsprotokoll rekonstruierbar sein; neue modelleingänge müssen neue SessionEventMap-Sitzungsereignisse hinzufügen.
• Typsichere Ereignisse/Dienste mittels Declaration Merging (declare module '@deepseek-ai/cordis'); Ereignisdokumentation mit @mode versehen.
• Konfiguration mittels Schemastery Schema<Config> (keine einfachen Objekte erlaubt); fehlerhafte Konfiguration führt zu lautem Fehler beim Laden; Keine hartcodierten justierbaren Parameter (Test: Kann es in cordis.yml geändert werden?).
• Tools mittels defineTool: execute gibt nur die im output.schema deklarierten, standardkonformen JSON-Werte zurück; exec.signal beachten; menschenlesbare Inhalte in output.render platzieren; UI-Karten-Präsentator ist reine Funktion (keine I/O/Uhren/Zufall).
• Austauschbare Fähigkeiten gemäß Dreischicht-Nahtdesign: Service Definition / Provider / Consumer; nicht vorzeitig auftrennen.
• Bundling: Bundle-Manifest "dsh":{"bundle":{"patch":"..."}}; Überschreibung per id vollständige zeilenweise Konfigurationsersetzung; !!js (Doppelausrufezeichen); Git-Installation erfordert prepare-Skript und benutzerseitige allowBuilds, Veröffentlichung als npm/tarball benötigt keine Build-Genehmigung.

Entwicklungsweg nach Aufgabentyp

(Diese Pfade befinden sich alle unter references/official-docs/ und sind vollständige Kopien der offiziellen Dokumentation)

• Neues Tool: docs/user/develop/basic/tool.md (Tutorial) → docs/cookbook/adding-a-tool.md (Vollständiger Vertrag: Parametervalidierung, Standardwerte, Hintergrund-Jobs ctx.jobs, Policy-Hooks, Code-Mode, UI-Karten) → Referenzimplementierung packages/shell/tool-bash (lokales Checkout).
• Neuer Dienst/Fähigkeit: docs/user/develop/framework/service.md + docs/user/develop/practice/ (Vollständiger Code für Dreischicht-Aufteilung).
• Interception/Policy/Hook: docs/cookbook/extension-cookbook.md (permission-gate-Beispiel) + docs/event-producer-consumer.md (Vollständige Ereignismatrix).
• Neuer LLM-Provider: docs/user/develop/practice/llm-adapter.md (StreamChunk-Protokoll).
• UI/Sitzungsknoten: docs/cookbook/adding-a-conversation-node.md + docs/subsystems/session.md, client-modules.md.
• Bundling/Veröffentlichung: docs/user/develop/basic/publish.md (bundle/profile, Layer-Reihenfolge, Git-Installationsfallen).
• Dienst-/Ereignisgenaue Signaturen suchen: docs/subsystems/*.md (generativer Cordis-API-Bereich) + docs/cordis-api/*; KEINE zweite statische Liste selbst erstellen. Zuordnung Website-URL ↔ lokale Kopie in guide/links.md, vollständige Liste der Community-Links in references/community-ecosystem.md.
• Referenz-Community-Implementierungen & getestete Fallstricke: references/community-ecosystem.md, references/community-repo-deep-dive.md (Tiefenanalyse von 15 Entwicklungs-Repositories), downloads/community-repos/ (vollständige Quellcode-Kopien, müssen zuerst mit scripts/download-community-repos.ps1 generiert werden). Bereits bestätigte Mechanismusänderungen in der Community (z.B. Entfernung von repository-plugin 0811, Bundle vs. reiner Cordis-Dualkanal) und 20 getestete Fallstricke (Cordis-Doppelkopie/tsconfig-Dreierpack/Multi-Frame-zstd/Windows-Junction etc.) finden Sie in guide/plugin-dev-guide.md §7.

Validierung (vor Auslieferung)

• Ladevalidierung: dsh --profile <name> --dump-config prüfen, ob die Patch-Zeile wirksam ist; Start-Log ohne FAILED.
• Verhaltensvalidierung: Web-UI oder dsh --profile headless "…" praktisch testen; Tool-Rückgabe/menschenlesbarer Text entspricht dem Verhalten, Änderungen müssen erneut getestet werden.
• Zusätzliche Schritte bei Repository-internen Änderungen: Typprüfung, Tests des Zielpakets, schlüsselloser Snapshot (modell-/produktsichtbares Verhalten muss nach der Montage einen transkribierten Snapshot haben), zweisprachige Dokumentation als Paar, Agent-Notiz (bei nicht-trivialen Änderungen im selben PR).
• Unabhängiges Plugin-Paket: Nach pnpm pack in einem sauberen Profil testweise installieren und validieren (einschließlich lib/ Build-Artefakt).

Wartung der Wissensdatenbank (bei Bedarf)

• Offizielle Dokumentation synchronisieren: pwsh -File ./scripts/sync-official-docs.ps1 [-Checkout <deepseek-harness checkout>] – synchronisiert nur von Git verfolgte Dateien (unverfolgte Entwürfe und nicht gepushte Commits werden nicht importiert) und aktualisiert references/official-docs/SNAPSHOT.md; das Datum der „letzten Überprüfung“ und die Commit-Nummer in der README verweisen auf SNAPSHOT.md, nicht manuell ändern. Driftprüfung: pwsh -File ./scripts/verify-kit.ps1 -Checkout <checkout>.
• Online-Quellen aktualisieren: pwsh -File ./scripts/download-sources.ps1; Community-Repositories aktualisieren: pwsh -File ./scripts/download-community-repos.ps1 (beide Skripte sind idempotent, Ausgabe in ./downloads/). Themenliste-Zählung erneut prüfen: pwsh -File ./scripts/gen-topic-snapshot.ps1 -OutDir <dir> -MaxPages 20 (GitHub Search API q=topic:dsh-plugin; Paginierungsobergrenze 1000 Einträge, deduplizierte Anzahl und API total_count müssen in sources.md §D.2 protokolliert werden).
• Agent-Skill-Kopie installieren/aktualisieren: pwsh -File ./scripts/install-skill.ps1 -Target <skill-Verzeichnis> (überspringt downloads/ und .github/, byteweise Prüfung).
• Konfliktentscheidung: Bei Konflikten mit der offiziellen Dokumentation hat references/official-docs/ (Originaltext des offiziellen Repositorys) Vorrang.

Grenzen

• Dieser Skill ist eine „Anleitung + Einschränkungen + Quellenindex“, keine mechanische Ausführung von Skripten/Listen; exakte APIs richten sich nach der generativen Referenz.
• Es dürfen keine Dateien außerhalb des Wissensdatenbestands im Harness-Repository geändert werden, es sei denn, der Benutzer fordert dies ausdrücklich; vendor/ und .agents/notes/archived/ sind schreibgeschützt.
• Vor dem Verweis auf Inhalte in downloads/ sicherstellen, dass diese vorhanden sind (dieses Verzeichnis ist nicht in Git, muss mit dem obigen Skript generiert werden); das Archiv von awesome-dsh-plugins dient nur zur lokalen Referenz und DARF NICHT mit dem Repository weiterverteilt werden (die upstream-Erklärung enthält Nutzungsbeschränkungen, siehe NOTICE.md).