Сервисы и зависимости DeepSeek Harness: базовый класс Service и объявления типов
В предыдущих главах мы использовали встроенные сервисы, такие как ctx.tools, ctx.llm и ctx.agents.
В этой главе мы с точки зрения поставщика сервиса рассмотрим, как использоватьбазовый класс Service, чтобы предоставить собственный именованный сервис и дать потребителям полные подсказки типов.
Что такое сервис?
В Harness tools, llm и agents — это всё сервисы.
Сервисы — это именованные возможности, смонтированные на ctx; любой плагин может предоставлять сервисы для использования другими плагинами.
Сервисы: возможность, которую плагин предоставляет другим плагинам.
Он занимает стабильный ctx.<key> (например, ctx.tools, ctx.llm, ctx.sessions), а другие плагины ищут сервисы по ключу, а не импортируют конкретную реализацию.
Например, ctx.tools — это сервис выполнения инструментов, ctx.llm — сервис больших моделей, а ctx.agents — сервис агентов.
Имена сервисов, публичные методы и местоположения исходного кода встроенных сервисов автоматически генерируются репозиторием на страницу подсистемы каждого сервиса. При разработке плагинов полагайтесь на эти сгенерированные блоки и интерфейсы TypeScript сервисов и не зависьте от какого-либо написанного вручную статического манифеста сервисов.
Использование сервисов: объявления inject
Чтобы использовать существующий сервис, объявите inject в плагине.
Фреймворк гарантирует: когда выполняется apply, все сервисы, объявленные через inject, уже готовы.
Пример
// Объявить зависимость от сервиса tools
export const inject = ['tools']
export function apply(ctx: Context) {
// Гарантируется, что ctx.tools существует и готов
ctx.tools.register(/* ... */)
}
Если сервис ещё не готов, ваш плагин будет ждать и не выполнит apply.
Предоставление сервиса: базовый класс Service
Наследуйте подкласс от базового класса Service и вызовите в конструктореsuper(ctx, 'service name')Зарегистрируйте сервис с указанным именем.
Пример
import { Service, type Context } from '@deepseek-ai/cordis'
// Сервисы также могут зависеть от других сервисов, объявленных с помощью static inject
export default class MetricsService extends Service {
static inject = ['llm'] // Этот сервис требует, чтобы сервис llm был готов первым
constructor(ctx: Context) {
// Второй параметр 'metrics' — это имя сервиса, смонтированного в ctx.metrics.
super(ctx, 'metrics')
}
// Публичный метод сервиса
record(event: string, value: number) {
// Запишите метрику здесь, например количество вызовов инструмента
// Фактическая реализация записывает в бэкенд метрик; здесь опущена
}
}
После загрузки этого плагина потребители могут получить к нему доступ через ctx.metrics.
Пример
// Потребитель объявляет зависимость от сервиса метрик
export const inject = ['metrics']
export function apply(ctx: Context) {
// Вызовите метод сервиса: запишите вызов инструмента
ctx.metrics.record('example_tool_call', 1)
}
Объявления типов: declare module Merging
Используйте слияние объявлений TypeScript, чтобы задать ctx.metrics правильный тип.
Это даёт автодополнение при написании кода и позволяет отлавливать опечатки в именах сервисов во время компиляции.
Пример
import { Service, type Context } from '@deepseek-ai/cordis'
// Объединение объявлений: сообщите TypeScript, что Context имеет поле metrics
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) {
/* Реализация опущена */
}
}
Объединение объявлений declare module — стандартный способ TypeScript добавить типы к существующему модулю.
Здесь тип и реализация ctx.metrics записаны в одном файле, чтобы гарантировать, что они не разойдутся.
Обязательные зависимости и опциональные зависимости
Зависимости сервисов делятся на два типа: обязательные и необязательные.
Обязательные зависимости объявляются с помощью inject; если сервис отсутствует, плагин не загружается вообще.
Необязательные зависимости опускают inject; в месте использования используйтеctx.get()Запрос может вернуть undefined.
Пример
// Обязательная зависимость: плагин не загрузится, если сервис отсутствует
export const inject = ['tools']
// Необязательная зависимость: опустите inject, запрашивайте через ctx.get() в месте использования
export function apply(ctx: Context) {
// ctx.get('metrics') может вернуть undefined; используйте опциональную цепочку для безопасного вызова
const metrics = ctx.get('metrics')
metrics?.record('example_plugin_loaded', 1)
}
| Тип зависимости | Синтаксис | Поведение при отсутствии сервиса | Применимые сценарии |
|---|---|---|---|
| Обязательная зависимость | export const inject = ['tools'] | Плагин не загружается и остаётся в состоянии PENDING | Он не может нормально работать без этого сервиса |
| Необязательная зависимость | Не указывайте inject, используйте ctx.get('metrics') для запроса | Плагин загружается как обычно, ctx.get() возвращает undefined | Сервис необязателен; плагин должен нормально работать даже при его отсутствии. |
Когда использовать необязательные зависимости? Когда сервис необязателен и ваш плагин должен работать нормально даже при его отсутствии.
Поведение при исчезновении сервиса
Если обязательный сервис исчезает во время работы приложения (например, его поставщик удалён), произойдут две вещи:
- Плагины, зависящие от него, будут автоматически утилизированы (с освобождением ресурсов).
- Когда сервис появляется снова, плагин автоматически перезагружается.
Это предотвращает вызовы плагинами сервисов, которые больше не существуют.
Итоговая самопроверка
Подклассы сервисов предоставляют именованные сервисы через super(ctx, 'name'), слияние объявлений модуля declare заполняет типы, inject объявляет обязательные зависимости, а ctx.get() запрашивает необязательные зависимости.
Проверьте себя:
- В каком виде сервисы существуют на ctx? Какой параметр определяет имя сервиса?
- Как задать подсказки типов для ctx.metrics?
- В чём разница в коде между обязательными и необязательными зависимостями?