DeepSeek-Harness: Dienste und Abhängigkeiten: Basisklasse für Dienste und Typdeklarationen
In den vorherigen Kapiteln haben wir integrierte Dienste wie ctx.tools, ctx.llm und ctx.agents verwendet.
In diesem Kapitel betrachten wir aus Sicht des Dienstanbieters, wie Sie mithilfeder Service-Basisklasseeinen eigenen benannten Dienst bereitstellen und den Konsumenten vollständige Typhinweise geben.
Was ist ein Service?
In Harness sind tools, llm und agents alles Dienste.
Dienste sind benannte Fähigkeiten, die an ctx angebunden sind; jedes Plugin kann Dienste bereitstellen, die andere Plugins verwenden können.
Dienste: die Fähigkeit, die ein Plugin anderen Plugins bereitstellt.
Es belegt einen stabilen ctx.<key> (wie ctx.tools, ctx.llm, ctx.sessions), und andere Plugins suchen Dienste anhand des Schlüssels, anstatt eine bestimmte Implementierung zu importieren.
Zum Beispiel ist ctx.tools der Tool-Laufzeitdienst, ctx.llm der Dienst für das große Modell und ctx.agents der Agent-Dienst.
Die Dienstnamen, öffentlichen Methoden und Quellorte integrierter Dienste werden automatisch vom Repository in die Subsystemseite jedes Dienstes generiert. Verlassen Sie sich bei der Entwicklung von Plugins auf diese generierten Blöcke und die TypeScript-Schnittstellen der Dienste und nicht auf ein handgeschriebenes statisches Dienstmanifest.
Dienste verwenden: inject-Deklarationen
Um einen vorhandenen Dienst zu verwenden, deklarieren Sie inject im Plugin.
Das Framework garantiert: Wenn apply ausgeführt wird, sind alle durch inject deklarierten Dienste bereits bereit.
Beispiel
// Abhängigkeit vom tools-Dienst deklarieren
export const inject = ['tools']
export function apply(ctx: Context) {
// ctx.tools ist garantiert vorhanden und bereit
ctx.tools.register(/* ... */)
}
Wenn ein Dienst noch nicht bereit ist, wartet dein Plugin und führt apply nicht aus.
Einen Dienst bereitstellen: die Service-Basisklasse
Leite eine Unterklasse von der Service-Basisklasse ab und rufe im Konstruktorsuper(ctx, 'service name')Registriere den Namensdienst.
Beispiel
import { Service, type Context } from '@deepseek-ai/cordis'
// Dienste können auch von anderen Diensten abhängen, deklariert mit static inject
export default class MetricsService extends Service {
static inject = ['llm'] // Dieser Dienst erfordert, dass der llm-Dienst zuerst bereit ist
constructor(ctx: Context) {
// Der zweite Parameter 'metrics' ist der Dienstname, gemountet an ctx.metrics.
super(ctx, 'metrics')
}
// Öffentliche Service-Methode
record(event: string, value: number) {
// Hier eine Metrik erfassen, z. B. Anzahl der Tool-Aufrufe
// Die eigentliche Implementierung schreibt in das Metrik-Backend; hier ausgelassen
}
}
Nach dem Laden dieses Plugins können Konsumenten über ctx.metrics darauf zugreifen.
Beispiel
// Konsument deklariert Abhängigkeit vom Metrik-Service
export const inject = ['metrics']
export function apply(ctx: Context) {
// Service-Methode aufrufen: einen Tool-Aufruf aufzeichnen
ctx.metrics.record('example_tool_call', 1)
}
Typdeklarationen: declare module Merging
Verwende TypeScript-Deklarationszusammenführung, um ctx.metrics den korrekten Typ zu geben.
Dies ermöglicht Autovervollständigung beim Schreiben von Code und lässt Sie falsch geschriebene Service-Namen zur Kompilierzeit erkennen.
Beispiel
import { Service, type Context } from '@deepseek-ai/cordis'
// Declaration merging: Teile TypeScript mit, dass Context ein metrics-Feld hat
declare module '@deepseek-ai/cordis' {
interface Context {
metrics: MetricsService
}
}
export default class MetricsService extends Service {
constructor(ctx: Context) {
super(ctx, 'metrics')
}
record(event: string, value: number) {
/* Implementierung ausgelassen */
}
}
declare module declaration merging ist der Standardweg in TypeScript, um Typen zu einem vorhandenen Modul hinzuzufügen.
Hier werden Typ und Implementierung von ctx.metrics in derselben Datei geschrieben, um sicherzustellen, dass sie nicht auseinanderdriften.
Erforderliche Abhängigkeiten und optionale Abhängigkeiten
Service-Abhängigkeiten werden in zwei Typen unterteilt: erforderlich und optional.
Erforderliche Abhängigkeiten werden mit inject deklariert; wenn ein Dienst fehlt, wird das Plugin überhaupt nicht geladen.
Optionale Abhängigkeiten lassen inject weg; an der Verwendungsstelle verwenden Siectx.get()Die Abfrage kann undefined zurückgeben.
Beispiel
// Erforderliche Abhängigkeit: Das Plugin wird nicht geladen, wenn der Dienst fehlt
export const inject = ['tools']
// Optionale Abhängigkeit: inject weglassen, an der Verwendungsstelle mit ctx.get() abfragen
export function apply(ctx: Context) {
// ctx.get('metrics') kann undefined zurückgeben, verwende optional chaining, um sicher aufzurufen
const metrics = ctx.get('metrics')
metrics?.record('example_plugin_loaded', 1)
}
| Abhängigkeitstyp | Syntax | Verhalten, wenn ein Dienst fehlt | Anwendbare Szenarien |
|---|---|---|---|
| Erforderliche Abhängigkeit | export const inject = ['tools'] | Das Plugin wird nicht geladen und bleibt PENDING | Es kann ohne diesen Dienst nicht normal funktionieren |
| Optionale Abhängigkeit | inject weglassen, verwende ctx.get('metrics') zum Abfragen | Das Plugin wird wie gewohnt geladen, ctx.get() gibt undefined zurück | Der Dienst ist optional; das Plugin muss auch dann normal funktionieren, wenn er fehlt. |
Wann sollten optionale Abhängigkeiten verwendet werden? Wenn der Dienst optional ist und Ihr Plugin auch ohne ihn normal funktionieren muss.
Verhalten, wenn ein Dienst verschwindet
Wenn ein erforderlicher Dienst zur Laufzeit der Anwendung verschwindet (zum Beispiel, wenn sein Anbieter deinstalliert wird), passieren zwei Dinge:
- Plugins, die davon abhängen, werden automatisch verworfen (Ressourcen werden freigegeben).
- Wenn der Dienst wieder auftaucht, wird das Plugin automatisch neu geladen.
Dadurch wird verhindert, dass Plugins Dienste aufrufen, die nicht mehr existieren.
Zusammenfassung Selbsttest
Dienst-Unterklassen stellen benannte Dienste über super(ctx, 'name') bereit, declare module declaration merging füllt die Typen aus, inject deklariert erforderliche Abhängigkeiten und ctx.get() fragt optionale Abhängigkeiten ab.
Testen Sie sich selbst:
- In welcher Form existieren Dienste auf ctx? Welcher Parameter bestimmt den Dienstnamen?
- Wie gibt man ctx.metrics Typ-Hinweise?
- Worin unterscheidet sich der Code zwischen erforderlichen und optionalen Abhängigkeiten?