Запрос как добавить tool в DeepSeek Harness описывает одну из задач реализации: определить контракт, зарегистрировать его в плагине и проверить его поведение с помощью тестов. Это руководство посвящено стороннему проекту DeepSeek Harness. Это не документация от DeepSeek AI или OdiRouter и не устанавливает отношения интеграции, партнерства или официальной поддержки.
В официальном README DeepSeek Harness проект назван предварительной версией для разработчиков с открытым исходным кодом; также в нем предупреждается, что будут внесены изменения, нарушающие совместимость. Прежде чем использовать пример, ознакомьтесь с актуальной документацией, веткой и примечаниями к выпуску. Не переносите этот пример в производственную среду без проверки. Согласно данным о выпусках, изученным в рамках этого исследования, предварительный выпуск dsh-v0.1.0-rc.7 был опубликован 2026-08-17.
Начните с узкой ответственности
Инструмент должен выполнять одну небольшую задачу с четко определенными входными данными и структурированным результатом. Начните с операции, не имеющей побочных эффектов. Она не должна записывать файлы, выполнять команды оболочки, обращаться к сетевому сервису или изменять разрешения. Это упрощает тестирование первой версии и делает ее безопаснее для использования в рабочем процессе агента.
Перед написанием кода ответьте на следующие вопросы:
Какие входные данные принимает инструмент и какие значения недопустимы?
Какой результат должен получить вызывающий код при успешном выполнении операции?
Для каких действий требуется отдельный контроль разрешений вне реализации инструмента?
Какое поведение должен видеть вызывающий код при отмене, ошибке инфраструктуры или нарушении бизнес-правила?
Проверка по схеме и семантическая проверка решают разные задачи. В официальном справочнике указано, что defineTool проверяет аргументы, сгенерированные моделью, на соответствие объявленной схеме параметров до запуска execute. Схема не заменяет проверки на наличие пустой строки, положительного числа, допустимого диапазона или связи между полями. Разместите эти правила в обработчике или в соответствующем слое политик.
Определите минимальный контракт
В официальной документации представлен шаблон, ориентированный на плагины, с defineTool, ctx.tools.register, parameters, output и execute. Следующий пример является оригинальным. Эта функция нормализует строку только в памяти и возвращает каноническое значение в формате JSON.
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
export const name = 'safe-label-tool'
export const inject = ['tools']
export function apply(ctx: Context) {
ctx.tools.register(defineTool({
name: 'normalize_label',
description: 'Trim a label and collapse repeated spaces.',
parameters: {
label: {
type: 'string',
required: true,
description: 'A short label that stays in memory.',
},
},
output: {
schema: {
type: 'object',
properties: { value: { type: 'string' } },
required: ['value'],
},
render: (_args, value) => [{ type: 'text', text: value.value }],
},
async execute(args, exec) {
if (exec.signal.aborted) throw new Error('Cancelled before processing')
const value = args.label.trim().replace(/\s+/g, ' ')
if (!value) throw new Error('label must contain visible characters')
return { value }
},
}))
}description предназначен для модели, поэтому он должен указывать действие, границы и ожидаемый результат. parameters определяют проверенную структуру входных данных. output.schema превращает возвращаемое значение в контракт, а output.render отделяет представление для человека от программного результата. Сверяйте точные типы и допустимые поля с актуальной официальной документацией.
Регистрируйте через жизненный цикл плагина
В справочном документе регистрация описывается как основанная на эффекте: удаление плагина приводит к отмене регистрации инструмента. Это полезная граница для тестов и обновлений. Не изменяйте схему и не заменяйте обратные вызовы после регистрации объекта определения. Если инструмент необходимо изменить, отмените регистрацию, которой он принадлежит, и зарегистрируйте замену в соответствии с текущим API.
Дайте инструменту стабильное имя и ограничьте его область действия одним плагином. Не регистрируйте два обработчика с одной и той же ответственностью лишь потому, что один из них экспериментальный. Понятное имя, узкий контракт и контроль жизненного цикла упрощают диагностику сбоев.
Добавьте валидацию, разрешения и обработку ошибок
Проверьте последовательно три уровня:
Схема: обязательные поля и базовые типы.
Семантическая валидация: непустые строки, числовые границы, связи между полями и разрешённые состояния.
Авторизация: разрешение на действие до начала побочного эффекта.
Третий уровень в примере не требуется, поскольку операция не имеет побочных эффектов. Не следует расширять его прямым вызовом при добавлении операций с файлами, оболочкой, сетью или учетными данными. Сначала создайте явный список разрешённых вариантов, определите проверку разрешений, ограничьте область действия, установите тайм-аут и проверьте журнал аудита. Официальная документация рекомендует использовать перехватчики политик для решений «разрешить», «запретить» и «запросить», а также точки наблюдения вокруг выполнения.
Для аннулирования используйте код exec.signal. Передайте сигнал API, которые его поддерживают, и прекратите выполнение незавершенной работы после прерывания. Не следует прятать функцию отмены за неограниченным циклом повторных попыток. Сбой инфраструктуры должен приводить к исключению. Успешный результат в предметной области может подразумевать неидеальное состояние в объявленном каноническом значении, если это допускает схема.
Протестируйте инструмент до добавления опасных возможностей
Сначала напишите модульные тесты для контракта, затем интеграционный тест для регистрации и вызова. Минимальный набор тестов включает:
Корректная метка возвращает нормализованное значение.
Пустая метка или метка, состоящая только из пробелов, не проходит семантическую валидацию.
Неожиданное поле, неверный тип и отсутствие обязательного поля не достигают бизнес-логики, если схема их отклоняет.
Сигнал отмены останавливает длительную операцию, поддерживающую отмену.
Жизненный цикл плагина отменяет регистрацию инструмента, а повторная регистрация не оставляет старый обработчик активным.
Операция с побочными эффектами без проверки разрешений отклоняется до выполнения.
Для более масштабных изменений следуйте текущей политике тестирования репозитория и документации по тестированию на уровне пакета. Поскольку DeepSeek Harness находится в предварительной версии для разработчиков, повторяйте эти проверки после обновления зависимостей или нового релиза.
Отдельный следующий шаг с OdiRouter
OdiRouter не является частью DeepSeek Harness в этом руководстве. Если после безопасного локального теста вам нужно оценить отдельный рабочий процесс API для моделей, начните с OdiRouter. Эта ссылка не подтверждает совместимость или поддержку DeepSeek Harness, доступность конкретной модели, цены или готовность к промышленной эксплуатации.