Практикум по DeepSeek Harness: пишем заменяемую возможность

В предыдущей главе было представлено понятие трёх ролей; в этой мы превратим его в код, следуя официальному руководству.

Мы собираемся реализовать возможность под названием myCap: она принимает фрагмент текста на вход и выводит всё в верхнем регистре. Она достаточно мала, чтобы её можно было понять с первого взгляда, но при этом полностью охватывает три пакета: Definition, Provider и Consumer.

Три шага: Service Definition (абстрактный класс + тип) → Service Provider (конкретный подкласс) → Consumer (defineTool).

Наконец, загрузите Provider и Consumer вместе в cordis.yml.


Шаг 1: Напишите Service Definition

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

В нём нет логики реализации, только один абстрактный метод и два интерфейса.

Абстрактный класс MyCapService наследуется от Service и черезsuper(ctx, 'myCap')регистрируется как именованный сервис.

Объединение объявлений declare module даёт ctx.myCap его типы; эта техника рассматривалась в части 14.

Пример

// Путь к файлу: packages/my-cap/my-cap/src/index.ts
import { Service, type Context } from '@deepseek-ai/cordis'

// Объединение объявлений: сделать так, чтобы ctx.myCap имел подсказки типов в TypeScript
declare module '@deepseek-ai/cordis' {
  interface Context {
    myCap: MyCapService
  }
}

// Абстрактный класс: пакет Definition только объявляет контракты, а не реализации.
export abstract class MyCapService extends Service {
  constructor(ctx: Context) {
    super(ctx, 'myCap') // Зарегистрировать как именованный сервис ctx.myCap
  }

  /** Выполнить возможность. */
  abstract execute(request: MyCapRequest): Promise<MyCapResult>
}

// Тип запроса: вызывающий должен предоставить входные данные
export interface MyCapRequest {
  input: string
}

// Тип результата: возможность возвращает выходные данные
export interface MyCapResult {
  output: string
}

abstract execute — единственный абстрактный метод, и Provider должен его реализовать.

MyCapRequest имеет поле input, а MyCapResult — поле output.

Типы request и result принадлежат пакету Definition, и как Provider, так и Consumer импортируют их из него.


Шаг 2: Напишите Service Provider

Service Provider наследует абстрактный класс и реализует реальное поведение.

MyCapLocal преобразует input в верхний регистр и возвращает его.

export const name объявляет имя плагина; в apply зарегистрируйте реализацию сервиса через ctx.plugin(MyCapLocal).

Пример

// Путь к файлу: packages/my-cap/my-cap-local/src/index.ts
import type { Context } from '@deepseek-ai/cordis'
import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/dsh-my-cap'

// Класс реализации: зависит только от пакета Definition
class MyCapLocal extends MyCapService {
  async execute(request: MyCapRequest): Promise<MyCapResult> {
    // Поведение локального провайдера.
    return { output: request.input.toUpperCase() }
  }
}

export const name = 'my-cap-local'

export function apply(ctx: Context) {
  // Загрузить класс реализации как плагин, зарегистрировать его как фактическую службу для ctx.myCap
  ctx.plugin(MyCapLocal)
}

Провайдер зависит только от абстрактных классов и типов в пакете Definition.

Ему неважно, как модель его вызывает и как выглядит инструмент.

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


Шаг 3: Напишите сторону Consumer

Consumer оборачивает возможность в инструмент, который модель может вызвать.

Объявление inject зависит от tools и myCap, гарантируя, что apply запускается только после того, как оба сервиса готовы.

defineTool объявляет схему инструмента; как только модель увидит инструмент my_cap, она передаст параметры в соответствии с parameters.

В execute вызовите ctx.myCap.execute и верните результат как вывод инструмента.

Пример

// Путь к файлу: packages/my-cap/tool-my-cap/src/index.ts
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'tool-my-cap'
// Объявление зависимости: tools предоставляет точку регистрации, myCap предоставляет реализацию сервиса.
export const inject = ['tools', 'myCap']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'my_cap', // Имя инструмента для модели
    description: 'Выполнить мою возможность.',
    // Схема параметров: модель генерирует параметры в соответствии с ней
    parameters: {
      input: { type: 'string', required: true },
    },
    // Схема вывода и метод рендеринга
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    // Фактическое выполнение: вызов сервиса возможностей
    async execute(args) {
      const result = await ctx.myCap.execute({ input: args.input })
      return result.output
    },
  }))
}

Модель не знает ctx.myCap напрямую; она знает только инструмент my_cap.

Consumer — это мост между ними и также отвечает за рендеринг результата в текст, видимый модели.


Структура из трёх ролей myCap и поток данных

Когда три пакета собраны вместе, данные идут от модели через Consumer и Definition и попадают в Provider.

myCap 三角色结构与数据流图

Сначала модель вызывает инструмент my_cap; этот шаг происходит только на уровне Consumer.

Consumer передаёт параметры, упакованные в MyCapRequest, в ctx.myCap.execute(request).

Definition делегирует вызов текущей загруженной реализации Provider.

После того как Provider вычисляет результат, он возвращает MyCapResult в Consumer по исходному пути.

Consumer рендерит вывод в текст и передаёт его модели как результат инструмента.

На протяжении всей цепочки, когда Provider заменяется, ни Consumer, ни модель этого не замечают.


Объединение в cordis.yml

Три пакета — это лишь части, когда они написаны; вам также нужно загрузить Provider и Consumer вместе в cordis.yml.

Загрузка Provider даёт ctx.myCap реализацию; загрузка Consumer даёт модели инструмент my_cap.

Пример

# Путь к файлу: cordis.yml
# Сначала загрузите Provider, чтобы у ctx.myCap была реализация.
- name
: '@deepseek-ai/dsh-my-cap-local'

Перезагрузите Consumer, чтобы модель могла использовать инструмент my_cap
- name
: '@deepseek-ai/dsh-tool-my-cap'

Что касается порядка загрузки, Cordis автоматически сортирует по зависимостям, так что неважно, Provider или Consumer идёт первым.

Чтобы переключиться на другого Provider, измените только первую строку; Consumer остаётся без изменений.


Моменты проектирования

Официальная документация предлагает три принципа проектирования; лучше держать их в уме перед написанием capability.

Во-первых, не разделяйте преждевременно.

Помещайте роли в отдельные пакеты только тогда, когда им нужно развиваться независимо.

Простые плагины инструментов не нужно разбивать; вполне допустимо, чтобы один пакет брал на себя несколько ролей.

Во-вторых, определение сервиса содержит типы Request/Result.

Provider и Consumer зависят только от пакета Definition, поэтому типы Request и Result должны быть определены в Definition.

В-третьих, явное лучше неявного.

Реализации должны обрабатывать значения по умолчанию через явный шаг resolve(request), а не скрывать ?? default внутри run().

Bash-шов — пример: workdir и timeoutMs в ShellExecRequest необязательны; слой инструмента сначала вызывает ctx.shell.resolve(request), чтобы получить ShellExecSpec со всеми обязательными полями, затем передаёт его в run().

Не заполняйте молча значения по умолчанию внутри run(); сначала resolve, затем выполнение — только тогда границы ясны.


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

Одним предложением: написание заменяемой возможности = абстрактный класс Definition + подкласс Provider + инструмент Consumer, плюс cordis.yml.

Вопрос для самопроверки 1: В каком пакете должны быть определены MyCapRequest и MyCapResult?

Самопроверка 2: Есть ли зависимость между Provider и Consumer?

Самотестирование 3: Почему не рекомендуется превентивное разделение для простых плагинов инструментов?

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