Практикум по 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.
Пример
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).
Пример
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 и верните результат как вывод инструмента.
Пример
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.
Сначала модель вызывает инструмент 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.
Пример
# Сначала загрузите 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: Почему не рекомендуется превентивное разделение для простых плагинов инструментов?
Другие расширения