DeepSeek Harness Объявленные зависимости: inject и встроенные сервисы

Ранее мы познакомились с плагинами, которые работают независимо, но большинство плагинов полагается на другие возможности: реестр инструментов, LLM, Agent.

В этом разделе мы расскажем, как объявлять зависимости и как фреймворк гарантирует, что зависимости готовы до выполнения apply.


Что такое сервис?

Сервис — это именованная возможность, которую плагин предоставляет другим плагинам.

В Harness среди них tools, llm, agents — всё это сервисы, они загружаются в ctx: ctx.tools, ctx.llm, ctx.agents.

Встроенный сервисЧто этоТипичное использование
ctx.toolsСреда выполнения инструментовРегистрация / вызов инструментов
ctx.llmСервис большой языковой модели (LLM)Регистрация адаптеров, инициирование запросов к модели
ctx.agentsСервис агентаУправление субагентами

Объявление зависимостей с помощью inject

Если вашему плагину нужен сервис, укажите его в массиве inject.

Фреймворк гарантирует, что ваш плагин загружается только после того, как эти сервисы готовы.

Пример

// Путь к файлу: scratch-plugin/src/my-tool-plugin.ts
import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-tool-plugin'
// Объявите зависимость: требуется сервис tools
export const inject = ['tools']

export function apply(ctx: Context) {
  // К моменту, когда мы доходим сюда, ctx.tools гарантированно готов.
  ctx.tools.register(/* ... */)
}

Когда apply выполняется, все сервисы, объявленные в inject, уже готовы.

Это гарантируется фреймворком, поэтому вам не нужно ничего ждать в вашем коде.


Зависимость не готова: плагин ждёт

Если сервис не готов, плагин не выполнится.

Его Fiber останется в состоянии PENDING, ожидая появления сервиса.

В жизненном цикле PENDING означает "объявлен, но обязательные зависимости не готовы."

依赖就绪后再加载插件

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


Обязательные зависимости и опциональные зависимости

inject объявляет обязательные зависимости: плагин не загружается, когда сервис отсутствует.

Если сервис опционален, используйте опциональную зависимость: не включайте его в inject и запрашивайте его через ctx.get() в точке использования.

Пример

// Опциональная зависимость: не указывайте inject, используйте ctx.get() для запроса
import type { Context } from '@deepseek-ai/cordis'

export function apply(ctx: Context) {
  // Сервис metrics может присутствовать или отсутствовать
  const metrics = ctx.get('metrics')
  // Опциональная цепочка: пропустить, если он не существует, без ошибки
  metrics?.record('plugin_loaded', 1)
}

Что происходит, когда сервис исчезает

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

Во-первых, плагины, которые зависят от него, автоматически выполнят dispose (освободят ресурсы).

Во-вторых, когда сервис появляется снова, плагин автоматически перезагружается.

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

Совет: это правило работает с автоматической очисткой — выгрузка запускает disposer, описанный в части 8.


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

Используйте inject, чтобы объявить обязательные сервисы, и фреймворк гарантирует, что apply выполняется только после того, как сервисы готовы; запрашивайте необязательные сервисы с помощью ctx.get().

1. Что объявляет массив inject?

2. В каком состоянии находится плагин, когда сервисы не готовы?

3. Как следует объявлять необязательные зависимости?

Другие расширения