Сервисы и зависимости 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, уже готовы.

Пример

// Путь к файлу: scratch-plugin/src/use-tools.ts
// Объявить зависимость от сервиса tools
export const inject = ['tools']

export function apply(ctx: Context) {
  // Гарантируется, что ctx.tools существует и готов
  ctx.tools.register(/* ... */)
}

Если сервис ещё не готов, ваш плагин будет ждать и не выполнит apply.


Предоставление сервиса: базовый класс Service

Наследуйте подкласс от базового класса Service и вызовите в конструктореsuper(ctx, 'service name')Зарегистрируйте сервис с указанным именем.

Пример

// Путь к файлу: scratch-plugin/src/metrics-service.ts
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.

Пример

// Путь к файлу: scratch-plugin/src/use-metrics.ts
// Потребитель объявляет зависимость от сервиса метрик
export const inject = ['metrics']

export function apply(ctx: Context) {
  // Вызовите метод сервиса: запишите вызов инструмента
  ctx.metrics.record('example_tool_call', 1)
}

Объявления типов: declare module Merging

Используйте слияние объявлений TypeScript, чтобы задать ctx.metrics правильный тип.

Это даёт автодополнение при написании кода и позволяет отлавливать опечатки в именах сервисов во время компиляции.

Пример

// Путь к файлу: scratch-plugin/src/metrics-service.ts
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.

Пример

// Путь к файлу: scratch-plugin/src/optional-dep.ts
// Обязательная зависимость: плагин не загрузится, если сервис отсутствует
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Сервис необязателен; плагин должен нормально работать даже при его отсутствии.

Когда использовать необязательные зависимости? Когда сервис необязателен и ваш плагин должен работать нормально даже при его отсутствии.


Поведение при исчезновении сервиса

Если обязательный сервис исчезает во время работы приложения (например, его поставщик удалён), произойдут две вещи:

  1. Плагины, зависящие от него, будут автоматически утилизированы (с освобождением ресурсов).
  2. Когда сервис появляется снова, плагин автоматически перезагружается.

Это предотвращает вызовы плагинами сервисов, которые больше не существуют.


Итоговая самопроверка

Подклассы сервисов предоставляют именованные сервисы через super(ctx, 'name'), слияние объявлений модуля declare заполняет типы, inject объявляет обязательные зависимости, а ctx.get() запрашивает необязательные зависимости.

Проверьте себя:

  1. В каком виде сервисы существуют на ctx? Какой параметр определяет имя сервиса?
  2. Как задать подсказки типов для ctx.metrics?
  3. В чём разница в коде между обязательными и необязательными зависимостями?
Другие расширения