Конфигурация плагина DeepSeek Harness: Config и Schemastery
Инструмент greet жёстко задаёт приветствие в коде; в разных развёртываниях для его изменения потребуется менять код.
В этой главе плагин учится принимать конфигурацию, передаваемую из cordis.yml, что обеспечивает «разделение конфигурации и кода».
Экспортируйте тип Config и схему с тем же именем
В плагине экспортируйте интерфейс Config и схему Schemastery с тем же именем.
Значение по умолчанию записывается непосредственно в поле схемы.
Пример
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'
export const name = 'my-plugin'
// Интерфейс Config: определяет, какие параметры конфигурации принимает плагин
export interface Config {
greeting: string // Приветствие
maxRetries: number // Максимальное количество повторных попыток
verbose?: boolean // Выводить ли подробные логи (необязательно)
}
// Схема Config с тем же именем: значения по умолчанию записываются здесь
export const Config: Schema<Config> = Schema.объект({
greeting: Schema.string().default('Hello'),
maxRetries: Schema.number().default(3),
verbose: Schema.boolean().default(false),
})
// Второй аргумент apply — это валидированная конфигурация
export function apply(ctx: Context, config: Config) {
// Выводит значение, переданное пользователем, или значение по умолчанию из схемы
console.log(config.greeting)
}
Интерфейс предоставляет типы TypeScript, а схема обеспечивает проверку во время выполнения и значения по умолчанию.
У обоих одинаковое имя — это соглашение Cordis.
Не экспортируйте обычный объект как Config.
Он не соответствует интерфейсу Standard Schema, требуемому Cordis.
Передайте конфигурацию в cordis.yml.
Добавьте поле config во вновь вставленную строку локального плагина.
Пример
- insert:
- id: hello
# Путь к плагину должен быть абсолютным (см. часть 7)
name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
config:
greeting: 'Hi there, example!'
maxRetries: 5
Когда плагин загружается, Cordis проверяет конфигурацию через экспортированную схему и заполняет значения по умолчанию для полей, которые не были предоставлены.
В приведённой выше конфигурации verbose не указан; он примет значение по умолчанию из схемы — false.
Валидация схемы
Когда требуется более строгая валидация, используйте Schemastery для выражения ограничений.
Пример
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'
export const name = 'validated-plugin'
export interface Config {
apiKey: string // Обязательно
timeout: number // Таймаут в миллисекундах
mode: 'fast' | 'accurate' // Может принимать только одно из этих двух значений
}
export const Config = Schema.object({
apiKey: Schema.string().required(),
timeout: Schema.number().default(30000),
mode: Schema.union(['fast', 'accurate']).default('fast'),
})
export function apply(ctx: Context, config: Config) {
// config прошёл валидацию и типобезопасен
}
Schema выполняет проверку при загрузке плагина.
Если конфигурация недействительна, плагин не сможет загрузиться и выдаст понятное сообщение об ошибке.
Принцип проектирования: никаких жестко закодированных настраиваемых параметров.
Соглашение Harness таково: любой параметр, который может принимать разные значения в разных развертываниях, должен быть определён как поле конфигурации.
Неправильное и правильное использование
const TIMEOUT = 30000
// Правильно: определить как поле конфигурации; значение по умолчанию всё ещё предоставляется схемой.
export interface Config {
timeoutMs: number // По умолчанию 30000
}
Критерий проверки в одном предложении: можете ли вы изменить это значение в cordis.yml без изменения кода?
Если да, это допустимый настраиваемый параметр; если нет, его следует вынести в поле конфигурации.
Жесткое кодированиеЭто жесткое кодирование значений, которые должны были быть настраиваемыми в коде.
Это превращает «изменение конфигурации» в «изменение кода и повторное развёртывание» — частый источник инцидентов в продакшене.
Ошибки конфигурации должны быть громкими
Выражайте самодостаточные ограничения в схеме, чтобы недопустимые конфигурации вызывали ошибку при загрузке плагина.
Ссылки на сервисы или зарегистрированные ресурсы требуют внедрения зависимостей; учебник по сервисам познакомит с этим соглашением.
Работа с HMR: горячая замена конфигурации.
Изменения конфигурации запускают горячую замену модулей (HMR) для плагина.
После изменения конфигурации плагина в cordis.yml фреймворк выгружает старый экземпляр и загружает новый.
Поскольку все регистрации являются эффектами и автоматически очищаются, регистрации старого экземпляра не сохранятся после замены.
Итог и самопроверка
Экспортируйте интерфейс Config и одноимённую схему, записывайте значения по умолчанию в схему, проверяйте конфигурацию при загрузке; все настраиваемые параметры попадают в конфигурацию.
Другие расширения1. Почему значения по умолчанию пишут в схеме, а не в коде?
2. Что происходит, когда конфигурация недопустима?
3. Каков стандарт проверки «отсутствия хардкода»?