Разработка адаптеров провайдеров

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

ThreadCells Провайдер Adapter API V1 — граница расширения доверенного кода, отличная от observer plugins. Устанавливайте адаптеры как проверенные Python-пакеты, которые регистрируют объекты ProviderAdapterDefinition в группе entry point threadcells.provider_adapters.v1. После установки перезапустите локальный candidate/runtime, чтобы entry point были обнаружены заново.

Контракт

Определение адаптера предоставляет:

• AdapterManifest со стабильными adapter_id, API плагина 1.0, версией реализации, описанием, возможностями и схемой конфигурации JSON;
• модель Pydantic AdapterSettings для декларативных настроек;
• фабрику, принимающую ProviderLaunchContext и проверенные настройки;
• функцию предварительной проверки, возвращающую нормализованные состояние, установку, аутентификацию, версию, совместимость, модели, код причины и сообщение без секретов.

Возвращаемый провайдер реализует нормализованные семантики запуска/возобновления/отмены, статуса/результата терминала, использования и состояния через существующий жизненный цикл BaseProvider. Честно объявляйте неподдерживаемые и условные возможности. Никогда не синтезируйте использование, которое CLI не сообщил.

Доверие и конфигурация

Пакеты адаптеров исполняемы и поэтому устанавливаются только доверенным оператором хоста. JSON реестра не может выбирать бинарные файлы или внедрять команды. ThreadCells рекурсивно отклоняет ключи executable, command, shell, argument, flag, environment, credential, password, token и secret. Необработанные секреты никогда не принадлежат settings; используйте семантические непрозрачные secret_refs и разрешайте их только внутри доверенного кода адаптера согласно политике секретов установки.

Сохраняйте нормализованные ошибки со стабильными кодами причин и безопасными для публикации сообщениями. Предварительная проверка не должна изменять настройки провайдера или аутентифицировать от имени оператора.

Пример

Установленный source/candidate содержит examples/provider-adapters/threadcells-echo — детерминированный пакет и manifest, демонстрирующие entry point, схему, проверку конфигурации, жизненный цикл, предварительную проверку и неподдерживаемое использование. Это не провайдер модели и по умолчанию отключён. Соберите и протестируйте его независимо до установки.

Поставляемые схемы schemas/v1/adapter-manifest.schema.json и schemas/v1/capabilities.schema.json — ссылки на переносимые артефакты. Проверка Python-контракта остаётся источником истины для установленного кода.

Готовность должна оставаться правдивой

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

API реестра, Settings и Spawn Agent проецируют один и тот же результат. Добавьте покрытие, доказывающее, что неустановленная команда отключена, ошибка аутентификации отличается от отсутствия, а установленный провайдер с действительно непознаваемой аутентификацией остаётся помеченным как непроверенный.

Использование должно оставаться правдивым

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

Контрольный список проверки

• Стабильные ID адаптера, версия, отображаемое имя и схема конфигурации.
• Отсутствие полей для бинарного файла, оболочки, аргумента, окружения или необработанного секрета, выбранных вызывающим кодом.
• Ограниченная предварительная проверка без изменения настроек или аутентификации.
• Честные поддерживаемые/условные/неподдерживаемые возможности.
• Тесты жизненного цикла для запуска, статуса, отмены и восстанавливаемого сбоя.
• Точные тесты использования при поддержке телеметрии.
• Тесты согласованности реестра/Settings/Spawn.
• Безопасные для публикации ошибки без учётных данных или приватных путей.