Конфигурация плагина DeepSeek Harness: Config и Schemastery

Инструмент greet жёстко задаёт приветствие в коде; в разных развёртываниях для его изменения потребуется менять код.

В этой главе плагин учится принимать конфигурацию, передаваемую из cordis.yml, что обеспечивает «разделение конфигурации и кода».


Экспортируйте тип Config и схему с тем же именем

В плагине экспортируйте интерфейс Config и схему Schemastery с тем же именем.

Значение по умолчанию записывается непосредственно в поле схемы.

Пример

// Путь к файлу: scratch-plugin/src/my-plugin.ts
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 во вновь вставленную строку локального плагина.

Пример

# Путь к файлу: scratch-plugin/cordis.yml
- 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 для выражения ограничений.

Пример

// Путь к файлу: scratch-plugin/src/validated-plugin.ts
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 фреймворк выгружает старый экземпляр и загружает новый.

Поскольку все регистрации являются эффектами и автоматически очищаются, регистрации старого экземпляра не сохранятся после замены.

配置校验与 HMR 流程


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

Экспортируйте интерфейс Config и одноимённую схему, записывайте значения по умолчанию в схему, проверяйте конфигурацию при загрузке; все настраиваемые параметры попадают в конфигурацию.

1. Почему значения по умолчанию пишут в схеме, а не в коде?

2. Что происходит, когда конфигурация недопустима?

3. Каков стандарт проверки «отсутствия хардкода»?

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